breakpoint-mcp 1.74.0 → 1.75.0

package/dist/cli/usage.js

@@ -0,0 +1,106 @@
+/**
+ * The CLI's help text, in ONE place, split by subcommand.
+ *
+ * It lived in `index.ts`'s `printUsage` as a single flat array, which was fine
+ * while `--help` was the only thing that printed it. It stopped being fine the
+ * moment `breakpoint-mcp init --help` had to print the init section and nothing
+ * else: the alternative to this module is the same twelve lines written twice,
+ * and a help text that disagrees with itself is worse than one that is merely
+ * long. `index.ts` composes the whole document from these parts, so a flag
+ * documented for a subcommand is documented in the top-level help by
+ * construction.
+ *
+ * 🔴 THE ROSTERS BELOW ARE NOT DOCUMENTATION — THEY ARE THE PARSER'S INPUT.
+ * `parseArgs` takes them as `knownFlags` and reports anything else as unknown,
+ * so a flag added to a subcommand and not added here is refused at the command
+ * line rather than silently ignored. That is the whole point of keeping the
+ * prose and the roster in the same file: the pressure to update both is the
+ * same edit.
+ */
+export const HEADLINE = "breakpoint-mcp — MCP server exposing Godot to AI coding assistants.";
+export const SYNOPSIS = [
+    "Usage:",
+    "  breakpoint-mcp             Start the MCP server on stdio (default; how MCP clients launch it).",
+    "  breakpoint-mcp init        Install + enable the editor addon in a project and wire the MCP client.",
+    "  breakpoint-mcp doctor      Check the Godot binary, the editor addon, and the four bridges.",
+    "  breakpoint-mcp tools       Export the tool surface + risk annotations (for catalogs / reviews).",
+    "  breakpoint-mcp --help      Show this help.",
+    "  breakpoint-mcp --version   Print the installed version and exit.",
+    "",
+    "Every subcommand also accepts --help.",
+];
+export const INIT_USAGE = [
+    "Usage: breakpoint-mcp init [options]",
+    "",
+    "Install + enable the editor addon in a Godot project and wire the MCP client.",
+    "",
+    "init options:",
+    "  --project <dir>     Target Godot project (default: $GODOT_PROJECT or the current directory).",
+    "  --client <id>       Write the MCP config for a client: claude-code | claude-desktop | cursor | windsurf | vscode.",
+    "  --force             Overwrite an addon that is already installed.",
+    "  --dry-run           Print what would change without writing anything.",
+    "  --from-github [ref] Fetch the editor addon from GitHub at [ref] (default: this package's version tag) instead of the bundled copy.",
+    "  --repo <owner/repo> With --from-github, the source repo (default: jlivingston-Cipher/godot-breakpoint-mcp).",
+    "  --trust <level>     secure | full. `full` enables every higher-trust group (default: secure).",
+    "  --privileged-groups <a,b>  Enable named higher-trust groups instead of all of them.",
+];
+export const DOCTOR_USAGE = [
+    "Usage: breakpoint-mcp doctor [options]",
+    "",
+    "Check the Godot binary, the editor addon, and the four bridges.",
+    "",
+    "doctor options:",
+    "  --project <dir>     Project to check (default: $GODOT_PROJECT or the current directory).",
+    "  --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.",
+];
+export const TOOLS_USAGE = [
+    "Usage: breakpoint-mcp tools [options]",
+    "",
+    "Export the tool surface + risk annotations (for catalogs / reviews).",
+    "",
+    "tools options:",
+    "  --surface <which>   full | secure-default (default: secure-default, what an untouched install advertises).",
+    "  --json              Emit the surface as JSON — stable and timestamp-free, so releases can be diffed.",
+];
+/** Every flag `init` accepts. Booleans are declared at the call site. */
+export const INIT_FLAGS = [
+    "project",
+    "client",
+    "from-github",
+    "repo",
+    "trust",
+    "privileged-groups",
+];
+/** Every flag `doctor` accepts. */
+export const DOCTOR_FLAGS = ["project", "timeout"];
+/** Every flag `tools` accepts. */
+export const TOOLS_FLAGS = ["surface"];
+/** The whole document, composed — what `breakpoint-mcp --help` prints. */
+export function fullUsage() {
+    // Each subcommand block contributes only its own `<name> options:` tail; the
+    // per-subcommand synopsis above it would read as four competing headlines in
+    // a single document.
+    const tail = (block) => block.slice(block.findIndex((l) => l.endsWith("options:")));
+    return [
+        HEADLINE,
+        "",
+        ...SYNOPSIS,
+        "",
+        ...tail(INIT_USAGE),
+        "",
+        ...tail(DOCTOR_USAGE),
+        "",
+        ...tail(TOOLS_USAGE),
+        "",
+        "All runtime configuration is via environment variables; see the README.",
+        "",
+    ];
+}
+//# sourceMappingURL=usage.js.map

