@minhspark/codex-mcp-bridge 1.13.9 → 1.15.1

package/src/claude-sender-context.mjs

@@ -0,0 +1,206 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { listClaudeSessions } from "./peer-protocol.mjs";
+import { readClaudeDesktopContext } from "./claude-desktop-context.mjs";
+
+const execute = promisify(execFile);
+const MAX_ANCESTORS = 8;
+const WINDOWS_ANCESTRY_SOURCE = `
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Globalization;
+using System.Runtime.InteropServices;
+
+public static class ClaudeProcessAncestry {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  private struct ProcessEntry {
+    public uint dwSize, cntUsage, th32ProcessID;
+    public UIntPtr th32DefaultHeapID;
+    public uint th32ModuleID, cntThreads, th32ParentProcessID;
+    public int pcPriClassBase;
+    public uint dwFlags;
+    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)] public string szExeFile;
+  }
+  public sealed class Row {
+    public uint pid;
+    public uint parentPid;
+    public string processStart;
+  }
+  [DllImport("kernel32.dll", SetLastError = true)]
+  private static extern IntPtr CreateToolhelp32Snapshot(uint flags, uint processId);
+  [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+  [return: MarshalAs(UnmanagedType.Bool)]
+  private static extern bool Process32FirstW(IntPtr snapshot, ref ProcessEntry entry);
+  [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+  [return: MarshalAs(UnmanagedType.Bool)]
+  private static extern bool Process32NextW(IntPtr snapshot, ref ProcessEntry entry);
+  [DllImport("kernel32.dll", SetLastError = true)]
+  private static extern IntPtr OpenProcess(uint access, [MarshalAs(UnmanagedType.Bool)] bool inherit, uint processId);
+  [DllImport("kernel32.dll", SetLastError = true)]
+  [return: MarshalAs(UnmanagedType.Bool)]
+  private static extern bool GetProcessTimes(IntPtr process, out long creation, out long exit, out long kernel, out long user);
+  [DllImport("kernel32.dll")]
+  [return: MarshalAs(UnmanagedType.Bool)]
+  private static extern bool CloseHandle(IntPtr handle);
+
+  public static Row[] Read(uint firstPid, int limit) {
+    var capturedAt = DateTime.UtcNow.ToFileTimeUtc();
+    var snapshot = CreateToolhelp32Snapshot(2, 0);
+    if (snapshot == new IntPtr(-1)) throw new Win32Exception(Marshal.GetLastWin32Error());
+    var parents = new Dictionary<uint, uint>();
+    try {
+      var entry = new ProcessEntry { dwSize = (uint)Marshal.SizeOf(typeof(ProcessEntry)) };
+      if (!Process32FirstW(snapshot, ref entry)) throw new Win32Exception(Marshal.GetLastWin32Error());
+      do {
+        if (parents.Count >= 65536) throw new InvalidOperationException("Process snapshot exceeds its read limit.");
+        parents.Add(entry.th32ProcessID, entry.th32ParentProcessID);
+      } while (Process32NextW(snapshot, ref entry));
+      if (Marshal.GetLastWin32Error() != 18) throw new Win32Exception(Marshal.GetLastWin32Error());
+    } finally {
+      CloseHandle(snapshot);
+    }
+    var rows = new List<Row>();
+    var seen = new HashSet<uint>();
+    var next = firstPid;
+    var childStart = capturedAt;
+    while (next > 0 && rows.Count < limit && seen.Add(next)) {
+      uint parent;
+      if (!parents.TryGetValue(next, out parent)) break;
+      var process = OpenProcess(0x1000, false, next);
+      if (process == IntPtr.Zero) break;
+      try {
+        long creation, exit, kernel, user;
+        if (!GetProcessTimes(process, out creation, out exit, out kernel, out user)
+            || creation <= 0 || creation > childStart || exit != 0) break;
+        rows.Add(new Row { pid = next, parentPid = parent, processStart = creation.ToString(CultureInfo.InvariantCulture) });
+        childStart = creation;
+        next = parent;
+      } finally {
+        CloseHandle(process);
+      }
+    }
+    return rows.ToArray();
+  }
+}`;
+
+function parseWindowsAncestry(stdout, parentPid, limit) {
+  const rows = JSON.parse(stdout.trim());
+  if (!Array.isArray(rows) || rows.length > limit) throw new Error("Invalid process ancestry response");
+  const seen = new Set();
+  let next = parentPid;
+  let childStart;
+  for (const row of rows) {
+    if (!row || typeof row !== "object" || Object.keys(row).some((key) => !["pid", "parentPid", "processStart"].includes(key))
+        || !Number.isSafeInteger(row.pid) || row.pid !== next || row.pid <= 0 || row.pid > 0xffffffff || seen.has(row.pid)
+        || !Number.isSafeInteger(row.parentPid) || row.parentPid < 0 || row.parentPid > 0xffffffff
+        || typeof row.processStart !== "string" || !/^[1-9]\d{0,18}$/.test(row.processStart)) throw new Error("Invalid process ancestry response");
+    const start = BigInt(row.processStart);
+    if (childStart !== undefined && start > childStart) throw new Error("Process ancestry contains a replaced parent");
+    childStart = start;
+    seen.add(row.pid);
+    next = row.parentPid;
+  }
+  return rows;
+}
+
+export async function readProcessAncestry({ parentPid = process.ppid, platform = process.platform, maxDepth = MAX_ANCESTORS, run = execute } = {}) {
+  if (!Number.isSafeInteger(parentPid) || parentPid <= 0 || parentPid > 0xffffffff) return [];
+  const limit = Number.isInteger(maxDepth) && maxDepth > 0 ? Math.min(maxDepth, MAX_ANCESTORS) : MAX_ANCESTORS;
+  const options = { timeout: 5000, maxBuffer: 16384, windowsHide: true };
+  if (platform === "win32") {
+    const shell = path.win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    const script = `$ErrorActionPreference='Stop'; $PSModuleAutoLoadingPreference='None'; Import-Module -Name ([IO.Path]::Combine($PSHOME,'Modules','Microsoft.PowerShell.Utility','Microsoft.PowerShell.Utility.psd1')) -ErrorAction Stop; Add-Type -TypeDefinition @'\n${WINDOWS_ANCESTRY_SOURCE}\n'@\nConvertTo-Json -InputObject @([ClaudeProcessAncestry]::Read(${parentPid},${limit})) -Compress`;
+    const { stdout } = await run(shell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], options);
+    return parseWindowsAncestry(stdout, parentPid, limit);
+  }
+  const rows = [];
+  const seen = new Set();
+  let next = parentPid;
+  const deadline = Date.now() + 5000;
+  while (next > 0 && !seen.has(next) && rows.length < limit) {
+    seen.add(next);
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new Error("process inspection deadline elapsed");
+    const { stdout } = await run("/bin/ps", ["-p", String(next), "-o", "pid=,ppid=,lstart="], {
+      ...options, timeout: remaining, env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+    });
+    const match = stdout.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+    if (!match) break;
+    const row = { pid: Number(match[1]), parentPid: Number(match[2]), processStart: match[3].trim() };
+    rows.push(row);
+    next = row.parentPid;
+  }
+  return rows;
+}
+
+function senderResult(status, reason, values = {}) {
+  return { status, pid: null, sessionId: null, taskId: null, cwd: null, processStart: null, accountFingerprint: null, reason, ...values };
+}
+
+function senderFailureCode(error) {
+  if (error?.code === "ETIMEDOUT" || (error?.killed && ["SIGTERM", "SIGKILL"].includes(error.signal))) return "INSPECTION_TIMEOUT";
+  if (error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return "OUTPUT_LIMIT";
+  if (["ENOENT", "EACCES", "EPERM"].includes(error?.code)) return error.code;
+  if (typeof error?.code === "number") return "NATIVE_EXIT";
+  if (error instanceof SyntaxError) return "INVALID_JSON";
+  return "UNAVAILABLE";
+}
+
+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";
+  try {
+    const registered = listSessions();
+    const direct = registered.some((session) => session.entrypoint === "claude-desktop" && session.alive && session.pid === parentPid);
+    stage = "process_inspection";
+    const ancestry = await readAncestry({ parentPid, maxDepth: direct ? 1 : MAX_ANCESTORS });
+    stage = "ancestry_validation";
+    if (!Array.isArray(ancestry) || !ancestry.length || ancestry.length > MAX_ANCESTORS) throw new Error("invalid ancestry");
+    const seen = new Set();
+    let expected = parentPid;
+    for (const entry of ancestry) {
+      if (!Number.isSafeInteger(entry.pid) || entry.pid !== expected || seen.has(entry.pid) ||
+          !Number.isSafeInteger(entry.parentPid) || entry.parentPid < 0 || typeof entry.processStart !== "string" || !entry.processStart.trim()) throw new Error("invalid ancestry");
+      seen.add(entry.pid);
+      expected = entry.parentPid;
+    }
+    const sessions = registered.filter((session) => session.entrypoint === "claude-desktop" && session.alive && seen.has(session.pid));
+    if (sessions.length > 1) return senderResult("ambiguous", "Multiple registered Claude Desktop sessions appear in this MCP process's ancestry.");
+    if (!sessions.length) return senderResult("unavailable", "This MCP process has no registered Claude Desktop Code session in its parent ancestry. Reconnect the bridge inside the intended existing Code task.");
+    const session = sessions[0];
+    const process = ancestry.find((entry) => entry.pid === session.pid);
+    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.");
+    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,
+      lineage: ancestry.map((entry) => ({ ...entry })),
+    });
+  } catch (error) {
+    const code = senderFailureCode(error);
+    return senderResult("unavailable", `The calling Claude process ancestry or task identity could not be verified (${stage}:${code}).`, { diagnostic: { stage, code } });
+  }
+}
+
+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";
+    throw error;
+  }
+  return sender;
+}
+
+export async function assertClaudeSenderContext(expected, options) {
+  const current = requireClaudeSenderContext(await readClaudeSenderContext(options));
+  if (["pid", "sessionId", "taskId", "cwd", "processStart", "accountFingerprint"].some((field) => current[field] !== expected?.[field])) {
+    const error = new Error("The calling Claude Desktop session or account changed while this operation was pending.");
+    error.code = "CLAUDE_SENDER_CONTEXT_CHANGED";
+    throw error;
+  }
+  return current;
+}

