@bookedsolid/rea 0.1.0 → 0.2.0

package/dist/gateway/middleware/kill-switch.d.ts

@@ -1,10 +1,25 @@
 import type { Middleware } from './chain.js';
 /**
- * Checks for `.rea/HALT` file. If present, denies the invocation.
+ * HALT semantic guarantee:
+ *   - HALT is read exactly once per invocation, at the top of this middleware layer.
+ *   - Decision is final for the remainder of the chain; downstream middleware and
+ *     the terminal never re-check HALT.
+ *   - Creating HALT mid-flight does NOT cancel in-flight invocations. Remove HALT
+ *     to re-enable new invocations; outstanding ones complete.
+ *   - This layer is first in the chain so the decision frames every other layer's
+ *     view. Do not reorder.
  *
- * SECURITY: Validates HALT is a regular file (not directory/symlink to sensitive file).
- * SECURITY: Symlinks must resolve to a target within `.rea/`.
- * SECURITY: Caps read size to prevent oversized error strings.
- * SECURITY: Fails closed on unexpected errors.
+ * Implementation:
+ *   - Exactly ONE syscall on the HALT file per invocation: `fs.open(path, O_RDONLY)`.
+ *     There is no preceding stat/exists/lstat call, so there is no TOCTOU window
+ *     between a check and a subsequent open.
+ *   - ENOENT on open  → HALT absent → proceed with the chain.
+ *   - Open succeeds   → HALT present → deny. The file descriptor is then used
+ *     (best-effort) to read the reason string for the error message, with the
+ *     read size capped at {@link MAX_HALT_READ_BYTES}. The denial does NOT depend
+ *     on the read succeeding.
+ *   - Any other errno → unknown state → deny (fail-closed).
+ *   - The decision is recorded on `ctx.metadata.halt_decision` for audit and is
+ *     never re-consulted by downstream middleware.
  */
 export declare function createKillSwitchMiddleware(baseDir: string): Middleware;

package/dist/gateway/middleware/kill-switch.js

