@bookedsolid/rea 0.10.3 → 0.11.0

package/dist/hooks/push-gate/index.js

@@ -0,0 +1,351 @@
+/**
+ * Push-gate composition — the pure orchestrator that `rea hook push-gate`
+ * calls.
+ *
+ * Contract: `runPushGate(deps)` returns a `GateResult` with an `exitCode`
+ * the CLI wrapper hands back to `git`. Exit codes:
+ *
+ *   - `0` push proceeds (pass, disabled, skipped, empty-diff)
+ *   - `1` HALT kill-switch active — rea unfreeze required
+ *   - `2` blocked — blocking verdict, timeout, or protocol error
+ *
+ * The happy path is a single call: resolve policy → resolve base → spawn
+ * codex exec review → parse findings → write last-review.json → emit audit
+ * record → return exit code. No cache lookups, no SHA matching, no
+ * attestation gymnastics. Every push runs codex afresh; Codex is the
+ * source of truth.
+ *
+ * The function is pure-compositional: every external dependency (git,
+ * codex, halt, policy) is injected via `PushGateDeps`, which is the
+ * affordance tests use to replace subprocess calls with deterministic
+ * fakes. `runPushGate` never reaches for `process.env` or `process.cwd`
+ * directly — `deps.env` and `deps.baseDir` are the only ambient state.
+ */
+import path from 'node:path';
+import { appendAuditRecord } from '../../audit/append.js';
+import { Tier, InvocationStatus } from '../../policy/types.js';
+import { resolvePushGatePolicy, } from './policy.js';
+import { readHalt } from './halt.js';
+import { resolveBaseRef } from './base.js';
+import { createRealGitExecutor, runCodexReview, CodexNotInstalledError, CodexProtocolError, CodexSubprocessError, CodexTimeoutError, } from './codex-runner.js';
+import { summarizeReview } from './findings.js';
+import { renderBanner, writeLastReview } from './report.js';
+/**
+ * Parse the raw pre-push stdin text into refspecs. Each line is four
+ * whitespace-separated fields. Blank lines and malformed lines are
+ * silently dropped — the empty result then falls through to the
+ * upstream-resolver path in `runPushGate`.
+ */
+export function parsePrePushStdin(raw) {
+    const out = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const fields = trimmed.split(/\s+/);
+        if (fields.length !== 4)
+            continue;
+        const [localRef, localSha, remoteRef, remoteSha] = fields;
+        if (typeof localRef !== 'string' ||
+            typeof localSha !== 'string' ||
+            typeof remoteRef !== 'string' ||
+            typeof remoteSha !== 'string') {
+            continue;
+        }
+        out.push({ localRef, localSha, remoteRef, remoteSha });
+    }
+    return out;
+}
+/**
+ * Well-known "null SHA" in git's wire format. Pre-push sends this as
+ * `remote_sha` for a fresh remote ref (the branch doesn't exist yet on
+ * the remote) and as `local_sha` for a branch deletion.
+ */
+const NULL_SHA = '0000000000000000000000000000000000000000';
+// ---------------------------------------------------------------------------
+// Audit event names (advisory — no gate ever reads these back)
+// ---------------------------------------------------------------------------
+const AUDIT_SERVER_NAME = 'rea';
+const EVT_REVIEWED = 'rea.push_gate.reviewed';
+const EVT_HALTED = 'rea.push_gate.halted';
+const EVT_DISABLED = 'rea.push_gate.disabled';
+const EVT_SKIPPED = 'rea.push_gate.skipped';
+const EVT_EMPTY = 'rea.push_gate.empty_diff';
+const EVT_ERROR = 'rea.push_gate.error';
+// ---------------------------------------------------------------------------
+// Composer
+// ---------------------------------------------------------------------------
+export async function runPushGate(deps) {
+    const stderr = deps.stderr;
+    const env = deps.env;
+    const readHaltFn = deps.readHalt ?? readHalt;
+    const resolvePolicyFn = deps.resolvePolicy ?? resolvePushGatePolicy;
+    const writeLastReviewFn = deps.writeLastReview ?? writeLastReview;
+    const runCodexFn = deps.runCodex ?? runCodexReview;
+    const appendAuditFn = deps.appendAudit ?? appendAuditRecord;
+    const git = deps.git ?? createRealGitExecutor(deps.baseDir);
+    // 1. HALT wins over everything, including `review.codex_required: false`.
+    //    Reading it before policy also means a corrupted policy.yaml doesn't
+    //    prevent the kill-switch from firing.
+    const halt = readHaltFn(deps.baseDir);
+    if (halt.halted) {
+        stderr(`REA HALT: ${halt.reason ?? 'unknown'}\nAll push operations suspended. Run: rea unfreeze\n`);
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_HALTED, {
+            reason: halt.reason ?? 'unknown',
+        });
+        return {
+            status: 'halted',
+            exitCode: 1,
+            summary: `HALT active: ${halt.reason ?? 'unknown'}`,
+        };
+    }
+    // 2. Load policy. A malformed policy.yaml surfaces as a thrown zod error;
+    //    we catch it, audit, and exit 2 rather than silently bypass.
+    let policy;
+    try {
+        policy = await resolvePolicyFn(deps.baseDir);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        stderr(`PUSH BLOCKED: failed to load .rea/policy.yaml — ${msg}\n`);
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, {
+            kind: 'policy-load',
+            error: msg,
+        });
+        return { status: 'error', exitCode: 2, summary: `policy-load error: ${msg}` };
+    }
+    if (!policy.codex_required) {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_DISABLED, {
+            policy_missing: policy.policyMissing,
+        });
+        return {
+            status: 'disabled',
+            exitCode: 0,
+            summary: 'review.codex_required is false — push-gate skipped',
+        };
+    }
+    // 3. REA_SKIP_PUSH_GATE — value-carrying waiver. HALT-wins ordering means
+    //    this is checked AFTER halt (step 1) and AFTER codex_required=false
+    //    short-circuit (step 2). Both of those should hold anyway; this is
+    //    for the case where codex is required but the operator wants to
+    //    skip for a narrow, documented reason.
+    const skipReason = (env.REA_SKIP_PUSH_GATE ?? '').trim();
+    if (skipReason.length > 0) {
+        stderr(`rea: REA_SKIP_PUSH_GATE=${skipReason} — push-gate skipped (audited).\n`);
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_SKIPPED, {
+            reason: skipReason,
+        });
+        return {
+            status: 'skipped',
+            exitCode: 0,
+            summary: `REA_SKIP_PUSH_GATE waiver: ${skipReason}`,
+        };
+    }
+    // 4. Resolve (base_ref, head_sha) for the actual review.
+    //
+    //    When pre-push stdin yielded at least one refspec (`git push` path),
+    //    diff against the first NON-DELETION refspec's (remote_sha..local_sha).
+    //    This matches what git itself is about to push — critical when the
+    //    operator uses `git push origin HEAD:release/1.0` and the branch's
+    //    tracking ref is a different branch entirely (the 0.10.x gate
+    //    silently reviewed against the wrong base in that case).
+    //
+    //    When stdin was empty (manual invocation, test), fall back to the
+    //    upstream → origin/HEAD → main/master ladder.
+    const activeRefspec = (deps.refspecs ?? []).find((r) => r.localSha !== NULL_SHA && r.localSha.length > 0);
+    let base;
+    let headSha;
+    if (activeRefspec !== undefined && (deps.explicitBase === undefined || deps.explicitBase.length === 0)) {
+        headSha = activeRefspec.localSha;
+        if (activeRefspec.remoteSha === NULL_SHA || activeRefspec.remoteSha.length === 0) {
+            // New remote ref — no existing commits to diff against. Fall back to
+            // the resolver ladder so we still get a meaningful review (e.g. vs
+            // origin/main) rather than an empty-tree diff of everything.
+            base = resolveBaseRef(git);
+        }
+        else {
+            base = { ref: activeRefspec.remoteSha, source: 'explicit' };
+        }
+    }
+    else {
+        base = resolveBaseRef(git, {
+            ...(deps.explicitBase !== undefined && deps.explicitBase.length > 0
+                ? { explicit: deps.explicitBase }
+                : {}),
+        });
+        headSha = git.headSha();
+    }
+    if (headSha.length === 0) {
+        stderr('PUSH BLOCKED: could not resolve HEAD SHA. Is this a valid git repo?\n');
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, { kind: 'head-sha-missing' });
+        return { status: 'error', exitCode: 2, summary: 'head-sha-missing' };
+    }
+    // 5. Empty-diff short-circuit. An initial push against the empty-tree
+    //    sentinel ALWAYS has a non-empty diff (HEAD vs empty tree); this
+    //    short-circuit only fires when the feature branch really is a
+    //    no-op relative to base.
+    const diff = git.diffNames(base.ref, headSha);
+    if (diff.length === 0) {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_EMPTY, {
+            base_ref: base.ref,
+            base_source: base.source,
+            head_sha: headSha,
+        });
+        return {
+            status: 'empty-diff',
+            exitCode: 0,
+            summary: 'empty diff — nothing to review',
+            baseRef: base.ref,
+            headSha,
+        };
+    }
+    // 6. Run Codex. Typed errors translate to exit 2 with distinct stderr.
+    try {
+        const codexResult = await runCodexFn({
+            baseRef: base.ref,
+            cwd: deps.baseDir,
+            timeoutMs: policy.timeout_ms,
+            env,
+        });
+        const summary = summarizeReview(codexResult.reviewText);
+        const blocked = summary.verdict === 'blocking'
+            || (summary.verdict === 'concerns'
+                && policy.concerns_blocks
+                && !isConcernsOverrideSet(env));
+        const lastReviewPath = path.join(deps.baseDir, '.rea', 'last-review.json');
+        const payload = writeLastReviewFn({
+            baseDir: deps.baseDir,
+            summary,
+            baseRef: base.ref,
+            headSha,
+            eventCount: codexResult.eventCount,
+            durationSeconds: codexResult.durationSeconds,
+            ...(deps.now !== undefined ? { now: deps.now() } : {}),
+        });
+        stderr(renderBanner({
+            payload,
+            baseSource: base.source,
+            blocked,
+            lastReviewPath,
+        }));
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_REVIEWED, {
+            verdict: summary.verdict,
+            finding_count: summary.findings.length,
+            base_ref: base.ref,
+            base_source: base.source,
+            head_sha: headSha,
+            blocked,
+            duration_seconds: codexResult.durationSeconds,
+            event_count: codexResult.eventCount,
+            concerns_override: summary.verdict === 'concerns' && isConcernsOverrideSet(env) ? true : undefined,
+        });
+        if (blocked) {
+            return {
+                status: summary.verdict === 'blocking' ? 'blocking' : 'concerns',
+                exitCode: 2,
+                summary: `${summary.verdict}: ${summary.findings.length} finding(s)`,
+                verdict: summary.verdict,
+                findingCount: summary.findings.length,
+                baseRef: base.ref,
+                headSha,
+            };
+        }
+        return {
+            status: summary.verdict === 'blocking'
+                ? 'blocking'
+                : summary.verdict === 'concerns'
+                    ? 'concerns'
+                    : 'pass',
+            exitCode: 0,
+            summary: `${summary.verdict}: ${summary.findings.length} finding(s)`,
+            verdict: summary.verdict,
+            findingCount: summary.findings.length,
+            baseRef: base.ref,
+            headSha,
+        };
+    }
+    catch (e) {
+        return handleCodexError(e, deps, base, headSha, appendAuditFn);
+    }
+}
+function isConcernsOverrideSet(env) {
+    const raw = env.REA_ALLOW_CONCERNS;
+    if (raw === undefined)
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+async function handleCodexError(e, deps, base, headSha, appendAuditFn) {
+    const stderr = deps.stderr;
+    const runError = classifyCodexError(e);
+    const metadata = {
+        base_ref: base.ref,
+        base_source: base.source,
+        head_sha: headSha,
+        kind: runError.kind,
+    };
+    if (runError.message.length > 0)
+        metadata.error = runError.message;
+    stderr(`PUSH BLOCKED: ${runError.message}\n`);
+    await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, metadata);
+    return {
+        status: 'error',
+        exitCode: 2,
+        summary: `codex error (${runError.kind}): ${runError.message}`,
+        baseRef: base.ref,
+        headSha,
+    };
+}
+function classifyCodexError(e) {
+    if (e instanceof CodexNotInstalledError)
+        return { kind: 'not-installed', message: e.message };
+    if (e instanceof CodexTimeoutError)
+        return { kind: 'timeout', message: e.message };
+    if (e instanceof CodexProtocolError)
+        return { kind: 'protocol', message: e.message };
+    if (e instanceof CodexSubprocessError)
+        return { kind: 'subprocess', message: e.message };
+    if (e instanceof Error)
+        return { kind: 'unknown', message: e.message };
+    return { kind: 'unknown', message: String(e) };
+}
+/**
+ * Audit-record helper. Never throws — audit failures are themselves audited
+ * (best-effort warn to stderr) but must not prevent the gate from returning
+ * its primary result. The hash chain remains intact if this succeeds; on
+ * failure we've already made the gate decision based on the actual review.
+ */
+async function safeAppend(appendFn, baseDir, toolName, metadata) {
+    try {
+        // Prune undefined values — the audit record schema's `metadata` is an
+        // arbitrary map, but `undefined` values cause JSON.stringify to emit
+        // missing keys which breaks round-trips on some readers.
+        const cleanMeta = {};
+        for (const [k, v] of Object.entries(metadata)) {
+            if (v !== undefined)
+                cleanMeta[k] = v;
+        }
+        await appendFn(baseDir, {
+            tool_name: toolName,
+            server_name: AUDIT_SERVER_NAME,
+            tier: Tier.Read,
+            status: InvocationStatus.Allowed,
+            ...(Object.keys(cleanMeta).length > 0 ? { metadata: cleanMeta } : {}),
+        });
+    }
+    catch (e) {
+        // Audit persistence failure should never cascade into a push block when
+        // the gate itself decided to pass — but we do want operator visibility.
+        const msg = e instanceof Error ? e.message : String(e);
+        // Use the deps.stderr is unavailable here (different stack frame); write
+        // directly to process.stderr as a fallback.
+        process.stderr.write(`rea: audit append failed (${toolName}): ${msg}\n`);
+    }
+}
+// Re-exports for the CLI wrapper so it can construct dependency defaults.
+export { resolvePushGatePolicy } from './policy.js';
+export { readHalt } from './halt.js';
+export { resolveBaseRef } from './base.js';
+export { runCodexReview, createRealGitExecutor } from './codex-runner.js';
+export { summarizeReview, parseFindings, inferVerdict } from './findings.js';
+export { writeLastReview, renderBanner } from './report.js';

