specrails-desktop 2.29.1 → 2.29.2

package/server/dist/headroom-manager.js

@@ -3,17 +3,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HeadroomManager = exports.HEADROOM_MANAGED_PYTHON_VERSION = void 0;
+exports.HeadroomManager = exports.HEADROOM_ACTIVATION_SOURCE = exports.HEADROOM_ACTIVATION_SCHEMA_VERSION = exports.HEADROOM_MANAGED_PYTHON_VERSION = exports.HEADROOM_RELAY_PATH = void 0;
 exports.getHeadroomManagedInstallPlan = getHeadroomManagedInstallPlan;
+exports.parseWindowsOwnershipSnapshot = parseWindowsOwnershipSnapshot;
+exports.windowsSnapshotHasOwnedListener = windowsSnapshotHasOwnedListener;
+exports.parseHeadroomDoctorRoutes = parseHeadroomDoctorRoutes;
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const fs_1 = __importDefault(require("fs"));
+const http_1 = __importDefault(require("http"));
+const net_1 = __importDefault(require("net"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const auth_1 = require("./auth");
 const desktop_db_1 = require("./desktop-db");
 const headroom_routing_1 = require("./headroom-routing");
+const win_spawn_1 = require("./util/win-spawn");
 const STATE_KEY = 'plugins.headroom.state';
 const DEFAULT_PORT = 8787;
+const PROXY_HEALTH_REQUEST_TIMEOUT_MS = 750;
+const RELAY_CONNECT_TIMEOUT_MS = 3_000;
+exports.HEADROOM_RELAY_PATH = '/_specrails/headroom';
 exports.HEADROOM_MANAGED_PYTHON_VERSION = '3.12';
+exports.HEADROOM_ACTIVATION_SCHEMA_VERSION = 1;
+exports.HEADROOM_ACTIVATION_SOURCE = 'explicit-user-action';
 function nowIso() {
     return new Date().toISOString();
 }
@@ -209,6 +222,290 @@ function classifyProxyFailure(output, command) {
     }
     return issue('proxy_unhealthy', output, command);
 }
+function positiveInteger(value) {
+    const parsed = typeof value === 'number' ? value : Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+/** Parse the language-independent JSON emitted by the Windows ownership probe. */
+function parseWindowsOwnershipSnapshot(raw) {
+    try {
+        const parsed = JSON.parse(raw.replace(/^\uFEFF/, '').trim());
+        const listeningValues = Array.isArray(parsed.listeningPids)
+            ? parsed.listeningPids
+            : parsed.listeningPids == null
+                ? []
+                : [parsed.listeningPids];
+        const processValues = Array.isArray(parsed.processes)
+            ? parsed.processes
+            : parsed.processes && typeof parsed.processes === 'object'
+                ? [parsed.processes]
+                : [];
+        const listeningPids = new Set();
+        for (const value of listeningValues) {
+            const pid = positiveInteger(value);
+            if (pid)
+                listeningPids.add(pid);
+        }
+        const parentByPid = new Map();
+        for (const value of processValues) {
+            if (!value || typeof value !== 'object')
+                continue;
+            const row = value;
+            const pid = positiveInteger(row.ProcessId);
+            const parentPid = positiveInteger(row.ParentProcessId);
+            if (pid && parentPid)
+                parentByPid.set(pid, parentPid);
+        }
+        return { listeningPids, parentByPid };
+    }
+    catch {
+        return null;
+    }
+}
+/** True only when a listening PID is the spawned process or one of its descendants. */
+function windowsSnapshotHasOwnedListener(snapshot, rootPid) {
+    if (!Number.isInteger(rootPid) || rootPid <= 0)
+        return false;
+    for (const listenerPid of snapshot.listeningPids) {
+        let current = listenerPid;
+        const visited = new Set();
+        while (current > 0 && !visited.has(current)) {
+            if (current === rootPid)
+                return true;
+            visited.add(current);
+            current = snapshot.parentByPid.get(current) ?? 0;
+        }
+    }
+    return false;
+}
+function descendantPids(rootPid, parentByPid) {
+    const descendants = new Set([rootPid]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [pid, parentPid] of parentByPid) {
+            if (descendants.has(pid) || !descendants.has(parentPid))
+                continue;
+            descendants.add(pid);
+            changed = true;
+        }
+    }
+    return descendants;
+}
+async function captureCommandOutput(command, args, options) {
+    return await new Promise((resolve) => {
+        let child;
+        try {
+            child = (0, child_process_1.spawn)(command, args, {
+                env: options.env ?? process.env,
+                stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: options.windowsHide,
+            });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        let output = '';
+        let size = 0;
+        let settled = false;
+        const maxBuffer = options.maxBuffer ?? 2 * 1024 * 1024;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+            settle(null);
+        }, options.timeoutMs);
+        timer.unref?.();
+        child.stdout?.on('data', (chunk) => {
+            if (settled)
+                return;
+            const value = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk;
+            size += Buffer.byteLength(value);
+            if (size > maxBuffer) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* already gone */ }
+                settle(null);
+                return;
+            }
+            output += value;
+        });
+        child.once('error', () => settle(null));
+        child.once('close', (code) => settle(code === 0 ? output : null));
+    });
+}
+async function readLinuxDescendantPids(rootPid) {
+    const descendants = new Set([rootPid]);
+    const pending = [rootPid];
+    while (pending.length > 0) {
+        const current = pending.shift();
+        try {
+            const taskIds = await fs_1.default.promises.readdir(`/proc/${current}/task`);
+            for (const taskId of taskIds) {
+                let raw;
+                try {
+                    raw = await fs_1.default.promises.readFile(`/proc/${current}/task/${taskId}/children`, 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                for (const value of raw.trim().split(/\s+/)) {
+                    const childPid = positiveInteger(value);
+                    if (!childPid || descendants.has(childPid))
+                        continue;
+                    descendants.add(childPid);
+                    pending.push(childPid);
+                }
+            }
+        }
+        catch {
+            // A process can exit while its descendants are enumerated. Omitting that
+            // branch is fail-closed for listener ownership.
+        }
+    }
+    return descendants;
+}
+async function readPosixParentMap() {
+    const args = ['-axo', 'pid=,ppid='];
+    const raw = await captureCommandOutput('/bin/ps', args, { timeoutMs: 2_000 })
+        ?? await captureCommandOutput('/usr/bin/ps', args, { timeoutMs: 2_000 });
+    const parentByPid = new Map();
+    if (raw === null)
+        return parentByPid;
+    for (const line of raw.split(/\r?\n/)) {
+        const match = line.match(/^\s*(\d+)\s+(\d+)\s*$/);
+        const pid = positiveInteger(match?.[1]);
+        const parentPid = positiveInteger(match?.[2]);
+        if (pid && parentPid)
+            parentByPid.set(pid, parentPid);
+    }
+    return parentByPid;
+}
+async function windowsProcessOwnsListeningPort(pid, port) {
+    const env = (0, win_spawn_1.windowsSpawnEnv)();
+    const systemRoot = (env.SystemRoot || env.windir || 'C:\\Windows').replace(/[\\/]$/, '');
+    const powershell = path_1.default.win32.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    // uv-managed console entry points are native trampoline processes on
+    // Windows. The Python process that owns the socket is their child, so an
+    // exact-PID netstat comparison rejects every legitimate managed install.
+    // Query both the listener owner and the process tree in one fail-closed
+    // snapshot, then accept only a transitive descendant of our spawned PID.
+    const command = [
+        "$ErrorActionPreference = 'Stop'",
+        `$listeningPids = @(Get-NetTCPConnection -State Listen -LocalPort ${port} | ForEach-Object { [int]$_.OwningProcess })`,
+        '$processes = @(Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId)',
+        '[pscustomobject]@{ listeningPids = $listeningPids; processes = $processes } | ConvertTo-Json -Compress -Depth 4',
+    ].join('; ');
+    const raw = await captureCommandOutput(powershell, [
+        '-NoLogo',
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        command,
+    ], {
+        // Keep this below the relay's connection deadline. A slow/ambiguous OS
+        // probe rejects the connection without ever releasing its queued headers.
+        timeoutMs: 2_500,
+        windowsHide: true,
+        env,
+        maxBuffer: 2 * 1024 * 1024,
+    });
+    if (raw === null)
+        return false;
+    const snapshot = parseWindowsOwnershipSnapshot(raw);
+    return !!snapshot && windowsSnapshotHasOwnedListener(snapshot, pid);
+}
+/**
+ * A successful HTTP probe is not proof that the process we spawned owns the
+ * endpoint: another local process can bind between the preflight probe and the
+ * child calling bind(2). Verify the listening socket belongs to the owned PID
+ * before provider credentials are routed to it.
+ */
+async function processOwnsListeningPort(pid, port) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    if (process.platform === 'linux') {
+        try {
+            const listeningInodes = new Set();
+            const tables = await Promise.all(['/proc/net/tcp', '/proc/net/tcp6'].map(async (table) => {
+                try {
+                    return await fs_1.default.promises.readFile(table, 'utf8');
+                }
+                catch {
+                    return '';
+                }
+            }));
+            for (const raw of tables) {
+                for (const line of raw.split(/\r?\n/).slice(1)) {
+                    const columns = line.trim().split(/\s+/);
+                    if (columns.length < 10 || columns[3] !== '0A')
+                        continue;
+                    const portHex = columns[1]?.split(':').pop();
+                    if (!portHex || Number.parseInt(portHex, 16) !== port)
+                        continue;
+                    if (columns[9])
+                        listeningInodes.add(columns[9]);
+                }
+            }
+            if (listeningInodes.size === 0)
+                return false;
+            const ownedPids = await readLinuxDescendantPids(pid);
+            for (const ownedPid of ownedPids) {
+                let fds;
+                try {
+                    fds = await fs_1.default.promises.readdir(`/proc/${ownedPid}/fd`);
+                }
+                catch {
+                    continue;
+                }
+                for (const fd of fds) {
+                    let target;
+                    try {
+                        target = await fs_1.default.promises.readlink(`/proc/${ownedPid}/fd/${fd}`);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const match = target.match(/^socket:\[(\d+)\]$/);
+                    if (match?.[1] && listeningInodes.has(match[1]))
+                        return true;
+                }
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (process.platform === 'win32') {
+        return await windowsProcessOwnsListeningPort(pid, port);
+    }
+    const args = [
+        '-nP',
+        `-iTCP:${port}`,
+        '-sTCP:LISTEN',
+        '-Fp',
+    ];
+    const output = await captureCommandOutput('/usr/sbin/lsof', args, { timeoutMs: 2_000 })
+        ?? await captureCommandOutput('lsof', args, { timeoutMs: 2_000 });
+    if (output === null)
+        return false;
+    const ownedPids = descendantPids(pid, await readPosixParentMap());
+    return output.split(/\r?\n/).some((line) => {
+        const listenerPid = positiveInteger(line.match(/^p(\d+)$/)?.[1]);
+        return !!listenerPid && ownedPids.has(listenerPid);
+    });
+}
 function providerLabel(provider) {
     return provider === 'codex' ? 'Codex' : 'Claude';
 }
@@ -260,6 +557,33 @@ function normalizeProviderKey(value) {
         return 'claude';
     return null;
 }
+/** Parse only the documented pass/fail signal; human prose is never authority. */
+function parseHeadroomDoctorRoutes(raw) {
+    const routes = { codex: false, claude: false };
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.checks))
+            return routes;
+        for (const value of parsed.checks) {
+            if (!value || typeof value !== 'object')
+                continue;
+            const check = value;
+            const provider = normalizeProviderKey(check.name);
+            if (!provider || check.status !== 'pass')
+                continue;
+            const summary = typeof check.summary === 'string' ? check.summary.trim().toLowerCase() : '';
+            // Some Headroom versions have emitted a successful diagnostic check with
+            // text such as "not routed". A contradictory result must fail closed.
+            if (/\bnot(?:\s+\w+){0,3}\s+routed\b|\bunrouted\b|\brouting\s+(?:is\s+)?(?:disabled|inactive|off)\b/.test(summary))
+                continue;
+            routes[provider] = true;
+        }
+    }
+    catch {
+        // Malformed/unknown doctor schemas are not evidence of a configured route.
+    }
+    return routes;
+}
 function num(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : 0;
@@ -295,18 +619,44 @@ class HeadroomManager {
     db;
     broadcast;
     availableProvidersSupplier;
+    processControl;
     proxy = null;
+    proxyTrustedPort = null;
+    proxyStart = null;
+    proxyStop = null;
+    proxyGeneration = 0;
+    shuttingDown = false;
+    shutdownPromise = null;
+    shutdownState = null;
+    lifecycleTail = Promise.resolve();
+    lifecycleCommands = new Map();
     proxyTail = '';
+    relayToken = (0, crypto_1.randomBytes)(32).toString('base64url');
+    relayAgent;
+    relayUpgradeTeardowns = new Set();
     routeDetectionCache = null;
     metricsCache = emptyMetricsState();
     metricsRefresh = null;
-    constructor(db, broadcast, availableProvidersSupplier = () => ['claude', 'codex']) {
+    constructor(db, broadcast, availableProvidersSupplier = () => ['claude', 'codex'], processControl = {}) {
         this.db = db;
         this.broadcast = broadcast;
         this.availableProvidersSupplier = availableProvidersSupplier;
+        this.processControl = processControl;
+        this.relayAgent = new http_1.default.Agent({ keepAlive: true, maxSockets: 16, maxFreeSockets: 4 });
+        // Agent#createConnection supports an asynchronous callback. Returning no
+        // socket prevents ClientRequest from writing queued headers/body on TCP
+        // connect; the socket is handed over only after the post-connect PID check.
+        this.relayAgent.createConnection = ((options, callback) => {
+            const expectedPort = Number(options.port);
+            void this.connectVerifiedBackend(expectedPort).then(({ socket }) => callback?.(null, socket), (err) => callback?.(err, undefined));
+            return undefined;
+        });
         this.syncRouting();
     }
     getState() {
+        return this.buildState(true);
+    }
+    buildState(refreshMetrics) {
         const persisted = this.readPersisted();
         const uvPath = this.resolveUvPath();
         const install = this.resolveHeadroomInstall(persisted.executablePath ?? null, !!persisted.ignoreSystemInstall);
@@ -315,10 +665,7 @@ class HeadroomManager {
         const installed = !!exe && !!version;
         const availableProviders = this.availableProviderRecord();
         const detectedRoutes = installed && exe ? this.detectProviderRoutes(exe) : providerRecord(persisted.detectedRoutes);
-        const activeProviders = {
-            codex: persisted.activeProviders?.codex ?? (availableProviders.codex && detectedRoutes.codex),
-            claude: persisted.activeProviders?.claude ?? (availableProviders.claude && detectedRoutes.claude),
-        };
+        const activeProviders = this.explicitActiveProviders(persisted);
         if (installed) {
             const shouldPersistInstall = persisted.installed !== true ||
                 persisted.executablePath !== exe ||
@@ -326,9 +673,7 @@ class HeadroomManager {
                 persisted.installSource !== install?.source ||
                 persisted.ignoreSystemInstall === true;
             const shouldPersistRoutes = persisted.detectedRoutes?.codex !== detectedRoutes.codex ||
-                persisted.detectedRoutes?.claude !== detectedRoutes.claude ||
-                persisted.activeProviders?.codex !== activeProviders.codex ||
-                persisted.activeProviders?.claude !== activeProviders.claude;
+                persisted.detectedRoutes?.claude !== detectedRoutes.claude;
             if (shouldPersistInstall || shouldPersistRoutes) {
                 this.updatePersisted({
                     installed: true,
@@ -337,11 +682,11 @@ class HeadroomManager {
                     installSource: install?.source ?? null,
                     ignoreSystemInstall: false,
                     detectedRoutes,
-                    activeProviders,
                 });
             }
         }
-        this.refreshMetricsInBackground();
+        if (refreshMetrics)
+            this.refreshMetricsInBackground();
         const learning = {
             enabled: persisted.learningEnabled ?? installed,
             ...this.readLearningBaseline(),
@@ -369,10 +714,357 @@ class HeadroomManager {
         };
     }
     async getFreshState() {
+        if (this.shuttingDown)
+            return this.shutdownState ?? this.buildState(false);
         await this.refreshMetrics();
         return this.getState();
     }
+    /**
+     * Stream a provider request through the stable desktop listener. A TCP
+     * connection to the backend is established first, then ownership is verified,
+     * and only then are headers/body (including provider credentials) written.
+     * A process that rebinds the backend port can therefore receive a TCP handshake
+     * but never a secret-bearing byte.
+     */
+    async handleRelayRequest(req, res) {
+        const upstreamPath = this.relayUpstreamPath(req.url);
+        if (!upstreamPath) {
+            this.writeRelayError(res, 404, 'Not Found');
+            return;
+        }
+        const backendPort = this.trustedBackendPort();
+        if (!backendPort) {
+            this.writeRelayError(res, 503, 'Headroom proxy is unavailable');
+            return;
+        }
+        const headers = this.filterRelayHttpHeaders(req.headers);
+        headers.host = `127.0.0.1:${backendPort}`;
+        let upstreamResponse = null;
+        let relaySettled = false;
+        const upstream = http_1.default.request({
+            host: '127.0.0.1',
+            port: backendPort,
+            method: req.method,
+            path: upstreamPath,
+            headers,
+            agent: this.relayAgent,
+        }, (response) => {
+            upstreamResponse = response;
+            if (res.destroyed) {
+                abortRelay(false);
+                return;
+            }
+            response.once('aborted', () => abortRelay(true));
+            response.once('error', () => abortRelay(true));
+            response.once('close', () => {
+                // IncomingMessage#close is also emitted after a fully-consumed response.
+                // Only an incomplete HTTP message is a broken backend stream.
+                if (!response.complete)
+                    abortRelay(true);
+            });
+            response.once('end', settleCleanRelay);
+            res.writeHead(response.statusCode ?? 502, this.filterRelayHttpHeaders(response.headers));
+            response.pipe(res);
+        });
+        const abortRelay = (notifyClient) => {
+            if (relaySettled)
+                return;
+            relaySettled = true;
+            req.unpipe(upstream);
+            upstreamResponse?.unpipe(res);
+            upstreamResponse?.destroy();
+            upstream.destroy();
+            if (!notifyClient || res.destroyed || res.writableFinished)
+                return;
+            if (!res.headersSent)
+                this.writeRelayError(res, 503, 'Headroom proxy request failed');
+            else
+                res.destroy();
+        };
+        const settleCleanRelay = () => {
+            if (req.complete &&
+                upstreamResponse?.complete &&
+                res.writableFinished)
+                relaySettled = true;
+        };
+        upstream.once('error', () => abortRelay(true));
+        upstream.once('close', () => {
+            if (!upstreamResponse)
+                abortRelay(true);
+        });
+        req.once('aborted', () => abortRelay(false));
+        req.once('error', () => abortRelay(false));
+        req.once('close', () => {
+            // A normal IncomingMessage closes after the complete request body. Do not
+            // confuse that with a client disconnect while a valid response streams.
+            if (!req.complete)
+                abortRelay(false);
+        });
+        req.once('end', settleCleanRelay);
+        res.once('error', () => abortRelay(false));
+        res.once('close', () => {
+            if (!res.writableFinished)
+                abortRelay(false);
+        });
+        res.once('finish', settleCleanRelay);
+        req.pipe(upstream);
+    }
+    /** WebSocket equivalent of handleRelayRequest (used by Codex streaming). */
+    async handleRelayUpgrade(req, clientSocket, head) {
+        const upstreamPath = this.relayUpstreamPath(req.url);
+        if (!upstreamPath) {
+            this.rejectRelayUpgrade(clientSocket, 404, 'Not Found');
+            return;
+        }
+        let backend;
+        try {
+            backend = await this.connectVerifiedBackend();
+        }
+        catch {
+            this.rejectRelayUpgrade(clientSocket, 503, 'Headroom proxy unavailable');
+            return;
+        }
+        if (clientSocket.destroyed) {
+            backend.socket.destroy();
+            return;
+        }
+        const raw = [`${req.method ?? 'GET'} ${upstreamPath} HTTP/${req.httpVersion}`];
+        const connectionTokens = this.connectionHeaderTokens(req.headers);
+        let wroteHost = false;
+        for (let i = 0; i < req.rawHeaders.length; i += 2) {
+            const name = req.rawHeaders[i];
+            const value = req.rawHeaders[i + 1];
+            if (!name || value === undefined)
+                continue;
+            const lower = name.toLowerCase();
+            if (lower === 'host') {
+                if (!wroteHost)
+                    raw.push(`Host: 127.0.0.1:${backend.port}`);
+                wroteHost = true;
+                continue;
+            }
+            if (lower === 'connection' ||
+                lower === 'proxy-connection' ||
+                lower === 'keep-alive' ||
+                lower === 'transfer-encoding' ||
+                lower === 'te' ||
+                lower === 'trailer' ||
+                lower === 'proxy-authenticate' ||
+                lower === 'proxy-authorization' ||
+                (connectionTokens.has(lower) && lower !== 'upgrade'))
+                continue;
+            raw.push(`${name}: ${value}`);
+        }
+        if (!wroteHost)
+            raw.push(`Host: 127.0.0.1:${backend.port}`);
+        raw.push('Connection: Upgrade');
+        raw.push('', '');
+        const backendSocket = backend.socket;
+        let clientEnded = false;
+        let backendEnded = false;
+        let clientClosed = false;
+        let backendClosed = false;
+        let tearingDown = false;
+        const cleanup = () => {
+            this.relayUpgradeTeardowns.delete(destroyBoth);
+            clientSocket.unpipe(backendSocket);
+            backendSocket.unpipe(clientSocket);
+            clientSocket.removeListener('error', destroyBoth);
+            backendSocket.removeListener('error', destroyBoth);
+            clientSocket.removeListener('end', onClientEnd);
+            backendSocket.removeListener('end', onBackendEnd);
+            clientSocket.removeListener('close', onClientClose);
+            backendSocket.removeListener('close', onBackendClose);
+        };
+        const destroyBoth = () => {
+            if (tearingDown)
+                return;
+            tearingDown = true;
+            cleanup();
+            if (!clientSocket.destroyed)
+                clientSocket.destroy();
+            if (!backendSocket.destroyed)
+                backendSocket.destroy();
+        };
+        const finishIfClosed = () => {
+            if (clientClosed && backendClosed)
+                cleanup();
+        };
+        const onClientEnd = () => {
+            clientEnded = true;
+            if (!backendSocket.destroyed && !backendSocket.writableEnded)
+                backendSocket.end();
+        };
+        const onBackendEnd = () => {
+            backendEnded = true;
+            if (!clientSocket.destroyed && !clientSocket.writableEnded)
+                clientSocket.end();
+        };
+        const onClientClose = () => {
+            clientClosed = true;
+            if (!clientEnded)
+                destroyBoth();
+            else
+                finishIfClosed();
+        };
+        const onBackendClose = () => {
+            backendClosed = true;
+            if (!backendEnded)
+                destroyBoth();
+            else
+                finishIfClosed();
+        };
+        this.relayUpgradeTeardowns.add(destroyBoth);
+        clientSocket.once('error', destroyBoth);
+        backendSocket.once('error', destroyBoth);
+        clientSocket.once('end', onClientEnd);
+        backendSocket.once('end', onBackendEnd);
+        clientSocket.once('close', onClientClose);
+        backendSocket.once('close', onBackendClose);
+        if (clientSocket.destroyed || backendSocket.destroyed) {
+            destroyBoth();
+            return;
+        }
+        try {
+            backendSocket.write(raw.join('\r\n'));
+            if (head.length > 0)
+                backendSocket.write(head);
+            // Preserve a clean half-close so a peer that has finished sending can
+            // still receive the other direction's final frames. Premature close or
+            // error takes the idempotent destroyBoth path above.
+            clientSocket.pipe(backendSocket, { end: false });
+            backendSocket.pipe(clientSocket, { end: false });
+        }
+        catch {
+            destroyBoth();
+        }
+    }
+    relayUpstreamPath(rawUrl) {
+        try {
+            const parsed = new URL(rawUrl || '/', 'http://127.0.0.1');
+            const fullPrefix = `${exports.HEADROOM_RELAY_PATH}/`;
+            let relative = parsed.pathname.startsWith(fullPrefix)
+                ? parsed.pathname.slice(exports.HEADROOM_RELAY_PATH.length)
+                : parsed.pathname;
+            const separator = relative.indexOf('/', 1);
+            const providedToken = separator === -1 ? relative.slice(1) : relative.slice(1, separator);
+            if (!providedToken || !(0, auth_1.safeEqual)(providedToken, this.relayToken))
+                return null;
+            relative = separator === -1 ? '/' : relative.slice(separator);
+            return `${relative}${parsed.search}`;
+        }
+        catch {
+            return null;
+        }
+    }
+    trustedBackendPort(expectedPort) {
+        const child = this.proxy;
+        const port = this.proxyTrustedPort;
+        if (!child || !port || !child.pid ||
+            (expectedPort !== undefined && port !== expectedPort) ||
+            child.exitCode != null || child.signalCode != null)
+            return null;
+        return port;
+    }
+    connectVerifiedBackend(expectedPort) {
+        const child = this.proxy;
+        const port = this.trustedBackendPort(expectedPort);
+        if (!child || !port || !child.pid)
+            return Promise.reject(new Error('Headroom proxy is not trusted'));
+        return new Promise((resolve, reject) => {
+            const socket = net_1.default.connect({ host: '127.0.0.1', port });
+            let settled = false;
+            const timer = setTimeout(() => fail(new Error('Headroom relay connect timed out')), RELAY_CONNECT_TIMEOUT_MS);
+            timer.unref?.();
+            const fail = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                socket.destroy();
+                reject(err);
+            };
+            socket.once('error', fail);
+            socket.once('connect', () => {
+                void (async () => {
+                    const ownsProxyPort = this.processControl.ownsProxyPort ?? processOwnsListeningPort;
+                    let listenerOwned = false;
+                    try {
+                        listenerOwned = await ownsProxyPort(child.pid, port);
+                    }
+                    catch { /* fail closed */ }
+                    if (settled)
+                        return;
+                    const owned = this.proxy === child &&
+                        this.proxyTrustedPort === port &&
+                        child.exitCode == null &&
+                        child.signalCode == null &&
+                        !!child.pid &&
+                        listenerOwned &&
+                        this.proxy === child &&
+                        this.proxyTrustedPort === port &&
+                        child.exitCode == null &&
+                        child.signalCode == null;
+                    if (!owned) {
+                        fail(new Error('Headroom backend ownership changed'));
+                        return;
+                    }
+                    settled = true;
+                    clearTimeout(timer);
+                    socket.removeListener('error', fail);
+                    resolve({ socket, port });
+                })().catch((err) => fail(err instanceof Error ? err : new Error(String(err))));
+            });
+        });
+    }
+    writeRelayError(res, status, message) {
+        if (res.headersSent || res.destroyed)
+            return;
+        res.writeHead(status, { 'content-type': 'application/json', connection: 'close' });
+        res.end(JSON.stringify({ error: message }));
+    }
+    connectionHeaderTokens(headers) {
+        const raw = headers.connection;
+        const values = Array.isArray(raw) ? raw : raw ? [raw] : [];
+        return new Set(values.flatMap((value) => value.split(',')).map((value) => value.trim().toLowerCase()).filter(Boolean));
+    }
+    filterRelayHttpHeaders(headers) {
+        const connectionTokens = this.connectionHeaderTokens(headers);
+        const filtered = {};
+        for (const [name, value] of Object.entries(headers)) {
+            const lower = name.toLowerCase();
+            if (value === undefined ||
+                lower === 'connection' ||
+                lower === 'proxy-connection' ||
+                lower === 'keep-alive' ||
+                lower === 'transfer-encoding' ||
+                lower === 'upgrade' ||
+                lower === 'te' ||
+                lower === 'trailer' ||
+                lower === 'proxy-authenticate' ||
+                lower === 'proxy-authorization' ||
+                connectionTokens.has(lower))
+                continue;
+            filtered[name] = value;
+        }
+        return filtered;
+    }
+    rejectRelayUpgrade(socket, status, message) {
+        if (socket.destroyed)
+            return;
+        socket.end(`HTTP/1.1 ${status} ${message}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+    }
+    destroyRelayTransports() {
+        this.relayAgent.destroy();
+        for (const teardown of [...this.relayUpgradeTeardowns])
+            teardown();
+    }
     async install() {
+        return this.serializeLifecycle(() => this.installLocked());
+    }
+    async installLocked() {
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         const uv = this.resolveUvPath();
         if (!uv) {
             const failure = issue('uv_missing_or_corrupt');
@@ -395,6 +1087,8 @@ class HeadroomManager {
         this.emit('installing', logs[0]);
         this.emit('installing', logs[1]);
         const pythonResult = await this.runCommand(uv, plan.pythonInstallArgs, plan.env, logs);
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         if (pythonResult.code !== 0) {
             const failure = classifyInstallFailure(logs.join('\n'), pythonCommand);
             this.updatePersisted({ lastIssue: failure });
@@ -406,6 +1100,8 @@ class HeadroomManager {
         this.emit('installing', logs[logs.length - 2]);
         this.emit('installing', logs[logs.length - 1]);
         const result = await this.runCommand(uv, plan.toolInstallArgs, plan.env, logs);
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         if (result.code !== 0) {
             const failure = classifyInstallFailure(logs.join('\n'), installCommand);
             this.updatePersisted({ lastIssue: failure });
@@ -429,11 +1125,20 @@ class HeadroomManager {
             lastIssue: null,
         });
         await this.enableOutputLearning(exe, logs);
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         this.emit('installed', `Headroom ${version} installed`);
         await this.refreshMetrics();
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         return { ok: true, state: this.getState(), logs };
     }
     async activate(provider) {
+        return this.serializeLifecycle(() => this.activateLocked(provider));
+    }
+    async activateLocked(provider) {
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         const state = this.getState();
         if (!state.installed || !state.executablePath) {
             const failure = issue('not_installed');
@@ -443,13 +1148,18 @@ class HeadroomManager {
         const proxy = await this.ensureProxy();
         if (!proxy.ok)
             return proxy;
+        // The start promise can settle just before shutdown/deactivation invalidates
+        // its generation. Re-check the owned runtime synchronously before persisting
+        // a provider route so a resolved promise cannot resurrect activation.
+        if (this.shuttingDown || !this.isProxyAvailable())
+            return this.cancelledProxyStart();
         const current = this.readPersisted();
-        const activeProviders = { ...current.activeProviders, [provider]: true };
-        this.updatePersisted({ activeProviders, lastIssue: null });
+        const activeProviders = { ...this.explicitActiveProviders(current), [provider]: true };
+        this.updatePersisted({ ...this.activationPatch(activeProviders), lastIssue: null });
         this.syncRouting();
         if (!this.verifyProviderRoute(provider)) {
             const rolledBack = { ...activeProviders, [provider]: false };
-            this.updatePersisted({ activeProviders: rolledBack, lastIssue: issue('provider_route_failed') });
+            this.updatePersisted({ ...this.activationPatch(rolledBack), lastIssue: issue('provider_route_failed') });
             this.syncRouting();
             return { ok: false, state: this.getState(), issue: issue('provider_route_failed') };
         }
@@ -457,22 +1167,34 @@ class HeadroomManager {
         return { ok: true, state: this.getState() };
     }
     async deactivate(provider) {
+        return this.serializeLifecycle(() => this.deactivateLocked(provider));
+    }
+    async deactivateLocked(provider) {
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         const current = this.readPersisted();
-        const activeProviders = { ...current.activeProviders, [provider]: false };
-        this.updatePersisted({ activeProviders, lastIssue: null });
+        const activeProviders = { ...this.explicitActiveProviders(current), [provider]: false };
+        this.updatePersisted({ ...this.activationPatch(activeProviders), lastIssue: null });
         this.syncRouting();
         if (!activeProviders.codex && !activeProviders.claude)
-            this.stopProxy();
+            await this.stopProxy();
         this.emit('installed', `${provider} Headroom route disabled`);
         return { ok: true, state: this.getState() };
     }
     async uninstall() {
+        return this.serializeLifecycle(() => this.uninstallLocked());
+    }
+    async uninstallLocked() {
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         const before = this.getState();
         this.updatePersisted({
-            activeProviders: { codex: false, claude: false },
+            ...this.activationPatch({ codex: false, claude: false }),
             lastIssue: null,
         });
-        this.stopProxy();
+        await this.stopProxy();
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         this.syncRouting();
         if (!before.installed && !before.executablePath) {
             this.updatePersisted({
@@ -480,7 +1202,7 @@ class HeadroomManager {
                 version: null,
                 executablePath: null,
                 installSource: null,
-                activeProviders: { codex: false, claude: false },
+                ...this.activationPatch({ codex: false, claude: false }),
                 detectedRoutes: { codex: false, claude: false },
                 lastIssue: null,
             });
@@ -493,7 +1215,7 @@ class HeadroomManager {
                 executablePath: null,
                 installSource: null,
                 ignoreSystemInstall: true,
-                activeProviders: { codex: false, claude: false },
+                ...this.activationPatch({ codex: false, claude: false }),
                 detectedRoutes: { codex: false, claude: false },
                 lastIssue: null,
             });
@@ -516,6 +1238,8 @@ class HeadroomManager {
             UV_CACHE_DIR: uvCacheDir(),
             UV_NO_PROGRESS: '1',
         }, logs);
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         const stillInstalled = fileExists(path_1.default.join(uvBinDir(), headroomExeName()));
         if (result.code !== 0 || stillInstalled) {
             const failure = issue('uninstall_failed', logs.join('\n'), command);
@@ -528,7 +1252,7 @@ class HeadroomManager {
             version: null,
             executablePath: null,
             installSource: null,
-            activeProviders: { codex: false, claude: false },
+            ...this.activationPatch({ codex: false, claude: false }),
             detectedRoutes: { codex: false, claude: false },
             lastIssue: null,
         });
@@ -536,18 +1260,65 @@ class HeadroomManager {
         return { ok: true, state: this.getState(), logs };
     }
     async setPort(port) {
+        return this.serializeLifecycle(() => this.setPortLocked(port));
+    }
+    async setPortLocked(port) {
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
         if (!Number.isInteger(port) || port < 1 || port > 65535) {
             const failure = issue('proxy_port_busy', 'Port must be an integer between 1 and 65535.');
             return { ok: false, state: this.getState(), issue: failure };
         }
+        const previous = this.readPersisted();
+        const previousPort = this.validPort(previous.port);
         const active = this.getState().activeProviders;
-        this.stopProxy();
-        this.updatePersisted({ port, lastIssue: null });
-        this.syncRouting();
-        if (active.codex || active.claude) {
-            return this.ensureProxy();
+        await this.stopProxy();
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
+        if (!active.codex && !active.claude) {
+            this.updatePersisted({ port, lastIssue: null });
+            return { ok: true, state: this.getState() };
         }
-        return { ok: true, state: this.getState() };
+        // Keep routing disabled while the replacement is only a candidate. No job
+        // may send provider credentials to it until our owned child is healthy.
+        this.updatePersisted({
+            port,
+            ...this.activationPatch({ codex: false, claude: false }),
+            lastIssue: null,
+        });
+        const candidate = await this.ensureProxy();
+        if (this.shuttingDown)
+            return this.cancelledProxyStart();
+        if (candidate.ok) {
+            this.updatePersisted({ ...this.activationPatch(active), lastIssue: null });
+            return { ok: true, state: this.getState() };
+        }
+        // Roll back the entire transition, including the old owned proxy. If even
+        // that cannot be restored, remain fail-closed instead of persisting an
+        // active route with no healthy service behind it.
+        this.updatePersisted({
+            port: previousPort,
+            ...this.activationPatch({ codex: false, claude: false }),
+            lastIssue: candidate.issue ?? issue('proxy_unhealthy'),
+        });
+        const restored = await this.ensureProxy();
+        if (restored.ok) {
+            this.updatePersisted({
+                ...this.activationPatch(active),
+                lastIssue: candidate.issue ?? issue('proxy_unhealthy'),
+            });
+        }
+        else {
+            this.updatePersisted({
+                ...this.activationPatch({ codex: false, claude: false }),
+                lastIssue: restored.issue ?? candidate.issue ?? issue('proxy_unhealthy'),
+            });
+        }
+        return {
+            ok: false,
+            state: this.getState(),
+            issue: candidate.issue ?? issue('proxy_unhealthy'),
+        };
     }
     diagnostics() {
         const state = this.getState();
@@ -566,66 +1337,214 @@ class HeadroomManager {
             learning: state.learning,
             metrics: state.metrics,
             routing: {
-                codex: state.activeProviders.codex ? `OPENAI_BASE_URL=http://127.0.0.1:${state.port}/v1` : null,
-                claude: state.activeProviders.claude ? `ANTHROPIC_BASE_URL=http://127.0.0.1:${state.port}` : null,
+                codex: state.activeProviders.codex
+                    ? `OPENAI_BASE_URL=${this.relayDiagnosticBaseUrl() ?? `http://127.0.0.1:${state.port}`}/v1`
+                    : null,
+                claude: state.activeProviders.claude
+                    ? `ANTHROPIC_BASE_URL=${this.relayDiagnosticBaseUrl() ?? `http://127.0.0.1:${state.port}`}`
+                    : null,
             },
         };
     }
     async startActiveProxyOnBoot() {
+        return this.serializeLifecycle(() => this.startActiveProxyOnBootLocked());
+    }
+    async startActiveProxyOnBootLocked() {
+        if (this.shuttingDown)
+            return;
         const active = this.getState().activeProviders;
         this.syncRouting();
         if (active.codex || active.claude) {
             const result = await this.ensureProxy();
+            if (this.shuttingDown)
+                return;
             if (!result.ok) {
+                // Never keep provider credentials/prompts routed to a process we did not
+                // spawn and therefore cannot authenticate. The user can retry activation
+                // after resolving the port conflict.
+                this.updatePersisted({
+                    ...this.activationPatch({ codex: false, claude: false }),
+                    lastIssue: result.issue ?? issue('proxy_unhealthy'),
+                });
                 console.warn('[headroom] boot proxy start failed:', result.issue);
             }
         }
     }
+    serializeLifecycle(operation) {
+        const run = this.lifecycleTail.then(operation, operation);
+        this.lifecycleTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
     async ensureProxy() {
+        if (this.proxyStop)
+            await this.proxyStop;
         const state = this.getState();
         if (!state.installed || !state.executablePath) {
             const failure = issue('not_installed');
             return { ok: false, state, issue: failure };
         }
-        if (this.isProxyRunning())
+        if (this.shuttingDown) {
+            const failure = issue('proxy_unhealthy', 'Headroom proxy startup was cancelled during shutdown.');
+            return { ok: false, state, issue: failure };
+        }
+        if (this.proxyStart) {
+            if (this.proxyStart.port === state.port)
+                return this.proxyStart.promise;
+            await this.stopProxy();
+            if (this.shuttingDown)
+                return this.cancelledProxyStart();
+        }
+        if (this.isProxyAvailable(state.port))
             return { ok: true, state };
-        if (await this.adoptHealthyProxy(state.port)) {
-            return { ok: true, state: this.getState() };
+        if (this.isProxyRunning())
+            await this.stopProxy();
+        const generation = ++this.proxyGeneration;
+        const promise = this.startProxy(state, state.executablePath, generation);
+        this.proxyStart = { generation, port: state.port, promise };
+        const clear = () => {
+            if (this.proxyStart?.promise === promise)
+                this.proxyStart = null;
+        };
+        void promise.then(clear, clear);
+        return promise;
+    }
+    async startProxy(state, executablePath, generation) {
+        // A healthy endpoint is still not proof that the process belongs to this
+        // Specrails instance. Adopting it would route provider auth and prompts to an
+        // unauthenticated port occupant. Treat every pre-existing listener as a hard
+        // conflict and only trust the child created below.
+        if (await this.probeProxyHealthy(state.port)) {
+            if (!this.isProxyGenerationCurrent(generation))
+                return this.cancelledProxyStart();
+            const failure = issue('proxy_port_busy');
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure };
         }
+        if (!this.isProxyGenerationCurrent(generation))
+            return this.cancelledProxyStart();
         const args = ['proxy', '--host', '127.0.0.1', '--port', String(state.port)];
-        const command = `${state.executablePath} ${args.join(' ')}`;
+        const command = `${executablePath} ${args.join(' ')}`;
         this.emit('starting-proxy', `Starting proxy on ${state.port}`);
         this.proxyTail = '';
-        const child = (0, child_process_1.spawn)(state.executablePath, args, {
-            env: {
-                ...process.env,
-                HEADROOM_PORT: String(state.port),
-                HEADROOM_OUTPUT_SHAPER: '1',
-                HEADROOM_LEARN: state.learning.enabled ? '1' : '0',
-                HEADROOM_SAVINGS_PROFILE: process.env.HEADROOM_SAVINGS_PROFILE ?? 'agent-90',
-                HEADROOM_MODE: process.env.HEADROOM_MODE ?? 'token',
-            },
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
+        let child;
+        try {
+            child = (this.processControl.spawnProxy ?? child_process_1.spawn)(executablePath, args, {
+                env: {
+                    ...process.env,
+                    HEADROOM_PORT: String(state.port),
+                    HEADROOM_OUTPUT_SHAPER: '1',
+                    HEADROOM_LEARN: state.learning.enabled ? '1' : '0',
+                    HEADROOM_SAVINGS_PROFILE: process.env.HEADROOM_SAVINGS_PROFILE ?? 'agent-90',
+                    HEADROOM_MODE: process.env.HEADROOM_MODE ?? 'token',
+                },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            const failure = classifyProxyFailure(err instanceof Error ? err.message : String(err), command);
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure };
+        }
         this.proxy = child;
+        this.proxyTrustedPort = null;
+        this.syncRouting();
         child.stdout?.on('data', (chunk) => { this.proxyTail += chunk.toString(); this.trimProxyTail(); });
         child.stderr?.on('data', (chunk) => { this.proxyTail += chunk.toString(); this.trimProxyTail(); });
-        child.on('close', () => {
-            if (this.proxy === child)
-                this.proxy = null;
+        const invalidateOwnedProxy = () => {
+            if (this.proxy !== child)
+                return;
+            this.destroyRelayTransports();
+            this.proxy = null;
+            this.proxyTrustedPort = null;
+            this.syncRouting();
+        };
+        // `spawn()` reports ENOENT/EACCES asynchronously. Without this listener the
+        // EventEmitter contract turns a recoverable activation failure into an
+        // uncaught exception that terminates the desktop sidecar.
+        child.on('error', (err) => {
+            this.proxyTail += `${err.message}\n`;
+            this.trimProxyTail();
+            invalidateOwnedProxy();
         });
-        const healthy = await this.waitForProxyHealthy(state.port, 6000);
+        // `exit` invalidates routing immediately; `close` is retained as the final
+        // fallback for unusual ChildProcess implementations and stdio teardown.
+        child.on('exit', invalidateOwnedProxy);
+        child.on('close', invalidateOwnedProxy);
+        const healthy = await this.waitForProxyHealthy(state.port, 6000, () => this.isProxyGenerationCurrent(generation));
+        if (!this.isProxyGenerationCurrent(generation)) {
+            await this.discardProxyChild(child);
+            return this.cancelledProxyStart();
+        }
         if (!healthy) {
             const failure = classifyProxyFailure(this.proxyTail, command);
-            this.stopProxy();
+            await this.discardProxyChild(child);
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure };
+        }
+        const ownsProxyPort = this.processControl.ownsProxyPort ?? processOwnsListeningPort;
+        const ownedEndpointIsCurrent = async () => {
+            if (!this.isOwnedProxyCurrent(child, generation) || !child.pid)
+                return false;
+            let listenerOwned = false;
+            try {
+                listenerOwned = await ownsProxyPort(child.pid, state.port);
+            }
+            catch { /* fail closed */ }
+            if (!listenerOwned)
+                return false;
+            return this.isOwnedProxyCurrent(child, generation);
+        };
+        if (!(await ownedEndpointIsCurrent())) {
+            const failure = issue('proxy_port_busy', 'A healthy endpoint answered, but the Specrails-owned Headroom process does not own the listening socket.', command);
+            await this.discardProxyChild(child);
             this.updatePersisted({ lastIssue: failure });
             this.emit('failed', failure.title);
             return { ok: false, state: this.getState(), issue: failure };
         }
-        this.updatePersisted({ lastIssue: null });
         await this.refreshMetrics();
+        if (!this.isProxyGenerationCurrent(generation)) {
+            await this.discardProxyChild(child);
+            return this.cancelledProxyStart();
+        }
+        if (!(await ownedEndpointIsCurrent())) {
+            const failure = issue('proxy_unhealthy', 'The owned Headroom proxy exited during startup.', command);
+            await this.discardProxyChild(child);
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure };
+        }
+        this.proxyTrustedPort = state.port;
+        this.updatePersisted({ lastIssue: null });
         return { ok: true, state: this.getState() };
     }
+    cancelledProxyStart() {
+        const failure = issue('proxy_unhealthy', 'Headroom proxy startup was superseded by a newer lifecycle operation.');
+        const state = this.shuttingDown && this.shutdownState
+            ? this.shutdownState
+            : this.getState();
+        return { ok: false, state, issue: failure };
+    }
+    isProxyGenerationCurrent(generation) {
+        return !this.shuttingDown && this.proxyGeneration === generation;
+    }
+    isOwnedProxyCurrent(child, generation) {
+        return this.isProxyGenerationCurrent(generation) &&
+            this.proxy === child &&
+            child.exitCode == null &&
+            child.signalCode == null;
+    }
+    async discardProxyChild(child) {
+        if (this.proxy === child) {
+            this.destroyRelayTransports();
+            this.proxy = null;
+            this.proxyTrustedPort = null;
+            this.syncRouting();
+        }
+        await this.terminateProxyChild(child);
+    }
     resolveUvPath() {
         for (const p of bundledUvCandidates()) {
             if (fileExists(p))
@@ -657,7 +1576,7 @@ class HeadroomManager {
         if (this.routeDetectionCache?.executablePath === exe && this.routeDetectionCache.expiresAt > now) {
             return this.routeDetectionCache.routes;
         }
-        const routes = { codex: false, claude: false };
+        let routes = { codex: false, claude: false };
         try {
             const state = this.readPersisted();
             const probe = (0, child_process_1.spawnSync)(exe, ['doctor', '--json', '--port', String(this.validPort(state.port))], {
@@ -666,16 +1585,8 @@ class HeadroomManager {
                 env: process.env,
             });
             const raw = `${probe.stdout ?? ''}`.trim();
-            const parsed = raw ? JSON.parse(raw) : {};
-            for (const check of parsed.checks ?? []) {
-                const provider = normalizeProviderKey(check.name);
-                if (!provider)
-                    continue;
-                const routed = check.status === 'pass' || String(check.summary ?? '').toLowerCase().includes('routed');
-                if (routed)
-                    routes[provider] = true;
-            }
-            this.routeDetectionCache = { executablePath: exe, expiresAt: now + 10_000, routes, raw: parsed };
+            routes = probe.status === 0 && raw ? parseHeadroomDoctorRoutes(raw) : routes;
+            this.routeDetectionCache = { executablePath: exe, expiresAt: now + 10_000, routes, raw };
         }
         catch {
             this.routeDetectionCache = { executablePath: exe, expiresAt: now + 10_000, routes, raw: null };
@@ -718,6 +1629,8 @@ class HeadroomManager {
             HEADROOM_OUTPUT_SHAPER: '1',
             HEADROOM_SAVINGS_PROFILE: process.env.HEADROOM_SAVINGS_PROFILE ?? 'agent-90',
         }, logs);
+        if (this.shuttingDown)
+            return;
         if (result.code === 0) {
             this.updatePersisted({
                 learningEnabled: true,
@@ -734,6 +1647,8 @@ class HeadroomManager {
         });
     }
     refreshMetricsInBackground() {
+        if (this.shuttingDown)
+            return;
         const state = this.getMetricsPrereqState();
         if (!state.installed || !state.executablePath)
             return;
@@ -757,10 +1672,7 @@ class HeadroomManager {
             port: this.validPort(persisted.port),
             availableProviders,
             detectedRoutes,
-            activeProviders: {
-                codex: persisted.activeProviders?.codex ?? (availableProviders.codex && detectedRoutes.codex),
-                claude: persisted.activeProviders?.claude ?? (availableProviders.claude && detectedRoutes.claude),
-            },
+            activeProviders: this.explicitActiveProviders(persisted),
         };
     }
     async refreshMetrics() {
@@ -845,17 +1757,60 @@ class HeadroomManager {
         return JSON.parse(result.output);
     }
     async readProxyStats(port) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 2500);
-        try {
-            const res = await fetch(`http://127.0.0.1:${port}/stats?cached=1`, { signal: controller.signal });
-            if (!res.ok)
-                return null;
-            return await res.json();
-        }
-        finally {
-            clearTimeout(timer);
-        }
+        if (!this.isProxyAvailable(port))
+            return null;
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (value, err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (err)
+                    reject(err);
+                else
+                    resolve(value);
+            };
+            const request = http_1.default.request({
+                host: '127.0.0.1',
+                port,
+                method: 'GET',
+                path: '/stats?cached=1',
+                headers: { host: `127.0.0.1:${port}` },
+                agent: this.relayAgent,
+            }, (response) => {
+                if ((response.statusCode ?? 500) < 200 || (response.statusCode ?? 500) >= 300) {
+                    response.resume();
+                    finish(null);
+                    return;
+                }
+                const chunks = [];
+                let size = 0;
+                response.on('data', (chunk) => {
+                    const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                    size += value.length;
+                    if (size > 2 * 1024 * 1024) {
+                        request.destroy(new Error('Headroom stats response exceeded 2 MB'));
+                        return;
+                    }
+                    chunks.push(value);
+                });
+                response.on('end', () => {
+                    try {
+                        finish(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+                    }
+                    catch (err) {
+                        finish(null, err instanceof Error ? err : new Error(String(err)));
+                    }
+                });
+            });
+            const timer = setTimeout(() => {
+                request.destroy(new Error('Headroom stats request timed out'));
+            }, 2_500);
+            timer.unref?.();
+            request.once('error', (err) => finish(null, err));
+            request.end();
+        });
     }
     decorateMetrics(metrics, activeProviders, availableProviders, detectedRoutes) {
         return {
@@ -882,11 +1837,29 @@ class HeadroomManager {
         };
     }
     async runCommand(command, args, extraEnv, logs) {
+        if (this.shuttingDown)
+            return { code: null };
         return new Promise((resolve) => {
-            const child = (0, child_process_1.spawn)(command, args, {
-                env: { ...process.env, ...extraEnv },
-                stdio: ['ignore', 'pipe', 'pipe'],
-            });
+            let child;
+            try {
+                child = (0, child_process_1.spawn)(command, args, {
+                    env: { ...process.env, ...extraEnv },
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+            }
+            catch (err) {
+                logs.push(err instanceof Error ? err.message : String(err));
+                resolve({ code: null });
+                return;
+            }
+            let settled = false;
+            const settle = (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve({ code });
+            };
+            this.trackLifecycleCommand(child, () => settle(null));
             child.stdout?.on('data', (chunk) => {
                 for (const line of chunk.toString().split(/\r?\n/)) {
                     if (!line)
@@ -905,32 +1878,45 @@ class HeadroomManager {
             });
             child.on('error', (err) => {
                 logs.push(err.message);
-                resolve({ code: null });
+                settle(null);
             });
-            child.on('close', (code) => resolve({ code }));
+            child.on('close', (code) => settle(code));
+            if (this.shuttingDown) {
+                settle(null);
+                void this.terminateProxyChild(child);
+            }
         });
     }
     async runCommandCapture(command, args, extraEnv, timeoutMs) {
+        if (this.shuttingDown)
+            return { code: null, output: '' };
         return new Promise((resolve) => {
             let output = '';
             let settled = false;
-            const child = (0, child_process_1.spawn)(command, args, {
-                env: { ...process.env, ...extraEnv },
-                stdio: ['ignore', 'pipe', 'pipe'],
-            });
+            let child;
+            try {
+                child = (0, child_process_1.spawn)(command, args, {
+                    env: { ...process.env, ...extraEnv },
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+            }
+            catch (err) {
+                resolve({ code: null, output: err instanceof Error ? err.message : String(err) });
+                return;
+            }
+            let timer = null;
             const settle = (code) => {
                 if (settled)
                     return;
                 settled = true;
-                clearTimeout(timer);
+                if (timer)
+                    clearTimeout(timer);
                 resolve({ code, output });
             };
-            const timer = setTimeout(() => {
-                try {
-                    child.kill('SIGTERM');
-                }
-                catch { /* ignore */ }
+            this.trackLifecycleCommand(child, () => settle(null));
+            timer = setTimeout(() => {
                 settle(null);
+                void this.terminateProxyChild(child);
             }, timeoutMs);
             child.stdout?.on('data', (chunk) => { output += chunk.toString(); });
             child.stderr?.on('data', (chunk) => { output += chunk.toString(); });
@@ -939,23 +1925,68 @@ class HeadroomManager {
                 settle(null);
             });
             child.on('close', (code) => settle(code));
+            if (this.shuttingDown) {
+                settle(null);
+                void this.terminateProxyChild(child);
+            }
+        });
+    }
+    trackLifecycleCommand(child, cancel) {
+        this.lifecycleCommands.set(child, { cancel });
+        child.once('close', () => {
+            this.lifecycleCommands.delete(child);
         });
     }
-    async waitForProxyHealthy(port, timeoutMs) {
+    /** Cancel/terminate every command, including children added while draining. */
+    async drainLifecycleCommands() {
+        const attempted = new Set();
+        while (true) {
+            const pending = [...this.lifecycleCommands.entries()]
+                .filter(([child]) => !attempted.has(child));
+            if (pending.length === 0)
+                return;
+            for (const [child, control] of pending) {
+                attempted.add(child);
+                control.cancel();
+            }
+            await Promise.all(pending.map(([child]) => this.terminateProxyChild(child)));
+        }
+    }
+    async waitForProxyHealthy(port, timeoutMs, isCurrent = () => true) {
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
-            try {
-                const res = await fetch(`http://127.0.0.1:${port}/livez`);
-                if (res.ok)
-                    return true;
-            }
-            catch {
-                // retry until timeout
-            }
+            if (!isCurrent())
+                return false;
+            const requestTimeoutMs = Math.max(1, Math.min(PROXY_HEALTH_REQUEST_TIMEOUT_MS, deadline - Date.now()));
+            const healthy = await this.fetchProxyHealth(port, requestTimeoutMs);
+            if (!isCurrent())
+                return false;
+            if (healthy)
+                return true;
+            if (!isCurrent())
+                return false;
             await new Promise((r) => setTimeout(r, 250));
         }
         return false;
     }
+    async probeProxyHealthy(port) {
+        return this.fetchProxyHealth(port, PROXY_HEALTH_REQUEST_TIMEOUT_MS);
+    }
+    async fetchProxyHealth(port, timeoutMs) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        timeout.unref?.();
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/livez`, { signal: controller.signal });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
     verifyProviderRoute(provider) {
         const state = this.getState();
         return provider === 'codex'
@@ -963,27 +1994,124 @@ class HeadroomManager {
             : !!state.activeProviders.claude && state.port > 0;
     }
     isProxyRunning() {
-        return !!this.proxy && !this.proxy.killed && this.proxy.exitCode == null;
-    }
-    async adoptHealthyProxy(port) {
-        if (!await this.waitForProxyHealthy(port, 750))
-            return false;
-        await this.refreshMetrics();
-        this.updatePersisted({ lastIssue: null });
-        return true;
+        return !!this.proxy && this.proxy.exitCode == null && this.proxy.signalCode == null;
     }
-    isProxyAvailable() {
-        return this.isProxyRunning() || this.metricsCache.proxyStatsAvailable;
+    isProxyAvailable(port = this.validPort(this.readPersisted().port)) {
+        return this.proxyTrustedPort === port && this.isProxyRunning();
     }
-    stopProxy() {
+    async stopProxy() {
+        this.proxyGeneration += 1;
+        this.proxyStart = null;
+        this.destroyRelayTransports();
         const child = this.proxy;
         this.proxy = null;
-        if (child && !child.killed) {
+        this.proxyTrustedPort = null;
+        this.syncRouting();
+        const previousStop = this.proxyStop;
+        const stop = (async () => {
+            if (previousStop)
+                await previousStop;
+            if (child)
+                await this.terminateProxyChild(child);
+        })();
+        this.proxyStop = stop;
+        try {
+            await stop;
+        }
+        finally {
+            if (this.proxyStop === stop)
+                this.proxyStop = null;
+        }
+    }
+    /**
+     * Synchronously close lifecycle admission while other process owners drain.
+     * The proxy remains alive until shutdown() so already-routed children can be
+     * terminated before their transport disappears.
+     */
+    beginShutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.syncRouting();
+        const state = this.buildState(false);
+        this.shutdownState = { ...state, proxyRunning: false, proxyPid: null };
+    }
+    /** Stop the owned proxy before the app tears down its DB and HTTP server. */
+    shutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        this.beginShutdown();
+        const shutdown = this.finishShutdown();
+        this.shutdownPromise = shutdown;
+        return shutdown;
+    }
+    async finishShutdown() {
+        // Runtime-only fail closed; persisted activation remains so a clean restart
+        // can start a fresh owned proxy.
+        const persistedPort = this.validPort(this.readPersisted().port);
+        (0, headroom_routing_1.setHeadroomRoutingState)({
+            port: this.routingClientPort(persistedPort),
+            relayBaseUrl: this.relayBaseUrl(),
+            activeProviders: { codex: false, claude: false },
+        });
+        // Routed provider children inherited the stable desktop endpoint. Stop and
+        // await them before the app can release that listener; until then the relay
+        // remains bound and rejects any untrusted backend instead of exposing a
+        // reusable Headroom port.
+        const stoppingProxy = this.stopProxy();
+        await Promise.all([
+            (0, headroom_routing_1.terminateHeadroomRoutedChildren)(),
+            stoppingProxy,
+            this.drainLifecycleCommands(),
+        ]);
+        // A lifecycle action may still be unwinding an aborted health/metrics
+        // request. Keep the desktop DB alive until it has observed `shuttingDown`
+        // and completed; queued actions fail at their locked-method guard.
+        await this.lifecycleTail;
+        // Defense in depth for future lifecycle operations: no child may survive a
+        // completed shutdown even if a new await is added after an initial guard.
+        await this.drainLifecycleCommands();
+        await this.stopProxy();
+    }
+    terminateProxyChild(child) {
+        if (!child.pid || child.exitCode != null || child.signalCode != null)
+            return Promise.resolve();
+        const pid = child.pid;
+        const killTree = this.processControl.killTree ?? win_spawn_1.treeKillSafe;
+        return new Promise((resolve) => {
+            let closed = false;
+            let killTimer = null;
+            let deadlineTimer = null;
+            const finish = () => {
+                if (closed)
+                    return;
+                closed = true;
+                if (killTimer)
+                    clearTimeout(killTimer);
+                if (deadlineTimer)
+                    clearTimeout(deadlineTimer);
+                child.removeListener('close', finish);
+                resolve();
+            };
+            child.once('close', finish);
             try {
-                child.kill('SIGTERM');
+                killTree(pid, 'SIGTERM', () => { });
             }
-            catch { /* ignore */ }
-        }
+            catch { /* gone */ }
+            killTimer = setTimeout(() => {
+                if (closed)
+                    return;
+                try {
+                    killTree(pid, 'SIGKILL', () => { });
+                }
+                catch { /* gone */ }
+            }, 2_000);
+            killTimer.unref?.();
+            // A D-state process may never emit close. Do not wedge app shutdown after
+            // escalation; the OS will reclaim it when possible.
+            deadlineTimer = setTimeout(finish, 2_500);
+            deadlineTimer.unref?.();
+        });
     }
     trimProxyTail() {
         if (this.proxyTail.length > 32_000)
@@ -992,6 +2120,40 @@ class HeadroomManager {
     validPort(value) {
         return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 65535 ? Number(value) : DEFAULT_PORT;
     }
+    relayBaseUrl() {
+        const origin = this.processControl.relayOrigin;
+        if (!origin)
+            return undefined;
+        try {
+            const parsed = new URL(origin);
+            if (parsed.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(parsed.hostname)) {
+                return undefined;
+            }
+            return `${parsed.origin}${exports.HEADROOM_RELAY_PATH}/${this.relayToken}`;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    relayDiagnosticBaseUrl() {
+        const relay = this.relayBaseUrl();
+        if (!relay)
+            return undefined;
+        return `${new URL(relay).origin}${exports.HEADROOM_RELAY_PATH}/<redacted>`;
+    }
+    routingClientPort(backendPort) {
+        const relay = this.relayBaseUrl();
+        if (!relay)
+            return backendPort;
+        try {
+            const parsed = new URL(relay);
+            const port = Number(parsed.port || (parsed.protocol === 'https:' ? 443 : 80));
+            return this.validPort(port);
+        }
+        catch {
+            return backendPort;
+        }
+    }
     readPersisted() {
         const raw = (0, desktop_db_1.getDesktopSetting)(this.db, STATE_KEY);
         if (!raw)
@@ -1013,13 +2175,40 @@ class HeadroomManager {
         (0, desktop_db_1.setDesktopSetting)(this.db, STATE_KEY, JSON.stringify(next));
         this.syncRouting();
     }
+    explicitActiveProviders(persisted) {
+        const activation = persisted.activation;
+        if (activation?.version !== exports.HEADROOM_ACTIVATION_SCHEMA_VERSION ||
+            activation.source !== exports.HEADROOM_ACTIVATION_SOURCE)
+            return { codex: false, claude: false };
+        return {
+            codex: activation.activeProviders?.codex === true,
+            claude: activation.activeProviders?.claude === true,
+        };
+    }
+    activationPatch(activeProviders) {
+        const normalized = providerRecord(activeProviders);
+        return {
+            // Retain the old field for diagnostics/downgrades, but the versioned
+            // envelope below is the sole routing authority.
+            activeProviders: normalized,
+            activation: {
+                version: exports.HEADROOM_ACTIVATION_SCHEMA_VERSION,
+                source: exports.HEADROOM_ACTIVATION_SOURCE,
+                activeProviders: normalized,
+            },
+        };
+    }
     syncRouting() {
         const persisted = this.readPersisted();
+        const port = this.validPort(persisted.port);
+        const trustedRuntimeAvailable = this.proxyTrustedPort === port && this.isProxyRunning();
+        const explicitActiveProviders = this.explicitActiveProviders(persisted);
         (0, headroom_routing_1.setHeadroomRoutingState)({
-            port: this.validPort(persisted.port),
-            activeProviders: {
-                codex: !!persisted.activeProviders?.codex,
-                claude: !!persisted.activeProviders?.claude,
+            port: this.routingClientPort(port),
+            relayBaseUrl: this.relayBaseUrl(),
+            activeProviders: this.shuttingDown || !trustedRuntimeAvailable ? { codex: false, claude: false } : {
+                codex: explicitActiveProviders.codex,
+                claude: explicitActiveProviders.claude,
             },
         });
     }