@bookedsolid/rea 0.10.2 → 0.11.0

package/dist/cli/install/settings-merge.d.ts

@@ -41,6 +41,23 @@ export interface MergeResult {
  * hooks and returns the merged settings plus a list of warnings. Does NOT
  * touch disk.
  */
+/**
+ * Remove hook entries whose `command` contains any of the listed
+ * substrings. Returns a deep-cloned settings object plus the count of
+ * entries removed. Empty hook arrays and empty groups are pruned too so
+ * the resulting file doesn't accumulate empty sentinel objects after
+ * repeated upgrade runs.
+ *
+ * Used by `rea upgrade` to purge references to hooks we delete in a
+ * release (0.11.0 removed `push-review-gate.sh` and `commit-review-gate.sh`).
+ * Without this, `mergeSettings()` is additive-only and consumer
+ * `.claude/settings.json` would keep executing stale commands that
+ * point at files we just deleted from `.claude/hooks/`.
+ */
+export declare function pruneHookCommands(existing: Record<string, unknown>, staleSubstrings: readonly string[]): {
+    merged: Record<string, unknown>;
+    removedCount: number;
+};
 export declare function mergeSettings(existing: Record<string, unknown>, desired: DesiredHookGroup[]): MergeResult;
 /**
  * Atomic write via tmp-file + rename.

package/dist/cli/install/settings-merge.js

@@ -39,6 +39,54 @@ function keyFor(matcher, command) {
  * hooks and returns the merged settings plus a list of warnings. Does NOT
  * touch disk.
  */
+/**
+ * Remove hook entries whose `command` contains any of the listed
+ * substrings. Returns a deep-cloned settings object plus the count of
+ * entries removed. Empty hook arrays and empty groups are pruned too so
+ * the resulting file doesn't accumulate empty sentinel objects after
+ * repeated upgrade runs.
+ *
+ * Used by `rea upgrade` to purge references to hooks we delete in a
+ * release (0.11.0 removed `push-review-gate.sh` and `commit-review-gate.sh`).
+ * Without this, `mergeSettings()` is additive-only and consumer
+ * `.claude/settings.json` would keep executing stale commands that
+ * point at files we just deleted from `.claude/hooks/`.
+ */
+export function pruneHookCommands(existing, staleSubstrings) {
+    const merged = deepClone(existing);
+    const hooks = ensureHooksShape(merged);
+    let removedCount = 0;
+    for (const event of Object.keys(hooks)) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            const entries = group.hooks ?? [];
+            if (!Array.isArray(entries))
+                continue;
+            const kept = [];
+            for (const entry of entries) {
+                const cmd = typeof entry.command === 'string' ? entry.command : '';
+                if (staleSubstrings.some((s) => cmd.includes(s))) {
+                    removedCount += 1;
+                    continue;
+                }
+                kept.push(entry);
+            }
+            group.hooks = kept;
+        }
+        // Drop groups whose hooks list is now empty.
+        hooks[event] = groups.filter((g) => Array.isArray(g.hooks) && g.hooks.length > 0);
+    }
+    // Drop events whose group list is now empty.
+    for (const event of Object.keys(hooks)) {
+        const groups = hooks[event];
+        if (Array.isArray(groups) && groups.length === 0) {
+            delete hooks[event];
+        }
+    }
+    return { merged, removedCount };
+}
 export function mergeSettings(existing, desired) {
     const merged = deepClone(existing);
     const hooks = ensureHooksShape(merged);
@@ -215,7 +263,6 @@ export function defaultDesiredHooks() {
                 { type: 'command', command: `${base}/security-disclosure-gate.sh`, timeout: 5000, statusMessage: 'Checking disclosure policy...' },
                 { type: 'command', command: `${base}/pr-issue-link-gate.sh`, timeout: 5000, statusMessage: 'Checking PR for issue reference...' },
                 { type: 'command', command: `${base}/attribution-advisory.sh`, timeout: 5000, statusMessage: 'Checking for AI attribution...' },
-                { type: 'command', command: `${base}/push-review-gate.sh`, timeout: 30000, statusMessage: 'Running push review gate...' },
             ],
         },
         {

package/dist/cli/upgrade.js

@@ -44,11 +44,103 @@ import { loadPolicy } from '../policy/loader.js';
 import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFiles, } from './install/canonical.js';
 import { buildFragment, extractFragment, } from './install/claude-md.js';
 import { atomicReplaceFile, safeDeleteFile, safeInstallFile, safeReadFile, } from './install/fs-safe.js';
