@bookedsolid/rea 0.2.1 → 0.3.0

package/THREAT_MODEL.md

@@ -1,6 +1,6 @@
 # Threat Model — REA Gateway and Hook Layer
 
-Version: 0.1.x | Last updated: 2026-04-18
+Version: 0.2.x | Last updated: 2026-04-18
 
 ---
 
@@ -19,11 +19,14 @@ This document describes the security threat model for REA (`@bookedsolid/rea`),
 | `.rea/policy.yaml`              | Autonomy level, max autonomy ceiling, blocked paths, attribution policy | Critical — controls all tool access   |
 | `.rea/audit.jsonl`              | Hash-chained audit log of every tool invocation                         | High — integrity evidence             |
 | `.rea/HALT`                     | Kill-switch file; presence blocks all tool calls                        | High — single point of emergency stop |
+| `.rea/install-manifest.json`    | SHA-256 baseline of shipped artifacts; drives `rea upgrade` drift reports | Medium — upgrade trust signal         |
 | Hook scripts (`hooks/*.sh`)     | Bash scripts that enforce security at tool invocation time              | High — bypass = loss of control plane |
 | Agent definitions (`agents/*`)  | Role definitions and behavioral constraints for specialist agents       | Medium                                |
 | Secrets in scope                | Credentials, API keys, tokens visible in tool arguments or results      | Critical                              |
 | Gateway process memory          | In-flight tool arguments, results, session state                        | Medium                                |
-| Codex invocation audit entries  | Record of `/codex review` and `/codex adversarial-review` outcomes      | Medium — pre-merge gate evidence      |
+| Codex invocation audit entries  | Record of `/codex-review` / `/codex:adversarial-review` outcomes        | Medium — pre-merge gate evidence      |
+| Escape-hatch audit entries      | `codex.review.skipped` records naming the bypass reason and operator    | Medium — governance-weakening signal  |
+| `.rea/metrics.jsonl`            | Reviewer telemetry (counts, latency, rate-limit signals; NO payloads)   | Low — operational observability       |
 
 ---
 
@@ -32,7 +35,7 @@ This document describes the security threat model for REA (`@bookedsolid/rea`),
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │  TRUSTED                                                        │
-│  Human operator (operates via Claude Code UI)                   │
+│  Human operator (operates via Claude Code UI or terminal)       │
 │  Claude Code / agent process                                    │
 │  Codex plugin (running under the same Claude Code process)      │
 │    │                                                            │
@@ -46,13 +49,14 @@ This document describes the security threat model for REA (`@bookedsolid/rea`),
 │    │                                                            │
 │    ▼                                                            │
 │  UNTRUSTED                                                      │
-│  Downstream MCP servers (tool descriptions, results)            │
+│  Downstream MCP servers (tool descriptions, results, binaries)  │
 │  External network (responses, fetched content)                  │
 │  Codex plugin RESPONSES (treated as untrusted input)            │
+│  Downstream subprocess environment (env vars we export to them) │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-Downstream MCP servers are treated as untrusted by default. Codex plugin *invocations* are trusted (same process), but Codex *responses* are treated as untrusted input and flow through the injection and redaction middleware just like any other tool result. The `.rea/` directory is always protected — no agent or MCP server can write to it through the gateway.
+Downstream MCP servers are treated as untrusted by default. Codex plugin *invocations* are trusted (same process), but Codex *responses* are treated as untrusted input and flow through the injection and redaction middleware just like any other tool result. The `.rea/` directory is always protected — no agent or MCP server can write to it through the gateway. Environment variables exported to downstream MCP subprocesses are a deliberate data flow outward from the trusted process to an untrusted child — see §5.11.
 
 ---
 
@@ -66,6 +70,7 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 | Poisoned Codex response      | A compromised or adversarial Codex review                 | Induce Claude to take unsafe action under "review" cover |
 | Local user escalation        | Direct filesystem access on the same machine              | Modify policy.yaml, tamper with audit log, remove hooks |
 | Supply chain attacker        | npm package substitution or dependency confusion          | Install malicious code that executes during build/run   |
