test/ — suites & fixtures

Tests are plain Node scripts (no framework). Each prints PASS/FAIL [name] and exits non-zero on failure. Run one directly: node test/spawn.test.js. All eight run via pnpm run lint.

Suites: safety (flag contract), shell-quote, env-guard (secret matcher), spawn (review.js integration), answer (answer-file extraction / SECOND_OPINION_RESULT JSON), agent (bin/agent.js integration — task delegation, --unrestricted gate, change reporting, SECOND_AGENT_RESULT JSON), locate (canonical runner-discovery snippet drift), host-parity (host set == harness set). New test files must be added to the lint script in package.json.

safety.test.js

Parses bin/review.js's SAFETY_FLAGS map by regex, so those entries must stay simple string literals (no spreads/computed values). It checks each harness's required safety flags AND functional flags — when you add a new functional flag (e.g. --trust, --skip-trust), add it to requiredFunctionalFlags or the test won't guard it.

Fixtures (test/fixtures/<harness>)

Fake harness binaries put on PATH during tests, controlled by env vars:

• FAKE_BEHAVIOR — ok / silent N / hang / probe N / empty / noenvelope / echo-stdin / model-unavailable (codex fixture: fail when -m/--model is present, succeed otherwise) / malformed-marker (codex fixture: open marker with only two >, e.g. <<<SECOND_OPINION_START>>, near-miss on the open side only) / malformed (codex fixture: BOTH open and close markers use only two </> each — exercises tolerant-regex answer extraction on the close marker too) / double (codex fixture: emits two complete envelope pairs with different payloads, modeling a harness that echoes/duplicates output — answer extraction must keep the LAST pair) / empty-final-pair (codex fixture: real pair then a complete-but-EMPTY pair — extraction must fall back to the last NON-EMPTY pair) / stray-start (codex fixture: bare START marker echoed mid-reasoning, then the real pair — backward pairing must return the clean payload only) / echo-instructions (codex fixture: real own-line pair, then an instruction sentence with both markers INLINE — line-anchored extraction must keep the real payload) / inline-only (codex fixture: ONLY the inline instruction sentence, no own-line pair — no extractable answer, exit 3 when a log file is in use) / zero-payload (codex fixture: payload is the falsy string 0 — must still count as an answer) / big N (codex fixture: ~N MB payload ending in BIG_PAYLOAD_END_MARKER — exercises review.js's synchronous stdout flush of the --print-answer echo + result line) / write-file (codex fixture: writes a file into the current working directory — i.e. --cwd, since the child inherits it — at the relative path named by $FAKE_WRITE_FILE, then envelope + exit 0; models an unrestricted agent.js run that completed a task and left a real change on disk) / write-file-noenvelope (codex fixture: same file write as write-file, but the output is plain text WITHOUT the envelope markers — exercises agent.js's "NO REPORT" warning path) / commit-noenvelope (codex fixture: git add -A && git commit in the current working directory, moving HEAD, then plain text WITHOUT the envelope markers — porcelain comes back clean even though real work happened; exercises agent.js's verdict counting HEAD movement as a change) / delete-file (codex fixture: deletes the tracked file at $FAKE_WRITE_FILE, then envelope + exit 0 — exercises change-reporting's D → deleted classification; also reused against a never-git added path to model deleting an ALREADY-UNTRACKED file — a before-only path (?? in BEFORE, absent from AFTER) that diffPorcelain must classify deleted, not drop) / delete-file-noenvelope (codex fixture: same delete as delete-file, but plain text WITHOUT the envelope markers — used against an already-untracked path to exercise "no envelope, but a before-only vanished path is still real work" → exit 0 + NO REPORT, never a false exit 3) / revert-file (codex fixture: git checkout -- $FAKE_WRITE_FILE in the current working directory, reverting it to its committed content, then envelope + exit 0 — models reverting an ALREADY-DIRTY tracked file back to exactly what's committed: a before-only path, dirty in BEFORE and absent from AFTER since it's byte-identical to HEAD again, that diffPorcelain must classify modified, not drop) / start-only (codex fixture: emits ONLY the START marker — no END, no payload — then exit 0; exercises agent.js's strict no-log-file envelope watcher, which must NOT treat a lone START marker as usable, unlike review.js's unchanged loose presence-only streaming check; also used with a read-only --log=<path> to exercise the same strict rule on the async log-stream-open-failure fallback, since agent.js always requests the strict watcher now) / large-then-envelope (codex fixture: ~5MB of plain padding with no markers, then a real small envelope pair, then exit 0 — exercises the strict envelope watcher's ~4MB tail-cap truncation design: a real pair at the very end of the stream must still extract even though the padding pushed the total past the cap) / hang-grandchild (codex fixture: spawns a plain, non-detached grandchild that appends a timestamp to $FAKE_PROBE_FILE every ~200ms, then hangs like hang — exercises run.js's timeout kill tearing down the whole process GROUP, not just its direct child)
• FAKE_ARGV_FILE — fixture dumps its argv here, so tests assert which flags review.js/agent.js forwarded
• FAKE_WRITE_FILE — path (resolved against the child's cwd) that the write-file/write-file-noenvelope codex behaviors write to; used by test/agent.test.js's change-reporting tests
• FAKE_PROBE_FILE — START/END timestamps for concurrency (parallel vs serial) tests
• FAKE_OPENCODE_HELP — opencode fixture: what the opencode run --help capability probe (argv EXACTLY run --help) prints: unset/nodir (clean help, no --dir flag line, models v2.2.1) / dir (adds a --dir flag line on stdout) / stderr-dir (the --dir flag line on stderr only, stdout empty) / prose-dir (--dir only mid-line in prose) / directory-flag (only a --directory flag line) / alias-long ( --dir, -d string Directory to run in on stdout — long flag first, aliased; counts as advertised) / alias-short ( -d, --dir string Directory to run in on stdout — short alias first; counts as advertised) / error (exit 2, no output) / hang (never exits within a test; probe timeout must kill it). Probes never write FAKE_ARGV_FILE; any other argv keeps the normal argv-dump + envelope behavior.
• FAKE_HELP_LOG — opencode fixture: when set, each probe appends its argv (newline-joined + trailing newline) here, so tests assert the probe ran as exactly run\n--help\n

test/fixtures/claude is a minimal fixture (argv dump + fixed envelope-wrapped ok output, no FAKE_BEHAVIOR support) — mirrors cmd/agent/agy/gemini. Added for test/agent.test.js's per-harness argv-shape assertions since no claude fixture previously existed (test/spawn.test.js/test/answer.test.js only ever exercise the harness surface through the codex fixture).

A compliant fixture must wrap its output in <<<SECOND_OPINION_START>>> … <<<SECOND_OPINION_END>>> — otherwise review.js treats it as no-usable-output and exits 3, failing unrelated tests. chmod +x new fixtures.

Caveat: the argv dump is newline-joined and the helper re-splits on \n, so a multi-line prompt argument spreads across array entries — rejoin with argv.join('\n') for content assertions (not just argv[last]).