breakpoint-mcp 1.28.0 → 1.72.7

package/dist/tools/tabletop.js

@@ -1,6 +1,7 @@
+import fs from "node:fs";
 import { z } from "zod";
 import { gate } from "../confirm.js";
-import { toFsPath, readFileText } from "../paths.js";
+import { readFileText, resolveExistingFile, resolveInsideProject, resolveWriteTarget } from "../paths.js";
 /**
  * Group N — Card / board / piece authoring composites (`card_*`, and later
  * `board_*` / `piece_*` / `interact_*`).
@@ -550,9 +551,13 @@ export async function emitDeckFromTable(emit, readFile, args) {
     const base = sceneRootName(args.template_path);
     const face_up = args.face_up ?? true;
     const format = args.format ?? (args.table_path.toLowerCase().endsWith(".json") ? "json" : "csv");
+    // The reader seam guarantees the file EXISTS and is a regular file inside the
+    // project root (see resolveExistingFile), so "" here means one thing only: a
+    // real, reachable, zero-byte table. It used to mean four things at once and
+    // reported the wrong one for three of them.
     const text = readFile(args.table_path);
     if (text === "")
-        throw new ComposeError("not_found", `Cannot read table ${args.table_path} (does it exist?)`);
+        throw new ComposeError("empty_table", `Table ${args.table_path} is empty (0 bytes) — there are no rows to stamp.`);
     const allRows = readTableRows(text, format);
     const rows_read = allRows.length;
     const header = new Set();
@@ -1361,7 +1366,70 @@ export async function emitAddDropZone(emit, args) {
 // ------------------------------------------------------------- registration ----
 export function registerTabletopTools(server, bridge, config) {
     const emit = (method, params) => bridge.request(method, params);
-    const readFile = (p) => readFileText(toFsPath(p, config.projectPath));
+    // The reader REFUSES a path that escapes the project root, and separates
+    // "missing" / "a directory" / "the project root" from "an empty file" —
+    // `readFileText` alone answered "" to all four and the caller was told
+    // "does it exist?" for three things that did.
+    const readFile = (p) => readFileText(resolveExistingFile(p, config.projectPath, "table_path"));
+    /**
+     * Guard a caller-supplied res:// scene/script target before anything is
+     * written: refuse a path that escapes the root, refuse an existing target
+     * unless `overwrite`, and — when overwriting — close a stale editor tab.
+     *
+     * That last step is not defensive. The addon's `scene.new` saves a fresh
+     * single-root scene to `path` and then calls
+     * `EditorInterface.open_scene_from_path(path)`. When that scene is ALREADY
+     * OPEN the editor switches to the existing tab, whose in-memory tree is the
+     * OLD one — so every `node.add` that follows lands on top of it and the save
+     * writes both trees. Measured (session 161): a second `board_create` against
+     * the same path took a 5-node scene to 9, reported `saved: true` and a
+     * `node_count` of 5, and never mentioned the four orphans it had just made.
+     */
+    function guardWriteTarget(p, overwrite, label) {
+        resolveWriteTarget(p, config.projectPath, { overwrite, label });
+    }
+    /**
+     * The second half, run only AFTER the confirmation gate has been cleared —
+     * closing a scene tab is a visible side effect and must not happen on a call
+     * the caller then declines.
+     */
+    async function clearStaleTab(p) {
+        // Unconditional, and deliberately NOT gated on "the file exists": the stale
+        // tab is the editor's, not the disk's. Measured — deleting the .tscn out
+        // from under an OPEN editor tab still produced an append, because
+        // open_scene_from_path reuses the tab whatever the disk says. Keying the
+        // close on `exists` would have left that case open; keying it on "is this
+        // scene open" closes the whole class.
+        const open = await emit("scene.list_open", {});
+        const scenes = Array.isArray(open?.scenes) ? open.scenes.map(String) : [];
+        if (!scenes.includes(p))
+            return; // not open: scene.new reopens it fresh from disk
+        if (open?.current !== p) {
+            // Only the CURRENT scene can be closed, so a non-current target has to be
+            // made current first — and `scene.open` needs the file to still be there.
+            // A scene whose file was deleted from under the editor cannot be reached
+            // this way; skip rather than turn a create into "Scene not found". That
+            // residual case needs someone to delete a .tscn behind the editor's back,
+            // which no tool in this surface does.
+            if (!fs.existsSync(resolveInsideProject(p, config.projectPath, "path")))
+                return;
+            await emit("scene.open", { path: p });
+        }
+        try {
+            await emit("scene.close", { path: p });
+        }
+        catch (err) {
+            // EditorInterface.close_scene is Godot 4.4+; the addon answers
+            // "unsupported" below that. Refuse rather than proceed — proceeding is
+            // exactly the silent append this guard exists to stop.
+            if (err?.code === "unsupported") {
+                throw new ComposeError("overwrite_unsupported", `Cannot overwrite ${p}: it is open in the editor, and closing a scene requires Godot 4.4+. ` +
+                    `Close that scene tab by hand and retry, or write to a different path. Overwriting an OPEN ` +
+                    `scene without closing it appends to the stale tab instead of replacing it.`);
+            }
+            throw err;
+        }
+    }
     const slotSchema = z.object({
         name: z.string().describe("Slot key used by card_instance / card_deck_from_table data (e.g. title, cost, body, art)"),
         kind: z.enum(["label", "rich_text", "texture", "panel", "badge"]).describe("label→Label, rich_text→RichTextLabel, texture→TextureRect, panel→Panel, badge→Label-in-Panel"),
@@ -1411,7 +1479,7 @@ export function registerTabletopTools(server, bridge, config) {
                 }).optional(),
             }).optional().describe("Inline theme built via theme_create + theme_set_*"),
             script_path: z.string().optional().describe("Generated card script path (default derives from `path`)"),
