@minhspark/codex-mcp-bridge 1.13.9 → 1.15.1

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

package/src/release-snapshot.mjs

@@ -0,0 +1,198 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function digestFiles(root, files) {
+  const hash = createHash("sha256");
+  for (const file of files) hash.update(file).update("\0").update(fs.readFileSync(path.join(root, file))).update("\0");
+  return hash.digest("hex");
+}
+
+const DIGEST_FIELDS = ["dev", "ino", "size", "mtimeNs", "ctimeNs"];
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+
+function safeRelativePath(file) {
+  return typeof file === "string" && file.length > 0 && !file.includes("\0")
+    && !path.posix.isAbsolute(file) && !path.win32.parse(file).root
+    && path.normalize(file) === file && !file.split(/[\\/]/).some((part) => !part || part === "." || part === "..");
+}
+
+function digestMetadata(cache) {
+  const directories = new Map();
+  const dirty = new Set();
+  const metadataPath = (directory) => path.join(cache, `.digests-${createHash("sha256").update(directory).digest("hex")}.json`);
+  const signature = (stat) => Object.fromEntries(DIGEST_FIELDS.map((field) => [field, String(stat[field])]));
+  const matches = (left, right) => left && DIGEST_FIELDS.every((field) => left[field] === right[field]);
+  const load = (directory) => {
+    dirty.add(directory);
+    let descriptor;
+    try {
+      const file = metadataPath(directory);
+      const info = fs.lstatSync(file, { bigint: true });
+      if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1n || info.size > 32n * 1024n * 1024n) return new Map();
+      descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+      const opened = fs.fstatSync(descriptor, { bigint: true });
+      if (!opened.isFile() || opened.nlink !== 1n || !matches(signature(info), signature(opened))) return new Map();
+      const metadata = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+      if (metadata?.schema !== 1 || metadata.directory !== directory || !metadata.files || typeof metadata.files !== "object" || Array.isArray(metadata.files)) return new Map();
+      const entries = Object.entries(metadata.files);
+      if (entries.some(([file, record]) => !safeRelativePath(file) || !record || typeof record !== "object" || Array.isArray(record)
+        || typeof record.hash !== "string" || !DIGEST_PATTERN.test(record.hash)
+        || DIGEST_FIELDS.some((field) => typeof record[field] !== "string" || !/^-?\d+$/.test(record[field])))) return new Map();
+      dirty.delete(directory);
+      return new Map(entries);
+    } catch {
+      return new Map();
+    } finally {
+      if (descriptor !== undefined) fs.closeSync(descriptor);
+    }
+  };
+  return {
+    digest(directory, files) {
+      const previous = directories.get(directory) ?? load(directory);
+      const records = new Map();
+      const hash = createHash("sha256");
+      if (previous.size !== files.length) dirty.add(directory);
+      for (const file of files) {
+        if (!safeRelativePath(file)) throw new Error(`Unsafe release file: ${file}`);
+        const fullPath = path.join(directory, file);
+        const before = fs.statSync(fullPath, { bigint: true });
+        if (!before.isFile()) throw new Error(`Unsupported release file: ${file}`);
+        const current = signature(before);
+        let record = previous.get(file);
+        if (!matches(record, current)) {
+          dirty.add(directory);
+          const contentHash = createHash("sha256").update(fs.readFileSync(fullPath)).digest("hex");
+          const after = fs.statSync(fullPath, { bigint: true });
+          if (!after.isFile() || !matches(current, signature(after))) throw new Error("A release file changed during integrity verification");
+          record = { ...current, hash: contentHash };
+        }
+        records.set(file, record);
+        hash.update(file).update("\0").update(record.hash).update("\0");
+      }
+      directories.set(directory, records);
+      return hash.digest("hex");
+    },
+    relocate(from, to) {
+      if (directories.has(from)) {
+        directories.set(to, directories.get(from));
+        dirty.add(to);
+      }
+      directories.delete(from);
+      dirty.delete(from);
+    },
+    forget(directory) { directories.delete(directory); dirty.delete(directory); },
+    flush() {
+      for (const [directory, records] of directories) {
+        if (!dirty.has(directory)) continue;
+        const file = metadataPath(directory);
+        const temporary = path.join(cache, `.digests-${process.pid}-${randomUUID()}.tmp`);
+        try {
+          try {
+            const info = fs.lstatSync(file);
+            if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) continue;
+          } catch (error) { if (error.code !== "ENOENT") continue; }
+          fs.writeFileSync(temporary, JSON.stringify({ schema: 1, directory, files: Object.fromEntries(records) }), { flag: "wx", mode: 0o600 });
+          fs.renameSync(temporary, file);
+          dirty.delete(directory);
+        } catch {
+        } finally {
+          try { fs.rmSync(temporary, { force: true }); } catch {}
+        }
+      }
+    },
+  };
+}
+
+function inventory(root, prefix = "") {
+  const files = [];
+  for (const entry of fs.readdirSync(path.join(root, prefix), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, "en"))) {
+    if (entry.name === ".bin") continue;
+    const relative = path.join(prefix, entry.name);
+    const stat = entry.isSymbolicLink() ? fs.statSync(path.join(root, relative)) : entry;
+    if (stat.isDirectory()) files.push(...inventory(root, relative));
+    else if (stat.isFile()) files.push(relative);
+    else throw new Error(`Unsupported release file: ${relative}`);
+  }
+  return files;
+}
+
+export function sourceRevision(root) {
+  const files = ["package.json", ...inventory(root, "src")];
+  for (const file of ["package-lock.json", "node_modules/.package-lock.json"]) {
+    if (fs.existsSync(path.join(root, file))) files.push(file);
+  }
+  return digestFiles(root, files);
+}
+
+export function snapshotRoot(env = process.env) {
+  return path.resolve(env.CODEX_BRIDGE_RUNTIME_CACHE ?? path.join(env.CODEX_HOME ?? path.join(os.homedir(), ".codex"), "bridge-runtimes"));
+}
+
+function removeOwned(directory, cache) {
+  const relative = path.relative(cache, directory);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("Refusing to remove an unowned runtime directory");
+  if (fs.existsSync(directory) && fs.lstatSync(directory).isSymbolicLink()) throw new Error("Refusing to remove a linked runtime directory");
+  fs.rmSync(directory, { recursive: true, force: true });
+}
+
+export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRevision = sourceRevision(root) } = {}) {
+  root = fs.realpathSync.native(root);
+  if (fs.existsSync(cache) && fs.lstatSync(cache).isSymbolicLink()) throw new Error("The runtime cache cannot be a symbolic link");
+  const missing = [];
+  let ancestor = path.resolve(cache);
+  while (!fs.existsSync(ancestor)) {
+    missing.unshift(path.basename(ancestor));
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) throw new Error("The runtime cache has no accessible filesystem root");
+    ancestor = parent;
+  }
+  cache = path.join(fs.realpathSync.native(ancestor), ...missing);
+  fs.mkdirSync(cache, { recursive: true, mode: 0o700 });
+  if (fs.lstatSync(cache).isSymbolicLink()) throw new Error("The runtime cache cannot be a symbolic link");
+  cache = fs.realpathSync.native(cache);
+  const metadata = digestMetadata(cache);
+  const dependencies = inventory(root, "node_modules");
+  const dependencyRevision = metadata.digest(root, dependencies);
+  const key = createHash("sha256").update(expectedRevision).update(dependencyRevision).digest("hex");
+  const target = path.join(cache, key);
+  const validate = (directory) => {
+    if (fs.lstatSync(directory).isSymbolicLink()) throw new Error("The release directory cannot be a symbolic link");
+    return sourceRevision(directory) === expectedRevision && metadata.digest(directory, inventory(directory, "node_modules")) === dependencyRevision;
+  };
+  if (fs.existsSync(target)) {
+    if (!validate(target)) throw new Error("An existing immutable runtime failed integrity verification");
+    if (sourceRevision(root) !== expectedRevision) throw new Error("The installation changed during snapshot verification");
+    metadata.flush();
+    return { directory: target, revision: expectedRevision, key };
+  }
+  const temporary = path.join(cache, `.preparing-${process.pid}-${randomUUID()}`);
+  try {
+    fs.mkdirSync(temporary, { mode: 0o700 });
+    const files = ["package.json", ...inventory(root, "src"), ...dependencies];
+    if (fs.existsSync(path.join(root, "package-lock.json"))) files.push("package-lock.json");
+    const directories = new Set(["src", "node_modules", ...files.map((file) => path.dirname(file))]);
+    for (const directory of directories) fs.mkdirSync(path.join(temporary, directory), { recursive: true, mode: 0o700 });
+    for (const file of files) {
+      fs.copyFileSync(path.join(root, file), path.join(temporary, file), fs.constants.COPYFILE_FICLONE);
+    }
+    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, inventory(root, "node_modules")) !== dependencyRevision || !validate(temporary)) {
+      throw new Error("The installation changed while its immutable runtime was being prepared");
+    }
+    try {
+      fs.renameSync(temporary, target);
+      metadata.relocate(temporary, target);
+    }
+    catch (error) {
+      if (!fs.existsSync(target) || !validate(target)) throw error;
+      removeOwned(temporary, cache);
+      metadata.forget(temporary);
+    }
+    metadata.flush();
+    return { directory: target, revision: expectedRevision, key };
+  } catch (error) {
+    removeOwned(temporary, cache);
+    throw error;
+  }
+}

