exec: de-flake the SIGKILL escalation test

The test spawned a node child that installed a SIGTERM handler and relied on a 250ms deadline to fire after it. The deadline timer starts at spawn, so on a loaded runner node had not yet reached `process.on('SIGTERM')` when the signal landed: the default disposition killed it outright, the 5s grace-timer escalation never ran, and the elapsed-time assertion saw 462ms. That failed the v0.10.0 release job before the publish step. Use `sh -c 'trap "" TERM; exec sleep 30'` instead. The shell boots in ~1ms rather than a node runtime's tens of ms, and an ignored signal survives exec where an installed handler would not, so the sleep holding the group ignores SIGTERM too. Widen the deadline to 1s as well, so the window the child has to get there is 4x larger.
runtime: stream Claude agent activity (#58 )
2026-11-13 20:28:06 -10:00 · 2026-08-05 14:38:17 -07:00 · 2026-08-04 21:39:03 -07:00 · 2026-08-04 18:46:59 -07:00 · 2026-08-04 15:56:47 -07:00 · 2026-08-04 15:36:18 -07:00
41 changed files with 1987 additions and 338 deletions
@@ -37,13 +37,14 @@

  // Anthropic models always run through the Claude Code CLI (`claude -p`) — the
  // engine is inferred per agent from its model, so this entry only supplies the
-  // credential. In CI the tokenEnv holds a token minted by `claude setup-token`
-  // (an `sk-ant-oat…` subscription token; an `sk-ant-api…` Console key works too);
-  // locally an active `claude` login is enough — the entry could even be omitted.
-  // ECR_EXPECTED_TOKEN_ENV (repo variable) must equal this tokenEnv.
+  // credential. In CI the tokenEnv holds the shared review credential (an
+  // `sk-ant-oat…` token minted by `claude setup-token`, or an `sk-ant-api…`
+  // Console key); locally an active `claude` login is enough — the entry could
+  // even be omitted. ECR_EXPECTED_TOKEN_ENV (repo variable / workflow fallback)
+  // must equal this tokenEnv.
  "auth": {
    "providers": {
-      "anthropic": { "tokenEnv": "CLAUDE_CODE_OAUTH_TOKEN" }
+      "anthropic": { "tokenEnv": "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN" }
    }
  }
 }
@@ -68,7 +68,7 @@ jobs:
      # source, so the guard runs from that same base source — same engine as `ci`.
      - name: Guard config tokenEnv
        env:
-          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_OAUTH_TOKEN' }}
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_REVIEW_SHARED_API_TOKEN' }}
        run: bun run src/cli.ts verify-config

      - name: Run AI review
@@ -83,10 +83,10 @@ jobs:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Layer-1 auth lock: `ecr ci` re-checks the honored tokenEnv at runtime,
          # catching what the guard step above can't. Keep in sync with the guard.
-          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_OAUTH_TOKEN' }}
-          # Claude Max/Team subscription token minted by `claude setup-token`
-          # (~1 year lifetime). The claude-code engine forwards it to the Claude
-          # Code CLI as the only credential (any ANTHROPIC_* key is stripped).
-          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_REVIEW_SHARED_API_TOKEN' }}
+          # Shared Anthropic review credential. The claude-code engine forwards
+          # it to the Claude Code CLI as the only credential (any ambient
+          # ANTHROPIC_* key is stripped). A setup-token or Console key both work.
+          CLAUDE_CODE_REVIEW_SHARED_API_TOKEN: ${{ secrets.CLAUDE_CODE_REVIEW_SHARED_API_TOKEN }}
          # Optional: override the model for every agent.
          REVIEWER_MODEL: ${{ vars.REVIEWER_MODEL }}
@@ -48,21 +48,19 @@ npx @expo/code-review-cli setup-auth
 npx @expo/code-review-cli doctor
 ```

-`setup-auth` reads the repo's config and walks through each credential it needs:
-an OpenAI **API key** (the scaffolded default — it prints where to create the key
-and the exact restricted permissions to grant), and/or a **ChatGPT/Codex
-subscription** sign-in (it runs OpenCode's browser login and extracts the token
-for you). `doctor` offers to run it whenever a credential is missing.
+`setup-auth` reads the repo's config and walks through each credential it needs.
+The scaffolded default is **Anthropic via the Claude Code CLI**: locally your
+`claude` login is enough, and for CI it helps you mint a token with
+`claude setup-token`. It also handles the alternatives (an OpenAI **API key**,
+a **ChatGPT/Codex subscription** sign-in). `doctor` offers to run it whenever a
+credential is missing.

-In CI, store the same values as repo secrets (`OPENAI_API_KEY`; plus
-`CODEX_OAUTH_ACCESS_TOKEN` for the mixed setup) — the scaffolded workflow
-forwards them.
+In CI, store the credential as the repo secret the scaffolded workflow forwards
+(`CLAUDE_CODE_REVIEW_SHARED_API_TOKEN` by default — an `sk-ant-oat…` token from
+`claude setup-token`, or an `sk-ant-api…` Console key; the CLI reads either).

-**Have a ChatGPT Plus/Pro (Codex) subscription? Use both.** The recommended
-production setup pairs the subscription (runs the default models at no marginal
-cost) with the usage-based key (covers only the pro-tier models the subscription
-excludes) — see [the mixed setup](#other-providers) below. Prefer
-**Anthropic/Claude** or another provider? Same section.
+Prefer **OpenAI** (API key, or a ChatGPT/Codex subscription, or both mixed) or
+another provider? See [Other providers & auth modes](#other-providers) below.

 ### Reviewing (already configured)

@@ -196,7 +194,7 @@ your-monorepo/
  // Central guardrails every scope inherits and CANNOT override.
  "defaults": {
    // The ONLY place auth/tokenEnv is honored (besides the root config.jsonc).
-    "auth": { "mode": "api-key", "provider": "openai", "tokenEnv": "OPENAI_API_KEY" },
+    "auth": { "providers": { "anthropic": { "tokenEnv": "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN" } } },
    "enforceAgents": ["security"],            // always runs on every scope, roster or not
    "commentTag": "expo-ai-code-reviewer"     // per-scope markers derive from this
  },
@@ -214,7 +212,7 @@ your-monorepo/
 // apps/api/.expo-code-review/config.jsonc  (the api team owns this)
 {
  // NO "auth" block — locked centrally; a tokenEnv here is rejected by loader + CI guard.
-  "model": "openai/gpt-5.5",
+  "model": "anthropic/claude-sonnet-5",
  "policy": { "includeSuggestions": false },
  "noise":  { "additionalIgnores": ["apps/api/**/__generated__/**"] }
  // shared.md, coordinator.md, agents/*.md live beside this file — the api team's roster.
@@ -316,6 +314,11 @@ Ownership is enforced with CODEOWNERS: `/.expo-code-review/routing.jsonc @your-i
 - **Reporter** — posts/updates a single fingerprinted PR comment (CI), or prints
  a grouped summary (local). Findings below the configured severity floor are
  suppressed.
+- **Whole-review reuse** — automated CI stores a hash of each review job's inputs
+  in the hidden state of that comment. If a restack leaves a scope's files and
+  review configuration unchanged, its complete prior result is reused. Manual
+  `/review`, partial/failed reviews, stack-aware review, and model-adjudicated
+  feedback always run fresh.

 Built on the [OpenCode](https://opencode.ai) SDK, which spawns the model provider
 and applies the provider's prompt caching automatically.
@@ -387,7 +390,7 @@ show writes (there is nothing to re-read within the run).
 ---
 description: One line the router uses to decide relevance.
 alwaysRun: true        # run even when the router would skip this agent
-model: openai/gpt-5.5-pro     # override the default model
+model: anthropic/claude-opus-5   # override the default model
 temperature: 0.1
 ---

@@ -396,14 +399,14 @@ temperature: 0.1

 For a real-world example, see eas-cli's
 [`.expo-code-review/`](https://github.com/expo/eas-cli/tree/main/.expo-code-review)
-— correctness/security/consistency agents, a stronger model for security + the
-coordinator, and per-repo `noise.additionalIgnores`.
+— correctness/security/consistency agents, a stronger model for security, and
+per-repo `noise.additionalIgnores`.

 `config.jsonc` (JSONC — comments + trailing commas supported):

 ```jsonc
 {
-  "model": "openai/gpt-5.5",                  // default model for the specialists
+  "model": "anthropic/claude-sonnet-5",       // default model for the specialists
  "policy": { "includeSuggestions": false },  // suppress suggestion-severity findings
  "chunk": { "maxChangedLines": 1000, "maxFiles": 20 },  // concurrency defaults: 6 (API key) / 3 (subscription)
  "noise": { "additionalIgnores": ["packages/*/build/**"] },
@@ -412,8 +415,8 @@ coordinator, and per-repo `noise.additionalIgnores`.
              "skipLabel": "ai-review:skip" }, // "label" (only labeled PRs)
  "breakGlass": { "marker": "/skip-review" }, // PR body marker that skips the review
  "commentTag": "expo-ai-code-reviewer",      // hidden tag used to find/update the comment
-  "auth": { "mode": "api-key", "provider": "openai",
-            "tokenEnv": "OPENAI_API_KEY" }
+  "auth": { "providers": {
+    "anthropic": { "tokenEnv": "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN" } } }
 }
 ```

@@ -427,15 +430,17 @@ Precedence: **`REVIEWER_MODEL` env** (global override) → per-file **frontmatte
 setup, and a developer can override everything locally.

 - **Specialist agents** (correctness/security/consistency) benefit from a
-  reasoning-tier model — **`openai/gpt-5.5`** is the quality/speed sweet spot
-  (the scaffolded default). The **pro tier** finds more but is slower and more
-  expensive, so scope it to the highest-stakes agent: **security runs on
-  `openai/gpt-5.5-pro`** (set in `security.md` frontmatter), the rest on the default.
+  reasoning-tier model — **`anthropic/claude-sonnet-5`** is the quality/speed
+  sweet spot (the scaffolded default). The **Opus tier** finds more but is slower
+  and more expensive, so scope it to the highest-stakes agent: **security runs on
+  `anthropic/claude-opus-5`** (set in `security.md` frontmatter), the rest on the
+  default.
 - **The coordinator** makes the final call (dedupe / re-judge / decide) — worth a
-  strong model; set it in `coordinator.md` frontmatter.
+  strong model; the scaffold pins it to `anthropic/claude-opus-5` in
+  `coordinator.md` frontmatter.
 - If latency/timeouts dominate on big PRs, moving the specialists to a faster model
-  (e.g. `openai/gpt-5.4-mini`) is the most direct lever (a real recall tradeoff —
-  measure it).
+  (e.g. `anthropic/claude-haiku-4-5`) is the most direct lever (a real recall
+  tradeoff — measure it).
 - **Every run logs which model actually answered each pass** — in the job log
  (`Models used — …`), the Actions step summary table, and the run log's
  `agentModels` — and warns loudly if a pass ran on a different model than
@@ -650,11 +655,35 @@ visible even in CI (where the run log is ephemeral).
 <details>
 <summary><b>Other providers & auth modes</b></summary>

-The recommended setup is an OpenAI API key — see Usage above. Alternatives, all
-set in `config.auth` (credentials come from OpenCode):
+The scaffolded default is **Anthropic via the Claude Code CLI** — see First-time
+setup above and the Anthropic bullet below for how it authenticates and is
+sandboxed. Everything is set in `config.auth`; non-anthropic providers get their
+credentials through OpenCode.

- **ChatGPT/Codex subscription (OAuth) + usage-based API key — the recommended
-  mix.** OpenAI permits subscription auth in third-party tools, and OpenCode
+- **Anthropic / Claude (the default)** — use `anthropic/...` model ids and every
+  anthropic pass runs through the **Claude Code CLI** (`claude -p
+  --output-format stream-json --verbose`), inferred from the model. The
+  credential is (in order) a `tokenEnv` you name, an ambient
+  `CLAUDE_CODE_OAUTH_TOKEN`, or your local
+  `claude` login — an `auth` entry is entirely optional. Run `claude setup-token`
+  for a Max/Team subscription token or point `tokenEnv` at an Anthropic Console
+  API key (`sk-ant-api…`, forwarded as `ANTHROPIC_API_KEY`); the CLI reads
+  either. `ecr setup-auth` walks you through it. Each pass is trust-isolated and
+  read-only: it runs with `--safe-mode` (no `CLAUDE.md`/hooks/MCP/plugins),
+  `--strict-mcp-config`, `--permission-mode dontAsk`, and only the
+  `Read`/`Grep`/`Glob` tools — never `Bash`/`Edit`/`Write`/`WebFetch`/`WebSearch`.
+  The child env is an allowlist that omits ambient `ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN`
+  (only the configured credential is re-injected).
+  ```jsonc
+  // The scaffolded default. No anthropic entry at all falls back to your
+  // `claude` login.
+  "auth": { "providers": {
+    "anthropic": { "tokenEnv": "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN" }
+  } }
+  ```
+- **OpenAI: ChatGPT/Codex subscription (OAuth) + usage-based API key — the
+  recommended mix if you review with OpenAI.** OpenAI permits subscription auth
+  in third-party tools, and OpenCode
  ships the plugin for it — so the reviewer runs its default models on the
  subscription (zero marginal cost) and reserves the metered key for pro-tier
  models the subscription doesn't offer (`gpt-5.5-pro` is subscription-excluded).
@@ -693,25 +722,6 @@ set in `config.auth` (credentials come from OpenCode):
    One caveat: OpenCode can't price alias models (they're config-declared), so
    pro passes report `$0` in the run log's cost column — token counts are
    correct, and the OpenAI project dashboard is the source of truth for spend.
- **Anthropic / Claude** — use `anthropic/...` model ids and every anthropic pass
-  runs through the **Claude Code CLI** (`claude -p --output-format json`), inferred
-  from the model. The credential is (in order) a `tokenEnv` you name, an ambient
-  `CLAUDE_CODE_OAUTH_TOKEN`, or your local `claude` login — an `auth` entry is
-  entirely optional. Run `claude setup-token` for a Max/Team subscription token
-  (forwarded as `CLAUDE_CODE_OAUTH_TOKEN`) or point `tokenEnv` at an Anthropic
-  Console API key (`sk-ant-api…`, forwarded as `ANTHROPIC_API_KEY`); the CLI reads
-  either. `ecr setup-auth` walks you through it. Each pass is trust-isolated and
-  read-only: it runs with `--safe-mode` (no `CLAUDE.md`/hooks/MCP/plugins),
-  `--strict-mcp-config`, `--permission-mode dontAsk`, and only the
-  `Read`/`Grep`/`Glob` tools — never `Bash`/`Edit`/`Write`/`WebFetch`/`WebSearch`.
-  The child env is an allowlist that omits ambient `ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN`
-  (only the configured credential is re-injected).
-  ```jsonc
-  // Optional — no anthropic entry at all falls back to your `claude` login.
-  "auth": { "providers": {
-    "anthropic": { "tokenEnv": "CLAUDE_CODE_OAUTH_TOKEN" }
-  } }
-  ```
 - **Another provider** — the current path is the `REVIEWER_MODEL`
  env override: `opencode auth login` once (pick the provider), then run with
  e.g. `REVIEWER_MODEL=google/gemini-3-pro`. It overrides every agent's model
@@ -724,8 +734,9 @@ any other) OpenCode provider, and each agent's `model` selects its engine.
 `REVIEWER_MODEL` still overrides every agent's model (and therefore every agent's
 engine), converging the whole run onto one engine.

-There is no shared fallback key; if a run fails for lack of credentials, authenticate
-a provider in OpenCode. `ecr doctor` diagnoses setup.
+There is no shared fallback key; if a run fails for lack of credentials, log in
+with `claude` (the default) or authenticate a provider in OpenCode. `ecr doctor`
+diagnoses setup.

 **Setup errors fail fast, with the fix in the message.** A bad credential or model id
 would otherwise fail every pass identically — a run that spends its whole budget
