@minhspark/codex-mcp-bridge 1.20.0 → 1.21.0

package/src/native-creation-receipts.mjs

@@ -0,0 +1,155 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { homeDir } from "./platform.mjs";
+
+export const creationIdValid = value => typeof value === "string" && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(value);
+export function creationRequestHash(args) {
+  const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === "object"
+    ? Object.fromEntries(Object.keys(value).sort().filter(k => value[k] !== undefined).map(k => [k, canonical(value[k])])) : value;
+  return createHash("sha256").update(JSON.stringify(canonical(args))).digest("hex");
+}
+
+// Stores only exact native creation requests and their results. A missing or
+// pending receipt never permits dispatch again, including after a restart.
+export class NativeCreationReceipts {
+  #key;
+  #keyBoundary;
+  #keyDirectoryBoundary;
+  #keyDirectory;
+  constructor({ directory = path.join(process.env.CODEX_HOME ?? path.join(homeDir(), ".codex"), "bridge-native-creations") } = {}) {
+    this.directory = path.resolve(directory);
+    this.#keyDirectory = path.join(path.dirname(this.directory), "bridge-native-creation-authority");
+  }
+  #signingKey(create = false) {
+    if (create) {
+      try {
+        fs.mkdirSync(this.#keyDirectory, { mode: 0o700 });
+        if (process.platform === "win32") this.#protectWindowsPrivate(this.#keyDirectory, true);
+      } catch (error) { if (error.code !== "EEXIST") throw error; }
+    }
+    const directory = fs.lstatSync(this.#keyDirectory);
+    const canonical = fs.realpathSync.native(this.#keyDirectory);
+    if (!directory.isDirectory() || directory.isSymbolicLink() ||
+        process.platform !== "win32" && ((directory.mode & 0o077) || directory.uid !== process.getuid()) ||
+        this.#keyDirectoryBoundary && (this.#keyDirectoryBoundary.path !== canonical || this.#keyDirectoryBoundary.dev !== directory.dev || this.#keyDirectoryBoundary.ino !== directory.ino)) {
+      throw Error("Unsafe native creation authority directory");
+    }
+    if (process.platform === "win32" && !this.#keyDirectoryBoundary) {
+      this.#assertWindowsPrivate(canonical, true);
+    }
+    this.#keyDirectoryBoundary ??= { path: canonical, dev: directory.dev, ino: directory.ino };
+    const file = path.join(canonical, "signing-key");
+    if (create) {
+      let created, createdBoundary;
+      try {
+        created = fs.openSync(file, "wx", 0o600);
+        createdBoundary = fs.fstatSync(created);
+        if (process.platform === "win32") this.#protectWindowsPrivate(file, false);
+        fs.writeFileSync(created, randomBytes(32));
+        fs.fsyncSync(created);
+      }
+      catch (error) {
+        if (created !== undefined) {
+          fs.closeSync(created);
+          created = undefined;
+          const failed = fs.lstatSync(file);
+          if (failed.dev === createdBoundary.dev && failed.ino === createdBoundary.ino && !failed.isSymbolicLink()) fs.unlinkSync(file);
+        }
+        if (error.code !== "EEXIST") throw error;
+      }
+      finally { if (created !== undefined) fs.closeSync(created); }
+    }
+    const before = fs.lstatSync(file);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size !== 32 ||
+        process.platform !== "win32" && ((before.mode & 0o077) || before.uid !== process.getuid())) throw Error("Unsafe native creation signing key");
+    if (process.platform === "win32" && !this.#keyBoundary) this.#assertWindowsPrivate(file, false);
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    let key;
+    try {
+      const opened = fs.fstatSync(fd);
+      if (opened.dev !== before.dev || opened.ino !== before.ino) throw Error("Native creation signing key changed");
+      const bytes = Buffer.alloc(33);
+      let count = 0, read;
+      while (count < bytes.length && (read = fs.readSync(fd, bytes, count, bytes.length - count, count))) count += read;
+      key = bytes.subarray(0, count);
+      const after = fs.fstatSync(fd);
+      if (key.length !== 32 || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) throw Error("Native creation signing key changed");
+    } finally { fs.closeSync(fd); }
+    if (this.#keyBoundary && (this.#keyBoundary.dev !== before.dev || this.#keyBoundary.ino !== before.ino || !timingSafeEqual(this.#key, key))) throw Error("Native creation signing key changed");
+    this.#keyBoundary ??= { dev: before.dev, ino: before.ino };
+    this.#key ??= key;
+    return this.#key;
+  }
+  #protectWindowsPrivate(file, directory) {
+    const quoted = file.replaceAll("'", "''");
+    const securityType = directory ? "DirectorySecurity" : "FileSecurity";
+    const inheritance = directory ? "ContainerInherit,ObjectInherit" : "None";
+    const script = `$ErrorActionPreference='Stop';$s=[Security.Principal.WindowsIdentity]::GetCurrent().User;$a=New-Object Security.AccessControl.${securityType};$a.SetOwner($s);$a.SetAccessRuleProtection($true,$false);$r=New-Object Security.AccessControl.FileSystemAccessRule($s,'FullControl','${inheritance}','None','Allow');$a.AddAccessRule($r);Set-Acl -LiteralPath '${quoted}' -AclObject $a`;
+    this.#runWindowsAclScript(script);
+  }
+  #assertWindowsPrivate(file, directory) {
+    const quoted = file.replaceAll("'", "''");
+    const script = `$ErrorActionPreference='Stop';$a=Get-Acl -LiteralPath '${quoted}';$s=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value;if(${directory ? "$true" : "$false"} -and !$a.AreAccessRulesProtected){throw 'Unprotected native authority'};if($a.GetOwner([Security.Principal.SecurityIdentifier]).Value -ne $s){throw 'Unexpected native authority owner'};foreach($r in $a.Access){if($r.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value -ne $s -or $r.AccessControlType -ne 'Allow'){throw 'Unexpected native authority access'}};if($a.Access.Count -ne 1){throw 'Ambiguous native authority access'}`;
+    this.#runWindowsAclScript(script);
+  }
+  #runWindowsAclScript(script) {
+    const shellDirectory = path.win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0");
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => key.toLowerCase() !== "psmodulepath"));
+    env.PSModulePath = path.win32.join(shellDirectory, "Modules");
+    execFileSync(path.win32.join(shellDirectory, "powershell.exe"), ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { env, stdio: "pipe", windowsHide: true, timeout: 10000 });
+  }
+  #signature(row, create = false) {
+    const { signature, ...payload } = row;
+    return createHmac("sha256", this.#signingKey(create)).update("native-creation-receipt-v1\0").update(creationRequestHash(payload)).digest("hex");
+  }
+  file(id) {
+    if (!creationIdValid(id)) throw Error("Invalid native creation receipt id");
+    fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(this.directory);
+    if (!st.isDirectory() || st.isSymbolicLink()) throw Error("Unsafe native creation receipt directory");
+    const canonical = fs.realpathSync.native(this.directory);
+    if (this.boundary && (this.boundary.path !== canonical || this.boundary.dev !== st.dev || this.boundary.ino !== st.ino)) throw Error("Native creation receipt directory changed");
+    this.boundary ??= { path: canonical, dev: st.dev, ino: st.ino };
+    this.directory = canonical;
+    return path.join(canonical, id + ".json");
+  }
+  read(id, accounts, hash) {
+    const file = this.file(id);
+    let fd, receiptFound = false;
+    try {
+      const before = fs.lstatSync(file);
+      receiptFound = true;
+      if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > 1024 * 1024) throw Error("Unsafe native creation receipt");
+      fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+      const opened = fs.fstatSync(fd);
+      if (opened.ino !== before.ino || opened.dev !== before.dev) throw Error("Native creation receipt changed");
+      const bytes = Buffer.alloc(1024 * 1024 + 1);
+      let count = 0, n;
+      while ((n = fs.readSync(fd, bytes, count, bytes.length - count, count))) { count += n; if (count > 1024 * 1024) throw Error("Oversized native creation receipt"); }
+      const after = fs.fstatSync(fd);
+      if (after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs || 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]) ||
+          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");
+      return row;
+    } catch (e) { if (e.code === "ENOENT" && !receiptFound) return null; throw e; }
+    finally { if (fd !== undefined) fs.closeSync(fd); }
+  }
+  reserve(id, args, accounts, executorThreadId) {
+    const row = { version: 1, id, hash: creationRequestHash(args), args, accounts, executorThreadId, state: "pending" };
+    this.write(row, true); return row;
+  }
+  write(row, exclusive = false) {
+    const file = this.file(row.id), tmp = exclusive ? file : file + "." + randomUUID() + ".pending";
+    const bytes = JSON.stringify({ ...row, signature: this.#signature(row, exclusive) });
+    if (Buffer.byteLength(bytes) > 1024 * 1024) throw Error("Oversized native creation receipt");
+    const fd = fs.openSync(tmp, "wx", 0o600);
+    try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    if (!exclusive) fs.renameSync(tmp, file);
+  }
+}

package/src/native-relay-companion.mjs

@@ -32,9 +32,11 @@ import { hardenedBridgeEnabled } from "./hardened-root-policy.mjs";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 
+import { NativeCreationReceipts, creationIdValid } from "./native-creation-receipts.mjs";
+
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.20.0";
+const VERSION = "1.21.0";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {
@@ -238,12 +240,12 @@ export function createNativeScopeAuthorizer({ dispatchDesktop, env = process.env
  */
 export async function handleRelayRequest(
   payload,
-  { dispatch, dispatchDesktop, resolveExecutor = resolveRelayThreadId, env = process.env, assertAccount = assertAccountIdentity, authorize, strict = hardenedBridgeEnabled(env) } = {},
+  { dispatch, dispatchDesktop, resolveExecutor = resolveRelayThreadId, env = process.env, assertAccount = assertAccountIdentity, authorize, creationReceipts = new NativeCreationReceipts(), strict = hardenedBridgeEnabled(env) } = {},
 ) {
   if (strict && (!boundRequest(payload) || !validProtocol(payload))) return errorResponse("RELAY_BAD_REQUEST", "Hardened relay accepts only protocol 2 requests with account context", false);
   if (strict && typeof authorize !== "function") return errorResponse("NATIVE_SCOPE_UNVERIFIED", "Hardened relay requires verified current native project and task metadata; no dispatch was attempted", false);
   if (payload && typeof payload === "object" && Object.hasOwn(payload, "operation")) {
-    return handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env, assertAccount, authorize, strict });
+    return handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env, assertAccount, authorize, creationReceipts, strict });
   }
   if (!payload || typeof payload !== "object" || Array.isArray(payload) ||
       Object.keys(payload).some((key) => !["v", "targetThreadId", "message", "accountContext"].includes(key)) || !validProtocol(payload)) {
@@ -295,14 +297,15 @@ export async function handleRelayRequest(
   }
 }
 
-async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env, assertAccount, authorize, strict = hardenedBridgeEnabled(env) }) {
+async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env, assertAccount, authorize, creationReceipts, strict = hardenedBridgeEnabled(env) }) {
   if (strict && !boundRequest(payload)) return errorResponse("RELAY_BAD_REQUEST", "Hardened relay accepts only protocol 2 Desktop operations", false);
   if (Array.isArray(payload) || ![RELAY_PROTOCOL_VERSION, ACCOUNT_RELAY_PROTOCOL_VERSION].includes(payload.v) || !validProtocol(payload) ||
-      Object.keys(payload).some((key) => !["v", "operation", "arguments", "accountContext"].includes(key))) {
+      Object.keys(payload).some((key) => !["v", "operation", "arguments", "accountContext", "creationReceiptId"].includes(key))) {
     return errorResponse("RELAY_BAD_REQUEST", "expected an allowlisted Desktop operation");
   }
   try {
     validateDesktopOperation(payload.operation, payload.arguments);
+    if (payload.creationReceiptId !== undefined && (payload.operation !== "create_thread" || !boundRequest(payload) || !creationIdValid(payload.creationReceiptId))) throw new NativeRelayError("Invalid creation receipt binding", "RELAY_BAD_REQUEST");
     let accountContext;
     try {
       accountContext = await checkAccountContext(payload, assertAccount);
@@ -313,12 +316,29 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
       return errorResponse("NATIVE_OPERATION_UNAVAILABLE", "This companion does not support Desktop operations; reload the native relay");
     }
     const executorThreadId = resolveExecutor(env).threadId;
+    if (payload.operation === "get_creation_receipt") {
+      if (!accountContext) throw new NativeRelayError("Creation receipts require bound accounts", "RELAY_BAD_REQUEST");
+      const row = creationReceipts.read(payload.arguments.receiptId, accountContext, payload.arguments.requestHash);
+      if (row && row.executorThreadId !== executorThreadId) throw new NativeRelayError("Creation receipt executor changed", "NATIVE_SCOPE_UNVERIFIED");
+      const original = row ? { executorThreadId, operation: "create_thread", arguments: row.args, accountContext } : { executorThreadId, operation: "list_projects", arguments: {}, accountContext };
+      if (strict) {
+        const initial = await authorize(original);
+        if (row?.state === "completed") await authorize({ ...original, phase: "return", expected: initial, result: row.result });
+      }
+      await assertAccount(accountContext);
+      return { ok: true, v: payload.v, operation: payload.operation, executorThreadId,
+        result: { status: row?.state ?? "missing", ...(row?.state === "completed" ? { result: row.result } : {}), ...(row?.state === "failed" ? { error: row.error } : {}) } };
+    }
     const request = { executorThreadId, targetThreadId: payload.arguments?.threadId, operation: payload.operation, arguments: payload.arguments, accountContext };
     const authorization = strict ? await authorize(request) : null;
     if (payload.operation === "send_message_to_thread" && payload.arguments.threadId === executorThreadId) {
       return errorResponse("RELAY_BAD_REQUEST", "The relay executor cannot receive its own relayed message");
     }
-    const nativeResult = await dispatchDesktop({
+    // Reserve before dispatch. A disconnected caller must not discard a late
+    // result, and even identical duplicate writes must not dispatch twice.
+    const creation = payload.creationReceiptId ? creationReceipts.reserve(payload.creationReceiptId, payload.arguments, accountContext, executorThreadId) : null;
+    let nativeResult;
+    try { nativeResult = await dispatchDesktop({
       executorThreadId,
       operation: payload.operation,
       arguments: payload.arguments,
@@ -328,6 +348,10 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
     });
     const decoded = decodeNativeToolResult(nativeResult);
     const checked = strict ? await authorize({ ...request, phase: "return", expected: authorization, result: decoded }) : null;
+    if (creation) {
+      await assertAccount(accountContext);
+      creationReceipts.write({ ...creation, state: "completed", result: checked?.result ?? decoded });
+    }
     return {
       ok: true,
       v: boundRequest(payload) ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION,
@@ -335,6 +359,10 @@ async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor,
       executorThreadId,
       result: checked?.result ?? decoded,
     };
+    } catch (error) {
+      if (creation) creationReceipts.write({ ...creation, state: "failed", error: { code: errorCode(error), message: error.message } });
+      throw error;
+    }
   } catch (err) {
     return errorResponse(errorCode(err), err?.message ?? String(err), err?.sent === false && err?.reachedCompanion !== true ? false : undefined);
   }
@@ -354,6 +382,7 @@ export class RelaySocketServer {
     resolveExecutor = resolveRelayThreadId,
     assertAccount = assertAccountIdentity,
     authorize,
+    creationReceipts = new NativeCreationReceipts(),
     requireAccountContext = false,
     strict = hardenedBridgeEnabled(),
     protectSocket = protectCurrentUserPipe,
@@ -368,6 +397,7 @@ export class RelaySocketServer {
     this.resolveExecutor = resolveExecutor;
     this.assertAccount = assertAccount;
     this.authorize = authorize;
+    this.creationReceipts = creationReceipts;
     this.requireAccountContext = requireAccountContext;
     this.strict = strict;
     this.protectSocket = protectSocket;
@@ -574,6 +604,7 @@ export class RelaySocketServer {
       assertAccount: this.assertAccount,
       authorize: this.authorize,
       strict: this.strict,
+      creationReceipts: this.creationReceipts,
     });
     if (!response.ok) this.log(`relay refused ${payload?.targetThreadId ?? "?"}: ${response.error.message}`);
     else this.log(response.operation ? `completed Desktop operation ${response.operation}` : `relayed a message into thread ${response.targetThreadId}`);

package/src/native-relay.mjs

@@ -177,6 +177,8 @@ export function nativeDispatchParams({ executorThreadId, targetThreadId, message
   };
 }
 
+import { creationIdValid } from "./native-creation-receipts.mjs";
+
 const DESKTOP_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
 
 function exactObject(value, keys) {
@@ -201,6 +203,9 @@ export function validateDesktopOperation(operation, args) {
   const modelSettings = () => optionalText(args.model) &&
     (args.thinking === undefined || DESKTOP_EFFORTS.has(args.thinking));
   switch (operation) {
+    case "get_creation_receipt":
+      valid = exactObject(args, ["receiptId", "requestHash"]) && creationIdValid(args.receiptId) && /^[a-f0-9]{64}$/.test(args.requestHash);
+      break;
     case "list_projects":
       valid = exactObject(args, []);
       break;
@@ -540,7 +545,10 @@ export async function resolveNativeToolsPipePath({
       const remaining = deadline - Date.now();
       if (remaining <= 0) break;
       try {
-        if (await probeWindowsPipe(candidate, { env, timeoutMs: Math.min(750, remaining) })) return candidate;
+        // Cold Desktop metadata reads can take over a second. Keep the shared
+        // seven-second discovery budget, but do not reject a valid endpoint
+        // merely because its first read exceeds the old 750ms probe window.
+        if (await probeWindowsPipe(candidate, { env, timeoutMs: Math.min(3000, remaining) })) return candidate;
       } catch {}
     }
     return null;
@@ -801,11 +809,12 @@ export class NativeDesktopRelay {
     return this.#request(request, timeoutMs, beforeSend);
   }
 
-  async requestDesktop(operation, args, { timeoutMs = this.timeoutMs, beforeSend, accountContext } = {}) {
+  async requestDesktop(operation, args, { timeoutMs = this.timeoutMs, beforeSend, accountContext, creationReceiptId } = {}) {
     validateDesktopOperation(operation, args);
     const accounts = relayAccountContext(accountContext);
     if (hardenedBridgeEnabled(this.env) && !accounts) throw beforeWriteError(new NativeRelayError("Hardened relay requires protocol 2 account context", "RELAY_BAD_REQUEST"));
-    return this.#request({ v: accounts ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION, operation, arguments: args, ...(accounts ? { accountContext: accounts } : {}) }, timeoutMs, beforeSend);
+    if (creationReceiptId !== undefined && (operation !== "create_thread" || !accounts || !creationIdValid(creationReceiptId))) throw beforeWriteError(new NativeRelayError("Invalid creation receipt binding", "RELAY_BAD_REQUEST"));
+    return this.#request({ v: accounts ? ACCOUNT_RELAY_PROTOCOL_VERSION : RELAY_PROTOCOL_VERSION, operation, arguments: args, ...(accounts ? { accountContext: accounts } : {}), ...(creationReceiptId ? { creationReceiptId } : {}) }, timeoutMs, beforeSend);
   }
 
   async #request(request, timeoutMs, beforeSend) {

package/src/peer-protocol.mjs

@@ -167,6 +167,7 @@ function isProcessAlive(pid) {
 const SESSION_READ_ATTEMPTS = 3;
 const PEER_SEND_ATTEMPTS = 3;
 const PEER_CONNECT_TIMEOUT_MS = 2000;
+const PEER_VERIFY_TIMEOUT_MS = 30000;
 const PEER_RETRY_DELAY_MS = 75;
 const RETRYABLE_PEER_ERRORS = new Set(["ECONNREFUSED", "ECONNRESET", "ENOENT", "EPIPE", "ENOTFOUND", "ETIMEDOUT"]);
 
@@ -364,36 +365,179 @@ function injectedMessageRoot(entry, msgId) {
   return null;
 }
 
+function isInterruptedDelivery(receipt) {
+  return receipt?.status === "interrupted" && receipt.source === "transcript"
+    && receipt.reasonCode === "CLAUDE_REPLY_INTERRUPTED"
+    && typeof receipt.inReplyTo === "string" && receipt.inReplyTo.length > 0
+    && Number.isFinite(receipt.observedAt)
+    && Array.isArray(receipt.interruptedBy) && receipt.interruptedBy.length > 0
+    && receipt.interruptedBy.every((id) => typeof id === "string" && id.trim())
+    && Array.isArray(receipt.backgroundTaskIds)
+    && receipt.backgroundTaskIds.every((id) => typeof id === "string" && id.trim());
+}
+
+function isTerminalDelivery(receipt) {
+  return ["refused", "denied", "expired", "dropped"].includes(receipt?.status) || isInterruptedDelivery(receipt);
+}
+
 export function readTranscriptReply(sessionId, cwd, msgId) {
+  return readTranscriptOutcome(sessionId, cwd, msgId)?.reply ?? null;
+}
+
+// Read(image) adds a native user-role companion after its tool result (and
+// sometimes hooks). It describes image scaling, not a new user command.
+// Require the actual image-result ancestry; matching text alone is not proof.
+function isImageToolCompanion(entry, entriesById) {
+  if (entry.type !== "user" || entry.message?.role !== "user"
+      || entry.isMeta !== true || entry.turnCompanion !== true
+      || entry.origin != null || entry.promptSource != null || entry.turnOrigin != null
+      || typeof entry.promptId !== "string" || !entry.promptId
+      || typeof entry.sessionId !== "string" || !entry.sessionId
+      || typeof entry.message.content !== "string") return false;
+  let result = entriesById.get(entry.parentUuid);
+  for (let i = 0; i < 8 && result?.type === "attachment"
+      && ["hook_success", "total_tokens_reminder"].includes(result.attachment?.type); i++) {
+    result = entriesById.get(result.parentUuid);
+  }
+  const call = entriesById.get(result?.parentUuid);
+  return result?.type === "user" && result.message?.role === "user"
+    && result.promptId === entry.promptId && result.sessionId === entry.sessionId
+    && result.toolUseResult?.type === "image"
+    && result.sourceToolAssistantUUID === call?.uuid
+    && call?.message?.role === "assistant" && call.sessionId === entry.sessionId
+    && Array.isArray(result.message.content) && result.message.content.length === 1
+    && result.message.content.every(part => part?.type === "tool_result" && !part.is_error
+      && Array.isArray(part.content) && part.content.some(block => block?.type === "image")
+      && Array.isArray(call.message.content) && call.message.content.some(tool =>
+        tool?.type === "tool_use" && tool.name === "Read"
+        && typeof tool.id === "string" && tool.id === part.tool_use_id));
+}
+
+// Interruption closes reply observation, not execution. Never attach a later
+// user turn's answer to the original request or claim its side effects stopped.
+export function readTranscriptOutcome(sessionId, cwd, msgId) {
   const file = findTranscriptFile(sessionId, cwd);
   let lines;
   try { lines = fs.readFileSync(file, "utf8").split("\n"); }
   catch { return null; }
   const entries = [];
   const roots = [];
+  const ids = new Set();
+  let ambiguous = false;
   for (const line of lines) {
+    if (!line.trim()) continue;
     let entry;
-    try { entry = JSON.parse(line); } catch { continue; }
+    try { entry = JSON.parse(line); } catch { ambiguous = true; continue; }
     if (!entry || typeof entry !== "object" || Array.isArray(entry) || entry.isSidechain) continue;
+    if (typeof entry.uuid === "string") {
+      if (ids.has(entry.uuid)) ambiguous = true;
+      ids.add(entry.uuid);
+    }
     entries.push(entry);
     const root = injectedMessageRoot(entry, msgId);
     if (root) roots.push({ entry, absorbed: root === "absorbed" });
   }
   if (roots.length !== 1) return null;
   const { entry: root, absorbed } = roots[0];
-  const descendants = new Set();
+  const entriesById = new Map(entries.map((entry) => [entry.uuid, entry]));
+  const descendants = new Map();
+  const backgroundCalls = new Map();
+  const openLeaves = new Set();
+  const passiveLeaves = new Set();
+  const interruptions = [];
+  const interrupt = (entry, outstanding) => {
+    if (typeof entry.uuid !== "string" || !entry.uuid.trim()) return;
+    openLeaves.delete(entry.parentUuid);
+    interruptions.push({ entryId: entry.uuid, backgroundTaskIds: [...outstanding.keys()] });
+  };
   for (const entry of entries) {
-    if (entry === root) { descendants.add(entry.uuid); continue; }
+    if (entry === root) { descendants.set(entry.uuid, new Map()); openLeaves.add(entry.uuid); continue; }
     if (!descendants.has(entry.parentUuid)) continue;
-    if (entry.type === "attachment" && entry.attachment?.type === "queued_command") continue;
+    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.
+      if (entry.attachment.commandMode === "prompt") {
+        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.
+      if (entry.attachment.commandMode !== "task-notification"
+        || entry.attachment.origin?.kind !== "task-notification"
+        || entry.attachment.origin?.producer !== "session-task") continue;
+    }
     const role = entry.message?.role;
     const content = entry.message?.content;
-    if (role === "user" && !(Array.isArray(content) && content.length > 0 && content.every((part) => part?.type === "tool_result"))) continue;
+    const outstanding = new Map(descendants.get(entry.parentUuid));
+    const toolResults = Array.isArray(content) && content.length > 0 && content.every((part) => part?.type === "tool_result");
+    const imageCompanion = isImageToolCompanion(entry, entriesById);
+    if (role === "user" && !toolResults && !imageCompanion) {
+      const notificationText = typeof content === "string" ? content
+        : Array.isArray(content) ? content.filter((part) => typeof part?.text === "string").map((part) => part.text).join("\n") : "";
+      const nativeHuman = entry.origin?.kind === "human" && entry.promptSource === "sdk" && entry.turnOrigin === "human";
+      const legacyInput = entry.origin == null && entry.promptSource == null && entry.turnOrigin == null;
+      const ordinaryInput = !entry.isMeta && (nativeHuman || legacyInput)
+        && !notificationText.includes("<task-notification>")
+        && (typeof content === "string" && content.trim()
+          || Array.isArray(content) && content.length > 0 && content.every((part) => part?.type === "text" && typeof part.text === "string")
+            && content.some((part) => part.text.trim()));
+      if (ordinaryInput) {
+        interrupt(entry, outstanding);
+        continue;
+      }
+      // A background command can end one model turn, then resume it through a
+      // native task notification. Only that correlated system event may cross
+      // the user-message boundary; pasted notification text is never enough.
+      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;
+      const field = (name) => {
+        const matches = [...content.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);
+    }
     if (typeof entry.uuid !== "string" || !entry.uuid.trim()) continue;
-    descendants.add(entry.uuid);
+    if (role === "assistant" && Array.isArray(content)) {
+      for (const part of content) {
+        if (part?.type === "tool_use" && ["Bash", "PowerShell"].includes(part.name)
+          && typeof part.id === "string") backgroundCalls.set(part.id, entry.uuid);
+      }
+    }
+    const taskId = entry.toolUseResult?.backgroundTaskId;
+    if (role === "user" && toolResults && typeof taskId === "string" && /^[\w-]{1,128}$/.test(taskId)) {
+      const matches = content.filter((part) => !part.is_error && backgroundCalls.get(part.tool_use_id) === entry.parentUuid);
+      if (matches.length === 1) outstanding.set(taskId, matches[0].tool_use_id);
+    }
+    descendants.set(entry.uuid, outstanding);
+    // Parallel tool results and hook records can be leaf siblings of the real
+    // continuation. They are completed observations, not separate reply turns.
+    const parentEntry = entriesById.get(entry.parentUuid);
+    const matchedResults = toolResults && !entry.toolUseResult?.backgroundTaskId
+      && content.every((part) => Array.isArray(parentEntry?.message?.content)
+        && parentEntry.message.content.some((call) => call.type === "tool_use" && call.id === part.tool_use_id));
+    if (matchedResults || imageCompanion || entry.type === "attachment"
+      && ["hook_success", "total_tokens_reminder", "deferred_tools_record"].includes(entry.attachment?.type)) {
+      passiveLeaves.add(entry.uuid);
+    }
+    openLeaves.delete(entry.parentUuid);
+    openLeaves.add(entry.uuid);
     if (role !== "assistant" || !["end_turn", "stop_sequence"].includes(entry.message.stop_reason)) continue;
+    if (outstanding.size > 0) continue;
     const text = Array.isArray(content) ? content.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n") : typeof content === "string" ? content : "";
-    if (text.trim()) return { text: text.trim(), msgId: entry.uuid, source: "transcript", inReplyTo: msgId, absorbed };
+    if (text.trim()) return { status: "reply_received", reply: { text: text.trim(), msgId: entry.uuid, source: "transcript", inReplyTo: msgId, absorbed } };
+  }
+  if (!ambiguous && interruptions.length && [...openLeaves].every((id) => passiveLeaves.has(id))) {
+    return { status: "interrupted", source: "transcript", inReplyTo: msgId,
+      reasonCode: "CLAUDE_REPLY_INTERRUPTED",
+      reason: "A new conversation command separated this request from later replies. Reply waiting ended; the original task outcome is unknown and any background work may still be running. Inspect the existing task before sending a follow-up; do not resend the original action.",
+      interruptedBy: interruptions.map((entry) => entry.entryId),
+      backgroundTaskIds: [...new Set(interruptions.flatMap((entry) => entry.backgroundTaskIds))],
+    };
   }
   return null;
 }
@@ -611,6 +755,9 @@ export class PeerEndpoint {
                 reason: typeof frame.reason === "string" ? frame.reason : "",
                 fromSocket: decodePeerAddress(frame.from),
               };
+              // This status is derived locally from transcript ancestry, never
+              // accepted as a peer assertion that releases pending ownership.
+              if (receipt.status === "interrupted") continue;
               const pending = this.pendingMessages.get(frame.orig_msg_id);
               if (pending?.targetSocket === receipt.fromSocket) {
                 this.deliveryReceipts.set(frame.orig_msg_id, receipt);
@@ -673,8 +820,14 @@ export class PeerEndpoint {
       catch { continue; }
       if (stamp === pending.transcriptStamp) continue;
       pending.transcriptStamp = stamp;
-      const reply = readTranscriptReply(sessionId, cwd, msgId);
-      if (reply) this.#receiveMessage({ ...reply, fromSocket: pending.targetSocket });
+      const outcome = readTranscriptOutcome(sessionId, cwd, msgId);
+      if (outcome?.reply) this.#receiveMessage({ ...outcome.reply, fromSocket: pending.targetSocket });
+      else if (outcome?.status === "interrupted") {
+        this.activityRevision += 1;
+        this.deliveryReceipts.set(msgId, { ...outcome, fromSocket: pending.targetSocket, observedAt: Date.now() });
+        this.#removePendingReply(pending.targetSocket, msgId);
+        this.log(`reply observation interrupted for ${msgId}; task outcome remains unknown`);
+      }
     }
     if (![...this.pendingMessages.values()].some((entry) => entry.transcriptSession)) {
       globalThis.clearInterval(this.responsePoll);
@@ -719,12 +872,16 @@ export class PeerEndpoint {
           let connected = false;
           let writeStarted = false;
           let settled = false;
-          const timer = globalThis.setTimeout(() => {
-            const error = new Error("timed out connecting to " + targetSocket);
-            error.code = "ETIMEDOUT";
-            finish(error);
-            client.destroy();
-          }, PEER_CONNECT_TIMEOUT_MS);
+          let timer;
+          const armTimeout = (phase, duration) => {
+            globalThis.clearTimeout(timer);
+            timer = globalThis.setTimeout(() => {
+              const error = new Error(`timed out ${phase} ${targetSocket}`);
+              error.code = phase === "verifying sender for" ? "PEER_VERIFY_TIMEOUT" : "ETIMEDOUT";
+              finish(error);
+              client.destroy();
+            }, duration);
+          };
           const finish = (error) => {
             if (settled) return;
             settled = true;
@@ -736,11 +893,17 @@ export class PeerEndpoint {
               resolve();
             }
           };
+          armTimeout("connecting to", PEER_CONNECT_TIMEOUT_MS);
           client.once("connect", async () => {
             connected = true;
+            // An established connection must not time out while a long rollout
+            // and native ownership are being verified. Keep a separate bound;
+            // a late verification result still cannot write after settlement.
+            armTimeout("verifying sender for", PEER_VERIFY_TIMEOUT_MS);
             try {
               await beforeSend?.();
               if (settled) return;
+              armTimeout("writing to", PEER_CONNECT_TIMEOUT_MS);
               writeStarted = true;
               client.write(line, (error) => {
                 if (error) {
@@ -773,6 +936,7 @@ export class PeerEndpoint {
     const previous = this.requestQueues.get(targetSocket) ?? Promise.resolve();
     const pending = previous.catch(() => {}).then(async () => {
       await beforeSend?.();
+      this.#refreshTranscriptReplies();
       const unconfirmed = this.unconfirmedReplies.get(targetSocket) ?? 0;
       if (unconfirmed > 0) {
         const error = new Error(
@@ -864,7 +1028,7 @@ export class PeerEndpoint {
       });
       const poll = msgId ? globalThis.setInterval(() => {
         const receipt = this.deliveryReceipts.get(msgId);
-        if (receipt?.fromSocket === fromSocket && ["held", "refused", "denied", "expired", "dropped"].includes(receipt.status)) { finish(null); return; }
+        if (receipt?.fromSocket === fromSocket && (receipt.status === "held" || isTerminalDelivery(receipt))) { finish(null); return; }
       }, 250) : null;
     });
   }
@@ -881,6 +1045,7 @@ export class PeerEndpoint {
   }
 
   readDelivery(msgId) {
+    this.#refreshTranscriptReplies();
     const sent = this.sentMessages.get(msgId);
     if (!sent) return null;
     const delivery = this.deliveryReceipts.get(msgId);
@@ -903,15 +1068,23 @@ export class PeerEndpoint {
       ...(sent.accountContext ? { accountContext: { ...sent.accountContext } } : {}),
       ...(sent.scopeBindings ? { scopeBindings: structuredClone(sent.scopeBindings), senderCwd: sent.scopeBindings.sender?.path ?? null } : {}),
       pending: this.pendingMessages.has(msgId),
+      ...(isInterruptedDelivery(delivery) ? {
+        outcome: "unknown", waitEnded: true, taskCancelled: false, retrySafe: false,
+        nextAction: "inspect_existing_task_then_follow_up",
+        interruption: { reasonCode: delivery.reasonCode, source: delivery.source,
+          observedAt: delivery.observedAt, entryIds: delivery.interruptedBy,
+          backgroundTaskIds: delivery.backgroundTaskIds },
+      } : {}),
       ...(sent.reply ? { reply: sent.reply.text, source: sent.reply.source ?? "peer", ...(sent.reply.absorbed ? { replyAbsorbed: true } : {}), ...(sent.reply.forwardingError ? { forwardingError: { ...sent.reply.forwardingError } } : {}) } : {}),
     };
   }
 
   reloadReason() {
+    this.#refreshTranscriptReplies();
     if (this.connections.size) return "Peer socket connections are still open";
     if (this.requestQueues.size || this.pendingMessages.size || this.unconfirmedReplies.size) return "Claude messages still have pending or unconfirmed delivery";
     for (const [id, sent] of this.sentMessages) {
-      if (!sent.reply && !sent.failed && !["refused", "denied", "expired", "dropped"].includes(this.deliveryReceipts.get(id)?.status)) {
+      if (!sent.reply && !sent.failed && !isTerminalDelivery(this.deliveryReceipts.get(id))) {
         return "A Claude delivery outcome remains unconfirmed";
       }
     }
@@ -968,7 +1141,8 @@ export class PeerEndpoint {
     for (const [id, sent] of sentMessages) {
       if (typeof sent.targetSocket !== "string" || !sent.targetSocket || !Number.isFinite(sent.sentAt)
         || sent.reply && (typeof sent.reply.text !== "string" || sent.reply.inReplyTo !== id)
-        || !sent.reply && !sent.failed && !["refused", "denied", "expired", "dropped"].includes(deliveryReceipts.get(id)?.status)) {
+        || !sent.reply && !sent.failed && !isTerminalDelivery(deliveryReceipts.get(id))
+        || isInterruptedDelivery(deliveryReceipts.get(id)) && deliveryReceipts.get(id).inReplyTo !== id) {
         throw new Error("Invalid or unconfirmed Claude delivery reload record");
       }
     }