@bookedsolid/rea 0.9.4 → 0.10.1

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/audit/append.d.ts

@@ -65,11 +65,45 @@ export interface AppendAuditInput {
  * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a
  * hash chained against the tail of the existing log.
  *
+ * ## emission_source (defect P)
+ *
+ * Records written through this public helper are ALWAYS stamped with
+ * `emission_source: "other"`. External consumers (Helix, ad-hoc scripts,
+ * plugins) have no way to self-assert `"rea-cli"` or `"codex-cli"` through
+ * this entry point — the parameter is not part of the public
+ * {@link AppendAuditInput} shape. Records emitted by the rea CLI itself use
+ * the dedicated {@link appendCodexReviewAuditRecord} helper, which is the
+ * ONLY path that stamps `"rea-cli"`.
+ *
+ * The push-review cache gate rejects `codex.review` records whose
+ * `emission_source` is `"other"` (or missing, for legacy records), so
+ * forging a `codex.review` record through this helper produces a line that
+ * is on the hash chain but does NOT satisfy the gate.
+ *
  * @param baseDir - Repo/project root (the directory that contains `.rea/`).
  * @param input   - Event data. `tool_name` and `server_name` are required.
  * @returns The full written record, including the computed `hash`.
  */
 export declare function appendAuditRecord(baseDir: string, input: AppendAuditInput): Promise<AuditRecord>;
-export type { AuditRecord } from '../gateway/middleware/audit-types.js';
+/**
+ * Append a `tool_name: "codex.review"` audit record certifying that a Codex
+ * adversarial review ran on a specific commit SHA (defect P).
+ *
+ * This is the ONLY write path in `@bookedsolid/rea` that produces
+ * `emission_source: "rea-cli"` for `codex.review` records. Consumers MUST
+ * reach this helper through the `rea audit record codex-review` CLI (which
+ * is classified as a Write-tier Bash invocation by `reaCommandTier`, defect
+ * E). Any other code path calling the generic {@link appendAuditRecord}
+ * with `tool_name: "codex.review"` lands with `emission_source: "other"`
+ * and does NOT satisfy the push-review cache gate — closing the forgery
+ * surface that `.reports/hook-patches/emit-audit-*.mjs` scripts exploited
+ * before this patch.
+ *
+ * `tool_name` and `server_name` are fixed to the canonical values
+ * (`"codex.review"` / `"codex"`) and are NOT accepted as caller inputs —
+ * the type excludes them so the contract is self-documenting.
+ */
+export declare function appendCodexReviewAuditRecord(baseDir: string, input: Omit<AppendAuditInput, 'tool_name' | 'server_name'>): Promise<AuditRecord>;
+export type { AuditRecord, EmissionSource } from '../gateway/middleware/audit-types.js';
 export { Tier, InvocationStatus } from '../policy/types.js';
 export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, type CodexVerdict, type CodexReviewMetadata, } from './codex-event.js';

package/dist/audit/append.js

@@ -37,6 +37,7 @@ import path from 'node:path';
 import { Tier, InvocationStatus } from '../policy/types.js';
 import { GENESIS_HASH, computeHash, fsyncFile, readLastRecord, withAuditLock, } from './fs.js';
 import { maybeRotate } from '../gateway/audit/rotator.js';
+import { CODEX_REVIEW_SERVER_NAME, CODEX_REVIEW_TOOL_NAME } from './codex-event.js';
 const REA_DIR = '.rea';
 const AUDIT_FILE = 'audit.jsonl';
 /** Per-file write queue to preserve linear hash-chain order within a process. */
@@ -78,7 +79,7 @@ async function resolveBaseDir(baseDir) {
         return absolute;
     }
 }
