breakpoint-mcp 1.28.0 → 1.72.7

package/dist/tools/editor/ui.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** UI / Control / theming. control_* + container_add_child mutate the EDITED scene and are undoable via EditorUndoRedoManager and ungated (the node_* model). theme_* author a Theme on disk via ResourceSaver, so — like resource_* — they are file-writers gated by confirmation. */
-export function registerUiTools(server, call) {
+export function registerUiTools(server, call, guard) {
     server.registerTool("control_create", {
         title: "Create control",
         description: "Instance a Control-derived UI node (Button, Label, Panel, VBoxContainer, TextureRect, …) under a parent (undoable). Refuses non-Control classes. Optional 'text' is applied only to controls that expose a 'text' property. Returns the new node's path.",
@@ -93,7 +93,15 @@ export function registerUiTools(server, call) {
             path: z.string().describe("Control node path relative to the scene root"),
             theme_path: z.string().describe("Theme res:// path, or \"\" to clear the theme override"),
         },
-    }, async ({ path, theme_path }) => call("control.set_theme", { path, theme_path }));
+    }, 
+    // `""` is the documented "clear the override" spelling and resolves to the
+    // project root itself, which is INSIDE it — so the guard leaves it alone.
+    async ({ path, theme_path }) => {
+        const escaped = guard(theme_path, "theme_path");
+        if (escaped)
+            return escaped;
+        return call("control.set_theme", { path, theme_path });
+    });
     server.registerTool("theme_create", {
         title: "Create theme",
         description: "Create a new empty Theme resource and save it to a res:// path. DESTRUCTIVE (writes a file) — gated by confirmation.",
@@ -102,6 +110,9 @@ export function registerUiTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ to_path, confirm }) => {
+        const escaped = guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Create Theme resource at ${to_path}`);
         if (blocked)
             return blocked;
@@ -118,6 +129,13 @@ export function registerUiTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, name, theme_type, color, confirm }) => {
+        // 🔴 THE THEME ITSELF IS LOADED AND RE-SAVED, so `path` is a WRITE target. All four
+        // theme_set_* tools rewrote a Theme OUTSIDE the project root through ALL THREE
+        // spellings — verdict from the file's bytes. `theme_set_font`/`theme_set_stylebox`
+        // guarded their SECOND parameter and left this one open since #175.
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set theme color ${theme_type}/${name} in ${path}`);
         if (blocked)
             return blocked;
