@minhspark/codex-mcp-bridge 1.22.20 → 1.23.0

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,36 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.23.0] - 2026-10-26
+
+### Added
+
+- `remote_codex` lists, reads and messages existing Codex Desktop tasks on an explicitly configured SSH host. Calling-turn verification, exact project and repository checks, current account binding and signed durable receipts prevent wrong-project delivery and duplicate sends after uncertain transport outcomes. The two computers may use different Codex accounts; signing in again is discovered on the next call.
+
+### Tests
+
+- Remote handoff regressions cover different accounts, mid-request identity changes, target and repository mismatches, missing sender metadata, SSH argument isolation, size and deadline limits, concurrent retries and receipt recovery after restart. Task membership is verified through native listings because native task reads can omit the project ID.
+
+### Upgrade
+
+- Update both computers with `npm install -g @minhspark/codex-mcp-bridge@latest`. If an existing Codex task keeps its old tool catalog, reconnect its MCP server or start a fresh task to load `remote_codex`.
+
+## [1.22.21] - 2026-10-26
+
+### Fixed
+
+- Recognize native Claude background-task completion notifications stored as inline attachments. A completed command could otherwise remain outstanding, hiding the final reply and blocking later messages with `PEER_REPLY_PENDING`. Both notification formats retain native-origin, exact task/tool-call identity and transcript ancestry checks; observing the original reply never resends its action.
+- Resolve Claude reply ancestry when a final response is persisted before its parent attachment. Process unambiguous records with ancestors first, reject cycles, and preserve input boundaries and pending ownership until the required parent arrives.
+
+### Verification
+
+- Three focused regressions fail against 1.22.20 and pass with this fix: inline completion, child-before-parent ancestry, and pending ownership recovery without repeating the original action.
+- Independent parser checks cover 1,320 record-order and invalid-notification combinations. Endpoint tests verify that missing parents keep ownership pending and that a distinct follow-up is allowed only after the original reply resolves.
+
+### Limitations
+
+- Missing or ambiguous transcript ancestry still cannot establish a reply. Inspect the existing task instead of resending its original action. An already blocked older runtime may need a client restart after upgrading to load this fix.
+
 ## [1.22.20] - 2026-10-24
 
 ### Fixed

package/README.md

@@ -166,6 +166,7 @@ Send a short message and confirm its reply **in both directions**. Registration
 
 - **Claude → Codex:** “Send this review to my Codex task in this project and wait for its reply.”
 - **Codex → Claude:** “Send this result to my Claude Desktop Code session in this project.”
+- **Codex → Codex on another computer:** configure an SSH project mapping, then use `remote_codex` to list, read or message an existing Desktop task. Different Codex accounts on the two computers are supported. See [remote Codex setup](REFERENCE.md#codex-to-codex-over-ssh).
 - **New work:** “Create a new Codex conversation for this feature and send the brief there.”
 
 Continue unfinished work with its original `threadId`. For an authorized new Desktop task, use `delegate_to_codex` or `start_codex_thread` with a fresh UUID `requestId`; retain that ID on retries. If a send times out, use `wait_codex_reply` with the original `deliveryId` before retrying the message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.20",
+  "version": "1.23.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",
@@ -83,6 +83,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "zod": "^3.25.76"
+    "zod": "^4.6.7"
   }
 }

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.20",
+  "version": "1.23.0",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.20";
+const VERSION = "1.23.0";
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.20";
+const VERSION = "1.23.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/index.mjs

