fix(#501): stop stranding forked children of js attach targets

[debugmcpdev]

Fixes #501.

What

Attaching a javascript debug session to a Node process that fork()s children left those children permanently wedged: js-debug's pwa-node attach defaults inherit autoAttachChildProcesses: true, so the auto-attach bootloader was injected into the target; every fork parked under waitForDebugger and sent a startDebugging reverse request that the single-child ChildSessionManager silently dropped. The child's main module never ran.

Two complementary fixes:

1. Default autoAttachChildProcesses: false on the js attach path (transformAttachConfig, mirroring launch mode; defensive normalization in performHandshake for embedders). Caller-overridable via adapterConfig — a supplied boolean is respected, never silently overwritten (cf. ruby attach across a container boundary can bind no breakpoints: localfs is silently overridden, localfsMap is inert #499) — and the key is now in supportedAttachKeys so opting in doesn't trip the unrecognized-key warning (adapterConfig: unknown keys are accepted silently — a typo of a supported key (pathMapping vs pathMappings) gets no warning #466 mechanism).
2. Release instead of drop. An unadoptable startDebugging target is now released to run undebugged: a throwaway MinimalDapClient performs the minimal unpark sequence verified against the vendored bundle (initialize → configurationDone → attach {__pendingTargetId, continueOnAttach: true} → ready-signal grace → disconnect {terminateDebuggee: false}), bounded at ~20s, never touching adoption state, with a loud warning. createChildSession now reports 'adopted' | 'duplicate' | 'released' | 'release-failed'; MinimalDapClient rolls back its adoptedTargets only on 'release-failed' (parity with the js-debug: failed child adoption is unretryable (pendingTargetId never removed from adoptedTargets) #249 rollback) so a re-sent request can retry — released targets stay recorded, since their server-side deferred has settled and can never be adopted.

Two findings from validating against the real stack:

• js-debug delivers fork auto-attach requests on the adopted child's connection, not the parent's (server log: 23 startDebugging received, 1 adoption, 0 releases). The child-safe policy now forwards unadoptable targets back to the owning manager for release instead of squashing them.
• The cycle-breaking dynamic import('./minimal-dap.js') is now cached in a module-level promise: an adoption racing a release issued two concurrent import() calls, which vitest's module mocker can resolve inconsistently (one caller received the real module, the other the mock).

Testing

• New fixture examples/javascript/fork_attach_target.js: forks a child every 2s; each child announces itself over IPC and the parent logs child-handshake N — the ProxyManager fork + init-ACK shape.
• E2E (mcp-server-smoke-javascript-attach.test.ts): forks keep completing their IPC handshake while attached with default config (direct js attach to a Node process that forks children strands those children (second startDebugging target ignored, child waits forever) #501 regression), and with autoAttachChildProcesses: true the release path frees every unadoptable fork while parent debugging stays intact. Full suite: 6/6.
• Unit: the test that pinned the silent-drop behavior now asserts the release sequence; new coverage for release-after-adoption, duplicate, release-failure retry, hung-release bounding, no breakpoint mirroring to release clients, grandchild forwarding, transform/handshake defaults, and adoptedTargets retention/rollback.
• Live dogfood: with this + ProxyManager loses a late init ACK: any worker boot >500ms fails the whole launch as 'Failed to initialize proxy after 6 attempts' #512, an mcp-debugger instance attached to a live mcp-debugger server (node --inspect … http) no longer breaks the subject's ability to fork proxy workers — 6/6 clean attach→drive→detach stress cycles (0/6 before). Case study PR to follow.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgA5kHzkhFZLqbWNZRTsVG

[codecov]

Codecov Report

❌ Patch coverage is 91.76471% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/proxy/child-session-manager.ts	94.52%	4 Missing ⚠️
src/proxy/minimal-dap.ts	50.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!