breakpoint-mcp 1.74.1 → 1.76.0

package/dist/cli/doctor.js

@@ -14,6 +14,18 @@
  * may legitimately not be running when a user checks their install; pass
  * `--require-live` when you expect them up (e.g. after opening the editor).
  *
+ * 🔴 THE FOUR BRIDGES DO NOT COME UP TOGETHER, AND `--require-live` USED TO
+ * PRETEND THEY DID. Opening the editor starts three of them — the addon's
+ * bridge on 9080 and Godot's own LSP/DAP. The runtime bridge on 9081 lives
+ * INSIDE THE GAME and binds only while the project is running. So the one
+ * instruction `docs/USER_GUIDE.md` §3.0, `README.md` and `init`'s own closing
+ * line all give a new user — open the editor, then run `doctor --require-live`
+ * — exited 1 on a completely correct install, every time, because it demanded a
+ * game nobody had been told to launch. `LIVE_LEVELS` is that distinction made
+ * nameable: bare `--require-live` asserts what opening the editor makes true,
+ * and `--require-live=all` is the old four-bridge contract, still reachable and
+ * now something a caller asks for on purpose.
+ *
  * Configuration is read via loadConfig(), so the same env overrides the server
  * honours (GODOT_BIN, GODOT_PROJECT, and the BREAKPOINT_ / GODOT_ ports) apply here.
  */
@@ -27,7 +39,24 @@ import { parseArgs, preflight } from "./args.js";
 import { DOCTOR_FLAGS, DOCTOR_USAGE } from "./usage.js";
 import { BridgeClient } from "../bridge.js";
 import { resolveBridgeSecret } from "../secret.js";
-const ADDON_REL = "addons/breakpoint_mcp";
+import { ADDON_REL, ADDON_SKEW_HINT, compareAddonVersions, readAddonVersion, } from "../addon-version.js";
+import { resolveBundledAddon } from "./init.js";
+/**
+ * Which bridges a run insists on.
+ *
+ *   none    — every bridge is informational (the default: a user checking an
+ *             install has neither the editor nor the game up, necessarily)
+ *   editor  — the three the EDITOR brings up: editor bridge, GDScript LSP, DAP
+ *   runtime — the one the GAME brings up: the runtime bridge on 9081
+ *   all     — all four
+ *
+ * The order matters to nothing; the tier a bridge belongs to is declared on the
+ * bridge, so adding a fifth is one field and no new branch.
+ */
+export const LIVE_LEVELS = ["none", "editor", "runtime", "all"];
+export function severityFor(level, tier) {
+    return level === "all" || level === tier ? "required" : "info";
+}
 const PLUGIN_CFG_RES = "res://addons/breakpoint_mcp/plugin.cfg";
 /** Resolve after a TCP connect succeeds (true) or the port is closed/times out (false). */
 function probeTcp(host, port, timeoutMs) {
@@ -90,6 +119,57 @@ function checkGodotBinary(bin, timeoutMs) {
         detail: `${bin} → ${version}`,
     };
 }
