@bookedsolid/rea 0.17.0 → 0.19.0

package/.husky/commit-msg

@@ -78,9 +78,17 @@ BLOCKED=0
 MATCHES=""
 
 # Pattern 1: Co-Authored-By with noreply@ email
-if grep -qiE 'Co-Authored-By:.*noreply@' "$COMMIT_MSG_FILE" 2>/dev/null; then
+# 0.18.0 helix-020 / discord-ops Round 10 #3 fix (G4.B):
+# the pre-fix pattern `Co-Authored-By:.*noreply@` matched both AI-tool
+# noreply addresses AND legitimate `<user>@users.noreply.github.com`
+# collaborator credits — blocking honest co-author footers from human
+# contributors. Refined to enumerate AI-tool noreply domains explicitly;
+# Pattern 2 below catches Co-Authored-By with named tools regardless of
+# email, so dropping users.noreply.github.com from this branch only
+# relaxes the check for human collaborators — never for AI.
+if grep -qiE 'Co-Authored-By:.*noreply@(anthropic\.com|openai\.com|github-copilot|github\.com|claude\.ai|chatgpt\.com|googlemail\.com|google\.com|cursor\.com|codeium\.com|tabnine\.com|amazon\.com|amazonaws\.com|amazon-q\.amazonaws\.com|cody\.dev|sourcegraph\.com)' "$COMMIT_MSG_FILE" 2>/dev/null; then
   BLOCKED=1
-  MATCHES="${MATCHES}$(grep -niE 'Co-Authored-By:.*noreply@' "$COMMIT_MSG_FILE" 2>/dev/null)
+  MATCHES="${MATCHES}$(grep -niE 'Co-Authored-By:.*noreply@(anthropic\.com|openai\.com|github-copilot|github\.com|claude\.ai|chatgpt\.com|googlemail\.com|google\.com|cursor\.com|codeium\.com|tabnine\.com|amazon\.com|amazonaws\.com|amazon-q\.amazonaws\.com|cody\.dev|sourcegraph\.com)' "$COMMIT_MSG_FILE" 2>/dev/null)
 "
 fi
 

package/agents/codex-adversarial.md

@@ -32,13 +32,18 @@ You may read additional files in the repo if needed for context, but do so read-
 1. **Check HALT and policy** — read `.rea/policy.yaml`, check `.rea/HALT`. If frozen, stop immediately.
 2. **Validate Codex availability** — if `/codex` is not installed, report and stop. Do not silently fall back to another reviewer.
 3. **Prepare the Codex invocation** — construct the adversarial-review prompt with the diff, commit log, and any relevant context files.
-4. **Invoke `/codex:adversarial-review`** — this call flows through the REA middleware chain (audit → kill-switch → tier → policy → redact → injection → execute → result-size-cap).
+4. **Invoke `/codex:adversarial-review --model gpt-5.4`** — pass the `--model` flag explicitly to pin the iron-gate model regardless of plugin defaults or `~/.codex/config.toml` resolution. The codex-companion script accepts `--model` (see `codex-companion.mjs:684`). This call flows through the REA middleware chain (audit → kill-switch → tier → policy → redact → injection → execute → result-size-cap).
 
    **Model pinning (0.16.1+):** when the codex plugin's adversarial-review supports model overrides, request `gpt-5.4` with `model_reasoning_effort: high` to match the push-gate's iron-gate defaults. Pre-0.16.1, in-session adversarial reviews ran on whatever the plugin defaulted to (likely `codex-auto-review` at medium reasoning) — meaningfully WEAKER than the push-gate's `gpt-5.4` + `high`. This caused a "in-session review passes, push-gate review fails" pattern reported by helix across 014 / 015 / 016. If the plugin call accepts model parameters, pass them. If it does not, fall back to invoking `codex exec review --base <ref> --json --ephemeral -c model="gpt-5.4" -c model_reasoning_effort="high"` directly via `Bash` — same shape the push-gate uses (see `src/hooks/push-gate/codex-runner.ts::runCodexReview`). The cost of the stronger model is small relative to the cost of shipping a release with a P1 bypass that gets caught at consumer push time.
 5. **Parse the Codex output** — extract structured findings.
 6. **Classify findings** by category: security, correctness, edge cases, test gaps, API design, performance.
 7. **Assign verdict**: `pass` (no material findings), `concerns` (findings worth addressing but not blocking), `blocking` (findings that must be fixed before merge).
