breakpoint-mcp 1.76.0 → 1.77.0

package/dist/bridge.js

@@ -120,6 +120,34 @@ export class BridgeClient {
         this.secretProvider = secretProvider;
         this.ledger = new OverdueLedger("bridge", peerNoun, deadlineKnob);
     }
+    /**
+     * A cause this client cannot see, supplied by whoever CAN, as the remedy on a timeout.
+     *
+     * 🔴 WHY THIS EXISTS AT ALL — the eighth session of "the host's own failures carry no
+     * remedy" (254 §4.6 → 261 §4.4), answered for the one case a walk actually produced.
+     * `BridgeError.remedy` was documented as "the addon's to give, and a host-raised
+     * timeout arrives without one". True for a closed socket. NOT true here, and USER_GUIDE
+     * §10 B's own step 5 walks the reader straight into it: the addon services `runtime_*`
+     * from `_process`, so a breakpoint inside the method being called halts the very frame
+     * that owes the reply. Measured — the stop's stack trace is `compute` on top of
+     * `_call_method` → `_dispatch` → `_handle_line` → `_drain_lines` → `_process`, five
+     * frames of the addon's own dispatch — and the caller got
+     * `Bridge request 'runtime.call_method' timed out after 15000ms` and nothing else,
+     * EVERY TIME THE RECIPE WORKED. The deadlock is a fact about the debugger, which lives
+     * in the host, three modules away from the socket that gave up.
+     *
+     * 🔴 A HOOK RATHER THAN A CONSTRUCTOR PARAMETER, and that is not laziness: nine `.mjs`
+     * integration probes construct these registrars directly where TypeScript cannot see
+     * them, and 257 spent six red CI jobs learning what adding a parameter costs. A probe
+     * that never sets a probe gets exactly today's behaviour.
+     *
+     * Wired on the RUNTIME client only. A game halted at a breakpoint does not hold the
+     * editor bridge, and the sentence would be a confident lie on plane A.
+     */
+    setHoldProbe(probe) {
+        this.holdProbe = probe;
+    }
+    holdProbe = null;
     /** Register a listener for addon-pushed resource-change events. */
     onResourceChanged(cb) {
         this.eventListeners.add(cb);
@@ -325,7 +353,11 @@ export class BridgeClient {
                 // exact `timed out after <n>ms` phrasing — tools/dap.ts:29 and
                 // tools/csdap.ts:31 branch on that substring.
                 this.ledger.note(id, method, timeoutMs);
-                reject(new BridgeError("timeout", `Bridge request '${method}' timed out after ${timeoutMs}ms`));
+                // 🔴 THE ONE HOST-RAISED FAILURE THAT HAS A KNOWABLE CAUSE (262 §2). Everything
+                // else this class raises is genuinely opaque from here — a closed socket, a peer
+                // that never answered — but a timeout on the RUNTIME bridge has one cause the host
+                // can check for nothing: its own debugger holding the game. See `setHoldProbe`.
+                reject(new BridgeError("timeout", `Bridge request '${method}' timed out after ${timeoutMs}ms`, this.holdProbe?.() ?? undefined));
             }, timeoutMs);
             this.pending.set(id, { resolve: resolve, reject, timer, method });
             socket.write(payload, (err) => {

package/dist/confirm.js

@@ -50,14 +50,53 @@ export async function gate(server, confirm, summary) {
             content: [{ type: "text", text: `Cancelled — user did not approve: ${summary}` }],
         };
     }
-    catch {
+    catch (err) {
+        // 🔴 261 — ONE `catch` WAS COVERING THREE DIFFERENT CAUSES AND NAMING THE THIRD.
+        //
+        // Measured at 261 against the published 1.76.0: a client that DECLARES elicitation
+        // and then answers with content that does not satisfy `requestedSchema` gets
+        // "interactive confirmation isn't available on this client" — a sentence about the
+        // client's CAPABILITIES, printed because of a bad ANSWER — followed by the one
+        // remedy that skips the confirmation the user was in the middle of giving. That is
+        // 260's standing rule ("a diagnostic that names a state is not a diagnosis of its
+        // cause") landing on the safety control itself, and the misdiagnosis points at the
+        // bypass, which is the wrong direction for a gate to fail in.
+        //
+        // The capability is knowable, so ask instead of inferring it from a throw. Only the
+        // genuinely unsupported client is told to re-run with `confirm: true`; a client that
+        // CAN ask and failed is told the attempt failed and why, because the next action
+        // there is to fix the answer, not to bypass the prompt.
+        const supportsElicitation = (() => {
+            try {
+                return !!server.server.getClientCapabilities()?.elicitation;
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (!supportsElicitation) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `This is a destructive action (${summary}) and interactive confirmation ` +
+                            `isn't available on this client. Re-run the tool with confirm: true to proceed.`,
+                    },
+                ],
+            };
+        }
+        const detail = err instanceof Error ? err.message : String(err);
         return {
             isError: true,
             content: [
                 {
                     type: "text",
-                    text: `This is a destructive action (${summary}) and interactive confirmation ` +
-                        `isn't available on this client. Re-run the tool with confirm: true to proceed.`,
+                    text: `This is a destructive action (${summary}) and NOTHING WAS DONE. This client ` +
+                        `declares elicitation support, so the confirmation prompt was sent and the ` +
+                        `attempt failed: ${detail}. Fix the client's elicitation response (it must be ` +
+                        `{"action":"accept","content":{"proceed":true}}) and retry — or, if you mean to ` +
+                        `skip the prompt deliberately, re-run with confirm: true.`,
                 },
             ],
         };

package/dist/dap.js

@@ -113,6 +113,23 @@ export class DapClient extends EventEmitter {
     stoppedNow() {
         return this.state === "stopped";
     }
+    /**
+     * Whether there is a FRAME to answer from — the public half of `stoppedNow()`.
+     *
+     * 🔴 `hasSession` IS NOT THIS, AND THE DIFFERENCE IS A WHOLE FAMILY OF DEFECTS (262 §1).
+     * The `dbg_*` tools consulted `hasSession` — *did a launch succeed* — and then asked the
+     * adapter for a stack, a scope, a variable or a step. With a session live and the program
+     * RUNNING, measured against a real 4.7 adapter, that produced eight different answers to
+     * one question: `{"frames":[]}` and `{"scopes":[]}` (empty successes), a `dbg_watch` entry
+     * carrying a fabricated `error:"timeout"` after 5 s, a 15 s wait per `dbg_step` /
+     * `dbg_continue` ending in `{"state":"running"}`, and a `dbg_set_variable` refusal blaming
+     * the user's Godot build. ~48 s of adapter round trips for a question answerable here in
+     * none. A session existing is a PROXY for a frame existing, and the two part company the
+     * moment the program is not at a stop — 261's rule, one plane over.
+     */
+    get isStopped() {
+        return this.stoppedNow();
+    }
     constructor(host, port, timeoutMs) {
         super();
         this.timeoutMs = timeoutMs;

package/dist/index.js

@@ -9,6 +9,7 @@ import { CsLspClient } from "./cslsp.js";
 import { CsDapClient } from "./csdap.js";
 import { StdioChannel } from "./stdio.js";
 import { DapClient } from "./dap.js";
+import { DEBUGGER_HOLD_REMEDY } from "./remedies.js";
 import { fullUsage } from "./cli/usage.js";
 import { buildToolsets } from "./toolsets.js";
 import { registerRecipes } from "./recipes.js";
@@ -36,6 +37,11 @@ async function main() {
     // installed starts and runs the other planes unaffected.
     const csLsp = new CsLspClient(new StdioChannel(config.csLspCmd, config.csLspArgs, config.csLspProjectPath, "C# LSP (OmniSharp)", "Is OmniSharp installed and on PATH (or set GODOT_CSLSP_CMD to its binary), and GODOT_CSHARP_PROJECT pointed at a restored C# project?"), config.csLspProjectUri, config.csLspTimeoutMs);
     const dap = new DapClient(config.dapHost, config.dapPort, config.dapTimeoutMs);
+    // 🔴 THE ONE PLACE BOTH HALVES OF THE DEADLOCK ARE IN SCOPE (262 §2). The runtime
+    // bridge cannot see the debugger and the debugger cannot see the bridge; index.ts holds
+    // both, so the join is made here and nowhere else. Wired on `runtime` alone — the game
+    // being stopped says nothing about the editor bridge on plane A.
+    runtime.setHoldProbe(() => (dap.isStopped ? DEBUGGER_HOLD_REMEDY : undefined));
     // D4 C3: the C# debugging plane. netcoredbg is spawned over stdio (lazily, on
     // the first cs_dbg_* call) — so a host without netcoredbg installed starts and
     // runs every other plane unaffected.
@@ -44,7 +50,7 @@ async function main() {
     // so long jobs (export/import/headless script) support poll/await/cancel.
     // D3: also advertise resources.subscribe so clients can subscribe to
     // godot://… resources and receive notifications/resources/updated.
-    const server = new McpServer({ name: "breakpoint-mcp", version: "1.76.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.77.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // 208 §7.1 — delete from the wire what the protocol already says: the SDK's
     // draft-07 `$schema` inside every input/output schema (MCP's default dialect is
     // 2020-12, and declaring another is an explicit switch a peer may reject), and

package/dist/remedies.js

@@ -60,4 +60,22 @@ export function remedyForWireError(code, fromWire) {
         return fromWire;
     return HOST_FALLBACK_REMEDIES[code];
 }
+/**
+ * The next action when the runtime bridge went quiet because OUR debugger stopped the game.
+ *
+ * 🔴 NOT A ROW IN THE TABLE ABOVE, and the distinction is the whole reason this file's
+ * one-row ceiling can survive a second sentence being added to the module. That table is
+ * keyed by a CODE THE ADDON RAISES — check 28 joins every key to an `_err(..)` site on an
+ * engine plane, and a `timeout` key would have no such site to join to, because nothing in
+ * the engine raised it. This is the opposite population: a failure the HOST invents when a
+ * peer says nothing, keyed on a piece of state only the host holds. Keyed on a code it
+ * would be wrong — most `timeout`s have nothing to do with the debugger — so it is emitted
+ * only when `dap.isStopped` is true at the moment the deadline fires.
+ *
+ * Written to the same grammar check 28 enforces next door, because it reaches the same
+ * reader through the same clause: one imperative at the head, backticked names that resolve,
+ * a full stop at the end.
+ */
+export const DEBUGGER_HOLD_REMEDY = "Release the game with `dbg_continue` — it is stopped at a breakpoint, and the addon answers `runtime_*` calls from `_process`, " +
+    "so the frame that owes this reply cannot run until execution resumes.";
 //# sourceMappingURL=remedies.js.map

package/dist/tools/dap.js

@@ -166,6 +166,41 @@ export function registerDapTools(server, dap, cfg) {
             `There is none, so any state, frame or scope reported here would be invented — ` +
             `this call previously answered as if the program were running.`, "no_session");
     };
+    /**
+     * Refuse when the session is live but the program is not AT A STOP.
+     *
+     * 🔴 THE HALF `requireSession` COULD NOT SEE, AND IT IS THE SAME MISTAKE ONE LAYER IN.
+     * That guard asks whether a launch succeeded; every tool below then asked the adapter
+     * for a frame. A session existing is a proxy for a frame existing, and the proxy stops
+     * holding the instant the program runs on. Measured against a live 4.7 adapter with a
+     * launched session and nothing stopped — nine tools, eight different answers, none of
+     * them "the program is running":
+     *
+     * ```
+     * dbg_stack_trace     4ms   {"frames":[]}                    empty success
+     * dbg_scopes          8ms   {"scopes":[]}                    empty success
+     * dbg_variables      10ms   DAP error [variables]: unknown   the adapter's word for it
+     * dbg_watch        5,016ms  error:"timeout" per expression   a fabricated cause
+     * dbg_evaluate     5,019ms  DAP error [evaluate]: timeout    a fabricated cause
+     * dbg_set_variable 8,004ms  "this Godot build (e.g. 4.3)…"   blames the user's engine
+     * dbg_step        15,004ms  {"state":"running"}              a success that waited
+     * dbg_continue    15,003ms  {"state":"running"}              a success that waited
+     * ```
+     *
+     * 🔴 RAISED BEFORE THE ADAPTER ROUND TRIP, which is most of the point: that column of
+     * timeouts is ~48 s the caller waited to be told nothing, for a question `dap.isStopped`
+     * answers in none. `dbg_launch`'s scene guard is placed the same way and for the same
+     * reason. The refusal names the state it read rather than the state it assumed — 260's
+     * rule — and names the two ways to reach a stop, because "not stopped" is not itself an
+     * instruction.
+     */
+    const requireStopped = (tool) => {
+        if (dap.isStopped)
+            return;
+        throw new DapRefusal(`${tool} needs the program stopped at a breakpoint: the debug session is live but the program is ${dap.state}. ` +
+            `Arm a line with dbg_set_breakpoints and trigger that code path, or step from a stop you already have — ` +
+            `nothing here can be read from a program that is still running.`, "not_stopped");
+    };
     /**
      * Report, on a launch/attach result, any breakpoint modifier the handshake dropped
      * when it applied the buffered breakpoints.
@@ -376,11 +411,13 @@ export function registerDapTools(server, dap, cfg) {
     server.registerTool("dbg_continue", {
         title: "Continue",
         description: "Resume execution and wait for the program to settle again (next breakpoint or termination). " +
-            "Returns the resulting state; if it runs on with no further breakpoint, reports state 'running'.",
+            "Returns the resulting state; if it runs on with no further breakpoint, reports state 'running'. " +
+            "Requires a stop; a running program is refused (`not_stopped`).",
         inputSchema: {},
     }, async () => {
         try {
             requireSession("dbg_continue");
+            requireStopped("dbg_continue");
             const r = await dap.resume("continue", { threadId: dap.threadId() }, RESUME_WAIT_MS);
             return ok({ state: r.state, stopped_reason: r.reason });
         }
@@ -391,11 +428,13 @@ export function registerDapTools(server, dap, cfg) {
     server.registerTool("dbg_step", {
         title: "Step",
         description: "Step execution: 'over' (next), 'in' (stepIn), or 'out' (stepOut), then wait for the step to land. " +
-            "Returns the resulting state and stop reason. Note: stepOut may be unsupported on older Godot builds.",
+            "Returns the resulting state and stop reason. Note: stepOut may be unsupported on older Godot builds. " +
+            "Requires a stop; a running program is refused (`not_stopped`).",
         inputSchema: { kind: z.enum(["in", "over", "out"]).describe("Step kind") },
     }, async ({ kind }) => {
         try {
             requireSession("dbg_step");
+            requireStopped("dbg_step");
             const command = kind === "in" ? "stepIn" : kind === "out" ? "stepOut" : "next";
             const r = await dap.resume(command, { threadId: dap.threadId() }, RESUME_WAIT_MS);
             return ok({ state: r.state, stopped_reason: r.reason });
@@ -406,11 +445,13 @@ export function registerDapTools(server, dap, cfg) {
     });
     server.registerTool("dbg_stack_trace", {
         title: "Stack trace",
-        description: "Return the current call stack (only meaningful while stopped at a breakpoint).",
+        description: "Return the current call stack. Requires a stop; a running program is refused (`not_stopped`) rather than " +
+            "answered with the empty frame list it used to return.",
         inputSchema: { levels: z.number().int().positive().optional().describe("Max frames (default 20)") },
     }, async ({ levels }) => {
         try {
             requireSession("dbg_stack_trace");
+            requireStopped("dbg_stack_trace");
             const body = await dap.request("stackTrace", { threadId: dap.threadId(), startFrame: 0, levels: levels ?? 20 });
             const frames = Array.isArray(body["stackFrames"])
                 ? body["stackFrames"].map((f) => ({
@@ -425,11 +466,13 @@ export function registerDapTools(server, dap, cfg) {
     });
     server.registerTool("dbg_scopes", {
         title: "Scopes",
-        description: "Return the variable scopes (Locals, Members, Globals) for a stack frame.",
+        description: "Return the variable scopes (Locals, Members, Globals) for a stack frame. Requires a stop; a running program is " +
+            "refused (`not_stopped`) rather than answered with an empty list.",
         inputSchema: { frame_id: z.number().int().describe("Frame id from dbg_stack_trace") },
     }, async ({ frame_id }) => {
         try {
             requireSession("dbg_scopes");
+            requireStopped("dbg_scopes");
             const body = await dap.request("scopes", { frameId: frame_id });
             const scopes = Array.isArray(body["scopes"])
                 ? body["scopes"].map((s) => ({ name: s.name ?? "", variables_ref: s.variablesReference ?? 0 }))
@@ -442,11 +485,13 @@ export function registerDapTools(server, dap, cfg) {
     });
     server.registerTool("dbg_variables", {
         title: "Variables",
-        description: "List variables under a scope or a complex value (via its variables_ref).",
+        description: "List variables under a scope or a complex value (via its variables_ref). Requires a stop (`not_stopped`) — a " +
+            "reference is only valid within the stop that issued it.",
         inputSchema: { variables_ref: z.number().int().describe("variablesReference from dbg_scopes or a parent variable") },
     }, async ({ variables_ref }) => {
         try {
             requireSession("dbg_variables");
+            requireStopped("dbg_variables");
             const body = await dap.request("variables", { variablesReference: variables_ref });
             const variables = Array.isArray(body["variables"])
                 ? body["variables"].map((v) => ({
@@ -461,7 +506,8 @@ export function registerDapTools(server, dap, cfg) {
     });
     server.registerTool("dbg_evaluate", {
         title: "Evaluate expression",
-        description: "Evaluate a GDScript expression in the context of a stopped frame. DESTRUCTIVE: arbitrary code execution — confirm with the user and keep this capability gated.",
+        description: "Evaluate a GDScript expression in the context of a stopped frame. DESTRUCTIVE: arbitrary code execution — confirm with the user and keep this capability gated. " +
+            "Requires a stop (`not_stopped`), checked before the confirmation prompt.",
         inputSchema: {
             expression: z.string().describe("GDScript expression to evaluate"),
             frame_id: z.number().int().optional().describe("Frame id (from dbg_stack_trace); omit for the top frame"),
@@ -471,7 +517,11 @@ export function registerDapTools(server, dap, cfg) {
         try {
             // Before the gate on purpose: the old order prompted the operator to approve
             // arbitrary code execution against a session that had never been started.
+            // 🔴 And before it for the second reason too — a program that is running has no
+            // frame to evaluate in, so the prompt was asking the operator to approve code
+            // execution that could only end in the adapter's 5 s silence.
             requireSession("dbg_evaluate");
+            requireStopped("dbg_evaluate");
             const blocked = await gate(server, confirm, `Evaluate expression in the running game: ${expression}`);
             if (blocked)
                 return blocked;
@@ -513,12 +563,34 @@ export function registerDapTools(server, dap, cfg) {
     }, async ({ add, remove, clear, frame_id }) => {
         try {
             requireSession("dbg_watch");
+            // 🔴 THE ONE TOOL HERE THAT IS NOT REFUSED WHEN THE PROGRAM RUNS, ON PURPOSE (262 §1).
+            // `dbg_watch` is two things at once: it MANAGES a persistent set and it evaluates that
+            // set. §10 B step 6's documented use — "dbg_watch for an expression across stops" — is
+            // to arm the set once and re-read it at each stop, so refusing the mutation while the
+            // program runs would refuse the workflow the guide teaches. The set change is applied;
+            // only the VALUES are unavailable, and the entry's own `error` field says which — the
+            // shape already carries a per-expression reason, so this needs no new key and, unlike
+            // what it replaces, costs no adapter round trip.
             if (clear)
                 dap.clearWatches();
             if (remove && remove.length)
                 dap.removeWatches(remove);
             if (add && add.length)
                 dap.addWatches(add);
+            if (!dap.isStopped) {
+                // 🔴 What this replaces was worse than empty: each expression came back with
+                // `error: "timeout"` after the adapter sat on it for the full evaluate deadline —
+                // 5 s of waiting for a fabricated cause. The program was never stopped; the adapter
+                // had nothing to answer from and said so by saying nothing.
+                return ok({
+                    watches: dap.listWatches().map((expression) => ({
+                        expression,
+                        value: "",
+                        type: "",
+                        error: `not stopped (${dap.state}) — a watch is evaluated in a stopped frame, so values arrive at the next stop`,
+                    })),
+                });
+            }
             // Bound each watch's evaluate to the short deadline (mirrors dbg_evaluate): a watch
             // expression the adapter never answers fails fast on that entry instead of hanging the
             // full dapTimeoutMs (20 s) at every stop, while other watches still resolve normally.
@@ -582,6 +654,7 @@ export function registerDapTools(server, dap, cfg) {
         try {
             // Before the gate and the caps check on purpose — see dbg_evaluate.
             requireSession("dbg_set_variable");
+            requireStopped("dbg_set_variable");
             // Feature-detect: some debug adapters don't implement setVariable. If the
             // adapter explicitly advertised it as unsupported, say so plainly instead
             // of prompting for a confirmation and then failing.
@@ -594,10 +667,18 @@ export function registerDapTools(server, dap, cfg) {
             const blocked = await gate(server, confirm, `Set variable ${name} = ${value} in the running game`);
             if (blocked)
                 return blocked;
-            // Godot 4.3 advertises supportsSetVariable=true (so the caps short-circuit above does
-            // not fire) but never answers the setVariable request. Caps can't detect that — 4.3
-            // lies — so bound the request to a short deadline and, on timeout, say plainly that the
-            // build does not implement setVariable rather than emitting the generic 20 s DAP timeout.
+            // Godot advertises supportsSetVariable=true (so the caps short-circuit above does not
+            // fire) and never answers the setVariable request. Caps can't detect that — the adapter
+            // lies — so bound the request to a short deadline and, on timeout, say plainly that this
+            // adapter does not implement setVariable rather than emitting the generic 20 s DAP timeout.
+            //
+            // 🔴 THE SENTENCE USED TO BLAME THE READER'S ENGINE, AND IT WAS MEASURABLY WRONG (262 §3).
+            // It read "this Godot build (e.g. 4.3) does not implement setVariable", written when 4.3
+            // was the build in hand. Measured twice at a REAL stop on **4.7** — the newest build there
+            // is — the request is advertised and still unanswered, so the only sentence this tool has
+            // ever emitted told a current-build user they were behind. The naming is now the adapter,
+            // not the reader's version: no `dbg_*` caller can act on "upgrade", because there is
+            // nothing to upgrade to.
             let body;
             try {
                 body = await dap.request("setVariable", { variablesReference: variables_ref, name, value }, cfg.dapSetVarTimeoutMs);
@@ -606,7 +687,7 @@ export function registerDapTools(server, dap, cfg) {
                 if (isDapTimeout(err)) {
                     return {
                         isError: true,
-                        content: [{ type: "text", text: `The debug adapter advertises supportsSetVariable but did not answer the setVariable request within ${cfg.dapSetVarTimeoutMs}ms — this Godot build (e.g. 4.3) does not implement setVariable. No change was made; the variable is unchanged. Read-only inspection (dbg_variables) still works.` }],
+                        content: [{ type: "text", text: `The debug adapter advertises supportsSetVariable but did not answer the setVariable request within ${cfg.dapSetVarTimeoutMs}ms — Godot's GDScript debug adapter does not implement it (measured unanswered on 4.3 and on 4.7, at a real stop). No change was made; the variable is unchanged. Read-only inspection (dbg_variables) still works, and dbg_evaluate can read the value.` }],
                     };
                 }
                 throw err;
@@ -678,6 +759,13 @@ export function registerDapTools(server, dap, cfg) {
         },
     }, async ({ path, line, target_id, confirm }) => {
         try {
+            // Before the caps check, the same order `dbg_set_variable` uses: a guard that
+            // holds on every adapter outranks one that reports this adapter's answer. 262
+            // added the pair here — `dbg_goto` had NEITHER, and "unreachable behind the
+            // capability gate" is the same argument the escape guard above was written
+            // against three sessions earlier.
+            requireSession("dbg_goto");
+            requireStopped("dbg_goto");
             if (!dap.capabilities || dap.capabilities["supportsGotoTargetsRequest"] !== true) {
                 return {
                     isError: true,
@@ -742,6 +830,14 @@ export function registerDapTools(server, dap, cfg) {
         },
     }, async ({ watch }) => {
         try {
+            // 🔴 SESSION ONLY, NOT STOPPED — and the asymmetry with `dbg_goto` above is the
+            // point rather than an oversight. `goto` moves the program counter *within the
+            // current stopped frame*, which is meaningless without one. A data breakpoint is
+            // ARMED for the future: a `variables_ref` naming a live scope does need a stop,
+            // but a bare global `name` resolves without one, and refusing the whole tool
+            // would refuse the case that works. Each entry already reports its own
+            // `unresolved` reason, which is where a ref that needed a frame says so.
+            requireSession("dbg_data_breakpoints");
             if (!dap.capabilities || dap.capabilities["supportsDataBreakpoints"] !== true) {
                 return {
                     isError: true,

package/dist/tools/editor/introspection.js

@@ -28,6 +28,41 @@ import { fail } from "./common.js";
  * frame; the tab tools only give the caller somewhere to go when it bites.
  */
 const MIN_RENDERED_VIEWPORT_PX = 8;
+/**
+ * 🔴 261 — THE SIZE GUARD ABOVE FIRES ONCE PER EDITOR SESSION AND THEN NEVER AGAIN,
+ * AND WHAT IT STOPS PROTECTING AGAINST IS WORSE THAN WHAT IT CATCHES.
+ *
+ * Measured at 261 on Godot 4.7, driving the published `breakpoint-mcp@1.76.0` as a
+ * client against a live editor. Godot collapses a main-screen tab's viewport to 2x2
+ * only while that tab has **never been activated**. Visit it once — which is step 5
+ * of the User Guide's own scene-authoring recipe — and the viewport keeps its full
+ * size for the rest of the session while it is hidden. It also stops updating:
+ *
+ *   tab 2D, capture 2d  -> 2214x1809  md5 4dcacd9ac2ce
+ *   tab 3D, capture 2d  -> 2214x1809  md5 4dcacd9ac2ce   (same frame, now hidden)
+ *   add a 900x700 magenta ColorRect to the scene, still on the 3D tab
+ *   tab 3D, capture 2d  -> 2214x1809  md5 4dcacd9ac2ce   🔴 UNCHANGED — frozen
+ *   tab 2D, capture 2d  -> 2214x1809  md5 b2075a8606e7   the rect is there
+ *
+ * So after the first tab switch every capture of the inactive viewport is a
+ * SUCCESS carrying a stale frame, and `MIN_RENDERED_VIEWPORT_PX` cannot see it,
+ * because the size is the one thing that did not change. An assistant reads that
+ * image as the current scene and edits against a picture of the past.
+ *
+ * The size threshold is a proxy for a question the editor can answer directly —
+ * *is the viewport I am capturing the one that is on screen?* — so ask that
+ * instead, and keep the size check underneath it as the second line for the
+ * never-visited case that reaches this code with a matching tab.
+ *
+ * 🔴 THE UNIT TEST THAT PINS THE SIZE GUARD FEEDS A MOCKED 2x2 THROUGH A FAKE
+ * BRIDGE. It is a true test of the branch and it is structurally unable to observe
+ * the engine behaviour the branch is a model of — which is why this survived from
+ * 1.30.0 to 1.76.0 with a green suite over it the whole way.
+ *
+ * Best-effort by construction: an addon too old to answer `main_screen.get`
+ * (pre-1.9.3) degrades to the size check alone rather than losing the capture.
+ */
+const VIEWPORT_TAB = { "2d": "2D", "3d": "3D" };
 /** Editor selection, ClassDB / docs lookups, and viewport screenshot. */
 export function registerIntrospectionTools(server, call, bridge) {
     server.registerTool("selection_get", { title: "Get selection", description: "Return the paths of the nodes currently selected in the editor.", inputSchema: {} }, async () => call("selection.get"));
@@ -98,26 +133,46 @@ export function registerIntrospectionTools(server, call, bridge) {
     server.registerTool("screenshot_editor", {
         title: "Screenshot editor viewport",
         description: "Capture the 2D or 3D editor viewport as a PNG and return it as image content so the assistant can see the scene. " +
-            "Requires the matching editor tab (2D/3D) to be active: Godot collapses the inactive tab's viewport to a few " +
-            "pixels, and this tool returns a viewport_not_rendered error rather than that placeholder frame. " +
-            "A fresh editor is on the 3D tab and opening a scene does NOT switch it, so to capture 2d reliably call " +
-            'main_screen_set {"name":"2D"} first — or main_screen_get to see which tab is active.',
+            "The requested viewport's tab must be the ACTIVE main-screen tab, and this tool refuses with " +
+            "viewport_not_active when it is not: a hidden tab's viewport either collapses to a few pixels (before its " +
+            "first visit) or keeps rendering the frame it had when it was hidden (after), and the second case is a " +
+            "full-size stale image that looks exactly like a good capture. " +
+            'A fresh editor is on the 3D tab and opening a scene does NOT switch it, so to capture 2d call ' +
+            'main_screen_set {"name":"2D"} first AND pass {"viewport":"2d"} — the default is 3d, so switching the tab ' +
+            "alone captures the tab you just left. main_screen_get reports which tab is active.",
         inputSchema: { viewport: z.enum(["2d", "3d"]).optional().describe("Which viewport (default 3d)") },
     }, async ({ viewport }) => {
         try {
-            const r = (await bridge.request("screenshot.editor_viewport", { viewport: viewport ?? "3d" }));
+            const want = viewport ?? "3d";
+            // 🔴 261 — ASK THE EDITOR WHICH TAB IS ON SCREEN BEFORE READING A TEXTURE.
+            // The size check below cannot separate "hidden and frozen" from "visible and
+            // unchanged", because after a tab's first visit those two states have the same
+            // dimensions. This one can, and it is the question the caller actually means.
+            // Degrades on an addon too old to answer, rather than refusing the capture.
+            let activeTab;
+            try {
+                const s = (await bridge.request("main_screen.get", {}));
+                if (s?.active)
+                    activeTab = s.active;
+            }
+            catch { /* pre-1.9.3 addon — fall through to the size check alone */ }
+            if (activeTab && VIEWPORT_TAB[want] && activeTab.toUpperCase() !== VIEWPORT_TAB[want]) {
+                return fail({
+                    code: "viewport_not_active",
+                    message: `The ${want} editor viewport is not on screen — the editor is on the "${activeTab}" tab. Godot keeps a ` +
+                        `hidden tab's viewport alive but stops drawing to it, so capturing it now returns the frame it held when ` +
+                        `it was hidden, at full size and with no sign that it is stale. Call main_screen_set ` +
+                        `{"name":"${VIEWPORT_TAB[want]}"} and retry, or capture the active tab with ` +
+                        `screenshot_editor {"viewport":"${activeTab.toLowerCase()}"}.`,
+                });
+            }
+            const r = (await bridge.request("screenshot.editor_viewport", { viewport: want }));
             if (r.width < MIN_RENDERED_VIEWPORT_PX || r.height < MIN_RENDERED_VIEWPORT_PX) {
                 // Name the tab that is ACTUALLY active rather than leaving the caller to infer
-                // it from a 2x2. Best-effort: this error must survive an addon too old to answer
-                // (main_screen.* is 1.9.3+), so a failure here degrades the message instead of
-                // replacing a useful "not rendered" error with an unrelated bridge error.
-                let active;
-                try {
-                    const s = (await bridge.request("main_screen.get", {}));
-                    if (s?.active)
-                        active = s.active;
-                }
-                catch { /* older addon, or no main-screen container — fall through */ }
+                // it from a 2x2. 261: the read now happens ABOVE, before the capture, so this
+                // arm reuses it — an addon too old to answer leaves it undefined and the message
+                // degrades exactly as it did before.
+                const active = activeTab;
                 return fail({
                     code: "viewport_not_rendered",
                     message: `The ${r.viewport} editor viewport measured ${r.width}x${r.height} — a collapsed viewport, not a rendered ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.76.0",
+  "version": "1.77.0",
   "description": "MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model, captured console output, and MCP resources.",
   "type": "module",
   "license": "MIT",