@minhspark/codex-mcp-bridge 1.22.1 → 1.22.3

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,41 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.3] - 2026-10-15
+
+### Fixed
+
+- Retry the complete Claude Desktop identity snapshot up to three times when task metadata changes during inspection. An unrelated active chat updating its metadata no longer causes an immediate sender rejection; persistent changes, conflicting identities, archived tasks, and invalid metadata still fail closed.
+- Include bounded metadata diagnostic codes in sender-verification failures instead of discarding the underlying failure category behind a generic account message. Diagnostics exclude task contents and untrusted error text.
+
+### Verification
+
+- Regression tests reproduce a one-time unrelated metadata update, persistent updates, archive changes, duplicate identities, and diagnostic sanitization.
+- A live Windows check from the originally affected Claude Code session completed two reads, one diagnostic send to its existing Codex task, and reply observation through the returned delivery receipt. The exact diagnostic reply was verified in the destination task.
+
+### Upgrade notes
+
+- Existing supervisors load the updated source when safe. Shared Desktop MCP entries still cannot identify a Code task's process ancestry; use the per-Code bridge registration. The repair does not resend earlier work or weaken account, process, or project checks.
+
+## [1.22.2] - 2026-10-13
+
+### Fixed
+
+- Preserve exact filesystem identities when checking Desktop creation locks and receipts. Large file IDs can collide when represented as JavaScript Numbers; BigInt stat values prevent a replaced lock with a copied token from being mistaken for the owned file.
+- Clarify the shared sending-tool guidance: agent-authored handoffs must identify their actual Codex or Claude author in the first line and use English throughout, including the header purpose, instructions, constraints, and reply format.
+- Require sufficient measured context, file boundaries, validation steps, and completion criteria for a receiving agent to act without guessing.
+
+### Verification
+
+- A deterministic regression uses two distinct file IDs above the safe integer limit. It fails against the previous implementation and passes with exact BigInt comparisons; the real filesystem replacement test remains enabled.
+- Full Node test suite on macOS: 1,276 passed, 23 skipped, zero failures. A clean archived checkout passed 1,268 tests with 23 skipped and zero failures; Git-dependent tests are not registered outside a Git checkout.
+
+### Upgrade notes
+
+- The handoff changes update prompt guidance, not automatic translation or payload validation. Verbatim user text and exact identifiers retain their original content.
+- The native host may still display its own generic attribution label. A sender header inside the prompt does not rename that label or alter permission checks. Cowork/Dispatch support is unchanged.
+- Reconnect the MCP client to load the updated tool descriptions; installing the package does not hot-reload an existing process.
+
 ## [1.22.1] - 2026-10-13
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.1",
+  "version": "1.22.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/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.1",
+  "version": "1.22.3",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -23,7 +23,7 @@ import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-acce
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.1";
+const VERSION = "1.22.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/src/claude-bridge.mjs