package/dist/hooks/push-gate/policy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Push-gate policy resolution.
+ *
+ * Loads `.rea/policy.yaml` via the shared loader and flattens the subset the
+ * gate cares about into a single `ResolvedReviewPolicy`. Env-var overrides
+ * (`REA_SKIP_PUSH_GATE`, `REA_ALLOW_CONCERNS`) are NOT consumed here — the
+ * gate composition in `./index.ts` inspects them directly after policy load
+ * so the audit trail can distinguish "policy says skip" from "env says
+ * skip". This module is pure policy.
+ *
+ * Defaults (when a field is absent or `review:` is missing entirely):
+ *   - `codex_required`   → `true`  (safe-by-default: run Codex)
+ *   - `concerns_blocks`  → `true`  (safe-by-default: concerns halt the push)
+ *   - `timeout_ms`       → 600_000 (10 minutes)
+ *
+ * A missing `.rea/policy.yaml` is treated as "defaults apply" — the
+ * operator may not have run `rea init` yet, and the gate's behavior
+ * should match the most protective stance available. The caller is free
+ * to treat `policyMissing: true` as a doctor finding.
+ */
+export interface ResolvedReviewPolicy {
+    codex_required: boolean;
+    concerns_blocks: boolean;
+    timeout_ms: number;
+    /** `true` when `.rea/policy.yaml` was absent; defaults apply. */
+    policyMissing: boolean;
+}
+export declare const PUSH_GATE_DEFAULT_TIMEOUT_MS = 600000;
+export declare const PUSH_GATE_DEFAULT_CODEX_REQUIRED = true;
+export declare const PUSH_GATE_DEFAULT_CONCERNS_BLOCKS = true;
+/**
+ * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
+ * policy file surfaces as a typed error via the underlying zod validator,
+ * which we re-raise. The gate's `runPushGate()` catches that and returns
+ * `{ status: 'error', exitCode: 2 }` rather than silently bypassing.
+ *
+ * Returning a fully-populated object (no `undefined` knobs) means every
+ * downstream module can treat the policy as total — no `?? default` dance
+ * at each call site.
+ */
+export declare function resolvePushGatePolicy(baseDir: string): Promise<ResolvedReviewPolicy>;

