breakpoint-mcp 1.78.3 → 1.80.0

package/dist/dap.js

@@ -2,23 +2,122 @@ 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, unannouncedRemedy } from "./timeout-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.
+ * 🔴 ONE CONSTANT, THREE READERS (264, 267). The ledger names this peer when a reply
+ * arrives late, `closeRemedy` names it when the connection drops, and `timeoutRemedy`
+ * names it when a deadline fires. 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";
+/**
+ * The environment variable this plane's deadline comes from.
+ *
+ * 🔴 ONE CONSTANT, TWO READERS, FOR THE REASON DIRECTLY ABOVE. The ledger prints it on a
+ * late reply and `timeoutRemedy` tells the caller to raise it; a knob renamed in
+ * `config.ts` and updated in one of the two would send an operator to export a variable
+ * 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;
-    constructor(command, message) {
+    /**
+     * The next action — the same field `BridgeError` has carried since 254, for the same
+     * reason, and 🔴 **ITS ABSENCE WAS THE WHOLE OF THE ROW THIS CLOSES.** 264's census
+     * found 13 of 25 host-raised failures sitting on classes with nowhere to put an answer;
+     * this class was two of the four. Worse than nowhere: three of the raise sites below
+     * DID know the next action and pasted it into the MESSAGE, where nothing structural can
+     * read it — no gate can join it, `fail()` cannot render it under one clause with the
+     * rest, and a reword drops it with no test able to tell.
+     *
+     * Optional by construction, exactly as on `BridgeError`: a rejection RELAYING the
+     * adapter's own words has no business inventing a next action on its behalf. Absent
+     * here means nobody has answered that site yet, not that it is unanswerable.
+     */
+    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;
     }
 }
+/**
+ * The ceiling on the wait for `initialized`, shared by both DAP planes.
+ *
+ * Not a new number — both clients have used `Math.min(timeoutMs, 5000)` since their
+ * handshakes were written. It is named here because 267 made the OUTCOME of that wait
+ * something a caller reads, and a window reported in a warning has to be the window that
+ * 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.
+ *
+ * 🔴 REPORTED, NOT REFUSED, AND THE CHOICE IS THE WHOLE OF THE ROW. The wait has resolved
+ * on its own timer since the handshake was written, so every adapter in the field has
+ * been launching through this path; refusing outright would break working setups to fix a
+ * silence. The shape is the one this tool already ships for `stop_on_entry_honored`: name
+ * what did not happen, name the symptom to expect, leave the session alone. A stricter
+ * refusal remains available and is a separate decision.
+ */
+export function unorderedHandshakeWarning(waitedMs) {
+    return (`The debug adapter did not announce itself with an initialized event within ${waitedMs}ms. ` +
+        `Breakpoints were applied outside the order the DAP specification requires, so a breakpoint ` +
+        `that silently fails to bind is the symptom to expect; the session is otherwise live.`);
+}
+/**
+ * The next action when `restart` is called with no launch behind it.
+ *
+ * A `*_REMEDY` const rather than a literal at the throw site because check 28's grammar
+ * reader finds host-side remedies by that naming convention — a sentence spelled inline
+ * is a sentence no gate reads, which is the defect this whole change is about.
+ */
+export const DAP_RESTART_REMEDY = "Call `dbg_launch` or `dbg_attach` first — a restart reuses the parameters of a launch that already happened, and none has.";
 /**
  * Per-line breakpoint modifier fields, each gated by an adapter capability. Godot
  * advertises all three false AND ignores them — a "conditional" breakpoint halts
@@ -83,7 +182,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", DAP_PEER, "GODOT_DAP_TIMEOUT_MS");
+    ledger = new OverdueLedger("DAP", DAP_PEER, DAP_TIMEOUT_KNOB);
     configured = false;
     /** Persistent watch expressions, re-evaluated at each stop (see evaluateWatches). */
     watches = [];