+| Catalog-drift attacker       | Compromised downstream starts advertising new tools       | Extend attack surface silently after install review     |
 
 ---
 
@@ -78,10 +83,11 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 **Mitigations:**
 
 - `injection` middleware scans tool arguments and results for instruction-like patterns.
+- 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.
+**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.
 
 ---
 
@@ -91,10 +97,11 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 
 **Mitigations:**
 
-- `settings-protection.sh` blocks agent writes to `.claude/settings.json`.
+- `settings-protection.sh` blocks agent writes to `.claude/settings.json`, `.claude/hooks/*`, `.husky/*`, `.rea/policy.yaml`, and `.rea/HALT`.
 - The attribution-advisory hook and commit-msg hook both reject AI-attributed commits, so bypassing one does not disable the other.
 - `CLAUDE.md` template bundled with REA enforces a non-negotiable rule: `--no-verify` is never permitted.
 - The hook layer and gateway layer are independent — bypassing hooks does not disable the gateway middleware chain.
+- `dangerous-bash-interceptor.sh` explicitly pattern-matches `--no-verify`, `--no-gpg-sign`, `git reset --hard`, `rm -rf /`, and other destructive forms.
 
 **Residual risk:** A sufficiently privileged local process (same user) can modify git config directly without going through the hook. There is no runtime detection for this outside of audit log review.
 
@@ -110,6 +117,8 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 - `policy` middleware enforces the `max_autonomy_level` ceiling at runtime: autonomy_level is clamped even if policy.yaml is edited to exceed the maximum.
 - Policy file is re-read on every tool invocation, so a stricter policy takes effect immediately. A more permissive edit never bypasses the ceiling.
 - `promotion_requires_human_approval: true` is the default; CLI flag `--i-understand-the-risks` is required to disable it.
+- Policy schema is zod `.strict()` — unknown fields fail loudly at load, not silently ignored. Typos cannot silently defang a policy.
+- User-supplied redaction patterns are validated against `safe-regex` at policy load time; a flagged pattern rejects the entire policy load.
 
 **Residual risk:** If the local user (not an agent) directly edits policy.yaml and also raises `max_autonomy_level`, there is no enforcement beyond the honor system. This is by design — the human operator is a trusted actor.
 
@@ -125,8 +134,9 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 - Audit write failures are logged to stderr but do not crash the gateway — the tool call proceeds. This avoids DoS via audit failure while preserving the event.
 - `.rea/` is always blocked from agent writes, so agents cannot delete the audit file through the gateway.
 - `rea check audit` verifies the hash chain on demand; intended for pre-merge gates and compliance reviews.
+- Public `@bookedsolid/rea/audit` helper (`src/audit/append.ts`) is the only supported write path for consumers — it computes the hash and appends atomically with fsync so helix.* events and rea.* events share the chain.
 
-**Residual risk:** A local user with filesystem access can delete or truncate audit files outside the gateway. Hash-chain verification is a detection control, not a prevention control.
+**Residual risk:** A local user with filesystem access can delete or truncate audit files outside the gateway. Hash-chain verification is a detection control, not a prevention control. Concurrent-writer safety (proper-lockfile) and rotation semantics are planned for 0.3.0 (G1). Until then, concurrent `append()` calls from distinct processes can race at the fsync step.
 
 ---
 
@@ -137,9 +147,10 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 **Mitigations:**
 
 - `redact` middleware scans both tool arguments (pre-execution) and tool results (post-execution) using secret patterns covering AWS keys, GitHub tokens, generic API keys, bearer tokens, PEM private keys, Discord tokens, Anthropic/OpenAI keys, and base64-encoded variants.
-- Redaction patterns are validated at load time for catastrophic-backtracking safety.
+- Redaction patterns are validated at load time for catastrophic-backtracking safety (`safe-regex`), AND bounded at runtime via a per-call worker-thread timeout with hard-kill on budget exhaustion. See §5.12.
+- On regex timeout, the offending value is replaced with the sentinel `[REDACTED: pattern timeout]` — a scanner that cannot complete never lets the untouched value through. The byte length of the offending input is recorded in audit metadata; the input text is NEVER written to the log.
 - `secret-scanner.sh` hook scans file writes for credential patterns.
