breakpoint-mcp 1.28.0 → 1.72.7

package/dist/tools/dap.js

@@ -1,18 +1,130 @@
 import { z } from "zod";
 import { DapError } from "../dap.js";
-import { toFsPath } from "../paths.js";
+import { resolveSourceFile } from "../paths.js";
 import { gate } from "../confirm.js";
 import { ok } from "./lsp-common.js";
 import { portFree, portConflictMessage } from "../ports.js";
+/**
+ * How long `stop_on_entry: true` waits for the entry `stopped` event before
+ * reporting that the adapter did not honour it. Short on purpose: Godot 4.7 ignores
+ * `stopOnEntry` outright (measured — the game ran to completion and printed its
+ * `_ready()` line), so this is the price of the honest answer on every launch, not a
+ * rare timeout. An adapter that DOES honour it stops well inside the window.
+ */
+const ENTRY_STOP_WAIT_MS = 3000;
+/** A refusal raised by a guard here, rendered verbatim rather than as a DAP error. */
+class DapRefusal extends Error {
+    reason;
+    /**
+     * 🔴 162: the SAME marker `paths.ts`, `lsp-common.fail()` and `csdap.ts` already use.
+     * Before this, dap.ts recognised a refusal only by `instanceof DapRefusal`, so a
+     * refusal raised anywhere else — including by the shared guard this file now calls —
+     * would have been rendered as `DAP error [error]: Refusing "…"`, sending the caller
+     * to debug an adapter that was never asked. One refusal contract, four planes.
+     */
+    refusal = true;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "DapRefusal";
+    }
+}
+/**
+ * This plane's shipped refusal wording, kept verbatim while the guard moved to
+ * `paths.ts` (161 §8 item 5). `gdscript-dap-plane.integration.mjs` pins every string
+ * here BY REASON — /outside the Godot project root/, /no such file/, /is not a file/,
+ * and for the empty path additionally /project root/.
+ *
+ * 🔴 The escape check is deliberately WIDER than the `cs_dbg_*` plane's, and 162
+ * measured both to confirm the difference is real rather than drift. `cs_dbg_launch`
+ * documents overriding `program` to debug a DIFFERENT .NET program, whose sources
+ * legitimately live outside the Godot C# project. `dbg_launch` has no such mainline:
+ * its `scene` is `'main'`, `'current'` or a `res://` path, and Godot binds breakpoints
+ * only to scripts in the project it runs — so an absolute path outside the root can
+ * never bind here whichever way it is spelled, and all three forms stay anchored.
+ * Absolute paths INSIDE the project stay legal; the probe uses that form and two
+ * over-eager mutations exist to keep it working.
+ */
+const GD_DAP_PATHS = {
+    root: "the Godot project root",
+    escapeHint: "Godot binds breakpoints only to scripts in the project it runs, so a breakpoint " +
+        "there can never bind.",
+    missingHint: "A breakpoint there can never bind, but it was previously answered exactly like " +
+        "one on a real script.",
+    emptyNote: " (an empty path resolves to the project root)",
+};
+/**
+ * `dbg_launch` / `dbg_restart`'s `scene`, which is a path parameter that is not
+ * called `path` — which is exactly why 162's sweep never reached it (163 §2).
+ *
+ * 🔴 MEASURED against a real 4.7 adapter before a line of this was written, because
+ * the obvious rule would have broken two spellings that work. Every row below is a
+ * launch that was actually performed and whose game console was read back over the
+ * DAP `output` event, so "did it run" is the engine's answer, not an inference:
+ *
+ *   main · current · res://demo/demo.tscn · <abs inside>/demo/demo.tscn · uid://<known>
+ *       -> the REQUESTED scene ran. The last three are the load-bearing ones: each
+ *          ran a scene that is NOT the main scene, so they prove the spelling is
+ *          honoured rather than silently falling back.
+ *   res://../example_evil/… · ../example_evil/… · <root>_evil/… · /elsewhere/…
+ *       -> 🔴 NOTHING ran, and the session stayed `running` with a live, sceneless
+ *          game process. `dbg_stack_trace` then answered `{"frames":[]}` — BYTE
+ *          IDENTICAL to a healthy running session. The caller could not find out.
+ *   ""  -> 🔴 nothing ran, NO game process existed at all, session still `running`.
+ *   /etc/passwd · res://NoSuchFile.tscn · res://tests (a directory)
+ *       -> nothing ran; the session terminated a moment later, so those at least
+ *          announced themselves.
+ *
+ * So NOTHING ESCAPES — Godot never ran an out-of-project scene, whichever way it was
+ * spelled. The defect is not containment, it is that `dbg_launch` answered
+ * `{"state":"running"}` for every one of them. That is the same shape as the
+ * `dbg_set_breakpoints` defect above it in this file — an answer that cannot
+ * distinguish "armed" from "can never bind" — one tool over on the same plane.
+ *
+ * 🔴 uid:// IS EXEMPT AND THAT EXEMPTION IS MEASURED, NOT ASSUMED. Godot 4 writes a
+ * UID into every scene header, and `uid://bq3k7x2yv8n1a` RAN the scene it names. A
+ * uid names a project resource through the engine's own map, never a filesystem
+ * location, so it cannot express an escape — and requiring it to exist on disk would
+ * refuse a working spelling to fix a broken one. That is precisely the mistake 162
+ * §5 D2 caught itself about to make on `csdap`.
+ *
+ * 🔴 WHAT THIS DELIBERATELY DOES NOT FIX, because it was measured and is a different
+ * defect: an UNKNOWN uid (`uid://zzzzzzzzzzzzz`) silently ran the MAIN scene while
+ * the tool echoed the uid back. Resolving that needs the engine's UID map, which the
+ * host does not have. Recorded in the description and the handoff rather than guessed
+ * at. Likewise `res://player.gd` — a real file inside the root that is not a scene —
+ * stays legal here and terminates the session, which at least announces itself.
+ */
+const GD_DAP_SCENE = {
+    root: "the Godot project root",
+    escapeHint: "Godot runs scenes from the project it launched, so a scene outside the root never " +
+        "loads: measured, the game starts with no scene and the session reports `running` " +
+        "forever. Pass 'main', 'current', a scene inside the project, or a uid:// reference.",
+    missingHint: "The adapter accepts the launch and nothing runs, so this was previously reported " +
+        "as a started session.",
+    emptyNote: " (an empty scene resolves to the project root)",
+};
+/** Scene spellings the adapter resolves itself; neither names a file. */
+const SCENE_SENTINELS = new Set(["main", "current"]);
 // 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.
 const RESUME_WAIT_MS = 15000;
 function fail(err) {
+    // A refusal this file raised is the host's own answer — rendering it as
+    // `DAP error [...]` would send the caller off to debug an adapter that was never
+    // asked. Same distinction lsp-common.fail() already draws for the LSP planes.
     const e = err;
+    if (err instanceof DapRefusal || e?.refusal) {
+        return { isError: true, content: [{ type: "text", text: e.message ?? String(err) }] };
+    }
+    // An adapter can answer a failure with an EMPTY message (netcoredbg did, on
+    // setVariable). `?? String(err)` only covers an ABSENT one, so the whole answer
+    // became a label and a colon.
+    const detail = e.message && e.message.trim() !== "" ? e.message : String(err);
     return {
         isError: true,
-        content: [{ type: "text", text: `DAP error [${e.command ?? "error"}]: ${e.message ?? String(err)}` }],
+        content: [{ type: "text", text: `DAP error [${e.command ?? "error"}]: ${detail}` }],
     };
 }
 /**
@@ -23,46 +135,125 @@ function fail(err) {
 function isDapTimeout(err) {
     return err instanceof DapError && /timed out after/.test(err.message);
 }
-// Per-line breakpoint modifier fields, each gated by an adapter capability. Godot 4.3
-// advertises all three false AND ignores them (a "conditional" breakpoint would halt
-// unconditionally — verified live in the dap-plane's editor-dap-breakpoints probe), so we
-// feature-detect: drop an unsupported modifier and warn, mirroring the
-// dbg_set_exception_breakpoints / dbg_goto / dbg_data_breakpoints discipline.
-const BREAKPOINT_MODIFIER_CAPS = {
-    condition: "supportsConditionalBreakpoints",
-    hitCondition: "supportsHitConditionalBreakpoints",
-    logMessage: "supportsLogPoints",
-};
 /**
- * Which of condition/hitCondition/logMessage the connected adapter does NOT support, out of
- * the ones actually requested. Returns [] when capabilities are unknown (no session yet) —
- * we can only feature-detect once the adapter has advertised what it supports.
+ * 🔴 The modifier feature-detection lives in `dap.ts` (the client), NOT here, and that
+ * is the fix this release carries. It was here, at SET time, where `dap.capabilities`
+ * is null for every breakpoint buffered before launch — which is the documented and
+ * ordinary way to arm one. The guard was correct and unreachable: measured live, a
+ * pre-launch `conditions: ["counter < 0"]` was sent verbatim to an adapter that ignores
+ * it, the breakpoint halted every frame, and the result carried no warning at all.
+ * Detection now happens where the modifiers go on the wire, so every path gets it.
  */
