fix(game_eval): carve the not-ready path out into EVAL_GAME_NOT_READY (#518) (#519)

The opaque INTERNAL_ERROR 'regression' on game_eval (1.42%->6.15%) was a thin-baseline cohort artifact plus #500 reclassifying ~15s TimeoutErrors into fast ~3s INTERNAL_ERRORs; the genuine ~10s hang is flat ~2.8%. Carve the play-session-up-but-capture-not-ready failure into its own EVAL_GAME_NOT_READY code (mirrors #491, and is #518's Suggested Action #2) so the opaque bucket again means 'the eval truly hung'. Relabel only; no timing machinery touched.

Refs #518.

Author: dsarno

plugin/addons/godot_ai/debugger/mcp_debugger_plugin.gd

@@ -433,8 +433,12 @@ func _wait_then_eval(
 	while not is_game_capture_ready() and Time.get_ticks_msec() < deadline:
 		await tree.process_frame
 	if not is_game_capture_ready():
-		_send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR,
-			"Game-side autoload never registered its debugger capture within %ds. Is the game actually running? Start it with project_run / the editor's Play button, then retry. If it IS running, check Project Settings → Autoload for _mcp_game_helper (added automatically when the plugin is enabled)." % int(EVAL_READY_WAIT_SEC))
+		## #518: EVAL_GAME_NOT_READY (not INTERNAL_ERROR) — the play session is up
+		## but the game-side capture didn't register within the short wait. Fast
+		## and caller-actionable; classifying it apart from the opaque 10s hang
+		## keeps the INTERNAL_ERROR telemetry bucket meaning "the eval truly hung".
+		_send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY,
+			"Game-side capture didn't register within %ds. The play session is already running, so the game is most likely still booting — wait a moment and retry. If it persists, the _mcp_game_helper autoload is missing or disabled (Project Settings → Autoload; added automatically when the plugin is enabled), or the game uses a custom main loop." % int(EVAL_READY_WAIT_SEC))
 		return
 	_send_eval(tree, code, request_id, connection, timeout_sec)
 
@@ -448,8 +452,11 @@ func _send_eval(
 ) -> void:
 	var session: EditorDebuggerSession = _first_active_session()
 	if session == null:
-		_send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR,
-			"No active debugger session — is the game actually running?")
+		## #518: capture reported ready but the debugger session is no longer live
+		## (the game just stopped / is restarting) — a not-ready race, so the same
+		## caller-actionable EVAL_GAME_NOT_READY rather than the opaque hang bucket.
+		_send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY,
+			"Game-side capture registered but its debugger session is no longer active — the game likely just stopped or is restarting. Confirm it's running and retry.")
 		return
 
 	var timer: SceneTreeTimer = tree.create_timer(timeout_sec)

plugin/addons/godot_ai/utils/error_codes.gd

@@ -29,6 +29,15 @@ const DEFERRED_TIMEOUT := "DEFERRED_TIMEOUT"
 # game_eval failure codes (#490) — keep in sync with protocol/errors.py
 const EVAL_COMPILE_ERROR := "EVAL_COMPILE_ERROR"
 const EVAL_RUNTIME_ERROR := "EVAL_RUNTIME_ERROR"
+## #518: the play session is up (EditorInterface.is_playing_scene() is true, so
+## editor_handler's EDITOR_NOT_READY "game is not running" gate already passed)
+## but the game-side _mcp_game_helper autoload never registered its debugger
+## capture within EVAL_READY_WAIT_SEC. Carved out of INTERNAL_ERROR so this
+## boot-window / missing-autoload race stops masquerading as the opaque "eval
+## hung" 10s timeout in telemetry — the same split #490 made for compile/runtime
+## errors. NOT a hang: it fires fast (~3s) and is caller-actionable (let the game
+## finish booting and retry, or check the autoload is enabled).
+const EVAL_GAME_NOT_READY := "EVAL_GAME_NOT_READY"
 ## audit-v2 #21 (issue #365): finer-grained codes carved out of the 471
 ## INVALID_PARAMS sites so agents can distinguish recoverable input
 ## errors from structural ones. INVALID_PARAMS stays for genuinely

src/godot_ai/handlers/editor.py