-- `env-file-protection.sh` blocks reads of `.env` files.
+- `env-file-protection.sh` blocks reads of `.env*` files.
 
 **Residual risk:** Secret patterns not in the catalog (custom token formats, hex-encoded credentials) will not be redacted. Encoding-based bypasses (double-URL-encoding, Unicode normalization) are partially mitigated but not comprehensively tested.
 
@@ -165,18 +176,20 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 
 **Mitigations:**
 
-- `kill-switch` middleware validates that HALT is a regular file (`isFile()`), not a directory.
-- Symlink detection via `lstat`; if HALT is a symlink, its resolved target must remain within `.rea/`.
-- Read size capped at 1024 bytes.
+- `kill-switch` middleware issues exactly **one syscall per invocation** against HALT: `fs.open(path, O_RDONLY)`. The previous `stat → lstat → open` sequence had a TOCTOU window between the check and the read; the new implementation has none (shipped in 0.2.0, G4).
+- **Semantic guarantee:** HALT is evaluated once per invocation at chain entry. A call that passes the check runs to completion; a call that fails it is denied. Creating `.rea/HALT` mid-flight does **not** cancel in-flight invocations — it blocks *subsequent* invocations only. This matches standard kill-switch semantics (SIGTERM after acceptance: the process continues).
+- **Fail-closed on unknown state:** `ENOENT` → proceed; any other errno (`EACCES`, `EPERM`, `EISDIR`, `EIO`, …) → deny.
+- Read size is bounded at `MAX_HALT_READ_BYTES = 1024`; a large HALT file cannot DoS a scan.
+- **Observability:** `ctx.metadata.halt_decision` (`absent` / `present` / `unknown`) is recorded on every audit row, plus `ctx.metadata.halt_at_invocation` (ISO-8601 timestamp when HALT was present, else `null`).
 - The middleware **never clears HALT**. Unfreezing is an explicit `rea unfreeze --reason "..."` CLI action.
 
-**Residual risk:** TOCTOU between the `stat` call and the `open` call is a theoretical race on shared filesystems, but `.rea/` is a project-local directory controlled by the operator.
+**Residual risk:** On shared filesystems with eventual consistency, readers on different hosts could observe HALT at different times. `.rea/` is a project-local directory by design, so this is theoretical for the intended deployment.
 
 ---
 
-### 5.8 Codex Plugin Abuse
+### 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.
+**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.
 
 **Mitigations:**
 
@@ -184,8 +197,13 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 - Every Codex invocation produces an audit entry with request summary, response summary, and pass/fail signal — tamper-evident via the hash chain.
 - 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.
+- **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.
+**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.
 
 ---
 
@@ -198,10 +216,10 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 - `dependency-audit-gate.sh` runs `npm audit` before commits and blocks on high/critical vulnerabilities.
 - Dependabot weekly scans for npm and github-actions.
 - CI publish pipeline includes gitleaks secret scanning and npm publish payload validation.
-- **npm publish uses OIDC provenance** — package identity is cryptographically bound to the GitHub Actions workflow that built it.
-- REA's runtime dependencies are minimal: `@modelcontextprotocol/sdk`, `yaml`, `zod`. No transitive dep >10 levels deep.
+- **npm publish uses OIDC provenance** — package identity is cryptographically bound to the GitHub Actions workflow that built it. Migration to OIDC trusted-publisher (retiring `NODE_AUTH_TOKEN`) is planned for 0.3.0 (G8).
+- REA's runtime dependencies are minimal: `@anthropic-ai/sdk`, `@clack/prompts`, `@modelcontextprotocol/sdk`, `commander`, `safe-regex`, `yaml`, `zod`.
 
