@hellcoder/companion 0.110.0 → 0.110.1-preview.20260726083620.ff8e630

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellcoder/companion",
-  "version": "0.110.0",
+  "version": "0.110.1-preview.20260726083620.ff8e630",
   "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.ts

@@ -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 } from "./proc-diagnostics.js";
+import { captureProcState, hasLiveDescendants } from "./proc-diagnostics.js";
 import { parseNDJSON, isDuplicateCLIMessage } from "./ws-bridge-cli-ingest.js";
 import type { CLIDedupState } from "./ws-bridge-cli-ingest.js";
 import { reportProtocolDrift } from "./protocol-monitor.js";
@@ -75,6 +75,15 @@ const STDOUT_CLOSE_GRACE_MS = Number(process.env.COMPANION_STDOUT_CLOSE_GRACE_MS
  */
 const STDOUT_CLOSE_RESULT_GRACE_MS = Number(process.env.COMPANION_STDOUT_CLOSE_RESULT_GRACE_MS) || 10000;
 
+/**
+ * How long to wait after SIGTERM before escalating to SIGKILL.
+ *
+ * A CLI that ignores SIGTERM because it is itself blocked reaping children used
+ * to be left behind by the old flat kill, so `handleAutoRelaunch`'s PID-liveness
+ * guard could still see it alive. Escalating guarantees the pid is gone.
+ */
+const SIGKILL_ESCALATION_MS = Number(process.env.COMPANION_SIGKILL_ESCALATION_MS) || 2000;
+
 // --- Claude Code Adapter ------------------------------------------------------
 
 export class ClaudeAdapter implements IBackendAdapter {
@@ -322,7 +331,23 @@ export class ClaudeAdapter implements IBackendAdapter {
       //      is STILL alive afterwards, so a true wedge can't block recovery.
       const proc = this.stdioProc;
       if (proc && proc.exitCode === null && !proc.killed) {
-        if (this.lastInboundWasResult) {
+        // Which grace applies is decided by whether teardown is actually in
+        // progress, NOT by whether the last message happened to be a `result`.
+        //
+        // Every CLI spawns 2-3 MCP stdio servers, and npm-exec-wrapped servers
+        // plus headless chromium do not reap inside the short grace. The old
+        // `lastInboundWasResult` discriminator was a proxy for "clean shutdown"
+        // that has nothing to do with teardown cost, so a healthy CLI landed on
+        // the short grace two ways: any non-result/keep_alive/system message
+        // trailing the turn, or a fresh adapter (the flag initialises false).
+        // It was then SIGTERMed mid-teardown, exiting 143 and taking the user's
+        // turn with it.
+        //
+        // Live descendants are the direct signal: a genuine wedge is idle with
+        // no children, whereas a CLI still reaping MCP servers has children
+        // mid-exit.
+        const teardownInProgress = hasLiveDescendants(proc.pid);
+        if (this.lastInboundWasResult || teardownInProgress) {
           // Clean end-of-turn shutdown: let the process flush teardown (MCP
           // servers, etc.) and exit code-0 instead of SIGTERM-ing a code-0 exit.
           // Use a generous grace so we don't clobber a slow-but-clean exit, but
@@ -340,13 +365,10 @@ export class ClaudeAdapter implements IBackendAdapter {
               sessionId: this.sessionId,
               pid: proc.pid,
               graceMs: STDOUT_CLOSE_RESULT_GRACE_MS,
+              graceReason: this.lastInboundWasResult ? "result" : "descendants_alive",
               proc: captureProcState(proc.pid),
             });
-            try {
-              proc.kill();
-            } catch {
-              // Process may have exited between the check and the kill.
-            }
+            await this.killWithEscalation(proc);
           }
         } else {
           const exitedOnOwn = await Promise.race([
@@ -354,21 +376,17 @@ export class ClaudeAdapter implements IBackendAdapter {
             new Promise<boolean>((resolve) => setTimeout(() => resolve(false), STDOUT_CLOSE_GRACE_MS)),
           ]);
           if (!exitedOnOwn && proc.exitCode === null && !proc.killed) {
-            // Same rationale as the after-result branch above: snapshot kernel
-            // state before the kill destroys it. This is the dominant wedge
-            // variant (23 of 29 observed), so it is the one most likely to
-            // carry the answer.
+            // Reaching here now means a genuine wedge: stdout closed, no live
+            // descendants to reap, and still not exited. Snapshot kernel state
+            // before the kill destroys it.
             log.warn("claude-adapter", "stdout closed mid-stream and process did not exit within grace; killing wedged process", {
               sessionId: this.sessionId,
               pid: proc.pid,
               graceMs: STDOUT_CLOSE_GRACE_MS,
+              graceReason: "no_descendants",
               proc: captureProcState(proc.pid),
             });
-            try {
-              proc.kill();
-            } catch {
-              // Process may have exited between the check and the kill.
-            }
+            await this.killWithEscalation(proc);
           }
         }
       }
@@ -376,6 +394,40 @@ export class ClaudeAdapter implements IBackendAdapter {
     }
   }
 
+  /**
+   * SIGTERM a process, then SIGKILL it if it has not exited.
+   *
+   * A flat SIGTERM is not enough for the case this path exists to handle: a CLI
+   * blocked reaping its own children may never act on the signal, staying alive
+   * 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.
+   */
+  private async killWithEscalation(proc: Subprocess): Promise<void> {
+    try {
+      proc.kill();
+    } catch {
+      return; // Already gone.
+    }
+
+    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;
+
+    log.warn("claude-adapter", "process ignored SIGTERM; escalating to SIGKILL", {
+      sessionId: this.sessionId,
+      pid: proc.pid,
+      afterMs: SIGKILL_ESCALATION_MS,
+    });
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // Exited between the check and the escalation.
+    }
+  }
+
   /**
    * Send the one-time `initialize` control_request before the first outbound
    * message in stdio mode. This registers the canUseTool capability so the CLI

package/server/proc-diagnostics.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect, vi, afterEach } from "vitest";
-import { captureProcState, isProcAvailable } from "./proc-diagnostics.js";
+import { spawn } from "node:child_process";
+import {
+  captureProcState,
+  isProcAvailable,
+  getDescendants,
+  hasLiveDescendants,
+} from "./proc-diagnostics.js";
 
 /**
  * These tests cover the diagnostic that runs on the wedge-kill recovery path in
@@ -70,3 +76,68 @@ describe("captureProcState", () => {
     expect(JSON.stringify(snapshot)).toContain("state");
   });
 });
+
+/**
+ * Descendant detection is what replaced `lastInboundWasResult` as the grace
+ * discriminator in claude-adapter. Its correctness decides whether a CLI that
+ * is mid-teardown gets the generous grace or gets SIGTERMed at 2s — the latter
+ * being the bug that killed users' turns.
+ */
+describe("getDescendants / hasLiveDescendants", () => {
+  it("returns empty for undefined pid without throwing", () => {
+    expect(getDescendants(undefined)).toEqual([]);
+    expect(hasLiveDescendants(undefined)).toBe(false);
+  });
+
+  it("returns empty on platforms without /proc", () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    expect(getDescendants(1)).toEqual([]);
+    expect(hasLiveDescendants(1)).toBe(false);
+  });
+
+  it("returns empty for a pid that does not exist", () => {
+    expect(getDescendants(2_147_483_646)).toEqual([]);
+    expect(hasLiveDescendants(2_147_483_646)).toBe(false);
+  });
+
+  it.runIf(isLinux)("detects a live child and reports it gone after exit", async () => {
+    // Mirrors the real shape: a parent holding a child that has not yet reaped.
+    // `sleep` stands in for an MCP stdio server still shutting down.
+    const child = spawn("sleep", ["30"], { stdio: "ignore" });
+    await new Promise((r) => setTimeout(r, 150)); // let the fork land in /proc
+
+    expect(hasLiveDescendants(process.pid)).toBe(true);
+    const descendants = getDescendants(process.pid);
+    const found = descendants.find((d) => d.pid === child.pid);
+    expect(found).toBeDefined();
+    expect(found?.comm).toBe("sleep");
+    // A running-but-idle child reports S (sleeping), not Z (reaped).
+    expect(found?.state).toBe("S");
+
+    // After the child exits and is reaped, it must no longer count — otherwise
+    // a genuinely wedged process would be granted the long grace forever.
+    child.kill("SIGKILL");
+    await new Promise((r) => child.on("exit", r));
+    await new Promise((r) => setTimeout(r, 150));
+
+    expect(getDescendants(process.pid).some((d) => d.pid === child.pid)).toBe(false);
+  });
+
+  it.runIf(isLinux)("bounds the walk so a large tree cannot stall the kill path", () => {
+    // maxNodes is a safety bound: this runs immediately before a kill that
+    // unblocks a stuck session, so it must terminate regardless of tree size.
+    expect(getDescendants(1, 2).length).toBeLessThanOrEqual(2);
+  });
+
+  it.runIf(isLinux)("includes descendants in the captured snapshot", async () => {
+    const child = spawn("sleep", ["30"], { stdio: "ignore" });
+    await new Promise((r) => setTimeout(r, 150));
+
+    const snapshot = captureProcState(process.pid);
+    expect(snapshot.descendants?.some((d) => d.pid === child.pid)).toBe(true);
+    expect(() => JSON.stringify(snapshot)).not.toThrow();
+
+    child.kill("SIGKILL");
+    await new Promise((r) => child.on("exit", r));
+  });
+});

