[FEATURE] Agent-native breakpoint addressing: expectedContent assertion, statement anchors, function breakpoints

[debugmcpdev]

Problem (an AX lesson)

Agents set breakpoints on the wrong lines because they don't have a gutter. A human points at a statement and the IDE resolves the line number; an agent reads a 1D token stream, keeps a running count (often from a snippet that started mid-file), and commits to an integer — predictably landing off-by-one-or-two on a blank line, a brace, or a comment. The result is confusing session behavior (breakpoint never hits, or hits somewhere unexpected).

Current mitigations all act after commitment or rely on the agent noticing warnings: the response echoes line content, adapters silently snap to the nearest valid line, and the schema description warns about non-executable lines. None of them move the anchor itself.

There is also a drift problem: line numbers go stale the moment the agent edits the file mid-session — which is the core fix-verify loop. restart_debugging (#238) re-applies breakpoints at their recorded lines, so after an edit the re-applied breakpoints can silently point at the wrong code.

Proposal: a progression of addressing modes

All modes return the same resolved contract — {breakpointId, line, content, verified, anchor?} — so list_breakpoints and the audit trail stay uniform. All compose with condition, logMessage, and suspendPolicy unchanged.

1. expectedContent assertion (cheap, ship first)

Keep line addressing, add optional expectedContent: string. Server hard-errors before setting anything if the trimmed line content doesn't match, and the error includes the actual content of that line plus a few neighbors. A checksum on intent: converts off-by-one from 'confusing session behavior' into an immediate, self-explanatory failure. Non-breaking, ~small diff (line content is already read for the response echo).

2. statement anchors (primary agent mode)

set_breakpoint {sessionId, file, statement: \"total = sum(prices)\", nearLine?: 80}

• Exact-match after trimming leading/trailing whitespace; anchor at the first line of a multi-line match.
• Ambiguity contract: multiple matches → error listing every match as line: content pairs (the error message is the disambiguation UI; agent picks in one follow-up). nearLine selects the closest match when provided.
• Reject blank/comment-only anchors with a clear error.
• Re-resolution: the anchor is stored on the breakpoint record; restart_debugging re-resolves anchors against the current file, so breakpoints survive the edit that was the whole point of the session.
• Rationale: this recruits the single most-practiced agent skill — Edit-tool old_string matching — instead of demanding line arithmetic, a skill models are demonstrably bad at. Self-validating by construction: an anchor can't land on a blank line.

3. function breakpoints (symbol mode)

set_breakpoint {sessionId, function: \"build_cart\"} via DAP setFunctionBreakpoints, gated on supportsFunctionBreakpoints. Agents reason in symbols more reliably than in lines or statements, and names survive edits better than both.

Supporting: deliberate snapping

Where a line must be adjusted, use DAP breakpointLocations (where supported) to snap explicitly and report it loudly ('requested 12, bound to 13: total = ...') instead of relying on each adapter's silent adjustment.

Non-goals / alternatives considered

• Fuzzy content matching as the primary mode — rejected: silent wrong-match is the exact failure class we're eliminating. Fuzzy is acceptable only as an explicit nearLine-guided fallback with a warning in the response.
• AST-based addressing — per-language parser cost across seven adapters for marginal gain over statement + function modes.

Evaluation

This is an agent-experience change, so it should be validated like one: A/B the addressing modes against line-only in a controlled harness (same tasks, same model, feature-flagged server so conditions differ only in the tool contract). Metrics: wrong-breakpoint rate against annotated intended targets, correction re-sets within a few calls, rounds/tokens per task, and root-cause-identification success. Results will be posted here; the skill (skills/debugging/) gets updated with whichever contract wins.

Rollout

1. expectedContent (non-breaking assertion) + loud snapping
2. statement/nearLine + restart re-resolution + list_breakpoints anchor display
3. function mode, capability-gated per adapter

Related: #236 (breakpoint management — record shape), #238 (restart re-apply — re-resolution hook), #235 (logpoints — anchors compose with logMessage).

[debugmcpdev]

A/B results: addressing modes under controlled trials

As promised in the issue, the addressing modes were evaluated like an agent-experience change: a controlled A/B harness ran headless agent trials against a feature-flagged server (DEBUG_MCP_BP_ADDRESSING), so conditions differed only in the tool contract — line (pre-#271 behavior, byte-identical control), assert (+expectedContent/loud snapping), content (+statement/nearLine). Task prompts never mentioned breakpoints or the new params; the control arm's transcripts contain zero traces of them (verified).

Setup. 102 trials across three waves: (1) 36 trials × Sonnet 4.6 on four small seeded-bug Python fixtures (~40–60 lines; decorators, comment blocks, blank-heavy layouts, multi-line calls); (2) 30 trials × Sonnet 4.6 on a ~260-line module — a diagnose task whose prompt embeds stale line references from "an older revision", and a fix-verify task requiring an edit + restart_debugging; (3) 36 trials × Haiku 4.5 over a mix of both. Tasks: "diagnose why X is wrong; write root cause to analysis.md" (fix-verify additionally required a runtime-verified fix). Metrics: wrong-breakpoint rate vs annotated intended-target sets (judged by bound-line content, edit-proof), correction rate, turns/tokens/cost, and blinded rubric scoring of each analysis.

Results.

wave	model	arm	bp sets ok	rejected	wrong	mean turns	mean $	diagnosis success
small-file	Sonnet 4.6	line	13	0	0	13.6	0.28	12/12
small-file	Sonnet 4.6	assert	14	0	0	13.8	0.28	12/12
small-file	Sonnet 4.6	content	15	4	0	13.8	0.29	12/12
deep-file + fix-verify	Sonnet 4.6	line	11	0	0	18.1	0.41	10/10
deep-file + fix-verify	Sonnet 4.6	assert	10	0	0	15.9	0.35	10/10
deep-file + fix-verify	Sonnet 4.6	content	14	10	0	19.9	0.43	10/10
mixed	Haiku 4.5	line	15	0	0	18.9	0.15	12/12
mixed	Haiku 4.5	assert	17	2*	1*	19.3	0.16	12/12
mixed	Haiku 4.5	content	17	5	0	19.3	0.15	12/12

* Neither Haiku "rejection" was an assertion catch (one POSIX-formatted Windows path refused by the file checker, one call against a terminated session), and the single "wrong" set was a deliberate def-line breakpoint whose expectedContent matched — the agent got exactly the line it named.

Findings.

1. Adoption is total and unprompted. Offered the params, agents used them on essentially every set: 14/14 assert-arm sets carried expectedContent; 100% of content-arm sets used statement. The schema descriptions alone redirected behavior — no prompting, no skill text.
2. The guarded failure mode did not occur. Zero line-arithmetic errors in ~150 breakpoint sets across both models: with Read access, current models re-derive line numbers from fresh file reads and ignored even deliberately-planted stale line references. The off-by-N problem this issue targets appears to live at the margins for current frontier models at these file sizes (≤ ~260 lines) — plausibly still relevant for larger files, no-read contexts, or longer drift chains, none of which these trials cover.
3. The modes cost nothing — and assert may pay. Turn/cost parity everywhere, with the assert arm the cheapest on the hardest tasks (15.9 vs 18.1 control mean turns).
4. The phase-2 safety rails behaved correctly in live use. In every content-arm fix-verify trial, after the agent edited the buggy line, restart_debugging correctly reported the anchor as stale (the anchored text no longer existed) and kept the breakpoint rather than silently rebinding; agents re-anchored deliberately, some cycling to a clean re-resolved restart. No silent wrong-code breakpoints occurred in any arm.
5. One contract defect surfaced: agents overwhelmingly try statement + expectedContent together on their first set (100% of content-arm deep-task trials), and the hard-error costs a round each time → [AX] set_breakpoint: accept statement + matching expectedContent instead of hard-erroring #280 proposes accepting the redundant-but-consistent combination.

Conclusion. Phases 1–2 ship as zero-cost ergonomics with working safety rails and total organic adoption, rather than as a measured accuracy win — the failure mode they guard against didn't manifest under these conditions. The default stays content (all features on); the flag remains for anyone who wants to reproduce comparisons. The debugging skill's golden path now teaches statement-first addressing. Follow-ups: #280 (combination guard) and phase 3 (function breakpoints, capability-gated) remains open here.

[debugmcpdev]

Addendum to the A/B results, and closing

Why the wrong-breakpoint rate was zero — the harness explanation. A follow-up check of the trial transcripts found that 102 of 102 trials called the file-reading tool on the target file before their first set_breakpoint — and in the evaluated client (Claude Code) that tool returns content with line numbers prefixed on every line. When the agent's context contains a numbered listing, choosing a breakpoint line is transcription from a visible gutter, not the line arithmetic this issue's premise assumed. The failure mode wasn't beaten by model capability; it was engineered away upstream by the harness — which also explains why even the smaller model made no line errors.

That sharpens where content addressing still carries its weight:

• Post-edit staleness — edit results don't renumber the file, so line references between an edit and the next re-read are genuine arithmetic ("my breakpoint moved 3 lines down"). Statement anchors + restart re-resolution cover exactly this, and re-reads are the first thing skipped under context pressure.
• Unnumbered sources — diff hunks, pasted snippets, tracebacks quoting a since-edited file.
• Other MCP clients — this server doesn't only serve clients whose read tools number lines; for those that don't, the 1D-token-stream premise still holds as written.

Phase 3 shipped. set_breakpoint {function: "name"} (symbol addressing — no file, no line, survives edits best) landed with capability gating per adapter (Python/Go/Rust/.NET; Java and JavaScript fail fast — js-debug child-session wiring is tracked in #282), completing the issue's rollout:

1. ✅ expectedContent + loud snapping (feat(#271): expectedContent breakpoint assertions + loud snapping (phase 1) #278)
2. ✅ statement/nearLine + restart re-resolution (feat(#271): statement anchors + restart re-resolution (phase 2) #279)
3. ✅ function mode, capability-gated (feat(#271): function breakpoints (phase 3) + statement/expectedContent fix (#280) #281) — plus [AX] set_breakpoint: accept statement + matching expectedContent instead of hard-erroring #280's redundant-assertion fix from the trial findings

All three addressing modes are on by default; DEBUG_MCP_BP_ADDRESSING remains for reproducing controlled comparisons. The debugging skill teaches content-first addressing. Closing as complete — evaluation posted above, follow-up work tracked in #280 (done) and #282.