agent-polygraph 0.0.0-stage → 0.2.0

package/src/guard.js

@@ -0,0 +1,240 @@
+// `agent-polygraph guard`: a Stop hook for Claude Code and Codex.
+// When the agent's final message says tests pass but the session shows no passing run
+// after its last code edit, the hook sends it back once to rerun the tests or correct itself.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import * as claude from "./sources/claude.js";
+import * as codex from "./sources/codex.js";
+import { analyzeSession } from "./analyze.js";
+import { findTestClaim, findTestClaims } from "./classify.js";
+import { applyRecords } from "./record.js";
+import { readSettings, writeSettings } from "./safe-config.js";
+
+
+/** Hook entry point: read the Stop payload on stdin, maybe print a block decision. */
+export async function runHook(stdinText, { plugin = false } = {}) {
+  let payload;
+  try {
+    payload = JSON.parse(stdinText || "{}");
+  } catch {
+    return null;
+  }
+  if (payload.stop_hook_active) return null; // we already sent the agent back once
+  // The Claude Code plugin's hook steps aside when `guard --install` put one in settings
+  // too, so the agent isn't sent back twice with the same message.
+  if (plugin && settingsHasGuard(payload.cwd)) return null;
+  const transcript = payload.transcript_path;
+  if (!transcript || !fs.existsSync(transcript)) return null;
+
+  const isCodex = sniffCodex(transcript);
+  const src = isCodex ? codex : claude;
+  const files = [transcript];
+  if (!isCodex) {
+    const subDir = path.join(transcript.replace(/\.jsonl$/, ""), "subagents");
+    try {
+      for (const f of fs.readdirSync(subDir)) if (f.endsWith(".jsonl")) files.push(path.join(subDir, f));
+    } catch {}
+  }
+  const session = await src.parse({ agent: src.name, id: "live", files });
+  if (payload.cwd && !session.cwd) session.cwd = payload.cwd;
+  // snapshots and terminal runs from `agent-polygraph record`, if installed
+  try {
+    session.file = transcript;
+    applyRecords(session);
+  } catch {}
+
+  // Judge only what the agent is actually ending with. Agents send that text with the Stop
+  // payload (it may not be in the transcript yet); an earlier claim it has since corrected
+  // ("Correction: I did not run the tests") must not trigger a block.
+  const events = session.events;
+  const lastUser = events.findLastIndex((e) => e.kind === "user");
+  let final;
+  const last = payload.last_assistant_message;
+  if (typeof last === "string" && last.trim()) {
+    // a loop, not Math.max(...events): long sessions exceed the argument limit
+    let latest = session.end ?? 0;
+    for (const e of events) if ((e.ts ?? 0) > latest) latest = e.ts;
+    final = { kind: "say", ts: latest + 1, text: last };
+    events.push(final);
+  } else {
+    const i = events.findLastIndex((e) => e.kind === "say");
+    final = i > lastUser ? events[i] : null;
+  }
+  if (!final || !findTestClaim(final.text)) return null;
+
+  const result = analyzeSession(session);
+  const detail = result.findings.find((f) => f.type === "claim" && f.ts === final.ts && final.verdict === f.detail.verdict)?.detail;
+  if (!detail) return null; // backed, or nothing we can judge
+  // quote the message's conclusion ("All tests pass."), not a step along the way
+  const quote = findTestClaims(final.text).at(-1) ?? detail.claim;
+  return { decision: "block", reason: reasonFor({ ...detail, claim: quote }) };
+}
+
+function reasonFor(d) {
+  const why = {
+    "no-run": "no test run appears in this session",
+    stale: `you edited ${d.editedAfter} after the last test run`,
+    failed: "the most recent test run in this session failed",
+  }[d.verdict];
+  return [
+    `agent-polygraph: your final message says "${d.claim}", but ${why}.`,
+    "Run the relevant tests now and report the actual result. If they can't be run, say so instead of claiming they pass.",
+  ].join(" ");
+}
+
+/** Is a guard hook installed in Claude Code settings that apply to `cwd` (user or project)? */
+export function settingsHasGuard(cwd, home = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude")) {
+  const files = [path.join(home, "settings.json"), path.join(home, "settings.local.json")];
+  // Claude Code reads project settings from where it was started, which may be above cwd
+  for (let d = cwd ? path.resolve(cwd) : null; d; d = path.dirname(d) === d ? null : path.dirname(d)) {
+    files.push(path.join(d, ".claude", "settings.json"), path.join(d, ".claude", "settings.local.json"));
+  }
+  return files.some((file) => {
+    try {
+      const stop = JSON.parse(fs.readFileSync(file, "utf8")).hooks?.Stop;
+      return Array.isArray(stop) && stop.some((g) => (g.hooks || []).some((h) => isOurHook(h, "guard")));
+    } catch {
+      return false;
+    }
+  });
+}
+
+function sniffCodex(file) {
+  try {
+    const fd = fs.openSync(file, "r");
+    const buf = Buffer.alloc(4096);
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    fs.closeSync(fd);
+    return /"type"\s*:\s*"session_meta"/.test(buf.subarray(0, n).toString("utf8"));
+  } catch {
+    return false;
+  }
+}
+
+// --- install / uninstall ------------------------------------------------------------
+
+const IN_NPX_CACHE = /[\\/]_npx[\\/]/;
+
+export function hookCommand(sub = "guard") {
+  // npx puts its temporary copy on PATH while it runs, so a bare `agent-polygraph`
+  // only counts when it's a real install that will still exist later.
+  try {
+    const found = execFileSync(process.platform === "win32" ? "where" : "which", ["agent-polygraph"], { encoding: "utf8" }).split(/\r?\n/)[0].trim();
+    if (found && !IN_NPX_CACHE.test(fs.realpathSync(found))) return `agent-polygraph ${sub}`;
+  } catch {}
+  const self = fs.realpathSync(process.argv[1]);
+  if (!IN_NPX_CACHE.test(self)) return `node ${JSON.stringify(self)} ${sub}`;
+  const { version } = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  return `npx -y agent-polygraph@${version} ${sub}`;
+}
+
+/** Hook config files to touch: project-level by default, user-level with `global`. */
+export function targets({ agents = ["claude", "codex"], global = false, cwd = process.cwd() } = {}) {
+  const out = [];
+  if (agents.includes("claude")) {
+    out.push({
+      agent: "claude",
+      file: global
+        ? path.join(process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"), "settings.json")
+        : path.join(cwd, ".claude", "settings.json"),
+    });
+  }
+  if (agents.includes("codex")) {
+    out.push({
+      agent: "codex",
+      file: global
+        ? path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "hooks.json")
+        : path.join(cwd, ".codex", "hooks.json"),
+    });
+  }
+  return out;
+}
+
+/**
+ * One definition of "our hook", covering every command form we write: a global install
+ * (`agent-polygraph guard`), a version-pinned npx (`npx -y agent-polygraph@0.1.0 guard`)
+ * and a local checkout (`node "/path/bin/polygraph.js" guard`).
+ */
+export function isOurHook(h, sub = "guard") {
+  const cmd = String(h?.command || "");
+  return new RegExp(String.raw`\bagent-polygraph(?:@\S+)?\s+${sub}\b`).test(cmd) || new RegExp(String.raw`polygraph\.js["']?\s+${sub}\b`).test(cmd);
+}
+
+// `guard` is a Stop hook; `record` runs after each shell command (PostToolUse). Codex gets
+// no matcher: the recorder itself ignores tools that aren't shell commands.
+const HOOKS = {
+  guard: { event: "Stop", timeout: 30, matcher: {} },
+  record: { event: "PostToolUse", timeout: 20, matcher: { claude: "Bash|PowerShell" } },
+};
+
+export function install(opts) {
+  const sub = opts.sub || "guard";
+  const spec = HOOKS[sub];
+  const command = opts.command || hookCommand(sub);
+  const isOurs = (h) => isOurHook(h, sub);
+  return targets(opts).map(({ agent, file }) => {
+    const config = readJson(file);
+    config.hooks ||= {};
+    const stop = (config.hooks[spec.event] ||= []);
+    const ours = stop.flatMap((g) => (g.hooks || []).filter(isOurs));
+    let changed = false;
+    if (!ours.length) {
+      const group = { hooks: [{ type: "command", command, timeout: spec.timeout }] };
+      if (spec.matcher[agent]) group.matcher = spec.matcher[agent];
+      stop.push(group);
+      changed = true;
+    } else {
+      // upgrade an older form (another version, npx vs global) in place; drop duplicates
+      if (ours[0].command !== command) {
+        ours[0].command = command;
+        changed = true;
+      }
+      for (const g of stop) {
+        const before = (g.hooks || []).length;
+        g.hooks = (g.hooks || []).filter((h) => !isOurs(h) || h === ours[0]);
+        if (g.hooks.length !== before) changed = true;
+      }
+      config.hooks[spec.event] = stop.filter((g) => g.hooks.length);
+    }
+    if (changed) {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      const save = writeSettings(file, JSON.stringify(config, null, 2) + "\n");
+      return { agent, file, changed, command, backup: save.backup };
+    }
+    return { agent, file, changed, command };
+  });
+}
+
+export function uninstall(opts) {
+  const sub = opts.sub || "guard";
+  const { event } = HOOKS[sub];
+  const isOurs = (h) => isOurHook(h, sub);
+  return targets(opts).map(({ agent, file }) => {
+    if (!fs.existsSync(file)) return { agent, file, changed: false };
+    const config = readJson(file);
+    const stop = config.hooks?.[event];
+    if (!Array.isArray(stop)) return { agent, file, changed: false };
+    const removed = stop.reduce((n, g) => n + (g.hooks || []).filter(isOurs).length, 0);
+    if (!removed) return { agent, file, changed: false };
+    const kept = stop.map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !isOurs(h)) })).filter((g) => g.hooks.length);
+    if (kept.length) config.hooks[event] = kept;
+    else delete config.hooks[event];
+    if (!Object.keys(config.hooks).length) delete config.hooks;
+    const save = writeSettings(file, JSON.stringify(config, null, 2) + "\n");
+    return { agent, file, changed: true, backup: save.backup };
+  });
+}
+
+function readJson(file) {
+  try {
+    const { text } = readSettings(file);
+    if (text === null) return {};
+    return JSON.parse(text);
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    throw new Error(`${file} is not valid JSON; fix or remove it first (${e.message})`);
+  }
+}