package/src/reload-control.mjs

@@ -0,0 +1,102 @@
+export function assertRoutingReload(previous, next) {
+  if (typeof previous !== "boolean" || typeof next !== "boolean" || previous && !next) {
+    throw new Error("Invalid routing reload or Desktop-to-app-server downgrade; reconnect explicitly to change to legacy mode");
+  }
+}
+
+export function cloneReloadState(value) {
+  const encoded = JSON.stringify(value);
+  if (typeof encoded !== "string" || Buffer.byteLength(encoded) > 16 * 1024 * 1024) {
+    throw new Error("Reload state is missing or exceeds its transfer limit");
+  }
+  return JSON.parse(encoded);
+}
+
+export function clientReloadReason(client) {
+  if (!client) return null;
+  for (const field of ["pending", "threadOperations", "attachingThreads", "activeTurns", "threadListeners"]) {
+    if (client[field]?.size) return `The app-server still has ${field}`;
+  }
+  if (client.connecting) return "The app-server connection is still being established";
+  return null;
+}
+
+export function createReloadControl({ entry, inspect = () => null, quiesce = () => {}, exportState = () => ({}), restore = () => {}, activate = () => {}, resume = activate, env = process.env, channel = process } = {}) {
+  if (!["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"].includes(entry)) throw new Error("Invalid reload entry point");
+  const enabled = env.CODEX_BRIDGE_WORKER === "1" && typeof channel.send === "function";
+  let phase = enabled && env.CODEX_BRIDGE_STAGED === "1" ? "staged" : "active";
+  let active = 0;
+  let deferred = null;
+  let listening = false;
+  let commands = Promise.resolve();
+
+  const status = () => {
+    const reason = active ? "MCP tool calls are still active" : deferred ?? inspect();
+    return { reloadable: phase === "active" && !reason, reason: reason ?? (phase === "active" ? null : `The worker is ${phase}`), schema: 1, phase };
+  };
+
+  const control = async (action, data) => {
+    if (action === "inspect") return status();
+    if (action === "quiesce") {
+      const current = status();
+      if (!current.reloadable) throw new Error(current.reason);
+      phase = "quiescing";
+      try {
+        await quiesce();
+        const reason = deferred ?? inspect();
+        if (active || reason) throw new Error(reason ?? "A tool call raced with quiescence");
+        const state = cloneReloadState({ schema: 1, entry, payload: exportState() });
+        phase = "quiesced";
+        return { state };
+      } catch (error) {
+        phase = "quiesced";
+        throw error;
+      }
+    }
+    if (action === "restore") {
+      if (phase !== "staged") throw new Error("Reload state can only be restored into a staged worker");
+      const state = cloneReloadState(data);
+      if (!state || state.schema !== 1 || state.entry !== entry || !state.payload || typeof state.payload !== "object" || Array.isArray(state.payload)) {
+        throw new Error("Reload state schema or entry point does not match this worker");
+      }
+      await restore(state.payload);
+      return { restored: true, schema: 1 };
+    }
+    if (action === "activate" || action === "resume") {
+      if (phase === "active") return { active: true, schema: 1 };
+      if (action === "activate" && phase !== "staged" || action === "resume" && phase !== "quiesced") {
+        throw new Error(`Cannot ${action} a ${phase} worker`);
+      }
+      await (action === "activate" ? activate() : resume());
+      phase = "active";
+      return { active: true, schema: 1 };
+    }
+    throw new Error("Unknown bridge control action");
+  };
+
+  return {
+    get staged() { return phase === "staged"; },
+    inspect: status,
+    defer(reason) { deferred ??= String(reason); },
+    async run(handler) {
+      if (phase !== "active") throw new Error(`Bridge worker is ${phase}; no tool operation was started`);
+      active += 1;
+      try { return await handler(); }
+      finally { active -= 1; }
+    },
+    control,
+    listen() {
+      if (!enabled || listening) return;
+      listening = true;
+      channel.on("message", (message) => {
+        if (message?.type !== "bridge:control" || !["string", "number"].includes(typeof message.id)) return;
+        commands = commands.catch(() => {}).then(async () => {
+          let response;
+          try { response = { result: await control(message.action, message.data) }; }
+          catch (error) { response = { error: error?.message ?? String(error) }; }
+          if (channel.connected !== false) channel.send({ type: "bridge:control-result", id: message.id, ...response });
+        });
+      });
+    },
+  };
+}

