gdharness 1.0.13 → 1.0.15

package/build/cli.js

@@ -16398,7 +16398,11 @@ var init_tool_definitions = __esm(() => {
           description: "viewport: the Viewport node. Default the root viewport."
         },
         width: { type: "number", description: "Scale the image to this width." },
-        height: { type: "number", description: "Scale the image to this height." }
+        height: { type: "number", description: "Scale the image to this height." },
+        outputPath: {
+          type: "string",
+          description: "Also save the picture as a PNG at this absolute path, for somebody to open later; the answer says where. Refused unless it ends in .png, its directory exists, it is outside the project, and no file is there already."
+        }
       },
       requires: [],
       operations: {
@@ -16421,7 +16425,7 @@ var init_tool_definitions = __esm(() => {
         action: {
           type: "string",
           ops: ["action"],
-          description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with key Escape, or click its button."
+          description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with the key op and keycode Escape, or click its button."
         },
         pressed: {
           type: "boolean",
@@ -16524,7 +16528,11 @@ var init_tool_definitions = __esm(() => {
           ops: ["frames"],
           description: "frames: how many to let pass, 1 to 600. More than that is refused."
         },
-        nodePath: { type: "string", ops: ["signal", "until"], description: "signal, until: the node." },
+        nodePath: {
+          type: "string",
+          ops: ["signal", "until"],
+          description: "signal, until: the node. Needed for a signal and for a property; for says it defaults to /root, the whole screen."
+        },
         signal: { type: "string", ops: ["signal"], description: "signal: the signal name." },
         property: {
           type: "string",
@@ -16535,7 +16543,7 @@ var init_tool_definitions = __esm(() => {
         says: {
           type: "string",
           ops: ["until"],
-          description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
+          description: "until: wait for these words to appear anywhere under nodePath, or anywhere in the game when no nodePath is given, instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
         },
         includeHidden: {
           type: "boolean",
@@ -16557,7 +16565,7 @@ var init_tool_definitions = __esm(() => {
         },
         until: {
           summary: "wait for a property to read as a value, or for words to appear under a node, and answer with what it found",
-          requires: ["nodePath"]
+          requires: []
         }
       }
     },
@@ -31671,8 +31679,7 @@ function announcedAndGone(projectPath) {
     return [];
   }
   const since = Date.now() - GONE_WINDOW_MS;
-  const wanted = resolve3(projectPath);
-  return gone.filter((one) => one.noticedAt >= since && resolve3(one.project) === wanted);
+  return gone.filter((one) => one.noticedAt >= since && isSameDirectory(one.project, projectPath));
 }
 function strangersAmong(candidates, now, startTimes = startTimesOf) {
   const toJudge = candidates.filter((one) => {
@@ -31778,11 +31785,10 @@ function sweepErrorReport(path, pid, now = Date.now()) {
   } catch {}
 }
 async function announcedSince(projectPath, before, waiting = {}) {
-  const wanted = resolve3(projectPath);
   const directories = waiting.directories ?? runtimeDirectories();
   const until = Date.now() + Math.max(waiting.budgetMs ?? ANNOUNCE_BUDGET_MS, 0);
   for (;; ) {
-    const fresh = discoverRuntimes(directories).find((endpoint) => !before.has(endpoint.pid) && resolve3(endpoint.project.path) === wanted && (waiting.accept?.(endpoint) ?? true));
+    const fresh = discoverRuntimes(directories).find((endpoint) => !before.has(endpoint.pid) && isSameDirectory(endpoint.project.path, projectPath) && (waiting.accept?.(endpoint) ?? true));
     if (fresh !== undefined) {
       return fresh;
     }
@@ -31803,7 +31809,7 @@ function theOneProject(endpoints) {
   if (endpoints.some((endpoint) => endpoint.project.path === "")) {
     return;
   }
-  const paths = new Set(endpoints.map((endpoint) => resolve3(endpoint.project.path)));
+  const paths = new Set(endpoints.map((endpoint) => realPathOr(resolve3(endpoint.project.path))));
   const only = [...paths][0];
   return paths.size === 1 ? only : undefined;
 }
@@ -31832,7 +31838,7 @@ function chooseRuntime(endpoints, projectPath, unspoken = [], pid) {
   if (pid !== undefined) {
     const named = endpoints.find((endpoint) => endpoint.pid === pid);
     if (named !== undefined) {
-      if (projectPath !== undefined && resolve3(named.project.path) !== resolve3(projectPath)) {
+      if (projectPath !== undefined && !isSameDirectory(named.project.path, projectPath)) {
         return {
           problem: `The game with pid ${pid} is running ${named.project.path}, not ${resolve3(projectPath)}. Running: ${endpoints.map(describe2).join("; ")}.`
         };
@@ -31875,7 +31881,7 @@ function chooseRuntime(endpoints, projectPath, unspoken = [], pid) {
   }
   if (projectPath !== undefined) {
     const wanted = resolve3(projectPath);
-    const matching = endpoints.filter((endpoint) => resolve3(endpoint.project.path) === wanted);
+    const matching = endpoints.filter((endpoint) => isSameDirectory(endpoint.project.path, wanted));
     if (matching.length === 0) {
       return {
         problem: `No running game is from ${wanted}. Running: ${endpoints.map(describe2).join("; ")}.`
@@ -31986,6 +31992,7 @@ function runtimeRequest(endpoint, command, params, timeoutMs) {
 }
 var RUNTIME_PROTOCOL = 2, ANNOUNCEMENT_PATTERN, ERROR_REPORT_PATTERN, ERROR_REPORT_KEEP_MS, GONE_WINDOW_MS = 120000, GONE_KEPT = 32, gone, STARTED_AFTER_ANNOUNCING_MS = 2000, CONFIRMED_FOR_MS = 60000, JUDGED_AFTER_MS = 60000, verdicts, ENDED_WITHIN_MS = 3000, LOOK_EVERY_MS = 50, ANNOUNCE_BUDGET_MS = 5000, nextRequestId = 1;
 var init_runtime_client = __esm(() => {
+  init_paths();
   init_process_children();
   ANNOUNCEMENT_PATTERN = /^runtime-(\d+)\.json$/;
   ERROR_REPORT_PATTERN = /^runtime-(\d+)\.log$/;
@@ -38026,6 +38033,8 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 import {
   appendFileSync,
   closeSync as closeSync2,
+  constants,
+  copyFileSync,
   existsSync as existsSync15,
   fstatSync,
   mkdirSync as mkdirSync13,
@@ -38038,10 +38047,34 @@ import {
   statSync as statSync8
 } from "node:fs";
 import { tmpdir as tmpdir5 } from "node:os";
-import { basename as basename4, dirname as dirname15, isAbsolute as isAbsolute3, join as join22, normalize as normalize3, relative as relative3 } from "node:path";
+import { basename as basename4, dirname as dirname15, extname as extname2, isAbsolute as isAbsolute3, join as join22, normalize as normalize3, relative as relative3 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { promisify as promisify7 } from "node:util";
+function captureDestinationRefusal(outputPath, projects) {
+  if (/^(res|user):\/\//.test(outputPath)) {
+    return `outputPath ${outputPath} is a Godot path; a capture is saved outside the project, at an absolute path on this machine.`;
+  }
+  if (!isAbsolute3(outputPath)) {
+    return `outputPath ${outputPath} is not absolute; name the whole path, so where it is written does not depend on this server's directory.`;
+  }
+  if (extname2(outputPath).toLowerCase() !== ".png") {
+    return `outputPath ${outputPath} does not end in .png, which is what a capture is.`;
+  }
+  const directory = realPathOr(dirname15(outputPath));
+  if (!existsSync15(directory)) {
+    return `outputPath's directory ${dirname15(outputPath)} does not exist; a capture creates no directories.`;
+  }
+  const where = join22(directory, basename4(outputPath));
+  const inside = projects.find((project) => project !== "" && isWithinRoot(realPathOr(project), where));
+  if (inside !== undefined) {
+    return `outputPath ${outputPath} is inside the project at ${inside}; a capture is saved outside it, so it never becomes part of the game.`;
+  }
+  if (existsSync15(where)) {
+    return `outputPath ${outputPath} already exists; a capture is not written over a file. Name a new one.`;
+  }
+  return null;
+}
 function patienceForFrames(frames, atLeast) {
   return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
 }
@@ -41289,8 +41322,59 @@ class GodotServer {
     }
     return { heldAt: undefined, heldUnknown: true, heldNote: reply.message };
   }
+  async ownRunOnItsWay(projectPath, budgetMs) {
+    const run = this.currentRun();
+    const project = projectPath ?? run?.projectPath ?? null;
+    if (run === null || project === null || run.announcedPid !== undefined || run.projectPath !== null && !isSameDirectory(run.projectPath, project) || !existsSync15(join22(project, RUNTIME_AUTOLOAD2.path)) || !await this.runStillGoing(run)) {
+      return null;
+    }
+    const already = runtimesAnnounced().running;
+    const announcedSinceTheStart = (one) => {
+      if (run.announcedBefore !== undefined) {
+        return !run.announcedBefore.has(one.pid);
+      }
+      try {
+        return statSync8(one.file).mtimeMs >= run.startedAt;
+      } catch {
+        return false;
+      }
+    };
+    if (already.some((one) => announcedSinceTheStart(one) && this.isTheGameOf(run, one, project))) {
+      return null;
+    }
+    const which = run.throughEditor ? "the game the editor is playing for it" : `pid ${run.pid ?? "unknown"}`;
+    const comingUpUntil = run.startedAt + waitSizedTo(readBootNote(project)) + budgetMs;
+    const remaining = comingUpUntil - Date.now();
+    if (remaining <= 0) {
+      const seconds = Math.round((Date.now() - run.startedAt) / 1000);
+      return `The game this server started (${which}) has been running for ${seconds}s and has not announced its runtime, so there is nothing to talk to. A game that keeps the runtime off, as a project's own loader can for some scenes, never announces; editor_output says what it has printed.`;
+    }
+    const endpoint = await announcedSince(project, new Set(already.map((one) => one.pid)), {
+      budgetMs: Math.min(budgetMs, remaining),
+      accept: (one) => this.isTheGameOf(this.currentRun(), one, project),
+      giveUp: () => this.currentRun() !== run || this.dapClient?.isStopped() === true || !stillRunning(run)
+    });
+    if (endpoint !== null) {
+      const tiedMeanwhile = () => run.announcedPid !== undefined;
+      if (!tiedMeanwhile()) {
+        this.tie(run, endpoint);
+      }
+      return null;
+    }
+    if (this.currentRun() !== run || !await this.runStillGoing(run)) {
+      return null;
+    }
+    return `The game this server started (${which}) is still coming up and has not announced its runtime after a wait of ${Math.min(budgetMs, remaining)}ms, so there is nothing to talk to yet. It is still running: ask again in a moment rather than starting another.`;
+  }
   async handleRuntimeCommand(command, args, timeoutMs = this.runtimeTimeoutMs()) {
-    const { op: _op, projectPath, pid, ...params } = asParams(args);
+    const { op: _op, projectPath, pid, outputPath, ...params } = asParams(args);
+    const waited = typeof pid === "number" ? null : await this.ownRunOnItsWay(typeof projectPath === "string" ? projectPath : this.ownProject, timeoutMs);
+    if (waited !== null) {
+      return this.createErrorResponse(waited, [
+        "editor_status lists it under runtimes once it has announced",
+        "editor_output says what it has printed so far"
+      ]);
+    }
     const announced = runtimesAnnounced();
     const wanted = typeof projectPath === "string" ? projectPath : this.ownProject ?? undefined;
     const own = typeof pid === "number" ? undefined : this.ownGameAmong(announced.running, wanted) ?? await this.ownGameThroughTheTree(announced.running, wanted);
@@ -41310,6 +41394,16 @@ class GodotServer {
       ]);
     }
     const expectsScreenshot = command === "capture_screenshot" || command === "capture_viewport";
+    const saveTo = expectsScreenshot && typeof outputPath === "string" ? outputPath : null;
+    if (saveTo !== null) {
+      const refusal = captureDestinationRefusal(saveTo, [
+        choice.endpoint.project.path,
+        ...this.ownProject === null ? [] : [this.ownProject]
+      ]);
+      if (refusal !== null) {
+        return this.createErrorResponse(refusal);
+      }
+    }
     const screenshotDir = expectsScreenshot ? mkdtempSync3(join22(tmpdir5(), "gdharness-runtime-screenshot-")) : null;
     const screenshotPath = screenshotDir ? join22(screenshotDir, "capture.png") : null;
     try {
@@ -41329,11 +41423,18 @@ class GodotServer {
         return this.createErrorResponse(`Rejected screenshot file path outside the managed capture path: '${returnedPath}'`);
       }
       const dimensions = `${readNumber(payload, "width") ?? 0}x${readNumber(payload, "height") ?? 0} ${readString(payload, "format") ?? "unknown"}`;
+      if (saveTo !== null) {
+        try {
+          copyFileSync(screenshotPath, saveTo, constants.COPYFILE_EXCL);
+        } catch (error) {
+          return this.createErrorResponse(`The capture was taken and could not be saved at ${saveTo}: ${errorMessage(error)}`);
+        }
+      }
       return {
         content: [
           {
             type: "text",
-            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}`
+            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}${saveTo === null ? "" : `. Saved to ${saveTo}`}`
           },
           { type: "image", data: readFileSync20(screenshotPath).toString("base64"), mimeType: "image/png" }
         ]
@@ -41380,7 +41481,11 @@ class GodotServer {
       return await this.handleRuntimeCommand("wait_frames", { ...whichGame(args), frames }, waited);
     }
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 5000;
-    const nodePath = readNonEmptyString(args, "nodePath") ?? "";
+    const asked = readNonEmptyString(args, "nodePath");
+    if (asked === undefined && op === "until" && readNonEmptyString(args, "says") === undefined) {
+      return this.createErrorResponse("runtime_wait until needs nodePath to wait for a property: the property belongs to that node.", ["With says instead of property, nodePath can be left out and the whole game is searched"]);
+    }
+    const nodePath = asked ?? "/root";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
     return op === "signal" ? await this.handleRuntimeCommand("wait_signal", {
       ...whichGame(args),
@@ -43048,12 +43153,12 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | What a property on an object a node holds reads | the same two, with colons: \`_game:clock:speed\` |
 | Which control holds the focus, or anything only a method answers | the same path with a step written as a call, \`get_viewport():gui_get_focus_owner\`, which calls a method taking no arguments and walks into what it returned |
 | Press a button | \`runtime_input click\`, which says what was under the pointer |
-| Press the next thing after a click that changed screen | \`runtime_wait until\` with \`says\` and a word the new screen shows, then the click. A click sent straight after a screen change lands on a control the new screen is about to free, answers \`landed: true\`, and does nothing; a frame count is a number nobody can pick correctly across a cold start and a warm one, and waiting for the words answered in about 130ms where twenty frames had not been enough |
+| Press the next thing after a click that changed screen | \`runtime_wait until\` with \`says\` and a word the new screen shows (no \`nodePath\` needed: without one the whole game is searched), then the click. A click sent straight after a screen change lands on a control the new screen is about to free, answers \`landed: true\`, and does nothing; a frame count is a number nobody can pick correctly across a cold start and a warm one, and waiting for the words answered in about 130ms where twenty frames had not been enough |
 | Fill in a field | \`runtime_input click\` on it, then \`runtime_input text\` with \`replace\`; a submitted field has to be clicked again |
 | Click somebody standing in a 3D room | \`runtime_input click\` on the Node3D, which aims at what it draws |
 | Pick something out of a dropdown | \`runtime_input choose\` on it, by what the item says, rather than a click and keys: the menu opens as a window of its own that an injected key never reaches, so Enter closes it with nothing chosen |
-| Answer a dialog | \`runtime_input click\` on its button, or \`key\` Escape to dismiss it: an [AcceptDialog] reads that key itself and never asks the InputMap, so \`ui_cancel\` leaves it standing |
-| Press a bound key | \`runtime_input action\` or \`key\`, a whole press unless you hold it |
+| Answer a dialog | \`runtime_input click\` on its button, or \`runtime_input key\` with \`keycode\` \`Escape\` to dismiss it: an [AcceptDialog] reads that key itself and never asks the InputMap, so \`ui_cancel\` leaves it standing |
+| Press a bound key | \`runtime_input action\` with the action's name, or \`runtime_input key\` with \`keycode\`, a whole press unless you hold it |
 | Where a 3D node is on screen | \`runtime_inspect\` \`rect\`, rather than unprojecting by hand |
 | Wait for something in a running game | \`runtime_wait\`, never a sleep; \`until\` with \`says\` for a panel that rebuilds its own labels. The words have to be shown: a button that exists hidden through an animation does not satisfy it until it appears, unless \`includeHidden\` says otherwise |
 | What every label on a screen says | \`runtime_inspect tree\` with \`properties\` naming \`text\`, which reads it off every node that has one; \`includeProperties\` is every stored property of every node and ran to seventy-six thousand characters for one row |

package/build/index.js

@@ -10182,6 +10182,8 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 import {
   appendFileSync,
   closeSync as closeSync2,
+  constants,
+  copyFileSync,
   existsSync as existsSync10,
   fstatSync,
   mkdirSync as mkdirSync10,
@@ -10194,7 +10196,7 @@ import {
   statSync as statSync7
 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { basename as basename3, dirname as dirname10, isAbsolute as isAbsolute3, join as join16, normalize as normalize2, relative as relative3 } from "node:path";
+import { basename as basename3, dirname as dirname10, extname as extname2, isAbsolute as isAbsolute3, join as join16, normalize as normalize2, relative as relative3 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { promisify as promisify5 } from "node:util";
@@ -24770,7 +24772,7 @@ import { dirname as dirname2, join as join3 } from "node:path";
 import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3, statSync, unlinkSync } from "node:fs";
 import { createConnection } from "node:net";
 import { tmpdir as tmpdir2 } from "node:os";
-import { dirname, join as join2, resolve } from "node:path";
+import { dirname, join as join2, resolve as resolve2 } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 
 // src/launch.ts
@@ -24837,6 +24839,65 @@ function environmentFor(options, variables = process.env) {
 }
 var SAVES_NOT_MOVED_NOTE = "On macOS the engine reads user:// off HOME and ignores the variables that move it elsewhere, measured on Godot 4.7.2, so this run wrote its saves where the player keeps theirs. A suite that saves a game has written into the same folder as the copy being played, and one that tidies up after itself may have removed real saves.";
 
+// src/paths.ts
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+var RESOURCE_SCHEME = "res://";
+var OTHER_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]+:\/\//;
+function realPathOr(path) {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+function isSameDirectory(onePath, otherPath) {
+  return relative(realPathOr(resolve(onePath)), realPathOr(resolve(otherPath))) === "";
+}
+function isWithinRoot(rootPath, candidatePath) {
+  const step = relative(resolve(rootPath), resolve(candidatePath));
+  return step !== ".." && !step.startsWith(`..${sep}`) && !isAbsolute(step);
+}
+function resolveWithinProject(projectPath, candidatePath) {
+  const trimmed = candidatePath.trim();
+  if (trimmed === "") {
+    return { ok: false, reason: "Path is empty." };
+  }
+  if (trimmed.includes("\x00")) {
+    return { ok: false, reason: "Path contains a null byte." };
+  }
+  const withoutScheme = trimmed.startsWith(RESOURCE_SCHEME) ? trimmed.slice(RESOURCE_SCHEME.length) : trimmed;
+  const scheme = OTHER_SCHEME.exec(withoutScheme);
+  if (scheme) {
+    return {
+      ok: false,
+      reason: `Path '${trimmed}' uses the '${scheme[0]}' scheme, which names somewhere other than this project.`
+    };
+  }
+  if (withoutScheme.startsWith("/") || withoutScheme.startsWith("\\") || isAbsolute(withoutScheme)) {
+    return {
+      ok: false,
+      reason: `Path '${trimmed}' is absolute; give a path inside the project, such as 'scenes/main.tscn'.`
+    };
+  }
+  if (withoutScheme.includes(":")) {
+    return {
+      ok: false,
+      reason: `Path '${trimmed}' contains ':', which no file inside a project is named with.`
+    };
+  }
+  const root = resolve(projectPath);
+  const absolutePath = resolve(root, withoutScheme);
+  if (!isWithinRoot(root, absolutePath)) {
+    return { ok: false, reason: `Path '${trimmed}' resolves outside the project directory.` };
+  }
+  const relativePath = relative(root, absolutePath).split(sep).join("/");
+  if (relativePath === "") {
+    return { ok: false, reason: `Path '${trimmed}' is the project directory itself, not a file in it.` };
+  }
+  return { ok: true, absolutePath, relativePath };
+}
+
 // src/process-children.ts
 import { execFile, execFileSync, spawnSync } from "node:child_process";
 import { basename } from "node:path";
@@ -25110,7 +25171,7 @@ function runtimeDirectories(variables = process.env) {
   for (const base of fallbacks) {
     candidates.push(join2(base, process.platform === "win32" ? "Temp" : "", "gdharness"));
   }
-  return [...new Set(candidates.map((path) => resolve(path)))];
+  return [...new Set(candidates.map((path) => resolve2(path)))];
 }
 var ERROR_REPORT_PATTERN = /^runtime-(\d+)\.log$/;
 function errorReportOf(pid, directories = runtimeDirectories()) {
@@ -25205,8 +25266,7 @@ function announcedAndGone(projectPath) {
     return [];
   }
   const since = Date.now() - GONE_WINDOW_MS;
-  const wanted = resolve(projectPath);
-  return gone.filter((one) => one.noticedAt >= since && resolve(one.project) === wanted);
+  return gone.filter((one) => one.noticedAt >= since && isSameDirectory(one.project, projectPath));
 }
 var STARTED_AFTER_ANNOUNCING_MS = 2000;
 var CONFIRMED_FOR_MS = 60000;
@@ -25319,11 +25379,10 @@ function sweepErrorReport(path, pid, now = Date.now()) {
 var LOOK_EVERY_MS = 50;
 var ANNOUNCE_BUDGET_MS = 5000;
 async function announcedSince(projectPath, before, waiting = {}) {
-  const wanted = resolve(projectPath);
   const directories = waiting.directories ?? runtimeDirectories();
   const until = Date.now() + Math.max(waiting.budgetMs ?? ANNOUNCE_BUDGET_MS, 0);
   for (;; ) {
-    const fresh = discoverRuntimes(directories).find((endpoint) => !before.has(endpoint.pid) && resolve(endpoint.project.path) === wanted && (waiting.accept?.(endpoint) ?? true));
+    const fresh = discoverRuntimes(directories).find((endpoint) => !before.has(endpoint.pid) && isSameDirectory(endpoint.project.path, projectPath) && (waiting.accept?.(endpoint) ?? true));
     if (fresh !== undefined) {
       return fresh;
     }
@@ -25344,7 +25403,7 @@ function theOneProject(endpoints) {
   if (endpoints.some((endpoint) => endpoint.project.path === "")) {
     return;
   }
-  const paths = new Set(endpoints.map((endpoint) => resolve(endpoint.project.path)));
+  const paths = new Set(endpoints.map((endpoint) => realPathOr(resolve2(endpoint.project.path))));
   const only = [...paths][0];
   return paths.size === 1 ? only : undefined;
 }
@@ -25373,9 +25432,9 @@ function chooseRuntime(endpoints, projectPath, unspoken = [], pid) {
   if (pid !== undefined) {
     const named = endpoints.find((endpoint) => endpoint.pid === pid);
     if (named !== undefined) {
-      if (projectPath !== undefined && resolve(named.project.path) !== resolve(projectPath)) {
+      if (projectPath !== undefined && !isSameDirectory(named.project.path, projectPath)) {
         return {
-          problem: `The game with pid ${pid} is running ${named.project.path}, not ${resolve(projectPath)}. Running: ${endpoints.map(describe2).join("; ")}.`
+          problem: `The game with pid ${pid} is running ${named.project.path}, not ${resolve2(projectPath)}. Running: ${endpoints.map(describe2).join("; ")}.`
         };
       }
       return { endpoint: named };
@@ -25415,8 +25474,8 @@ function chooseRuntime(endpoints, projectPath, unspoken = [], pid) {
     };
   }
   if (projectPath !== undefined) {
-    const wanted = resolve(projectPath);
-    const matching = endpoints.filter((endpoint) => resolve(endpoint.project.path) === wanted);
+    const wanted = resolve2(projectPath);
+    const matching = endpoints.filter((endpoint) => isSameDirectory(endpoint.project.path, wanted));
     if (matching.length === 0) {
       return {
         problem: `No running game is from ${wanted}. Running: ${endpoints.map(describe2).join("; ")}.`
@@ -25560,67 +25619,6 @@ function waitSizedTo(lastBootMs, usual = ANNOUNCE_BUDGET_MS) {
 // src/breakpoint-note.ts
 import { mkdirSync as mkdirSync3, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname3, isAbsolute as isAbsolute2, join as join4, relative as relative2 } from "node:path";
-
-// src/paths.ts
-import { realpathSync } from "node:fs";
-import { isAbsolute, relative, resolve as resolve2, sep } from "node:path";
-var RESOURCE_SCHEME = "res://";
-var OTHER_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]+:\/\//;
-function realPathOr(path) {
-  try {
-    return realpathSync.native(path);
-  } catch {
-    return path;
-  }
-}
-function isSameDirectory(onePath, otherPath) {
-  return relative(realPathOr(resolve2(onePath)), realPathOr(resolve2(otherPath))) === "";
-}
-function isWithinRoot(rootPath, candidatePath) {
-  const step = relative(resolve2(rootPath), resolve2(candidatePath));
-  return step !== ".." && !step.startsWith(`..${sep}`) && !isAbsolute(step);
-}
-function resolveWithinProject(projectPath, candidatePath) {
-  const trimmed = candidatePath.trim();
-  if (trimmed === "") {
-    return { ok: false, reason: "Path is empty." };
-  }
-  if (trimmed.includes("\x00")) {
-    return { ok: false, reason: "Path contains a null byte." };
-  }
-  const withoutScheme = trimmed.startsWith(RESOURCE_SCHEME) ? trimmed.slice(RESOURCE_SCHEME.length) : trimmed;
-  const scheme = OTHER_SCHEME.exec(withoutScheme);
-  if (scheme) {
-    return {
-      ok: false,
-      reason: `Path '${trimmed}' uses the '${scheme[0]}' scheme, which names somewhere other than this project.`
-    };
-  }
-  if (withoutScheme.startsWith("/") || withoutScheme.startsWith("\\") || isAbsolute(withoutScheme)) {
-    return {
-      ok: false,
-      reason: `Path '${trimmed}' is absolute; give a path inside the project, such as 'scenes/main.tscn'.`
-    };
-  }
-  if (withoutScheme.includes(":")) {
-    return {
-      ok: false,
-      reason: `Path '${trimmed}' contains ':', which no file inside a project is named with.`
-    };
-  }
-  const root = resolve2(projectPath);
-  const absolutePath = resolve2(root, withoutScheme);
-  if (!isWithinRoot(root, absolutePath)) {
-    return { ok: false, reason: `Path '${trimmed}' resolves outside the project directory.` };
-  }
-  const relativePath = relative(root, absolutePath).split(sep).join("/");
-  if (relativePath === "") {
-    return { ok: false, reason: `Path '${trimmed}' is the project directory itself, not a file in it.` };
-  }
-  return { ok: true, absolutePath, relativePath };
-}
-
-// src/breakpoint-note.ts
 function breakpointNotePath(projectPath) {
   return join4(projectPath, ".godot", "gdharness-breakpoints.json");
 }
@@ -30476,7 +30474,11 @@ var TOOL_SPECS = [
         description: "viewport: the Viewport node. Default the root viewport."
       },
       width: { type: "number", description: "Scale the image to this width." },
-      height: { type: "number", description: "Scale the image to this height." }
+      height: { type: "number", description: "Scale the image to this height." },
+      outputPath: {
+        type: "string",
+        description: "Also save the picture as a PNG at this absolute path, for somebody to open later; the answer says where. Refused unless it ends in .png, its directory exists, it is outside the project, and no file is there already."
+      }
     },
     requires: [],
     operations: {
@@ -30499,7 +30501,7 @@ var TOOL_SPECS = [
       action: {
         type: "string",
         ops: ["action"],
-        description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with key Escape, or click its button."
+        description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with the key op and keycode Escape, or click its button."
       },
       pressed: {
         type: "boolean",
@@ -30602,7 +30604,11 @@ var TOOL_SPECS = [
         ops: ["frames"],
         description: "frames: how many to let pass, 1 to 600. More than that is refused."
       },
-      nodePath: { type: "string", ops: ["signal", "until"], description: "signal, until: the node." },
+      nodePath: {
+        type: "string",
+        ops: ["signal", "until"],
+        description: "signal, until: the node. Needed for a signal and for a property; for says it defaults to /root, the whole screen."
+      },
       signal: { type: "string", ops: ["signal"], description: "signal: the signal name." },
       property: {
         type: "string",
@@ -30613,7 +30619,7 @@ var TOOL_SPECS = [
       says: {
         type: "string",
         ops: ["until"],
-        description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
+        description: "until: wait for these words to appear anywhere under nodePath, or anywhere in the game when no nodePath is given, instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
       },
       includeHidden: {
         type: "boolean",
@@ -30635,7 +30641,7 @@ var TOOL_SPECS = [
       },
       until: {
         summary: "wait for a property to read as a value, or for words to appear under a node, and answer with what it found",
-        requires: ["nodePath"]
+        requires: []
       }
     }
   },
@@ -30737,6 +30743,30 @@ var __dirname2 = dirname10(fileURLToPath3(import.meta.url));
 var EDITOR_RESTART_TIMEOUT_MS = 90000;
 var HOLD_PING_MS = 2000;
 var SLOWEST_FRAME_RATE = 20;
+function captureDestinationRefusal(outputPath, projects) {
+  if (/^(res|user):\/\//.test(outputPath)) {
+    return `outputPath ${outputPath} is a Godot path; a capture is saved outside the project, at an absolute path on this machine.`;
+  }
+  if (!isAbsolute3(outputPath)) {
+    return `outputPath ${outputPath} is not absolute; name the whole path, so where it is written does not depend on this server's directory.`;
+  }
+  if (extname2(outputPath).toLowerCase() !== ".png") {
+    return `outputPath ${outputPath} does not end in .png, which is what a capture is.`;
+  }
+  const directory = realPathOr(dirname10(outputPath));
+  if (!existsSync10(directory)) {
+    return `outputPath's directory ${dirname10(outputPath)} does not exist; a capture creates no directories.`;
+  }
+  const where = join16(directory, basename3(outputPath));
+  const inside = projects.find((project) => project !== "" && isWithinRoot(realPathOr(project), where));
+  if (inside !== undefined) {
+    return `outputPath ${outputPath} is inside the project at ${inside}; a capture is saved outside it, so it never becomes part of the game.`;
+  }
+  if (existsSync10(where)) {
+    return `outputPath ${outputPath} already exists; a capture is not written over a file. Name a new one.`;
+  }
+  return null;
+}
 function patienceForFrames(frames, atLeast) {
   return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
 }
@@ -34030,8 +34060,59 @@ class GodotServer {
     }
     return { heldAt: undefined, heldUnknown: true, heldNote: reply.message };
   }
+  async ownRunOnItsWay(projectPath, budgetMs) {
+    const run = this.currentRun();
+    const project = projectPath ?? run?.projectPath ?? null;
+    if (run === null || project === null || run.announcedPid !== undefined || run.projectPath !== null && !isSameDirectory(run.projectPath, project) || !existsSync10(join16(project, RUNTIME_AUTOLOAD.path)) || !await this.runStillGoing(run)) {
+      return null;
+    }
+    const already = runtimesAnnounced().running;
+    const announcedSinceTheStart = (one) => {
+      if (run.announcedBefore !== undefined) {
+        return !run.announcedBefore.has(one.pid);
+      }
+      try {
+        return statSync7(one.file).mtimeMs >= run.startedAt;
+      } catch {
+        return false;
+      }
+    };
+    if (already.some((one) => announcedSinceTheStart(one) && this.isTheGameOf(run, one, project))) {
+      return null;
+    }
+    const which = run.throughEditor ? "the game the editor is playing for it" : `pid ${run.pid ?? "unknown"}`;
+    const comingUpUntil = run.startedAt + waitSizedTo(readBootNote(project)) + budgetMs;
+    const remaining = comingUpUntil - Date.now();
+    if (remaining <= 0) {
+      const seconds = Math.round((Date.now() - run.startedAt) / 1000);
+      return `The game this server started (${which}) has been running for ${seconds}s and has not announced its runtime, so there is nothing to talk to. A game that keeps the runtime off, as a project's own loader can for some scenes, never announces; editor_output says what it has printed.`;
+    }
+    const endpoint = await announcedSince(project, new Set(already.map((one) => one.pid)), {
+      budgetMs: Math.min(budgetMs, remaining),
+      accept: (one) => this.isTheGameOf(this.currentRun(), one, project),
+      giveUp: () => this.currentRun() !== run || this.dapClient?.isStopped() === true || !stillRunning(run)
+    });
+    if (endpoint !== null) {
+      const tiedMeanwhile = () => run.announcedPid !== undefined;
+      if (!tiedMeanwhile()) {
+        this.tie(run, endpoint);
+      }
+      return null;
+    }
+    if (this.currentRun() !== run || !await this.runStillGoing(run)) {
+      return null;
+    }
+    return `The game this server started (${which}) is still coming up and has not announced its runtime after a wait of ${Math.min(budgetMs, remaining)}ms, so there is nothing to talk to yet. It is still running: ask again in a moment rather than starting another.`;
+  }
   async handleRuntimeCommand(command, args, timeoutMs = this.runtimeTimeoutMs()) {
-    const { op: _op, projectPath, pid, ...params } = asParams(args);
+    const { op: _op, projectPath, pid, outputPath, ...params } = asParams(args);
+    const waited = typeof pid === "number" ? null : await this.ownRunOnItsWay(typeof projectPath === "string" ? projectPath : this.ownProject, timeoutMs);
+    if (waited !== null) {
+      return this.createErrorResponse(waited, [
+        "editor_status lists it under runtimes once it has announced",
+        "editor_output says what it has printed so far"
+      ]);
+    }
     const announced = runtimesAnnounced();
     const wanted = typeof projectPath === "string" ? projectPath : this.ownProject ?? undefined;
     const own = typeof pid === "number" ? undefined : this.ownGameAmong(announced.running, wanted) ?? await this.ownGameThroughTheTree(announced.running, wanted);
@@ -34051,6 +34132,16 @@ class GodotServer {
       ]);
     }
     const expectsScreenshot = command === "capture_screenshot" || command === "capture_viewport";
+    const saveTo = expectsScreenshot && typeof outputPath === "string" ? outputPath : null;
+    if (saveTo !== null) {
+      const refusal = captureDestinationRefusal(saveTo, [
+        choice.endpoint.project.path,
+        ...this.ownProject === null ? [] : [this.ownProject]
+      ]);
+      if (refusal !== null) {
+        return this.createErrorResponse(refusal);
+      }
+    }
     const screenshotDir = expectsScreenshot ? mkdtempSync2(join16(tmpdir4(), "gdharness-runtime-screenshot-")) : null;
     const screenshotPath = screenshotDir ? join16(screenshotDir, "capture.png") : null;
     try {
@@ -34070,11 +34161,18 @@ class GodotServer {
         return this.createErrorResponse(`Rejected screenshot file path outside the managed capture path: '${returnedPath}'`);
       }
       const dimensions = `${readNumber(payload, "width") ?? 0}x${readNumber(payload, "height") ?? 0} ${readString(payload, "format") ?? "unknown"}`;
+      if (saveTo !== null) {
+        try {
+          copyFileSync(screenshotPath, saveTo, constants.COPYFILE_EXCL);
+        } catch (error) {
+          return this.createErrorResponse(`The capture was taken and could not be saved at ${saveTo}: ${errorMessage(error)}`);
+        }
+      }
       return {
         content: [
           {
             type: "text",
-            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}`
+            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}${saveTo === null ? "" : `. Saved to ${saveTo}`}`
           },
           { type: "image", data: readFileSync16(screenshotPath).toString("base64"), mimeType: "image/png" }
         ]
@@ -34121,7 +34219,11 @@ class GodotServer {
       return await this.handleRuntimeCommand("wait_frames", { ...whichGame(args), frames }, waited);
     }
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 5000;
-    const nodePath = readNonEmptyString(args, "nodePath") ?? "";
+    const asked = readNonEmptyString(args, "nodePath");
+    if (asked === undefined && op === "until" && readNonEmptyString(args, "says") === undefined) {
+      return this.createErrorResponse("runtime_wait until needs nodePath to wait for a property: the property belongs to that node.", ["With says instead of property, nodePath can be left out and the whole game is searched"]);
+    }
+    const nodePath = asked ?? "/root";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
     return op === "signal" ? await this.handleRuntimeCommand("wait_signal", {
       ...whichGame(args),

package/package.json

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