@minhspark/codex-mcp-bridge 1.13.9 → 1.15.0

package/src/native-relay.mjs

@@ -6,6 +6,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
 import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir } from "./platform.mjs";
+import { assertAccountIdentity } from "./bridge-account-context.mjs";
 
 /**
  * The Codex Desktop app owns the per-thread writer lock of every thread it has
@@ -35,6 +36,7 @@ import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir } from "./platform.mjs";
 export const NATIVE_DISPATCH_METHOD = "tools/call";
 
 export const RELAY_PROTOCOL_VERSION = 1;
+export const ACCOUNT_RELAY_PROTOCOL_VERSION = 2;
 
 /**
  * A relay frame carries one chat message, so a megabyte-scale line is either a
@@ -70,6 +72,28 @@ export function desktopTaskSocketPath(env = process.env) {
   return env.CODEX_NATIVE_RELAY_SOCKET ?? `${relaySocketPath(env)}-desktop-tasks`;
 }
 
+export function accountRelaySocketPath(env = process.env) {
+  return `${relaySocketPath(env)}-accounts-v2`;
+}
+
+export function relayAccountContext(value) {
+  if (value === undefined) return undefined;
+  if (!exactObject(value, ["claude", "codex"]) || Object.keys(value).length !== 2 || [value.claude, value.codex].some((item) => typeof item !== "string" || !/^[a-f0-9]{64}$/.test(item))) {
+    throw beforeWriteError(new NativeRelayError("A bound relay request requires exact Claude and Codex account fingerprints", "RELAY_BAD_REQUEST"));
+  }
+  return Object.freeze({ claude: value.claude, codex: value.codex });
+}
+
+function beforeWriteError(error) {
+  const failure = new NativeRelayError(error?.message ?? "Relay preflight failed before dispatch", typeof error?.code === "string" ? error.code : "RELAY_PREFLIGHT_FAILED", { reachedCompanion: false });
+  failure.sent = false;
+  return failure;
+}
+
+function validateBeforeSend(beforeSend) {
+  if (beforeSend !== undefined && typeof beforeSend !== "function") throw beforeWriteError(new NativeRelayError("Relay beforeSend must be a function", "RELAY_BAD_REQUEST"));
+}
+
 export function desktopTasksConfigured(env = process.env) {
   return env.CODEX_BRIDGE_DESKTOP_TASKS !== undefined
     ? env.CODEX_BRIDGE_DESKTOP_TASKS === "1"
@@ -409,11 +433,14 @@ export async function resolveNativeToolsPipePath({
 }
 
 export class NativeToolsClient {
-  constructor({ env = process.env, socketPath = env.CODEX_APP_TOOLS_PIPE_PATH, timeoutMs = DEFAULT_TIMEOUT_MS, resolveSocketPath = () => resolveNativeToolsPipePath({ env }) } = {}) {
+  constructor({ env = process.env, socketPath = env.CODEX_APP_TOOLS_PIPE_PATH, timeoutMs = DEFAULT_TIMEOUT_MS, resolveSocketPath = () => resolveNativeToolsPipePath({ env }), assertAccount = assertAccountIdentity } = {}) {
     this.env = env;
     this.socketPath = socketPath;
+    this.explicitSocketPath = socketPath || null;
+    this.hasDiscoveredSocket = false;
     this.timeoutMs = timeoutMs;
     this.resolveSocketPath = resolveSocketPath;
+    this.assertAccount = assertAccount;
     this.socket = null;
     this.connectingSocket = null;
     this.connecting = null;
@@ -432,6 +459,7 @@ export class NativeToolsClient {
         throw new NativeRelayError("Native tools client closed while discovering the Desktop pipe", "NATIVE_PIPE_UNAVAILABLE");
       }
       this.socketPath = socketPath;
+      if (socketPath && !this.explicitSocketPath) this.hasDiscoveredSocket = true;
       if (!this.socketPath) {
         throw new NativeRelayError("CODEX_APP_TOOLS_PIPE_PATH is missing from the environment and parent Desktop app-server configuration; launch the companion from Codex Desktop", "NATIVE_PIPE_UNAVAILABLE");
       }
@@ -440,14 +468,17 @@ export class NativeToolsClient {
       this.connectingSocket = socket;
       let buffer = Buffer.alloc(0);
       let connected = false;
+      let failed = false;
       const timer = globalThis.setTimeout(() => {
-        reject(new NativeRelayError("Timed out connecting to the Codex Desktop native tools pipe", "NATIVE_PIPE_UNAVAILABLE"));
-        socket.destroy();
+        fail(new NativeRelayError("Timed out connecting to the Codex Desktop native tools pipe", "NATIVE_PIPE_UNAVAILABLE"));
       }, this.timeoutMs);
       const fail = (err) => {
+        if (failed) return;
+        failed = true;
         globalThis.clearTimeout(timer);
         if (!connected) reject(err);
         if (this.socket === socket) this.socket = null;
+        if (!this.explicitSocketPath && this.connectionGeneration === generation) this.socketPath = null;
         for (const pending of this.pending.values()) {
           if (pending.socket === socket) pending.reject(err);
         }
@@ -503,15 +534,17 @@ export class NativeToolsClient {
     }
   }
 
-  async dispatch(args) {
-    return this.#request(nativeDispatchParams(args));
+  async dispatch(args, options) {
+    return this.#request(nativeDispatchParams(args), options);
   }
 
-  async dispatchDesktop(args) {
-    return this.#request(nativeDesktopOperationParams(args));
+  async dispatchDesktop(args, options) {
+    return this.#request(nativeDesktopOperationParams(args), options);
   }
 
-  async #request(params) {
+  async #request(params, { beforeSend, accountContext } = {}) {
+    validateBeforeSend(beforeSend);
+    const accounts = relayAccountContext(accountContext);
     const id = this.nextId++;
     const payload = Buffer.from(JSON.stringify({
       jsonrpc: "2.0",
@@ -522,31 +555,50 @@ export class NativeToolsClient {
     if (payload.length > MAX_FRAME_BYTES) {
       throw new NativeRelayError("Native dispatch exceeds the frame limit", "RELAY_MESSAGE_TOO_LARGE");
     }
-    await this.connect();
+    try {
+      await this.connect();
+    } catch (error) {
+      throw beforeWriteError(error);
+    }
     const header = Buffer.alloc(4);
     header.writeUInt32LE(payload.length);
     return new Promise((resolve, reject) => {
+      const socket = this.socket;
+      let dispatched = false;
       const finish = (fn, value) => {
         if (!this.pending.delete(id)) return;
         globalThis.clearTimeout(timer);
         fn(value);
       };
       const timer = globalThis.setTimeout(() => {
-        finish(reject, new NativeRelayError("Codex Desktop native dispatch timed out; delivery may have occurred", "NATIVE_DELIVERY_UNCONFIRMED"));
+        finish(reject, dispatched
+          ? new NativeRelayError("Codex Desktop native dispatch timed out; delivery may have occurred", "NATIVE_DELIVERY_UNCONFIRMED")
+          : beforeWriteError(new NativeRelayError("Codex Desktop native send deadline elapsed before dispatch", "NATIVE_PIPE_UNAVAILABLE")));
       }, this.timeoutMs);
       this.pending.set(id, {
-        socket: this.socket,
+        socket,
         resolve: (value) => finish(resolve, value),
-        reject: (err) => finish(reject, err),
+        reject: (err) => finish(reject, dispatched ? err : beforeWriteError(err)),
       });
-      try {
-        if (!this.socket || this.socket.destroyed) throw new Error("native tools pipe is closed");
-        this.socket.write(Buffer.concat([header, payload]), (err) => {
-          if (err) finish(reject, new NativeRelayError(`Native dispatch write failed: ${err.message}`, "NATIVE_DELIVERY_UNCONFIRMED"));
-        });
-      } catch (err) {
-        finish(reject, new NativeRelayError(`Native dispatch write failed: ${err.message}`, "NATIVE_DELIVERY_UNCONFIRMED"));
-      }
+      void (async () => {
+        try {
+          const checked = beforeSend?.();
+          if (checked && typeof checked.then === "function") await checked;
+          if (!this.pending.has(id)) return;
+          if (accounts) {
+            const verified = this.assertAccount(accounts);
+            if (verified && typeof verified.then === "function") await verified;
+          }
+          if (!this.pending.has(id)) return;
+          if (!socket || socket.destroyed || this.socket !== socket) throw new NativeRelayError("Native tools pipe closed before dispatch", "NATIVE_PIPE_UNAVAILABLE");
+          dispatched = true;
+          socket.write(Buffer.concat([header, payload]), (err) => {
+            if (err) finish(reject, new NativeRelayError(`Native dispatch write failed: ${err.message}`, "NATIVE_DELIVERY_UNCONFIRMED"));
+          });
+        } catch (err) {
+          finish(reject, dispatched ? new NativeRelayError(`Native dispatch write failed: ${err.message}`, "NATIVE_DELIVERY_UNCONFIRMED") : beforeWriteError(err));
+        }
+      })();
     });
   }
 
@@ -554,6 +606,7 @@ export class NativeToolsClient {
     this.connectionGeneration++;
     const socket = this.socket;
     this.socket = null;
+    if (!this.explicitSocketPath) this.socketPath = null;
     for (const pending of this.pending.values()) {
       pending.reject(new NativeRelayError("Native tools client closed before confirming delivery", "NATIVE_DELIVERY_UNCONFIRMED"));
     }
@@ -603,9 +656,10 @@ export function nativeRelayStatus(env = process.env) {
  * socket cannot go stale while Codex Desktop restarts underneath it.
  */
 export class NativeDesktopRelay {
-  constructor({ env = process.env, socketPath = null, timeoutMs = DEFAULT_TIMEOUT_MS, log = () => {} } = {}) {
+  constructor({ env = process.env, socketPath = null, accountSocketPath = null, timeoutMs = DEFAULT_TIMEOUT_MS, log = () => {} } = {}) {
     this.env = env;
     this.explicitSocketPath = socketPath;
+    this.accountSocketPath = accountSocketPath ?? socketPath ?? accountRelaySocketPath(env);
     this.timeoutMs = timeoutMs;
     this.log = log;
   }
@@ -614,27 +668,31 @@ export class NativeDesktopRelay {
     return this.explicitSocketPath ?? relaySocketPath(this.env);
   }
 
-  status() {
-    if (!this.explicitSocketPath) return nativeRelayStatus(this.env);
-    const status = nativeRelayStatus({ ...this.env, CODEX_NATIVE_RELAY_SOCKET: this.explicitSocketPath });
-    return { ...status, socketPath: this.explicitSocketPath };
+  status({ accountContext } = {}) {
+    const socketPath = accountContext ? this.accountSocketPath : this.explicitSocketPath;
+    if (!socketPath) return nativeRelayStatus(this.env);
+    const status = nativeRelayStatus({ ...this.env, CODEX_NATIVE_RELAY_SOCKET: socketPath });
+    return { ...status, socketPath };
   }
 
   get available() {
     return this.status().enabled;
   }
 
-  async sendMessage(targetThreadId, message, { timeoutMs = this.timeoutMs } = {}) {
-    const request = { v: RELAY_PROTOCOL_VERSION, targetThreadId, message };
-    return this.#request(request, timeoutMs);
+  async sendMessage(targetThreadId, message, { timeoutMs = this.timeoutMs, beforeSend, accountContext } = {}) {
+    const accounts = relayAccountContext(accountContext);
+    const request = { v: accounts ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION, targetThreadId, message, ...(accounts ? { accountContext: accounts } : {}) };
+    return this.#request(request, timeoutMs, beforeSend);
   }
 
-  async requestDesktop(operation, args, { timeoutMs = this.timeoutMs } = {}) {
+  async requestDesktop(operation, args, { timeoutMs = this.timeoutMs, beforeSend, accountContext } = {}) {
     validateDesktopOperation(operation, args);
-    return this.#request({ v: RELAY_PROTOCOL_VERSION, operation, arguments: args }, timeoutMs);
+    const accounts = relayAccountContext(accountContext);
+    return this.#request({ v: accounts ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION, operation, arguments: args, ...(accounts ? { accountContext: accounts } : {}) }, timeoutMs, beforeSend);
   }
 
-  async #request(request, timeoutMs) {
+  async #request(request, timeoutMs, beforeSend) {
+    validateBeforeSend(beforeSend);
     const line = `${JSON.stringify(request)}\n`;
     if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
       throw new NativeRelayError(
@@ -643,20 +701,21 @@ export class NativeDesktopRelay {
       );
     }
 
-    const response = await this.#roundTrip(line, timeoutMs);
-    if (response?.ok === true && response.v === RELAY_PROTOCOL_VERSION) {
+    const response = await this.#roundTrip(line, timeoutMs, beforeSend, request.accountContext ? this.accountSocketPath : this.socketPath);
+    if (response?.ok === true && response.v === request.v) {
       if (request.operation && response.operation !== request.operation) throw new NativeRelayError("The relay answered a different Desktop operation; do not retry this request", "RELAY_BAD_RESPONSE", { reachedCompanion: true });
       return response;
     }
-    throw new NativeRelayError(
+    const error = new NativeRelayError(
       response?.error?.message ?? "the Codex Desktop relay refused the message",
       response?.error?.code ?? "NATIVE_DISPATCH_FAILED",
-      { reachedCompanion: true },
+      { reachedCompanion: response?.error?.sent !== false },
     );
+    if (response?.error?.sent === false) error.sent = false;
+    throw error;
   }
 
-  #roundTrip(line, timeoutMs) {
-    const socketPath = this.socketPath;
+  #roundTrip(line, timeoutMs, beforeSend, socketPath) {
     return new Promise((resolve, reject) => {
       let buffer = Buffer.alloc(0);
       let settled = false;
@@ -675,18 +734,29 @@ export class NativeDesktopRelay {
         () =>
           finish(
             reject,
-            new NativeRelayError(
+            dispatched ? new NativeRelayError(
               `The Codex Desktop relay did not answer within ${timeoutMs}ms`,
               "RELAY_TIMEOUT",
-              { reachedCompanion: dispatched },
-            ),
+              { reachedCompanion: true },
+            ) : beforeWriteError(new NativeRelayError("The Codex Desktop relay send deadline elapsed before dispatch", "RELAY_UNREACHABLE")),
           ),
         timeoutMs,
       );
 
       socket.on("connect", () => {
-        dispatched = true;
-        socket.write(line);
+        if (settled) return;
+        void (async () => {
+          try {
+            const checked = beforeSend?.();
+            if (checked && typeof checked.then === "function") await checked;
+            if (settled) return;
+            if (socket.destroyed) throw new NativeRelayError("The relay socket closed before dispatch", "RELAY_UNREACHABLE");
+            dispatched = true;
+            socket.write(line);
+          } catch (error) {
+            finish(reject, dispatched ? new NativeRelayError(`Relay write failed: ${error.message}`, "RELAY_DELIVERY_UNCONFIRMED", { reachedCompanion: true }) : beforeWriteError(error));
+          }
+        })();
       });
       socket.on("data", (chunk) => {
         buffer = Buffer.concat([buffer, chunk]);
@@ -717,17 +787,19 @@ export class NativeDesktopRelay {
       socket.on("error", (err) =>
         finish(
           reject,
-          new NativeRelayError(`Codex Desktop relay connection failed at ${socketPath}: ${err.message}`, dispatched ? "RELAY_DELIVERY_UNCONFIRMED" : "RELAY_UNREACHABLE", { reachedCompanion: dispatched }),
+          dispatched
+            ? new NativeRelayError(`Codex Desktop relay connection failed at ${socketPath}: ${err.message}`, "RELAY_DELIVERY_UNCONFIRMED", { reachedCompanion: true })
+            : beforeWriteError(new NativeRelayError(`Codex Desktop relay connection failed at ${socketPath}: ${err.message}`, "RELAY_UNREACHABLE")),
         ),
       );
       socket.on("close", () =>
         finish(
           reject,
-          new NativeRelayError(
+          dispatched ? new NativeRelayError(
             `The Codex Desktop relay at ${socketPath} closed before answering`,
-            dispatched ? "RELAY_DELIVERY_UNCONFIRMED" : "RELAY_UNREACHABLE",
-            { reachedCompanion: dispatched },
-          ),
+            "RELAY_DELIVERY_UNCONFIRMED",
+            { reachedCompanion: true },
+          ) : beforeWriteError(new NativeRelayError(`The Codex Desktop relay at ${socketPath} closed before dispatch`, "RELAY_UNREACHABLE")),
         ),
       );
     });

package/src/peer-protocol.mjs

@@ -6,6 +6,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { homeDir, IS_WINDOWS } from "./platform.mjs";
+import { cloneReloadState } from "./reload-control.mjs";
 
 const SOCKET_DIR = "/tmp/cc-socks";
 
@@ -366,6 +367,10 @@ export class PeerEndpoint {
     this.sentMessages = new Map();
     this.pendingMessages = new Map();
     this.responsePoll = null;
+    this.connections = new Set();
+    this.activityRevision = 0;
+    this.reloadPaused = false;
+    this.processHandlersRegistered = false;
   }
 
   /**
@@ -396,6 +401,7 @@ export class PeerEndpoint {
   }
 
   async start() {
+    if (this.reloadPaused) throw new Error("The peer endpoint is quiesced for reload");
     if (this.started) return;
     this.#sweepDeadBridges();
     const procStart = readProcessStart(this.pid);
@@ -432,24 +438,33 @@ export class PeerEndpoint {
     fs.writeFileSync(this.registryPath, JSON.stringify(this.registry), { mode: 0o600 });
     fs.writeFileSync(this.keyPath, JSON.stringify({ peerToken, ...processIdentity }), { mode: 0o600 });
 
-    for (const signal of ["SIGINT", "SIGTERM"]) {
-      process.on(signal, () => {
-        this.stop();
-        process.exit(0);
-      });
+    if (!this.processHandlersRegistered) {
+      for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, () => {
+          this.stop();
+          process.exit(0);
+        });
+      }
+      process.on("exit", () => this.stop());
+      this.processHandlersRegistered = true;
     }
-    process.on("exit", () => this.stop());
 
     this.started = true;
     this.log(`peer "${this.name}" listening on ${this.socketPath}`);
   }
 
   #handleConnection(socket) {
+    this.activityRevision += 1;
+    this.connections.add(socket);
+    socket.once("close", () => this.connections.delete(socket));
+    if (this.reloadPaused) { socket.destroy(); return; }
     let buffer = "";
     let authenticated = false;
     let firstLine = true;
     socket.setEncoding("utf8");
     socket.on("data", (chunk) => {
+      this.activityRevision += 1;
+      if (this.reloadPaused) { socket.destroy(); return; }
       buffer += chunk;
       if (buffer.length > 1048576) { socket.destroy(); return; }
       let index;
@@ -502,6 +517,7 @@ export class PeerEndpoint {
   }
 
   #receiveMessage(message) {
+    this.activityRevision += 1;
     const record = { ...message, receivedAt: Date.now(), sequence: ++this.messageSequence };
     this.inbox.push(record);
     const key = record.inReplyTo ?? [...this.pendingMessages].find(([, entry]) => entry.targetSocket === record.fromSocket)?.[0];
@@ -512,11 +528,12 @@ export class PeerEndpoint {
       if (sent) {
         record.inReplyTo = key;
         record.replyThreadId = sent.replyThreadId ?? null;
+        record.accountContext = sent.accountContext ?? null;
         sent.reply = record;
       }
       this.#removePendingReply(record.fromSocket, key);
     }
-    this.log(`inbox <- ${record.fromSocket ?? "?"}: ${record.text.slice(0, 120)}`);
+    this.log(`inbox <- ${record.fromSocket ?? "?"}: ${record.text.length} characters`);
     for (const listener of [...this.listeners]) {
       try { listener(record); }
       catch (err) { this.log(`peer listener error: ${err.message}`); }
@@ -564,6 +581,7 @@ export class PeerEndpoint {
   }
 
   async send(targetSocket, text, { priority = "next", msgId, permissionMode = this.permissionMode, beforeSend } = {}) {
+    if (this.reloadPaused) throw new Error("The peer endpoint is quiesced; no message was sent");
     const frame = buildFrame({ text, fromSocket: this.socketPath, priority, permissionMode });
     if (msgId) frame.uuid = frame.msg_id = msgId;
     const token = readPeerToken(targetSocket);
@@ -573,6 +591,8 @@ export class PeerEndpoint {
       try {
         await new Promise((resolve, reject) => {
           const client = net.connect({ path: targetSocket });
+          this.connections.add(client);
+          client.once("close", () => this.connections.delete(client));
           let connected = false;
           let writeStarted = false;
           let settled = false;
@@ -626,7 +646,7 @@ export class PeerEndpoint {
     return frame.msg_id;
   }
 
-  async sendAndWait(targetSocket, text, { timeoutMs = 120000, priority = "next", transcriptSession, beforeSend, permissionMode = this.permissionMode, replyThreadId, senderReview, senderApprovalPolicy, recipient } = {}) {
+  async sendAndWait(targetSocket, text, { timeoutMs = 120000, priority = "next", transcriptSession, beforeSend, permissionMode = this.permissionMode, replyThreadId, senderReview, senderApprovalPolicy, recipient, accountContext } = {}) {
     const previous = this.requestQueues.get(targetSocket) ?? Promise.resolve();
     const pending = previous.catch(() => {}).then(async () => {
       await beforeSend?.();
@@ -644,7 +664,7 @@ export class PeerEndpoint {
       this.unconfirmedReplies.set(targetSocket, unconfirmed + 1);
       let msgId = crypto.randomUUID();
       this.pendingMessages.set(msgId, { targetSocket, transcriptSession });
-      this.sentMessages.set(msgId, { targetSocket, transcriptSession, sentAt: since, replyThreadId, permissionMode, senderApprovalPolicy, ...(senderReview ? { senderReview: { ...senderReview } } : {}), ...(recipient ? { recipient: { ...recipient } } : {}) });
+      this.sentMessages.set(msgId, { targetSocket, transcriptSession, sentAt: since, replyThreadId, permissionMode, senderApprovalPolicy, ...(senderReview ? { senderReview: { ...senderReview } } : {}), ...(recipient ? { recipient: { ...recipient } } : {}), ...(accountContext ? { accountContext: Object.freeze({ ...accountContext }) } : {}) });
       if (transcriptSession && !this.responsePoll) {
         this.responsePoll = globalThis.setInterval(() => this.#refreshTranscriptReplies(), 250);
         this.responsePoll.unref();
@@ -726,9 +746,15 @@ export class PeerEndpoint {
     });
   }
 
-  drainInbox(limit = 20) {
+  drainInbox(limit = 20, accepts = () => true) {
     if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("Inbox limit must be a positive integer");
-    return this.inbox.splice(0, limit);
+    const selected = [];
+    this.inbox = this.inbox.filter((record) => {
+      if (selected.length >= limit || !accepts(record)) return true;
+      selected.push(record);
+      return false;
+    });
+    return selected;
   }
 
   readDelivery(msgId) {
@@ -751,11 +777,91 @@ export class PeerEndpoint {
       ...(sent.senderReview ? { senderReview: { ...sent.senderReview } } : {}),
       ...(sent.recipient ? { recipientPermissionMode: sent.recipient.permissionMode ?? null, recipientPermissionClass: sent.recipient.permissionClass ?? null, recipientInboundPolicy: sent.recipient.inboundPolicy ?? null } : {}),
       replyThreadId: sent.replyThreadId ?? null,
+      ...(sent.accountContext ? { accountContext: { ...sent.accountContext } } : {}),
       pending: this.pendingMessages.has(msgId),
       ...(sent.reply ? { reply: sent.reply.text, source: sent.reply.source ?? "peer", ...(sent.reply.absorbed ? { replyAbsorbed: true } : {}), ...(sent.reply.forwardingError ? { forwardingError: { ...sent.reply.forwardingError } } : {}) } : {}),
     };
   }
 
+  reloadReason() {
+    if (this.connections.size) return "Peer socket connections are still open";
+    if (this.requestQueues.size || this.pendingMessages.size || this.unconfirmedReplies.size) return "Claude messages still have pending or unconfirmed delivery";
+    for (const [id, sent] of this.sentMessages) {
+      if (!sent.reply && !sent.failed && !["refused", "denied", "expired", "dropped"].includes(this.deliveryReceipts.get(id)?.status)) {
+        return "A Claude delivery outcome remains unconfirmed";
+      }
+    }
+    return null;
+  }
+
+  async quiesce() {
+    const reason = this.reloadReason();
+    if (reason) throw new Error(reason);
+    const revision = this.activityRevision;
+    this.reloadPaused = true;
+    globalThis.clearInterval(this.responsePoll);
+    this.responsePoll = null;
+    if (this.server?.listening) {
+      await new Promise((resolve, reject) => this.server.close((error) => error ? reject(error) : resolve()));
+    }
+    this.started = false;
+    this.#removeRegistration();
+    if (revision !== this.activityRevision || this.reloadReason()) throw new Error("Peer activity raced with reload; the endpoint remains quiesced");
+  }
+
+  async resume() {
+    this.reloadPaused = false;
+    await this.start();
+  }
+
+  exportReloadState() {
+    const reason = this.reloadReason();
+    if (reason || this.started && !this.reloadPaused) throw new Error(reason ?? "Quiesce the peer endpoint before exporting state");
+    return cloneReloadState({ name: this.name, messageSequence: this.messageSequence, inbox: this.inbox,
+      sentMessages: [...this.sentMessages], deliveryReceipts: [...this.deliveryReceipts] });
+  }
+
+  restoreReloadState(input) {
+    if (this.started || this.connections.size || this.sentMessages.size || this.inbox.length) throw new Error("Peer reload state requires an empty dormant endpoint");
+    const state = cloneReloadState(input);
+    if (!state || typeof state.name !== "string" || !state.name || !Number.isSafeInteger(state.messageSequence) || state.messageSequence < 0
+      || !Array.isArray(state.inbox) || !Array.isArray(state.sentMessages) || !Array.isArray(state.deliveryReceipts)) throw new Error("Invalid peer reload state");
+    const restoreMap = (entries) => {
+      const restored = new Map();
+      for (const pair of entries) {
+        if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string" || !pair[0] || restored.has(pair[0])
+          || !pair[1] || typeof pair[1] !== "object" || Array.isArray(pair[1])) throw new Error("Invalid peer reload record");
+        restored.set(pair[0], pair[1]);
+      }
+      return restored;
+    };
+    const sentMessages = restoreMap(state.sentMessages);
+    const deliveryReceipts = restoreMap(state.deliveryReceipts);
+    for (const record of state.inbox) {
+      if (!record || typeof record.text !== "string" || !Number.isSafeInteger(record.sequence) || record.sequence < 1
+        || record.sequence > state.messageSequence || !Number.isFinite(record.receivedAt)) throw new Error("Invalid inbox reload record");
+    }
+    for (const [id, sent] of sentMessages) {
+      if (typeof sent.targetSocket !== "string" || !sent.targetSocket || !Number.isFinite(sent.sentAt)
+        || sent.reply && (typeof sent.reply.text !== "string" || sent.reply.inReplyTo !== id)
+        || !sent.reply && !sent.failed && !["refused", "denied", "expired", "dropped"].includes(deliveryReceipts.get(id)?.status)) {
+        throw new Error("Invalid or unconfirmed Claude delivery reload record");
+      }
+    }
+    this.name = state.name;
+    this.messageSequence = state.messageSequence;
+    this.inbox = state.inbox;
+    this.sentMessages = sentMessages;
+    this.deliveryReceipts = deliveryReceipts;
+  }
+
+  #removeRegistration() {
+    for (const file of [this.socketPath, this.registryPath, this.keyPath]) {
+      if (!file) continue;
+      try { fs.rmSync(file, { force: true }); } catch {}
+    }
+  }
+
   stop() {
     globalThis.clearInterval(this.responsePoll);
     this.responsePoll = null;
@@ -763,12 +869,9 @@ export class PeerEndpoint {
     try {
       this.server?.close();
     } catch {}
-    for (const file of [this.socketPath, this.registryPath, this.keyPath]) {
-      if (!file) continue;
-      try {
-        fs.rmSync(file, { force: true });
-      } catch {}
-    }
+    for (const socket of this.connections) socket.destroy();
+    this.connections.clear();
+    this.#removeRegistration();
     this.started = false;
   }
 }

package/src/platform.mjs

@@ -61,7 +61,10 @@ const FOREIGN_ROOT_PATTERNS = [
  * directory layout out of the source.
  */
 function bridgeParentDir() {
-  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const sourceRoot = process.env.CODEX_BRIDGE_WORKER === "1" && process.env.CODEX_BRIDGE_SOURCE_ROOT;
+  const repoRoot = sourceRoot && path.isAbsolute(sourceRoot)
+    ? sourceRoot
+    : path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
   return path.dirname(repoRoot);
 }