very-happy-cli 0.2.174 → 0.2.176

package/dist/{codexAppServerClient-BWB1267F.cjs → codexAppServerClient-DsIUkVnX.cjs}

@@ -3,12 +3,100 @@
 var node_child_process = require('node:child_process');
 var spawn = require('cross-spawn');
 var node_readline = require('node:readline');
-var logger = require('./logger-XjIS0lU7.cjs');
+var logger = require('./logger-zoO54Zsy.cjs');
 var contentLogMetadata = require('./contentLogMetadata-ZSFk_NjQ.cjs');
 var manager = require('./manager-HrEj442o.cjs');
-var _package = require('./package-DFQUF2in.cjs');
-var rateLimitWindows = require('./rateLimitWindows-U7NsRvIa.cjs');
+var _package = require('./package-A7zOGx8B.cjs');
+var rateLimitWindows = require('./rateLimitWindows-82izLQy8.cjs');
 
+const CODEX_HELPER_LABEL_MAX_CHARS = 80;
+function codexHelperLabel(prompt) {
+  if (typeof prompt !== "string") return null;
+  const collapsed = prompt.replace(/\s+/g, " ").trim();
+  if (collapsed.length === 0) return null;
+  if (collapsed.length <= CODEX_HELPER_LABEL_MAX_CHARS) return collapsed;
+  const keep = CODEX_HELPER_LABEL_MAX_CHARS - 1;
+  const last = collapsed.charCodeAt(keep - 1);
+  const end = last >= 55296 && last <= 56319 ? keep - 1 : keep;
+  return `${collapsed.slice(0, end)}\u2026`;
+}
+function codexAgentPathSegments(agentPath) {
+  if (typeof agentPath !== "string") return [];
+  return agentPath.split("/").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+}
+function isRootAgentPath(segments) {
+  return segments.length === 1 && segments[0] === "root";
+}
+function codexChildAnnouncements(item) {
+  if (item.type === "subAgentActivity") {
+    const threadId = item.agentThreadId;
+    if (typeof threadId !== "string" || threadId.length === 0) return [];
+    const segments = codexAgentPathSegments(item.agentPath);
+    if (isRootAgentPath(segments)) return [];
+    const leaf = segments.at(-1);
+    return [{ threadId, label: leaf && leaf.length > 0 ? leaf : null }];
+  }
+  if (item.type === "collabAgentToolCall") {
+    const receivers = Array.isArray(item.receiverThreadIds) ? item.receiverThreadIds.filter((id) => typeof id === "string" && id.length > 0) : [];
+    const label = item.tool === "spawnAgent" ? codexHelperLabel(item.prompt) : null;
+    return [...new Set(receivers)].map((threadId) => ({ threadId, label }));
+  }
+  return [];
+}
+
+function stopCodexProcess(proc, deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  try {
+    proc.stdin?.end();
+  } catch {
+  }
+  if (platform === "win32") return;
+  try {
+    proc.kill("SIGTERM");
+  } catch {
+  }
+}
+function killCodexProcessTree(proc, deps = {}) {
+  if (proc.exitCode != null || proc.signalCode != null) return;
+  const killRoot = () => {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+    }
+  };
+  const pid = proc.pid;
+  if (!pid || !("exitCode" in proc)) {
+    killRoot();
+    return;
+  }
+  const platform = deps.platform ?? process.platform;
+  const spawn = deps.spawn ?? ((command, args, options) => node_child_process.spawn(command, args, options));
+  if (platform === "win32") {
+    try {
+      const killer = spawn("taskkill", ["/pid", String(pid), "/t", "/f"], { stdio: "ignore", windowsHide: true });
+      killer.on("error", killRoot);
+      killer.on("exit", (code) => {
+        if (code !== 0) killRoot();
+      });
+      killer.unref();
+    } catch {
+      killRoot();
+    }
+    return;
+  }
+  try {
+    const reaper = spawn("pkill", ["-KILL", "-P", String(pid)], { stdio: "ignore", windowsHide: true });
+    reaper.on("error", () => void 0);
+    reaper.unref();
+  } catch {
+  }
+  killRoot();
+}
+
+function jsonRpcErrorCodeOf(error) {
+  const code = error?.jsonRpcCode;
+  return typeof code === "number" ? code : null;
+}
 function isAppServerAvailable() {
   try {
     const version = node_child_process.execSync("codex --version", { encoding: "utf8", windowsHide: true }).trim();
@@ -91,7 +179,6 @@ class CodexAppServerClient {
   _turnId = null;
   threadDefaults = null;
   // Turn completion tracking for the currently active sendTurnAndWait call.
-  // A completion event only resolves once we have seen task_started for this turn.
   pendingTurnCompletion = null;
   // Tracks in-flight interruptTurn() RPCs so sendTurnAndWait can wait for them
   // before starting a new turn (prevents stale turn/interrupt from aborting the next turn).
@@ -101,6 +188,22 @@ class CodexAppServerClient {
   idleRelease = null;
   notificationProtocol = "unknown";
   completedTurnIds = /* @__PURE__ */ new Set();
+  /** B-625: turns whose failure has already been forwarded, so a second failed frame is not. */
+  failedTurnIds = /* @__PURE__ */ new Set();
+  // B-625: the app-server speaks for every thread it hosts — the session's own and the
+  // children `spawn_agent` opens — so a lifecycle frame (turn/started, turn/completed,
+  // thread/status/changed, error, thread/closed) is the session's only when its `threadId`
+  // is ours; a frame naming no thread belongs to the thread it was asked on (Orca's rule,
+  // src/main/codex/codex-structured-turn-open-wait.ts). Before this, a child's
+  // `turn/completed` ended the parent's turn in the UI and a child's `turn/started`
+  // retargeted `turn/interrupt` at the child.
+  /** The own thread's last turn-ending `error` (willRetry=false), for a turn end that arrives without a verdict. */
+  lastTurnError = null;
+  /** Own thread reported idle/systemError while a turn was pending: Codex's `turn/completed`
+   *  follows within a millisecond; this ends the turn if it does not (see armThreadStopGrace). */
+  threadStopGrace = null;
+  /** Last few hundred chars of the app-server's stderr: Codex's own last words when it dies. */
+  stderrRing = "";
   rawFileChangesByItemId = /* @__PURE__ */ new Map();
   // B-622: inactivity watchdog for the pending turn — re-armed by every
   // notification, never a cap on how long a turn may run (see sendTurnAndWait).
@@ -108,6 +211,18 @@ class CodexAppServerClient {
   // Approval / elicitation requests we are still answering: a human may take
   // longer than the watchdog to decide, and that is not Codex going silent.
   inflightServerRequests = 0;
+  // B-628: `turn/steer` — a message sent into the running turn (approach from Orca,
+  // src/main/codex/codex-structured-turn-start.ts). This app-server has no such
+  // method (-32601) until it is respawned; a refusal is per call (the turn it named
+  // ended or changed meanwhile, a review/compact turn).
+  steerUnsupported = false;
+  /** Steered inputs Codex has not echoed back as a `userMessage` item yet: clientId → turnId. */
+  steeredAwaitingEcho = /* @__PURE__ */ new Map();
+  /** Waiters for the pending turn to open (steerTurn); released when it opens or ends. */
+  turnOpenWaiters = [];
+  /** B-628: the names Codex gave the child threads it spawned (see codexChildThreads.ts). */
+  childThreadLabels = /* @__PURE__ */ new Map();
+  static MAX_CHILD_LABELS = 128;
   // Handlers set by the consumer (runCodex.ts)
   eventHandler = null;
   approvalHandler = null;
@@ -169,8 +284,73 @@ class CodexAppServerClient {
     const status = params?.turn?.status ?? params?.status ?? null;
     return typeof status === "string" && status.length > 0 ? status : null;
   }
+  extractThreadId(params) {
+    const threadId = params?.threadId ?? params?.thread_id ?? params?.thread?.id ?? null;
+    return typeof threadId === "string" && threadId.length > 0 ? threadId : null;
+  }
+  /** B-625: whether a lifecycle frame is about the session's own thread (see the field comment). */
+  isOwnThreadFrame(params) {
+    const threadId = this.extractThreadId(params);
+    return threadId === null || this._threadId === null || threadId === this._threadId;
+  }
+  /** B-628: the child thread a frame belongs to, or null for the session's own. */
+  childThreadIdOf(params) {
+    return this.isOwnThreadFrame(params) ? null : this.extractThreadId(params);
+  }
+  /**
+   * B-628: what a child thread's item carries so the mapper files it under the child's
+   * card (`subagent` → the session protocol's sub-agent envelope, as a Claude Task's
+   * children are) instead of in the main conversation as the session's own work.
+   */
+  childItemFields(params) {
+    const child = this.childThreadIdOf(params);
+    if (!child) return {};
+    const label = this.childThreadLabels.get(child);
+    return { subagent: child, ...label ? { subagent_label: label } : {} };
+  }
+  rememberChildLabels(item) {
+    for (const { threadId, label } of codexChildAnnouncements(item)) {
+      if (!label || this.childThreadLabels.has(threadId)) continue;
+      if (this.childThreadLabels.size >= CodexAppServerClient.MAX_CHILD_LABELS) {
+        const oldest = this.childThreadLabels.keys().next().value;
+        if (oldest !== void 0) this.childThreadLabels.delete(oldest);
+      }
+      this.childThreadLabels.set(threadId, label);
+    }
+  }
+  /**
+   * B-628: steered inputs the ended turn never echoed. `report` = the turn did not complete
+   * (interrupted, failed, app-server gone, given up): Codex never read them, tell the runner.
+   * A turn that *completed* drains its pending input before it ends (core/src/session/turn.rs),
+   * so an unechoed input there is a codex that accepted the steer but echoes no `clientId` —
+   * forgotten silently, because a false「not delivered」on a message the model did read would
+   * be worse than today's silence.
+   */
+  dropUnechoedSteers(turnId, report) {
+    const dropped = [];
+    for (const [clientId, steeredTurn] of this.steeredAwaitingEcho) {
+      if (turnId === null || steeredTurn === turnId) {
+        dropped.push(clientId);
+        this.steeredAwaitingEcho.delete(clientId);
+      }
+    }
+    if (dropped.length === 0) return;
+    if (!report) {
+      logger.logger.debug(`[CodexAppServer] ${dropped.length} steered message(s) completed without an echo; not reported`);
+      return;
+    }
+    this.eventHandler?.({
+      type: "steer_dropped",
+      client_ids: dropped,
+      ...turnId ? { turn_id: turnId } : {}
+    });
+  }
+  /** Codex's last stderr lines, one line, for a message a person reads. */
+  stderrTail() {
+    return this.stderrRing.replace(/\x1b\[[0-9;]*m/g, "").replace(/\s+/g, " ").trim();
+  }
   shouldHandleRawNotification(method) {
-    const isRawNotification = method === "thread/started" || method === "turn/started" || method === "turn/completed" || method === "thread/status/changed" || method === "thread/tokenUsage/updated" || method.startsWith("item/");
+    const isRawNotification = method === "thread/started" || method === "turn/started" || method === "turn/completed" || method === "thread/status/changed" || method === "thread/closed" || method === "thread/tokenUsage/updated" || method.startsWith("item/");
     if (!isRawNotification) {
       return false;
     }
@@ -185,15 +365,21 @@ class CodexAppServerClient {
   emitRawTurnCompletion(turnId, status, error, source) {
     const aborted = status === "cancelled" || status === "canceled" || status === "aborted" || status === "interrupted";
     const failed = status === "failed" || error !== void 0 && error !== null;
+    this.clearThreadStopGrace();
     this.tryResolvePendingTurn(aborted, turnId, source);
     this._turnId = null;
     this.maybeRefreshRateLimits();
+    if (this.lastTurnError && (!turnId || !this.lastTurnError.turnId || this.lastTurnError.turnId === turnId)) {
+      this.lastTurnError = null;
+    }
     if (turnId && this.completedTurnIds.has(turnId)) {
-      if (!failed) return;
+      if (!failed || this.failedTurnIds.has(turnId)) return;
     }
     if (turnId) {
       this.completedTurnIds.add(turnId);
+      if (failed) this.failedTurnIds.add(turnId);
     }
+    this.dropUnechoedSteers(turnId, aborted || failed);
     if (aborted) {
       this.eventHandler?.({
         type: "turn_aborted",
@@ -215,6 +401,10 @@ class CodexAppServerClient {
       return false;
     }
     if (method === "turn/started") {
+      if (!this.isOwnThreadFrame(params)) {
+        logger.logger.debug(`[CodexAppServer] Child thread ${this.extractThreadId(params)} started a turn`);
+        return true;
+      }
       const turnId = this.extractTurnId(params);
       if (turnId) {
         this._turnId = turnId;
@@ -227,6 +417,15 @@ class CodexAppServerClient {
       return true;
     }
     if (method === "turn/completed") {
+      if (!this.isOwnThreadFrame(params)) {
+        logger.logger.debug(`[CodexAppServer] Child thread ${this.extractThreadId(params)} ended a turn`);
+        this.eventHandler?.({
+          type: "subagent_turn_end",
+          ...this.childItemFields(params),
+          status: this.extractTurnStatus(params)
+        });
+        return true;
+      }
       this.emitRawTurnCompletion(
         this.extractTurnId(params),
         this.extractTurnStatus(params),
@@ -236,13 +435,28 @@ class CodexAppServerClient {
       return true;
     }
     if (method === "thread/status/changed") {
+      if (!this.isOwnThreadFrame(params)) return true;
       const statusType = params?.status?.type;
-      if (statusType === "idle" && this.pendingTurnCompletion) {
-        this.emitRawTurnCompletion(this._turnId, "completed", null, method);
+      if ((statusType === "idle" || statusType === "systemError") && this.pendingTurnCompletion?.opened) {
+        this.armThreadStopGrace(statusType);
+      } else if (statusType === "active") {
+        this.clearThreadStopGrace();
+      }
+      return true;
+    }
+    if (method === "thread/closed") {
+      if (this.isOwnThreadFrame(params) && this.pendingTurnCompletion) {
+        this.emitRawTurnCompletion(
+          this.pendingTurnCompletion.turnId ?? this._turnId,
+          "aborted",
+          { message: "Codex closed the thread before the turn ended." },
+          method
+        );
       }
       return true;
     }
     if (method === "thread/tokenUsage/updated") {
+      if (!this.isOwnThreadFrame(params)) return true;
       const tokenUsage = params?.tokenUsage;
       if (tokenUsage && typeof tokenUsage === "object") {
         this.eventHandler?.({
@@ -256,8 +470,15 @@ class CodexAppServerClient {
     if (!item || typeof item !== "object") {
       return method.startsWith("item/");
     }
+    const child = this.childItemFields(params);
     if ((method === "item/started" || method === "item/completed") && (item.type === "collabAgentToolCall" || item.type === "subAgentActivity")) {
-      this.eventHandler?.({ type: "collab_agent_item", item });
+      this.rememberChildLabels(item);
+      this.eventHandler?.({ type: "collab_agent_item", item, ...child });
+      return true;
+    }
+    if (method === "item/completed" && item.type === "userMessage") {
+      const clientId = typeof item.clientId === "string" ? item.clientId : null;
+      if (clientId && !child.subagent) this.steeredAwaitingEcho.delete(clientId);
       return true;
     }
     if (method === "item/started" && item.type === "commandExecution") {
@@ -268,7 +489,8 @@ class CodexAppServerClient {
         callId,
         command: item.command,
         cwd: item.cwd,
-        description: item.command
+        description: item.command,
+        ...child
       });
       return true;
     }
@@ -283,7 +505,8 @@ class CodexAppServerClient {
         duration_ms: item.durationMs ?? null,
         status: item.status,
         cwd: item.cwd,
-        command: item.command
+        command: item.command,
+        ...child
       });
       return true;
     }
@@ -298,7 +521,8 @@ class CodexAppServerClient {
           type: "patch_apply_begin",
           call_id: callId,
           callId,
-          changes: changes ?? {}
+          changes: changes ?? {},
+          ...child
         });
         return true;
       }
@@ -307,7 +531,8 @@ class CodexAppServerClient {
           type: "patch_apply_end",
           call_id: callId,
           callId,
-          status: item.status
+          status: item.status,
+          ...child
         });
         if (callId && (item.status === "completed" || item.status === "failed" || item.status === "declined")) {
           this.rawFileChangesByItemId.delete(callId);
@@ -322,7 +547,8 @@ class CodexAppServerClient {
           type: "agent_message",
           message: text,
           item_id: item.id,
-          phase: item.phase
+          phase: item.phase,
+          ...child
         });
       }
       return true;
@@ -384,17 +610,39 @@ class CodexAppServerClient {
         return;
       }
       this.connected = false;
+      const tail = this.stderrTail();
+      const exited = `Codex process exited (code=${code ?? "null"}${signal ? `, signal=${signal}` : ""})`;
       for (const [id, req] of this.pending) {
         if (req.epoch !== epoch) continue;
-        req.reject(new Error(`Codex process exited (code=${code}) while waiting for ${req.method}`));
+        const error = new Error(`${exited} while waiting for ${req.method}`);
+        error.codexStderrTail = tail;
+        req.reject(error);
         this.pending.delete(id);
       }
+      if (this.pendingTurnCompletion) {
+        const turnId = this.pendingTurnCompletion.turnId ?? this._turnId;
+        this.dropUnechoedSteers(null, true);
+        this.eventHandler?.({
+          type: "turn_aborted",
+          reason: "process-exit",
+          ...turnId ? { turn_id: turnId } : {},
+          error: { message: `${exited}${tail ? `: ${tail}` : ""}` }
+        });
+      }
       this.resolvePendingTurn(true);
     });
+    this.stderrRing = "";
+    this.steerUnsupported = false;
+    this.steeredAwaitingEcho.clear();
+    this.childThreadLabels.clear();
     proc.stderr?.on("data", (chunk) => {
       if (this.process !== proc || this.processEpoch !== epoch) return;
       const text = chunk.toString().trim();
-      if (text) logger.logger.debug("[CodexAppServer:stderr]", contentLogMetadata.contentLogMetadata(text));
+      if (text) {
+        logger.logger.debug("[CodexAppServer:stderr]", contentLogMetadata.contentLogMetadata(text));
+        this.stderrRing = `${this.stderrRing}
+${text}`.slice(-400);
+      }
     });
     this.readline = node_readline.createInterface({ input: proc.stdout });
     this.readline.on("line", (line) => {
@@ -425,26 +673,21 @@ class CodexAppServerClient {
     logger.logger.debug(`[CodexAppServer] Disconnecting; pid=${pid ?? "none"}`);
     this.readline?.close();
     this.readline = null;
-    try {
-      proc?.stdin?.end();
-      proc?.kill("SIGTERM");
-    } catch {
-    }
-    if (pid) {
-      const killTimer = setTimeout(() => {
-        try {
-          process.kill(pid, 0);
-          process.kill(pid, "SIGKILL");
-        } catch {
-        }
-      }, 2e3);
-      killTimer.unref();
+    if (proc) {
+      stopCodexProcess(proc);
+      if (pid) {
+        const killTimer = setTimeout(() => killCodexProcessTree(proc), CodexAppServerClient.FORCE_KILL_AFTER_MS);
+        killTimer.unref();
+      }
     }
     this.process = null;
     this.connected = false;
     this._turnId = null;
     this.notificationProtocol = "unknown";
     this.completedTurnIds.clear();
+    this.failedTurnIds.clear();
+    this.lastTurnError = null;
+    this.clearThreadStopGrace();
     if (!opts?.preserveThreadState) {
       this._threadId = null;
       this.threadDefaults = null;
@@ -454,6 +697,7 @@ class CodexAppServerClient {
       req.reject(new Error(`Codex process disconnected while waiting for ${req.method}`));
       this.pending.delete(id);
     }
+    this.dropUnechoedSteers(null, true);
     this.resolvePendingTurn(true);
     if (this.sandboxCleanup) {
       try {
@@ -657,20 +901,137 @@ class CodexAppServerClient {
   // ─── Turn management ────────────────────────────────────────
   /** Default grace period after interrupt before forcing a restart (ms). */
   static ABORT_GRACE_MS = 3e3;
+  /** How long the graceful stop gets before the process tree is killed (disconnectInternal). */
+  static FORCE_KILL_AFTER_MS = 2e3;
   hasPendingTurnCompletion() {
     return this.pendingTurnCompletion !== null;
   }
   resolvePendingTurn(aborted) {
     if (!this.pendingTurnCompletion) return;
     this.clearTurnWatchdog();
+    this.clearThreadStopGrace();
     this.pendingTurnCompletion.resolve(aborted);
     this.pendingTurnCompletion = null;
+    this.releaseTurnOpenWaiters();
   }
   markPendingTurnStarted(turnId) {
     if (!this.pendingTurnCompletion) return;
+    this.pendingTurnCompletion.opened = true;
     if (turnId) {
       this.pendingTurnCompletion.turnId = turnId;
     }
+    this.releaseTurnOpenWaiters();
+  }
+  // ─── B-628: steering the running turn ───────────────────────
+  /** How long a steer waits for the pending turn to open before the message is queued instead. */
+  static STEER_OPEN_WAIT_MS = 5e3;
+  /** A turn Codex has reported running, under an id `turn/steer` can name. */
+  turnIsOpen() {
+    return this.pendingTurnCompletion?.opened === true && this._turnId !== null;
+  }
+  releaseTurnOpenWaiters() {
+    const waiters = this.turnOpenWaiters;
+    this.turnOpenWaiters = [];
+    for (const release of waiters) release();
+  }
+  /**
+   * Waits for the pending turn to open — `turn/start` is in flight, or the runner is still
+   * bringing a released app-server back before sending it (B-461) — as Orca's send does
+   * (codex-structured-turn-open-wait.ts, 5 s). Resolves early when the turn ends instead.
+   */
+  async waitForTurnOpen(timeoutMs) {
+    if (this.turnIsOpen()) return true;
+    if (timeoutMs <= 0) return false;
+    await new Promise((resolve) => {
+      const release = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(release, timeoutMs);
+      timer.unref();
+      this.turnOpenWaiters.push(release);
+    });
+    return this.turnIsOpen();
+  }
+  /**
+   * B-628: send a message into the turn running right now (`turn/steer`, codex ≥ 0.148 /
+   * app-server-protocol v2 `TurnSteerParams`). Codex appends it to that turn's pending input
+   * and the model reads it before its next call; the turn keeps its own model, approval
+   * policy and sandbox — the runner applies any change on the next `turn/start`. Codex
+   * refuses before taking any input (expectedTurnId is a precondition), so a non-`steered`
+   * outcome always means "queue it for the next turn as before": `no-turn` (nothing running,
+   * or it ended while we waited), `unsupported` (this app-server has no `turn/steer`,
+   * remembered until it is respawned), `refused` (Codex declined this one), `failed`
+   * (transport — the turn itself is reported through its own events).
+   */
+  async steerTurn(input, opts) {
+    if (this.steerUnsupported) return "unsupported";
+    if (this.pendingInterrupt) return "no-turn";
+    const opened = await this.waitForTurnOpen(opts?.waitForTurnMs ?? CodexAppServerClient.STEER_OPEN_WAIT_MS);
+    const threadId = this._threadId;
+    const turnId = this._turnId;
+    if (!opened || !threadId || !turnId || !this.connected || this.pendingInterrupt) return "no-turn";
+    const params = {
+      threadId,
+      expectedTurnId: turnId,
+      ...input.clientId ? { clientUserMessageId: input.clientId } : {},
+      input: [
+        { type: "text", text: input.text },
+        ...(input.images ?? []).map((path) => ({ type: "localImage", path }))
+      ]
+    };
+    try {
+      const result = await this.request("turn/steer", params);
+      const steeredTurnId = typeof result?.turnId === "string" && result.turnId.length > 0 ? result.turnId : turnId;
+      if (input.clientId) this.steeredAwaitingEcho.set(input.clientId, steeredTurnId);
+      logger.logger.debug(`[CodexAppServer] Steered a message into turn ${steeredTurnId}`);
+      return "steered";
+    } catch (error) {
+      const code = jsonRpcErrorCodeOf(error);
+      if (code === -32601) {
+        this.steerUnsupported = true;
+        logger.logger.debug("[CodexAppServer] turn/steer is not supported by this codex; queuing instead");
+        return "unsupported";
+      }
+      if (code !== null) {
+        logger.logger.debug("[CodexAppServer] turn/steer refused:", contentLogMetadata.errorLogMetadata(error));
+        return "refused";
+      }
+      logger.logger.debug("[CodexAppServer] turn/steer failed:", contentLogMetadata.errorLogMetadata(error));
+      return "failed";
+    }
+  }
+  /** Default wait for Codex's `turn/completed` after its thread reported idle/systemError. */
+  static THREAD_STOP_GRACE_MS = 1500;
+  /**
+   * B-625: the own thread stopped (idle / systemError) while a turn was pending and
+   * had opened. Codex's `turn/completed` follows at once in every probed release
+   * (0.154.0: 1 ms); this is the net under a release that does not send it, so the
+   * session never waits on the silence watchdog for a turn Codex has already left.
+   */
+  armThreadStopGrace(statusType) {
+    this.clearThreadStopGrace();
+    const graceMs = this.pendingTurnCompletion?.threadStopGraceMs ?? CodexAppServerClient.THREAD_STOP_GRACE_MS;
+    this.threadStopGrace = setTimeout(() => {
+      this.threadStopGrace = null;
+      const pending = this.pendingTurnCompletion;
+      if (!pending) return;
+      const turnId = pending.turnId ?? this._turnId;
+      const lastError = this.lastTurnError && (!turnId || !this.lastTurnError.turnId || this.lastTurnError.turnId === turnId) ? this.lastTurnError.error : null;
+      logger.logger.warn(`[CodexAppServer] Thread went ${statusType} and no turn/completed followed for turn ${turnId ?? "?"}; ending the turn`);
+      const failed = statusType === "systemError" || lastError !== null;
+      this.emitRawTurnCompletion(
+        turnId,
+        failed ? "failed" : "completed",
+        lastError ?? (failed ? { message: "Codex reported a system error and ended the turn without a verdict." } : null),
+        `thread/status/changed:${statusType}`
+      );
+    }, graceMs);
+  }
+  clearThreadStopGrace() {
+    if (!this.threadStopGrace) return;
+    clearTimeout(this.threadStopGrace);
+    this.threadStopGrace = null;
   }
   tryResolvePendingTurn(aborted, turnId, source) {
     const pending = this.pendingTurnCompletion;
@@ -773,6 +1134,8 @@ class CodexAppServerClient {
   }
   /** Default timeout for waiting on turn completion (ms). 10 minutes. */
   static TURN_TIMEOUT_MS = 10 * 60 * 1e3;
+  /** How much of the app-server's stderr is kept for its exit message. */
+  static STDERR_TAIL_CHARS = 400;
   /**
    * Send a user turn and wait for it to complete (task_complete or turn_aborted).
    * Returns { aborted: true } if the turn was aborted (user cancel, permission reject, etc.).
@@ -787,8 +1150,11 @@ class CodexAppServerClient {
     const completion = new Promise((resolve) => {
       this.pendingTurnCompletion = {
         resolve,
-        turnId: null
+        turnId: null,
+        opened: false,
+        threadStopGraceMs: opts?.threadStopGraceMs ?? CodexAppServerClient.THREAD_STOP_GRACE_MS
       };
+      this.lastTurnError = null;
       this.armTurnWatchdog(timeoutMs);
     });
     try {
@@ -796,6 +1162,7 @@ class CodexAppServerClient {
     } catch (err) {
       this.clearTurnWatchdog();
       this.pendingTurnCompletion = null;
+      this.releaseTurnOpenWaiters();
       throw err;
     }
     const aborted = await completion;
@@ -813,6 +1180,7 @@ class CodexAppServerClient {
       }
       logger.logger.warn(`[CodexAppServer] No notification from Codex for ${timeoutMs}ms \u2014 giving the turn up as aborted`);
       const turnId = this.pendingTurnCompletion.turnId ?? this._turnId;
+      this.dropUnechoedSteers(turnId, true);
       this.eventHandler?.({
         type: "turn_aborted",
         reason: "timeout",
@@ -863,12 +1231,16 @@ class CodexAppServerClient {
     logger.logger.debug(
       `[CodexAppServer] Clearing thread state: thread=${this._threadId ?? "none"} turn=${this._turnId ?? "none"}`
     );
+    this.dropUnechoedSteers(null, true);
     this.resolvePendingTurn(true);
     this._threadId = null;
     this._turnId = null;
     this.threadDefaults = null;
     this.completedTurnIds.clear();
+    this.failedTurnIds.clear();
+    this.lastTurnError = null;
     this.rawFileChangesByItemId.clear();
+    this.childThreadLabels.clear();
   }
   // ─── JSON-RPC transport ─────────────────────────────────────
   /** Default timeout for RPC requests (ms). */
@@ -949,7 +1321,9 @@ class CodexAppServerClient {
         }
         this.pending.delete(msg.id);
         if (msg.error) {
-          pending.reject(new Error(`${pending.method}: ${msg.error.message} (code=${msg.error.code})`));
+          const error = new Error(`${pending.method}: ${msg.error.message} (code=${msg.error.code})`);
+          if (typeof msg.error.code === "number") error.jsonRpcCode = msg.error.code;
+          pending.reject(error);
         } else {
           pending.resolve(msg.result);
         }
@@ -1136,6 +1510,7 @@ class CodexAppServerClient {
     }
     if (method === "thread/started" || method === "turn/started" || method === "turn/completed" || method === "thread/status/changed") {
       logger.logger.debug(`[CodexAppServer] Lifecycle notification: ${method}`);
+      if (!this.isOwnThreadFrame(params)) return;
       if (method === "turn/started") {
         const turnId = this.extractTurnId(params);
         if (turnId) {
@@ -1162,19 +1537,28 @@ class CodexAppServerClient {
       logger.logger.debug(`[CodexAppServer] mcpServer startup status:`, params);
       return;
     }
-    if (method === "error" && params?.willRetry === true) {
+    if (method === "error") {
+      if (!this.isOwnThreadFrame(params)) return;
       const error = params?.error ?? {};
-      const message = typeof error.message === "string" ? error.message : "";
-      const info = error.codexErrorInfo;
-      const httpStatus = info && typeof info === "object" ? info.responseStreamDisconnected?.httpStatusCode ?? info.httpStatusCode ?? null : null;
-      const turnId = typeof params?.turnId === "string" ? params.turnId : null;
-      this.eventHandler?.({
-        type: "turn_retry",
-        message,
-        ...typeof httpStatus === "number" ? { http_status: httpStatus } : {},
-        ...turnId ? { turn_id: turnId } : {},
-        ...typeof error.additionalDetails === "string" ? { details: error.additionalDetails } : {}
-      });
+      const turnId = typeof params?.turnId === "string" && params.turnId.length > 0 ? params.turnId : null;
+      if (params?.willRetry === true) {
+        const message = typeof error.message === "string" ? error.message : "";
+        const info = error.codexErrorInfo;
+        const httpStatus = info && typeof info === "object" ? info.responseStreamDisconnected?.httpStatusCode ?? info.httpStatusCode ?? null : null;
+        this.eventHandler?.({
+          type: "turn_retry",
+          message,
+          ...typeof httpStatus === "number" ? { http_status: httpStatus } : {},
+          ...turnId ? { turn_id: turnId } : {},
+          ...typeof error.additionalDetails === "string" ? { details: error.additionalDetails } : {}
+        });
+        return;
+      }
+      this.lastTurnError = { turnId, error };
+      const pending = this.pendingTurnCompletion;
+      if (pending && !pending.opened && (turnId === null || pending.turnId === null || pending.turnId === turnId)) {
+        this.emitRawTurnCompletion(turnId ?? pending.turnId, "failed", error, "error:unopened-turn");
+      }
       return;
     }
     logger.logger.debug(`[CodexAppServer] Notification: ${method}`);