package/dist/hooks/push-gate/policy.js

@@ -0,0 +1,55 @@
+/**
+ * Push-gate policy resolution.
+ *
+ * Loads `.rea/policy.yaml` via the shared loader and flattens the subset the
+ * gate cares about into a single `ResolvedReviewPolicy`. Env-var overrides
+ * (`REA_SKIP_PUSH_GATE`, `REA_ALLOW_CONCERNS`) are NOT consumed here — the
+ * gate composition in `./index.ts` inspects them directly after policy load
+ * so the audit trail can distinguish "policy says skip" from "env says
+ * skip". This module is pure policy.
+ *
+ * Defaults (when a field is absent or `review:` is missing entirely):
+ *   - `codex_required`   → `true`  (safe-by-default: run Codex)
+ *   - `concerns_blocks`  → `true`  (safe-by-default: concerns halt the push)
+ *   - `timeout_ms`       → 600_000 (10 minutes)
+ *
+ * A missing `.rea/policy.yaml` is treated as "defaults apply" — the
+ * operator may not have run `rea init` yet, and the gate's behavior
+ * should match the most protective stance available. The caller is free
+ * to treat `policyMissing: true` as a doctor finding.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadPolicyAsync } from '../../policy/loader.js';
+export const PUSH_GATE_DEFAULT_TIMEOUT_MS = 600_000;
+export const PUSH_GATE_DEFAULT_CODEX_REQUIRED = true;
+export const PUSH_GATE_DEFAULT_CONCERNS_BLOCKS = true;
+/**
+ * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
+ * policy file surfaces as a typed error via the underlying zod validator,
+ * which we re-raise. The gate's `runPushGate()` catches that and returns
+ * `{ status: 'error', exitCode: 2 }` rather than silently bypassing.
+ *
+ * Returning a fully-populated object (no `undefined` knobs) means every
+ * downstream module can treat the policy as total — no `?? default` dance
+ * at each call site.
+ */
+export async function resolvePushGatePolicy(baseDir) {
+    const policyPath = path.join(baseDir, '.rea', 'policy.yaml');
+    if (!fs.existsSync(policyPath)) {
+        return {
+            codex_required: PUSH_GATE_DEFAULT_CODEX_REQUIRED,
+            concerns_blocks: PUSH_GATE_DEFAULT_CONCERNS_BLOCKS,
+            timeout_ms: PUSH_GATE_DEFAULT_TIMEOUT_MS,
+            policyMissing: true,
+        };
+    }
+    const policy = await loadPolicyAsync(baseDir);
+    const review = policy.review ?? {};
+    return {
+        codex_required: review.codex_required ?? PUSH_GATE_DEFAULT_CODEX_REQUIRED,
+        concerns_blocks: review.concerns_blocks ?? PUSH_GATE_DEFAULT_CONCERNS_BLOCKS,
+        timeout_ms: review.timeout_ms ?? PUSH_GATE_DEFAULT_TIMEOUT_MS,
+        policyMissing: false,
+    };
+}

