HTTP stale-session reaper may leave the session's proxy worker running (single observation)

[debugmcpdev]

Summary

Low confidence — single observation, filed for the trail. After the Streamable HTTP stale-session reaper (#337) tore down a debug session whose MCP connection had closed, that session's proxy worker process stayed alive (observed minutes later holding its DAP sockets; killed manually).

What was seen

1. An MCP client connected over Streamable HTTP, created a js session, attached to a node --inspect target, then closed its HTTP connection (client exit without close_debug_session).
2. A later client asked about the session: Session not found: 51779093-…, and list_debug_sessions returned [] — so the server did reap it.
3. The session's proxy worker (node, pid 50872) was still running with three ESTABLISHED loopback connections (parent/child DAP sockets), and was still alive several minutes later.

The #337/#343 work made session teardown kill the proxy tree, and the proxy-orphan-reaper covers parentless workers — but this worker's parent (the server) was still alive, so the orphan reaper would not fire; only the reaper-initiated teardown path could have killed it, and apparently didn't.

Caveats

• Not re-reproduced; the same server had an unrelated debugger attached to its main process earlier in the session (see js attach to a Node process that forks children strands those children (second startDebugging target ignored, child waits forever) #501), which may have interfered with teardown timing.
• The worker held no breakpoint state of consequence; impact is a leaked node process + adapter per abandoned HTTP client.

Suggested check

A targeted test: HTTP client creates session + attaches, drops the connection, wait past the reaper interval, assert the proxy worker pid is gone (the #431 process-hygiene suite has the harness pieces).

Scope

Local build @ fix/500-js-attach-unbound-breakpoints, Windows 11, Node 24. Found during the #500 dogfooding session.

[debugmcpdev]

Ran the suggested targeted check on Linux (main @ 9b220a2, Node 22.22.3) — the leak does not reproduce here:

• Server: MCP_HTTP_STALE_SESSION_MS=5000 node dist/index.js http -p 3112
• Client: Streamable HTTP, create_debug_session {language: javascript} + attach_to_process to a running node --inspect target, then process.exit(0) — no detach, no close, transport dropped.
• ~44s later the sweep fired (Reaping stale HTTP session … (idle 44s, no open streams)), and the session's proxy worker exited cleanly (cmd: 'terminate' over IPC → Proxy exited. Code: 0); the vsDebugServer adapter went down with it. Verified by pid (kill -0) on both.

So on Linux the happy path of the teardown chain works. The original observation was Windows — and a code audit of the chain turned up several ways the kill can be skipped without any log line, which may explain a one-off:

1. closeSession skips the kill when session.proxyManager is already cleared (session-manager-core.ts:196). The terminated/exited/error handlers clear the reference and delegate to a fire-and-forget proxyManager.stop().catch(...) (:683-687, :709-713, :924-928); if that in-flight stop stalls or fails, the later reaper-driven closeSession finds nothing to stop and drops the last reference. handleExit (:934-968) clears the reference with no stop() at all.
2. The SIGKILL escalation is a no-op after any earlier signal: stop() guards both the IPC terminate and the force-kill with !process.killed (proxy-manager.ts:415, :431), but Node sets ChildProcess.killed after any delivered signal, not on death. Two paths send a bare kill() earlier (:1033, :1176); after either, the 5s force-kill silently does nothing and stop() resolves with the worker alive.
3. The worker's exit is state-gated: dap-proxy-core.ts:240 exits only when the post-command state is exactly TERMINATED; handleTerminate early-returns when a shutdown is already SHUTTING_DOWN (dap-proxy-worker.ts:1373-1376), in which case no exit is ever scheduled and no further IPC arrives to re-trigger it.
4. Nothing can verify the kill after the fact: IProxyManager exposes no worker-pid accessor, so once the reference is dropped the pid is unrecoverable in-process — and the startup orphan reaper explicitly skips workers whose owner pid is still alive (proxy-orphan-reaper.ts:113), which is exactly the reaped-HTTP-session case (single long-lived server process).

Related field observation from a #501 dogfooding session today: when a proxy worker died to an external SIGKILL, its vsDebugServer adapter survived indefinitely (owner alive → janitor skips it) — same structural hole as (4), different trigger.

Suggested next steps if this stays open: fix (2) by tracking actual exit (exitCode !== null / an exit-latch) instead of .killed; make the cleared-reference paths in (1) await or re-check their in-flight stop; and consider a worker-pid accessor + post-teardown liveness assert in the reaper path so a future recurrence logs itself.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgA5kHzkhFZLqbWNZRTsVG

[debugmcpdev]

Root-caused, reproduced deterministically on Linux, and fixed in #535. The mechanism is one layer below the audit above: the worker loses a shutdown race against itself, and the layers above just fail to notice.

The race. On natural debuggee termination the worker runs shutdown() as a floating promise off the DAP event callback, holding state SHUTTING_DOWN for ≥1s (two 500ms grace waits + adapter tree-kill). The parent reacts to the same terminated event with stop() → IPC terminate, which lands inside that window essentially every time (~7ms reaction vs ~800ms window). handleTerminate early-returns on SHUTTING_DOWN, and the runner's sole exit scheduler — post-handleCommand, state === TERMINATED exactly — sees SHUTTING_DOWN and schedules nothing. The in-flight shutdown later reaches TERMINATED, but nothing re-checks. The worker sits alive forever; on Linux the 5s SIGKILL usually saves it (which is why the reaper-path repro above looked clean), and the audit's items (1), (2) and the stop-free status-driven 'exit' handler are precisely the ways that SIGKILL can be skipped — leaving the observed zombie.

First-try repro on unfixed main (worker log):

21:44:15.058  [Worker] DAP event: terminated              ← floating shutdown() begins
21:44:15.065  [Worker] Already shutting down or terminated.   ← parent's terminate, 7ms later
21:44:15.065  [Worker] Completed command terminate … state=shutting_down   ← no exit scheduled
21:44:15.866  [Worker] Shutdown sequence completed.       ← TERMINATED, alive
21:44:20.064  [ProxyManager] Timeout waiting for proxy exit. Force killing.

The zombie was also inspected live by attaching mcp-debugger to both sides of the bug at once — one session frozen at a breakpoint inside the parent's force-kill timer (freezing the timer holds the zombie open), a second attached to the zombie via SIGUSR1 (idle event loop, IPC pipe only, argv-tagged to the reaped session). Full transcript: docs/case-studies/the-zombie-worker-and-the-frozen-force-kill.md in #535.

Fix (#535): worker latches terminate onto the in-flight shutdown (root cause); stop()/kill() escalation keys on exitCode/signalCode instead of the signal-latched .killed; terminal handlers retain their stop promise and the worker pid (IProxyManager.getProxyPid()), closeSession awaits the pending stop, the status-driven 'exit' now stops the proxy, and a post-close liveness probe logs leaked worker with the pid so any recurrence logs itself. New e2e drives the real reaper path (abandon-without-DELETE → reap → pid dead, no force-kill) — red on unfixed main, green with the fix.

Also the suggested targeted check from the issue body is now tests/e2e/mcp-server-smoke-http-stale-reap.test.ts, using a MCP_HTTP_STALE_SWEEP_INTERVAL_MS override added for testability.

🤖 Generated with Claude Code

https://claude.ai/code/session_018KnLteX47RBLM3ZYF1jGbc