-**Residual risk:** Zero-day vulnerabilities in direct or transitive dependencies. SBOM generation is planned but not yet automated.
+**Residual risk:** Zero-day vulnerabilities in direct or transitive dependencies. SBOM generation is planned but not yet automated. The `pnpm test` suite does not exercise "package works when a consumer installs it" — a dev-only dep that's mis-imported at runtime is not caught by CI (this was the 0.2.0 → 0.2.1 issue). A post-publish tarball smoke (install tarball into scratch dir, run CLI) is proposed for 0.3.0.
 
 ---
 
@@ -214,22 +232,75 @@ Downstream MCP servers are treated as untrusted by default. Codex plugin *invoca
 - **REA source code never uses `eval`, `Function()`, or dynamic `require`/`import()` on policy-driven input.** ESLint rules enforce this.
 - Policy parsing is strict zod schema — unknown fields rejected, not ignored.
 - Profile composition is a static key-merge, not a code evaluation.
+- User-supplied redaction regex patterns are compiled via `new RegExp(...)` with `safe-regex` vetting at load and per-call worker-thread timeout enforcement at runtime — regex compilation is the only policy-driven code path, and it's bounded.
 
 **Residual risk:** A malicious third-party middleware plugin (not currently supported) could reintroduce this risk. Plugins are out of scope for v1 by design.
 
 ---
 
