@hellcoder/companion 0.112.0 → 0.112.1-preview.20260728132124.bf82019

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellcoder/companion",
-  "version": "0.112.0",
+  "version": "0.112.1-preview.20260728132124.bf82019",
   "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

@@ -2221,3 +2221,101 @@ describe("orphaned descendant reaping", () => {
     expect(signalled).toEqual([]);
   });
 });
+
+/**
+ * stderr on the kill path.
+ *
+ * The launcher already captures a rolling stderr tail to classify *exit*
+ * reasons, but the wedge path kills the process rather than letting it exit, so
+ * that buffer was never surfaced. Every wedge warning therefore reported kernel
+ * state (S/ep_poll, RSS, fds) and nothing about what the CLI itself said before
+ * dropping stdout — which is the one piece of evidence that could explain a
+ * wedge rather than merely report it. In production 35 of 36 kills were
+ * `no_descendants` on healthy sleeping processes with no explanation available.
+ */
+describe("stderr tail on kill warnings", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(log, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    vi.useRealTimers();
+  });
+
+  const wedgeWarning = () =>
+    warnSpy.mock.calls.find((c: unknown[]) => String(c[1]).includes("killing wedged process"));
+
+  it("includes the CLI's stderr in the wedge-kill warning", async () => {
+    vi.useFakeTimers();
+    const adapter = new ClaudeAdapter("stderr-session", {
+      getStderrTail: () => "FATAL: upstream stream closed unexpectedly",
+    });
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    endStdout();
+    await vi.advanceTimersByTimeAsync(11_000);
+
+    const call = wedgeWarning();
+    expect(call).toBeDefined();
+    expect(call?.[2]).toMatchObject({ stderrTail: "FATAL: upstream stream closed unexpectedly" });
+  });
+
+  it("omits the field entirely when the CLI said nothing", async () => {
+    // A quiet failure should stay quiet rather than log an empty string.
+    vi.useFakeTimers();
+    const adapter = new ClaudeAdapter("stderr-quiet", { getStderrTail: () => "   " });
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    endStdout();
+    await vi.advanceTimersByTimeAsync(11_000);
+
+    expect(wedgeWarning()?.[2]).toMatchObject({ stderrTail: undefined });
+  });
+
+  it("caps a chatty process so it cannot flood the log", async () => {
+    vi.useFakeTimers();
+    const adapter = new ClaudeAdapter("stderr-loud", { getStderrTail: () => "x".repeat(5000) });
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    endStdout();
+    await vi.advanceTimersByTimeAsync(11_000);
+
+    const tail = (wedgeWarning()?.[2] as { stderrTail?: string })?.stderrTail;
+    expect(tail).toHaveLength(600);
+  });
+
+  it("still kills when the stderr reader throws", async () => {
+    // Diagnostics must never be able to block recovery.
+    vi.useFakeTimers();
+    const adapter = new ClaudeAdapter("stderr-throws", {
+      getStderrTail: () => { throw new Error("launcher gone"); },
+    });
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    endStdout();
+    await vi.advanceTimersByTimeAsync(11_000);
+
+    expect(proc.kill).toHaveBeenCalled();
+    expect(wedgeWarning()?.[2]).toMatchObject({ stderrTail: undefined });
+  });
+
+  it("works when no stderr reader is supplied at all", async () => {
+    vi.useFakeTimers();
+    const adapter = new ClaudeAdapter("stderr-absent");
+    const { proc, endStdout } = createMockProc();
+    adapter.attachStdio(proc);
+
+    endStdout();
+    await vi.advanceTimersByTimeAsync(11_000);
+
+    expect(proc.kill).toHaveBeenCalled();
+    expect(wedgeWarning()).toBeDefined();
+  });
+});

package/server/claude-adapter.ts

@@ -241,6 +241,7 @@ export class ClaudeAdapter implements IBackendAdapter {
    *  must be killed so recovery can proceed). Transport-level noise
    *  (`keep_alive`, `system` status/keepalive) does not reset it; any
    *  substantive turn activity does. */
+  private getStderrTail: (() => string) | null = null;
   private lastInboundWasResult = false;
   /** Timestamp of the last inbound frame of any kind, for the silence probe. */
   private lastInboundAt = Date.now();
