gdharness 1.0.22 → 1.0.23

package/build/cli.js

@@ -16415,7 +16415,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: 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. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved, which is that it was held when the bridge started, most often by the server a reconnect replaced.",
+      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. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait.",
       parameters: {},
       requires: []
     },
@@ -16570,12 +16570,12 @@ var init_tool_definitions = __esm(() => {
         property: {
           type: "string",
           ops: ["set"],
-          description: 'set: which one to write. Colons write through what a node holds, "_game:run:day", and a number or a key steps into a list or a map on the way, "_game:run:roster:0:name", a negative number counting from the end, and a step written as a call, "get_viewport():gui_embed_subwindows", walks through what a method taking no arguments returned. The answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
+          description: 'set: which one to write. Colons write through what a node holds, "_game:run:day", and a number or a key steps into a list or a map on the way, "_game:run:roster:0:name", a negative number counting from the end, and a step written as a call, "get_viewport():gui_embed_subwindows", walks through what a method taking no arguments returned. The answer reads back off the same holder, and a write that leaves the property as it was, because the engine would not take it, is refused and says what the property still holds.'
         },
         value: {
           ops: ["set"],
           blank: true,
-          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.`
+          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. A typed list or map, such as Array[int] or Dictionary[String, int], takes a JSON list or object with each element fitted to its element type, and an element that cannot become one is refused by its index or key.`
         },
         method: {
           type: "string",
@@ -16585,7 +16585,7 @@ var init_tool_definitions = __esm(() => {
         args: {
           type: "array",
           ops: ["call"],
-          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.`
+          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. A parameter typed as a list or map, such as Array[int] or Array[Gear], is built from a JSON list or object element by element, objects named by their paths.`
         }
       },
       requires: ["nodePath"],
@@ -36145,7 +36145,10 @@ var init_godot_bridge = __esm(() => {
     get port() {
       return this.boundPort ?? this.wantedPort;
     }
-    async start() {
+    get configuredPort() {
+      return this.wantedPort;
+    }
+    async start(moveIfHeld = true) {
       if (this.httpServer) {
         return;
       }
@@ -36153,7 +36156,7 @@ var init_godot_bridge = __esm(() => {
         await this.listenOn(this.wantedPort);
       } catch (error) {
         const held = error instanceof Error && "code" in error && error.code === "EADDRINUSE";
-        if (!held || !this.mayMove) {
+        if (!held || !this.mayMove || !moveIfHeld) {
           throw error;
         }
         this.log("warn", `Editor bridge port ${this.wantedPort} is held; taking another one.`);
@@ -38146,6 +38149,14 @@ function runIsUp(run, editorSays, now = Date.now()) {
 function noCodeWillCome(run) {
   return run.exitCode === null && run.process === null;
 }
+async function untilGone(handle, pids, withinMs = STOP_WAIT_MS) {
+  const gone = () => (handle?.exitCode !== null || handle.signalCode !== null) && pids.every((pid) => !alive(pid));
+  const deadline = Date.now() + withinMs;
+  while (!gone() && Date.now() < deadline) {
+    await delay3(50);
+  }
+  return gone();
+}
 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.";
@@ -38419,6 +38430,8 @@ class GodotServer {
   launchedFrom = null;
   ownProject;
   announcedAt = null;
+  handingOverFrom = null;
+  notHandedOverBy = null;
   constructor() {
     this.ownProject = envValue("GDHARNESS_PROJECT") ?? null;
     this.godotBridge = getDefaultBridge(this.ownProject);
@@ -38465,6 +38478,7 @@ class GodotServer {
     });
     console.error("gdharness running on stdio");
     try {
+      await this.takeOverFromAPredecessor();
       await this.godotBridge.start();
       this.bridgeStartupError = null;
       const bridgeStatus = this.godotBridge.getStatus();
@@ -38479,6 +38493,35 @@ class GodotServer {
       this.keepTryingTheBridge();
     }
   }
+  async takeOverFromAPredecessor() {
+    if (this.ownProject === null) {
+      return;
+    }
+    const wanted = this.godotBridge.configuredPort;
+    const announced = readAnnouncement2(announcementPath2(this.ownProject));
+    if (announced === null || announced.pid === process.pid || announced.port !== wanted || !alive(announced.pid)) {
+      return;
+    }
+    this.handingOverFrom = announced.pid;
+    this.announcedAt = announceBridge(this.ownProject, {
+      host: this.godotBridge.getStatus().host,
+      port: wanted,
+      version: SERVER_VERSION
+    });
+    const until = Date.now() + HANDOVER_MS;
+    let taken = false;
+    while (!taken && Date.now() < until && !this.shutdownInitiated) {
+      try {
+        await this.godotBridge.start(false);
+        taken = true;
+        this.logDebug(`Took port ${wanted} over from pid ${announced.pid}`);
+      } catch {
+        await delay3(HANDOVER_POLL_MS);
+      }
+    }
+    this.handingOverFrom = null;
+    this.notHandedOverBy = taken ? null : announced.pid;
+  }
   keepTryingTheBridge() {
     if (this.bridgeRetry !== null || this.shutdownInitiated) {
       return;
@@ -39852,7 +39895,12 @@ class GodotServer {
       awaitingLaunchedEditor: status.connected || !this.launchedEditorIsUp() ? undefined : this.launchedEditor?.pid ?? undefined,
       ...status.connected ? this.whatTheLaunchedEditorDropped() : {},
       startupError: this.bridgeStartupError,
-      portNote: status.portWanted === undefined ? undefined : `Port ${status.portWanted}, the one this server was configured with, was held by another process when the bridge started, so it took ${status.port} and announced that where the editor looks for it${this.announcedAt === null ? "" : `, ${this.announcedAt}`}. The editor finds it there; the next server started takes ${status.portWanted} again if it is free.`,
+      portNote: status.portWanted === undefined ? undefined : `Port ${status.portWanted}, the one this server was configured with, was held ${this.notHandedOverBy === null ? "by another process" : `by pid ${this.notHandedOverBy}, the gdharness server this one replaced, which had not let go of it ${HANDOVER_MS / 1000} seconds after being told it was replaced`} when the bridge started, so it took ${status.port} and announced that where the editor looks for it${this.announcedAt === null ? "" : `, ${this.announcedAt}`}. The editor finds it there; the next server started takes ${status.portWanted} again if it is free.`,
+      bridgeHandover: this.handingOverFrom === null ? undefined : {
+        fromPid: this.handingOverFrom,
+        port: this.godotBridge.configuredPort,
+        note: `The gdharness server this one replaced, pid ${this.handingOverFrom}, still holds port ${this.godotBridge.configuredPort} and is standing down; this server takes the port when it lets go, and takes another after ${HANDOVER_MS / 1000} seconds if it does not.`
+      },
       staleNote: stale ? addonMismatch(status.addonVersion, SERVER_VERSION, status.addonDigest, shippedEditorDigest()) : undefined,
       addonNote: status.connected ? sameCodeNote(status.addonVersion, SERVER_VERSION, status.addonDigest, shippedEditorDigest()) : undefined,
       ...this.breakpointsAtRisk(),
@@ -40404,24 +40452,25 @@ class GodotServer {
     const recorded = running?.process === null ? readRunRecord() : null;
     clearRunRecord((record) => this.couldBeOurs(record.projectPath));
     if (!running || !going) {
-      return;
+      return true;
     }
     running.endedHere = reason;
+    const announced = this.announcedPidOf(running);
     if (running.throughEditor) {
       await this.handleViaBridge("stop_playing", {});
-      return;
+      return await untilGone(null, announced === undefined ? [] : [announced]);
     }
     if (running.process !== null) {
       running.process.kill();
-      return;
+      return await untilGone(running.process, announced === undefined ? [] : [announced]);
     }
     if (running.pid === null) {
-      return;
+      return true;
     }
     if (recorded === null || recorded.pid !== running.pid || !stillTheRecordedRun(recorded)) {
       running.endedHere = null;
       running.log.record("warning", `This run was not ended here: pid ${running.pid} no longer answers as the run that was recorded, so nothing was signalled. If that process is still the game, end it yourself; if it is not, it belongs to something else.`);
-      return;
+      return true;
     }
     const signalled = runningAs(running.pid);
     const described = signalled === null ? "nothing it would name" : `${signalled.kind}: ${signalled.text}`;
@@ -40431,7 +40480,9 @@ class GodotServer {
     } catch {
       landed = false;
     }
+    const gone = await untilGone(null, [running.pid]);
     running.log.record("info", landed ? `gdharness ended pid ${running.pid}, which the operating system described as ${described}.` : `gdharness signalled pid ${running.pid} and it was already gone; the operating system had described it as ${described}.`);
+    return gone;
   }
   spawnGame(godotPath, cmdArgs, env) {
     const child = spawn(godotPath, cmdArgs, { stdio: ["ignore", "pipe", "pipe"], ...env ? { env } : {} });
@@ -41033,7 +41084,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", wasRunning);
+    const gone = await this.endActiveGame("editor_run stop", wasRunning);
     const ended = children === null ? null : endChildrenAmong(children);
     if (wasRunning) {
       for (const pid of new Set([endedPid, announcedPid])) {
@@ -41057,7 +41108,7 @@ class GodotServer {
       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 ? 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)}`,
+      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."}${gone ? "" : ` It had not exited ${STOP_WAIT_MS / 1000} seconds after being told to, so it may still be going: editor_status says whether it is.`} ${aboutTheChildren(ended, stopped.throughEditor)}`,
       entries: forAnswer(stopped.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries)
     });
   }
@@ -41573,7 +41624,7 @@ async function runGodotServer() {
   const server = new GodotServer;
   await server.run();
 }
-var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run7, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, CONSOLE_WRAPPER, LONGEST_BOOT_NOTED_MS, MOST_GROUPS = 20, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CACHE_WRITE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/";
+var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run7, __dirname2, EDITOR_RESTART_TIMEOUT_MS = 90000, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, STOP_WAIT_MS = 1e4, CONSOLE_WRAPPER, LONGEST_BOOT_NOTED_MS, MOST_GROUPS = 20, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/";
 var init_server3 = __esm(() => {
   init_mcp();
   init_stdio2();
@@ -41620,6 +41671,7 @@ var init_server3 = __esm(() => {
     boolean: "a boolean",
     object: "an object"
   };
+  HANDOVER_MS = SUCCESSOR_CHECK_MS + 5000;
   PATH_SOLUTIONS = [
     'Give the path relative to the project, such as "scenes/main.tscn" or "res://scenes/main.tscn"',
     "Point projectPath at the project the file belongs to"

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

@@ -629,14 +629,49 @@ func set_property(params: Dictionary) -> Dictionary:
 					% [reached["called"], named, type_string(wanted), type_string(typeof(given))]
 				)
 			}
+		var typed: Dictionary = _values.typed_like(given, old_value, _element_object.bind(node, node_path))
+		if typed.has("message"):
+			return {
+				"type": "error",
+				"message":
+				"%s.%s is a typed %s: %s." % [reached["called"], named, _sort_of(old_value), typed["message"]]
+			}
+		given = typed["value"]
 	Paths.write(holder, named, given)
+	var now: Variant = Paths.read_under(holder, named)
+	# Read back rather than trusted. The engine drops a write it will not take without a word, and
+	# the answer then showed the old value as the new one, shaped as a success: a typed container
+	# refusing a plain list did exactly that. A value the property changed on the way in, a setter
+	# clamping it, still changed it, so only a write that left the property as it was is refused.
+	if (
+		Values.comparable(given, old_value)
+		and given != old_value
+		and Values.comparable(now, old_value)
+		and now == old_value
+	):
+		return {
+			"type": "error",
+			"message":
+			(
+				(
+					"%s.%s was given %s and still holds %s: the engine kept what it had,"
+					+ " which a property it will not write does."
+				)
+				% [
+					reached["called"],
+					named,
+					JSON.stringify(_values.serialize(given)),
+					JSON.stringify(_values.serialize(now))
+				]
+			)
+		}
 
 	return {
 		"type": "property_set",
 		"path": node_path,
 		"property": property,
 		"old_value": _values.serialize(old_value),
-		"new_value": _values.serialize(Paths.read_under(holder, named))
+		"new_value": _values.serialize(now)
 	}
 
 
@@ -711,6 +746,23 @@ func call_method(params: Dictionary) -> Dictionary:
 					% [reached["called"], named, type_string(wants), index + 1, type_string(typeof(given))]
 				)
 			}
+		# A typed list or map is built as one, since a plain one handed to such a parameter raises
+		# inside the game, which is what every check here exists to stop.
+		var container: Variant = _values.parameter_container(holder, named, index)
+		if container != null:
+			var typed: Dictionary = _values.typed_like(
+				given, container, _element_object.bind(node, node_path)
+			)
+			if typed.has("message"):
+				return {
+					"type": "error",
+					"message":
+					(
+						"%s.%s takes a typed %s as argument %d: %s."
+						% [reached["called"], named, _sort_of(container), index + 1, typed["message"]]
+					)
+				}
+			given = typed["value"]
 		deserialized_args.append(given)
 
 	var result: Variant = holder.callv(named, deserialized_args)
@@ -718,6 +770,17 @@ func call_method(params: Dictionary) -> Dictionary:
 	return {"type": "method_result", "path": node_path, "method": method, "result": _values.serialize(result)}
 
 
+## [method _object_named] with the path first, which is the order [method Values.typed_like] calls
+## an element resolver in.
+func _element_object(given: Variant, declared: String, node: Node, node_path: String) -> Dictionary:
+	return _object_named(node, node_path, given, declared)
+
+
+## "list" or "map", for a refusal about a typed container.
+static func _sort_of(container: Variant) -> String:
+	return "list" if container is Array else "map"
+
+
 ## 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.
 ##

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

@@ -163,3 +163,149 @@ static func class_of(object: Object) -> String:
 ## 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)
+
+
+## An empty list or map typed the way argument [param index] of [param method] declares, or null
+## when that argument is not a typed container. What [method typed_like] builds against.
+func parameter_container(object: Object, method: String, index: int) -> Variant:
+	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 null
+		var parameter: Dictionary = params[index]
+		var hint: int = Read.as_int(parameter.get("hint", 0), 0)
+		var named: String = str(parameter.get("hint_string", ""))
+		if hint == PROPERTY_HINT_ARRAY_TYPE:
+			var element: Dictionary = _element_type(named)
+			if element.is_empty():
+				return null
+			var builtin: int = element["builtin"]
+			var engine_class: StringName = element["class"]
+			return Array([], builtin, engine_class, element["script"])
+		if hint == PROPERTY_HINT_DICTIONARY_TYPE and named.contains(";"):
+			var key: Dictionary = _element_type(named.get_slice(";", 0))
+			var entry_type: Dictionary = _element_type(named.get_slice(";", 1))
+			if key.is_empty() or entry_type.is_empty():
+				return null
+			var key_builtin: int = key["builtin"]
+			var key_class: StringName = key["class"]
+			var value_builtin: int = entry_type["builtin"]
+			var value_class: StringName = entry_type["class"]
+			return Dictionary(
+				{}, key_builtin, key_class, key["script"], value_builtin, value_class, entry_type["script"]
+			)
+		return null
+	return null
+
+
+## The type a container hint names, as `{"builtin", "class", "script"}`, or {} for a name this
+## cannot resolve. A built-in type by its name, an engine class, or a script class by its global
+## name, which a typed container holds as the class it extends and the script itself.
+static func _element_type(named: String) -> Dictionary:
+	for type: int in TYPE_MAX:
+		if type != TYPE_OBJECT and type_string(type) == named:
+			return {"builtin": type, "class": &"", "script": null}
+	if ClassDB.class_exists(named):
+		return {"builtin": TYPE_OBJECT, "class": StringName(named), "script": null}
+	for global: Dictionary in ProjectSettings.get_global_class_list():
+		if str(global.get("class", "")) == named:
+			var script: Script = load(str(global.get("path", "")))
+			if script == null:
+				return {}
+			return {"builtin": TYPE_OBJECT, "class": script.get_instance_base_type(), "script": script}
+	return {}
+
+
+## [param given] rebuilt as the typed list or map [param like] is, as `{"value": ...}`, or
+## `{"message": ...}` naming the element that cannot become what the container holds.
+##
+## A typed container refuses a plain one, and the engine says nothing about it: an Array[int]
+## property written with the list JSON carries kept what it held, and the answer showed the write
+## as done. Each element is fitted the way a single value is, and an object element is named by
+## its path through [param resolve], which is called with the path and the class declared and
+## answers the way an object argument does. Anything that is not a typed container comes back as
+## it was given.
+func typed_like(given: Variant, like: Variant, resolve: Callable) -> Dictionary:
+	if like is Array and given is Array:
+		var template: Array = like
+		if not template.is_typed():
+			return {"value": given}
+		var items: Array = given
+		var built: Array = []
+		for index: int in items.size():
+			var element: Dictionary = _element(
+				items[index],
+				template.get_typed_builtin(),
+				_typed_class(template.get_typed_script(), template.get_typed_class_name()),
+				resolve
+			)
+			if element.has("message"):
+				return {"message": "element %d %s" % [index, element["message"]]}
+			built.append(element["value"])
+		return {
+			"value":
+			Array(
+				built,
+				template.get_typed_builtin(),
+				template.get_typed_class_name(),
+				template.get_typed_script()
+			)
+		}
+	if like is Dictionary and given is Dictionary:
+		var map_like: Dictionary = like
+		if not map_like.is_typed():
+			return {"value": given}
+		var entries: Dictionary = given
+		var rebuilt: Dictionary = {}
+		for key: Variant in entries:
+			var key_fitted: Dictionary = _element(
+				key,
+				map_like.get_typed_key_builtin(),
+				_typed_class(map_like.get_typed_key_script(), map_like.get_typed_key_class_name()),
+				resolve
+			)
+			if key_fitted.has("message"):
+				return {"message": "key %s %s" % [str(key), key_fitted["message"]]}
+			var value_fitted: Dictionary = _element(
+				entries[key],
+				map_like.get_typed_value_builtin(),
+				_typed_class(map_like.get_typed_value_script(), map_like.get_typed_value_class_name()),
+				resolve
+			)
+			if value_fitted.has("message"):
+				return {"message": "the value under %s %s" % [str(key), value_fitted["message"]]}
+			rebuilt[key_fitted["value"]] = value_fitted["value"]
+		return {
+			"value":
+			Dictionary(
+				rebuilt,
+				map_like.get_typed_key_builtin(),
+				map_like.get_typed_key_class_name(),
+				map_like.get_typed_key_script(),
+				map_like.get_typed_value_builtin(),
+				map_like.get_typed_value_class_name(),
+				map_like.get_typed_value_script()
+			)
+		}
+	return {"value": given}
+
+
+## One element fitted to a container's element type, as `{"value"}` or `{"message"}` saying what it
+## was and what goes there. The message is the part after "element N".
+func _element(item: Variant, builtin: int, declared: String, resolve: Callable) -> Dictionary:
+	if builtin == TYPE_NIL:
+		return {"value": item}
+	if builtin == TYPE_OBJECT and item is String:
+		var named: Dictionary = resolve.call(item, declared)
+		if named.has("message"):
+			return {"message": str(named["message"])}
+		return {"value": named["object"]}
+	var fitted_item: Variant = fitted(item, builtin)
+	if not acceptable(fitted_item, builtin):
+		# The value as it was sent rather than its engine type: JSON numbers arrive as floats, so a 7
+		# the caller wrote was named "float".
+		var wanted: String = declared if builtin == TYPE_OBJECT else type_string(builtin)
+		return {"message": "is %s, which cannot become %s" % [JSON.stringify(serialize(item)), wanted]}
+	return {"value": fitted_item}

package/build/index.js

@@ -27107,7 +27107,10 @@ class GodotBridge extends EventEmitter {
   get port() {
     return this.boundPort ?? this.wantedPort;
   }
-  async start() {
+  get configuredPort() {
+    return this.wantedPort;
+  }
+  async start(moveIfHeld = true) {
     if (this.httpServer) {
       return;
     }
@@ -27115,7 +27118,7 @@ class GodotBridge extends EventEmitter {
       await this.listenOn(this.wantedPort);
     } catch (error) {
       const held = error instanceof Error && "code" in error && error.code === "EADDRINUSE";
-      if (!held || !this.mayMove) {
+      if (!held || !this.mayMove || !moveIfHeld) {
         throw error;
       }
       this.log("warn", `Editor bridge port ${this.wantedPort} is held; taking another one.`);
@@ -30287,7 +30290,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: 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. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved, which is that it was held when the bridge started, most often by the server a reconnect replaced.",
+    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. addonIsStale is decided by the code of the editor addons rather than their version, so an editor started before an upgrade that left that code alone reports the older addonVersion, is not stale, and addonNote says so: it needs no restart. port is the one the editor bridge is on; when that is not the one this server was configured with, portWanted names the configured one and portNote says why it moved and, when it was the server this one replaced, which pid kept it. A server replacing another of its project that holds the configured port waits for it to stand down and takes the port over, which takes a few seconds; bridgeHandover says so while it waits, and it moves only if that server has not let go within the wait.",
     parameters: {},
     requires: []
   },
@@ -30442,12 +30445,12 @@ var TOOL_SPECS = [
       property: {
         type: "string",
         ops: ["set"],
-        description: 'set: which one to write. Colons write through what a node holds, "_game:run:day", and a number or a key steps into a list or a map on the way, "_game:run:roster:0:name", a negative number counting from the end, and a step written as a call, "get_viewport():gui_embed_subwindows", walks through what a method taking no arguments returned. The answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
+        description: 'set: which one to write. Colons write through what a node holds, "_game:run:day", and a number or a key steps into a list or a map on the way, "_game:run:roster:0:name", a negative number counting from the end, and a step written as a call, "get_viewport():gui_embed_subwindows", walks through what a method taking no arguments returned. The answer reads back off the same holder, and a write that leaves the property as it was, because the engine would not take it, is refused and says what the property still holds.'
       },
       value: {
         ops: ["set"],
         blank: true,
-        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.`
+        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. A typed list or map, such as Array[int] or Dictionary[String, int], takes a JSON list or object with each element fitted to its element type, and an element that cannot become one is refused by its index or key.`
       },
       method: {
         type: "string",
@@ -30457,7 +30460,7 @@ var TOOL_SPECS = [
       args: {
         type: "array",
         ops: ["call"],
-        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.`
+        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. A parameter typed as a list or map, such as Array[int] or Array[Gear], is built from a JSON list or object element by element, objects named by their paths.`
       }
     },
     requires: ["nodePath"],
@@ -30834,6 +30837,15 @@ function runIsUp(run, editorSays, now = Date.now()) {
 function noCodeWillCome(run) {
   return run.exitCode === null && run.process === null;
 }
+var STOP_WAIT_MS = 1e4;
+async function untilGone(handle, pids, withinMs = STOP_WAIT_MS) {
+  const gone = () => (handle?.exitCode !== null || handle.signalCode !== null) && pids.every((pid) => !alive(pid));
+  const deadline = Date.now() + withinMs;
+  while (!gone() && Date.now() < deadline) {
+    await delay3(50);
+  }
+  return gone();
+}
 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.";
@@ -31019,6 +31031,8 @@ function outsideTheirLists(spec, args) {
 }
 var BRIDGE_RETRY_MS = 2000;
 var SUCCESSOR_CHECK_MS = 1e4;
+var HANDOVER_MS = SUCCESSOR_CHECK_MS + 5000;
+var HANDOVER_POLL_MS = 250;
 var CACHE_WRITE_MS = 2000;
 var PLAYING_STATUS_MS = 1000;
 var SCAN_START_MS = 2000;
@@ -31152,6 +31166,8 @@ class GodotServer {
   launchedFrom = null;
   ownProject;
   announcedAt = null;
+  handingOverFrom = null;
+  notHandedOverBy = null;
   constructor() {
     this.ownProject = envValue("GDHARNESS_PROJECT") ?? null;
     this.godotBridge = getDefaultBridge(this.ownProject);
@@ -31198,6 +31214,7 @@ class GodotServer {
     });
     console.error("gdharness running on stdio");
     try {
+      await this.takeOverFromAPredecessor();
       await this.godotBridge.start();
       this.bridgeStartupError = null;
       const bridgeStatus = this.godotBridge.getStatus();
@@ -31212,6 +31229,35 @@ class GodotServer {
       this.keepTryingTheBridge();
     }
   }
+  async takeOverFromAPredecessor() {
+    if (this.ownProject === null) {
+      return;
+    }
+    const wanted = this.godotBridge.configuredPort;
+    const announced = readAnnouncement(announcementPath(this.ownProject));
+    if (announced === null || announced.pid === process.pid || announced.port !== wanted || !alive(announced.pid)) {
+      return;
+    }
+    this.handingOverFrom = announced.pid;
+    this.announcedAt = announceBridge(this.ownProject, {
+      host: this.godotBridge.getStatus().host,
+      port: wanted,
+      version: SERVER_VERSION
+    });
+    const until = Date.now() + HANDOVER_MS;
+    let taken = false;
+    while (!taken && Date.now() < until && !this.shutdownInitiated) {
+      try {
+        await this.godotBridge.start(false);
+        taken = true;
+        this.logDebug(`Took port ${wanted} over from pid ${announced.pid}`);
+      } catch {
+        await delay3(HANDOVER_POLL_MS);
+      }
+    }
+    this.handingOverFrom = null;
+    this.notHandedOverBy = taken ? null : announced.pid;
+  }
   keepTryingTheBridge() {
     if (this.bridgeRetry !== null || this.shutdownInitiated) {
       return;
@@ -32585,7 +32631,12 @@ class GodotServer {
       awaitingLaunchedEditor: status.connected || !this.launchedEditorIsUp() ? undefined : this.launchedEditor?.pid ?? undefined,
       ...status.connected ? this.whatTheLaunchedEditorDropped() : {},
       startupError: this.bridgeStartupError,
-      portNote: status.portWanted === undefined ? undefined : `Port ${status.portWanted}, the one this server was configured with, was held by another process when the bridge started, so it took ${status.port} and announced that where the editor looks for it${this.announcedAt === null ? "" : `, ${this.announcedAt}`}. The editor finds it there; the next server started takes ${status.portWanted} again if it is free.`,
+      portNote: status.portWanted === undefined ? undefined : `Port ${status.portWanted}, the one this server was configured with, was held ${this.notHandedOverBy === null ? "by another process" : `by pid ${this.notHandedOverBy}, the gdharness server this one replaced, which had not let go of it ${HANDOVER_MS / 1000} seconds after being told it was replaced`} when the bridge started, so it took ${status.port} and announced that where the editor looks for it${this.announcedAt === null ? "" : `, ${this.announcedAt}`}. The editor finds it there; the next server started takes ${status.portWanted} again if it is free.`,
+      bridgeHandover: this.handingOverFrom === null ? undefined : {
+        fromPid: this.handingOverFrom,
+        port: this.godotBridge.configuredPort,
+        note: `The gdharness server this one replaced, pid ${this.handingOverFrom}, still holds port ${this.godotBridge.configuredPort} and is standing down; this server takes the port when it lets go, and takes another after ${HANDOVER_MS / 1000} seconds if it does not.`
+      },
       staleNote: stale ? addonMismatch(status.addonVersion, SERVER_VERSION, status.addonDigest, shippedEditorDigest()) : undefined,
       addonNote: status.connected ? sameCodeNote(status.addonVersion, SERVER_VERSION, status.addonDigest, shippedEditorDigest()) : undefined,
       ...this.breakpointsAtRisk(),
@@ -33137,24 +33188,25 @@ class GodotServer {
     const recorded = running?.process === null ? readRunRecord() : null;
     clearRunRecord((record) => this.couldBeOurs(record.projectPath));
     if (!running || !going) {
-      return;
+      return true;
     }
     running.endedHere = reason;
+    const announced = this.announcedPidOf(running);
     if (running.throughEditor) {
       await this.handleViaBridge("stop_playing", {});
-      return;
+      return await untilGone(null, announced === undefined ? [] : [announced]);
     }
     if (running.process !== null) {
       running.process.kill();
-      return;
+      return await untilGone(running.process, announced === undefined ? [] : [announced]);
     }
     if (running.pid === null) {
-      return;
+      return true;
     }
     if (recorded === null || recorded.pid !== running.pid || !stillTheRecordedRun(recorded)) {
       running.endedHere = null;
       running.log.record("warning", `This run was not ended here: pid ${running.pid} no longer answers as the run that was recorded, so nothing was signalled. If that process is still the game, end it yourself; if it is not, it belongs to something else.`);
-      return;
+      return true;
     }
     const signalled = runningAs(running.pid);
     const described = signalled === null ? "nothing it would name" : `${signalled.kind}: ${signalled.text}`;
@@ -33164,7 +33216,9 @@ class GodotServer {
     } catch {
       landed = false;
     }
+    const gone = await untilGone(null, [running.pid]);
     running.log.record("info", landed ? `gdharness ended pid ${running.pid}, which the operating system described as ${described}.` : `gdharness signalled pid ${running.pid} and it was already gone; the operating system had described it as ${described}.`);
+    return gone;
   }
   spawnGame(godotPath, cmdArgs, env) {
     const child = spawn(godotPath, cmdArgs, { stdio: ["ignore", "pipe", "pipe"], ...env ? { env } : {} });
@@ -33766,7 +33820,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", wasRunning);
+    const gone = await this.endActiveGame("editor_run stop", wasRunning);
     const ended = children === null ? null : endChildrenAmong(children);
     if (wasRunning) {
       for (const pid of new Set([endedPid, announcedPid])) {
@@ -33790,7 +33844,7 @@ class GodotServer {
       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 ? 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)}`,
+      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."}${gone ? "" : ` It had not exited ${STOP_WAIT_MS / 1000} seconds after being told to, so it may still be going: editor_status says whether it is.`} ${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.22",
+  "version": "1.0.23",
   "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",