@minhspark/codex-mcp-bridge 1.19.1 → 1.19.2

package/CHANGELOG.md

@@ -4,6 +4,13 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.19.2] - 2026-09-29
+
+### Fixed
+
+- Start both bridges from project-local npm installations. When npm hoists the bridge's dependencies into the project's `node_modules`, the package has no `node_modules` of its own, and preparing the immutable runtime failed with `ENOENT` (`scandir …node_modules`) since 1.15.0; only global installs, which keep a nested `node_modules`, started. The runtime now copies the dependency tree Node resolves from the package (hoisted, nested, scoped, aliased, linked and peer dependencies) and nothing else from the project, so it stays isolated from later installation changes. Its revision also covers the project's npm lock, so an `npm install` that changes those dependencies reloads the bridge.
+- Stop the Codex bridge cleanly when its MCP client disconnects. The bridge ends the Windows PowerShell caller checks it started and waits for them to close, and the supervisor gives its worker up to 6 seconds to exit before stopping it. Before, the supervisor stopped the worker after 1 second without waiting, which left those checks running with the bridge's working directory in use. On Windows, deleting that directory right after a test closed its bridge then failed with `EPERM`; the tests no longer retry that deletion.
+
 ## [1.19.1] - 2026-09-29
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.19.1",
+  "version": "1.19.2",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",

package/scripts/install-native-relay.mjs

@@ -22,7 +22,7 @@ import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.1";
+const VERSION = "1.19.2";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/src/claude-bridge.mjs

@@ -26,7 +26,7 @@ import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs"
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.1";
+const VERSION = "1.19.2";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/claude-sender-context.mjs

@@ -7,6 +7,13 @@ import { readClaudeDesktopContext } from "./claude-desktop-context.mjs";
 const execute = promisify(execFile);
 const MAX_ANCESTORS = 8;
 const INSPECTION_OUTPUT_LIMIT = 16384;
