breakpoint-mcp 1.74.1 → 1.76.0

package/dist/peers.js

@@ -3,6 +3,7 @@ import { ProcessRegistry } from "./tools/processes.js";
 import { ensureProjectSecret, readProjectSecret } from "./secret.js";
 import { log } from "./logger.js";
 import { portFree } from "./ports.js";
+import { waitForBridge } from "./readiness.js";
 /**
  * Hard ceiling on simultaneously live peers.
  *
@@ -73,9 +74,11 @@ export class PeerRegistry {
      * sequential and the window is sub-millisecond, and the failure mode is
      * benign — the child logs "could not listen" and the readiness wait below
      * reports it with that line attached, rather than the peer silently
-     * half-existing. The DEFAULT runtime port has no such readiness wait, which
-     * is why `godot_run_managed` and `godot_run_project` refuse a held port
-     * outright rather than reporting it after the fact.
+     * half-existing. The DEFAULT runtime port refuses a held port outright rather
+     * than reporting it after the fact — and as of 257 it waits too:
+     * `godot_run_project` and `godot_run_managed` call `waitForRuntimeBridge` and
+     * report `bridge_ready`, so the sentence that used to stand here — *the
+     * default runtime port has no such readiness wait* — is no longer true.
      */
     async allocatePorts(count) {
         const taken = new Set([this.cfg.runtimePort, ...this.live().map((p) => p.port)]);
@@ -95,22 +98,18 @@ export class PeerRegistry {
         }
         return ports;
     }
