@bookedsolid/rea 0.25.0 → 0.26.1

package/dist/cli/preflight.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `rea preflight` — local-first enforcement workhorse (0.26.0+).
+ *
+ * Called by:
+ *   - The husky pre-push template (`exec rea preflight --strict`)
+ *   - The Bash-tier `local-review-gate.sh` PreToolUse hook
+ *   - Operators directly (`rea preflight` to check status)
+ *
+ * Decision flow:
+ *
+ *   1. `policy.review.local_review.mode === 'off'` → exit 0 (no-op)
+ *   2. `<bypass_env_var>` is set (default REA_SKIP_LOCAL_REVIEW) → audit
+ *      `rea.local_review.skipped_override` with the reason; exit 0
+ *   3. `--no-review-check` flag → audit `rea.preflight.review_skipped`;
+ *      proceed to commit-count check only
+ *   4. Tail `.rea/audit.jsonl` for a `rea.local_review` (or back-compat
+ *      `codex.review`) entry with `metadata.head_sha === <git HEAD>`
+ *      AND `now - timestamp < max_age_seconds`. Found → exit 0.
+ *      Missing → exit 2 with helpful message.
+ *   5. Commit-count check (independent of step 4):
+ *        `git rev-list --count <base>..HEAD` against thresholds
+ *        from `policy.commit_hygiene`.
+ *
+ * Exit codes:
+ *
+ *   0 — clean (mode=off, recent review found, or override set)
+ *   1 — warn (commit count > warn_at_commits but ≤ refuse_at_commits)
+ *   2 — refuse (no recent review covering HEAD, OR commit count >
+ *       refuse_at_commits, OR --strict elevated a warn to refuse)
+ */
+import type { Command } from 'commander';
+import { type Policy } from '../policy/types.js';
+/** Default max age for a local-review audit entry (24h). */
+export declare const DEFAULT_MAX_AGE_SECONDS = 86400;
+/** Default bypass env-var name. */
+export declare const DEFAULT_BYPASS_ENV_VAR = "REA_SKIP_LOCAL_REVIEW";
+/** Default commit-hygiene thresholds. */
+export declare const DEFAULT_WARN_AT_COMMITS = 1;
+export declare const DEFAULT_REFUSE_AT_COMMITS = 5;
+export interface RunPreflightOptions {
+    /**
+     * Treat warn-tier commit-hygiene findings as refusals. Husky pre-push
+     * always sets this — a warn that doesn't refuse is a useless warning
+     * at the terminal layer.
+     */
+    strict?: boolean;
+    /**
+     * Skip the audit-log check. The commit-count check still runs. Used
+     * by operators who explicitly want to defer review (audit-logged so
+     * the deferral is forensically visible).
+     */
+    noReviewCheck?: boolean;
+    /** Emit a single JSON line on stdout instead of pretty output. */
+    json?: boolean;
+}
+interface PreflightOutcome {
+    status: 'clean' | 'warn' | 'refuse';
+    reason: string;
+    exitCode: 0 | 1 | 2;
+    details: Record<string, unknown>;
+}
+/**
+ * Run preflight in-process. Tests drive this directly. The CLI binding
+ * exits via `process.exit` at the end of `runPreflight()`.
+ */
+export declare function computePreflight(baseDir: string, options: RunPreflightOptions, env?: NodeJS.ProcessEnv): Promise<{
+    outcome: PreflightOutcome;
+    policy: Policy | undefined;
+}>;
+export declare function runPreflight(options: RunPreflightOptions): Promise<void>;
+/**
+ * Tail `.rea/audit.jsonl` for the most recent matching local-review
+ * entry. We accept BOTH `rea.local_review` (canonical) and
+ * `codex.review` (back-compat from pre-0.26.0 audit data) so existing
+ * users with prior reviews don't have to re-review on upgrade.
+ *
+ * Streaming approach: read the whole file (audit logs are typically
+ * < 10 MB even after months of use) and walk lines from the end. The
+ * audit log is append-only and timestamps are monotonic per writer.
+ *
+ * # Coverage matching (0.26.0 helix-026 finding-1)
+ *
+ * The first valid `metadata.content_token` on each record wins:
+ *
+ *   1. Record has `content_token` AND caller supplied `contentToken` →
+ *      exact-string match. Stable across `--amend` / fixup rebases.
+ *   2. Record has NO `content_token` (legacy `codex.review` entry, or
+ *      a future provider that can't compute one) → fall back to
+ *      exact-string `head_sha` match. Pre-0.26.0 reviews still cover.
+ *   3. Record has `content_token` but caller's `contentToken` is empty
+ *      (preflight on a non-git directory or detached state) → fall back
+ *      to `head_sha` match. The content path is the additive layer; the
+ *      head-sha layer remains as the floor.
+ *
+ * Hierarchy invariant: an entry is valid coverage when EITHER the token
+ * matches OR the head_sha matches. The two are not AND-ed — that would
+ * make legacy entries un-matchable and would break the local-first loop
+ * back to the old "commit first, then review" inversion.
+ */
+export interface LocalReviewLookupResult {
+    found: boolean;
+    /** Audit-record metadata payload, when found. */
+    metadata?: Record<string, unknown>;
+    /** ISO timestamp on the matching record. */
+    timestamp?: string;
+    /** Tool name that matched (canonical or legacy). */
+    tool_name?: string;
+    /**
+     * Which match-path validated this entry. Useful for tests and for the
+     * `--json` outcome: `'content_token'` (preferred), `'head_sha'`
+     * (back-compat / fallback).
+     */
+    match_kind?: 'content_token' | 'head_sha';
+}
+export declare function findRecentLocalReview(baseDir: string, headSha: string, maxAgeSeconds: number, now?: Date, contentToken?: string): LocalReviewLookupResult;
+/**
+ * Attach `rea preflight` to a commander Program.
+ */
+export declare function registerPreflightCommand(program: Command): void;
+export {};

