@minhspark/codex-mcp-bridge 1.25.1 → 1.25.3

package/src/mcp-supervisor.mjs

@@ -7,6 +7,7 @@ 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"]);
@@ -16,7 +17,10 @@ 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);
@@ -170,6 +174,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 +186,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 +205,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,25 +226,37 @@ 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 });
       };
-      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);
-      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 +273,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 +356,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,16 +402,16 @@ 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" : ""}`, { 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

@@ -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.3";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {
@@ -344,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;
@@ -865,6 +869,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 +956,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 +972,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

@@ -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",
@@ -560,9 +563,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 +584,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");
       }
@@ -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/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/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;
 }