@minhspark/codex-mcp-bridge 1.16.0 → 1.16.1

package/src/peer-protocol.mjs

@@ -7,6 +7,8 @@ import path from "node:path";
 
 import { homeDir, IS_WINDOWS } from "./platform.mjs";
 import { cloneReloadState } from "./reload-control.mjs";
+import { hardenedBridgeEnabled } from "./hardened-root-policy.mjs";
+import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
 
 const SOCKET_DIR = "/tmp/cc-socks";
 
@@ -100,6 +102,8 @@ function readPeerToken(socket) {
     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 = readPeerProcessIdentity(key);
+    const hasIdentity = Object.hasOwn(key, "procStart") || (IS_WINDOWS && Object.hasOwn(key, "procStartFt"));
+    if (!identity && (hasIdentity || (IS_WINDOWS && hardenedBridgeEnabled()))) throw new Error("Peer process identity missing or invalid");
     if (identity && identity !== readProcessStart(candidates[0].pid)) throw new Error("Peer process identity changed");
     return key.peerToken;
   } catch {
@@ -247,7 +251,7 @@ export function assertClaudeSessionCwd(session, expectedCwd) {
 }
 
 export function assertClaudeSessionProcess(session) {
-  if (!session.alive || typeof session.processStart !== "string" || !session.processStart ||
+  if (!session?.alive || typeof session.processStart !== "string" || !session.processStart ||
       readProcessStart(session.pid) !== session.processStart) {
     throw new Error("The live Claude process identity is missing or changed. No message was sent; reopen the existing Desktop task and inspect its session again.");
   }
@@ -383,7 +387,7 @@ export function readTranscriptReply(sessionId, cwd, msgId) {
  * answer on and the conversation stays one-way.
  */
 export class PeerEndpoint {
-  constructor({ name = `codex-${process.pid}`, cwd = process.cwd(), log = () => {} } = {}) {
+  constructor({ name = `codex-${process.pid}`, cwd = process.cwd(), log = () => {}, env = process.env, protectSocket } = {}) {
     this.name = name;
     this.cwd = cwd;
     this.log = log;
@@ -408,6 +412,13 @@ export class PeerEndpoint {
     this.activityRevision = 0;
     this.reloadPaused = false;
     this.processHandlersRegistered = false;
+    this.strict = hardenedBridgeEnabled(env);
+    this.protectSocket = protectSocket ?? (hardenedBridgeEnabled(env) ? protectCurrentUserPipe : null);
+    this.aclReady = !IS_WINDOWS || !this.protectSocket;
+    this.provisionalSockets = new Set();
+    this.startGeneration = 0;
+    this.startPromise = null;
+    this.closed = Promise.resolve();
   }
 
   /**
@@ -437,9 +448,19 @@ export class PeerEndpoint {
     }
   }
 
-  async start() {
+  start() {
     if (this.reloadPaused) throw new Error("The peer endpoint is quiesced for reload");
     if (this.started) return;
+    if (this.startPromise) return this.startPromise;
+    const starting = this.#startOnce();
+    const shared = starting.finally(() => {
+      if (this.startPromise === shared) this.startPromise = null;
+    });
+    this.startPromise = shared;
+    return shared;
+  }
+
+  async #startOnce() {
     this.#sweepDeadBridges();
     const procStart = readProcessStart(this.pid);
     const peerToken = crypto.randomBytes(16).toString("hex");
@@ -450,12 +471,34 @@ export class PeerEndpoint {
     fs.mkdirSync(sessionsDir(), { recursive: true });
     if (!IS_WINDOWS && fs.existsSync(this.socketPath)) fs.rmSync(this.socketPath, { force: true });
 
+    const generation = ++this.startGeneration;
+    this.aclReady = !IS_WINDOWS || !this.protectSocket;
     await new Promise((resolve, reject) => {
       this.server = net.createServer((socket) => this.#handleConnection(socket));
       this.server.on("error", reject);
       this.server.listen(this.socketPath, resolve);
     });
     if (!IS_WINDOWS) fs.chmodSync(this.socketPath, 0o600);
+    if (IS_WINDOWS && this.protectSocket) {
+      try {
+        await this.protectSocket(this.socketPath);
+        if (generation !== this.startGeneration) throw new Error("Peer pipe ACL startup was cancelled");
+        this.aclReady = true;
+        for (const socket of this.provisionalSockets) socket.destroy();
+        this.provisionalSockets.clear();
+      } catch (error) {
+        for (const socket of this.provisionalSockets) socket.destroy();
+        this.provisionalSockets.clear();
+        await this.#closeServer();
+        throw error;
+      }
+    }
+    if (generation !== this.startGeneration) {
+      for (const socket of this.provisionalSockets) socket.destroy();
+      this.provisionalSockets.clear();
+      await this.#closeServer();
+      throw new Error("Peer endpoint startup was cancelled");
+    }
 
     const processIdentity = procStart ? (IS_WINDOWS ? { procStart, procStartFt: procStart } : { procStart }) : {};
     this.registry = {
@@ -490,7 +533,26 @@ export class PeerEndpoint {
     this.log(`peer "${this.name}" listening on ${this.socketPath}`);
   }
 
+  #closeServer() {
+    const server = this.server;
+    return new Promise((resolve) => {
+      if (!server) return resolve();
+      try {
+        if (!server.listening) return resolve();
+        server.close(() => resolve());
+      } catch {
+        resolve();
+      }
+    });
+  }
+
   #handleConnection(socket) {
+    if (IS_WINDOWS && !this.aclReady) {
+      this.provisionalSockets.add(socket);
+      socket.once("close", () => this.provisionalSockets.delete(socket));
+      socket.once("error", () => {});
+      return;
+    }
     this.activityRevision += 1;
     this.connections.add(socket);
     socket.once("close", () => this.connections.delete(socket));
@@ -554,18 +616,25 @@ export class PeerEndpoint {
   }
 
   #receiveMessage(message) {
+    const key = message.inReplyTo ?? [...this.pendingMessages].find(([, entry]) => entry.targetSocket === message.fromSocket)?.[0];
+    const pending = this.pendingMessages.get(key);
+    const correlated = pending && (!pending.transcriptSession || (message.source === "transcript" && message.inReplyTo === key));
+    if (this.strict && !(key && correlated && pending.targetSocket === message.fromSocket)) {
+      this.log(`ignored uncorrelated inbound peer message from ${message.fromSocket ?? "?"} in hardened mode`);
+      return;
+    }
     this.activityRevision += 1;
     const record = { ...message, receivedAt: Date.now(), sequence: ++this.messageSequence };
     this.inbox.push(record);
-    const key = record.inReplyTo ?? [...this.pendingMessages].find(([, entry]) => entry.targetSocket === record.fromSocket)?.[0];
-    const pending = this.pendingMessages.get(key);
-    const correlated = pending && (!pending.transcriptSession || (record.source === "transcript" && record.inReplyTo === key));
     if (key && correlated && pending.targetSocket === record.fromSocket) {
       const sent = this.sentMessages.get(key);
       if (sent) {
         record.inReplyTo = key;
         record.replyThreadId = sent.replyThreadId ?? null;
         record.accountContext = sent.accountContext ?? null;
+        record.cwd = sent.transcriptSession?.cwd ?? null;
+        record.senderCwd = sent.scopeBindings?.sender?.path ?? null;
+        record.scopeBindings = sent.scopeBindings ?? null;
         sent.reply = record;
       }
       this.#removePendingReply(record.fromSocket, key);
@@ -683,7 +752,7 @@ export class PeerEndpoint {
     return frame.msg_id;
   }
 
-  async sendAndWait(targetSocket, text, { timeoutMs = 120000, priority = "next", transcriptSession, beforeSend, permissionMode = this.permissionMode, replyThreadId, senderReview, senderApprovalPolicy, recipient, accountContext } = {}) {
+  async sendAndWait(targetSocket, text, { timeoutMs = 120000, priority = "next", transcriptSession, beforeSend, permissionMode = this.permissionMode, replyThreadId, senderReview, senderApprovalPolicy, recipient, accountContext, scopeBindings } = {}) {
     const previous = this.requestQueues.get(targetSocket) ?? Promise.resolve();
     const pending = previous.catch(() => {}).then(async () => {
       await beforeSend?.();
@@ -701,7 +770,7 @@ export class PeerEndpoint {
       this.unconfirmedReplies.set(targetSocket, unconfirmed + 1);
       let msgId = crypto.randomUUID();
       this.pendingMessages.set(msgId, { targetSocket, transcriptSession });
-      this.sentMessages.set(msgId, { targetSocket, transcriptSession, sentAt: since, replyThreadId, permissionMode, senderApprovalPolicy, ...(senderReview ? { senderReview: { ...senderReview } } : {}), ...(recipient ? { recipient: { ...recipient } } : {}), ...(accountContext ? { accountContext: Object.freeze({ ...accountContext }) } : {}) });
+      this.sentMessages.set(msgId, { targetSocket, transcriptSession, sentAt: since, replyThreadId, permissionMode, senderApprovalPolicy, ...(senderReview ? { senderReview: { ...senderReview } } : {}), ...(recipient ? { recipient: { ...recipient } } : {}), ...(accountContext ? { accountContext: Object.freeze({ ...accountContext }) } : {}), ...(scopeBindings ? { scopeBindings: Object.freeze(structuredClone(scopeBindings)) } : {}) });
       if (transcriptSession && !this.responsePoll) {
         this.responsePoll = globalThis.setInterval(() => this.#refreshTranscriptReplies(), 250);
         this.responsePoll.unref();
@@ -815,6 +884,7 @@ export class PeerEndpoint {
       ...(sent.recipient ? { recipientPermissionMode: sent.recipient.permissionMode ?? null, recipientPermissionClass: sent.recipient.permissionClass ?? null, recipientInboundPolicy: sent.recipient.inboundPolicy ?? null } : {}),
       replyThreadId: sent.replyThreadId ?? null,
       ...(sent.accountContext ? { accountContext: { ...sent.accountContext } } : {}),
+      ...(sent.scopeBindings ? { scopeBindings: structuredClone(sent.scopeBindings), senderCwd: sent.scopeBindings.sender?.path ?? null } : {}),
       pending: this.pendingMessages.has(msgId),
       ...(sent.reply ? { reply: sent.reply.text, source: sent.reply.source ?? "peer", ...(sent.reply.absorbed ? { replyAbsorbed: true } : {}), ...(sent.reply.forwardingError ? { forwardingError: { ...sent.reply.forwardingError } } : {}) } : {}),
     };
@@ -900,12 +970,19 @@ export class PeerEndpoint {
   }
 
   stop() {
+    this.startGeneration += 1;
+    this.aclReady = !IS_WINDOWS || !this.protectSocket;
+    for (const socket of this.provisionalSockets) socket.destroy();
+    this.provisionalSockets.clear();
     globalThis.clearInterval(this.responsePoll);
     this.responsePoll = null;
     this.pendingMessages.clear();
-    try {
-      this.server?.close();
-    } catch {}
+    const server = this.server;
+    this.closed = new Promise((resolve) => {
+      if (!server) return resolve();
+      try { server.close(() => resolve()); }
+      catch { resolve(); }
+    });
     for (const socket of this.connections) socket.destroy();
     this.connections.clear();
     this.#removeRegistration();

package/src/reply-forwarder.mjs

@@ -93,10 +93,17 @@ export class ReplyForwarder {
     return entry ? { ...entry.receipt } : null;
   }
 
-  status() {
+  status(accepts = () => true) {
     const counts = { total: this.records.size, queued: 0, sending: 0, forwarded: 0, failed: 0, unknown: 0, blocked: 0 };
-    for (const { receipt } of this.records.values()) counts[receipt.status] += 1;
-    return { ...counts, attempts: this.attempts, maxPerSession: this.maxPerSession, closed: this.closed };
+    counts.total = 0;
+    let attempts = 0;
+    for (const { record, receipt } of this.records.values()) {
+      if (!accepts(record, receipt)) continue;
+      counts.total += 1;
+      counts[receipt.status] += 1;
+      if (Number.isFinite(receipt.attemptedAt)) attempts += 1;
+    }
+    return { ...counts, attempts, maxPerSession: this.maxPerSession, closed: this.closed };
   }
 
   reloadReason() {

package/src/security-policy.mjs

@@ -1,5 +1,6 @@
 import { realpathSync } from "node:fs";
 import path from "node:path";
+import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 
 const APPROVAL_POLICIES = new Set(["untrusted", "on-failure", "on-request", "never"]);
 const SANDBOXES = new Set(["read-only", "workspace-write"]);
@@ -84,6 +85,7 @@ export function assertAllowedAppServerUrl(value) {
 
 export class BridgeSecurityPolicy {
   constructor(env = process.env) {
+    this.hardenedRoots = createHardenedRootPolicy(env);
     const configuredThreads = parseList(env.CODEX_BRIDGE_ALLOWED_THREADS);
     this.allowAllThreads = configuredThreads.has(ALLOW_ALL_THREADS);
     this.allowedThreadIds = new Set([...configuredThreads].filter((threadId) => threadId !== ALLOW_ALL_THREADS));
@@ -189,6 +191,7 @@ export class BridgeSecurityPolicy {
   }
 
   isCwdAuthorized(cwd) {
+    if (this.hardenedRoots.enabled) return this.hardenedRoots.allows(cwd);
     if (!cwd) return false;
     if (this.allowAllRoots) return true;
     if (!this.allowedRoots.length) return false;
@@ -197,6 +200,7 @@ export class BridgeSecurityPolicy {
   }
 
   assertCwd(cwd) {
+    if (this.hardenedRoots.enabled) return this.hardenedRoots.assert(cwd);
     if (!this.allowAllRoots && !this.allowedRoots.length) {
       throw new Error(
         "No authorized workspace roots are configured. Set CODEX_BRIDGE_ALLOWED_ROOTS to one or more project directories.",

package/src/telemetry-config.mjs

@@ -0,0 +1,2 @@
+export const TELEMETRY_ENDPOINT = "https://vdbwkowdggtcihixowxi.supabase.co/functions/v1/bridge-usage";
+export const TELEMETRY_PUBLIC_KEY = "sb_publishable_2GIhGKL82wM8mN44L-Gzxw_Zgd-Vioh";

package/src/telemetry.mjs

@@ -0,0 +1,149 @@
+import { mkdir, readFile, open, rename, unlink, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export function telemetryDirectory(platform = process.platform, env = process.env, home = homedir()) {
+  const base = platform === 'win32' ? env.LOCALAPPDATA || path.join(home, 'AppData', 'Local') : platform === 'darwin' ? path.join(home, 'Library', 'Application Support') : env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+  return path.join(base, 'codex-mcp-bridge');
+}
+
+function resolveOptions(options = {}) {
+  return { directory: telemetryDirectory(), env: process.env, platform: process.platform, now: new Date(), ...options };
+}
+
+async function readSettings(directory) {
+  try {
+    const settings = JSON.parse(await readFile(path.join(directory, 'telemetry.json'), 'utf8'));
+    if (settings.enabled !== true || !uuidPattern.test(settings.installId)) return { enabled: false };
+    return settings;
+  } catch { return { enabled: false }; }
+}
+
+async function writeSettings(directory, settings) {
+  const filename = path.join(directory, 'telemetry.json');
+  const temporary = `${filename}.${randomUUID()}.tmp`;
+  let file;
+  try {
+    file = await open(temporary, 'wx', 0o600);
+    await file.writeFile(`${JSON.stringify(settings, null, 2)}\n`);
+    await file.sync();
+    await file.close();
+    file = null;
+    await rename(temporary, filename);
+  } finally {
+    await file?.close();
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+async function locked(directory, action) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const filename = path.join(directory, '.telemetry.lock');
+  let lock;
+  try {
+    lock = await open(filename, 'wx', 0o600);
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const info = await stat(filename).catch(() => null);
+    if (info && Date.now() - info.mtimeMs > 60000) {
+      await unlink(filename).catch(() => {});
+      lock = await open(filename, 'wx', 0o600);
+    } else throw new Error('Telemetry settings are busy. Retry in a few seconds.');
+  }
+  try { return await action(); }
+  finally { await lock.close(); await unlink(filename).catch(() => {}); }
+}
+
+function suppressed(env) {
+  return env.DO_NOT_TRACK === '1' || env.CODEX_BRIDGE_TELEMETRY === '0';
+}
+
+export async function getTelemetryStatus(options = {}) {
+  const opts = resolveOptions(options);
+  const settings = await readSettings(opts.directory);
+  return { enabled: settings.enabled, effective: settings.enabled && !suppressed(opts.env), suppressed: suppressed(opts.env), lastReportDay: settings.lastReportDay || null, settingsPath: path.join(opts.directory, 'telemetry.json') };
+}
+
+export async function enableTelemetry(options = {}) {
+  const opts = resolveOptions(options);
+  await locked(opts.directory, async () => {
+    const previous = await readSettings(opts.directory);
+    await writeSettings(opts.directory, previous.enabled ? previous : { enabled: true, installId: randomUUID(), consentedAt: opts.now.toISOString() });
+  });
+  return getTelemetryStatus(opts);
+}
+
+export async function disableTelemetry(options = {}) {
+  const opts = resolveOptions(options);
+  await locked(opts.directory, () => writeSettings(opts.directory, { enabled: false }));
+  return getTelemetryStatus(opts);
+}
+
+export async function reportUsage(options = {}) {
+  try {
+    const opts = resolveOptions(options);
+    if (suppressed(opts.env) || !versionPattern.test(opts.version || '')) return false;
+    if (!(await readSettings(opts.directory)).enabled) return false;
+    const platform = { win32: 'windows', darwin: 'macos', linux: 'linux' }[opts.platform];
+    if (!platform) return false;
+    return await locked(opts.directory, async () => {
+      const settings = await readSettings(opts.directory);
+      const day = opts.now.toISOString().slice(0, 10);
+      if (!settings.enabled || settings.lastReportDay === day) return false;
+      const config = opts.config || await import('./telemetry-config.mjs');
+      const endpoint = config.TELEMETRY_ENDPOINT;
+      const key = config.TELEMETRY_PUBLIC_KEY;
+      if (!endpoint || !key || new URL(endpoint).protocol !== 'https:') return false;
+      const controller = new AbortController();
+      const timeout = Math.max(1, Math.min(opts.timeoutMs || 2000, 2000));
+      let timer;
+      try {
+        const response = await Promise.race([
+          (opts.fetcher || fetch)(endpoint, {
+            method: 'POST', redirect: 'error', signal: controller.signal,
+            headers: { 'Content-Type': 'application/json', apikey: key },
+            body: JSON.stringify({ install_id: settings.installId, version: opts.version, platform, day }),
+          }),
+          new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('timeout')); }, timeout); }),
+        ]);
+        if (!response.ok) return false;
+        await writeSettings(opts.directory, { ...settings, lastReportDay: day });
+        return true;
+      } finally { clearTimeout(timer); controller.abort(); }
+    });
+  } catch { return false; }
+}
+
+export function startUsageReporting(options = {}) {
+  const initialReport = reportUsage(options);
+  const schedule = options.schedule || setInterval;
+  const cancel = options.cancel || clearInterval;
+  const timer = schedule(() => { void reportUsage(options); }, 60 * 60 * 1000);
+  timer.unref?.();
+  return { initialReport, stop: () => cancel(timer) };
+}
+
+export async function handleTelemetryCommand(args = process.argv.slice(2), options = {}) {
+  if (args[0] !== 'telemetry') return false;
+  const output = options.output || (message => process.stdout.write(`${message}\n`));
+  if (args.length !== 2 || !['enable', 'disable', 'status'].includes(args[1])) {
+    output('Usage: codex-mcp-bridge telemetry <enable|disable|status>');
+    process.exitCode = 1;
+    return true;
+  }
+  try {
+    const status = await ({ enable: enableTelemetry, disable: disableTelemetry, status: getTelemetryStatus }[args[1]])(options);
+    output(`Telemetry: ${status.effective ? 'enabled' : 'disabled'}${status.suppressed ? ' (environment override)' : ''}.`);
+    output('When enabled, sends a random installation ID, package version, OS family, and UTC day; at most once per day. No prompts, paths, account IDs, or message contents.');
+    if (args[1] === 'disable') output('Local installation ID removed. Previously submitted records remain until retention cleanup.');
+    output(`Settings: ${status.settingsPath}`);
+  } catch {
+    output('Could not update telemetry settings. Check directory permissions and retry when no telemetry request is running.');
+    process.exitCode = 1;
+  }
+  return true;
+}

package/src/thread-delivery.mjs

@@ -3,6 +3,7 @@ import { runTurn } from "./turn.mjs";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { DesktopTaskReceipts } from "./desktop-task-receipts.mjs";
+import { captureCodexRolloutWatermark, inspectCodexNativeTurn, readCodexNativeTurnResponse } from "./codex-native-response.mjs";
 
 /**
  * Which backend puts a message into a Codex thread.
@@ -23,6 +24,11 @@ export const APP_SERVER_BACKEND = "app-server";
 export const DESKTOP_TOOL_BUDGET_MS = 40000;
 const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
 
+function sameAccountContext(expected, current) {
+  return Boolean(expected && current && ["claude", "codex"].every((provider) =>
+    typeof expected[provider] === "string" && expected[provider] === current[provider]));
+}
+
 export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync.native, paths = path } = {}) {
   const requested = canonicalize(cwd);
   const matches = projects.filter((project) => {
@@ -42,7 +48,7 @@ export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync
 }
 
 export class DesktopTaskDelivery {
-  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts(), beforeRequest, accountContext } = {}) {
+  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath(), accountSocketPath: accountRelaySocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts(), beforeRequest, accountContext, captureResponse = captureCodexRolloutWatermark, readResponse = readCodexNativeTurnResponse, inspectResponse = inspectCodexNativeTurn } = {}) {
     this.relay = relay;
     this.security = security;
     this.sleep = sleep;
@@ -50,10 +56,13 @@ export class DesktopTaskDelivery {
     this.receipts = receipts;
     this.beforeRequest = beforeRequest;
     this.accountContext = accountContext;
+    this.captureResponse = captureResponse;
+    this.readResponse = readResponse;
+    this.inspectResponse = inspectResponse;
     this.threadOperations = new Map();
   }
 
-  async request(operation, args, { deadline } = {}) {
+  async request(operation, args, { deadline, includeRelayContext = false } = {}) {
     try {
       await this.beforeRequest?.({ operation, args });
       const remaining = deadline === undefined ? undefined : deadline - this.now();
@@ -64,7 +73,7 @@ export class DesktopTaskDelivery {
         ...(this.beforeRequest ? { beforeSend: () => this.beforeRequest({ operation, args, phase: "write" }) } : {}),
         ...(accountContext ? { accountContext } : {}),
       });
-      return response.result;
+      return includeRelayContext ? { result: response.result, executorThreadId: response.executorThreadId } : response.result;
     } catch (err) {
       throw new Error(`Codex Desktop operation ${operation} failed: ${err.message}. Desktop-only mode will not start or use an external app-server. Open Codex Desktop and reconnect its native relay, then inspect the existing task before retrying a send.`, { cause: err });
     }
@@ -247,17 +256,32 @@ export class DesktopTaskDelivery {
   async send({ threadId, prompt, cwd, model, effort, name, deadline }) {
     const inspected = await this.inspect(threadId, cwd, { deadline });
     if (name) await this.request("set_thread_title", { threadId, title: name.trim().slice(0, 200) }, { deadline });
-    const response = await this.request("send_message_to_thread", {
+    const expectedCwd = realpathSync.native(inspected.thread.cwd);
+    const accountContext = this.accountContext?.();
+    const watermark = this.captureResponse({ threadId, expectedCwd });
+    const envelope = await this.request("send_message_to_thread", {
       threadId, prompt,
       ...(model ? { model } : {}),
       ...(effort ? { thinking: effort } : {}),
-    }, { deadline });
+    }, { deadline, includeRelayContext: true });
+    const response = envelope.result;
     if (response?.threadId !== threadId || response?.success === false || response?.isError === true ||
         (response?.status !== undefined && !["accepted", "sent"].includes(response.status)) ||
         (response?.firstTurn && response.firstTurn.status !== "accepted")) {
       throw new Error(`Desktop send is not confirmed for ${threadId}. Do not resend: ${JSON.stringify(response)}`);
     }
-    return { threadId, cwd: inspected.thread.cwd, name: inspected.thread.title, previousTurnId: inspected.latestTurnId, backend: NATIVE_BACKEND };
+    return {
+      threadId, cwd: expectedCwd, name: inspected.thread.title, previousTurnId: inspected.latestTurnId, backend: NATIVE_BACKEND,
+      responseObservation: {
+        threadId,
+        previousTurnId: inspected.latestTurnId,
+        expectedCwd,
+        executorThreadId: envelope.executorThreadId ?? null,
+        prompt,
+        accountContext: accountContext ? { ...accountContext } : null,
+        watermark,
+      },
+    };
   }
 
   async open(threadId, { deadline } = {}) {
@@ -265,12 +289,51 @@ export class DesktopTaskDelivery {
     if (response?.navigated !== true) throw new Error(`Desktop did not confirm opening task ${threadId}`);
   }
 
-  async wait(threadId, { timeoutMs = 240000, previousTurnId = null } = {}) {
+  async observeNativeResponse(threadId, turnId, responseObservation, { deadline } = {}) {
+    if (!responseObservation) return unavailableObservation("Codex Desktop completed the turn without exposing assistant response text or a pre-send observation binding.");
+    const { expectedCwd } = responseObservation;
+    const args = { threadId, hostId: "local", turnLimit: 1 };
+    const recheck = async () => {
+      await this.beforeRequest?.({ operation: "read_thread", args, phase: "observe" });
+      if (this.accountContext && !sameAccountContext(responseObservation.accountContext, this.accountContext())) throw new Error("The original account changed while the native response was being observed; reply content was withheld");
+      this.security.assertCwd(expectedCwd);
+      this.security.assertThread(threadId, expectedCwd);
+      if (realpathSync.native(expectedCwd) !== expectedCwd) throw new Error("The selected native task workspace changed while its response was being observed");
+    };
+    await recheck();
+    const observed = this.readResponse({ ...responseObservation, threadId, turnId });
+    await recheck();
+    const inspected = await this.inspect(threadId, expectedCwd, { deadline });
+    if (inspected.latestTurnId !== turnId) throw new Error("The selected native task changed before its response could be confirmed; reply content was withheld");
+    await recheck();
+    return observed;
+  }
+
+  async inspectNativeTurn(threadId, turnId, cwd, { deadline } = {}) {
+    const initial = await this.inspect(threadId, cwd, { deadline });
+    const expectedCwd = realpathSync.native(initial.thread.cwd);
+    const accountContext = this.accountContext?.() ?? null;
+    const args = { threadId, hostId: "local", turnLimit: 1 };
+    const recheck = async () => {
+      await this.beforeRequest?.({ operation: "read_thread", args, phase: "inspect-turn" });
+      if (this.accountContext && !sameAccountContext(accountContext, this.accountContext())) throw new Error("The account changed while the native turn was being inspected; response content was withheld");
+      this.security.assertCwd(expectedCwd);
+      this.security.assertThread(threadId, expectedCwd);
+      if (realpathSync.native(expectedCwd) !== expectedCwd) throw new Error("The selected native task workspace changed while its turn was being inspected");
+    };
+    await recheck();
+    const result = this.inspectResponse({ threadId, turnId, expectedCwd });
+    await recheck();
+    await this.inspect(threadId, expectedCwd, { deadline });
+    await recheck();
+    return result;
+  }
+
+  async wait(threadId, { timeoutMs = 240000, previousTurnId = null, responseObservation = null } = {}) {
     const startedAt = this.now();
     let cursor;
     let turnId = null;
-    let text = "";
-    const expired = () => ({ threadId, turnId, status: "timeout", text, activity: [], errors: [], durationMs: this.now() - startedAt });
+    const expired = () => ({ threadId, turnId, status: "timeout", text: "", responseStatus: "unavailable", assistantItems: [], replySha256: null, activity: [], errors: [], durationMs: this.now() - startedAt });
     for (;;) {
       if (this.now() - startedAt >= timeoutMs) return expired();
       let response;
@@ -292,10 +355,21 @@ export class DesktopTaskDelivery {
       }
       if (turn?.id && turn.id !== previousTurnId) {
         turnId = turn.id;
-        if (poll.latestAssistantMessage?.turnId === turnId && poll.latestAssistantMessage?.phase === "final_answer") text = poll.latestAssistantMessage.text ?? text;
         const status = turn.status;
         if (RELEASE_STATUSES.has(status)) {
-          return { threadId, turnId, status, text, activity: [], errors: turn.error ? [turn.error] : [], durationMs: turn.durationMs ?? this.now() - startedAt };
+          const observed = await this.observeNativeResponse(threadId, turnId, responseObservation, { deadline: startedAt + timeoutMs });
+          const responseStatus = observed.status;
+          return {
+            threadId, turnId, status,
+            text: responseStatus === "completed" ? observed.text : "",
+            responseStatus,
+            observationStatus: responseStatus,
+            ...(observed.reason ? { observationReason: observed.reason } : {}),
+            assistantItems: observed.assistantItems ?? [],
+            replySha256: observed.replySha256 ?? null,
+            responseSource: observed.source ?? null,
+            activity: [], errors: turn.error ? [turn.error] : [], durationMs: turn.durationMs ?? this.now() - startedAt,
+          };
         }
       }
       if (this.now() - startedAt >= timeoutMs) return expired();
@@ -304,6 +378,10 @@ export class DesktopTaskDelivery {
   }
 }
 
+function unavailableObservation(reason) {
+  return { status: "unavailable", reason };
+}
+
 export function createThreadDelivery({
   codex,
   relay = new NativeDesktopRelay(),