@bookedsolid/rea 0.4.0 → 0.6.0

package/dist/gateway/downstream-pool.js

@@ -8,6 +8,13 @@
 import { DownstreamConnection } from './downstream.js';
 export class DownstreamPool {
     connections = new Map();
+    /**
+     * Cached tool counts from the most recent successful `listAllTools` cycle,
+     * keyed by server name. Surfaced via `healthSnapshot()` so the meta-tool
+     * can report per-server counts even when the current listing pass fails
+     * or is skipped. Stale but truthful > absent.
+     */
+    lastToolsCount = new Map();
     constructor(registry, logger) {
         for (const server of registry.servers) {
             if (!server.enabled)
@@ -45,6 +52,7 @@ export class DownstreamPool {
                 continue;
             try {
                 const tools = await conn.listTools();
+                this.lastToolsCount.set(server, tools.length);
                 for (const t of tools) {
                     const prefixed = {
                         ...t,
@@ -60,6 +68,35 @@ export class DownstreamPool {
         }
         return out;
     }
+    /**
+     * Snapshot per-server connection state for the `__rea__health` meta-tool.
+     * Pure / non-blocking — no MCP I/O — so it can be called while HALT is
+     * active or while other tool calls are in-flight.
+     */
+    healthSnapshot() {
+        const out = [];
+        for (const [name, conn] of this.connections) {
+            const cached = this.lastToolsCount.get(name);
+            const connected = conn.isConnected;
+            const healthy = conn.isHealthy;
+            // Only surface the cached tool count when the connection is BOTH
+            // connected AND healthy right now. Codex F1 caught that a dead
+            // downstream was showing its last-successful count alongside
+            // `healthy: false`, which is a worse-than-null diagnostic — operators
+            // would read "5 tools reachable" from a server that is reachable
+            // through exactly zero tools.
+            const tools_count = connected && healthy && typeof cached === 'number' ? cached : null;
+            out.push({
+                name,
+                enabled: true,
+                connected,
+                healthy,
+                last_error: conn.lastError,
+                tools_count,
+            });
+        }
+        return out;
+    }
     /**
      * Split a prefixed tool name and dispatch. Returns the raw result from the
      * downstream (the gateway response handler shapes it for the upstream reply).

package/dist/gateway/downstream.d.ts

@@ -93,6 +93,13 @@ export declare class DownstreamConnection {
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     private lastReconnectAt;
     private health;
+    /**
+     * The most recent error observed on this connection (connect or call
+     * failure). Surfaced via `__rea__health` so callers can diagnose an empty
+     * tool catalog without digging through stderr logs. Set to `null` after a
+     * successful connect/reconnect.
+     */
+    private lastErrorMessage;
     constructor(config: RegistryServer, 
     /**
      * Optional structured logger (G5). When omitted, connection lifecycle
@@ -102,6 +109,10 @@ export declare class DownstreamConnection {
     logger?: Logger | undefined);
     get name(): string;
     get isHealthy(): boolean;
+    /** True iff the underlying MCP client is currently connected. */
+    get isConnected(): boolean;
+    /** Last error observed, or null if the connection has never failed (or fully recovered). */
+    get lastError(): string | null;
     connect(): Promise<void>;
     listTools(): Promise<DownstreamToolInfo[]>;
     /**

package/dist/gateway/downstream.js

@@ -107,6 +107,13 @@ export class DownstreamConnection {
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     lastReconnectAt = 0;
     health = 'healthy';
+    /**
+     * The most recent error observed on this connection (connect or call
+     * failure). Surfaced via `__rea__health` so callers can diagnose an empty
+     * tool catalog without digging through stderr logs. Set to `null` after a
+     * successful connect/reconnect.
+     */
+    lastErrorMessage = null;
     constructor(config, 
     /**
      * Optional structured logger (G5). When omitted, connection lifecycle
@@ -123,6 +130,14 @@ export class DownstreamConnection {
     get isHealthy() {
         return this.health !== 'unhealthy';
     }
+    /** True iff the underlying MCP client is currently connected. */
+    get isConnected() {
+        return this.client !== null;
+    }
+    /** Last error observed, or null if the connection has never failed (or fully recovered). */
+    get lastError() {
+        return this.lastErrorMessage;
+    }
     async connect() {
         if (this.client !== null)
             return;
@@ -143,10 +158,13 @@ export class DownstreamConnection {
         }
         catch (err) {
             this.health = 'unhealthy';
-            throw new Error(`failed to resolve env for downstream "${this.config.name}": ${err instanceof Error ? err.message : err}`);
+            const msg = `failed to resolve env for downstream "${this.config.name}": ${err instanceof Error ? err.message : err}`;
+            this.lastErrorMessage = msg;
+            throw new Error(msg);
         }
         if (built.missing.length > 0) {
             this.health = 'unhealthy';
+            this.lastErrorMessage = `missing env: ${built.missing.join(', ')}`;
             // One line per missing var so grep/jq users can find the exact gap.
             // We intentionally do NOT log the env key name's VALUE (there is none —
             // it's unresolved) nor any other env values.
@@ -166,10 +184,13 @@ export class DownstreamConnection {
             await client.connect(transport);
             this.client = client;
             this.health = 'healthy';
+            this.lastErrorMessage = null;
         }
         catch (err) {
             this.health = 'unhealthy';
-            throw new Error(`failed to connect to downstream "${this.config.name}" (${this.config.command}): ${err instanceof Error ? err.message : err}`);
+            const msg = `failed to connect to downstream "${this.config.name}" (${this.config.command}): ${err instanceof Error ? err.message : err}`;
+            this.lastErrorMessage = msg;
+            throw new Error(msg);
         }
     }
     async listTools() {
@@ -190,7 +211,13 @@ export class DownstreamConnection {
             await this.connect();
         }
         try {
-            return await this.client.callTool({ name: toolName, arguments: args });
+            const result = await this.client.callTool({ name: toolName, arguments: args });
+            // Clear any lingering error from a previous transient failure. Without
+            // this, a connection that failed once and then recovered on the very
+            // next call (same client, no reconnect) would forever report the old
+            // error via `__rea__health`, misleading operators about live state.
+            this.lastErrorMessage = null;
+            return result;
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -212,6 +239,7 @@ export class DownstreamConnection {
                     // stamp the reconnect time so flap-guard can refuse rapid repeats.
                     this.reconnectAttempted = false;
                     this.lastReconnectAt = Date.now();
+                    this.lastErrorMessage = null;
                     this.logger?.info({
                         event: 'downstream.reconnected',
                         server_name: this.config.name,
@@ -221,16 +249,19 @@ export class DownstreamConnection {
                 }
                 catch (reconnectErr) {
                     this.health = 'unhealthy';
+                    const errMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
+                    this.lastErrorMessage = errMsg;
                     this.logger?.error({
                         event: 'downstream.reconnect_failed',
                         server_name: this.config.name,
                         message: `downstream "${this.config.name}" unhealthy after one reconnect`,
-                        error: reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr),
+                        error: errMsg,
                     });
-                    throw new Error(`downstream "${this.config.name}" unhealthy after one reconnect: ${reconnectErr instanceof Error ? reconnectErr.message : reconnectErr}`);
+                    throw new Error(`downstream "${this.config.name}" unhealthy after one reconnect: ${errMsg}`);
                 }
             }
             this.health = 'unhealthy';
+            this.lastErrorMessage = message;
             this.logger?.error({
                 event: 'downstream.call_failed',
                 server_name: this.config.name,

package/dist/gateway/meta/health.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Gateway-internal `__rea__health` meta-tool.
+ *
+ * WHY THIS EXISTS
+ * ===============
+ *
+ * The MCP `listTools` catalog the gateway advertises is the UNION of every
+ * healthy downstream's own catalog. When all downstreams are unhealthy — or
+ * the registry is empty, or fingerprints fail, or an env var is missing — the
+ * catalog is empty. From the LLM's perspective this is indistinguishable from
+ * a gateway that came up fine but happens to have nothing to proxy, and there
+ * is no tool it can call to ask "why is this empty?" because, well, the
+ * catalog is empty.
+ *
+ * This meta-tool closes that diagnostic gap: the gateway ALWAYS exposes
+ * `__rea__health` regardless of downstream state, the kill-switch, or the
+ * middleware chain. A caller can invoke it to get a snapshot of every
+ * registered server's connection state, last error, and tool count.
+ *
+ * DESIGN CHOICES
+ * --------------
+ *
+ * 1. Name shape: `__rea__health`. The leading `__` (instead of a normal
+ *    `<server>__<tool>` prefix) reserves the namespace for gateway-internal
+ *    tools. It never collides with a registered server because
+ *    `src/registry/loader.ts` restricts `name` to `^[a-z0-9][a-z0-9-]*$` —
+ *    no underscores allowed.
+ *
+ * 2. Short-circuit in `server.ts`: the CallTool handler matches on the
+ *    constant below BEFORE calling `splitPrefixed`, and responds directly
+ *    without running the middleware chain. Reasons, ordered:
+ *      (a) This tool must be callable while HALT is present — otherwise the
+ *          operator can't introspect a frozen gateway.
+ *      (b) Tier middleware would classify `health` as Write (default for
+ *          unlisted names) and deny L0 callers — wrong for read-only
+ *          introspection.
+ *      (c) There is no downstream to dispatch to — the entire middleware
+ *          chain is about getting to one safely.
+ *    The short-circuit still writes an audit record via `appendAuditRecord`
+ *    so invocations remain accountable.
+ *
+ * 3. Never throws. Health is the one tool the caller uses when things are
+ *    broken. Every field is best-effort; a missing value is surfaced as
+ *    `null`, not as an exception.
+ */
+import type { Policy } from '../../policy/types.js';
+import type { DownstreamHealth } from '../downstream-pool.js';
+/** Canonical MCP tool name exposed by the gateway. */
+export declare const META_HEALTH_TOOL_NAME = "__rea__health";
+/** `server_name` recorded in audit entries for this meta-tool. */
+export declare const META_SERVER_NAME = "__rea__";
+/** `tool_name` recorded in audit entries for this meta-tool. */
+export declare const META_TOOL_NAME = "health";
+export interface MetaHealthSnapshot {
+    /** rea gateway version (from package.json, pinned to the shipped version). */
+    gateway: {
+        version: string;
+        /** Seconds since gateway process started. */
+        uptime_s: number;
+        /** Whether `.rea/HALT` is present. */
+        halt: boolean;
+        /** When true, the health tool is the only callable tool right now. */
+        halt_reason: string | null;
+    };
+    policy: {
+        profile: string;
+        autonomy_level: string;
+        max_autonomy_level: string;
+        block_ai_attribution: boolean;
+        blocked_paths_count: number;
+    };
+    /** Per-downstream state. Empty array iff the registry is empty. */
+    downstreams: DownstreamHealth[];
+    /** Rolled-up counts the LLM can act on without walking the array. */
+    summary: {
+        registered: number;
+        connected: number;
+        healthy: number;
+        total_tools: number;
+    };
+}
+export interface BuildHealthSnapshotDeps {
+    /** Gateway version (so we can test deterministically without reading package.json). */
+    gatewayVersion: string;
+    /** Gateway boot time in epoch ms. `uptime_s` is computed from this. */
+    startedAtMs: number;
+    /** Frozen policy snapshot — we do not re-read `.rea/policy.yaml` here. */
+    policy: Policy;
+    /** Per-downstream state from the pool. */
+    downstreams: DownstreamHealth[];
+    /** Whether `.rea/HALT` is present at snapshot time. */
+    halt: boolean;
+    /**
+     * HALT reason, if any. `null` when HALT is absent OR when the file exists
+     * but the caller couldn't read its contents — we never surface an I/O
+     * exception through this tool.
+     */
+    haltReason: string | null;
+    /** Current epoch ms. Injected for determinism in tests. */
+    nowMs?: number;
+}
+/**
+ * Pure function that builds the snapshot from injected state. All I/O happens
+ * in the caller (`server.ts`) — keeps this testable and keeps "health never
+ * throws" a local invariant rather than a chain-wide claim.
+ */
+export declare function buildHealthSnapshot(deps: BuildHealthSnapshotDeps): MetaHealthSnapshot;
+/**
+ * The descriptor the gateway advertises via `tools/list`. No arguments —
+ * callers request a snapshot by calling with `{}`. Keeping the surface
+ * argument-free makes the tool trivially safe for any autonomy level.
+ */
+export declare function metaHealthToolDescriptor(): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};

package/dist/gateway/meta/health.js

@@ -0,0 +1,108 @@
+/**
+ * Gateway-internal `__rea__health` meta-tool.
+ *
+ * WHY THIS EXISTS
+ * ===============
+ *
+ * The MCP `listTools` catalog the gateway advertises is the UNION of every
+ * healthy downstream's own catalog. When all downstreams are unhealthy — or
+ * the registry is empty, or fingerprints fail, or an env var is missing — the
+ * catalog is empty. From the LLM's perspective this is indistinguishable from
+ * a gateway that came up fine but happens to have nothing to proxy, and there
+ * is no tool it can call to ask "why is this empty?" because, well, the
+ * catalog is empty.
+ *
+ * This meta-tool closes that diagnostic gap: the gateway ALWAYS exposes
+ * `__rea__health` regardless of downstream state, the kill-switch, or the
+ * middleware chain. A caller can invoke it to get a snapshot of every
+ * registered server's connection state, last error, and tool count.
+ *
+ * DESIGN CHOICES
+ * --------------
+ *
+ * 1. Name shape: `__rea__health`. The leading `__` (instead of a normal
+ *    `<server>__<tool>` prefix) reserves the namespace for gateway-internal
+ *    tools. It never collides with a registered server because
+ *    `src/registry/loader.ts` restricts `name` to `^[a-z0-9][a-z0-9-]*$` —
+ *    no underscores allowed.
+ *
+ * 2. Short-circuit in `server.ts`: the CallTool handler matches on the
+ *    constant below BEFORE calling `splitPrefixed`, and responds directly
+ *    without running the middleware chain. Reasons, ordered:
+ *      (a) This tool must be callable while HALT is present — otherwise the
+ *          operator can't introspect a frozen gateway.
+ *      (b) Tier middleware would classify `health` as Write (default for
+ *          unlisted names) and deny L0 callers — wrong for read-only
+ *          introspection.
+ *      (c) There is no downstream to dispatch to — the entire middleware
+ *          chain is about getting to one safely.
+ *    The short-circuit still writes an audit record via `appendAuditRecord`
+ *    so invocations remain accountable.
+ *
+ * 3. Never throws. Health is the one tool the caller uses when things are
+ *    broken. Every field is best-effort; a missing value is surfaced as
+ *    `null`, not as an exception.
+ */
+/** Canonical MCP tool name exposed by the gateway. */
+export const META_HEALTH_TOOL_NAME = '__rea__health';
+/** `server_name` recorded in audit entries for this meta-tool. */
+export const META_SERVER_NAME = '__rea__';
+/** `tool_name` recorded in audit entries for this meta-tool. */
+export const META_TOOL_NAME = 'health';
+/**
+ * Pure function that builds the snapshot from injected state. All I/O happens
+ * in the caller (`server.ts`) — keeps this testable and keeps "health never
+ * throws" a local invariant rather than a chain-wide claim.
+ */
+export function buildHealthSnapshot(deps) {
+    const now = deps.nowMs ?? Date.now();
+    const uptime_s = Math.max(0, Math.floor((now - deps.startedAtMs) / 1000));
+    let connected = 0;
+    let healthy = 0;
+    let total_tools = 0;
+    for (const d of deps.downstreams) {
+        if (d.connected)
+            connected += 1;
+        if (d.healthy)
+            healthy += 1;
+        if (typeof d.tools_count === 'number')
+            total_tools += d.tools_count;
+    }
+    return {
+        gateway: {
+            version: deps.gatewayVersion,
+            uptime_s,
+            halt: deps.halt,
+            halt_reason: deps.haltReason,
+        },
+        policy: {
+            profile: deps.policy.profile,
+            autonomy_level: String(deps.policy.autonomy_level),
+            max_autonomy_level: String(deps.policy.max_autonomy_level),
+            block_ai_attribution: deps.policy.block_ai_attribution,
+            blocked_paths_count: deps.policy.blocked_paths.length,
+        },
+        downstreams: deps.downstreams,
+        summary: {
+            registered: deps.downstreams.length,
+            connected,
+            healthy,
+            total_tools,
+        },
+    };
+}
+/**
+ * The descriptor the gateway advertises via `tools/list`. No arguments —
+ * callers request a snapshot by calling with `{}`. Keeping the surface
+ * argument-free makes the tool trivially safe for any autonomy level.
+ */
+export function metaHealthToolDescriptor() {
+    return {
+        name: META_HEALTH_TOOL_NAME,
+        description: 'rea gateway self-diagnostic. Returns the gateway version, HALT state, policy summary, ' +
+            'and per-downstream connection/health/tool-count. Always available, even when every ' +
+            'downstream is unhealthy or HALT is active — this is the tool you call when listTools ' +
+            'comes back empty or suspicious.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    };
+}

package/dist/gateway/server.js

@@ -32,7 +32,12 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { DownstreamPool, splitPrefixed } from './downstream-pool.js';
+import { META_HEALTH_TOOL_NAME, META_SERVER_NAME, META_TOOL_NAME, buildHealthSnapshot, metaHealthToolDescriptor, } from './meta/health.js';
+import { appendAuditRecord } from '../audit/append.js';
+import { getPkgVersion } from '../cli/utils.js';
 import { createAuditMiddleware } from './middleware/audit.js';
 import { createKillSwitchMiddleware } from './middleware/kill-switch.js';
 import { createTierMiddleware } from './middleware/tier.js';
@@ -116,11 +121,13 @@ function buildMiddlewareChain(opts, deps) {
     ];
 }
 export function createGateway(opts) {
-    const { registry } = opts;
+    const { registry, policy, baseDir } = opts;
     const logger = opts.logger ?? createLogger({ base: { session_id: currentSessionId() } });
     const metrics = opts.metrics;
     const pool = new DownstreamPool(registry, logger);
-    const server = new Server({ name: 'rea', version: '0.2.0' }, { capabilities: { tools: {} } });
+    const gatewayVersion = getPkgVersion();
+    const startedAtMs = Date.now();
+    const server = new Server({ name: 'rea', version: gatewayVersion }, { capabilities: { tools: {} } });
     // Build the circuit breaker with observability hooks wired in — state
     // transitions log a structured record AND update the Prometheus gauge.
     const breaker = new CircuitBreaker({
@@ -146,22 +153,116 @@ export function createGateway(opts) {
         },
     });
     const staticChain = buildMiddlewareChain(opts, { breaker });
+    // Read `.rea/HALT` without ever throwing. Returns `{halt, reason}` where
+    // `reason` is the (trimmed) file contents or null when the file is absent
+    // / unreadable. The meta-tool never surfaces I/O errors — health is the one
+    // thing that has to keep working when everything else is broken.
+    async function readHalt() {
+        try {
+            const contents = await fs.readFile(path.join(baseDir, '.rea', 'HALT'), 'utf8');
+            const trimmed = contents.trim();
+            return { halt: true, reason: trimmed.length > 0 ? trimmed : null };
+        }
+        catch {
+            return { halt: false, reason: null };
+        }
+    }
     // ── Handlers ─────────────────────────────────────────────────────────────
     server.setRequestHandler(ListToolsRequestSchema, async () => {
+        // The `__rea__health` meta-tool is ALWAYS advertised, regardless of
+        // downstream state. This is the systemic answer to the "listTools came
+        // back empty, now what?" diagnostic gap — the LLM can always call
+        // health to find out why.
+        const metaTool = metaHealthToolDescriptor();
         if (pool.size === 0)
-            return { tools: [] };
+            return { tools: [metaTool] };
         const prefixed = await pool.listAllTools();
         return {
-            tools: prefixed.map((t) => ({
-                name: t.name,
-                description: t.description ?? `${t.server} → ${t.name.slice(t.server.length + 2)}`,
-                inputSchema: t.inputSchema ?? { type: 'object' },
-            })),
+            tools: [
+                metaTool,
+                ...prefixed.map((t) => ({
+                    name: t.name,
+                    description: t.description ?? `${t.server} → ${t.name.slice(t.server.length + 2)}`,
+                    inputSchema: t.inputSchema ?? { type: 'object' },
+                })),
+            ],
         };
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const prefixed = req.params.name;
         const args = (req.params.arguments ?? {});
+        // Short-circuit the `__rea__health` meta-tool BEFORE the middleware chain
+        // and BEFORE splitPrefixed. Reasons:
+        //   - Must be callable while HALT is active (so the operator can
+        //     introspect a frozen gateway). The kill-switch middleware would
+        //     otherwise deny.
+        //   - `deriveBaseTier('health')` defaults to Write, which would deny L0
+        //     callers. Health is pure introspection — tier doesn't apply.
+        //   - There's no downstream to dispatch to. The middleware chain exists
+        //     to reach one safely.
+        // We still write an audit record so invocations remain accountable.
+        // The `__rea__` prefix is reserved for gateway-internal meta-tools.
+        // Reject any unknown name in that namespace with a clear error rather
+        // than letting `splitPrefixed` produce the confusing `unknown downstream
+        // server ""` message for e.g. `__rea__health ` (trailing space) or a
+        // future meta-tool name the client was guessing at.
+        if (prefixed.startsWith('__rea__') && prefixed !== META_HEALTH_TOOL_NAME) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `reserved meta-namespace: only "${META_HEALTH_TOOL_NAME}" is defined under __rea__`,
+                    },
+                ],
+            };
+        }
+        if (prefixed === META_HEALTH_TOOL_NAME) {
+            const startMs = Date.now();
+            const haltState = await readHalt();
+            const snapshot = buildHealthSnapshot({
+                gatewayVersion,
+                startedAtMs,
+                policy,
+                downstreams: pool.healthSnapshot(),
+                halt: haltState.halt,
+                haltReason: haltState.reason,
+            });
+            // Best-effort audit append. Failures here must never prevent the
+            // caller from getting the health response — that would defeat the
+            // whole point of a "works when everything else is broken" tool.
+            try {
+                await appendAuditRecord(baseDir, {
+                    tool_name: META_TOOL_NAME,
+                    server_name: META_SERVER_NAME,
+                    status: InvocationStatus.Allowed,
+                    tier: Tier.Read,
+                    autonomy_level: String(policy.autonomy_level),
+                    session_id: currentSessionId(),
+                    duration_ms: Date.now() - startMs,
+                    metadata: {
+                        halt: snapshot.gateway.halt,
+                        downstreams_registered: snapshot.summary.registered,
+                        downstreams_healthy: snapshot.summary.healthy,
+                    },
+                });
+            }
+            catch (err) {
+                logger.warn({
+                    event: 'meta.health.audit_failed',
+                    message: 'failed to append audit record for __rea__health; serving response anyway',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(snapshot, null, 2),
+                    },
+                ],
+            };
+        }
         // Split prefix for downstream dispatch; the terminal middleware uses the
         // full prefixed name to call the pool (which re-splits internally).
         let serverName;
@@ -336,7 +437,3 @@ export function createGateway(opts) {
     }
     return { server, start, stop, pool, logger, metrics };
 }
-// Prevent TS from complaining about the unused `Tier` import when the file is
-// compiled in isolation; keeping the import pins the semantic dependency edge
-// for future middleware that may want to inspect the tier in terminal.
-void Tier;

package/dist/policy/loader.d.ts

@@ -32,10 +32,16 @@ declare const PolicySchema: z.ZodObject<{
     }>>;
     review: z.ZodOptional<z.ZodObject<{
         codex_required: z.ZodOptional<z.ZodBoolean>;
+        cache_max_age_seconds: z.ZodOptional<z.ZodNumber>;
+        allow_skip_in_ci: z.ZodOptional<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
+        cache_max_age_seconds?: number | undefined;
+        allow_skip_in_ci?: boolean | undefined;
     }, {
         codex_required?: boolean | undefined;
+        cache_max_age_seconds?: number | undefined;
+        allow_skip_in_ci?: boolean | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -110,6 +116,8 @@ declare const PolicySchema: z.ZodObject<{
     } | undefined;
     review?: {
         codex_required?: boolean | undefined;
+        cache_max_age_seconds?: number | undefined;
+        allow_skip_in_ci?: boolean | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -146,6 +154,8 @@ declare const PolicySchema: z.ZodObject<{
     } | undefined;
     review?: {
         codex_required?: boolean | undefined;
+        cache_max_age_seconds?: number | undefined;
+        allow_skip_in_ci?: boolean | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;

package/dist/policy/loader.js

@@ -24,6 +24,8 @@ const ContextProtectionSchema = z.object({
 const ReviewPolicySchema = z
     .object({
     codex_required: z.boolean().optional(),
+    cache_max_age_seconds: z.number().int().positive().optional(),
+    allow_skip_in_ci: z.boolean().optional(),
 })
     .strict();
 /**

package/dist/policy/types.d.ts

@@ -31,6 +31,26 @@ export interface ReviewPolicy {
      * log. Default when unset is `true` (Codex required).
      */
     codex_required?: boolean;
+    /**
+     * Review-cache TTL used by `rea cache check` (BUG-009). Entries older
+     * than this window are treated as a miss, forcing re-review. Default
+     * when unset is 3600 seconds (1 hour) — matches the windows the
+     * push-review-gate hook already assumes. Express in seconds, positive
+     * integer.
+     */
+    cache_max_age_seconds?: number;
+    /**
+     * Authorization for `REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW` when
+     * the `CI` environment variable is set. The skip hatches are ambient and
+     * unauthenticated — a leaked env file or a malicious parent process can
+     * bypass the gate and record a forged actor (git config is mutable repo
+     * config). Refusing these hatches in CI contexts by default removes that
+     * bypass surface. Set `true` ONLY on build agents where the operator has
+     * an independent reason to trust the environment. Default `false`.
+     *
+     * Added in 0.5.0 as Codex F2 on the PR1 adversarial review.
+     */
+    allow_skip_in_ci?: boolean;
 }
 /**
  * User-supplied redaction pattern entry. Each pattern has a stable `name` used