Breakpoints: aim at a step point, enable/disable, and a manager view

[ericwinger]

Closes #262.

Setting a breakpoint meant a gutter click, which lands on the leftmost step point of the line. A Smalltalk line routinely holds several, so the one you wanted was often not the one you got — and there was no way to disable a breakpoint, act on all of them at once, or see what the session actually had.

The rule everything follows

A GemStone breakpoint lives in the gem. It is not in the repository — no commit persists it, verified on 3.6.2 and 3.7.5 — so it cannot outlive the thing it was set in. VS Code's breakpoint list is the working model (which is what makes the gutter, the per-breakpoint checkbox and the built-in Enable/Disable/Remove All controls drive GemStone for free), but deliberately not a durable one. A breakpoint is dropped from that list, not just from the gem, when:

• the session logs out — and anything VS Code's own cross-restart persistence brings back on startup is pruned;
• the method is recompiled — the new method is a different object, and after an edit the same step point may be different code, so re-applying would move the breakpoint somewhere the developer never put it.

Both of those were the opposite way round in the first draft of this branch. They changed because a marker that promises to stop execution it cannot stop is worse than no marker.

What you get

Aiming at a step point. Precision rides on the breakpoint's column: a gutter click carries none and means the leftmost step point on the line, while an inline breakpoint or Toggle Breakpoint at Cursor (Shift+F9) carries the exact column and picks the step point nearest it. The token that will actually break is outlined — grey and faded when disabled, matching the grey the gutter dot goes.

Enable / disable. Per breakpoint from the Breakpoints view checkbox or the cursor commands; Enable All / Disable All / Remove All cover every GemStone breakpoint, including ones Jasper never set. A disabled breakpoint is applied as set-then-disable, because disableBreakAtStepPoint: is a no-op on a step point with no breakpoint.

Step points, numbered but out of the way. Numbers are inlay hints — VS Code's own dim style, suppressed or restyled by its editor.inlayHints.* settings like any other — each clickable to toggle a breakpoint there. gemstone.stepPoints.display defaults to debugging, so they appear while a debug session runs and stay out of the way while you are reading or writing code. Hovering a step point always reports its number and breakpoint state whatever the setting. Numbers are withheld while a buffer has unsaved edits, since the stone's offsets no longer describe the text on screen.

A breakpoint manager. A Breakpoints view in the GemStone sidebar lists what the gem actually holds, grouped by class and method with the step point each breakpoint resolved to. It is the gem's truth rather than a copy of VS Code's list, so it also surfaces breakpoints Jasper never set — from topaz, or a halt left in the code — which were invisible until execution stopped on one.

Break on entry by naming a method. The + button in VS Code's Breakpoints panel takes a name rather than a location. Type a bare selector and Jasper finds the implementors, asking which class you meant when there is more than one; a qualified Account>>balance or Account class>>new skips the prompt but is still checked against the image, since a typo would otherwise set a breakpoint that silently never fires. The name is then replaced by an ordinary breakpoint on the method's first step point, rather than carried as a second kind of breakpoint — so it gains a real location and red dot, enable/disable, and a row in the manager view, and cannot fight a source breakpoint over which of them owns a method's breaks.

Everything works in the debugger's source pane too, since the debugger opens ordinary editors.

Unifying two managers that fought each other

The old cursor-toggle command kept its breakpoints in a private map, so they never appeared in the Breakpoints view and were silently wiped whenever a gutter breakpoint on the same method was applied (that path calls clearAllBreaks first). It now adds a normal VS Code breakpoint, so the two kinds are one kind.

Bugs found along the way

• A gutter breakpoint could land one step point late. Line-to-step-point mapping compared GemStone's 1-based source offsets against 0-based line offsets, so a step point sitting exactly on a line boundary was read as belonging to the previous line. Run to Cursor already corrected for this; the gutter path did not.
• _allMethodBreakpoints' tuple stride is version-dependent — 3 fields on 3.6.2, 4 on 3.7.5, which gained breakpointLevel. Decoding it by hand walks off the end of the array on the older release. getAllBreakpoints reads the kernel's own _breakReport: instead, which knows its own stride. It also skips breakpoints stranded on a superseded method version, which a recompile leaves behind and the gem goes on reporting.
• Cursor commands failed silently in four cases — a non-method editor, an unsaved buffer, a diff view, a method whose step points can't be read. Invoked from a keystroke, a silent no-op is indistinguishable from a dead keybinding. Each now says why.
• A named breakpoint's implementor search skipped environment 0. gemstone.maxEnvironment is a ceiling, not a selection, and was passed straight through as the environment to search — so on a stone configured above 0 an ordinary selector came back as "nothing implements it". It now sweeps 0..max and remembers which environment each hit came from.
• VS Code's + creates the breakpoint blank and only then opens it for editing, and the typed name arrives as a change, not an addition. Rejecting the blank deleted the row before it could be typed into; watching additions alone never saw the name.

