@minhspark/codex-mcp-bridge 1.23.0 → 1.24.1

package/src/antigravity-sender-context.mjs

@@ -0,0 +1,162 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readProcessAncestry, runProcessInspector } from "./claude-sender-context.mjs";
+import { antigravityBridgeDirectory, callAntigravityDesktop } from "./antigravity-ipc.mjs";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PREFIX = "antigravity.google/";
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+class ContextError extends Error {}
+const fail = (reason) => { throw new ContextError(reason); };
+const hash = (value) => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+export async function readAntigravityConfigurationJson(file, { filesystem = fs } = {}) {
+  const valid = (stat) => stat.isFile() && stat.nlink === 1n && stat.size >= 0n && stat.size <= 1048576n;
+  const same = (left, right) => ["dev", "ino", "size", "mtimeNs", "ctimeNs", "nlink"].every((key) => left[key] === right[key]);
+  const handle = await filesystem.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  try {
+    const opened = await handle.stat({ bigint: true });
+    const linked = await filesystem.lstat(file, { bigint: true });
+    if (!valid(opened) || !valid(linked)) fail("Native configuration must be a bounded regular file with one link");
+    if (!same(opened, linked)) fail("Native configuration changed while opening");
+    const buffer = Buffer.alloc(Number(opened.size) + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+      if (bytesRead === 0) break;
+      length += bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    const current = await filesystem.lstat(file, { bigint: true });
+    if (length !== Number(opened.size) || !valid(after) || !valid(current) || !same(opened, after) || !same(after, current)) fail("Native configuration changed while reading");
+    return JSON.parse(buffer.subarray(0, length).toString("utf8"));
+  } finally { await handle.close(); }
+}
+
+async function readExecutables(rows, { platform }) {
+  if (platform === "win32") {
+    const ids = rows.map((row) => row.pid);
+    const script = `$ErrorActionPreference='Stop'; @(${ids.join(",")}) | ForEach-Object { $processId=$_; $p=Get-Process -Id $processId -ErrorAction SilentlyContinue; [PSCustomObject]@{pid=$processId;executable=$p.Path} } | ConvertTo-Json -Compress`;
+    const shell = path.win32.join(process.env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    const result = await runProcessInspector(shell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { timeout: 10000, maxBuffer: 16384, windowsHide: true });
+    const parsed = JSON.parse(result.stdout);
+    return Array.isArray(parsed) ? parsed : [parsed];
+  }
+  if (platform === "darwin") return Promise.all(rows.map(async ({ pid }) => {
+    const result = await runProcessInspector("/bin/ps", ["-p", String(pid), "-o", "comm="], { timeout: 5000, maxBuffer: 4096 });
+    return { pid, executable: result.stdout.trim() };
+  }));
+  fail("Antigravity Desktop host verification is unsupported on this platform");
+}
+
+function validAncestry(rows, parentPid) {
+  return Array.isArray(rows) && rows.length > 0 && rows.length <= 8 && rows[0].pid === parentPid
+    && new Set(rows.map((row) => row.pid)).size === rows.length
+    && rows.every((row, index) => Number.isSafeInteger(row.pid) && row.pid > 0 && row.pid <= 0xffffffff
+      && Number.isSafeInteger(row.parentPid) && row.parentPid >= 0 && row.parentPid <= 0xffffffff
+      && typeof row.processStart === "string" && row.processStart.length > 0
+      && (!index || rows[index - 1].parentPid === row.pid));
+}
+
+function grants(value) {
+  if (value === undefined) return { allow: [], ask: [], deny: [] };
+  if (!object(value) || Object.keys(value).some((key) => !["allow", "ask", "deny"].includes(key))) fail("Native permission grants have an unsupported schema");
+  const result = {};
+  for (const key of ["allow", "ask", "deny"]) {
+    const items = value[key] ?? [];
+    if (!Array.isArray(items) || items.some((item) => typeof item !== "string" || !item.trim())) fail("Native permission grants have an unsupported schema");
+    result[key] = items;
+  }
+  return result;
+}
+
+function permissions(global, project) {
+  const settings = global?.userSettings;
+  if (!object(settings) || !object(project.settings ?? {})) fail("Native permission settings are unavailable");
+  const local = project.settings ?? {};
+  const wrapper = project.permissionGrants ?? {};
+  if (!object(wrapper) || Object.keys(wrapper).some((key) => !["permissionGrants", "v2Migrated"].includes(key))) fail("Native project permission grants have an unsupported schema");
+  if (settings.permissionGrantsV2Migrated !== true || (wrapper.v2Migrated !== undefined && wrapper.v2Migrated !== true)) fail("Native permission migration state is unsupported");
+  const globalGrants = grants(settings.globalPermissionGrants);
+  const projectGrants = grants(wrapper.permissionGrants);
+  const preset = local.permissionPreset ?? settings.permissionPreset;
+  const execution = local.autoExecutionPolicy ?? settings.autoExecutionPolicy;
+  const sandbox = local.sandboxMode ?? settings.enableTerminalSandbox;
+  const fileAccess = local.fileAccessPolicy ?? settings.nonWorkspaceFileAccessPolicy;
+  const artifact = local.artifactReviewMode ?? settings.artifactReviewMode;
+  const browser = local.browserJsExecutionPolicy ?? settings.browserJsExecutionPolicy;
+  const knownPresets = ["AGENT_PERMISSION_PRESET_TURBO", "AGENT_PERMISSION_PRESET_REQUEST_REVIEW", "AGENT_PERMISSION_PRESET_DEFAULT", "AGENT_PERMISSION_PRESET_AUTO"];
+  if (preset !== undefined && !knownPresets.includes(preset)) fail("Native permission preset is unsupported");
+  if (!['CASCADE_COMMANDS_AUTO_EXECUTION_EAGER', 'CASCADE_COMMANDS_AUTO_EXECUTION_OFF', 'CASCADE_COMMANDS_AUTO_EXECUTION_AUTO', 'CASCADE_COMMANDS_AUTO_EXECUTION_PROCEED_IN_SANDBOX'].includes(execution)
+    || typeof sandbox !== "boolean" || !["AGENT_SETTING_POLICY_ALLOW", "AGENT_SETTING_POLICY_ASK", "AGENT_SETTING_POLICY_DENY"].includes(fileAccess)
+    || !["ARTIFACT_REVIEW_MODE_ALWAYS", "ARTIFACT_REVIEW_MODE_TURBO", "ARTIFACT_REVIEW_MODE_AUTO"].includes(artifact)
+    || !["BROWSER_JS_EXECUTION_POLICY_DISABLED", "BROWSER_JS_EXECUTION_POLICY_ALWAYS_ASK", "BROWSER_JS_EXECUTION_POLICY_MODEL_DECIDES", "BROWSER_JS_EXECUTION_POLICY_TURBO"].includes(browser)) fail("Native permission settings are incomplete or unsupported");
+  const restricted = globalGrants.ask.length + globalGrants.deny.length + projectGrants.ask.length + projectGrants.deny.length > 0;
+  const unrestricted = (!preset || preset === "AGENT_PERMISSION_PRESET_TURBO") && execution === "CASCADE_COMMANDS_AUTO_EXECUTION_EAGER" && sandbox === false && fileAccess === "AGENT_SETTING_POLICY_ALLOW" && artifact === "ARTIFACT_REVIEW_MODE_TURBO" && browser === "BROWSER_JS_EXECUTION_POLICY_TURBO" && !restricted;
+  const mode = unrestricted ? "bypass" : "prompting";
+  return { mode, fingerprint: hash({ preset, execution, sandbox, fileAccess, artifact, browser, globalGrants, projectGrants, globalMigration: settings.permissionGrantsV2Migrated, projectMigration: wrapper.v2Migrated }) };
+}
+
+export async function resolveAntigravitySenderContext(meta, dependencies = {}) {
+  let reason = "Native Antigravity caller metadata is missing or invalid";
+  try {
+    if (!object(meta)) fail(reason);
+    const conversationId = meta[PREFIX + "conversation_id"];
+    const workspaces = meta[PREFIX + "workspace_paths"];
+    if (typeof conversationId !== "string" || !UUID.test(conversationId) || (workspaces !== undefined && (!Array.isArray(workspaces) || workspaces.length !== 1))) fail(reason);
+    const parent = meta[PREFIX + "parent_conversation_id"];
+    const root = meta[PREFIX + "root_conversation_id"];
+    if ((parent !== undefined && parent !== null && parent !== "") || (root !== undefined && root !== null && root !== "" && root !== conversationId)) fail("Nested Antigravity callers are not supported");
+    const { home = os.homedir(), platform = process.platform, parentPid = process.ppid, readAncestry = readProcessAncestry, readExecutables: executables = readExecutables, readJson: json = readAntigravityConfigurationJson, realpath = fs.realpath } = dependencies;
+    const paths = platform === "win32" ? path.win32 : path.posix;
+    const canonical = async (value) => {
+      if (typeof value !== "string" || value.includes("\0") || !paths.isAbsolute(value)) fail("Native workspace path is invalid");
+      const resolved = paths.normalize(await realpath(value));
+      return platform === "win32" ? resolved.toLowerCase() : resolved;
+    };
+    reason = "Native Antigravity Desktop process ancestry could not be verified";
+    const before = await readAncestry({ parentPid, platform });
+    if (!validAncestry(before, parentPid)) fail(reason);
+    const images = await executables(before, { platform });
+    if (!Array.isArray(images) || images.length !== before.length || new Set(images.map((image) => image.pid)).size !== before.length) fail(reason);
+    let appIndex = -1;
+    let expected;
+    for (let index = 0; index < before.length; index++) {
+      const executable = await canonical(images.find((image) => image.pid === before[index].pid)?.executable);
+      if (expected && executable === expected) { appIndex = index; break; }
+      const suffix = platform === "win32" ? "\\resources\\bin\\language_server.exe" : "/Contents/Resources/bin/language_server";
+      if (executable.endsWith(suffix)) {
+        const rootPath = executable.slice(0, -suffix.length);
+        expected = platform === "win32" ? paths.join(rootPath, "antigravity.exe") : paths.join(rootPath, "Contents", "MacOS", "Antigravity");
+      }
+    }
+    if (appIndex < 0) fail(reason);
+    reason = "Native Antigravity conversation could not be verified";
+    const readNative = dependencies.readNative ?? ((id) => callAntigravityDesktop({ operation: "read", conversationId: id }, { directory: antigravityBridgeDirectory(home) }));
+    const native = await readNative(conversationId);
+    if (native?.conversationId !== conversationId || native.surface !== "desktop" || !UUID.test(native.projectId)) fail(reason);
+    const cwd = await canonical(native.cwd);
+    if (workspaces !== undefined && await canonical(workspaces[0]) !== cwd) fail(reason);
+    const projectId = native.projectId;
+    reason = "Native Antigravity project permissions could not be verified";
+    const globalPath = paths.join(home, ".gemini", "config", "config.json");
+    const projectPath = paths.join(home, ".gemini", "config", "projects", projectId + ".json");
+    const global = await json(globalPath);
+    const project = await json(projectPath);
+    const resources = project?.projectResources?.resources;
+    if (project?.id !== projectId || !Array.isArray(resources) || resources.length !== 1) fail(reason);
+    const uri = resources[0]?.gitFolder?.folderUri;
+    if (typeof uri !== "string" || await canonical(fileURLToPath(uri, { windows: platform === "win32" })) !== cwd) fail(reason);
+    const policy = permissions(global, project);
+    const after = await readAncestry({ parentPid, platform });
+    if (!validAncestry(after, parentPid) || hash(before.slice(0, appIndex + 1)) !== hash(after.slice(0, appIndex + 1))) fail("Native Antigravity host changed during verification");
+    if (hash(global) !== hash(await json(globalPath)) || hash(project) !== hash(await json(projectPath))) fail("Native Antigravity permissions changed during verification");
+    return { status: "verified", provider: "antigravity", id: conversationId, conversationId, cwd, projectId, surface: "desktop", mode: policy.mode, permissionFingerprint: policy.fingerprint };
+  } catch (error) {
+    return { status: "unverified", provider: "antigravity", reason: error instanceof ContextError ? error.message : reason };
+  }
+}

package/src/antigravity-sidecar.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { antigravityBridgeDirectory, serveAntigravityDesktop } from "./antigravity-ipc.mjs";
+import { AntigravityDeliveries } from "./antigravity-deliveries.mjs";
+import { listAntigravityConversations, runAgentApi, sanitizeAntigravityMetadata } from "./antigravity-desktop.mjs";
+import { exitForVersionRequest } from "./cli-version.mjs";
+import { readProcessAncestry } from "./claude-sender-context.mjs";
+
+export async function createAntigravityParentGuard({ parentPid = process.ppid, inspect = readProcessAncestry } = {}) {
+  if (!Number.isSafeInteger(parentPid) || parentPid <= 1 || parentPid > 0xffffffff) throw new Error("Antigravity sidecar parent is unavailable; relaunch it from the native app");
+  const read = async () => {
+    const rows = await inspect({ parentPid, maxDepth: 1 });
+    const row = rows?.[0];
+    return rows?.length === 1 && row?.pid === parentPid && typeof row.processStart === "string" && row.processStart ? { pid: row.pid, processStart: row.processStart } : null;
+  };
+  let initial;
+  try { initial = await read(); } catch {}
+  if (!initial) throw new Error("Antigravity sidecar parent is unavailable; relaunch it from the native app");
+  let unavailable = false;
+  let pending;
+  return async () => {
+    if (!unavailable) {
+      pending ??= (async () => {
+        try {
+          const current = await read();
+          unavailable = !current || current.pid !== initial.pid || current.processStart !== initial.processStart;
+        } catch { unavailable = true; }
+      })();
+      await pending;
+      pending = undefined;
+    }
+    if (unavailable) throw Object.assign(new Error("Antigravity sidecar parent exited or changed; relaunch it from the native app"), { deliveryState: "not_sent" });
+  };
+}
+
+export async function startAntigravitySidecar({ directory = antigravityBridgeDirectory(), env = process.env, createParentGuard = createAntigravityParentGuard, serve = serveAntigravityDesktop, parentCheckIntervalMs = 5000, onParentLost = () => {} } = {}) {
+  if (!env.ANTIGRAVITY_AGENTAPI_EXE || !env.ANTIGRAVITY_LS_ADDRESS) throw new Error("Antigravity must launch this sidecar. Do not run it as a replacement app server.");
+  const assertParent = await createParentGuard();
+  const deliveries = new AntigravityDeliveries(path.join(directory, "desktop-deliveries"));
+  const sending = new Set();
+  let sidecar;
+  let timer;
+  let closing;
+  let closed = false;
+  let parentLost = false;
+  const close = () => {
+    closed = true;
+    clearTimeout(timer);
+    return closing ??= Promise.resolve().then(() => sidecar?.close());
+  };
+  const checkParent = async () => {
+    try { await assertParent(); }
+    catch (error) {
+      if (!parentLost) { parentLost = true; void close().then(onParentLost); }
+      throw error;
+    }
+  };
+  sidecar = await serve(async (request) => {
+    await checkParent();
+    if (!request || typeof request !== "object") throw new Error("Invalid sidecar request");
+    if (request.operation === "status") return { available: true, transport: "native-agentapi", permissionPolicy: "native-unchanged" };
+    if (request.operation === "list") return listAntigravityConversations({ surface: "desktop" });
+    if (request.operation === "read") {
+      const records = await listAntigravityConversations({ surface: "desktop" });
+      const record = records.find((item) => item.conversationId === request.conversationId);
+      if (!record) throw new Error("Exact Antigravity Desktop conversation not found");
+      const native = sanitizeAntigravityMetadata(await runAgentApi({ command: "metadata", conversationId: request.conversationId, env }), request.conversationId);
+      return { ...record, ...native };
+    }
+    if (request.operation === "receipt") return deliveries.read(request.requestId);
+    if (request.operation !== "send" || typeof request.prompt !== "string" || !request.prompt.trim() || request.prompt.length > 30000 || request.prompt.includes("\0")
+      || typeof request.cwd !== "string" || !path.isAbsolute(request.cwd) || !request.sender || !["codex", "claude"].includes(request.sender.provider)
+      || typeof request.sender.id !== "string" || !request.sender.id) throw new Error("Invalid Antigravity delivery request");
+    return deliveries.dispatch({ requestId: request.requestId, surface: "desktop", conversationId: request.conversationId, cwd: request.cwd, sender: request.sender, prompt: request.prompt }, async () => {
+      await checkParent();
+      if (sending.has(request.conversationId)) throw Object.assign(new Error("Another delivery is pending for this conversation"), { deliveryState: "not_sent" });
+      sending.add(request.conversationId);
+      try { return await runAgentApi({ command: "send", conversationId: request.conversationId, expectedCwd: request.cwd, prompt: request.prompt, env }); }
+      finally { sending.delete(request.conversationId); }
+    });
+  }, { directory });
+  try { await checkParent(); } catch (error) { await close(); throw error; }
+  const schedule = () => {
+    if (closed) return;
+    timer = setTimeout(async () => {
+      try { await checkParent(); } catch { return; }
+      schedule();
+    }, parentCheckIntervalMs);
+    timer.unref();
+  };
+  schedule();
+  return { ...sidecar, close };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  exitForVersionRequest(import.meta.url);
+  const sidecar = await startAntigravitySidecar({ onParentLost: () => process.exit(0) });
+  for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void sidecar.close().then(() => process.exit(0)); });
+}

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.23.0";
+const VERSION = "1.24.1";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
@@ -109,7 +109,7 @@ const replyForwarder = new ReplyForwarder({
     if (desktopOnly) assertAccountIdentity(record.accountContext);
     recheckScopeBindings(record.scopeBindings);
   },
-  deliver: (threadId, record) => delivery.deliver(threadId, `[message from Claude session ${record.fromSocket ?? "?"}]\n${record.absorbed ? "[This reply is the closing text of a turn that absorbed the message while it was running; it may not address the message.]\n" : ""}\n${record.text}`,
+  deliver: (threadId, record) => delivery.deliver(threadId, `${record.kind === "delivery_status" ? "[Bridge notification about Claude reply observation; not a Claude reply]" : `[message from Claude session ${record.fromSocket ?? "?"}]`}\n${record.absorbed ? "[This reply is the closing text of a turn that absorbed the message while it was running; it may not address the message.]\n" : ""}\n${record.text}`,
     desktopOnly ? { beforeSend: () => { assertAccountIdentity(record.accountContext); recheckScopeBindings(record.scopeBindings); }, accountContext: record.accountContext } : {}),
 });
 