+### 5.11 Downstream Subprocess Environment Inheritance
+
+**Threat:** `rea serve` spawns downstream MCP servers as child processes over stdio. Environment variables from the gateway process leak into the child by default (Node's `child_process.spawn` inherits `process.env` unless overridden). A malicious or compromised downstream can read anything the gateway can — `AWS_*`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GITHUB_TOKEN`, database URLs, session cookies.
+
+**Mitigations:**
+
+- Downstream subprocesses are launched with an explicit env object built from `registry.yaml#servers[].env` — the gateway does not pass `process.env` through wholesale.
+- Registry schema is zod `.strict()` — typos in the env list fail at load.
+- Operator intent to forward a specific variable (e.g., `HOME`, `PATH`) is expressed explicitly in `registry.yaml`; no "allow list by default."
+- The `redact` middleware also scrubs values that match secret patterns — if a downstream inadvertently emits a credential in its response, it is redacted before reaching the agent.
+
+**Residual risk:** If an operator explicitly forwards a credential-bearing variable into a downstream, that is a conscious trust decision — REA does not override it. A `rea doctor` lint that flags likely-credential variable names (`*_TOKEN`, `*_KEY`, `*_SECRET`) in registry.yaml is a candidate for 0.3.0 (G7 adjacent).
+
+---
+
+### 5.12 Regex Denial-of-Service (ReDoS)
+
+**Threat:** A malicious MCP payload carefully crafted to trigger catastrophic backtracking in a redaction or injection regex — hanging the gateway's event loop and denying service to all downstream tools.
+
+**Mitigations (shipped 0.2.0, G3):**
+
+- Every built-in pattern in `redact.ts` and `injection.ts` is statically linted via `safe-regex` at build time (`pnpm lint:regex` — chained into `pnpm lint` BEFORE eslint so a bad regex short-circuits the pipeline).
+- Every user-supplied `redact.patterns[]` is re-vetted via `safe-regex` at policy load time; a flagged pattern rejects the entire policy load, naming the offender.
+- Every regex call at runtime flows through `wrapRegex(pattern, {timeoutMs})` — a worker-thread timeout wrapper that blocks the parent on `Atomics.wait` over a SharedArrayBuffer and hard-`terminate()`s the worker on budget exhaustion. Default budget is 100ms; configurable via `policy.redact.match_timeout_ms`.
+- On timeout the redaction middleware substitutes the sentinel `[REDACTED: pattern timeout]` and records `{event: "redact.regex_timeout", pattern_source, pattern_id, input_bytes, timeout_ms}` on `ctx.metadata`. The input text is NEVER written — only its byte length.
+- The "Private Key" PEM armor pattern, flagged by `safe-regex` in the original form, was tightened to a bounded alternation that `safe-regex` accepts.
+
+**Residual risk:** A pattern that `safe-regex` approves but that is nevertheless slow on pathological inputs could still time out frequently, effectively denying redaction for that class of input. The sentinel-replacement behavior is a fail-secure outcome (the value is redacted), but a downstream that can trigger mass timeouts can effectively delete content from reaching the agent. Detection via `.rea/metrics.jsonl` rate-limit signals is the current observability story.
+
+---
+
+### 5.13 Installer Path Trust
+
+**Threat:** `rea init` and `rea upgrade` copy shipped artifacts from the npm package into a consumer project (`.claude/hooks/*`, `.claude/agents/*`, `.claude/commands/*`, `.husky/*`, a managed CLAUDE.md fragment). A compromised npm tarball could carry a subverted hook that runs in the consumer's context with the consumer's privileges.
+
+**Mitigations (shipped 0.2.0, G12):**
+
+- Shipped artifacts are listed explicitly in `package.json#files[]`; nothing outside `dist/`, `hooks/`, `agents/`, `commands/`, `.husky/`, `scripts/`, `profiles/` is in the tarball.
+- npm publish uses `--provenance` — each published version's tarball is cryptographically bound to the exact GitHub Actions workflow run that built it (commit SHA, workflow file, runner image). A consumer can verify provenance via `npm audit signatures`.
+- `rea init` writes `.rea/install-manifest.json` recording the SHA-256 of every shipped file on first install. Subsequent `rea upgrade` runs compare canonical (what this rea version ships) against on-disk content via that manifest, and against the consumer's previous baseline — drifted files are flagged, not silently replaced.
+- `rea upgrade` conflict policy: `unmodified` files auto-update silently; `drifted` files prompt (`keep | overwrite | diff`); `--yes` defaults to `keep` (safe). `--force` required for overwrite.
+- Hook scripts are chmodded `0o755` during copy; the manifest records the hash of the content, not the mode, so a tampered mode is caught by `rea doctor` (which separately checks `hook executable`).
+- The `postinstall` hook prints a one-line stderr nudge when the installed rea version disagrees with the manifest version — silent inside CI (`CI=true`), silent when no manifest exists, silent inside the rea repo itself. It never fails the install.
+
+**Residual risk:** A consumer that blindly accepts `rea upgrade` prompts without reviewing diff output is trusting the current rea version's maintainers transitively through npm. Mitigation depends on the provenance ecosystem maturing — the `npm audit signatures` verification is a manual step today, not a default gate.
+
+---
+
 ## 6. Residual Risks and Open Issues
 
 | Risk                                                          | Severity | Tracking                       |
 | ------------------------------------------------------------- | -------- | ------------------------------ |
-| Semantic prompt injection via tool descriptions               | High     | No issue filed                 |
-| Semantic injection via Codex adversarial-review responses     | High     | No issue filed                 |
-| Double-URL-encoding bypass for blocked paths                  | Medium   | Planned fix in 0.2.x           |
-| No real-time alert on audit hash chain break                  | Medium   | Planned for 0.3.x              |
-| SBOM not automated in publish pipeline                        | Medium   | Planned for 0.2.x              |
+| Semantic prompt injection via tool descriptions               | High     | 0.3.0 G9 (tier escalation)     |
+| 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)     |
+| SBOM not automated in publish pipeline                        | Medium   | Planned                        |
 | Secret pattern gaps (custom token formats, encoding variants) | Medium   | No issue filed                 |
-| TOCTOU on HALT file in shared filesystem scenarios            | Low      | Theoretical                    |
+| 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                 |
 | Local user can escalate policy.yaml outside gateway           | Low      | By design (trusted actor)      |
 
 ---
@@ -238,8 +309,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): 11 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, and PR issue linking.
+**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.
 
-**Gateway layer** (runtime, `rea serve`): A middleware chain processes every proxied MCP tool call. Middleware enforces: kill switch, policy/autonomy level, blocked paths, tier classification, rate limit, circuit breaker, secret redaction (pre and post), prompt injection detection, result size cap, and hash-chained audit logging.
+**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.
 
-Both layers fail closed: on read failure, parse error, or unexpected condition, the default action is deny.
+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/audit/append.d.ts