package/server/proc-diagnostics.ts

@@ -26,10 +26,105 @@ export interface ProcSnapshot {
   wchan?: string;
   /** Open file descriptor count for this process. */
   fdCount?: number;
+  /**
+   * Live descendants at capture time. This is the field that separates the two
+   * reasons a process sits in `ep_poll` with stdout closed: a genuine wedge is
+   * idle with NO children, whereas a CLI still reaping MCP stdio servers has
+   * children mid-exit. Without it, both look identical.
+   */
+  descendants?: ProcDescendant[];
   /** Why the snapshot is incomplete, when it is. */
   error?: string;
 }
 
+/** A live descendant process, as seen from /proc. */
+export interface ProcDescendant {
+  pid: number;
+  /** Command name from /proc/<pid>/comm, e.g. "npm exec", "node", "chrome". */
+  comm?: string;
+  /** Scheduler state letter, e.g. "S", "R", "Z". "Z" means mid-reap. */
+  state?: string;
+}
+
+/** Read the direct children of a pid via /proc/<pid>/task/<tid>/children. */
+function readChildren(pid: number): number[] {
+  const kids: number[] = [];
+  try {
+    for (const tid of readdirSync(`/proc/${pid}/task`)) {
+      try {
+        const raw = readFileSync(`/proc/${pid}/task/${tid}/children`, "utf8").trim();
+        if (!raw) continue;
+        for (const part of raw.split(/\s+/)) {
+          const child = Number(part);
+          if (Number.isInteger(child) && child > 0) kids.push(child);
+        }
+      } catch {
+        // Thread exited between readdir and read.
+      }
+    }
+  } catch {
+    // Process gone, or kernel built without CONFIG_PROC_CHILDREN.
+  }
+  return kids;
+}
+
+/**
+ * Walk the descendant tree of a pid, breadth-first.
+ *
+ * Bounded by `maxNodes` because this runs on the kill path — a runaway tree
+ * must not stall recovery. MCP stdio servers are the expected population here
+ * (2-3 per CLI, sometimes with their own children, e.g. headless chromium).
+ */
+export function getDescendants(
+  pid: number | undefined,
+  maxNodes = 32,
+): ProcDescendant[] {
+  if (pid === undefined || !isProcAvailable()) return [];
+
+  const found: ProcDescendant[] = [];
+  const seen = new Set<number>([pid]);
+  let frontier = readChildren(pid);
+
+  while (frontier.length > 0 && found.length < maxNodes) {
+    const next: number[] = [];
+    for (const child of frontier) {
+      if (seen.has(child) || found.length >= maxNodes) continue;
+      seen.add(child);
+
+      const entry: ProcDescendant = { pid: child };
+      try {
+        entry.comm = readFileSync(`/proc/${child}/comm`, "utf8").trim();
+      } catch {
+        // Already reaped — still worth reporting the pid.
+      }
+      try {
+        const status = readFileSync(`/proc/${child}/status`, "utf8");
+        const line = status.split("\n").find((l) => l.startsWith("State:"));
+        if (line) entry.state = line.split(":")[1]?.trim().split(" ")[0];
+      } catch {
+        // Same.
+      }
+      found.push(entry);
+      next.push(...readChildren(child));
+    }
+    frontier = next;
+  }
+
+  return found;
+}
+
+/**
+ * Whether a process still has live descendants.
+ *
+ * Used to decide how long to wait for a CLI to shut down: one that is still
+ * reaping MCP subprocesses deserves the generous grace, regardless of whether
+ * the last message it sent happened to be a `result`.
+ */
+export function hasLiveDescendants(pid: number | undefined): boolean {
+  if (pid === undefined || !isProcAvailable()) return false;
+  return readChildren(pid).length > 0;
+}
+
 /** True when /proc-based introspection is available (Linux only). */
 export function isProcAvailable(): boolean {
   return process.platform === "linux";
@@ -78,6 +173,12 @@ export function captureProcState(pid: number | undefined): ProcSnapshot {
     // Reading another process's fd dir can fail on permissions; not fatal.
   }
 
+  const descendants = getDescendants(pid);
+  if (descendants.length > 0) {
+    snapshot.descendants = descendants;
+    readAnything = true;
+  }
+
   if (!readAnything) snapshot.error = "process_gone_or_unreadable";
   return snapshot;
 }