@@ -6,53 +6,75 @@ const MAX_HALT_READ_BYTES = 1024;
 const REA_DIR = '.rea';
 const HALT_FILE = 'HALT';
 /**
- * Checks for `.rea/HALT` file. If present, denies the invocation.
+ * HALT semantic guarantee:
+ *   - HALT is read exactly once per invocation, at the top of this middleware layer.
+ *   - Decision is final for the remainder of the chain; downstream middleware and
+ *     the terminal never re-check HALT.
+ *   - Creating HALT mid-flight does NOT cancel in-flight invocations. Remove HALT
+ *     to re-enable new invocations; outstanding ones complete.
+ *   - This layer is first in the chain so the decision frames every other layer's
+ *     view. Do not reorder.
  *
- * SECURITY: Validates HALT is a regular file (not directory/symlink to sensitive file).
- * SECURITY: Symlinks must resolve to a target within `.rea/`.
- * SECURITY: Caps read size to prevent oversized error strings.
- * SECURITY: Fails closed on unexpected errors.
+ * Implementation:
+ *   - Exactly ONE syscall on the HALT file per invocation: `fs.open(path, O_RDONLY)`.
+ *     There is no preceding stat/exists/lstat call, so there is no TOCTOU window
+ *     between a check and a subsequent open.
+ *   - ENOENT on open  → HALT absent → proceed with the chain.
+ *   - Open succeeds   → HALT present → deny. The file descriptor is then used
+ *     (best-effort) to read the reason string for the error message, with the
+ *     read size capped at {@link MAX_HALT_READ_BYTES}. The denial does NOT depend
+ *     on the read succeeding.
+ *   - Any other errno → unknown state → deny (fail-closed).
+ *   - The decision is recorded on `ctx.metadata.halt_decision` for audit and is
+ *     never re-consulted by downstream middleware.
  */
 export function createKillSwitchMiddleware(baseDir) {
     return async (ctx, next) => {
         const haltPath = path.join(baseDir, REA_DIR, HALT_FILE);
+        let fh;
         try {
-            const stat = await fs.stat(haltPath);
-            if (!stat.isFile()) {
-                ctx.status = InvocationStatus.Denied;
-                ctx.error = 'Kill switch active: HALT exists (non-file)';
-                return;
-            }
-            const lstat = await fs.lstat(haltPath);
-            if (lstat.isSymbolicLink()) {
-                const target = await fs.realpath(haltPath);
-                const reaDir = path.join(baseDir, REA_DIR);
-                if (!target.startsWith(reaDir)) {
-                    ctx.status = InvocationStatus.Denied;
-                    ctx.error = 'Kill switch active: HALT is a symlink outside .rea/';
-                    return;
-                }
-            }
-            const fh = await fs.open(haltPath, fsConstants.O_RDONLY);
-            try {
-                const buf = Buffer.alloc(MAX_HALT_READ_BYTES);
-                const { bytesRead } = await fh.read(buf, 0, MAX_HALT_READ_BYTES, 0);
-                const reason = buf.subarray(0, bytesRead).toString('utf8').trim();
-                ctx.status = InvocationStatus.Denied;
-                ctx.error = `Kill switch active: ${reason}`;
-            }
-            finally {
-                await fh.close();
-            }
-            return;
+            fh = await fs.open(haltPath, fsConstants.O_RDONLY);
         }
         catch (err) {
-            if (err.code === 'ENOENT') {
+            const errno = err.code;
+            if (errno === 'ENOENT') {
+                // HALT absent at the moment of check. Decision is final — no re-check.
+                ctx.metadata.halt_decision = 'absent';
+                ctx.metadata.halt_at_invocation = null;
                 await next();
                 return;
             }
+            // Any other errno (EACCES, EPERM, EISDIR on some platforms, EIO, …) is an
+            // unknown state. Fail closed: deny the invocation and surface the errno.
             ctx.status = InvocationStatus.Denied;
-            ctx.error = `Kill switch check failed: ${err.message}`;
+            ctx.error = `Kill switch check failed: ${errno ?? 'unknown'} (${err.message})`;
+            ctx.metadata.halt_decision = 'unknown';
+            ctx.metadata.halt_at_invocation = null;
+            return;
+        }
+        // Open succeeded → HALT is present → decision is locked to DENY.
+        // The subsequent read is best-effort only; it shapes the error message but
+        // does NOT influence the decision. Timestamp reflects the moment the
+        // decision was made, not the file's mtime.
+        ctx.metadata.halt_decision = 'present';
+        ctx.metadata.halt_at_invocation = new Date().toISOString();
+        let reason = '';
+        try {
+            const buf = Buffer.alloc(MAX_HALT_READ_BYTES);
+            const { bytesRead } = await fh.read(buf, 0, MAX_HALT_READ_BYTES, 0);
+            reason = buf.subarray(0, bytesRead).toString('utf8').trim();
+        }
+        catch {
+            // Read failed (e.g., EISDIR on Linux when HALT is a directory). The
+            // denial still stands — we just fall back to a generic reason string.
+            reason = '';
+        }
+        finally {
+            await fh.close().catch(() => {
+                /* closing a dead fd is not actionable — denial already recorded */
+            });
         }
+        ctx.status = InvocationStatus.Denied;
+        ctx.error = reason ? `Kill switch active: ${reason}` : 'Kill switch active: HALT present';
     };
 }

package/dist/gateway/middleware/redact.d.ts

@@ -1,16 +1,93 @@
 import type { Middleware } from './chain.js';
+import { type SafeRegex, type MatchTimeoutOptions } from '../redact-safe/match-timeout.js';
 /**
- * Redact secrets from a string, returning the redacted string and list of redacted field names.
+ * Patterns that match common secret formats.
+ * Each pattern has a name (for audit logging) and a regex.
+ *
+ * SECURITY: Patterns use case-insensitive flag where applicable.
+ * SECURITY: Input is sanitized (null bytes stripped) before matching.
+ * SECURITY (G3): Every pattern is wrapped in a `SafeRegex` with a per-call
+ *   timeout so a catastrophic backtracker cannot hang the gateway. See
+ *   `src/gateway/redact-safe/match-timeout.ts`.
+ */
+export declare const SECRET_PATTERNS: ReadonlyArray<{
+    name: string;
+    pattern: RegExp;
+}>;
+/**
+ * Sentinel inserted when a redaction pattern exceeds its timeout budget. The
+ * original field is replaced entirely — the middleware never lets a potentially
+ * secret-bearing string pass through when the scanner failed to complete.
+ */
+export declare const REDACT_TIMEOUT_SENTINEL = "[REDACTED: pattern timeout]";
+/**
+ * Identifier for the timeout audit event. Emitted on `ctx.metadata` as an
+ * array under this key so multiple timeouts in one invocation are recorded.
+ */
+export declare const REDACT_TIMEOUT_METADATA_KEY = "redact.regex_timeout";
+export interface RedactTimeoutEvent {
+    event: 'redact.regex_timeout';
+    pattern_source: 'default' | 'user';
+    pattern_id: string;
+    input_bytes: number;
+    timeout_ms: number;
+}
+/**
+ * A compiled secret pattern — the original `RegExp` plus a `SafeRegex` wrapper
+ * that carries the configured timeout + audit callback. Precompiled at
+ * middleware-creation time so the per-call worker spawn is the only overhead.
  */
-export declare function redactSecrets(input: string): {
+export interface CompiledSecretPattern {
+    name: string;
+    source: 'default' | 'user';
+    safe: SafeRegex;
+}
+/**
+ * Build a list of compiled SECRET_PATTERNS using the provided timeout options.
+ * Exported so the middleware factory can reuse it with its own `onTimeout`.
+ */
+export declare function compileDefaultSecretPatterns(opts?: MatchTimeoutOptions & {
+    source?: 'default' | 'user';
+}): CompiledSecretPattern[];
+/**
+ * Redact secrets from a string, returning the redacted string and the list of
+ * pattern names that matched. Timeouts are reported via `onTimeout` — the
+ * caller is responsible for audit accounting.
+ *
+ * On timeout for a given pattern, the scanner replaces the entire input with
+ * `REDACT_TIMEOUT_SENTINEL` (see the comment above the sentinel) and short-
+ * circuits further scanning of that value. This is the safe choice: we cannot
+ * let an un-scanned string leak downstream.
+ */
+export declare function redactSecrets(input: string, patterns: CompiledSecretPattern[], onTimeout?: (ev: {
+    name: string;
+    source: 'default' | 'user';
+    input: string;
+}) => void): {
     output: string;
     redacted: string[];
+    timedOut: boolean;
 };
+export interface RedactMiddlewareOptions {
+    /** Timeout budget for each regex test/replace call. Default 100ms. */
+    matchTimeoutMs?: number;
+    /** Optional user-supplied patterns (loaded from policy). */
+    userPatterns?: CompiledSecretPattern[];
+}
 /**
- * Post-execution middleware: scans tool output for secret patterns and redacts them.
+ * Build the redact middleware with a configured timeout budget and (optionally)
+ * user-supplied patterns loaded from policy. Both default and user patterns are
+ * wrapped in `SafeRegex` so every regex the middleware runs is bounded.
  *
- * SECURITY: For non-string results, redaction operates on individual string values
- * within the object structure rather than JSON.stringify→replace→JSON.parse, which
- * could corrupt the result if a replacement changes JSON structure.
+ * SECURITY: For non-string results, redaction operates on individual string
+ * values within the object structure rather than JSON.stringify → replace →
+ * JSON.parse, which could corrupt the result if a replacement changes JSON
+ * structure.
+ */
+export declare function createRedactMiddleware(opts?: RedactMiddlewareOptions): Middleware;
+/**
+ * Default-configured redact middleware (100ms timeout, default patterns only).
+ * Preserved for callers that don't need to configure; `createRedactMiddleware`
+ * is the new canonical factory.
  */
 export declare const redactMiddleware: Middleware;

package/dist/gateway/middleware/redact.js

@@ -1,11 +1,15 @@
+import { wrapRegex } from '../redact-safe/match-timeout.js';
 /**
  * Patterns that match common secret formats.
  * Each pattern has a name (for audit logging) and a regex.
  *
  * SECURITY: Patterns use case-insensitive flag where applicable.
  * SECURITY: Input is sanitized (null bytes stripped) before matching.
+ * SECURITY (G3): Every pattern is wrapped in a `SafeRegex` with a per-call
+ *   timeout so a catastrophic backtracker cannot hang the gateway. See
+ *   `src/gateway/redact-safe/match-timeout.ts`.
  */
-const SECRET_PATTERNS = [
+export const SECRET_PATTERNS = [
     { name: 'AWS Access Key', pattern: /AKIA[0-9A-Z]{16}/gi },
     {
         name: 'AWS Secret Key',
@@ -17,7 +21,11 @@ const SECRET_PATTERNS = [
         pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*["']?[A-Za-z0-9\-_.]{20,}["']?/gi,
     },
     { name: 'Bearer Token', pattern: /bearer\s+[A-Za-z0-9\-_.~+/]+=*/gi },
-    { name: 'Private Key', pattern: /-----BEGIN\s+(?:RSA\s+|EC\s+|DSA\s+)?PRIVATE\s+KEY-----/gi },
+    // PEM armor header — canonical format uses single spaces. Bounded repetition
+    // avoids the nested-`\s+` ReDoS pattern that safe-regex flags on the broader
+    // form (`\s+(?:FOO\s+|BAR\s+)?PRIVATE\s+KEY-----`). PEMs with non-space
+    // separators are non-standard and not in our threat model.
+    { name: 'Private Key', pattern: /-----BEGIN (?:(?:RSA|EC|DSA) )?PRIVATE KEY-----/gi },
     { name: 'Discord Token', pattern: /[MN][A-Za-z\d]{23,}\.[\w-]{6}\.[\w-]{27,}/g },
     // Base64-encoded AWS access key (AKIA... in base64 starts with QUTJQ)
     { name: 'Base64 AWS Key', pattern: /QUtJQ[A-Za-z0-9+/]{17,}={0,2}/g },
@@ -29,6 +37,17 @@ const SECRET_PATTERNS = [
     // Hugging Face access tokens
     { name: 'Hugging Face Token', pattern: /hf_[a-zA-Z0-9]{32,}/g },
 ];
+/**
+ * Sentinel inserted when a redaction pattern exceeds its timeout budget. The
+ * original field is replaced entirely — the middleware never lets a potentially
+ * secret-bearing string pass through when the scanner failed to complete.
+ */
+export const REDACT_TIMEOUT_SENTINEL = '[REDACTED: pattern timeout]';
+/**
+ * Identifier for the timeout audit event. Emitted on `ctx.metadata` as an
+ * array under this key so multiple timeouts in one invocation are recorded.
+ */
+export const REDACT_TIMEOUT_METADATA_KEY = 'redact.regex_timeout';
 /**
  * Strip null bytes and other control characters that could break regex matching.
  */
@@ -36,61 +55,129 @@ function sanitizeInput(input) {
     return input.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
 }
 /**
- * Redact secrets from a string, returning the redacted string and list of redacted field names.
+ * Build a list of compiled SECRET_PATTERNS using the provided timeout options.
+ * Exported so the middleware factory can reuse it with its own `onTimeout`.
  */
-export function redactSecrets(input) {
+export function compileDefaultSecretPatterns(opts = {}) {
+    const source = opts.source ?? 'default';
+    return SECRET_PATTERNS.map(({ name, pattern }) => ({
+        name,
+        source,
+        safe: wrapRegex(pattern, opts),
+    }));
+}
+/**
+ * Redact secrets from a string, returning the redacted string and the list of
+ * pattern names that matched. Timeouts are reported via `onTimeout` — the
+ * caller is responsible for audit accounting.
+ *
+ * On timeout for a given pattern, the scanner replaces the entire input with
+ * `REDACT_TIMEOUT_SENTINEL` (see the comment above the sentinel) and short-
+ * circuits further scanning of that value. This is the safe choice: we cannot
+ * let an un-scanned string leak downstream.
+ */
+export function redactSecrets(input, patterns, onTimeout) {
     let output = sanitizeInput(input);
     const redacted = [];
-    for (const { name, pattern } of SECRET_PATTERNS) {
-        // Reset lastIndex for global regexes
-        pattern.lastIndex = 0;
-        if (pattern.test(output)) {
-            pattern.lastIndex = 0;
-            output = output.replace(pattern, '[REDACTED]');
-            redacted.push(name);
+    for (const { name, source, safe } of patterns) {
+        const t = safe.test(output);
+        if (t.timedOut) {
+            if (onTimeout)
+                onTimeout({ name, source, input: output });
+            return { output: REDACT_TIMEOUT_SENTINEL, redacted: [name], timedOut: true };
+        }
+        if (!t.matched)
+            continue;
+        const r = safe.replace(output, '[REDACTED]');
+        if (r.timedOut) {
+            if (onTimeout)
+                onTimeout({ name, source, input: output });
+            return { output: REDACT_TIMEOUT_SENTINEL, redacted: [name], timedOut: true };
         }
+        output = r.output;
+        redacted.push(name);
     }
-    return { output, redacted };
+    return { output, redacted, timedOut: false };
 }
 /**
- * Post-execution middleware: scans tool output for secret patterns and redacts them.
+ * Helper: push a timeout event onto `ctx.metadata[REDACT_TIMEOUT_METADATA_KEY]`.
+ * Uses an array so multiple timeouts in one invocation are all recorded.
  *
- * SECURITY: For non-string results, redaction operates on individual string values
- * within the object structure rather than JSON.stringify→replace→JSON.parse, which
- * could corrupt the result if a replacement changes JSON structure.
+ * SECURITY: The input text is NEVER put into metadata — only `input_bytes`.
  */
-export const redactMiddleware = async (ctx, next) => {
-    // SECURITY: Pre-execution — scan arguments for secrets before they reach the downstream tool.
-    if (ctx.arguments) {
-        const argRedacted = [];
-        redactDeep(ctx.arguments, argRedacted);
-        if (argRedacted.length > 0) {
-            ctx.redacted_fields = [...new Set(argRedacted)];
-        }
-    }
-    await next();
-    if (ctx.result == null)
-        return;
-    if (typeof ctx.result === 'string') {
-        const { output, redacted } = redactSecrets(ctx.result);
-        if (redacted.length > 0) {
-            ctx.result = output;
-            ctx.redacted_fields = [...new Set([...(ctx.redacted_fields ?? []), ...redacted])];
-        }
-        return;
+function recordTimeoutOnCtx(ctx, name, source, inputBytes, timeoutMs) {
+    const ev = {
+        event: 'redact.regex_timeout',
+        pattern_source: source,
+        pattern_id: name,
+        input_bytes: inputBytes,
+        timeout_ms: timeoutMs,
+    };
+    const existing = ctx.metadata[REDACT_TIMEOUT_METADATA_KEY];
+    if (Array.isArray(existing)) {
+        existing.push(ev);
     }
-    // For objects, deeply redact all string values in-place
-    const allRedacted = [];
-    redactDeep(ctx.result, allRedacted);
-    if (allRedacted.length > 0) {
-        ctx.redacted_fields = [...new Set([...(ctx.redacted_fields ?? []), ...allRedacted])];
+    else {
+        ctx.metadata[REDACT_TIMEOUT_METADATA_KEY] = [ev];
     }
-};
+}
+/**
+ * Build the redact middleware with a configured timeout budget and (optionally)
+ * user-supplied patterns loaded from policy. Both default and user patterns are
+ * wrapped in `SafeRegex` so every regex the middleware runs is bounded.
+ *
+ * SECURITY: For non-string results, redaction operates on individual string
+ * values within the object structure rather than JSON.stringify → replace →
+ * JSON.parse, which could corrupt the result if a replacement changes JSON
+ * structure.
+ */
+export function createRedactMiddleware(opts = {}) {
+    const timeoutMs = opts.matchTimeoutMs ?? 100;
+    const defaultPatterns = compileDefaultSecretPatterns({ timeoutMs, source: 'default' });
+    const userPatterns = opts.userPatterns ?? [];
+    const allPatterns = [...defaultPatterns, ...userPatterns];
+    return async (ctx, next) => {
+        const recordTimeout = (name, source, input) => {
+            recordTimeoutOnCtx(ctx, name, source, Buffer.byteLength(input, 'utf8'), timeoutMs);
+        };
+        // SECURITY: Pre-execution — scan arguments for secrets before they reach the downstream tool.
+        if (ctx.arguments) {
+            const argRedacted = [];
+            redactDeep(ctx.arguments, argRedacted, allPatterns, recordTimeout);
+            if (argRedacted.length > 0) {
+                ctx.redacted_fields = [...new Set(argRedacted)];
+            }
+        }
+        await next();
+        if (ctx.result == null)
+            return;
+        if (typeof ctx.result === 'string') {
+            const { output, redacted } = redactSecrets(ctx.result, allPatterns, (ev) => recordTimeout(ev.name, ev.source, ev.input));
+            if (redacted.length > 0) {
+                ctx.result = output;
+                ctx.redacted_fields = [...new Set([...(ctx.redacted_fields ?? []), ...redacted])];
+            }
+            return;
+        }
+        // For objects, deeply redact all string values in-place
+        const allRedacted = [];
+        redactDeep(ctx.result, allRedacted, allPatterns, recordTimeout);
+        if (allRedacted.length > 0) {
+            ctx.redacted_fields = [...new Set([...(ctx.redacted_fields ?? []), ...allRedacted])];
+        }
+    };
+}
+/**
+ * Default-configured redact middleware (100ms timeout, default patterns only).
+ * Preserved for callers that don't need to configure; `createRedactMiddleware`
+ * is the new canonical factory.
+ */
+export const redactMiddleware = createRedactMiddleware();
 /**
  * Recursively walk an object/array and redact string values in-place.
  * Uses a WeakSet to guard against circular references.
  */
-function redactDeep(obj, redacted, seen = new WeakSet()) {
+function redactDeep(obj, redacted, patterns, onTimeout, seen = new WeakSet()) {
     if (obj == null || typeof obj !== 'object')
         return;
     // Guard against circular references
@@ -100,14 +187,14 @@ function redactDeep(obj, redacted, seen = new WeakSet()) {
     if (Array.isArray(obj)) {
         for (let i = 0; i < obj.length; i++) {
             if (typeof obj[i] === 'string') {
-                const { output, redacted: r } = redactSecrets(obj[i]);
+                const { output, redacted: r } = redactSecrets(obj[i], patterns, (ev) => onTimeout(ev.name, ev.source, ev.input));
                 if (r.length > 0) {
                     obj[i] = output;
                     redacted.push(...r);
                 }
             }
             else {
-                redactDeep(obj[i], redacted, seen);
+                redactDeep(obj[i], redacted, patterns, onTimeout, seen);
             }
         }
         return;
@@ -115,14 +202,14 @@ function redactDeep(obj, redacted, seen = new WeakSet()) {
     const record = obj;
     for (const key of Object.keys(record)) {
         if (typeof record[key] === 'string') {
-            const { output, redacted: r } = redactSecrets(record[key]);
+            const { output, redacted: r } = redactSecrets(record[key], patterns, (ev) => onTimeout(ev.name, ev.source, ev.input));
             if (r.length > 0) {
                 record[key] = output;
                 redacted.push(...r);
             }
         }
         else {
-            redactDeep(record[key], redacted, seen);
+            redactDeep(record[key], redacted, patterns, onTimeout, seen);
         }
     }
 }

package/dist/gateway/observability/codex-probe.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Codex availability probe (G11.3).
+ *
+ * Passive, periodic reachability check for the Codex CLI, used by `rea serve`
+ * at startup and by `rea doctor` to surface a one-line status about whether
+ * Codex is actually usable right now. This is INTENTIONALLY separate from
+ * the reviewer-selection path in `src/gateway/reviewers/select.ts`:
+ *
+ *   - The selector decides which reviewer to run for a specific push (it
+ *     respects `REA_REVIEWER`, registry pin, policy, etc.).
+ *   - The probe just reports "is the Codex CLI responding at all?" as a
+ *     observability signal — never gates a review.
+ *
+ * Startup must NEVER fail-closed on a probe failure. Codex going away is a
+ * degraded state, not a fatal one; the push gate has its own audited escape
+ * hatch (`REA_SKIP_CODEX_REVIEW`, G11.1).
+ *
+ * ## Probe shape
+ *
+ *   1. `codex --version`  — must exit 0 within {@link VERSION_TIMEOUT_MS}.
+ *      Success → `cli_installed: true` and `version` populated from stdout.
+ *   2. Catalog check     — see the `tryCatalogProbe` comment below. We try
+ *      a best-effort authenticated subcommand with a short timeout. If the
+ *      subcommand is unrecognized by this Codex build, we degrade to "assume
+ *      authenticated iff cli_installed is true" rather than flagging a false
+ *      negative.
+ *
+ * `cli_responsive` is the AND of both. Consumers should treat
+ * `cli_responsive: false` as "Codex may be unavailable — plan accordingly",
+ * not as authoritative proof that a specific review will fail.
+ *
+ * ## Concurrency
+ *
+ * `probe()` is safe to call concurrently. We serialize via a module-local
+ * promise; callers queue up behind the in-flight probe instead of kicking off
+ * duplicate exec calls. `start()` / `stop()` manage a single `setInterval`
+ * with `.unref()` so the probe never pins the event loop.
+ */
+/**
+ * Narrow test seam mirroring the shape in `src/gateway/reviewers/codex.ts`.
+ * Kept module-local; production callers never pass their own.
+ */
+export type ExecFileFn = (file: string, args: readonly string[], options: {
+    timeout: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Observable Codex state. Serialized verbatim into the doctor output and
+ * (later, G5) into a metrics export. Keep field names stable.
+ */
+export interface CodexProbeState {
+    /** `codex --version` exited 0 within the version-probe timeout. */
+    cli_installed: boolean;
+    /** Catalog probe succeeded (or was degraded-skipped — see module header). */
+    cli_authenticated: boolean;
+    /** `cli_installed && cli_authenticated`. */
+    cli_responsive: boolean;
+    /** ISO-8601 timestamp of the most recent `probe()` completion. */
+    last_probe_at: string;
+    /** Populated on failure; cleared on the next successful probe. */
+    last_error?: string;
+    /** Parsed from `codex --version` stdout on success. */
+    version?: string;
+}
+export interface CodexProbeOptions {
+    execFileFn?: ExecFileFn;
+    timeoutInstallMs?: number;
+    timeoutCatalogMs?: number;
+}
+export declare class CodexProbe {
+    private readonly exec;
+    private readonly versionTimeoutMs;
+    private readonly catalogTimeoutMs;
+    private state;
+    private inFlight;
+    private timer;
+    private readonly listeners;
+    constructor(opts?: CodexProbeOptions);
+    /**
+     * Execute a single probe. Safe to call concurrently — overlapping callers
+     * await the single in-flight attempt. Never throws.
+     */
+    probe(): Promise<CodexProbeState>;
+    /** Start periodic polling. Immediate probe, then every `intervalMs`. */
+    start(intervalMs?: number): void;
+    /** Stop periodic polling. Safe to call even if never started. */
+    stop(): void;
+    /** Snapshot of the most recent probe state. Never throws. */
+    getState(): CodexProbeState;
+    /**
+     * Subscribe to state transitions. Returns an unsubscribe function. The
+     * listener fires only when any observable field changes, not on every
+     * tick.
+     */
+    onStateChange(listener: (state: CodexProbeState) => void): () => void;
+    /** Core probe logic. Private — use `probe()`. */
+    private runProbe;
+    /**
+     * Try `codex catalog --json`. Returns:
+     *   - `{ ok: true }` on exit 0.
+     *   - `{ ok: false, skipped: true }` when the subcommand is unrecognized
+     *     (best-effort detection on stderr).
+     *   - `{ ok: false, skipped: false, error }` on any other failure.
+     */
+    private tryCatalogProbe;
+    /** Persist `next` and fire listeners if anything observable changed. */
+    private commit;
+}