@minhspark/codex-mcp-bridge 1.15.1 → 1.16.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-09-14
+
+### Added
+
+- Prepare a separate native Claude Desktop Code conversation in an existing project with `start_claude_session`, then verify its new task identity and exact initial prompt through `read_claude_creation`. The official Desktop link requires user confirmation and Send; opening a composer is reported as `awaiting_user`, never as completed creation.
+- Retain bounded creation receipts across automatic reload, prevent duplicate or competing composer launches, reject old tasks resumed as new processes, and allow explicit cancellation through `abandon_claude_creation`. Existing clients can use `send_to_claude_session` with `target: "new"` and inspect its request ID through `read_claude_delivery`.
+- Detect a submitted new conversation that remains in No folder as `awaiting_project_confirmation`, preserve its native identity, and verify completion after the user moves it to the requested project. Recognize Claude Desktop's initial No folder banner without accepting a different or later user prompt.
+
+## [1.15.2] - 2026-09-14
+
+### Fixed
+
+- Restore Codex-to-Claude Desktop messaging on Windows with Claude Code 2.1.270, which advertises its process FILETIME as `procStart` instead of `procStartFt`. Normalize both fields in session records and authentication keys, retain live process verification, and reject malformed or conflicting identities.
+- Advertise both Windows identity fields on bridge peer records and authentication keys so current Claude sessions and older peers can validate the same endpoint without restarting Desktop.
+
 ## [1.15.1] - 2026-09-14
 
 ### Fixed

package/README.md

@@ -400,9 +400,18 @@ Under `owned`, a thread a human opened is **unreachable rather than merely restr
 
 ## Tools — `claude-bridge` (runs inside Codex)
 
