peon-mem 1.0.0

package/scripts/eval-retrieval.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Retrieval evaluation harness for Peon.
+//
+// Builds a labeled query→gold-belief set (LLM-generated, realistic), then scores
+// the LIVE retrieval ranker with standard IR metrics (Recall@K, MRR, nDCG@10).
+// The eval set is SAVED so the identical queries re-score before/after a ranker
+// change — a fair A/B.
+//
+//   node scripts/eval-retrieval.mjs build "<projectPath>" [N]   # generate + save the set
+//   node scripts/eval-retrieval.mjs run   "<projectPath>"       # score current ranker on saved set
+//   node scripts/eval-retrieval.mjs       "<projectPath>" [N]   # build-if-missing then run
+//
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { PeonMemoryStore } from "../dist/memory-store.js";
+import { loadPeonConfig } from "../dist/config.js";
+
+const [, , maybeMode, ...rest] = process.argv;
+const MODES = new Set(["build", "run"]);
+const mode = MODES.has(maybeMode) ? maybeMode : "auto";
+const projectPath = (MODES.has(maybeMode) ? rest[0] : maybeMode) ?? process.cwd();
+const N = Number.parseInt((MODES.has(maybeMode) ? rest[1] : rest[0]) ?? "40", 10);
+
+const setPath = join(projectPath, ".peon", "evaluation", "retrieval-eval.json");
+const config = loadPeonConfig();
+
+async function genQuery(belief) {
+  const sys =
+    "Write ONE natural, specific question a user would ask whose answer is exactly the given memory belief. " +
+    "Include a distinctive detail from it so the question is unambiguous, but phrase it as a real user would " +
+    "(do NOT quote the belief verbatim). Output ONLY the question.";
+  const r = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${config.openRouterApiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ model: config.processingModel, temperature: 0.3, messages: [
+      { role: "system", content: sys },
+      { role: "user", content: belief.content }
+    ] })
+  });
+  const j = await r.json();
+  return (j.choices?.[0]?.message?.content ?? "").trim().replace(/^["']|["']$/g, "");
+}
+
+async function build() {
+  const store = await PeonMemoryStore.open({ projectPath });
+  const all = (await store.listMemoryRecords()).filter((r) => r.status === "active");
+  // Sample spread across types, prefer substantial content.
+  const pool = all.filter((r) => r.content.length > 30);
+  const step = Math.max(1, Math.floor(pool.length / N));
+  const sample = pool.filter((_, i) => i % step === 0).slice(0, N);
+  const items = [];
+  for (const belief of sample) {
+    const query = await genQuery(belief).catch(() => "");
+    if (query) items.push({ query, goldId: belief.id, goldContent: belief.content.slice(0, 100) });
+  }
+  mkdirSync(join(projectPath, ".peon", "evaluation"), { recursive: true });
+  writeFileSync(setPath, JSON.stringify({ projectPath, builtFrom: all.length, items }, null, 2));
+  console.log(`built ${items.length} labeled queries → ${setPath}`);
+  return items;
+}
+
+async function run(items) {
+  const store = await PeonMemoryStore.open({ projectPath });
+  const K = [1, 3, 5, 10];
+  const recallAt = Object.fromEntries(K.map((k) => [k, 0]));
+  let mrr = 0, ndcg = 0, found = 0;
+  for (const it of items) {
+    const ranked = await store.rankRecords(it.query, { limit: 20 });
+    const rank = ranked.findIndex((r) => r.record.id === it.goldId) + 1; // 1-based, 0 = not found
+    if (rank > 0) {
+      found++;
+      mrr += 1 / rank;
+      if (rank <= 10) ndcg += 1 / Math.log2(rank + 1);
+      for (const k of K) if (rank <= k) recallAt[k] += 1;
+    }
+  }
+  const n = items.length;
+  const pct = (x) => (100 * x / n).toFixed(1) + "%";
+  console.log(`\n  Retrieval eval — ${n} queries (gold belief per query), current ranker:`);
+  for (const k of K) console.log(`    Recall@${k}: ${pct(recallAt[k])}`);
+  console.log(`    MRR (top-20): ${(mrr / n).toFixed(3)}`);
+  console.log(`    nDCG@10:      ${(ndcg / n).toFixed(3)}`);
+  console.log(`    found in top-20: ${pct(found)}`);
+  return { recallAt, mrr: mrr / n, ndcg: ndcg / n, found: found / n, n };
+}
+
+let items;
+if (mode === "run") {
+  if (!existsSync(setPath)) { console.error("no eval set; run 'build' first"); process.exit(1); }
+  items = JSON.parse(readFileSync(setPath, "utf8")).items;
+} else if (mode === "build") {
+  items = await build();
+} else {
+  items = existsSync(setPath) ? JSON.parse(readFileSync(setPath, "utf8")).items : await build();
+}
+if (mode !== "build") await run(items);

package/scripts/evaluate-peon.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { access, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const packageDir = resolve(scriptDir, "..");
+const projectPath = resolve(process.argv[2] || process.cwd());
+const expectedPath = readOption("--expected");
+const memoryDirName = readOption("--memory-dir") || ".peon";
+const evaluationModulePath = resolve(packageDir, "dist", "evaluation.js");
+
+if (!(await exists(evaluationModulePath))) {
+  console.error(
+    JSON.stringify(
+      {
+        error: "Peon evaluation module is not built.",
+        expectedModule: evaluationModulePath,
+        buildCommand: "npm --workspace @peon/mcp run build"
+      },
+      null,
+      2
+    )
+  );
+  process.exitCode = 1;
+} else {
+  const { evaluatePeonProject } = await import(pathToFileURL(evaluationModulePath).href);
+  const expectedMemories = expectedPath ? JSON.parse(await readFile(resolve(expectedPath), "utf8")) : undefined;
+  const report = await evaluatePeonProject({
+    projectPath,
+    memoryDirName,
+    expectedMemories
+  });
+  console.log(JSON.stringify(report, null, 2));
+}
+
+function readOption(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+async function exists(path) {
+  return access(path).then(
+    () => true,
+    () => false
+  );
+}

package/scripts/install-peon-stl.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Install (or re-sync) the Peon STL daily cycle as a launchd job.
+ *
+ * It copies peon-stl.mjs into Peon's support dir (so the job is independent of any
+ * git checkout / worktree), writes ~/Library/LaunchAgents/com.peon.stl.daily.plist
+ * (generated from $HOME — the OpenRouter key is NEVER written into the plist), and
+ * bootstraps the job into the gui/$UID domain to run daily at 09:00.
+ *
+ *   node scripts/install-peon-stl.mjs            # install / re-sync
+ *   node scripts/install-peon-stl.mjs --run-now  # also run one cycle immediately
+ *   node scripts/install-peon-stl.mjs --uninstall # remove the job
+ */
+import { copyFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const HOME = homedir();
+const UID = userInfo().uid;
+const LABEL = "com.peon.stl.daily";
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const SUPPORT_SCRIPTS = join(HOME, "Library", "Application Support", "Peon", "scripts");
+const INSTALLED_SCRIPT = join(SUPPORT_SCRIPTS, "peon-stl.mjs");
+const STL_LOG_DIR = join(HOME, "Library", "Logs", "Peon", "stl");
+const PLIST_PATH = join(HOME, "Library", "LaunchAgents", `${LABEL}.plist`);
+const WORKING_DIR = join(HOME, "Documents", "Project_x 2"); // dir that holds Peon's .env
+
+const sh = (cmd, args) => { try { return execFileSync(cmd, args, { stdio: "pipe" }).toString(); } catch (e) { return e.stdout?.toString() || e.message; } };
+
+function bootout() { sh("launchctl", ["bootout", `gui/${UID}/${LABEL}`]); }
+
+if (process.argv.includes("--uninstall")) {
+  bootout();
+  console.log(`[install-peon-stl] booted out ${LABEL}. Plist left at ${PLIST_PATH} (delete it to fully remove).`);
+  process.exit(0);
+}
+
+// 1. copy the script to the branch-independent support dir
+mkdirSync(SUPPORT_SCRIPTS, { recursive: true });
+mkdirSync(STL_LOG_DIR, { recursive: true });
+copyFileSync(join(HERE, "peon-stl.mjs"), INSTALLED_SCRIPT);
+
+// 2. generate the plist
+const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/opt/homebrew/bin/node</string>
+    <string>${INSTALLED_SCRIPT}</string>
+  </array>
+  <key>WorkingDirectory</key><string>${WORKING_DIR}</string>
+  <key>StartCalendarInterval</key>
+  <dict><key>Hour</key><integer>9</integer><key>Minute</key><integer>0</integer></dict>
+  <key>StandardOutPath</key><string>${join(STL_LOG_DIR, "cron.out.log")}</string>
+  <key>StandardErrorPath</key><string>${join(STL_LOG_DIR, "cron.err.log")}</string>
+  <key>ProcessType</key><string>Background</string>
+  <key>LowPriorityIO</key><true/>
+</dict>
+</plist>
+`;
+writeFileSync(PLIST_PATH, plist);
+
+// 3. (re)bootstrap into the gui/$UID domain
+bootout();
+console.log(sh("launchctl", ["bootstrap", `gui/${UID}`, PLIST_PATH]).trim() || "[install-peon-stl] bootstrapped");
+sh("launchctl", ["enable", `gui/${UID}/${LABEL}`]);
+
+console.log(`[install-peon-stl] installed ${LABEL}`);
+console.log(`  script : ${INSTALLED_SCRIPT}`);
+console.log(`  plist  : ${PLIST_PATH}`);
+console.log(`  runs   : daily 09:00 · reports → ${STL_LOG_DIR}/`);
+
+if (process.argv.includes("--run-now")) {
+  console.log("[install-peon-stl] kicking off one cycle now…");
+  console.log(sh("launchctl", ["kickstart", "-k", `gui/${UID}/${LABEL}`]).trim() || "kickstarted");
+}

package/scripts/install-peon.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+import { access } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const defaultPackageDir = resolve(scriptDir, "..");
+const defaultRepoDir = resolve(defaultPackageDir, "..");
+const defaultDaemonUrl = "http://127.0.0.1:3737";
+const nonDestructiveNote =
+  "This helper does not write config files, install hooks, start services, or modify the project.";
+
+if (isMain(import.meta.url, process.argv[1])) {
+  await main(process.argv.slice(2), {
+    cwd: process.cwd(),
+    env: process.env,
+    packageDir: defaultPackageDir,
+    repoDir: defaultRepoDir
+  });
+}
+
+export async function main(argv, options = {}) {
+  let parsed;
+  try {
+    parsed = parseInstallArgs(argv, options.cwd || process.cwd());
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error("Usage: node scripts/install-peon.mjs [--json] [--check|--write-plan] [project-path]");
+    process.exitCode = 2;
+    return;
+  }
+
+  if (parsed.help) {
+    console.log(formatHelp());
+    return;
+  }
+
+  const daemonUrl = normalizeUrl(options.env?.PEON_DAEMON_URL || defaultDaemonUrl);
+  const packageDir = resolve(options.packageDir || defaultPackageDir);
+  const repoDir = resolve(options.repoDir || defaultRepoDir);
+  const checks = await collectChecks(parsed.projectPath, packageDir);
+  const plan = buildInstallPlan({
+    projectPath: parsed.projectPath,
+    packageDir,
+    repoDir,
+    daemonUrl,
+    checks
+  });
+  plan.mode = parsed.action;
+
+  if (parsed.output === "json") {
+    console.log(JSON.stringify(plan, null, 2));
+  } else if (parsed.action === "write-plan") {
+    console.log(formatWritePlan(plan));
+  } else {
+    console.log(formatTextReport(plan));
+  }
+
+  if (parsed.action === "check" && !plan.checks.ready) {
+    process.exitCode = 1;
+  }
+}
+
+export function parseInstallArgs(argv, cwd = process.cwd()) {
+  const result = {
+    action: "dry-run",
+    output: "text",
+    projectPath: undefined,
+    help: false
+  };
+
+  for (const arg of argv) {
+    if (arg === "--json") {
+      result.output = "json";
+    } else if (arg === "--check") {
+      result.action = setAction(result.action, "check");
+    } else if (arg === "--write-plan") {
+      result.action = setAction(result.action, "write-plan");
+    } else if (arg === "--help" || arg === "-h") {
+      result.help = true;
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else if (!result.projectPath) {
+      result.projectPath = resolve(cwd, arg);
+    } else {
+      throw new Error(`Unexpected extra project path: ${arg}`);
+    }
+  }
+
+  result.projectPath = resolve(result.projectPath || cwd);
+  return result;
+}
+
+export function buildInstallPlan({ projectPath, packageDir, repoDir, daemonUrl, checks }) {
+  const memoryDir = join(projectPath, ".peon");
+  const claudeHook = join(packageDir, "scripts", "claude-peon-hook.mjs");
+  const daemonBin = join(packageDir, "dist", "daemon-cli.js");
+  const mcpBin = join(packageDir, "dist", "index.js");
+  const launchctlLabel = "com.peon.daemon";
+  const launchAgentPlist = join("~", "Library", "LaunchAgents", `${launchctlLabel}.plist`);
+  const runDaemon = `PEON_DAEMON_URL=${daemonUrl} node ${shellQuote(daemonBin)}`;
+  const runMcpServer = `PEON_DAEMON_URL=${daemonUrl} node ${shellQuote(mcpBin)}`;
+  const hookCommand = `PEON_DAEMON_URL=${daemonUrl} node ${shellQuote(claudeHook)}`;
+  const ready = Boolean(checks.packageDir && checks.builtDaemon && checks.builtMcpServer && checks.claudeHook);
+
+  return {
+    mode: "dry-run",
+    nonDestructive: true,
+    projectPath,
+    packageDir,
+    repoDir,
+    daemonUrl,
+    paths: {
+      memoryDir,
+      daemonBin,
+      mcpBin,
+      claudeHook
+    },
+    checks: {
+      ...checks,
+      ready
+    },
+    launchctl: {
+      label: launchctlLabel,
+      plistPath: launchAgentPlist,
+      recommendation:
+        "Use this label for a user LaunchAgent if you choose to install the daemon with launchctl."
+    },
+    claude: {
+      mcpConfigSnippet: {
+        mcpServers: {
+          peon: {
+            command: "node",
+            args: [mcpBin],
+            env: {
+              PEON_DAEMON_URL: daemonUrl
+            }
+          }
+        }
+      },
+      hookCommandSnippet: hookCommand
+    },
+    commands: {
+      build: "npm --workspace @peon/mcp run build",
+      runDaemon,
+      runMcpServer,
+      claudeHook: hookCommand
+    },
+    nextCommands: buildNextCommands({ ready, daemonUrl, daemonBin, mcpBin, claudeHook }),
+    notes: [
+      nonDestructiveNote,
+      ready ? "Build artifacts are present." : "Build artifacts are missing; run the build command first.",
+      checks.projectMemoryDir
+        ? "Project memory directory already exists."
+        : "Project memory directory is not present yet; Peon will create it when the daemon writes memory."
+    ]
+  };
+}
+
+export async function collectChecks(projectPath, packageDir) {
+  const daemonBin = join(packageDir, "dist", "daemon-cli.js");
+  const mcpBin = join(packageDir, "dist", "index.js");
+  const claudeHook = join(packageDir, "scripts", "claude-peon-hook.mjs");
+  const memoryDir = join(projectPath, ".peon");
+
+  return {
+    packageDir: await exists(packageDir),
+    builtDaemon: await exists(daemonBin),
+    builtMcpServer: await exists(mcpBin),
+    claudeHook: await exists(claudeHook),
+    projectMemoryDir: await exists(memoryDir)
+  };
+}
+
+export function formatTextReport(plan) {
+  const status = plan.checks.ready ? "ready" : "needs build";
+  return [
+    `Peon installer ${plan.mode} (${status})`,
+    "",
+    "Paths:",
+    `  Project: ${plan.projectPath}`,
+    `  Daemon:  ${plan.paths.daemonBin}`,
+    `  MCP:     ${plan.paths.mcpBin}`,
+    `  Hook:    ${plan.paths.claudeHook}`,
+    `  Memory:  ${plan.paths.memoryDir}`,
+    "",
+    "Checks:",
+    ...formatChecks(plan.checks),
+    "",
+    "launchctl recommendation:",
+    `  Label: ${plan.launchctl.label}`,
+    `  Plist: ${plan.launchctl.plistPath}`,
+    "",
+    "Claude MCP config snippet:",
+    indent(JSON.stringify(plan.claude.mcpConfigSnippet, null, 2), 2),
+    "",
+    "Claude hook command snippet:",
+    `  ${plan.claude.hookCommandSnippet}`,
+    "",
+    "Next commands:",
+    ...plan.nextCommands.map((command) => `  ${command}`),
+    "",
+    "Notes:",
+    ...plan.notes.map((note) => `  - ${note}`)
+  ].join("\n");
+}
+
+export function formatWritePlan(plan) {
+  return [
+    "# Peon Local Installation Plan",
+    "",
+    "> Planning output only. This command does not modify files, install services, or start Peon.",
+    "",
+    "## 1. Build Peon MCP",
+    "",
+    "```sh",
+    plan.commands.build,
+    "```",
+    "",
+    "## 2. Run the daemon manually",
+    "",
+    "```sh",
+    plan.commands.runDaemon,
+    "```",
+    "",
+    "If you later choose to use launchctl, use:",
+    "",
+    `- Label: \`${plan.launchctl.label}\``,
+    `- Plist path: \`${plan.launchctl.plistPath}\``,
+    "",
+    "## 3. Add Claude MCP server config",
+    "",
+    "```json",
+    JSON.stringify(plan.claude.mcpConfigSnippet, null, 2),
+    "```",
+    "",
+    "## 4. Add Claude hook command",
+    "",
+    "```sh",
+    plan.claude.hookCommandSnippet,
+    "```",
+    "",
+    "## 5. Smoke test commands",
+    "",
+    "```sh",
+    ...plan.nextCommands,
+    "```"
+  ].join("\n");
+}
+
+function formatHelp() {
+  return [
+    "Usage: node scripts/install-peon.mjs [--json] [--check|--write-plan] [project-path]",
+    "",
+    "Modes:",
+    "  default       Print a non-destructive dry-run report.",
+    "  --json        Print the report as JSON.",
+    "  --check       Verify local build artifacts and exit 1 if required artifacts are missing.",
+    "  --write-plan  Print a Markdown installation plan to stdout.",
+    "",
+    "This helper never writes config files, installs hooks, starts services, or calls launchctl."
+  ].join("\n");
+}
+
+function formatChecks(checks) {
+  return [
+    ["packageDir", checks.packageDir],
+    ["builtDaemon", checks.builtDaemon],
+    ["builtMcpServer", checks.builtMcpServer],
+    ["claudeHook", checks.claudeHook],
+    ["projectMemoryDir", checks.projectMemoryDir],
+    ["ready", checks.ready]
+  ].map(([name, value]) => `  ${name}: ${value ? "ok" : "missing"}`);
+}
+
+function buildNextCommands({ ready, daemonUrl, daemonBin, mcpBin, claudeHook }) {
+  const commands = [];
+  if (!ready) commands.push("npm --workspace @peon/mcp run build");
+  commands.push(`PEON_DAEMON_URL=${daemonUrl} node ${shellQuote(daemonBin)}`);
+  commands.push(`PEON_DAEMON_URL=${daemonUrl} node ${shellQuote(mcpBin)}`);
+  commands.push(`PEON_DAEMON_URL=${daemonUrl} node ${shellQuote(claudeHook)}`);
+  commands.push("node peon-mcp/scripts/install-peon.mjs --check");
+  return commands;
+}
+
+function setAction(current, next) {
+  if (current !== "dry-run" && current !== next) {
+    throw new Error("Choose only one of --check or --write-plan.");
+  }
+  return next;
+}
+
+function normalizeUrl(value) {
+  return String(value || defaultDaemonUrl).replace(/\/$/, "");
+}
+
+async function exists(path) {
+  return access(path).then(
+    () => true,
+    () => false
+  );
+}
+
+function isMain(moduleUrl, argvPath) {
+  return Boolean(argvPath && moduleUrl === pathToFileURL(argvPath).href);
+}
+
+function indent(value, spaces) {
+  const prefix = " ".repeat(spaces);
+  return value
+    .split("\n")
+    .map((line) => `${prefix}${line}`)
+    .join("\n");
+}
+
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/scripts/lib/eval-ledger.mjs

@@ -0,0 +1,104 @@
+/**
+ * Eval results ledger — a committed, append-only history of every eval run so improvements
+ * can be PROVEN (diffed against a fixed baseline) rather than asserted.
+ *
+ * Peon's most valuable findings (graph-is-dead at -2.9%/-3.8% Recall@10; consolidation
+ * belief-only 16.7% vs raw 61.1%) came from evals that only `console.log`'d — there was no
+ * baseline to regress against. Each row pins THREE fingerprints so a comparison is trustworthy:
+ *   - gitSha    : the code under test
+ *   - qrelsHash : the exact question/relevance set
+ *   - brain     : {records, hash} of memories.jsonl — because retrieval evals rank against the
+ *                 LIVE, mutating brain, a diff is only apples-to-apples when the brain matches.
+ * Side-effect-free except appendRow/mkdir, so the pure logic is unit-testable.
+ */
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { join, dirname } from "node:path";
+
+export function sha256(text) {
+  return createHash("sha256").update(String(text)).digest("hex").slice(0, 16);
+}
+
+export function gitSha(cwd = process.cwd()) {
+  try {
+    // execFileSync (no shell) with a fixed argv — no interpolation, no injection surface.
+    return execFileSync("git", ["rev-parse", "--short", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"] })
+      .toString()
+      .trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+/** sha256 of a file's contents (short), or "absent" if unreadable — for the qrels fingerprint. */
+export function fileHash(path) {
+  try {
+    return sha256(readFileSync(path, "utf8"));
+  } catch {
+    return "absent";
+  }
+}
+
+/** Pin the memory state: record count + content hash of memories.jsonl. */
+export function brainFingerprint(projectPath, memoryDirName = ".peon") {
+  const mem = join(projectPath, memoryDirName, "brain", "memories.jsonl");
+  let content = "";
+  try {
+    content = readFileSync(mem, "utf8");
+  } catch {
+    return { records: 0, hash: "absent" };
+  }
+  const records = content.split(/\r?\n/).filter(Boolean).length;
+  return { records, hash: sha256(content) };
+}
+
+export function ledgerPath(cwd = process.cwd()) {
+  return join(cwd, "eval-results", "history.jsonl");
+}
+
+export function readLedger(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * The most recent prior row comparable to `row`. Prefers an EXACT match (same kind + qrelsHash +
+ * brain hash) → a trustworthy code-only A/B. Falls back to the latest same-kind+qrels row with
+ * `sameBrain:false` so the caller can still show a delta but flag it as brain-drifted (informational).
+ */
+export function findBaseline(rows, row) {
+  let loose = null;
+  for (let i = rows.length - 1; i >= 0; i--) {
+    const r = rows[i];
+    if (r.kind !== row.kind || r.qrelsHash !== row.qrelsHash) continue;
+    if ((r.brain && r.brain.hash) === (row.brain && row.brain.hash)) return { row: r, sameBrain: true };
+    if (!loose) loose = r;
+  }
+  return loose ? { row: loose, sameBrain: false } : null;
+}
+
+export function appendRow(path, row) {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, JSON.stringify(row) + "\n");
+}
+
+/** Signed per-key delta of two flat numeric metric maps (keys present in both). */
+export function metricDelta(current, baseline) {
+  const out = {};
+  if (!baseline) return out;
+  for (const k of Object.keys(current)) {
+    if (typeof current[k] === "number" && typeof baseline[k] === "number") out[k] = current[k] - baseline[k];
+  }
+  return out;
+}

package/scripts/lib/stl-classify.mjs

@@ -0,0 +1,44 @@
+/**
+ * Pure classifiers for STL daemon-log analysis.
+ *
+ * Kept side-effect free (no fs / no top-level work) so the STL engine's behaviour
+ * can be unit-tested without executing the whole report-generation script.
+ */
+
+/**
+ * True when a `response_out` log entry is a CLIENT-side connection abort rather than
+ * a genuine server fault. Node/Express logs status 500 with `error: "aborted"` when
+ * the socket closes mid-response — e.g. a Claude Code hook process exits (or fires a
+ * newer request) before Peon finishes replying. The event is not lost: the client
+ * retries and the record lands (the 201s dominate the log). Counting these as
+ * "serious recording-path 5xx" cries wolf and has repeatedly skewed the verdict.
+ */
+export function isClientAbort(e) {
+  if (!e || Number(e.status) < 500) return false;
+  return /\babort(ed)?\b/i.test(String(e.error || ""));
+}
+
+/**
+ * True when a `response_out` 500 is a stale-session rejection the client self-heals,
+ * rather than a genuine server fault. The daemon throws `Unknown Peon session: <id>`
+ * (HTTP 500) when a recording call (`/messages`, `/events`) references a session id it
+ * no longer holds — typically because the daemon restarted, or the session index pruned
+ * the entry, after the client cached the id. The Claude Code hook's `recordWithSession`
+ * catches exactly this message, drops the stale id, recreates the session and retries,
+ * so the record still lands (the log shows the 500 immediately followed by
+ * `/sessions:201` + `/messages:201`). Surfacing these as "serious recording-path 5xx"
+ * cries wolf just like client aborts did, and repeatedly drove the recording-path
+ * headline off a self-healed, no-data-loss condition.
+ */
+export function isStaleSession(e) {
+  if (!e || Number(e.status) < 500) return false;
+  return /Unknown Peon session/i.test(String(e.error || ""));
+}
+
+/**
+ * True when a `response_out` is a real server fault we should surface — status >= 500
+ * that is neither a client abort nor a self-healed stale-session rejection.
+ */
+export function isServerFault(e) {
+  return !!e && Number(e.status) >= 500 && !isClientAbort(e) && !isStaleSession(e);
+}