breakpoint-mcp 1.74.0 → 1.75.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.
  */
@@ -23,10 +35,28 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { loadConfig } from "../config.js";
 import { CAPABILITY_GROUPS, droppedTools, selectPrivilegedGroups } from "../capabilities.js";
-import { parseArgs } from "./args.js";
+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) {
@@ -89,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) {
@@ -114,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)
         ? {
@@ -197,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") ||
@@ -224,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).
@@ -247,21 +373,25 @@ 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.',
+            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).',
             secretEnv: ["BREAKPOINT_BRIDGE_SECRET"],
         },
         {
             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.",
@@ -269,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,
             };
@@ -299,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.",
                 };
@@ -313,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));
@@ -325,34 +478,102 @@ 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 { flags } = parseArgs(argv, ["json", "require-live", "include-csharp"]);
+    const parsed = parseArgs(argv, ["json", "require-live", "include-csharp", "help", "h"], DOCTOR_FLAGS);
+    const pre = preflight(parsed, "doctor", DOCTOR_USAGE);
+    if (pre !== null)
+        return pre;
+    const { flags } = parsed;
     if (typeof flags.project === "string")
         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

@@ -12,16 +12,20 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseArgs } from "./args.js";
+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" };
@@ -39,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";
 /**
@@ -135,19 +139,52 @@ 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 = {}) {
-    const { flags } = parseArgs(argv, ["force", "dry-run"]);
+    const parsed = parseArgs(argv, ["force", "dry-run", "help", "h"], INIT_FLAGS);
+    const pre = preflight(parsed, "init", INIT_USAGE);
+    if (pre !== null)
+        return pre;
+    const { flags } = parsed;
     const projectPath = typeof flags.project === "string"
         ? path.resolve(flags.project)
         : process.env.GODOT_PROJECT ?? process.cwd();
@@ -220,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");
@@ -283,16 +331,39 @@ 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.");
     }
     if (privilegedWarn)
         say(`  note: ${privilegedWarn}`);
     say("");
-    say("Next: open the project in Godot, then run `breakpoint-mcp doctor --require-live` to verify.");
+    // 🔴 THE REOPEN TRAP. Godot reads project.godot's [editor_plugins] at project load and
+    // does not reload it, so an editor that was already running when we wrote the section
+    // keeps the plugin DISABLED — the bridge never starts and every editor-plane tool is
+    // dark, with nothing on screen saying why. The line is conditioned on `en.changed`
+    // because a project whose plugin was already enabled has nothing to reopen for, and a
+    // warning printed on every run is a warning nobody reads.
+    if (!dryRun && en.changed) {
+        say("Next: open the project in Godot — and if it is ALREADY OPEN, close and reopen it.");
+        say("  Godot reads project.godot's [editor_plugins] at project load and does not reload");
+        say("  it, so an editor that was already running keeps the plugin disabled.");
+        say("Then run `breakpoint-mcp doctor --require-live` to verify.");
+    }
+    else {
+        say("Next: open the project in Godot, then run `breakpoint-mcp doctor --require-live` to verify.");
+    }
     process.stdout.write(out.join("\n") + "\n");
     return 0;
 }

package/dist/cli/tools.js

@@ -22,7 +22,8 @@
  * `--surface` picks which one populates `tools[]`; both counts are always in the
  * header so a consumer cannot report one as the other by accident.
  */
-import { parseArgs } from "./args.js";
+import { parseArgs, preflight } from "./args.js";
+import { TOOLS_FLAGS, TOOLS_USAGE } from "./usage.js";
 import { buildToolsets } from "../toolsets.js";
 import { applyOutputSchemas } from "../schemas.js";
 import { applyAnnotations, annotationsFor } from "../annotations.js";
@@ -148,20 +149,16 @@ function renderText(report) {
     return lines.join("\n");
 }
 export async function runTools(argv) {
-    const { flags } = parseArgs(argv, ["json", "help", "h"]);
-    if (flags.help || flags.h) {
-        process.stdout.write([
-            "breakpoint-mcp tools — export the tool surface (name, risk annotations, capability group).",
-            "",
-            "  --json                Emit JSON (stable, no timestamp — safe to diff between releases).",
-            "  --surface <which>     full | secure-default   (default: secure-default, what an",
-            "                        untouched install actually advertises).",
-            "",
-            "Reads no Godot install and starts no server — the registry is built statically.",
-            "",
-        ].join("\n"));
-        return 0;
-    }
+    const parsed = parseArgs(argv, ["json", "help", "h"], TOOLS_FLAGS);
+    const pre = preflight(parsed, "tools", [
+        ...TOOLS_USAGE,
+        "",
+        "Reads no Godot install and starts no server — the registry is built statically.",
+        "",
+    ]);
+    if (pre !== null)
+        return pre;
+    const { flags } = parsed;
     const raw = typeof flags.surface === "string" ? flags.surface : "secure-default";
     if (raw !== "full" && raw !== "secure-default") {
         process.stderr.write(`unknown --surface "${raw}" (expected: full | secure-default)\n`);