breakpoint-mcp 1.78.1 → 1.78.3

package/dist/bridge.js

@@ -2,9 +2,10 @@ import net from "node:net";
 import { randomUUID } from "node:crypto";
 import { log } from "./logger.js";
 import { OverdueLedger } from "./late-reply.js";
-import { findNonFinite, describeNonFinite, tolerate, TOLERANT_METHODS } from "./finiteness.js";
+import { findNonFinite, describeNonFinite, tolerate, TOLERANT_METHODS, nonFiniteRemedy } from "./finiteness.js";
 import { remedyForWireError } from "./remedies.js";
 import { closeDetail, closeRemedy } from "./close-cause.js";
+import { connectHint, connectRemedy } from "./connect-cause.js";
 export class BridgeError extends Error {
     code;
     /**
@@ -121,7 +122,17 @@ export class BridgeClient {
      * 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") {
+    deadlineKnob = "BREAKPOINT_BRIDGE_TIMEOUT_MS", peerNoun = "the editor", 
+    /**
+     * The env var that names THIS instance's HOST, for the same per-INSTANCE reason
+     * `deadlineKnob` exists (265). The editor bridge takes its address from
+     * BREAKPOINT_BRIDGE_HOST and the runtime bridge and its peers from
+     * BREAKPOINT_RUNTIME_HOST; an unresolved-host remedy naming the wrong one sends the
+     * operator to a knob that cannot move the address they just failed to reach — the
+     * identical defect the late-reply line was given its own knob to avoid. Defaults keep
+     * the editor bridge's wording byte-identical to what shipped.
+     */
+    hostKnob = "BREAKPOINT_BRIDGE_HOST") {
         this.host = host;
         this.port = port;
         this.defaultTimeoutMs = defaultTimeoutMs;
@@ -133,9 +144,12 @@ export class BridgeClient {
         // peer a late reply does, and the two sentences drifting apart would be a bug nobody
         // could see from either side.
         this.peerNoun = peerNoun;
+        this.hostKnob = hostKnob;
     }
     /** Who answers this client — read by the close path and the late-reply ledger alike. */
     peerNoun;
+    /** The env var that moves this client's host — read by the connect path (265). */
+    hostKnob;
     /**
      * A cause this client cannot see, supplied by whoever CAN, as the remedy on a timeout.
      *
@@ -215,7 +229,16 @@ export class BridgeClient {
                 // Recorded for onClose(): if the connection was already up, this reject()
                 // is a no-op on a settled promise and the errno would otherwise be lost.
                 this.lastSocketError = err;
-                reject(new BridgeError(BRIDGE_UNAVAILABLE, `Cannot reach the Godot ${this.label} at ${this.host}:${this.port}. ${this.hint} (${err.message})`));
+                // 🔴 THE ERRNO WAS ALREADY HERE AND ONLY ITS `message` WAS READ (265), which is
+                // 264's close-family finding one step earlier in the same file. `err.code`
+                // separates a port nothing is listening on from a host name that never resolved,
+                // and the hint below was appended to BOTH — telling a caller whose
+                // BREAKPOINT_*_HOST is a typo to go and look at Godot, for a connect where no
+                // packet ever left this machine. `connectHint` suppresses the hint in exactly
+                // that case and returns it untouched otherwise, so every other message a caller
+                // reads is byte-identical to what shipped. See connect-cause.ts.
+                const hint = connectHint(err, this.hint);
+                reject(new BridgeError(BRIDGE_UNAVAILABLE, `Cannot reach the Godot ${this.label} at ${this.host}:${this.port}.${hint ? ` ${hint}` : ""} (${err.message})`, connectRemedy(err, this.peerNoun, this.hostKnob)));
             });
             socket.on("data", (chunk) => this.onData(chunk));
             socket.on("close", () => this.onClose());
@@ -319,7 +342,7 @@ export class BridgeClient {
             else {
                 const hits = findNonFinite(result);
                 if (hits.length)
-                    p.reject(new BridgeError("non_finite", describeNonFinite(hits)));
+                    p.reject(new BridgeError("non_finite", describeNonFinite(hits), nonFiniteRemedy(hits)));
                 else
                     p.resolve(result);
             }

package/dist/connect-cause.js

@@ -0,0 +1,124 @@
+/**
+ * What a FAILED CONNECT's errno discriminates, and the next action for each.
+ *
+ * 🔴 WHY THIS EXISTS — 264 answered the CLOSE family and left the CONNECT site in the
+ * census's silent bucket. They are the same shape one step apart: `close-cause.ts` was
+ * written because five close handlers read `cause.message` and threw `cause.code` away,
+ * and `bridge.ts`'s connect handler does exactly that too. Measured at 265 against real
+ * sockets, two families:
+ *
+ * ```
+ * nothing bound the port       code=ECONNREFUSED  syscall=connect      "connect ECONNREFUSED 127.0.0.1:43305"
+ * host name does not resolve   code=ENOTFOUND     syscall=getaddrinfo  "getaddrinfo ENOTFOUND not-a-real-host.invalid"
+ * ```
+ *
+ * and what a caller received for BOTH was one code and one hint:
+ *
+ * ```
+ * [bridge_unavailable] Cannot reach the Godot editor bridge at 127.0.0.1:43305.
+ *                      Is the editor open with the "Breakpoint MCP" plugin enabled? (connect ECONNREFUSED …)
+ * [bridge_unavailable] Cannot reach the Godot editor bridge at not-a-real-host.invalid:6010.
+ *                      Is the editor open with the "Breakpoint MCP" plugin enabled? (getaddrinfo ENOTFOUND …)
+ * ```
+ *
+ * 🔴 AND THE SECOND ONE IS NOT MERELY UNHELPFUL, IT IS WRONG ABOUT WHAT HAPPENED. On
+ * ENOTFOUND the name never resolved, so nothing was contacted: no packet left this
+ * machine, and whether the editor is open and its plugin enabled had no bearing on the
+ * failure. The caller with a typo in `BREAKPOINT_BRIDGE_HOST` is sent to look at Godot.
+ * That is 263 §3.2's rule — a capability read is a question for somebody, and there may be
+ * nobody — arriving at the transport: the hint answers "why can this peer not serve me",
+ * and in the unresolved case there is no peer on the other end of the question.
+ *
+ * 🔴 THE HINT IS SUPPRESSED RATHER THAN REPLACED. `connectHint` returns `""` for the
+ * unresolved family and the instance's own hint for everything else, so the message a
+ * caller reads is BYTE-IDENTICAL to what shipped in every case except the one that was
+ * making a false claim. The next action goes in the `remedy` FIELD, which is the channel
+ * `remedyClause` reads and 264 §1.2 found seven other sites answering around.
+ *
+ * 🔴 AND WHAT IT DELIBERATELY DOES NOT DO — 264 §3.3's rule, kept. An errno outside the
+ * two measured families gets NO remedy and NO hint change: `classifyConnect` returns
+ * `"unclassified"` and `connectRemedy` returns `undefined`, with a test asserting it.
+ * EHOSTUNREACH, ETIMEDOUT, EACCES and EAI_AGAIN are all plausible here and NONE of them
+ * was driven — this container's egress answers an unroutable address with ECONNREFUSED,
+ * so the case could not be produced honestly and is therefore not spoken for. A third
+ * family inheriting one of these sentences by default would be a claim nobody made
+ * wearing the authority of one that was measured.
+ */
+/**
+ * Errnos that mean the address was reached and the connection was REFUSED.
+ *
+ * ECONNREFUSED: the host's stack answered with RST — the machine is there, and nothing is
+ * listening on that port. It is the ordinary "the editor is not running" case, and it is
+ * the one case where the instance hint is exactly right.
+ */
+export const REFUSED_CONNECT_CODES = new Set(["ECONNREFUSED"]);
+/**
+ * Errnos that mean the host NAME never became an address, so nothing was contacted.
+ *
+ * ENOTFOUND: `getaddrinfo` found no record. Note the syscall — this failure happens
+ * before any packet is sent, which is why the peer's own state cannot be the cause and
+ * the hint that names it has to go.
+ *
+ * EAI_AGAIN is deliberately ABSENT: it is a TEMPORARY resolver failure, its next action
+ * is "retry" rather than "fix the name", and 265 did not drive it.
+ */
+export const UNRESOLVED_HOST_CODES = new Set(["ENOTFOUND"]);
+/**
+ * Which of the three a failed connect was.
+ *
+ * Unlike `classifyClose`, a missing `cause` is NOT a meaningful state here: a connect
+ * that fails always fails with an error, and this handler is only ever reached from
+ * `socket.once("error")`. An absent cause is therefore `"unclassified"`, not a fourth
+ * family invented to fill the slot.
+ */
+export function classifyConnect(cause) {
+    if (!cause)
+        return "unclassified";
+    const code = cause.code;
+    if (typeof code !== "string")
+        return "unclassified";
+    if (REFUSED_CONNECT_CODES.has(code))
+        return "refused";
+    if (UNRESOLVED_HOST_CODES.has(code))
+        return "unresolved";
+    return "unclassified";
+}
+/**
+ * The hint that belongs in the MESSAGE, given what actually failed.
+ *
+ * Returns the instance's own hint unchanged for every family except `"unresolved"`,
+ * where the hint is a statement about a peer that was never contacted. Suppressing is
+ * the whole change: nothing is reworded, so every existing caller and test reading the
+ * refused case reads the same bytes.
+ */
+export function connectHint(cause, hint) {
+    return classifyConnect(cause) === "unresolved" ? "" : hint;
+}
+/**
+ * The next action, given who the peer was and which env var names this client's host —
+ * or `undefined` when the errno does not determine one.
+ *
+ * `hostKnob` is per-INSTANCE for the same reason `deadlineKnob` is (see `BridgeClient`'s
+ * constructor): the editor bridge is configured by `BREAKPOINT_BRIDGE_HOST` and the
+ * runtime bridge and its peers by `BREAKPOINT_RUNTIME_HOST`, and a sentence naming the
+ * wrong one sends the operator to a knob that cannot move the address they just failed
+ * to reach.
+ *
+ * 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 connectRemedy(cause, peer, hostKnob) {
+    switch (classifyConnect(cause)) {
+        case "refused":
+            // The errno is NOT repeated: `bridge.ts` already puts `(connect ECONNREFUSED …)` in
+            // the sentence immediately to the left, and a second copy teaches nobody anything.
+            return (`Start ${peer} and retry — the machine answered and refused the connection, ` +
+                `so the address is right and nothing is listening on that port.`);
+        case "unresolved":
+            return (`Check ${hostKnob} — the host name did not resolve, so nothing was contacted ` +
+                `and the state of ${peer} is not what failed here.`);
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=connect-cause.js.map

package/dist/exit-cause.js

@@ -0,0 +1,110 @@
+/**
+ * What a MANAGED CHILD'S termination discriminates, and the next action for each.
+ *
+ * 🔴 WHY THIS EXISTS — 265 answered the connect family and left the two peer sites in
+ * the census's silent bucket. Driven at 266 against real spawned children, they are the
+ * same shape one file over, and one of them was making a claim that is FALSE rather than
+ * merely absent:
+ *
+ * ```
+ *                          what the caller read
+ * child exited (code 1)    1 of 1 peer(s) did not become ready. peer-1 on 21101: exited (code 1)
+ *                          — SCRIPT ERROR: could not load main scene. Is the Breakpoint MCP
+ *                          addon enabled in this project (it registers the runtime autoload)?
+ *
+ * child alive, no ping     1 of 1 peer(s) did not become ready. peer-1 on 21121: never answered
+ *                          ping. Is the Breakpoint MCP addon enabled in this project (it
+ *                          registers the runtime autoload)?
+ *
+ * two measured causes -> one question -> ZERO next actions
+ * ```
+ *
+ * 🔴 READ THE FIRST ROW. The child EXITED, on its own, with a code and a stderr line
+ * naming what stopped it. Whether the addon is enabled had no bearing on that: an absent
+ * runtime autoload does not stop a process, it stops a process from ANSWERING. The
+ * operator whose scene fails to load is sent to go and look at the plugin list. That is
+ * 265 §1's ENOTFOUND finding at the process boundary — and `m?.exited`, the thing that
+ * says which sentence is true, is computed on the line directly above the one that pastes
+ * the question over both.
+ *
+ * 🔴 THE QUESTION IS SUPPRESSED, NOT REWORDED. `readinessHint` returns the shipped
+ * sentence unchanged when NO not-ready peer exited — the family it was always true of —
+ * and `""` the moment one did. Every caller that reads the silent case reads the same
+ * bytes, and there is a test asserting that direction specifically, because a build that
+ * dropped the question unconditionally would be a worse defect than the one being fixed
+ * and would pass a one-sided test.
+ *
+ * 🔴 AND THE SECOND SITE NAMED A CODE THAT IS NOT A CODE. `peer_exited` rendered
+ * `Peer "peer-1" exited (code null)` for a SIGKILLed child, because
+ * `ProcessRegistry.run` registered `child.on("exit", (code) => …)` and dropped node's
+ * SECOND argument. The signal was handed to that callback on every kill since the
+ * registry was written and assigned to nothing — 265's "a default that compiles asks no
+ * 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.
+ */
+/** How a managed child ended, in the words a person would use. */
+export function describeExit(code, signal) {
+    // The signal is checked FIRST because both can be non-null in no case node produces,
+    // and because `code` is the one that is null exactly when the signal is the answer.
+    if (signal)
+        return `killed by ${signal}`;
+    if (code === null)
+        return "exited without reporting a code";
+    return `exited (code ${code})`;
+}
+/**
+ * The hint that belongs in the MESSAGE, given what actually happened to the children.
+ *
+ * Returns the shipped sentence unchanged while every not-ready peer is merely SILENT —
+ * the family it describes correctly — and suppresses it as soon as one has exited, where
+ * it is a statement about a plugin that could not have stopped a process.
+ */
+export function readinessHint(causes, hint) {
+    return causes.some((c) => c === "exited") ? "" : hint;
+}
+/**
+ * The next action for a peer that did not become ready, branched on the causes in hand.
+ *
+ * Three populations, because the registry really does produce three: every child gone,
+ * every child alive and mute, and a mixture. A mixture gets both actions named rather
+ * than the first one that matched, because telling an operator with one dead peer and one
+ * mute peer to do only half the work is the same error as the sentence this replaces.
+ *
+ * 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 readinessRemedy(causes) {
+    if (causes.length === 0)
+        return undefined;
+    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.`);
+    }
+    if (exited) {
+        return (`Read the output quoted above and fix what stopped the child — it exited on its own, ` +
+            `so the state of the Breakpoint MCP plugin is not what failed here.`);
+    }
+    return (`Enable the "Breakpoint MCP" plugin in this project and retry — the peer is still running ` +
+        `and answered nothing on its port, which is what a missing runtime autoload looks like.`);
+}
+/**
+ * The next action for a request addressed to a peer whose process is already gone.
+ *
+ * Branched on whether the host CAPTURED any output from it: a child that said something
+ * before it died has a cause the caller can read, and one that said nothing has only the
+ * fact of its death, which makes re-spawning the next action rather than reading.
+ */
+export function peerExitRemedy(hasTail) {
+    return hasTail
+        ? `Read the last output quoted above to see what stopped this peer, then spawn a replacement with runtime_spawn_peers.`
+        : `Spawn a replacement with runtime_spawn_peers — this peer captured no output before it went, so there is nothing here to read.`;
+}
+//# sourceMappingURL=exit-cause.js.map

package/dist/finiteness.js

@@ -117,6 +117,42 @@ export function describeNonFinite(hits) {
         `JSON cannot carry them — Godot stringifies INF as 1e99999 and NAN as null — so the ` +
         `call is refused rather than reported as a success with the value silently missing.`);
 }
