@threadbase-sh/streamer 1.46.1 → 1.47.0

package/dist/index.js

@@ -1040,12 +1040,66 @@ var PTY_COLS = 120;
 var PTY_ROWS = 40;
 var SCREEN_SCROLLBACK = 1e3;
 var CODEX_PROMPT_READY_TEXT = "Ready";
+var CODEX_BUSY_STATUS_RE = /\b(?:Starting|Working)\b/;
+var CODEX_MCP_BOOT_RE = /Booting MCP|Starting MCP servers/i;
 var CODEX_TRUST_GATE_REGEX = /trust the contents/i;
 var CODEX_HOOKS_GATE_REGEX = /hooks need review/i;
+var CODEX_ACTIVE_WRITER_RE = /already has an active writer|-32600/;
+var CODEX_ACTIVE_WRITER_CODE = "codex_active_writer";
+var CODEX_USAGE_LIMIT_RE = /you(?:'ve| have) hit your usage limit/i;
+var CODEX_USAGE_RESET_TIP_RE = /usage limit reset available/i;
+var CODEX_RATE_LIMIT_MENU_RE = /approaching rate limits/i;
+function parseCodexNumberedOptions(lines) {
+  const options = [];
+  for (const line of lines) {
+    const m = /^\s*›?\s*(\d+)\.\s+(.+?)\s*$/.exec(line.trimEnd());
+    if (!m) continue;
+    const label = m[2].replace(/\s*\(selected\)\s*$/i, "").trim();
+    options.push({ index: Number(m[1]), label, answerKeys: `${m[1]}\r` });
+  }
+  return options;
+}
+function detectCodexBlockingPrompt(lines) {
+  const screenText = lines.join("\n");
+  const usageLine = lines.find((l) => CODEX_USAGE_LIMIT_RE.test(l))?.trim();
+  const tipLine = lines.find((l) => CODEX_USAGE_RESET_TIP_RE.test(l))?.trim();
+  const rateMenu = CODEX_RATE_LIMIT_MENU_RE.test(screenText);
+  if (!usageLine && !rateMenu && !tipLine) return null;
+  const soft = !usageLine && !rateMenu && Boolean(tipLine);
+  const prompt = usageLine ?? lines.find((l) => CODEX_RATE_LIMIT_MENU_RE.test(l))?.trim() ?? tipLine ?? "Codex usage limit reached";
+  const detail = lines.find((l) => /try again at/i.test(l))?.trim();
+  const options = parseCodexNumberedOptions(lines);
+  if (options.length === 0) {
+    options.push({ index: 1, label: soft ? "Dismiss" : "OK", answerKeys: "\x1B" });
+  }
+  return { prompt, ...detail ? { detail } : {}, options, ...soft ? { soft: true } : {} };
+}
 var QUIET_DETECT_MS = 500;
 var CODEX_READY_FALLBACK_MS = 8e3;
 var SUBMIT_BYTES = "\r";
 var CODEX_SUBMIT_DELAY_MS = 16;
+var CODEX_SUBMIT_MAX_WAIT_MS = 500;
+var CODEX_SUBMIT_STALE_MS = 2e3;
+function codexStatusBarLine(lines) {
+  return [...lines].reverse().find((l) => l.trim() !== "") ?? "";
+}
+function codexScreenBlocksComposer(lines) {
+  const screenText = lines.join("\n");
+  if (CODEX_HOOKS_GATE_REGEX.test(screenText) || CODEX_TRUST_GATE_REGEX.test(screenText)) {
+    return true;
+  }
+  if (CODEX_MCP_BOOT_RE.test(screenText)) return true;
+  return CODEX_BUSY_STATUS_RE.test(codexStatusBarLine(lines));
+}
+function codexScreenShowsReady(lines) {
+  if (codexScreenBlocksComposer(lines)) return false;
+  return codexStatusBarLine(lines).includes(CODEX_PROMPT_READY_TEXT);
+}
+function codexScreenLooksIdle(lines) {
+  if (codexScreenBlocksComposer(lines)) return false;
+  if (codexScreenShowsReady(lines)) return true;
+  return lines.some((l) => /^\s*[›>]\s/.test(l) || l.includes("\u203A"));
+}
 function digestBytes(s) {
   const escaped = s.replace(new RegExp(String.fromCharCode(27), "g"), "\\x1b").replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t");
   if (escaped.length <= 200) return escaped;
@@ -1136,6 +1190,21 @@ var CodexPtyRunner = class {
   quietCheckers = /* @__PURE__ */ new Map();
   // Per-session flat backstop from spawn (CODEX_READY_FALLBACK_MS).
   readyFallbackTimers = /* @__PURE__ */ new Map();
+  // After a user submit: if Working never appears, recover from stuck `running`.
+  submitWatchTimers = /* @__PURE__ */ new Map();
+  // Wall-clock of the last PTY chunk per session — writeSubmit waits until
+  // this hasn't advanced for CODEX_SUBMIT_DELAY_MS before writing \r.
+  lastChunkAt = /* @__PURE__ */ new Map();
+  // Sessions that have shown a Working status bar since the last user submit.
+  // Mid-session Ready→waiting_input only fires after this, so a still-painted
+  // Ready bar immediately after sendInput cannot flip status back before the
+  // turn starts (which would let grace/hold kill a live turn).
+  turnBusy = /* @__PURE__ */ new Set();
+  // Usage-limit / rate-limit menus — content key for deduped permission cards.
+  openBlockingPrompt = /* @__PURE__ */ new Map();
+  // Last codex.screen fingerprint per session — only emit when it changes so
+  // MCP boot redraw storms don't flood the log.
+  lastScreenLog = /* @__PURE__ */ new Map();
   // In-flight start()/startFresh() calls keyed by sessionId. A second
   // concurrent resume for the same session (double-tap, client retry) awaits
   // the first call's promise instead of spawning a duplicate PTY (CRITICAL #3).
@@ -1165,24 +1234,27 @@ var CodexPtyRunner = class {
     return promise;
   }
   async doStart(sessionId, options) {
+    return this.launch(
+      sessionId,
+      ["resume", options.resumeId ?? sessionId, "--cd", options.projectPath, "--no-alt-screen"],
+      options
+    );
+  }
+  // Spawn a Codex PTY under `sessionId` and wire up the shared boot machinery
+  // (screen, ready fallback, output/exit handlers). The only difference between
+  // resume, fresh and fork is argv.
+  async launch(sessionId, args, options) {
     const nodePty = await loadPty();
     const projectName = options.projectName ?? basename(options.projectPath);
     let proc;
     try {
-      proc = nodePty.spawn(
-        resolveCodexExe(),
-        // `sessionId` stays the runner's map key — only argv carries the
-        // provider-side id, so a resumed Codex session keeps the placeholder id
-        // its client already navigated to.
-        ["resume", options.resumeId ?? sessionId, "--cd", options.projectPath, "--no-alt-screen"],
-        {
-          name: "xterm-256color",
-          cols: PTY_COLS,
-          rows: PTY_ROWS,
-          cwd: options.projectPath,
-          env: process.env
-        }
-      );
+      proc = nodePty.spawn(resolveCodexExe(), args, {
+        name: "xterm-256color",
+        cols: PTY_COLS,
+        rows: PTY_ROWS,
+        cwd: options.projectPath,
+        env: process.env
+      });
     } catch (err) {
       clearCodexExeCache();
       throw err;
@@ -1222,71 +1294,85 @@ var CodexPtyRunner = class {
   // binding logic). This runner generates a local placeholder id for the
   // ManagedSession handle only.
   async startFresh(options) {
-    const nodePty = await loadPty();
     const sessionId = randomUUID();
-    const projectName = options.projectName ?? basename(options.projectPath);
     const args = ["--cd", options.projectPath, "--no-alt-screen"];
     if (options.systemPrompt) {
       args.push(options.systemPrompt);
     }
-    let proc;
-    try {
-      proc = nodePty.spawn(resolveCodexExe(), args, {
-        name: "xterm-256color",
-        cols: PTY_COLS,
-        rows: PTY_ROWS,
-        cwd: options.projectPath,
-        env: process.env
-      });
-    } catch (err) {
-      clearCodexExeCache();
-      throw err;
-    }
-    const session = {
-      id: sessionId,
-      provider: CODEX_CLI_PROVIDER,
-      projectPath: options.projectPath,
-      projectName,
-      branch: "",
-      status: "running",
-      statusSource: "spawn",
-      statusUpdatedAt: /* @__PURE__ */ new Date(),
-      startedAt: /* @__PURE__ */ new Date(),
-      completedAt: null,
-      promptCount: 0,
-      lastOutput: "",
-      process: proc,
-      outputBuffer: Buffer.alloc(0),
-      screen: createScreen(),
-      inputHistory: []
-    };
-    this.sessions.set(sessionId, session);
-    this.pendingReady.add(sessionId);
-    this.armReadyFallback(sessionId);
-    proc.onData((data) => {
-      this.handleOutput(sessionId, data);
-    });
-    proc.onExit(({ exitCode }) => {
-      this.pendingReady.delete(sessionId);
-      this.handleExit(sessionId, exitCode);
-    });
-    return toPublicSession(session);
+    return this.launch(sessionId, args, options);
   }
-  // Flat backstop: if neither the "Ready" marker nor the quiet-checker settled
-  // the session within CODEX_READY_FALLBACK_MS of spawn, mark it ready anyway
-  // so start requests resolve and mobile can watch the boot live. unref() so a
-  // pending timer never holds the process open.
+  /**
+   * Fork an existing Codex conversation into a new, independently-owned one
+   * (`codex fork <session-id>`).
+   *
+   * This is the recovery path for a rollout Codex will not let us resume: fork
+   * starts a *new* rollout seeded from the source's history and never touches
+   * the source's writer, so the terminal / VS Code / desktop client that owns
+   * it keeps running untouched. Like a fresh start, Codex assigns the new
+   * rollout id itself — the returned session is keyed by a local placeholder
+   * until watchForCodexRollout binds the real id.
+   */
+  async startFork(options) {
+    const sessionId = randomUUID();
+    return this.launch(
+      sessionId,
+      ["fork", options.forkFromId, "--cd", options.projectPath, "--no-alt-screen"],
+      options
+    );
+  }
+  // Flat backstop: if the "Ready" marker never appears within
+  // CODEX_READY_FALLBACK_MS of spawn (truncated status bar), mark ready once
+  // the screen is no longer Starting/Working/MCP-booting. Re-arms while the
+  // boot is still busy so a slow MCP load cannot be mistaken for Ready.
+  // unref() so a pending timer never holds the process open.
   armReadyFallback(sessionId) {
     const timer = setTimeout(() => {
       this.readyFallbackTimers.delete(sessionId);
-      const session = this.sessions.get(sessionId);
-      if (session?.status === "running" && this.pendingReady.has(sessionId)) {
-        this.markReady(sessionId, session, "timeout-fallback", "fallback:timeout");
-      }
+      void this.tryReadyFallback(sessionId);
     }, CODEX_READY_FALLBACK_MS);
     timer.unref?.();
     this.readyFallbackTimers.set(sessionId, timer);
   }
+  async tryReadyFallback(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (session?.status !== "running" || !this.pendingReady.has(sessionId)) return;
+    if (session.outputBuffer.length === 0) {
+      this.markReady(sessionId, session, "timeout-fallback", "fallback:timeout");
+      return;
+    }
+    try {
+      const lines = await this.getOutputLines(sessionId, PTY_ROWS);
+      if (!this.pendingReady.has(sessionId)) return;
+      const busy = codexScreenBlocksComposer(lines);
+      const bar = codexStatusBarLine(lines);
+      this.log.info(
+        `[codex.ready_fallback] ${sessionId.slice(0, 8)} busy=${busy} bar=${JSON.stringify(bar.slice(0, 120))}`,
+        {
+          event: "codex.ready_fallback",
+          sessionId,
+          busy,
+          hasReady: codexScreenShowsReady(lines),
+          statusBar: bar.slice(0, 160)
+        }
+      );
+      if (busy) {
+        this.armReadyFallback(sessionId);
+        return;
+      }
+      if (!codexScreenShowsReady(lines) && !codexScreenLooksIdle(lines)) {
+        this.armReadyFallback(sessionId);
+        return;
+      }
+      this.markReady(sessionId, session, "timeout-fallback", "fallback:timeout");
+    } catch (err) {
+      this.log.warn("[codex.ready_fallback] failed", {
+        event: "codex.ready_fallback_failed",
+        sessionId,
+        err
+      });
+      if (this.pendingReady.has(sessionId)) this.armReadyFallback(sessionId);
+    }
+  }
   // Write raw key bytes directly to the PTY, same as PTYManager.sendKeys.
   sendKeys(sessionId, keys) {
     const session = this.sessions.get(sessionId);
@@ -1347,7 +1433,7 @@ var CodexPtyRunner = class {
     if (session.status === "idle") {
       throw new Error(`Session is idle (no active PTY): ${sessionId}`);
     }
-    if (this.pendingReady.has(sessionId)) {
+    if (this.pendingReady.has(sessionId) || this.openGate.has(sessionId)) {
       const queue = this.queuedInputs.get(sessionId) ?? [];
       queue.push(input);
       this.queuedInputs.set(sessionId, queue);
@@ -1371,14 +1457,17 @@ var CodexPtyRunner = class {
       session.statusUpdatedAt = /* @__PURE__ */ new Date();
       this.onStatusChange?.(toPublicSession(session));
     }
+    this.turnBusy.delete(sessionId);
     this.writeSubmit(sessionId, session, input, "direct", session.promptCount + 1);
     session.lastActivityAt = /* @__PURE__ */ new Date();
     session.promptCount++;
     return session.promptCount;
   }
   // Write the input as plain bytes (no bracketed-paste wrap — Phase 0
-  // confirmed Codex accepts plain keystrokes), then submit \r after a short
-  // delay so Codex's TUI gets an event-loop tick to process the input first.
+  // confirmed Codex accepts plain keystrokes), then submit \r once the PTY
+  // has been quiet for CODEX_SUBMIT_DELAY_MS. A flat delay fired \r into a
+  // still-repainting TUI and the Enter became a compose newline instead of a
+  // turn submit (same pathology Claude's quiescence wait fixed).
   writeSubmit(sessionId, session, input, path, promptCount) {
     this.recordUserMessage(session, input);
     this.log.info(
@@ -1393,12 +1482,21 @@ var CodexPtyRunner = class {
         phase: "input"
       }
     );
+    const writeAt = Date.now();
     session.process.write(input);
-    setTimeout(() => {
+    const trySubmit = () => {
       const current = this.sessions.get(sessionId);
       if (!current || current !== session) return;
+      const now = Date.now();
+      const lastChunk = this.lastChunkAt.get(sessionId) ?? writeAt;
+      const quiet = now - lastChunk >= CODEX_SUBMIT_DELAY_MS;
+      const timedOut = now - writeAt >= CODEX_SUBMIT_MAX_WAIT_MS;
+      if (!quiet && !timedOut) {
+        setTimeout(trySubmit, CODEX_SUBMIT_DELAY_MS);
+        return;
+      }
       this.log.info(
-        `[codex.input.submit] ${sessionId.slice(0, 8)} promptCount=${promptCount} digest=\\r`,
+        `[codex.input.submit] ${sessionId.slice(0, 8)} promptCount=${promptCount} digest=\\r waitedMs=${now - writeAt} timedOut=${timedOut}`,
         {
           event: "codex.input_write",
           sessionId,
@@ -1406,11 +1504,55 @@ var CodexPtyRunner = class {
           byteLen: SUBMIT_BYTES.length,
           digest: "\\r",
           path,
-          phase: "submit"
+          phase: "submit",
+          waitedMs: now - writeAt,
+          timedOut
         }
       );
       current.process.write(SUBMIT_BYTES);
-    }, CODEX_SUBMIT_DELAY_MS);
+      this.armSubmitWatch(sessionId);
+    };
+    setTimeout(trySubmit, CODEX_SUBMIT_DELAY_MS);
+  }
+  // If Working never appears after \r, the turn did not start — recover from
+  // stuck `running` even when no further PTY chunks re-arm the quiet checker
+  // (session ddc67b57: one post-submit chunk, then silence forever).
+  armSubmitWatch(sessionId) {
+    const prev = this.submitWatchTimers.get(sessionId);
+    if (prev) clearTimeout(prev);
+    const timer = setTimeout(() => {
+      this.submitWatchTimers.delete(sessionId);
+      void this.trySubmitStaleRecovery(sessionId);
+    }, CODEX_SUBMIT_STALE_MS);
+    timer.unref?.();
+    this.submitWatchTimers.set(sessionId, timer);
+  }
+  async trySubmitStaleRecovery(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (session?.status !== "running") return;
+    if (this.turnBusy.has(sessionId)) return;
+    if (session.statusSource !== "user-input") return;
+    try {
+      const lines = await this.getOutputLines(sessionId, PTY_ROWS);
+      if (session.status !== "running" || this.turnBusy.has(sessionId)) return;
+      if (codexScreenBlocksComposer(lines)) {
+        this.armSubmitWatch(sessionId);
+        return;
+      }
+      this.log.info(`[codex.submit_stale] ${sessionId.slice(0, 8)} recovering`, {
+        event: "codex.submit_stale",
+        sessionId,
+        statusBar: codexStatusBarLine(lines).slice(0, 160)
+      });
+      this.markReady(sessionId, session, "quiet-fallback", "submit-stale");
+    } catch (err) {
+      this.log.warn("[codex.submit_stale] failed", {
+        event: "codex.submit_stale_failed",
+        sessionId,
+        err
+      });
+      this.armSubmitWatch(sessionId);
+    }
   }
   // Drain any inputs sent while the session was still pendingReady, writing
   // them in arrival order now that Codex is Ready. No-op while a gate dialog
@@ -1485,11 +1627,20 @@ var CodexPtyRunner = class {
     const timer = this.readyFallbackTimers.get(sessionId);
     if (timer) clearTimeout(timer);
     this.readyFallbackTimers.delete(sessionId);
+    const submitWatch = this.submitWatchTimers.get(sessionId);
+    if (submitWatch) clearTimeout(submitWatch);
+    this.submitWatchTimers.delete(sessionId);
+    this.lastChunkAt.delete(sessionId);
     if (this.openGate.delete(sessionId)) {
       this.onPermissionChange?.(sessionId, null);
     }
     this.gateActioned.delete(`${sessionId}:hooks`);
     this.gateActioned.delete(`${sessionId}:trust`);
+    this.turnBusy.delete(sessionId);
+    if (this.openBlockingPrompt.delete(sessionId)) {
+      this.onPermissionChange?.(sessionId, null);
+    }
+    this.lastScreenLog.delete(sessionId);
   }
   getOutput(sessionId) {
     const session = this.sessions.get(sessionId);
@@ -1561,10 +1712,19 @@ var CodexPtyRunner = class {
     this.gateActioned.clear();
     this.quietCheckers.clear();
     this.readyFallbackTimers.clear();
+    for (const timer of this.submitWatchTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.submitWatchTimers.clear();
+    this.lastChunkAt.clear();
+    this.turnBusy.clear();
+    this.openBlockingPrompt.clear();
+    this.lastScreenLog.clear();
   }
   handleOutput(sessionId, data) {
     const session = this.sessions.get(sessionId);
     if (!session) return;
+    this.lastChunkAt.set(sessionId, Date.now());
     const chunk = Buffer.from(data, "utf-8");
     session.outputBuffer = Buffer.concat([session.outputBuffer, chunk]);
     if (session.outputBuffer.length > OUTPUT_BUFFER_MAX) {
@@ -1601,16 +1761,24 @@ var CodexPtyRunner = class {
   //   - Gates (directory trust, hooks review) — checked on EVERY pass,
   //     independent of pendingReady, so a gate appearing after ready is still
   //     surfaced and a gate leaving the screen closes its card.
-  //   - Readiness — the "Ready" status-bar marker while pendingReady, plus the
-  //     quiet path: after QUIET_DETECT_MS of PTY silence a still-pending
-  //     session is marked ready anyway (`›` alone is NOT a marker — Phase 0 —
-  //     but a quiet boot screen is more useful to the user live than a
-  //     spinner, and "Ready" may be truncated off the 120-col status bar).
-  async detectScreenState(sessionId, trigger) {
+  //   - Readiness — boot (pendingReady) requires the "Ready" status-bar marker
+  //     (quiet alone never settles boot — Starting shows `›` already). Mid-
+  //     session, running → waiting_input after Working then Ready (or a stale
+  //     Ready recovery if the turn never started).
+  async detectScreenState(sessionId, _trigger) {
     const session = this.sessions.get(sessionId);
     if (!session || session.status === "idle") return;
     const lines = await this.getOutputLines(sessionId, PTY_ROWS);
     const screenText = lines.join("\n");
+    if (this.pendingReady.has(sessionId) && CODEX_ACTIVE_WRITER_RE.test(screenText)) {
+      this.failStartup(
+        sessionId,
+        session,
+        CODEX_ACTIVE_WRITER_CODE,
+        "This Codex session is already open in another client"
+      );
+      return;
+    }
     const gate = CODEX_HOOKS_GATE_REGEX.test(screenText) ? "hooks" : CODEX_TRUST_GATE_REGEX.test(screenText) ? "trust" : null;
     if (gate) {
       this.handleGate(sessionId, session, gate, lines);
@@ -1618,12 +1786,83 @@ var CodexPtyRunner = class {
       this.onPermissionChange?.(sessionId, null);
       this.flushQueuedInputs(sessionId);
     }
-    if (session.status !== "running" || !this.pendingReady.has(sessionId)) return;
-    const lastNonBlank2 = [...lines].reverse().find((l) => l.trim() !== "") ?? "";
-    if (lastNonBlank2.includes(CODEX_PROMPT_READY_TEXT)) {
-      this.markReady(sessionId, session, "prompt-marker", `marker:${CODEX_PROMPT_READY_TEXT}`);
-    } else if (trigger === "quiet") {
-      this.markReady(sessionId, session, "quiet-fallback", "quiet:timeout");
+    const blocking = detectCodexBlockingPrompt(lines);
+    if (blocking) {
+      const elevateSoft = !blocking.soft || session.status === "running" && session.statusSource === "user-input" && !this.turnBusy.has(sessionId) && !this.pendingReady.has(sessionId);
+      if (elevateSoft) {
+        this.handleBlockingPrompt(sessionId, session, blocking);
+      }
+    } else if (this.openBlockingPrompt.delete(sessionId)) {
+      this.onPermissionChange?.(sessionId, null);
+    }
+    const hasReady = codexScreenShowsReady(lines);
+    const busy = codexScreenBlocksComposer(lines);
+    const bar = codexStatusBarLine(lines);
+    const screenFp = [
+      this.pendingReady.has(sessionId) ? "1" : "0",
+      session.status,
+      hasReady ? "1" : "0",
+      busy ? "1" : "0",
+      blocking ? blocking.soft ? "soft" : "1" : "0",
+      bar.slice(0, 80)
+    ].join("|");
+    if (this.lastScreenLog.get(sessionId) !== screenFp) {
+      this.lastScreenLog.set(sessionId, screenFp);
+      this.log.info(
+        `[codex.screen] ${sessionId.slice(0, 8)} pending=${this.pendingReady.has(sessionId)} status=${session.status} ready=${hasReady} busy=${busy} usage=${Boolean(blocking)} bar=${JSON.stringify(bar.slice(0, 100))}`,
+        {
+          event: "codex.screen",
+          sessionId,
+          trigger: _trigger,
+          pendingReady: this.pendingReady.has(sessionId),
+          status: session.status,
+          hasReady,
+          busy,
+          usageHit: Boolean(blocking),
+          usageSoft: Boolean(blocking?.soft),
+          statusBar: bar.slice(0, 160)
+        }
+      );
+    }
+    if (this.pendingReady.has(sessionId)) {
+      if (hasReady) {
+        this.markReady(sessionId, session, "prompt-marker", `marker:${CODEX_PROMPT_READY_TEXT}`);
+      }
+      return;
+    }
+    if (session.status === "running") {
+      if (/\bWorking\b/.test(bar)) {
+        this.turnBusy.add(sessionId);
+        const watch = this.submitWatchTimers.get(sessionId);
+        if (watch) clearTimeout(watch);
+        this.submitWatchTimers.delete(sessionId);
+      }
+      if (hasReady && this.turnBusy.has(sessionId)) {
+        this.turnBusy.delete(sessionId);
+        this.markReady(sessionId, session, "prompt-marker", `marker:${CODEX_PROMPT_READY_TEXT}`);
+      } else if (!this.turnBusy.has(sessionId) && !busy && session.statusSource === "user-input" && session.statusUpdatedAt != null && Date.now() - session.statusUpdatedAt.getTime() >= CODEX_SUBMIT_STALE_MS) {
+        this.markReady(sessionId, session, "quiet-fallback", "submit-stale");
+      }
+    }
+  }
+  // Surface quota / rate-limit screens as permission cards and stop leaving
+  // the session stuck in `running` while Codex waits for a menu pick.
+  handleBlockingPrompt(sessionId, session, blocking) {
+    const key = `${blocking.prompt}\0${blocking.detail ?? ""}\0${blocking.options.map((o) => o.index).join(",")}`;
+    const prev = this.openBlockingPrompt.get(sessionId);
+    if (prev !== key) {
+      this.openBlockingPrompt.set(sessionId, key);
+      session.failureReason = blocking.detail ? `${blocking.prompt} ${blocking.detail}` : blocking.prompt;
+      this.log.info(`[codex.usage_limit] ${sessionId.slice(0, 8)}`, {
+        event: "codex.usage_limit",
+        sessionId,
+        prompt: blocking.prompt
+      });
+      this.onPermissionChange?.(sessionId, blocking);
+    }
+    if (session.status === "running") {
+      this.turnBusy.delete(sessionId);
+      this.markReady(sessionId, session, "quiet-fallback", "usage-limit");
     }
   }
   // Answer a gate from the persisted remember-store, or surface it as a
@@ -1665,12 +1904,52 @@ var CodexPtyRunner = class {
       reason
     });
     this.onStatusChange?.(toPublicSession(session));
-    if (this.pendingReady.has(sessionId)) {
-      this.pendingReady.delete(sessionId);
+    const wasPending = this.pendingReady.delete(sessionId);
+    const submitWatch = this.submitWatchTimers.get(sessionId);
+    if (submitWatch) clearTimeout(submitWatch);
+    this.submitWatchTimers.delete(sessionId);
+    if (wasPending) {
+      const timer = this.readyFallbackTimers.get(sessionId);
+      if (timer) clearTimeout(timer);
+      this.readyFallbackTimers.delete(sessionId);
       this.flushQueuedInputs(sessionId);
       this.onReady?.(toPublicSession(session));
     }
   }
+  /**
+   * Tear down a session that failed before it ever became usable, and report
+   * the reason in machine-readable form.
+   *
+   * Deliberately NOT markReady + exit: the caller must be able to tell a
+   * never-started session from a live one, `onReady` must not fire (no
+   * `session_ready` for a failed start), and every piece of per-session state —
+   * queue, timers, quiet-checker, gate cards, screen — has to go, since the
+   * session is removed from the map and nothing will collect it later.
+   */
+  failStartup(sessionId, session, code, message) {
+    this.log.warn(`[codex.start_failed] ${sessionId.slice(0, 8)} ${code}`, {
+      event: "codex.start_failed",
+      sessionId,
+      code,
+      message
+    });
+    session.failureCode = code;
+    session.failureReason = message;
+    session.status = "idle";
+    session.statusSource = "process-exit";
+    session.statusUpdatedAt = /* @__PURE__ */ new Date();
+    session.completedAt = /* @__PURE__ */ new Date();
+    this.pendingReady.delete(sessionId);
+    this.queuedInputs.delete(sessionId);
+    this.clearSessionDetectors(sessionId);
+    this.sessions.delete(sessionId);
+    try {
+      session.process.kill("SIGINT");
+    } catch {
+    }
+    session.screen.dispose();
+    this.onStatusChange?.(toPublicSession(session));
+  }
   handleExit(sessionId, exitCode) {
     const session = this.sessions.get(sessionId);
     if (!session) return;
@@ -1706,6 +1985,7 @@ function toPublicSession(s) {
     promptCount: s.promptCount,
     lastOutput: s.lastOutput,
     ...s.failureReason != null && { failureReason: s.failureReason },
+    ...s.failureCode != null && { failureCode: s.failureCode },
     ...s.lastActivityAt != null && { lastActivityAt: s.lastActivityAt },
     ...s.statusSource != null && { statusSource: s.statusSource },
     ...s.statusUpdatedAt != null && { statusUpdatedAt: s.statusUpdatedAt },
@@ -3206,6 +3486,24 @@ var LiveSessionManager = class {
     const runner = this.assertSupportedProvider(provider, options.projectPath);
     return runner.startFresh(options);
   }
+  /**
+   * Fork an existing conversation into a new session. Codex-only: `codex fork`
+   * has no Claude Code equivalent, and there is no safe generic fallback — a
+   * silent downgrade to resume would attach to the very writer the caller is
+   * trying to leave alone.
+   */
+  async startFork(options) {
+    const provider = options.provider ?? CODEX_CLI_PROVIDER;
+    const runner = this.remoteRunner ?? this.runners.get(provider);
+    if (!(runner instanceof CodexPtyRunner)) {
+      const err = new Error(
+        this.remoteRunner ? "Forking is not supported while sessions are hosted by the pty-host" : `Forking is not supported for ${provider} sessions`
+      );
+      err.statusCode = 501;
+      throw err;
+    }
+    return runner.startFork(options);
+  }
   sendInput(sessionId, input) {
     return this.runnerFor(sessionId).sendInput(sessionId, input);
   }
@@ -3481,7 +3779,7 @@ async function discoverWindowsViaCim() {
       "-NoProfile",
       "-NonInteractive",
       "-Command",
-      "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress"
+      `Get-CimInstance Win32_Process -Filter "Name = 'claude.exe' OR Name = 'claude' OR Name = 'node.exe' OR Name = 'bun.exe' OR Name = 'deno.exe'" | Select-Object ProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress`
     ]);
   } catch {
     return null;
@@ -5681,6 +5979,10 @@ var createSessionRoutes = (deps) => {
     await deps.handleAdopt(c.req.param("id"), c.env.outgoing);
     return alreadyHandled6();
   });
+  app.post("/:id/fork", async (c) => {
+    await deps.handleFork(c.req.param("id"), c.env.incoming, c.env.outgoing);
+    return alreadyHandled6();
+  });
   app.post("/:id/stop", async (c) => {
     await deps.handleStopSession(c.req.param("id"), c.env.outgoing);
     return alreadyHandled6();
@@ -7612,7 +7914,6 @@ function rowToProject(row) {
     lastIndexedAt: row.last_indexed_at,
     latestMessageAt: row.latest_message_at,
     latestMessageId: row.latest_message_id,
-    messageCount: row.message_count,
     createdAt: row.created_at,
     updatedAt: row.updated_at
   };
@@ -7631,12 +7932,12 @@ var ProjectsRepository = class {
       INSERT INTO projects (
         id, path, name,
         last_conversation_id, last_conversation_created_at, last_indexed_at,
-        latest_message_at, latest_message_id, message_count,
+        latest_message_at, latest_message_id,
         created_at, updated_at
       ) VALUES (
         @id, @path, @name,
         @last_conversation_id, @last_conversation_created_at, @last_indexed_at,
-        @latest_message_at, @latest_message_id, @message_count,
+        @latest_message_at, @latest_message_id,
         @created_at, @updated_at
       )
     `);
@@ -7697,7 +7998,6 @@ var ProjectsRepository = class {
       last_indexed_at: now,
       latest_message_at: input.latestMessageAt ?? null,
       latest_message_id: input.latestMessageId ?? null,
-      message_count: 0,
       created_at: now,
       updated_at: now
     });
@@ -7791,9 +8091,39 @@ async function recordUpload(pool2, instanceId, row) {
 }
 
 // src/handlers/handleListProjects.ts
-import { readdirSync as readdirSync3, statSync as statSync4 } from "fs";
+import { closeSync as closeSync4, openSync as openSync4, readdirSync as readdirSync3, readSync as readSync4, statSync as statSync4 } from "fs";
 import { homedir as homedir6 } from "os";
 import { join as join13 } from "path";
+var HEAD_BYTES = 64 * 1024;
+var MAX_FILES_PROBED = 3;
+function readRecordedCwd(dir) {
+  let files;
+  try {
+    files = readdirSync3(dir).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return null;
+  }
+  for (const file of files.slice(0, MAX_FILES_PROBED)) {
+    let fd;
+    try {
+      fd = openSync4(join13(dir, file), "r");
+      const buf = Buffer.alloc(HEAD_BYTES);
+      const bytes = readSync4(fd, buf, 0, HEAD_BYTES, 0);
+      for (const line of buf.subarray(0, bytes).toString("utf8").split("\n")) {
+        if (!line.includes('"cwd"')) continue;
+        try {
+          const cwd = JSON.parse(line).cwd;
+          if (typeof cwd === "string" && cwd.length > 0) return cwd;
+        } catch {
+        }
+      }
+    } catch {
+    } finally {
+      if (fd !== void 0) closeSync4(fd);
+    }
+  }
+  return null;
+}
 function decodeProjectPath(dirName) {
   return dirName.replace(/-/g, "/");
 }
@@ -7810,9 +8140,7 @@ function handleListProjects(url, res) {
         mtime = statSync4(fullPath).mtimeMs;
       } catch {
       }
-      const path = decodeProjectPath(dirName);
-      const name = path.split("/").filter(Boolean).pop() ?? dirName;
-      return { name, path, dirName, mtime };
+      return { dirName: String(dirName), mtime };
     }).sort((a, b) => b.mtime - a.mtime);
   } catch {
     res.writeHead(200, { "Content-Type": "application/json" });
@@ -7820,7 +8148,11 @@ function handleListProjects(url, res) {
     return;
   }
   const total = entries.length;
-  const page = entries.slice(offset, offset + limit).map(({ name, path, dirName }) => ({ name, path, dirName }));
+  const page = entries.slice(offset, offset + limit).map(({ dirName }) => {
+    const path = readRecordedCwd(join13(projectsDir, dirName)) ?? decodeProjectPath(String(dirName));
+    const name = path.split(/[\\/]/).filter(Boolean).pop() ?? dirName;
+    return { name, path, dirName };
+  });
   res.writeHead(200, { "Content-Type": "application/json" });
   res.end(JSON.stringify({ projects: page, total }));
 }
@@ -8346,8 +8678,12 @@ var ConversationWatcher = class {
       offset = 0;
     }
     const watcher = chokidar.watch(filePath, {
-      ignoreInitial: true,
-      awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 25 }
+      ignoreInitial: true
+      // No awaitWriteFinish: readNewLines already coalesces bursts via the
+      // reading/pending flags, and awaitWriteFinish on Linux has been observed
+      // to drop the unlink when a just-created file is deleted inside the
+      // stability window — leaving an external tail attached until the 5 min
+      // idle sweep (#393).
     });
     watcher.on("change", () => {
       void this.readNewLines(key);
@@ -9575,6 +9911,69 @@ function planAutoResume(rows, opts) {
   };
 }
 
+// src/services/sessions/codexRolloutOwner.ts
+import { execFile as execFile3 } from "child_process";
+var ROLLOUT_OWNER_TIMEOUT_MS = 800;
+function runLsof(rolloutPath, timeoutMs) {
+  return new Promise((resolve2, reject) => {
+    const child = execFile3(
+      "lsof",
+      ["-F", "pc", "-w", "--", rolloutPath],
+      { windowsHide: true },
+      (err, stdout) => {
+        clearTimeout(timer);
+        if (err && !stdout) {
+          reject(err);
+          return;
+        }
+        resolve2(stdout);
+      }
+    );
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      reject(new Error("lsof timed out"));
+    }, timeoutMs);
+    timer.unref?.();
+    child.unref();
+  });
+}
+function parseLsofFieldOutput(stdout) {
+  const owners = [];
+  let pid = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("p")) {
+      const n = Number.parseInt(line.slice(1), 10);
+      pid = Number.isFinite(n) ? n : null;
+    } else if (line.startsWith("c") && pid != null) {
+      owners.push({ pid, command: line.slice(1).trim() });
+      pid = null;
+    }
+  }
+  return owners;
+}
+async function findRolloutOwner(rolloutPath, options = {}) {
+  const platform3 = options.platform ?? process.platform;
+  if (platform3 === "win32") return null;
+  const selfPid = options.selfPid ?? process.pid;
+  const run2 = options.run ?? runLsof;
+  let stdout;
+  try {
+    stdout = await run2(rolloutPath, options.timeoutMs ?? ROLLOUT_OWNER_TIMEOUT_MS);
+  } catch {
+    return null;
+  }
+  for (const { pid, command } of parseLsofFieldOutput(stdout)) {
+    if (pid === selfPid) continue;
+    return { pid, command, source: command === "codex" ? "terminal" : "unknown" };
+  }
+  return null;
+}
+
 // src/services/sessions/conversationBusy.ts
 import { statSync as statSync8 } from "fs";
 var RESUME_BUSY_WINDOW_MS = 12e4;
@@ -9887,6 +10286,9 @@ function findCursorBoundary(sorted, cursor, key, order) {
   }
   return sorted.length;
 }
+function isLiveMultiAgent(s) {
+  return s.currentTurnId !== void 0 && (s.status === "running" || s.status === "waiting_input");
+}
 function managedToResponse(s, ptyAttached) {
   return {
     id: s.id,
@@ -9905,8 +10307,18 @@ function managedToResponse(s, ptyAttached) {
     // leaves it gone, but the conversation is still resumable, not terminal —
     // `putOnHold` records that by leaving `statusSource: "shutdown"` (the only
     // place either runner sets it), so it is checked here alongside `rehydrated`.
-    lifecycle: ptyAttached ? "attached" : s.rehydrated || s.statusSource === "shutdown" ? "resumable" : s.failureReason != null ? "failed" : "completed",
-    lifecycleSource: ptyAttached ? s.reconciled ? "reconcile" : "spawn" : s.rehydrated ? "reconcile" : "exit",
+    // Multi-agent sessions never have a PTY (`currentTurnId` is defined — null
+    // while idle between turns — only on that path). While their status is
+    // still live they are `attached`, not terminal (#438).
+    // Otherwise, terminal requires evidence of termination — a recorded
+    // `failureReason`, or the `completedAt` every exit path stamps. Without
+    // either, no PTY here means the spawn has not landed, which is `starting`,
+    // not `completed` (tb-mobile #508). Scoped to the PTY path only
+    // (`currentTurnId === undefined`) — multi-agent never stamps `completedAt`
+    // at all, so an idle multi-agent session (no pre-attach race to
+    // disambiguate) stays `completed` regardless.
+    lifecycle: ptyAttached || isLiveMultiAgent(s) ? "attached" : s.rehydrated || s.statusSource === "shutdown" ? "resumable" : s.failureReason != null ? "failed" : s.currentTurnId === void 0 && s.completedAt == null ? "starting" : "completed",
+    lifecycleSource: ptyAttached || isLiveMultiAgent(s) ? s.reconciled ? "reconcile" : "spawn" : s.rehydrated ? "reconcile" : s.currentTurnId === void 0 && s.completedAt == null ? "spawn" : "exit",
     // We own its PTY, so `status` is the authoritative signal — no inferred
     // `activity` is attached for managed sessions.
     ownership: s.rehydrated ? "historical" : "managed",
@@ -9942,6 +10354,9 @@ function managedToResponse(s, ptyAttached) {
     ...s.resumedFromConversationId != null && {
       resumedFromConversationId: s.resumedFromConversationId
     },
+    ...s.forkedFromConversationId != null && {
+      forkedFromConversationId: s.forkedFromConversationId
+    },
     ...s.boundConversationId != null && { boundConversationId: s.boundConversationId },
     ...s.interruptedStatus != null && { interruptedStatus: s.interruptedStatus }
   };
@@ -10319,6 +10734,13 @@ var ADOPT_KILL_TIMEOUT_MS = 5e3;
 var ADOPT_KILL_POLL_MS = 100;
 var REFRESH_TTL_MS = 2e3;
 var START_READY_TIMEOUT_MS = 1e4;
+var CODEX_STARTUP_TIMEOUT_MS = 4e3;
+function resolveCodexStartupTimeoutMs(env = process.env) {
+  const raw = env.THREADBASE_CODEX_STARTUP_TIMEOUT_MS;
+  if (raw === void 0) return CODEX_STARTUP_TIMEOUT_MS;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : CODEX_STARTUP_TIMEOUT_MS;
+}
 var MODEL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 var EXTERNAL_TAIL_RECENCY_MS = RESUME_BUSY_WINDOW_MS;
 var EXTERNAL_TAIL_MAX = 32;
@@ -10329,6 +10751,22 @@ function parseIncludeAgentsEnv(raw) {
   const v = raw.trim().toLowerCase();
   return !(v === "0" || v === "false" || v === "no" || v === "off" || v === "");
 }
+function codexSessionActiveBody(outcome) {
+  return {
+    error: "This Codex session is already open in another client",
+    code: "CONVERSATION_BUSY",
+    reasonCode: "CODEX_SESSION_ACTIVE",
+    provider: CODEX_CLI_PROVIDER,
+    detectedBy: outcome.detectedBy,
+    lastActivityMs: outcome.lastActivityMs,
+    likelyOwner: "external",
+    canForce: false,
+    canTakeOver: false,
+    canFork: true,
+    ...outcome.ownerPid != null && { ownerPid: outcome.ownerPid },
+    ...outcome.ownerSource != null && { ownerSource: outcome.ownerSource }
+  };
+}
 var StreamerServer = class {
   httpServer;
   ptyManager;
@@ -10525,6 +10963,10 @@ var StreamerServer = class {
   liveActivityNotifier = null;
   liveActivityRenewal = null;
   discoveryCache = null;
+  // Single-flight for process discovery. Mobile polls GET /api/sessions and
+  // retries on timeout; without this, every concurrent request starts its own
+  // Windows CIM scan (observed: overlapping 80–100s /api/sessions responses).
+  discoveryInFlight = null;
   cacheDir;
   runtimeDbPath;
   tailSize;
@@ -10578,8 +11020,9 @@ var StreamerServer = class {
     this.tailSize = config.tailSize ?? loadTailSize() ?? 10;
     this.directoryDebounceMs = parseDirScanDebounceEnv(process.env.THREADBASE_DIR_SCAN_DEBOUNCE_MS) ?? config.directoryScanDebounceMs ?? 1e3;
     this.markScannerStaleDebounced = debounce(() => {
-      if (this.scannerReady) this.scannerStale = true;
-      else {
+      if (this.scannerReady) {
+        if (this.staleFiles.size > 0) this.scannerStale = true;
+      } else {
         this.scanner = null;
         this.staleFiles.clear();
       }
@@ -10671,6 +11114,12 @@ var StreamerServer = class {
         this.pendingLineSeqs.delete(filePath);
       },
       onConversationChanged: (filePath) => {
+        try {
+          statSync9(filePath);
+        } catch {
+          this.handleJsonlDeleted(filePath);
+          return;
+        }
         const tailed = this.fileWatcher.poke(filePath);
         if (!tailed) this.maybeAttachExternalTail(filePath);
         this.sweepIdleExternalTails();
@@ -10690,21 +11139,7 @@ var StreamerServer = class {
           event: "tail.truncated"
         });
       },
-      onFileDeleted: (filePath) => {
-        this.detachExternalTail(canonicalizeFilePath(filePath));
-        if (this.cacheMonitor?.pending) {
-          this.cacheMonitor.deferUnlink(filePath);
-          return;
-        }
-        const id = this.cache?.invalidateByFilePath(filePath);
-        if (id)
-          this.log.info(`Cache row invalidated after JSONL delete: ${id}`, {
-            id,
-            filePath,
-            event: "cache.invalidate_on_unlink"
-          });
-        this.cacheMonitor?.recordUnlink(filePath);
-      },
+      onFileDeleted: (filePath) => this.handleJsonlDeleted(filePath),
       onError: (filePath, err) => {
         const enospc = err.code === "ENOSPC";
         this.log.error(
@@ -10826,7 +11261,7 @@ var StreamerServer = class {
           this.wsHub.broadcast({ type: "session_update", session: resp });
         }
         void this.liveActivityNotifier?.onStatusChange(session, previousStatus);
-        this.sessionStatusBus.emit(`status:${session.id}`, session.status);
+        this.sessionStatusBus.emit(`status:${session.id}`, session.status, session);
       }
     });
     this.agentConfig = readAgentConfig();
@@ -10895,6 +11330,7 @@ var StreamerServer = class {
       handleSetSessionEffort: (id, req, res) => this.applyLiveSessionSetting(id, req, res, "effort"),
       handleUploadFile: (id, req, res) => this.handleUploadFile(id, req, res),
       handleAdopt: (id, res) => this.handleAdopt(id, res),
+      handleFork: (id, req, res) => this.handleFork(id, req, res),
       handleResume: (req, res) => this.handleResume(req, res),
       handleStartSession: (req, res) => this.handleStartSession(req, res),
       handleListConversations: (url, res) => this.handleListConversations(url, res),
@@ -12552,6 +12988,9 @@ var StreamerServer = class {
     return metas.filter((m) => m !== null);
   }
   async getScanner(skipStaleRescan = false) {
+    if (skipStaleRescan && this.scanner) {
+      return this.scanner;
+    }
     if (this.scannerReady) {
       await this.scannerReady;
       if (this.scanner) {
@@ -12594,29 +13033,38 @@ var StreamerServer = class {
     this.scannerReady = null;
     return this.getScanner();
   }
-  // refresh=1's scan: reuse the WARM scanner and re-run its scan with
-  // fullRescan:true — the escape hatch that bypasses the scanner's
-  // dir-mtime discovery gate, since an explicit user pull-to-refresh is exactly
-  // the "don't trust the gate, check disk for real" signal. Unlike
-  // getFreshScanner() this does NOT discard the warm scanner. scannerReady is
-  // only ever reassigned to a live scan promise (never nulled mid-scan), so the
-  // getScanner() anti-infinite-loop guard is preserved.
+  // refresh=1's scan: build a SHADOW scanner with fullRescan:true, then swap
+  // it in atomically. The escape hatch bypasses the scanner's dir-mtime
+  // discovery gate (an explicit user pull-to-refresh is exactly the "don't
+  // trust the gate, check disk for real" signal).
+  //
+  // Scanning in place would clear the non-persistent scanner's metadataCache
+  // at start, so a concurrent detail fetch that skipped the await would 404 a
+  // conversation that exists — and one that awaited would pay the full scan's
+  // wall clock (#368). Shadow-and-swap keeps this.scanner readable as the
+  // previous generation for the whole rebuild.
   async rescanForRefresh(onProgress) {
     if (this.scannerReady) await this.scannerReady;
     this.takeStaleFiles();
-    if (!this.scanner) {
-      this.scanner = new ConversationScanner();
-      this.allScanners.add(this.scanner);
-    }
-    const scanner = this.scanner;
-    this.scannerReady = scanner.scan({
+    const previous = this.scanner;
+    const statCache = this.buildStatCache(previous);
+    const shadow = this.newScanner(statCache ? { persistent: false } : void 0);
+    this.allScanners.add(shadow);
+    this.scannerReady = shadow.scan({
       ...this.scanProfiles ? { profiles: this.scanProfiles } : {},
       ...this.codexScanOpts(),
       fullRescan: true,
+      ...statCache ? { statCache } : {},
       ...onProgress ? { onProgress } : {}
     });
-    await this.scannerReady;
-    return scanner;
+    try {
+      await this.scannerReady;
+    } catch (err) {
+      this.scannerReady = null;
+      throw err;
+    }
+    this.scanner = shadow;
+    return shadow;
   }
   /**
    * The projects dirs disk discovery should walk — the single source of truth
@@ -12770,6 +13218,26 @@ var StreamerServer = class {
       event: "external_tail.detach"
     });
   }
+  /**
+   * Shared unlink path for the per-file watcher and the directory watcher.
+   * Detaches any external tail and drops the cache row (unless an integrity
+   * alert is freezing deletes).
+   */
+  handleJsonlDeleted(filePath) {
+    this.detachExternalTail(canonicalizeFilePath(filePath));
+    if (this.cacheMonitor?.pending) {
+      this.cacheMonitor.deferUnlink(filePath);
+      return;
+    }
+    const id = this.cache?.invalidateByFilePath(filePath);
+    if (id)
+      this.log.info(`Cache row invalidated after JSONL delete: ${id}`, {
+        id,
+        filePath,
+        event: "cache.invalidate_on_unlink"
+      });
+    this.cacheMonitor?.recordUnlink(filePath);
+  }
   /** Make room for one more tail by evicting the least recently active ones. */
   evictExternalTailsIfNeeded() {
     while (this.externalTails.size >= EXTERNAL_TAIL_MAX) {
@@ -12914,6 +13382,24 @@ var StreamerServer = class {
     if (this.scanProfiles) return null;
     const filePath = this.findJsonlPath(lookupId) ?? this.findLiveSessionFilePath(uuid) ?? this.findLiveSessionFilePath(lookupId);
     if (!filePath) return null;
+    if (this.scannerReady) {
+      const account = this.cache?.getMetaById(lookupId)?.account ?? void 0;
+      const singleFileScanner = this.scanner ?? this.newScanner();
+      try {
+        const page = await singleFileScanner.parseSingleFilePage(filePath, account, {
+          limit: Number.MAX_SAFE_INTEGER
+        });
+        if (page?.conversation) return page.conversation;
+      } catch (err) {
+        this.log.warn("detail.single_file_parse_failed", {
+          event: "detail.single_file_parse_failed",
+          conversationId: lookupId,
+          filePath,
+          err
+        });
+      }
+      return null;
+    }
     this.scanner = null;
     this.scannerReady = null;
     const freshScanner = await this.getScanner();
@@ -13294,15 +13780,7 @@ var StreamerServer = class {
   }
   async handleListSessions(url, res) {
     if (this.rejectIfWarmingUp(res)) return;
-    const now = Date.now();
-    if (!this.discoveryCache || now - this.discoveryCache.fetchedAt >= DISCOVERY_TTL_MS) {
-      try {
-        const discovered = await discoverClaudeProcesses();
-        this.sessionStore.setDiscovered(discovered);
-        this.discoveryCache = { entries: discovered, fetchedAt: now };
-      } catch {
-      }
-    }
+    await this.refreshDiscovery();
     const hasPaginationParams = url.searchParams.has("limit") || url.searchParams.has("cursor") || url.searchParams.has("sortBy") || url.searchParams.has("order") || url.searchParams.has("status");
     if (!hasPaginationParams) {
       json(
@@ -13331,6 +13809,36 @@ var StreamerServer = class {
       throw err;
     }
   }
+  /**
+   * Refresh the discovered-process list, sharing one in-flight enumeration
+   * across concurrent callers and honouring the 15s TTL cache.
+   */
+  async refreshDiscovery() {
+    const cached3 = this.discoveryCache;
+    if (cached3 && Date.now() - cached3.fetchedAt < DISCOVERY_TTL_MS) {
+      return cached3.entries;
+    }
+    if (this.discoveryInFlight) {
+      return this.discoveryInFlight;
+    }
+    let flight;
+    flight = (async () => {
+      try {
+        const discovered = await discoverClaudeProcesses();
+        this.sessionStore.setDiscovered(discovered);
+        this.discoveryCache = { entries: discovered, fetchedAt: Date.now() };
+        return discovered;
+      } catch {
+        return this.discoveryCache?.entries ?? [];
+      } finally {
+        if (this.discoveryInFlight === flight) {
+          this.discoveryInFlight = null;
+        }
+      }
+    })();
+    this.discoveryInFlight = flight;
+    return flight;
+  }
   async handleGetSession(sessionId, res) {
     if (this.rejectIfWarmingUp(res)) return;
     const base = this.sessionStore.get(sessionId, this.ptyAttachedIds());
@@ -13392,7 +13900,23 @@ var StreamerServer = class {
             code: "CONVERSATION_BUSY",
             detectedBy: outcome.detectedBy,
             lastActivityMs: outcome.lastActivityMs,
-            likelyOwner: outcome.likelyOwner
+            likelyOwner: outcome.likelyOwner,
+            // Additive capability hints (see docs/compatibility/tb-mobile.md).
+            // Older clients ignore them and keep deriving the same actions from
+            // `likelyOwner`; newer ones must honour these instead of guessing.
+            canForce: true,
+            canTakeOver: outcome.likelyOwner === "external",
+            canFork: false
+          });
+          return;
+        case "codex_session_active":
+          json(res, 409, codexSessionActiveBody(outcome));
+          return;
+        case "codex_start_failed":
+          json(res, 502, {
+            error: outcome.failureReason,
+            code: "SESSION_START_FAILED",
+            provider: CODEX_CLI_PROVIDER
           });
           return;
       }
@@ -13404,6 +13928,116 @@ var StreamerServer = class {
     this.broadcastOrUnicastSessionList(req);
     json(res, 201, outcome.response ?? outcome.session);
   }
+  /**
+   * `POST /api/sessions/:id/fork` — continue a conversation this streamer is
+   * not allowed to resume, without touching whoever owns it.
+   *
+   * Codex only (`codex fork <id>`): Claude Code has no equivalent, and there is
+   * no safe generic fallback — quietly resuming instead would attach to the
+   * exact writer the caller is trying to leave alone, which is the failure this
+   * endpoint exists to avoid.
+   *
+   * NOT idempotent by default: every accepted call starts another Codex
+   * process and another rollout. Clients that retry on timeout must send
+   * `idempotencyKey`, which replays the first outcome for 10 minutes (same
+   * store and semantics as `POST /:id/input`).
+   */
+  async handleFork(sessionId, req, res) {
+    const body = await readBody2(req);
+    let idempotencyKey;
+    try {
+      idempotencyKey = readIdempotencyKey(body);
+    } catch (err) {
+      json(res, 400, { error: err instanceof Error ? err.message : "Invalid idempotencyKey" });
+      return;
+    }
+    if (idempotencyKey) {
+      const replayed = this.idempotency.get(sessionId, idempotencyKey);
+      if (replayed) {
+        json(res, replayed.status, replayed.body);
+        return;
+      }
+    }
+    const target = await this.resolveConversationTarget(sessionId);
+    if (!target.ok) {
+      if (target.reason === "history_file_missing") {
+        json(res, 404, {
+          error: "Conversation history file is missing; it can no longer be forked",
+          code: "history_file_missing"
+        });
+      } else {
+        json(res, 400, { error: "Could not determine project path" });
+      }
+      return;
+    }
+    if (target.provider !== CODEX_CLI_PROVIDER) {
+      json(res, 501, {
+        error: "Forking is only supported for Codex sessions",
+        code: "UNSUPPORTED_PROVIDER",
+        provider: target.provider
+      });
+      return;
+    }
+    this.discoveryCache = null;
+    let session;
+    try {
+      session = await this.ptyManager.startFork({
+        provider: CODEX_CLI_PROVIDER,
+        // The rollout id, never the placeholder the client navigated to — it is
+        // the only id `codex fork` accepts.
+        forkFromId: target.historyId,
+        projectPath: target.projectPath,
+        projectName: body.projectName,
+        branch: body.branch
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Failed to fork session";
+      const statusCode = typeof err.statusCode === "number" ? err.statusCode : 500;
+      this.log.error(`[fork] failed to fork ${sessionId}: ${message}`, {
+        event: "session.fork_failed",
+        sessionId,
+        error: message
+      });
+      json(res, statusCode, { error: message, code: "FORK_FAILED" });
+      return;
+    }
+    session.forkedFromConversationId = target.historyId;
+    this.sessionStore.addManaged(session);
+    this.recordSessionSpawn(session);
+    const { outcome, session: settled } = await this.waitForStartupOutcome(
+      session.id,
+      resolveCodexStartupTimeoutMs()
+    );
+    if (outcome === "failed") {
+      const failed = settled ?? this.sessionStore.getManaged(session.id);
+      this.abandonFailedStart(session.id);
+      if (failed?.failureCode === CODEX_ACTIVE_WRITER_CODE) {
+        json(res, 409, codexSessionActiveBody({ detectedBy: [], lastActivityMs: null }));
+        return;
+      }
+      json(res, 502, {
+        error: failed?.failureReason ?? "Codex exited before the fork became ready",
+        code: "SESSION_START_FAILED",
+        provider: CODEX_CLI_PROVIDER
+      });
+      return;
+    }
+    this.watchForCodexRollout(session.id, target.projectPath);
+    const response = this.sessionStore.get(session.id, this.ptyAttachedIds());
+    const result = {
+      status: outcome === "ready" ? 201 : 202,
+      body: outcome === "ready" ? response ?? session : { id: session.id, status: "pending", forkedFromConversationId: target.historyId }
+    };
+    if (idempotencyKey) this.idempotency.set(sessionId, idempotencyKey, result);
+    this.log.info(`[fork] forked ${target.historyId} into ${session.id}`, {
+      event: "session.forked",
+      sessionId: session.id,
+      forkedFromConversationId: target.historyId,
+      outcome
+    });
+    this.broadcastOrUnicastSessionList(req);
+    json(res, result.status, result.body);
+  }
   /**
    * Resume a session, from an HTTP request or from the boot path.
    *
@@ -13424,43 +14058,38 @@ var StreamerServer = class {
         return { ok: true, alreadyRunning: true, session: null, response: resp };
       }
     }
-    let jsonlPath = this.findJsonlPath(sessionId);
-    let conv = await this.findConversationByUuid(sessionId);
-    let historyId = sessionId;
-    let registryProvider;
-    if (!jsonlPath && !conv) {
-      const row = this.managedSessionsRepo?.get(sessionId) ?? null;
-      const boundId = row ? resumeIdForRow(row) : null;
-      if (boundId != null && boundId !== sessionId) {
-        historyId = boundId;
-        registryProvider = row?.provider;
-        jsonlPath = this.findJsonlPath(boundId);
-        conv = await this.findConversationByUuid(boundId);
+    const target = await this.resolveConversationTarget(sessionId);
+    if (!target.ok) return target;
+    const { historyId, jsonlPath, historyPath, conv, projectPath, provider } = target;
+    if (provider === CODEX_CLI_PROVIDER && historyPath) {
+      const owner = await findRolloutOwner(historyPath);
+      if (owner) {
+        this.log.info(`[resume] codex rollout held by pid ${owner.pid}`, {
+          event: "session.codex_rollout_busy",
+          sessionId,
+          historyId,
+          ownerPid: owner.pid,
+          ownerCommand: owner.command
+        });
+        return {
+          ok: false,
+          reason: "codex_session_active",
+          detectedBy: ["file_handle"],
+          lastActivityMs: null,
+          ownerPid: owner.pid,
+          ownerSource: owner.source
+        };
       }
     }
-    const jsonlCwd = jsonlPath ? await this.readCwdFromJsonl(jsonlPath) : null;
-    const projectPath = jsonlCwd ?? conv?.projectPath;
-    if (!projectPath) {
-      if (!conv && !jsonlPath) return { ok: false, reason: "history_file_missing" };
-      return { ok: false, reason: "no_project_path" };
-    }
     let discovered = [];
-    const cached3 = this.discoveryCache;
-    if (cached3 && Date.now() - cached3.fetchedAt < DISCOVERY_TTL_MS) {
-      discovered = cached3.entries;
-    } else {
-      try {
-        discovered = await Promise.race([
-          discoverClaudeProcesses(),
-          new Promise(
-            (resolve2) => setTimeout(() => resolve2([]), RESUME_DISCOVERY_TIMEOUT_MS).unref?.()
-          )
-        ]);
-        if (discovered.length > 0) {
-          this.discoveryCache = { entries: discovered, fetchedAt: Date.now() };
-        }
-      } catch {
-      }
+    try {
+      discovered = await Promise.race([
+        this.refreshDiscovery(),
+        new Promise(
+          (resolve2) => setTimeout(() => resolve2([]), RESUME_DISCOVERY_TIMEOUT_MS).unref?.()
+        )
+      ]);
+    } catch {
     }
     const busy = conversationBusy({
       // The id another owner's argv would actually carry — for a placeholder
@@ -13484,10 +14113,6 @@ var StreamerServer = class {
     if (busy.busy) {
       this.contendedSessions.add(sessionId);
     }
-    const cachedConvMeta = this.cache?.getMetaById(historyId);
-    const provider = coerceProviderForRunner(
-      conv?.provider ?? cachedConvMeta?.provider ?? registryProvider
-    );
     this.discoveryCache = null;
     const session = await this.ptyManager.start(sessionId, {
       provider,
@@ -13503,11 +14128,136 @@ var StreamerServer = class {
     if (historyId !== sessionId) session.boundConversationId = historyId;
     this.sessionStore.addManaged(session);
     this.recordSessionSpawn(session);
+    if (provider === CODEX_CLI_PROVIDER) {
+      const { outcome, session: settled } = await this.waitForStartupOutcome(
+        sessionId,
+        resolveCodexStartupTimeoutMs()
+      );
+      if (outcome === "failed") {
+        const failed = settled ?? this.sessionStore.getManaged(sessionId);
+        this.abandonFailedStart(sessionId);
+        if (failed?.failureCode === CODEX_ACTIVE_WRITER_CODE) {
+          return {
+            ok: false,
+            reason: "codex_session_active",
+            detectedBy: [],
+            lastActivityMs: null
+          };
+        }
+        return {
+          ok: false,
+          reason: "codex_start_failed",
+          failureReason: failed?.failureReason ?? "Codex exited before becoming ready"
+        };
+      }
+    }
     void this.watchConversationFile(sessionId, historyId);
     this.enrichResumedSessionAsync(sessionId, projectPath, conv);
     const response = this.sessionStore.get(session.id, this.ptyAttachedIds());
     return { ok: true, alreadyRunning: false, session, response };
   }
+  /**
+   * Resolve a client-supplied session/conversation id into everything needed to
+   * launch against it: the id the PROVIDER filed the history under, that
+   * history's path, the project cwd, and which CLI owns it.
+   *
+   * Shared by resume and fork so the two can never disagree about identity —
+   * which for Codex is the whole difficulty: the id a client navigated to may
+   * be a local placeholder, and only the registry knows the rollout id behind
+   * it.
+   */
+  async resolveConversationTarget(sessionId) {
+    let jsonlPath = this.findJsonlPath(sessionId);
+    let conv = await this.findConversationByUuid(sessionId);
+    let historyId = sessionId;
+    let registryProvider;
+    if (!jsonlPath && !conv) {
+      const row = this.managedSessionsRepo?.get(sessionId) ?? null;
+      const boundId = row ? resumeIdForRow(row) : null;
+      if (boundId != null && boundId !== sessionId) {
+        historyId = boundId;
+        registryProvider = row?.provider;
+        jsonlPath = this.findJsonlPath(boundId);
+        conv = await this.findConversationByUuid(boundId);
+      }
+    }
+    const jsonlCwd = jsonlPath ? await this.readCwdFromJsonl(jsonlPath) : null;
+    const projectPath = jsonlCwd ?? conv?.projectPath;
+    if (!projectPath) {
+      if (!conv && !jsonlPath) return { ok: false, reason: "history_file_missing" };
+      return { ok: false, reason: "no_project_path" };
+    }
+    const cachedConvMeta = this.cache?.getMetaById(historyId);
+    const provider = coerceProviderForRunner(
+      conv?.provider ?? cachedConvMeta?.provider ?? registryProvider
+    );
+    return {
+      ok: true,
+      historyId,
+      jsonlPath,
+      // findJsonlPath() only knows Claude's `<uuid>.jsonl` layout under
+      // ~/.claude/projects; a Codex rollout lives in a date-nested directory
+      // under a name it chose, so its path only ever comes from the indexed
+      // conversation. Kept separate from `jsonlPath` deliberately: feeding it to
+      // conversationBusy() would newly arm the mtime heuristic for Codex, which
+      // is exactly the over-broad signal the report ruled out.
+      historyPath: jsonlPath ?? conv?.filePath ?? null,
+      conv,
+      projectPath,
+      provider
+    };
+  }
+  /**
+   * Block until a freshly spawned session reaches `waiting_input` (ready) or
+   * `idle` (failed), or until `timeoutMs` elapses with the process still alive.
+   *
+   * "timeout" is not an error: it is the pre-existing asynchronous contract —
+   * the session keeps booting and the caller answers with a pending shape.
+   */
+  waitForStartupOutcome(sessionId, timeoutMs) {
+    return new Promise((resolve2) => {
+      let timer = null;
+      const handler = (status, session) => {
+        if (status !== "waiting_input" && status !== "idle") return;
+        this.sessionStatusBus.off(`status:${sessionId}`, handler);
+        if (timer) clearTimeout(timer);
+        resolve2({
+          outcome: status === "waiting_input" ? "ready" : "failed",
+          session: session ?? null
+        });
+      };
+      this.sessionStatusBus.on(`status:${sessionId}`, handler);
+      timer = setTimeout(() => {
+        this.sessionStatusBus.off(`status:${sessionId}`, handler);
+        resolve2({ outcome: "timeout", session: null });
+      }, timeoutMs);
+      timer.unref?.();
+    });
+  }
+  /**
+   * Drop every trace of a session that never became usable, and hand back what
+   * it failed with.
+   *
+   * The runner has already torn itself down (failStartup / handleExit); what
+   * remains is server-side bookkeeping that would otherwise leave a dead
+   * session in the list, a registry row claiming a spawn, and a `selfPtyEndedAt`
+   * marker that would suppress the mtime collision signal on the NEXT resume —
+   * i.e. it would help hide the very owner we just collided with.
+   */
+  abandonFailedStart(sessionId) {
+    this.sessionStore.removeManaged(sessionId);
+    this.selfPtyEndedAt.delete(sessionId);
+    this.contendedSessions.delete(sessionId);
+    try {
+      this.managedSessionsRepo?.delete(sessionId);
+    } catch (err) {
+      this.log.warn("[registry] failed to drop a failed start", {
+        event: "registry.forget_failed",
+        sessionId,
+        err
+      });
+    }
+  }
   enrichResumedSessionAsync(sessionId, projectPath, conv) {
     try {
       if (!this.sessionStore.getManaged(sessionId)) return;
@@ -14034,19 +14784,7 @@ var StreamerServer = class {
       });
       this.sessionStore.addManaged(session);
       this.recordSessionSpawn(session);
-      const readyOrFailed = new Promise((resolve2) => {
-        const handler = (status) => {
-          if (status === "waiting_input" || status === "idle") {
-            this.sessionStatusBus.off(`status:${session.id}`, handler);
-            resolve2(status === "waiting_input" ? "ready" : "failed");
-          }
-        };
-        this.sessionStatusBus.on(`status:${session.id}`, handler);
-      });
-      const timeoutPromise = new Promise(
-        (resolve2) => setTimeout(() => resolve2("timeout"), START_READY_TIMEOUT_MS)
-      );
-      const outcome = await Promise.race([readyOrFailed, timeoutPromise]);
+      const { outcome } = await this.waitForStartupOutcome(session.id, START_READY_TIMEOUT_MS);
       const current = this.sessionStore.get(session.id, this.ptyAttachedIds());
       if (outcome === "ready" && current) {
         json(res, 200, { session: current });
@@ -14522,7 +15260,11 @@ function conversationToResumableSession(c) {
     status: "on_hold",
     // A cached conversation with no process behind it. Distinguishes "nobody is
     // running this" from an external session that IS live (ownership "external").
+    // Match the rehydrated branch of managedToResponse: same conceptual state
+    // ("resumable, no live process") must produce the same wire shape (#438).
     ownership: "historical",
+    lifecycle: "resumable",
+    lifecycleSource: "reconcile",
     ptyAttached: false,
     projectId: c.projectId ?? void 0,
     projectPath: c.projectPath ?? "",