+When the user explicitly requests a separate conversation, call `start_claude_session` with a stable `requestId`, exact existing project `cwd`, and initial `prompt`. This uses the [official Claude Desktop Code link](https://support.claude.com/en/articles/14729294-open-claude-desktop-with-a-link), which prefills the composer but requires the user to confirm the folder and press Send. It is not unattended session creation. The bridge never patches Desktop, writes session metadata, starts a substitute CLI, or silently sends into an old conversation.
+
+Retain the creation receipt and call `read_claude_creation`. Only `created` identifies a verified new native task and live session; it does not claim an assistant reply. Once created, use the returned exact session and task IDs with the existing send/read tools. One pending request reserves the current account's composer, including across different projects. If the user cancels it, `abandon_claude_creation` releases that reservation without discarding evidence or claiming that the old composer was closed. Compatible automatic reload preserves creation receipts; after a full restart, an unknown request is not proof that creation failed.
+
+Clients whose tool list has not refreshed can use `send_to_claude_session` with `target: "new"`, `expectedCwd`, and `message`. It returns a creation receipt instead of a message receipt. Repeated calls with the same payload in the same verified Codex turn reuse that request; inspect its 64-character `requestId` with `read_claude_delivery`. A later explicit new-session request in a new turn has a separate identity.
+
 | Tool | What it does | Hints |
 |---|---|---|
 | `list_claude_sessions` | Lists Claude Code sessions running on this machine (name, pid, sessionId, cwd, entrypoint). | read-only |
+| `start_claude_session` | Opens the official Claude Code composer for a new conversation in an existing project. Returns `awaiting_user`; the user confirms the folder and presses Send in Claude Desktop. Reuse the same `requestId` to avoid reopening. | writes |
+| `read_claude_creation` | Verifies a creation request using a new native task ID, exact initial user prompt, account, cwd, and live process identity. Reports `awaiting_project_confirmation` if the prompt arrived in No folder or another directory; only the requested project can become `created`. A resumed old task never counts as newly created. | read-only |
+| `abandon_claude_creation` | Releases a pending composer reservation only when the user cancels it. Retains the receipt; does not close Desktop or prove the prompt was never submitted. | writes |
 | `send_to_claude_session` | Sends to a Claude inbox and waits for a correlated reply. Receipt statuses distinguish `reply_received`, `sent_unconfirmed`, `reply_timeout`, and receiver policy outcomes such as `held` or `refused`. `waitSec: 0` sends without waiting for confirmation. Prefer an exact `sessionId` because session names can change. | destructive |
 | `read_claude_delivery` | Inspects the latest recipient receipt or correlated reply by original message ID without resending or clearing the inbox. Receipts belong to this MCP process; an unknown ID after reconnect never proves non-delivery. | read-only |
 | `read_claude_inbox` | Reads and consumes the oldest requested page of messages, including late replies, preserving unread messages. Includes reply forwarding status. | destructive |

package/package.json

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

package/scripts/install-native-relay.mjs

@@ -22,7 +22,7 @@ import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.15.1";
+const VERSION = "1.16.0";
 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

@@ -2,15 +2,17 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { createHash } from "node:crypto";
 
 import { CodexAppServerClient } from "./app-server-client.mjs";
-import { PLATFORM_LABEL } from "./platform.mjs";
-import { PeerEndpoint, assertClaudeSessionCwd, assertClaudeSessionProcess, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
+import { PLATFORM_LABEL, openClaudeCodeComposer } from "./platform.mjs";
+import { PeerEndpoint, assertClaudeSessionCwd, assertClaudeSessionProcess, findClaudeSession, listClaudeSessions, readTranscript, readInitialTranscriptMessage } from "./peer-protocol.mjs";
 import { createThreadDelivery } from "./thread-delivery.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
 import { createRuntimeState } from "./runtime-state.mjs";
-import { readClaudeDesktopContext } from "./claude-desktop-context.mjs";
+import { readClaudeDesktopContext, readClaudeDesktopTasks } from "./claude-desktop-context.mjs";
+import { ClaudeSessionCreation } from "./claude-session-creation.mjs";
 import { readClaudeInboundPolicy } from "./claude-inbound-policy.mjs";
 import { assertRecipientClass, preflightFailure } from "./recipient-preflight.mjs";
 import { readCodexSenderContext } from "./codex-sender-context.mjs";
@@ -22,7 +24,7 @@ import { resolveClaudeDesktopSession } from "./claude-session-router.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.15.1";
+const VERSION = "1.16.0";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 
@@ -55,6 +57,16 @@ const forwarding = {
   threadId: process.env.CODEX_THREAD_ID ?? null,
 };
 
+const creations = new ClaudeSessionCreation({
+  open: openClaudeCodeComposer,
+  listTasks: (account) => readClaudeDesktopTasks({ account }),
+  listSessions: () => listClaudeSessions(),
+  readContext: (session, account) => readClaudeDesktopContext(session, { account }),
+  readTranscript: readInitialTranscriptMessage,
+  readAccount: readClaudeAccountContext,
+  assertProcess: assertClaudeSessionProcess,
+});
+
 const replyForwarder = new ReplyForwarder({
   minIntervalMs: FORWARD_MIN_INTERVAL_MS,
   maxPerSession: FORWARD_MAX_PER_SESSION,
@@ -72,7 +84,7 @@ const reload = createReloadControl({
   entry: "claude-bridge.mjs",
   inspect: () => peer.reloadReason() ?? replyForwarder.reloadReason() ?? clientReloadReason(codex),
   quiesce: async () => { await peer.quiesce(); codex.close(); },
-  exportState: () => ({ desktopOnly, peer: peer.exportReloadState(), forwarding: replyForwarder.exportReloadState(), threadId: forwarding.threadId }),
+  exportState: () => ({ desktopOnly, peer: peer.exportReloadState(), forwarding: replyForwarder.exportReloadState(), threadId: forwarding.threadId, creations: creations.exportState() }),
   restore: (state) => {
     assertRoutingReload(state.desktopOnly, desktopOnly);
     if (state.threadId !== null && (typeof state.threadId !== "string" || !state.threadId.trim())) {
@@ -81,6 +93,7 @@ const reload = createReloadControl({
     peer.restoreReloadState(state.peer);
     replyForwarder.restoreReloadState(state.forwarding);
     forwarding.threadId = state.threadId;
+    if (state.creations !== undefined) creations.restoreState(state.creations);
   },
   activate: () => peer.start(),
   resume: () => peer.resume(),
@@ -134,6 +147,31 @@ function assertSender(meta) {
   return sender;
 }
 
+async function startClaudeCreation({ requestId, cwd, prompt }, meta) {
+  runtime.assertCurrent();
+  if (!desktopOnly) throw new Error("New Claude sessions require Desktop-only mode");
+  const sender = assertSender(meta);
+  const accounts = readBridgeAccounts();
+  const selectedAccounts = requireBridgeAccounts(accounts);
+  const receipt = await creations.start({ requestId, cwd, prompt, account: accounts.claude, senderThreadId: sender.threadId,
+    beforeOpen: () => {
+      runtime.assertCurrent();
+      assertAccountIdentity(selectedAccounts);
+      const current = assertSender(meta);
+      if (JSON.stringify(current) !== JSON.stringify(sender)) throw new Error("The calling Codex turn changed before opening Claude Desktop");
+    },
+  });
+  return { ...textResult(JSON.stringify(receipt, null, 2)), structuredContent: { creation: receipt } };
+}
+
+async function inspectClaudeCreation(requestId, meta) {
+  const sender = assertSender(meta);
+  const accounts = readBridgeAccounts();
+  requireBridgeAccounts(accounts);
+  const receipt = await creations.inspect(requestId, { account: accounts.claude, senderThreadId: sender.threadId });
+  return { ...textResult(JSON.stringify(receipt, null, 2)), structuredContent: { creation: receipt } };
+}
+
 function forwardToCodexThread(record) {
   const threadId = record.replyThreadId ?? (desktopOnly ? null : forwarding.threadId);
   if (!threadId) return;
@@ -178,6 +216,49 @@ function registerTool(name, definition, handler) {
   });
 }
 
+registerTool(
+  "start_claude_session",
+  {
+    title: "Prepare a new Claude Desktop Code session",
+    description: "Use only when the user explicitly requests a NEW Claude Desktop session. Open the official Code composer in an existing project with a prefilled prompt. Claude Desktop requires the user to confirm the folder and press Send; opening the link is not session creation. Retain requestId and inspect read_claude_creation. Never substitute an existing task or launch a CLI session.",
+    inputSchema: {
+      requestId: z.string().describe("Stable UUID for this creation; reuse exactly when inspecting or retrying"),
+      cwd: z.string().describe("Exact absolute directory of the existing Claude Desktop project"),
+      prompt: z.string().describe("Initial prompt for the NEW conversation; shown for user confirmation"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  async (args, extra) => startClaudeCreation(args, extra?._meta),
+);
+
+registerTool(
+  "read_claude_creation",
+  {
+    title: "Verify a new Claude Desktop session",
+    description: "Inspect an existing creation request without reopening or sending. A created receipt requires a new native task, matching account/project, live process identity, and the exact initial user prompt. awaiting_project_confirmation means the prompt arrived in a new task but its folder still differs; the user must adopt the requested project before creation can be confirmed. An old task resumed with a new process never counts as a new session.",
+    inputSchema: { requestId: z.string().describe("Original requestId returned by start_claude_session") },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async ({ requestId }, extra) => inspectClaudeCreation(requestId, extra?._meta),
+);
+
+registerTool(
+  "abandon_claude_creation",
+  {
+    title: "Release a cancelled Claude creation request",
+    description: "Use only when the user explicitly cancels a pending creation request. Release its composer reservation while retaining the receipt. This does not close Claude Desktop or prove that the prefilled prompt was never submitted; the old request remains inspectable.",
+    inputSchema: { requestId: z.string().describe("Exact creation requestId the user cancelled") },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  async ({ requestId }, extra) => {
+    const sender = assertSender(extra?._meta);
+    const accounts = readBridgeAccounts();
+    requireBridgeAccounts(accounts);
+    const receipt = await creations.abandon(requestId, { account: accounts.claude, senderThreadId: sender.threadId });
+    return { ...textResult(JSON.stringify(receipt, null, 2)), structuredContent: { creation: receipt } };
+  },
+);
+
 registerTool(
   "list_claude_sessions",
   {
@@ -221,13 +302,14 @@ registerTool(
     title: "Send a message to a Claude session",
     description:
       "Send a message to a running Claude Code session's peer transport and wait for its reply. " +
+      "Only when the user requests a NEW conversation, target new prepares the native Desktop composer in expectedCwd; it requires user confirmation and returns a creation receipt, not a delivery receipt. " +
       "A socket write alone does not confirm that Claude received the message. Set waitSec to 0 to send without confirmation. " +
       "Every send is refused while earlier messages to that session still await replies, including waitSec 0; " +
       "wait for those replies and read_claude_inbox before trying again. Desktop-only mode refuses CLI or unknown " +
       "entrypoints, partial names, ambiguous targets, and a missing or mismatched expectedCwd or expectedTaskId before sending. Use target auto and expectedCwd for automatic current-account discovery; expectedTaskId is optional only when auto finds exactly one matching task. " +
       "The sender's current permissions are verified per call; environment overrides and manual binding cannot bypass an unknown sender. It never creates a replacement session.",
     inputSchema: {
-      target: z.string().describe("Use auto for current-account discovery in expectedCwd, or an exact session name, pid or sessionId"),
+      target: z.string().describe("Use auto for current-account discovery in expectedCwd, an exact session identity, or new to prepare a separate Desktop conversation requiring user confirmation"),
       message: z.string().describe("The message text to deliver"),
       expectedCwd: z.string().optional().describe("Exact absolute project directory independently verified by the caller; required in Desktop-only mode"),
       expectedTaskId: z.string().optional().describe("Exact native Claude Desktop task ID from list_claude_sessions; verify its title in the app before sending"),
@@ -249,6 +331,12 @@ registerTool(
   async ({ target, message, waitSec, expectedCwd, expectedTaskId }, extra) => {
     try {
       runtime.assertCurrent();
+      if (target === "new") {
+        if (expectedTaskId !== undefined) throw new Error("A new Claude conversation cannot target an existing task ID");
+        const sender = assertSender(extra?._meta);
+        const requestId = createHash("sha256").update(JSON.stringify([sender.threadId, sender.turnId, expectedCwd, message])).digest("hex");
+        return await startClaudeCreation({ requestId, cwd: expectedCwd, prompt: message }, extra?._meta);
+      }
       const accounts = desktopOnly ? readBridgeAccounts() : null;
       const selectedAccounts = desktopOnly ? requireBridgeAccounts(accounts) : null;
       const found = desktopOnly ? resolveClaudeDesktopSession({ target, expectedCwd, expectedTaskId,
@@ -339,11 +427,12 @@ registerTool(
   "read_claude_delivery",
   {
     title: "Inspect a Claude message receipt without resending",
-    description: "Read the latest recipient control receipt or correlated reply for a message sent by this MCP process. Unknown IDs do not prove non-delivery; retain the original receipt after a reconnect and inspect the existing Claude session before any resend.",
+    description: "Read the latest recipient control receipt or correlated reply for a message sent by this MCP process. Also accepts the 64-character requestId returned by target new to inspect creation without reopening. Unknown IDs do not prove non-delivery; retain the original receipt after a reconnect and inspect the existing Claude session before any resend.",
     inputSchema: { msgId: z.string().describe("The original message ID returned by send_to_claude_session") },
     annotations: { readOnlyHint: true, openWorldHint: false },
   },
-  async ({ msgId }) => {
+  async ({ msgId }, extra) => {
+    if (/^[0-9a-f]{64}$/i.test(msgId)) return inspectClaudeCreation(msgId, extra?._meta);
     const receipt = readReceipt(msgId);
     if (!receipt) return textResult("This MCP process has no receipt for that message ID. It may belong to a previous process; do not infer failure or resend. Inspect the original Claude Desktop session.", true);
     return { ...textResult(JSON.stringify(receipt, null, 2)), structuredContent: { receipt } };

package/src/claude-desktop-context.mjs

@@ -133,22 +133,11 @@ export function readClaudeDesktopContext(session, { platform = process.platform,
       (typeof session.bridgeSessionId !== "string" || !session.bridgeSessionId.trim())) {
     return result("mismatch", "The live Claude bridge session identity is invalid.");
   }
-  const directory = root ?? (account ? path.join(account.root, "claude-code-sessions") : sessionsRoot(platform, env));
   let records;
   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.");
-    const files = metadataFiles(directory, account?.accountId);
-    const budget = { bytes: 0, versions: new Map(), contents: new Map() };
-    records = files.map((file) => readMetadata(file, budget));
-    const currentFiles = metadataFiles(directory, account?.accountId);
-    if (files.length !== currentFiles.length || files.some((file, index) => file !== currentFiles[index])) {
-      return result("mismatch", "Claude Desktop task metadata changed during inspection; inspect the existing task again.");
-    }
-    for (const file of files) {
-      const current = fs.lstatSync(file);
-      if (!current.isFile() || !sameVersion(current, budget.versions.get(file))) throw new Error("metadata changed");
-      if (!rereadMetadata(file).equals(budget.contents.get(file))) throw new Error("metadata changed");
-    }
+    records = readClaudeDesktopTasks({ platform, env, root, account });
   } catch {
     return result("mismatch", "Claude Desktop task metadata could not be read completely and consistently; no task identity is confirmed.");
   }
@@ -202,3 +191,20 @@ export function readClaudeDesktopContext(session, { platform = process.platform,
     accountFingerprint: account?.fingerprint,
   });
 }
+
+export function readClaudeDesktopTasks({ platform = process.platform, env = process.env, root, account } = {}) {
+  if (account !== undefined && (account.status !== "verified" || !ACCOUNT_ID.test(account.accountId ?? "") || !account.root)) {
+    throw new Error("Claude Desktop account is not verified");
+  }
+  const directory = root ?? (account ? path.join(account.root, "claude-code-sessions") : sessionsRoot(platform, env));
+  const files = metadataFiles(directory, account?.accountId);
+  const budget = { bytes: 0, versions: new Map(), contents: new Map() };
+  const records = files.map((file) => readMetadata(file, budget));
+  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);
+    if (!current.isFile() || !sameVersion(current, budget.versions.get(file)) || !rereadMetadata(file).equals(budget.contents.get(file))) throw new Error("metadata changed");
+  }
+  return records;
+}

package/src/claude-session-creation.mjs

@@ -0,0 +1,216 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const REQUEST_ID = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{32,128})$/i;
+const PENDING = new Set(["awaiting_user", "launch_uncertain", "ambiguous", "awaiting_project_confirmation"]);
+const STATUSES = new Set([...PENDING, "created", "abandoned"]);
+const MAX_REQUESTS = 32;
+const MAX_TASKS = 8192;
+
+function fail(code, message) {
+  throw Object.assign(new Error(message), { code });
+}
+
+function string(value, max = 1024) {
+  return typeof value === "string" && value.length > 0 && value.length <= max && !value.includes("\0");
+}
+
+function accountIdentity(account) {
+  if (account?.status !== "verified" || !string(account.fingerprint) || !string(account.root, 8192)) {
+    fail("CLAUDE_ACCOUNT_UNVERIFIED", "The current Claude Desktop account must be verified.");
+  }
+  return { fingerprint: account.fingerprint, root: account.root };
+}
+
+function sameAccount(left, right) {
+  return left.fingerprint === right.fingerprint && left.root === right.root;
+}
+
+function augmentedPrompt(prompt, requestId) {
+  if (!string(prompt, 14000) || !prompt.trim()) fail("CLAUDE_CREATION_PROMPT_INVALID", "Provide a nonempty prompt of at most 14000 characters.");
+  const submitted = `${prompt.trim()}\n\n[Codex creation request: ${requestId}]`;
+  if (submitted.length > 14000) fail("CLAUDE_CREATION_PROMPT_TOO_LONG", "The prompt including its correlation marker exceeds 14000 characters.");
+  return submitted;
+}
+
+function matchesInitialMessage(text, expected) {
+  if (text === expected) return true;
+  if (typeof text !== "string" || !/^<system-reminder>\r?\nThe user started this session without choosing a project folder,/.test(text)) return false;
+  const closing = text.indexOf("</system-reminder>");
+  if (closing < 0 || closing > 32768) return false;
+  const body = text.slice("<system-reminder>".length, closing);
+  if (body.includes("<system-reminder") || body.includes("</system-reminder")) return false;
+  const suffix = text.slice(closing + "</system-reminder>".length);
+  const separator = /^\r?\n\r?\n/.exec(suffix);
+  return separator !== null && suffix.slice(separator[0].length) === expected;
+}
+
+function receipt(request) {
+  return structuredClone({ requestId: request.requestId, status: request.status, cwd: request.cwd, promptSubmitted: request.status === "created" || request.submissionObserved === true, reason: request.reason, ...(request.observedCwd ? { observedCwd: request.observedCwd } : {}), ...(request.sessionId ? { sessionId: request.sessionId, taskId: request.taskId, title: request.title } : {}) });
+}
+
+export class ClaudeSessionCreation {
+  constructor({ open, listTasks, listSessions, readContext, readTranscript, readAccount, assertProcess, realpath = (directory) => {
+    const canonical = fs.realpathSync.native(directory);
+    if (!fs.statSync(canonical).isDirectory()) throw new Error("Not a directory");
+    return canonical;
+  }, platform = process.platform }) {
+    for (const [name, dependency] of Object.entries({ open, listTasks, listSessions, readContext, readTranscript, readAccount, assertProcess, realpath })) {
+      if (typeof dependency !== "function") throw new TypeError(`${name} must be a function`);
+    }
+    Object.assign(this, { open, listTasks, listSessions, readContext, readTranscript, readAccount, assertProcess, realpath, platform });
+    this.requests = new Map();
+    this.queue = Promise.resolve();
+  }
+
+  async canonical(directory) {
+    const paths = this.platform === "win32" ? path.win32 : path.posix;
+    if (!string(directory, 8192) || !paths.isAbsolute(directory)) fail("CLAUDE_CREATION_CWD_INVALID", "The project directory must be an existing absolute directory.");
+    let canonical;
+    try { canonical = await this.realpath(directory); } catch { fail("CLAUDE_CREATION_CWD_INVALID", "The project directory does not exist or cannot be resolved."); }
+    if (!string(canonical, 8192) || !paths.isAbsolute(canonical)) fail("CLAUDE_CREATION_CWD_INVALID", "The canonical project directory is invalid.");
+    return canonical;
+  }
+
+  sameCwd(left, right) {
+    return this.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+  }
+
+  async checkAccount(account, expected) {
+    const provided = accountIdentity(account);
+    const current = accountIdentity(await this.readAccount());
+    if (!sameAccount(provided, current) || (expected && !sameAccount(provided, expected))) fail("CLAUDE_CREATION_ACCOUNT_CHANGED", "Claude Desktop account changed; this creation request cannot be used in another account.");
+    return provided;
+  }
+
+  start(args) {
+    const pending = this.queue.then(() => this.startLocked(args));
+    this.queue = pending.catch(() => {});
+    return pending;
+  }
+
+  async startLocked({ requestId, cwd, prompt, account, senderThreadId, beforeOpen }) {
+    if (!REQUEST_ID.test(requestId ?? "") || typeof requestId !== "string") fail("CLAUDE_CREATION_REQUEST_INVALID", "requestId must be a UUID or 32–128 hexadecimal characters.");
+    if (!string(senderThreadId, 256)) fail("CLAUDE_CREATION_SENDER_INVALID", "A verified sender thread identity is required.");
+    const identity = await this.checkAccount(account);
+    const canonical = await this.canonical(cwd);
+    const initialMessage = augmentedPrompt(prompt, requestId);
+    const prior = this.requests.get(requestId);
+    if (prior) {
+      if (!sameAccount(identity, prior.account) || prior.senderThreadId !== senderThreadId || !this.sameCwd(prior.cwd, canonical) || prior.prompt !== prompt) {
+        fail("CLAUDE_CREATION_REQUEST_CONFLICT", "This requestId is already bound to a different creation payload.");
+      }
+      return receipt(prior);
+    }
+    if (this.requests.size >= MAX_REQUESTS) fail("CLAUDE_CREATION_LIMIT", "The creation receipt limit has been reached; existing requests remain available for inspection.");
+    for (const existing of this.requests.values()) {
+      if (sameAccount(existing.account, identity) && PENDING.has(existing.status)) fail("CLAUDE_CREATION_PENDING", "A creation request is already pending for this account; inspect or explicitly abandon that request before opening another project in the shared composer.");
+    }
+    const tasks = await this.listTasks(account);
+    if (!Array.isArray(tasks) || tasks.length > MAX_TASKS || tasks.some((task) => !string(task?.taskId, 256) || (task.fileTaskId !== undefined && task.fileTaskId !== task.taskId))) fail("CLAUDE_CREATION_TASKS_INVALID", "The existing native task baseline cannot be verified.");
+    let existingProject = false;
+    for (const task of tasks) {
+      if (task.isArchived !== false) continue;
+      try { if (this.sameCwd(await this.canonical(task.cwd), canonical)) existingProject = true; } catch {}
+    }
+    if (!existingProject) fail("CLAUDE_CREATION_PROJECT_NOT_FOUND", "The canonical directory must already belong to a nonarchived Claude Desktop task.");
+    const url = `claude://code/new?q=${encodeURIComponent(initialMessage)}&folder=${encodeURIComponent(canonical)}`;
+    if (url.length > 30000) fail("CLAUDE_CREATION_URL_TOO_LONG", "The encoded Claude Desktop link exceeds 30000 characters.");
+    await this.checkAccount(account, identity);
+    if (beforeOpen !== undefined) {
+      if (typeof beforeOpen !== "function") fail("CLAUDE_CREATION_PREFLIGHT_INVALID", "beforeOpen must be a function.");
+      await beforeOpen();
+    }
+    const request = { requestId, cwd: canonical, prompt, initialMessage, account: identity, senderThreadId, baseline: [...new Set(tasks.map((task) => task.taskId))], status: "launch_uncertain", reason: "The Desktop launch outcome is uncertain; inspect this request before taking further action." };
+    this.requests.set(requestId, request);
+    try {
+      await this.open(url);
+      request.status = "awaiting_user";
+      request.reason = "Claude Desktop was asked to prefill a new session. Confirm the folder if prompted and press Send; no prompt has been submitted by the bridge.";
+    } catch {
+      request.reason = "The Desktop launcher failed or returned an uncertain outcome. This request will not be launched again; inspect it to check whether the session was created.";
+    }
+    return receipt(request);
+  }
+
+  async inspect(requestId, { account, senderThreadId }) {
+    const request = this.requests.get(requestId);
+    if (!request) fail("CLAUDE_CREATION_REQUEST_NOT_FOUND", "No retained creation request has this requestId.");
+    if (request.senderThreadId !== senderThreadId) fail("CLAUDE_CREATION_SENDER_MISMATCH", "This creation request belongs to another sender thread.");
+    await this.checkAccount(account, request.account);
+    if (request.status === "created") return receipt(request);
+    const sessions = await this.listSessions(account);
+    if (!Array.isArray(sessions) || sessions.length > MAX_TASKS) fail("CLAUDE_CREATION_SESSIONS_INVALID", "Live native sessions could not be inspected within the limit.");
+    const matches = new Map();
+    for (const session of sessions) {
+      if (!session?.alive || session.entrypoint !== "claude-desktop" || !string(session.sessionId, 256)) continue;
+      try {
+        const observedCwd = await this.canonical(session.cwd);
+        if (await this.assertProcess(session) === false) continue;
+        const context = await this.readContext(session, account);
+        if (context?.status !== "matched" || context.isArchived || !string(context.taskId, 256) || request.baseline.includes(context.taskId)) continue;
+        if (context.fileTaskId !== undefined && context.fileTaskId !== context.taskId) continue;
+        if (context.accountFingerprint && context.accountFingerprint !== request.account.fingerprint) continue;
+        if (!this.sameCwd(await this.canonical(context.cwd), observedCwd)) continue;
+        const transcript = await this.readTranscript(session.sessionId, observedCwd, 1000);
+        if (transcript?.truncated || transcript?.incomplete) continue;
+        const firstUser = transcript?.messages?.find((message) => message.role === "user");
+        if (!matchesInitialMessage(firstUser?.text, request.initialMessage)) continue;
+        if (await this.assertProcess(session) === false) continue;
+        matches.set(JSON.stringify([context.taskId, session.sessionId]), { sessionId: session.sessionId, taskId: context.taskId, title: string(context.title, 65536) && context.title.trim() ? context.title.trim().slice(0, 4096) : null, observedCwd });
+      } catch {}
+    }
+    await this.checkAccount(account, request.account);
+    if (matches.size > 1) {
+      request.submissionObserved = true;
+      request.ambiguitySeen = true;
+      request.status = "ambiguous";
+      for (const key of ["sessionId", "taskId", "title", "observedCwd"]) delete request[key];
+      request.reason = "Multiple new native sessions contain the exact creation message; no session was selected.";
+    } else if (matches.size === 1 && request.status !== "ambiguous" && !request.ambiguitySeen) {
+      const match = [...matches.values()][0];
+      const projectConfirmed = this.sameCwd(match.observedCwd, request.cwd);
+      Object.assign(request, match, { submissionObserved: true, status: projectConfirmed ? "created" : "awaiting_project_confirmation", reason: projectConfirmed ? "A new live native Claude Desktop task has the exact initial user message, verified project, account, and process identity." : "The prompt was submitted in a new native Claude Desktop task, but its actual directory differs from the requested project. Select or adopt the requested project folder in Claude Desktop and inspect this request again; project creation is not confirmed." });
+    }
+    return receipt(request);
+  }
+
+  abandon(requestId, args) {
+    const pending = this.queue.then(() => this.abandonLocked(requestId, args));
+    this.queue = pending.catch(() => {});
+    return pending;
+  }
+
+  async abandonLocked(requestId, { account, senderThreadId }) {
+    const request = this.requests.get(requestId);
+    if (!request) fail("CLAUDE_CREATION_REQUEST_NOT_FOUND", "No retained creation request has this requestId.");
+    if (request.senderThreadId !== senderThreadId) fail("CLAUDE_CREATION_SENDER_MISMATCH", "This creation request belongs to another sender thread.");
+    await this.checkAccount(account, request.account);
+    if (request.status === "created") return receipt(request);
+    if (request.status === "ambiguous") request.ambiguitySeen = true;
+    request.status = "abandoned";
+    request.reason = "The creation request was abandoned and its composer lock released. Claude Desktop and its composer may still be open, and the prompt could still be submitted later. The receipt is retained for inspection and will never relaunch.";
+    return receipt(request);
+  }
+
+  exportState() {
+    return structuredClone({ version: 1, requests: [...this.requests.values()] });
+  }
+
+  restoreState(state) {
+    if (this.requests.size || state?.version !== 1 || !Array.isArray(state.requests) || state.requests.length > MAX_REQUESTS) fail("CLAUDE_CREATION_STATE_INVALID", "Creation state cannot be restored.");
+    const restored = new Map();
+    const paths = this.platform === "win32" ? path.win32 : path.posix;
+    for (const request of state.requests) {
+      if (!request || typeof request.requestId !== "string" || !REQUEST_ID.test(request.requestId) || restored.has(request.requestId) || !string(request.cwd, 8192) || !paths.isAbsolute(request.cwd) || !string(request.senderThreadId, 256) || !string(request.account?.fingerprint) || !string(request.account?.root, 8192) || !STATUSES.has(request.status) || !string(request.reason, 4096) || !Array.isArray(request.baseline) || request.baseline.length > MAX_TASKS || request.baseline.some((id) => !string(id, 256)) || request.initialMessage !== augmentedPrompt(request.prompt, request.requestId)) fail("CLAUDE_CREATION_STATE_INVALID", "A retained creation receipt is invalid.");
+      const hasSession = ["created", "awaiting_project_confirmation"].includes(request.status) || request.sessionId !== undefined;
+      if (hasSession && (!string(request.sessionId, 256) || !string(request.taskId, 256) || request.baseline.includes(request.taskId) || (request.title !== null && !string(request.title, 4096)))) fail("CLAUDE_CREATION_STATE_INVALID", "A submitted creation receipt is invalid.");
+      if (request.submissionObserved !== undefined && typeof request.submissionObserved !== "boolean") fail("CLAUDE_CREATION_STATE_INVALID", "A retained submission marker is invalid.");
+      if ((request.status === "awaiting_project_confirmation" || request.observedCwd !== undefined) && (!string(request.observedCwd, 8192) || !paths.isAbsolute(request.observedCwd))) fail("CLAUDE_CREATION_STATE_INVALID", "A retained observed directory is invalid.");
+      if (request.status === "awaiting_project_confirmation" && (request.submissionObserved !== true || this.sameCwd(request.cwd, request.observedCwd))) fail("CLAUDE_CREATION_STATE_INVALID", "A pending project confirmation is invalid.");
+      if (request.ambiguitySeen !== undefined && typeof request.ambiguitySeen !== "boolean") fail("CLAUDE_CREATION_STATE_INVALID", "A retained ambiguity marker is invalid.");
+      restored.set(request.requestId, structuredClone({ requestId: request.requestId, cwd: request.cwd, prompt: request.prompt, initialMessage: request.initialMessage, account: { fingerprint: request.account.fingerprint, root: request.account.root }, senderThreadId: request.senderThreadId, baseline: request.baseline, status: request.status, reason: request.reason, ...(request.ambiguitySeen || request.status === "ambiguous" ? { ambiguitySeen: true } : {}), ...(request.submissionObserved ? { submissionObserved: true } : {}), ...(request.observedCwd ? { observedCwd: request.observedCwd } : {}), ...(hasSession ? { sessionId: request.sessionId, taskId: request.taskId, title: request.title } : {}) }));
+    }
+    this.requests = restored;
+  }
+}

package/src/index.mjs

@@ -33,7 +33,7 @@ import { assertClaudeSenderContext, readClaudeSenderContext, requireClaudeSender
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.15.1";
+const VERSION = "1.16.0";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**

package/src/native-relay-companion.mjs

@@ -30,7 +30,7 @@ import { createRuntimeState } from "./runtime-state.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.15.1";
+const VERSION = "1.16.0";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {

package/src/peer-protocol.mjs

@@ -99,7 +99,7 @@ function readPeerToken(socket) {
   try {
     const key = JSON.parse(fs.readFileSync(peerKeyPath(candidates[0].pid, socket), "utf8"));
     if (typeof key.peerToken !== "string" || !/^[0-9a-f]{32}$/i.test(key.peerToken)) throw new Error("Invalid peer key");
-    const identity = IS_WINDOWS ? key.procStartFt : key.procStart;
+    const identity = readPeerProcessIdentity(key);
     if (identity && identity !== readProcessStart(candidates[0].pid)) throw new Error("Peer process identity changed");
     return key.peerToken;
   } catch {
@@ -108,6 +108,17 @@ function readPeerToken(socket) {
   }
 }
 
+export function readPeerProcessIdentity(entry, platform = process.platform) {
+  if (platform !== "win32") return entry.procStart ?? null;
+  const values = ["procStart", "procStartFt"].filter((field) => Object.hasOwn(entry, field)).map((field) => entry[field]);
+  if (!values.length) return null;
+  if (values.some((value) => typeof value !== "string" || !/^[1-9]\d{0,19}$/.test(value) || BigInt(value) > 18446744073709551615n)
+      || values.some((value) => value !== values[0])) {
+    throw new Error("Invalid or conflicting Windows peer process identity");
+  }
+  return values[0];
+}
+
 /**
  * MCP servers are spawned with an empty PATH, so `ps` must be addressed by its
  * absolute path - a bare lookup throws ENOENT and takes the whole server down
@@ -173,6 +184,9 @@ export function listClaudeSessions({ includeDead = false, includeBridges = false
     if (entry.entrypoint === BRIDGE_ENTRYPOINT && !includeBridges) continue;
     const alive = isProcessAlive(entry.pid) && hasMessagingEndpoint(entry);
     if (!alive && !includeDead) continue;
+    let processStart;
+    try { processStart = readPeerProcessIdentity(entry); }
+    catch { continue; }
     rows.push({
       pid: entry.pid,
       name: entry.name ?? null,
@@ -182,7 +196,7 @@ export function listClaudeSessions({ includeDead = false, includeBridges = false
       kind: entry.kind ?? null,
       entrypoint: entry.entrypoint ?? null,
       startedAt: entry.startedAt ?? null,
-      processStart: (IS_WINDOWS ? entry.procStartFt : entry.procStart) ?? null,
+      processStart,
       socket: entry.messagingSocketPath,
       alive,
     });
@@ -285,6 +299,29 @@ export function readTranscript(sessionId, cwd, limit = 10) {
   return { file, messages: messages.slice(-limit) };
 }
 
+export function readInitialTranscriptMessage(sessionId, cwd) {
+  const file = findTranscriptFile(sessionId, cwd);
+  if (!fs.existsSync(file)) return { file, messages: [] };
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile()) return { file, messages: [] };
+    const buffer = Buffer.alloc(Math.min(stat.size, 1024 * 1024));
+    const bytes = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+    const text = buffer.subarray(0, bytes).toString("utf8");
+    for (const line of text.slice(0, text.lastIndexOf("\n") + 1).split("\n")) {
+      if (!line.trim()) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { return { file, messages: [] }; }
+      if (entry.isMeta || entry.isSidechain || entry.message?.role !== "user") continue;
+      const content = entry.message.content;
+      const initial = (Array.isArray(content) ? content.filter((part) => part?.type === "text").map((part) => part.text ?? "").join("\n") : String(content ?? "")).trim();
+      return { file, messages: initial ? [{ role: "user", text: initial }] : [] };
+    }
+    return { file, messages: [] };
+  } finally { fs.closeSync(descriptor); }
+}
+
 /**
  * Claude Code records an injected peer message in one of two shapes. An idle
  * recipient starts a new turn with a user entry whose uuid is the message id
@@ -420,7 +457,7 @@ export class PeerEndpoint {
     });
     if (!IS_WINDOWS) fs.chmodSync(this.socketPath, 0o600);
 
-    const processIdentity = procStart ? (IS_WINDOWS ? { procStartFt: procStart } : { procStart }) : {};
+    const processIdentity = procStart ? (IS_WINDOWS ? { procStart, procStartFt: procStart } : { procStart }) : {};
     this.registry = {
       pid: this.pid,
       sessionId: crypto.randomUUID(),

package/src/platform.mjs

@@ -468,3 +468,21 @@ export async function openThreadInCodexApp(threadId, { activate = true } = {}) {
   await execFileAsync("open", args, { timeout: 10000 });
   return url;
 }
+
+export async function openClaudeCodeComposer(url, { platform = process.platform, env = process.env, run = execFileAsync } = {}) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "claude:" || parsed.hostname !== "code" || parsed.pathname !== "/new" || parsed.username || parsed.password || parsed.port || parsed.hash
+      || [...parsed.searchParams.keys()].some((key) => !["q", "folder"].includes(key))) {
+    throw new Error("Invalid Claude Desktop Code creation link");
+  }
+  if (platform === "win32") {
+    const shell = path.win32.join(env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    const encodedUrl = Buffer.from(url, "utf8").toString("base64");
+    const script = `$ErrorActionPreference='Stop'; $creationUrl=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedUrl}')); Start-Process -FilePath $creationUrl -ErrorAction Stop`;
+    await run(shell, ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { windowsHide: true, timeout: 10000 });
+    return;
+  }
+  const command = platform === "darwin" ? "/usr/bin/open" : platform === "linux" ? "/usr/bin/xdg-open" : null;
+  if (!command) throw new Error("Claude Desktop Code links are unsupported on this platform");
+  await run(command, [url], { windowsHide: true, timeout: 10000 });
+}