@@ -99,9 +99,38 @@ oversight, and must not be silently reintroduced as a "fix" ([observed]
 ## Claude Code CLI Containment

 The Claude Code engine runs each review pass as a single stateless
-`claude -p --output-format json` subprocess fed the task on stdin. The argv and child
-environment are built to keep an untrusted PR (the review input) from turning that
-subprocess into code execution or credential exfiltration.
+`claude -p --output-format stream-json --verbose` subprocess fed the task on stdin.
+The JSONL stream makes tool activity observable while the pass runs instead of leaving
+only a periodic heartbeat until the final result. The incremental decoder emits only
+bounded lifecycle metadata and read-tool names with confined repo-relative targets;
+raw assistant text, tool results, grep patterns, and attempted host paths never reach
+the progress or error logs because model output is untrusted and may contain source
+secrets or terminal/log-injection payloads. If a stream ends without a final result,
+or its error result has no explicit message, parsing returns a fixed diagnostic rather
+than falling back to the raw JSONL transcript. The fixed diagnostic carries the child
+exit code and may derive an actionable, fixed category from stderr only when no stream
+was emitted (rejected flags, authentication, or launch failure); arbitrary stderr is
+never copied into logs, and only an explicit final-result error message reaches
+provider-error classification. Every task-specific progress line is tagged with the
+stable agent bucket by the review pipeline, so concurrent passes remain attributable
+[observed] `claude-code.ts` `claudeExitDiagnostic`/`runClaudePrompt`, `review.ts`
+`formatAgentActivity`/`taskProgress`; tests in
+`claude-code.test.ts` and `review-internals.test.ts`. The argv and child environment
+are built to keep an untrusted PR (the review input) from turning that subprocess into
+code execution or credential exfiltration.
+
+Every production structured-output parser carries a draft-07 JSON Schema generated
+from the same Zod contract used at the local trust boundary. The Claude runtime passes
+that schema through `--json-schema`; Claude Code validates the final `StructuredOutput`
+tool call and re-prompts inside the original session when a required field or type is
+wrong. The validated `structured_output` object is then serialized through the local
+Zod parser again — provider validation improves reliability but never replaces local
+validation. If Claude exhausts its in-session structured-output retries (or claims
+success without returning `structured_output`), the runtime makes one clean-process
+attempt and accounts for both attempts; it never accepts unvalidated fallback text
+[observed] `schema.ts` `structuredParser`; `opencode.ts` `promptAndParse`;
+`claude-code.ts` `buildClaudeArgs`, `parseClaudeResult`, `runClaudePrompt`,
+`claudeCodePromptAndParse`.

 **Flags.** `--safe-mode` disables CLAUDE.md/hooks/MCP/plugins while keeping OAuth;
 `--bare` is deliberately **not** used because bare mode ignores
@@ -247,6 +276,14 @@ child resolves with `timedOut: true` in the result regardless of the `check` fla
 callers get one consistent shape to distinguish "our own deadline fired" from a real
 command failure ([observed] `exec.ts:71-87, 181-189, 230-250`).

+**Structured stdout observation stays inside the capture bound.** Spawn/input callers
+may observe stdout chunks as they arrive, but only the bytes admitted by `maxBuffer`;
+the observer is best-effort and its exceptions cannot affect the child. Claude uses
+this seam to decode `stream-json` without piping raw subprocess output to the terminal,
+while the complete bounded stdout remains available for final-result parsing
+([observed] `exec.ts` `RunOptions.onStdout` / `runWithInput`; `claude-code.ts`
+`createClaudeActivityStream`).
+
 ## Retry Taxonomy

 The runtime tells apart five failure classes and handles each differently. Conflating
@@ -271,12 +308,21 @@ retry, because re-sending the whole context into a limited account only makes it
 always capped at half the pass's own `maxWaitMs` so it can never outlast the deadline it
 protects ([observed] `opencode.ts:552-555`).

-**JSON-parse failure — same-session corrective first.** A reply that will not parse is
+**JSON-parse failure — same-session corrective first.** Claude Code receives the local
+parser's draft-07 JSON Schema and performs validation-aware retries inside the original
+session before returning `structured_output`; this retains the investigation context
+and names the exact missing field/type to the model. Local Zod validation still runs on
+the provider-validated object. If those in-session repairs are exhausted, Claude gets
+one fresh-process corrective attempt; both attempts remain in cost/token accounting.
+OpenCode has no equivalent structured-output seam, so a reply that will not parse is
 retried in the **same** OpenCode session first: the model still holds all the file
-context it read, so the corrective is a cheap cache-read re-emit with better recall than
-re-investigating; only if that also fails does it fall back to a fresh session. Parse
-failure and timeout are handled by entirely separate mechanisms and must not be
-conflated ([observed] `opencode.ts:994-1003`).
+context it read, making the corrective a cheap cache-read
+re-emit with better recall than re-investigating; only if that also fails does it fall
+back to a fresh session. Claude's legacy/no-schema path retains one fresh-process
+corrective as defense in depth. Parse failure and timeout are handled by entirely
+separate mechanisms and must not be conflated ([observed] `schema.ts`
+`structuredParser`; `claude-code.ts` `claudeCodePromptAndParse`; `opencode.ts`
+`promptAndParse`).

 **Finalize and corrective prompts run with every tool disabled.** The "stop and return
 what you have" finalize and the "re-emit valid JSON" corrective are sent with `NO_TOOLS`
@@ -61,6 +61,14 @@ The absolute constraint is the carve-out (`suppress.ts:39-44`): a `critical` or

 **The comment is the durable store.** An embedded `<!-- tag:state=... -->` comment holds base64 JSON of the FULL review plus dismissals — not just what is rendered — so a later `/dismiss` or `/undismiss` can re-render without re-running the engine (`render.ts:198-202`, `encodeState`/`parseReviewState` at `render.ts:493-513`). There is no side-channel database; the comment body is the state. Dismissed findings render in a collapsed `<details>` section, disjoint from the active list (a finding is never in both), keeping the main list clean while preserving a `by`/`reason` audit trail.

+## Review Result Cache
+
+The same durable comment state is the cache for automated CI reviews. `reviewInputHash` (`src/core/review-cache.ts`) hashes each scoped changed file's content from the materialized PR-head tree, a normalized patch (blob ids and hunk coordinates removed; deletion/mode information retained), and every stable input that can change the result: the engine package version, resolved prompts/config/models, PR title/body, selected agents and routing mode, and external context. It deliberately excludes the temporary trusted-config path and the base/head commit OIDs. A restack changes OIDs and may move hunk line numbers; if it leaves the actual review input byte-identical, CI reuses the complete `CoordinatorOutput` already embedded in the most recent author-verified reviewer comment instead of launching the agents again. Symlinks are hashed as link targets and never followed. A package release changes the key so upgraded review logic runs once. Legacy comments store one `inputHash`; aggregate comments store one per `ScopeReviewResult`, so an unchanged scope can hit independently while a changed sibling reruns.
+
+Reuse is conservative. Manual `/review`/`--force` always reruns. Partial or failed reviews (`incomplete` or `couldNotComplete`) are never cacheable. Aggregate truncation removes the affected scope's hash because the embedded scope is no longer the full result. Stack-aware requalification and model-backed author-feedback seams stay fresh because their live GitHub inputs are not yet represented in the key. Cache lookup failures degrade to an ordinary fresh review. These gates make a false miss cost tokens, while preventing a false hit from presenting stale or incomplete coverage as current.
+
+The hash is state, not display: it lives only inside the base64 state marker and survives `/dismiss`/`/undismiss` re-renders. The existing author-plus-marker ownership check remains the trust boundary for adopting prior state; a PR author cannot forge a look-alike comment and supply a cache entry.
+
 **The coverage note only cries wolf when there is a wolf.** The partial-coverage warning renders only when `review.incomplete` is non-empty (`render.ts:166`) — the aggregate renderer additionally triggers it when unmatched files exist (`render.ts:373`) — a deliberate anti-noise choice so the warning is trustworthy when it appears (`render.test.ts:34`). The advisory footer ("never blocks a merge and never auto-approves") is duplicated verbatim across both renderers because it is a required trust-boundary claim, not incidental text.

 ## Truncation and Aggregate State
@@ -45,6 +45,8 @@ Flag exclusivity is rejected outright, never silently resolved, because silently

 **It never fails the PR's checks.** A reviewer error degrades to a posted failure comment, not a non-zero process exit [observed: `AGENTS.md`; `src/commands/ci.ts:354-373` legacy catch posts a summary; `src/commands/ci.ts:571-576` per-scope catch builds a `failureReview` placeholder instead of aborting the fan-out]. PR-facing comment text uses `publicFailureReason(error)`, not the raw `errorMessage`, so the credential and internal detail never leak into a comment (LLP 0002) [observed: `src/commands/ci.ts:176,365,575`].

+**Automated reruns reuse unchanged complete results.** Before launching agents, CI hashes the review job's scoped diff and stable review inputs and compares it with the hash hidden in the newest author-verified reviewer comment. An exact match re-renders the stored result (so links, dismissals, and live annotation-only feedback still update) without spending model budget. Routed CI does this independently per scope. Manual `/review`/`--force`, stack-aware runs, model-backed feedback runs, partial/failed results, and truncated aggregate state all bypass reuse and run fresh. The hash contract and durable-state rules are owned by LLP 0005's Review Result Cache section.
+
 `--unsafe-config-from-head` is a deliberate escape hatch that reverses this model, loading config from the checkout. It is never scaffolded by `ecr init`, always prints a loud `⚠ SECURITY` warning, and is scheduled for removal on a minor version boundary [observed: `src/commands/ci.ts:85-91` `CI_USAGE`, `155-162` warning].

 `--context-file` in CI takes the opposite read-error policy from `ecr review`, and the split is dictated by the never-fail-checks invariant. `ci` reads the file once before any fan-out and, on a missing/oversized/unreadable path, WARNs to stderr and continues with no context — it never fails, because a broken Atlantis-provided plan file must not turn the PR's check red [observed: `src/commands/ci.ts` `--context-file` read → stderr warn, no `exitCode`, `contextText` stays undefined]. The same reader (`readContextFile`, capped at `MAX_CONTEXT_FILE_BYTES`) backs both commands; only the catch policy differs — fatal locally, warn in CI. The byte-bounded raw text threads through the shared `CiRunOptions` into both `runLegacyCi` and `runRoutedCi`, and from there into every per-scope `runReview` as `contextText` (char-capped at prompt build) [observed: `src/commands/ci.ts` `CiRunOptions.contextText`; `runReview` calls in `runLegacyCi` and the fan-out loop].
@@ -91,8 +91,11 @@ settle. A reviewer of this feature named the case: a Terraform prompt citing
 "this is very likely going to drift" [observed] — not one of those has an extension, and
 `anthropic/claude-opus-5` is shaped identically while naming no file. Syntax cannot tell
 them apart, so an extensionless token counts as a citation exactly when it *names
-something real*: probed against the repo root and the scope's own subtree, brace lists
-and wildcards cut back to their fixed prefix. Model ids resolve to nothing and stay prose.
+something real*: probed against the scope's own subtree first, then the repo root (a
+scoped prompt citing `alerts/` means its own tree even when the root has one too), brace
+lists cut back to their fixed prefix. A token carrying `*` resolves as a glob instead,
+scope-rebased when that is what matches, so the suggested `glob:` ref itself resolves.
+Model ids resolve to nothing and stay prose.

 The consequence is deliberate: an extensionless path that had already drifted before
 adoption is invisible (nothing distinguishes it from prose), while every one that is true
