fix(pty): reap process trees orphaned by an abnormal exit (#139) - #140

Closes #139.

What actually goes wrong

killAll() is reachable from exactly one place — app.on('will-quit') — and that does not run when the process dies abnormally. Windows does not tear down a process tree when its root dies, so a crashed wmux leaves every pane's shell resident, along with the agent under it and each of that agent's MCP servers. Restoring the session then spawns a fresh set beside them, so a crash-loop multiplies processes instead of replacing them. Six crash cycles is how the reporter reached 251 node.exe / 3.3 GB.

The tree-kill itself was never the problem: PtyManager.kill() has done taskkill /PID <pid> /T /F since #65, precisely because Claude Code's backend orphans otherwise. Every caller just required wmux to be alive and cooperating to reach it.

The fix

A ledger of spawned PIDs under APPDATA. Each spawn appends, each kill removes, killAll() clears. The next launch claims the file and reaps whatever a dead owner left behind.

On not killing the wrong process. This list feeds taskkill /T /F, so a stale entry whose PID has since been recycled would kill an unrelated process and its children. A recorded PID being alive is therefore not evidence that it is ours. Before killing anything, each PID is re-queried through Win32_Process and must still match the image name and the creation time recorded at spawn. Every failure path — no PowerShell, a query error, unparseable output — reaps nothing: leaking a process is recoverable, killing the user's editor is not. selectOrphans() is pure so those rules are tested without spawning anything.

Two smaller notes:

• The ledger is injected into PtyManager rather than constructed inside it. The pty tests spawn real shells, and must not overwrite the ledger of an instance the user has running on the same machine.
• takeOver() returns nothing when the recorded owner is still running — those PTYs have a live parent and are not orphans.

Also: two hook lifetimes

Found while chasing the same symptom, in wmux-hook.js:

• The 1s stdin fallback timer was never cleared, so every hook process stayed resident for a full second even when its work finished in ~90 ms. Claude Code fires one per tool call, per pane. Measured 1049 ms → 101 ms.
• The reply was never read. On Windows named pipes end() tears the connection down, but a paused socket has no queued read, so the EOF never surfaces to JS — 'end' and 'close' never fire. resume() makes the close observable and deterministic.

A 5s connect deadline matching the CLI's sendV1/sendV2 is added as a backstop. It is explicitly not a fix for an observed hang — measured against absent, responsive and wedged servers, the hook exits on its own in all three. I had assumed a hang and the measurement disproved it; the comment says so rather than claiming otherwise.

Verification

tests/unit/pty-ledger.test.ts — 22 cases, weighted toward what must not be killed: recycled PID under a different image, recycled PID outside the creation-time window, malformed ledger entries, a live owner. Plus a live Win32_Process probe of our own PID, which is what proves the PowerShell command string quotes correctly.

Beyond the suite, exercised against real process trees (two cmd.exe → ping trees, one recorded truthfully, one recorded under a wrong image):

PASS  recorded tree root killed
PASS  recorded tree GRANDCHILD killed (the MCP-server case)
PASS  image-mismatched tree root SPARED
PASS  image-mismatched tree grandchild SPARED
PASS  ledger now owned by this process

And the hook, pre-fix vs post-fix:

server shape    | before (HEAD)      | after (fix)
----------------+--------------------+------------------
absent          | 43ms               | 40ms
responsive      | 1044ms             | 100ms
wedged          | 1051ms             | 99ms

Full suite: 62 files, 689 tests passing. npm run typecheck clean; npm run lint unchanged from master (31 problems before and after, none in the touched lines).

What this does not fix

The crash itself. Six .dmp files means a native crash, and I have no way to diagnose one without them — asked for them on the issue. This change makes a crash survivable rather than cumulative; it does not stop it happening.