fix(sidecar): a sidecar cannot outlive a parent that died before it started - #113

Problem

44 sidecar processes accumulated on one machine over ~16 hours and had to be reclaimed by explicit PID. They were all bun.exe run <deleted-worktree>/… debug claude-sidecar-entry with ppid 1, sleeping, holding no session database — and unregistered, so resolveOpencodeSender could not resolve them and no peer could address them at all. Pure overhead.

Two independent mechanisms miss them, and neither is accidental:

1. The sweep cannot, by design. sweepStaleSidecars (sidecar-registry.ts:98-126) removes registration files whose process has already exited. It never signals a live process, so it cannot reclaim an orphan.
2. The self-termination guard has a startup blind spot. sidecar-entry.ts:93 compares process.ppid against a value captured at startup, so it only sees a parent that dies afterwards.

Root cause

The blind window is the duration of startSidecar, not an abstract read of process.ppid:

• sidecar-entry.ts:37 — await startSidecar(...), async, writes the registration from inside sidecar-server.ts:156
• sidecar-entry.ts:93 — originalPpid = process.ppid
• sidecar-entry.ts:94 — the poll interval starts

A parent dying anywhere inside that window leaves originalPpid reading as 1, the comparison 1 !== 1 false forever. Two sub-cases, distinguished by whether the registration reached disk:

• dies before the registration write → alive, unregistered: invisible to the sweep, unroutable
• dies after it, before line 93 → alive, registered, still skipped by the sweep

Reproduced before fixing (Bun 1.3.14/macOS): SIGKILL the spawner before the child's first ppid read and the child records ppid 1 and never notices. Two peer sessions reproduced it independently; one narrowed the window to the above, which corrected my original description.

Fix

Exit on stdin EOF. The parent's pipe closes when the parent dies, at any point in the sidecar's life, so this covers both sub-windows — including the one where originalPpid is captured already-reparented. The ppid guard stays as a second net.

The discriminator is isSocket(), not isFIFO(). Measured on Bun 1.3.14: a child spawned with stdio: ["pipe"] reports isSocket()=true, isFIFO()=false (mode 140000), while stdio: "ignore" reports isCharacterDevice()=true (/dev/null). My first attempt checked isFIFO(), which reads as correct, matches nothing in production, and leaves the guard dead — caught by the failing test, not by review. The check exists at all because every test spawns with stdio: "ignore", where stdin reads EOF immediately and an unguarded listener would kill a healthy sidecar on startup.

Bound stop(). shutdown() set shuttingDown before awaiting sidecar.stop(), so a stop that never settled left the process alive with every later SIGTERM swallowed — killable only by SIGKILL. The exit now happens on a timer rather than on stop() settling.

Verification

• New test observed red with the guard disabled, green with it restored.
• The race test retries rather than asserting once: hitting the window depends on bun's startup time, so an attempt where the sidecar never registered proves nothing and is discarded. It only passes having observed a registration appear and then disappear, so it cannot pass vacuously.
• test/peer 211 pass / 0 fail. Typecheck clean. openspec validate passes. fork:verify 251/251 owned, 117/117 patched — and it correctly failed on the new test file until it was committed.

Not in this PR

Reclaiming sidecars already leaked elsewhere, and the operator command to do it — separate tasks in the change. Prevention alone does not reclaim existing leaks; both peers agreed on that split, and the boot sweep stays non-signalling.

One path is mitigated but not confirmed: shutdown()'s stop() never settling was reported by reading, not reproduced. Treat the timer as mitigation rather than a proven fix.

🤖 Generated with Claude Code