@bookedsolid/rea 0.10.0 → 0.10.1

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.js

@@ -13,7 +13,7 @@
 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 { 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';
@@ -59,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,
@@ -101,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,
@@ -174,37 +222,82 @@ 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.`);
 }
 /**
@@ -253,9 +346,12 @@ export async function runAuditRecordCodexReview(options) {
     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,
+    // 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 } : {}),

package/dist/cli/doctor.js

@@ -103,7 +103,7 @@ export async function checkFingerprintStore(baseDir) {
     return {
         label,
         status: 'warn',
-        detail: `${parts.join(', ')} — next \`rea serve\` will block drift (set REA_ACCEPT_DRIFT=<name> to accept)`,
+        detail: `${parts.join(', ')} — next \`rea serve\` will block drift (run \`rea tofu list\` for detail, \`rea tofu accept <name>\` to rebase after a legitimate registry edit)`,
     };
 }
 function checkRegistryParses(baseDir, registryPath) {

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import { runFreeze, runUnfreeze } from './freeze.js';
 import { runInit } from './init.js';
 import { runServe } from './serve.js';
 import { runStatus } from './status.js';
+import { runTofuAccept, runTofuList } from './tofu.js';
 import { runUpgrade } from './upgrade.js';
 import { err, getPkgVersion } from './utils.js';
 async function main() {
@@ -180,6 +181,23 @@ async function main() {
         .action(async (opts) => {
         await runCacheList({ ...(opts.branch !== undefined ? { branch: opts.branch } : {}) });
     });
+    const tofu = program
+        .command('tofu')
+        .description('TOFU fingerprint operations (G7) — inspect and rebase `.rea/fingerprints.json` when a legitimate registry edit has triggered drift fail-close. Emits audit records.');
+    tofu
+        .command('list')
+        .description('Print every server declared in `.rea/registry.yaml` with its current-vs-stored fingerprint verdict (first-seen | unchanged | drifted).')
+        .option('--json', 'emit JSON instead of the human-readable table')
+        .action(async (opts) => {
+        await runTofuList({ ...(opts.json === true ? { json: true } : {}) });
+    });
+    tofu
+        .command('accept <name>')
+        .description('Rebase the stored fingerprint for <name> to match the current canonical shape in `.rea/registry.yaml`. Use after a deliberate registry edit (vault added, command path renamed, env-key set changed). Emits a `tofu.drift_accepted_by_cli` audit record; next `rea serve` will classify as unchanged.')
+        .option('--reason <text>', 'free-text note captured in the audit record (recommended when accepting drift — explains WHY the canonical shape changed)')
+        .action(async (name, opts) => {
+        await runTofuAccept({ name, ...(opts.reason !== undefined ? { reason: opts.reason } : {}) });
+    });
     program
         .command('doctor')
         .description('Validate the install: policy parses, .rea/ layout, hooks, Codex plugin.')

package/dist/cli/tofu.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `rea tofu` — operator-facing recovery surface for TOFU fingerprint drift
+ * (defect S).
+ *
+ * The TOFU gate in `src/registry/tofu-gate.ts` fail-closes on drift: an
+ * enabled downstream whose canonical fingerprint no longer matches the stored
+ * baseline is silently dropped from the spawn set. The only documented
+ * recovery path used to be `REA_ACCEPT_DRIFT=<name>` as a startup env var,
+ * which is useless when the gateway is spawned indirectly (e.g. by Claude
+ * Code via `.mcp.json`) — there is no operator-reachable env in that path.
+ *
+ * This module provides two verbs:
+ *
+ *   - `list`            — print every declared server's current-vs-stored
+ *                         fingerprint verdict so the operator can see drift
+ *                         before reaching for `accept`.
+ *   - `accept <name>`   — recompute the current fingerprint for `<name>` and
+ *                         write it to `.rea/fingerprints.json`. Emits a
+ *                         `tofu.drift_accepted_by_cli` audit record so the
+ *                         action is on the hash chain.
+ *
+ * Both verbs are pure CLI surface — they do NOT speak to a running `rea
+ * serve`. The next gateway boot re-runs `applyTofuGate` against the updated
+ * store and classifies the server as `unchanged` with no banner.
+ *
+ * ## Trust model
+ *
+ * `accept` updates the stored baseline to match whatever the YAML currently
+ * says. It is a **deliberate operator action**: anyone who can run `rea`
+ * could already edit `.rea/fingerprints.json` by hand. The CLI is an
+ * audit-recording wrapper over that capability, not a privilege expansion.
+ *
+ * The audit record captures BOTH fingerprints (stored + current) and the
+ * registry canonical shape at accept-time, so a forensic re-hash of the
+ * registry after the fact can confirm the operator accepted the shape they
+ * intended to accept.
+ */
+import type { RegistryServer } from '../registry/types.js';
+export type TofuVerdictLabel = 'first-seen' | 'unchanged' | 'drifted';
+export interface TofuRow {
+    name: string;
+    enabled: boolean;
+    current: string;
+    stored: string | undefined;
+    verdict: TofuVerdictLabel;
+}
+/** Pure classifier used by both `list` and `accept` — keep free of I/O. */
+export declare function classifyRows(servers: RegistryServer[], stored: Record<string, string>): TofuRow[];
+export interface RunTofuListOptions {
+    json?: boolean;
+}
+export declare function runTofuList(options?: RunTofuListOptions): Promise<void>;
+export interface RunTofuAcceptOptions {
+    name: string;
+    reason?: string;
+}
+export declare function runTofuAccept(options: RunTofuAcceptOptions): Promise<void>;

package/dist/cli/tofu.js

@@ -0,0 +1,134 @@
+/**
+ * `rea tofu` — operator-facing recovery surface for TOFU fingerprint drift
+ * (defect S).
+ *
+ * The TOFU gate in `src/registry/tofu-gate.ts` fail-closes on drift: an
+ * enabled downstream whose canonical fingerprint no longer matches the stored
+ * baseline is silently dropped from the spawn set. The only documented
+ * recovery path used to be `REA_ACCEPT_DRIFT=<name>` as a startup env var,
+ * which is useless when the gateway is spawned indirectly (e.g. by Claude
+ * Code via `.mcp.json`) — there is no operator-reachable env in that path.
+ *
+ * This module provides two verbs:
+ *
+ *   - `list`            — print every declared server's current-vs-stored
+ *                         fingerprint verdict so the operator can see drift
+ *                         before reaching for `accept`.
+ *   - `accept <name>`   — recompute the current fingerprint for `<name>` and
+ *                         write it to `.rea/fingerprints.json`. Emits a
+ *                         `tofu.drift_accepted_by_cli` audit record so the
+ *                         action is on the hash chain.
+ *
+ * Both verbs are pure CLI surface — they do NOT speak to a running `rea
+ * serve`. The next gateway boot re-runs `applyTofuGate` against the updated
+ * store and classifies the server as `unchanged` with no banner.
+ *
+ * ## Trust model
+ *
+ * `accept` updates the stored baseline to match whatever the YAML currently
+ * says. It is a **deliberate operator action**: anyone who can run `rea`
+ * could already edit `.rea/fingerprints.json` by hand. The CLI is an
+ * audit-recording wrapper over that capability, not a privilege expansion.
+ *
+ * The audit record captures BOTH fingerprints (stored + current) and the
+ * registry canonical shape at accept-time, so a forensic re-hash of the
+ * registry after the fact can confirm the operator accepted the shape they
+ * intended to accept.
+ */
+import { appendAuditRecord } from '../audit/append.js';
+import { InvocationStatus, Tier } from '../policy/types.js';
+import { fingerprintServer } from '../registry/fingerprint.js';
+import { FINGERPRINT_STORE_VERSION, loadFingerprintStore, saveFingerprintStore, } from '../registry/fingerprints-store.js';
+import { loadRegistry } from '../registry/loader.js';
+import { err, log } from './utils.js';
+/** Pure classifier used by both `list` and `accept` — keep free of I/O. */
+export function classifyRows(servers, stored) {
+    return servers.map((s) => {
+        const current = fingerprintServer(s);
+        const prior = stored[s.name];
+        let verdict;
+        if (prior === undefined)
+            verdict = 'first-seen';
+        else if (prior === current)
+            verdict = 'unchanged';
+        else
+            verdict = 'drifted';
+        return {
+            name: s.name,
+            enabled: s.enabled !== false,
+            current,
+            stored: prior,
+            verdict,
+        };
+    });
+}
+export async function runTofuList(options = {}) {
+    const baseDir = process.cwd();
+    const registry = loadRegistry(baseDir);
+    const store = await loadFingerprintStore(baseDir);
+    const rows = classifyRows(registry.servers, store.servers);
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify({ servers: rows }, null, 2) + '\n');
+        return;
+    }
+    if (rows.length === 0) {
+        log('No servers declared in .rea/registry.yaml.');
+        return;
+    }
+    log('TOFU fingerprint status:');
+    log('');
+    for (const row of rows) {
+        const shortCur = row.current.slice(0, 12);
+        const shortPrior = row.stored !== undefined ? row.stored.slice(0, 12) : '—';
+        const flag = row.enabled ? '' : ' (disabled)';
+        log(`  ${row.verdict.padEnd(10)} ${row.name.padEnd(20)} stored=${shortPrior}  current=${shortCur}${flag}`);
+    }
+    log('');
+    const drifted = rows.filter((r) => r.verdict === 'drifted');
+    if (drifted.length > 0) {
+        log(`  ${drifted.length} drifted — run \`rea tofu accept <name>\` to rebase the stored fingerprint (emits an audit record).`);
+    }
+}
+export async function runTofuAccept(options) {
+    const baseDir = process.cwd();
+    const registry = loadRegistry(baseDir);
+    const server = registry.servers.find((s) => s.name === options.name);
+    if (server === undefined) {
+        err(`Server "${options.name}" is not declared in .rea/registry.yaml. Run \`rea tofu list\` to see declared servers.`);
+        process.exit(1);
+    }
+    const current = fingerprintServer(server);
+    const store = await loadFingerprintStore(baseDir);
+    const stored = store.servers[server.name];
+    if (stored === current) {
+        log(`tofu: "${server.name}" already matches stored fingerprint (${current.slice(0, 12)}…) — no change written.`);
+        return;
+    }
+    const nextStore = {
+        version: FINGERPRINT_STORE_VERSION,
+        servers: { ...store.servers, [server.name]: current },
+    };
+    await saveFingerprintStore(baseDir, nextStore);
+    const event = stored === undefined ? 'tofu.first_seen_accepted_by_cli' : 'tofu.drift_accepted_by_cli';
+    try {
+        await appendAuditRecord(baseDir, {
+            tool_name: 'rea.tofu',
+            server_name: 'rea',
+            tier: Tier.Write,
+            status: InvocationStatus.Allowed,
+            metadata: {
+                event,
+                server: server.name,
+                stored_fingerprint: stored ?? null,
+                current_fingerprint: current,
+                ...(options.reason !== undefined ? { reason: options.reason } : {}),
+            },
+        });
+    }
+    catch (auditErr) {
+        err(`tofu: fingerprint updated, but audit append failed — operator MUST investigate: ${auditErr instanceof Error ? auditErr.message : String(auditErr)}`);
+        process.exit(2);
+    }
+    const shortPrior = stored !== undefined ? stored.slice(0, 12) : '(first-seen)';
+    log(`tofu: accepted "${server.name}" — stored=${shortPrior} → current=${current.slice(0, 12)}. Next \`rea serve\` will classify as unchanged.`);
+}

package/dist/gateway/audit/rotator.js

@@ -237,6 +237,10 @@ export async function performRotation(auditFile, now = new Date()) {
             autonomy_level: 'system',
             duration_ms: 0,
             prev_hash: tailHash,
+            // Defect P: rotation markers are written by rea itself, not by an
+            // external caller of appendAuditRecord() — tag as rea-cli so the
+            // hash chain remains consistent under the post-P schema.
+            emission_source: 'rea-cli',
             metadata: {
                 rotated_from: path.basename(rotatedPath),
                 rotated_at: now.toISOString(),

package/dist/gateway/middleware/audit-types.d.ts

@@ -1,4 +1,31 @@
 import type { Tier, InvocationStatus } from '../../policy/types.js';
+/**
+ * Emission-path discriminator for the audit record (defect P).
+ *
+ * The push-review gate trusts `tool_name: "codex.review"` records to certify
+ * a real Codex adversarial review ran on the given commit SHA. Before this
+ * field existed, any script with filesystem access to `node_modules` could
+ * call `appendAuditRecord(...)` with a `codex.review` tool name and forge
+ * the certification — the governance promise was a convention, not enforced.
+ *
+ * `emission_source` tags the code path that wrote the record:
+ *
+ *   - `"rea-cli"`   — emitted by the `rea` CLI itself (e.g. `rea audit
+ *                     record codex-review`). The rea CLI is classified by
+ *                     `reaCommandTier()` (defect E) and is an audited,
+ *                     policy-governed entry point.
+ *   - `"codex-cli"` — emitted by the Codex adversarial review path itself,
+ *                     the authoritative source.
+ *   - `"other"`     — every other caller of the public
+ *                     `appendAuditRecord()` helper (consumer plugins,
+ *                     ad-hoc scripts, tests). Legitimate for event types
+ *                     OTHER than `codex.review`; REJECTED by the
+ *                     push-review cache gate for `codex.review` lookups.
+ *
+ * The field is part of the hashed record body — it cannot be altered after
+ * the fact without breaking the chain.
+ */
+export type EmissionSource = 'rea-cli' | 'codex-cli' | 'other';
 export interface AuditRecord {
     timestamp: string;
     session_id: string;
@@ -21,6 +48,14 @@ export interface AuditRecord {
      * the redaction middleware runs on `ctx.arguments`, not on metadata.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Defect P (0.10.1). Discriminates the emission path: `"rea-cli"` for
+     * rea's own CLI, `"codex-cli"` for the Codex adversarial reviewer,
+     * `"other"` for every other caller of the public audit helper. Required
+     * field; the push-review gate refuses to accept `codex.review` records
+     * whose source is `"other"` (or missing, for pre-0.10.1 legacy records).
+     */
+    emission_source: EmissionSource;
     hash: string;
     prev_hash: string;
 }

package/dist/gateway/middleware/audit.js

@@ -95,6 +95,12 @@ metrics) {
                         autonomy_level: autonomyLevel,
                         duration_ms,
                         prev_hash: prevHash,
+                        // Defect P: gateway middleware records every proxied tool call.
+                        // rea itself is the writer — tag as rea-cli so the schema is
+                        // consistent. "rea-cli" here is a misnomer (the gateway isn't a
+                        // CLI) but is part of the stable 0.10.1 discriminator set;
+                        // semantically it means "written by @bookedsolid/rea itself".
+                        emission_source: 'rea-cli',
                     };
                     if (ctx.error) {
                         recordBase.error = ctx.error;

package/dist/registry/tofu-gate.js

@@ -141,7 +141,10 @@ async function emitSideEffects(baseDir, c, log) {
         boxLine(` current: ${c.current.slice(0, 16)}…`),
         boxLine(''),
         boxLine(' The server will NOT connect. Other servers remain up.'),
-        boxLine(' To accept (once):  REA_ACCEPT_DRIFT=<name> rea serve'),
+        boxLine(' After a legitimate registry edit:'),
+        boxLine(`   rea tofu accept ${c.server} --reason "<why>"`),
+        boxLine(' One-shot bypass (not recommended):'),
+        boxLine(`   REA_ACCEPT_DRIFT=${c.server} rea serve`),
         `  ╚${'═'.repeat(BOX_INNER_WIDTH)}╝`,
         '',
     ].join('\n'));

package/hooks/_lib/push-review-core.sh

@@ -719,12 +719,20 @@ pr_core_run() {
   # fail-closed and require an explicit review.
   local SOURCE_SHA="" MERGE_BASE="" TARGET_BRANCH="" SOURCE_REF=""
   local HAS_DELETE=0 BEST_COUNT=0
-  local rec local_sha remote_sha local_ref remote_ref target mb mb_status count count_status
+  local rec local_sha remote_sha local_ref remote_ref target resolved_base mb mb_status count count_status
   for rec in "${REFSPEC_RECORDS[@]}"; do
     IFS='|' read -r local_sha remote_sha local_ref remote_ref <<<"$rec"
     target="${remote_ref#refs/heads/}"
     target="${target#refs/for/}"
     [[ -z "$target" ]] && target="main"
+    # Defect N: track the SEMANTIC base (the ref the diff was anchored on)
+    # distinctly from `target` (the pushed remote ref). For a tracked branch
+    # they coincide; for a new branch, `target` is the branch name being
+    # created — which is NOT what we reviewed against, so `Target:` must
+    # echo `resolved_base` instead. Default to `target` for the tracked
+    # case; the new-branch path overrides with the resolved default_ref
+    # short name below.
+    resolved_base="$target"
 
     if [[ "$local_sha" == "$ZERO_SHA" ]]; then
       HAS_DELETE=1
@@ -774,25 +782,81 @@ pr_core_run() {
       #
       # argv_remote is set from the adapter's argv (git passes the remote name
       # as $1 on pre-push); defaults to "origin" when absent (BUG-008 sniff).
-      local default_ref default_ref_status
-      default_ref=$(cd "$REA_ROOT" && git symbolic-ref "refs/remotes/${argv_remote}/HEAD" 2>/dev/null)
-      default_ref_status=$?
-      if [[ "$default_ref_status" -ne 0 || -z "$default_ref" ]]; then
-        # symbolic-ref failed (common on shallow or mirror clones where
-        # origin/HEAD was never set). Probe the common default-branch names in
-        # order: main, then master. Both are remote-tracking refs and still
-        # server-authoritative; the order matters only for projects that still
-        # default to `master` (older internal forks), where without this
-        # fallback the first push of a new branch would fail closed.
-        if cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/remotes/${argv_remote}/main" >/dev/null 2>&1; then
-          default_ref="refs/remotes/${argv_remote}/main"
-        elif cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/remotes/${argv_remote}/master" >/dev/null 2>&1; then
-          default_ref="refs/remotes/${argv_remote}/master"
-        else
-          default_ref=""
+      #
+      # Defect N (0.10.1): BEFORE falling back to the remote's default branch,
+      # consult per-branch config `branch.<source>.base`. A feature branch
+      # targeting `dev` in a main-as-production repo would otherwise resolve
+      # against `origin/main` silently, producing a diff that spans the entire
+      # dev→main history — reviewers see "Scope: 28690 lines" for a 4-file
+      # change. The git-config route uses local branch knowledge that is
+      # authoritative for this working copy (set via `git branch --set-upstream`,
+      # or by CI tooling that tracks the intended target). This is consulted
+      # BEFORE origin/HEAD because the latter is a server-default that may
+      # mis-represent the reviewer's actual intent for this specific branch.
+      local default_ref default_ref_status configured_base source_branch
+      source_branch="${local_ref#refs/heads/}"
+      default_ref=""
+      # Codex 0.10.1 finding #1: `local` is function-scoped, not loop-
+      # iteration-scoped — without an explicit reset, iteration N inherits
+      # iteration N-1's configured_base and falsely promotes resolved_base
+      # when the current refspec's local_ref does NOT begin with refs/heads/
+      # (tag push, gerrit-style refs/for/, etc.). Reset before every
+      # potential assignment so each iteration sees a clean slate.
+      configured_base=""
+
+      if [[ -n "$source_branch" && "$source_branch" != "HEAD" ]]; then
+        configured_base=$(cd "$REA_ROOT" && git config --get "branch.${source_branch}.base" 2>/dev/null || echo "")
+        if [[ -n "$configured_base" ]]; then
+          # Prefer the REMOTE-TRACKING form so the gate still anchors on a
+          # server-authoritative ref (see the local-ref hijack explanation
+          # above). Fall back to the local short ref only if the remote
+          # counterpart doesn't exist, with a visible WARN on stderr — the
+          # local ref is less trustworthy and the reviewer should know.
+          if cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/remotes/${argv_remote}/${configured_base}" >/dev/null 2>&1; then
+            default_ref="refs/remotes/${argv_remote}/${configured_base}"
+          elif cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/heads/${configured_base}" >/dev/null 2>&1; then
+            default_ref="refs/heads/${configured_base}"
+            printf 'WARN: branch.%s.base=%s resolved to local ref; remote counterpart %s/%s missing — reviewer-side diff may be stale\n' \
+              "$source_branch" "$configured_base" "$argv_remote" "$configured_base" >&2
+          fi
+        fi
+      fi
+
+      if [[ -z "$default_ref" ]]; then
+        default_ref=$(cd "$REA_ROOT" && git symbolic-ref "refs/remotes/${argv_remote}/HEAD" 2>/dev/null)
+        default_ref_status=$?
+        if [[ "$default_ref_status" -ne 0 || -z "$default_ref" ]]; then
+          # symbolic-ref failed (common on shallow or mirror clones where
+          # origin/HEAD was never set). Probe the common default-branch names in
+          # order: main, then master. Both are remote-tracking refs and still
+          # server-authoritative; the order matters only for projects that still
+          # default to `master` (older internal forks), where without this
+          # fallback the first push of a new branch would fail closed.
+          if cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/remotes/${argv_remote}/main" >/dev/null 2>&1; then
+            default_ref="refs/remotes/${argv_remote}/main"
+          elif cd "$REA_ROOT" && git rev-parse --verify --quiet "refs/remotes/${argv_remote}/master" >/dev/null 2>&1; then
+            default_ref="refs/remotes/${argv_remote}/master"
+          else
+            default_ref=""
+          fi
         fi
       fi
       if [[ -n "$default_ref" ]]; then
+        # Defect N: if operator-configured `branch.<source>.base` resolved the
+        # ref we're about to diff against, overwrite `resolved_base` with the
+        # short name so TARGET_BRANCH (and the Target: label) reflect the
+        # actual review anchor. Without an explicit config override, leave
+        # `resolved_base` at the refspec target — this preserves the cache
+        # contract for new-branch pushes where remote_ref is the same as the
+        # source branch (the common case) and for bare pushes that
+        # argv-resolve via `@{upstream}`. Only operators who opted into a
+        # per-branch base get the label promoted, keeping the change
+        # backward-compatible for every other path.
+        if [[ -n "$configured_base" ]]; then
+          resolved_base="${default_ref#refs/remotes/${argv_remote}/}"
+          resolved_base="${resolved_base#refs/heads/}"
+          [[ -z "$resolved_base" ]] && resolved_base="$default_ref"
+        fi
         mb=$(cd "$REA_ROOT" && git merge-base "$default_ref" "$local_sha" 2>/dev/null || echo "")
         if [[ -z "$mb" ]]; then
           # default_ref resolved but merge-base came back empty (unrelated
@@ -867,13 +931,40 @@ pr_core_run() {
         if [[ "$CODEX_WAIVER_ACTIVE" == "1" ]]; then
           _codex_ok=1
         elif [[ -f "$_audit" ]]; then
-          if jq -e --arg sha "$local_sha" '
-              select(
-                .tool_name == "codex.review"
-                and .metadata.head_sha == $sha
-                and (.metadata.verdict == "pass" or .metadata.verdict == "concerns")
-              )
-            ' "$_audit" >/dev/null 2>&1; then
+          # Defect P (0.10.1): require .emission_source == "rea-cli" or
+          # "codex-cli" so agents cannot forge a codex.review record by
+          # directly calling appendAuditRecord() from an ad-hoc .mjs script
+          # (the generic helper stamps "other"). Legacy records (pre-0.10.1)
+          # have no emission_source field and are rejected — the first push
+          # on an upgraded consumer requires a fresh `rea audit record
+          # codex-review` (or Codex CLI emission) which stamps "rea-cli".
+          #
+          # Defect T/U (0.10.2): read the audit file as raw lines and parse
+          # each with `fromjson?`. Before 0.10.2 this scan used
+          # `jq -e '<filter>' "$_audit"` which feeds the file as a single
+          # JSON stream — a single malformed line (literal backslash-u
+          # followed by non-hex characters inside a string, for example)
+          # makes jq bail on the stream with exit 2 and the `select` never
+          # runs against ANY record, including legitimate codex.review
+          # entries further down the file. The failure is total: every
+          # cached codex.review receipt becomes unreachable until the
+          # corrupt line is hand-edited out. `-R` flips jq into raw-input
+          # mode (one string per line), and `fromjson?` is the error-
+          # suppressing parser — malformed lines silently yield empty
+          # output. The `select` filter then inspects each successfully
+          # parsed record exactly as before, and `grep -q .` detects
+          # whether ANY record survived the filter. Lines 1107 and the
+          # earlier cache_result scans at :432/:612 operate on a single
+          # printf'd JSON string, not audit.jsonl, so they remain `jq -e`.
+          if jq -R --arg sha "$local_sha" '
+              fromjson?
+              | select(
+                  .tool_name == "codex.review"
+                  and .metadata.head_sha == $sha
+                  and (.metadata.verdict == "pass" or .metadata.verdict == "concerns")
+                  and (.emission_source == "rea-cli" or .emission_source == "codex-cli")
+                )
+            ' "$_audit" 2>/dev/null | grep -q .; then
             _codex_ok=1
           fi
         fi
@@ -918,7 +1009,12 @@ pr_core_run() {
     if [[ -z "$SOURCE_SHA" ]] || [[ "$count" -gt "$BEST_COUNT" ]]; then
       SOURCE_SHA="$local_sha"
       MERGE_BASE="$mb"
-      TARGET_BRANCH="$target"
+      # Defect N: use `resolved_base` (the actual merge-base anchor we
+      # diffed against), not `target` (the pushed-ref name). For tracked
+      # branches these are the same; for new branches without an upstream
+      # the distinction is the difference between "Target: <source-branch>"
+      # (misleading) and "Target: main" (or whichever base was resolved).
+      TARGET_BRANCH="$resolved_base"
       SOURCE_REF="$local_ref"
       BEST_COUNT="$count"
     fi

package/package.json

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