@bookedsolid/rea 0.18.0 → 0.19.0

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/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;
+    }
+}

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

@@ -72,6 +72,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.18.0",
+  "version": "0.19.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)",

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,51 @@ 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');
+        const res = spawnSync(reaCli, ['upgrade', '--yes'], {
+          cwd: consumerRoot,
+          stdio: 'inherit',
+          env: process.env,
+        });
+        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.