@minhspark/codex-mcp-bridge 1.19.1 → 1.19.3

package/CHANGELOG.md

@@ -4,6 +4,23 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.19.3] - 2026-09-30
+
+### Changed
+
+- Write the `analytics` branch with the `Repository analytics` workflow's own token. Its hourly commits were pushed with `ANALYTICS_TOKEN`, a personal token, so they were attributed to the repository owner and GitHub showed the owner an "analytics had recent pushes" banner with a "Compare & pull request" button after every run. The commits now come from `github-actions[bot]`. `ANALYTICS_TOKEN` only reads GitHub traffic and no longer needs write access (fine-grained: Administration read).
+
+### Fixed
+
+- Refuse Claude-to-Codex Desktop delivery into another project even when `send_to_codex_thread` omits `cwd` or supplies the recipient's directory. The bridge now compares the independently verified Claude caller with the destination before creation, rename, navigation and prompt delivery, and checks both directory/repository identities and the current native destination again at the socket write. Broad allowed roots and thread overrides cannot authorize a different project. Subfolders and registered worktrees of the same repository remain usable; drive/home repositories do not absorb unrelated projects. Blocked preflight calls report that no Desktop mutation was dispatched.
+
+## [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/README.md

@@ -331,7 +331,7 @@ For unresolved failures, [open an issue](https://github.com/buidangminh23/codex-
 
 ## Repository analytics
 
-The live dashboard polls the aggregate API every 30 seconds. Installation counts reflect reports received by the server; this is not a count of currently online processes. Public GitHub/npm sources are refreshed with a short cache, but their own statistics may be delayed. GitHub Actions refreshes and archives statistics hourly through the `Repository analytics` workflow, including private GitHub traffic; scheduled runs may be delayed by GitHub. That workflow needs the `ANALYTICS_TOKEN` repository secret set to a token with push access to this repository (fine-grained: Contents read/write plus Administration read); the default workflow token cannot read GitHub traffic, so without it the views/clones sources are retained from the last successful run and the run is reported as incomplete while the Pages deployment still succeeds. The README image is a snapshot and may be cached by GitHub; open the live dashboard for automatic updates. Source timestamps show freshness; missing data is unavailable, not zero. Only aggregate figures are published. Installation IDs stay in the private database.
+The live dashboard polls the aggregate API every 30 seconds. Installation counts reflect reports received by the server; this is not a count of currently online processes. Public GitHub/npm sources are refreshed with a short cache, but their own statistics may be delayed. GitHub Actions refreshes and archives statistics hourly through the `Repository analytics` workflow, including private GitHub traffic; scheduled runs may be delayed by GitHub. That workflow reads GitHub traffic with the `ANALYTICS_TOKEN` repository secret, a token with push access to this repository (fine-grained: Administration read); the default workflow token cannot read GitHub traffic, so without it the views/clones sources are retained from the last successful run and the run is reported as incomplete while the Pages deployment still succeeds. The `analytics` branch is written with the workflow's own token, so its commits come from `github-actions[bot]` and `ANALYTICS_TOKEN` needs no write access. The README image is a snapshot and may be cached by GitHub; open the live dashboard for automatic updates. Source timestamps show freshness; missing data is unavailable, not zero. Only aggregate figures are published. Installation IDs stay in the private database.
 
 Repository owners can view [GitHub traffic](https://github.com/buidangminh23/codex-mcp-bridge/graphs/traffic) for recent views and clones. Downloads and clones include updates, reinstalls, and automation; they do not measure active users. GitHub traffic only covers the recent 14-day window, so collect it regularly to keep a longer history.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.19.1",
+  "version": "1.19.3",
   "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.3";
 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/scripts/publish-repo-analytics.mjs

@@ -150,11 +150,19 @@ export function publicFiles(history, usage) {
   return { 'dashboard.svg': renderPublicDashboard(data), 'README.md': readme.replace('![Repository dashboard]', `[Live dashboard · refreshes every 30 seconds](${pagesUrl})\n\n![Repository dashboard]`), 'data.json': `${JSON.stringify(data, null, 2)}\n`, 'index.html': renderLiveDashboard(data) };
 }
 
-export function githubApi(endpoint, { method = 'GET', body } = {}) {
+export function githubEnvironment(token, env = process.env) {
+  return token ? { ...env, GH_TOKEN: token } : env;
+}
+
+export function githubClient(token, api = githubApi) {
+  return token ? (endpoint, options = {}) => api(endpoint, { ...options, token }) : api;
+}
+
+export function githubApi(endpoint, { method = 'GET', body, token } = {}) {
   return new Promise((resolve, reject) => {
     const args = ['api', '--hostname', 'github.com', '--method', method, endpoint];
     if (body) args.push('--input', '-');
-    const child = spawn('gh', args, { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    const child = spawn('gh', args, { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'], env: githubEnvironment(token) });
     let stdout = '';
     let stderr = '';
     const timer = setTimeout(() => child.kill(), 60000);

package/scripts/refresh-hosted-analytics.mjs

@@ -1,37 +1,46 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { collectSources, mergeHistory } from './collect-repo-analytics.mjs';
-import { githubApi, publicFiles, publishAnalytics, sanitizeAnalytics } from './publish-repo-analytics.mjs';
+import { githubApi, githubClient, publicFiles, publishAnalytics, sanitizeAnalytics } from './publish-repo-analytics.mjs';
 import { TELEMETRY_PUBLIC_KEY } from '../src/telemetry-config.mjs';
 
 const repo = 'buidangminh23/codex-mcp-bridge';
-const file = await githubApi(`repos/${repo}/contents/data.json?ref=analytics`);
-const previous = JSON.parse(Buffer.from(file.content, 'base64').toString('utf8'));
-const options = { repo, package: '@minhspark/codex-mcp-bridge' };
-const snapshot = await collectSources(options);
-const history = mergeHistory(previous, options, snapshot);
-let usage = previous.usage;
-let usageFailed = false;
-try {
-  const response = await fetch('https://vdbwkowdggtcihixowxi.supabase.co/functions/v1/bridge-stats', {
-    headers: { apikey: TELEMETRY_PUBLIC_KEY }, signal: AbortSignal.timeout(15000),
-  });
-  if (!response.ok) throw new Error('Stats unavailable');
-  const data = await response.json();
-  if (!data.usage || data.errors?.some(row => row.source === 'usage')) throw new Error('Usage unavailable');
-  usage = sanitizeAnalytics(history, data.usage).usage;
-} catch { usageFailed = true; }
-const sha = await publishAnalytics(repo, publicFiles(history, usage));
-const ref = await githubApi(`repos/${repo}/git/ref/heads/analytics`);
-if (ref.object.sha !== sha) throw new Error('Analytics publication changed during verification');
-const directory = path.resolve('public-analytics');
-await mkdir(directory, { recursive: true });
-for (const [name, content] of Object.entries(publicFiles(history, usage))) await writeFile(path.join(directory, name), content);
-console.log(`Published aggregate analytics: ${sha}`);
-for (const error of snapshot.errors) {
-  const status = error.status ? ` (HTTP ${error.status})` : '';
-  const hint = error.status === 403 && ['views', 'clones'].includes(error.source) ? ' GitHub traffic requires the ANALYTICS_TOKEN secret to be a token with push access (fine-grained: Administration read); the default workflow token cannot read traffic.' : '';
-  console.error(`::warning::${error.source} was not refreshed${status}; previous data retained.${hint}`);
+
+export async function refreshHostedAnalytics({ env = process.env, api = githubApi, collect = collectSources, fetcher = fetch, directory = path.resolve('public-analytics') } = {}) {
+  const branch = githubClient(env.ANALYTICS_BRANCH_TOKEN, api);
+  const file = await branch(`repos/${repo}/contents/data.json?ref=analytics`);
+  const previous = JSON.parse(Buffer.from(file.content, 'base64').toString('utf8'));
+  const options = { repo, package: '@minhspark/codex-mcp-bridge' };
+  const snapshot = await collect(options);
+  const history = mergeHistory(previous, options, snapshot);
+  let usage = previous.usage;
+  let usageFailed = false;
+  try {
+    const response = await fetcher('https://vdbwkowdggtcihixowxi.supabase.co/functions/v1/bridge-stats', {
+      headers: { apikey: TELEMETRY_PUBLIC_KEY }, signal: AbortSignal.timeout(15000),
+    });
+    if (!response.ok) throw new Error('Stats unavailable');
+    const data = await response.json();
+    if (!data.usage || data.errors?.some(row => row.source === 'usage')) throw new Error('Usage unavailable');
+    usage = sanitizeAnalytics(history, data.usage).usage;
+  } catch { usageFailed = true; }
+  const sha = await publishAnalytics(repo, publicFiles(history, usage), branch);
+  const ref = await branch(`repos/${repo}/git/ref/heads/analytics`);
+  if (ref.object.sha !== sha) throw new Error('Analytics publication changed during verification');
+  await mkdir(directory, { recursive: true });
+  for (const [name, content] of Object.entries(publicFiles(history, usage))) await writeFile(path.join(directory, name), content);
+  return { sha, errors: snapshot.errors, usageFailed };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  const { sha, errors, usageFailed } = await refreshHostedAnalytics();
+  console.log(`Published aggregate analytics: ${sha}`);
+  for (const error of errors) {
+    const status = error.status ? ` (HTTP ${error.status})` : '';
+    const hint = error.status === 403 && ['views', 'clones'].includes(error.source) ? ' GitHub traffic requires the ANALYTICS_TOKEN secret to be a token with push access (fine-grained: Administration read); the default workflow token cannot read traffic.' : '';
+    console.error(`::warning::${error.source} was not refreshed${status}; previous data retained.${hint}`);
+  }
+  if (usageFailed) console.error('::warning::Usage was not refreshed; previous data retained.');
+  if (errors.length || usageFailed) process.exitCode = 1;
 }
-if (usageFailed) console.error('::warning::Usage was not refreshed; previous data retained.');
-if (snapshot.errors.length || usageFailed) process.exitCode = 1;

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.3";
 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.3";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -57,7 +57,7 @@ const security = new BridgeSecurityPolicy();
 const desktopTasksEnabled = desktopTasksConfigured();
 const runtime = createRuntimeState({ configuration: desktopTasksConfigured });
 const desktopOperation = new AsyncLocalStorage();
-const desktopTasks = new DesktopTaskDelivery({ security, beforeRequest: beforeDesktopRequest, accountContext: () => desktopOperation.getStore()?.accounts });
+const desktopTasks = new DesktopTaskDelivery({ security, beforeRequest: beforeDesktopRequest, accountContext: () => desktopOperation.getStore()?.accounts, senderContext: () => desktopOperation.getStore()?.caller });
 
 async function assertDesktopOperation(context, { verifyProcess = false } = {}) {
   if (!context || context.diagnostic) return;
@@ -77,7 +77,7 @@ async function beforeDesktopRequest({ operation, args, phase }) {
   if (!context) throw new Error("Desktop operations require a verified calling Code session.");
   const mutating = ["create_thread", "send_message_to_thread", "set_thread_title", "navigate_to_codex_page"].includes(operation);
   await assertDesktopOperation(context, { verifyProcess: mutating && phase === "write" });
-  if (mutating) {
+  if (mutating && phase === "dispatch") {
     context.dispatched = true;
     if (args.threadId) context.threadId = args.threadId;
   }
@@ -349,7 +349,8 @@ const server = new McpServer(
       "A completed turn alone does not mean the task is finished. Do not choose an old task merely because its project matches or it was recently active. " +
       "Without authorization to create a new conversation, ask before creating it. With Desktop tasks enabled it assigns the exact saved project and starts visibly in " +
       "Codex Desktop using Desktop permissions. Otherwise it releases the bridge writer lock and opens the exact thread in " +
-      "Codex Desktop. Use send_to_codex_thread only when an existing threadId is intentional; use " +
+      "Codex Desktop. Desktop creation and sends always require the verified calling Claude task and the Codex destination to belong to the same project, even when cwd is omitted. " +
+      "Use send_to_codex_thread only when an existing threadId is intentional; use " +
       "list_codex_threads or read_codex_thread to inspect sessions and codex_bridge_status to inspect wiring. " +
       AGENT_PROMPT_GUIDANCE,
   },
@@ -368,6 +369,7 @@ function registerTool(name, definition, handler) {
         result.content.push({ type: "text", text: `runtime pid: ${state.pid}\nloaded source: ${state.revision}\nruntime state: current` });
         result.structuredContent = { ...result.structuredContent, runtime: state };
         if (desktopTasksEnabled) {
+          result.structuredContent.projectScope = { enabled: true, policy: "verified-sender-same-project", match: "canonical-directory-or-git-repository", checkedBeforeMutation: true };
           result.structuredContent.accounts = { claude: publicAccountState(accounts.claude), codex: publicAccountState(accounts.codex) };
         }
         return result;
@@ -383,6 +385,9 @@ function registerTool(name, definition, handler) {
             await assertDesktopOperation(context);
             const result = await handler(...args);
             await assertDesktopOperation(context);
+            if (result.isError && !context.dispatched) {
+              result.structuredContent = { ...result.structuredContent, accountContext: context.accounts, operation: { state: "blocked", threadId: context.threadId ?? null } };
+            }
             return result;
           } catch (error) {
             return withheldDesktopResult(error, context);
@@ -513,7 +518,7 @@ registerTool(
         .max(3600)
         .optional()
         .describe("How long to observe the task (Desktop caps the entire call at 40s; the task continues and its threadId is returned)"),
-      cwd: z.string().optional().describe("Override the working directory for this turn"),
+      cwd: z.string().optional().describe("Expected destination directory; Desktop always checks the verified sender's project and cannot change the task's workspace"),
       model: z.string().optional().describe("Override the model for this turn"),
       effort: z
         .enum(["minimal", "low", "medium", "high", "xhigh", "ultra"])
@@ -950,6 +955,7 @@ registerTool(
         `bridge version: ${VERSION}`,
         `node:           ${process.version} at ${process.execPath}`,
         "desktop tasks:  enabled; Desktop permissions, exact saved project, immediate visibility",
+        "project scope:  verified Claude sender; same directory or Git repository, checked before each mutation",
         `native relay:   ${native.available ? "available; verified through Codex Desktop" : "unavailable"}`,
         `native endpoint: ${native.socketPath}`,
         ...(native.available ? [`local projects: ${native.localProjects}`] : [`reason: ${native.reason}`]),
@@ -1011,5 +1017,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.3";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {

package/src/project-scope.mjs

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function directory(value) {
+  if (typeof value !== "string" || !value.trim() || !path.isAbsolute(value)) throw new Error("Project directory must be an absolute existing directory");
+  const resolved = fs.realpathSync.native(value);
+  const stat = fs.statSync(resolved, { bigint: true });
+  if (!stat.isDirectory()) throw new Error("Project path is not a directory");
+  return { input: value, path: resolved, identity: `${stat.dev}:${stat.ino}:${stat.birthtimeNs ?? stat.birthtimeMs}` };
+}
+
+function samePath(left, right) {
+  return path.relative(left, right) === "";
+}
+
+function metadata(file) {
+  const stat = fs.statSync(file);
+  if (!stat.isFile() || stat.size > 4096) throw new Error("Invalid project repository metadata");
+  return fs.readFileSync(file, "utf8").trim();
+}
+
+function exists(file) {
+  try { fs.lstatSync(file); return true; } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function gitRepository(gitdir, common = gitdir) {
+  const head = metadata(path.join(gitdir.path, "HEAD"));
+  if (!/^(?:ref: refs\/[^\s]+|[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/.test(head)) throw new Error("Invalid project repository HEAD metadata");
+  directory(path.join(common.path, "objects"));
+  return common;
+}
+
+function repository(cwd) {
+  const home = fs.realpathSync.native(os.homedir());
+  for (let root = cwd; ; root = path.dirname(root)) {
+    if (samePath(root, path.parse(root).root) || samePath(root, home)) return null;
+    const marker = path.join(root, ".git");
+    if (exists(marker)) {
+      if (fs.statSync(marker).isDirectory()) return gitRepository(directory(marker));
+      const match = metadata(marker).match(/^gitdir: ([^\r\n]+)$/);
+      if (!match) throw new Error("Invalid project gitdir metadata");
+      const gitdir = directory(path.resolve(root, match[1]));
+      const commonFile = path.join(gitdir.path, "commondir");
+      if (!exists(commonFile)) return gitRepository(gitdir);
+      const common = gitRepository(directory(path.resolve(gitdir.path, metadata(commonFile))));
+      const registered = path.relative(path.join(common.path, "worktrees"), gitdir.path);
+      if (!registered || registered === ".." || registered.startsWith(`..${path.sep}`) || path.isAbsolute(registered) || registered.includes(path.sep)) throw new Error("Project worktree is not registered in its common repository");
+      const backlink = path.resolve(gitdir.path, metadata(path.join(gitdir.path, "gitdir")));
+      if (!samePath(fs.realpathSync.native(backlink), fs.realpathSync.native(marker))) throw new Error("Project worktree backlink does not match its directory");
+      return gitRepository(gitdir, common);
+    }
+    if (path.dirname(root) === root) return null;
+  }
+}
+
+function project(value) {
+  const current = directory(value);
+  return { ...current, repository: repository(current.path) };
+}
+
+function sameBinding(left, right) {
+  return Boolean(left && right && samePath(left.path, right.path) && left.identity === right.identity);
+}
+
+function sameProject(left, right) {
+  return sameBinding(left, right) || sameBinding(left.repository, right.repository);
+}
+
+export function captureProjectScope(senderCwd, recipientCwd) {
+  let sender;
+  let recipient;
+  try {
+    sender = project(senderCwd);
+    recipient = project(recipientCwd);
+  } catch (cause) {
+    const error = new Error(`Project scope could not be verified: ${cause.message}. No message was sent.`, { cause });
+    error.code = "PROJECT_SCOPE_UNVERIFIED";
+    throw error;
+  }
+  if (!sameProject(sender, recipient)) {
+    const error = new Error(`Project mismatch: the calling Claude task works in "${sender.path}", but the Codex destination works in "${recipient.path}". Select a task in the sender's project. No message was sent.`);
+    error.code = "PROJECT_SCOPE_MISMATCH";
+    throw error;
+  }
+  return { sender, recipient };
+}
+
+export function recheckProjectScope(expected, current = captureProjectScope(expected.sender.input, expected.recipient.input)) {
+  for (const side of ["sender", "recipient"]) {
+    if (!sameBinding(expected[side], current[side]) ||
+        Boolean(expected[side].repository) !== Boolean(current[side].repository) ||
+        (expected[side].repository && !sameBinding(expected[side].repository, current[side].repository))) {
+      const error = new Error(`The ${side} project directory or repository changed before delivery. No message was sent.`);
+      error.code = "PROJECT_SCOPE_CHANGED";
+      throw error;
+    }
+  }
+  return current;
+}

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 {

package/src/thread-delivery.mjs

@@ -4,6 +4,8 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { DesktopTaskReceipts } from "./desktop-task-receipts.mjs";
 import { captureCodexRolloutWatermark, inspectCodexNativeTurn, readCodexNativeTurnResponse } from "./codex-native-response.mjs";
+import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
+import { requireClaudeSenderContext } from "./claude-sender-context.mjs";
 
 /**
  * Which backend puts a message into a Codex thread.
@@ -48,7 +50,7 @@ export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync
 }
 
 export class DesktopTaskDelivery {
-  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts(), beforeRequest, accountContext, captureResponse = captureCodexRolloutWatermark, readResponse = readCodexNativeTurnResponse, inspectResponse = inspectCodexNativeTurn } = {}) {
+  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts(), beforeRequest, accountContext, senderContext, captureResponse = captureCodexRolloutWatermark, readResponse = readCodexNativeTurnResponse, inspectResponse = inspectCodexNativeTurn } = {}) {
     this.relay = relay;
     this.security = security;
     this.sleep = sleep;
@@ -56,25 +58,56 @@ export class DesktopTaskDelivery {
     this.receipts = receipts;
     this.beforeRequest = beforeRequest;
     this.accountContext = accountContext;
+    this.senderContext = senderContext;
     this.captureResponse = captureResponse;
     this.readResponse = readResponse;
     this.inspectResponse = inspectResponse;
     this.threadOperations = new Map();
   }
 
-  async request(operation, args, { deadline, includeRelayContext = false } = {}) {
+  senderProjectScope(cwd) {
+    if (!this.senderContext) return null;
+    const sender = requireClaudeSenderContext(this.senderContext());
+    return captureProjectScope(sender.cwd, cwd);
+  }
+
+  async mutationProjectScope(operation, args, { deadline } = {}) {
+    if (!this.senderContext) return null;
+    if (operation === "create_thread") {
+      const listed = await this.request("list_projects", {}, { deadline });
+      const projects = listed?.projects?.filter((project) => project.projectId === args.target?.projectId && project.projectKind === "local" && project.hostId === "local");
+      if (projects?.length !== 1) throw new Error("Desktop did not confirm the destination project before creation");
+      this.security.assertCwd(projects[0].path);
+      return this.senderProjectScope(projects[0].path);
+    }
+    if (!["send_message_to_thread", "set_thread_title", "navigate_to_codex_page"].includes(operation)) return null;
+    const inspected = await this.inspect(args.threadId, undefined, { deadline });
+    return inspected.projectScope;
+  }
+
+  async request(operation, args, { deadline, includeRelayContext = false, projectScope: expectedScope } = {}) {
     try {
       await this.beforeRequest?.({ operation, args });
+      const projectScope = expectedScope ?? await this.mutationProjectScope(operation, args, { deadline });
+      if (expectedScope) recheckProjectScope(expectedScope, this.senderProjectScope(expectedScope.recipient.input));
       const remaining = deadline === undefined ? undefined : deadline - this.now();
       if (remaining !== undefined && remaining <= 0) throw new Error("The bridge's response deadline has elapsed; this operation was not sent");
       const accountContext = this.accountContext?.();
       const response = await this.relay.requestDesktop(operation, args, {
         ...(remaining === undefined ? {} : { timeoutMs: remaining }),
-        ...(this.beforeRequest ? { beforeSend: () => this.beforeRequest({ operation, args, phase: "write" }) } : {}),
+        ...(this.beforeRequest || projectScope ? { beforeSend: async () => {
+          await this.beforeRequest?.({ operation, args, phase: "write" });
+          if (projectScope) {
+            recheckProjectScope(projectScope);
+            recheckProjectScope(projectScope, await this.mutationProjectScope(operation, args, { deadline }));
+          }
+          await this.beforeRequest?.({ operation, args, phase: "dispatch" });
+        } } : {}),
         ...(accountContext ? { accountContext } : {}),
       });
       return includeRelayContext ? { result: response.result, executorThreadId: response.executorThreadId } : response.result;
     } catch (err) {
+      if (err.code?.startsWith("PROJECT_SCOPE_") || err.code === "CLAUDE_SENDER_CONTEXT_UNVERIFIED") throw err;
       throw new Error(`Codex Desktop operation ${operation} failed: ${err.message}. Desktop-only mode will not start or use an external app-server. Open Codex Desktop and reconnect its native relay, then inspect the existing task before retrying a send.`, { cause: err });
     }
   }
@@ -203,6 +236,7 @@ export class DesktopTaskDelivery {
 
   async create({ cwd, prompt, name, dedupeName = name, requestId, model, effort, deadline = this.now() + DESKTOP_TOOL_BUDGET_MS }) {
     this.security.assertCwd(cwd);
+    const projectScope = this.senderProjectScope(cwd);
     cwd = realpathSync.native(cwd);
     this.security.assertCwd(cwd);
     dedupeName = dedupeName?.normalize("NFC").trim().replace(/\s+/g, " ") || undefined;
@@ -228,7 +262,7 @@ export class DesktopTaskDelivery {
           prompt, title: name,
           target: { type: "project", projectId: project.projectId, environment: { type: "local" } },
           ...(model ? { model } : {}), ...(effort ? { thinking: effort } : {}),
-        }, { deadline });
+        }, { deadline, projectScope });
         const confirmedId = response?.threadId ?? response?.conversationId;
         threadId = confirmedId;
         if (!threadId && (response?.status === "outcome-unknown" || response?.firstTurn?.status === "outcome-unknown")) threadId = response?.clientThreadId;
@@ -251,15 +285,16 @@ export class DesktopTaskDelivery {
     if (thread?.id !== threadId || thread.hostId !== "local" || !thread.cwd) throw new Error("Desktop did not confirm the task's local workspace.");
     this.security.assertThread(threadId, thread.cwd);
     this.security.assertCwd(thread.cwd);
+    const projectScope = this.senderProjectScope(thread.cwd);
     if (cwd && path.relative(realpathSync.native(cwd), realpathSync.native(thread.cwd))) {
       throw new Error("Native Desktop delivery cannot change an existing task's workspace; create a new task at the requested cwd.");
     }
-    return { thread, latestTurnId: response.turns?.[0]?.id ?? null };
+    return { thread, latestTurnId: response.turns?.[0]?.id ?? null, projectScope };
   }
 
   async send({ threadId, prompt, cwd, model, effort, name, deadline }) {
     const inspected = await this.inspect(threadId, cwd, { deadline });
-    if (name) await this.request("set_thread_title", { threadId, title: name.trim().slice(0, 200) }, { deadline });
+    if (name) await this.request("set_thread_title", { threadId, title: name.trim().slice(0, 200) }, { deadline, projectScope: inspected.projectScope });
     const expectedCwd = realpathSync.native(inspected.thread.cwd);
     const accountContext = this.accountContext?.();
     const watermark = this.captureResponse({ threadId, expectedCwd });
@@ -267,7 +302,7 @@ export class DesktopTaskDelivery {
       threadId, prompt,
       ...(model ? { model } : {}),
       ...(effort ? { thinking: effort } : {}),
-    }, { deadline, includeRelayContext: true });
+    }, { deadline, includeRelayContext: true, projectScope: inspected.projectScope });
     const response = envelope.result;
     if (response?.threadId !== threadId || response?.success === false || response?.isError === true ||
         (response?.status !== undefined && !["accepted", "sent"].includes(response.status)) ||