@minhspark/codex-mcp-bridge 1.25.1 → 1.25.3

package/src/antigravity-bridge.mjs

@@ -9,11 +9,12 @@ import { readClaudeSenderContext, requireClaudeSenderContext, stopProcessInspect
 import { readClaudeAccountContext } from "./desktop-account-context.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 import { antigravityBridgeDirectory, callAntigravityDesktop } from "./antigravity-ipc.mjs";
-import { AntigravityDeliveries } from "./antigravity-deliveries.mjs";
+import { AntigravityDeliveries, antigravityDeliveryError } from "./antigravity-deliveries.mjs";
 import { AntigravityCliSession } from "./antigravity-cli.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
 import { NativeDesktopRelay, desktopTaskSocketPath, accountRelaySocketPath } from "./native-relay.mjs";
 import { requireBridgeAccounts, readBridgeAccounts, assertAccountIdentity } from "./bridge-account-context.mjs";
+import { bridgeDiagnostic, withBridgeDiagnostic, preflightFailure } from "./recipient-preflight.mjs";
 
 exitForVersionRequest(import.meta.url);
 
@@ -28,7 +29,7 @@ const senderRelay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath()
 const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
 const schema = { requestId: z.string().uuid(), cwd: z.string().min(1), prompt: z.string().min(1).max(65536) };
 
-async function sender(extra) {
+async function identifySender(extra) {
   if (caller === "codex") {
     const context = await resolveCodexSenderContext(extra?._meta, { inspectDesktopTask: async (threadId) => {
       const accounts = requireBridgeAccounts(readBridgeAccounts());
@@ -46,17 +47,34 @@ async function sender(extra) {
   throw new Error("Install this bridge for Codex or Claude; unknown callers cannot read conversations or send work");
 }
 
+async function sender(extra) {
+  try { return await identifySender(extra); }
+  catch (error) {
+    error.code ??= "ANTIGRAVITY_SENDER_UNVERIFIED";
+    error.phase ??= "sender";
+    error.deliveryState = "not_sent";
+    throw error;
+  }
+}
+
 function sameCwd(expected, actual) {
-  if (!path.isAbsolute(expected) || !path.isAbsolute(actual)) throw new Error("Expected an absolute project directory");
-  const left = fs.realpathSync.native(expected);
-  const right = fs.realpathSync.native(actual);
-  if (path.relative(left, right)) throw new Error("Antigravity destination must match the verified sender's project directory");
-  rootPolicy.assert(left, "Antigravity project");
-  return left;
+  try {
+    if (!path.isAbsolute(expected) || !path.isAbsolute(actual)) throw new Error("Expected an absolute project directory");
+    const left = fs.realpathSync.native(expected);
+    const right = fs.realpathSync.native(actual);
+    if (path.relative(left, right)) throw new Error("Antigravity destination must match the verified sender's project directory");
+    rootPolicy.assert(left, "Antigravity project");
+    return left;
+  } catch (error) {
+    error.code ??= "ANTIGRAVITY_PROJECT_SCOPE_INVALID";
+    error.phase ??= "scope";
+    error.deliveryState = "not_sent";
+    throw error;
+  }
 }
 
 function owns(record, identity) {
-  if (!record || record.sender?.provider !== identity.provider || record.sender?.id !== identity.id) throw new Error("Delivery does not belong to this sending conversation");
+  if (!record || record.sender?.provider !== identity.provider || record.sender?.id !== identity.id) throw preflightFailure("ANTIGRAVITY_RECEIPT_OWNER_MISMATCH", "Delivery does not belong to this sending conversation");
   sameCwd(identity.cwd, record.cwd);
   return record;
 }
@@ -65,20 +83,49 @@ function handoff(prompt, identity) {
   return `[Agent handoff from ${identity.provider} conversation ${identity.id}. Native Antigravity permissions remain in effect.]\n\n${prompt}`;
 }
 
-const server = new McpServer({ name: "antigravity-bridge", version }, { instructions: "Send authorized work to Antigravity Desktop through its native sidecar or to an explicitly created CLI streaming session. Always select the requested surface; never substitute CLI for Desktop. The exact destination directory must match the verified sending conversation. Desktop delivery acceptance is not an agent reply. CLI sessions are bridge-owned headless sessions, not attached interactive terminals. Preserve requestId across retries and read_antigravity_delivery after pending or unknown outcomes; never resend automatically. Native tool approvals remain in force. Do not claim support for Antigravity-origin handoffs into Codex or Claude; this server receives from those hosts." });
+const server = new McpServer({ name: "antigravity-bridge", version }, { instructions: "Send authorized work to Antigravity Desktop through its native sidecar or to an explicitly created CLI streaming session. Always select the requested surface; never substitute CLI for Desktop. The exact destination directory must match the verified sending conversation. Desktop delivery acceptance is not an agent reply. CLI sessions are bridge-owned headless sessions, not attached interactive terminals. Preserve requestId across retries and read_antigravity_delivery after pending or unknown outcomes; never resend automatically. Native tool approvals remain in force. Antigravity Desktop can send authorized handoffs back to existing Codex Desktop tasks and live Claude Desktop Code sessions in the same project through its separate agent-bridge MCP server. From Antigravity, verify agent_bridge_status, discover list_agent_tasks, then use send_to_agent_task and read_agent_delivery. This inbound server does not initiate those outbound calls, and its status does not verify the outbound server's readiness. Antigravity CLI outbound and automatic App reply forwarding are not supported. An unreachable sidecar does not prove that the Antigravity App is closed; report its diagnostic and inspect sidecar configuration. Never use Computer Use, open an old chat, or create an empty, new, or error chat to load or recover a relay." });
 
 function register(name, description, inputSchema, readOnly, handler) {
   server.registerTool(name, { description, inputSchema, annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: true, openWorldHint: !readOnly } }, async (args, extra) => {
-    try { return result(await handler(args, extra)); }
-    catch (error) { return { ...result({ error: error.message, deliveryState: error.deliveryState ?? "not_sent" }), isError: true }; }
+    const options = { component: "antigravity-bridge", operation: name, requestId: args.requestId, conversationId: args.conversationId, readOnly };
+    try {
+      const value = await handler(args, extra);
+      const failure = antigravityDeliveryError(value);
+      if (failure) return withBridgeDiagnostic({ ...result(value), isError: true }, failure, { ...options, readOnly: false, msgId: value.result?.msgId });
+      if (value?.desktop?.available === false) return withBridgeDiagnostic({ ...result(value), isError: true }, { diagnostic: value.desktop.diagnostic }, options);
+      return result(value);
+    } catch (error) {
+      const diagnostic = bridgeDiagnostic(error, options);
+      return withBridgeDiagnostic({ ...result({ error: diagnostic.reason, code: diagnostic.code, deliveryState: error.deliveryState ?? diagnostic.deliveryState }), isError: true }, { diagnostic }, options);
+    }
   });
 }
 
-register("antigravity_bridge_status", "Inspect connection capabilities without sending prompts.", {}, true, async () => {
+register("antigravity_bridge_status", "Inspect native sidecar connectivity and supported inbound/outbound routes without sending prompts. Outbound readiness must be checked with agent_bridge_status inside Antigravity Desktop.", {}, true, async () => {
   let desktop;
   try { desktop = await callAntigravityDesktop({ operation: "status" }, { timeoutMs: 5000 }); }
-  catch { desktop = { available: false, reason: "Open Antigravity with the installed codex-bridge sidecar enabled" }; }
-  return { version, caller: caller ?? "unconfigured", desktop, cli: { transport: "stream-json", activeSessions: sessions.size, permissionPolicy: "native-unchanged", interactiveTerminalAttachment: false } };
+  catch (cause) {
+    const error = Object.assign(new Error("The native Antigravity sidecar could not be reached. This does not prove that the App is closed. Inspect its codex-bridge sidecar configuration and include the diagnostic in the report; do not open a chat to load the relay."), { code: "ANTIGRAVITY_SIDECAR_UNAVAILABLE", phase: cause.phase ?? "connect", cause });
+    const diagnostic = bridgeDiagnostic(error, { component: "antigravity-bridge", operation: "antigravity_bridge_status", readOnly: true });
+    desktop = { available: false, code: diagnostic.code, reason: diagnostic.reason, diagnostic };
+  }
+  return {
+    version,
+    caller: caller ?? "unconfigured",
+    desktop,
+    cli: { transport: "stream-json", activeSessions: sessions.size, permissionPolicy: "native-unchanged", interactiveTerminalAttachment: false },
+    outbound: {
+      supported: true,
+      server: "agent-bridge",
+      surface: "desktop",
+      targets: ["codex-desktop", "claude-desktop-code"],
+      scope: "existing-conversations-in-the-same-project",
+      readiness: "not_checked",
+      statusTool: "agent_bridge_status",
+      cliSupported: false,
+      automaticReplyForwarding: false,
+    },
+  };
 });
 
 register("list_antigravity_conversations", "List native Desktop conversations and bridge-owned CLI sessions in the sending project.", { surface: z.enum(["desktop", "cli"]) }, true, async ({ surface }, extra) => {
@@ -94,28 +141,29 @@ register("send_to_antigravity_conversation", "Send one authorized prompt to an e
   const identity = await sender(extra);
   const cwd = sameCwd(identity.cwd, args.cwd);
   const prompt = handoff(args.prompt, identity);
-  if (args.surface === "desktop" && (prompt.length > 30000 || prompt.includes("\0"))) throw new Error("Desktop handoff must fit within 30000 characters and contain no NUL");
+  if (args.surface === "desktop" && (prompt.length > 30000 || prompt.includes("\0"))) throw preflightFailure("ANTIGRAVITY_PROMPT_INVALID", "Desktop handoff must fit within 30000 characters and contain no NUL");
   if (args.surface === "desktop") return callAntigravityDesktop({ operation: "send", ...args, cwd, prompt, sender: identity });
   const entry = sessions.get(args.conversationId);
-  if (!entry || entry.sender.id !== identity.id || entry.sender.provider !== identity.provider) throw new Error("CLI session is not owned by this sender and bridge process");
+  if (!entry || entry.sender.id !== identity.id || entry.sender.provider !== identity.provider) throw preflightFailure("ANTIGRAVITY_SESSION_OWNER_MISMATCH", "CLI session is not owned by this sender and bridge process");
   sameCwd(cwd, entry.session.read().cwd);
   return deliveries.dispatch({ ...args, cwd, sender: identity, prompt }, async () => {
     const current = await sender(extra);
     sameCwd(cwd, current.cwd);
-    if (current.id !== identity.id) throw Object.assign(new Error("Sender changed before delivery"), { deliveryState: "not_sent" });
+    if (current.id !== identity.id) throw preflightFailure("ANTIGRAVITY_SENDER_CHANGED", "Sender changed before delivery");
     return entry.session.send(prompt);
-  });
+  }, { component: "antigravity-bridge", operation: "send_to_antigravity_conversation" });
 });
 
 register("start_antigravity_cli_session", "Create a new bridge-owned Antigravity CLI streaming session for explicitly authorized new work; sends the initial prompt and returns a durable delivery receipt.", schema, false, async (args, extra) => {
   const identity = await sender(extra);
   const cwd = sameCwd(identity.cwd, args.cwd);
-  if (sessions.size + startingSessions >= 4) throw new Error("At most four CLI sessions may be open in one bridge");
+  if (sessions.size + startingSessions >= 4) throw preflightFailure("ANTIGRAVITY_SESSION_CAPACITY", "At most four CLI sessions may be open in one bridge");
   return deliveries.dispatch({ ...args, cwd, sender: identity, surface: "cli" }, async () => {
-    if (sessions.size + startingSessions >= 4) throw Object.assign(new Error("CLI session capacity reached"), { deliveryState: "not_sent" });
+    if (sessions.size + startingSessions >= 4) throw preflightFailure("ANTIGRAVITY_SESSION_CAPACITY", "CLI session capacity reached");
     startingSessions++;
     let reserved = true;
     let session;
+    let sending = false;
     try {
       const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !/^(?:CODEX_|CLAUDE|ANTHROPIC_|MCP_)/i.test(name)));
       session = new AntigravityCliSession({ cwd, env });
@@ -126,9 +174,15 @@ register("start_antigravity_cli_session", "Create a new bridge-owned Antigravity
       reserved = false;
       const current = await sender(extra);
       sameCwd(cwd, current.cwd);
-      if (current.id !== identity.id) throw Object.assign(new Error("Sender changed before delivery"), { deliveryState: "not_sent" });
+      if (current.id !== identity.id) throw preflightFailure("ANTIGRAVITY_SENDER_CHANGED", "Sender changed before delivery");
+      sending = true;
       return await session.send(handoff(args.prompt, identity));
     } catch (error) {
+      if (!sending) {
+        error.code ??= "ANTIGRAVITY_CLI_START_FAILED";
+        error.phase ??= "startup";
+        error.deliveryState = "not_sent";
+      }
       if (error.deliveryState !== "unknown") {
         for (const [id, entry] of sessions) if (entry.session === session) sessions.delete(id);
         await session?.close();
@@ -137,7 +191,7 @@ register("start_antigravity_cli_session", "Create a new bridge-owned Antigravity
     } finally {
       if (reserved) startingSessions--;
     }
-  });
+  }, { component: "antigravity-bridge", operation: "start_antigravity_cli_session" });
 });
 
 register("read_antigravity_delivery", "Read the original receipt without resending. Desktop accepted means the native API accepted it, not that the agent completed a turn.", { surface: z.enum(["desktop", "cli"]), requestId: z.string().uuid() }, true, async (args, extra) => {
@@ -149,9 +203,9 @@ register("read_antigravity_delivery", "Read the original receipt without resendi
 register("close_antigravity_cli_session", "Close an idle bridge-owned CLI session belonging to the caller.", { conversationId: z.string().uuid() }, false, async ({ conversationId }, extra) => {
   const identity = await sender(extra);
   const entry = sessions.get(conversationId);
-  if (!entry || entry.sender.id !== identity.id || entry.sender.provider !== identity.provider) throw new Error("CLI session is not owned by this sender");
+  if (!entry || entry.sender.id !== identity.id || entry.sender.provider !== identity.provider) throw preflightFailure("ANTIGRAVITY_SESSION_OWNER_MISMATCH", "CLI session is not owned by this sender");
   sameCwd(identity.cwd, entry.session.read().cwd);
-  if (["running", "starting"].includes(entry.session.read().status)) throw new Error("Wait for the active CLI delivery before closing");
+  if (["running", "starting"].includes(entry.session.read().status)) throw preflightFailure("ANTIGRAVITY_SESSION_BUSY", "Wait for the active CLI delivery before closing");
   const closed = await entry.session.close();
   if (closed.status !== "closing") sessions.delete(conversationId);
   return { closed: closed.status !== "closing", conversationId, status: closed.status };

package/src/antigravity-deliveries.mjs

@@ -2,9 +2,19 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { ensureBridgeDirectory } from "./antigravity-ipc.mjs";
+import { bridgeDiagnostic } from "./recipient-preflight.mjs";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
+export function antigravityDeliveryError(record) {
+  if (!record || !UUID.test(record.requestId) || !["failed", "unknown"].includes(record.status)) return null;
+  return Object.assign(new Error(record.reason ?? "The original Antigravity delivery did not complete successfully"), {
+    code: record.diagnostic?.code ?? (record.status === "unknown" ? "ANTIGRAVITY_DELIVERY_UNKNOWN" : "ANTIGRAVITY_DELIVERY_FAILED"),
+    deliveryState: record.diagnostic?.deliveryState ?? "unknown",
+    diagnostic: record.diagnostic,
+  });
+}
+
 export class AntigravityDeliveries {
   constructor(directory) {
     this.directory = ensureBridgeDirectory(directory);
@@ -39,7 +49,11 @@ export class AntigravityDeliveries {
       record = JSON.parse(buffer.subarray(0, bytes).toString("utf8"));
     } finally { fs.closeSync(descriptor); }
     if (record.requestId !== requestId) throw new Error("Delivery identity mismatch");
-    if (record.status === "pending" && !this.active.has(requestId)) return { ...record, status: "unknown", reason: "This process cannot observe the original worker. Inspect the exact destination; do not resend." };
+    if (record.status === "pending" && !this.active.has(requestId)) {
+      const error = Object.assign(new Error("This process cannot observe the original worker. Inspect the original delivery receipt; do not resend or open a chat to load the relay."), { code: "ANTIGRAVITY_WORKER_UNAVAILABLE", phase: "receipt", deliveryState: "unknown" });
+      const diagnostic = bridgeDiagnostic(error, { component: "antigravity-deliveries", operation: record.operation ?? "send", requestId, conversationId: record.conversationId });
+      return { ...record, status: "unknown", reason: diagnostic.reason, diagnostic };
+    }
     return record;
   }
 
@@ -56,28 +70,38 @@ export class AntigravityDeliveries {
     fs.renameSync(temporary, this.file(record.requestId));
   }
 
-  async dispatch(request, operation) {
+  async dispatch(request, operation, diagnosticOptions = {}) {
     const { requestId, ...identity } = request;
     const digest = crypto.createHash("sha256").update(JSON.stringify(identity)).digest("hex");
     const existing = this.read(requestId);
     if (existing) {
-      if (existing.digest !== digest) throw new Error("requestId was already used for a different delivery");
+      if (existing.digest !== digest) throw Object.assign(new Error("requestId was already used for a different delivery; inspect the original receipt before further action"), { code: "ANTIGRAVITY_REQUEST_ID_CONFLICT", phase: "validation", deliveryState: "not_sent" });
       return existing;
     }
-    const record = { requestId, digest, status: "pending", cwd: request.cwd, sender: request.sender, conversationId: request.conversationId ?? null, surface: request.surface, createdAt: new Date().toISOString() };
+    const record = { requestId, digest, status: "pending", operation: diagnosticOptions.operation ?? "send", cwd: request.cwd, sender: request.sender, conversationId: request.conversationId ?? null, surface: request.surface, createdAt: new Date().toISOString() };
+    const diagnose = (error) => bridgeDiagnostic(error, { component: "antigravity-deliveries", operation: record.operation, ...diagnosticOptions, requestId, conversationId: record.conversationId, msgId: error.msgId });
     try { fs.writeFileSync(this.file(requestId), JSON.stringify(record), { flag: "wx", mode: 0o600 }); }
     catch (error) {
-      if (error.code !== "EEXIST") throw error;
-      throw new Error("Delivery is owned by another process. Inspect requestId; do not resend.");
+      if (error.code !== "EEXIST") {
+        error.deliveryState = "not_sent";
+        error.phase = "receipt";
+        throw error;
+      }
+      throw Object.assign(new Error("Delivery is owned by another process. Inspect requestId; do not resend."), { code: "ANTIGRAVITY_DELIVERY_IN_PROGRESS", phase: "receipt", deliveryState: "unknown" });
     }
     this.active.add(requestId);
     void Promise.resolve().then(operation).then((result) => {
       record.status = ["accepted", "sent_unconfirmed", "held", "refused"].includes(result?.status) ? result.status : result?.status && result.status !== "SUCCESS" ? "failed" : "completed";
       record.result = result;
       record.conversationId = result?.conversationId ?? result?.conversation_id ?? record.conversationId;
+      if (record.status === "failed") {
+        record.diagnostic = diagnose(Object.assign(new Error(typeof result.error === "string" ? result.error : "The native Antigravity delivery failed"), { code: result.status, deliveryState: result.deliveryState, sent: result.sent }));
+        record.reason = record.diagnostic.reason;
+      }
     }, (error) => {
-      record.status = ["not_sent", "not-sent"].includes(error.deliveryState) ? "failed" : "unknown";
-      record.reason = error.message;
+      record.diagnostic = diagnose(error);
+      record.status = record.diagnostic.deliveryState === "not_sent" ? "failed" : "unknown";
+      record.reason = record.diagnostic.reason;
       if (typeof error.msgId === "string" && UUID.test(error.msgId)) record.result = { msgId: error.msgId, completed: false };
       if (error.accountContext) record.result = { ...record.result, accountContext: error.accountContext };
     }).finally(() => {

package/src/antigravity-ipc.mjs

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
 import { relayFileIdentity, removeRelayFile } from "./native-relay-files.mjs";
+import { bridgeDiagnostic } from "./recipient-preflight.mjs";
 
 const LIMIT = 2 * 1024 * 1024;
 
@@ -55,28 +56,30 @@ export function callAntigravityDesktop(request, { directory = antigravityBridgeD
       socket.destroy();
       if (error) {
         error.deliveryState ??= dispatched ? "unknown" : "not_sent";
+        error.phase ??= dispatched ? "dispatch" : "connect";
+        error.diagnostic = bridgeDiagnostic(error, { component: "antigravity-sidecar", operation: request?.operation, requestId: request?.requestId, conversationId: request?.conversationId, readOnly: ["status", "list", "read", "receipt"].includes(request?.operation) });
         reject(error);
       } else resolve(result);
     };
-    const timer = setTimeout(() => done(Object.assign(new Error("Antigravity sidecar did not reply; inspect the original requestId before retrying"), { deliveryState: "unknown" })), timeoutMs);
+    const timer = setTimeout(() => done(Object.assign(new Error("Antigravity sidecar did not reply; inspect the original requestId before retrying"), { code: "ANTIGRAVITY_IPC_TIMEOUT" })), timeoutMs);
     socket.on("error", (error) => done(error));
-    socket.on("end", () => done(new Error("Antigravity sidecar disconnected before replying")));
+    socket.on("end", () => done(Object.assign(new Error("Antigravity sidecar disconnected before replying"), { code: "ANTIGRAVITY_IPC_DISCONNECTED" })));
     socket.on("connect", () => {
       const frame = JSON.stringify(request) + "\n";
-      if (Buffer.byteLength(frame) > LIMIT) return done(new Error("Request exceeds size limit"));
+      if (Buffer.byteLength(frame) > LIMIT) return done(Object.assign(new Error("Request exceeds size limit"), { code: "ANTIGRAVITY_REQUEST_TOO_LARGE", phase: "validation" }));
       dispatched = true;
       socket.write(frame);
     });
     socket.on("data", (chunk) => {
       buffer = Buffer.concat([buffer, chunk]);
-      if (buffer.length > LIMIT) return done(new Error("Sidecar response exceeds size limit"));
+      if (buffer.length > LIMIT) return done(Object.assign(new Error("Sidecar response exceeds size limit"), { code: "ANTIGRAVITY_RESPONSE_TOO_LARGE", phase: "response" }));
       const end = buffer.indexOf(10);
       if (end < 0) return;
       try {
         const response = JSON.parse(buffer.subarray(0, end).toString("utf8"));
-        if (response.error) return done(Object.assign(new Error(response.error), { deliveryState: response.deliveryState }));
+        if (response.error) return done(Object.assign(new Error(response.error), { code: response.code, phase: response.phase, deliveryState: response.deliveryState, diagnostic: response.diagnostic }));
         done(null, response.result);
-      } catch (error) { done(error); }
+      } catch (error) { done(Object.assign(new Error("Antigravity sidecar returned an invalid response"), { code: "ANTIGRAVITY_RESPONSE_INVALID", phase: "response", cause: error })); }
     });
   });
 }
@@ -101,12 +104,18 @@ export async function serveAntigravityDesktop(handler, { directory = antigravity
       const end = buffer.indexOf(10);
       if (end < 0) return;
       received = true;
+      let request;
       try {
-        const result = await handler(JSON.parse(buffer.subarray(0, end).toString("utf8")));
+        try { request = JSON.parse(buffer.subarray(0, end).toString("utf8")); }
+        catch { throw Object.assign(new Error("Invalid Antigravity sidecar request"), { code: "ANTIGRAVITY_REQUEST_INVALID", phase: "validation", deliveryState: "not_sent" }); }
+        const result = await handler(request);
         const frame = JSON.stringify({ result }) + "\n";
-        if (Buffer.byteLength(frame) > LIMIT) throw new Error("Sidecar response exceeds size limit");
+        if (Buffer.byteLength(frame) > LIMIT) throw Object.assign(new Error("Sidecar response exceeds size limit"), { code: "ANTIGRAVITY_RESPONSE_TOO_LARGE", phase: "response" });
         socket.end(frame);
-      } catch (error) { socket.end(JSON.stringify({ error: error.message, deliveryState: error.deliveryState }) + "\n"); }
+      } catch (error) {
+        const diagnostic = bridgeDiagnostic(error, { component: "antigravity-sidecar", operation: request?.operation, requestId: request?.requestId, conversationId: request?.conversationId, readOnly: ["status", "list", "read", "receipt"].includes(request?.operation), deliveryState: error.deliveryState ?? "unknown" });
+        socket.end(JSON.stringify({ error: diagnostic.reason, code: diagnostic.code, phase: diagnostic.phase, deliveryState: diagnostic.deliveryState, diagnostic }) + "\n");
+      }
     });
   });
   const privatePath = process.platform === "win32" ? socketPath : path.join(directory, `.${crypto.randomBytes(6).toString("hex")}.sock`);

package/src/antigravity-outbound-bridge.mjs

@@ -7,12 +7,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { resolveAntigravitySenderContext } from "./antigravity-sender-context.mjs";
 import { createAntigravityOutboundTargets } from "./antigravity-outbound-targets.mjs";
-import { AntigravityDeliveries } from "./antigravity-deliveries.mjs";
+import { AntigravityDeliveries, antigravityDeliveryError } from "./antigravity-deliveries.mjs";
 import { antigravityBridgeDirectory } from "./antigravity-ipc.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 import { stopProcessInspectors } from "./claude-sender-context.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
 import { assertAccountIdentity } from "./bridge-account-context.mjs";
+import { bridgeDiagnostic, withBridgeDiagnostic, preflightFailure } from "./recipient-preflight.mjs";
 
 const { version } = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
@@ -20,19 +21,34 @@ const targetSchema = { target: z.enum(["codex", "claude"]) };
 const taskSchema = { ...targetSchema, conversationId: z.string().uuid(), taskId: z.string().min(1).max(256).optional() };
 
 export function createAntigravityOutboundBridge({ resolveSender = resolveAntigravitySenderContext, targets = createAntigravityOutboundTargets(), deliveries = new AntigravityDeliveries(path.join(antigravityBridgeDirectory(), "outbound-deliveries")), rootPolicy = createHardenedRootPolicy() } = {}) {
-  const server = new McpServer({ name: "agent-bridge", version }, { instructions: "Send user-authorized work FROM the current Antigravity Desktop conversation to an exact existing Codex Desktop task or Claude Desktop Code session in the same project. Use list_agent_tasks first, verify title and identity, then send_to_agent_task with a fresh requestId. Keep requestId after uncertainty and read_agent_delivery; never automatically resend. Native permissions and sender identity are verified on every call. Do not launch a CLI substitute, impersonate Codex/Claude, or change permissions to overcome a rejection. Native acceptance is not task completion; read_agent_task for Codex or read_agent_delivery for a Claude reply. Independent new work requires a separate native conversation; this bridge only continues existing tasks. Agent-authored handoffs must be in English and name Antigravity as the author." });
+  const server = new McpServer({ name: "agent-bridge", version }, { instructions: "Send user-authorized work FROM the current Antigravity Desktop conversation to an exact existing Codex Desktop task or Claude Desktop Code session in the same project. Use list_agent_tasks first, verify title and identity, then send_to_agent_task with a fresh requestId. Keep requestId after uncertainty and read_agent_delivery; never automatically resend. Native permissions and sender identity are verified on every call. Do not launch a CLI substitute, impersonate Codex/Claude, or change permissions to overcome a rejection. Native acceptance is not task completion; read_agent_task for Codex or read_agent_delivery for a Claude reply. Independent new work requires a separate native conversation; this bridge only continues existing tasks. Never use Computer Use, open an old chat, or create an empty, new, or error chat to load or recover a relay. Report the structured diagnostic when a native relay or session is unavailable. Agent-authored handoffs must be in English and name Antigravity as the author." });
 
   function scope(expected, actual) {
-    if (!path.isAbsolute(expected) || !path.isAbsolute(actual)) throw new Error("An absolute project directory is required");
-    const canonical = fs.realpathSync.native(expected);
-    if (path.relative(canonical, fs.realpathSync.native(actual))) throw new Error("Destination must match the verified Antigravity sender's project");
-    rootPolicy.assert(canonical, "Antigravity sender project");
-    return canonical;
+    try {
+      if (!path.isAbsolute(expected) || !path.isAbsolute(actual)) throw new Error("An absolute project directory is required");
+      const canonical = fs.realpathSync.native(expected);
+      if (path.relative(canonical, fs.realpathSync.native(actual))) throw new Error("Destination must match the verified Antigravity sender's project");
+      rootPolicy.assert(canonical, "Antigravity sender project");
+      return canonical;
+    } catch (error) {
+      error.code ??= "ANTIGRAVITY_PROJECT_SCOPE_INVALID";
+      error.phase ??= "scope";
+      error.deliveryState = "not_sent";
+      throw error;
+    }
   }
 
   async function sender(extra) {
-    const identity = await resolveSender(extra?._meta);
-    if (identity.status !== "verified" || identity.provider !== "antigravity" || !identity.id || !["bypass", "prompting"].includes(identity.mode)) throw new Error(identity.reason ?? "Antigravity sender is not verified");
+    let identity;
+    try {
+      identity = await resolveSender(extra?._meta);
+      if (identity.status !== "verified" || identity.provider !== "antigravity" || !identity.id || !["bypass", "prompting"].includes(identity.mode)) throw new Error(identity.reason ?? "Antigravity sender is not verified");
+    } catch (error) {
+      error.code ??= "ANTIGRAVITY_SENDER_UNVERIFIED";
+      error.phase ??= "sender";
+      error.deliveryState = "not_sent";
+      throw error;
+    }
     scope(identity.cwd, identity.cwd);
     return identity;
   }
@@ -40,44 +56,54 @@ export function createAntigravityOutboundBridge({ resolveSender = resolveAntigra
   function recheck(identity, extra) {
     return async () => {
       const current = await sender(extra);
-      if (JSON.stringify(current) !== JSON.stringify(identity)) throw Object.assign(new Error("Antigravity sender identity or permissions changed before delivery"), { deliveryState: "not_sent" });
+      if (JSON.stringify(current) !== JSON.stringify(identity)) throw preflightFailure("ANTIGRAVITY_SENDER_CHANGED", "Antigravity sender identity or permissions changed before delivery");
     };
   }
 
   function register(name, description, inputSchema, readOnly, handler) {
     server.registerTool(name, { description, inputSchema, annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: true, openWorldHint: !readOnly } }, async (args, extra) => {
-      try { return result(await handler(args, extra)); }
-      catch (error) { return { ...result({ error: error.message, deliveryState: error.deliveryState ?? "not_sent" }), isError: true }; }
+      const options = { component: "agent-bridge", operation: name, requestId: args.requestId, conversationId: args.conversationId, readOnly };
+      try {
+        const value = await handler(args, extra);
+        const failure = antigravityDeliveryError(value);
+        if (failure) return withBridgeDiagnostic({ ...result(value), isError: true }, failure, { ...options, readOnly: false, msgId: value.result?.msgId });
+        if (value?.diagnostic && (value.nativeReceipt === null || value.sender?.status !== "verified")) return withBridgeDiagnostic({ ...result(value), isError: true }, { diagnostic: value.diagnostic }, options);
+        return result(value);
+      } catch (error) {
+        const diagnostic = bridgeDiagnostic(error, options);
+        return withBridgeDiagnostic({ ...result({ error: diagnostic.reason, code: diagnostic.code, deliveryState: error.deliveryState ?? diagnostic.deliveryState }), isError: true }, { diagnostic }, options);
+      }
     });
   }
 
   register("agent_bridge_status", "Check this Antigravity caller's native identity and outbound bridge capabilities without sending work.", {}, true, async (_, extra) => {
     const identity = await resolveSender(extra?._meta);
     const metadataFields = Object.fromEntries(Object.entries(extra?._meta ?? {}).filter(([key]) => key.startsWith("antigravity.google/")).map(([key, value]) => [key, Array.isArray(value) ? "array" : typeof value]));
-    return { version, sender: identity, metadataFields, targets: ["codex-desktop", "claude-desktop"], permissions: "native-unchanged", createsConversations: false };
+    const diagnostic = identity.status === "verified" ? null : bridgeDiagnostic(Object.assign(new Error(identity.reason ?? "Antigravity sender is not verified"), { code: "ANTIGRAVITY_SENDER_UNVERIFIED", phase: "sender" }), { component: "agent-bridge", operation: "agent_bridge_status", readOnly: true });
+    return { version, sender: identity, metadataFields, targets: ["codex-desktop", "claude-desktop"], permissions: "native-unchanged", createsConversations: false, ...(diagnostic ? { diagnostic } : {}) };
   });
 
-  register("list_agent_tasks", "List exact existing native tasks in this Antigravity conversation's project before selecting a destination.", targetSchema, true, async (args, extra) => {
+  register("list_agent_tasks", "List exact existing native tasks in this Antigravity conversation's project before selecting a destination. Dormant Claude tasks remain unavailable until their native session is already connected.", targetSchema, true, async (args, extra) => {
     const identity = await sender(extra);
     return targets.list({ ...args, sender: identity, beforeSend: recheck(identity, extra) });
   });
 
-  register("send_to_agent_task", "Continue an exact existing Codex or Claude Desktop task with authorized work. Preserve requestId across retries; inspect the durable receipt.", { ...taskSchema, requestId: z.string().uuid(), cwd: z.string().min(1), prompt: z.string().min(1).max(30000) }, false, async (args, extra) => {
+  register("send_to_agent_task", "Continue an exact existing Codex or connected Claude Desktop task with authorized work. Unavailable native sessions produce a diagnostic without opening chats; native permissions remain unchanged. Preserve requestId across retries; inspect the durable receipt.", { ...taskSchema, requestId: z.string().uuid(), cwd: z.string().min(1), prompt: z.string().min(1).max(30000) }, false, async (args, extra) => {
     const identity = await sender(extra);
     const cwd = scope(identity.cwd, args.cwd);
-    if (args.prompt.includes("\0")) throw new Error("Prompt must not contain NUL");
+    if (args.prompt.includes("\0")) throw preflightFailure("ANTIGRAVITY_PROMPT_INVALID", "Prompt must not contain NUL");
     const prompt = `[From Antigravity Desktop · ${path.basename(cwd)} · Authorized task handoff]\n[Source conversation: ${identity.id}]\n\n${args.prompt}`;
     return deliveries.dispatch({ ...args, cwd, surface: args.target, sender: { provider: identity.provider, id: identity.id }, prompt }, async () => {
       await recheck(identity, extra)();
       const sent = await targets.send({ ...args, cwd, prompt, sender: identity, ...(args.target === "codex" ? { threadId: args.conversationId } : { sessionId: args.conversationId }), beforeSend: recheck(identity, extra) });
       return { ...sent, completed: false };
-    });
+    }, { component: "agent-bridge", operation: "send_to_agent_task" });
   });
 
   register("read_agent_delivery", "Read an owned delivery without resending. Accepted or pending does not prove a completed response.", { requestId: z.string().uuid() }, true, async ({ requestId }, extra) => {
     const identity = await sender(extra);
     const record = deliveries.read(requestId);
-    if (!record || record.sender?.provider !== "antigravity" || record.sender.id !== identity.id) throw new Error("Delivery does not belong to this Antigravity conversation");
+    if (!record || record.sender?.provider !== "antigravity" || record.sender.id !== identity.id) throw preflightFailure("ANTIGRAVITY_RECEIPT_OWNER_MISMATCH", "Delivery does not belong to this Antigravity conversation");
     scope(identity.cwd, record.cwd);
     if (record.result?.accountContext) assertAccountIdentity(record.result.accountContext);
     if (record.surface === "claude" && record.result?.msgId) {
@@ -85,7 +111,8 @@ export function createAntigravityOutboundBridge({ resolveSender = resolveAntigra
         return { ...record, nativeReceipt: await targets.read({ target: "claude", msgId: record.result.msgId, sender: identity, beforeSend: recheck(identity, extra) }) };
       } catch (error) {
         if (error.code !== "ANTIGRAVITY_NATIVE_RECEIPT_UNAVAILABLE") throw error;
-        return { ...record, nativeReceipt: null, recovery: "The original native receipt is unavailable. Inspect the exact Claude Desktop task before further action; do not resend.", receiptError: error.message };
+        const diagnostic = bridgeDiagnostic(error, { component: "agent-bridge", operation: "read_agent_delivery", phase: "receipt", readOnly: true, requestId, msgId: record.result.msgId, conversationId: record.conversationId });
+        return { ...record, nativeReceipt: null, recovery: "The original native receipt is unavailable. Report the diagnostic before further action; do not resend or open a chat to load the relay.", receiptError: diagnostic.reason, diagnostic: record.diagnostic ?? diagnostic, receiptDiagnostic: diagnostic };
       }
     }
     return record;

package/src/antigravity-outbound-targets.mjs

@@ -3,10 +3,10 @@ import path from "node:path";
 import { NativeDesktopRelay, desktopTaskSocketPath, accountRelaySocketPath } from "./native-relay.mjs";
 import { readBridgeAccounts, requireBridgeAccounts, assertAccountIdentity } from "./bridge-account-context.mjs";
 import { PeerEndpoint, listClaudeSessions, assertClaudeSessionProcess } from "./peer-protocol.mjs";
-import { readClaudeDesktopContext } from "./claude-desktop-context.mjs";
+import { readClaudeDesktopContext, readClaudeDesktopTasks } from "./claude-desktop-context.mjs";
 import { readClaudeInboundPolicy } from "./claude-inbound-policy.mjs";
 import { assertRecipientClass } from "./recipient-preflight.mjs";
-import { sameClaudeDesktopRecipient } from "./claude-session-router.mjs";
+import { recoverClaudeDesktopSession, sameClaudeDesktopRecipient } from "./claude-session-router.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
 
@@ -42,6 +42,7 @@ export function createAntigravityOutboundTargets(options = {}) {
   const readAccounts = options.readAccounts ?? readBridgeAccounts;
   const assertAccounts = options.assertAccounts ?? ((identity) => assertAccountIdentity(identity, readAccounts()));
   const listSessions = options.listSessions ?? listClaudeSessions;
+  const listTasks = options.listTasks ?? ((account) => readClaudeDesktopTasks({ account }));
   const readContext = options.readContext ?? ((session, account) => readClaudeDesktopContext(session, { account }));
   const readInbound = options.readInbound ?? readClaudeInboundPolicy;
   const assertProcess = options.assertProcess ?? assertClaudeSessionProcess;
@@ -122,6 +123,29 @@ export function createAntigravityOutboundTargets(options = {}) {
     return { ...session, desktop, inbound: readInbound(session.cwd) };
   }
 
+  function savedClaudeTask(context, tasks, sessionId, taskId) {
+    if (!Array.isArray(tasks) || tasks.length > 8192) throw blocked("Saved Claude Desktop tasks cannot be verified");
+    const matches = tasks.filter((task) => task.taskId === taskId);
+    const task = matches[0];
+    if (matches.length !== 1 || typeof taskId !== "string" || !taskId.startsWith("local_") || !UUID.test(taskId.slice(6)) || task.fileTaskId !== taskId || task.isArchived !== false
+        || !UUID.test(sessionId ?? "") || task.cliSessionId !== sessionId || !sameDirectory(captureDirectory(task.cwd).path, context.cwd)
+        || typeof task.title !== "string" || !task.title.trim() || task.title.length > 1024 || /[\u0000-\u001f\u007f]/u.test(task.title)) throw blocked("Exact saved Claude Desktop task and session identity cannot be verified");
+    return { target: "claude", sessionId, taskId, cwd: context.cwd, title: task.title, status: "dormant", recoverable: false, code: "CLAUDE_SESSION_NOT_READY" };
+  }
+
+  async function recoverClaudeRecipient(context, sessionId, taskId) {
+    if (listSessions().some((session) => session.sessionId === sessionId && session.alive)) return claudeRecipient(context, sessionId, taskId);
+    savedClaudeTask(context, await listTasks(context.accounts.claude), sessionId, taskId);
+    await context.check();
+    const resolved = await recoverClaudeDesktopSession({
+      target: "auto", expectedCwd: context.cwd, expectedTaskId: taskId, sessions: listSessions(), account: context.accounts.claude, readContext,
+    }, {
+      listTasks: () => listTasks(context.accounts.claude), listSessions, beforeInspect: context.check,
+    });
+    await context.check();
+    return claudeRecipient(context, resolved.session.sessionId, taskId);
+  }
+
   async function list({ target, sender, beforeSend } = {}) {
     const context = operation(sender, beforeSend);
     await context.check();
@@ -148,9 +172,15 @@ export function createAntigravityOutboundTargets(options = {}) {
       try {
         const desktop = readContext(session, context.accounts.claude);
         const verified = claudeRecipient(context, session.sessionId, desktop?.taskId);
-        rows.push({ target: "claude", sessionId: verified.sessionId, taskId: verified.desktop.taskId, cwd: context.cwd, title: verified.desktop.title ?? null, permissionClass: verified.desktop.permissionClass ?? null, inboundPolicy: verified.inbound?.value ?? null });
+        rows.push({ target: "claude", sessionId: verified.sessionId, taskId: verified.desktop.taskId, cwd: context.cwd, title: verified.desktop.title ?? null, permissionClass: verified.desktop.permissionClass ?? null, inboundPolicy: verified.inbound?.value ?? null, status: "ready" });
       } catch {}
     }
+    const tasks = await listTasks(context.accounts.claude);
+    if (!Array.isArray(tasks) || tasks.length > 8192) throw blocked("Saved Claude Desktop tasks cannot be verified");
+    for (const task of tasks) {
+      if (rows.some((row) => row.taskId === task.taskId) || listSessions().some((session) => session.sessionId === task.cliSessionId && session.alive)) continue;
+      try { rows.push(savedClaudeTask(context, tasks, task.cliSessionId, task.taskId)); } catch {}
+    }
     await context.check();
     return rows;
   }
@@ -178,7 +208,7 @@ export function createAntigravityOutboundTargets(options = {}) {
       }
     }
     if (target !== "claude") throw blocked("Target must be codex or claude");
-    const recipient = claudeRecipient(context, sessionId, taskId);
+    const recipient = await recoverClaudeRecipient(context, sessionId, taskId);
     assertRecipientClass(recipient, context.identity);
     if (!peer) peer = peerFactory({ name: `antigravity-${process.pid}`, cwd: context.cwd, signalExit: false, env, protectSocket: protectCurrentUserPipe });
     await peer.start();
@@ -189,7 +219,7 @@ export function createAntigravityOutboundTargets(options = {}) {
         recipient: { permissionMode: recipient.desktop.permissionMode ?? null, permissionClass: recipient.desktop.permissionClass ?? null, inboundPolicy: recipient.inbound?.value ?? null },
         beforeSend: async () => {
           await context.check();
-          const current = claudeRecipient(context, sessionId, taskId);
+          const current = claudeRecipient(context, recipient.sessionId, taskId);
           if (!sameClaudeDesktopRecipient(recipient, current)) throw blocked("Claude session process or socket changed before delivery");
           assertRecipientClass(current, context.identity);
           await context.check();
@@ -198,7 +228,7 @@ export function createAntigravityOutboundTargets(options = {}) {
       msgId = outcome.msgId;
       receipts.set(msgId, { sender: context.identity, accountContext: context.accountContext, cwd: context.cwd });
       await context.check();
-      return { target, sessionId, taskId, cwd: context.cwd, msgId, status: outcome.delivery?.status ?? "sent_unconfirmed", completed: false, accountContext: context.accountContext };
+      return { target, sessionId: recipient.sessionId, taskId, cwd: context.cwd, msgId, status: outcome.delivery?.status ?? "sent_unconfirmed", completed: false, accountContext: context.accountContext };
     } catch (error) {
       if (error.msgId) receipts.set(error.msgId, { sender: context.identity, accountContext: context.accountContext, cwd: context.cwd });
       if (msgId) error.msgId = msgId;
@@ -221,6 +251,11 @@ export function createAntigravityOutboundTargets(options = {}) {
     }
     if (target !== undefined && target !== "claude") throw blocked("Target must be codex or claude");
     if (msgId === undefined) {
+      if (!listSessions().some((session) => session.sessionId === sessionId && session.alive)) {
+        const task = savedClaudeTask(context, await listTasks(context.accounts.claude), sessionId, taskId);
+        await context.check();
+        return task;
+      }
       const recipient = claudeRecipient(context, sessionId, taskId);
       await context.check();
       return { target: "claude", sessionId, taskId, cwd: context.cwd, title: recipient.desktop.title ?? null, permissionClass: recipient.desktop.permissionClass ?? null, inboundPolicy: recipient.inbound?.value ?? null };

package/src/bridge-readiness.mjs

@@ -1,6 +1,6 @@
 import { RELAY_DOWN_GUIDANCE } from "./thread-delivery.mjs";
 
-export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = true, verifyTargetProject }) {
+export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = true, nativeDiagnostic, verifyTargetProject }) {
   const issues = [];
   if (sender?.status !== "verified") issues.push({ code: "SENDER_UNVERIFIED", detail: sender?.reason ?? "No current Code session identity", action: "Load the user-level Claude Code bridge entry in this existing task; a shared Desktop entry cannot identify the caller. Run the Code registration check, then reload the affected client." });
   const projectPolicy = scope?.status?.(sender?.status === "verified" ? sender.cwd : undefined) ?? null;
@@ -20,6 +20,6 @@ export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = tr
       issues.push({ code: error.code ?? "PROJECT_SCOPE_UNVERIFIED", detail: error.message, action: "Select a destination in the verified sender's project. A project grant does not authorize cross-project delivery." });
     }
   }
-  if (!nativeAvailable) issues.push({ code: "RELAY_UNAVAILABLE", action: RELAY_DOWN_GUIDANCE });
+  if (!nativeAvailable) issues.push({ code: nativeDiagnostic?.code ?? "RELAY_UNAVAILABLE", detail: nativeDiagnostic?.reason, action: RELAY_DOWN_GUIDANCE, ...(nativeDiagnostic ? { diagnostic: nativeDiagnostic } : {}) });
   return { ready: issues.length === 0, readyScope: "transport-identity-and-project", hostToolPermission: "evaluated-by-client-at-call-time", sender, projectPolicy, target, issues };
 }