fix(game_eval): cap eval readiness wait below the server command timeout (#500)

[dsarno]

Summary

Addresses the residual TimeoutError ~15s bucket in #500 (the larger of the two long-timeout slices the telemetry flagged post-2.5.10).

Root cause

The game_eval editor-side path (mcp_debugger_plugin.gd::request_game_eval → _wait_then_eval) reused GAME_READY_WAIT_SEC = 20.0 — a wait tuned for the screenshot path, where a freshly launched game subprocess can take ~15s to boot and render a first frame.

But the eval path's total editor-side budget is ready_wait + eval_backstop (10s), and the server-side game_eval command timeout is 15s (handlers/editor.py::game_eval, mirrored by the dispatcher's 15000 ms game_eval budget). With a 20s readiness wait, a game that isn't running/ready makes the editor poll past the 15s server deadline, so the server gives up first with an opaque TimeoutError — the editor's actionable "Is the game actually running?" error never reaches the client.

This matches #500's hypothesis exactly: a hang path where "the eval request never reaches game_helper.gd, or no game is running," so only the outer server-side timeout catches it.

Fix

Give eval its own EVAL_READY_WAIT_SEC = 3.0 instead of inheriting the 20s screenshot wait:

• Editor-side worst case is now 3s + 10s backstop = 13s, comfortably under the 15s server timeout, so the fast, actionable error always wins the race instead of an opaque 15s TimeoutError.
• A game launched moments before the eval still has a 3s grace to register its mcp:hello; if it needs longer, the user gets a fast "is it running? start it and retry" message rather than a 15s hang.
• The 20s GAME_READY_WAIT_SEC is unchanged for the screenshot path (which genuinely needs the longer boot window and whose 8s send timeout sits differently).

The TIMEOUT ORDERING comments are updated to document the new invariant: EVAL_READY_WAIT_SEC + eval backstop < server command timeout.

Scope / notes

• The INTERNAL_ERROR ~10s bucket in game_eval: residual ~10–15s timeout failures not caught by the 8s eval bound (#488 follow-up) #500 is the editor-side eval backstop firing on a genuinely stuck/frozen eval (e.g. a backgrounded play-in-editor game with a frozen idle loop, or an infinite loop). That path is already actionable (it returns the "compiled and started running but never returned… likely an infinite loop or never-firing await" message), so this PR leaves it as-is — the opaque TimeoutError bucket was the higher-value target.
• game_command (_wait_then_game_command) shares the same 20s-wait-vs-15s-command-timeout relationship and could get the same treatment, but it isn't in game_eval: residual ~10–15s timeout failures not caught by the 8s eval bound (#488 follow-up) #500's telemetry, so I've kept this change scoped to game_eval. Happy to extend if desired.
• Final confirmation against the telemetry logs (which path each residual failure took) is still the issue's investigative ask and needs the maintainers' data — this PR closes the most likely opaque-timeout path.

Testing

• script/ci-check-gdscript → All GDScript files OK (parse-clean on the import pass).
• Behavioral change is timing-only; logic paths (ready check, send, backstop, grace timer) are unchanged.

https://claude.ai/code/session_01Jq5X4ivngAf1N6r5UX2BVw

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR adjusts the editor-side game_eval “wait for game readiness” window so it can’t outlast the 15s server/dispatcher game_eval timeout, preventing opaque ~15s TimeoutError failures and allowing the editor to return a faster, actionable “game not running/ready” error instead.

Changes:

• Introduces a dedicated EVAL_READY_WAIT_SEC = 3.0 (separate from the 20s screenshot readiness wait).
• Updates game_eval’s readiness polling deadline to use EVAL_READY_WAIT_SEC.
• Expands the inline timeout-ordering documentation around game_eval to capture the new invariant (ready_wait + backstop < 15s).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.