@minhspark/codex-mcp-bridge 1.26.8 → 1.26.10

package/src/peer-protocol.mjs

@@ -284,6 +284,7 @@ export function assertClaudeSessionProcess(session) {
  * rather than by reconstructing the slug.
  */
 function findTranscriptFile(sessionId, cwd) {
+  if (typeof sessionId !== "string" || !sessionId || sessionId.length > 128 || /[^a-zA-Z0-9_-]/.test(sessionId)) return null;
   const dir = projectsDir();
   const guess = path.join(dir, String(cwd ?? "").replace(/[^a-zA-Z0-9]/g, "-"), `${sessionId}.jsonl`);
   if (fs.existsSync(guess)) return guess;
@@ -297,7 +298,7 @@ function findTranscriptFile(sessionId, cwd) {
 
 export function readTranscript(sessionId, cwd, limit = 10) {
   const file = findTranscriptFile(sessionId, cwd);
-  if (!fs.existsSync(file)) return { file, messages: [] };
+  if (!file || !fs.existsSync(file)) return { file, messages: [] };
   const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
   const messages = [];
   for (const line of lines) {
@@ -325,7 +326,7 @@ export function readTranscript(sessionId, cwd, limit = 10) {
 
 export function readInitialTranscriptMessage(sessionId, cwd) {
   const file = findTranscriptFile(sessionId, cwd);
-  if (!fs.existsSync(file)) return { file, messages: [] };
+  if (!file || !fs.existsSync(file)) return { file, messages: [] };
   const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   try {
     const stat = fs.fstatSync(descriptor);
@@ -388,6 +389,46 @@ function isTerminalDelivery(receipt) {
   return ["refused", "denied", "expired", "dropped"].includes(receipt?.status) || isInterruptedDelivery(receipt);
 }
 
+function resumableTranscriptDelivery(id, sent, receipt) {
+  const uuid = value => typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+  const session = sent?.transcriptSession;
+  return Boolean(sent) && uuid(id) && !sent.reply && !sent.failed && !isTerminalDelivery(receipt)
+    && Number.isFinite(sent.sentAt) && (!receipt || receipt.status === "delivered" && receipt.fromSocket === sent.targetSocket)
+    && session?.entrypoint === "claude-desktop" && uuid(session.sessionId)
+    && typeof session.cwd === "string" && path.isAbsolute(session.cwd)
+    && typeof sent.targetSocket === "string" && sent.targetSocket && session.socket === sent.targetSocket
+    && session.desktop?.status === "matched" && typeof session.desktop.taskId === "string"
+    && session.desktop.taskId.startsWith("local_") && uuid(session.desktop.taskId.slice(6))
+    && session.desktop.cwd === session.cwd
+    && /^[a-f0-9]{64}$/i.test(sent.accountContext?.claude ?? "") && /^[a-f0-9]{64}$/i.test(sent.accountContext?.codex ?? "")
+    && session.desktop.accountFingerprint === sent.accountContext.claude
+    && hasTranscriptDeliveryRoot(session.sessionId, session.cwd, id);
+}
+
+function hasTranscriptDeliveryRoot(sessionId, cwd, msgId) {
+  const file = findTranscriptFile(sessionId, cwd);
+  if (!file) return false;
+  let lines;
+  try { lines = fs.readFileSync(file, "utf8").split("\n"); }
+  catch { return false; }
+  let roots = 0;
+  const ids = new Set();
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { return false; }
+    if (!entry || typeof entry !== "object" || entry.isSidechain) continue;
+    if (typeof entry.uuid === "string") {
+      if (ids.has(entry.uuid)) return false;
+      ids.add(entry.uuid);
+    }
+    if (!injectedMessageRoot(entry, msgId)) continue;
+    if (entry.entrypoint !== "claude-desktop" || entry.sessionId !== sessionId || entry.cwd !== cwd) return false;
+    roots++;
+  }
+  return roots === 1;
+}
+
 export function readTranscriptReply(sessionId, cwd, msgId) {
   return readTranscriptOutcome(sessionId, cwd, msgId)?.reply ?? null;
 }
@@ -460,6 +501,7 @@ function compactContinuation(entry, root, entriesById, transcriptIds, sessionId,
 // user turn's answer to the original request or claim its side effects stopped.
 export function readTranscriptOutcome(sessionId, cwd, msgId) {
   const file = findTranscriptFile(sessionId, cwd);
+  if (!file) return null;
   let lines;
   try { lines = fs.readFileSync(file, "utf8").split("\n"); }
   catch { return null; }
@@ -509,6 +551,7 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
     }
   }
   const descendants = new Map();
+  const monitorTasksByEntry = new Map();
   const backgroundCalls = new Map();
   const openLeaves = new Set();
   const passiveLeaves = new Set();
@@ -520,7 +563,7 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
     interruptions.push({ entryId: entry.uuid, backgroundTaskIds: [...outstanding.keys()] });
   };
   for (const entry of orderedEntries) {
-    if (entry === root) { descendants.set(entry.uuid, new Map()); openLeaves.add(entry.uuid); continue; }
+    if (entry === root) { descendants.set(entry.uuid, new Map()); monitorTasksByEntry.set(entry.uuid, new Set()); openLeaves.add(entry.uuid); continue; }
     let parentUuid = entry.parentUuid;
     if (!ambiguous && !interruptions.length && descendants.has(entry.logicalParentUuid)
         && openLeaves.has(entry.logicalParentUuid)) {
@@ -549,6 +592,7 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
     const role = entry.message?.role;
     const content = entry.message?.content;
     const outstanding = new Map(descendants.get(parentUuid));
+    const monitorTasks = new Set(monitorTasksByEntry.get(parentUuid));
     const toolResults = Array.isArray(content) && content.length > 0 && content.every((part) => part?.type === "tool_result");
     const imageCompanion = isImageToolCompanion(entry, entriesById);
     if (role === "user" && !toolResults && !imageCompanion && !compactSummaries.has(entry.uuid)) {
@@ -575,13 +619,20 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
     }
     if (typeof taskNotification === "string" && /^<task-notification>\s[\s\S]*<\/task-notification>$/.test(taskNotification.trim())) {
       const field = (name) => {
+        if (taskNotification.split(`<${name}>`).length !== 2 || taskNotification.split(`</${name}>`).length !== 2) return null;
         const matches = [...taskNotification.matchAll(new RegExp(`<${name}>([^<>]+)</${name}>`, "g"))];
         return matches.length === 1 ? matches[0][1] : null;
       };
       const taskId = field("task-id");
+      const hasField = name => taskNotification.split(`<${name}>`).length === 2
+        && taskNotification.split(`</${name}>`).length === 2
+        && new RegExp(`<${name}>[\\s\\S]+?</${name}>`).test(taskNotification);
+      const monitorProgress = monitorTasks.has(taskId) && !outstanding.has(taskId)
+        && hasField("summary") && hasField("event")
+        && !/<\/?(?:status|tool-use-id)(?:\s|>)/.test(taskNotification);
       if (!outstanding.has(taskId) || outstanding.get(taskId) !== field("tool-use-id")
         || !["completed", "failed", "killed"].includes(field("status"))) {
-        if (role === "user") continue;
+        if (role === "user" && !monitorProgress) continue;
       } else outstanding.delete(taskId);
     }
     if (typeof entry.uuid !== "string" || !entry.uuid.trim()) continue;
@@ -600,6 +651,18 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
     // Parallel tool results and hook records can be leaf siblings of the real
     // continuation. They are completed observations, not separate reply turns.
     const parentEntry = entriesById.get(entry.parentUuid);
+    const monitorTaskId = entry.toolUseResult?.taskId;
+    if (role === "user" && toolResults && content.length === 1 && typeof monitorTaskId === "string" && /^[\w-]{1,128}$/.test(monitorTaskId)
+      && entry.sourceToolAssistantUUID === parentEntry?.uuid
+      && parentEntry?.message?.role === "assistant"
+      && Number.isSafeInteger(entry.toolUseResult.timeoutMs) && entry.toolUseResult.timeoutMs > 0
+      && typeof entry.toolUseResult.persistent === "boolean") {
+      const matches = content.filter(part => !part.is_error && typeof part.tool_use_id === "string" && part.tool_use_id
+        && Array.isArray(parentEntry.message.content)
+        && parentEntry.message.content.filter(call => call.type === "tool_use" && call.name === "Monitor" && call.id === part.tool_use_id).length === 1);
+      if (matches.length === 1) monitorTasks.add(monitorTaskId);
+    }
+    monitorTasksByEntry.set(entry.uuid, monitorTasks);
     const matchedResults = toolResults && !entry.toolUseResult?.backgroundTaskId
       && content.every((part) => Array.isArray(parentEntry?.message?.content)
         && parentEntry.message.content.some((call) => call.type === "tool_use" && call.id === part.tool_use_id));
@@ -654,6 +717,7 @@ export class PeerEndpoint {
     this.sentMessages = new Map();
     this.pendingMessages = new Map();
     this.responsePoll = null;
+    this.transcriptPollingPaused = false;
     this.connections = new Set();
     this.activityRevision = 0;
     this.reloadPaused = false;
@@ -779,6 +843,8 @@ export class PeerEndpoint {
     }
 
     this.started = true;
+    this.transcriptPollingPaused = false;
+    this.#startTranscriptPolling();
     this.log(`peer "${this.name}" listening on ${this.socketPath}`);
   }
 
@@ -903,11 +969,20 @@ export class PeerEndpoint {
     }
   }
 
+  #startTranscriptPolling() {
+    if (this.reloadPaused || this.transcriptPollingPaused || this.responsePoll
+      || ![...this.pendingMessages.values()].some(entry => entry.transcriptSession)) return;
+    this.responsePoll = globalThis.setInterval(() => this.#refreshTranscriptReplies(), 250);
+    this.responsePoll.unref();
+  }
+
   #refreshTranscriptReplies() {
+    if (this.reloadPaused || this.transcriptPollingPaused) return;
     for (const [msgId, pending] of this.pendingMessages) {
       if (!pending.transcriptSession) continue;
       const { sessionId, cwd } = pending.transcriptSession;
       const file = findTranscriptFile(sessionId, cwd);
+      if (!file) continue;
       let stamp;
       try { const stat = fs.statSync(file, { bigint: true }); stamp = `${stat.dev}:${stat.ino}:${stat.mtimeNs}:${stat.ctimeNs}:${stat.size}`; }
       catch { continue; }
@@ -1051,6 +1126,7 @@ export class PeerEndpoint {
         );
         error.code = "PEER_REPLY_PENDING";
         error.sent = false;
+        error.msgId = [...this.pendingMessages].find(([, entry]) => entry.targetSocket === targetSocket)?.[0];
         throw error;
       }
       const since = Date.now();
@@ -1059,10 +1135,7 @@ export class PeerEndpoint {
       let msgId = crypto.randomUUID();
       this.pendingMessages.set(msgId, { targetSocket, transcriptSession });
       this.sentMessages.set(msgId, { targetSocket, transcriptSession, sentAt: since, replyThreadId, permissionMode, senderApprovalPolicy, ...(senderReview ? { senderReview: { ...senderReview } } : {}), ...(recipient ? { recipient: { ...recipient } } : {}), ...(accountContext ? { accountContext: Object.freeze({ ...accountContext }) } : {}), ...(scopeBindings ? { scopeBindings: Object.freeze(structuredClone(scopeBindings)) } : {}) });
-      if (transcriptSession && !this.responsePoll) {
-        this.responsePoll = globalThis.setInterval(() => this.#refreshTranscriptReplies(), 250);
-        this.responsePoll.unref();
-      }
+      this.#startTranscriptPolling();
       try {
         const sentId = await this.send(targetSocket, text, { priority, msgId, permissionMode, beforeSend });
         if (sentId !== msgId) {
@@ -1191,9 +1264,21 @@ export class PeerEndpoint {
   reloadReason() {
     this.#refreshTranscriptReplies();
     if (this.connections.size) return "Peer socket connections are still open";
-    if (this.requestQueues.size || this.pendingMessages.size || this.unconfirmedReplies.size) return "Claude messages still have pending or unconfirmed delivery";
+    if (this.requestQueues.size) return "Claude messages are still being sent";
+    const counts = new Map();
+    for (const [id, pending] of this.pendingMessages) {
+      const sent = this.sentMessages.get(id);
+      if (!resumableTranscriptDelivery(id, sent, this.deliveryReceipts.get(id))
+        || pending.targetSocket !== sent.targetSocket || JSON.stringify(pending.transcriptSession) !== JSON.stringify(sent.transcriptSession)) {
+        return "Claude messages still have pending or unconfirmed delivery";
+      }
+      counts.set(sent.targetSocket, (counts.get(sent.targetSocket) ?? 0) + 1);
+    }
+    if (counts.size !== this.unconfirmedReplies.size || [...counts].some(([socket, count]) => this.unconfirmedReplies.get(socket) !== count)) {
+      return "Claude messages still have pending or unconfirmed delivery";
+    }
     for (const [id, sent] of this.sentMessages) {
-      if (!sent.reply && !sent.failed && !isTerminalDelivery(this.deliveryReceipts.get(id))) {
+      if (!sent.reply && !sent.failed && !isTerminalDelivery(this.deliveryReceipts.get(id)) && !this.pendingMessages.has(id)) {
         return "A Claude delivery outcome remains unconfirmed";
       }
     }
@@ -1243,14 +1328,17 @@ export class PeerEndpoint {
     const reason = this.reloadReason();
     if (reason || this.started && !this.reloadPaused) throw new Error(reason ?? "Quiesce the peer endpoint before exporting state");
     return cloneReloadState({ name: this.name, messageSequence: this.messageSequence, inbox: this.inbox,
-      sentMessages: [...this.sentMessages], deliveryReceipts: [...this.deliveryReceipts] });
+      sentMessages: [...this.sentMessages], deliveryReceipts: [...this.deliveryReceipts],
+      pendingMessages: [...this.pendingMessages].map(([id, pending]) => [id, { targetSocket: pending.targetSocket, transcriptSession: pending.transcriptSession }]) });
   }
 
   restoreReloadState(input) {
-    if (this.started || this.connections.size || this.sentMessages.size || this.inbox.length) throw new Error("Peer reload state requires an empty dormant endpoint");
+    if (this.started || this.connections.size || this.sentMessages.size || this.inbox.length || this.pendingMessages.size
+      || this.unconfirmedReplies.size || this.requestQueues.size || this.responsePoll) throw new Error("Peer reload state requires an empty dormant endpoint");
     const state = cloneReloadState(input);
     if (!state || typeof state.name !== "string" || !state.name || !Number.isSafeInteger(state.messageSequence) || state.messageSequence < 0
-      || !Array.isArray(state.inbox) || !Array.isArray(state.sentMessages) || !Array.isArray(state.deliveryReceipts)) throw new Error("Invalid peer reload state");
+      || !Array.isArray(state.inbox) || !Array.isArray(state.sentMessages) || !Array.isArray(state.deliveryReceipts)
+      || state.pendingMessages !== undefined && !Array.isArray(state.pendingMessages)) throw new Error("Invalid peer reload state");
     const restoreMap = (entries) => {
       const restored = new Map();
       for (const pair of entries) {
@@ -1262,6 +1350,17 @@ export class PeerEndpoint {
     };
     const sentMessages = restoreMap(state.sentMessages);
     const deliveryReceipts = restoreMap(state.deliveryReceipts);
+    const pendingMessages = restoreMap(state.pendingMessages ?? []);
+    const unconfirmedReplies = new Map();
+    for (const [id, pending] of pendingMessages) {
+      const sent = sentMessages.get(id);
+      if (!resumableTranscriptDelivery(id, sent, deliveryReceipts.get(id))
+        || pending.targetSocket !== sent.targetSocket || JSON.stringify(pending.transcriptSession) !== JSON.stringify(sent.transcriptSession)) {
+        throw new Error("Invalid pending Claude transcript reload record");
+      }
+      delete pending.transcriptStamp;
+      unconfirmedReplies.set(sent.targetSocket, (unconfirmedReplies.get(sent.targetSocket) ?? 0) + 1);
+    }
     for (const record of state.inbox) {
       if (!record || typeof record.text !== "string" || !Number.isSafeInteger(record.sequence) || record.sequence < 1
         || record.sequence > state.messageSequence || !Number.isFinite(record.receivedAt)) throw new Error("Invalid inbox reload record");
@@ -1269,7 +1368,7 @@ export class PeerEndpoint {
     for (const [id, sent] of sentMessages) {
       if (typeof sent.targetSocket !== "string" || !sent.targetSocket || !Number.isFinite(sent.sentAt)
         || sent.reply && (typeof sent.reply.text !== "string" || sent.reply.inReplyTo !== id)
-        || !sent.reply && !sent.failed && !isTerminalDelivery(deliveryReceipts.get(id))
+        || !sent.reply && !sent.failed && !isTerminalDelivery(deliveryReceipts.get(id)) && !pendingMessages.has(id)
         || isInterruptedDelivery(deliveryReceipts.get(id)) && deliveryReceipts.get(id).inReplyTo !== id) {
         throw new Error("Invalid or unconfirmed Claude delivery reload record");
       }
@@ -1279,6 +1378,9 @@ export class PeerEndpoint {
     this.inbox = state.inbox;
     this.sentMessages = sentMessages;
     this.deliveryReceipts = deliveryReceipts;
+    this.pendingMessages = pendingMessages;
+    this.unconfirmedReplies = unconfirmedReplies;
+    this.transcriptPollingPaused = true;
   }
 
   #removeRegistration() {

package/src/platform.mjs

@@ -88,9 +88,10 @@ function workspaceRoots() {
 }
 
 function isRunnable(candidate) {
-  if (!candidate || !existsSync(candidate)) return false;
-  if (IS_WINDOWS) return true;
+  if (typeof candidate !== "string" || !candidate || candidate.includes("\0")) return false;
   try {
+    if (!existsSync(candidate) || !statSync(candidate).isFile()) return false;
+    if (IS_WINDOWS) return true;
     accessSync(candidate, constants.X_OK);
     return true;
   } catch {
@@ -98,9 +99,9 @@ function isRunnable(candidate) {
   }
 }
 
-function windowsCodexCandidates() {
-  const roaming = process.env.APPDATA;
-  const local = process.env.LOCALAPPDATA;
+function windowsCodexCandidates(env, runnable) {
+  const roaming = env.APPDATA;
+  const local = env.LOCALAPPDATA;
   const versionedRoot = local && path.join(local, "OpenAI", "Codex", "bin");
   let versioned = [];
   if (versionedRoot) {
@@ -108,7 +109,7 @@ function windowsCodexCandidates() {
       versioned = readdirSync(versionedRoot, { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
         .map((entry) => path.join(versionedRoot, entry.name, "codex.exe"))
-        .filter((candidate) => isRunnable(candidate))
+        .filter((candidate) => runnable(candidate))
         .sort((left, right) => {
           try {
             return statSync(path.dirname(right)).mtimeMs - statSync(path.dirname(left)).mtimeMs;
@@ -119,16 +120,16 @@ function windowsCodexCandidates() {
     } catch {}
   }
   return [
-    process.env.CODEX_CLI_PATH,
+    env.CODEX_CLI_PATH,
     ...versioned,
     local && path.join(local, "Programs", "OpenAI", "Codex", "bin", "codex.exe"),
     roaming && path.join(roaming, "npm", "codex.cmd"),
-    process.env.ProgramFiles && path.join(process.env.ProgramFiles, "nodejs", "codex.cmd"),
+    env.ProgramFiles && path.join(env.ProgramFiles, "nodejs", "codex.cmd"),
   ];
 }
 
-function unixCodexCandidates() {
-  const home = homeDir();
+function unixCodexCandidates(env) {
+  const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
   return [
     path.join(home, ".local", "bin", "codex"),
     path.join(home, ".npm-global", "bin", "codex"),
@@ -147,17 +148,17 @@ function unixCodexCandidates() {
  * two versions write that same state, so prefer the app's binary whenever the
  * app is installed and fall back to the standalone CLI installs otherwise.
  */
-function macosCodexCandidates() {
+function macosCodexCandidates(env) {
   return [
     hasCodexDesktopApp() ? CODEX_DESKTOP_BIN_MACOS : null,
-    ...unixCodexCandidates(),
+    ...unixCodexCandidates(env),
   ];
 }
 
-function pathCandidates() {
-  const separator = IS_WINDOWS ? ";" : ":";
-  const names = IS_WINDOWS ? ["codex.exe", "codex.cmd"] : ["codex"];
-  return (process.env.PATH ?? "")
+function pathCandidates(env, platform) {
+  const separator = platform === "win32" ? ";" : ":";
+  const names = platform === "win32" ? ["codex.exe", "codex.cmd"] : ["codex"];
+  return (env.PATH ?? "")
     .split(separator)
     .filter(Boolean)
     .flatMap((dir) => names.map((name) => path.join(dir, name)));
@@ -217,8 +218,8 @@ export function resolveCodexBin(explicit, {
     explicit,
     env.CODEX_BIN,
     ...(discovered ?? [
-      ...(IS_WINDOWS ? windowsCodexCandidates() : IS_MACOS ? macosCodexCandidates() : unixCodexCandidates()),
-      ...pathCandidates(),
+      ...(platform === "win32" ? windowsCodexCandidates(env, runnable) : platform === "darwin" ? macosCodexCandidates(env) : unixCodexCandidates(env)),
+      ...pathCandidates(env, platform),
     ]),
   ].filter(Boolean);
 

package/src/recipient-preflight.mjs

@@ -55,8 +55,9 @@ export function bridgeDiagnostic(error, options = {}) {
     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."
+    retrySafe: deliveryState === "not_sent" && code !== "PEER_REPLY_PENDING",
+    nextAction: code === "PEER_REPLY_PENDING" ? "Read read_claude_delivery with the original msgId. Wait for its correlated outcome; do not resend or start another bridge to bypass pending work."
+      : 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),

package/src/setup.mjs

@@ -8,6 +8,7 @@ import { resolveCodexBin, resolvePackagedCodexBin } from "./platform.mjs";
 import { readRegularConfigFile } from "./project-policy.mjs";
 import { stableInstallPath } from "./install-paths.mjs";
 import { resolveClaudeDesktopConfigRoot } from "./desktop-account-context.mjs";
+import { CODEX_MCP_TIMEOUT_MS } from "./codex-mcp-registration.mjs";
 
 const ROOT = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const CODEX_PACKAGE = "@openai/codex@0.166.0";
@@ -64,7 +65,7 @@ export function setupFailureSummary(value) {
 }
 
 export function setupArguments(args) {
-  const allowed = new Set(["--postinstall", "--check", "--dry-run", "--json", "--no-download", "--help"]);
+  const allowed = new Set(["--postinstall", "--check", "--dry-run", "--json", "--no-download", "--progress", "--help"]);
   if (args.some((arg) => !allowed.has(arg))) throw new Error("Unknown setup option; use codex-bridge-setup --help");
   if (args.includes("--check") && args.includes("--dry-run")) throw new Error("Use --check or --dry-run, not both");
   return Object.fromEntries([...allowed].map((arg) => [arg.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()), args.includes(arg)]));
@@ -148,6 +149,13 @@ export function setupEnvironment(env, paths, codex) {
     CLAUDE_DESKTOP_CONFIG: paths.desktop, CODEX_EXE: codex, CODEX_BIN: codex };
 }
 
+function codexInventoryFailure(error) {
+  const detail = error?.message?.includes("ETIMEDOUT") || error?.code === "ETIMEDOUT"
+    ? `Codex CLI did not list its MCP servers within ${CODEX_MCP_TIMEOUT_MS / 1000} seconds; the computer may be busy. Rerun the check when it is idle`
+    : error?.message ?? String(error);
+  return Object.assign(new Error(detail), error?.code ? { code: error.code } : {});
+}
+
 function configurationCheck(label, check, components) {
   try { const details = check(); components.push({ name: label, status: "configured", ...details }); }
   catch (error) { components.push(failedComponent(label, error)); }
@@ -171,15 +179,16 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
   let inventory;
   configurationCheck("Codex CLI", () => {
     codex = ensureSetupCodex({ env, paths, platform, download: false, run, resolve }).binary;
-    inventory = JSON.parse(run(codex, ["mcp", "list", "--json"], setupEnvironment(env, paths, codex), 30000));
-    if (!Array.isArray(inventory)) throw new Error("Codex returned an invalid MCP inventory");
+    try { inventory = JSON.parse(run(codex, ["mcp", "list", "--json"], setupEnvironment(env, paths, codex), CODEX_MCP_TIMEOUT_MS)); }
+    catch (error) { throw codexInventoryFailure(error); }
+    if (!Array.isArray(inventory)) { inventory = undefined; throw new Error("Codex returned an invalid MCP inventory"); }
   }, components);
   const native = platform === "win32" || platform === "darwin";
   for (const [name, worker] of [["claude-bridge", "claude-bridge.mjs"], ...(native ? [["codex-native-relay", "native-relay-companion.mjs"]] : []), ["antigravity-bridge", "antigravity-bridge.mjs"]]) {
     configurationCheck(`Codex / ${name}`, () => {
-      const item = inventory?.find((server) => server.name === name);
-      if (!item) throw new Error("MCP registration is missing");
-      const entry = JSON.parse(run(codex, ["mcp", "get", name, "--json"], setupEnvironment(env, paths, codex), 30000));
+      if (!inventory) throw new Error("Not checked because Codex CLI did not report its MCP servers; the registration may still be present");
+      const entry = inventory.find((server) => server?.name === name);
+      if (!entry) throw new Error("MCP registration is missing");
       const details = assertEntry({ ...entry.transport, enabled: entry.enabled }, worker, root, name === "antigravity-bridge" ? { caller: "codex" } : {});
       if (name === "codex-native-relay" && !entry.transport.env_vars?.includes("CODEX_APP_TOOLS_PIPE_PATH")) throw new Error("Native pipe forwarding is missing");
       return details;
@@ -228,7 +237,7 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
   return { configured: components.every((item) => item.status === "configured"), liveVerified: false, components };
 }
 
-export function runSetup({ args = [], env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin } = {}) {
+export function runSetup({ args = [], env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin, onProgress = () => {} } = {}) {
   const options = setupArguments(args);
   if (options.help) return { help: `Usage: codex-bridge-setup [--check|--dry-run] [--json] [--no-download]\nUpdate the package and apply managed settings in an interactive terminal with: ${platform === "win32" ? "npx.cmd" : "npx"} -y @minhspark/codex-mcp-bridge@latest\nThe updater installs the package with lifecycle scripts disabled, then directly configures Claude Desktop, Claude Code, Codex, Antigravity and the independent worker relay. CODEX_BRIDGE_SKIP_SETUP=1 opts out. Saved configuration, background relay health and loaded native app connections are verified separately.` };
   if (options.postinstall && !automaticSetupEnabled(env)) return { skipped: true, reason: "Automatic configuration runs only for a global npm install; use codex-bridge-setup for manual setup." };
@@ -243,6 +252,7 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
   const base = setupEnvironment(env, paths, runtime.binary);
   const components = [];
   const install = (name, script, arguments_, environment = base) => {
+    onProgress(name);
     try {
       const output = run(process.execPath, [path.join(root, "scripts", script), ...arguments_], environment, 180000);
       let details = {};
@@ -265,6 +275,7 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
   install("Codex / claude-bridge", "install-codex-mcp.mjs", ["--setup"]);
   if (code) install("Antigravity / all components", "install-antigravity-bridge.mjs", ["--all", "--setup"]);
   install("Independent background relay", "setup-background-relay.mjs", ["--json"]);
+  onProgress("Verifying saved settings");
   const inspection = checkSetup({ env: base, platform, root, run, resolve: () => runtime.binary });
   return { configured: components.every((item) => item.status === "configured") && inspection.configured, liveVerified: false,
     cliInstalled: runtime.installed, components, verification: inspection.components,