@hellcoder/companion 0.111.2-preview.20260728013354.d1fdce0 → 0.111.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellcoder/companion",
-  "version": "0.111.2-preview.20260728013354.d1fdce0",
+  "version": "0.111.2",
   "type": "module",
   "description": "Web UI for launching and interacting with Claude Code agents — Moritz Edition (fork of the-companion)",
   "license": "MIT",

package/server/claude-adapter.test.ts

@@ -28,9 +28,15 @@ vi.mock("node:crypto", () => ({
 // Default 0 (childless) preserves the existing tests' behaviour; individual
 // tests override it.
 const mockCountDescendants = vi.hoisted(() => vi.fn(() => 0));
+// getDescendants is stubbed so the orphan-reaping tests can present a known tree
+// without spawning real children. Default empty, matching a childless CLI.
+const mockGetDescendants = vi.hoisted(() =>
+  vi.fn((): { pid: number; comm?: string; state?: string }[] => []),
+);
 vi.mock("./proc-diagnostics.js", async (importOriginal) => ({
   ...(await importOriginal<typeof import("./proc-diagnostics.js")>()),
   countDescendants: mockCountDescendants,
+  getDescendants: mockGetDescendants,
 }));
 
 // Settings are stubbed so the wedge-kill and silence-probe switches can be
@@ -1870,3 +1876,296 @@ describe("stdio silence probe", () => {
     expect(adapter.isConnected()).toBe(true);
   });
 });
+
+/**
+ * Turn-stall — the variant the silence probe structurally cannot catch.
+ *
+ * Reported from production on 0.111.1 (session aa37e7de): the turn died at
+ * 02:10:56 mid-`stream_event` while the CLI kept answering probes. Each reply
+ * refreshes `lastInboundAt` and pushes escalation out another interval — five
+ * probes were answered before the process went silent outright and the existing
+ * probe could fire, landing recovery at 02:29:33. An 18.6-minute hang, nearly
+ * all of it after the turn was already dead. Turn progress has to be tracked
+ * independently of transport liveness.
+ */
+describe("stdio turn-stall detection", () => {
+  let adapter: ClaudeAdapter;
+  let disconnectCb: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    adapter = new ClaudeAdapter("turn-stall-session");
+    disconnectCb = vi.fn();
+    adapter.onDisconnect(disconnectCb as unknown as () => void);
+    mockSettings.silenceProbeEnabled = true;
+  });
+
+  afterEach(() => {
+    mockSettings.silenceProbeEnabled = true;
+    vi.useRealTimers();
+  });
+
+  const controlResponse = (i: number) =>
+    JSON.stringify({
+      type: "control_response",
+      response: { subtype: "mcp_status", request_id: `r-${i}` },
+    }) + "\n";
+
+  const streamEvent = () =>
+    JSON.stringify({
+      type: "stream_event",
+      event: { type: "content_block_delta", index: 0, delta: { type: "thinking_delta", thinking: "" } },
+      session_id: "s",
+    }) + "\n";
+
+  const startTurn = () => adapter.send({ type: "user_message", content: "go" } as never);
+
+  it("fires when the CLI answers control requests but the turn is dead", async () => {
+    vi.useFakeTimers();
+    const { proc, pushStdout } = createMockProc();
+    adapter.attachStdio(proc);
+    startTurn();
+
+    // The turn streams briefly, then dies — exactly the aa37e7de shape.
+    pushStdout(streamEvent());
+    await vi.advanceTimersByTimeAsync(1_000);
+
+    // ...while the transport stays chatty. This is what pins the silence probe
+    // permanently disarmed, so anything that fires here is the turn-stall check.
+    for (let i = 0; i < 12; i++) {
+      await vi.advanceTimersByTimeAsync(30_000);
+      pushStdout(controlResponse(i));
+    }
+
+    expect(disconnectCb).toHaveBeenCalledTimes(1);
+    expect(adapter.isConnected()).toBe(false);
+  });
+
+  it("does NOT fire while a tool call is outstanding", async () => {
+    // The critical false-positive guard: a long `Bash` run legitimately emits
+    // nothing for many minutes and must never be torn down.
+    vi.useFakeTimers();
+    const { proc, pushStdout } = createMockProc();
+    adapter.attachStdio(proc);
+    startTurn();
+
+    pushStdout(
+      JSON.stringify({
+        type: "assistant",
+        message: {
+          role: "assistant",
+          model: "m",
+          content: [{ type: "tool_use", id: "tu-1", name: "Bash", input: {} }],
+        },
+        session_id: "s",
+      }) + "\n",
+    );
+
+    // Keep the transport answering so the (separate) silence probe stays out of
+    // it — this test is only about the turn-stall check.
+    for (let i = 0; i < 20; i++) {
+      await vi.advanceTimersByTimeAsync(30_000);
+      pushStdout(controlResponse(i));
+    }
+
+    expect(disconnectCb).not.toHaveBeenCalled();
+    expect(adapter.isConnected()).toBe(true);
+  });
+
+  it("resumes watching once the tool result comes back", async () => {
+    vi.useFakeTimers();
+    const { proc, pushStdout } = createMockProc();
+    adapter.attachStdio(proc);
+    startTurn();
+
+    pushStdout(
+      JSON.stringify({
+        type: "assistant",
+        message: {
+          role: "assistant",
+          model: "m",
+          content: [{ type: "tool_use", id: "tu-1", name: "Bash", input: {} }],
+        },
+        session_id: "s",
+      }) + "\n",
+    );
+    for (let i = 0; i < 14; i++) {
+      await vi.advanceTimersByTimeAsync(30_000);
+      pushStdout(controlResponse(i));
+    }
+    expect(disconnectCb).not.toHaveBeenCalled();
+
+    // Tool finished; the model should now be producing output again. It does
+    // not, so the exemption lifts and the stall is caught.
+    pushStdout(
+      JSON.stringify({
+        type: "user",
+        message: { role: "user", content: [{ type: "tool_result", tool_use_id: "tu-1", content: "ok" }] },
+        session_id: "s",
+      }) + "\n",
+    );
+    for (let i = 0; i < 12; i++) {
+      await vi.advanceTimersByTimeAsync(30_000);
+      pushStdout(controlResponse(100 + i));
+    }
+
+    expect(disconnectCb).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT fire on an idle session with no turn outstanding", async () => {
+    // A session simply waiting for the user emits nothing for hours.
+    vi.useFakeTimers();
+    const { proc, pushStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    for (let i = 0; i < 12; i++) {
+      await vi.advanceTimersByTimeAsync(30_000);
+      pushStdout(controlResponse(i));
+    }
+
+    expect(disconnectCb).not.toHaveBeenCalled();
+    expect(adapter.isConnected()).toBe(true);
+  });
+
+  it("does NOT fire while the turn keeps producing output", async () => {
+    vi.useFakeTimers();
+    const { proc, pushStdout } = createMockProc();
+    adapter.attachStdio(proc);
+    startTurn();
+
+    for (let i = 0; i < 12; i++) {
+      await vi.advanceTimersByTimeAsync(30_000);
+      pushStdout(streamEvent());
+    }
+
+    expect(disconnectCb).not.toHaveBeenCalled();
+    expect(adapter.isConnected()).toBe(true);
+  });
+
+  it("does NOT fire after the turn ends with a result", async () => {
+    vi.useFakeTimers();
+    const { proc, pushStdout } = createMockProc();
+    adapter.attachStdio(proc);
+    startTurn();
+
+    pushStdout(
+      JSON.stringify({ type: "result", subtype: "success", is_error: false, session_id: "s" }) + "\n",
+    );
+    for (let i = 0; i < 12; i++) {
+      await vi.advanceTimersByTimeAsync(30_000);
+      pushStdout(controlResponse(i));
+    }
+
+    expect(disconnectCb).not.toHaveBeenCalled();
+    expect(adapter.isConnected()).toBe(true);
+  });
+});
+
+/**
+ * Orphaned MCP descendants.
+ *
+ * Signals go to a pid, not a tree, so killing a wedged CLI leaves its 2-3 stdio
+ * MCP servers (and, for @playwright/mcp, a headless chromium) re-parented to
+ * init with no client that can ever reach them. Under kill/relaunch churn they
+ * accumulate: a production box was found holding 123 orphans across 11.9 GB of
+ * 23 GB total, starving the surviving CLIs until they stopped answering — which
+ * caused more kills, and more orphans.
+ */
+describe("orphaned descendant reaping", () => {
+  let adapter: ClaudeAdapter;
+  let killSpy: ReturnType<typeof vi.spyOn>;
+  let signalled: { pid: number; sig: unknown }[];
+
+  beforeEach(() => {
+    adapter = new ClaudeAdapter("orphan-session");
+    signalled = [];
+    // Simulate a live process table: signal 0 succeeds, real signals recorded.
+    killSpy = vi.spyOn(process, "kill").mockImplementation(((pid: number, sig?: unknown) => {
+      if (sig === 0) return true;
+      signalled.push({ pid, sig });
+      return true;
+    }) as unknown as typeof process.kill);
+  });
+
+  afterEach(() => {
+    killSpy.mockRestore();
+    mockGetDescendants.mockReturnValue([]);
+    vi.useRealTimers();
+  });
+
+  /** Drive the wedge path far enough to trigger killWithEscalation. */
+  const wedgeAndKill = async (endStdout: () => void) => {
+    endStdout();
+    await vi.advanceTimersByTimeAsync(11_000); // past the stdout-close grace
+  };
+
+  it("terminates descendants that outlived the CLI", async () => {
+    vi.useFakeTimers();
+    mockGetDescendants.mockReturnValue([{ pid: 99001 }, { pid: 99002 }]);
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    await wedgeAndKill(endStdout);
+
+    expect(proc.kill).toHaveBeenCalled();
+    expect(signalled.map((s) => s.pid).sort()).toEqual([99001, 99002]);
+    expect(signalled.every((s) => s.sig === "SIGTERM")).toBe(true);
+  });
+
+  it("escalates to SIGKILL for descendants that ignore SIGTERM", async () => {
+    // Chromium routinely ignores SIGTERM.
+    vi.useFakeTimers();
+    mockGetDescendants.mockReturnValue([{ pid: 99003 }]);
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    await wedgeAndKill(endStdout);
+    expect(signalled).toEqual([{ pid: 99003, sig: "SIGTERM" }]);
+
+    await vi.advanceTimersByTimeAsync(2100);
+    expect(signalled).toContainEqual({ pid: 99003, sig: "SIGKILL" });
+  });
+
+  it("does NOT signal a pid whose identity can no longer be confirmed", async () => {
+    // The recycled-pid guard. A snapshotted descendant carrying a `comm` is only
+    // signalled if /proc still reports that same comm — otherwise the pid has
+    // been reused by an unrelated process and must be left alone. Here /proc has
+    // no such entry at all, so it must be skipped.
+    vi.useFakeTimers();
+    mockGetDescendants.mockReturnValue([{ pid: 99004, comm: "npm exec" }]);
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    await wedgeAndKill(endStdout);
+
+    expect(proc.kill).toHaveBeenCalled();
+    expect(signalled).toEqual([]);
+  });
+
+  it("skips descendants that already exited with their parent", async () => {
+    vi.useFakeTimers();
+    killSpy.mockImplementation(((pid: number, sig?: unknown) => {
+      if (sig === 0) throw new Error("ESRCH"); // nothing alive
+      signalled.push({ pid, sig });
+      return true;
+    }) as unknown as typeof process.kill);
+    mockGetDescendants.mockReturnValue([{ pid: 99005 }, { pid: 99006 }]);
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    await wedgeAndKill(endStdout);
+
+    expect(signalled).toEqual([]);
+  });
+
+  it("is a no-op for a childless CLI", async () => {
+    vi.useFakeTimers();
+    mockGetDescendants.mockReturnValue([]);
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    await wedgeAndKill(endStdout);
+
+    expect(proc.kill).toHaveBeenCalled();
+    expect(signalled).toEqual([]);
+  });
+});