-async function doAppend(resolvedBase, input) {
+async function doAppend(resolvedBase, input, emissionSource) {
     const reaDir = path.join(resolvedBase, REA_DIR);
     const auditFile = path.join(reaDir, AUDIT_FILE);
     await fs.mkdir(reaDir, { recursive: true });
@@ -100,6 +101,7 @@ async function doAppend(resolvedBase, input) {
             autonomy_level: input.autonomy_level ?? 'unknown',
             duration_ms: input.duration_ms ?? 0,
             prev_hash: effectivePrev,
+            emission_source: emissionSource,
         };
         if (input.error)
             recordBase.error = input.error;
@@ -111,20 +113,39 @@ async function doAppend(resolvedBase, input) {
         const hash = computeHash(recordBase);
         const record = { ...recordBase, hash };
         const line = JSON.stringify(record) + '\n';
+        // Defect T (0.10.2): serialization self-check. A valid AuditRecord + the
+        // trailing newline should always round-trip through JSON.parse, but we
+        // verify that invariant BEFORE the line touches the hash-chain file. A
+        // throw here aborts the append WITHOUT writing anything — the caller sees
+        // the failure and the on-disk chain tail is unchanged. This is
+        // defense-in-depth against the class of regression that would otherwise
+        // write an unparseable line to `.rea/audit.jsonl` and only surface at
+        // `rea audit verify` time (or, worse, when push-review-core.sh's jq scan
+        // silently fails to find a legitimate `codex.review` record past the
+        // corruption). The concrete failure modes guarded against:
+        //
+        //   - A future refactor introducing a non-JSON-safe field into
+        //     AuditRecord (BigInt, circular ref, undefined-in-array, etc.) that
+        //     slips past TypeScript.
+        //   - A hostile `metadata` value whose serialized form produces output
+        //     JSON.parse rejects (currently impossible given our input types,
+        //     but the check is cheap and the recovery cost is high).
+        try {
+            JSON.parse(line);
+        }
+        catch (e) {
+            throw new Error(`Audit append aborted: JSON.stringify produced an unparseable line ` +
+                `for tool_name=${JSON.stringify(record.tool_name)} ` +
+                `server_name=${JSON.stringify(record.server_name)}. ` +
+                `Underlying parser error: ${e.message}. ` +
+                `No data was written to ${auditFile}.`);
+        }
         await fs.appendFile(auditFile, line);
         await fsyncFile(auditFile);
         return record;
     });
 }
