breakpoint-mcp 1.19.1 → 1.23.0

package/dist/cli/tools.js

@@ -0,0 +1,193 @@
+/**
+ * `breakpoint-mcp tools` — export the tool surface as a stable, machine-readable
+ * artifact.
+ *
+ * Why this exists: third-party MCP catalogs, policy gateways, and security
+ * reviewers need to know what this server exposes and how risky each tool is.
+ * Without a published artifact their only options are to run the server and
+ * speak MCP at it, or to infer risk from tool NAMES. A public catalog did the
+ * latter in July 2026 and got it backwards in both directions — `tilemap_clear`
+ * filed as irreversible (it is undoable), `theme_set_color` not flagged at all
+ * (it rewrites a `.tres` in place). This command, plus the annotations shipped
+ * on `tools/list`, removes the need to guess.
+ *
+ * It reports the surface WITHOUT connecting to Godot: the registry is built
+ * against a recorder using the same `buildToolsets` path `index.ts` drives, with
+ * stub clients, and no handler is ever invoked. So it works in CI, in a
+ * container, and on a machine with no Godot installed.
+ *
+ * Two surfaces are reported, because the difference is the security story:
+ *   • `full`           — all 289 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
+ *   • `secure-default` — 274, what an untouched install actually advertises
+ * `--surface` picks which one populates `tools[]`; both counts are always in the
+ * header so a consumer cannot report one as the other by accident.
+ */
+import { parseArgs } from "./args.js";
+import { buildToolsets } from "../toolsets.js";
+import { applyOutputSchemas } from "../schemas.js";
+import { applyAnnotations, annotationsFor } from "../annotations.js";
+import { TOOL_CAPABILITIES, CAPABILITY_GROUPS, GROUP_DESCRIBE } from "../capabilities.js";
+import { loadConfig } from "../config.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+/**
+ * Read the version from package.json at runtime rather than hardcoding it.
+ * Deliberate: the version already has to be bumped in `package.json`, the
+ * `serverInfo` literal, both `plugin.cfg`s, and the doctor/init surface strings
+ * — this command must not become a sixth place to forget. package.json ships in
+ * the npm tarball, so the read is safe in an installed package; if it ever
+ * isn't, an unknown version is better than a stale one.
+ */
+function packageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(join(here, "..", "..", "package.json"), "utf8")).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Register the whole surface against a recorder, exactly as `index.ts` does
+ * (`applyOutputSchemas` → `applyAnnotations` → every `register*Tools`), and
+ * capture each tool's config. Capability filtering is applied afterwards rather
+ * than via `applyCapabilities`, so a single pass can report both surfaces.
+ */
+function recordSurface() {
+    const recorded = [];
+    let current = "";
+    const push = (name, config) => {
+        recorded.push({ name, config, toolset: current });
+        return { name };
+    };
+    const server = {
+        registerTool: (name, config) => push(name, config),
+        registerResource: () => { },
+        experimental: {
+            tasks: { registerToolTask: (name, config) => push(name, config) },
+        },
+        server: { elicitInput: async () => ({ action: "decline" }) },
+    };
+    const mcp = server;
+    const stub = {};
+    applyOutputSchemas(mcp);
+    applyAnnotations(mcp);
+    for (const ts of buildToolsets({
+        server: mcp,
+        bridge: stub,
+        runtime: stub,
+        lsp: stub,
+        csLsp: stub,
+        dap: stub,
+        csDap: stub,
+        config: loadConfig(),
+    })) {
+        current = ts.id;
+        ts.run();
+    }
+    return recorded;
+}
+function toExported(r) {
+    const groups = [...(TOOL_CAPABILITIES[r.name] ?? [])];
+    const shape = r.config.inputSchema ?? {};
+    const params = Object.keys(shape);
+    return {
+        name: r.name,
+        title: typeof r.config.title === "string" ? r.config.title : null,
+        description: typeof r.config.description === "string" ? r.config.description : null,
+        toolset: r.toolset,
+        capabilityGroups: groups,
+        privileged: groups.length > 0,
+        confirmationGated: params.includes("confirm"),
+        params,
+        annotations: annotationsFor(r.name),
+    };
+}
+/** Build the report. Exported for the tests, which assert it against the registry. */
+export function buildToolsReport(surface) {
+    const all = recordSurface().map(toExported);
+    const secure = all.filter((t) => !t.privileged);
+    const shown = surface === "full" ? all : secure;
+    return {
+        server: { name: "breakpoint-mcp", version: packageVersion() },
+        // Deliberately null, not a timestamp: this artifact is a pure function of the
+        // source tree, so two runs of the same build must be byte-identical (a
+        // consumer can diff releases; CI can assert no drift).
+        generatedAt: null,
+        surface,
+        counts: {
+            full: all.length,
+            secureDefault: secure.length,
+            readOnly: shown.filter((t) => t.annotations.readOnlyHint).length,
+            destructive: shown.filter((t) => t.annotations.destructiveHint).length,
+            idempotent: shown.filter((t) => t.annotations.idempotentHint).length,
+            openWorld: shown.filter((t) => t.annotations.openWorldHint).length,
+            confirmationGated: shown.filter((t) => t.confirmationGated).length,
+            privileged: all.length - secure.length,
+        },
+        capabilityGroups: CAPABILITY_GROUPS.map((g) => ({
+            id: g,
+            describe: GROUP_DESCRIBE[g],
+            defaultEnabled: false,
+            tools: all.filter((t) => t.capabilityGroups.includes(g)).map((t) => t.name).sort(),
+        })),
+        tools: [...shown].sort((a, b) => a.name.localeCompare(b.name)),
+    };
+}
+function renderText(report) {
+    const c = report.counts;
+    const lines = [
+        `breakpoint-mcp ${report.server.version} — ${report.surface} surface`,
+        "",
+        `  tools                ${report.tools.length}` +
+            (report.surface === "secure-default" ? `  (of ${c.full} total; ${c.privileged} privileged, dropped)` : ""),
+        `  read-only            ${c.readOnly}`,
+        `  destructive          ${c.destructive}`,
+        `  idempotent           ${c.idempotent}`,
+        `  open-world (egress)  ${c.openWorld}`,
+        `  confirmation-gated   ${c.confirmationGated}`,
+        "",
+        "Capability groups (all OFF by default — enable with BREAKPOINT_PRIVILEGED_GROUPS):",
+    ];
+    for (const g of report.capabilityGroups) {
+        lines.push(`  ${g.id} (${g.tools.length} tools) — ${g.describe}`);
+    }
+    lines.push("", "Tools:");
+    for (const t of report.tools) {
+        const marks = [
+            t.annotations.readOnlyHint ? "read-only" : null,
+            t.annotations.destructiveHint ? "destructive" : null,
+            t.confirmationGated ? "gated" : null,
+            t.privileged ? `privileged:${t.capabilityGroups.join("+")}` : null,
+        ].filter(Boolean);
+        lines.push(`  ${t.name.padEnd(34)} ${marks.join(" · ")}`);
+    }
+    lines.push("", "Re-run with --json for the machine-readable form.", "");
+    return lines.join("\n");
+}
+export async function runTools(argv) {
+    const { flags } = parseArgs(argv, ["json", "help", "h"]);
+    if (flags.help || flags.h) {
+        process.stdout.write([
+            "breakpoint-mcp tools — export the tool surface (name, risk annotations, capability group).",
+            "",
+            "  --json                Emit JSON (stable, no timestamp — safe to diff between releases).",
+            "  --surface <which>     full | secure-default   (default: secure-default, what an",
+            "                        untouched install actually advertises).",
+            "",
+            "Reads no Godot install and starts no server — the registry is built statically.",
+            "",
+        ].join("\n"));
+        return 0;
+    }
+    const raw = typeof flags.surface === "string" ? flags.surface : "secure-default";
+    if (raw !== "full" && raw !== "secure-default") {
+        process.stderr.write(`unknown --surface "${raw}" (expected: full | secure-default)\n`);
+        return 2;
+    }
+    const report = buildToolsReport(raw);
+    process.stdout.write(flags.json ? `${JSON.stringify(report, null, 2)}\n` : renderText(report));
+    return 0;
+}
+//# sourceMappingURL=tools.js.map

