@bookedsolid/rea 0.1.0 → 0.2.0

package/dist/gateway/redact-safe/match-timeout.js

@@ -0,0 +1,179 @@
+import { MessageChannel, Worker, receiveMessageOnPort } from 'node:worker_threads';
+const DEFAULT_TIMEOUT_MS = 100;
+/**
+ * Worker source — one script handles both `test` and `replace` ops. The worker
+ * receives the request + a SharedArrayBuffer for synchronization via
+ * `workerData`, compiles the regex inside the worker (so a catastrophic
+ * pattern burns worker CPU only), writes the result payload into a parentPort
+ * message, and then signals completion by writing `1` into the SAB and calling
+ * `Atomics.notify`. The parent blocks on `Atomics.wait(sab, 0, 0, timeoutMs)`
+ * and wakes when the worker notifies — OR when the timeout expires, in which
+ * case the parent terminates the worker.
+ *
+ * SECURITY: The parent must NOT rely on the `message` event alone, because
+ * `Atomics.wait` blocks the main thread's event loop. The SAB signal is the
+ * authoritative wake source. The parent reads the reply AFTER wake by draining
+ * the worker's `receiveMessageOnPort` queue.
+ */
+const WORKER_SOURCE = `
+const { workerData } = require('node:worker_threads');
+const { signalSab, replyPort, req } = workerData;
+const view = new Int32Array(signalSab);
+try {
+  const re = new RegExp(req.source, req.flags);
+  let reply;
+  if (req.op === 'test') {
+    re.lastIndex = 0;
+    reply = { ok: true, op: 'test', matched: re.test(req.input) };
+  } else if (req.op === 'replace') {
+    re.lastIndex = 0;
+    reply = { ok: true, op: 'replace', output: req.input.replace(re, req.replacer) };
+  } else if (req.op === 'matchAll') {
+    // Force the global flag on so matchAll is meaningful.
+    const flags = req.flags.includes('g') ? req.flags : req.flags + 'g';
+    const gre = new RegExp(req.source, flags);
+    const out = [];
+    for (const m of req.input.matchAll(gre)) {
+      out.push(m[0]);
+    }
+    reply = { ok: true, op: 'matchAll', matches: out };
+  } else {
+    reply = { ok: false, error: 'unknown op: ' + req.op };
+  }
+  replyPort.postMessage(reply);
+} catch (err) {
+  replyPort.postMessage({ ok: false, error: err && err.message ? err.message : String(err) });
+} finally {
+  // Signal completion via SAB so the parent's Atomics.wait unblocks. The parent
+  // then drains the replyPort synchronously via receiveMessageOnPort.
+  Atomics.store(view, 0, 1);
+  Atomics.notify(view, 0);
+}
+`;
+/**
+ * Synchronous wrapper around the worker. Middleware hot paths call `.test()`
+ * and `.replace()` inside tight synchronous loops (see `redactSecrets`), so the
+ * public `SafeRegex` surface has to be synchronous to be a drop-in replacement.
+ *
+ * How it works:
+ *   1. Allocate a 4-byte SharedArrayBuffer. The worker and parent both see it.
+ *   2. Spawn the worker with `workerData: { signalSab, req }`.
+ *   3. Parent blocks on `Atomics.wait(view, 0, 0, timeoutMs)` — allowed on the
+ *      Node main thread (unlike the browser).
+ *   4. Worker computes the result, posts the reply message, then writes `1` to
+ *      the SAB and calls `Atomics.notify`. The SAB notify is the authoritative
+ *      wake — the message event cannot fire because the event loop is blocked.
+ *   5. Parent wakes, drains the worker's message queue synchronously via
+ *      `receiveMessageOnPort`, then terminates the worker.
+ *
+ * On timeout the parent `terminate()`s the worker — a hard kill that stops a
+ * catastrophic backtracker cold.
+ */
+function runInWorkerSync(req, timeoutMs) {
+    const signalSab = new SharedArrayBuffer(4);
+    const view = new Int32Array(signalSab);
+    // Create a MessageChannel so the parent can drain the reply synchronously
+    // via `receiveMessageOnPort`. We give the worker the `port1` end and keep
+    // `port2` on the parent side.
+    const { port1: workerSendPort, port2: parentRecvPort } = new MessageChannel();
+    const worker = new Worker(WORKER_SOURCE, {
+        eval: true,
+        workerData: { signalSab, replyPort: workerSendPort, req },
+        transferList: [workerSendPort],
+    });
+    // Don't pin the process on the worker's existence.
+    worker.unref();
+    // Block this thread until the worker signals completion OR the timeout
+    // expires. `Atomics.wait` is allowed on the Node main thread (unlike the
+    // browser, where it is blocked on the UI thread).
+    const waitResult = Atomics.wait(view, 0, 0, timeoutMs);
+    if (waitResult === 'timed-out') {
+        // Worker is still running — kill it and report timeout.
+        void worker.terminate();
+        parentRecvPort.close();
+        return { reply: null, timedOut: true };
+    }
+    // Worker signaled completion. Drain the port queue synchronously to
+    // recover the reply payload. `receiveMessageOnPort` returns `undefined` if
+    // no message is queued — that should not happen on the happy path because
+    // the worker posts the message BEFORE notifying the SAB, but we guard
+    // defensively.
+    let reply = null;
+    const msg = receiveMessageOnPort(parentRecvPort);
+    if (msg !== undefined) {
+        reply = msg.message;
+    }
+    // Release the worker thread and close the port.
+    void worker.terminate();
+    parentRecvPort.close();
+    if (reply !== null) {
+        return { reply, timedOut: false };
+    }
+    return { reply: { ok: false, error: 'worker produced no result' }, timedOut: false };
+}
+/**
+ * Wrap a RegExp in a timeout-enforced `SafeRegex`. Compilation happens both in
+ * the parent (to catch syntax errors early) and inside the worker (so a
+ * catastrophic compile or match spends only worker CPU).
+ *
+ * SECURITY: callers should pass regexes that have ALSO been cleared by
+ * `safe-regex` at load time — the timeout is a defense-in-depth backstop, not
+ * a replacement for static analysis. See `scripts/lint-safe-regex.mjs` and the
+ * load-time check in `src/policy/loader.ts`.
+ */
+export function wrapRegex(pattern, opts) {
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const onTimeout = opts?.onTimeout;
+    const source = pattern.source;
+    const flags = pattern.flags;
+    const emitTimeout = (input) => {
+        if (onTimeout) {
+            try {
+                onTimeout(pattern, input);
+            }
+            catch {
+                // Callback errors MUST NOT break middleware. Swallow silently — the
+                // middleware has its own audit path if it cares.
+            }
+        }
+    };
+    return {
+        pattern,
+        test(input) {
+            const { reply, timedOut } = runInWorkerSync({ op: 'test', source, flags, input }, timeoutMs);
+            if (timedOut) {
+                emitTimeout(input);
+                return { matched: false, timedOut: true };
+            }
+            if (reply && reply.ok && reply.op === 'test') {
+                return { matched: reply.matched, timedOut: false };
+            }
+            // Worker errored (compile error, etc.) — treat as no match, no timeout.
+            return { matched: false, timedOut: false };
+        },
+        replace(input, replacer) {
+            const { reply, timedOut } = runInWorkerSync({ op: 'replace', source, flags, input, replacer }, timeoutMs);
+            if (timedOut) {
+                emitTimeout(input);
+                return { output: input, timedOut: true };
+            }
+            if (reply && reply.ok && reply.op === 'replace') {
+                return { output: reply.output, timedOut: false };
+            }
+            // Worker errored — preserve input unchanged (never corrupt payload).
+            return { output: input, timedOut: false };
+        },
+        matchAll(input) {
+            const { reply, timedOut } = runInWorkerSync({ op: 'matchAll', source, flags, input }, timeoutMs);
+            if (timedOut) {
+                emitTimeout(input);
+                return { matches: [], timedOut: true };
+            }
+            if (reply && reply.ok && reply.op === 'matchAll') {
+                return { matches: reply.matches, timedOut: false };
+            }
+            // Worker errored — return empty match set.
+            return { matches: [], timedOut: false };
+        },
+    };
+}

