gdharness 0.5.9 → 0.5.11

package/build/cli.js

@@ -7229,6 +7229,16 @@ class GameLog {
     this.entries.push(entry);
     this.lastHeadline = headline ? { index: entry.index, detail } : null;
   }
+  record(severity, text) {
+    this.entries.push({
+      index: this.entries.length,
+      severity,
+      source: "debugger",
+      text,
+      detail: []
+    });
+    this.lastHeadline = null;
+  }
   get all() {
     return this.entries;
   }
@@ -15741,7 +15751,10 @@ var init_tool_definitions = __esm(() => {
           type: "string",
           description: "tree, find: where to start, default /root. rect: the node to place. property: the node to read."
         },
-        property: { type: "string", description: "property: which one to read." },
+        property: {
+          type: "string",
+          description: "property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label."
+        },
         depth: { type: "number", description: "tree: levels to descend. Default 3." },
         includeProperties: {
           type: "boolean",
@@ -15768,7 +15781,7 @@ var init_tool_definitions = __esm(() => {
       operations: {
         tree: { summary: "the live scene tree", requires: [] },
         find: {
-          summary: "the paths of every node matching className, script, namePattern or group",
+          summary: "the paths of every node matching className, script, namePattern or group, with property read off each",
           requires: []
         },
         rect: {
@@ -30785,6 +30798,10 @@ var init_ports = __esm(() => {
 // src/dap_client.ts
 import { createConnection } from "node:net";
 import { setTimeout as delay } from "node:timers/promises";
+function said(body, field) {
+  const value = body?.[field];
+  return typeof value === "string" ? value : "";
+}
 
 class GodotDAPClient {
   socket = null;
@@ -30799,7 +30816,7 @@ class GodotDAPClient {
   initialized = false;
   attached = false;
   lastThreadId = 1;
-  stopped = false;
+  halt = null;
   breakpoints = new Map;
   constructor(port = portFromEnv("GDHARNESS_DAP_PORT", DEFAULT_DAP_PORT), host = "127.0.0.1") {
     this.port = port;
@@ -30848,7 +30865,7 @@ class GodotDAPClient {
           this.connected = false;
           this.initialized = false;
           this.attached = false;
-          this.stopped = false;
+          this.halt = null;
           this.socket = null;
           this.failPendingRequests(new Error("DAP connection closed"));
         });
@@ -30868,7 +30885,7 @@ class GodotDAPClient {
       this.connected = false;
       this.initialized = false;
       this.attached = false;
-      this.stopped = false;
+      this.halt = null;
       return;
     }
     if (this.connected) {
@@ -30897,7 +30914,7 @@ class GodotDAPClient {
     this.connected = false;
     this.initialized = false;
     this.attached = false;
-    this.stopped = false;
+    this.halt = null;
   }
   async ensureConnected() {
     if (!this.connected) {
@@ -30974,12 +30991,16 @@ class GodotDAPClient {
       if (typeof threadId === "number") {
         this.lastThreadId = threadId;
       }
-      this.stopped = true;
+      this.halt = {
+        reason: said(body, "reason"),
+        description: said(body, "description"),
+        text: said(body, "text")
+      };
       return;
     }
     if (eventName === "terminated" || eventName === "exited") {
       this.attached = false;
-      this.stopped = false;
+      this.halt = null;
     }
   }
   async initialize() {
@@ -31053,7 +31074,7 @@ class GodotDAPClient {
     await this.attach();
     const resolvedThreadId = await this.resolveThreadId(threadId);
     await this.sendRequest("continue", { threadId: resolvedThreadId });
-    this.stopped = false;
+    this.halt = null;
   }
   async stepOver(threadId) {
     await this.attach();
@@ -31124,7 +31145,10 @@ class GodotDAPClient {
     return this.connected;
   }
   isStopped() {
-    return this.stopped;
+    return this.halt !== null;
+  }
+  whereItStopped() {
+    return this.halt;
   }
   async resolveThreadId(threadId) {
     if (typeof threadId === "number" && threadId > 0) {
@@ -31153,7 +31177,7 @@ class GodotDAPClient {
     this.connected = false;
     this.initialized = false;
     this.attached = false;
-    this.stopped = false;
+    this.halt = null;
     this.reader = new FrameReader;
     socket?.destroy();
     this.failPendingRequests(new Error(`Godot DAP ${detail}. The connection was dropped.`));
@@ -35741,11 +35765,31 @@ var init_runtime_client = __esm(() => {
   ANNOUNCEMENT_PATTERN = /^runtime-(\d+)\.json$/;
 });
 
+// src/setup.ts
+import { cpSync as cpSync2, existsSync as existsSync11, mkdirSync as mkdirSync6, readFileSync as readFileSync11, rmSync as rmSync7, writeFileSync as writeFileSync8 } from "node:fs";
+import { dirname as dirname8, join as join14 } from "node:path";
+function installedAddonVersion(projectPath) {
+  const marker = join14(projectPath, "addons", ADDONS2[0], VERSION_MARKER2);
+  if (!existsSync11(marker)) {
+    return null;
+  }
+  const said = readFileSync11(marker, "utf8").trim();
+  return said === "" ? null : said;
+}
+var ADDONS2, VERSION_MARKER2 = ".gdharness-version";
+var init_setup = __esm(() => {
+  init_class_cache();
+  init_headless();
+  init_resources();
+  init_server_version();
+  ADDONS2 = ["gdharness_editor", "gdharness_runtime", "auto_reload"];
+});
+
 // src/server.ts
 import { execFile as execFile5, spawn } from "node:child_process";
-import { existsSync as existsSync11, mkdtempSync as mkdtempSync3, readdirSync as readdirSync6, readFileSync as readFileSync11, realpathSync as realpathSync2, rmSync as rmSync7 } from "node:fs";
+import { existsSync as existsSync12, mkdtempSync as mkdtempSync3, readdirSync as readdirSync6, readFileSync as readFileSync12, realpathSync as realpathSync2, rmSync as rmSync8 } from "node:fs";
 import { tmpdir as tmpdir5 } from "node:os";
-import { basename as basename2, dirname as dirname8, join as join14, normalize as normalize3 } from "node:path";
+import { basename as basename2, dirname as dirname9, join as join15, normalize as normalize3 } from "node:path";
 import { setTimeout as delay2 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { promisify as promisify5 } from "node:util";
@@ -35771,11 +35815,11 @@ function realPathOr(path) {
   }
 }
 function hasMainScene(projectFile) {
-  const scene = parseProjectGodot(readFileSync11(projectFile, "utf8"))["application"]?.["run/main_scene"];
+  const scene = parseProjectGodot(readFileSync12(projectFile, "utf8"))["application"]?.["run/main_scene"];
   return typeof scene === "string" && scene !== "";
 }
 function editorPlaysHeadless(projectFile) {
-  const runArgs = parseProjectGodot(readFileSync11(projectFile, "utf8"))["editor"]?.["run/main_run_args"];
+  const runArgs = parseProjectGodot(readFileSync12(projectFile, "utf8"))["editor"]?.["run/main_run_args"];
   return typeof runArgs === "string" && /(?:^|\s)--headless(?:\s|$)/.test(runArgs);
 }
 function camelCased(params) {
@@ -35791,7 +35835,7 @@ function camelCased(params) {
 class GodotServer {
   mcp;
   locator = new GodotLocator2;
-  operationsScript = join14(__dirname2, "godot", "operations", "godot_operations.gd");
+  operationsScript = join15(__dirname2, "godot", "operations", "godot_operations.gd");
   godotBridge;
   tools = buildToolDefinitions();
   activeProcess = null;
@@ -36029,28 +36073,44 @@ class GodotServer {
     if (this.callsSinceNotice < UPDATE_NOTICE_EVERY && this.noticedUpdate) {
       return answer;
     }
+    const moved = this.projectHasMovedOn();
+    if (moved !== null) {
+      this.noticedUpdate = true;
+      this.callsSinceNotice = 0;
+      return this.saying(answer, {
+        project_upgraded_under_this_server: {
+          server_is: SERVER_VERSION,
+          project_is: moved,
+          what_to_do: "The project was upgraded while this server has been running, so it is still answering " + "as the version it was started as. Tell the user to reconnect the MCP server, which is " + "the only thing that replaces it: a server cannot restart itself."
+        }
+      });
+    }
     const notice = this.updates.notice();
     if (notice === null) {
       return answer;
     }
     this.noticedUpdate = true;
     this.callsSinceNotice = 0;
+    return this.saying(answer, {
+      update_available: {
+        ...notice,
+        what_to_do: "Tell the user a newer gdharness is out, with what changed, and offer to take it. " + "Only run the upgrade command if they say yes: it restarts their editor and the " + "MCP server has to be reconnected afterwards."
+      }
+    });
+  }
+  saying(answer, block) {
     return {
       ...answer,
-      content: [
-        ...answer.content,
-        {
-          type: "text",
-          text: JSON.stringify({
-            update_available: {
-              ...notice,
-              what_to_do: "Tell the user a newer gdharness is out, with what changed, and offer to take it. " + "Only run the upgrade command if they say yes: it restarts their editor and the " + "MCP server has to be reconnected afterwards."
-            }
-          }, null, 2)
-        }
-      ]
+      content: [...answer.content, { type: "text", text: JSON.stringify(block, null, 2) }]
     };
   }
+  projectHasMovedOn() {
+    if (this.ownProject === null) {
+      return null;
+    }
+    const installed = installedAddonVersion(this.ownProject);
+    return installed === null || installed === SERVER_VERSION ? null : installed;
+  }
   withFeedbackNotice(answer) {
     this.callsSinceFeedback += 1;
     if (this.callsSinceFeedback < FEEDBACK_NOTICE_EVERY) {
@@ -36296,8 +36356,8 @@ class GodotServer {
     if (path === undefined) {
       return { ok: false, response: this.createErrorResponse("projectPath is required.") };
     }
-    const file = join14(path, "project.godot");
-    if (!existsSync11(file)) {
+    const file = join15(path, "project.godot");
+    if (!existsSync12(file)) {
       return {
         ok: false,
         response: this.createErrorResponse(`Not a Godot project: ${path}`, [
@@ -36442,7 +36502,7 @@ class GodotServer {
     if (!engine.ok) {
       return engine.response;
     }
-    const application = parseProjectGodot(readFileSync11(project.value.file, "utf8"))["application"] ?? {};
+    const application = parseProjectGodot(readFileSync12(project.value.file, "utf8"))["application"] ?? {};
     const name = application["config/name"];
     const mainScene = application["run/main_scene"];
     const info = {
@@ -36531,7 +36591,7 @@ class GodotServer {
     log.finish();
     const problems = log.select({ severity: "warning", sinceLastCall: false, limit: 200 });
     const verdict = {
-      exported: exitCode === 0 && log.count("error") === 0 && existsSync11(output.absolutePath),
+      exported: exitCode === 0 && log.count("error") === 0 && existsSync12(output.absolutePath),
       preset,
       outputPath: output.relativePath,
       debug,
@@ -36561,7 +36621,7 @@ class GodotServer {
       return contained.response;
     }
     const runner = "addons/gdUnit4/bin/GdUnitCmdTool.gd";
-    if (!existsSync11(join14(project.value.path, runner))) {
+    if (!existsSync12(join15(project.value.path, runner))) {
       return this.createErrorResponse(`gdUnit4 is not installed in this project: no ${runner}.`, [
         "Install gdUnit4 under addons/gdUnit4, from https://github.com/godot-gdunit-labs/gdUnit4"
       ]);
@@ -36594,7 +36654,7 @@ class GodotServer {
     ];
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 600000;
     this.logDebug(`Running tests: ${engine.value} ${cmdArgs.join(" ")}`);
-    const userData = mkdtempSync3(join14(tmpdir5(), "gdharness-tests-"));
+    const userData = mkdtempSync3(join15(tmpdir5(), "gdharness-tests-"));
     const run = this.spawnGame(engine.value, cmdArgs, userDataIn(userData));
     const hung = await new Promise((resolve) => {
       const timer = setTimeout(() => {
@@ -36610,20 +36670,20 @@ class GodotServer {
         resolve(false);
       });
     });
-    const reportsDir = join14(project.value.path, ".godot", "gdharness-reports");
+    const reportsDir = join15(project.value.path, ".godot", "gdharness-reports");
     let report = null;
     let reportProblem = null;
     try {
-      const written = existsSync11(reportsDir) ? readdirSync6(reportsDir).filter((name) => name.startsWith("report_")).sort((a, b) => Number(a.slice("report_".length)) - Number(b.slice("report_".length))) : [];
+      const written = existsSync12(reportsDir) ? readdirSync6(reportsDir).filter((name) => name.startsWith("report_")).sort((a, b) => Number(a.slice("report_".length)) - Number(b.slice("report_".length))) : [];
       const newest = written.at(-1);
       if (newest !== undefined) {
-        report = parseJUnit(readFileSync11(join14(reportsDir, newest, "results.xml"), "utf8"));
+        report = parseJUnit(readFileSync12(join15(reportsDir, newest, "results.xml"), "utf8"));
       }
     } catch (error) {
       reportProblem = errorMessage(error);
     } finally {
-      rmSync7(reportsDir, { recursive: true, force: true });
-      rmSync7(userData, { recursive: true, force: true });
+      rmSync8(reportsDir, { recursive: true, force: true });
+      rmSync8(userData, { recursive: true, force: true });
     }
     const engineEntries = run.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries;
     const verdicts = {
@@ -36737,6 +36797,7 @@ class GodotServer {
       staleNote: stale ? addonMismatch(status.addonVersion, SERVER_VERSION) : undefined,
       retryingBridge: this.bridgeRetry === null ? undefined : true,
       announcedAt: this.announcedAt ?? undefined,
+      projectIs: this.projectHasMovedOn() ?? undefined,
       note: isPortConflict ? "Bridge port is already in use. Another gdharness instance owns the editor bridge, so this server cannot reach the editor. Usually the server this one replaced, still on its way out." : undefined,
       suggestion: isPortConflict ? `This server is asking for the port again every ${BRIDGE_RETRY_MS / 1000}s and takes it the moment the other one lets go, so editor tools come back on their own. Ask again, or end the older gdharness process to have it now.` : undefined
     };
@@ -36949,7 +37010,8 @@ class GodotServer {
       log,
       startedAt: Date.now(),
       exitCode: null,
-      throughEditor: true
+      throughEditor: true,
+      brokeOn: null
     };
     this.activeProcess = played;
     return this.jsonTextResponse({
@@ -36969,6 +37031,15 @@ class GodotServer {
 `) ? line : `${line}
 `);
     }
+    this.recordWhatItBrokeOn(game);
+  }
+  recordWhatItBrokeOn(game) {
+    const halt = this.dapClient?.whereItStopped() ?? null;
+    if (halt?.reason !== "exception" || halt.text === "" || game.brokeOn === halt.text) {
+      return;
+    }
+    game.brokeOn = halt.text;
+    game.log.record("error", halt.text);
   }
   async endActiveGame() {
     const running = this.activeProcess;
@@ -36990,7 +37061,8 @@ class GodotServer {
       log,
       startedAt: Date.now(),
       exitCode: null,
-      throughEditor: false
+      throughEditor: false,
+      brokeOn: null
     };
     child.stdout.on("data", (data) => {
       log.append("stdout", data);
@@ -37055,6 +37127,7 @@ class GodotServer {
       contains: readNonEmptyString(args, "contains"),
       limit: readPositiveNumber(args, "limit") ?? 200
     });
+    const halt = this.activeProcess.throughEditor ? this.dapClient?.whereItStopped() ?? null : null;
     return this.jsonTextResponse({
       running: this.activeProcess.exitCode === null,
       exitCode: this.activeProcess.exitCode,
@@ -37063,6 +37136,7 @@ class GodotServer {
       errors: this.activeProcess.log.count("error"),
       warnings: this.activeProcess.log.count("warning"),
       clean: this.activeProcess.log.count("error") === 0,
+      heldAt: halt,
       omitted: selected.omitted,
       entries: selected.entries
     });
@@ -37132,8 +37206,8 @@ class GodotServer {
       return this.createErrorResponse(choice.problem);
     }
     const expectsScreenshot = command === "capture_screenshot" || command === "capture_viewport";
-    const screenshotDir = expectsScreenshot ? mkdtempSync3(join14(tmpdir5(), "gdharness-runtime-screenshot-")) : null;
-    const screenshotPath = screenshotDir ? join14(screenshotDir, "capture.png") : null;
+    const screenshotDir = expectsScreenshot ? mkdtempSync3(join15(tmpdir5(), "gdharness-runtime-screenshot-")) : null;
+    const screenshotPath = screenshotDir ? join15(screenshotDir, "capture.png") : null;
     try {
       const reply = await runtimeRequest(choice.endpoint, command, screenshotPath ? { ...params, output_path: screenshotPath } : params, timeoutMs);
       if (!reply.ok) {
@@ -37154,12 +37228,12 @@ class GodotServer {
       return {
         content: [
           { type: "text", text: `Screenshot captured: ${dimensions}` },
-          { type: "image", data: readFileSync11(screenshotPath).toString("base64"), mimeType: "image/png" }
+          { type: "image", data: readFileSync12(screenshotPath).toString("base64"), mimeType: "image/png" }
         ]
       };
     } finally {
       if (screenshotDir) {
-        rmSync7(screenshotDir, { recursive: true, force: true });
+        rmSync8(screenshotDir, { recursive: true, force: true });
       }
     }
   }
@@ -37180,11 +37254,13 @@ class GodotServer {
     if (Object.keys(filters).length === 0) {
       return this.createErrorResponse("runtime_inspect find needs at least one of className, script, namePattern, group.");
     }
+    const property = readNonEmptyString(args, "property");
     return await this.handleRuntimeCommand("find_nodes", {
       ...filters,
       projectPath: args["projectPath"],
       root: readNonEmptyString(args, "nodePath") ?? "/root",
-      limit: readPositiveNumber(args, "limit") ?? 100
+      limit: readPositiveNumber(args, "limit") ?? 100,
+      ...property === undefined ? {} : { property }
     });
   }
   async handleRuntimeWait(op, args) {
@@ -37237,10 +37313,11 @@ var init_server3 = __esm(() => {
   init_resources();
   init_runtime_client();
   init_server_version();
+  init_setup();
   init_tool_definitions();
   init_update_check();
   run5 = promisify5(execFile5);
-  __dirname2 = dirname8(fileURLToPath4(import.meta.url));
+  __dirname2 = dirname9(fileURLToPath4(import.meta.url));
   PATH_SOLUTIONS = [
     'Give the path relative to the project, such as "scenes/main.tscn" or "res://scenes/main.tscn"',
     "Point projectPath at the project the file belongs to"
@@ -37297,8 +37374,8 @@ var init_server3 = __esm(() => {
 });
 
 // src/cli.ts
-import { existsSync as existsSync12 } from "fs";
-import { join as join15, resolve as resolve5 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { join as join16, resolve as resolve5 } from "path";
 
 // src/errors.ts
 class Refusal extends Error {
@@ -38700,7 +38777,7 @@ class UsageError extends Refusal {
 function projectArgument(at) {
   const named = args.slice(at).find((value) => !value.startsWith("--"));
   const projectPath = resolve5(named ?? ".");
-  if (!existsSync12(join15(projectPath, "project.godot"))) {
+  if (!existsSync13(join16(projectPath, "project.godot"))) {
     throw new UsageError(`Not a Godot project: ${projectPath} holds no project.godot.`);
   }
   return projectPath;
@@ -38712,7 +38789,7 @@ async function engine() {
   }
   return { godotPath, script: shippedOperationsScript(), debug: GODOT_DEBUG_MODE_DEFAULT2 };
 }
-function said(outcome, what) {
+function said2(outcome, what) {
   if (!outcome.ok) {
     throw new Refusal(`${what}: ${outcome.message}`);
   }
@@ -38813,15 +38890,15 @@ async function setup() {
   const enabled = await enablePlugins(godot, projectPath, EDITOR_PLUGINS);
   for (const [index, outcome] of enabled.entries()) {
     const name = EDITOR_PLUGINS[index] ?? "";
-    said(outcome, `enabling ${name}`);
+    said2(outcome, `enabling ${name}`);
     console.log(`${name}: ${outcome.ok ? String(outcome.payload["action"]) : "failed"}`);
   }
   if (runtime) {
-    said(await setRuntime(godot, projectPath, true), "registering the runtime autoload");
+    said2(await setRuntime(godot, projectPath, true), "registering the runtime autoload");
     console.log(`${RUNTIME_AUTOLOAD.name} autoload registered`);
   }
   const classes = await runOperation(godot, "refresh_class_cache", {}, projectPath);
-  said(classes, "rebuilding the class list");
+  said2(classes, "rebuilding the class list");
   if (classes.ok) {
     console.log(`class list rebuilt: ${String(classes.payload["classes"])} classes`);
   }
@@ -38844,7 +38921,7 @@ async function setup() {
       console.log("no harness configured; name one yourself, and gdharness harnesses lists them all");
     }
     if (!args.includes("--no-skill")) {
-      const directories = skillDirectories(chosen.harnesses, projectPath, existsSync12);
+      const directories = skillDirectories(chosen.harnesses, projectPath, existsSync13);
       for (const written of writeSkill(directories, getLocalVersion())) {
         console.log(`skill: ${written.replaced ? "replaced" : "written"} ${written.path}`);
       }
@@ -38883,11 +38960,11 @@ async function uninstall() {
   const disabled = await disablePlugins(godot, projectPath, enabled);
   for (const [index, outcome] of disabled.entries()) {
     const name = enabled[index] ?? "";
-    said(outcome, `disabling ${name}`);
+    said2(outcome, `disabling ${name}`);
     console.log(`${name}: ${outcome.ok ? String(outcome.payload["action"]) : "failed"}`);
   }
   if (before.runtimeAutoload) {
-    said(await setRuntime(godot, projectPath, false), "removing the runtime autoload");
+    said2(await setRuntime(godot, projectPath, false), "removing the runtime autoload");
     console.log(`${RUNTIME_AUTOLOAD.name} autoload removed`);
   }
   const addons = removeAddons(projectPath);
@@ -38915,12 +38992,12 @@ async function upgrade() {
   }
   const enabled = await enablePlugins(godot, projectPath, EDITOR_PLUGINS);
   for (const [index, outcome] of enabled.entries()) {
-    said(outcome, `enabling ${EDITOR_PLUGINS[index] ?? ""}`);
+    said2(outcome, `enabling ${EDITOR_PLUGINS[index] ?? ""}`);
   }
   if (before.runtimeAutoload) {
-    said(await setRuntime(godot, projectPath, true), "registering the runtime autoload");
+    said2(await setRuntime(godot, projectPath, true), "registering the runtime autoload");
   }
-  said(await runOperation(godot, "refresh_class_cache", {}, projectPath), "rebuilding the class list");
+  said2(await runOperation(godot, "refresh_class_cache", {}, projectPath), "rebuilding the class list");
   const launch = launchFor(version, godot.godotPath, projectPath);
   const already = HARNESSES.filter((harness) => registered(harness, projectPath));
   for (const group of groupByFile(already, projectPath)) {
@@ -38929,7 +39006,7 @@ async function upgrade() {
   if (already.length === 0) {
     console.log("no harness config names gdharness, so none was re-pinned");
   }
-  for (const written of writeSkill(skillDirectories(already, projectPath, existsSync12), version)) {
+  for (const written of writeSkill(skillDirectories(already, projectPath, existsSync13), version)) {
     console.log(`skill: ${written.replaced ? "replaced" : "written"} ${written.path}`);
   }
   console.log(`
@@ -38965,14 +39042,14 @@ async function runtime3() {
   }
   const projectPath = projectArgument(2);
   const godot = await engine();
-  said(await setRuntime(godot, projectPath, state === "on"), `turning the runtime ${state}`);
+  said2(await setRuntime(godot, projectPath, state === "on"), `turning the runtime ${state}`);
   console.log(`${RUNTIME_AUTOLOAD.name} autoload ${state === "on" ? "registered" : "removed"}`);
 }
 async function classes() {
   const projectPath = projectArgument(1);
   const godot = await engine();
   const outcome = await runOperation(godot, "refresh_class_cache", {}, projectPath);
-  said(outcome, "rebuilding the class list");
+  said2(outcome, "rebuilding the class list");
   if (outcome.ok) {
     console.log(JSON.stringify(outcome.payload, null, 2));
   }

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

@@ -36,12 +36,19 @@ func get_tree(params: Dictionary) -> Dictionary:
 ## Nodes matching every filter given, as paths, so a caller can name what it wants without
 ## reading the whole tree to find it. `class` matches native classes and their subclasses, and
 ## the global name of a script class; `name` is a case-insensitive glob; `script` is a path.
+##
+## `property` names one to read off each of them, which is the difference between one question and
+## one call per answer. A panel of a dozen labels took thirteen calls to read, and a tree that
+## rebuilds between them, which any HUD following a clock does, hands back paths that are gone by
+## the time they are asked about. A node without that property says so rather than answering null,
+## because null is what a node holding null answers.
 func find_nodes(params: Dictionary) -> Dictionary:
 	var root_path: String = str(params.get("root", "/root"))
 	var wanted_class: String = str(params.get("class", ""))
 	var wanted_script: String = str(params.get("script", ""))
 	var wanted_name: String = str(params.get("name", ""))
 	var wanted_group: String = str(params.get("group", ""))
+	var wanted_property: String = str(params.get("property", ""))
 	var limit: int = clampi(int(params.get("limit", FIND_LIMIT)), 1, FIND_LIMIT_CEILING)
 
 	if (
@@ -67,7 +74,7 @@ func find_nodes(params: Dictionary) -> Dictionary:
 			if found.size() >= limit:
 				truncated = true
 				break
-			found.append(_serialize_node(node, false))
+			found.append(_found(node, wanted_property))
 		var children: Array[Node] = node.get_children()
 		for index: int in range(children.size() - 1, -1, -1):
 			pending.push_front(children[index])
@@ -75,6 +82,29 @@ func find_nodes(params: Dictionary) -> Dictionary:
 	return {"type": "nodes", "count": found.size(), "truncated": truncated, "nodes": found}
 
 
+## One match, with the named property on it when one was named.
+##
+## `has_property` alongside the value, because a node that has not got it and a node holding null
+## are different answers and a bare null reads as the second. The same distinction the `property`
+## op makes by refusing, which it cannot do here: a find over a panel matches nodes of several
+## classes on purpose, and refusing the whole answer because one of them has no `text` would make
+## the question unaskable.
+func _found(node: Node, wanted_property: String) -> Dictionary:
+	var entry: Dictionary = _serialize_node(node, false)
+	if wanted_property.is_empty():
+		return entry
+	var has: bool = false
+	for prop: Dictionary in node.get_property_list():
+		if str(prop["name"]) == wanted_property:
+			has = true
+			break
+	entry["property"] = wanted_property
+	entry["has_property"] = has
+	if has:
+		entry["value"] = _values.serialize(node.get(wanted_property))
+	return entry
+
+
 func _matches(
 	node: Node, wanted_class: String, wanted_script: String, wanted_name: String, wanted_group: String
 ) -> bool:

package/build/index.js

@@ -10126,9 +10126,9 @@ function defectReport(where, error, godotVersion) {
 
 // src/server.ts
 import { execFile as execFile3, spawn } from "node:child_process";
-import { existsSync as existsSync6, mkdtempSync as mkdtempSync2, readdirSync as readdirSync5, readFileSync as readFileSync7, realpathSync as realpathSync2, rmSync as rmSync3 } from "node:fs";
+import { existsSync as existsSync7, mkdtempSync as mkdtempSync2, readdirSync as readdirSync5, readFileSync as readFileSync8, realpathSync as realpathSync2, rmSync as rmSync4 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { basename, dirname as dirname3, join as join8, normalize as normalize2 } from "node:path";
+import { basename, dirname as dirname4, join as join9, normalize as normalize2 } from "node:path";
 import { setTimeout as delay2 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { promisify as promisify3 } from "node:util";
@@ -24878,6 +24878,10 @@ var DEFAULT_DAP_PORT = 6006;
 var DAP_REQUEST_TIMEOUT_MS = 1e4;
 var SCOPES_TIMEOUT_MS = 20000;
 var VARIABLES_POLL_TIMEOUT_MS = 2000;
+function said(body, field) {
+  const value = body?.[field];
+  return typeof value === "string" ? value : "";
+}
 
 class GodotDAPClient {
   socket = null;
@@ -24892,7 +24896,7 @@ class GodotDAPClient {
   initialized = false;
   attached = false;
   lastThreadId = 1;
-  stopped = false;
+  halt = null;
   breakpoints = new Map;
   constructor(port = portFromEnv("GDHARNESS_DAP_PORT", DEFAULT_DAP_PORT), host = "127.0.0.1") {
     this.port = port;
@@ -24941,7 +24945,7 @@ class GodotDAPClient {
           this.connected = false;
           this.initialized = false;
           this.attached = false;
-          this.stopped = false;
+          this.halt = null;
           this.socket = null;
           this.failPendingRequests(new Error("DAP connection closed"));
         });
@@ -24961,7 +24965,7 @@ class GodotDAPClient {
       this.connected = false;
       this.initialized = false;
       this.attached = false;
-      this.stopped = false;
+      this.halt = null;
       return;
     }
     if (this.connected) {
@@ -24990,7 +24994,7 @@ class GodotDAPClient {
     this.connected = false;
     this.initialized = false;
     this.attached = false;
-    this.stopped = false;
+    this.halt = null;
   }
   async ensureConnected() {
     if (!this.connected) {
@@ -25067,12 +25071,16 @@ class GodotDAPClient {
       if (typeof threadId === "number") {
         this.lastThreadId = threadId;
       }
-      this.stopped = true;
+      this.halt = {
+        reason: said(body, "reason"),
+        description: said(body, "description"),
+        text: said(body, "text")
+      };
       return;
     }
     if (eventName === "terminated" || eventName === "exited") {
       this.attached = false;
-      this.stopped = false;
+      this.halt = null;
     }
   }
   async initialize() {
@@ -25146,7 +25154,7 @@ class GodotDAPClient {
     await this.attach();
     const resolvedThreadId = await this.resolveThreadId(threadId);
     await this.sendRequest("continue", { threadId: resolvedThreadId });
-    this.stopped = false;
+    this.halt = null;
   }
   async stepOver(threadId) {
     await this.attach();
@@ -25217,7 +25225,10 @@ class GodotDAPClient {
     return this.connected;
   }
   isStopped() {
-    return this.stopped;
+    return this.halt !== null;
+  }
+  whereItStopped() {
+    return this.halt;
   }
   async resolveThreadId(threadId) {
     if (typeof threadId === "number" && threadId > 0) {
@@ -25246,7 +25257,7 @@ class GodotDAPClient {
     this.connected = false;
     this.initialized = false;
     this.attached = false;
-    this.stopped = false;
+    this.halt = null;
     this.reader = new FrameReader;
     socket?.destroy();
     this.failPendingRequests(new Error(`Godot DAP ${detail}. The connection was dropped.`));
@@ -25402,6 +25413,16 @@ class GameLog {
     this.entries.push(entry);
     this.lastHeadline = headline ? { index: entry.index, detail } : null;
   }
+  record(severity, text) {
+    this.entries.push({
+      index: this.entries.length,
+      severity,
+      source: "debugger",
+      text,
+      detail: []
+    });
+    this.lastHeadline = null;
+  }
   get all() {
     return this.entries;
   }
@@ -27557,6 +27578,20 @@ function runtimeRequest(endpoint, command, params, timeoutMs) {
   });
 }
 
+// src/setup.ts
+import { cpSync, existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync7, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname3, join as join8 } from "node:path";
+var ADDONS = ["gdharness_editor", "gdharness_runtime", "auto_reload"];
+var VERSION_MARKER = ".gdharness-version";
+function installedAddonVersion(projectPath) {
+  const marker = join8(projectPath, "addons", ADDONS[0], VERSION_MARKER);
+  if (!existsSync6(marker)) {
+    return null;
+  }
+  const said = readFileSync7(marker, "utf8").trim();
+  return said === "" ? null : said;
+}
+
 // src/tool-definitions.ts
 var PROJECT_PATH = {
   type: "string",
@@ -28230,7 +28265,10 @@ var TOOL_SPECS = [
         type: "string",
         description: "tree, find: where to start, default /root. rect: the node to place. property: the node to read."
       },
-      property: { type: "string", description: "property: which one to read." },
+      property: {
+        type: "string",
+        description: "property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label."
+      },
       depth: { type: "number", description: "tree: levels to descend. Default 3." },
       includeProperties: {
         type: "boolean",
@@ -28257,7 +28295,7 @@ var TOOL_SPECS = [
     operations: {
       tree: { summary: "the live scene tree", requires: [] },
       find: {
-        summary: "the paths of every node matching className, script, namePattern or group",
+        summary: "the paths of every node matching className, script, namePattern or group, with property read off each",
         requires: []
       },
       rect: {
@@ -28472,7 +28510,7 @@ function buildToolDefinitions() {
 var UPDATE_NOTICE_EVERY = 500;
 var FEEDBACK_NOTICE_EVERY = 250;
 var run3 = promisify3(execFile3);
-var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
+var __dirname2 = dirname4(fileURLToPath2(import.meta.url));
 var EDITOR_RESTART_TIMEOUT_MS = 90000;
 var BRIDGE_RETRY_MS = 2000;
 var PATH_SOLUTIONS = [
@@ -28550,11 +28588,11 @@ function realPathOr(path) {
   }
 }
 function hasMainScene(projectFile) {
-  const scene = parseProjectGodot(readFileSync7(projectFile, "utf8"))["application"]?.["run/main_scene"];
+  const scene = parseProjectGodot(readFileSync8(projectFile, "utf8"))["application"]?.["run/main_scene"];
   return typeof scene === "string" && scene !== "";
 }
 function editorPlaysHeadless(projectFile) {
-  const runArgs = parseProjectGodot(readFileSync7(projectFile, "utf8"))["editor"]?.["run/main_run_args"];
+  const runArgs = parseProjectGodot(readFileSync8(projectFile, "utf8"))["editor"]?.["run/main_run_args"];
   return typeof runArgs === "string" && /(?:^|\s)--headless(?:\s|$)/.test(runArgs);
 }
 function camelCased(params) {
@@ -28570,7 +28608,7 @@ function camelCased(params) {
 class GodotServer {
   mcp;
   locator = new GodotLocator;
-  operationsScript = join8(__dirname2, "godot", "operations", "godot_operations.gd");
+  operationsScript = join9(__dirname2, "godot", "operations", "godot_operations.gd");
   godotBridge;
   tools = buildToolDefinitions();
   activeProcess = null;
@@ -28808,28 +28846,44 @@ class GodotServer {
     if (this.callsSinceNotice < UPDATE_NOTICE_EVERY && this.noticedUpdate) {
       return answer;
     }
+    const moved = this.projectHasMovedOn();
+    if (moved !== null) {
+      this.noticedUpdate = true;
+      this.callsSinceNotice = 0;
+      return this.saying(answer, {
+        project_upgraded_under_this_server: {
+          server_is: SERVER_VERSION,
+          project_is: moved,
+          what_to_do: "The project was upgraded while this server has been running, so it is still answering " + "as the version it was started as. Tell the user to reconnect the MCP server, which is " + "the only thing that replaces it: a server cannot restart itself."
+        }
+      });
+    }
     const notice = this.updates.notice();
     if (notice === null) {
       return answer;
     }
     this.noticedUpdate = true;
     this.callsSinceNotice = 0;
+    return this.saying(answer, {
+      update_available: {
+        ...notice,
+        what_to_do: "Tell the user a newer gdharness is out, with what changed, and offer to take it. " + "Only run the upgrade command if they say yes: it restarts their editor and the " + "MCP server has to be reconnected afterwards."
+      }
+    });
+  }
+  saying(answer, block) {
     return {
       ...answer,
-      content: [
-        ...answer.content,
-        {
-          type: "text",
-          text: JSON.stringify({
-            update_available: {
-              ...notice,
-              what_to_do: "Tell the user a newer gdharness is out, with what changed, and offer to take it. " + "Only run the upgrade command if they say yes: it restarts their editor and the " + "MCP server has to be reconnected afterwards."
-            }
-          }, null, 2)
-        }
-      ]
+      content: [...answer.content, { type: "text", text: JSON.stringify(block, null, 2) }]
     };
   }
+  projectHasMovedOn() {
+    if (this.ownProject === null) {
+      return null;
+    }
+    const installed = installedAddonVersion(this.ownProject);
+    return installed === null || installed === SERVER_VERSION ? null : installed;
+  }
   withFeedbackNotice(answer) {
     this.callsSinceFeedback += 1;
     if (this.callsSinceFeedback < FEEDBACK_NOTICE_EVERY) {
@@ -29075,8 +29129,8 @@ class GodotServer {
     if (path === undefined) {
       return { ok: false, response: this.createErrorResponse("projectPath is required.") };
     }
-    const file = join8(path, "project.godot");
-    if (!existsSync6(file)) {
+    const file = join9(path, "project.godot");
+    if (!existsSync7(file)) {
       return {
         ok: false,
         response: this.createErrorResponse(`Not a Godot project: ${path}`, [
@@ -29221,7 +29275,7 @@ class GodotServer {
     if (!engine.ok) {
       return engine.response;
     }
-    const application = parseProjectGodot(readFileSync7(project.value.file, "utf8"))["application"] ?? {};
+    const application = parseProjectGodot(readFileSync8(project.value.file, "utf8"))["application"] ?? {};
     const name = application["config/name"];
     const mainScene = application["run/main_scene"];
     const info = {
@@ -29310,7 +29364,7 @@ class GodotServer {
     log.finish();
     const problems = log.select({ severity: "warning", sinceLastCall: false, limit: 200 });
     const verdict = {
-      exported: exitCode === 0 && log.count("error") === 0 && existsSync6(output.absolutePath),
+      exported: exitCode === 0 && log.count("error") === 0 && existsSync7(output.absolutePath),
       preset,
       outputPath: output.relativePath,
       debug,
@@ -29340,7 +29394,7 @@ class GodotServer {
       return contained.response;
     }
     const runner = "addons/gdUnit4/bin/GdUnitCmdTool.gd";
-    if (!existsSync6(join8(project.value.path, runner))) {
+    if (!existsSync7(join9(project.value.path, runner))) {
       return this.createErrorResponse(`gdUnit4 is not installed in this project: no ${runner}.`, [
         "Install gdUnit4 under addons/gdUnit4, from https://github.com/godot-gdunit-labs/gdUnit4"
       ]);
@@ -29373,7 +29427,7 @@ class GodotServer {
     ];
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 600000;
     this.logDebug(`Running tests: ${engine.value} ${cmdArgs.join(" ")}`);
-    const userData = mkdtempSync2(join8(tmpdir4(), "gdharness-tests-"));
+    const userData = mkdtempSync2(join9(tmpdir4(), "gdharness-tests-"));
     const run = this.spawnGame(engine.value, cmdArgs, userDataIn(userData));
     const hung = await new Promise((resolve) => {
       const timer = setTimeout(() => {
@@ -29389,20 +29443,20 @@ class GodotServer {
         resolve(false);
       });
     });
-    const reportsDir = join8(project.value.path, ".godot", "gdharness-reports");
+    const reportsDir = join9(project.value.path, ".godot", "gdharness-reports");
     let report = null;
     let reportProblem = null;
     try {
-      const written = existsSync6(reportsDir) ? readdirSync5(reportsDir).filter((name) => name.startsWith("report_")).sort((a, b) => Number(a.slice("report_".length)) - Number(b.slice("report_".length))) : [];
+      const written = existsSync7(reportsDir) ? readdirSync5(reportsDir).filter((name) => name.startsWith("report_")).sort((a, b) => Number(a.slice("report_".length)) - Number(b.slice("report_".length))) : [];
       const newest = written.at(-1);
       if (newest !== undefined) {
-        report = parseJUnit(readFileSync7(join8(reportsDir, newest, "results.xml"), "utf8"));
+        report = parseJUnit(readFileSync8(join9(reportsDir, newest, "results.xml"), "utf8"));
       }
     } catch (error) {
       reportProblem = errorMessage(error);
     } finally {
-      rmSync3(reportsDir, { recursive: true, force: true });
-      rmSync3(userData, { recursive: true, force: true });
+      rmSync4(reportsDir, { recursive: true, force: true });
+      rmSync4(userData, { recursive: true, force: true });
     }
     const engineEntries = run.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries;
     const verdicts = {
@@ -29516,6 +29570,7 @@ class GodotServer {
       staleNote: stale ? addonMismatch(status.addonVersion, SERVER_VERSION) : undefined,
       retryingBridge: this.bridgeRetry === null ? undefined : true,
       announcedAt: this.announcedAt ?? undefined,
+      projectIs: this.projectHasMovedOn() ?? undefined,
       note: isPortConflict ? "Bridge port is already in use. Another gdharness instance owns the editor bridge, so this server cannot reach the editor. Usually the server this one replaced, still on its way out." : undefined,
       suggestion: isPortConflict ? `This server is asking for the port again every ${BRIDGE_RETRY_MS / 1000}s and takes it the moment the other one lets go, so editor tools come back on their own. Ask again, or end the older gdharness process to have it now.` : undefined
     };
@@ -29728,7 +29783,8 @@ class GodotServer {
       log,
       startedAt: Date.now(),
       exitCode: null,
-      throughEditor: true
+      throughEditor: true,
+      brokeOn: null
     };
     this.activeProcess = played;
     return this.jsonTextResponse({
@@ -29748,6 +29804,15 @@ class GodotServer {
 `) ? line : `${line}
 `);
     }
+    this.recordWhatItBrokeOn(game);
+  }
+  recordWhatItBrokeOn(game) {
+    const halt = this.dapClient?.whereItStopped() ?? null;
+    if (halt?.reason !== "exception" || halt.text === "" || game.brokeOn === halt.text) {
+      return;
+    }
+    game.brokeOn = halt.text;
+    game.log.record("error", halt.text);
   }
   async endActiveGame() {
     const running = this.activeProcess;
@@ -29769,7 +29834,8 @@ class GodotServer {
       log,
       startedAt: Date.now(),
       exitCode: null,
-      throughEditor: false
+      throughEditor: false,
+      brokeOn: null
     };
     child.stdout.on("data", (data) => {
       log.append("stdout", data);
@@ -29834,6 +29900,7 @@ class GodotServer {
       contains: readNonEmptyString(args, "contains"),
       limit: readPositiveNumber(args, "limit") ?? 200
     });
+    const halt = this.activeProcess.throughEditor ? this.dapClient?.whereItStopped() ?? null : null;
     return this.jsonTextResponse({
       running: this.activeProcess.exitCode === null,
       exitCode: this.activeProcess.exitCode,
@@ -29842,6 +29909,7 @@ class GodotServer {
       errors: this.activeProcess.log.count("error"),
       warnings: this.activeProcess.log.count("warning"),
       clean: this.activeProcess.log.count("error") === 0,
+      heldAt: halt,
       omitted: selected.omitted,
       entries: selected.entries
     });
@@ -29911,8 +29979,8 @@ class GodotServer {
       return this.createErrorResponse(choice.problem);
     }
     const expectsScreenshot = command === "capture_screenshot" || command === "capture_viewport";
-    const screenshotDir = expectsScreenshot ? mkdtempSync2(join8(tmpdir4(), "gdharness-runtime-screenshot-")) : null;
-    const screenshotPath = screenshotDir ? join8(screenshotDir, "capture.png") : null;
+    const screenshotDir = expectsScreenshot ? mkdtempSync2(join9(tmpdir4(), "gdharness-runtime-screenshot-")) : null;
+    const screenshotPath = screenshotDir ? join9(screenshotDir, "capture.png") : null;
     try {
       const reply = await runtimeRequest(choice.endpoint, command, screenshotPath ? { ...params, output_path: screenshotPath } : params, timeoutMs);
       if (!reply.ok) {
@@ -29933,12 +30001,12 @@ class GodotServer {
       return {
         content: [
           { type: "text", text: `Screenshot captured: ${dimensions}` },
-          { type: "image", data: readFileSync7(screenshotPath).toString("base64"), mimeType: "image/png" }
+          { type: "image", data: readFileSync8(screenshotPath).toString("base64"), mimeType: "image/png" }
         ]
       };
     } finally {
       if (screenshotDir) {
-        rmSync3(screenshotDir, { recursive: true, force: true });
+        rmSync4(screenshotDir, { recursive: true, force: true });
       }
     }
   }
@@ -29959,11 +30027,13 @@ class GodotServer {
     if (Object.keys(filters).length === 0) {
       return this.createErrorResponse("runtime_inspect find needs at least one of className, script, namePattern, group.");
     }
+    const property = readNonEmptyString(args, "property");
     return await this.handleRuntimeCommand("find_nodes", {
       ...filters,
       projectPath: args["projectPath"],
       root: readNonEmptyString(args, "nodePath") ?? "/root",
-      limit: readPositiveNumber(args, "limit") ?? 100
+      limit: readPositiveNumber(args, "limit") ?? 100,
+      ...property === undefined ? {} : { property }
     });
   }
   async handleRuntimeWait(op, args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "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",