@bookedsolid/rea 0.19.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/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,11 +23,12 @@
  */
 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';
@@ -87,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 {
@@ -111,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 {
@@ -156,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,
         });
@@ -251,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
@@ -321,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,
@@ -348,7 +363,7 @@ export async function runPushGate(deps) {
         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, {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_CACHE_HIT, fullPolicy, {
             verdict: cached.verdict,
             finding_count: cached.finding_count,
             base_ref: base.ref,
@@ -423,7 +438,7 @@ export async function runPushGate(deps) {
         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, {
+                await safeAppend(appendAuditFn, deps.baseDir, EVT_VERDICT_FLIP, fullPolicy, {
                     head_sha: headSha,
                     prior_verdict: cacheLookup.entry.verdict,
                     fresh_verdict: summary.verdict,
@@ -435,20 +450,22 @@ export async function runPushGate(deps) {
                 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',
+                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 {
-                writeVerdict(deps.baseDir, headSha, entry);
+                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.
+                // 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, {
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_REVIEWED, fullPolicy, {
             verdict: summary.verdict,
             finding_count: summary.findings.length,
             base_ref: base.ref,
@@ -492,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) {
@@ -502,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 = {
@@ -514,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,
@@ -542,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
@@ -552,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/verdict-cache.d.ts

@@ -37,6 +37,21 @@
  *     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.
  */
@@ -66,33 +81,46 @@ export interface VerdictCacheLookupResult {
  * 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;
+/**
+ * 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): boolean;
+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): number;
+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): number;
+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

@@ -37,11 +37,28 @@
  *     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
@@ -66,25 +83,6 @@ export function lookupVerdict(baseDir, headSha, now = new Date()) {
     }
     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
@@ -95,68 +93,99 @@ export function isFlip(prior, fresh) {
         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 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];
+export async function clearVerdict(baseDir, headSha) {
     const cachePath = path.join(baseDir, '.rea', VERDICT_CACHE_FILE);
-    fs.writeFileSync(cachePath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
-    return true;
+    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 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 });
+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 });
     }
-    fs.writeFileSync(cachePath, `${JSON.stringify(empty, null, 2)}\n`, 'utf8');
-    return count;
+    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 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,
-    };
+export async function pruneOlderThan(baseDir, olderThanMs, now = new Date()) {
     const cachePath = path.join(baseDir, '.rea', VERDICT_CACHE_FILE);
-    fs.writeFileSync(cachePath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
-    return removed;
+    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`).
@@ -167,18 +196,43 @@ 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 ||
-            parsed.schema_version !== VERDICT_CACHE_SCHEMA_VERSION) {
+        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;
@@ -188,3 +242,35 @@ function readCacheFile(baseDir) {
         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.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

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.19.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/scripts/postinstall.mjs

@@ -135,10 +135,17 @@ 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([