breakpoint-mcp 1.74.0 → 1.75.0

package/dist/schemas.js

@@ -84,12 +84,31 @@ export const outputSchemas = {
     },
     godot_version: { version: z.string(), raw: capturedRaw },
     godot_launch_editor: { launched: z.boolean(), pid: z.number().nullable(), project: z.string() },
-    godot_run_project: { running: z.boolean(), pid: z.number().nullable(), scene: z.string().nullable() },
+    // 🔴 `running` ALONE WAS THE DEFECT (249, closed 257). It reported that spawn()
+    // returned a pid, and callers read it as "runtime_* is reachable now" — which it
+    // was not, for 566–3213 ms. `running` still means what it always meant; the
+    // three readiness fields are the question that was actually being asked.
+    godot_run_project: {
+        running: z.boolean(),
+        pid: z.number().nullable(),
+        scene: z.string().nullable(),
+        bridge_ready: z.boolean(),
+        bridge_wait_ms: z.number(),
+        bridge_note: z.string().nullable(),
+    },
     godot_export: { preset: z.string(), output_path: z.string(), exit_code: z.number().nullable(), timed_out: z.boolean(), stdout: z.string(), stderr: z.string() },
     godot_import: { exit_code: z.number().nullable(), timed_out: z.boolean(), stdout: z.string(), stderr: z.string() },
     godot_run_headless_script: { script_path: z.string(), exit_code: z.number().nullable(), timed_out: z.boolean(), stdout: z.string(), stderr: z.string() },
     // ---- Managed processes (tools/processes.ts) ----
-    godot_run_managed: { id: z.string(), pid: z.number().nullable(), running: z.boolean(), scene: z.string().nullable() },
+    godot_run_managed: {
+        id: z.string(),
+        pid: z.number().nullable(),
+        running: z.boolean(),
+        scene: z.string().nullable(),
+        bridge_ready: z.boolean(),
+        bridge_wait_ms: z.number(),
+        bridge_note: z.string().nullable(),
+    },
     godot_output: {
         id: z.string(),
         exited: z.boolean(),
@@ -341,7 +360,7 @@ export const outputSchemas = {
     test_detect: { framework: z.string(), path: z.string(), version: z.string() },
     test_list: { dir: z.string(), count: z.number(), tests: z.array(z.string()) },
     // ---- Plane D: semantic / LSP (tools/lsp.ts) ----
-    gd_completion: { items: z.array(z.object({ label: z.string(), kind: z.string(), detail: z.string(), insertText: z.string() })) },
+    gd_completion: { items: z.array(z.object({ label: z.string(), kind: z.string(), detail: z.string(), insertText: z.string() })), truncated: z.boolean() },
     gd_hover: { contents: z.string() },
     gd_definition: { locations: z.array(location) },
     gd_references: { locations: z.array(location) },
@@ -398,7 +417,7 @@ export const outputSchemas = {
         })),
     },
     // ---- Plane D: C# semantic / OmniSharp LSP (tools/cslsp.ts) ----
-    cs_completion: { items: z.array(z.object({ label: z.string(), kind: z.string(), detail: z.string(), insertText: z.string() })) },
+    cs_completion: { items: z.array(z.object({ label: z.string(), kind: z.string(), detail: z.string(), insertText: z.string() })), truncated: z.boolean() },
     cs_hover: { contents: z.string() },
     cs_definition: { locations: z.array(location) },
     cs_references: { locations: z.array(location) },