-import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
+import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, pruneHookCommands, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
 import { ensureReaGitignore } from './install/gitignore.js';
 import { manifestExists, readManifest, writeManifestAtomic, } from './install/manifest-io.js';
 import { sha256OfBuffer, sha256OfFile } from './install/sha.js';
 import { err, getPkgVersion, log, warn } from './utils.js';
+// ---------------------------------------------------------------------------
+// 0.11.0 policy migration
+// ---------------------------------------------------------------------------
+/**
+ * Strip 0.10.x review.* fields that 0.11.0 rejects at schema load, and
+ * backfill `concerns_blocks: true` if the `review:` block exists without
+ * it. Writes a timestamped backup to `.rea/policy.yaml.bak-<ts>` before
+ * mutating.
+ *
+ * Surgical text rewrite, not YAML round-trip. YAML round-tripping loses
+ * comments and reformats quoting; operators care about their comments.
+ * Line-by-line deletion of the two removed keys keeps every other line
+ * byte-identical. This is safe because the keys we strip are simple
+ * scalars (`cache_max_age_seconds: 3600`, `allow_skip_in_ci: false`) that
+ * cannot span multiple lines in any reasonable policy file.
+ */
+async function migrateReviewPolicyFor0110(resolvedRoot, opts) {
+    const policyPath = path.join(resolvedRoot, '.rea', 'policy.yaml');
+    let raw;
+    try {
+        raw = await fsPromises.readFile(policyPath, 'utf8');
+    }
+    catch {
+        return; // no policy to migrate
+    }
+    const lines = raw.split(/\r?\n/);
+    const REVIEW_RE = /^review:\s*(?:#.*)?$/;
+    const REMOVED_KEY_RE = /^(\s+)(cache_max_age_seconds|allow_skip_in_ci):\s*\S.*$/;
+    const INDENT_RE = /^(\s+)\S/;
+    let reviewStart = -1;
+    let reviewIndent = '';
+    const linesToDrop = new Set();
+    let hasConcernsBlocks = false;
+    let reviewChildIndent = '';
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        if (reviewStart < 0 && REVIEW_RE.test(line.trimEnd())) {
+            reviewStart = i;
+            const indentMatch = INDENT_RE.exec(line);
+            reviewIndent = indentMatch?.[1] ?? '';
+            continue;
+        }
+        if (reviewStart < 0)
+            continue;
+        // Inside the review: block as long as indent is deeper than reviewIndent.
+        if (line.trim() === '')
+            continue;
+        const indentMatch = INDENT_RE.exec(line);
+        const lineIndent = indentMatch?.[1] ?? '';
+        if (lineIndent.length <= reviewIndent.length) {
+            // Left the block.
+            break;
+        }
+        if (reviewChildIndent.length === 0)
+            reviewChildIndent = lineIndent;
+        if (/^\s+concerns_blocks:/.test(line))
+            hasConcernsBlocks = true;
+        if (REMOVED_KEY_RE.test(line)) {
+            linesToDrop.add(i);
+        }
+    }
+    const addConcernsBlocks = reviewStart >= 0 && !hasConcernsBlocks;
+    if (linesToDrop.size === 0 && !addConcernsBlocks)
+        return;
+    const newLines = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        if (linesToDrop.has(i))
+            continue;
+        newLines.push(lines[i] ?? '');
+        // Append `concerns_blocks: true` right after the `review:` header line
+        // when the block exists but lacks the key.
+        if (i === reviewStart && addConcernsBlocks) {
+            const indent = reviewChildIndent.length > 0 ? reviewChildIndent : reviewIndent + '  ';
+            newLines.push(`${indent}concerns_blocks: true`);
+        }
+    }
+    const updated = newLines.join('\n');
+    const droppedSummary = [];
+    if (linesToDrop.size > 0)
+        droppedSummary.push(`dropped ${linesToDrop.size} removed-field line(s)`);
+    if (addConcernsBlocks)
+        droppedSummary.push('added concerns_blocks: true');
+    if (opts.dryRun) {
+        log(`[dry-run] would migrate .rea/policy.yaml: ${droppedSummary.join(', ')}`);
+        return;
+    }
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${policyPath}.bak-${ts}`;
+    await fsPromises.copyFile(policyPath, backupPath);
+    await atomicReplaceFile(policyPath, updated);
+    warn(`migrated .rea/policy.yaml for 0.11.0 (${droppedSummary.join(', ')}); backup at ${path.basename(backupPath)}`);
+}
 /**
  * Hard cap for `showDiff` reads. Canonical files are all tiny (<64KB) but a
  * consumer could have replaced a hook with a 500MB log; refuse to slurp the
@@ -282,19 +374,50 @@ async function upgradeClaudeMdFragment(resolvedRoot, opts) {
     await atomicReplaceFile(claudeMdPath, next);
     return { sha: newSha, action: 'written' };
 }
+/**
+ * Hook commands deleted in 0.11.0. `upgradeSettings` prunes any entries
+ * whose `command` string contains one of these tokens so consumer
+ * `.claude/settings.json` files don't keep invoking missing scripts
+ * (which would fail every matched tool call until the operator edited
+ * settings by hand).
+ *
+ * 0.11.0 removals:
+ *   - push-review-gate.sh        (replaced by husky stub → rea hook push-gate)
+ *   - commit-review-gate.sh      (intentionally unregistered; source-of-truth deleted)
+ *   - push-review-gate-git.sh    (native-git adapter; deleted)
+ *
+ * Add future removals here rather than baking the list into
+ * `pruneHookCommands` itself — the removal list is release history,
+ * not a static setting.
+ */
+const STALE_HOOK_COMMAND_TOKENS = [
+    'push-review-gate.sh',
+    'commit-review-gate.sh',
+    'push-review-gate-git.sh',
+];
 async function upgradeSettings(baseDir, opts) {
     const desired = defaultDesiredHooks();
     const sha = canonicalSettingsSubsetHash(desired);
     const { settings, settingsPath } = readSettings(baseDir);
-    const mergeResult = mergeSettings(settings, desired);
+    // PRUNE FIRST (remove 0.11.0-deleted hook references), THEN MERGE
+    // (add any new hooks). Order matters: merging first would re-add the
+    // stale entry only to have the prune re-delete it on the next line —
+    // pointless work. Pruning first means the merge sees a clean baseline.
+    const pruned = pruneHookCommands(settings, STALE_HOOK_COMMAND_TOKENS);
+    const mergeResult = mergeSettings(pruned.merged, desired);
     if (opts.dryRun !== true) {
         await writeSettingsAtomic(settingsPath, mergeResult.merged);
     }
+    const warnings = [...mergeResult.warnings];
+    if (pruned.removedCount > 0) {
+        warnings.push(`pruned ${pruned.removedCount} stale 0.10.x hook entr${pruned.removedCount === 1 ? 'y' : 'ies'} from .claude/settings.json (removed in 0.11.0)`);
+    }
     return {
         sha,
         addedCount: mergeResult.addedCount,
         skippedCount: mergeResult.skippedCount,
-        warnings: mergeResult.warnings,
+        removedCount: pruned.removedCount,
+        warnings,
     };
 }
 /** Re-hash a file we just wrote. Source and on-disk bytes should match, but
@@ -321,6 +444,11 @@ export async function runUpgrade(options = {}) {
     if (options.force === true && !dryRun) {
         warn('--force: overwriting locally-modified files and deleting removed-upstream entries without prompt.');
     }
+    // 0.11.0 migration — strip removed review.* fields and backfill the new
+    // concerns_blocks default. Runs before canonical file reconciliation so a
+    // policy that fails strict schema load (which happens on upgrade from
+    // 0.10.x the moment we re-read `.rea/policy.yaml`) is cleaned up first.
+    await migrateReviewPolicyFor0110(resolvedRoot, { dryRun });
     const canonicalFiles = await enumerateCanonicalFiles();
     if (canonicalFiles.length === 0) {
         err('no canonical files found in package — is the build complete?');

package/dist/config/tier-map.js

@@ -110,28 +110,20 @@ export function isToolBlocked(toolName, serverName, gatewayConfig) {
  * Classify a `rea <subcommand>` Bash invocation by its own semantics rather
  * than the generic Bash default.
  *
- * Defect E (rea#78): REA's own governance CLI must not be denied by REA's own
- * middleware. The gate's error messages literally say "Run `rea cache set
- * <sha> pass --branch <x> --base <y>`" — then the agent is denied at autonomy
- * L1 because `Bash` is classified Write and the downstream middleware can't
- * see that the Write is just appending a line to `.rea/review-cache.jsonl`.
+ * REA's own governance CLI must not be denied by REA's own middleware. This
+ * helper returns the tier appropriate to the rea subcommand when the command
+ * parses as `rea <sub>` or `npx rea <sub>`. Returns `null` if the command is
+ * not a rea invocation — callers then fall back to the generic Bash tier.
  *
- * This helper returns the tier appropriate to the rea subcommand when the
- * command parses as `rea <sub>` or `npx rea <sub>`. Returns `null` if the
- * command is not a rea invocation — callers then fall back to the generic
- * Bash tier.
- *
- * Tier mapping:
- *   - Read:        `cache check|list|get`, `audit verify`,
- *                  `audit record codex-review`, `check`, `doctor`, `status`
- *   - Write:       `cache set|clear`, `audit rotate`, `init`,
- *                  `serve`, `upgrade`, `unfreeze`
+ * Tier mapping (0.11.0):
+ *   - Read:        `audit verify`, `check`, `doctor`, `status`,
+ *                  `hook push-gate` (exec-only — no state mutation)
+ *   - Write:       `audit rotate`, `init`, `serve`, `upgrade`, `unfreeze`
  *   - Destructive: `freeze` (writes `.rea/HALT`, suspends the session)
  *
- * `audit record codex-review` is Read-tier because it is REA's own append-only
- * audit surface — the whole point of the command is to let an L1 agent satisfy
- * the push-review gate without a human in the loop. Write-tier here would
- * reintroduce exactly the deadlock Defect D/E close.
+ * `rea cache` and `rea audit record codex-review` were removed in 0.11.0 —
+ * the stateless push-gate needs neither. Any lingering reference to those
+ * subcommands falls through to `Tier.Write` (safe default).
  *
  * SECURITY: returns `null` for any command containing shell metacharacters
  * that would let an attacker piggyback arbitrary commands onto an allowed
@@ -275,18 +267,19 @@ export function reaCommandTier(command) {
             case 'doctor':
             case 'status':
                 return Tier.Read;
-            case 'cache': {
-                if (sub2 === 'check' || sub2 === 'list' || sub2 === 'get')
+            case 'hook': {
+                // `rea hook push-gate` is execution-only — it runs codex exec review
+                // and writes `.rea/last-review.json` + an audit record, but the
+                // user-visible effect is an exit code. Classify Read so the pre-push
+                // hook is not blocked at L1 (symmetric to the 0.10.x reasoning for
+                // `audit record codex-review`).
+                if (sub2 === 'push-gate')
                     return Tier.Read;
-                if (sub2 === 'set' || sub2 === 'clear')
-                    return Tier.Write;
                 return Tier.Write;
             }
             case 'audit': {
                 if (sub2 === 'verify')
                     return Tier.Read;
-                if (sub2 === 'record')
-                    return Tier.Read;
                 if (sub2 === 'rotate')
                     return Tier.Write;
                 return Tier.Write;

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

@@ -0,0 +1,57 @@
+/**
+ * Base-branch resolution for the push-gate.
+ *
+ * Codex `exec review --base <ref>` needs a git ref to diff against. The
+ * caller may provide one via `rea hook push-gate --base <ref>`; if they
+ * don't, we resolve it in priority order:
+ *
+ *   1. Current branch's upstream (`@{upstream}`) — the branch the operator
+ *      configured as their tracking ref. Most accurate since it matches
+ *      what `git push` is about to compare against.
+ *   2. `origin/HEAD` symbolic ref (e.g. `refs/remotes/origin/main`). Set
+ *      automatically by `git clone` and `git remote set-head`.
+ *   3. Explicit probes: `origin/main` → `origin/master` via rev-parse.
+ *   4. Local `main` / `master` — last resort when the clone has no remote
+ *      tracking refs yet (freshly initialized sibling project, mirror
+ *      clone).
+ *
+ * On total failure we surface the sentinel `empty-tree` SHA
+ * (`4b825dc642cb6eb9a060e54bf8d69288fbee4904`) so the diff covers every
+ * file in HEAD. First pushes to a fresh remote still get reviewed — the
+ * 0.10.x fail-open at this resolution step was defect J.
+ *
+ * All git commands are invoked via the injected `GitExecutor` — tests
+ * replace it with a fake to avoid shelling out.
+ */
+import type { GitExecutor } from './codex-runner.js';
+export interface BaseResolution {
+    /**
+     * Resolved ref (branch, remote-tracking ref, or 40-char SHA). Always
+     * usable as the `--base` argument to `codex exec review`.
+     */
+    ref: string;
+    /** Where the ref came from — surfaces in audit records and stderr. */
+    source: 'explicit' | 'upstream' | 'origin-head' | 'origin-main' | 'origin-master' | 'local-main' | 'local-master' | 'empty-tree';
+}
+/**
+ * Well-known empty-tree SHA: `git hash-object -t tree /dev/null`. Every git
+ * installation carries this object implicitly. Using it as a fallback lets
+ * a review on a clone with no tracking refs still exercise the entire HEAD
+ * tree diff.
+ */
+export declare const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+export interface ResolveBaseOptions {
+    /**
+     * Explicit ref from `--base <ref>` or equivalent. When set, the resolver
+     * returns it unchanged with `source: 'explicit'` — the caller is
+     * responsible for its correctness. We do NOT validate that it exists;
+     * that's Codex's job (it'll error clearly if the ref is bad).
+     */
+    explicit?: string;
+}
+/**
+ * Resolve the base ref using the configured priority order. Never throws —
+ * every failure mode degrades to the next step, and the worst case (no
+ * tracking refs, no local main/master) is `empty-tree`.
+ */
+export declare function resolveBaseRef(git: GitExecutor, options?: ResolveBaseOptions): BaseResolution;

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

@@ -0,0 +1,77 @@
+/**
+ * Base-branch resolution for the push-gate.
+ *
+ * Codex `exec review --base <ref>` needs a git ref to diff against. The
+ * caller may provide one via `rea hook push-gate --base <ref>`; if they
+ * don't, we resolve it in priority order:
+ *
+ *   1. Current branch's upstream (`@{upstream}`) — the branch the operator
+ *      configured as their tracking ref. Most accurate since it matches
+ *      what `git push` is about to compare against.
+ *   2. `origin/HEAD` symbolic ref (e.g. `refs/remotes/origin/main`). Set
+ *      automatically by `git clone` and `git remote set-head`.
+ *   3. Explicit probes: `origin/main` → `origin/master` via rev-parse.
+ *   4. Local `main` / `master` — last resort when the clone has no remote
+ *      tracking refs yet (freshly initialized sibling project, mirror
+ *      clone).
+ *
+ * On total failure we surface the sentinel `empty-tree` SHA
+ * (`4b825dc642cb6eb9a060e54bf8d69288fbee4904`) so the diff covers every
+ * file in HEAD. First pushes to a fresh remote still get reviewed — the
+ * 0.10.x fail-open at this resolution step was defect J.
+ *
+ * All git commands are invoked via the injected `GitExecutor` — tests
+ * replace it with a fake to avoid shelling out.
+ */
+/**
+ * Well-known empty-tree SHA: `git hash-object -t tree /dev/null`. Every git
+ * installation carries this object implicitly. Using it as a fallback lets
+ * a review on a clone with no tracking refs still exercise the entire HEAD
+ * tree diff.
+ */
+export const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * Resolve the base ref using the configured priority order. Never throws —
+ * every failure mode degrades to the next step, and the worst case (no
+ * tracking refs, no local main/master) is `empty-tree`.
+ */
+export function resolveBaseRef(git, options = {}) {
+    if (options.explicit !== undefined && options.explicit.length > 0) {
+        return { ref: options.explicit, source: 'explicit' };
+    }
+    // 1. Upstream of current branch. `@{upstream}` resolves to the configured
+    //    tracking ref (typically `refs/remotes/origin/<branch>`). Returns
+    //    empty on branches without an upstream — which is normal for a brand
+    //    new feature branch; fall through.
+    const upstream = git
+        .tryRevParse(['--abbrev-ref', '--symbolic-full-name', '@{upstream}'])
+        .trim();
+    if (upstream.length > 0) {
+        return { ref: upstream, source: 'upstream' };
+    }
+    // 2. origin/HEAD symbolic ref. Set by `git clone` to point at the remote's
+    //    default branch. `git symbolic-ref` returns the full ref path; we
+    //    hand that to Codex directly (it's `refs/remotes/origin/<name>`).
+    const originHead = git.trySymbolicRef('refs/remotes/origin/HEAD').trim();
+    if (originHead.length > 0) {
+        return { ref: originHead, source: 'origin-head' };
+    }
+    // 3. Explicit probes for the two most common default-branch names.
+    if (git.tryRevParse(['--verify', '--quiet', 'refs/remotes/origin/main']).length > 0) {
+        return { ref: 'refs/remotes/origin/main', source: 'origin-main' };
+    }
+    if (git.tryRevParse(['--verify', '--quiet', 'refs/remotes/origin/master']).length > 0) {
+        return { ref: 'refs/remotes/origin/master', source: 'origin-master' };
+    }
+    // 4. Local branches. `main` and `master` without `refs/remotes/` prefix
+    //    resolve via `refs/heads/`. Order matches priority 3.
+    if (git.tryRevParse(['--verify', '--quiet', 'refs/heads/main']).length > 0) {
+        return { ref: 'refs/heads/main', source: 'local-main' };
+    }
+    if (git.tryRevParse(['--verify', '--quiet', 'refs/heads/master']).length > 0) {
+        return { ref: 'refs/heads/master', source: 'local-master' };
+    }
+    // 5. Last resort: diff against the empty-tree SHA. Covers every file in
+    //    HEAD; expensive for large repos but correct.
+    return { ref: EMPTY_TREE_SHA, source: 'empty-tree' };
+}

package/dist/hooks/push-gate/codex-runner.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Codex CLI runner for the push-gate.
+ *
+ * Shells to `codex exec review --base <ref> --json --ephemeral` and consumes
+ * the JSONL event stream. Every event is parsed; the sequence of
+ * `agent_message` items becomes the review text that `findings.ts` then
+ * parses for P1/P2/P3 markers.
+ *
+ * Errors are typed so `index.ts` can distinguish:
+ *
+ *   - `CodexNotInstalledError`  → clear install-Codex prompt
+ *   - `CodexTimeoutError`       → `review.timeout_ms` exceeded; kill signal
+ *   - `CodexProtocolError`      → stdout was not JSONL or lacked agent output
+ *   - `CodexSubprocessError`    → non-zero exit with captured stderr
+ *
+ * The `GitExecutor` interface is a narrow shim around `git` invocations the
+ * gate needs (base resolution, diff-names, HEAD resolution). Extracted so
+ * `./base.ts` and `./index.ts` can be unit-tested with deterministic fakes
+ * and so the one git dependency surface is in one place.
+ */
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+export declare class CodexNotInstalledError extends Error {
+    readonly kind: "not-installed";
+    constructor();
+}
+export declare class CodexTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly kind: "timeout";
+    constructor(timeoutMs: number);
+}
+export declare class CodexProtocolError extends Error {
+    readonly detail: string;
+    readonly sampleLine?: string | undefined;
+    readonly kind: "protocol";
+    constructor(detail: string, sampleLine?: string | undefined);
+}
+export declare class CodexSubprocessError extends Error {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stderrTail: string;
+    readonly kind: "subprocess";
+    constructor(exitCode: number | null, signal: NodeJS.Signals | null, stderrTail: string);
+}
+export type CodexRunError = CodexNotInstalledError | CodexTimeoutError | CodexProtocolError | CodexSubprocessError;
+export interface GitExecutor {
+    /** `git rev-parse <args>`. Returns stdout trimmed or '' on non-zero exit. */
+    tryRevParse(args: string[]): string;
+    /** `git symbolic-ref <ref>`. Returns stdout trimmed or '' on non-zero. */
+    trySymbolicRef(ref: string): string;
+    /** `git rev-parse HEAD`. Returns the 40-char SHA or '' on non-zero. */
+    headSha(): string;
+    /** `git diff --name-only <base> <head>`. Returns path list (possibly empty). */
+    diffNames(base: string, head: string): string[];
+}
+/**
+ * Real git implementation using `spawnSync`. Each call is independent (no
+ * persistent git process) — the gate runs infrequently enough that the
+ * fork overhead is inaudible.
+ */
+export declare function createRealGitExecutor(cwd: string): GitExecutor;
+export interface CodexRunOptions {
+    baseRef: string;
+    cwd: string;
+    timeoutMs: number;
+    /** Optional custom review prompt; defaults to Codex's built-in. */
+    prompt?: string;
+    /**
+     * Env passthrough. Tests inject a clean env to prevent ambient overrides.
+     * Production passes `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Injection seam for tests. When set, replaces `spawn` entirely. Must
+     * return an object whose `stdout`/`stderr` are async iterables of Buffer
+     * chunks and whose `on('exit')` yields `(code, signal)` like a real
+     * ChildProcess. Keeping this narrow means we don't have to fake the
+     * whole ChildProcess API.
+     */
+    spawnImpl?: (command: string, args: readonly string[], options: {
+        cwd: string;
+        env: NodeJS.ProcessEnv;
+    }) => ChildProcessWithoutNullStreams;
+}
+export interface CodexRunResult {
+    /** The concatenated text of every `item.completed` agent_message item. */
+    reviewText: string;
+    /** Number of JSONL events observed — useful for debugging protocol issues. */
+    eventCount: number;
+    /** Seconds of wall time spent in the subprocess. */
+    durationSeconds: number;
+}
+/**
+ * Execute `codex exec review` and return the concatenated review text on
+ * success. Callers then pass the text to `summarizeReview()` to get a
+ * structured verdict.
+ *
+ * Every error case throws a typed `CodexRunError`. Callers are expected to
+ * catch and translate to an exit code + audit event.
+ */
+export declare function runCodexReview(options: CodexRunOptions): Promise<CodexRunResult>;
+export interface CodexJsonlParseResult {
+    reviewText: string;
+    eventCount: number;
+}
+/**
+ * Parse the JSONL event stream emitted by `codex exec review --json`. We
+ * tolerate partial lines (stream chunks may split mid-object; our caller
+ * gives us the full stdout after exit, but robustness costs nothing).
+ *
+ * The only events we care about are `item.completed` where `item.type ===
+ * "agent_message"` — those carry the review text. Everything else (turn
+ * lifecycle, command_execution telemetry, thread metadata) is counted but
+ * discarded.
+ *
+ * A JSONL line that doesn't parse as JSON is tolerated: we skip it and
+ * continue. Codex occasionally emits warnings outside the JSON envelope
+ * (e.g. macOS xcrun cache errors leak into stderr but can accidentally
+ * land on stdout in misbehaving shells); we treat these as non-fatal.
+ *
+ * We throw `CodexProtocolError` only when the ENTIRE stdout contains zero
+ * parseable events AND zero `agent_message`-carrying items. An empty diff
+ * can legitimately yield zero agent messages with events (thread.started,
+ * turn.started, turn.completed), so we allow zero findings when at least
+ * one event parsed.
+ */
+export declare function parseCodexJsonl(stdout: string): CodexJsonlParseResult;