package/dist/gateway/reviewers/claude-self.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ClaudeSelfReviewer — the runtime fallback for the adversarial reviewer
+ * slot (G11.2).
+ *
+ * When Codex is unreachable (rate-limited, unauthenticated, CLI missing)
+ * and the operator hasn't opted into a first-class no-Codex policy, we
+ * still want SOMETHING pushing back on the diff before it lands. A fresh-
+ * context Opus call with a review-only system prompt is not a cross-model
+ * check — it's the same family reviewing its own output — so we label every
+ * result `degraded: true` so the audit trail is honest about it.
+ *
+ * ## Design notes
+ *
+ * - One-shot, no conversation history. The SDK call is synchronous from
+ *   our caller's perspective.
+ * - We pin the model id in `version` so older audit entries stay
+ *   reproducible when we bump the default.
+ * - The model is prompted to return STRICT JSON matching `ReviewResult`.
+ *   If parsing fails we return `verdict: 'error'` rather than guessing —
+ *   the operator gets a clear signal that the fallback didn't work.
+ * - Rate-limit / 5xx errors bubble up as `verdict: 'error'` with the raw
+ *   message; callers can decide to retry, prompt the human, or abort.
+ * - We cap the diff at 200KB and note the truncation in the summary. The
+ *   inbound token budget for a big Opus call is much larger, but a 200KB
+ *   diff is already a red flag on its own and we don't want to silently
+ *   eat massive payloads.
+ */
+import { recordTelemetry } from '../observability/codex-telemetry.js';
+import type { AdversarialReviewer, ReviewRequest, ReviewResult } from './types.js';
+/**
+ * Thin shape of the one SDK method we call. Lets the tests swap in a fake
+ * without pulling the full Anthropic client into the unit test. Shape
+ * mirrors `client.messages.create` closely enough for our purposes.
+ */
+export interface MessagesCreateFn {
+    (params: {
+        model: string;
+        max_tokens: number;
+        system: string;
+        messages: Array<{
+            role: 'user';
+            content: string;
+        }>;
+    }): Promise<{
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }>;
+}
+/**
+ * Constructor seams let tests inject a fake exec/SDK without stubbing the
+ * module registry. Production callers use the defaults.
+ */
+export interface ClaudeSelfReviewerOptions {
+    apiKey?: string;
+    model?: string;
+    create?: MessagesCreateFn;
+    /**
+     * Repo root used for the telemetry write path (`<baseDir>/.rea/metrics.jsonl`).
+     * Defaults to `process.cwd()`. Tests inject a temp dir so they don't scribble
+     * into the repo's real metrics file.
+     */
+    baseDir?: string;
+    /**
+     * Test seam — override the telemetry-record function so unit tests can
+     * assert on the exact shape without hitting disk. Defaults to the real
+     * `recordTelemetry` helper.
+     */
+    recordTelemetryFn?: typeof recordTelemetry;
+}
+export declare class ClaudeSelfReviewer implements AdversarialReviewer {
+    readonly name = "claude-self";
+    readonly version: string;
+    private readonly apiKey;
+    private readonly createFn;
+    private readonly baseDir;
+    private readonly recordTelemetryFn;
+    constructor(opts?: ClaudeSelfReviewerOptions);
+    /**
+     * Cheap check. We don't actually ping the API — the selector only needs
+     * to know whether we CAN try. If the key is bogus we'll find out in
+     * `review()` and surface it as `verdict: 'error'`.
+     */
+    isAvailable(): Promise<boolean>;
+    review(req: ReviewRequest): Promise<ReviewResult>;
+    /**
+     * Fire-and-forget telemetry write. The helper itself is fail-soft, but a
+     * misbehaving injected `recordTelemetryFn` (synchronous throw) could
+     * still escape a bare `void fn(...)`. This wrapper catches both sync and
+     * async rejections so a telemetry bug never breaks a review.
+     */
+    private emitTelemetry;
+    /**
+     * Resolve the create() closure lazily so we only build the real client
+     * when there's an API key and nothing was injected.
+     */
+    private getCreateFn;
+}

