fix(launch): a noDebug launch says what it did to the debugger instead of blaming the breakpoints (#710)

[debugmcpdev]

Closes #710.

What

dapLaunchArgs.noDebug: true is DAP's "launch without enabling debugging". Where the adapter honours it, no breakpoint binds, no exception filter arms, and no stop ever arrives — and the session read as a mystery: a short script ended stopped carrying the #467 warning ("check the file path and line") for breakpoints that were never going to bind; a server stayed running with no warning while the caller waited for a stop that could not come.

start_debugging now says what the flag did. Where the debugger is off and the caller asked for a stop:

dapLaunchArgs.noDebug is true, so the debugger is disabled for this launch and no stop can arrive:
2 breakpoint(s), 1 function breakpoint(s), breakOnExceptions='all' and stopOnEntry will not fire.
Drop noDebug to debug, or ignore this if you only meant to run the program

Where the adapter ignores the flag:

dapLaunchArgs.noDebug has no effect with the ruby adapter: the debugger stays on, and breakpoints,
breakOnExceptions and stopOnEntry work as usual

The premise was wrong, so it is now measured

The issue (and the first version of this PR) assumed every adapter honours the flag. The /code-review on the first commit checked the sources, and a live probe of every adapter (set a breakpoint, launch with { stopOnEntry: false, noDebug: true }) gave the full picture:

adapter	flag reaches the adapter	honours it	today
javascript (js-debug)	yes (#706)	yes	runs to completion, stopped, exit 0
python (debugpy)	yes	yes	launch fails at init — #746
go (Delve)	yes	yes	program ran, no initialized, init failure — #746
cpp (CodeLLDB)	yes	yes, by refusing	"Not supported in noDebug mode" → launch error — #746
rust (CodeLLDB)	no — the launch transform builds from a fixed key set	—	paused at the breakpoint
ruby (rdbg)	yes	no (server_dap.rb never reads it)	paused at the breakpoint
dotnet (netcoredbg)	yes	no	paused at the breakpoint
java (JDI bridge)	yes	no (JdiDapServer.java never reads it)	debugger on
mock	yes	no	paused at the breakpoint

So the first version's warning was false for half the languages — and worse, it suppressed the accurate #467/#308/#469 diagnostics for them. The redesign:

• AdapterPolicy.honoursNoDebug (beside the functionBreakpointsBindLate precedent), true for javascript/python/go/cpp and unset elsewhere, pinned per language in tests/unit/shared/adapter-policy-contract.test.ts so a policy cannot start or stop claiming it silently. The four trues carry a comment saying what was observed.
• The launcher resolves noDebug the way the adapter will see it — adapterLaunchConfig over dapLaunchArgs over the server defaults, the proxy launcher's merge order — and decides debuggerOff = noDebug && honoursNoDebug. Only that gates the suppression of the breakpoint-shaped warnings.
• Where the flag is ignored, the caller is told it had no effect and the usual diagnostics stay.

Design decisions kept from the first round

• Seam: the launcher, not handler intake. restart_debugging replays session.lastLaunch through the private DebugLauncher.launch() and never touches normalizeStartDebuggingArgs, so an intake-only warning could never fire on the restart where breakpoints were added after the launch. In the launcher the breakpoint stores, the caller's breakOnExceptions, the launch config and the policy are all in hand, and data.warning already lifts into the top-level warning for start and restart. dryRunSpawn carries it too — a configuration check should say so.
• Trigger = something the caller asked for: line or function breakpoints, an explicit breakOnExceptions other than none, or stopOnEntry. The effective exception mode is deliberately not used — the policy default is uncaught almost everywhere and would make every bare noDebug run warn. (defaultDapLaunchArgs merges later, so stopOnEntry at this seam is the caller's value.)
• It replaces, not joins, the breakpoint-shaped warnings (Function breakpoints: no feedback when a name never binds (Go bare "main" silently never fires) #308 "check the symbol name", Breakpoint-binding failures are under-surfaced: start_debugging hides unbound breakpoints, and known-never-bind function breakpoints are still accepted #467 "check the file path and line", Ruby logpoints silently become pausing breakpoints; list_breakpoints then reports verified:true with the logMessage intact #469 "will PAUSE") when the debugger is off: each diagnoses a symptom of this one cause. Adapter notices (Docker: Rust type summaries unavailable (no rustc in image) — &str/String render as raw LLDB internals #441) still join; the start_debugging: a launch that runs to completion without ever stopping reports a bare state: "stopped" — say the program exited and name the verified breakpoints that were never hit #701 run-to-completion summary stays.

Also from the reviews (two rounds)

• With the debugger off, stopOnEntry is neutralized once, for everything that reads it. stopOnEntry: true + noDebug: true used to sit on the 30 s readiness ceiling. The first fix (a readiness-only view plus a post-hoc RUNNING projection) was shown to be inert for python/go/cpp — their isSessionReady is state === PAUSED, they always request an entry stop and auto-continue — and racy for js-debug, whose adapter-configured fires before the readiness listener exists while the core still withheld RUNNING under the caller's value. Now the launch args handed to the proxy, the handshake and the readiness wait carry stopOnEntry: false, the readiness policy drops its pause-only predicate (running is ready), and the core's own projection does the rest; session.lastLaunch and the warning keep the caller's value. Both band-aids are gone.
• noDebug and stopOnEntry are resolved the way the adapter sees them (adapterLaunchConfig over dapLaunchArgs, over the server defaults for noDebug) and by truthiness — the proxy forwards a string 'true' verbatim and js-debug gates on truthiness.
• A launch that fails under the flag (debugpy/Delve/CodeLLDB today — noDebug launches never complete proxy init on python and go (no initialized event) and error on cpp (CodeLLDB refuses configuration in noDebug mode) #746) carries a noDebug note in its data, so the caller sees the flag before retrying paths and ports. The note states the fact and the remedy ("the debugger was off; if the failure is unexpected, drop noDebug") without asserting the flag caused a failure it cannot attribute — a bad scriptPath under noDebug is still a bad path.
• A stop that lands before the launch reports outranks the static policy pin (an adapter build that ignores the flag after all): the ordinary diagnostics stay and the note says the flag had no effect. A stop that lands after the launch answered is noDebug sessions: set_breakpoint, list_breakpoints, pause and inspection still explain themselves in debugger terms after a debugger-off launch #749's territory.
• Logpoints are counted apart from breakpoints (the run-to-completion summary already distinguishes them); the builder takes ExceptionBreakMode; tests build real Breakpoint maps; the two dry-run payloads collapse into one helper; setMockProxyRunning moves to session-manager-test-utils.ts; the redundant second policy lookup reads the hoisted one.
• Third round: a pause that came anyway counts as ready (it had fallen to RUNNING-only); an entry stop the core already resumed counts as evidence of a wrong pin (firstStopHandled); stopOnEntry is neutralized in adapterLaunchConfig too (it wins the adapter merge — the worker and the js child adoption would still have waited on it); the worker's js-debug function breakpoints via the CDP proxy (revives #282 by another route) #295 stopOnEntry force for pending CDP function breakpoints yields to an honoured noDebug; attach-shaped start_debugging is left alone (noDebug is a launch-request property); a bare noDebug launch that fails carries a note even with nothing armed, and every failure return carries it; 'true'/'false' strings are read the way the proxy parser coerces them; the server-defaults source is dropped (they are typed stopOnEntry/justMyCode only); the texts name the flag alone since either source may have carried it.
• Declined: recording the decision on the session for downstream surfaces (set_breakpoint, list_breakpoints, pause_execution on a noDebug session) is the right next step but a separate change — noDebug sessions: set_breakpoint, list_breakpoints, pause and inspection still explain themselves in debugger terms after a debugger-off launch #749. breakpointsReapplied on restart keeps its documented meaning (breakpoints re-sent); the warning beside it says they will not fire.

Changes

• packages/shared/src/interfaces/adapter-policy.ts + the js/python/go/cpp policies — honoursNoDebug.
• src/session/breakpoints/launch-warnings.ts — buildNoDebugLaunchWarning, pure, two texts.
• src/session/launch/debug-launcher.ts — resolveLaunchFlag, the policy-gated decision, the neutralized launchArgs/readinessPolicy when the debugger is off, failureData, dryRunResult; operations-context.ts gives the launch slice defaultDapLaunchArgs.
• src/server/tool-schemas.ts (+ the 24 tool-list snapshots), docs/tool-reference.md, changelog.d/710.fixed.md — say which adapters do what.
• Tests: builder (10), launcher wiring on the mock-proxy harness (honouring via a policy override on the facade seam, ignoring via the mock's real policy, adapterLaunchConfig as the source and as the override, readiness with the real event order and with a pause-only policy, string-typed flag, failed launch, a stop that arrived anyway, dry run, restart, string forms, attach-shaped, bare failed launch, resumed entry stop — 18), the policy contract pin, and two e2e cases in tests/e2e/mcp-server-break-on-exceptions.test.ts: js-debug (honours: success, warning, no Breakpoint-binding failures are under-surfaced: start_debugging hides unbound breakpoints, and known-never-bind function breakpoints are still accepted #467 text, stopped/exit 0 — fails on main's build with exactly the issue's symptom) and the mock adapter (ignores: "no effect", still paused at the breakpoint).

Verification

lint, typecheck:all, changelog:check, check:docs clean; tests/core/unit/session + tests/core/unit/server + tests/unit/shared: 102 files / 1840 tests (session, server, shared, proxy). CI does not run the e2e project, and the worker change sits on the js function-breakpoint path only e2e drives, so tests/e2e/mcp-server-smoke-js-function-bp.test.ts + the full tests/e2e/mcp-server-break-on-exceptions.test.ts (26 tests) were run locally against the rebuilt dist — green; the readiness and merged-source wiring tests each fail when their fix is disabled; pre-push gate passed.

Follow-ups filed: #746 (python/go/cpp launches fail under noDebug — matrix attached), #749 (downstream surfaces).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!