godot-mcp-runtime 2.3.0 → 3.1.0

package/dist/utils/godot-runner.js

@@ -1,20 +1,36 @@
 import { fileURLToPath } from 'url';
-import { join, dirname, normalize } from 'path';
-import { existsSync, readFileSync, writeFileSync, copyFileSync, unlinkSync, mkdirSync } from 'fs';
+import { join, dirname, normalize, resolve, sep } from 'path';
+import { existsSync } from 'fs';
 import { spawn } from 'child_process';
-import { createSocket } from 'dgram';
+import * as net from 'net';
 import { randomBytes } from 'crypto';
+import { BridgeManager } from './bridge-manager.js';
+import { DEFAULT_BRIDGE_PORT, encodeFrame, findFreePort, parseFrames, FRAME_HEADER_BYTES, MAX_FRAME_BYTES, } from './bridge-protocol.js';
+import { logDebug, logError, DEBUG_MODE } from './logger.js';
+/**
+ * Thrown when the bridge socket closes (Godot exited, port closed, or peer
+ * dropped the connection mid-flight). Lets callers distinguish
+ * "session ended" from generic transport errors.
+ */
+export class BridgeDisconnectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BridgeDisconnectedError';
+    }
+}
 // Derive __filename and __dirname in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-// Debug mode from environment
-const DEBUG_MODE = process.env.DEBUG === 'true';
 // Bridge readiness polling
-const BRIDGE_WAIT_SPAWNED_TIMEOUT_MS = 8000;
+export const BRIDGE_WAIT_SPAWNED_TIMEOUT_MS = 8000;
 const BRIDGE_WAIT_SPAWNED_INTERVAL_MS = 300;
 const BRIDGE_WAIT_ATTACHED_TIMEOUT_MS = 15000;
 const BRIDGE_WAIT_ATTACHED_INTERVAL_MS = 500;
 const BRIDGE_PING_TIMEOUT_MS = 1000;
+const BRIDGE_SHUTDOWN_SPAWNED_TIMEOUT_MS = 500;
+const BRIDGE_SHUTDOWN_ATTACHED_TIMEOUT_MS = 1500;
+const BRIDGE_PROCESS_EXIT_TIMEOUT_MS = 2000;
+const BRIDGE_RECONNECT_DELAY_MS = 1000;
 /**
  * Normalize a path for cross-platform comparison.
  * Folds Windows backslashes to forward slashes and strips trailing slashes,
@@ -94,35 +110,50 @@ export function cleanOutput(output) {
     });
     return cleanedLines.join('\n');
 }
+export function cleanStdout(stdout) {
+    if (stdout.includes('{') || stdout.includes('[')) {
+        return extractJson(stdout);
+    }
+    return cleanOutput(stdout);
+}
 // Parameter mappings between snake_case and camelCase
+// Add new entries whenever a tool surfaces a new compound parameter — the
+// strict converter throws in test env on unmapped keys to catch oversights.
 const parameterMappings = {
     project_path: 'projectPath',
     scene_path: 'scenePath',
     root_node_type: 'rootNodeType',
     parent_node_path: 'parentNodePath',
+    parent_path: 'parentPath',
     node_type: 'nodeType',
     node_name: 'nodeName',
     texture_path: 'texturePath',
     node_path: 'nodePath',
+    node_paths: 'nodePaths',
+    target_node_path: 'targetNodePath',
+    target_parent_path: 'targetParentPath',
+    new_name: 'newName',
     output_path: 'outputPath',
     mesh_item_names: 'meshItemNames',
     new_path: 'newPath',
     file_path: 'filePath',
     script_path: 'scriptPath',
+    response_mode: 'responseMode',
+    preview_max_width: 'previewMaxWidth',
+    preview_max_height: 'previewMaxHeight',
+    bridge_port: 'bridgePort',
+    abort_on_error: 'abortOnError',
+    max_depth: 'maxDepth',
+    changed_only: 'changedOnly',
+    case_sensitive: 'caseSensitive',
+    file_types: 'fileTypes',
+    max_results: 'maxResults',
 };
 // Reverse mapping from camelCase to snake_case
 const reverseParameterMappings = {};
 for (const [snakeCase, camelCase] of Object.entries(parameterMappings)) {
     reverseParameterMappings[camelCase] = snakeCase;
 }
-export function logDebug(message) {
-    if (DEBUG_MODE) {
-        console.error(`[DEBUG] ${message}`);
-    }
-}
-export function logError(message) {
-    console.error(`[SERVER] ${message}`);
-}
 export function normalizeParameters(params) {
     if (!params || typeof params !== 'object') {
         return params;
@@ -145,29 +176,116 @@ export function normalizeParameters(params) {
     }
     return result;
 }
+function convertCamelToSnakeValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => convertCamelToSnakeValue(entry));
+    }
+    if (typeof value === 'object' && value !== null) {
+        return convertCamelToSnakeCase(value);
+    }
+    return value;
+}
 export function convertCamelToSnakeCase(params) {
     const result = {};
+    const isTestEnv = process.env.NODE_ENV === 'test' || process.env.VITEST === 'true';
     for (const key in params) {
         if (Object.prototype.hasOwnProperty.call(params, key)) {
-            const snakeKey = reverseParameterMappings[key] ||
-                key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-            const value = params[key];
-            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                result[snakeKey] = convertCamelToSnakeCase(value);
+            const mapped = reverseParameterMappings[key];
+            let snakeKey;
+            if (mapped) {
+                snakeKey = mapped;
+            }
+            else if (/[A-Z]/.test(key)) {
+                // Unmapped camelCase key — tolerated in production via regex fallback,
+                // but in tests we throw to catch missing entries in parameterMappings.
+                if (isTestEnv) {
+                    throw new Error(`convertCamelToSnakeCase: unmapped camelCase key '${key}'. ` +
+                        `Add it to parameterMappings in src/utils/godot-runner.ts so snake/camel conversion stays explicit.`);
+                }
+                snakeKey = key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
             }
             else {
-                result[snakeKey] = value;
+                snakeKey = key;
             }
+            result[snakeKey] = convertCamelToSnakeValue(params[key]);
         }
     }
     return result;
 }
+/**
+ * Check whether a display server (X11 / Wayland) is available on the current
+ * platform.  On macOS and Windows the display subsystem is always present;
+ * on Linux we probe the standard environment variables.
+ */
+export function checkDisplayAvailable() {
+    if (process.platform !== 'linux')
+        return true;
+    return !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+}
 export function validatePath(path) {
     if (!path || path.includes('..')) {
         return false;
     }
     return true;
 }
