fix(proxy): a noDebug launch completes without waiting on a configuration phase the adapter never opens (#746)

[debugmcpdev]

Closes #746.

What was wrong

A noDebug launch on an adapter that honours the flag (#710: python, go, cpp — js was the one working case) could never succeed. The proxy worker's configuration phase (setBreakpoints → setFunctionBreakpoints → setExceptionBreakpoints → configurationDone → adapter_configured_and_launched) runs off the adapter's initialized event, and:

• debugpy and Delve — correctly, per DAP — send no initialized when they are not debugging. The worker never reported configured, ProxyManager.start() never resolved, and the launch died as Proxy exited during initialization. Code: 0 for a short script (it had run and exited 0) or the 30 s init deadline for a server. On go the two-phase path burned its 2 s + 10 s waits first.
• CodeLLDB does send initialized, then refuses what is sent in the phase (Internal debugger error: Not supported in noDebug mode.) → Error in DAP sequence → shutdown.

Measured before writing code, with DAP_TRACE=1 and a raw DAP probe against CodeLLDB: it withholds the launch response until configurationDone; it refuses setBreakpoints but accepts configurationDone and then launches; without configurationDone nothing ever happens (12 s silence).

What changes

Under an honoured noDebug — the launcher's decision (debuggerOff = noDebug && honoursNoDebug, #747), now stamped once on the init payload (ProxyConfig.debuggerOff → ProxyInitPayload.debuggerOff, parser-validated) so the worker never re-derives it from a launch config an adapter transform may have reshaped; attach never carries it — the worker stops waiting on and stops dying on the configuration phase, but does not pre-empt the adapter:

• the launch is reported configured on the launch response (completeDebuggerOffLaunch), and the go/java two-phase waits are skipped — both are pure delays when no initialized is coming;
• if the adapter opens a phase anyway, the normal phase runs unchanged (breakpoints, exception filters, configurationDone, breakpoints_synced echo): the adapter's own answers stand, and a stale pin for some adapter build self-corrects (its breakpoints bind, its stops arrive) instead of the program running free;
• only the failure policy changes, and only for a request the adapter answered with an error (DapResponseError, which MinimalDapClient now rejects with — a transport failure, timeout or shutdown is still a broken session): the refusal is forwarded, configurationDone is still sent so the phase the adapter opened is closed (CodeLLDB releases the launch response on it), and the session carries on — unless it is already shutting down;
• markConfiguredAndLaunched makes the CONNECTED transition + readiness status fire once, from INITIALIZING only, since under the flag the launch response and the end of a phase both reach it — a phase pending from the handshake, or one in flight when the launch response lands (CodeLLDB answers launch before its configurationDone response), closes first, as in debug mode;
• a terminal DAP event (terminated, exited, adapter exit, socket close — all four go through enqueueTerminalSignal) waits, bounded by the slot's 2 s backstop and contained, for the launch outcome (settleDebuggerOffLaunch) and then only marks configured: a phase still pending from the handshake is dropped, one in flight is left to finish, and no phase is ever opened from a terminal slot against a program that has ended. The handshake's own completion checks a synchronous terminalSignalArrived flag before opening one. This closes the tick-count race (initialized and terminated in one socket read) that could regress to "Proxy exited during initialization";
• every refusal — setBreakpoints, setFunctionBreakpoints, setExceptionBreakpoints, configurationDone — is forwarded to the caller in the adapter's own words: worker adapter_notice status → ProxyManager adapter-notice event → recorded like a Docker: Rust type summaries unavailable (no rustc in image) — &str/String render as raw LLDB internals #441 policy annotation (launch warning + [mcp-debugger] Warning output entry), through the same [FEATURE] Secret redaction + least-privilege variable inspection #237 write-time redaction as every other buffer entry, with the listener contained like the output path. A refused setBreakpoints is also echoed per breakpoint: the file groups the adapter already answered are echoed as they came (verified, adapterId), only the unanswered ones are stamped verified: false with the refusal as message, so list_breakpoints shows what the adapter actually said. A refused setFunctionBreakpoints gets the same function_breakpoints_synced echo;
• the launcher's post-launch resyncAll is gated on !debuggerOff: CodeLLDB has already answered in the phase, debugpy/Delve open no phase, and resyncAll discards the answer anyway (measured: debugpy says Server is not available to a post-launch setBreakpoints, and nothing kept it) — the round trips bought nothing. Follow-up breakpoints: a failed live setBreakpoints re-send never stamps the adapter's answer onto the records #754 asks for live-sync refusals to be stamped onto the records the way the worker echo now does;
• the js-debug function breakpoints via the CDP proxy (revives #282 by another route) #295 stopOnEntry-force site (js launch command args) reads the same stamp — nothing in the worker re-derives the decision from a flag any more.

The parent needs no change: adapter_configured_and_launched resolves start(), #747's neutralized stopOnEntry projects RUNNING, readiness short-circuits, and the program's exit lands as STOPPED + exit code with the #467/#701 summary and the #710 warning. When the launch fails under the flag, the failure note (buildNoDebugFailureNote(language)) says the debugger was off and — for go only — that Delve resolves the program through exec.LookPath (see the quirk below).

Stamp, not derive — the first version derived the decision a second time in the worker from the post-transform launchConfig; both review rounds pointed out the agreement rested on every honouring transform spreading the key through, and a divergence produces the exact #746 symptom with a misleading "debugger is off" warning attached. One decision, decided once in the launcher, read by the worker.

Measured matrix (this branch's dist, set a breakpoint, launch { stopOnEntry: false, noDebug: true })

adapter	before	after
python (debugpy)	success: false, Proxy exited during initialization. Code: 0	running → stopped, exit 0, Result: 30 in output, #710 warning
go (Delve)	30 s init ceiling	running → stopped, Hello, World! in output, #710 warning (no exitCode: Delve reports the status as a console line only, in debug mode too — #753)
cpp (CodeLLDB)	Error in DAP sequence: … Not supported in noDebug mode.	running → stopped, exit 0, program output; CodeLLDB's own refusal in get_output, in the launch warning (…; setBreakpoints refused under noDebug: Internal debugger error: Not supported in noDebug mode.) and on each pre-launch breakpoint's message in list_breakpoints
javascript (js-debug)	stopped, exit 0	unchanged
rust, ruby, dotnet, java, mock	paused at the breakpoint, "no effect" warning	unchanged

One adapter quirk surfaced truthfully through the new path: under the flag Delve runs the binary through Go's exec.LookPath, so on Windows an extensionless binary fails with the adapter's own executable file not found in %PATH% (debug mode spawns it fine). Documented; the go e2e builds a .exe on win32.

Tests

• New tests/proxy/dap-proxy-worker-nodebug.test.ts (25): configured on the launch response with no initialized; the phase still runs once when initialized comes; a refused setBreakpoints (with the CodeLLDB deferred-launch-response shape) and a refused configurationDone are non-fatal; the 'true' string form; attach-shaped config untouched; an adapter without the pin keeps today's behaviour including the fatal refusal; go two-phase arms no timers and still runs a late phase once; the js-debug function breakpoints via the CDP proxy (revives #282 by another route) #295 guard (which fix(launch): a noDebug launch says what it did to the debugger instead of blaming the breakpoints (#710) #747 left untested); the stamp is the decision (stamp without the key reports early, key without the stamp does not); a refusal forwarded as a notice; a transport failure still fatal; refused exception filters / function breakpoints noticed and echoed; no CONNECTED flip mid-shutdown; a phase pending from the handshake, or in flight at the launch response, closes before the report; the adversarial same-read terminated ordering; a stale-pin two-phase adapter with initialized + terminated in one read opens no phase (launch-response → configured → terminated, no setBreakpoints); the per-group refusal echo (file A accepted with adapterId, file B stamped); configured before dap_connection_closed. Plus DapResponseError (appended to the A failed DAP response without a top-level message (js-debug ProtocolError) reaches the agent as a bare "Request failed" #663 suite), the parser's debuggerOff coercion, the launcher stamping it and gating resyncAll, the language-scoped failure note, ProxyManager adapter_notice → adapter-notice, and the core recording (and redacting, and containing) it like a Docker: Rust type summaries unavailable (no rustc in image) — &str/String render as raw LLDB internals #441 annotation.
• e2e (CI does not run the e2e project — Bundled CLI: split main() out of src/index.ts so the bootstrap needs no env flag; e2e project is not run by CI #732 — all run locally against a rebuilt dist): python noDebug in mcp-server-break-on-exceptions.test.ts (watched it fail against the pre-fix build with the issue's exact text), go in mcp-server-smoke-go.test.ts, cpp in mcp-server-smoke-cpp.test.ts. The proxy suite, unit + integration, typecheck:all, lint, check:docs, changelog:check and the full vitest run (every project; the one failure is the pre-existing tests: the #714 tarball-contents check fails on Windows Git Bash — GNU tar reads the C: drive prefix as a host #752 tar-on-Windows case, reproduced on main) pass.

Docs

docs/tool-reference.md noDebug paragraph, the honoursNoDebug doc comment and the python/go/cpp policy comments no longer say the launch fails; changelog.d/746.fixed.md.

Out of scope

Rust forwarding the flag (its transformLaunchConfig drops it, so noDebug silently does nothing there) is a separate decision. The later surfaces of a debugger-off session (set_breakpoint, list_breakpoints, pause_execution, inspection still answering in debugger terms) are #749 (PR #751). Go never reporting exitCode is #753; stamping live-sync refusals onto breakpoint records is #754.

🤖 Generated with Claude Code

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
src/proxy/dap-proxy-worker.ts	97.26%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[debugmcpdev]

Review round 1 (/code-review 750 high) — ten findings, all taken in 7907887

#	Finding	Resolution
1	isDebuggerOff() read only true/'true'; the launcher's resolveLaunchFlag takes anything else by truthiness, so noDebug: 'True'/1 had the launcher say "debugger off" while the worker waited for initialized — the exact #746 failure with a warning calling it deliberate	One coerceLaunchFlag (src/utils/launch-flags.ts) read by both; worker test covers 'True', 1, 'yes' and 'false'
2	LLM-facing tool-schemas.ts noDebug text (and the unreleased 710.fixed.md) still said the launches "currently fail"	Reworded; 24 tool-list fences re-recorded
3	completeDebuggerOffLaunch reported configured before running a phase that had arrived during the launch request (stale pin on a two-phase adapter)	Pending phase runs first (it marks configured itself); the launch-response mark fires only from INITIALIZING. New go test pins the order launch-response → setBreakpoints → configurationDone → configured
4	The tolerant catch downgraded any phase rejection to a log line; a stale-pin build failing for a real reason reported success with no mention	The adapter's own words now go to the caller: worker adapter_notice status (naming the request) → ProxyManager adapter-notice → core records it exactly like a #441 annotation (launch warning + [mcp-debugger] Warning output entry). cpp's warning now ends ; setBreakpoints refused under noDebug: Internal debugger error: Not supported in noDebug mode.
5	markConfiguredAndLaunched could flip SHUTTING_DOWN back to CONNECTED from the new catch path	Guarded on INITIALIZING; test simulates shutdown rejecting a pending setBreakpoints
6	go e2e asserted no exitCode while the changelog/docs claimed "with the exit code"	Measured: Delve reports no exitCode in debug mode either (console line only). Docs/changelog say so; the go e2e asserts the console line. Filing a dogfood ticket for exit-code synthesis on go
7	buildNoDebugFailureNote / failureData comment described the pre-#746 world	Reworded: the failure is most likely unrelated to the flag; drop it to compare
8	cpp e2e comment claimed the refusal is surfaced but never asserted it	Asserts the refusal in get_output and in the launch warning
9	Third copy of the worker-test scaffolding	createMockMessageSender + createMockWorkerDependencies hoisted into tests/test-utils/mocks/dap-proxy-doubles.ts; the go fallback suite and the new suite use them
10	The "no configuration phase to wait for" log line preceded a phase run	Distinct log for the pending case; the reorder in #3 removes the contradiction

Re-verified: proxy suite 323, unit+integration 5376 green; python/go/cpp noDebug e2e and the 9-adapter probe matrix unchanged (python/go/cpp complete, js unchanged, the five ignoring adapters pause).

[debugmcpdev]

Review round 2 (/code-review 750 medium, scoped to round 1's fixes) — seven findings, all taken

#	Finding	Resolution
1	The tolerant catch was cause- and state-agnostic: 'DAP client disconnected', a timeout or 'worker shutdown' all became "refused under noDebug", configurationDone was fired at a possibly-null client, and configured could be reported anyway	MinimalDapClient now rejects a DAP error response with a typed DapResponseError (carrying the response); only that is tolerated, and only while the session is not SHUTTING_DOWN/TERMINATED. A transport failure is fatal as in debug mode. Tests: transport error → Error in DAP sequence, no notice; a refusal landing during shutdown → no notice, no configurationDone, no mark
2	Plain launch mode handles initialized on arrival, so the phase could be mid-flight when the launch response landed and configured was reported before the phase closed (CodeLLDB answers launch before its configurationDone response)	The in-flight phase is tracked (initializedPhase) and awaited by completeDebuggerOffLaunch. Test pins launch-response → configurationDone → configured
3	Derive-vs-stamp, second time, with a concrete desync scenario	Stamped. debuggerOff rides ProxyLaunchRequest → ProxyConfig → the init command → ProxyInitPayload (parser coerces/validates it); the worker reads the stamp. Tests: the launcher stamps it (and false where the flag is ignored); the worker's "stamp without the key reports early, key without the stamp does not"
4	Refused setExceptionBreakpoints / setFunctionBreakpoints never became notices	noticeRefusalUnderNoDebug(request, err) in both inner catches (typed refusals only). Test asserts both notices
5	recordAdapterNotice bypassed #237 redaction	Same write-time pass as every other entry; flagged redacted. Test with a GitHub PAT in the note
6	Same-read terminated vs launch-response race	sendTrackedLaunch records the launch outcome; the exited/terminated terminal tasks first settleDebuggerOffLaunch() — configured is reported before the exit goes out, deterministically. The test models the terminal path starting first with the response delayed eight ticks; without the hook it yields ['terminated'] alone (the mark is refused after shutdown)
7	configurationDoneAttempted redundant with stage; three copies of the safe-status guard	stage alone; one sendStatusSafely used by the breakpoint echo, the notice and the child-adoption report

Re-verified: proxy/parser/launcher/core suites, unit + integration, typecheck:all, lint; python/go/cpp noDebug e2e green against the rebuilt dist.

[debugmcpdev]

Review round 3 (/code-review 750 low, scoped to round 2) — nine findings, all taken

#	Finding	Resolution
1	Round 2 overwrote tests/unit/proxy/dap-response-error.test.ts (the #663 suite) with the one new test	Restored from main, new describe appended — 7 tests
2	The configurationDone sent after a refusal swallowed every error and still marked configured	Only a DapResponseError is tolerated there; a transport failure takes the fatal path (failConfigurationPhase). Test: refusal, then 'DAP client disconnected' → Error in DAP sequence, no configured
3	initializedEventPending never consumed → a second completion took the pending branch, hit the duplicate guard without waiting, reported configured mid-phase	Consumed once; the duplicate guard awaits the in-flight phase. Test: go two-phase, pending phase + terminated with the launch response → setBreakpoints → configurationDone → configured → terminated
4	settleDebuggerOffLaunch ran an unbounded wait inside a terminal slot, and a throw aborted the forward	Bounded by the slot's 2 s backstop (TERMINAL_SIGNAL_BACKSTOP_MS, shared with the stdio drain) and wrapped. Tests: launch never answered → terminated forwarded after the backstop; the readiness status throwing → terminated still forwarded
5	The failure note said "most likely unrelated to the flag" while the PR documents the Delve .exe case	Names both: possibly unrelated (see the error), or an adapter behaving differently under the flag
6	The #295 site still re-derived the decision from its own args	Reads the stamp. coerceLaunchFlag had no worker consumer left → folded back into resolveLaunchFlag; the helper module and its test removed
7	A refused setBreakpoints skipped the breakpoints_synced echo	The refusal is echoed onto every pre-launch breakpoint (verified: false, message = the adapter's words). Live: cpp list_breakpoints → "Internal debugger error: Not supported in noDebug mode." on the pre-launch breakpoint
8	Duplicated redact-at-write block; redundant notice lambda	One redactForBuffer() for output entries and notices; recordAdapterNotice registered directly
9	Child-adoption report inlined the readiness payload	Calls reportConfiguredAndLaunched() again inside its try/catch

Re-verified: proxy/parser/session/server suites (1838), unit + integration, typecheck:all, lint, check:docs; python/go/cpp noDebug e2e green against the rebuilt dist.

[debugmcpdev]

Review round 4 (/code-review 750 low, scoped to round 3) — nine findings, all taken

#	Finding	Resolution
1	settleDebuggerOffLaunch could open a whole configuration phase from a terminal slot, outside the backstop, against a program that had ended	The slot only marks configured (a pending phase is dropped, one in flight finishes on its own); the handshake's completion checks a synchronous terminalSignalArrived flag before opening a phase. Test: stale-pin go, initialized + terminated in one read → launch-response → configured → terminated, no setBreakpoints
2	The refusal echo stamped every pre-launch breakpoint, overwriting groups the adapter had accepted	Answered groups are echoed as they came; only the unanswered ones are stamped. Test: file A accepted (verified: true, adapterId), file B refused
3	Delve's .exe advice on every adapter's failed noDebug launch	buildNoDebugFailureNote(language); the sentence is go's only
4	Refused setFunctionBreakpoints → notice but no echo	function_breakpoints_synced with verified: false + the refusal per function breakpoint
5	resyncAll re-asked an adapter whose debugger is off	Gated on !debuggerOff. Measured first: debugpy answers a post-launch setBreakpoints with "Server is not available", but resyncAll discards that answer — so the round trips bought nothing. Follow-up #754 filed to stamp live-sync refusals onto the records
6	Notice listener registered without the output path's guard	Contained; test with a throwing output-captured subscriber
7	Settle in two of four terminal slots	Hoisted into enqueueTerminalSignal; test asserts configured before dap_connection_closed
8	DapResponseError.command unused; duplicated predicate/strings	isNoDebugRefusal(), notices named by error.command
9	Stale comments; hardcoded child-flush backstop	Constant shared; sendStatusSafely's comment says what it covers

Re-verified: proxy/parser/session/server suites (1843), unit + integration, typecheck:all, lint, check:docs; python/go/cpp noDebug e2e green against the rebuilt dist.