mcpforunityserver 8.7.0__py3-none-any.whl → 9.1.0__py3-none-any.whl

services/tools/preflight.py

@@ -42,11 +42,12 @@ async def preflight(
     if _in_pytest():
         return None
 
-    # Load canonical v2 state (server enriches advice + staleness).
+    # Load canonical editor state (server enriches advice + staleness).
     try:
-        from services.resources.editor_state_v2 import get_editor_state_v2
-        state_resp = await get_editor_state_v2(ctx)
-        state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
+        from services.resources.editor_state import get_editor_state
+        state_resp = await get_editor_state(ctx)
+        state = state_resp.model_dump() if hasattr(
+            state_resp, "model_dump") else state_resp
     except Exception:
         # If we cannot determine readiness, fall back to proceeding (tools already contain retry logic).
         return None
@@ -80,9 +81,12 @@ async def preflight(
     if wait_for_no_compile:
         deadline = time.monotonic() + float(max_wait_s)
         while True:
-            compilation = data.get("compilation") if isinstance(data, dict) else None
-            is_compiling = isinstance(compilation, dict) and compilation.get("is_compiling") is True
-            is_domain_reload_pending = isinstance(compilation, dict) and compilation.get("is_domain_reload_pending") is True
+            compilation = data.get("compilation") if isinstance(
+                data, dict) else None
+            is_compiling = isinstance(compilation, dict) and compilation.get(
+                "is_compiling") is True
+            is_domain_reload_pending = isinstance(compilation, dict) and compilation.get(
+                "is_domain_reload_pending") is True
             if not is_compiling and not is_domain_reload_pending:
                 break
             if time.monotonic() >= deadline:
@@ -91,9 +95,10 @@ async def preflight(
 
             # Refresh state for the next loop iteration.
             try:
-                from services.resources.editor_state_v2 import get_editor_state_v2
-                state_resp = await get_editor_state_v2(ctx)
-                state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
+                from services.resources.editor_state import get_editor_state
+                state_resp = await get_editor_state(ctx)
+                state = state_resp.model_dump() if hasattr(
+                    state_resp, "model_dump") else state_resp
                 data = state.get("data") if isinstance(state, dict) else None
                 if not isinstance(data, dict):
                     return None
@@ -103,5 +108,3 @@ async def preflight(
     # Staleness: if the snapshot is stale, proceed (tools will still run), but callers that read resources can back off.
     # In future we may make this strict for some tools.
     return None
-
-

services/tools/read_console.py

@@ -4,27 +4,44 @@ Defines the read_console tool for accessing Unity Editor console messages.
 from typing import Annotated, Any, Literal
 
 from fastmcp import Context
+from mcp.types import ToolAnnotations
+
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
-from services.tools.utils import coerce_int, coerce_bool
+from services.tools.utils import coerce_int, coerce_bool, parse_json_payload
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 
 
+def _strip_stacktrace_from_list(items: list) -> None:
+    """Remove stacktrace fields from a list of log entries."""
+    for item in items:
+        if isinstance(item, dict) and "stacktrace" in item:
+            item.pop("stacktrace", None)
+
+
 @mcp_for_unity_tool(
-    description="Gets messages from or clears the Unity Editor console. Note: For maximum client compatibility, pass count as a quoted string (e.g., '5')."
+    description="Gets messages from or clears the Unity Editor console. Defaults to 10 most recent entries. Use page_size/cursor for paging. Note: For maximum client compatibility, pass count as a quoted string (e.g., '5'). The 'get' action is read-only; 'clear' modifies ephemeral UI state (not project data).",
+    annotations=ToolAnnotations(
+        title="Read Console",
+    ),
 )
 async def read_console(
     ctx: Context,
     action: Annotated[Literal['get', 'clear'],
                       "Get or clear the Unity Editor console. Defaults to 'get' if omitted."] | None = None,
     types: Annotated[list[Literal['error', 'warning',
-                                  'log', 'all']], "Message types to get"] | None = None,
+                                  'log', 'all']] | str,
+                     "Message types to get (accepts list or JSON string)"] | None = None,
     count: Annotated[int | str,
-                     "Max messages to return (accepts int or string, e.g., 5 or '5')"] | None = None,
+                     "Max messages to return in non-paging mode (accepts int or string, e.g., 5 or '5'). Ignored when paging with page_size/cursor."] | None = None,
     filter_text: Annotated[str, "Text filter for messages"] | None = None,
     since_timestamp: Annotated[str,
                                "Get messages after this timestamp (ISO 8601)"] | None = None,
+    page_size: Annotated[int | str,
+                         "Page size for paginated console reads. Defaults to 50 when omitted."] | None = None,
+    cursor: Annotated[int | str,
+                      "Opaque cursor for paging (0-based offset). Defaults to 0."] | None = None,
     format: Annotated[Literal['plain', 'detailed',
                               'json'], "Output format"] | None = None,
     include_stacktrace: Annotated[bool | str,
@@ -35,11 +52,48 @@ async def read_console(
     unity_instance = get_unity_instance_from_context(ctx)
     # Set defaults if values are None
     action = action if action is not None else 'get'
-    types = types if types is not None else ['error', 'warning', 'log']
-    format = format if format is not None else 'detailed'
+    
+    # Parse types if it's a JSON string (handles client compatibility issue #561)
+    if isinstance(types, str):
+        types = parse_json_payload(types)
+    # Validate types is a list after parsing
+    if types is not None and not isinstance(types, list):
+        return {
+            "success": False,
+            "message": (
+                f"types must be a list, got {type(types).__name__}. "
+                "If passing as JSON string, use format: '[\"error\", \"warning\"]'"
+            )
+        }
+    if types is not None:
+        allowed_types = {"error", "warning", "log", "all"}
+        normalized_types = []
+        for entry in types:
+            if not isinstance(entry, str):
+                return {
+                    "success": False,
+                    "message": f"types entries must be strings, got {type(entry).__name__}"
+                }
+            normalized = entry.strip().lower()
+            if normalized not in allowed_types:
+                return {
+                    "success": False,
+                    "message": (
+                        f"invalid types entry '{entry}'. "
+                        f"Allowed values: {sorted(allowed_types)}"
+                    )
+                }
+            normalized_types.append(normalized)
+        types = normalized_types
+    else:
+        types = ['error', 'warning', 'log']
+    
+    format = format if format is not None else 'plain'
     # Coerce booleans defensively (strings like 'true'/'false')
 
-    include_stacktrace = coerce_bool(include_stacktrace, default=True)
+    include_stacktrace = coerce_bool(include_stacktrace, default=False)
+    coerced_page_size = coerce_int(page_size, default=None)
+    coerced_cursor = coerce_int(cursor, default=None)
 
     # Normalize action if it's a string
     if isinstance(action, str):
@@ -56,7 +110,7 @@ async def read_console(
         count = coerce_int(count)
 
     if action == "get" and count is None:
-        count = 200
+        count = 10
 
     # Prepare parameters for the C# handler
     params_dict = {
@@ -65,6 +119,8 @@ async def read_console(
         "count": count,
         "filterText": filter_text,
         "sinceTimestamp": since_timestamp,
+        "pageSize": coerced_page_size,
+        "cursor": coerced_cursor,
         "format": format.lower() if isinstance(format, str) else format,
         "includeStacktrace": include_stacktrace
     }
@@ -83,16 +139,13 @@ async def read_console(
         # Strip stacktrace fields from returned lines if present
         try:
             data = resp.get("data")
-            # Handle standard format: {"data": {"lines": [...]}}
-            if isinstance(data, dict) and "lines" in data and isinstance(data["lines"], list):
-                for line in data["lines"]:
-                    if isinstance(line, dict) and "stacktrace" in line:
-                        line.pop("stacktrace", None)
-            # Handle legacy/direct list format if any
+            if isinstance(data, dict):
+                for key in ("lines", "items"):
+                    if key in data and isinstance(data[key], list):
+                        _strip_stacktrace_from_list(data[key])
+                        break
             elif isinstance(data, list):
-                for line in data:
-                    if isinstance(line, dict) and "stacktrace" in line:
-                        line.pop("stacktrace", None)
+                _strip_stacktrace_from_list(data)
         except Exception:
             pass
     return resp if isinstance(resp, dict) else {"success": False, "message": str(resp)}

services/tools/refresh_unity.py

@@ -1,28 +1,40 @@
 from __future__ import annotations
 
 import asyncio
+import logging
 import time
 from typing import Annotated, Any, Literal
 
 from fastmcp import Context
+from mcp.types import ToolAnnotations
 
 from models import MCPResponse
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
 import transport.unity_transport as unity_transport
-from transport.legacy.unity_connection import async_send_command_with_retry
+from transport.legacy.unity_connection import async_send_command_with_retry, _extract_response_reason
 from services.state.external_changes_scanner import external_changes_scanner
+import services.resources.editor_state as editor_state
+
+logger = logging.getLogger(__name__)
 
 
 @mcp_for_unity_tool(
-    description="Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness."
+    description="Request a Unity asset database refresh and optionally a script compilation. Can optionally wait for readiness.",
+    annotations=ToolAnnotations(
+        title="Refresh Unity",
+        destructiveHint=True,
+    ),
 )
 async def refresh_unity(
     ctx: Context,
     mode: Annotated[Literal["if_dirty", "force"], "Refresh mode"] = "if_dirty",
-    scope: Annotated[Literal["assets", "scripts", "all"], "Refresh scope"] = "all",
-    compile: Annotated[Literal["none", "request"], "Whether to request compilation"] = "none",
-    wait_for_ready: Annotated[bool, "If true, wait until editor_state.advice.ready_for_tools is true"] = True,
+    scope: Annotated[Literal["assets", "scripts", "all"],
+                     "Refresh scope"] = "all",
+    compile: Annotated[Literal["none", "request"],
+                       "Whether to request compilation"] = "none",
+    wait_for_ready: Annotated[bool,
+                              "If true, wait until editor_state.advice.ready_for_tools is true"] = True,
 ) -> MCPResponse | dict[str, Any]:
     unity_instance = get_unity_instance_from_context(ctx)
 
@@ -34,45 +46,98 @@ async def refresh_unity(
     }
 
     recovered_from_disconnect = False
+    # Don't retry on reload - refresh_unity triggers compilation/reload,
+    # so retrying would cause multiple reloads (issue #577)
     response = await unity_transport.send_with_unity_instance(
         async_send_command_with_retry,
         unity_instance,
         "refresh_unity",
         params,
+        retry_on_reload=False,
     )
 
-    # Option A: treat disconnects / retry hints as recoverable when wait_for_ready is true.
-    # Unity can legitimately disconnect during refresh/compile/domain reload, so callers should not
-    # interpret that as a hard failure (#503-style loops).
-    if isinstance(response, dict) and not response.get("success", True):
-        hint = response.get("hint")
-        err = (response.get("error") or response.get("message") or "")
-        is_retryable = (hint == "retry") or ("disconnected" in str(err).lower())
-        if (not wait_for_ready) or (not is_retryable):
-            return MCPResponse(**response)
-        recovered_from_disconnect = True
+    # Handle connection errors during refresh/compile gracefully.
+    # Unity disconnects during domain reload, which is expected behavior - not a failure.
+    # If we sent the command and connection closed, the refresh was likely triggered successfully.
+    # Convert MCPResponse to dict if needed
+    response_dict = response if isinstance(response, dict) else (response.model_dump() if hasattr(response, "model_dump") else response.__dict__)
+    if not response_dict.get("success", True):
+        hint = response_dict.get("hint")
+        err = (response_dict.get("error") or response_dict.get("message") or "").lower()
+        reason = _extract_response_reason(response_dict)
+
+        # Connection closed/timeout during compile = refresh was triggered, Unity is reloading
+        # This is SUCCESS, not failure - don't return error to prevent Claude Code from retrying
+        is_connection_lost = (
+            "connection closed" in err
+            or "disconnected" in err
+            or "aborted" in err  # WinError 10053: connection aborted
+            or "timeout" in err
+            or reason == "reloading"
+        )
+
+        if is_connection_lost and compile == "request":
+            # EXPECTED BEHAVIOR: When compile="request", Unity triggers domain reload which
+            # causes connection to close mid-command. This is NOT a failure - the refresh
+            # was successfully triggered. Treating this as success prevents Claude Code from
+            # retrying unnecessarily (which would cause multiple domain reloads - issue #577).
+            # The subsequent wait_for_ready loop (below) will verify Unity becomes ready.
+            logger.info("refresh_unity: Connection lost during compile (expected - domain reload triggered)")
+            recovered_from_disconnect = True
+        elif hint == "retry" or "could not connect" in err:
+            # Retryable error - proceed to wait loop if wait_for_ready
+            if not wait_for_ready:
+                return MCPResponse(**response_dict)
+            recovered_from_disconnect = True
+        else:
+            # Non-recoverable error - connection issue unrelated to domain reload
+            logger.warning(f"refresh_unity: Non-recoverable error (compile={compile}): {err[:100]}")
+            return MCPResponse(**response_dict)
 
     # Optional server-side wait loop (defensive): if Unity tool doesn't wait or returns quickly,
-    # poll the canonical editor_state v2 resource until ready or timeout.
+    # poll the canonical editor_state resource until ready or timeout.
+    ready_confirmed = False
     if wait_for_ready:
         timeout_s = 60.0
         start = time.monotonic()
-        from services.resources.editor_state_v2 import get_editor_state_v2
+
+        # Blocking reasons that indicate Unity is actually busy (not just stale status)
+        # Must match activityPhase values from EditorStateCache.cs
+        real_blocking_reasons = {"compiling", "domain_reload", "running_tests", "asset_import"}
 
         while time.monotonic() - start < timeout_s:
-            state_resp = await get_editor_state_v2(ctx)
-            state = state_resp.model_dump() if hasattr(state_resp, "model_dump") else state_resp
-            data = (state or {}).get("data") if isinstance(state, dict) else None
-            advice = (data or {}).get("advice") if isinstance(data, dict) else None
-            if isinstance(advice, dict) and advice.get("ready_for_tools") is True:
-                break
+            state_resp = await editor_state.get_editor_state(ctx)
+            state = state_resp.model_dump() if hasattr(
+                state_resp, "model_dump") else state_resp
+            data = (state or {}).get("data") if isinstance(
+                state, dict) else None
+            advice = (data or {}).get(
+                "advice") if isinstance(data, dict) else None
+            if isinstance(advice, dict):
+                # Exit if ready_for_tools is True
+                if advice.get("ready_for_tools") is True:
+                    ready_confirmed = True
+                    break
+                # Also exit if the only blocking reason is "stale_status" (Unity in background)
+                # Staleness means we can't confirm status, not that Unity is actually busy
+                blocking = set(advice.get("blocking_reasons") or [])
+                if not (blocking & real_blocking_reasons):
+                    ready_confirmed = True  # No real blocking reasons, consider ready
+                    break
             await asyncio.sleep(0.25)
 
+        # If we timed out without confirming readiness, log and return failure
+        if not ready_confirmed:
+            logger.warning(f"refresh_unity: Timed out after {timeout_s}s waiting for editor to become ready")
+            return MCPResponse(
+                success=False,
+                message=f"Refresh triggered but timed out after {timeout_s}s waiting for editor readiness.",
+                data={"timeout": True, "wait_seconds": timeout_s},
+            )
+
     # After readiness is restored, clear any external-dirty flag for this instance so future tools can proceed cleanly.
     try:
-        from services.resources.editor_state_v2 import _infer_single_instance_id
-
-        inst = unity_instance or await _infer_single_instance_id(ctx)
+        inst = unity_instance or await editor_state.infer_single_instance_id(ctx)
         if inst:
             external_changes_scanner.clear_dirty(inst)
     except Exception:
@@ -85,6 +150,4 @@ async def refresh_unity(
             data={"recovered_from_disconnect": True},
         )
 
-    return MCPResponse(**response) if isinstance(response, dict) else response
-
-
+    return MCPResponse(**response_dict) if isinstance(response, dict) else response

services/tools/run_tests.py

@@ -1,16 +1,24 @@
-"""Tool for executing Unity Test Runner suites."""
-from typing import Annotated, Literal, Any
+"""Async Unity Test Runner jobs: start + poll."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Annotated, Any, Literal
 
 from fastmcp import Context
-from pydantic import BaseModel, Field
+from mcp.types import ToolAnnotations
+from pydantic import BaseModel
 
 from models import MCPResponse
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
-from services.tools.utils import coerce_int
-from transport.unity_transport import send_with_unity_instance
-from transport.legacy.unity_connection import async_send_command_with_retry
 from services.tools.preflight import preflight
+import transport.unity_transport as unity_transport
+from transport.legacy.unity_connection import async_send_command_with_retry
+from utils.focus_nudge import nudge_unity_focus, should_nudge
+
+logger = logging.getLogger(__name__)
 
 
 class RunTestsSummary(BaseModel):
@@ -38,31 +46,83 @@ class RunTestsResult(BaseModel):
     results: list[RunTestsTestResult] | None = None
 
 
-class RunTestsResponse(MCPResponse):
-    data: RunTestsResult | None = None
+class RunTestsStartData(BaseModel):
+    job_id: str
+    status: str
+    mode: str | None = None
+    include_details: bool | None = None
+    include_failed_tests: bool | None = None
+
+
+class RunTestsStartResponse(MCPResponse):
+    data: RunTestsStartData | None = None
+
+
+class TestJobFailure(BaseModel):
+    full_name: str | None = None
+    message: str | None = None
+
+
+class TestJobProgress(BaseModel):
+    completed: int | None = None
+    total: int | None = None
+    current_test_full_name: str | None = None
+    current_test_started_unix_ms: int | None = None
+    last_finished_test_full_name: str | None = None
+    last_finished_unix_ms: int | None = None
+    stuck_suspected: bool | None = None
+    editor_is_focused: bool | None = None
+    blocked_reason: str | None = None
+    failures_so_far: list[TestJobFailure] | None = None
+    failures_capped: bool | None = None
+
+
+class GetTestJobData(BaseModel):
+    job_id: str
+    status: str
+    mode: str | None = None
+    started_unix_ms: int | None = None
+    finished_unix_ms: int | None = None
+    last_update_unix_ms: int | None = None
+    progress: TestJobProgress | None = None
+    error: str | None = None
+    result: RunTestsResult | None = None
+
+
+class GetTestJobResponse(MCPResponse):
+    data: GetTestJobData | None = None
 
 
 @mcp_for_unity_tool(
-    description="Runs Unity tests synchronously (blocks until complete). Prefer run_tests_async for non-blocking execution with progress polling."
+    description="Starts a Unity test run asynchronously and returns a job_id immediately. Poll with get_test_job for progress.",
+    annotations=ToolAnnotations(
+        title="Run Tests",
+        destructiveHint=True,
+    ),
 )
 async def run_tests(
     ctx: Context,
-    mode: Annotated[Literal["EditMode", "PlayMode"], "Unity test mode to run"] = "EditMode",
-    timeout_seconds: Annotated[int | str, "Optional timeout in seconds for the test run"] | None = None,
-    test_names: Annotated[list[str] | str, "Full names of specific tests to run (e.g., 'MyNamespace.MyTests.TestMethod')"] | None = None,
-    group_names: Annotated[list[str] | str, "Same as test_names, except it allows for Regex"] | None = None,
-    category_names: Annotated[list[str] | str, "NUnit category names to filter by (tests marked with [Category] attribute)"] | None = None,
-    assembly_names: Annotated[list[str] | str, "Assembly names to filter tests by"] | None = None,
-    include_failed_tests: Annotated[bool, "Include details for failed/skipped tests only (default: false)"] = False,
-    include_details: Annotated[bool, "Include details for all tests (default: false)"] = False,
-) -> RunTestsResponse | MCPResponse:
+    mode: Annotated[Literal["EditMode", "PlayMode"],
+                    "Unity test mode to run"] = "EditMode",
+    test_names: Annotated[list[str] | str,
+                          "Full names of specific tests to run"] | None = None,
+    group_names: Annotated[list[str] | str,
+                           "Same as test_names, except it allows for Regex"] | None = None,
+    category_names: Annotated[list[str] | str,
+                              "NUnit category names to filter by"] | None = None,
+    assembly_names: Annotated[list[str] | str,
+                              "Assembly names to filter tests by"] | None = None,
+    include_failed_tests: Annotated[bool,
+                                    "Include details for failed/skipped tests only (default: false)"] = False,
+    include_details: Annotated[bool,
+                               "Include details for all tests (default: false)"] = False,
+) -> RunTestsStartResponse | MCPResponse:
     unity_instance = get_unity_instance_from_context(ctx)
 
     gate = await preflight(ctx, requires_no_tests=True, wait_for_no_compile=True, refresh_if_dirty=True)
     if isinstance(gate, MCPResponse):
         return gate
 
-    # Coerce string or list to list of strings
     def _coerce_string_list(value) -> list[str] | None:
         if value is None:
             return None
@@ -74,47 +134,121 @@ async def run_tests(
         return None
 
     params: dict[str, Any] = {"mode": mode}
-    ts = coerce_int(timeout_seconds)
-    if ts is not None:
-        params["timeoutSeconds"] = ts
+    if (t := _coerce_string_list(test_names)):
+        params["testNames"] = t
+    if (g := _coerce_string_list(group_names)):
+        params["groupNames"] = g
+    if (c := _coerce_string_list(category_names)):
+        params["categoryNames"] = c
+    if (a := _coerce_string_list(assembly_names)):
+        params["assemblyNames"] = a
+    if include_failed_tests:
+        params["includeFailedTests"] = True
+    if include_details:
+        params["includeDetails"] = True
 
-    # Add filter parameters if provided
-    test_names_list = _coerce_string_list(test_names)
-    if test_names_list:
-        params["testNames"] = test_names_list
+    response = await unity_transport.send_with_unity_instance(
+        async_send_command_with_retry,
+        unity_instance,
+        "run_tests",
+        params,
+    )
 
-    group_names_list = _coerce_string_list(group_names)
-    if group_names_list:
-        params["groupNames"] = group_names_list
+    if isinstance(response, dict):
+        if not response.get("success", True):
+            return MCPResponse(**response)
+        return RunTestsStartResponse(**response)
+    return MCPResponse(success=False, error=str(response))
 
-    category_names_list = _coerce_string_list(category_names)
-    if category_names_list:
-        params["categoryNames"] = category_names_list
 
-    assembly_names_list = _coerce_string_list(assembly_names)
-    if assembly_names_list:
-        params["assemblyNames"] = assembly_names_list
+@mcp_for_unity_tool(
+    description="Polls an async Unity test job by job_id.",
+    annotations=ToolAnnotations(
+        title="Get Test Job",
+        readOnlyHint=True,
+    ),
+)
+async def get_test_job(
+    ctx: Context,
+    job_id: Annotated[str, "Job id returned by run_tests"],
+    include_failed_tests: Annotated[bool,
+                                    "Include details for failed/skipped tests only (default: false)"] = False,
+    include_details: Annotated[bool,
+                               "Include details for all tests (default: false)"] = False,
+    wait_timeout: Annotated[int | None,
+                            "If set, wait up to this many seconds for tests to complete before returning. "
+                            "Reduces polling frequency and avoids client-side loop detection. "
+                            "Recommended: 30-60 seconds. Returns immediately if tests complete sooner."] = None,
+) -> GetTestJobResponse | MCPResponse:
+    unity_instance = get_unity_instance_from_context(ctx)
 
-    # Add verbosity parameters
+    params: dict[str, Any] = {"job_id": job_id}
     if include_failed_tests:
         params["includeFailedTests"] = True
     if include_details:
         params["includeDetails"] = True
 
-    response = await send_with_unity_instance(async_send_command_with_retry, unity_instance, "run_tests", params)
-
-    # If Unity indicates a run is already active, return a structured "busy" response rather than
-    # letting clients interpret this as a generic failure (avoids #503 retry loops).
-    if isinstance(response, dict) and not response.get("success", True):
-        err = (response.get("error") or response.get("message") or "").strip()
-        if "test run is already in progress" in err.lower():
-            return MCPResponse(
-                success=False,
-                error="tests_running",
-                message=err,
-                hint="retry",
-                data={"reason": "tests_running", "retry_after_ms": 5000},
-            )
-        return MCPResponse(**response)
-
-    return RunTestsResponse(**response) if isinstance(response, dict) else response
+    async def _fetch_status() -> dict[str, Any]:
+        return await unity_transport.send_with_unity_instance(
+            async_send_command_with_retry,
+            unity_instance,
+            "get_test_job",
+            params,
+        )
+
+    # If wait_timeout is specified, poll server-side until complete or timeout
+    if wait_timeout and wait_timeout > 0:
+        deadline = asyncio.get_event_loop().time() + wait_timeout
+        poll_interval = 2.0  # Poll Unity every 2 seconds
+
+        while True:
+            response = await _fetch_status()
+
+            if not isinstance(response, dict):
+                return MCPResponse(success=False, error=str(response))
+
+            if not response.get("success", True):
+                return MCPResponse(**response)
+
+            # Check if tests are done
+            data = response.get("data", {})
+            status = data.get("status", "")
+            if status in ("succeeded", "failed", "cancelled"):
+                return GetTestJobResponse(**response)
+
+            # Check if Unity needs a focus nudge to make progress
+            # This handles OS-level throttling (e.g., macOS App Nap) that can
+            # stall PlayMode tests when Unity is in the background.
+            progress = data.get("progress", {})
+            editor_is_focused = progress.get("editor_is_focused", True)
+            last_update_unix_ms = data.get("last_update_unix_ms")
+            current_time_ms = int(time.time() * 1000)
+
+            if should_nudge(
+                status=status,
+                editor_is_focused=editor_is_focused,
+                last_update_unix_ms=last_update_unix_ms,
+                current_time_ms=current_time_ms,
+                stall_threshold_ms=10_000,  # 10 seconds without progress
+            ):
+                logger.info(f"Test job {job_id} appears stalled (unfocused Unity), attempting nudge...")
+                nudged = await nudge_unity_focus(focus_duration_s=0.5)
+                if nudged:
+                    logger.info(f"Test job {job_id} nudge completed")
+
+            # Check timeout
+            remaining = deadline - asyncio.get_event_loop().time()
+            if remaining <= 0:
+                # Timeout reached, return current status
+                return GetTestJobResponse(**response)
+
+            # Wait before next poll (but don't exceed remaining time)
+            await asyncio.sleep(min(poll_interval, remaining))
+    
+    # No wait_timeout - return immediately (original behavior)
+    response = await _fetch_status()
+    if isinstance(response, dict):
+        if not response.get("success", True):
+            return MCPResponse(**response)
+        return GetTestJobResponse(**response)
+    return MCPResponse(success=False, error=str(response))