+/**
+ * The next action for a refused non-finite reply.
+ *
+ * 🔴 ONE FAMILY IS MEASURED AND ONE IS SPOKEN FOR (266). Driven against a raw-bytes fake
+ * addon writing what Godot writes, every value that reaches this refusal is `Infinity` or
+ * `-Infinity` from a literal `1e99999`, flat or nested, one hit or many. **NAN is NOT this
+ * refusal's population**, which the message's own aside makes easy to assume it is:
+ * measured, Godot's `null` for NAN parses to `null`, `findNonFinite({current: null})`
+ * returns `[]`, and the reply RESOLVES and reaches the client's schema as a null. So the
+ * remedy speaks about an infinity and about nothing else, per 265's refusal to invent.
+ *
+ * 🔴 AND IT DOES NOT SAY "RETRY". This is the one host-raised failure in the census whose
+ * cause is neither the transport nor the host's own state but the PROJECT'S DATA — the
+ * engine really does hold that value, and it will hold it again on the next call. A
+ * sentence offering a retry would be the shape 262 §2 found on `dbg_set_variable`: fluent,
+ * addressed to the wrong party, and wrong every time it is read.
+ *
+ * Branched on the one discriminator in hand: how many paths carry it. Naming a single
+ * path is a place to go and look; naming six is almost always one upstream value, and
+ * sending someone to inspect six properties one at a time is the wrong next action.
+ *
+ * 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 nonFiniteRemedy(hits) {
+    if (hits.length === 0)
+        return undefined;
+    if (hits.length === 1) {
+        return (`Inspect ${hits[0].path} in the project — the engine's own value there is infinite ` +
+            `(a division by zero and an unset scale are the usual sources), so this is data to fix ` +
+            `rather than a call to repeat.`);
+    }
+    return (`Look for the one value feeding all ${hits.length} of the paths named above — an infinity ` +
+        `this wide is almost always a single division by zero propagated by the engine, so this is ` +
+        `data to fix rather than a call to repeat.`);
+}
 /**
  * Drop every non-finite value from a flat monitor record, returning what survived and the
  * keys that did not. The declared type of the record does not move: a reading that is not

package/dist/index.js

@@ -30,7 +30,9 @@ async function main() {
     // 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");
+    "BREAKPOINT_RUNTIME_TIMEOUT_MS", "the running game", 
+    // And its ADDRESS comes from BREAKPOINT_RUNTIME_HOST, for the same reason (265).
+    "BREAKPOINT_RUNTIME_HOST");
     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
@@ -50,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.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.78.3" }, { 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/peers.js

@@ -4,6 +4,7 @@ import { ensureProjectSecret, readProjectSecret } from "./secret.js";
 import { log } from "./logger.js";
 import { portFree } from "./ports.js";
 import { waitForBridge } from "./readiness.js";
+import { describeExit, peerExitRemedy, readinessHint, readinessRemedy } from "./exit-cause.js";
 /**
  * Hard ceiling on simultaneously live peers.
  *
@@ -44,6 +45,35 @@ export class PeerRegistry {
     all() {
         return [...this.peers.values()].map((e) => e.info);
     }
+    /**
+     * The one `unknown_peer` refusal, raised from both the read path and the write path.
+     *
+     * 🔴 WHY THIS IS A FUNCTION (265). `clientFor` and `stop` both refused an unknown id
+     * with the code `unknown_peer`, off the SAME registry, in two sentences that had drifted:
+     *
+     * ```
+     * clientFor("peer-9")   No peer with id "peer-9". Live peers: (none). Spawn peers with runtime_spawn_peers, or omit `peer`…
+     * stop("peer-9")        No peer with id "peer-9". Live peers: (none).
+     * ```
+     *
+     * One named a next action and the other stopped dead after the ids, and nothing in this
+     * repository could see the difference — 264 §1.2 measured why: a next action written
+     * into a message BODY reaches no reader, so `remedyClause()` returned `""` for both and
+     * check 28's grammar arm judged neither. The answer moves into the `remedy` FIELD, which
+     * is the channel that IS read, and the two paths stop being two sentences.
+     *
+     * 🔴 AND THE REMEDY IS BRANCHED ON THE REGISTRY, which is the point of 264's "silent,
+     * but the host holds something that discriminates" column. Telling a caller with three
+     * live peers to spawn some is the wrong next action; telling a caller with none to use
+     * one of the ids above names nothing. The registry answers which sentence is true, and
+     * it was in hand at both sites the whole time.
+     */
+    unknownPeer(id) {
+        const ids = this.live().map((p) => p.id);
+        return new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}.`, ids.length
+            ? `Address one of the live peer ids above, or omit \`peer\` to address the default running game.`
+            : `Spawn peers with runtime_spawn_peers, or omit \`peer\` to address the default running game.`);
+    }
     /**
      * The bridge client addressing one peer. Throws a BridgeError the runtime
      * tools' `fail()` renders — an unknown or dead peer must read as a clear
@@ -51,17 +81,17 @@ export class PeerRegistry {
      */
     clientFor(id) {
         const e = this.peers.get(id);
-        if (!e) {
-            const ids = this.live().map((p) => p.id);
-            throw new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}. ` +
-                `Spawn peers with runtime_spawn_peers, or omit \`peer\` to address the default running game.`);
-        }
+        if (!e)
+            throw this.unknownPeer(id);
         if (e.stopped)
             throw new BridgeError("peer_stopped", `Peer "${id}" was stopped by runtime_peer_stop.`);
         const m = this.procs.get(e.managedId);
         if (m?.exited) {
             const tail = this.procs.tail(e.managedId, 6).join(" | ");
-            throw new BridgeError("peer_exited", `Peer "${id}" exited (code ${m.exitCode})${tail ? `; last output: ${tail}` : ""}.`);
+            // 🔴 `describeExit` RATHER THAN `exitCode` ALONE (266). A SIGKILLed child has a null
+            // code and a signal, and this sentence used to render the null: `exited (code null)`.
+            // See exit-cause.ts for the argument node was handing us and nobody declared.
+            throw new BridgeError("peer_exited", `Peer "${id}" ${describeExit(m.exitCode, m.exitSignal)}${tail ? `; last output: ${tail}` : ""}.`, peerExitRemedy(tail.length > 0));
         }
         return e.client;
     }