-/**
- * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a
- * hash chained against the tail of the existing log.
- *
- * @param baseDir - Repo/project root (the directory that contains `.rea/`).
- * @param input   - Event data. `tool_name` and `server_name` are required.
- * @returns The full written record, including the computed `hash`.
- */
-export async function appendAuditRecord(baseDir, input) {
+async function enqueueAppend(baseDir, input, emissionSource) {
     // Canonicalize the baseDir so every caller targeting the same on-disk
     // directory lands on the same queue key, regardless of whether they passed
     // `'.'`, `process.cwd()`, or a symlinked path. Without this, two callers in
@@ -139,7 +160,7 @@ export async function appendAuditRecord(baseDir, input) {
         /* previous write's error is owned by that caller */
     })
         .then(async () => {
-        record = await doAppend(resolvedBase, input);
+        record = await doAppend(resolvedBase, input, emissionSource);
     });
     writeQueues.set(key, next
         .finally(() => {
@@ -161,5 +182,52 @@ export async function appendAuditRecord(baseDir, input) {
     await next;
     return record;
 }
+/**
+ * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a
+ * hash chained against the tail of the existing log.
+ *
+ * ## emission_source (defect P)
+ *
+ * Records written through this public helper are ALWAYS stamped with
+ * `emission_source: "other"`. External consumers (Helix, ad-hoc scripts,
+ * plugins) have no way to self-assert `"rea-cli"` or `"codex-cli"` through
+ * this entry point — the parameter is not part of the public
+ * {@link AppendAuditInput} shape. Records emitted by the rea CLI itself use
+ * the dedicated {@link appendCodexReviewAuditRecord} helper, which is the
+ * ONLY path that stamps `"rea-cli"`.
+ *
+ * The push-review cache gate rejects `codex.review` records whose
+ * `emission_source` is `"other"` (or missing, for legacy records), so
+ * forging a `codex.review` record through this helper produces a line that
+ * is on the hash chain but does NOT satisfy the gate.
+ *
+ * @param baseDir - Repo/project root (the directory that contains `.rea/`).
+ * @param input   - Event data. `tool_name` and `server_name` are required.
+ * @returns The full written record, including the computed `hash`.
+ */
+export async function appendAuditRecord(baseDir, input) {
+    return enqueueAppend(baseDir, input, 'other');
+}
+/**
+ * Append a `tool_name: "codex.review"` audit record certifying that a Codex
+ * adversarial review ran on a specific commit SHA (defect P).
+ *
+ * This is the ONLY write path in `@bookedsolid/rea` that produces
+ * `emission_source: "rea-cli"` for `codex.review` records. Consumers MUST
+ * reach this helper through the `rea audit record codex-review` CLI (which
+ * is classified as a Write-tier Bash invocation by `reaCommandTier`, defect
+ * E). Any other code path calling the generic {@link appendAuditRecord}
+ * with `tool_name: "codex.review"` lands with `emission_source: "other"`
+ * and does NOT satisfy the push-review cache gate — closing the forgery
+ * surface that `.reports/hook-patches/emit-audit-*.mjs` scripts exploited
+ * before this patch.
+ *
+ * `tool_name` and `server_name` are fixed to the canonical values
+ * (`"codex.review"` / `"codex"`) and are NOT accepted as caller inputs —
+ * the type excludes them so the contract is self-documenting.
+ */
+export async function appendCodexReviewAuditRecord(baseDir, input) {
+    return enqueueAppend(baseDir, { ...input, tool_name: CODEX_REVIEW_TOOL_NAME, server_name: CODEX_REVIEW_SERVER_NAME }, 'rea-cli');
+}
 export { Tier, InvocationStatus } from '../policy/types.js';
 export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, } from './codex-event.js';

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 { appendCodexReviewAuditRecord, } 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
@@ -55,36 +59,83 @@ export async function runAuditRotate(_options) {
     console.log(`       A rotation marker anchors the new chain on the old tail's hash.`);
 }
 /**
- * Load a JSONL audit file as a record array + per-line raw text, so we can
- * re-hash against the exact serialization that was written. Throws on read
- * errors; returns an empty array for an empty file.
+ * Best-effort column extractor. Node's JSON.parse error messages include a
+ * `position N` that is a 0-based character offset into the parsed string.
+ * When we parse a single JSONL line, that offset maps directly to a column.
+ * Returns undefined when the position token is absent — the line number
+ * alone is still useful.
+ */
+function extractColumnFromParserError(message) {
+    const m = /position (\d+)/.exec(message);
+    if (m === null)
+        return undefined;
+    const n = Number.parseInt(m[1] ?? '', 10);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return n + 1;
+}
+/**
+ * Load a JSONL audit file as a record array + per-line raw text + a list of
+ * per-line parse failures, so we can re-hash against the exact serialization
+ * that was written AND report every malformed line in one pass (defect T).
+ *
+ * Unparseable lines are a DISTINCT failure class from hash-chain tampers:
+ *
+ *   - Malformed lines are collected into `parseFailures` and dropped from
+ *     `records`. `rawLines` still contains the full original line array, so
+ *     callers can cross-reference. `recordLineMap[i]` holds the 1-based file
+ *     line number of `records[i]`.
+ *   - The chain-verify pass runs only over the parseable subset. A caller
+ *     that wants to report the verification result as partial checks
+ *     `parseFailures.length > 0`.
+ *
+ * Throws only on read errors; returns an empty shape for an empty file.
  */
 async function loadRecords(filePath) {
     const raw = await fs.readFile(filePath, 'utf8');
     // Drop a single trailing newline but preserve blank lines inside the file
     // so index numbers line up with real record positions.
     const trimmedTail = raw.replace(/\n$/, '');
-    if (trimmedTail.length === 0)
-        return { records: [], rawLines: [] };
+    if (trimmedTail.length === 0) {
+        return { records: [], recordLineMap: [], rawLines: [], parseFailures: [] };
+    }
     const rawLines = trimmedTail.split('\n');
-    const records = rawLines.map((line, i) => {
+    const records = [];
+    const recordLineMap = [];
+    const parseFailures = [];
+    const basename = path.basename(filePath);
+    for (let i = 0; i < rawLines.length; i++) {
+        const line = rawLines[i];
+        // Empty lines mid-file are not records but also not parseable — JSON.parse('')
+        // throws. Treat as a parse failure so verify surfaces them explicitly.
         try {
-            return JSON.parse(line);
+            const parsed = JSON.parse(line);
+            records.push(parsed);
+            recordLineMap.push(i + 1);
         }
         catch (e) {
-            throw new Error(`Cannot parse JSON at ${path.basename(filePath)} line ${i + 1}: ${e.message}`);
+            const msg = e.message;
+            const col = extractColumnFromParserError(msg);
+            parseFailures.push({
+                file: basename,
+                lineNumber: i + 1,
+                ...(col !== undefined ? { column: col } : {}),
+                message: msg,
+            });
         }
-    });
-    return { records, rawLines };
+    }
+    return { records, recordLineMap, rawLines, parseFailures };
 }
-function verifyChain(fileBasename, records, expectedStartPrev) {
+function verifyChain(fileBasename, records, recordLineMap, expectedStartPrev) {
     let prev = expectedStartPrev;
     for (let i = 0; i < records.length; i++) {
         const r = records[i];
+        const fileLineNumber = recordLineMap[i] ?? i + 1;
         if (r.prev_hash !== prev) {
             return {
                 file: fileBasename,
-                lineIndex: i,
+                recordIndex: i,
+                fileLineNumber,
                 reason: 'prev_hash does not match previous record',
                 expected: prev,
                 actual: r.prev_hash,
@@ -97,7 +148,8 @@ function verifyChain(fileBasename, records, expectedStartPrev) {
         if (recomputed !== hash) {
             return {
                 file: fileBasename,
-                lineIndex: i,
+                recordIndex: i,
+                fileLineNumber,
                 reason: 'stored hash does not match recomputed hash over record body',
                 expected: recomputed,
                 actual: hash,
@@ -170,36 +222,151 @@ export async function runAuditVerify(options) {
         console.error(`       Expected: ${path.relative(baseDir, currentAudit)}`);
         process.exit(1);
     }
+    // Defect T (0.10.2): collect-all-errors mode. We no longer abort at the
+    // first unparseable line — `rea audit verify` now walks every file, lists
+    // EVERY malformed line with its number + parser message, and attempts
+    // chain verification over the parseable subset. Unparseable lines are a
+    // distinct failure class from hash-chain tampers; both contribute to a
+    // non-zero exit, but they are reported separately so an operator can tell
+    // "JSONL corruption" from "someone edited a hash".
     let expectedPrev = GENESIS_HASH;
     let totalRecords = 0;
+    const allParseFailures = [];
+    let chainFailure = null;
+    let chainFailureFile = null;
     for (const filePath of filesToVerify) {
-        let records;
+        let loaded;
         try {
-            ({ records } = await loadRecords(filePath));
+            loaded = await loadRecords(filePath);
         }
         catch (e) {
             err(`${e.message}`);
             process.exit(1);
         }
-        const basename = path.basename(filePath);
-        const failure = verifyChain(basename, records, expectedPrev);
-        if (failure !== null) {
-            err(`Audit chain TAMPER DETECTED in ${failure.file}`);
-            console.error(`       Record index:  ${failure.lineIndex} (0-based within file)`);
-            console.error(`       Reason:        ${failure.reason}`);
-            if (failure.expected !== undefined) {
-                console.error(`       Expected:      ${failure.expected}`);
+        const { records, recordLineMap, parseFailures } = loaded;
+        allParseFailures.push(...parseFailures);
+        // Chain verify over the parseable subset only. If an earlier file had a
+        // chain failure we stop verifying further files — advancing `expectedPrev`
+        // past an unknown tail would produce misleading secondary failures.
+        // recordLineMap threads the 1-based original-file line number through so
+        // the failure diagnostic names the editor/jq position directly, not the
+        // parseable-subset index which diverges from the file whenever a
+        // malformed line precedes the tamper.
+        if (chainFailure === null) {
+            const failure = verifyChain(path.basename(filePath), records, recordLineMap, expectedPrev);
+            if (failure !== null) {
+                chainFailure = failure;
+                chainFailureFile = filePath;
             }
-            if (failure.actual !== undefined) {
-                console.error(`       Actual:        ${failure.actual}`);
+            else if (records.length > 0) {
+                expectedPrev = records[records.length - 1].hash;
             }
-            process.exit(1);
-        }
-        // Advance the cross-file anchor for the next file.
-        if (records.length > 0) {
-            expectedPrev = records[records.length - 1].hash;
         }
         totalRecords += records.length;
     }
+    // Report parse failures first — they're independent of the chain result.
+    if (allParseFailures.length > 0) {
+        err(`Audit verify: ${allParseFailures.length} unparseable line(s) detected. ` +
+            `Chain verification was performed over the parseable subset only.`);
+        for (const f of allParseFailures) {
+            const loc = f.column !== undefined
+                ? `${f.file}:${f.lineNumber}:${f.column}`
+                : `${f.file}:${f.lineNumber}`;
+            console.error(`       ${loc}  ${f.message}`);
+        }
+    }
+    // Then report any chain failure found on the parseable subset.
+    if (chainFailure !== null) {
+        err(`Audit chain TAMPER DETECTED in ${chainFailure.file}`);
+        // File-line-number is the operator-facing anchor — jump straight to the
+        // offending line with `sed -n "${n}p" audit.jsonl` or editor:LINE. The
+        // parseable-subset index is kept for audit-tooling consumers that walk
+        // the records[] array.
+        console.error(`       File line:     ${chainFailure.fileLineNumber} (1-based in ${chainFailure.file})`);
+        console.error(`       Record index:  ${chainFailure.recordIndex} (0-based within parseable subset)`);
+        console.error(`       Reason:        ${chainFailure.reason}`);
+        if (chainFailure.expected !== undefined) {
+            console.error(`       Expected:      ${chainFailure.expected}`);
+        }
+        if (chainFailure.actual !== undefined) {
+            console.error(`       Actual:        ${chainFailure.actual}`);
+        }
+        if (chainFailureFile !== null) {
+            console.error(`       File path:     ${path.relative(baseDir, chainFailureFile)}`);
+        }
+    }
+    if (allParseFailures.length > 0 || chainFailure !== null) {
+        process.exit(1);
+    }
     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;
+    }
+    // Defect P: stamps emission_source: "rea-cli" so the record satisfies the
+    // push-review gate's new integrity predicate. Legacy records (without
+    // emission_source) and records written through the generic
+    // appendAuditRecord() helper (emission_source: "other") are rejected.
+    // tool_name/server_name are fixed inside the helper.
+    await appendCodexReviewAuditRecord(baseDir, {
+        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}).`);
+    }
+}