@@ -152,15 +251,19 @@ export class DapClient extends EventEmitter {
             // 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 = 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.
+            // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), NOW ON THE FIELD RATHER THAN IN
+            // THE MESSAGE (267). The comment that stood here said `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" — true when it was written,
+            // and the reason 264's census counted this site among the SEVEN that named an
+            // action nothing structural could read. Both halves are gone: the field exists and
+            // `fail()` appends the clause. **What a caller receives is byte-identical**, which
+            // is asserted rather than assumed — the message ended in ` — ${remedy}` and the
+            // renderer appends exactly that, so this is a change of channel, not of wording.
             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}${remedy ? ` — ${remedy}` : ""}`));
+                p.reject(new DapError(p.command, `DAP connection closed${detail}`, remedy));
             }
             this.pending.clear();
             this.emit("closed");
@@ -234,7 +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);
-                reject(new DapError(command, `DAP '${command}' timed out after ${timeoutMs}ms`));
+                // 🔴 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) => {
@@ -251,15 +359,32 @@ export class DapClient extends EventEmitter {
     recentLateReplies() {
         return this.ledger.recent();
     }
+    /**
+     * Wait for `name`, bounded — resolving **`true` when the event arrived and `false` when
+     * the timer fired**.
+     *
+     * 🔴 THE RETURN VALUE IS THE FIX (267), AND THE OLD SIGNATURE IS WHY THE DEFECT COULD
+     * NOT BE SEEN. `Promise<void>` gave both outcomes the same shape, so `await onInit` in
+     * `start()` below could not distinguish *the adapter said it was ready* from *five
+     * seconds passed*, and the handshake carried on either way — sending `setBreakpoints`
+     * ahead of the event the DAP specification says must precede it, and telling nobody.
+     * Driven against a stub adapter that answers `initialize` and never emits
+     * `initialized`, `start()` returned after 5,003 ms having sent
+     * `initialize -> launch -> setBreakpoints -> configurationDone` in exactly the order a
+     * conformant run sends them, with no complaint anywhere.
+     *
+     * 262's rule, one instance further in: a guard that asks whether the container exists
+     * has not asked whether the content is there. A resolve is not an answer.
+     */
     waitEvent(name, timeoutMs) {
         return new Promise((resolve) => {
             const timer = setTimeout(() => {
                 this.removeListener(name, onEvent);
-                resolve();
+                resolve(false);
             }, timeoutMs);
             const onEvent = () => {
                 clearTimeout(timer);
-                resolve();
+                resolve(true);
             };
             this.once(name, onEvent);
         });
@@ -398,8 +523,15 @@ export class DapClient extends EventEmitter {
      * before returning — see `dbg_launch`'s `stop_on_entry`. Godot 4.7 does not honour
      * `stopOnEntry` at all, so this wait times out there and the caller is told so
      * rather than being handed a bare `running` that reads like it worked.
+     *
+     * 🆕 `initializedSeen` (267) is the SAME DISCIPLINE applied to the wait one line up.
+     * The `initialized` wait had been resolving on its own timer since this handshake was
+     * written, so a five-second silence and a prompt event were the same observable and the
+     * caller was handed a session that read exactly like a conformant one. It is reported,
+     * 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;
@@ -407,8 +539,21 @@ 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.
-        const onInit = this.waitEvent("initialized", Math.min(this.timeoutMs, 5000));
+        // 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",
             clientName: "Godot Breakpoint MCP",
@@ -436,7 +581,21 @@ export class DapClient extends EventEmitter {
         });
         // An entry stop can arrive before configurationDone answers — arm first.
         const entryStop = entryStopWaitMs > 0 ? this.waitEvent("stopped", entryStopWaitMs) : null;
-        await onInit;
+        // 🔴 CAPTURED, NOT DISCARDED (267). `await onInit` threw this away for as long as the
+        // handshake has existed, which is why `setBreakpoints` going out ahead of the event
+        // 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
@@ -460,7 +619,7 @@ export class DapClient extends EventEmitter {
             if (startFailure)
                 throw startFailure;
         }
-        return { entryStopSeen: this.stoppedNow() };
+        return { entryStopSeen: this.stoppedNow(), initializedSeen, initializedWaitMs };
     }
     threadId() {
         return this.lastStoppedThreadId ?? 1;
@@ -532,7 +691,7 @@ export class DapClient extends EventEmitter {
      */
     async restart(overrideArgs = {}, waitMs = 15000) {
         if (!this.lastStartMode || !this.lastStartArgs) {
-            throw new DapError("restart", "no debug session to restart — call dbg_launch or dbg_attach first");
+            throw new DapError("restart", "no debug session to restart", DAP_RESTART_REMEDY);
         }
         const args = { ...this.lastStartArgs, ...overrideArgs };
         const scene = typeof args["scene"] === "string" ? args["scene"] : null;

package/dist/exit-cause.js

@@ -42,10 +42,12 @@
  * question", spelled here as a parameter nobody declared. `exitSignal` is captured now
  * and `describeExit` says `killed by SIGKILL` where the sentence used to print a null.
  *
- * 🔵 WHAT THIS DELIBERATELY DOES NOT DO. `godot_process_output` still answers
- * `exit_code: null` for a signal-killed child and carries no `signal` key: that is a wire
- * addition to a shipped tool, it would make this cut a MINOR, and it is enqueued rather
- * than folded in. The capture is internal; only the two peer sentences read it today.
+ * 🟢 AND THE WIRE CAUGHT UP AT 267. 266 left this capture deliberately internal —
+ * `godot_output` answered `exit_code: null` for a signal-killed child with no `signal`
+ * key, because that is a wire addition to a shipped tool and would make a PATCH a MINOR.
+ * It was enqueued as `process-output-omits-signal` and paid in the next cut: the tool now
+ * answers `signal`, nullable beside `exit_code`, so a caller can tell a child that chose
+ * to exit from one the OS killed without parsing a sentence.
  */
 /** How a managed child ended, in the words a person would use. */
 export function describeExit(code, signal) {
@@ -84,9 +86,13 @@ export function readinessRemedy(causes) {
     const exited = causes.some((c) => c === "exited");
     const silent = causes.some((c) => c === "silent");
     if (exited && silent) {
-        return (`Read the output quoted above for the peer(s) that exited and fix what stopped them, ` +
-            `then check the Breakpoint MCP plugin is enabled for the one(s) that stayed up and never ` +
-            `answered — two different things failed here and only the second is about the addon.`);
+        return (
+        // Trimmed at 267 to the ceiling check 28 has always enforced on the addon's own
+        // remedies and now enforces here: it was 255 characters, and the two populations it
+        // addresses are still both named.
+        `Read the output quoted above and fix what stopped the peer(s) that exited, then check ` +
+            `the "Breakpoint MCP" plugin for the one(s) that never answered — two things failed and ` +
+            `only the second is the addon.`);
     }
     if (exited) {
         return (`Read the output quoted above and fix what stopped the child — it exited on its own, ` +

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.78.3" }, { 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/lsp.js

@@ -3,6 +3,7 @@ import { FramedConnection } from "./framing.js";
 import { packageVersion } from "./version.js";
 import { OverdueLedger } from "./late-reply.js";
 import { closeDetail, closeRemedy } from "./close-cause.js";
+import { timeoutRemedy } from "./timeout-cause.js";
 /**
  * Who answers this plane, in the words its late-reply ledger already uses.
  *
@@ -12,12 +13,28 @@ import { closeDetail, closeRemedy } from "./close-cause.js";
  * per-instance deadline noun was written to stop.
  */
 const LSP_PEER = "the language server";
+/** The environment variable this plane's deadline comes from — see `dap.ts`'s twin. */
+const LSP_TIMEOUT_KNOB = "GODOT_LSP_TIMEOUT_MS";
 export class LspError extends Error {
     code;
-    constructor(code, message) {
+    /**
+     * The next action — the same field `BridgeError` has carried since 254, added here at
+     * 267 for the same reason it was added there. 🔴 **ITS ABSENCE WAS THE ROW.** 264's
+     * census found 13 of 25 host-raised failures sitting on classes with nowhere to put an
+     * answer, and this class was two of the four. The close handler below already KNEW the
+     * next action and pasted it into the message, where no gate can join it and `fail()`
+     * cannot render it under one clause.
+     *
+     * Optional by construction, as on `BridgeError`: a rejection relaying the language
+     * server's own words has no business inventing an action on its behalf.
+     */
+    remedy;
+    constructor(code, message, remedy) {
         super(message);
         this.name = "LspError";
         this.code = code;
+        if (remedy)
+            this.remedy = remedy;
     }
 }
 /**
@@ -41,7 +58,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", LSP_PEER, "GODOT_LSP_TIMEOUT_MS");
+    ledger = new OverdueLedger("LSP", LSP_PEER, LSP_TIMEOUT_KNOB);
     /** Absolute project root path (no trailing slash), used to canonicalize URIs. */
     rootFsPath;
     constructor(host, port, rootUri, timeoutMs) {
@@ -143,15 +160,17 @@ export class LspClient {
         // 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 = 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.
+        // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), ON THE FIELD RATHER THAN IN THE
+        // MESSAGE (267). The comment that stood here said `LspError` "carries no `remedy`
+        // field, and the plane's `fail()` renders no `remedyClause`" — true when written, and
+        // the reason 264's census counted this site among the SEVEN that named an action
+        // nothing structural could read. Both halves are gone. **What a caller receives is
+        // byte-identical** and is asserted so: the message ended in ` — ${remedy}` and the
+        // renderer appends exactly that. A change of channel, not of wording.
         const remedy = closeRemedy(cause, LSP_PEER);
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
-            p.reject(new LspError("closed", `LSP connection closed${detail}${remedy ? ` — ${remedy}` : ""}`));
+            p.reject(new LspError("closed", `LSP connection closed${detail}`, remedy));
         }
         this.pending.clear();
         this.initialized = null;
@@ -166,7 +185,7 @@ export class LspClient {
                 // 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`));
