@bookedsolid/rea 0.9.0 → 0.9.1

package/README.md

@@ -2,14 +2,15 @@
 
 **Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review.**
 
-[![npm version](https://img.shields.io/badge/npm-pending-lightgrey)](https://www.npmjs.com/package/@bookedsolid/rea)
-[![CI](https://img.shields.io/badge/ci-pending-lightgrey)](https://github.com/bookedsolidtech/rea/actions)
-[![provenance](https://img.shields.io/badge/npm%20provenance-pending-lightgrey)](https://docs.npmjs.com/generating-provenance-statements)
+[![npm version](https://img.shields.io/npm/v/%40bookedsolid%2Frea?color=cb3837&label=npm)](https://www.npmjs.com/package/@bookedsolid/rea)
+[![CI](https://github.com/bookedsolidtech/rea/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bookedsolidtech/rea/actions/workflows/ci.yml)
+[![npm provenance](https://img.shields.io/badge/npm%20provenance-attested-blue?logo=npm)](https://docs.npmjs.com/generating-provenance-statements)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 [![DCO](https://img.shields.io/badge/DCO-required-green)](https://developercertificate.org/)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
 
-> Status: 0.0.x, pre-release. Badges are placeholders until the first publish.
+> Status: `0.9.x` — published to npm with provenance. See
+> [CHANGELOG.md](./CHANGELOG.md) for the per-release history.
 
 ---
 
@@ -31,18 +32,38 @@ Node 22+ and pnpm 9+ required.
 REA is a governance layer for Claude Code. It is a single npm package that
 ships four things:
 
-1. A **hook layer** — 11 shell scripts wired into Claude Code's `PreToolUse`
-   and `PostToolUse` events. Hooks enforce secret scanning, dangerous-command
-   interception, blocked-path protection, settings protection, attribution
-   rejection, and commit/push review gates.
+1. A **hook layer** — 14 shell scripts total. 12 are registered in the
+   shipped `.claude/settings.json` and fire on Claude Code's `PreToolUse`
+   / `PostToolUse` events (secret scanning, dangerous-command
+   interception, blocked-path protection, settings protection,
+   attribution rejection, env-file protection, disclosure-policy
+   routing, dependency audit, changeset security, architecture advisory,
+   PR-issue-link advisory, and the Claude-Code push-review adapter).
+   One more shipped hook, `commit-review-gate.sh`, is a Claude
+   `PreToolUse: Bash` hook that matches `git commit` — it is shipped
+   ready-to-wire but intentionally NOT registered in the default
+   `.claude/settings.json`, so operators who want commit-time review can
+   opt in by adding a rule. The final script,
+   `push-review-gate-git.sh`, is a thin native-git adapter that sources
+   `hooks/_lib/push-review-core.sh` (the same shared core used by the
+   Claude-Code push-review adapter), so a fix to the push-review logic
+   lands in one place. It ships for consumers who manually configure
+   a wrapper-based `.husky/pre-push` (and as scaffolding for a future
+   installer revision). The default `rea init` installer emits a
+   standalone inline `.husky/pre-push` body instead of wiring the
+   adapter — see the Hooks section for details.
 2. A **gateway layer** — an MCP server (`rea serve`) that proxies downstream
    MCP servers through a middleware chain. Every tool call — native or
    proxied — is classified, policy-checked, redacted, audited, and
-   size-capped before it executes.
-3. A **policy runtime** — `.rea/policy.yaml` with strict zod-validated
+   size-capped before it executes. The gateway also supervises downstream
+   child processes: unexpected deaths are detected eagerly, the circuit
+   breaker never reuses a zombie client, and a `SESSION_BLOCKER` audit
+   event fires when a downstream crosses the per-session failure threshold.
+3. A **policy runtime** — `.rea/policy.yaml` with a strict zod-validated
    schema. Defines autonomy level, a hard ceiling (`max_autonomy_level`),
-   blocked paths, attribution rules, context protection, and optional
-   Discord notification webhook.
+   blocked paths, attribution rules, context protection, redaction and
+   injection tuning, review/cache knobs, and an optional Discord
+   notification webhook.
 4. A **kill switch** — `.rea/HALT` is a single file. If it exists, every
    tool call is denied at the middleware and hook layers. Use
    `rea freeze --reason "..."` to create it and `rea unfreeze --reason "..."`
@@ -69,7 +90,8 @@ to build a separate package that composes with REA.
   no `rea stop`, no systemd unit. A short-lived `.rea/serve.pid`
   breadcrumb is written at startup so `rea status` can detect a live
   gateway — it is removed on graceful shutdown and never used for
-  locking or lifecycle management.
+  locking or lifecycle management. A per-session `.rea/serve.state.json`
+  snapshot accompanies it for live per-downstream introspection.
 - **Not a hosted service.** There is no REA Cloud, no SaaS tier, no
   multi-token workstreams, no workload isolation platform.
 - **Not a 70-agent roster.** 10 curated agents ship in the package. Four
@@ -130,10 +152,16 @@ its own.
 rea doctor
 ```
 
-`rea doctor` checks hook coverage, policy parse, husky commit-msg hook
-install, `.mcp.json` gateway wiring, Codex plugin availability, and the
-integrity of the audit hash chain. It returns a pass/fail summary with
-specific remediation hints.
+`rea doctor` checks `.rea/` directory presence, policy parse, registry
+parse, curated-agent presence, hook coverage, `.claude/settings.json`
+wiring, commit-msg / pre-push git hooks, Codex CLI + agent availability
+(when `codex_required: true`), and the TOFU fingerprint store. It
+returns a pass/fail summary with specific remediation hints. In non-git
+directories (knowledge repos, docs-only projects) the commit-msg and
+pre-push checks are skipped cleanly — REA governs policy and injection
+detection there, not pushes. Audit hash-chain integrity is verified by
+a separate command — `rea check` (on-disk tail) or the full replay
+verifier — not by `rea doctor`.
 
 ### 4. Watch the running gateway
 
@@ -144,10 +172,31 @@ rea status --json       # JSON — pipe to jq
 
 `rea status` is the live-process view. It reads the pidfile written by
 `rea serve`, verifies the pid is alive, and surfaces the session id,
-policy summary (profile, autonomy, HALT state), and audit stats (lines,
-last timestamp, whether the tail record's hash looks well-formed). Use
-`rea check` when you want the pure on-disk view without probing for a
-live process.
+policy summary (profile, autonomy, HALT state), audit stats (lines,
+last timestamp, whether the tail record's hash looks well-formed), and
+— as of 0.9.0 — a **per-downstream live block** sourced from
+`.rea/serve.state.json`. Each downstream entry includes:
+
+| Field                       | Type                                 | Meaning                                                         |
+| --------------------------- | ------------------------------------ | --------------------------------------------------------------- |
+| `name`                      | string                               | Registry server name                                            |
+| `connected`                 | boolean                              | MCP client currently holds an open stdio transport              |
+| `healthy`                   | boolean                              | Gateway considers the server safe to route calls to             |
+| `circuit_state`             | `closed` \| `open` \| `half-open`    | Current breaker position                                        |
+| `retry_at`                  | ISO timestamp \| `null`              | Next allowed half-open probe, when `open`                       |
+| `last_error`                | string \| `null`                     | Bounded, redacted diagnostic from the most recent failure       |
+| `tools_count`               | integer \| `null`                    | Tool count from the last successful `tools/list`                |
+| `open_transitions`          | integer                              | Cumulative circuit-open events in this session                  |
+| `session_blocker_emitted`   | boolean                              | Whether `SESSION_BLOCKER` has fired for this server yet         |
+
+`.rea/serve.state.json` is the authoritative live source — it is written
+atomically (temp+rename) on every circuit transition and supervisor
+event, debounced through a 250 ms trailing timer so a flap storm can't
+spam disk. State files written by a pre-0.9.0 gateway degrade gracefully:
+`downstreams` surfaces as `null` with a hint to upgrade.
+
+Use `rea check` when you want the pure on-disk view (policy + HALT +
+tail audit) without probing for a live process.
 
 ### 5. Optional Prometheus `/metrics` endpoint
 
@@ -172,6 +221,39 @@ Set `REA_LOG_LEVEL=debug` for verbose gateway logs; the default is
 `info`. Records are JSON lines on a non-TTY stderr and pretty-printed
 on an interactive terminal.
 
+### 6. Ask the gateway how it's doing — `__rea__health`
+
+The gateway advertises a single built-in tool, `__rea__health`, in
+every `listTools` response regardless of downstream state. Calling it
+returns a snapshot of gateway version, uptime, HALT state, policy
+summary, and per-downstream health. The handler **short-circuits the
+middleware chain** — it is callable under HALT and at any autonomy
+level — because it is the tool an operator reaches for when everything
+else is frozen. Every invocation still writes an audit record.
+
+The wire response is **sanitized by default**: `halt_reason` and
+`downstreams[].last_error` surface as `null`. Full diagnostic detail
+lives in the audit record's metadata (`halt_reason`,
+`downstream_errors[]`) — local disk, hash-chained, not
+LLM-reachable — which is the right sink for trusted-operator text.
+
+Operators who genuinely need error strings on the MCP wire can opt in:
+
+```yaml
+# .rea/policy.yaml
+gateway:
+  health:
+    expose_diagnostics: true
+```
+
+Opt-in mode still runs the full sanitizer pass: `redactSecrets` replaces
+known secret patterns with `[REDACTED:*]`, `classifyInjection` replaces
+any non-`clean` diagnostic string (verdicts `suspicious` or
+`likely_injection`) with the exported `INJECTION_REDACTED_PLACEHOLDER`
+token — the literal string `<redacted: suspected injection>` — and
+oversize values are bounded before scanning so an adversarial downstream
+can't DoS the tool with a multi-megabyte error.
+
 ## Architecture
 
 ### Middleware chain
@@ -192,12 +274,12 @@ tool call
 │ rate-limit         — token bucket per server      │
 │ circuit-breaker    — trip on downstream failure   │
 │ redact (args)      — secrets in arguments         │
-│ injection          — prompt-injection heuristics  │
 │                                                   │
 │ ==== EXECUTE ====                                 │
 │                                                   │
-│ redact (result)    — secrets in result            │
 │ result-size-cap    — bounded response             │
+│ redact (result)    — secrets in result            │
+│ injection          — prompt-injection in result   │
 │ audit.exit         — hash-chained record close    │
 └───────────────────────────────────────────────────┘
     │
@@ -209,14 +291,104 @@ result
 from policy. Policy is re-read on every invocation — any edit to
 `policy.yaml` takes effect on the next tool call.
 
-### Hook layer
+The `__rea__health` meta-tool is the one documented exception: it
+short-circuits the chain (see §6 above) and writes an audit record from
+the short-circuit handler itself.
+
+### Gateway supervisor
+
+Downstream MCP servers run as child processes over stdio. The
+`DownstreamConnection` wrapper wires the SDK `StdioClientTransport`'s
+`onclose` + `onerror` callbacks, so an unexpected child death — OS
+OOM-kill, unhandled exception in the child, stdio pipe error outside a
+caller-initiated close — is detected **eagerly**: the client and
+transport are nulled before the next `callTool` tries to use them. The
+following call forces a genuine reconnect rather than invoking through a
+stale handle.
+
+"Not connected" errors from the SDK (the in-flight fallback) are
+promoted to the same respawn path with the same eager invalidation.
+A 30-second flapping guard refuses a second reconnect that lands too
+quickly after the previous one — the child is clearly unhealthy and the
+circuit breaker is a better place to handle it.
+
+`SessionBlockerTracker` subscribes to circuit-breaker
+`onStateChange` events and counts circuit-open transitions per
+`(session_id, server_name)`. Once the threshold (default: 3) is
+crossed, exactly one `SESSION_BLOCKER` audit record is appended and a
+LOUD structured log line is emitted — subsequent opens do not re-fire
+until recovery (a transition to `closed`) re-arms the emit. A new
+session (new `rea serve` process) drops every counter and starts fresh.
+
+### Live state
+
+`.rea/serve.state.json` is the on-disk live snapshot. It is written
+once at boot and again on every circuit transition or supervisor event,
+debounced through a 250 ms trailing timer and flushed atomically via
+temp-file + rename. The snapshot carries a `session_id` (boot-time
+ownership key) and `owner_pid`; a newly-started `rea serve` whose
+predecessor crashed without cleanup can detect the abandoned file and
+take over ownership rather than stalling forever. `rea status` is a
+read-only consumer of this file.
+
+### Downstream environment safety
+
+`rea serve` does **not** forward `process.env` wholesale to downstream
+children. Each child gets:
+
+1. A fixed allowlist of neutral OS vars (`PATH`, `HOME`, `TZ`,
+   `NODE_OPTIONS`, …).
+2. Any names opted into via `registry.yaml#servers[].env_passthrough` —
+   the schema refuses secret-looking names (`*_TOKEN`, `*_KEY`,
+   `*_SECRET`, …), so secrets must be named explicitly.
+3. Values from the registry's `env:` mapping, which may contain
+   `${VAR}` placeholders resolved against the host environment
+   (0.3.0). Secret-looking values are redacted in logs by default.
+   A `${VAR}` whose host variable is unset is treated as fatal — the
+   downstream is marked unhealthy rather than handed an unresolved
+   placeholder.
 
-Hooks are shell scripts wired into `.claude/settings.json`. They run at
-Claude Code tool-invocation time, independently of the gateway. Both
-layers fail closed. Bypassing one does not disable the other.
+### Hook layer
 
-Every hook sources `hooks/_lib/halt-check.sh` and `hooks/_lib/policy-read.sh`
-at the top of the script. Every hook uses `set -euo pipefail`.
+Hooks are shell scripts. 14 ship in the package; 12 are wired into
+the default `.claude/settings.json` and run at Claude Code
+tool-invocation time, independently of the gateway. The remaining
+two (`commit-review-gate.sh` and `push-review-gate-git.sh`) ship
+ready-to-wire but are not registered by default — see "What REA is"
+above and the inventory table at the end of this section for the full
+picture. Both layers (hooks and the gateway middleware) fail closed.
+Bypassing one does not disable the other.
+
+Every hook uses `set -euo pipefail` (or `set -uo pipefail` for the
+ones that process stdin JSON) and performs a HALT check near the top.
+The review-gate hooks (`push-review-gate.sh`, `push-review-gate-git.sh`,
+`commit-review-gate.sh`) additionally anchor `REA_ROOT` to their own
+on-disk location (BUG-012 fix, 0.6.2) — for those hooks,
+`CLAUDE_PROJECT_DIR` is accepted only as an advisory signal because it
+is caller-controlled. The remaining hooks (e.g. `secret-scanner.sh`,
+`settings-protection.sh`, `blocked-paths-enforcer.sh`,
+`dangerous-bash-interceptor.sh`) still derive `REA_ROOT` from
+`${CLAUDE_PROJECT_DIR:-$(pwd)}`; extending the script-anchor idiom to
+those hooks is tracked as an open hardening item. Cross-repo
+invocations (running a review-gate hook from a consumer project that
+is not the rea install) short-circuit cleanly using
+`git --git-common-dir` comparison (0.6.1).
+
+The two push-review adapters that ship in `hooks/` share a single
+implementation core at `hooks/_lib/push-review-core.sh` (0.7.0 BUG-008
+cleanup) so a fix lands in one place: `push-review-gate.sh` consumes
+Claude-Code PreToolUse JSON and is what `rea init` copies to
+`.claude/hooks/`; `push-review-gate-git.sh` consumes git's native
+`.husky/pre-push` refspec lines and is shipped for consumers who wire
+a wrapper-based `.husky/pre-push` that execs it directly. The default
+`rea init` installer does NOT currently emit that wrapper — it writes
+a standalone inline gate body as `.husky/pre-push` (source of truth:
+`src/cli/install/pre-push.ts`). The native-git adapter and the
+inline installer currently implement the same protected-path logic
+separately; unifying the husky installer on the adapter is tracked as
+follow-up hardening. `commit-review-gate.sh` is a standalone Claude
+`PreToolUse: Bash` hook that matches `git commit`; it does not source
+the push-review core.
 
 ### Slash commands
 
@@ -228,9 +400,13 @@ during `rea init`.
 Ten curated agents ship in the package: `rea-orchestrator`, `code-reviewer`,
 `codex-adversarial`, `security-engineer`, `accessibility-engineer`,
 `typescript-specialist`, `frontend-specialist`, `backend-engineer`,
-`qa-engineer`, `technical-writer`. Four profiles
-(`client-engagement`, `bst-internal`, `lit-wc`, `open-source`) layer
-additional specialists on top.
+`qa-engineer`, `technical-writer`. Profiles
+(`client-engagement`, `bst-internal`, `bst-internal-no-codex`,
+`lit-wc`, `open-source`, `open-source-no-codex`, `minimal`) layer
+additional specialists on top. The `-no-codex` variants match their
+parents but default `review.codex_required: false` so teams without a
+Codex CLI on the bench get a first-class opt-out rather than relying on
+`REA_SKIP_CODEX_REVIEW`.
 
 The orchestrator is the single entry point for non-trivial tasks. The
 CLAUDE.md template installed by `rea init` instructs the host agent:
@@ -259,9 +435,38 @@ Three things make this work:
 2. The **`/codex-review` slash command** is one of the five shipped
    commands. It produces an audit entry including the request summary,
    response summary, and pass/fail signal.
-3. The **`push-review-gate.sh` hook** checks for a recent `/codex-review`
-   audit entry on the current branch and warns (does not block) if none
-   is present.
+3. The **`push-review-gate.sh` hook** blocks (exit 2) every protected-path
+   push that does not carry a matching `codex.review` audit entry for the
+   pushed `head_sha` with a `verdict` of `pass` or `concerns`. The only
+   other way through the protected-path branch is an active Codex-only
+   waiver (`REA_SKIP_CODEX_REVIEW=<reason>`, 0.8.0 narrowing). For
+   **non-protected-path** pushes the gate runs a separate review-cache
+   lookup — this is where the cache predicate and pushed-ref key
+   hardening live. The cache-hit predicate requires
+   `.hit == true and .result == "pass"` (0.8.0 hardening — a cached
+   `fail` verdict no longer satisfies the gate), and the cache key is
+   derived from the **pushed source ref** (from pre-push stdin) rather
+   than the checkout branch, so `git push origin hotfix:main` from a
+   `feature` checkout correctly looks up the `hotfix` cache entry.
+
+### Codex-only waiver semantics (0.8.0)
+
+Through 0.7.0, `REA_SKIP_CODEX_REVIEW=<reason>` short-circuited the
+**entire** push-review gate — operators reached for it to silence a
+transient Codex outage and accidentally bypassed HALT, the cross-repo
+guard, and the general push-review gate. 0.8.0 narrows it to what the
+name implies: the waiver satisfies **only** the protected-path Codex
+audit requirement. HALT, cross-repo guard, ref-resolution failures, and
+push-review-cache misses still block. The skip audit record is still
+named `codex.review.skipped` and still fails the `codex.review` jq
+predicate — skipping a review is not a review.
+
+For the previous whole-gate bypass, use `REA_SKIP_PUSH_REVIEW=<reason>`
+(unchanged, 0.5.0). It writes `push.review.skipped` with an
+`os_identity` sub-object (uid, whoami, hostname, pid, ppid, tty, ci)
+so auditors can distinguish a real operator from a forged git-config
+actor, and refuses on CI runners unless the policy opts in via
+`review.allow_skip_in_ci: true`.
 
 Codex responses are treated as untrusted input. They flow through the
 `redact` and `injection` middleware on return — same treatment as any
@@ -269,30 +474,32 @@ other downstream tool result. Codex never receives `.rea/policy.yaml`
 content in its prompts; Codex reviews diffs, not policy.
 
 If Codex is not installed, `rea doctor` warns with a one-line install
-hint. REA does not require Codex to function, but the default workflow
-assumes it.
+hint. REA does not require Codex to function — the `bst-internal-no-codex`
+and `open-source-no-codex` profiles disable the requirement entirely,
+and `ClaudeSelfReviewer` is the in-process fallback (tagged
+`degraded: true` in the audit record so self-review is visible and
+countable).
 
 ## Hooks
 
-Eleven hooks, down from reagent's 26. Each does one thing.
+Fourteen hooks. Each does one thing.
 
 | Hook | Event | One-line purpose |
 | --- | --- | --- |
 | `dangerous-bash-interceptor` | PreToolUse: Bash | Block categories of destructive shell commands |
 | `env-file-protection` | PreToolUse: Bash | Block reads of `.env*` files |
-| `dependency-audit-gate` | PreToolUse: Bash | Run `npm audit`; block on high/critical |
+| `dependency-audit-gate` | PreToolUse: Bash | Verify packages exist on the registry before install |
 | `commit-review-gate` | PreToolUse: Bash | Intercept `git commit`; require review on non-trivial diffs |
-| `push-review-gate` | PreToolUse: Bash | Intercept `git push`; warn if no recent `/codex-review` |
-| `attribution-advisory` | PreToolUse: Bash | Block commits containing AI attribution markers |
+| `push-review-gate` | PreToolUse: Bash | Intercept `git push` (Claude-Code-JSON adapter); protected-path + Codex audit |
+| `push-review-gate-git` | `.husky/pre-push` | Native git adapter around the same core |
+| `attribution-advisory` | PreToolUse: Bash | Block commits / PRs containing AI attribution markers |
+| `pr-issue-link-gate` | PreToolUse: Bash | Advisory warn when `gh pr create` has no linked issue |
+| `security-disclosure-gate` | PreToolUse: Bash | Route security-keyword `gh issue create` to private disclosure |
 | `secret-scanner` | PreToolUse: Write\|Edit | Scan file writes for credential patterns |
-| `settings-protection` | PreToolUse: Write\|Edit | Block agent writes to `.claude/settings.json` |
+| `settings-protection` | PreToolUse: Write\|Edit | Block agent writes to `.claude/settings.json`, hook dirs, policy |
 | `blocked-paths-enforcer` | PreToolUse: Write\|Edit | Enforce `blocked_paths` from policy |
-| `changeset-security-gate` | PreToolUse: Write\|Edit | Require changeset entry on security-relevant changes |
-| `architecture-review-gate` | PostToolUse: Write\|Edit | Flag edits crossing architectural boundaries |
-
-A twelfth hook, `security-disclosure-gate`, intercepts `gh issue create`
-commands containing security-sensitive keywords and redirects to private
-disclosure. It is installed as part of the Bash PreToolUse set.
+| `changeset-security-gate` | PreToolUse: Write\|Edit | Guard changesets against GHSA leaks and malformed frontmatter |
+| `architecture-review-gate` | PostToolUse: Write\|Edit | Flag edits crossing architectural boundaries (advisory) |
 
 ## Slash commands
 
@@ -311,7 +518,7 @@ rejected, not ignored.
 
 | Field | Type | Purpose |
 | --- | --- | --- |
-| `version` | string, `"1"` | Schema version; only `"1"` accepted in 0.1.x |
+| `version` | string, `"1"` | Schema version; only `"1"` accepted in the current major |
 | `profile` | string | Profile name from `profiles/` (e.g. `bst-internal`) |
 | `autonomy_level` | `L0`\|`L1`\|`L2`\|`L3` | Current autonomy. `L0` = read-only; `L3` = full tool access |
 | `max_autonomy_level` | `L0`\|`L1`\|`L2`\|`L3` | Hard ceiling. `autonomy_level` cannot exceed this |
@@ -321,6 +528,13 @@ rejected, not ignored.
 | `context_protection.delegate_to_subagent` | string[] | Commands that must run in a subagent context to preserve the parent's context window |
 | `context_protection.max_bash_output_lines` | number | Truncate long bash output at this line count |
 | `notification_channel` | string | Optional Discord webhook URL. Empty string = no notifications |
+| `review.codex_required` | boolean | When `false`, protected-path pushes don't require a Codex audit (first-class no-Codex mode). Default `true` |
+| `review.cache_max_age_seconds` | number | TTL for entries in `.rea/review-cache.jsonl`. Default 3600 |
+| `review.allow_skip_in_ci` | boolean | When `true`, `REA_SKIP_PUSH_REVIEW` is accepted on CI runners. Default `false` |
+| `injection.suspicious_blocks_writes` | boolean | `bst-internal` posture — `suspicious` verdict on a write/destructive tool denies instead of warning. Default `false` |
+| `redact.patterns[]` | string[] | User-supplied secret patterns; vetted via `safe-regex` at load |
+| `redact.match_timeout_ms` | number | Per-call regex budget. Default 100 |
+| `gateway.health.expose_diagnostics` | boolean | When `true`, `__rea__health` emits redacted+classified diagnostic strings on the wire. Default `false` (null) |
 
 `autonomy_level > max_autonomy_level` is rejected at parse time. Setting
 `promotion_requires_human_approval: false` requires the CLI flag
@@ -345,8 +559,11 @@ npx @bookedsolid/rea init --from-reagent
 - Leaves `.reagent/` in place; you delete it manually after verifying
   `rea doctor` passes and a dogfood run completes.
 
-Reagent will be deprecated via `npm deprecate` within seven days of
-REA 0.1.0. The deprecation notice points users here.
+See [MIGRATION-0.5.0.md](./MIGRATION-0.5.0.md) for the BUG-008 / BUG-009
+/ BUG-010 coordinated fix window. Between 0.5.0 and 0.9.0, the breaking
+semantic change worth calling out is 0.8.0's narrowing of
+`REA_SKIP_CODEX_REVIEW` to a Codex-only waiver — see the CHANGELOG
+entry for the migration steps.
 
 ## Security
 

package/SECURITY.md

@@ -2,10 +2,16 @@
 
 ## Supported Versions
 
-| Version | Supported |
-| ------- | --------- |
-| 0.1.x   | Yes       |
-| < 0.1   | No (pre-release) |
+Security fixes land on the latest minor line. Older minors receive fixes only
+when the issue is critical and a backport is tractable.
+
+| Version | Supported                                   |
+| ------- | ------------------------------------------- |
+| 0.9.x   | Yes — active line                           |
+| 0.8.x   | Critical fixes only, 30 days from 0.9.0     |
+| 0.7.x   | No — superseded; upgrade recommended        |
+| ≤ 0.6.x | No — superseded; upgrade recommended        |
+| < 0.1   | No (pre-release)                            |
 
 ## Reporting a Vulnerability
 
@@ -85,10 +91,21 @@ REA's security model is defense-in-depth across two independent layers:
 
 **Hook layer** (development-time, Claude Code hooks):
 
-- 11 Claude Code hooks enforce security at the point of tool invocation
-- `security-disclosure-gate` blocks public issue creation for security topics
+- 14 shell scripts ship in the hook layer. 12 are wired into Claude Code's
+  `PreToolUse` / `PostToolUse` events via the default `.claude/settings.json`.
+  Two are shipped but NOT registered by default: `commit-review-gate.sh`
+  is a `PreToolUse: Bash` hook that matches `git commit` for operators who
+  opt into commit-time review by adding a rule, and `push-review-gate-git.sh`
+  is a native-git adapter that sources `hooks/_lib/push-review-core.sh`
+  (the same shared core used by the Claude-Code push-review adapter),
+  shipped for consumers who wire a wrapper-based `.husky/pre-push` that
+  execs it directly. `rea init`'s default installer emits a standalone
+  inline `.husky/pre-push` body rather than a wrapper; unifying the
+  husky installer on the adapter is tracked as a follow-up
+- `security-disclosure-gate` routes public security-keyword issue creation to private disclosure
 - `settings-protection` prevents agents from modifying their own safety rails
 - `dangerous-bash-interceptor` blocks categories of destructive shell commands
+- `push-review-gate` and the shared-core adapter (`push-review-gate-git.sh` sourcing `hooks/_lib/push-review-core.sh`) anchor trust on the hook's own on-disk location via `BASH_SOURCE` rather than caller-controlled env vars; see `THREAT_MODEL.md §5.18`. The shipped inline `.husky/pre-push` body uses `git rev-parse --show-toplevel` to locate `REA_ROOT` — extending the script-anchor idiom to the inline path is tracked follow-up hardening
 
 Both layers operate independently — compromising one does not disable the other.
 
@@ -99,6 +116,6 @@ Both layers operate independently — compromising one does not disable the othe
 - Policy parsing is strict zod schema — unknown fields rejected, not ignored
 - Path traversal protection on profile loading (regex + path containment check)
 - CI publish pipeline includes gitleaks secret scanning, npm provenance attestation via OIDC, SBOM generation, and payload validation
-- All shell hooks use `set -euo pipefail` with explicit variable quoting
+- All shell hooks set fail-fast flags with explicit variable quoting (`set -euo pipefail`, or `set -uo pipefail` for hooks that consume stdin JSON where a single `jq`-path miss must not abort before the conditional branches run)
 - Commits are signed and DCO-signed-off; `main` branch protection requires passing checks and review
 - npm publish uses OIDC provenance; no long-lived NPM tokens in CI

package/THREAT_MODEL.md

@@ -1,6 +1,6 @@
 # Threat Model — REA Gateway and Hook Layer
 
-Version: 0.2.x | Last updated: 2026-04-18
+Version: 0.9.x | Last updated: 2026-04-21
 
 ---
 
@@ -82,12 +82,12 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 
 **Mitigations:**
 
-- `injection` middleware scans tool arguments and results for instruction-like patterns.
+- `injection` middleware scans downstream tool **results** (`ctx.result`) post-execute for instruction-like patterns — see §5.21 for the three-tier classifier.
 - All injection regexes run under a per-call worker-thread timeout (`wrapRegex`, default 100ms) with a hard kill on timeout — catastrophic backtracking cannot hang the gateway. See §5.12.
 - Gateway middleware chain re-derives tier from tool_name independently on every invocation — a poisoned description cannot change the tier classification.
 - `.rea/policy.yaml` is re-read on every invocation; a "set autonomy to L3" instruction cannot be persisted by any middleware path.
 
-**Residual risk:** Semantic injection in natural-language descriptions is not fully mitigated. No regex can reliably detect all instruction-injection patterns. A three-valued escalation (`clean` / `suspicious` / `likely-injection`) is planned for 0.3.0 so write/destructive tiers require human-loop approval on suspicion rather than accepting a binary pass/fail.
+**Residual risk:** Semantic injection in natural-language descriptions is not fully mitigated. No regex can reliably detect all instruction-injection patterns. The shipped three-valued classifier (`clean` / `suspicious` / `likely_injection`; see §5.21) narrows the footgun by making "write under suspicion" a conscious policy decision but does not eliminate it.
 
 ---
 
@@ -203,7 +203,7 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 
 ### 5.8 Codex Plugin Abuse and Codex-Review Gate Weakening
 
-**Threat:** A poisoned Codex adversarial-review response contains prompt-injection content designed to make Claude take an unsafe action "per the reviewer's recommendation." A malicious actor uses `/codex-review` to launder an attack past the policy layer. Separately: a rogue agent or operator disables the Codex-review requirement to push protected-path changes without adversarial review.
+**Threat:** A poisoned Codex adversarial-review response contains prompt-injection content designed to make Claude take an unsafe action "per the reviewer's recommendation." A malicious actor uses `/codex-review` to launder an attack past the policy layer. Separately: a rogue agent or operator disables the Codex-review requirement to push protected-path changes without adversarial review, or uses the escape hatch to bypass far more than the Codex requirement.
 
 **Mitigations:**
 
@@ -212,12 +212,27 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 - Codex never receives `.rea/policy.yaml` content in its prompt; Codex reviews diffs, not policy.
 - The `codex-adversarial` agent cannot by itself modify policy, trigger writes, or bypass blocked paths — it is a review tool, not an actor.
 - **Pluggable reviewer** (0.2.0, G11.2): when Codex is unreachable, `ClaudeSelfReviewer` is the fallback. Claude-on-Claude review is explicitly tagged `degraded: true` in the audit record so self-review is visible and countable.
-- **Audited escape hatch** (0.2.0, G11.1): `REA_SKIP_CODEX_REVIEW=<reason>` bypasses the protected-path Codex requirement but writes a `codex.review.skipped` audit record carrying the verbatim reason, the operator's git identity, the head_sha, and the files-changed count. Fail-closed on missing `dist/audit/append.js` or missing git identity — the gate never silently disables. Skip records use `tool_name: "codex.review.skipped"` so a skip cannot satisfy a future Codex-review requirement on the same HEAD.
-- **First-class no-Codex mode** (0.2.0, G11.4): `policy.review.codex_required: false` skips the protected-path Codex requirement entirely. In that mode `REA_SKIP_CODEX_REVIEW` becomes a no-op (skipping a review that isn't required has no meaning), and no skip record is emitted. Both `.claude/hooks/push-review-gate.sh` (Claude Code path) and `.husky/pre-push` (terminal path) honor this knob.
+- **First-class no-Codex mode** (0.2.0, G11.4): `policy.review.codex_required: false` skips the protected-path Codex requirement entirely. In that mode `REA_SKIP_CODEX_REVIEW` becomes a no-op (skipping a review that isn't required has no meaning), and no skip record is emitted. Both the Claude-Code adapter (`.claude/hooks/push-review-gate.sh`) and the native git adapter (`.claude/hooks/push-review-gate-git.sh`, sharing `hooks/_lib/push-review-core.sh`) honor this knob.
 - **Availability probe** (0.2.0, G11.3): `rea serve` runs an initial `codex --version` probe on startup when `codex_required` ≠ false. A failed probe emits a single stderr warn — startup never fail-closes on a Codex miss.
 - **Reviewer telemetry** (0.2.0, G11.5): `ClaudeSelfReviewer.review()` writes a row to `.rea/metrics.jsonl` with invocation counts, estimated tokens (chars/4), latency, and a `rate_limited` signal parsed from stderr. Payloads are NEVER stored; a unit test asserts that marker strings in inputs never appear in the metrics file.
 
-**Residual risk:** Semantic injection in Codex responses (e.g., reviewer recommends a specific code change that is itself malicious) cannot be fully detected. Mitigation is defense-in-depth: the middleware still runs on any subsequent write that Claude attempts based on the review. A `rea doctor` abuse signal on escape-hatch frequency (≥3 invocations per rolling 7 days) is proposed for 0.3.0.
+**`REA_SKIP_CODEX_REVIEW` — Codex-only waiver (0.8.0, #85).** Through 0.7.0 this env var short-circuited the **entire** push-review gate after writing its skip audit record — equivalent in scope to `REA_SKIP_PUSH_REVIEW`. Operators reached for it to silence a transient Codex unavailability and accidentally bypassed HALT, the cross-repo guard, ref-resolution, and the push-review cache. 0.8.0 narrows it to what the name implies: the waiver satisfies **only** the protected-path Codex-audit requirement. Every other gate still runs:
+
+- **HALT** (`.rea/HALT`) — still blocks.
+- **Cross-repo guard** — still blocks.
+- **Ref-resolution failures** (missing remote object, unresolvable source ref) — still block, but the skip audit record is written first so the operator's commitment to waive is durable.
+- **Push-review cache** — a miss still falls through to the general "Review required" block.
+
+The skip audit record is still named `codex.review.skipped` and still fails the `codex.review` jq predicate. Banner text changed from `CODEX REVIEW SKIPPED` to `CODEX REVIEW WAIVER active` to reflect the narrower scope. Fail-closed contract preserved: missing `dist/audit/append.js` (rea unbuilt) or missing git identity → exit 2.
+
+**Cache gate hardening (0.8.0, same release).** The review cache is a separate, later check in the core (`hooks/_lib/push-review-core.sh` §8) — it governs the general push-review gate for non-protected-path pushes, not the protected-path Codex audit itself. Two composition bugs in that cache layer became load-bearing once the Codex waiver no longer papered over cache behavior, so they were fixed in the same release:
+
+- The cache-hit predicate now requires `.hit == true and .result == "pass"`. Previously `.hit == true` alone was sufficient, which meant a cached `fail` verdict would silently satisfy the gate. The permissive predicate was a real exposure once the Codex-only waiver stopped short-circuiting subsequent checks.
+- The cache key is derived from the PUSHED source ref (from pre-push stdin), not from the checkout branch. `git push origin hotfix:main` from a `feature` checkout now correctly looks up the `hotfix` cache entry.
+
+**`REA_SKIP_PUSH_REVIEW` — whole-gate bypass (0.5.0).** The recovery path for consumers deadlocked on a broken rea install. Writes `tool_name: "push.review.skipped"` with an `os_identity` sub-object (uid, whoami, hostname, pid, ppid, ppid_cmd, tty, ci) so auditors can distinguish a real operator from a forged git-config actor. Refuses with exit 2 on CI runners (`CI` env var set) unless `review.allow_skip_in_ci: true` is opted in via policy — closes the ambient-env-var bypass surface on shared build agents. HALT check runs before the skip branch: `.rea/HALT` cannot be bypassed by either hatch.
+
+**Residual risk:** Semantic injection in Codex responses (e.g., reviewer recommends a specific code change that is itself malicious) cannot be fully detected. Mitigation is defense-in-depth: the middleware still runs on any subsequent write that Claude attempts based on the review. A `rea doctor` abuse signal on escape-hatch frequency (≥3 invocations per rolling 7 days) remains tracked.
 
 ---
 
@@ -300,22 +315,185 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 
 ---
 
+### 5.14 Supervisor Trust Boundary (0.9.0, BUG-002..003)
+
+**Threat:** A downstream MCP child process crashes unexpectedly — OS OOM-kill, unhandled exception in the child, stdio pipe error outside a caller-initiated close — and the gateway keeps a stale `Client` handle around. Every subsequent `callTool` hits the zombie, receives `Not connected`, the circuit breaker flaps open → half-open → open against the same dead handle, and the child is never respawned. From the operator's perspective the gateway is "up" but nothing works.
+
+**Mitigations:**
+
+- `DownstreamConnection` wires the MCP SDK `StdioClientTransport`'s `onclose` and `onerror` callbacks on a **per-transport** basis (never global) and treats an unexpected close as "child is dead": the client and transport fields are nulled before the next call. The next `callTool` takes the `connect()` branch and actually respawns the child.
+- Intentional `close()` sets a local flag before calling into the SDK, so the same `onclose` callback does not double-count a graceful shutdown as an unexpected death.
+- "Not connected" errors from the SDK (the in-flight fallback path) are promoted to the respawn path with the same eager invalidation — a stale client is invalidated before the one-shot reconnect fires, so we spawn fresh rather than retrying with the same dead handle.
+- A 30-second flapping guard (`RECONNECT_FLAP_WINDOW_MS`) refuses a second reconnect that lands too quickly after the previous successful one — the child is clearly unhealthy and the circuit breaker is a better place to handle it.
+- `DownstreamConnection.lastError` is bounded **at write** via `boundedDiagnosticString` on a true ES-private `#lastErrorMessage` setter (0.7.0, BUG-014). The invariant is structural: every write produces a bounded stored value regardless of assignment-site count. Non-string inputs raise `TypeError` instead of silently corrupting the field.
+- Error strings published to `serve.state.json` flow through the same `buildRegexRedactor` the gateway logger uses (policy `redact.patterns` + built-in `SECRET_PATTERNS`) via the `lastErrorRedactor` option on the live-state publisher — a credential that leaked into a downstream error message is scrubbed before it lands on disk or on an operator's terminal via `rea status`.
+
+**Residual risk:** A child that advertises tools but then returns malicious responses on every call is not a supervisor-layer concern — it is handled by the standard middleware chain (injection, redact, result-size-cap). A child that alternates between healthy and malicious responses more slowly than the circuit breaker can trip is a limitation of any breaker-based approach; detection depends on `.rea/metrics.jsonl` anomalies.
+
+Ref: `src/gateway/downstream.ts`, `src/gateway/downstream.test.ts`.
+
+---
+
+### 5.15 SESSION_BLOCKER Audit Semantics (0.9.0, BUG-004)
+
+**Threat:** A persistently failing downstream produces a log stream full of identical circuit-open records. Operators miss the signal because it looks like normal circuit-breaker churn, or alert-fatigue kicks in and they tune it out entirely.
+
+**Mitigations:**
+
+- `SessionBlockerTracker` subscribes to circuit-breaker `onStateChange` events and counts circuit-open transitions per `(session_id, server_name)`. It tracks **open-level** failures per session, not wire-hot call-level failures — every circuit-open transition counts as one, so a downstream that flaps `open→closed→open` three times in ten minutes crosses the threshold once.
+- On threshold crossing (default: 3), exactly **one** `SESSION_BLOCKER` event fires: a LOUD structured log record plus an audit append via `appendAuditRecord`. The counter keeps incrementing but subsequent opens do **not** re-fire.
+- Recovery (transition to `closed`) resets the counter and re-arms the emit flag — a later threshold crossing fires a fresh record.
+- A new session (new `rea serve` process / new `session_id`) drops every counter and starts fresh.
+- Audit append is best-effort; log-side emission happens first and unconditionally. A broken audit pipeline must never break state tracking.
+- `SESSION_BLOCKER` is an **audit event**, not a gateway exception. The gateway keeps serving traffic; the event is the forensic signal an operator can search for in `audit.jsonl`.
+
+**Residual risk:** A downstream that flaps fast enough to hit the threshold on every session but recovers quickly in between can still generate a record per session. This is the intended behavior — the operator should see it every session and fix the downstream.
+
+Ref: `src/gateway/session-blocker.ts`, `src/gateway/session-blocker.test.ts`.
+
+---
+
+### 5.16 `.rea/serve.state.json` Lock / Ownership Handoff (0.9.0, BUG-005)
+
+**Threat:** A crashed `rea serve` leaves `serve.state.json` and `serve.pid` behind. A new `rea serve` instance either (a) refuses to start because ownership-by-session-id locks the file forever, or (b) silently takes over without verifying the predecessor is dead — letting two live gateways race on writes.
+
+**Mitigations:**
+
+- Writes use atomic temp-file + rename (`writeFileAtomic`) with a `.<filename>.<randomUUID>.tmp` suffix, so a reader never sees a torn intermediate.
+- The snapshot carries both `session_id` (boot-time ownership key) and `owner_pid` (0.9.0 pass-4). A newly-started `rea serve` whose predecessor crashed can detect the abandoned file — `kill(owner_pid, 0)` returns ESRCH — and take over ownership rather than stalling.
+- The session-id check runs first; `owner_pid` is a secondary lock-guarded field used only to distinguish "abandoned" from "actively owned by a different session." The combination preserves the safety invariant (no silent takeover of a live gateway's file) while avoiding the pass-2 strict-one-directional lock.
+- Consumers (`rea status`, `rea check`) read the file **only**. They never write and never clean up stale state — the serve process is the only writer. Pre-0.9.0 snapshots without `downstreams` or `owner_pid` degrade to `null` fields with a hint to upgrade.
+- Writes are debounced through a 250 ms trailing timer so a flap storm (open → half-open → open → half-open in rapid succession) doesn't spam the filesystem.
+
+**Residual risk:** A pathological PID reuse (the OS recycled the crashed gateway's PID onto an unrelated process before the new gateway boots) would cause the `kill(pid, 0)` probe to report "alive" spuriously. The session-id check catches this — a live process with a different session_id is distinguishable from an abandoned file — but the first-boot window where session_id is also unchanged is a theoretical corner. Operators who suspect this should `rm .rea/serve.pid .rea/serve.state.json` and restart.
+
+Ref: `src/gateway/live-state.ts`, `src/gateway/server.ts`.
+
+---
+
+### 5.17 Health Payload Sanitization (0.6.2, BUG-011)
+
+**Threat:** The `__rea__health` meta-tool short-circuits the middleware chain (intentionally — so it stays callable under HALT) and previously serialized `halt_reason` plus every `downstreams[].last_error` verbatim. Error strings from upstream MCPs can contain secrets (API keys, tokens) or prompt-injection payloads, neither of which the `redact` or `injection` middleware would see because the short-circuit response skips the chain entirely. Net effect: a redact + injection-sanitizer bypass, callable precisely when HALT should be holding the line.
+
+**Mitigations:**
+
+- `sanitizeHealthSnapshot()` runs on the short-circuit response before it reaches the MCP wire. Default behavior: `halt_reason = null` and every `downstreams[].last_error = null`. The operator-visible wire response carries no downstream-controlled diagnostic strings.
+- Full diagnostic detail still flows into the meta-tool audit record. The record written for `__rea__health` carries the unsanitized `metadata.halt_reason` and `metadata.downstream_errors[]` (sourced pre-sanitize from `pool.healthSnapshot()` inside `server.ts`) alongside the existing counts. Audit is on local disk, hash-chained, append-only, and not LLM-reachable — the correct sink for trusted-operator diagnostic text.
+- Operators who need error strings on the MCP wire can opt in via `.rea/policy.yaml`:
+
+  ```yaml
+  gateway:
+    health:
+      expose_diagnostics: true
+  ```
+
+  Opt-in mode still runs the full sanitizer pass: `redactSecrets` replaces known secret patterns with `[REDACTED:*]`, `classifyInjection` replaces any non-`clean` diagnostic string (verdicts `suspicious` or `likely_injection`) with the exported `INJECTION_REDACTED_PLACEHOLDER` token (`<redacted: suspected injection>`), and the redact-timeout sentinel `[REDACTED: pattern timeout]` is filtered from the wire so a caller cannot distinguish "pattern timed out" from "pattern matched."
+
+- Diagnostic strings are bounded at 4096 UTF-16 code units before any scanning runs, via a UTF-8-safe truncate that drops trailing lone surrogates — an adversarial downstream cannot DoS the tool by throwing oversize errors.
+- `meta.health.audit_failed` log level was elevated from `warn` to `error` and `summary.audit_fail_count` is exposed in the snapshot so operators can detect an audit-sink failure without parsing stderr.
+
+**Residual risk:** `expose_diagnostics: true` is still operator-controlled text on an LLM-reachable surface. The sanitizer is best-effort defense-in-depth — a secret pattern not in the catalog, or an injection pattern that `classifyInjection` rates `clean`, will pass through unchanged.
+
+Ref: `src/gateway/meta/health.ts`, `src/gateway/meta/health-sanitize.test.ts`.
+
+---
+
+### 5.18 Script-Anchor Hook Trust Boundary (0.6.2, BUG-012)
+
+**Threat:** The `push-review-gate.sh` and `commit-review-gate.sh` hooks need to know the rea repository root for (a) the cross-repo short-circuit when invoked from a consumer repository, and (b) HALT / policy enforcement against the correct policy file. Prior to 0.6.2, `REA_ROOT=${CLAUDE_PROJECT_DIR:-$(pwd)}`. `CLAUDE_PROJECT_DIR` is caller-controlled — any process invoking the hook can set it to a foreign path, which the guard would treat as rea. Result: HALT silently bypassed, cross-repo short-circuit fires on the wrong comparison, policy read from a directory the caller chose.
+
+**Mitigations:**
+
+- Hooks derive `REA_ROOT` from their own on-disk location using `BASH_SOURCE[0]` + `pwd -P`, then walk up to 4 parent directories looking for `.rea/policy.yaml` as the authoritative install marker. Install topology is fixed (`<root>/.claude/hooks/<name>.sh`), so the anchor is forge-resistant — a caller cannot relocate the hook without filesystem write access to the rea install, which is already protected by `settings-protection.sh` and `blocked-paths` enforcement.
+- `CLAUDE_PROJECT_DIR` is retained only as an advisory signal. When set and the realpath differs from the script-derived `REA_ROOT`, the hook emits a stderr advisory and continues using the script-derived value. It is never compared for short-circuit, never used to select the policy file, and never used to locate HALT.
+- The cross-repo guard (0.6.1) compares `git rev-parse --git-common-dir` on both sides (not path prefixes). Mixed state (one side git, one non-git) fails **closed** — the gate runs — rather than falling through to path-prefix. Only the both-non-git case uses path-prefix, matching the documented 0.5.1 non-git escape hatch.
+- The 0.7.0 BUG-008 cleanup extracted the shared logic into `hooks/_lib/push-review-core.sh` so both the Claude-Code PreToolUse adapter (`push-review-gate.sh`) and the native git adapter (`push-review-gate-git.sh`) share a single anchor-walk implementation — a fix lands in one place.
+
+**Residual risk:** If a local attacker has write access to the rea install directory they can move or replace the hook file, which would change `SCRIPT_DIR` and therefore `REA_ROOT`. This is equivalent to tampering with any other hook contents (`settings-protection.sh` already addresses it) and lies outside the `CLAUDE_PROJECT_DIR` threat class.
+
+Ref: `hooks/_lib/push-review-core.sh`, `__tests__/hooks/push-review-gate-cross-repo.test.ts` "BUG-012: foreign CLAUDE_PROJECT_DIR does NOT bypass HALT".
+
+---
+
+### 5.19 Tarball-Smoke Security-Claim Gate (0.6.2, BUG-013)
+
+**Threat:** A changeset file claims a security fix (`[security]` marker), the release workflow merges and publishes, but the shipping `dist/` is byte-identical to the previous release — the claimed fix never made it into the compiled output. The 0.6.0 → 0.6.1 regression is the canonical example: `src/` changed, `dist/` did not. Without a pipeline gate that rebuilds `dist/` from the shipping commit and verifies the published tarball contents, no future security changeset can be trusted.
+
+**Mitigations (shipped across 0.6.2 + 0.7.0):**
+
+- `scripts/tarball-smoke.sh` (0.6.2) enforces a **content-based security-claim gate**. When any `.changeset/*.md` contains the `[security]` marker, the smoke requires at least one `src/**/*(sanitize|security)*.test.ts` file exists **and** every named-import symbol it pulls from a relative path is present in the compiled `dist/` tree. The gate fails loudly (exit 2) if the marker is present but no testable security symbols are extractable.
+- `.github/workflows/release.yml` (0.7.0) rebuilds `dist/` from the shipping HEAD immediately before `changesets/action`, records the SHA-256 tree hash to `$RUNNER_TEMP/rea-dist-hash` (CI scratch space — cannot be accidentally committed by `changesets/action`'s `git add .`), and post-publish re-packs the just-published tarball from npm and fails the release if the published `dist/` tree hash doesn't match.
+- `scripts/dist-regression-gate.sh` (0.7.0) + the `dist-regression` CI job run on every PR and every push-to-main. If `src/` has changed vs the last published tag but the rebuilt `dist/` tree hashes identically to the published tarball, CI fails — the "src changed, dist didn't" regression class is caught **before** the release branch, not only at publish time.
+- Husky e2e regression guard (`__tests__/hooks/husky-e2e.test.ts`, 0.7.0) invokes a REAL `git push` against a bare remote via `core.hooksPath=.husky` with the SHIPPED `.husky/pre-push` in place (the standalone inline body emitted by `src/cli/install/pre-push.ts`). The ten-test matrix covers: nine cases that exercise the inline body's HALT, protected-path, Codex-waiver, `review.codex_required: false`, and bootstrap-push branches, plus one case that swaps in a wrapper around `hooks/push-review-gate-git.sh` as a shape-guard for the future installer path. The kind of BUG-008 silent-exit-0 regression that slipped past synthesized-stdin unit tests through 0.4.0 would now fail loudly.
+
+**Residual risk:** A security claim whose fix is purely a deletion (no new symbols, no new test file) cannot be validated by the symbol-extraction gate. The `dist-regression` job catches this as a byte-identity failure, but the gate has no positive evidence of the fix's presence. Manual maintainer review on `[security]`-labeled PRs remains the compensating control.
+
+Ref: `scripts/tarball-smoke.sh`, `scripts/dist-regression-gate.sh`, `.github/workflows/release.yml`.
+
+---
+
+### 5.20 Registry TOFU Pinning (0.3.0, G7)
+
+**Threat:** An attacker who lands a malicious template via `rea init`, or who patches `.rea/registry.yaml` out-of-band (compromised dependency postinstall, CI-bot misconfig, editor plugin writing through stale buffers), can silently swap a downstream server's `command`, `args`, or `env` keys. The gateway would spawn the new child at next startup and proxy it without challenge.
+
+**Mitigations:**
+
+- On first successful connect, the gateway records a SHA-256 fingerprint of each downstream's **canonicalized registry config path** — `name`, `command`, `args`, the sorted KEY SET of `env` (values excluded so secret rotation doesn't trip drift), `env_passthrough`, and `tier_overrides` — to `.rea/fingerprints.json`. Trust-On-First-Use (TOFU) by config-path hash, not by tool-surface or binary hash.
+- Subsequent connects re-compute the fingerprint and compare. A mismatch is a **hard fail**: the downstream is marked unhealthy, a structured log + audit record names the drift, and the gateway refuses to route calls to it. The operator must inspect the registry delta and either clear the fingerprint entry (re-pin) or acknowledge the drift via one-shot `REA_ACCEPT_DRIFT=<name>`.
+- `fingerprints.json` is gitignored by default via the `.rea/` managed block so a local re-pin does not pollute history.
+- Scope is explicitly **path-only, not binary, and not tool-surface**. Binary hashing would turn TOFU into a slow-boot tax and would trip false-positive drift on every legitimate MCP server upgrade. Tool-surface hashing was considered and deferred — see residual risk below.
+
+**Residual risk:** Two classes remain uncovered by G7:
+
+1. **Catalog drift from a legitimately-configured downstream.** A downstream whose registry config is unchanged but whose `tools/list` response changes between connects (new tool, renamed tool, modified description, modified input schema) is **not** detected by the config-path fingerprint. An attacker who compromises the downstream binary at `config.command` without changing the registry entry, or a legitimate upstream MCP server that silently expands its tool catalog in a patch release, both fall through this gate. See §6 "Catalog drift by downstream not detected on reconnect" — this is an active, tracked residual risk, not a mitigated one. The redact + injection middleware running on every proxied result is the compensating control, not a substitute.
+2. **Host compromise with config-matching binary substitution.** An attacker who swaps the on-disk binary at `config.command` but leaves `.rea/registry.yaml` untouched is outside the G7 threat model — that is a host-integrity / supply-chain class, not a registry-tampering class.
+
+Ref: `src/registry/fingerprint.ts` (`canonicalize()`, `fingerprintServer()`), `src/gateway/downstream-pool.ts` fingerprint-probe path.
+
+---
+
+### 5.21 G9 Three-Tier Injection Classifier (0.3.0)
+
+**Threat:** A binary pass/fail injection detector is either too permissive (known instruction patterns slip through) or too strict (every tool description flags and the gateway becomes unusable). Either failure mode eventually trains operators to ignore the signal.
+
+**Mitigations:**
+
+- `classifyInjection()` returns one of three verdicts: `clean`, `suspicious`, or `likely_injection`. The verdict is derived from weighted matches against the shipped pattern catalog, tuned so legitimate tool descriptions rate `clean` by default.
+- Escalation rules (first match wins, per `src/gateway/middleware/injection.ts:450-527`):
+  1. No literal and no base64-decoded match → `clean`.
+  2. Any base64-decoded match, regardless of tier → `likely_injection`.
+  3. ≥2 distinct literal matches, regardless of tier → `likely_injection`.
+  4. Any match at read-tier (or unknown tier — fail closed) → `likely_injection`.
+  5. Exactly one literal match at write/destructive tier → `suspicious`.
+- `likely_injection` → always deny. No opt-out at policy level. (Note: because of rule 4, ANY injection match at read-tier is denied — the "warn but permit" path only exists for single-literal matches at write/destructive tier.)
+- `suspicious` on a write/destructive tier → **policy-controlled**. `injection.suspicious_blocks_writes: true` (shipped in `bst-internal` and `bst-internal-no-codex` profiles — internal posture) denies. The schema default is `false` — external profiles (`open-source`, `client-engagement`, `minimal`, `lit-wc`) inherit the looser behavior so upgrading 0.2.x consumers are not silently tightened.
+- **Regex timeout / oversize-result `error` verdict is mode-dependent** (`src/gateway/middleware/injection.ts:654-728`). Under `injection_detection: block` (all profiles except `warn`), any scan timeout or oversize input denies unconditionally — the partial scan cannot prove the unscanned suffix is safe, so block mode fails closed. Under `injection_detection: warn`, a timeout on an otherwise-clean partial scan is recorded as `metadata.injection.verdict = 'error'` and let through — this matches the 0.2.x `warn` semantics (fail-open by design) and operators opting into `warn` must accept this trade-off. Operators who want fail-closed everywhere should stay on `block`.
+- The opt-in strict flag is honored at both the middleware layer (write/destructive deny) and the sanitizer layer (health payload replacement — the `<redacted: suspected injection>` placeholder collapses **any** non-`clean` diagnostic, so `suspicious` and `likely_injection` strings are both replaced on the `__rea__health` wire under `expose_diagnostics: true`).
+- Every non-`clean` invocation records a nested `ctx.metadata.injection = { verdict, matched_patterns, base64_decoded }` object on the audit row (`src/gateway/middleware/injection.ts:733-740`). Consumers must read the nested shape — there is no top-level `injection_verdict` / `injection_match_count` field. The matched-patterns array contains the distinct phrase names only; the original input text is never exported.
+
+**Residual risk:** Semantic injection in natural-language descriptions — a well-phrased instruction that no pattern catalog will catch — is not mitigated by pattern matching. This is the general limitation acknowledged in §5.1; the three-tier classifier narrows the footgun (by making "write under suspicion" a conscious policy decision) but does not eliminate it.
+
+Ref: `src/gateway/middleware/injection.ts`, `src/gateway/middleware/injection.test.ts`.
+
+---
+
 ## 6. Residual Risks and Open Issues
 
-| Risk                                                          | Severity | Tracking                       |
+| Risk                                                          | Severity | Status / Tracking              |
 | ------------------------------------------------------------- | -------- | ------------------------------ |
-| Semantic prompt injection via tool descriptions               | High     | 0.3.0 G9 (tier escalation)     |
+| Semantic prompt injection via tool descriptions               | High     | Partially mitigated — G9 three-tier classifier (§5.21) narrows the footgun via pattern matching, but semantic/natural-language injection that no catalog entry will catch is still unmitigated by design |
 | Semantic injection via Codex adversarial-review responses     | High     | No issue filed (defense in depth via middleware) |
-| Double-URL-encoding bypass for blocked paths                  | Medium   | Planned fix                    |
-| No real-time alert on audit hash chain break                  | Medium   | 0.3.0 G1 + G5                  |
-| Concurrent audit writers can race at fsync                    | Medium   | 0.3.0 G1 (proper-lockfile)     |
+| Concurrent audit writers can race at fsync                    | Medium   | Mitigated — proper-lockfile shipped 0.3.0 (G1) |
+| Catalog drift by downstream not detected on reconnect         | Medium   | Active — G7 TOFU (§5.20) pins registry CONFIG (name/command/args/env keys), not the `tools/list` response. A downstream that silently expands or alters its tool catalog without a registry edit is not caught by the fingerprint; compensating control is the per-result redact + injection middleware. Tool-surface TOFU is a planned follow-up. |
+| Post-publish tarball smoke not in CI                          | Medium   | Mitigated — tarball-smoke shipped 0.3.0, security-claim gate 0.6.2 (§5.19) |
+| No real-time alert on audit hash chain break                  | Medium   | Mitigated — audit-rotation + verify-on-append shipped 0.3.0 (G1 + G5) |
+| OIDC trusted publisher not yet migrated (`NODE_AUTH_TOKEN` still in use) | Medium | Deferred past 0.5.0 per MIGRATION-0.5.0.md; current path is `--provenance` with `NODE_AUTH_TOKEN` |
+| Double-URL-encoding bypass for blocked paths                  | Medium   | Planned fix (iterative decode to fixed-point) |
 | SBOM not automated in publish pipeline                        | Medium   | Planned                        |
 | Secret pattern gaps (custom token formats, encoding variants) | Medium   | No issue filed                 |
-| Post-publish tarball smoke not in CI                          | Medium   | 0.3.0 CI hardening             |
-| Escape-hatch abuse signal not surfaced in `rea doctor`        | Low      | 0.3.0 (threshold: ≥3 / 7d)     |
-| Catalog drift by downstream not detected on reconnect         | Medium   | 0.3.0 G7 (fingerprint + drift) |
-| OIDC trusted publisher not yet migrated (`NODE_AUTH_TOKEN` still in use) | Medium | 0.3.0 G8                 |
+| Escape-hatch abuse signal not surfaced in `rea doctor`        | Low      | Tracked (threshold: ≥3 / 7d)   |
 | Local user can escalate policy.yaml outside gateway           | Low      | By design (trusted actor)      |
+| Registry pin mismatch → hard fail (no rollback) on TOFU       | Low      | By design — operator clears `.rea/fingerprints.json` to re-pin |
 
 ---
 
@@ -323,8 +501,8 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 
 REA operates two independent layers. Bypassing one does not disable the other.
 
-**Hook layer** (development-time): 13 Claude Code hooks intercept tool calls before execution at the Claude Code level. Hooks enforce: secret scanning, dangerous command interception, blocked path enforcement, settings protection, attribution advisory, dependency audit, commit/push review gates, PR issue linking, architecture review, env file protection, changeset security gates, and security-disclosure gates.
+**Hook layer** (development-time): 14 shell scripts ship. 12 are wired into Claude Code's `PreToolUse` / `PostToolUse` events via the default `.claude/settings.json`. Two are shipped but NOT registered by default: `commit-review-gate.sh` is a `PreToolUse: Bash` hook that matches `git commit` for operators who opt into commit-time review by adding a rule, and `push-review-gate-git.sh` is a native-git adapter that sources `hooks/_lib/push-review-core.sh` (the same shared core the Claude-Code `push-review-gate.sh` sources), shipped for consumers who wire a wrapper-based `.husky/pre-push` that execs it directly. `rea init` currently emits a standalone inline `.husky/pre-push` body (`src/cli/install/pre-push.ts`) rather than a wrapper; unifying the husky installer on the shared-core adapter is tracked as follow-up hardening. Hooks enforce: secret scanning, dangerous command interception, blocked path enforcement, settings protection, attribution advisory, dependency audit, push review gate (Claude-Code-JSON adapter registered; native `.husky/pre-push` adapter opt-in), PR issue linking, architecture review, env file protection, changeset security, and security-disclosure routing. The review-gate hooks (`push-review-gate.sh`, `push-review-gate-git.sh`, `commit-review-gate.sh`) anchor their trust decision on their own on-disk script location (BUG-012, §5.18), not on caller-controlled env vars. The remaining hooks still derive `REA_ROOT` from `${CLAUDE_PROJECT_DIR:-$(pwd)}`; extending the script-anchor idiom across the full hook set is a tracked hardening follow-up.
 
-**Gateway layer** (runtime, `rea serve`): A middleware chain processes every proxied MCP tool call. Middleware enforces: audit, kill switch, policy/autonomy level, tier classification, blocked paths, rate limit, circuit breaker, prompt injection detection, secret redaction (pre and post), and result size cap.
+**Gateway layer** (runtime, `rea serve`): A middleware chain processes every proxied MCP tool call. Middleware enforces: audit, kill switch, policy/autonomy level, tier classification, blocked paths, rate limit, circuit breaker, prompt-injection classification (§5.21), secret redaction (pre and post), and result size cap. The gateway also supervises downstream child processes (§5.14), emits a `SESSION_BLOCKER` audit event on persistent failure (§5.15), and publishes a live per-downstream state snapshot to `.rea/serve.state.json` (§5.16) that `rea status` reads read-only. The `__rea__health` meta-tool short-circuits the chain for callability under HALT and runs a dedicated sanitizer on its response (§5.17).
 
 Both layers fail closed: on read failure, parse error, unknown errno on HALT, regex timeout, or any unexpected condition, the default action is deny (or for redaction specifically: replace with a sentinel — the content never escapes unscanned).

package/dist/cli/status.d.ts

@@ -6,7 +6,7 @@
  *
  * `rea status` is the LIVE view: is a gateway running for this cwd? What is
  * its session id? What does the audit chain look like right now? Is HALT
- * active?
+ * active? Which downstreams are connected / healthy / tripped?
  *
  * Detection strategy for "is serve running":
  *   1. Read `.rea/serve.pid`.
@@ -14,6 +14,15 @@
  *   3. If kill throws ESRCH or EPERM, the pid is stale — treat as not-running
  *      and surface that nuance in the output.
  *
+ * 0.9.0 — per-downstream live block. `readServeState` parses the
+ * `downstreams: [...]` array from `.rea/serve.state.json` (written by the
+ * live-state publisher on every circuit transition + supervisor event).
+ * Each entry carries `name`, `connected`, `healthy`, `circuit_state`,
+ * `retry_at`, `last_error` (redacted by the publisher), `tools_count`,
+ * `open_transitions`, and `session_blocker_emitted`. State files written
+ * by a pre-0.9.0 gateway degrade gracefully: `downstreams` surfaces as
+ * `null` with a hint to upgrade.
+ *
  * Output modes:
  *   - Default: human-pretty, matching the spacing used by `rea check`.
  *   - `--json`: canonical JSON object, composable with jq and future tooling.
@@ -23,6 +32,11 @@
  * `rea audit verify` is the authoritative check and is expensive on large
  * chains; here we just report line count, last timestamp, and a cheap "last
  * record's stored hash is non-empty" heuristic as an integrity smoke signal.
+ *
+ * Every disk-sourced string field flows through `sanitizeForTerminal` on the
+ * pretty-print path — JSON mode relies on `JSON.stringify` to escape control
+ * chars safely — so a malicious `halt_reason` or `last_error` cannot inject
+ * ANSI/OSC escapes into the operator's terminal.
  */
 /**
  * Strip every ASCII control code (C0 plus DEL) from a string. Defense

package/dist/cli/status.js

@@ -6,7 +6,7 @@
  *
  * `rea status` is the LIVE view: is a gateway running for this cwd? What is
  * its session id? What does the audit chain look like right now? Is HALT
- * active?
+ * active? Which downstreams are connected / healthy / tripped?
  *
  * Detection strategy for "is serve running":
  *   1. Read `.rea/serve.pid`.
@@ -14,6 +14,15 @@
  *   3. If kill throws ESRCH or EPERM, the pid is stale — treat as not-running
  *      and surface that nuance in the output.
  *
+ * 0.9.0 — per-downstream live block. `readServeState` parses the
+ * `downstreams: [...]` array from `.rea/serve.state.json` (written by the
+ * live-state publisher on every circuit transition + supervisor event).
+ * Each entry carries `name`, `connected`, `healthy`, `circuit_state`,
+ * `retry_at`, `last_error` (redacted by the publisher), `tools_count`,
+ * `open_transitions`, and `session_blocker_emitted`. State files written
+ * by a pre-0.9.0 gateway degrade gracefully: `downstreams` surfaces as
+ * `null` with a hint to upgrade.
+ *
  * Output modes:
  *   - Default: human-pretty, matching the spacing used by `rea check`.
  *   - `--json`: canonical JSON object, composable with jq and future tooling.
@@ -23,6 +32,11 @@
  * `rea audit verify` is the authoritative check and is expensive on large
  * chains; here we just report line count, last timestamp, and a cheap "last
  * record's stored hash is non-empty" heuristic as an integrity smoke signal.
+ *
+ * Every disk-sourced string field flows through `sanitizeForTerminal` on the
+ * pretty-print path — JSON mode relies on `JSON.stringify` to escape control
+ * chars safely — so a malicious `halt_reason` or `last_error` cannot inject
+ * ANSI/OSC escapes into the operator's terminal.
  */
 import fs from 'node:fs';
 import { loadPolicy } from '../policy/loader.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",