@minhspark/codex-mcp-bridge 1.25.1 → 1.25.2

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.25.1",
+  "version": "1.25.2",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,19 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.25.2] - 2026-10-31
+
+### Fixed
+
+- Relay recovery no longer opens a task or activates a Desktop window, including request-triggered recovery. The old keeper flag cannot restore navigation. Windows background task navigation now fails explicitly instead of silently stealing focus.
+- The Desktop-owned supervisor restarts crashed native relay workers with bounded exponential backoff and validates their protocol and tool catalog before activation. In-flight operations fail without replay; client disconnect still shuts down the supervisor and its workers.
+- Stale inherited native pipe hints can recover through verified Desktop ancestry. Explicitly configured endpoints stay pinned, and uncertain native sends are never replayed.
+- Recovery waits and subsequent retries share the original request deadline. Native relay status checks a read-only operation through the serving shared relay instead of treating socket availability as proof of working dispatch.
+
+### Limitations
+
+- Reconnect the relay MCP once after upgrading to load the new supervisor. Worker hot reload alone cannot replace its running parent. Automatic recovery requires that Desktop-owned supervisor to remain alive; it cannot cold-start MCP in an idle application with no loaded session.
+
 ## [1.25.1] - 2026-10-31
 
 ### Fixed

package/README.md

@@ -669,9 +669,9 @@ For a repeatable failure, capture the app/OS/Node versions, the version reported
 
 **Symptoms:** `RELAY_UNAVAILABLE`, `connect ENOENT`, a missing native relay socket, or `thread ... already has an active writer`.
 
-Native Desktop handoffs require Codex Desktop to be installed, signed in and open on Windows/macOS. The app runs `codex-native-relay` while a regular task has its MCP servers loaded. The bridge can wake a saved task on both platforms when the relay is absent; the background keeper requires a live bridge client and an eligible saved task. On Windows, opening a task brings the app to the foreground, so the background keeper is off there unless `CODEX_BRIDGE_RELAY_KEEPER=1`; the relay is still woken when a request needs it. Explicit keeper/wake opt-outs remain respected.
+Native Desktop handoffs require Codex Desktop to be installed, signed in and open on Windows/macOS. The app runs `codex-native-relay` while a regular task has its MCP servers loaded. Recovery never navigates to a task, launches a window, or activates Codex. The Desktop-owned supervisor restarts crashed native relay workers with bounded exponential backoff; pending requests fail without replay, and later requests use the recovered worker. Inherited native pipe hints are rediscovered through the original Desktop process ancestry when they become stale. Requests that never reached the relay wait up to 20 seconds, within their original deadline, for its transport to recover. `CODEX_BRIDGE_RELAY_WAKE=0` disables that wait; the retired `CODEX_BRIDGE_RELAY_KEEPER` flag cannot enable UI navigation.
 
