breakpoint-mcp 1.29.0 → 1.72.7

package/README.md

@@ -3,7 +3,7 @@
 The MCP **host** for [Breakpoint MCP](https://github.com/jlivingston-Cipher/godot-breakpoint-mcp) —
 a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
 Godot game engine to AI coding assistants across four planes: headless CLI, the live
-editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **289 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **291 tools
 + 6 MCP resources**, built against the stable `@modelcontextprotocol/sdk` 1.x API.
 Developed and tested with **Claude**; because MCP is an open protocol, other clients can
 connect too (currently untested — reports welcome).

package/addon/breakpoint_mcp/operations.gd

@@ -7,7 +7,7 @@ extends RefCounted
 ## wrapped in the EditorUndoRedoManager so a human can Ctrl-Z anything the assistant did.
 
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
-const ADDON_VERSION := "1.9.2"
+const ADDON_VERSION := "1.9.8"
 
 var _plugin: EditorPlugin
 
@@ -317,6 +317,10 @@ func dispatch(method: String, params: Dictionary) -> Dictionary:
 			return _ok(_selection_get())
 		"selection.set":
 			return _selection_set(params)
+		"main_screen.get":
+			return _main_screen_get()
+		"main_screen.set":
+			return _main_screen_set(params)
 		"classdb.get_class":
 			return _classdb_get_class(params)
 		"classdb.reference":
@@ -683,6 +687,119 @@ func _selection_set(params: Dictionary) -> Dictionary:
 	return _ok({"selection": applied})
 
 
+# ------------------------------------------------- main-screen tab ----------
+# Godot keeps the INACTIVE main-screen tab's viewport alive at its minimum size,
+# so screenshot_editor on the wrong tab "succeeds" and returns a 2x2 placeholder.
+# The host has guarded that since #139 by rejecting anything under 8px, but the
+# error could only tell the caller to switch tabs by hand -- there was no tool to
+# do it with, which is a dead end for the assistant this addon exists to serve.
+#
+# Tab names are NOT hardcoded anywhere here. The engine reports them, they differ
+# between versions (Godot 4.6 added "Game"), and a caller that asks for one that
+# does not exist gets the live list back in the error. `_main_screen_set` matches
+# case-insensitively so "2d" works as well as the engine's own "2D".
+#
+# Both EditorInterface methods are reached through call()/has_method rather than
+# literally, for the reason spelled out on _scene_close: a literal call to a
+# method the running engine lacks fails at PARSE time and takes the WHOLE addon
+# down on that version, not just this tool. get_editor_main_screen is 4.1+ and
+# set_main_screen_editor is 4.0+, so both should be present across this repo's
+# 4.3/4.5/4.7 matrix -- the guard is here so that being wrong about that degrades
+# to one tool reporting `unsupported` instead of the plugin failing to load.
+func _main_screen_root() -> Node:
+	if not EditorInterface.has_method("get_editor_main_screen"):
+		return null
+	return EditorInterface.call("get_editor_main_screen")
+
+
+# The container's children do NOT carry the tab names. Measured on 4.7, the five
+# children are named @CanvasItemEditor@10149, @Node3DEditor@10909, two
+# @WindowWrapper@... and @EditorAssetLibrary@... -- Godot's auto-generated node
+# names, which `set_main_screen_editor` does not accept. The tab name it DOES
+# accept ("2D", "3D", "Script", "Game", "AssetLib") is the EditorPlugin's name,
+# which is not on the control. So the label is derived from the control's class:
+const _MAIN_SCREEN_LABELS := {
+	"CanvasItemEditor": "2D",
+	"Node3DEditor": "3D",
+	"ScriptEditor": "Script",
+	"GameView": "Game",
+	"EditorAssetLibrary": "AssetLib",
+}
+
+
+func _main_screen_label(c: Node) -> String:
+	var cls := c.get_class()
+	if _MAIN_SCREEN_LABELS.has(cls):
+		return String(_MAIN_SCREEN_LABELS[cls])
+	# Script and Game are wrapped in a WindowWrapper (the "make floating" feature),
+	# so the identifying class is one level down. Measured: ['Window','ScriptEditor']
+	# and ['Window','GameView'].
+	for k in c.get_children():
+		var kcls := k.get_class()
+		if _MAIN_SCREEN_LABELS.has(kcls):
+			return String(_MAIN_SCREEN_LABELS[kcls])
+	# A third-party EditorPlugin main screen, or a future built-in this map predates.
+	# Its real tab name is the plugin's get_plugin_name(), which is not reachable from
+	# here -- so report something honest rather than inventing one. set_main_screen_editor
+	# is still given the caller's string verbatim, so such a tab remains switchable by
+	# name even though this list cannot spell it.
+	var nm := String(c.name)
+	return cls if nm.begins_with("@") else nm
+
+
+func _main_screen_state() -> Dictionary:
+	# The active tab is the one visible child; the editor shows exactly one at a time.
+	# Reported as null rather than guessed if somehow none is visible.
+	var mains := _main_screen_root()
+	var available: Array = []
+	var active: Variant = null
+	if mains == null:
+		return {"active": null, "available": available}
+	for c in mains.get_children():
+		var label := _main_screen_label(c)
+		available.append(label)
+		if c is Control and (c as Control).visible:
+			active = label
+	return {"active": active, "available": available}
+
+
+func _main_screen_get() -> Dictionary:
+	if _main_screen_root() == null:
+		return _err("unsupported", "main_screen_get requires EditorInterface.get_editor_main_screen (Godot 4.1+)")
+	return _ok(_main_screen_state())
+
+
+func _main_screen_set(params: Dictionary) -> Dictionary:
+	if not EditorInterface.has_method("set_main_screen_editor"):
+		return _err("unsupported", "main_screen_set requires EditorInterface.set_main_screen_editor")
+	var state := _main_screen_state()
+	var available: Array = state.get("available", [])
+	var want := String(params.get("name", ""))
+	if want == "":
+		return _err("bad_params", "name is required (one of: %s)" % ", ".join(PackedStringArray(available)))
+	# Resolve case-insensitively against the derived labels so "2d" works, but fall
+	# back to the caller's string verbatim when nothing matches. The label map cannot
+	# spell a third-party plugin's main screen (see _main_screen_label), and the
+	# engine's own lookup can -- so a name this addon does not recognise is still
+	# WORTH TRYING rather than rejected here.
+	var target := want
+	for nm in available:
+		if String(nm).to_lower() == want.to_lower():
+			target = String(nm)
+			break
+	EditorInterface.call("set_main_screen_editor", target)
+	# Verify by READ-BACK, not by trusting the call. set_main_screen_editor returns
+	# nothing and silently does nothing for a name it does not know, so this is the
+	# only way to tell a successful switch from a typo -- and it is what makes the
+	# verbatim fallback above safe. It also means the caller's next move (usually a
+	# screenshot) acts on what the editor actually did.
+	var after := _main_screen_state()
+	var now := String(after.get("active", ""))
+	if now.to_lower() != target.to_lower():
+		return _err("not_found", "No main-screen tab named \"%s\" — the editor is still on \"%s\". Available: %s" % [want, now, ", ".join(PackedStringArray(available))])
+	return _ok({"active": after.get("active"), "available": after.get("available"), "requested": target})
+
+
 func _classdb_get_class(params: Dictionary) -> Dictionary:
 	var cls := String(params.get("class_name", ""))
 	if cls == "" or not ClassDB.class_exists(cls):
@@ -1294,10 +1411,71 @@ func _scene_get_dependencies(params: Dictionary) -> Dictionary:
 		return _err("bad_params", "Current scene has no saved path yet")
 	if not ResourceLoader.exists(target):
 		return _err("not_found", "Scene not found: %s" % target)
+	# 🔴 THE ENTRY GODOT HANDS BACK IS NOT A PATH, AND FOR SOME DEPENDENCIES IT IS THE
+	# ONLY SPELLING THAT DOES NOT LOAD (session 169 §5). Measured on 4.7 against the
+	# example project, with controls:
+	#
+	#   res://main.tscn            -> "uid://ccgi4n26nbyku::::res://player.gd"   (2 segments)
+	#   res://demo/demo.tscn       -> "res://demo/demo_snowman.gd"               (1 segment)
+	#
+	# The shape is HETEROGENEOUS — it depends on whether the dependency has a `.uid`
+	# sidecar — so `dependencies` was an array a caller could not parse without already
+	# knowing the rule. Fed to resource_load verbatim, the two-segment form answers
+	# `not_found`, while BOTH of its halves load fine on their own. The tool was handing
+	# out the one spelling that works with nothing.
+	#
+	# This is #181's defect in a read-only tool: a value echoed from the engine and
+	# presented as an answer nobody had measured. Same fix as #181 — the field is made to
+	# mean what its description says, and nothing is destroyed: the engine's own encoding
+	# is preserved verbatim under `dependencies_raw`.
+	#
+	# 🔴 THE FALLBACK NEVER DROPS AN ENTRY. An unrecognised shape (no res:// or user://
+	# segment) is passed through whole rather than skipped: a splitter that silently
+	# discards what it does not understand would shrink the dependency list and look
+	# cleaner for it, which is this session's entire subject.
 	var deps: Array = []
+	var raw: Array = []
+	var uids: Array = []
 	for d in ResourceLoader.get_dependencies(target):
-		deps.append(String(d))
-	return _ok({"path": target, "dependencies": deps})
+		var entry := String(d)
+		var split := split_dependency_entry(entry)
+		raw.append(entry)
+		deps.append(split["path"])
+		uids.append(split["uid"])
+	return _ok({
+		"path": target,
+		"dependencies": deps,
+		"dependencies_raw": raw,
+		"dependency_uids": uids,
+	})
+
+
+## Split one ResourceLoader.get_dependencies entry into its loadable path and its UID.
+##
+## 🔴 A SEPARATE, PUBLIC FUNCTION ON PURPOSE. Inlined in the loop, two of its branches
+## were unreachable from any scene the example project contains — a mutation sweep proved
+## it (169 §7): making the splitter DROP unrecognised entries, and matching the UID prefix
+## as loosely as `begins_with("u")`, both SURVIVED with the suite fully green, because no
+## fixture produces an entry that exercises either path. The comment claiming "the
+## fallback never drops an entry" was itself an unasserted claim, which is this session's
+## whole subject. Pulled out here, every branch takes a synthetic input in one cheap
+## hermetic test.
+##
+## Returns {"path": String, "uid": String}. `uid` is "" when the entry carries none.
+## An entry with no recognisable path segment is returned WHOLE as the path: dropping it
+## would shrink the dependency list and look tidier for it.
+static func split_dependency_entry(entry: String) -> Dictionary:
+	var found_path := ""
+	var found_uid := ""
+	for s in entry.split("::::"):
+		var seg := String(s)
+		if seg.begins_with("res://") or seg.begins_with("user://"):
+			if found_path == "":
+				found_path = seg
+		elif seg.begins_with("uid://"):
+			if found_uid == "":
+				found_uid = seg
+	return {"path": found_path if found_path != "" else entry, "uid": found_uid}
 
 
 func _scene_pack(params: Dictionary) -> Dictionary:
@@ -1624,6 +1802,18 @@ func _resource_get_import_settings(params: Dictionary) -> Dictionary:
 	var path := String(params.get("path", ""))
 	if path == "":
 		return _err("bad_params", "Missing 'path'")
+	# 🔴 168 (166 §5 D3), MEASURED against a live 4.7 editor: this used to test ONLY for
+	# the sidecar, so `res://player.gd` (a real file with no .import) and
+	# `res://no_such_file.png` (nothing at all) returned BYTE-IDENTICAL replies —
+	# {"imported": false, "importer": "", "settings": {}} — and a caller had no channel
+	# to tell "not imported" from "not there". A directory answered the same way.
+	# The vocabulary here is NOT invented: resource_load and resource_get_property were
+	# both probed for a missing path AND for a directory, and both already answer
+	# `not_found` / "Resource not found: %s" for each. This joins that convention rather
+	# than adding a third one. `imported: false` now means what it says — the file is
+	# really there and really has no .import sidecar.
+	if not FileAccess.file_exists(path):
+		return _err("not_found", "Resource not found: %s" % path)
 	var import_path := path + ".import"
 	if not FileAccess.file_exists(import_path):
 		return _ok({"path": path, "imported": false, "importer": "", "settings": {}})
@@ -1645,6 +1835,12 @@ func _resource_set_import_settings(params: Dictionary) -> Dictionary:
 	var path := String(params.get("path", ""))
 	if path == "":
 		return _err("bad_params", "Missing 'path'")
+	# 🔴 168: the same lie as D3, one tool over. A path that does not exist was refused
+	# with "No .import metadata for X (not an imported asset)" — a sentence that
+	# describes a file which EXISTS and is not imported. Measured: a directory got that
+	# message too. `not_imported` is now reserved for what it names.
+	if not FileAccess.file_exists(path):
+		return _err("not_found", "Resource not found: %s" % path)
 	var import_path := path + ".import"
 	if not FileAccess.file_exists(import_path):
 		return _err("not_imported", "No .import metadata for %s (not an imported asset)" % path)
@@ -1652,10 +1848,28 @@ func _resource_set_import_settings(params: Dictionary) -> Dictionary:
 	var e := cfg.load(import_path)
 	if e != OK:
 		return _err("load_failed", "Could not read import metadata: %s (%d)" % [import_path, e])
+	# 🔴 168 (166 §5 D4), MEASURED: `applied` lists every key the CALLER SENT, and
+	# `reimported` echoes the REQUEST parameter. Setting a key to the value it already
+	# held reported {"reimported": true, "settings": ["compress/mode"]} with the
+	# sidecar's bytes provably unmoved (sha256 before == after). A caller reading that
+	# reply cannot tell a real edit from a ceremonial one.
+	#
+	# `changed` is the missing channel, and it is deliberately a channel rather than a
+	# behaviour change: `settings: {}` with `reimport: true` is a legitimate FORCE-REIMPORT
+	# idiom (the source file moved under Godot's feet), so the reimport still runs and
+	# `reimported` still reports it honestly. What was missing was the ability to say
+	# "and nothing in the metadata actually moved" — which is now `changed: []`.
 	var applied: Array = []
+	var changed: Array = []
 	for key in params.get("settings", {}):
-		cfg.set_value("params", String(key), Codec.decode(params["settings"][key]))
-		applied.append(String(key))
+		var k := String(key)
+		var new_value = Codec.decode(params["settings"][key])
+		var had := cfg.has_section_key("params", k)
+		var old_value = cfg.get_value("params", k) if had else null
+		cfg.set_value("params", k, new_value)
+		applied.append(k)
+		if not had or old_value != new_value:
+			changed.append(k)
 	e = cfg.save(import_path)
 	if e != OK:
 		return _err("save_failed", "Could not write import metadata (%d)" % e)
@@ -1663,7 +1877,7 @@ func _resource_set_import_settings(params: Dictionary) -> Dictionary:
 	if reimport:
 		var efs := EditorInterface.get_resource_filesystem()
 		efs.reimport_files(PackedStringArray([path]))
-	return _ok({"path": path, "reimported": reimport, "settings": applied})
+	return _ok({"path": path, "reimported": reimport, "settings": applied, "changed": changed})
 
 
 # ----------------------------------------------- Group B: filesystem --------
@@ -1706,12 +1920,28 @@ func _filesystem_move(params: Dictionary) -> Dictionary:
 	var e := dir.rename(from_path, to_path)
 	if e != OK:
 		return _err("move_failed", "rename() returned %d" % e)
+	# 🔴 173 §10.3 — THE THIRD CONFIRMED MEMBER OF THE ECHO-MISTAKEN-FOR-A-REPORT
+	# FAMILY (#181, #183, 172 D5). `dir.rename()`'s RETURN WAS DISCARDED HERE and
+	# `moved_import` was set to true whenever a sidecar merely EXISTED — so the field
+	# described the REQUEST ("there was an .import and I called rename") rather than the
+	# outcome. A sidecar rename that failed (destination taken, permissions, a
+	# case-only rename on a case-insensitive filesystem) left an ORPHANED .import beside
+	# a file that had moved, stripping the moved asset of its import settings on the next
+	# scan — and the report said `moved_import: true`.
+	#
+	# THREE OUTCOMES, TWO BOOLEANS, BOTH DERIVED FROM THE RETURN CODE. "No sidecar" and
+	# "a sidecar that would not move" are different events and the caller has to be able
+	# to tell them apart; one boolean can only say "not moved" for both. The move itself
+	# already succeeded, so a stranded sidecar is a PARTIAL, not a failure — returning
+	# _err here would say nothing happened, which is the same lie in the other direction.
 	var moved_import := false
+	var import_stranded := false
 	if is_file and FileAccess.file_exists(from_path + ".import"):
-		dir.rename(from_path + ".import", to_path + ".import")
-		moved_import = true
+		var ie := dir.rename(from_path + ".import", to_path + ".import")
+		moved_import = ie == OK
+		import_stranded = ie != OK
 	EditorInterface.get_resource_filesystem().scan()
-	return _ok({"moved": to_path, "from": from_path, "moved_import": moved_import})
+	return _ok({"moved": to_path, "from": from_path, "moved_import": moved_import, "import_stranded": import_stranded})
 
 
 func _filesystem_create_dir(params: Dictionary) -> Dictionary:
@@ -1723,6 +1953,11 @@ func _filesystem_create_dir(params: Dictionary) -> Dictionary:
 	var e := DirAccess.make_dir_recursive_absolute(path)
 	if e != OK:
 		return _err("mkdir_failed", "make_dir_recursive_absolute() returned %d" % e)
+	# 🔴 173 §10.3, same family, one step milder: `created` was the REQUESTED path echoed
+	# back, and an OK return was never once confirmed against the filesystem. Re-read it,
+	# so `created` names a directory that is THERE rather than one that was asked for.
+	if not DirAccess.dir_exists_absolute(path):
+		return _err("mkdir_failed", "make_dir_recursive_absolute() returned OK but %s does not exist" % path)
 	EditorInterface.get_resource_filesystem().scan()
 	return _ok({"created": path, "existed": false})
 
@@ -3275,7 +3510,7 @@ func _particles_set_texture(params: Dictionary) -> Dictionary:
 	if node == null:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	if not (node is GPUParticles2D):
-		return _err("unsupported", "%s has no texture (GPUParticles3D draws meshes; texture is GPUParticles2D-only)" % node.name)
+		return _err("unsupported", "%s has no texture: only GPUParticles2D has one, and GPUParticles3D draws meshes instead. Pass the path of a GPUParticles2D node." % node.name)
 	var tex_path := String(params.get("texture_path", ""))
 	if tex_path == "" or not ResourceLoader.exists(tex_path):
 		return _err("not_found", "Texture not found: %s" % tex_path)
@@ -3347,7 +3582,7 @@ func _shadermaterial_create(params: Dictionary) -> Dictionary:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	var prop := _material_prop(node)
 	if prop == "":
-		return _err("unsupported", "%s has no material slot (needs CanvasItem.material or GeometryInstance3D.material_override)" % node.name)
+		return _err("unsupported", "%s has no material slot. Pass a node that has one: any CanvasItem exposes CanvasItem.material, any GeometryInstance3D exposes GeometryInstance3D.material_override." % node.name)
 	var mat := ShaderMaterial.new()
 	var shader_path := String(params.get("shader_path", ""))
 	if shader_path != "":
@@ -3375,7 +3610,7 @@ func _shadermaterial_set_shader(params: Dictionary) -> Dictionary:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	var prop := _material_prop(node)
 	if prop == "":
-		return _err("unsupported", "%s has no material slot" % node.name)
+		return _err("unsupported", "%s has no material slot. Pass a node that has one: any CanvasItem exposes CanvasItem.material, any GeometryInstance3D exposes GeometryInstance3D.material_override." % node.name)
 	var cur = node.get(prop)
 	if not (cur is ShaderMaterial):
 		return _err("bad_type", "%s has no ShaderMaterial (create one first)" % node.name)
@@ -3403,7 +3638,7 @@ func _shadermaterial_set_param(params: Dictionary) -> Dictionary:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	var prop := _material_prop(node)
 	if prop == "":
-		return _err("unsupported", "%s has no material slot" % node.name)
+		return _err("unsupported", "%s has no material slot. Pass a node that has one: any CanvasItem exposes CanvasItem.material, any GeometryInstance3D exposes GeometryInstance3D.material_override." % node.name)
 	var cur = node.get(prop)
 	if not (cur is ShaderMaterial):
 		return _err("bad_type", "%s has no ShaderMaterial (create one first)" % node.name)

package/addon/breakpoint_mcp/plugin.cfg

@@ -3,5 +3,5 @@
 name="Breakpoint MCP"
 description="Exposes the live Godot editor and the running game to an MCP host so an AI assistant can drive them: scene/node/resource CRUD with full undo/redo, project settings, ClassDB, editor + in-game screenshots, and an in-game runtime bridge (live SceneTree, property get/set, method calls, signals, input injection, Performance monitors). Pairs with the breakpoint-mcp MCP host."
 author="James Livingston"
-version="1.9.2"
+version="1.9.8"
 script="plugin.gd"

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -35,6 +35,12 @@ const MONITORS := {
 	"time/process": Performance.TIME_PROCESS,
 	"time/physics_process": Performance.TIME_PHYSICS_PROCESS,
 	"memory/static": Performance.MEMORY_STATIC,
+	# Total live ObjectDB instances — Nodes, Resources and BARE Objects alike, which is
+	# what makes it the only monitor here that can see a leaked non-Node. Added session
+	# 153 so the _node_add `not_a_node` leak fixed in the same commit is REGRESSION-LOCKED
+	# in CI rather than merely proved once on a laptop: node-lifecycle.integration.mjs
+	# drives that branch in bulk and watches this number.
+	"object/count": Performance.OBJECT_COUNT,
 	"object/node_count": Performance.OBJECT_NODE_COUNT,
 	"object/resource_count": Performance.OBJECT_RESOURCE_COUNT,
 	"render/total_objects_drawn": Performance.RENDER_TOTAL_OBJECTS_IN_FRAME,
@@ -456,7 +462,36 @@ func _emit_signal(params: Dictionary) -> Dictionary:
 	var call_args: Array = [sig]
 	for a in params.get("args", []):
 		call_args.append(Codec.decode(a))
-	node.callv("emit_signal", call_args)
+	# emit_signal RETURNS an Error, and discarding it made this tool answer
+	# {"emitted": true} for an emission the engine refused. The cause is an `args` count
+	# that does not match a CONNECTED callable's arity: the engine pushes its own
+	# "Method expected N argument(s), but called with M" into the GAME's log — not the
+	# caller's — and that callable never runs, so the caller fails at its NEXT assertion,
+	# arbitrarily far from the cause.
+	#
+	# 🔴 TWO non-OK codes, and only one of them is a failure. Measured identically on
+	# 4.3, 4.5 and 4.7:
+	#
+	#   OK (0)                    a connected callable ran
+	#   ERR_METHOD_NOT_FOUND (37) a callable IS connected and could not be invoked —
+	#                             the arity mismatch. This is the defect worth reporting.
+	#   ERR_UNAVAILABLE (2)       the signal exists but has NO connections at all.
+	#                             Emitting into the void is ordinary and must SUCCEED —
+	#                             rejecting it would break every game that emits a signal
+	#                             nothing happens to be listening to.
+	#
+	# 🔴 The honest consequence: arity is checkable ONLY when something is connected.
+	# With no listener, a wrong count also returns ERR_UNAVAILABLE (there is no callable
+	# whose arity could mismatch), so it is indistinguishable from a correct emission.
+	# That is a limit of what the engine reports, not something this tool can tighten,
+	# and the catalog says so rather than implying a guarantee that does not exist.
+	var err: int = node.callv("emit_signal", call_args)
+	if err != OK and err != ERR_UNAVAILABLE:
+		return _err(
+			"emit_failed",
+			"emit_signal(%s) with %d arg(s) failed: %s (%d). Check the count against the arity of the signal's connected callables."
+				% [sig, call_args.size() - 1, error_string(err), err]
+		)
 	return _ok({"emitted": true})
 
 
@@ -466,6 +501,14 @@ func _inject_input(params: Dictionary) -> Dictionary:
 	match kind:
 		"action":
 			var action := String(ev.get("action", ""))
+			# An action the InputMap does not know is NOT injectable. Input.action_press
+			# pushes its own engine error and returns, so without this guard the reply is
+			# {"injected": true} for a typo'd action name and the caller's NEXT assertion is
+			# where the failure surfaces — as far from the cause as it is possible to get.
+			# Found live, session 153, by the probe that first pointed this tool at a real
+			# InputMap. Covers both operands: an absent "action" key arrives here as "".
+			if not InputMap.has_action(action):
+				return _err("bad_action", "No such InputMap action: %s" % action)
 			if bool(ev.get("pressed", true)):
 				Input.action_press(action, float(ev.get("strength", 1.0)))
 			else:
@@ -891,6 +934,16 @@ func _node_add(params: Dictionary) -> Dictionary:
 			return _err("bad_type", "Cannot instantiate class: %s" % type_name)
 		var obj: Variant = ClassDB.instantiate(type_name)
 		if not (obj is Node):
+			# ClassDB.instantiate hands back an UNOWNED instance. A RefCounted subclass
+			# (Resource, Image, ...) releases itself when this reference goes out of scope;
+			# a bare Object does NOT, so returning here without freeing leaked one instance
+			# per call — which the engine reports only at exit, as "N ObjectDB instances
+			# were leaked". Proved session 152, measured session 153 at 51 leaked over 51
+			# calls and 0 with this branch in place.
+			# The RefCounted arm MUST be excluded: free() on a RefCounted is itself an error,
+			# which is why the safe-looking `Resource` case hid this for so long.
+			if obj is Object and not (obj is RefCounted):
+				(obj as Object).free()
 			return _err("not_a_node", "%s is not a Node" % type_name)
 		child = obj
 	if child == null:

package/dist/annotations.js

@@ -8,7 +8,7 @@ const READ_ONLY = [
     "gd_declaration", "gd_definition", "gd_diagnostics", "gd_document_color", "gd_document_highlight",
     "gd_document_link", "gd_document_symbols", "gd_folding_ranges", "gd_formatting", "gd_hover", "gd_implementation",
     "gd_references", "gd_semantic_tokens", "gd_signature_help", "gd_type_definition", "gd_workspace_symbols",
-    "godot_output", "godot_version", "inputmap_list", "node_find", "node_get_children", "node_get_path",
+    "godot_output", "godot_version", "inputmap_list", "main_screen_get", "node_find", "node_get_children", "node_get_path",
     "node_get_property", "node_list_groups", "node_list_properties", "project_get_info", "project_get_setting",
     "project_list_settings", "project_search", "resource_get_import_settings", "resource_get_property",
     "resource_load", "runtime_anim_get_state", "runtime_assert_node_state", "runtime_assert_perf",
@@ -63,7 +63,7 @@ const IDEMPOTENT = [
     "gd_references", "gd_rename", "gd_semantic_tokens", "gd_signature_help", "gd_type_definition",
     "gd_workspace_symbols", "godot_export", "godot_import", "godot_output", "godot_stop", "godot_version",
     "inputmap_add_action", "inputmap_erase_action", "inputmap_list", "joint_set_bodies", "leaderboard_scaffold",
-    "mesh_set_surface_material", "mp_scaffold_lobby", "mp_set_authority", "mp_setup_enet_peer",
+    "main_screen_get", "main_screen_set", "mesh_set_surface_material", "mp_scaffold_lobby", "mp_set_authority", "mp_setup_enet_peer",
     "mp_setup_webrtc_peer", "mp_wire_rpc", "node_add_to_group", "node_change_type", "node_delete", "node_find",
     "node_get_children", "node_get_path", "node_get_property", "node_list_groups", "node_list_properties",
     "node_move_child", "node_remove_from_group", "node_rename", "node_reparent", "node_set_editable_instance",
@@ -131,7 +131,7 @@ export const ALL_ANNOTATED = [
     "godot_launch_editor", "godot_output", "godot_run_headless_script", "godot_run_managed", "godot_run_project",
     "godot_stop", "godot_version", "inputmap_add_action", "inputmap_add_event", "inputmap_erase_action",
     "inputmap_list", "interact_add_drop_zone", "interact_make_draggable", "joint_create", "joint_set_bodies",
-    "leaderboard_scaffold", "light_create", "mesh_set_surface_material", "meshinstance_create", "mp_add_spawner",
+    "leaderboard_scaffold", "light_create", "main_screen_get", "main_screen_set", "mesh_set_surface_material", "meshinstance_create", "mp_add_spawner",
     "mp_add_synchronizer", "mp_scaffold_lobby", "mp_set_authority", "mp_setup_enet_peer", "mp_setup_webrtc_peer",
     "mp_wire_rpc", "navagent_configure", "navregion_create", "node_add", "node_add_to_group", "node_call_method",
     "node_change_type", "node_delete", "node_duplicate", "node_find", "node_get_children", "node_get_path",

package/dist/cli/doctor.js

@@ -195,7 +195,7 @@ export function checkCapabilities(config) {
             status: "ok",
             severity: "info",
             detail: dropped.length === 0
-                ? `${state} — full 289-tool surface`
+                ? `${state} — full 291-tool surface`
                 : `${state} (secure default) — ${dropped.length} higher-trust tool(s) dropped from the surface`,
             hint: dropped.length === 0
                 ? undefined

package/dist/cli/init.js

@@ -279,7 +279,7 @@ export async function runInit(argv, deps = {}) {
     // Trust groups — surface the secure default so even a bare `init` teaches it.
     say("");
     if (privilegedGroups) {
-        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 289-tool surface loads.`);
+        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 291-tool surface loads.`);
     }
     else {
         say("Higher-trust tool groups are OFF by default (the secure default). The assistant loads the");

package/dist/cli/tools.js

@@ -17,8 +17,8 @@
  * container, and on a machine with no Godot installed.
  *
  * Two surfaces are reported, because the difference is the security story:
- *   • `full`           — all 289 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
- *   • `secure-default` — 276, what an untouched install actually advertises
+ *   • `full`           — all 291 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
+ *   • `secure-default` — 278, what an untouched install actually advertises
  * `--surface` picks which one populates `tools[]`; both counts are always in the
  * header so a consumer cannot report one as the other by accident.
  */

package/dist/csdap.js

@@ -1,6 +1,13 @@
 import { EventEmitter } from "node:events";
 import { DapError } from "./dap.js";
 import { OverdueLedger } from "./late-reply.js";
+/**
+ * How long `start()` waits for the entry `stopped` event when `stopAtEntry` was
+ * requested. Bounded so an adapter that ignores stop-on-entry reports `running`
+ * rather than hanging the launch. Measured: netcoredbg emits it well inside a
+ * second on a local program, after its `configurationDone` response.
+ */
+const ENTRY_STOP_WAIT_MS = 10000;
 /**
  * Minimal DAP client for the C#/.NET debugging plane (D4 C3) — the debugger
  * analogue of the C2 `CsLspClient`. Transport-agnostic: it drives any
@@ -40,6 +47,12 @@ export class CsDapClient extends EventEmitter {
     watches = [];
     lastStartMode = null;
     lastStartArgs = null;
+    /**
+     * The launch/attach rejection, when one arrives. Set by `start()`; read there and
+     * kept afterwards so a rejection that lands late is still visible rather than
+     * being emitted as an unlistened `error` event (which throws).
+     */
+    startFailure = null;
     capabilities = null;
     state = "disconnected";
     lastStoppedThreadId = null;
@@ -229,7 +242,23 @@ export class CsDapClient extends EventEmitter {
             await this.applyBreakpoints(path).catch(() => undefined);
         }
     }
-    /** Full handshake: initialize → launch/attach → (breakpoints) → configurationDone. */
+    /**
+     * Full handshake: initialize → launch/attach → (breakpoints) → configurationDone.
+     *
+     * 🔴 The handshake used to declare success unconditionally. Measured against a
+     * real netcoredbg 3.2.0-1092 with `program: "/no/such/binary"`:
+     *
+     *     >> launch             << success=true
+     *     >> configurationDone  << success=false
+     *                              "Failed command 'configurationDone' : 0x80070002"
+     *
+     * `0x80070002` is ERROR_FILE_NOT_FOUND — the adapter DOES report the failure, and it
+     * reports it on `configurationDone`, which was `.catch(() => undefined)`-swallowed
+     * immediately before `state = "running"`. So `cs_dbg_launch` answered
+     * `isError:false state:"running"` for a session that never existed, and every tool
+     * afterwards failed with a bare hex code against a phantom session. The same held
+     * for `program: ""` and for `cs_dbg_attach` on a process id that does not exist.
+     */
     async start(mode, args) {
         this.lastStartMode = mode;
         this.lastStartArgs = args;
@@ -247,14 +276,67 @@ export class CsDapClient extends EventEmitter {
         this.state = "initialized";
         // Send launch/attach but don't await it yet — many adapters (netcoredbg included)
         // only resolve it after configurationDone.
-        const startReq = this.request(mode, args);
+        //
+        // 🔴 A rejection used to be routed to `this.emit("error", err)`. Nothing in the
+        // host registers an `error` listener, and an unlistened `error` emit on an
+        // EventEmitter is an UNCAUGHT THROW — a failing launch could take the MCP server
+        // down. It is captured instead, and recorded on the client so a rejection that
+        // lands after `start()` has returned still puts the session in `terminated`
+        // rather than leaving it reading `running`.
+        this.startFailure = null;
+        const startReq = this.request(mode, args).then(() => undefined, (err) => {
+            this.startFailure = err;
+            this.configured = false;
+            this.state = "terminated";
+            // A DISTINCT event name, deliberately: `error` is special-cased by
+            // EventEmitter and throws when unlistened. This one is safe to ignore.
+            this.emit("start_failed", err);
+        });
         await onInit;
         await this.applyAllBreakpoints();
-        await this.request("configurationDone", {}).catch(() => undefined);
+        // Arm the entry-stop wait BEFORE configurationDone is sent: netcoredbg can emit
+        // `stopped` before its configurationDone response lands, and a listener attached
+        // afterwards would miss it.
+        const wantsEntryStop = mode === "launch" && args["stopAtEntry"] === true;
+        const entryStop = wantsEntryStop ? this.waitEvent("stopped", ENTRY_STOP_WAIT_MS) : null;
+        let configureFailure = null;
+        await this.request("configurationDone", {}).catch((err) => {
+            configureFailure = err;
+        });
+        // 🔴 Only treat a configurationDone failure as fatal when the adapter ADVERTISED
+        // the request. An adapter that never claimed `supportsConfigurationDoneRequest`
+        // may legitimately reject it while the session is perfectly alive — refusing
+        // there would be the over-eager mirror of the bug being fixed. netcoredbg
+        // advertises it (measured: `supportsConfigurationDoneRequest = true`), so its
+        // 0x80070002 is a real answer, not an unimplemented request.
+        const configureDoneAdvertised = this.capabilities?.["supportsConfigurationDoneRequest"] === true;
+        const fatal = this.startFailure ?? (configureDoneAdvertised ? configureFailure : null);
+        if (fatal) {
+            this.configured = false;
+            this.state = "terminated";
+            void startReq;
+            const detail = fatal?.message ?? String(fatal);
+            throw new DapError(mode, `the C# debug adapter did not start the session: ${detail}. No debug session is ` +
+                `running — check that the program exists and is a .NET assembly (${mode} args: ` +
+                `${JSON.stringify(args).slice(0, 200)}).`);
+        }
         this.configured = true;
-        this.state = "running";
-        // Surface a launch/attach failure if one occurs, but don't hang on success.
-        startReq.catch((err) => this.emit("error", err));
+        // 🔴 ONLY from `initialized`, never unconditionally. The adapter can emit `stopped`
+        // (or `terminated`) between the configurationDone RESPONSE and this line, and the
+        // event handler has already moved the state — a blind `= "running"` clobbers it and
+        // the awaited entry stop below then has nothing left to wait for. The first version
+        // of this fix wrote it unconditionally and passed locally for exactly that reason:
+        // the race window is small, and CI is where it opened.
+        if (this.state === "initialized")
+            this.state = "running";
+        // 🔴 `stop_on_entry` used to return before the entry stop, so the tool reported
+        // `running` and `threadId()` fell back to 1 while netcoredbg's real thread id is a
+        // large integer — cs_dbg_stack_trace answered `0x80070057` immediately after
+        // launch, and the IDENTICAL call succeeded 1.5s later. Waiting here is what makes
+        // stop-on-entry work end to end. Bounded: an adapter that ignores stopAtEntry
+        // simply reports `running`, as before.
+        if (entryStop)
+            await entryStop;
     }
     threadId() {
         return this.lastStoppedThreadId ?? 1;