breakpoint-mcp 1.79.0 → 1.80.0

package/dist/bridge.js

@@ -65,6 +65,68 @@ export function remedyClause(err) {
     const r = err?.remedy;
     return typeof r === "string" && r !== "" ? ` — ${r}` : "";
 }
+/** The code this class raises when a bridge request outlives its own deadline. */
+export const BRIDGE_TIMEOUT_CODE = "timeout";
+/**
+ * The label `tools/editor/common.ts`'s `fail()` puts in front of a bridge failure.
+ *
+ * 🔴 **ONE BUILDER, TWO READERS, AND THE SECOND ONE WAS A STRING LITERAL UNTIL 268.**
+ * `timeout-caveat.ts` decides whether a mutating tool gets its retry caveat by
+ * looking for `Bridge error [timeout]` inside the rendered envelope — a substring it
+ * spelled out itself, one file away from the template that produces it. That is
+ * `dap-timeout-predicate-reads-prose` again with a far wider blast radius: a reword of
+ * `fail()` would silently stop every non-idempotent tool from warning that a timed-out
+ * mutation may already have landed, and nothing compares the two spellings. Derived here
+ * so the two move together, and check 32 refuses a fresh literal.
+ */
+export function bridgeErrorLabel(code) {
+    return `Bridge error [${code}]`;
+}
+/**
+ * The code raised when the request could not be handed to the socket at all.
+ *
+ * 🔴 **ONE WORD, TWO PRODUCERS, AND ONLY ONE OF THEM HAS A REMEDY THAT FITS (268).** The
+ * ADDON raises `write_failed` too, from `operations.gd`, for a FILE it could not open for
+ * writing — and `error_remedies.gd` answers it with *"Check the target path is inside the
+ * project and not read-only; the number is a Godot Error code."* That sentence is correct
+ * for the addon and nonsense for this site, which has no path, no file and no Godot error
+ * code: it is a TCP socket that went away. The collision was invisible while this branch
+ * was believed unreachable; 268 measured it reachable 200/200 and it became live.
+ *
+ * The CODE is kept and the message and remedy are made to fit — 262's disposition for an
+ * overloaded shipped code, for the same reason: fix what the reader acts on, and leave a
+ * wire vocabulary that callers may already branch on alone. Whether the two producers
+ * should share a word at all is a wire question, and it is enqueued as one rather than
+ * decided here.
+ */
+export const BRIDGE_WRITE_FAILED = "write_failed";
+/**
+ * The next action for a request that never reached the socket.
+ *
+ * 🔴 IT IS THE ONE FAILURE IN THIS CLASS THAT CAN SAY *RETRY* WITHOUT QUALIFICATION, and
+ * that is the whole value of separating it. `timeout-caveat.ts` exists because a bridge
+ * TIMEOUT may already have been applied by the editor; `closeRemedy` cannot promise
+ * otherwise either, since a request in flight when the socket dropped may have landed.
+ * This one is different in a way the host actually knows: the frame was never handed to
+ * the kernel, so nothing can have been applied, so a retry is a first attempt and not a
+ * second. 264's rule — measure N families, speak for N — read in the direction that
+ * licenses a stronger sentence rather than a weaker one.
+ */
+export const WRITE_FAILED_REMEDY = "Retry the call — the request was never sent, so nothing was applied and this is a " +
+    "first attempt rather than a second. A recurrence means the host is tearing the " +
+    "connection down mid-request.";
+/**
+ * The sentence for a request that never reached the socket.
+ *
+ * `cause` is node's own error, kept in a parenthetical rather than used as the whole
+ * message: `Cannot call write after a stream was destroyed` is a true statement about a
+ * Node stream and tells a caller of `node_add` nothing about their call, which is what
+ * this site shipped until 268.
+ */
+export function writeFailedMessage(method, cause) {
+    return (`Bridge request '${method}' was never sent — the connection was torn down between ` +
+        `preparing the request and writing it, so the editor did not receive it (${cause.message}).`);
+}
 /**
  * TCP client for the in-editor Breakpoint MCP addon. Speaks newline-delimited
  * JSON. Requests are correlated to responses by `id`. Connects lazily and
@@ -396,9 +458,15 @@ export class BridgeClient {
             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.
+                // reconciled rather than dropped as anonymous.
+                //
+                // 🔴 THIS COMMENT USED TO SAY THE `timed out after <n>ms` PHRASING WAS
+                // LOAD-BEARING, NAMING `tools/dap.ts:29` AND `tools/csdap.ts:31`. Both line
+                // numbers had drifted by more than a hundred lines, and as of 268 the claim is
+                // false as well: those predicates read `DapError.code`, and this class's own
+                // caveat reader derives its marker from `bridgeErrorLabel`. A comment naming a
+                // line number is a claim that goes stale in silence — which is the whole reason
+                // the join is structural now.
                 this.ledger.note(id, method, timeoutMs);
                 // 🔴 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
@@ -408,14 +476,30 @@ export class BridgeClient {
                 // 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));
+                reject(new BridgeError(BRIDGE_TIMEOUT_CODE, `Bridge request '${method}' timed out after ${timeoutMs}ms`, this.holdProbe?.() ?? undefined));
             }, timeoutMs);
             this.pending.set(id, { resolve: resolve, reject, timer, method });
             socket.write(payload, (err) => {
                 if (err) {
                     clearTimeout(timer);
                     this.pending.delete(id);
-                    reject(new BridgeError("write_failed", err.message));
+                    // 🔴 REACHABLE, AND 265 CONCLUDED THE OPPOSITE FROM THE SAME TECHNIQUE (268).
+                    // 265 broke a live socket four ways and read `bridge_closed` every time, and
+                    // reasoned that `onClose()` always rejects the pending map first. Measured here
+                    // 300/300 at the node level, that ordering is BACKWARDS: on a destroyed socket
+                    // the write callback fires with ERR_STREAM_DESTROYED **before** the `close`
+                    // event, so this line wins whenever the socket dies inside the await gap
+                    // `request()` leaves between `connect()` and here. Driven through the real
+                    // client — `request()` not awaited, `close()` on the next statement — the caller
+                    // received THIS rejection 200 times out of 200. 265's drives all broke the
+                    // socket and then WAITED, which is the one window in which they could not win.
+                    //
+                    // The sentence is worth having because this case knows something the other two
+                    // do not: the payload never left. A `timeout` may have been applied by the
+                    // editor and `bridge_closed` may have been too, so neither can tell a caller to
+                    // retry; this one can, and 267's rule is that a next action rides in the field
+                    // rather than inside the message.
+                    reject(new BridgeError(BRIDGE_WRITE_FAILED, writeFailedMessage(method, err), WRITE_FAILED_REMEDY));
                 }
             });
         });

package/dist/config.js

@@ -111,6 +111,18 @@ function positiveInt(raw, fallback) {
     const n = Number(t);
     return Number.isSafeInteger(n) && n > 0 && n <= 2_147_483_647 ? n : fallback;
 }
+/**
+ * An opt-OUT flag: true unless the operator spelled a recognised falsehood.
+ *
+ * 🔴 THE UNRECOGNISED VALUE KEEPS THE SAFE DEFAULT, AND THAT IS THE OPPOSITE OF
+ * `positiveInt`'s reasoning ON PURPOSE. A malformed deadline falls back because both
+ * outcomes are ordinary; a malformed *guard* setting must not disable the guard, or a
+ * typo — `GODOT_DAP_REQUIRE_INITIALIZED=no thanks` — turns a refusal off silently. Only
+ * `0`, `false`, `off` and `no` are read as intent, case-insensitively.
+ */
+function optOut(raw) {
+    return !/^(0|false|off|no)$/i.test((raw ?? "").trim());
+}
 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
