breakpoint-mcp 1.23.0 → 1.25.0

package/dist/config.js

@@ -1,5 +1,30 @@
 import { pathToFileURL } from "node:url";
 import { parsePrivilegedGroups } from "./capabilities.js";
+/**
+ * A TCP port from the environment, falling back to `fallback` when the variable
+ * is absent, empty, non-numeric or out of range.
+ *
+ * `?? "9081"` alone does not cover this: an env var set to `""` or `"nope"`
+ * reaches `Number.parseInt` and yields `NaN`, which then propagates into every
+ * dial and bind as a port nothing can use. The addon has guarded this since it
+ * shipped — `runtime_bridge.gd:75` requires `is_valid_int()` before overriding
+ * and otherwise keeps the default — and the host simply never matched it. The
+ * mismatch was harmless while a bad port merely failed to connect; it stopped
+ * being harmless once `godot_run_managed` began *refusing* on an unbindable
+ * port, which would have read as "127.0.0.1:NaN is already bound".
+ */
+function port(raw, fallback) {
+    // Deliberately NOT Number.parseInt on its own: it stops at the first
+    // non-digit, so "80a80" parses to 80. The host would then dial port 80 while
+    // the addon — whose `is_valid_int()` rejects the whole string — bound the
+    // default, which is precisely the host/addon disagreement this guard exists
+    // to prevent. The pattern mirrors GDScript's `is_valid_int()`.
+    const t = (raw ?? "").trim();
+    if (!/^[+-]?\d+$/.test(t))
+        return fallback;
+    const n = Number(t);
+    return Number.isInteger(n) && n >= 0 && n <= 65535 ? n : fallback;
+}
 export function loadConfig() {
     const projectPath = process.env.GODOT_PROJECT ?? process.cwd();
     // The C# project defaults to the main project, but is usually pointed at a
@@ -10,10 +35,10 @@ export function loadConfig() {
         projectPath,
         projectUri: pathToFileURL(projectPath).href,
         bridgeHost: process.env.BREAKPOINT_BRIDGE_HOST ?? "127.0.0.1",
-        bridgePort: Number.parseInt(process.env.BREAKPOINT_BRIDGE_PORT ?? "9080", 10),
+        bridgePort: port(process.env.BREAKPOINT_BRIDGE_PORT, 9080),
         bridgeTimeoutMs: Number.parseInt(process.env.BREAKPOINT_BRIDGE_TIMEOUT_MS ?? "15000", 10),
         lspHost: process.env.GODOT_LSP_HOST ?? "127.0.0.1",
-        lspPort: Number.parseInt(process.env.GODOT_LSP_PORT ?? "6005", 10),
+        lspPort: port(process.env.GODOT_LSP_PORT, 6005),
         lspTimeoutMs: Number.parseInt(process.env.GODOT_LSP_TIMEOUT_MS ?? "15000", 10),
         csLspCmd: process.env.GODOT_CSLSP_CMD ?? "OmniSharp",
         csLspArgs: (process.env.GODOT_CSLSP_ARGS ?? "-lsp").split(/\s+/).filter(Boolean),
@@ -21,7 +46,7 @@ export function loadConfig() {
         csLspProjectUri: pathToFileURL(csLspProjectPath).href,
         csLspTimeoutMs: Number.parseInt(process.env.GODOT_CSLSP_TIMEOUT_MS ?? "30000", 10),
         dapHost: process.env.GODOT_DAP_HOST ?? "127.0.0.1",
-        dapPort: Number.parseInt(process.env.GODOT_DAP_PORT ?? "6006", 10),
+        dapPort: port(process.env.GODOT_DAP_PORT, 6006),
         dapTimeoutMs: Number.parseInt(process.env.GODOT_DAP_TIMEOUT_MS ?? "20000", 10),
         dapSetVarTimeoutMs: Number.parseInt(process.env.GODOT_DAP_SETVAR_TIMEOUT_MS ?? "8000", 10),
         dapEvaluateTimeoutMs: Number.parseInt(process.env.GODOT_DAP_EVALUATE_TIMEOUT_MS ?? "8000", 10),
@@ -36,7 +61,7 @@ export function loadConfig() {
         csDapSetVarTimeoutMs: Number.parseInt(process.env.GODOT_CSDAP_SETVAR_TIMEOUT_MS ?? "8000", 10),
         csDapEvaluateTimeoutMs: Number.parseInt(process.env.GODOT_CSDAP_EVALUATE_TIMEOUT_MS ?? "8000", 10),
         runtimeHost: process.env.BREAKPOINT_RUNTIME_HOST ?? "127.0.0.1",
-        runtimePort: Number.parseInt(process.env.BREAKPOINT_RUNTIME_PORT ?? "9081", 10),
+        runtimePort: port(process.env.BREAKPOINT_RUNTIME_PORT, 9081),
         runtimeTimeoutMs: Number.parseInt(process.env.BREAKPOINT_RUNTIME_TIMEOUT_MS ?? "15000", 10),
         // Group J: asset generation is OFF by default (backend "none" → tools degrade).
         assetGenBackend: process.env.BREAKPOINT_ASSETGEN_BACKEND ?? "none",

package/dist/index.js

@@ -36,7 +36,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.23.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.25.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // any register*Tools call — it wraps server.registerTool.
     applyOutputSchemas(server);

package/dist/peers.js

@@ -1,8 +1,8 @@
-import net from "node:net";
 import { BridgeClient, BridgeError } from "./bridge.js";
 import { ProcessRegistry } from "./tools/processes.js";
 import { ensureProjectSecret, readProjectSecret } from "./secret.js";
 import { log } from "./logger.js";
+import { portFree } from "./ports.js";
 /**
  * Hard ceiling on simultaneously live peers.
  *
@@ -15,20 +15,6 @@ import { log } from "./logger.js";
 export const MAX_PEERS = 4;
 /** How far above the default runtime port the allocator will scan. */
 const PORT_SCAN_SPAN = 200;
-/** Is `port` bindable on `host` right now? */
-function portFree(host, port) {
-    return new Promise((resolve) => {
-        const srv = net.createServer();
-        srv.once("error", () => resolve(false));
-        srv.once("listening", () => srv.close(() => resolve(true)));
-        try {
-            srv.listen(port, host);
-        }
-        catch {
-            resolve(false);
-        }
-    });
-}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class PeerRegistry {
     cfg;
@@ -83,12 +69,13 @@ export class PeerRegistry {
      * runtime port so a peer never collides with a developer's already-running
      * game. Ports held by live peers are skipped even if the probe would pass.
      *
-     * Probe-then-release is a TOCTOU window by construction: another process could
-     * take the port between the probe and the child's bind. Allocation is
+     * The probe is TOCTOU by construction (see `ports.ts`), but allocation is
      * 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.
+     * 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.
      */
     async allocatePorts(count) {
         const taken = new Set([this.cfg.runtimePort, ...this.live().map((p) => p.port)]);

package/dist/ports.js

@@ -0,0 +1,102 @@
+import net from "node:net";
+/**
+ * Loopback port probing, shared by the two callers that must not collide.
+ *
+ * It lives in its own module because `peers.ts` imports `ProcessRegistry` from
+ * `tools/processes.ts`, so `processes.ts` importing the probe back out of
+ * `peers.ts` would close an import cycle. Nothing here imports anything local.
+ */
+/**
+ * Is `port` bindable on `host` right now?
+ *
+ * Probe-then-release is a TOCTOU window by construction: another process could
+ * take the port between this answer and whoever acts on it. Every caller here
+ * treats a `true` as "nothing is holding it as of now", never as a lease.
+ *
+ * SO_REUSEADDR (which Node sets by default) does NOT let two live listeners
+ * share an address on Linux or macOS — that needs SO_REUSEPORT, which Node does
+ * not set — so a bound port answers `false` rather than being silently joinable.
+ */
+export function portFree(host, port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once("error", () => resolve(false));
+        srv.once("listening", () => srv.close(() => resolve(true)));
+        try {
+            srv.listen(port, host);
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/**
+ * The refusal text shared by every tool that starts a game.
+ *
+ * All of them launch a project whose runtime autoload binds
+ * `BREAKPOINT_RUNTIME_PORT` (`runtime_bridge.gd:74` reads it, `:79` binds it).
+ * When that port is already held, the autoload's `listen()` returns non-OK, it
+ * `push_error`s, and **the game keeps running without a bridge** — while the
+ * host's runtime client, which dials the same fixed port, connects to whichever
+ * process got there first. Every subsequent `runtime_*` call then answers
+ * confidently about the WRONG process, and `ping` carries no pid or boot nonce
+ * that could tell them apart.
+ *
+ * That is why this refuses rather than warns: a determinism feature returning a
+ * correct-looking answer from the wrong game is worse than one that will not
+ * start.
+ *
+ * Note what is deliberately NOT offered as a remedy: stopping peers. A peer can
+ * never hold this port — `allocatePorts` seeds its `taken` set with
+ * `cfg.runtimePort` and scans from `runtimePort + 1`, so whatever holds it is
+ * something else. `runtime_spawn_peers` is named below as the way to drive
+ * several games at once, which is true; `runtime_peer_stop` as a way to free
+ * THIS port would not be, and a remedy that cannot work is worse than one fewer
+ * suggestion.
+ *
+ * The `debugger` variant differs in one way that matters. A DAP session is
+ * addressed by SESSION, not by port, so `dbg_*` keeps working perfectly against
+ * a second game even with the port held — only `runtime_*` is corrupted. The
+ * override is therefore a legitimate everyday choice on that plane rather than a
+ * last resort, and the text says so instead of over-warning. Over-warning is how
+ * a check earns the reputation that gets it disabled.
+ *
+ * What NEITHER variant may do is claim to know WHAT is holding the port. All the
+ * probe learns is that something is. The holder may be a `godot_run_managed`
+ * child (`godot_stop` clears it), a game already under the debugger (`dbg_attach`
+ * reaches it), or a window the developer opened themselves (only they can close
+ * it) — and the two planes contend for the SAME port, so a debugger refusal is
+ * often about a run-plane holder and vice versa. An earlier draft of the
+ * debugger text asserted "a debugger-launched game is owned by the editor, so no
+ * tool here can stop it" and withheld `godot_stop` on that basis; it was wrong
+ * whenever the holder was a managed child, which is the commonest case of all.
+ * Both variants now list every remedy with the condition under which it applies,
+ * and assert nothing about which one is live.
+ */
+export function portConflictMessage(host, port, launcher = "run") {
+    const why = `${host}:${port} is already bound, so a game started now could not host the runtime bridge. ` +
+        `Its autoload would fail to listen and keep running anyway, and every runtime_* call would ` +
+        `silently address the process that already holds the port instead of the one you just started. `;
+    if (launcher === "debugger") {
+        return (why +
+            `Deal with whatever is already holding it — which remedy applies depends on what it is: ` +
+            `godot_stop if godot_run_managed started it, dbg_attach / cs_dbg_attach to debug the running ` +
+            `game instead of launching a second one (that works only if it is already under the ` +
+            `debugger — a plain godot_run_project or godot_run_managed game is not), or quit it in the ` +
+            `game window or the editor. You can also point this server at a free port with ` +
+            `BREAKPOINT_RUNTIME_PORT. Pass allow_port_conflict:true to launch anyway: breakpoints, ` +
+            `stepping and variable inspection will all work normally, because a DAP session is addressed ` +
+            `by session rather than by port — but every runtime_* call would go to the process holding ` +
+            `the port, not to the game you just launched. To drive more than one game at once, use ` +
+            `runtime_spawn_peers, which allocates a distinct port per peer.`);
+    }
+    return (why +
+        `Stop the running game first — godot_stop if godot_run_managed started it, otherwise quit it in ` +
+        `the game window or end the debug session that launched it (a detached godot_run_project game is ` +
+        `not stoppable by any tool) — or point this server at a free port with ` +
+        `BREAKPOINT_RUNTIME_PORT. Pass allow_port_conflict:true to start it anyway — reasonable only if ` +
+        `you want the process for its console output or its side effects and will not use any runtime_* ` +
+        `tool against it. To drive more than one game at once, use runtime_spawn_peers, which allocates ` +
+        `a distinct port per peer.`);
+}
+//# sourceMappingURL=ports.js.map

package/dist/recipes.js

@@ -114,8 +114,8 @@ export function registerRecipes(server) {
         return recipe("Golden-image regression check for a scene.", [
             `Goal: lock a scene's look to a golden image at ${ref} and catch visual drift.`,
             "",
-            `1. Establish the golden (first run only): godot_run_project, drive the game to the state under test (runtime_inject_input / runtime_call_method), then runtime_screenshot and save the frame to ${ref}. Commit it (vcs_add) so it's the reference.`,
-            `2. Regression run (every time after): godot_run_project, reproduce the same state, then runtime_screenshot_diff against ${ref} with tolerance ${tol} (pass a region to ignore volatile HUD areas). ok:true means no meaningful drift.`,
+            `1. Establish the golden (first run only): godot_run_managed, drive the game to the state under test (runtime_inject_input / runtime_call_method), then runtime_screenshot and save the frame to ${ref}. Commit it (vcs_add) so it's the reference, then godot_stop — this recipe runs the game more than once, and a game left running holds the runtime bridge port, so the next run is refused.`,
+            `2. Regression run (every time after): godot_run_managed, reproduce the same state, then runtime_screenshot_diff against ${ref} with tolerance ${tol} (pass a region to ignore volatile HUD areas). ok:true means no meaningful drift. godot_stop when the diff is in hand.`,
             "3. On failure: the diff returns diff_ratio + differing_pixels — don't just eyeball it. runtime_get_tree / runtime_assert_node_state to find the node that changed, or dbg_* to break where the offending value is set. Update the golden deliberately (re-do step 1) only once you've confirmed the change is intended.",
             "",
             "The whole diff runs engine-side (Image), so there's no OCR/image dependency and it stays read-only and ungated.",
@@ -138,7 +138,7 @@ export function registerRecipes(server) {
             `1. Understand: gd_document_symbols for the file's shape; gd_definition / gd_references before touching a symbol so you know every call site; find_usages across the project for wider blast radius.`,
             "2. Edit with help: while writing, use gd_completion and gd_hover to get exact API names and signatures (this is where a generic 'call any method' tool hallucinates — the LSP gives you the truth). gd_rename to rename safely across the project.",
             "3. Gate: run gd_diagnostics and do not proceed until it's clean. gd_code_action for quick-fixes it suggests.",
-            "4. Prove behavior: godot_run_project and a runtime_assert_* that the change did what you intended. If it didn't, dbg_* into it.",
+            "4. Prove behavior: godot_run_managed and a runtime_assert_* that the change did what you intended, then godot_stop — leaving it running holds the runtime bridge port and the next run of this recipe is refused. If the assert didn't pass, dbg_* into it.",
             "",
             "Every mutation is on the undo stack — editor_undo reverts a bad edit instantly.",
             "",

package/dist/tools/cli.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { log } from "../logger.js";
 import { registerTaskTool } from "../tasks.js";
 import { ok } from "./lsp-common.js";
+import { portFree, portConflictMessage } from "../ports.js";
 const execFileAsync = promisify(execFile);
 /** Run the Godot binary to completion, capturing stdout/stderr. */
 async function runCaptured(cfg, args, timeoutMs, signal) {
@@ -62,11 +63,23 @@ export function registerCliTools(server, cfg) {
     });
     server.registerTool("godot_run_project", {
         title: "Run project",
-        description: "Run the project (detached). Optionally start from a specific scene path (res://...). Returns the process id.",
+        description: "Run the project (detached). Optionally start from a specific scene path (res://...). Returns the process id. " +
+            "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
+            "runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
+            "than one game at once.",
         inputSchema: {
             scene: z.string().optional().describe("Optional scene to run, e.g. res://levels/test.tscn"),
+            allow_port_conflict: z
+                .boolean()
+                .optional()
+                .describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
+                "bridge will NOT be reachable — use only when you want the process for its side effects and will not " +
+                "call any runtime_* tool against it."),
         },
-    }, async ({ scene }) => {
+    }, async ({ scene, allow_port_conflict }) => {
+        if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
+            return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
+        }
         const args = ["--path", cfg.projectPath];
         if (scene)
             args.push(scene);

package/dist/tools/csdap.js

@@ -3,6 +3,7 @@ import { DapError } from "../dap.js";
 import { toFsPath } from "../paths.js";
 import { gate } from "../confirm.js";
 import { ok } from "./lsp-common.js";
+import { portFree, portConflictMessage } from "../ports.js";
 // How long step/continue wait for the program to settle (hit a breakpoint,
 // finish a step, or terminate) before returning. On timeout the tool reports
 // the current state — e.g. `continue` with no further breakpoint stays running.
@@ -54,12 +55,41 @@ export function registerCsDapTools(server, dap, cfg) {
             args: z.array(z.string()).optional().describe("Program arguments (default: ['--path', <C# project>])"),
             stop_on_entry: z.boolean().optional().describe("Break at entry (default false)"),
             just_my_code: z.boolean().optional().describe("Restrict stepping/breakpoints to user code (netcoredbg justMyCode; default true)"),
+            allow_port_conflict: z
+                .boolean()
+                .optional()
+                .describe("Launch even though the runtime bridge port is already bound (default false). Only consulted when " +
+                "this looks like a Godot launch — the program is named godot, or the args carry Godot's --path " +
+                "project flag. Debugging some other .NET program is never gated. Breakpoints and stepping still " +
+                "work; runtime_* tools would talk to the process holding the port."),
         },
-    }, async ({ program, args, stop_on_entry, just_my_code }) => {
+    }, async ({ program, args, stop_on_entry, just_my_code, allow_port_conflict }) => {
+        const resolvedProgram = program ?? cfg.csDapProgram;
+        const resolvedArgs = args ?? ["--path", cfg.csDapProjectPath];
+        // Does this launch a Godot game — i.e. one whose autoload wants the runtime
+        // port — or some other .NET program netcoredbg is being pointed at?
+        //
+        // DEFAULT TO YES, and skip the gate only when the caller has clearly aimed
+        // elsewhere. Comparing the resolved program against `cfg.csDapProgram` was
+        // the obvious-looking test and is wrong: that is equality against the
+        // DEFAULT, so passing the real Mono binary explicitly — the way config.ts
+        // documents pointing at it — skipped the gate on the mainline path this
+        // whole change exists to cover. `--path <project>` is Godot's own project
+        // flag and appears in the default args; a program not called godot and not
+        // given --path is the one case we are confident is not a game.
+        const looksLikeGodot = /godot/i.test(resolvedProgram.split(/[\\/]/).pop() ?? "") || resolvedArgs.includes("--path");
+        if (looksLikeGodot &&
+            !allow_port_conflict &&
+            !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort, "debugger") }],
+            };
+        }
         try {
             await dap.start("launch", {
-                program: program ?? cfg.csDapProgram,
-                args: args ?? ["--path", cfg.csDapProjectPath],
+                program: resolvedProgram,
+                args: resolvedArgs,
                 cwd: cfg.csDapProjectPath,
                 stopAtEntry: stop_on_entry ?? false,
                 justMyCode: just_my_code ?? true,
@@ -70,6 +100,8 @@ export function registerCsDapTools(server, dap, cfg) {
             return fail(err);
         }
     });
+    // NOT port-gated, deliberately — see dbg_attach: attaching to the process that
+    // already holds the port is the remedy, not the problem.
     server.registerTool("cs_dbg_attach", {
         title: "Attach C# debug session",
         description: "Attach netcoredbg to an already-running .NET process (e.g. a C# Godot game launched separately) by its OS process id. " +
@@ -345,6 +377,8 @@ export function registerCsDapTools(server, dap, cfg) {
             return fail(err);
         }
     });
+    // NOT port-gated, deliberately — see dbg_restart: the session's own game still
+    // holds the port at check time, so a probe here false-positives every restart.
     server.registerTool("cs_dbg_restart", {
         title: "Restart C# debug session",
         description: "Restart the current C# debug session. Uses the DAP `restart` request when the adapter advertises `supportsRestartRequest`, " +

package/dist/tools/dap.js

@@ -3,6 +3,7 @@ import { DapError } from "../dap.js";
 import { toFsPath } from "../paths.js";
 import { gate } from "../confirm.js";
 import { ok } from "./lsp-common.js";
+import { portFree, portConflictMessage } from "../ports.js";
 // How long step/continue wait for the program to settle (hit a breakpoint,
 // finish a step, or terminate) before returning. On timeout the tool reports
 // the current state — e.g. `continue` with no further breakpoint stays running.
@@ -55,12 +56,28 @@ export function registerDapTools(server, dap, cfg) {
     server.registerTool("dbg_launch", {
         title: "Launch debug session",
         description: "Start the game under the debugger. scene may be 'main', 'current', or a res:// scene path. " +
-            "Any breakpoints set beforehand are applied during the handshake.",
+            "Any breakpoints set beforehand are applied during the handshake. " +
+            "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, so " +
+            "runtime_* would address the process already holding the port. Clear the holder (godot_stop, or quit " +
+            "it), or dbg_attach onto it if it is already under the debugger, or pass allow_port_conflict " +
+            "(dbg_* is unaffected either way; only runtime_* is).",
         inputSchema: {
             scene: z.string().optional().describe("'main' (default), 'current', or res://scene.tscn"),
             stop_on_entry: z.boolean().optional().describe("Break at entry (default false)"),
+            allow_port_conflict: z
+                .boolean()
+                .optional()
+                .describe("Launch even though the runtime bridge port is already bound (default false). Breakpoints and " +
+                "stepping still work — a DAP session is addressed by session, not by port — but runtime_* " +
+                "tools would talk to the process holding the port, not to this game."),
         },
-    }, async ({ scene, stop_on_entry }) => {
+    }, async ({ scene, stop_on_entry, allow_port_conflict }) => {
+        if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort, "debugger") }],
+            };
+        }
         try {
             await dap.start("launch", {
                 project: cfg.projectPath,
@@ -73,6 +90,9 @@ export function registerDapTools(server, dap, cfg) {
             return fail(err);
         }
     });
+    // NOT port-gated, deliberately: attaching to the game that already holds the
+    // port is the REMEDY dbg_launch's refusal points at. Gating it would close the
+    // exit and leave the caller with nowhere to go.
     server.registerTool("dbg_attach", {
         title: "Attach debug session",
         description: "Attach to an already-running Godot debug session.",
@@ -367,6 +387,14 @@ export function registerDapTools(server, dap, cfg) {
             return fail(err);
         }
     });
+    // NOT port-gated, deliberately, and this one is a trap worth naming: at the
+    // moment of the check the session's OWN game still holds the runtime port and
+    // is about to be terminated. A probe here would fire on the very process it is
+    // about to replace — a guaranteed false positive on the happy path, every
+    // single time. The relaunch reuses the launch parameters, so if some THIRD
+    // process holds the port the fresh game lands bridgeless exactly as before;
+    // that residue is accepted knowingly rather than traded for a check that cries
+    // wolf on every restart.
     server.registerTool("dbg_restart", {
         title: "Restart debug session",
         description: "Restart the current debug session. Uses the DAP `restart` request when the adapter advertises `supportsRestartRequest`, " +

package/dist/tools/processes.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { z } from "zod";
 import { log } from "../logger.js";
 import { ok } from "./lsp-common.js";
+import { portFree, portConflictMessage } from "../ports.js";
 const LINE_CAP = 5000;
 /**
  * Runs Godot as a MANAGED child (piped stdio) so the host captures ALL stdout/
@@ -83,9 +84,23 @@ export function registerProcessTools(server, cfg) {
     server.registerTool("godot_run_managed", {
         title: "Run project (managed, captured output)",
         description: "Run the project as a managed child process with captured stdout/stderr, so godot_output can read ALL print()/error output. " +
-            "Returns a process id. Use this instead of godot_run_project when you want the game's console log.",
-        inputSchema: { scene: z.string().optional().describe("Optional res:// scene to run") },
-    }, async ({ scene }) => {
+            "Returns a process id. Use this instead of godot_run_project when you want the game's console log. " +
+            "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
+            "runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
+            "than one game at once.",
+        inputSchema: {
+            scene: z.string().optional().describe("Optional res:// scene to run"),
+            allow_port_conflict: z
+                .boolean()
+                .optional()
+                .describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
+                "bridge will NOT be reachable — use only when you want the process for its console output or side " +
+                "effects and will not call any runtime_* tool against it."),
+        },
+    }, async ({ scene, allow_port_conflict }) => {
+        if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
+            return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
+        }
         const m = registry.run(cfg, scene ? [scene] : []);
         return ok({ id: m.id, pid: m.child.pid ?? null, running: true, scene: scene ?? null });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model, captured console output, and MCP resources.",
   "type": "module",
   "license": "MIT",