+/**
+ * The pair nothing compared until 258 §2: the addon a project has INSTALLED
+ * against the addon this host SHIPS.
+ *
+ * 🔴 WHY `info` AND NOT `required`, ON THE RECORD. `doctor`'s exit code is a
+ * pre-flight contract, and 252 spent a whole row fixing `--require-live` for
+ * exactly one reason: it exited 1 on a correct install. An addon a release or two
+ * behind answers almost every method the host calls — an addon at 1.9.1 answers
+ * 260 of the current 265 — so a red exit would be wrong for most of the population
+ * that has one. The skew is REPORTED, loudly and with the command that clears it;
+ * it does not fail the run. Promoting it is one word if that turns out to be the
+ * wrong call.
+ *
+ * `newer` is not folded into `older`. An installed addon ahead of the host is a
+ * developer running the repo copy against an older published host, and telling
+ * that person to overwrite it with `--force` would destroy the newer one.
+ */
+function addonVersionCheck(installed) {
+    const bundledDir = resolveBundledAddon();
+    const bundled = bundledDir === null ? null : readAddonVersion(bundledDir);
+    const skew = compareAddonVersions(installed, bundled);
+    const pair = `installed ${installed ?? "?"} · this host ships ${bundled ?? "?"}`;
+    if (skew === "same") {
+        return { name: "addon-version", status: "ok", severity: "info", detail: `matches this host (${installed})` };
+    }
+    if (skew === "unknown") {
+        return {
+            name: "addon-version",
+            status: "skip",
+            severity: "info",
+            detail: `not comparable (${pair})`,
+            hint: "Neither version parsed as a dotted number, so no direction can be reported without guessing at it.",
+        };
+    }
+    if (skew === "newer") {
+        return {
+            name: "addon-version",
+            status: "ok",
+            severity: "info",
+            detail: `ahead of this host (${pair})`,
+            hint: "The project's addon is newer than the one bundled here. Upgrade the host ('npm i -g breakpoint-mcp@latest') rather than overwriting the addon.",
+        };
+    }
+    return {
+        name: "addon-version",
+        status: "fail",
+        severity: "info",
+        detail: `older than this host (${pair})`,
+        hint: ADDON_SKEW_HINT,
+    };
+}
 function checkAddon(projectPath) {
     const projText = readText(path.join(projectPath, "project.godot"));
     if (projText === null) {
@@ -115,13 +195,14 @@ function checkAddon(projectPath) {
         });
     }
     else {
-        const m = /version\s*=\s*"([^"]*)"/.exec(cfgText);
+        const installed = readAddonVersion(path.join(projectPath, ADDON_REL));
         checks.push({
             name: "addon-installed",
             status: "ok",
             severity: "required",
-            detail: `${ADDON_REL} (version ${m ? m[1] : "?"})`,
+            detail: `${ADDON_REL} (version ${installed ?? "?"})`,
         });
