[debugmcpdev]

Cluster 2 of the bugs gating 0.27.0: five answers that are right about the debugger's state and wrong about what the caller should conclude from it.

Closes #1135, closes #1140, closes #1141, closes #1142, closes #1139.

One commit per issue, then five commits from the reviews (three fixes, the tests and doc corrections they asked for, and one doc limit). Every row below was reproduced before its fix and run again after: on main (0f1eb6ac) through the dev proxy, except the two #1139 rows the reviews found (a reset, and a hang-up after initialize), which were measured on this branch's own build with a scripted listener.

What was wrong, and what changes

#1141 — get_stack_trace pointed at itself, and an ended session was explained by one tool of five

The includeInternals hint. get_stack_trace adds "No program frame is active…" only when it hid nothing, and that sentence ended "get_stack_trace with includeInternals: true lists the frames" — said to a caller who had passed the flag and was looking at every frame.

• ErrorMessages.stopWithoutProgramFrame now takes whether the thread has frames the answer did not show. get_stack_trace never says the clause. The pause and step answers say it when the thread has more than the one frame they show.

An ended session. get_local_variables explained it; get_stack_trace, get_scopes, get_variables and evaluate_expression answered the bare Session is terminated: <id>. The one sentence that existed was also wrong for two kinds of session: after detach_from_process on a Python attach it said "The program has terminated… Use restart_debugging" while the process was still running and restart_debugging refused it (measured).

• One helper (handlers/shared.ts endedSessionExtras) adds message, worded by the three cases restart_debugging itself tells apart: a child names its parent, an attach session is attached again, a launch is restarted.
• error is unchanged everywhere.

#1135 — get_local_variables answered a runtime frame's variables as plain locals

extractLocalsFromResolved never read the resolver's noProgramFrame verdict.

• get_local_variables now carries noProgramFrame: true and the sentence the pause or step answer gave for that stop ("No program frame is active…"), plus "The variables shown belong to '', not to your program."
• evaluate_expression without frameId had the same gap and gets the same flag, ending "The expression was evaluated in that frame." An explicit frameId adds nothing.
• The variables are still returned: they are what the adapter reported.

