gdharness 0.6.3 → 0.6.5

package/build/cli.js

@@ -157,8 +157,8 @@ function runArguments(options) {
   }
   return args;
 }
-function editorArguments(projectPath) {
-  return ["-e", "--path", projectPath];
+function editorArguments(projectPath, ports) {
+  return ["-e", "--path", projectPath, "--lsp-port", String(ports.lsp), "--dap-port", String(ports.dap)];
 }
 function userDataIn(home, variables = process.env) {
   const moved = ["APPDATA", "XDG_DATA_HOME"];
@@ -8962,7 +8962,7 @@ var init_versions = __esm(() => {
   version = {
     major: 4,
     minor: 6,
-    patch: 4
+    patch: 5
   };
 });
 
@@ -15744,12 +15744,12 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "runtime_inspect",
-      description: "Questions about the running game: the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.",
+      description: "Questions about the running game: what is written on the screen, the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.",
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
         nodePath: {
           type: "string",
-          description: "tree, find: where to start, default /root. rect: the node to place. property: the node to read."
+          description: "tree, find, text: where to start, default /root. rect: the node to place. property: the node to read."
         },
         property: {
           type: "string",
@@ -15771,6 +15771,10 @@ var init_tool_definitions = __esm(() => {
         },
         group: { type: "string", description: "find: a group the node is in." },
         limit: { type: "number", description: "find: the most nodes to answer with. Default 100." },
+        includeHidden: {
+          type: "boolean",
+          description: "text: read hidden nodes as well, for checking that something is not showing. Default false."
+        },
         metrics: {
           type: "array",
           items: { type: "string" },
@@ -15780,6 +15784,10 @@ var init_tool_definitions = __esm(() => {
       requires: [],
       operations: {
         tree: { summary: "the live scene tree", requires: [] },
+        text: {
+          summary: "every line of text under nodePath, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+          requires: []
+        },
         find: {
           summary: "the paths of every node matching className, script, namePattern or group, with property read off each",
           requires: []
@@ -30791,10 +30799,11 @@ var init_framing = __esm(() => {
 });
 
 // src/ports.ts
-function portFromEnv(variable, fallback) {
+import { createServer } from "node:net";
+function portFromEnvOrNull(variable) {
   const raw = process.env[variable]?.trim();
   if (!raw) {
-    return fallback;
+    return null;
   }
   const parsed = Number.parseInt(raw, 10);
   if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535 || String(parsed) !== raw) {
@@ -30802,6 +30811,36 @@ function portFromEnv(variable, fallback) {
   }
   return parsed;
 }
+function portFromEnv(variable, fallback) {
+  return portFromEnvOrNull(variable) ?? fallback;
+}
+async function freePort(preferred, host = "127.0.0.1") {
+  const asked = await bindable(preferred, host);
+  if (asked !== null) {
+    return asked;
+  }
+  const spare = await bindable(0, host);
+  if (spare === null) {
+    throw new Refusal2(`No port could be bound on ${host}.`);
+  }
+  return spare;
+}
+function bindable(port, host) {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => {
+      resolve(null);
+    });
+    probe.once("listening", () => {
+      const bound = probe.address();
+      const taken = typeof bound === "object" && bound !== null ? bound.port : port;
+      probe.close(() => {
+        resolve(taken);
+      });
+    });
+    probe.listen(port, host);
+  });
+}
 var init_ports = __esm(() => {
   init_errors();
 });
@@ -34189,6 +34228,9 @@ function resolveDefaultBridgeHost() {
   const host = process.env["GDHARNESS_BRIDGE_HOST"]?.trim();
   return host === undefined || host === "" ? DEFAULT_HOST : host;
 }
+function servedPort(said) {
+  return typeof said === "number" && Number.isInteger(said) && said > 0 && said <= 65535 ? said : undefined;
+}
 function getDefaultBridge(mayMove = false) {
   defaultBridge ??= new GodotBridge(resolveDefaultBridgePort(), resolveDefaultBridgeHost(), DEFAULT_TIMEOUT_MS, mayMove);
   return defaultBridge;
@@ -34329,6 +34371,9 @@ var init_godot_bridge = __esm(() => {
         lastPongAt: this.connectionInfo?.lastPongAt,
         addonVersion: this.connectionInfo?.addonVersion,
         editorPid: this.connectionInfo?.editorPid,
+        lspPort: this.connectionInfo?.lspPort,
+        dapPort: this.connectionInfo?.dapPort,
+        debugPort: this.connectionInfo?.debugPort,
         pendingRequests: this.pendingRequests.size,
         queuedResources: this.resourceQueues.size
       };
@@ -34462,6 +34507,9 @@ var init_godot_bridge = __esm(() => {
             this.connectionInfo.projectPath = message.project_path;
             this.connectionInfo.addonVersion = message.addon_version ?? "";
             this.connectionInfo.editorPid = message.editor_pid;
+            this.connectionInfo.lspPort = servedPort(message.lsp_port);
+            this.connectionInfo.dapPort = servedPort(message.dap_port);
+            this.connectionInfo.debugPort = servedPort(message.debug_port);
             this.log("info", `Godot ready: ${message.project_path}`);
             this.emitBridgeEvent("godot_connected", { projectPath: message.project_path });
           }
@@ -35368,10 +35416,10 @@ function asToolResponse(payload) {
     ]
   };
 }
-function normalizeLSPError(error) {
+function normalizeLSPError(error, port) {
   if (error instanceof Error) {
     if (error.message.includes("ECONNREFUSED") || error.message.includes("Failed to connect to Godot LSP") || error.message.includes("socket closed")) {
-      return `Godot LSP is unavailable on port ${portFromEnv("GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT)}. Start the Godot editor and enable Language Server in Editor Settings, or set GDHARNESS_LSP_PORT to the port it serves.`;
+      return `Godot LSP is unavailable on port ${port}. Start the Godot editor and enable Language Server in Editor Settings, or set GDHARNESS_LSP_PORT to the port it serves.`;
     }
     return error.message;
   }
@@ -35449,7 +35497,7 @@ async function handleLSPTool(client, toolName, args) {
     }
   } catch (error) {
     return asToolResponse({
-      error: normalizeLSPError(error)
+      error: normalizeLSPError(error, client.port)
     });
   }
 }
@@ -35804,6 +35852,9 @@ import { basename as basename2, dirname as dirname9, join as join15, normalize a
 import { setTimeout as delay2 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { promisify as promisify5 } from "node:util";
+function patienceForFrames(frames, atLeast) {
+  return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
+}
 function escapingPropertyValue(properties) {
   if (typeof properties !== "object" || properties === null) {
     return;
@@ -36283,6 +36334,12 @@ class GodotServer {
             });
           case "find":
             return await this.handleFindRuntimeNodes(args);
+          case "text":
+            return await this.handleRuntimeCommand("read_text", {
+              projectPath: args["projectPath"],
+              root: readNonEmptyString(args, "nodePath") ?? "/root",
+              include_hidden: readBoolean(args, "includeHidden") ?? false
+            });
           case "rect":
             return await this.handleRuntimeCommand("get_rect", {
               projectPath: args["projectPath"],
@@ -36412,7 +36469,7 @@ class GodotServer {
       return {
         ok: false,
         response: this.createErrorResponse(`The editor is playing the game but its debug adapter did not answer: ${errorMessage(error)}`, [
-          "Godot serves the debug adapter on 6006 unless --dap-port says otherwise",
+          `This asked on port ${this.dap().port}, which is where the connected editor says it serves`,
           "GDHARNESS_DAP_PORT points this server at another one"
         ])
       };
@@ -36779,7 +36836,8 @@ class GodotServer {
     if (payload["error"] !== undefined) {
       const reason = payload["error"];
       return this.createErrorResponse(`Diagnostics unavailable: ${typeof reason === "string" ? reason : JSON.stringify(reason)}`, [
-        "Ensure the Godot editor is running with its language server enabled, on port 6005 or on the port GDHARNESS_LSP_PORT names"
+        `Ensure the Godot editor is running with its language server enabled, on port ${this.editorServes("lspPort", "GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT)}`,
+        "GDHARNESS_LSP_PORT points this server at another one"
       ]);
     }
     const diagnostics = readArray(payload, "diagnostics") ?? [];
@@ -36796,16 +36854,33 @@ class GodotServer {
     });
   }
   async handleLSP(toolName, args) {
-    this.lspClient ??= new GodotLSPClient;
+    const port = this.editorServes("lspPort", "GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT);
+    if (this.lspClient !== null && this.lspClient.port !== port) {
+      await this.lspClient.disconnect();
+      this.lspClient = null;
+    }
+    this.lspClient ??= new GodotLSPClient(port);
     return handleLSPTool(this.lspClient, toolName, args);
   }
   async handleDAP(toolName, args) {
     return handleDAPTool(this.dap(), toolName, args);
   }
   dap() {
-    this.dapClient ??= new GodotDAPClient;
+    const port = this.editorServes("dapPort", "GDHARNESS_DAP_PORT", DEFAULT_DAP_PORT);
+    if (this.dapClient !== null && this.dapClient.port !== port) {
+      this.dapClient = null;
+    }
+    this.dapClient ??= new GodotDAPClient(port);
     return this.dapClient;
   }
+  editorServes(field, variable, fallback) {
+    const named = portFromEnvOrNull(variable);
+    if (named !== null) {
+      return named;
+    }
+    const status = this.godotBridge.getStatus();
+    return (status.connected ? status[field] : undefined) ?? fallback;
+  }
   getEditorStatusPayload() {
     const status = this.godotBridge.getStatus();
     const isPortConflict = this.bridgeStartupError?.includes("EADDRINUSE") ?? false;
@@ -36833,7 +36908,8 @@ class GodotServer {
       const answer = await this.godotBridge.invokeTool("playing_status", {});
       return {
         playing: readBoolean(asParams(answer), "playing") ?? false,
-        scene: readString(asParams(answer), "scenePath") ?? ""
+        scene: readString(asParams(answer), "scenePath") ?? "",
+        debugPort: readNumber(asParams(answer), "debugPort")
       };
     } catch {
       return null;
@@ -36851,15 +36927,19 @@ class GodotServer {
         problem: reply.ok ? null : reply.message
       };
     }));
+    const playing = await this.editorPlayingState();
     return this.jsonTextResponse({
-      editor: this.getEditorStatusPayload(),
+      editor: {
+        ...this.getEditorStatusPayload(),
+        debugPort: playing?.debugPort ?? this.godotBridge.getStatus().debugPort
+      },
       godot: {
         path: godotPath,
         version: godotPath === null ? null : await this.godotVersion(godotPath)
       },
       game: {
         processActive: this.activeProcess !== null,
-        playingInEditor: await this.editorPlayingState(),
+        playingInEditor: playing,
         runtimeConnected: games.some((game) => game.reachable),
         runtimes: games
       }
@@ -36918,10 +36998,10 @@ class GodotServer {
       return project.response;
     }
     if (this.godotBridge.isConnected()) {
-      return this.createErrorResponse("An editor is already connected to this server, and a second one would take the language server and debug adapter ports from it.", [
+      return this.createErrorResponse("An editor is already connected to this server.", [
         "editor_status says which editor is answering, and for which project",
         "editor_launch restart replaces the connected editor rather than joining it",
-        "Close the open editor first if the new project is the one you want"
+        "Another project wants its own gdharness server, which is its own harness session"
       ]);
     }
     const engine = await this.engine();
@@ -36929,10 +37009,16 @@ class GodotServer {
       return engine.response;
     }
     this.logDebug(`Launching Godot editor for project: ${project.value.path}`);
-    const editor = spawn(engine.value, editorArguments(project.value.path), {
+    const ports = await this.portsForAnEditor();
+    const editor = spawn(engine.value, editorArguments(project.value.path, ports), {
       stdio: "ignore",
       detached: true,
-      env: { ...process.env, GDHARNESS_RUNTIME_DIR: runtimeDirectory() }
+      env: {
+        ...process.env,
+        GDHARNESS_RUNTIME_DIR: runtimeDirectory(),
+        GDHARNESS_LSP_PORT: String(ports.lsp),
+        GDHARNESS_DAP_PORT: String(ports.dap)
+      }
     });
     const started = await new Promise((resolve) => {
       editor.once("spawn", () => {
@@ -36949,9 +37035,16 @@ class GodotServer {
     return this.jsonTextResponse({
       launched: true,
       pid: editor.pid ?? null,
-      projectPath: project.value.path
+      projectPath: project.value.path,
+      lspPort: ports.lsp,
+      dapPort: ports.dap
     });
   }
+  async portsForAnEditor() {
+    const lsp = portFromEnvOrNull("GDHARNESS_LSP_PORT") ?? await freePort(DEFAULT_LSP_PORT);
+    const dap = portFromEnvOrNull("GDHARNESS_DAP_PORT") ?? await freePort(DEFAULT_DAP_PORT);
+    return { lsp, dap };
+  }
   async handleRunProject(args, op) {
     const project = this.project(args);
     if (!project.ok) {
@@ -37019,7 +37112,7 @@ class GodotServer {
       await this.dap().connect();
     } catch (error) {
       return this.createErrorResponse(`The editor is connected but its debug adapter is not: ${errorMessage(error)}`, [
-        "Godot serves the debug adapter on 6006 unless --dap-port says otherwise",
+        `This asked on port ${this.dap().port}, which is where the connected editor says it serves`,
         "GDHARNESS_DAP_PORT points this server at another one"
       ]);
     }
@@ -37041,6 +37134,7 @@ class GodotServer {
       through: "editor",
       scene: scene === null ? "the main scene" : `res://${scene}`,
       refreshedClasses,
+      debugPort: readNumber(asParams(JSON.parse(answer.content[0]?.text ?? "{}")), "debugPort"),
       message: "The editor is playing it, so its debugger holds it: the debug_* tools can reach it, " + "editor_output reads its console through the debug adapter, and editor_run stop ends it."
     });
   }
@@ -37223,7 +37317,7 @@ class GodotServer {
   async handleRuntimeCommand(command, args, timeoutMs = this.runtimeTimeoutMs()) {
     const { op: _op, projectPath, ...params } = asParams(args);
     const announced = runtimesAnnounced();
-    const choice = chooseRuntime(announced.running, typeof projectPath === "string" ? projectPath : undefined, announced.unspoken);
+    const choice = chooseRuntime(announced.running, typeof projectPath === "string" ? projectPath : this.ownProject ?? undefined, announced.unspoken);
     if ("problem" in choice) {
       return this.createErrorResponse(choice.problem);
     }
@@ -37290,8 +37384,11 @@ class GodotServer {
     const nodePath = readNonEmptyString(args, "nodePath") ?? "";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
     switch (op) {
-      case "frames":
-        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames: readPositiveNumber(args, "frames") ?? 1 }, patience);
+      case "frames": {
+        const frames = readPositiveNumber(args, "frames") ?? 1;
+        const waited = patienceForFrames(frames, patience);
+        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames }, waited);
+      }
       case "signal":
         return await this.handleRuntimeCommand("wait_signal", {
           projectPath: args["projectPath"],
@@ -37314,7 +37411,7 @@ async function runGodotServer() {
   const server = new GodotServer;
   await server.run();
 }
-var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run5, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, BRIDGE_RETRY_MS = 2000, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, HEADLESS_OPERATIONS, PROJECT_INFO_SECTIONS;
+var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run5, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, SLOWEST_FRAME_RATE = 20, BRIDGE_RETRY_MS = 2000, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, HEADLESS_OPERATIONS, PROJECT_INFO_SECTIONS;
 var init_server3 = __esm(() => {
   init_mcp();
   init_stdio2();
@@ -37331,6 +37428,7 @@ var init_server3 = __esm(() => {
   init_junit();
   init_lsp_client();
   init_paths();
+  init_ports();
   init_project_scan();
   init_resources();
   init_runtime_client();
@@ -38654,11 +38752,15 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 - Read \`editor_output\` after every run. It returns the engine's errors and warnings as entries
   with their backtraces, and a \`clean\` verdict, so a run that printed an error is one call away
   from being known.
+- One server, one editor. A second project is a second harness session with its own server, and
+  that works: each editor is opened on its own language server and debug adapter ports, and says
+  where it serves. Two editors on one project is the thing to refuse.
 
 ## Measuring a running game
 
 | Ask | Tool |
 | --- | --- |
+| What a screen says | \`runtime_inspect text\`, which reads what is drawn and leaves out what is hidden |
 | Where a control is, and whether it is visible | \`runtime_inspect\` \`find\`, \`rect\` |
 | What a property reads right now | \`runtime_inspect\` \`property\`, \`runtime_invoke\` |
 | Press a button | \`runtime_input click\`, which says what was under the pointer |

package/build/godot/addons/gdharness_editor/bridge_client.gd

@@ -18,6 +18,17 @@ const ANNOUNCE_PROTOCOL: int = 1
 const RECONNECT_DELAY: float = 3.0
 const MAX_RECONNECT_DELAY: float = 30.0
 
+## Where Godot keeps the three ports an editor serves. None of them is per editor: the settings
+## file is one for every editor on the machine, so two open at once want the same three and the
+## second one binds nothing.
+const LSP_SETTING: String = "network/language_server/remote_port"
+const DAP_SETTING: String = "network/debug_adapter/remote_port"
+const DEBUGGER_SETTING: String = "network/debug/remote_port"
+## What a server that opened this editor put in the environment, matching the ports it named on
+## the command line. Kept in step with `editorArguments` in src/launch.ts.
+const LSP_ASKED: String = "GDHARNESS_LSP_PORT"
+const DAP_ASKED: String = "GDHARNESS_DAP_PORT"
+
 ## How long one attempt is given before the address is called a bad one.
 ##
 ## A socket pointed at a port nothing holds gives up by itself, in thirty seconds on Windows. One
@@ -62,6 +73,7 @@ var _connecting_for: float = 0.0
 func _ready() -> void:
 	_project_path = ProjectSettings.globalize_path("res://")
 	version_at_load = _loaded_version()
+	_keep_the_ports_this_editor_was_given()
 
 	_reconnect_timer = Timer.new()
 	_reconnect_timer.one_shot = true
@@ -243,18 +255,73 @@ func _handle_connect() -> void:
 	# somebody restarts it, and nothing else can tell the two apart.
 	# The process id with it, because a restarted editor is a different process from the one
 	# whoever started it is holding, and nothing else says which one is now on the other end.
+	# The three ports with that, because a server that assumes the defaults talks to whichever
+	# editor took them, which on a machine running two is not this one.
 	_send_message(
 		{
 			"type": "godot_ready",
 			"project_path": _project_path,
 			"addon_version": version_at_load,
-			"editor_pid": OS.get_process_id()
+			"editor_pid": OS.get_process_id(),
+			"lsp_port": _serves(LSP_ASKED, LSP_SETTING),
+			"dap_port": _serves(DAP_ASKED, DAP_SETTING),
+			"debug_port": _serving(DEBUGGER_SETTING)
 		}
 	)
 
 	connected.emit()
 
 
+## Writes the ports this editor was started on into the settings it reads them from.
+##
+## The command line moved the language server and the debug adapter for this run and the engine
+## keeps that override to itself: the setting still reads whatever it read before, so an editor
+## that restarts itself comes back on the old number and lands on top of whichever editor holds
+## it. Writing it here is what makes the move survive a restart, and what leaves one place either
+## side has to read.
+func _keep_the_ports_this_editor_was_given() -> void:
+	if not Engine.is_editor_hint():
+		return
+	_keep_port(LSP_ASKED, LSP_SETTING)
+	_keep_port(DAP_ASKED, DAP_SETTING)
+
+
+func _keep_port(variable: String, setting: String) -> void:
+	var port: int = _asked_for(variable)
+	if port < 1 or port == _serving(setting):
+		return
+	var settings: EditorSettings = EditorInterface.get_editor_settings()
+	if settings != null:
+		settings.set_setting(setting, port)
+
+
+## What this editor serves: what it was told to when a server opened it, and what its settings
+## say otherwise. The first is the one that counts, because the settings are the thing the command
+## line was overriding.
+func _serves(variable: String, setting: String) -> int:
+	var asked: int = _asked_for(variable)
+	return asked if asked > 0 else _serving(setting)
+
+
+## The port this variable names, or 0 for anything that is not one.
+static func _asked_for(variable: String) -> int:
+	var said: String = OS.get_environment(variable)
+	if not said.is_valid_int():
+		return 0
+	var port: int = int(said)
+	return port if port >= 1 and port <= 65535 else 0
+
+
+## What the settings say this editor serves on, or 0 when there is nothing to ask.
+func _serving(setting: String) -> int:
+	if not Engine.is_editor_hint():
+		return 0
+	var settings: EditorSettings = EditorInterface.get_editor_settings()
+	if settings == null or not settings.has_setting(setting):
+		return 0
+	return int(settings.get_setting(setting))
+
+
 ## The version marker beside this addon, or "" when the copy was not installed by gdharness.
 ##
 ## Read once, when this copy loads, and never again: an upgrade replaces the files under a

package/build/godot/addons/gdharness_editor/tools/play_tools.gd

@@ -10,6 +10,10 @@ extends Node
 
 ## What the display server calls itself when the engine was started with no display at all.
 const HEADLESS_DISPLAY: String = "headless"
+## Where Godot keeps the port its own debugger listens on for a game it is playing. One setting
+## for every editor on the machine, and bound only while a game runs.
+const DEBUGGER_SETTING: String = "network/debug/remote_port"
+const LOOPBACK: String = "127.0.0.1"
 
 var _editor_plugin: EditorPlugin = null
 
@@ -24,6 +28,8 @@ func play_scene(args: Dictionary) -> Dictionary:
 	if EditorInterface.is_playing_scene():
 		EditorInterface.stop_playing_scene()
 
+	var debugger: int = _a_port_for_the_debugger()
+
 	if scene_path.is_empty():
 		EditorInterface.play_main_scene()
 	else:
@@ -35,10 +41,43 @@ func play_scene(args: Dictionary) -> Dictionary:
 	return {
 		"ok": true,
 		"playing": EditorInterface.is_playing_scene(),
-		"scenePath": EditorInterface.get_playing_scene()
+		"scenePath": EditorInterface.get_playing_scene(),
+		"debugPort": debugger
 	}
 
 
+## Gives this editor's debugger a port of its own, and answers the one the game will be sent to.
+##
+## The editor binds this while a game runs, out of a setting shared by every editor on the
+## machine, and Godot takes --lsp-port and --dap-port on its command line but nothing at all for
+## this one. So two editors playing at once want the same number, and both ways that can go are
+## wrong: a bind that fails leaves a game with no debugger behind it, which is every debug tool
+## and the whole console gone, and a bind that succeeds anyway leaves two editors on one port with
+## the games going to whichever one the operating system picks.
+##
+## Asked of the operating system each time rather than tested first, which is how the runtime
+## addon takes its own port: a port that was free a moment ago is not a port that is still free,
+## and nothing this can ask distinguishes the editor's own debugger from another editor's.
+func _a_port_for_the_debugger() -> int:
+	var settings: EditorSettings = EditorInterface.get_editor_settings()
+	if settings == null or not settings.has_setting(DEBUGGER_SETTING):
+		return 0
+	var spare: int = _any_free_port()
+	if spare > 0:
+		settings.set_setting(DEBUGGER_SETTING, spare)
+	return spare
+
+
+## A port the operating system handed out, or 0 when it would not give one.
+static func _any_free_port() -> int:
+	var probe: TCPServer = TCPServer.new()
+	if probe.listen(0, LOOPBACK) != OK:
+		return 0
+	var port: int = probe.get_local_port()
+	probe.stop()
+	return port
+
+
 func stop_playing(_args: Dictionary) -> Dictionary:
 	var was_playing: bool = EditorInterface.is_playing_scene()
 	if was_playing:
@@ -88,6 +127,17 @@ func restart_editor(_args: Dictionary) -> Dictionary:
 
 func playing_status(_args: Dictionary) -> Dictionary:
 	var playing: bool = EditorInterface.is_playing_scene()
+	# The debugger's port with it, read now rather than remembered: it is taken again before every
+	# play, so the one from when this editor greeted the server is a number it has moved off.
+	var settings: EditorSettings = EditorInterface.get_editor_settings()
+	var debugger: int = (
+		int(settings.get_setting(DEBUGGER_SETTING))
+		if settings != null and settings.has_setting(DEBUGGER_SETTING)
+		else 0
+	)
 	return {
-		"ok": true, "playing": playing, "scenePath": EditorInterface.get_playing_scene() if playing else ""
+		"ok": true,
+		"playing": playing,
+		"scenePath": EditorInterface.get_playing_scene() if playing else "",
+		"debugPort": debugger
 	}

package/build/godot/addons/gdharness_runtime/runtime_autoload.gd

@@ -57,6 +57,7 @@ func _init() -> void:
 		"ping": _ping,
 		"get_tree": _queries.get_tree,
 		"find_nodes": _queries.find_nodes,
+		"read_text": _queries.read_text,
 		"get_rect": _queries.get_rect,
 		"get_property": _queries.get_property,
 		"set_property": _queries.set_property,

package/build/godot/addons/gdharness_runtime/runtime_input.gd

@@ -435,6 +435,16 @@ func choose(params: Dictionary) -> Dictionary:
 			)
 		}
 
+	if not params.has("index") and str(params.get("text", "")).is_empty():
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s needs the item named, by text or index. It holds: %s"
+				% [node_path, ", ".join(_items_of(menu))]
+			)
+		}
+
 	var index: int = _wanted_item(menu, params)
 	if index < 0:
 		return {

package/build/godot/addons/gdharness_runtime/runtime_queries.gd

@@ -10,6 +10,10 @@ const Values = preload("runtime_values.gd")
 const FIND_LIMIT: int = 100
 const FIND_LIMIT_CEILING: int = 1000
 
+## The most lines one read answers with. A screen is a few dozen; a thousand is a tree somebody
+## pointed this at by mistake.
+const READ_LIMIT: int = 500
+
 var _host: Node
 var _values: Values
 
@@ -138,6 +142,60 @@ func _matches(
 ## is drawn in, in both the canvas coordinates the node reports and the window pixels input
 ## arrives in. The two differ whenever the project stretches its viewport, which is what made a
 ## rect unusable for a click.
+## Every line of text under a node, in the order somebody reads the screen.
+##
+## The question a caller asks most often, and the one that cost the most to answer: reading a panel
+## was a find for every label with the path of each beside it, a few hundred characters apiece to
+## carry a sentence of six words. Long is the smaller half of it. A find answers off nodes nobody
+## can see, and a panel keeps its empty state in the tree beside its rows, so "Nothing posted" came
+## back next to the three things posted and was believed twice in one session.
+##
+## A hidden node is left out and so is everything under it, because what a player reads is what is
+## drawn. [param include_hidden] asks for the lot instead, which is what a caller checking that
+## something is not showing wants.
+func read_text(params: Dictionary) -> Dictionary:
+	var root_path: String = str(params.get("root", "/root"))
+	var include_hidden: bool = bool(params.get("include_hidden", false))
+
+	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
+	if root == null:
+		return {"type": "error", "message": "Node not found: " + root_path}
+
+	var lines: PackedStringArray = PackedStringArray()
+	_read_into(root, include_hidden, lines)
+	return {
+		"type": "text",
+		"root": root_path,
+		"lines": lines,
+		"count": lines.size(),
+		"truncated": lines.size() >= READ_LIMIT,
+	}
+
+
+## Walks [param node] depth first, which is the order the screen is laid out in and the order a
+## person reads it.
+func _read_into(node: Node, include_hidden: bool, into: PackedStringArray) -> void:
+	if into.size() >= READ_LIMIT:
+		return
+	var control: CanvasItem = node as CanvasItem
+	if not include_hidden and control != null and not control.visible:
+		return
+	var said: String = _said_by(node)
+	if not said.is_empty():
+		into.append(said)
+	for child: Node in node.get_children():
+		_read_into(child, include_hidden, into)
+
+
+## What one node says, or "" for a node that says nothing. Anything with a `text` property, which
+## is every label, button and field the interface is built out of.
+static func _said_by(node: Node) -> String:
+	for property: Dictionary in node.get_property_list():
+		if str(property.get("name", "")) == "text" and int(property.get("type", 0)) == TYPE_STRING:
+			return str(node.get("text")).strip_edges()
+	return ""
+
+
 func get_rect(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	if node_path.is_empty():

package/build/index.js

@@ -15311,7 +15311,7 @@ ${content.join(`
 var version = {
   major: 4,
   minor: 6,
-  patch: 4
+  patch: 5
 };
 
 // node_modules/zod/v4/core/schemas.js
@@ -24861,10 +24861,11 @@ class FrameReader {
 }
 
 // src/ports.ts
-function portFromEnv(variable, fallback) {
+import { createServer } from "node:net";
+function portFromEnvOrNull(variable) {
   const raw = process.env[variable]?.trim();
   if (!raw) {
-    return fallback;
+    return null;
   }
   const parsed = Number.parseInt(raw, 10);
   if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535 || String(parsed) !== raw) {
@@ -24872,6 +24873,36 @@ function portFromEnv(variable, fallback) {
   }
   return parsed;
 }
+function portFromEnv(variable, fallback) {
+  return portFromEnvOrNull(variable) ?? fallback;
+}
+async function freePort(preferred, host = "127.0.0.1") {
+  const asked = await bindable(preferred, host);
+  if (asked !== null) {
+    return asked;
+  }
+  const spare = await bindable(0, host);
+  if (spare === null) {
+    throw new Refusal(`No port could be bound on ${host}.`);
+  }
+  return spare;
+}
+function bindable(port, host) {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => {
+      resolve(null);
+    });
+    probe.once("listening", () => {
+      const bound = probe.address();
+      const taken = typeof bound === "object" && bound !== null ? bound.port : port;
+      probe.close(() => {
+        resolve(taken);
+      });
+    });
+    probe.listen(port, host);
+  });
+}
 
 // src/dap_client.ts
 var DEFAULT_DAP_PORT = 6006;
@@ -25476,6 +25507,9 @@ function resolveDefaultBridgeHost() {
   const host = process.env["GDHARNESS_BRIDGE_HOST"]?.trim();
   return host === undefined || host === "" ? DEFAULT_HOST : host;
 }
+function servedPort(said) {
+  return typeof said === "number" && Number.isInteger(said) && said > 0 && said <= 65535 ? said : undefined;
+}
 
 class GodotBridge extends EventEmitter {
   httpServer = null;
@@ -25608,6 +25642,9 @@ class GodotBridge extends EventEmitter {
       lastPongAt: this.connectionInfo?.lastPongAt,
       addonVersion: this.connectionInfo?.addonVersion,
       editorPid: this.connectionInfo?.editorPid,
+      lspPort: this.connectionInfo?.lspPort,
+      dapPort: this.connectionInfo?.dapPort,
+      debugPort: this.connectionInfo?.debugPort,
       pendingRequests: this.pendingRequests.size,
       queuedResources: this.resourceQueues.size
     };
@@ -25741,6 +25778,9 @@ class GodotBridge extends EventEmitter {
           this.connectionInfo.projectPath = message.project_path;
           this.connectionInfo.addonVersion = message.addon_version ?? "";
           this.connectionInfo.editorPid = message.editor_pid;
+          this.connectionInfo.lspPort = servedPort(message.lsp_port);
+          this.connectionInfo.dapPort = servedPort(message.dap_port);
+          this.connectionInfo.debugPort = servedPort(message.debug_port);
           this.log("info", `Godot ready: ${message.project_path}`);
           this.emitBridgeEvent("godot_connected", { projectPath: message.project_path });
         }
@@ -26013,8 +26053,8 @@ function runArguments(options) {
   }
   return args;
 }
-function editorArguments(projectPath) {
-  return ["-e", "--path", projectPath];
+function editorArguments(projectPath, ports) {
+  return ["-e", "--path", projectPath, "--lsp-port", String(ports.lsp), "--dap-port", String(ports.dap)];
 }
 function userDataIn(home, variables = process.env) {
   const moved = ["APPDATA", "XDG_DATA_HOME"];
@@ -26911,10 +26951,10 @@ function asToolResponse(payload) {
     ]
   };
 }
-function normalizeLSPError(error) {
+function normalizeLSPError(error, port) {
   if (error instanceof Error) {
     if (error.message.includes("ECONNREFUSED") || error.message.includes("Failed to connect to Godot LSP") || error.message.includes("socket closed")) {
-      return `Godot LSP is unavailable on port ${portFromEnv("GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT)}. Start the Godot editor and enable Language Server in Editor Settings, or set GDHARNESS_LSP_PORT to the port it serves.`;
+      return `Godot LSP is unavailable on port ${port}. Start the Godot editor and enable Language Server in Editor Settings, or set GDHARNESS_LSP_PORT to the port it serves.`;
     }
     return error.message;
   }
@@ -26992,7 +27032,7 @@ async function handleLSPTool(client, toolName, args) {
     }
   } catch (error) {
     return asToolResponse({
-      error: normalizeLSPError(error)
+      error: normalizeLSPError(error, client.port)
     });
   }
 }
@@ -28258,12 +28298,12 @@ var TOOL_SPECS = [
   },
   {
     name: "runtime_inspect",
-    description: "Questions about the running game: the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.",
+    description: "Questions about the running game: what is written on the screen, the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.",
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
       nodePath: {
         type: "string",
-        description: "tree, find: where to start, default /root. rect: the node to place. property: the node to read."
+        description: "tree, find, text: where to start, default /root. rect: the node to place. property: the node to read."
       },
       property: {
         type: "string",
@@ -28285,6 +28325,10 @@ var TOOL_SPECS = [
       },
       group: { type: "string", description: "find: a group the node is in." },
       limit: { type: "number", description: "find: the most nodes to answer with. Default 100." },
+      includeHidden: {
+        type: "boolean",
+        description: "text: read hidden nodes as well, for checking that something is not showing. Default false."
+      },
       metrics: {
         type: "array",
         items: { type: "string" },
@@ -28294,6 +28338,10 @@ var TOOL_SPECS = [
     requires: [],
     operations: {
       tree: { summary: "the live scene tree", requires: [] },
+      text: {
+        summary: "every line of text under nodePath, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+        requires: []
+      },
       find: {
         summary: "the paths of every node matching className, script, namePattern or group, with property read off each",
         requires: []
@@ -28523,6 +28571,10 @@ var FEEDBACK_NOTICE_EVERY = 250;
 var run3 = promisify3(execFile3);
 var __dirname2 = dirname4(fileURLToPath2(import.meta.url));
 var EDITOR_RESTART_TIMEOUT_MS = 90000;
+var SLOWEST_FRAME_RATE = 20;
+function patienceForFrames(frames, atLeast) {
+  return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
+}
 var BRIDGE_RETRY_MS = 2000;
 var PATH_SOLUTIONS = [
   'Give the path relative to the project, such as "scenes/main.tscn" or "res://scenes/main.tscn"',
@@ -29056,6 +29108,12 @@ class GodotServer {
             });
           case "find":
             return await this.handleFindRuntimeNodes(args);
+          case "text":
+            return await this.handleRuntimeCommand("read_text", {
+              projectPath: args["projectPath"],
+              root: readNonEmptyString(args, "nodePath") ?? "/root",
+              include_hidden: readBoolean(args, "includeHidden") ?? false
+            });
           case "rect":
             return await this.handleRuntimeCommand("get_rect", {
               projectPath: args["projectPath"],
@@ -29185,7 +29243,7 @@ class GodotServer {
       return {
         ok: false,
         response: this.createErrorResponse(`The editor is playing the game but its debug adapter did not answer: ${errorMessage(error)}`, [
-          "Godot serves the debug adapter on 6006 unless --dap-port says otherwise",
+          `This asked on port ${this.dap().port}, which is where the connected editor says it serves`,
           "GDHARNESS_DAP_PORT points this server at another one"
         ])
       };
@@ -29552,7 +29610,8 @@ class GodotServer {
     if (payload["error"] !== undefined) {
       const reason = payload["error"];
       return this.createErrorResponse(`Diagnostics unavailable: ${typeof reason === "string" ? reason : JSON.stringify(reason)}`, [
-        "Ensure the Godot editor is running with its language server enabled, on port 6005 or on the port GDHARNESS_LSP_PORT names"
+        `Ensure the Godot editor is running with its language server enabled, on port ${this.editorServes("lspPort", "GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT)}`,
+        "GDHARNESS_LSP_PORT points this server at another one"
       ]);
     }
     const diagnostics = readArray(payload, "diagnostics") ?? [];
@@ -29569,16 +29628,33 @@ class GodotServer {
     });
   }
   async handleLSP(toolName, args) {
-    this.lspClient ??= new GodotLSPClient;
+    const port = this.editorServes("lspPort", "GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT);
+    if (this.lspClient !== null && this.lspClient.port !== port) {
+      await this.lspClient.disconnect();
+      this.lspClient = null;
+    }
+    this.lspClient ??= new GodotLSPClient(port);
     return handleLSPTool(this.lspClient, toolName, args);
   }
   async handleDAP(toolName, args) {
     return handleDAPTool(this.dap(), toolName, args);
   }
   dap() {
-    this.dapClient ??= new GodotDAPClient;
+    const port = this.editorServes("dapPort", "GDHARNESS_DAP_PORT", DEFAULT_DAP_PORT);
+    if (this.dapClient !== null && this.dapClient.port !== port) {
+      this.dapClient = null;
+    }
+    this.dapClient ??= new GodotDAPClient(port);
     return this.dapClient;
   }
+  editorServes(field, variable, fallback) {
+    const named = portFromEnvOrNull(variable);
+    if (named !== null) {
+      return named;
+    }
+    const status = this.godotBridge.getStatus();
+    return (status.connected ? status[field] : undefined) ?? fallback;
+  }
   getEditorStatusPayload() {
     const status = this.godotBridge.getStatus();
     const isPortConflict = this.bridgeStartupError?.includes("EADDRINUSE") ?? false;
@@ -29606,7 +29682,8 @@ class GodotServer {
       const answer = await this.godotBridge.invokeTool("playing_status", {});
       return {
         playing: readBoolean(asParams(answer), "playing") ?? false,
-        scene: readString(asParams(answer), "scenePath") ?? ""
+        scene: readString(asParams(answer), "scenePath") ?? "",
+        debugPort: readNumber(asParams(answer), "debugPort")
       };
     } catch {
       return null;
@@ -29624,15 +29701,19 @@ class GodotServer {
         problem: reply.ok ? null : reply.message
       };
     }));
+    const playing = await this.editorPlayingState();
     return this.jsonTextResponse({
-      editor: this.getEditorStatusPayload(),
+      editor: {
+        ...this.getEditorStatusPayload(),
+        debugPort: playing?.debugPort ?? this.godotBridge.getStatus().debugPort
+      },
       godot: {
         path: godotPath,
         version: godotPath === null ? null : await this.godotVersion(godotPath)
       },
       game: {
         processActive: this.activeProcess !== null,
-        playingInEditor: await this.editorPlayingState(),
+        playingInEditor: playing,
         runtimeConnected: games.some((game) => game.reachable),
         runtimes: games
       }
@@ -29691,10 +29772,10 @@ class GodotServer {
       return project.response;
     }
     if (this.godotBridge.isConnected()) {
-      return this.createErrorResponse("An editor is already connected to this server, and a second one would take the language server and debug adapter ports from it.", [
+      return this.createErrorResponse("An editor is already connected to this server.", [
         "editor_status says which editor is answering, and for which project",
         "editor_launch restart replaces the connected editor rather than joining it",
-        "Close the open editor first if the new project is the one you want"
+        "Another project wants its own gdharness server, which is its own harness session"
       ]);
     }
     const engine = await this.engine();
@@ -29702,10 +29783,16 @@ class GodotServer {
       return engine.response;
     }
     this.logDebug(`Launching Godot editor for project: ${project.value.path}`);
-    const editor = spawn(engine.value, editorArguments(project.value.path), {
+    const ports = await this.portsForAnEditor();
+    const editor = spawn(engine.value, editorArguments(project.value.path, ports), {
       stdio: "ignore",
       detached: true,
-      env: { ...process.env, GDHARNESS_RUNTIME_DIR: runtimeDirectory() }
+      env: {
+        ...process.env,
+        GDHARNESS_RUNTIME_DIR: runtimeDirectory(),
+        GDHARNESS_LSP_PORT: String(ports.lsp),
+        GDHARNESS_DAP_PORT: String(ports.dap)
+      }
     });
     const started = await new Promise((resolve) => {
       editor.once("spawn", () => {
@@ -29722,9 +29809,16 @@ class GodotServer {
     return this.jsonTextResponse({
       launched: true,
       pid: editor.pid ?? null,
-      projectPath: project.value.path
+      projectPath: project.value.path,
+      lspPort: ports.lsp,
+      dapPort: ports.dap
     });
   }
+  async portsForAnEditor() {
+    const lsp = portFromEnvOrNull("GDHARNESS_LSP_PORT") ?? await freePort(DEFAULT_LSP_PORT);
+    const dap = portFromEnvOrNull("GDHARNESS_DAP_PORT") ?? await freePort(DEFAULT_DAP_PORT);
+    return { lsp, dap };
+  }
   async handleRunProject(args, op) {
     const project = this.project(args);
     if (!project.ok) {
@@ -29792,7 +29886,7 @@ class GodotServer {
       await this.dap().connect();
     } catch (error) {
       return this.createErrorResponse(`The editor is connected but its debug adapter is not: ${errorMessage(error)}`, [
-        "Godot serves the debug adapter on 6006 unless --dap-port says otherwise",
+        `This asked on port ${this.dap().port}, which is where the connected editor says it serves`,
         "GDHARNESS_DAP_PORT points this server at another one"
       ]);
     }
@@ -29814,6 +29908,7 @@ class GodotServer {
       through: "editor",
       scene: scene === null ? "the main scene" : `res://${scene}`,
       refreshedClasses,
+      debugPort: readNumber(asParams(JSON.parse(answer.content[0]?.text ?? "{}")), "debugPort"),
       message: "The editor is playing it, so its debugger holds it: the debug_* tools can reach it, " + "editor_output reads its console through the debug adapter, and editor_run stop ends it."
     });
   }
@@ -29996,7 +30091,7 @@ class GodotServer {
   async handleRuntimeCommand(command, args, timeoutMs = this.runtimeTimeoutMs()) {
     const { op: _op, projectPath, ...params } = asParams(args);
     const announced = runtimesAnnounced();
-    const choice = chooseRuntime(announced.running, typeof projectPath === "string" ? projectPath : undefined, announced.unspoken);
+    const choice = chooseRuntime(announced.running, typeof projectPath === "string" ? projectPath : this.ownProject ?? undefined, announced.unspoken);
     if ("problem" in choice) {
       return this.createErrorResponse(choice.problem);
     }
@@ -30063,8 +30158,11 @@ class GodotServer {
     const nodePath = readNonEmptyString(args, "nodePath") ?? "";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
     switch (op) {
-      case "frames":
-        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames: readPositiveNumber(args, "frames") ?? 1 }, patience);
+      case "frames": {
+        const frames = readPositiveNumber(args, "frames") ?? 1;
+        const waited = patienceForFrames(frames, patience);
+        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames }, waited);
+      }
       case "signal":
         return await this.handleRuntimeCommand("wait_signal", {
           projectPath: args["projectPath"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",