@minhspark/codex-mcp-bridge 1.25.2 → 1.26.0

package/scripts/worker-relay.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { callBackgroundRelay } from "../src/background-relay-client.mjs";
+import { withBridgeDiagnostic } from "../src/recipient-preflight.mjs";
+import { relayFailure, RELAY_UUID } from "../src/background-relay-config.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+
+exitForVersionRequest(import.meta.url);
+const args = process.argv.slice(2);
+const action = args.shift() ?? "status";
+const option = name => { const index = args.indexOf(name); return index < 0 ? undefined : args[index + 1]; };
+try {
+  let result;
+  if (action === "status" || action === "list") result = await callBackgroundRelay(action);
+  else if (action === "read") result = await callBackgroundRelay("read", { requestId: option("--request-id"), waitSec: Number(option("--wait") ?? 0) }, { timeoutMs: (Number(option("--wait") ?? 0) + 10) * 1000 });
+  else if (action === "send") {
+    if (!args.includes("--stdin") || !RELAY_UUID.test(option("--request-id") ?? "")) throw relayFailure("WORKER_REQUEST_INVALID", "Use --stdin and a persistent --request-id UUID so uncertain deliveries can be inspected safely");
+    const chunks = [];
+    let bytes = 0;
+    for (;;) {
+      const buffer = Buffer.alloc(65536);
+      const count = fs.readSync(0, buffer, 0, buffer.length, null);
+      if (!count) break;
+      bytes += count;
+      if (bytes > 256 * 1024) throw relayFailure("WORKER_REQUEST_TOO_LARGE", "The authorized prompt exceeds the worker input limit");
+      chunks.push(buffer.subarray(0, count));
+    }
+    const prompt = Buffer.concat(chunks).toString("utf8");
+    result = await callBackgroundRelay("send", { agent: option("--agent"), cwd: option("--cwd"), requestId: option("--request-id"), prompt });
+  } else if (action === "--help" || action === "help") {
+    process.stdout.write("worker-relay status | list | send --agent <codex|claude|antigravity> --cwd <project> --request-id <uuid> --stdin | read --request-id <uuid> [--wait <0-60>]\n");
+  } else throw relayFailure("WORKER_COMMAND_INVALID", "Unknown worker relay command");
+  if (result) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    if (result.status === "failed" || result.status === "unknown") process.exitCode = 1;
+  }
+} catch (error) {
+  const result = withBridgeDiagnostic({ isError: true, content: [] }, error, { component: "worker-relay-cli", operation: action, requestId: option("--request-id") });
+  process.stderr.write(result.content.map(item => item.text ?? "").join("\n") + "\n");
+  process.exitCode = 1;
+}

package/src/antigravity-bridge.mjs

@@ -9,11 +9,13 @@ 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";
+import { createReloadControl, exitWhenClientCloses } from "./reload-control.mjs";
 
 exitForVersionRequest(import.meta.url);
 
@@ -27,8 +29,21 @@ const caller = process.env.ANTIGRAVITY_BRIDGE_CALLER;
 const senderRelay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() });
 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) };
+const reloadReason = () => startingSessions ? "Antigravity CLI sessions are still starting"
+  : deliveries.active.size ? "Antigravity deliveries are still active"
+    : sessions.size ? "Open Antigravity CLI sessions retain process pipes and cannot migrate" : null;
+const reload = createReloadControl({
+  entry: "antigravity-bridge.mjs",
+  inspect: reloadReason,
+  exportState: () => ({ caller: caller ?? null, directory }),
+  restore: (state) => {
+    if (state.caller !== (caller ?? null) || typeof state.directory !== "string" || path.relative(state.directory, directory)) {
+      throw new Error("Antigravity caller or durable receipt directory changed during reload");
+    }
+  },
+});
 
-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 +61,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 +97,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 reload.run(() => 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 +155,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 +188,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 +205,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 +217,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 };
@@ -165,6 +233,7 @@ async function stop() {
   await stopProcessInspectors();
   await server.close();
 }
-for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void stop(); });
-process.stdin.once("end", () => { void stop(); });
 await server.connect(new StdioServerTransport());
+const shutdown = exitWhenClientCloses({ busy: () => startingSessions || deliveries.active.size ? "Antigravity deliveries are still active" : null, stop });
+for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void shutdown.close(signal); });
+reload.listen();

package/src/antigravity-cli.mjs

@@ -50,6 +50,8 @@ export class AntigravityCliSession {
     this.env = { ...(options.env ?? process.env) };
     this.binary = resolveAntigravityCliBinary({ binary: options.binary, env: this.env });
     this.spawn = options.spawn ?? spawnProcess;
+    this.onEvent = options.onEvent;
+    this.onStderr = options.onStderr;
     this.requestedConversationId = options.conversationId ?? null;
     if (this.requestedConversationId !== null && !UUID.test(this.requestedConversationId)) throw new Error("Invalid Antigravity conversation ID");
     this.startupTimeoutMs = positive(options.startupTimeoutMs, 30000, "startupTimeoutMs");
@@ -102,7 +104,11 @@ export class AntigravityCliSession {
       this.child.stdin.on("error", () => this.fail(failure("Antigravity CLI input pipe failed", "STDIN_ERROR", this.pending ? "unknown" : this.deliveryState)));
       this.child.stdout.on("error", () => this.fail(failure("Antigravity CLI output pipe failed", "STDOUT_ERROR", this.pending ? "unknown" : this.deliveryState)));
       this.child.stderr.on("error", () => this.fail(failure("Antigravity CLI diagnostic pipe failed", "STDERR_ERROR", this.pending ? "unknown" : this.deliveryState)));
-      this.child.stderr.resume();
+      if (this.onStderr) this.child.stderr.on("data", (chunk) => {
+        try { this.onStderr(chunk); }
+        catch { this.fail(failure("Antigravity CLI diagnostic observer failed", "OBSERVER_ERROR", this.pending ? "unknown" : this.deliveryState)); }
+      });
+      else this.child.stderr.resume();
       this.child.stdout.on("data", (chunk) => this.consume(chunk));
       this.child.on("close", (code, signal) => {
         this.exited = true;
@@ -147,6 +153,7 @@ export class AntigravityCliSession {
       this.conversationId = event.conversation_id;
       this.permissionMode = event.init.permission_mode;
       this.status = "idle";
+      this.onEvent?.(structuredClone(event));
       clearTimeout(this.startTimer);
       this.startResolve(this.read());
       this.startResolve = null;
@@ -154,11 +161,15 @@ export class AntigravityCliSession {
       return;
     }
     if (!this.conversationId) throw new Error("Invalid Antigravity event");
-    if (event.event !== "result") return;
+    if (event.event !== "result") {
+      this.onEvent?.(structuredClone(event));
+      return;
+    }
     const result = event.result;
     if (!this.awaitingResult || !result || result.conversation_id !== this.conversationId
         || typeof result.status !== "string" || !/^[A-Z][A-Z_]{0,127}$/.test(result.status)
         || typeof result.response !== "string" || result.error !== undefined && typeof result.error !== "string") throw new Error("Invalid Antigravity event");
+    this.onEvent?.(structuredClone(event));
     this.lastResult = { conversation_id: result.conversation_id, status: result.status, response: result.response, ...(result.error === undefined ? {} : { error: result.error }) };
     this.awaitingResult = false;
     this.deliveryState = "completed";

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`);