gdharness 1.1.24 → 1.1.26

package/build/cli.js

@@ -17556,7 +17556,7 @@ var init_tool_definitions = __esm(() => {
           requires: ["projectPath"]
         },
         stop: {
-          summary: "end the run and answer with what it printed last, naming the process ended under endedPid: for a run the editor plays, the number its game announced under, read at the stop rather than remembered, and the operating system hands a freed number to the next process, so it can equal the game before it. A game that started processes of its own keeps them unless andChildren says to end those too. stopped is false, with the number under notSignalled, when that number no longer answers as the process the run was started as and nothing was signalled, and false with the number under stillGoing when what was told to end was still running ten seconds later",
+          summary: "end the run and answer with what it printed last, naming the process ended under endedPid: for a run the editor plays, the number its game announced under, read at the stop rather than remembered, and the operating system hands a freed number to the next process, so it can equal the game before it. A game that started processes of its own keeps them unless andChildren says to end those too. stopped is false, with the number under notSignalled, when that number no longer answers as the process the run was started as and nothing was signalled, the note naming which property it failed on, and false with the number under stillGoing when what was told to end was still running ten seconds later. endedThrough says how the stop ended a run that was going: keeper (the process that started the game ended it through the handle it holds), signal (its pid was signalled once shown to still be the run), or editor (the editor playing it was asked). A start that ends the run before it says how under endedPreviousRunThrough, with the same values, and one that refused to signal that run names the property it failed on under previousRunLeftBecause",
           requires: []
         },
         check: {
@@ -17874,7 +17874,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "runtime_input",
-      description: "Input to the running game: a whole click on a Control or a 3D node named by path or on a control named by the words on it, an item chosen out of a menu, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it.",
+      description: "Input to the running game: a whole click on a Control or a 3D node named by path or on a control named by the words on it, an item chosen out of a menu, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it. On gdharness's own desktop, where a windowed run goes, Windows refuses to say where the pointer is: the pointer ops answer with pointer_note there, because get_mouse_position() on the root window, and the mouse positions derived from it, read a meaningless position, while what reads the event itself (the control under it, hover, tooltips, input handlers) gets the injected position.",
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
         pid: RUNNING_PID,
@@ -17914,7 +17914,7 @@ var init_tool_definitions = __esm(() => {
           type: "string",
           ops: ["text", "choose"],
           blank: true,
-          description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says as drawn, which in a game with translations is the translation; the key it holds is matched after that.'
+          description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says as drawn, which in a game with translations is the translation; the key it holds is matched after that. An item whose whole words are these comes first; otherwise the words match as says does anywhere, a plain word as part of the item, a glob, or alternatives split at |, enabled items ahead of disabled ones, and several matching equally are refused with each listed.'
         },
         replace: {
           type: "boolean",
@@ -39767,7 +39767,7 @@ function stopVerdict(stop) {
     return {
       stopped: false,
       notSignalled: stop.endedPid,
-      note: `Nothing was ended: pid ${stop.endedPid ?? "unknown"} no longer answers as the process this run was started as (its engine, its project and when it started), so it was not signalled. If that process is still the game, end it yourself, for instance with runtime_invoke calling get_tree().quit() when the game has the runtime addon; if it is not, it belongs to something else.`,
+      note: `Nothing was ended: pid ${stop.endedPid ?? "unknown"} no longer answers as the process this run was started as (${stop.notEndedBecause ?? "its engine, its project and when it started"}), so it was not signalled. If that process is still the game, end it yourself, for instance with runtime_invoke calling get_tree().quit() when the game has the runtime addon; if it is not, it belongs to something else.`,
       withChildren: false
     };
   }
@@ -39788,6 +39788,15 @@ function stopVerdict(stop) {
     withChildren: true
   };
 }
+function previousRunHow(ended) {
+  if (ended === null) {
+    return {};
+  }
+  return {
+    ...ended.through === undefined || ended.ending === "refused" ? {} : { endedPreviousRunThrough: ended.through },
+    ...ended.ending === "refused" && ended.notEndedBecause !== undefined ? { previousRunLeftBecause: ended.notEndedBecause } : {}
+  };
+}
 function endedPreviousRun(ended) {
   if (ended?.ending !== "gone") {
     return;
@@ -42512,9 +42521,12 @@ class GodotServer {
     if (before !== null && await this.runStillGoing(before)) {
       this.logDebug("Ending the running game before starting another");
       const endingFrom = Date.now();
+      const ending = await this.endActiveGame("editor_run start, which ends the run that was going before it starts another", true);
       ended = {
         pid: before.pid ?? this.announcedPidOf(before) ?? null,
-        ending: await this.endActiveGame("editor_run start, which ends the run that was going before it starts another", true)
+        ending,
+        ...before.endedThrough === undefined ? {} : { through: before.endedThrough },
+        ...before.notEndedBecause === undefined ? {} : { notEndedBecause: before.notEndedBecause }
       };
       this.logDebug(`The running game was ${ended.ending} after ${Date.now() - endingFrom}ms`);
     }
@@ -42562,6 +42574,7 @@ class GodotServer {
       savesNote: asked.value.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       endedPreviousRun: endedPreviousRun(ended),
       previousRunLeft: previousRunLeft(ended),
+      ...previousRunHow(ended),
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs, given.value.length > 0),
       message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}${endedForThis}${alsoRunning}`
     });
@@ -42714,6 +42727,7 @@ class GodotServer {
       debugPort: readNumber(playAnswer, "debugPort"),
       endedPreviousRun: endedPreviousRun(ended),
       previousRunLeft: previousRunLeft(ended),
+      ...previousRunHow(ended),
       breakpoints: breakpoints.applied.length === 0 ? undefined : this.breakpointsAsProjectSpells(projectPath, breakpoints.applied),
       breakpointsRefused: breakpoints.refused.length === 0 ? undefined : breakpoints.refused.map((one) => ({
         scriptPath: projectSpelling(projectPath, one.scriptPath),
@@ -42868,6 +42882,7 @@ class GodotServer {
         running.log.record("warning", `This run was not ended here: the editor could not be asked to stop it (${asked.content[0]?.text ?? "no reason given"}).`);
         return "unreached";
       }
+      running.endedThrough = "editor";
       if (announced === undefined) {
         return await this.untilTheEditorStopsPlaying() ? "gone" : "lingering";
       }
@@ -42896,6 +42911,7 @@ class GodotServer {
     if (why !== null) {
       clearTheRecord();
       running.endedHere = null;
+      running.notEndedBecause = why;
       running.log.record("warning", `This run was not ended here: pid ${running.pid} no longer answers as the process the run was started as (${why}), so nothing was signalled. If that process is still the game, end it yourself; if it is not, it belongs to something else.`);
       return "refused";
     }
@@ -42920,6 +42936,9 @@ class GodotServer {
       running.exitCode = null;
       running.exitSignal = "SIGTERM";
     }
+    if (landed) {
+      running.endedThrough = "signal";
+    }
     clearTheRecord();
     running.log.record(gone ? "info" : "warning", declined !== null ? `gdharness could not signal pid ${running.pid}: the operating system refused it (${declined}). It had described that process as ${described}.` : !gone ? `gdharness signalled pid ${running.pid}, which the operating system described as ${described}, and it was still running ${STOP_WAIT_MS / 1000} seconds later.` : 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 ? "gone" : "lingering";
@@ -42930,6 +42949,9 @@ class GodotServer {
       this.logDebug(`The keeper of pid ${pid} could not be asked to end it (${asked.unreached})`);
       return null;
     }
+    if (asked === "signalled") {
+      run.endedThrough = "keeper";
+    }
     const gone = await untilGone([pid]);
     if (gone) {
       await this.untilTheExitIsRecorded(run);
@@ -43655,11 +43677,13 @@ class GodotServer {
       endedPid,
       throughEditor: stopped.throughEditor,
       exitSignal: stopped.exitSignal,
-      clean: cleanVerdict(stopped)
+      clean: cleanVerdict(stopped),
+      ...stopped.notEndedBecause === undefined ? {} : { notEndedBecause: stopped.notEndedBecause }
     });
     return this.jsonTextResponse({
       stopped: verdict.stopped,
       through: stopped.throughEditor ? "editor" : "gdharness",
+      endedThrough: wasRunning ? stopped.endedThrough : undefined,
       endedPid: verdict.endedPid,
       notSignalled: verdict.notSignalled,
       stillGoing: verdict.stillGoing,
@@ -43724,6 +43748,7 @@ class GodotServer {
       through: "gdharness",
       endedPid: gone ? pid : undefined,
       stillGoing: gone ? undefined : pid,
+      ...landed ? { endedThrough: "signal" } : {},
       ...childrenFields(ended),
       exitedBeforeStop: !landed,
       note: `${!gone ? `pid ${pid} was told to end and was still running ${STOP_WAIT_MS / 1000} seconds later, so it has not stopped: a game of this project that no server here was holding,` : landed ? `pid ${pid} was ended: a game of this project that no server here was holding,` : `pid ${pid} had already gone when it was signalled: a game of this project that no server here was holding,`} identified by its announcement and by its command line, ${read.executable} run with --path ${read.projectPath ?? ""}. Nothing here read what it printed or holds its exit code, so neither is in this answer.${gone ? "" : " editor_status says when it has gone."} ${aboutTheChildren(ended, false)}`

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

@@ -21,6 +21,10 @@ const TO_SMALL: int = 32
 ## reason a control is out of reach. Only worth telling somebody when it is what they have.
 const HEADLESS_VIEWPORT: Vector2 = Vector2(64, 64)
 
+## Set, to the desktop's name, for a process gdharness started on a desktop of its own and for
+## everything that process starts. Kept in step with `DESKTOP_VARIABLE` in src/desktop.ts.
+const DESKTOP_VARIABLE: String = "GDHARNESS_DESKTOP"
+
 var _host: Node
 var _values: Values
 
@@ -45,6 +49,28 @@ func _init(host: Node, values: Values) -> void:
 	_values = values
 
 
+## [param answer], saying what a desktop of gdharness's own does to the game's own reading of the
+## pointer when the game is on one.
+##
+## For the root window the engine asks Windows where the pointer is, and GetCursorPos refuses a
+## process on a desktop that is not in use: measured on one of gdharness's own, it answered false
+## with access denied and left the point unwritten. The engine does not check, so a game driven
+## there read get_mouse_position() as x 836852416 after a motion to 1310, 314. Nothing here can
+## put a pointer on that desktop: Windows moves one only on the desktop in use, and making this one
+## that would take the screen. What reads the injected event is right, tooltips included, since the
+## engine places a tooltip from the motion that reached the control.
+static func _pointer_noted(answer: Dictionary) -> Dictionary:
+	if OS.get_environment(DESKTOP_VARIABLE) != "":
+		answer["pointer_note"] = (
+			"This game is on gdharness's own desktop, where Windows refuses to say where the"
+			+ " pointer is, so get_mouse_position() on the root window, and get_global_mouse_position()"
+			+ " and get_local_mouse_position() on what is drawn there, read a meaningless position"
+			+ " rather than where this put it. What reads the event itself gets this position: the"
+			+ " control under the pointer, its hover and tooltip, and the game's input handlers."
+		)
+	return answer
+
+
 ## The movement a pointer arriving at [param position] carries, which is the distance from where
 ## the last injected event put it, and none at all for the first. The arrival is recorded, with how
 ## long it took: at least a frame, since two motions sent in one frame did not cross the screen in
@@ -238,15 +264,17 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 		Input.parse_input_event(_button(position, button, false, false))
 		await _host.get_tree().process_frame
 
-	return {
-		"type": "input_injected",
-		"input_type": "mouse_click",
-		"position": [position.x, position.y],
-		"button": button,
-		"pressed": held and not whole,
-		"whole": whole,
-		"double": double
-	}
+	return _pointer_noted(
+		{
+			"type": "input_injected",
+			"input_type": "mouse_click",
+			"position": [position.x, position.y],
+			"button": button,
+			"pressed": held and not whole,
+			"whole": whole,
+			"double": double
+		}
+	)
 
 
 ## Moves the pointer to a position, with the movement the event carries taken from where the
@@ -275,12 +303,14 @@ func inject_mouse_motion(params: Dictionary) -> Dictionary:
 
 	Input.parse_input_event(_motion(position, relative))
 
-	return {
-		"type": "input_injected",
-		"input_type": "mouse_motion",
-		"position": [position.x, position.y],
-		"relative": [relative.x, relative.y]
-	}
+	return _pointer_noted(
+		{
+			"type": "input_injected",
+			"input_type": "mouse_motion",
+			"position": [position.x, position.y],
+			"relative": [relative.x, relative.y]
+		}
+	)
 
 
 ## Whether [param centre] is somewhere a click can reach it: inside the viewport, and inside every
@@ -289,11 +319,11 @@ static func _in_sight(control: Control, viewport: Viewport, centre: Vector2) ->
 	return viewport.get_visible_rect().has_point(centre) and _clipped_by(control, centre) == null
 
 
-## The ScrollContainer between [param control] and the root that clips [param centre] away from it,
-## or null when none does.
+## The ScrollContainer between [param control] and its viewport that clips [param centre] away from
+## it, or null when none does. Not past the viewport: one holding a dialog is in another space.
 static func _clipped_by(control: Control, centre: Vector2) -> ScrollContainer:
 	var walking: Node = control.get_parent()
-	while walking != null:
+	while walking != null and not (walking is Viewport):
 		var holder: ScrollContainer = walking as ScrollContainer
 		# Carried into the same space the centre is in, which is the canvas rather than the
 		# container's own: the two are only the same while nothing above it is transformed.
@@ -312,11 +342,12 @@ static func _clipped_by(control: Control, centre: Vector2) -> ScrollContainer:
 ## next layout pass rather than inside the call, and the next one out works out where the control is
 ## from where it is drawn, so asked in the same frame it scrolled to where the control had been.
 ## Moved means a scroll value changed: a container asked to show what it already shows moves
-## nothing, and answering true for it said the view had moved when it had not.
+## nothing, and answering true for it said the view had moved when it had not. Only the containers in
+## the control's own viewport: one holding a dialog scrolls the page behind it, not the dialog.
 func _scroll_into_view(control: Control) -> bool:
 	var moved: bool = false
 	var walking: Variant = control.get_parent()
-	while walking != null:
+	while walking != null and not (walking is Viewport):
 		var step: Node = walking
 		var holder: ScrollContainer = step as ScrollContainer
 		if holder != null:
@@ -466,7 +497,7 @@ func click(params: Dictionary) -> Dictionary:
 	}
 	if found != null:
 		answer["found"] = found
-	return answer
+	return _pointer_noted(answer)
 
 
 ## Why [param control] would take no click a player gave it, or "" when it would.
@@ -636,19 +667,21 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 	_press_button(arriving, _button(position, button, false, false))
 	await _host.get_tree().process_frame
 
-	return {
-		"type": "clicked",
-		"path": node_path,
-		"position": _values.serialize(position),
-		"button": button,
-		"double": double,
-		"hovered": hovered_path,
-		# The interface did not take it, so it reached the game's own input. As close to "it
-		# landed" as anything outside the game can get, and said in the same word the Control
-		# click says it in.
-		"landed": through["landed"],
-		"camera": found["camera"],
-	}
+	return _pointer_noted(
+		{
+			"type": "clicked",
+			"path": node_path,
+			"position": _values.serialize(position),
+			"button": button,
+			"double": double,
+			"hovered": hovered_path,
+			# The interface did not take it, so it reached the game's own input. As close to "it
+			# landed" as anything outside the game can get, and said in the same word the Control
+			# click says it in.
+			"landed": through["landed"],
+			"camera": found["camera"],
+		}
+	)
 
 
 ## Whether a pointer on its way out through [param out], the steps [method Screen.steps_out]

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

@@ -4,6 +4,7 @@ extends RefCounted
 ## where it is in the list.
 
 const Read = preload("reading.gd")
+const Says = preload("runtime_says.gd")
 const Words = preload("runtime_words.gd")
 
 
@@ -20,20 +21,28 @@ static func menu_of(node: Node) -> PopupMenu:
 	return null
 
 
-## Which item was asked for: `text`, matched exactly and then case-insensitively, or `index`.
-## Minus one when neither names one that is there.
+## The items asked for, best first: the one at `index`; else the one whose whole words are `text`,
+## exactly and then case-insensitively; else every item `text` matches by the rules `says` has, a
+## plain word as a contains, a glob, and alternatives split at `|`, the enabled ones when any are.
+## Empty when nothing matches, and more than one when several match equally well, which the caller
+## refuses rather than guesses between.
+##
+## By the same rules as `says` because a caller who has learnt them from a click, a find and a wait
+## writes the same pattern here: "Leave*" was refused against a menu holding "Leave the hall", and
+## the item had to be written out in full on a second call. The whole words still come first, so an
+## item named in full is chosen over another whose words contain it.
 ##
 ## `text` is matched against the words the item shows before the ones it holds. In a game with
 ## translations they differ, and the shown ones are what a caller has read off the screen: an item
 ## held as `ACT_ENGAGE` and shown as "Hire" refused "Hire" and listed the keys. The held words
 ## still count after them, for a caller that has the key from the source.
-static func wanted_item(menu: PopupMenu, params: Dictionary) -> int:
+static func wanted_items(menu: PopupMenu, params: Dictionary) -> Array[int]:
 	if params.has("index"):
 		var asked: int = Read.as_int(params.get("index", -1), -1)
-		return asked if asked >= 0 and asked < menu.get_item_count() else -1
+		return _items([asked] if asked >= 0 and asked < menu.get_item_count() else [])
 	var wanted: String = str(params.get("text", ""))
 	if wanted.is_empty():
-		return -1
+		return _items([])
 	# The items before the separators, because a heading can carry the same words as an item under
 	# it, and finding the heading first refused the choice the caller meant. A separator is still
 	# looked for after, so a heading asked for by name is refused as one rather than as missing.
@@ -50,11 +59,33 @@ static func wanted_item(menu: PopupMenu, params: Dictionary) -> int:
 	for words: Array[String] in [shown, held]:
 		for at: int in words.size():
 			if words[at] == wanted:
-				return order[at]
+				return _items([order[at]])
 		for at: int in words.size():
 			if words[at].nocasecmp_to(wanted) == 0:
-				return order[at]
-	return -1
+				return _items([order[at]])
+	# Separators are left out here: a heading is refused when named in full, and a pattern that
+	# matched one beside the item it heads would tie the two.
+	for words: Array[String] in [shown, held]:
+		var matched: Array[int] = []
+		var enabled: Array[int] = []
+		for at: int in words.size():
+			var index: int = order[at]
+			if menu.is_item_separator(index) or not Says.matches(words[at], wanted):
+				continue
+			matched.append(index)
+			if not menu.is_item_disabled(index):
+				enabled.append(index)
+		if not matched.is_empty():
+			return enabled if not enabled.is_empty() else matched
+	return _items([])
+
+
+## [param indices] as a list of item numbers: a literal list is untyped, and handed back where a
+## typed one is declared it is refused when the call is made, not when the script is read.
+static func _items(indices: Array) -> Array[int]:
+	var typed: Array[int] = []
+	typed.assign(indices)
+	return typed
 
 
 ## What the menu shows, for a refusal that names the choices rather than the miss: a titled

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

@@ -216,13 +216,21 @@ static func can_read(holder: Variant, named: String) -> bool:
 ## A step is text, and a map is keyed by whatever the game put in it: text, a StringName, or a
 ## number, which a map of units by id is. Keyed by 3, "3" is not a key of it, measured on 4.7.2, so a
 ## step that reads as a number is tried as one after the two spellings of text.
+##
+## A map typed by its key is asked only in that type. It checks every key it is asked about and
+## reports an engine error for one of another type, so a step into a map typed by an enum read the
+## right entry and left four errors in the game's log for each of the two walks, and the run was
+## counted as unclean for a read.
 static func _key_in(map: Dictionary, named: String) -> Array:
 	var spellings: Array = [named, StringName(named)]
 	if named.is_valid_int():
 		spellings.append(int(named))
 	if named.is_valid_float():
 		spellings.append(float(named))
+	var typed: int = map.get_typed_key_builtin() if map.is_typed_key() else TYPE_NIL
 	for key: Variant in spellings:
+		if typed != TYPE_NIL and typeof(key) != typed:
+			continue
 		if map.has(key):
 			return [key]
 	return []

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

@@ -229,7 +229,7 @@ static func _covered_note(covered: int, cover: Node) -> String:
 ## its words means.
 static func _pressed_through(control: Control) -> Control:
 	var walk: Node = control
-	while walk != null:
+	while walk != null and not (walk is Viewport):
 		if walk is BaseButton:
 			var pressed: BaseButton = walk
 			return pressed
@@ -376,7 +376,7 @@ static func _where_it_lands(target: Control, point: Vector2) -> Vector2:
 	var half: Vector2 = (drawn * Rect2(Vector2.ZERO, target.size)).size * 0.5
 	var landed: Vector2 = point
 	var walk: Node = target.get_parent()
-	while walk != null:
+	while walk != null and not (walk is Viewport):
 		var holder: ScrollContainer = walk as ScrollContainer
 		if holder != null:
 			var shown: Rect2 = holder.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, holder.size)
@@ -405,9 +405,13 @@ static func _off_screen(target: Control) -> bool:
 
 
 ## Whether a container clipping what it holds cuts [param point] off from [param control].
+##
+## Only up to the viewport [param control] is in. A dialog is a window, and the containers the game
+## added it under are in another space: judged against a clipping one of those, every button of a
+## confirmation was refused as off the screen while it sat in plain view.
 static func _clipped_away(control: Control, point: Vector2) -> bool:
 	var walk: Node = control.get_parent()
-	while walk != null:
+	while walk != null and not (walk is Viewport):
 		var holder: Control = walk as Control
 		if holder != null and holder.clip_contents and not _holds(holder, point):
 			return true

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

@@ -261,11 +261,24 @@ func choose(params: Dictionary) -> Dictionary:
 	var opened: bool = Menus.open_the_menu(node, menu)
 	await _host.get_tree().process_frame
 
-	var index: int = Menus.wanted_item(menu, params)
+	var found: Array[int] = Menus.wanted_items(menu, params)
+	if found.size() > 1:
+		await _shut(menu, opened)
+		var tied: Array[String] = []
+		for at: int in found:
+			tied.append("%d: %s" % [at, Words.item_says(menu, at)])
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s has %d items that say %s, so nothing was chosen: %s. Name one by its whole text or by index"
+				% [node_path, found.size(), JSON.stringify(str(params.get("text", ""))), ", ".join(tied)]
+			)
+		}
+	var index: int = found[0] if found.size() == 1 else -1
 	var refused: String = _not_a_choice(node_path, menu, index)
 	if not refused.is_empty():
-		if opened and is_instance_valid(menu):
-			menu.hide()
+		await _shut(menu, opened)
 		return {"type": "error", "message": refused}
 
 	# Read before the press, because the press can take the menu away: a game that rebuilds its
@@ -298,8 +311,7 @@ func choose(params: Dictionary) -> Dictionary:
 		menu.index_pressed.disconnect(hear)
 
 	if not fired.has(index):
-		if opened and is_instance_valid(menu) and menu.visible:
-			menu.hide()
+		await _shut(menu, opened)
 		return {
 			"type": "error",
 			"message":
@@ -322,6 +334,16 @@ func choose(params: Dictionary) -> Dictionary:
 	return answer
 
 
+## Shuts a menu this call opened, and lets the frame pass in which the engine finishes shutting it.
+## A choice asked for in the frame a refusal shut the menu found it half shut, and the press it sent
+## went nowhere: measured on 4.7.2, a MenuButton refused and at once asked again answered that the
+## menu did not take the item.
+func _shut(menu: PopupMenu, opened: bool) -> void:
+	if opened and is_instance_valid(menu) and menu.visible:
+		menu.hide()
+		await _host.get_tree().process_frame
+
+
 ## Why item [param index] of [param menu] is not something to choose, or "" when it is.
 static func _not_a_choice(node_path: String, menu: PopupMenu, index: int) -> String:
 	if index < 0:

package/build/index.js

@@ -31540,7 +31540,7 @@ var TOOL_SPECS = [
         requires: ["projectPath"]
       },
       stop: {
-        summary: "end the run and answer with what it printed last, naming the process ended under endedPid: for a run the editor plays, the number its game announced under, read at the stop rather than remembered, and the operating system hands a freed number to the next process, so it can equal the game before it. A game that started processes of its own keeps them unless andChildren says to end those too. stopped is false, with the number under notSignalled, when that number no longer answers as the process the run was started as and nothing was signalled, and false with the number under stillGoing when what was told to end was still running ten seconds later",
+        summary: "end the run and answer with what it printed last, naming the process ended under endedPid: for a run the editor plays, the number its game announced under, read at the stop rather than remembered, and the operating system hands a freed number to the next process, so it can equal the game before it. A game that started processes of its own keeps them unless andChildren says to end those too. stopped is false, with the number under notSignalled, when that number no longer answers as the process the run was started as and nothing was signalled, the note naming which property it failed on, and false with the number under stillGoing when what was told to end was still running ten seconds later. endedThrough says how the stop ended a run that was going: keeper (the process that started the game ended it through the handle it holds), signal (its pid was signalled once shown to still be the run), or editor (the editor playing it was asked). A start that ends the run before it says how under endedPreviousRunThrough, with the same values, and one that refused to signal that run names the property it failed on under previousRunLeftBecause",
         requires: []
       },
       check: {
@@ -31858,7 +31858,7 @@ var TOOL_SPECS = [
   },
   {
     name: "runtime_input",
-    description: "Input to the running game: a whole click on a Control or a 3D node named by path or on a control named by the words on it, an item chosen out of a menu, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it.",
+    description: "Input to the running game: a whole click on a Control or a 3D node named by path or on a control named by the words on it, an item chosen out of a menu, typing into whatever has the focus, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it. On gdharness's own desktop, where a windowed run goes, Windows refuses to say where the pointer is: the pointer ops answer with pointer_note there, because get_mouse_position() on the root window, and the mouse positions derived from it, read a meaningless position, while what reads the event itself (the control under it, hover, tooltips, input handlers) gets the injected position.",
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
       pid: RUNNING_PID,
@@ -31898,7 +31898,7 @@ var TOOL_SPECS = [
         type: "string",
         ops: ["text", "choose"],
         blank: true,
-        description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says as drawn, which in a game with translations is the translation; the key it holds is matched after that.'
+        description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says as drawn, which in a game with translations is the translation; the key it holds is matched after that. An item whose whole words are these comes first; otherwise the words match as says does anywhere, a plain word as part of the item, a glob, or alternatives split at |, enabled items ahead of disabled ones, and several matching equally are refused with each listed.'
       },
       replace: {
         type: "boolean",
@@ -32287,7 +32287,7 @@ function stopVerdict(stop) {
     return {
       stopped: false,
       notSignalled: stop.endedPid,
-      note: `Nothing was ended: pid ${stop.endedPid ?? "unknown"} no longer answers as the process this run was started as (its engine, its project and when it started), so it was not signalled. If that process is still the game, end it yourself, for instance with runtime_invoke calling get_tree().quit() when the game has the runtime addon; if it is not, it belongs to something else.`,
+      note: `Nothing was ended: pid ${stop.endedPid ?? "unknown"} no longer answers as the process this run was started as (${stop.notEndedBecause ?? "its engine, its project and when it started"}), so it was not signalled. If that process is still the game, end it yourself, for instance with runtime_invoke calling get_tree().quit() when the game has the runtime addon; if it is not, it belongs to something else.`,
       withChildren: false
     };
   }
@@ -32308,6 +32308,15 @@ function stopVerdict(stop) {
     withChildren: true
   };
 }
+function previousRunHow(ended) {
+  if (ended === null) {
+    return {};
+  }
+  return {
+    ...ended.through === undefined || ended.ending === "refused" ? {} : { endedPreviousRunThrough: ended.through },
+    ...ended.ending === "refused" && ended.notEndedBecause !== undefined ? { previousRunLeftBecause: ended.notEndedBecause } : {}
+  };
+}
 function endedPreviousRun(ended) {
   if (ended?.ending !== "gone") {
     return;
@@ -35092,9 +35101,12 @@ class GodotServer {
     if (before !== null && await this.runStillGoing(before)) {
       this.logDebug("Ending the running game before starting another");
       const endingFrom = Date.now();
+      const ending = await this.endActiveGame("editor_run start, which ends the run that was going before it starts another", true);
       ended = {
         pid: before.pid ?? this.announcedPidOf(before) ?? null,
-        ending: await this.endActiveGame("editor_run start, which ends the run that was going before it starts another", true)
+        ending,
+        ...before.endedThrough === undefined ? {} : { through: before.endedThrough },
+        ...before.notEndedBecause === undefined ? {} : { notEndedBecause: before.notEndedBecause }
       };
       this.logDebug(`The running game was ${ended.ending} after ${Date.now() - endingFrom}ms`);
     }
@@ -35142,6 +35154,7 @@ class GodotServer {
       savesNote: asked.value.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       endedPreviousRun: endedPreviousRun(ended),
       previousRunLeft: previousRunLeft(ended),
+      ...previousRunHow(ended),
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs, given.value.length > 0),
       message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}${endedForThis}${alsoRunning}`
     });
@@ -35294,6 +35307,7 @@ class GodotServer {
       debugPort: readNumber(playAnswer, "debugPort"),
       endedPreviousRun: endedPreviousRun(ended),
       previousRunLeft: previousRunLeft(ended),
+      ...previousRunHow(ended),
       breakpoints: breakpoints.applied.length === 0 ? undefined : this.breakpointsAsProjectSpells(projectPath, breakpoints.applied),
       breakpointsRefused: breakpoints.refused.length === 0 ? undefined : breakpoints.refused.map((one) => ({
         scriptPath: projectSpelling(projectPath, one.scriptPath),
@@ -35448,6 +35462,7 @@ class GodotServer {
         running.log.record("warning", `This run was not ended here: the editor could not be asked to stop it (${asked.content[0]?.text ?? "no reason given"}).`);
         return "unreached";
       }
+      running.endedThrough = "editor";
       if (announced === undefined) {
         return await this.untilTheEditorStopsPlaying() ? "gone" : "lingering";
       }
@@ -35476,6 +35491,7 @@ class GodotServer {
     if (why !== null) {
       clearTheRecord();
       running.endedHere = null;
+      running.notEndedBecause = why;
       running.log.record("warning", `This run was not ended here: pid ${running.pid} no longer answers as the process the run was started as (${why}), so nothing was signalled. If that process is still the game, end it yourself; if it is not, it belongs to something else.`);
       return "refused";
     }
@@ -35500,6 +35516,9 @@ class GodotServer {
       running.exitCode = null;
       running.exitSignal = "SIGTERM";
     }
+    if (landed) {
+      running.endedThrough = "signal";
+    }
     clearTheRecord();
     running.log.record(gone ? "info" : "warning", declined !== null ? `gdharness could not signal pid ${running.pid}: the operating system refused it (${declined}). It had described that process as ${described}.` : !gone ? `gdharness signalled pid ${running.pid}, which the operating system described as ${described}, and it was still running ${STOP_WAIT_MS / 1000} seconds later.` : 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 ? "gone" : "lingering";
@@ -35510,6 +35529,9 @@ class GodotServer {
       this.logDebug(`The keeper of pid ${pid} could not be asked to end it (${asked.unreached})`);
       return null;
     }
+    if (asked === "signalled") {
+      run.endedThrough = "keeper";
+    }
     const gone = await untilGone([pid]);
     if (gone) {
       await this.untilTheExitIsRecorded(run);
@@ -36235,11 +36257,13 @@ class GodotServer {
       endedPid,
       throughEditor: stopped.throughEditor,
       exitSignal: stopped.exitSignal,
-      clean: cleanVerdict(stopped)
+      clean: cleanVerdict(stopped),
+      ...stopped.notEndedBecause === undefined ? {} : { notEndedBecause: stopped.notEndedBecause }
     });
     return this.jsonTextResponse({
       stopped: verdict.stopped,
       through: stopped.throughEditor ? "editor" : "gdharness",
+      endedThrough: wasRunning ? stopped.endedThrough : undefined,
       endedPid: verdict.endedPid,
       notSignalled: verdict.notSignalled,
       stillGoing: verdict.stillGoing,
@@ -36304,6 +36328,7 @@ class GodotServer {
       through: "gdharness",
       endedPid: gone ? pid : undefined,
       stillGoing: gone ? undefined : pid,
+      ...landed ? { endedThrough: "signal" } : {},
       ...childrenFields(ended),
       exitedBeforeStop: !landed,
       note: `${!gone ? `pid ${pid} was told to end and was still running ${STOP_WAIT_MS / 1000} seconds later, so it has not stopped: a game of this project that no server here was holding,` : landed ? `pid ${pid} was ended: a game of this project that no server here was holding,` : `pid ${pid} had already gone when it was signalled: a game of this project that no server here was holding,`} identified by its announcement and by its command line, ${read.executable} run with --path ${read.projectPath ?? ""}. Nothing here read what it printed or holds its exit code, so neither is in this answer.${gone ? "" : " editor_status says when it has gone."} ${aboutTheChildren(ended, false)}`

package/build/keeper.js

@@ -10,6 +10,7 @@ import { setTimeout as delay } from "node:timers/promises";
 // src/desktop.ts
 import { createHash } from "node:crypto";
 import { writeFileSync } from "node:fs";
+var DESKTOP_VARIABLE = "GDHARNESS_DESKTOP";
 var SOURCE = `using System;
 using System.ComponentModel;
 using System.IO;
@@ -565,7 +566,8 @@ async function startThroughHelper(spec, output, stopFile) {
       error: errorFile,
       stop: stopFile
     });
-    const started = await startDirectly({ ...spec, command: wrapper.command, args: wrapper.args }, output, true, false, "ignore");
+    const envChanges = spec.desktop === undefined ? spec.envChanges : { ...spec.envChanges, [DESKTOP_VARIABLE]: spec.desktop };
+    const started = await startDirectly({ ...spec, command: wrapper.command, args: wrapper.args, envChanges }, output, true, false, "ignore");
     if ("error" in started) {
       return started;
     }

package/package.json

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