Cross-platform desktop automation: how to verify the runtime is actually healthy before you click

The contract is the same on both platforms

Every platform implements one Rust trait, PlatformHealthCheck, and returns one shape, HealthCheckResult. The convenience function check_automation_health() picks the right implementation at compile time using cfg(target_os = "..."). That is the part that makes cross-platform verify actually portable: a single client can poll one URL and reason about one JSON object regardless of whether the agent is sitting on Windows or macOS.

What the call looks like in flight

The CI runner hits one HTTP endpoint. Inside the process, the readiness handler calls the shared probe, which dispatches to the platform implementation, which talks to the native automation API. Every step is bounded.

The Windows probe is a five-step check with a hard timeout

On Windows the verify path is real work: COM init, UIAutomation construction, desktop root, enumeration, status rollup. The whole sequence runs inside tokio::time::timeout(Duration::from_secs(5), ...), so a hung COM call returns a clean 503 with an error string instead of taking the readiness lane offline.

File: crates/terminator/src/platforms/windows/health.rs. The timeout is on line 35, COM init around line 70, the UIAutomation construction around line 91, the root element retrieval around line 107. Headless detection lives in the same file via is_headless_environment() and surfaces in the diagnostics bag rather than silently failing the check.

A healthy response, and an unhealthy one

The body is small enough to read in one breath. On a working Windows session you get a 200 with three trues and a duration. On a wedged session you get a 503 with the timeout string.

What verify means on macOS today

The MacOSHealthChecker in health.rs currently returns an optimistic Healthy result with a diagnostic note that reads Accessibility API health checks not yet implemented. That is the right behavior for a stub: it is honest, the field is in the JSON, and a caller that cares can branch on it. Until the AX-level probe lands, treat the macOS /ready response as a liveness signal that the agent is up and Cocoa is reachable, and rely on a small canary script (open a known app, query the AX tree of its window) for harder verification.

The two trapdoors that bite on macOS are TCC permissions and a non-interactive session. TCC denials show up as empty AX trees rather than errors, which is why the planned macOS probe will need to actually walk a known window, not just instantiate the AX client. The Linux branch in the same file has the same shape and the same honest TODO.

How this changes your CI lane

The shape of a desktop automation job becomes the same on both operating systems. Boot the agent, poll /ready until the rolled-up status is ready (or treat degraded as acceptable if you have made that call), then run the actual scenario. If a scenario then fails, you have a real bisect: was /ready healthy a moment before? If yes, the failure is in your selector or the app under test. If no, the runtime broke and the scenario was never going to pass. That bisect is the whole point.

The cost of adding this gate is negligible. The probe runs in a couple hundred milliseconds on a warm Windows runner, the timeout caps the worst case at five seconds, and a status-code check is one line of bash or one assertion in your test runner. The cost of not adding it is the class of flake that every long-lived desktop suite eventually accumulates, where one machine in the pool quietly degrades and every scenario fails for reasons that have nothing to do with the code under test.