@minhspark/codex-mcp-bridge 1.25.2 → 1.26.0

package/src/antigravity-outbound-bridge.mjs

@@ -7,32 +7,68 @@ 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 { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./background-relay-mcp.mjs";
 import { assertAccountIdentity } from "./bridge-account-context.mjs";
+import { bridgeDiagnostic, withBridgeDiagnostic, preflightFailure } from "./recipient-preflight.mjs";
+import { createReloadControl, exitWhenClientCloses } from "./reload-control.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) }] });
 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." });
+export function createAntigravityOutboundBridge({ resolveSender = resolveAntigravitySenderContext, targets = createAntigravityOutboundTargets(), deliveries = new AntigravityDeliveries(path.join(antigravityBridgeDirectory(), "outbound-deliveries")), rootPolicy = createHardenedRootPolicy(), env = process.env, channel = process } = {}) {
+  const reload = createReloadControl({
+    entry: "antigravity-outbound-bridge.mjs", env, channel,
+    inspect: () => deliveries.active.size ? "Antigravity outbound deliveries are still active" : targets.reloadReason?.() ?? null,
+    quiesce: () => targets.quiesce(),
+    exportState: () => ({ directory: deliveries.directory, targets: targets.exportReloadState() }),
+    restore: (state) => {
+      if (typeof state.directory !== "string" || path.relative(state.directory, deliveries.directory)) throw new Error("Antigravity durable receipt directory changed during reload");
+      targets.restoreReloadState(state.targets);
+    },
+    activate: () => targets.activate(),
+  });
+  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 for a native task, 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 native work requires a separate native conversation; native handoff tools only continue 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. " + BACKGROUND_WORKER_GUIDANCE });
+
+  registerBackgroundTools((name, config, handler) => server.registerTool(name, config, async (args, extra) => {
+    try { return await reload.run(() => handler(args, extra)); }
+    catch (error) {
+      return withBridgeDiagnostic({ isError: true, content: [] }, error, { component: "agent-bridge", operation: name, requestId: args.requestId, readOnly: config.annotations?.readOnlyHint === true });
+    }
+  }), { env });
 
   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 +76,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 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?.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 +131,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;
@@ -96,7 +143,8 @@ export function createAntigravityOutboundBridge({ resolveSender = resolveAntigra
     return targets.read({ ...args, cwd: identity.cwd, sender: identity, ...(args.target === "codex" ? { threadId: args.conversationId } : { sessionId: args.conversationId }), beforeSend: recheck(identity, extra) });
   });
 
-  return { server, close: async () => { await targets.close(); await server.close(); } };
+  reload.listen();
+  return { server, reload, busy: () => deliveries.active.size ? "Antigravity outbound deliveries are still active" : null, close: async () => { await targets.close(); await server.close(); } };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
@@ -109,7 +157,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     await bridge.close();
     await stopProcessInspectors();
   };
-  for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void stop(); });
-  process.stdin.once("end", () => { void stop(); });
   await bridge.server.connect(new StdioServerTransport());
+  const shutdown = exitWhenClientCloses({ busy: bridge.busy, stop });
+  for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => { void shutdown.close(signal); });
 }

package/src/antigravity-outbound-targets.mjs

@@ -3,12 +3,13 @@ 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";
+import { cloneReloadState } from "./reload-control.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;
 
