@minhspark/codex-mcp-bridge 1.25.2 → 1.26.0

package/src/claude-session-router.mjs

@@ -1,6 +1,5 @@
 import { assertClaudeSessionCwd } from "./peer-protocol.mjs";
 import { preflightFailure } from "./recipient-preflight.mjs";
-import { setTimeout as delay } from "node:timers/promises";
 
 function assertCwd(session, expectedCwd) {
   try {
@@ -24,13 +23,13 @@ function uniqueLiveSessions(sessions) {
   return [...unique.values()];
 }
 
-export async function recoverClaudeDesktopSession(args, { listTasks, listSessions, open, beforeOpen, sleep = delay, timeoutMs = 15000 }) {
+export async function recoverClaudeDesktopSession(args, { listTasks, listSessions, beforeInspect }) {
   try { return { session: resolveClaudeDesktopSession(args) }; }
   catch (error) {
     if (error.preflight?.code !== "CLAUDE_SESSION_NOT_FOUND" || args.target !== "auto" || !args.expectedTaskId) throw error;
   }
   const assertTask = async () => {
-    await beforeOpen();
+    await beforeInspect();
     const tasks = await listTasks();
     if (!Array.isArray(tasks) || tasks.length > 8192) throw preflightFailure("CLAUDE_DESKTOP_TASK_UNVERIFIED", "Saved Desktop tasks cannot be verified.");
     const matches = tasks.filter((task) => task.taskId === args.expectedTaskId);
@@ -41,17 +40,11 @@ export async function recoverClaudeDesktopSession(args, { listTasks, listSession
     return matches[0];
   };
   const task = await assertTask();
-  try { await open(task.taskId); }
-  catch { return { recovery: { status: "launch_uncertain", sent: false, taskId: task.taskId, cwd: args.expectedCwd, reason: "The exact Desktop task could not be confirmed open. Inspect this task before retrying; no message was sent." } }; }
-  const deadline = Date.now() + timeoutMs;
-  for (;;) {
-    await assertTask();
-    try { return { session: resolveClaudeDesktopSession({ ...args, sessions: await listSessions() }) }; }
-    catch (error) { if (error.preflight?.code !== "CLAUDE_SESSION_NOT_FOUND") throw error; }
-    if (Date.now() >= deadline) break;
-    await sleep(Math.min(250, Math.max(0, deadline - Date.now())));
-  }
-  return { recovery: { status: "awaiting_session", sent: false, taskId: task.taskId, cwd: args.expectedCwd, reason: "The exact saved task was opened in Claude Desktop and is reconnecting. Retry target auto with this expectedTaskId; no message has been sent." } };
+  const sessions = await listSessions();
+  await assertTask();
+  try { return { session: resolveClaudeDesktopSession({ ...args, sessions }) }; }
+  catch (error) { if (error.preflight?.code !== "CLAUDE_SESSION_NOT_FOUND") throw error; }
+  throw Object.assign(preflightFailure("CLAUDE_SESSION_NOT_READY", "The exact saved Claude Desktop task has no live native Code endpoint. Background delivery requires that endpoint; this bridge has no supported silent cold-start API. No app or chat was opened. Inspect claude_bridge_status and report this diagnostic; do not create or open a chat to load the relay."), { taskId: task.taskId, phase: "recipient_discovery" });
 }
 
 export function sameClaudeDesktopRecipient(selected, current) {
@@ -133,7 +126,7 @@ export function resolveClaudeDesktopSession({ target, expectedCwd, expectedTaskI
     throw preflightFailure("CLAUDE_SESSION_AMBIGUOUS", "Multiple live Claude Desktop sessions match the current account and intended project/task; inspect the intended task and provide its exact identity.");
   }
   if (!candidates.length) {
-    throw preflightFailure("CLAUDE_SESSION_NOT_FOUND", "No live Claude Desktop session matches the current account and intended project/task. Open or reconnect the existing task in Claude Desktop.");
+    throw preflightFailure("CLAUDE_SESSION_NOT_FOUND", "No live Claude Desktop session matches the current account and intended project/task. Inspect list_claude_sessions and claude_bridge_status; do not open or create a chat to load the relay.");
   }
   return candidates[0];
 }

package/src/index.mjs

@@ -38,10 +38,13 @@ 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 } from "./relay-wake.mjs";
+import { withBridgeDiagnostic } from "./recipient-preflight.mjs";
+import { BACKGROUND_TOOLS } from "./background-relay-config.mjs";
+import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./background-relay-mcp.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.25.2";
+const VERSION = "1.26.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -52,9 +55,7 @@ const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
  */
 const DEFAULT_MODEL = process.env.CODEX_BRIDGE_MODEL || null;
 const DEFAULT_EFFORT = process.env.CODEX_BRIDGE_EFFORT || null;
-const DEFAULT_OPEN_IN_APP = process.env.CODEX_BRIDGE_OPEN_IN_APP
-  ? process.env.CODEX_BRIDGE_OPEN_IN_APP === "1"
-  : IS_WINDOWS;
+const DEFAULT_OPEN_IN_APP = process.env.CODEX_BRIDGE_OPEN_IN_APP === "1";
 const DEFAULT_RELEASE_AFTER_TURN = process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN
   ? process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN === "1"
   : IS_WINDOWS;
@@ -155,15 +156,18 @@ const textResult = (text, isError = false) => ({
   ...(isError ? { isError: true } : {}),
 });
 
-const failure = (err) => {
+const failure = (err, options = {}) => {
   const result = textResult(`Codex bridge error: ${err?.message ?? String(err)}`, true);
-  for (let cause = err; cause; cause = cause.cause) {
+  const seen = new Set();
+  for (let cause = err; cause && !seen.has(cause) && seen.size < 8; cause = cause.cause) {
+    seen.add(cause);
     if (["RESPONSE_TOO_LARGE", "INVALID_RESPONSE_PREFERENCES", "INVALID_CURSOR", "CURSOR_EXPIRED"].includes(cause.code)) {
       result.structuredContent = { error: Object.fromEntries(["code", "boundary", "bytes", "limit"].filter((key) => cause[key] !== undefined).map((key) => [key, cause[key]])) };
       break;
     }
   }
-  return result;
+  return withBridgeDiagnostic(result, err, { component: "codex-bridge", operation: desktopOperation.getStore()?.name,
+    ...(desktopOperation.getStore() ? { deliveryState: desktopOperation.getStore().dispatched ? "unknown" : "not_sent", readOnly: desktopOperation.getStore().readOnly ?? desktopOperation.getStore().diagnostic } : {}), ...options });
 };
 
 function replyResult(delivered, deliveryId, result, notes = []) {
@@ -173,10 +177,14 @@ function replyResult(delivered, deliveryId, result, notes = []) {
   const observationUnavailable = result.status === "observation_unavailable";
   if (observationUnavailable) notes = [...notes, OBSERVATION_UNAVAILABLE_GUIDANCE];
   const continuation = deliveryId ? `deliveryId: ${deliveryId}\n${pending ? "Continue automatically with wait_codex_reply and this deliveryId; it only observes the original send. Do not resend the prompt." : "Keep this deliveryId to inspect the same send after reconnecting."}` : "";
-  return {
+  const output = {
     ...textResult([...notes, `deliveryStatus: ${deliveryStatus}`, formatTurn(result, { desktop: true }), continuation].filter(Boolean).join("\n"), result.status === "failed" || result.status === "systemError"),
     structuredContent: { ...result, threadId: delivered.threadId, deliveryStatus, ...(deliveryId ? { deliveryId } : {}), nextAction: observationUnavailable ? "inspect_existing_task" : pending && deliveryId ? "wait_codex_reply" : "none" },
   };
+  return output.isError ? withBridgeDiagnostic(output, new Error("The native Codex turn failed. Inspect the original delivery receipt and local tool output for details."), {
+    component: "codex-bridge", operation: desktopOperation.getStore()?.name, code: result.status === "failed" ? "CODEX_TURN_FAILED" : "CODEX_TURN_SYSTEM_ERROR",
+    deliveryState: deliveryStatus === "accepted" ? "sent" : "unknown", deliveryId, threadId: delivered.threadId,
+  }) : output;
 }
 
 /**
@@ -245,7 +253,7 @@ function creationVerificationFailure({ created, deliveryId, requestId, err }) {
     threadId ? "Task was accepted; do not resend. Resolve the verification error, then continue observing with wait_codex_reply and this deliveryId." : "Do not resend or create again. Continue observing with wait_codex_reply and this deliveryId.");
   return {
     ...textResult(lines.join("\n"), true),
-    structuredContent: { ...failure(err).structuredContent, threadId, deliveryStatus: threadId ? "accepted" : "unconfirmed", ...(deliveryId ? { deliveryId } : {}), nextAction: deliveryId ? "wait_codex_reply" : "none" },
+    structuredContent: { ...failure(err, { deliveryState: threadId ? "sent" : "unknown", readOnly: false, requestId, deliveryId, threadId }).structuredContent, threadId, deliveryStatus: threadId ? "accepted" : "unconfirmed", ...(deliveryId ? { deliveryId } : {}), nextAction: deliveryId ? "wait_codex_reply" : "none" },
   };
 }
 
@@ -449,21 +457,23 @@ const server = new McpServer(
       "In legacy app-server mode, use delegate_to_codex with the initial prompt and omit requestId; durable creation deduplication is unavailable there. " +
       "Reuse that requestId only for retries of that creation. Continue unfinished work, fixes, clarifications, and results in its verified original threadId with send_to_codex_thread. " +
       "A completed turn alone does not mean the task is finished. Do not choose an old task merely because its project matches or it was recently active. " +
-      "Without authorization to create a new conversation, ask before creating it. With Desktop tasks enabled it assigns the exact saved project and starts visibly in " +
-      "Codex Desktop using Desktop permissions. Otherwise it releases the bridge writer lock and opens the exact thread in " +
-      "Codex Desktop. Desktop creation and sends always require the verified calling Claude task and the Codex destination to belong to the same project, even when cwd is omitted. " +
+      "Without authorization to create a new conversation, ask before creating it. With Desktop tasks enabled it assigns the exact saved project using Desktop permissions. Normal delivery does not navigate or focus a window. " +
+      "Never use Computer Use or open an old, new, empty or failed chat to load a relay. Report the Bridge diagnostic block when the native endpoint is unavailable. " +
+      "Desktop creation and sends always require the verified calling Claude task and the Codex destination to belong to the same project, even when cwd is omitted. " +
       "Use send_to_codex_thread only when an existing threadId is intentional; use " +
       "list_codex_threads or read_codex_thread to inspect sessions and codex_bridge_status to inspect wiring. " +
       "When a Desktop send returns nextAction=wait_codex_reply, continue observing with that tool and the returned deliveryId until completion, user input is required, or the user stops the task. Never resend to obtain a reply. Each observation is bounded, and the receipt survives reconnection. " +
-      AGENT_PROMPT_GUIDANCE,
+      BACKGROUND_WORKER_GUIDANCE + AGENT_PROMPT_GUIDANCE,
   },
 );
 
 function registerTool(name, definition, handler) {
   server.registerTool(name, definition, async (...args) => {
+    let result;
     try {
-      return await reload.run(async () => {
+      result = await reload.run(async () => {
       if (!definition.annotations?.readOnlyHint) runtime.assertCurrent();
+      if (BACKGROUND_TOOLS.includes(name)) return handler(...args);
       if (name === "codex_bridge_status") {
         const state = runtime.status();
         if (!state.current) return { ...failure(new Error(`${state.reason}; reconnect this MCP server in the existing task.`)), structuredContent: { runtime: state } };
@@ -482,8 +492,8 @@ function registerTool(name, definition, handler) {
         const accounts = readBridgeAccounts();
         const identity = requireBridgeAccounts(accounts);
         const caller = requireClaudeSenderContext(await readClaudeSenderContext({ account: accounts.claude }));
-        const context = { accounts: identity, caller, dispatched: false, deadline, projectSetup: PROJECT_SETUP_TOOLS.has(name) };
         const readOnly = definition.annotations?.readOnlyHint === true;
+        const context = { name, accounts: identity, caller, dispatched: false, deadline, readOnly, projectSetup: PROJECT_SETUP_TOOLS.has(name) };
         const guidance = deliveryReadGuidance(name, args[0]);
         return await desktopOperation.run(context, async () => {
           let completed = false;
@@ -505,11 +515,18 @@ function registerTool(name, definition, handler) {
       return await handler(...args);
       });
     } catch (err) {
-      return failure(err);
+      result = failure(err);
     }
+    return result.isError ? withBridgeDiagnostic(result, result.structuredContent?.error ?? new Error("The Codex bridge operation failed. Inspect the local tool result for details."), {
+      component: "codex-bridge", operation: name, readOnly: definition.annotations?.readOnlyHint === true,
+      requestId: args[0]?.requestId, deliveryId: result.structuredContent?.deliveryId ?? args[0]?.deliveryId,
+      threadId: result.structuredContent?.threadId ?? args[0]?.threadId,
+    }) : result;
   });
 }
 
+registerBackgroundTools(registerTool);
+
 registerDesktopReadTools(registerTool, {
   desktopTasksEnabled, desktopTasks, replyReceipts, security, client,
   context: () => desktopOperation.getStore(), assertOperation: assertDesktopOperation,
@@ -550,7 +567,7 @@ registerTool(
       openInApp: z
         .boolean()
         .optional()
-        .describe("Show the task in Codex Desktop; native tasks open immediately while running"),
+        .describe("Explicitly show the task in Codex Desktop while it runs. Default is false unless CODEX_BRIDGE_OPEN_IN_APP=1; normal delivery does not navigate or focus a window."),
       releaseAfterTurn: z
         .boolean()
         .optional()
@@ -648,7 +665,7 @@ registerTool(
       openInApp: z
         .boolean()
         .optional()
-        .describe("Open the thread in Codex Desktop on Windows or macOS so a human can watch it live"),
+        .describe("Explicitly open the thread in Codex Desktop so a human can watch it live. Default is false unless CODEX_BRIDGE_OPEN_IN_APP=1; normal delivery does not navigate or focus a window."),
       releaseAfterTurn: z
         .boolean()
         .optional()
@@ -1025,12 +1042,12 @@ registerTool(
     if (desktopTasksEnabled) {
       const native = await desktopTasks.status();
       const sender = await readClaudeSenderContext({ account: readBridgeAccounts().claude });
-      const readiness = bridgeReadiness({ sender, scope: security.hardenedRoots.mode === "project-policy" ? security.hardenedRoots : { assert: (candidate) => { security.assertCwd(candidate); return candidate; } }, targetCwd: cwd, nativeAvailable: native.available, verifyTargetProject: captureProjectScope });
+      const readiness = bridgeReadiness({ sender, scope: security.hardenedRoots.mode === "project-policy" ? security.hardenedRoots : { assert: (candidate) => { security.assertCwd(candidate); return candidate; } }, targetCwd: cwd, nativeAvailable: native.available, nativeDiagnostic: native.diagnostic, verifyTargetProject: captureProjectScope });
       return { ...textResult([
         `platform:       ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
         `bridge version: ${VERSION}`,
         `node:           ${process.version} at ${process.execPath}`,
-        "desktop tasks:  enabled; Desktop permissions, exact saved project, immediate visibility",
+        "desktop tasks:  enabled; Desktop permissions, exact saved project, silent delivery",
         "project scope:  verified Claude sender; same directory or Git repository, checked before each mutation",
         `native relay:   ${native.available ? "available; verified through Codex Desktop" : "unavailable"}`,
         `native endpoint: ${native.socketPath}`,
@@ -1043,7 +1060,7 @@ registerTool(
         ...(readiness.projectPolicy ? [`project policy: ${readiness.projectPolicy.file}; revision ${readiness.projectPolicy.revision ?? "unavailable"}; changes apply on the next operation`] : []),
         ...(readiness.target ? [`target: ${readiness.target.cwd}; authorized=${readiness.target.authorized}${readiness.target.authorizedBy ? `; via ${readiness.target.authorizedBy.kind} ${readiness.target.authorizedBy.path}` : ""}`] : []),
         ...readiness.issues.map((issue) => `${issue.code}: ${issue.detail ?? ""} ${issue.action}`),
-      ].join("\n"), !readiness.ready), structuredContent: { readiness, projectScope: { enabled: true, policy: "verified-sender-same-project", match: "canonical-directory-or-git-repository", checkedBeforeMutation: true } } };
+      ].join("\n"), !readiness.ready), structuredContent: { readiness, native, ...(native.diagnostic ? { diagnostic: native.diagnostic } : !readiness.ready ? { error: { code: readiness.issues[0]?.code, message: readiness.issues[0]?.detail } } : {}), projectScope: { enabled: true, policy: "verified-sender-same-project", match: "canonical-directory-or-git-repository", checkedBeforeMutation: true } } };
     }
     const up = await client.isServerUp();
     let liveThreads = null;
@@ -1106,4 +1123,4 @@ const shutdown = () => shutdownPromise ??= (async () => {
 process.stdin.once("end", () => { void shutdown().catch((error) => log(`shutdown failed: ${error.message}`)); });
 process.once("disconnect", () => { void shutdown().catch((error) => log(`shutdown failed: ${error.message}`)); });
 reload.listen();
-log(desktopTasksEnabled ? `ready on ${PLATFORM_LABEL} (Codex Desktop only; external app-server disabled)` : `ready on ${PLATFORM_LABEL} (app-server endpoint: ${client.url}, codex: ${client.codexBin})`);
+log(desktopTasksEnabled ? `MCP initialized on ${PLATFORM_LABEL}; native readiness is checked per operation (external app-server disabled)` : `MCP initialized on ${PLATFORM_LABEL} (app-server endpoint: ${client.url}, codex: ${client.codexBin})`);

package/src/mcp-supervisor.mjs

@@ -7,16 +7,21 @@ import { createReleaseSnapshot, pruneReleaseSnapshots, snapshotRoot, sourceRevis
 import { desktopTasksConfigured } from "./native-relay.mjs";
 import { isMainModule, stableInstallPath } from "./install-paths.mjs";
 import { CLIENT_CLOSE_DRAIN_MS, CLIENT_CLOSE_STOP_MS } from "./reload-control.mjs";
+import { withBridgeDiagnostic } from "./recipient-preflight.mjs";
 
 const WORKER_NODE = stableInstallPath(process.execPath);
-const ENTRIES = new Set(["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"]);
+const ENTRIES = new Set(["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs", "antigravity-bridge.mjs", "antigravity-outbound-bridge.mjs"]);
+const ANTIGRAVITY_ENTRIES = new Set(["antigravity-bridge.mjs", "antigravity-outbound-bridge.mjs"]);
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
 const MAX_QUEUE = 256;
 const RETIRE_GRACE_MS = 6000;
 const CLIENT_CLOSE_GRACE_MS = CLIENT_CLOSE_DRAIN_MS + CLIENT_CLOSE_STOP_MS + 1000;
 const hasId = (message) => Object.hasOwn(message, "id");
 const idKey = (id) => JSON.stringify(id);
-const errorMessage = (id, message) => ({ jsonrpc: "2.0", id, error: { code: -32603, message } });
+const errorMessage = (id, message, options = {}) => {
+  const result = withBridgeDiagnostic({ content: [] }, new Error(message), { component: "mcp-supervisor", code: "MCP_WORKER_UNAVAILABLE", ...options });
+  return { jsonrpc: "2.0", id, error: { code: -32603, message: `${message}\n${result.content[0].text}`, data: { diagnostic: result.structuredContent.diagnostic } } };
+};
 
 export function supervisorInterval(value, fallback) {
   const parsed = Number(value);
@@ -147,7 +152,7 @@ class Worker {
 }
 
 export async function runSupervisor(entry, options = {}) {
-  if (!ENTRIES.has(entry)) throw new Error("Expected index.mjs, claude-bridge.mjs, or native-relay-companion.mjs");
+  if (!ENTRIES.has(entry)) throw new Error(`Expected one of: ${[...ENTRIES].join(", ")}`);
   const installRoot = stableInstallPath(fs.realpathSync.native(options.root ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")));
   const currentRoot = () => fs.realpathSync.native(installRoot);
   const root = currentRoot();
@@ -158,7 +163,8 @@ export async function runSupervisor(entry, options = {}) {
   const log = (message) => process.stderr.write(`[bridge-supervisor] ${message}\n`);
   const output = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
   const env = { ...process.env, CODEX_BRIDGE_SOURCE_ROOT: installRoot };
-  const routingConfiguration = () => entry === "native-relay-companion.mjs" ? null : desktopTasksConfigured(env);
+  const recoverable = entry === "native-relay-companion.mjs" || ANTIGRAVITY_ENTRIES.has(entry);
+  const routingConfiguration = () => recoverable ? null : desktopTasksConfigured(env);
   if (entry === "native-relay-companion.mjs" && !env.CODEX_APP_TOOLS_PIPE_PATH) {
     const { resolveNativeToolsPipePath } = await import("./native-relay.mjs");
     const pipe = await resolveNativeToolsPipePath();
@@ -188,7 +194,7 @@ export async function runSupervisor(entry, options = {}) {
   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 canRecover = () => recoverable && ready && initializeResult && initializeCatalog;
   const scheduleRecovery = () => {
     if (recoveryAttempts >= recoveryLimit) return;
     recoveryAt = Date.now() + Math.min(30000, recoveryDelayMs * 2 ** recoveryAttempts);
@@ -222,25 +228,25 @@ export async function runSupervisor(entry, options = {}) {
       const respond = async () => {
         if (pending.method === "initialize" && !message.error) {
           initializeResult = message.result;
-          if (entry === "native-relay-companion.mjs") {
+          if (recoverable) {
             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");
+            if (!Array.isArray(initializeCatalog.tools) || !initializeCatalog.tools.length || initializeCatalog.nextCursor) throw new Error("The bridge 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)) {
+        if (message.result && ["codex_bridge_status", "claude_bridge_status", "native_relay_status", "antigravity_bridge_status", "agent_bridge_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}\nrecovery count: ${recoveries}${reason ? `\nreload detail: ${reason}` : ""}` }];
         }
         output({ ...message, id: pending.id });
       };
-      void respond().catch((error) => { failure = error.message; output(errorMessage(pending.id, error.message)); });
+      void respond().catch((error) => { failure = error.message; output(errorMessage(pending.id, error.message, { code: "MCP_RESPONSE_FAILED", operation: pending.tool ?? pending.method, deliveryState: "unknown" })); });
     },
     exit(worker, error) {
       for (const [id, pending] of worker.clientPending) {
         requests.delete(idKey(pending.id));
-        output(errorMessage(pending.id, `${error.message}. The operation may already have been dispatched; it was not retried. Retain the original task and receipts.`));
+        output(errorMessage(pending.id, `${error.message}. The operation may already have been dispatched; it was not retried. Retain the original task and receipts.`, { code: "MCP_WORKER_EXITED", operation: pending.tool ?? pending.method, deliveryState: "unknown" }));
         worker.clientPending.delete(id);
       }
       for (const [id, pending] of reverse) if (pending.worker === worker) reverse.delete(id);
@@ -289,19 +295,23 @@ export async function runSupervisor(entry, options = {}) {
         }
         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");
+        if (!Array.isArray(catalog.tools) || !catalog.tools.length || catalog.nextCursor) throw new Error("The replacement tool catalog is incomplete");
+        const catalogChanged = JSON.stringify(catalog) !== JSON.stringify(initializeCatalog);
+        if (catalogChanged && (!ANTIGRAVITY_ENTRIES.has(entry) || initializeResult.capabilities?.tools?.listChanged !== true)) 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;
+        initializeCatalog = catalog;
         activeSince = Date.now();
         failure = null;
         reason = null;
         recoveries++;
-        log(`recovered native relay worker after exit; recovery ${recoveries}, no requests replayed`);
+        if (catalogChanged) output({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+        log(`recovered ${entry} worker after exit; recovery ${recoveries}, no requests replayed`);
         schedulePrune();
       } catch (error) {
-        failure = `Native relay recovery failed: ${error.message}; no requests were replayed`;
+        failure = `Bridge worker recovery failed: ${error.message}; no requests were replayed`;
         if (candidate) {
           try {
             await candidate.stop();
@@ -398,16 +408,16 @@ export async function runSupervisor(entry, options = {}) {
       }
       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 (failure) { if (hasId(message)) output(errorMessage(message.id, `${failure}${canRecover() && recoveryAttempts < recoveryLimit ? "; bridge worker recovery is pending, this request was not sent" : ""}`, { operation: message.params?.name ?? message.method, deliveryState: "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; }
+      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", { code: "MCP_QUEUE_FULL", operation: message.params?.name ?? message.method, deliveryState: "not_sent" })); return; }
       queue.push(message);
       return;
     }
     if (message.method === "initialize") initializeParams = message.params;
     if (hasId(message)) {
-      if (requests.has(idKey(message.id))) { output(errorMessage(message.id, "Duplicate active JSON-RPC request ID")); return; }
+      if (requests.has(idKey(message.id))) { output(errorMessage(message.id, "Duplicate active JSON-RPC request ID", { code: "MCP_DUPLICATE_REQUEST", operation: message.params?.name ?? message.method, deliveryState: "unknown" })); return; }
       const id = `client:${++sequence}`;
       active.clientPending.set(id, { id: message.id, method: message.method, tool: message.params?.name });
       requests.set(idKey(message.id), { worker: active, workerId: id });

package/src/native-relay-companion.mjs

@@ -43,7 +43,7 @@ import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } fro
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.25.2";
+const VERSION = "1.26.0";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {
@@ -345,6 +345,9 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
     if (payload.operation === "send_message_to_thread" && payload.arguments.threadId === executorThreadId) {
       return errorResponse("RELAY_BAD_REQUEST", "The relay executor cannot receive its own relayed message");
     }
+    if (payload.operation === "navigate_to_codex_page" && payload.arguments.threadId === executorThreadId) {
+      return errorResponse("RELAY_BAD_REQUEST", "The internal relay executor has no user conversation to open");
+    }
     // Reserve before dispatch. A disconnected caller must not discard a late
     // result, and even identical duplicate writes must not dispatch twice.
     const creation = payload.creationReceiptId ? creationReceipts.reserve(payload.creationReceiptId, payload.arguments, accountContext, executorThreadId) : null;

package/src/native-relay.mjs

@@ -254,6 +254,9 @@ export function validateDesktopOperation(operation, args) {
 
 export function nativeDesktopOperationParams({ executorThreadId, operation, arguments: args }) {
   validateDesktopOperation(operation, args);
+  if (operation === "navigate_to_codex_page" && args.threadId === executorThreadId) {
+    throw new NativeRelayError("The internal relay executor has no user conversation to open", "RELAY_BAD_REQUEST");
+  }
   return {
     arguments: args,
     callerSource: "codex",
@@ -774,7 +777,8 @@ export function nativeRelayStatus(env = process.env) {
       enabled: false,
       mode,
       socketPath,
-      reason: `no companion socket at ${socketPath}. Install the native relay if it is missing. 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.`,
+      code: "RELAY_UNREACHABLE",
+      reason: `The native relay endpoint is unavailable at ${socketPath}. Its Desktop-owned host may be unloaded or disconnected; socket absence alone cannot distinguish these causes. Silent worker recovery requires a running native supervisor. Do not open or create chats to load the relay; include the bridge diagnostic in a report.`,
     };
   }
   return { enabled: true, mode, socketPath, reason: null };

package/src/peer-protocol.mjs

@@ -235,7 +235,7 @@ export function findClaudeSession(target, { desktopOnly = false, expectedCwd } =
     if (matches.length !== 1) throw new Error(`Desktop-only mode requires an unambiguous sessionId or pid; "${needle}" matches multiple sessions. No message was sent.`);
     const session = matches[0];
     if (session.entrypoint !== "claude-desktop") {
-      throw new Error(`Desktop-only mode refuses Claude session ${session.sessionId ?? session.pid} with entrypoint ${session.entrypoint ?? "unknown"}. Open or reconnect an existing Code session in Claude Desktop for the intended project. Do not launch a replacement CLI session. No message was sent.`);
+      throw Object.assign(new Error(`Desktop-only mode refuses Claude session ${session.sessionId ?? session.pid} with entrypoint ${session.entrypoint ?? "unknown"}. Inspect native session discovery; do not open chats to load a relay or launch a replacement CLI session. No message was sent.`), { code: "CLAUDE_DESKTOP_TASK_UNVERIFIED", sent: false });
     }
     if (expectedCwd !== undefined) assertClaudeSessionCwd(session, expectedCwd);
     return session;
@@ -268,13 +268,13 @@ export function assertClaudeSessionCwd(session, expectedCwd) {
 }
 
 export function assertClaudeSessionProcess(session) {
-  const changed = "The live Claude process identity is missing or changed. No message was sent; reopen the existing Desktop task and inspect its session again.";
-  if (!session?.alive || typeof session.processStart !== "string" || !session.processStart) throw new Error(changed);
+  const changed = "The live Claude process identity is missing or changed. No message was sent; inspect list_claude_sessions without opening an app or chat.";
+  if (!session?.alive || typeof session.processStart !== "string" || !session.processStart) throw Object.assign(new Error(changed), { code: "CLAUDE_PROCESS_IDENTITY_CHANGED", sent: false });
   const current = readProcessStart(session.pid);
   if (current === null) {
-    throw new Error("The live Claude process identity could not be read, so this send was refused rather than sent unverified. That failure is not itself evidence the session changed; inspect the existing Desktop task before retrying.");
+    throw Object.assign(new Error("The live Claude process identity could not be read, so this send was refused rather than sent unverified. That failure is not itself evidence the session changed; inspect native session discovery before retrying."), { code: "CLAUDE_PROCESS_IDENTITY_UNAVAILABLE", sent: false });
   }
-  if (current !== session.processStart) throw new Error(changed);
+  if (current !== session.processStart) throw Object.assign(new Error(changed), { code: "CLAUDE_PROCESS_IDENTITY_CHANGED", sent: false });
 }
 
 /**
@@ -1050,6 +1050,7 @@ export class PeerEndpoint {
           + "Inspect read_claude_delivery and wait for Claude's outstanding replies. Changing waitSec or starting another bridge must not be used to bypass a pending message.",
         );
         error.code = "PEER_REPLY_PENDING";
+        error.sent = false;
         throw error;
       }
       const since = Date.now();
@@ -1076,8 +1077,9 @@ export class PeerEndpoint {
         }
       } catch (err) {
         const sent = this.sentMessages.get(msgId);
-        if (sent) sent.error = err.message;
+        if (sent) { sent.error = err.message; sent.errorCode = err.code ?? "CLAUDE_PEER_SEND_FAILED"; }
         if (!err.deliveryUncertain) {
+          err.sent = false;
           this.#removePendingReply(targetSocket, msgId);
           if (sent) sent.failed = true;
         }
@@ -1160,6 +1162,7 @@ export class PeerEndpoint {
       msgId,
       status: sent.reply ? "reply_received" : sent.failed ? "send_failed" : delivery?.status ?? "sent_unconfirmed",
       reason: delivery?.reason ?? sent.error ?? null,
+      ...(sent.errorCode || delivery?.reasonCode ? { reasonCode: sent.errorCode ?? delivery.reasonCode } : {}),
       sentAt: sent.sentAt,
       sessionId: session?.sessionId ?? null,
       cwd: session?.cwd ?? null,

package/src/recipient-preflight.mjs

@@ -1,5 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const diagnosticCode = (value) => typeof value === "string" && /^[A-Z][A-Z0-9_]{0,79}$/.test(value) ? value : null;
+const diagnosticId = (value) => typeof value === "string" && /^(?:[a-f0-9]{64}|(?:local_)?[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})$/i.test(value) ? value : null;
+
+export function diagnosticText(value) {
+  return String(value ?? "Unknown bridge failure")
+    .replace(/\{[\s\S]*\}|\[\s*(?:\{|"|true|false|null|\d)[\s\S]*\]/g, "[structured details omitted]")
+    .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[credential]")
+    .replace(/((?:access[_-]?token|refresh[_-]?token|api[_-]?key|token|secret|password|authorization)\s*["']?\s*[:=]\s*)["']?[^\s,"';}]+["']?/gi, "$1[redacted]")
+    .replace(/https?:\/\/[^\s<>"']+/gi, "[url]")
+    .replace(/(?:[a-z]:[\\/]|\\\\)[^\r\n"'<>|,;]*/gi, "[path]")
+    .replace(/(^|[\s"'(])\/(?:Users|home|tmp|var|private|Volumes|mnt)\/[^\r\n"'<>|,;]*/g, "$1[path]")
+    .replace(/[\w.+-]+@[\w.-]+\.[a-z]{2,}/gi, "[email]")
+    .replace(/\b(?:sk-[a-z0-9_-]+|gh[pousr]_[a-z0-9_]+)\b/gi, "[credential]")
+    .replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, 1400);
+}
+
+export function bridgeDiagnostic(error, options = {}) {
+  const previous = error?.diagnostic?.schemaVersion === 1 ? error.diagnostic : null;
+  const chain = [];
+  const seen = new Set();
+  for (let cause = error; cause && !seen.has(cause) && chain.length < 8; cause = cause.cause) {
+    seen.add(cause);
+    chain.push(cause);
+  }
+  const codes = [...new Set(chain.flatMap((cause) => [cause?.preflight?.code, cause?.code, cause?.reasonCode, cause?.diagnostic?.code]).map(diagnosticCode).filter(Boolean))];
+  const code = diagnosticCode(previous?.code) ?? diagnosticCode(options.code) ?? codes[0] ?? "BRIDGE_OPERATION_FAILED";
+  const state = options.deliveryState ?? previous?.deliveryState ?? error?.deliveryState;
+  const deliveryState = state === "not_applicable" || options.readOnly && !previous ? "not_applicable"
+    : ["not_sent", "not-sent"].includes(state) ? "not_sent"
+    : state === "sent" ? "sent"
+    : state === "unknown" || error?.deliveryUncertain ? "unknown"
+    : chain.some((cause) => cause?.sent === false || cause?.preflight?.sent === false) ? "not_sent" : "unknown";
+  const name = (value, fallback) => typeof value === "string" && /^[a-zA-Z][a-zA-Z0-9_./-]{0,99}$/.test(value) ? value : fallback;
+  const ids = {};
+  for (const key of ["requestId", "msgId", "deliveryId", "threadId", "taskId", "conversationId"]) {
+    const id = diagnosticId(previous?.ids?.[key] ?? options[key] ?? error?.[key]);
+    if (id) ids[key] = id;
+  }
+  const timestamp = previous?.timestamp;
+  return {
+    schemaVersion: 1,
+    reportId: diagnosticId(previous?.reportId) ?? randomUUID(),
+    timestamp: typeof timestamp === "string" && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/.test(timestamp) ? timestamp : new Date().toISOString(),
+    component: name(previous?.component ?? options.component, "bridge"),
+    operation: name(previous?.operation === "unknown" ? options.operation : previous?.operation ?? options.operation, "unknown"),
+    version: typeof previous?.version === "string" && /^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i.test(previous.version) ? previous.version : version,
+    platform: process.platform,
+    nodeVersion: process.versions.node,
+    code,
+    causeCodes: [...new Set([...(Array.isArray(previous?.causeCodes) ? previous.causeCodes : []).map(diagnosticCode).filter(Boolean), ...codes])].filter((value) => value !== code).slice(0, 8),
+    phase: name(previous?.phase ?? options.phase ?? error?.phase ?? error?.diagnostic?.stage, deliveryState === "not_sent" ? "preflight" : options.readOnly ? "inspection" : "delivery"),
+    deliveryState,
+    sent: deliveryState === "not_sent" ? false : deliveryState === "sent" ? true : null,
+    retrySafe: deliveryState === "not_sent",
+    nextAction: deliveryState === "not_sent" ? "Inspect the reported cause and bridge status before retrying. Do not open or create chats to load a relay."
+      : deliveryState === "not_applicable" ? "Inspect bridge status and include this diagnostic in the report."
+      : "Inspect the original delivery receipt. Do not resend automatically or create a replacement chat.",
+    reason: diagnosticText(previous?.reason ?? error?.preflight?.reason ?? error?.message ?? error),
+    ids,
+  };
+}
+
+export function withBridgeDiagnostic(result, error, options = {}) {
+  const diagnostic = bridgeDiagnostic({ ...error, cause: error?.cause, message: error?.message ?? String(error ?? "Bridge operation failed"), diagnostic: result?.structuredContent?.diagnostic ?? result?.diagnostic ?? error?.diagnostic }, options);
+  const report = ["Bridge diagnostic (include this block in a bug report)", `${diagnostic.code} | ${diagnostic.component} / ${diagnostic.operation}`,
+    `Bridge ${diagnostic.version} | ${diagnostic.platform} | Node ${diagnostic.nodeVersion}`,
+    `Phase: ${diagnostic.phase} | Delivery: ${diagnostic.deliveryState} | Sent: ${diagnostic.sent ?? "unconfirmed"}`,
+    `Reason: ${diagnostic.reason}`, ...(diagnostic.causeCodes.length ? [`Cause codes: ${diagnostic.causeCodes.join(", ")}`] : []),
+    ...Object.entries(diagnostic.ids).map(([key, value]) => `${key}: ${value}`),
+    `Report: ${diagnostic.reportId} | ${diagnostic.timestamp}`, diagnostic.nextAction].join("\n");
+  return { ...result, content: [...(result?.content ?? []).filter((item) => item.type !== "text" || !item.text.startsWith("Bridge diagnostic (")), { type: "text", text: report }],
+    structuredContent: { ...result?.structuredContent, diagnostic } };
+}
+
 export function preflightFailure(code, reason) {
   const error = new Error(`${reason} No message was sent.`);
+  error.code = code;
+  error.deliveryState = "not_sent";
+  error.sent = false;
   error.preflight = { status: "blocked", code, reason, sent: false };
   return error;
 }

package/src/reload-control.mjs

@@ -26,7 +26,7 @@ export async function drainPendingAccepts(turns = 3) {
 }
 
 export function createReloadControl({ entry, inspect = () => null, quiesce = () => {}, exportState = () => ({}), restore = () => {}, activate = () => {}, resume = activate, env = process.env, channel = process } = {}) {
-  if (!["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"].includes(entry)) throw new Error("Invalid reload entry point");
+  if (!["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs", "antigravity-bridge.mjs", "antigravity-outbound-bridge.mjs"].includes(entry)) throw new Error("Invalid reload entry point");
   const enabled = env.CODEX_BRIDGE_WORKER === "1" && typeof channel.send === "function";
   let phase = enabled && env.CODEX_BRIDGE_STAGED === "1" ? "staged" : "active";
   let active = 0;
@@ -83,7 +83,7 @@ export function createReloadControl({ entry, inspect = () => null, quiesce = ()
     inspect: status,
     defer(reason) { deferred ??= String(reason); },
     async run(handler) {
-      if (phase !== "active") throw new Error(`Bridge worker is ${phase}; no tool operation was started`);
+      if (phase !== "active") throw Object.assign(new Error(`Bridge worker is ${phase}; no tool operation was started`), { code: "MCP_WORKER_QUIESCED", phase: "lifecycle", deliveryState: "not_sent", sent: false });
       active += 1;
       try { return await handler(); }
       finally { active -= 1; }