feat: restart_debugging — one-call relaunch with breakpoints re-applied + fix live-proxy relaunch destroying the session (fixes #238)

[debugmcpdev]

Closes #238. Completes the cluster:breakpoint-tooling trio (#267 → #268 → this).

The edit-rerun loop — fix a line, rerun to the same breakpoints, confirm the state changed — was 4+ calls with breakpoint state lost (close, create, re-set every breakpoint, start). It is now one call.

restart_debugging {sessionId}

Terminates the current debuggee (if any) and replays the last real launch with the identical configuration — effective script path, args, dapLaunchArgs, adapterLaunchConfig, raw breakOnExceptions (policy defaults re-resolve on replay). Breakpoints re-apply automatically via the existing initialBreakpoints snapshot (#267 keeps their verified state honest). The response mirrors start_debugging plus data.breakpointsReapplied and data.outputReset: true — each launch starts a fresh output buffer, so read get_output from since: 0.

Design choices (per the planning session):

• Terminate+relaunch uniformly. No adapter advertises native DAP restart, and the DAP spec explicitly blesses the emulation — so every launch-mode language works with zero per-adapter wiring. Native restart stays a future optimization.
• Works after exit — the primary use case. The server tool deliberately skips validateSession's TERMINATED rejection (same precedent as get_output); a finished session restarts without being recreated.
• Guards: attach sessions (no launch config to replay — detach/re-attach instead), never-launched and dry-run-only sessions, reentrant restarts, and INITIALIZING starts are refused with specific errors. ERROR state is allowed — relaunch-after-crash is a recovery path.
• No per-restart overrides (v1) — different config = start_debugging, which itself now works correctly on a live session (below).
• A launch now clears the sticky attachMode flag, so an attach-then-launch session doesn't wrongly refuse restarts forever.

🐛 Fixed: the session-destroying relaunch landmine

start_debugging (and attach_to_process) on a session with a live proxy called closeSession — which removes the session from the store — and then updated state on the removed session. Net effect: calling start_debugging on a paused session silently destroyed it and reported a bogus "Session not found". Zero test coverage (both existing "restart works" tests used dead proxies).

Both paths now use a new session-preserving stopProxyPreservingSession helper (listeners detached, worker stopped, adapter-registry slot released — repeated restarts can't exhaust the 10-instance cap), and the relaunch proceeds normally. The per-launch reset also clears breakpoint verified/message/adapterId, since a new adapter instance has verified nothing.

Tests

• New session-manager-restart unit suite: replay fidelity (same script/args/config + breakpoints in the snapshot), the landmine regression (restart-while-paused keeps the session), per-launch verified reset (observable via a launch that dies mid-start), and every guard incl. concurrency. The old coverage test that asserted closeSession gets called now pins the session-preserving behavior instead.
• Server handler suite: TERMINATED sessions restart; refusals surface as {success: false}; unknown session/missing param errors.
• E2E tests/e2e/mcp-server-smoke-restart.test.ts across all 8 languages (toolchain-skip): pause at breakpoint → restart while paused (landmine path) → same breakpoint hits again → bounded-continue to completion → restart from TERMINATED → breakpoint hits again without re-issuing set_breakpoint → fresh get_output. 8/8 pass locally (rust/win32 uses the documented Rust/Windows: continue_execution re-stops at the same breakpoint (never advances without a step_over) #255 step_over workaround). Attach rejection asserted live in the python-attach e2e.
• Dogfooded via the dev proxy: a finished Python session restarted in one call and paused at the re-applied breakpoint with breakpointsReapplied: 1, outputReset: true.

Docs

tool-reference section (+ TOC), README table, CLAUDE.md tool list (25 → 26), usage.md, both skill copies (the root-cause recipe's "fix, then re-run" step now names the tool), error-messages.ts's timeout advice points at the real tool, CHANGELOG Added + Fixed.

🤖 Generated with Claude Code

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
src/session/session-manager-core.ts	75.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!