agent-polygraph 0.0.0-stage → 0.2.0

package/src/report/format.js

@@ -0,0 +1,87 @@
+export const AGENT_NAMES = { claude: "Claude Code", codex: "Codex" };
+
+export function duration(ms) {
+  if (!ms) return "0m";
+  const m = ms / 60000;
+  if (m < 1) return `${Math.round(ms / 1000)}s`;
+  if (m < 60) return `${Math.round(m)}m`;
+  const h = m / 60;
+  return h < 10 ? `${h.toFixed(1)}h` : `${Math.round(h)}h`;
+}
+
+export function pct(x) {
+  return x == null ? "–" : `${Math.round(x * 100)}%`;
+}
+
+export function day(ts, opts = { month: "short", day: "numeric" }) {
+  return ts ? new Date(ts).toLocaleDateString("en-US", opts) : "?";
+}
+
+export function range(g) {
+  if (!g.start || !isFinite(g.start)) return "";
+  const y = { month: "short", day: "numeric", year: "numeric" };
+  return `${day(g.start)} – ${day(g.end, y)}`;
+}
+
+/** Columns to show: one per agent (or model) that has sessions, plus "All" when there are several. */
+export function columns(groups, by = "agent") {
+  const cols = Object.entries(groups)
+    .filter(([k, g]) => k.startsWith(by + ":") && g.activeSessions > 0)
+    .sort((a, b) => b[1].activeSessions - a[1].activeSessions)
+    .map(([k, g]) => ({ key: k, label: by === "agent" ? AGENT_NAMES[k.slice(6)] || k.slice(6) : k.slice(6), g }));
+  if (cols.length !== 1) cols.push({ key: "all", label: "All", g: groups.all });
+  return cols;
+}
+
+export const ROWS = {
+  claims: [
+    ["Backed by a fresh passing run", (g) => g.claims.backed],
+    ["No test run in the session", (g) => g.claims["no-run"]],
+    ["Code edited after the last run", (g) => g.claims.stale],
+    ["Last run had failed", (g) => g.claims.failed],
+    ["Couldn't tell", (g) => g.claims.unknown],
+  ],
+  unclear: [
+    ["…test result unreadable", (g) => g.unclear["test result unreadable"] || 0],
+    ["…unresolved file change after the run", (g) => g.unclear["unresolved file change after the run"] || 0],
+    ["…test still running", (g) => g.unclear["test still running"] || 0],
+    ["…other", (g) => Object.entries(g.unclear).filter(([k]) => !/unreadable|unresolved|still running/.test(k)).reduce((a, [, v]) => a + v, 0)],
+  ],
+  integrity: [
+    ['Failing test "fixed" by editing only tests', (g) => g.findingCounts["test-only-fix"] || 0],
+    ["Edits that weakened an existing test", (g) => g.findingCounts["weakened-test"] || 0],
+  ],
+  time: [
+    ["Test runs", (g) => g.testRuns],
+    ["…that failed", (g) => g.failingRuns],
+    ["Time spent in tests", (g) => duration(g.testMs)],
+    ["Full-suite runs", (g) => g.fullSuiteRuns],
+    ["Time in full-suite runs", (g) => duration(g.fullSuiteMs)],
+    ["Same failing command retried 3+ times", (g) => g.findingCounts["retry-loop"] || 0],
+  ],
+  you: [
+    ["Your messages", (g) => g.userMessages],
+    ['Pushback ("no", "I told you", "revert"…)', (g) => g.corrections],
+    ["Times you interrupted the agent", (g) => g.interrupts],
+    ["Risky git commands", (g) => Object.values(g.risky).reduce((a, b) => a + b, 0)],
+  ],
+};
+
+// Newest agent versions this release was checked against. Logs from newer versions are
+// still read, but formats change: the report says so instead of failing quietly.
+export const TESTED = { claude: "2.1.314", codex: "0.166.0" };
+
+const parts = (v) => String(v).split(/[^\d]+/).filter(Boolean).map(Number);
+export function compareVersions(a, b) {
+  const x = parts(a), y = parts(b);
+  for (let i = 0; i < Math.max(x.length, y.length); i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  return 0;
+}
+
+/** "2.1.220–2.1.314" for the versions seen, and whether any is newer than tested. */
+export function versionRange(agent, versions) {
+  if (!versions?.length) return null;
+  const sorted = [...versions].sort(compareVersions);
+  const lo = sorted[0], hi = sorted[sorted.length - 1];
+  return { text: lo === hi ? lo : `${lo}–${hi}`, newer: compareVersions(hi, TESTED[agent] || "0") > 0 };
+}

package/src/report/html.js

@@ -0,0 +1,101 @@
+// A self-contained, numbers-only report meant to be screenshotted or shared.
+// Never put prompts, file paths, commands or claim text in here.
+
+import { ROWS, columns, pct, range } from "./format.js";
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+
+export function renderHtml({ groups, by = "agent", version, demo = false, skipped = 0, unrecognized = 0 }) {
+  const cols = columns(groups, by);
+  const all = groups.all;
+  const head = cols.map((c) => `<th>${esc(c.label)}</th>`).join("");
+  // "…" rows break down the row above them; like the terminal, hide them when all zero
+  const table = (rows) =>
+    rows
+      .filter(([label, fn]) => !label.startsWith("…") || cols.some((c) => Number(fn(c.g)) > 0))
+      .map(([label, fn]) => {
+        const cls = label.startsWith("…") ? ' class="sub"' : "";
+        return `<tr${cls}><td>${esc(label)}</td>${cols.map((c) => `<td>${esc(fn(c.g))}</td>`).join("")}</tr>`;
+      })
+      .join("");
+  const rate = `<tr class="total"><td>Receipt rate</td>${cols.map((c) => `<td>${esc(pct(c.g.receiptRate))}</td>`).join("")}</tr>`;
+
+  const tiles = cols
+    .filter((c) => c.key !== "all" || cols.length === 1)
+    .map((c) => {
+      const r = c.g.receiptRate;
+      const judged = c.g.claimsTotal - c.g.claims.unknown;
+      const unclear = c.g.claims.unknown;
+      const tone = r == null ? "" : r >= 0.95 ? "good" : r >= 0.8 ? "warn" : "bad";
+      return `<div class="tile ${tone}">
+  <div class="tile-label">${esc(c.label)}</div>
+  <div class="tile-value">${esc(pct(r))}</div>
+  <div class="tile-sub">${c.g.claims.backed} of ${judged} “tests pass” claims had a fresh passing run${unclear ? `; ${unclear} more couldn't be judged` : ""}</div>
+  <div class="bar"><span style="width:${r == null ? 0 : Math.round(r * 100)}%"></span></div>
+</div>`;
+    })
+    .join("\n");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Agent Polygraph Report</title>
+<style>
+:root{--bg:#f6f5f1;--card:#fff;--ink:#16181d;--muted:#6b6f78;--line:#e4e2dc;--good:#1f8a4c;--warn:#b7791f;--bad:#c0392b;--accent:#3949ab}
+@media (prefers-color-scheme:dark){:root:not([data-theme=light]){--bg:#111317;--card:#1a1d23;--ink:#eceef2;--muted:#9aa0ab;--line:#2a2e36;--good:#4cc38a;--warn:#e0a84a;--bad:#ef6b5e;--accent:#8c9eff}}
+:root[data-theme=dark]{--bg:#111317;--card:#1a1d23;--ink:#eceef2;--muted:#9aa0ab;--line:#2a2e36;--good:#4cc38a;--warn:#e0a84a;--bad:#ef6b5e;--accent:#8c9eff}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:860px;margin:0 auto;padding:40px 16px 56px}
+h1{font-size:28px;letter-spacing:-.02em;margin:0}
+.meta{color:var(--muted);margin:4px 0 28px}
+.tiles{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:14px;margin-bottom:28px}
+.tile{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px 18px 16px}
+.tile-label{color:var(--muted);font-size:13px;text-transform:uppercase;letter-spacing:.06em}
+.tile-value{font-size:52px;font-weight:700;letter-spacing:-.03em;line-height:1.1;margin:6px 0 2px;font-variant-numeric:tabular-nums}
+.tile.good .tile-value{color:var(--good)}.tile.warn .tile-value{color:var(--warn)}.tile.bad .tile-value{color:var(--bad)}
+.tile-sub{color:var(--muted);font-size:13px}
+.bar{height:6px;background:var(--line);border-radius:3px;margin-top:12px;overflow:hidden}
+.bar span{display:block;height:100%;background:currentColor}
+.tile.good .bar{color:var(--good)}.tile.warn .bar{color:var(--warn)}.tile.bad .bar{color:var(--bad)}
+section{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:6px 18px 10px;margin-bottom:14px;overflow-x:auto}
+h2{font-size:15px;margin:14px 0 4px}
+h2 small{color:var(--muted);font-weight:400}
+table{width:100%;border-collapse:collapse;font-variant-numeric:tabular-nums}
+th,td{padding:7px 0;border-bottom:1px solid var(--line);text-align:right;white-space:nowrap}
+th{color:var(--muted);font-weight:500;font-size:13px}
+th:first-child,td:first-child{text-align:left;white-space:normal;padding-right:12px}
+td+td,th+th{padding-left:16px}
+tr:last-child td{border-bottom:0}
+tr.sub td{color:var(--muted);font-size:13px;padding-top:4px;padding-bottom:4px}
+tr.sub td:first-child{padding-left:14px}
+tr.total td{font-weight:600}
+.note{color:var(--warn);font-size:13px;margin:-16px 0 24px}
+.demo{display:inline-block;margin:10px 0 0;padding:4px 10px;border-radius:999px;background:var(--warn);color:var(--card);font-size:13px;font-weight:600}
+footer{color:var(--muted);font-size:13px;margin-top:22px}
+footer a{color:var(--accent)}
+</style>
+</head>
+<body>
+<main>
+<h1>Did my coding agents show their work?</h1>${demo ? '\n<p class="demo">Demo data: generated sessions with invented numbers, not a benchmark of any agent.</p>' : ""}
+<p class="meta">${all.activeSessions} working sessions · ${esc(range(all))} · ${all.testRuns.toLocaleString("en-US")} test runs checked</p>${skipped ? `\n<p class="note">${skipped} session file${skipped === 1 ? "" : "s"} couldn't be read and ${skipped === 1 ? "is" : "are"} not included.</p>` : ""}${unrecognized ? `\n<p class="note">${unrecognized} session file${unrecognized === 1 ? " is" : "s are"} in a log format this version doesn't recognize and not included.</p>` : ""}
+<div class="tiles">
+${tiles}
+</div>
+<section><h2>“Tests pass” claims <small>was there a passing run after the last code edit?</small></h2>
+<table><tr><th></th>${head}</tr>${table(ROWS.claims)}${table(ROWS.unclear)}${rate}</table></section>
+<section><h2>Test integrity <small>worth a second look, not proof of cheating</small></h2>
+<table><tr><th></th>${head}</tr>${table(ROWS.integrity)}</table></section>
+<section><h2>Where the time went</h2>
+<table><tr><th></th>${head}</tr>${table(ROWS.time)}</table></section>
+<section><h2>You and the agent</h2>
+<table><tr><th></th>${head}</tr>${table(ROWS.you)}</table></section>
+<footer>Generated locally by <a href="https://github.com/EleChon-pixel/agent-polygraph">agent-polygraph</a>${version ? " " + esc(version) : ""} from Claude Code and Codex session logs. Numbers only: no prompts, code or file paths are included. Run your own: <code>npx agent-polygraph</code></footer>
+</main>
+</body>
+</html>
+`;
+}

package/src/report/terminal.js

@@ -0,0 +1,160 @@
+import os from "node:os";
+import { AGENT_NAMES, ROWS, TESTED, columns, day, duration, pct, range, versionRange } from "./format.js";
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = paint("1");
+const dim = paint("2");
+const red = paint("31");
+const green = paint("32");
+const yellow = paint("33");
+const cyan = paint("36");
+
+const VERDICT_LABEL = {
+  "no-run": "no test run in the session",
+  stale: "code edited after the last run",
+  failed: "the last test run had failed",
+};
+
+export function renderTerminal({ sessions, groups, seconds, by = "agent", examples = 5, demo = false }) {
+  const out = [];
+  const cols = columns(groups, by);
+  const all = groups.all;
+  const W = 44;
+  const CW = Math.max(12, ...cols.map((c) => c.label.length + 2));
+
+  const header = (title, sub) => {
+    out.push("");
+    out.push(bold(title) + (sub ? dim("  " + sub) : ""));
+    out.push(dim(" ".repeat(W) + cols.map((c) => c.label.padStart(CW)).join("")));
+  };
+  const row = (label, fn, colorize) => {
+    const cells = cols.map((c) => {
+      const v = fn(c.g);
+      const s = String(v).padStart(CW);
+      return colorize ? colorize(v, s) : s;
+    });
+    const padded = label.padEnd(W - 2);
+    out.push("  " + (label.startsWith("…") ? dim(padded) : padded) + cells.join(""));
+  };
+  const warnIfPositive = (v, s) => (typeof v === "number" && v > 0 ? yellow(s) : s);
+
+  out.push("");
+  if (!all.activeSessions) {
+    out.push(bold("agent-polygraph"));
+    out.push("");
+    out.push("No Claude Code or Codex sessions with commands or edits found.");
+    out.push(dim("Looked in ~/.claude/projects and ~/.codex/sessions (override with --claude-dir / --codex-dir)."));
+    return out.join("\n");
+  }
+  out.push(bold("agent-polygraph") + dim(`  ${all.activeSessions} working sessions · ${range(all)} · ${seconds.toFixed(1)}s`));
+  if (demo) out.push(yellow("DEMO DATA: generated sessions, invented numbers. Run without --demo to check your own."));
+
+  header('"Tests pass" claims', "was there a passing run after the last code edit?");
+  ROWS.claims.forEach(([label, fn], i) => row(label, fn, i === 0 ? (v, s) => green(s) : i < 4 ? warnIfPositive : null));
+  // say why, instead of hiding unclear claims behind the receipt rate
+  ROWS.unclear.forEach(([label, fn]) => cols.some((c) => fn(c.g) > 0) && row(label, fn, (v, s) => dim(s)));
+  row(
+    bold("Receipt rate"),
+    (g) => pct(g.receiptRate),
+    (v, s) => bold(v === "–" ? s : parseInt(v) >= 95 ? green(s) : parseInt(v) >= 80 ? yellow(s) : red(s)),
+  );
+  // evidence that came from outside the agents' logs (record, --ci)
+  const ev = all.evidence || {};
+  const used = [
+    [ev.snapshot, "settled by working-tree snapshots"],
+    [ev.recorded, "read from recorded test output"],
+    [ev.terminal, "judged by test runs in your terminal"],
+    [ev.ci, "judged with GitHub Actions"],
+  ].filter(([n]) => n > 0);
+  if (used.length) out.push(dim("  Beyond the logs: " + used.map(([n, what]) => `${n} ${what}`).join(" · ")));
+
+  header("Test integrity", "worth a second look, not proof of cheating");
+  ROWS.integrity.forEach(([label, fn]) => row(label, fn, warnIfPositive));
+
+  header("Where the time went");
+  ROWS.time.forEach(([label, fn]) => row(label, fn));
+
+  header("You and the agent");
+  ROWS.you.forEach(([label, fn]) => row(label, fn));
+
+  if (sessions.unrecognized?.length) {
+    out.push("");
+    out.push(yellow(`${sessions.unrecognized.length} session file(s) are in a log format this version doesn't recognize and are not included.`) + dim(" Please report it, with your agent's version."));
+  }
+  if (sessions.skipped?.length) {
+    out.push("");
+    out.push(yellow(`${sessions.skipped.length} session file(s) couldn't be read and are not included.`) + dim(" Set POLYGRAPH_DEBUG=1 to see why."));
+  }
+
+  if (examples > 0) {
+    const all = sessions.flatMap((s) => s.findings);
+    const pick = (type) => all.filter((f) => f.type === type).sort((a, b) => b.ts - a.ts).slice(0, examples);
+    const claims = pick("claim");
+    const fixes = pick("test-only-fix");
+    const weak = pick("weakened-test");
+    const loops = pick("retry-loop");
+    const risky = pick("risky");
+    if (claims.length + fixes.length + weak.length + loops.length + risky.length) {
+      out.push("");
+      out.push(bold("Most recent examples") + dim("  (stays on your machine; --html never includes these)"));
+    }
+    for (const f of claims) {
+      out.push("");
+      out.push(`  ${red("✗")} ${bold(VERDICT_LABEL[f.detail.verdict] + (f.detail.ci ? " (CI claim)" : ""))} ${where(f)}`);
+      out.push(`    ${cyan("“" + f.detail.claim + "”")}`);
+      const lt = f.detail.lastTest;
+      if (lt) out.push(dim(`    last test: ${lt.cmd} → ${lt.outcome ?? "?"}, ${duration(lt.ago)} earlier`));
+      if (f.detail.editedAfter) out.push(dim(`    then edited: ${f.detail.editedAfter}`));
+      out.push(dim(`    ${tilde(f.file)}`));
+    }
+    for (const f of fixes) {
+      out.push("");
+      out.push(`  ${yellow("!")} ${bold("failing test made to pass by editing only tests")} ${where(f)}`);
+      out.push(dim(`    edited: ${f.detail.tests.join(", ")}`));
+      out.push(dim(`    then passed: ${f.detail.cmd}`));
+      out.push(dim(`    ${tilde(f.file)}`));
+    }
+    for (const f of weak) {
+      out.push("");
+      out.push(`  ${yellow("!")} ${bold(f.detail.reasons.join(", "))}: ${f.detail.path} ${where(f)}`);
+      if (f.detail.removed?.length) out.push(dim(`    - ${f.detail.removed.slice(0, 2).join("\n    - ")}`));
+      out.push(dim(`    ${tilde(f.file)}`));
+    }
+    for (const f of loops) {
+      out.push("");
+      out.push(`  ${yellow("↻")} ${bold("same failing command, 3+ times, nothing changed in between")} ${where(f)}`);
+      out.push(dim(`    ${f.detail.cmd}`));
+    }
+    for (const f of risky) {
+      out.push("");
+      out.push(`  ${yellow("!")} ${bold(f.detail.label)} ${where(f)}`);
+      out.push(dim(`    ${f.detail.cmd}`));
+    }
+  }
+
+  const seen = ["claude", "codex"].map((a) => [a, versionRange(a, groups[`agent:${a}`]?.versions)]).filter(([, r]) => r);
+  if (seen.length) {
+    out.push("");
+    out.push(dim("Log versions: " + seen.map(([a, r]) => `${AGENT_NAMES[a]} ${r.text}`).join(" · ")));
+    for (const [a, r] of seen) if (r.newer) out.push(yellow(`${AGENT_NAMES[a]} logs are newer than the versions this release was tested with (up to ${TESTED[a]}). If numbers look off, please report it.`));
+  }
+  out.push("");
+  out.push(dim("How each number is measured: https://github.com/EleChon-pixel/agent-polygraph#how-it-decides"));
+  out.push(dim("A verdict looks wrong? Report it (redacted): https://github.com/EleChon-pixel/agent-polygraph/issues/new/choose"));
+  out.push(dim("Share a numbers-only card: npx agent-polygraph --html"));
+  out.push(dim("Catch these as they happen: npx agent-polygraph guard --install"));
+  if (!used.length) out.push(dim("See what the logs miss: npx agent-polygraph record --install (stays offline), or --ci (asks GitHub)"));
+  out.push("");
+  return out.join("\n");
+}
+
+function where(f) {
+  const project = f.cwd ? f.cwd.split("/").filter(Boolean).pop() : "";
+  return dim(`· ${AGENT_NAMES[f.agent]} · ${day(f.ts)}${project ? " · " + project : ""}`);
+}
+
+function tilde(p) {
+  const home = os.homedir();
+  return p && p.startsWith(home) ? "~" + p.slice(home.length) : p;
+}

package/src/safe-config.js

@@ -0,0 +1,85 @@
+// Atomic, permission-preserving edits for user-owned hook and shell settings.
+// Original content is backed up outside the repository before every change.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+const statKey = (s) => [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].map(String).join(":");
+const backupRoot = () => path.join(process.env.AGENT_POLYGRAPH_HOME || path.join(os.homedir(), ".agent-polygraph"), "backups");
+
+function checkDirectory(dir, create = false) {
+  if (create) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const st = fs.lstatSync(dir);
+  if (!st.isDirectory() || st.isSymbolicLink()) throw new Error("Unsafe settings directory: " + dir);
+  // A directory owned by someone else could redirect the settings file.
+  if (process.platform !== "win32" && st.uid !== process.getuid()) throw new Error("Settings directory is not owned by this user: " + dir);
+}
+
+export function readSettings(file) {
+  let fd;
+  try {
+    const st = fs.lstatSync(file, { bigint: true });
+    if (!st.isFile() || st.nlink !== 1n) throw new Error("Unsafe settings file: " + file);
+    fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW);
+    const opened = fs.fstatSync(fd, { bigint: true });
+    if (!opened.isFile() || opened.nlink !== 1n || opened.dev !== st.dev || opened.ino !== st.ino)
+      throw new Error("Settings file changed while opening: " + file);
+    if (process.platform !== "win32" && opened.uid !== BigInt(process.getuid()))
+      throw new Error("Settings file belongs to another user: " + file);
+    const data = fs.readFileSync(fd);
+    const after = fs.fstatSync(fd, { bigint: true });
+    if (statKey(after) !== statKey(opened)) throw new Error("Settings file changed during read: " + file);
+    return { text: data.toString("utf8"), stat: after, mode: Number(opened.mode & 0o777n) };
+  } catch (e) {
+    if (e.code === "ENOENT") return { text: null, stat: null, mode: 0o600 };
+    throw e;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function backupOriginal(file, previous) {
+  if (previous.text === null) return null;
+  const dir = backupRoot();
+  checkDirectory(dir, true);
+  if (process.platform !== "win32") fs.chmodSync(dir, 0o700);
+  const id = crypto.createHash("sha256").update(path.resolve(file)).digest("hex").slice(0, 16);
+  const target = path.join(dir, id + "-" + Date.now() + "-" + crypto.randomBytes(5).toString("hex") + ".bak");
+  fs.writeFileSync(target, previous.text, { flag: "wx", mode: 0o600 });
+  return target;
+}
+
+// Never truncate the user's existing config. Write a sibling temp file, fsync,
+// and atomically rename it only after confirming the source is still unchanged.
+export function writeSettings(file, text) {
+  const parent = path.dirname(file);
+  checkDirectory(parent, true);
+  const previous = readSettings(file);
+  if (previous.text === text) return { changed: false, backup: null };
+  const backup = backupOriginal(file, previous);
+  const tmp = path.join(parent, "." + path.basename(file) + ".apg-" + crypto.randomBytes(10).toString("hex"));
+  let created = false;
+  try {
+    const fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, previous.mode);
+    created = true;
+    try {
+      fs.writeFileSync(fd, text);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const current = readSettings(file);
+    if ((previous.stat === null) !== (current.stat === null) ||
+        (previous.stat && statKey(previous.stat) !== statKey(current.stat)))
+      throw new Error("Settings changed concurrently; original not overwritten: " + file);
+    fs.renameSync(tmp, file);
+    created = false;
+    return { changed: true, backup };
+  } finally {
+    if (created) fs.rmSync(tmp, { force: true });
+  }
+}
+
+export function backupDirectory() { return backupRoot(); }

package/src/scan.js

@@ -0,0 +1,60 @@
+import * as claude from "./sources/claude.js";
+import * as codex from "./sources/codex.js";
+import { analyzeSession } from "./analyze.js";
+import { applyRecords } from "./record.js";
+
+export const SOURCES = { claude, codex };
+
+/**
+ * Discover, parse and analyze sessions.
+ * opts: { agents: ["claude","codex"], since: ms timestamp, project: substring, exclude: [id prefix or cwd substring],
+ *         roots: {claude, codex}, records: false to ignore `record` data, enrich: async (session) => void,
+ *         onProgress }
+ */
+export async function scan(opts = {}) {
+  const agents = opts.agents?.length ? opts.agents : Object.keys(SOURCES);
+  let entries = [];
+  for (const a of agents) {
+    const src = SOURCES[a];
+    entries.push(...src.discover(opts.roots?.[a] || src.defaultRoot()));
+  }
+  if (opts.since) entries = entries.filter((e) => e.mtime >= opts.since);
+
+  const results = [];
+  results.skipped = []; // session files we couldn't read: a quiet gap would look like a full audit
+  results.unrecognized = []; // files with content in a format we don't know (a new agent version?)
+  let done = 0;
+  const queue = [...entries];
+  const worker = async () => {
+    while (queue.length) {
+      const entry = queue.shift();
+      try {
+        const session = await SOURCES[entry.agent].parse(entry);
+        if (opts.project && !(session.cwd || "").includes(opts.project)) continue;
+        // --exclude: a session id prefix or a piece of its working directory
+        if (opts.exclude?.some((x) => entry.id.startsWith(x) || (session.cwd || "").includes(x))) continue;
+        if (opts.since && session.end && session.end < opts.since) continue;
+        if (session.unrecognized) {
+          results.unrecognized.push({ file: entry.files[0], agent: entry.agent });
+          continue;
+        }
+        if (!session.events.length) continue;
+        // evidence outside the logs: `record` snapshots and terminal runs (local files),
+        // then --ci (GitHub) when asked for
+        if (opts.records !== false) applyRecords(session);
+        if (opts.enrich) await opts.enrich(session);
+        results.push(analyzeSession(session));
+      } catch (err) {
+        results.skipped.push({ file: entry.files[0], error: err.message });
+        if (process.env.POLYGRAPH_DEBUG) console.error(`skip ${entry.files[0]}: ${err.message}`);
+      } finally {
+        opts.onProgress?.(++done, entries.length);
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(8, entries.length || 1) }, worker));
+  const { skipped, unrecognized } = results;
+  results.sort((a, b) => (a.start ?? 0) - (b.start ?? 0));
+  Object.assign(results, { skipped, unrecognized });
+  return results;
+}

package/src/shell/record.sh

@@ -0,0 +1,73 @@
+# agent-polygraph record: store only a recognized test-runner label, timestamps,
+# working directory and exit code. Never persist the shell command or its output.
+# Remove with: agent-polygraph record --uninstall --shell
+case $- in *i*) ;; *) return 0 2>/dev/null ;; esac
+[ -n "${CLAUDECODE:-}${CODEX_SANDBOX:-}${CODEX_THREAD_ID:-}${CODEX_MANAGED_BY_NPM:-}" ] && return 0 2>/dev/null
+
+# Substituted with an installed, persistent CLI path by record --install --shell.
+__apg_node=__APG_NODE__
+__apg_entry=__APG_ENTRY__
+__apg_runner=
+
+__apg_now() {
+  if [ -n "${EPOCHREALTIME:-}" ]; then printf '%s' "${EPOCHREALTIME/,/.}"; else date +%s; fi
+}
+__apg_esc() {
+  local s=$1
+  s=${s//\\/\\\\}; s=${s//\"/\\\"}; s=${s//$'\n'/\\n}; s=${s//$'\t'/\\t}; s=${s//$'\r'/\\r}
+  printf '%s' "$s"
+}
+__apg_pre() {
+  __apg_runner=
+  # Conservative: do not treat compound commands (e.g. npm test; true) as proof.
+  case "$1" in *';'*|*'|'*|*'&'*|*'`'*|*'$('*|*$'\n'*) return 0 ;; esac
+  local c="${1#${1%%[![:space:]]*}}"
+  case "$c" in
+    "pytest"|"pytest "*|"python -m pytest"*|"python3 -m pytest"*) __apg_runner="pytest" ;;
+    "npm test"|"npm test "*|"npm run test"|"npm run test "*|"npm run test:"*) __apg_runner="npm test" ;;
+    "node --test"|"node --test "*) __apg_runner="node --test" ;;
+    "go test"|"go test "*) __apg_runner="go test" ;;
+    "cargo test"|"cargo test "*) __apg_runner="cargo test" ;;
+    "mvn test"|"mvn test "*) __apg_runner="mvn test" ;;
+    "gradle test"|"gradle test "*|"./gradlew test"|"./gradlew test "*) __apg_runner="gradle test" ;;
+    "dotnet test"|"dotnet test "*) __apg_runner="dotnet test" ;;
+    "vitest"|"vitest "*|"jest"|"jest "*) __apg_runner="vitest run" ;;
+  esac
+  [ -n "$__apg_runner" ] || return 0
+  __apg_dir=$PWD
+  __apg_t0=$(__apg_now)
+}
+__apg_post() {
+  local s=$?
+  if [ -n "$__apg_runner" ]; then
+    # The CLI validates input and writes with O_NOFOLLOW; shell redirection
+    # cannot be used here because it would follow an attacker-created symlink.
+    printf '{"v":2,"kind":"terminal","start":%s,"end":%s,"exit":%s,"cwd":"%s","runner":"%s"}\n' \
+      "$__apg_t0" "$(__apg_now)" "$s" "$(__apg_esc "$__apg_dir")" "$__apg_runner" |
+      "$__apg_node" "$__apg_entry" record --shell-event >/dev/null 2>&1
+    __apg_runner=
+  fi
+  return $s
+}
+
+if [ -n "${ZSH_VERSION:-}" ]; then
+  autoload -Uz add-zsh-hook && add-zsh-hook preexec __apg_pre && add-zsh-hook precmd __apg_post
+elif [ -n "${BASH_VERSION:-}" ]; then
+  if [ -n "${bash_preexec_imported:-}${__bp_imported:-}" ]; then
+    preexec_functions+=(__apg_pre)
+    precmd_functions=(__apg_post "${precmd_functions[@]}")
+  elif [ -z "$(trap -p DEBUG)" ]; then
+    __apg_last=$HISTCMD
+    __apg_debug() {
+      [[ ${BASH_COMMAND:-} == __apg_* ]] && return
+      [ -n "${COMP_LINE:-}" ] && return
+      [ "$HISTCMD" = "$__apg_last" ] && return
+      __apg_last=$HISTCMD
+      local h
+      h=$(HISTTIMEFORMAT= builtin history 1)
+      [[ $h =~ ^[[:space:]]*[0-9]+[*]?[[:space:]]+(.*)$ ]] && __apg_pre "${BASH_REMATCH[1]}"
+    }
+    trap '__apg_debug' DEBUG
+    PROMPT_COMMAND="__apg_post${PROMPT_COMMAND:+;$PROMPT_COMMAND}"
+  fi
+fi