@@ -42,6 +43,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;
@@ -49,10 +51,12 @@ export function createAntigravityOutboundTargets(options = {}) {
   const peerFactory = options.peerFactory ?? ((settings) => new PeerEndpoint(settings));
   const receipts = new Map();
   let peer;
+  let peerCwd;
+  let paused = false;
   let closed = false;
 
   function operation(sender, beforeSend, required = false) {
-    if (closed) throw blocked("Antigravity outbound targets have been closed");
+    if (closed || paused) throw blocked("Antigravity outbound targets are closed or quiesced");
     if (required && typeof beforeSend !== "function") throw blocked("A live Antigravity sender revalidation callback is required");
     const identity = senderIdentity(sender);
     const cwd = captureDirectory(identity.cwd);
@@ -60,7 +64,7 @@ export function createAntigravityOutboundTargets(options = {}) {
     const accounts = readAccounts();
     const accountContext = requireBridgeAccounts(accounts);
     const check = async () => {
-      if (closed) throw blocked("Antigravity outbound targets have been closed");
+      if (closed || paused) throw blocked("Antigravity outbound targets are closed or quiesced");
       assertAccounts(accountContext);
       roots.recheck(root, "Antigravity sender project");
       const current = captureDirectory(identity.cwd);
@@ -122,6 +126,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 +175,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,9 +211,12 @@ 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 });
+    if (!peer) {
+      peerCwd = context.cwd;
+      peer = peerFactory({ name: `antigravity-${process.pid}`, cwd: peerCwd, signalExit: false, env, protectSocket: protectCurrentUserPipe });
+    }
     await peer.start();
     let msgId;
     try {
@@ -189,7 +225,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 +234,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 +257,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 };
@@ -240,5 +281,54 @@ export function createAntigravityOutboundTargets(options = {}) {
     await peer?.closed;
   }
 
-  return { list, send, read, close };
+  const reloadReason = () => peer?.reloadReason() ?? null;
+
+  async function quiesce() {
+    const reason = reloadReason();
+    if (reason) throw new Error(reason);
+    paused = true;
+    await peer?.quiesce();
+  }
+
+  function exportReloadState() {
+    if (!paused || reloadReason()) throw new Error("Quiesce Antigravity targets before exporting reload state");
+    return cloneReloadState({ receipts: [...receipts], peer: peer ? { cwd: peerCwd, state: peer.exportReloadState() } : null });
+  }
+
+  function restoreReloadState(input) {
+    if (peer || receipts.size || closed) throw new Error("Antigravity reload state requires empty targets");
+    const state = cloneReloadState(input);
+    if (!state || !Array.isArray(state.receipts) || state.receipts.length > 100000
+      || state.peer !== null && (!state.peer || typeof state.peer.cwd !== "string" || !path.isAbsolute(state.peer.cwd))) {
+      throw new Error("Invalid Antigravity target reload state");
+    }
+    const restored = new Map();
+    for (const pair of state.receipts) {
+      if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string" || !pair[0] || restored.has(pair[0])) throw new Error("Invalid Antigravity receipt reload record");
+      const record = pair[1];
+      const identity = senderIdentity(record?.sender);
+      if (typeof record.cwd !== "string" || !path.isAbsolute(record.cwd) || typeof identity.cwd !== "string" || !sameDirectory(record.cwd, identity.cwd)
+        || !record.accountContext || typeof record.accountContext.codex !== "string" || !record.accountContext.codex
+        || typeof record.accountContext.claude !== "string" || !record.accountContext.claude) throw new Error("Invalid Antigravity receipt ownership reload record");
+      restored.set(pair[0], { ...record, sender: identity });
+    }
+    if (!state.peer && restored.size) throw new Error("Antigravity receipts require their native peer state");
+    if (state.peer) {
+      const nativeMessages = state.peer.state?.sentMessages;
+      if (!Array.isArray(nativeMessages) || nativeMessages.length !== restored.size || nativeMessages.some(([id]) => !restored.has(id))) throw new Error("Antigravity receipt ownership does not match native peer state");
+      const candidate = peerFactory({ name: `antigravity-${process.pid}`, cwd: state.peer.cwd, signalExit: false, env, protectSocket: protectCurrentUserPipe });
+      candidate.restoreReloadState(state.peer.state);
+      peer = candidate;
+      peerCwd = state.peer.cwd;
+    }
+    for (const [id, record] of restored) receipts.set(id, record);
+  }
+
+  async function activate() {
+    if (closed) throw new Error("Antigravity targets are closed");
+    await peer?.resume();
+    paused = false;
+  }
+
+  return { list, send, read, close, reloadReason, quiesce, exportReloadState, restoreReloadState, activate };
 }

package/src/background-antigravity-worker.mjs

@@ -0,0 +1,192 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { AntigravityCliSession, resolveAntigravityCliBinary } from "./antigravity-cli.mjs";
+
+const runFile = promisify(execFile);
+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;
+const RELAY_TOOLS = ["worker_status", "list_workers", "send_to_worker", "read_worker_delivery"];
+const RELAY_ENV = ["AGENT_RELAY_ENDPOINT", "AGENT_RELAY_TOKEN", "AGENT_RELAY_WORKER_ID", "AGENT_RELAY_REQUEST_ID"];
+const MAX_STDERR_BYTES = 65536;
+
+function failure(code, reason, phase, deliveryState = "not_sent") {
+  return Object.assign(new Error(reason), { code, phase, deliveryState, sent: deliveryState === "sent" ? true : deliveryState === "not_sent" ? false : null });
+}
+
+export async function inspectAntigravityWorker({ env = process.env, executable, platform = process.platform, run = runFile } = {}) {
+  const state = { agent: "antigravity", available: false, authenticated: null, ready: false };
+  let binary;
+  try { binary = resolveAntigravityCliBinary({ binary: executable, env, platform }); }
+  catch { return { ...state, code: "ANTIGRAVITY_CLI_UNAVAILABLE", reason: "The dedicated Antigravity CLI executable is unavailable." }; }
+  try {
+    const result = await run(binary, ["--version"], { env: { ...env }, windowsHide: true, shell: false, timeout: 5000, maxBuffer: 4096, encoding: "utf8" });
+    const status = result?.exitCode ?? result?.status ?? result?.code ?? 0;
+    const version = String(result?.stdout ?? "").trim();
+    if (status !== 0 || !/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i.test(version)) throw new Error("Invalid version result");
+    return { ...state, available: true, executable: binary, version, code: "ANTIGRAVITY_AUTH_UNVERIFIED", reason: "Antigravity CLI has no supported read-only authentication probe. An authorized job must establish runtime authentication." };
+  } catch {
+    return { ...state, executable: binary, code: "ANTIGRAVITY_INSPECTION_FAILED", reason: "Antigravity CLI version inspection failed or returned an unsupported response." };
+  }
+}
+
+function classifyDiagnostic(value) {
+  if (typeof value !== "string") return null;
+  const text = value.slice(0, 8192).replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ");
+  if (/\b(?:unauthenticated|auth(?:entication)?[ _-]+(?:required|failed)|not[ _-]+authenticated|not[ _-]+logged[ _-]+in|(?:login|sign[ -]?in)[ _-]+required|(?:credentials?|tokens?)[ _-]+(?:are[ _-]+|is[ _-]+|has[ _-]+|have[ _-]+)?(?:expired|invalid|missing))\b/i.test(text)) return "authentication";
+  if (/\b(?:soft[ _-]+denied|permission[ _-]+(?:denied|required|rejected)|approval[ _-]+required|requires?[ _-]+(?:user[ _-]+)?(?:approval|permission))\b/i.test(text)
+      || /\b(?:tool|mcp)\b[^\r\n]{0,160}\b(?:not allowed|blocked|denied)\b/i.test(text)) return "permission";
+  return null;
+}
+
+function discoverRelayTools(tools) {
+  if (tools === undefined) return { relayToolsVerified: false, relayToolDiscovery: "unadvertised" };
+  if (!Array.isArray(tools) || tools.length > 4096 || tools.some((name) => typeof name !== "string" || !name || name.length > 256)) {
+    throw failure("ANTIGRAVITY_WORKER_PROTOCOL_ERROR", "Antigravity CLI advertised an invalid tool list.", "startup");
+  }
+  const names = new Set(tools.map((name) => name.replace(/[-_:/\.]+/g, "_")));
+  if (RELAY_TOOLS.every((name) => names.has(name) || names.has(`worker_relay_${name}`) || names.has(`mcp_worker_relay_${name}`))) return { relayToolsVerified: true, relayToolDiscovery: "explicit-tools" };
+  if (tools.includes("call_mcp_tool")) return { relayToolsVerified: false, relayToolDiscovery: "mcp-dispatcher" };
+  throw failure("ANTIGRAVITY_RELAY_TOOLS_MISSING", "Antigravity CLI advertised neither its native MCP dispatcher nor all required worker-relay tools. Inspect the CLI MCP configuration.", "relay");
+}
+
+function workerEnvironment(env, relayMcp, requestId) {
+  const grant = relayMcp?.env;
+  if (typeof relayMcp?.command !== "string" || !relayMcp.command || !Array.isArray(relayMcp.args)
+      || relayMcp.args.some((value) => typeof value !== "string") || !grant || typeof grant !== "object" || Array.isArray(grant)
+      || RELAY_ENV.some((key) => typeof grant[key] !== "string" || !grant[key] || grant[key].length > 8192 || grant[key].includes("\0"))
+      || grant.AGENT_RELAY_REQUEST_ID !== requestId) {
+    throw failure("ANTIGRAVITY_RELAY_GRANT_INVALID", "The Antigravity worker requires a complete relay grant bound to this request.", "preflight");
+  }
+  const cleaned = Object.fromEntries(Object.entries(env).filter(([name]) => !/^(?:CODEX_|CLAUDE|ANTHROPIC_|MCP_|AGENT_RELAY_)/i.test(name)));
+  for (const key of RELAY_ENV) cleaned[key] = grant[key];
+  return cleaned;
+}
+
+export async function runAntigravityWorker({ executable, cwd, prompt, requestId, sessionId, env = process.env, relayMcp, onEvent = () => {}, signal, timeoutMs = 600000, spawn, conversationId, resume } = {}) {
+  if (conversationId !== undefined || resume !== undefined) throw failure("ANTIGRAVITY_WORKER_RESUME_UNSUPPORTED", "Background Antigravity jobs require a fresh CLI conversation and cannot resume an external conversation.", "preflight");
+  if (typeof prompt !== "string" || !prompt.trim() || !UUID.test(requestId ?? "")
+      || sessionId !== undefined && !UUID.test(sessionId) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1
+      || typeof onEvent !== "function") {
+    throw failure("ANTIGRAVITY_WORKER_INPUT_INVALID", "The Antigravity worker requires a non-empty prompt, valid request identity, and bounded timeout.", "preflight");
+  }
+  if (signal?.aborted) throw failure("ANTIGRAVITY_WORKER_ABORTED", "The Antigravity worker was canceled before dispatch.", "cancellation");
+  const workerEnv = workerEnvironment(env, relayMcp, requestId);
+  const deadline = Date.now() + timeoutMs;
+  let session;
+  let initialized;
+  let accepted = false;
+  let terminal = false;
+  let diagnosticKind = null;
+  let stderrBytes = 0;
+  let stderrTail = "";
+  let stderrOverflow = false;
+  let observerFailed = false;
+  let finalError;
+  let deadlineTimer;
+  let rejectInterruption;
+  const interrupted = new Promise((resolve, reject) => { rejectInterruption = reject; });
+  interrupted.catch(() => {});
+  const observers = [];
+  const deliveryState = () => accepted ? "sent" : session && ["unknown", "completed"].includes(session.read().deliveryState) ? "unknown" : "not_sent";
+  const notify = (event) => {
+    try { observers.push(Promise.resolve(onEvent(event)).catch(() => { observerFailed = true; })); }
+    catch { observerFailed = true; }
+  };
+  const accept = () => {
+    if (accepted) return;
+    accepted = true;
+    notify({ type: "accepted", sessionId: initialized.conversation_id });
+  };
+  const observeDiagnostic = (value) => {
+    const kind = classifyDiagnostic(value);
+    if (kind && (!diagnosticKind || kind === "authentication")) diagnosticKind = kind;
+  };
+  const diagnosticFailure = () => diagnosticKind === "authentication"
+    ? failure("ANTIGRAVITY_AUTH_REQUIRED", "Antigravity CLI could not authenticate the background worker. Restore its configured credentials without opening a Desktop chat.", "authentication", deliveryState())
+    : diagnosticKind === "permission"
+      ? failure("ANTIGRAVITY_PERMISSION_DENIED", "Antigravity CLI denied a required tool operation. Inspect its scoped permission rules; no permissions were changed.", "permission", deliveryState())
+      : stderrOverflow ? failure("ANTIGRAVITY_WORKER_DIAGNOSTIC_LIMIT", "Antigravity CLI exceeded its bounded diagnostic limit; successful execution could not be verified.", "observation", deliveryState()) : null;
+  const abort = () => {
+    if (!terminal) {
+      const error = failure("ANTIGRAVITY_WORKER_ABORTED", "The Antigravity worker was canceled. Inspect its existing receipt before further action.", "cancellation", deliveryState());
+      session?.fail(error);
+      rejectInterruption(error);
+    }
+  };
+  const observe = (promise) => Promise.race([promise, interrupted]);
+  try {
+    session = new AntigravityCliSession({
+      binary: executable, cwd, env: workerEnv, spawn,
+      startupTimeoutMs: Math.min(30000, timeoutMs), turnTimeoutMs: timeoutMs, closeTimeoutMs: Math.min(1000, timeoutMs),
+      onStderr(chunk) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        if (bytes.length > MAX_STDERR_BYTES - stderrBytes) stderrOverflow = true;
+        if (stderrBytes >= MAX_STDERR_BYTES) return;
+        const text = bytes.subarray(0, MAX_STDERR_BYTES - stderrBytes).toString("utf8");
+        stderrBytes += Math.min(bytes.length, MAX_STDERR_BYTES - stderrBytes);
+        for (let offset = 0; offset < text.length; offset += 4096) {
+          stderrTail = `${stderrTail}${text.slice(offset, offset + 4096)}`.slice(-8192);
+          observeDiagnostic(stderrTail);
+        }
+      },
+      onEvent(event) {
+        if (event.event === "init") {
+          initialized = { conversation_id: event.conversation_id, tools: event.init.tools };
+          return;
+        }
+        if (event.event === "result") {
+          accept();
+          terminal = true;
+          observeDiagnostic(event.result.error);
+          return;
+        }
+        if (event.event !== "step_update") return;
+        const step = event.step_update;
+        if (!step || step.conversation_id !== initialized?.conversation_id) throw new Error("Invalid Antigravity event");
+        if (!session.awaitingResult) throw new Error("Invalid Antigravity event");
+        if (step.step_type === "user_input" && step.state === "DONE") accept();
+        const error = step.tool_info?.error;
+        if (error) observeDiagnostic(typeof error === "string" ? error : `${typeof error.type === "string" ? error.type : ""} ${typeof error.message === "string" ? error.message : ""}`);
+      },
+    });
+    deadlineTimer = setTimeout(() => {
+      const error = failure("ANTIGRAVITY_WORKER_TIMEOUT", "The Antigravity worker exceeded its observation deadline. Inspect its existing receipt before further action.", "observation", deliveryState());
+      session.fail(error);
+      rejectInterruption(error);
+    }, Math.max(1, deadline - Date.now()));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) throw failure("ANTIGRAVITY_WORKER_ABORTED", "The Antigravity worker was canceled before dispatch.", "cancellation");
+    const started = await observe(session.start());
+    if (diagnosticFailure()) throw diagnosticFailure();
+    const relayTools = discoverRelayTools(initialized?.tools);
+    notify({ type: "session", sessionId: started.conversationId });
+    await observe(Promise.all(observers));
+    if (observerFailed) throw failure("ANTIGRAVITY_WORKER_OBSERVER_FAILED", "The Antigravity worker could not record its session event.", "observation");
+    if (signal?.aborted) throw failure("ANTIGRAVITY_WORKER_ABORTED", "The Antigravity worker was canceled before dispatch.", "cancellation");
+    const remaining = deadline - Date.now();
+    if (remaining < 1) throw failure("ANTIGRAVITY_WORKER_TIMEOUT", "The Antigravity worker exceeded its observation deadline.", "observation");
+    session.turnTimeoutMs = remaining;
+    const result = await observe(session.send(prompt));
+    await observe(session.close());
+    await observe(Promise.all(observers));
+    if (observerFailed) throw failure("ANTIGRAVITY_WORKER_OBSERVER_FAILED", "The Antigravity worker could not record its acceptance event.", "observation", deliveryState());
+    if (diagnosticFailure()) throw diagnosticFailure();
+    if (result.status !== "SUCCESS" || result.error) throw failure("ANTIGRAVITY_WORKER_TURN_FAILED", "Antigravity CLI returned an unsuccessful background turn. Inspect the existing worker receipt.", "execution", deliveryState());
+    return { output: result.response, sessionId: result.conversation_id, ...(sessionId ? { workerSessionId: sessionId } : {}), deliveryState: "sent", sent: true, authenticated: true, ...relayTools };
+  } catch (error) {
+    const state = deliveryState();
+    if (/^ANTIGRAVITY_[A-Z_]+$/.test(error?.code ?? "")) finalError = failure(error.code, error.message, error.phase, state);
+    else if (diagnosticFailure()) finalError = diagnosticFailure();
+    else if (["STARTUP_TIMEOUT", "TURN_TIMEOUT"].includes(error?.code)) finalError = failure("ANTIGRAVITY_WORKER_TIMEOUT", "The Antigravity worker exceeded its observation deadline. Inspect its existing receipt before further action.", "observation", state);
+    else if (error?.code === "INVALID_PROTOCOL") finalError = failure("ANTIGRAVITY_WORKER_PROTOCOL_ERROR", "Antigravity CLI returned invalid or mismatched streaming data.", "protocol", state);
+    else finalError = failure("ANTIGRAVITY_WORKER_FAILED", "The Antigravity CLI worker could not complete its operation. Inspect its existing receipt before further action.", state === "not_sent" ? "startup" : "execution", state);
+    finalError.requestId = requestId;
+    if (initialized?.conversation_id) finalError.sessionId = initialized.conversation_id;
+    if (sessionId) finalError.workerSessionId = sessionId;
+    throw finalError;
+  } finally {
+    clearTimeout(deadlineTimer);
+    signal?.removeEventListener("abort", abort);
+    const closed = await session?.close();
+    if (!finalError && closed?.status === "closing") throw failure("ANTIGRAVITY_WORKER_STOP_FAILED", "The Antigravity worker did not confirm process shutdown.", "shutdown", deliveryState());
+  }
+}