package/dist/hooks/push-gate/report.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Report output for the push-gate.
+ *
+ * Two channels:
+ *
+ *   1. `.rea/last-review.json` — machine-readable structured dump. Atomic
+ *      write (write-to-tmp + rename), gitignored, overwritten every push.
+ *      Claude reads this as the source of truth for file/line/body during
+ *      the auto-fix loop.
+ *
+ *   2. stderr banner — human-legible severity-sorted summary capped to 20
+ *      findings. The pre-push hook's stderr reaches Claude as the tool
+ *      output of `Bash(git push)`, so this is the primary fast-path to
+ *      surface verdict + first blocking finding.
+ *
+ * Redaction: before serializing anything to disk or stderr we run the
+ * shared `SECRET_PATTERNS` list over `title`, `body`, and `reviewText`. If
+ * Codex accidentally quoted a secret from the diff (common in password-
+ * reset flows, API-key migration PRs, env-file edits) it never hits disk
+ * in cleartext.
+ */
+import type { Finding, ReviewSummary, Verdict } from './findings.js';
+export interface LastReviewPayload {
+    schema_version: 1;
+    /** ISO-8601 UTC timestamp of the review run (wall clock). */
+    generated_at: string;
+    verdict: Verdict;
+    base_ref: string;
+    head_sha: string;
+    finding_count: number;
+    findings: Finding[];
+    /** Full agent text (post-redact). Useful for debugging parser misses. */
+    review_text: string;
+    /** Number of raw JSONL events Codex emitted. */
+    event_count: number;
+    /** Wall clock seconds in the Codex subprocess. */
+    duration_seconds: number;
+}
+export interface WriteLastReviewInput {
+    baseDir: string;
+    summary: ReviewSummary;
+    baseRef: string;
+    headSha: string;
+    eventCount: number;
+    durationSeconds: number;
+    /** Test seam — defaults to `new Date()`. */
+    now?: Date;
+}
+/**
+ * Atomic write of `.rea/last-review.json`. Returns the redacted payload
+ * actually written so the caller can reuse it for stderr rendering
+ * without re-redacting.
+ *
+ * We write to `last-review.json.tmp.<pid>-<rand>` first, fsync the file
+ * descriptor, then rename. rename(2) is atomic within the same
+ * filesystem, so partial writes never surface to readers.
+ */
+export declare function writeLastReview(input: WriteLastReviewInput): LastReviewPayload;
+export interface RenderBannerInput {
+    payload: LastReviewPayload;
+    /** Where was the base ref sourced from (audit / debugging). */
+    baseSource: string;
+    /**
+     * Whether the verdict-level action is BLOCKED or SOFT. Surfaced in the
+     * banner first line. Callers infer this from verdict + concerns_blocks.
+     */
+    blocked: boolean;
+    /** Last-review.json on-disk path — shown as a pointer. */
+    lastReviewPath: string;
+    /** Max findings to enumerate in the banner. Default 20. */
+    maxFindings?: number;
+}
+/**
+ * Build the stderr banner as a single multi-line string. Ends with `\n`.
+ *
+ * Layout:
+ *
+ *   ┌────────────────────────────────────────────┐
+ *   │ push-gate VERDICT — BLOCKED / PROCEEDING   │
+ *   │ base: <ref> (<source>)                     │
+ *   │ head: <sha>                                │
+ *   │ findings: <count>                          │
+ *   └────────────────────────────────────────────┘
+ *   - [P1] Title — file:42
+ *       body-excerpt
+ *   ...
+ *   see .rea/last-review.json for full details
+ */
+export declare function renderBanner(input: RenderBannerInput): string;

