breakpoint-mcp 1.77.0 → 1.78.1

package/dist/bridge.js

@@ -4,13 +4,23 @@ import { log } from "./logger.js";
 import { OverdueLedger } from "./late-reply.js";
 import { findNonFinite, describeNonFinite, tolerate, TOLERANT_METHODS } from "./finiteness.js";
 import { remedyForWireError } from "./remedies.js";
+import { closeDetail, closeRemedy } from "./close-cause.js";
 export class BridgeError extends Error {
     code;
     /**
      * The next action the addon attached to this code (254). Optional by
-     * construction: the addon omits it for codes it has nothing to say about, and
-     * every failure the host raises itself — timeout, closed socket, non-finite —
-     * arrives without one, because the remedy for those is not the addon's to give.
+     * construction: the addon omits it for codes it has nothing to say about.
+     *
+     * 🔴 THE REST OF THIS SENTENCE WAS WRONG FOR TWO SESSIONS, AND 264 MEASURED IT. It
+     * read: *every failure the host raises itself — timeout, closed socket, non-finite —
+     * arrives without one, because the remedy for those is not the addon's to give.* The
+     * because-clause is true and the claim does not follow from it. 262 answered `timeout`;
+     * 264 answered `bridge_closed` off an errno that had been in hand at the close site the
+     * whole time. The census counted the rest: of 25 host-raised failures about the world,
+     * ONE carried a remedy in this field, SEVEN named a next action in their message where
+     * no reader counts it, and SEVENTEEN said nothing while holding an errno, a state
+     * machine or a registry the host owns. **Absent here means nobody has answered it yet,
+     * not that it is unanswerable.**
      */
     remedy;
     constructor(code, message, remedy) {
@@ -119,14 +129,22 @@ export class BridgeClient {
         this.hint = hint;
         this.secretProvider = secretProvider;
         this.ledger = new OverdueLedger("bridge", peerNoun, deadlineKnob);
+        // 🔴 KEPT, not just handed to the ledger (264). A dropped connection names the same
+        // peer a late reply does, and the two sentences drifting apart would be a bug nobody
+        // could see from either side.
+        this.peerNoun = peerNoun;
     }
+    /** Who answers this client — read by the close path and the late-reply ledger alike. */
+    peerNoun;
     /**
      * 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
+     * timeout arrives without one". 🔴 264 DISPROVED THE "TRUE FOR A CLOSED SOCKET" HALF —
+     * `onClose` had the errno in hand and read only its `message`, so a killed peer and an
+     * orderly shutdown arrived as one code and one sentence. NOT true here either, 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
@@ -328,12 +346,18 @@ export class BridgeClient {
         this.socket = null;
         // Name the transport error when there was one. The CODE stays `bridge_closed`
         // — callers and tests branch on it — but the message carries the errno.
-        const cause = this.lastSocketError;
+        const cause = this.lastSocketError ?? undefined;
         this.lastSocketError = null;
-        const detail = cause ? ` (${cause.message})` : "";
+        const detail = closeDetail(cause);
+        // 🔴 THE ERRNO WAS ALREADY HERE AND ONLY ITS `message` WAS READ (264 §3). A peer that
+        // was killed and a peer that shut down cleanly produced the SAME code and the SAME
+        // sentence, differing by one parenthetical nothing instructed the caller to act on.
+        // `cause.code` separates them, and this is the one close site whose class has a field
+        // to put the answer in — see close-cause.ts for the four that do not.
+        const remedy = closeRemedy(cause, this.peerNoun);
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
-            p.reject(new BridgeError("bridge_closed", `Bridge connection closed before a response arrived${detail}`));
+            p.reject(new BridgeError("bridge_closed", `Bridge connection closed before a response arrived${detail}`, remedy));
         }
         this.pending.clear();
         // Keep the push channel alive across editor restarts while subscriptions want it.
@@ -353,10 +377,14 @@ 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);
-                // 🔴 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`.
+                // 🔴 262 §2 CALLED THIS "THE ONE HOST-RAISED FAILURE THAT HAS A KNOWABLE CAUSE",
+                // and said everything else this class raises — "a closed socket, a peer that never
+                // answered" — is genuinely opaque from here. 264 MEASURED THAT AND IT IS FALSE FOR
+                // THE CLOSED SOCKET: `onClose` holds the socket `Error` and its errno separates a
+                // peer that was killed from one that shut down cleanly. It stays TRUE for this
+                // line — a peer that never answered really does leave nothing behind — which is
+                // why the one cause the host can supply comes from outside the socket: its own
+                // debugger holding the game. See `setHoldProbe`, and 264's census for the rest.
                 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 });

package/dist/close-cause.js

@@ -0,0 +1,98 @@
+/**
+ * What a dropped connection's errno discriminates, and the next action for each.
+ *
+ * 🔴 WHY THIS EXISTS — 264's census, which is the answer to a row nine sessions old.
+ * `BridgeError`'s own doc said every failure the host raises "arrives without one,
+ * because the remedy for those is not the addon's to give", and `setHoldProbe`'s said
+ * that was "true for a closed socket". **It is not true for a closed socket.** Measured
+ * against real sockets, three ways a peer can go:
+ *
+ * ```
+ * peer resetAndDestroy    code=ECONNRESET  syscall=read  message="read ECONNRESET"
+ * peer end()   cleanly    NULL — no socket error at all
+ * peer destroy()          NULL — no socket error at all
+ * ```
+ *
+ * and what a caller received for the last two was the SAME code and the SAME sentence,
+ * separated by a parenthesis:
+ *
+ * ```
+ * B  peer reset mid-request   bridge_closed  Bridge connection closed before a response arrived (read ECONNRESET)
+ * C  peer closed cleanly      bridge_closed  Bridge connection closed before a response arrived
+ * ```
+ *
+ * An editor that was killed and an addon that shut its socket on purpose are different
+ * next actions. The `Error` that tells them apart was already in hand at all five close
+ * sites — `framing.ts` hands the whole object to every one of them — and every one read
+ * `cause.message` and threw the rest away.
+ *
+ * 🔴 ONE MODULE, FIVE CALLERS, BECAUSE THE ALTERNATIVE IS FIVE COPIES OF A JUDGEMENT.
+ * `bridge.ts`, `dap.ts`, `csdap.ts`, `lsp.ts` and `cslsp.ts` each drop a connection the
+ * same way for the same reasons. A sentence pasted into five close handlers is five
+ * places for the errno list to drift.
+ *
+ * 🔴 AND WHAT IT DELIBERATELY DOES NOT DO. An errno outside the abrupt family gets NO
+ * remedy — not a hedge, not a generic one. 264 measured two families and can speak for
+ * two; `classifyClose` returns `"unclassified"` for the rest so a future session can find
+ * the population it did not cover instead of inheriting a sentence nobody measured.
+ * 260's rule: a diagnostic that names a state is not a diagnosis of its cause.
+ */
+/**
+ * Errnos that mean the peer went away WITHOUT closing the connection.
+ *
+ * ECONNRESET: the peer's stack sent RST — the process died or was killed mid-stream.
+ * EPIPE: we wrote to a connection the peer had already torn down.
+ * ECONNABORTED: the local stack aborted an established connection.
+ *
+ * All three say the same thing about the world — nobody hung up, somebody vanished —
+ * and none of them can be produced by an orderly shutdown.
+ */
+export const ABRUPT_CLOSE_CODES = new Set(["ECONNRESET", "EPIPE", "ECONNABORTED"]);
+/**
+ * Which of the three a close was. `undefined` means the socket ended with no error at
+ * all, which is what an orderly `end()` or `destroy()` looks like from this side.
+ */
+export function classifyClose(cause) {
+    if (!cause)
+        return "deliberate";
+    const code = cause.code;
+    if (typeof code === "string" && ABRUPT_CLOSE_CODES.has(code))
+        return "abrupt";
+    return "unclassified";
+}
+/**
+ * The next action, given who the peer was — or `undefined` when the errno does not
+ * determine one.
+ *
+ * Written to the grammar check 28 enforces on `error_remedies.gd`: one imperative at the
+ * head, a full stop at the end, and nothing named that does not resolve. `peer` is the
+ * noun each client already uses for whoever answers it — "the editor", "the running
+ * game", "the debug adapter", "the language server" — so the sentence names the thing the
+ * caller was actually talking to rather than a socket.
+ */
+export function closeRemedy(cause, peer) {
+    switch (classifyClose(cause)) {
+        case "abrupt":
+            // The errno is NOT repeated here: `closeDetail` has already put it in the sentence
+            // immediately to the left, and a caller reading `(read ECONNRESET) — … (ECONNRESET)`
+            // learns nothing from the second one.
+            return (`Restart ${peer} and retry — it went away without closing the connection, ` +
+                `so nothing here says whether this request ran.`);
+        case "deliberate":
+            return (`Check whether ${peer} is still running — it closed the connection in an orderly way ` +
+                `rather than dropping it, which is what a shutdown looks like from here.`);
+        default:
+            return undefined;
+    }
+}
+/**
+ * The parenthetical the five close handlers already built by hand, spelled once.
+ *
+ * Kept byte-identical to what shipped — ` (read ECONNRESET)` — because tests and users
+ * read it, and this change is about adding the next action, not about rewording the
+ * detail that was already right.
+ */
+export function closeDetail(cause) {
+    return cause ? ` (${cause.message})` : "";
+}
+//# sourceMappingURL=close-cause.js.map

package/dist/csdap.js

@@ -1,6 +1,16 @@
 import { EventEmitter } from "node:events";
 import { DapError } from "./dap.js";
 import { OverdueLedger } from "./late-reply.js";
+import { closeDetail, closeRemedy } from "./close-cause.js";
+/**
+ * Who answers this plane, in the words its late-reply ledger already uses.
+ *
+ * 🔴 ONE CONSTANT, TWO READERS (264). The ledger names this peer when a reply arrives
+ * late and `closeRemedy` names it when the connection drops. Two literals would let the
+ * same peer acquire two names on the same run, which is the class of drift 257's
+ * per-instance deadline noun was written to stop.
+ */
+const CSDAP_PEER = "the debug adapter";
 /**
  * How long `start()` waits for the entry `stopped` event when `stopAtEntry` was
  * requested. Bounded so an adapter that ignores stop-on-entry reports `running`
@@ -41,7 +51,7 @@ export class CsDapClient extends EventEmitter {
      * dropped. `seq` is monotonic and is never reset, so a seq is never reused and
      * a late response can only be its own request's.
      */
-    ledger = new OverdueLedger("C# DAP", "the debug adapter", "GODOT_CSDAP_TIMEOUT_MS");
+    ledger = new OverdueLedger("C# DAP", CSDAP_PEER, "GODOT_CSDAP_TIMEOUT_MS");
     configured = false;
     /** Persistent watch expressions, re-evaluated at each stop (see evaluateWatches). */
     watches = [];
@@ -53,10 +63,61 @@ export class CsDapClient extends EventEmitter {
      * being emitted as an unlistened `error` event (which throws).
      */
     startFailure = null;
+    /**
+     * Whether a launch/attach this client sent was accepted. Tracked SEPARATELY from
+     * `state` for the reason `DapClient` tracks it separately, measured here on this
+     * plane against a real netcoredbg: `cs_dbg_continue` on a client that had never
+     * launched anything left `state = "running"` behind — `resume()` assigns it
+     * optimistically before it waits — so every call after it read as a live session.
+     * A guard built on `state` alone would be poisoned by the very call it exists to
+     * refuse.
+     */
+    sessionStarted = false;
     capabilities = null;
     state = "disconnected";
     lastStoppedThreadId = null;
     lastStoppedReason = null;
+    /**
+     * Whether a launch/attach the adapter accepted is still in force. The `cs_dbg_*`
+     * tools that can only answer from a live session consult this instead of asking
+     * netcoredbg and reporting whatever came back.
+     *
+     * 🔴 Measured against a real netcoredbg 3.2.0-1092 on a client that had never
+     * launched anything: seven of the nine readers answered with a raw hex code —
+     * `Failed command 'stackTrace' : 0x80004005` (E_FAIL), `0x80070057` (E_INVALIDARG)
+     * — `cs_dbg_set_variable` reported "the debug adapter reported a failure with no
+     * message", and `cs_dbg_watch` answered `isError:false` with every entry carrying
+     * `error: "error: 0x80004005"`. Only `cs_dbg_restart` refused, and only because it
+     * happens to read `lastStartMode`. That is the same single exception session 259
+     * measured one plane over, for the same accidental reason.
+     */
+    get hasSession() {
+        return this.sessionStarted && this.state !== "terminated" && this.state !== "disconnected";
+    }
+    /**
+     * Whether the adapter has reported a stop, read through a call so TypeScript's
+     * control-flow narrowing does not collapse it — `state` is mutated by the event
+     * handler across every `await` in `start()`, so a literal comparison after an
+     * assignment is (wrongly) an impossible one to tsc. `DapClient.stoppedNow()`
+     * carries the same note for the same reason.
+     */
+    stoppedNow() {
+        return this.state === "stopped";
+    }
+    /**
+     * Whether there is a FRAME to answer from — the public half of `stoppedNow()`.
+     *
+     * 🔴 `hasSession` IS NOT THIS, and session 262 spent a whole session on the
+     * difference on the GDScript plane. Measured here with a session live and the
+     * program merely RUNNING: `stackTrace` 0x80070057, `scopes` / `variables` /
+     * `step` 0x80004005, `evaluate` 0x80070057, `set_variable` blaming the adapter,
+     * `watch` an `isError:false` answer whose every entry carried a hex code, and
+     * `cs_dbg_continue` waiting the full 15 s to answer `{"state":"running"}` —
+     * about 45 s of adapter round trips for a question answerable here in none.
+     */
+    get isStopped() {
+        return this.stoppedNow();
+    }
     constructor(channel, timeoutMs) {
         super();
         this.channel = channel;
@@ -65,10 +126,17 @@ export class CsDapClient extends EventEmitter {
         this.channel.onClose((cause) => {
             this.state = "terminated";
             this.configured = false;
-            const detail = cause ? ` (${cause.message})` : "";
+            this.sessionStarted = false;
+            const detail = closeDetail(cause);
+            // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), IN THE MESSAGE BECAUSE THIS CLASS
+            // HAS NOWHERE ELSE TO PUT IT. `DapError` carries no `remedy` field, and the plane's
+            // `fail()` renders no `remedyClause`, so the next action goes where the caller will
+            // actually read it. 264's census records the asymmetry rather than hiding it: of 25
+            // host-raised failures about the world, 13 are on classes that cannot carry an answer.
+            const remedy = closeRemedy(cause, CSDAP_PEER);
             for (const [, p] of this.pending) {
                 clearTimeout(p.timer);
-                p.reject(new DapError(p.command, `C# DAP connection closed${detail}`));
+                p.reject(new DapError(p.command, `C# DAP connection closed${detail}${remedy ? ` — ${remedy}` : ""}`));
             }
             this.pending.clear();
             this.emit("closed");
@@ -262,6 +330,7 @@ export class CsDapClient extends EventEmitter {
     async start(mode, args) {
         this.lastStartMode = mode;
         this.lastStartArgs = args;
+        this.sessionStarted = false;
         // Listen for `initialized` before we ask, so we cannot miss it.
         const onInit = this.waitEvent("initialized", Math.min(this.timeoutMs, 5000));
         this.capabilities = await this.request("initialize", {
@@ -287,6 +356,9 @@ export class CsDapClient extends EventEmitter {
         const startReq = this.request(mode, args).then(() => undefined, (err) => {
             this.startFailure = err;
             this.configured = false;
+            // A rejection arriving after `start()` returned ends the session, so the
+            // tools' session guard refuses from then on rather than reading `running`.
+            this.sessionStarted = false;
             this.state = "terminated";
             // A DISTINCT event name, deliberately: `error` is special-cased by
             // EventEmitter and throws when unlistened. This one is safe to ignore.
@@ -313,6 +385,7 @@ export class CsDapClient extends EventEmitter {
         const fatal = this.startFailure ?? (configureDoneAdvertised ? configureFailure : null);
         if (fatal) {
             this.configured = false;
+            this.sessionStarted = false;
             this.state = "terminated";
             void startReq;
             const detail = fatal?.message ?? String(fatal);
@@ -321,6 +394,7 @@ export class CsDapClient extends EventEmitter {
                 `${JSON.stringify(args).slice(0, 200)}).`);
         }
         this.configured = true;
+        this.sessionStarted = true;
         // 🔴 ONLY from `initialized`, never unconditionally. The adapter can emit `stopped`
         // (or `terminated`) between the configurationDone RESPONSE and this line, and the
         // event handler has already moved the state — a blind `= "running"` clobbers it and
@@ -430,6 +504,7 @@ export class CsDapClient extends EventEmitter {
         this.channel.close();
         this.state = "disconnected";
         this.configured = false;
+        this.sessionStarted = false;
     }
 }
 //# sourceMappingURL=csdap.js.map

package/dist/cslsp.js

@@ -1,7 +1,17 @@
 import { fileURLToPath } from "node:url";
 import { LspError } from "./lsp.js";
 import { OverdueLedger } from "./late-reply.js";
+import { closeDetail, closeRemedy } from "./close-cause.js";
 import { packageVersion } from "./version.js";
+/**
+ * Who answers this plane, in the words its late-reply ledger already uses.
+ *
+ * 🔴 ONE CONSTANT, TWO READERS (264). The ledger names this peer when a reply arrives
+ * late and `closeRemedy` names it when the connection drops. Two literals would let the
+ * same peer acquire two names on the same run, which is the class of drift 257's
+ * per-instance deadline noun was written to stop.
+ */
+const CSLSP_PEER = "the language server";
 /**
  * Minimal LSP client for the C#/.NET semantic plane (D4 C2). Transport-agnostic:
  * it drives any `JsonRpcChannel`, so production spawns OmniSharp over stdio
@@ -31,7 +41,7 @@ export class CsLspClient {
      * dropped. `nextId` is monotonic and is deliberately NOT reset by onClose(),
      * so an id is never reused and a late reply can only be its own request's.
      */
-    ledger = new OverdueLedger("C# LSP", "the language server", "GODOT_CSLSP_TIMEOUT_MS");
+    ledger = new OverdueLedger("C# LSP", CSLSP_PEER, "GODOT_CSLSP_TIMEOUT_MS");
     /** Absolute project root path (no trailing slash), used to canonicalize URIs. */
     rootFsPath;
     constructor(channel, rootUri, timeoutMs) {
@@ -128,9 +138,16 @@ export class CsLspClient {
         }
     }
     onClose(cause) {
+        const detail = closeDetail(cause);
+        // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), IN THE MESSAGE BECAUSE THIS CLASS
+        // HAS NOWHERE ELSE TO PUT IT. `LspError` carries no `remedy` field, and the plane's
+        // `fail()` renders no `remedyClause`, so the next action goes where the caller will
+        // actually read it. 264's census records the asymmetry rather than hiding it: of 25
+        // host-raised failures about the world, 13 are on classes that cannot carry an answer.
+        const remedy = closeRemedy(cause, CSLSP_PEER);
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
-            p.reject(new LspError("closed", `C# LSP connection closed${cause ? ` (${cause.message})` : ""}`));
+            p.reject(new LspError("closed", `C# LSP connection closed${detail}${remedy ? ` — ${remedy}` : ""}`));
         }
         this.pending.clear();
         this.initialized = null;

package/dist/dap.js

@@ -1,6 +1,16 @@
 import { EventEmitter } from "node:events";
 import { FramedConnection } from "./framing.js";
 import { OverdueLedger } from "./late-reply.js";
+import { closeDetail, closeRemedy } from "./close-cause.js";
+/**
+ * Who answers this plane, in the words its late-reply ledger already uses.
+ *
+ * 🔴 ONE CONSTANT, TWO READERS (264). The ledger names this peer when a reply arrives
+ * late and `closeRemedy` names it when the connection drops. Two literals would let the
+ * same peer acquire two names on the same run, which is the class of drift 257's
+ * per-instance deadline noun was written to stop.
+ */
+const DAP_PEER = "the debug adapter";
 export class DapError extends Error {
     command;
     constructor(command, message) {
@@ -73,7 +83,7 @@ export class DapClient extends EventEmitter {
      * dropped. `seq` is monotonic and is never reset, so a seq is never reused and
      * a late response can only be its own request's.
      */
-    ledger = new OverdueLedger("DAP", "the debug adapter", "GODOT_DAP_TIMEOUT_MS");
+    ledger = new OverdueLedger("DAP", DAP_PEER, "GODOT_DAP_TIMEOUT_MS");
     configured = false;
     /** Persistent watch expressions, re-evaluated at each stop (see evaluateWatches). */
     watches = [];
@@ -141,10 +151,16 @@ export class DapClient extends EventEmitter {
             // `cause` is the socket-level error when the drop had one (ECONNRESET, EPIPE).
             // Without it every pending request reported a generic close and the operator
             // could not tell a crashed server from something else holding the port.
-            const detail = cause ? ` (${cause.message})` : "";
+            const detail = closeDetail(cause);
+            // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), IN THE MESSAGE BECAUSE THIS CLASS
+            // HAS NOWHERE ELSE TO PUT IT. `DapError` carries no `remedy` field, and the plane's
+            // `fail()` renders no `remedyClause`, so the next action goes where the caller will
+            // actually read it. 264's census records the asymmetry rather than hiding it: of 25
+            // host-raised failures about the world, 13 are on classes that cannot carry an answer.
+            const remedy = closeRemedy(cause, DAP_PEER);
             for (const [, p] of this.pending) {
                 clearTimeout(p.timer);
-                p.reject(new DapError(p.command, `DAP connection closed${detail}`));
+                p.reject(new DapError(p.command, `DAP connection closed${detail}${remedy ? ` — ${remedy}` : ""}`));
             }
             this.pending.clear();
             this.emit("closed");

package/dist/index.js

@@ -50,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.77.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.78.1" }, { 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/lsp.js

@@ -2,6 +2,16 @@ import { fileURLToPath } from "node:url";
 import { FramedConnection } from "./framing.js";
 import { packageVersion } from "./version.js";
 import { OverdueLedger } from "./late-reply.js";
+import { closeDetail, closeRemedy } from "./close-cause.js";
+/**
+ * Who answers this plane, in the words its late-reply ledger already uses.
+ *
+ * 🔴 ONE CONSTANT, TWO READERS (264). The ledger names this peer when a reply arrives
+ * late and `closeRemedy` names it when the connection drops. Two literals would let the
+ * same peer acquire two names on the same run, which is the class of drift 257's
+ * per-instance deadline noun was written to stop.
+ */
+const LSP_PEER = "the language server";
 export class LspError extends Error {
     code;
     constructor(code, message) {
@@ -31,7 +41,7 @@ export class LspClient {
      * dropped. `nextId` is monotonic and is deliberately NOT reset by onClose(),
      * so an id is never reused and a late reply can only be its own request's.
      */
-    ledger = new OverdueLedger("LSP", "the language server", "GODOT_LSP_TIMEOUT_MS");
+    ledger = new OverdueLedger("LSP", LSP_PEER, "GODOT_LSP_TIMEOUT_MS");
     /** Absolute project root path (no trailing slash), used to canonicalize URIs. */
     rootFsPath;
     constructor(host, port, rootUri, timeoutMs) {
@@ -132,10 +142,16 @@ export class LspClient {
         // `cause` is the socket-level error when the drop had one (ECONNRESET, EPIPE).
         // Without it every pending request reported a generic close and the operator
         // could not tell a crashed server from something else holding the port.
-        const detail = cause ? ` (${cause.message})` : "";
+        const detail = closeDetail(cause);
+        // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), IN THE MESSAGE BECAUSE THIS CLASS
+        // HAS NOWHERE ELSE TO PUT IT. `LspError` carries no `remedy` field, and the plane's
+        // `fail()` renders no `remedyClause`, so the next action goes where the caller will
+        // actually read it. 264's census records the asymmetry rather than hiding it: of 25
+        // host-raised failures about the world, 13 are on classes that cannot carry an answer.
+        const remedy = closeRemedy(cause, LSP_PEER);
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
-            p.reject(new LspError("closed", `LSP connection closed${detail}`));
+            p.reject(new LspError("closed", `LSP connection closed${detail}${remedy ? ` — ${remedy}` : ""}`));
         }
         this.pending.clear();
         this.initialized = null;

package/dist/tools/csdap.js

@@ -105,6 +105,67 @@ const CS_DAP_PATHS = {
 };
 export function registerCsDapTools(server, dap, cfg) {
     const root = cfg.csDapProjectPath;
+    /**
+     * Refuse when no launch/attach the adapter accepted is in force.
+     *
+     * 🔴 Measured against a real netcoredbg 3.2.0-1092 on a client that had never
+     * launched anything. Nine readers, and the only one that refused did so by
+     * accident:
+     *
+     * ```
+     * cs_dbg_stack_trace   11ms  Failed command 'stackTrace' : 0x80004005
+     * cs_dbg_scopes         1ms  Failed command 'scopes' : 0x80004005
+     * cs_dbg_variables      1ms  Failed command 'variables' : 0x80004005
+     * cs_dbg_evaluate       1ms  error: 0x80004005
+     * cs_dbg_watch          1ms  isError:FALSE, every entry error "error: 0x80004005"
+     * cs_dbg_set_variable   1ms  "the debug adapter reported a failure with no message"
+     * cs_dbg_step           1ms  Failed command 'next' : 0x80004005
+     * cs_dbg_continue       0ms  Failed command 'continue' : 0x80004005
+     * cs_dbg_restart        1ms  refuses — because it reads `lastStartMode`
+     * ```
+     *
+     * `0x80004005` is E_FAIL and `0x80070057` is E_INVALIDARG: hex for "no", naming
+     * nothing the caller can act on and pointing at the adapter for a state the host
+     * already knew. The refusal names the two ways to open a session instead.
+     */
+    const requireSession = (tool) => {
+        if (dap.hasSession)
+            return;
+        refuse(`${tool} needs a C# debug session: call cs_dbg_launch or cs_dbg_attach first. ` +
+            `There is none, so any state, frame or scope reported here would be invented — ` +
+            `this call previously answered with the adapter's raw failure code.`, "no_session");
+    };
+    /**
+     * Refuse when the session is live but the program is not AT A STOP.
+     *
+     * 🔴 THE SAME PROXY, ONE PLANE OVER — session 262 §1's whole finding, ported after
+     * measuring it here rather than assumed. A session existing is a proxy for a frame
+     * existing, and the two part company the moment the program runs on. Measured with
+     * a launched session and nothing stopped:
+     *
+     * ```
+     * cs_dbg_stack_trace      2ms  Failed command 'stackTrace' : 0x80070057
+     * cs_dbg_scopes           1ms  Failed command 'scopes' : 0x80004005
+     * cs_dbg_variables        1ms  Failed command 'variables' : 0x80004005
+     * cs_dbg_evaluate         1ms  error: 0x80070057
+     * cs_dbg_set_variable     1ms  "the debug adapter reported a failure with no message"
+     * cs_dbg_step             1ms  Failed command 'next' : 0x80004005
+     * cs_dbg_continue    15,000ms  isError:FALSE  {"state":"running"}
+     * ```
+     *
+     * 🔴 RAISED BEFORE THE ADAPTER ROUND TRIP, which is most of the point: that 15 s —
+     * with `cs_dbg_restart`'s 30 s beside it — is time the caller spent being told
+     * nothing, for a question `dap.isStopped` answers in none. The refusal names the
+     * state it READ rather than the state it assumed, and names both ways to reach a
+     * stop, because "not stopped" is not itself an instruction.
+     */
+    const requireStopped = (tool) => {
+        if (dap.isStopped)
+            return;
+        refuse(`${tool} needs the program stopped at a breakpoint: the C# debug session is live but the program is ${dap.state}. ` +
+            `Arm a line with cs_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");
+    };
     /**
      * Resolve a breakpoint source path and REFUSE one that cannot carry a breakpoint.
      *
@@ -272,6 +333,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: {},
     }, async () => {
         try {
+            requireSession("cs_dbg_continue");
+            requireStopped("cs_dbg_continue");
             const r = await dap.resume("continue", { threadId: dap.threadId() }, RESUME_WAIT_MS);
             return ok({ state: r.state, stopped_reason: r.reason });
         }
@@ -286,6 +349,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: { kind: z.enum(["in", "over", "out"]).describe("Step kind") },
     }, async ({ kind }) => {
         try {
+            requireSession("cs_dbg_step");
+            requireStopped("cs_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 });
@@ -300,6 +365,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: { levels: z.number().int().positive().optional().describe("Max frames (default 20)") },
     }, async ({ levels }) => {
         try {
+            requireSession("cs_dbg_stack_trace");
+            requireStopped("cs_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) => ({
@@ -318,6 +385,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: { frame_id: z.number().int().describe("Frame id from cs_dbg_stack_trace") },
     }, async ({ frame_id }) => {
         try {
+            requireSession("cs_dbg_scopes");
+            requireStopped("cs_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 }))
@@ -334,6 +403,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: { variables_ref: z.number().int().describe("variablesReference from cs_dbg_scopes or a parent variable") },
     }, async ({ variables_ref }) => {
         try {
+            requireSession("cs_dbg_variables");
+            requireStopped("cs_dbg_variables");
             const body = await dap.request("variables", { variablesReference: variables_ref });
             const variables = Array.isArray(body["variables"])
                 ? body["variables"].map((v) => ({
@@ -357,6 +428,11 @@ export function registerCsDapTools(server, dap, cfg) {
         },
     }, async ({ expression, frame_id, confirm }) => {
         try {
+            // 🔴 BEFORE the confirmation prompt, not after. Asking the operator to approve
+            // an evaluate that cannot run — and that previously answered `0x80070057` when
+            // they approved it — spends their attention on a call already known to fail.
+            requireSession("cs_dbg_evaluate");
+            requireStopped("cs_dbg_evaluate");
             const blocked = await gate(server, confirm, `Evaluate C# expression in the running game: ${expression}`);
             if (blocked)
                 return blocked;
@@ -393,6 +469,11 @@ export function registerCsDapTools(server, dap, cfg) {
         },
     }, async ({ variables_ref, name, value, confirm }) => {
         try {
+            // Before the capability read as well as before the prompt: `capabilities` is
+            // null until `initialize`, so with no session the check below is a question
+            // asked of nobody.
+            requireSession("cs_dbg_set_variable");
+            requireStopped("cs_dbg_set_variable");
             if (dap.capabilities && dap.capabilities["supportsSetVariable"] === false) {
                 return {
                     isError: true,
@@ -436,12 +517,37 @@ export function registerCsDapTools(server, dap, cfg) {
         },
     }, async ({ add, remove, clear, frame_id }) => {
         try {
+            requireSession("cs_dbg_watch");
+            // 🔴 THE ONE READER HERE NOT REFUSED WHILE THE PROGRAM RUNS, ON PURPOSE — the
+            // same deliberate divergence session 262 made on the GDScript plane, for the
+            // same reason. `cs_dbg_watch` is two things at once: it MANAGES a persistent
+            // set and it evaluates that set, and this tool's own description teaches
+            // arming the set and re-reading it "after a step/continue". Refusing the
+            // mutation while the program runs would refuse the documented workflow.
+            // The set change is applied; only the VALUES are unavailable, and the entry's
+            // own `error` field says which.
             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. Measured against a real
+                // netcoredbg with no session and again with the program running: an
+                // `isError:false` answer whose every entry carried `error: "error:
+                // 0x80004005"` — a hex code offered to the caller as the reason their watch
+                // has no value. The reason is that the program is not stopped, the host
+                // knows it, and it costs no round trip to say so.
+                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 cs_dbg_evaluate): a watch
             // the adapter never answers fails fast on that entry instead of hanging the full DAP
             // timeout at every stop, while other watches still resolve normally.
@@ -468,6 +574,21 @@ export function registerCsDapTools(server, dap, cfg) {
             // Per the DAP spec a client should only send setExceptionBreakpoints when the adapter
             // advertised at least one exception filter. Short-circuit with a clear "unsupported"
             // message otherwise, matching the GDScript dbg_set_exception_breakpoints discipline.
+            // 🔴 "THE CONNECTED ADAPTER" MUST FIRST BE ONE. `capabilities` is null until
+            // `initialize`, so with no session this read found nothing and the tool told
+            // the caller their debugger advertises no exception filters. Measured against
+            // a real netcoredbg 3.2.0-1092: with no session it answered "unsupported by
+            // the connected C# debug adapter (it advertises no exceptionBreakpointFilters)"
+            // — while that same adapter advertises `all` and `user-unhandled`, which the
+            // cs-dap cohort asserts on every CI leg. A capability read is a question for
+            // somebody, and there was nobody. Session 262 §2 fixed this shape one plane
+            // over, where the message blamed the user's engine BUILD; here it blamed their
+            // debugger for a handshake that never happened.
+            //
+            // NOT `requireStopped`: exception filters are armed for the FUTURE, so a live
+            // running session is a legitimate caller — the same call `dbg_data_breakpoints`
+            // gets on the GDScript plane, and for the same reason.
+            requireSession("cs_dbg_set_exception_breakpoints");
             const advertised = dap.capabilities?.["exceptionBreakpointFilters"];
             const available_filters = Array.isArray(advertised)
                 ? advertised.map((f) => ({ filter: f.filter ?? "", label: f.label ?? "" }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.77.0",
+  "version": "1.78.1",
   "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",