@bookedsolid/rea 0.9.4 → 0.10.1

package/dist/cli/cache.d.ts

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

package/dist/cli/cache.js

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

package/dist/cli/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

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

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

package/dist/config/tier-map.js

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

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