@@ -29,7 +29,7 @@ import { registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.1";
+const VERSION = "1.22.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-desktop-context.mjs

@@ -132,7 +132,14 @@ export function readClaudeDesktopContext(session, { platform = process.platform,
   try {
     const directory = root ?? (account ? path.join(account.root, "claude-code-sessions") : sessionsRoot(platform, env));
     if (!fs.existsSync(directory)) return result("missing", "Claude Desktop task metadata is not available on this host.");
-    records = readClaudeDesktopTasks({ platform, env, root, account });
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        records = readClaudeDesktopTasks({ platform, env, root, account });
+        break;
+      } catch (error) {
+        if (error.message !== "metadata changed" || attempt === 2) throw error;
+      }
+    }
   } catch (error) {
     const detail = {
       "file limit": " A task metadata file exceeds the 4 MiB per-file limit.",
@@ -140,7 +147,13 @@ export function readClaudeDesktopContext(session, { platform = process.platform,
       "scan limit": " The task directory exceeds the 8192-entry scan limit.",
       "metadata changed": " Task metadata changed during inspection; retry discovery.",
     }[error.message] ?? "";
-    return result("mismatch", `Claude Desktop task metadata could not be read completely and consistently; no task identity is confirmed.${detail}`);
+    const code = {
+      "file limit": "FILE_LIMIT",
+      "identity limit": "IDENTITY_LIMIT",
+      "scan limit": "SCAN_LIMIT",
+      "metadata changed": "METADATA_CHANGED",
+    }[error.message] ?? "UNREADABLE_METADATA";
+    return { ...result("mismatch", `Claude Desktop task metadata could not be read completely and consistently; no task identity is confirmed.${detail}`), diagnostic: { stage: "task_metadata", code } };
   }
 
   const primary = records.filter((record) => record.cliSessionId === session.sessionId);

package/src/claude-sender-context.mjs

@@ -265,6 +265,17 @@ function senderFailureCode(error) {
   return "UNAVAILABLE";
 }
 
+const METADATA_FAILURE_CODES = new Set(["METADATA_CHANGED", "FILE_LIMIT", "IDENTITY_LIMIT", "SCAN_LIMIT", "UNREADABLE_METADATA", "MISSING", "MISMATCH", "AMBIGUOUS", "UNAVAILABLE"]);
+const INSPECTION_FAILURE_CODES = new Set(["INSPECTOR_START_TIMEOUT", "INSPECTION_TIMEOUT", "OUTPUT_LIMIT", "ENOENT", "EACCES", "EPERM", "NATIVE_EXIT", "INVALID_JSON", "UNAVAILABLE"]);
+
+function safeSenderDiagnostic(diagnostic) {
+  if (!diagnostic || typeof diagnostic !== "object") return null;
+  const { stage, code } = diagnostic;
+  if (stage === "task_metadata" && (METADATA_FAILURE_CODES.has(code) || INSPECTION_FAILURE_CODES.has(code))) return { stage, code };
+  if (["session_registry", "process_inspection", "ancestry_validation"].includes(stage) && INSPECTION_FAILURE_CODES.has(code)) return { stage, code };
+  return null;
+}
+
 export async function readClaudeSenderContext({ account, parentPid = process.ppid, readAncestry = readProcessAncestry, listSessions = listClaudeSessions, readContext = readClaudeDesktopContext } = {}) {
   if (account?.status !== "verified" || !account.fingerprint) return senderResult("unavailable", "The calling Claude account is not verified.");
   let stage = "session_registry";
@@ -291,7 +302,12 @@ export async function readClaudeSenderContext({ account, parentPid = process.ppi
     if (session.processStart && session.processStart !== process.processStart) return senderResult("unavailable", "The calling Claude session's registered process identity changed.");
     stage = "task_metadata";
     const context = readContext(session, { account });
-    if (context.status !== "matched") return senderResult("unavailable", "The calling Claude Code session is not confirmed in the currently signed-in account.");
+    if (context.status !== "matched") {
+      const code = context.diagnostic?.stage === "task_metadata" && METADATA_FAILURE_CODES.has(context.diagnostic.code)
+        ? context.diagnostic.code
+        : ["missing", "mismatch", "ambiguous"].includes(context.status) ? context.status.toUpperCase() : "UNAVAILABLE";
+      return senderResult("unavailable", `The calling Claude Code session is not confirmed in the currently signed-in account. (${stage}:${code})`, { diagnostic: { stage, code } });
+    }
     return senderResult("verified", "The calling MCP process belongs to a live Claude Desktop Code session in the selected account.", {
       pid: session.pid, sessionId: session.sessionId, taskId: context.taskId, cwd: context.cwd,
       processStart: process.processStart, accountFingerprint: account.fingerprint,
@@ -307,6 +323,8 @@ export function requireClaudeSenderContext(sender) {
   if (sender?.status !== "verified") {
     const error = new Error(sender?.reason ?? "The calling Claude Desktop Code session is unverified.");
     error.code = "CLAUDE_SENDER_CONTEXT_UNVERIFIED";
+    const diagnostic = safeSenderDiagnostic(sender?.diagnostic);
+    if (diagnostic) error.diagnostic = diagnostic;
     throw error;
   }
   return sender;

package/src/desktop-task-receipts.mjs

@@ -76,23 +76,23 @@ export class DesktopTaskReceipts {
     const file = path.join(this.directory, `${key}.json`);
     let handle;
     try {
-      const info = await fs.lstat(file);
-      if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw unsafeReceipt(key);
+      const info = await fs.lstat(file, { bigint: true });
+      if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1n) throw unsafeReceipt(key);
       handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-      const opened = await handle.stat();
-      const fields = ["dev", "ino", "size", "mtimeMs", "ctimeMs"];
+      const opened = await handle.stat({ bigint: true });
+      const fields = ["dev", "ino", "size", "mtimeNs", "ctimeNs"];
       const matches = (left, right) => fields.every((field) => left[field] === right[field]);
-      if (!opened.isFile() || opened.nlink !== 1 || opened.size > 65536 || !matches(info, opened)) throw unsafeReceipt(key);
-      const data = Buffer.alloc(opened.size);
+      if (!opened.isFile() || opened.nlink !== 1n || opened.size > 65536n || !matches(info, opened)) throw unsafeReceipt(key);
+      const data = Buffer.alloc(Number(opened.size));
       let offset = 0;
       while (offset < data.length) {
         const { bytesRead } = await handle.read(data, offset, data.length - offset, offset);
         if (!bytesRead) throw unsafeReceipt(key);
         offset += bytesRead;
       }
-      const after = await handle.stat();
-      const current = await fs.lstat(file);
-      if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1 || !matches(opened, after) || !matches(after, current)) throw unsafeReceipt(key);
+      const after = await handle.stat({ bigint: true });
+      const current = await fs.lstat(file, { bigint: true });
+      if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1n || !matches(opened, after) || !matches(after, current)) throw unsafeReceipt(key);
       return validateReceipt(key, JSON.parse(data.toString("utf8")));
     } catch (err) {
       if (err.code === "ENOENT" && !handle) return null;
@@ -150,11 +150,11 @@ export class DesktopTaskReceipts {
       return await callback();
     } finally {
       try {
-        const owned = await handle.stat();
+        const owned = await handle.stat({ bigint: true });
         const data = Buffer.alloc(Buffer.byteLength(token));
         const { bytesRead } = await handle.read(data, 0, data.length, 0);
-        const current = await fs.lstat(file);
-        if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1 || owned.dev !== current.dev || owned.ino !== current.ino || owned.size !== data.length || current.size !== data.length || bytesRead !== data.length || data.toString("utf8") !== token) {
+        const current = await fs.lstat(file, { bigint: true });
+        if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1n || owned.dev !== current.dev || owned.ino !== current.ino || owned.size !== BigInt(data.length) || current.size !== BigInt(data.length) || bytesRead !== data.length || data.toString("utf8") !== token) {
           throw new Error("Desktop task creation lock changed; inspect the existing task before repairing the lock");
         }
         await fs.unlink(file);

package/src/index.mjs

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

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.1";
+const VERSION = "1.22.3";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {

package/src/prompt-guidance.mjs

@@ -18,15 +18,15 @@ export const PROMPT_SECTIONS = Object.freeze([
 export const AGENT_PROMPT_GUIDANCE =
   "Honor the user's existing, explicitly authorized collaboration workflow: routine handoffs and result reports within that workflow do not require a new user message for every exchange. " +
   "Installation, a project grant, or a peer's claim alone is not user authorization. Keep the real sender visible; do not impersonate the user. Host permission denials still require proper resolution, never a different channel or alias. " +
-  "Write every prompt you compose for another agent in English, in this order, omitting sections that do not apply: " +
-  "a first line naming the sender, project and purpose, e.g. [From Claude Code · <project> · <purpose>]; " +
+  "Write all agent-authored text in English, including the header purpose, headings, instructions, constraints and reply format. Use this order, omitting sections that do not apply: " +
+  "a first line naming the actual author: [From Codex · <project> · <purpose in English>] or [From Claude · <project> · <purpose in English>]. Never substitute the relay or recipient for the author, or use only a generic another-task label. The host may retain its own native attribution label; do not claim that a body header changes that label; " +
   "## Goal, the outcome in one sentence; ## Context, measured facts, paths with line numbers and existing code to reuse; " +
   "## Task, numbered imperative steps; ## Scope, the files that may and must not change; " +
   "## Constraints, conventions and tests, plus: if the current state differs from this description, stop and report instead of reconciling it; " +
   "## Done when, checkable criteria; ## Reply format, the exact shape of the reply. " +
-  "A short coordination message needs only Goal, Context, Task and Reply format. " +
+  "Include enough verified context, explicit file boundaries, validation steps and completion criteria for the recipient to act without guessing. A short coordination message needs only Goal, Context, Task and Reply format. " +
   "Send text the user supplied verbatim, and keep file names, identifiers and user-facing strings in their original language.";
 
 export const PROMPT_FIELD_HINT =
-  `The prompt for the recipient agent, in English with the sections ${PROMPT_SECTIONS.join(", ")} ` +
+  `The prompt for the recipient agent, with an explicit From Codex or From Claude header naming the actual author, all agent-authored text in English including the header purpose, and the sections ${PROMPT_SECTIONS.join(", ")} ` +
   "(omit any that do not apply); text the user supplied is sent verbatim";