@@ -134,6 +152,9 @@ export function registerUiTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, name, theme_type, font_path, confirm }) => {
+        const escaped = guard(path, "path") ?? guard(font_path, "font_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set theme font ${theme_type}/${name} in ${path}`);
         if (blocked)
             return blocked;
@@ -150,6 +171,9 @@ export function registerUiTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, name, theme_type, stylebox_path, confirm }) => {
+        const escaped = guard(path, "path") ?? guard(stylebox_path, "stylebox_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set theme stylebox ${theme_type}/${name} in ${path}`);
         if (blocked)
             return blocked;
@@ -166,6 +190,9 @@ export function registerUiTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, name, theme_type, value, confirm }) => {
+        const escaped = guard(path, "path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Set theme constant ${theme_type}/${name} in ${path}`);
         if (blocked)
             return blocked;

package/dist/tools/editor.js

@@ -1,4 +1,4 @@
-import { makeCall } from "./editor/common.js";
+import { makeCall, makePathGuard } from "./editor/common.js";
 import { registerCoreTools } from "./editor/core.js";
 import { registerSceneTools } from "./editor/scene.js";
 import { registerNodeTools } from "./editor/node.js";
@@ -22,23 +22,30 @@ import { registerProjectInputTestTools } from "./editor/project_input_test.js";
  * helper and registers each group in its original order, so the registered tool
  * set and its order are unchanged.
  */
-export function registerEditorTools(server, bridge) {
+export function registerEditorTools(server, bridge, config) {
     const call = makeCall(bridge);
+    // 🔴 THE GUARD IS THREADED, NOT INSTALLED IN `makeCall`. Wrapping the shared bridge
+    // helper would have been one line, but it serves ~150 editor tools whose params are
+    // node paths, property names and class names — a helper that has to GUESS which
+    // string is a filesystem path is a guess on every one of them. The writers (164)
+    // and READERS (165) that were MEASURED escaping take it explicitly instead, so the
+    // blast radius of this change is exactly the set that was measured.
+    const guard = makePathGuard(config.projectPath);
     registerCoreTools(server, call);
-    registerSceneTools(server, call);
-    registerNodeTools(server, call);
+    registerSceneTools(server, call, guard);
+    registerNodeTools(server, call, guard);
     registerSignalTools(server, call);
     registerIntrospectionTools(server, call, bridge);
-    registerResourceTools(server, call);
-    registerFilesystemTools(server, call);
+    registerResourceTools(server, call, guard);
+    registerFilesystemTools(server, call, guard);
     registerAnimationTools(server, call);
-    registerTileTools(server, call);
+    registerTileTools(server, call, guard);
     registerPhysicsTools(server, call);
-    registerParticleTools(server, call);
-    registerShaderTools(server, call);
-    registerAudioTools(server, call);
-    registerUiTools(server, call);
-    registerSpatialTools(server, call);
-    registerProjectInputTestTools(server, call);
+    registerParticleTools(server, call, guard);
+    registerShaderTools(server, call, guard);
+    registerAudioTools(server, call, guard);
+    registerUiTools(server, call, guard);
+    registerSpatialTools(server, call, guard);
+    registerProjectInputTestTools(server, call, guard);
 }
 //# sourceMappingURL=editor.js.map

package/dist/tools/knowledge.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { toFsPath } from "../paths.js";
+import { resolveInsideProject, toFsPath } from "../paths.js";
+import { failPath } from "./lsp-common.js";
 /**
  * Group K — Knowledge & search (read-only).
  *
@@ -351,6 +352,18 @@ export function registerKnowledgeTools(server, cfg) {
             max_results: z.number().int().positive().optional().describe("Cap on returned matches (default 200)"),
         },
     }, async ({ query, regex, ignore_case, extensions, path: sub, max_results }) => {
+        // 🔴 MEASURED: `path: "res://../example_evil"` SEARCHED AND RETURNED MATCHES from
+        // files outside the project root. This tool never touches the editor bridge, so
+        // the addon's res:// check was never in front of it — the host is the only guard.
+        // An omitted `path` means "whole project" and stays legal.
+        if (sub !== undefined) {
+            try {
+                resolveInsideProject(sub, cfg.projectPath, "path");
+            }
+            catch (err) {
+                return failPath(err);
+            }
+        }
         const cap = max_results ?? 200;
         let re;
         try {

package/dist/tools/lsp-common.js

@@ -28,11 +28,40 @@ export function ok(obj) {
 /** MCP error envelope for a failed LSP call (never throws to the caller). */
 export function fail(err) {
     const e = err;
+    // A REFUSAL is the host declining the call, not the language server failing
+    // one. Rendering it as "LSP error [...]" sent the caller to debug a server
+    // that was never asked. Refusals carry their own message verbatim.
+    if (e?.refusal) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: e.message ?? String(err) }],
+        };
+    }
     return {
         isError: true,
         content: [{ type: "text", text: `LSP error [${e.code ?? "error"}]: ${e.message ?? String(err)}` }],
     };
 }
