breakpoint-mcp 1.78.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 = [];
@@ -117,10 +127,16 @@ export class CsDapClient extends EventEmitter {
             this.state = "terminated";
             this.configured = false;
             this.sessionStarted = false;
-            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, 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");

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.78.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/package.json

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