@minhspark/codex-mcp-bridge 1.22.6 → 1.22.8

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.22.6",
+  "version": "1.22.8",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,48 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.8] - 2026-10-20
+
+### Fixed
+
+- Compare file identities with exact 64-bit values everywhere. Reply and native creation receipts, the creation signing key, Codex rollout watermarks and segment checks, Codex account evidence, Claude Desktop task metadata and account state, project repository metadata, and the Sites connector's private files read `dev`, `ino`, `size` and nanosecond `mtime`/`ctime` as bigint. Number stats round inodes above 2^53, which NTFS file IDs and some macOS volumes (such as `/tmp` on the sealed system volume) exceed, so a replaced file or directory could pass as unchanged; this made `rejects replacement of a pinned receipt directory` fail intermittently on Windows CI.
+
+### Security
+
+- A rollout watermark now stores its file identity as exact decimal strings. A reply receipt written by an earlier version still matches only when its numeric identity is an exactly representable integer equal to the current file; a rounded identity no longer matches, and the observation reports the rollout as changed instead.
+
+### Verification
+
+- 7 new regression tests. Two identities that differ only below Number precision (`2^60` and `2^60 + 1`) compare as different for both `ino` and `dev`; the reply and native creation receipt stores reject a pinned directory whose inode changes only below 2^53, and both store tests fail on v1.22.7. The rollout watermark keeps exact string identities through JSON and honors only exactly representable legacy numbers.
+- A review of the change found a test that now passed without reaching its byte comparison: its mock returned Number stats to code that requests bigint. It was fixed and checked by removing the comparison, which makes the test fail.
+- CI passed on macOS, Ubuntu and Windows with Node 22 and 24, including `test (windows-latest, 22)` where the flake appeared. CodeQL re-reported 12 `js/path-injection` flows on the edited stat lines; each source is operator `process.env` configuration, matching the earlier dismissals, and they were dismissed as false positives.
+
+### Limitations
+
+- The 64-bit NTFS case runs for real only on Windows CI; local tests simulate it with mocked bigint stats. A reply observation whose earlier receipt stored a rounded rollout identity reports the rollout as changed; inspect that task instead of resending.
+
+## [1.22.7] - 2026-10-20
+
+### Added
+
+- Install with Homebrew: `brew install buidangminh23/tap/codex-mcp-bridge`. The formula in [buidangminh23/homebrew-tap](https://github.com/buidangminh23/homebrew-tap) follows each npm release.
+
+### Fixed
+
+- Record Homebrew's stable `opt` paths instead of a versioned Cellar keg when the Claude Desktop, Codex and native relay installers and `bridge-projects register-manager` write a client configuration, for both the bridge and Homebrew's Node.js. A keg path broke every registration as soon as `brew upgrade` removed the old keg. Paths outside a Homebrew keg are written exactly as before.
+- Start the supervisor when its path reaches the installation through a symbolic link, such as Homebrew's `opt` alias. The direct-execution check compared the unresolved command-line path with the resolved module path, so the process exited at once without serving MCP.
+- Follow a Homebrew upgrade in a running supervisor: it watches the `opt` alias, reloads the new keg like any other installed update, and forks workers with the stable Node.js path, instead of reporting "Installation is not ready" after the old keg is removed.
+
+### Verification
+
+- 9 new regression tests: Cellar to `opt` mapping, a custom `HOMEBREW_PREFIX`, the main-module check through a symlink and a respelled path, a running supervisor following a bridge keg switch, and one following a Node.js keg replacement. The supervisor tests fail on v1.22.6 and pass here.
+- End to end on macOS with a local tap: two packed versions installed with brew, the three installers run against an isolated home, and every recorded path was `opt/codex-mcp-bridge` and `opt/node` (the relay keeps Codex Desktop's Node). A bridge launched from the recorded Claude Desktop entry kept its supervisor through `brew upgrade` and `brew cleanup` and reloaded the new keg; fresh launches from the recorded paths answered `initialize`.
+- An independent adversarial review confirmed two defects in the first draft, a main-module regression for respelled paths and a worker Node path resolved too late, and both were fixed before merge.
+
+### Limitations
+
+- Registrations written from a Homebrew keg by an earlier version still name that keg; run the installers once after upgrading. `codex-native-relay-install` still refuses to rewrite an entry that has `env_vars`, so edit that entry's path by hand.
+
 ## [1.22.6] - 2026-10-20
 
 ### Fixed

package/README.md

@@ -27,6 +27,14 @@ npm install -g @minhspark/codex-mcp-bridge@latest
 
 Requires **Node.js 22+**. In Windows PowerShell, use `npm.cmd` instead of `npm`. Run the same command to update; reconnect MCP servers if their settings or installation paths changed.
 
+On macOS or Linux you can install with [Homebrew](https://github.com/buidangminh23/homebrew-tap) instead, which brings its own Node.js:
+
+```bash
+brew install buidangminh23/tap/codex-mcp-bridge
+```
+
+Update with `brew upgrade codex-mcp-bridge`. The installers record Homebrew's stable `opt` paths, so registrations keep working after an upgrade and running bridges reload the new version. Keep one install channel: whichever of npm or Homebrew comes first on `PATH` provides the commands.
+
 [Windows](#windows-powershell) · [macOS](#macos-terminal) · [Linux / WSL](#linux--wsl-bash) · [ChatGPT plugin](#chatgpt-plugin)
 
 ### Windows (PowerShell)
@@ -93,6 +101,15 @@ claude mcp add --scope user codex-bridge \
   -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
 ```
 
+For a Homebrew install, use the stable paths instead of `npm root -g` and `command -v node`:
+
+```bash
+bridge_root="$(brew --prefix)/opt/codex-mcp-bridge/libexec/lib/node_modules/@minhspark/codex-mcp-bridge"
+node_bin="$(brew --prefix)/opt/node/bin/node"
+```
+
+and end the command with `-- "$node_bin" "$bridge_root/src/mcp-supervisor.mjs" index.mjs`.
+
 </details>
 
 Separate multiple allowed directories with `;` on Windows or `:` on macOS/Linux.
@@ -178,7 +195,7 @@ Dispatch expires after two minutes; operation history remains stored. Disconnect
 
 ## Troubleshooting
 
-- **Command missing:** open a new terminal and check Node.js 22+ and the global npm directory on PATH.
+- **Command missing:** open a new terminal and check Node.js 22+ and the global npm directory (or Homebrew's `bin`) on PATH.
 - **PowerShell blocks scripts:** use `npm.cmd`, installer `.cmd` launchers, and `codex.exe`.
 - **No sessions or wrong project:** open the intended Claude **Code** session and use the exact project directory saved in Codex Desktop.
 - **Relay unavailable:** check [pipe forwarding](#native-relay-pipe-forwarding), reconnect, and run `native_relay_status` in the task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.6",
+  "version": "1.22.8",
   "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/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.22.6",
+  "version": "1.22.8",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-claude-desktop.mjs

@@ -9,10 +9,11 @@ import { desktopTasksConfigured } from "../src/native-relay.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();
 const reset = process.argv.includes("--reset");
 const forceDesktopTasks = process.argv.includes("--desktop-tasks");
@@ -29,7 +30,7 @@ if (fullAccess) enableCodexFullAccess();
  */
 const defaultRoots = "*";
 
-const nodeBin = process.env.NODE_EXE ?? process.execPath;
+const nodeBin = process.env.NODE_EXE ?? stableNodeBin();
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);
 
 if (!fs.existsSync(nodeBin)) throw new Error(`node executable not found: ${nodeBin}`);

package/scripts/install-codex-mcp.mjs

@@ -10,10 +10,12 @@ import { desktopTasksConfigured } from "../src/native-relay.mjs";
 import { codexMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+const nodeBin = process.env.NODE_EXE ?? stableNodeBin();
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);
 const serverName = process.env.CLAUDE_BRIDGE_NAME ?? "claude-bridge";
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
@@ -39,13 +41,13 @@ const servers = JSON.parse(run(["mcp", "list", "--json"]));
 if (!Array.isArray(servers)) throw new Error("Codex returned an invalid MCP inventory; existing configuration was not changed");
 const existing = servers.some((server) => server.name === serverName)
   ? JSON.parse(run(["mcp", "get", serverName, "--json"])) : null;
-const registration = codexMcpRegistration({ name: serverName, existing, node: process.execPath, entry, entryArgs, env: process.env, desktopOnly: desktopTasksConfigured() });
+const registration = codexMcpRegistration({ name: serverName, existing, node: nodeBin, entry, entryArgs, env: process.env, desktopOnly: desktopTasksConfigured() });
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...registration.environment }) });
 run(registration.args);
 
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`registered MCP server "${serverName}" with Codex:`);
-console.log(`command: ${process.execPath} ${entry} ${entryArgs.join(" ")}`);
+console.log(`command: ${nodeBin} ${entry} ${entryArgs.join(" ")}`);
 console.log(`environment keys: ${registration.environmentKeys.join(", ")}`);
 console.log("\nReconnect claude-bridge once in the existing Codex Desktop task to load the supervisor. Subsequent compatible installed-source updates reload automatically when the worker is safely idle. Do not create a replacement task.");
 console.log("Verify claude_bridge_status from that task: autoReload must be enabled, runtime state must be current, and the session policy must match this installation. A separate diagnostic process does not verify the app's loaded MCP process.");

package/scripts/install-native-relay.mjs

@@ -20,11 +20,12 @@ import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.6";
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION = "1.22.8";
+const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];
 const serverName = process.env.CODEX_NATIVE_RELAY_NAME ?? "codex-native-relay";

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.6";
+const VERSION = "1.22.8";
 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-desktop-context.mjs

@@ -9,7 +9,7 @@ const TASK_FILE = new RegExp(`^(local_${UUID})\\.json$`, "i");
 const MAX_ENTRIES = 8192;
 const MAX_FILE_BYTES = 4 * 1024 * 1024;
 const MAX_IDENTITY_BYTES = 32 * 1024 * 1024;
-const VERSION_FIELDS = ["size", "mtimeMs", "ctimeMs", "ino", "dev"];
+const VERSION_FIELDS = ["size", "mtimeNs", "ctimeNs", "ino", "dev"];
 
 const sameVersion = (left, right) => VERSION_FIELDS.every((field) => left[field] === right[field]);
 
@@ -68,12 +68,12 @@ function metadataFiles(root, accountId) {
 function readMetadata(file, budget) {
   const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   try {
-    const before = fs.fstatSync(descriptor);
-    if (!before.isFile() || before.size > MAX_FILE_BYTES) throw new Error("file limit");
-    const bytes = Buffer.alloc(before.size);
+    const before = fs.fstatSync(descriptor, { bigint: true });
+    if (!before.isFile() || before.size > BigInt(MAX_FILE_BYTES)) throw new Error("file limit");
+    const bytes = Buffer.alloc(Number(before.size));
     if (fs.readSync(descriptor, bytes, 0, bytes.length, 0) !== bytes.length) throw new Error("short read");
-    const after = fs.fstatSync(descriptor);
-    const current = fs.lstatSync(file);
+    const after = fs.fstatSync(descriptor, { bigint: true });
+    const current = fs.lstatSync(file, { bigint: true });
     if (!sameVersion(before, after) || current.isSymbolicLink() || !sameVersion(current, after)) throw new Error("metadata changed");
     budget.versions.set(file, current);
     budget.digests.set(file, createHash("sha256").update(bytes).digest("hex"));
@@ -217,7 +217,7 @@ export function readClaudeDesktopTasks({ platform = process.platform, env = proc
   const currentFiles = metadataFiles(directory, account?.accountId);
   if (files.length !== currentFiles.length || files.some((file, index) => file !== currentFiles[index])) throw new Error("metadata changed");
   for (const file of files) {
-    const current = fs.lstatSync(file);
+    const current = fs.lstatSync(file, { bigint: true });
     if (!current.isFile() || !sameVersion(current, budget.versions.get(file)) || rereadMetadata(file) !== budget.digests.get(file)) throw new Error("metadata changed");
   }
   return records;

package/src/codex-account-context.mjs

@@ -16,22 +16,22 @@ function identity(value) {
 }
 
 function readStable(file, limit) {
-  const entry = fs.lstatSync(file);
+  const entry = fs.lstatSync(file, { bigint: true });
   if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Codex account evidence must be a regular file");
   const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   try {
-    const before = fs.fstatSync(descriptor);
-    if (!before.isFile() || before.size > limit || entry.ino !== before.ino || entry.dev !== before.dev) throw new Error("Codex account evidence is invalid or exceeds its read limit");
-    const data = Buffer.alloc(before.size);
+    const before = fs.fstatSync(descriptor, { bigint: true });
+    if (!before.isFile() || before.size > BigInt(limit) || entry.ino !== before.ino || entry.dev !== before.dev) throw new Error("Codex account evidence is invalid or exceeds its read limit");
+    const data = Buffer.alloc(Number(before.size));
     let offset = 0;
     while (offset < data.length) {
       const count = fs.readSync(descriptor, data, offset, data.length - offset, offset);
       if (!count) throw new Error("Codex account evidence changed while reading; retry on the next call");
       offset += count;
     }
-    const after = fs.fstatSync(descriptor);
-    const current = fs.lstatSync(file);
-    if (!current.isFile() || current.isSymbolicLink() || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.ino !== current.ino || before.dev !== current.dev || after.size !== current.size || after.mtimeMs !== current.mtimeMs || after.ctimeMs !== current.ctimeMs) throw new Error("Codex account evidence changed while reading; retry on the next call");
+    const after = fs.fstatSync(descriptor, { bigint: true });
+    const current = fs.lstatSync(file, { bigint: true });
+    if (!current.isFile() || current.isSymbolicLink() || before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs || before.ino !== current.ino || before.dev !== current.dev || after.size !== current.size || after.mtimeNs !== current.mtimeNs || after.ctimeNs !== current.ctimeNs) throw new Error("Codex account evidence changed while reading; retry on the next call");
     return data.toString("utf8");
   } finally {
     fs.closeSync(descriptor);

package/src/codex-native-response.mjs

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { scanRollout } from "./rollout-reader.mjs";
+import { fileIdentity, sameFileIdentity } from "./file-identity.mjs";
 import { findRolloutSegments, confirmsDesktopTask, isLegacyCliSession, assertRolloutSetStable } from "./rollout-segments.mjs";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -52,9 +53,9 @@ function findRollouts(threadId, env) {
 }
 
 function pathIdentity(candidate, kind) {
-  const status = fs.lstatSync(candidate);
+  const status = fs.lstatSync(candidate, { bigint: true });
   if ((kind === "file" ? !status.isFile() : !status.isDirectory()) || status.isSymbolicLink()) throw new Error(`The Codex rollout ${kind === "file" ? "file" : "ancestor"} is not regular`);
-  return { path: candidate, dev: status.dev, ino: status.ino };
+  return { path: candidate, ...fileIdentity(status) };
 }
 
 function capturePathBoundary(file, sessions) {
@@ -77,9 +78,9 @@ function capturePathBoundary(file, sessions) {
 }
 
 function samePathBoundary(expected, current) {
-  return expected.file.dev === current.file.dev && expected.file.ino === current.file.ino &&
+  return sameFileIdentity(expected.file, current.file) &&
     expected.ancestors.length === current.ancestors.length && expected.ancestors.every((entry, index) =>
-      entry.path === current.ancestors[index].path && entry.dev === current.ancestors[index].dev && entry.ino === current.ancestors[index].ino);
+      entry.path === current.ancestors[index].path && sameFileIdentity(entry, current.ancestors[index]));
 }
 
 function readStable(found, maxBytes, { threadId, turnId, afterOffset = 0, prefixSize, dispatchOutputs, dispatchAfterOffset = afterOffset } = {}) {
@@ -136,7 +137,7 @@ function readStableOnce(found, maxBytes, { threadId, turnId, afterOffset, prefix
     },
   });
   const afterBoundary = capturePathBoundary(file, sessions);
-  if (!samePathBoundary(beforeBoundary, afterBoundary) || snapshot.identity.dev !== beforeBoundary.file.dev || snapshot.identity.ino !== beforeBoundary.file.ino) {
+  if (!samePathBoundary(beforeBoundary, afterBoundary) || !sameFileIdentity(snapshot.identity, beforeBoundary.file)) {
     throw new Error("The Codex rollout changed while reading");
   }
   return { ...snapshot, file, sessions, records, dispatches, otherTurnStarts, retainedBytes, session, latestContext, turnBeforeWatermark, prefixSha256: digest.digest("hex") };
@@ -427,7 +428,7 @@ export function resolveCodexNativeDispatchResponse(binding, { env = process.env,
       const mark = marks.find(({ file }) => file === entry.file);
       const snapshot = readStable(entry, maxRolloutBytes, { threadId, afterOffset: mark?.size ?? 0, prefixSize: mark?.size, dispatchOutputs: outputs });
       if (mark) {
-        if (snapshot.identity.dev !== mark.identity?.dev || snapshot.identity.ino !== mark.identity?.ino || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
+        if (!sameFileIdentity(snapshot.identity, mark.identity) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
         if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
       }
       validateIdentity(snapshot, threadId, cwd, desktopEvidence);
@@ -473,7 +474,7 @@ export function readCodexNativeTurnResponse({ threadId, turnId, previousTurnId,
       retainedBytes += snapshot.retainedBytes;
       if (retainedBytes > maxRolloutBytes) throw new Error("The native turn exceeds the retained-record limit across segments");
       if (mark) {
-        if (snapshot.identity.dev !== mark.identity?.dev || snapshot.identity.ino !== mark.identity?.ino || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
+        if (!sameFileIdentity(snapshot.identity, mark.identity) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
         if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
       }
       if (snapshot.turnBeforeWatermark) throw new Error("The observed turn was already present before dispatch");

package/src/desktop-account-context.mjs

@@ -8,7 +8,7 @@ const PACKAGE_NAME = /^Claude_[a-z0-9._-]+$/i;
 const MAX_CONFIG_BYTES = 1024 * 1024;
 const MAX_PACKAGES = 512;
 const MAX_ROOTS = 16;
-const VERSION_FIELDS = ["size", "mtimeMs", "ctimeMs", "ino", "dev"];
+const VERSION_FIELDS = ["size", "mtimeNs", "ctimeNs", "ino", "dev"];
 const sameVersion = (left, right) => VERSION_FIELDS.every((field) => left[field] === right[field]);
 const isMissing = (error) => error.code === "ENOENT";
 
@@ -28,7 +28,7 @@ function absoluteDirectory(value) {
 }
 
 function directoryStat(directory) {
-  const stat = fs.lstatSync(directory);
+  const stat = fs.lstatSync(directory, { bigint: true });
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("invalid directory");
   return stat;
 }
@@ -73,22 +73,22 @@ function readConfig(root) {
   }
   const file = path.join(root, "config.json");
   let initial;
-  try { initial = fs.lstatSync(file); }
+  try { initial = fs.lstatSync(file, { bigint: true }); }
   catch (error) {
     if (isMissing(error)) return { kind: "missing-config", rootStat };
     throw error;
   }
-  if (!initial.isFile() || initial.isSymbolicLink() || initial.size > MAX_CONFIG_BYTES) throw new Error("invalid config");
+  if (!initial.isFile() || initial.isSymbolicLink() || initial.size > BigInt(MAX_CONFIG_BYTES)) throw new Error("invalid config");
   const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   let bytes;
   let current;
   try {
-    const before = fs.fstatSync(descriptor);
+    const before = fs.fstatSync(descriptor, { bigint: true });
     if (!before.isFile() || !sameVersion(initial, before)) throw new Error("config changed");
-    bytes = Buffer.alloc(before.size);
+    bytes = Buffer.alloc(Number(before.size));
     if (fs.readSync(descriptor, bytes, 0, bytes.length, 0) !== bytes.length) throw new Error("short read");
-    const after = fs.fstatSync(descriptor);
-    current = fs.lstatSync(file);
+    const after = fs.fstatSync(descriptor, { bigint: true });
+    current = fs.lstatSync(file, { bigint: true });
     if (!current.isFile() || current.isSymbolicLink() || !sameVersion(before, after) || !sameVersion(after, current)) throw new Error("config changed");
   } finally {
     fs.closeSync(descriptor);

package/src/desktop-reply-receipts.mjs

@@ -4,10 +4,11 @@ import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { creationRequestHash, creationIdValid } from "./native-creation-receipts.mjs";
 import { homeDir } from "./platform.mjs";
+import { fileIdentity, sameFileIdentity } from "./file-identity.mjs";
 
 const ID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
 const LIMIT = 256 * 1024;
-const sameFile = (left, right) => ["dev", "ino", "size", "mode", "uid", "nlink", "mtimeMs", "ctimeMs"].every(field => left[field] === right[field]);
+const sameFile = (left, right) => ["dev", "ino", "size", "mode", "uid", "nlink", "mtimeNs", "ctimeNs"].every(field => left[field] === right[field]);
 
 function owner(context) {
   const { sessionId, taskId } = context?.caller ?? {};
@@ -29,11 +30,11 @@ export class DesktopReplyReceipts {
   file(id, create = false) {
     if (typeof id !== "string" || !ID.test(id)) throw new Error("Invalid reply deliveryId");
     if (create) fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
-    const info = fs.lstatSync(this.directory);
+    const info = fs.lstatSync(this.directory, { bigint: true });
     if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Unsafe reply receipt directory");
     const canonical = fs.realpathSync.native(this.directory);
-    if (this.#boundary && (this.#boundary.path !== canonical || this.#boundary.dev !== info.dev || this.#boundary.ino !== info.ino)) throw new Error("Reply receipt directory changed");
-    this.#boundary ??= { path: canonical, dev: info.dev, ino: info.ino };
+    if (this.#boundary && (this.#boundary.path !== canonical || !sameFileIdentity(this.#boundary, fileIdentity(info)))) throw new Error("Reply receipt directory changed");
+    this.#boundary ??= { path: canonical, ...fileIdentity(info) };
     return path.join(canonical, `${id}.json`);
   }
 
@@ -82,11 +83,11 @@ export class DesktopReplyReceipts {
 
   read(id, context) {
     const file = this.file(id);
-    const before = fs.lstatSync(file);
-    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > LIMIT) throw new Error("Unsafe reply receipt");
+    const before = fs.lstatSync(file, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n || before.size > BigInt(LIMIT)) throw new Error("Unsafe reply receipt");
     const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
     try {
-      const opened = fs.fstatSync(fd);
+      const opened = fs.fstatSync(fd, { bigint: true });
       if (!opened.isFile() || !sameFile(before, opened)) throw new Error("Reply receipt changed while opening");
       const buffer = Buffer.alloc(LIMIT + 1);
       let length = 0;
@@ -96,9 +97,9 @@ export class DesktopReplyReceipts {
         length += count;
         if (length > LIMIT) throw new Error("Reply receipt exceeds its read limit");
       }
-      const after = fs.fstatSync(fd);
-      const current = fs.lstatSync(this.file(id));
-      if (current.isSymbolicLink() || !sameFile(opened, after) || !sameFile(after, current) || length !== opened.size) throw new Error("Reply receipt changed while reading");
+      const after = fs.fstatSync(fd, { bigint: true });
+      const current = fs.lstatSync(this.file(id), { bigint: true });
+      if (current.isSymbolicLink() || !sameFile(opened, after) || !sameFile(after, current) || BigInt(length) !== opened.size) throw new Error("Reply receipt changed while reading");
       const receipt = JSON.parse(buffer.subarray(0, length).toString("utf8"));
       const expected = owner(context);
       if (receipt.version !== 1 || receipt.deliveryId !== id || !receipt.owner ||

package/src/file-identity.mjs

@@ -0,0 +1,13 @@
+const exact = (value) => typeof value === "bigint" ? String(value)
+  : typeof value === "string" ? (/^-?\d+$/.test(value) ? value : null)
+    : Number.isSafeInteger(value) ? String(value) : null;
+
+export function fileIdentity(stat) {
+  if (typeof stat?.dev !== "bigint" || typeof stat.ino !== "bigint") throw new TypeError("File identity requires bigint stats");
+  return { dev: String(stat.dev), ino: String(stat.ino) };
+}
+
+export function sameFileIdentity(left, right) {
+  const values = [left?.dev, left?.ino, right?.dev, right?.ino].map(exact);
+  return values.every((value) => value !== null) && values[0] === values[2] && values[1] === values[3];
+}

package/src/index.mjs

@@ -40,7 +40,7 @@ import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-o
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.6";
+const VERSION = "1.22.8";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 

package/src/install-paths.mjs

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KEG_PATH = /^(\/.*?)\/Cellar\/([^/]+)\/[^/]+(\/.*)?$/;
+
+function resolved(target) {
+  try { return fs.realpathSync.native(target); } catch { return null; }
+}
+
+/**
+ * Homebrew installs every version of a formula into its own Cellar keg and
+ * deletes the old keg on upgrade, while <prefix>/opt/<formula> is retargeted to
+ * the current one. A path that outlives this process - written into a client
+ * configuration, or watched for an upgrade - therefore has to name the opt
+ * alias. A keg path is rewritten only when the alias resolves to the same file
+ * right now; every other path is returned unchanged.
+ */
+export function stableInstallPath(target, env = process.env) {
+  if (process.platform === "win32" || typeof target !== "string") return target;
+  const match = KEG_PATH.exec(target);
+  if (!match) return target;
+  const real = resolved(target);
+  if (!real) return target;
+  const [, base, formula, rest = ""] = match;
+  const prefixes = [...new Set([env.HOMEBREW_PREFIX, base].filter((prefix) => prefix && path.isAbsolute(prefix)))];
+  for (const prefix of prefixes) {
+    const alias = path.join(prefix, "opt", formula) + rest;
+    if (resolved(alias) === real) return alias;
+  }
+  return target;
+}
+
+/** The node binary to record for later launches. */
+export function stableNodeBin(env = process.env) {
+  return stableInstallPath(process.execPath, env);
+}
+
+/**
+ * True when `entry` names the running main module, however it was reached.
+ * Node resolves the main module with the JavaScript realpath, which follows
+ * symlinks but keeps the spelling of the path as typed (case, 8.3 names,
+ * substituted drives), so that is the form compared first.
+ */
+export function isMainModule(entry, moduleUrl) {
+  if (!entry) return false;
+  const file = path.resolve(entry);
+  const module = fileURLToPath(moduleUrl);
+  let typed;
+  try { typed = fs.realpathSync(file); } catch { typed = file; }
+  if (typed === module) return true;
+  const canonical = resolved(file);
+  return canonical !== null && canonical === resolved(module);
+}

package/src/mcp-supervisor.mjs

@@ -5,7 +5,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createReleaseSnapshot, sourceRevision } from "./release-snapshot.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
+import { isMainModule, stableInstallPath } from "./install-paths.mjs";
 
+const WORKER_NODE = stableInstallPath(process.execPath);
 const ENTRIES = new Set(["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"]);
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
 const MAX_QUEUE = 256;
@@ -40,7 +42,7 @@ class Worker {
     this.retiring = false;
     this.closed = false;
     this.process = fork(path.join(release.directory, "src", entry), [], {
-      execPath: process.execPath, execArgv: [], cwd: process.cwd(), windowsHide: true,
+      execPath: WORKER_NODE, execArgv: [], cwd: process.cwd(), windowsHide: true,
       env: { ...env, CODEX_BRIDGE_WORKER: "1", CODEX_BRIDGE_STAGED: "1" },
       stdio: ["pipe", "pipe", "pipe", "ipc"], serialization: "json",
     });
@@ -133,14 +135,16 @@ class Worker {
 
 export async function runSupervisor(entry, options = {}) {
   if (!ENTRIES.has(entry)) throw new Error("Expected index.mjs, claude-bridge.mjs, or native-relay-companion.mjs");
-  const root = fs.realpathSync.native(options.root ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+  const installRoot = stableInstallPath(fs.realpathSync.native(options.root ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")));
+  const currentRoot = () => fs.realpathSync.native(installRoot);
+  const root = currentRoot();
   if (process.argv.includes("--version") || process.argv.includes("-v")) {
     process.stdout.write(`${JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version}\n`);
     return;
   }
   const log = (message) => process.stderr.write(`[bridge-supervisor] ${message}\n`);
   const output = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
-  const env = { ...process.env, CODEX_BRIDGE_SOURCE_ROOT: root };
+  const env = { ...process.env, CODEX_BRIDGE_SOURCE_ROOT: installRoot };
   const routingConfiguration = () => entry === "native-relay-companion.mjs" ? null : desktopTasksConfigured(env);
   if (entry === "native-relay-companion.mjs" && !env.CODEX_APP_TOOLS_PIPE_PATH) {
     const { resolveNativeToolsPipePath } = await import("./native-relay.mjs");
@@ -226,9 +230,10 @@ export async function runSupervisor(entry, options = {}) {
   };
   const check = async () => {
     if (switching || !ready || stopping || failure) return;
+    let source;
     let revision;
     let routing;
-    try { revision = sourceRevision(root); routing = routingConfiguration(); }
+    try { source = currentRoot(); revision = sourceRevision(source); routing = routingConfiguration(); }
     catch (error) { reason = `Installation is not ready: ${error.message}`; return; }
     if (observed !== revision || observedRouting !== routing) { observed = revision; observedRouting = routing; observedAt = Date.now(); retryAt = 0; }
     if (revision === active.release.revision && routing === active.routingConfiguration) { reason = null; return; }
@@ -241,7 +246,7 @@ export async function runSupervisor(entry, options = {}) {
     try {
       const state = await previous.control("inspect");
       if (!state.reloadable) { reason = state.reason ?? "Pending deliveries prevent a safe reload"; return; }
-      const release = createReleaseSnapshot(root, { expectedRevision: revision });
+      const release = createReleaseSnapshot(source, { expectedRevision: revision });
       candidate = spawn(release, routing);
       const initialized = await candidate.rpc("initialize", initializeParams);
       if (initialized.protocolVersion !== initializeResult.protocolVersion || JSON.stringify(initialized.capabilities) !== JSON.stringify(initializeResult.capabilities)) {
@@ -251,7 +256,7 @@ export async function runSupervisor(entry, options = {}) {
       const catalog = await candidate.rpc("tools/list", {});
       if (!Array.isArray(catalog.tools) || !catalog.tools.length || catalog.nextCursor) throw new Error("The candidate tool catalog is incomplete");
       const oldCatalog = await previous.rpc("tools/list", {});
-      if (sourceRevision(root) !== revision) throw new Error("The installation changed before activation");
+      if (sourceRevision(currentRoot()) !== revision) throw new Error("The installation changed before activation");
       if (routingConfiguration() !== routing) throw new Error("The routing configuration changed before activation");
       quiesced = true;
       const exported = await previous.control("quiesce");
@@ -339,6 +344,6 @@ export async function runSupervisor(entry, options = {}) {
   log(`supervising ${entry}; installed updates activate after pending work completes`);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(process.argv[1], import.meta.url)) {
   await runSupervisor(process.argv[2]);
 }

package/src/native-creation-receipts.mjs

@@ -3,8 +3,9 @@ import path from "node:path";
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { homeDir } from "./platform.mjs";
+import { fileIdentity, sameFileIdentity } from "./file-identity.mjs";
 
-const sameFile = (left, right) => ["dev", "ino", "size", "mode", "uid", "nlink", "mtimeMs", "ctimeMs"].every(field => left[field] === right[field]);
+const sameFile = (left, right) => ["dev", "ino", "size", "mode", "uid", "nlink", "mtimeNs", "ctimeNs"].every(field => left[field] === right[field]);
 
 export const creationIdValid = value => typeof value === "string" && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(value);
 export function creationRequestHash(args) {
@@ -31,23 +32,23 @@ export class NativeCreationReceipts {
         if (process.platform === "win32") this.#protectWindowsPrivate(this.#keyDirectory, true);
       } catch (error) { if (error.code !== "EEXIST") throw error; }
     }
-    const directory = fs.lstatSync(this.#keyDirectory);
+    const directory = fs.lstatSync(this.#keyDirectory, { bigint: true });
     const canonical = fs.realpathSync.native(this.#keyDirectory);
     if (!directory.isDirectory() || directory.isSymbolicLink() ||
-        process.platform !== "win32" && ((directory.mode & 0o077) || directory.uid !== process.getuid()) ||
-        this.#keyDirectoryBoundary && (this.#keyDirectoryBoundary.path !== canonical || this.#keyDirectoryBoundary.dev !== directory.dev || this.#keyDirectoryBoundary.ino !== directory.ino)) {
+        process.platform !== "win32" && ((directory.mode & 0o077n) || directory.uid !== BigInt(process.getuid())) ||
+        this.#keyDirectoryBoundary && (this.#keyDirectoryBoundary.path !== canonical || !sameFileIdentity(this.#keyDirectoryBoundary, fileIdentity(directory)))) {
       throw Error("Unsafe native creation authority directory");
     }
     if (process.platform === "win32" && !this.#keyDirectoryBoundary) {
       this.#assertWindowsPrivate(canonical, true);
     }
-    this.#keyDirectoryBoundary ??= { path: canonical, dev: directory.dev, ino: directory.ino };
+    this.#keyDirectoryBoundary ??= { path: canonical, ...fileIdentity(directory) };
     const file = path.join(canonical, "signing-key");
     if (create) {
       let created, createdBoundary;
       try {
         created = fs.openSync(file, "wx", 0o600);
-        createdBoundary = fs.fstatSync(created);
+        createdBoundary = fs.fstatSync(created, { bigint: true });
         if (process.platform === "win32") this.#protectWindowsPrivate(file, false);
         fs.writeFileSync(created, randomBytes(32));
         fs.fsyncSync(created);
@@ -56,32 +57,32 @@ export class NativeCreationReceipts {
         if (created !== undefined) {
           fs.closeSync(created);
           created = undefined;
-          const failed = fs.lstatSync(file);
-          if (failed.dev === createdBoundary.dev && failed.ino === createdBoundary.ino && !failed.isSymbolicLink()) fs.unlinkSync(file);
+          const failed = fs.lstatSync(file, { bigint: true });
+          if (sameFileIdentity(fileIdentity(failed), fileIdentity(createdBoundary)) && !failed.isSymbolicLink()) fs.unlinkSync(file);
         }
         if (error.code !== "EEXIST") throw error;
       }
       finally { if (created !== undefined) fs.closeSync(created); }
     }
-    const before = fs.lstatSync(file);
-    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size !== 32 ||
-        process.platform !== "win32" && ((before.mode & 0o077) || before.uid !== process.getuid())) throw Error("Unsafe native creation signing key");
+    const before = fs.lstatSync(file, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n || before.size !== 32n ||
+        process.platform !== "win32" && ((before.mode & 0o077n) || before.uid !== BigInt(process.getuid()))) throw Error("Unsafe native creation signing key");
     if (process.platform === "win32" && !this.#keyBoundary) this.#assertWindowsPrivate(file, false);
     const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
     let key;
     try {
-      const opened = fs.fstatSync(fd);
+      const opened = fs.fstatSync(fd, { bigint: true });
       if (!opened.isFile() || !sameFile(before, opened)) throw Error("Native creation signing key changed");
       const bytes = Buffer.alloc(33);
       let count = 0, read;
       while (count < bytes.length && (read = fs.readSync(fd, bytes, count, bytes.length - count, count))) count += read;
       key = bytes.subarray(0, count);
-      const after = fs.fstatSync(fd);
-      const current = fs.lstatSync(file);
+      const after = fs.fstatSync(fd, { bigint: true });
+      const current = fs.lstatSync(file, { bigint: true });
       if (key.length !== 32 || current.isSymbolicLink() || !sameFile(opened, after) || !sameFile(after, current)) throw Error("Native creation signing key changed");
     } finally { fs.closeSync(fd); }
-    if (this.#keyBoundary && (this.#keyBoundary.dev !== before.dev || this.#keyBoundary.ino !== before.ino || !timingSafeEqual(this.#key, key))) throw Error("Native creation signing key changed");
-    this.#keyBoundary ??= { dev: before.dev, ino: before.ino };
+    if (this.#keyBoundary && (!sameFileIdentity(this.#keyBoundary, fileIdentity(before)) || !timingSafeEqual(this.#key, key))) throw Error("Native creation signing key changed");
+    this.#keyBoundary ??= fileIdentity(before);
     this.#key ??= key;
     return this.#key;
   }
@@ -110,11 +111,11 @@ export class NativeCreationReceipts {
   file(id) {
     if (!creationIdValid(id)) throw Error("Invalid native creation receipt id");
     fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
-    const st = fs.lstatSync(this.directory);
+    const st = fs.lstatSync(this.directory, { bigint: true });
     if (!st.isDirectory() || st.isSymbolicLink()) throw Error("Unsafe native creation receipt directory");
     const canonical = fs.realpathSync.native(this.directory);
-    if (this.boundary && (this.boundary.path !== canonical || this.boundary.dev !== st.dev || this.boundary.ino !== st.ino)) throw Error("Native creation receipt directory changed");
-    this.boundary ??= { path: canonical, dev: st.dev, ino: st.ino };
+    if (this.boundary && (this.boundary.path !== canonical || !sameFileIdentity(this.boundary, fileIdentity(st)))) throw Error("Native creation receipt directory changed");
+    this.boundary ??= { path: canonical, ...fileIdentity(st) };
     this.directory = canonical;
     return path.join(canonical, id + ".json");
   }
@@ -122,18 +123,18 @@ export class NativeCreationReceipts {
     const file = this.file(id);
     let fd, receiptFound = false;
     try {
-      const before = fs.lstatSync(file);
+      const before = fs.lstatSync(file, { bigint: true });
       receiptFound = true;
-      if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > 1024 * 1024) throw Error("Unsafe native creation receipt");
+      if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n || before.size > 1024n * 1024n) throw Error("Unsafe native creation receipt");
       fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
-      const opened = fs.fstatSync(fd);
+      const opened = fs.fstatSync(fd, { bigint: true });
       if (!opened.isFile() || !sameFile(before, opened)) throw Error("Native creation receipt changed");
       const bytes = Buffer.alloc(1024 * 1024 + 1);
       let count = 0, n;
       while ((n = fs.readSync(fd, bytes, count, bytes.length - count, count))) { count += n; if (count > 1024 * 1024) throw Error("Oversized native creation receipt"); }
-      const after = fs.fstatSync(fd);
-      const current = fs.lstatSync(this.file(id));
-      if (current.isSymbolicLink() || !sameFile(opened, after) || !sameFile(after, current) || count !== opened.size) throw Error("Native creation receipt changed");
+      const after = fs.fstatSync(fd, { bigint: true });
+      const current = fs.lstatSync(this.file(id), { bigint: true });
+      if (current.isSymbolicLink() || !sameFile(opened, after) || !sameFile(after, current) || BigInt(count) !== opened.size) throw Error("Native creation receipt changed");
       const row = JSON.parse(bytes.subarray(0, count).toString());
       if (row.version !== 1 || row.id !== id || row.hash !== hash || creationRequestHash(row.args) !== hash ||
           !accounts || ["claude", "codex"].some(k => !accounts[k] || row.accounts?.[k] !== accounts[k]) ||

package/src/native-relay-companion.mjs

@@ -38,7 +38,7 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.6";
+const VERSION = "1.22.8";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {

package/src/platform.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
+import { stableNodeBin } from "./install-paths.mjs";
+
 const execFileAsync = promisify(execFile);
 
 export const IS_MACOS = process.platform === "darwin";
@@ -230,7 +232,7 @@ export function resolveCodexDesktopNodeBin(
   ]) {
     if (candidate && isRunnable(candidate)) return { path: candidate, source };
   }
-  return { path: process.execPath, source: "process.execPath" };
+  return { path: stableNodeBin(env), source: "process.execPath" };
 }
 
 /**
@@ -393,7 +395,7 @@ export function spawnEnv(extra = {}) {
   const systemDirs = IS_WINDOWS
     ? []
     : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
-  const merged = [path.dirname(process.execPath), ...systemDirs, ...(process.env.PATH ?? "").split(separator)]
+  const merged = [path.dirname(stableNodeBin()), ...systemDirs, ...(process.env.PATH ?? "").split(separator)]
     .filter(Boolean)
     .filter((dir, index, all) => all.indexOf(dir) === index)
     .join(separator);

package/src/project-manager-registration.mjs

@@ -4,15 +4,16 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { readRegularConfigFile, backupRegularConfigFile } from "./project-policy.mjs";
+import { stableInstallPath, stableNodeBin } from "./install-paths.mjs";
 
 // Optional UI adapter discovery. Neither bridge startup nor policy evaluation reads
 // this file. Removing the card extension or this descriptor cannot stop messaging.
-export function registerProjectManager({ policyFile, env = process.env, executable = process.execPath } = {}) {
+export function registerProjectManager({ policyFile, env = process.env, executable = stableNodeBin(env) } = {}) {
   if (!path.isAbsolute(policyFile ?? "")) throw new Error("Manager policy path must be absolute");
   const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
   const file = path.join(home, ".config", "GptClaudeBridge", "management.json");
   const value = { version: 1, node: executable,
-    script: fileURLToPath(new URL("../scripts/bridge-projects.mjs", import.meta.url)),
+    script: stableInstallPath(fileURLToPath(new URL("../scripts/bridge-projects.mjs", import.meta.url)), env),
     policyFile, configFile: env.CLAUDE_CONFIG_DIR ? path.join(env.CLAUDE_CONFIG_DIR, ".claude.json") : path.join(home, ".claude.json") };
   if (!Object.values(value).filter(v => typeof v === "string").every(v => path.isAbsolute(v))) throw new Error("Manager paths must be absolute");
   fs.mkdirSync(path.dirname(file), { recursive: true });

package/src/project-scope.mjs

@@ -15,23 +15,23 @@ function samePath(left, right) {
 }
 
 function metadata(file) {
-  const entry = fs.lstatSync(file);
-  if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 4096) throw new Error("Invalid project repository metadata");
+  const entry = fs.lstatSync(file, { bigint: true });
+  if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 4096n) throw new Error("Invalid project repository metadata");
   const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   try {
-    const before = fs.fstatSync(descriptor);
-    const fields = ["dev", "ino", "size", "mtimeMs", "ctimeMs"];
+    const before = fs.fstatSync(descriptor, { bigint: true });
+    const fields = ["dev", "ino", "size", "mtimeNs", "ctimeNs"];
     const matches = (left, right) => fields.every((field) => left[field] === right[field]);
     if (!before.isFile() || !matches(entry, before)) throw new Error("Project repository metadata changed during access");
-    const data = Buffer.alloc(before.size);
+    const data = Buffer.alloc(Number(before.size));
     let offset = 0;
     while (offset < data.length) {
       const count = fs.readSync(descriptor, data, offset, data.length - offset, offset);
       if (!count) throw new Error("Project repository metadata changed during access");
       offset += count;
     }
-    const after = fs.fstatSync(descriptor);
-    const current = fs.lstatSync(file);
+    const after = fs.fstatSync(descriptor, { bigint: true });
+    const current = fs.lstatSync(file, { bigint: true });
     if (!current.isFile() || current.isSymbolicLink() || !matches(before, after) || !matches(after, current)) throw new Error("Project repository metadata changed during access");
     return data.toString("utf8").trim();
   } finally {

package/src/rollout-reader.mjs

@@ -1,25 +1,28 @@
 import fs from "node:fs";
+import { fileIdentity } from "./file-identity.mjs";
 
 const CHUNK_BYTES = 256 * 1024;
-const VERSION_FIELDS = ["size", "mtimeMs", "ctimeMs", "ino", "dev"];
+const VERSION_FIELDS = ["size", "mtimeNs", "ctimeNs", "ino", "dev"];
 const sameVersion = (a, b) => VERSION_FIELDS.every((key) => a[key] === b[key]);
 
 // Scan the complete history, but retain at most one bounded JSONL record.
 // Skipping the middle of a rollout would miss duplicate identities or corruption.
 export function scanRollout(file, { maxRecordBytes, onRecord, onChunk = () => {} }) {
   if (!Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 1) throw new Error("The rollout record read limit is invalid");
-  const named = fs.lstatSync(file);
+  const named = fs.lstatSync(file, { bigint: true });
   if (!named.isFile() || named.isSymbolicLink()) throw new Error("The rollout is not a regular file");
   const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
   try {
-    const before = fs.fstatSync(descriptor);
+    const before = fs.fstatSync(descriptor, { bigint: true });
     if (!before.isFile()) throw new Error("The opened rollout is not a regular file");
     if (!sameVersion(named, before)) throw new Error("The rollout changed while opening");
-    if (before.size === 0) throw new Error("The rollout is empty (0 bytes)");
+    if (before.size > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("The rollout exceeds the safe size range");
+    const size = Number(before.size);
+    if (size === 0) throw new Error("The rollout is empty (0 bytes)");
     let parts = [], length = 0, start = 0, position = 0;
     const decoder = new TextDecoder("utf-8", { fatal: true });
-    while (position < before.size) {
-      const buffer = Buffer.allocUnsafe(Math.min(CHUNK_BYTES, before.size - position));
+    while (position < size) {
+      const buffer = Buffer.allocUnsafe(Math.min(CHUNK_BYTES, size - position));
       const count = fs.readSync(descriptor, buffer, 0, buffer.length, position);
       if (!count) throw new Error("The rollout changed while reading");
       const chunk = buffer.subarray(0, count);
@@ -29,7 +32,7 @@ export function scanRollout(file, { maxRecordBytes, onRecord, onChunk = () => {}
         const newline = chunk.indexOf(0x0a, offset);
         const end = newline < 0 ? count : newline;
         length += end - offset;
-        if (length > maxRecordBytes) throw new Error(`The rollout record at byte ${start} exceeds the ${maxRecordBytes}-byte per-record read limit (file: ${before.size} bytes)`);
+        if (length > maxRecordBytes) throw new Error(`The rollout record at byte ${start} exceeds the ${maxRecordBytes}-byte per-record read limit (file: ${size} bytes)`);
         parts.push(chunk.subarray(offset, end));
         if (newline < 0) break;
         if (length) {
@@ -45,14 +48,14 @@ export function scanRollout(file, { maxRecordBytes, onRecord, onChunk = () => {}
       }
       position += count;
     }
-    if (start !== before.size) throw new Error("The rollout has an incomplete final record");
-    const after = fs.fstatSync(descriptor);
-    const current = fs.lstatSync(file);
+    if (start !== size) throw new Error("The rollout has an incomplete final record");
+    const after = fs.fstatSync(descriptor, { bigint: true });
+    const current = fs.lstatSync(file, { bigint: true });
     if (!current.isFile() || current.isSymbolicLink() || !sameVersion(before, after) || !sameVersion(after, current)) {
       throw new Error("The rollout changed while reading");
     }
-    return { size: before.size, identity: { dev: before.dev, ino: before.ino },
-      version: Object.fromEntries(VERSION_FIELDS.map((key) => [key, before[key]])) };
+    return { size, identity: fileIdentity(before),
+      version: Object.fromEntries(VERSION_FIELDS.map((key) => [key, String(before[key])])) };
   } finally {
     fs.closeSync(descriptor);
   }

package/src/rollout-segments.mjs

@@ -59,7 +59,7 @@ export function assertRolloutSetStable(sessions, threadId, snapshots) {
   const files = findRolloutSegments(sessions, threadId);
   if (files.length !== snapshots.length || files.some((file, i) => file !== snapshots[i].file)) throw new Error("The rollout segment set changed while reading");
   for (const { file, version } of snapshots) {
-    const current = fs.lstatSync(file);
-    if (!current.isFile() || current.isSymbolicLink() || Object.entries(version).some(([key, value]) => current[key] !== value)) throw new Error("A rollout segment changed while reading");
+    const current = fs.lstatSync(file, { bigint: true });
+    if (!current.isFile() || current.isSymbolicLink() || Object.entries(version).some(([key, value]) => typeof value !== "string" || String(current[key]) !== value)) throw new Error("A rollout segment changed while reading");
   }
 }

package/src/sites-connector.mjs

@@ -49,24 +49,24 @@ export function validateSitesConfig(value, { allowLoopback = false } = {}) {
 }
 
 async function readPrivateJson(file, maxBytes = 2 * 1024 * 1024) {
-  const info = await fs.lstat(file);
-  if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > maxBytes) throw new Error("Private connector file is unsafe or oversized");
+  const info = await fs.lstat(file, { bigint: true });
+  if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1n || info.size > BigInt(maxBytes)) throw new Error("Private connector file is unsafe or oversized");
   const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
   try {
-    const current = await handle.stat();
-    const fields = ["dev", "ino", "size", "mtimeMs", "ctimeMs"];
+    const current = await handle.stat({ bigint: true });
+    const fields = ["dev", "ino", "size", "mtimeNs", "ctimeNs"];
     const matches = (left, right) => fields.every((field) => left[field] === right[field]);
-    if (!current.isFile() || current.nlink !== 1 || current.size > maxBytes || !matches(info, current)) throw new Error("Private connector file changed during access");
-    const data = Buffer.alloc(current.size);
+    if (!current.isFile() || current.nlink !== 1n || current.size > BigInt(maxBytes) || !matches(info, current)) throw new Error("Private connector file changed during access");
+    const data = Buffer.alloc(Number(current.size));
     let offset = 0;
     while (offset < data.length) {
       const { bytesRead } = await handle.read(data, offset, data.length - offset, offset);
       if (!bytesRead) throw new Error("Private connector file changed during access");
       offset += bytesRead;
     }
-    const after = await handle.stat();
-    const entry = await fs.lstat(file);
-    if (!entry.isFile() || entry.isSymbolicLink() || entry.nlink !== 1 || !matches(current, after) || !matches(after, entry)) throw new Error("Private connector file changed during access");
+    const after = await handle.stat({ bigint: true });
+    const entry = await fs.lstat(file, { bigint: true });
+    if (!entry.isFile() || entry.isSymbolicLink() || entry.nlink !== 1n || !matches(current, after) || !matches(after, entry)) throw new Error("Private connector file changed during access");
     return JSON.parse(data.toString("utf8"));
   } catch (error) {
     if (error.code === "ENOENT") throw new Error("Private connector file changed during access", { cause: error });