@@ -15,19 +15,25 @@
  * - Never throws on stat/missing-file conditions; only throws on write failure
  *   (the caller decides how to react).
  *
- * ## Concurrency
+ * ## Concurrency (G1)
  *
- * The helper serializes writes per-process via a module-scoped queue keyed by
- * the resolved audit-file path. Cross-process concurrency on the same file is
- * NOT handled here — writers in separate processes can interleave and break
- * the chain. The current deployment targets (rea's own governance hooks, the
- * Codex agent, Helix) all funnel through a single process at a time. If that
- * changes, add an exclusive-lock file (`audit.jsonl.lock`) before lifting this
- * restriction. Documented risk; do not silently expand the guarantee.
+ * Writes are serialized two ways:
+ *
+ *   1. Per-process: a module-scoped queue keyed by the canonical path
+ *      preserves linear ordering within a single Node process.
+ *   2. Cross-process: each `doAppend` call is wrapped in a `proper-lockfile`
+ *      lock on `.rea/`. Stale locks are reclaimed after 10s. Two processes
+ *      appending concurrently serialize cleanly; the hash chain stays linear.
+ *
+ * Rotation (`maybeRotate`) runs BEFORE the append lock is taken, so a full
+ * audit file is rotated out of the way transparently. The rotation marker
+ * record preserves hash-chain continuity across the boundary.
  *
  * @see {@link file://./codex-event.ts} for the canonical `codex.review` shape.
+ * @see {@link file://../gateway/audit/rotator.ts} for rotation semantics.
  */
 import { Tier, InvocationStatus } from '../policy/types.js';
+import type { Policy } from '../policy/types.js';
 import type { AuditRecord } from '../gateway/middleware/audit-types.js';
 /**
  * Input shape for {@link appendAuditRecord}. All fields except `tool_name`
@@ -47,6 +53,13 @@ export interface AppendAuditInput {
     metadata?: Record<string, unknown>;
     /** ISO-8601 timestamp; defaults to `new Date().toISOString()` */
     timestamp?: string;
+    /**
+     * Optional policy for rotation decisions. When absent, rotation is
+     * disabled (back-compat). Callers that want rotation pass the already-
+     * loaded policy; the helper does not re-read `.rea/policy.yaml` on every
+     * append — that would be a surprise cost for consumers.
+     */
+    policy?: Policy;
 }
 /**
  * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a

package/dist/audit/append.js

@@ -15,23 +15,28 @@
  * - Never throws on stat/missing-file conditions; only throws on write failure
  *   (the caller decides how to react).
  *
- * ## Concurrency
+ * ## Concurrency (G1)
  *
- * The helper serializes writes per-process via a module-scoped queue keyed by
- * the resolved audit-file path. Cross-process concurrency on the same file is
- * NOT handled here — writers in separate processes can interleave and break
- * the chain. The current deployment targets (rea's own governance hooks, the
- * Codex agent, Helix) all funnel through a single process at a time. If that
- * changes, add an exclusive-lock file (`audit.jsonl.lock`) before lifting this
- * restriction. Documented risk; do not silently expand the guarantee.
+ * Writes are serialized two ways:
+ *
+ *   1. Per-process: a module-scoped queue keyed by the canonical path
+ *      preserves linear ordering within a single Node process.
+ *   2. Cross-process: each `doAppend` call is wrapped in a `proper-lockfile`
+ *      lock on `.rea/`. Stale locks are reclaimed after 10s. Two processes
+ *      appending concurrently serialize cleanly; the hash chain stays linear.
+ *
+ * Rotation (`maybeRotate`) runs BEFORE the append lock is taken, so a full
+ * audit file is rotated out of the way transparently. The rotation marker
+ * record preserves hash-chain continuity across the boundary.
  *
  * @see {@link file://./codex-event.ts} for the canonical `codex.review` shape.
+ * @see {@link file://../gateway/audit/rotator.ts} for rotation semantics.
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { Tier, InvocationStatus } from '../policy/types.js';
-const GENESIS_HASH = '0'.repeat(64);
+import { GENESIS_HASH, computeHash, fsyncFile, readLastRecord, withAuditLock, } from './fs.js';
+import { maybeRotate } from '../gateway/audit/rotator.js';
 const REA_DIR = '.rea';
 const AUDIT_FILE = 'audit.jsonl';
 /** Per-file write queue to preserve linear hash-chain order within a process. */
@@ -73,83 +78,43 @@ async function resolveBaseDir(baseDir) {
         return absolute;
     }
 }
