@bookedsolid/rea 0.1.0 → 0.2.1

package/dist/cli/install/reagent.js

@@ -0,0 +1,160 @@
+/**
+ * Translate a `.reagent/policy.yaml` into a `.rea/policy.yaml`-shaped payload.
+ *
+ * ## Explicit contract
+ *
+ * Reagent had a broader policy schema than rea. Most top-level fields either
+ * transfer directly (same semantics) or are dropped because their governance
+ * model changed. Dropping a security-relevant field silently would downgrade a
+ * guarantee the user already expected — that is forbidden.
+ *
+ * Fields fall into one of three lists:
+ *
+ *   - **copy list**: copy verbatim into the rea policy.
+ *   - **drop list**: SECURITY-RELEVANT fields that were removed or restructured
+ *     in rea. If any drop-list field is present in the input policy, this
+ *     function refuses to translate unless `acceptDropped === true`.
+ *   - **ignore list**: non-governance fields (metadata, project name, notes)
+ *     that are simply not written to the rea policy. No warning emitted.
+ *
+ * ## Autonomy clamping
+ *
+ * If the reagent policy's `max_autonomy_level` exceeds the chosen profile's
+ * ceiling, we clamp down to the profile ceiling and record a notice. A reagent
+ * install that allowed L3 cannot silently survive a migration into an
+ * `open-source` profile capped at L2.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { AutonomyLevel } from '../../policy/types.js';
+import { ProfileSchema } from '../../policy/profiles.js';
+const LEVEL_RANK = {
+    [AutonomyLevel.L0]: 0,
+    [AutonomyLevel.L1]: 1,
+    [AutonomyLevel.L2]: 2,
+    [AutonomyLevel.L3]: 3,
+};
+/** Fields transferred directly from reagent. Both schemas agree on semantics. */
+const COPY_FIELDS = [
+    'autonomy_level',
+    'max_autonomy_level',
+    'promotion_requires_human_approval',
+    'blocked_paths',
+    'context_protection',
+    'block_ai_attribution',
+];
+/**
+ * SECURITY-RELEVANT fields that reagent supported but rea does not model the
+ * same way (yet). Presence of any of these triggers a refusal unless the
+ * caller explicitly opts in via `--accept-dropped-fields`. This list is
+ * intentionally broader than the strict minimum — err on the side of asking.
+ */
+const DROP_FIELDS = [
+    'push_review',
+    'coverage',
+    'security',
+    'commit_review',
+    'quality_gates',
+];
+export class ReagentDroppedFieldsError extends Error {
+    dropped;
+    constructor(dropped) {
+        super(`Reagent policy contains fields that rea does not model identically:\n` +
+            dropped.map((f) => `  - ${f}`).join('\n') +
+            `\n\nPass --accept-dropped-fields to continue. The dropped fields are\n` +
+            `security-adjacent and will be silently removed — review the rea policy\n` +
+            `after migration and restore equivalent guarantees by other means.`);
+        this.name = 'ReagentDroppedFieldsError';
+        this.dropped = dropped;
+    }
+}
+function readReagentPolicy(reagentPath) {
+    const raw = fs.readFileSync(reagentPath, 'utf8');
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse reagent policy at ${reagentPath}: ${err instanceof Error ? err.message : err}`);
+    }
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Reagent policy at ${reagentPath} is not a YAML mapping`);
+    }
+    return parsed;
+}
+function detectDropped(policy) {
+    const found = [];
+    for (const f of DROP_FIELDS) {
+        if (f in policy)
+            found.push(f);
+    }
+    return found;
+}
+function extractCopyFields(policy) {
+    const out = {};
+    for (const f of COPY_FIELDS) {
+        if (f in policy)
+            out[f] = policy[f];
+    }
+    return out;
+}
+/**
+ * Translate the reagent policy at `reagentPath`, enforcing drop-list rules.
+ *
+ * @throws {ReagentDroppedFieldsError} if drop-list fields are present and
+ *   `acceptDropped` is false.
+ */
+export function translateReagentPolicy(reagentPath, options) {
+    if (!fs.existsSync(reagentPath)) {
+        throw new Error(`Reagent policy not found at ${reagentPath}`);
+    }
+    const raw = readReagentPolicy(reagentPath);
+    const dropped = detectDropped(raw);
+    if (dropped.length > 0 && !options.acceptDropped) {
+        throw new ReagentDroppedFieldsError(dropped);
+    }
+    const notices = [];
+    if (dropped.length > 0) {
+        for (const f of dropped) {
+            notices.push(`dropped reagent field "${f}" — governance surface no longer modeled in rea policy`);
+        }
+    }
+    const copied = extractCopyFields(raw);
+    // Validate the copied subset against the profile schema. This catches shape
+    // drift (e.g. a reagent file with a malformed context_protection block).
+    let validated;
+    try {
+        validated = ProfileSchema.parse(copied);
+    }
+    catch (err) {
+        throw new Error(`Reagent-translated fields failed schema validation: ${err instanceof Error ? err.message : err}`);
+    }
+    let clamped = false;
+    if (validated.max_autonomy_level !== undefined) {
+        const reagentCeilingRank = LEVEL_RANK[validated.max_autonomy_level];
+        const profileCeilingRank = LEVEL_RANK[options.profileCeiling];
+        if (reagentCeilingRank > profileCeilingRank) {
+            notices.push(`clamping max_autonomy_level ${validated.max_autonomy_level} → ${options.profileCeiling} (profile ceiling)`);
+            validated.max_autonomy_level = options.profileCeiling;
+            clamped = true;
+        }
+        // Also clamp autonomy_level if it now exceeds the ceiling.
+        if (validated.autonomy_level !== undefined &&
+            LEVEL_RANK[validated.autonomy_level] > LEVEL_RANK[validated.max_autonomy_level]) {
+            notices.push(`clamping autonomy_level ${validated.autonomy_level} → ${validated.max_autonomy_level} after ceiling clamp`);
+            validated.autonomy_level = validated.max_autonomy_level;
+            clamped = true;
+        }
+    }
+    return { translated: validated, notices, droppedFields: dropped, clampedAutonomy: clamped };
+}
+/**
+ * Resolve the default reagent policy path inside a target directory.
+ * Convenience for the CLI's `--from-reagent` flag.
+ */
+export function defaultReagentPath(targetDir) {
+    return path.join(targetDir, '.reagent', 'policy.yaml');
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Merge rea's required hook registrations into a consumer's
+ * `.claude/settings.json` without ever silently overwriting consumer-authored
+ * entries.
+ *
+ * Rules per hook-group `(event, matcher, command)`:
+ *
+ *   1. `${matcher}::${command}` already present on the same event  → no-op.
+ *   2. Same matcher, different command  → append and warn (the consumer may
+ *      need to chain the hooks manually if order matters).
+ *   3. Novel matcher  → append as a new matcher group.
+ *
+ * Writes are atomic: serialize to `settings.json.tmp`, then rename. This keeps
+ * the file intact under crash or signal-interrupt.
+ *
+ * We deliberately do NOT validate the shape of existing entries beyond the
+ * minimum needed to merge. The harness is the source of truth for the schema;
+ * if a consumer has hand-authored unusual entries, we trust them and merge
+ * around their structure.
+ */
+export type HookEvent = 'PreToolUse' | 'PostToolUse' | 'Notification' | 'Stop';
+export interface DesiredHook {
+    type: 'command';
+    command: string;
+    timeout?: number;
+    statusMessage?: string;
+}
+export interface DesiredHookGroup {
+    event: HookEvent;
+    matcher: string;
+    hooks: DesiredHook[];
+}
+export interface MergeResult {
+    merged: Record<string, unknown>;
+    warnings: string[];
+    addedCount: number;
+    skippedCount: number;
+}
+/**
+ * Pure merge function — takes the existing settings object and the desired
+ * hooks and returns the merged settings plus a list of warnings. Does NOT
+ * touch disk.
+ */
+export declare function mergeSettings(existing: Record<string, unknown>, desired: DesiredHookGroup[]): MergeResult;
+/**
+ * Atomic write via tmp-file + rename.
+ *
+ * Portability note (finding #8): POSIX `rename(2)` atomically replaces the
+ * destination if it exists, but Windows `MoveFileEx` without
+ * `MOVEFILE_REPLACE_EXISTING` fails with `EEXIST`/`EPERM` on a non-empty
+ * destination — and Node's `fs.rename` does not pass that flag on Win32. So on
+ * Windows, a straight rename over an existing `settings.json` fails and
+ * `rea init` cannot update consumer settings.
+ *
+ * We handle this inline rather than taking a dependency: try `rename`; if it
+ * fails with `EEXIST` or `EPERM`, `unlink` the destination and retry. This
+ * opens a tiny window where the file is missing between unlink and rename, but
+ * a crash in that window leaves the `.tmp` file on disk as a recoverable
+ * artifact — strictly better than a corrupted merge. We prefer no dependency
+ * over `write-file-atomic`: every dep on a governance tool is a supply-chain
+ * surface, and this shim is small enough to audit here.
+ */
+export declare function writeSettingsAtomic(settingsPath: string, settings: Record<string, unknown>): Promise<void>;
+/**
+ * Read `${targetDir}/.claude/settings.json` if present; return an empty object
+ * otherwise. The wizard/`--yes` path will then populate env defaults
+ * elsewhere; this function only concerns itself with structural parsing.
+ */
+export declare function readSettings(targetDir: string): {
+    settings: Record<string, unknown>;
+    settingsPath: string;
+    existed: boolean;
+};
+/**
+ * Stable SHA-256 of the rea-owned "desired hooks" subset. G12 uses this as
+ * the manifest entry for `.claude/settings.json` so drift detection only
+ * flags cases where a consumer deleted one of OUR entries — consumer-added
+ * entries remain invisible.
+ *
+ * Deterministic serialization: property order is fixed in-code (event,
+ * matcher, hooks → type, command, timeout, statusMessage), and the array
+ * order matches `defaultDesiredHooks()`. Any change to the desired set
+ * produces a new hash, which is the correct upgrade signal.
+ */
+export declare function canonicalSettingsSubsetHash(groups: DesiredHookGroup[]): string;
+/**
+ * Desired hook registrations that `rea init` installs on every run. Mirrors
+ * the shape of the `.claude/settings.json` that this repo dogfoods. Keep in
+ * lockstep with `hooks/` filenames.
+ */
+export declare function defaultDesiredHooks(): DesiredHookGroup[];

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

@@ -0,0 +1,239 @@
+/**
+ * Merge rea's required hook registrations into a consumer's
+ * `.claude/settings.json` without ever silently overwriting consumer-authored
+ * entries.
+ *
+ * Rules per hook-group `(event, matcher, command)`:
+ *
+ *   1. `${matcher}::${command}` already present on the same event  → no-op.
+ *   2. Same matcher, different command  → append and warn (the consumer may
+ *      need to chain the hooks manually if order matters).
+ *   3. Novel matcher  → append as a new matcher group.
+ *
+ * Writes are atomic: serialize to `settings.json.tmp`, then rename. This keeps
+ * the file intact under crash or signal-interrupt.
+ *
+ * We deliberately do NOT validate the shape of existing entries beyond the
+ * minimum needed to merge. The harness is the source of truth for the schema;
+ * if a consumer has hand-authored unusual entries, we trust them and merge
+ * around their structure.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+function deepClone(value) {
+    // structuredClone is available on Node 22+ (engines.node enforces this).
+    return structuredClone(value);
+}
+function ensureHooksShape(settings) {
+    const hooks = settings.hooks ?? {};
+    settings.hooks = hooks;
+    return hooks;
+}
+function keyFor(matcher, command) {
+    return `${matcher}::${command}`;
+}
+/**
+ * Pure merge function — takes the existing settings object and the desired
+ * hooks and returns the merged settings plus a list of warnings. Does NOT
+ * touch disk.
+ */
+export function mergeSettings(existing, desired) {
+    const merged = deepClone(existing);
+    const hooks = ensureHooksShape(merged);
+    const warnings = [];
+    let addedCount = 0;
+    let skippedCount = 0;
+    for (const want of desired) {
+        const existingGroups = hooks[want.event] ?? [];
+        // Build a set of already-registered (matcher, command) pairs across all
+        // groups for this event. Most consumer files have one group per matcher,
+        // but we handle the multi-group case defensively.
+        const seen = new Set();
+        for (const g of existingGroups) {
+            if (typeof g.matcher !== 'string')
+                continue;
+            for (const h of g.hooks ?? []) {
+                if (typeof h.command === 'string')
+                    seen.add(keyFor(g.matcher, h.command));
+            }
+        }
+        // Find or create a group with exactly this matcher. Track whether the
+        // group pre-existed so we only warn when rea chains onto consumer-authored
+        // hooks — not when multiple rea defaults share the same matcher group we
+        // just created this run.
+        const preExisting = existingGroups.find((g) => g.matcher === want.matcher);
+        let targetGroup = preExisting;
+        const wasPreExisting = preExisting !== undefined;
+        for (const wantHook of want.hooks) {
+            const k = keyFor(want.matcher, wantHook.command);
+            if (seen.has(k)) {
+                skippedCount += 1;
+                continue;
+            }
+            if (targetGroup === undefined) {
+                targetGroup = { matcher: want.matcher, hooks: [] };
+                existingGroups.push(targetGroup);
+                hooks[want.event] = existingGroups;
+                warnings.push(`added novel matcher "${want.matcher}" to event ${want.event}`);
+            }
+            else if (wasPreExisting) {
+                // Same matcher existed already in the consumer file; we're chaining
+                // new commands onto something the consumer owns. Warn so they review
+                // ordering semantics.
+                warnings.push(`chained new command onto existing matcher "${want.matcher}" for event ${want.event}: ${wantHook.command} — verify hook ordering is still correct`);
+            }
+            if (!Array.isArray(targetGroup.hooks))
+                targetGroup.hooks = [];
+            targetGroup.hooks.push({
+                type: wantHook.type,
+                command: wantHook.command,
+                ...(wantHook.timeout !== undefined ? { timeout: wantHook.timeout } : {}),
+                ...(wantHook.statusMessage !== undefined
+                    ? { statusMessage: wantHook.statusMessage }
+                    : {}),
+            });
+            seen.add(k);
+            addedCount += 1;
+        }
+    }
+    return { merged, warnings, addedCount, skippedCount };
+}
+/**
+ * Atomic write via tmp-file + rename.
+ *
+ * Portability note (finding #8): POSIX `rename(2)` atomically replaces the
+ * destination if it exists, but Windows `MoveFileEx` without
+ * `MOVEFILE_REPLACE_EXISTING` fails with `EEXIST`/`EPERM` on a non-empty
+ * destination — and Node's `fs.rename` does not pass that flag on Win32. So on
+ * Windows, a straight rename over an existing `settings.json` fails and
+ * `rea init` cannot update consumer settings.
+ *
+ * We handle this inline rather than taking a dependency: try `rename`; if it
+ * fails with `EEXIST` or `EPERM`, `unlink` the destination and retry. This
+ * opens a tiny window where the file is missing between unlink and rename, but
+ * a crash in that window leaves the `.tmp` file on disk as a recoverable
+ * artifact — strictly better than a corrupted merge. We prefer no dependency
+ * over `write-file-atomic`: every dep on a governance tool is a supply-chain
+ * surface, and this shim is small enough to audit here.
+ */
+export async function writeSettingsAtomic(settingsPath, settings) {
+    const dir = path.dirname(settingsPath);
+    await fsPromises.mkdir(dir, { recursive: true });
+    const tmp = `${settingsPath}.tmp`;
+    const serialized = JSON.stringify(settings, null, 2) + '\n';
+    await fsPromises.writeFile(tmp, serialized, 'utf8');
+    try {
+        await fsPromises.rename(tmp, settingsPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'EEXIST' && code !== 'EPERM') {
+            // Clean up the tmp file on unexpected failure so we don't leave litter.
+            await fsPromises.unlink(tmp).catch(() => {
+                /* best-effort; original error is the one that matters */
+            });
+            throw err;
+        }
+        // Windows: destination exists and rename refuses to replace it. Remove
+        // and retry. If the second rename also fails, propagate — something
+        // stranger is going on (permissions, read-only volume) that the operator
+        // needs to see.
+        await fsPromises.unlink(settingsPath);
+        try {
+            await fsPromises.rename(tmp, settingsPath);
+        }
+        catch (retryErr) {
+            await fsPromises.unlink(tmp).catch(() => {
+                /* best-effort cleanup */
+            });
+            throw retryErr;
+        }
+    }
+}
+/**
+ * Read `${targetDir}/.claude/settings.json` if present; return an empty object
+ * otherwise. The wizard/`--yes` path will then populate env defaults
+ * elsewhere; this function only concerns itself with structural parsing.
+ */
+export function readSettings(targetDir) {
+    const settingsPath = path.join(targetDir, '.claude', 'settings.json');
+    if (!fs.existsSync(settingsPath)) {
+        return { settings: {}, settingsPath, existed: false };
+    }
+    const raw = fs.readFileSync(settingsPath, 'utf8');
+    try {
+        const parsed = JSON.parse(raw);
+        return { settings: parsed, settingsPath, existed: true };
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${settingsPath}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+/**
+ * Stable SHA-256 of the rea-owned "desired hooks" subset. G12 uses this as
+ * the manifest entry for `.claude/settings.json` so drift detection only
+ * flags cases where a consumer deleted one of OUR entries — consumer-added
+ * entries remain invisible.
+ *
+ * Deterministic serialization: property order is fixed in-code (event,
+ * matcher, hooks → type, command, timeout, statusMessage), and the array
+ * order matches `defaultDesiredHooks()`. Any change to the desired set
+ * produces a new hash, which is the correct upgrade signal.
+ */
+export function canonicalSettingsSubsetHash(groups) {
+    const canonical = groups.map((g) => ({
+        event: g.event,
+        matcher: g.matcher,
+        hooks: g.hooks.map((h) => {
+            const entry = { type: h.type, command: h.command };
+            if (h.timeout !== undefined)
+                entry.timeout = h.timeout;
+            if (h.statusMessage !== undefined)
+                entry.statusMessage = h.statusMessage;
+            return entry;
+        }),
+    }));
+    return createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+}
+/**
+ * Desired hook registrations that `rea init` installs on every run. Mirrors
+ * the shape of the `.claude/settings.json` that this repo dogfoods. Keep in
+ * lockstep with `hooks/` filenames.
+ */
+export function defaultDesiredHooks() {
+    const base = '"$CLAUDE_PROJECT_DIR"/.claude/hooks';
+    return [
+        {
+            event: 'PreToolUse',
+            matcher: 'Bash',
+            hooks: [
+                { type: 'command', command: `${base}/dangerous-bash-interceptor.sh`, timeout: 10000, statusMessage: 'Checking command safety...' },
+                { type: 'command', command: `${base}/env-file-protection.sh`, timeout: 5000, statusMessage: 'Checking for .env file reads...' },
+                { type: 'command', command: `${base}/dependency-audit-gate.sh`, timeout: 15000, statusMessage: 'Verifying package exists...' },
+                { 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...' },
+            ],
+        },
+        {
+            event: 'PreToolUse',
+            matcher: 'Write|Edit',
+            hooks: [
+                { type: 'command', command: `${base}/secret-scanner.sh`, timeout: 15000, statusMessage: 'Scanning for credentials...' },
+                { type: 'command', command: `${base}/settings-protection.sh`, timeout: 5000, statusMessage: 'Checking settings protection...' },
+                { type: 'command', command: `${base}/blocked-paths-enforcer.sh`, timeout: 5000, statusMessage: 'Checking blocked paths...' },
+                { type: 'command', command: `${base}/changeset-security-gate.sh`, timeout: 5000, statusMessage: 'Checking changeset for security leaks...' },
+            ],
+        },
+        {
+            event: 'PostToolUse',
+            matcher: 'Write|Edit',
+            hooks: [
+                { type: 'command', command: `${base}/architecture-review-gate.sh`, timeout: 10000, statusMessage: 'Checking architecture impact...' },
+            ],
+        },
+    ];
+}

package/dist/cli/install/sha.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SHA-256 helpers for the install manifest (G12). Lowercase hex, 64 chars.
+ *
+ * Reads source files via streaming so large files don't balloon memory —
+ * even though our canonical files are all small, the same helper is used
+ * for consumer-side drift detection and we don't want a surprise.
+ */
+export declare function sha256OfBuffer(buf: Buffer | string): string;
+export declare function sha256OfFile(filePath: string): Promise<string>;

package/dist/cli/install/sha.js

@@ -0,0 +1,21 @@
+/**
+ * SHA-256 helpers for the install manifest (G12). Lowercase hex, 64 chars.
+ *
+ * Reads source files via streaming so large files don't balloon memory —
+ * even though our canonical files are all small, the same helper is used
+ * for consumer-side drift detection and we don't want a surprise.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+export function sha256OfBuffer(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+export function sha256OfFile(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+        stream.on('error', reject);
+    });
+}

package/dist/cli/serve.d.ts

@@ -1 +1,12 @@
+/**
+ * `rea serve` — start the MCP gateway.
+ *
+ * Loads `.rea/policy.yaml` and `.rea/registry.yaml`, builds the middleware
+ * chain, spawns downstream children from the registry, and connects an upstream
+ * stdio MCP server that clients (Claude Code, Helix, etc.) can talk to.
+ *
+ * Signals: SIGTERM and SIGINT both trigger a graceful shutdown. We do NOT exit
+ * on uncaughtException — that path is owned by `src/cli/index.ts`. If the
+ * gateway itself throws during startup we log and exit 1.
+ */
 export declare function runServe(): Promise<void>;

package/dist/cli/serve.js

@@ -1,19 +1,85 @@
 import { loadPolicy } from '../policy/loader.js';
-import { POLICY_FILE, err, exitWithMissingPolicy, log, reaPath } from './utils.js';
+import { loadRegistry } from '../registry/loader.js';
+import { createGateway } from '../gateway/server.js';
+import { CodexProbe } from '../gateway/observability/codex-probe.js';
+import { POLICY_FILE, REGISTRY_FILE, err, exitWithMissingPolicy, log, reaPath, warn, } from './utils.js';
+/**
+ * `rea serve` — start the MCP gateway.
+ *
+ * Loads `.rea/policy.yaml` and `.rea/registry.yaml`, builds the middleware
+ * chain, spawns downstream children from the registry, and connects an upstream
+ * stdio MCP server that clients (Claude Code, Helix, etc.) can talk to.
+ *
+ * Signals: SIGTERM and SIGINT both trigger a graceful shutdown. We do NOT exit
+ * on uncaughtException — that path is owned by `src/cli/index.ts`. If the
+ * gateway itself throws during startup we log and exit 1.
+ */
 export async function runServe() {
     const baseDir = process.cwd();
     const policyPath = reaPath(baseDir, POLICY_FILE);
+    const registryPath = reaPath(baseDir, REGISTRY_FILE);
+    let policy;
     try {
-        const policy = loadPolicy(baseDir);
-        log(`MCP gateway not yet implemented — install complete, policy loaded (profile=${policy.profile}, autonomy=${policy.autonomy_level}).`);
-        process.exit(0);
+        policy = loadPolicy(baseDir);
     }
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
-        if (message.includes('not found')) {
+        if (message.includes('not found'))
             exitWithMissingPolicy(policyPath);
-        }
         err(`Failed to load policy: ${message}`);
         process.exit(1);
     }
+    let registry;
+    try {
+        registry = loadRegistry(baseDir);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (message.includes('not found')) {
+            err(`Registry file not found: ${registryPath}`);
+            console.error('');
+            console.error('  Run `rea init` to create an empty registry, then edit it to declare downstream servers.');
+            console.error('');
+            process.exit(1);
+        }
+        err(`Failed to load registry: ${message}`);
+        process.exit(1);
+    }
+    const handle = createGateway({ baseDir, policy, registry });
+    // G11.3 — Codex availability probe. Observational only: a failed probe
+    // NEVER fail-closes the gateway at startup. When the policy explicitly
+    // opts out of Codex (`review.codex_required: false`), skip the probe
+    // entirely — there are no Codex calls to observe, so the probe would be
+    // noise on stderr.
+    const codexRequired = policy.review?.codex_required !== false;
+    let codexProbe;
+    if (codexRequired) {
+        codexProbe = new CodexProbe();
+        const initialState = await codexProbe.probe();
+        if (!initialState.cli_responsive) {
+            warn(`Codex probe failed — push-gate will use fallback reviewer path if triggered (${initialState.last_error ?? 'no error detail'})`);
+        }
+        codexProbe.start();
+    }
+    const shutdown = async (signal) => {
+        log(`rea serve: received ${signal} — draining and shutting down`);
+        codexProbe?.stop();
+        try {
+            await handle.stop();
+        }
+        catch (e) {
+            err(`shutdown error: ${e instanceof Error ? e.message : e}`);
+        }
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    log(`rea serve: policy profile=${policy.profile}, autonomy=${policy.autonomy_level}, downstream servers=${registry.servers.filter((s) => s.enabled).length}`);
+    try {
+        await handle.start();
+    }
+    catch (e) {
+        err(`gateway start failed: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
 }