@bookedsolid/rea 0.9.3 → 0.10.0

package/README.md

@@ -480,6 +480,111 @@ and `ClaudeSelfReviewer` is the in-process fallback (tagged
 `degraded: true` in the audit record so self-review is visible and
 countable).
 
+## Agent push workflow — satisfying the push-review gate
+
+When `git push` is blocked by `push-review-gate.sh` the gate prints
+remediation steps. This section is the canonical one-command flow the
+steps reduce to. Agents should copy-paste this verbatim; humans should
+expect agents to.
+
+### 1. Run the adversarial review
+
+```bash
+# From an interactive Claude Code session:
+/codex-review
+```
+
+This invokes the `codex-adversarial` agent, which records a
+`codex.review` audit entry with `verdict: pass | concerns | blocking |
+error` and a `finding_count`. The push gate looks up that entry by
+`head_sha + verdict ∈ {pass, concerns}`.
+
+### 2. Record-and-cache in one CLI call
+
+If you already have a review verdict (from `/codex-review`, or from a
+manual Codex run, or from an offline review) emit the audit record AND
+update the push-review cache with a single command:
+
+```bash
+rea audit record codex-review \
+  --head-sha "$(git rev-parse HEAD)" \
+  --branch   "$(git rev-parse --abbrev-ref HEAD)" \
+  --target   main \
+  --verdict  pass \
+  --finding-count 0 \
+  --summary  "no findings" \
+  --also-set-cache
+```
+
+`--also-set-cache` writes both `.rea/audit.jsonl` and
+`.rea/review-cache.jsonl` in the same invocation (two sequential
+appends, not a two-phase commit — but close enough in practice that the
+push-gate lookup cannot see the audit record without the cache entry
+unless a crash lands between them). Without it, the audit record lands
+but the cache stays cold — and the next `git push` pays for a re-review
+even though the audit trail already shows the review happened.
+`--also-set-cache` is what the gate's remediation text should be reduced
+to.
+
+Verdict mapping for the cache leg:
+
+| `--verdict`  | Cache `result` | Cache `reason` |
+| ------------ | -------------- | -------------- |
+| `pass`       | `pass`         | — (omitted) |
+| `concerns`   | `pass`         | `codex:concerns` |
+| `blocking`   | `fail`         | `codex:blocking` |
+| `error`      | `fail`         | `codex:error` |
+
+### 3. Push
+
+```bash
+git push
+```
+
+The gate hits the cache, sees `{"hit":true,"result":"pass"}`, and exits
+0 on the first attempt. No `!`-bash escapes, no manual audit writing,
+no separate `rea cache set` invocation.
+
+### SDK alternative
+
+When embedding the flow in a TypeScript tool instead of shelling out,
+import the public audit helper:
+
+```ts
+import {
+  appendAuditRecord,
+  CODEX_REVIEW_SERVER_NAME,
+  CODEX_REVIEW_TOOL_NAME,
+  InvocationStatus,
+  Tier,
+} from '@bookedsolid/rea/audit';
+
+await appendAuditRecord(process.cwd(), {
+  tool_name: CODEX_REVIEW_TOOL_NAME,
+  server_name: CODEX_REVIEW_SERVER_NAME,
+  tier: Tier.Read,
+  status: InvocationStatus.Allowed,
+  metadata: {
+    head_sha: headSha,
+    target: 'main',
+    finding_count: 0,
+    verdict: 'pass',
+  },
+});
+```
+
+The CLI wraps exactly this — use the CLI unless the host is already a
+TypeScript process that wants to avoid the subprocess roundtrip.
+
+### Agent autonomy self-consistency
+
+At autonomy `L1`, `rea cache check`, `rea audit record codex-review`,
+`rea doctor`, and `rea status` are classified **Read tier** — they
+cannot be denied by REA's own middleware. `rea cache set` is Write
+tier and is still allowed at L1. `rea freeze` is Destructive tier and
+is denied at L1 (deny-reason includes the subcommand, e.g.
+`Bash (rea freeze)`, not just `Bash`).
+
 ## Hooks
 
 Fourteen hooks. Each does one thing.

package/THREAT_MODEL.md

@@ -1,6 +1,6 @@
 # Threat Model — REA Gateway and Hook Layer
 
-Version: 0.9.x | Last updated: 2026-04-21
+Version: 0.10.x | Last updated: 2026-04-21
 
 ---
 