@@ -345,10 +345,13 @@ async def game_eval(runtime: DirectRuntime, code: str) -> dict:
 
     Errors come back fast and actionable (#490): a syntax/parse error returns
     ``EVAL_COMPILE_ERROR`` and a runtime error returns ``EVAL_RUNTIME_ERROR``
-    with the real message and resolved line, instead of a generic timeout. A
-    genuine infinite loop / never-firing await still hits the timeout. Note
-    that ``await`` (timers, signals, frames) only progresses while the game
-    window is focused; a backgrounded play-in-editor game has a frozen idle
-    loop, so an awaiting eval reads as a timeout until the game is focused.
+    with the real message and resolved line, instead of a generic timeout.
+    ``EVAL_GAME_NOT_READY`` (#518) means the play session is up but the
+    game-side capture hasn't registered yet — let the game finish launching and
+    retry, or check the ``_mcp_game_helper`` autoload is enabled. A genuine
+    infinite loop / never-firing await still hits the timeout. Note that
+    ``await`` (timers, signals, frames) only progresses while the game window is
+    focused; a backgrounded play-in-editor game has a frozen idle loop, so an
+    awaiting eval reads as a timeout until the game is focused.
     """
     return await runtime.send_command("game_eval", {"code": code}, timeout=15.0)

src/godot_ai/protocol/errors.py

@@ -18,6 +18,12 @@ class ErrorCode(StrEnum):
     # actionable reply. Keep in sync with utils/error_codes.gd.
     EVAL_COMPILE_ERROR = "EVAL_COMPILE_ERROR"
     EVAL_RUNTIME_ERROR = "EVAL_RUNTIME_ERROR"
+    # #518: the play session is up but the game-side autoload never registered
+    # its debugger capture within the readiness wait (boot-window race, worst on
+    # Windows, or a missing/disabled autoload). Carved out of INTERNAL_ERROR so
+    # this fast (~3s), caller-actionable failure stops being counted as the
+    # opaque "eval hung" 10s timeout. Keep in sync with utils/error_codes.gd.
+    EVAL_GAME_NOT_READY = "EVAL_GAME_NOT_READY"
     ## audit-v2 #21 (issue #365): finer-grained codes carved out of the
     ## 471 INVALID_PARAMS sites so agents can distinguish recoverable
     ## input errors from structural ones. INVALID_PARAMS stays for

src/godot_ai/tools/editor.py

@@ -39,8 +39,10 @@
         'await' so user code can await internally. Errors return fast and
         actionable: EVAL_COMPILE_ERROR for a syntax/parse error,
         EVAL_RUNTIME_ERROR (with the real message + line) for a runtime
-        error; a genuine infinite loop / never-firing await still times out.
-        'await' only progresses while the game window is focused."""
+        error; EVAL_GAME_NOT_READY if the game isn't ready yet — still
+        launching (retry once it's up) or the _mcp_game_helper autoload is
+        missing/disabled; a genuine infinite loop / never-firing await still
+        times out. 'await' only progresses while the game window is focused."""
 
 
 def register_editor_tools(mcp: FastMCP, *, include_non_core: bool = True) -> None:

test_project/tests/test_game_eval_errors.gd

@@ -394,3 +394,28 @@ func test_eval_grace_noop_when_already_compiled() -> void:
 	assert_true(plugin._pending.has(rid), "a compiled eval is untouched by the grace timer")
 	assert_eq(conn.captured.size(), 0, "no compile error for a compiled eval")
 	conn.free()
+
+
+func test_send_eval_without_active_session_replies_game_not_ready() -> void:
+	## #518: with no live debugger session, _send_eval replies with the
+	## caller-actionable EVAL_GAME_NOT_READY rather than the opaque INTERNAL_ERROR
+	## that the telemetry bucket now reserves for a genuine ~10s eval hang. (The
+	## no-session branch returns before touching `tree`, so a bare plugin is safe.)
+	var tree := Engine.get_main_loop() as SceneTree
+	if tree == null:
+		skip("No SceneTree available")
+		return
+	var plugin := McpDebuggerPlugin.new()
+	## Gate BEFORE calling _send_eval: a bare plugin normally has no session, but
+	## if one were present _send_eval would take its live path (arm timers, send a
+	## real mcp:eval into the running game). Skip first so the test never has side
+	## effects in that case rather than bailing after the fact.
+	if plugin._first_active_session() != null:
+		skip("an active debugger session is present; no-session branch not exercised")
+		return
+	var conn := _StubConnection.new()
+	plugin._send_eval(tree, "return 1", "rid-no-session", conn, 10.0)
+	assert_eq(conn.captured.size(), 1, "exactly one deferred reply is sent")
+	assert_eq(conn.captured[0]["payload"]["error"]["code"], ErrorCodes.EVAL_GAME_NOT_READY,
+		"no active debugger session replies with EVAL_GAME_NOT_READY, not INTERNAL_ERROR")
+	conn.free()

tests/unit/test_game_eval.py

@@ -67,9 +67,12 @@ async def test_game_eval_passes_code_verbatim():
 
 
 def test_eval_error_codes_exist():
-    """The two codes the plugin emits for fast game_eval failures."""
+    """The codes the plugin emits for fast game_eval failures."""
     assert ErrorCode.EVAL_COMPILE_ERROR == "EVAL_COMPILE_ERROR"
     assert ErrorCode.EVAL_RUNTIME_ERROR == "EVAL_RUNTIME_ERROR"
+    # #518: the play-session-up-but-capture-not-ready race, carved out of
+    # INTERNAL_ERROR so it stops being counted as a genuine eval hang.
+    assert ErrorCode.EVAL_GAME_NOT_READY == "EVAL_GAME_NOT_READY"
 
 
 class _RaisingGameEvalClient: