hi-godot
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 10 additions & 1 deletion b/‎.github/workflows/ci.yml‎
Lines changed: 10 additions & 1 deletion
diff --git a/‎README.md‎
Lines changed: 22 additions & 13 deletions b/‎README.md‎
Lines changed: 22 additions & 13 deletions
diff --git a/‎plugin/addons/godot_ai/clients/_base.gd‎
Lines changed: 14 additions & 0 deletions b/‎plugin/addons/godot_ai/clients/_base.gd‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎plugin/addons/godot_ai/clients/_json_strategy.gd‎
Lines changed: 78 additions & 6 deletions b/‎plugin/addons/godot_ai/clients/_json_strategy.gd‎
Lines changed: 78 additions & 6 deletions
diff --git a/‎plugin/addons/godot_ai/clients/_path_template.gd‎
Lines changed: 2 additions & 0 deletions b/‎plugin/addons/godot_ai/clients/_path_template.gd‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎plugin/addons/godot_ai/clients/_toml_strategy.gd‎
Lines changed: 90 additions & 6 deletions b/‎plugin/addons/godot_ai/clients/_toml_strategy.gd‎
Lines changed: 90 additions & 6 deletions
diff --git a/‎plugin/addons/godot_ai/debugger/mcp_debugger_plugin.gd‎
Lines changed: 16 additions & 4 deletions b/‎plugin/addons/godot_ai/debugger/mcp_debugger_plugin.gd‎
Lines changed: 16 additions & 4 deletions
@@ -163,7 +163,7 @@ jobs:
 
       - name: Start Godot editor (headless)
         shell: bash
-        run: GODOT_AI_ALLOW_HEADLESS=1 godot --headless --path test_project --editor &
+        run: GODOT_AI_ALLOW_HEADLESS=1 godot --headless --path test_project --editor > godot-editor.log 2>&1 &
 
       - name: Run handler tests
         shell: bash
@@ -180,6 +180,15 @@ jobs:
         timeout-minutes: 2
         run: bash script/ci-quit-test
 
+      - name: Dump Godot editor log on failure
+        if: failure()
+        shell: bash
+        run: |
+          echo "===== godot-editor.log (last 500 lines) ====="
+          tail -n 500 godot-editor.log || echo "(log not found)"
+          echo "===== godot-import.log (last 200 lines) ====="
+          tail -n 200 godot-import.log || echo "(log not found)"
+
   # Separate job from godot-tests: the capture smoke test needs a real
   # rendering driver (null RenderingDevice in --headless produces empty
   # framebuffers) and a display server. Linux uses xvfb-run; macOS and
 
@@ -173,31 +173,40 @@ every process unmaps it. uv's post-install cleanup of the build venv then
 dies on a stale lock; the misleading `pywin32` mention is just the last
 package in the resolution order, not the actual lock holder.
 
-**Mitigation in this plugin:** `_stop_server` and `force_restart_server`
-both call `McpUvCacheCleanup.purge_stale_builds()` immediately after
-killing the server children, while the `.pyd` is briefly unmapped. See
-[`plugin/addons/godot_ai/utils/uv_cache_cleanup.gd`](plugin/addons/godot_ai/utils/uv_cache_cleanup.gd).
-
-**Recommended belt-and-braces:** tell uv to copy instead of hard-link by
-setting `UV_LINK_MODE=copy` in the MCP launcher's environment. This also
-removes the reverse race where an MCP client spawns `uvx mcp-proxy`
-*while* a server child is still holding the `.pyd`. Example for Claude
-Desktop's `claude_desktop_config.json`:
+**Mitigation in this plugin:**
+
+1. `_stop_server` and `force_restart_server` both call
+   `McpUvCacheCleanup.purge_stale_builds()` immediately after killing the
+   server children, while the `.pyd` is briefly unmapped. See
+   [`plugin/addons/godot_ai/utils/uv_cache_cleanup.gd`](plugin/addons/godot_ai/utils/uv_cache_cleanup.gd).
+2. **Auto-configure now writes `UV_LINK_MODE=copy` into the bridged
+   entry's `env` block** for every uvx-bridge client (Claude Desktop, Zed),
+   telling uv to copy shared C extensions instead of hard-linking them.
+   That removes the reverse race where an MCP client spawns `uvx mcp-proxy`
+   *while* a server child still holds the `.pyd`. Existing entries written
+   by older plugin versions surface in the dock as **drift (amber banner)**
+   so a single Configure click rewrites them with the env pin.
+
+The shape `client_configure` writes for Claude Desktop is now:
 
 ```json
 {
   "mcpServers": {
     "godot-ai": {
       "command": "uvx",
-      "args": ["mcp-proxy", "--transport", "streamablehttp", "http://127.0.0.1:8000/mcp"],
+      "args": ["mcp-proxy==0.11.0", "--transport", "streamablehttp", "http://127.0.0.1:8000/mcp"],
       "env": { "UV_LINK_MODE": "copy" }
     }
   }
 }
 ```
 
-If you've already hit the lock, kill stray `python.exe` children whose
-command line contains `spawn_main(parent_pid=...)` and delete
+If you've already hit the lock on an older config, click **Configure**
+on the affected uvx-bridge client (Claude Desktop *or* Zed) in the
+godot-ai dock to rewrite the entry with the env pin, then quit and
+reopen that client. If the lock persists (rare — pre-existing orphans
+the cache sweeper couldn't reach), kill stray `python.exe` children
+whose command line contains `spawn_main(parent_pid=...)` and delete
 `%LOCALAPPDATA%\uv\cache\builds-v0\.tmp*` manually before retrying.
 
 </details>
 
@@ -180,3 +180,17 @@ static func resolve_uvx_path() -> String:
 ## Callers splice this into the client-specific command shape.
 static func mcp_proxy_bridge_args(url: String) -> Array:
 	return ["mcp-proxy==" + MCP_PROXY_VERSION, "--transport", "streamablehttp", url]
+
+
+## Environment overrides written alongside every auto-configured uvx-bridge
+## entry. `UV_LINK_MODE=copy` tells uv to copy shared C extensions into each
+## `builds-v0\.tmpXXXXXX\` build venv instead of hard-linking them from
+## `archive-v0\`. On Windows that breaks the lock race documented in
+## `utils/uv_cache_cleanup.gd` and the README — the running godot-ai server
+## holds `_pydantic_core.pyd` mapped, the build venv's hard-linked copy
+## inherits the lock, uv's post-install cleanup fails, and the MCP launcher
+## reports "pywin32 wheel invalid / file in use" with no working transport.
+## Cost on macOS/Linux is a few extra MB in the uvx cache — well worth it
+## to keep one config shape across platforms.
+static func bridge_env_for_uvx() -> Dictionary:
+	return {"UV_LINK_MODE": "copy"}
@@ -79,13 +79,15 @@ static func build_entry(client: McpClient, server_url: String, existing: Variant
 			return {
 				"command": McpClient.resolve_uvx_path(),
 				"args": McpClient.mcp_proxy_bridge_args(server_url),
+				"env": _merge_bridge_env(existing),
 			}
 		McpClient.UvxBridge.NESTED:
 			return {
 				"command": {
 					"path": McpClient.resolve_uvx_path(),
 					"args": McpClient.mcp_proxy_bridge_args(server_url),
 				},
+				"env": _merge_bridge_env(existing),
 				"settings": {},
 			}
 	var entry: Dictionary = (existing as Dictionary).duplicate() if existing is Dictionary else {}
@@ -113,17 +115,21 @@ static func verify_entry(client: McpClient, entry: Dictionary, server_url: Strin
 			if entry.get(client.entry_url_field, "") == server_url:
 				return true
 			var cmd = entry.get("command", "")
-			if not (cmd is String):
+			if not (cmd is String and _command_is_uvx_like(cmd as String)):
 				return false
-			var uvx_like := (cmd as String).get_file() == "uvx" or (cmd as String).get_file() == "uvx.exe"
-			var args = entry.get("args", [])
-			return uvx_like and args is Array and args.has(server_url)
+			if not _bridge_args_are_valid(entry.get("args", []), server_url):
+				return false
+			return _bridge_env_matches(entry)
 		McpClient.UvxBridge.NESTED:
 			var cmd_obj = entry.get("command", {})
 			if not (cmd_obj is Dictionary):
 				return false
-			var nargs = cmd_obj.get("args", [])
-			return nargs is Array and nargs.has(server_url)
+			var npath = cmd_obj.get("path", "")
+			if not (npath is String and _command_is_uvx_like(npath as String)):
+				return false
+			if not _bridge_args_are_valid(cmd_obj.get("args", []), server_url):
+				return false
+			return _bridge_env_matches(entry)
 	if entry.get(client.entry_url_field, "") != server_url:
 		return false
 	for k in client.entry_extra_fields:
@@ -132,6 +138,72 @@ static func verify_entry(client: McpClient, entry: Dictionary, server_url: Strin
 	return true
 
 
+## Pre-fix entries lack `env.UV_LINK_MODE=copy` and hit the Windows uvx
+## hard-link race documented in `utils/uv_cache_cleanup.gd`. Flag them as
+## drift so the dock surfaces an amber banner and a Configure-click
+## rewrites the entry with the env pin. Every key in `bridge_env_for_uvx()`
+## must match verbatim — extra user keys are tolerated so a hand-added
+## `PYTHONUNBUFFERED=1` etc. doesn't trigger drift forever.
+static func _bridge_env_matches(entry: Dictionary) -> bool:
+	var env = entry.get("env", null)
+	if not (env is Dictionary):
+		return false
+	var pin := McpClient.bridge_env_for_uvx()
+	for k in pin:
+		if env.get(k) != pin[k]:
+			return false
+	return true
+
+
+## Configure rewrites the bridge entry wholesale (the bridge form is
+## identity-defined by command+args+env), but the verifier tolerates extra
+## user-added env keys like `HTTP_PROXY` / `PYTHONUNBUFFERED`. Without
+## merging, a Configure click on a CONFIGURED_MISMATCH entry would silently
+## drop those keys — so layer the UV_LINK_MODE pin over whatever env block
+## already exists on disk. New entries with no prior env get just the pin.
+static func _merge_bridge_env(existing: Variant) -> Dictionary:
+	var pin := McpClient.bridge_env_for_uvx()
+	if not (existing is Dictionary):
+		return pin
+	var existing_env = (existing as Dictionary).get("env", null)
+	if not (existing_env is Dictionary):
+		return pin
+	var merged: Dictionary = (existing_env as Dictionary).duplicate()
+	for k in pin:
+		merged[k] = pin[k]
+	return merged
+
+
+## Basename match for `uvx` / `uvx.exe`, accepting both the bare-name
+## fallback and an absolute path resolved by `McpCliFinder`. Shared by the
+## FLAT and NESTED bridge verifiers — the only place we ever inspect a
+## stored bridge command/path.
+static func _command_is_uvx_like(cmd: String) -> bool:
+	var basename := cmd.get_file()
+	return basename == "uvx" or basename == "uvx.exe"
+
+
+## Strict bridge-argv check: the args array must include the pinned
+## `mcp-proxy` package spec, the `--transport streamablehttp` selector, and
+## the expected URL. Pre-fix `args.has(url)` was lenient — entries with the
+## wrong transport (`--transport sse`) or a different package would still
+## verify CONFIGURED, hiding the broken bridge. Match `mcp-proxy` by prefix
+## so a future MCP_PROXY_VERSION bump doesn't churn the verifier.
+static func _bridge_args_are_valid(args: Variant, server_url: String) -> bool:
+	if not (args is Array):
+		return false
+	var has_mcp_proxy := false
+	for a in args:
+		if a is String and (a as String).begins_with("mcp-proxy"):
+			has_mcp_proxy = true
+			break
+	if not has_mcp_proxy:
+		return false
+	if not (args.has("--transport") and args.has("streamablehttp") and args.has(server_url)):
+		return false
+	return true
+
+
 ## Returns {"ok": true, "data": Dictionary} when the file is absent or parses
 ## cleanly, and {"ok": false, "error": String} when the file exists with
 ## non-empty content we cannot safely round-trip. Callers must NOT fall back
 
@@ -39,6 +39,8 @@ static func expand(template: String) -> String:
 				value = _home().path_join("AppData/Roaming")
 			if value.is_empty() and var_name == "LOCALAPPDATA":
 				value = _home().path_join("AppData/Local")
+			if value.is_empty() and var_name == "HOME":
+				value = _home()
 			out = out.replace(token, value)
 	return out
 
 
@@ -81,15 +81,20 @@ static func remove(client: McpClient, _server_name: String) -> Dictionary:
 		return {"status": "error", "message": "Refusing to rewrite %s: %s." % [path, read["error"]]}
 	var lines: Array[String] = _split_lines(String(read["data"]))
 	var headers := _all_headers(client)
+	## Subtables in the namespace (e.g. [mcp_servers.godot-ai.tools.session_list]
+	## that codex users add to set per-tool approval_mode) must be removed
+	## too. Leaving them behind keeps `mcp_servers.godot-ai` implicitly
+	## defined, so a later configure that writes [mcp_servers."godot-ai"]
+	## produces a duplicate-key TOML error.
+	var subtable_prefixes := _subtable_prefixes(headers)
 
 	var output: Array[String] = []
 	var i := 0
 	while i < lines.size():
-		if _matches_any_header(lines[i], headers):
+		if _matches_any_header(lines[i], headers) or _matches_subtable_prefix(lines[i], subtable_prefixes):
 			i += 1
 			while i < lines.size():
-				var nt := lines[i].strip_edges()
-				if nt.begins_with("[") and nt.ends_with("]"):
+				if _is_any_section_header(lines[i]):
 					break
 				i += 1
 			continue
@@ -152,12 +157,75 @@ static func _primary_header(client: McpClient) -> String:
 
 
 static func _all_headers(client: McpClient) -> Array[String]:
-	var out: Array[String] = [_primary_header(client)]
+	var primary := _primary_header(client)
+	var out: Array[String] = [primary]
+	## TOML accepts bare keys ([A-Za-z0-9_-]+) unquoted in section headers,
+	## so [mcp_servers.godot-ai] is a valid hand-written form of the same
+	## logical key we emit as [mcp_servers."godot-ai"]. Match both during
+	## reconfigure / status / remove or a hand-edited (or older-plugin)
+	## bare-key file gets a duplicate quoted section appended that breaks
+	## the user's TOML parser.
+	var bare := _bare_key_header(client)
+	if not bare.is_empty() and bare != primary:
+		out.append(bare)
 	for legacy in client.toml_legacy_section_aliases:
 		out.append("[%s]" % legacy)
 	return out
 
 
+static func _bare_key_header(client: McpClient) -> String:
+	var parts := client.toml_section_path
+	if parts.is_empty():
+		return ""
+	for p in parts:
+		if not _is_bare_key(String(p)):
+			return ""
+	return "[%s]" % ".".join(parts)
+
+
+static func _is_bare_key(s: String) -> bool:
+	if s.is_empty():
+		return false
+	for i in range(s.length()):
+		var c := s.unicode_at(i)
+		var alpha := (c >= 65 and c <= 90) or (c >= 97 and c <= 122)
+		var digit := c >= 48 and c <= 57
+		var dash_or_under := c == 45 or c == 95  # '-' or '_'
+		if not (alpha or digit or dash_or_under):
+			return false
+	return true
+
+
+## Subtable prefixes derived from each header in `headers`. Strips the
+## closing `]` and appends `.` so a header `[a.b]` becomes the prefix
+## `[a.b.` — matching subtables `[a.b.<rest>]` but NOT siblings like
+## `[a.b-other]` (next char must be a dot, not anything bare-key-valid).
+static func _subtable_prefixes(headers: Array[String]) -> Array[String]:
+	var out: Array[String] = []
+	for h in headers:
+		if h.length() > 2 and h.ends_with("]"):
+			out.append(h.substr(0, h.length() - 1) + ".")
+	return out
+
+
+## Mirror of `_matches_any_header` for subtable prefixes — line must
+## start with `[a.b.` and have a closing `]` followed only by whitespace
+## or a comment.
+static func _matches_subtable_prefix(line: String, prefixes: Array[String]) -> bool:
+	var trimmed := line.strip_edges()
+	for p in prefixes:
+		if not trimmed.begins_with(p):
+			continue
+		var rest := trimmed.substr(p.length())
+		var bracket := rest.find("]")
+		if bracket < 0:
+			continue
+		var remainder := rest.substr(bracket + 1).strip_edges()
+		if remainder.is_empty() or remainder.begins_with("#"):
+			return true
+	return false
+
+
 ## Exact-header match. We cannot use a simple prefix check because
 ## `[mcp_servers."godot-ai"` is a prefix of `[mcp_servers."godot-ai-dev"]`,
 ## which would silently delete unrelated sections during remove().
@@ -177,9 +245,25 @@ static func _find_section(lines: Array[String], headers: Array[String]) -> Dicti
 		if _matches_any_header(lines[i], headers):
 			var end := lines.size()
 			for j in range(i + 1, lines.size()):
-				var nt := lines[j].strip_edges()
-				if nt.begins_with("[") and nt.ends_with("]"):
+				if _is_any_section_header(lines[j]):
 					end = j
 					break
 			return {"start": i, "end": end}
 	return {}
+
+
+## Generic "is this line a TOML section header" check that tolerates an
+## inline comment after the closing `]`, e.g. `[next_section] # note`.
+## The pre-fix `nt.begins_with("[") and nt.ends_with("]")` rejected those
+## lines, so a hand-written comment after a header would let the
+## section-deletion / section-end loops walk straight through into the
+## following section and clobber unrelated content.
+static func _is_any_section_header(line: String) -> bool:
+	var trimmed := line.strip_edges()
+	if not trimmed.begins_with("["):
+		return false
+	var bracket := trimmed.find("]")
+	if bracket < 0:
+		return false
+	var remainder := trimmed.substr(bracket + 1).strip_edges()
+	return remainder.is_empty() or remainder.begins_with("#")
@@ -32,7 +32,10 @@ const GAME_READY_WAIT_SEC := 20.0
 var _log_buffer: McpLogBuffer
 var _game_log_buffer: McpGameLogBuffer
 
-## Pending request_id -> {connection, deadline_ts, timer}
+## Pending request_id -> {connection, timer, timeout_callable}.
+## We retain the bound timeout lambda so `_clear_pending` can disconnect
+## it on success/error; otherwise the SceneTreeTimer pins the captured
+## request_id until `timeout_sec` elapses (8s default).
 var _pending: Dictionary = {}
 
 ## Flipped true when the game-side autoload sends its "mcp:hello" boot
@@ -216,10 +219,14 @@ func _send_take_screenshot(
 			"No active debugger session — is the game actually running and started from this editor?")
 		return
 
-	_pending[request_id] = {"connection": connection}
 	var timer: SceneTreeTimer = tree.create_timer(timeout_sec)
-	timer.timeout.connect(func() -> void: _on_timeout(request_id))
-	_pending[request_id]["timer"] = timer
+	var timeout_callable := func() -> void: _on_timeout(request_id)
+	timer.timeout.connect(timeout_callable)
+	_pending[request_id] = {
+		"connection": connection,
+		"timer": timer,
+		"timeout_callable": timeout_callable,
+	}
 
 	session.send_message("mcp:take_screenshot", [request_id, max_resolution])
 	if _log_buffer:
@@ -300,4 +307,9 @@ func _send_error(connection: McpConnection, request_id: String, code: String, me
 
 
 func _clear_pending(request_id: String) -> void:
+	var pending: Dictionary = _pending.get(request_id, {})
+	var timer: SceneTreeTimer = pending.get("timer")
+	var cb: Callable = pending.get("timeout_callable", Callable())
+	if timer != null and timer.timeout.is_connected(cb):
+		timer.timeout.disconnect(cb)
 	_pending.erase(request_id)