package/server/claude-adapter.ts

@@ -10,7 +10,7 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join, basename } from "node:path";
 import { log } from "./logger.js";
 import type { ServerWebSocket, Subprocess } from "bun";
@@ -46,7 +46,7 @@ import type {
 import type { SocketData } from "./ws-bridge-types.js";
 import type { PendingControlRequest } from "./ws-bridge-types.js";
 import type { RecorderManager } from "./recorder.js";
-import { captureProcState, hasLiveDescendants, countDescendants } from "./proc-diagnostics.js";
+import { captureProcState, hasLiveDescendants, countDescendants, getDescendants, type ProcDescendant } from "./proc-diagnostics.js";
 import { getSettings } from "./settings-manager.js";
 import { parseNDJSON, isDuplicateCLIMessage } from "./ws-bridge-cli-ingest.js";
 import type { CLIDedupState } from "./ws-bridge-cli-ingest.js";
@@ -129,9 +129,71 @@ const SILENCE_PROBE_AFTER_MS = Number(process.env.COMPANION_SILENCE_PROBE_AFTER_
 const SILENCE_PROBE_TIMEOUT_MS = Number(process.env.COMPANION_SILENCE_PROBE_TIMEOUT_MS) || 60_000;
 const SILENCE_CHECK_INTERVAL_MS = Number(process.env.COMPANION_SILENCE_CHECK_INTERVAL_MS) || 15_000;
 
+/**
+ * Turn-stall threshold.
+ *
+ * The silence probe above keys on *total* inbound silence, which recovers a
+ * dead turn far later than it needs to — and only if the CLI eventually stops
+ * answering control requests as well.
+ *
+ * Observed on 0.111.1 (session aa37e7de): turn output stopped at 02:10:56
+ * mid-`stream_event`, but the CLI kept replying to probes. Every reply refreshes
+ * `lastInboundAt`, so escalation is pushed out another full interval each time —
+ * five probes were answered before the process finally went silent outright and
+ * the probe could fire. Recovery landed at 02:29:33: an **18.6-minute** hang for
+ * the user, nearly all of it spent watching a turn that was already dead.
+ *
+ * The probe is doing its job; it is just asking the wrong question. Transport
+ * liveness and turn progress are independent, and a CLI that answers pings
+ * forever while its turn is dead would postpone escalation forever.
+ *
+ * So track turn progress separately from transport liveness. Only substantive
+ * turn frames (`stream_event`, `assistant`, `user`, `result`, `tool_progress`)
+ * count — control and keepalive traffic does not.
+ *
+ * False positives are the thing to fear (every previous timer in this file was
+ * too aggressive), so this only applies while a turn is actually outstanding,
+ * and never while a tool call is in flight: a long `Bash` run legitimately
+ * emits nothing for many minutes. The default is deliberately well beyond any
+ * plausible model think-time.
+ */
+const TURN_STALL_AFTER_MS = Number(process.env.COMPANION_TURN_STALL_AFTER_MS) || 300_000;
+
 /** How often to re-check the descendant count while waiting for teardown. */
 const TEARDOWN_POLL_MS = Number(process.env.COMPANION_TEARDOWN_POLL_MS) || 500;
 
+/**
+ * Does this frame type represent the turn actually making progress?
+ *
+ * `control_response` and `keep_alive` are excluded on purpose — they are the
+ * frames a stalled-but-responsive CLI keeps sending. `system` is excluded for
+ * the same reason it is excluded from `lastInboundWasResult`: it carries status
+ * and keepalive chatter, not turn work.
+ */
+function isTurnOutput(type: string): boolean {
+  return (
+    type === "stream_event" ||
+    type === "assistant" ||
+    type === "user" ||
+    type === "result" ||
+    type === "tool_progress"
+  );
+}
+
+/** Extract `tool_use` / `tool_result` ids from a message's content blocks. */
+function toolBlockIds(content: unknown): { uses: string[]; results: string[] } {
+  const uses: string[] = [];
+  const results: string[] = [];
+  if (!Array.isArray(content)) return { uses, results };
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    const b = block as { type?: string; id?: string; tool_use_id?: string };
+    if (b.type === "tool_use" && typeof b.id === "string") uses.push(b.id);
+    if (b.type === "tool_result" && typeof b.tool_use_id === "string") results.push(b.tool_use_id);
+  }
+  return { uses, results };
+}
+
 
 // --- Claude Code Adapter ------------------------------------------------------
 
@@ -173,6 +235,20 @@ export class ClaudeAdapter implements IBackendAdapter {
   /** When the outstanding silence probe was sent, or null if none is in flight. */
   private probeSentAt: number | null = null;
   private silenceTimer: ReturnType<typeof setInterval> | null = null;
+  /**
+   * Timestamp of the last substantive *turn* frame, for the turn-stall check.
+   * Deliberately narrower than `lastInboundAt`: control_response and keep_alive
+   * prove the transport is alive but say nothing about the turn making progress.
+   */
+  private lastTurnOutputAt = Date.now();
+  /** True while a user turn is outstanding — sent to the CLI, no `result` yet. */
+  private turnInFlight = false;
+  /**
+   * `tool_use` ids emitted by the model that have no matching `tool_result` yet.
+   * A long-running tool produces no turn output for minutes at a time and must
+   * never be mistaken for a stall.
+   */
+  private pendingToolUses = new Set<string>();
 
   // Callbacks registered by the bridge via on*() methods
   private browserMessageCb: ((msg: BrowserIncomingMessage) => void) | null = null;
@@ -488,6 +564,11 @@ export class ClaudeAdapter implements IBackendAdapter {
     this.stopSilenceProbe();
     this.lastInboundAt = Date.now();
     this.probeSentAt = null;
+    // A relaunched transport starts with a clean slate: the bridge replays the
+    // in-flight turn, which re-arms turnInFlight via handleOutgoingUserMessage.
+    this.lastTurnOutputAt = Date.now();
+    this.turnInFlight = false;
+    this.pendingToolUses.clear();
     this.silenceTimer = setInterval(() => this.checkSilence(), SILENCE_CHECK_INTERVAL_MS);
     // Never hold the process open for a diagnostic timer.
     (this.silenceTimer as unknown as { unref?: () => void }).unref?.();
@@ -501,12 +582,47 @@ export class ClaudeAdapter implements IBackendAdapter {
     this.probeSentAt = null;
   }
 
+  /**
+   * Maintain the outstanding-tool set so a long tool call is never mistaken for
+   * a stalled turn. The model announces work with `tool_use` blocks on an
+   * `assistant` frame; the CLI echoes the matching `tool_result` blocks back on
+   * a `user` frame when it finishes.
+   */
+  private trackToolCalls(msg: CLIMessage): void {
+    if (msg.type !== "assistant" && msg.type !== "user") return;
+    const content = (msg as { message?: { content?: unknown } }).message?.content;
+    const { uses, results } = toolBlockIds(content);
+    for (const id of uses) this.pendingToolUses.add(id);
+    for (const id of results) this.pendingToolUses.delete(id);
+  }
+
   private checkSilence(): void {
     if (this.transportKind !== "stdio" || !this.stdioConnected) return;
     if (getSettings().silenceProbeEnabled === false) return;
 
     const now = Date.now();
 
+    // Turn-stall: the CLI is answering control requests but its turn is dead,
+    // so `lastInboundAt` never ages and the probe below can never escalate.
+    // Only applies while a turn is outstanding and no tool is running.
+    if (
+      this.turnInFlight &&
+      this.pendingToolUses.size === 0 &&
+      now - this.lastTurnOutputAt >= TURN_STALL_AFTER_MS
+    ) {
+      log.warn("claude-adapter", "turn stalled while transport still responsive; treating transport as dead", {
+        sessionId: this.sessionId,
+        pid: this.stdioProc?.pid,
+        turnSilentForMs: now - this.lastTurnOutputAt,
+        transportSilentForMs: now - this.lastInboundAt,
+        proc: captureProcState(this.stdioProc?.pid),
+      });
+      this.stopSilenceProbe();
+      // Same handoff as the silence probe: relaunch replays the in-flight turn.
+      this.notifyStdioDisconnect();
+      return;
+    }
+
     // An unanswered probe is the actual failure signal: a healthy CLI replies
     // to control requests promptly even while working.
     if (this.probeSentAt !== null) {
@@ -609,19 +725,35 @@ export class ClaudeAdapter implements IBackendAdapter {
    * and satisfying `handleAutoRelaunch`'s PID-liveness guard, which blocks
    * recovery indefinitely — the exact failure the kill was meant to prevent.
    * Never throws; the process may exit between any two steps here.
+   *
+   * Killing the CLI alone leaks its MCP servers. Signals go to the pid, not the
+   * tree, so each CLI's 2-3 stdio MCP children (plus, for @playwright/mcp, a
+   * headless chromium) are re-parented to init and live on with no client that
+   * could ever reach them. Under kill/relaunch churn they accumulate: a
+   * production box was found holding 123 such orphans across 11.9 GB, on 23 GB
+   * total — which starves the surviving CLIs until they stop answering, causing
+   * more kills and more orphans.
    */
   private async killWithEscalation(proc: Subprocess): Promise<void> {
+    // Snapshot the tree *before* the parent dies. Once it exits its children are
+    // re-parented to init and the link back to this session is gone for good.
+    const spawned = getDescendants(proc.pid);
+
     try {
       proc.kill();
     } catch {
-      return; // Already gone.
+      this.reapOrphans(spawned); // Parent already gone; children may not be.
+      return;
     }
 
     const exited = await Promise.race([
       proc.exited.then(() => true),
       new Promise<boolean>((resolve) => setTimeout(() => resolve(false), SIGKILL_ESCALATION_MS)),
     ]);
-    if (exited || proc.exitCode !== null) return;
+    if (exited || proc.exitCode !== null) {
+      this.reapOrphans(spawned);
+      return;
+    }
 
     log.warn("claude-adapter", "process ignored SIGTERM; escalating to SIGKILL", {
       sessionId: this.sessionId,
@@ -633,6 +765,60 @@ export class ClaudeAdapter implements IBackendAdapter {
     } catch {
       // Exited between the check and the escalation.
     }
+    this.reapOrphans(spawned);
+  }
+
+  /**
+   * Terminate descendants that outlived the CLI they belonged to.
+   *
+   * Only pids snapshotted as descendants of *this* session's process are
+   * touched. A pid could in principle be recycled between the snapshot and the
+   * signal, so each one is re-checked against the `comm` recorded at snapshot
+   * time and skipped if it no longer matches — a recycled pid is a different
+   * process and must not be killed.
+   */
+  private reapOrphans(spawned: ProcDescendant[]): void {
+    if (spawned.length === 0) return;
+
+    const stillAlive = spawned.filter((d) => {
+      try {
+        process.kill(d.pid, 0); // Signal 0 = liveness check only.
+      } catch {
+        return false; // Already reaped with its parent.
+      }
+      if (!d.comm) return true;
+      try {
+        return readFileSync(`/proc/${d.pid}/comm`, "utf8").trim() === d.comm;
+      } catch {
+        return false;
+      }
+    });
+    if (stillAlive.length === 0) return;
+
+    for (const d of stillAlive) {
+      try {
+        process.kill(d.pid, "SIGTERM");
+      } catch {
+        // Exited in the meantime.
+      }
+    }
+    log.info("claude-adapter", "reaped orphaned CLI descendants", {
+      sessionId: this.sessionId,
+      count: stillAlive.length,
+      comms: [...new Set(stillAlive.map((d) => d.comm).filter(Boolean))].slice(0, 5),
+    });
+
+    // Chromium (and npm wrappers mid-install) routinely ignore SIGTERM.
+    setTimeout(() => {
+      for (const d of stillAlive) {
+        try {
+          process.kill(d.pid, 0);
+          process.kill(d.pid, "SIGKILL");
+        } catch {
+          // Gone, which is the desired outcome.
+        }
+      }
+    }, SIGKILL_ESCALATION_MS).unref?.();
   }
 
   /**
@@ -878,7 +1064,16 @@ export class ClaudeAdapter implements IBackendAdapter {
     });
     // Propagate delivery success so the bridge re-queues an undelivered prompt
     // (write to a dying stdio pipe) rather than treating send() as delivery.
-    return this.sendToBackend(ndjson);
+    const delivered = this.sendToBackend(ndjson);
+    if (delivered) {
+      // A turn is now outstanding: arm the turn-stall check. Only armed on
+      // actual delivery, so an undelivered prompt can't start the clock against
+      // a CLI that was never asked to do anything.
+      this.turnInFlight = true;
+      this.lastTurnOutputAt = Date.now();
+      this.pendingToolUses.clear();
+    }
+    return delivered;
   }
 
   /**
@@ -974,6 +1169,9 @@ export class ClaudeAdapter implements IBackendAdapter {
       request: { subtype: "interrupt" },
     });
     this.sendToBackend(ndjson);
+    // The user abandoned the turn, so stop holding it against the CLI.
+    this.turnInFlight = false;
+    this.pendingToolUses.clear();
     return true;
   }
 
@@ -1061,6 +1259,18 @@ export class ClaudeAdapter implements IBackendAdapter {
     this.lastInboundAt = Date.now();
     this.probeSentAt = null;
 
+    // Turn progress is tracked separately: a CLI can keep answering control
+    // requests long after its turn has died (see TURN_STALL_AFTER_MS), so only
+    // frames that represent actual turn work count here.
+    if (isTurnOutput(msg.type)) {
+      this.lastTurnOutputAt = Date.now();
+    }
+    this.trackToolCalls(msg);
+    if (msg.type === "result") {
+      this.turnInFlight = false;
+      this.pendingToolUses.clear();
+    }
+
     // Track activity for idle detection (skip keepalives -- they don't indicate real work)
     if (msg.type !== "keep_alive") {
       this.onActivityUpdate?.();

package/server/index.ts

@@ -18,6 +18,7 @@ import { WsBridge } from "./ws-bridge.js";
 import { SessionStore } from "./session-store.js";
 import { WorktreeTracker } from "./worktree-tracker.js";
 import { containerManager } from "./container-manager.js";
+import { startOrphanSweeper } from "./orphan-sweeper.js";
 import { join } from "node:path";
 import { COMPANION_HOME } from "./paths.js";
 import { TerminalManager } from "./terminal-manager.js";
@@ -102,6 +103,14 @@ containerManager.restoreState(CONTAINER_STATE_PATH);
 // ── Session orchestrator — centralizes lifecycle event wiring ────────────────
 orchestrator.initialize();
 
+// ── Reap orphaned MCP servers: once now, then periodically ───────────────────
+// Per-kill reaping cannot cover kills this process did not perform. A previous
+// run that crashed or was OOM-killed orphans every CLI it owned along with those
+// CLIs' MCP children, and a CLI the kernel OOM-kills mid-run does the same. With
+// nothing holding the reference needed to clean them up they survive for the
+// life of the host, holding memory nobody can reclaim.
+startOrphanSweeper();
+
 console.log(`[server] Session persistence: ${sessionStore.directory}`);
 if (recorder.isGloballyEnabled()) {
   console.log(`[server] Recording enabled (dir: ${recorder.getRecordingsDir()}, max: ${recorder.getMaxLines()} lines)`);

package/server/orphan-sweeper.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const mockFindOrphans = vi.hoisted(() =>
+  vi.fn((): { pid: number; comm?: string }[] => []),
+);
+vi.mock("./proc-diagnostics.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./proc-diagnostics.js")>()),
+  findOrphanedMcpProcesses: mockFindOrphans,
+}));
+
+import {
+  sweepOrphanedMcpProcesses,
+  startOrphanSweeper,
+  stopOrphanSweeper,
+} from "./orphan-sweeper.js";
+
+/**
+ * Orphans left behind when companion itself dies. Per-kill reaping cannot cover
+ * this: the CLIs and their MCP children are all orphaned at once and nothing
+ * remains holding the reference needed to clean them up.
+ */
+describe("sweepOrphanedMcpProcesses", () => {
+  let killSpy: ReturnType<typeof vi.spyOn>;
+  let signalled: { pid: number; sig: unknown }[];
+
+  beforeEach(() => {
+    signalled = [];
+    killSpy = vi.spyOn(process, "kill").mockImplementation(((pid: number, sig?: unknown) => {
+      if (sig === 0) return true;
+      signalled.push({ pid, sig });
+      return true;
+    }) as unknown as typeof process.kill);
+  });
+
+  afterEach(() => {
+    killSpy.mockRestore();
+    mockFindOrphans.mockReturnValue([]);
+    vi.useRealTimers();
+  });
+
+  it("terminates every orphaned MCP server it finds", () => {
+    mockFindOrphans.mockReturnValue([
+      { pid: 501, comm: "npm exec" },
+      { pid: 502, comm: "chrome" },
+    ]);
+
+    expect(sweepOrphanedMcpProcesses()).toBe(2);
+    expect(signalled).toEqual([
+      { pid: 501, sig: "SIGTERM" },
+      { pid: 502, sig: "SIGTERM" },
+    ]);
+  });
+
+  it("escalates to SIGKILL for processes that ignore SIGTERM", () => {
+    vi.useFakeTimers();
+    mockFindOrphans.mockReturnValue([{ pid: 503 }]);
+
+    sweepOrphanedMcpProcesses();
+    expect(signalled).toEqual([{ pid: 503, sig: "SIGTERM" }]);
+
+    vi.advanceTimersByTime(5100);
+    expect(signalled).toContainEqual({ pid: 503, sig: "SIGKILL" });
+  });
+
+  it("is a no-op when nothing is orphaned", () => {
+    mockFindOrphans.mockReturnValue([]);
+
+    expect(sweepOrphanedMcpProcesses()).toBe(0);
+    expect(signalled).toEqual([]);
+  });
+
+  it("never throws when the scan fails, so startup is not blocked", () => {
+    mockFindOrphans.mockImplementation(() => {
+      throw new Error("/proc unreadable");
+    });
+
+    expect(() => sweepOrphanedMcpProcesses()).not.toThrow();
+    expect(sweepOrphanedMcpProcesses()).toBe(0);
+  });
+
+  it("tolerates a process that exits between the scan and the signal", () => {
+    killSpy.mockImplementation(((pid: number, sig?: unknown) => {
+      if (sig === "SIGTERM" && pid === 504) throw new Error("ESRCH");
+      if (sig === 0) return true;
+      signalled.push({ pid, sig });
+      return true;
+    }) as unknown as typeof process.kill);
+    mockFindOrphans.mockReturnValue([{ pid: 504 }, { pid: 505 }]);
+
+    expect(sweepOrphanedMcpProcesses()).toBe(1);
+    expect(signalled).toEqual([{ pid: 505, sig: "SIGTERM" }]);
+  });
+});
+
+/**
+ * The periodic schedule. A startup-only sweep leaves a gap: a CLI the kernel
+ * OOM-kills mid-run orphans its MCP children with nobody to reap them, and they
+ * then accumulate for the rest of the server's uptime — which is how a
+ * production box reached 123 orphans across 11.9 GB inside a single run.
+ */
+describe("startOrphanSweeper", () => {
+  let killSpy: ReturnType<typeof vi.spyOn>;
+  let signalled: number[];
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    signalled = [];
+    killSpy = vi.spyOn(process, "kill").mockImplementation(((pid: number, sig?: unknown) => {
+      if (sig === 0) return true;
+      if (sig === "SIGTERM") signalled.push(pid);
+      return true;
+    }) as unknown as typeof process.kill);
+  });
+
+  afterEach(() => {
+    stopOrphanSweeper();
+    killSpy.mockRestore();
+    mockFindOrphans.mockReturnValue([]);
+    vi.useRealTimers();
+  });
+
+  it("sweeps immediately and then on each interval", () => {
+    mockFindOrphans.mockReturnValue([{ pid: 601 }]);
+
+    startOrphanSweeper();
+    expect(signalled).toEqual([601]); // startup sweep
+
+    vi.advanceTimersByTime(600_000);
+    expect(signalled).toEqual([601, 601]); // first periodic run
+
+    vi.advanceTimersByTime(600_000);
+    expect(signalled).toEqual([601, 601, 601]);
+  });
+
+  it("stops sweeping once cancelled", () => {
+    mockFindOrphans.mockReturnValue([{ pid: 602 }]);
+
+    const stop = startOrphanSweeper();
+    expect(signalled).toEqual([602]);
+
+    stop();
+    vi.advanceTimersByTime(1_800_000);
+    expect(signalled).toEqual([602]); // no further sweeps
+  });
+
+  it("replaces the schedule rather than stacking a second one", () => {
+    mockFindOrphans.mockReturnValue([{ pid: 603 }]);
+
+    startOrphanSweeper();
+    startOrphanSweeper();
+    signalled.length = 0; // ignore the two startup sweeps
+
+    vi.advanceTimersByTime(600_000);
+    expect(signalled).toEqual([603]); // one interval fired, not two
+  });
+});

package/server/orphan-sweeper.ts

@@ -0,0 +1,113 @@
+/**
+ * Startup sweep for MCP servers orphaned by a previous companion run.
+ *
+ * Each `claude --print` CLI spawns 2-3 stdio MCP children (e.g. @shopify/dev-mcp,
+ * @playwright/mcp plus its headless chromium). Signals go to a pid rather than a
+ * tree, so when a CLI dies its children are re-parented to init. `ClaudeAdapter`
+ * now reaps them on its own kill path, but that only covers kills companion
+ * performs while it is running. If companion itself is restarted, crashes or is
+ * OOM-killed, every CLI it owned is orphaned together with those children and
+ * nothing remains that could clean them up.
+ *
+ * Left alone they persist for the life of the host. A production box was found
+ * holding 123 such processes across 11.9 GB of 23 GB total, which starved the
+ * live CLIs of CPU and memory until they stopped answering — producing exactly
+ * the stall and wedge symptoms that cause more kills, and so more orphans.
+ *
+ * Running this once at startup breaks that cycle. An MCP stdio server whose
+ * parent is not a `claude` process has no client and can never acquire one, so
+ * terminating it is unambiguously safe.
+ */
+import { findOrphanedMcpProcesses } from "./proc-diagnostics.js";
+import { log } from "./logger.js";
+
+/** Grace before escalating; chromium and npm wrappers often ignore SIGTERM. */
+const SWEEP_SIGKILL_AFTER_MS = Number(process.env.COMPANION_SWEEP_SIGKILL_AFTER_MS) || 5000;
+
+/**
+ * How often to re-run the sweep while the server is up.
+ *
+ * A startup sweep alone leaves a gap: a CLI killed by something other than this
+ * process — the kernel OOM killer is the common one on a loaded host — orphans
+ * its MCP children with nobody to reap them, and they then accumulate for the
+ * rest of the server's uptime. That is exactly how a production box reached 123
+ * orphans across 11.9 GB inside a single run. The scan is a cheap /proc walk, so
+ * running it periodically costs nothing measurable.
+ */
+const SWEEP_INTERVAL_MS = Number(process.env.COMPANION_SWEEP_INTERVAL_MS) || 600_000;
+
+/**
+ * Terminate every MCP server process with no live CLI parent.
+ *
+ * Never throws: a failure to tidy up must not prevent the server from starting.
+ * Returns the number of processes signalled, for logging and tests.
+ */
+export function sweepOrphanedMcpProcesses(): number {
+  let orphans: ReturnType<typeof findOrphanedMcpProcesses>;
+  try {
+    orphans = findOrphanedMcpProcesses();
+  } catch (err) {
+    log.warn("orphan-sweeper", "scan failed; skipping sweep", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return 0;
+  }
+
+  if (orphans.length === 0) return 0;
+
+  const signalled: number[] = [];
+  for (const o of orphans) {
+    try {
+      process.kill(o.pid, "SIGTERM");
+      signalled.push(o.pid);
+    } catch {
+      // Exited between the scan and the signal.
+    }
+  }
+
+  if (signalled.length === 0) return 0;
+
+  log.info("orphan-sweeper", "reaped MCP servers orphaned by a previous run", {
+    count: signalled.length,
+    comms: [...new Set(orphans.map((o) => o.comm).filter(Boolean))].slice(0, 5),
+  });
+
+  setTimeout(() => {
+    for (const pid of signalled) {
+      try {
+        process.kill(pid, 0);
+        process.kill(pid, "SIGKILL");
+      } catch {
+        // Gone, which is the desired outcome.
+      }
+    }
+  }, SWEEP_SIGKILL_AFTER_MS).unref?.();
+
+  return signalled.length;
+}
+
+let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Sweep at startup, then periodically for as long as the server runs.
+ *
+ * Returns a stop function, so tests and shutdown paths can clear the timer.
+ * Calling this twice replaces the existing schedule rather than stacking a
+ * second one.
+ */
+export function startOrphanSweeper(): () => void {
+  stopOrphanSweeper();
+  sweepOrphanedMcpProcesses();
+  sweepTimer = setInterval(() => sweepOrphanedMcpProcesses(), SWEEP_INTERVAL_MS);
+  // Housekeeping must never hold the process open.
+  (sweepTimer as unknown as { unref?: () => void }).unref?.();
+  return stopOrphanSweeper;
+}
+
+/** Cancel the periodic sweep, if one is scheduled. */
+export function stopOrphanSweeper(): void {
+  if (sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+}

package/server/proc-diagnostics.test.ts

@@ -6,6 +6,7 @@ import {
   getDescendants,
   hasLiveDescendants,
   countDescendants,
+  findOrphanedMcpProcesses,
 } from "./proc-diagnostics.js";
 
 /**
@@ -208,3 +209,81 @@ describe("getDescendants / hasLiveDescendants", () => {
     await new Promise((r) => child.on("exit", r));
   });
 });
+
+/**
+ * Orphaned-MCP detection. This drives a sweeper that SIGTERMs whatever it
+ * returns, so both directions matter: missing an orphan leaks memory (a
+ * production host reached 123 orphans across 11.9 GB), but a false positive
+ * kills a live MCP server out from under a working session.
+ */
+describe("findOrphanedMcpProcesses", () => {
+  const spawned: ReturnType<typeof spawn>[] = [];
+
+  afterEach(async () => {
+    for (const p of spawned.splice(0)) {
+      try {
+        p.kill("SIGKILL");
+        await new Promise((r) => p.on("exit", r));
+      } catch {
+        // Already gone.
+      }
+    }
+  });
+
+  it("returns empty on platforms without /proc", () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    expect(findOrphanedMcpProcesses()).toEqual([]);
+  });
+
+  it.runIf(isLinux)("never throws and returns a well-formed list", () => {
+    // Runs against the real /proc of whatever host this is, so it must tolerate
+    // processes exiting mid-scan — the scan races every other process on the box.
+    const orphans = findOrphanedMcpProcesses();
+    expect(Array.isArray(orphans)).toBe(true);
+    for (const o of orphans) {
+      expect(typeof o.pid).toBe("number");
+      expect(o.pid).toBeGreaterThan(0);
+    }
+  });
+
+  it.runIf(isLinux)("detects a process whose cmdline marks it an MCP server with no CLI parent", async () => {
+    // `exec -a` sets argv[0], reproducing the cmdline shape of a CLI-spawned
+    // stdio MCP server. Its parent here is the test runner, not a `claude`
+    // process, so it is exactly the orphan the sweeper targets.
+    const child = spawn("/bin/bash", [
+      "-c",
+      "exec -a 'npm exec @modelcontextprotocol/server-test' sleep 30",
+    ], { stdio: "ignore" });
+    spawned.push(child);
+    await new Promise((r) => setTimeout(r, 300));
+
+    const orphans = findOrphanedMcpProcesses();
+    expect(orphans.some((o) => o.pid === child.pid)).toBe(true);
+  });
+
+  it.runIf(isLinux)("ignores processes with no MCP marker in their cmdline", async () => {
+    // The false-positive guard: an ordinary child must never be swept, or the
+    // sweeper would kill unrelated processes on the host.
+    const child = spawn("sleep", ["30"], { stdio: "ignore" });
+    spawned.push(child);
+    await new Promise((r) => setTimeout(r, 300));
+
+    const orphans = findOrphanedMcpProcesses();
+    expect(orphans.some((o) => o.pid === child.pid)).toBe(false);
+  });
+
+  it.runIf(isLinux)("labels findings with comm where readable", async () => {
+    const child = spawn("/bin/bash", [
+      "-c",
+      "exec -a 'mcp-server-label-test' sleep 30",
+    ], { stdio: "ignore" });
+    spawned.push(child);
+    await new Promise((r) => setTimeout(r, 300));
+
+    const found = findOrphanedMcpProcesses().find((o) => o.pid === child.pid);
+    expect(found).toBeDefined();
+    // comm is the executable name (truncated to 15 chars by the kernel), not
+    // argv[0] — it is a label for the log line, not the match key.
+    expect(typeof found?.comm).toBe("string");
+  });
+});

package/server/proc-diagnostics.ts

@@ -162,6 +162,73 @@ export function isProcAvailable(): boolean {
   return process.platform === "linux";
 }
 
+/** Command-line markers identifying a CLI-spawned stdio MCP server. */
+const MCP_CMDLINE_MARKERS = ["dev-mcp", "playwright/mcp", "mcp-server", "@modelcontextprotocol"];
+
+/**
+ * Find MCP server processes that no longer belong to a live CLI.
+ *
+ * Per-kill reaping (see `ClaudeAdapter.reapOrphans`) handles the steady state,
+ * but it cannot clean up after the server itself dies: if companion is killed,
+ * restarted or OOM-killed, every CLI it owned is orphaned along with that CLI's
+ * MCP children, and nothing is left holding the reference needed to reap them.
+ * They then sit there for the lifetime of the host, holding memory no one can
+ * reclaim — 123 such processes across 11.9 GB were found on a 23 GB production
+ * box.
+ *
+ * An MCP stdio server whose parent is not a `claude` process has no client and
+ * can never acquire one, which makes it unambiguously safe to terminate.
+ */
+export function findOrphanedMcpProcesses(): ProcDescendant[] {
+  if (!isProcAvailable()) return [];
+
+  const orphans: ProcDescendant[] = [];
+  let pids: string[];
+  try {
+    pids = readdirSync("/proc").filter((n) => /^\d+$/.test(n));
+  } catch {
+    return [];
+  }
+
+  for (const entry of pids) {
+    const pid = Number(entry);
+    if (pid === process.pid) continue;
+
+    let cmdline: string;
+    try {
+      cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8").replace(/\0/g, " ");
+    } catch {
+      continue; // Exited mid-scan.
+    }
+    if (!MCP_CMDLINE_MARKERS.some((m) => cmdline.includes(m))) continue;
+
+    // Parent still a live claude process → it has a client; leave it alone.
+    let ppid: number | undefined;
+    try {
+      ppid = Number(readFileSync(`/proc/${pid}/stat`, "utf8").split(" ")[3]);
+    } catch {
+      continue;
+    }
+    if (ppid && ppid !== 1) {
+      try {
+        if (readFileSync(`/proc/${ppid}/cmdline`, "utf8").includes("claude")) continue;
+      } catch {
+        // Parent vanished between reads — treat as orphaned.
+      }
+    }
+
+    const orphan: ProcDescendant = { pid };
+    try {
+      orphan.comm = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
+    } catch {
+      // Best-effort label only.
+    }
+    orphans.push(orphan);
+  }
+
+  return orphans;
+}
+
 /**
  * Capture kernel state for a pid. Returns `{ error }` rather than throwing when
  * the platform has no /proc or the process has already exited (the common race:

package/server/ws-bridge-codex.ts

@@ -8,6 +8,7 @@ import type { Session } from "./ws-bridge-types.js";
 import { appendHistory } from "./ws-bridge-persist.js";
 import { validatePermission } from "./ai-validator.js";
 import { getEffectiveAiValidation } from "./ai-validation-settings.js";
+import { log } from "./logger.js";
 import { companionBus } from "./event-bus.js";
 
 /**
@@ -176,7 +177,15 @@ export function attachCodexAdapterHandlers(
     session.pendingPermissions.clear();
     session.backendAdapter = null;
     deps.persistSession(session);
-    console.log(`[ws-bridge] Codex adapter disconnected for session ${sessionId}`);
+    // Mirrors WsBridge.broadcastCliDisconnected so every path that raises the
+    // "CLI disconnected / Reconnect" banner is greppable under one message.
+    log.warn("ws-bridge", "UI: CLI disconnected banner shown", {
+      sessionId,
+      reason: "codex_adapter_disconnected",
+      backendType: session.backendType,
+      phase: session.stateMachine.phase,
+      browsers: session.browserSockets.size,
+    });
     deps.broadcastToBrowsers(session, { type: "cli_disconnected" });
 
     // Auto-relaunch if browsers are still connected (don't leave users staring

package/server/ws-bridge.test.ts

@@ -1963,6 +1963,39 @@ describe("CLI message routing", () => {
     expect(session.inFlightUserTurn).toBeTruthy();
   });
 
+  /**
+   * The "CLI disconnected / Reconnect" banner is the single most-reported
+   * symptom, so every path that raises it must leave a greppable log line.
+   * Previously the four broadcast sites logged inconsistently — two via
+   * console.log, one describing the cause rather than the broadcast, one
+   * silent — which made post-hoc log analysis miss occurrences entirely.
+   */
+  it("logs a greppable line whenever the CLI-disconnected banner is broadcast", async () => {
+    vi.useFakeTimers();
+    try {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const cli = makeCliSocket("s1");
+      bridge.handleCLIOpen(cli, "s1");
+      await bridge.handleCLIMessage(cli, makeInitMsg());
+
+      const browser = makeBrowserSocket("s1");
+      bridge.handleBrowserOpen(browser, "s1");
+
+      bridge.handleCLIClose(cli);
+      // Past the disconnect debounce, the banner goes out.
+      await vi.advanceTimersByTimeAsync(20_000);
+
+      const calls = warnSpy.mock.calls.map(([a]) => String(a));
+      const banner = calls.find((l) => l.includes("UI: CLI disconnected banner shown"));
+      expect(banner).toBeDefined();
+      // The reason is what makes a log searchable for *why*, not just *that*.
+      expect(banner).toContain("cli_disconnect_confirmed");
+      expect(banner).toContain("s1");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("tool_progress: broadcasts", async () => {
     const msg = JSON.stringify({
       type: "tool_progress",

package/server/ws-bridge.ts

@@ -687,7 +687,7 @@ export class WsBridge {
         session.pendingPermissions.clear();
         session.stateMachine.transition("terminated", "disconnect_confirmed");
         this.persistSession(session);
-        this.broadcastToBrowsers(session, { type: "cli_disconnected" });
+        this.broadcastCliDisconnected(session, "codex_disconnect_confirmed");
 
         // Request auto-relaunch regardless of browser state — proactive
         // keepalive in the orchestrator ensures headless sessions stay alive.
@@ -931,7 +931,10 @@ export class WsBridge {
         interruptedMidTurn,
       });
       session.stateMachine.transition("terminated", "disconnect_confirmed");
-      this.broadcastToBrowsers(session, { type: "cli_disconnected" });
+      this.broadcastCliDisconnected(session, "cli_disconnect_confirmed", {
+        phaseAtClose,
+        interruptedMidTurn,
+      });
       for (const [reqId] of session.pendingPermissions) {
         this.broadcastToBrowsers(session, { type: "permission_cancelled", request_id: reqId });
       }
@@ -990,8 +993,17 @@ export class WsBridge {
     if (!backendConnected && !this.disconnectTimers.has(sessionId)) {
       // Only signal disconnection if we're not within the debounce window
       // (CLI may be mid-reconnect — avoid UI flap and spurious relaunch)
+      // Same banner, different trigger: a browser attached to a session whose
+      // backend is already gone. Logged in the same shape so both paths surface
+      // under one grep.
+      log.warn("ws-bridge", "UI: CLI disconnected banner shown", {
+        sessionId,
+        reason: "backend_dead_on_browser_open",
+        backendType: session.backendType,
+        phase: session.stateMachine.phase,
+        browsers: session.browserSockets.size,
+      });
       this.sendToBrowser(ws, { type: "cli_disconnected" });
-      console.log(`[ws-bridge] Browser connected but backend is dead for session ${sessionId}, requesting relaunch`);
       companionBus.emit("session:relaunch-needed", { sessionId });
     }
   }
@@ -1304,6 +1316,34 @@ export class WsBridge {
     this.broadcastToBrowsers(session, { type: "session_name_update", name });
   }
 
+  /**
+   * Broadcast `cli_disconnected` and record it, in that order, from one place.
+   *
+   * `cli_disconnected` is what puts the "CLI disconnected / Reconnect" banner in
+   * front of the user, so every occurrence must be greppable afterwards — this
+   * is the single most reported symptom and was previously logged inconsistently
+   * across the four call sites (two `console.log`, one `log.warn` describing the
+   * cause rather than the broadcast, one silent).
+   *
+   * Emitting it here means the log line and the banner cannot drift apart: if
+   * the user saw the banner, this line exists.
+   */
+  private broadcastCliDisconnected(
+    session: Session,
+    reason: string,
+    detail: Record<string, unknown> = {},
+  ) {
+    log.warn("ws-bridge", "UI: CLI disconnected banner shown", {
+      sessionId: session.id,
+      reason,
+      backendType: session.backendType,
+      phase: session.stateMachine.phase,
+      browsers: session.browserSockets.size,
+      ...detail,
+    });
+    this.broadcastToBrowsers(session, { type: "cli_disconnected" });
+  }
+
   private broadcastToBrowsers(session: Session, msg: BrowserIncomingMessage) {
     broadcastToBrowsersFn(session, msg, {
       eventBufferLimit: EVENT_BUFFER_LIMIT,