package/src/claude-session-router.mjs

@@ -0,0 +1,92 @@
+import { assertClaudeSessionCwd } from "./peer-protocol.mjs";
+import { preflightFailure } from "./recipient-preflight.mjs";
+
+function assertCwd(session, expectedCwd) {
+  try {
+    assertClaudeSessionCwd(session, expectedCwd);
+  } catch (error) {
+    throw preflightFailure("CLAUDE_SESSION_CWD_MISMATCH", error.message.replace(/ No message was sent\.$/, ""));
+  }
+}
+
+function taskMatches(session, expectedTaskId) {
+  return expectedTaskId === undefined || session.desktop.taskId === expectedTaskId;
+}
+
+function uniqueLiveSessions(sessions) {
+  const unique = new Map();
+  for (const session of sessions) {
+    if (!session?.alive) continue;
+    const identity = JSON.stringify([session.pid, session.sessionId, session.socket, session.processStart, session.cwd, session.entrypoint, session.name, session.bridgeSessionId]);
+    if (!unique.has(identity)) unique.set(identity, session);
+  }
+  return [...unique.values()];
+}
+
+export function resolveClaudeDesktopSession({ target, expectedCwd, expectedTaskId, sessions, account, readContext }) {
+  if (account?.status !== "verified") {
+    throw preflightFailure("CLAUDE_ACCOUNT_UNVERIFIED", account?.reason ?? "The current Claude Desktop account is not confirmed.");
+  }
+  assertCwd({ cwd: expectedCwd }, expectedCwd);
+  const needle = typeof target === "string" || typeof target === "number" ? String(target).trim() : "";
+  const automatic = needle === "auto";
+  if (!needle) throw preflightFailure("CLAUDE_SESSION_NOT_FOUND", "Provide an exact Claude Desktop session identity or target auto.");
+  const assertExpectedTaskId = () => {
+    if ((!automatic && (typeof expectedTaskId !== "string" || !expectedTaskId.trim())) ||
+        (expectedTaskId !== undefined && (typeof expectedTaskId !== "string" || !expectedTaskId.trim()))) {
+      throw preflightFailure("CLAUDE_DESKTOP_TASK_MISMATCH", "Provide expectedTaskId from the intended native Desktop task after checking its title and cwd.");
+    }
+  };
+  const live = uniqueLiveSessions(sessions ?? []);
+  const contextualize = (session) => {
+    let desktop;
+    try {
+      desktop = readContext(session, account);
+    } catch {
+      throw preflightFailure("CLAUDE_DESKTOP_TASK_UNVERIFIED", "The live session's current-account Desktop task could not be inspected consistently.");
+    }
+    return { ...session, desktop };
+  };
+  if (!automatic) {
+    const byId = live.filter((session) => String(session.pid) === needle || session.sessionId === needle);
+    const matches = byId.length ? byId : live.filter((session) => session.name === needle);
+    if (matches.length > 1) {
+      throw preflightFailure("CLAUDE_SESSION_AMBIGUOUS", "The exact target identifies multiple live sessions; use an unambiguous sessionId or pid.");
+    }
+    if (matches.length === 1) {
+      const found = matches[0];
+      if (found.entrypoint !== "claude-desktop") {
+        throw preflightFailure("CLAUDE_DESKTOP_TASK_UNVERIFIED", "The exact target is not an existing Claude Desktop Code session.");
+      }
+      assertCwd(found, expectedCwd);
+      assertExpectedTaskId();
+      const session = contextualize(found);
+      if (session.desktop?.status !== "matched") {
+        throw preflightFailure("CLAUDE_DESKTOP_TASK_UNVERIFIED", session.desktop?.reason ?? "The exact live target does not belong to a verified task in the current Claude Desktop account.");
+      }
+      if (!taskMatches(session, expectedTaskId)) {
+        throw preflightFailure("CLAUDE_DESKTOP_TASK_MISMATCH", "The exact live target belongs to a different native Claude Desktop task than expectedTaskId.");
+      }
+      return session;
+    }
+  }
+  assertExpectedTaskId();
+  const candidates = [];
+  for (const candidate of live) {
+    if (candidate.entrypoint !== "claude-desktop") continue;
+    try {
+      assertClaudeSessionCwd(candidate, expectedCwd);
+    } catch {
+      continue;
+    }
+    const session = contextualize(candidate);
+    if (session.desktop?.status === "matched" && taskMatches(session, expectedTaskId)) candidates.push(session);
+  }
+  if (candidates.length > 1) {
+    throw preflightFailure("CLAUDE_SESSION_AMBIGUOUS", "Multiple live Claude Desktop sessions match the current account and intended project/task; inspect the intended task and provide its exact identity.");
+  }
+  if (!candidates.length) {
+    throw preflightFailure("CLAUDE_SESSION_NOT_FOUND", "No live Claude Desktop session matches the current account and intended project/task. Open or reconnect the existing task in Claude Desktop.");
+  }
+  return candidates[0];
+}