+                reject(new LspError("timeout", `LSP '${method}' timed out after ${timeoutMs}ms`, timeoutRemedy(LSP_PEER, LSP_TIMEOUT_KNOB)));
             }, timeoutMs);
             this.pending.set(id, { resolve: resolve, reject, timer });
             this.conn.send({ jsonrpc: "2.0", id, method, params }).catch((err) => {

package/dist/readiness.js

@@ -93,16 +93,35 @@ export async function waitForRuntimeBridge(cfg, timeoutMs) {
  * message that says what broke has done half the job — applied to a field rather
  * than to a message: `bridge_ready: false` says what happened, and this says what
  * to do about it.
+ *
+ * 🔴 BOTH SENTENCES WERE REWRITTEN AT 267, AND A GATE FOUND THEM RATHER THAN A READER.
+ * Widening check 28's grammar to the host's OWN remedies — until then it read only
+ * `error_remedies.gd` — refused both of these at once, and the two refusals were the same
+ * two defects this project has now found three times:
+ *
+ * 1. **They opened by describing the failure.** *The process launched but the runtime
+ *    bridge … did not answer ping* is a second copy of what `bridge_ready: false` already
+ *    said. The next action arrived in the last clause, after 200 characters, which is the
+ *    exact shape 254 moved the addon's remedies away from.
+ * 2. 🔴 **AND THE SECOND ASKED A QUESTION OVER TWO CAUSES.** *Is the "Breakpoint MCP"
+ *    plugin enabled in this project?* — with *if the project is simply slow to boot* three
+ *    clauses later, so the sentence named both causes and instructed on neither. That is
+ *    266 §1's finding, in a different file, surviving the session that fixed it: the
+ *    question was removed from `peers.ts` and left standing here, because nothing joined
+ *    the two sites. A gate over the whole population is what joined them.
+ *
+ * Neither cause can be discriminated from here — a ping that went unanswered inside the
+ * wait says nothing about which — so the repair is to name both and give one action each,
+ * not to guess.
  */
 export function notReadyRemedy(cfg, waitedMs) {
     if (waitedMs <= 0) {
-        return (`The process launched and no wait was requested (wait_timeout_ms 0), so nothing here knows whether the ` +
-            `runtime bridge at ${cfg.runtimeHost}:${cfg.runtimePort} is up yet. Call runtime_get_tree to find out, or ` +
-            `re-run without wait_timeout_ms and this tool will wait and answer.`);
+        return (`Call \`runtime_get_tree\` to find out whether the runtime bridge at ` +
+            `${cfg.runtimeHost}:${cfg.runtimePort} is up, or re-run with a wait above 0 — the process launched ` +
+            `and wait_timeout_ms 0 asked for no wait, so this is unknown, not failed.`);
     }
-    return (`The process launched but the runtime bridge at ${cfg.runtimeHost}:${cfg.runtimePort} did not answer ping ` +
-        `within ${waitedMs} ms, so a runtime_* call will fail until it does. Is the "Breakpoint MCP" plugin enabled in ` +
-        `this project? The runtime autoload it registers is what binds the port. If the project is simply slow to boot, ` +
-        `raise the wait with wait_timeout_ms.`);
+    return (`Raise wait_timeout_ms and retry if the project is slow to boot, and check the "Breakpoint MCP" ` +
+        `plugin is enabled if it is not — the bridge at ${cfg.runtimeHost}:${cfg.runtimePort} answered no ping ` +
+        `in ${waitedMs} ms and this host cannot tell those apart.`);
 }
 //# sourceMappingURL=readiness.js.map

package/dist/schemas.js

@@ -113,6 +113,10 @@ export const outputSchemas = {
         id: z.string(),
         exited: z.boolean(),
         exit_code: z.number().nullable(),
+        // The signal that ended the child, when one did — null otherwise, and null for a
+        // process still running. Nullable rather than optional, matching exit_code beside it:
+        // a key that vanishes cannot be told apart from a host too old to send it.
+        signal: z.string().nullable(),
         latest_seq: z.number(),
         lines: z.array(z.object({ seq: z.number(), stream: z.enum(["stdout", "stderr"]), text: z.string() })),
     },
@@ -449,6 +453,9 @@ export const outputSchemas = {
         // one inside a shape makes contract_check.py swallow every later entry into
         // this one, and the drift error then names every field in the file.
         stop_on_entry_honored: z.boolean().optional(),
+        // Whether the adapter emitted its initialized event before breakpoints were applied.
+        // Always present: false means the handshake ran out of the order DAP specifies.
+        initialized_seen: z.boolean(),
         // Modifiers dropped when the handshake applied the BUFFERED breakpoints. Buffered
         // modifiers cannot be feature-detected at set time, so this is where their fate is
         // reported; dbg_set_breakpoints said only that detection was deferred.
@@ -457,6 +464,7 @@ export const outputSchemas = {
     },
     dbg_attach: {
         session_id: z.string(), state: z.string(),
+        initialized_seen: z.boolean(),
         unsupported_modifiers: z.array(z.string()).optional(),
         warning: z.string().optional(),
     },
@@ -496,8 +504,8 @@ export const outputSchemas = {
         unresolved: z.array(z.object({ name: z.string(), reason: z.string() })),
     },
     // ---- Plane D: C# debugging / netcoredbg DAP (tools/csdap.ts) ----
-    cs_dbg_launch: { session_id: z.string(), state: z.string() },
-    cs_dbg_attach: { session_id: z.string(), state: z.string() },
+    cs_dbg_launch: { session_id: z.string(), state: z.string(), initialized_seen: z.boolean(), warning: z.string().optional() },
+    cs_dbg_attach: { session_id: z.string(), state: z.string(), initialized_seen: z.boolean(), warning: z.string().optional() },
     cs_dbg_set_breakpoints: {
         path: z.string(), buffered: z.boolean(),
         breakpoints: z.array(z.object({ line: z.number(), verified: z.boolean() })),

package/dist/timeout-cause.js

@@ -0,0 +1,66 @@
+/**
+ * The next action when a request hit its own deadline — the last class of host-raised
+ * failure on the DAP and LSP planes that had nothing to say.
+ *
+ * 🔴 WHY THIS EXISTS, AND WHY IT IS THE END OF A ROW RATHER THAN THE MIDDLE OF ONE.
+ * 264's census counted 25 host-raised failures about the world: ONE carried a remedy in
+ * a field, SEVEN named a next action inside their message where no reader counts it, and
+ * SEVENTEEN said nothing at all. 266 answered the last three that had a field to put an
+ * answer in, and left five that did not — four request deadlines and the C# session
+ * start — because `DapError` and `LspError` had no `remedy` at all. **The gap was never
+ * that nobody knew the answer; it was that there was nowhere to put it.** This module is
+ * the answer for four of the five, and the field it rides on is the other half.
+ *
+ * 🔴 WHAT THE HOST ACTUALLY KNOWS AT THE MOMENT A DEADLINE FIRES, which is the whole
+ * argument for the sentence below. A dropped connection does NOT reach here: every one of
+ * the four clients rejects its pending map from the close handler, with `closeDetail` and
+ * `closeRemedy` (264), on a different code path. An unreachable peer does not reach here
+ * either — `connect()` fails earlier and differently. By the time a deadline can fire the
+ * connection was established and the frame was written, so the honest reading is *the
+ * peer has this request and has not answered yet*, not *the request did not go through*.
+ * That is `timeout-caveat.ts`'s measured argument for the editor bridge, made one
+ * transport over, where it holds for the same structural reason.
+ *
+ * 🔴 AND WHAT IT DELIBERATELY DOES NOT SAY. It does not tell the caller to retry. Three
+ * of the four planes carry mutating requests (`setVariable`, `textDocument/rename`,
+ * `evaluate` with a side effect), and the ledger in `late-reply.ts` exists because a
+ * reply arriving after its deadline is ordinary here, not exotic — so an unqualified
+ * *try again* is the instruction that duplicates the write. The sentence names the knob
+ * and says plainly that a retry is a second request. 264's rule: measure N families,
+ * speak for N.
+ */
+/**
+ * The next action for a request that outlived its deadline.
+ *
+ * `peer` is the noun the plane's own late-reply ledger already uses — "the debug
+ * adapter", "the language server", "the C# debug adapter", "the C# language server" —
+ * so the sentence names what the caller was talking to rather than a socket, exactly as
+ * `closeRemedy` does. `knob` is the environment variable `config.ts` reads that
+ * deadline from, so the instruction is executable rather than a suggestion to be patient.
+ *
+ * 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.
+ */
+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.";