gdharness 1.0.18 → 1.0.20

package/build/cli.js

@@ -16409,7 +16409,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "editor_status",
-      description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it.",
+      description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it.",
       parameters: {},
       requires: []
     },
@@ -16569,7 +16569,7 @@ var init_tool_definitions = __esm(() => {
         value: {
           ops: ["set"],
           blank: true,
-          description: `set: the value, fitted to the property's type. "" writes an empty string.`
+          description: `set: the value, fitted to the property's type. "" writes an empty string. A property typed as or holding an object takes a path naming one the game holds, the way call's args do, and holds that instance.`
         },
         method: {
           type: "string",
@@ -16579,7 +16579,7 @@ var init_tool_definitions = __esm(() => {
         args: {
           type: "array",
           ops: ["call"],
-          description: "call: the arguments, fitted to the method's parameter types."
+          description: `call: the arguments, fitted to the method's parameter types. A parameter typed as an object takes a path naming one the game holds and is handed that instance: a colon path read from nodePath, "_game:run:wares:3", or one starting at a node, "/root/Main/Hud" or "/root/Main:_game:run". A path that reaches no object, or an object of another class than the parameter declares, is refused.`
         }
       },
       requires: ["nodePath"],
@@ -38110,6 +38110,9 @@ function stillRunning(run) {
   if (run?.exitCode !== null || run.endedUnwatched === true) {
     return false;
   }
+  if (typeof run.endedHere === "string") {
+    return false;
+  }
   if (!run.throughEditor && run.process === null && run.pid !== null) {
     return alive(run.pid);
   }
@@ -38122,6 +38125,9 @@ function runIsUp(run, editorSays, now = Date.now()) {
   if (run?.throughEditor !== true) {
     return stillRunning(run);
   }
+  if (typeof run.endedHere === "string") {
+    return false;
+  }
   if (run.announcedPid !== undefined && !alive(run.announcedPid)) {
     return false;
   }
@@ -38130,6 +38136,22 @@ function runIsUp(run, editorSays, now = Date.now()) {
   }
   return editorSays ?? stillRunning(run);
 }
+function noCodeWillCome(run) {
+  return run.exitCode === null && run.process === null;
+}
+function endedWithoutACode(run) {
+  if (!run.throughEditor) {
+    return run.endedHere ? "This run was started by another server, so nothing here held it and its exit code was never collected. Everything it printed is below, read back from its transcript." : "This run was started by another server, the one this server replaced or one running beside it, and it ended with nothing here waiting on it, so its exit code was never collected. Everything it printed is below, read back from its transcript.";
+  }
+  const kept = "A game the editor plays is the editor's own child, so its exit code stays with the editor and none was collected here.";
+  if (run.endedHere) {
+    return `${kept} What it printed is below.`;
+  }
+  if (!run.announced && run.couldAnnounce) {
+    return `The editor stopped playing this run before its game announced a runtime, so the game ended while it was starting or was closed in the editor. ${kept} What it printed is below, and editor_output with op "editor" has what the editor said about it.`;
+  }
+  return `The editor stopped playing this run. ${kept} What it printed is below.`;
+}
 function endedPreviousRun(ended) {
   if (ended === null) {
     return;
@@ -39871,6 +39893,7 @@ class GodotServer {
         pid: endpoint.pid,
         port: endpoint.port,
         project: endpoint.project,
+        ...this.ownProject === null ? {} : { ofThisProject: isSameDirectory(endpoint.project.path, this.ownProject) },
         editorPid: endpoint.editorPid,
         reachable: reply.ok,
         problem: reply.ok ? null : reply.message
@@ -39902,7 +39925,7 @@ class GodotServer {
         processActive: active,
         playingInEditor: playing,
         ...hold,
-        runtimeConnected: games.some((game) => game.reachable),
+        runtimeConnected: games.some((game) => game.reachable && game.ofThisProject !== false),
         runtimes: games,
         unreadable: announced.unspoken.map((game) => ({
           pid: game.pid,
@@ -40126,7 +40149,7 @@ class GodotServer {
     if (before !== null && await this.runStillGoing(before)) {
       this.logDebug("Ending the running game before starting another");
       ended = { pid: before.pid ?? this.announcedPidOf(before) ?? null };
-      await this.endActiveGame("editor_run start, which ends the run that was going before it starts another");
+      await this.endActiveGame("editor_run start, which ends the run that was going before it starts another", true);
     }
     const alreadyPlaying = new Set(discoverRuntimes().map((endpoint) => endpoint.pid));
     const wereHereFirst = this.everyRuntimeOfOurs();
@@ -40367,12 +40390,11 @@ class GodotServer {
     game.brokeOn = halt.text;
     game.log.record("error", halt.text);
   }
-  async endActiveGame(reason) {
+  async endActiveGame(reason, going) {
     const running = this.activeProcess;
-    this.activeProcess = null;
     const recorded = running?.process === null ? readRunRecord() : null;
     clearRunRecord((record) => this.couldBeOurs(record.projectPath));
-    if (!running) {
+    if (!running || !going) {
       return;
     }
     running.endedHere = reason;
@@ -40536,7 +40558,8 @@ class GodotServer {
       return;
     }
     const going = this.activeProcess;
-    if (going !== null) {
+    const givesWay = going !== null && !stillRunning(going) && typeof going.endedHere === "string";
+    if (going !== null && !givesWay) {
       if (going.throughEditor && going.consoleLost === true && (await this.editorPlayingState())?.playing) {
         try {
           await this.dap().connect();
@@ -40922,7 +40945,7 @@ class GodotServer {
     const going = await this.runStillGoing(run);
     if (run.endedUnwatched !== true && !going) {
       run.log.finish();
-      run.endedUnwatched = run.exitCode === null;
+      run.endedUnwatched = noCodeWillCome(run);
     }
     const severity = readString(args, "severity");
     const selected = run.log.select({
@@ -40943,8 +40966,18 @@ class GodotServer {
     if (waitedMs !== undefined) {
       notes.push(`The wait of ${waitedMs}ms ran out and the run is still going, so this is what it had printed by then rather than everything it will print. editor_run wait again to keep waiting.`);
     }
+    if (typeof run.endedHere === "string") {
+      notes.push(`This run was ended here, by ${run.endedHere}.`);
+    } else if (!stillRunning(run) && !run.throughEditor && run.exitCode !== null) {
+      notes.push(run.exitCode === 0 ? "This run quit on its own, cleanly: exit code 0." : "Nothing here ended this run: it stopped on its own or something outside this server stopped it.");
+    }
     if (run.endedUnwatched === true) {
-      notes.push("This run outlived the server that started it and is over now, so its exit code was never collected. Everything it printed is below, read back from its transcript.");
+      notes.push(endedWithoutACode({
+        throughEditor: run.throughEditor,
+        announced: announced !== undefined || run.announcedPid !== undefined,
+        couldAnnounce: run.projectPath !== null && existsSync15(join23(run.projectPath, RUNTIME_AUTOLOAD2.path)),
+        endedHere: typeof run.endedHere === "string"
+      }));
     }
     if (run.pickedUpPlaying === true) {
       notes.push(run.transcript === null ? "The editor was already playing this when this server reached it, and the server that started it left no transcript, so this is not the run from its start: what it printed before that is only in the editor. It is the run the editor is holding now, which is the one the debug_* tools answer for." : "The editor was already playing this when this server reached it, and what it printed before that has been read back from its transcript. It is the run the editor is holding now, which is the one the debug_* tools answer for.");
@@ -40953,11 +40986,6 @@ class GodotServer {
       const back = this.dapClient?.isConnected() === true;
       notes.push(`The debug adapter this run's console arrives over went away while the run was going, so what is below has a hole in it and the counts are of what was heard rather than of what was printed. ${back ? "It is connected again, and the line marking where is in the log." : "It is still gone, so nothing further will arrive here."} The project's own user://logs/godot.log has the rest, and "no entries" here means "not heard" rather than a quiet run.`);
     }
-    if (typeof run.endedHere === "string") {
-      notes.push(`This run was ended here, by ${run.endedHere}.`);
-    } else if (!stillRunning(run) && !run.throughEditor && run.exitCode !== null) {
-      notes.push(run.exitCode === 0 ? "This run quit on its own, cleanly: exit code 0." : "Nothing here ended this run: it stopped on its own or something outside this server stopped it.");
-    }
     if (run.transcript !== null && selected.omitted > 0) {
       notes.push(`Everything this run has printed is in ${run.transcript}, uncapped and still being written. Read it for output, not for whether the run is alive: a transcript that stops growing is a run between prints. running above is asked of the operating system while there is a process to ask about, and for an editor-played run that announced no runtime it is the editor's answer instead, which can lag after the game has gone.`);
     }
@@ -40996,7 +41024,7 @@ class GodotServer {
     const endedPid = stopped.pid ?? announcedPid;
     const children = readBoolean(args, "andChildren") === true && wasRunning ? await this.whatTheRunStarted(stopped) : null;
     this.logDebug("Stopping the running game");
-    await this.endActiveGame("editor_run stop");
+    await this.endActiveGame("editor_run stop", wasRunning);
     const ended = children === null ? null : endChildrenAmong(children);
     if (wasRunning) {
       for (const pid of new Set([endedPid, announcedPid])) {
@@ -41015,12 +41043,12 @@ class GodotServer {
         childrenLeft: ended.left.length === 0 ? undefined : ended.left,
         childrenUnknown: ended.unknown === false ? undefined : true
       },
-      exitedBeforeStop: stopped.exitCode !== null || !wasRunning,
+      exitedBeforeStop: !wasRunning,
       exitCode: stopped.exitCode,
       errors: stopped.log.count("error"),
       warnings: stopped.log.count("warning"),
       clean: stopped.log.count("error") === 0,
-      note: !wasRunning ? "This run was over before the stop, so nothing was ended here: editor_output has what it printed and how it ended. Anything that game started for itself, with OS.create_process or otherwise, is a separate process and may still be running." : `${stopped.throughEditor ? "The editor was asked to stop the scene it is playing." : "The process named under endedPid was ended."} ${aboutTheChildren(ended, stopped.throughEditor)}`,
+      note: !wasRunning ? "This run was over before the stop, so nothing was ended here: editor_output has what it printed and how it ended. Anything that game started for itself, with OS.create_process or otherwise, is a separate process and may still be running." : `${stopped.throughEditor ? endedPid === null ? "The editor was asked to stop the scene it is playing. Its game had not announced a runtime, so no process was named under endedPid, and its exit code stays with the editor." : "The editor was asked to stop the scene it is playing." : "The process named under endedPid was ended."} ${aboutTheChildren(ended, stopped.throughEditor)}`,
       entries: forAnswer(stopped.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries)
     });
   }

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

@@ -0,0 +1,251 @@
+extends RefCounted
+
+## Colon paths through what a node holds: "/root/Main" with "_game:run:day" reaches the day off the
+## run off the game the node keeps. Every op that reads, writes, calls or waits on a game's state
+## walks the same way, so the walk and what it says when a step is not there live in one place.
+
+const Values = preload("runtime_values.gd")
+
+
+## What [param reaching] names something on, which is the node itself until the name has a colon
+## in it, and the last name along that path.
+##
+## A game's state does not sit on nodes, it hangs off them: the speed of the clock is a property of
+## a [RefCounted] held by a [RefCounted] held by the root, and that is what an agent asks about.
+## What a game does hangs off them the same way, so the last name is a property to read, a property
+## to write or a method to call, and the walk to it is one walk.
+##
+## Colons, because that is the separator [method Object.get_indexed] already takes. Walked a step
+## at a time rather than handed to that method, which answers null for a path that goes wrong
+## halfway along and for one that ends on null.
+##
+## A step written as a call, "get_viewport()", calls a method of that name that takes no arguments
+## and walks into what it returned. Some of what hangs off a node is only reachable by asking:
+## which control holds the focus is a question for the viewport a control is in, and the viewport
+## is a method's answer rather than a property. Spelled with the brackets so a reader sees a call
+## where one happens, and so a method can never shadow a property of the same name.
+##
+## Answers with a `message` instead when a step along the way is not there or holds something that
+## is not an object, naming the step rather than the whole path: "/root/Main:_game has no property
+## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle.
+static func walk_to(node: Node, node_path: String, reaching: String) -> Dictionary:
+	var parts: PackedStringArray = reaching.split(":")
+	var holder: Variant = node
+	var called: String = node_path
+	for step: int in parts.size() - 1:
+		var named: String = parts[step]
+		if not can_read(holder, named):
+			return {"type": "error", "message": nothing_there(holder, named, called)}
+		holder = read_under(holder, named)
+		called = "%s:%s" % [called, named]
+		if not _can_hold(holder):
+			var wanted: String = parts[step + 1]
+			return {"type": "error", "message": "%s holds no object to read %s off" % [called, wanted]}
+	return {"holder": holder, "name": parts[parts.size() - 1], "called": called}
+
+
+## The object [param given] names for a method's argument, as `{"object": ...}`, or as
+## `{"message": ...}` saying why it names none.
+##
+## A colon path read from [param node], the node the call was made on, the way the method's own
+## path is: "_ladder:shop:_wares:-15". One beginning with a slash starts at the node it names
+## instead, "/root/Main/Hud" or "/root/Main:_game:run". The record runtime_inspect answers an object
+## with is not accepted, because its id is a 64-bit number and does not survive being sent as JSON:
+## a rounded id names another object or none, and the path names the one meant.
+static func object_at(root: Node, node: Node, node_path: String, given: Variant) -> Dictionary:
+	if given is Dictionary:
+		return {
+			"message":
+			(
+				"an object is named by its path, not by the record runtime_inspect answered with:"
+				+ " its id does not survive the trip as a number"
+			)
+		}
+	var path: String = given
+	var start: Node = node
+	var start_path: String = node_path
+	var reaching: String = path
+	if path.begins_with("/"):
+		var colon: int = path.find(":")
+		start_path = path if colon == -1 else path.substr(0, colon)
+		var standing: Dictionary = Values.node_at(root, start_path)
+		if standing.has("message"):
+			return {"message": str(standing["message"])}
+		start = standing["node"]
+		if colon == -1:
+			return {"object": start}
+		reaching = path.substr(colon + 1)
+	if reaching.is_empty():
+		return {"message": "%s names nothing past the node" % path}
+	var reached: Dictionary = walk_to(start, start_path, reaching)
+	if reached.has("message"):
+		return {"message": str(reached["message"])}
+	var holder: Variant = reached["holder"]
+	var name: String = reached["name"]
+	if not can_read(holder, name):
+		return {"message": nothing_there(holder, name, str(reached["called"]))}
+	var value: Variant = read_under(holder, name)
+	if not value is Object or not is_instance_valid(value):
+		return {
+			"message": "%s:%s holds %s, not an object" % [reached["called"], name, type_string(typeof(value))]
+		}
+	return {"object": value}
+
+
+## Whether a step can be taken into [param value] at all: an object, a list or a map can be walked
+## into, and a number or a string is where a path ends whether the caller meant it to or not.
+static func _can_hold(value: Variant) -> bool:
+	return value is Object or value is Array or value is Dictionary
+
+
+## What is wrong with reading [param named] off [param holder], or "" when nothing is.
+##
+## Public because a wait asks the same question before it starts waiting, and used to answer it by
+## waiting: a property nobody has spends the whole timeout and comes back "not met", which reads
+## exactly like a game that never reached the state. The read refuses a mistyped name in one call
+## and says so, and the two tools disagreeing about one typo is worth more than the duplication.
+static func nothing_under(holder: Variant, named: String, called: String) -> String:
+	return "" if can_read(holder, named) else nothing_there(holder, named, called)
+
+
+## Whether [param named] is something [param holder] has.
+##
+## Three kinds of holder, because the state a game keeps is not all properties of objects: a roster
+## is a list and an in-tray is a map, and a path that could not step into either stopped at the
+## first one. An index reads the way a property does, and a negative one counts from the end the
+## way GDScript's own does, so reading the last of something does not mean asking how many first.
+static func can_read(holder: Variant, named: String) -> bool:
+	if holder is Array:
+		var items: Array = holder
+		return _index_in(named, items.size()) != -1
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		return map.has(named) or map.has(StringName(named))
+	if holder is Object:
+		var object: Object = holder
+		var method: String = method_of(named)
+		if not method.is_empty():
+			return _arguments_required(object, method) == 0
+		return _has_property(object, named)
+	return false
+
+
+## The method a step written as a call names, "get_viewport()" being get_viewport, or "" for a
+## step that is a name.
+static func method_of(named: String) -> String:
+	return named.trim_suffix("()") if named.ends_with("()") else ""
+
+
+## How many arguments [param method] on [param object] has to be given, or -1 when there is no such
+## method. Read off the method list rather than [method Object.has_method], because a path can only
+## call a method with nothing, and a method with a required argument called with nothing raises
+## inside the game rather than answering.
+static func _arguments_required(object: Object, method: String) -> int:
+	for entry: Dictionary in object.get_method_list():
+		if str(entry.get("name", "")) != method:
+			continue
+		var params: Array = entry.get("args", [])
+		var defaults: Array = entry.get("default_args", [])
+		return params.size() - defaults.size()
+	return -1
+
+
+## Put [param value] where [param named] points. Only ever called once [method can_read] agrees,
+## and lists and maps are reference types, so writing into one reaches the game's own copy.
+static func write(holder: Variant, named: String, value: Variant) -> void:
+	if holder is Array:
+		var items: Array = holder
+		items[_index_in(named, items.size())] = value
+		return
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		# Written back under the key it was found under, since a map keyed by StringName and one
+		# keyed by String both read the same way and a write to the wrong one adds a second entry.
+		if map.has(named):
+			map[named] = value
+		else:
+			map[StringName(named)] = value
+		return
+	var object: Object = holder
+	object.set(named, value)
+
+
+## What [param holder] holds under [param named], or answers to it when [param named] is a call.
+## Only ever called once [method can_read] agrees.
+static func read_under(holder: Variant, named: String) -> Variant:
+	if holder is Array:
+		var items: Array = holder
+		return items[_index_in(named, items.size())]
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		if map.has(named):
+			return map[named]
+		return map[StringName(named)]
+	var object: Object = holder
+	var method: String = method_of(named)
+	if not method.is_empty():
+		return object.call(method)
+	return object.get(named)
+
+
+## Where [param named] lands in a list of [param size], or -1 for a step that is not in it.
+##
+## -1 for "nowhere" is safe because every answer this gives is an index into a list that long, so a
+## real one is never negative by the time it is returned.
+static func _index_in(named: String, size: int) -> int:
+	if not named.is_valid_int():
+		return -1
+	var index: int = int(named)
+	if index < 0:
+		index += size
+	return index if index >= 0 and index < size else -1
+
+
+## Why a step could not be taken, said in the terms of what was actually there.
+##
+## "has no property 0" about a list is a true sentence that sends somebody looking for a property,
+## so a list says how long it is and a map says what it is keyed by. The step is named rather than
+## the whole path, because the step is the typo.
+static func nothing_there(holder: Variant, named: String, called_as: String) -> String:
+	if holder is Array:
+		var items: Array = holder
+		return "%s is a list of %d, so there is no %s in it" % [called_as, items.size(), named]
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		var keys: Array = map.keys()
+		# Eight of them, because a map keyed by something unexpected is told by the first few and a
+		# map of two hundred would bury the sentence saying which key was missing.
+		var some: Array[String] = []
+		for key: Variant in keys.slice(0, 8):
+			some.append(str(key))
+		var rest: String = ""
+		if keys.size() > 8:
+			rest = " and %d more" % [keys.size() - 8]
+		return "%s has no key %s; it is keyed by %s%s" % [called_as, named, ", ".join(some), rest]
+	var object: Object = holder
+	var method: String = method_of(named)
+	if not method.is_empty():
+		var required: int = _arguments_required(object, method)
+		if required == -1:
+			return "%s has no method %s" % [called_as, method]
+		return (
+			"%s.%s takes %d argument%s, and a path can only call a method that takes none"
+			% [called_as, method, required, "" if required == 1 else "s"]
+		)
+	# A method spelled as a property is the likeliest thing behind a name the object has no property
+	# for, and the caller is one pair of brackets away from what they meant.
+	if object.has_method(named):
+		return (
+			"%s has no property %s; it has a method of that name, which a path calls as %s()"
+			% [called_as, named, named]
+		)
+	return "%s has no property %s" % [called_as, named]
+
+
+## Whether [param holder] declares [param named]. Asked of the list rather than read, because a
+## property read back as null answers it wrongly.
+static func _has_property(holder: Object, named: String) -> bool:
+	for entry: Dictionary in holder.get_property_list():
+		if str(entry["name"]) == named:
+			return true
+	return false

package/build/godot/addons/gdharness_runtime/runtime_paths.gd.uid

@@ -0,0 +1 @@
+uid://cna71d704esno

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

@@ -3,6 +3,7 @@ extends RefCounted
 ## What the server asks about the running tree: its shape, one node, the nodes matching a
 ## question, where one is on screen, a property set, a method called, the metrics.
 
+const Paths = preload("runtime_paths.gd")
 const Read = preload("reading.gd")
 const Values = preload("runtime_values.gd")
 
@@ -182,19 +183,19 @@ func _found(node: Node, wanted_property: String) -> Dictionary:
 	if wanted_property.is_empty():
 		return entry
 	entry["property"] = wanted_property
-	# Through a path as well, for the reason [method walk_to] gives. A step that is not there on
+	# Through a path as well, for the reason [method Paths.walk_to] gives. A step that is not there on
 	# this node reads as not having the property rather than as a refusal, which is the rule this
 	# whole function is written to: a find matches nodes of several classes on purpose.
-	var reached: Dictionary = walk_to(node, str(entry["path"]), wanted_property)
+	var reached: Dictionary = Paths.walk_to(node, str(entry["path"]), wanted_property)
 	if reached.has("message"):
 		entry["has_property"] = false
 		return entry
 	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
-	var has: bool = _can_read(holder, named)
+	var has: bool = Paths.can_read(holder, named)
 	entry["has_property"] = has
 	if has:
-		entry["value"] = _values.serialize(read_under(holder, named))
+		entry["value"] = _values.serialize(Paths.read_under(holder, named))
 	return entry
 
 
@@ -548,7 +549,7 @@ func get_property(params: Dictionary) -> Dictionary:
 		return standing
 	var node: Node = standing["node"]
 
-	var reached: Dictionary = walk_to(node, node_path, property)
+	var reached: Dictionary = Paths.walk_to(node, node_path, property)
 	if reached.has("message"):
 		return reached
 
@@ -556,213 +557,17 @@ func get_property(params: Dictionary) -> Dictionary:
 	var named: String = reached["name"]
 	# Asked of the holder rather than read and compared to null, because a property the holder does
 	# not have and a property that is null both read as null.
-	if not _can_read(holder, named):
-		return {"type": "error", "message": _nothing_there(holder, named, str(reached["called"]))}
+	if not Paths.can_read(holder, named):
+		return {"type": "error", "message": Paths.nothing_there(holder, named, str(reached["called"]))}
 
 	return {
 		"type": "property",
 		"path": node_path,
 		"property": property,
-		"value": _values.serialize(read_under(holder, named)),
+		"value": _values.serialize(Paths.read_under(holder, named)),
 	}
 
 
-## What [param reaching] names something on, which is the node itself until the name has a colon
-## in it, and the last name along that path.
-##
-## A game's state does not sit on nodes, it hangs off them: the speed of the clock is a property of
-## a [RefCounted] held by a [RefCounted] held by the root, and that is what an agent asks about.
-## What a game does hangs off them the same way, so the last name is a property to read, a property
-## to write or a method to call, and the walk to it is one walk.
-##
-## Colons, because that is the separator [method Object.get_indexed] already takes. Walked a step
-## at a time rather than handed to that method, which answers null for a path that goes wrong
-## halfway along and for one that ends on null.
-##
-## A step written as a call, "get_viewport()", calls a method of that name that takes no arguments
-## and walks into what it returned. Some of what hangs off a node is only reachable by asking:
-## which control holds the focus is a question for the viewport a control is in, and the viewport
-## is a method's answer rather than a property. Spelled with the brackets so a reader sees a call
-## where one happens, and so a method can never shadow a property of the same name.
-##
-## Answers with a `message` instead when a step along the way is not there or holds something that
-## is not an object, naming the step rather than the whole path: "/root/Main:_game has no property
-## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle.
-static func walk_to(node: Node, node_path: String, reaching: String) -> Dictionary:
-	var parts: PackedStringArray = reaching.split(":")
-	var holder: Variant = node
-	var called: String = node_path
-	for step: int in parts.size() - 1:
-		var named: String = parts[step]
-		if not _can_read(holder, named):
-			return {"type": "error", "message": _nothing_there(holder, named, called)}
-		holder = read_under(holder, named)
-		called = "%s:%s" % [called, named]
-		if not _can_hold(holder):
-			var wanted: String = parts[step + 1]
-			return {"type": "error", "message": "%s holds no object to read %s off" % [called, wanted]}
-	return {"holder": holder, "name": parts[parts.size() - 1], "called": called}
-
-
-## Whether a step can be taken into [param value] at all: an object, a list or a map can be walked
-## into, and a number or a string is where a path ends whether the caller meant it to or not.
-static func _can_hold(value: Variant) -> bool:
-	return value is Object or value is Array or value is Dictionary
-
-
-## Whether [param named] is something [param holder] has.
-##
-## Three kinds of holder, because the state a game keeps is not all properties of objects: a roster
-## is a list and an in-tray is a map, and a path that could not step into either stopped at the
-## first one. An index reads the way a property does, and a negative one counts from the end the
-## way GDScript's own does, so reading the last of something does not mean asking how many first.
-## What is wrong with reading [param named] off [param holder], or "" when nothing is.
-##
-## Public because a wait asks the same question before it starts waiting, and used to answer it by
-## waiting: a property nobody has spends the whole timeout and comes back "not met", which reads
-## exactly like a game that never reached the state. The read refuses a mistyped name in one call
-## and says so, and the two tools disagreeing about one typo is worth more than the duplication.
-static func nothing_under(holder: Variant, named: String, called: String) -> String:
-	return "" if _can_read(holder, named) else _nothing_there(holder, named, called)
-
-
-static func _can_read(holder: Variant, named: String) -> bool:
-	if holder is Array:
-		var items: Array = holder
-		return _index_in(named, items.size()) != -1
-	if holder is Dictionary:
-		var map: Dictionary = holder
-		return map.has(named) or map.has(StringName(named))
-	if holder is Object:
-		var object: Object = holder
-		var method: String = _called(named)
-		if not method.is_empty():
-			return _arguments_required(object, method) == 0
-		return _has_property(object, named)
-	return false
-
-
-## The method a step written as a call names, "get_viewport()" being get_viewport, or "" for a
-## step that is a name.
-static func _called(named: String) -> String:
-	return named.trim_suffix("()") if named.ends_with("()") else ""
-
-
-## How many arguments [param method] on [param object] has to be given, or -1 when there is no such
-## method. Read off the method list rather than [method Object.has_method], because a path can only
-## call a method with nothing, and a method with a required argument called with nothing raises
-## inside the game rather than answering.
-static func _arguments_required(object: Object, method: String) -> int:
-	for entry: Dictionary in object.get_method_list():
-		if str(entry.get("name", "")) != method:
-			continue
-		var params: Array = entry.get("args", [])
-		var defaults: Array = entry.get("default_args", [])
-		return params.size() - defaults.size()
-	return -1
-
-
-## Put [param value] where [param named] points. Only ever called once [method _can_read] agrees,
-## and lists and maps are reference types, so writing into one reaches the game's own copy.
-static func _write(holder: Variant, named: String, value: Variant) -> void:
-	if holder is Array:
-		var items: Array = holder
-		items[_index_in(named, items.size())] = value
-		return
-	if holder is Dictionary:
-		var map: Dictionary = holder
-		# Written back under the key it was found under, since a map keyed by StringName and one
-		# keyed by String both read the same way and a write to the wrong one adds a second entry.
-		if map.has(named):
-			map[named] = value
-		else:
-			map[StringName(named)] = value
-		return
-	var object: Object = holder
-	object.set(named, value)
-
-
-## What [param holder] holds under [param named], or answers to it when [param named] is a call.
-## Only ever called once [method _can_read] agrees.
-static func read_under(holder: Variant, named: String) -> Variant:
-	if holder is Array:
-		var items: Array = holder
-		return items[_index_in(named, items.size())]
-	if holder is Dictionary:
-		var map: Dictionary = holder
-		if map.has(named):
-			return map[named]
-		return map[StringName(named)]
-	var object: Object = holder
-	var method: String = _called(named)
-	if not method.is_empty():
-		return object.call(method)
-	return object.get(named)
-
-
-## Where [param named] lands in a list of [param size], or -1 for a step that is not in it.
-##
-## -1 for "nowhere" is safe because every answer this gives is an index into a list that long, so a
-## real one is never negative by the time it is returned.
-static func _index_in(named: String, size: int) -> int:
-	if not named.is_valid_int():
-		return -1
-	var index: int = int(named)
-	if index < 0:
-		index += size
-	return index if index >= 0 and index < size else -1
-
-
-## Why a step could not be taken, said in the terms of what was actually there.
-##
-## "has no property 0" about a list is a true sentence that sends somebody looking for a property,
-## so a list says how long it is and a map says what it is keyed by. The step is named rather than
-## the whole path, because the step is the typo.
-static func _nothing_there(holder: Variant, named: String, called: String) -> String:
-	if holder is Array:
-		var items: Array = holder
-		return "%s is a list of %d, so there is no %s in it" % [called, items.size(), named]
-	if holder is Dictionary:
-		var map: Dictionary = holder
-		var keys: Array = map.keys()
-		# Eight of them, because a map keyed by something unexpected is told by the first few and a
-		# map of two hundred would bury the sentence saying which key was missing.
-		var some: Array[String] = []
-		for key: Variant in keys.slice(0, 8):
-			some.append(str(key))
-		var rest: String = ""
-		if keys.size() > 8:
-			rest = " and %d more" % [keys.size() - 8]
-		return "%s has no key %s; it is keyed by %s%s" % [called, named, ", ".join(some), rest]
-	var object: Object = holder
-	var method: String = _called(named)
-	if not method.is_empty():
-		var required: int = _arguments_required(object, method)
-		if required == -1:
-			return "%s has no method %s" % [called, method]
-		return (
-			"%s.%s takes %d argument%s, and a path can only call a method that takes none"
-			% [called, method, required, "" if required == 1 else "s"]
-		)
-	# A method spelled as a property is the likeliest thing behind a name the object has no property
-	# for, and the caller is one pair of brackets away from what they meant.
-	if object.has_method(named):
-		return (
-			"%s has no property %s; it has a method of that name, which a path calls as %s()"
-			% [called, named, named]
-		)
-	return "%s has no property %s" % [called, named]
-
-
-## Whether [param holder] declares [param named]. Its own function because three ops ask it and a
-## property read back as null answers it wrongly.
-static func _has_property(holder: Object, named: String) -> bool:
-	for entry: Dictionary in holder.get_property_list():
-		if str(entry["name"]) == named:
-			return true
-	return false
-
-
 func set_property(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var property: String = str(params.get("property", ""))
@@ -776,10 +581,10 @@ func set_property(params: Dictionary) -> Dictionary:
 		return standing
 	var node: Node = standing["node"]
 
-	# Through a path as well, for the reason [method walk_to] gives, and read back off the same
+	# Through a path as well, for the reason [method Paths.walk_to] gives, and read back off the same
 	# holder afterwards: a set that does not take says so by answering with the old value, which is
 	# how a typed container refusing a write is told from one accepting it.
-	var reached: Dictionary = walk_to(node, node_path, property)
+	var reached: Dictionary = Paths.walk_to(node, node_path, property)
 	if reached.has("message"):
 		return reached
 
@@ -787,7 +592,7 @@ func set_property(params: Dictionary) -> Dictionary:
 	var named: String = reached["name"]
 	# A call can be walked through and read, and is not a place: what it returns is the method's
 	# to hand out, and writing "into" it would set nothing the game keeps.
-	if not _called(named).is_empty():
+	if not Paths.method_of(named).is_empty():
 		return {
 			"type": "error",
 			"message":
@@ -796,31 +601,42 @@ func set_property(params: Dictionary) -> Dictionary:
 				% [reached["called"], named]
 			)
 		}
-	if not _can_read(holder, named):
-		return {"type": "error", "message": _nothing_there(holder, named, str(reached["called"]))}
-	var old_value: Variant = read_under(holder, named)
+	if not Paths.can_read(holder, named):
+		return {"type": "error", "message": Paths.nothing_there(holder, named, str(reached["called"]))}
+	var old_value: Variant = Paths.read_under(holder, named)
 	# The same rule the call path holds: a value that cannot become what the property holds is
 	# refused rather than written. Writing it means the engine picks something, and what it picks
 	# for a word where a number goes is zero, which the answer then reports as the new value.
-	var wanted: int = typeof(old_value)
-	var given: Variant = _values.fitted(value, wanted)
-	if not Values.acceptable(given, wanted):
-		return {
-			"type": "error",
-			"message":
-			(
-				"%s.%s holds %s and the value given is %s, which cannot become one."
-				% [reached["called"], named, type_string(wanted), type_string(typeof(given))]
-			)
-		}
-	_write(holder, named, given)
+	var slot: Dictionary = Values.slot_declared(holder, named)
+	var wanted: int = slot["type"] if slot["type"] != TYPE_NIL else typeof(old_value)
+	var given: Variant
+	if wanted == TYPE_OBJECT and (value is String or value is Dictionary):
+		var named_object: Dictionary = _object_named(node, node_path, value, str(slot["class"]))
+		if named_object.has("message"):
+			return {
+				"type": "error",
+				"message": "%s.%s holds an object: %s" % [reached["called"], named, named_object["message"]]
+			}
+		given = named_object["object"]
+	else:
+		given = _values.fitted(value, wanted)
+		if not Values.acceptable(given, wanted):
+			return {
+				"type": "error",
+				"message":
+				(
+					"%s.%s holds %s and the value given is %s, which cannot become one."
+					% [reached["called"], named, type_string(wanted), type_string(typeof(given))]
+				)
+			}
+	Paths.write(holder, named, given)
 
 	return {
 		"type": "property_set",
 		"path": node_path,
 		"property": property,
 		"old_value": _values.serialize(old_value),
-		"new_value": _values.serialize(read_under(holder, named))
+		"new_value": _values.serialize(Paths.read_under(holder, named))
 	}
 
 
@@ -837,10 +653,10 @@ func call_method(params: Dictionary) -> Dictionary:
 		return standing
 	var node: Node = standing["node"]
 
-	# Through a path as well, for the reason [method walk_to] gives. What a game does hangs off its
+	# Through a path as well, for the reason [method Paths.walk_to] gives. What a game does hangs off its
 	# nodes as much as its state does, so reading `_game:run:day` while being unable to call
 	# `_game:run:advance` answers half of what a node holds and refuses the other half.
-	var reached: Dictionary = walk_to(node, node_path, method)
+	var reached: Dictionary = Paths.walk_to(node, node_path, method)
 	if reached.has("message"):
 		return reached
 
@@ -862,8 +678,8 @@ func call_method(params: Dictionary) -> Dictionary:
 	# The method a call ends on is the one being called whether or not it carries the brackets a
 	# step along the way would: "get_viewport():gui_get_focus_owner()" is the same call as without
 	# the last pair.
-	if not _called(named).is_empty():
-		named = _called(named)
+	if not Paths.method_of(named).is_empty():
+		named = Paths.method_of(named)
 	if not holder.has_method(named):
 		return {"type": "error", "message": "%s has no method %s" % [reached["called"], named]}
 
@@ -874,6 +690,17 @@ func call_method(params: Dictionary) -> Dictionary:
 	var deserialized_args: Array = []
 	for index: int in args.size():
 		var wants: int = _values.parameter_type(holder, named, index)
+		if wants == TYPE_OBJECT and (args[index] is String or args[index] is Dictionary):
+			var declared: String = _values.parameter_class(holder, named, index)
+			var named_object: Dictionary = _object_named(node, node_path, args[index], declared)
+			if named_object.has("message"):
+				return {
+					"type": "error",
+					"message":
+					"%s.%s argument %d: %s" % [reached["called"], named, index + 1, named_object["message"]]
+				}
+			deserialized_args.append(named_object["object"])
+			continue
 		var given: Variant = _values.fitted(args[index], wants)
 		if not Values.acceptable(given, wants):
 			return {
@@ -891,6 +718,23 @@ func call_method(params: Dictionary) -> Dictionary:
 	return {"type": "method_result", "path": node_path, "method": method, "result": _values.serialize(result)}
 
 
+## The object [param given] names for a slot or a parameter declared as [param declared], as
+## `{"object": ...}`, or `{"message": ...}` saying why it names none that fits.
+##
+## JSON cannot carry an object, so one the game holds is named by its path, read from the node the
+## call or the write was made on, and handed over as that instance rather than a copy: a method
+## given a piece of the game's state acts on the piece the game keeps, and a slot written with one
+## holds the game's own.
+func _object_named(node: Node, node_path: String, given: Variant, declared: String) -> Dictionary:
+	var found: Dictionary = Paths.object_at(_host.get_tree().root, node, node_path, given)
+	if found.has("message"):
+		return found
+	var instance: Object = found["object"]
+	if not declared.is_empty() and not Values.is_a(instance, declared):
+		return {"message": "%s is %s, not a %s" % [str(given), Values.class_of(instance), declared]}
+	return found
+
+
 func get_metrics(params: Dictionary) -> Dictionary:
 	var metrics: Array = params.get("metrics", [])
 	var all: Dictionary = {
@@ -954,13 +798,13 @@ func _serialize_node_tree(
 func _named_properties_of(node: Node, path: String, named: Array[String]) -> Dictionary:
 	var properties: Dictionary = {}
 	for wanted: String in named:
-		var reached: Dictionary = walk_to(node, path, wanted)
+		var reached: Dictionary = Paths.walk_to(node, path, wanted)
 		if reached.has("message"):
 			continue
 		var holder: Variant = reached["holder"]
 		var name: String = reached["name"]
-		if _can_read(holder, name):
-			properties[wanted] = _values.serialize(read_under(holder, name))
+		if Paths.can_read(holder, name):
+			properties[wanted] = _values.serialize(Paths.read_under(holder, name))
 	return properties
 
 

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

@@ -79,6 +79,87 @@ func parameter_type(object: Object, method: String, index: int) -> int:
 	return TYPE_NIL
 
 
+## The class a method declares for argument [param index], or "" when it names none: an untyped
+## parameter, a Variant, or a type that is not an object.
+func parameter_class(object: Object, method: String, index: int) -> String:
+	for entry: Dictionary in object.get_method_list():
+		if entry.get("name", "") != method:
+			continue
+		var params: Array = entry.get("args", [])
+		if index < 0 or index >= params.size():
+			return ""
+		var parameter: Dictionary = params[index]
+		return str(parameter.get("class_name", ""))
+	return ""
+
+
+## What the slot [param named] on [param holder] declares it holds, as `{"type": int, "class":
+## String}`: a property's declaration, or the element type of a typed list or the value type of a
+## typed map. TYPE_NIL when nothing is declared.
+##
+## Asked rather than read off the value in the slot, because an object slot can be empty: a
+## property typed `Gear` holding null reads as TYPE_NIL, and anything written into it passed the
+## check and was then dropped by the engine, which answered with the slot still null.
+static func slot_declared(holder: Variant, named: String) -> Dictionary:
+	if holder is Array:
+		var items: Array = holder
+		if items.is_typed():
+			return {
+				"type": items.get_typed_builtin(),
+				"class": _typed_class(items.get_typed_script(), items.get_typed_class_name()),
+			}
+	elif holder is Dictionary:
+		var map: Dictionary = holder
+		if map.is_typed_value():
+			return {
+				"type": map.get_typed_value_builtin(),
+				"class": _typed_class(map.get_typed_value_script(), map.get_typed_value_class_name()),
+			}
+	elif holder is Object:
+		var object: Object = holder
+		for entry: Dictionary in object.get_property_list():
+			if str(entry.get("name", "")) == named:
+				return {
+					"type": Read.as_int(entry.get("type", TYPE_NIL), TYPE_NIL),
+					"class": str(entry.get("class_name", "")),
+				}
+	return {"type": TYPE_NIL, "class": ""}
+
+
+## The class a typed container names: its script's global name where it has one, since the engine
+## class of a script class is only what the script extends.
+static func _typed_class(script: Variant, engine_class: StringName) -> String:
+	if script is Script:
+		var typed: Script = script
+		if not typed.get_global_name().is_empty():
+			return str(typed.get_global_name())
+	return str(engine_class)
+
+
+## Whether [param object] is a [param declared]: an engine class, or a script class by its global
+## name anywhere along the script's inheritance.
+static func is_a(object: Object, declared: String) -> bool:
+	if object.is_class(declared):
+		return true
+	var script: Variant = object.get_script()
+	while script is Script:
+		var current: Script = script
+		if current.get_global_name() == StringName(declared):
+			return true
+		script = current.get_base_script()
+	return false
+
+
+## What [param object] is, by its script class where it has one.
+static func class_of(object: Object) -> String:
+	var script: Variant = object.get_script()
+	if script is Script:
+		var current: Script = script
+		if not current.get_global_name().is_empty():
+			return str(current.get_global_name())
+	return object.get_class()
+
+
 ## A value from the wire fitted to the type a property or parameter declares.
 func fitted(value: Variant, type: int) -> Variant:
 	return _shared.fitted(value, type)

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

@@ -3,6 +3,7 @@ extends RefCounted
 ## The commands that take time: they let the game run and answer when what was waited for has
 ## happened, or when the time ran out, so the caller never sleeps for a guessed length.
 
+const Paths = preload("runtime_paths.gd")
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
 const Values = preload("runtime_values.gd")
@@ -207,15 +208,15 @@ static func _not_comparable(current: Variant, wanted: Variant, node_path: String
 ## its nodes hold: a run object built afresh each day would leave a wait watching the day before. A
 ## step that has gone in the meantime ends the wait with what went.
 static func _watched(node: Node, node_path: String, property: String) -> Dictionary:
-	var reached: Dictionary = Queries.walk_to(node, node_path, property)
+	var reached: Dictionary = Paths.walk_to(node, node_path, property)
 	if reached.has("message"):
 		return reached
 	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
-	var missing: String = Queries.nothing_under(holder, named, str(reached["called"]))
+	var missing: String = Paths.nothing_under(holder, named, str(reached["called"]))
 	if not missing.is_empty():
 		return {"type": "error", "message": missing}
-	return {"value": Queries.read_under(holder, named)}
+	return {"value": Paths.read_under(holder, named)}
 
 
 ## Waits until something under [param node_path] has [param said] written on it.

package/build/index.js

@@ -30280,7 +30280,7 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_status",
-    description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it.",
+    description: "Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable: runtimeConnected counts the games of the project this server serves, and runtimes lists every game on the machine with ofThisProject saying which is which, since a game of another project is reached only by naming its projectPath. playingInEditor is null when the editor was not asked or did not answer, which is not the same as a no: with no editor connected there is nobody to ask, and an editor that does not serve the question is given a moment and then left. A game can be playing while this is null, so read it as unanswered rather than as nothing playing, and use processActive and runtimes, which come from elsewhere and do not depend on the editor answering. Each game under runtimes is pinged with a short wait, so one held at a breakpoint is listed as unreachable rather than making this call wait out the runtime timeout; for the run this server is reporting on, heldAt says whether that is what it is, with the same three answers editor_output gives. A game the editor played announces the editor under editorPid, and so does whatever that game started for itself; a game some other server started announces none, which is how the two are told apart when both are running from one project. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means \"not reached yet\" as often as it means \"no editor\". True is worth waiting out; false is an editor that is not there. False beside restartInterrupted is one that an editor_launch restart on a previous server asked to quit, where the launch half never ran because that server was ended in between, usually by the reconnect the restart was taken for; editor_launch open finishes it. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer. A game that has announced itself in a protocol this server does not speak is listed under unreadable rather than left out, with the protocol it speaks and whether the server or the addon is the older half. This happens during an upgrade that moves the runtime protocol, which most do not: installing replaces the addon on disk as soon as the pin moves, while a server that is already running stays on the version it started with, so the two speak different protocols until the server is reconnected. Those games are real and running, but no tool here can reach them until the halves match, so runtimes stays empty and runtimeConnected stays false. An upgrade that leaves the protocol alone opens no such window and this list stays empty through it.",
     parameters: {},
     requires: []
   },
@@ -30440,7 +30440,7 @@ var TOOL_SPECS = [
       value: {
         ops: ["set"],
         blank: true,
-        description: `set: the value, fitted to the property's type. "" writes an empty string.`
+        description: `set: the value, fitted to the property's type. "" writes an empty string. A property typed as or holding an object takes a path naming one the game holds, the way call's args do, and holds that instance.`
       },
       method: {
         type: "string",
@@ -30450,7 +30450,7 @@ var TOOL_SPECS = [
       args: {
         type: "array",
         ops: ["call"],
-        description: "call: the arguments, fitted to the method's parameter types."
+        description: `call: the arguments, fitted to the method's parameter types. A parameter typed as an object takes a path naming one the game holds and is handed that instance: a colon path read from nodePath, "_game:run:wares:3", or one starting at a node, "/root/Main/Hud" or "/root/Main:_game:run". A path that reaches no object, or an object of another class than the parameter declares, is refused.`
       }
     },
     requires: ["nodePath"],
@@ -30797,6 +30797,9 @@ function stillRunning(run) {
   if (run?.exitCode !== null || run.endedUnwatched === true) {
     return false;
   }
+  if (typeof run.endedHere === "string") {
+    return false;
+  }
   if (!run.throughEditor && run.process === null && run.pid !== null) {
     return alive(run.pid);
   }
@@ -30810,6 +30813,9 @@ function runIsUp(run, editorSays, now = Date.now()) {
   if (run?.throughEditor !== true) {
     return stillRunning(run);
   }
+  if (typeof run.endedHere === "string") {
+    return false;
+  }
   if (run.announcedPid !== undefined && !alive(run.announcedPid)) {
     return false;
   }
@@ -30818,6 +30824,22 @@ function runIsUp(run, editorSays, now = Date.now()) {
   }
   return editorSays ?? stillRunning(run);
 }
+function noCodeWillCome(run) {
+  return run.exitCode === null && run.process === null;
+}
+function endedWithoutACode(run) {
+  if (!run.throughEditor) {
+    return run.endedHere ? "This run was started by another server, so nothing here held it and its exit code was never collected. Everything it printed is below, read back from its transcript." : "This run was started by another server, the one this server replaced or one running beside it, and it ended with nothing here waiting on it, so its exit code was never collected. Everything it printed is below, read back from its transcript.";
+  }
+  const kept = "A game the editor plays is the editor's own child, so its exit code stays with the editor and none was collected here.";
+  if (run.endedHere) {
+    return `${kept} What it printed is below.`;
+  }
+  if (!run.announced && run.couldAnnounce) {
+    return `The editor stopped playing this run before its game announced a runtime, so the game ended while it was starting or was closed in the editor. ${kept} What it printed is below, and editor_output with op "editor" has what the editor said about it.`;
+  }
+  return `The editor stopped playing this run. ${kept} What it printed is below.`;
+}
 function endedPreviousRun(ended) {
   if (ended === null) {
     return;
@@ -32604,6 +32626,7 @@ class GodotServer {
         pid: endpoint.pid,
         port: endpoint.port,
         project: endpoint.project,
+        ...this.ownProject === null ? {} : { ofThisProject: isSameDirectory(endpoint.project.path, this.ownProject) },
         editorPid: endpoint.editorPid,
         reachable: reply.ok,
         problem: reply.ok ? null : reply.message
@@ -32635,7 +32658,7 @@ class GodotServer {
         processActive: active,
         playingInEditor: playing,
         ...hold,
-        runtimeConnected: games.some((game) => game.reachable),
+        runtimeConnected: games.some((game) => game.reachable && game.ofThisProject !== false),
         runtimes: games,
         unreadable: announced.unspoken.map((game) => ({
           pid: game.pid,
@@ -32859,7 +32882,7 @@ class GodotServer {
     if (before !== null && await this.runStillGoing(before)) {
       this.logDebug("Ending the running game before starting another");
       ended = { pid: before.pid ?? this.announcedPidOf(before) ?? null };
-      await this.endActiveGame("editor_run start, which ends the run that was going before it starts another");
+      await this.endActiveGame("editor_run start, which ends the run that was going before it starts another", true);
     }
     const alreadyPlaying = new Set(discoverRuntimes().map((endpoint) => endpoint.pid));
     const wereHereFirst = this.everyRuntimeOfOurs();
@@ -33100,12 +33123,11 @@ class GodotServer {
     game.brokeOn = halt.text;
     game.log.record("error", halt.text);
   }
-  async endActiveGame(reason) {
+  async endActiveGame(reason, going) {
     const running = this.activeProcess;
-    this.activeProcess = null;
     const recorded = running?.process === null ? readRunRecord() : null;
     clearRunRecord((record) => this.couldBeOurs(record.projectPath));
-    if (!running) {
+    if (!running || !going) {
       return;
     }
     running.endedHere = reason;
@@ -33269,7 +33291,8 @@ class GodotServer {
       return;
     }
     const going = this.activeProcess;
-    if (going !== null) {
+    const givesWay = going !== null && !stillRunning(going) && typeof going.endedHere === "string";
+    if (going !== null && !givesWay) {
       if (going.throughEditor && going.consoleLost === true && (await this.editorPlayingState())?.playing) {
         try {
           await this.dap().connect();
@@ -33655,7 +33678,7 @@ class GodotServer {
     const going = await this.runStillGoing(run);
     if (run.endedUnwatched !== true && !going) {
       run.log.finish();
-      run.endedUnwatched = run.exitCode === null;
+      run.endedUnwatched = noCodeWillCome(run);
     }
     const severity = readString(args, "severity");
     const selected = run.log.select({
@@ -33676,8 +33699,18 @@ class GodotServer {
     if (waitedMs !== undefined) {
       notes.push(`The wait of ${waitedMs}ms ran out and the run is still going, so this is what it had printed by then rather than everything it will print. editor_run wait again to keep waiting.`);
     }
+    if (typeof run.endedHere === "string") {
+      notes.push(`This run was ended here, by ${run.endedHere}.`);
+    } else if (!stillRunning(run) && !run.throughEditor && run.exitCode !== null) {
+      notes.push(run.exitCode === 0 ? "This run quit on its own, cleanly: exit code 0." : "Nothing here ended this run: it stopped on its own or something outside this server stopped it.");
+    }
     if (run.endedUnwatched === true) {
-      notes.push("This run outlived the server that started it and is over now, so its exit code was never collected. Everything it printed is below, read back from its transcript.");
+      notes.push(endedWithoutACode({
+        throughEditor: run.throughEditor,
+        announced: announced !== undefined || run.announcedPid !== undefined,
+        couldAnnounce: run.projectPath !== null && existsSync10(join16(run.projectPath, RUNTIME_AUTOLOAD.path)),
+        endedHere: typeof run.endedHere === "string"
+      }));
     }
     if (run.pickedUpPlaying === true) {
       notes.push(run.transcript === null ? "The editor was already playing this when this server reached it, and the server that started it left no transcript, so this is not the run from its start: what it printed before that is only in the editor. It is the run the editor is holding now, which is the one the debug_* tools answer for." : "The editor was already playing this when this server reached it, and what it printed before that has been read back from its transcript. It is the run the editor is holding now, which is the one the debug_* tools answer for.");
@@ -33686,11 +33719,6 @@ class GodotServer {
       const back = this.dapClient?.isConnected() === true;
       notes.push(`The debug adapter this run's console arrives over went away while the run was going, so what is below has a hole in it and the counts are of what was heard rather than of what was printed. ${back ? "It is connected again, and the line marking where is in the log." : "It is still gone, so nothing further will arrive here."} The project's own user://logs/godot.log has the rest, and "no entries" here means "not heard" rather than a quiet run.`);
     }
-    if (typeof run.endedHere === "string") {
-      notes.push(`This run was ended here, by ${run.endedHere}.`);
-    } else if (!stillRunning(run) && !run.throughEditor && run.exitCode !== null) {
-      notes.push(run.exitCode === 0 ? "This run quit on its own, cleanly: exit code 0." : "Nothing here ended this run: it stopped on its own or something outside this server stopped it.");
-    }
     if (run.transcript !== null && selected.omitted > 0) {
       notes.push(`Everything this run has printed is in ${run.transcript}, uncapped and still being written. Read it for output, not for whether the run is alive: a transcript that stops growing is a run between prints. running above is asked of the operating system while there is a process to ask about, and for an editor-played run that announced no runtime it is the editor's answer instead, which can lag after the game has gone.`);
     }
@@ -33729,7 +33757,7 @@ class GodotServer {
     const endedPid = stopped.pid ?? announcedPid;
     const children = readBoolean(args, "andChildren") === true && wasRunning ? await this.whatTheRunStarted(stopped) : null;
     this.logDebug("Stopping the running game");
-    await this.endActiveGame("editor_run stop");
+    await this.endActiveGame("editor_run stop", wasRunning);
     const ended = children === null ? null : endChildrenAmong(children);
     if (wasRunning) {
       for (const pid of new Set([endedPid, announcedPid])) {
@@ -33748,12 +33776,12 @@ class GodotServer {
         childrenLeft: ended.left.length === 0 ? undefined : ended.left,
         childrenUnknown: ended.unknown === false ? undefined : true
       },
-      exitedBeforeStop: stopped.exitCode !== null || !wasRunning,
+      exitedBeforeStop: !wasRunning,
       exitCode: stopped.exitCode,
       errors: stopped.log.count("error"),
       warnings: stopped.log.count("warning"),
       clean: stopped.log.count("error") === 0,
-      note: !wasRunning ? "This run was over before the stop, so nothing was ended here: editor_output has what it printed and how it ended. Anything that game started for itself, with OS.create_process or otherwise, is a separate process and may still be running." : `${stopped.throughEditor ? "The editor was asked to stop the scene it is playing." : "The process named under endedPid was ended."} ${aboutTheChildren(ended, stopped.throughEditor)}`,
+      note: !wasRunning ? "This run was over before the stop, so nothing was ended here: editor_output has what it printed and how it ended. Anything that game started for itself, with OS.create_process or otherwise, is a separate process and may still be running." : `${stopped.throughEditor ? endedPid === null ? "The editor was asked to stop the scene it is playing. Its game had not announced a runtime, so no process was named under endedPid, and its exit code stays with the editor." : "The editor was asked to stop the scene it is playing." : "The process named under endedPid was ended."} ${aboutTheChildren(ended, stopped.throughEditor)}`,
       entries: forAnswer(stopped.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries)
     });
   }

package/package.json

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