[debugmcpdev]

M2 of the session tree (design, #1082), first of two PRs: with autoAttachChildProcesses: true, every Node process js-debug reports after the program's own target becomes a child debug session — a fork(), a spawn(process.execPath, …), a cluster worker, a grandchild — through the mechanism M1 built for debugpy (#1081), instead of being released to run undebugged (#501). The second PR flips the launch and attach defaults, adds the attach/cluster/cascade suites and rewrites the attach smoke and the docs sweep; it closes #1082.

The rule

In a js-debug worker the root connection's first report is the program, adopted in-session by ChildSessionManager as before (the #704 launch-ready signal). Every other report, on any connection, is a child report: held by ChildConnections, adopted as a child session on a fresh connection to the same js-debug server, or released by a throwaway attach. Every non-root connection runs the child-safe policy, so no connection but the root ever builds a manager.

What js-debug's measured shapes change (docs/javascript/spike-notes-forks.md)

• Where reports arrive. A fork is reported on the program target's connection (the manager's private client), a grandchild on the fork's. The manager relays a held request as childReport, naming the connection it must be answered on; MinimalDapClient hands it to the root's holder (child-report now carries the origin client).
• The release lever. Every M1 release path answered the request success: false, which parks a js-debug child forever. A js-debug report is now acked the moment it is held (the ack decides nothing) and never answered again; release opens a fresh child-safe connection and runs js attach to a Node process that forks children strands those children (second startDebugging target ignored, child waits forever) #501's sequence (src/proxy/throwaway-release.ts: initialize → configurationDone → attach { __pendingTargetId, continueOnAttach: true } → ready signal → disconnect with the target kept, 20 s cap). A process the released child reports in that window is held on the session the released child was reported on. An adoption that fails lets the child go the same way (the server's release command that follows would find the report already taken).
• The attach body. The contract gains readChildReport (the design's "report recognition" member) and a root config for buildChildAttachArguments; js-debug's is the measured second-connection body, an attach root's forwardable extras riding along (adapterConfig: unknown keys are accepted silently — a typo of a supported key (pathMapping vs pathMappings) gets no warning #466), a launch root's keys never.
• Nested managers. ChildConnections.adopt built its clients with the raw policy, which for js-debug would construct a ChildSessionManager + CDP bridge per fork connection; createChildSafePolicy (its own module now) is what every non-root connection runs, and it reads every report through the contract.
• Output. childOutput: 'launch-session' gets its consumer: a launch child's get_output and output resource answer outputOn: <root id>, preserving any child-local diagnostics. Children under an attach root retain their own console output, measured against js-debug v1.140.0.
• Close. closeChild: 'release' shapes the close itself: a js child's connection closes with terminateDebuggee: false (either flag leaves the target running, measured) and the answer says released: true, in the root's cascade as well.

Measured in this PR (the fact M2 owed the design doc)

An adopted js-debug child, paused on a breakpoint, does not survive its parent's exit: its terminated arrives the moment the parent exits (no exit code), the child row goes stopped, the root ends with its own exit code. The launch owns the tree, as the spike found for unreported children. Lifecycle row 2 and the Exit section of the design doc now say so; the JavaScript README tells the agent to keep the parent alive while inspecting a child.

Also measured: logpoints set on the parent carry into a fork and print into the launch session's output; function breakpoints do not carry (they are armed over CDP on the program's own target) — documented, a follow-up if wanted.

Release and output hardening

Throwaway releases handle socket errors and closure throughout the handshake, capture ready events before the attach response, and stop sending requests after their deadline. The worker tracks release connections and drains them before root disconnect or shutdown, including reports arriving during release; JavaScript gets 25 seconds of worker-exit grace to cover the 20-second release deadline and cleanup. Regression tests cover these failure and shutdown paths, attach-child output, and output-resource diagnostics. Fork logpoints use a console.log fallback; replacing it in the child can suppress those messages, now documented.

Evidence

• tests/adapters/javascript/integration/javascript-subprocess-tree.test.ts (seven cases on the shipped server over stdio, real js-debug v1.140.0, runs in build-and-test on both OSes): the designed flow (breakpoint in child.js only; the root's wait answers the fork's three stops with its sessionId and children; outputOn; the root ends 0), the grandchild chain (three rows, the grandchild under the fork, both waits report it), closing a paused fork (released: true, it runs on), restart (childrenClosed: 1) and root close, cap 0 (program adopted, fork released by the throwaway attach, childrenReleased: 1), the parent-exit measurement, the logpoint.
• Unit: the contract test pins js-debug's contract with per-engine report fixtures and allows the one policy whose program is itself a pending target to combine the contract with in-session adoption; ChildConnections under the throwaway lever (hold acks once, adopt never answers again, release and the safety timer run the throwaway on a child-safe client, a report in the release window, a relayed report answered on its origin, failure and shutdown paths); the relay in the manager and the client; releaseByThrowawayAttach; the session layer's released close and outputOnFor; the get_output pointer.
• tests/e2e/mcp-server-smoke-javascript-attach.test.ts run locally (it is not in CI): all ten rounds pass, the two js attach to a Node process that forks children strands those children (second startDebugging target ignored, child waits forever) #501 fork rounds included — with the key opted in, forks are now adopted and still complete their handshake under continueOnAttach, and detach_from_process releases them.
• Local gates on 6b21788d: lint, typecheck:all (zero errors), clean build, personal-path audit, check:docs (150 files), and changelog:check passed. The required pre-push run passed 408 unit files (8,159 tests, 5 skipped) and 31 integration files (149 tests, 1 skipped).

Not in this PR

• The default flip (autoAttachChildProcesses on launch and attach, the schema text and its 24 snapshots), the attach suite on examples/javascript/fork_attach_target.js, the cluster and cascade suites, the e2e attach smoke expecting adoption, the docs sweep (docs/tool-reference.md, the skill references, README.md's stale "not yet shipped" line) and the changed entry: the second PR.
• ChildSessionManager.releaseUndebugged is unreachable for js-debug after this and stays as the manager's own invariant; removing it (and its tests) is a small follow-up.

Part of #1005. Design: docs/architecture/session-tree.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_015BDrn6AsHQ4rmTXFHzQkn8

[codecov]

Codecov Report

❌ Patch coverage is 98.08612% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/proxy/child-connections.ts	96.77%	2 Missing ⚠️
src/proxy/child-safe-policy.ts	95.23%	1 Missing ⚠️
src/session/session-manager-core.ts	92.30%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!