-    /** Poll a peer's bridge until it answers `ping`, or the deadline passes. */
+    /**
+     * Poll a peer's bridge until it answers `ping`, or the deadline passes.
+     *
+     * 🔴 THE BODY MOVED TO `readiness.ts` AT 257, AND THE POINT IS NOT REUSE. The
+     * comment in `allocatePorts` above named the default runtime port's missing
+     * readiness wait as a property of the design — it was the defect
+     * `run-project-returns-before-bridge`, open since 249. Two copies would have
+     * let the default port's wait drift from the one this module has proven
+     * against real peers since 1.21.0; one function cannot.
+     */
     async waitReady(client, deadline) {
-        for (;;) {
-            const remaining = deadline - Date.now();
-            if (remaining <= 0)
-                return false;
-            try {
-                await client.request("ping", {}, Math.min(1000, remaining));
-                return true;
-            }
-            catch {
-                if (Date.now() >= deadline)
-                    return false;
-                await sleep(100);
-            }
-        }
+        return waitForBridge(client, deadline);
     }
     /**
      * Spawn `count` headless peers and wait until each answers `ping`.

package/dist/readiness.js

@@ -0,0 +1,108 @@
+/**
+ * One readiness wait, for every launcher that hands a caller a bridge.
+ *
+ * 🔴 THE FIELD WAS TRUE AND THE MOMENT WAS FALSE. `godot_run_project` and its
+ * twin `godot_run_managed` returned `running: true` the instant `spawn()` handed
+ * back a pid — measured 566–3213 ms before the game's autoload binds 9081. Every
+ * `runtime_*` call inside that window answers *Is the project running?*, and it
+ * is: the tool said so, and returned the pid. The answer is true, the question is
+ * the wrong one, and no gate in this repository could read the difference.
+ *
+ * The tree already argued against itself here. `peers.ts` waits, and says why:
+ * *"Godot needs ~200 ms to bind, so a tool that returned immediately would hand
+ * the caller peers its very next call cannot reach — a flake in the one feature
+ * that exists to remove flakes."* `allocatePorts`'s comment then names the gap
+ * out loud — *"The DEFAULT runtime port has no such readiness wait"* — as a
+ * property of the design rather than a defect. It was the defect. This module is
+ * that wait, lifted out of `PeerRegistry` so the default port and the peer ports
+ * are ready by the same code and provably so, and `waitReady` there is now a
+ * one-line delegation rather than a second copy.
+ *
+ * 🔴 `ping` IS THE VERB, NOT A TCP CONNECT. `cli/doctor.ts`'s `probeTcp` proves a
+ * socket accepted, which any process holding 9081 does; the launchers already
+ * refuse a held port for exactly that reason. `ping` is answered by the addon's
+ * runtime bridge and by nothing else, and `runtime_bridge.gd` exempts it from the
+ * pause latch, so it is also the one verb that answers on a paused game.
+ */
+import { BridgeClient } from "./bridge.js";
+import { resolveBridgeSecret } from "./secret.js";
+/** Delay between two `ping` attempts while waiting for a bridge to bind. */
+export const READY_POLL_INTERVAL_MS = 100;
+/** Per-attempt deadline, so one slow `ping` cannot eat the whole wait. */
+export const READY_PING_TIMEOUT_MS = 1000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll a bridge until it answers `ping`, or `deadline` passes.
+ *
+ * Returns whether it answered. It never throws: a caller that launched a process
+ * successfully has not failed just because the bridge was slow, and the honest
+ * report of that is a false in a field, not an error in place of the pid.
+ */
+export async function waitForBridge(client, deadline) {
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        try {
+            await client.request("ping", {}, Math.min(READY_PING_TIMEOUT_MS, remaining));
+            return true;
+        }
+        catch {
+            if (Date.now() >= deadline)
+                return false;
+            await sleep(READY_POLL_INTERVAL_MS);
+        }
+    }
+}
+/**
+ * The default runtime port's own client, built the way `index.ts` builds the
+ * long-lived one — same host, same port, same secret resolution order — but
+ * short-lived, because a launcher wants one answer and not a subscription.
+ *
+ * Built here rather than threaded in from `index.ts` because `registerCliTools`
+ * and `registerProcessTools` both take only a `Config`: two toolsets, two
+ * signatures and a stub type would have to change to hand them a client they use
+ * for one `ping`.
+ */
+export function runtimeReadinessClient(cfg) {
+    return new BridgeClient(cfg.runtimeHost, cfg.runtimePort, READY_PING_TIMEOUT_MS, "runtime bridge", "Is the project running?", () => resolveBridgeSecret(cfg.projectPath, ["BREAKPOINT_RUNTIME_SECRET", "BREAKPOINT_BRIDGE_SECRET"]), "BREAKPOINT_RUNTIME_TIMEOUT_MS", "the running game");
+}
+/**
+ * Wait for the DEFAULT runtime bridge after a launch, and report what happened.
+ *
+ * `timeoutMs` of 0 (or less) is the documented opt-out: no client is built, no
+ * socket is opened, and the answer is an honest `{ready: false, waited_ms: 0}` —
+ * *not waited* rather than *waited and failed*, which is what a caller that asked
+ * not to wait needs to be able to tell apart from a launch that lost the race.
+ */
+export async function waitForRuntimeBridge(cfg, timeoutMs) {
+    if (timeoutMs <= 0)
+        return { ready: false, waited_ms: 0 };
+    const start = Date.now();
+    const client = runtimeReadinessClient(cfg);
+    try {
+        const ready = await waitForBridge(client, start + timeoutMs);
+        return { ready, waited_ms: Date.now() - start };
+    }
+    finally {
+        client.close();
+    }
+}
+/**
+ * What a launcher tells a caller whose bridge never came up. 254's rule — a
+ * 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.
+ */
+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 (`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.`);
+}
+//# sourceMappingURL=readiness.js.map

package/dist/remedies.js