+const activeInspectors = new Set();
+let inspectorsStopping = false;
+
+export async function stopProcessInspectors() {
+  inspectorsStopping = true;
+  await Promise.all([...activeInspectors].map((inspector) => inspector.stop()));
+}
 
 /**
  * The five-second deadline is what keeps the caller check fail-closed: a read
@@ -148,6 +155,7 @@ function parseWindowsAncestry(stdout, parentPid, limit) {
  * elapsedMs so tests can report where the time went.
  */
 export function runProcessInspector(command, args, { timeout, startupTimeout, readyMarker, maxBuffer = Infinity, windowsHide = true } = {}) {
+  if (inspectorsStopping) return Promise.reject(Object.assign(new Error("Process inspection is shutting down"), { code: "ABORT_ERR" }));
   return new Promise((resolve, reject) => {
     const started = performance.now();
     const child = spawn(command, args, { windowsHide, stdio: ["ignore", "pipe", "pipe"] });
@@ -156,36 +164,59 @@ export function runProcessInspector(command, args, { timeout, startupTimeout, re
     let readyAfterMs = null;
     let settled = false;
     let timer;
+    let failure;
+    let killTimer;
+    let closeTimer;
+    let resolveClosed;
+    const closed = new Promise((resolve) => { resolveClosed = resolve; });
+    const inspector = { stop: () => {
+      fail(Object.assign(new Error("Process inspection cancelled during shutdown"), { code: "ABORT_ERR" }));
+      return closed.then((error) => { if (error) throw error; });
+    } };
+    activeInspectors.add(inspector);
     const text = (stream) => Buffer.concat(output[stream]).toString("utf8");
     const settle = (error) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      if (error && child.pid !== undefined && child.exitCode === null && child.signalCode === null) child.kill();
+      clearTimeout(killTimer);
+      clearTimeout(closeTimer);
+      activeInspectors.delete(inspector);
+      resolveClosed(error?.cleanupFailed ? error : null);
       const result = { stdout: text("stdout"), stderr: text("stderr"), pid: child.pid, readyAfterMs, elapsedMs: Math.round(performance.now() - started) };
       if (error) reject(Object.assign(error, result));
       else resolve(result);
     };
+    const fail = (error) => {
+      if (settled || failure) return;
+      failure = error;
+      clearTimeout(timer);
+      closeTimer = setTimeout(() => settle(Object.assign(failure, { cleanupFailed: true, message: `${failure.message}; helper ${child.pid} did not close within 5000 ms after termination` })), 5000);
+      if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
+        child.kill();
+        killTimer = setTimeout(() => child.kill("SIGKILL"), 250);
+      }
+    };
     const arm = (phase, ms) => {
       clearTimeout(timer);
-      timer = setTimeout(() => settle(Object.assign(new Error(`Process inspection ${phase} deadline elapsed`), { code: "ETIMEDOUT", phase, killed: true, signal: "SIGTERM" })), ms);
+      timer = setTimeout(() => fail(Object.assign(new Error(`Process inspection ${phase} deadline elapsed`), { code: "ETIMEDOUT", phase, killed: true, signal: "SIGTERM" })), ms);
     };
     if (readyMarker) arm("startup", startupTimeout);
     else arm("inspection", timeout);
     for (const stream of ["stdout", "stderr"]) {
       child[stream].on("data", (chunk) => {
-        if (settled) return;
+        if (settled || failure) return;
         output[stream].push(chunk);
         size[stream] += chunk.length;
-        if (size[stream] > maxBuffer) return settle(Object.assign(new RangeError(`${stream} maxBuffer length exceeded`), { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" }));
+        if (size[stream] > maxBuffer) return fail(Object.assign(new RangeError(`${stream} maxBuffer length exceeded`), { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" }));
         if (stream === "stderr" && readyMarker && readyAfterMs === null && text("stderr").includes(readyMarker)) {
           readyAfterMs = Math.round(performance.now() - started);
           arm("inspection", timeout);
         }
       });
     }
-    child.on("error", settle);
-    child.on("close", (code, signal) => settle(code === 0 ? null : Object.assign(new Error(`Process inspection exited with ${signal ?? code}`), { code, signal })));
+    child.on("error", fail);
+    child.on("close", (code, signal) => settle(failure ?? (code === 0 ? null : Object.assign(new Error(`Process inspection exited with ${signal ?? code}`), { code, signal }))));
   });
 }
 

package/src/index.mjs

@@ -29,12 +29,12 @@ import { exitForVersionRequest } from "./cli-version.mjs";
 import { createRuntimeState } from "./runtime-state.mjs";
 import { assertRoutingReload, clientReloadReason, createReloadControl } from "./reload-control.mjs";
 import { accountIdentity, assertAccountIdentity, publicAccountState, readBridgeAccounts, requireBridgeAccounts } from "./bridge-account-context.mjs";
-import { assertClaudeSenderContext, readClaudeSenderContext, requireClaudeSenderContext } from "./claude-sender-context.mjs";
+import { assertClaudeSenderContext, readClaudeSenderContext, requireClaudeSenderContext, stopProcessInspectors } from "./claude-sender-context.mjs";
 import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.1";
+const VERSION = "1.19.2";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -1011,5 +1011,13 @@ registerTool(
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
+let shutdownPromise;
+const shutdown = () => shutdownPromise ??= (async () => {
+  client?.close();
+  await server.close();
+  await stopProcessInspectors();
+})();
+process.stdin.once("end", () => { void shutdown().catch((error) => log(`shutdown failed: ${error.message}`)); });
+process.once("disconnect", () => { void shutdown().catch((error) => log(`shutdown failed: ${error.message}`)); });
 reload.listen();
 log(desktopTasksEnabled ? `ready on ${PLATFORM_LABEL} (Codex Desktop only; external app-server disabled)` : `ready on ${PLATFORM_LABEL} (app-server endpoint: ${client.url}, codex: ${client.codexBin})`);

package/src/mcp-supervisor.mjs

@@ -44,6 +44,7 @@ class Worker {
       env: { ...env, CODEX_BRIDGE_WORKER: "1", CODEX_BRIDGE_STAGED: "1" },
       stdio: ["pipe", "pipe", "pipe", "ipc"], serialization: "json",
     });
+    this.exited = new Promise((resolve) => this.process.once("exit", resolve));
     this.process.stderr.on("data", (data) => process.stderr.write(data));
     this.process.stdin.on("error", (error) => this.fail(error));
     this.process.on("error", (error) => this.fail(error));
@@ -110,13 +111,23 @@ class Worker {
 
   async stop() {
     this.retiring = true;
-    if (this.process.exitCode !== null || this.process.signalCode) return;
-    await new Promise((resolve) => {
-      const timer = setTimeout(() => { this.process.kill(); resolve(); }, 1000);
-      this.process.once("exit", () => { clearTimeout(timer); resolve(); });
+    if (this.stopping) return this.stopping;
+    this.stopping = (async () => {
+      let timer;
+      const wait = async (ms) => {
+        try {
+          return await Promise.race([this.exited.then(() => true), new Promise((resolve) => { timer = setTimeout(() => resolve(false), ms); })]);
+        } finally { clearTimeout(timer); }
+      };
       this.process.stdin.end();
       if (this.process.connected) this.process.disconnect();
-    });
+      if (await wait(6000)) return;
+      if (this.process.exitCode === null && this.process.signalCode === null) {
+        this.process.kill("SIGKILL");
+      }
+      if (!await wait(5000)) throw new Error(`Bridge worker ${this.process.pid} did not close after termination`);
+    })();
+    return this.stopping;
   }
 }
 
@@ -248,13 +259,16 @@ export async function runSupervisor(entry, options = {}) {
       reloads++;
       reason = null;
       if (JSON.stringify(catalog) !== JSON.stringify(oldCatalog)) output({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
-      await previous.stop();
+      await previous.stop().catch((error) => log(`retired ${entry} worker: ${error.message}`));
       workers.delete(previous);
       log(`activated ${entry} revision ${revision.slice(0, 12)}; client connection retained`);
     } catch (error) {
       reason = `Update deferred: ${error.message}`;
       retryAt = Date.now() + Math.max(pollMs, 5000);
-      if (candidate) { await candidate.stop(); workers.delete(candidate); }
+      if (candidate) {
+        await candidate.stop().catch((stopError) => log(`rejected ${entry} candidate: ${stopError.message}`));
+        workers.delete(candidate);
+      }
       if (quiesced && active === previous && !previous.closed) {
         try { await previous.control("resume"); }
         catch (resumeError) { failure = `Previous runtime could not resume: ${resumeError.message}`; }

package/src/native-relay-companion.mjs

@@ -34,7 +34,7 @@ import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.1";
+const VERSION = "1.19.2";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {

package/src/release-snapshot.mjs

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
 
 function digestFiles(root, files) {
   const hash = createHash("sha256");
@@ -49,14 +50,14 @@ function digestMetadata(cache) {
     }
   };
   return {
-    digest(directory, files) {
+    digest(directory, files, sources) {
       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 fullPath = sources?.get(file) ?? 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);
@@ -105,25 +106,101 @@ function digestMetadata(cache) {
   };
 }
 
-function inventory(root, prefix = "") {
+function inventory(root, prefix = "", omitModules = false) {
   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;
+    if (omitModules && !prefix && entry.name === "node_modules") 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));
+    if (stat.isDirectory()) files.push(...inventory(root, relative, omitModules));
     else if (stat.isFile()) files.push(relative);
     else throw new Error(`Unsupported release file: ${relative}`);
   }
   return files;
 }
 
+const INSTALLATION_LOCKS = ".bridge-installation-locks.json";
+const dependencySearchPaths = (root, name) => createRequire(path.join(root, "package.json")).resolve.paths(name) ?? [];
+
+function installationLocks(root) {
+  const saved = path.join(root, INSTALLATION_LOCKS);
+  if (fs.existsSync(saved)) return fs.readFileSync(saved, "utf8");
+  const local = path.join(root, "node_modules");
+  const hashes = [];
+  for (const directory of dependencySearchPaths(root, "bridge-dependency-lock")) {
+    if (directory === local) continue;
+    const lock = path.join(directory, ".package-lock.json");
+    if (fs.existsSync(lock)) hashes.push(createHash("sha256").update(fs.readFileSync(lock)).digest("hex"));
+  }
+  return JSON.stringify(hashes);
+}
+
+function dependencyFiles(root) {
+  const files = new Map();
+  if (fs.existsSync(path.join(root, "node_modules"))) {
+    for (const file of inventory(root, "node_modules")) files.set(file, path.join(root, file));
+  }
+  const queue = [{ source: root, destination: "" }];
+  const visited = new Set();
+  const packageSources = new Map();
+  const packageAt = (directory) => {
+    if (packageSources.has(directory)) return packageSources.get(directory);
+    const manifest = files.get(path.join(directory, "package.json"));
+    if (!manifest) return null;
+    const source = fs.realpathSync.native(path.dirname(manifest));
+    packageSources.set(directory, source);
+    return source;
+  };
+  for (let index = 0; index < queue.length; index++) {
+    const { source, destination } = queue[index];
+    if (visited.has(destination)) continue;
+    visited.add(destination);
+    const manifest = JSON.parse(fs.readFileSync(path.join(source, "package.json"), "utf8"));
+    const names = new Set([...Object.keys(manifest.dependencies ?? {}), ...Object.keys(manifest.optionalDependencies ?? {}), ...Object.keys(manifest.peerDependencies ?? {})]);
+    for (const name of [...names].sort()) {
+      if (!/^(?:@[a-zA-Z0-9._~-]+\/)?[a-zA-Z0-9._~-]+$/.test(name) || name === "." || name === "..") throw new Error(`Unsafe dependency name: ${name}`);
+      let resolved;
+      for (const modules of dependencySearchPaths(source, name)) {
+        const candidate = path.join(modules, name);
+        if (fs.existsSync(path.join(candidate, "package.json"))) { resolved = fs.realpathSync.native(candidate); break; }
+      }
+      if (!resolved) {
+        if (Object.hasOwn(manifest.optionalDependencies ?? {}, name) || manifest.peerDependenciesMeta?.[name]?.optional) continue;
+        throw new Error(`Cannot resolve required dependency ${name} from ${source}`);
+      }
+      let placement;
+      let current = destination;
+      while (true) {
+        if (path.basename(current) !== "node_modules") {
+          const candidate = path.join(current, "node_modules", name);
+          const installed = packageAt(candidate);
+          if (installed) { if (installed === resolved) placement = candidate; break; }
+        }
+        if (!current) break;
+        const parent = path.dirname(current);
+        current = parent === "." ? "" : parent;
+      }
+      if (!placement) {
+        const hoisted = path.join("node_modules", name);
+        placement = packageAt(hoisted) ? path.join(destination, "node_modules", name) : hoisted;
+        const occupied = packageAt(placement);
+        if (occupied && occupied !== resolved) throw new Error(`Conflicting dependency resolution for ${name}`);
+        for (const file of inventory(resolved, "", true)) files.set(path.join(placement, file), path.join(resolved, file));
+        packageSources.set(placement, resolved);
+      }
+      queue.push({ source: resolved, destination: placement });
+    }
+  }
+  return new Map([...files].sort(([left], [right]) => left.localeCompare(right, "en")));
+}
+
 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);
+  return createHash("sha256").update(digestFiles(root, files)).update(installationLocks(root)).digest("hex");
 }
 
 export function snapshotRoot(env = process.env) {
@@ -153,31 +230,36 @@ export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRe
   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 dependencies = dependencyFiles(root);
+  const dependencyRevision = metadata.digest(root, [...dependencies.keys()], 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;
+    return sourceRevision(directory) === expectedRevision && metadata.digest(directory, inventory(directory, "node_modules").sort((left, right) => left.localeCompare(right, "en"))) === 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");
+    const currentDependencies = dependencyFiles(root);
+    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, [...currentDependencies.keys()], currentDependencies) !== dependencyRevision) {
+      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];
+    const files = ["package.json", ...inventory(root, "src"), ...dependencies.keys()];
     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);
+      fs.copyFileSync(dependencies.get(file) ?? 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)) {
+    fs.writeFileSync(path.join(temporary, INSTALLATION_LOCKS), installationLocks(root), { flag: "wx", mode: 0o600 });
+    const currentDependencies = dependencyFiles(root);
+    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, [...currentDependencies.keys()], currentDependencies) !== dependencyRevision || !validate(temporary)) {
       throw new Error("The installation changed while its immutable runtime was being prepared");
     }
     try {