Known limitation

VS Code's own Deactivate Breakpoints button greys the breakpoints out but cannot reach GemStone: vscode.debug exposes no activation state and no event for it, so an extension cannot observe the flag and the breakpoints stay armed in the gem. Disable All Breakpoints is the one that disarms them. Documented in the README.

Testing

npm run lint, npm run format:check, npm run compile and npm test all clean: 6152 client, 322 server, 92 mcp-server.

breakpoints.integration.test.ts pins the GemStone semantics the design rests on against a live stone, since none of them is documented anywhere we control — the disable-is-a-no-op rule, set-as-enable, out-of-range being silently ignored, breakpoints surviving a transaction abort, and the version-independence of the breakpoint report. Run against both 3.6.2 and 3.7.5.

Manually verified end to end in the Extension Development Host across 20 checks: gutter and cursor breakpoints, the panel and the manager view, enable/disable individually and globally, step point numbering and its dirty-buffer suppression, hover, reveal-from-list, the four global toolbar actions, all six named-breakpoint cases, actually stopping on a breakpoint, recompile, logout, and class-side methods.

🤖 Generated with Claude Code

[npapagna]

Thanks @ericwinger! Left a couple of comments.

[ericwinger]

Thanks @npapagna — all fourteen are addressed, each with a reply in its own thread and the thread resolved. Branch is up to date with main.

Both blockers. The swallowed GCI failure now reports the stone's message and, in the case you spotted, removes a break that armed but could not be disabled rather than leaving it stopping execution behind a marker that reads "disabled". The doit/decompiled blocker went a different way than you asked: the case is now refused rather than threaded through BreakpointManager, because a doit's method is compiled for one execution and gone afterwards, so a breakpoint on it could never be hit again. That is a decision worth your eye — the reasoning is in that thread, along with the residual filed as #515.

One premise correction, because it changes severity rather than the fix. The three session-scoping findings were called latent on the grounds that Jasper supports only one open session. Concurrent sessions ship today behind gemstone.sessionMode: "multiple", documented in the README and in the CHANGELOG entry that introduced Logins & Sessions — and the README's own note describes the exact state the code mishandled: "an open workspace/editor stays bound to the session that opened it even after you switch the active session." All three were reachable by a developer flipping one documented setting, and all three are fixed and tested.

Verified by hand against a live stone, by Eric — as distinct from the rest, which rest on automated tests:

• a breakpoint is applied to the gem its method was opened from, not the selected session;
• a Breakpoints view row disables only its own session's breakpoint;
• Disable All reaches every logged-in session's gem;
• the keyword scan carries past a separator nested inside brackets;
• the step point numbers toggle survives a fast double-click;
• Run to Cursor through the shared resolver stops at the send nearest the cursor on an Executed Code frame.

Also in this round, from a second pass over the branch after your review:

• the one-round-trip step point query had never executed against a stone — every test mocked it, so a syntax error or a release difference in sourceString / _sourceOffsets would have stopped step point numbers entirely with the suite green. It now has ungated integration cases comparing its three parts against the three queries it replaced, proving the reply is not merely empty, and pinning the framing with source containing tabs, blank lines and header-shaped text;
• the args.source.path branch of setBreakpointsRequest — the only path that now carries a refusal reason to the developer — has tests for the reason arriving, for an accepted breakpoint carrying none, and for the column being forwarded;
• a method held still while its editor was dirty was only ever released by a revert, never by a save, so the URI leaked for the life of the window; it is released on recompile and swept on logout;
• CHANGELOG entries for four fixes that had none, and the README now states that a breakpoint belongs to its own session's gem and that Enable/Disable/Remove All sweep every logged-in session.

Every source change was mutation-checked: reverted in turn, with the suite required to go red. Gate is green — lint, formatting, compile, 6,818 client tests, 322 server, 92 mcp, including the live-stone integration tests.

[npapagna]

Thanks @ericwinger! 🚀