@@ -0,0 +1,63 @@
+/**
+ * The next action for a code the ADDON could not name — the host's own fallback.
+ *
+ * 🔴 WHY A FALLBACK AT ALL, AND WHY IT IS EXACTLY ONE ROW (258 §2).
+ * `error_remedies.gd` is the real table: 254 measured 525 `_err(..)` sites across
+ * the two engine planes emitting 216 message templates with 451 of them naming no
+ * next action, and answered it where the codes are raised. This file is not a
+ * second copy of that table and must not become one — check 28f ceilings it at one
+ * row, so a second is a decision somebody makes on purpose against a red gate
+ * rather than a drift nobody notices.
+ *
+ * It exists for one population the addon-side table structurally cannot reach.
+ * `error_remedies.gd` WAS ADDED IN ADDON 1.10.0. Its `unknown_method` row says
+ * *the addon installed in the project is older than the host* — and every addon
+ * old enough to raise `unknown_method` is old enough to predate the file that
+ * would explain it. The remedy shipped only where it was not needed; the set of
+ * users who can receive it and the set who need it are disjoint by construction.
+ *
+ * So the sentence has to come from the side that is current by definition: the
+ * host the user just upgraded. `bridge.ts` reads `remedy` off the wire error and
+ * falls back to this table when the wire carried none, which means a current addon
+ * keeps answering for itself and nothing here overrides it.
+ *
+ * 🔴 AND THE ONE THING THIS CANNOT SEE. `unknown_method` also fires if the HOST
+ * calls a method no addon has ever implemented — a host bug, not a stale addon —
+ * and this remedy would then send a user to reinstall an addon that was never the
+ * problem. That case is gated: `contract_check` joins every method the host calls
+ * to the addon's own dispatch on both planes, so it cannot reach a release. The
+ * remedy is correct for every `unknown_method` that survives CI.
+ */
+/**
+ * code -> next action, used ONLY when the wire error carried no remedy of its own.
+ *
+ * Keyed by the same code vocabulary the addon raises and written to the same
+ * grammar check 28 enforces on `error_remedies.gd` — one imperative at the head, a
+ * full stop at the end, under the length ceiling, every backticked name joined to
+ * something real. It is the same sentence a reader gets from the addon when the
+ * addon is new enough to have one, so it must read the same way.
+ *
+ * 🔴 IT IS NOT `ADDON_SKEW_HINT` REUSED, DELIBERATELY. That constant is what a
+ * TERMINAL prints — single quotes, because backticks in a shell transcript are
+ * command substitution and a user pasting one gets something surprising. This is
+ * what crosses the WIRE to an agent, where backticks are how every other remedy
+ * marks a name. Same instruction, two audiences that read punctuation differently.
+ */
+export const HOST_FALLBACK_REMEDIES = {
+    unknown_method: "Re-run `breakpoint-mcp init --force`, then reopen the project — the addon here is older than the host and plain `init` skips an addon that is already present.",
+};
+/**
+ * The remedy to attach to a wire error: the addon's if it sent one, else the
+ * host's fallback, else nothing.
+ *
+ * The addon ALWAYS wins when it spoke. A newer addon may know something specific
+ * about the failure that a host-side table keyed only on the code cannot — and
+ * silently preferring the generic sentence would make every future addon-side
+ * remedy improvement invisible to the reader who acts on it.
+ */
+export function remedyForWireError(code, fromWire) {
+    if (typeof fromWire === "string" && fromWire !== "")
+        return fromWire;
+    return HOST_FALLBACK_REMEDIES[code];
+}
+//# sourceMappingURL=remedies.js.map

package/dist/result-cost.js