-function unsupportedBreakpointModifiers(caps, requested) {
-    if (!caps)
-        return [];
-    const out = [];
-    for (const field of ["condition", "hitCondition", "logMessage"]) {
-        if (requested[field] && caps[BREAKPOINT_MODIFIER_CAPS[field]] !== true)
-            out.push(field);
-    }
-    return out;
-}
-/** True when a per-line modifier array carries at least one non-null, non-empty entry. */
-function hasModifier(arr) {
-    return Array.isArray(arr) && arr.some((v) => v != null && v !== "");
-}
+const warnDropped = (dropped) => `The connected Godot debug adapter does not support ${dropped.join(", ")} on breakpoints (it advertises ` +
+    `${dropped.length > 1 ? "them" : "it"} unsupported), so ${dropped.length > 1 ? "they were" : "it was"} dropped — ` +
+    `the affected breakpoint(s) will halt unconditionally.`;
 export function registerDapTools(server, dap, cfg) {
+    /**
+     * Refuse when no launch/attach the adapter accepted is in force.
+     *
+     * 🔴 Measured on a client that had never launched anything: `dbg_continue` and
+     * `dbg_step` answered `isError:false {"state":"running"}`, `dbg_stack_trace`
+     * answered `{"frames":[]}` and `dbg_scopes` `{"scopes":[]}` — all four
+     * indistinguishable from the same calls against a real session. Worse,
+     * `resume()`'s optimistic `state = "running"` MEANT THE FIRST SUCH CALL LEFT THE
+     * CLIENT LOOKING LIVE, so everything after it read as a genuine session. Only
+     * `dbg_restart` refused, and only because it happens to read `lastStartMode`.
+     */
+    const requireSession = (tool) => {
+        if (dap.hasSession)
+            return;
+        throw new DapRefusal(`${tool} needs a debug session: call dbg_launch or dbg_attach first. ` +
+            `There is none, so any state, frame or scope reported here would be invented — ` +
+            `this call previously answered as if the program were running.`, "no_session");
+    };
+    /**
+     * Report, on a launch/attach result, any breakpoint modifier the handshake dropped
+     * when it applied the buffered breakpoints.
+     *
+     * 🔴 This is the other half of the buffered-modifier fix. `dbg_set_breakpoints` can
+     * only say "deferred" before a session exists; this is where the caller finds out what
+     * actually happened. Without it the honest "deferred" answer would have no follow-up
+     * and the caller would still be left guessing.
+     */
+    const reportDroppedModifiers = (result) => {
+        const dropped = dap.droppedBreakpointModifiers();
+        if (!dropped.length)
+            return;
+        result.unsupported_modifiers = dropped;
+        // Never clobber a warning the caller needs more (stop_on_entry's); append.
+        const note = `Buffered breakpoint modifiers were applied during this handshake: ${warnDropped(dropped)}`;
+        result.warning = typeof result.warning === "string" && result.warning.length > 0 ? `${result.warning} ${note}` : note;
+    };
+    /**
+     * Resolve a breakpoint source, refusing one that can never bind.
+     *
+     * 🔴 Measured: `res://NoSuchFile.gd`, `res://tests` (a DIRECTORY) and `""` — which
+     * resolves to the project root — each answered `{"buffered":true,"breakpoints":[]}`
+     * with `isError:false`, so a caller could not tell an armed breakpoint from one
+     * that can never bind. `res://../../../etc/passwd` resolved to `/private/etc/passwd`
+     * and was accepted too.
+     *
+     * 🔴 THE ESCAPE CHECK IS DELIBERATELY WIDER THAN THE `cs_dbg_*` PLANE'S, and the
+     * difference is the point rather than an inconsistency. `cs_dbg_launch` documents
+     * overriding `program` to debug a DIFFERENT .NET program, whose sources
+     * legitimately live outside the Godot project, so #166 kept an absolute path
+     * elsewhere legal. `dbg_launch` has no such mainline: its `scene` is `'main'`,
+     * `'current'` or a `res://` path, and Godot binds breakpoints only to scripts in
+     * the project it is running. An absolute path outside the root can never bind here
+     * whichever way it is spelled, so ALL THREE FORMS are anchored to the root.
+     * Absolute paths INSIDE the project stay legal — that form is documented, the probe
+     * uses it, and two over-eager mutations exist to keep it working.
+     *
+     * The comparison is against `root + path.sep`, never a bare `startsWith(root)`:
+     * the latter accepts a sibling directory that merely shares the root's name prefix.
+     */
+    const guardSource = (p) => resolveSourceFile(p, cfg.projectPath, GD_DAP_PATHS);
+    /**
+     * `scene` for `dbg_launch` / `dbg_restart`. See GD_DAP_SCENE for the measurement.
+     *
+     * 🔴 Returns the ORIGINAL SPELLING, never the resolved path. `res://demo/demo.tscn`
+     * and `<abs>/demo/demo.tscn` were both measured running the demo scene, so what
+     * reaches the adapter must not change — this guard only ever ADDS a refusal, which
+     * is what makes it behaviour-preserving on every spelling that already worked.
+     *
+     * 🔴 It also refuses BEFORE the port check and before the transport, deliberately:
+     * that is the property 162 §2 identified as making a guard measurable with no
+     * backend at all, and it is why the unit tests below need no editor. The one
+     * behaviour change is a call that has BOTH a bad scene and a bound bridge port —
+     * it now names the scene instead of the port. That is the more actionable of the
+     * two answers, and it is pinned by a test rather than left to chance.
+     */
+    const guardScene = (s) => {
+        if (s === undefined)
+            return;
+        if (SCENE_SENTINELS.has(s))
+            return;
+        if (s.startsWith("uid://"))
+            return;
+        resolveSourceFile(s, cfg.projectPath, GD_DAP_SCENE);
+    };
     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. " +
+        description: "Start the game under the debugger. scene may be 'main', 'current', a scene inside the project " +
+            "(res://, or an absolute path inside the root), or a uid:// reference. " +
+            "Refuses a scene outside the project root, one that does not exist, and an empty scene: measured on 4.7, " +
+            "the adapter ACCEPTS all of those and nothing runs — an out-of-project scene leaves a live sceneless game " +
+            "and a session that reports 'running' forever. A uid:// the project does not know is the one case still " +
+            "not caught: Godot silently runs the main scene instead, and resolving it needs the engine's UID map. " +
             "Any breakpoints set beforehand are applied during the handshake. " +
+            "Refuses if the debug adapter rejects the launch (e.g. Godot answers 'wrong_path' when the configured " +
+            "project path is not the one the editor has open) rather than reporting a session that never started. " +
+            "With stop_on_entry the result carries stop_on_entry_honored: Godot's adapter does not implement " +
+            "stopOnEntry, so it reports false plus a warning instead of a bare 'running'. " +
             "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"),