+/**
+ * MCP error envelope for a PATH REFUSAL — the host declining a call before it
+ * touches any backend. Lives here, beside `ok`/`fail`, because it belongs to no
+ * single plane: the editor writers and the asset generators both raise it.
+ *
+ * 🔴 DELIBERATELY NOT the editor plane's `fail()`, which labels everything
+ * "Bridge error" — that means "the editor could not be reached" and sends the
+ * caller to restart Godot over a typo in their own path. The distinction is the
+ * one `fail()` above already draws for LSP refusals, applied to the writers.
+ *
+ * The refusal's own message and `path_outside_project` code carry through
+ * unchanged, which is what every gate in the tree actually pins.
+ */
+export function failPath(err) {
+    const be = err;
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Path error [${be?.code ?? "error"}]: ${be?.message ?? String(err)}` }],
+    };
+}
 /**
  * Normalize an LSP documentation / MarkupContent field (a plain string, a
  * `{ kind, value }` MarkupContent, or an array of either) down to a single

package/dist/tools/lsp.js

@@ -1,8 +1,34 @@
 import fs from "node:fs";
 import { z } from "zod";
-import { toFileUri, toFsPath, readFileText } from "../paths.js";
+import { toFileUri, toFsPath, readFileText, resolveSourceFile } from "../paths.js";
 import { gate } from "../confirm.js";
 import { COMPLETION_KIND, SYMBOL_KIND, ok, fail, markupToString, isMethodNotFound, normalizeLocations, applyTextEdits, } from "./lsp-common.js";
+/**
+ * The wording this plane's refusals have shipped with, kept verbatim while the guard
+ * itself moved to `paths.ts` (161 §8 item 5). `lsp-plane.integration.mjs` pins every
+ * string here by regex — /outside the Godot project root/, /no such file/,
+ * /is not a file/ — so this constant IS the contract, not decoration.
+ *
+ * Measured, sessions 156 and 162: `toFsPath` joins through `path.join`, which
+ * normalizes `..` away silently, so `res://../../../etc/passwd` resolved to a real
+ * path outside the project and the tools answered success for it. And a missing file
+ * was OPENED AS AN EMPTY ONE: `gd_document_symbols` returned a phantom
+ * `{name: "<file>.gd", kind: "class"}` and `gd_diagnostics` a genuine
+ * "(EMPTY_FILE): Empty script file." warning — both isError:false, about a file that
+ * is not there.
+ *
+ * 🔴 162: this guard sits AFTER each tool's capability check, so on Godot 4.7 only
+ * 11 of the 19 path-taking gd_* tools reach it — the other 8 answer "unsupported"
+ * first. Nothing escapes (an unsupported tool never touches the path), but the live
+ * gate can only assert the refusal on tools whose provider the connected build
+ * advertises. Measured, recorded, deliberately NOT rearranged.
+ */
+const GD_LSP_PATHS = {
+    root: "the Godot project root",
+    escapeHint: "Pass a res:// path, or a path inside the project.",
+    missingHint: "It was previously opened as an EMPTY document, so the language server answered " +
+        "about a file that does not exist.",
+};
 /**
  * Returned by gd_workspace_symbols when the connected Godot build's GDScript
  * language server has no `workspace/symbol` method. This is an engine limitation
@@ -165,16 +191,52 @@ function decodeSemanticTokens(data, legend) {
 }
 // offsetOf / applyTextEdits now live in ./lsp-common.js (shared with the C#
 // rename mutator, cs_rename). Imported above.
+/**
+ * A GDScript identifier: the only thing `gd_rename` may rename a symbol TO.
+ * Measured on real 4.3/4.5/4.7 — the language server happily plans a full
+ * project-wide rename to "", "1bad name!", "func" or a string containing a
+ * newline and answers `edit_count: 9` for every one of them. With `apply:true`
+ * those edits WRITE GDScript that cannot parse, so the refusal has to happen
+ * here: the server will not do it for us.
+ */
+const GD_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * GDScript reserved words. A rename to one of these is syntactically an
+ * identifier but produces a file the parser rejects, so it is refused for the
+ * same reason. Kept deliberately narrow — engine CLASS names (Node, Vector2)
+ * are shadowable and legal, so they are NOT listed.
+ */
+const GD_KEYWORDS = new Set([
+    "if", "elif", "else", "for", "while", "match", "when", "break", "continue", "pass", "return",
+    "class", "class_name", "extends", "is", "in", "as", "self", "super", "signal", "func",
+    "static", "const", "enum", "var", "breakpoint", "preload", "await", "yield", "assert",
+    "void", "PI", "TAU", "INF", "NAN", "and", "or", "not", "true", "false", "null",
+]);
 export function registerLspTools(server, lsp, cfg) {
+    /**
+     * Resolve a caller-supplied script path and REFUSE one that escapes the
+     * project root. `toFsPath` joins through `path.join`, which normalizes `..`
+     * away silently — so `res://../../../etc/passwd` resolved to a real path
+     * outside the project and the tools answered success for it. Measured: the
+     * answer was the same degenerate one any missing path produces, so nothing
+     * leaked, but nothing refused it either.
+     */
+    const guardPath = (p) => {
+        resolveSourceFile(p, cfg.projectPath, GD_LSP_PATHS);
+    };
     const openAndPos = async (path) => {
+        guardPath(path);
         const uri = toFileUri(path, cfg.projectPath);
         await lsp.ensureOpen(uri, readFileText(toFsPath(path, cfg.projectPath)));
         return uri;
     };
     const posSchema = {
         path: z.string().describe("Script path (res://..., absolute, or project-relative)"),
-        line: z.number().int().describe("0-based line"),
-        character: z.number().int().describe("0-based character"),
+        // .min(0): a negative line or character is not a position. Measured — they
+        // sailed through to the wire and the server answered success with empty
+        // contents, so the caller could not tell a bad request from a real miss.
+        line: z.number().int().min(0).describe("0-based line"),
+        character: z.number().int().min(0).describe("0-based character"),
     };
     server.registerTool("gd_completion", { title: "GDScript completion", description: "Type-aware code completion at a position via the Godot language server.", inputSchema: posSchema }, async ({ path, line, character }) => {
         try {
@@ -238,7 +300,8 @@ export function registerLspTools(server, lsp, cfg) {
     });
     server.registerTool("gd_rename", {
         title: "GDScript rename symbol",
-        description: "Rename a symbol project-wide. Returns the planned edit; pass apply=true to WRITE the changes to disk (DESTRUCTIVE — confirm with the user).",
+        description: "Rename a symbol project-wide. Returns the planned edit; pass apply=true to WRITE the changes to disk (DESTRUCTIVE — confirm with the user). " +
+            "new_name must be a valid GDScript identifier and not a reserved word: the language server plans a rename to any string, including one that would write a file GDScript cannot parse, so an illegal name is refused here before the rename is planned.",
         inputSchema: {
             ...posSchema,
             new_name: z.string().describe("New symbol name"),
@@ -247,6 +310,21 @@ export function registerLspTools(server, lsp, cfg) {
         },
     }, async ({ path, line, character, new_name, apply, confirm }) => {
         try {
+            // Refuse BEFORE planning. The language server does not validate the new
+            // name: measured on 4.3/4.5/4.7, a rename to "", "1bad name!", "func"
+            // or "a\nb" each came back with edit_count 9 and isError:false — and
+            // with apply:true those edits write a file GDScript cannot parse.
+            if (!GD_IDENTIFIER.test(new_name)) {
+                throw Object.assign(new Error(`Refusing to rename to ${JSON.stringify(new_name)}: it is not a valid GDScript ` +
+                    `identifier (letter or underscore, then letters, digits or underscores). ` +
+                    `The language server will plan this rename anyway and the written file would ` +
+                    `not parse.`), { refusal: true, code: "invalid_identifier" });
+            }
+            if (GD_KEYWORDS.has(new_name)) {
+                throw Object.assign(new Error(`Refusing to rename to "${new_name}": it is a GDScript reserved word. ` +
+                    `The language server will plan this rename anyway and the written file would ` +
+                    `not parse.`), { refusal: true, code: "reserved_word" });
+            }
             const uri = await openAndPos(path);
             const edit = (await lsp.request("textDocument/rename", {
                 textDocument: { uri }, position: { line, character }, newName: new_name,
@@ -389,10 +467,10 @@ export function registerLspTools(server, lsp, cfg) {
             "end_line/end_character default to the start position (a caret, not a selection).",
         inputSchema: {
             path: z.string().describe("Script path (res://..., absolute, or project-relative)"),
-            start_line: z.number().int().describe("0-based start line"),
-            start_character: z.number().int().describe("0-based start character"),
-            end_line: z.number().int().optional().describe("0-based end line (default = start_line)"),
-            end_character: z.number().int().optional().describe("0-based end character (default = start_character)"),
+            start_line: z.number().int().min(0).describe("0-based start line"),
+            start_character: z.number().int().min(0).describe("0-based start character"),
+            end_line: z.number().int().min(0).optional().describe("0-based end line (default = start_line)"),
+            end_character: z.number().int().min(0).optional().describe("0-based end character (default = start_character)"),
             only: z.array(z.string()).optional().describe("Restrict to these CodeActionKind prefixes, e.g. 'quickfix', 'refactor', 'source'"),
         },
     }, async ({ path, start_line, start_character, end_line, end_character, only }) => {
@@ -579,6 +657,7 @@ export function registerLspTools(server, lsp, cfg) {
             const caps = await lsp.getServerCapabilities();
             if (!caps.documentFormattingProvider)
                 return unsupportedLsp("gd_formatting", "textDocument/formatting", "documentFormattingProvider", alt);
+            guardPath(path);
             const fsPath = toFsPath(path, cfg.projectPath);
             const before = readFileText(fsPath);
             const uri = toFileUri(path, cfg.projectPath);

package/dist/tools/netcode.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { gate } from "../confirm.js";
-import { toFsPath, readFileText } from "../paths.js";
+import { readFileText, resolveExistingFile, resolveInsideProject } from "../paths.js";
 /**
  * Group M — Netcode & backend scaffolding (native multiplayer family, `mp_*`).
  *
@@ -202,7 +202,19 @@ export function registerNetcodeTools(server, bridge, config) {
             spawn_path: z.string().optional().describe("NodePath (relative to the spawner) whose children are auto-replicated"),
             spawnable_scenes: z.array(z.string()).optional().describe("res:// scenes the spawner may instantiate (add_spawnable_scene)"),
         },
-    }, async ({ parent_path, name, spawn_path, spawnable_scenes }) => {
+    }, 
+    // 🔴 AN ARRAY PARAM, AND EVERY ELEMENT IS A PATH. The spawner STORED
+    // `res://../example_evil/x.tscn` on the node and echoed it back, so at runtime it
+    // would instantiate a scene from outside the project. Guard each element — a
+    // guard on `spawnable_scenes[0]` alone is not a guard.
+    async ({ parent_path, name, spawn_path, spawnable_scenes }) => {
+        try {
+            for (const s of spawnable_scenes ?? [])
+                resolveInsideProject(s, config.projectPath, "spawnable_scenes");
+        }
+        catch (err) {
+            return fail(err);
+        }
         try {
             return ok(await call("mp.add_spawner", {
                 parent_path,
@@ -283,6 +295,13 @@ export function registerNetcodeTools(server, bridge, config) {
     }, async ({ to_path, port, max_clients, class_name, overwrite, confirm }) => {
         if (!to_path.startsWith("res://") || !to_path.endsWith(".gd"))
             return fail({ code: "bad_params", message: "'to_path' must be a res:// .gd path" });
+        // `res://../` satisfies the pre-guard and writes outside the root (161).
+        try {
+            resolveInsideProject(to_path, config.projectPath, "to_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, confirm, `Write ENet peer script to ${to_path}`);
         if (blocked)
             return blocked;
@@ -310,6 +329,13 @@ export function registerNetcodeTools(server, bridge, config) {
     }, async ({ to_path, class_name, overwrite, confirm }) => {
         if (!to_path.startsWith("res://") || !to_path.endsWith(".gd"))
             return fail({ code: "bad_params", message: "'to_path' must be a res:// .gd path" });
+        // `res://../` satisfies the pre-guard and writes outside the root (161).
+        try {
+            resolveInsideProject(to_path, config.projectPath, "to_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, confirm, `Write WebRTC peer script to ${to_path}`);
         if (blocked)
             return blocked;
@@ -348,9 +374,19 @@ export function registerNetcodeTools(server, bridge, config) {
     }, async ({ path, function: fn, mode, transfer_mode, call_local, channel, confirm }) => {
         if (!path.startsWith("res://") || !path.endsWith(".gd"))
             return fail({ code: "bad_params", message: "'path' must be a res:// .gd path" });
-        const source = readFileText(toFsPath(path, config.projectPath));
+        // The res:// pre-guard above stops an absolute path and a bare `../`, but
+        // `res://../elsewhere/x.gd` satisfies startsWith("res://") and resolved to
+        // a real file outside the project root — which this tool then REWROTE.
+        // Measured 3/3 against a sibling directory (session 161).
+        let source;
+        try {
+            source = readFileText(resolveExistingFile(path, config.projectPath, "path"));
+        }
+        catch (err) {
+            return fail(err);
+        }
         if (source === "")
-            return fail({ code: "not_found", message: `Cannot read ${path} (does it exist?)` });
+            return fail({ code: "empty_file", message: `${path} is empty (0 bytes) — there is no source to annotate.` });
         const annotation = rpcAnnotation({
             mode: mode ?? "authority",
             call_local: call_local ?? false,
@@ -395,6 +431,13 @@ export function registerNetcodeTools(server, bridge, config) {
     }, async ({ to_path, port, max_players, class_name, overwrite, confirm }) => {
         if (!to_path.startsWith("res://") || !to_path.endsWith(".gd"))
             return fail({ code: "bad_params", message: "'to_path' must be a res:// .gd path" });
+        // `res://../` satisfies the pre-guard and writes outside the root (161).
+        try {
+            resolveInsideProject(to_path, config.projectPath, "to_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, confirm, `Write multiplayer lobby script to ${to_path}`);
         if (blocked)
             return blocked;

package/dist/tools/processes.js

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
 import { z } from "zod";
 import { log } from "../logger.js";
-import { ok } from "./lsp-common.js";
+import { ok, failPath } from "./lsp-common.js";
+import { resolveInsideProject } from "../paths.js";
 import { portFree, portConflictMessage } from "../ports.js";
 const LINE_CAP = 5000;
 /**
@@ -97,7 +98,18 @@ export function registerProcessTools(server, cfg) {
                 "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 }) => {
+    }, 
+    // 🔴 `godot_run_project`'s TWIN, in a different file, with the same defect —
+    // measured the same way and launching the same escaping argv. 1.42.0's lesson
+    // ("the second call site is the interesting one") applied before the fact.
+    async ({ scene, allow_port_conflict }) => {
+        try {
+            if (scene !== undefined)
+                resolveInsideProject(scene, cfg.projectPath, "scene");
+        }
+        catch (err) {
+            return failPath(err);
+        }
         if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
             return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
         }

package/dist/tools/runtime.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { MAX_PEERS } from "../peers.js";
 import { gate } from "../confirm.js";
-import { ok } from "./lsp-common.js";
+import { ok, failPath } from "./lsp-common.js";
+import { resolveInsideProject } from "../paths.js";
 const confirmField = {
     confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
 };
@@ -77,7 +78,33 @@ function canonical(value) {
     };
     return JSON.stringify(walk(value));
 }
-export function registerRuntimeTools(server, runtime, peers) {
+export function registerRuntimeTools(server, runtime, peers, config) {
+    // 🔴 NINE `.mjs` INTEGRATION PROBES CALL THIS REGISTRAR DIRECTLY, WHERE TYPESCRIPT
+    // CANNOT SEE THEM. Adding `config` compiled clean, passed the whole unit suite, and
+    // then broke six CI jobs at runtime with "Cannot read properties of undefined
+    // (reading 'projectPath')" — thrown from inside a guard, forty minutes in, naming
+    // neither the parameter nor the caller. Failing HERE turns that into a named error
+    // at registration. A .mjs call site is a call site; the compiler is not the roster.
+    if (!config?.projectPath) {
+        throw new Error("registerRuntimeTools requires a Config as its FOURTH argument (added 1.43.0) — " +
+            "got none. Direct callers in test-integration/*.mjs must pass `cfg`.");
+    }
+    /** 🔴 MEASURED against a game actually hosting the runtime bridge — rounds A–C
+     *  answered `bridge_unavailable` for every runtime row, which is a degrade path,
+     *  not a verdict. With the bridge up, `runtime_node_add` instantiated a PackedScene
+     *  from outside the root and `runtime_screenshot_diff` diffed against an outside
+     *  PNG, both through all three spellings. */
+    const guardPath = (p, label) => {
+        if (p === undefined)
+            return null;
+        try {
+            resolveInsideProject(p, config.projectPath, label);
+            return null;
+        }
+        catch (err) {
+            return failPath(err);
+        }
+    };
     /** The bridge addressing `peer`, or the default running game when omitted. */
     const clientFor = (peer) => (peer ? peers.clientFor(peer) : runtime);
     /** Human label for confirmation prompts, so a gated op names its target process. */
@@ -125,7 +152,9 @@ export function registerRuntimeTools(server, runtime, peers) {
     });
     server.registerTool("runtime_emit_signal", {
         title: "Runtime emit signal",
-        description: "Emit a signal from a live node. DESTRUCTIVE — gated by confirmation.",
+        description: "Emit a signal from a live node. DESTRUCTIVE — gated by confirmation. " +
+            "args must match the arity of the signal's CONNECTED callables, or the emission fails with emit_failed and no handler runs. " +
+            "Argument types are not checked, and a signal with no listeners always succeeds — so emitted:true does not mean a handler ran.",
         inputSchema: { path: z.string(), signal: z.string(), args: z.array(z.any()).optional(), ...confirmField, ...peerField },
     }, async ({ path, signal, args, confirm, peer }) => {
         const blocked = await gate(server, confirm, `Emit signal "${signal}" from ${path} on ${target(peer)}`);
@@ -303,12 +332,17 @@ export function registerRuntimeTools(server, runtime, peers) {
                 .describe("Optional sub-region (applied to both frame and reference) to compare"),
             ...peerField,
         },
-    }, async ({ reference, tolerance, per_channel_threshold, region, peer }) => call("runtime.screenshot_diff", {
-        reference,
-        ...(tolerance !== undefined ? { tolerance } : {}),
-        ...(per_channel_threshold !== undefined ? { per_channel_threshold } : {}),
-        ...(region !== undefined ? { region } : {}),
-    }, peer));
+    }, 
+    // `user://…` stays legal: `toFsPath` treats it as a relative spelling and joins
+    // it under the root, so it resolves INSIDE and the guard passes it through
+    // untouched — the documented mainline is preserved, and a test pins it.
+    async ({ reference, tolerance, per_channel_threshold, region, peer }) => guardPath(reference, "reference") ??
+        call("runtime.screenshot_diff", {
+            reference,
+            ...(tolerance !== undefined ? { tolerance } : {}),
+            ...(per_channel_threshold !== undefined ? { per_channel_threshold } : {}),
+            ...(region !== undefined ? { region } : {}),
+        }, peer));
     // F8: deterministic-verification helper. Poll a live property until it meets a
     // comparison, or a timeout elapses. Host-side over runtime.get_property (no new
     // bridge method), so it works on every engine build the runtime bridge supports.
@@ -418,6 +452,9 @@ export function registerRuntimeTools(server, runtime, peers) {
             ...peerField,
         },
     }, async ({ parent, type, scene, name, confirm, peer }) => {
+        const escaped = guardPath(scene, "scene");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Add ${scene ?? type ?? "node"} under ${parent} in ${target(peer)}`);
         if (blocked)
             return blocked;
@@ -553,6 +590,9 @@ export function registerRuntimeTools(server, runtime, peers) {
                 .describe("How long to wait for every peer to answer on its bridge, in ms (default 15000)"),
         },
     }, async ({ count, scene, args, role, timeout_ms }) => {
+        const escaped = guardPath(scene, "scene");
+        if (escaped)
+            return escaped;
         try {
             const spawned = await peers.spawn({
                 count,