@bookedsolid/rea 0.10.0 → 0.10.2

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(),