@hellcoder/companion 0.109.1 → 0.110.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellcoder/companion",
-  "version": "0.109.1",
+  "version": "0.110.0",
   "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,6 +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 { parseNDJSON, isDuplicateCLIMessage } from "./ws-bridge-cli-ingest.js";
 import type { CLIDedupState } from "./ws-bridge-cli-ingest.js";
 import { reportProtocolDrift } from "./protocol-monitor.js";
@@ -332,10 +333,14 @@ export class ClaudeAdapter implements IBackendAdapter {
             new Promise<boolean>((resolve) => setTimeout(() => resolve(false), STDOUT_CLOSE_RESULT_GRACE_MS)),
           ]);
           if (!exitedOnOwn && proc.exitCode === null && !proc.killed) {
+            // Capture kernel state BEFORE the kill: once we SIGTERM, the
+            // evidence is gone. A wedged CLI writes nothing to stderr, so this
+            // is the only signal about why it is still alive.
             log.warn("claude-adapter", "stdout closed after result but process did not exit within grace; killing wedged process", {
               sessionId: this.sessionId,
               pid: proc.pid,
               graceMs: STDOUT_CLOSE_RESULT_GRACE_MS,
+              proc: captureProcState(proc.pid),
             });
             try {
               proc.kill();
@@ -349,10 +354,15 @@ 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.
             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,
+              proc: captureProcState(proc.pid),
             });
             try {
               proc.kill();

package/server/proc-diagnostics.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { captureProcState, isProcAvailable } from "./proc-diagnostics.js";
+
+/**
+ * These tests cover the diagnostic that runs on the wedge-kill recovery path in
+ * claude-adapter.ts. The overriding requirement is that it NEVER throws — it
+ * executes immediately before a SIGTERM that unblocks a stuck session, so a
+ * diagnostic that raises would turn a recoverable wedge into a dead session.
+ *
+ * CI runs on both ubuntu-latest and macos-latest, and macOS has no /proc at
+ * all, so every test here must pass on a platform where the feature is inert.
+ */
+
+const isLinux = process.platform === "linux";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("isProcAvailable", () => {
+  // /proc is a Linux-only filesystem; on macOS the whole capture must no-op.
+  it("reports availability based on platform", () => {
+    expect(isProcAvailable()).toBe(process.platform === "linux");
+  });
+});
+
+describe("captureProcState", () => {
+  it("returns no_pid when the pid is undefined", () => {
+    // Bun's Subprocess.pid is optional, so undefined is reachable in practice.
+    expect(captureProcState(undefined)).toEqual({ error: "no_pid" });
+  });
+
+  it("never throws for a pid that does not exist", () => {
+    // The common race: the process exits between the liveness check and the
+    // capture. This must degrade to a marker, not an exception.
+    const snapshot = captureProcState(2_147_483_646);
+    expect(() => snapshot).not.toThrow();
+    if (isLinux) {
+      expect(snapshot.error).toBe("process_gone_or_unreadable");
+    }
+  });
+
+  it("degrades cleanly on platforms without /proc", () => {
+    // Simulate macOS regardless of the host we are running on, so this
+    // assertion is meaningful in both CI matrix legs.
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    expect(captureProcState(1)).toEqual({ error: "unsupported_platform:darwin" });
+  });
+
+  it.runIf(isLinux)("captures live kernel state for the current process", () => {
+    // Uses our own pid, which is guaranteed to exist and be readable. This is
+    // the field set the wedge investigation actually needs: `state` and `wchan`
+    // together distinguish a process blocked on a full pipe from one parked in
+    // a futex or spinning in userspace.
+    const snapshot = captureProcState(process.pid);
+
+    expect(snapshot.error).toBeUndefined();
+    // e.g. "R (running)" or "S (sleeping)" — always parenthesised on Linux.
+    expect(snapshot.state).toMatch(/^[A-Z] \(/);
+    expect(snapshot.threads).toBeGreaterThan(0);
+    expect(snapshot.fdCount).toBeGreaterThan(0);
+    // VmRSS is reported in kB by /proc; absent only for kernel threads.
+    expect(snapshot.vmRSS).toMatch(/kB$/);
+  });
+
+  it.runIf(isLinux)("returns a plain object safe to embed in a log payload", () => {
+    // The snapshot is passed straight into log.warn, which JSON-serialises it.
+    const snapshot = captureProcState(process.pid);
+    expect(() => JSON.stringify(snapshot)).not.toThrow();
+    expect(JSON.stringify(snapshot)).toContain("state");
+  });
+});

package/server/proc-diagnostics.ts

@@ -0,0 +1,83 @@
+// Kernel-level process diagnostics for wedged CLI processes.
+//
+// When a CLI wedges, its stdout is closed and it emits nothing on stderr (see
+// claude-adapter's wedge handling). With both output channels gone, the only
+// remaining signal about *why* it is still alive is kernel state, so we read it
+// from /proc immediately before killing the process.
+//
+// Everything here is best-effort and must never throw: this runs on a recovery
+// path, and a diagnostic that breaks recovery is worse than no diagnostic.
+
+import { readFileSync, readdirSync } from "node:fs";
+
+/** A point-in-time snapshot of kernel state for a process. */
+export interface ProcSnapshot {
+  /** Scheduler state, e.g. "S (sleeping)", "R (running)", "Z (zombie)", "D (disk sleep)". */
+  state?: string;
+  /** Thread count. A live-threads-but-no-output process looks different from a zombie. */
+  threads?: number;
+  /** Resident set size as reported by /proc (e.g. "123456 kB"). */
+  vmRSS?: string;
+  /**
+   * Kernel wait channel — the syscall the process is blocked in. This is the
+   * discriminating field: a process blocked writing to a full pipe, parked in a
+   * futex, and spinning in userspace are three different bugs.
+   */
+  wchan?: string;
+  /** Open file descriptor count for this process. */
+  fdCount?: number;
+  /** Why the snapshot is incomplete, when it is. */
+  error?: string;
+}
+
+/** True when /proc-based introspection is available (Linux only). */
+export function isProcAvailable(): boolean {
+  return process.platform === "linux";
+}
+
+/**
+ * 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:
+ * it exits between the liveness check and this call).
+ */
+export function captureProcState(pid: number | undefined): ProcSnapshot {
+  if (pid === undefined) return { error: "no_pid" };
+  if (!isProcAvailable()) return { error: `unsupported_platform:${process.platform}` };
+
+  const snapshot: ProcSnapshot = {};
+  let readAnything = false;
+
+  try {
+    const status = readFileSync(`/proc/${pid}/status`, "utf8");
+    readAnything = true;
+    for (const line of status.split("\n")) {
+      const [rawKey, ...rest] = line.split(":");
+      const value = rest.join(":").trim();
+      if (!value) continue;
+      if (rawKey === "State") snapshot.state = value;
+      else if (rawKey === "Threads") snapshot.threads = Number(value) || undefined;
+      else if (rawKey === "VmRSS") snapshot.vmRSS = value;
+    }
+  } catch {
+    // Process exited, or /proc entry vanished mid-read.
+  }
+
+  try {
+    // wchan has no trailing newline and reads as "0" for a running process.
+    const wchan = readFileSync(`/proc/${pid}/wchan`, "utf8").trim();
+    readAnything = true;
+    if (wchan) snapshot.wchan = wchan;
+  } catch {
+    // Requires the process to still exist; ignore if it does not.
+  }
+
+  try {
+    snapshot.fdCount = readdirSync(`/proc/${pid}/fd`).length;
+    readAnything = true;
+  } catch {
+    // Reading another process's fd dir can fail on permissions; not fatal.
+  }
+
+  if (!readAnything) snapshot.error = "process_gone_or_unreadable";
+  return snapshot;
+}