package/dist/cli/preflight.js

@@ -0,0 +1,487 @@
+/**
+ * `rea preflight` — local-first enforcement workhorse (0.26.0+).
+ *
+ * Called by:
+ *   - The husky pre-push template (`exec rea preflight --strict`)
+ *   - The Bash-tier `local-review-gate.sh` PreToolUse hook
+ *   - Operators directly (`rea preflight` to check status)
+ *
+ * Decision flow:
+ *
+ *   1. `policy.review.local_review.mode === 'off'` → exit 0 (no-op)
+ *   2. `<bypass_env_var>` is set (default REA_SKIP_LOCAL_REVIEW) → audit
+ *      `rea.local_review.skipped_override` with the reason; exit 0
+ *   3. `--no-review-check` flag → audit `rea.preflight.review_skipped`;
+ *      proceed to commit-count check only
+ *   4. Tail `.rea/audit.jsonl` for a `rea.local_review` (or back-compat
+ *      `codex.review`) entry with `metadata.head_sha === <git HEAD>`
+ *      AND `now - timestamp < max_age_seconds`. Found → exit 0.
+ *      Missing → exit 2 with helpful message.
+ *   5. Commit-count check (independent of step 4):
+ *        `git rev-list --count <base>..HEAD` against thresholds
+ *        from `policy.commit_hygiene`.
+ *
+ * Exit codes:
+ *
+ *   0 — clean (mode=off, recent review found, or override set)
+ *   1 — warn (commit count > warn_at_commits but ≤ refuse_at_commits)
+ *   2 — refuse (no recent review covering HEAD, OR commit count >
+ *       refuse_at_commits, OR --strict elevated a warn to refuse)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { appendAuditRecord } from '../audit/append.js';
+import { LOCAL_REVIEW_TOOL_NAME, LOCAL_REVIEW_SKIPPED_OVERRIDE_TOOL_NAME, LOCAL_REVIEW_PREFLIGHT_SKIPPED_TOOL_NAME, LOCAL_REVIEW_SERVER_NAME, } from '../audit/local-review-event.js';
+import { CODEX_REVIEW_TOOL_NAME } from '../audit/codex-event.js';
+import { computeTreeToken, EMPTY_TREE_SHA } from '../audit/content-token.js';
+import { readHalt } from '../hooks/push-gate/halt.js';
+import { Tier, InvocationStatus } from '../policy/types.js';
+import { loadPolicyAsync } from '../policy/loader.js';
+import { err, log } from './utils.js';
+/** Default max age for a local-review audit entry (24h). */
+export const DEFAULT_MAX_AGE_SECONDS = 86_400;
+/** Default bypass env-var name. */
+export const DEFAULT_BYPASS_ENV_VAR = 'REA_SKIP_LOCAL_REVIEW';
+/** Default commit-hygiene thresholds. */
+export const DEFAULT_WARN_AT_COMMITS = 1;
+export const DEFAULT_REFUSE_AT_COMMITS = 5;
+/**
+ * Run preflight in-process. Tests drive this directly. The CLI binding
+ * exits via `process.exit` at the end of `runPreflight()`.
+ */
+export async function computePreflight(baseDir, options, env = process.env) {
+    const policy = await tryLoadPolicy(baseDir);
+    // Round-27 F4 fix: HALT check BEFORE every other path. The Bash-tier
+    // `local-review-gate.sh` and the canonical husky BODY_TEMPLATE both
+    // honor `.rea/HALT`, but `rea preflight` itself was missing the check —
+    // direct invocations and the minimal `templates/pre-push.local-first.sh`
+    // body bypassed the kill-switch entirely. The HALT check runs BEFORE
+    // `mode === 'off'` so a halted repo cannot push even when local-review
+    // enforcement is opted-out.
+    const halt = readHalt(baseDir);
+    if (halt.halted) {
+        return {
+            outcome: {
+                status: 'refuse',
+                reason: `REA HALT: ${halt.reason ?? 'unknown'}`,
+                exitCode: 2,
+                details: {
+                    halt: true,
+                    halt_reason: halt.reason ?? 'unknown',
+                },
+            },
+            policy,
+        };
+    }
+    // Step 1: mode === 'off' → no-op clean exit.
+    const mode = policy?.review?.local_review?.mode ?? 'enforced';
+    if (mode === 'off') {
+        return {
+            outcome: {
+                status: 'clean',
+                reason: 'policy.review.local_review.mode is off',
+                exitCode: 0,
+                details: { mode: 'off' },
+            },
+            policy,
+        };
+    }
+    const headSha = resolveHeadSha(baseDir);
+    // 0.26.0 helix-026 finding-1: compute the current tree-token. Coverage
+    // is matched on this in step 4 — `head_sha` is only used for forensics
+    // (and as a back-compat fallback for legacy `codex.review` entries that
+    // were written before content_token existed).
+    const contentToken = computeTreeToken(baseDir);
+    const bypassEnvVar = policy?.review?.local_review?.bypass_env_var ?? DEFAULT_BYPASS_ENV_VAR;
+    const bypassReason = (env[bypassEnvVar] ?? '').trim();
+    // Step 2: bypass env-var → audit + clean exit.
+    if (bypassReason.length > 0) {
+        const meta = {
+            head_sha: headSha,
+            reason: bypassReason,
+            bypass_env_var: bypassEnvVar,
+        };
+        await safeAudit(baseDir, LOCAL_REVIEW_SKIPPED_OVERRIDE_TOOL_NAME, InvocationStatus.Allowed, meta, policy);
+        return {
+            outcome: {
+                status: 'clean',
+                reason: `${bypassEnvVar} set (audited)`,
+                exitCode: 0,
+                details: { bypass_env_var: bypassEnvVar, reason: bypassReason },
+            },
+            policy,
+        };
+    }
+    // Step 3: --no-review-check escape hatch (audit-logged).
+    let reviewCheckSkipped = false;
+    if (options.noReviewCheck === true) {
+        reviewCheckSkipped = true;
+        await safeAudit(baseDir, LOCAL_REVIEW_PREFLIGHT_SKIPPED_TOOL_NAME, InvocationStatus.Allowed, { head_sha: headSha, reason: '--no-review-check flag' }, policy);
+    }
+    // Step 4: audit-log lookup (skipped under --no-review-check).
+    const maxAgeSeconds = policy?.review?.local_review?.max_age_seconds ?? DEFAULT_MAX_AGE_SECONDS;
+    if (!reviewCheckSkipped) {
+        const lookup = findRecentLocalReview(baseDir, headSha, maxAgeSeconds, new Date(), contentToken);
+        if (!lookup.found) {
+            return {
+                outcome: {
+                    status: 'refuse',
+                    reason: 'no recent local-review audit entry covers HEAD',
+                    exitCode: 2,
+                    details: {
+                        head_sha: headSha,
+                        content_token: contentToken,
+                        max_age_seconds: maxAgeSeconds,
+                        bypass_env_var: bypassEnvVar,
+                        policy_off_switch: 'policy.review.local_review.mode: off',
+                    },
+                },
+                policy,
+            };
+        }
+    }
+    // Step 5: commit-count check.
+    const warnAt = policy?.commit_hygiene?.warn_at_commits ?? DEFAULT_WARN_AT_COMMITS;
+    const refuseAt = policy?.commit_hygiene?.refuse_at_commits ?? DEFAULT_REFUSE_AT_COMMITS;
+    const commitCount = countCommitsAheadOfBase(baseDir);
+    if (commitCount !== null) {
+        if (commitCount > refuseAt) {
+            return {
+                outcome: {
+                    status: 'refuse',
+                    reason: `commit count ${commitCount} > refuse_at_commits=${refuseAt} — squash before pushing`,
+                    exitCode: 2,
+                    details: {
+                        commit_count: commitCount,
+                        warn_at_commits: warnAt,
+                        refuse_at_commits: refuseAt,
+                    },
+                },
+                policy,
+            };
+        }
+        if (commitCount > warnAt) {
+            const elevated = options.strict === true;
+            return {
+                outcome: {
+                    status: elevated ? 'refuse' : 'warn',
+                    reason: `commit count ${commitCount} > warn_at_commits=${warnAt}${elevated ? ' (strict)' : ''}`,
+                    exitCode: elevated ? 2 : 1,
+                    details: {
+                        commit_count: commitCount,
+                        warn_at_commits: warnAt,
+                        refuse_at_commits: refuseAt,
+                        strict: elevated,
+                    },
+                },
+                policy,
+            };
+        }
+    }
+    return {
+        outcome: {
+            status: 'clean',
+            reason: reviewCheckSkipped
+                ? 'review check skipped, commit-hygiene clean'
+                : 'recent local-review audit entry covers HEAD',
+            exitCode: 0,
+            details: { head_sha: headSha, content_token: contentToken, commit_count: commitCount },
+        },
+        policy,
+    };
+}
+export async function runPreflight(options) {
+    const baseDir = process.cwd();
+    const { outcome } = await computePreflight(baseDir, options);
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify({ ...outcome }) + '\n');
+    }
+    else {
+        if (outcome.exitCode === 0) {
+            log(`preflight clean — ${outcome.reason}`);
+        }
+        else if (outcome.exitCode === 1) {
+            console.warn(`[rea] preflight WARN — ${outcome.reason}`);
+        }
+        else {
+            err(`preflight refuse — ${outcome.reason}`);
+            console.error('');
+            console.error('  To unblock, do ONE of:');
+            console.error('    1. Run `rea review`           — write a fresh local-review audit entry');
+            console.error('    2. Set REA_SKIP_LOCAL_REVIEW="<reason>"');
+            console.error('                                  — per-invocation override (audited)');
+            console.error('    3. Edit .rea/policy.yaml      — set:');
+            console.error('         review:');
+            console.error('           local_review:');
+            console.error('             mode: off');
+            console.error('       (use this if your team does not have codex/claude installed)');
+            console.error('');
+        }
+    }
+    process.exit(outcome.exitCode);
+}
+// ---------------------------------------------------------------------------
+// Implementation helpers
+// ---------------------------------------------------------------------------
+async function tryLoadPolicy(baseDir) {
+    try {
+        return await loadPolicyAsync(baseDir);
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveHeadSha(baseDir) {
+    const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: baseDir, encoding: 'utf8' });
+    if (r.status !== 0) {
+        // Round-27 F2 fix: unborn-HEAD repos return EMPTY_TREE_SHA so the
+        // reader stays symmetric with `rea review`'s writer (which uses the
+        // same constant when HEAD can't be resolved — see review.ts). Pre-fix
+        // the reader returned '' and the both-empty guard in
+        // `findRecentLocalReview` rejected the just-written audit entry,
+        // deadlocking `git init → rea review → git commit` under
+        // `refuse_at: both`.
+        return EMPTY_TREE_SHA;
+    }
+    const sha = (r.stdout ?? '').toString().trim();
+    return sha.length > 0 ? sha : EMPTY_TREE_SHA;
+}
+/**
+ * Resolve the divergence base for commit-counting. The intent is "how
+ * many commits will this push deliver to TRUNK" — not "how many commits
+ * are unpushed on this branch". Order trunk-equivalent refs first.
+ *
+ * Order (0.26.0 helix-026 finding-3):
+ *   1. `origin/HEAD` (the default branch on origin — usually `main`)
+ *   2. `origin/main`
+ *   3. `origin/master`
+ *   4. `@{upstream}` (LAST RESORT — see warning below)
+ *
+ * # Why `@{upstream}` is last
+ *
+ * After `git push -u origin <branch>`, `@{upstream}` resolves to
+ * `origin/<branch>` — the branch's OWN remote tip, NOT trunk. If
+ * preflight's commit-count check were keyed to that, a 50-commit
+ * feature branch would always count "0" once pushed, defeating
+ * `refuse_at_commits` on the very long-lived branches the policy was
+ * designed to discourage.
+ *
+ * `@{upstream}` is preserved as the absolute fallback for repos with no
+ * `origin` (forks, mirrors, weird CI clones). When `@{upstream}` is the
+ * only resolvable base AND it points to a non-trunk ref, preflight
+ * accepts the no-op cost — the audit-log review check is the primary
+ * gate; commit-count is best-effort.
+ *
+ * Additional guard: when `@{upstream}` resolves to a ref under
+ * `refs/remotes/origin/` other than the default branch, we skip it.
+ * This catches the typical `git push -u origin <feature>` case while
+ * still allowing `@{upstream}` -> `origin/main` to work for branches
+ * whose upstream IS trunk.
+ *
+ * Returns null when none resolve — `rea preflight` then skips the
+ * commit-count check (best-effort; the audit-log check is the primary
+ * gate).
+ */
+function resolveCommitCountBase(baseDir) {
+    // Trunk-equivalent refs first. `@{upstream}` is held back as a
+    // last-resort because it can resolve to the branch's own remote tip
+    // and turn the gate into a no-op — see the docblock above.
+    const primary = ['origin/HEAD', 'origin/main', 'origin/master'];
+    for (const ref of primary) {
+        if (resolveRef(baseDir, ref).length > 0)
+            return ref;
+    }
+    // `@{upstream}` LAST. We additionally probe what it resolves to —
+    // if it's a remote feature-branch ref under `refs/remotes/origin/`
+    // (not a primary trunk ref we already tried), the candidate is
+    // useless for commit-counting and we skip it rather than silently
+    // turn the check into a no-op.
+    const upstreamSymbolic = resolveSymbolicRef(baseDir, '@{upstream}');
+    if (upstreamSymbolic.length > 0) {
+        // `git rev-parse --abbrev-ref @{upstream}` returns e.g.
+        // `origin/main` or `origin/feat/foo`. If the resolved ref matches
+        // origin/<branch> for any branch we DIDN'T already try as a primary
+        // candidate, it's a feature-tracking upstream — skip.
+        const isFeatureUpstream = upstreamSymbolic.startsWith('origin/') &&
+            !primary.includes(upstreamSymbolic);
+        if (!isFeatureUpstream) {
+            // Upstream IS a trunk-equivalent ref (origin/main / origin/master /
+            // a non-origin remote). Use it.
+            if (resolveRef(baseDir, '@{upstream}').length > 0)
+                return '@{upstream}';
+        }
+        // Feature-tracking upstream: deliberately skipped to avoid the
+        // "50-commit branch counts 0" no-op. Fall through.
+    }
+    return null;
+}
+function resolveRef(baseDir, ref) {
+    const r = spawnSync('git', ['rev-parse', '--verify', '--quiet', ref], {
+        cwd: baseDir,
+        encoding: 'utf8',
+    });
+    if (r.status !== 0)
+        return '';
+    return (r.stdout ?? '').toString().trim();
+}
+function resolveSymbolicRef(baseDir, ref) {
+    const r = spawnSync('git', ['rev-parse', '--abbrev-ref', ref], {
+        cwd: baseDir,
+        encoding: 'utf8',
+    });
+    if (r.status !== 0)
+        return '';
+    return (r.stdout ?? '').toString().trim();
+}
+function countCommitsAheadOfBase(baseDir) {
+    const base = resolveCommitCountBase(baseDir);
+    if (base === null)
+        return null;
+    const r = spawnSync('git', ['rev-list', '--count', `${base}..HEAD`], {
+        cwd: baseDir,
+        encoding: 'utf8',
+    });
+    if (r.status !== 0)
+        return null;
+    const n = Number((r.stdout ?? '').toString().trim());
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new Date(), contentToken = '') {
+    // 0.26.0 helix-026 finding-1: callers can match by content_token,
+    // head_sha, or both. We need at least ONE non-empty key — without
+    // either the function would match every record indiscriminately.
+    if (headSha.length === 0 && contentToken.length === 0)
+        return { found: false };
+    const auditPath = path.join(baseDir, '.rea', 'audit.jsonl');
+    if (!fs.existsSync(auditPath))
+        return { found: false };
+    let raw;
+    try {
+        raw = fs.readFileSync(auditPath, 'utf8');
+    }
+    catch {
+        return { found: false };
+    }
+    const lines = raw.split(/\r?\n/);
+    const cutoffMs = now.getTime() - maxAgeSeconds * 1000;
+    // Walk in reverse — most recent first.
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line === undefined || line.length === 0)
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const toolName = typeof record.tool_name === 'string' ? record.tool_name : '';
+        if (toolName !== LOCAL_REVIEW_TOOL_NAME && toolName !== CODEX_REVIEW_TOOL_NAME) {
+            continue;
+        }
+        const status = typeof record.status === 'string' ? record.status : '';
+        // Skipped/error variants are not coverage. `denied` (blocking verdict)
+        // is also not coverage — preflight's job is to ensure a successful
+        // recent review, not just any review.
+        if (status !== 'allowed')
+            continue;
+        const metadata = (record.metadata ?? {});
+        const recordedSha = typeof metadata.head_sha === 'string' ? metadata.head_sha : '';
+        const recordedToken = typeof metadata.content_token === 'string' ? metadata.content_token : '';
+        // Coverage match: prefer content_token (stable across --amend), fall
+        // back to head_sha for legacy entries / providers that can't compute
+        // a token. See block-comment above for the full hierarchy.
+        //
+        // Round-27 F3 fix: when BOTH sides have a content_token but they
+        // DISAGREE, the entry is stale — the working-tree content has changed
+        // since the review was written. Pre-fix the `else if` ran whenever
+        // the first branch failed, INCLUDING real token mismatch, which
+        // silently fell back to head_sha matching. PoC: `rea review` writes
+        // T1, operator edits one tracked file (no commit), `git commit`
+        // under `refuse_at: commit` → preflight approves the commit because
+        // HEAD hasn't moved, defeating the whole content-token path.
+        //
+        // Fix: when both tokens are present, the comparison is authoritative —
+        // mismatch means stale, no fallback. Only when the entry is missing
+        // a content_token (legacy `codex.review`) OR the caller's contentToken
+        // is empty (non-git directory) do we fall through to head_sha.
+        let matchKind = null;
+        if (recordedToken.length > 0 && contentToken.length > 0) {
+            // Both sides have a token — token comparison is AUTHORITATIVE.
+            if (recordedToken === contentToken)
+                matchKind = 'content_token';
+            // Token mismatch: this entry is stale. Do NOT fall back.
+        }
+        else if (recordedSha.length > 0 && headSha.length > 0 && recordedSha === headSha) {
+            // No token on this entry (or caller). Legacy / non-git fallback.
+            matchKind = 'head_sha';
+        }
+        if (matchKind === null)
+            continue;
+        const verdict = typeof metadata.verdict === 'string' ? metadata.verdict : '';
+        if (verdict === 'error' || verdict === 'blocking')
+            continue;
+        const timestamp = typeof record.timestamp === 'string' ? record.timestamp : '';
+        if (timestamp.length > 0) {
+            const ts = Date.parse(timestamp);
+            if (Number.isFinite(ts) && ts < cutoffMs) {
+                // Older than max_age_seconds — keep walking; a more recent valid
+                // record may exist further back? No: we walk newest-to-oldest so
+                // anything older from here on is also stale. Stop early.
+                return { found: false };
+            }
+        }
+        return {
+            found: true,
+            metadata,
+            timestamp,
+            tool_name: toolName,
+            match_kind: matchKind,
+        };
+    }
+    return { found: false };
+}
+async function safeAudit(baseDir, toolName, status, metadata, policy) {
+    try {
+        const cleanMeta = {};
+        for (const [k, v] of Object.entries(metadata)) {
+            if (v !== undefined)
+                cleanMeta[k] = v;
+        }
+        await appendAuditRecord(baseDir, {
+            tool_name: toolName,
+            server_name: LOCAL_REVIEW_SERVER_NAME,
+            tier: Tier.Read,
+            status,
+            ...(Object.keys(cleanMeta).length > 0 ? { metadata: cleanMeta } : {}),
+            ...(policy !== undefined ? { policy } : {}),
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`rea: audit append failed (${toolName}): ${msg}\n`);
+    }
+}
+/**
+ * Attach `rea preflight` to a commander Program.
+ */
+export function registerPreflightCommand(program) {
+    program
+        .command('preflight')
+        .description('Local-first enforcement workhorse. Refuses (exit 2) when no recent `rea.local_review` audit entry covers HEAD, when commit-hygiene thresholds are exceeded, or when the kill-switch is active. Exit 0 (clean) / 1 (warn) / 2 (refuse). Husky pre-push and the Bash-tier `local-review-gate.sh` hook both delegate here.')
+        .option('--strict', 'treat commit-hygiene warns as refusals (exit 2 instead of 1). Always set by husky pre-push.')
+        .option('--no-review-check', 'skip the audit-log lookup (still runs commit-hygiene). Audit-logged escape hatch — different from the per-invocation env-var override.')
+        .option('--json', 'emit a single-line JSON outcome instead of human-readable output')
+        .action(async (opts) => {
+        // Commander negation: --no-review-check sets opts.reviewCheck = false.
+        // We invert to noReviewCheck for clarity in the runner.
+        const noReviewCheck = opts.reviewCheck === false;
+        await runPreflight({
+            ...(opts.strict === true ? { strict: true } : {}),
+            ...(noReviewCheck ? { noReviewCheck: true } : {}),
+            ...(opts.json === true ? { json: true } : {}),
+        });
+    });
+}

package/dist/cli/review.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `rea review` — local-first codex review CLI (0.26.0+).
+ *
+ * Runs `codex exec review` against the working tree (or a specified
+ * base ref), parses the verdict, and writes a `rea.local_review`
+ * audit entry that `rea preflight` consults.
+ *
+ * Exit codes:
+ *
+ *   0 — pass (or skipped because `mode: off` + codex unavailable)
+ *   1 — concerns (configurable via --strict-fail-on)
+ *   2 — blocking, codex error, or codex unavailable in `mode: enforced`
+ *
+ * Behavior matrix:
+ *
+ *   policy.local_review.mode  codex available?  result
+ *   ------------------------  ---------------   ----------------------
+ *   enforced or unset (def.)  yes               run review, audit
+ *   enforced or unset (def.)  no                exit 2 with helpful msg
+ *   off                       yes               run review, audit
+ *   off                       no                exit 0, audit skipped
+ *
+ * The `provider` field on the audit record is `'codex'` today. Future
+ * providers (Claude-subagent, Pi, Gemma) write the SAME `rea.local_review`
+ * shape with their own `provider:` value — `rea preflight` accepts any.
+ *
+ * The CLI is a thin wrapper around `runCodexReview` from
+ * `src/hooks/push-gate/codex-runner.ts`. We do NOT re-implement codex
+ * spawning. The push-gate's iron-gate defaults (gpt-5.4 + high reasoning)
+ * apply identically here so a local review carries the same weight as
+ * the push-gate's review.
+ */
+import type { Command } from 'commander';
+export interface RunReviewOptions {
+    /** Optional explicit base ref. Defaults to upstream-ladder resolution. */
+    base?: string;
+    /**
+     * Verdict floor that turns into a non-zero exit. `'concerns'` exits 1
+     * on concerns; `'blocking'` (default) exits 0 on concerns and 2 only
+     * on blocking. Aligns with the push-gate's `concerns_blocks` knob.
+     */
+    strictFailOn?: 'concerns' | 'blocking';
+    /** Emit a single JSON line on stdout instead of pretty output. */
+    json?: boolean;
+}
+/**
+ * Public runner — exposed so tests can drive the function in-process and
+ * the commander binding can stay thin. Throws via `process.exit` (CLI
+ * convention across `src/cli/`).
+ */
+export declare function runReview(options: RunReviewOptions): Promise<void>;
+/**
+ * Attach `rea review` to a commander Program.
+ */
+export declare function registerReviewCommand(program: Command): void;
+export declare const REA_AUDIT_RELATIVE: string;