devflow-kit 1.8.2 → 2.0.0

package/dist/cli/commands/proxy.js

@@ -0,0 +1,1435 @@
+/**
+ * devflow proxy — Enable, disable, and check status of external model routing
+ * (GPT models via your OpenAI/Codex subscription).
+ *
+ * applies ADR-013: CLI-layer module; all core logic lives in src/core/proxy-state.ts
+ *   and src/core/agent-models.ts.
+ * avoids PF-014: never process.exit() inside a finally-guarded scope; use return
+ *   from the async action handler for all early-exit paths.
+ * avoids PF-001: hook output strings use fixed templates; port number interpolation
+ *   is acceptable (digit-validated integer, not user-controlled content).
+ *
+ * Branding note: "subswitch" must NEVER appear in user-visible strings. Internal
+ * identifiers (SUBSWITCH_CONFIG env var, health body checks) are fine.
+ */
+import { Command } from 'commander';
+import { promises as fs, readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import * as path from 'path';
+import * as net from 'net';
+import * as http from 'http';
+import * as https from 'https';
+import { spawn as cpSpawn } from 'child_process';
+import * as p from '@clack/prompts';
+import color from 'picocolors';
+import { readProxyState, writeProxyState, buildProxyState, buildRoutingConfigJson, proxyBaseUrl, resolveProxyBin, DEFAULT_PROXY_PORT, } from '../../core/proxy-state.js';
+import { syncManifestFeature, readManifest } from '../../core/manifest.js';
+import { writeFileAtomicExclusive } from '../../core/fs-atomic.js';
+import { scrubChildEnv, openProxyLog, rotateProxyLogIfLarge } from '../../core/proxy-log.js';
+import { inspectCodexAuth, classifyCodexAuthReadError } from '../../core/codex-auth-inspect.js';
+import { stripAnsi } from '../../hud/colors.js';
+import { reapplyAgentMapping, revertExternalAgents, countExternalMappedAgents, readAgentMapping, } from '../../core/agent-models.js';
+import { getExternalModelsCached, discoverExternalModels, } from '../../core/model-discovery.js';
+import { modelCacheDir } from '../../core/cache.js';
+import { getClaudeDirectory, getDevFlowDirectory, getHomeDirectory, } from '../../targets/claude-code/claude-paths.js';
+function Ok(value) {
+    return { ok: true, value };
+}
+function Err(error) {
+    return { ok: false, error };
+}
+// ─── Constants ────────────────────────────────────────────────────────────────
+/** Marker used to identify ensure-proxy hook entries. */
+const PROXY_HOOK_MARKER = 'ensure-proxy';
+/** Pattern matching our relay's ANTHROPIC_BASE_URL value. */
+const OUR_BASE_URL_PATTERN = /^http:\/\/127\.0\.0\.1:\d+$/;
+/** Timeout for individual TCP connect probes and HTTP health checks (ms). */
+const PROBE_TIMEOUT_MS = 2000;
+/**
+ * Maximum length of the authMode field rendered by formatCodexAuthLine.
+ *
+ * Known values are 'chatgpt', 'apikey', 'unknown' (≤7 chars). A generous cap
+ * of 32 accommodates any future mode strings while bounding hostile input from
+ * the third-party ~/.codex/auth.json file. Matches the screenshot/bug-report
+ * hygiene rationale applied to accountSuffix (6-char cap).
+ */
+const AUTH_MODE_MAX_LEN = 32;
+/**
+ * Maximum response body accepted by realHttpGet before aborting (64 KB).
+ * Prevents unbounded memory growth on slow-trickle or misconfigured endpoints
+ * (e.g. an SSE stream on the same port that --disable probes).
+ */
+const BODY_CAP_BYTES = 64 * 1024;
+/** Timeout for the relay doctor subprocess (ms). */
+const DOCTOR_TIMEOUT_MS = 10_000;
+/**
+ * Maximum number of relay port probes during the CLI spawn wait (5s at 100ms each).
+ *
+ * The ensure-proxy hook uses a larger budget (80×0.1s = 8s) — this difference is
+ * intentional:
+ *   - CLI (--enable): the user is waiting at an interactive terminal. 5s is the
+ *     maximum comfortable wait; a cold relay start typically completes in <2s.
+ *   - Hook (ensure-proxy): the hook fires inside a 15-second platform timeout. The
+ *     relay may be starting from a cold OS state (first session after reboot) where
+ *     5s is too short. 8s gives a wider revival window while leaving 7s of headroom
+ *     before the platform kills the hook.
+ */
+const RELAY_SPAWN_MAX_PROBES = 50;
+/** Interval between relay port probes during the CLI spawn wait (ms). */
+const RELAY_SPAWN_PROBE_INTERVAL_MS = 100;
+/** TCP connect timeout for each relay port probe during the CLI spawn wait (ms). */
+const RELAY_SPAWN_PER_PROBE_TIMEOUT_MS = 500;
+// ─── Version helper ───────────────────────────────────────────────────────────
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+let _cachedVersion;
+function getDevflowVersion() {
+    if (_cachedVersion !== undefined)
+        return _cachedVersion;
+    try {
+        // dist/cli/commands/ → ../../.. → repo root
+        const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', '..', '..', 'package.json'), 'utf-8'));
+        _cachedVersion = typeof pkg.version === 'string' ? pkg.version : null;
+    }
+    catch {
+        _cachedVersion = null;
+    }
+    return _cachedVersion;
+}
+// ─── Internal object helpers (used for single-pass atomic settings write) ────
+/**
+ * Mutate a parsed Settings object in place: set ANTHROPIC_BASE_URL to our relay.
+ * Returns true when the object was changed (used to detect if a write is needed).
+ */
+function _applyProxyEnvToObject(settings, port) {
+    const s = settings;
+    s.env = s.env ?? {};
+    const env = s.env;
+    const newUrl = proxyBaseUrl(port);
+    if (env.ANTHROPIC_BASE_URL === newUrl)
+        return false;
+    env.ANTHROPIC_BASE_URL = newUrl;
+    return true;
+}
+/**
+ * Mutate a parsed Settings object in place: remove ANTHROPIC_BASE_URL only when
+ * its value exactly matches our relay on the given managed port.
+ *
+ * Scoped to `managedPort` so a user's own localhost gateway (LiteLLM,
+ * local Ollama proxy, etc.) on ANY other port is never clobbered.
+ * The caller is responsible for passing the port Devflow currently owns:
+ *   - disable path  → proxy.json.port (or DEFAULT_PROXY_PORT)
+ *   - init path     → proxy.json.port after the preflight block
+ *   - enable path   → the new port being applied (followed immediately by _applyProxyEnvToObject)
+ *   - uninstall     → proxy.json.port (or DEFAULT_PROXY_PORT)
+ *
+ * Returns true when the object was changed.
+ */
+function _stripProxyEnvFromObject(settings, managedPort) {
+    const s = settings;
+    const env = s.env;
+    if (typeof env?.ANTHROPIC_BASE_URL !== 'string')
+        return false;
+    if (env.ANTHROPIC_BASE_URL !== proxyBaseUrl(managedPort))
+        return false;
+    delete env.ANTHROPIC_BASE_URL;
+    if (Object.keys(env).length === 0)
+        delete s.env;
+    return true;
+}
+/** Internal: add ensure-proxy hook to one event. Returns true when added. */
+function _ensureProxyHook(settings, eventName, hookCmd) {
+    const existing = settings.hooks?.[eventName];
+    if (existing?.some((m) => m.hooks.some((h) => h.command.includes(PROXY_HOOK_MARKER)))) {
+        return false;
+    }
+    settings.hooks ??= {};
+    settings.hooks[eventName] ??= [];
+    const entry = {
+        hooks: [{ type: 'command', command: hookCmd, timeout: 15 }],
+    };
+    settings.hooks[eventName].push(entry);
+    return true;
+}
+/** Internal: remove ensure-proxy hooks from one event. Returns true when removed. */
+function _filterProxyHooks(settings, eventName) {
+    if (!settings.hooks?.[eventName])
+        return false;
+    const before = settings.hooks[eventName].length;
+    settings.hooks[eventName] = settings.hooks[eventName].filter((m) => !m.hooks.some((h) => h.command.includes(PROXY_HOOK_MARKER)));
+    if (settings.hooks[eventName].length === before)
+        return false;
+    if (settings.hooks[eventName].length === 0)
+        delete settings.hooks[eventName];
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    return true;
+}
+// ─── Pure env functions (exported for testing and cross-module reuse) ─────────
+/**
+ * Apply ANTHROPIC_BASE_URL=http://127.0.0.1:<port> to settings JSON.
+ * Returns new serialized settings string. Does not mutate input.
+ * Idempotent — calling twice with the same port produces the same result.
+ */
+export function applyProxyEnv(settingsJson, port) {
+    const settings = JSON.parse(settingsJson);
+    _applyProxyEnvToObject(settings, port);
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+/**
+ * Remove ANTHROPIC_BASE_URL from settings JSON, but ONLY when its value exactly
+ * matches our relay on `managedPort`.
+ *
+ * `managedPort` scopes the strip to the port Devflow owns — a user's own
+ * localhost gateway on any other port is never touched. Pass `proxy.json.port`
+ * (or `DEFAULT_PROXY_PORT` when the file is absent) at every call site.
+ *
+ * Returns new serialized settings string. Does not mutate input.
+ * Cleans up an emptied env object.
+ */
+export function stripProxyEnv(settingsJson, managedPort) {
+    const settings = JSON.parse(settingsJson);
+    _stripProxyEnvFromObject(settings, managedPort);
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+/**
+ * Read the proxy env state from a settings JSON string.
+ *
+ * Returns:
+ *   'ours'           — ANTHROPIC_BASE_URL = our relay on the given port
+ *   'ours-other-port'— ANTHROPIC_BASE_URL = our relay on a different port
+ *   'foreign'        — ANTHROPIC_BASE_URL set but not our relay
+ *   'absent'         — ANTHROPIC_BASE_URL not set
+ */
+export function readProxyEnvState(settingsJson, port) {
+    const settings = JSON.parse(settingsJson);
+    const s = settings;
+    const env = s.env;
+    const url = env?.ANTHROPIC_BASE_URL;
+    if (typeof url !== 'string')
+        return 'absent';
+    if (url === proxyBaseUrl(port))
+        return 'ours';
+    if (OUR_BASE_URL_PATTERN.test(url))
+        return 'ours-other-port';
+    return 'foreign';
+}
+// ─── Pure hook helpers ──────────────────────────────────────────────────────────
+/**
+ * Add ensure-proxy hooks to BOTH SessionStart and UserPromptSubmit events.
+ * Idempotent — skips events that already have the hook.
+ * Repairs partial state (one event present, other missing) by adding the missing one.
+ * Mutates settings in place. Returns true when any hook was added.
+ */
+export function addProxyHooks(settings, devflowDir) {
+    const hookCmd = path.join(devflowDir, 'scripts', 'hooks', 'run-hook') + ' ' + PROXY_HOOK_MARKER;
+    const addedSession = _ensureProxyHook(settings, 'SessionStart', hookCmd);
+    const addedPrompt = _ensureProxyHook(settings, 'UserPromptSubmit', hookCmd);
+    return addedSession || addedPrompt;
+}
+/**
+ * Remove ensure-proxy hooks from all events.
+ * Idempotent — no-op when hooks are not present.
+ * Preserves other hooks. Cleans empty arrays/objects.
+ * Mutates settings in place. Returns true when any hook was removed.
+ */
+export function removeProxyHooks(settings) {
+    const removedSession = _filterProxyHooks(settings, 'SessionStart');
+    const removedPrompt = _filterProxyHooks(settings, 'UserPromptSubmit');
+    return removedSession || removedPrompt;
+}
+/**
+ * Apply the disable settings-pass: remove proxy hooks AND strip ANTHROPIC_BASE_URL.
+ *
+ * Both operations always run unconditionally — never short-circuited with ||.
+ * A full enabled state (hooks present AND ANTHROPIC_BASE_URL set) requires
+ * both calls to be evaluated; short-circuiting left ANTHROPIC_BASE_URL in
+ * settings when hooks were present, keeping new sessions pointed at a disabled
+ * relay.
+ *
+ * `managedPort` scopes the URL strip to the port Devflow owns — pass
+ * `proxy.json.port` (or `DEFAULT_PROXY_PORT`) at the call site.
+ *
+ * Mutates settings in place. Returns true when any change was made.
+ */
+export function applyDisableToSettings(settings, managedPort) {
+    const removedHooks = removeProxyHooks(settings);
+    const strippedEnv = _stripProxyEnvFromObject(settings, managedPort);
+    return removedHooks || strippedEnv;
+}
+/**
+ * Check whether the ensure-proxy hook is registered on at least one event.
+ * Returns true if present on either SessionStart or UserPromptSubmit.
+ * Partial state (one event present, other missing) returns true —
+ * addProxyHooks will repair it on next enable.
+ */
+export function hasProxyHooks(input) {
+    const settings = typeof input === 'string' ? JSON.parse(input) : input;
+    const check = (eventName) => settings.hooks?.[eventName]?.some((m) => m.hooks.some((h) => h.command.includes(PROXY_HOOK_MARKER))) === true;
+    return check('SessionStart') || check('UserPromptSubmit');
+}
+// ─── Health-check identity helper ────────────────────────────────────────────
+/**
+ * Return true when the raw health-check response body identifies our relay.
+ *
+ * The internal check `parsed['name'] === 'subswitch'` is correct here — 'subswitch'
+ * is the internal package name (fine in code, not in user-facing output — see branding
+ * note at the top of this file). Returns false on JSON parse failure, empty body, or a
+ * mismatched name field.
+ *
+ * Note: the ensure-proxy shell hook has its own inline copy of this check — it is a
+ * different language and cannot share the TypeScript module.
+ */
+export function isOurRelayBody(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return parsed['name'] === 'subswitch';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run preflight checks before enabling the Devflow proxy.
+ *
+ * Checks (in order):
+ * ① Routing runtime bin resolvable.
+ * ② ~/.codex/auth.json exists.
+ * ③ Port probe: free → OK; accepting → health check → adopt or fail.
+ * ④ settings.json parseable; ANTHROPIC_BASE_URL not pointing elsewhere; API key warn.
+ *
+ * Doctor is deliberately excluded from preflight: the relay's doctor subcommand
+ * probes the relay port — a not-yet-started relay makes that probe fail (exit 1). A
+ * pre-spawn gate is therefore always unsatisfiable on a cold path. Doctor now runs in
+ * runPostSpawnVerification, after the relay is confirmed up. See D-EFR-2.
+ *
+ * Returns Ok(PreflightResult) on success, Err(message) on any check failure.
+ */
+export async function runProxyPreflight(port, codexAuthPath, configPath, logPath, deps) {
+    // ① Routing runtime bin
+    const binResult = await deps.resolveProxyBin();
+    if (!binResult.ok)
+        return Err(binResult.error);
+    const { binPath, npxWarning } = binResult.value;
+    // ② Codex auth
+    const codexAuthExists = await deps.fileExists(codexAuthPath);
+    if (!codexAuthExists) {
+        return Err('Sign in to the Codex CLI first (codex login)');
+    }
+    // ③ Port probe
+    const portAccepting = await deps.tcpConnectable(port, PROBE_TIMEOUT_MS);
+    if (portAccepting) {
+        // Port is up — check health identity
+        const healthResult = await deps.httpGet(`${proxyBaseUrl(port)}/__subswitch/health`, PROBE_TIMEOUT_MS);
+        if (healthResult.ok && isOurRelayBody(healthResult.value)) {
+            return Ok({ binPath, npxWarning, adopted: true });
+        }
+        // Port accepting but health timed out, failed, or not our relay
+        return Err(`port ${port} is in use by another application — pick a different port with \`devflow proxy --enable --port <n>\``);
+    }
+    // Port refused — free to proceed
+    // ④ Settings.json check
+    let settingsJson;
+    try {
+        settingsJson = await deps.readSettingsJson();
+    }
+    catch {
+        return Err('Could not read settings.json — check file permissions');
+    }
+    let parsedSettings;
+    try {
+        parsedSettings = JSON.parse(settingsJson);
+    }
+    catch {
+        return Err('settings.json is malformed — fix it before enabling the proxy');
+    }
+    const envState = readProxyEnvState(settingsJson, port);
+    if (envState === 'foreign') {
+        return Err('An existing ANTHROPIC_BASE_URL in settings.json points to a different gateway — Devflow will not overwrite it');
+    }
+    // API key warning (non-fatal)
+    const envBlock = parsedSettings.env;
+    if (typeof envBlock === 'object' &&
+        envBlock !== null &&
+        !Array.isArray(envBlock) &&
+        typeof envBlock.ANTHROPIC_API_KEY === 'string') {
+        deps.onWarn?.('ANTHROPIC_API_KEY is set in settings.json — requests will use that key through the local relay');
+    }
+    return Ok({ binPath, npxWarning, adopted: false });
+}
+// ─── Production dependency implementations ────────────────────────────────────
+/** Production TCP connect implementation. */
+async function realTcpConnectable(port, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection({ host: '127.0.0.1', port, timeout: timeoutMs });
+        socket.on('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('error', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.on('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+/**
+ * Production HTTP/HTTPS GET implementation — selects module from URL scheme.
+ *
+ * Three resource bounds:
+ *   • Wall-clock total deadline: fires when 'end' never arrives (SSE / trickle server).
+ *     `--disable` probes precisely the port Devflow no longer owns, so any local
+ *     service that trickles bytes could pin the CLI forever without this bound.
+ *   • 64 KB body cap: aborts before accumulating unbounded memory.
+ *   • res.on('error') listener: response-stream errors are caught, not ignored.
+ *
+ * Exported for reliability tests.
+ */
+export async function realHttpGet(url, timeoutMs) {
+    const mod = url.startsWith('https://') ? https : http;
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(r);
+        };
+        // Wall-clock deadline — independent of the per-chunk socket idle timeout below.
+        const wallClock = setTimeout(() => {
+            req.destroy();
+            settle(Err('deadline exceeded'));
+        }, timeoutMs);
+        wallClock.unref();
+        const req = mod.get(url, { timeout: timeoutMs }, (res) => {
+            let bodyBytes = 0;
+            let body = '';
+            res.on('data', (chunk) => {
+                bodyBytes += chunk.length;
+                if (bodyBytes > BODY_CAP_BYTES) {
+                    res.destroy();
+                    req.destroy();
+                    clearTimeout(wallClock);
+                    settle(Err('response too large'));
+                    return;
+                }
+                body += chunk.toString();
+            });
+            res.on('end', () => {
+                clearTimeout(wallClock);
+                settle(Ok(body));
+            });
+            res.on('error', (err) => {
+                clearTimeout(wallClock);
+                settle(Err(err.message));
+            });
+        });
+        req.on('error', (err) => {
+            clearTimeout(wallClock);
+            settle(Err(err.message));
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            clearTimeout(wallClock);
+            settle(Err('timeout'));
+        });
+    });
+}
+/** Production doctor subprocess implementation. */
+async function realSpawnDoctor(binPath, env, timeoutMs, logFile) {
+    // openProxyLog: 0700 parent dir + 0600 file creation + best-effort chmod for
+    // pre-existing wider modes (SEC-2). Non-fatal on chmod failure per PF-009.
+    const logFd = await openProxyLog(logFile);
+    try {
+        return await new Promise((resolve) => {
+            const proc = cpSpawn(process.execPath, [binPath, 'doctor'], {
+                env,
+                stdio: ['ignore', logFd.fd, logFd.fd],
+            });
+            let resolved = false;
+            const timer = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    proc.kill(); // SIGTERM — ask the process to terminate gracefully
+                    // A SIGTERM-trapping child keeps the event loop alive (no unref on
+                    // proc here, since we are awaiting the promise). Schedule a SIGKILL escalation
+                    // after a short grace period. The escalation timer is unref()'d so it never
+                    // prevents the CLI from exiting on its own if the process exits first.
+                    const sigkillTimer = setTimeout(() => {
+                        try {
+                            proc.kill('SIGKILL');
+                        }
+                        catch { /* already dead — ignore */ }
+                    }, 2000);
+                    sigkillTimer.unref();
+                    resolve(1);
+                }
+            }, timeoutMs);
+            proc.on('close', (code) => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timer);
+                    resolve(code ?? 1);
+                }
+            });
+            // OS-level spawn failure (EMFILE, ENOMEM, EAGAIN) must be handled — an
+            // unhandled 'error' event becomes an uncaught exception. Resolve(1) so the
+            // finally block closes logFd and callers get a clean failure path.
+            proc.on('error', () => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timer);
+                    resolve(1);
+                }
+            });
+        });
+    }
+    finally {
+        await logFd.close();
+    }
+}
+/**
+ * Build the real (production) ProxyPreflightDeps from the given options.
+ * Centralises the three private implementations so both runEnable and init.ts
+ * can consume them without byte-identical inline copies.
+ *
+ * applies ADR-013: pure configuration factory; I/O implementations factored once.
+ */
+export function buildRealPreflightDeps(opts) {
+    const { settingsPath, onWarn, swallowSettingsReadError = false } = opts;
+    return {
+        resolveProxyBin,
+        fileExists: async (filePath) => {
+            try {
+                await fs.access(filePath);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        tcpConnectable: realTcpConnectable,
+        httpGet: realHttpGet,
+        readSettingsJson: swallowSettingsReadError
+            ? async () => { try {
+                return await fs.readFile(settingsPath, 'utf-8');
+            }
+            catch {
+                return '{}';
+            } }
+            : () => fs.readFile(settingsPath, 'utf-8'),
+        spawnDoctor: realSpawnDoctor,
+        onWarn,
+    };
+}
+/**
+ * Spawn the relay (unless adopted) and wait up to 50×100ms for TCP accept.
+ *
+ * When `adopted` is true, the relay is already running — skip spawn entirely.
+ *
+ * Returns `{ ok: true }` when the port accepts connections.
+ * Returns `{ ok: false }` when:
+ *   - relay never accepted after 50 probes (caller should rollback proxy.json)
+ *   - relay process died before the port came up
+ *   - OS-level spawn error (EMFILE, ENOMEM, EAGAIN) — always handled via the
+ *     injected onError callback, never an uncaught exception
+ *
+ * avoids PF-014: no process.exit() — returns Result; caller decides error handling.
+ */
+export async function spawnRelayAndWaitForPort(port, binPath, configPath, logPath, pidPath, adopted, deps) {
+    if (adopted) {
+        // Port already hosting our relay — skip spawn entirely, proceed to settings pass.
+        return { ok: true };
+    }
+    const logHandle = await deps.openLog(logPath);
+    let spawnError;
+    // SEC-2: allowlist env for the relay — only PATH/HOME/TMPDIR/LANG/LC_ALL are
+    // inherited; SUBSWITCH_CONFIG is the only process-specific addition here.
+    const env = { ...scrubChildEnv(), SUBSWITCH_CONFIG: configPath };
+    const { pid } = deps.spawnProcess({
+        execPath: process.execPath,
+        args: [binPath, 'serve'],
+        env,
+        stdioFd: logHandle.fd,
+        // Captured here; breaks the wait loop on the next iteration
+        onError: (err) => { spawnError = err; },
+    });
+    // Parent closes its copy; the spawned child retains the fd through the OS
+    await logHandle.close();
+    if (pid !== undefined) {
+        // Non-fatal: best-effort pid record for devflow proxy --status
+        await deps.writePid(pidPath, pid);
+    }
+    // Bounded wait: ≤RELAY_SPAWN_MAX_PROBES×100ms (5s max) for TCP accept
+    let portUp = false;
+    for (let i = 0; i < RELAY_SPAWN_MAX_PROBES; i++) {
+        await deps.sleep(RELAY_SPAWN_PROBE_INTERVAL_MS);
+        if (spawnError !== undefined) {
+            // OS-level error fired — no point waiting; relay will never start
+            break;
+        }
+        if (pid !== undefined && !deps.isProcessAlive(pid)) {
+            // Process died before port came up — check for EADDRINUSE race
+            // (another session may have started and already owns the port)
+            if (await deps.tcpConnectable(port, RELAY_SPAWN_PER_PROBE_TIMEOUT_MS)) {
+                portUp = true;
+            }
+            break;
+        }
+        if (await deps.tcpConnectable(port, RELAY_SPAWN_PER_PROBE_TIMEOUT_MS)) {
+            portUp = true;
+            break;
+        }
+    }
+    if (!portUp) {
+        return { ok: false, reason: 'relay-not-started' };
+    }
+    return { ok: true, spawnedPid: pid };
+}
+/** Build the real (production) SpawnAndWaitDeps. Not exported — internal to runEnable. */
+function buildRealSpawnAndWaitDeps() {
+    return {
+        openLog: async (logPath) => {
+            // openProxyLog: 0700 parent dir + 0600 file creation + best-effort chmod (SEC-2).
+            const handle = await openProxyLog(logPath);
+            return { fd: handle.fd, close: () => handle.close() };
+        },
+        spawnProcess: ({ execPath, args, env, stdioFd, onError }) => {
+            const proc = cpSpawn(execPath, args, {
+                detached: true,
+                stdio: ['ignore', stdioFd, stdioFd],
+                env,
+            });
+            // Attach error handler before unref so OS-level failures are caught
+            proc.on('error', onError);
+            proc.unref();
+            return { pid: proc.pid };
+        },
+        writePid: async (pidPath, pid) => {
+            // Non-fatal: failure is inconvenient (--status loses pid) but not blocking
+            try {
+                await fs.writeFile(pidPath, String(pid), 'utf-8');
+            }
+            catch { /* non-fatal */ }
+        },
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        isProcessAlive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        tcpConnectable: realTcpConnectable,
+    };
+}
+/**
+ * Run `node <binPath> doctor` against the live relay and handle failure.
+ *
+ * @D-EFR-2 Doctor gates post-spawn, not pre-spawn: the relay's doctor subcommand
+ *   probes the relay port to confirm it is running — a not-yet-started relay makes
+ *   that probe fail (exit 1), so a pre-spawn gate is always unsatisfiable on a cold
+ *   path (the port is down by definition before spawn). Moving the gate post-spawn
+ *   means doctor runs against an already-live relay, turning "running: NO" into
+ *   "running: YES" on the healthy path, validating codex auth and TLS reachability.
+ *
+ *   Kill-on-rollback is restricted to self-spawned relays (spawnedPid defined): an
+ *   adopted relay may be serving other live Claude Code sessions, so we must never
+ *   kill it. A just-spawned relay predates the settings pass, so no session is
+ *   routing through it — SIGTERM is safe (with a SIGKILL escalation in the caller).
+ *
+ * @param spawnedPid  Pid of the relay we spawned; undefined when the relay was adopted.
+ * @returns Ok(undefined) when doctor exits 0; Err(message) on failure. On failure the
+ *          rollback (writeDisabledProxyState) and conditional kill are applied before
+ *          returning — the caller does not need to do additional rollback.
+ */
+export async function runPostSpawnVerification(binPath, configPath, logPath, spawnedPid, deps) {
+    // SEC-2: allowlist env for doctor — matches the relay spawn composition.
+    const doctorEnv = { ...scrubChildEnv(), SUBSWITCH_CONFIG: configPath };
+    const doctorExit = await deps.spawnDoctor(binPath, doctorEnv, DOCTOR_TIMEOUT_MS, logPath);
+    if (doctorExit === 0)
+        return Ok(undefined);
+    // Doctor failed — rollback proxy state and conditionally kill the relay.
+    // Both are best-effort: write failure is secondary; kill failure means process already exited.
+    await deps.writeDisabledProxyState();
+    if (spawnedPid !== undefined) {
+        deps.killProcess(spawnedPid);
+    }
+    return Err(`Routing verification failed — see ${logPath}`);
+}
+// ─── Atomic settings mutation for enable ─────────────────────────────────────
+/**
+ * Perform the single atomic settings.json pass for enable:
+ * strip old hooks + env, then apply new hooks + env in one write.
+ *
+ * The writeFileAtomicExclusive call is guarded — ENOSPC/EACCES returns Err
+ * instead of crashing with an unhandled rejection.
+ *
+ * Returns Ok(undefined) on success, Err(reason) on hard failure.
+ */
+async function applyEnableSettingsPass(settingsPath, devflowDir, port) {
+    let settingsContent;
+    try {
+        settingsContent = await fs.readFile(settingsPath, 'utf-8');
+    }
+    catch {
+        // Missing settings.json is fine — start from an empty object
+        settingsContent = '{}';
+    }
+    let parsedSettings;
+    try {
+        parsedSettings = JSON.parse(settingsContent);
+    }
+    catch {
+        return Err('settings.json is malformed — fix it before enabling the proxy');
+    }
+    // Atomic 4-call settings mutation: strip stale entries, then apply fresh ones.
+    // Strip is scoped to `port` (the new port being applied). The apply
+    // call below always overwrites ANTHROPIC_BASE_URL regardless, so the strip
+    // here primarily removes any exact-port match before the write-set cycle.
+    removeProxyHooks(parsedSettings);
+    _stripProxyEnvFromObject(parsedSettings, port);
+    addProxyHooks(parsedSettings, devflowDir);
+    _applyProxyEnvToObject(parsedSettings, port);
+    try {
+        await writeFileAtomicExclusive(settingsPath, JSON.stringify(parsedSettings, null, 2) + '\n');
+    }
+    catch (err) {
+        return Err(`Could not write settings.json: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return Ok(undefined);
+}
+// ─── PID-to-port identity binding ─────────────────────────────────────────────
+/**
+ * Resolve the PID of the process currently listening on the given TCP port.
+ *
+ * @D-EFR-5 PID-port identity gate: signal 0 proves a PID exists; a health
+ *   check proves some process on the port is our relay. Neither alone proves
+ *   the pid-file PID *is* the listening process. A recycled PID can fool both
+ *   checks simultaneously. The fix: use lsof to resolve the listening PID
+ *   directly and require it to equal the pid-file PID before any signal.
+ *
+ *   lsof is the canonical tool on darwin and is commonly available on linux.
+ *   On unsupported platforms or when lsof is absent/restricted, returns null
+ *   so the caller fails safe (identity-unconfirmed) rather than throwing.
+ *
+ * On darwin and linux: `lsof -nP -iTCP:<port> -sTCP:LISTEN -t`
+ *   -n  no host-name resolution  -P  no port-name resolution
+ *   -sTCP:LISTEN  only LISTEN-state sockets  -t  PIDs only
+ *
+ * avoids PF-001: fixed argument array — port is validated as a safe integer
+ *   by the caller before this function is invoked; it is never interpolated
+ *   into a shell string.
+ *
+ * Returns null when:
+ *   • Platform is not darwin or linux
+ *   • lsof is not on PATH or returns a non-zero exit code (EPERM, etc.)
+ *   • Zero processes are listening on the port
+ *   • More than one PID is returned (ambiguous — fail safe)
+ *   • The single returned value is not a valid positive integer
+ */
+async function realResolveListeningPid(port) {
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+        return null;
+    }
+    return new Promise((resolve) => {
+        // SEC: fixed argument list — port is a validated integer (1-65535).
+        const proc = cpSpawn('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        let stdout = '';
+        proc.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        // Spawn failure (ENOENT = lsof absent, EPERM = restricted) → degrade to null
+        proc.on('error', () => resolve(null));
+        proc.on('close', () => {
+            const lines = stdout.trim().split('\n').filter(Boolean);
+            // Zero or more-than-one result: ambiguous → fail safe
+            if (lines.length !== 1) {
+                resolve(null);
+                return;
+            }
+            const parsed = parseInt(lines[0].trim(), 10);
+            resolve(Number.isInteger(parsed) && parsed > 0 ? parsed : null);
+        });
+    });
+}
+/**
+ * Read and parse the relay PID file. Returns null on ENOENT, parse failure, or
+ * invalid value — callers treat null as "no pid available".
+ */
+async function readPidFile(pidPath) {
+    try {
+        const pidStr = await fs.readFile(pidPath, 'utf-8');
+        const pid = parseInt(pidStr.trim(), 10);
+        return !isNaN(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Terminate the relay process recorded in the pid file, with identity confirmation.
+ *
+ * Protocol:
+ *   1. Read the pid file — skip silently if absent.
+ *   2. Check liveness (signal 0).
+ *   3. Confirm identity — three signals, ALL must pass before signalling:
+ *      a. TCP probe: port is accepting connections.
+ *      b. Health check: the process on the port is our relay (`isOurRelayBody`).
+ *      c. PID-port binding (D-EFR-5): lsof confirms the pid-file PID is the
+ *         process listening on the port. If lsof is unavailable or ambiguous,
+ *         fail safe — return 'identity-unconfirmed' without signalling.
+ *   4. SIGTERM → poll for death every 250 ms for up to 2 s (8 checks).
+ *   5. SIGKILL → poll for death every 250 ms for up to 2 s (8 checks).
+ *   6. Remove the pid file when the process is gone.
+ *   7. Best-effort rmdir of .proxy-spawn.lock when stale.
+ *
+ * applies D-EFR-5: signal 0 and health check are independent facts; lsof
+ *   binds the pid-file PID to the port owner before any signal is sent.
+ * avoids PF-009: all sub-operations are non-fatal; a kill failure never aborts disable.
+ * avoids PF-014: never process.exit() inside a finally-guarded scope.
+ *
+ * @param deps  Optional injectable dependencies (default: real lsof implementation).
+ *              Provide a stub in tests to exercise every branch without a real binary.
+ *
+ * @returns 'killed'     — relay stopped successfully.
+ *          'not-running' — pid file absent or process already dead.
+ *          'identity-unconfirmed' — pid alive but identity not positively established
+ *                                   (health or lsof mismatch); no signal sent.
+ *          'kill-failed' — SIGTERM + SIGKILL sent but process still alive after grace.
+ */
+export async function terminateRelay(pidPath, spawnLockPath, port, deps = { resolveListeningPid: realResolveListeningPid }) {
+    // Step 1: read pid file
+    const pid = await readPidFile(pidPath);
+    if (pid === null)
+        return 'not-running';
+    // Step 2: check liveness
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        // Process already dead
+        try {
+            await fs.unlink(pidPath);
+        }
+        catch { /* best-effort */ }
+        return 'not-running';
+    }
+    // Step 3: confirm identity — all three signals must pass (D-EFR-5)
+    //
+    // Signal (a): TCP probe — confirms the port is accepting connections at all.
+    const portUp = await realTcpConnectable(port, PROBE_TIMEOUT_MS);
+    let identityConfirmed = false;
+    if (portUp) {
+        // Signal (b): health check — confirms the process on the port is our relay.
+        const healthResult = await realHttpGet(`${proxyBaseUrl(port)}/__subswitch/health`, PROBE_TIMEOUT_MS);
+        const healthOk = healthResult.ok && isOurRelayBody(healthResult.value);
+        if (healthOk) {
+            // Signal (c): PID-port binding — lsof confirms the pid-file PID owns the port.
+            // If lsof is absent, returns null → null !== pid → identityConfirmed stays false.
+            // Failing safe is strictly better than signalling the wrong process.
+            const listeningPid = await deps.resolveListeningPid(port);
+            identityConfirmed = listeningPid === pid;
+        }
+    }
+    if (!identityConfirmed) {
+        return 'identity-unconfirmed';
+    }
+    // Bounded poll helper: check if PID is alive every 250 ms, up to maxChecks iterations.
+    // Returns true when the process is gone within the polling window.
+    const pollDead = async (maxChecks) => {
+        for (let i = 0; i < maxChecks; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 250));
+            try {
+                process.kill(pid, 0);
+            }
+            catch {
+                return true;
+            }
+        }
+        return false;
+    };
+    // Step 4: SIGTERM → bounded 2 s wait (8 × 250 ms)
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch { /* already exited — race */ }
+    const deadAfterTerm = await pollDead(8);
+    if (!deadAfterTerm) {
+        // Step 5: SIGKILL → bounded 2 s wait (8 × 250 ms)
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* already exited — race */ }
+        const deadAfterKill = await pollDead(8);
+        if (!deadAfterKill) {
+            return 'kill-failed';
+        }
+    }
+    // Step 6: remove pid file
+    try {
+        await fs.unlink(pidPath);
+    }
+    catch { /* best-effort */ }
+    // Step 7: best-effort rmdir of spawn lock when stale
+    try {
+        await fs.rmdir(spawnLockPath);
+    }
+    catch { /* held by another session or absent — ignore */ }
+    return 'killed';
+}
+/**
+ * Probe relay process state via TCP connect + health identity check.
+ * Always probes — does not short-circuit when the feature is disabled.
+ * This ensures `--status` surfaces the divergence case where the feature is
+ * disabled but the relay process is still listening (the relay is not killed on
+ * `--disable` for live-session continuity; it may outlive the disable operation).
+ */
+async function resolveProcessState(port) {
+    const portUp = await realTcpConnectable(port, PROBE_TIMEOUT_MS);
+    if (!portUp)
+        return 'down';
+    const healthResult = await realHttpGet(`${proxyBaseUrl(port)}/__subswitch/health`, PROBE_TIMEOUT_MS);
+    // Uses shared isOurRelayBody helper (same logic as runProxyPreflight)
+    if (healthResult.ok && isOurRelayBody(healthResult.value)) {
+        return 'running-ours';
+    }
+    // Port accepting but health timed out, failed, or not our relay
+    return 'port-squatted';
+}
+/**
+ * Pure: compute the process log line from resolved state.
+ * Returns null when no line should be emitted (dead pid + non-down processState).
+ */
+function formatProcessLine(processState, pidAlive, pidFromFile, port) {
+    if (pidFromFile !== null) {
+        if (pidAlive) {
+            if (processState === 'running-ours') {
+                return {
+                    level: 'info',
+                    msg: `Process: ${color.green('running')} (pid ${pidFromFile}) — stop manually with: kill ${pidFromFile}`,
+                };
+            }
+            else if (processState === 'port-squatted') {
+                return {
+                    level: 'warn',
+                    msg: `Process: ${color.yellow('port squatted by another app')} (pid ${pidFromFile} alive but port ${port} is not our relay)`,
+                };
+            }
+            else {
+                return {
+                    level: 'info',
+                    msg: `Process: ${color.yellow('pid alive but port not responding')} (pid ${pidFromFile})`,
+                };
+            }
+        }
+        // Pid dead
+        if (processState === 'down') {
+            return {
+                level: 'info',
+                msg: `Process: ${color.dim('down')} (last pid ${pidFromFile}, no longer running)`,
+            };
+        }
+        return null; // pid dead but port squatted/running — unusual, no line
+    }
+    // No pid file
+    if (processState === 'running-ours') {
+        return { level: 'info', msg: `Process: ${color.green('running')} (no pid file)` };
+    }
+    else if (processState === 'port-squatted') {
+        return {
+            level: 'warn',
+            msg: `Process: ${color.yellow('port squatted')} — port ${port} is in use by another application`,
+        };
+    }
+    else {
+        return { level: 'info', msg: `Process: ${color.dim('down')}` };
+    }
+}
+// ─── Status formatters ────────────────────────────────────────────────────────
+/**
+ * Pure formatter for the external models status line shown by `devflow proxy --status`.
+ *
+ * Extracted to enable isolated testing without clack I/O. (AC-F6)
+ */
+export function formatExternalModelsLine(catalog, logPath) {
+    if (catalog.known) {
+        return `External models: ${color.cyan(catalog.selectableNames.join(', '))}`;
+    }
+    return `External models: ${color.dim('unavailable')} — see ${logPath}`;
+}
+/**
+ * Pure formatter for the Codex auth status line shown by `devflow proxy --status`.
+ *
+ * Returns `{level, msg}` — level encodes the warn-on-unreadable rule so callers
+ * need not re-derive it from `state.kind`. `unreadable` is the only state the user
+ * must act on (the relay rejects requests at that point while a bare file-existence
+ * check still reported success). Expiry is informational: the relay refreshes the
+ * access token on its own, so an expired stamp on a healthy install is normal.
+ *
+ * @param now  Injected for deterministic tests; pass `new Date()` in production.
+ */
+export function formatCodexAuthLine(state, authPath, now) {
+    switch (state.kind) {
+        case 'absent':
+            return { level: 'info', msg: `Codex auth: ${color.dim('absent')} — run codex login` };
+        case 'unreadable':
+            return {
+                level: 'warn',
+                msg: `Codex auth: ${color.red(`unreadable (${state.reason})`)} at ${authPath} — run codex login`,
+            };
+        case 'present': {
+            // authMode comes from the third-party ~/.codex/auth.json; strip
+            // ANSI escapes and cap length before embedding in terminal output.
+            const safeAuthMode = stripAnsi(state.authMode).slice(0, AUTH_MODE_MAX_LEN);
+            const identity = `${safeAuthMode}, ${state.accountSuffix}`;
+            const present = `Codex auth: ${color.green('present')} (${identity})`;
+            if (state.expiresAt === undefined)
+                return { level: 'info', msg: present };
+            const stamp = state.expiresAt.toISOString().slice(0, 10);
+            const msg = state.expiresAt.getTime() <= now.getTime()
+                ? `${present} — access token expired ${stamp}, refreshes on next request`
+                : `${present} — access token valid through ${stamp}`;
+            return { level: 'info', msg };
+        }
+        default: {
+            const exhaustive = state;
+            void exhaustive;
+            return { level: 'info', msg: '' };
+        }
+    }
+}
+// ─── Port resolution ──────────────────────────────────────────────────────────
+/**
+ * Resolve the effective port for enable.
+ *
+ * When portOption is undefined (--port flag not provided by the user), falls back to
+ * priorPort from proxy.json. This is the remembered-port path: a user who enabled on
+ * port 5000, disabled, then re-enables without --port correctly reuses 5000.
+ *
+ * @param portOption  Commander --port value; undefined when flag not provided
+ * @param priorPort   Last-used port from proxy.json (or DEFAULT_PROXY_PORT)
+ */
+export function resolvePort(portOption, priorPort) {
+    if (portOption === undefined)
+        return Ok(priorPort);
+    const parsed = parseInt(portOption, 10);
+    if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+        return Err(`Invalid port: ${portOption}`);
+    }
+    return Ok(parsed);
+}
+export const proxyCommand = new Command('proxy')
+    .description('Enable or disable external model routing (GPT models via your OpenAI/Codex subscription)')
+    .option('--enable', 'Enable external model routing via the Devflow proxy')
+    .option('--disable', 'Disable external model routing')
+    .option('--status', 'Show proxy status')
+    .option('--port <n>', 'Port for the local relay (default: remembered or 4141)')
+    .action(async (options) => {
+    // No flag → show status
+    const hasFlag = options.enable || options.disable || options.status;
+    if (!hasFlag) {
+        await runStatus();
+        return;
+    }
+    if (options.status) {
+        await runStatus();
+        return;
+    }
+    if (options.enable) {
+        await runEnable(options.port);
+        return;
+    }
+    if (options.disable) {
+        await runDisable();
+        return;
+    }
+});
+// ─── Status ───────────────────────────────────────────────────────────────────
+async function runStatus() {
+    const devflowDir = getDevFlowDirectory();
+    const claudeDir = getClaudeDirectory();
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    const home = getHomeDirectory();
+    const logPath = path.join(devflowDir, 'logs', 'proxy.log');
+    const pidPath = path.join(devflowDir, 'proxy.pid');
+    const codexAuthPath = path.join(home, '.codex', 'auth.json');
+    p.intro(color.bgBlue(color.white(' Devflow Proxy Status ')));
+    // Feature state: manifest + proxy.json
+    const manifest = await readManifest(devflowDir);
+    const proxyStateResult = await readProxyState(devflowDir);
+    const proxyState = proxyStateResult.ok ? proxyStateResult.value : null;
+    const manifestEnabled = manifest?.features.proxy ?? false;
+    const stateEnabled = proxyState?.enabled ?? false;
+    if (manifestEnabled !== stateEnabled) {
+        p.log.warn(`Feature state drift: manifest says ${manifestEnabled ? color.green('enabled') : color.dim('disabled')}, ` +
+            `proxy.json says ${stateEnabled ? color.green('enabled') : color.dim('disabled')} — run devflow proxy --enable or --disable to repair`);
+    }
+    const featureEnabled = manifestEnabled && stateEnabled;
+    p.log.info(`Feature: ${featureEnabled ? color.green('enabled') : color.dim('disabled')}` +
+        (proxyState?.port ? ` (port ${proxyState.port})` : ''));
+    // Process state — always probe regardless of featureEnabled so that the
+    // divergence case (feature disabled but relay still running) is visible.
+    const port = proxyState?.port ?? DEFAULT_PROXY_PORT;
+    const processState = await resolveProcessState(port);
+    // Divergence: feature is disabled but the relay is still responding.
+    // This is the expected state immediately after `--disable` — the relay
+    // keeps serving any live Claude Code sessions whose env captured the URL.
+    if (!stateEnabled && processState === 'running-ours') {
+        p.log.warn(`Relay is still running on port ${port} even though external model routing is disabled. ` +
+            `Live Claude Code sessions whose env captured the relay URL continue routing through it. ` +
+            `Run ${color.cyan('devflow proxy --disable')} again to stop the relay, ` +
+            `or restart Claude Code to clear the routed session.`);
+    }
+    const pidFromFile = await readPidFile(pidPath);
+    let pidAlive = false;
+    if (pidFromFile !== null) {
+        try {
+            process.kill(pidFromFile, 0);
+            pidAlive = true;
+        }
+        catch { /* dead */ }
+    }
+    const processLine = formatProcessLine(processState, pidAlive, pidFromFile, port);
+    if (processLine !== null) {
+        if (processLine.level === 'warn') {
+            p.log.warn(processLine.msg);
+        }
+        else {
+            p.log.info(processLine.msg);
+        }
+    }
+    // Env state
+    let envState = 'absent';
+    try {
+        const settingsJson = await fs.readFile(settingsPath, 'utf-8');
+        envState = readProxyEnvState(settingsJson, port);
+    }
+    catch { /* settings missing */ }
+    const envStateLabels = {
+        'ours': color.green('set (our relay)'),
+        'ours-other-port': color.yellow('set (our relay, different port)'),
+        'foreign': color.red('set (foreign gateway — Devflow will not overwrite)'),
+        'absent': color.dim('not set'),
+    };
+    p.log.info(`ANTHROPIC_BASE_URL: ${envStateLabels[envState]}`);
+    // Codex auth — inspect contents, not just existence. A file the relay would
+    // reject (bad JSON, no account id) 401s every request while an existence check
+    // still reports "present"; that gap is what this check closes.
+    let codexAuth;
+    try {
+        codexAuth = inspectCodexAuth(await fs.readFile(codexAuthPath, 'utf-8'));
+    }
+    catch (err) {
+        codexAuth = classifyCodexAuthReadError(err);
+    }
+    const codexAuthLine = formatCodexAuthLine(codexAuth, codexAuthPath, new Date());
+    if (codexAuthLine.level === 'warn') {
+        p.log.warn(codexAuthLine.msg);
+    }
+    else {
+        p.log.info(codexAuthLine.msg);
+    }
+    // Agent mapping count
+    const mappingResult = await readAgentMapping(devflowDir);
+    if (mappingResult.ok) {
+        const count = countExternalMappedAgents(mappingResult.value);
+        if (count > 0) {
+            p.log.info(`External-mapped agents: ${color.cyan(String(count))}`);
+        }
+        else {
+            p.log.info('External-mapped agents: none — use devflow agents to configure');
+        }
+    }
+    // External models registry (cache-only, zero spawns — avoids multi-second silent pause in --status)
+    const cacheDir = modelCacheDir(devflowDir); // authoritative path from cache.ts (avoids PF-013)
+    const catalog = getExternalModelsCached(cacheDir);
+    p.log.info(formatExternalModelsLine(catalog, logPath));
+    // Log path
+    p.log.info(`Proxy log: ${color.dim(logPath)}`);
+    if (featureEnabled && processState === 'running-ours') {
+        p.note(`${color.cyan('devflow proxy --disable')}  Disable external model routing\n` +
+            `${color.cyan('devflow proxy --status')}   Refresh status`, 'Management');
+    }
+    else {
+        p.note(`${color.cyan('devflow proxy --enable')}   Enable external model routing\n` +
+            `${color.cyan('devflow proxy --status')}   Refresh status`, 'Management');
+    }
+}
+// ─── Enable ───────────────────────────────────────────────────────────────────
+async function runEnable(portOption) {
+    const devflowDir = getDevFlowDirectory();
+    const claudeDir = getClaudeDirectory();
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    const installDir = path.join(claudeDir, 'agents', 'devflow');
+    const home = getHomeDirectory();
+    const codexAuthPath = path.join(home, '.codex', 'auth.json');
+    const configPath = path.join(devflowDir, 'proxy-routing.json');
+    const logPath = path.join(devflowDir, 'logs', 'proxy.log');
+    const pidPath = path.join(devflowDir, 'proxy.pid');
+    const cacheDir = modelCacheDir(devflowDir); // authoritative path from cache.ts (avoids PF-013)
+    // Step 1: Read prior proxy.json (remembered port); --port flag overrides
+    const priorStateResult = await readProxyState(devflowDir);
+    const priorPort = priorStateResult.ok ? priorStateResult.value.port : DEFAULT_PROXY_PORT;
+    const portResult = resolvePort(portOption, priorPort);
+    if (!portResult.ok) {
+        p.log.error(portResult.error);
+        process.exitCode = 1;
+        return;
+    }
+    const port = portResult.value;
+    const s = p.spinner();
+    s.start('Running preflight checks...');
+    // Step 2: Write routing config
+    await fs.mkdir(devflowDir, { recursive: true });
+    // SEC-2: mode 0o700 for the logs directory (new directories only; pre-existing
+    // dirs are unaffected by mkdir). openProxyLog handles individual file mode.
+    await fs.mkdir(path.join(devflowDir, 'logs'), { recursive: true, mode: 0o700 });
+    // SEC-2 pre-spawn rotation: rotate proxy.log before the relay opens an fd on it.
+    // MUST run before spawnRelayAndWaitForPort (Step 5) — a rename while the relay
+    // holds an append fd would orphan that fd. At this point no relay is running.
+    await rotateProxyLogIfLarge(logPath);
+    // Read existing routing config to preserve user-added anthropic/limits/logLevel/providers
+    // blocks. A missing or malformed file falls back to clean defaults inside
+    // buildRoutingConfigJson (non-fatal; avoids PF-009).
+    let existingRoutingContent;
+    try {
+        existingRoutingContent = await fs.readFile(configPath, 'utf-8');
+    }
+    catch { /* ENOENT or EACCES — fall through to clean defaults */ }
+    try {
+        await fs.writeFile(configPath, buildRoutingConfigJson(port, existingRoutingContent), 'utf-8');
+    }
+    catch (err) {
+        s.stop(color.red('Failed to write routing config'));
+        p.log.error(`Could not write routing config: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Step 3: Preflight checks (①–④: bin, codex auth, port probe, settings)
+    // preflightDeps is saved so spawnDoctor can be reused in step 6 (post-spawn verification).
+    const preflightDeps = buildRealPreflightDeps({
+        settingsPath,
+        // runEnable propagates settings read errors (init.ts swallows — see swallowSettingsReadError)
+        swallowSettingsReadError: false,
+        onWarn: (msg) => { s.stop(''); p.log.warn(msg); s.start(''); },
+    });
+    const preflightResult = await runProxyPreflight(port, codexAuthPath, configPath, logPath, preflightDeps);
+    if (!preflightResult.ok) {
+        s.stop(color.red('Preflight failed'));
+        p.log.error(preflightResult.error);
+        process.exitCode = 1;
+        return;
+    }
+    const { binPath, npxWarning, adopted } = preflightResult.value;
+    // Shared best-effort rollback for steps 5–7: write proxy.json enabled:false so a
+    // subsequent --enable attempt does not believe the relay is running. A write failure
+    // here is always secondary to the primary failure — never surfaced to the user.
+    // All captured variables (binPath, configPath, port, devflowDir) are resolved by
+    // this point.
+    const rollbackProxyState = async () => {
+        await writeProxyState(devflowDir, buildProxyState({
+            enabled: false,
+            port,
+            binPath,
+            configPath,
+            devflowVersion: getDevflowVersion(),
+        }));
+    };
+    s.message('Writing proxy state...');
+    // Step 4: Write proxy.json enabled:true
+    const newState = buildProxyState({
+        enabled: true,
+        port,
+        binPath,
+        configPath,
+        devflowVersion: getDevflowVersion(),
+    });
+    const writeStateResult = await writeProxyState(devflowDir, newState);
+    if (!writeStateResult.ok) {
+        s.stop(color.red('Failed to write proxy state'));
+        p.log.error(writeStateResult.error);
+        process.exitCode = 1;
+        return;
+    }
+    // Step 5: Spawn relay and wait for port
+    if (!adopted) {
+        s.message('Starting relay...');
+    }
+    const spawnResult = await spawnRelayAndWaitForPort(port, binPath, configPath, logPath, pidPath, adopted, buildRealSpawnAndWaitDeps());
+    if (!spawnResult.ok) {
+        await rollbackProxyState();
+        s.stop(color.red('Relay failed to start'));
+        p.log.error(`Proxy failed to start — check ${logPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    const { spawnedPid } = spawnResult;
+    // Step 6: Post-spawn doctor verification — runs against the live relay (see D-EFR-2).
+    // Relay is confirmed up before this runs, so "running: YES" is the expected outcome.
+    s.message('Verifying routing connection...');
+    const verifyResult = await runPostSpawnVerification(binPath, configPath, logPath, spawnedPid, {
+        spawnDoctor: preflightDeps.spawnDoctor,
+        // Best-effort SIGTERM + SIGKILL escalation after 2s grace period.
+        // Only called when we spawned the relay (spawnedPid defined) — see D-EFR-2.
+        killProcess: (pid) => {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch { /* already exited — ignore */ }
+            const sigkillTimer = setTimeout(() => {
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch { /* already exited — ignore */ }
+            }, 2000);
+            sigkillTimer.unref();
+        },
+        writeDisabledProxyState: rollbackProxyState,
+    });
+    if (!verifyResult.ok) {
+        // Rollback and conditional kill already applied inside runPostSpawnVerification
+        s.stop(color.red('Routing verification failed'));
+        p.log.error(verifyResult.error);
+        process.exitCode = 1;
+        return;
+    }
+    s.message('Updating settings...');
+    // Step 7: Atomic settings mutation
+    const settingsResult = await applyEnableSettingsPass(settingsPath, devflowDir, port);
+    if (!settingsResult.ok) {
+        await rollbackProxyState();
+        s.stop(color.red('Cannot update settings'));
+        p.log.error(settingsResult.error);
+        process.exitCode = 1;
+        return;
+    }
+    // Step 8: Sync manifest
+    await syncManifestFeature(devflowDir, 'proxy', true);
+    // Step 9: Reapply agent mapping
+    const reapplyResult = await reapplyAgentMapping({
+        proxyEnabled: true,
+        installDir,
+        devflowDir,
+    });
+    const mappedCount = reapplyResult.updated.length;
+    // Warm the model cache UNDER the spinner so the wait is visible and
+    // attributed. Strictly non-fatal — a cache failure must never affect the
+    // enable result. The promise is awaited so Node can exit cleanly after
+    // s.stop, instead of being held open ~200-600ms.
+    s.message('Warming model cache...');
+    await discoverExternalModels(cacheDir, logPath).catch(() => { });
+    s.stop(color.green('External model routing enabled'));
+    if (adopted) {
+        p.log.info(`Relay already running on port ${port} — adopted`);
+    }
+    else {
+        p.log.success(`Relay started on port ${port}`);
+    }
+    if (npxWarning) {
+        p.log.warn('Relay binary resolved from npx cache — may not persist across reboots; run devflow init to reinstall');
+    }
+    if (mappedCount > 0) {
+        p.log.info(`Restored external model mapping for ${mappedCount} agent(s)`);
+    }
+    p.log.info(color.dim('Takes effect in new Claude Code sessions. Use devflow agents to configure per-agent models.'));
+}
+// ─── Disable ──────────────────────────────────────────────────────────────────
+async function runDisable() {
+    const devflowDir = getDevFlowDirectory();
+    const claudeDir = getClaudeDirectory();
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    const installDir = path.join(claudeDir, 'agents', 'devflow');
+    const pidPath = path.join(devflowDir, 'proxy.pid');
+    // Read prior state FIRST (before settings pass) to determine managed port.
+    // applyDisableToSettings strips ANTHROPIC_BASE_URL only when the URL
+    // port matches the port Devflow manages — callers must supply it. Reading
+    // proxy.json here also consolidates state for Step 2 below.
+    const priorStateResult = await readProxyState(devflowDir);
+    const priorState = priorStateResult.ok ? priorStateResult.value : null;
+    const managedPort = priorState?.port ?? DEFAULT_PROXY_PORT;
+    // Step 1: Settings pass (removeProxyHooks + stripProxyEnv, single atomic write)
+    let settingsContent;
+    try {
+        settingsContent = await fs.readFile(settingsPath, 'utf-8');
+    }
+    catch {
+        settingsContent = '{}';
+    }
+    let parsedSettings;
+    try {
+        parsedSettings = JSON.parse(settingsContent);
+    }
+    catch {
+        p.log.error('settings.json is malformed — fix it before disabling the proxy');
+        process.exitCode = 1;
+        return;
+    }
+    const changed = applyDisableToSettings(parsedSettings, managedPort);
+    if (changed) {
+        // Guard ENOSPC/EACCES — unhandled rejection leaves proxy in partial state
+        try {
+            await writeFileAtomicExclusive(settingsPath, JSON.stringify(parsedSettings, null, 2) + '\n');
+        }
+        catch (err) {
+            p.log.error(`Could not write settings.json: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Step 2: Write proxy.json enabled:false (keep port/binPath/configPath)
+    const disabledState = buildProxyState({
+        enabled: false,
+        port: priorState?.port ?? DEFAULT_PROXY_PORT,
+        binPath: priorState?.binPath ?? null,
+        configPath: priorState?.configPath ?? null,
+        devflowVersion: getDevflowVersion(),
+    });
+    const writeDisabledResult = await writeProxyState(devflowDir, disabledState);
+    if (!writeDisabledResult.ok) {
+        p.log.error(`Could not write proxy state: ${writeDisabledResult.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Step 3: Sync manifest
+    await syncManifestFeature(devflowDir, 'proxy', false);
+    // Step 4: Revert external agents to shipped defaults
+    await revertExternalAgents({ installDir, devflowDir });
+    p.log.success('External model routing disabled');
+    // Step 5: Terminate the relay process.
+    // Identity is confirmed via TCP + health before signalling — a recycled PID
+    // must never be killed. avoids PF-009: all sub-operations are non-fatal.
+    const spawnLockPath = path.join(devflowDir, '.proxy-spawn.lock');
+    const terminateResult = await terminateRelay(pidPath, spawnLockPath, managedPort);
+    switch (terminateResult) {
+        case 'killed':
+            p.log.info('Relay process stopped.');
+            break;
+        case 'not-running':
+            p.log.info(color.dim('Relay process was not running.'));
+            break;
+        case 'identity-unconfirmed':
+            p.log.warn(`PID from proxy.pid is alive but the relay identity could not be confirmed ` +
+                `(port ${managedPort} is not responding as our relay). ` +
+                `Inspect the process before stopping it manually.`);
+            break;
+        case 'kill-failed':
+            p.log.warn(`Relay process (pid recorded in proxy.pid) did not stop after SIGTERM + SIGKILL. ` +
+                `It may still be running — check with: kill -0 <pid>`);
+            break;
+    }
+    // Always-print warning: already-running Claude Code sessions captured
+    // ANTHROPIC_BASE_URL in their process env before the disable. The env var
+    // is now stripped from settings.json so NEW sessions will not route, but
+    // any session that was open during enable continues routing until restarted.
+    p.log.warn('Already-running Claude Code sessions remain routed through the relay until they are restarted. ' +
+        'Restart Claude Code to fully stop routing in those sessions.');
+}
+//# sourceMappingURL=proxy.js.map