-Open a regular task in the intended saved project, then check `native_relay_status` there and `codex_bridge_status` in the sending Code session. If the relay died while that task stayed loaded, reopening the same task may not restart it: reconnect its MCP or open another regular task. Do not use the internal **Native Relay** executor task as the interactive destination. Rerun setup if registration/executor configuration is missing, and verify [native relay pipe forwarding](#native-relay-pipe-forwarding). Do not persist a pipe address copied from a different app process; discovery must validate its owner.
+Check `native_relay_status` in a regular project task and `codex_bridge_status` in the sending Code session. Native status performs a read-only `list_projects` probe and reports native dispatch separately from socket availability. Recovery requires the original Desktop-owned supervisor to remain alive: it cannot cold-start MCP when Desktop has loaded no session, and it stops when the MCP client closes. After five unsuccessful worker replacements, reconnect MCP in a regular task. Do not open the internal **Native Relay** executor; it is not an interactive chat and may show a missing-rollout error. Rerun setup if registration/executor configuration is missing, and verify [native relay pipe forwarding](#native-relay-pipe-forwarding). Never persist a pipe address copied from a different app process. After upgrading from a supervisor without crash recovery, reconnect the relay MCP once to load the updated supervisor; worker hot reload alone cannot replace its parent.
 
 An active-writer error usually identifies the legacy app-server route attempting to attach to a thread already owned by Desktop. Use the registered native Code-to-Desktop route for that conversation. Do not start another app-server or terminate shared work to force access. The ordinary `codex-bridge-desktop` Chat connector remains a legacy app-server connection; it is not a substitute for the verified native sender. An unused `CODEX_APP_SERVER_URL` alongside `external app-server disabled` is not by itself a native connection failure.
 
@@ -720,7 +720,7 @@ The catalog below records user-visible failures fixed in earlier releases. It is
 
 | Historical symptom | Fix version and cause | Current recovery |
 |---|---|---|
-| Relay vanished after app restart or was absent when a companion first started | [1.17.0](CHANGELOG.md#1170---2026-09-21): retry late pipe discovery. [1.22.14](CHANGELOG.md#12214---2026-10-21) / [1.22.16](CHANGELOG.md#12216---2026-10-22): task wake and coordinated background keeper. | Follow [relay recovery](#relay-unavailable-stale-pipe-or-an-active-writer); keep the app and a bridge client open. A dead relay in an already-loaded task may need MCP reconnect or another regular task. |
+| Relay vanished after app restart or was absent when a companion first started | [1.25.2](CHANGELOG.md#1252---2026-10-31): silent worker recovery and stale-pipe rediscovery replace the historical task wake and keeper. | Follow [relay recovery](#relay-unavailable-stale-pipe-or-an-active-writer). Reconnect MCP once after upgrading the supervisor; an idle app with no loaded MCP session cannot be cold-started by silent recovery. |
 | `No handler registered for method: tools/call` or `RELAY_UNAVAILABLE` after a Codex Desktop update | [1.18.2](CHANGELOG.md#1182---2026-09-26): native caller-source compatibility. [1.22.13](CHANGELOG.md#12213---2026-10-20): discover Windows `codex-app-tools-*` pipes instead of probing only browser pipes. | Update/reload the native companion as well as the sending bridge. Check `native_relay_status`; never copy a foreign process's pipe to bypass discovery. |
 | A Windows task opened successfully, but `open_codex_thread` or relay wake reported failure | [1.22.14](CHANGELOG.md#12214---2026-10-21): replace reliance on `explorer.exe`'s misleading exit code with the native URI launcher. | Upgrade/reconnect and inspect the opened task. A navigation error is not evidence that an accepted prompt should be sent again. |
 | A macOS companion appeared installed but every native delivery was unconfirmed | [1.13.4](CHANGELOG.md#1134---2026-09-06): use the Codex-bundled runtime trusted by Desktop. | Run current setup with Codex Desktop installed and reconnect. Keep the runtime selected by the installer; an arbitrary Homebrew/nvm Node may not satisfy native host checks. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.25.1",
+  "version": "1.25.2",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.25.1",
+  "version": "1.25.2",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.25.1";
+const VERSION = "1.25.2";
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.25.1";
+const VERSION = "1.25.2";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/index.mjs

@@ -37,11 +37,11 @@ import { captureProjectScope } from "./project-scope.mjs";
 import { DesktopReplyReceipts } from "./desktop-reply-receipts.mjs";
 import { registerDesktopReadTools } from "./desktop-read-tools.mjs";
 import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
-import { createRelayWake, relayKeeperEnabled, relayWakeStateFile, startRelayKeeper } from "./relay-wake.mjs";
+import { createRelayWake } from "./relay-wake.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.25.1";
+const VERSION = "1.25.2";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -76,7 +76,7 @@ const desktopTasksEnabled = desktopTasksConfigured();
 const runtime = createRuntimeState({ configuration: desktopTasksConfigured });
 const desktopOperation = new AsyncLocalStorage();
 const replyReceipts = new DesktopReplyReceipts();
-const relayWake = createRelayWake({ senderCwd: () => desktopOperation.getStore()?.caller?.cwd ?? null, stateFile: relayWakeStateFile(), log });
+const relayWake = createRelayWake({ log });
 const desktopTasks = new DesktopTaskDelivery({ security, beforeRequest: beforeDesktopRequest, accountContext: () => desktopOperation.getStore()?.accounts, senderContext: () => desktopOperation.getStore()?.caller, wakeRelay: relayWake });
 
 async function assertDesktopOperation(context, { verifyProcess = false } = {}) {
@@ -1097,7 +1097,6 @@ registerTool(
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-if (desktopTasksEnabled && relayKeeperEnabled()) startRelayKeeper({ wake: relayWake, socketPath: () => desktopTasks.relay.accountSocketPath, log });
 let shutdownPromise;
 const shutdown = () => shutdownPromise ??= (async () => {
   client?.close();

package/src/mcp-supervisor.mjs

@@ -170,6 +170,7 @@ export async function runSupervisor(entry, options = {}) {
   let active;
   let initializeParams;
   let initializeResult;
+  let initializeCatalog;
   let ready = false;
   let switching = false;
   let stopping = false;
@@ -181,6 +182,17 @@ export async function runSupervisor(entry, options = {}) {
   let retryAt = 0;
   let reason = null;
   let reloads = 0;
+  let recoveries = 0;
+  let recoveryAttempts = 0;
+  let recoveryAt = 0;
+  let activeSince = Date.now();
+  const recoveryDelayMs = Math.min(30000, supervisorInterval(env.CODEX_BRIDGE_RECOVERY_DELAY_MS, 1000));
+  const recoveryLimit = 5;
+  const canRecover = () => entry === "native-relay-companion.mjs" && ready && initializeResult && initializeCatalog;
+  const scheduleRecovery = () => {
+    if (recoveryAttempts >= recoveryLimit) return;
+    recoveryAt = Date.now() + Math.min(30000, recoveryDelayMs * 2 ** recoveryAttempts);
+  };
   const queue = [];
   const requests = new Map();
   const reverse = new Map();
@@ -189,7 +201,7 @@ export async function runSupervisor(entry, options = {}) {
     revision: active?.release.revision ?? null, availableRevision: observed,
     routingConfiguration: active?.routingConfiguration ?? null, availableRoutingConfiguration: observedRouting,
     pending: Boolean(observed && (observed !== active?.release.revision || observedRouting !== active?.routingConfiguration)),
-    state: failure ? "failed" : switching ? "reloading" : reason ? "deferred" : "current", reason: failure ?? reason, reloads });
+    state: failure ? canRecover() && recoveryAttempts < recoveryLimit ? "recovering" : "failed" : switching ? "reloading" : reason ? "deferred" : "current", reason: failure ?? reason, reloads, recoveries, recoveryAttempts });
 
   const handlers = {
     message(worker, message) {
@@ -210,12 +222,16 @@ export async function runSupervisor(entry, options = {}) {
       const respond = async () => {
         if (pending.method === "initialize" && !message.error) {
           initializeResult = message.result;
+          if (entry === "native-relay-companion.mjs") {
+            initializeCatalog = await worker.rpc("tools/list", {});
+            if (!Array.isArray(initializeCatalog.tools) || !initializeCatalog.tools.length || initializeCatalog.nextCursor) throw new Error("The native relay tool catalog is incomplete");
+          }
           await worker.control("activate");
           ready = true;
         }
         if (message.result && ["codex_bridge_status", "claude_bridge_status", "native_relay_status"].includes(pending.tool)) {
           message.result.structuredContent = { ...message.result.structuredContent, autoReload: diagnostics() };
-          message.result.content = [...(message.result.content ?? []), { type: "text", text: `automatic reload: ${diagnostics().state}\nsupervisor pid: ${process.pid}\nworker pid: ${worker.process.pid}\nreload count: ${reloads}${reason ? `\nreload detail: ${reason}` : ""}` }];
+          message.result.content = [...(message.result.content ?? []), { type: "text", text: `automatic reload: ${diagnostics().state}\nsupervisor pid: ${process.pid}\nworker pid: ${worker.process.pid}\nreload count: ${reloads}\nrecovery count: ${recoveries}${reason ? `\nreload detail: ${reason}` : ""}` }];
         }
         output({ ...message, id: pending.id });
       };
@@ -228,7 +244,15 @@ export async function runSupervisor(entry, options = {}) {
         worker.clientPending.delete(id);
       }
       for (const [id, pending] of reverse) if (pending.worker === worker) reverse.delete(id);
-      if (worker === active && !worker.retiring && !stopping) { failure = `${error.message}; automatic replay is disabled because delivery state may be unknown`; log(failure); }
+      if (worker === active && !worker.retiring && !stopping) {
+        failure = `${error.message}; automatic replay is disabled because delivery state may be unknown`;
+        if (canRecover()) {
+          if (Date.now() - activeSince >= 60000) recoveryAttempts = 0;
+          scheduleRecovery();
+          if (recoveryAttempts >= recoveryLimit) failure += "; recovery limit reached, reconnect MCP";
+        }
+        log(failure);
+      }
     },
   };
   const spawn = (release, routing) => {
@@ -245,7 +269,56 @@ export async function runSupervisor(entry, options = {}) {
     return worker;
   };
   const check = async () => {
-    if (switching || !ready || stopping || failure) return;
+    if (switching || !ready || stopping) return;
+    if (failure) {
+      if (!canRecover() || recoveryAttempts >= recoveryLimit || Date.now() < recoveryAt) return;
+      switching = true;
+      recoveryAttempts++;
+      const previous = active;
+      let candidate;
+      try {
+        await previous.stop();
+        workers.delete(previous);
+        if (stopping) return;
+        const source = currentRoot();
+        const release = createReleaseSnapshot(source, { expectedRevision: sourceRevision(source), lease: true });
+        candidate = spawn(release, routingConfiguration());
+        const initialized = await candidate.rpc("initialize", initializeParams);
+        if (initialized.protocolVersion !== initializeResult.protocolVersion || JSON.stringify(initialized.capabilities) !== JSON.stringify(initializeResult.capabilities)) {
+          throw new Error("The replacement MCP protocol or capabilities require an explicit client reconnect");
+        }
+        candidate.write({ jsonrpc: "2.0", method: "notifications/initialized" });
+        const catalog = await candidate.rpc("tools/list", {});
+        if (JSON.stringify(catalog) !== JSON.stringify(initializeCatalog)) throw new Error("The replacement tool catalog requires an explicit client reconnect");
+        await candidate.control("activate");
+        if (stopping || candidate.closed) throw new Error("The relay replacement stopped before activation completed");
+        active = candidate;
+        candidate = null;
+        activeSince = Date.now();
+        failure = null;
+        reason = null;
+        recoveries++;
+        log(`recovered native relay worker after exit; recovery ${recoveries}, no requests replayed`);
+        schedulePrune();
+      } catch (error) {
+        failure = `Native relay recovery failed: ${error.message}; no requests were replayed`;
+        if (candidate) {
+          try {
+            await candidate.stop();
+            workers.delete(candidate);
+          } catch (stopError) {
+            recoveryAttempts = recoveryLimit;
+            failure += `; replacement shutdown could not be confirmed: ${stopError.message}`;
+          }
+        }
+        scheduleRecovery();
+        if (recoveryAttempts >= recoveryLimit) failure += "; recovery limit reached, reconnect MCP";
+        log(failure);
+      } finally {
+        switching = false;
+      }
+      return;
+    }
     let source;
     let revision;
     let routing;
@@ -279,8 +352,12 @@ export async function runSupervisor(entry, options = {}) {
       await candidate.control("restore", exported.state);
       await candidate.control("activate");
       if (stopping) throw new Error("The MCP client disconnected during activation");
+      if (candidate.closed) throw new Error("The replacement worker exited during activation");
       active = candidate;
       candidate = null;
+      initializeCatalog = catalog;
+      activeSince = Date.now();
+      failure = null;
       reloads++;
       reason = null;
       if (JSON.stringify(catalog) !== JSON.stringify(oldCatalog)) output({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
@@ -321,7 +398,7 @@ export async function runSupervisor(entry, options = {}) {
       }
       return;
     }
-    if (failure) { if (hasId(message)) output(errorMessage(message.id, failure)); return; }
+    if (failure) { if (hasId(message)) output(errorMessage(message.id, `${failure}${canRecover() && recoveryAttempts < recoveryLimit ? "; native relay recovery is pending, this request was not sent" : ""}`)); return; }
     if (switching || !active) {
       const bytes = queue.reduce((size, queued) => size + Buffer.byteLength(JSON.stringify(queued)), 0);
       if (queue.length >= MAX_QUEUE || bytes + Buffer.byteLength(JSON.stringify(message)) > MAX_FRAME_BYTES) { if (hasId(message)) output(errorMessage(message.id, "Reload request queue is full; no operation was dispatched")); return; }

package/src/native-relay-companion.mjs

@@ -14,6 +14,7 @@ import {
   responseTooLargeError,
   NATIVE_DISPATCH_METHOD,
   NativeToolsClient,
+  NativeDesktopRelay,
   NativeRelayError,
   RELAY_PROTOCOL_VERSION,
   ACCOUNT_RELAY_PROTOCOL_VERSION,
@@ -28,7 +29,7 @@ import {
 } from "./native-relay.mjs";
 import { IS_WINDOWS, PLATFORM_LABEL } from "./platform.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
-import { assertAccountIdentity } from "./bridge-account-context.mjs";
+import { accountIdentity, assertAccountIdentity, readBridgeAccounts } from "./bridge-account-context.mjs";
 import { createReloadControl, drainPendingAccepts, exitWhenClientCloses } from "./reload-control.mjs";
 import { createRuntimeState } from "./runtime-state.mjs";
 import { hardenedBridgeEnabled } from "./hardened-root-policy.mjs";
@@ -42,7 +43,7 @@ import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } fro
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.25.1";
+const VERSION = "1.25.2";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {
@@ -865,6 +866,20 @@ export function createNativeRelayLifecycle({ nativeTools, relays, log: logFn = (
   };
 }
 
+export async function probeRelayDispatch({ env = process.env, timeoutMs = 3000, accounts = readBridgeAccounts, relay = new NativeDesktopRelay({ env, socketPath: desktopTaskSocketPath(env), accountSocketPath: accountRelaySocketPath(env) }) } = {}) {
+  try {
+    const accountContext = accountIdentity(accounts());
+    const response = await relay.requestDesktop("list_projects", {}, {
+      timeoutMs,
+      ...(accountContext ? { accountContext, beforeSend: () => assertAccountIdentity(accountContext) } : {}),
+    });
+    if (!Array.isArray(response?.result?.projects)) throw new Error("Native Desktop did not return a project list");
+    return { ready: true, checkedAt: new Date().toISOString(), scope: "shared-relay-native-dispatch" };
+  } catch (error) {
+    return { ready: false, checkedAt: new Date().toISOString(), scope: "shared-relay-native-dispatch", code: error.code ?? "NATIVE_HEALTH_CHECK_FAILED", reason: error.message };
+  }
+}
+
 export function createRelayServers({ nativeTools, env = process.env, signalExit = true, log: logFn = () => {} }) {
   const hardened = hardenedBridgeEnabled(env);
   if (hardened && !desktopTasksConfigured(env)) throw new Error("CODEX_BRIDGE_HARDENED=1 requires CODEX_BRIDGE_DESKTOP_TASKS=1; legacy relay listeners are disabled");
@@ -938,8 +953,9 @@ if (invokedDirectly) {
       } catch (err) {
         executor = err.message;
       }
+      const nativeDispatch = listening ? await probeRelayDispatch() : { ready: false, reason: "Relay transport is not listening" };
       return {
-        structuredContent: { runtime: runtime.status() },
+        structuredContent: { runtime: runtime.status(), nativeDispatch },
         content: [
           {
             type: "text",
@@ -953,6 +969,7 @@ if (invokedDirectly) {
               `remote Codex:   ${remoteRelay.socketPath} (${await remoteRelay.isListening() ? "listening" : "not listening"})`,
               `executor:       ${executor}`,
               `dispatch:       ${process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD}`,
+              `native dispatch: ${nativeDispatch.ready ? "verified (read-only list_projects)" : `unavailable (${nativeDispatch.reason})`}`,
               `native pipe:    ${nativeTools.socketPath ?? "unavailable (requires Codex Desktop)"}`,
             ].join("\n"),
           },

package/src/native-relay.mjs

@@ -560,9 +560,9 @@ export async function resolveNativeToolsPipePath({
 }
 
 export class NativeToolsClient {
-  constructor({ env = process.env, socketPath = env.CODEX_APP_TOOLS_PIPE_PATH, timeoutMs = DEFAULT_TIMEOUT_MS, resolveSocketPath = () => resolveNativeToolsPipePath({ env }), assertAccount = assertAccountIdentity } = {}) {
+  constructor({ env = process.env, socketPath, timeoutMs = DEFAULT_TIMEOUT_MS, resolveSocketPath = () => resolveNativeToolsPipePath({ env: { ...env, CODEX_APP_TOOLS_PIPE_PATH: undefined } }), assertAccount = assertAccountIdentity } = {}) {
     this.env = env;
-    this.socketPath = socketPath;
+    this.socketPath = socketPath ?? env.CODEX_APP_TOOLS_PIPE_PATH;
     this.explicitSocketPath = socketPath || null;
     this.hasDiscoveredSocket = false;
     this.timeoutMs = timeoutMs;
@@ -581,7 +581,7 @@ export class NativeToolsClient {
     if (this.socket && !this.socket.destroyed) return;
     const generation = this.connectionGeneration;
     this.connecting = (async () => {
-      const socketPath = this.socketPath || await this.resolveSocketPath();
+      const socketPath = this.socketPath || await this.resolveSocketPath() || this.env.CODEX_APP_TOOLS_PIPE_PATH;
       if (generation !== this.connectionGeneration) {
         throw new NativeRelayError("Native tools client closed while discovering the Desktop pipe", "NATIVE_PIPE_UNAVAILABLE");
       }

package/src/platform.mjs

@@ -545,6 +545,7 @@ export async function openThreadInCodexApp(threadId, { activate = true, platform
   if (typeof threadId !== "string" || !threadId) throw new Error("A Codex thread id is required");
   const url = codexThreadUrl(encodeURIComponent(threadId));
   if (platform === "win32") {
+    if (!activate) throw Object.assign(new Error("Windows cannot open a Codex task without activating its window; background navigation is disabled"), { code: "BACKGROUND_NAVIGATION_UNAVAILABLE" });
     const [shell, args] = windowsOpenUrlCommand(url, env);
     await run(shell, args, { windowsHide: true, timeout: 10000 });
     return url;

package/src/relay-wake.mjs

@@ -1,22 +1,6 @@
-import fs from "node:fs";
 import net from "node:net";
-import path from "node:path";
 
-import { codexHome, resolveRelayThreadId } from "./native-relay.mjs";
-import { isCodexDesktopRunning, openThreadInCodexApp } from "./platform.mjs";
-import { captureProjectScope } from "./project-scope.mjs";
-import { readRolloutFirstRecord } from "./rollout-reader.mjs";
-
-const THREAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const ROLLOUT = /^rollout-.+-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl(?:\.zst)?$/i;
 export const RELAY_WAKE_WAIT_MS = 20000;
-export const RELAY_WAKE_COOLDOWN_MS = 60000;
-export const RELAY_KEEPER_INTERVAL_MS = 30000;
-export const RELAY_KEEPER_WAIT_MS = 60000;
-export const RELAY_KEEPER_MAX_BACKOFF_MS = 30 * 60000;
-export const DESKTOP_RECHECK_MS = 60000;
-const MAX_DAY_DIRECTORIES = 14;
-const MAX_CANDIDATES = 40;
 
 export function relayWakeEnabled(env = process.env, platform = process.platform) {
   const value = (env.CODEX_BRIDGE_RELAY_WAKE ?? "").toLowerCase();
@@ -24,71 +8,14 @@ export function relayWakeEnabled(env = process.env, platform = process.platform)
   return platform === "darwin" || platform === "win32";
 }
 
-function dayDirectories(sessions) {
-  const directories = [];
-  const children = (directory, pattern) => {
-    try { return fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && pattern.test(entry.name)).map((entry) => entry.name).sort().reverse(); }
-    catch { return []; }
-  };
-  for (const year of children(sessions, /^\d{4}$/)) {
-    for (const month of children(path.join(sessions, year), /^\d{2}$/)) {
-      for (const day of children(path.join(sessions, year, month), /^\d{2}$/)) {
-        directories.push(path.join(sessions, year, month, day));
-        if (directories.length >= MAX_DAY_DIRECTORIES) return directories;
-      }
-    }
-  }
-  return directories;
-}
-
-function sameProject(senderCwd, taskCwd) {
-  try { captureProjectScope(senderCwd, taskCwd); return true; }
-  catch { return false; }
-}
-
-export function relayKeeperEnabled(env = process.env, platform = process.platform) {
-  const value = (env.CODEX_BRIDGE_RELAY_KEEPER ?? "").toLowerCase();
-  if (["0", "off", "false"].includes(value)) return false;
-  if (!relayWakeEnabled(env, platform)) return false;
-  if (platform === "win32") return ["1", "on", "true"].includes(value);
-  return true;
-}
-
-export function relayWakeStateFile(env = process.env) {
-  return path.join(codexHome(env), "bridge-relay-wake.json");
-}
-
-export async function recentDesktopTaskFor(cwd, { env = process.env, sessions = path.join(codexHome(env), "sessions"), exclude = [], anyProject = false } = {}) {
-  if (!anyProject && (typeof cwd !== "string" || !cwd)) return null;
-  const excluded = new Set(exclude.filter(Boolean));
-  const candidates = [];
-  for (const directory of dayDirectories(sessions)) {
-    let entries;
-    try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { continue; }
-    for (const entry of entries) {
-      const match = entry.isFile() ? ROLLOUT.exec(entry.name) : null;
-      if (!match || excluded.has(match[1])) continue;
-      const file = path.join(directory, entry.name);
-      try { candidates.push({ file, threadId: match[1], mtimeMs: fs.lstatSync(file).mtimeMs }); } catch {}
-    }
-    if (candidates.length >= MAX_CANDIDATES) break;
-  }
-  candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
-  for (const candidate of candidates.slice(0, MAX_CANDIDATES)) {
-    let record;
-    try { record = await readRolloutFirstRecord(candidate.file, { maxBytes: 256 * 1024 }); } catch { continue; }
-    const meta = record?.type === "session_meta" ? record.payload : null;
-    if (meta?.id !== candidate.threadId || meta.originator !== "Codex Desktop" || typeof meta.cwd !== "string") continue;
-    if (anyProject || sameProject(cwd, meta.cwd)) return candidate.threadId;
-  }
-  return null;
-}
-
 export function endpointAnswers(socketPath, { timeoutMs = 1000 } = {}) {
   if (typeof socketPath !== "string" || !socketPath) return Promise.resolve(false);
   return new Promise((resolve) => {
     const probe = net.connect({ path: socketPath });
+    let settled = false;
     const done = (answer) => {
+      if (settled) return;
+      settled = true;
       globalThis.clearTimeout(timer);
       probe.destroy();
       resolve(answer);
@@ -96,163 +23,33 @@ export function endpointAnswers(socketPath, { timeoutMs = 1000 } = {}) {
     const timer = globalThis.setTimeout(() => done(false), timeoutMs);
     probe.once("connect", () => done(true));
     probe.once("error", () => done(false));
+    probe.once("close", () => done(false));
   });
 }
 
-function readWakeState(file) {
-  if (!file) return {};
-  try {
-    const state = JSON.parse(fs.readFileSync(file, "utf8"));
-    return state && typeof state === "object" && !Array.isArray(state) ? state : {};
-  } catch { return {}; }
-}
-
-function writeWakeState(file, state) {
-  if (!file) return;
-  const temporary = `${file}.${process.pid}.tmp`;
-  try {
-    fs.writeFileSync(temporary, JSON.stringify(state));
-    fs.renameSync(temporary, file);
-  } catch { try { fs.rmSync(temporary, { force: true }); } catch {} }
-}
-
-function acquireWakeLock(file, now, staleMs) {
-  if (!file) return () => {};
-  const lock = `${file}.lock`;
-  const claim = () => {
-    const descriptor = fs.openSync(lock, "wx");
-    try { fs.writeSync(descriptor, JSON.stringify({ pid: process.pid, at: now() })); } finally { fs.closeSync(descriptor); }
-    return () => { try { fs.rmSync(lock, { force: true }); } catch {} };
-  };
-  try { return claim(); }
-  catch (error) { if (error.code !== "EEXIST") return null; }
-  let heldSince;
-  try { heldSince = JSON.parse(fs.readFileSync(lock, "utf8")).at; } catch { heldSince = 0; }
-  if (Number.isFinite(heldSince) && now() - heldSince < staleMs) return null;
-  try { fs.rmSync(lock, { force: true }); return claim(); } catch { return null; }
-}
-
-export function keeperBackoffMs(failures, { baseMs = RELAY_WAKE_COOLDOWN_MS, maxMs = RELAY_KEEPER_MAX_BACKOFF_MS } = {}) {
-  const count = Number.isInteger(failures) && failures > 0 ? Math.min(failures, 16) : 0;
-  return count === 0 ? 0 : Math.min(baseMs * 2 ** (count - 1), maxMs);
-}
-
 export function createRelayWake({
   env = process.env,
   enabled = relayWakeEnabled(env),
-  desktopRunning = () => isCodexDesktopRunning(),
-  senderCwd = () => null,
-  findTask = (cwd, exclude) => recentDesktopTaskFor(cwd, { env, exclude }),
-  findAnyTask = (exclude) => recentDesktopTaskFor(null, { env, exclude, anyProject: true }),
-  executorThreadId = () => { try { return resolveRelayThreadId(env).threadId; } catch { return null; } },
-  open = (threadId) => openThreadInCodexApp(threadId, { activate: false }),
   answers = endpointAnswers,
   waitMs = RELAY_WAKE_WAIT_MS,
-  backgroundWaitMs = RELAY_KEEPER_WAIT_MS,
-  cooldownMs = RELAY_WAKE_COOLDOWN_MS,
-  desktopRecheckMs = DESKTOP_RECHECK_MS,
-  stateFile = null,
   pollMs = 250,
   now = Date.now,
   sleep = (ms) => new Promise((resolve) => globalThis.setTimeout(resolve, ms)),
   log = () => {},
 } = {}) {
-  let inFlight = null;
-  let failedAt = -Infinity;
-  const waitFor = async (socketPath, until) => {
+  return async ({ socketPath, deadline }) => {
+    if (!enabled || typeof socketPath !== "string" || !socketPath) return null;
+    const until = Math.min(now() + waitMs, deadline ?? Infinity);
     while (now() < until) {
-      if (await answers(socketPath)) return true;
-      await sleep(pollMs);
-    }
-    return false;
-  };
-  const attempt = async ({ socketPath, threadId, deadline, background = false }) => {
-    if (!enabled) return null;
-    const state = readWakeState(stateFile);
-    if (background) {
-      if (state.desktopRunning === false && now() - (state.desktopCheckedAt ?? -Infinity) < desktopRecheckMs) return null;
-      if (now() - (state.attemptAt ?? -Infinity) < Math.max(keeperBackoffMs(state.failures), cooldownMs)) return null;
-    } else if (now() - failedAt < cooldownMs) return null;
-    const running = await desktopRunning();
-    if (stateFile) writeWakeState(stateFile, { ...readWakeState(stateFile), desktopCheckedAt: now(), desktopRunning: Boolean(running) });
-    if (!running) return null;
-    const wait = background ? backgroundWaitMs : waitMs;
-    const release = acquireWakeLock(stateFile, now, wait + 15000);
-    if (!release) {
-      if (background) return null;
-      return await waitFor(socketPath, Math.min(now() + wait, deadline ?? Infinity)) ? { threadId: null } : null;
-    }
-    try {
-      const executor = executorThreadId();
-      const target = typeof threadId === "string" && THREAD_ID.test(threadId) && threadId !== executor
-        ? threadId : (await findTask(senderCwd(), [executor])) ?? (await findAnyTask([executor]));
-      const startedAt = now();
-      const failures = Number.isInteger(state.failures) ? state.failures : 0;
-      if (!target) {
-        if (background && stateFile) writeWakeState(stateFile, { ...readWakeState(stateFile), attemptAt: startedAt, failures: failures + 1 });
-        return null;
+      if (await answers(socketPath, { timeoutMs: Math.min(1000, until - now()) })) {
+        if (now() >= until) return null;
+        log("relay transport available; the original operation will verify native dispatch");
+        return { threadId: null };
       }
-      const fail = (message) => {
-        failedAt = now();
-        if (stateFile) writeWakeState(stateFile, { ...readWakeState(stateFile), attemptAt: startedAt, failures: failures + 1 });
-        log(message);
-        return null;
-      };
-      try { await open(target); }
-      catch (error) { return fail(`could not open Codex task ${target} to start the native relay: ${error.message}`); }
-      if (await waitFor(socketPath, Math.min(now() + wait, deadline ?? Infinity))) {
-        if (stateFile) writeWakeState(stateFile, { ...readWakeState(stateFile), attemptAt: startedAt, failures: 0 });
-        log(`started the Codex Desktop native relay by opening task ${target} in the background`);
-        return { threadId: target };
-      }
-      return fail(`opened Codex task ${target}, but the native relay did not start within ${wait} ms`);
-    } finally {
-      release();
+      const remaining = until - now();
+      if (remaining > 0) await sleep(Math.min(pollMs, remaining));
     }
-  };
-  return (request) => {
-    if (!inFlight) return inFlight = attempt(request).finally(() => { inFlight = null; });
-    if (request.background || !request.socketPath) return inFlight;
-    const until = Math.min(now() + waitMs, request.deadline ?? Infinity);
-    return Promise.race([inFlight, waitFor(request.socketPath, until).then((ready) => ready ? { threadId: null } : null)]);
-  };
-}
-
-export function startRelayKeeper({
-  wake,
-  socketPath,
-  answers = endpointAnswers,
-  intervalMs = RELAY_KEEPER_INTERVAL_MS,
-  initialDelayMs = 3000,
-  timers = globalThis,
-  log = () => {},
-}) {
-  let busy = false;
-  let stopped = false;
-  const tick = async () => {
-    if (busy || stopped) return null;
-    busy = true;
-    try {
-      const target = socketPath();
-      if (await answers(target)) return null;
-      return await wake({ socketPath: target, background: true });
-    } catch (error) {
-      log(`relay keeper check failed: ${error.message}`);
-      return null;
-    } finally {
-      busy = false;
-    }
-  };
-  const first = timers.setTimeout(tick, initialDelayMs);
-  const repeat = timers.setInterval(tick, intervalMs);
-  first?.unref?.();
-  repeat?.unref?.();
-  return {
-    tick,
-    stop() {
-      stopped = true;
-      timers.clearTimeout(first);
-      timers.clearInterval(repeat);
-    },
+    log("native relay recovery timed out; no task or window was opened");
+    return null;
   };
 }

package/src/thread-delivery.mjs

@@ -74,7 +74,7 @@ export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync
   return matches[0];
 }
 
-export const RELAY_DOWN_GUIDANCE = "The Codex Desktop native relay is not listening: Codex Desktop runs codex-native-relay only while a task has its MCP servers loaded. Open any regular project task (not the internal Native Relay executor task) and send it a turn or reconnect its MCP servers, then retry.";
+export const RELAY_DOWN_GUIDANCE = "The Codex Desktop native relay is not listening after waiting for silent recovery. Its Desktop-owned supervisor restarts crashed relay workers without replaying requests. If Desktop has not loaded the relay MCP, reconnect it in a regular project task; automatic recovery never opens a task or window. Do not open the internal Native Relay executor task.";
 
 function relayUnreachable(error) {
   return error?.code === "RELAY_UNREACHABLE" && error.sent === false;
@@ -126,23 +126,25 @@ export class DesktopTaskDelivery {
       if (scopeBinding) this.security.hardenedRoots.recheck(scopeBinding);
       const projectScope = expectedScope ?? await this.mutationProjectScope(operation, args, { deadline });
       if (expectedScope) recheckProjectScope(expectedScope, this.senderProjectScope(expectedScope.recipient.input));
-      const remaining = deadline === undefined ? undefined : deadline - this.now();
-      if (remaining !== undefined && remaining <= 0) throw Object.assign(new Error("The bridge's response deadline has elapsed; this operation was not sent"), { code: "DESKTOP_RESPONSE_DEADLINE" });
       const accountContext = this.accountContext?.();
-      const send = () => this.relay.requestDesktop(operation, args, {
-        ...(remaining === undefined ? {} : { timeoutMs: remaining }),
-        ...(this.beforeRequest || projectScope || scopeBinding ? { beforeSend: async () => {
-          await this.beforeRequest?.({ operation, args, phase: "write" });
-          if (projectScope) {
-            recheckProjectScope(projectScope);
-            recheckProjectScope(projectScope, await this.mutationProjectScope(operation, args, { deadline }));
-          }
-          await this.beforeRequest?.({ operation, args, phase: "dispatch" });
-          if (scopeBinding) this.security.hardenedRoots.recheck(scopeBinding);
-        } } : {}),
-        ...(accountContext ? { accountContext } : {}),
-        ...(creationReceiptId ? { creationReceiptId } : {}),
-      });
+      const send = () => {
+        const remaining = deadline === undefined ? undefined : deadline - this.now();
+        if (remaining !== undefined && remaining <= 0) throw Object.assign(new Error("The bridge's response deadline has elapsed; this operation was not sent"), { code: "DESKTOP_RESPONSE_DEADLINE" });
+        return this.relay.requestDesktop(operation, args, {
+          ...(remaining === undefined ? {} : { timeoutMs: remaining }),
+          ...(this.beforeRequest || projectScope || scopeBinding ? { beforeSend: async () => {
+            await this.beforeRequest?.({ operation, args, phase: "write" });
+            if (projectScope) {
+              recheckProjectScope(projectScope);
+              recheckProjectScope(projectScope, await this.mutationProjectScope(operation, args, { deadline }));
+            }
+            await this.beforeRequest?.({ operation, args, phase: "dispatch" });
+            if (scopeBinding) this.security.hardenedRoots.recheck(scopeBinding);
+          } } : {}),
+          ...(accountContext ? { accountContext } : {}),
+          ...(creationReceiptId ? { creationReceiptId } : {}),
+        });
+      };
       let response;
       try {
         response = await send();