@@ -149,7 +179,11 @@ export class PeerRegistry {
             // The FILE, not resolveBridgeSecret: the addon's _setup_auth() does not
             // read BREAKPOINT_*_SECRET, so a host-launched child authenticates with
             // whatever is on disk regardless of the host's env overrides.
-            () => readProjectSecret(this.cfg.projectPath));
+            () => readProjectSecret(this.cfg.projectPath), 
+            // A peer's deadline and peer-noun are its own, and so is its ADDRESS: peers are
+            // dialled on `cfg.runtimeHost`, so an unresolved-host remedy here must name
+            // BREAKPOINT_RUNTIME_HOST and not the editor bridge's variable (265).
+            "BREAKPOINT_RUNTIME_TIMEOUT_MS", `peer ${id}`, "BREAKPOINT_RUNTIME_HOST");
             const entry = {
                 info: { id, port, pid: managed.child.pid ?? null, role: opts.role ?? null, ready: false },
                 client,
@@ -164,10 +198,16 @@ export class PeerRegistry {
         }));
         const notReady = spawned.filter((e) => !e.info.ready);
         if (notReady.length) {
+            // 🔴 THE CAUSE IS COLLECTED, NOT JUST RENDERED (266). `m?.exited` decided one word
+            // of the sentence and was then thrown away, so the hint below was pasted over both
+            // measured causes and was FALSE on one of them — an absent runtime autoload does
+            // not stop a process, it stops a process from ANSWERING. See exit-cause.ts.
+            const causes = [];
             const detail = notReady
                 .map((e) => {
                 const m = this.procs.get(e.managedId);
-                const why = m?.exited ? `exited (code ${m.exitCode})` : "never answered ping";
+                causes.push(m?.exited ? "exited" : "silent");
+                const why = m?.exited ? describeExit(m.exitCode, m.exitSignal) : "never answered ping";
                 const tail = this.procs.tail(e.managedId, 6).join(" | ");
                 return `${e.info.id} on ${e.info.port}: ${why}${tail ? ` — ${tail}` : ""}`;
             })
@@ -176,18 +216,17 @@ export class PeerRegistry {
             // can still runtime_peer_stop{all:true}, and a half-started peer that
             // vanished from the registry is harder to reason about than one that
             // reports why it is not ready.
-            throw new BridgeError("peer_not_ready", `${notReady.length} of ${spawned.length} peer(s) did not become ready. ${detail}. ` +
-                `Is the Breakpoint MCP addon enabled in this project (it registers the runtime autoload)?`);
+            const hint = readinessHint(causes, `Is the Breakpoint MCP addon enabled in this project (it registers the runtime autoload)?`);
+            throw new BridgeError("peer_not_ready", `${notReady.length} of ${spawned.length} peer(s) did not become ready. ${detail}.` +
+                (hint ? ` ${hint}` : ""), readinessRemedy(causes));
         }
         return spawned.map((e) => e.info);
     }
     /** Stop one peer (or all). Repeating is a no-op, so the tool is idempotent. */
     stop(id, all = false) {
         const targets = all ? [...this.peers.keys()] : id ? [id] : [];
-        if (!all && id && !this.peers.has(id)) {
-            const ids = this.live().map((p) => p.id);
-            throw new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}.`);
-        }
+        if (!all && id && !this.peers.has(id))
+            throw this.unknownPeer(id);
         const stopped = [];
         for (const t of targets) {
             const e = this.peers.get(t);

package/dist/tools/processes.js

@@ -4,6 +4,7 @@ import { log } from "../logger.js";
 import { ok, failPath } from "./lsp-common.js";
 import { resolveInsideProject } from "../paths.js";
 import { portFree, portConflictMessage } from "../ports.js";
+import { describeExit } from "../exit-cause.js";
 import { waitForRuntimeBridge, notReadyRemedy } from "../readiness.js";
 const LINE_CAP = 5000;
 /**
@@ -33,7 +34,7 @@ export class ProcessRegistry {
             stdio: ["ignore", "pipe", "pipe"],
             ...(env ? { env: { ...process.env, ...env } } : {}),
         });
-        const m = { id, child, lines: [], seq: 0, exited: false, exitCode: null };
+        const m = { id, child, lines: [], seq: 0, exited: false, exitCode: null, exitSignal: null };
         const ingest = (stream) => (buf) => {
             const text = typeof buf === "string" ? buf : buf.toString("utf8");
             for (const line of text.split(/\r?\n/)) {
@@ -47,10 +48,11 @@ export class ProcessRegistry {
         };
         child.stdout?.on("data", ingest("stdout"));
         child.stderr?.on("data", ingest("stderr"));
-        child.on("exit", (code) => {
+        child.on("exit", (code, signal) => {
             m.exited = true;
             m.exitCode = code;
-            log(`managed process ${id} exited (${code})`);
+            m.exitSignal = signal;
+            log(`managed process ${id} ${describeExit(code, signal)}`);
         });
         this.procs.set(id, m);
         return m;

package/package.json

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