@hellcoder/companion 0.111.2 → 0.111.3

package/package.json

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

package/server/auto-namer.test.ts

@@ -42,6 +42,7 @@ beforeEach(() => {
     updateChannel: "stable",
     dockerAutoUpdate: false,
     proactiveKeepaliveEnabled: true,
+    keepaliveDetachedSessions: false,
     wedgeKillEnabled: true,
     silenceProbeEnabled: true,
     updatedAt: 0,
@@ -92,6 +93,7 @@ describe("generateSessionTitle", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -149,6 +151,7 @@ describe("generateSessionTitle", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -235,6 +238,7 @@ describe("generateSessionTitle", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,

package/server/claude-adapter.test.ts

@@ -1864,6 +1864,58 @@ describe("stdio silence probe", () => {
     expect(adapter.isConnected()).toBe(true);
   });
 
+  it("does NOT kill a session that is silent because a tool is running", async () => {
+    // Production regression: a session running its test suite (a single ~200s
+    // Bash call) was declared dead at 182s of silence and relaunched, losing the
+    // turn. The CLI does not service control requests while a synchronous tool
+    // runs, so an unanswered probe proves nothing.
+    vi.useFakeTimers();
+    const { proc, pushStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    pushStdout(
+      JSON.stringify({
+        type: "assistant",
+        message: {
+          role: "assistant",
+          model: "m",
+          content: [{ type: "tool_use", id: "tu-slow", name: "Bash", input: {} }],
+        },
+        session_id: "s",
+      }) + "\n",
+    );
+
+    // Well past probe-after + probe-timeout, which previously killed it.
+    await vi.advanceTimersByTimeAsync(300_000);
+
+    expect(disconnectCb).not.toHaveBeenCalled();
+    expect(adapter.isConnected()).toBe(true);
+  });
+
+  it("still escalates when a tool call blows the grace ceiling", async () => {
+    // A tool that never returns must not suppress recovery forever.
+    vi.useFakeTimers();
+    const { proc, pushStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    pushStdout(
+      JSON.stringify({
+        type: "assistant",
+        message: {
+          role: "assistant",
+          model: "m",
+          content: [{ type: "tool_use", id: "tu-stuck", name: "Bash", input: {} }],
+        },
+        session_id: "s",
+      }) + "\n",
+    );
+
+    await vi.advanceTimersByTimeAsync(700_000); // past the 660s ceiling
+
+    expect(disconnectCb).toHaveBeenCalledTimes(1);
+    expect(adapter.isConnected()).toBe(false);
+  });
+
   it("does nothing when the silence probe is disabled", async () => {
     vi.useFakeTimers();
     mockSettings.silenceProbeEnabled = false;

package/server/claude-adapter.ts

@@ -159,6 +159,18 @@ const SILENCE_CHECK_INTERVAL_MS = Number(process.env.COMPANION_SILENCE_CHECK_INT
  */
 const TURN_STALL_AFTER_MS = Number(process.env.COMPANION_TURN_STALL_AFTER_MS) || 300_000;
 
+/**
+ * How long a CLI with an outstanding tool call is allowed to stay silent before
+ * the liveness probe is permitted to escalate anyway.
+ *
+ * The CLI does not answer control requests while a synchronous tool runs, so
+ * during a long `Bash` call the probe goes unanswered for reasons that have
+ * nothing to do with health. Set above the CLI's own maximum background-command
+ * duration (10 minutes), on the same reasoning as TEARDOWN_MAX_MS: only a tool
+ * that blows this ceiling is treated as a genuine hang.
+ */
+const TOOL_CALL_PROBE_GRACE_MS = Number(process.env.COMPANION_TOOL_CALL_PROBE_GRACE_MS) || 660_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;
 
@@ -626,6 +638,22 @@ export class ClaudeAdapter implements IBackendAdapter {
     // An unanswered probe is the actual failure signal: a healthy CLI replies
     // to control requests promptly even while working.
     if (this.probeSentAt !== null) {
+      // A long tool call is silence with a cause. The CLI does not service
+      // control requests while a synchronous tool runs, so an unanswered probe
+      // proves nothing here — and killing on it destroys a healthy session
+      // mid-work. Observed in production: a session running its test suite (a
+      // single ~200s Bash call) was declared dead at 182s of silence and
+      // relaunched, losing the turn.
+      //
+      // Bounded by TOOL_CALL_PROBE_GRACE_MS so a tool that never returns cannot
+      // suppress recovery forever; the ceiling sits above the CLI's own maximum
+      // background-command duration, matching TEARDOWN_MAX_MS's reasoning.
+      if (
+        this.pendingToolUses.size > 0 &&
+        now - this.lastInboundAt < TOOL_CALL_PROBE_GRACE_MS
+      ) {
+        return;
+      }
       if (now - this.probeSentAt >= SILENCE_PROBE_TIMEOUT_MS) {
         log.warn("claude-adapter", "CLI silent with stdout open and probe unanswered; treating transport as dead", {
           sessionId: this.sessionId,

package/server/linear-connections.test.ts

@@ -68,6 +68,7 @@ beforeEach(() => {
     updateChannel: "stable",
     dockerAutoUpdate: false,
     proactiveKeepaliveEnabled: true,
+    keepaliveDetachedSessions: false,
     wedgeKillEnabled: true,
     silenceProbeEnabled: true,
     updatedAt: 0,
@@ -206,6 +207,7 @@ describe("linear-connections", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -254,6 +256,7 @@ describe("linear-connections", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -321,6 +324,7 @@ describe("linear-connections", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,

package/server/routes/settings-routes.ts

@@ -34,6 +34,7 @@ export function registerSettingsRoutes(api: Hono): void {
       updateChannel: settings.updateChannel,
       dockerAutoUpdate: settings.dockerAutoUpdate,
       proactiveKeepaliveEnabled: settings.proactiveKeepaliveEnabled,
+      keepaliveDetachedSessions: settings.keepaliveDetachedSessions,
       wedgeKillEnabled: settings.wedgeKillEnabled,
       silenceProbeEnabled: settings.silenceProbeEnabled,
       cliBridgeMode: settings.cliBridgeMode,
@@ -134,6 +135,9 @@ export function registerSettingsRoutes(api: Hono): void {
     if (body.proactiveKeepaliveEnabled !== undefined && typeof body.proactiveKeepaliveEnabled !== "boolean") {
       return c.json({ error: "proactiveKeepaliveEnabled must be a boolean" }, 400);
     }
+    if (body.keepaliveDetachedSessions !== undefined && typeof body.keepaliveDetachedSessions !== "boolean") {
+      return c.json({ error: "keepaliveDetachedSessions must be a boolean" }, 400);
+    }
     if (body.wedgeKillEnabled !== undefined && typeof body.wedgeKillEnabled !== "boolean") {
       return c.json({ error: "wedgeKillEnabled must be a boolean" }, 400);
     }
@@ -160,6 +164,7 @@ export function registerSettingsRoutes(api: Hono): void {
       || body.updateChannel !== undefined
       || body.dockerAutoUpdate !== undefined
       || body.proactiveKeepaliveEnabled !== undefined
+      || body.keepaliveDetachedSessions !== undefined
       || body.wedgeKillEnabled !== undefined
       || body.silenceProbeEnabled !== undefined
       || body.cliBridgeMode !== undefined;
@@ -276,6 +281,10 @@ export function registerSettingsRoutes(api: Hono): void {
         typeof body.proactiveKeepaliveEnabled === "boolean"
           ? body.proactiveKeepaliveEnabled
           : undefined,
+      keepaliveDetachedSessions:
+        typeof body.keepaliveDetachedSessions === "boolean"
+          ? body.keepaliveDetachedSessions
+          : undefined,
       wedgeKillEnabled:
         typeof body.wedgeKillEnabled === "boolean"
           ? body.wedgeKillEnabled
@@ -317,6 +326,7 @@ export function registerSettingsRoutes(api: Hono): void {
       updateChannel: settings.updateChannel,
       dockerAutoUpdate: settings.dockerAutoUpdate,
       proactiveKeepaliveEnabled: settings.proactiveKeepaliveEnabled,
+      keepaliveDetachedSessions: settings.keepaliveDetachedSessions,
       wedgeKillEnabled: settings.wedgeKillEnabled,
       silenceProbeEnabled: settings.silenceProbeEnabled,
       cliBridgeMode: settings.cliBridgeMode,

package/server/routes.test.ts

@@ -1158,6 +1158,7 @@ describe("GET /api/sessions/:id/archive-info", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -1535,6 +1536,7 @@ describe("GET /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 123,
@@ -1570,6 +1572,7 @@ describe("GET /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
     });
@@ -1605,6 +1608,7 @@ describe("GET /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 123,
@@ -1640,6 +1644,7 @@ describe("GET /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
     });
@@ -1676,6 +1681,7 @@ describe("GET /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 100,
@@ -1720,6 +1726,7 @@ describe("PUT /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 456,
@@ -1777,6 +1784,7 @@ describe("PUT /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
     });
@@ -1812,6 +1820,7 @@ describe("PUT /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 789,
@@ -1864,6 +1873,7 @@ describe("PUT /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 999,
@@ -2016,6 +2026,7 @@ describe("PUT /api/settings", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 500,
@@ -2274,6 +2285,7 @@ describe("GET /api/linear/issues", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2316,6 +2328,7 @@ describe("GET /api/linear/issues", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2411,6 +2424,7 @@ describe("GET /api/linear/issues", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2513,6 +2527,7 @@ describe("GET /api/linear/issues", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2580,6 +2595,7 @@ describe("GET /api/linear/connection", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2622,6 +2638,7 @@ describe("GET /api/linear/connection", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2686,6 +2703,7 @@ describe("POST /api/linear/issues/:id/transition", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2732,6 +2750,7 @@ describe("POST /api/linear/issues/:id/transition", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2777,6 +2796,7 @@ describe("POST /api/linear/issues/:id/transition", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2824,6 +2844,7 @@ describe("POST /api/linear/issues/:id/transition", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2905,6 +2926,7 @@ describe("POST /api/linear/issues/:id/transition", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -2965,6 +2987,7 @@ describe("GET /api/linear/projects", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -3007,6 +3030,7 @@ describe("GET /api/linear/projects", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -3079,6 +3103,7 @@ describe("GET /api/linear/project-issues", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -3121,6 +3146,7 @@ describe("GET /api/linear/project-issues", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -3208,6 +3234,7 @@ describe("GET /api/linear/project-issues", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,

package/server/session-orchestrator.test.ts

@@ -50,6 +50,7 @@ vi.mock("./settings-manager.js", () => ({
     openaiApiKey: "",
     onboardingCompleted: false,
     proactiveKeepaliveEnabled: true,
+    keepaliveDetachedSessions: false,
     wedgeKillEnabled: true,
     silenceProbeEnabled: true,
   })),
@@ -249,6 +250,7 @@ describe("SessionOrchestrator", () => {
       openaiApiKey: "",
       onboardingCompleted: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
     } as any);
@@ -434,6 +436,102 @@ describe("SessionOrchestrator", () => {
 
   // ── Crash-loop relaunch budget ────────────────────────────────────────────
 
+  // ── Browser-aware keepalive ───────────────────────────────────────────────
+
+  /**
+   * Relaunching a session nobody has open buys latency nobody is waiting for,
+   * while re-initialising that session's MCP servers from scratch every time.
+   * Measured on a 4-core host: 90 relaunches in 21 minutes drove the load
+   * average to 36, starving the live sessions into failing and producing more
+   * relaunches. Detached sessions revive on demand instead — typing into a
+   * terminated session already requests a relaunch and flushes the queued
+   * message on attach.
+   */
+  describe("keepalive is browser-aware", () => {
+    async function crash() {
+      companionBus.emit("session:exited", { sessionId: "s1", exitCode: 143 });
+      await vi.advanceTimersByTimeAsync(45_000);
+      await vi.advanceTimersByTimeAsync(0);
+    }
+
+    beforeEach(() => {
+      deps.launcher.getSession.mockReturnValue({ archived: false, state: "exited", pid: undefined } as any);
+      deps.launcher.relaunch.mockResolvedValue({ ok: true });
+      deps.wsBridge.isCliConnected.mockReturnValue(false);
+    });
+
+    it("does NOT relaunch a session with no browser attached", async () => {
+      vi.useFakeTimers();
+      deps.wsBridge.getSession.mockReturnValue({ browserSockets: new Set() } as any);
+      orchestrator.initialize();
+
+      await crash();
+
+      expect(deps.launcher.relaunch).not.toHaveBeenCalled();
+      vi.useRealTimers();
+    });
+
+    it("relaunches a session someone has open", async () => {
+      vi.useFakeTimers();
+      deps.wsBridge.getSession.mockReturnValue({ browserSockets: new Set(["ws1"]) } as any);
+      orchestrator.initialize();
+
+      await crash();
+
+      expect(deps.launcher.relaunch).toHaveBeenCalled();
+      vi.useRealTimers();
+    });
+
+    it("always relaunches agent/cron sessions, which run detached by design", async () => {
+      // For these a dead CLI means dropped work, not just a slower first reply.
+      vi.useFakeTimers();
+      deps.launcher.getSession.mockReturnValue({
+        archived: false, state: "exited", pid: undefined, agentId: "agent-7",
+      } as any);
+      deps.wsBridge.getSession.mockReturnValue({ browserSockets: new Set() } as any);
+      orchestrator.initialize();
+
+      await crash();
+
+      expect(deps.launcher.relaunch).toHaveBeenCalled();
+      vi.useRealTimers();
+    });
+
+    it("relaunches detached sessions when the setting opts back in", async () => {
+      vi.useFakeTimers();
+      const { getSettings } = await import("./settings-manager.js");
+      const prior = (getSettings as any).getMockImplementation();
+      // The gate reads getSettings() more than once per relaunch decision, so
+      // this has to hold for the whole cycle rather than a single call.
+      (getSettings as any).mockReturnValue({
+        proactiveKeepaliveEnabled: true,
+        keepaliveDetachedSessions: true,
+        wedgeKillEnabled: true,
+        silenceProbeEnabled: true,
+      });
+      deps.wsBridge.getSession.mockReturnValue({ browserSockets: new Set() } as any);
+      orchestrator.initialize();
+
+      await crash();
+
+      expect(deps.launcher.relaunch).toHaveBeenCalled();
+      (getSettings as any).mockImplementation(prior);
+      vi.useRealTimers();
+    });
+
+    it("fails open when the bridge has no record of the session", async () => {
+      // A bookkeeping gap must never silently cost a session its recovery.
+      vi.useFakeTimers();
+      deps.wsBridge.getSession.mockReturnValue(null as any);
+      orchestrator.initialize();
+
+      await crash();
+
+      expect(deps.launcher.relaunch).toHaveBeenCalled();
+      vi.useRealTimers();
+    });
+  });
+
   describe("auto-relaunch crash budget", () => {
     // Drives one crash→proactive-relaunch cycle: the CLI exits, the keepalive
     // timer fires, handleAutoRelaunch waits out its grace + cooldown, and the
@@ -1835,6 +1933,7 @@ describe("SessionOrchestrator", () => {
       vi.mocked(settingsManager.getSettings).mockReturnValue({
         ...settingsManager.getSettings(),
         proactiveKeepaliveEnabled: false,
+        keepaliveDetachedSessions: false,
         wedgeKillEnabled: true,
         silenceProbeEnabled: true,
       });

package/server/session-orchestrator.ts

@@ -982,14 +982,14 @@ export class SessionOrchestrator {
   // ── Private: Proactive keepalive ────────────────────────────────────────────
 
   /**
-   * Schedules a proactive relaunch of a crashed CLI process, regardless of
-   * whether any browsers are connected. Uses exponential backoff (3s, 6s, 12s)
-   * based on the auto-relaunch attempt count.
+   * Schedules a proactive relaunch of a crashed CLI process. Uses exponential
+   * backoff (3s, 6s, 12s) based on the auto-relaunch attempt count.
    *
    * Skips relaunch for:
    * - Intentional kills (idle-kill, manual delete/archive)
    * - Archived sessions
    * - Sessions that have exhausted their relaunch budget
+   * - Detached sessions, unless `keepaliveDetachedSessions` is on (see below)
    */
   private scheduleProactiveRelaunch(sessionId: string): void {
     // Respect the global kill-switch — lets operators experiment with letting
@@ -1006,6 +1006,35 @@ export class SessionOrchestrator {
     const info = this.launcher.getSession(sessionId);
     if (!info || info.archived) return;
 
+    // Detached sessions: nobody is watching, so nobody is waiting on the
+    // latency this relaunch buys. Relaunching them anyway is what turns a
+    // handful of crashes into a load spike — every relaunch re-initialises the
+    // session's MCP servers from scratch (`npm exec` + node boot, plus chromium
+    // for @playwright/mcp). Measured on a 4-core host: 90 relaunches in 21
+    // minutes drove the load average to 36, which starved the *live* sessions
+    // into failing, producing more relaunches.
+    //
+    // Nothing is lost by waiting. Typing into a terminated session already
+    // requests a relaunch on demand (`terminated -> starting` is legal, and the
+    // queued message flushes on attach), which is the same path that replays an
+    // in-flight turn after a wedge-kill. The cost is a one-time resume on first
+    // message instead of a permanent warm process.
+    //
+    // Agent- and cron-spawned sessions are exempt: they legitimately run with no
+    // browser attached, and for them a dead CLI means dropped work, not just a
+    // slower first reply.
+    // Fails open: only a session the bridge positively reports as having zero
+    // browsers is treated as detached. If the bridge has no record of it we
+    // relaunch as before, so a bookkeeping gap can never silently cost a session
+    // its recovery.
+    if (!info.agentId && !getSettings().keepaliveDetachedSessions) {
+      const tracked = this.wsBridge.getSession(sessionId);
+      if (tracked && tracked.browserSockets.size === 0) {
+        log.info("orchestrator", "Session detached; deferring relaunch until it is opened", { sessionId });
+        return;
+      }
+    }
+
     // Skip if already at relaunch limit
     if (this.relaunchExhaustedNotified.has(sessionId)) return;
 

package/server/settings-manager.test.ts

@@ -53,6 +53,7 @@ describe("settings-manager", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       cliBridgeMode: "loopback",
@@ -119,6 +120,7 @@ describe("settings-manager", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       cliBridgeMode: "loopback",
@@ -211,6 +213,7 @@ describe("settings-manager", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       cliBridgeMode: "loopback",

package/server/settings-manager.ts

@@ -92,6 +92,16 @@ export interface CompanionSettings {
    * cron) alive. Disable to experiment with letting dead sessions stay dead.
    */
   proactiveKeepaliveEnabled: boolean;
+  /**
+   * Also keep *detached* sessions (no browser attached) auto-relaunching.
+   *
+   * Off by default: relaunching a session nobody has open buys latency nobody
+   * is waiting for, while re-initialising its MCP servers each time. On a busy
+   * multi-session host that dominates CPU. Detached sessions still revive on
+   * demand the moment a message is sent to them. Agent/cron sessions are exempt
+   * from this gate and always keep alive.
+   */
+  keepaliveDetachedSessions: boolean;
   /**
    * When true (default), a CLI whose stdout closes but which does not exit is
    * treated as wedged and killed so recovery can proceed.
@@ -158,6 +168,7 @@ let settings: CompanionSettings = {
   updateChannel: "stable",
   dockerAutoUpdate: false,
   proactiveKeepaliveEnabled: true,
+  keepaliveDetachedSessions: false,
   wedgeKillEnabled: true,
   silenceProbeEnabled: true,
   cliBridgeMode: "loopback",
@@ -211,6 +222,7 @@ function normalize(raw: Partial<CompanionSettings> | null | undefined): Companio
     updateChannel: raw?.updateChannel === "prerelease" ? "prerelease" : "stable",
     dockerAutoUpdate: typeof raw?.dockerAutoUpdate === "boolean" ? raw.dockerAutoUpdate : false,
     proactiveKeepaliveEnabled: typeof raw?.proactiveKeepaliveEnabled === "boolean" ? raw.proactiveKeepaliveEnabled : true,
+    keepaliveDetachedSessions: typeof raw?.keepaliveDetachedSessions === "boolean" ? raw.keepaliveDetachedSessions : false,
     wedgeKillEnabled: typeof raw?.wedgeKillEnabled === "boolean" ? raw.wedgeKillEnabled : true,
     silenceProbeEnabled: typeof raw?.silenceProbeEnabled === "boolean" ? raw.silenceProbeEnabled : true,
     cliBridgeMode: raw?.cliBridgeMode === "jsonHandoff" ? "jsonHandoff" : "loopback",
@@ -246,7 +258,7 @@ export function getSettings(): CompanionSettings {
 }
 
 export function updateSettings(
-  patch: Partial<Pick<CompanionSettings, "anthropicApiKey" | "anthropicModel" | "claudeCodeOAuthToken" | "openaiApiKey" | "onboardingCompleted" | "linearApiKey" | "linearAutoTransition" | "linearAutoTransitionStateId" | "linearAutoTransitionStateName" | "linearArchiveTransition" | "linearArchiveTransitionStateId" | "linearArchiveTransitionStateName" | "linearOAuthClientId" | "linearOAuthClientSecret" | "linearOAuthWebhookSecret" | "linearOAuthAccessToken" | "linearOAuthRefreshToken" | "aiValidationEnabled" | "aiValidationAutoApprove" | "aiValidationAutoDeny" | "dashboardEnabled" | "dashboardModel" | "dashboardRunHour" | "dashboardMaxSessionsPerRun" | "publicUrl" | "updateChannel" | "dockerAutoUpdate" | "proactiveKeepaliveEnabled" | "wedgeKillEnabled" | "silenceProbeEnabled" | "cliBridgeMode" | "claudeBridgeMode" | "claudeBridgeIngressUrl" | "claudeCompatBannerDismissedVersion">>,
+  patch: Partial<Pick<CompanionSettings, "anthropicApiKey" | "anthropicModel" | "claudeCodeOAuthToken" | "openaiApiKey" | "onboardingCompleted" | "linearApiKey" | "linearAutoTransition" | "linearAutoTransitionStateId" | "linearAutoTransitionStateName" | "linearArchiveTransition" | "linearArchiveTransitionStateId" | "linearArchiveTransitionStateName" | "linearOAuthClientId" | "linearOAuthClientSecret" | "linearOAuthWebhookSecret" | "linearOAuthAccessToken" | "linearOAuthRefreshToken" | "aiValidationEnabled" | "aiValidationAutoApprove" | "aiValidationAutoDeny" | "dashboardEnabled" | "dashboardModel" | "dashboardRunHour" | "dashboardMaxSessionsPerRun" | "publicUrl" | "updateChannel" | "dockerAutoUpdate" | "proactiveKeepaliveEnabled" | "keepaliveDetachedSessions" | "wedgeKillEnabled" | "silenceProbeEnabled" | "cliBridgeMode" | "claudeBridgeMode" | "claudeBridgeIngressUrl" | "claudeCompatBannerDismissedVersion">>,
 ): CompanionSettings {
   ensureLoaded();
   settings = normalize({
@@ -278,6 +290,7 @@ export function updateSettings(
     updateChannel: patch.updateChannel ?? settings.updateChannel,
     dockerAutoUpdate: patch.dockerAutoUpdate ?? settings.dockerAutoUpdate,
     proactiveKeepaliveEnabled: patch.proactiveKeepaliveEnabled ?? settings.proactiveKeepaliveEnabled,
+    keepaliveDetachedSessions: patch.keepaliveDetachedSessions ?? settings.keepaliveDetachedSessions,
     wedgeKillEnabled: patch.wedgeKillEnabled ?? settings.wedgeKillEnabled,
     silenceProbeEnabled: patch.silenceProbeEnabled ?? settings.silenceProbeEnabled,
     cliBridgeMode: patch.cliBridgeMode ?? settings.cliBridgeMode,

package/server/ws-bridge-codex.test.ts

@@ -140,6 +140,7 @@ describe("attachCodexAdapterHandlers", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       proactiveKeepaliveEnabled: true,
+      keepaliveDetachedSessions: false,
       wedgeKillEnabled: true,
       silenceProbeEnabled: true,
       updatedAt: 0,
@@ -1133,6 +1134,7 @@ describe("attachCodexAdapterHandlers", () => {
         updateChannel: "stable",
         dockerAutoUpdate: false,
         proactiveKeepaliveEnabled: true,
+        keepaliveDetachedSessions: false,
         wedgeKillEnabled: true,
         silenceProbeEnabled: true,
         updatedAt: 0,
@@ -1316,6 +1318,7 @@ describe("attachCodexAdapterHandlers", () => {
         updateChannel: "stable",
         dockerAutoUpdate: false,
         proactiveKeepaliveEnabled: true,
+        keepaliveDetachedSessions: false,
         wedgeKillEnabled: true,
         silenceProbeEnabled: true,
         updatedAt: 0,
@@ -1369,6 +1372,7 @@ describe("attachCodexAdapterHandlers", () => {
         updateChannel: "stable",
         dockerAutoUpdate: false,
         proactiveKeepaliveEnabled: true,
+        keepaliveDetachedSessions: false,
         wedgeKillEnabled: true,
         silenceProbeEnabled: true,
         updatedAt: 0,
@@ -1487,6 +1491,7 @@ describe("attachCodexAdapterHandlers", () => {
         updateChannel: "stable",
         dockerAutoUpdate: false,
         proactiveKeepaliveEnabled: true,
+        keepaliveDetachedSessions: false,
         wedgeKillEnabled: true,
         silenceProbeEnabled: true,
         updatedAt: 0,
@@ -1624,6 +1629,7 @@ describe("attachCodexAdapterHandlers", () => {
         updateChannel: "stable",
         dockerAutoUpdate: false,
         proactiveKeepaliveEnabled: true,
+        keepaliveDetachedSessions: false,
         wedgeKillEnabled: true,
         silenceProbeEnabled: true,
         updatedAt: 0,