sneakoscope 9.2.4 → 9.2.6

package/README.md

@@ -22,7 +22,7 @@ Proof-first orchestration for Codex CLI, ChatGPT Desktop, AI coding agents, mult
 Sneakoscope Codex (`sks`) is an open-source trust layer for Codex CLI and ChatGPT Desktop. It coordinates bounded AI coding agents, records machine-verifiable evidence, preserves project memory, and blocks release claims that are not supported by current tests or artifacts. Search visibility outcomes are measured separately; SKS does not promise rankings or traffic.
 <!-- END SKS SEARCH VISIBILITY MARKETING -->
 
-This README documents package **SKS 9.2.4** — its own identity, read from `package.json` and subject to release-gate verification, not advice about what to install.
+This README documents package **SKS 9.2.6** — its own identity, read from `package.json` and subject to release-gate verification, not advice about what to install.
 
 Use the official latest stable SKS and Codex CLI releases. The Codex compatibility SSOT is always the **current latest stable** host; capability probes measure what that host can actually do. Product docs do not crown a fixed `0.x.y` string as SSOT (release pins and schema directories are measured artifacts for the current package, not a permanent product version claim). Menu Bar / Center induce updates to the latest stable build. Run `sks update-check` for what is installed and read the capability report for what is supported. Install SSOT is npm `sneakoscope@latest`; PATH `sks` and Menu Bar stamped generation must match that version or gates fail. It resolves managed SKS skills from the authoritative global install, preserves a runnable Naruto child slot when `max_threads=2`, and keeps Menu Bar repair transactional so stamped generations remain verifiable. Naruto uses stable opt-in multi-agent V2 when the host exposes it (Codex official multi-agent wrap-only; SKS does not reimplement a parallel runtime). Local code search is mode-separated (`sks search files|text|structure|symbol|context`); `context` is answered by the compiled TriWiki Context Graph (`context-graph.json` is exhaustive authority; `context-pack.json` and managed `AGENTS.md` are bounded projections) — see [docs/architecture/context-graph.md](https://github.com/mandarange/Sneakoscope-Codex/blob/main/docs/architecture/context-graph.md) and [docs/PRODUCT-CONTRACT.md](https://github.com/mandarange/Sneakoscope-Codex/blob/main/docs/PRODUCT-CONTRACT.md). See [CHANGELOG.md](https://github.com/mandarange/Sneakoscope-Codex/blob/main/CHANGELOG.md).
 

package/crates/sks-core/Cargo.lock

@@ -259,7 +259,7 @@ dependencies = [
 
 [[package]]
 name = "sks-core"
-version = "9.2.4"
+version = "9.2.6"
 dependencies = [
  "globset",
  "grep-matcher",

package/crates/sks-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sks-core"
-version = "9.2.4"
+version = "9.2.6"
 edition = "2021"
 
 [dependencies]

package/dist/commands/doctor.js

@@ -8,7 +8,7 @@ import { getCodexInfo } from '../core/codex-adapter.js';
 import { rustInfo } from '../core/rust-accelerator.js';
 import { codexAppIntegrationStatus } from '../core/codex-app.js';
 import { desktopBridgeStatusV3 } from '../core/codex-lb/desktop-controller-v3.js';
-import { repairDoctorDesktopBridgeCatalog } from '../core/doctor/desktop-bridge-catalog-repair.js';
+import { readDesktopBridgeUnreachableUpstreamEvidence, repairDoctorDesktopBridgeCatalog } from '../core/doctor/desktop-bridge-catalog-repair.js';
 import { inspectCodexConfigReadability } from '../core/codex/codex-config-readability.js';
 import { inspectOAuthCallbackPortConflict, oauthCallbackDoctorGuidance } from '../core/codex/oauth-callback-port-diagnostic.js';
 import { inventoryCodexPermissionProfiles } from '../core/codex/codex-permission-profiles.js';
@@ -72,6 +72,14 @@ export async function inspectDoctorDesktopBridgeStatus(input = {}, deps = {}) {
         const blockers = expected && status.readiness.ready !== true
             ? (status.readiness.blockers || []).map(String).filter(Boolean)
             : [];
+        const recoveryActions = (status.recovery_actions || []).map(String).filter(Boolean);
+        if (expected && status.management?.managed === true) {
+            const evidence = await (deps.desktopBridgeUpstreamEvidenceImpl || readDesktopBridgeUnreachableUpstreamEvidence)(home).catch(() => null);
+            if (evidence) {
+                blockers.push(`desktop_bridge_upstream_unreachable:${evidence.code}`);
+                recoveryActions.push('Run `sks doctor --fix` (or `sks bridge repair`) to restart the Desktop Bridge and re-resolve its upstream address.');
+            }
+        }
         return {
             schema: 'sks.doctor-desktop-bridge.v1',
             ok: blockers.length === 0,
@@ -82,7 +90,7 @@ export async function inspectDoctorDesktopBridgeStatus(input = {}, deps = {}) {
             providers: status.providers,
             blockers,
             warnings: (status.readiness.warnings || []).map(String).filter(Boolean),
-            recovery_actions: (status.recovery_actions || []).map(String).filter(Boolean)
+            recovery_actions: recoveryActions
         };
     }
     catch (error) {

package/dist/config/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "sks.skills-manifest.v1",
-  "package_version": "9.2.4",
+  "package_version": "9.2.6",
   "skills": [
     {
       "canonical_name": "sks",

package/dist/core/codex/codex-feature-flags.js

@@ -2,9 +2,9 @@ export const MANAGED_CODEX_FEATURE_FLAGS = Object.freeze(['hooks', 'fast_mode',
 export const REMOVED_CODEX_FEATURE_FLAGS = Object.freeze([
     'fast_mode_ui',
     'codex_hooks',
+    'multi_agent_mode',
     'remote_control',
     'codex_git_commit',
     'plugin_hooks',
-    'js_repl',
-    'multi_agent_mode'
+    'js_repl'
 ]);

package/dist/core/codex-control/codex-current-collab-agent-real-probe.js

@@ -3,7 +3,10 @@ import path from 'node:path';
 import { findCodexBinary } from '../codex-adapter.js';
 import { ensureDir, runProcess } from '../fsx.js';
 import { codexCurrentCoreProbeTail, skippedCodexCurrentCoreProbe } from './codex-current-core-real-probes.js';
-const CURRENT_COLLAB_TOOLS = ['spawnAgent', 'sendInput', 'resumeAgent', 'wait', 'closeAgent'];
+const CURRENT_COLLAB_TOOLS = [
+    'spawnAgent', 'sendInput', 'resumeAgent', 'wait', 'closeAgent',
+    'sendMessage', 'followupTask', 'interruptAgent', 'listAgents'
+];
 export async function runCodexCurrentCollabAgentToolSchemaRealProbe(input) {
     const started = Date.now();
     const codexBin = input.codexBin || await findCodexBinary();
@@ -23,7 +26,7 @@ export async function runCodexCurrentCollabAgentToolSchemaRealProbe(input) {
         ? schema.definitions.CollabAgentTool.enum.map(String)
         : [];
     const currentNamesPresent = CURRENT_COLLAB_TOOLS.every((name) => tools.includes(name));
-    const legacyInterruptAbsent = !tools.includes('interruptAgent') && !tools.includes('interrupt_agent');
+    const legacyInterruptAbsent = !tools.includes('interrupt_agent');
     const collabItemPresent = JSON.stringify(schema?.definitions?.ThreadItem || {}).includes('collabAgentToolCall')
         || JSON.stringify(schema || {}).includes('collabAgentToolCall');
     const processExitedSuccessfully = result.code === 0;

package/dist/core/codex-lb/desktop-bridge/http-forward.js

@@ -5,7 +5,7 @@ import { pipeline } from 'node:stream/promises';
 import { BRIDGE_OFFICIAL_ROUTE_ID } from '../bridge-contracts.js';
 import { buildOfficialPassthroughHeaders, buildProviderUpstreamHeaders, rewriteResponseHeaders } from './header-policy.js';
 import { createDesktopBridgeRejectionLogger } from './rejection-log.js';
-import { resolveAndBindDesktopBridgeRouteContext, resolveCodexSessionIdentity, resolveDesktopBridgeTarget, safeBridgeErrorCode, singleBridgeHeader } from './security.js';
+import { ensureDesktopBridgeRemoteTarget, isUnreachableUpstreamError, refreshDesktopBridgeRemoteTarget, resolveAndBindDesktopBridgeRouteContext, resolveCodexSessionIdentity, resolveDesktopBridgeTarget, safeBridgeErrorCode, singleBridgeHeader } from './security.js';
 import { desktopBridgeListenOrigin } from './state.js';
 import { DesktopBridgeError } from './types.js';
 const MAX_UPSTREAM_ERROR_BODY_BYTES = 1024 * 1024;
@@ -251,6 +251,8 @@ class StalePooledSocketFailure extends Error {
         this.reason = reason;
     }
 }
+class UnreachableUpstreamFailure extends StalePooledSocketFailure {
+}
 export async function forwardHttp(req, res, config, prepared, authenticatedLocalBaseUrl = desktopBridgeListenOrigin(config)) {
     try {
         const request = prepared || await prepareDesktopBridgeRequest(req, config);
@@ -264,6 +266,7 @@ export async function forwardHttp(req, res, config, prepared, authenticatedLocal
         const upstreamBaseUrl = official ? remote.baseUrl : provider.base_url;
         if (!official && !request.credential)
             throw new DesktopBridgeError('bridge_provider_credential_invalid');
+        await ensureDesktopBridgeRemoteTarget(remote, config.remoteLookup);
         const target = resolveDesktopBridgeTarget(req.url, remote);
         const transport = remote.secure ? https : http;
         const headers = official
@@ -303,6 +306,13 @@ export async function forwardHttp(req, res, config, prepared, authenticatedLocal
             req.once('aborted', abort);
             res.once('close', abort);
             upstream.once('error', (error) => {
+                if (!responseStarted && isUnreachableUpstreamError(error)) {
+                    if (replayable && canReplay) {
+                        finish(new UnreachableUpstreamFailure(error));
+                        return;
+                    }
+                    void refreshDesktopBridgeRemoteTarget(remote, config.remoteLookup);
+                }
                 if (!responseStarted && replayable && !useFreshConnection && isStalePooledSocketFailure(upstream, error)) {
                     finish(new StalePooledSocketFailure(error));
                     return;
@@ -405,16 +415,30 @@ export async function forwardHttp(req, res, config, prepared, authenticatedLocal
                 if (!(error instanceof StalePooledSocketFailure) || remainingReplays <= 0)
                     throw error;
                 remainingReplays -= 1;
-                if (!useFreshConnection) {
+                if (error instanceof UnreachableUpstreamFailure) {
+                    const staleAddress = remote.address;
+                    await refreshDesktopBridgeRemoteTarget(remote, config.remoteLookup);
                     agent.destroy();
-                    upstreamAgents.delete(`${remote.secure ? 'https' : 'http'}:${remote.address}:${remote.port}`);
+                    upstreamAgents.delete(`${remote.secure ? 'https' : 'http'}:${staleAddress}:${remote.port}`);
+                    logHttpRejection({
+                        code: `bridge_upstream_unreachable_rerouted:${underlyingErrorCode(error.reason) || 'unknown'}`,
+                        transport: 'http',
+                        ...(req.method === undefined ? {} : { method: req.method }),
+                        ...(req.url === undefined ? {} : { url: req.url }),
+                    });
+                }
+                else {
+                    if (!useFreshConnection) {
+                        agent.destroy();
+                        upstreamAgents.delete(`${remote.secure ? 'https' : 'http'}:${remote.address}:${remote.port}`);
+                    }
+                    logHttpRejection({
+                        code: `bridge_upstream_socket_stale_replayed:${underlyingErrorCode(error.reason) || 'unknown'}`,
+                        transport: 'http',
+                        ...(req.method === undefined ? {} : { method: req.method }),
+                        ...(req.url === undefined ? {} : { url: req.url }),
+                    });
                 }
-                logHttpRejection({
-                    code: `bridge_upstream_socket_stale_replayed:${underlyingErrorCode(error.reason) || 'unknown'}`,
-                    transport: 'http',
-                    ...(req.method === undefined ? {} : { method: req.method }),
-                    ...(req.url === undefined ? {} : { url: req.url }),
-                });
                 useFreshConnection = true;
                 const backoffIndex = TRANSIENT_UPSTREAM_REPLAY_LIMIT - remainingReplays - 1;
                 const backoffMs = TRANSIENT_UPSTREAM_REPLAY_BACKOFF_MS[Math.max(0, backoffIndex)]

package/dist/core/codex-lb/desktop-bridge/security.js

@@ -7,6 +7,7 @@ const MIN_HIGH_PORT = 49_152;
 const MAX_PORT = 65_535;
 const MAX_SESSION_PINS = 10_000;
 const sessionPinMutationQueues = new WeakMap();
+const remoteRefreshStates = new WeakMap();
 const FORBIDDEN_REMOTE_ADDRESSES = new net.BlockList();
 FORBIDDEN_REMOTE_ADDRESSES.addSubnet('0.0.0.0', 8, 'ipv4');
 FORBIDDEN_REMOTE_ADDRESSES.addSubnet('10.0.0.0', 8, 'ipv4');
@@ -369,7 +370,7 @@ const defaultLookup = async (hostname) => {
         return { address: row.address, family: row.family };
     });
 };
-export async function resolveDesktopBridgeRemoteTarget(raw, lookup = defaultLookup) {
+export async function resolveDesktopBridgeRemoteTarget(raw, lookup = defaultLookup, options = {}) {
     const remote = validateRemoteUrl(raw);
     const hostname = stripIpv6Brackets(remote.hostname);
     const family = net.isIP(hostname);
@@ -388,7 +389,9 @@ export async function resolveDesktopBridgeRemoteTarget(raw, lookup = defaultLook
     if (!loopback && addresses.some((row) => FORBIDDEN_REMOTE_ADDRESSES.check(row.address, row.family === 4 ? 'ipv4' : 'ipv6'))) {
         throw new DesktopBridgeError('bridge_remote_dns_private_address');
     }
-    const selected = addresses[0];
+    const selected = (options.preferAddress ? addresses.find((row) => row.address === options.preferAddress) : undefined)
+        ?? addresses.find((row) => row.address !== options.avoidAddress)
+        ?? addresses[0];
     if (!selected)
         throw new DesktopBridgeError('bridge_remote_dns_empty');
     const target = {
@@ -396,8 +399,85 @@ export async function resolveDesktopBridgeRemoteTarget(raw, lookup = defaultLook
         port: Number(remote.port || (remote.protocol === 'https:' ? 443 : 80)), secure: remote.protocol === 'https:',
         address: selected.address, family: selected.family, ...(family ? {} : { tlsServername: hostname }),
     };
+    remoteRefreshStates.set(target, { resolvedAt: Date.now(), lastRefreshAt: null, inflight: null });
     return target;
 }
+function deferredRemoteTarget(remote, hostname) {
+    return {
+        baseUrl: remote.toString().replace(/\/$/, ''), origin: remote.origin, hostname,
+        port: Number(remote.port || (remote.protocol === 'https:' ? 443 : 80)), secure: remote.protocol === 'https:',
+        address: '0.0.0.0', family: 4, ...(net.isIP(hostname) ? {} : { tlsServername: hostname }),
+        unresolved: true,
+    };
+}
+async function resolveOrDeferRemoteTarget(raw, lookup) {
+    try {
+        return await resolveDesktopBridgeRemoteTarget(raw, lookup);
+    }
+    catch (error) {
+        if (!(error instanceof DesktopBridgeError) || error.code !== 'bridge_remote_dns_failed')
+            throw error;
+        const remote = validateRemoteUrl(raw);
+        return deferredRemoteTarget(remote, stripIpv6Brackets(remote.hostname));
+    }
+}
+const UNREACHABLE_UPSTREAM_ERROR_CODES = new Set([
+    'EHOSTUNREACH', 'ENETUNREACH', 'ENETDOWN', 'EHOSTDOWN', 'EADDRNOTAVAIL', 'ECONNREFUSED', 'ETIMEDOUT',
+    'ERR_TLS_CERT_ALTNAME_INVALID',
+]);
+export function isUnreachableUpstreamError(error) {
+    if (error instanceof DesktopBridgeError)
+        return error.code === 'bridge_upstream_connect_timeout';
+    const code = error?.code;
+    return typeof code === 'string' && UNREACHABLE_UPSTREAM_ERROR_CODES.has(code);
+}
+export const REMOTE_REFRESH_COOLDOWN_MS = 5_000;
+export const REMOTE_TARGET_TTL_MS = 5 * 60_000;
+export async function refreshDesktopBridgeRemoteTarget(remote, lookup = defaultLookup, reason = 'unreachable') {
+    if (net.isIP(remote.hostname))
+        return false;
+    const state = remoteRefreshStates.get(remote) ?? { resolvedAt: null, lastRefreshAt: null, inflight: null };
+    if (state.inflight)
+        return state.inflight;
+    if (state.lastRefreshAt !== null && Date.now() - state.lastRefreshAt < REMOTE_REFRESH_COOLDOWN_MS)
+        return false;
+    const inflight = (async () => {
+        let resolvedAt = state.resolvedAt;
+        try {
+            const fresh = await resolveDesktopBridgeRemoteTarget(remote.baseUrl, lookup, reason === 'stale'
+                ? { preferAddress: remote.address }
+                : reason === 'unreachable' ? { avoidAddress: remote.address } : {});
+            const changed = remote.unresolved === true || fresh.address !== remote.address || fresh.family !== remote.family;
+            remote.address = fresh.address;
+            remote.family = fresh.family;
+            delete remote.unresolved;
+            resolvedAt = Date.now();
+            return changed;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            remoteRefreshStates.set(remote, { resolvedAt, lastRefreshAt: Date.now(), inflight: null });
+        }
+    })();
+    remoteRefreshStates.set(remote, { ...state, inflight });
+    return inflight;
+}
+export async function ensureDesktopBridgeRemoteTarget(remote, lookup = defaultLookup, ttlMs = REMOTE_TARGET_TTL_MS) {
+    if (remote.unresolved) {
+        await refreshDesktopBridgeRemoteTarget(remote, lookup, 'unresolved');
+        if (remote.unresolved)
+            throw new DesktopBridgeError('bridge_remote_dns_failed');
+        return;
+    }
+    if (net.isIP(remote.hostname))
+        return;
+    const state = remoteRefreshStates.get(remote);
+    if (state?.resolvedAt !== null && state?.resolvedAt !== undefined && Date.now() - state.resolvedAt >= ttlMs) {
+        await refreshDesktopBridgeRemoteTarget(remote, lookup, 'stale');
+    }
+}
 async function prepareProvider(provider, lookup) {
     const remote = validateRemoteUrl(provider.base_url);
     const hostname = stripIpv6Brackets(remote.hostname);
@@ -414,7 +494,7 @@ async function prepareProvider(provider, lookup) {
             },
         };
     }
-    const target = await resolveDesktopBridgeRemoteTarget(provider.base_url, lookup);
+    const target = await resolveOrDeferRemoteTarget(provider.base_url, lookup);
     return { ...provider, base_url: target.baseUrl, remote: target };
 }
 function assertRegistryAndPolicy(config, registry) {
@@ -525,9 +605,9 @@ export async function prepareDesktopBridgeConfig(config, lookup = defaultLookup)
     }));
     const providers = Object.fromEntries(entries);
     const officialRemote = config.officialPassthrough
-        ? await resolveDesktopBridgeRemoteTarget(config.officialPassthrough.baseUrl, lookup)
+        ? await resolveOrDeferRemoteTarget(config.officialPassthrough.baseUrl, lookup)
         : null;
-    return { ...config, providers, officialRemote };
+    return { ...config, providers, officialRemote, remoteLookup: lookup };
 }
 export function validatePreparedDesktopBridgeConfig(config) {
     validateDesktopBridgeConfig(config);

package/dist/core/codex-lb/desktop-bridge/websocket-forward.js

@@ -5,7 +5,7 @@ import { BRIDGE_OFFICIAL_ROUTE_ID } from '../bridge-contracts.js';
 import { buildOfficialPassthroughWebSocketHeaders, buildProviderWebSocketHeaders } from './header-policy.js';
 import { createDesktopBridgeRejectionLogger } from './rejection-log.js';
 import { rewriteLocationHeader } from './location-rewrite.js';
-import { desktopBridgeOfficialPassthroughEnabled, resolveAndBindDesktopBridgeRouteContext, resolveCodexSessionIdentity, resolveDesktopBridgeTarget, safeBridgeErrorCode, singleBridgeHeader, canonicalSessionId } from './security.js';
+import { desktopBridgeOfficialPassthroughEnabled, ensureDesktopBridgeRemoteTarget, isUnreachableUpstreamError, refreshDesktopBridgeRemoteTarget, resolveAndBindDesktopBridgeRouteContext, resolveCodexSessionIdentity, resolveDesktopBridgeTarget, safeBridgeErrorCode, singleBridgeHeader, canonicalSessionId } from './security.js';
 import { desktopBridgeListenOrigin } from './state.js';
 import { DESKTOP_BRIDGE_DIAGNOSTIC_PROTOCOL, DesktopBridgeError, } from './types.js';
 const MAX_HEAD = 64 * 1024;
@@ -152,71 +152,103 @@ export async function forwardWebSocket(req, client, head, config, authenticatedL
         writeUpgradeFailure(client, new DesktopBridgeError(official ? 'bridge_official_passthrough_unavailable' : 'bridge_provider_route_unavailable'), req);
         return;
     }
-    const upstreamBaseUrl = official ? remote.baseUrl : provider.base_url;
-    const target = resolveDesktopBridgeTarget(req.url, remote);
-    const upstream = remote.secure
-        ? tls.connect({ host: remote.address, port: remote.port, ...(remote.tlsServername ? { servername: remote.tlsServername } : {}) })
-        : net.connect({ host: remote.address, port: remote.port, family: remote.family });
+    const pin = remote;
+    const upstreamBaseUrl = official ? pin.baseUrl : provider.base_url;
+    const target = resolveDesktopBridgeTarget(req.url, pin);
+    try {
+        await ensureDesktopBridgeRemoteTarget(pin, config.remoteLookup);
+    }
+    catch (error) {
+        writeUpgradeFailure(client, error, req);
+        return;
+    }
     const key = String(req.headers['sec-websocket-key'] || '');
     const requestedProtocol = String(req.headers['sec-websocket-protocol'] || '').split(',')[0]?.trim() || null;
-    let connected = false;
-    let response = Buffer.alloc(0);
-    const timer = setTimeout(() => upstream.destroy(new DesktopBridgeError('bridge_upstream_connect_timeout')), config.connectTimeoutMs);
-    timer.unref();
-    const fail = (error) => { clearTimeout(timer); if (!connected)
-        writeUpgradeFailure(client, error, req);
-    else
-        client.destroy(); };
-    const onConnected = () => {
-        connected = true;
-        clearTimeout(timer);
-        upstream.setNoDelay(true);
-        upstream.setKeepAlive(true, 30_000);
-        const clientSocket = client;
-        if (typeof clientSocket.setKeepAlive === 'function')
-            clientSocket.setKeepAlive(true, 30_000);
-        const headers = official
-            ? buildOfficialPassthroughWebSocketHeaders(req.headers, target.host)
-            : buildProviderWebSocketHeaders(req.headers, { providerId: provider.provider_id, authTransport: provider.auth_transport, credential: credential }, target.host);
-        upstream.write([`${req.method || 'GET'} ${target.pathname}${target.search} HTTP/1.1`, ...serializeHeaders(headers), '', ''].join('\r\n'));
-        if (head.length)
-            upstream.write(head);
-        const onData = (chunk) => {
-            response = Buffer.concat([response, chunk]);
-            if (response.length > MAX_HEAD) {
-                upstream.destroy(new DesktopBridgeError('bridge_websocket_response_headers_too_large'));
-                return;
-            }
-            const boundary = response.indexOf('\r\n\r\n');
-            if (boundary < 0)
-                return;
-            upstream.off('data', onData);
-            const raw = response.subarray(0, boundary);
-            const remaining = response.subarray(boundary + 4);
-            try {
-                validateUpgrade(raw, key, requestedProtocol);
-                client.write(rewriteUpgradeResponseHead(raw, upstreamBaseUrl, authenticatedLocalBaseUrl));
-                if (remaining.length)
-                    client.write(remaining);
-            }
-            catch (error) {
-                upstream.destroy(error instanceof Error ? error : undefined);
-                return;
-            }
-            client.pipe(upstream);
-            upstream.pipe(client);
+    connectUpstreamForUpgrade(1);
+    function connectUpstreamForUpgrade(retriesLeft) {
+        const upstream = pin.secure
+            ? tls.connect({ host: pin.address, port: pin.port, ...(pin.tlsServername ? { servername: pin.tlsServername } : {}) })
+            : net.connect({ host: pin.address, port: pin.port, family: pin.family });
+        let connected = false;
+        let retrying = false;
+        let response = Buffer.alloc(0);
+        const timer = setTimeout(() => upstream.destroy(new DesktopBridgeError('bridge_upstream_connect_timeout')), config.connectTimeoutMs);
+        timer.unref();
+        const fail = (error) => { clearTimeout(timer); if (!connected)
+            writeUpgradeFailure(client, error, req);
+        else
+            client.destroy(); };
+        const onConnected = () => {
+            connected = true;
+            clearTimeout(timer);
+            upstream.setNoDelay(true);
+            upstream.setKeepAlive(true, 30_000);
+            const clientSocket = client;
+            if (typeof clientSocket.setKeepAlive === 'function')
+                clientSocket.setKeepAlive(true, 30_000);
+            const headers = official
+                ? buildOfficialPassthroughWebSocketHeaders(req.headers, target.host)
+                : buildProviderWebSocketHeaders(req.headers, { providerId: provider.provider_id, authTransport: provider.auth_transport, credential: credential }, target.host);
+            upstream.write([`${req.method || 'GET'} ${target.pathname}${target.search} HTTP/1.1`, ...serializeHeaders(headers), '', ''].join('\r\n'));
+            if (head.length)
+                upstream.write(head);
+            const onData = (chunk) => {
+                response = Buffer.concat([response, chunk]);
+                if (response.length > MAX_HEAD) {
+                    upstream.destroy(new DesktopBridgeError('bridge_websocket_response_headers_too_large'));
+                    return;
+                }
+                const boundary = response.indexOf('\r\n\r\n');
+                if (boundary < 0)
+                    return;
+                upstream.off('data', onData);
+                const raw = response.subarray(0, boundary);
+                const remaining = response.subarray(boundary + 4);
+                try {
+                    validateUpgrade(raw, key, requestedProtocol);
+                    client.write(rewriteUpgradeResponseHead(raw, upstreamBaseUrl, authenticatedLocalBaseUrl));
+                    if (remaining.length)
+                        client.write(remaining);
+                }
+                catch (error) {
+                    upstream.destroy(error instanceof Error ? error : undefined);
+                    return;
+                }
+                client.pipe(upstream);
+                upstream.pipe(client);
+            };
+            upstream.on('data', onData);
         };
-        upstream.on('data', onData);
-    };
-    if (remote.secure)
-        upstream.once('secureConnect', onConnected);
-    else
-        upstream.once('connect', onConnected);
-    upstream.once('error', (error) => fail(error));
-    upstream.once('close', () => { clearTimeout(timer); if (!client.destroyed)
-        client.end(); });
-    client.once('error', () => upstream.destroy());
-    client.once('close', () => upstream.destroy());
+        if (pin.secure)
+            upstream.once('secureConnect', onConnected);
+        else
+            upstream.once('connect', onConnected);
+        upstream.once('error', (error) => {
+            if (!connected && isUnreachableUpstreamError(error)) {
+                const refreshed = refreshDesktopBridgeRemoteTarget(pin, config.remoteLookup);
+                if (retriesLeft > 0 && !client.destroyed) {
+                    retrying = true;
+                    clearTimeout(timer);
+                    const cause = error?.code;
+                    logWebSocketRejection({
+                        code: `bridge_upstream_unreachable_rerouted:${typeof cause === 'string' && /^[A-Za-z0-9_]{1,64}$/.test(cause) ? cause : 'unknown'}`,
+                        transport: 'websocket',
+                        ...(req.method === undefined ? {} : { method: req.method }),
+                        ...(req.url === undefined ? {} : { url: req.url }),
+                    });
+                    void refreshed.then(() => { if (!client.destroyed)
+                        connectUpstreamForUpgrade(retriesLeft - 1); });
+                    return;
+                }
+            }
+            fail(error);
+        });
+        upstream.once('close', () => { clearTimeout(timer); if (retrying)
+            return; if (!client.destroyed)
+            client.end(); });
+        client.once('error', () => upstream.destroy());
+        client.once('close', () => upstream.destroy());
+    }
 }
 function encodeClientFrame(opcode, payload) {
     if (payload.length > 125)

package/dist/core/codex-lb/desktop-service.js

@@ -14,6 +14,7 @@ import { captureCodexAuthSnapshot } from './desktop-auth-invariant.js';
 import { applyOfficialModelPassthrough, bridgeRoutePolicyPath, writeBridgeRoutingPolicy } from './provider-route-policy.js';
 import { desktopBridgeRuntimeVersion, desktopBridgeRuntimeVersionStale } from './desktop-bridge/state.js';
 import { PACKAGE_VERSION } from '../version.js';
+import { BRIDGE_OFFICIAL_ROUTE_ID } from './bridge-contracts.js';
 import { DESKTOP_BRIDGE_ALLOWED_PATH_PREFIXES, DESKTOP_BRIDGE_LAUNCHD_LABEL, desktopBridgeConfigGeneration, desktopBridgeLaunchdPlistPath, desktopBridgeProcessExists, desktopBridgeStatePath, getDesktopBridgeStatus, preflightDesktopBridge, readDesktopBridgeState, safeBridgeErrorCode, writeDesktopBridgeLaunchdPlist, selectAvailableDesktopBridgePort, startPreparedDesktopBridge, DESKTOP_BRIDGE_STATE_SCHEMA, DESKTOP_BRIDGE_OFFICIAL_UPSTREAM_BASE_URL, DesktopBridgeError, } from './desktop-bridge/index.js';
 export const DEFAULT_DESKTOP_BRIDGE_HOST = '127.0.0.1';
 export const DEFAULT_DESKTOP_BRIDGE_PORT = 49_152;
@@ -465,17 +466,15 @@ async function autoApplyOfficialModelsAtServe(runtime, home, options) {
         home,
         codexLbRegistered: desktopBridgeCodexLbRegistered(settings.provider_registry.providers),
     });
-    if (mode !== 'passthrough')
+    const converged = applyOfficialModelPassthrough(settings.route_policy, { mode });
+    if (converged.policy_generation === settings.route_policy.policy_generation)
         return;
-    const flipped = applyOfficialModelPassthrough(settings.route_policy, { mode: 'passthrough' });
-    if (flipped.policy_generation === settings.route_policy.policy_generation)
-        return;
-    const nextSettings = { ...settings, route_policy: flipped };
+    const nextSettings = { ...settings, route_policy: converged };
     await writeDesktopBridgeServiceSettings(options.settingsPath || desktopBridgeServicePaths(home).settings_path, nextSettings);
-    await writeBridgeRoutingPolicy(bridgeRoutePolicyPath(path.join(path.resolve(home), '.codex')), flipped).catch(() => undefined);
-    settings.route_policy = flipped;
-    runtime.config.routePolicy = flipped;
-    process.stdout.write(`${JSON.stringify({ schema: 'sks.desktop-bridge-log.v2', event: 'sks.desktop_bridge.official_models_auto_applied', at: new Date().toISOString(), sks_version: PACKAGE_VERSION, mode: 'passthrough', policy_generation: flipped.policy_generation, secret_fields_redacted: true })}\n`);
+    await writeBridgeRoutingPolicy(bridgeRoutePolicyPath(path.join(path.resolve(home), '.codex')), converged).catch(() => undefined);
+    settings.route_policy = converged;
+    runtime.config.routePolicy = converged;
+    process.stdout.write(`${JSON.stringify({ schema: 'sks.desktop-bridge-log.v2', event: 'sks.desktop_bridge.official_models_auto_applied', at: new Date().toISOString(), sks_version: PACKAGE_VERSION, mode, policy_generation: converged.policy_generation, secret_fields_redacted: true })}\n`);
 }
 export async function serveDesktopBridge(options = {}) {
     let handle = null;
@@ -485,7 +484,12 @@ export async function serveDesktopBridge(options = {}) {
         await autoApplyOfficialModelsAtServe(runtime, serveHome, options);
         const supervised = desktopBridgeIsSupervised();
         const skewMarkerPath = path.join(path.dirname(runtime.paths.state_path), 'desktop-bridge-skew-restart.json');
-        handle = await startPreparedDesktopBridge(await preflightDesktopBridge(runtime.config), {
+        const prepared = await preflightDesktopBridge(runtime.config);
+        const deferredUpstreams = [
+            ...Object.values(prepared.providers).filter((provider) => provider.enabled && provider.remote.unresolved).map((provider) => provider.provider_id),
+            ...(prepared.officialRemote?.unresolved ? [BRIDGE_OFFICIAL_ROUTE_ID] : []),
+        ];
+        handle = await startPreparedDesktopBridge(prepared, {
             statePath: runtime.paths.state_path,
             versionSkew: {
                 readInstalledVersion: installedPackageVersion,
@@ -504,7 +508,7 @@ export async function serveDesktopBridge(options = {}) {
                 },
             },
         });
-        process.stdout.write(`${JSON.stringify({ schema: 'sks.desktop-bridge-log.v2', event: 'sks.desktop_bridge.started', at: new Date().toISOString(), sks_version: PACKAGE_VERSION, pid: handle.state.pid, process_generation: handle.state.schema === DESKTOP_BRIDGE_STATE_SCHEMA ? handle.state.process_generation : null, provider_registry_generation: runtime.config.providerRegistry?.generation, route_policy_generation: runtime.config.routePolicy?.policy_generation, secret_fields_redacted: true })}\n`);
+        process.stdout.write(`${JSON.stringify({ schema: 'sks.desktop-bridge-log.v2', event: 'sks.desktop_bridge.started', at: new Date().toISOString(), sks_version: PACKAGE_VERSION, pid: handle.state.pid, process_generation: handle.state.schema === DESKTOP_BRIDGE_STATE_SCHEMA ? handle.state.process_generation : null, provider_registry_generation: runtime.config.providerRegistry?.generation, route_policy_generation: runtime.config.routePolicy?.policy_generation, ...(deferredUpstreams.length ? { deferred_upstreams: deferredUpstreams } : {}), secret_fields_redacted: true })}\n`);
         await waitForShutdown(handle);
         return { schema: 'sks.desktop-bridge-serve.v1', ok: true, status: 'stopped', state: handle.state };
     }

package/dist/core/codex-lb/provider-route-policy.js

@@ -118,14 +118,18 @@ function isRouteTargetId(value) {
 }
 export const OFFICIAL_MODEL_ID_PATTERN = /^(?:gpt-[0-9]|o[0-9]|codex-mini)/;
 export function applyOfficialModelPassthrough(policy, input = { mode: 'passthrough' }) {
-    if (input.mode === 'gateway')
-        return policy;
     const routes = {};
+    let changed = false;
     for (const [model, target] of Object.entries(policy.model_routes)) {
-        routes[model] = OFFICIAL_MODEL_ID_PATTERN.test(model) && !model.includes(':')
-            ? { provider_id: BRIDGE_OFFICIAL_ROUTE_ID, upstream_model: model }
-            : target;
+        const next = input.mode === 'passthrough'
+            ? passthroughRouteTarget(model, target)
+            : gatewayRouteTarget(model, target, policy);
+        routes[model] = next;
+        if (next !== target)
+            changed = true;
     }
+    if (!changed)
+        return policy;
     const semantic = {
         default_provider_id: policy.default_provider_id,
         fallback: 'none',
@@ -139,6 +143,23 @@ export function applyOfficialModelPassthrough(policy, input = { mode: 'passthrou
         changed_at: input.changedAt || new Date().toISOString()
     };
 }
+function passthroughRouteTarget(model, target) {
+    if (!OFFICIAL_MODEL_ID_PATTERN.test(model) || model.includes(':'))
+        return target;
+    if (target.provider_id === BRIDGE_OFFICIAL_ROUTE_ID && target.upstream_model === model)
+        return target;
+    return { provider_id: BRIDGE_OFFICIAL_ROUTE_ID, upstream_model: model };
+}
+function gatewayRouteTarget(model, target, policy) {
+    if (target.provider_id !== BRIDGE_OFFICIAL_ROUTE_ID)
+        return target;
+    if (!OFFICIAL_MODEL_ID_PATTERN.test(model) || model.includes(':'))
+        return target;
+    const twin = policy.model_routes[`codex-lb:${model}`];
+    if (!twin || twin.provider_id !== 'codex-lb')
+        return target;
+    return { provider_id: twin.provider_id, upstream_model: twin.upstream_model };
+}
 function sameTarget(left, right) {
     return left.provider_id === right.provider_id && left.upstream_model === right.upstream_model;
 }

package/dist/core/doctor/desktop-bridge-catalog-repair.js

@@ -1,30 +1,110 @@
+import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { desktopBridgeStatusV3, executeDesktopBridgeCommandV3 } from '../codex-lb/desktop-controller-v3.js';
-import { bootstrapExistingDesktopBridgeService, desktopBridgeServiceStatus } from '../codex-lb/desktop-service.js';
-import { desktopBridgeRuntimeVersion, desktopBridgeRuntimeVersionStale } from '../codex-lb/desktop-bridge/state.js';
+import { bootstrapExistingDesktopBridgeService, desktopBridgeServicePaths, desktopBridgeServiceStatus } from '../codex-lb/desktop-service.js';
+import { desktopBridgeRuntimeVersion, desktopBridgeRuntimeVersionStale, readDesktopBridgeState } from '../codex-lb/desktop-bridge/state.js';
 import { PACKAGE_VERSION } from '../version.js';
-export async function restartStaleDesktopBridgeRuntime(input) {
-    if (process.env.SKS_TEST_ISOLATION === '1' || process.env.SKS_RELEASE_UPGRADE_SMOKE === '1') {
+export const BRIDGE_UNREACHABLE_EVIDENCE_WINDOW_MS = 10 * 60_000;
+const BRIDGE_LOG_TAIL_BYTES = 256 * 1024;
+const UNREACHABLE_REJECTION_CODE = /^bridge_(?:websocket_)?upstream_unavailable/;
+const REROUTED_REJECTION_CODE = /^bridge_upstream_unreachable_rerouted/;
+export function detectUnreachableUpstreamEvidence(logTail, startedAt, nowMs) {
+    const startedMs = startedAt ? Date.parse(startedAt) : Number.NaN;
+    const cutoffMs = Math.max(Number.isFinite(startedMs) ? startedMs : 0, nowMs - BRIDGE_UNREACHABLE_EVIDENCE_WINDOW_MS);
+    let latest = null;
+    let latestReroute = Number.NEGATIVE_INFINITY;
+    for (const line of logTail.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{') || !trimmed.includes('"sks.desktop_bridge.rejected'))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (record.event !== 'sks.desktop_bridge.rejected' && record.event !== 'sks.desktop_bridge.rejected_summary')
+            continue;
+        const code = typeof record.code === 'string' ? record.code : '';
+        const unreachable = UNREACHABLE_REJECTION_CODE.test(code);
+        const rerouted = !unreachable && REROUTED_REJECTION_CODE.test(code);
+        if (!unreachable && !rerouted)
+            continue;
+        const at = typeof record.at === 'string' ? Date.parse(record.at) : Number.NaN;
+        if (!Number.isFinite(at) || at < cutoffMs)
+            continue;
+        if (rerouted) {
+            latestReroute = Math.max(latestReroute, at);
+            continue;
+        }
+        if (!latest || at > latest.at)
+            latest = { at, code };
+    }
+    if (!latest || latest.at <= latestReroute)
+        return null;
+    return latest.code;
+}
+export async function readDesktopBridgeUnreachableUpstreamEvidence(home, deps = {}) {
+    const paths = desktopBridgeServicePaths(home);
+    const state = await readDesktopBridgeState(paths.state_path).catch(() => null);
+    if (!state)
+        return null;
+    const tail = await (deps.readLogTailImpl || readBridgeLogTail)(paths.stdout_log_path, BRIDGE_LOG_TAIL_BYTES).catch(() => '');
+    const code = detectUnreachableUpstreamEvidence(tail, state.started_at, (deps.nowMs || Date.now)());
+    return code ? { code, started_at: state.started_at } : null;
+}
+async function readBridgeLogTail(logPath, maxBytes) {
+    const handle = await fsp.open(logPath, 'r');
+    try {
+        const { size } = await handle.stat();
+        const start = Math.max(0, size - maxBytes);
+        const buffer = Buffer.alloc(size - start);
+        await handle.read(buffer, 0, buffer.length, start);
+        return buffer.toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function restartStaleDesktopBridgeRuntime(input, deps = {}) {
+    const usingRealImpls = !deps.serviceStatusImpl && !deps.bootstrapImpl && !deps.readLogTailImpl;
+    if (usingRealImpls && (process.env.SKS_TEST_ISOLATION === '1' || process.env.SKS_RELEASE_UPGRADE_SMOKE === '1')) {
         return { restarted: false, warnings: [], blockers: [] };
     }
-    const service = await desktopBridgeServiceStatus({ home: input.home }).catch(() => null);
-    if (!service?.running || !desktopBridgeRuntimeVersionStale(service.state)) {
+    const service = await (deps.serviceStatusImpl || desktopBridgeServiceStatus)({ home: input.home }).catch(() => null);
+    if (!service?.running)
         return { restarted: false, warnings: [], blockers: [] };
+    const versionStale = desktopBridgeRuntimeVersionStale(service.state);
+    let unreachable = null;
+    if (!versionStale) {
+        const logPath = service.paths?.stdout_log_path;
+        const tail = logPath
+            ? await (deps.readLogTailImpl || readBridgeLogTail)(logPath, BRIDGE_LOG_TAIL_BYTES).catch(() => '')
+            : '';
+        unreachable = detectUnreachableUpstreamEvidence(tail, service.state?.started_at, (deps.nowMs || Date.now)());
+        if (!unreachable)
+            return { restarted: false, warnings: [], blockers: [] };
     }
     const running = desktopBridgeRuntimeVersion(service.state) || 'pre-8.6.2';
+    const blocker = versionStale
+        ? `desktop_bridge_runtime_version_stale:${running}:${PACKAGE_VERSION}`
+        : `desktop_bridge_upstream_unreachable:${unreachable}`;
     if (!input.fix) {
-        return {
-            restarted: false,
-            warnings: [],
-            blockers: [`desktop_bridge_runtime_version_stale:${running}:${PACKAGE_VERSION}`]
-        };
+        return { restarted: false, warnings: [], blockers: [blocker] };
     }
-    const restarted = await bootstrapExistingDesktopBridgeService({ home: input.home }).catch(() => null);
+    const restarted = await (deps.bootstrapImpl || bootstrapExistingDesktopBridgeService)({ home: input.home }).catch(() => null);
     const nowRunning = restarted?.running === true && !desktopBridgeRuntimeVersionStale(restarted.state);
-    return nowRunning
-        ? { restarted: true, warnings: [`desktop_bridge_runtime_restarted:${running}:${PACKAGE_VERSION}`], blockers: [] }
-        : { restarted: false, warnings: [], blockers: [`desktop_bridge_runtime_version_stale:${running}:${PACKAGE_VERSION}`] };
+    if (!nowRunning)
+        return { restarted: false, warnings: [], blockers: [blocker] };
+    return {
+        restarted: true,
+        warnings: [versionStale
+                ? `desktop_bridge_runtime_restarted:${running}:${PACKAGE_VERSION}`
+                : `desktop_bridge_upstream_unreachable_restarted:${unreachable}`],
+        blockers: []
+    };
 }
 export const CATALOG_REPAIR_MAX_ATTEMPTS = 2;
 export async function repairDoctorDesktopBridgeCatalog(input, deps = {}) {

package/dist/core/doctor/legacy-runtime-data-gc.js

@@ -0,0 +1,185 @@
+import path from 'node:path';
+import fsp from 'node:fs/promises';
+import { readJson } from '../fsx.js';
+import { inspectConfinedPath, publicPathError, removeManagedPathVerified } from '../managed-path-safety.js';
+export const LEGACY_RUNTIME_DATA_GC_SCHEMA = 'sks.legacy-runtime-data-gc.v1';
+const CONFIG_BACKUP_NAME = /^config\.toml\.(?:backup-[A-Za-z0-9_.:-]+|bak(?:[-.][A-Za-z0-9_.-]+)?|[A-Za-z0-9_.-]+\.bak)$/;
+const BRIDGE_GENERATION_DIR = /^[0-9a-f]{64}\.[0-9a-f]{64}\.[0-9a-f]{64}$/;
+const RETIRED_VERSION_CACHE = /^codex-0\d{2,3}-(?:capability|doctor)\.json$/;
+const RETIRED_CHROME_HOSTS_V1 = 'chrome-native-hosts.json';
+const CHROME_HOSTS_V2 = 'chrome-native-hosts-v2.json';
+export const LEGACY_CONFIG_BACKUP_KEEP_COUNT = 3;
+export const LEGACY_BRIDGE_GENERATION_KEEP_COUNT = 1;
+export async function reconcileLegacyRuntimeData(input) {
+    const codexHome = path.resolve(input.codexHome);
+    const configBackups = await reconcileConfigBackups(codexHome, input.fix);
+    const bridgeGenerations = await reconcileBridgeGenerations(codexHome, input.fix);
+    const retiredVersionCaches = await reconcileRetiredVersionCaches(input.stateRoots, input.fix);
+    const retiredSingletons = await reconcileRetiredSingletons(codexHome, input.fix);
+    const categories = [configBackups, bridgeGenerations, retiredVersionCaches, retiredSingletons];
+    const remainingCount = categories.reduce((total, category) => total + category.remaining, 0);
+    const errorCount = categories.reduce((total, category) => total + category.errors.length, 0);
+    return {
+        schema: LEGACY_RUNTIME_DATA_GC_SCHEMA,
+        ok: remainingCount === 0 && errorCount === 0,
+        fix: input.fix,
+        config_backups: configBackups,
+        bridge_generations: bridgeGenerations,
+        retired_version_caches: retiredVersionCaches,
+        retired_singletons: retiredSingletons,
+        remaining_count: remainingCount,
+        error_count: errorCount
+    };
+}
+function emptyCategory() {
+    return { detected: 0, removed: 0, kept: 0, remaining: 0, errors: [] };
+}
+async function reconcileConfigBackups(codexHome, fix) {
+    const report = emptyCategory();
+    const names = await readdirOrNull(codexHome);
+    if (!names)
+        return report;
+    const candidates = [];
+    for (const name of names) {
+        if (!CONFIG_BACKUP_NAME.test(name))
+            continue;
+        const inspected = await inspectOwnedRegularFile(codexHome, path.join(codexHome, name), report);
+        if (!inspected)
+            continue;
+        report.detected += 1;
+        candidates.push({ file: inspected.path, mtimeMs: inspected.stat?.mtimeMs || 0 });
+    }
+    candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    report.kept = Math.min(candidates.length, LEGACY_CONFIG_BACKUP_KEEP_COUNT);
+    for (const candidate of candidates.slice(LEGACY_CONFIG_BACKUP_KEEP_COUNT)) {
+        await removeOrCount(codexHome, candidate.file, fix, report);
+    }
+    return report;
+}
+async function reconcileBridgeGenerations(codexHome, fix) {
+    const report = emptyCategory();
+    const runtimeRoot = path.join(codexHome, 'sks');
+    const generationsRoot = path.join(runtimeRoot, '.sks-bridge-generations');
+    const names = await readdirOrNull(generationsRoot);
+    if (!names)
+        return report;
+    const pointer = await readJson(path.join(runtimeRoot, 'sks-bridge-active-generation.json'), null);
+    const activeName = typeof pointer?.bundle_directory === 'string'
+        ? path.basename(pointer.bundle_directory)
+        : null;
+    const candidates = [];
+    for (const name of names) {
+        if (!BRIDGE_GENERATION_DIR.test(name))
+            continue;
+        const target = path.join(generationsRoot, name);
+        let inspected;
+        try {
+            inspected = await inspectConfinedPath(generationsRoot, target);
+        }
+        catch (error) {
+            report.errors.push(publicPathError(error, target));
+            continue;
+        }
+        if (!inspected.exists || inspected.leafSymlink || !inspected.stat?.isDirectory() || !ownedByCurrentUid(inspected))
+            continue;
+        report.detected += 1;
+        if (name === activeName) {
+            report.kept += 1;
+            continue;
+        }
+        candidates.push({ file: target, name, mtimeMs: inspected.stat.mtimeMs });
+    }
+    if (!activeName || !BRIDGE_GENERATION_DIR.test(activeName)) {
+        report.kept += candidates.length;
+        return report;
+    }
+    candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    report.kept += Math.min(candidates.length, LEGACY_BRIDGE_GENERATION_KEEP_COUNT);
+    for (const candidate of candidates.slice(LEGACY_BRIDGE_GENERATION_KEEP_COUNT)) {
+        await removeOrCount(generationsRoot, candidate.file, fix, report);
+    }
+    return report;
+}
+async function reconcileRetiredVersionCaches(stateRoots, fix) {
+    const report = emptyCategory();
+    for (const root of [...new Set(stateRoots.map((value) => path.resolve(value)))]) {
+        const names = await readdirOrNull(root);
+        if (!names)
+            continue;
+        for (const name of names) {
+            if (!RETIRED_VERSION_CACHE.test(name))
+                continue;
+            const inspected = await inspectOwnedRegularFile(root, path.join(root, name), report);
+            if (!inspected)
+                continue;
+            report.detected += 1;
+            await removeOrCount(root, inspected.path, fix, report);
+        }
+    }
+    return report;
+}
+async function reconcileRetiredSingletons(codexHome, fix) {
+    const report = emptyCategory();
+    const v1 = path.join(codexHome, RETIRED_CHROME_HOSTS_V1);
+    const v2 = path.join(codexHome, CHROME_HOSTS_V2);
+    const v1Inspected = await inspectOwnedRegularFile(codexHome, v1, report, { quiet: true });
+    if (!v1Inspected)
+        return report;
+    const v2Inspected = await inspectOwnedRegularFile(codexHome, v2, report, { quiet: true });
+    report.detected += 1;
+    if (!v2Inspected) {
+        report.kept += 1;
+        return report;
+    }
+    await removeOrCount(codexHome, v1, fix, report);
+    return report;
+}
+async function removeOrCount(boundary, file, fix, report) {
+    if (!fix) {
+        report.remaining += 1;
+        return;
+    }
+    try {
+        await removeManagedPathVerified(boundary, file);
+        report.removed += 1;
+    }
+    catch (error) {
+        report.errors.push(publicPathError(error, file));
+        report.remaining += 1;
+    }
+}
+async function inspectOwnedRegularFile(boundary, file, report, options = {}) {
+    let inspected;
+    try {
+        inspected = await inspectConfinedPath(boundary, file);
+    }
+    catch (error) {
+        if (!options.quiet)
+            report.errors.push(publicPathError(error, file));
+        return null;
+    }
+    if (!inspected.exists || inspected.leafSymlink || !inspected.stat?.isFile() || !ownedByCurrentUid(inspected))
+        return null;
+    return inspected;
+}
+function ownedByCurrentUid(inspected) {
+    if (typeof process.getuid !== 'function')
+        return true;
+    return inspected.stat?.uid === process.getuid();
+}
+async function readdirOrNull(directory) {
+    try {
+        const stat = await fsp.lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    try {
+        return (await fsp.readdir(directory)).sort();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/init/legacy-generation-convergence.js

@@ -6,6 +6,7 @@ import { hasExplicitSksManagedCodexConfigMarker, writeCodexConfigGuarded } from
 import { validateCodexConfigRoundTrip } from '../codex/codex-config-toml.js';
 import { collectNestedProjectRoots } from '../doctor/current-project-guidance-nested.js';
 import { reconcileRetiredManagedResidue } from '../doctor/retired-managed-residue.js';
+import { reconcileLegacyRuntimeData } from '../doctor/legacy-runtime-data-gc.js';
 import { readJson, readText } from '../fsx.js';
 import { removeMcpServerBlock, mcpServerBlockWithChildren } from '../mcp/mcp-config-preservation.js';
 import { reconcileRetiredSksConfigText } from '../auto-review.js';
@@ -54,6 +55,11 @@ export async function reconcileLegacyManagedGeneration(input) {
     for (const runtimeRoot of runtimeRoots) {
         retiredRuntimeScopes.push(await reconcileRuntimeScope(runtimeRoot, input.fix));
     }
+    const runtimeDataGc = await reconcileLegacyRuntimeData({
+        codexHome,
+        stateRoots: runtimeRoots.map((runtimeRoot) => path.join(runtimeRoot, '.sneakoscope')),
+        fix: input.fix
+    });
     const managedConfigs = await reconcileManagedConfigs({
         projectRoots,
         home,
@@ -68,6 +74,7 @@ export async function reconcileLegacyManagedGeneration(input) {
         ok: skillsOk
             && retiredAgentRoles.ok
             && runtimeOk
+            && runtimeDataGc.ok
             && managedConfigs.ok
             && blockers.length === 0
             && nested.errorCount === 0,
@@ -79,6 +86,7 @@ export async function reconcileLegacyManagedGeneration(input) {
         project_skills: projectSkills,
         retired_agent_roles: retiredAgentRoles,
         retired_runtime_scopes: retiredRuntimeScopes,
+        runtime_data_gc: runtimeDataGc,
         managed_configs: managedConfigs,
         blockers,
         warnings
@@ -133,6 +141,7 @@ async function reconcileManagedConfigs(input) {
         rewritten_count: 0,
         retired_mcp_block_count: 0,
         retired_config_entry_count: 0,
+        compacted_marker_line_count: 0,
         preserved_user_config_count: 0,
         remaining_count: 0,
         error_count: 0,
@@ -179,7 +188,8 @@ async function reconcileManagedConfigTarget(target, fix, report) {
     const before = await readText(target.configPath, '');
     const ownership = await managedConfigOwnershipProof(target.ownerRoot, target.configPath, before);
     const retiredConfig = reconcileRetiredSksConfigText(before);
-    let next = retiredConfig.user_authored_conflict && !ownership ? before : retiredConfig.text;
+    const retiredApplied = !(retiredConfig.user_authored_conflict && !ownership);
+    let next = retiredApplied ? retiredConfig.text : before;
     let retiredMcpCount = 0;
     if (ownership) {
         for (const server of RETIRED_SKS_MCP_SERVERS) {
@@ -189,8 +199,11 @@ async function reconcileManagedConfigTarget(target, fix, report) {
             retiredMcpCount += 1;
         }
     }
-    const retiredConfigCount = next === before ? 0 : retiredConfig.detected_count;
-    const detectedCount = retiredConfigCount + retiredMcpCount;
+    const compacted = compactSksMovedConfigMarkers(next);
+    const markerCount = compacted.removed_count;
+    next = compacted.text;
+    const retiredConfigCount = retiredApplied && retiredConfig.detected_count > 0 ? retiredConfig.detected_count : 0;
+    const detectedCount = retiredConfigCount + retiredMcpCount + markerCount;
     if (retiredConfig.user_authored_conflict && !ownership) {
         report.preserved_user_config_count += 1;
         report.preserved_user_configs.push(target.configPath);
@@ -200,6 +213,7 @@ async function reconcileManagedConfigTarget(target, fix, report) {
     report.detected_count += detectedCount;
     report.retired_config_entry_count += retiredConfigCount;
     report.retired_mcp_block_count += retiredMcpCount;
+    report.compacted_marker_line_count += markerCount;
     if (!fix) {
         report.remaining_count += detectedCount;
         return;
@@ -211,8 +225,9 @@ async function reconcileManagedConfigTarget(target, fix, report) {
     }
     try {
         const normalized = normalizeConfigText(next);
-        const exactRetiredConfigAuthorized = retiredConfig.detected_count > 0
-            && retiredConfig.user_authored_conflict !== true;
+        const exactRetiredConfigAuthorized = (retiredConfig.detected_count > 0
+            && retiredConfig.user_authored_conflict !== true)
+            || markerCount > 0;
         const guarded = await writeCodexConfigGuarded({
             root: target.ownerRoot,
             configPath: target.configPath,
@@ -254,6 +269,16 @@ function normalizeConfigText(text) {
     const value = String(text || '').trimEnd().replace(/\n{3,}/g, '\n\n');
     return value ? `${value}\n` : '';
 }
+const SKS_MOVED_MARKER_LINE = /^\s*#\s*SKS moved machine-local Codex config\b/i;
+function compactSksMovedConfigMarkers(text) {
+    const lines = String(text || '').split('\n');
+    const markerIndexes = lines.flatMap((line, index) => (SKS_MOVED_MARKER_LINE.test(line) ? [index] : []));
+    if (markerIndexes.length < 2)
+        return { text, removed_count: 0 };
+    const keep = markerIndexes[markerIndexes.length - 1];
+    const kept = lines.filter((line, index) => !SKS_MOVED_MARKER_LINE.test(line) || index === keep);
+    return { text: kept.join('\n'), removed_count: markerIndexes.length - 1 };
+}
 function recordConfigError(report, file, error) {
     report.error_count += 1;
     report.errors.push(`${file}:${error instanceof Error ? error.message : String(error)}`);

package/dist/core/version.js

@@ -1 +1 @@
-export const PACKAGE_VERSION = '9.2.4';
+export const PACKAGE_VERSION = '9.2.6';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "9.2.4",
+  "version": "9.2.6",
   "description": "Sneakoscope Codex (`sks`) is an open-source trust layer for Codex CLI and ChatGPT Desktop. It coordinates bounded AI coding agents, records machine-verifiable evidence, preserves project memory, and blocks release claims that are not supported by current tests or artifacts. Search visibility outcomes are measured separately; SKS does not promise rankings or traffic.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
@@ -200,7 +200,7 @@
   "dependencies": {
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
-    "@openai/codex-sdk": "0.147.0",
+    "@openai/codex-sdk": "0.150.1",
     "smol-toml": "^1.7.0",
     "typescript": "^5.9.3"
   },