@bookedsolid/rea 0.18.0 → 0.20.0

package/.husky/commit-msg

@@ -86,9 +86,9 @@ MATCHES=""
 # 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
+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|mistral\.ai|xai-org|x\.ai|inflection\.ai|perplexity\.ai|replit\.com|jetbrains\.com|bito\.ai|pieces\.app|phind\.com|you\.com)' "$COMMIT_MSG_FILE" 2>/dev/null; then
   BLOCKED=1
-  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)
+  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|mistral\.ai|xai-org|x\.ai|inflection\.ai|perplexity\.ai|replit\.com|jetbrains\.com|bito\.ai|pieces\.app|phind\.com|you\.com)' "$COMMIT_MSG_FILE" 2>/dev/null)
 "
 fi
 

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/hooks/push-gate/codex-runner.d.ts

@@ -19,6 +19,23 @@
  * and so the one git dependency surface is in one place.
  */
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+/**
+ * Default codex model when policy doesn't pin one. Always passed via
+ * `-c model="<name>"` so codex's own default (`codex-auto-review` at
+ * medium reasoning) is unreachable through the rea push-gate.
+ *
+ * 0.19.0 code-reviewer P3-4: exported as a single source of truth.
+ * `src/hooks/push-gate/index.ts` imports this for the verdict-cache
+ * write so the cached `model` field reflects the same constant the
+ * runner actually used. Bump here to bump everywhere.
+ */
+export declare const IRON_GATE_DEFAULT_MODEL = "gpt-5.4";
+/**
+ * Default reasoning effort when policy doesn't pin one. `high` for
+ * verdict stability — the helixir 2026-04-26 thrashing came from the
+ * lower-reasoning default.
+ */
+export declare const IRON_GATE_DEFAULT_REASONING: 'low' | 'medium' | 'high';
 export declare class CodexNotInstalledError extends Error {
     readonly kind: "not-installed";
     constructor();

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

@@ -20,6 +20,26 @@
  */
 import { spawn, spawnSync } from 'node:child_process';
 // ---------------------------------------------------------------------------
+// Iron-gate runtime defaults (0.18.0+)
+// ---------------------------------------------------------------------------
+/**
+ * Default codex model when policy doesn't pin one. Always passed via
+ * `-c model="<name>"` so codex's own default (`codex-auto-review` at
+ * medium reasoning) is unreachable through the rea push-gate.
+ *
+ * 0.19.0 code-reviewer P3-4: exported as a single source of truth.
+ * `src/hooks/push-gate/index.ts` imports this for the verdict-cache
+ * write so the cached `model` field reflects the same constant the
+ * runner actually used. Bump here to bump everywhere.
+ */
+export const IRON_GATE_DEFAULT_MODEL = 'gpt-5.4';
+/**
+ * Default reasoning effort when policy doesn't pin one. `high` for
+ * verdict stability — the helixir 2026-04-26 thrashing came from the
+ * lower-reasoning default.
+ */
+export const IRON_GATE_DEFAULT_REASONING = 'high';
+// ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
 export class CodexNotInstalledError extends Error {
@@ -151,8 +171,10 @@ export async function runCodexReview(options) {
     // 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 effectiveModel = options.model !== undefined && options.model.length > 0 ? options.model : 'gpt-5.4';
-    const effectiveReasoning = options.reasoningEffort ?? 'high';
+    const effectiveModel = options.model !== undefined && options.model.length > 0
+        ? options.model
+        : IRON_GATE_DEFAULT_MODEL;
+    const effectiveReasoning = options.reasoningEffort ?? IRON_GATE_DEFAULT_REASONING;
     const overrideArgs = [
         '-c',
         `model="${escapeTomlString(effectiveModel)}"`,

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

@@ -23,13 +23,15 @@
  */
 import path from 'node:path';
 import { appendAuditRecord } from '../../audit/append.js';
+import { loadPolicyAsync } from '../../policy/loader.js';
 import { Tier, InvocationStatus } from '../../policy/types.js';
 import { resolvePushGatePolicy, PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK, } 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 { createRealGitExecutor, runCodexReview, CodexNotInstalledError, CodexProtocolError, CodexSubprocessError, CodexTimeoutError, IRON_GATE_DEFAULT_MODEL, IRON_GATE_DEFAULT_REASONING, } 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 +74,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
 // ---------------------------------------------------------------------------
@@ -84,13 +88,27 @@ export async function runPushGate(deps) {
     const runCodexFn = deps.runCodex ?? runCodexReview;
     const appendAuditFn = deps.appendAudit ?? appendAuditRecord;
     const git = deps.git ?? createRealGitExecutor(deps.baseDir);
+    // 0.19.0 backend-engineer review P1-1: load the full Policy once and
+    // thread it to every safeAppend so audit rotation actually fires.
+    // Pre-fix the rotator short-circuited because policy was never passed
+    // through, silently disabling the `audit.rotation: {}` opt-in shipped
+    // in 0.18.1 for the bst-internal profile. A failure to load policy
+    // here is non-fatal — the gate continues; audit rotation just stays
+    // disabled for this run (back-compat).
+    let fullPolicy;
+    try {
+        fullPolicy = await loadPolicyAsync(deps.baseDir);
+    }
+    catch {
+        fullPolicy = undefined;
+    }
     // 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, {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_HALTED, fullPolicy, {
             reason: halt.reason ?? 'unknown',
         });
         return {
@@ -108,14 +126,14 @@ export async function runPushGate(deps) {
     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, {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, fullPolicy, {
             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, {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_DISABLED, fullPolicy, {
             policy_missing: policy.policyMissing,
         });
         return {
@@ -153,7 +171,7 @@ export async function runPushGate(deps) {
         const skipVar = skipPush.length > 0 ? 'REA_SKIP_PUSH_GATE' : 'REA_SKIP_CODEX_REVIEW';
         const skipReason = skipVar === 'REA_SKIP_PUSH_GATE' ? skipPush : skipCodex;
         stderr(`rea: ${skipVar}=${skipReason} — push-gate skipped (audited).\n`);
-        await safeAppend(appendAuditFn, deps.baseDir, EVT_SKIPPED, {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_SKIPPED, fullPolicy, {
             reason: skipReason,
             skip_var: skipVar,
         });
@@ -248,7 +266,7 @@ export async function runPushGate(deps) {
     }
     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' });
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, fullPolicy, { kind: 'head-sha-missing' });
         return { status: 'error', exitCode: 2, summary: 'head-sha-missing' };
     }
     // 4b. Auto-narrow probe (J / 0.13.0). When the resolved base is far
@@ -318,7 +336,7 @@ export async function runPushGate(deps) {
     //    no-op relative to base.
     const diff = git.diffNames(base.ref, headSha);
     if (diff.length === 0) {
-        await safeAppend(appendAuditFn, deps.baseDir, EVT_EMPTY, {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_EMPTY, fullPolicy, {
             base_ref: base.ref,
             base_source: base.source,
             head_sha: headSha,
@@ -335,7 +353,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, fullPolicy, {
+            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,7 +429,43 @@ export async function runPushGate(deps) {
             blocked,
             lastReviewPath,
         }));
-        await safeAppend(appendAuditFn, deps.baseDir, EVT_REVIEWED, {
+        // 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, fullPolicy, {
+                    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 ?? IRON_GATE_DEFAULT_MODEL,
+                reasoning_effort: policy.codex_reasoning_effort ?? IRON_GATE_DEFAULT_REASONING,
+                ttl_ms: policy.cache_ttl_ms,
+            };
+            try {
+                await 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. Foreign-schema (v3+ cache
+                // from a future rea version) lands here and is correctly
+                // declined — overwriting would lose forward-compat data.
+            }
+        }
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_REVIEWED, fullPolicy, {
             verdict: summary.verdict,
             finding_count: summary.findings.length,
             base_ref: base.ref,
@@ -386,6 +479,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 {
@@ -413,7 +509,7 @@ export async function runPushGate(deps) {
         };
     }
     catch (e) {
-        return handleCodexError(e, deps, base, headSha, appendAuditFn);
+        return handleCodexError(e, deps, base, headSha, appendAuditFn, fullPolicy);
     }
 }
 function isConcernsOverrideSet(env) {
@@ -423,7 +519,7 @@ function isConcernsOverrideSet(env) {
     const normalized = raw.trim().toLowerCase();
     return normalized === '1' || normalized === 'true' || normalized === 'yes';
 }
-async function handleCodexError(e, deps, base, headSha, appendAuditFn) {
+async function handleCodexError(e, deps, base, headSha, appendAuditFn, policy) {
     const stderr = deps.stderr;
     const runError = classifyCodexError(e);
     const metadata = {
@@ -435,7 +531,7 @@ async function handleCodexError(e, deps, base, headSha, appendAuditFn) {
     if (runError.message.length > 0)
         metadata.error = runError.message;
     stderr(`PUSH BLOCKED: ${runError.message}\n`);
-    await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, metadata);
+    await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, policy, metadata);
     return {
         status: 'error',
         exitCode: 2,
@@ -463,7 +559,7 @@ function classifyCodexError(e) {
  * 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) {
+async function safeAppend(appendFn, baseDir, toolName, policy, metadata) {
     try {
         // Prune undefined values — the audit record schema's `metadata` is an
         // arbitrary map, but `undefined` values cause JSON.stringify to emit
@@ -473,12 +569,19 @@ async function safeAppend(appendFn, baseDir, toolName, metadata) {
             if (v !== undefined)
                 cleanMeta[k] = v;
         }
+        // 0.19.0 P1-1 fix (backend-engineer review): pass the loaded Policy
+        // through so `appendAuditRecord` → `maybeRotate` actually fires.
+        // Pre-fix the policy was never threaded; rotation short-circuited
+        // to `{ rotated: false }` on the entire push-gate audit-emission
+        // path, silently disabling the `audit.rotation: {}` opt-in shipped
+        // in 0.18.1 for the bst-internal profile.
         await appendFn(baseDir, {
             tool_name: toolName,
             server_name: AUDIT_SERVER_NAME,
             tier: Tier.Read,
             status: InvocationStatus.Allowed,
             ...(Object.keys(cleanMeta).length > 0 ? { metadata: cleanMeta } : {}),
+            ...(policy !== undefined ? { policy } : {}),
         });
     }
     catch (e) {

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,126 @@
+/**
+ * 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).
+ *
+ * 0.19.0 review fixes:
+ *   - Concurrent writes are now serialized via `withAuditLock` on the
+ *     `.rea/` directory (backend-engineer P1-2; security M3). Two
+ *     concurrent push-gate runs no longer race read-modify-write.
+ *   - Tmp filenames carry a high-entropy suffix (PID + millis + random)
+ *     and are unlinked in finally so a crash mid-write doesn't leave
+ *     stale state (backend-engineer P1-3; code-reviewer P2-1).
+ *   - All three writers (writeVerdict, clearVerdict, pruneOlderThan,
+ *     clearAll) route through one `_atomicWrite` helper — no asymmetry
+ *     between paths (code-reviewer P2-2).
+ *   - On unrecognized schema_version, reads return undefined AND
+ *     writes refuse to overwrite — the v3 cache stays intact for a
+ *     future rea version that knows how to read it (code-reviewer P3-5;
+ *     backend-engineer P2-2).
+ *
+ * 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;
+/**
+ * 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;
+/**
+ * Write a fresh verdict entry. Atomic via tmp-file + rename, serialized
+ * via `withAuditLock` on `.rea/`. Refuses to overwrite when the existing
+ * cache has an unrecognized schema_version (forward-compat — a v3 cache
+ * from a future rea version stays intact for that version to read).
+ */
+export declare function writeVerdict(baseDir: string, headSha: string, entry: VerdictCacheEntry): Promise<void>;
+/**
+ * Remove a single SHA from the cache. Returns true if the entry existed.
+ */
+export declare function clearVerdict(baseDir: string, headSha: string): Promise<boolean>;
+/**
+ * Remove ALL entries from the cache. Returns the count of removed entries.
+ */
+export declare function clearAll(baseDir: string): Promise<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): Promise<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>;
+/**
+ * Thrown by writeVerdict when the existing cache file has an
+ * unrecognized schema_version. The caller (push-gate) catches this
+ * and treats the write as best-effort failure (log to stderr,
+ * continue) rather than overwriting forward-compat data.
+ */
+export declare class VerdictCacheForeignSchemaError extends Error {
+    readonly cachePath: string;
+    readonly kind: "foreign-schema";
+    constructor(cachePath: string);
+}

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

@@ -0,0 +1,276 @@
+/**
+ * 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).
+ *
+ * 0.19.0 review fixes:
+ *   - Concurrent writes are now serialized via `withAuditLock` on the
+ *     `.rea/` directory (backend-engineer P1-2; security M3). Two
+ *     concurrent push-gate runs no longer race read-modify-write.
+ *   - Tmp filenames carry a high-entropy suffix (PID + millis + random)
+ *     and are unlinked in finally so a crash mid-write doesn't leave
+ *     stale state (backend-engineer P1-3; code-reviewer P2-1).
+ *   - All three writers (writeVerdict, clearVerdict, pruneOlderThan,
+ *     clearAll) route through one `_atomicWrite` helper — no asymmetry
+ *     between paths (code-reviewer P2-2).
+ *   - On unrecognized schema_version, reads return undefined AND
+ *     writes refuse to overwrite — the v3 cache stays intact for a
+ *     future rea version that knows how to read it (code-reviewer P3-5;
+ *     backend-engineer P2-2).
+ *
+ * The cache is OPTIONAL by design: existing callers that don't pass a
+ * `cacheImpl` get the legacy stateless path. Tests inject a fake.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { withAuditLock } from '../../audit/fs.js';
+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 };
+}
+/**
+ * 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;
+}
+/**
+ * Write a fresh verdict entry. Atomic via tmp-file + rename, serialized
+ * via `withAuditLock` on `.rea/`. Refuses to overwrite when the existing
+ * cache has an unrecognized schema_version (forward-compat — a v3 cache
+ * from a future rea version stays intact for that version to read).
+ */
+export async 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);
+    await withAuditLock(cachePath, async () => {
+        if (foreignSchemaPresent(baseDir)) {
+            throw new VerdictCacheForeignSchemaError(cachePath);
+        }
+        const existing = readCacheFile(baseDir);
+        const next = {
+            schema_version: VERDICT_CACHE_SCHEMA_VERSION,
+            entries: { ...(existing?.entries ?? {}), [headSha]: entry },
+        };
+        _atomicWriteJson(cachePath, next);
+    });
+}
+/**
+ * Remove a single SHA from the cache. Returns true if the entry existed.
+ */
+export async function clearVerdict(baseDir, headSha) {
+    const cachePath = path.join(baseDir, '.rea', VERDICT_CACHE_FILE);
+    return withAuditLock(cachePath, async () => {
+        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];
+        _atomicWriteJson(cachePath, next);
+        return true;
+    });
+}
+/**
+ * Remove ALL entries from the cache. Returns the count of removed entries.
+ */
+export async function clearAll(baseDir) {
+    const reaDir = path.join(baseDir, '.rea');
+    const cachePath = path.join(reaDir, VERDICT_CACHE_FILE);
+    if (!fs.existsSync(reaDir)) {
+        fs.mkdirSync(reaDir, { recursive: true });
+    }
+    return withAuditLock(cachePath, async () => {
+        const file = readCacheFile(baseDir);
+        const count = file === undefined ? 0 : Object.keys(file.entries).length;
+        const empty = {
+            schema_version: VERDICT_CACHE_SCHEMA_VERSION,
+            entries: {},
+        };
+        _atomicWriteJson(cachePath, empty);
+        return count;
+    });
+}
+/**
+ * Remove entries whose `reviewed_at` is older than `olderThanMs` from `now`.
+ * Returns the count of removed entries.
+ */
+export async function pruneOlderThan(baseDir, olderThanMs, now = new Date()) {
+    const cachePath = path.join(baseDir, '.rea', VERDICT_CACHE_FILE);
+    return withAuditLock(cachePath, async () => {
+        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,
+        };
+        _atomicWriteJson(cachePath, next);
+        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 ?? {};
+}
+/**
+ * Thrown by writeVerdict when the existing cache file has an
+ * unrecognized schema_version. The caller (push-gate) catches this
+ * and treats the write as best-effort failure (log to stderr,
+ * continue) rather than overwriting forward-compat data.
+ */
+export class VerdictCacheForeignSchemaError extends Error {
+    cachePath;
+    kind = 'foreign-schema';
+    constructor(cachePath) {
+        super(`Refused to overwrite ${cachePath}: existing cache has unrecognized schema_version. ` +
+            `Either delete the file or run with a newer rea that supports it.`);
+        this.cachePath = cachePath;
+        this.name = 'VerdictCacheForeignSchemaError';
+    }
+}
+function readCacheFile(baseDir) {
+    const parsed = readForeignCacheFile(baseDir);
+    if (parsed === undefined)
+        return undefined;
+    if (parsed.schema_version !== VERDICT_CACHE_SCHEMA_VERSION)
+        return undefined;
+    // We checked schema_version exactly; entries shape is the v2 contract.
+    return parsed;
+}
+function readForeignCacheFile(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)
+            return undefined;
+        const sv = parsed.schema_version;
+        if (typeof sv !== 'number')
+            return undefined;
+        const entries = parsed.entries;
+        if (typeof entries !== 'object' || entries === null)
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function foreignSchemaPresent(baseDir) {
+    const parsed = readForeignCacheFile(baseDir);
+    if (parsed === undefined)
+        return false;
+    return parsed.schema_version !== VERDICT_CACHE_SCHEMA_VERSION;
+}
+/**
+ * Atomic JSON write: stringify → write tmp → fsync → rename.
+ *
+ * Tmp filename: `${target}.tmp.${pid}.${ms}.${random8}` — collision-
+ * resistant under concurrent writes, PID reuse, and same-process
+ * parallel calls. On any failure, the tmp file is unlinked so a crash
+ * mid-write doesn't leave stale state.
+ */
+function _atomicWriteJson(targetPath, payload) {
+    const tmp = `${targetPath}.tmp.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString('hex')}`;
+    try {
+        fs.writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+        fs.renameSync(tmp, targetPath);
+    }
+    catch (e) {
+        try {
+            if (fs.existsSync(tmp))
+                fs.unlinkSync(tmp);
+        }
+        catch {
+            // Tmp already gone or unlink failed — caller's error is the
+            // important signal.
+        }
+        throw e;
+    }
+}

package/dist/policy/loader.d.ts

@@ -81,6 +81,15 @@ declare const PolicySchema: z.ZodObject<{
          * matters less than throughput.
          */
         codex_reasoning_effort: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+        /**
+         * Verdict cache TTL in milliseconds (0.18.1+ helixir #1, #4, #7, #8).
+         * Default 86_400_000 (24 hours). When a push of `head_sha` produces
+         * a non-blocking verdict, the result is written to
+         * `.rea/last-review.cache.json`. Subsequent pushes of the same SHA
+         * within the TTL skip the codex invocation and reuse the cached
+         * verdict. Set to 0 to disable caching (every push re-invokes codex).
+         */
+        cache_ttl_ms: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
@@ -89,6 +98,7 @@ declare const PolicySchema: z.ZodObject<{
         auto_narrow_threshold?: number | undefined;
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
+        cache_ttl_ms?: number | undefined;
     }, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
@@ -97,6 +107,7 @@ declare const PolicySchema: z.ZodObject<{
         auto_narrow_threshold?: number | undefined;
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
+        cache_ttl_ms?: number | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -196,6 +207,7 @@ declare const PolicySchema: z.ZodObject<{
         auto_narrow_threshold?: number | undefined;
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
+        cache_ttl_ms?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -245,6 +257,7 @@ declare const PolicySchema: z.ZodObject<{
         auto_narrow_threshold?: number | undefined;
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
+        cache_ttl_ms?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;

package/dist/policy/loader.js

@@ -58,7 +58,12 @@ const ReviewPolicySchema = z
      * NOT want to lock consumers to a hardcoded enum that drifts behind
      * upstream. Codex itself validates the model name at exec time.
      */
-    codex_model: z.string().min(1).optional(),
+    // 0.19.0 security review M4: restrict to a safe character class so
+    // a typo or malicious value can't smuggle TOML control characters
+    // (NUL, NL, CR, escape sequences) through the `-c model="<value>"`
+    // injection point. Accepts published codex model names; rejects
+    // re-quote / TOML-escape edge cases.
+    codex_model: z.string().regex(/^[a-zA-Z0-9._-]{1,64}$/).optional(),
     /**
      * Codex reasoning effort knob (0.13.4+). Pinned via
      * `-c model_reasoning_effort="<level>"` on every invocation. Only
@@ -72,6 +77,15 @@ const ReviewPolicySchema = z
      * matters less than throughput.
      */
     codex_reasoning_effort: z.enum(['low', 'medium', 'high']).optional(),
+    /**
+     * Verdict cache TTL in milliseconds (0.18.1+ helixir #1, #4, #7, #8).
+     * Default 86_400_000 (24 hours). When a push of `head_sha` produces
+     * a non-blocking verdict, the result is written to
+     * `.rea/last-review.cache.json`. Subsequent pushes of the same SHA
+     * within the TTL skip the codex invocation and reuse the cached
+     * verdict. Set to 0 to disable caching (every push re-invokes codex).
+     */
+    cache_ttl_ms: z.number().int().nonnegative().optional(),
 })
     .strict();
 /**

package/dist/policy/profiles.d.ts

@@ -47,6 +47,28 @@ export declare const ProfileSchema: z.ZodObject<{
         delegate_to_subagent?: string[] | undefined;
         max_bash_output_lines?: number | undefined;
     }>>;
+    audit: z.ZodOptional<z.ZodObject<{
+        rotation: z.ZodOptional<z.ZodObject<{
+            max_bytes: z.ZodOptional<z.ZodNumber>;
+            max_age_days: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            max_bytes?: number | undefined;
+            max_age_days?: number | undefined;
+        }, {
+            max_bytes?: number | undefined;
+            max_age_days?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        rotation?: {
+            max_bytes?: number | undefined;
+            max_age_days?: number | undefined;
+        } | undefined;
+    }, {
+        rotation?: {
+            max_bytes?: number | undefined;
+            max_age_days?: number | undefined;
+        } | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -64,6 +86,12 @@ export declare const ProfileSchema: z.ZodObject<{
         delegate_to_subagent?: string[] | undefined;
         max_bash_output_lines?: number | undefined;
     } | undefined;
+    audit?: {
+        rotation?: {
+            max_bytes?: number | undefined;
+            max_age_days?: number | undefined;
+        } | undefined;
+    } | undefined;
 }, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -81,6 +109,12 @@ export declare const ProfileSchema: z.ZodObject<{
         delegate_to_subagent?: string[] | undefined;
         max_bash_output_lines?: number | undefined;
     } | undefined;
+    audit?: {
+        rotation?: {
+            max_bytes?: number | undefined;
+            max_age_days?: number | undefined;
+        } | undefined;
+    } | undefined;
 }>;
 export type Profile = z.infer<typeof ProfileSchema>;
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/profiles.js

@@ -54,6 +54,21 @@ export const ProfileSchema = z
     injection_detection: z.enum(['block', 'warn']).optional(),
     injection: InjectionProfileSchema.optional(),
     context_protection: ContextProtectionProfileSchema.optional(),
+    // 0.18.1+ helixir #9: profiles can ship audit-rotation defaults.
+    // The full audit policy block validates at load time via
+    // `AuditPolicySchema` in loader.ts; profiles only need to declare
+    // the rotation knob (most consumer profiles will leave this empty
+    // — the default 50 MiB / 30 days are sane).
+    audit: z
+        .object({
+        rotation: z
+            .object({
+            max_bytes: z.number().int().positive().optional(),
+            max_age_days: z.number().int().positive().optional(),
+        })
+            .optional(),
+    })
+        .optional(),
 })
     .strict();
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/types.d.ts

@@ -158,6 +158,17 @@ export interface ReviewPolicy {
      * throughput.
      */
     codex_reasoning_effort?: 'low' | 'medium' | 'high';
+    /**
+     * Verdict cache TTL in milliseconds (0.18.1+ helixir #1, #4, #7, #8).
+     * Default 86_400_000 (24 hours). When a push of `head_sha` produces a
+     * non-blocking verdict, the result is written to
+     * `.rea/last-review.cache.json`. Subsequent pushes of the same SHA
+     * within the TTL skip the codex invocation and reuse the cached
+     * verdict. Set to `0` to disable caching (every push re-invokes
+     * codex — pre-0.18.1 behavior). Verdict flips on the same SHA emit
+     * a `rea.push_gate.verdict_flip` audit event and overwrite the cache.
+     */
+    cache_ttl_ms?: number;
 }
 /**
  * User-supplied redaction pattern entry. Each pattern has a stable `name` used

package/hooks/_lib/cmd-segments.sh

@@ -181,7 +181,14 @@ _rea_unwrap_nested_shells() {
       # alternation `(^|[[:space:]&|;])` therefore cannot anchor on a
       # masked separator, and the shell-name token itself can no longer
       # appear adjacent to a masked quote-introducer.
-      WRAP = "(^|[[:space:]&|;])(bash|sh|zsh|dash|ksh)([[:space:]]+-[a-zA-Z]+)*[[:space:]]+-(c|lc|lic|ic|cl|cli|li|il)[[:space:]]+"
+      # 0.19.0 security review M1: extend the shell-name set to cover
+      # every commonly-installed POSIX-style shell. mksh / oksh / yash /
+      # posh ship on minimal containers, csh/tcsh on legacy macOS,
+      # fish on dev workstations. Each accepts -c with a quoted body.
+      # NOTE: pwsh (PowerShell) uses -Command / -EncodedCommand and is
+      # NOT covered here. Adding pwsh requires a separate code path
+      # because EncodedCommand base64-decodes at runtime.
+      WRAP = "(^|[[:space:]&|;])(bash|sh|zsh|dash|ksh|mksh|oksh|posh|yash|csh|tcsh|fish)([[:space:]]+-[a-zA-Z]+)*[[:space:]]+-(c|lc|lic|ic|cl|cli|li|il)[[:space:]]+"
       # Track the cursor in BOTH raw and masked. Because the mask is
       # byte-for-byte width-preserving, the same RSTART/RLENGTH applies
       # to both — but each iteration of the loop must SLICE both strings

package/hooks/_lib/protected-paths.sh

@@ -45,6 +45,10 @@ REA_PROTECTED_PATTERNS_FULL=(
   '.husky/'
   '.rea/policy.yaml'
   '.rea/HALT'
+  # 0.19.0 security review C1: the verdict cache is a security boundary
+  # since 0.18.1. A forged entry would skip codex on next push of that
+  # SHA. Protect it like the kill-switch.
+  '.rea/last-review.cache.json'
 )
 
 # Kill-switch invariants — never relaxable. Subset of FULL.
@@ -52,6 +56,7 @@ REA_KILL_SWITCH_INVARIANTS=(
   '.claude/settings.json'
   '.rea/policy.yaml'
   '.rea/HALT'
+  '.rea/last-review.cache.json'
 )
 
 # Effective patterns after applying the relax list. Computed lazily on

package/hooks/attribution-advisory.sh

@@ -102,7 +102,7 @@ FOUND=0
 # below catches Co-Authored-By with named tools regardless of the email
 # domain, so dropping `users.noreply.github.com` from the noreply
 # pattern only relaxes the check for human collaborators — never for AI.
-if any_segment_matches "$CMD" '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)'; then
+if any_segment_matches "$CMD" '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|mistral\.ai|xai-org|x\.ai|inflection\.ai|perplexity\.ai|replit\.com|jetbrains\.com|bito\.ai|pieces\.app|phind\.com|you\.com)'; then
   FOUND=1
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",
@@ -84,6 +84,7 @@
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "ajv": "^8.17.1",
     "eslint": "^10.2.0",
     "prettier": "^3.8.1",
     "typescript": "^5.8.0",

package/profiles/bst-internal.yaml

@@ -28,3 +28,11 @@ context_protection:
     - pnpm run test
     - pnpm run lint
   max_bash_output_lines: 100
+# 0.18.1+ helixir #9: enable audit log rotation by default for
+# bst-internal. Long sessions accumulate 100s of push_gate.reviewed
+# entries; without rotation the audit file grows unbounded. The empty
+# `rotation: {}` block opts in to the documented defaults — 50 MiB
+# OR 30 days, whichever arrives first. Rotation marker preserves the
+# hash chain across the boundary.
+audit:
+  rotation: {}

package/scripts/postinstall.mjs

@@ -116,13 +116,58 @@ try {
 
   if (manifestVersion === installedVersion) process.exit(0);
 
-  // Package-manager-agnostic message. Any of `npx rea upgrade`,
+  // 0.18.1+ helixir #3: opt-in auto-upgrade. Pre-fix the drift was
+  // detected and a "run rea upgrade" nudge printed, but consumers had
+  // to run the upgrade by hand on every install. With
+  // `REA_AUTO_UPGRADE=1` (or `--yes` semantics inferred from a
+  // package.json field), the postinstall runs `rea upgrade --yes`
+  // for them. Defaults to PRINT-ONLY for back-compat — silent
+  // mutation of the consumer's `.claude/` / `.husky/` on every
+  // install would surprise existing users.
+  const autoUpgrade =
+    process.env.REA_AUTO_UPGRADE === '1' ||
+    process.env.REA_AUTO_UPGRADE === 'true';
+
+  if (autoUpgrade) {
+    // Best-effort: invoke `rea upgrade --yes`. Failures fall through to
+    // the print path so the consumer still sees the drift advisory.
+    try {
+      const reaCli = path.join(consumerRoot, 'node_modules', '.bin', 'rea');
+      if (fs.existsSync(reaCli)) {
+        const { spawnSync } = await import('node:child_process');
+        // 0.19.0 backend-engineer P2-1: 5-min wall-clock cap so a hung
+        // upgrade falls through to print-only instead of hanging the
+        // consumer's `npm install`. 0.19.0 code-reviewer P3-6:
+        // Windows shim (.bin/rea.cmd) requires `shell: true` —
+        // detect via process.platform.
+        const res = spawnSync(reaCli, ['upgrade', '--yes'], {
+          cwd: consumerRoot,
+          stdio: 'inherit',
+          env: process.env,
+          timeout: 5 * 60 * 1000,
+          shell: process.platform === 'win32',
+        });
+        if (res.status === 0) {
+          NOTE([
+            `@bookedsolid/rea: auto-upgraded from v${manifestVersion} to v${installedVersion}.`,
+            `(REA_AUTO_UPGRADE=1; set REA_AUTO_UPGRADE=0 to opt out.)`,
+          ]);
+          process.exit(0);
+        }
+      }
+    } catch {
+      // Fall through to the manual-nudge path below.
+    }
+  }
+
+  // Package-manager-agnostic nudge. Any of `npx rea upgrade`,
   // `pnpm exec rea upgrade`, or `yarn rea upgrade` works; recommending `npx`
   // covers the widest audience without privileging pnpm in error output.
   NOTE([
     `@bookedsolid/rea v${installedVersion} installed; manifest at v${manifestVersion}.`,
     `Run  \`npx rea upgrade\`  to sync .claude/, .husky/, and managed fragments.`,
     `(Or  \`npx rea doctor --drift\`  to preview without changes.)`,
+    `(Set  \`REA_AUTO_UPGRADE=1\`  to auto-run upgrade on future installs.)`,
   ]);
 } catch {
   // Any uncaught failure → silent success. Never break the consumer's install.