agent-polygraph 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eleftherios Chondros
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,233 @@
-# Temporary Holding Version
+# agent-polygraph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![test](https://github.com/EleChon-pixel/agent-polygraph/actions/workflows/test.yml/badge.svg)](https://github.com/EleChon-pixel/agent-polygraph/actions/workflows/test.yml)
+
+Your coding agent said "all tests pass". Did a test pass after its last edit?
+
+agent-polygraph is an audit of your past sessions. It reads the Claude Code and Codex session logs already on your machine and checks every "tests pass" claim against what ran: was there a passing test run after the agent's last code edit? It tells you how often your agents claimed something they hadn't verified, and shows the evidence for each case. No setup, no API key, nothing uploaded.
+
+The audit and guard **read evidence; they do not execute tests**. A flagged claim is not proof the code is wrong: it means the available evidence does not support the claim at that point. If you want automatic test execution, use a separate test-running hook or CI.
+
+```sh
+npx agent-polygraph          # your own sessions
+npx agent-polygraph --demo   # generated sample sessions
+```
+
+> **Beta / evidence limitations:** The parser has been evaluated on the author's own sessions and public Claude Code traces ([evaluation](docs/evaluation.md)). Controlled replays and real executed tests exist, but **independent, blinded human-validated accuracy has not been established**. If you report a wrong verdict, [open an issue](https://github.com/EleChon-pixel/agent-polygraph/issues/new/choose) with a *manually redacted* example—never upload an unreviewed raw session log.
+
+Historical example from the author's sessions, July–October 2026 (not a representative benchmark or a current-user measurement):
+
+```
+agent-polygraph  32 working sessions · Jul 30 – Oct 31, 2026 · 11.0s
+
+"Tests pass" claims  was there a passing run after the last code edit?
+                                                    Codex  Claude Code          All
+  Backed by a fresh passing run                       243           80          323
+  No test run in the session                            0            0            0
+  Code edited after the last run                       15            5           20
+  Last run had failed                                   1            0            1
+  Couldn't tell                                        15           17           32
+  …test result unreadable                               3            1            4
+  …unresolved file change after the run                11           14           25
+  …other                                                1            2            3
+  Receipt rate                                        94%          94%          94%
+
+Test integrity  worth a second look, not proof of cheating
+  Failing test "fixed" by editing only tests            0            0            0
+  Edits that weakened an existing test                  3            1            4
+
+Where the time went
+  Test runs                                           851          976         1827
+  Time spent in tests                                3.1h         8.7h          12h
+  Full-suite runs                                     325          212          537
+  ...
+```
+
+Under the tables it prints the latest examples: what the agent claimed, the last test command and its result, what was edited afterwards, and the session file, so you can check it yourself.
+
+**What the benchmarks actually show:** agent-polygraph detects stale test claims more reliably than a *simple any-prior-pass rule* in [25 authored replay scenarios](docs/benchmark.md) (14/14 unbacked claims versus 7/14). In [12 instrumented projects using real test executions](docs/live-evaluation.md), its selective guard requested **5** additional tests and detected **3 of 7** failing final suites; rerunning the full suite every time required **12** additional tests and detected **all 7**. That is an efficiency-versus-coverage trade-off, **not** evidence that the guard improves overall defect detection. [Public-session workload projections](docs/benchmark.md) are separate from actual executed tests. The independently labeled human study is [still open](https://github.com/EleChon-pixel/agent-polygraph/issues/3).
+
+**npm release status:** The [public npm registry](https://www.npmjs.com/package/agent-polygraph) still serves **0.1.0**, while GitHub `main` contains the security-hardened **0.2.0 release candidate**. The automated tarball test passes, but new npm code will not be available to `npx` until it has been published. For the exact manual publishing procedure (GitHub OIDC trusted publisher), see [Release instructions](docs/releasing.md).
+
+## Share your numbers
+
+```sh
+npx agent-polygraph --html
+```
+
+This writes `polygraph.html`, a self-contained card with numbers only. Prompts, code, commands and file paths are left out.
+
+<img src="docs/card.png" alt="agent-polygraph report card from my own sessions" width="600">
+
+## Catch unbacked claims as they happen (optional)
+
+```sh
+npx agent-polygraph guard --install            # this project (.claude/settings.json, .codex/hooks.json)
+npx agent-polygraph guard --install --global   # every project (~/.claude, ~/.codex)
+npx agent-polygraph guard --uninstall
+```
+
+<img src="docs/guard.gif" alt="staged demo: guard stops a coding agent that claims tests pass after editing code, and the rerun fails" width="760">
+
+`guard` is a Stop hook that runs the same checks on the live session. When the agent's final message says tests pass and the session doesn't back it up, the agent is sent back once:
+
+> agent-polygraph: your final message says "All tests pass.", but you edited calc.js after the last test run. Run the relevant tests now and report the actual result. If they can't be run, say so instead of claiming they pass.
+
+It blocks at most once per stop, looks only at the final message (so a claim the agent already corrected doesn't count), stays quiet when it can't tell, and never fails the turn because of its own errors. Install it globally (`npm i -g agent-polygraph`) so the hook doesn't start `npx` on every stop.
+
+I tested it with both agents in a staged setup: they were told to edit code after a test run and then claim the tests pass (the GIF above is one of these runs). Both were stopped, reran `npm test` and reported the failure. Codex needs one extra step: it only runs hooks you have approved, and only reads a project's `.codex/` folder if you trust it. After installing, open `codex` in the project once, trust the folder and approve the hook.
+
+### Do you need it?
+
+Maybe not. Two simpler setups also work, and they are more thorough:
+
+- A Stop hook that runs your test suite after every turn and gives the agent the result. This also catches breakage when the agent doesn't claim anything.
+- A Stop hook that always asks the agent to double-check its results. When I tried this on small tasks where the agent had edited code after its last run, it reran the tests every time (6 of 6, Claude Haiku).
+
+The trade-off is cost. Both fire on every stop, so every turn ends with a test run, and the second also adds a model turn, even when nothing changed or nothing was claimed. A test-running hook also has to know each project's test command and setup (a virtualenv, environment variables, a subfolder, a database). `guard` runs nothing: it reads the session in well under a second and only sends the agent back when the final message claims a pass that no run after the last edit supports (about 6% of claims in my logs), naming the edit that made the run stale.
+
+If your suite runs in a few seconds and needs no setup, running it on every stop is the better choice. `guard` is for suites that are slow or fiddly to run, and for when you don't want an extra turn on every stop.
+
+### As a Claude Code plugin
+
+In Claude Code you can install the guard as a plugin instead:
+
+```
+/plugin install agent-polygraph --marketplace EleChon-pixel/agent-polygraph
+```
+
+On Claude Code older than 2.1.275, run `/plugin marketplace add EleChon-pixel/agent-polygraph` first, then `/plugin install agent-polygraph@agent-polygraph`.
+
+The plugin runs the same Stop hook from its own copy, so nothing is downloaded when the agent stops, and it adds `/agent-polygraph:check` for the report (it takes the same options, for example `/agent-polygraph:check --since 30d`). If you also installed the hook with `guard --install`, the plugin's copy stays quiet so the agent isn't sent back twice. The plugin doesn't include `record`; turn that on separately if you want it.
+
+## Evidence the logs don't have
+
+Some things never show up in the logs: tests you ran yourself in another terminal, CI results, and files changed by a script that builds their names at run time. Two optional extras cover them.
+
+```sh
+npx agent-polygraph record --install           # this project; add --global for all of them
+agent-polygraph record --install --shell       # your own terminals (requires a persistent install)
+npx agent-polygraph --ci                       # GitHub Actions (online)
+```
+
+`record --install` adds a PostToolUse hook to Claude Code and Codex. After a test or a command that may write files, it records the test outcome and an HMAC-fingerprinted source snapshot. The snapshot reads bounded source files without writing copies to Git or storing raw contents. Ignored and non-source files are excluded; symlinks, unreadable files and exceeded size limits make a snapshot inconclusive. Comparing snapshots can resolve scripts that modify dynamically chosen source files. All new records stay in `~/.agent-polygraph` (or `$AGENT_POLYGRAPH_HOME`). Recording starts with new sessions.
+
+`record --install --shell` adds one line to `~/.bashrc` and `~/.zshrc`. Supported test commands you run in interactive Bash/Zsh shells produce a minimal receipt: runner category, working directory, timestamps and exit code. Raw commands and output are never saved. To avoid unsafe shell redirection, the shell hook invokes the installed Node CLI, which validates and writes the receipt with private permissions and no-follow checks. **Use a persistent installation** (`npm i -g agent-polygraph` or a durable checkout) for shell integration; temporary `npx` cache paths may disappear. Shell mode recognizes a conservative subset of direct test commands. `record --uninstall --shell` removes its startup line.
+
+`--ci` goes online. Through your [`gh`](https://cli.github.com) login, it asks the GitHub API for the workflow runs of the repositories your sessions pushed to. The request contains the repository name and a date range, nothing from your sessions. A test workflow on a pushed commit counts as a test run of the code as it was at the push, so later edits still make it stale. Runs are matched to pushes by commit id, which has to appear in the session (in the push output, or from `git commit` or `git log` before it). Branch names and timing alone are not enough. With `--ci`, claims about CI itself ("CI is green", "all checks on the PR pass") are checked too. Workflows with no job or step named like a test, and runs GitHub never started, are ignored.
+
+The report shows how many claims each of these settled.
+
+## What it checks
+
+| Finding | How it's decided |
+|---|---|
+| Backed claim | The agent said tests pass and the run it refers to passed. That is the run with the count or test file the claim names; for "the full suite passes", the latest run in that folder about as large as the largest one; otherwise the latest result the agent had seen. The run must have started after the last edit to a source file in the same checkout. |
+| Code edited after the last run | A test ran, the agent then changed source code in that checkout (with an edit tool, a patch or the shell), and claimed tests pass without running them again. An edit made while the run was still going counts too. |
+| Last run had failed | The latest test result in the session showed failures. A subagent's failing run in its own worktree is "couldn't tell" instead. |
+| No test run | The agent changed code but ran nothing recognisable as a test before the claim. |
+| Couldn't tell | Left out of the receipt rate, with the reason shown: the result can't be read (piped, truncated, mixed with other output), a file changed in a way that can't be traced (a script with no file name in it, `git checkout`, `git merge`), the test was still running, a subagent's run failed in its own worktree, or nothing in the session changed code. |
+| Failing test "fixed" by editing only tests | A run failed, the agent changed a test it hadn't touched before, changed nothing else, and the next run passed. Fixing a test the agent just wrote doesn't count. Sometimes the test was wrong, so this is a flag to look at, not a verdict. |
+| Weakened an existing test | An edit to a test that existed before the session removed cases or assertions, added `skip`/`xfail`, `.only` or an always-true assertion, or deleted the file. |
+| Full-suite runs | A test command with no file, directory, node id or `-k` filter. |
+| Retry loops | The same failing command run 3 or more times in a row with no edit in between. |
+| Pushback and interrupts | Your messages that start with "no", "stop" or "revert" or contain "I told you", and turns you interrupted. |
+| Risky git | `--no-verify`, `push --force`, `reset --hard`, discarding uncommitted changes. |
+
+Background runs are followed: Claude Code's `run_in_background` results (the notification and the output file the agent reads) and Codex cells that finish later through `wait`.
+
+## How it decides
+
+Everything is deterministic pattern matching over the logs. There is no LLM involved, and the same logs always give the same numbers. When a rule is unsure, it says "couldn't tell" instead of flagging the agent.
+
+- Each command's start and its result are separate events, in the order they were observed. A claim can only be backed by a result the agent had already seen. A run covers the code as it was when the run started, so an edit during the run makes it stale.
+- In a Codex cell that runs several commands, each command gets its own output. If outputs can't be matched to commands, the result stays unknown.
+- An edit counts once it happened: a Claude Code edit after its tool result confirms it, a Codex patch if it applied. Shell writes count too (`sed -i`, redirects, `tee`, `cp`/`mv`, scripts that write named files), placed by the `cd` in effect where they appear.
+- A script's writes are the files it clearly writes, such as `open('x.py', 'w')`, `Path('x.py').write_text(...)`, `writeFileSync('x.js', ...)`, or a variable holding such a path that is written later. Files it only reads don't count. A write to a file it can't name (a loop over paths, `extractall`, `shutil.copy` to a variable) makes the claim "couldn't tell".
+- An edit in one checkout or worktree doesn't make a run in another one stale. Only edits to source files count; docs, config, data, generated output and hidden tool folders don't.
+- `tail pytest.log` is evidence about the run that wrote `pytest.log`, not a new run.
+- Results come from the runner's summary line first (`3 failed, 10 passed in 1.2s`, `Tests: 1 failed`, `test result: FAILED`). An exit code is trusted only when the test ran last (`cd app && pytest`, `ruff check .; pytest`) or a plain `&&` chain exited 0. `npm test; true` exits 0 because of `true`.
+- Commands refused by a permission prompt, the auto-mode classifier or a hook never ran, so they aren't test runs.
+- A claim is a sentence like "all tests pass" or "62 passed". Plans ("I'll make sure the tests pass"), conditions ("once tests pass"), history ("the latest recorded run passed"), questions, partial results ("58 of 59 pass") and quoted runner output are ignored. English is supported, plus simple forms in Greek, Spanish, Portuguese, German, French and Italian.
+- Subagent transcripts are merged into the parent session, so a subagent's passing run backs the parent's claim.
+- Tests the agent created in the same session can't be "weakened". A Claude Code `Write` over an existing test is an overwrite, so it can.
+- `guard` judges only the final message. "Correction: I did not run the tests" after an earlier claim doesn't trigger a block.
+
+The rules are in [`src/classify.js`](src/classify.js) and the tests in [`test/`](test), including a labelled set of claim and non-claim sentences ([`test/claims.corpus.test.js`](test/claims.corpus.test.js)). A false positive or a missed claim makes a good [issue](https://github.com/EleChon-pixel/agent-polygraph/issues/new/choose); include the redacted sentence and it goes into that set.
+
+## Validation and accuracy
+
+The historical analysis of the author's own Claude Code and Codex sessions includes manual spot checks of claims and flagged evidence. In a small, author-selected review, approximately 95% of 25 detected claim candidates were genuine claims, and a separate sample suggested some real claims were missed. **These are preliminary, author-reviewed observations, not externally validated precision or recall.** See the [original evaluation protocol](docs/evaluation.md).
+
+The public Claude Code evaluation reviewed 26 parsed sessions and identified 24 backed claims and three stale findings (one confirmed and two considered likely). It is useful for parser regression coverage but does **not** establish accuracy on an independent, representative population. A separately pinned, redacted holdout audit inspected 103 public sessions; under its conservative automated reference rules, **no eligible claims were found**, so **no holdout accuracy percentage was produced**. Additional dataset limitations and exact counts are documented in [live-evaluation.md](docs/live-evaluation.md).
+
+Two reproducible controlled experiments test narrower propositions:
+
+- [Stop-hook replay](docs/benchmark.md): 25 authored Claude Code/Codex scenarios. Agent-polygraph correctly blocked 14/14 labeled unbacked claims versus 7/14 for a naive “any test passed earlier” hook, with zero false blocks in these selected cases.
+- [Executed-test policy comparison](docs/live-evaluation.md): 12 authored scenarios with actual Node.js test executions. The selective guard required five extra test executions and detected three of seven failing final suites; running the full suite after every response required 12 executions and detected all seven.
+
+The replay labels and scenarios were constructed by the project authors. The guard cannot discover failures the agent never claimed away, or infer whether a narrow passing test establishes a full-suite pass. **An independent, blinded human evaluation is still needed.** The [review issue](https://github.com/EleChon-pixel/agent-polygraph/issues/3) describes the protocol; `scripts/blind-review.mjs` prepares prediction-free review packets. No raw private session logs should be shared with reviewers or issues without permission and redaction.
+
+## Limits
+
+These are the gaps that remain. `record` and `--ci` can reduce some of them, but neither replaces running tests or provides independent proof of correctness.
+
+- Tests outside the logs. Tests the agent ran, test runs Claude Code recorded from hooks, commands you typed with `!` in Claude Code, and test output you pasted into the chat all count. So do your own bash and zsh runs with `record --shell`, and GitHub Actions runs on pushed commits with `--ci`. Other shells (fish, PowerShell, an IDE's test button), other CI services, and CI runs on commits the session never printed are still invisible.
+- "The full suite passes" is compared with the latest run about as large as the largest one in that folder, using the counts the runner printed. If no run printed a count, it's compared with the latest run, which may have been narrower. Claims that name no count, test file or full suite are compared with the latest run.
+- Output with no summary. Codex keeps each command's full output. Claude Code may save long output to a separate file that the analyzer reads if it still exists. New `record` entries retain **parsed test outcomes and pass counts, not raw test output**. A run abandoned before printing a result leaves nothing to read.
+- Files a script names at run time. Without `record` these make a claim "couldn't tell", never "backed". `record` settles them, but only in git checkouts and only for sessions after it was installed.
+- New agent versions can change the log format. Supported: Claude Code 2.x (Bash and PowerShell tools; Linux, macOS and Windows paths) and Codex CLI. The report lists the versions it read, warns about newer ones, and counts files it couldn't parse instead of dropping them silently.
+- Unbacked is not the same as false. "Code edited after the last run" means the claim wasn't verified after the edit; the edit may have been harmless, such as a comment or a test file. The report can't tell whether the tests would have passed, because nobody ran them at that point.
+- The numbers describe your sessions, projects and prompts. They are not a benchmark of the models.
+
+## Options
+
+```
+--since <when>      only sessions since a date (2026-10-01) or age (7d, 4w, 3m)
+--project <text>    only sessions whose working directory contains <text>
+--exclude <text>    skip sessions whose id starts with, or whose working directory contains, <text> (repeatable)
+--agent <name>      claude or codex (repeatable; default: both)
+--by <col>          compare by "agent" (default) or "model"
+--examples <n>      examples to show per finding type (default 3, 0 to hide)
+--html [file]       write a numbers-only report to share (default polygraph.html)
+--json              full results as JSON: findings, unclear reasons, unreadable files (keep it local)
+--ci                also use GitHub Actions results (goes online, through your gh login)
+--claude-dir <dir>  Claude Code projects dir (default ~/.claude/projects, or $CLAUDE_CONFIG_DIR/projects)
+--codex-dir <dir>   Codex sessions dir (default ~/.codex/sessions, or $CODEX_HOME/sessions)
+```
+
+## Running the repository version
+
+The GitHub source and the npm-distributed package are different delivery paths. To try the **current `main` code** without assuming npm is up to date:
+
+```sh
+git clone https://github.com/EleChon-pixel/agent-polygraph.git
+cd agent-polygraph
+node bin/polygraph.js --demo
+npm test
+npm run benchmark:replay
+npm run benchmark:live
+```
+
+Before distributing a new version, verify `npm view agent-polygraph version`, the published tarball (`npm pack --dry-run`), and that a clean install really contains the latest privacy and guard fixes. The repository declares version `0.2.0` as the **next release candidate**; until it is published, `npx agent-polygraph` still installs the older public registry version. A green GitHub Actions badge does **not** prove npm has been updated.
+
+## Privacy
+
+New recordings intentionally minimize local data. The agent hook stores a keyed command fingerprint, the runner's result and optional fingerprints of source files. It does **not** save raw command text, test output or copies of repository files in its snapshot store. The shell integration saves only a recognized test-runner category, time, folder and exit code. Local record files, key and snapshot metadata are owner-only on Unix. Hook settings and shell startup files are replaced atomically, preserving their permissions and creating private recovery backups under `~/.agent-polygraph/backups` (see [recovery](docs/releasing.md#recovery-for-installed-hooks)). The secret fingerprint key is stored in `$AGENT_POLYGRAPH_HOME/record-key` (default `~/.agent-polygraph/record-key`).
+
+**Existing installations:** records made before this update may still include full commands, and older versions may have created a local Git object store with duplicate source contents. Upgrading does **not** remove those files. After reviewing whether you still need the historical evidence, uninstall recording and manually remove the old `~/.agent-polygraph/records` and `~/.agent-polygraph/objects` directories. Removing historical records means those sessions will lose their supplemental evidence; the original Claude Code/Codex transcripts remain untouched. Do not delete `record-key` while retaining version 2 records that rely on matching fingerprints.
+
+Stored fingerprints are **not** a guarantee of anonymity: recording metadata includes timestamps, working directories and relative source-file paths, and existing v1 records may still contain raw commands. The original Claude Code/Codex transcripts can also contain secrets and confidential data. The terminal report and `--json` may quote transcript text and paths; do not share them without review. The `--html` report intentionally excludes excerpts, prompts, commands and paths. The recorder only supports bounded source-file snapshots in Git checkouts and skips symbolic links; when evidence cannot be read it must stay inconclusive rather than certifying a pass. New source-file fingerprints include relative filenames and are not an anonymization guarantee.
+
+
+It reads files and works offline. These operations are opt-in:
+
+- `guard` and `record` edit the hook config files they print when you install or uninstall them, and `record --shell` adds or removes one marked line in `~/.bashrc` and `~/.zshrc`.
+- `record` saves snapshots and logs in `~/.agent-polygraph`.
+- `--ci` contacts api.github.com through `gh` and sends repository names and date ranges.
+
+The terminal report and `--json` include excerpts from your sessions. `--html` doesn't.
+
+## License
+
+MIT

package/bin/polygraph.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { createRequire } from "node:module";
+import { scan } from "../src/scan.js";
+import { aggregate } from "../src/analyze.js";
+import { renderTerminal } from "../src/report/terminal.js";
+import { renderHtml } from "../src/report/html.js";
+
+const { version } = createRequire(import.meta.url)("../package.json");
+
+if (process.argv[2] === "guard") {
+  await guard(process.argv.slice(3));
+  process.exit(0);
+}
+if (process.argv[2] === "record") {
+  await record(process.argv.slice(3));
+  process.exit(0);
+}
+
+const HELP = `agent-polygraph ${version}
+Check what your coding agents claimed against what actually ran.
+Reads Claude Code and Codex session logs on this machine. Nothing is uploaded
+(except with --ci, which asks GitHub for your workflow results).
+
+Usage: npx agent-polygraph [options]
+
+  --since <when>      only sessions since a date (2026-10-01) or age (7d, 4w, 3m)
+  --project <text>    only sessions whose working directory contains <text>
+  --exclude <text>    skip sessions whose id starts with, or whose working directory
+                      contains, <text> (repeatable)
+  --agent <name>      claude or codex (repeatable; default: both)
+  --by <col>          compare by "agent" (default) or "model"
+  --examples <n>      examples to show per finding type (default 3, 0 to hide)
+  --html [file]       write a numbers-only report to share (default polygraph.html)
+  --json              print full results as JSON (findings, unclear reasons, unreadable files; keep it local)
+  --ci                also use GitHub Actions results (goes online: asks the GitHub API,
+                      through your \`gh\` login, about the repositories your sessions pushed to)
+  --demo              run on generated sample sessions instead of yours
+  --claude-dir <dir>  Claude Code projects dir (default ~/.claude/projects)
+  --codex-dir <dir>   Codex sessions dir (default ~/.codex/sessions)
+  -h, --help          show this help
+  -v, --version       show the version
+
+Guard (stop unbacked "tests pass" claims as they happen):
+
+  npx agent-polygraph guard --install            add a Stop hook to this project (.claude/, .codex/)
+  npx agent-polygraph guard --install --global   add it for every project (~/.claude, ~/.codex)
+  npx agent-polygraph guard --uninstall [--global]
+      --agent claude|codex   only that agent's config
+
+Record (more evidence than the logs carry; stays on this machine):
+
+  npx agent-polygraph record --install [--global]   hook that snapshots the working tree after test
+                                                    and file-writing commands (.claude/, .codex/)
+  npx agent-polygraph record --install --shell      log test commands you run in your own terminals
+                                                    (bash, zsh; time, folder, exit code; no output)
+  npx agent-polygraph record --uninstall [--global] [--shell]
+`;
+
+async function record(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      install: { type: "boolean" },
+      uninstall: { type: "boolean" },
+      global: { type: "boolean" },
+      shell: { type: "boolean" },
+      "shell-event": { type: "boolean" },
+      agent: { type: "string", multiple: true },
+      command: { type: "string" },
+    },
+  });
+  const rec = await import("../src/record.js");
+  if (values["shell-event"]) {
+    const chunks = [];
+    for await (const piece of process.stdin) chunks.push(piece);
+    rec.runShellRecord(Buffer.concat(chunks).toString("utf8"));
+    return;
+  }
+  if (!values.install && !values.uninstall) {
+    // invoked by the agent as a PostToolUse hook: quiet, and never in the way
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    rec.runRecordHook(Buffer.concat(chunks).toString("utf8"));
+    return;
+  }
+  const { install, uninstall } = await import("../src/guard.js");
+  const opts = { sub: "record", agents: values.agent?.length ? values.agent : ["claude", "codex"], global: values.global, command: values.command };
+  // --shell alone touches only the shell setup
+  const hooks = values.shell ? [] : values.install ? install(opts) : uninstall(opts);
+  for (const r of hooks) {
+    const verb = values.install ? (r.changed ? "added PostToolUse hook to" : "already installed in") : r.changed ? "removed PostToolUse hook from" : "nothing to remove in";
+    console.log(`${r.agent === "claude" ? "Claude Code" : "Codex"}: ${verb} ${r.file}`);
+    if (r.backup) console.log(`  Recovery backup: ${r.backup}`);
+  }
+  if (values.shell) {
+    const out = values.install ? rec.installShell() : rec.uninstallShell();
+    for (const r of out.rcs) {
+      console.log(`Shell: ${values.install ? (r.changed ? "added a line to" : "already in") : "removed the line from"} ${r.file}`);
+      if (r.backup) console.log(`  Recovery backup: ${r.backup}`);
+    }
+    if (values.install) console.log(`Shell: ${out.rcs.length ? "open a new terminal to start logging" : "no ~/.bashrc or ~/.zshrc found; source " + out.script + " from your shell's startup file"}. Only interactive bash and zsh are supported.`);
+  }
+  if (values.install) {
+    console.log(`\nRecords are kept in ${rec.home()} and never leave this machine.`);
+    if (hooks.length) {
+      console.log(`Hook command: ${hooks[0].command}`);
+      console.log("Snapshots start with the next session; earlier sessions are read as before.");
+      if (hooks.some((r) => r.agent === "codex")) console.log("Codex: run `codex` once and approve the new hook when it says it needs review; until then Codex skips it.");
+    }
+  }
+}
+
+async function guard(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      install: { type: "boolean" },
+      uninstall: { type: "boolean" },
+      global: { type: "boolean" },
+      agent: { type: "string", multiple: true },
+      command: { type: "string" },
+      "from-plugin": { type: "boolean" },
+    },
+  });
+  const { runHook, install, uninstall } = await import("../src/guard.js");
+  if (!values.install && !values.uninstall) {
+    // invoked by the agent as a Stop hook; never fail the agent's turn
+    try {
+      const chunks = [];
+      for await (const c of process.stdin) chunks.push(c);
+      const out = await runHook(Buffer.concat(chunks).toString("utf8"), { plugin: values["from-plugin"] });
+      if (out) process.stdout.write(JSON.stringify(out));
+    } catch (e) {
+      if (process.env.POLYGRAPH_DEBUG) console.error(e);
+    }
+    return;
+  }
+  const opts = { agents: values.agent?.length ? values.agent : ["claude", "codex"], global: values.global, command: values.command };
+  const results = values.install ? install(opts) : uninstall(opts);
+  for (const r of results) {
+    const verb = values.install ? (r.changed ? "added Stop hook to" : "already installed in") : r.changed ? "removed Stop hook from" : "nothing to remove in";
+    console.log(`${r.agent === "claude" ? "Claude Code" : "Codex"}: ${verb} ${r.file}`);
+    if (r.backup) console.log(`  Recovery backup: ${r.backup}`);
+  }
+  if (values.install) {
+    console.log(`\nHook command: ${results[0].command}`);
+    console.log("When a final message says tests pass without a passing run after the last edit, the agent is asked once to rerun them.");
+    if (results.some((r) => r.agent === "codex")) {
+      console.log(
+        values.global
+          ? "Codex: run `codex` once and approve the new hook when it says it needs review; until then Codex skips it."
+          : "Codex: run `codex` once in this project, trust the folder, and approve the new hook when it says it needs review; until then Codex skips it.",
+      );
+    }
+  }
+}
+
+let args;
+try {
+  args = parseArgs({
+    allowPositionals: false,
+    options: {
+      since: { type: "string" },
+      project: { type: "string" },
+      exclude: { type: "string", multiple: true },
+      agent: { type: "string", multiple: true },
+      by: { type: "string", default: "agent" },
+      examples: { type: "string", default: "3" },
+      html: { type: "string" },
+      json: { type: "boolean" },
+      demo: { type: "boolean" },
+      ci: { type: "boolean" },
+      "claude-dir": { type: "string" },
+      "codex-dir": { type: "string" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+    // `--html` with no value
+    strict: true,
+    tokens: false,
+    args: process.argv.slice(2).flatMap((a, i, arr) => (a === "--html" && (!arr[i + 1] || arr[i + 1].startsWith("-")) ? ["--html", "polygraph.html"] : [a])),
+  }).values;
+} catch (e) {
+  console.error(`${e.message}\n\n${HELP}`);
+  process.exit(2);
+}
+
+if (args.help) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+if (args.version) {
+  console.log(version);
+  process.exit(0);
+}
+
+const agents = args.agent?.map((a) => a.toLowerCase());
+if (agents?.some((a) => !["claude", "codex"].includes(a))) {
+  console.error("--agent must be claude or codex");
+  process.exit(2);
+}
+if (!["agent", "model"].includes(args.by)) {
+  console.error('--by must be "agent" or "model"');
+  process.exit(2);
+}
+
+const since = parseSince(args.since);
+if (args.since && !since) {
+  console.error(`Can't read --since ${args.since}; use a date like 2026-10-01 or an age like 7d`);
+  process.exit(2);
+}
+
+const started = Date.now();
+const progress = process.stderr.isTTY && !args.json;
+let roots = { claude: args["claude-dir"], codex: args["codex-dir"] };
+let demoDir;
+if (args.demo) {
+  const { makeDemo } = await import("../src/demo.js");
+  const d = makeDemo();
+  demoDir = d.root;
+  roots = { claude: d.claudeDir, codex: d.codexDir };
+}
+let ci = null;
+if (args.ci && !args.demo) {
+  const { checkGh, makeCi } = await import("../src/ci.js");
+  try {
+    await checkGh();
+    ci = makeCi();
+    console.error("--ci: asking GitHub (api.github.com, through your gh login) for workflow runs of the repositories your sessions pushed to. Only repository names, branches and dates are sent.");
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+}
+const sessions = await scan({
+  agents,
+  since,
+  project: args.project,
+  exclude: args.exclude,
+  roots,
+  records: !args.demo,
+  enrich: ci ? ci.enrich : undefined,
+  onProgress: progress ? (done, total) => process.stderr.write(`\rReading sessions… ${done}/${total}`) : undefined,
+});
+if (progress) process.stderr.write("\r\x1b[K");
+const groups = aggregate(sessions);
+const seconds = (Date.now() - started) / 1000;
+if (demoDir) fs.rmSync(demoDir, { recursive: true, force: true });
+
+if (args.json) {
+  process.stdout.write(JSON.stringify({ version, groups, sessions, skipped: sessions.skipped, unrecognized: sessions.unrecognized }, null, 2) + "\n");
+} else {
+  console.log(renderTerminal({ sessions, groups, seconds, by: args.by, examples: Math.max(0, Number(args.examples) || 0), demo: args.demo }));
+}
+
+if (args.html) {
+  const file = path.resolve(args.html);
+  fs.writeFileSync(file, renderHtml({ groups, by: args.by, version, demo: args.demo, skipped: sessions.skipped?.length || 0, unrecognized: sessions.unrecognized?.length || 0 }));
+  console.error(`Wrote ${file}`);
+}
+
+function parseSince(s) {
+  if (!s) return null;
+  const rel = /^(\d+)\s*([dwmy])$/i.exec(s.trim());
+  if (rel) {
+    const days = { d: 1, w: 7, m: 30, y: 365 }[rel[2].toLowerCase()] * Number(rel[1]);
+    return Date.now() - days * 86400000;
+  }
+  const t = Date.parse(s);
+  return Number.isNaN(t) ? null : t;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "agent-polygraph",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Check your coding agents' \"tests pass\" claims against what actually ran. Reads Claude Code and Codex session logs locally.",
+  "type": "module",
+  "bin": {
+    "agent-polygraph": "bin/polygraph.js",
+    "polygraph": "bin/polygraph.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/polygraph.js",
+    "benchmark:demo": "node scripts/benchmark.mjs --demo",
+    "benchmark:replay": "node scripts/benchmark-guard-replay.mjs",
+    "benchmark:live": "node scripts/benchmark-live.mjs"
+  },
+  "engines": {
+    "node": ">=18.3"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "coding-agents",
+    "ai-agents",
+    "testing",
+    "audit",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EleChon-pixel/agent-polygraph.git"
+  },
+  "homepage": "https://github.com/EleChon-pixel/agent-polygraph#readme",
+  "bugs": "https://github.com/EleChon-pixel/agent-polygraph/issues",
+  "author": "Eleftherios Chondros"
+}