+            scene: z
+                .string()
+                .optional()
+                .describe("'main' (default), 'current', res://scene.tscn, or uid://… — must be inside the project"),
             stop_on_entry: z.boolean().optional().describe("Break at entry (default false)"),
             allow_port_conflict: z
                 .boolean()
@@ -72,6 +263,13 @@ export function registerDapTools(server, dap, cfg) {
                 "tools would talk to the process holding the port, not to this game."),
         },
     }, async ({ scene, stop_on_entry, allow_port_conflict }) => {
+        // Before the port check and before the transport — see guardScene.
+        try {
+            guardScene(scene);
+        }
+        catch (err) {
+            return fail(err);
+        }
         if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
             return {
                 isError: true,
@@ -79,12 +277,23 @@ export function registerDapTools(server, dap, cfg) {
             };
         }
         try {
-            await dap.start("launch", {
-                project: cfg.projectPath,
-                scene: scene ?? "main",
-                stopOnEntry: stop_on_entry ?? false,
-            });
-            return ok({ session_id: "godot", state: dap.state, scene: scene ?? "main" });
+            const { entryStopSeen } = await dap.start("launch", { project: cfg.projectPath, scene: scene ?? "main", stopOnEntry: stop_on_entry ?? false }, stop_on_entry ? ENTRY_STOP_WAIT_MS : 0);
+            const result = { session_id: "godot", state: dap.state, scene: scene ?? "main" };
+            if (stop_on_entry) {
+                // 🔴 Measured on Godot 4.7: stopOnEntry is ignored outright — the game ran to
+                // completion and printed its _ready() line while the tool answered a bare
+                // `running`, which reads exactly like a launch that simply had not stopped
+                // YET. Say which one it is.
+                result.stop_on_entry_honored = entryStopSeen;
+                if (!entryStopSeen) {
+                    result.warning =
+                        `The connected Godot debug adapter did not stop at entry within ${ENTRY_STOP_WAIT_MS}ms ` +
+                            `and the program is running. Godot's adapter does not implement stopOnEntry — set a ` +
+                            `breakpoint with dbg_set_breakpoints before dbg_launch to land a stop.`;
+                }
+            }
+            reportDroppedModifiers(result);
+            return ok(result);
         }
         catch (err) {
             return fail(err);
@@ -95,7 +304,9 @@ export function registerDapTools(server, dap, cfg) {
     // 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.",
+        description: "Attach to an already-running Godot debug session. Refuses if the adapter rejects the attach — " +
+            "Godot answers 'not_running' when nothing is running — instead of reporting state 'running' for a " +
+            "session that never started.",
         inputSchema: {
             address: z.string().optional().describe("Address of the running game (default 127.0.0.1)"),
             port: z.number().int().optional().describe("Remote debug port"),
@@ -103,7 +314,9 @@ export function registerDapTools(server, dap, cfg) {
     }, async ({ address, port }) => {
         try {
             await dap.start("attach", { address: address ?? "127.0.0.1", port });
-            return ok({ session_id: "godot", state: dap.state });
+            const result = { session_id: "godot", state: dap.state };
+            reportDroppedModifiers(result);
+            return ok(result);
         }
         catch (err) {
             return fail(err);
@@ -112,10 +325,15 @@ export function registerDapTools(server, dap, cfg) {
     server.registerTool("dbg_set_breakpoints", {
         title: "Set breakpoints",
         description: "Set (replace) the breakpoints for a source file. Applied immediately if a session is running, else buffered until launch. " +
+            "Refuses a source that can never bind: a missing file, a directory, an empty path (which resolves to the project root), " +
+            "or a path resolving outside the Godot project root — Godot binds breakpoints only to scripts in the project it runs, so " +
+            "unlike cs_dbg_set_breakpoints an absolute path outside the root is refused here too. " +
             "Feature-detected: the per-line conditions / hit_conditions / log_messages modifiers are only sent when the connected adapter " +
             "advertises support (supportsConditionalBreakpoints / supportsHitConditionalBreakpoints / supportsLogPoints). On an adapter that " +
-            "advertises them unsupported (e.g. Godot 4.3, which ignores them and would otherwise halt unconditionally) the modifier is dropped " +
-            "and the result includes `unsupported_modifiers` plus a `warning`. Detection needs a live session, so set modifiers after dbg_launch.",
+            "advertises them unsupported (Godot advertises all three false and IGNORES them, so the breakpoint would halt unconditionally) the " +
+            "modifier is dropped and the result includes `unsupported_modifiers` plus a `warning`. Detection happens when the breakpoints are " +
+            "applied, so it covers buffered ones too: setting modifiers before a session exists returns `modifier_detection: \"deferred\"` with a " +
+            "warning, and dbg_launch then reports the `unsupported_modifiers` actually dropped during the handshake.",
         inputSchema: {
             path: z.string().describe("Script path (res://..., absolute, or project-relative)"),
             lines: z.array(z.number().int().positive()).describe("1-based line numbers"),
@@ -125,28 +343,29 @@ export function registerDapTools(server, dap, cfg) {
         },
     }, async ({ path, lines, conditions, hit_conditions, log_messages }) => {
         try {
-            const fsPath = toFsPath(path, cfg.projectPath);
-            // Feature-detect the per-line modifiers against the connected adapter. When it does
-            // not advertise support (Godot 4.3 advertises none AND ignores them, so the
-            // breakpoint would halt unconditionally), DROP the field and warn rather than send
-            // something the adapter mishandles.
-            const dropped = unsupportedBreakpointModifiers(dap.capabilities, {
-                condition: hasModifier(conditions),
-                hitCondition: hasModifier(hit_conditions),
-                logMessage: hasModifier(log_messages),
-            });
-            const drop = new Set(dropped);
-            const body = await dap.setBreakpoints(fsPath, lines, drop.has("condition") ? undefined : conditions, drop.has("hitCondition") ? undefined : hit_conditions, drop.has("logMessage") ? undefined : log_messages);
+            const fsPath = guardSource(path);
+            // The client feature-detects and drops at apply time — on this call when a session
+            // is live, during the handshake when the breakpoint is buffered.
+            const before = new Set(dap.droppedBreakpointModifiers());
+            const body = await dap.setBreakpoints(fsPath, lines, conditions, hit_conditions, log_messages);
             const verified = Array.isArray(body["breakpoints"])
                 ? body["breakpoints"].map((b) => ({ line: b.line ?? 0, verified: Boolean(b.verified) }))
                 : [];
             const result = { path: fsPath, buffered: body["buffered"] === true, breakpoints: verified };
+            const dropped = dap.droppedBreakpointModifiers().filter((d) => !before.has(d));
             if (dropped.length) {
                 result.unsupported_modifiers = dropped;
+                result.warning = warnDropped(dropped);
+            }
+            else if (body["modifier_detection_deferred"] === true) {
+                // 🔴 Buffered with modifiers and no session yet: the honest answer is "not yet
+                // known", never silence. dbg_launch reports what was actually dropped.
+                result.modifier_detection = "deferred";
                 result.warning =
-                    `The connected Godot debug adapter does not support ${dropped.join(", ")} on breakpoints (it advertises ` +
-                        `${dropped.length > 1 ? "them" : "it"} unsupported), so ${dropped.length > 1 ? "they were" : "it was"} dropped — ` +
-                        `the affected breakpoint(s) will halt unconditionally.`;
+                    "These breakpoints are buffered until launch, so the adapter has not advertised its capabilities yet and the " +
+                        "conditions / hit_conditions / log_messages modifiers COULD NOT be feature-detected. Godot ignores modifiers it " +
+                        "does not support, which makes such a breakpoint halt unconditionally. dbg_launch reports `unsupported_modifiers` " +
+                        "for whatever is dropped when these are applied.";
             }
             return ok(result);
         }
@@ -161,6 +380,7 @@ export function registerDapTools(server, dap, cfg) {
         inputSchema: {},
     }, async () => {
         try {
+            requireSession("dbg_continue");
             const r = await dap.resume("continue", { threadId: dap.threadId() }, RESUME_WAIT_MS);
             return ok({ state: r.state, stopped_reason: r.reason });
         }
@@ -175,6 +395,7 @@ export function registerDapTools(server, dap, cfg) {
         inputSchema: { kind: z.enum(["in", "over", "out"]).describe("Step kind") },
     }, async ({ kind }) => {
         try {
+            requireSession("dbg_step");
             const command = kind === "in" ? "stepIn" : kind === "out" ? "stepOut" : "next";
             const r = await dap.resume(command, { threadId: dap.threadId() }, RESUME_WAIT_MS);
             return ok({ state: r.state, stopped_reason: r.reason });
@@ -189,6 +410,7 @@ export function registerDapTools(server, dap, cfg) {
         inputSchema: { levels: z.number().int().positive().optional().describe("Max frames (default 20)") },
     }, async ({ levels }) => {
         try {
+            requireSession("dbg_stack_trace");
             const body = await dap.request("stackTrace", { threadId: dap.threadId(), startFrame: 0, levels: levels ?? 20 });
             const frames = Array.isArray(body["stackFrames"])
                 ? body["stackFrames"].map((f) => ({
@@ -207,6 +429,7 @@ export function registerDapTools(server, dap, cfg) {
         inputSchema: { frame_id: z.number().int().describe("Frame id from dbg_stack_trace") },
     }, async ({ frame_id }) => {
         try {
+            requireSession("dbg_scopes");
             const body = await dap.request("scopes", { frameId: frame_id });
             const scopes = Array.isArray(body["scopes"])
                 ? body["scopes"].map((s) => ({ name: s.name ?? "", variables_ref: s.variablesReference ?? 0 }))
@@ -223,6 +446,7 @@ export function registerDapTools(server, dap, cfg) {
         inputSchema: { variables_ref: z.number().int().describe("variablesReference from dbg_scopes or a parent variable") },
     }, async ({ variables_ref }) => {
         try {
+            requireSession("dbg_variables");
             const body = await dap.request("variables", { variablesReference: variables_ref });
             const variables = Array.isArray(body["variables"])
                 ? body["variables"].map((v) => ({
@@ -245,6 +469,9 @@ export function registerDapTools(server, dap, cfg) {
         },
     }, async ({ expression, frame_id, confirm }) => {
         try {
+            // Before the gate on purpose: the old order prompted the operator to approve
+            // arbitrary code execution against a session that had never been started.
+            requireSession("dbg_evaluate");
             const blocked = await gate(server, confirm, `Evaluate expression in the running game: ${expression}`);
             if (blocked)
                 return blocked;
@@ -285,6 +512,7 @@ export function registerDapTools(server, dap, cfg) {
         },
     }, async ({ add, remove, clear, frame_id }) => {
         try {
+            requireSession("dbg_watch");
             if (clear)
                 dap.clearWatches();
             if (remove && remove.length)
@@ -352,6 +580,8 @@ export function registerDapTools(server, dap, cfg) {
         },
     }, async ({ variables_ref, name, value, confirm }) => {
         try {
+            // Before the gate and the caps check on purpose — see dbg_evaluate.
+            requireSession("dbg_set_variable");
             // Feature-detect: some debug adapters don't implement setVariable. If the
             // adapter explicitly advertised it as unsupported, say so plainly instead
             // of prompting for a confirmation and then failing.
@@ -400,13 +630,25 @@ export function registerDapTools(server, dap, cfg) {
         description: "Restart the current debug session. Uses the DAP `restart` request when the adapter advertises `supportsRestartRequest`, " +
             "otherwise falls back to terminate + relaunch — so it works on every adapter. Reuses the last dbg_launch/dbg_attach parameters; " +
             "pass `scene` / `stop_on_entry` to override them for a launched session. `method` in the result reports which path ran " +
-            "('restart' = native DAP restart, 'relaunch' = terminate + fresh handshake). Requires a session started with dbg_launch/dbg_attach.",
+            "('restart' = native DAP restart, 'relaunch' = terminate + fresh handshake). Requires a session started with dbg_launch/dbg_attach. " +
+            "`scene` is held to the same rule as dbg_launch's — inside the project root, existing, non-empty.",
         inputSchema: {
-            scene: z.string().optional().describe("Override the scene for a launched session: 'main', 'current', or res://scene.tscn"),
+            scene: z
+                .string()
+                .optional()
+                .describe("Override the scene for a launched session: 'main', 'current', res://scene.tscn, or uid://…"),
             stop_on_entry: z.boolean().optional().describe("Override stop-at-entry for the restart (launched sessions)"),
         },
     }, async ({ scene, stop_on_entry }) => {
         try {
+            // 🔴 THE SECOND CALL SITE, and the reason it is here. 162 §8 item 5 named
+            // `dbg_launch` alone; `dbg_restart` takes the same `scene` and hands it to the
+            // same adapter, so guarding only the first would have left the plane guarded
+            // in name only. Measured before it was written: an unguarded `dbg_restart`
+            // onto `res://../example_evil/outside.tscn` answered
+            // `ok {"method":"restart","state":"running"}`, exactly like `dbg_launch`.
+            // §7's standing rule — a guard is not wired until EVERY call site is wired.
+            guardScene(scene);
             const override = {};
             if (scene !== undefined)
                 override.scene = scene;
@@ -425,6 +667,8 @@ export function registerDapTools(server, dap, cfg) {
             "list the valid goto targets on that line; when the line has exactly one target (or you pass `target_id`) it jumps there. " +
             "DESTRUCTIVE: skips or repeats code by moving execution — confirm with the user and keep this gated. " +
             "Feature-detected: on an adapter that does not advertise `supportsGotoTargetsRequest` it returns a clear \"unsupported\" message WITHOUT prompting. " +
+            "Refuses a source that can never carry a target — a missing file, a directory, an empty path (which resolves to the project root), " +
+            "or a path resolving outside the Godot project root — the same guard dbg_set_breakpoints applies. " +
             "Only meaningful while stopped at a breakpoint.",
         inputSchema: {
             path: z.string().describe("Script path (res://..., absolute, or project-relative)"),
@@ -440,7 +684,20 @@ export function registerDapTools(server, dap, cfg) {
                     content: [{ type: "text", text: "dbg_goto is unsupported by the connected Godot build's debug adapter (it does not advertise supportsGotoTargetsRequest)." }],
                 };
             }
-            const fsPath = toFsPath(path, cfg.projectPath);
+            // 🔴 162: THIS GUARD WAS MISSING, and only a measurement found it. 161 §8 item 5
+            // described dap.ts as carrying "its own inline copy of the escape guard" — true
+            // of ONE of its two path-taking tools. `dbg_goto` resolved with a bare
+            // `toFsPath` and handed the result to the adapter as `source.path`: no
+            // containment check, no existence check. The same shape as 161 §4's "only
+            // board_create's stale-tab close was asserted, and one of four creators was
+            // covered" — a guard is not wired until every call site is wired.
+            //
+            // 🔴 It is not currently REACHABLE on Godot: the capability gate above returns
+            // first because no Godot build advertises supportsGotoTargetsRequest. That is a
+            // capability, not a boundary — it can change under us, and `dbg_goto` is the
+            // DESTRUCTIVE tool on this plane. Guarded on its own merits, not on the engine's
+            // current answer.
+            const fsPath = guardSource(path);
             const body = await dap.request("gotoTargets", { source: { path: fsPath }, line });
             const targets = Array.isArray(body["targets"])
                 ? body["targets"].map((t) => ({ id: t.id ?? 0, label: t.label ?? "", line: t.line ?? 0 }))

package/dist/tools/editor/audio.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { gate } from "../../confirm.js";
 /** AudioStreamPlayer nodes + audio bus layout / effects. */
-export function registerAudioTools(server, call) {
+export function registerAudioTools(server, call, guard) {
     server.registerTool("audio_player_create", {
         title: "Create audio player",
         description: "Add an AudioStreamPlayer / AudioStreamPlayer2D / AudioStreamPlayer3D node under a parent in the edited scene (undoable). `dim` selects \"none\" (default, non-positional AudioStreamPlayer), \"2d\", or \"3d\". Optional initial stream_path (res:// AudioStream), autoplay, volume_db, bus. In-scene and undoable — not gated.",
@@ -15,6 +15,9 @@ export function registerAudioTools(server, call) {
             bus: z.string().optional().describe("Target audio bus name (default \"Master\")"),
         },
     }, async ({ parent_path, dim, name, stream_path, autoplay, volume_db, bus }) => {
+        const escaped = guard(stream_path, "stream_path");
+        if (escaped)
+            return escaped;
         const params = { parent_path };
         if (dim !== undefined)
             params.dim = dim;
@@ -37,7 +40,12 @@ export function registerAudioTools(server, call) {
             path: z.string().describe("AudioStreamPlayer/2D/3D node path relative to the scene root"),
             stream_path: z.string().describe("res:// path to an AudioStream resource"),
         },
-    }, async ({ path, stream_path }) => call("audio.set_stream", { path, stream_path }));
+    }, async ({ path, stream_path }) => {
+        const escaped = guard(stream_path, "stream_path");
+        if (escaped)
+            return escaped;
+        return call("audio.set_stream", { path, stream_path });
+    });
     server.registerTool("audio_bus_add", {
         title: "Add audio bus",
         description: "Add a bus to the project's global AudioServer layout, optionally naming it, positioning it (at_position), and setting its send bus. DESTRUCTIVE (project-wide audio state) — gated by confirmation.",
@@ -100,6 +108,12 @@ export function registerAudioTools(server, call) {
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ to_path, confirm }) => {
+        // `to_path` is OPTIONAL here — an omitted one takes the addon's documented
+        // default and has nothing to escape, which is why the guard passes `undefined`
+        // through untouched rather than refusing it.
+        const escaped = guard(to_path, "to_path");
+        if (escaped)
+            return escaped;
         const blocked = await gate(server, confirm, `Save audio bus layout to ${to_path ?? "res://default_bus_layout.tres"}`);
         if (blocked)
             return blocked;

package/dist/tools/editor/common.js

@@ -1,4 +1,5 @@
-import { ok } from "../lsp-common.js";
+import { ok, failPath } from "../lsp-common.js";
+import { resolveInsideProject } from "../../paths.js";
 /**
  * MCP error envelope for a failed editor-bridge call (never throws to the
  * caller). Distinct from lsp-common's `fail` (which labels errors "LSP error");
@@ -28,4 +29,41 @@ export function makeCall(bridge) {
         }
     };
 }
+// ------------------------------------------------------------ path guard ----
+//
+// MEASURED, session 164, against a real 4.7 editor with the addon live, on a temp
+// project copy at /private/tmp/g164 with a prefix-sharing sibling `example_evil/`:
+// ELEVEN editor writers created files OUTSIDE the project root through `res://../`,
+// and `filesystem_move` MOVED one out. Every one answered `ok` and echoed the
+// escaping path straight back. The verdict came from `stat`, not from the reply —
+// 163 §1's lesson, which is that an ACCEPTANCE is only measured by asking a channel
+// the tool does not control.
+//
+// 🔴 THE ADDON'S ONLY CHECK IS `to_path.begins_with("res://")`, at seventeen call
+// sites in operations.gd, and `res://../` satisfies it. That is why a bare relative
+// and an absolute path are already refused (self-announcing) while `res://../` was
+// silent. This guard closes the silent one; it does not touch the other two.
+/**
+ * Build the containment guard the editor writers share. Returns `null` when the
+ * path is legal and a ready-to-return error envelope when it escapes, so a call
+ * site reads as one line and cannot forget the `return`.
+ *
+ * 🔴 IT RETURNS NOTHING AND REWRITES NOTHING. The caller's ORIGINAL spelling still
+ * goes on the wire, so `res://foo.tres` reaches the addon exactly as before and the
+ * guard is provably inert on every path that already worked — the same property
+ * 163's `guardScene` was built for, and an over-eager mutation keeps it that way.
+ */
+export function makePathGuard(projectPath) {
+    return (p, label) => {
+        if (p === undefined)
+            return null; // an absent optional param has nothing to escape
+        try {
+            resolveInsideProject(p, projectPath, label);
+            return null;
+        }
+        catch (err) {
+            return failPath(err);
+        }
+    };
+}
 //# sourceMappingURL=common.js.map