@@ -41,7 +41,7 @@ import { createRelayWake, relayKeeperEnabled, relayWakeStateFile, startRelayKeep
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.20";
+const VERSION = "1.23.0";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 

package/src/native-creation-receipts.mjs

@@ -21,7 +21,9 @@ export class NativeCreationReceipts {
   #keyBoundary;
   #keyDirectoryBoundary;
   #keyDirectory;
-  constructor({ directory = path.join(process.env.CODEX_HOME ?? path.join(homeDir(), ".codex"), "bridge-native-creations") } = {}) {
+  constructor({ directory = path.join(process.env.CODEX_HOME ?? path.join(homeDir(), ".codex"), "bridge-native-creations"), accountProviders = ["claude", "codex"] } = {}) {
+    if (!["claude,codex", "codex"].includes(accountProviders?.join())) throw Error("Invalid receipt account providers");
+    this.accountProviders = Object.freeze([...accountProviders]);
     this.directory = path.resolve(directory);
     this.#keyDirectory = path.join(path.dirname(this.directory), "bridge-native-creation-authority");
   }
@@ -137,7 +139,7 @@ export class NativeCreationReceipts {
       if (current.isSymbolicLink() || !sameFile(opened, after) || !sameFile(after, current) || BigInt(count) !== opened.size) throw Error("Native creation receipt changed");
       const row = JSON.parse(bytes.subarray(0, count).toString());
       if (row.version !== 1 || row.id !== id || row.hash !== hash || creationRequestHash(row.args) !== hash ||
-          !accounts || ["claude", "codex"].some(k => !accounts[k] || row.accounts?.[k] !== accounts[k]) ||
+          !accounts || Object.keys(row.accounts ?? {}).sort().join() !== this.accountProviders.join() || this.accountProviders.some(k => !accounts[k] || row.accounts?.[k] !== accounts[k]) ||
           typeof row.executorThreadId !== "string" || !["pending", "completed", "failed"].includes(row.state)) throw Error("Native creation receipt binding mismatch");
       if (typeof row.signature !== "string" || !/^[a-f0-9]{64}$/.test(row.signature) ||
           !timingSafeEqual(Buffer.from(row.signature, "hex"), Buffer.from(this.#signature(row), "hex"))) throw Error("Native creation receipt signature is invalid; ownership recovery is blocked");

package/src/native-relay-companion.mjs

@@ -37,10 +37,12 @@ import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 import { removeRelayFile, relayFileIdentity, verifyRelaySocketMode } from "./native-relay-files.mjs";
 
 import { NativeCreationReceipts, creationIdValid } from "./native-creation-receipts.mjs";
+import { registerRemoteCodexTools } from "./remote-codex-tools.mjs";
+import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } from "./remote-codex.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.20";
+const VERSION = "1.23.0";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {
@@ -392,6 +394,7 @@ export class RelaySocketServer {
     authorize,
     creationReceipts = new NativeCreationReceipts(),
     requireAccountContext = false,
+    requestHandler,
     strict = hardenedBridgeEnabled(),
     protectSocket = protectCurrentUserPipe,
     restrictSocket = (target, expected) => {
@@ -408,6 +411,7 @@ export class RelaySocketServer {
     this.authorize = authorize;
     this.creationReceipts = creationReceipts;
     this.requireAccountContext = requireAccountContext;
+    this.requestHandler = requestHandler;
     this.strict = strict;
     this.protectSocket = protectSocket;
     this.restrictSocket = restrictSocket;
@@ -667,6 +671,10 @@ export class RelaySocketServer {
       this.#reply(socket, errorResponse("RELAY_BAD_REQUEST", `malformed JSON: ${err.message}`));
       return;
     }
+    if (this.requestHandler) {
+      this.#reply(socket, await this.requestHandler(payload));
+      return;
+    }
     if ((this.requireAccountContext || this.strict) && !boundRequest(payload)) {
       this.#reply(socket, errorResponse("RELAY_BAD_REQUEST", "The account relay requires protocol 2 and the original account context", false));
       return;
@@ -875,7 +883,12 @@ export function createRelayServers({ nativeTools, env = process.env, signalExit
     ...shared,
   });
   const strictDesktop = hardened && desktopTasksConfigured(env);
-  return { relay, desktopRelay, accountRelay, strictDesktop, relays: strictDesktop ? [accountRelay] : [relay, desktopRelay, accountRelay] };
+  const remoteRelay = new RelaySocketServer({
+    socketPath: remoteCodexSocketPath(env), strict: true,
+    requestHandler: (request) => remoteRequestResponse(request, { env, relay: remoteNativeAdapter(nativeTools, env) }),
+    ...shared,
+  });
+  return { relay, desktopRelay, accountRelay, remoteRelay, strictDesktop, relays: strictDesktop ? [accountRelay, remoteRelay] : [relay, desktopRelay, accountRelay, remoteRelay] };
 }
 
 /**
@@ -891,16 +904,17 @@ if (invokedDirectly) {
     {
       instructions:
         "Companion process for the Codex Desktop native relay. It carries no work of its own: it accepts " +
-        "messages from claude-bridge on a private local socket and asks the Codex Desktop app-server that " +
+        "authorized Codex handoffs over SSH and messages from claude-bridge on private local sockets, and asks the Codex Desktop app-server that " +
         "launched it to deliver them into an already-open thread, so that thread keeps its writer lock.",
     },
   );
 
   const nativeTools = new NativeToolsClient();
-  const { relay, desktopRelay, accountRelay, strictDesktop, relays } = createRelayServers({ nativeTools, signalExit: false, log });
+  const { relay, desktopRelay, accountRelay, remoteRelay, strictDesktop, relays } = createRelayServers({ nativeTools, signalExit: false, log });
   const runtime = createRuntimeState();
   const lifecycle = createNativeRelayLifecycle({ nativeTools, relays, log });
   const reload = createReloadControl({ entry: "native-relay-companion.mjs", ...lifecycle });
+  registerRemoteCodexTools(mcp, { nativeTools, runtime, reload });
 
   mcp.registerTool(
     "native_relay_status",
@@ -936,6 +950,7 @@ if (invokedDirectly) {
                `relay socket:   ${strictDesktop ? "disabled by hardened Desktop profile" : relay.started ? relay.socketPath : `${relay.socketPath} (${listening ? "shared companion listening" : "not listening"})`}`,
                `desktop tasks:  ${strictDesktop ? "disabled by hardened Desktop profile" : `${desktopRelay.socketPath} (${await desktopRelay.isListening() ? "listening" : "not listening"})`}`,
               `account relay:  ${accountRelay.socketPath} (protocol ${ACCOUNT_RELAY_PROTOCOL_VERSION}, ${await accountRelay.isListening() ? "listening" : "not listening"})`,
+              `remote Codex:   ${remoteRelay.socketPath} (${await remoteRelay.isListening() ? "listening" : "not listening"})`,
               `executor:       ${executor}`,
               `dispatch:       ${process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD}`,
               `native pipe:    ${nativeTools.socketPath ?? "unavailable (requires Codex Desktop)"}`,

package/src/peer-protocol.mjs

@@ -486,6 +486,28 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
   if (roots.length !== 1) return null;
   const { entry: root, absorbed } = roots[0];
   const entriesById = new Map(entries.map((entry) => [entry.uuid, entry]));
+  const orderedEntries = ambiguous ? entries : [];
+  if (!ambiguous) {
+    // Claude can persist a reply before its parent attachment; visit late
+    // ancestors before their children instead of assuming append order.
+    const visited = new Set();
+    for (const entry of entries) {
+      const ancestors = [];
+      const visiting = new Set();
+      let ancestor = entry;
+      while (ancestor && !visited.has(ancestor)) {
+        if (visiting.has(ancestor)) return null;
+        visiting.add(ancestor);
+        ancestors.push(ancestor);
+        ancestor = typeof ancestor.parentUuid === "string" ? entriesById.get(ancestor.parentUuid) : null;
+      }
+      while (ancestors.length) {
+        const ancestor = ancestors.pop();
+        visited.add(ancestor);
+        orderedEntries.push(ancestor);
+      }
+    }
+  }
   const descendants = new Map();
   const backgroundCalls = new Map();
   const openLeaves = new Set();
@@ -497,7 +519,7 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
     openLeaves.delete(entry.parentUuid);
     interruptions.push({ entryId: entry.uuid, backgroundTaskIds: [...outstanding.keys()] });
   };
-  for (const entry of entries) {
+  for (const entry of orderedEntries) {
     if (entry === root) { descendants.set(entry.uuid, new Map()); openLeaves.add(entry.uuid); continue; }
     let parentUuid = entry.parentUuid;
     if (!ambiguous && !interruptions.length && descendants.has(entry.logicalParentUuid)
@@ -509,6 +531,7 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
       }
     }
     if (!descendants.has(parentUuid)) continue;
+    let taskNotification = null;
     if (entry.type === "attachment" && entry.attachment?.type === "queued_command") {
       // Only a native command record is a boundary. Its text is never used as
       // proof of authorization, cancellation, or successful task completion.
@@ -516,12 +539,12 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
         interrupt(entry, descendants.get(entry.parentUuid));
         continue;
       }
-      // An inline native task notification is not a new prompt. Preserve the
-      // active reply chain even when the notification belongs to another task;
-      // its text alone never completes any outstanding background command.
+      // Inline native notifications preserve the chain; only matching task and
+      // tool-call identities below can complete an outstanding command.
       if (entry.attachment.commandMode !== "task-notification"
         || entry.attachment.origin?.kind !== "task-notification"
         || entry.attachment.origin?.producer !== "session-task") continue;
+      taskNotification = entry.attachment.prompt;
     }
     const role = entry.message?.role;
     const content = entry.message?.content;
@@ -548,14 +571,18 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
       if (entry.origin?.kind !== "task-notification" || entry.origin.producer !== "session-task"
         || entry.promptSource !== "system" || entry.turnOrigin !== "task_notification"
         || typeof content !== "string" || !/^<task-notification>\s[\s\S]*<\/task-notification>$/.test(content.trim())) continue;
+      taskNotification = content;
+    }
+    if (typeof taskNotification === "string" && /^<task-notification>\s[\s\S]*<\/task-notification>$/.test(taskNotification.trim())) {
       const field = (name) => {
-        const matches = [...content.matchAll(new RegExp(`<${name}>([^<>]+)</${name}>`, "g"))];
+        const matches = [...taskNotification.matchAll(new RegExp(`<${name}>([^<>]+)</${name}>`, "g"))];
         return matches.length === 1 ? matches[0][1] : null;
       };
       const taskId = field("task-id");
       if (!outstanding.has(taskId) || outstanding.get(taskId) !== field("tool-use-id")
-        || !["completed", "failed", "killed"].includes(field("status"))) continue;
-      outstanding.delete(taskId);
+        || !["completed", "failed", "killed"].includes(field("status"))) {
+        if (role === "user") continue;
+      } else outstanding.delete(taskId);
     }
     if (typeof entry.uuid !== "string" || !entry.uuid.trim()) continue;
     if (role === "assistant" && Array.isArray(content)) {

package/src/remote-codex-receiver.mjs

@@ -0,0 +1,17 @@
+import { forwardRemoteRequest } from "./remote-codex.mjs";
+
+const chunks = [];
+let bytes = 0;
+for await (const chunk of process.stdin) {
+  bytes += chunk.length;
+  if (bytes > 128 * 1024) throw new Error("Remote request exceeds its limit");
+  chunks.push(chunk);
+}
+let request;
+try {
+  request = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  const result = await forwardRemoteRequest(request);
+  process.stdout.write(JSON.stringify({ version: 1, ok: true, action: request.action, requestId: request.requestId ?? null, result }) + "\n");
+} catch (error) {
+  process.stdout.write(JSON.stringify({ version: 1, ok: false, action: request?.action, requestId: request?.requestId ?? null, error: { code: error.code ?? "REMOTE_FAILED", message: error.message } }) + "\n");
+}

package/src/remote-codex-tools.mjs

@@ -0,0 +1,62 @@
+import os from "node:os";
+import { z } from "zod";
+import { resolveCodexSenderContext } from "./codex-sender-context.mjs";
+import { readCodexAccountContext } from "./codex-account-context.mjs";
+import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
+import { decodeNativeToolResult } from "./native-relay.mjs";
+import { exchangeRemoteRequest, readRemoteProfile, remoteFailure, repositoryIdentity, sameRemoteProfile, validateRemoteRequest } from "./remote-codex.mjs";
+
+export function registerRemoteCodexTools(mcp, { nativeTools, runtime, reload,
+  resolveSender = resolveCodexSenderContext, readAccount = readCodexAccountContext,
+  readProfile = readRemoteProfile, captureScope = captureProjectScope, recheckScope = recheckProjectScope,
+  repositoryIdentityOf = repositoryIdentity, exchange = exchangeRemoteRequest, hostname = os.hostname,
+}) {
+  mcp.registerTool("remote_codex", {
+    title: "Send to Codex Desktop on another computer",
+    description: "List, read or message existing Codex Desktop tasks through an explicitly configured SSH host. Requires bridge-remote-hosts.json and live host-supplied sender metadata. Each computer may use a different Codex account; the current accounts are rediscovered per call and cannot change during delivery. Select the exact saved project and task from list before send. Send requires Full access and a fresh UUID requestId; retain that ID after uncertainty, because retries only recover the durable receipt and never dispatch twice. Submitted means accepted, not completed; use read to verify the reply. Only send work explicitly authorized by the user. This does not delegate to Claude or run an external app-server.",
+    inputSchema: {
+      host: z.string().min(1).max(64).describe("Exact host name from bridge-remote-hosts.json"),
+      action: z.enum(["list", "read", "send"]).describe("List matching tasks, read a selected task, or send an authorized message"),
+      threadId: z.string().uuid().optional().describe("Exact remote task id from list; required for read and send"),
+      message: z.string().min(1).max(50000).optional().describe("Authorized prompt for send; retain exactly on receipt recovery"),
+      requestId: z.string().uuid().optional().describe("Fresh v4 UUID for a new send; preserve on retries"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  }, async (args, extra) => reload.run(async () => {
+    try {
+      runtime.assertCurrent();
+      const readSender = () => resolveSender(extra?._meta, { inspectDesktopTask: async (threadId) => {
+        const result = decodeNativeToolResult(await nativeTools.dispatchDesktop({ executorThreadId: threadId, operation: "read_thread", arguments: { threadId, hostId: "local", turnLimit: 1, includeOutputs: false, maxOutputCharsPerItem: 1 } }));
+        return { thread: result.thread, latestTurnId: result.turns?.[0]?.id ?? null };
+      } });
+      const sender = await readSender();
+      if (sender.status !== "verified") throw remoteFailure("CODEX_SENDER_CONTEXT_UNVERIFIED", sender.reason);
+      if (args.action === "send" && sender.mode !== "bypass") throw remoteFailure("REMOTE_SENDER_PERMISSION", "Remote sending requires this Codex turn to use Full access; no permissions were changed");
+      const account = readAccount();
+      if (account.status !== "verified") throw remoteFailure("REMOTE_ACCOUNT_UNVERIFIED", account.reason);
+      const profile = readProfile(args.host);
+      const scope = captureScope(sender.cwd, profile.localCwd);
+      const repository = repositoryIdentityOf(profile.localCwd);
+      const check = async () => {
+        runtime.assertCurrent();
+        const current = await readSender();
+        if (current.status !== "verified" || ["threadId", "turnId", "cwd", "mode"].some((key) => current[key] !== sender[key])) throw remoteFailure("CODEX_SENDER_CHANGED", "The sending Codex turn changed; inspect the destination before retrying");
+        const currentAccount = readAccount();
+        if (currentAccount.status !== "verified" || currentAccount.fingerprint !== account.fingerprint) throw remoteFailure("REMOTE_ACCOUNT_CHANGED", "The sending Codex account changed");
+        sameRemoteProfile(profile, readProfile(args.host));
+        recheckScope(scope);
+        if (repositoryIdentityOf(profile.localCwd) !== repository) throw remoteFailure("REMOTE_PROJECT_CHANGED", "The sending repository changed");
+      };
+      await check();
+      const request = { version: 1, action: args.action, cwd: profile.remoteCwd, repository, account: account.fingerprint,
+        sender: { threadId: sender.threadId, mode: sender.mode, host: hostname() },
+        ...(args.threadId ? { threadId: args.threadId } : {}), ...(args.message ? { message: args.message } : {}), ...(args.requestId ? { requestId: args.requestId } : {}) };
+      validateRemoteRequest(request);
+      const result = await exchange(profile, request);
+      await check();
+      return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result };
+    } catch (error) {
+      return { isError: true, content: [{ type: "text", text: `${error.code ?? "REMOTE_FAILED"}: ${error.message}` }] };
+    }
+  }));
+}

package/src/remote-codex.mjs

@@ -0,0 +1,281 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import net from "node:net";
+import { execFileSync, spawn } from "node:child_process";
+import { isDeepStrictEqual } from "node:util";
+import { relaySocketPath, resolveRelayThreadId, validateDesktopOperation, decodeNativeToolResult } from "./native-relay.mjs";
+import { readCodexAccountContext } from "./codex-account-context.mjs";
+import { NativeCreationReceipts, creationIdValid, creationRequestHash } from "./native-creation-receipts.mjs";
+import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
+import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
+
+const LIMIT = 128 * 1024;
+const ID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const HASH = /^[a-f0-9]{64}$/;
+const ownObject = (value) => value && typeof value === "object" && !Array.isArray(value);
+const cleanPath = (value) => typeof value === "string" && value.length <= 4096 && !/[\0\r\n]/.test(value);
+const home = (env) => env.CODEX_HOME ?? path.join(env.HOME || env.USERPROFILE || os.homedir(), ".codex");
+export const remoteCodexSocketPath = (env = process.env) => `${relaySocketPath(env)}-codex-remote-v1`;
+
+export function currentRemoteAccount() {
+  const account = readCodexAccountContext();
+  if (account.status !== "verified") throw remoteFailure("REMOTE_ACCOUNT_UNVERIFIED", account.reason);
+  return { codex: account.fingerprint };
+}
+
+export function assertRemoteAccount(expected) {
+  if (currentRemoteAccount().codex !== expected.codex) throw remoteFailure("REMOTE_ACCOUNT_CHANGED", "The receiving Codex account changed during this operation");
+}
+
+export function remoteNativeAdapter(nativeTools, env = process.env) {
+  return { async requestDesktop(operation, args, { beforeSend }) {
+    validateDesktopOperation(operation, args);
+    const result = await nativeTools.dispatchDesktop({ executorThreadId: resolveRelayThreadId(env).threadId, operation, arguments: args }, { beforeSend });
+    return { result: decodeNativeToolResult(result) };
+  } };
+}
+
+export function forwardRemoteRequest(request, { env = process.env, timeoutMs = 30000, socketPath = remoteCodexSocketPath(env) } = {}) {
+  validateRemoteRequest(request);
+  return new Promise((resolve, reject) => {
+    const socket = net.connect({ path: socketPath });
+    let output = Buffer.alloc(0), settled = false;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer); socket.destroy();
+      if (error) reject(error); else resolve(result);
+    };
+    const uncertain = () => remoteFailure("REMOTE_DELIVERY_UNCONFIRMED", "The Codex remote companion did not confirm delivery. Keep the requestId and inspect the destination; no fallback or resend was attempted");
+    const timer = setTimeout(() => finish(uncertain()), timeoutMs);
+    socket.on("error", () => finish(uncertain()));
+    socket.on("close", () => { if (!settled) finish(uncertain()); });
+    socket.on("connect", () => socket.write(JSON.stringify(request) + "\n"));
+    socket.on("data", (chunk) => {
+      output = Buffer.concat([output, chunk]);
+      if (output.length > 4 * 1024 * 1024) return finish(uncertain());
+      const end = output.indexOf(10);
+      if (end < 0) return;
+      try {
+        const response = JSON.parse(output.subarray(0, end).toString("utf8"));
+        if (response.version !== 1 || response.action !== request.action || response.requestId !== (request.requestId ?? null)) throw uncertain();
+        if (!response.ok) throw remoteFailure(response.error?.code ?? "REMOTE_FAILED", response.error?.message ?? "Remote Codex refused the request");
+        finish(null, response.result);
+      } catch (error) { finish(error); }
+    });
+  });
+}
+
+export async function remoteRequestResponse(request, options) {
+  try {
+    const result = await handleRemoteRequest(request, options);
+    return { version: 1, ok: true, action: request.action, requestId: request.requestId ?? null, result };
+  } catch (error) {
+    return { version: 1, ok: false, action: request?.action, requestId: request?.requestId ?? null, error: { code: error.code ?? "REMOTE_FAILED", message: error.message } };
+  }
+}
+
+export function remoteFailure(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+export function repositoryIdentity(cwd) {
+  const value = execFileSync("git", ["-C", cwd, "config", "--get", "remote.origin.url"], { encoding: "utf8", timeout: 5000, windowsHide: true }).trim();
+  const scp = value.includes("://") ? null : value.match(/^(?:[^@/:]+@)?([^/:]+):([^/].*)$/);
+  let url;
+  try { url = new URL(scp ? `ssh://${scp[1]}/${scp[2]}` : value); }
+  catch { throw remoteFailure("REMOTE_PROJECT_UNVERIFIED", "The project needs a canonical network origin URL"); }
+  if (!["https:", "ssh:"].includes(url.protocol) || url.password || url.protocol === "https:" && url.username || url.search || url.hash) throw remoteFailure("REMOTE_PROJECT_UNVERIFIED", "The project origin is unsupported");
+  const name = url.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "");
+  if (!name || name.split("/").some((part) => !part || part === "." || part === "..")) throw remoteFailure("REMOTE_PROJECT_UNVERIFIED", "The project origin path is invalid");
+  return `${url.hostname.toLowerCase()}${url.port ? `:${url.port}` : ""}/${name}`;
+}
+
+export function readRemoteProfile(name, { env = process.env } = {}) {
+  if (typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name)) throw remoteFailure("REMOTE_HOST_INVALID", "Choose an exact configured remote host name");
+  const root = home(env);
+  if (!cleanPath(root) || !path.isAbsolute(root)) throw remoteFailure("REMOTE_CONFIG_UNSAFE", "Codex configuration directory must be absolute");
+  const directory = fs.realpathSync.native(root);
+  const file = path.resolve(directory, "bridge-remote-hosts.json");
+  if (!file.startsWith(directory + path.sep)) throw remoteFailure("REMOTE_CONFIG_UNSAFE", "Remote host configuration is outside Codex home");
+  const safe = (entry) => entry.isFile() && !entry.isSymbolicLink() && entry.nlink === 1n && entry.size <= BigInt(LIMIT)
+    && (process.platform === "win32" || entry.uid === BigInt(process.getuid()) && !(entry.mode & 0o077n));
+  const same = (left, right) => ["dev", "ino", "size", "mode", "uid", "nlink", "mtimeNs", "ctimeNs"].every((key) => left[key] === right[key]);
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+  let config;
+  try {
+    const opened = fs.fstatSync(descriptor, { bigint: true });
+    const stat = fs.lstatSync(file, { bigint: true });
+    if (!safe(opened) || !safe(stat)) throw remoteFailure("REMOTE_CONFIG_UNSAFE", "Remote host configuration must be a private regular file");
+    if (!same(stat, opened)) throw remoteFailure("REMOTE_CONFIG_CHANGED", "Remote host configuration changed after opening");
+    const data = Buffer.alloc(Number(opened.size));
+    let offset = 0;
+    while (offset < data.length) {
+      const count = fs.readSync(descriptor, data, offset, data.length - offset, offset);
+      if (!count) throw remoteFailure("REMOTE_CONFIG_CHANGED", "Remote host configuration changed during reading");
+      offset += count;
+    }
+    const current = fs.lstatSync(file, { bigint: true });
+    if (!safe(current) || !same(opened, fs.fstatSync(descriptor, { bigint: true })) || !same(opened, current)
+        || fs.realpathSync.native(root) !== directory) throw remoteFailure("REMOTE_CONFIG_CHANGED", "Remote host configuration changed during reading");
+    config = JSON.parse(data.toString("utf8"));
+  } finally { fs.closeSync(descriptor); }
+  const profile = config.version === 1 && Object.hasOwn(config.hosts ?? {}, name) ? config.hosts[name] : null;
+  if (!ownObject(profile) || Object.keys(profile).sort().join() !== ["sshHost", "node", "receiver", "localCwd", "remoteCwd"].sort().join()
+      || typeof profile.sshHost !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(profile.sshHost)
+      || ![profile.node, profile.receiver, profile.remoteCwd].every((value) => cleanPath(value) && path.posix.isAbsolute(value))
+      || !cleanPath(profile.localCwd) || !path.isAbsolute(profile.localCwd)) throw remoteFailure("REMOTE_CONFIG_INVALID", "Remote host needs an SSH alias, absolute POSIX runtime/receiver/project paths and an absolute local project path");
+  return Object.freeze({ ...profile });
+}
+
+export function validateRemoteRequest(request) {
+  if (!ownObject(request) || Object.keys(request).some((key) => !["version", "action", "cwd", "repository", "account", "sender", "threadId", "message", "requestId"].includes(key))
+      || request.version !== 1 || !["list", "read", "send"].includes(request.action)
+      || !cleanPath(request.cwd) || !path.isAbsolute(request.cwd)
+      || typeof request.repository !== "string" || request.repository.length > 4096 || !HASH.test(request.account)
+      || !ownObject(request.sender) || Object.keys(request.sender).sort().join() !== ["host", "threadId", "mode"].sort().join()
+      || !ID.test(request.sender.threadId) || !["bypass", "prompting"].includes(request.sender.mode)
+      || typeof request.sender.host !== "string" || !/^[A-Za-z0-9_.-]{1,255}$/.test(request.sender.host)
+      || request.action !== "list" && !ID.test(request.threadId)
+      || request.action === "send" && (!creationIdValid(request.requestId) || typeof request.message !== "string" || !request.message.trim() || request.message.length > 50000)
+      || request.action !== "send" && (request.message !== undefined || request.requestId !== undefined)
+      || request.action === "list" && request.threadId !== undefined
+      || Buffer.byteLength(JSON.stringify(request)) > LIMIT) throw remoteFailure("REMOTE_REQUEST_INVALID", "Invalid remote Codex request");
+  if (request.action === "send" && request.sender.mode !== "bypass") throw remoteFailure("REMOTE_SENDER_PERMISSION", "Remote sending requires a verified Full access Codex turn; no permission setting was changed");
+  return request;
+}
+
+export function remoteSshArguments(profile) {
+  const quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+  const command = `${quote(profile.node)} ${quote(profile.receiver)}`;
+  return ["-T", "-o", "BatchMode=yes", "-o", "StrictHostKeyChecking=yes", "-o", "ConnectTimeout=10", "-o", "ClearAllForwardings=yes", "-o", "PermitLocalCommand=no", "--", profile.sshHost, `zsh -lc ${quote(command)}`];
+}
+
+export function exchangeRemoteRequest(profile, request, { spawnProcess = spawn, timeoutMs = 35000 } = {}) {
+  const input = JSON.stringify(request);
+  if (Buffer.byteLength(input) > LIMIT) throw remoteFailure("REMOTE_REQUEST_INVALID", "Remote request exceeds its limit");
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess("ssh", remoteSshArguments(profile), { shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+    let output = "", size = 0, settled = false;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) { child.kill(); reject(error); } else resolve(value);
+    };
+    const uncertain = () => remoteFailure("REMOTE_DELIVERY_UNCONFIRMED", "SSH did not confirm the result. Keep the same requestId and inspect the existing destination; do not send a new request");
+    const timer = setTimeout(() => finish(uncertain()), timeoutMs);
+    child.on("error", () => finish(uncertain()));
+    child.stdin.on("error", () => finish(uncertain()));
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      size += Buffer.byteLength(chunk);
+      if (size > 4 * 1024 * 1024) return finish(uncertain());
+      output += chunk;
+    });
+    child.stderr.resume();
+    child.on("close", (code) => {
+      if (code !== 0) return finish(uncertain());
+      try {
+        const response = JSON.parse(output);
+        if (response.version !== 1 || response.action !== request.action || response.requestId !== (request.requestId ?? null)) throw uncertain();
+        if (!response.ok) return finish(remoteFailure(response.error?.code ?? "REMOTE_FAILED", response.error?.message ?? "Remote Codex refused the request"));
+        finish(null, response.result);
+      } catch (error) { finish(error); }
+    });
+    child.stdin.end(input + "\n");
+  });
+}
+
+export async function handleRemoteRequest(request, {
+  env = process.env,
+  readAccounts = currentRemoteAccount,
+  assertAccounts = assertRemoteAccount,
+  repository = repositoryIdentity,
+  canonical = (value) => fs.realpathSync.native(value),
+  captureScope = captureProjectScope,
+  recheckScope = recheckProjectScope,
+  relay,
+  rootPolicy = createHardenedRootPolicy(env),
+  receipts = new NativeCreationReceipts({ directory: path.join(home(env), "bridge-remote-deliveries"), accountProviders: ["codex"] }),
+  executor = () => resolveRelayThreadId(env).threadId,
+} = {}) {
+  validateRemoteRequest(request);
+  const accounts = readAccounts();
+  if (!accounts || Object.keys(accounts).join() !== "codex" || !HASH.test(accounts.codex)) throw remoteFailure("REMOTE_ACCOUNT_UNVERIFIED", "No current receiving Codex account was verified");
+  const cwd = canonical(request.cwd);
+  const scope = captureScope(cwd, cwd);
+  const check = () => {
+    assertAccounts(accounts);
+    rootPolicy.assert(cwd, "Remote Codex project");
+    recheckScope(scope);
+    if (canonical(request.cwd) !== cwd || repository(cwd) !== request.repository) throw remoteFailure("REMOTE_PROJECT_MISMATCH", "The remote project differs from the verified sender repository");
+  };
+  check();
+  const call = async (operation, args, guard = check) => {
+    check();
+    const { result } = await relay.requestDesktop(operation, args, { beforeSend: guard });
+    check();
+    return result;
+  };
+  const project = async () => {
+    const result = await call("list_projects", {});
+    const matches = (result?.projects ?? []).filter((item) => item.projectKind === "local" && item.hostId === "local" && exactCwd(item.path));
+    if (matches.length !== 1 || !matches[0].projectId) throw remoteFailure("REMOTE_PROJECT_UNVERIFIED", "Select exactly one existing saved Codex project on the remote computer");
+    return matches[0].projectId;
+  };
+  const exactCwd = (value) => {
+    try { return typeof value === "string" && canonical(value) === cwd; } catch { return false; }
+  };
+  const projectId = await project();
+  const matchesIdentity = (thread) => thread?.kind === "codex" && thread.hostId === "local" && exactCwd(thread.cwd);
+  const matches = (thread) => matchesIdentity(thread) && thread.projectId === projectId;
+  const listedThreads = async () => {
+    const result = await call("list_threads", { limit: 50 });
+    return [...(result?.pinnedThreads ?? []), ...(result?.threads ?? [])];
+  };
+  if (request.action === "list") {
+    const threads = (await listedThreads()).filter(matches)
+      .map(({ id, title, status }) => ({ id, title, status, cwd, projectId }));
+    return { threads, coverage: "Most recent 50 unpinned tasks plus pinned tasks in the exact saved project" };
+  }
+  const inspect = async (includeOutputs = false) => {
+    if (await project() !== projectId) throw remoteFailure("REMOTE_PROJECT_MISMATCH", "The destination saved project changed");
+    const result = await call("read_thread", { threadId: request.threadId, hostId: "local", turnLimit: 2, includeOutputs, maxOutputCharsPerItem: includeOutputs ? 6000 : 1 });
+    const thread = result?.thread;
+    if (!matchesIdentity(thread) || thread.id !== request.threadId || (thread.projectId !== undefined && thread.projectId !== projectId)) throw remoteFailure("REMOTE_THREAD_MISMATCH", "The target task does not belong to the exact saved project");
+    const listed = (await listedThreads()).filter((item) => item.id === request.threadId);
+    if (listed.length !== 1 || !matches(listed[0])) throw remoteFailure("REMOTE_THREAD_MISMATCH", "The target task is no longer listed in the exact saved project");
+    return result;
+  };
+  if (request.action === "read") return inspect(true);
+  await inspect();
+  const executorId = executor();
+  if (request.threadId === executorId) throw remoteFailure("REMOTE_THREAD_MISMATCH", "The relay executor cannot be a handoff destination");
+  const hash = creationRequestHash(request);
+  const existing = receipts.read(request.requestId, accounts, hash);
+  if (existing) return { requestId: request.requestId, threadId: request.threadId, status: existing.state === "completed" ? "submitted" : "unconfirmed", result: existing.result ?? null, duplicate: true };
+  let row;
+  try { row = receipts.reserve(request.requestId, request, accounts, executorId); }
+  catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    receipts.read(request.requestId, accounts, hash);
+    return { requestId: request.requestId, threadId: request.threadId, status: "unconfirmed", duplicate: true };
+  }
+  try {
+    await inspect();
+    const prompt = `[From Codex on ${request.sender.host} · task ${request.sender.threadId}]\n\n${request.message}`;
+    const result = await call("send_message_to_thread", { threadId: request.threadId, prompt }, async () => { await inspect(); check(); });
+    await inspect();
+    receipts.write({ ...row, state: "completed", result });
+    return { requestId: request.requestId, threadId: request.threadId, status: "submitted", result, duplicate: false };
+  } catch (error) {
+    receipts.write({ ...row, state: "failed", error: { code: error.code ?? "REMOTE_FAILED", message: error.message } });
+    throw remoteFailure("REMOTE_DELIVERY_UNCONFIRMED", "The send was reserved but its outcome was not confirmed. Inspect this task with read; reuse the original requestId only to recover its receipt");
+  }
+}
+
+export function sameRemoteProfile(left, right) {
+  if (!isDeepStrictEqual(left, right)) throw remoteFailure("REMOTE_CONFIG_CHANGED", "The remote host profile changed during the operation");
+}

package/src/windows-pipe-acl.mjs

@@ -16,7 +16,9 @@ export async function protectCurrentUserPipe(socketPath, { pid = process.pid, ru
   if (!IS_WINDOWS) return { skipped: true };
   const name = bridgePipeName(socketPath);
   const script = fileURLToPath(new URL("./windows-pipe-acl.ps1", import.meta.url));
-  const { stdout } = await run(powershell, ["-NoProfile", "-NonInteractive", "-File", script, "-PipeName", name, "-ServerPid", String(pid)], { windowsHide: true, timeout: 15000 });
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => key.toLowerCase() !== "psmodulepath"));
+  env.PSModulePath = "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\Modules";
+  const { stdout } = await run(powershell, ["-NoProfile", "-NonInteractive", "-File", script, "-PipeName", name, "-ServerPid", String(pid)], { env, windowsHide: true, timeout: 15000 });
   let result;
   try { result = JSON.parse(stdout.trim()); } catch { throw new Error("Windows pipe ACL helper returned invalid readback"); }
   if (result?.serverMatches !== true || result?.serverUserMatches !== true || result?.ownerMatches !== true || result?.protected !== true || result?.aceCount !== 1