@downdraft/engine 0.1.1 → 0.2.0

package/dist/mcp/src/client.js

@@ -0,0 +1,669 @@
+// ============================================================================
+// GameClient — client for a running game's in-process MCP automation endpoint.
+//
+// A running game (draft dev / draft test / launchGame) exposes a JSON-RPC
+// over HTTP endpoint on 127.0.0.1 (McpHttpTransport) and advertises its port
+// via ~/.downdraft/port/<pid>. This module is the single implementation of
+// the client side of that wire — previously triplicated across
+// scripts/mcp-call.mjs, .devin/mcp-stdio-bridge.mjs, and tests/e2e/harness.ts.
+//
+//   import { GameClient, launchGame } from "@downdraft/engine/mcp/client";
+//
+//   const client = await GameClient.connect();          // PID-file discovery
+//   const tools = await client.listTools();
+//   const state = await client.callJson("get_world_state");
+//   await client.screenshot("shot.png");
+//
+//   // Or launch + connect + kill in one:
+//   const game = await launchGame({ game: "to-the-ocean" });
+//   await game.client.callText("get_player_state");
+//   await game.kill();
+//
+// Node- and Bun-compatible: only node: APIs + fetch, no Bun.* globals.
+// ============================================================================
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+const DEFAULT_TIMEOUT_MS = 120_000;
+export class McpClientError extends Error {
+}
+// ---------------------------------------------------------------------------
+// Instance discovery — ~/.downdraft/port/<pid> PID files
+// ---------------------------------------------------------------------------
+/** Directory holding one PID file per running game instance. Each file is
+ *  named `<pid>` and contains the bound MCP HTTP port; a sibling
+ *  `<pid>.token` holds the bearer token when the instance requires auth. */
+export function mcpPortDir() {
+    return join(homedir(), ".downdraft", "port");
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/** Best-effort appId recovery: read /proc/<pid>/cmdline and return the
+ *  basename of --user-data-dir=<path>. Returns undefined on non-Linux or
+ *  when the arg is absent. */
+function readAppId(pid) {
+    if (process.platform !== "linux")
+        return undefined;
+    try {
+        const raw = readFileSync(`/proc/${pid}/cmdline`, "utf8");
+        const m = /--user-data-dir=(\S+)/.exec(raw.replace(/\0+$/g, "").replace(/\0/g, " "));
+        return m ? basename(m[1]) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** List all live game instances, newest-first. Dead PID files are pruned
+ *  as a side effect. */
+export function listGameInstances(sel = {}) {
+    let entries;
+    try {
+        entries = readdirSync(mcpPortDir());
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    // Group files by PID: "<pid>" is the automation endpoint, "<pid>.editor"
+    // the editor toolset endpoint (createMcpModule http transport). Token
+    // siblings "<pid>.token" / "<pid>.editor.token" don't match the regex.
+    const byPid = new Map();
+    for (let _i = 0, _it = entries, _n = _it.length; _i < _n; _i++) {
+        const name = _it[_i];
+        const m = /^(\d+)(\.editor)?$/.exec(name);
+        if (!m)
+            continue;
+        const rec = byPid.get(Number(m[1])) ?? {};
+        if (m[2])
+            rec.editor = name;
+        else
+            rec.automation = name;
+        byPid.set(Number(m[1]), rec);
+    }
+    const readPort = (file) => {
+        if (!file)
+            return undefined;
+        try {
+            const raw = readFileSync(join(mcpPortDir(), file), "utf8").trim();
+            return /^\d+$/.test(raw) ? Number(raw) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const readToken = (file) => {
+        if (!file)
+            return undefined;
+        try {
+            return readFileSync(join(mcpPortDir(), `${file}.token`), "utf8").trim() || undefined;
+        }
+        catch { /* no token file — auth not required */ }
+        return undefined;
+    };
+    for (const [pid, files] of byPid.entries()) {
+        if (!isAlive(pid)) {
+            [files.automation, files.editor].forEach((f) => {
+                if (!f)
+                    return;
+                try {
+                    unlinkSync(join(mcpPortDir(), f));
+                }
+                catch { /* gone */ }
+                try {
+                    unlinkSync(join(mcpPortDir(), `${f}.token`));
+                }
+                catch { /* gone */ }
+            });
+            continue;
+        }
+        if (sel.pid !== undefined && pid !== sel.pid)
+            continue;
+        const appId = readAppId(pid);
+        if (sel.appId !== undefined && appId !== undefined && appId !== sel.appId)
+            continue;
+        if (sel.appId !== undefined && appId === undefined && process.platform === "linux")
+            continue;
+        const port = readPort(files.automation);
+        const editorPort = readPort(files.editor);
+        if (port === undefined && editorPort === undefined)
+            continue;
+        let mtimeMs = 0;
+        [files.automation, files.editor].forEach((f) => {
+            if (!f)
+                return;
+            try {
+                mtimeMs = Math.max(mtimeMs, statSync(join(mcpPortDir(), f)).mtimeMs);
+            }
+            catch { /* treat as oldest */ }
+        });
+        out.push({
+            pid,
+            port,
+            editorPort,
+            token: readToken(files.automation),
+            editorToken: readToken(files.editor),
+            mtimeMs,
+            appId,
+        });
+    }
+    out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return out;
+}
+/** Pick the newest live instance matching the selector, or null. */
+export function discoverGameInstance(sel = {}) {
+    return listGameInstances(sel)[0] ?? null;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export class GameClient {
+    url;
+    pid;
+    token;
+    sessionId = null;
+    reqId = 0;
+    defaultTimeout;
+    constructor(url, token, pid, timeoutMs) {
+        this.url = url;
+        this.token = token;
+        this.pid = pid;
+        this.defaultTimeout = timeoutMs;
+    }
+    /**
+     * Connect to a running game instance. With no selector, attaches to the
+     * newest live instance in ~/.downdraft/port/. Performs the `initialize`
+     * handshake before returning.
+     */
+    static async connect(opts = {}) {
+        // Env fallbacks: DOWNDRAFT_MCP_URL/MCP_HTTP_URL for explicit targets,
+        // MCP_APP_ID/MCP_PID for discovery selectors — the same selectors the
+        // old stdio bridge honored, so existing configs keep working.
+        const envPid = Number(process.env.MCP_PID);
+        const appId = opts.appId ?? process.env.MCP_APP_ID;
+        let pid = opts.pid ?? (Number.isFinite(envPid) && envPid > 0 ? envPid : undefined);
+        let url = opts.url ?? process.env.DOWNDRAFT_MCP_URL ?? process.env.MCP_HTTP_URL;
+        let token = opts.token ?? process.env.DOWNDRAFT_MCP_TOKEN ?? process.env.MCP_TOKEN;
+        const endpoint = opts.endpoint ?? (process.env.DOWNDRAFT_MCP_ENDPOINT === "editor" ? "editor" : "automation");
+        if (!url) {
+            const inst = discoverGameInstance({ appId, pid });
+            if (!inst) {
+                const filter = appId
+                    ? ` with appId "${appId}"`
+                    : pid !== undefined
+                        ? ` with PID ${pid}`
+                        : "";
+                throw new McpClientError(`No running downdraft game instance found${filter} in ${mcpPortDir()}. ` +
+                    `Start a game first (e.g. \`draft dev\`), or pass url / set DOWNDRAFT_MCP_URL.`);
+            }
+            const instPort = endpoint === "editor" ? inst.editorPort : inst.port;
+            if (instPort === undefined) {
+                throw new McpClientError(`Instance ${inst.pid} has no ${endpoint} MCP endpoint in ${mcpPortDir()}` +
+                    (endpoint === "editor"
+                        ? ` — register createMcpModule({ transport: "http" }) in the game, or drop the editor endpoint selection.`
+                        : "."));
+            }
+            url = `http://localhost:${instPort}/mcp`;
+            token ??= endpoint === "editor" ? (inst.editorToken ?? inst.token) : inst.token;
+            pid = inst.pid;
+        }
+        const client = new GameClient(url, token, pid, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        await client.rpc("initialize", {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "downdraft-game-client", version: "0.1.0" },
+        }, 10_000);
+        return client;
+    }
+    headers() {
+        const h = {
+            "Content-Type": "application/json",
+            // Deliberately no text/event-stream — the transport then answers
+            // with plain JSON instead of SSE framing.
+            "Accept": "application/json",
+        };
+        if (this.sessionId)
+            h["Mcp-Session-Id"] = this.sessionId;
+        if (this.token)
+            h["X-Downdraft-Token"] = this.token;
+        return h;
+    }
+    async rpc(method, params = {}, timeoutMs) {
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({ jsonrpc: "2.0", id: ++this.reqId, method, params }),
+            signal: AbortSignal.timeout(timeoutMs ?? this.defaultTimeout),
+        });
+        const sid = res.headers.get("Mcp-Session-Id");
+        if (sid)
+            this.sessionId = sid;
+        const text = await res.text();
+        if (!res.ok)
+            throw new McpClientError(`MCP HTTP ${res.status}: ${text.slice(0, 500)}`);
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new McpClientError(`Non-JSON response: ${text.slice(0, 500)}`);
+        }
+        if (json.error)
+            throw new McpClientError(`MCP error ${json.error.code}: ${json.error.message}`);
+        // Proxy mode wraps handler errors in result.error — surface those too.
+        const result = json.result;
+        if (result?.error)
+            throw new McpClientError(`MCP error ${result.error.code}: ${result.error.message}`);
+        return json.result;
+    }
+    /** Raw JSON-RPC method call — for methods without a typed helper
+     *  (resources/read, prompts/get) and the stdio bridge's forwarding. */
+    async request(method, params = {}, timeoutMs) {
+        return this.rpc(method, params, timeoutMs);
+    }
+    /** tools/list — the tool defs the game registered. */
+    async listTools() {
+        const result = (await this.rpc("tools/list", {}, 10_000));
+        return result.tools ?? [];
+    }
+    /** tools/call — returns the raw {content, isError} envelope. */
+    async call(name, args = {}, opts = {}) {
+        return (await this.rpc("tools/call", { name, arguments: args }, opts.timeoutMs));
+    }
+    textOrThrow(result) {
+        const text = (result.content ?? [])
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("\n");
+        if (result.isError)
+            throw new McpClientError(`MCP tool returned an error: ${text}`);
+        return text;
+    }
+    /** tools/call → concatenated text content; throws when isError. */
+    async callText(name, args = {}, opts = {}) {
+        return this.textOrThrow(await this.call(name, args, opts));
+    }
+    /** tools/call → JSON.parse of the text content; throws on isError or
+     *  non-JSON output. */
+    async callJson(name, args = {}, opts = {}) {
+        const text = this.textOrThrow(await this.call(name, args, opts));
+        try {
+            return JSON.parse(text);
+        }
+        catch (e) {
+            throw new McpClientError(`MCP tool returned non-JSON text: ${e.message} | ${text.slice(0, 200)}`);
+        }
+    }
+    /** Retry on transport/connection errors only — tool-level isError
+     *  results are thrown immediately. */
+    async callWithRetry(name, args = {}, opts = {}) {
+        const maxRetries = opts.retries ?? 3;
+        const backoffMs = opts.backoffMs ?? 500;
+        let lastError = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const result = await this.call(name, args, opts);
+                if (result.isError) {
+                    throw new McpClientError(`MCP tool returned an error: ${result.content?.[0] && "text" in result.content[0] ? result.content[0].text : ""}`);
+                }
+                return result;
+            }
+            catch (e) {
+                lastError = e;
+                const msg = lastError.message;
+                const isTransportError = msg.includes("MCP HTTP") ||
+                    msg.includes("fetch failed") ||
+                    msg.includes("aborted") ||
+                    msg.includes("ECONNREFUSED") ||
+                    msg.includes("MCP error");
+                if (!isTransportError || attempt === maxRetries)
+                    throw lastError;
+                await sleep(backoffMs * (attempt + 1));
+            }
+        }
+        throw lastError ?? new McpClientError("callWithRetry exhausted retries");
+    }
+    /** capture_screenshot → write the image block to `path` as PNG. Returns
+     *  the dimensions from the tool's text metadata. */
+    async screenshot(path, args = {}) {
+        const result = await this.call("capture_screenshot", { fullPage: true, ...args });
+        const text = this.textOrThrow(result);
+        let meta = {};
+        try {
+            meta = JSON.parse(text);
+        }
+        catch { /* older tools may not emit meta */ }
+        const image = result.content.find((c) => c.type === "image");
+        if (!image?.data)
+            throw new McpClientError("capture_screenshot returned no image data");
+        mkdirSync(dirname(resolve(path)), { recursive: true });
+        writeFileSync(path, Buffer.from(image.data, "base64"));
+        return { width: meta.width ?? 0, height: meta.height ?? 0 };
+    }
+    /**
+     * Wait until the instance is serving MCP and has registered tools:
+     * poll GET /mcp/health, then initialize + tools/list until non-empty.
+     * `proc` (optional) enables fail-fast when a launched game dies early.
+     * A final capture_screenshot probe warns (non-fatal) when WebGPU isn't
+     * producing frames yet — mirrors the e2e harness's readiness check.
+     */
+    async waitForReady(timeoutMs = 90_000, opts = {}) {
+        const healthUrl = this.url.replace(/\/mcp\/?$/, "/mcp/health");
+        const deadline = Date.now() + timeoutMs;
+        let lastErr = "";
+        const alive = () => !opts.proc || (opts.proc.exitCode === null && !opts.proc.killed);
+        const failIfDead = (stage) => {
+            if (!alive())
+                throw new McpClientError(`Game process exited before ${stage} became ready`);
+        };
+        while (Date.now() < deadline) {
+            failIfDead("MCP health endpoint");
+            try {
+                const res = await fetch(healthUrl, {
+                    headers: this.token ? { "X-Downdraft-Token": this.token } : {},
+                    signal: AbortSignal.timeout(5_000),
+                });
+                if (res.ok)
+                    break;
+                lastErr = `HTTP ${res.status}`;
+            }
+            catch (e) {
+                lastErr = e.message;
+            }
+            await sleep(250);
+        }
+        if (Date.now() >= deadline) {
+            throw new McpClientError(`MCP health endpoint did not become ready at ${healthUrl}: ${lastErr}`);
+        }
+        while (Date.now() < deadline) {
+            failIfDead("MCP tools");
+            try {
+                const tools = await this.listTools();
+                if (tools.length > 0)
+                    break;
+                lastErr = "tools list empty";
+            }
+            catch (e) {
+                lastErr = e.message;
+            }
+            await sleep(1_000);
+        }
+        if (Date.now() >= deadline) {
+            throw new McpClientError(`MCP tools did not become available at ${this.url}: ${lastErr}`);
+        }
+        // Best-effort readiness probe: a valid screenshot implies WebGPU is
+        // initialized. Warn but don't fail — some games can't screenshot in
+        // their initial state.
+        const probeDeadline = Math.min(Date.now() + 30_000, deadline + 30_000);
+        let lastProbeErr = "";
+        while (Date.now() < probeDeadline) {
+            failIfDead("readiness probe");
+            try {
+                const result = await this.call("capture_screenshot", { fullPage: false }, { timeoutMs: 10_000 });
+                if (!result.isError && result.content?.some((c) => c.type === "image" && c.data))
+                    return;
+                lastProbeErr = result.isError
+                    ? `capture_screenshot error: ${result.content?.[0] && "text" in result.content[0] ? result.content[0].text : ""}`
+                    : "capture_screenshot returned no image data";
+            }
+            catch (e) {
+                lastProbeErr = e.message;
+            }
+            await sleep(1_000);
+        }
+        process.stderr.write(`[GameClient] readiness probe failed (non-fatal): ${lastProbeErr}\n`);
+    }
+    // ── Harness-compat aliases (the old tests/e2e McpClient interface) ──
+    callTool(name, args = {}, opts = {}) {
+        return this.call(name, args, opts);
+    }
+    callToolWithRetry(name, args = {}, opts = {}) {
+        return this.callWithRetry(name, args, opts);
+    }
+    close() {
+        // Stateless HTTP — nothing to tear down.
+    }
+}
+/** Find a free loopback TCP port (OS-assigned). */
+export function findFreePort() {
+    return new Promise((resolvePort, reject) => {
+        const srv = createServer();
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            srv.close(() => (port ? resolvePort(port) : reject(new Error("no port assigned"))));
+        });
+        srv.on("error", reject);
+    });
+}
+const DEFAULT_ERROR_PATTERNS = [
+    /Uncaught/i,
+    /TypeError:/,
+    /ReferenceError:/,
+    /SyntaxError:/,
+    /RangeError:/,
+    /WrongDocumentError:/,
+    /is not a function/,
+    /is not defined/,
+    /cannot read propert/i,
+    /REJECTED action/i,
+    /GPU process exited unexpectedly/i,
+    /WebGPU.*not available/i,
+    /adapter request failed/i,
+    /\[.*WorkerHost.*\]\s*[Ww]orker error:/i,
+];
+const DEFAULT_IGNORE_PATTERNS = [
+    /ERROR:components\/services\/storage/,
+    /ERROR:storage\/browser/,
+    /Gtk-Message/,
+    /deprecated.*session\.loadExtension/,
+    /SandboxOriginDatabase/,
+    /Failed to load module.*xapp-gtk3/,
+    /Failed to delete the database/,
+    /Could not open the quota database/,
+    /WebSocket connection.*failed/,
+    /gc.*does not exist/,
+    /Physics re-initialized after panic/i,
+    /Slow (tick|physics)/,
+];
+function isRealError(line, extraIgnorePatterns = []) {
+    const stripped = line.replace(/\x1b\[[0-9;]*m/g, "").replace(/\x1b\[[0-9;]*/g, "");
+    if (!DEFAULT_ERROR_PATTERNS.some((p) => p.test(stripped)))
+        return false;
+    if (DEFAULT_IGNORE_PATTERNS.some((p) => p.test(stripped)))
+        return false;
+    return !extraIgnorePatterns.some((p) => p.test(stripped));
+}
+/** Collect all descendant PIDs of `rootPid` by walking /proc/<pid>/stat on
+ *  Linux. Backup for helpers that called setsid and escaped the process
+ *  group — the group signal alone would miss them. */
+function collectDescendants(rootPid) {
+    const childrenOf = new Map();
+    try {
+        for (const entry of readdirSync("/proc")) {
+            if (!/^\d+$/.test(entry))
+                continue;
+            const pid = Number(entry);
+            if (pid === rootPid)
+                continue;
+            try {
+                const stat = readFileSync(`/proc/${entry}/stat`, "utf8");
+                const rparen = stat.lastIndexOf(")");
+                if (rparen < 0)
+                    continue;
+                const ppid = Number(stat.slice(rparen + 2).split(" ")[1]);
+                if (ppid === rootPid || childrenOf.has(ppid)) {
+                    const list = childrenOf.get(ppid) ?? [];
+                    list.push(pid);
+                    childrenOf.set(ppid, list);
+                }
+            }
+            catch {
+                // Process exited between readdir and read — ignore.
+            }
+        }
+    }
+    catch {
+        return []; // /proc unavailable (non-Linux)
+    }
+    const result = [];
+    const queue = [rootPid];
+    while (queue.length) {
+        const cur = queue.shift();
+        (childrenOf.get(cur) ?? []).forEach((k) => {
+            result.push(k);
+            queue.push(k);
+        });
+    }
+    return result;
+}
+/**
+ * Launch a game on the native runtime (`bun <entry>`), wait for its MCP
+ * endpoint to serve tools, and return a connected GameClient plus a kill()
+ * that tears down the whole process tree (detached group kill + /proc
+ * descendant sweep — the game must not outlive the caller).
+ */
+export async function launchGame(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const game = opts.game ?? "to-the-ocean";
+    const entry = opts.entry
+        ? resolve(cwd, opts.entry)
+        : [
+            resolve(cwd, "games", game, "src", "native-entry.ts"),
+            resolve(cwd, "examples", game, "src", "native-entry.ts"),
+            resolve(cwd, "src", "native-entry.ts"),
+        ].find((p) => existsSync(p)) ?? resolve(cwd, "games", game, "src", "native-entry.ts");
+    if (!existsSync(entry)) {
+        throw new McpClientError(`Game entry not found: ${entry} (pass --entry or game:)`);
+    }
+    const port = opts.port ?? (await findFreePort());
+    const env = {
+        ...process.env,
+        MCP_PORT: String(port),
+        MCP_TIMEOUT_MS: String(DEFAULT_TIMEOUT_MS),
+        DOWNDRAFT_GPU: opts.gpu ?? process.env.DOWNDRAFT_GPU ?? "swiftshader",
+        ...(opts.deterministic ? { DOWNDRAFT_DETERMINISTIC: "1" } : {}),
+        ...(opts.headed ? { DOWNDRAFT_HEADED: "1" } : {}),
+        ...opts.env,
+    };
+    const proc = spawn("bun", [entry], {
+        cwd,
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        // New session → child is a process-group leader, so kill(-pid)
+        // reaches helpers that get re-parented to init.
+        detached: true,
+    });
+    const exited = new Promise((res) => proc.once("exit", (code) => res(code)));
+    // Capture console output lines to detect JS errors.
+    const consoleErrors = [];
+    const watchStream = (stream, mirror) => {
+        if (!stream)
+            return;
+        let buf = "";
+        stream.on("data", (chunk) => {
+            const text = chunk.toString();
+            buf += text;
+            if (opts.mirrorOutput)
+                mirror(text);
+            const lines = buf.split("\n");
+            buf = lines.pop() ?? "";
+            lines.forEach((line) => {
+                if (isRealError(line, opts.ignoreErrorPatterns)) {
+                    consoleErrors.push(line.replace(/\x1b\[[0-9;]*m/g, "").trim());
+                }
+            });
+        });
+    };
+    watchStream(proc.stdout, (s) => process.stdout.write(s));
+    watchStream(proc.stderr, (s) => process.stderr.write(s));
+    const kill = async () => {
+        const pid = proc.pid;
+        const signalAll = (sig) => {
+            if (pid) {
+                try {
+                    process.kill(-pid, sig);
+                }
+                catch { /* group already gone */ }
+                [pid, ...collectDescendants(pid)].forEach((p) => {
+                    try {
+                        process.kill(p, sig);
+                    }
+                    catch { /* already dead */ }
+                });
+            }
+            else {
+                try {
+                    proc.kill(sig);
+                }
+                catch { /* already dead */ }
+            }
+        };
+        signalAll("SIGTERM");
+        try {
+            await Promise.race([
+                exited,
+                new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 5_000)),
+            ]);
+        }
+        catch {
+            signalAll("SIGKILL");
+            try {
+                await exited;
+            }
+            catch { /* gone */ }
+        }
+    };
+    // The token file (when required) is written synchronously at server
+    // bind — poll briefly so callers don't race it.
+    let token;
+    {
+        const tokenFile = join(mcpPortDir(), `${proc.pid}.token`);
+        const deadline = Date.now() + 15_000;
+        while (Date.now() < deadline && proc.exitCode === null) {
+            if (existsSync(tokenFile)) {
+                try {
+                    token = readFileSync(tokenFile, "utf8").trim() || undefined;
+                }
+                catch { /* retry */ }
+                break;
+            }
+            // No token file → auth not required; don't wait for a file that
+            // will never appear. But it also may just not be written yet —
+            // the transport always writes one, so if the pid file exists
+            // but the token doesn't, auth is genuinely off.
+            if (existsSync(join(mcpPortDir(), String(proc.pid))))
+                break;
+            await sleep(100);
+        }
+    }
+    const client = await GameClient.connect({
+        url: `http://localhost:${port}/mcp`,
+        token,
+        timeoutMs: opts.timeoutMs,
+    }).catch(async (e) => { await kill(); throw e; });
+    try {
+        await client.waitForReady(opts.timeoutMs ?? 90_000, { proc });
+    }
+    catch (e) {
+        await kill();
+        throw e;
+    }
+    return {
+        client,
+        process: proc,
+        pid: proc.pid ?? 0,
+        port,
+        token,
+        getConsoleErrors: () => [...consoleErrors],
+        kill,
+    };
+}