Verify pstack

pstack's surface is what a Claude Code session receives from poteto-mode/hooks/pstack-hook.mjs and the skills. Proof means starting real headless sessions and reading what landed in their transcripts. The judge reads the transcripts itself, but it shares the gate's read counting, skip parsing and data-shape pattern from rules.mjs and toAction and SOURCE_FILE from trace.mjs, so a bug there can pass both. The mutation fixtures in scripts/judge.test.js guard that shared code.

~/.claude/skills links into one checkout, and a headless session run from anywhere sees that checkout's files. To verify a branch, check it out in the checkout the link serves. The Doctor prints which checkout that is.

Launch

Nothing to start. A drive spawns its own sessions, and they exit when their turn ends.

Doctor

Answers "is this install worth driving?" in under a minute. Run from the repo root.

node skills/verify-pstack/scripts/doctor.mjs
node skills/poteto-mode/scripts/check-port.mjs skills agents
node --test $(git ls-files '*.test.js')
node scripts/drift.mjs --check

doctor.mjs checks that ~/.claude/settings.json carries each hook registration in install.json exactly, carries its env keys, links each agent (pstack-reader among them) into the served checkout, and that ~/.claude/pstack/hook-errors.log is absent or empty. Every line must read ok. The other three print 0 findings, all tests ok, and DRIFT.md is current. Fix anything else before driving.

Drive

bash skills/verify-pstack/scripts/drive.sh

drive.sh --settings <file> adds <file> to every session's settings, so a branch's hook registrations run without parking the live checkout, beside the live hooks the user settings still load.

It runs three headless sessions in parallel, in about two minutes:

• mode (opus). /poteto-mode <task> piped on stdin, where the task is a one-line bug in a seeded scratch repo. Nothing names a playbook.
• control (haiku). One prompt, no slash command.
• reader (haiku). Spawns a haiku pstack-reader and tells it to run echo x > <scratch>/f.

scripts/judge.mjs then prints one verdict per file in features/: hook-context, mode-reminder, step-ledger, gate, action-gate, reader, task-tools. The drive adds port-clean. Each feature file says what its verdict asserts and which session it reads.

Evidence

Everything lands under pstack-verify/<UTC timestamp>/ in the temp directory, $TEMP on Windows and ${TMPDIR:-/tmp} on macOS and Linux: each session's stream (<role>.stream.jsonl) and transcript (<role>.jsonl), the reader's subagent transcripts, the mode session's final reply, the port-clean outputs, and verdicts.txt. Each verdict names the file and line that prove it. A verdict is VERIFIED, NOT VERIFIED, or INCONCLUSIVE, and INCONCLUSIVE is not a pass. The script exits 1 unless every verdict is VERIFIED.

Each session runs under a 540 s deadline, through timeout or gtimeout where one is installed and scripts/deadline.mjs otherwise. A session that hits it leaves <role>.timeout holding the seconds, and the judge reports every feature read from that session as INCONCLUSIVE <feature> <role> session timed out after <n> s instead of judging its partial transcript. Any other non-zero exit is recorded in <role>.exit.

Cleanup

The three seeded working directories live under ~/.claude/pstack/verify/, one per role, named pstack-verify-<timestamp>-<role>. They sit outside the temp directory because the action gate treats anything under it as scratch, and a scratch edit never meets the design ask.

drive.sh --clean <timestamp> removes that drive's three scratch directories under ~/.claude/pstack/verify/ and the three project directories under ~/.claude/projects/ whose names end in -pstack-verify-<timestamp>-mode, -control and -reader. The evidence directory and the rest of ~/.claude/pstack/ stay.

Helpers

• scripts/doctor.mjs checks the install.
• scripts/drive.sh runs the sessions and the port checks.
• scripts/deadline.mjs <seconds> <command>... runs a command under a deadline where no timeout exists, kills its process tree when it runs late, and exits 124.
• scripts/judge.mjs <evidence dir> prints the session verdicts, so a saved drive can be judged again.