package/dist/gateway/reviewers/claude-self.js

@@ -0,0 +1,316 @@
+/**
+ * ClaudeSelfReviewer — the runtime fallback for the adversarial reviewer
+ * slot (G11.2).
+ *
+ * When Codex is unreachable (rate-limited, unauthenticated, CLI missing)
+ * and the operator hasn't opted into a first-class no-Codex policy, we
+ * still want SOMETHING pushing back on the diff before it lands. A fresh-
+ * context Opus call with a review-only system prompt is not a cross-model
+ * check — it's the same family reviewing its own output — so we label every
+ * result `degraded: true` so the audit trail is honest about it.
+ *
+ * ## Design notes
+ *
+ * - One-shot, no conversation history. The SDK call is synchronous from
+ *   our caller's perspective.
+ * - We pin the model id in `version` so older audit entries stay
+ *   reproducible when we bump the default.
+ * - The model is prompted to return STRICT JSON matching `ReviewResult`.
+ *   If parsing fails we return `verdict: 'error'` rather than guessing —
+ *   the operator gets a clear signal that the fallback didn't work.
+ * - Rate-limit / 5xx errors bubble up as `verdict: 'error'` with the raw
+ *   message; callers can decide to retry, prompt the human, or abort.
+ * - We cap the diff at 200KB and note the truncation in the summary. The
+ *   inbound token budget for a big Opus call is much larger, but a 200KB
+ *   diff is already a red flag on its own and we don't want to silently
+ *   eat massive payloads.
+ */
+import Anthropic, { APIError } from '@anthropic-ai/sdk';
+import { recordTelemetry } from '../observability/codex-telemetry.js';
+/** Pin the model id — audit entries reference this verbatim. */
+const CLAUDE_MODEL_ID = 'claude-opus-4-7';
+/** 200KB cap on the diff before we truncate and flag degraded. */
+const DIFF_TRUNCATE_BYTES = 200 * 1024;
+/** Bounded output so a runaway model can't exhaust our token budget. */
+const MAX_OUTPUT_TOKENS = 4096;
+const SYSTEM_PROMPT = `You are an adversarial code reviewer. A diff will be provided along with
+commit metadata. Identify high-impact security, correctness, edge-case,
+test-gap, api-design, or performance issues. Do not restate what the diff
+does; surface what is wrong or risky.
+
+Respond with STRICT JSON matching exactly this schema. Do not include
+markdown fences, commentary, or any text outside the JSON object:
+
+{
+  "verdict": "pass" | "concerns" | "blocking" | "error",
+  "summary": "one sentence",
+  "findings": [
+    {
+      "category": "security" | "correctness" | "edge-case" | "test-gap" | "api-design" | "performance",
+      "severity": "high" | "medium" | "low",
+      "file": "relative/path",
+      "line": 123,
+      "issue": "short problem statement",
+      "evidence": "optional quote from the diff",
+      "suggested_fix": "optional one-line fix hint"
+    }
+  ]
+}
+
+Return an empty findings array for a clean pass. Use "blocking" only for
+issues that must be fixed before merge.`;
+function buildUserMessage(req, diffWasTruncated) {
+    const truncNote = diffWasTruncated
+        ? '\n\nNOTE: The diff was truncated to 200KB. The review is necessarily partial.'
+        : '';
+    return [
+        `Branch: ${req.branch}`,
+        `Head SHA: ${req.head_sha}`,
+        `Diffed against: ${req.target}`,
+        '',
+        '## Commit log',
+        req.commit_log || '(empty)',
+        '',
+        '## Diff',
+        req.diff || '(empty)',
+        truncNote,
+    ].join('\n');
+}
+/**
+ * Safe parse — we don't want a malformed model response to crash the push
+ * gate. Any parse failure or shape mismatch folds into an error verdict.
+ */
+function parseModelJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            error: `unparseable JSON from model: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return { error: 'model response was not a JSON object' };
+    }
+    const obj = parsed;
+    const verdict = obj['verdict'];
+    const summary = obj['summary'];
+    const findings = obj['findings'];
+    const validVerdicts = ['pass', 'concerns', 'blocking', 'error'];
+    if (typeof verdict !== 'string' || !validVerdicts.includes(verdict)) {
+        return { error: `invalid verdict: ${String(verdict)}` };
+    }
+    if (typeof summary !== 'string') {
+        return { error: 'missing or non-string summary' };
+    }
+    if (!Array.isArray(findings)) {
+        return { error: 'missing or non-array findings' };
+    }
+    // Findings get shallow validation — we pass each through a narrow guard
+    // and drop any entries that can't be coerced. A noisy model is better
+    // handled by discarding junk than by erroring the whole review.
+    const cleanFindings = [];
+    for (const f of findings) {
+        const finding = toReviewFinding(f);
+        if (finding !== undefined)
+            cleanFindings.push(finding);
+    }
+    return {
+        reviewer_name: 'claude-self',
+        reviewer_version: CLAUDE_MODEL_ID,
+        verdict: verdict,
+        findings: cleanFindings,
+        summary,
+        // Always true for this reviewer — same-model is structurally degraded.
+        // Callers that compose results should keep this value, not overwrite it.
+        degraded: true,
+    };
+}
+function toReviewFinding(input) {
+    if (typeof input !== 'object' || input === null)
+        return undefined;
+    const o = input;
+    const validCategories = [
+        'security',
+        'correctness',
+        'edge-case',
+        'test-gap',
+        'api-design',
+        'performance',
+    ];
+    const validSeverities = ['high', 'medium', 'low'];
+    if (typeof o['category'] !== 'string' || !validCategories.includes(o['category'])) {
+        return undefined;
+    }
+    if (typeof o['severity'] !== 'string' || !validSeverities.includes(o['severity'])) {
+        return undefined;
+    }
+    if (typeof o['file'] !== 'string')
+        return undefined;
+    if (typeof o['issue'] !== 'string')
+        return undefined;
+    const out = {
+        category: o['category'],
+        severity: o['severity'],
+        file: o['file'],
+        issue: o['issue'],
+    };
+    if (typeof o['line'] === 'number')
+        out.line = o['line'];
+    if (typeof o['start_line'] === 'number')
+        out.start_line = o['start_line'];
+    if (typeof o['evidence'] === 'string')
+        out.evidence = o['evidence'];
+    if (typeof o['suggested_fix'] === 'string')
+        out.suggested_fix = o['suggested_fix'];
+    return out;
+}
+function errorResult(message, summary, degradedNote) {
+    return {
+        reviewer_name: 'claude-self',
+        reviewer_version: CLAUDE_MODEL_ID,
+        verdict: 'error',
+        findings: [],
+        summary: `${summary}${degradedNote}`,
+        degraded: true,
+        error: message,
+    };
+}
+export class ClaudeSelfReviewer {
+    name = 'claude-self';
+    version;
+    apiKey;
+    createFn;
+    baseDir;
+    recordTelemetryFn;
+    constructor(opts = {}) {
+        this.version = opts.model ?? CLAUDE_MODEL_ID;
+        this.apiKey = opts.apiKey ?? process.env['ANTHROPIC_API_KEY'];
+        this.createFn = opts.create;
+        this.baseDir = opts.baseDir ?? process.cwd();
+        this.recordTelemetryFn = opts.recordTelemetryFn ?? recordTelemetry;
+    }
+    /**
+     * Cheap check. We don't actually ping the API — the selector only needs
+     * to know whether we CAN try. If the key is bogus we'll find out in
+     * `review()` and surface it as `verdict: 'error'`.
+     */
+    async isAvailable() {
+        // When a test injects `create`, treat the reviewer as available so we
+        // don't need to juggle fake env in every test.
+        if (this.createFn !== undefined)
+            return true;
+        return this.apiKey !== undefined && this.apiKey.length > 0;
+    }
+    async review(req) {
+        const create = this.getCreateFn();
+        if (create === undefined) {
+            return errorResult('ANTHROPIC_API_KEY not set', 'claude-self fallback unavailable: no API key', '');
+        }
+        const diffBytes = Buffer.byteLength(req.diff, 'utf8');
+        const truncated = diffBytes > DIFF_TRUNCATE_BYTES;
+        const effectiveDiff = truncated
+            ? req.diff.slice(0, DIFF_TRUNCATE_BYTES)
+            : req.diff;
+        const userMessage = buildUserMessage({ ...req, diff: effectiveDiff }, truncated);
+        // G11.5 — measure the SDK call. The telemetry write is best-effort and
+        // fire-and-forget; it MUST NOT block or fail the review. We call
+        // `recordTelemetryFn` in a fire-and-forget void expression; the helper
+        // itself is already fail-soft (single stderr warn on error).
+        const startedAt = Date.now();
+        let response;
+        try {
+            response = await create({
+                model: this.version,
+                max_tokens: MAX_OUTPUT_TOKENS,
+                system: SYSTEM_PROMPT,
+                messages: [
+                    {
+                        role: 'user',
+                        content: userMessage,
+                    },
+                ],
+            });
+        }
+        catch (err) {
+            // Rate-limits, 5xx, network errors all land here. Surface the raw
+            // message so operators can act on it; the caller decides whether
+            // to retry or abort.
+            const message = err instanceof APIError ? `API ${err.status ?? '?'}: ${err.message}` : err instanceof Error ? err.message : String(err);
+            this.emitTelemetry({
+                invocation_type: 'adversarial-review',
+                input_text: userMessage,
+                output_text: '',
+                duration_ms: Date.now() - startedAt,
+                exit_code: 1,
+                stderr: message,
+            });
+            return errorResult(message, 'claude-self review failed', '');
+        }
+        const text = response.content
+            .filter((c) => c.type === 'text')
+            .map((c) => c.text ?? '')
+            .join('');
+        const parsed = parseModelJson(text);
+        if ('error' in parsed) {
+            this.emitTelemetry({
+                invocation_type: 'adversarial-review',
+                input_text: userMessage,
+                output_text: text,
+                duration_ms: Date.now() - startedAt,
+                exit_code: 1,
+                stderr: parsed.error,
+            });
+            return errorResult(parsed.error, 'claude-self produced unparseable output', '');
+        }
+        if (truncated) {
+            parsed.summary = `[diff truncated to 200KB] ${parsed.summary}`;
+        }
+        // Defense in depth — parseModelJson should always set degraded=true
+        // for this reviewer, but this reviewer is the canonical authority on
+        // that flag so re-pin it.
+        parsed.degraded = true;
+        this.emitTelemetry({
+            invocation_type: 'adversarial-review',
+            input_text: userMessage,
+            output_text: text,
+            duration_ms: Date.now() - startedAt,
+            exit_code: 0,
+        });
+        return parsed;
+    }
+    /**
+     * Fire-and-forget telemetry write. The helper itself is fail-soft, but a
+     * misbehaving injected `recordTelemetryFn` (synchronous throw) could
+     * still escape a bare `void fn(...)`. This wrapper catches both sync and
+     * async rejections so a telemetry bug never breaks a review.
+     */
+    emitTelemetry(input) {
+        try {
+            void Promise.resolve(this.recordTelemetryFn(this.baseDir, input)).catch(() => {
+                /* swallowed — telemetry is observational, never fatal */
+            });
+        }
+        catch {
+            /* same rationale — a sync throw from the injected fn is contained */
+        }
+    }
+    /**
+     * Resolve the create() closure lazily so we only build the real client
+     * when there's an API key and nothing was injected.
+     */
+    getCreateFn() {
+        if (this.createFn !== undefined)
+            return this.createFn;
+        if (this.apiKey === undefined || this.apiKey.length === 0)
+            return undefined;
+        const client = new Anthropic({ apiKey: this.apiKey });
+        return async (params) => {
+            const res = await client.messages.create(params);
+            return {
+                content: res.content.map((block) => block.type === 'text' ? { type: 'text', text: block.text } : { type: block.type }),
+            };
+        };
+    }
+}

package/dist/gateway/reviewers/codex.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Codex adversarial reviewer adapter (G11.2).
+ *
+ * ## Why this class throws from `review()`
+ *
+ * The actual Codex review path is the `codex-adversarial` agent shipped under
+ * `.claude/agents/`, invoked from Claude Code via the `/codex-review` slash
+ * command (which eventually reaches the Codex plugin's
+ * `/codex:adversarial-review`). None of that is importable from TS — the
+ * agent runtime is the harness, not a library.
+ *
+ * `CodexReviewer` exists so:
+ *
+ *   1. `selectReviewer()` can return a typed reviewer handle with a stable
+ *      `name`/`version` that the audit log and CLI can surface.
+ *   2. `isAvailable()` can cheaply probe the CLI without invoking a review.
+ *   3. G11.3 (startup probe) and G11.4 (no-Codex policy) have something to
+ *      type-check against now, so the broader flow can land without waiting
+ *      for an in-process Codex SDK that may never ship.
+ *
+ * If we ever get a native Codex TS client, `review()` becomes real and this
+ * comment block goes away. Until then: treat a Codex selection as
+ * "dispatch to the agent", not "await reviewer.review(...)".
+ */
+import type { AdversarialReviewer, ReviewRequest, ReviewResult } from './types.js';
+/**
+ * Narrow test seam: the unit tests swap the exec implementation via the
+ * constructor so we don't have to hit the real CLI. Kept internal to this
+ * file — production callers always use the default.
+ */
+export type ExecFileFn = (file: string, args: readonly string[], options: {
+    timeout: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare class CodexReviewer implements AdversarialReviewer {
+    readonly name = "codex";
+    private readonly exec;
+    private cachedVersion;
+    constructor(opts?: {
+        exec?: ExecFileFn;
+    });
+    /**
+     * Lazily populated via `codex --version`. We don't block construction on
+     * the probe because the selector calls `isAvailable()` before it commits
+     * to Codex, so we'll have a fresh value by the time anything reads it.
+     */
+    get version(): string;
+    isAvailable(): Promise<boolean>;
+    /**
+     * Not invokable from TS — see the file header. The selector contract is
+     * "CodexReviewer handles mean dispatch to the codex-adversarial agent";
+     * if a caller ignores that and awaits this, we throw loudly rather than
+     * silently produce a bad `ReviewResult`.
+     *
+     * TODO(0.3.0): when Codex ships a native TS client, this path will
+     * actually run the review. At that point, instrument with
+     * `recordTelemetry` the same way `ClaudeSelfReviewer.review()` does
+     * today (G11.5). The throwing placeholder below is deliberately NOT
+     * instrumented — there is nothing to measure.
+     */
+    review(_req: ReviewRequest): Promise<ReviewResult>;
+}