-8. **Emit an audit entry — REQUIRED** for every `/codex-review` invocation. The pre-push gate does not consult audit records to decide pass/fail (post-0.11.0 the gate is stateless), but the `/codex-review` slash command's Step 3 verifies an audit entry was appended for this run and surfaces "review never happened" to the user when one is missing. The two specs are a contract pair — audit emission is what tells the operator their interactive review actually completed. Append via the public `@bookedsolid/rea/audit` helper:
+8. **Emit an audit entry — REQUIRED** for every `/codex-review` invocation. This is one of three identical contract checkpoints:
+   - The runtime always emits (`src/hooks/push-gate/index.ts` calls `appendAuditRecord` via `safeAppend` on every completed review — see `EVT_REVIEWED`).
+   - This agent always emits (this step).
+   - The `/codex-review` slash command's Step 3 verifies the entry exists and surfaces "review never happened" as a failure if it does not.
+
+   The pre-push gate does not consult audit records to decide pass/fail (post-0.11.0 the gate is stateless), but the audit record is still the operator's only forensic trail for an interactive review. Without it, "did this review actually happen" becomes unanswerable. Reconciled in 0.18.0 (helixir Finding #6 across cycles 1–7) so the three documents — `commands/codex-review.md`, `agents/codex-adversarial.md`, `src/hooks/push-gate/index.ts` — describe the same contract in identical wording. Append via the public `@bookedsolid/rea/audit` helper:
 
    ```ts
    import { appendAuditRecord, CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, Tier, InvocationStatus } from '@bookedsolid/rea/audit';

package/commands/codex-review.md

@@ -55,17 +55,21 @@ Invoke the `codex-adversarial` agent with:
 
 The agent wraps `/codex:adversarial-review` and returns structured findings.
 
-## Step 3 — (Optional) verify audit entry
+## Step 3 — Verify audit entry — REQUIRED
 
-Audit emission is **optional** in 0.11.0+. The pre-push gate is stateless and does not consult audit records to decide pass/fail; the agent's structured findings ARE the review. The agent will append an audit entry when it helps forensic traceability (intermittent verdicts, review-history audits) but its absence is not a failure.
+The `codex-adversarial` agent **MUST** emit an audit entry for every invocation. This is the same contract documented in `agents/codex-adversarial.md` Step 4 and matches the runtime behavior of `rea hook push-gate` (which always calls `appendAuditRecord` on a completed review — see `src/hooks/push-gate/index.ts`'s `EVT_REVIEWED` path).
 
-If you want to confirm an entry was written for this run:
+Verify the entry was written:
 
 ```bash
 tail -n 1 .rea/audit.jsonl
 ```
 
-A `codex-adversarial-review` entry with `head_sha`, `target`, `finding_count`, and `verdict` fields is informative — but DO NOT treat its absence as a failure. The review happened if the agent returned text. (Pre-0.15.0 this step was a hard verification gate that contradicted the agent's "audit optional" contract — see Helix Finding 3, 2026-05-03.)
+The expected entry has `tool_name: "codex.review"`, `server_name: "codex"`, and `metadata` containing `head_sha`, `target`, `finding_count`, and `verdict`. If the entry is missing, the review **did not complete its contract** — surface that to the user as a failure.
+
+**Why audit emission is required even though the pre-push gate is stateless:** the 0.11.0 push-gate decides pass/fail on Codex's live verdict, not on a receipt in the audit log — but the audit record is still the operator's only forensic trail for an interactive `/codex-review` run. Without it, "did this review actually happen" becomes unanswerable, which is exactly the failure mode helixir flagged across rounds 65/66/73 in the 0.13–0.17 cycle. Runtime always emits; the agent always emits; the slash command verifies. Three checkpoints, one contract.
+
+(Earlier docs in 0.15+ said this step was "optional"; that wording contradicted both the agent's Step 4 and the runtime behavior of `safeAppend` in `src/hooks/push-gate/index.ts`. Reconciled in 0.18.0 — helixir Finding #6 across cycles 1–7.)
 
 ## Step 4 — Report
 

package/dist/cli/init.js

@@ -297,6 +297,23 @@ function writePolicyYaml(targetDir, config, layered) {
             lines.push(`  max_bash_output_lines: ${cp.max_bash_output_lines}`);
         }
     }
+    // 0.18.1+ helixir #9: emit audit.rotation when the layered profile
+    // declared it. Empty `rotation: {}` opts in to documented defaults
+    // (50 MiB / 30 days); explicit values override.
+    if (layered.audit !== undefined) {
+        lines.push(`audit:`);
+        if (layered.audit.rotation !== undefined) {
+            const rot = layered.audit.rotation;
+            const hasFields = rot.max_bytes !== undefined || rot.max_age_days !== undefined;
+            lines.push(hasFields ? `  rotation:` : `  rotation: {}`);
+            if (rot.max_bytes !== undefined) {
+                lines.push(`    max_bytes: ${rot.max_bytes}`);
+            }
+            if (rot.max_age_days !== undefined) {
+                lines.push(`    max_age_days: ${rot.max_age_days}`);
+            }
+        }
+    }
     // G11.4: always emit the review block explicitly. Making the value
     // visible in the generated file helps the operator notice what was
     // chosen at init time and simplifies switching modes later (edit a

package/dist/cli/upgrade.js

@@ -635,7 +635,22 @@ export async function runUpgrade(options = {}) {
     }
     const now = new Date().toISOString();
     const installedAt = existingManifest?.installed_at ?? now;
-    const profile = existingManifest?.profile ?? 'unknown';
+    // 0.18.0 helix-020 G6 fix: pre-fix the upgrade path read profile from
+    // the existing manifest only — and pre-0.2.0 manifests recorded
+    // `"unknown"` as a placeholder. Every subsequent `rea upgrade` then
+    // re-stamped `"unknown"` forever. Authoritative source for the
+    // profile is `.rea/policy.yaml`; the manifest is a derivative
+    // record. Read policy first; fall back to existing manifest only
+    // when policy load fails (covers the bootstrap case where the
+    // manifest exists but policy is malformed).
+    let profile;
+    try {
+        const livePolicy = loadPolicy(resolvedRoot);
+        profile = livePolicy.profile;
+    }
+    catch {
+        profile = existingManifest?.profile ?? 'unknown';
+    }
     const freshManifest = {
         version: getPkgVersion(),
         profile,

package/dist/hooks/push-gate/codex-runner.js

@@ -136,18 +136,29 @@ function escapeTomlString(value) {
  */
 export async function runCodexReview(options) {
     const spawner = options.spawnImpl ?? spawn;
+    // 0.18.0 iron-gate runtime default: ALWAYS pass model + reasoning
+    // effort to codex. Pre-fix, undefined options fell back to codex's
+    // own default (`codex-auto-review` at medium reasoning), which
+    // bypassed the iron-gate intent and let weaker reviews ship. Now
+    // the runtime hardcodes `gpt-5.4` + `high` as the floor; policy
+    // can OVERRIDE to a different model/effort but cannot opt out into
+    // codex's defaults (config.toml or otherwise). The user's directive
+    // — "we want codex to be using its BEST. EVERY TIME" — is enforced
+    // here, not at the policy layer.
+    //
     // Model + reasoning overrides go BEFORE the `exec` subcommand because
     // `-c key=value` is a top-level codex CLI flag, not an `exec` flag.
     // Codex's TOML parser interprets the value, so we wrap strings in TOML
     // quotes — `-c model="gpt-5.4"` not `-c model=gpt-5.4` — to ensure the
     // value lands as a string regardless of upstream parsing changes.
-    const overrideArgs = [];
-    if (options.model !== undefined && options.model.length > 0) {
-        overrideArgs.push('-c', `model="${escapeTomlString(options.model)}"`);
-    }
-    if (options.reasoningEffort !== undefined) {
-        overrideArgs.push('-c', `model_reasoning_effort="${escapeTomlString(options.reasoningEffort)}"`);
-    }
+    const effectiveModel = options.model !== undefined && options.model.length > 0 ? options.model : 'gpt-5.4';
+    const effectiveReasoning = options.reasoningEffort ?? 'high';
+    const overrideArgs = [
+        '-c',
+        `model="${escapeTomlString(effectiveModel)}"`,
+        '-c',
+        `model_reasoning_effort="${escapeTomlString(effectiveReasoning)}"`,
+    ];
     const baseArgs = [
         ...overrideArgs,
         'exec',

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

@@ -30,6 +30,7 @@ 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';
+import { isFlip, lookupVerdict, writeVerdict, } from './verdict-cache.js';
 /**
  * Parse the raw pre-push stdin text into refspecs. Each line is four
  * whitespace-separated fields. Blank lines and malformed lines are
@@ -72,6 +73,8 @@ 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';
+const EVT_CACHE_HIT = 'rea.push_gate.cache_hit';
+const EVT_VERDICT_FLIP = 'rea.push_gate.verdict_flip';
 // ---------------------------------------------------------------------------
 // Composer
 // ---------------------------------------------------------------------------
@@ -335,7 +338,46 @@ export async function runPushGate(deps) {
             headSha,
         };
     }
-    // 6. Run Codex. Typed errors translate to exit 2 with distinct stderr.
+    // 6a. Verdict cache lookup (0.18.1 helixir #1, #4, #7, #8). Same-SHA
+    // pushes within the configured TTL skip the codex invocation and
+    // reuse the cached verdict — durable PASS. Cache is bypassed when
+    // policy.review.cache_ttl_ms is 0. Cache miss / expired falls
+    // through to the codex call below.
+    const cacheLookup = policy.cache_ttl_ms > 0 ? lookupVerdict(deps.baseDir, headSha) : { hit: false };
+    if (cacheLookup.hit && cacheLookup.entry !== undefined) {
+        const cached = cacheLookup.entry;
+        const cachedBlocked = cached.verdict === 'blocking'
+            || (cached.verdict === 'concerns' && policy.concerns_blocks && !isConcernsOverrideSet(env));
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_CACHE_HIT, {
+            verdict: cached.verdict,
+            finding_count: cached.finding_count,
+            base_ref: base.ref,
+            base_source: base.source,
+            head_sha: headSha,
+            cached_reviewed_at: cached.reviewed_at,
+            cached_model: cached.model,
+            cached_reasoning_effort: cached.reasoning_effort,
+            blocked: cachedBlocked,
+        });
+        return {
+            status: cachedBlocked
+                ? cached.verdict === 'blocking'
+                    ? 'blocking'
+                    : 'concerns'
+                : cached.verdict === 'blocking'
+                    ? 'blocking'
+                    : cached.verdict === 'concerns'
+                        ? 'concerns'
+                        : 'pass',
+            exitCode: cachedBlocked ? 2 : 0,
+            summary: `${cached.verdict}: ${cached.finding_count} finding(s) (cached)`,
+            verdict: cached.verdict,
+            findingCount: cached.finding_count,
+            baseRef: base.ref,
+            headSha,
+        };
+    }
+    // 6b. Run Codex. Typed errors translate to exit 2 with distinct stderr.
     try {
         const codexResult = await runCodexFn({
             baseRef: base.ref,
@@ -372,6 +414,40 @@ export async function runPushGate(deps) {
             blocked,
             lastReviewPath,
         }));
+        // 0.18.1 verdict cache write + flip detection. The lookup at step
+        // 6a already returned miss/expired; if `cacheLookup.entry` is set,
+        // a stale entry existed — compare its verdict to the fresh one and
+        // emit a flip event when they differ. Operators can grep
+        // `rea.push_gate.verdict_flip` in the audit log to detect codex
+        // non-determinism (helixir #8).
+        if (policy.cache_ttl_ms > 0) {
+            const flipped = isFlip(cacheLookup.entry, summary.verdict);
+            if (flipped && cacheLookup.entry !== undefined) {
+                await safeAppend(appendAuditFn, deps.baseDir, EVT_VERDICT_FLIP, {
+                    head_sha: headSha,
+                    prior_verdict: cacheLookup.entry.verdict,
+                    fresh_verdict: summary.verdict,
+                    prior_reviewed_at: cacheLookup.entry.reviewed_at,
+                    base_ref: base.ref,
+                });
+            }
+            const entry = {
+                verdict: summary.verdict,
+                finding_count: summary.findings.length,
+                reviewed_at: deps.now !== undefined ? deps.now().toISOString() : new Date().toISOString(),
+                model: policy.codex_model ?? 'gpt-5.4',
+                reasoning_effort: policy.codex_reasoning_effort ?? 'high',
+                ttl_ms: policy.cache_ttl_ms,
+            };
+            try {
+                writeVerdict(deps.baseDir, headSha, entry);
+            }
+            catch {
+                // Cache writes are best-effort. A failure here must NOT
+                // affect the verdict — log to stderr (already done by the
+                // caller via banner) and proceed.
+            }
+        }
         await safeAppend(appendAuditFn, deps.baseDir, EVT_REVIEWED, {
             verdict: summary.verdict,
             finding_count: summary.findings.length,
@@ -386,6 +462,9 @@ export async function runPushGate(deps) {
             last_n_commits_requested: base.lastNCommitsRequested,
             auto_narrowed: autoNarrowed ? true : undefined,
             original_commit_count: originalCommitCount !== null ? originalCommitCount : undefined,
+            flipped: cacheLookup.entry !== undefined && isFlip(cacheLookup.entry, summary.verdict)
+                ? true
+                : undefined,
         });
         if (blocked) {
             return {

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

@@ -56,6 +56,12 @@ export interface ResolvedReviewPolicy {
      * codex's own default (currently `medium`).
      */
     codex_reasoning_effort: 'low' | 'medium' | 'high' | undefined;
+    /**
+     * Verdict cache TTL in milliseconds (0.18.1+). `0` disables caching;
+     * positive values enable the same-SHA short-circuit. Default 86_400_000
+     * (24 hours) when policy.review.cache_ttl_ms is unset.
+     */
+    cache_ttl_ms: number;
     /** `true` when `.rea/policy.yaml` was absent; defaults apply. */
     policyMissing: boolean;
 }
@@ -97,6 +103,17 @@ export declare const PUSH_GATE_DEFAULT_CODEX_MODEL = "gpt-5.4";
  * `.rea/policy.yaml` for cost-bounded environments.
  */
 export declare const PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT: 'low' | 'medium' | 'high';
+/**
+ * Default verdict-cache TTL in milliseconds (0.18.1+). 24 hours: long
+ * enough to amortize multi-push iteration of the same SHA (push, push
+ * --force-with-lease after a quick fixup, push again post-rebase),
+ * short enough that a stale cache from yesterday doesn't suppress
+ * review of code whose context (env, dependencies, .rea/policy.yaml)
+ * has changed. Operators can shorten to a few minutes for tighter
+ * loops or extend via `policy.review.cache_ttl_ms`. `0` disables
+ * caching — every push re-invokes codex (pre-0.18.1 behavior).
+ */
+export declare const PUSH_GATE_DEFAULT_CACHE_TTL_MS: number;
 /**
  * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
  * policy file surfaces as a typed error via the underlying zod validator,

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

@@ -66,6 +66,17 @@ export const PUSH_GATE_DEFAULT_CODEX_MODEL = 'gpt-5.4';
  * `.rea/policy.yaml` for cost-bounded environments.
  */
 export const PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT = 'high';
+/**
+ * Default verdict-cache TTL in milliseconds (0.18.1+). 24 hours: long
+ * enough to amortize multi-push iteration of the same SHA (push, push
+ * --force-with-lease after a quick fixup, push again post-rebase),
+ * short enough that a stale cache from yesterday doesn't suppress
+ * review of code whose context (env, dependencies, .rea/policy.yaml)
+ * has changed. Operators can shorten to a few minutes for tighter
+ * loops or extend via `policy.review.cache_ttl_ms`. `0` disables
+ * caching — every push re-invokes codex (pre-0.18.1 behavior).
+ */
+export const PUSH_GATE_DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
 /**
  * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
  * policy file surfaces as a typed error via the underlying zod validator,
@@ -87,6 +98,7 @@ export async function resolvePushGatePolicy(baseDir) {
             auto_narrow_threshold: PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD,
             codex_model: PUSH_GATE_DEFAULT_CODEX_MODEL,
             codex_reasoning_effort: PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT,
+            cache_ttl_ms: PUSH_GATE_DEFAULT_CACHE_TTL_MS,
             policyMissing: true,
         };
     }
@@ -100,6 +112,7 @@ export async function resolvePushGatePolicy(baseDir) {
         auto_narrow_threshold: review.auto_narrow_threshold ?? PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD,
         codex_model: review.codex_model ?? PUSH_GATE_DEFAULT_CODEX_MODEL,
         codex_reasoning_effort: review.codex_reasoning_effort ?? PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT,
+        cache_ttl_ms: review.cache_ttl_ms ?? PUSH_GATE_DEFAULT_CACHE_TTL_MS,
         policyMissing: false,
     };
 }

package/dist/hooks/push-gate/verdict-cache.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Durable verdict cache for the push-gate (helixir #1, #4, #7, #8 / 0.18.1).
+ *
+ * Pre-0.18.1 the push-gate was strictly stateless: every push of the same
+ * `head_sha` invoked `codex exec review` afresh. helixir round 82 reproduced
+ * the failure mode — push #1 of `9fbdfb63` returned PASS, push #2 of the
+ * IDENTICAL commit returned CONCERNS — 1 P2. The verdict instability is
+ * a property of codex's stochastic decoding at `reasoning_effort: high`;
+ * rea cannot eliminate it, but rea CAN make a clean PASS DURABLE so the
+ * second push of the same SHA doesn't roll the dice again.
+ *
+ * Design:
+ *
+ *   .rea/last-review.cache.json
+ *   {
+ *     schema_version: 2,
+ *     entries: {
+ *       "<head_sha>": {
+ *         verdict: "pass" | "concerns" | "blocking",
+ *         finding_count: number,
+ *         reviewed_at: ISO8601,
+ *         model: string,
+ *         reasoning_effort: "low" | "medium" | "high",
+ *         ttl_ms: number,                 // policy.review.cache_ttl_ms at write time
+ *       },
+ *       ...
+ *     }
+ *   }
+ *
+ *   - Hit (within TTL): emit `rea.push_gate.cache_hit` audit event, exit
+ *     with the cached verdict + finding count; codex is NOT invoked.
+ *   - Miss or expired: invoke codex; on success, write the new entry.
+ *   - Flip detection: if a new codex result on the same SHA produces a
+ *     verdict different from the cached one, set `last-review.json.flip_flag = true`,
+ *     emit `rea.push_gate.verdict_flip`, and overwrite the cache with
+ *     the fresh result. Operators can detect non-determinism from the
+ *     audit log alone (helixir #8).
+ *   - REA_SKIP_CODEX_REVIEW short-circuits BEFORE cache lookup (unchanged).
+ *
+ * The cache is OPTIONAL by design: existing callers that don't pass a
+ * `cacheImpl` get the legacy stateless path. Tests inject a fake.
+ */
+import type { Verdict as ReviewVerdict } from './findings.js';
+export declare const VERDICT_CACHE_FILE = "last-review.cache.json";
+export declare const VERDICT_CACHE_SCHEMA_VERSION: 2;
+export declare const DEFAULT_CACHE_TTL_MS: number;
+export interface VerdictCacheEntry {
+    verdict: ReviewVerdict;
+    finding_count: number;
+    reviewed_at: string;
+    model: string;
+    reasoning_effort: 'low' | 'medium' | 'high';
+    ttl_ms: number;
+}
+export interface VerdictCacheLookupResult {
+    /** True if a non-expired entry exists for this SHA. */
+    hit: boolean;
+    /** The entry, present on both hit and miss-of-stale-entry. Used for flip detection. */
+    entry?: VerdictCacheEntry;
+    /** True if the entry exists but is past TTL. */
+    expired?: boolean;
+}
+/**
+ * Read the cache file and look up `head_sha`. Missing file, malformed
+ * JSON, missing entry, and unsupported schema_version all resolve to a
+ * miss with `entry: undefined` — the caller proceeds to codex.
+ */
+export declare function lookupVerdict(baseDir: string, headSha: string, now?: Date): VerdictCacheLookupResult;
+/**
+ * Write a fresh verdict entry. Atomic via tmp-file + rename. Unrecognized
+ * pre-existing entries are preserved (forward-compat for v3+).
+ */
+export declare function writeVerdict(baseDir: string, headSha: string, entry: VerdictCacheEntry): void;
+/**
+ * Detect whether a new verdict contradicts a previously-cached verdict
+ * on the same SHA. Used by `runPushGate` to set the flip-flag on
+ * last-review.json and emit the `verdict_flip` audit event.
+ */
+export declare function isFlip(prior: VerdictCacheEntry | undefined, fresh: ReviewVerdict): boolean;
+/**
+ * Remove a single SHA from the cache. Returns true if the entry existed.
+ */
+export declare function clearVerdict(baseDir: string, headSha: string): boolean;
+/**
+ * Remove ALL entries from the cache. Returns the count of removed entries.
+ */
+export declare function clearAll(baseDir: string): number;
+/**
+ * Remove entries whose `reviewed_at` is older than `olderThanMs` from `now`.
+ * Returns the count of removed entries.
+ */
+export declare function pruneOlderThan(baseDir: string, olderThanMs: number, now?: Date): number;
+/**
+ * Read all entries (used by `rea cache stats` / `rea cache show`).
+ * Returns empty object on any read error (missing file, malformed JSON,
+ * unsupported schema_version).
+ */
+export declare function listEntries(baseDir: string): Record<string, VerdictCacheEntry>;

package/dist/hooks/push-gate/verdict-cache.js

@@ -0,0 +1,190 @@
+/**
+ * Durable verdict cache for the push-gate (helixir #1, #4, #7, #8 / 0.18.1).
+ *
+ * Pre-0.18.1 the push-gate was strictly stateless: every push of the same
+ * `head_sha` invoked `codex exec review` afresh. helixir round 82 reproduced
+ * the failure mode — push #1 of `9fbdfb63` returned PASS, push #2 of the
+ * IDENTICAL commit returned CONCERNS — 1 P2. The verdict instability is
+ * a property of codex's stochastic decoding at `reasoning_effort: high`;
+ * rea cannot eliminate it, but rea CAN make a clean PASS DURABLE so the
+ * second push of the same SHA doesn't roll the dice again.
+ *
+ * Design:
+ *
+ *   .rea/last-review.cache.json
+ *   {
+ *     schema_version: 2,
+ *     entries: {
+ *       "<head_sha>": {
+ *         verdict: "pass" | "concerns" | "blocking",
+ *         finding_count: number,
+ *         reviewed_at: ISO8601,
+ *         model: string,
+ *         reasoning_effort: "low" | "medium" | "high",
+ *         ttl_ms: number,                 // policy.review.cache_ttl_ms at write time
+ *       },
+ *       ...
+ *     }
+ *   }
+ *
+ *   - Hit (within TTL): emit `rea.push_gate.cache_hit` audit event, exit
+ *     with the cached verdict + finding count; codex is NOT invoked.
+ *   - Miss or expired: invoke codex; on success, write the new entry.
+ *   - Flip detection: if a new codex result on the same SHA produces a
+ *     verdict different from the cached one, set `last-review.json.flip_flag = true`,
+ *     emit `rea.push_gate.verdict_flip`, and overwrite the cache with
+ *     the fresh result. Operators can detect non-determinism from the
+ *     audit log alone (helixir #8).
+ *   - REA_SKIP_CODEX_REVIEW short-circuits BEFORE cache lookup (unchanged).
+ *
+ * The cache is OPTIONAL by design: existing callers that don't pass a
+ * `cacheImpl` get the legacy stateless path. Tests inject a fake.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export const VERDICT_CACHE_FILE = 'last-review.cache.json';
+export const VERDICT_CACHE_SCHEMA_VERSION = 2;
+export const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1_000; // 24h
+/**
+ * Read the cache file and look up `head_sha`. Missing file, malformed
+ * JSON, missing entry, and unsupported schema_version all resolve to a
+ * miss with `entry: undefined` — the caller proceeds to codex.
+ */
+export function lookupVerdict(baseDir, headSha, now = new Date()) {
+    const file = readCacheFile(baseDir);
+    if (file === undefined)
+        return { hit: false };
+    const entry = file.entries[headSha];
+    if (entry === undefined)
+        return { hit: false };
+    const reviewedAtMs = Date.parse(entry.reviewed_at);
+    if (Number.isNaN(reviewedAtMs))
+        return { hit: false, entry };
+    const ageMs = now.getTime() - reviewedAtMs;
+    if (ageMs >= entry.ttl_ms) {
+        return { hit: false, entry, expired: true };
+    }
+    return { hit: true, entry };
+}
+/**
+ * Write a fresh verdict entry. Atomic via tmp-file + rename. Unrecognized
+ * pre-existing entries are preserved (forward-compat for v3+).
+ */
+export function writeVerdict(baseDir, headSha, entry) {
+    const reaDir = path.join(baseDir, '.rea');
+    if (!fs.existsSync(reaDir)) {
+        fs.mkdirSync(reaDir, { recursive: true });
+    }
+    const cachePath = path.join(reaDir, VERDICT_CACHE_FILE);
+    const existing = readCacheFile(baseDir);
+    const next = {
+        schema_version: VERDICT_CACHE_SCHEMA_VERSION,
+        entries: { ...(existing?.entries ?? {}), [headSha]: entry },
+    };
+    const tmp = `${cachePath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, cachePath);
+}
+/**
+ * Detect whether a new verdict contradicts a previously-cached verdict
+ * on the same SHA. Used by `runPushGate` to set the flip-flag on
+ * last-review.json and emit the `verdict_flip` audit event.
+ */
+export function isFlip(prior, fresh) {
+    if (prior === undefined)
+        return false;
+    return prior.verdict !== fresh;
+}
+/**
+ * Remove a single SHA from the cache. Returns true if the entry existed.
+ */
+export function clearVerdict(baseDir, headSha) {
+    const file = readCacheFile(baseDir);
+    if (file === undefined || file.entries[headSha] === undefined)
+        return false;
+    const next = {
+        schema_version: VERDICT_CACHE_SCHEMA_VERSION,
+        entries: { ...file.entries },
+    };
+    delete next.entries[headSha];
+    const cachePath = path.join(baseDir, '.rea', VERDICT_CACHE_FILE);
+    fs.writeFileSync(cachePath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return true;
+}
+/**
+ * Remove ALL entries from the cache. Returns the count of removed entries.
+ */
+export function clearAll(baseDir) {
+    const file = readCacheFile(baseDir);
+    const cachePath = path.join(baseDir, '.rea', VERDICT_CACHE_FILE);
+    const count = file === undefined ? 0 : Object.keys(file.entries).length;
+    const empty = {
+        schema_version: VERDICT_CACHE_SCHEMA_VERSION,
+        entries: {},
+    };
+    if (!fs.existsSync(path.dirname(cachePath))) {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    }
+    fs.writeFileSync(cachePath, `${JSON.stringify(empty, null, 2)}\n`, 'utf8');
+    return count;
+}
+/**
+ * Remove entries whose `reviewed_at` is older than `olderThanMs` from `now`.
+ * Returns the count of removed entries.
+ */
+export function pruneOlderThan(baseDir, olderThanMs, now = new Date()) {
+    const file = readCacheFile(baseDir);
+    if (file === undefined)
+        return 0;
+    const cutoff = now.getTime() - olderThanMs;
+    const surviving = {};
+    let removed = 0;
+    for (const [sha, entry] of Object.entries(file.entries)) {
+        const reviewedAtMs = Date.parse(entry.reviewed_at);
+        if (Number.isNaN(reviewedAtMs) || reviewedAtMs >= cutoff) {
+            surviving[sha] = entry;
+        }
+        else {
+            removed += 1;
+        }
+    }
+    if (removed === 0)
+        return 0;
+    const next = {
+        schema_version: VERDICT_CACHE_SCHEMA_VERSION,
+        entries: surviving,
+    };
+    const cachePath = path.join(baseDir, '.rea', VERDICT_CACHE_FILE);
+    fs.writeFileSync(cachePath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return removed;
+}
+/**
+ * Read all entries (used by `rea cache stats` / `rea cache show`).
+ * Returns empty object on any read error (missing file, malformed JSON,
+ * unsupported schema_version).
+ */
+export function listEntries(baseDir) {
+    const file = readCacheFile(baseDir);
+    return file?.entries ?? {};
+}
+function readCacheFile(baseDir) {
+    const cachePath = path.join(baseDir, '.rea', VERDICT_CACHE_FILE);
+    if (!fs.existsSync(cachePath))
+        return undefined;
+    try {
+        const raw = fs.readFileSync(cachePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            parsed.schema_version !== VERDICT_CACHE_SCHEMA_VERSION) {
+            return undefined;
+        }
+        const entries = parsed.entries;
+        if (typeof entries !== 'object' || entries === null)
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}