package/dist/index.js

@@ -12,6 +12,7 @@ import { DapClient } from "./dap.js";
 import { buildToolsets } from "./toolsets.js";
 import { registerRecipes } from "./recipes.js";
 import { applyOutputSchemas } from "./schemas.js";
+import { applyAnnotations } from "./annotations.js";
 import { applyCapabilities, droppedTools, registerCapabilitiesResource, selectPrivilegedGroups, } from "./capabilities.js";
 import { taskStore, TASK_CAPABILITIES } from "./tasks.js";
 import { RESOURCE_CAPABILITIES, registerResourceSubscriptions } from "./subscriptions.js";
@@ -35,24 +36,31 @@ async function main() {
     // so long jobs (export/import/headless script) support poll/await/cancel.
     // D3: also advertise resources.subscribe so clients can subscribe to
     // godot://… resources and receive notifications/resources/updated.
-    const server = new McpServer({ name: "breakpoint-mcp", version: "1.19.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.23.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // any register*Tools call — it wraps server.registerTool.
     applyOutputSchemas(server);
+    // MCP tool annotations — publish readOnly/destructive/idempotent/openWorld
+    // hints on every tool so clients and policy catalogs read our risk posture
+    // instead of guessing it from tool names. Hints only; the enforcement stays
+    // in applyCapabilities (below) + confirm.ts. Wraps registerTool after the
+    // schema wrapper, before any register*Tools call.
+    applyAnnotations(server);
     // Capability groups — a risk-based axis over the toolsets. Both `code-execution`
     // and `network` are OFF by default; a disabled group's tools are DROPPED at
     // registration (omitted from tools/list), so the secure-default surface is
-    // 276 − 14 = 262 tools. Enable via BREAKPOINT_PRIVILEGED_GROUPS. Wraps
+    // 289 − 15 = 274 tools. Enable via BREAKPOINT_PRIVILEGED_GROUPS. Wraps
     // server.registerTool AFTER applyOutputSchemas (schema wrapper stays innermost).
     const privilegedGroups = selectPrivilegedGroups(config.privilegedGroups, (unknown) => log(`ignoring unknown BREAKPOINT_PRIVILEGED_GROUPS token(s): ${unknown.join(", ")}`));
     applyCapabilities(server, privilegedGroups);
     // The A/B/C/D planes ARE the grouping. Build the ordered toolset registry
     // (the single source of truth, shared with the registration tests) and
     // register only the selected groups. Default (BREAKPOINT_TOOLSETS unset) =
-    // every group → the full 276-tool surface, byte-identical to before. A filter
+    // every group → the full 289-tool surface, byte-identical to before. A filter
     // lets a client that can't defer tools, or a user who wants a smaller default
     // menu, load only the planes a project needs (GitHub-MCP `--toolsets` style).
     let processes;
+    let peers;
     const toolsets = buildToolsets({
         server,
         bridge,
@@ -65,6 +73,9 @@ async function main() {
         onProcesses: (h) => {
             processes = h;
         },
+        onPeers: (h) => {
+            peers = h;
+        },
     });
     const enabled = selectToolsets(toolsets.map((t) => t.id), config.toolsets, (unknown) => log(`ignoring unknown BREAKPOINT_TOOLSETS token(s): ${unknown.join(", ")}`));
     for (const ts of toolsets)
@@ -85,7 +96,7 @@ async function main() {
         log(`toolsets enabled: ${[...enabled].sort().join(", ")} (${enabled.size}/${toolsets.length} groups)`);
     }
     // Recipes: a free, curated task-recipe layer exposed as MCP prompts (discoverable
-    // via prompts/list). Adds NO tools — the 276-tool count is unchanged — and drives
+    // via prompts/list). Adds NO tools — the 289-tool count is unchanged — and drives
     // the enforced tools above, so it's a skill-pack layer over typed/undoable tools.
     registerRecipes(server);
     // Always-on capability affordance — never behind a toolset or a privileged
@@ -117,6 +128,8 @@ async function main() {
         dap.close();
         csDap.close();
         processes?.killAll();
+        // F6: headless peers are children of this server — never outlive it.
+        peers?.stopAll();
         process.exit(0);
     };
     process.on("SIGINT", shutdown);
@@ -130,6 +143,7 @@ function printUsage() {
         "  breakpoint-mcp             Start the MCP server on stdio (default; how MCP clients launch it).",
         "  breakpoint-mcp init        Install + enable the editor addon in a project and wire the MCP client.",
         "  breakpoint-mcp doctor      Check the Godot binary, the editor addon, and the four bridges.",
+        "  breakpoint-mcp tools       Export the tool surface + risk annotations (for catalogs / reviews).",
         "  breakpoint-mcp --help      Show this help.",
         "",
         "init options:",
@@ -147,6 +161,10 @@ function printUsage() {
         "  --timeout <ms>      Per-bridge connect timeout (default 1500).",
         "  --json              Emit the report as JSON.",
         "",
+        "tools options:",
+        "  --surface <which>   full | secure-default (default: secure-default, what an untouched install advertises).",
+        "  --json              Emit the surface as JSON — stable and timestamp-free, so releases can be diffed.",
+        "",
         "All runtime configuration is via environment variables; see the README.",
         "",
     ].join("\n"));
@@ -160,6 +178,10 @@ void (async () => {
         const { runDoctor } = await import("./cli/doctor.js");
         process.exit(await runDoctor(process.argv.slice(3)));
     }
+    if (sub === "tools") {
+        const { runTools } = await import("./cli/tools.js");
+        process.exit(await runTools(process.argv.slice(3)));
+    }
     if (sub === "init") {
         const { runInit } = await import("./cli/init.js");
         process.exit(await runInit(process.argv.slice(3)));

package/dist/peers.js

@@ -0,0 +1,238 @@
+import net from "node:net";
+import { BridgeClient, BridgeError } from "./bridge.js";
+import { ProcessRegistry } from "./tools/processes.js";
+import { ensureProjectSecret, readProjectSecret } from "./secret.js";
+import { log } from "./logger.js";
+/**
+ * Hard ceiling on simultaneously live peers.
+ *
+ * Four, not the eight a rival offers. Four headless Godot instances is already a
+ * heavy CI runner, the convergence cases that matter are covered at four, and
+ * every extra instance multiplies the flake surface of the one feature whose
+ * entire selling point is that it does NOT flake. Raise it on evidence, never
+ * speculatively.
+ */
+export const MAX_PEERS = 4;
+/** How far above the default runtime port the allocator will scan. */
+const PORT_SCAN_SPAN = 200;
+/** Is `port` bindable on `host` right now? */
+function portFree(host, port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once("error", () => resolve(false));
+        srv.once("listening", () => srv.close(() => resolve(true)));
+        try {
+            srv.listen(port, host);
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class PeerRegistry {
+    cfg;
+    /** Peers get their OWN process registry, so peer ids and `godot_run_managed`
+     *  ids never share a namespace and the `runtime` toolset does not depend on
+     *  whether the `processes` toolset is enabled. */
+    procs = new ProcessRegistry();
+    peers = new Map();
+    counter = 0;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** Peers that have not been stopped and whose child is still running. */
+    live() {
+        const out = [];
+        for (const e of this.peers.values()) {
+            if (e.stopped)
+                continue;
+            if (this.procs.get(e.managedId)?.exited)
+                continue;
+            out.push(e.info);
+        }
+        return out;
+    }
+    /** Every peer this registry has spawned, live or not. */
+    all() {
+        return [...this.peers.values()].map((e) => e.info);
+    }
+    /**
+     * The bridge client addressing one peer. Throws a BridgeError the runtime
+     * tools' `fail()` renders — an unknown or dead peer must read as a clear
+     * message naming the live ids, never as a generic "cannot reach the bridge".
+     */
+    clientFor(id) {
+        const e = this.peers.get(id);
+        if (!e) {
+            const ids = this.live().map((p) => p.id);
+            throw new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}. ` +
+                `Spawn peers with runtime_spawn_peers, or omit \`peer\` to address the default running game.`);
+        }
+        if (e.stopped)
+            throw new BridgeError("peer_stopped", `Peer "${id}" was stopped by runtime_peer_stop.`);
+        const m = this.procs.get(e.managedId);
+        if (m?.exited) {
+            const tail = this.procs.tail(e.managedId, 6).join(" | ");
+            throw new BridgeError("peer_exited", `Peer "${id}" exited (code ${m.exitCode})${tail ? `; last output: ${tail}` : ""}.`);
+        }
+        return e.client;
+    }
+    /**
+     * Allocate `count` free loopback ports, starting just above the default
+     * runtime port so a peer never collides with a developer's already-running
+     * game. Ports held by live peers are skipped even if the probe would pass.
+     *
+     * Probe-then-release is a TOCTOU window by construction: another process could
+     * take the port between the probe and the child's bind. Allocation is
+     * sequential and the window is sub-millisecond, and the failure mode is
+     * benign — the child logs "could not listen" and the readiness wait below
+     * reports it with that line attached, rather than the peer silently
+     * half-existing.
+     */
+    async allocatePorts(count) {
+        const taken = new Set([this.cfg.runtimePort, ...this.live().map((p) => p.port)]);
+        const ports = [];
+        const base = this.cfg.runtimePort + 1;
+        for (let port = base; port < base + PORT_SCAN_SPAN && ports.length < count; port++) {
+            if (taken.has(port))
+                continue;
+            if (!(await portFree(this.cfg.runtimeHost, port)))
+                continue;
+            taken.add(port);
+            ports.push(port);
+        }
+        if (ports.length < count) {
+            throw new BridgeError("no_free_port", `Could not find ${count} free loopback port(s) in ${base}–${base + PORT_SCAN_SPAN - 1}. ` +
+                `Stop stale peers with runtime_peer_stop{all:true}, or set BREAKPOINT_RUNTIME_PORT to a quieter range.`);
+        }
+        return ports;
+    }
+    /** Poll a peer's bridge until it answers `ping`, or the deadline passes. */
+    async waitReady(client, deadline) {
+        for (;;) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return false;
+            try {
+                await client.request("ping", {}, Math.min(1000, remaining));
+                return true;
+            }
+            catch {
+                if (Date.now() >= deadline)
+                    return false;
+                await sleep(100);
+            }
+        }
+    }
+    /**
+     * Spawn `count` headless peers and wait until each answers `ping`.
+     *
+     * Waiting is part of the contract on purpose. Godot needs ~200 ms to bind, so
+     * a tool that returned immediately would hand the caller peers its very next
+     * call cannot reach — a flake in the one feature that exists to remove flakes.
+     */
+    async spawn(opts) {
+        const liveCount = this.live().length;
+        if (liveCount + opts.count > MAX_PEERS) {
+            throw new BridgeError("peer_limit", `${liveCount} peer(s) already live; spawning ${opts.count} more would exceed the ceiling of ${MAX_PEERS}. ` +
+                `Stop some with runtime_peer_stop{all:true} first.`);
+        }
+        // Constraint 2 — mint BEFORE the first spawn so no child reaches the addon's
+        // unlocked mint branch. Never overwrites an existing secret.
+        const secret = ensureProjectSecret(this.cfg.projectPath);
+        if (!secret) {
+            log("[peers] could not read or mint the project secret; peers will mint their own (see peers.ts)");
+        }
+        const ports = await this.allocatePorts(opts.count);
+        const deadline = Date.now() + (opts.timeoutMs ?? 15000);
+        const spawned = [];
+        for (let i = 0; i < ports.length; i++) {
+            const port = ports[i];
+            const id = `peer-${++this.counter}`;
+            const extraArgs = ["--headless", ...(opts.args ?? []), ...(opts.scene ? [opts.scene] : [])];
+            const env = {
+                BREAKPOINT_RUNTIME_PORT: String(port),
+                BREAKPOINT_PEER_ID: id,
+                BREAKPOINT_PEER_INDEX: String(i),
+            };
+            if (opts.role)
+                env.BREAKPOINT_PEER_ROLE = opts.role;
+            const managed = this.procs.run(this.cfg, extraArgs, env);
+            const client = new BridgeClient(this.cfg.runtimeHost, port, this.cfg.runtimeTimeoutMs, `runtime peer ${id}`, "Is the peer still running? Peers are headless children of this server; a project that fails to load exits immediately.", 
+            // The FILE, not resolveBridgeSecret: the addon's _setup_auth() does not
+            // read BREAKPOINT_*_SECRET, so a host-launched child authenticates with
+            // whatever is on disk regardless of the host's env overrides.
+            () => readProjectSecret(this.cfg.projectPath));
+            const entry = {
+                info: { id, port, pid: managed.child.pid ?? null, role: opts.role ?? null, ready: false },
+                client,
+                managedId: managed.id,
+                stopped: false,
+            };
+            this.peers.set(id, entry);
+            spawned.push(entry);
+        }
+        await Promise.all(spawned.map(async (e) => {
+            e.info.ready = await this.waitReady(e.client, deadline);
+        }));
+        const notReady = spawned.filter((e) => !e.info.ready);
+        if (notReady.length) {
+            const detail = notReady
+                .map((e) => {
+                const m = this.procs.get(e.managedId);
+                const why = m?.exited ? `exited (code ${m.exitCode})` : "never answered ping";
+                const tail = this.procs.tail(e.managedId, 6).join(" | ");
+                return `${e.info.id} on ${e.info.port}: ${why}${tail ? ` — ${tail}` : ""}`;
+            })
+                .join("; ");
+            // Leave the failed peers registered rather than reaping them: the caller
+            // can still runtime_peer_stop{all:true}, and a half-started peer that
+            // vanished from the registry is harder to reason about than one that
+            // reports why it is not ready.
+            throw new BridgeError("peer_not_ready", `${notReady.length} of ${spawned.length} peer(s) did not become ready. ${detail}. ` +
+                `Is the Breakpoint MCP addon enabled in this project (it registers the runtime autoload)?`);
+        }
+        return spawned.map((e) => e.info);
+    }
+    /** Stop one peer (or all). Repeating is a no-op, so the tool is idempotent. */
+    stop(id, all = false) {
+        const targets = all ? [...this.peers.keys()] : id ? [id] : [];
+        if (!all && id && !this.peers.has(id)) {
+            const ids = this.live().map((p) => p.id);
+            throw new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}.`);
+        }
+        const stopped = [];
+        for (const t of targets) {
+            const e = this.peers.get(t);
+            if (!e)
+                continue;
+            try {
+                e.client.close();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                this.procs.get(e.managedId)?.child.kill();
+            }
+            catch {
+                /* ignore */
+            }
+            e.stopped = true;
+            stopped.push(t);
+        }
+        return stopped;
+    }
+    /** Shutdown hook — kill every peer child and close every peer socket. */
+    stopAll() {
+        try {
+            this.stop(undefined, true);
+        }
+        catch {
+            /* ignore */
+        }
+        this.procs.killAll();
+    }
+}
+//# sourceMappingURL=peers.js.map

package/dist/recipes.js

@@ -7,7 +7,7 @@
  * it's **free** (MIT, shipped in the server), and it sits **over typed,
  * schema-validated, undoable tools** — so the contract is executed by the
  * server, not merely described in prose the model might misapply. Recipes are
- * discoverable via MCP `prompts/list`; they add **no tools** (the 276-tool
+ * discoverable via MCP `prompts/list`; they add **no tools** (the 289-tool
  * count is unchanged) and cost nothing until a client pulls one.
  */
 import { z } from "zod";
@@ -27,6 +27,8 @@ export const RECIPE_NAMES = [
     "recipe_screenshot_regression",
     "recipe_type_safe_edit",
     "recipe_csharp_fix_and_debug",
+    "recipe_deterministic_playtest",
+    "recipe_multiplayer_scaffold_and_converge",
 ];
 export function registerRecipes(server) {
     // 1 — 2D player controller, then verify it moves.
@@ -164,5 +166,67 @@ export function registerRecipes(server) {
             SAFETY,
         ].join("\n"));
     });
+    // 7 — Deterministic playtesting: freeze, step exact frames, assert a golden frame.
+    server.registerPrompt("recipe_deterministic_playtest", {
+        title: "Freeze the game, step exact frames, and assert a deterministic golden frame",
+        description: "Turn a flaky run-screenshot-guess loop into a frame-exact, reproducible one: freeze time, advance a fixed number of frames, then assert node state and diff a golden frame.",
+        argsSchema: {
+            scene_path: z.string().optional().describe("Scene to play-test (default res://main.tscn)"),
+            root_path: z.string().optional().describe("Node to snapshot/assert on (default '.', the running scene root)"),
+            frames: z.string().optional().describe("Frames to advance per step (default 30)"),
+            reference_path: z.string().optional().describe("Golden PNG for the screenshot diff (default res://tests/frame.png)"),
+            tolerance: z.string().optional().describe("Max fraction of differing pixels for the diff (default 0.0)"),
+        },
+    }, (a) => {
+        const scene = str(a, "scene_path", "res://main.tscn");
+        const root = str(a, "root_path", ".");
+        const frames = str(a, "frames", "30");
+        const ref = str(a, "reference_path", "res://tests/frame.png");
+        const tol = str(a, "tolerance", "0.0");
+        return recipe("Deterministic, frame-exact playtesting with a golden-frame check.", [
+            `Goal: drive ${scene} to an exact, reproducible frame and assert on it — no wall-clock flakiness.`,
+            "",
+            `1. Boot + freeze: godot_run_project. runtime_time_scale{scale:0} to FREEZE the game (this pauses the SceneTree, so nothing advances on its own). If the run uses randomness, runtime_seed_rng{seed:...} first so the whole playtest is reproducible.`,
+            `2. Baseline: runtime_state_digest{root:"${root}"} to snapshot the frozen state (positions / visibility / modulate, stable-ordered) — this is your deterministic "before".`,
+            `3. Step: runtime_step_frames{frames:${frames}, kind:"physics"} to advance EXACTLY ${frames} frames while frozen (use kind:"both" to also tick _process each step). The game stays frozen afterwards, so your reads are stable.`,
+            `4. Assert: runtime_state_digest{root:"${root}"} (or runtime_assert_node_state) that the node reached the expected, frame-exact state, then runtime_screenshot_diff against ${ref} with tolerance ${tol} — because you stepped a fixed number of frames the frame is reproducible, so the diff is stable (establish ${ref} once with runtime_screenshot on the first green run, then vcs_add it).`,
+            `5. Iterate or thaw: repeat 3–4 to walk frame-by-frame (every step is deterministic), or runtime_time_scale{scale:1} to thaw and resume normal play. godot_stop when done. On a failed assert you are one dbg_set_breakpoints + dbg_launch away from the exact value that diverged.`,
+            "",
+            "Why this beats run-screenshot-guess: freezing plus fixed-frame stepping converts a timing-dependent check into a frame-exact, reproducible one the runtime_assert_* family can verify — the R tier of the W/R/E model, made deterministic.",
+            "",
+            SAFETY,
+        ].join("\n"));
+    });
+    // 8 — Multiplayer: scaffold it with mp_*, then prove independent peers converge.
+    server.registerPrompt("recipe_multiplayer_scaffold_and_converge", {
+        title: "Scaffold multiplayer with mp_*, then prove independent peers converge",
+        description: "Scaffold ENet + spawner / synchronizer / RPC netcode, then spawn real headless peers and assert they reach a byte-equal state — the scaffold verified rather than assumed.",
+        argsSchema: {
+            scene_path: z.string().optional().describe("Scene to scaffold and play-test (default res://main.tscn)"),
+            peer_count: z.string().optional().describe("Headless peers to spawn (1-4; default 3)"),
+            seed: z.string().optional().describe("RNG seed given to every peer (default 12345)"),
+            frames: z.string().optional().describe("Physics frames to step on each peer (default 30)"),
+            root_path: z.string().optional().describe("Node subtree to compare across peers (default '.', the running scene root)"),
+        },
+    }, (a) => {
+        const scene = str(a, "scene_path", "res://main.tscn");
+        const count = str(a, "peer_count", "3");
+        const seed = str(a, "seed", "12345");
+        const frames = str(a, "frames", "30");
+        const root = str(a, "root_path", ".");
+        return recipe("Multiplayer scaffolding with a multi-peer convergence check.", [
+            `Goal: scaffold multiplayer in ${scene} with the mp_* family, then prove ${count} independently-driven peers reach the SAME state.`,
+            "",
+            `1. Scaffold: scene_open ${scene}. mp_setup_enet_peer for the host/join script (mp_setup_webrtc_peer if you need WebRTC); mp_scaffold_lobby for a lobby; mp_add_spawner for nodes created at runtime and mp_add_synchronizer for replicated properties; mp_set_authority on the nodes each peer owns; mp_wire_rpc for the calls that cross the wire. Run gd_diagnostics until clean BEFORE running anything.`,
+            "2. Make it testable, or step 4 will diverge and be right to: keep replicated state on _physics_process (the FIXED timestep), guard every global randf() on `delta > 0`, and give idle-frame code its OWN RandomNumberGenerator. runtime_seed_rng seeds ONE stream for the whole project, and freezing does not stop callbacks firing — an unguarded draw burns that stream at wall-clock rate and desynchronises peers that are otherwise identical.",
+            `3. Spawn: runtime_spawn_peers{count:${count}} — real headless children of this project, each on its own loopback port (ceiling 4). Pass role:"server" to label one and branch on OS.get_environment("BREAKPOINT_PEER_ROLE"). It is code-execution-privileged, so it is absent from the default surface unless you enabled that capability group.`,
+            `4. Converge, IN THIS ORDER: runtime_time_scale{scale:0, peer} to FREEZE every peer first (they free-ran for different durations since spawn, so their state already differs); runtime_set_property{peer} to equalise the starting state; runtime_seed_rng{seed:${seed}, peer} with the SAME seed on each; runtime_step_frames{frames:${frames}, kind:"physics", peer} on each; then runtime_peers_digest{root:"${root}"}.`,
+            `5. Assert, then diagnose: converged:true is the green result. On false, diverged_at names the exact node paths that disagree — start there with runtime_get_property{peer} and runtime_get_log{peer} on the two peers that differ, runtime_assert_node_state for the value you expected, and dbg_set_breakpoints + dbg_launch when you need the frame it went wrong on. Finish with runtime_peer_stop{all:true}.`,
+            "",
+            "Scope, so a green result means what you think it does: peers are local headless children on loopback — this is testing, not hosting, and Breakpoint runs no relay, lobby or signalling server. Convergence is a same-machine claim (one OS, one engine build); it says nothing about two players on two machines.",
+            "",
+            SAFETY,
+        ].join("\n"));
+    });
 }
 //# sourceMappingURL=recipes.js.map

package/dist/schemas.js

@@ -494,6 +494,42 @@ export const outputSchemas = {
         reference: z.string(),
         reason: z.string().optional(),
     },
+    // F8 additions: await/animation/node-lifecycle over the runtime bridge.
+    runtime_await_condition: { met: z.boolean(), polls: z.number(), elapsed_ms: z.number(), value: encodedValue },
+    runtime_anim_play: { playing: z.boolean(), current_animation: z.string(), speed_scale: z.number() },
+    runtime_anim_stop: { playing: z.boolean(), current_animation: z.string(), position: z.number() },
+    runtime_anim_get_state: {
+        playing: z.boolean(),
+        current_animation: z.string(),
+        position: z.number(),
+        length: z.number(),
+        speed_scale: z.number(),
+        animations: z.array(z.string()),
+    },
+    runtime_node_add: { added: z.boolean(), path: z.string(), type: z.string() },
+    runtime_node_remove: { removed: z.boolean(), path: z.string() },
+    // F4 additions: deterministic playtesting (time control / frame stepping / state digest / RNG seed).
+    runtime_time_scale: { previous: z.number(), current: z.number() },
+    runtime_step_frames: { frames_advanced: z.number(), frame_index: z.number() },
+    runtime_state_digest: { digest: z.record(z.record(encodedValue)), node_count: z.number() },
+    runtime_seed_rng: { seed: z.number() },
+    // F6 additions: multi-peer deterministic playtesting (spawn / stop / converge).
+    runtime_spawn_peers: {
+        peers: z.array(z.object({
+            id: z.string(),
+            port: z.number(),
+            pid: z.number().nullable(),
+            role: z.string().nullable(),
+            ready: z.boolean(),
+        })),
+        count: z.number(),
+    },
+    runtime_peer_stop: { stopped: z.array(z.string()) },
+    runtime_peers_digest: {
+        digests: z.array(z.object({ id: z.string(), digest: z.record(z.record(encodedValue)), node_count: z.number() })),
+        converged: z.boolean(),
+        diverged_at: z.array(z.string()).nullable(),
+    },
     // ---- Group K: knowledge & search ----
     // Host-side project index (tools/knowledge.ts) — no bridge/LSP; read the project files directly.
     project_search: {