package/src/jsonl.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import readline from "node:readline";
+
+/**
+ * Stream parsed records from a JSONL file. `keep(line)` is a cheap substring
+ * prefilter so we don't JSON.parse the many large records we never look at.
+ */
+export async function* readJsonl(file, keep = () => true, stats = {}) {
+  const rl = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity });
+  stats.lines ??= 0;
+  stats.kept ??= 0;
+  for await (const line of rl) {
+    if (!line) continue;
+    stats.lines++;
+    if (!keep(line)) continue;
+    stats.kept++;
+    try {
+      yield JSON.parse(line);
+    } catch {
+      // partial line from a session that is still being written
+    }
+  }
+}

package/src/record.js

@@ -0,0 +1,402 @@
+// `agent-polygraph record`: optional evidence the session logs don't carry.
+//
+// - A PostToolUse hook (Claude Code and Codex). After a test or potential write,
+//   it records bounded, keyed source-file fingerprints and test outcomes.
+//   It does not store raw commands, test output, source contents or Git objects.
+//   Comparing snapshots can resolve changes not identifiable from shell text.
+// - Shell integration (bash, zsh): test commands you run in your own terminals are logged
+//   with their folder, start and end time and exit code. No output is kept.
+//
+// Everything stays in ~/.agent-polygraph (or $AGENT_POLYGRAPH_HOME). Nothing is uploaded.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { readSettings, writeSettings } from "./safe-config.js";
+import { execFileSync } from "node:child_process";
+import { isTestCommand, isCodePath, mayWriteFiles, shellWrites, outcomeFromOutput, passedCount } from "./classify.js";
+
+export const home = () => process.env.AGENT_POLYGRAPH_HOME || path.join(os.homedir(), ".agent-polygraph");
+const hash = (s) => crypto.createHash("sha1").update(String(s)).digest("hex").slice(0, 16);
+export const recordsFile = (transcript) => path.join(home(), "records", hash(path.resolve(transcript)) + ".jsonl");
+export const terminalFile = () => path.join(home(), "records", "terminal.jsonl");
+
+// Refuse redirected or shared record paths. These files are local evidence,
+// not a place to follow arbitrary symlinks or overwrite somebody else's files.
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+function verifyPrivateFile(fd, file = null) {
+  const st = fs.fstatSync(fd);
+  if (file && process.platform === "win32") {
+    // Windows lacks O_NOFOLLOW; inspect the entry and opened file before I/O.
+    const entry = fs.lstatSync(file);
+    if (entry.isSymbolicLink() || !entry.isFile() || entry.dev !== st.dev || entry.ino !== st.ino)
+      throw new Error("Unsafe linked record file: " + file);
+  }
+  if (!st.isFile() || st.nlink !== 1) throw new Error("Unsafe record file (not regular or multiply linked)");
+  if (process.platform !== "win32") {
+    if (st.uid !== process.getuid()) throw new Error("Record file belongs to another user");
+    fs.fchmodSync(fd, 0o600);
+  }
+}
+function secureDirectory(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // Act on the opened directory, not on a pathname that may be replaced
+  // with a symlink between an lstat() check and chmod().
+  const entry = fs.lstatSync(dir);
+  if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error("Unsafe linked record directory");
+  const fd = fs.openSync(dir, fs.constants.O_RDONLY | (fs.constants.O_DIRECTORY || 0) | NOFOLLOW);
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isDirectory()) throw new Error("Unsafe record directory");
+    if (process.platform === "win32" && fs.lstatSync(dir).isSymbolicLink())
+      throw new Error("Unsafe linked record directory");
+    if (process.platform !== "win32") {
+      if (st.uid !== process.getuid()) throw new Error("Record directory belongs to another user");
+      fs.fchmodSync(fd, 0o700);
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function secureWrite(file, data, append = false) {
+  secureDirectory(path.dirname(file));
+  // Never truncate before validating an existing file. O_NOFOLLOW rejects final
+  // symlinks, and nlink/owner checks reject hard links and unrelated files.
+  try {
+    const entry = fs.lstatSync(file);
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Unsafe linked record file: " + file);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  const fd = fs.openSync(file, fs.constants.O_CREAT | fs.constants.O_WRONLY | (append ? fs.constants.O_APPEND : 0) | NOFOLLOW, 0o600);
+  try {
+    verifyPrivateFile(fd, file);
+    if (!append) fs.ftruncateSync(fd, 0);
+    fs.writeSync(fd, data);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// The key stays on the local machine. A keyed digest lets us correlate commands
+// without ever persisting their text (which may contain tokens/passwords).
+let keyCache;
+let keyCachePath;
+function localKey() {
+  const file = path.join(home(), "record-key");
+  if (keyCachePath === file && keyCache) return keyCache;
+  secureDirectory(home());
+  let key;
+  const readKey = () => {
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+    try {
+      verifyPrivateFile(fd, file);
+      return fs.readFileSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  };
+  try {
+    key = readKey();
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    const candidate = crypto.randomBytes(32);
+    try {
+      const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, 0o600);
+      try { verifyPrivateFile(fd, file); fs.writeSync(fd, candidate); } finally { fs.closeSync(fd); }
+      key = candidate;
+    } catch (race) {
+      if (race.code !== "EEXIST") throw race;
+      key = readKey();
+    }
+  }
+  if (key.length !== 32) throw new Error("Invalid agent-polygraph local record key");
+  keyCache = key;
+  keyCachePath = file;
+  return key;
+}
+export const commandFingerprint = (cmd) => crypto.createHmac("sha256", localKey()).update(String(cmd)).digest("hex");
+
+// --- the hook --------------------------------------------------------------------------
+
+/** PostToolUse entry point. Never throws, never prints: a recorder must not get in the way. */
+export function runRecordHook(stdinText) {
+  try {
+    const p = JSON.parse(stdinText || "{}");
+    const cmd = commandOf(p.tool_input);
+    if (!cmd || !p.transcript_path) return;
+    const test = isTestCommand(cmd);
+    if (!test && !mayWriteFiles(cmd) && !shellWrites(cmd).unresolved) return;
+    const cwd = p.cwd || process.cwd();
+    const rec = { v: 2, ts: Date.now(), id: p.tool_use_id || null, tool: p.tool_name || null, cmdKey: commandFingerprint(cmd), cwd };
+    try {
+      rec.tree = snapshot(cwd);
+    } catch {}
+    if (test) {
+      const out = outputOf(p.tool_response);
+      const outcome = outcomeFromOutput(out);
+      if (outcome) rec.outcome = outcome;
+      const passed = passedCount(out);
+      if (passed != null) rec.passed = passed;
+    }
+    if (!rec.tree && !rec.outcome) return;
+    const file = recordsFile(p.transcript_path);
+    secureWrite(file, JSON.stringify(rec) + "\n", true);
+  } catch {}
+}
+
+function commandOf(input) {
+  if (!input) return null;
+  if (typeof input === "string") return input;
+  const c = input.command ?? input.cmd;
+  if (typeof c === "string") return c;
+  // ["bash", "-lc", "npm test"]
+  if (Array.isArray(c)) return c.length >= 3 && /^-\w*c$/.test(c[c.length - 2]) ? String(c[c.length - 1]) : c.join(" ");
+  return null;
+}
+
+function outputOf(r) {
+  if (r == null) return "";
+  if (typeof r === "string") return r;
+  const parts = [r.stdout, r.stderr, r.output, r.aggregated_output, r.formatted_output, typeof r.content === "string" ? r.content : null];
+  return parts.filter((x) => typeof x === "string").join("\n");
+}
+
+// --- working-tree fingerprints -------------------------------------------------------------
+
+// No git objects or copies of source files are written. Snapshots contain
+// bounded HMACs, which cannot be used as a substitute for the source contents.
+const MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+const MAX_SNAPSHOT_BYTES = 64 * 1024 * 1024;
+const MAX_SNAPSHOT_FILES = 10000;
+
+function safeParents(root, relative) {
+  let parent = root;
+  for (const part of relative.split(/[\\/]/).slice(0, -1)) {
+    if (!part || part === "." || part === "..") return false;
+    parent = path.join(parent, part);
+    const st = fs.lstatSync(parent);
+    if (!st.isDirectory() || st.isSymbolicLink()) return false;
+  }
+  return true;
+}
+
+function sourceFingerprint(root, name, key) {
+  const file = path.join(root, name);
+  // Refuse symlinks in the path. Open the leaf with O_NOFOLLOW too: a symlink
+  // substitution between lstat and open must not make us read its target.
+  if (path.isAbsolute(name) || name.split(/[\\/]/).includes("..") || !safeParents(root, name)) return null;
+  const initial = fs.lstatSync(file, { bigint: true });
+  if (!initial.isFile() || initial.nlink !== 1n || initial.size > BigInt(MAX_SOURCE_BYTES)) return null;
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+  try {
+    const before = fs.fstatSync(fd, { bigint: true });
+    if (!before.isFile() || before.dev !== initial.dev || before.ino !== initial.ino ||
+        before.nlink !== 1n || before.size > BigInt(MAX_SOURCE_BYTES)) return null;
+    const bytes = fs.readFileSync(fd);
+    const after = fs.fstatSync(fd, { bigint: true });
+    if (before.size !== after.size || before.mtimeNs !== after.mtimeNs ||
+        before.ctimeNs !== after.ctimeNs || bytes.length !== Number(before.size)) return null;
+    // A path replacement during the read must remain inconclusive.
+    const current = fs.lstatSync(file, { bigint: true });
+    if (!current.isFile() || current.dev !== after.dev || current.ino !== after.ino ||
+        current.mtimeNs !== after.mtimeNs || current.ctimeNs !== after.ctimeNs) return null;
+    // Linux exposes the opened descriptor's actual path. Reject a race that
+    // redirected a parent directory outside the checkout after safeParents().
+    if (process.platform === "linux") {
+      const opened = fs.realpathSync(`/proc/self/fd/${fd}`);
+      const relative = path.relative(fs.realpathSync(root), opened);
+      if (relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) return null;
+    }
+    return { bytes: bytes.length, digest: crypto.createHmac("sha256", key).update(bytes).digest("hex") };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+export function snapshot(cwd) {
+  const git = (args, options = {}) => execFileSync("git", args, {
+    cwd, encoding: options.encoding ?? "utf8", stdio: ["ignore", "pipe", "ignore"],
+    timeout: 8000, maxBuffer: 16 << 20,
+  });
+  const root = git(["rev-parse", "--show-toplevel"]).trim();
+  const files = Object.create(null);
+  const paths = git(["ls-files", "--cached", "--others", "--exclude-standard", "-z"], { encoding: "buffer" }).toString("utf8").split("\0").filter(Boolean);
+  const key = localKey();
+  let complete = true;
+  let total = 0;
+  let count = 0;
+  for (const name of paths) {
+    if (!isCodePath(name)) continue;
+    if (++count > MAX_SNAPSHOT_FILES) { complete = false; break; }
+    try {
+      const data = sourceFingerprint(root, name, key);
+      if (!data) { complete = false; continue; }
+      if (total + data.bytes > MAX_SNAPSHOT_BYTES) { complete = false; break; }
+      total += data.bytes;
+      files[name] = data.digest;
+    } catch {
+      complete = false;
+    }
+  }
+  return { root, files, complete };
+}
+
+export function treeDiff(a, b) {
+  if (!a || !b || a.root !== b.root || !a.complete || !b.complete) return null;
+  const names = new Set([...Object.keys(a.files), ...Object.keys(b.files)]);
+  return [...names].filter((name) => a.files[name] !== b.files[name]);
+}
+
+// --- using the records -----------------------------------------------------------------------
+
+const squash = (c) => String(c).replace(/\s+/g, " ").trim();
+
+/**
+ * Attach recorded snapshots and outcomes to the session's commands, and add test runs from
+ * your terminals that happened during the session in its checkout. Mutates `session`.
+ */
+export function applyRecords(session, { terminal = loadTerminal() } = {}) {
+  let recs = [];
+  try {
+    recs = readLines(recordsFile(session.file));
+  } catch {}
+  if (recs.length) {
+    session.treeDiff = treeDiff;
+    // a record belongs to the command with the same text, recorded after it started
+    const free = recs.map((r) => ({ ...r, key: r.cmdKey || (r.cmd ? squash(r.cmd) : null) }));
+    for (const ev of session.events) {
+      if (ev.kind !== "cmd" || ev.external) continue;
+      const key = commandFingerprint(ev.cmd);
+      const legacyKey = squash(ev.cmd);
+      const k = free.findIndex((r) => r && (ev.id && r.id ? r.id === ev.id : r.key != null && r.key === (r.cmdKey ? key : legacyKey) && r.ts >= (ev.ts ?? 0) - 2000));
+      if (k < 0) continue;
+      const r = free[k];
+      free[k] = null;
+      if (r.tree) ev.tree = r.tree;
+      if (r.outcome) ev.recorded = { outcome: r.outcome, passed: r.passed ?? null };
+    }
+  }
+  addTerminalRuns(session, terminal);
+  return session;
+}
+
+let terminalCache = null;
+export function loadTerminal() {
+  if (terminalCache) return terminalCache;
+  try {
+    terminalCache = readLines(terminalFile());
+  } catch {
+    terminalCache = [];
+  }
+  return terminalCache;
+}
+
+// Shell hook receipts use the same no-follow, owner-only writer as agent hooks.
+// Accept an allowlisted category, never an arbitrary command or untrusted output.
+const SHELL_RUNNERS = new Set(["pytest", "npm test", "node --test", "go test", "cargo test", "mvn test", "gradle test", "dotnet test", "vitest run"]);
+export function runShellRecord(input) {
+  try {
+    const r = JSON.parse(input);
+    if (!SHELL_RUNNERS.has(r.runner) || !isTestCommand(r.runner)) return false;
+    if (!Number.isFinite(r.start) || !Number.isFinite(r.end) || r.end < r.start ||
+        !Number.isInteger(r.exit) || typeof r.cwd !== "string" ||
+        !path.isAbsolute(r.cwd) || r.cwd.length > 4096) return false;
+    const rec = { v: 2, kind: "terminal", start: r.start, end: r.end, exit: r.exit, cwd: r.cwd, runner: r.runner };
+    secureWrite(terminalFile(), JSON.stringify(rec) + "\n", true);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function addTerminalRuns(session, runs) {
+  if (!runs.length || !session.cwd || session.start == null || session.end == null) return;
+  const cwd = slash(session.cwd);
+  const related = (d) => {
+    d = slash(d);
+    return d === cwd || d.startsWith(cwd + "/") || cwd.startsWith(d + "/");
+  };
+  let added = 0;
+  for (const r of runs) {
+    const start = Math.round(r.start * 1000);
+    const end = Math.round((r.end ?? r.start) * 1000);
+    const runner = r.runner || r.cmd; // legacy raw-command records are still readable
+    if (!(start >= session.start && start <= session.end) || !r.cwd || !related(r.cwd) || !runner || !isTestCommand(runner)) continue;
+    const ev = { kind: "cmd", ts: start, seq: Number.MAX_SAFE_INTEGER, cmd: runner, workdir: r.cwd, external: "terminal", sub: false };
+    session.events.push(ev, { kind: "result", of: ev, ts: end, seq: Number.MAX_SAFE_INTEGER, exitCode: typeof r.exit === "number" ? r.exit : null, isError: null, output: "" });
+    added++;
+  }
+  if (added) session.events.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0) || (a.seq ?? 0) - (b.seq ?? 0));
+}
+
+const slash = (p) => String(p).replace(/\\/g, "/").replace(/\/$/, "");
+
+function readLines(file) {
+  const out = [];
+  for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {}
+  }
+  return out;
+}
+
+// --- shell integration -----------------------------------------------------------------------
+
+const MARK = "# agent-polygraph record";
+export const shellScript = () => path.join(home(), "shell.sh");
+
+const shQuote = (s) => "'" + String(s).replaceAll("'", "'\"'\"'") + "'";
+const SHELL_SNIPPET = () => fs.readFileSync(new URL("./shell/record.sh", import.meta.url), "utf8")
+  .replace("__APG_NODE__", shQuote(process.execPath))
+  .replace("__APG_ENTRY__", shQuote(fs.realpathSync(fileURLToPath(new URL("../bin/polygraph.js", import.meta.url)))));
+
+const RC_FILES = () => [".bashrc", ".zshrc"].map((f) => path.join(process.env.HOME || os.homedir(), f));
+
+export function installShell() {
+  const script = shellScript();
+  secureWrite(script, SHELL_SNIPPET());
+  secureDirectory(path.join(home(), "records"));
+  const quoted = shQuote(script);
+  const line = `[ -f ${quoted} ] && . ${quoted}  ${MARK}`;
+  const out = [];
+  for (const rc of RC_FILES()) {
+    const shell = rc.endsWith("zshrc") ? "zsh" : "bash";
+    if (!fs.existsSync(rc) && !onPath(shell)) continue;
+    const text = readSettings(rc).text ?? "";
+    if (text.includes(MARK)) {
+      out.push({ file: rc, changed: false });
+      continue;
+    }
+    const result = writeSettings(rc, text + (text && !text.endsWith("\n") ? "\n" : "") + line + "\n");
+    out.push({ file: rc, changed: result.changed, backup: result.backup });
+  }
+  return { script, rcs: out };
+}
+
+export function uninstallShell() {
+  const out = [];
+  for (const rc of RC_FILES()) {
+    if (!fs.existsSync(rc)) continue;
+    const text = readSettings(rc).text;
+    if (text == null) continue;
+    if (!text.includes(MARK)) continue;
+    const result = writeSettings(rc, text.split("\n").filter((l) => !l.includes(MARK)).join("\n"));
+    out.push({ file: rc, changed: result.changed, backup: result.backup });
+  }
+  fs.rmSync(shellScript(), { force: true });
+  return { rcs: out };
+}
+
+function onPath(cmd) {
+  try {
+    execFileSync("which", [cmd], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}