agent-polygraph 0.0.0-stage → 0.1.0

package/src/guard.js

@@ -0,0 +1,216 @@
+// `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";
+
+
+/** Hook entry point: read the Stop payload on stdin, maybe print a block decision. */
+export async function runHook(stdinText) {
+  let payload;
+  try {
+    payload = JSON.parse(stdinText || "{}");
+  } catch {
+    return null;
+  }
+  if (payload.stop_hook_active) return null; // we already sent the agent back once
+  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(" ");
+}
+
+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 });
+      fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+    }
+    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;
+    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+    return { agent, file, changed: true };
+  });
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } 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,238 @@
+// `agent-polygraph record`: optional evidence the session logs don't carry.
+//
+// - A PostToolUse hook (Claude Code and Codex). After a test command or a command that may
+//   write files, it saves a snapshot of the working tree (a git tree id, stored in
+//   agent-polygraph's own object store so your repository is never written to) and, for
+//   test commands, the outcome the runner printed in full. With snapshots, a change the
+//   logs can't follow ("a script that computes its file names") is settled by comparing the
+//   tree after the test run with the tree before the claim.
+// - 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 { execFileSync } from "node:child_process";
+import { isTestCommand, 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");
+
+// --- 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: 1, ts: Date.now(), id: p.tool_use_id || null, tool: p.tool_name || null, 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);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(rec) + "\n");
+  } 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 snapshots ---------------------------------------------------------------
+
+/**
+ * The working tree as a git tree id, untracked files included, ignored files left out.
+ * Built with a temporary index and a private object store (the repository's own objects
+ * are read through git's alternates), so nothing in the repository changes.
+ */
+export function snapshot(cwd) {
+  const git = (args, env = {}, dir = cwd) =>
+    execFileSync("git", args, { cwd: dir, env: { ...process.env, ...env }, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 8000, maxBuffer: 8 << 20 }).trim();
+  const root = git(["rev-parse", "--show-toplevel"]);
+  const [index, objects] = git(["rev-parse", "--git-path", "index", "--git-path", "objects"])
+    .split("\n")
+    .map((p) => path.resolve(cwd, p));
+  const store = path.join(home(), "objects", hash(objects));
+  fs.mkdirSync(store, { recursive: true });
+  const tmp = path.join(os.tmpdir(), `agent-polygraph-${process.pid}-${Date.now()}.index`);
+  try {
+    // starting from the real index keeps git's stat cache: only changed files are hashed
+    if (fs.existsSync(index)) fs.copyFileSync(index, tmp);
+    const env = { GIT_INDEX_FILE: tmp, GIT_OBJECT_DIRECTORY: store, GIT_ALTERNATE_OBJECT_DIRECTORIES: objects };
+    git(["add", "-A", "--ignore-errors", "--", "."], env, root);
+    const tree = git(["write-tree"], env, root);
+    return { root, tree, objects, store };
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+/** Paths (relative to the checkout) that differ between two snapshots of it. */
+export function treeDiff(a, b) {
+  const gitDir = path.dirname(a.objects);
+  const out = execFileSync("git", ["diff", "--name-only", "-z", "--no-renames", a.tree, b.tree], {
+    env: { ...process.env, GIT_DIR: gitDir, GIT_OBJECT_DIRECTORY: a.store, GIT_ALTERNATE_OBJECT_DIRECTORIES: [a.objects, b.store].join(path.delimiter) },
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 10000,
+    maxBuffer: 16 << 20,
+  });
+  return out.split("\0").filter(Boolean);
+}
+
+// --- 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: squash(r.cmd) }));
+    for (const ev of session.events) {
+      if (ev.kind !== "cmd" || ev.external) continue;
+      const key = squash(ev.cmd);
+      const k = free.findIndex((r) => r && (ev.id && r.id ? r.id === ev.id : r.key === key && 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;
+}
+
+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);
+    if (!(start >= session.start && start <= session.end) || !r.cwd || !related(r.cwd) || !isTestCommand(r.cmd)) continue;
+    const ev = { kind: "cmd", ts: start, seq: Number.MAX_SAFE_INTEGER, cmd: r.cmd, 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 SHELL_SNIPPET = () => fs.readFileSync(new URL("./shell/record.sh", import.meta.url), "utf8");
+
+const RC_FILES = () => [".bashrc", ".zshrc"].map((f) => path.join(os.homedir(), f));
+
+export function installShell() {
+  const script = shellScript();
+  fs.mkdirSync(path.join(home(), "records"), { recursive: true });
+  fs.writeFileSync(script, SHELL_SNIPPET());
+  const line = `[ -f "${script}" ] && . "${script}"  ${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 = fs.existsSync(rc) ? fs.readFileSync(rc, "utf8") : "";
+    if (text.includes(MARK)) {
+      out.push({ file: rc, changed: false });
+      continue;
+    }
+    fs.appendFileSync(rc, (text && !text.endsWith("\n") ? "\n" : "") + line + "\n");
+    out.push({ file: rc, changed: true });
+  }
+  return { script, rcs: out };
+}
+
+export function uninstallShell() {
+  const out = [];
+  for (const rc of RC_FILES()) {
+    if (!fs.existsSync(rc)) continue;
+    const text = fs.readFileSync(rc, "utf8");
+    if (!text.includes(MARK)) continue;
+    fs.writeFileSync(rc, text.split("\n").filter((l) => !l.includes(MARK)).join("\n"));
+    out.push({ file: rc, changed: true });
+  }
+  fs.rmSync(shellScript(), { force: true });
+  return { rcs: out };
+}
+
+function onPath(cmd) {
+  try {
+    execFileSync("which", [cmd], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}

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>
+`;
+}