package/src/codex-account-context.mjs

@@ -0,0 +1,116 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+const MAX_AUTH_BYTES = 1024 * 1024;
+const MAX_CONFIG_BYTES = 2 * 1024 * 1024;
+const MAX_TOKEN_BYTES = 128 * 1024;
+
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function identity(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 512 && value.trim() === value && !/[\u0000-\u001f\u007f]/.test(value) ? value : null;
+}
+
+function readStable(file, limit) {
+  const entry = fs.lstatSync(file);
+  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);
+    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");
+    return data.toString("utf8");
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function configAllowsFile(file) {
+  let text;
+  try {
+    text = readStable(file, MAX_CONFIG_BYTES);
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw new Error("Codex credential storage configuration could not be verified");
+  }
+  for (const line of text.split(/\r?\n/)) {
+    let quote = null;
+    let end = line.length;
+    for (let index = 0; index < line.length; index++) {
+      if (quote) {
+        if (quote === '"' && line[index] === "\\") index++;
+        else if (line[index] === quote) quote = null;
+      } else if (line[index] === '"' || line[index] === "'") quote = line[index];
+      else if (line[index] === "#") { end = index; break; }
+    }
+    const content = line.slice(0, end);
+    if (!/\bcli_auth_credentials_store\b/.test(content)) continue;
+    const assignments = [...content.matchAll(/(?:^|[\s{,])(?:cli_auth_credentials_store|"cli_auth_credentials_store"|'cli_auth_credentials_store')\s*=\s*(?:"([^"\\]*)"|'([^']*)')(?=\s*(?:[,}]|$))/g)];
+    if (!assignments.length || assignments.some((match) => (match[1] ?? match[2]) !== "file")) throw new Error("Codex account detection requires verified file credential storage; keyring, auto, ephemeral, or ambiguous storage is unavailable");
+  }
+}
+
+function tokenIdentity(token) {
+  if (typeof token !== "string" || token.length > MAX_TOKEN_BYTES) throw new Error("Codex account evidence has no usable user identity token");
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts.some((part) => !/^[A-Za-z0-9_-]+$/.test(part))) throw new Error("Codex account user identity is malformed; retry on the next call");
+  let claims;
+  try {
+    claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+  } catch {
+    throw new Error("Codex account user identity is malformed; retry on the next call");
+  }
+  if (!object(claims)) throw new Error("Codex account user identity is unavailable");
+  const auth = object(claims["https://api.openai.com/auth"]) ? claims["https://api.openai.com/auth"] : {};
+  return { userId: identity(auth.chatgpt_user_id) ?? identity(claims.sub), accountId: identity(auth.chatgpt_account_id) };
+}
+
+export function readCodexAccountContext({ env = process.env, root } = {}) {
+  let source = null;
+  const result = (status, reason, values = {}) => ({ status, provider: "codex", accountId: null, userId: null, fingerprint: null, source, reason, ...values });
+  try {
+    const home = root ?? env.CODEX_HOME ?? path.join(env.HOME || env.USERPROFILE || os.homedir(), ".codex");
+    if (typeof home !== "string" || !path.isAbsolute(home)) return result("unavailable", "The configured Codex home must be absolute");
+    source = path.join(home, "auth.json");
+    configAllowsFile(path.join(home, "config.toml"));
+    let text;
+    try {
+      text = readStable(source, MAX_AUTH_BYTES);
+    } catch (error) {
+      if (error.code === "ENOENT") return result("signed_out", "Codex has no stored login identity; retry after sign-in completes");
+      throw error;
+    }
+    let auth;
+    try {
+      auth = JSON.parse(text);
+    } catch {
+      return result("unavailable", "Codex account evidence is incomplete or malformed; retry on the next call");
+    }
+    if (!object(auth)) return result("unavailable", "Codex account evidence is not an object");
+    if (auth.auth_mode !== "chatgpt") return result("unavailable", "Codex account detection requires a stored ChatGPT login; external tokens and other authentication modes are unavailable");
+    const accountId = identity(auth.tokens?.account_id);
+    if (!accountId) return result("unavailable", "Codex account evidence has no stable account ID; retry after sign-in completes");
+    const decoded = tokenIdentity(auth.tokens?.id_token);
+    if (!decoded.userId) return result("unavailable", "Codex account evidence has no stable user ID; no identity was inferred");
+    if (decoded.accountId && decoded.accountId !== accountId) return result("unavailable", "Codex account and user identity evidence disagree; retry on the next call");
+    configAllowsFile(path.join(home, "config.toml"));
+    if (readStable(source, MAX_AUTH_BYTES) !== text) return result("unavailable", "Codex account evidence changed during identity verification; retry on the next call");
+    const fingerprint = createHash("sha256").update(JSON.stringify(["codex", accountId, decoded.userId])).digest("hex");
+    return result("verified", "Stored Codex ChatGPT account and user identity were read consistently", { accountId, userId: decoded.userId, fingerprint });
+  } catch (error) {
+    return result("unavailable", error.code ? "Codex account evidence could not be read; retry on the next call" : error.message);
+  }
+}

package/src/codex-bridge-launcher.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runSupervisor } from "./mcp-supervisor.mjs";
+await runSupervisor("index.mjs");