@@ -304,10 +305,19 @@ export class ClaudeAdapter implements IBackendAdapter {
        *  `<cwd>/.companion-uploads/`. Optional because tests may construct
        *  without it; the bridge should always pass it. */
       cwd?: string;
+      /** Reads the rolling stderr tail for this session.
+       *
+       *  The launcher already captures stderr to classify exit reasons, but on
+       *  the wedge path — where the process is killed rather than exiting — that
+       *  buffer was never surfaced. It is the only record of what the CLI said
+       *  before it dropped its stdout, so it is the one piece of evidence that
+       *  can explain a wedge rather than just report it. */
+      getStderrTail?: () => string;
     },
   ) {
     this.sessionId = sessionId;
     this.recorder = opts?.recorder ?? null;
+    this.getStderrTail = opts?.getStderrTail ?? null;
     this.onActivityUpdate = opts?.onActivityUpdate ?? null;
     this.sessionCwd = opts?.cwd ?? null;
   }
@@ -489,6 +499,7 @@ export class ClaudeAdapter implements IBackendAdapter {
           sessionId: this.sessionId,
           pid: proc.pid,
           proc: captureProcState(proc.pid),
+          stderrTail: this.stderrTailForLog(),
         });
       } else if (proc && proc.exitCode === null && !proc.killed) {
         // Which grace applies is decided by whether teardown is actually in
@@ -527,6 +538,7 @@ export class ClaudeAdapter implements IBackendAdapter {
               graceReason: this.lastInboundWasResult ? "result" : "descendants_alive",
               teardownOutcome: this.lastTeardownOutcome,
               proc: captureProcState(proc.pid),
+              stderrTail: this.stderrTailForLog(),
             });
             await this.killWithEscalation(proc);
           }
@@ -553,6 +565,7 @@ export class ClaudeAdapter implements IBackendAdapter {
               graceMs: STDOUT_CLOSE_GRACE_MS,
               graceReason: "no_descendants",
               proc: captureProcState(proc.pid),
+              stderrTail: this.stderrTailForLog(),
             });
             await this.killWithEscalation(proc);
           }
@@ -608,6 +621,21 @@ export class ClaudeAdapter implements IBackendAdapter {
     for (const id of results) this.pendingToolUses.delete(id);
   }
 
+  /**
+   * Last few hundred bytes the CLI wrote to stderr, for kill/stall warnings.
+   *
+   * Trimmed and length-capped so a chatty process cannot flood the log, and
+   * omitted entirely when empty so quiet failures stay quiet.
+   */
+  private stderrTailForLog(): string | undefined {
+    try {
+      const tail = this.getStderrTail?.().trim();
+      return tail ? tail.slice(-600) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   private checkSilence(): void {
     if (this.transportKind !== "stdio" || !this.stdioConnected) return;
     if (getSettings().silenceProbeEnabled === false) return;
@@ -628,6 +656,7 @@ export class ClaudeAdapter implements IBackendAdapter {
         turnSilentForMs: now - this.lastTurnOutputAt,
         transportSilentForMs: now - this.lastInboundAt,
         proc: captureProcState(this.stdioProc?.pid),
+        stderrTail: this.stderrTailForLog(),
       });
       this.stopSilenceProbe();
       // Same handoff as the silence probe: relaunch replays the in-flight turn.
@@ -661,6 +690,7 @@ export class ClaudeAdapter implements IBackendAdapter {
           silentForMs: now - this.lastInboundAt,
           probeUnansweredForMs: now - this.probeSentAt,
           proc: captureProcState(this.stdioProc?.pid),
+          stderrTail: this.stderrTailForLog(),
         });
         this.stopSilenceProbe();
         // Hand off to the existing recovery path, which relaunches and replays
@@ -787,6 +817,7 @@ export class ClaudeAdapter implements IBackendAdapter {
       sessionId: this.sessionId,
       pid: proc.pid,
       afterMs: SIGKILL_ESCALATION_MS,
+      stderrTail: this.stderrTailForLog(),
     });
     try {
       proc.kill("SIGKILL");

package/server/cli-launcher.ts

@@ -633,6 +633,8 @@ export class CliLauncher {
     const adapter = new ClaudeAdapter(sessionId, {
       recorder: this.recorder ?? undefined,
       cwd: info.cwd,
+      // Lets the adapter quote the CLI's own stderr in its kill/stall warnings.
+      getStderrTail: () => this.stderrTails.get(sessionId) ?? "",
     });
     adapter.attachStdio(proc);
     companionBus.emit("backend:claude-adapter-created", { sessionId, adapter });