Row from the issue	Before	After
JavaScript, pause on pause_test.js	now = 4210, no flag, no note	flag and note
C/C++ on Windows, step_out of main	[return value] = 0 and five CRT locals, no flag	flag and note
C/C++ in Docker, step_out of main	[return value] = 0 from ___lldb_unnamed_symbol_2a580, no flag (the issue's report; not re-run by me on main)	flag and note, same variable
Rust, step_out of main	no flag	unchanged

The Rust row is not this bug: its landing frame (core::ops::function::FnOnce::call_once) is not classified as runtime, so get_stack_trace has no verdict there either. That is #1131; I left a comment there.

#1140 — changedVariables invented a value for a variable that was not there

A name absent from the diff base was written as a change from the string "<undefined>". The shape below is the one the maintainer chose during planning (one map, explicit kinds, gone added now):

"changedVariables": {
  "x":   { "before": "1", "after": "2" },
  "sum": { "after": "30", "new": true },
  "i":   { "before": "3", "gone": true }
}

• An empty {} still means nothing visible changed.
• A flag is set only when it is known. The locals a snapshot shows are capped at 20, so the diff base now records whether its list was complete. new needs a complete previous list; without one the entry is { "after": … } alone. gone needs a complete current list; without one the variable is not listed, as before.
• The adapters' return-value entries stay in the diff, as new.

#1142 — the statement hint could not be followed

An expectedContent mismatch ended "Or address by content: set_breakpoint {statement: ""}" whether or not the text was in the file.

• The sentence is now resolveStatement's own answer for that text: on one line it names the line; on several it adds nearLine and lists them.
• Where the resolver would not find the text, no statement is offered. The message names the lines the same expectedContent check passes on ("That expectedContent matches line 3."), or says it matches no line of the file.
• Both of those claims come from the check's own function (matchLineContent, which assertLineContent now reads too). The resolver ignores comment lines and whatever follows a // or #; expectedContent does not. The first version of this fix said "matches no line of the file" for the resolver's reasons, so text sitting in a trailing comment one line away was called absent. The review caught it.
• Text spanning lines gets no such sentence.

#1139 — a direct-connect attach described an adapter that never existed

A Python or Ruby attach starts nothing; the worker connects to the caller's host and port. Every failure was worded for a spawned adapter, or not worded at all:

Target	Before	After
Silent listener (30 s)	"…the adapter started and accepted the connection. Retrying usually succeeds…"	"127.0.0.1:47811 accepted the connection but never answered the DAP "initialize" request. Nothing was started for this attach: the server connected to what is already listening on that port, so check that it is a debugpy listener (python -m debugpy --listen 127.0.0.1:47811 …) and not another service. Retrying the same port stalls the same way."
Real HTTP port (python -m http.server, about 1 s)	"Critical initialization error: DAP client disconnected [Executable: python | adapter PID=none exitCode=n/a]"	"Critical initialization error: 127.0.0.1:47812 never answered the DAP "initialize" request (DAP client disconnected). Nothing was started for this attach: …"
Port that resets the connection (about 1 s)	"DAP client error: read ECONNRESET"	"Critical initialization error: 127.0.0.1:56811 never answered the DAP "initialize" request (read ECONNRESET). Nothing was started for this attach: …"
Debug server that answers initialize, then hangs up (about 1 s)	Python: "Proxy exited during initialization. Code: null, Signal: undefined" and ten lines of worker stderr. During configuration: "Error in DAP sequence: DAP client disconnected"	"Critical initialization error: DAP client disconnected [direct connect to 127.0.0.1:59591; no adapter process was started]"
Nothing listening (12.5 s)	"…[Executable: python | adapter PID=none exitCode=n/a]"	"…[direct connect to 127.0.0.1:47819; no adapter process was started]"

• The worker sends a direct_connect status with what it dialed; the policy supplies what should be listening there. The answer for a 30 s stall carries it as data.initProgress.directConnect; the answers that fail sooner name the endpoint in the message only.
• A connection that dies mid-handshake reaches the worker as a socket event before the pending request fails: a reset as error, a hang-up as close. The parent fails the attach on the first thing it is sent, and for a close that used to be the connection-closed status. During a direct-connect handshake the first socket event now sends the endpoint report, once (reportDirectConnectDrop).
• The two reviews found the reset and the hang-up-after-initialize paths. The first version of the fix covered only a hang-up before initialize was answered.
• The wording is keyed on what is pending: once initialize was answered the endpoint is a debug server, and the port is no longer blamed.
• The spawned-adapter sentences are byte for byte what they were.

Behaviour a client can observe

• Changed shape: a new variable in snapshot.changedVariables no longer has before; it has new: true. A variable that left scope is now listed, with gone: true.
• New fields: noProgramFrame on get_local_variables and evaluate_expression; message on four more tools for an ended session; data.initProgress.directConnect on a direct-connect attach that stalls for the 30 s.
• Changed text: the notes and messages quoted above. No tool is added or removed (29), and no field is removed.

Evidence

Each fix's unit tests were run failing before the fix. The tests that pin behaviour a review found unpinned passed when written, so each was checked against the reviewer's surviving mutant, which it now kills.

Check	Result
Unit suite	424 files, 9,077 tests pass
Integration project	42 files, 194 tests pass (the stress file is skipped by design)
New real-adapter suites (js-debug, debugpy, a real server)	4 files, 7 tests pass
typecheck:all, lint, check-docs, changelog:check	pass
Pre-push hook (lint, typecheck, build, unit, integration) on 9e15d749	pass
Live, every row above: through the dev proxy, and for the two review-found #1139 rows with a scripted listener against the built server	as quoted

The four real-adapter suites were written after their fixes, so their "before" is the live answers on main quoted above, not a failing test run. The reset and hang-up-after-initialize cases of #1139 are the exception: their tests failed first (for the hang-up, the real-server test too), and their "before" was measured on this branch's own build.

Review

Three independent reviews, each by a fresh agent with a shell. Each ran the built server against its own listeners, ran a mutation pass, and restored every edit.

1. The five issue commits. No Critical findings; four Important, all fixed:

• attach to a port that never answers DAP: the 30 s stall message says 'the adapter started… retrying usually succeeds' — for a direct-connect attach the likely cause is the wrong port #1139 missed a path: a port that resets the connection (57b3281e).
• set_breakpoint: an expectedContent mismatch suggests 'statement: <the mismatched text>' even when that text is nowhere in the file #1142's replacement sentence was false for text in a comment or past a // inside a string (fc211017).
• Two promised behaviours had no test: an ordinary evaluate_expression is not flagged (get_local_variables returns a runtime frame's variables with no note when no program frame is active (JS, C/C++, Rust) #1135), and a failure after initialize was answered does not doubt the endpoint (attach to a port that never answers DAP: the 30 s stall message says 'the adapter started… retrying usually succeeds' — for a direct-connect attach the likely cause is the wrong port #1139). Both are pinned.
• Mutation pass: 86 mutants, 76 killed. Of the 10 survivors, 7 are now killed by new tests. The other 3 are resets of per-attempt state that nothing reaches today (a worker and a proxy manager each serve one attempt). A mutant that reverted the skill text also survives: no test pins that wording.
• Its doc findings are corrected (bf157654).

2. The two fix commits above. No Critical findings; one Important, fixed:

• A direct-connect debug server that hangs up after answering initialize still lost the endpoint (6fa2651c).
• A property fuzz of the set_breakpoint: an expectedContent mismatch suggests 'statement: <the mismatched text>' even when that text is nowhere in the file #1142 message (about 267,000 cases a seed, 3 seeds) and a differential fuzz against the previous resolver (340,000 cases) found no failure.
• Mutation pass: 59 mutants, 51 killed. Of the 8 survivors, 6 are equivalent or not observable by a caller, 1 is in code this PR only moved (a match label in Agent-facing papercuts: CodeLLDB console chatter in get_output; expectedContent without the trailing ';'/'.' gets the substring warning #1038's terminator rule), and 1 was the cap on the new list of lines, now pinned.

3. The last fix commit (6fa2651c). No Critical findings and no regression. One Important, not fixed here:

• A scripted listener that answers initialize, then sends a DAP terminated event and closes, is still answered "Proxy exited during initialization. Code: 0…" with worker stderr. The worker is already shutting down when the socket closes, so it has no report to send first. Re-run by me; not seen from a real debugpy or rdbg.
• I stopped rather than change behaviour a fourth time. The cause is one level up: the parent words a failed start from whichever worker message arrives first. That is direct-connect attach: a debug server that ends the session mid-handshake still answers 'Proxy exited during initialization', and a refused configuration request names no endpoint (follow-up to #1139) #1152 (filed), with a direction: the parent already holds the endpoint and can word its own exit path. The changelog and troubleshooting guide state the limit (9e15d749).
• Mutation pass: 23 mutants, 19 killed. Of the 4 survivors, 2 are killed by a sibling test file, 1 is equivalent, and 1 could not be made visible to a caller.
• One change for every adapter: after an init failure has been reported, the configuration phase no longer sends a second "Error in DAP sequence: DAP client disconnected" from its own teardown. By the reviewer's reading of the code the parent never read that second message; that was not run end to end with a spawned adapter.

Seen outside the branch by the first reviewer, both reproduced by me, both for cluster 3:

• detach_from_process on a launched session answers 'process still running' while the debuggee is dead (python, deterministic; the message is unconditional) #1151 (filed): detach_from_process on a launched Python session answers "process still running", and the process is dead.
• javascript: step_into on a line that calls a Node builtin takes ~6 s and answers pending, blaming 'a long-running call' #1130 (comment added): step_into from simple_test.js:11 never lands, and the program runs to its exit.

Calls I made

• get_local_variables returns a runtime frame's variables with no note when no program frame is active (JS, C/C++, Rust) #1135 keeps the variables. The snapshot still leaves locals out on such a stop; the two now agree on what the frame is.
• get_local_variables returns a runtime frame's variables with no note when no program frame is active (JS, C/C++, Rust) #1135 covers evaluate_expression, which the issue does not name.
• get_stack_trace guidance: the includeInternals hint is circular, and a terminated session gets a bare error where get_local_variables explains #1141 covers get_scopes, get_variables and evaluate_expression, and corrects the sentence for attach and child sessions.
• snapshot.changedVariables shows a new binding as before: "<undefined>" — a fake change for js-debug's 'Return value', and JS vocabulary for a Java/Rust/Dart local entering scope #1140, gone needs only the current list to be complete. The plan said both lists. A variable that was shown and is absent from a complete list has left scope, whatever the earlier list omitted.
• snapshot.changedVariables shows a new binding as before: "<undefined>" — a fake change for js-debug's 'Return value', and JS vocabulary for a Java/Rust/Dart local entering scope #1140 keeps the return-value entries. Measured: debugpy's (return) add stays in the frame once it appears, and js-debug's Return value shows at a return point, after which the frame changes. Neither flickers, so no exception was added.
• set_breakpoint: an expectedContent mismatch suggests 'statement: <the mismatched text>' even when that text is nowhere in the file #1142 also answers a comment expectation. expectedContent: "# setup" on the wrong line used to get no sentence; it now gets the line the comment is on. No statement is offered for it.
• attach to a port that never answers DAP: the 30 s stall message says 'the adapter started… retrying usually succeeds' — for a direct-connect attach the likely cause is the wrong port #1139 leaves the 30 s deadline alone. A shorter one for direct connect would be a hold sized without a measurement.
• No tool description changed, so the tool-list snapshots are untouched.

Known limits

• get_local_variables returns a runtime frame's variables with no note when no program frame is active (JS, C/C++, Rust) #1135 for Rust waits on rust: step_out of main lands in FnOnce::call_once with no 'no program frame' note, a symbol label as location, and a nameless junk local #1131.
• set_breakpoint: an expectedContent mismatch suggests 'statement: <the mismatched text>' even when that text is nowhere in the file #1142: the statement hint names where the resolver finds the text ("that text is on line 5"). expectedContent may also pass on a line the resolver ignores, such as a comment; the hint does not list those.
• attach to a port that never answers DAP: the 30 s stall message says 'the adapter started… retrying usually succeeds' — for a direct-connect attach the likely cause is the wrong port #1139: the message for a silent port still takes 30 s to arrive.
• attach to a port that never answers DAP: the 30 s stall message says 'the adapter started… retrying usually succeeds' — for a direct-connect attach the likely cause is the wrong port #1139: a debug server that ends the session itself mid-handshake (terminated, then close), and a configuration request refused in DAP ("Error in DAP sequence: …", the server's words without the endpoint). Both are direct-connect attach: a debug server that ends the session mid-handshake still answers 'Proxy exited during initialization', and a refused configuration request names no endpoint (follow-up to #1139) #1152.
• attach to a port that never answers DAP: the 30 s stall message says 'the adapter started… retrying usually succeeds' — for a direct-connect attach the likely cause is the wrong port #1139: a reset after the worker's handshake completed, while attach_to_process is still verifying the attach, still answers the plain "DAP client error: read ECONNRESET". The endpoint wording stops at the handshake.
• attach to a port that never answers DAP: the 30 s stall message says 'the adapter started… retrying usually succeeds' — for a direct-connect attach the likely cause is the wrong port #1139: a spawned adapter whose socket errors mid-handshake still gets the bare "DAP client error: …" first. That is not a direct connection and is unchanged here.
• get_stack_trace guidance: the includeInternals hint is circular, and a terminated session gets a bare error where get_local_variables explains #1141: list_threads, the step tools and pause_execution still answer the bare Session is terminated: <id> (as docs/tool-reference.md says).
• snapshot.changedVariables shows a new binding as before: "<undefined>" — a fake change for js-debug's 'Return value', and JS vocabulary for a Java/Rust/Dart local entering scope #1140: an empty locals read still emits no diff, so a frame whose every variable left scope says nothing on that stop.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!