+        checks.push(addonVersionCheck(installed));
     }
     checks.push(isPluginEnabled(projText)
         ? {
@@ -198,9 +279,12 @@ export function checkCapabilities(config) {
             detail: dropped.length === 0
                 ? `${state} — full 292-tool surface`
                 : `${state} (secure default) — ${dropped.length} higher-trust tool(s) dropped from the surface`,
+            // The token list is DERIVED — `code-execution,network` was printed here
+            // for as long as the `network` group has been deleted, so the remedy
+            // named a token `selectPrivilegedGroups` reports as unknown and drops.
             hint: dropped.length === 0
                 ? undefined
-                : "Enable with BREAKPOINT_PRIVILEGED_GROUPS=code-execution,network (or `breakpoint-mcp init --trust full`). See the godot://capabilities resource for the exact tool list.",
+                : `Enable with BREAKPOINT_PRIVILEGED_GROUPS=${CAPABILITY_GROUPS.join(",")} (or \`breakpoint-mcp init --trust full\`). See the godot://capabilities resource for the exact tool list.`,
         },
     ];
     const assetGenConfigured = (config.assetGenBackend && config.assetGenBackend !== "none") ||
@@ -225,20 +309,61 @@ export function checkCapabilities(config) {
  * secret that no longer matches the one the addon minted. `probeTcp` can see
  * neither, which is what made "editor-bridge reachable" a check that could pass
  * while every tool failed.
+ *
+ * 🔴 AND IT NOW KEEPS THE ANSWER. `ping` has replied with `addon_version` since the
+ * addon had one, and all four of its consumers threw it away — this one returned
+ * `boolean`, `readiness.ts` returns `boolean`, and the two tool paths hand it to the
+ * model and forget it. That is the third of 258 §2's four compounding parts: the
+ * version of the addon ACTUALLY LOADED never reached anything that could compare it.
+ * Files on disk are not what is running — Godot reads the addon at project load, so
+ * `init --force` fixes the disk and changes nothing until the editor restarts, and
+ * that gap is exactly where a user concludes the fix did not work.
  */
 async function handshakeOk(config, b, timeoutMs) {
     const client = new BridgeClient(b.host, b.port, timeoutMs, "bridge", undefined, () => resolveBridgeSecret(config.projectPath, b.secretEnv ?? []));
     try {
-        await client.request("ping", {}, timeoutMs);
-        return true;
+        const reply = (await client.request("ping", {}, timeoutMs));
+        const v = reply?.addon_version;
+        return { ok: true, addonVersion: typeof v === "string" && v !== "" ? v : null };
     }
     catch {
-        return false;
+        return { ok: false, addonVersion: null };
     }
     finally {
         client.close();
     }
 }
+/**
+ * The live half of the pair: the addon a bridge REPORTS against the one this host
+ * ships. Emitted only when a bridge actually answered with a version, so a closed
+ * editor produces no row rather than a row about nothing.
+ */
+export function addonRunningCheck(bridge, running, bundled) {
+    if (running === null)
+        return null;
+    // One row per answering bridge, named after it: a stale editor and a stale game are
+    // two different states with two different next actions — reopen the project, versus
+    // relaunch it — and collapsing them into one `addon-running` row would report
+    // whichever process happened to be asked first.
+    const name = `addon-running-${bridge.replace(/-bridge$/, "")}`;
+    const skew = compareAddonVersions(running, bundled);
+    const pair = `${bridge} reports ${running} · this host ships ${bundled ?? "?"}`;
+    if (skew === "older") {
+        return {
+            name,
+            status: "fail",
+            severity: "info",
+            detail: `older than this host (${pair})`,
+            hint: ADDON_SKEW_HINT,
+        };
+    }
+    return {
+        name,
+        status: "ok",
+        severity: "info",
+        detail: skew === "same" ? `matches this host (${running}, live on ${bridge})` : `(${pair})`,
+    };
+}
 export async function runDoctorChecks(config, opts) {
     const checks = [];
     // Capability groups — the secure-default surface + how to widen it (info only).
@@ -248,14 +373,17 @@ export async function runDoctorChecks(config, opts) {
     // Editor addon install + enable.
     checks.push(...checkAddon(config.projectPath));
     // The four bridges.
-    const severity = opts.requireLive ? "required" : "info";
     // `secretEnv` marks the two bridges that speak OUR protocol, so a TCP connect
     // is not the end of the story for them (see handshakeOk). The LSP and DAP
     // entries have none: those ports belong to Godot, and anything we could send
     // to prove liveness would be us implementing a foreign protocol inside doctor.
+    //
+    // `tier` is what the bridge NEEDS RUNNING, not what it talks to — the one
+    // fact `--require-live` was missing.
     const bridges = [
         {
             name: "editor-bridge",
+            tier: "editor",
             host: config.bridgeHost,
             port: config.bridgePort,
             hint: 'Open the editor with the "Breakpoint MCP" plugin enabled — and if it was already open when you ran `breakpoint-mcp init`, close and reopen the project (Godot reads the enabled-plugin list only at project load).',
@@ -263,6 +391,7 @@ export async function runDoctorChecks(config, opts) {
         },
         {
             name: "runtime-bridge",
+            tier: "runtime",
             host: config.runtimeHost,
             port: config.runtimePort,
             hint: "Launch the project (godot_run_project / dbg_launch) with the plugin enabled — it auto-registers the runtime autoload.",
@@ -270,24 +399,35 @@ export async function runDoctorChecks(config, opts) {
         },
         {
             name: "gdscript-lsp",
+            tier: "editor",
             host: config.lspHost,
             port: config.lspPort,
             hint: "Godot's language server runs while the editor is open (Editor → Editor Settings → Network → Language Server).",
         },
         {
             name: "gdscript-dap",
+            tier: "editor",
             host: config.dapHost,
             port: config.dapPort,
             hint: "Godot's debug adapter runs while the editor is open (Editor → Editor Settings → Network → Debug Adapter).",
         },
     ];
+    // Filled by the handshakes below, read once after them: which bridge reported which
+    // addon version. A map and not a single variable because both the editor and the
+    // runtime plane answer `ping` with one, and they are two different processes that
+    // can legitimately disagree — the editor holds the addon it loaded at project open,
+    // the game holds the one on disk when it launched.
+    const liveAddonVersions = new Map();
     const bridgeChecks = await Promise.all(bridges.map(async (b) => {
+        const severity = severityFor(opts.liveLevel, b.tier);
+        const liveness = true; // every row in this map is one
         const ok = await probeTcp(b.host, b.port, opts.timeoutMs);
         if (!ok) {
             return {
                 name: b.name,
                 status: "fail",
                 severity,
+                liveness,
                 detail: `${b.host}:${b.port} unreachable`,
                 hint: b.hint,
             };
@@ -300,11 +440,14 @@ export async function runDoctorChecks(config, opts) {
         // Both then reported "reachable" here and failed on every real call.
         if (b.secretEnv) {
             const live = await handshakeOk(config, b, opts.timeoutMs);
-            if (!live) {
+            if (live.addonVersion !== null)
+                liveAddonVersions.set(b.name, live.addonVersion);
+            if (!live.ok) {
                 return {
                     name: b.name,
                     status: "fail",
                     severity,
+                    liveness,
                     detail: `${b.host}:${b.port} open, but no Breakpoint bridge answered`,
                     hint: "Something holds that port without speaking the bridge protocol, or the shared secret is stale. Close other Godot instances, or delete res://.godot/breakpoint_mcp.secret and reopen the editor to remint it.",
                 };
@@ -314,10 +457,19 @@ export async function runDoctorChecks(config, opts) {
             name: b.name,
             status: "ok",
             severity,
+            liveness,
             detail: `${b.host}:${b.port} reachable${b.secretEnv ? " · bridge answered" : ""}`,
         };
     }));
     checks.push(...bridgeChecks);
+    // The running half of the pair, one row per bridge that answered.
+    const bundledDir = resolveBundledAddon();
+    const bundledVersion = bundledDir === null ? null : readAddonVersion(bundledDir);
+    for (const [bridge, running] of liveAddonVersions) {
+        const c = addonRunningCheck(bridge, running, bundledVersion);
+        if (c)
+            checks.push(c);
+    }
     // Optional C# tooling.
     if (opts.includeCsharp) {
         checks.push(checkCsharpTool("csharp-lsp", config.csLspCmd));
@@ -326,23 +478,82 @@ export async function runDoctorChecks(config, opts) {
     const ok = checks.every((c) => c.severity !== "required" || c.status !== "fail");
     return { checks, ok };
 }
-function glyph(status) {
-    return status === "ok" ? "✓" : status === "fail" ? "✗" : "–";
+/**
+ * 🔴 `✗` IS RESERVED FOR A CHECK THAT FAILED THE RUN. An informational check
+ * that did not pass gets `!`, because the alternative was the contradiction this
+ * function used to print: four `✗` glyphs, and then `All required checks
+ * passed.` Both halves were true and defensible on their own — the bridges were
+ * genuinely down, and no REQUIRED check had genuinely failed — and a tool whose
+ * whole job is telling a user whether they are okay cannot say those two things
+ * in one breath and leave them to work out which one is the answer.
+ */
+function glyph(c) {
+    if (c.status === "ok")
+        return "✓";
+    if (c.status === "skip")
+        return "–";
+    return c.severity === "required" ? "✗" : "!";
+}
+/**
+ * The last line, which is the only line many readers read. It says what failed
+ * AND what that means for the exit code, because those are two facts and the
+ * summary that named only one of them was the defect.
+ */
+export function summaryLine(report) {
+    const failed = report.checks.filter((c) => c.status === "fail");
+    const noted = failed.filter((c) => c.severity === "info");
+    if (!report.ok)
+        return "Some required checks failed — see the ↳ hints above.";
+    if (noted.length === 0)
+        return "All checks passed.";
+    const names = noted.map((c) => c.name).join(", ");
+    const head = `All required checks passed. ${noted.length} informational check(s) did not — ${names} (marked !, not counted against the exit code).`;
+    const live = noted.filter((c) => c.liveness);
+    const standing = noted.filter((c) => !c.liveness);
+    // Only the liveness rows get the "expected when nothing is running" sentence, and
+    // only the standing rows get "this will not clear on its own". Saying either of
+    // those about the whole set is how the line contradicted the glyphs the first time.
+    const parts = [head];
+    if (live.length) {
+        parts.push(`${live.map((c) => c.name).join(", ")} ${live.length === 1 ? "is" : "are"} expected when the editor ` +
+            `or the game is not running; re-run with --require-live once the project is open in Godot.`);
+    }
+    if (standing.length) {
+        parts.push(`${standing.map((c) => c.name).join(", ")} will NOT clear by starting anything — see the ↳ hint${standing.length === 1 ? "" : "s"} above.`);
+    }
+    return parts.join(" ");
 }
 function printReport(report) {
     const width = Math.max(...report.checks.map((c) => c.name.length));
     const out = ["breakpoint-mcp doctor", ""];
     for (const c of report.checks) {
-        out.push(`  ${glyph(c.status)} ${c.name.padEnd(width)}  ${c.detail}`);
+        out.push(`  ${glyph(c)} ${c.name.padEnd(width)}  ${c.detail}`);
         if (c.status === "fail" && c.hint)
             out.push(`      ↳ ${c.hint}`);
     }
     out.push("");
-    out.push(report.ok
-        ? "All required checks passed."
-        : "Some required checks failed — see the ↳ hints above.");
+    out.push(summaryLine(report));
     process.stdout.write(out.join("\n") + "\n");
 }
+/**
+ * Read `--require-live` in both its forms. Bare (`true`) is `editor`; a value is
+ * taken literally. An unrecognised value is an ERROR, never a silent default —
+ * `--require-live=yes` quietly meaning "editor" would be a flag that agrees with
+ * whatever you typed and asserts something else.
+ */
+export function parseLiveLevel(raw) {
+    if (raw === undefined || raw === false)
+        return "none";
+    if (raw === true)
+        return "editor";
+    const v = raw.trim().toLowerCase();
+    if (LIVE_LEVELS.includes(v) && v !== "none")
+        return v;
+    return {
+        error: `doctor: --require-live=${raw} is not a level. Use --require-live (the editor's three bridges), ` +
+            `--require-live=runtime (the game's), or --require-live=all.`,
+    };
+}
 /** Entry point for `breakpoint-mcp doctor`. Returns the process exit code. */
 export async function runDoctor(argv) {
     const parsed = parseArgs(argv, ["json", "require-live", "include-csharp", "help", "h"], DOCTOR_FLAGS);
@@ -354,10 +565,15 @@ export async function runDoctor(argv) {
         process.env.GODOT_PROJECT = flags.project;
     const timeoutRaw = typeof flags.timeout === "string" ? Number.parseInt(flags.timeout, 10) : NaN;
     const timeoutMs = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 1500;
+    const liveLevel = parseLiveLevel(flags["require-live"]);
+    if (typeof liveLevel !== "string") {
+        process.stderr.write(liveLevel.error + "\n");
+        return 2;
+    }
     const config = loadConfig();
     const report = await runDoctorChecks(config, {
         timeoutMs,
-        requireLive: flags["require-live"] === true,
+        liveLevel,
         includeCsharp: flags["include-csharp"] === true,
     });
     if (flags.json === true) {

package/dist/cli/init.js

@@ -14,15 +14,18 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, preflight } from "./args.js";
 import { INIT_FLAGS, INIT_USAGE } from "./usage.js";
+import { ADDON_REL, ADDON_SKEW_HINT, compareAddonVersions, readAddonVersion, } from "../addon-version.js";
 import { CLIENT_IDS, clientInfo, mergeClientConfig, serverEntry, snippet } from "./clients.js";
 import { DEFAULT_REPO, fetchAddonFromGitHub } from "./github.js";
 import { CAPABILITY_GROUPS, PRIVILEGED_TOOL_COUNT, parsePrivilegedGroups, selectPrivilegedGroups, } from "../capabilities.js";
 /**
  * Resolve the guided trust preset into a validated BREAKPOINT_PRIVILEGED_GROUPS
- * value ("" = the safe default — `code-execution` + `network` off). Accepts either
- * `--trust safe|full` (friendly presets) or `--privileged-groups <list>`
- * (`code-execution`, `network`, `all`, comma-separated). Unknown tokens are dropped
- * with a warning so a typo never silently enables a group.
+ * value ("" = the safe default — every group in `CAPABILITY_GROUPS` off). Accepts
+ * either `--trust safe|full` (friendly presets) or `--privileged-groups <list>`
+ * (any of `CAPABILITY_GROUPS`, or `all`, comma-separated). Unknown tokens are
+ * dropped with a warning so a typo never silently enables a group — which is why
+ * every printed example of this flag is derived from `CAPABILITY_GROUPS` rather
+ * than restated: a restated one named `network` long after it was deleted.
  */
 export function resolvePrivilegedGroups(flags) {
     const trustAlias = { safe: "", none: "", off: "", full: "all", all: "all" };
@@ -40,7 +43,7 @@ export function resolvePrivilegedGroups(flags) {
     const value = [...enabled].sort().join(",");
     return warn ? { value, warn } : { value };
 }
-const PLUGIN_REL = "addons/breakpoint_mcp";
+const PLUGIN_REL = ADDON_REL;
 const PLUGIN_CFG_RES = "res://addons/breakpoint_mcp/plugin.cfg";
 const SERVER_NAME = "godot";
 /**
@@ -136,15 +139,44 @@ export function enablePlugin(projectGodotText) {
 export function installAddon(addonSource, projectPath, opts) {
     const dest = path.join(projectPath, PLUGIN_REL);
     const exists = fs.existsSync(path.join(dest, "plugin.cfg"));
+    const installed = exists ? readAddonVersion(dest) : null;
+    const source = readAddonVersion(addonSource);
+    const skew = exists ? compareAddonVersions(installed, source) : "unknown";
     if (exists && !opts.force)
-        return { action: "skipped", dest };
+        return { action: "skipped", dest, installed, source, skew };
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.cpSync(addonSource, dest, { recursive: true });
-    return { action: exists ? "overwritten" : "installed", dest };
+    return { action: exists ? "overwritten" : "installed", dest, installed, source, skew };
+}
+/**
+ * POSIX-quote one word of a command line this CLI prints for a human to paste.
+ *
+ * 🔴 A GENERATED COMMAND LINE IS AN INPUT YOU WROTE. The JSON snippet beside this
+ * one has been correct since it shipped, and for a reason that has nothing to do
+ * with care: JSON quotes for you. The shell line was assembled by interpolation,
+ * so `~/Godot Projects/My Game` became four words — `claude mcp add` read
+ * `--env GODOT_PROJECT=/Users/x/Godot` and then `Projects/My`, `Game` as stray
+ * positionals, and the server it configured pointed at a directory that does not
+ * exist. Nothing failed loudly; the path was simply truncated at the first space.
+ *
+ * The safe set is `shlex.quote`'s: characters no shell reinterprets, so an
+ * ordinary path stays readable and only a path that needs quoting gets it. The
+ * `'\''` idiom closes the quote, escapes a literal apostrophe, and reopens —
+ * correct in every POSIX shell, and the only way to carry a `'` inside `'…'`.
+ */
+export function shellQuote(word) {
+    if (word.length > 0 && /^[A-Za-z0-9_@%+=:,./-]+$/.test(word))
+        return word;
+    return `'${word.replace(/'/g, `'\\''`)}'`;
 }
 function claudeCodeCommand(projectPath, privilegedGroups) {
-    const groups = privilegedGroups ? ` --env BREAKPOINT_PRIVILEGED_GROUPS=${privilegedGroups}` : "";
-    return `claude mcp add godot --env GODOT_PROJECT=${projectPath}${groups} -- npx -y breakpoint-mcp`;
+    // Each `--env` value is ONE word to the shell, so the whole `KEY=value` token is
+    // quoted rather than the path alone: `GODOT_PROJECT='/a b'` would reach the
+    // process as the literal string it looks like, quotes and all.
+    const groups = privilegedGroups
+        ? ` --env ${shellQuote(`BREAKPOINT_PRIVILEGED_GROUPS=${privilegedGroups}`)}`
+        : "";
+    return `claude mcp add godot --env ${shellQuote(`GODOT_PROJECT=${projectPath}`)}${groups} -- npx -y breakpoint-mcp`;
 }
 /** Entry point for `breakpoint-mcp init`. Returns the process exit code. */
 export async function runInit(argv, deps = {}) {
@@ -225,7 +257,18 @@ export async function runInit(argv, deps = {}) {
         const r = installAddon(addonSource, projectPath, { force });
         if (tmpFetchDir)
             fs.rmSync(tmpFetchDir, { recursive: true, force: true });
-        say(`  addon: ${r.action} → ${PLUGIN_REL}/`);
+        const versionNote = r.action === "skipped" ? ` (kept ${r.installed ?? "?"})` : r.source ? ` (${r.source})` : "";
+        say(`  addon: ${r.action} → ${PLUGIN_REL}/${versionNote}`);
+        // 🔴 THE LINE THAT MAKES THE SKIP HONEST. A skip over an addon that is already
+        // current is correct and silent; a skip over an OLDER one is the moment the skew
+        // becomes permanent, and until now the two read identically. It goes to stderr
+        // because it is not part of the install transcript a user pastes — it is the thing
+        // that went wrong inside a command that exits 0.
+        if (r.action === "skipped" && r.skew === "older") {
+            process.stderr.write(`init: the addon already in this project is OLDER than the one this host ships ` +
+                `(${r.installed ?? "?"} vs ${r.source ?? "?"}), and it was left in place.\n` +
+                `  ${ADDON_SKEW_HINT}\n`);
+        }
     }
     // 2. Enable it in project.godot.
     const before = fs.readFileSync(projGodot, "utf8");
@@ -288,9 +331,18 @@ export async function runInit(argv, deps = {}) {
     }
     else {
         say("Higher-trust tool groups are OFF by default (the secure default). The assistant loads the");
-        say(`everyday authoring/debug surface and drops the ${PRIVILEGED_TOOL_COUNT} code-execution + network tools (e.g.`);
-        say("godot_run_headless_script, the *_call_method / dbg_evaluate tools, asset-gen, backend_*).");
-        say("Enable them by re-running with `--trust full` (or `--privileged-groups code-execution,network`),");
+        // 🔴 THE GROUP NAME AND THE EXAMPLES ARE BOTH CORRECTIONS, NOT POLISH.
+        // This said "code-execution + network tools" and named `backend_*` among
+        // them: `network` has been deleted from capabilities.ts, and
+        // backend_detect / backend_configure are DELIBERATELY unprivileged — so the
+        // first thing a new user reads named a group that does not exist and two
+        // tools that are not dropped. The suggested flag below carried the same
+        // dead token, which `init`'s own resolver answers with
+        // `ignoring unknown trust group(s): network`: the tool warned about the
+        // command the tool told them to run.
+        say(`everyday authoring/debug surface and drops the ${PRIVILEGED_TOOL_COUNT} ${CAPABILITY_GROUPS.join(" + ")} tools (e.g.`);
+        say("godot_run_headless_script, the *_call_method / dbg_evaluate tools, asset-gen).");
+        say(`Enable them by re-running with \`--trust full\` (or \`--privileged-groups ${CAPABILITY_GROUPS.join(",")}\`),`);
         say("or set BREAKPOINT_PRIVILEGED_GROUPS in the server env. The `godot://capabilities` resource and");
         say("`breakpoint-mcp doctor` list exactly what each group gates.");
     }

package/dist/cli/usage.js

@@ -51,7 +51,11 @@ export const DOCTOR_USAGE = [
     "",
     "doctor options:",
     "  --project <dir>     Project to check (default: $GODOT_PROJECT or the current directory).",
-    "  --require-live      Also require the editor/runtime/LSP/DAP bridges to be reachable.",
+    "  --require-live[=L]  Require bridges to be reachable rather than just report them.",
+    "                      Bare, it means the three OPENING THE EDITOR brings up: the editor",
+    "                      bridge, the GDScript LSP and the DAP. L is editor | runtime | all —",
+    "                      the runtime bridge lives inside the running game, so it is required",
+    "                      only by =runtime and =all.",
     "  --include-csharp    Also probe OmniSharp / netcoredbg on PATH (the C# planes).",
     "  --timeout <ms>      Per-bridge connect timeout (default 1500).",
     "  --json              Emit the report as JSON.",

package/dist/index.js

@@ -16,10 +16,11 @@ import { applyWireDefaults } from "./wire-defaults.js";
 import { applyOutputSchemas } from "./schemas.js";
 import { applyAnnotations } from "./annotations.js";
 import { applyTimeoutCaveat } from "./timeout-caveat.js";
-import { applyCapabilities, droppedTools, registerCapabilitiesResource, selectPrivilegedGroups, } from "./capabilities.js";
+import { applyCapabilities, applyDroppedToolRefusal, droppedTools, registerCapabilitiesResource, selectPrivilegedGroups, } from "./capabilities.js";
 import { taskStore, TASK_CAPABILITIES } from "./tasks.js";
 import { RESOURCE_CAPABILITIES, registerResourceSubscriptions } from "./subscriptions.js";
 import { pauseLatch, installPauseSignalHandlers } from "./pause.js";
+import { applyResultCost } from "./result-cost.js";
 import { log } from "./logger.js";
 async function main() {
     const config = loadConfig();
@@ -43,7 +44,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.74.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.76.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // 208 §7.1 — delete from the wire what the protocol already says: the SDK's
     // draft-07 `$schema` inside every input/output schema (MCP's default dialect is
     // 2020-12, and declaring another is an explicit switch a peer may reject), and
@@ -129,6 +130,17 @@ async function main() {
     // read godot://capabilities to see what exists-but-is-disabled and how to
     // enable it. Registered directly (not via the `resources` toolset).
     registerCapabilitiesResource(server, privilegedGroups);
+    // …and the other half of "never a silent gap", which the resource alone could
+    // not deliver. A dropped tool is not registered, so calling it by name reaches
+    // the SDK's `Tool <name> not found` — grammatical, accurate about the lookup,
+    // and wrong about the world. Must run AFTER every ts.run() above: the CallTool
+    // dispatcher does not exist until the first registerTool, and this wraps it.
+    // Advertises nothing new — tools/list is untouched at 279.
+    applyDroppedToolRefusal(server, privilegedGroups);
+    // 257 — the result-cost meter, off unless BREAKPOINT_RESULT_COST names a file.
+    // AFTER the refusal wrapper so a dropped tool's refusal is measured as the result
+    // it actually is: a client pays for a refusal exactly as it pays for an answer.
+    applyResultCost(server);
     if (config.privilegedGroups) {
         const on = [...privilegedGroups].sort().join(", ") || "(none)";
         log(`privileged groups enabled: ${on}; dropped ${droppedTools(privilegedGroups).length} tool(s) from the surface`);
@@ -181,23 +193,55 @@ function printUsage() {
 //   * An unrecognized token is a TYPO, and the only useful thing to do with one
 //     is name it. Falling through spends the user's next twenty minutes on the
 //     wrong question.
+// 🔴 EXIT ONLY AFTER stdout HAS DRAINED, AND IT IS THE PIPE THAT MAKES THIS A
+// DEFECT RATHER THAN A STYLE NOTE. `process.stdout` is SYNCHRONOUS to a file
+// and to a TTY and ASYNCHRONOUS to a pipe. `process.exit()` does not flush what
+// is still queued, so every subcommand below was correct when a human watched
+// it, correct when a shell redirected it to a file, and lost everything past
+// the first 64 KiB the moment anybody piped it.
+//
+// Measured on 1.75.0 and on the published 1.74.1 — same command, same build:
+//
+//   breakpoint-mcp tools --json > file    202,960 bytes · valid JSON
+//   breakpoint-mcp tools --json | cat      65,536 bytes · unterminated string
+//
+// 65,536 is one pipe buffer, and that is the whole tell: nothing failed and no
+// error was raised, the process simply stopped existing with the rest of the
+// answer still inside it. The flag's own usage text is `so releases can be
+// diffed`, and diffing is a pipe.
+//
+// 🔴 THE POPULATION IS A PREDICATE, NOT A LIST OF COMMANDS (257). `tools --json`
+// is the only subcommand that exceeds a buffer TODAY — `doctor --json` measures
+// 2,138 bytes and `init --dry-run` 1,186 — so a fix inside `runTools` would be
+// correct and would leave the next command to cross 64 KiB to rediscover this
+// from a user's bug report. The drain is attached at the dispatch every
+// subcommand passes through instead (254).
+//
+// The empty write IS the flush: its callback runs once everything already
+// queued on the stream has been handed to the OS.
+async function exitAfterFlush(code) {
+    await new Promise((resolve) => {
+        process.stdout.write("", () => resolve());
+    });
+    process.exit(code);
+}
 void (async () => {
     const sub = process.argv[2];
     if (sub === "doctor") {
         const { runDoctor } = await import("./cli/doctor.js");
-        process.exit(await runDoctor(process.argv.slice(3)));
+        await exitAfterFlush(await runDoctor(process.argv.slice(3)));
     }
     if (sub === "tools") {
         const { runTools } = await import("./cli/tools.js");
-        process.exit(await runTools(process.argv.slice(3)));
+        await exitAfterFlush(await runTools(process.argv.slice(3)));
     }
     if (sub === "init") {
         const { runInit } = await import("./cli/init.js");
-        process.exit(await runInit(process.argv.slice(3)));
+        await exitAfterFlush(await runInit(process.argv.slice(3)));
     }
     if (sub === "help" || sub === "--help" || sub === "-h") {
         printUsage();
-        process.exit(0);
+        await exitAfterFlush(0);
     }
     if (sub === "version" || sub === "--version" || sub === "-v" || sub === "-V") {
         // Bare, so `breakpoint-mcp --version` is usable in a shell substitution.
@@ -205,13 +249,13 @@ void (async () => {
         // twenty releases that announced 0.2.0 to every LSP server they met.
         const { packageVersion } = await import("./version.js");
         process.stdout.write(`${packageVersion()}\n`);
-        process.exit(0);
+        await exitAfterFlush(0);
     }
     if (sub !== undefined) {
         process.stderr.write(`breakpoint-mcp: unknown argument '${sub}'.\n` +
             "  Run `breakpoint-mcp --help` for the subcommands and their options.\n" +
             "  To start the MCP server, run it with no arguments — that is how MCP clients launch it.\n");
-        process.exit(2);
+        await exitAfterFlush(2);
     }
     await main();
 })().catch((err) => {