package/dist/index.js

@@ -9,16 +9,18 @@ import { CsLspClient } from "./cslsp.js";
 import { CsDapClient } from "./csdap.js";
 import { StdioChannel } from "./stdio.js";
 import { DapClient } from "./dap.js";
+import { fullUsage } from "./cli/usage.js";
 import { buildToolsets } from "./toolsets.js";
 import { registerRecipes } from "./recipes.js";
 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();
@@ -42,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.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.75.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
@@ -128,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`);
@@ -160,61 +173,89 @@ async function main() {
     process.on("SIGTERM", shutdown);
 }
 function printUsage() {
-    process.stdout.write([
-        "breakpoint-mcp — MCP server exposing Godot to AI coding assistants.",
-        "",
-        "Usage:",
-        "  breakpoint-mcp             Start the MCP server on stdio (default; how MCP clients launch it).",
-        "  breakpoint-mcp init        Install + enable the editor addon in a project and wire the MCP client.",
-        "  breakpoint-mcp doctor      Check the Godot binary, the editor addon, and the four bridges.",
-        "  breakpoint-mcp tools       Export the tool surface + risk annotations (for catalogs / reviews).",
-        "  breakpoint-mcp --help      Show this help.",
-        "",
-        "init options:",
-        "  --project <dir>     Target Godot project (default: $GODOT_PROJECT or the current directory).",
-        "  --client <id>       Write the MCP config for a client: claude-code | claude-desktop | cursor | windsurf | vscode.",
-        "  --force             Overwrite an addon that is already installed.",
-        "  --dry-run           Print what would change without writing anything.",
-        "  --from-github [ref] Fetch the editor addon from GitHub at [ref] (default: this package's version tag) instead of the bundled copy.",
-        "  --repo <owner/repo> With --from-github, the source repo (default: jlivingston-Cipher/godot-breakpoint-mcp).",
-        "  --trust <level>     secure | full. `full` enables every higher-trust group (default: secure).",
-        "  --privileged-groups <a,b>  Enable named higher-trust groups instead of all of them.",
-        "",
-        "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.",
-        "  --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.",
-        "",
-        "tools options:",
-        "  --surface <which>   full | secure-default (default: secure-default, what an untouched install advertises).",
-        "  --json              Emit the surface as JSON — stable and timestamp-free, so releases can be diffed.",
-        "",
-        "All runtime configuration is via environment variables; see the README.",
-        "",
-    ].join("\n"));
+    process.stdout.write(fullUsage().join("\n"));
+}
+// Subcommand dispatch. NO arguments at all is how every MCP client launches
+// this — every invocation in the README, the user guide and `init`'s own
+// emitted config passes the binary an empty argv — so that case, and only that
+// case, starts the stdio server. The launch contract is unchanged.
+//
+// 🔴 WHAT CHANGED IS THE FALL-THROUGH, WHICH USED TO SWALLOW EVERYTHING ELSE.
+// `breakpoint-mcp --version` started a server. So did `-v`, `version`, and any
+// mistyped flag: the process printed one ready line and then sat on a stdin
+// nobody was going to speak MCP into, which in a terminal is a hang. The two
+// halves of that are separate defects and both are user-facing:
+//
+//   * There was NO WAY TO ASK THIS BINARY ITS VERSION. `--version` is the most
+//     universal convention a CLI has, and the first thing anyone filing a bug
+//     report is asked for. A project with 0 issues against ~3,700 downloads
+//     cannot afford a version query that hangs the terminal instead.
+//   * 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);
 }
-// Subcommand dispatch. Anything that isn't a recognized subcommand — including
-// no arguments at all, which is how every MCP client launches this — falls
-// through to the stdio server, so the server's launch contract is unchanged.
 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.
+        // Read from package.json rather than written here: see version.ts on the
+        // twenty releases that announced 0.2.0 to every LSP server they met.
+        const { packageVersion } = await import("./version.js");
+        process.stdout.write(`${packageVersion()}\n`);
+        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");
+        await exitAfterFlush(2);
     }
     await main();
 })().catch((err) => {

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