@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/transport/channel.js

@@ -0,0 +1,352 @@
+/**
+ * Reconnecting, authenticating WebSocket with JSON-RPC request/response
+ * correlation — the transport Channel primitive.
+ *
+ * One responsibility: run ONE reliable request/response conversation over a
+ * flaky socket — connect, authenticate (re-reading the token every connect),
+ * correlate responses to their pending promise by id, reset a pending call's
+ * timeout on _queued/_executing progress notifications, and ride out transient
+ * drops with exponential backoff (reset on a successful round-trip, not on
+ * open). Kept whole: the correlation layer and the connection/reconnect
+ * lifecycle co-vary — the backoff reset lives inside the response-correlation
+ * path — so they do not separate without a mutual-callback cycle.
+ */
+import { WebSocket } from "ws";
+import { randomUUID } from "node:crypto";
+import { BridgeError } from "../shared/errors.js";
+import { readToken } from "./tokenPath.js";
+import { authenticate } from "./authHandshake.js";
+import { getServerVersion, compareVersions } from "../shared/version.js";
+// ── Constants ────────────────────────────────────────────────────────
+const JSONRPC_VERSION = "2.0";
+const DEFAULT_TIMEOUT_MS = 30_000;
+// Reconnect tuning. 2^6 = 64s clamped to 60s ceiling, so the attempt
+// progression is 1, 2, 4, 8, 16, 32, 60, 60, ... seconds. The per-call
+// await ceiling (CALL_AWAIT_RECONNECT_MS) bounds how long a fresh call()
+// will wait for the bridge to come back before rejecting DISCONNECTED —
+// covers the first two backoff rungs (1s + 2s) plus editor-restart
+// settle margin.
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 60_000;
+const RECONNECT_MAX_ATTEMPT = 6;
+const CALL_AWAIT_RECONNECT_MS = 10_000;
+// ── Channel (WebSocket wrapper with reconnect) ───────────────────────
+export function createChannel(url, projectPath, onAuthResolved, onNotification, opts) {
+    const noReconnect = opts?.noReconnect ?? false;
+    const connectTimeout = opts?.connectTimeoutMs ?? 30_000;
+    // Skip the server/toolkit version-compat check on the runtime channel — the
+    // editor connection runs the authoritative check, and the runtime auth ack
+    // carries no version, so re-checking only false-warns about the same plugin.
+    const skipVersionCheck = opts?.skipVersionCheck ?? false;
+    const pending = new Map();
+    const openWaiters = new Set();
+    let ws = undefined;
+    let connectPromise = undefined;
+    let reconnectTimer = undefined;
+    let attempt = 0;
+    let closed = false;
+    // Cold vs hot disconnect distinction. Until the first successful open we
+    // treat connect failures as terminal (CONNECT_FAILED) so callers like
+    // `callRuntime` can map "game never started" to GAME_NOT_RUNNING in ms,
+    // not after a 10s reconnect-await ceiling. Once we've connected once we
+    // assume the peer exists and ride out transient drops with backoff.
+    // When noReconnect is set (runtime channels), disconnect is always terminal.
+    let hasConnectedOnce = false;
+    /** Send a fire-and-forget JSON-RPC notification to the toolkit (no id, no response). */
+    function sendNotification(method, params) {
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ jsonrpc: JSONRPC_VERSION, method, params }));
+        }
+    }
+    /** Cancel an in-flight bridge call: clear its timeout, reject the promise, and
+     *  notify the toolkit so cooperative cancellation can bail out early. */
+    function cancelPending(id) {
+        const pendingRequest = pending.get(id);
+        if (pendingRequest) {
+            clearTimeout(pendingRequest.timer);
+            pendingRequest.reject(new BridgeError("CANCELLED", "Request cancelled by client"));
+            pending.delete(id);
+        }
+        // Always notify toolkit — fire-and-forget even if pending already resolved.
+        sendNotification("_cancel", { request_id: id });
+    }
+    function rejectAllPending(code, message) {
+        for (const [id, pendingRequest] of pending) {
+            clearTimeout(pendingRequest.timer);
+            pendingRequest.reject(new BridgeError(code, message));
+            pending.delete(id);
+        }
+    }
+    function resolveAllWaiters(socket) {
+        for (const waiter of openWaiters) {
+            clearTimeout(waiter.timer);
+            waiter.resolve(socket);
+        }
+        openWaiters.clear();
+    }
+    function rejectAllWaiters(code, message) {
+        for (const waiter of openWaiters) {
+            clearTimeout(waiter.timer);
+            waiter.reject(new BridgeError(code, message));
+        }
+        openWaiters.clear();
+    }
+    function scheduleReconnect() {
+        if (closed)
+            return;
+        // Runtime channels (noReconnect): game is dead, don't try again.
+        // Reject all waiters immediately so callers get DISCONNECTED fast.
+        if (noReconnect) {
+            rejectAllWaiters("DISCONNECTED", `${url} disconnected (no reconnect — runtime channel)`);
+            return;
+        }
+        if (reconnectTimer)
+            return;
+        const delay = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** attempt);
+        attempt = Math.min(attempt + 1, RECONNECT_MAX_ATTEMPT);
+        process.stderr.write(`[bridge] ${url} disconnected; reconnect in ${delay}ms (attempt ${attempt})\n`);
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = undefined;
+            if (closed)
+                return;
+            // Failure path schedules the next attempt itself via socket.error.
+            void connect().catch(() => { });
+        }, delay);
+        reconnectTimer.unref?.();
+    }
+    /** Authenticate after the socket opens, then resolve the connect promise. */
+    async function performAuth(socket, resolve, reject) {
+        const wasReconnect = hasConnectedOnce;
+        process.stderr.write(`[bridge] ${url} ${wasReconnect ? "reconnected" : "connected"}, authenticating…\n`);
+        try {
+            // Re-read token from disk on every connect (including reconnects)
+            // so rotated tokens after a plugin restart are picked up.
+            const token = await readToken(projectPath);
+            const authResp = await authenticate(socket, token);
+            hasConnectedOnce = true;
+            if (authResp.godotVersion && onAuthResolved)
+                onAuthResolved({ version: authResp.godotVersion, headless: authResp.headless });
+            const verNote = authResp.godotVersion ? ` (Godot ${authResp.godotVersion})` : "";
+            process.stderr.write(`[bridge] ${url} authenticated${verNote}\n`);
+            // Version mismatch check — human-only (stderr), nothing on MCP wire.
+            if (!skipVersionCheck) {
+                const serverVer = getServerVersion();
+                const severity = compareVersions(serverVer, authResp.toolkitVersion);
+                if (severity === "major") {
+                    process.stderr.write(`[bridge] ERROR: major version mismatch — server ${serverVer}, toolkit ${authResp.toolkitVersion}. Update both to the same major version.\n`);
+                }
+                else if (severity === "minor") {
+                    process.stderr.write(`[bridge] WARNING: version mismatch — server ${serverVer}, toolkit ${authResp.toolkitVersion}. Consider updating.\n`);
+                }
+                else if (severity === "unknown") {
+                    process.stderr.write(`[bridge] WARNING: toolkit did not report version (pre-handshake build?). Consider updating the toolkit plugin.\n`);
+                }
+            }
+            // Notify on reconnect so the server can re-read config.
+            if (wasReconnect) {
+                onNotification?.()?.("config_reloaded", { reconnect: true });
+            }
+            resolveAllWaiters(socket);
+            resolve(socket);
+        }
+        catch (err) {
+            ws = undefined;
+            socket.close();
+            const error = err instanceof BridgeError ? err : new BridgeError("AUTH_FAILED", err.message);
+            rejectAllWaiters(error.code, error.message);
+            reject(error);
+            if (!closed)
+                scheduleReconnect();
+        }
+    }
+    function connect() {
+        if (ws && ws.readyState === WebSocket.OPEN)
+            return Promise.resolve(ws);
+        if (connectPromise)
+            return connectPromise;
+        connectPromise = new Promise((resolve, reject) => {
+            const socket = new WebSocket(url);
+            ws = socket;
+            // Connection timeout: if neither `open` nor `error` fires within the
+            // deadline, tear down the attempt. Without this, connect() hangs
+            // indefinitely. Editor channels use 30s (slow startups); runtime
+            // channels use 10s (game is either there or dead).
+            const connectTimer = setTimeout(() => {
+                connectPromise = undefined;
+                ws = undefined;
+                socket.removeAllListeners();
+                socket.close();
+                const error = new BridgeError("CONNECT_FAILED", `WebSocket connection to ${url} timed out (${connectTimeout / 1000}s)`);
+                scheduleReconnect();
+                reject(error);
+            }, connectTimeout);
+            connectTimer.unref?.();
+            socket.once("open", () => {
+                clearTimeout(connectTimer);
+                connectPromise = undefined;
+                if (reconnectTimer) {
+                    clearTimeout(reconnectTimer);
+                    reconnectTimer = undefined;
+                }
+                // Note: attempt is reset on successful message round-trip (below),
+                // not on open — open alone isn't proof the peer is healthy. A
+                // half-broken peer that accepts then immediately closes the socket
+                // would otherwise reset backoff every cycle.
+                void performAuth(socket, resolve, reject);
+            });
+            socket.once("error", (err) => {
+                clearTimeout(connectTimer);
+                connectPromise = undefined;
+                ws = undefined;
+                const error = new BridgeError("CONNECT_FAILED", `WebSocket error: ${err.message}`);
+                // Hot path: keep waiters alive across this failure — they'll either
+                // be picked up by a later successful reconnect or hit their per-call
+                // 10s timer. Cold path: the connect()'s rejection here propagates
+                // through awaitOpenSocket → call() so callers see CONNECT_FAILED.
+                scheduleReconnect();
+                reject(error);
+            });
+            socket.on("message", (data) => {
+                let message;
+                try {
+                    message = JSON.parse(data.toString());
+                }
+                catch {
+                    return;
+                }
+                // Plugin notification (no JSON-RPC id, has notification field).
+                if (message.notification && message.id == null) {
+                    process.stderr.write(`[godot-mcp] plugin notification: ${message.notification}\n`);
+                    onNotification?.()?.(message.notification, message.params);
+                    return;
+                }
+                // Mutation-queue notifications from the toolkit: reset the pending
+                // request's timeout so queued commands don't time out on the sidecar.
+                const method = message.method;
+                if ((method === "_queued" || method === "_executing") && message.id == null) {
+                    const reqId = String(message.params?.request_id ?? "");
+                    const queuedPending = pending.get(reqId);
+                    if (queuedPending) {
+                        clearTimeout(queuedPending.timer);
+                        queuedPending.timer = setTimeout(() => {
+                            pending.delete(reqId);
+                            if (method === "_queued") {
+                                // The call was accepted and queued behind other mutations (fair
+                                // FIFO), then ran out its window before its turn — not a stall.
+                                // Mark it so the error mapper serves the serialization-specific
+                                // hint, not the generic "editor is busy" one. Code stays TIMEOUT.
+                                const queuedTimeoutError = new BridgeError("TIMEOUT", `call accepted and serialized behind other mutations; exceeded its ${queuedPending.timeoutMs}ms window while still queued`);
+                                queuedTimeoutError.serializedQueueTimeout = true;
+                                queuedPending.reject(queuedTimeoutError);
+                            }
+                            else {
+                                // Post-_executing: the call was RUNNING when its window closed —
+                                // genuinely slow, not queue wait. Generic timeout shape, no marker.
+                                queuedPending.reject(new BridgeError("TIMEOUT", `call timed out after ${queuedPending.timeoutMs}ms (post-${method})`));
+                            }
+                        }, queuedPending.timeoutMs);
+                    }
+                    return;
+                }
+                const id = message.id;
+                if (id == null)
+                    return;
+                const key = String(id);
+                const pendingRequest = pending.get(key);
+                if (!pendingRequest)
+                    return;
+                clearTimeout(pendingRequest.timer);
+                pending.delete(key);
+                // Reset backoff on successful round-trip.
+                attempt = 0;
+                if (message.error) {
+                    pendingRequest.reject(new BridgeError("RPC_ERROR", `${message.error.code}: ${message.error.message}`));
+                }
+                else {
+                    pendingRequest.resolve(message.result);
+                }
+            });
+            socket.on("close", () => {
+                ws = undefined;
+                rejectAllPending("DISCONNECTED", "WebSocket closed before response");
+                // Auto-reconnect unless the user explicitly closed us.
+                if (!closed)
+                    scheduleReconnect();
+            });
+        });
+        return connectPromise;
+    }
+    function awaitOpenSocket(maxMs) {
+        if (ws && ws.readyState === WebSocket.OPEN)
+            return Promise.resolve(ws);
+        // Cold path: never been connected. Surface failure immediately so
+        // GAME_NOT_RUNNING / first-call-against-dead-editor stay snappy.
+        if (!hasConnectedOnce)
+            return connect();
+        // Hot path: was connected, dropped. Wait up to maxMs for either an
+        // in-flight reconnect to succeed or our timer to fire DISCONNECTED.
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                openWaiters.delete(waiter);
+                reject(new BridgeError("DISCONNECTED", `no connection to ${url} after ${maxMs}ms`));
+            }, maxMs);
+            const waiter = { resolve, reject, timer };
+            openWaiters.add(waiter);
+            // If neither a connect attempt nor a backoff timer is in flight,
+            // kick off a connect now. Otherwise the existing one will eventually
+            // call resolveAllWaiters or scheduleReconnect.
+            if (!connectPromise && !reconnectTimer) {
+                void connect().catch(() => { });
+            }
+        });
+    }
+    return {
+        async call(method, params = null, timeoutMs = DEFAULT_TIMEOUT_MS, signal) {
+            if (closed)
+                throw new BridgeError("CLOSED", "channel is closed");
+            // Pre-aborted guard: if the signal was already aborted before we start,
+            // throw immediately to avoid half-initialized pending state.
+            if (signal?.aborted)
+                throw new BridgeError("CANCELLED", "Request already cancelled");
+            const socket = ws && ws.readyState === WebSocket.OPEN ? ws : await awaitOpenSocket(CALL_AWAIT_RECONNECT_MS);
+            const id = randomUUID();
+            const payload = JSON.stringify({ jsonrpc: JSONRPC_VERSION, id, method, params });
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    reject(new BridgeError("TIMEOUT", `call to ${method} timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                pending.set(id, { resolve, reject, timer, timeoutMs });
+                // Wire up cooperative cancellation: when the MCP client cancels the
+                // request, the SDK aborts this signal, which triggers cancelPending.
+                signal?.addEventListener("abort", () => cancelPending(id), { once: true });
+                socket.send(payload, (err) => {
+                    if (err) {
+                        const pendingRequest = pending.get(id);
+                        if (pendingRequest) {
+                            clearTimeout(pendingRequest.timer);
+                            pending.delete(id);
+                            reject(new BridgeError("SEND_FAILED", err.message));
+                        }
+                    }
+                });
+            });
+        },
+        async close() {
+            closed = true;
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = undefined;
+            }
+            rejectAllPending("CLOSED", "channel closed by caller");
+            rejectAllWaiters("CLOSED", "channel closed by caller");
+            if (ws && ws.readyState === WebSocket.OPEN) {
+                await new Promise((resolve) => {
+                    ws.once("close", () => resolve());
+                    ws.close();
+                });
+            }
+            ws = undefined;
+        },
+    };
+}

package/dist/transport/heartbeat.js

@@ -0,0 +1,54 @@
+/**
+ * A generic, bridge-agnostic liveness primitive: a self-stopping interval that
+ * probes a resource, counts consecutive failures, and runs the owner's teardown
+ * after a threshold. It knows nothing of channels, ports, or the runtime — the
+ * resource-specific bits (the probe, the liveness check, the teardown) are
+ * injected through `ping`/`isAlive`/`onDead`, so the timer policy is
+ * unit-testable in isolation and reusable. The bridge composes it as the
+ * frozen-game detector for the playtest runtime channel.
+ */
+/**
+ * Build a liveness heartbeat. On each tick — before probing — it checks
+ * `isAlive`: a false result stops the timer and skips the probe with NO failure
+ * increment (the load-bearing self-stop guard for a resource that vanished
+ * out-of-band). Otherwise it `await`s `ping`; a resolve resets the
+ * consecutive-failure counter, a reject increments it, and reaching
+ * `maxFailures` fires `onDead` once (the owner's teardown) then stops.
+ */
+export function createHeartbeat(opts) {
+    const { ping, isAlive, onDead, intervalMs, maxFailures } = opts;
+    // Closure state, constructed per primitive (no module-level mutable).
+    let interval = undefined;
+    let failures = 0;
+    function start() {
+        if (interval)
+            return;
+        failures = 0;
+        interval = setInterval(async () => {
+            if (!isAlive()) {
+                stop();
+                return;
+            }
+            try {
+                await ping();
+                failures = 0;
+            }
+            catch {
+                failures++;
+                if (failures >= maxFailures) {
+                    onDead();
+                    stop();
+                }
+            }
+        }, intervalMs);
+        interval.unref?.();
+    }
+    function stop() {
+        if (interval) {
+            clearInterval(interval);
+            interval = undefined;
+        }
+        failures = 0;
+    }
+    return { start, stop };
+}

package/dist/transport/runtimeConnection.js

@@ -0,0 +1,239 @@
+/**
+ * The playtest runtime-connection aggregate.
+ *
+ * Owns the ephemeral playtest channel and everything that keeps it consistent —
+ * the (runtimeChannel, cachedRuntimePort) pair, the registry watcher that
+ * auto-connects/tears-down on playtest start/stop, the port-waiters that
+ * waitForRuntimeConnection parks on, and a composed heartbeat that proactively
+ * clears a frozen game. One reason to change: the runtime-process connection
+ * lifecycle (discover → connect → watch-for-freeze → tear down a playtest
+ * channel). It touches neither version state nor notification routing — that is
+ * why it carves cleanly out of the composition root.
+ *
+ * The channel primitive, the heartbeat primitive, and the six registry reader
+ * fns are injected through an optional `deps` seam (production default = the
+ * real imports) so the aggregate is unit-testable in isolation with fakes. The
+ * seam destructures `deps ?? REAL` at the top into the same bare names the
+ * bodies reference.
+ *
+ * Deps: channel (createChannel, Channel), heartbeat (createHeartbeat), registry
+ * (six reader fns), errors (BridgeError). The composition root (bridge.ts)
+ * constructs one createRuntimeConnection and delegates its callRuntime /
+ * waitForRuntimeConnection / clearRuntime facade methods to it.
+ */
+import { createChannel as realCreateChannel } from "./channel.js";
+import { createHeartbeat as realCreateHeartbeat } from "./heartbeat.js";
+import * as realRegistry from "../registry.js";
+import { BridgeError } from "../shared/errors.js";
+export function createRuntimeConnection(opts, deps) {
+    // DI seam: destructure the injected (or real) collaborators into the same
+    // bare names the bodies reference. The real imports are aliased (real*) so
+    // this default object can name them without shadowing the destructured locals
+    // (a temporal-dead-zone hazard otherwise).
+    const { createChannel, createHeartbeat, registry } = deps ?? {
+        createChannel: realCreateChannel,
+        createHeartbeat: realCreateHeartbeat,
+        registry: realRegistry,
+    };
+    const { discoverRuntime, normalizePath, watchRegistry, unwatchRegistry, isWatcherActive, getCachedRuntimePort } = registry;
+    const projectPath = opts.projectPath;
+    // ── Runtime channel management ───────────────────────────────────
+    // When an explicit port is set, create a static channel. Otherwise,
+    // callRuntime re-reads the registry on each invocation to pick up
+    // newly-started playtests. The channel is cached and recreated only
+    // when the port changes.
+    // Single construction point for all runtime channels (no reconnect, 10s connect timeout).
+    const createRuntimeChannel = (port) => createChannel(`ws://127.0.0.1:${port}`, projectPath, undefined, undefined, {
+        noReconnect: true,
+        connectTimeoutMs: 10_000,
+        // The editor connection runs the authoritative server/toolkit version
+        // check; the runtime ack carries no version, so skip the redundant
+        // (false-positive) check on the runtime channel.
+        skipVersionCheck: true,
+    });
+    let runtimeChannel = opts?.explicitRuntimePort
+        ? createRuntimeChannel(opts.explicitRuntimePort)
+        : undefined;
+    let cachedRuntimePort = opts?.explicitRuntimePort ? Number(opts.explicitRuntimePort) : undefined;
+    let runtimePortResolvers = [];
+    // ── Runtime heartbeat (frozen-game detection) ───────────────────
+    // Pings the runtime every 15s with a 10s timeout. Four consecutive
+    // failures (~60s unresponsive) → proactive teardown. The generous
+    // threshold avoids false positives on poorly-optimized games running
+    // at very low FPS. True freezes (infinite loop) will never respond.
+    // The generic timer/threshold policy lives in heartbeat.ts; the
+    // runtime-state probe + teardown are injected here.
+    const heartbeat = createHeartbeat({
+        // The probe bakes its own 10s timeout (the channel call self-rejects at
+        // 10s), so createHeartbeat runs no timeout race of its own.
+        ping: () => runtimeChannel.call("ping", null, 10_000),
+        // Load-bearing self-stop guard: callRuntime can clear runtimeChannel
+        // WITHOUT stopping us (it relies on the next tick seeing this and
+        // self-stopping — no failure counted).
+        isAlive: () => runtimeChannel !== undefined,
+        onDead: () => {
+            process.stderr.write("[bridge] heartbeat failed 4x (~60s) — runtime dead/frozen, clearing\n");
+            if (runtimeChannel) {
+                void runtimeChannel.close();
+                runtimeChannel = undefined;
+                cachedRuntimePort = undefined;
+            }
+        },
+        intervalMs: 15_000,
+        maxFailures: 4,
+    });
+    // ── Registry watcher for instant runtime discovery ─────────────
+    // fs.watch on projects.json auto-connects to new runtime ports and
+    // tears down stale channels. Replaces per-RPC file reads in
+    // callRuntime with in-memory lookups (Path A). Falls back to
+    // per-RPC reads when fs.watch is unavailable (Path B).
+    if (projectPath && !opts?.explicitRuntimePort) {
+        const normalizedProject = normalizePath(projectPath);
+        watchRegistry({
+            onDiscovered: (discoveredPath, port) => {
+                if (discoveredPath !== normalizedProject)
+                    return;
+                process.stderr.write(`[bridge] runtime discovered on port ${port}\n`);
+                if (runtimeChannel)
+                    void runtimeChannel.close();
+                runtimeChannel = createRuntimeChannel(port);
+                cachedRuntimePort = port;
+                heartbeat.start();
+                // Notify any pending waitForRuntimeConnection callers.
+                const resolvers = runtimePortResolvers;
+                runtimePortResolvers = [];
+                for (const resolve of resolvers)
+                    resolve(port);
+            },
+            onRemoved: (removedPath) => {
+                if (removedPath !== normalizedProject)
+                    return;
+                process.stderr.write(`[bridge] runtime removed\n`);
+                heartbeat.stop();
+                if (runtimeChannel) {
+                    void runtimeChannel.close();
+                    runtimeChannel = undefined;
+                    cachedRuntimePort = undefined;
+                }
+            },
+        });
+    }
+    return {
+        async callRuntime(method, params, timeoutMs, signal) {
+            // Static port override — same as explicit-port behaviour.
+            if (opts?.explicitRuntimePort) {
+                // The pinned channel is built once at construct, but clearRuntime()
+                // (game_stopped notification on game stop/crash) nulls it. Unlike the
+                // discovery path there is no watcher to rebuild it, so lazily re-create
+                // it against the pinned port here — otherwise the next call dereferences
+                // an undefined channel and every runtime tool is dead until restart.
+                if (!runtimeChannel) {
+                    runtimeChannel = createRuntimeChannel(opts.explicitRuntimePort);
+                    cachedRuntimePort = Number(opts.explicitRuntimePort);
+                }
+                try {
+                    return await runtimeChannel.call(method, params, timeoutMs, signal);
+                }
+                catch (err) {
+                    if (err instanceof BridgeError && (err.code === "CONNECT_FAILED" || err.code === "DISCONNECTED")) {
+                        throw new BridgeError("GAME_NOT_RUNNING", `no runtime server on 127.0.0.1:${opts.explicitRuntimePort} — start the game in the editor (F5) with a debug build`);
+                    }
+                    throw err;
+                }
+            }
+            // Registry-based discovery.
+            if (!projectPath) {
+                throw new BridgeError("GAME_NOT_RUNNING", "no runtime port configured and no project path for registry lookup");
+            }
+            // Fast path: if clearRuntime() was called (game_stopped notification),
+            // trust it over the potentially-stale registry cache. The registry
+            // watcher has a 100ms debounce — during that window getCachedRuntimePort
+            // still returns the old port. Don't create a doomed channel to it.
+            if (!runtimeChannel && cachedRuntimePort === undefined) {
+                const freshPort = isWatcherActive() ? getCachedRuntimePort(projectPath) : discoverRuntime(projectPath);
+                if (freshPort === null) {
+                    throw new BridgeError("GAME_NOT_RUNNING", "no runtime_port in registry — start the game in the editor (F5) with a debug build");
+                }
+                // Registry still has a port — either watcher is stale (race) or a new
+                // game started before we ran. Re-read the file to break the debounce.
+                const diskPort = discoverRuntime(projectPath);
+                if (diskPort === null) {
+                    throw new BridgeError("GAME_NOT_RUNNING", "game stopped (runtime cleared by notification, registry not yet updated)");
+                }
+                // Disk confirms a port exists — new game started. Create channel.
+                runtimeChannel = createRuntimeChannel(diskPort);
+                cachedRuntimePort = diskPort;
+            }
+            else {
+                // Normal path: consult registry cache.
+                const currentPort = isWatcherActive() ? getCachedRuntimePort(projectPath) : discoverRuntime(projectPath);
+                if (currentPort === null) {
+                    // No playtest running — close stale channel and reject immediately.
+                    if (runtimeChannel) {
+                        await runtimeChannel.close();
+                        runtimeChannel = undefined;
+                        cachedRuntimePort = undefined;
+                    }
+                    throw new BridgeError("GAME_NOT_RUNNING", "no runtime_port in registry — start the game in the editor (F5) with a debug build");
+                }
+                // Port changed (new playtest or different runtime instance).
+                if (currentPort !== cachedRuntimePort) {
+                    if (runtimeChannel)
+                        await runtimeChannel.close();
+                    runtimeChannel = createRuntimeChannel(currentPort);
+                    cachedRuntimePort = currentPort;
+                }
+            }
+            try {
+                return await runtimeChannel.call(method, params, timeoutMs, signal);
+            }
+            catch (err) {
+                if (err instanceof BridgeError && (err.code === "CONNECT_FAILED" || err.code === "DISCONNECTED")) {
+                    const failedPort = cachedRuntimePort;
+                    await runtimeChannel.close();
+                    runtimeChannel = undefined;
+                    cachedRuntimePort = undefined;
+                    throw new BridgeError("GAME_NOT_RUNNING", `runtime server on port ${failedPort} is not responding — playtest may have ended`);
+                }
+                throw err;
+            }
+        },
+        waitForRuntimeConnection(timeoutMs) {
+            if (!projectPath)
+                return Promise.resolve(undefined);
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    runtimePortResolvers = runtimePortResolvers.filter((r) => r !== handler);
+                    resolve(undefined);
+                }, timeoutMs);
+                timer.unref?.();
+                const handler = (port) => {
+                    clearTimeout(timer);
+                    runtimePortResolvers = runtimePortResolvers.filter((r) => r !== handler);
+                    resolve(port != null ? { port } : undefined);
+                };
+                runtimePortResolvers.push(handler);
+            });
+        },
+        clearRuntime() {
+            heartbeat.stop();
+            if (runtimeChannel) {
+                void runtimeChannel.close();
+                runtimeChannel = undefined;
+                cachedRuntimePort = undefined;
+                process.stderr.write("[bridge] runtime cleared (game_stopped notification)\n");
+            }
+        },
+        async close() {
+            heartbeat.stop();
+            // Resolve outstanding runtime-port waiters as undefined (bridge closing).
+            const resolvers = runtimePortResolvers;
+            runtimePortResolvers = [];
+            for (const resolve of resolvers)
+                resolve(undefined);
+            unwatchRegistry();
+            if (runtimeChannel)
+                await runtimeChannel.close();
+        },
+    };
+}