-function computeHash(record) {
-    return crypto.createHash('sha256').update(JSON.stringify(record)).digest('hex');
-}
-async function readLastHash(auditFile) {
-    let data;
-    try {
-        data = await fs.readFile(auditFile, 'utf8');
-    }
-    catch (err) {
-        if (err.code === 'ENOENT')
-            return GENESIS_HASH;
-        throw err;
-    }
-    // Walk the file backwards by newline — the last non-empty line is the tail.
-    const trimmed = data.replace(/\n+$/, '');
-    if (trimmed.length === 0)
-        return GENESIS_HASH;
-    const lastNewline = trimmed.lastIndexOf('\n');
-    const lastLine = lastNewline === -1 ? trimmed : trimmed.slice(lastNewline + 1);
-    try {
-        const parsed = JSON.parse(lastLine);
-        if (typeof parsed.hash === 'string' && parsed.hash.length === 64) {
-            return parsed.hash;
-        }
-    }
-    catch {
-        // Corrupt tail line — fall through to genesis. The operator will see this
-        // because the chain verify tool (future) will flag the break point. We do
-        // not throw: refusing to append would mask every subsequent event.
-    }
-    return GENESIS_HASH;
-}
-async function fsyncFile(filePath) {
-    let fh;
-    try {
-        fh = await fs.open(filePath, 'r');
-        await fh.sync();
-    }
-    catch {
-        // fsync failure is not fatal — durability is best-effort here; the write
-        // itself already succeeded.
-    }
-    finally {
-        if (fh)
-            await fh.close();
-    }
-}
 async function doAppend(resolvedBase, input) {
     const reaDir = path.join(resolvedBase, REA_DIR);
     const auditFile = path.join(reaDir, AUDIT_FILE);
     await fs.mkdir(reaDir, { recursive: true });
-    const prevHash = await readLastHash(auditFile);
-    const now = input.timestamp ?? new Date().toISOString();
-    const recordBase = {
-        timestamp: now,
-        session_id: input.session_id ?? 'external',
-        tool_name: input.tool_name,
-        server_name: input.server_name,
-        tier: input.tier ?? Tier.Read,
-        status: input.status ?? InvocationStatus.Allowed,
-        autonomy_level: input.autonomy_level ?? 'unknown',
-        duration_ms: input.duration_ms ?? 0,
-        prev_hash: prevHash,
-    };
-    if (input.error)
-        recordBase.error = input.error;
-    if (input.redacted_fields?.length)
-        recordBase.redacted_fields = input.redacted_fields;
-    if (input.metadata && Object.keys(input.metadata).length > 0) {
-        recordBase.metadata = input.metadata;
-    }
-    const hash = computeHash(recordBase);
-    const record = { ...recordBase, hash };
-    const line = JSON.stringify(record) + '\n';
-    await fs.appendFile(auditFile, line);
-    await fsyncFile(auditFile);
-    return record;
+    // Rotate BEFORE acquiring our append lock. maybeRotate takes its own lock
+    // internally and is idempotent; callers that race simply observe a fresh
+    // file with the rotation marker as their chain anchor.
+    await maybeRotate(auditFile, input.policy);
+    return withAuditLock(auditFile, async () => {
+        const { hash: prevHash } = await readLastRecord(auditFile);
+        const effectivePrev = prevHash || GENESIS_HASH;
+        const now = input.timestamp ?? new Date().toISOString();
+        const recordBase = {
+            timestamp: now,
+            session_id: input.session_id ?? 'external',
+            tool_name: input.tool_name,
+            server_name: input.server_name,
+            tier: input.tier ?? Tier.Read,
+            status: input.status ?? InvocationStatus.Allowed,
+            autonomy_level: input.autonomy_level ?? 'unknown',
+            duration_ms: input.duration_ms ?? 0,
+            prev_hash: effectivePrev,
+        };
+        if (input.error)
+            recordBase.error = input.error;
+        if (input.redacted_fields?.length)
+            recordBase.redacted_fields = input.redacted_fields;
+        if (input.metadata && Object.keys(input.metadata).length > 0) {
+            recordBase.metadata = input.metadata;
+        }
+        const hash = computeHash(recordBase);
+        const record = { ...recordBase, hash };
+        const line = JSON.stringify(record) + '\n';
+        await fs.appendFile(auditFile, line);
+        await fsyncFile(auditFile);
+        return record;
+    });
 }
 /**
  * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a

package/dist/audit/fs.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared audit filesystem primitives (G1). Both the gateway audit middleware
+ * (`src/gateway/middleware/audit.ts`) and the public append helper
+ * (`src/audit/append.ts`) funnel through this module so locking, partial-write
+ * recovery, and rotation semantics stay in lockstep.
+ *
+ * ## Locking
+ *
+ * Every append acquires a `proper-lockfile` lock on the audit file's parent
+ * directory (`.rea/`) — NOT on `audit.jsonl` directly, because `proper-lockfile`
+ * refuses to lock a file that does not yet exist. The lock is taken BEFORE the
+ * read-last-record → compute-hash → append → fsync sequence, so two processes
+ * on the same filesystem can append concurrently without interleaving.
+ *
+ * Stale-lock detection: `proper-lockfile` handles `EEXIST` with `stale: 10000`
+ * (10s). A crashed writer that leaves a stale lockfile frees itself on the
+ * next append attempt.
+ *
+ * ## Partial-write recovery
+ *
+ * An append that crashes mid-write leaves a trailing line WITHOUT a newline.
+ * `readLastRecord()` detects this signal (file doesn't end with `\n`) and
+ * truncates the partial line before returning the previous record's hash.
+ * This recovery is idempotent and runs on every read.
+ *
+ * ## Locking contract
+ *
+ * Callers invoke `withAuditLock(auditFile, async () => { ... })`. The callback
+ * MUST perform its read → compute → append → fsync inside the lock scope. On
+ * lock acquisition failure the callback does NOT run — the caller receives
+ * the error and decides whether to fall back (middleware logs and continues;
+ * the public helper propagates).
+ */
+import type { AuditRecord } from '../gateway/middleware/audit-types.js';
+export declare const GENESIS_HASH: string;
+/**
+ * Acquire an exclusive lock on the audit file's parent directory and run
+ * `fn` inside it. The parent directory must exist before calling this.
+ *
+ * The lock is released even if `fn` throws. Lock-acquisition failures
+ * surface as the caller's rejection — middleware catches and logs, the
+ * public helper propagates.
+ */
+export declare function withAuditLock<T>(auditFile: string, fn: () => Promise<T>): Promise<T>;
+export declare function computeHash(record: Omit<AuditRecord, 'hash'>): string;
+/**
+ * Read the last complete JSON record from the audit file. Returns the parsed
+ * record plus its hash (the value a new append should use for `prev_hash`).
+ *
+ * Recovers from three tail states:
+ *   - File does not exist → genesis.
+ *   - File exists but is empty (or only whitespace) → genesis.
+ *   - File tail does not end in `\n` → treat the trailing partial line as a
+ *     crash signal, truncate it, and return the record before it.
+ *
+ * Never throws on read-side issues except raw I/O errors (permission, ENOSPC,
+ * etc.) that the caller should surface.
+ */
+export declare function readLastRecord(auditFile: string): Promise<{
+    record: AuditRecord | null;
+    hash: string;
+}>;
+/**
+ * Open-and-fsync the audit file. Called after an append to flush the write
+ * to durable storage. fsync failure is not fatal — the append itself
+ * already succeeded; durability is best-effort.
+ */
+export declare function fsyncFile(filePath: string): Promise<void>;