@@ -593,13 +593,13 @@ registerTool(
       }
 
       if (wait === 0) {
-        return result(`Sent to peer transport for ${targetLabel}.\nClaude receipt unconfirmed; not waiting for a reply.\nMessage id: ${msgId}`);
+        return result(`Sent to peer transport for ${targetLabel}.\nClaude receipt unconfirmed; not waiting for a reply.\nMessage id: ${msgId}\nCheck read_claude_delivery with this message ID for terminal status, and read_claude_inbox for late replies or bridge notifications. Do not resend automatically.`);
       }
 
       if (!reply) {
         return result(
           `Sent to peer transport for ${targetLabel}.\n\nNo reply within ${wait}s; Claude receipt and outcome remain unconfirmed. ` +
-          `Do not automatically retry: the message may still be processed. Check read_claude_inbox for a late reply.\nMessage id: ${msgId}`,
+          `Do not automatically retry: the message may still be processed. Check read_claude_delivery for terminal status and read_claude_inbox for a late reply or bridge notification.\nMessage id: ${msgId}`,
           true,
         );
       }
@@ -633,7 +633,7 @@ registerTool(
     title: "Read messages Claude sent to this bridge",
     description:
       "Read and consume the oldest requested page of Claude messages, preserving unread messages. " +
-      "Includes late replies and their Codex forwarding status.",
+      "Includes late replies, terminal bridge-status notifications (not assistant replies), and their Codex forwarding status.",
     inputSchema: {
       limit: z.number().int().min(1).max(100).optional().describe("How many messages to return (default 20)"),
     },
@@ -655,7 +655,7 @@ registerTool(
           .map((m) => {
             const at = new Date(m.receivedAt).toISOString().replace("T", " ").slice(0, 19);
             const state = replyForwarder.read(m.inReplyTo ?? m.msgId) ?? m.forwardingError;
-            return `[${at}] from ${m.fromSocket ?? "?"}${state ? `\nCodex forwarding: ${state.status}${state.reason ? ` (${state.reason})` : ""}` : ""}\n${m.text}`;
+            return `[${at}] ${m.kind === "delivery_status" ? "bridge status for" : "from"} ${m.fromSocket ?? "?"}${state ? `\nCodex forwarding: ${state.status}${state.reason ? ` (${state.reason})` : ""}` : ""}\n${m.text}`;
           })
           .join("\n\n"),
       );

package/src/codex-native-response.mjs

@@ -140,7 +140,7 @@ function scanSegment(file, maxBytes, { threadId, turnId, afterOffset, prefixSize
       if (start >= dispatchAfterOffset && dispatchOutputs && record.type === "response_item" && record.payload.type === "function_call_output" &&
           record.payload.namespace === "codex_app" && record.payload.name === "send_message_to_thread" && dispatchOutputs.includes(record.payload.output)) {
         const metadata = record.payload.internal_chat_message_metadata_passthrough;
-        const selectedTurnId = record.payload.turn_id ?? record.payload.root_turn_id ?? metadata?.turn_id ?? metadata?.root_turn_id;
+        const selectedTurnId = record.payload.turn_id ?? metadata?.turn_id ?? record.payload.root_turn_id ?? metadata?.root_turn_id;
         if (!UUID.test(selectedTurnId) || !recordBelongsToTurn(entry, threadId, selectedTurnId)) throw new Error("The native dispatch has no consistent turn identity");
         dispatches.push({ turnId: selectedTurnId, start });
         if (dispatches.length > 1) throw new Error("Multiple post-send native dispatches match the reply receipt");
@@ -223,7 +223,11 @@ function replyHash(text) {
 function recordBelongsToTurn(entry, threadId, turnId) {
   const payload = entry.record.payload;
   const metadata = object(payload.internal_chat_message_metadata_passthrough) ? payload.internal_chat_message_metadata_passthrough : {};
-  const turnFields = [payload.turn_id, payload.root_turn_id, metadata.turn_id, metadata.root_turn_id].filter((value) => value !== undefined);
+  // root_turn_id describes causal ancestry and may belong to another thread.
+  // Only older records without explicit turn IDs use it as their identity.
+  const explicitTurns = [payload.turn_id, metadata.turn_id].filter((value) => value !== undefined);
+  const turnFields = explicitTurns.length ? explicitTurns
+    : [payload.root_turn_id, metadata.root_turn_id].filter((value) => value !== undefined);
   if (!turnFields.includes(turnId)) return false;
   if (turnFields.some((value) => value !== turnId)) throw validationError("The native response contains contradictory turn identity", "turn_identity", { recordByte: entry.start });
   const threadFields = [payload.thread_id, metadata.thread_id].filter((value) => value !== undefined);

package/src/desktop-read-tools.mjs

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
-import { DESKTOP_TOOL_BUDGET_MS } from "./thread-delivery.mjs";
+import { DESKTOP_TOOL_BUDGET_MS, OBSERVATION_UNAVAILABLE_GUIDANCE } from "./thread-delivery.mjs";
 import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
 import { ResponseSnapshots, responsePreferencesSchema, normalizeResponsePreferences, projectHistory, projectReply, assertResponseResultSize } from "./response-preferences.mjs";
 
@@ -102,7 +102,8 @@ export function registerDesktopReadTools(registerTool, {
         metadata: { ...metadata, threadId: delivered.threadId, turnId: result.turnId ?? null,
           turnStatus: ["completed", "interrupted", "failed"].includes(result.status) ? result.status : null, deliveryId,
           deliveryStatus: ["completed", "completed_no_reply"].includes(result.responseStatus) ? "accepted" : delivered.deliveryStatus ?? "accepted",
-          nextAction: result.status === "timeout" ? "wait_codex_reply" : "none" },
+          nextAction: result.status === "observation_unavailable" ? "inspect_existing_task" : result.status === "timeout" ? "wait_codex_reply" : "none",
+          ...(result.status === "observation_unavailable" ? { guidance: OBSERVATION_UNAVAILABLE_GUIDANCE } : {}) },
         items: projectReply(assistantItems ?? [], result.turnId) });
     };
     if (!delivered.threadId || Date.now() >= observationDeadline) return finish(timeout());

package/src/index.mjs

@@ -24,7 +24,7 @@ import {
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "./codex-full-access.mjs";
-import { DesktopTaskDelivery, DESKTOP_TOOL_BUDGET_MS } from "./thread-delivery.mjs";
+import { DesktopTaskDelivery, DESKTOP_TOOL_BUDGET_MS, OBSERVATION_UNAVAILABLE_GUIDANCE } from "./thread-delivery.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
 import { createRuntimeState } from "./runtime-state.mjs";
@@ -41,7 +41,7 @@ import { createRelayWake, relayKeeperEnabled, relayWakeStateFile, startRelayKeep
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.23.0";
+const VERSION = "1.24.1";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -170,10 +170,12 @@ function replyResult(delivered, deliveryId, result, notes = []) {
   result = { activity: [], errors: [], ...result };
   const deliveryStatus = ["completed", "completed_no_reply"].includes(result.responseStatus) ? "accepted" : delivered.deliveryStatus ?? "accepted";
   const pending = result.status === "timeout";
+  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 {
     ...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: pending && deliveryId ? "wait_codex_reply" : "none" },
+    structuredContent: { ...result, threadId: delivered.threadId, deliveryStatus, ...(deliveryId ? { deliveryId } : {}), nextAction: observationUnavailable ? "inspect_existing_task" : pending && deliveryId ? "wait_codex_reply" : "none" },
   };
 }
 

package/src/native-relay-companion.mjs

@@ -42,7 +42,7 @@ import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } fro
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.23.0";
+const VERSION = "1.24.1";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {

package/src/peer-protocol.mjs

@@ -875,9 +875,7 @@ export class PeerEndpoint {
       this.log(`ignored uncorrelated inbound peer message from ${message.fromSocket ?? "?"} in hardened mode`);
       return;
     }
-    this.activityRevision += 1;
-    const record = { ...message, receivedAt: Date.now(), sequence: ++this.messageSequence };
-    this.inbox.push(record);
+    const record = { ...message };
     if (key && correlated && pending.targetSocket === record.fromSocket) {
       const sent = this.sentMessages.get(key);
       if (sent) {
@@ -891,6 +889,13 @@ export class PeerEndpoint {
       }
       this.#removePendingReply(record.fromSocket, key);
     }
+    this.#publishMessage(record);
+  }
+
+  #publishMessage(record) {
+    this.activityRevision += 1;
+    Object.assign(record, { receivedAt: Date.now(), sequence: ++this.messageSequence });
+    this.inbox.push(record);
     this.log(`inbox <- ${record.fromSocket ?? "?"}: ${record.text.length} characters`);
     for (const listener of [...this.listeners]) {
       try { listener(record); }
@@ -911,9 +916,22 @@ export class PeerEndpoint {
       const outcome = readTranscriptOutcome(sessionId, cwd, msgId);
       if (outcome?.reply) this.#receiveMessage({ ...outcome.reply, fromSocket: pending.targetSocket });
       else if (outcome?.status === "interrupted") {
-        this.activityRevision += 1;
         this.deliveryReceipts.set(msgId, { ...outcome, fromSocket: pending.targetSocket, observedAt: Date.now() });
         this.#removePendingReply(pending.targetSocket, msgId);
+        const sent = this.sentMessages.get(msgId);
+        // A terminal observation is a bridge notification, never a Claude reply.
+        // Retain the send's original routing and scope for inbox filtering and
+        // forwarding; do not infer either from the currently active task.
+        this.#publishMessage({
+          kind: "delivery_status", source: "bridge", status: "interrupted",
+          msgId: `interrupted:${msgId}`, inReplyTo: msgId, fromSocket: pending.targetSocket,
+          replyThreadId: sent?.replyThreadId ?? null, accountContext: sent?.accountContext ?? null,
+          cwd: sent?.transcriptSession?.cwd ?? null, senderCwd: sent?.scopeBindings?.sender?.path ?? null,
+          scopeBindings: sent?.scopeBindings ?? null,
+          outcome: "unknown", waitEnded: true, taskCancelled: false, retrySafe: false,
+          reasonCode: outcome.reasonCode, interruptedBy: outcome.interruptedBy, backgroundTaskIds: outcome.backgroundTaskIds,
+          text: `[Bridge delivery status: ${outcome.reasonCode}]\nMessage id: ${msgId}\n${outcome.reason}`,
+        });
         this.log(`reply observation interrupted for ${msgId}; task outcome remains unknown`);
       }
     }
@@ -1096,7 +1114,7 @@ export class PeerEndpoint {
    */
   waitForReply(fromSocket, { timeoutMs = 120000, since = Date.now(), afterSequence = null, msgId } = {}) {
     const expectsTranscript = Boolean(msgId && this.sentMessages.get(msgId)?.transcriptSession);
-    const matches = (record) => record.fromSocket === fromSocket
+    const matches = (record) => record.kind !== "delivery_status" && record.fromSocket === fromSocket
       && (!expectsTranscript || (record.source === "transcript" && record.inReplyTo === msgId))
       && (!record.inReplyTo || !msgId || record.inReplyTo === msgId)
       && (afterSequence === null ? record.receivedAt >= since : record.sequence > afterSequence);

package/src/thread-delivery.mjs

@@ -27,6 +27,7 @@ import { requireClaudeSenderContext } from "./claude-sender-context.mjs";
 export const NATIVE_BACKEND = "codex-desktop-native";
 export const APP_SERVER_BACKEND = "app-server";
 export const DESKTOP_TOOL_BUDGET_MS = 40000;
+export const OBSERVATION_UNAVAILABLE_GUIDANCE = "The response could not be verified; this does not establish that delivery or the task failed. Inspect the existing task and this receipt; do not resend the prompt.";
 export const WORKSPACE_UNASSIGNED = "DESKTOP_WORKSPACE_UNASSIGNED";
 export const UNASSIGNED_WORKSPACE_GRACE_MS = 120000;
 const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
@@ -644,8 +645,9 @@ export class DesktopTaskDelivery {
         }
         turnId = observed.turnId ?? null;
         if (observed.status !== "pending") {
+          const nativeFailure = turnId && turn?.id === turnId && ["failed", "interrupted"].includes(turn.status) ? turn.status : null;
           return {
-            threadId, turnId, status: observed.status === "unavailable" ? "failed" : "completed",
+            threadId, turnId, status: observed.status === "unavailable" ? nativeFailure ?? "observation_unavailable" : "completed",
             responseStatus: observed.status, observationStatus: observed.status,
             text: observed.status === "completed" ? observed.text : "",
             ...(observed.reason ? { observationReason: observed.reason } : {}),