@@ -136,6 +148,7 @@ export function loadConfig() {
         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),
+        dapRequireInitialized: optOut(process.env.GODOT_DAP_REQUIRE_INITIALIZED),
         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

package/dist/csdap.js

@@ -1,8 +1,8 @@
 import { EventEmitter } from "node:events";
-import { DapError, INITIALIZED_WAIT_CEILING_MS } from "./dap.js";
+import { DapError, DAP_TIMEOUT_CODE, DAP_UNANNOUNCED_CODE, INITIALIZED_WAIT_CEILING_MS, unannouncedMessage, } from "./dap.js";
 import { OverdueLedger } from "./late-reply.js";
 import { closeDetail, closeRemedy } from "./close-cause.js";
-import { timeoutRemedy } from "./timeout-cause.js";
+import { timeoutRemedy, unannouncedRemedy } from "./timeout-cause.js";
 /**
  * Who answers this plane, in the words its late-reply ledger already uses.
  *
@@ -230,9 +230,9 @@ export class CsDapClient extends EventEmitter {
                 // Remember the seq BEFORE rejecting, so a response already in flight is
                 // reconciled rather than dropped as anonymous.
                 this.ledger.note(seq, command, timeoutMs);
-                // The `timed out after <n>ms` wording is load-bearing — `tools/csdap.ts`'s
-                // `isDapTimeout` branches on it. The next action rides beside it, not inside it.
-                reject(new DapError(command, `C# DAP '${command}' timed out after ${timeoutMs}ms`, timeoutRemedy(CSDAP_PEER, CSDAP_TIMEOUT_KNOB)));
+                // 🔴 THE WORDING IS NO LONGER LOAD-BEARING (268) — see `dap.ts`'s twin. The code
+                // is what `tools/csdap.ts`'s `isDapTimeout` reads; the sentence is free.
+                reject(new DapError(command, `C# DAP '${command}' timed out after ${timeoutMs}ms`, timeoutRemedy(CSDAP_PEER, CSDAP_TIMEOUT_KNOB), DAP_TIMEOUT_CODE));
             }, timeoutMs);
             this.pending.set(seq, { command, resolve: resolve, reject, timer });
             this.channel.send({ seq, type: "request", command, arguments: args }).catch((err) => {
@@ -350,12 +350,17 @@ export class CsDapClient extends EventEmitter {
      * afterwards failed with a bare hex code against a phantom session. The same held
      * for `program: ""` and for `cs_dbg_attach` on a process id that does not exist.
      */