package/src/reply-forwarder.mjs

@@ -1,3 +1,5 @@
+import { cloneReloadState } from "./reload-control.mjs";
+
 const KNOWN_UNSENT_CODES = new Set([
   "RELAY_UNREACHABLE",
   "RELAY_MESSAGE_TOO_LARGE",
@@ -97,6 +99,47 @@ export class ReplyForwarder {
     return { ...counts, attempts: this.attempts, maxPerSession: this.maxPerSession, closed: this.closed };
   }
 
+  reloadReason() {
+    if (this.active || this.queue.length || this.timer !== null) return "Reply forwarding is still active or queued";
+    if ([...this.records.values()].some(({ receipt }) => ["queued", "sending", "unknown"].includes(receipt.status))) {
+      return "A reply forwarding outcome remains unconfirmed";
+    }
+    return null;
+  }
+
+  exportReloadState() {
+    const reason = this.reloadReason();
+    if (reason) throw new Error(reason);
+    return cloneReloadState({ records: [...this.records], attempts: this.attempts, lastAt: this.lastAt, closed: this.closed,
+      maxPerSession: this.maxPerSession, minIntervalMs: this.minIntervalMs });
+  }
+
+  restoreReloadState(input) {
+    if (this.records.size || this.active || this.queue.length || this.timer !== null) throw new Error("Reply forwarding state is not empty");
+    const state = cloneReloadState(input);
+    if (!state || !Array.isArray(state.records) || !Number.isSafeInteger(state.attempts) || state.attempts < 0
+      || !Number.isSafeInteger(state.maxPerSession) || state.maxPerSession < 1 || state.attempts > state.maxPerSession
+      || !Number.isFinite(state.minIntervalMs) || state.minIntervalMs < 0 || typeof state.closed !== "boolean"
+      || state.lastAt !== null && (!Number.isFinite(state.lastAt) || state.lastAt < 0)) throw new Error("Invalid reply forwarding reload state");
+    const records = new Map();
+    for (const pair of state.records) {
+      if (!Array.isArray(pair) || pair.length !== 2) throw new Error("Invalid reply forwarding record");
+      const [id, entry] = pair;
+      if (!validIdentity(id) || records.has(id) || !entry?.record || !entry.receipt
+        || entry.receipt.msgId !== id || !validIdentity(entry.receipt.threadId)
+        || entry.record.replyThreadId !== entry.receipt.threadId || (entry.record.inReplyTo ?? entry.record.msgId) !== id
+        || typeof entry.record.text !== "string" || !entry.record.text.trim()
+        || !["forwarded", "failed", "blocked"].includes(entry.receipt.status)) throw new Error("Invalid or unconfirmed reply forwarding record");
+      records.set(id, { record: Object.freeze(entry.record), receipt: entry.receipt });
+    }
+    this.records = records;
+    this.attempts = state.attempts;
+    this.lastAt = state.lastAt;
+    this.closed = state.closed;
+    this.maxPerSession = Math.min(this.maxPerSession, state.maxPerSession);
+    this.minIntervalMs = Math.max(this.minIntervalMs, state.minIntervalMs);
+  }
+
   close() {
     this.closed = true;
     if (this.timer !== null) this.cancel(this.timer);