@hellcoder/companion 0.110.3-preview.20260726142826.52ddfd8 → 0.110.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellcoder/companion",
-  "version": "0.110.3-preview.20260726142826.52ddfd8",
+  "version": "0.110.3",
   "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

@@ -23,6 +23,16 @@ vi.mock("node:crypto", () => ({
 }));
 
 // Mock settings-manager to prevent real file system reads
+// countDescendants is stubbed so the wedge tests can drive the "process has
+// live descendants" branch deterministically, without spawning real children.
+// Default 0 (childless) preserves the existing tests' behaviour; individual
+// tests override it.
+const mockCountDescendants = vi.hoisted(() => vi.fn(() => 0));
+vi.mock("./proc-diagnostics.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./proc-diagnostics.js")>()),
+  countDescendants: mockCountDescendants,
+}));
+
 vi.mock("./settings-manager.js", () => ({
   getSettings: () => ({
     aiValidationEnabled: false,
@@ -1593,6 +1603,44 @@ describe("stdio transport disconnect propagation", () => {
     }
   });
 
+  it("does NOT kill a process that is supervising live descendants", async () => {
+    // The dominant real-world case, from a captured kill:
+    //   graceReason=result state="R (running)" threads=28
+    //   descendants=[bash, gh, tail]
+    // Those are the agent's own tool subprocesses — a background command still
+    // running after the turn's `result`. The CLI closed stdout normally at
+    // end-of-turn and stayed alive to supervise that work.
+    //
+    // Its descendant count holds STEADY (nothing is being reaped), so any
+    // drop-based test reads it as stalled and kills a process that is actively
+    // working. It must survive well past the stall window.
+    vi.useFakeTimers();
+    mockCountDescendants.mockReturnValue(3); // bash + gh + tail
+    try {
+      const { proc, endStdout } = createMockProc();
+      adapter.attachStdio(proc);
+
+      endStdout();
+      await vi.advanceTimersByTimeAsync(0);
+      expect(proc.kill).not.toHaveBeenCalled();
+
+      // Far beyond the 10s stall window that would fire for a childless
+      // process. Still busy, so still not killed.
+      await vi.advanceTimersByTimeAsync(60_000);
+      expect(proc.kill).not.toHaveBeenCalled();
+
+      // Once the background work finishes and the children are gone, the stall
+      // window starts accumulating and a genuinely idle process is killed —
+      // recovery is deferred, not abandoned.
+      mockCountDescendants.mockReturnValue(0);
+      await vi.advanceTimersByTimeAsync(11_000);
+      expect(proc.kill).toHaveBeenCalledTimes(1);
+    } finally {
+      mockCountDescendants.mockReturnValue(0);
+      vi.useRealTimers();
+    }
+  });
+
   it("does NOT kill a process that exits on its own within the grace period", async () => {
     // The common, healthy case: the CLI closes stdout a beat before it exits
     // cleanly (e.g. right after a `result`). Killing here would convert a code-0

package/server/claude-adapter.ts

@@ -90,15 +90,16 @@ const STDOUT_CLOSE_RESULT_GRACE_MS = Number(process.env.COMPANION_STDOUT_CLOSE_R
 const SIGKILL_ESCALATION_MS = Number(process.env.COMPANION_SIGKILL_ESCALATION_MS) || 2000;
 
 /**
- * Absolute ceiling on waiting for MCP teardown, however well it is progressing.
+ * Absolute backstop on waiting for a process with live descendants, so a stuck
+ * child cannot block recovery forever.
  *
- * The flat 10s grace was not enough: 8 of 12 observed kills were processes
- * correctly identified as still reaping children, waited the full 10s for, and
- * killed anyway while perfectly healthy (S sleeping, 311-351MB). `npm exec`
- * -wrapped MCP servers plus headless chromium routinely exceed 10s, especially
- * with ~70 CLIs contending for I/O.
+ * Set above the CLI's own maximum background-command duration (10 minutes): the
+ * descendants being waited on are frequently the agent's own tool subprocesses,
+ * and a ceiling below that would kill a legitimately running command — the very
+ * failure this path exists to avoid. Only a process still childless-and-idle,
+ * or one that blows this ceiling, is treated as wedged.
  */
-const TEARDOWN_MAX_MS = Number(process.env.COMPANION_TEARDOWN_MAX_MS) || 120_000;
+const TEARDOWN_MAX_MS = Number(process.env.COMPANION_TEARDOWN_MAX_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;
@@ -426,21 +427,32 @@ export class ClaudeAdapter implements IBackendAdapter {
   private lastTeardownOutcome: string | undefined;
 
   /**
-   * Wait for a process to exit while its descendants are still being reaped.
+   * Wait for a process to exit after its stdout transport has died.
    *
-   * Returns true if it exited on its own. The wait is adaptive: as long as the
-   * descendant count keeps dropping, teardown is demonstrably working and we
-   * keep waiting regardless of elapsed time. We give up only when the count
-   * sits unchanged for TEARDOWN_STALL_MS (nothing is happening) or the hard
-   * TEARDOWN_MAX_MS ceiling is hit.
+   * Returns true if it exited on its own.
    *
-   * This replaces a flat 10s grace that killed 8 of 12 healthy processes: a
-   * fixed deadline cannot know how long `npm exec`-wrapped MCP servers plus
-   * headless chromium need, particularly under contention.
+   * The rule is: **a process with live descendants is never killed on a timer.**
+   *
+   * An earlier version only reset the stall window when the descendant count
+   * *dropped*, on the assumption that descendants are MCP servers mid-teardown.
+   * Captured evidence disproved that. A representative kill:
+   *
+   *   graceReason=result state="R (running)" wchan=0 threads=28
+   *   descendants=[{comm:"bash"},{comm:"gh"},{comm:"tail"}]
+   *
+   * Those are the agent's own tool subprocesses — a background command still
+   * running after the turn's `result`. The CLI had closed stdout normally at
+   * end-of-turn and stayed alive to supervise that work. Its descendant count
+   * holds steady for as long as the command runs, so a drop-based test reads it
+   * as stalled and kills a process that is actively working (R, on CPU).
+   *
+   * So any live descendant counts as "busy", not just a falling count. The
+   * stall window only accumulates once the process is childless AND idle, which
+   * is the one state that genuinely looks like a wedge. TEARDOWN_MAX_MS remains
+   * as a backstop so recovery cannot be blocked forever.
    */
   private async awaitTeardown(proc: Subprocess, stallMs: number): Promise<boolean> {
     const started = Date.now();
-    let lastCount = countDescendants(proc.pid);
     let lastProgressAt = started;
     this.lastTeardownOutcome = undefined;
 
@@ -456,10 +468,10 @@ export class ClaudeAdapter implements IBackendAdapter {
 
       const now = Date.now();
       const count = countDescendants(proc.pid);
-      if (count < lastCount) {
-        // Progress: children are being reaped. Reset the stall window — a slow
-        // but advancing teardown must never be killed.
-        lastCount = count;
+      if (count > 0) {
+        // Live descendants: the process is supervising work — a background tool
+        // call, or MCP servers still shutting down. Either way it is doing
+        // something, so the stall window must not accumulate.
         lastProgressAt = now;
       }
 

package/server/proc-diagnostics.test.ts

@@ -167,6 +167,30 @@ describe("getDescendants / hasLiveDescendants", () => {
     expect(countDescendants(process.pid)).toBeLessThan(withOne);
   });
 
+  it.runIf(isLinux)("countDescendants stays steady while a child keeps running", async () => {
+    // The case that broke the drop-based test. A background tool call (bash ->
+    // gh -> tail in the captured kill) holds a *steady* descendant count for as
+    // long as it runs — it never falls, because nothing is being reaped. Any
+    // logic keyed on a falling count reads this as a stall and kills a process
+    // that is actively working. awaitTeardown therefore treats count > 0 as
+    // busy, so this steady-state must be observable as non-zero over time.
+    const child = spawn("sleep", ["30"], { stdio: "ignore" });
+    await new Promise((r) => setTimeout(r, 150));
+
+    const first = countDescendants(process.pid);
+    expect(first).toBeGreaterThan(0);
+
+    await new Promise((r) => setTimeout(r, 400));
+    const second = countDescendants(process.pid);
+    // Still alive, still counted, and not decreasing — the signal that a
+    // drop-based test would misread.
+    expect(second).toBeGreaterThan(0);
+    expect(second).toBeGreaterThanOrEqual(first);
+
+    child.kill("SIGKILL");
+    await new Promise((r) => child.on("exit", r));
+  });
+
   it.runIf(isLinux)("countDescendants is bounded by maxNodes", () => {
     // Bounds the poll-loop cost: this runs every 500ms during teardown.
     expect(countDescendants(1, 3)).toBeLessThanOrEqual(3);