fix(#513): make pause_execution land on attached idle Node servers

[debugmcpdev]

Fixes #513: on a js attach session against an idle Node server, pause_execution returned pending:true and the stop never landed — even once the target provably executed JavaScript. Root-caused by attaching mcp-debugger to a live mcp-debugger server and reading the adapter's own CDP/DAP trace (adapterConfig: {trace: true}); full narrative coming as a case-study docs PR.

Root cause (three distinct holes)

1. js-debug's smart-stepper eats user pauses on idle servers. A pause that lands on a blackboxed/unmapped frame is converted into an auto-step; on a mostly-idle server every frame the pause can land on is one (node internals / no-URL frames), so it steps forever at ~43ms per CDP round-trip — observable as a flood of continued events with zero stopped. Its >256-step failsafe switches to step-out, which never escapes an idle event loop. js-debug exempts breakpoint/exception/entry stops but not pause — which is exactly why the set-a-breakpoint workaround in the issue always worked. launchConfig.smartStep defaults true; our launch transform pins it, our attach transform never mentioned it.
2. A pause dispatched mid-adoption is swallowed without a response. The child DAP connection exists (and activeChild is set) before its attach {__pendingTargetId} binds it to the target; a request written in that window gets no response from js-debug, ever. Interactive repro can't hit this (~200ms window vs seconds between tool calls) — the new e2e's back-to-back calls hit it every time.
3. A pause with no child to run against fell through to the js-debug root session, whose handler is async () => ({}) — success, no CDP Debugger.pause, no stop possible. The tool then reported pending:true forever, which is the contract promising something that cannot happen.

Fix

• js attach defaults smartStep: false (caller value wins via adapterConfig, same pattern as fix(#501): stop stranding forked children of js attach targets #514's autoAttachChildProcesses; launch unchanged). Pause now lands truthfully — at an internal frame if that's where the VM is, exactly like an IDE pausing an idle server.
• New policy vocabulary DapClientBehavior.childRequiredCommands (js: {'pause'}) — commands the parent is known to no-op. MinimalDapClient.sendRequest gates them on ChildSessionManager.getChildTargetState() ('active' | 'adopting' | 'ended' | 'none'): waits for adoption to complete (not merely for an activeChild reference), grants a short grace for the attach → reverse-startDebugging race, and otherwise throws a shared "no debug target" error instead of falling through to the parent — including when the child dies mid-dispatch. threads deliberately keeps its parent fallback (the attach verify loop depends on it).
• pause() surfaces the no-target error as a structured {success: false, error} (matching the Cannot pause in state: shape), and the deliberate retention of pausePending across the pending-timeout settle is documented (the late-landing stop must normalize to 'pause'). Tool description now names the failure mode.

Verification

• Live before/after against node --inspect dist/index.js http: pre-fix pending forever (512-continued-event step chase in the trace); post-fix immediate paused with stopReason: 'pause', and on a truly idle target pending:true that lands the moment JS runs — with a working stack trace / evaluate_expression / continue cycle.
• First-ever test coverage for pause on js attach: unit coverage of the child-vs-parent dispatch gate in MinimalDapClient.sendRequest (7 cases incl. the netcoredbg/Java regression guard: policies without childRequiredCommands keep the old fallback), getChildTargetState() lifecycle, pause() structured failure, adapter transform defaults; two e2e cases against a new zero-timer HTTP fixture (examples/javascript/idle_server_attach_target.js) — the js attach: pause_execution stays pending forever on an idle Node server — the stop never lands even once JS runs #513 regression (pending pause must land when JS runs; the /work request itself hangs because the pause fires mid-request, which is the point) and a busy-target pause-within-grace smoke.
• Full unit suite (4227), full js attach e2e (8/8), js launch e2e smoke, lint — all green.

Side findings from the investigation filed as #518 (DAP trace lacks a parent/child discriminator), #519 (routing-layer logs invisible in the per-session proxy log), #520 (ensureInitialStop burns 12s of threads polling on every js attach).

🤖 Generated with Claude Code

https://claude.ai/code/session_01XtvNu3aNB1nw1URRL5UTgR

[codecov]

Codecov Report

❌ Patch coverage is 97.29730% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/proxy/minimal-dap.ts	95.83%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!