@@ -0,0 +1,90 @@
+/**
+ * The half of client cost the cost instrument could not see.
+ *
+ * 🔴 `token-cost.mjs` GOVERNS THE MENU AND THE MEAL WAS NEVER MEASURED (249, closed
+ * 257). Its unit is `JSON.stringify(tools)` from a live `tools/list` — the catalogue a
+ * client puts in the model's context once — against a byte ceiling that file owns, and
+ * its own header says the rest out loud: *"it reads the tool list over stdio and never
+ * calls a tool."* One `gd_completion` was measured returning, in a single result, very
+ * nearly the byte cost of the ENTIRE advertised surface. The instrument read that tree
+ * and printed `ok`, correctly, about a question nobody was asking.
+ *
+ * This is the missing axis, and it is deliberately a METER rather than a gate: results
+ * depend on a live engine, a live language server and a real project, so nothing here can
+ * refuse at build time without lying about what it measured. What it can do is make the
+ * number obtainable and repeatable — `BREAKPOINT_RESULT_COST=<path>` records one line per
+ * call, and `token-cost.mjs --results <path>` reads them back against a ceiling. A number
+ * that lives in a handoff is a measurement; a number a command can re-take is an
+ * instrument, and 249's 342,116 B has been the first kind for eight sessions.
+ *
+ * 🔴 ONE WRAPPER, AT THE ONE POINT THAT KNOWS BOTH HALVES. `ok()` builds the envelope but
+ * is not told which tool it is answering for — and it is not even one function: six
+ * byte-identical copies exist across the tool files. The `CallTool` dispatcher sees the
+ * name and the result together, and `applyDroppedToolRefusal` already proves the SDK's
+ * handler map can be wrapped in place. This adds one more branch in front of it.
+ *
+ * OFF BY DEFAULT, and off means absent: with the variable unset no wrapper is installed
+ * at all, so the measured path is the shipped path plus nothing.
+ */
+import fs from "node:fs";
+import { log } from "./logger.js";
+const CALL_TOOL_METHOD = "tools/call";
+/** The env var that turns the meter on, and names the file it writes. */
+export const RESULT_COST_ENV = "BREAKPOINT_RESULT_COST";
+/**
+ * The wire cost of one tool result, in the same unit the catalogue is measured in.
+ *
+ * 🔴 THE WHOLE RESULT, NOT THE PAYLOAD. `ok()` returns `content[0].text` — the payload
+ * pretty-printed at two-space indent — AND `structuredContent`, the same object again.
+ * Measuring the payload once would understate what crosses the wire by roughly half, and
+ * the point of this module is to stop understating it.
+ */
+export function resultBytes(result) {
+    try {
+        return Buffer.byteLength(JSON.stringify(result) ?? "", "utf8");
+    }
+    catch {
+        // A result that cannot be stringified cannot have crossed the wire either, so
+        // there is no honest number to record. Zero is the absence of a measurement and
+        // the reader treats it as one.
+        return 0;
+    }
+}
+/** Render one record as the reader's line format: `tool<TAB>bytes`. */
+export function formatRecord(rec) {
+    return `${rec.tool}\t${rec.bytes}\n`;
+}
+/**
+ * Install the meter, if `BREAKPOINT_RESULT_COST` names a file to write.
+ *
+ * Returns whether it installed, so a caller — and a test — can tell "off" from
+ * "on but the dispatcher was missing", which are the same silence otherwise.
+ */
+export function applyResultCost(server, env = process.env) {
+    const path = env[RESULT_COST_ENV];
+    if (!path)
+        return false;
+    const proto = server.server;
+    const handlers = proto?._requestHandlers;
+    const inner = handlers?.get(CALL_TOOL_METHOD);
+    // No dispatcher means no tool was ever registered; there is nothing to meter.
+    if (!handlers || !inner)
+        return false;
+    handlers.set(CALL_TOOL_METHOD, async (request, extra) => {
+        const result = await inner(request, extra);
+        const name = request?.params?.name;
+        if (typeof name === "string") {
+            try {
+                fs.appendFileSync(path, formatRecord({ tool: name, bytes: resultBytes(result) }));
+            }
+            catch (err) {
+                // A meter that takes the server down is worse than a meter that misses a line.
+                log(`[result-cost] could not append to ${path}: ${err.message}`);
+            }
+        }
+        return result;
+    });
+    log(`[result-cost] metering tool results to ${path}`);
+    return true;
+}
+//# sourceMappingURL=result-cost.js.map

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 ----