breakpoint-mcp 1.26.0 → 1.27.0

package/dist/bridge.js

@@ -1,6 +1,7 @@
 import net from "node:net";
 import { randomUUID } from "node:crypto";
 import { log } from "./logger.js";
+import { OverdueLedger } from "./late-reply.js";
 export class BridgeError extends Error {
     code;
     constructor(code, message) {
@@ -32,6 +33,8 @@ export class BridgeClient {
     connecting = null;
     buffer = "";
     pending = new Map();
+    /** Ids whose deadline fired, so a reply arriving later is recognised, not dropped. */
+    ledger;
     eventListeners = new Set();
     wantConnected = false;
     reconnectTimer = null;
@@ -43,13 +46,25 @@ export class BridgeClient {
      * insecure or not-yet-provisioned bridge. Lazy so a secret minted after the
      * host started (editor launched later) is picked up on the next (re)connect.
      */
-    secretProvider) {
+    secretProvider, 
+    /**
+     * The env var that widens THIS instance's deadline, and the noun for what
+     * answered it. Per-INSTANCE, not per-class: index.ts builds two
+     * BridgeClients — the editor bridge and the runtime bridge — and they are
+     * configured by different variables (BREAKPOINT_BRIDGE_TIMEOUT_MS vs
+     * BREAKPOINT_RUNTIME_TIMEOUT_MS). A late-reply line that names the wrong one
+     * sends the operator to a knob that cannot move the deadline they just hit,
+     * which is worse than saying nothing. Defaults keep the editor bridge's
+     * wording byte-identical to what shipped.
+     */
+    deadlineKnob = "BREAKPOINT_BRIDGE_TIMEOUT_MS", peerNoun = "the editor") {
         this.host = host;
         this.port = port;
         this.defaultTimeoutMs = defaultTimeoutMs;
         this.label = label;
         this.hint = hint;
         this.secretProvider = secretProvider;
+        this.ledger = new OverdueLedger("bridge", peerNoun, deadlineKnob);
     }
     /** Register a listener for addon-pushed resource-change events. */
     onResourceChanged(cb) {
@@ -155,8 +170,16 @@ export class BridgeClient {
             return;
         }
         const id = msg.id;
-        if (!id || !this.pending.has(id))
+        if (!id)
             return;
+        if (!this.pending.has(id)) {
+            // Not pending: either a reply we already gave up on (reconcile + log it), or
+            // a genuinely unknown id (the addon's auth reply, a stale frame) — ignored
+            // exactly as before. Ids are randomUUID() and never reused, so a late reply
+            // can only ever be its OWN request's; misattribution is impossible here.
+            this.ledger.reconcile(id, msg.ok === true);
+            return;
+        }
         const p = this.pending.get(id);
         this.pending.delete(id);
         clearTimeout(p.timer);
@@ -168,6 +191,13 @@ export class BridgeClient {
             p.reject(new BridgeError(e.code, e.message));
         }
     }
+    /**
+     * Snapshot of replies that arrived after their deadline, oldest first.
+     * Diagnostics only — nothing in the request path reads this.
+     */
+    recentLateReplies() {
+        return this.ledger.recent();
+    }
     onClose() {
         this.socket = null;
         for (const [, p] of this.pending) {
@@ -187,6 +217,11 @@ export class BridgeClient {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
+                // Remember the id BEFORE rejecting, so a reply already in flight is
+                // reconciled rather than dropped as anonymous. The message keeps the
+                // 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`));
             }, timeoutMs);
             this.pending.set(id, { resolve: resolve, reject, timer });

package/dist/config.js

@@ -1,5 +1,6 @@
 import { pathToFileURL } from "node:url";
 import { parsePrivilegedGroups } from "./capabilities.js";
+import { log } from "./logger.js";
 /**
  * A TCP port from the environment, falling back to `fallback` when the variable
  * is absent, empty, non-numeric or out of range.
@@ -25,6 +26,91 @@ function port(raw, fallback) {
     const n = Number(t);
     return Number.isInteger(n) && n >= 0 && n <= 65535 ? n : fallback;
 }
+/**
+ * The floor below which a deadline on a FRAME-POLLED bridge is premature *by
+ * construction* rather than by luck.
+ *
+ * Both addons — `bridge_server.gd` and `runtime_bridge.gd` — poll their socket
+ * from `_process` and dispatch synchronously, so they cannot answer faster than
+ * one frame no matter how trivial the request. Any deadline shorter than a frame
+ * period is guaranteed to fire before a reply is possible. The editor throttles
+ * its main loop when idle or unfocused, so "one frame" is not the 16 ms a running
+ * game would suggest; 250 ms is a frame at any plausible editor framerate, with
+ * headroom.
+ *
+ * Below the floor we FALL BACK to the default rather than clamp up to it,
+ * matching how `positiveInt` already treats `0` and negatives. A silently
+ * adjusted config value is its own small dishonesty: the operator asked for
+ * something unusable, and the honest answer is the documented default, said out
+ * loud.
+ *
+ * **This applies to the two bridge deadlines ONLY, and that boundary is the
+ * whole point.** LSP, DAP and the asset-gen backend are ordinary
+ * request/response over TCP or stdio — nothing frame-polls them, and they answer
+ * in microseconds. A 200 ms DAP deadline is a perfectly reasonable "fail fast",
+ * not a broken one; `csdap.test.ts:301` sets exactly that and is right to. The
+ * justification for this floor is the frame poll, so its scope is the frame poll.
+ *
+ * **And it does not replace late-reply reconciliation in `bridge.ts`, nor can
+ * it.** A *legitimate* 15000 ms deadline fails identically the moment a frame
+ * outlasts it, which `bridge_server.gd:96` documents happening on a `scene.save`
+ * that triggers a rescan/reimport. The floor removes the configured cause; the
+ * ledger catches the consequence whatever the cause.
+ */
+export const MIN_TIMEOUT_MS = 250;
+/**
+ * A deadline for a frame-polled bridge: `positiveInt`, then the floor.
+ * Used for `bridgeTimeoutMs` and `runtimeTimeoutMs` — the two values that reach
+ * a `BridgeClient` — and deliberately not for anything else.
+ */
+function bridgeDeadlineMs(raw, fallback) {
+    const n = positiveInt(raw, fallback);
+    if (n >= MIN_TIMEOUT_MS)
+        return n;
+    log(`ignoring a ${n}ms bridge timeout: below the ${MIN_TIMEOUT_MS}ms floor, where the addon cannot answer ` +
+        `within one frame no matter what it is doing. Using the ${fallback}ms default instead.`);
+    return fallback;
+}
+/**
+ * A millisecond deadline from the environment, falling back to `fallback` when
+ * the variable is absent, empty, non-numeric, or not a usable positive integer.
+ *
+ * This is `port()`'s sibling, and it exists because the two were split for
+ * eleven releases. `port()` was hardened the moment a bad port began *refusing*
+ * a launch; every timeout kept the `Number.parseInt(x ?? "15000", 10)` pattern
+ * the docstring above condemns. `??` catches only null/undefined, so an
+ * exported-but-empty `GODOT_LSP_TIMEOUT_MS=""` — the same shape that motivated
+ * `port()` — reached `parseInt` and yielded `NaN`.
+ *
+ * **`setTimeout(cb, NaN)` does not throw. It fires on the next tick**,
+ * measurably sooner than `setTimeout(cb, 1)`, with no Node warning
+ * (`TimeoutOverflowWarning` covers only `> 2^31-1`). So the failure is worse
+ * than an unusable port, because by then the request is already on the wire:
+ * the addon polls its socket from `_process`, once per frame, and cannot answer
+ * inside ~1 ms. The deadline wins *deterministically*, the host reports
+ * `timed out after NaNms`, the addon still **executes** the mutation, and the
+ * real reply is dropped as an unknown id. An agent that retries a reported
+ * failure applies it twice.
+ *
+ * `parseInt` alone is not the fix here either, for the same reason it was not
+ * the fix for ports: it stops at the first non-digit, so a plausible `"15s"`
+ * silently becomes 15 ms and `"20_000"` becomes 20.
+ */
+function positiveInt(raw, fallback) {
+    // Same shape as port(), mirroring GDScript's `is_valid_int()`: reject the
+    // whole string rather than accept a numeric prefix.
+    //
+    // Zero and negatives are rejected rather than clamped — a deadline of 0 is
+    // not a shorter deadline, it is the NaN failure with a different spelling.
+    // The upper bound is setTimeout's own: past 2^31-1 Node warns and silently
+    // uses 1 ms, so a fat-fingered BREAKPOINT_ASSETGEN_TIMEOUT_MS would land back
+    // in the near-zero failure this guard exists to prevent.
+    const t = (raw ?? "").trim();
+    if (!/^\+?\d+$/.test(t))
+        return fallback;
+    const n = Number(t);
+    return Number.isSafeInteger(n) && n > 0 && n <= 2_147_483_647 ? n : fallback;
+}
 export function loadConfig() {
     const projectPath = process.env.GODOT_PROJECT ?? process.cwd();
     // The C# project defaults to the main project, but is usually pointed at a
@@ -36,20 +122,20 @@ export function loadConfig() {
         projectUri: pathToFileURL(projectPath).href,
         bridgeHost: process.env.BREAKPOINT_BRIDGE_HOST ?? "127.0.0.1",
         bridgePort: port(process.env.BREAKPOINT_BRIDGE_PORT, 9080),
-        bridgeTimeoutMs: Number.parseInt(process.env.BREAKPOINT_BRIDGE_TIMEOUT_MS ?? "15000", 10),
+        bridgeTimeoutMs: bridgeDeadlineMs(process.env.BREAKPOINT_BRIDGE_TIMEOUT_MS, 15000),
         lspHost: process.env.GODOT_LSP_HOST ?? "127.0.0.1",
         lspPort: port(process.env.GODOT_LSP_PORT, 6005),
-        lspTimeoutMs: Number.parseInt(process.env.GODOT_LSP_TIMEOUT_MS ?? "15000", 10),
+        lspTimeoutMs: positiveInt(process.env.GODOT_LSP_TIMEOUT_MS, 15000),
         csLspCmd: process.env.GODOT_CSLSP_CMD ?? "OmniSharp",
         csLspArgs: (process.env.GODOT_CSLSP_ARGS ?? "-lsp").split(/\s+/).filter(Boolean),
         csLspProjectPath,
         csLspProjectUri: pathToFileURL(csLspProjectPath).href,
-        csLspTimeoutMs: Number.parseInt(process.env.GODOT_CSLSP_TIMEOUT_MS ?? "30000", 10),
+        csLspTimeoutMs: positiveInt(process.env.GODOT_CSLSP_TIMEOUT_MS, 30000),
         dapHost: process.env.GODOT_DAP_HOST ?? "127.0.0.1",
         dapPort: port(process.env.GODOT_DAP_PORT, 6006),
-        dapTimeoutMs: Number.parseInt(process.env.GODOT_DAP_TIMEOUT_MS ?? "20000", 10),
-        dapSetVarTimeoutMs: Number.parseInt(process.env.GODOT_DAP_SETVAR_TIMEOUT_MS ?? "8000", 10),
-        dapEvaluateTimeoutMs: Number.parseInt(process.env.GODOT_DAP_EVALUATE_TIMEOUT_MS ?? "8000", 10),
+        dapTimeoutMs: positiveInt(process.env.GODOT_DAP_TIMEOUT_MS, 20000),
+        dapSetVarTimeoutMs: positiveInt(process.env.GODOT_DAP_SETVAR_TIMEOUT_MS, 8000),
+        dapEvaluateTimeoutMs: positiveInt(process.env.GODOT_DAP_EVALUATE_TIMEOUT_MS, 8000),
         csDapCmd: process.env.GODOT_CSDAP_CMD ?? "netcoredbg",
         csDapArgs: (process.env.GODOT_CSDAP_ARGS ?? "--interpreter=vscode").split(/\s+/).filter(Boolean),
         // The default program cs_dbg_launch launches is the Mono/.NET Godot binary. GODOT_CSHARP_BIN
@@ -57,17 +143,17 @@ export function loadConfig() {
         // caller can also override per-call via cs_dbg_launch's `program` arg.
         csDapProgram: process.env.GODOT_CSHARP_BIN ?? process.env.GODOT_BIN ?? "godot",
         csDapProjectPath: csLspProjectPath,
-        csDapTimeoutMs: Number.parseInt(process.env.GODOT_CSDAP_TIMEOUT_MS ?? "20000", 10),
-        csDapSetVarTimeoutMs: Number.parseInt(process.env.GODOT_CSDAP_SETVAR_TIMEOUT_MS ?? "8000", 10),
-        csDapEvaluateTimeoutMs: Number.parseInt(process.env.GODOT_CSDAP_EVALUATE_TIMEOUT_MS ?? "8000", 10),
+        csDapTimeoutMs: positiveInt(process.env.GODOT_CSDAP_TIMEOUT_MS, 20000),
+        csDapSetVarTimeoutMs: positiveInt(process.env.GODOT_CSDAP_SETVAR_TIMEOUT_MS, 8000),
+        csDapEvaluateTimeoutMs: positiveInt(process.env.GODOT_CSDAP_EVALUATE_TIMEOUT_MS, 8000),
         runtimeHost: process.env.BREAKPOINT_RUNTIME_HOST ?? "127.0.0.1",
         runtimePort: port(process.env.BREAKPOINT_RUNTIME_PORT, 9081),
-        runtimeTimeoutMs: Number.parseInt(process.env.BREAKPOINT_RUNTIME_TIMEOUT_MS ?? "15000", 10),
+        runtimeTimeoutMs: bridgeDeadlineMs(process.env.BREAKPOINT_RUNTIME_TIMEOUT_MS, 15000),
         // Group J: asset generation is OFF by default (backend "none" → tools degrade).
         assetGenBackend: process.env.BREAKPOINT_ASSETGEN_BACKEND ?? "none",
         assetGenCommand: process.env.BREAKPOINT_ASSETGEN_CMD ?? "",
         assetGenProvider: process.env.BREAKPOINT_ASSETGEN_PROVIDER ?? "",
-        assetGenTimeoutMs: Number.parseInt(process.env.BREAKPOINT_ASSETGEN_TIMEOUT_MS ?? "120000", 10),
+        assetGenTimeoutMs: positiveInt(process.env.BREAKPOINT_ASSETGEN_TIMEOUT_MS, 120000),
         toolsets: parseToolsets(process.env.BREAKPOINT_TOOLSETS),
         privilegedGroups: parsePrivilegedGroups(process.env.BREAKPOINT_PRIVILEGED_GROUPS),
     };

package/dist/csdap.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from "node:events";
 import { DapError } from "./dap.js";
+import { OverdueLedger } from "./late-reply.js";
 /**
  * Minimal DAP client for the C#/.NET debugging plane (D4 C3) — the debugger
  * analogue of the C2 `CsLspClient`. Transport-agnostic: it drives any
@@ -28,6 +29,12 @@ export class CsDapClient extends EventEmitter {
     seq = 1;
     pending = new Map();
     breakpoints = new Map();
+    /**
+     * Seqs whose deadline fired, so a response arriving later is recognised, not
+     * 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");
     configured = false;
     /** Persistent watch expressions, re-evaluated at each stop (see evaluateWatches). */
     watches = [];
@@ -58,8 +65,12 @@ export class CsDapClient extends EventEmitter {
         if (type === "response") {
             const reqSeq = msg["request_seq"];
             const p = this.pending.get(reqSeq);
-            if (!p)
+            if (!p) {
+                // Not pending: either a response we already gave up on (reconcile + log
+                // the overshoot), or a genuinely unknown seq — ignored exactly as before.
+                this.ledger.reconcile(reqSeq, msg["success"] === true);
                 return;
+            }
             this.pending.delete(reqSeq);
             clearTimeout(p.timer);
             if (msg["success"]) {
@@ -109,11 +120,21 @@ export class CsDapClient extends EventEmitter {
                 break;
         }
     }
+    /**
+     * Snapshot of responses that arrived after their deadline, oldest first.
+     * Diagnostics only — nothing in the request path reads this.
+     */
+    recentLateReplies() {
+        return this.ledger.recent();
+    }
     request(command, args = {}, timeoutMs = this.timeoutMs) {
         const seq = this.seq++;
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(seq);
+                // Remember the seq BEFORE rejecting, so a response already in flight is
+                // reconciled rather than dropped as anonymous.
+                this.ledger.note(seq, command, timeoutMs);
                 reject(new DapError(command, `C# DAP '${command}' timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             this.pending.set(seq, { command, resolve: resolve, reject, timer });

package/dist/cslsp.js

@@ -1,5 +1,6 @@
 import { fileURLToPath } from "node:url";
 import { LspError } from "./lsp.js";
+import { OverdueLedger } from "./late-reply.js";
 import { packageVersion } from "./version.js";
 /**
  * Minimal LSP client for the C#/.NET semantic plane (D4 C2). Transport-agnostic:
@@ -25,6 +26,12 @@ export class CsLspClient {
     opened = new Set();
     diagnostics = new Map();
     diagWaiters = new Map();
+    /**
+     * Ids whose deadline fired, so a reply arriving later is recognised, not
+     * 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");
     /** Absolute project root path (no trailing slash), used to canonicalize URIs. */
     rootFsPath;
     constructor(channel, rootUri, timeoutMs) {
@@ -71,8 +78,12 @@ export class CsLspClient {
         // Response to one of our requests.
         if (typeof id === "number" && method === undefined) {
             const p = this.pending.get(id);
-            if (!p)
+            if (!p) {
+                // Not pending: either a reply we already gave up on (reconcile + log the
+                // overshoot), or a genuinely unknown id — ignored exactly as before.
+                this.ledger.reconcile(id, msg["error"] === undefined);
                 return;
+            }
             this.pending.delete(id);
             clearTimeout(p.timer);
             if (msg["error"]) {
@@ -126,11 +137,21 @@ export class CsLspClient {
         this.serverCapabilities = null;
         this.opened.clear();
     }
+    /**
+     * Snapshot of replies that arrived after their deadline, oldest first.
+     * Diagnostics only — nothing in the request path reads this.
+     */
+    recentLateReplies() {
+        return this.ledger.recent();
+    }
     rawRequest(method, params, timeoutMs = this.timeoutMs) {
         const id = this.nextId++;
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
+                // Remember the id BEFORE rejecting, so a reply already in flight is
+                // reconciled rather than dropped as anonymous.
+                this.ledger.note(id, method, timeoutMs);
                 reject(new LspError("timeout", `C# LSP '${method}' timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             this.pending.set(id, { resolve: resolve, reject, timer });

package/dist/dap.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from "node:events";
 import { FramedConnection } from "./framing.js";
+import { OverdueLedger } from "./late-reply.js";
 export class DapError extends Error {
     command;
     constructor(command, message) {
@@ -19,6 +20,12 @@ export class DapClient extends EventEmitter {
     seq = 1;
     pending = new Map();
     breakpoints = new Map();
+    /**
+     * Seqs whose deadline fired, so a response arriving later is recognised, not
+     * 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");
     configured = false;
     /** Persistent watch expressions, re-evaluated at each stop (see evaluateWatches). */
     watches = [];
@@ -50,8 +57,12 @@ export class DapClient extends EventEmitter {
         if (type === "response") {
             const reqSeq = msg["request_seq"];
             const p = this.pending.get(reqSeq);
-            if (!p)
+            if (!p) {
+                // Not pending: either a response we already gave up on (reconcile + log
+                // the overshoot), or a genuinely unknown seq — ignored exactly as before.
+                this.ledger.reconcile(reqSeq, msg["success"] === true);
                 return;
+            }
             this.pending.delete(reqSeq);
             clearTimeout(p.timer);
             if (msg["success"]) {
@@ -106,6 +117,9 @@ export class DapClient extends EventEmitter {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(seq);
+                // Remember the seq BEFORE rejecting, so a response already in flight is
+                // reconciled rather than dropped as anonymous.
+                this.ledger.note(seq, command, timeoutMs);
                 reject(new DapError(command, `DAP '${command}' timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             this.pending.set(seq, { command, resolve: resolve, reject, timer });
@@ -116,6 +130,13 @@ export class DapClient extends EventEmitter {
             });
         });
     }
+    /**
+     * Snapshot of responses that arrived after their deadline, oldest first.
+     * Diagnostics only — nothing in the request path reads this.
+     */
+    recentLateReplies() {
+        return this.ledger.recent();
+    }
     waitEvent(name, timeoutMs) {
         return new Promise((resolve) => {
             const timer = setTimeout(() => {

package/dist/index.js

@@ -13,6 +13,7 @@ import { buildToolsets } from "./toolsets.js";
 import { registerRecipes } from "./recipes.js";
 import { applyOutputSchemas } from "./schemas.js";
 import { applyAnnotations } from "./annotations.js";
+import { applyTimeoutCaveat } from "./timeout-caveat.js";
 import { applyCapabilities, droppedTools, registerCapabilitiesResource, selectPrivilegedGroups, } from "./capabilities.js";
 import { taskStore, TASK_CAPABILITIES } from "./tasks.js";
 import { RESOURCE_CAPABILITIES, registerResourceSubscriptions } from "./subscriptions.js";
@@ -21,7 +22,11 @@ import { log } from "./logger.js";
 async function main() {
     const config = loadConfig();
     const bridge = new BridgeClient(config.bridgeHost, config.bridgePort, config.bridgeTimeoutMs, "editor bridge", undefined, () => resolveBridgeSecret(config.projectPath, ["BREAKPOINT_BRIDGE_SECRET"]));
-    const runtime = new BridgeClient(config.runtimeHost, config.runtimePort, config.runtimeTimeoutMs, "runtime bridge", "Is the project running? Launch it (godot_run_project or dbg_launch) with the Breakpoint MCP plugin enabled — it auto-registers the runtime autoload.", () => resolveBridgeSecret(config.projectPath, ["BREAKPOINT_RUNTIME_SECRET", "BREAKPOINT_BRIDGE_SECRET"]));
+    const runtime = new BridgeClient(config.runtimeHost, config.runtimePort, config.runtimeTimeoutMs, "runtime bridge", "Is the project running? Launch it (godot_run_project or dbg_launch) with the Breakpoint MCP plugin enabled — it auto-registers the runtime autoload.", () => resolveBridgeSecret(config.projectPath, ["BREAKPOINT_RUNTIME_SECRET", "BREAKPOINT_BRIDGE_SECRET"]), 
+    // This instance's deadline comes from BREAKPOINT_RUNTIME_TIMEOUT_MS, not the
+    // editor bridge's variable — a late reply here must name the knob that can
+    // actually move it, and the peer that answered is the running game.
+    "BREAKPOINT_RUNTIME_TIMEOUT_MS", "the running game");
     const lsp = new LspClient(config.lspHost, config.lspPort, config.projectUri, config.lspTimeoutMs);
     // D4 C2: the C# semantic plane. OmniSharp is spawned over stdio (lazily, on the
     // first cs_* call) against the C# project root — so a host without OmniSharp
@@ -36,7 +41,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.26.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.27.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // any register*Tools call — it wraps server.registerTool.
     applyOutputSchemas(server);
@@ -46,6 +51,15 @@ async function main() {
     // in applyCapabilities (below) + confirm.ts. Wraps registerTool after the
     // schema wrapper, before any register*Tools call.
     applyAnnotations(server);
+    // A bridge timeout does not mean nothing happened: the request is already on
+    // the wire when the deadline fires, and the addon polls once per frame, so the
+    // ordinary outcome is that the editor applies the change and answers late.
+    // Append a caveat scaled by the annotations just injected above — nothing for
+    // the read-only tools, "retrying is safe" for the idempotent ones, and
+    // "retrying may apply it a SECOND time" for those that are neither. Wraps the
+    // HANDLER (not the config), after applyAnnotations so the hints exist, before
+    // applyCapabilities so a dropped tool is never wrapped.
+    applyTimeoutCaveat(server);
     // Capability groups — a risk-based axis over the toolsets. Both `code-execution`
     // and `network` are OFF by default; a disabled group's tools are DROPPED at
     // registration (omitted from tools/list), so the secure-default surface is

package/dist/late-reply.js

@@ -0,0 +1,105 @@
+import { log } from "./logger.js";
+/**
+ * Bounds on the overdue ledger. Both are belt-and-braces: an id is normally
+ * evicted the moment its late reply lands, so the map is empty in steady state.
+ * These only matter for deadlines whose reply NEVER arrives (peer killed
+ * mid-request), which would otherwise accumulate one small record each.
+ */
+export const OVERDUE_MAX = 64;
+export const OVERDUE_MAX_AGE_MS = 5 * 60_000;
+/** How many late replies to retain for `recent()`. Diagnostics only. */
+export const LATE_REPLY_MAX = 32;
+/**
+ * Per-client ledger of ids whose deadline fired, plus the late replies that
+ * later reconciled against them.
+ *
+ * Generic in the id type because the clients disagree on it and both are safe:
+ * `BridgeClient` correlates on `randomUUID()` strings, while the LSP/DAP family
+ * uses a monotonic per-instance counter (`nextId++` / `seq++`) that is never
+ * reset — not even by `onClose()`, which clears `pending` but deliberately
+ * leaves the counter alone. Either way an id is never reused within the
+ * instance that owns the ledger, so a late reply can only ever be its OWN
+ * request's and misattribution is impossible.
+ */
+export class OverdueLedger {
+    kind;
+    peer;
+    knob;
+    overdue = new Map();
+    lateReplies = [];
+    /**
+     * @param kind  names the channel in the log line ("bridge", "LSP", "C# DAP").
+     * @param peer  what answered, as a noun phrase ("the editor", "the debug adapter").
+     * @param knob  the env var that widens THIS client's deadline. Per-instance,
+     *              not per-class: the editor and runtime bridges are both
+     *              `BridgeClient` but are configured by different variables, and
+     *              naming the wrong one sends the operator to a knob that cannot
+     *              move the deadline they just hit.
+     */
+    constructor(kind, peer, knob) {
+        this.kind = kind;
+        this.peer = peer;
+        this.knob = knob;
+    }
+    /**
+     * Record that `id`'s deadline fired, so a reply arriving afterwards is
+     * recognisable rather than anonymous. Call ONLY from the timeout path — a
+     * request that was never written, or whose connection closed, can never be
+     * answered by the peer, so a "late reply" for it is not a thing.
+     */
+    note(id, method, deadlineMs) {
+        this.overdue.set(id, { method, deadlineMs, timedOutAt: Date.now() });
+        const cutoff = Date.now() - OVERDUE_MAX_AGE_MS;
+        for (const [k, v] of this.overdue) {
+            if (v.timedOutAt < cutoff)
+                this.overdue.delete(k);
+        }
+        // Map iterates in insertion order, so the first key is always the oldest.
+        while (this.overdue.size > OVERDUE_MAX) {
+            const oldest = this.overdue.keys().next();
+            if (oldest.done)
+                break;
+            this.overdue.delete(oldest.value);
+        }
+    }
+    /**
+     * A reply landed for an id that is no longer pending. If we timed that id out,
+     * this is the proof the deadline was premature — record it and SAY SO. The
+     * caller's promise is already settled and cannot be un-rejected; the value
+     * here is the overshoot number, which is exactly what the operator needs to
+     * fix the deadline, and which the client previously discarded in silence.
+     *
+     * @returns true if this was a reconciled late reply, false for a genuinely
+     *          unknown id (a handshake ack, a stale frame) — ignored as ever.
+     */
+    reconcile(id, ok) {
+        const o = this.overdue.get(id);
+        if (!o)
+            return false;
+        this.overdue.delete(id);
+        const overshootMs = Date.now() - o.timedOutAt;
+        this.lateReplies.push({ method: o.method, deadlineMs: o.deadlineMs, overshootMs, ok });
+        if (this.lateReplies.length > LATE_REPLY_MAX)
+            this.lateReplies.shift();
+        log(`late ${this.kind} reply: '${o.method}' answered ${overshootMs}ms AFTER its ${o.deadlineMs}ms deadline — ` +
+            `the call ${ok ? `DID complete in ${this.peer}` : `reached ${this.peer} and failed there`}, ` +
+            `so the reported timeout was premature. Raise ${this.knob} above ${o.deadlineMs + overshootMs}ms.`);
+        return true;
+    }
+    /**
+     * Snapshot of replies that arrived after their deadline, oldest first.
+     * Diagnostics only — nothing in any request path reads this.
+     */
+    recent() {
+        return [...this.lateReplies];
+    }
+    /**
+     * How many timed-out ids are still awaiting a reply. Empty in steady state;
+     * exposed so a test can assert the ledger does not leak rather than trusting
+     * the bounds by inspection.
+     */
+    overdueSize() {
+        return this.overdue.size;
+    }
+}
+//# sourceMappingURL=late-reply.js.map

package/dist/lsp.js

@@ -1,6 +1,7 @@
 import { fileURLToPath } from "node:url";
 import { FramedConnection } from "./framing.js";
 import { packageVersion } from "./version.js";
+import { OverdueLedger } from "./late-reply.js";
 export class LspError extends Error {
     code;
     constructor(code, message) {
@@ -25,6 +26,12 @@ export class LspClient {
     opened = new Set();
     diagnostics = new Map();
     diagWaiters = new Map();
+    /**
+     * Ids whose deadline fired, so a reply arriving later is recognised, not
+     * 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");
     /** Absolute project root path (no trailing slash), used to canonicalize URIs. */
     rootFsPath;
     constructor(host, port, rootUri, timeoutMs) {
@@ -73,8 +80,12 @@ export class LspClient {
         // Response to one of our requests.
         if (typeof id === "number" && method === undefined) {
             const p = this.pending.get(id);
-            if (!p)
+            if (!p) {
+                // Not pending: either a reply we already gave up on (reconcile + log the
+                // overshoot), or a genuinely unknown id — ignored exactly as before.
+                this.ledger.reconcile(id, msg["error"] === undefined);
                 return;
+            }
             this.pending.delete(id);
             clearTimeout(p.timer);
             if (msg["error"]) {
@@ -132,6 +143,9 @@ export class LspClient {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
+                // Remember the id BEFORE rejecting, so a reply already in flight is
+                // reconciled rather than dropped as anonymous.
+                this.ledger.note(id, method, timeoutMs);
                 reject(new LspError("timeout", `LSP '${method}' timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             this.pending.set(id, { resolve: resolve, reject, timer });
@@ -179,6 +193,13 @@ export class LspClient {
         await this.ensureInitialized();
         return this.rawRequest(method, params, timeoutMs);
     }
+    /**
+     * Snapshot of replies that arrived after their deadline, oldest first.
+     * Diagnostics only — nothing in the request path reads this.
+     */
+    recentLateReplies() {
+        return this.ledger.recent();
+    }
     /**
      * The server's advertised capabilities from the `initialize` handshake (an
      * empty object if the server advertised none). Lets a tool feature-detect an

package/dist/stdio.js

@@ -12,7 +12,10 @@ import { log } from "./logger.js";
  * connects lazily — so a host with no C# language server installed pays nothing
  * and never fails at startup; only a cs_* tool call actually launches it. A spawn
  * failure (e.g. the binary isn't on PATH) rejects the send with an actionable
- * hint rather than hanging.
+ * hint rather than hanging, and — like the TCP sibling's dropped connection —
+ * fires `onClose`, so a client caching an initialize handshake drops it: install
+ * the language server afterwards and the next cs_* call picks it up, with no
+ * host restart.
  */
 export class StdioChannel {
     command;
@@ -44,13 +47,18 @@ export class StdioChannel {
             return Promise.resolve(this.child);
         if (this.starting)
             return this.starting;
-        this.starting = new Promise((resolve, reject) => {
+        let threwSynchronously = false;
+        const starting = new Promise((resolve, reject) => {
             let child;
             try {
                 child = spawn(this.command, this.args, { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"] });
             }
             catch (err) {
-                this.starting = null;
+                // Nulling `this.starting` here would be undone by the assignment below —
+                // the executor runs synchronously, BEFORE that assignment — so a synchronous
+                // throw (bad spawn options, not a missing binary) would cache the rejected
+                // promise forever. Flag it and let the assignment skip instead.
+                threwSynchronously = true;
                 reject(new Error(`${this.label} could not spawn '${this.command}'. ${this.unavailableHint} (${err.message})`));
                 return;
             }
@@ -75,12 +83,33 @@ export class StdioChannel {
             });
             child.on("exit", (code, signal) => {
                 log(`${this.label} exited (code=${code ?? "null"} signal=${signal ?? "null"})`);
+            });
+            // Reset on `close`, NOT `exit` — the one event name that separated this from
+            // its TCP sibling, which hooks `close` and self-heals. A spawn failure (ENOENT:
+            // no OmniSharp on PATH) emits `error` + `close` and NEVER `exit`, so an
+            // exit-only hook never ran `closeCb()`, and the client's cached `initialized`
+            // promise stayed rejected for the process's lifetime: install the language
+            // server afterwards and every cs_* call still returned the stale spawn error
+            // until the host restarted. `close` is a strict superset — a process that
+            // really ran emits `spawn` -> `exit` -> `close` — so the normal path still
+            // notifies exactly once and nothing double-fires.
+            //
+            // Do NOT move this into the `error` handler to notify a turn sooner. `close`
+            // lands after the microtask that settles the rejected send, and that lateness
+            // is load-bearing: a client's onClose rejects every still-pending request with
+            // its own generic "connection closed", so notifying synchronously would
+            // overwrite the actionable `${this.unavailableHint}` above with it and the
+            // caller would never learn which binary to install. The heal is therefore one
+            // turn behind the rejection the caller sees, which no real second tool call
+            // can observe.
+            child.on("close", () => {
                 this.child = null;
                 this.decoder.reset();
                 this.closeCb();
             });
         });
-        return this.starting;
+        this.starting = threwSynchronously ? null : starting;
+        return starting;
     }
     async send(msg) {
         const child = await this.start();

package/dist/timeout-caveat.js

@@ -0,0 +1,84 @@
+import { annotationsFor } from "./annotations.js";
+/**
+ * The marker identifying a bridge timeout envelope, built by
+ * `tools/editor/common.ts`'s `fail()`. Deliberately narrow: LSP and DAP timeouts
+ * are a different transport with a different failure mode (no editor-side
+ * mutation is implied), and `tools/dap.ts:29` / `tools/csdap.ts:31` branch on
+ * their own `/timed out after/` predicate, which this must not disturb.
+ */
+const BRIDGE_TIMEOUT_MARK = "Bridge error [timeout]";
+/** Mutating, but repeating it lands in the same state — retrying is safe. */
+export const CAVEAT_IDEMPOTENT = "The request WAS delivered to the editor and may already have been applied. " +
+    "This tool is idempotent, so retrying is safe.";
+/** Mutating and NOT idempotent — this is where a blind retry duplicates. */
+export const CAVEAT_NON_IDEMPOTENT = "The request WAS delivered to the editor and may already have been applied. " +
+    "Retrying may apply it a SECOND time — verify the editor state before you do.";
+/**
+ * The caveat a given tool's timeout envelope should carry, or null for the
+ * read-only tools that should carry none.
+ */
+export function caveatFor(name) {
+    const a = annotationsFor(name);
+    if (a.readOnlyHint)
+        return null;
+    return a.idempotentHint ? CAVEAT_IDEMPOTENT : CAVEAT_NON_IDEMPOTENT;
+}
+/**
+ * Append `caveat` to the first text block carrying the bridge-timeout marker.
+ *
+ * APPENDS — never rewrites. The existing sentence, including its exact
+ * `timed out after <n>ms` phrasing, is load-bearing elsewhere. Anything that is
+ * not a bridge-timeout error envelope is returned untouched, by identity, so a
+ * tool that never speaks to the bridge is unaffected even though it is wrapped.
+ */
+export function appendCaveat(result, caveat) {
+    const r = result;
+    if (!r || r.isError !== true || !Array.isArray(r.content))
+        return result;
+    let done = false;
+    const content = r.content.map((block) => {
+        if (done || block?.["type"] !== "text")
+            return block;
+        const text = block["text"];
+        if (typeof text !== "string" || !text.includes(BRIDGE_TIMEOUT_MARK))
+            return block;
+        done = true;
+        return { ...block, text: `${text} ${caveat}` };
+    });
+    return done ? { ...r, content } : result;
+}
+/**
+ * Wrap `server.registerTool` so a bridge-timeout envelope leaves with a caveat
+ * matching the tool's own annotations.
+ *
+ * Mirrors `applyOutputSchemas` / `applyAnnotations` / `applyCapabilities`; call
+ * once, AFTER `applyAnnotations` and BEFORE `applyCapabilities`, so a tool
+ * dropped by a disabled capability group is never wrapped at all.
+ *
+ * Read-only tools are not wrapped — not wrapped-and-inert, actually not wrapped —
+ * so 92 of the 289 handlers keep their exact previous identity.
+ */
+export function applyTimeoutCaveat(server) {
+    const inject = (raw) => (name, config, handler) => {
+        const caveat = caveatFor(name);
+        if (!caveat || typeof handler !== "function")
+            return raw(name, config, handler);
+        const inner = handler;
+        const wrapped = (...args) => {
+            const out = inner(...args);
+            // Preserve synchronicity: only a promise-returning handler gets a
+            // promise back, so nothing's timing changes just by being wrapped.
+            return out instanceof Promise ? out.then((v) => appendCaveat(v, caveat)) : appendCaveat(out, caveat);
+        };
+        return raw(name, config, wrapped);
+    };
+    const s = server;
+    s.registerTool = inject(s.registerTool.bind(server));
+    // The D2 task-model tools register through experimental.tasks.registerToolTask,
+    // not registerTool — same reason applyAnnotations covers both paths.
+    const tasks = s.experimental?.tasks;
+    if (tasks?.registerToolTask) {
+        tasks.registerToolTask = inject(tasks.registerToolTask.bind(tasks));
+    }
+}
+//# sourceMappingURL=timeout-caveat.js.map

package/dist/tools/tabletop.js

@@ -95,6 +95,31 @@ function resourceVariant(cls, path) {
 }
 const ALIGN_TO_ENUM = { left: 0, center: 1, right: 2 };
 // ------------------------------------------------------ column expressions ----
+/**
+ * The `{placeholder}` scanner, shared by `resolveColumnExpr` and
+ * `columnExprPlaceholders` so the two can never disagree about what counts as a
+ * placeholder. Both drive it through `String.replace`, which resets `lastIndex`
+ * when it finishes, so the shared `/g` instance carries no state between calls.
+ */
+const COLUMN_PLACEHOLDER = /\{([^}]*)\}/g;
+/**
+ * The column names an expression references, WITHOUT needing a row to resolve
+ * against. `resolveColumnExpr` reports the same set, but only as a side effect of
+ * resolving a row that exists — so a deck whose filter selected zero rows would
+ * otherwise report every mapped column as unmapped. Malformed placeholders are
+ * skipped here and still raised by `resolveColumnExpr` on the first real row.
+ * Pure — unit-tested.
+ */
+export function columnExprPlaceholders(expr) {
+    const columns = [];
+    expr.replace(COLUMN_PLACEHOLDER, (_full, rawName) => {
+        const name = rawName.trim();
+        if (name !== "")
+            columns.push(name);
+        return "";
+    });
+    return columns;
+}
 /**
  * Resolve a `card_deck_from_table` column expression against one row. A value is
  * either a bare `{column}` or a composed template like `{name} · {role}`; every
@@ -106,7 +131,7 @@ const ALIGN_TO_ENUM = { left: 0, center: 1, right: 2 };
  */
 export function resolveColumnExpr(expr, row) {
     const columns = [];
-    const value = expr.replace(/\{([^}]*)\}/g, (_full, rawName) => {
+    const value = expr.replace(COLUMN_PLACEHOLDER, (_full, rawName) => {
         const name = rawName.trim();
         if (name === "")
             throw new ComposeError("bad_params", `Empty {} placeholder in column expression ${JSON.stringify(expr)}`);
@@ -534,12 +559,21 @@ export async function emitDeckFromTable(emit, readFile, args) {
     for (const r of allRows)
         for (const k of Object.keys(r))
             header.add(k);
-    // which columns are actually referenced (by a placeholder, art, or filter)?
+    // Which columns are actually referenced (by a placeholder, art, or filter)?
+    // All three come off the ARGUMENTS, never off the selected rows. Reading the
+    // column_map inside the stamping loop below made this asymmetric: art_column and
+    // filter.column counted as referenced whatever the filter matched, while the
+    // mapped slots only counted once a row existed to resolve them against — so a
+    // filter matching zero rows reported every explicitly mapped column as unmapped.
     const referenced = new Set();
     if (args.art_column)
         referenced.add(args.art_column);
     if (args.filter)
         referenced.add(args.filter.column);
+    for (const expr of Object.values(args.column_map)) {
+        for (const c of columnExprPlaceholders(expr))
+            referenced.add(c);
+    }
     // select rows: filter → limit.
     let selected = args.filter
         ? allRows.filter((r) => String(r[args.filter.column] ?? "") === String(args.filter.equals))
@@ -552,9 +586,7 @@ export async function emitDeckFromTable(emit, readFile, args) {
         const row = selected[i];
         const data = {};
         for (const [slot, expr] of Object.entries(args.column_map)) {
-            const { value, columns } = resolveColumnExpr(expr, row);
-            for (const c of columns)
-                referenced.add(c);
+            const { value } = resolveColumnExpr(expr, row);
             data[slot] = value;
         }
         if (args.art_column && row[args.art_column])

package/package.json

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