package/src/codex-mcp-registration.mjs

@@ -1,13 +1,23 @@
-export function codexMcpRegistration({ name, existing, node, entry, env, desktopOnly }) {
+export function stdioMcpRegistration({ name, existing, node, entry, entryArgs = [], envOverrides = {} }) {
   if (existing) {
     const customized = ["enabled_tools", "disabled_tools", "startup_timeout_sec", "tool_timeout_sec", "disabled_reason"]
       .some((key) => existing[key] != null && (!Array.isArray(existing[key]) || existing[key].length > 0));
     if (existing.enabled === false || customized || existing.transport?.type !== "stdio" || existing.transport?.cwd || existing.transport?.env_vars?.length) {
-      throw new Error("The existing MCP entry has custom access, timeout, or transport settings. Keep that entry and update only its command/args using Codex settings; the installer will not remove or reset it.");
+      throw new Error(`The existing MCP entry has custom access, timeout, or transport settings. The installer will not remove or reset it. Keep those settings and update only command=${JSON.stringify(node)} and args=${JSON.stringify([entry, ...entryArgs])} in the existing entry, then reconnect that MCP server once.`);
     }
   }
+  const values = { ...existing?.transport?.env, ...envOverrides };
+  const args = ["mcp", "add", name];
+  for (const [key, value] of Object.entries(values).sort(([a], [b]) => a.localeCompare(b))) {
+    if (typeof value !== "string") throw new Error(`MCP environment value ${key} must be a string`);
+    args.push("--env", `${key}=${value}`);
+  }
+  return { args: [...args, "--", node, entry, ...entryArgs], environment: values, environmentKeys: Object.keys(values).sort() };
+}
+
+export function codexMcpRegistration({ name, existing, node, entry, entryArgs = [], env, desktopOnly }) {
   const values = { ...existing?.transport?.env };
-  for (const key of ["CLAUDE_BRIDGE_PEER_NAME", "CLAUDE_BRIDGE_PERMISSION_MODE", "CODEX_BRIDGE_DESKTOP_TASKS"]) {
+  for (const key of ["CLAUDE_BRIDGE_PEER_NAME", "CLAUDE_BRIDGE_PERMISSION_MODE", "CODEX_BRIDGE_DESKTOP_TASKS", "CLAUDE_DESKTOP_USER_DATA"]) {
     if (env[key] !== undefined) values[key] = env[key];
   }
   values.CODEX_BRIDGE_DESKTOP_TASKS ??= desktopOnly ? "1" : "0";
@@ -16,10 +26,5 @@ export function codexMcpRegistration({ name, existing, node, entry, env, desktop
     throw new Error("CLAUDE_BRIDGE_PERMISSION_MODE must be bypass or prompting; never infer it from the recipient");
   }
   if (values.CODEX_BRIDGE_DESKTOP_TASKS === "1") values.CODEX_BRIDGE_AUTOSTART = "0";
-  const args = ["mcp", "add", name];
-  for (const [key, value] of Object.entries(values).sort(([a], [b]) => a.localeCompare(b))) {
-    if (typeof value !== "string") throw new Error(`MCP environment value ${key} must be a string`);
-    args.push("--env", `${key}=${value}`);
-  }
-  return { args: [...args, "--", node, entry], environmentKeys: Object.keys(values).sort() };
+  return stdioMcpRegistration({ name, existing, node, entry, entryArgs, envOverrides: values });
 }

package/src/desktop-account-context.mjs

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const ACCOUNT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+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 sameVersion = (left, right) => VERSION_FIELDS.every((field) => left[field] === right[field]);
+const isMissing = (error) => error.code === "ENOENT";
+
+function result(status, reason, root = null, accountId = null) {
+  return {
+    status,
+    accountId,
+    fingerprint: accountId ? createHash("sha256").update(`claude-desktop\0${accountId}`).digest("hex") : null,
+    root,
+    reason,
+  };
+}
+
+function absoluteDirectory(value) {
+  if (typeof value !== "string" || !value || !path.isAbsolute(value)) throw new Error("invalid root");
+  return path.resolve(value);
+}
+
+function directoryStat(directory) {
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("invalid directory");
+  return stat;
+}
+
+function candidateRoots({ platform, env, root }) {
+  const selected = root !== undefined ? root : env.CLAUDE_DESKTOP_USER_DATA;
+  if (selected !== undefined) return [absoluteDirectory(selected)];
+  const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
+  const config = platform === "darwin" ? path.join(home, "Library", "Application Support")
+    : platform === "win32" ? env.APPDATA || path.join(home, "AppData", "Roaming")
+      : env.XDG_CONFIG_HOME || path.join(home, ".config");
+  const roots = [absoluteDirectory(path.join(config, "Claude"))];
+  if (platform === "win32") {
+    const packages = absoluteDirectory(path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "Packages"));
+    let entries;
+    try {
+      directoryStat(packages);
+      entries = fs.readdirSync(packages, { withFileTypes: true });
+    } catch (error) {
+      if (!isMissing(error)) throw error;
+      entries = [];
+    }
+    if (entries.length > MAX_PACKAGES) throw new Error("package scan limit");
+    for (const entry of entries) {
+      if (!PACKAGE_NAME.test(entry.name)) continue;
+      const packageRoot = path.join(packages, entry.name);
+      directoryStat(packageRoot);
+      roots.push(path.join(packageRoot, "LocalCache", "Roaming", "Claude"));
+    }
+  }
+  const unique = [...new Map(roots.map((value) => [platform === "win32" ? value.toLowerCase() : value, value])).values()].sort();
+  if (unique.length > MAX_ROOTS) throw new Error("root scan limit");
+  return unique;
+}
+
+function readConfig(root) {
+  let rootStat;
+  try { rootStat = directoryStat(root); }
+  catch (error) {
+    if (isMissing(error)) return { kind: "missing-root" };
+    throw error;
+  }
+  const file = path.join(root, "config.json");
+  let initial;
+  try { initial = fs.lstatSync(file); }
+  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");
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  let bytes;
+  let current;
+  try {
+    const before = fs.fstatSync(descriptor);
+    if (!before.isFile() || !sameVersion(initial, before)) throw new Error("config changed");
+    bytes = Buffer.alloc(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);
+    if (!current.isFile() || current.isSymbolicLink() || !sameVersion(before, after) || !sameVersion(after, current)) throw new Error("config changed");
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  if (!sameVersion(rootStat, directoryStat(root))) throw new Error("root changed");
+  const config = JSON.parse(bytes.toString("utf8"));
+  if (!config || typeof config !== "object" || Array.isArray(config)) throw new Error("invalid config");
+  const hasAccount = Object.hasOwn(config, "lastKnownAccountUuid");
+  const hasSignedIn = Object.hasOwn(config, "windowSizeWasSignedIn");
+  if (!hasAccount && !hasSignedIn) return { kind: "unrelated", rootStat, fileStat: current, bytes };
+  if (!hasAccount || !hasSignedIn || typeof config.windowSizeWasSignedIn !== "boolean" ||
+      typeof config.lastKnownAccountUuid !== "string" || !ACCOUNT_ID.test(config.lastKnownAccountUuid)) throw new Error("invalid account state");
+  return {
+    kind: config.windowSizeWasSignedIn ? "verified" : "signed_out",
+    accountId: config.lastKnownAccountUuid.toLowerCase(),
+    rootStat,
+    fileStat: current,
+    bytes,
+  };
+}
+
+function sameSnapshot(left, right) {
+  return left.kind === right.kind &&
+    (!left.rootStat || right.rootStat && sameVersion(left.rootStat, right.rootStat)) &&
+    (!left.fileStat || right.fileStat && sameVersion(left.fileStat, right.fileStat)) &&
+    (!left.bytes || right.bytes && left.bytes.equals(right.bytes));
+}
+
+export function readClaudeAccountContext({ platform = process.platform, env = process.env, root } = {}) {
+  let roots;
+  try {
+    roots = candidateRoots({ platform, env, root });
+    const snapshots = roots.map((candidate) => readConfig(candidate));
+    const currentRoots = candidateRoots({ platform, env, root });
+    if (roots.length !== currentRoots.length || roots.some((candidate, index) => candidate !== currentRoots[index]) ||
+        roots.some((candidate, index) => !sameSnapshot(snapshots[index], readConfig(candidate)))) {
+      return result("unavailable", "Claude Desktop account state changed during inspection; inspect the existing session again.", roots.length === 1 ? roots[0] : null);
+    }
+    const credible = snapshots.map((snapshot, index) => ({ ...snapshot, root: roots[index] }))
+      .filter((snapshot) => snapshot.kind === "verified" || snapshot.kind === "signed_out");
+    if (credible.length > 1) return result("ambiguous", "Multiple Claude Desktop data roots contain account state; no current account or metadata root is selected.");
+    if (!credible.length) return result("unavailable", "Claude Desktop account state is unavailable; no current account is confirmed.", roots.length === 1 ? roots[0] : null);
+    const selected = credible[0];
+    if (selected.kind === "signed_out") return result("signed_out", "Claude Desktop's persisted account state reports signed out; no destination is confirmed.", selected.root);
+    return result("verified", "Claude Desktop's persisted signed-in account state identifies this account; destination session identity still requires verification.", selected.root, selected.accountId);
+  } catch {
+    return result("unavailable", "Claude Desktop account state could not be read completely and consistently; no current account is confirmed.", roots?.length === 1 ? roots[0] : null);
+  }
+}

package/src/desktop-task-receipts.mjs

@@ -5,7 +5,7 @@ import path from "node:path";
 import { homeDir } from "./platform.mjs";
 
 const HASH = /^[a-f0-9]{64}$/;
-const FIELDS = new Set(["version", "key", "cwd", "promptHash", "state", "startedAt", "threadId", "projectId", "projectName", "name"]);
+const FIELDS = new Set(["version", "key", "cwd", "promptHash", "state", "startedAt", "threadId", "projectId", "projectName", "name", "accountContext"]);
 const digest = (value) => createHash("sha256").update(value).digest("hex");
 const normalizedName = (name) => name?.normalize("NFC").trim().replace(/\s+/g, " ");
 const canonicalCwd = (cwd) => process.platform === "win32" ? path.normalize(cwd).toLowerCase() : path.normalize(cwd);
@@ -26,6 +26,8 @@ function validateReceipt(key, receipt) {
     && nonemptyString(receipt.cwd) && path.isAbsolute(receipt.cwd)
     && ["pending", "unknown", "known"].includes(receipt.state)
     && Number.isSafeInteger(receipt.startedAt) && receipt.startedAt >= 0
+    && (receipt.accountContext === undefined || receipt.accountContext && typeof receipt.accountContext === "object" && !Array.isArray(receipt.accountContext)
+      && Object.keys(receipt.accountContext).length === 2 && ["claude", "codex"].every((provider) => typeof receipt.accountContext[provider] === "string" && HASH.test(receipt.accountContext[provider])))
     && ["threadId", "projectId", "projectName", "name"].every((field) => receipt[field] === undefined || nonemptyString(receipt[field]))
     && (receipt.state !== "known" || nonemptyString(receipt.threadId));
   if (!valid) throw unsafeReceipt(key);