Add a local Claude review worker for essential pull request heads

[seathatflowsinourveins]

Scope

• What this PR changes: it adds a local Claude review worker, tools/claude-review-worker/.
  • A systemd user timer reviews each essential pull request head of us-equities-trading and native-agent-stack with Claude Code headless (Opus 5.5 at max) on an Anthropic API key.
  • It posts a claude-review/local commit status. On the private repository it also posts one sanitized comment.
• Base commit: 86fa38442 (rebased from 8c95a50d1 after Regenerate the final-stack manifest after #1018 changed one of its sources #1025 landed; all 18 commits patch-identical, manifests/evidence.json taken from main and re-registered per commit). The first rebase, from the PR's earlier base b0b4b1097, is under "Rebase corrections".
• Lane: lane:foundation.
• Owned paths touched:
  • tools/claude-review-worker/** (new);
  • tests/test_claude_review_worker.py (new);
  • docs/decisions/2026-10-09-claude-review-worker.md (new);
  • docs/github-automation.md (a section);
  • manifests/evidence.json.

How it works:

• Key: the repository's credential runner injects the key. The chain is srt (the network boundary, started without the key) → credential_run.py → bwrap → the pinned claude binary. The key is never in argv, a unit property or a file.

• Sandbox: bubblewrap with no home directory, gh login or key store. Main's checkout is the working directory, read-only; the head (pr-head/) and the diff are data.

• Instruction fence: CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 in every session, plus --restricted, --setting-sources user and --permission-mode dontAsk. Only Read, Glob and Grep are available. Hooks, plugins and MCP are off.

• Spend: each run is debited (CRW) in the api-actions ledger before it starts. Each review is bounded at $11, the day at $55. Keys fill first, in the owner's order (api-4, api-3, api-2, api-5, anthropic-api, then api-6 to api-10; api-2 third since the owner's direction of 2026-10-11): the worker stays on a key until Anthropic reports it out of credit (402, or 400 credit too low) or revoked (401), skips a slot the credential runner refuses before any debit, and writes a switch row for each move.

• Upstream alignment: every trading head gets the upstream-alignment rule (the command center's ruling of 2026-10-10 00:15Z). Each claim about external behaviour must cite its upstream source at a pin; an uncited or deviating claim is an [upstream] finding.

• Security review: a Claude security-reviewer pass found three Medium issues, all fixed in 2acade9.

  • Head-derived citation labels were placed in the prompt's instructions; they now go to a data file.
  • The private-repository comment could render images and links; the findings now sit in a code fence that cannot be closed.
  • The gate did not cover the worker or the credential inventory; both are now essential paths, with the command center's additions.
  • Residual risks R1 to R3 are recorded as accepted boundaries.

• After the GPT read at 4b8027b (CHANGES_REQUESTED, seven P2): all seven are fixed in forward commits.

  • P2-1: the pull request is read just before each POST; a moved or closed head marks what is unsent superseded, and a move after posting adds a superseded line to the comment.
  • P2-2: each POST is saved as sending first; a retry first finds the commit's latest claude-review/local status and this attempt's comment (a hidden marker line) by the same gh login, so a lost reply or a stopped tick never posts twice.
  • P2-4: a stream with lines but no readable record is unreadable_stream: the reservation settles as unknown and the attempt counts.
  • P2-5: a settle or void needs the ref's open debit, under the ledger lock (the harness's _open_debit); recovery leaves a ref another writer closed.
  • P2-6: L7, L8 and L9 name their required calls (7, 2 and 6) and fail when any call or result is missing or a required denial is answered.
  • P2-7: the decision record paraphrases the routing row instead of quoting it.
  • P2-3: each review now runs inside srt, Anthropic's sandbox runtime (@anthropic-ai/sandbox-runtime 0.0.79, the command center's ruling on the measured options): srt's namespace has only lo, and its host proxy passes api.anthropic.com alone. The inner bwrap stays the filesystem fence. Preflight refuses the tick before any key is read unless node (the mise 24.21.0), the pinned srt install, socat and a keyless check through the same chain all pass (lo only, the API through the proxy, example.com 403, no direct route, a host loopback listener never reached). R2 is closed.

• After the GPT read at d784fe0 (CHANGES_REQUESTED, four P2), one forward commit:

  • Supersession is durable: a comment whose reply was lost before a head move is found by its marker and gets the superseded line; a failed superseding PATCH is retried on later ticks; open posting work is found from the stored attempt markers, not from the listed heads.
  • srt starts without the key. The inventory runner is srt's command and injects the key into bwrap and the client only; srt's node process, shells and socat bridges never hold it (measured by a process-environment scan with a fake key; the key-first order put it in node, sh, bash and three socat).
  • RecordRuleTest rejects a restored quotation in the record's direction sections (synthetic text), wrapped across lines or not; its detector finds the 25-word wrapped quotation of the 4b8027b form (1 span) and none in the current form, and that form spliced back fails the test on the detector's assertion. (At 3d0bead the detector stopped at line breaks and missed it; the CC's read found that.)
  • The final head read after posting is open work (verify: pending) until a head read settles it, so a failed final read or a stopped tick no longer leaves a superseded comment unmarked (the GPT micro at 3d0bead).
  • The ledger reference (the api-actions harness common.py, then not in git; under local git since d97aad49) is pinned by sha256 362cb74c…9a71 with line locators and a read-only copy, and the worker was run against it on one temporary ledger; a close of another workload's debit is now refused.

• After the command center's read at 3d0bead and the GPT read at 0d08404 (forward commits, first pushed now):

  • bdc2df4b5: the CC's P3s. R1 names where the key lives (the runner in memory; bwrap, the client and its children in their environment), names CLAUDE_CODE_SUBPROCESS_ENV_SCRUB as unmeasured, and weighs srt's credential masking. A superseding PATCH now ends: 404 marks the comment deleted, and the worker gives up after 24 failed tries (a new test fails on the pushed worker). The ledger reference is also pinned by commit.
  • 04a3d74f6: the records-rule detector cites the Python 3.13 re and str.split() behaviour it rests on.
  • fb041ded9 and 9305bb01a: fill-first key order and per-run tokens (the owner's directions of 2026-10-10, relayed by the CC). Each settle records per-model tokens and the cache hit rate, and each settle or void row carries a use case. fb041ded9 adds four tests; seven tests fail on bdc2df4b5.

• Rebase corrections (rebased onto main 8c95a50d1; Retire Claude review inside GitHub; AI reviews run locally #981, 8bffa2c4, removed the in-GitHub Claude workflows and so made these statements false):

  • docs/github-automation.md: this PR's copies of the three retired bullets (harness audit, PR review, toolkit read) are dropped in the conflict resolution. Main's "Claude review inside GitHub: retired" bullet is kept unchanged, and this PR adds only its "Local review of essential heads" bullet after it.
  • tools/claude-review-worker/README.md (two places): the paths input of claude-pr-review.yml is no longer offered as a way to review a refused head; it is named as removed by Retire Claude review inside GitHub; AI reviews run locally #981. anthropic-api-3 no longer "serves CI review first": its CI-review purpose ended with Retire Claude review inside GitHub; AI reviews run locally #981.
  • tools/claude-review-worker/worker.py (three comments): the stream-bounds pattern and the 1.10 cost factor are attributed to claude-pr-review.yml as it was before Retire Claude review inside GitHub; AI reviews run locally #981, not as a live workflow, and anthropic-api-3's CI-review purpose is named as ended.
  • docs/decisions/2026-10-09-claude-review-worker.md (seven places): anthropic-api-3 "served" CI review through the claude-review environment, which no workflow on main uses since Retire Claude review inside GitHub; AI reviews run locally #981; the removed tests/test_claude_pr_review_workflow.py is named as removed. The "Why" section no longer says the cloud path still waits on the federation fix. The fence flags are traced to the workflow until Retire Claude review inside GitHub; AI reviews run locally #981 removed it. The cloud path is no longer listed as an optional alternative. The overturn condition "the federation fix landing" becomes an owner decision to bring a cloud review back. The source read is pinned to 65cf2730, the last main commit with the workflow.
  • Nothing else changed: the other 15 commits apply as they were, with manifests/evidence.json taken from main and re-registered per commit.

• The terminal commit 317cdd3e (the CC's micro at a3881b19, CHANGES_REQUESTED; the CC's adjudication at 1a610ba7 after the GPT read there):

  • B4, and the GPT read's P2 at 1a610ba7: when credential_run.py --check refused every key, the loop only skipped and still ended in its else suite (CPython 3.13.16 Doc/reference/compound_stmts.rst:165, :173), so each tick published "every configured key is out of credit" with no request made and no attempt recorded. Such a run is now key_check_refused: one error status saying the credential check refused every key, an uncounted, non-final attempt, no ledger row; the first tick with a usable key reviews the head as usual. A mix of credit and revoked refusals now says both.
  • B3: the boundary tests put a stand-in socat on their own search path; CI's ubuntu-24.04 runner has none, and validate-shard-0 failed on it.
  • B2: the record says no hosted run had succeeded (scheduled run 37988961127 ran on main on 2026-10-09 and failed). B5: the record counts the module's 94 tests.
  • Owner direction of 2026-10-11 ~22:33Z (via the CC): the default key order is api-4, api-3, api-2, api-5, anthropic-api, then api-6 to api-10.
  • Prompt caching (CC): the prompt puts its stable part (rules, task, upstream rule, answer shape) first and the pull request's line and citation counts last (anthropics/skills@dbd4588f prompt-caching.md:7, :27); the settings set promptCacheTtl: "1h" (anthropics/claude-code CHANGELOG.md:2970, 2.1.243), subagents unchanged.
  • The gh-login comment is back on self.login.

• Which heads are essential: tools/claude-review-worker/essential-paths.json:

  • every us-equities-trading PR;
  • native-agent-stack PRs touching blueprints/us-equities/**, .github/**, scripts/validate*.py, tools/credentials/**, adoption/hooks/** and the other listed paths.

  This file is for the command center to approve.

SOTA sources

• Claude Code (the pinned native client, 2.1.296), as installed:
  • environment variables, CLAUDE_CODE_DISABLE_CLAUDE_MDS ("Set to 1 to prevent loading any CLAUDE.md memory files into context, including user, project, and auto memory files"): https://code.claude.com/docs/en/env-vars;
  • permissions (Read deny rules, and "Claude makes a best-effort attempt to apply Read rules to all built-in tools that read files like Grep and Glob"): https://code.claude.com/docs/en/permissions;
  • headless mode and the CLI reference: https://code.claude.com/docs/en/headless.
• bubblewrap (bwrap), the distribution package on the host; the profile and its measurements are in the decision record.
• Anthropic's sandbox runtime, anthropics/sandbox-runtime@d9aac2098351ca17f3743fbaf6ecbd0051b7e00e (tag v0.0.79; npm @anthropic-ai/sandbox-runtime@0.0.79, tarball sha256 5a730e4367c264ccc4b592af01dab038a6c39db7c184efbd132841688fa854f1): src/sandbox/linux-sandbox-utils.ts:1343-1363,3378 (--unshare-net plus a host filtering proxy over a bound socket), src/sandbox/sandbox-manager.ts:355-415 (the allowlist).
• GitHub REST API, commit statuses and issue comments: https://docs.github.com/en/rest/commits/statuses, https://docs.github.com/en/rest/issues/comments.
• The api-actions harness ledger protocol (the coordination record's harness/common.py: an fcntl lock on <ledger>.lock, and debit before submit), followed row for row.
• Claude Code CHANGELOG.md:2970 at anthropics/claude-code@3deb873 (2.1.243): promptCacheTtl and subagentPromptCacheTtl.
• The claude-api skill, anthropics/skills@dbd4588f skills/claude-api/shared/prompt-caching.md: :7 and :27 (stable content before volatile content, the prompt's order), :130 (caches per organization, fill-first).
• CPython 3.13.16 at python/cpython@cbc944f4, Doc/reference/compound_stmts.rst:165 and :173: a loop that only skipped ends in its else suite (the refused-check fix).
• The command center's ruling ROW-cc-20261010T0015Z-api-routing.md (essential review routing and the upstream-alignment rule).

Evidence-class table

Claim	Evidence class	Command / receipt
The sandbox has only the bound paths: no home directory, gh login or key store; the API host is reachable	native_proven	probes.py offline O3, O4 (coordination receipt crw-probes/probes/20261010T004458Z)
No instruction file reaches a request: a control arm sends all five planted facts, the fenced arm none (nor the head's .claude rule fact; the skill fact has no positive control)	native_proven (with a scripted stand-in model)	probes.py offline L1 at 2acade9 (crw-probes/probes/20261010T013843Z, 18 of 18 PASS), rerun with the stricter grader (20261010T052121Z, 18 of 18)
Bash is unavailable; Read of /etc/hostname, .git, .env, .pem, outside files and a planted gh login are denied; no planted value or key reaches a request by any /proc (self, thread-self, 1) or /dev/fd route; a link in main's checkout is not followed out of the working directory; a run's config directory keeps neither the key nor a stored key response	native_proven (with a scripted stand-in model)	probes.py offline L4, L5, L7 to L11, O8; L7, L8 and L9 now with 7, 2 and 6 required calls answered (20261010T052121Z)
With Opus 5.5, the fenced arm knows none of the five facts and the control arm knows all; no MCP server loads; a planted secret-like string is not echoed; an uncited upstream claim yields an [upstream] finding	native_proven	probes.py live P1, P2, P6, P11 on api-4, $0.5557 (receipt crw-probes/probes/20261010T004508Z; the receipt reads FAIL as a whole because of the refused tool arm, and its P4 PASS was vacuous: no Bash call was made)
A live tool-call probe asking the model to try reading credentials was refused by the Opus 5.5 safeguard ([cyber]), so that arm is dropped; the offline L checks stand	native_proven	the same receipt, run tools
Ledger rows are compatible both ways: the worker reads the harness's 611 rows, and the harness counts a CRW row in the key's column	local_integration	a copy of the ledger (coordination record)
Selection, ledger (open-debit check), posting (head read before each POST, reconcile before a retry), the fenced comment, the citations data file, the whole-stream mask bound, the unreadable-stream class, the size cap and the attempt markers behave as described	synthetic	tests/test_claude_review_worker.py, 94 tests at 317cdd3e; 21 weakened copies of the code guards fail their tests in 25 runs (readers/crw-mutants-20261010/mutants3.py)
The network boundary is closed: only lo in the run's namespace, the API reachable through srt's proxy, example.com refused (CONNECT 403), no direct route, a host loopback listener never reached; the same check with example.com allowed fails	native_proven (keyless)	the worker's boundary_self_check through srt and bwrap, 2026-10-10 06:05Z; RealBoundaryChainTest with CRW_TEST_SRT/CRW_TEST_NODE set
A real review streams through srt: probes.py live on api-4 passes P1, P2, P6 and P11; three runs end_turn	native_proven	at d784fe0: crw-probes/probes/20261010T060816Z, $0.6252, review 204 s; through the reordered chain: crw-probes/probes/20261010T095638Z, 20 of 20, $0.7766, review 261 s
srt's node process, shells and socat bridges never hold the key; the client does (a process-environment scan during a run with a fake key); with the runner outside srt the same test fails	native_proven	RealBoundaryChainTest with CRW_TEST_SRT/CRW_TEST_NODE set
The worker's ledger and the harness's common.py (sha256 362cb74c…9a71) refuse the same double, cross and orphan closes on one ledger; recovery skips a ref the harness closed; the harness counts the worker's rows	local_integration	coordination record readers/ledger-compat-20261010/: common.py.pinned sha256 362cb74c3178a8715a28c97ae5e98dfefe044dfd68f5f09d00a85eb062e99a71, compat.json sha256 15d9f39979016c9d11b7b9948b20ccf758fbd1b45207d3300591b04c1bca3b00, ledger_compat.py sha256 4be8f465c55a54a335dc7623dbbd1a25ff8706cf9524f54a4df650132242a115
The records rule: no quoted direction in the direction sections	synthetic	RecordRuleTest; the 4b8027b section form gives 1 span and fails it on the detector's assertion (readers/crw-mutants-20261010/prior_record_check.py)
The rebased head behaves as before: offline probes pass and the worker's tests pass	local_integration	at a3881b19f: probes.py offline 16 PASS, 9 INFO, 0 FAIL (state receipt probes/20261011T212536Z), 91 worker tests OK; at 317cdd3e: 94 worker tests OK with and without socat on the search path, validate exit 0
A check that refuses every key posts one non-credit status and records one attempt; a usable key later reviews as usual	synthetic	the two regressions fail at 1a610ba7 (rc 1) and pass at 317cdd3e (rc 0); the GPT read's review_regressions.py passes at 317cdd3e
No real pull request has been reviewed yet	—	the first ticks run with CLAUDE_REVIEW_POST=0

Local commands run

$ python3 -I tools/claude-review-worker/probes.py offline
18 PASS, exit 0 (at 2acade96a); 18 PASS with the stricter L7 to L9 grader; 16 PASS at the head (api-4 only, so O6 once), with srt's static checks
$ CLAUDE_REVIEW_KEYS=anthropic-api-4 API_ACTIONS_LEDGER=<ledger> python3 -I tools/claude-review-worker/probes.py live
P1 P2 P6 P11 PASS (P4 vacuous); P5 P7-P10 FAIL (tool arm refused by the safeguard, not exercised; arm dropped since)
$ CLAUDE_REVIEW_KEYS=anthropic-api-4 CLAUDE_REVIEW_SRT=<srt prefix> CLAUDE_REVIEW_NODE=<mise node> API_ACTIONS_LEDGER=<ledger> python3 -I tools/claude-review-worker/probes.py live   # at the head, through srt
PASS, native_proven: boundary check passed; P1 P2 P6 P11 PASS; $0.6252
$ python3 -m unittest tests.test_claude_review_worker   # at 0d08404e
Ran 87 tests, OK (skipped=1: RealBoundaryChainTest; run separately with CRW_TEST_SRT and CRW_TEST_NODE set: OK)
$ TMPDIR=/var/tmp/claude-tmp/<dir> python3 -m unittest <the 45 test modules that name the worker, its record or manifests/evidence.json>   # at 0d08404e3
Ran 3345 tests, OK (skipped=34). (At d784fe0e with TMPDIR=/tmp, test_token_e2e_grader F27c failed on a cross-device git clone; on /var/tmp it passes.)
$ python3 mutants3.py <scratch copy>   # each code guard of both rounds undone in turn
25 of 25 fail their named test
$ python3 scripts/validate.py
exit 0
$ gitleaks git . --log-opts="$(git merge-base origin/main HEAD)..HEAD" --max-target-megabytes 2 --config .gitleaks.toml --redact
no leaks found
$ uvx ruff check --select F tools/claude-review-worker/ tests/test_claude_review_worker.py
All checks passed!

At the rebased head a3881b19f (2026-10-11; 1a610ba7c changes comments and records only):

$ CLAUDE_REVIEW_SRT=<srt 0.0.79 prefix> CLAUDE_REVIEW_NODE=<mise node 24.21.0> python3 -I tools/claude-review-worker/probes.py offline
exit 0: 16 PASS, 9 INFO (O6i for each later fill-first slot), 0 FAIL
$ python3 -m unittest tests.test_claude_review_worker
Ran 91 tests, OK (skipped=1)
$ python3 scripts/validate.py
exit 0
$ python3 scripts/validate_shards.py run --shard N --shards 8   # N = 0..7, in parallel, as validate.yml runs them
5 shards OK; shards 2, 4 and 7 failed under a host load average above 100, in four modules:
  tests.test_workflow_hardening (BetterleaksTrial fixture), tests.test_secret_path_guard (timing bounds), tests.test_child_usage_suite:
    the three together, 213 tests OK on this head at a load near 45 (unchanged main 8c95a50d: each OK)
  tests.test_adaptive_paper_credential_race: the same 5 failures on this head and on unchanged main 8c95a50d
$ gitleaks git --log-opts="$(git merge-base origin/main HEAD)..HEAD"
no leaks found

At the terminal head 317cdd3e (2026-10-12, on main 86fa38442):

$ python3 -m unittest tests.test_claude_review_worker tests.test_evidence_manifest tests.test_github_automation_practice
Ran 107 tests, OK (skipped=1)
$ bwrap --dev-bind / / --ro-bind /dev/null /usr/bin/socat python3 -m unittest tests.test_claude_review_worker   # no socat
Ran 94 tests, OK (skipped=1)
$ python3 -m unittest tests.test_claude_review_worker.ReviewRunTest.test_a_check_that_refuses_every_key_posts_one_status_and_records_one_attempt   # and ...test_a_key_usable_on_a_later_tick_reviews_the_head_as_usual
rc 1 at 1a610ba7 (the test file copied there), rc 0 here, each
$ python3 scripts/validate.py
exit 0
$ gitleaks git --log-opts="$(git merge-base origin/main HEAD)..HEAD"
no leaks found

The GPT read at 317cdd3e (fix4): ACK, no blocker. Its P3s join the follow-ups below; the first, the Spend bullet's old key order, is fixed in this body.

The command center's Claude delta at 317cdd3e: PASS_WITH_P3 (pr953-claude-micro-317cdd3e.md). Its P3s and the research row join the follow-ups below; the three pinned sources are now in this body's SOTA sources.

Follow-ups (the reads' P3s): when every key is refused, only the first eligible head gets the not-started status, since the tick stops there; the dedupe matches any earlier key_check_refused attempt rather than the latest; and its log line is not at warning priority. The TTL in effect is not observable: record ephemeral_1h_input_tokens from the stream's per-message usage on the first real runs. The record's "no two heads shared any of the prompt" is loose (the old prompts shared 32 bytes, below Opus 5.5's 512-token minimum prefix, prompt-caching.md:131, :135). The record's SOTA sources (:681) should list the three new pinned sources too. Cosmetic: the trading rule's "not exported," line break (worker.py:1523-1525) and record :202-203 past the wrap width. Research-queue row 31 (co-op): measure whether the one-hour TTL's doubled cache writes pay back through prefix reuse across heads, and keep "1h" only if the measured reuse covers it. A retained primary capture for B2's historical run (37988961127) and a red-before guard for the B2/B5 prose corrections; the switch row written before the next debit succeeds; the refusal and switch-row wording around the key loop; the evidence summary's historical counts; the hostname references in the manifest's existing content; moving line locators in pre-existing files; the merged-tree verification gaps (new main modules such as tests.test_active_model_currency); the CC's P3s at a3881b19 (the harness pin after d97aad49, the 404 handling, R1's allowPlaintextInject note, the Python citations as mirror paths, the automation bullet's path groups, the old SHAs above).

Decision record

docs/decisions/2026-10-09-claude-review-worker.md: the run, the instruction fence, upstream alignment, the sandbox measurements, the probes and the live results, the decisions beyond the brief, alternatives, what would overturn it, the evidence class and the SOTA sources.

Checklist

• No GitHub Actions workflow is added or changed.
• No secrets are printed, logged or committed. The key reaches only the sandboxed client's environment, and the stream is masked.
• No new paid hosting, subscription or billing surface. It spends the existing Anthropic API keys under the ledger.
• Peer-owned untracked files and worktrees were preserved.

🤖 Generated with Claude Code