package/dist/tools/backend.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { remedyClause } from "../bridge.js";
 import { gate } from "../confirm.js";
 import { resolveInsideProject } from "../paths.js";
 /**
@@ -46,7 +47,7 @@ function fail(err) {
     const message = be?.message ?? String(err);
     return {
         isError: true,
-        content: [{ type: "text", text: `Backend scaffold error [${code}]: ${message}` }],
+        content: [{ type: "text", text: `Backend scaffold error [${code}]: ${message}${remedyClause(err)}` }],
     };
 }
 // ---- the known SDKs + their capability matrix ----------------------------

package/dist/tools/cli.js

@@ -7,6 +7,7 @@ import { ok, failPath } from "./lsp-common.js";
 import { resolveInsideProject } from "../paths.js";
 import { portFree, portConflictMessage } from "../ports.js";
 import { runDoctorChecks } from "../cli/doctor.js";
+import { waitForRuntimeBridge, notReadyRemedy } from "../readiness.js";
 const execFileAsync = promisify(execFile);
 /** Run the Godot binary to completion, capturing stdout/stderr. */
 async function runCaptured(cfg, args, timeoutMs, signal) {
@@ -66,6 +67,8 @@ export function registerCliTools(server, cfg) {
     server.registerTool("godot_run_project", {
         title: "Run project",
         description: "Run the project (detached). Optionally start from a specific scene path (res://...). Returns the process id. " +
+            "WAITS until the game's runtime bridge answers ping and reports bridge_ready — the game takes roughly half a " +
+            "second to three seconds to bind it, and no runtime_* tool is reachable before it does. " +
             "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
             "runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
             "than one game at once.",
@@ -77,13 +80,26 @@ export function registerCliTools(server, cfg) {
                 .describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
                 "bridge will NOT be reachable — use only when you want the process for its side effects and will not " +
                 "call any runtime_* tool against it."),
+            wait_timeout_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("How long to wait for the runtime bridge to answer ping, in ms (default 15000, the runtime bridge's own " +
+                "deadline). 0 returns as soon as the process is spawned, reporting bridge_ready false and " +
+                "bridge_wait_ms 0 — waited-not-at-all, which a caller can tell apart from waited-and-lost."),
         },
     }, 
     // 🔴 MEASURED by the LAUNCHED PROCESS'S OWN ARGV: `res://../example_evil/x.tscn`
     // produced `godot --path …/example res://../example_evil/x.tscn` and the game
     // ran it. The port check comes second — a scene that can never legally run
     // should not first claim the runtime port.
-    async ({ scene, allow_port_conflict }) => {
+    //
+    // 🔴 AND THE WAIT COMES LAST, WHICH IS THE WHOLE POINT (257). `portFree` above
+    // asserts 9081 is FREE; this handler used to prove the bridge was not up and
+    // then answer `running: true`, 566–3213 ms before it came up. The field was
+    // true and the moment was false — see `readiness.ts`.
+    async ({ scene, allow_port_conflict, wait_timeout_ms }) => {
         try {
             if (scene !== undefined)
                 resolveInsideProject(scene, cfg.projectPath, "scene");
@@ -98,7 +114,15 @@ export function registerCliTools(server, cfg) {
         if (scene)
             args.push(scene);
         const pid = launchDetached(cfg, args);
-        return ok({ running: true, pid, scene: scene ?? null });
+        const readiness = await waitForRuntimeBridge(cfg, wait_timeout_ms ?? cfg.runtimeTimeoutMs);
+        return ok({
+            running: true,
+            pid,
+            scene: scene ?? null,
+            bridge_ready: readiness.ready,
+            bridge_wait_ms: readiness.waited_ms,
+            bridge_note: readiness.ready ? null : notReadyRemedy(cfg, readiness.waited_ms),
+        });
     });
     registerTaskTool(server, "godot_export", {
         title: "Export project",
@@ -198,22 +222,35 @@ export function registerCliTools(server, cfg) {
             require_live: z
                 .boolean()
                 .optional()
-                .describe("Treat an unreachable bridge as a failure rather than information (default false)"),
+                .describe("Treat an unreachable bridge as a failure rather than information (default false). True means " +
+                "the EDITOR's three bridges — editor, GDScript LSP, GDScript DAP. The runtime bridge lives " +
+                "inside the running game and is deliberately not implied; use live_level for that."),
+            live_level: z
+                .enum(["none", "editor", "runtime", "all"])
+                .optional()
+                .describe("Which bridges this report insists on: none (default), editor (the three the editor brings " +
+                "up), runtime (the one the running game brings up), all. Takes precedence over require_live."),
             include_csharp: z
                 .boolean()
                 .optional()
                 .describe("Also probe OmniSharp / netcoredbg on PATH (the C# planes)"),
             timeout_ms: z.number().int().positive().optional().describe("Per-bridge connect timeout (default 1500)"),
         },
-    }, async ({ require_live, include_csharp, timeout_ms }) => {
+    }, async ({ require_live, live_level, include_csharp, timeout_ms }) => {
         const report = await runDoctorChecks(cfg, {
             timeoutMs: timeout_ms ?? 1500,
-            requireLive: require_live ?? false,
+            liveLevel: live_level ?? (require_live ? "editor" : "none"),
             includeCsharp: include_csharp ?? false,
         });
+        // `failed` counted BOTH severities beside `ok: true` — the same sentence
+        // the CLI summary used to print, in a field an agent reads instead of a
+        // human. Split, so the number that decides the verdict is its own number.
+        const failed = report.checks.filter((c) => c.status === "fail");
         return ok({
             ok: report.ok,
-            failed: report.checks.filter((c) => c.status === "fail").length,
+            failed: failed.length,
+            required_failed: failed.filter((c) => c.severity === "required").length,
+            informational_failed: failed.filter((c) => c.severity === "info").length,
             checks: report.checks,
         });
     });

package/dist/tools/cslsp.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import { z } from "zod";
 import { toFileUri, toFsPath, readFileText, resolveSourceFile } from "../paths.js";
 import { gate } from "../confirm.js";
-import { COMPLETION_KIND, SYMBOL_KIND, ok, fail, markupToString, isMethodNotFound, normalizeLocations, applyTextEdits, normalizeWorkspaceEdit, } from "./lsp-common.js";
+import { COMPLETION_KIND, SYMBOL_KIND, ok, fail, markupToString, isMethodNotFound, normalizeLocations, applyTextEdits, normalizeWorkspaceEdit, capList, COMPLETION_LIMIT } from "./lsp-common.js";
 /**
  * D4 C2 — the C#/.NET semantic plane. Read-only `cs_*` tools mirroring the proven
  * read-only `gd_*` LSP surface, but driven by OmniSharp (spawned over stdio by the
@@ -127,7 +127,23 @@ export function registerCsLspTools(server, cslsp, cfg) {
         line: z.number().int().min(0).describe("0-based line"),
         character: z.number().int().min(0).describe("0-based character"),
     };
-    server.registerTool("cs_completion", { title: "C# completion", description: "Type-aware C# code completion at a position via OmniSharp.", inputSchema: posSchema }, async ({ path, line, character }) => {
+    server.registerTool("cs_completion", {
+        title: "C# completion",
+        description: "Type-aware C# code completion at a position via OmniSharp. Returns at most max_results items " +
+            "(default 200) and sets truncated when the language server offered more — `gd_completion`'s twin, " +
+            "capped for the reason measured on that one.",
+        inputSchema: {
+            ...posSchema,
+            max_results: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Maximum completion items to return (default 200). Completion is the one verb whose result size " +
+                "is a function of project scope rather than of the cursor — one call was measured at 342,116 bytes, " +
+                "more than the entire tool catalogue — so the list is capped and `truncated` says when it was."),
+        },
+    }, async ({ path, line, character, max_results }) => {
         try {
             const uri = await openAndPos(path);
             const result = await cslsp.request("textDocument/completion", { textDocument: { uri }, position: { line, character } });
@@ -136,7 +152,7 @@ export function registerCsLspTools(server, cslsp, cfg) {
                 const it = i;
                 return { label: it.label ?? "", kind: it.kind ? COMPLETION_KIND[it.kind] ?? String(it.kind) : "", detail: it.detail ?? "", insertText: it.insertText ?? it.label ?? "" };
             });
-            return ok({ items });
+            return ok(capList(items, max_results ?? COMPLETION_LIMIT));
         }
         catch (err) {
             return fail(err);

package/dist/tools/editor/common.js

@@ -1,5 +1,6 @@
 import { ok, failPath } from "../lsp-common.js";
 import { resolveInsideProject } from "../../paths.js";
+import { remedyClause } 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");
@@ -11,7 +12,7 @@ export function fail(err) {
     const message = be?.message ?? String(err);
     return {
         isError: true,
-        content: [{ type: "text", text: `Bridge error [${code}]: ${message}` }],
+        content: [{ type: "text", text: `Bridge error [${code}]: ${message}${remedyClause(err)}` }],
     };
 }
 /**

package/dist/tools/lsp-common.js

@@ -18,6 +18,29 @@ export const SYMBOL_KIND = {
     14: "constant", 15: "string", 16: "number", 17: "boolean", 18: "array", 19: "object",
     20: "key", 21: "null", 22: "enumMember", 23: "struct", 24: "event", 25: "operator", 26: "typeParameter",
 };
+/**
+ * The default ceiling on a completion list, and the only reason there is one.
+ *
+ * 🔴 MEASURED: ONE `gd_completion` RETURNED 342,116 B (249) — 99.6% of the whole
+ * 279-tool `tools/list` surface, in a single result, and pretty-printed and shipped
+ * twice by `ok()` below. Completion is the one language-server verb whose result size
+ * is a function of PROJECT scope rather than of the cursor: at most positions it is
+ * every global class, every autoload and every in-scope built-in. `gd_hover`,
+ * `gd_definition` and their C# twins are bounded by the thing under the cursor and are
+ * not in this population.
+ *
+ * 200 is the knowledge family's shipped default — `knowledge.ts` caps grep, symbols and
+ * usages there and returns a `truncated` flag beside them. The same number, because a
+ * second convention would be a second thing to keep true.
+ */
+export const COMPLETION_LIMIT = 200;
+/**
+ * Cap a list and say so. The flag is the whole point: a silently short list reads as a
+ * complete one, which is the failure `knowledge.ts` avoided the same way.
+ */
+export function capList(items, max) {
+    return items.length > max ? { items: items.slice(0, max), truncated: true } : { items, truncated: false };
+}
 /** MCP success envelope: human-readable JSON text plus the structured content. */
 export function ok(obj) {
     return {

package/dist/tools/lsp.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import { z } from "zod";
 import { toFileUri, toFsPath, readFileText, resolveSourceFile } from "../paths.js";
 import { gate } from "../confirm.js";
-import { COMPLETION_KIND, SYMBOL_KIND, ok, fail, markupToString, isMethodNotFound, normalizeLocations, applyTextEdits, } from "./lsp-common.js";
+import { COMPLETION_KIND, SYMBOL_KIND, ok, fail, markupToString, isMethodNotFound, normalizeLocations, applyTextEdits, capList, COMPLETION_LIMIT } from "./lsp-common.js";
 /**
  * The wording this plane's refusals have shipped with, kept verbatim while the guard
  * itself moved to `paths.ts` (161 §8 item 5). `lsp-plane.integration.mjs` pins every
@@ -238,7 +238,22 @@ export function registerLspTools(server, lsp, cfg) {
         line: z.number().int().min(0).describe("0-based line"),
         character: z.number().int().min(0).describe("0-based character"),
     };
-    server.registerTool("gd_completion", { title: "GDScript completion", description: "Type-aware code completion at a position via the Godot language server.", inputSchema: posSchema }, async ({ path, line, character }) => {
+    server.registerTool("gd_completion", {
+        title: "GDScript completion",
+        description: "Type-aware code completion at a position via the Godot language server. Returns at most max_results " +
+            "items (default 200) and sets truncated when the language server offered more.",
+        inputSchema: {
+            ...posSchema,
+            max_results: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Maximum completion items to return (default 200). Completion is the one verb whose result size " +
+                "is a function of project scope rather than of the cursor — one call was measured at 342,116 bytes, " +
+                "more than the entire tool catalogue — so the list is capped and `truncated` says when it was."),
+        },
+    }, async ({ path, line, character, max_results }) => {
         try {
             const uri = await openAndPos(path);
             const result = await lsp.request("textDocument/completion", { textDocument: { uri }, position: { line, character } });
@@ -247,7 +262,7 @@ export function registerLspTools(server, lsp, cfg) {
                 const it = i;
                 return { label: it.label ?? "", kind: it.kind ? COMPLETION_KIND[it.kind] ?? String(it.kind) : "", detail: it.detail ?? "", insertText: it.insertText ?? it.label ?? "" };
             });
-            return ok({ items });
+            return ok(capList(items, max_results ?? COMPLETION_LIMIT));
         }
         catch (err) {
             return fail(err);

package/dist/tools/netcode.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { remedyClause } from "../bridge.js";
 import { gate } from "../confirm.js";
 import { readFileText, resolveExistingFile, resolveInsideProject } from "../paths.js";
 /**
@@ -41,7 +42,7 @@ function fail(err) {
     const message = be?.message ?? String(err);
     return {
         isError: true,
-        content: [{ type: "text", text: `Netcode scaffold error [${code}]: ${message}` }],
+        content: [{ type: "text", text: `Netcode scaffold error [${code}]: ${message}${remedyClause(err)}` }],
     };
 }
 // ------------------------------------------------------------- codegen ----

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 { waitForRuntimeBridge, notReadyRemedy } from "../readiness.js";
 const LINE_CAP = 5000;
 /**
  * Runs Godot as a MANAGED child (piped stdio) so the host captures ALL stdout/
@@ -86,6 +87,8 @@ export function registerProcessTools(server, cfg) {
         title: "Run project (managed, captured output)",
         description: "Run the project as a managed child process with captured stdout/stderr, so godot_output can read ALL print()/error output. " +
             "Returns a process id. Use this instead of godot_run_project when you want the game's console log. " +
+            "WAITS until the game's runtime bridge answers ping and reports bridge_ready, exactly as godot_run_project " +
+            "does — no runtime_* tool is reachable before it does. " +
             "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
             "runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
             "than one game at once.",
@@ -97,12 +100,24 @@ export function registerProcessTools(server, cfg) {
                 .describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
                 "bridge will NOT be reachable — use only when you want the process for its console output or side " +
                 "effects and will not call any runtime_* tool against it."),
+            wait_timeout_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("How long to wait for the runtime bridge to answer ping, in ms (default 15000, the runtime bridge's own " +
+                "deadline). 0 returns as soon as the process is spawned, reporting bridge_ready false and " +
+                "bridge_wait_ms 0 — waited-not-at-all, which a caller can tell apart from waited-and-lost."),
         },
     }, 
     // 🔴 `godot_run_project`'s TWIN, in a different file, with the same defect —
     // measured the same way and launching the same escaping argv. 1.42.0's lesson
     // ("the second call site is the interesting one") applied before the fact.
-    async ({ scene, allow_port_conflict }) => {
+    //
+    // 🔴 AND THE SAME LESSON AGAIN AT 257 FOR THE READINESS RACE. The queue row
+    // `run-project-returns-before-bridge` names only `godot_run_project`; this
+    // returned `running: true` at the same false moment and no row said so.
+    async ({ scene, allow_port_conflict, wait_timeout_ms }) => {
         try {
             if (scene !== undefined)
                 resolveInsideProject(scene, cfg.projectPath, "scene");
@@ -114,7 +129,16 @@ export function registerProcessTools(server, cfg) {
             return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
         }
         const m = registry.run(cfg, scene ? [scene] : []);
-        return ok({ id: m.id, pid: m.child.pid ?? null, running: true, scene: scene ?? null });
+        const readiness = await waitForRuntimeBridge(cfg, wait_timeout_ms ?? cfg.runtimeTimeoutMs);
+        return ok({
+            id: m.id,
+            pid: m.child.pid ?? null,
+            running: true,
+            scene: scene ?? null,
+            bridge_ready: readiness.ready,
+            bridge_wait_ms: readiness.waited_ms,
+            bridge_note: readiness.ready ? null : notReadyRemedy(cfg, readiness.waited_ms),
+        });
     });
     server.registerTool("godot_output", {
         title: "Read managed process output",

package/dist/tools/runtime.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isTransportUnavailable, remedyClause } from "../bridge.js";
 import { MAX_PEERS } from "../peers.js";
 import { gate } from "../confirm.js";
 import { ok, failPath } from "./lsp-common.js";
@@ -26,7 +27,7 @@ function fail(err) {
     const be = err;
     return {
         isError: true,
-        content: [{ type: "text", text: `Runtime error [${be?.code ?? "error"}]: ${be?.message ?? String(err)}` }],
+        content: [{ type: "text", text: `Runtime error [${be?.code ?? "error"}]: ${be?.message ?? String(err)}${remedyClause(err)}` }],
     };
 }
 /**
@@ -259,14 +260,21 @@ export function registerRuntimeTools(server, runtime, peers, config) {
             "Capture the baseline earlier with runtime_get_monitors and pass it back inline. Pass direction is inferred " +
             "(time/fps is higher-better; every other monitor is lower-better) unless overridden per key.",
         inputSchema: {
-            // 🔴 226 §2 — `.finite()` REFUSES `1e999` AT THE DOOR AND MOVES NO BYTE ON THE
-            // WIRE. `zodToJsonSchema` emits `{"type":"number"}` for both forms, measured, so
-            // this narrows what the host accepts without changing what it advertises. Before
-            // it, a well-formed call carrying `1e999` reached `float(baseline[key])` in
-            // runtime_bridge.gd as `inf` and came back as `1e99999` — the one non-finite path
-            // in this tree that needed no engine edge case at all.
+            // 🔴 226 §2 — `1e999` MUST NOT REACH `float(baseline[key])` IN runtime_bridge.gd,
+            // where it arrives as `inf` and comes back as `1e99999`: the one non-finite path in
+            // this tree that needs no engine edge case at all, only a well-formed call.
+            //
+            // 🆕 255 — AND THE `.finite()` THAT CLOSED IT IS GONE, BECAUSE THE BASE TYPE CLOSED
+            // IT. Under the major this tree left, `z.number()` accepted ±Infinity and the
+            // refinement was the whole guard; under the installed one `z.number()` refuses it
+            // and `.finite()` contributes NO check and NO bag entry — measured, not assumed:
+            // `wire_invisible_gate.mjs` found the roster row it had been pinned by standing over
+            // nothing. A call that adds no rule is a sentence wearing a rule's clothes, and this
+            // repository has spent three sessions deleting those. What holds the door now is
+            // asserted in `finiteness.test.ts` against the INSTALLED zod, so a future major that
+            // relaxes `z.number()` reddens there rather than silently re-opening this line.
             baseline: z
-                .record(z.string(), z.number().finite())
+                .record(z.string(), z.number())
                 .describe("Monitor key -> baseline value (capture earlier via runtime_get_monitors)"),
             tolerance: z
                 .number()
@@ -357,7 +365,9 @@ export function registerRuntimeTools(server, runtime, peers, config) {
         title: "Runtime await condition",
         description: "Poll a property on a LIVE node until it satisfies a comparison, or a timeout elapses (read-only verification). " +
             "op is eq | ne | gt | ge | lt | le (the ordered operators require numeric values). Use this to wait for the " +
-            "running game to reach a state before asserting on it — e.g. wait for hp le 0, then runtime_assert_screen_text.",
+            "running game to reach a state before asserting on it — e.g. wait for hp le 0, then runtime_assert_screen_text. " +
+            "An unreachable runtime bridge is retried until the timeout rather than failing on the first poll, so this " +
+            "tool can also be used to wait for a game that is still booting.",
         inputSchema: {
             path: z.string().describe("Node path (relative to the current scene; '/root/...' absolute allowed)"),
             property: z.string().describe("Property to read on each poll"),
@@ -388,7 +398,21 @@ export function registerRuntimeTools(server, runtime, peers, config) {
                 res = (await client.request("runtime.get_property", { path, property }));
             }
             catch (err) {
-                return fail(err);
+                // 🔴 THE ONE WAITING TOOL DID NOT WAIT FOR THE ONE THING WORTH WAITING
+                // FOR (249, closed 257). Every error ended the loop here, so a caller
+                // that set timeout_ms 15000 against a game that was still booting got
+                // an answer in 2 ms with polls 1 — `deadline` and `sleep(interval)`
+                // are both downstream of this catch and were never reached.
+                //
+                // `bridge_unavailable` is the transport saying *not yet*; every other
+                // code is the game saying *no* — a missing node, an unknown property,
+                // a refused method — and retrying those would turn a precise failure
+                // into a slow one. So the retry is scoped to the one code, and it is
+                // still bounded by the caller's own deadline rather than by a new one.
+                if (!isTransportUnavailable(err) || Date.now() >= deadline)
+                    return fail(err);
+                await sleep(interval);
+                continue;
             }
             last = res?.value ?? null;
             if (compareValues(last, value, operator)) {

package/dist/tools/tabletop.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { z } from "zod";
+import { remedyClause } from "../bridge.js";
 import { gate } from "../confirm.js";
 import { readFileText, resolveExistingFile, resolveInsideProject, resolveWriteTarget } from "../paths.js";
 /**
@@ -36,7 +37,7 @@ function fail(err) {
     const message = be?.message ?? String(err);
     return {
         isError: true,
-        content: [{ type: "text", text: `Tabletop compose error [${code}]: ${message}` }],
+        content: [{ type: "text", text: `Tabletop compose error [${code}]: ${message}${remedyClause(err)}` }],
     };
 }
 /** A bad-input failure that reads like a bridge error but never reaches the bridge. */

package/dist/wire-defaults.js

@@ -6,10 +6,19 @@ import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
  * conforming peer does not already assume. Both are removed on the way out.
  *
  *  1. 🔴 `"$schema": "http://json-schema.org/draft-07/schema#"`, inside EVERY input and
- *     output schema. Nobody in this repo writes it: the SDK converts our Zod through
- *     `zod-to-json-schema`, which defaults to draft-07, and offers no target knob on the
- *     Zod-v3 path (`server/zod-json-schema-compat.js` — the `target` option is read only
- *     by the Zod-v4 branch). MCP fixes the DEFAULT dialect at JSON Schema 2020-12 and
+ *     output schema. Nobody in this repo writes it: the SDK converts our Zod and asks for
+ *     draft-07 while doing it.
+ *
+ *     🆕 255 — AND MOVING TO THE ZOD-v4 BRANCH DID NOT CHANGE THAT, WHICH THE PARAGRAPH
+ *     THIS REPLACES IMPLIED IT WOULD. The old text read "the `target` option is read only
+ *     by the Zod-v4 branch", which is true and useless: `server/mcp.js` calls
+ *     `toJsonSchemaCompat` with no `target` at either version, and the v4 branch maps an
+ *     absent target to `'draft-7'` before handing it to zod's own converter. So the
+ *     declaration on the wire is the SDK's choice and not the library's, it survived a
+ *     major bump unchanged, and this strip stays necessary — the same conclusion the
+ *     migration spike reached from the outside, now measured from inside the tree.
+ *
+ *     MCP fixes the DEFAULT dialect at JSON Schema 2020-12 and
  *     requires every implementation to support it; a `$schema` field is an EXPLICIT
  *     SWITCH to a dialect nobody is obliged to support and which a peer MUST reject
  *     gracefully if it does not. So this is not decoration and it is not a trim:
@@ -49,12 +58,65 @@ export const DIALECT_SENSITIVE = [
     ["exclusiveMinimum", (v) => typeof v === "boolean"], // draft-04 form
     ["exclusiveMaximum", (v) => typeof v === "boolean"], // draft-04 form
     ["dependencies", () => true], //                  split into dependentSchemas/dependentRequired
-    ["definitions", () => true], //                   $defs in 2020-12
-    ["$defs", () => true], //                         2020-12 only — the label would be wrong already
     ["prefixItems", () => true], //                   2020-12 only
     ["unevaluatedProperties", () => true], //         2020-12 only
     ["unevaluatedItems", () => true], //              2020-12 only
 ];
+/**
+ * The definition CONTAINERS, which are the one entry above that could not be decided from
+ * its own value.
+ *
+ * 🔴 255 — AND THEY WERE ON THE LIST FOR A SPELLING DIFFERENCE THAT DOES NOT REACH A
+ * REFERENCE. `definitions` is draft-07's container and `$defs` is 2020-12's, so each is an
+ * unknown keyword under the other dialect — and an unknown keyword is one both specs
+ * require a validator to IGNORE. What actually resolves a reference is `$ref`, and
+ * `"#/definitions/X"` is a URI-reference resolved as a JSON Pointer into the same schema
+ * resource under BOTH dialects: the pointer walks the document by key, and it does not
+ * care whether the key it walks through is vocabulary or not.
+ *
+ * So the container is dialect-bound only when something inside it is REACHED BY A NAME
+ * rather than by a path — `$anchor` (2020-12 only) or a nested `$id` (a new base URI in
+ * both, resolved differently) — or when a `$ref` anywhere in the document is not a plain
+ * local pointer. That is the predicate below, and it is a property of the WHOLE document,
+ * which is why it could not live in the table above.
+ *
+ * 🔴 THIS WAS MEASURED BEFORE IT WAS BELIEVED, AND IT IS MEASURED AGAIN ON EVERY RUN.
+ * `wire_defaults.test.ts` compiles the STRIPPED schema under a strict 2020-12 validator
+ * and the declared one under draft-07, and compares their verdicts on probe instances —
+ * Ajv is a second opinion with no stake in this argument. The fail-safe is not weakened:
+ * a container that is reached by name, or a reference that leaves the document, still
+ * keeps its declaration.
+ */
+const CONTAINER_KEYS = ["definitions", "$defs"];
+/** Reached by NAME rather than by path — the two ways a container stops being inert. */
+const NAME_REACHED = new Set(["$id", "$anchor", "$dynamicAnchor", "$dynamicRef", "$recursiveAnchor", "$recursiveRef"]);
+/**
+ * Can a definition container be renamed between dialects without changing meaning?
+ * A property of the whole document: every `$ref` in it must be a plain local pointer, and
+ * nothing anywhere may be reached by name.
+ */
+export function containersInert(doc) {
+    let inert = true;
+    const walk = (node) => {
+        if (!inert || node === null || typeof node !== "object")
+            return;
+        if (Array.isArray(node))
+            return node.forEach(walk);
+        for (const [k, v] of Object.entries(node)) {
+            if (NAME_REACHED.has(k)) {
+                inert = false;
+                return;
+            }
+            if (k === "$ref" && !(typeof v === "string" && v.startsWith("#/"))) {
+                inert = false;
+                return;
+            }
+            walk(v);
+        }
+    };
+    walk(doc);
+    return inert;
+}
 /** Keys under these keywords are AUTHOR-CHOSEN NAMES, not schema vocabulary. */
 const NAME_BEARING = new Set(["properties", "patternProperties", "definitions", "$defs"]);
 /**
@@ -65,12 +127,20 @@ const NAME_BEARING = new Set(["properties", "patternProperties", "definitions",
  * have kept the declaration on the whole surface; the hit was `scene_get_dependencies`'s
  * output field, a property NAMED dependencies. A walker that cannot tell a keyword from a
  * key reads an author's vocabulary as the protocol's.
+ *
+ * 🔴 THE CONTAINER ANSWER IS COMPUTED ONCE, AT THE DOCUMENT, AND CARRIED DOWN. Whether
+ * `definitions` is load-bearing is not readable from `definitions` — see `containersInert`
+ * — so the recursion threads the document's answer rather than re-deriving a different one
+ * at each level, which is how the same schema would get two verdicts from one walk.
  */
 export function dialectSensitive(node, inNamePosition = false) {
+    return walkSensitive(node, inNamePosition, containersInert(node));
+}
+function walkSensitive(node, inNamePosition, inert) {
     if (node === null || typeof node !== "object")
         return false;
     if (Array.isArray(node))
-        return node.some((v) => dialectSensitive(v, false));
+        return node.some((v) => walkSensitive(v, false, inert));
     const obj = node;
     // draft-07 ignores keywords adjacent to $ref; 2020-12 applies them.
     if (obj.$ref !== undefined && Object.keys(obj).length > 1)
@@ -80,8 +150,10 @@ export function dialectSensitive(node, inNamePosition = false) {
             for (const [key, matches] of DIALECT_SENSITIVE)
                 if (k === key && matches(v))
                     return true;
+            if (!inert && CONTAINER_KEYS.includes(k))
+                return true;
         }
-        if (dialectSensitive(v, NAME_BEARING.has(k)))
+        if (walkSensitive(v, NAME_BEARING.has(k), inert))
             return true;
     }
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.74.0",
+  "version": "1.75.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",
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.25.76"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",