-    async start(mode, args) {
+    async start(mode, args, requireInitialized = true) {
         this.lastStartMode = mode;
         this.lastStartArgs = args;
         this.sessionStarted = false;
-        // Listen for `initialized` before we ask, so we cannot miss it.
-        const initializedWaitMs = Math.min(this.timeoutMs, INITIALIZED_WAIT_CEILING_MS);
+        // Listen for `initialized` before we ask, so we cannot miss it. Two windows since
+        // 268 — see `dap.ts`'s twin for the argument. Refusing is the default, so the wait
+        // runs to the caller's own deadline; the five-second ceiling survives on the opt-out
+        // path alone, which exists to reproduce 267's behaviour including its numbers.
+        const initializedWaitMs = requireInitialized
+            ? this.timeoutMs
+            : Math.min(this.timeoutMs, INITIALIZED_WAIT_CEILING_MS);
         const onInit = this.waitEvent("initialized", initializedWaitMs);
         this.capabilities = await this.request("initialize", {
             clientID: "breakpoint-mcp",
@@ -390,6 +395,14 @@ export class CsDapClient extends EventEmitter {
         });
         // 🔴 CAPTURED, NOT DISCARDED (267) — see `dap.ts`'s twin.
         const initializedSeen = await onInit;
+        // 🔴 REFUSED, NOT REPORTED (268) — and BEFORE `applyAllBreakpoints()`, because that
+        // call is the defect itself. See `dap.ts`'s twin.
+        if (!initializedSeen && requireInitialized) {
+            this.state = "terminated";
+            this.sessionStarted = false;
+            this.configured = false;
+            throw new DapError(mode, unannouncedMessage("The C# debug adapter", mode, initializedWaitMs), unannouncedRemedy(CSDAP_PEER, CSDAP_TIMEOUT_KNOB), DAP_UNANNOUNCED_CODE);
+        }
         await this.applyAllBreakpoints();
         // Arm the entry-stop wait BEFORE configurationDone is sent: netcoredbg can emit
         // `stopped` before its configurationDone response lands, and a listener attached

package/dist/dap.js

@@ -2,7 +2,7 @@ import { EventEmitter } from "node:events";
 import { FramedConnection } from "./framing.js";
 import { OverdueLedger } from "./late-reply.js";
 import { closeDetail, closeRemedy } from "./close-cause.js";
-import { timeoutRemedy } from "./timeout-cause.js";
+import { timeoutRemedy, unannouncedRemedy } from "./timeout-cause.js";
 /**
  * Who answers this plane, in the words its late-reply ledger already uses.
  *
@@ -22,6 +22,13 @@ const DAP_PEER = "the debug adapter";
  * nothing reads, which is worse than saying nothing.
  */
 const DAP_TIMEOUT_KNOB = "GODOT_DAP_TIMEOUT_MS";
+/** This request hit its own deadline. The only code `isDapTimeout` answers to. */
+export const DAP_TIMEOUT_CODE = "timeout";
+/**
+ * The adapter answered `initialize` and never emitted `initialized`, so the handshake
+ * was refused rather than continued out of order. See `start()`.
+ */
+export const DAP_UNANNOUNCED_CODE = "unannounced";
 export class DapError extends Error {
     command;
     /**
@@ -38,12 +45,27 @@ export class DapError extends Error {
      * here means nobody has answered that site yet, not that it is unanswerable.
      */
     remedy;
-    constructor(command, message, remedy) {
+    /**
+     * Why the host raised this, for callers that branch — `undefined` on the six sites
+     * that relay the adapter's own failure.
+     *
+     * 🔴 **`LspError` HAS CARRIED ONE SINCE IT WAS WRITTEN AND THIS CLASS DID NOT, FOR NO
+     * REASON ANYBODY DECIDED.** `LspError`'s first constructor argument happens to be a
+     * code, so its two timeout sites pass `"timeout"` and every LSP caller branches on a
+     * field. This class's first argument is `command`, so its two timeout sites had
+     * nowhere to put one — and the tool layer read the message body instead. The shape of
+     * a constructor decided whether a shipped branch was structural or textual, and
+     * nothing ever asked.
+     */
+    code;
+    constructor(command, message, remedy, code) {
         super(message);
         this.command = command;
         this.name = "DapError";
         if (remedy)
             this.remedy = remedy;
+        if (code)
+            this.code = code;
     }
 }
 /**
@@ -55,6 +77,24 @@ export class DapError extends Error {
  * was actually waited.
  */
 export const INITIALIZED_WAIT_CEILING_MS = 5000;
+/**
+ * The message both planes raise when the adapter never announces itself.
+ *
+ * 🔴 ONE BUILDER, TWO PLANES — the same discipline `timeoutRemedy` and `closeRemedy`
+ * already follow, and the reason is 267's finding one file over: the SAME question was
+ * pasted into `peers.ts` and `readiness.ts`, 266 fixed one, and the other survived the
+ * session that fixed it because nothing joined the two sites. A sentence shipped twice
+ * is a sentence that will be corrected once.
+ *
+ * `waitedMs` is the window ACTUALLY waited, not the ceiling — a refusal naming a wait
+ * that did not happen sends an operator to the wrong knob, which is exactly why 267
+ * captured the window instead of recomputing it at the report site.
+ */
+export function unannouncedMessage(peer, mode, waitedMs) {
+    return (`${peer} answered \`initialize\` for this ${mode} and never emitted \`initialized\` ` +
+        `within ${waitedMs}ms, so the session was refused rather than configured out of order. ` +
+        `No breakpoints were applied and no program was left running by this host.`);
+}
 /**
  * What a launch/attach result says when the adapter never announced itself.
  *
@@ -297,10 +337,12 @@ export class DapClient extends EventEmitter {
                 // Remember the seq BEFORE rejecting, so a response already in flight is
                 // reconciled rather than dropped as anonymous.
                 this.ledger.note(seq, command, timeoutMs);
-                // The message keeps its exact `timed out after <n>ms` wording — `tools/dap.ts`'s
-                // `isDapTimeout` branches on it and `timeout-caveat.ts` says out loud that this
-                // predicate must not be disturbed. The next action rides beside it, not inside it.
-                reject(new DapError(command, `DAP '${command}' timed out after ${timeoutMs}ms`, timeoutRemedy(DAP_PEER, DAP_TIMEOUT_KNOB)));
+                // 🔴 THE WORDING IS NO LONGER LOAD-BEARING, AND THAT IS 268's CHANGE. It used to
+                // be: `tools/dap.ts`'s `isDapTimeout` regexed `/timed out after/` against this
+                // string, so a copy edit here silently changed which answer `dbg_evaluate` and
+                // `dbg_set_variable` gave, with every test green. The code below is what those
+                // branches read now; the sentence is free to be improved.
+                reject(new DapError(command, `DAP '${command}' timed out after ${timeoutMs}ms`, timeoutRemedy(DAP_PEER, DAP_TIMEOUT_KNOB), DAP_TIMEOUT_CODE));
             }, timeoutMs);
             this.pending.set(seq, { command, resolve: resolve, reject, timer });
             this.conn.send({ seq, type: "request", command, arguments: args }).catch((err) => {
@@ -489,7 +531,7 @@ export class DapClient extends EventEmitter {
      * not refused: every adapter that works today keeps working, and the four launch tools
      * say which of the two happened — the shape `stop_on_entry_honored` already ships in.
      */
-    async start(mode, args, entryStopWaitMs = 0) {
+    async start(mode, args, entryStopWaitMs = 0, requireInitialized = true) {
         // Remember how we started so restart() can reuse (or override) these params.
         this.lastStartMode = mode;
         this.lastStartArgs = args;
@@ -497,12 +539,20 @@ export class DapClient extends EventEmitter {
         // A fresh session re-detects against whatever adapter answers this time — a
         // restart may reach a different build than the one that dropped last time.
         this.droppedModifiers.clear();
-        // Listen for `initialized` before we ask, so we cannot miss it.
-        // The window is captured rather than recomputed at the report site: it is
-        // `min(timeoutMs, 5000)`, so a caller who raised the deadline gets 5000 and one who
-        // lowered it gets their own number, and a warning naming the wrong one is a warning
-        // that sends an operator to the wrong knob.
-        const initializedWaitMs = Math.min(this.timeoutMs, INITIALIZED_WAIT_CEILING_MS);
+        // Listen for `initialized` before we ask, so we cannot miss it. The window is
+        // captured rather than recomputed at the report site, so a warning or refusal names
+        // the wait that actually happened rather than the one the code would compute later.
+        //
+        // 🔴 TWO WINDOWS, AND WHICH ONE APPLIES IS THE WHOLE OF 268's DECISION. Refusing is
+        // the default now, so the ceiling that made a longer wait pointless has gone with it:
+        // when nothing is going to proceed regardless, the honest bound is the deadline the
+        // CALLER declared. A conformant adapter that takes six seconds used to be configured
+        // out of order at five and told nobody; it now simply succeeds. The five-second
+        // ceiling survives only on the opt-out path, where it must, because that path exists
+        // to reproduce 267's behaviour exactly — including the number its warning prints.
+        const initializedWaitMs = requireInitialized
+            ? this.timeoutMs
+            : Math.min(this.timeoutMs, INITIALIZED_WAIT_CEILING_MS);
         const onInit = this.waitEvent("initialized", initializedWaitMs);
         this.capabilities = await this.request("initialize", {
             clientID: "breakpoint-mcp",
@@ -536,6 +586,16 @@ export class DapClient extends EventEmitter {
         // that licenses it was invisible: the failing case and the succeeding case returned
         // the same `undefined`.
         const initializedSeen = await onInit;
+        // 🔴 THE REFUSAL GOES HERE AND NOWHERE LATER (268), because the next line is the
+        // defect. `applyAllBreakpoints()` is `setBreakpoints` going out ahead of the event
+        // the DAP specification says must precede it — the thing 266 measured against a stub
+        // adapter and 267 made observable without stopping. Refusing after it would leave the
+        // adapter holding breakpoints from a session the caller was told did not start.
+        if (!initializedSeen && requireInitialized) {
+            this.state = "terminated";
+            this.sessionStarted = false;
+            throw new DapError(mode, unannouncedMessage("The debug adapter", mode, initializedWaitMs), unannouncedRemedy(DAP_PEER, DAP_TIMEOUT_KNOB), DAP_UNANNOUNCED_CODE);
+        }
         await this.applyAllBreakpoints();
         await this.request("configurationDone", {}).catch(() => undefined);
         // 🔴 By the time we get here an already-arrived rejection has ALREADY run its

package/dist/index.js

@@ -52,7 +52,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.79.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.80.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // 208 §7.1 — delete from the wire what the protocol already says: the SDK's
     // draft-07 `$schema` inside every input/output schema (MCP's default dialect is
     // 2020-12, and declaring another is an explicit switch a peer may reject), and

package/dist/timeout-cause.js

@@ -45,4 +45,22 @@ export function timeoutRemedy(peer, knob) {
     return (`Raise \`${knob}\` if ${peer} is merely slow — the request reached it and this ` +
         `host's deadline fired first, so it may still answer and a retry sends a second request.`);
 }
+/**
+ * The next action when an adapter answered `initialize` and never announced itself.
+ *
+ * 🔴 IT NAMES BOTH WAYS OUT, BECAUSE THE HOST CANNOT TELL THEM APART FROM HERE. Either
+ * the adapter is slower than the caller's own declared deadline — raise it — or it does
+ * not implement the `initialized` event at all, in which case a session can still be had
+ * by opting out and accepting that breakpoints are applied ahead of the event that
+ * licenses them, which is what every session did silently before 268. Naming only the
+ * knob would send an operator to lengthen a wait that is never going to end.
+ *
+ * Written to check 28's grammar: an imperative at the head, a full stop at the end, and
+ * nothing named that does not resolve.
+ */
+export function unannouncedRemedy(peer, knob) {
+    return (`Raise \`${knob}\` if ${peer} is merely slow to announce itself, or set ` +
+        `\`GODOT_DAP_REQUIRE_INITIALIZED=0\` to start anyway against an adapter that never ` +
+        `sends \`initialized\`.`);
+}
 //# sourceMappingURL=timeout-cause.js.map

package/dist/timeout-caveat.js

@@ -1,12 +1,23 @@
 import { annotationsFor } from "./annotations.js";
+import { BRIDGE_TIMEOUT_CODE, bridgeErrorLabel } from "./bridge.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.
+ * are a different transport with a different failure mode — no editor-side
+ * mutation is implied — and the two DAP planes classify their own by
+ * `DapError.code`, which this neither reads nor disturbs.
+ *
+ * 🔴 **DERIVED SINCE 268; A HAND-COPIED LITERAL BEFORE IT.** This constant used to
+ * spell `Bridge error [timeout]` out, here, while the template producing it lives in
+ * `tools/editor/common.ts` and the code it embeds is raised in `bridge.ts`. Three
+ * files, one sentence, nothing joining them — so a reword of `fail()`'s label would
+ * have left this matching nothing, and the caveat that tells a caller their timed-out
+ * `node_add` may ALREADY have landed would have gone quiet on every mutating tool
+ * with the whole suite still green. `dap-timeout-predicate-reads-prose` with a hundred
+ * times the blast radius, found only by asking what ELSE in the tree decides behaviour
+ * by matching English.
  */
-const BRIDGE_TIMEOUT_MARK = "Bridge error [timeout]";
+const BRIDGE_TIMEOUT_MARK = bridgeErrorLabel(BRIDGE_TIMEOUT_CODE);
 /** 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.";

package/dist/tools/csdap.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { DapError, unorderedHandshakeWarning } from "../dap.js";
+import { DapError, DAP_TIMEOUT_CODE, unorderedHandshakeWarning } from "../dap.js";
 import { remedyClause } from "../bridge.js";
 import { resolveSourceFile } from "../paths.js";
 import { gate } from "../confirm.js";
@@ -64,9 +64,13 @@ function refuse(message, code) {
  * adapter-reported failure or a dropped connection). Used to turn a
  * setVariable / evaluate non-response into a clear message rather than the
  * generic timeout — the same F1 discipline the GDScript DAP plane uses.
+ *
+ * 🔴 A CODE SINCE 268, A REGEX OVER ENGLISH BEFORE IT — see `tools/dap.ts`'s twin for
+ * the whole argument. Both planes carried the identical prose predicate, which is why
+ * the row named two files and not one.
  */
 function isDapTimeout(err) {
-    return err instanceof DapError && /timed out after/.test(err.message);
+    return err instanceof DapError && err.code === DAP_TIMEOUT_CODE;
 }
 /**
  * D4 C3 — the C#/.NET debugging plane. `cs_dbg_*` tools mirroring the read/inspect
@@ -259,7 +263,7 @@ export function registerCsDapTools(server, dap, cfg) {
                 cwd: cfg.csDapProjectPath,
                 stopAtEntry: stop_on_entry ?? false,
                 justMyCode: just_my_code ?? true,
-            });
+            }, cfg.dapRequireInitialized);
             const result = { session_id: "csharp", state: dap.state };
             reportHandshakeOrder(result, initializedSeen, initializedWaitMs);
             return ok(result);
@@ -296,7 +300,7 @@ export function registerCsDapTools(server, dap, cfg) {
                         `was previously reported as "running" against a process that does not exist.`, "no_such_process");
                 }
             }
-            const { initializedSeen, initializedWaitMs } = await dap.start("attach", { processId: process_id });
+            const { initializedSeen, initializedWaitMs } = await dap.start("attach", { processId: process_id }, cfg.dapRequireInitialized);
             const result = { session_id: "csharp", state: dap.state };
             reportHandshakeOrder(result, initializedSeen, initializedWaitMs);
             return ok(result);

package/dist/tools/dap.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { DapError, unorderedHandshakeWarning } from "../dap.js";
+import { DapError, DAP_TIMEOUT_CODE, unorderedHandshakeWarning } from "../dap.js";
 import { remedyClause } from "../bridge.js";
 import { resolveSourceFile } from "../paths.js";
 import { gate } from "../confirm.js";
@@ -137,9 +137,18 @@ function fail(err) {
  * True when `err` is a DAP request that hit its own request deadline (as opposed to an
  * adapter-reported failure or a dropped connection). Used to turn the setVariable /
  * evaluate hangs on advertised-but-unimplemented Godot builds into a clear message.
+ *
+ * 🔴 **THIS READ THE MESSAGE BODY UNTIL 268, AND TWO SHIPPED TOOLS BRANCHED ON IT.** The
+ * predicate was `/timed out after/.test(err.message)`, so `dbg_evaluate`'s and
+ * `dbg_set_variable`'s specific answers were selected by a regex over English — a copy
+ * edit at the raise site would have silently returned every caller to a bare timeout,
+ * with every test in the suite still green. 267 declined to reword those messages for
+ * exactly that reason and asserted the wording instead, which is a test defending a
+ * defect rather than a behaviour. The raise site now sets `DAP_TIMEOUT_CODE` and this
+ * reads it; check 32 refuses the regex coming back.
  */
 function isDapTimeout(err) {
-    return err instanceof DapError && /timed out after/.test(err.message);
+    return err instanceof DapError && err.code === DAP_TIMEOUT_CODE;
 }
 /**
  * 🔴 The modifier feature-detection lives in `dap.ts` (the client), NOT here, and that
@@ -335,7 +344,7 @@ export function registerDapTools(server, dap, cfg) {
             };
         }
         try {
-            const { entryStopSeen, initializedSeen, initializedWaitMs } = await dap.start("launch", { project: cfg.projectPath, scene: scene ?? "main", stopOnEntry: stop_on_entry ?? false }, stop_on_entry ? ENTRY_STOP_WAIT_MS : 0);
+            const { entryStopSeen, initializedSeen, initializedWaitMs } = await dap.start("launch", { project: cfg.projectPath, scene: scene ?? "main", stopOnEntry: stop_on_entry ?? false }, stop_on_entry ? ENTRY_STOP_WAIT_MS : 0, cfg.dapRequireInitialized);
             const result = { session_id: "godot", state: dap.state, scene: scene ?? "main" };
             reportHandshakeOrder(result, initializedSeen, initializedWaitMs);
             if (stop_on_entry) {
@@ -372,7 +381,7 @@ export function registerDapTools(server, dap, cfg) {
         },
     }, async ({ address, port }) => {
         try {
-            const { initializedSeen, initializedWaitMs } = await dap.start("attach", { address: address ?? "127.0.0.1", port });
+            const { initializedSeen, initializedWaitMs } = await dap.start("attach", { address: address ?? "127.0.0.1", port }, 0, cfg.dapRequireInitialized);
             const result = { session_id: "godot", state: dap.state };
             reportHandshakeOrder(result, initializedSeen, initializedWaitMs);
             reportDroppedModifiers(result);

package/dist/tools/editor/common.js

@@ -1,10 +1,15 @@
 import { ok, failPath } from "../lsp-common.js";
 import { resolveInsideProject } from "../../paths.js";
-import { remedyClause } from "../../bridge.js";
+import { remedyClause, bridgeErrorLabel } from "../../bridge.js";
 /**
  * MCP error envelope for a failed editor-bridge call (never throws to the
  * caller). Distinct from lsp-common's `fail` (which labels errors "LSP error");
  * this one labels them "Bridge error".
+ *
+ * 🔴 THE LABEL IS BUILT BY `bridgeErrorLabel` AND NOT WRITTEN HERE (268), because
+ * `timeout-caveat.ts` matches against it to decide whether a mutating tool warns that
+ * a timed-out change may already have landed. Inlining the template again would put the
+ * two spellings back in two files with nothing joining them.
  */
 export function fail(err) {
     const be = err;
@@ -12,7 +17,7 @@ export function fail(err) {
     const message = be?.message ?? String(err);
     return {
         isError: true,
-        content: [{ type: "text", text: `Bridge error [${code}]: ${message}${remedyClause(err)}` }],
+        content: [{ type: "text", text: `${bridgeErrorLabel(code)}: ${message}${remedyClause(err)}` }],
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.79.0",
+  "version": "1.80.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",
@@ -43,7 +43,8 @@
     "start": "node dist/index.js",
     "dev": "tsc && node dist/index.js",
     "stage-addon": "node scripts/stage-addon.mjs",
-    "prepublishOnly": "npm run build && npm run stage-addon",
+    "prepublishOnly": "npm run build && npm run stage-addon && node scripts/publish_guard.mjs",
+    "publish-guard": "node scripts/publish_guard.mjs --selftest && node scripts/publish_guard.mjs",
     "path-cohort": "node scripts/path-cohort.mjs",
     "tautology-gate": "node scripts/tautology_gate.selftest.mjs && node scripts/tautology_gate.mjs",
     "scope-gate": "python3 ../scripts/scope_gate.py",