sneakoscope 9.2.5 → 10.0.0

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.5** — its own identity, read from `package.json` and subject to release-gate verification, not advice about what to install.
+This README documents package **SKS 10.0.0** — 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).
 
@@ -305,7 +305,7 @@ Adapter rules that keep updates safe:
 | --- | --- | --- |
 | Did tests/typecheck fail? | Another model may say so. | Machine check output is tagged `evidence: machine`. |
 | Are findings ranked? | Usually one blended opinion. | Machine evidence sorts before LLM findings. |
-| Can work stop? | The model decides. | Stop gates, Completion Proof, and Honest Mode decide. |
+| Can work stop? | The model decides. | Safety gates decide (`essential`, default: a finished turn finishes; `strict` adds Stop gates, Completion Proof, and Honest Mode). |
 | Can I inspect agent-thread progress? | Usually no runtime UI. | Use the official Codex subagent/thread surfaces and their proof artifacts. |
 
 ## Demo

package/config/skills-hash-ledger.v1.json

@@ -18,6 +18,7 @@
     {
       "canonical_name": "sks-answer",
       "trusted_sha256": [
+        "0e461537093215960734aaeafdccb125d2c3ca139dab5db8548d5c0bdd14d652",
         "3056ac543fa074868c7023097fdcb042d7175ab557d8e18cb7d92ce872785452",
         "bc8e2fc157b6c9819d32bb0a41bdf7f599a07693df18b0d80aa0ba103594f6eb"
       ]
@@ -65,6 +66,7 @@
     {
       "canonical_name": "sks-computer-use-fast",
       "trusted_sha256": [
+        "1d191ed0f9490fc320dd17b871ca556fa5835bfb372c38b62f3985e3369f685a",
         "57e4c1d04ae785b0a53711e53210f2ddabd6131041b97edb4b6d99f18b24155e",
         "b270d82e4057934d7f92ed4241d4ae86e22d0a9a08bceba1aa179d7535bda042",
         "b8736b2621398dfc85f7a2ff35d7a2fc728db0dfc0e964de69aebff93b5ed897"
@@ -207,6 +209,7 @@
     {
       "canonical_name": "sks-honest-mode",
       "trusted_sha256": [
+        "4a0722737a837b0de895b7c950da216a8641922e4da53d6b9c1681b957340e82",
         "d1216afadecd4d9c85a2fb54bd31ee77ba45f8071f43bb0e21305c5fcd870095",
         "4543d942cac510b1a23e2e842f944d033087bbc761f6abc4a27d0a015bf22235"
       ]
@@ -283,6 +286,7 @@
     {
       "canonical_name": "sks-pipeline-runner",
       "trusted_sha256": [
+        "66e105773b8e042eec5d5679b97b7cb305cad8d45671034907fbfa728fc4d68a",
         "020ba4da2f96bcda23cee4596b1e790816780178f1917dee748ff4b289cba0e5",
         "ffcbe0ea4b585e3d2886f1d9fa7a3b88706aaf42182fb177b2371b76beb0ddcd"
       ]

package/crates/sks-core/Cargo.lock

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

package/crates/sks-core/Cargo.toml

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

package/dist/bin/fast-inline.js

@@ -11,9 +11,63 @@ function rootJsonFastInline(fs, cwd = process.cwd()) {
         using_global_root: !project
     })}\n`);
 }
+async function fastDesktopBridgeUpstreamEvidence(home) {
+    const notChecked = (reason) => ({
+        section: { schema: 'sks.desktop-bridge-fast-status.v1', status: 'not_checked', reason, secret_stores_read: false },
+        warnings: [], nextActions: [],
+    });
+    try {
+        const getBuiltinModule = process.getBuiltinModule;
+        const fs = typeof getBuiltinModule === 'function' ? getBuiltinModule('node:fs') : await import('node:fs');
+        const runtime = joinPath(joinPath(home, '.codex'), 'sks');
+        const statePath = joinPath(runtime, 'desktop-bridge-state.json');
+        if (!fs.existsSync(statePath))
+            return notChecked('bridge_state_missing');
+        const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        const startedAt = typeof state.started_at === 'string' ? state.started_at : null;
+        const logPath = joinPath(joinPath(runtime, 'logs'), 'desktop-bridge.out.log');
+        const { BRIDGE_LOG_TAIL_BYTES, UNREACHABLE_UPSTREAM_RECOVERY_ACTION, detectUnreachableUpstreamEvidence } = await import('../core/codex-lb/desktop-bridge/upstream-evidence.js');
+        let tail = '';
+        if (fs.existsSync(logPath)) {
+            const handle = fs.openSync(logPath, 'r');
+            try {
+                const size = fs.fstatSync(handle).size;
+                const start = Math.max(0, size - BRIDGE_LOG_TAIL_BYTES);
+                const buffer = Buffer.alloc(size - start);
+                fs.readSync(handle, buffer, 0, buffer.length, start);
+                tail = buffer.toString('utf8');
+            }
+            finally {
+                fs.closeSync(handle);
+            }
+        }
+        const code = detectUnreachableUpstreamEvidence(tail, startedAt, Date.now());
+        const blockers = code ? [`desktop_bridge_upstream_unreachable:${code}`] : [];
+        return {
+            section: {
+                schema: 'sks.desktop-bridge-fast-status.v1',
+                status: code ? 'upstream_unreachable_evidence' : 'log_evidence_clear',
+                reason: 'fast_readonly_json_log_evidence',
+                secret_stores_read: false,
+                serving_pid: typeof state.pid === 'number' ? state.pid : null,
+                started_at: startedAt,
+                blockers,
+                recovery_actions: code ? [UNREACHABLE_UPSTREAM_RECOVERY_ACTION] : [],
+            },
+            warnings: blockers,
+            nextActions: code ? [UNREACHABLE_UPSTREAM_RECOVERY_ACTION] : [],
+        };
+    }
+    catch {
+        return notChecked('evidence_read_failed');
+    }
+}
 async function doctorJsonFastInline(input = {}) {
     const startedAt = Date.now();
     const write = input.write || ((text) => process.stdout.write(text));
+    const env = input.processEnv || process.env;
+    const home = input.home || env.HOME || env.USERPROFILE || process.cwd();
+    const bridge = await fastDesktopBridgeUpstreamEvidence(home);
     write(`${JSON.stringify({
         schema: 'sks.doctor-status.v3',
         elapsed_ms: Math.max(0, Date.now() - startedAt),
@@ -23,7 +77,7 @@ async function doctorJsonFastInline(input = {}) {
         deep_diagnostics_skipped: true,
         deep_ok: null,
         not_counted_as_full_doctor: true,
-        next_actions: ['Run sks doctor --full --json for deep diagnostics.'],
+        next_actions: ['Run sks doctor --full --json for deep diagnostics.', ...bridge.nextActions],
         fast_path: true,
         profile: 'fast-readonly',
         root: process.cwd(),
@@ -40,13 +94,8 @@ async function doctorJsonFastInline(input = {}) {
         },
         doctor_fix_transaction: null,
         blockers: [],
-        warnings: ['fast_readonly_doctor_skipped_optional_deep_diagnostics'],
-        desktop_bridge: {
-            schema: 'sks.desktop-bridge-fast-status.v1',
-            status: 'not_checked',
-            reason: 'fast_readonly_json',
-            secret_stores_read: false
-        }
+        warnings: ['fast_readonly_doctor_skipped_optional_deep_diagnostics', ...bridge.warnings],
+        desktop_bridge: bridge.section
     }, null, 2)}\n`);
 }
 async function narutoHelpJsonFastInline() {

package/dist/bin/sks-dispatch.js

@@ -27,7 +27,7 @@ async function runSks(args) {
         const { hookUserPromptSubmitPerfInline } = await import('./fast-inline.js');
         await hookUserPromptSubmitPerfInline();
     }
-    else if (args[0] === 'hook' && args[1] && process.env.SKS_HOOK_DAEMON === '1') {
+    else if (args[0] === 'hook' && args[1] && (await import('../core/verification-profile.js')).hookDaemonEnabled()) {
         const { hookDaemonInline } = await import('../core/daemon/sksd-hook-dispatch.js');
         await hookDaemonInline(args[1]);
     }

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,19 @@ 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);
+        const warnings = (status.readiness.warnings || []).map(String).filter(Boolean);
+        if (expected && status.readiness.ready !== true && status.readiness.state === 'degraded' && blockers.length === 0) {
+            warnings.push('desktop_bridge_readiness_degraded:transport_unverified_for_current_process');
+            recoveryActions.push('Run `sks bridge verify --level transport` (or `sks doctor --fix`, which re-verifies after its repair) to bind a transport diagnostic to the serving bridge.');
+        }
+        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,
@@ -81,8 +94,8 @@ export async function inspectDoctorDesktopBridgeStatus(input = {}, deps = {}) {
             status,
             providers: status.providers,
             blockers,
-            warnings: (status.readiness.warnings || []).map(String).filter(Boolean),
-            recovery_actions: (status.recovery_actions || []).map(String).filter(Boolean)
+            warnings,
+            recovery_actions: recoveryActions
         };
     }
     catch (error) {

package/dist/config/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "sks.skills-manifest.v1",
-  "package_version": "9.2.5",
+  "package_version": "10.0.0",
   "skills": [
     {
       "canonical_name": "sks",
@@ -23,8 +23,9 @@
     {
       "canonical_name": "sks-answer",
       "type": "official",
-      "content_sha256": "3056ac543fa074868c7023097fdcb042d7175ab557d8e18cb7d92ce872785452",
+      "content_sha256": "0e461537093215960734aaeafdccb125d2c3ca139dab5db8548d5c0bdd14d652",
       "hash_history": [
+        "3056ac543fa074868c7023097fdcb042d7175ab557d8e18cb7d92ce872785452",
         "bc8e2fc157b6c9819d32bb0a41bdf7f599a07693df18b0d80aa0ba103594f6eb"
       ],
       "deprecated_aliases": []
@@ -82,8 +83,9 @@
     {
       "canonical_name": "sks-computer-use-fast",
       "type": "official",
-      "content_sha256": "57e4c1d04ae785b0a53711e53210f2ddabd6131041b97edb4b6d99f18b24155e",
+      "content_sha256": "1d191ed0f9490fc320dd17b871ca556fa5835bfb372c38b62f3985e3369f685a",
       "hash_history": [
+        "57e4c1d04ae785b0a53711e53210f2ddabd6131041b97edb4b6d99f18b24155e",
         "b270d82e4057934d7f92ed4241d4ae86e22d0a9a08bceba1aa179d7535bda042",
         "b8736b2621398dfc85f7a2ff35d7a2fc728db0dfc0e964de69aebff93b5ed897"
       ],
@@ -263,8 +265,9 @@
     {
       "canonical_name": "sks-honest-mode",
       "type": "official",
-      "content_sha256": "d1216afadecd4d9c85a2fb54bd31ee77ba45f8071f43bb0e21305c5fcd870095",
+      "content_sha256": "4a0722737a837b0de895b7c950da216a8641922e4da53d6b9c1681b957340e82",
       "hash_history": [
+        "d1216afadecd4d9c85a2fb54bd31ee77ba45f8071f43bb0e21305c5fcd870095",
         "4543d942cac510b1a23e2e842f944d033087bbc761f6abc4a27d0a015bf22235"
       ],
       "deprecated_aliases": []
@@ -351,8 +354,9 @@
     {
       "canonical_name": "sks-pipeline-runner",
       "type": "official",
-      "content_sha256": "020ba4da2f96bcda23cee4596b1e790816780178f1917dee748ff4b289cba0e5",
+      "content_sha256": "66e105773b8e042eec5d5679b97b7cb305cad8d45671034907fbfa728fc4d68a",
       "hash_history": [
+        "020ba4da2f96bcda23cee4596b1e790816780178f1917dee748ff4b289cba0e5",
         "ffcbe0ea4b585e3d2886f1d9fa7a3b88706aaf42182fb177b2371b76beb0ddcd"
       ],
       "deprecated_aliases": []

package/dist/core/codex-hooks/codex-hook-managed-install.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { ensureDir, nowIso, readText, writeTextAtomic } from '../fsx.js';
 import { CODEX_HOOK_EVENTS } from '../codex-compat/codex-hook-events.js';
+import { postToolEvidenceEnabled } from '../verification-profile.js';
 import { buildCodexCommandHookToml, matcherApplies } from './codex-hook-config-writer.js';
 import { readCodexHookActualState } from './codex-hook-actual-discovery.js';
 import { writeTrustedHashStateForHooksFile } from './codex-hook-state-writer.js';
@@ -22,12 +23,13 @@ export async function installManagedCodexHooks(root, opts = {}) {
     const scriptPath = path.join(managedDir, 'sks-managed-hook.sh');
     const tomlPath = path.join(managedDir, 'sks-managed-hooks.toml');
     const binCommand = opts.binCommand || 'sks hook';
-    const hooksToml = CODEX_HOOK_EVENTS.map((event) => buildCodexCommandHookToml({
+    const installedEvents = CODEX_HOOK_EVENTS.filter((event) => event !== 'PostToolUse' || postToolEvidenceEnabled(root));
+    const hooksToml = installedEvents.map((event) => buildCodexCommandHookToml({
         event,
         matcher: matcherApplies(event) ? '*' : null,
         command: `${scriptPath} ${HOOK_SUBCOMMANDS[event] || event}`,
         timeout: event === 'Stop' ? 60 : 30,
-        statusMessage: event === 'Stop' ? 'SKS validating completion proof' : null
+        statusMessage: event === 'Stop' ? 'SKS checking done gate' : null
     })).join('\n');
     const requirementsToml = mergeRequirementsToml(await readText(requirementsPath, ''), {
         managedDir,

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/server.js

@@ -306,7 +306,7 @@ export async function startPreparedDesktopBridge(input, options = {}) {
     }
     const freshnessMs = input.stateFreshnessMs ?? 5 * 60_000;
     const heartbeat = statePath ? setInterval(() => {
-        void refreshDesktopBridgeState(statePath, state, new Date(), freshnessMs).catch(() => undefined);
+        void refreshDesktopBridgeState(statePath, state, new Date(), freshnessMs, { preserveVerifiedProbeIds: true }).catch(() => undefined);
     }, Math.max(1_000, Math.floor(freshnessMs / 3))) : null;
     heartbeat?.unref();
     let skewCandidate = null;

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

@@ -69,11 +69,13 @@ export function isDesktopBridgePublicState(value) {
         && Array.isArray(row.last_verified_probe_ids) && row.last_verified_probe_ids.every(isGeneration)
         && typeof row.config_generation === 'string' && /^[a-f0-9]{64}$/.test(row.config_generation);
 }
-export async function refreshDesktopBridgeState(file, state, now = new Date(), freshnessMs = DEFAULT_FRESHNESS_MS) {
+export async function refreshDesktopBridgeState(file, state, now = new Date(), freshnessMs = DEFAULT_FRESHNESS_MS, options = {}) {
     const current = await readDesktopBridgeState(file).catch(() => null);
     if (!current || current.schema !== DESKTOP_BRIDGE_STATE_SCHEMA || current.pid !== state.pid
         || current.process_generation !== state.process_generation || current.config_generation !== state.config_generation)
         return false;
+    if (options.preserveVerifiedProbeIds)
+        state.last_verified_probe_ids = [...current.last_verified_probe_ids];
     state.updated_at = now.toISOString();
     state.stale_after = new Date(now.getTime() + freshnessMs).toISOString();
     await writeDesktopBridgeState(file, state);

package/dist/core/codex-lb/desktop-bridge/upstream-evidence.js

@@ -0,0 +1,42 @@
+export const BRIDGE_UNREACHABLE_EVIDENCE_WINDOW_MS = 10 * 60_000;
+export 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 const UNREACHABLE_UPSTREAM_RECOVERY_ACTION = 'Run `sks doctor --fix` (or `sks bridge repair`) to restart the Desktop Bridge and re-resolve its upstream address.';