package/dist/hooks/push-gate/report.js

@@ -0,0 +1,140 @@
+/**
+ * Report output for the push-gate.
+ *
+ * Two channels:
+ *
+ *   1. `.rea/last-review.json` — machine-readable structured dump. Atomic
+ *      write (write-to-tmp + rename), gitignored, overwritten every push.
+ *      Claude reads this as the source of truth for file/line/body during
+ *      the auto-fix loop.
+ *
+ *   2. stderr banner — human-legible severity-sorted summary capped to 20
+ *      findings. The pre-push hook's stderr reaches Claude as the tool
+ *      output of `Bash(git push)`, so this is the primary fast-path to
+ *      surface verdict + first blocking finding.
+ *
+ * Redaction: before serializing anything to disk or stderr we run the
+ * shared `SECRET_PATTERNS` list over `title`, `body`, and `reviewText`. If
+ * Codex accidentally quoted a secret from the diff (common in password-
+ * reset flows, API-key migration PRs, env-file edits) it never hits disk
+ * in cleartext.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { compileDefaultSecretPatterns, redactSecrets, } from '../../gateway/middleware/redact.js';
+const LAST_REVIEW_FILENAME = 'last-review.json';
+/**
+ * Atomic write of `.rea/last-review.json`. Returns the redacted payload
+ * actually written so the caller can reuse it for stderr rendering
+ * without re-redacting.
+ *
+ * We write to `last-review.json.tmp.<pid>-<rand>` first, fsync the file
+ * descriptor, then rename. rename(2) is atomic within the same
+ * filesystem, so partial writes never surface to readers.
+ */
+export function writeLastReview(input) {
+    const { baseDir, summary, baseRef, headSha, eventCount, durationSeconds } = input;
+    const now = input.now ?? new Date();
+    const patterns = compileDefaultSecretPatterns({ source: 'default' });
+    const payload = {
+        schema_version: 1,
+        generated_at: now.toISOString(),
+        verdict: summary.verdict,
+        base_ref: baseRef,
+        head_sha: headSha,
+        finding_count: summary.findings.length,
+        findings: summary.findings.map((f) => redactFinding(f, patterns)),
+        review_text: redactString(summary.reviewText, patterns),
+        event_count: eventCount,
+        duration_seconds: Number.isFinite(durationSeconds) ? durationSeconds : 0,
+    };
+    const reaDir = path.join(baseDir, '.rea');
+    ensureDir(reaDir);
+    const finalPath = path.join(reaDir, LAST_REVIEW_FILENAME);
+    const tmpPath = `${finalPath}.tmp.${process.pid}-${randomBytes(4).toString('hex')}`;
+    const fd = fs.openSync(tmpPath, 'w', 0o600);
+    try {
+        fs.writeFileSync(fd, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf8' });
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmpPath, finalPath);
+    return payload;
+}
+function redactFinding(f, patterns) {
+    return {
+        severity: f.severity,
+        title: redactString(f.title, patterns),
+        body: redactString(f.body, patterns),
+        ...(f.file !== undefined ? { file: f.file } : {}),
+        ...(f.line !== undefined ? { line: f.line } : {}),
+    };
+}
+function redactString(s, patterns) {
+    const { output } = redactSecrets(s, patterns);
+    return output;
+}
+function ensureDir(dir) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch (e) {
+        // mkdir -p is idempotent; EEXIST is fine, anything else surfaces to
+        // the caller and becomes an exit-2 error.
+        const code = e.code;
+        if (code !== 'EEXIST')
+            throw e;
+    }
+}
+const SEVERITY_ORDER = { P1: 0, P2: 1, P3: 2 };
+/**
+ * Build the stderr banner as a single multi-line string. Ends with `\n`.
+ *
+ * Layout:
+ *
+ *   ┌────────────────────────────────────────────┐
+ *   │ push-gate VERDICT — BLOCKED / PROCEEDING   │
+ *   │ base: <ref> (<source>)                     │
+ *   │ head: <sha>                                │
+ *   │ findings: <count>                          │
+ *   └────────────────────────────────────────────┘
+ *   - [P1] Title — file:42
+ *       body-excerpt
+ *   ...
+ *   see .rea/last-review.json for full details
+ */
+export function renderBanner(input) {
+    const { payload, baseSource, blocked, lastReviewPath } = input;
+    const max = input.maxFindings ?? 20;
+    const verdictLabel = blocked ? 'BLOCKED' : 'PROCEEDING';
+    const lines = [];
+    lines.push('');
+    lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    lines.push(`rea push-gate: ${payload.verdict.toUpperCase()} — ${verdictLabel}`);
+    lines.push(`base:     ${payload.base_ref}  (${baseSource})`);
+    lines.push(`head:     ${payload.head_sha}`);
+    lines.push(`findings: ${payload.finding_count}`);
+    lines.push(`elapsed:  ${payload.duration_seconds.toFixed(1)}s`);
+    lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    if (payload.findings.length === 0) {
+        lines.push('(no findings)');
+    }
+    else {
+        const sorted = [...payload.findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+        const shown = sorted.slice(0, max);
+        for (const f of shown) {
+            const loc = f.file !== undefined ? ` — ${f.file}${f.line !== undefined ? `:${f.line}` : ''}` : '';
+            lines.push(`- [${f.severity}] ${f.title}${loc}`);
+        }
+        if (sorted.length > shown.length) {
+            lines.push(`... ${sorted.length - shown.length} additional finding(s) suppressed (see JSON)`);
+        }
+    }
+    lines.push('');
+    lines.push(`machine-readable: ${lastReviewPath}`);
+    lines.push('');
+    return lines.join('\n');
+}