+/**
+ * Stricter check for paths that must stay inside `projectPath`. Rejects `..`
+ * (via `validatePath`) and absolute paths that escape the project root.
+ * `path.join('/project', '/etc/passwd')` resolves to `/etc/passwd`, so the
+ * basic `..`-substring check alone permits absolute-path traversal.
+ *
+ * Tolerates a leading `res://` (Godot's project-root URI) by stripping it
+ * before resolving — autoload entries and resource paths use this prefix.
+ */
+export function validateSubPath(projectPath, userPath) {
+    if (!validatePath(userPath))
+        return false;
+    const stripped = userPath.startsWith('res://') ? userPath.slice('res://'.length) : userPath;
+    if (!stripped)
+        return false;
+    const projectRoot = resolve(projectPath);
+    const resolved = resolve(projectRoot, stripped);
+    const tail = projectRoot === sep ? sep : projectRoot + sep;
+    return resolved === projectRoot || resolved.startsWith(tail);
+}
+/**
+ * Validate a Godot scene-tree path (NodePath). Scene-tree paths are a
+ * separate namespace from filesystem paths — they address nodes inside
+ * a scene, not files on disk, so the project-root containment check
+ * in `validateSubPath` does not apply.
+ *
+ * Rejects empty strings and `..` segments. Accepts both relative
+ * (`root/Player`) and absolute (`/root/Player`) Godot forms; the
+ * codebase convention is the relative form.
+ */
+export function validateNodePath(path) {
+    return typeof path === 'string' && path.length > 0 && !path.includes('..');
+}
+/**
+ * True when `child` resolves to `parent` or a path beneath it. Used by
+ * defense-in-depth checks on bridge-returned paths (e.g. screenshot files
+ * that must live under `.mcp/screenshots/`).
+ */
+export function isUnderDir(parent, child) {
+    const parentResolved = resolve(parent);
+    const childResolved = resolve(child);
+    return childResolved === parentResolved || childResolved.startsWith(parentResolved + sep);
+}
+/**
+ * Return `error.message` when `error` is an `Error`, otherwise `'Unknown error'`.
+ * Centralizes the catch-block boilerplate so handlers can build error responses
+ * without repeating the `instanceof Error` ternary.
+ */
+export function getErrorMessage(error) {
+    return error instanceof Error ? error.message : 'Unknown error';
+}
+/**
+ * Build the absolute path to a project's `project.godot` manifest. Use this
+ * instead of `join(dir, 'project.godot')` ad hoc.
+ */
+export function projectGodotPath(projectDir) {
+    return join(projectDir, 'project.godot');
+}
 /**
  * Extract the first [ERROR] message from GDScript stderr output.
  * Falls back to a generic message if no [ERROR] line is found.
@@ -206,7 +324,7 @@ export function validateProjectArgs(args) {
             'Provide a valid path without ".." or other potentially unsafe characters',
         ]);
     }
-    const projectFile = join(args.projectPath, 'project.godot');
+    const projectFile = projectGodotPath(args.projectPath);
     if (!existsSync(projectFile)) {
         return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`, [
             'Ensure the path points to a directory containing a project.godot file',
@@ -227,9 +345,9 @@ export function validateSceneArgs(args, opts) {
         }
         return { projectPath: projectResult.projectPath, scenePath: '' };
     }
-    if (!validatePath(args.scenePath)) {
+    if (!validateSubPath(projectResult.projectPath, args.scenePath)) {
         return createErrorResponse('Invalid scene path', [
-            'Provide a valid path without ".." or other potentially unsafe characters',
+            'Provide a valid relative path without ".." that stays inside the project directory',
         ]);
     }
     if (sceneRequired) {
@@ -243,20 +361,48 @@ export function validateSceneArgs(args, opts) {
     }
     return { projectPath: projectResult.projectPath, scenePath: args.scenePath };
 }
+/**
+ * Read the first `n` bytes from a chunk array without concatenating the
+ * entire array. If the first chunk already has enough bytes, returns a
+ * zero-copy subarray; otherwise copies just `n` bytes into a fresh buffer.
+ * Caller must ensure total length across chunks is >= n.
+ */
+function readBytesFromChunks(chunks, n) {
+    if (chunks[0].length >= n)
+        return chunks[0].subarray(0, n);
+    const result = Buffer.allocUnsafe(n);
+    let copied = 0;
+    for (const c of chunks) {
+        const take = Math.min(c.length, n - copied);
+        c.copy(result, copied, 0, take);
+        copied += take;
+        if (copied >= n)
+            break;
+    }
+    return result;
+}
 export class GodotRunner {
     godotPath = null;
     operationsScriptPath;
-    bridgeScriptPath;
+    bridge;
     validatedPaths = new Map();
-    injectedProjects = new Set();
-    strictPathValidation;
+    cachedVersion = null;
     activeProcess = null;
     activeProjectPath = null;
     activeSessionMode = null;
+    activeBridgePort = null;
+    socket = null;
+    // Receive buffer kept as an array of chunks until at least one complete frame
+    // is available. Avoids re-copying accumulated bytes on every TCP data event
+    // (the old `Buffer.concat([rxBuffer, chunk])` pattern was O(n²) on large
+    // frames split across many chunks).
+    rxChunks = [];
+    rxTotal = 0;
+    inFlight = null;
     constructor(config) {
-        this.strictPathValidation = config?.strictPathValidation ?? false;
         this.operationsScriptPath = join(__dirname, '..', 'scripts', 'godot_operations.gd');
-        this.bridgeScriptPath = join(__dirname, '..', 'scripts', 'mcp_bridge.gd');
+        const bridgeScriptPath = join(__dirname, '..', 'scripts', 'mcp_bridge.gd');
+        this.bridge = new BridgeManager(bridgeScriptPath);
         logDebug(`Operations script path: ${this.operationsScriptPath}`);
         if (config?.godotPath) {
             const normalizedPath = normalize(config.godotPath);
@@ -361,36 +507,42 @@ export class GodotRunner {
         else if (osPlatform === 'linux') {
             possiblePaths.push('/usr/bin/godot', '/usr/local/bin/godot', '/snap/bin/godot', `${process.env.HOME}/.local/bin/godot`);
         }
-        for (const path of possiblePaths) {
-            const normalizedPath = normalize(path);
-            if (await this.isValidGodotPath(normalizedPath)) {
-                this.godotPath = normalizedPath;
-                logDebug(`Found Godot at: ${normalizedPath}`);
-                return;
-            }
+        const normalizedCandidates = possiblePaths.map((p) => normalize(p));
+        const probeResults = await Promise.all(normalizedCandidates.map(async (p) => ({ path: p, valid: await this.isValidGodotPath(p) })));
+        const winner = probeResults.find((r) => r.valid);
+        if (winner) {
+            this.godotPath = winner.path;
+            logDebug(`Found Godot at: ${winner.path}`);
+            return;
         }
         logDebug(`Warning: Could not find Godot in common locations for ${osPlatform}`);
         logError(`Could not find Godot in common locations for ${osPlatform}`);
-        if (this.strictPathValidation) {
-            throw new Error('Could not find a valid Godot executable. Set GODOT_PATH or provide a valid path in config.');
+        if (osPlatform === 'win32') {
+            this.godotPath = normalize('C:\\Program Files\\Godot\\Godot.exe');
+        }
+        else if (osPlatform === 'darwin') {
+            this.godotPath = normalize('/Applications/Godot.app/Contents/MacOS/Godot');
         }
         else {
-            if (osPlatform === 'win32') {
-                this.godotPath = normalize('C:\\Program Files\\Godot\\Godot.exe');
-            }
-            else if (osPlatform === 'darwin') {
-                this.godotPath = normalize('/Applications/Godot.app/Contents/MacOS/Godot');
-            }
-            else {
-                this.godotPath = normalize('/usr/bin/godot');
-            }
-            logDebug(`Using default path: ${this.godotPath}, but this may not work.`);
+            this.godotPath = normalize('/usr/bin/godot');
         }
+        logDebug(`Using default path: ${this.godotPath}, but this may not work.`);
     }
     getGodotPath() {
         return this.godotPath;
     }
+    /**
+     * Read the port currently baked into the project's bridge script. Returns
+     * null if the file is missing or malformed. Thin pass-through to
+     * BridgeManager — used by bridge-wait-timeout race detection.
+     */
+    readBakedBridgePort(projectPath) {
+        return this.bridge.readBakedPort(projectPath);
+    }
     async getVersion() {
+        if (this.cachedVersion !== null) {
+            return this.cachedVersion;
+        }
         if (!this.godotPath) {
             await this.detectGodotPath();
             if (!this.godotPath) {
@@ -398,21 +550,13 @@ export class GodotRunner {
             }
         }
         const { stdout } = await this.spawnAsync(this.godotPath, ['--version']);
-        return stdout.trim();
-    }
-    isGodot44OrLater(version) {
-        const match = version.match(/^(\d+)\.(\d+)/);
-        if (match) {
-            const major = parseInt(match[1], 10);
-            const minor = parseInt(match[2], 10);
-            return major > 4 || (major === 4 && minor >= 4);
-        }
-        return false;
+        this.cachedVersion = stdout.trim();
+        return this.cachedVersion;
     }
     async executeOperation(operation, params, projectPath, timeoutMs = 30000) {
         logDebug(`Executing operation: ${operation} in project: ${projectPath}`);
         logDebug(`Original operation params: ${JSON.stringify(params)}`);
-        this.repairOrphanedBridge(projectPath);
+        this.bridge.repairOrphaned(projectPath);
         const snakeCaseParams = convertCamelToSnakeCase(params);
         logDebug(`Converted snake_case params: ${JSON.stringify(snakeCaseParams)}`);
         if (!this.godotPath) {
@@ -433,12 +577,6 @@ export class GodotRunner {
             ...(DEBUG_MODE ? ['--debug-godot'] : []),
         ];
         logDebug(`Command: ${this.godotPath} ${args.join(' ')}`);
-        function cleanStdout(stdout) {
-            if (stdout.includes('{') || stdout.includes('[')) {
-                return extractJson(stdout);
-            }
-            return cleanOutput(stdout);
-        }
         let stdout = '';
         let stderr = '';
         try {
@@ -470,24 +608,32 @@ export class GodotRunner {
         }
         return spawn(this.godotPath, ['-e', '--path', projectPath], { stdio: 'pipe' });
     }
-    runProject(projectPath, scene, background = false) {
+    async runProject(projectPath, scene, background = false, bridgePort) {
         if (!this.godotPath) {
             throw new Error('Godot path not set. Call detectGodotPath first.');
         }
         if (this.activeSessionMode === 'spawned' && this.activeProcess) {
             logDebug('Killing existing Godot process before starting a new one');
+            this.closeConnection();
             this.activeProcess.process.kill();
             if (this.activeProjectPath && this.activeProjectPath !== projectPath) {
-                this.cleanupBridgeAutoload(this.activeProjectPath);
+                this.bridge.cleanup(this.activeProjectPath);
             }
         }
         else if (this.activeSessionMode === 'attached' &&
             this.activeProjectPath &&
             this.activeProjectPath !== projectPath) {
-            this.cleanupBridgeAutoload(this.activeProjectPath);
+            this.closeConnection();
+            this.bridge.cleanup(this.activeProjectPath);
+        }
+        if (!checkDisplayAvailable()) {
+            throw new Error('No display server available (DISPLAY and WAYLAND_DISPLAY are both unset). ' +
+                'Godot requires a display to run a project window.');
         }
+        const port = bridgePort ?? (await findFreePort());
+        this.activeBridgePort = port;
         try {
-            this.injectBridgeAutoload(projectPath);
+            this.bridge.inject(projectPath, port);
         }
         catch (err) {
             logDebug(`Non-fatal: Failed to inject bridge autoload: ${err}`);
@@ -495,15 +641,19 @@ export class GodotRunner {
         this.activeProjectPath = projectPath;
         this.activeSessionMode = 'spawned';
         const cmdArgs = ['--path', projectPath];
-        if (scene && validatePath(scene)) {
+        if (scene && validateSubPath(projectPath, scene)) {
             logDebug(`Adding scene parameter: ${scene}`);
             cmdArgs.push(scene);
         }
-        logDebug(`Running Godot project: ${projectPath}`);
+        const portSource = bridgePort !== undefined ? 'explicit' : 'auto';
+        logDebug(`Running Godot project: ${projectPath} (bridge port ${port}, ${portSource})`);
         const sessionToken = randomBytes(16).toString('hex');
         const spawnOptions = {
             stdio: 'pipe',
-            env: { ...process.env, MCP_SESSION_TOKEN: sessionToken },
+            env: {
+                ...process.env,
+                MCP_SESSION_TOKEN: sessionToken,
+            },
         };
         if (background) {
             spawnOptions.env = { ...spawnOptions.env, MCP_BACKGROUND: '1' };
@@ -555,33 +705,57 @@ export class GodotRunner {
         this.activeProcess = godotProcess;
         return this.activeProcess;
     }
-    attachProject(projectPath) {
+    async attachProject(projectPath, bridgePort) {
         if (this.activeSessionMode === 'spawned' && this.activeProcess) {
-            this.stopProject();
+            await this.stopProject();
         }
         else if (this.activeSessionMode === 'attached' &&
             this.activeProjectPath &&
             this.activeProjectPath !== projectPath) {
-            this.cleanupBridgeAutoload(this.activeProjectPath);
+            // Different project — detach the old one cleanly so its bridge
+            // releases the port before we inject into the new project.
+            try {
+                await this.sendCommand('shutdown', {}, BRIDGE_SHUTDOWN_ATTACHED_TIMEOUT_MS);
+            }
+            catch (err) {
+                logDebug(`Shutdown command failed during attach swap (ignored): ${err}`);
+            }
+            this.closeConnection();
+            this.bridge.cleanup(this.activeProjectPath);
             this.activeProjectPath = null;
             this.activeSessionMode = null;
         }
-        this.injectBridgeAutoload(projectPath);
+        const port = bridgePort ?? (await findFreePort());
+        this.activeBridgePort = port;
+        this.bridge.inject(projectPath, port);
+        const portSource = bridgePort !== undefined ? 'explicit' : 'auto';
+        logDebug(`Attaching to Godot project: ${projectPath} (bridge port ${port}, ${portSource})`);
         this.activeProjectPath = projectPath;
         this.activeSessionMode = 'attached';
         this.activeProcess = null;
     }
-    stopProject() {
+    async stopProject() {
         if (!this.activeSessionMode) {
             return null;
         }
         if (this.activeSessionMode === 'attached') {
+            // Ask the bridge to shut down so the user's still-running Godot
+            // releases the port. A timeout here is non-fatal — same end state
+            // as today, the bridge dies when the user closes Godot.
+            try {
+                await this.sendCommand('shutdown', {}, BRIDGE_SHUTDOWN_ATTACHED_TIMEOUT_MS);
+            }
+            catch (err) {
+                logDebug(`Attached shutdown timed out or failed (continuing cleanup): ${err}`);
+            }
+            this.closeConnection();
             const projectPath = this.activeProjectPath;
             if (projectPath) {
-                this.cleanupBridgeAutoload(projectPath);
+                this.bridge.cleanup(projectPath);
             }
             this.activeProjectPath = null;
             this.activeSessionMode = null;
+            this.activeBridgePort = null;
             this.activeProcess = null;
             return {
                 mode: 'attached',
@@ -593,8 +767,36 @@ export class GodotRunner {
         if (!this.activeProcess) {
             return null;
         }
+        // Spawned: try graceful shutdown so the bridge releases the port,
+        // then ensure the process actually exits.
+        try {
+            await this.sendCommand('shutdown', {}, BRIDGE_SHUTDOWN_SPAWNED_TIMEOUT_MS);
+        }
+        catch {
+            // Bridge may already be unreachable — proceed to kill.
+        }
+        this.closeConnection();
         logDebug('Stopping active Godot process');
-        this.activeProcess.process.kill();
+        const proc = this.activeProcess.process;
+        proc.kill();
+        // Wait up to BRIDGE_PROCESS_EXIT_TIMEOUT_MS for graceful exit; otherwise SIGKILL.
+        if (!this.activeProcess.hasExited) {
+            await new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    try {
+                        proc.kill('SIGKILL');
+                    }
+                    catch {
+                        // already dead
+                    }
+                    resolve();
+                }, BRIDGE_PROCESS_EXIT_TIMEOUT_MS);
+                proc.once('exit', () => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+            });
+        }
         const result = {
             mode: 'spawned',
             output: this.activeProcess.output,
@@ -602,10 +804,11 @@ export class GodotRunner {
         };
         this.activeProcess = null;
         if (this.activeProjectPath) {
-            this.cleanupBridgeAutoload(this.activeProjectPath);
+            this.bridge.cleanup(this.activeProjectPath);
             this.activeProjectPath = null;
         }
         this.activeSessionMode = null;
+        this.activeBridgePort = null;
         return result;
     }
     hasActiveRuntimeSession() {
@@ -617,165 +820,167 @@ export class GodotRunner {
         }
         return true;
     }
-    removeAutoloadEntry(projectPath, entryName, scriptFilename) {
-        try {
-            const projectFile = join(projectPath, 'project.godot');
-            if (existsSync(projectFile)) {
-                let content = readFileSync(projectFile, 'utf8');
-                const autoloadEntry = `${entryName}="*res://${scriptFilename}"`;
-                if (content.includes(autoloadEntry)) {
-                    content = content.replace(new RegExp(`\\n?${autoloadEntry.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'g'), '');
-                    content = content.replace(/\[autoload\]\s*(?=\n\[|\n*$)/g, '');
-                    content = content.trimEnd() + '\n';
-                    writeFileSync(projectFile, content, 'utf8');
-                    logDebug(`Removed ${entryName} autoload from project.godot`);
-                }
-            }
-        }
-        catch (err) {
-            logDebug(`Non-fatal: Failed to clean ${entryName} from project.godot: ${err}`);
-        }
-        try {
-            const scriptFile = join(projectPath, scriptFilename);
-            if (existsSync(scriptFile)) {
-                unlinkSync(scriptFile);
-                logDebug(`Removed ${scriptFilename} from project`);
-            }
-        }
-        catch (err) {
-            logDebug(`Non-fatal: Failed to remove ${scriptFilename}: ${err}`);
-        }
-        try {
-            const uidFile = join(projectPath, `${scriptFilename}.uid`);
-            if (existsSync(uidFile)) {
-                unlinkSync(uidFile);
-                logDebug(`Removed ${scriptFilename}.uid from project`);
-            }
-        }
-        catch (err) {
-            logDebug(`Non-fatal: Failed to remove ${scriptFilename}.uid: ${err}`);
-        }
-    }
     /**
-     * Idempotent within a session: short-circuits on `injectedProjects` so a
-     * second `attach_project`/`run_project` call does not rewrite `project.godot`.
+     * Send a JSON command to the McpBridge over a long-lived TCP connection.
+     *
+     * MCP serializes tool calls so we hold one in-flight command at a time. The
+     * socket is lazy-connected on first call and persists across commands until
+     * `closeConnection` (or a peer-side close). A close mid-flight rejects with
+     * `BridgeDisconnectedError`; a per-command timeout rejects but does NOT
+     * close the socket — a slow command does not invalidate the session.
      */
-    injectBridgeAutoload(projectPath) {
-        if (this.injectedProjects.has(projectPath)) {
-            logDebug('Bridge already injected for this project, skipping');
-            return;
-        }
-        // Ensure .mcp/ directory exists with .gdignore so Godot skips it
-        const mcpDir = join(projectPath, '.mcp');
-        if (!existsSync(mcpDir)) {
-            mkdirSync(mcpDir, { recursive: true });
-        }
-        writeFileSync(join(mcpDir, '.gdignore'), '', 'utf8');
-        logDebug('Created .mcp/.gdignore');
-        // Also add .mcp/ to .gitignore if not already present
-        const gitignorePath = join(projectPath, '.gitignore');
-        const mcpGitignoreEntry = '.mcp/';
-        if (existsSync(gitignorePath)) {
-            const gitignoreContent = readFileSync(gitignorePath, 'utf8');
-            if (!gitignoreContent.includes(mcpGitignoreEntry)) {
-                const newline = gitignoreContent.endsWith('\n') ? '' : '\n';
-                writeFileSync(gitignorePath, gitignoreContent + newline + mcpGitignoreEntry + '\n', 'utf8');
-                logDebug('Added .mcp/ to existing .gitignore');
-            }
-        }
-        else {
-            writeFileSync(gitignorePath, mcpGitignoreEntry + '\n', 'utf8');
-            logDebug('Created .gitignore with .mcp/ entry');
-        }
-        // Clean up legacy screenshot server if present
-        this.removeAutoloadEntry(projectPath, 'McpScreenshotServer', 'mcp_screenshot_server.gd');
-        const destScript = join(projectPath, 'mcp_bridge.gd');
-        copyFileSync(this.bridgeScriptPath, destScript);
-        logDebug(`Copied bridge autoload to ${destScript}`);
-        const projectFile = join(projectPath, 'project.godot');
-        let content = readFileSync(projectFile, 'utf8');
-        const autoloadEntry = 'McpBridge="*res://mcp_bridge.gd"';
-        if (content.includes(autoloadEntry)) {
-            logDebug('Bridge autoload already present, skipping injection');
-            if (!existsSync(destScript)) {
-                copyFileSync(this.bridgeScriptPath, destScript);
-                logDebug('Re-copied missing bridge script');
-            }
-            this.injectedProjects.add(projectPath);
-            return;
-        }
-        const autoloadSectionRegex = /^\[autoload\]\s*$/m;
-        if (autoloadSectionRegex.test(content)) {
-            content = content.replace(autoloadSectionRegex, `[autoload]\n${autoloadEntry}`);
-        }
-        else {
-            content = content.trimEnd() + `\n\n[autoload]\n${autoloadEntry}\n`;
-        }
-        writeFileSync(projectFile, content, 'utf8');
-        logDebug('Injected bridge autoload into project.godot');
-        this.injectedProjects.add(projectPath);
-    }
-    cleanupBridgeAutoload(projectPath) {
-        this.removeAutoloadEntry(projectPath, 'McpBridge', 'mcp_bridge.gd');
-        this.injectedProjects.delete(projectPath);
-    }
-    repairOrphanedBridge(projectPath) {
-        const projectFile = join(projectPath, 'project.godot');
-        const bridgeScript = join(projectPath, 'mcp_bridge.gd');
-        if (!existsSync(projectFile))
-            return;
-        if (existsSync(bridgeScript))
-            return;
-        try {
-            const content = readFileSync(projectFile, 'utf8');
-            if (content.includes('McpBridge=')) {
-                this.removeAutoloadEntry(projectPath, 'McpBridge', 'mcp_bridge.gd');
-                logDebug('Cleaned up orphaned McpBridge autoload entry');
-            }
-        }
-        catch (err) {
-            logDebug(`Non-fatal: Failed to check/repair orphaned bridge: ${err}`);
-        }
-    }
     sendCommand(command, params = {}, timeoutMs = 10000) {
         return new Promise((resolve, reject) => {
-            const socket = createSocket('udp4');
-            let settled = false;
+            if (this.inFlight) {
+                reject(new Error(`Command '${command}' rejected: another command ('${this.inFlight.command}') is in flight`));
+                return;
+            }
+            const settle = (err, value) => {
+                if (!this.inFlight)
+                    return;
+                const flight = this.inFlight;
+                this.inFlight = null;
+                clearTimeout(flight.timer);
+                if (err) {
+                    flight.reject(err);
+                }
+                else {
+                    flight.resolve(value ?? '');
+                }
+            };
             const timer = setTimeout(() => {
-                if (!settled) {
-                    settled = true;
-                    socket.close();
-                    reject(new Error(`Command '${command}' timed out after ${timeoutMs}ms. Is the game running?`));
+                // Destroy the socket on timeout. The bridge serializes commands
+                // (peer.handling gate), so a slow command's late response would
+                // otherwise correlate against the next command we send. The next
+                // sendCommand lazy-reconnects.
+                if (this.socket) {
+                    const sock = this.socket;
+                    this.socket = null;
+                    sock.removeAllListeners();
+                    sock.destroy();
                 }
+                this.resetRxBuffer();
+                settle(new Error(`Command '${command}' timed out after ${timeoutMs}ms. Is the game running?`));
             }, timeoutMs);
-            socket.on('message', (msg) => {
-                if (!settled) {
-                    settled = true;
-                    clearTimeout(timer);
-                    socket.close();
-                    resolve(msg.toString('utf8'));
+            this.inFlight = { command, resolve, reject, timer };
+            const ensureSocket = (cb) => {
+                if (this.socket) {
+                    cb();
+                    return;
                 }
-            });
-            socket.on('error', (err) => {
-                if (!settled) {
-                    settled = true;
-                    clearTimeout(timer);
-                    socket.close();
-                    reject(new Error(`UDP error for command '${command}': ${err.message}`));
+                // Fallback to DEFAULT_BRIDGE_PORT is defensive — every entry point
+                // (runProject, attachProject) sets activeBridgePort before sendCommand
+                // can be reached, so this branch is not expected in practice.
+                const port = this.activeBridgePort ?? DEFAULT_BRIDGE_PORT;
+                const sock = net.connect(port, '127.0.0.1');
+                const onConnect = () => {
+                    sock.setNoDelay(true);
+                    sock.removeListener('error', onConnectError);
+                    this.socket = sock;
+                    this.resetRxBuffer();
+                    sock.on('data', (chunk) => {
+                        this.rxChunks.push(chunk);
+                        this.rxTotal += chunk.length;
+                        // Defer the (potentially expensive) concat until we know at least
+                        // one complete frame is ready. Peek the 4-byte header without
+                        // copying all accumulated chunks first.
+                        if (this.rxTotal < FRAME_HEADER_BYTES)
+                            return;
+                        const header = readBytesFromChunks(this.rxChunks, FRAME_HEADER_BYTES);
+                        const firstLen = header.readUInt32BE(0);
+                        if (firstLen > MAX_FRAME_BYTES) {
+                            this.socket = null;
+                            sock.destroy();
+                            settle(new BridgeDisconnectedError(`Bridge frame header advertises ${firstLen} bytes, exceeds limit ${MAX_FRAME_BYTES}`));
+                            return;
+                        }
+                        if (this.rxTotal < FRAME_HEADER_BYTES + firstLen)
+                            return;
+                        try {
+                            const buffer = this.rxChunks.length === 1
+                                ? this.rxChunks[0]
+                                : Buffer.concat(this.rxChunks, this.rxTotal);
+                            const { frames, remainder } = parseFrames(buffer);
+                            if (remainder.length === 0) {
+                                this.rxChunks = [];
+                                this.rxTotal = 0;
+                            }
+                            else {
+                                this.rxChunks = [remainder];
+                                this.rxTotal = remainder.length;
+                            }
+                            for (const frame of frames) {
+                                settle(null, frame.toString('utf8'));
+                            }
+                        }
+                        catch (parseErr) {
+                            const message = parseErr instanceof Error ? parseErr.message : String(parseErr);
+                            this.socket = null;
+                            sock.destroy();
+                            settle(new BridgeDisconnectedError(`Bridge framing error: ${message}`));
+                        }
+                    });
+                    const onClose = () => {
+                        this.socket = null;
+                        settle(new BridgeDisconnectedError(`Bridge connection closed before '${command}' response was received`));
+                    };
+                    sock.once('close', onClose);
+                    sock.on('error', (sockErr) => {
+                        this.socket = null;
+                        settle(new BridgeDisconnectedError(`Bridge socket error during '${command}': ${sockErr.message}`));
+                    });
+                    cb();
+                };
+                const onConnectError = (connErr) => {
+                    sock.destroy();
+                    cb(connErr);
+                };
+                sock.once('connect', onConnect);
+                sock.once('error', onConnectError);
+            };
+            ensureSocket((err) => {
+                if (err) {
+                    settle(new BridgeDisconnectedError(`Failed to connect to bridge for '${command}': ${err.message}`));
+                    return;
                 }
-            });
-            const payload = JSON.stringify({ command, ...params });
-            const message = Buffer.from(payload);
-            socket.send(message, 9900, '127.0.0.1', (err) => {
-                if (err && !settled) {
-                    settled = true;
-                    clearTimeout(timer);
-                    socket.close();
-                    reject(new Error(`Failed to send command '${command}': ${err.message}`));
+                if (!this.socket) {
+                    settle(new BridgeDisconnectedError(`Bridge socket unavailable for '${command}'`));
+                    return;
+                }
+                try {
+                    const payload = JSON.stringify({ command, ...params });
+                    this.socket.write(encodeFrame(payload));
+                }
+                catch (writeErr) {
+                    const message = writeErr instanceof Error ? writeErr.message : String(writeErr);
+                    settle(new Error(`Failed to send command '${command}': ${message}`));
                 }
             });
         });
     }
+    /**
+     * Tear down the bridge socket. Idempotent. Any in-flight command is
+     * rejected with a session-ended error.
+     */
+    closeConnection() {
+        if (this.inFlight) {
+            const flight = this.inFlight;
+            this.inFlight = null;
+            clearTimeout(flight.timer);
+            flight.reject(new BridgeDisconnectedError('Bridge session ended'));
+        }
+        if (this.socket) {
+            const sock = this.socket;
+            this.socket = null;
+            sock.removeAllListeners();
+            sock.destroy();
+        }
+        this.resetRxBuffer();
+    }
+    resetRxBuffer() {
+        this.rxChunks = [];
+        this.rxTotal = 0;
+    }
     getErrorCount() {
         return this.activeProcess?.totalErrorsWritten ?? 0;
     }
@@ -789,37 +994,64 @@ export class GodotRunner {
         const window = delta >= errors.length ? errors.slice() : errors.slice(errors.length - delta);
         return window.filter((line) => line.trim() !== '');
     }
-    static SCRIPT_ERROR_PATTERNS = [
-        'SCRIPT ERROR:',
-        'USER SCRIPT ERROR:',
-        'GDScript error',
-    ];
+    // Only the explicit `SCRIPT ERROR:` / `USER SCRIPT ERROR:` markers belong here — the looser
+    // `GDScript error` substring also matches user printerr output and produces false positives.
+    static SCRIPT_ERROR_PATTERNS = ['SCRIPT ERROR:', 'USER SCRIPT ERROR:'];
+    static RETRYABLE_BRIDGE_COMMANDS = new Set(['get_ui_elements', 'screenshot']);
     extractRuntimeErrors(lines) {
         return lines.filter((line) => GodotRunner.SCRIPT_ERROR_PATTERNS.some((p) => line.includes(p)));
     }
+    async sendCommandWithReconnect(command, params = {}, timeoutMs = 10000) {
+        try {
+            return await this.sendCommand(command, params, timeoutMs);
+        }
+        catch (err) {
+            if (err instanceof BridgeDisconnectedError &&
+                this.activeSessionMode &&
+                GodotRunner.RETRYABLE_BRIDGE_COMMANDS.has(command)) {
+                this.closeConnection();
+                await new Promise((r) => setTimeout(r, BRIDGE_RECONNECT_DELAY_MS));
+                return this.sendCommand(command, params, timeoutMs);
+            }
+            throw err;
+        }
+    }
     async sendCommandWithErrors(command, params = {}, timeoutMs = 10000) {
         const marker = this.getErrorCount();
-        const response = await this.sendCommand(command, params, timeoutMs);
+        const response = await this.sendCommandWithReconnect(command, params, timeoutMs);
         const newErrors = this.getErrorsSince(marker);
         const runtimeErrors = this.activeSessionMode === 'spawned' ? this.extractRuntimeErrors(newErrors) : [];
         return { response, runtimeErrors };
     }
-    async waitForBridgeAttached(timeoutMs = BRIDGE_WAIT_ATTACHED_TIMEOUT_MS, intervalMs = BRIDGE_WAIT_ATTACHED_INTERVAL_MS) {
-        const deadline = Date.now() + timeoutMs;
-        const expectedPath = this.activeProjectPath
-            ? normalizeForCompare(this.activeProjectPath)
-            : null;
+    /**
+     * Shared poll loop for `waitForBridge` (spawned) and `waitForBridgeAttached`.
+     * Sends `ping` payloads until the bridge replies with a pong that
+     * `validatePong` accepts, the deadline passes, or `shouldAbort` reports
+     * the spawned process has exited.
+     */
+    async pollBridge(opts) {
+        const deadline = Date.now() + opts.timeoutMs;
         while (Date.now() < deadline) {
+            if (opts.shouldAbort) {
+                const abort = opts.shouldAbort();
+                if (abort.aborted) {
+                    const errorText = abort.tail.length > 0 ? `\nLast stderr:\n${abort.tail.join('\n')}` : '';
+                    return {
+                        ready: false,
+                        error: `Process exited with code ${this.activeProcess?.exitCode ?? '?'} before bridge was ready.${errorText}`,
+                    };
+                }
+            }
             try {
-                const response = await this.sendCommand('ping', {}, BRIDGE_PING_TIMEOUT_MS);
+                const response = await this.sendCommand('ping', opts.pingPayload, BRIDGE_PING_TIMEOUT_MS);
                 const parsed = JSON.parse(response);
-                if (parsed.status === 'pong') {
-                    if (expectedPath && parsed.project_path) {
+                if (opts.validatePong(parsed)) {
+                    if (opts.expectedPath && parsed.project_path) {
                         const bridgePath = normalizeForCompare(parsed.project_path);
-                        if (bridgePath !== expectedPath) {
+                        if (bridgePath !== opts.expectedPath) {
                             return {
                                 ready: false,
-                                error: `Bridge is running for a different project (${bridgePath}), expected ${expectedPath}`,
+                                error: `Bridge reports project ${bridgePath}, expected ${opts.expectedPath}`,
                             };
                         }
                     }
@@ -829,56 +1061,37 @@ export class GodotRunner {
             catch {
                 // Expected: ping will fail until bridge is listening
             }
-            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+            await new Promise((resolve) => setTimeout(resolve, opts.intervalMs));
         }
-        return {
-            ready: false,
-            error: 'Bridge did not respond within timeout — is Godot running with the McpBridge autoload?',
-        };
+        return { ready: false, error: opts.timeoutError };
+    }
+    async waitForBridgeAttached(timeoutMs = BRIDGE_WAIT_ATTACHED_TIMEOUT_MS, intervalMs = BRIDGE_WAIT_ATTACHED_INTERVAL_MS) {
+        return this.pollBridge({
+            expectedPath: this.activeProjectPath ? normalizeForCompare(this.activeProjectPath) : null,
+            timeoutMs,
+            intervalMs,
+            timeoutError: 'Bridge did not respond within timeout — is Godot running with the McpBridge autoload?',
+            pingPayload: {},
+            validatePong: (parsed) => parsed.status === 'pong',
+        });
     }
     async waitForBridge(timeoutMs = BRIDGE_WAIT_SPAWNED_TIMEOUT_MS, intervalMs = BRIDGE_WAIT_SPAWNED_INTERVAL_MS) {
-        const deadline = Date.now() + timeoutMs;
         const expectedToken = this.activeProcess?.sessionToken;
-        const expectedPath = this.activeProjectPath
-            ? normalizeForCompare(this.activeProjectPath)
-            : null;
         if (!expectedToken) {
             return { ready: false, error: 'No active spawned Godot process to verify' };
         }
-        while (Date.now() < deadline) {
-            if (this.activeProcess && this.activeProcess.hasExited) {
-                const lastErrors = this.getRecentErrors(20);
-                const errorText = lastErrors.length > 0 ? `\nLast stderr:\n${lastErrors.join('\n')}` : '';
-                return {
-                    ready: false,
-                    error: `Process exited with code ${this.activeProcess.exitCode} before bridge was ready.${errorText}`,
-                };
-            }
-            try {
-                const response = await this.sendCommand('ping', { session_token: expectedToken }, BRIDGE_PING_TIMEOUT_MS);
-                const parsed = JSON.parse(response);
-                if (parsed.status === 'pong' && parsed.session_token === expectedToken) {
-                    if (expectedPath && parsed.project_path) {
-                        const bridgePath = normalizeForCompare(parsed.project_path);
-                        if (bridgePath !== expectedPath) {
-                            return {
-                                ready: false,
-                                error: `Bridge reports project ${bridgePath}, expected ${expectedPath}`,
-                            };
-                        }
-                    }
-                    return { ready: true };
-                }
-            }
-            catch {
-                // Expected: ping will fail until bridge is listening
-            }
-            await new Promise((resolve) => setTimeout(resolve, intervalMs));
-        }
-        return {
-            ready: false,
-            error: 'Bridge did not respond with the expected session token within timeout',
-        };
+        return this.pollBridge({
+            expectedPath: this.activeProjectPath ? normalizeForCompare(this.activeProjectPath) : null,
+            timeoutMs,
+            intervalMs,
+            timeoutError: 'Bridge did not respond with the expected session token within timeout',
+            pingPayload: { session_token: expectedToken },
+            validatePong: (parsed) => parsed.status === 'pong' && parsed.session_token === expectedToken,
+            shouldAbort: () => ({
+                aborted: this.activeProcess !== null && this.activeProcess.hasExited,
+                tail: this.getRecentErrors(20),
+            }),
+        });
     }
     getRecentErrors(count = 20) {
         if (!this.activeProcess)