-            overwrite: z.boolean().optional().describe("Overwrite an existing template at `path` (default false)"),
+            overwrite: z.boolean().optional().describe("Replace an existing template at `path` (default false). With overwrite omitted or false an existing `path` is REFUSED (`exists`) rather than written — before 1.39.0 this flag was declared and never read, and a repeat call APPENDED to the existing scene while reporting success. With overwrite:true the scene is replaced, which requires closing it first if it is open in the editor (Godot 4.4+; below that an open target is refused rather than appended to)."),
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async (raw) => {
@@ -1420,10 +1488,30 @@ export function registerTabletopTools(server, bridge, config) {
             return fail({ code: "bad_params", message: "'path' must be a res:// .tscn path" });
         if (a.theme_path && a.theme)
             return fail({ code: "bad_params", message: "Pass either theme_path or an inline theme, not both" });
+        try {
+            guardWriteTarget(a.path, a.overwrite, "path");
+            if (a.script_path !== undefined)
+                resolveInsideProject(a.script_path, config.projectPath, "script_path");
+            if (a.theme_path !== undefined)
+                resolveInsideProject(a.theme_path, config.projectPath, "theme_path");
+            // 🔴 NESTED. `back.art` and `theme.font_path` live ONE LEVEL DOWN in the schema,
+            // which is why no enumeration this project ever ran could see them: enum163 walks
+            // TOP-LEVEL `inputSchema.properties` only. Measured — `back.art` was written
+            // VERBATIM into the saved scene, and `theme.font_path` LOADED a font from outside
+            // the root through all three spellings.
+            if (a.back?.art !== undefined)
+                resolveInsideProject(a.back.art, config.projectPath, "back.art");
+            if (a.theme?.font_path !== undefined)
+                resolveInsideProject(a.theme.font_path, config.projectPath, "theme.font_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, a.confirm, `Create card template scene + script at ${a.path}`);
         if (blocked)
             return blocked;
         try {
+            await clearStaleTab(a.path);
             return ok(await emitCardTemplate(emit, a));
         }
         catch (err) {
@@ -1446,6 +1534,12 @@ export function registerTabletopTools(server, bridge, config) {
         },
     }, async (raw) => {
         const a = raw;
+        try {
+            resolveInsideProject(a.template_path, config.projectPath, "template_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         try {
             return ok(await emitCardInstance(emit, a));
         }
@@ -1471,6 +1565,12 @@ export function registerTabletopTools(server, bridge, config) {
         },
     }, async (raw) => {
         const a = raw;
+        try {
+            resolveInsideProject(a.template_path, config.projectPath, "template_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         try {
             return ok(await emitCardHand(emit, a));
         }
@@ -1508,6 +1608,15 @@ export function registerTabletopTools(server, bridge, config) {
         },
     }, async (raw) => {
         const a = raw;
+        // 🔴 `table_path` has been guarded since #173 (`resolveExistingFile`, via
+        // `readFile`); `template_path` on the SAME CALL was not. Fourth session running
+        // where the interesting defect is the second parameter on a guarded tool.
+        try {
+            resolveInsideProject(a.template_path, config.projectPath, "template_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         try {
             return ok(await emitDeckFromTable(emit, readFile, a));
         }
@@ -1579,17 +1688,27 @@ export function registerTabletopTools(server, bridge, config) {
                 art: z.string().optional().describe("res:// texture background (Sprite2D under Node2D, TextureRect under Control)"),
                 size: z.object({ w: z.number().optional(), h: z.number().optional() }).optional().describe("Background size in px (ColorRect / TextureRect)"),
             }).optional().describe("Optional background drawn behind the cells"),
-            overwrite: z.boolean().optional().describe("Overwrite an existing board at `path` (default false)"),
+            overwrite: z.boolean().optional().describe("Replace an existing board at `path` (default false). With overwrite omitted or false an existing `path` is REFUSED (`exists`) rather than written — before 1.39.0 this flag was declared and never read, and a repeat call APPENDED to the existing scene while reporting success. With overwrite:true the scene is replaced, which requires closing it first if it is open in the editor (Godot 4.4+; below that an open target is refused rather than appended to)."),
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async (raw) => {
         const a = raw;
         if (!a.path.startsWith("res://") || !a.path.endsWith(".tscn"))
             return fail({ code: "bad_params", message: "'path' must be a res:// .tscn path" });
+        try {
+            guardWriteTarget(a.path, a.overwrite, "path");
+            // 🔴 NESTED — `background.art` is stored verbatim in the saved board scene.
+            if (a.background?.art !== undefined)
+                resolveInsideProject(a.background.art, config.projectPath, "background.art");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, a.confirm, `Create board scene at ${a.path}`);
         if (blocked)
             return blocked;
         try {
+            await clearStaleTab(a.path);
             return ok(await emitBoardCreate(emit, a));
         }
         catch (err) {
@@ -1633,7 +1752,7 @@ export function registerTabletopTools(server, bridge, config) {
                 atlas_coords: z.array(z.number().int()).length(2).optional().describe("Tile atlas coordinates [x, y] within the source (default [0, 0])"),
             }).optional().describe("Fill the whole grid with one tile (needs an existing `tileset` that has the source); omitted → cells stay empty (a coordinate frame only)"),
             layer_name: z.string().optional().describe("TileMapLayer node name (default \"Cells\")"),
-            overwrite: z.boolean().optional().describe("Overwrite an existing board at `path` (default false)"),
+            overwrite: z.boolean().optional().describe("Replace an existing board at `path` (default false). With overwrite omitted or false an existing `path` is REFUSED (`exists`) rather than written — before 1.39.0 this flag was declared and never read, and a repeat call APPENDED to the existing scene while reporting success. With overwrite:true the scene is replaced, which requires closing it first if it is open in the editor (Godot 4.4+; below that an open target is refused rather than appended to)."),
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async (raw) => {
@@ -1642,10 +1761,21 @@ export function registerTabletopTools(server, bridge, config) {
             return fail({ code: "bad_params", message: "'path' must be a res:// .tscn path" });
         if (a.tileset !== undefined && !(a.tileset.startsWith("res://") && a.tileset.endsWith(".tres")))
             return fail({ code: "bad_params", message: "'tileset' must be a res:// .tres path" });
+        try {
+            guardWriteTarget(a.path, a.overwrite, "path");
+            // A supplied tileset is READ, not written — but `res://../x.tres` would
+            // reach outside the root just the same, so it is resolved too.
+            if (a.tileset !== undefined)
+                resolveInsideProject(a.tileset, config.projectPath, "tileset");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, a.confirm, `Create tile-backed board scene at ${a.path}`);
         if (blocked)
             return blocked;
         try {
+            await clearStaleTab(a.path);
             return ok(await emitBoardTileCreate(emit, a));
         }
         catch (err) {
@@ -1696,17 +1826,35 @@ export function registerTabletopTools(server, bridge, config) {
                 color: z.string().regex(/^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/).optional().describe("Solid ColorRect back colour"),
             }).optional().describe("Optional back state; its presence makes the piece two-sided"),
             script_path: z.string().optional().describe("Generated piece script path (default derives from `path`)"),
-            overwrite: z.boolean().optional().describe("Overwrite an existing template at `path` (default false)"),
+            overwrite: z.boolean().optional().describe("Replace an existing template at `path` (default false). With overwrite omitted or false an existing `path` is REFUSED (`exists`) rather than written — before 1.39.0 this flag was declared and never read, and a repeat call APPENDED to the existing scene while reporting success. With overwrite:true the scene is replaced, which requires closing it first if it is open in the editor (Godot 4.4+; below that an open target is refused rather than appended to)."),
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async (raw) => {
         const a = raw;
         if (!a.path.startsWith("res://") || !a.path.endsWith(".tscn"))
             return fail({ code: "bad_params", message: "'path' must be a res:// .tscn path" });
+        try {
+            guardWriteTarget(a.path, a.overwrite, "path");
+            if (a.script_path !== undefined)
+                resolveInsideProject(a.script_path, config.projectPath, "script_path");
+            // 🔴 `art` is STORED, not loaded: the escaping path was written verbatim into
+            // the generated .tscn, so the template carried a reference out of the project.
+            if (a.art !== undefined)
+                resolveInsideProject(a.art, config.projectPath, "art");
+            // 🔴 AND ITS NESTED TWIN. #173 guarded `art` and left `back.art` open, because the
+            // enumerator that scoped that work could not see one level down. Same defect,
+            // same tool, three sessions apart — measured storing the escaping path verbatim.
+            if (a.back?.art !== undefined)
+                resolveInsideProject(a.back.art, config.projectPath, "back.art");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, a.confirm, `Create piece template scene + script at ${a.path}`);
         if (blocked)
             return blocked;
         try {
+            await clearStaleTab(a.path);
             return ok(await emitPieceTemplate(emit, a));
         }
         catch (err) {
@@ -1734,6 +1882,12 @@ export function registerTabletopTools(server, bridge, config) {
         },
     }, async (raw) => {
         const a = raw;
+        try {
+            resolveInsideProject(a.template_path, config.projectPath, "template_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         try {
             return ok(await emitPieceInstance(emit, a));
         }
@@ -1790,6 +1944,12 @@ export function registerTabletopTools(server, bridge, config) {
         const a = raw;
         if (!a.script_path.startsWith("res://") || !a.script_path.endsWith(".gd"))
             return fail({ code: "bad_params", message: "'script_path' must be a res:// .gd path" });
+        try {
+            resolveInsideProject(a.script_path, config.projectPath, "script_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, a.confirm, `Make ${a.node} draggable (writes script ${a.script_path})`);
         if (blocked)
             return blocked;
@@ -1827,6 +1987,12 @@ export function registerTabletopTools(server, bridge, config) {
         const a = raw;
         if (!a.script_path.startsWith("res://") || !a.script_path.endsWith(".gd"))
             return fail({ code: "bad_params", message: "'script_path' must be a res:// .gd path" });
+        try {
+            resolveInsideProject(a.script_path, config.projectPath, "script_path");
+        }
+        catch (err) {
+            return fail(err);
+        }
         const blocked = await gate(server, a.confirm, `Add a drop zone on ${a.node} (writes script ${a.script_path})`);
         if (blocked)
             return blocked;

package/dist/tools/vcs.js

@@ -57,6 +57,30 @@ function gitFail(r) {
         content: [{ type: "text", text: `git error${r.code != null ? ` [${r.code}]` : ""}: ${msg}${hint}` }],
     };
 }
+/**
+ * The paths from a `git ... --name-only` run, in git's own order and dropping the
+ * trailing blank. Used by `vcs_restore` to MEASURE what changed rather than echo what
+ * was requested — see the comment at its handler for why that distinction is the whole
+ * point (D5, 155 §2; the same family as #181, #183 and #188).
+ */
+function nameOnly(stdout) {
+    return stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * Classify a `vcs_restore` run from the two readings around it.
+ *
+ * 🔴 A PURE FUNCTION TAKING ITS POPULATIONS AS PARAMETERS, AND THAT IS THE POINT
+ * (173 §6, whose own reverse sweep caught the same shape in the commit written to fix
+ * that session). Inlined in the handler, `stranded` could only ever be built from what
+ * a real `git restore` produces — which, when it works, is always the empty list. A
+ * collector you only ever assert is EMPTY is a collector nobody has proved collects,
+ * so the collapse case has to be constructible without git's cooperation.
+ */
+export function restoreOutcome(rels, wasDirty, stillDirty) {
+    const stuck = new Set(stillDirty);
+    const restored = wasDirty.filter((p) => !stuck.has(p));
+    return { restored, count: restored.length, requested: rels, stranded: [...stuck] };
+}
 /**
  * Truncate long text so a single tool result stays reasonable; report whether it
  * was cut. Keeps the HEAD (not the tail): for a patch the first changed files and
@@ -219,44 +243,68 @@ export function registerVcsTools(server, cfg) {
     server.registerTool("vcs_branch_list", {
         title: "Git branches",
         description: "List branches with their short object name and a flag for the current branch. Local only by default; " +
-            "set remotes=true to include remote-tracking branches. Read-only.",
+            "set remotes=true to include remote-tracking branches (flagged remote=true). On a detached HEAD, " +
+            "`current` is null and `detached` is true — matching vcs_status — and no pseudo-branch is listed. " +
+            "Read-only.",
         inputSchema: {
             remotes: z.boolean().optional().describe("Include remote-tracking branches (default false)"),
         },
     }, async ({ remotes }) => {
-        const args = ["branch", "--no-color", `--format=%(refname:short)${UNIT}%(objectname:short)${UNIT}%(HEAD)`];
+        const args = [
+            "branch", "--no-color",
+            `--format=%(refname)${UNIT}%(refname:short)${UNIT}%(objectname:short)${UNIT}%(HEAD)`,
+        ];
         if (remotes)
             args.push("--all");
         const r = await git(cfg, args);
         if (!r.ok)
             return gitFail(r);
         let current = null;
+        let detached = false;
         const branches = r.stdout
             .split("\n")
             .filter(Boolean)
             .map((line) => {
-            const [name, short_sha, head] = line.split(UNIT);
+            const [full, name, short_sha, head] = line.split(UNIT);
             const isCurrent = head.trim() === "*";
+            // On a detached HEAD `git branch` emits a pseudo-entry whose refname is the
+            // literal "(HEAD detached at <sha>)" rather than refs/heads/… . It is NOT a
+            // branch — listing it as `current` contradicted vcs_status, which reports
+            // null for the same repo, and no vcs_switch could ever reach it.
+            if (!full.startsWith("refs/")) {
+                if (isCurrent)
+                    detached = true;
+                return null;
+            }
             if (isCurrent)
                 current = name;
-            return { name, short_sha, current: isCurrent, remote: name.startsWith("remotes/") };
-        });
-        return ok({ current, branches, count: branches.length });
+            // Discriminate off the FULL refname: `%(refname:short)` of a remote-tracking
+            // branch is "origin/main", never "remotes/origin/main", so the old
+            // name.startsWith("remotes/") test could never match and every branch came
+            // back remote=false — including under remotes=true, the flag's whole point.
+            return { name, short_sha, current: isCurrent, remote: full.startsWith("refs/remotes/") };
+        })
+            .filter((b) => b !== null);
+        return ok({ current, branches, count: branches.length, detached });
     });
     // ---- vcs_blame -----------------------------------------------------------
     server.registerTool("vcs_blame", {
         title: "Git blame",
         description: "Per-line last-change attribution for a file: for each line, the short commit, author, ISO date, and the " +
-            "line text. Optionally restrict to a [start,end] line range (1-based, inclusive). Read-only.",
+            "line text. Optionally restrict to a [start,end] line range (1-based, inclusive); either bound may be " +
+            "given alone (start alone runs to end-of-file). Read-only.",
         inputSchema: {
             path: z.string().describe("File to blame (res:// or repo-relative)"),
-            start: z.number().int().positive().optional().describe("First line (1-based, inclusive)"),
-            end: z.number().int().positive().optional().describe("Last line (1-based, inclusive)"),
+            start: z.number().int().positive().optional().describe("First line (1-based, inclusive). May be given without `end`."),
+            end: z.number().int().positive().optional().describe("Last line (1-based, inclusive). May be given without `start`."),
         },
     }, async ({ path, start, end }) => {
         const args = ["blame", "--line-porcelain"];
+        // An omitted end must be an EMPTY field: `-L 3,` blames line 3 to end-of-file.
+        // `$` is a `git log -L` form and `git blame` REJECTS it with usage exit 129, so
+        // the old `end ?? "$"` made every start-without-end call fail. Measured, not read.
         if (start != null || end != null)
-            args.push("-L", `${start ?? 1},${end ?? "$"}`);
+            args.push("-L", `${start ?? 1},${end ?? ""}`);
         args.push("--", toRepoPath(path));
         const r = await git(cfg, args);
         if (!r.ok)
@@ -322,7 +370,10 @@ export function registerVcsTools(server, cfg) {
         title: "Git restore (discard changes)",
         description: "Discard uncommitted working-tree changes to the given paths, restoring them from the index/HEAD " +
             "(`git restore -- <paths>`). DESTRUCTIVE — the discarded edits are unrecoverable — so it is " +
-            "elicitation-gated: pass confirm:true to bypass the prompt on clients that can't elicit.",
+            "elicitation-gated: pass confirm:true to bypass the prompt on clients that can't elicit. " +
+            "`restored` is MEASURED, not echoed: it lists only the paths git actually changed, so a path with " +
+            "nothing to discard is absent from it rather than reported as discarded work. `requested` carries " +
+            "what you asked for, and `stranded` names any path still dirty afterwards (a partial, not an error).",
         inputSchema: {
             paths: z.array(z.string()).min(1).describe("Paths to discard changes for (res:// or repo-relative)"),
             confirm: z.boolean().optional().describe("Skip the confirmation prompt"),
@@ -332,17 +383,44 @@ export function registerVcsTools(server, cfg) {
         const blocked = await gate(server, confirm, `Discard working-tree changes to: ${rels.join(", ")}`);
         if (blocked)
             return blocked;
+        // 🔴 D5 (155 §2), AND THE THIRD MEMBER OF #181/#183/#188's FAMILY: this used to
+        // return `restored: rels` — THE REQUEST, ECHOED. `git restore` exits 0 for a path
+        // with nothing to discard, so asking to discard five files of which one was dirty
+        // reported all five as restored, and the caller of a DESTRUCTIVE, gated tool was
+        // told it had thrown away work it had not touched. Every existing test restored a
+        // path that was dirty, so the clean-path branch had never run anywhere.
+        //
+        // What `git restore -- <paths>` discards is exactly the working-tree-vs-index
+        // diff, so that diff, read BEFORE and AFTER, is the measurement — not the request.
+        const before = await git(cfg, ["diff", "--name-only", "--", ...rels]);
+        if (!before.ok)
+            return gitFail(before);
+        const wasDirty = nameOnly(before.stdout);
         const r = await git(cfg, ["restore", "--", ...rels]);
         if (!r.ok)
             return gitFail(r);
-        return ok({ restored: rels, count: rels.length });
+        const after = await git(cfg, ["diff", "--name-only", "--", ...rels]);
+        if (!after.ok)
+            return gitFail(after);
+        // Three outcomes, and one list cannot carry them (#188's two booleans, as lists):
+        // a path that was dirty and is now clean was RESTORED; a path git still reports as
+        // dirty is STRANDED; and `requested` stays available so a caller can see that the
+        // other paths had nothing to discard rather than having to infer it.
+        //
+        // A stranded path is a PARTIAL, not an error — deliberately, and for #188 §7's
+        // reason inverted: work WAS discarded for the other paths, and `_err` would claim
+        // nothing happened, which is the same misdescription pointing the other way.
+        return ok(restoreOutcome(rels, wasDirty, nameOnly(after.stdout)));
     });
     // ---- vcs_stash — push/pop/list ungated; drop GATED (destroys an entry) ----
     server.registerTool("vcs_stash", {
         title: "Git stash",
         description: "Manage stashes: op='push' saves and reverts your working changes (optional message); 'pop' " +
             "re-applies the latest stash; 'list' returns the stash entries; 'drop' deletes a stash entry. " +
-            "Only 'drop' is destructive and elicitation-gated (confirm:true bypasses); push/pop/list are not.",
+            "Only 'drop' is destructive and elicitation-gated (confirm:true bypasses); push/pop/list are not. " +
+            "op='push' ERRORS when nothing was stashed (no tracked file has uncommitted changes) rather than " +
+            "reporting success — a success there would tell you work is parked when it is not. Untracked files " +
+            "are never stashed.",
         inputSchema: {
             op: z.enum(["push", "pop", "list", "drop"]).describe("Stash operation"),
             message: z.string().optional().describe("Message for op='push'"),
@@ -370,20 +448,45 @@ export function registerVcsTools(server, cfg) {
                 return gitFail(r);
             return ok({ op, message: r.stdout.trim() || "dropped", stashes: [] });
         }
-        // push / pop
-        const args = op === "push"
-            ? ["stash", "push", ...(message ? ["-m", message] : [])]
-            : ["stash", "pop", ...(ref ? [ref] : [])];
-        const r = await git(cfg, args);
+        if (op === "push") {
+            // `git stash push` EXITS 0 printing "No local changes to save" when there is
+            // nothing to stash. Passing that through as success is the worst shape this
+            // family has: the caller believes their work is safely parked and may then
+            // switch or restore over it. Decide on refs/stash BEFORE vs AFTER rather than
+            // on git's wording, which is not a stable interface across versions.
+            // Note untracked-only trees stash NOTHING here (no -u) — measured.
+            const before = await git(cfg, ["rev-parse", "--quiet", "--verify", "refs/stash"]);
+            const r = await git(cfg, ["stash", "push", ...(message ? ["-m", message] : [])]);
+            if (!r.ok)
+                return gitFail(r);
+            const after = await git(cfg, ["rev-parse", "--quiet", "--verify", "refs/stash"]);
+            const beforeOid = before.ok ? before.stdout.trim() : "";
+            const afterOid = after.ok ? after.stdout.trim() : "";
+            if (afterOid === "" || afterOid === beforeOid) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: "Nothing was stashed — no tracked file has uncommitted changes, so your working tree " +
+                                "is unchanged and no stash entry was created. Do not treat this as work being parked. " +
+                                `(git said: ${r.stdout.trim() || "nothing"})`,
+                        }],
+                };
+            }
+            return ok({ op, message: r.stdout.trim() || "push ok", stashes: [] });
+        }
+        const r = await git(cfg, ["stash", "pop", ...(ref ? [ref] : [])]);
         if (!r.ok)
             return gitFail(r);
-        return ok({ op, message: r.stdout.trim() || `${op} ok`, stashes: [] });
+        return ok({ op, message: r.stdout.trim() || "pop ok", stashes: [] });
     });
     // ---- vcs_branch_create — ungated (reversible) ----------------------------
     server.registerTool("vcs_branch_create", {
         title: "Git branch (create)",
         description: "Create a new branch, optionally starting from a given ref (default HEAD), and optionally switch to " +
-            "it. Reversible (`git branch -d`), so not gated. Errors clearly if the branch already exists.",
+            "it. Reversible (`git branch -d`), so not gated. Errors clearly if the branch already exists. If " +
+            "switch=true and the switch is refused (e.g. local changes would be overwritten), the error SAYS the " +
+            "branch was still created — create and switch are two git calls and only the second can fail.",
         inputSchema: {
             name: z.string().min(1).describe("New branch name"),
             from: z.string().optional().describe("Start point (branch, tag, or sha; default HEAD)"),
@@ -396,8 +499,21 @@ export function registerVcsTools(server, cfg) {
         let switched = false;
         if (doSwitch) {
             const sw = await git(cfg, ["switch", name]);
-            if (!sw.ok)
-                return gitFail(sw);
+            if (!sw.ok) {
+                // The branch EXISTS at this point. Returning only the switch failure strands
+                // the caller: they believe nothing happened, retry, and get "already exists"
+                // from a branch they created themselves. Report BOTH halves.
+                const failure = gitFail(sw);
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: `Branch '${name}' WAS created, but switching to it failed — you are still on the ` +
+                                `previous branch. Delete it with \`git branch -d ${name}\` if it is unwanted, or ` +
+                                `resolve the block below and switch with vcs_switch. ${failure.content[0].text}`,
+                        }],
+                };
+            }
             switched = true;
         }
         return ok({ created: true, name, from: from ?? null, switched });

package/dist/toolsets.js

@@ -31,12 +31,12 @@ export function buildToolsets(d) {
     d.onPeers?.(peers);
     return [
         { id: "cli", describe: "Plane B — headless CLI (no editor required)", run: () => registerCliTools(s, c) },
-        { id: "editor", describe: "Plane A — live editor authoring (addon bridge)", run: () => registerEditorTools(s, stub(d.bridge)) },
+        { id: "editor", describe: "Plane A — live editor authoring (addon bridge)", run: () => registerEditorTools(s, stub(d.bridge), c) },
         { id: "lsp", describe: "Plane D — GDScript language server (LSP)", run: () => registerLspTools(s, stub(d.lsp), c) },
         { id: "cslsp", describe: "Plane D — C# language server (OmniSharp)", run: () => registerCsLspTools(s, stub(d.csLsp), c) },
         { id: "dap", describe: "Plane D — GDScript debug adapter (DAP)", run: () => registerDapTools(s, stub(d.dap), c) },
         { id: "csdap", describe: "Plane D — C# debug adapter (netcoredbg)", run: () => registerCsDapTools(s, stub(d.csDap), c) },
-        { id: "runtime", describe: "Plane C — running-game runtime + verification family (incl. F6 multi-peer)", run: () => registerRuntimeTools(s, stub(d.runtime), peers) },
+        { id: "runtime", describe: "Plane C — running-game runtime + verification family (incl. F6 multi-peer)", run: () => registerRuntimeTools(s, stub(d.runtime), peers, c) },
         { id: "processes", describe: "Managed run + captured console output", run: () => { const h = registerProcessTools(s, c); d.onProcesses?.(h); } },
         { id: "knowledge", describe: "Group K — host-side project grep / symbol & idiom lookup", run: () => registerKnowledgeTools(s, c) },
         { id: "vcs", describe: "Group L — read-only version control (git) over the project", run: () => registerVcsTools(s, c) },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.28.0",
+  "version": "1.72.7",
   "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",
@@ -43,7 +43,13 @@
     "start": "node dist/index.js",
     "dev": "tsc && node dist/index.js",
     "stage-addon": "node scripts/stage-addon.mjs",
-    "prepublishOnly": "npm run build && npm run stage-addon"
+    "prepublishOnly": "npm run build && npm run stage-addon",
+    "path-cohort": "node scripts/path-cohort.mjs",
+    "tautology-gate": "node scripts/tautology_gate.selftest.mjs && node scripts/tautology_gate.mjs",
+    "scope-gate": "python3 ../scripts/scope_gate.py",
+    "instrument-gate": "python3 ../scripts/instrument_gate.py",
+    "ledger-selftest": "node test-integration/_path_ledger.selftest.mjs",
+    "workspace-selftest": "node test-integration/_workspace.selftest.mjs"
   },
   "engines": {
     "node": ">=18"