@@ -475,6 +475,24 @@ Ref: `src/registry/fingerprint.ts` (`canonicalize()`, `fingerprintServer()`), `s
 
 Ref: `src/gateway/middleware/injection.ts`, `src/gateway/middleware/injection.test.ts`.
 
+### 5.22 Hook-Patch Session Env Var (0.10.0, Defect I)
+
+**Threat:** `settings-protection.sh` blanket-blocks edits under `.claude/hooks/`. That is the correct default (agents must not silently rewrite safety infrastructure) but it leaves no documented path for applying upstream-sourced CodeRabbit/Codex findings on hook scripts during a live session. Before 0.10.0, operators reached for `!`-bash to sidestep the hook entirely, which dodged every audit surface — a worse outcome than the block it was working around. The source-of-truth `hooks/` directory is intentionally editable by default; `rea init` is the supply-chain step that promotes those edits into `.claude/hooks/`, so gating at the runtime directory is where the runtime-trust decision belongs.
+
+**Mitigations:**
+
+- `REA_HOOK_PATCH_SESSION=<reason>` is a **session-scoped**, **self-revoking** bypass. When set to a non-empty value, `settings-protection.sh` (`hooks/settings-protection.sh:219-336`) allows edits ONLY to paths under `.claude/hooks/` (the runtime directory). Every other protected path (`.rea/policy.yaml`, `.rea/HALT`, `.claude/settings.json`, `.claude/settings.local.json`) remains blocked — this is a hook-maintenance escape hatch, not a policy-editing one.
+- Order of enforcement: (§5a) reject any path containing a `..` segment in either raw or normalized form; (§6) deny hard-protected paths; (§6b) only then consult the patch-session allowlist. This ordering closes a pre-merge Codex-surfaced bypass where `.claude/hooks/../settings.json` slipped through the old patch-session case-glob and reached `.claude/settings.json` on disk with the env var set.
+- The session boundary IS the expiry. A new shell requires a fresh opt-in. There is no auto-expiry countdown to race, no policy-file flag that can silently linger across sessions, no CI refusal — the env var lives and dies with the process that set it.
+- Every allowed edit emits a `hooks.patch.session` audit record routed through the TypeScript `appendAuditRecord()` chain (`src/audit/append.ts`) so the entry extends the hash chain and cannot be silently back-filled. The payload carries: `metadata.reason` (env-var value verbatim, control-character-stripped before display), `metadata.file` (normalized path), `metadata.sha_before` (pre-edit SHA-256 of the file, captured via the portable `sha256sum`/`shasum`/`openssl` fallback chain), `metadata.actor.{name,email}` (from `git config`), `metadata.pid`, `metadata.ppid`. The hook resolves the audit module via two paths, in order: (1) `import("@bookedsolid/rea/audit")` — succeeds for `rea init`-installed consumers via `node_modules/`, and via package self-reference when running inside the rea source repo; (2) `import(REA_ROOT + "/dist/audit/append.js")` — direct file import for development checkouts. If BOTH resolve-paths fail, the edit is **refused outright** (exit 2). There is no bash-native jq fallback because that path would skip `prev_hash`/`hash` computation and silently degrade the chain integrity `rea audit verify` relies on — audit-drop is indistinguishable from chain tampering, and a hook that can drop audit on demand is a governance failure, not a usability win.
+- Note on `codex.review` entries: audit records emitted by `rea audit record codex-review` (and the related hook-append paths) are **local assertions** recorded by the operator's agent runtime. They extend the local hash chain — so retroactive tampering is detectable — but they are not signed by Codex or by any external party. Operators auditing a consumer repo must treat the presence of a `codex.review` record as evidence that SOMEONE claimed a Codex pass at that SHA, not cryptographic proof that Codex itself issued that verdict.
+
+**Trust boundary:** `REA_HOOK_PATCH_SESSION` is advisory for the tool-gate bypass only. It does not raise the autonomy level, does not disable any other hook, and does not relax blocked-paths, attribution, or secret-scanning enforcement. The gateway-layer middleware chain does not read this env var — it only affects the shell hook that guards `.claude/hooks/`. A malicious agent that set the env var for itself without human intent would gain the ability to mutate runtime hooks, but every such mutation is auditable and the session ends with the shell; there is no persistent escalation path.
+
+**Residual risk:** An operator who declares a reason and then forgets to unset the variable carries the bypass across every subsequent hook edit in that shell. Mitigation: treat the env var as a one-use stand and unset it immediately after the intended patch; the audit trail will show repeated `hooks.patch.session` records if the lifetime leaks. A follow-up hardening could scope the var to a single edit by tying it to a nonce committed to the audit record and invalidating on next append — not shipped in 0.10.0 because the session-boundary model matches how operators actually reason about the feature.
+
+Ref: `hooks/settings-protection.sh:86-336`, `.claude/hooks/settings-protection.sh` (dogfood mirror), `__tests__/hooks/settings-protection-patch-session.test.ts`, `src/audit/append.ts`.
+
 ---
 
 ## 6. Residual Risks and Open Issues

package/dist/cli/audit.d.ts

@@ -10,6 +10,7 @@
  * explicit by definition, and verify operates on existing files regardless
  * of policy.
  */
+import { type CodexVerdict } from '../audit/append.js';
 /**
  * Reserved for future rotate knobs (e.g. `--retain N` to prune old rotated
  * files). Empty today — kept as a typed record so the call site's option
@@ -38,3 +39,33 @@ export declare function runAuditRotate(_options: AuditRotateOptions): Promise<vo
  * exit code is the primary signal.
  */
 export declare function runAuditVerify(options: AuditVerifyOptions): Promise<void>;
+export interface AuditRecordCodexReviewOptions {
+    headSha: string;
+    branch: string;
+    target: string;
+    verdict: CodexVerdict;
+    findingCount: number;
+    summary?: string | undefined;
+    sessionId?: string | undefined;
+    alsoSetCache?: boolean | undefined;
+}
+/**
+ * `rea audit record codex-review` (Defect D / rea#77). Emits the single audit
+ * event the push-review cache gate looks up by `tool_name == "codex.review"` +
+ * `metadata.head_sha == <sha>` + `metadata.verdict in {pass, concerns}`. Prior
+ * to this command, agents had to reverse-engineer the canonical `tool_name`
+ * string, the hash-chain append path, and the `CodexReviewMetadata` shape —
+ * the most common failure mode was emitting `tool_name: "codex-adversarial-review"`
+ * (the agent's name) instead of `codex.review` (the event type), which the
+ * gate's jq predicate silently missed.
+ *
+ * `--also-set-cache` performs the audit record AND the review-cache write
+ * in one invocation — two sequential appends in a single process, not a
+ * two-phase commit. A crash between them leaves the audit entry without
+ * a cache row; the cache is recomputable from audit, the audit chain is
+ * the source of truth. What this DOES eliminate is the two-step race where
+ * `rea cache set` is denied by permission middleware (Defect E) after the
+ * audit has already been emitted, leaving the gate stuck on "audit present
+ * but cache cold" with no way forward.
+ */
+export declare function runAuditRecordCodexReview(options: AuditRecordCodexReviewOptions): Promise<void>;

package/dist/cli/audit.js

@@ -13,8 +13,12 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { forceRotate } from '../gateway/audit/rotator.js';
+import { appendAuditRecord, CODEX_REVIEW_SERVER_NAME, CODEX_REVIEW_TOOL_NAME, } from '../audit/append.js';
 import { computeHash, GENESIS_HASH } from '../audit/fs.js';
+import { appendEntry as appendCacheEntry } from '../cache/review-cache.js';
 import { AUDIT_FILE, REA_DIR, err, log, reaPath } from './utils.js';
+import { Tier, InvocationStatus } from '../policy/types.js';
+import { codexVerdictToCacheResult } from './cache.js';
 /**
  * `rea audit rotate`. Forces a rotation now regardless of thresholds.
  * Empty audit files are a no-op — rotating an empty chain would produce a
@@ -203,3 +207,70 @@ export async function runAuditVerify(options) {
     }
     log(`Audit chain verified: ${totalRecords} records across ${filesToVerify.length} file(s) — clean.`);
 }
+/**
+ * `rea audit record codex-review` (Defect D / rea#77). Emits the single audit
+ * event the push-review cache gate looks up by `tool_name == "codex.review"` +
+ * `metadata.head_sha == <sha>` + `metadata.verdict in {pass, concerns}`. Prior
+ * to this command, agents had to reverse-engineer the canonical `tool_name`
+ * string, the hash-chain append path, and the `CodexReviewMetadata` shape —
+ * the most common failure mode was emitting `tool_name: "codex-adversarial-review"`
+ * (the agent's name) instead of `codex.review` (the event type), which the
+ * gate's jq predicate silently missed.
+ *
+ * `--also-set-cache` performs the audit record AND the review-cache write
+ * in one invocation — two sequential appends in a single process, not a
+ * two-phase commit. A crash between them leaves the audit entry without
+ * a cache row; the cache is recomputable from audit, the audit chain is
+ * the source of truth. What this DOES eliminate is the two-step race where
+ * `rea cache set` is denied by permission middleware (Defect E) after the
+ * audit has already been emitted, leaving the gate stuck on "audit present
+ * but cache cold" with no way forward.
+ */
+export async function runAuditRecordCodexReview(options) {
+    if (options.headSha.length === 0) {
+        err('--head-sha must not be empty');
+        process.exit(1);
+    }
+    if (options.branch.length === 0) {
+        err('--branch must not be empty');
+        process.exit(1);
+    }
+    if (options.target.length === 0) {
+        err('--target must not be empty');
+        process.exit(1);
+    }
+    if (!Number.isFinite(options.findingCount) || options.findingCount < 0) {
+        err(`--finding-count must be a non-negative integer; got ${options.findingCount}`);
+        process.exit(1);
+    }
+    const baseDir = process.cwd();
+    const metadata = {
+        head_sha: options.headSha,
+        target: options.target,
+        finding_count: options.findingCount,
+        verdict: options.verdict,
+    };
+    if (options.summary !== undefined && options.summary.length > 0) {
+        metadata.summary = options.summary;
+    }
+    await appendAuditRecord(baseDir, {
+        tool_name: CODEX_REVIEW_TOOL_NAME,
+        server_name: CODEX_REVIEW_SERVER_NAME,
+        tier: Tier.Read,
+        status: InvocationStatus.Allowed,
+        ...(options.sessionId !== undefined ? { session_id: options.sessionId } : {}),
+        metadata,
+    });
+    log(`Recorded codex.review (${options.verdict}, ${options.findingCount} finding${options.findingCount === 1 ? '' : 's'}) for ${options.headSha.slice(0, 12)}.`);
+    if (options.alsoSetCache === true) {
+        const effect = codexVerdictToCacheResult(options.verdict);
+        const cacheEntry = await appendCacheEntry(baseDir, {
+            sha: options.headSha,
+            branch: options.branch,
+            base: options.target,
+            result: effect.result,
+            ...(effect.reason !== undefined ? { reason: effect.reason } : {}),
+        });
+        log(`Cached ${cacheEntry.result} for ${cacheEntry.sha.slice(0, 12)} (${cacheEntry.branch} → ${cacheEntry.base}).`);
+    }
+}

package/dist/cli/cache.d.ts

@@ -20,6 +20,7 @@
  * entirely.
  */
 import { type CacheResult } from '../cache/review-cache.js';
+import type { CodexVerdict } from '../audit/codex-event.js';
 export interface CacheCheckOptions {
     sha: string;
     branch: string;
@@ -48,5 +49,36 @@ export declare function runCacheCheck(options: CacheCheckOptions): Promise<void>
 export declare function runCacheSet(options: CacheSetOptions): Promise<void>;
 export declare function runCacheClear(options: CacheClearOptions): Promise<void>;
 export declare function runCacheList(options: CacheListOptions): Promise<void>;
-/** Parse-and-validate helper for `set` — surfaces a clean error on bad input. */
+/** Parse-and-validate helper for `set` — surfaces a clean error on bad input.
+ *
+ * Accepts the two historical cache values (`pass`, `fail`) AND the four
+ * canonical Codex verdicts (`pass`, `concerns`, `blocking`, `error`) per
+ * Defect D (rea#77). Codex verdicts are mapped to cache semantics at the CLI
+ * boundary: `pass|concerns` → gate-satisfying `pass`; `blocking|error` →
+ * gate-failing `fail`. The cache internal vocabulary stays binary
+ * (`pass`/`fail` = "gate-satisfying?") while the CLI accepts the full Codex
+ * vocabulary so agents can copy the `/codex-review` verdict verbatim.
+ */
 export declare function parseCacheResult(raw: string): CacheResult;
+/** Shape returned by {@link codexVerdictToCacheResult}: the binary cache result
+ * plus an optional machine-readable `reason` string that records the source
+ * Codex verdict. `reason` is populated for non-`pass` verdicts so downstream
+ * listings expose WHY a cache fail was recorded. */
+export interface CodexVerdictCacheEffect {
+    result: CacheResult;
+    reason?: string | undefined;
+}
+/** Map a Codex verdict to the binary cache result the gate compares against.
+ *
+ * Mapping rationale:
+ *   - `pass` → cache `pass` (clean review, gate should pass)
+ *   - `concerns` → cache `pass` (non-blocking findings, gate should pass;
+ *     reviewer captured concerns in the audit record `metadata.summary`)
+ *   - `blocking` → cache `fail` (must address findings before merge)
+ *   - `error` → cache `fail` (Codex itself errored; no clean-bill-of-health)
+ *
+ * Kept separate from `parseCacheResult` so callers that already have a typed
+ * `CodexVerdict` (e.g. `rea audit record codex-review --also-set-cache`) don't
+ * round-trip through string parsing.
+ */
+export declare function codexVerdictToCacheResult(verdict: CodexVerdict): CodexVerdictCacheEffect;

package/dist/cli/cache.js

@@ -103,10 +103,48 @@ export async function runCacheList(options) {
         console.log(`${e.recorded_at}  ${e.result.padEnd(4)}  ${shortSha}  ${e.branch} → ${e.base}${reason}`);
     }
 }
-/** Parse-and-validate helper for `set` — surfaces a clean error on bad input. */
+/** Parse-and-validate helper for `set` — surfaces a clean error on bad input.
+ *
+ * Accepts the two historical cache values (`pass`, `fail`) AND the four
+ * canonical Codex verdicts (`pass`, `concerns`, `blocking`, `error`) per
+ * Defect D (rea#77). Codex verdicts are mapped to cache semantics at the CLI
+ * boundary: `pass|concerns` → gate-satisfying `pass`; `blocking|error` →
+ * gate-failing `fail`. The cache internal vocabulary stays binary
+ * (`pass`/`fail` = "gate-satisfying?") while the CLI accepts the full Codex
+ * vocabulary so agents can copy the `/codex-review` verdict verbatim.
+ */
 export function parseCacheResult(raw) {
     if (raw === 'pass' || raw === 'fail')
         return raw;
-    err(`result must be 'pass' or 'fail'; got ${JSON.stringify(raw)}`);
+    if (raw === 'concerns')
+        return 'pass';
+    if (raw === 'blocking' || raw === 'error')
+        return 'fail';
+    err(`result must be 'pass', 'fail', 'concerns', 'blocking', or 'error'; got ${JSON.stringify(raw)}`);
     process.exit(1);
 }
+/** Map a Codex verdict to the binary cache result the gate compares against.
+ *
+ * Mapping rationale:
+ *   - `pass` → cache `pass` (clean review, gate should pass)
+ *   - `concerns` → cache `pass` (non-blocking findings, gate should pass;
+ *     reviewer captured concerns in the audit record `metadata.summary`)
+ *   - `blocking` → cache `fail` (must address findings before merge)
+ *   - `error` → cache `fail` (Codex itself errored; no clean-bill-of-health)
+ *
+ * Kept separate from `parseCacheResult` so callers that already have a typed
+ * `CodexVerdict` (e.g. `rea audit record codex-review --also-set-cache`) don't
+ * round-trip through string parsing.
+ */
+export function codexVerdictToCacheResult(verdict) {
+    switch (verdict) {
+        case 'pass':
+            return { result: 'pass' };
+        case 'concerns':
+            return { result: 'pass', reason: 'codex:concerns' };
+        case 'blocking':
+            return { result: 'fail', reason: 'codex:blocking' };
+        case 'error':
+            return { result: 'fail', reason: 'codex:error' };
+    }
+}

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { runAuditRotate, runAuditVerify } from './audit.js';
+import { runAuditRecordCodexReview, runAuditRotate, runAuditVerify } from './audit.js';
 import { parseCacheResult, runCacheCheck, runCacheClear, runCacheList, runCacheSet, } from './cache.js';
 import { runCheck } from './check.js';
 import { runDoctor } from './doctor.js';
@@ -102,6 +102,44 @@ async function main() {
         .action(async (opts) => {
         await runAuditVerify({ ...(opts.since !== undefined ? { since: opts.since } : {}) });
     });
+    const auditRecord = audit
+        .command('record')
+        .description('Emit a structured audit record (D).');
+    auditRecord
+        .command('codex-review')
+        .description('Append a codex.review audit entry the push-review cache gate recognizes. With --also-set-cache, writes the review cache in the same invocation (two sequential appends in one process — not a two-phase commit).')
+        .requiredOption('--head-sha <sha>', 'git HEAD SHA the review covers')
+        .requiredOption('--branch <branch>', 'feature branch under review')
+        .requiredOption('--target <target>', 'base ref or SHA diffed against (e.g. main)')
+        .requiredOption('--verdict <verdict>', 'one of: pass | concerns | blocking | error')
+        .requiredOption('--finding-count <N>', 'non-negative integer finding count', (raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isFinite(n) || n < 0) {
+            throw new Error(`--finding-count must be a non-negative integer; got ${JSON.stringify(raw)}`);
+        }
+        return n;
+    })
+        .option('--summary <text>', 'one-sentence review summary (optional)')
+        .option('--session-id <id>', 'session id to attribute (defaults to "external")')
+        .option('--also-set-cache', 'also update .rea/review-cache.jsonl to reflect this verdict, in the same invocation (recommended for post-review push flow)')
+        .action(async (opts) => {
+        if (opts.verdict !== 'pass' &&
+            opts.verdict !== 'concerns' &&
+            opts.verdict !== 'blocking' &&
+            opts.verdict !== 'error') {
+            throw new Error(`--verdict must be one of pass|concerns|blocking|error; got ${JSON.stringify(opts.verdict)}`);
+        }
+        await runAuditRecordCodexReview({
+            headSha: opts.headSha,
+            branch: opts.branch,
+            target: opts.target,
+            verdict: opts.verdict,
+            findingCount: opts.findingCount,
+            ...(opts.summary !== undefined ? { summary: opts.summary } : {}),
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+            ...(opts.alsoSetCache === true ? { alsoSetCache: true } : {}),
+        });
+    });
     const cache = program
         .command('cache')
         .description('Review-cache operations — check/set/clear/list .rea/review-cache.jsonl (BUG-009). Used by hooks/push-review-gate.sh to skip re-review on a previously-approved diff.');
@@ -115,7 +153,7 @@ async function main() {
     });
     cache
         .command('set <sha> <result>')
-        .description('Record a review outcome. <result> must be "pass" or "fail". Idempotent line-per-invocation; last write wins on (sha, branch, base).')
+        .description('Record a review outcome. <result> accepts pass|fail (historical) or pass|concerns|blocking|error (Codex verdicts). concerns→pass, blocking|error→fail. Idempotent line-per-invocation; last write wins on (sha, branch, base).')
         .requiredOption('--branch <branch>', 'feature branch being pushed')
         .requiredOption('--base <base>', 'base branch the feature targets')
         .option('--reason <text>', 'free-text context for this entry (recommended on fail)')

package/dist/config/tier-map.d.ts

@@ -9,3 +9,4 @@ export declare function classifyTool(toolName: string, serverName: string, gatew
  * Check if a tool is explicitly blocked in gateway config.
  */
 export declare function isToolBlocked(toolName: string, serverName: string, gatewayConfig?: GatewayConfig): boolean;
+export declare function reaCommandTier(command: string): Tier | null;

package/dist/config/tier-map.js

@@ -106,3 +106,213 @@ export function isToolBlocked(toolName, serverName, gatewayConfig) {
     const override = serverConfig?.tool_overrides?.[toolName];
     return override?.blocked === true;
 }
+/**
+ * Classify a `rea <subcommand>` Bash invocation by its own semantics rather
+ * than the generic Bash default.
+ *
+ * Defect E (rea#78): REA's own governance CLI must not be denied by REA's own
+ * middleware. The gate's error messages literally say "Run `rea cache set
+ * <sha> pass --branch <x> --base <y>`" — then the agent is denied at autonomy
+ * L1 because `Bash` is classified Write and the downstream middleware can't
+ * see that the Write is just appending a line to `.rea/review-cache.jsonl`.
+ *
+ * This helper returns the tier appropriate to the rea subcommand when the
+ * command parses as `rea <sub>` or `npx rea <sub>`. Returns `null` if the
+ * command is not a rea invocation — callers then fall back to the generic
+ * Bash tier.
+ *
+ * Tier mapping:
+ *   - Read:        `cache check|list|get`, `audit verify`,
+ *                  `audit record codex-review`, `check`, `doctor`, `status`
+ *   - Write:       `cache set|clear`, `audit rotate`, `init`,
+ *                  `serve`, `upgrade`, `unfreeze`
+ *   - Destructive: `freeze` (writes `.rea/HALT`, suspends the session)
+ *
+ * `audit record codex-review` is Read-tier because it is REA's own append-only
+ * audit surface — the whole point of the command is to let an L1 agent satisfy
+ * the push-review gate without a human in the loop. Write-tier here would
+ * reintroduce exactly the deadlock Defect D/E close.
+ *
+ * SECURITY: returns `null` for any command containing shell metacharacters
+ * that would let an attacker piggyback arbitrary commands onto an allowed
+ * prefix (e.g. `rea check && rm -rf ~`). Bash tokenizes on whitespace, but
+ * the shell itself dispatches the full command string — token[0] matching
+ * is not a sufficient trust decision. Falling back to `null` forces the
+ * generic Write-tier Bash default, which is what the operator expects for
+ * any command they did not explicitly model here.
+ */
+// Reject redirection and chaining operators. Bare `rea check > /etc/passwd`
+// still executes a write the classifier cannot reason about; same for
+// heredocs (`<<`), pipe-process-substitution (`>(`, `<(`), and the
+// chain/substitute operators the prior pass already covered.
+const REA_SHELL_METACHAR_RE = /[;&|`\n\r<>]|\$\(|>\(|<\(/;
+/**
+ * Returns true iff `first` is an invocation shape we trust for Read-tier
+ * downgrade. Implemented as a function because the trust rules are not pure
+ * suffix matching — pass-3 Codex review surfaced two P1 bypasses in the old
+ * suffix-only model:
+ *
+ *   1. A repo-authored `./bin/rea` script satisfied `endsWith('/bin/rea')`
+ *      and classified as Read at L0 → RCE via repo content.
+ *   2. A repo-authored `./dist/cli/index.js` satisfied
+ *      `endsWith('/dist/cli/index.js')` → same.
+ *
+ * The rules now require:
+ *   - The first token is **absolute** (starts with `/`). Relative paths are
+ *     attacker-influenced via CWD and repo content, so they never get the
+ *     Read-tier downgrade. Callers MAY still run relative-path rea — they
+ *     just fall through to weak-trust (bare `rea`) semantics: Destructive
+ *     subcommands still upgrade; Read/Write fall back to the generic Bash
+ *     Write tier.
+ *   - The path matches one of the two *strong* install shapes:
+ *       (a) contains `/node_modules/.bin/rea` anywhere (unambiguous marker
+ *           of an npm install directory tree);
+ *       (b) starts with `/usr/` or `/opt/` AND ends with `/bin/rea`
+ *           (classic root-write system install location). `/home/…/bin/rea`
+ *           is intentionally NOT honored — `/home/<user>/` is writable
+ *           without root, so an attacker with local shell access could
+ *           pre-seed a trusted-looking path there.
+ *
+ * The old `/dist/cli/index.js` suffix is gone entirely. The legitimate
+ * developer invocation `node ./dist/cli/index.js` has `first === 'node'`
+ * which never matches; only a filesystem-marked-executable
+ * `./dist/cli/index.js` would have hit the old suffix, and that shape was
+ * always attacker-authorable inside a repo. Similarly, `/.bin/rea` (exactly
+ * `/.bin/rea`, at filesystem root) was an accident of suffix matching, not
+ * a real install location; it is gone.
+ */
+function isTrustedReaPath(first) {
+    if (!first.startsWith('/'))
+        return false;
+    // npm install marker — absolute path whose tail is `/node_modules/.bin/rea`.
+    // This is unambiguous: an attacker can only seed this path by having already
+    // run a real npm install, at which point they already had execution.
+    if (first.endsWith('/node_modules/.bin/rea'))
+        return true;
+    // Classic global install — absolute path rooted at a system prefix that
+    // requires root write (so attacker-seeded files are out-of-scope for the
+    // repo-content threat model).
+    if (first.endsWith('/bin/rea')) {
+        if (first.startsWith('/usr/'))
+            return true;
+        if (first.startsWith('/opt/'))
+            return true;
+    }
+    return false;
+}
+export function reaCommandTier(command) {
+    if (typeof command !== 'string' || command.length === 0)
+        return null;
+    // Refuse to classify commands that chain/substitute/redirect — the trailing
+    // shell payload is arbitrary, so the prefix's read-tier status tells us
+    // nothing about what the shell will actually execute.
+    if (REA_SHELL_METACHAR_RE.test(command))
+        return null;
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return null;
+    const tokens = trimmed.split(/\s+/);
+    if (tokens.length === 0)
+        return null;
+    const first = tokens[0];
+    if (first === undefined)
+        return null;
+    // Classify the invocation's trust posture. The ONLY fully-trusted shape is
+    // an absolute-path invocation that `isTrustedReaPath()` recognizes as a
+    // strong install marker (npm `/node_modules/.bin/rea` or a root-write
+    // system global under `/usr/` or `/opt/`). Everything else — bare `rea`,
+    // `npx rea …`, relative paths — is treated as *weak trust*: we still
+    // recognize the subcommand for the sake of destructive-tier UPGRADES
+    // (e.g. `rea freeze` at L1 should be blocked whether or not we can prove
+    // the binary is ours), but we refuse to DOWNGRADE anything that could be
+    // piggybacking on a PATH-spoofable name or an `npx` network/install
+    // side-effect.
+    //
+    // npx note (pass-3 Codex Finding 2): `npx rea …` on a machine without the
+    // package locally cached downloads the tarball, writes to the npm cache,
+    // and executes — explicitly not Read-tier semantics. Treating npx as weak
+    // trust forces agents to commit to a deterministic install path (absolute
+    // `/usr/local/bin/rea` from `npm i -g`, or the fully-resolved
+    // `/…/node_modules/.bin/rea` from a project install) if they want the
+    // Read-tier downgrade.
+    let idx = 0;
+    let trust = 'trusted';
+    if (first === 'npx') {
+        if (tokens.length < 2)
+            return null;
+        const second = tokens[1];
+        if (second !== 'rea' && second !== '@bookedsolid/rea')
+            return null;
+        idx = 2;
+        trust = 'weak';
+    }
+    else if (isTrustedReaPath(first)) {
+        idx = 1;
+    }
+    else if (first === 'rea' || first.split('/').pop() === 'rea') {
+        // Bare `rea` OR any path (relative/absolute) whose tail is literally
+        // `rea`. This captures `./bin/rea`, `./node_modules/.bin/rea`,
+        // `/home/user/.npm-global/bin/rea`, `/tmp/fake/rea`, etc. — none of
+        // these are full-trust under `isTrustedReaPath()`, but we still want
+        // Destructive subcommands (`freeze`) to UPGRADE from Bash Write even
+        // here, because destructive intent is invocation-shape-independent.
+        idx = 1;
+        trust = 'weak';
+    }
+    else {
+        return null;
+    }
+    const sub = tokens[idx];
+    if (sub === undefined) {
+        // `rea` with no subcommand is help/version under `commander` — a read.
+        // Under weak trust, we refuse to downgrade; fall back to generic Write.
+        return trust === 'trusted' ? Tier.Read : null;
+    }
+    const sub2 = tokens[idx + 1];
+    const subcommandTier = (() => {
+        switch (sub) {
+            case 'check':
+            case 'doctor':
+            case 'status':
+                return Tier.Read;
+            case 'cache': {
+                if (sub2 === 'check' || sub2 === 'list' || sub2 === 'get')
+                    return Tier.Read;
+                if (sub2 === 'set' || sub2 === 'clear')
+                    return Tier.Write;
+                return Tier.Write;
+            }
+            case 'audit': {
+                if (sub2 === 'verify')
+                    return Tier.Read;
+                if (sub2 === 'record')
+                    return Tier.Read;
+                if (sub2 === 'rotate')
+                    return Tier.Write;
+                return Tier.Write;
+            }
+            case 'init':
+            case 'serve':
+            case 'upgrade':
+            case 'unfreeze':
+                return Tier.Write;
+            case 'freeze':
+                return Tier.Destructive;
+            default:
+                return null;
+        }
+    })();
+    // Trusted path — return whatever the subcommand semantics say.
+    // Unknown subcommand: default Write (safer than Read).
+    if (trust === 'trusted') {
+        return subcommandTier ?? Tier.Write;
+    }
+    // Weak trust (bare `rea`) — only honor upgrades above Write.
+    // Read/Write subcommands: return null so the middleware applies the generic
+    // Bash Write default (same as the pre-helper behavior, no downgrade).
+    // Destructive subcommands: KEEP the upgrade — `rea freeze` at L1 must block
+    // even if we cannot prove the binary on PATH is ours.
+    if (subcommandTier === Tier.Destructive)
+        return Tier.Destructive;
+    return null;
+}