@@ -188,8 +188,14 @@ test("checkProviderAuth: FORBIDDEN + cross-provider guards still fire for an ant
 test("checkProviderAuth: a non-anthropic entry naming CLAUDE_CODE_OAUTH_TOKEN is refused", () => {
  // The long-lived Claude Max/Team subscription token would otherwise be forwarded to
  // a FOREIGN provider (here openai) as its bearer — it is neither in FORBIDDEN nor a
-  // PROVIDER_KEY_ENV value, so only the anthropic-owned guard catches it.
-  for (const tokenEnv of ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_AUTH_TOKEN"]) {
+  // PROVIDER_KEY_ENV value, so only the anthropic-owned guard catches it. The
+  // scaffolded default CLAUDE_CODE_REVIEW_SHARED_API_TOKEN is anthropic-owned the
+  // same way: it always holds an Anthropic credential (templates/config.jsonc).
+  for (const tokenEnv of [
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN",
+  ]) {
    const r = checkProviderAuth(cfg({ mode: "api-key", provider: "openai", tokenEnv }), {
      [tokenEnv]: `sk-ant-oat01-${"x".repeat(95)}`,
    });
@@ -207,6 +213,16 @@ test("checkProviderAuth: an anthropic entry naming CLAUDE_CODE_OAUTH_TOKEN is st
  expect(r.ok).toBe(true);
 });

+test("checkProviderAuth: the scaffolded default setup (anthropic + shared token env) passes", () => {
+  // The exact shape `ecr init` scaffolds (templates/config.jsonc) — anthropic owns
+  // the shared env, so its own entry must not trip the ownership guard.
+  const r = checkProviderAuth(
+    cfg({ provider: "anthropic", tokenEnv: "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN" }),
+    { CLAUDE_CODE_REVIEW_SHARED_API_TOKEN: `sk-ant-oat01-${"x".repeat(95)}` },
+  );
+  expect(r.ok).toBe(true);
+});
+
 test("checkProviderAuth: an upstream=anthropic alias may name CLAUDE_CODE_OAUTH_TOKEN", () => {
  // upstream is anthropic, so the owner matches the upstream and the token is not
  // being sent to a foreign provider.
@@ -9,11 +9,13 @@ import {
  assertClaudeModels,
  buildClaudeArgs,
  buildEngineMap,
+  claudeActivities,
  claudeCodePromptAndParse,
  claudeSubscriptionActive,
  claudeTemperatureNote,
  claudeTokenCredential,
  classifyClaudeError,
+  createClaudeActivityStream,
  claudeModelId,
  claudeModelMatches,
  engineForModel,
@@ -25,7 +27,14 @@ import {
  usageLimitResetMs,
 } from "../core/claude-code.js";
 import type { ClaudeCodeHandle } from "../core/claude-code.js";
-import { AgentTimeoutError, CLAUDE_CODE_ENGINE, isTransientApiError } from "../core/opencode.js";
+import {
+  AgentTimeoutError,
+  CLAUDE_CODE_ENGINE,
+  isTransientApiError,
+  promptAndParse,
+} from "../core/opencode.js";
+import type { OpencodeHandle } from "../core/opencode.js";
+import { parseReviewerOutput } from "../core/schema.js";
 import { RateLimitWatch } from "../core/throttle.js";
 import type { AuthConfigEntry, LoadedConfig } from "../config/schema.js";

@@ -50,7 +59,7 @@ async function fakeClaude(script: string): Promise<{ bin: string; cleanup: () =>
 }

 /**
- * A fake `claude` that returns a different canned `--output-format json` body on
+ * A fake `claude` that returns a different canned final-result body on
 * each successive invocation (tracked via a counter file, since childEnv is fixed
 * for the whole test) and logs each call's stdin (the prompt actually sent) to
 * `<dir>/stdin.<n>` via `stdinLog(n)` — so a corrective-retry test can assert what
@@ -60,6 +69,7 @@ async function fakeClaude(script: string): Promise<{ bin: string; cleanup: () =>
 async function sequencedFakeClaude(outputs: string[]): Promise<{
  bin: string;
  stdinLog: (n: number) => Promise<string>;
+  argsLog: (n: number) => Promise<string>;
  cleanup: () => Promise<void>;
 }> {
  const dir = await mkdtemp(path.join(tmpdir(), "ecr-claude-code-test-"));
@@ -76,6 +86,7 @@ async function sequencedFakeClaude(outputs: string[]): Promise<{
    "COUNT=$((COUNT + 1))",
    'echo "$COUNT" > "$COUNT_FILE"',
    `cat > "${dir}/stdin.$COUNT"`,
+    `printf '%s\n' "$@" > "${dir}/args.$COUNT"`,
    `if [ "$COUNT" -gt ${outputs.length} ]; then COUNT=${outputs.length}; fi`,
    `cat "${dir}/out.$COUNT"`,
    "",
@@ -85,6 +96,7 @@ async function sequencedFakeClaude(outputs: string[]): Promise<{
  return {
    bin,
    stdinLog: (n: number) => readFile(path.join(dir, `stdin.${n}`), "utf8"),
+    argsLog: (n: number) => readFile(path.join(dir, `args.${n}`), "utf8"),
    cleanup: () => rm(dir, { recursive: true, force: true }),
  };
 }
@@ -206,16 +218,25 @@ test("claudeModelMatches: dated-suffix family match; cross-family mismatch", ()
 });

 test("buildClaudeArgs: read-only, trust-isolated, subscription argv; never --bare", () => {
+  const jsonSchema = {
+    type: "object",
+    properties: { title: { type: "string" } },
+    required: ["title"],
+  };
  const args = buildClaudeArgs({
    model: "claude-opus-5",
    system: "SYS",
    cwd: "/work/repo",
    maxTurns: 60,
+    jsonSchema,
  });
  const joined = args.join(" ");
-  expect(joined).toContain("--output-format json");
+  expect(joined).toContain("--output-format stream-json --verbose");
  expect(joined).toContain("--model claude-opus-5");
  expect(joined).toContain("--append-system-prompt SYS");
+  const schemaIndex = args.indexOf("--json-schema");
+  expect(schemaIndex).toBeGreaterThan(-1);
+  expect(JSON.parse(args[schemaIndex + 1]!)).toEqual(jsonSchema);
  // Read, Grep, AND Glob are all path-scoped to the review tree — a bare Grep
  // would read arbitrary files (credentials, /proc/self/environ) despite the
  // scoped Read, defeating the whole exfiltration defense.
@@ -260,6 +281,144 @@ test("parseClaudeResult: success maps text/cost/tokens/model", () => {
  expect(r.cost).toBe(0.0123);
  expect(r.tokens).toEqual({ input: 100, output: 200, cache: { write: 50, read: 30 } });
  expect(r.modelOutputTokens).toEqual({ "claude-opus-5-20250101": 200 });
+  expect(r.hasStructuredOutput).toBe(false);
+  expect(r.structuredOutputFailure).toBe(false);
+});
+
+test("parseClaudeResult: reads the final result from stream-json JSONL", () => {
+  const stdout = [
+    JSON.stringify({ type: "system", subtype: "init", model: "claude-opus-5" }),
+    JSON.stringify({
+      type: "assistant",
+      message: { content: [{ type: "tool_use", id: "tool-1", name: "Read", input: {} }] },
+    }),
+    JSON.stringify({
+      type: "result",
+      subtype: "success",
+      is_error: false,
+      result: "the findings",
+      total_cost_usd: 0.02,
+      usage: { input_tokens: 12, output_tokens: 34 },
+    }),
+  ].join("\n");
+  const result = parseClaudeResult(stdout);
+  expect(result.isError).toBe(false);
+  expect(result.text).toBe("the findings");
+  expect(result.cost).toBe(0.02);
+  expect(result.tokens).toEqual({
+    input: 12,
+    output: 34,
+    cache: { write: undefined, read: undefined },
+  });
+});
+
+test("parseClaudeResult: prefers provider-validated structured_output", () => {
+  const stdout = JSON.stringify({
+    type: "result",
+    subtype: "success",
+    is_error: false,
+    // Keep a conflicting text result to prove the structured object wins.
+    result: '{"title":"wrong"}',
+    structured_output: { title: "validated" },
+  });
+  const result = parseClaudeResult(stdout);
+  expect(result.isError).toBe(false);
+  expect(JSON.parse(result.text)).toEqual({ title: "validated" });
+  expect(result.hasStructuredOutput).toBe(true);
+});
+
+test("parseClaudeResult: an error ignores stale structured_output", () => {
+  const stdout = JSON.stringify({
+    type: "result",
+    subtype: "error_max_structured_output_retries",
+    is_error: true,
+    result: "Could not produce valid structured output",
+    structured_output: { title: "PR_SECRET rate limit" },
+  });
+  const result = parseClaudeResult(stdout);
+  expect(result.isError).toBe(true);
+  expect(result.errorText).toBe("Could not produce valid structured output");
+  expect(result.errorText).not.toContain("PR_SECRET");
+  expect(result.structuredOutputFailure).toBe(true);
+});
+
+test("claudeActivities: reports lifecycle and safe tool targets, never raw text/results/patterns", () => {
+  expect(
+    claudeActivities({ type: "system", subtype: "init", model: "claude-opus-5" }, "/repo"),
+  ).toEqual([{ line: "started claude-opus-5" }]);
+  expect(
+    claudeActivities(
+      {
+        type: "assistant",
+        message: {
+          content: [
+            { type: "text", text: "secret reasoning" },
+            {
+              type: "tool_use",
+              id: "read-1",
+              name: "Read",
+              input: { file_path: "/repo/src/auth.ts" },
+            },
+            {
+              type: "tool_use",
+              id: "grep-1",
+              name: "Grep",
+              input: { path: "/repo/src", pattern: "DO_NOT_LOG_THIS" },
+            },
+            {
+              type: "tool_use",
+              id: "outside-1",
+              name: "Read",
+              input: { file_path: "/etc/passwd\nforged log line" },
+            },
+            {
+              type: "tool_use",
+              id: "glob-1",
+              name: "Glob",
+              input: { pattern: "SECRET_PATTERN" },
+            },
+          ],
+        },
+      },
+      "/repo",
+    ),
+  ).toEqual([
+    { key: "read-1", line: "Read src/auth.ts" },
+    { key: "grep-1", line: "Grep src" },
+    { key: "outside-1", line: "Read" },
+    { key: "glob-1", line: "Glob" },
+  ]);
+  expect(
+    claudeActivities(
+      { type: "result", is_error: false, duration_ms: 12_400, num_turns: 3 },
+      "/repo",
+    ),
+  ).toEqual([{ line: "completed (12s, 3 turn(s))" }]);
+  expect(
+    claudeActivities(
+      { type: "user", message: { content: [{ type: "tool_result", content: "SECRET" }] } },
+      "/repo",
+    ),
+  ).toEqual([]);
+});
+
+test("createClaudeActivityStream: handles chunk boundaries and dedupes repeated tool ids", () => {
+  const lines: string[] = [];
+  const stream = createClaudeActivityStream("/repo", (line) => lines.push(line));
+  const init = `${JSON.stringify({ type: "system", subtype: "init", model: "claude-opus-5" })}\n`;
+  const tool = JSON.stringify({
+    type: "assistant",
+    message: {
+      content: [
+        { type: "tool_use", id: "tool-1", name: "Read", input: { file_path: "/repo/a.ts" } },
+      ],
+    },
+  });
+  stream.push(init.slice(0, 15));
+  stream.push(`${init.slice(15)}${tool}\n${tool.slice(0, 20)}`);
+  stream.push(tool.slice(20));
+  stream.finish();
+  expect(lines).toEqual(["started claude-opus-5", "Read a.ts"]);
 });

 test("pickAnsweringModel: prefers the requested family over key order; else max output", () => {
@@ -298,7 +457,37 @@ test("parseClaudeResult: is_error true even when subtype stays 'success'", () =>
 test("parseClaudeResult: unparseable stdout is an error, not a throw", () => {
  const r = parseClaudeResult("not json at all");
  expect(r.isError).toBe(true);
-  expect(r.errorText).toBe("not json at all");
+  expect(r.errorText).toBe("Claude Code stream ended without a final result event");
+});
+
+test("parseClaudeResult: a stream without a final result does not expose its transcript", () => {
+  const secret = "PR_SECRET rate limit";
+  const stdout = [
+    JSON.stringify({ type: "system", subtype: "init", model: "claude-opus-5" }),
+    JSON.stringify({
+      type: "user",
+      message: { content: [{ type: "tool_result", content: secret }] },
+    }),
+  ].join("\n");
+  const result = parseClaudeResult(stdout);
+  expect(result.isError).toBe(true);
+  expect(result.errorText).toBe("Claude Code stream ended without a final result event");
+  expect(result.errorText).not.toContain(secret);
+});
+
+test("parseClaudeResult: an error result without a message does not expose its transcript", () => {
+  const secret = "PR_SECRET quota";
+  const stdout = [
+    JSON.stringify({
+      type: "user",
+      message: { content: [{ type: "tool_result", content: secret }] },
+    }),
+    JSON.stringify({ type: "result", subtype: "error", is_error: true, result: "" }),
+  ].join("\n");
+  const result = parseClaudeResult(stdout);
+  expect(result.isError).toBe(true);
+  expect(result.errorText).toBe("Claude Code returned an error without a message");
+  expect(result.errorText).not.toContain(secret);
 });

 test("classifyClaudeError: rate-limit / auth / usage-limit / other", () => {
@@ -663,17 +852,25 @@ test("runClaudePrompt: our own deadline kills the child and throws AgentTimeoutE
  }
 });

-test("runClaudePrompt: a non-timeout signal throws a crash error naming the signal", async () => {
-  const { bin, cleanup } = await fakeClaude("#!/bin/sh\ncat > /dev/null\nkill -9 $$\n");
+test("runClaudePrompt: a non-timeout signal names the signal without exposing stderr", async () => {
+  const secret = "PR_SECRET from stderr";
+  const { bin, cleanup } = await fakeClaude(
+    `#!/bin/sh\ncat > /dev/null\nprintf '%s' '${secret}' >&2\nkill -9 $$\n`,
+  );
  try {
-    await expect(
-      runClaudePrompt(testHandle(bin), {
+    let message = "";
+    try {
+      await runClaudePrompt(testHandle(bin), {
        agent: "reviewer",
        system: "SYS",
        text: "hi",
        title: "t",
-      }),
-    ).rejects.toThrow(/killed by signal SIGKILL/);
+      });
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error);
+    }
+    expect(message).toContain("killed by signal SIGKILL");
+    expect(message).not.toContain(secret);
  } finally {
    await cleanup();
  }
@@ -720,6 +917,115 @@ test("runClaudePrompt: a 429 result dispatches to a rate-limit throw and records
  }
 });

+test("runClaudePrompt: an incomplete stream cannot forge rate-limit evidence or leak tool results", async () => {
+  const secret = "PR_SECRET rate limit quota usage limit reached|1728000000";
+  const body = [
+    JSON.stringify({ type: "system", subtype: "init", model: "claude-opus-5" }),
+    JSON.stringify({
+      type: "user",
+      message: { content: [{ type: "tool_result", content: secret }] },
+    }),
+  ].join("\n");
+  const { bin, cleanup } = await fakeClaude(`#!/bin/sh\ncat > /dev/null\nprintf '%s' '${body}'\n`);
+  try {
+    const handle = testHandle(bin);
+    let message = "";
+    try {
+      await runClaudePrompt(handle, {
+        agent: "reviewer",
+        system: "SYS",
+        text: "hi",
+        title: "t",
+      });
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error);
+    }
+    expect(message).toContain("stream ended without a final result event");
+    expect(message).toContain("Claude Code exited with code 0");
+    expect(message).not.toContain(secret);
+    expect(handle.rateLimit.events).toBe(0);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("runClaudePrompt: an early bad-flag failure reports a safe fixed diagnostic", async () => {
+  const secret = "PR_SECRET from stderr";
+  const { bin, cleanup } = await fakeClaude(
+    `#!/bin/sh\ncat > /dev/null\nprintf '%s' "error: unknown option '--json-schema' ${secret}" >&2\nexit 2\n`,
+  );
+  try {
+    let message = "";
+    try {
+      await runClaudePrompt(testHandle(bin), {
+        agent: "reviewer",
+        system: "SYS",
+        text: "hi",
+        title: "t",
+      });
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error);
+    }
+    expect(message).toContain("Claude Code exited with code 2");
+    expect(message).toContain("CLI rejected its arguments");
+    expect(message).toContain("verify the pinned @anthropic-ai/claude-code version");
+    expect(message).not.toContain("--json-schema");
+    expect(message).not.toContain(secret);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("runClaudePrompt: an early auth failure names the fix without copying stderr", async () => {
+  const secret = "PR_SECRET from auth stderr";
+  const { bin, cleanup } = await fakeClaude(
+    `#!/bin/sh\ncat > /dev/null\nprintf '%s' 'OAuth authentication failed: ${secret}' >&2\nexit 1\n`,
+  );
+  try {
+    let message = "";
+    try {
+      await runClaudePrompt(testHandle(bin), {
+        agent: "reviewer",
+        system: "SYS",
+        text: "hi",
+        title: "t",
+      });
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error);
+    }
+    expect(message).toContain("Claude Code exited with code 1");
+    expect(message).toContain("authentication failed before a result was emitted");
+    expect(message).toContain("`claude auth status` and `ecr doctor`");
+    expect(message).not.toContain(secret);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("runClaudePrompt: unknown early stderr is never copied into the failure", async () => {
+  const secret = "PR_SECRET arbitrary diagnostic";
+  const { bin, cleanup } = await fakeClaude(
+    `#!/bin/sh\ncat > /dev/null\nprintf '%s' '${secret}' >&2\nexit 7\n`,
+  );
+  try {
+    let message = "";
+    try {
+      await runClaudePrompt(testHandle(bin), {
+        agent: "reviewer",
+        system: "SYS",
+        text: "hi",
+        title: "t",
+      });
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error);
+    }
+    expect(message).toContain("Claude Code exited with code 7");
+    expect(message).not.toContain(secret);
+  } finally {
+    await cleanup();
+  }
+});
+
 test("runClaudePrompt: a usage-limit result throws the non-retryable, reset-time-carrying message", async () => {
  const body = JSON.stringify({
    type: "result",
@@ -743,6 +1049,53 @@ test("runClaudePrompt: a usage-limit result throws the non-retryable, reset-time
  }
 });

+test("runClaudePrompt: streams safe tool activity while preserving the final result", async () => {
+  const body = [
+    JSON.stringify({ type: "system", subtype: "init", model: "claude-opus-5" }),
+    JSON.stringify({
+      type: "assistant",
+      message: {
+        content: [
+          {
+            type: "tool_use",
+            id: "read-1",
+            name: "Read",
+            input: { file_path: process.cwd() + "/src/core/auth.ts" },
+          },
+        ],
+      },
+    }),
+    JSON.stringify({
+      type: "result",
+      subtype: "success",
+      is_error: false,
+      result: "the findings",
+      duration_ms: 2500,
+      num_turns: 2,
+      total_cost_usd: 0.01,
+    }),
+  ].join("\n");
+  const { bin, cleanup } = await fakeClaude(`#!/bin/sh\ncat > /dev/null\nprintf '%s' '${body}'\n`);
+  try {
+    const activity: string[] = [];
+    const result = await runClaudePrompt(testHandle(bin), {
+      agent: "reviewer",
+      system: "SYS",
+      text: "hi",
+      title: "t",
+      onActivity: (line) => activity.push(line),
+    });
+    expect(result.text).toBe("the findings");
+    expect(activity).toEqual([
+      "started claude-opus-5",
+      "Read src/core/auth.ts",
+      "completed (3s, 2 turn(s))",
+    ]);
+  } finally {
+    await cleanup();
+  }
+});
+
 test("claudeCodePromptAndParse: a parseable first reply returns immediately with truncated:false", async () => {
  const body = JSON.stringify({
    type: "result",
@@ -773,6 +1126,146 @@ test("claudeCodePromptAndParse: a parseable first reply returns immediately with
  }
 });

+test("promptAndParse: a Claude-routed production parser forwards its JSON Schema", async () => {
+  const body = JSON.stringify({
+    type: "result",
+    subtype: "success",
+    is_error: false,
+    result: '{"findings":[]}',
+    structured_output: { findings: [] },
+  });
+  const { bin, argsLog, cleanup } = await sequencedFakeClaude([body]);
+  try {
+    const output = await promptAndParse(
+      testHandle(bin) as unknown as OpencodeHandle,
+      { agent: "reviewer", system: "SYS", text: "hi", title: "t" },
+      parseReviewerOutput,
+    );
+    expect(output.value).toEqual({ findings: [] });
+
+    const args = (await argsLog(1)).split("\n");
+    const schemaIndex = args.indexOf("--json-schema");
+    expect(schemaIndex).toBeGreaterThan(-1);
+    const schema = JSON.parse(args[schemaIndex + 1]!) as {
+      properties: { findings: { items: { required: string[] } } };
+    };
+    expect(schema.properties.findings.items.required).toContain("title");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("promptAndParse: Claude structured-output exhaustion retries once and preserves usage", async () => {
+  const exhausted = JSON.stringify({
+    type: "result",
+    subtype: "error_max_structured_output_retries",
+    is_error: true,
+    result: "Could not produce valid structured output",
+    total_cost_usd: 0.01,
+    usage: { input_tokens: 5, output_tokens: 7 },
+  });
+  const recovered = JSON.stringify({
+    type: "result",
+    subtype: "success",
+    is_error: false,
+    result: "ignored in structured mode",
+    structured_output: { findings: [] },
+    total_cost_usd: 0.03,
+    usage: { input_tokens: 11, output_tokens: 13 },
+  });
+  const { bin, stdinLog, cleanup } = await sequencedFakeClaude([exhausted, recovered]);
+  try {
+    const activity: string[] = [];
+    const output = await promptAndParse(
+      testHandle(bin) as unknown as OpencodeHandle,
+      {
+        agent: "security",
+        system: "SYS",
+        text: "review",
+        title: "security review",
+        onActivity: (line) => activity.push(line),
+      },
+      parseReviewerOutput,
+    );
+    expect(output.value).toEqual({ findings: [] });
+    expect(output.cost).toBeCloseTo(0.04);
+    expect(output.tokens).toEqual({
+      input: 16,
+      output: 20,
+      reasoning: 0,
+      cache: { read: 0, write: 0 },
+    });
+    expect(activity).toContain("structured output validation failed — retrying once");
+    expect(await stdinLog(2)).toContain("IMPORTANT: reply with ONLY the single JSON object");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("claudeCodePromptAndParse: schema mode never accepts result text without structured_output", async () => {
+  const unvalidated = JSON.stringify({
+    type: "result",
+    subtype: "success",
+    is_error: false,
+    result: JSON.stringify({ ok: "unvalidated" }),
+  });
+  const validated = JSON.stringify({
+    type: "result",
+    subtype: "success",
+    is_error: false,
+    result: JSON.stringify({ ok: "wrong-channel" }),
+    structured_output: { ok: "validated" },
+  });
+  const { bin, cleanup } = await sequencedFakeClaude([unvalidated, validated]);
+  try {
+    const output = await claudeCodePromptAndParse(
+      testHandle(bin),
+      {
+        agent: "reviewer",
+        system: "SYS",
+        text: "hi",
+        title: "t",
+        jsonSchema: {
+          type: "object",
+          properties: { ok: { type: "string" } },
+          required: ["ok"],
+        },
+      },
+      (text) => JSON.parse(text) as { ok: string },
+    );
+    expect(output.value).toEqual({ ok: "validated" });
+  } finally {
+    await cleanup();
+  }
+});
+
+test("claudeCodePromptAndParse: repeated structured-output exhaustion fails explicitly", async () => {
+  const exhausted = JSON.stringify({
+    type: "result",
+    subtype: "error_max_structured_output_retries",
+    is_error: true,
+    result: "Could not produce valid structured output",
+  });
+  const { bin, cleanup } = await sequencedFakeClaude([exhausted, exhausted]);
+  try {
+    await expect(
+      claudeCodePromptAndParse(
+        testHandle(bin),
+        {
+          agent: "security",
+          system: "SYS",
+          text: "review",
+          title: "security review",
+          jsonSchema: { type: "object", required: ["findings"] },
+        },
+        parseReviewerOutput,
+      ),
+    ).rejects.toThrow(/could not satisfy its required JSON Schema after retries/);
+  } finally {
+    await cleanup();
+  }
+});
+
 test("claudeCodePromptAndParse: an unparseable first reply retries with CLAUDE_CORRECTIVE appended, accumulating cost/tokens across both calls", async () => {
  const bad = JSON.stringify({
    type: "result",
@@ -69,6 +69,8 @@ test("isCodeCitation separates paths from prose tokens", () => {
    "src/entities/oauth/",
    ".github/workflows/**",
    "*PrivacyPolicy.ts",
+    "castai-spot.tf",
+    "*/.terraform.lock.hcl",
  ]) {
    expect(isCodeCitation(token)).toBe(true);
  }
@@ -248,6 +250,67 @@ test("the ref the message suggests silences the citation it was suggested for",
  }
 });

+test("a scope-relative citation WITH an extension is covered by its precise ref", async () => {
+  const files = (pin: string): Record<string, string> => ({
+    "infrastructure/pgbouncer/base/pdb.yaml": "kind: PodDisruptionBudget\n",
+    "server/www/k8s/pdb.yaml": "kind: PodDisruptionBudget\n",
+    "infrastructure/.expo-code-review/config.jsonc": "{}\n",
+    "infrastructure/.expo-code-review/agents/k8s.md": `${pin}\n\nSee \`pgbouncer/base/pdb.yaml\`.\n`,
+  });
+
+  const unpinned = await checkConfigRefs({ root: await makeRepo(files("")) });
+  expect(unpinned.problems).toHaveLength(1);
+  // the suggestion is the precise path, never a basename glob
+  expect(unpinned.problems[0]!.problem).toContain(
+    `${REF} infrastructure/pgbouncer/base/pdb.yaml —`,
+  );
+
+  const pinned = await checkConfigRefs({
+    root: await makeRepo(
+      files(`<!-- ${REF} infrastructure/pgbouncer/base/pdb.yaml — the PDB this rule is about -->`),
+    ),
+  });
+  expect(pinned.problems).toEqual([]);
+});
+
+test("a scope-relative wildcard token gets a glob suggestion that itself resolves", async () => {
+  const files = (pin: string): Record<string, string> => ({
+    "infra/pgbouncer/production/patch.yaml": "x\n",
+    "infra/.expo-code-review/config.jsonc": "{}\n",
+    "infra/.expo-code-review/agents/a.md": `${pin}\nSee \`pgbouncer/*/patch.yaml\`.\n`,
+  });
+  const report = await checkConfigRefs({ root: await makeRepo(files("")) });
+  expect(report.problems).toHaveLength(1);
+  expect(report.problems[0]!.problem).toContain(`${REF} glob:infra/pgbouncer/*/patch.yaml`);
+  // …and that suggestion, once written, clears the citation and resolves
+  const pinned = await checkConfigRefs({
+    root: await makeRepo(files(`<!-- ${REF} glob:infra/pgbouncer/*/patch.yaml — the patches -->`)),
+  });
+  expect(pinned.problems).toEqual([]);
+});
+
+test("scope wins over root when both could satisfy an extensionless citation", async () => {
+  const root = await makeRepo({
+    "alerts/root.txt": "x\n",
+    "infra/alerts/scope.tf": "y\n",
+    "infra/.expo-code-review/config.jsonc": "{}\n",
+    "infra/.expo-code-review/agents/a.md": "Watch `alerts/` closely.\n",
+  });
+  const report = await checkConfigRefs({ root });
+  expect(report.problems).toHaveLength(1);
+  expect(report.problems[0]!.problem).toContain(`${REF} infra/alerts/ —`);
+});
+
+test("a token carrying its own wildcard keeps the glob suggestion", async () => {
+  const root = await makeRepo({
+    ".github/workflows/deploy.yml": "on: push\n",
+    ".expo-code-review/config.jsonc": "{}\n",
+    ".expo-code-review/agents/sec.md": "Changes under `.github/workflows/**` are high risk.\n",
+  });
+  const report = await checkConfigRefs({ root });
+  expect(report.problems[0]!.problem).toContain(`${REF} glob:.github/workflows/**`);
+});
+
 test("a scope-relative annotated ref is broken, and names the root-relative fix", async () => {
  const root = await makeRepo({
    "infrastructure/general-central/module/main.tf": "resource {}\n",
@@ -409,6 +472,27 @@ test("reviewSetupRefNotes advises on broken refs and on cited code the PR change
  ).toEqual([]);
 });

+test("a ref to scrubbed ambient config is not review advice (the read root removes it)", async () => {
+  const root = await makeRepo(
+    setup({
+      "src/auth.ts": "export const a = 1;\n",
+      ".expo-code-review/shared.md":
+        `<!-- ${REF} AGENTS.md — the conventions to judge against -->\n` +
+        `<!-- ${REF} CLAUDE.md#conventions — same, with an anchor -->\n` +
+        `<!-- ${REF} glob:**/.env.local — same, as a glob -->\n` +
+        `<!-- ${REF} src/gone.ts — really moved -->\n`,
+    }),
+  );
+  const setupDir = path.join(root, ".expo-code-review");
+  const notes = await reviewSetupRefNotes({ root, setupDirs: [setupDir], changedFiles: [] });
+  expect(notes).toHaveLength(1);
+  expect(notes[0]).toContain("1 ref(s)");
+  expect(notes[0]).not.toContain("shared.md:1");
+
+  // The standalone gate still reports all of them — there the tree is a real checkout.
+  expect((await checkConfigRefs({ root })).problems).toHaveLength(4);
+});
+
 test("setup problems are labelled by setup-dir position when the config lives outside the tree", async () => {
  const code = await makeRepo({ "src/auth.ts": "export const a = 1;\n" });
  const trustedBase = await makeRepo(
@@ -21,6 +21,27 @@ test("run with input: feeds stdin through the spawn path", async () => {
  expect(result.overflowed).toBeFalsy();
 });

+test("run with input: observes admitted stdout incrementally without changing capture", async () => {
+  const observed: string[] = [];
+  const result = await run("sh", ["-c", "printf first; sleep 0.05; printf second"], {
+    input: "",
+    onStdout: (chunk) => observed.push(chunk),
+  });
+  expect(result.stdout).toBe("firstsecond");
+  expect(observed.join("")).toBe(result.stdout);
+});
+
+test("run with input: a stdout observer failure never breaks the command", async () => {
+  const result = await run("printf", ["safe"], {
+    input: "",
+    onStdout: () => {
+      throw new Error("observer failed");
+    },
+  });
+  expect(result.stdout).toBe("safe");
+  expect(result.code).toBe(0);
+});
+
 test("run with input: timeout kills the child and resolves timedOut (no throw)", async () => {
  const started = Date.now();
  const result = await run("sleep", ["30"], { input: "", timeout: 250, check: true });
@@ -50,17 +71,23 @@ test("run with input: timeout kills the whole process group, not just the direct

 test("run with input: escalates to SIGKILL after the grace period when the child traps SIGTERM", async () => {
  const started = Date.now();
-  const result = await run(
-    "node",
-    ["-e", "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000);"],
-    { input: "", timeout: 250, check: true },
-  );
+  // The deadline timer starts at spawn, so the child must have SIGTERM ignored
+  // before it fires or the default disposition kills it and this never reaches
+  // the escalation path. `sh` with an ignoring `trap` is the cheapest way there:
+  // it boots in ~1ms (a node runtime takes far longer, and lost this race on a
+  // loaded CI runner), and an *ignored* signal survives `exec` where an
+  // installed handler would not — so the `sleep` holding the group ignores it too.
+  const result = await run("sh", ["-c", 'trap "" TERM; exec sleep 30'], {
+    input: "",
+    timeout: 1000,
+    check: true,
+  });
  expect(result.timedOut).toBe(true);
-  // SIGTERM alone never ends a process that traps it; only the 5s grace-timer
+  // SIGTERM alone never ends a process that ignores it; only the 5s grace-timer
  // SIGKILL escalation does, so a duration past that proves the path fired.
-  expect(Date.now() - started).toBeGreaterThanOrEqual(5000);
-  expect(Date.now() - started).toBeLessThan(10_000);
-}, 10_000);
+  expect(Date.now() - started).toBeGreaterThanOrEqual(6000);
+  expect(Date.now() - started).toBeLessThan(14_000);
+}, 20_000);

 test("run without input: timeout resolves timedOut too (execFile path, same contract)", async () => {
  const started = Date.now();
@@ -70,12 +97,17 @@ test("run without input: timeout resolves timedOut too (execFile path, same cont
 });

 test("run with input: maxBuffer overflow is flagged, not silently truncated", async () => {
+  let observed = "";
  const result = await run("sh", ["-c", "head -c 100000 /dev/zero | tr '\\0' 'x'"], {
    input: "",
    maxBuffer: 1024,
    check: false,
+    onStdout: (chunk) => {
+      observed += chunk;
+    },
  });
  expect(result.overflowed).toBe(true);
+  expect(observed.length).toBe(1024);
 });

 test("run with input: check=false returns a non-zero exit instead of throwing", async () => {
@@ -132,7 +132,7 @@ test("init --token-env refuses when review workflows already exist without --for
    path.join(root, ".github", "workflows", "expo-code-review.yml"),
    "utf8",
  );
-  expect(text).toContain("OPENAI_API_KEY");
+  expect(text).toContain("CLAUDE_CODE_REVIEW_SHARED_API_TOKEN");
  expect(text).not.toContain("CLAUDE_CODE_OAUTH_TOKEN");
 });

@@ -143,7 +143,7 @@ test("init --token-env --force rewrites existing review workflows", async () =>
  for (const file of ["expo-code-review.yml", "expo-code-review-command.yml"]) {
    const text = await readFile(path.join(root, ".github", "workflows", file), "utf8");
    expect(text).toContain("CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}");
-    expect(text).not.toContain("OPENAI_API_KEY");
+    expect(text).not.toContain("CLAUDE_CODE_REVIEW_SHARED_API_TOKEN");
  }
 });

@@ -210,7 +210,7 @@ test("init --force-workflows refuses when only the forwarded secret line is non-
  // The fallback alone reads as default, so the guard must also see the secret line.
  const wf = path.join(root, ".github", "workflows", "expo-code-review.yml");
  const patched = (await readFile(wf, "utf8")).replaceAll(
-    "OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}",
+    "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN: ${{ secrets.CLAUDE_CODE_REVIEW_SHARED_API_TOKEN }}",
    "ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}",
  );
  await writeFile(wf, patched, "utf8");
@@ -220,7 +220,7 @@ test("init --force-workflows refuses when only the forwarded secret line is non-
  process.exitCode = 0;
  expect(err).toContain("ANTHROPIC_API_KEY");
  expect(err).toContain("--token-env");
-  // Untouched: no silent reversion to the default OpenAI wiring.
+  // Untouched: no silent reversion to the default wiring.
  expect(await readFile(wf, "utf8")).toContain(
    "ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}",
  );
@@ -229,7 +229,7 @@ test("init --force-workflows refuses when only the forwarded secret line is non-
 test("init --force-workflows without --token-env is fine on a default-credential repo", async () => {
  const root = await freshRepo();
  await initCommand([]);
-  // Default OPENAI_API_KEY wiring: nothing to revert, so no refusal.
+  // Default credential wiring: nothing to revert, so no refusal.
  await initCommand(["--force-workflows"]);
  expect(process.exitCode ?? 0).toBe(0);
  expect(
@@ -240,8 +240,8 @@ test("init --force-workflows without --token-env is fine on a default-credential
 test("init --token-env prints the config.jsonc auth edit as a next step", async () => {
  await freshRepo();
  const out = await captureStdout(() => initCommand(["--token-env", "CLAUDE_CODE_OAUTH_TOKEN"]));
-  // The scaffolded config.jsonc still declares OPENAI_API_KEY, so without this
-  // step CI's verify-config fails and the user has no pointer to why.
+  // The scaffolded config.jsonc still declares the default tokenEnv, so without
+  // this step CI's verify-config fails and the user has no pointer to why.
  expect(out).toContain("config.jsonc at this credential");
  expect(out).toContain("refuses to review until the config names `CLAUDE_CODE_OAUTH_TOKEN`");
 });
@@ -275,7 +275,7 @@ test("substituteTokenEnv fails loudly when the template markers drift", () => {
 });

 test("parseTokenEnvs validates names and refuses well-known unrelated secrets", () => {
-  expect(parseTokenEnvs(undefined)).toEqual(["OPENAI_API_KEY"]);
+  expect(parseTokenEnvs(undefined)).toEqual(["CLAUDE_CODE_REVIEW_SHARED_API_TOKEN"]);
  expect(parseTokenEnvs("A_TOKEN, B_TOKEN")).toEqual(["A_TOKEN", "B_TOKEN"]);
  expect(() => parseTokenEnvs("lower_case")).toThrow(/UPPER_SNAKE_CASE/);
  expect(() => parseTokenEnvs("GH_TOKEN")).toThrow(/unrelated secret/);
@@ -87,13 +87,17 @@ test("aggregate: default scope uses plain fingerprints, non-default uses scoped

 test("aggregate: state round-trips through parseReviewState (scopes intact); a v1 body still parses", () => {
  const results = [
-    scope("default", true, { findings: [finding({ title: "D" })] }),
-    scope("api", false, { findings: [finding({ title: "W" })] }),
+    {
+      ...scope("default", true, { findings: [finding({ title: "D" })] }),
+      inputHash: "a".repeat(64),
+    },
+    { ...scope("api", false, { findings: [finding({ title: "W" })] }), inputHash: "b".repeat(64) },
  ];
  const body = renderAggregateMarkdown(results, "tag", []);
  const state = parseReviewState(body, "tag");
  expect(state).not.toBeNull();
  expect(state!.scopes?.map((s) => s.scope)).toEqual(["default", "api"]);
+  expect(state!.scopes?.map((s) => s.inputHash)).toEqual(["a".repeat(64), "b".repeat(64)]);

  // A pre-routing v1 comment still parses (no scopes field).
  const v1 = renderMarkdown(review({ findings: [finding()] }), "tag");
@@ -249,7 +253,12 @@ test("aggregate: the /undismiss pin set survives a render with no records and a
    }),
  );
  const big = renderAggregateMarkdown(
-    [scope("api", false, { decision: "request_changes", findings: [pinned, ...many] })],
+    [
+      {
+        ...scope("api", false, { decision: "request_changes", findings: [pinned, ...many] }),
+        inputHash: "c".repeat(64),
+      },
+    ],
    "tag",
    [],
    undefined,
@@ -259,4 +268,5 @@ test("aggregate: the /undismiss pin set survives a render with no records and a
  );
  expect(big.length).toBeLessThan(65_000);
  expect(parseReviewState(big, "tag")!.pins).toEqual(pins);
+  expect(parseReviewState(big, "tag")!.scopes![0]!.inputHash).toBeUndefined();
 });
@@ -70,6 +70,14 @@ test("review state (review + dismissals) round-trips via parseReviewState", () =
  expect(state!.review.findings.length).toBe(1);
 });

+test("review input hash round-trips only in hidden comment state", () => {
+  const inputHash = "a".repeat(64);
+  const body = renderMarkdown(base, "tag", [], undefined, [], [], inputHash);
+  expect(parseReviewState(body, "tag")!.inputHash).toBe(inputHash);
+  expect(Buffer.from(inputHash).toString("base64")).not.toBe(inputHash);
+  expect(body).not.toContain(inputHash);
+});
+
 test("links a finding location to the PR diff line when the line is in the diff", () => {
  const out = renderMarkdown(
    { ...base, findings: [finding({ file: "src/a.ts", line: 12 })] },
@@ -0,0 +1,173 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import type { LoadedConfig } from "../config/schema.js";
+import { reviewCanBeReused, reviewInputHash, reviewMatchesInput } from "../core/review-cache.js";
+import type { CoordinatorOutput, DiffEntry } from "../core/schema.js";
+
+const config = (over: Partial<LoadedConfig> = {}): LoadedConfig => ({
+  configDir: "/tmp/config-a",
+  sharedPromptText: "shared rules",
+  agents: [
+    {
+      id: "correctness",
+      description: "bugs",
+      alwaysRun: false,
+      model: "anthropic/claude-sonnet-5",
+      temperature: 0.1,
+      tools: { read: true },
+      promptText: "find bugs",
+    },
+  ],
+  coordinator: {
+    model: "anthropic/claude-sonnet-5",
+    temperature: 0,
+    promptText: "dedupe",
+  },
+  policy: { includeSuggestions: false },
+  chunk: { maxChangedLines: 1000, maxFiles: 20 },
+  noise: { additionalIgnores: [], additionalMarkers: [] },
+  breakGlassMarker: "/skip-review",
+  commentTag: "review",
+  auth: [{ provider: "anthropic", mode: "oauth", tokenEnv: "TOKEN" }],
+  review: { trigger: "all", label: "ai-review", skipLabel: "ai-review:skip" },
+  stack: {
+    enabled: false,
+    maxDepth: 4,
+    maxPrs: 8,
+    maxFilesPerPr: 100,
+    requireSameAuthor: true,
+    confirmWithPatch: false,
+    maxConfirmations: 10,
+  },
+  feedback: {
+    mode: "annotate",
+    match: "both",
+    dismiss: "never",
+    protectedCategories: ["security", "secrets"],
+    maxAdjudications: 10,
+  },
+  ...over,
+});
+
+const files: DiffEntry[] = [
+  {
+    path: "b.ts",
+    patch: "diff --git a/b.ts b/b.ts\nindex 111..222 100644\n@@ -1 +1 @@\n-old\n+new",
+    status: "M",
+  },
+  { path: "a.ts", patch: "diff --git a/a.ts b/a.ts\n@@ -0,0 +1 @@\n+export {};", status: "A" },
+];
+
+async function fixtureRoot(): Promise<string> {
+  const root = await mkdtemp(path.join(tmpdir(), "ecr-review-cache-test-"));
+  await mkdir(root, { recursive: true });
+  await Promise.all([
+    writeFile(path.join(root, "a.ts"), "export {};\n"),
+    writeFile(path.join(root, "b.ts"), "new\n"),
+  ]);
+  return root;
+}
+
+const hash = (
+  readRoot: string,
+  over: Partial<Parameters<typeof reviewInputHash>[0]> = {},
+): Promise<string> =>
+  reviewInputHash({
+    files,
+    config: config(),
+    metadata: { title: "Change", body: "Why" },
+    readRoot,
+    agents: ["security", "correctness"],
+    route: true,
+    contextText: "plan",
+    ...over,
+  });
+
+test("review input hash ignores restack-only blob ids, hunk offsets, and ordering", async () => {
+  const root = await fixtureRoot();
+  try {
+    const first = await hash(root);
+    const restacked = files.map((file) =>
+      file.path === "b.ts"
+        ? { ...file, patch: file.patch.replace("111..222", "aaa..bbb").replace("-1 +1", "-9 +9") }
+        : file,
+    );
+    const second = await hash(root, {
+      files: restacked.reverse(),
+      config: config({ configDir: "/another/ephemeral/base-worktree" }),
+      agents: ["correctness", "security"],
+    });
+    expect(first).toBe(second);
+    expect(first).toMatch(/^[a-f0-9]{64}$/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("review input hash changes with code, prompts, PR prose, selection, or context", async () => {
+  const root = await fixtureRoot();
+  try {
+    const original = await hash(root);
+    expect(
+      await hash(root, { files: [{ ...files[0]!, patch: "+different" }, files[1]!] }),
+    ).not.toBe(original);
+    await writeFile(path.join(root, "b.ts"), "different\n");
+    expect(await hash(root)).not.toBe(original);
+    await writeFile(path.join(root, "b.ts"), "new\n");
+    expect(await hash(root, { config: config({ sharedPromptText: "new rules" }) })).not.toBe(
+      original,
+    );
+    expect(await hash(root, { metadata: { title: "Renamed", body: "Why" } })).not.toBe(original);
+    expect(await hash(root, { agents: ["correctness"] })).not.toBe(original);
+    expect(await hash(root, { route: false })).not.toBe(original);
+    expect(await hash(root, { contextText: "new plan" })).not.toBe(original);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+const review = (over: Partial<CoordinatorOutput> = {}): CoordinatorOutput => ({
+  decision: "approve",
+  findings: [],
+  summary: "ok",
+  incomplete: [],
+  ...over,
+});
+
+test("only a complete review with the exact stored hash can be reused", async () => {
+  const root = await fixtureRoot();
+  try {
+    const current = await hash(root);
+    expect(reviewCanBeReused(review())).toBe(true);
+    expect(reviewMatchesInput(review(), current, current)).toBe(true);
+    expect(reviewMatchesInput(review(), "bad", current)).toBe(false);
+    expect(reviewMatchesInput(review({ incomplete: ["timed out"] }), current, current)).toBe(false);
+    expect(reviewMatchesInput(review({ couldNotComplete: true }), current, current)).toBe(false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("file hashing refuses traversal and never follows a PR-controlled symlink", async () => {
+  const root = await fixtureRoot();
+  const outside = path.join(path.dirname(root), `${path.basename(root)}-secret`);
+  try {
+    await writeFile(outside, "secret one\n");
+    await symlink(outside, path.join(root, "link"));
+    const link: DiffEntry = { path: "link", patch: "diff --git a/link b/link", status: "A" };
+    const first = await hash(root, { files: [link] });
+    await writeFile(outside, "secret two\n");
+    expect(await hash(root, { files: [link] })).toBe(first);
+    await expect(
+      hash(root, {
+        files: [{ path: "../outside", patch: "diff --git a/x b/x", status: "A" }],
+      }),
+    ).rejects.toThrow("escapes the PR tree");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(outside, { force: true });
+  }
+});
@@ -11,6 +11,7 @@ import {
  formatUsageSummary,
  renderUsageMarkdown,
  effectiveConcurrency,
+  formatAgentActivity,
 } from "../core/review.js";
 import type { LoadedConfig } from "../config/schema.js";
 import type { PatchWorkspaceFile } from "../core/noise.js";
@@ -51,6 +52,28 @@ test("chunkByLines: a single over-budget file is its own chunk", () => {
  expect(chunks.map((c) => c.map((f) => f.path))).toEqual([["big"], ["small"]]);
 });

+test("formatAgentActivity: stable agent tag leads every line and pass detail stays visible", () => {
+  expect(formatAgentActivity("security", "security", "Read src/auth.ts")).toBe(
+    "  [security] Read src/auth.ts",
+  );
+  expect(formatAgentActivity("correctness", "correctness [2/3]", "Grep src")).toBe(
+    "  [correctness] [2/3]: Grep src",
+  );
+  expect(formatAgentActivity("cross-cutting", "cross-file", "still working…\n45s")).toBe(
+    "  [cross-cutting] cross-file: still working… 45s",
+  );
+  expect(formatAgentActivity("correctness", "correctness [1/2]", "FAILED (bad output)")).toBe(
+    "  [correctness] [1/2]: FAILED (bad output)",
+  );
+  expect(
+    formatAgentActivity(
+      "security",
+      "security [2/2]",
+      "exceeded 15m — retrying 3 files with a fast no-tools pass",
+    ),
+  ).toBe("  [security] [2/2]: exceeded 15m — retrying 3 files with a fast no-tools pass");
+});
+
 test("applyReviewPolicy: drops suggestions, sorts by severity", () => {
  const out: CoordinatorOutput = {
    decision: "request_changes",
@@ -5,6 +5,7 @@ import {
  fingerprintFinding,
  parseCoordinatorOutput,
  parseReviewerOutput,
+  parseVerdict,
 } from "../core/schema.js";
 import type { Finding } from "../core/schema.js";

@@ -80,6 +81,31 @@ test("a forged `agent` in model output is dropped at the parse boundary", () =>
  expect(attributed[0]!.agent).toBe("correctness");
 });

+test("structured parsers expose draft-07 contracts for provider-side validation", () => {
+  const reviewer = parseReviewerOutput.jsonSchema as {
+    $schema: string;
+    properties: {
+      findings: { items: { properties: Record<string, unknown>; required: string[] } };
+    };
+  };
+  expect(reviewer.$schema).toBe("http://json-schema.org/draft-07/schema#");
+  expect(reviewer.properties.findings.items.required).toContain("title");
+  expect(reviewer.properties.findings.items.properties.agent).toBeUndefined();
+
+  const coordinator = parseCoordinatorOutput.jsonSchema as {
+    properties: Record<string, unknown>;
+    required: string[];
+  };
+  expect(coordinator.required).toEqual(["decision", "findings", "summary"]);
+  expect(coordinator.properties.incomplete).toBeUndefined();
+  expect(coordinator.properties.couldNotComplete).toBeUndefined();
+
+  expect(parseVerdict.jsonSchema).toMatchObject({
+    type: "object",
+    required: ["verified", "reason"],
+  });
+});
+
 test("extractJsonObject: an empty response names the cause instead of 'undefined'", () => {
  expect(() => extractJsonObject("")).toThrow(/an EMPTY response/);
  expect(() => extractJsonObject("prose with no json at all")).toThrow(/no \{\.\.\.\}/);
@@ -23,12 +23,13 @@ import { repoRoot, resolveTrustedTool, run } from "../core/exec.js";
 import { errorMessage, publicFailureReason } from "../core/util.js";
 import { readContextFile } from "../core/context-file.js";
 import { buildDiffLineIndex } from "../core/render.js";
-import type { LinkContext, ScopeReviewResult } from "../core/render.js";
+import type { LinkContext, ReviewState, ScopeReviewResult } from "../core/render.js";
 import type { CoordinatorOutput, FeedbackPin, FeedbackRecord, Finding } from "../core/schema.js";
 import { applyPins, collectPins, scopedFingerprint } from "../core/schema.js";
 import { dropStaleVerdict, feedbackApplied, feedbackNeedsRunSeam } from "../core/adjudicate.js";
 import { runReview } from "../core/review.js";
 import type { ReviewRunOptions, ReviewRunResult } from "../core/review.js";
+import { reviewCanBeReused, reviewInputHash, reviewMatchesInput } from "../core/review-cache.js";
 import { GitHubPRSource } from "../sources/github-pr.js";
 import { memoizeSource, stackConfirmFromConfig, stackWalkFromConfig } from "../sources/source.js";
 import type { PreparedReadRoot, ReviewSource, StackWalkOptions } from "../sources/source.js";
@@ -540,9 +541,11 @@ async function runLegacyCi(
  // unchanged (see mergeFeedback). Memoized on the source — no extra API call. A
  // metadata failure leaves it unknown, which re-judges replies instead of trusting a
  // verdict against source we cannot pin.
+  let metadata: Awaited<ReturnType<ReviewSource["getMetadata"]>> | undefined;
  let headSha: string | undefined;
  try {
-    headSha = (await source.getMetadata()).headOid;
+    metadata = await source.getMetadata();
+    headSha = metadata.headOid;
  } catch {
    // leave headSha unset → stored verdicts do not carry (fail safe, costs budget only)
  }
@@ -569,24 +572,76 @@ async function runLegacyCi(
    );
  }

+  const stack = resolveStackWalk(config.stack, noStackAware);
+  const stackConfirm = resolveStackConfirm(config.stack, noStackAware);
+  const feedback = adjudicationSeam(config, reporter);
+  // Dynamic stack context and model-backed reply adjudication have inputs outside
+  // the scoped diff. Keep those paths fresh until their inputs join the cache key.
+  // A maintainer's explicit /review is also always a real rerun.
+  const cacheAllowed = !bypassTriggerGate && !stack && !feedback && metadata !== undefined;
+  let inputHash: string | undefined;
+
  try {
+    if (cacheAllowed) {
+      try {
+        const prepared = await source.prepareReadRootAsync?.();
+        try {
+          inputHash = await reviewInputHash({
+            files: await source.getChangedFiles(),
+            config,
+            metadata: metadata!,
+            readRoot: prepared?.dir ?? cwd,
+            agents,
+            route,
+            contextText,
+          });
+        } finally {
+          await prepared?.cleanup();
+        }
+      } catch (error) {
+        process.stderr.write(
+          `CI reviewer: could not hash the review input (continuing fresh): ${errorMessage(error)}\n`,
+        );
+      }
+      if (inputHash) {
+        try {
+          const prior = await reporter.readState();
+          if (prior && reviewMatchesInput(prior.review, prior.inputHash, inputHash)) {
+            await reporter.report(prior.review, undefined, inputHash);
+            process.stderr.write(
+              "CI reviewer: unchanged review input; reused the previous result.\n",
+            );
+            return;
+          }
+        } catch (error) {
+          process.stderr.write(
+            `CI reviewer: could not read the previous review cache (continuing fresh): ${errorMessage(error)}\n`,
+          );
+        }
+      }
+    }
+
    const review = await runReview(source, {
      config,
      mode: "ci",
      agents,
      route,
      contextText,
-      stack: resolveStackWalk(config.stack, noStackAware),
-      stackConfirm: resolveStackConfirm(config.stack, noStackAware),
+      stack,
+      stackConfirm,
      runsDir: workspaceRunsDir(cwd),
      // Adjudicate mode judges the matched replies against the source before the
      // comment is rendered; annotate mode lets the reporter match them at report
      // time. Either way the feedback path is fail-open (runReview swallows its own
      // errors), so it never fails the PR's checks.
-      feedback: adjudicationSeam(config, reporter),
+      feedback,
      onProgress: (message) => process.stderr.write(`${message}\n`),
    });
-    await reporter.report(review, review.feedback);
+    await reporter.report(
+      review,
+      review.feedback,
+      inputHash && reviewCanBeReused(review) ? inputHash : undefined,
+    );
    process.stderr.write(`CI reviewer: posted review (${review.decision}).\n`);
  } catch (error) {
    // A reviewer failure must never fail the PR's checks — but it must also not be
@@ -763,13 +818,14 @@ async function runRoutedCi(
  };
  // The reviewed head OID also binds each adjudication verdict to the source it judged
  // (see mergeFeedback); unresolved leaves it unknown, so verdicts are re-judged.
+  let metadata: Awaited<ReturnType<ReviewSource["getMetadata"]>> | undefined;
  let headSha: string | undefined;
  try {
-    const { baseOid, headOid } = await source.getMetadata();
-    if (baseOid) {
-      link.baseSha = baseOid;
+    metadata = await source.getMetadata();
+    if (metadata.baseOid) {
+      link.baseSha = metadata.baseOid;
    }
-    headSha = headOid;
+    headSha = metadata.headOid;
  } catch {
    // leave baseSha unset → out-of-diff findings degrade to plain text
  }
@@ -824,11 +880,42 @@ async function runRoutedCi(
    reporterFor(scopedCommentTag(rootTag, name), true),
  );

+  const cacheAllowed =
+    !bypassTriggerGate &&
+    !stackWalk &&
+    !feedbackNeedsRunSeam(rootConfig.feedback) &&
+    metadata !== undefined;
+  let cacheReadRoot: string | undefined;
+  if (cacheAllowed) {
+    try {
+      const prepared = await source.prepareReadRootAsync?.();
+      cacheReadRoot = prepared?.dir ?? cwd;
+      await prepared?.cleanup();
+    } catch (error) {
+      // The fresh run will retry the same materialization and apply CI's ordinary
+      // fail-closed behavior. Cache setup itself never changes that outcome.
+      process.stderr.write(
+        `CI reviewer: could not prepare the review cache input (continuing fresh): ${errorMessage(error)}\n`,
+      );
+    }
+  }
+  let priorAggregateState: ReviewState | null = null;
+  if (cacheReadRoot && mode === "single") {
+    try {
+      priorAggregateState = await singleModeReporter!.readState();
+    } catch (error) {
+      process.stderr.write(
+        `CI reviewer: could not read the previous aggregate cache (continuing fresh): ${errorMessage(error)}\n`,
+      );
+    }
+  }
+
  const results: ScopeReviewResult[] = [];
  for (const scope of active) {
    const scopeDef = manifest.scopes.find((entry) => entry.name === scope.name)!;
    const isDefault = scope.configDir === ".";
    let review: CoordinatorOutput;
+    let inputHash: string | undefined;
    try {
      // A scope whose config dir doesn't exist at the TRUSTED base commit is a
      // scope this PR introduces: review it with the root config rather than
@@ -858,27 +945,66 @@ async function runRoutedCi(
              : undefined,
          )
        : undefined;
-      review = await runReview(source, {
-        config,
-        mode: "ci",
-        agents,
-        route,
-        includePaths: scope.files,
-        contextText,
-        stack: stackWalk,
-        stackConfirm,
-        passesBudgetMs: budget,
-        runsDir: workspaceRunsDir(cwd),
-        feedback: feedbackSeam,
-        onProgress: (message) => process.stderr.write(`[${scope.name}] ${message}\n`),
-      });
+      let cached: ScopeReviewResult | ReviewState | undefined;
+      if (cacheReadRoot) {
+        try {
+          const included = new Set(scope.files);
+          inputHash = await reviewInputHash({
+            files: changed.filter((file) => included.has(file.path)),
+            config,
+            metadata: metadata!,
+            readRoot: cacheReadRoot,
+            agents,
+            route,
+            contextText,
+          });
+          if (mode === "single") {
+            cached = priorAggregateState?.scopes?.find((entry) => entry.scope === scope.name);
+          } else {
+            cached = (await scopeReporter(scope.name).readState()) ?? undefined;
+          }
+        } catch (error) {
+          inputHash = undefined;
+          process.stderr.write(
+            `CI reviewer: [${scope.name}] could not use the previous cache (continuing fresh): ${errorMessage(error)}\n`,
+          );
+        }
+      }
+
+      if (cached && reviewMatchesInput(cached.review, cached.inputHash, inputHash!)) {
+        review = cached.review;
+        process.stderr.write(
+          `CI reviewer: [${scope.name}] unchanged review input; reused the previous result.\n`,
+        );
+      } else {
+        review = await runReview(source, {
+          config,
+          mode: "ci",
+          agents,
+          route,
+          includePaths: scope.files,
+          contextText,
+          stack: stackWalk,
+          stackConfirm,
+          passesBudgetMs: budget,
+          runsDir: workspaceRunsDir(cwd),
+          feedback: feedbackSeam,
+          onProgress: (message) => process.stderr.write(`[${scope.name}] ${message}\n`),
+        });
+      }
    } catch (error) {
      process.stderr.write(
        `CI reviewer: [${scope.name}] failed (non-blocking): ${errorMessage(error)}\n`,
      );
      review = failureReview(scope.name, publicFailureReason(error));
+      inputHash = undefined;
    }
-    results.push({ scope: scope.name, isDefault, review });
+    results.push({
+      scope: scope.name,
+      isDefault,
+      review,
+      ...(inputHash && reviewCanBeReused(review) ? { inputHash } : {}),
+    });
  }

  if (mode === "single") {
@@ -888,7 +1014,7 @@ async function runRoutedCi(
      // A partial run (--scopes) is authoritative ONLY for the named scopes: merge
      // the other scopes' previous results out of the existing aggregate comment's
      // state so re-running one scope doesn't silently discard the rest.
-      const prior = (await aggregate.readState())?.scopes ?? [];
+      const prior = (priorAggregateState ?? (await aggregate.readState()))?.scopes ?? [];
      finalResults = mergePartialAggregate(
        results,
        prior,
@@ -947,7 +1073,11 @@ async function runRoutedCi(
      const reporter = scopeReporter(scope.name);
      const result = results.find((entry) => entry.scope === scope.name);
      if (result) {
-        await reporter.report(result.review, (result.review as ReviewRunResult).feedback);
+        await reporter.report(
+          result.review,
+          (result.review as ReviewRunResult).feedback,
+          result.inputHash,
+        );
      } else {
        // A reconciled scope with zero matched files gets its stale comment deleted.
        await reporter.clear();
@@ -27,9 +27,10 @@ Options:
  --no-workflow   Skip writing the CI workflows (review, command, and dismiss
                  under .github/workflows/)
  --token-env <name[,name…]>
-                  Env var(s) holding the model credential (default OPENAI_API_KEY,
-                  e.g. CLAUDE_CODE_OAUTH_TOKEN). The scaffolded workflows forward
-                  the matching repo secret(s) and expect this tokenEnv
+                  Env var(s) holding the model credential (default
+                  CLAUDE_CODE_REVIEW_SHARED_API_TOKEN, e.g. OPENAI_API_KEY). The
+                  scaffolded workflows forward the matching repo secret(s) and
+                  expect this tokenEnv
  --force         Overwrite existing files
  --force-workflows
                  Overwrite only the CI workflow files, keeping your customized
@@ -38,7 +39,7 @@ Options:
  -h, --help      Show this help
 `;

-const DEFAULT_TOKEN_ENV = "OPENAI_API_KEY";
+const DEFAULT_TOKEN_ENV = "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN";

 export async function initCommand(argv: string[]): Promise<void> {
  if (argv.includes("-h") || argv.includes("--help")) {
@@ -107,7 +108,7 @@ async function scaffold(argv: string[]): Promise<void> {

  // The reverse of the guard above: --force-workflows (or --force) always rewrites
  // the review workflows from the pristine template, which forwards the default
-  // OPENAI_API_KEY unless --token-env names the credential again. An adopter who
+  // Anthropic token env unless --token-env names the credential again. An adopter who
  // scaffolded with a non-default tokenEnv and later refreshes the workflow YAML
  // without re-passing --token-env would silently lose the forwarded secret, and
  // CI would keep passing the auth lock but run with an empty credential. Refuse
@@ -121,7 +122,7 @@ async function scaffold(argv: string[]): Promise<void> {
          `${baked}, but this run has no --token-env, so rewriting them would restore the ` +
          `default ${DEFAULT_TOKEN_ENV} and CI would run with an empty credential. Re-run with ` +
          `--token-env ${baked} to keep the current credential, or --token-env ${DEFAULT_TOKEN_ENV} ` +
-          `to reset to OpenAI on purpose.`,
+          `to reset to the default on purpose.`,
      );
    }
  }
@@ -226,14 +227,15 @@ async function scaffold(argv: string[]): Promise<void> {
  const steps = [
    `Customize ${CONFIG_DIRNAME}/agents/*.md (and shared.md, coordinator.md) for this repo.`,
    // --token-env only rewires the workflows; the scaffolded config.jsonc still
-    // declares OPENAI_API_KEY, and CI's `ecr verify-config` refuses to review
-    // until the config's tokenEnv set matches the workflow's expected set.
+    // declares the default Anthropic tokenEnv, and CI's `ecr verify-config`
+    // refuses to review until the config's tokenEnv set matches the workflow's
+    // expected set.
    ...(tokenEnvs.join(",") !== DEFAULT_TOKEN_ENV
      ? [
          `Point ${CONFIG_DIRNAME}/config.jsonc at ${tokenEnvs.length > 1 ? "these credentials" : "this credential"}: set \`auth\` (and \`model\`) per the file's comments — CI's \`ecr verify-config\` refuses to review until the config names ${names}.`,
        ]
      : []),
-    "Configure a model provider in OpenCode (or set REVIEWER_MODEL).",
+    "Log in with `claude` (or run `ecr setup-auth`) so local runs have a credential.",
    "Run `ecr doctor`, then `ecr review`.",
    withWorkflow
      ? `Add the ${names} repo secret${tokenEnvs.length > 1 ? "s" : ""} referenced by the workflow, then add an \`ai-review\` label to a PR.`
@@ -639,11 +641,14 @@ export function substituteTokenEnv(raw: string, tokenEnvs: string[]): string {
    return raw;
  }
  const expectedFallback = `vars.ECR_EXPECTED_TOKEN_ENV || '${DEFAULT_TOKEN_ENV}'`;
+  // Byte-identical to the credential block in templates/workflow.yml AND
+  // templates/command.yml (both flow through this function).
  const credentialBlock = [
-    "          # OpenAI API key — the env var named by auth.tokenEnv in config.jsonc.",
-    "          # Store it as a repo secret; a project-scoped key restricted to model",
-    "          # inference (with a spend limit) is all the reviewer needs.",
-    "          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}",
+    "          # Anthropic review credential — the env var named by auth.tokenEnv in",
+    "          # config.jsonc. Store it as a repo secret: an `sk-ant-oat…` token minted",
+    "          # by `claude setup-token`, or an `sk-ant-api…` Console key (the Claude",
+    "          # Code CLI reads either).",
+    "          CLAUDE_CODE_REVIEW_SHARED_API_TOKEN: ${{ secrets.CLAUDE_CODE_REVIEW_SHARED_API_TOKEN }}",
  ].join("\n");
  if (!raw.includes(expectedFallback) || !raw.includes(credentialBlock)) {
    throw new Error("workflow template drifted: tokenEnv markers not found (report this bug)");
@@ -25,7 +25,7 @@ Exit 0 = every ref holds. Exit 1 = at least one is broken.

 Options:
  --root <dir>   Repository root to check (default: the current git repo).
-  --json         Emit {ok, problems:[{file, line, kind, problem}]} on stdout.
+  --json         Emit {ok, problems:[{file, line, kind, problem, target?}]} on stdout.
 `;

 const KIND_LABEL: Record<RefProblem["kind"], string> = {
@@ -244,6 +244,7 @@ export async function adjudicateFeedback(
            title: `adjudicate-${index}`,
            maxWaitMs: ADJUDICATE_TIMEOUT_MS,
            finalizeOnTimeout: true,
+            onActivity: (line) => debug(`  [adjudicator] #${index + 1}: ${line}`),
          },
          parseAdjudication,
        );
@@ -21,7 +21,9 @@ const PROVIDER_KEY_ENV: Record<string, string> = {
 * Provider-owned credential env vars BEYOND the x-api-key ones above: Anthropic's
 * OAuth/subscription bearer envs. CLAUDE_CODE_OAUTH_TOKEN holds the long-lived (1-year)
 * Claude Max/Team subscription token that `ecr setup-auth`/`claude setup-token` export,
- * and ANTHROPIC_AUTH_TOKEN is Anthropic's documented bearer var. They belong to
+ * ANTHROPIC_AUTH_TOKEN is Anthropic's documented bearer var, and
+ * CLAUDE_CODE_REVIEW_SHARED_API_TOKEN is the SCAFFOLDED DEFAULT tokenEnv (see
+ * templates/config.jsonc) — it always holds an Anthropic credential. They belong to
 * anthropic, so the cross-provider guard below refuses a non-anthropic entry that names
 * one — without this, `{provider:"openai", tokenEnv:"CLAUDE_CODE_OAUTH_TOKEN"}` passes
 * (neither a FORBIDDEN secret nor a PROVIDER_KEY_ENV value) and prepareAuth forwards the
@@ -31,6 +33,7 @@ const PROVIDER_KEY_ENV: Record<string, string> = {
 const ANTHROPIC_TOKEN_ENVS: Record<string, string> = {
  CLAUDE_CODE_OAUTH_TOKEN: "anthropic",
  ANTHROPIC_AUTH_TOKEN: "anthropic",
+  CLAUDE_CODE_REVIEW_SHARED_API_TOKEN: "anthropic",
 };

 /**
@@ -20,7 +20,7 @@ import { RateLimitWatch } from "./throttle.js";

 /**
 * The Claude Code CLI review engine. Runs each pass as a single `claude -p
- * --output-format json` subprocess on the user's Claude Max/Team subscription,
+ * --output-format stream-json --verbose` subprocess on the user's Claude Max/Team subscription,
 * bypassing OpenCode entirely (which cannot use Anthropic subscription OAuth).
 * The seam functions in opencode.ts dispatch here on `handle.engine`.
 *
@@ -59,6 +59,8 @@ export interface ClaudePromptArgs {
  maxWaitMs?: number;
  maxToolCalls?: number;
  finalizeOnTimeout?: boolean;
+  /** Provider-enforced output contract, generated from the local Zod parser. */
+  jsonSchema?: Record<string, unknown>;
 }

 /** Coarse per-pass wander bound; the review's own maxWaitMs is the real ceiling. */
@@ -66,9 +68,9 @@ const CLAUDE_MAX_TURNS = 60;
 /** Fallback per-pass ceiling when a caller passes no maxWaitMs. */
 const DEFAULT_MAX_WAIT_MS = 8 * 60 * 1000;
 /**
- * A stateless `claude -p` pass emits no incremental tool lines to the caller, so a
- * long pass would look hung. Emit a "still working" heartbeat this often (matching
- * opencode.ts's HEARTBEAT_MS) to keep the progress signal alive.
+ * Emit a "still working" heartbeat after this long with no structured stream
+ * activity (matching opencode.ts's HEARTBEAT_MS), so a thinking stretch still has
+ * a progress signal between tool calls.
 */
 const CLAUDE_HEARTBEAT_MS = 45_000;

@@ -289,6 +291,7 @@ export function buildClaudeArgs(opts: {
   */
  tools?: readonly string[];
  maxTurns?: number;
+  jsonSchema?: Record<string, unknown>;
 }): string[] {
  // Permission rules are gitignore-style with forward slashes; a Windows cwd
  // (`C:\Users\dev\repo`) must be normalized or every rule silently matches
@@ -305,11 +308,13 @@ export function buildClaudeArgs(opts: {
  return [
    "-p",
    "--output-format",
-    "json",
+    "stream-json",
+    "--verbose",
    "--model",
    opts.model,
    "--append-system-prompt",
    opts.system,
+    ...(opts.jsonSchema ? ["--json-schema", JSON.stringify(opts.jsonSchema)] : []),
    ...(enabled.length > 0 ? ["--allowedTools", ...enabled.map(scope)] : []),
    "--disallowedTools",
    ...deniedReadTools,
@@ -331,6 +336,184 @@ export interface ClaudeResult {
  modelOutputTokens: Record<string, number>;
  isError: boolean;
  errorText: string;
+  /** Whether the final result carried the object validated by `--json-schema`. */
+  hasStructuredOutput: boolean;
+  /** Claude Code exhausted its own in-session structured-output repair attempts. */
+  structuredOutputFailure: boolean;
+}
+
+const CLAUDE_STREAM_MISSING_RESULT = "Claude Code stream ended without a final result event";
+const CLAUDE_RESULT_MISSING_ERROR = "Claude Code returned an error without a message";
+
+type JsonRecord = Record<string, unknown>;
+
+function jsonRecord(value: unknown): JsonRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as JsonRecord)
+    : null;
+}
+
+/** The final result object from either legacy single JSON or JSONL stream output. */
+function finalClaudeResult(stdout: string): JsonRecord | null {
+  try {
+    const parsed = jsonRecord(JSON.parse(stdout));
+    return parsed?.type === "result" ? parsed : null;
+  } catch {
+    let result: JsonRecord | null = null;
+    for (const line of stdout.split(/\r?\n/)) {
+      if (!line.trim()) {
+        continue;
+      }
+      try {
+        const event = jsonRecord(JSON.parse(line));
+        if (event?.type === "result") {
+          result = event;
+        }
+      } catch {
+        // A malformed/non-JSON line cannot be the structured final result.
+      }
+    }
+    return result;
+  }
+}
+
+const MAX_ACTIVITY_DETAIL = 180;
+
+/** Collapse control/newline injection and bound provider/model-originated log text. */
+function safeActivityDetail(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const withoutControls = [...value]
+    .map((char) => {
+      const code = char.charCodeAt(0);
+      return code <= 0x1f || (code >= 0x7f && code <= 0x9f) ? " " : char;
+    })
+    .join("");
+  const clean = withoutControls.replace(/\s+/g, " ").trim();
+  if (!clean) {
+    return undefined;
+  }
+  return clean.length > MAX_ACTIVITY_DETAIL ? `${clean.slice(0, MAX_ACTIVITY_DETAIL - 1)}…` : clean;
+}
+
+/** Render an in-tree tool target without exposing attempted host paths. */
+function activityPath(value: unknown, cwd: string): string | undefined {
+  const candidate = safeActivityDetail(value);
+  if (!candidate) {
+    return undefined;
+  }
+  const root = path.resolve(cwd);
+  const absolute = path.resolve(root, candidate);
+  if (absolute !== root && !pathInside(absolute, root)) {
+    return undefined;
+  }
+  const relative = path.relative(root, absolute).replace(/\\/g, "/");
+  return relative || ".";
+}
+
+interface ClaudeActivity {
+  /** Stable tool-use id; repeated assistant events with the same id log once. */
+  key?: string;
+  line: string;
+}
+
+/**
+ * Convert one Claude stream event into safe progress metadata. Raw assistant text,
+ * tool results, and grep patterns are deliberately never logged: PR/model content is
+ * untrusted and may contain secrets or terminal-control/log-injection payloads.
+ */
+// @ref LLP 0003#claude-code-cli-containment [implements] — stream only bounded lifecycle/tool metadata; raw model text and tool results never become progress logs
+export function claudeActivities(eventValue: unknown, cwd: string): ClaudeActivity[] {
+  const event = jsonRecord(eventValue);
+  if (!event) {
+    return [];
+  }
+  if (event.type === "system" && event.subtype === "init") {
+    const model = safeActivityDetail(event.model);
+    return [{ line: model ? `started ${model}` : "started" }];
+  }
+  if (event.type === "result") {
+    if (event.is_error === true) {
+      return [];
+    }
+    const duration =
+      typeof event.duration_ms === "number"
+        ? `${Math.max(0, Math.round(event.duration_ms / 1000))}s`
+        : null;
+    const turns = typeof event.num_turns === "number" ? `${event.num_turns} turn(s)` : null;
+    const detail = [duration, turns].filter(Boolean).join(", ");
+    return [{ line: detail ? `completed (${detail})` : "completed" }];
+  }
+  if (event.type !== "assistant") {
+    return [];
+  }
+  const message = jsonRecord(event.message);
+  const content = Array.isArray(message?.content) ? message.content : [];
+  const activities: ClaudeActivity[] = [];
+  for (const value of content) {
+    const block = jsonRecord(value);
+    if (block?.type !== "tool_use" || typeof block.name !== "string") {
+      continue;
+    }
+    const input = jsonRecord(block.input) ?? {};
+    const key = typeof block.id === "string" ? block.id : undefined;
+    if (block.name === "Read") {
+      const target = activityPath(input.file_path, cwd);
+      activities.push({ key, line: target ? `Read ${target}` : "Read" });
+    } else if (block.name === "Grep") {
+      const target = activityPath(input.path, cwd);
+      activities.push({ key, line: target ? `Grep ${target}` : "Grep" });
+    } else if (block.name === "Glob") {
+      const target = activityPath(input.path, cwd);
+      activities.push({ key, line: target && target !== "." ? `Glob ${target}` : "Glob" });
+    }
+  }
+  return activities;
+}
+
+/** Incremental JSONL decoder for Claude's stream-json stdout. */
+export function createClaudeActivityStream(
+  cwd: string,
+  onActivity: (line: string) => void,
+): { push: (chunk: string) => void; finish: () => void } {
+  let buffered = "";
+  const reported = new Set<string>();
+  const consume = (line: string): void => {
+    if (!line.trim()) {
+      return;
+    }
+    try {
+      for (const activity of claudeActivities(JSON.parse(line), cwd)) {
+        if (activity.key && reported.has(activity.key)) {
+          continue;
+        }
+        if (activity.key) {
+          reported.add(activity.key);
+        }
+        onActivity(activity.line);
+      }
+    } catch {
+      // Ignore malformed progress events; final result parsing still reports errors.
+    }
+  };
+  return {
+    push(chunk: string): void {
+      buffered += chunk;
+      for (;;) {
+        const newline = buffered.indexOf("\n");
+        if (newline < 0) {
+          break;
+        }
+        consume(buffered.slice(0, newline).replace(/\r$/, ""));
+        buffered = buffered.slice(newline + 1);
+      }
+    },
+    finish(): void {
+      consume(buffered);
+      buffered = "";
+    },
+  };
 }

 /**
@@ -353,21 +536,26 @@ export function pickAnsweringModel(
 }

 /**
- * Parse the `--output-format json` result object. Keys off `is_error` / a parse
+ * Parse the final result from `--output-format stream-json` JSONL (also accepts the
+ * former single JSON object for compatibility/tests). Keys off `is_error` / a parse
 * failure, NOT `subtype` — `subtype` stays `"success"` on some API errors.
 */
 export function parseClaudeResult(stdout: string): ClaudeResult {
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(stdout) as Record<string, unknown>;
-  } catch {
+  const parsed = finalClaudeResult(stdout);
+  if (!parsed) {
+    // The stream may contain assistant text and tool results sourced from the
+    // untrusted review tree. Never turn that transcript into an error message or
+    // feed it to provider-error classification.
+    // @ref LLP 0003#claude-code-cli-containment [constrained-by] — raw JSONL transcript content must never reach logs or error classifiers
    return {
      text: "",
      cost: 0,
      tokens: {},
      modelOutputTokens: {},
      isError: true,
-      errorText: stdout.trim(),
+      errorText: CLAUDE_STREAM_MISSING_RESULT,
+      hasStructuredOutput: false,
+      structuredOutputFailure: false,
    };
  }
  const usage = (parsed.usage ?? {}) as Record<string, unknown>;
@@ -386,18 +574,42 @@ export function parseClaudeResult(stdout: string): ClaudeResult {
  for (const [key, value] of Object.entries(modelUsage)) {
    modelOutputTokens[key] = num((value as Record<string, unknown> | null)?.outputTokens) ?? 0;
  }
-  const result = typeof parsed.result === "string" ? parsed.result : "";
  const isError = parsed.is_error === true;
+  const hasStructuredOutput = parsed.structured_output !== undefined;
+  // `--json-schema` returns a provider-validated object in `structured_output`.
+  // Serialize it back through the existing local parser so Zod remains the final
+  // trust boundary. Ignore any stale/retracted structured value on an error result;
+  // error classification must use only the CLI's explicit final error message.
+  const structured =
+    isError || parsed.structured_output === undefined
+      ? undefined
+      : JSON.stringify(parsed.structured_output);
+  const result = structured ?? (typeof parsed.result === "string" ? parsed.result : "");
  return {
    text: result,
    cost: num(parsed.total_cost_usd) ?? 0,
    tokens,
    modelOutputTokens,
    isError,
-    errorText: isError ? result || stdout.trim() : "",
+    // Only the final result event's explicit error text is safe to classify and
+    // surface. Falling back to stdout would expose the full JSONL transcript.
+    errorText: isError ? result || CLAUDE_RESULT_MISSING_ERROR : "",
+    hasStructuredOutput,
+    structuredOutputFailure: parsed.subtype === "error_max_structured_output_retries",
  };
 }

+/**
+ * A provider-side schema failure that spent tokens and may be retried once from a
+ * clean process. Carrying the attempt lets the caller retain honest run metrics.
+ */
+class ClaudeStructuredOutputError extends Error {
+  constructor(readonly result: PromptResult) {
+    super("Claude Code could not produce output matching the required JSON Schema");
+    this.name = "ClaudeStructuredOutputError";
+  }
+}
+
 /** Classify a Claude Code failure so the caller can pick backoff vs. hard fail. */
 export function classifyClaudeError(
  errorText: string,
@@ -488,6 +700,40 @@ export function claudeTemperatureNote(
    : null;
 }

+/**
+ * Preserve actionable process diagnostics without copying arbitrary stderr into a
+ * public Actions log. A non-empty stream may already contain model/tool content, so
+ * stderr is not even classified in that case. With no stream, recognize only fixed
+ * CLI/setup categories and never interpolate the matched text.
+ */
+// @ref LLP 0003#claude-code-cli-containment [constrained-by] — stderr may reflect untrusted tree content; expose only exit metadata and fixed allowlisted categories
+function claudeExitDiagnostic(result: { stdout: string; stderr: string; code: number }): string {
+  const exit = `Claude Code exited with code ${result.code}`;
+  if (result.stdout.trim() !== "") {
+    return exit;
+  }
+
+  if (/unknown (?:option|argument)|unrecognized option|unexpected argument/i.test(result.stderr)) {
+    return (
+      `${exit}; the CLI rejected its arguments — verify the pinned ` +
+      "@anthropic-ai/claude-code version supports the configured flags"
+    );
+  }
+  if (/authentication|oauth|api.?key|unauthorized|\b401\b|\b403\b/i.test(result.stderr)) {
+    return (
+      `${exit}; authentication failed before a result was emitted — check ` +
+      "`claude auth status` and `ecr doctor`"
+    );
+  }
+  if (/\bENOENT\b|command not found|no such file or directory/i.test(result.stderr)) {
+    return `${exit}; the Claude Code executable or one of its required files was not found`;
+  }
+  if (/\bEACCES\b/i.test(result.stderr)) {
+    return `${exit}; the Claude Code executable could not be launched due to permissions`;
+  }
+  return exit;
+}
+
 /**
 * One prompt → text/cost/tokens/model, as a single `claude -p` subprocess (the
 * Claude analogue of OpenCode's promptAgent; no sessions/polling).
@@ -507,14 +753,25 @@ export async function runClaudePrompt(
  // stateless analogue of OpenCode's mid-run tool-call cap).
  const maxTurns =
    args.maxToolCalls != null && args.maxToolCalls > 0 ? args.maxToolCalls : undefined;
-  // A stateless `claude -p` pass streams nothing back, so emit a heartbeat while it
-  // runs or a long pass looks hung (cleared in finally, whatever the outcome).
+  // Stream safe structured activity. The heartbeat fires only after a quiet window,
+  // rather than on a fixed cadence that can land immediately after a tool line.
  const heartbeatStart = Date.now();
+  let lastStreamActivityAt = heartbeatStart;
+  const emitActivity = (line: string): void => {
+    lastStreamActivityAt = Date.now();
+    args.onActivity?.(line);
+  };
+  const activityStream = args.onActivity
+    ? createClaudeActivityStream(process.cwd(), emitActivity)
+    : undefined;
  const heartbeat = args.onActivity
    ? setInterval(() => {
-        args.onActivity?.(
-          `still working… ${Math.round((Date.now() - heartbeatStart) / 1000)}s elapsed`,
-        );
+        if (Date.now() - lastStreamActivityAt >= CLAUDE_HEARTBEAT_MS) {
+          args.onActivity?.(
+            `still working… ${Math.round((Date.now() - heartbeatStart) / 1000)}s elapsed ` +
+              `(no new activity for ${Math.round((Date.now() - lastStreamActivityAt) / 1000)}s)`,
+          );
+        }
      }, CLAUDE_HEARTBEAT_MS)
    : undefined;
  heartbeat?.unref?.();
@@ -528,6 +785,7 @@ export async function runClaudePrompt(
        cwd: process.cwd(),
        tools,
        maxTurns,
+        jsonSchema: args.jsonSchema,
      }),
      {
        input: args.text,
@@ -535,9 +793,11 @@ export async function runClaudePrompt(
        cwd: process.cwd(),
        timeout: maxWaitMs,
        check: false,
+        onStdout: activityStream?.push,
      },
    );
  } finally {
+    activityStream?.finish();
    if (heartbeat) {
      clearInterval(heartbeat);
    }
@@ -551,9 +811,7 @@ export async function runClaudePrompt(
  // A non-timeout signal is a crash (SIGSEGV, OOM SIGKILL, external kill), not a
  // timeout — surface it as a hard error rather than the subdivide/retry path.
  if (result.signal) {
-    throw new Error(
-      `Claude Code was killed by signal ${result.signal}: ${result.stderr.trim() || "(no output)"}`,
-    );
+    throw new Error(`Claude Code was killed by signal ${result.signal}`);
  }
  // Truncated output can't be parsed as JSON; report the cause plainly instead of
  // letting it fall through as a generic parse failure.
@@ -562,6 +820,31 @@ export async function runClaudePrompt(
  }

  const parsed = parseClaudeResult(result.stdout);
+  const answered = pickAnsweringModel(configuredModel, parsed.modelOutputTokens);
+  const model = answered
+    ? claudeModelMatches(configuredModel, answered)
+      ? configuredModel
+      : `anthropic/${answered}`
+    : configuredModel;
+  const promptResult: PromptResult = {
+    text: parsed.text,
+    cost: parsed.cost,
+    sessionID: "",
+    tokens: parsed.tokens,
+    model,
+  };
+
+  // A schema-requesting caller must receive the provider-validated object, never a
+  // parseable-looking fallback from `result`. Claude repairs schema mismatches in
+  // session first; its documented exhaustion result gets one clean-process retry in
+  // claudeCodePromptAndParse. A success that omits structured_output is treated the
+  // same way because it did not honor the requested provider contract.
+  if (
+    args.jsonSchema &&
+    (parsed.structuredOutputFailure || (!parsed.isError && !parsed.hasStructuredOutput))
+  ) {
+    throw new ClaudeStructuredOutputError(promptResult);
+  }
  if (parsed.isError) {
    const kind = classifyClaudeError(parsed.errorText);
    if (kind === "rate-limit" || kind === "usage-limit") {
@@ -581,37 +864,33 @@ export async function runClaudePrompt(
          "`ecr doctor`.",
      );
    }
+    const needsProcessDiagnostic =
+      parsed.errorText === CLAUDE_STREAM_MISSING_RESULT ||
+      parsed.errorText === CLAUDE_RESULT_MISSING_ERROR;
    throw new Error(
-      parsed.errorText ||
-        `claude exited with code ${result.code}: ${
-          result.stderr.trim() || result.stdout.trim() || "(no output)"
-        }`,
+      needsProcessDiagnostic
+        ? `${parsed.errorText} (${claudeExitDiagnostic(result)})`
+        : parsed.errorText,
    );
  }

-  const answered = pickAnsweringModel(configuredModel, parsed.modelOutputTokens);
-  const model = answered
-    ? claudeModelMatches(configuredModel, answered)
-      ? configuredModel
-      : `anthropic/${answered}`
-    : configuredModel;
-  return { text: parsed.text, cost: parsed.cost, sessionID: "", tokens: parsed.tokens, model };
+  return promptResult;
 }

 /**
- * The claude analogue of opencode.ts's CORRECTIVE. NOT shared: that one says
- * "your previous reply could not be parsed", which is true in OpenCode's
- * same-session follow-up but false here — each `claude -p` invocation is a fresh
- * stateless process with no previous reply to reference.
+ * Last-resort correction for a no-schema caller or disagreement between the
+ * provider's JSON Schema validator and our local parser. Production parsers pass
+ * `--json-schema`, so Claude Code already performs validation-aware repair inside
+ * the original session before this fresh-process fallback is needed.
 */
 const CLAUDE_CORRECTIVE =
  "\n\nIMPORTANT: reply with ONLY the single JSON object described above — no prose, " +
  "no code fences, no partial output.";

 /**
- * Prompt via the Claude Code CLI and parse the reply, mirroring OpenCode's
- * promptAndParse: transient retry on the first call, then one corrective re-run
- * (a fresh process — the diff is inlined, so re-read is a cache hit).
+ * Prompt via the Claude Code CLI and parse the provider-validated structured
+ * result locally. Transient failures retry first; a remaining local parse failure
+ * gets one fresh-process corrective as defense in depth.
 */
 export async function claudeCodePromptAndParse<T>(
  handle: ClaudeCodeHandle,
@@ -627,24 +906,47 @@ export async function claudeCodePromptAndParse<T>(
    model = result.model ?? model;
  };

-  const first = await withTransientRetry(`Agent "${args.agent}"`, args.onActivity, () =>
-    runClaudePrompt(handle, args),
-  );
-  record(first);
+  let first: PromptResult | undefined;
  try {
-    return { value: parse(first.text), cost, truncated: false, tokens, model };
-  } catch {
-    const retry = await runClaudePrompt(handle, { ...args, text: args.text + CLAUDE_CORRECTIVE });
-    record(retry);
+    first = await withTransientRetry(`Agent "${args.agent}"`, args.onActivity, () =>
+      runClaudePrompt(handle, args),
+    );
+    record(first);
    try {
-      return { value: parse(retry.text), cost, truncated: false, tokens, model };
-    } catch (finalError) {
-      throw new Error(
-        `Agent "${args.agent}" did not return parseable JSON after retries: ${
-          finalError instanceof Error ? finalError.message : String(finalError)
-        }`,
-      );
+      return { value: parse(first.text), cost, truncated: false, tokens, model };
+    } catch {
+      // Provider validation and local Zod validation disagreed. Retry once from a
+      // clean process rather than accepting an object the trust boundary rejected.
    }
+  } catch (error) {
+    if (!(error instanceof ClaudeStructuredOutputError)) {
+      throw error;
+    }
+    record(error.result);
+    args.onActivity?.("structured output validation failed — retrying once");
+  }
+
+  let retry: PromptResult;
+  try {
+    retry = await runClaudePrompt(handle, { ...args, text: args.text + CLAUDE_CORRECTIVE });
+  } catch (error) {
+    if (!(error instanceof ClaudeStructuredOutputError)) {
+      throw error;
+    }
+    record(error.result);
+    throw new Error(
+      `Agent "${args.agent}" could not satisfy its required JSON Schema after retries`,
+    );
+  }
+  record(retry);
+  try {
+    return { value: parse(retry.text), cost, truncated: false, tokens, model };
+  } catch (finalError) {
+    throw new Error(
+      `Agent "${args.agent}" did not return parseable JSON after retries: ${
+        finalError instanceof Error ? finalError.message : String(finalError)
+      }`,
+    );
  }
 }

@@ -8,6 +8,7 @@ import { CONFIG_DIRNAME, stripJsonComments, stripTrailingCommas } from "../confi
 import { ROUTING_FILENAME } from "../config/routing.js";
 import { git, pathInside } from "./exec.js";
 import { matchesIgnore } from "./noise.js";
+import { isAmbientRuntimeConfig } from "./scrub.js";

 /**
 * Built by concatenation so this module's own regexes and doc comments are not
@@ -46,6 +47,7 @@ const CITATION_EXTENSIONS = new Set([
  ".css",
  ".go",
  ".graphql",
+  ".hcl",
  ".h",
  ".hpp",
  ".html",
@@ -69,6 +71,8 @@ const CITATION_EXTENSIONS = new Set([
  ".sh",
  ".sql",
  ".swift",
+  ".tf",
+  ".tfvars",
  ".toml",
  ".ts",
  ".tsx",
@@ -95,6 +99,8 @@ export interface RefProblem {
  kind: RefProblemKind;
  /** One sentence, imperative where a fix is obvious. */
  problem: string;
+  /** The ref target (or prose token) at fault. Absent for structural problems. */
+  target?: string;
 }

 export interface ParsedRef {
@@ -693,10 +699,11 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
  // Does an extensionless token name something real? Cached: prompts repeat the same
  // paths, and each miss would otherwise cost a stat per occurrence.
  const resolvable = new Map<string, string | null>();
-  /** The root-relative path an extensionless token names, or null if it names nothing. */
+  /** The root-relative path a token names, or null. Scope first: a scoped prompt
+   * citing `alerts/` means its own tree even when the root has one too. */
  const namedPath = async (token: string, scopeRoot: string): Promise<string | null> => {
    for (const candidate of pathishCandidates(token)) {
-      for (const base of [root, scopeRoot]) {
+      for (const base of [scopeRoot, root]) {
        const absolute = path.resolve(base, candidate);
        let resolved = resolvable.get(absolute);
        if (resolved === undefined) {
@@ -716,6 +723,19 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
    return null;
  };

+  /** The glob a wildcard token names, rebased onto the scope when that is what
+   * matches, so the suggested `glob:` ref actually resolves. */
+  const namedGlob = (token: string, scopeRoot: string): string | null => {
+    const scopeRel = path.relative(root, scopeRoot).split(path.sep).join("/");
+    const candidates = [...(scopeRel && scopeRel !== "." ? [`${scopeRel}/${token}`] : []), token];
+    for (const candidate of candidates) {
+      if (index.files.some((file) => matchesIgnore(file, candidate))) {
+        return candidate;
+      }
+    }
+    return null;
+  };
+
  for (const dir of dirs) {
    const scopeRoot = path.dirname(dir);
    for (const file of await setupFiles(dir)) {
@@ -745,6 +765,7 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
            line: ref.line,
            kind: problem.startsWith("cites a line number") ? "line-number-ref" : "broken-ref",
            problem,
+            target: ref.target,
          });
          continue;
        }
@@ -762,18 +783,15 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
      }

      for (const { line, token } of findProseCitations(text)) {
-        // Extension or wildcard tail ⇒ a citation on shape alone. Otherwise it only
-        // counts if it names something real: `eas-build-worker/terraform` and
-        // `general-central/{module,production}` are paths, `anthropic/claude-opus-5`
-        // is shaped identically and is not.
-        const named = isCodeCitation(token) ? null : await namedPath(token, scopeRoot);
+        const isWild = token.includes("*");
+        const named = isWild ? namedGlob(token, scopeRoot) : await namedPath(token, scopeRoot);
+        // Shape alone makes a citation; otherwise it must name something real, or
+        // `anthropic/claude-opus-5` would read as a path.
        if (!isCodeCitation(token) && !named) {
          continue;
        }
-        // Coverage must accept the path the token RESOLVED to, not just the token as
-        // written: a prompt says `cert-manager` and the ref that pins it is
-        // `infrastructure/cert-manager/`. Without this, the fix the message suggests
-        // does not silence the citation it was suggested for.
+        // Coverage accepts the resolved path too, else the only ref that silences a
+        // scope-relative citation is an over-broad `glob:**/<basename>`.
        const forms = [...citationForms(token), ...(named ? coveringForms(named) : [])];
        if (
          ignored.has(token) ||
@@ -785,9 +803,12 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
          continue;
        }
        const lineCitation = LINE_CITATION_RE.exec(token);
-        // For an extensionless token the suggestion is the path that actually resolved,
-        // which is also how a scope-relative citation learns its root-relative form.
-        const suggestion = named ?? suggestedRef(token);
+        // A wildcard token means the family; anything else gets the precise resolved path.
+        const suggestion = isWild
+          ? named
+            ? `${GLOB_PREFIX}${named}`
+            : suggestedRef(token)
+          : (named ?? suggestedRef(token));
        problems.push({
          file: relative,
          line,
@@ -795,6 +816,7 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
          problem: lineCitation
            ? `\`${token}\` pins a line number; cite the file or a \`#symbol\` instead, as \`${REF_MARK} ${suggestedRef(lineCitation[1]!)}\``
            : `\`${token}\` cites code without a ref; add \`${REF_MARK} ${suggestion} — why it matters\` (or \`${IGNORE_MARK} ${token}\` if it is not a path)`,
+          target: token,
        });
      }
    }
@@ -821,6 +843,13 @@ export async function checkConfigRefs(options: CheckConfigRefsOptions): Promise<
  };
 }

+/** The file a target names, with any `glob:` prefix, `#anchor` or `:line` stripped. */
+function citedBasename(target: string): string {
+  const withoutPrefix = target.startsWith(GLOB_PREFIX) ? target.slice(GLOB_PREFIX.length) : target;
+  const withoutLine = LINE_CITATION_RE.exec(withoutPrefix)?.[1] ?? withoutPrefix;
+  return path.basename(splitAnchor(withoutLine)[0]);
+}
+
 /** How many examples a review-side note names before saying "and N more". */
 const NOTE_EXAMPLES = 5;

@@ -848,7 +877,14 @@ export async function reviewSetupRefNotes(options: {
    return []; // a check that cannot run must never degrade the review
  }
  const notes: string[] = [];
-  const broken = report.problems.filter((problem) => problem.kind !== "unannotated-citation");
+  // The read root is scrubbed of ambient runtime config (AGENTS.md, CLAUDE.md, .env…),
+  // so a ref to one is missing by design here, not stale. The template itself cites
+  // AGENTS.md, which would make this note cry wolf on every PR.
+  const broken = report.problems.filter(
+    (problem) =>
+      problem.kind !== "unannotated-citation" &&
+      !(problem.target && isAmbientRuntimeConfig(citedBasename(problem.target))),
+  );
  if (broken.length > 0) {
    notes.push(
      `The reviewer setup cites code that no longer resolves (${broken.length} ref(s)): ` +
@@ -35,6 +35,7 @@ export async function coordinate(
  agentFindings: Record<string, Finding[]>,
  coverageNotes: string[] = [],
  stackManifest?: StackManifest | null,
+  onActivity?: (line: string) => void,
 ): Promise<CoordinationResult> {
  const system = buildCoordinatorSystem(config);
  const text = buildCoordinatorTask(metadata, agentFindings, coverageNotes, stackManifest);
@@ -47,6 +48,7 @@ export async function coordinate(
      title: "review-coordinator",
      maxWaitMs: COORDINATOR_TIMEOUT_MS,
      finalizeOnTimeout: true,
+      onActivity,
    },
    parseCoordinatorOutput,
  );
@@ -31,6 +31,12 @@ export interface RunOptions {
  killSignal?: NodeJS.Signals;
  /** When set, write this to the child's stdin (routes through spawn, not execFile). */
  input?: string;
+  /**
+   * Best-effort observer for captured stdout chunks on the spawn/input path. Only
+   * bytes admitted by maxBuffer are observed; callback failures never affect the
+   * child process. Intended for structured incremental output, not raw log piping.
+   */
+  onStdout?: (chunk: string) => void;
 }

 /**
@@ -205,7 +211,16 @@ function runWithInput(
    child.stdout.setEncoding("utf8");
    child.stderr.setEncoding("utf8");
    child.stdout.on("data", (chunk: string) => {
+      const before = stdout.length;
      stdout = cap(stdout, chunk);
+      const admitted = stdout.length - before;
+      if (admitted > 0 && options.onStdout) {
+        try {
+          options.onStdout(chunk.slice(0, admitted));
+        } catch {
+          // Observability must never break the command whose output it observes.
+        }
+      }
    });
    child.stderr.on("data", (chunk: string) => {
      stderr = cap(stderr, chunk);
@@ -1010,14 +1010,13 @@ export async function withTransientRetry<T>(
 }

 /**
- * Prompt an agent and parse its reply. On a JSON-parse failure, first retry in
- * the SAME session: the model still holds all the file context it read, so the
- * corrective is a cache read and a cheap re-emit — and better for recall than
- * re-investigating from scratch (the usual failure is a truncated/malformed reply
- * after a sound investigation). Only if that also fails do we fall back to a fresh
- * session as a clean-slate last resort. A timeout is NOT a parse failure:
- * promptAgent throws AgentTimeoutError, which propagates so the caller abandons
- * the task instead of retrying a non-convergent run.
+ * Prompt an agent and parse its reply. Claude-routed production parsers hand their
+ * JSON Schema to the CLI, which repairs validation failures in-session before
+ * returning. OpenCode retries a JSON-parse failure in the SAME session: the model
+ * still holds all the file context it read, so the corrective is a cheap cache-read
+ * re-emit with better recall than re-investigating. Only if that also fails does it
+ * use a fresh session. A timeout is NOT a parse failure: AgentTimeoutError propagates
+ * so the caller abandons the non-convergent task.
 */
 export async function promptAndParse<T>(
  handle: OpencodeHandle,
@@ -1031,12 +1030,16 @@ export async function promptAndParse<T>(
    maxToolCalls?: number;
    finalizeOnTimeout?: boolean;
  },
-  parse: (text: string) => T,
+  parse: ((text: string) => T) & { jsonSchema?: Record<string, unknown> },
 ): Promise<{ value: T; cost: number; truncated: boolean; tokens: TokenUsage; model?: string }> {
  const dispatch = resolveEngineDispatch(handle, args.agent);
  if (dispatch.engine === CLAUDE_CODE_ENGINE) {
    const { claudeCodePromptAndParse } = await import("./claude-code.js");
-    return claudeCodePromptAndParse(dispatch.claudeHandle, args, parse);
+    return claudeCodePromptAndParse(
+      dispatch.claudeHandle,
+      { ...args, jsonSchema: parse.jsonSchema },
+      parse,
+    );
  }
  let cost = 0;
  let truncated = false;
@@ -206,6 +206,7 @@ export function renderMarkdown(
  link?: LinkContext,
  feedback: FeedbackRecord[] = [],
  pins: FeedbackPin[] = [],
+  inputHash?: string,
 ): string {
  const dismissedByFp = new Map(dismissed.map((record) => [record.fp, record]));
  const withFp = review.findings.map((finding) => ({ finding, fp: fingerprintFinding(finding) }));
@@ -283,7 +284,9 @@ export function renderMarkdown(
  const fingerprints = review.findings.map(fingerprintFinding);
  lines.push("", `<!-- ${tag}:fingerprints=${JSON.stringify(fingerprints)} -->`);
  lines.push(
-    `<!-- ${tag}:state=${encodeState(reviewState({ review, dismissed }, feedbackByFp, pins))} -->`,
+    `<!-- ${tag}:state=${encodeState(
+      reviewState({ review, dismissed, ...(inputHash ? { inputHash } : {}) }, feedbackByFp, pins),
+    )} -->`,
  );
  return lines.join("\n");
 }
@@ -490,6 +493,8 @@ export interface ScopeReviewResult {
  /** config '.' → un-namespaced fingerprints (dismissal carry-over). */
  isDefault: boolean;
  review: CoordinatorOutput;
+  /** Hash of the complete input that produced `review`; absent means do not reuse. */
+  inputHash?: string;
 }

 /** The machine-readable state embedded in the reviewer's comment. */
@@ -497,6 +502,8 @@ export interface ReviewState {
  /** v1 field, kept: the aggregate stores the MERGED output here. */
  review: CoordinatorOutput;
  dismissed: DismissalRecord[];
+  /** v5: legacy/single-scope review-result cache key. */
+  inputHash?: string;
  /** v2: present only on aggregate comments (routing, comment:'single'). */
  scopes?: ScopeReviewResult[];
  /** v3: author replies matched to the findings shown in this comment. */
@@ -730,7 +737,7 @@ export function renderAggregateMarkdown(
    // across re-renders. The per-scope data (`scopes`) plus a merged v1 `review`
    // keep both v2 and v1 consumers working.
    const stateScopes: ScopeReviewResult[] = rendered.map(
-      ({ result, shown, requalified, dropped }) => {
+      ({ result, shown, hidden, requalified, requalifiedHidden, dropped }) => {
        // @ref LLP 0011#suppression-is-never-silent — strip any per-scope `feedback`
        // a freshly-reviewed scope's ReviewRunResult carries: the top-level feedback
        // array (reviewState below) is the single source of truth. A stale per-scope
@@ -742,6 +749,13 @@ export function renderAggregateMarkdown(
        return {
          scope: result.scope,
          isDefault: result.isDefault,
+          // A truncated state is not the full result and therefore cannot be a cache
+          // source. Omit its hash so the next run retries instead of reusing a subset.
+          ...(hidden === 0 && requalifiedHidden === 0
+            ? result.inputHash
+              ? { inputHash: result.inputHash }
+              : {}
+            : {}),
          // Requalified findings ride the embedded state (like dismissed ones) so a
          // re-render (/dismiss) round-trips them and the addressed section persists.
          // Under truncation they are trimmed exactly like `shown` — state bytes count
@@ -0,0 +1,142 @@
+// @ref LLP 0005#review-result-cache [implements] — automated CI reuses only a complete result whose full review input hashes identically
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readlink } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import type { LoadedConfig } from "../config/schema.js";
+import { pathInside } from "./exec.js";
+import type { CoordinatorOutput, DiffEntry, ReviewMetadata } from "./schema.js";
+
+const packageVersion = (createRequire(import.meta.url)("../../package.json") as { version: string })
+  .version;
+
+/**
+ * Version the cache-key contract independently of the embedded comment-state shape.
+ * Bump this whenever review inputs gain a new source that is not represented below.
+ */
+const REVIEW_INPUT_HASH_VERSION = 1;
+
+export interface ReviewInputHashOptions {
+  files: DiffEntry[];
+  config: LoadedConfig;
+  metadata: Pick<ReviewMetadata, "title" | "body">;
+  /** PR-head tree. Changed-file contents are hashed from here, never the base checkout. */
+  readRoot: string;
+  agents?: string[];
+  route?: boolean;
+  contextText?: string;
+}
+
+/** Canonical JSON: object-key order never turns the same input into a cache miss. */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  return `{${Object.keys(record)
+    .filter((key) => record[key] !== undefined)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+    .join(",")}}`;
+}
+
+/**
+ * Hash every input that can change the code-review result while deliberately
+ * excluding checkout-local paths and commit OIDs. A restack changes OIDs; when the
+ * scoped changed-file contents, normalized patch, prompts/config and PR prose are
+ * byte-identical, that is the cache hit this key is meant to recognize.
+ */
+function normalizedPatch(patch: string, binary: boolean): string {
+  return (
+    patch
+      .split("\n")
+      // Blob ids are volatile across a restack. A binary patch has no textual content
+      // to hash, so retain its index line as the only content identity available.
+      .filter((line) => binary || !line.startsWith("index "))
+      // Unrelated lines landing earlier in the file move hunk coordinates without
+      // changing the code under review. Preserve any trailing function heading.
+      .map((line) => line.replace(/^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@(.*)$/, "@@ @@$1"))
+      .join("\n")
+  );
+}
+
+async function fileContentIdentity(
+  root: string,
+  file: DiffEntry,
+): Promise<{ kind: string; digest?: string; mode?: number; target?: string }> {
+  const abs = path.resolve(root, file.path);
+  if (!pathInside(abs, root)) {
+    throw new Error(`review cache path escapes the PR tree: ${file.path}`);
+  }
+  let stat;
+  try {
+    stat = await lstat(abs);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { kind: "missing" };
+    }
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    // Never follow a PR-controlled symlink out of the materialized tree.
+    return { kind: "symlink", target: await readlink(abs), mode: stat.mode & 0o777 };
+  }
+  if (!stat.isFile()) {
+    return { kind: "other", mode: stat.mode & 0o777 };
+  }
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(abs)) {
+    hash.update(chunk as Buffer);
+  }
+  return { kind: "file", digest: hash.digest("hex"), mode: stat.mode & 0o777 };
+}
+
+export async function reviewInputHash(options: ReviewInputHashOptions): Promise<string> {
+  const { configDir: _configDir, ...portableConfig } = options.config;
+  const sortedFiles = [...options.files].sort(
+    (a, b) => a.path.localeCompare(b.path) || (a.status ?? "").localeCompare(b.status ?? ""),
+  );
+  const files = [];
+  // Sequential reads avoid opening one descriptor per changed file on a very wide PR.
+  for (const file of sortedFiles) {
+    files.push({
+      path: file.path,
+      patch: normalizedPatch(file.patch, file.binary === true),
+      status: file.status ?? "",
+      binary: file.binary === true,
+      content: await fileContentIdentity(options.readRoot, file),
+    });
+  }
+  const input = {
+    version: REVIEW_INPUT_HASH_VERSION,
+    engineVersion: packageVersion,
+    files,
+    config: portableConfig,
+    metadata: options.metadata,
+    agents: options.agents ? [...options.agents].sort() : null,
+    route: options.route === true,
+    contextText: options.contextText ?? null,
+  };
+  return createHash("sha256").update(canonicalJson(input)).digest("hex");
+}
+
+/** Partial/failed reviews must be retried, never made durable by a cache hit. */
+export function reviewCanBeReused(review: CoordinatorOutput): boolean {
+  return review.couldNotComplete !== true && review.incomplete.length === 0;
+}
+
+/** Exact hash match plus the completeness guard used by every CI comment shape. */
+export function reviewMatchesInput(
+  review: CoordinatorOutput,
+  storedHash: string | undefined,
+  currentHash: string,
+): boolean {
+  return (
+    storedHash === currentHash && /^[a-f0-9]{64}$/.test(storedHash) && reviewCanBeReused(review)
+  );
+}
@@ -181,6 +181,14 @@ export function effectiveConcurrency(
  return 6;
 }

+/** Prefix live model activity with its stable agent bucket and optional pass label. */
+export function formatAgentActivity(agent: string, label: string, line: string): string {
+  const pass =
+    label === agent ? "" : label.startsWith(`${agent} `) ? label.slice(agent.length).trim() : label;
+  const activity = line.replace(/[\r\n]+/g, " ").trim();
+  return `  [${agent}] ${pass ? `${pass}: ` : ""}${activity}`;
+}
+
 export async function runReview(
  source: ReviewSource,
  options: ReviewRunOptions,
@@ -463,7 +471,9 @@ export async function runReview(
    let selectedAgents = explicitAgents ?? config.agents;
    if (!explicitAgents && options.route) {
      progress("Routing: selecting relevant agents…");
-      const routed = await routeAgents(handle, config, workspace.files);
+      const routed = await routeAgents(handle, config, workspace.files, (line) =>
+        progress(formatAgentActivity("router", "router", line)),
+      );
      selectedAgents = routed.agents;
      progress(
        routed.routed
@@ -673,6 +683,8 @@ export async function runReview(

    let completedPasses = 0;
    let failedPasses = 0;
+    const taskProgress = (task: ReviewTask, line: string): void =>
+      progress(formatAgentActivity(task.bucket, task.label, line));
    // promptAndParse already retries internally (same-session corrective, then a
    // bounded fresh session). We do NOT wrap it in another retry loop. On a genuine
    // TIMEOUT, instead of dropping the work we break it into units that converge:
@@ -688,7 +700,7 @@ export async function runReview(
            system: task.system,
            text: buildTaskText(task),
            title: task.title,
-            onActivity: (line) => progress(`  ${task.label}: ${line}`),
+            onActivity: (line) => taskProgress(task, line),
            maxWaitMs: task.maxWaitMs,
            maxToolCalls: task.maxToolCalls,
            finalizeOnTimeout: true,
@@ -707,7 +719,7 @@ export async function runReview(
        }
        completedPasses++;
        if (truncated) {
-          progress(`  ${task.label}: hit its budget — returned partial findings`);
+          taskProgress(task, "hit its budget — returned partial findings");
          incomplete.push(
            `${capitalize(task.coverageLabel)} ran out of time; its findings may be incomplete.`,
          );
@@ -717,7 +729,7 @@ export async function runReview(
        // Non-timeout errors are genuine failures — record and move on.
        if (!(error instanceof AgentTimeoutError)) {
          failedPasses++;
-          progress(`  ${task.label}: FAILED (${errorMessage(error)})`);
+          taskProgress(task, `FAILED (${errorMessage(error)})`);
          // An auth/permission failure hits every pass identically; push one shared,
          // actionable note (deduped into a single coverage line) instead of N generic
          // per-pass failures that bury the real, fixable cause.
@@ -745,8 +757,9 @@ export async function runReview(
          const mid = Math.ceil(task.files.length / 2);
          const left = task.files.slice(0, mid);
          const right = task.files.slice(mid);
-          progress(
-            `  ${task.label}: exceeded ${minutes}m — splitting into 2 smaller passes (${left.length} + ${right.length} files)`,
+          taskProgress(
+            task,
+            `exceeded ${minutes}m — splitting into 2 smaller passes (${left.length} + ${right.length} files)`,
          );
          const over: Partial<ReviewTask> = { depth: task.depth + 1, maxWaitMs: childCap };
          enqueue(childTask(task, left, `↳${left.length}f`, over));
@@ -759,8 +772,9 @@ export async function runReview(
        // without tools; it just can't open a caller outside the diff. A lighter
        // cross-file review beats the coverage gap it used to report.
        if (!task.fallback && remaining > FALLBACK_TIMEOUT_MS) {
-          progress(
-            `  ${task.label}: exceeded ${minutes}m — retrying ${filesLabel(task.files)} with a fast no-tools pass`,
+          taskProgress(
+            task,
+            `exceeded ${minutes}m — retrying ${filesLabel(task.files)} with a fast no-tools pass`,
          );
          enqueue(
            childTask(task, task.files, "(no-tools fallback)", {
@@ -782,8 +796,9 @@ export async function runReview(
        const couldStillReduce =
          (canSubdivide && task.depth < MAX_SUBDIVIDE_DEPTH) || !task.fallback;
        if (error.reason === "stall") {
-          progress(
-            `  ${task.label}: its model requests went silent (stalled) and did not recover — ` +
+          taskProgress(
+            task,
+            `its model requests went silent (stalled) and did not recover — ` +
              `most likely provider rate limiting; reporting a coverage gap`,
          );
          // Name the likely cause. OpenCode retries a 429 internally without surfacing
@@ -797,15 +812,17 @@ export async function runReview(
              `those changes were not fully reviewed.`,
          );
        } else if (couldStillReduce) {
-          progress(
-            `  ${task.label}: exceeded ${minutes}m and the run's time budget is spent — reporting a coverage gap`,
+          taskProgress(
+            task,
+            `exceeded ${minutes}m and the run's time budget is spent — reporting a coverage gap`,
          );
          incomplete.push(
            `${capitalize(task.coverageLabel)} timed out and the overall review budget was exhausted before it could be broken down further; those changes were not fully reviewed.`,
          );
        } else {
-          progress(
-            `  ${task.label}: exceeded ${minutes}m even at its smallest reviewable unit — reporting a coverage gap`,
+          taskProgress(
+            task,
+            `exceeded ${minutes}m even at its smallest reviewable unit — reporting a coverage gap`,
          );
          incomplete.push(
            `${capitalize(task.coverageLabel)} exceeded its time budget even after being reduced to its smallest reviewable unit; those changes were not fully reviewed.`,
@@ -883,7 +900,15 @@ export async function runReview(
          tokens: coordinatorTokens,
          truncated: coordinatorTruncated,
          model: coordinatorModel,
-        } = await coordinate(handle, config, metadata, agentFindings, coverageNotes, stackManifest);
+        } = await coordinate(
+          handle,
+          config,
+          metadata,
+          agentFindings,
+          coverageNotes,
+          stackManifest,
+          (line) => progress(formatAgentActivity("coordinator", "coordinator", line)),
+        );
        agentCosts["coordinator"] = cost;
        trackTokens("coordinator", coordinatorTokens);
        trackModel("coordinator", config.coordinator.model, coordinatorModel);
@@ -978,7 +1003,9 @@ export async function runReview(
        const confirmation = await confirmStackRequalifications(
          grounded,
          options.stackConfirm.maxConfirmations,
-          patchConfirmer(handle, source),
+          patchConfirmer(handle, source, (line) =>
+            progress(formatAgentActivity(STACK_VERIFIER_AGENT, STACK_VERIFIER_AGENT, line)),
+          ),
          progress,
        );
        grounded = confirmation.findings;
@@ -21,6 +21,7 @@ export async function routeAgents(
  handle: OpencodeHandle,
  config: LoadedConfig,
  files: PatchWorkspaceFile[],
+  onActivity?: (line: string) => void,
 ): Promise<RouteResult> {
  const always = config.agents.filter((agent) => agent.alwaysRun);
  try {
@@ -31,6 +32,7 @@ export async function routeAgents(
        system: buildRouterSystem(),
        text: buildRouterTask(config.agents, files),
        title: "route",
+        onActivity,
      },
      parseRouteOutput,
    );
@@ -112,10 +112,6 @@ export const VerdictSchema = z.object({
 });
 export type Verdict = z.infer<typeof VerdictSchema>;

-export function parseVerdict(text: string): Verdict {
-  return VerdictSchema.parse(extractJsonObject(text));
-}
-
 /**
 * A stack verifier's verdict on whether a later stacked PR's patch actually
 * addresses an absence-style finding (v2 patch confirmation). Fails toward
@@ -128,21 +124,16 @@ export const StackVerdictSchema = z.object({
 });
 export type StackVerdict = z.infer<typeof StackVerdictSchema>;

-export function parseStackVerdict(text: string): StackVerdict {
-  return StackVerdictSchema.parse(extractJsonObject(text));
-}
-
 // @ref LLP 0011#attribution-and-identity [implements] — `agent` is engine-populated, so the model-facing schema drops it at the parse boundary instead of trusting call sites to strip it
 /**
 * The finding shape a MODEL may emit: `FindingSchema` minus the engine-only `agent`.
 * Both model outputs parse through this, so an `agent` a reviewer pass or the
 * coordinator invented is dropped where model JSON becomes typed data — the engine's own
- * fingerprint lookup is then the only thing that can set it. The transform re-widens the
- * result to `Finding` so downstream code (which does set `agent`) needs no change.
+ * fingerprint lookup is then the only thing that can set it. This schema deliberately
+ * has no Zod transform: the Claude runtime converts it to JSON Schema so the provider
+ * can enforce the same contract before the local parse boundary checks it again.
 */
-const ModelFindingSchema = FindingSchema.omit({ agent: true }).transform(
-  (finding): Finding => finding,
-);
+const ModelFindingSchema = FindingSchema.omit({ agent: true });

 /** Shape each sub-reviewer must emit. */
 export const ReviewerOutputSchema = z.object({
@@ -151,10 +142,13 @@ export const ReviewerOutputSchema = z.object({
 export type ReviewerOutput = z.infer<typeof ReviewerOutputSchema>;

 /** Mode-agnostic coordinator result; each Reporter decides how to render it. */
-export const CoordinatorOutputSchema = z.object({
+const CoordinatorModelOutputSchema = z.object({
  decision: z.enum(DECISIONS),
  findings: z.array(ModelFindingSchema).default([]),
  summary: z.string(),
+});
+
+export const CoordinatorOutputSchema = CoordinatorModelOutputSchema.extend({
  /**
   * Human-readable notes about reduced coverage (e.g. a review pass that hit its
   * time limit and returned partial findings, or was skipped). Populated by the
@@ -358,10 +352,6 @@ export const AdjudicationSchema = z.object({
 });
 export type Adjudication = z.infer<typeof AdjudicationSchema>;

-export function parseAdjudication(text: string): Adjudication {
-  return AdjudicationSchema.parse(extractJsonObject(text));
-}
-
 /** Minimum normalized evidence length to key a fingerprint on the code (below
 * this we fall back to the title). */
 const MIN_FP_EVIDENCE_LEN = 12;
@@ -442,14 +432,31 @@ export const RouteOutputSchema = z.object({
 });
 export type RouteOutput = z.infer<typeof RouteOutputSchema>;

-export function parseRouteOutput(text: string): RouteOutput {
-  return RouteOutputSchema.parse(extractJsonObject(text));
+type JsonSchema = Record<string, unknown>;
+type StructuredParser<T> = ((text: string) => T) & { jsonSchema: JsonSchema };
+
+/**
+ * Bind local Zod validation to the draft-07 JSON Schema Claude Code consumes.
+ * Local parsing remains authoritative; provider-side validation is a reliability
+ * layer that repairs malformed output before it reaches this trust boundary.
+ */
+// @ref LLP 0003#retry-taxonomy [implements] — Claude receives the same contract as the local parser and repairs mismatches in-session
+function structuredParser<T>(
+  parseSchema: z.ZodType<T>,
+  outputSchema: z.ZodType = parseSchema,
+): StructuredParser<T> {
+  const parser = ((text: string): T =>
+    parseSchema.parse(extractJsonObject(text))) as StructuredParser<T>;
+  parser.jsonSchema = z.toJSONSchema(outputSchema, { target: "draft-7" }) as JsonSchema;
+  return parser;
 }

-export function parseReviewerOutput(text: string): ReviewerOutput {
-  return ReviewerOutputSchema.parse(extractJsonObject(text));
-}
-
-export function parseCoordinatorOutput(text: string): CoordinatorOutput {
-  return CoordinatorOutputSchema.parse(extractJsonObject(text));
-}
+export const parseVerdict = structuredParser(VerdictSchema);
+export const parseStackVerdict = structuredParser(StackVerdictSchema);
+export const parseAdjudication = structuredParser(AdjudicationSchema);
+export const parseRouteOutput = structuredParser(RouteOutputSchema);
+export const parseReviewerOutput = structuredParser(ReviewerOutputSchema);
+export const parseCoordinatorOutput = structuredParser(
+  CoordinatorOutputSchema,
+  CoordinatorModelOutputSchema,
+);
@@ -156,7 +156,11 @@ export async function confirmStackRequalifications(
 * it into the no-tools stack verifier, and require `addressed: true`. The patch is
 * inlined, never materialized — there is no disk read and no tool use at all.
 */
-export function patchConfirmer(handle: OpencodeHandle, source: ReviewSource): ConfirmOne {
+export function patchConfirmer(
+  handle: OpencodeHandle,
+  source: ReviewSource,
+  onActivity?: (line: string) => void,
+): ConfirmOne {
  // Per-run patch memo: distinct findings citing the same (prNumber, file) each get
  // their own verdict but share one gh fetch. The source fails open to null (never
  // rejects), so memoizing the promise is safe.
@@ -186,6 +190,7 @@ export function patchConfirmer(handle: OpencodeHandle, source: ReviewSource): Co
        // A timeout here throws AgentTimeoutError, which the caller catches and STRIPS
        // (fail toward blocking) — so no finalize salvage, unlike the main verifier.
        finalizeOnTimeout: false,
+        onActivity: (line) => onActivity?.(`PR #${prNumber}: ${line}`),
      },
      parseStackVerdict,
    );
@@ -159,6 +159,7 @@ export async function verifyFindings(
            title: `verify-${index}`,
            maxWaitMs: VERIFY_TIMEOUT_MS,
            finalizeOnTimeout: true,
+            onActivity: (line) => onProgress?.(`  [verifier] #${index + 1}: ${line}`),
          },
          parseVerdict,
        );
@@ -468,7 +468,11 @@ export class GitHubReporter implements Reporter {
   * (annotate mode). Either way the feedback path fails soft — it never blocks the
   * comment from being posted.
   */
-  async report(review: CoordinatorOutput, feedback?: FeedbackRecord[]): Promise<void> {
+  async report(
+    review: CoordinatorOutput,
+    feedback?: FeedbackRecord[],
+    inputHash?: string,
+  ): Promise<void> {
    // Carry forward any per-PR dismissals recorded in the existing comment so they
    // survive re-reviews (a dismissed finding stays in the collapsed section).
    const existing = await this.findExistingComment();
@@ -487,7 +491,7 @@ export class GitHubReporter implements Reporter {
      : await this.computeFeedback(withFp, priorRecords, pinsIn);
    const link = await this.linkContextAsync();
    await this.upsertComment(
-      renderMarkdown(review, this.options.commentTag, dismissed, link, records, pins),
+      renderMarkdown(review, this.options.commentTag, dismissed, link, records, pins, inputHash),
    );
  }

@@ -834,6 +838,7 @@ export class GitHubReporter implements Reporter {
          link,
          next.feedback,
          next.pins,
+          state.inputHash,
        );
    await this.patchComment(existing.id, body);
    return {
@@ -3,11 +3,11 @@
 description: Security and secrets. Injection, credential or secret leakage, unsafe shell/child-process use, missing validation at trust boundaries.
 alwaysRun: true
 # Security is the highest-stakes agent and benefits most from stronger threat-model
-# reasoning, so it runs on the pro tier even though the other specialists use the
+# reasoning, so it runs on the Opus tier even though the other specialists use the
 # default model. Scoped to this one agent to limit the extra latency/rate-limit cost;
-# subdivide-on-timeout + the per-fetch deadline keep a slow pro pass from hanging.
+# subdivide-on-timeout + the per-fetch deadline keep a slow Opus pass from hanging.
 # @ref LLP 0009#config-and-prompt-templates [implements]
-model: openai/gpt-5.5-pro
+model: anthropic/claude-opus-5
 ---

 # Security & secrets
@@ -81,6 +81,11 @@ jobs:
          # disable setup-node's auto package-manager cache.
          package-manager-cache: false

+      # The anthropic/… models run through the Claude Code CLI (claude-code
+      # engine). Pinned exactly — see workflow.yml (expo-code-review.yml).
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/[email protected]
+
      # SECURITY: the base-ref checkout includes every .expo-code-review/ config,
      # whose auth.tokenEnv names the forwarded model credential. `ecr verify-config`
      # sweeps every config and refuses unless tokenEnv appears exactly once, in a
@@ -89,7 +94,7 @@ jobs:
      # @ref LLP 0009#guard-step-ordering-and-job-budgets [implements] — same $ECR_VERSION feeds guard and review
      - name: Guard config tokenEnv (root + routing + all scopes)
        env:
-          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'OPENAI_API_KEY' }}
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_REVIEW_SHARED_API_TOKEN' }}
        run: npx --yes -p "@expo/code-review-cli@$ECR_VERSION" ecr verify-config

      # Running via `issue_comment` makes this a manual /review, which the CLI detects
@@ -101,10 +106,11 @@ jobs:
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Layer-1 auth lock: keep in sync with the guard's EXPECTED.
-          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'OPENAI_API_KEY' }}
-          # OpenAI API key — the env var named by auth.tokenEnv in config.jsonc.
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          # Optional: override the model for every agent (uses your OpenCode login).
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_REVIEW_SHARED_API_TOKEN' }}
+          # Anthropic review credential — the env var named by auth.tokenEnv in
+          # config.jsonc (see workflow.yml for the accepted token shapes).
+          CLAUDE_CODE_REVIEW_SHARED_API_TOKEN: ${{ secrets.CLAUDE_CODE_REVIEW_SHARED_API_TOKEN }}
+          # Optional: override the model for every agent.
          REVIEWER_MODEL: ${{ vars.REVIEWER_MODEL }}
        run: |
          # Build the flags as a bash array so the path never word-splits.
@@ -111,6 +111,12 @@ jobs:
          # to save an empty cache and error).
          package-manager-cache: false

+      # The anthropic/… models run through the Claude Code CLI (claude-code
+      # engine). Pinned exactly — see workflow.yml (expo-code-review.yml).
+      - name: Install Claude Code CLI
+        if: steps.cmd.outputs.run == 'true'
+        run: npm install -g @anthropic-ai/[email protected]
+
      # SECURITY: the base-ref checkout above includes every .expo-code-review/
      # config.jsonc + routing.jsonc, whose auth.tokenEnv names the env var the CLI
      # forwards as the model credential. The canonical guard ships with the CLI:
@@ -126,7 +132,7 @@ jobs:
        if: steps.cmd.outputs.run == 'true'
        env:
          # (Comma-separated set for a multi-credential auth.providers config.)
-          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'OPENAI_API_KEY' }}
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_REVIEW_SHARED_API_TOKEN' }}
        run: npx --yes -p "@expo/code-review-cli@$ECR_VERSION" ecr verify-config

      - name: Run AI review
@@ -136,12 +142,13 @@ jobs:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Layer-1 auth lock: the CLI refuses to run when the tokenEnv it would honor
          # differs from this. Keep it in sync with the guard's EXPECTED.
-          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'OPENAI_API_KEY' }}
-          # OpenAI API key — the env var named by auth.tokenEnv in config.jsonc.
-          # Store it as a repo secret; a project-scoped key restricted to model
-          # inference (with a spend limit) is all the reviewer needs.
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          # Optional: override the model for every agent (uses your OpenCode login).
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_REVIEW_SHARED_API_TOKEN' }}
+          # Anthropic review credential — the env var named by auth.tokenEnv in
+          # config.jsonc. Store it as a repo secret: an `sk-ant-oat…` token minted
+          # by `claude setup-token`, or an `sk-ant-api…` Console key (the Claude
+          # Code CLI reads either).
+          CLAUDE_CODE_REVIEW_SHARED_API_TOKEN: ${{ secrets.CLAUDE_CODE_REVIEW_SHARED_API_TOKEN }}
+          # Optional: override the model for every agent.
          REVIEWER_MODEL: ${{ vars.REVIEWER_MODEL }}
          AGENTS: ${{ steps.cmd.outputs.agents }}
          ROUTE: ${{ steps.cmd.outputs.route }}
@@ -1,15 +1,17 @@
 // @ref LLP 0009#config-and-prompt-templates — root config: agent roster by filename, phase-1 defaults, auth
 {
-  // Default model for every agent. Override per-agent via frontmatter in the
-  // agent's markdown, or at runtime with the REVIEWER_MODEL env var
-  // (e.g. REVIEWER_MODEL=openai/gpt-5.4-mini).
-  "model": "openai/gpt-5.5",
+  // Default model for every agent. Anthropic models run through the Claude Code
+  // CLI engine (`claude -p`), inferred per agent from the model id — see `auth`
+  // below for the credential. Override per-agent via frontmatter in the agent's
+  // markdown, or at runtime with the REVIEWER_MODEL env var
+  // (e.g. REVIEWER_MODEL=anthropic/claude-haiku-4-5).
+  "model": "anthropic/claude-sonnet-5",

  // Agents: every markdown file in agents/ is one reviewer (id = filename).
  // Add or remove files to change the roster — no list needed here.
  // shared.md (prepended to every agent + coordinator) and coordinator.md are
  // reserved filenames. Per-agent overrides go in each file's YAML frontmatter,
-  // e.g. `---\nmodel: openai/gpt-5.5-pro\n---`.
+  // e.g. `---\nmodel: anthropic/claude-opus-5\n---`.

  // @ref LLP 0009#config-and-prompt-templates [implements] — suggestions off by default, not a schema limit
  "policy": {
@@ -46,49 +48,39 @@
  // HTML marker used to find + update the single PR comment. Keep it stable.
  "commentTag": "expo-ai-code-reviewer",

-  // How model credentials are provided. Default: an OpenAI API key.
+  // How model credentials are provided. Default: Anthropic via the Claude Code
+  // CLI. Anthropic models always run through that CLI — the engine is inferred
+  // per agent from the `anthropic/…` model id, so this entry only supplies the
+  // credential. In CI the tokenEnv holds the review credential (an `sk-ant-oat…`
+  // token minted by `claude setup-token`, or an `sk-ant-api…` Console key — the
+  // CLI reads either); locally an active `claude` login is enough, and the entry
+  // could even be omitted. ECR_EXPECTED_TOKEN_ENV (repo variable / workflow
+  // fallback) must equal this tokenEnv. `ecr setup-auth` walks you through it.
+  //
+  // Other providers run through OpenCode:
  //   "api-key": tokenEnv names the env var holding a provider API key. In CI,
-  //              store the key as a repo secret and pass it under that env var
-  //              (the scaffolded workflow does). If you omit `auth` entirely,
-  //              OpenCode's own login / ambient provider env vars are used.
-  // For Anthropic/Claude, see the dedicated block below (it now runs through the
-  // Claude Code CLI). For another provider, omit `auth` and set REVIEWER_MODEL
-  // after an `opencode auth login` for that provider.
+  //              store the key as a repo secret and pass it under that env var.
+  //   "auth": { "mode": "api-key", "provider": "openai", "tokenEnv": "OPENAI_API_KEY" }
  //
-  // MIXED setup (a ChatGPT/Codex subscription for the default models, plus a
-  // metered API key for pro-tier models the subscription doesn't offer): use the
-  // per-provider map instead, reference `openai-api/...` models in the frontmatter
-  // of the agents that need the pro tier, and set ECR_EXPECTED_TOKEN_ENV in the
-  // workflow to the comma-separated set of both env names.
+  //   ChatGPT/Codex subscription ("oauth"): tokenEnv holds the ACCESS token from
+  //   an `opencode auth login` ChatGPT sign-in — `ecr setup-auth` extracts it.
+  //   NEVER share the refresh token: it is single-use and dies on first rotation.
  //   "auth": { "providers": {
-  //     "openai":     { "mode": "oauth",   "tokenEnv": "CODEX_OAUTH_ACCESS_TOKEN" },
-  //     "openai-api": { "mode": "api-key", "tokenEnv": "OPENAI_API_KEY", "upstream": "openai" }
-  //   } }
-  // (openai oauth: tokenEnv holds the ACCESS token from an `opencode auth login`
-  // ChatGPT sign-in — `ecr setup-auth` extracts it. NEVER share the refresh
-  // token: it is single-use and dies on first rotation.)
-  //
-  // Anthropic runs through the Claude Code CLI, inferred from the model — set your
-  // models to "anthropic/…" (e.g. anthropic/claude-opus-5, anthropic/claude-sonnet-5)
-  // and run `claude setup-token`, exporting the token as CLAUDE_CODE_OAUTH_TOKEN (CI)
-  // or rely on your local `claude` login. An auth entry is OPTIONAL (tokenEnv just
-  // names the credential env); `ecr setup-auth` walks you through it.
-  //   "auth": { "providers": {
-  //     "anthropic": { "tokenEnv": "CLAUDE_CODE_OAUTH_TOKEN" }
+  //     "openai": { "mode": "oauth", "tokenEnv": "CODEX_OAUTH_ACCESS_TOKEN" }
  //   } }
  //
-  // MIXING engines is supported: the engine is inferred per agent from its model, so
-  // an anthropic entry may coexist with an openai (or any other) OpenCode provider.
-  // Each agent's `model` selects its engine — an `anthropic/…` agent runs through the
-  // Claude Code CLI while an `openai/…` agent runs through OpenCode, in the SAME run.
+  // MIXING engines is supported: the engine is inferred per agent from its model,
+  // so this anthropic entry may coexist with an openai (or any other) OpenCode
+  // provider — an `anthropic/…` agent runs through the Claude Code CLI while an
+  // `openai/…` agent runs through OpenCode, in the SAME run:
  //   "auth": { "providers": {
-  //     "anthropic": { "tokenEnv": "CLAUDE_CODE_OAUTH_TOKEN" },
+  //     "anthropic": { "tokenEnv": "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN" },
  //     "openai":    { "mode": "oauth", "tokenEnv": "CODEX_OAUTH_ACCESS_TOKEN" }
  //   } }
  "auth": {
-    "mode": "api-key",
-    "provider": "openai",
-    "tokenEnv": "OPENAI_API_KEY"
+    "providers": {
+      "anthropic": { "tokenEnv": "CLAUDE_CODE_REVIEW_SHARED_API_TOKEN" }
+    }
  },

  // Stack-aware requalification (ROOT-ONLY; off by default). When on, `ecr ci` walks
@@ -1,11 +1,11 @@
 <!-- @ref LLP 0009#config-and-prompt-templates — pro tier pinned on purpose: consolidation quality over serial-tail latency -->
 ---
 # The coordinator makes the final call — de-duping, re-judging severity, and
-# deciding — so it runs on the pro tier: consolidation quality matters more here
+# deciding — so it runs on the Opus tier: consolidation quality matters more here
 # than the small serial-tail latency it adds (no repo tools, one bounded pass).
 # Override with a cheaper model if you'd rather trade decision quality for latency.
 # @ref LLP 0009#config-and-prompt-templates [implements]
-model: openai/gpt-5.5-pro
+model: anthropic/claude-opus-5
 ---

 # Coordinator — consolidation & decision
@@ -67,6 +67,13 @@ jobs:
          # to save an empty cache and error).
          package-manager-cache: false

+      # The anthropic/… models in .expo-code-review/config.jsonc run through the
+      # Claude Code CLI (the claude-code engine). Pinned exactly — an unpinned CLI
+      # would silently drift on every CI run; bump it deliberately. Remove this
+      # step if you switch every model to an OpenCode-served provider.
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/[email protected]
+
      # SECURITY: the TRUSTED BASE checkout above includes every
      # .expo-code-review/config.jsonc + routing.jsonc, whose auth.tokenEnv names the
      # env var the CLI forwards as the model credential. The canonical guard ships
@@ -87,7 +94,7 @@ jobs:
      - name: Guard config tokenEnv (root + routing + all scopes)
        env:
          # (Comma-separated set for a multi-credential auth.providers config.)
-          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'OPENAI_API_KEY' }}
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_REVIEW_SHARED_API_TOKEN' }}
        run: npx --yes -p "@expo/code-review-cli@$ECR_VERSION" ecr verify-config

      - name: Run AI review
@@ -101,12 +108,13 @@ jobs:
          # honor (root config.jsonc, or routing.jsonc defaults.auth) differs from
          # this — it catches what the guard step above can't. Keep it in sync
          # with the guard.
-          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'OPENAI_API_KEY' }}
-          # OpenAI API key — the env var named by auth.tokenEnv in config.jsonc.
-          # Store it as a repo secret; a project-scoped key restricted to model
-          # inference (with a spend limit) is all the reviewer needs.
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          # Optional: override the model for every agent (uses your OpenCode login).
+          ECR_EXPECTED_TOKEN_ENV: ${{ vars.ECR_EXPECTED_TOKEN_ENV || 'CLAUDE_CODE_REVIEW_SHARED_API_TOKEN' }}
+          # Anthropic review credential — the env var named by auth.tokenEnv in
+          # config.jsonc. Store it as a repo secret: an `sk-ant-oat…` token minted
+          # by `claude setup-token`, or an `sk-ant-api…` Console key (the Claude
+          # Code CLI reads either).
+          CLAUDE_CODE_REVIEW_SHARED_API_TOKEN: ${{ secrets.CLAUDE_CODE_REVIEW_SHARED_API_TOKEN }}
+          # Optional: override the model for every agent.
          REVIEWER_MODEL: ${{ vars.REVIEWER_MODEL }}

      # Observability: the per-run log (token/cache/cost totals + per-pass timing +
Author	SHA1	Message	Date
Brent Vatne	7d75093062	exec: de-flake the SIGKILL escalation test The test spawned a node child that installed a SIGTERM handler and relied on a 250ms deadline to fire after it. The deadline timer starts at spawn, so on a loaded runner node had not yet reached `process.on('SIGTERM')` when the signal landed: the default disposition killed it outright, the 5s grace-timer escalation never ran, and the elapsed-time assertion saw 462ms. That failed the v0.10.0 release job before the publish step. Use `sh -c 'trap "" TERM; exec sleep 30'` instead. The shell boots in ~1ms rather than a node runtime's tens of ms, and an ignored signal survives exec where an installed handler would not, so the sleep holding the group ignores SIGTERM too. Widen the deadline to 1s as well, so the window the child has to get there is 4x larger.	2026-08-05 14:38:17 -07:00
Brent Vatne	b5466193b6	runtime: stream Claude agent activity (#58 )	2026-08-04 21:39:03 -07:00
Brent Vatne	9955a2c014	templates: default new scaffolds to Claude (sonnet 5, opus for security/coordinator) (#59 )	2026-08-04 18:46:59 -07:00
Brent Vatne	092791d045	ci: reuse unchanged review results (#57 )	2026-08-04 15:56:47 -07:00
Brent Vatne	ae594054af	ci: use shared Claude review token	2026-08-04 15:36:18 -07:00
Philippe Loulidi	a5453ba045	ref-check: cover scope-relative citations that carry an extension (#52 ) * ref-check: cover scope-relative citations that carry an extension A scoped prompt writes `pgbouncer/base/pdb.yaml` for what is really `infrastructure/pgbouncer/base/pdb.yaml`. Only extensionless tokens were resolved before, so the precise ref did not silence the citation and the only thing that did was `glob:*/pdb.yaml` — which resolves while pointing at every same-named file in the repo. Six agents pinning a real setup all reached for that glob. Suggestions now name the resolved path; a token with its own wildcard keeps the glob form. ref-check: don't report scrubbed ambient config as a stale ref The read root is scrubbed of AGENTS.md, CLAUDE.md, .env and friends, so a ref to one is missing there by design. The template's own shared.md cites AGENTS.md, so the review note cried wolf on every PR — including this repo's, which is how it was found. The standalone gate is unchanged: there the tree is a real checkout. * ref-check: strip anchor, line and glob prefix before the ambient-config test `AGENTS.md#conventions` and `glob:*/.env.local` name scrubbed files too. Found by the review on this PR. ref-check: see Terraform citations, resolve wildcards as globs, probe scope first Re-review findings, each reproduced before fixing: - .tf/.tfvars/.hcl were missing from the citation allowlist, so `backend.tf` or `/.terraform.lock.hcl` in a prompt was never checked — 18 unchecked citations in the infra setup that motivated this feature. - A wildcard token now resolves as a glob, scope-rebased when that is what matches; the suggested `glob:` ref for `pgbouncer//patch.yaml` used to be a ref that itself failed the check. - namedPath probes the scope before the root: a scoped prompt citing `alerts/` means its own tree even when the root has one too. - USAGE documents the `target` field --json now emits.	2026-08-03 16:08:26 -06:00
Philippe Loulidi	4349be0b24	ref-check: make the suggested ref actually silence its citation (#51 ) A scoped prompt names a directory by basename (`cert-manager`); the ref that pins it is root-relative (`infrastructure/cert-manager/`). Coverage only compared the token as written, so adding the exact ref the message suggested left the same problem reported. Coverage now also accepts the path the token resolved to, in plain and glob form.	2026-08-03 15:29:59 -06:00