fix(computer_use): pass --no-overlay to cua-driver on Linux/WSL2 to prevent idle CPU

[DavidMetcalfe]

Bug Description

cua-driver's cursor overlay rendering loop can consume CPU indefinitely when idle. On Linux/WSL2, the overlay has no visual benefit and is the primary source of idle CPU usage (~52% reported). On macOS, the overlay's vImage buffer setup can enter an infinite redraw loop at 105%+ CPU (#28152, #47032).

Fixes #28152

Root Cause

The cursor overlay rendered by cua-driver runs a CoreAnimation redraw loop that, on Linux/WSL2, spins continuously even with no work to do. On macOS, a vImage buffer sizing mismatch causes the same loop to error and retry indefinitely. The --no-overlay flag (cua-driver ≥ 0.6.x) suppresses the overlay entirely.

Hermes never passed this flag, so all users got the overlay regardless of platform or need.

Fix

• Add computer_use.no_overlay config option (default: None = auto-detect)
• Auto-detection disables the overlay on Linux (covers WSL2, headless, containers) where it has no visual purpose
• macOS and Windows keep the overlay by default (visually useful there)
• Explicit true/false in config overrides auto-detection
• Follows the existing computer_use.cua_telemetry config pattern

How to Verify

1. On Linux/WSL2: run hermes computer-use — cua-driver should start with --no-overlay, CPU idle near 0%
2. On macOS: overlay should still appear by default (auto-detect enables it)
3. Set computer_use.no_overlay: true in config.yaml — overlay disabled regardless of platform
4. Run python -m pytest tests/computer_use/test_cua_no_overlay.py -v — 10 tests pass

Test Plan

• Added regression tests for auto-detection, config override, and arg construction (10 tests)
• Existing tests still pass (201/201)
• Manual verification on Linux/WSL2 (community reporter confirmed --no-overlay works)

Risk Assessment

Low — config-only change with safe defaults. Auto-detection only affects Linux where the overlay has no benefit. macOS/Windows behavior unchanged. Older cua-driver versions that don't support --no-overlay will reject the flag; callers should fall back gracefully (already handled by existing spawn error handling).

[tonydwb]

Code Review Summary

Verdict: Approved

cua-driver --no-overlay flag on Linux/WSL2 (4 files). Platform-specific CPU fix:

• New computer_use.no_overlay config option (None=True/False/auto-detect)
• Auto-detect: disables overlay on Linux without DISPLAY (headless/WSL2)
• Config version bumped from 31 to 32
• Comprehensive test suite: 132 lines covering auto-detect, explicit override, version probe
• Tests use proper mocking of platform, env, and config

Good fix for idle CPU consumption. The auto-detect approach is sensible.

[lincoln-mackay]

@DavidMetcalfe are you able to merge this now it's been approved by @tonydwb please

[teknium1]

Thanks for addressing the documented idle CPU issue. The current origin/main MCP path still launches the resolved driver without an overlay policy (tools/computer_use/cua_backend.py:144-195, :617-624), so the underlying fix remains needed.

Problems

• tools/computer_use/cua_backend.py:260 adds a cua-driver --help subprocess without env=. Current main sanitizes every third-party cua-driver spawn, including manifest discovery (:163-171) and update checking (:253-264); this new probe must use the same sanitized environment.
• tools/computer_use/cua_backend.py:238 returns the manifest's command, but _mcp_args_with_overlay_flag() defaults its probe to _CUA_DRIVER_CMD. When manifest discovery relocates the executable, the support check can inspect a different binary from the one launched.
• hermes_cli/config.py:3178 bumps _config_version for an additive default. AGENTS.md:586-590 specifies that deep merge handles new keys in existing sections without a version bump.

Suggested changes

• Sanitize the help-probe environment, pass the effective resolved command into the support check, and cover a manifest command differing from driver_cmd.
• Remove the schema-version bump and document computer_use.no_overlay beside the existing telemetry configuration.

Automated hermes-sweeper review.

[teknium1]

This manifest branch launches command, but the helper defaults to _CUA_DRIVER_CMD; a relocated manifest executable can therefore be probed for --no-overlay on the wrong binary. Pass command here (and driver_cmd on fallback paths) and add a differing-command regression case.

[DavidMetcalfe]

Good catch — addressed in the latest push. Both findings fixed in commit 176e0876f on the same PR.

1. --help subprocess env sanitization (cua_backend.py:260): Added env=_sanitize_subprocess_env(cua_driver_child_env()) with the same lazy import + rationale comment as the manifest probe at :214. The --help subprocess now matches the policy of every other cua-driver spawn site (manifest probe, MCP spawn, install probe).

2. Manifest command not in support check (cua_backend.py:238): The command returned by the manifest is now passed into _mcp_args_with_overlay_flag via driver_cmd=command. The fallback path (no command in manifest) uses driver_cmd=driver_cmd to keep the existing input-driver semantics. The lru_cache on _cua_driver_supports_no_overlay is keyed on driver_cmd, so each binary gets its own cached verdict — no cross-binary cache leakage.

3. _config_version bump: Resolved by cherry-picking the PR onto current origin/main (already at 33). The original commit's bump to 32 was dropped during the conflict resolution — hermes_cli/config.py:3394 correctly stays at 33 with no bump for the additive no_overlay default.

Four new tests in tests/computer_use/test_cua_no_overlay.py:

• test_help_probe_passes_sanitized_env — verifies subprocess.run is called with env=.
• test_manifest_command_drives_support_probe — verifies the probe uses the manifest command when it differs from the input driver_cmd.
• test_fallback_uses_input_driver_cmd_for_support_probe — verifies the fallback path uses the input driver_cmd.
• test_probe_distinguishes_support_between_binaries — sanity check on the lru_cache key.

File-revert negative test confirmed all three of the new "manifest/probe" tests are load-bearing: they fail pre-fix and pass post-fix. 20/20 in tests/computer_use/test_cua_no_overlay.py, 50/50 in tests/computer_use/, and the existing TestMcpInvocationResolution (8/8) in tests/tools/test_computer_use.py still green.

[teknium1]

This new third-party subprocess inherits the full parent environment. Match the current manifest/update-check policy with env=_sanitize_subprocess_env(cua_driver_child_env()) so provider credentials are not exposed to cua-driver --help.

[DavidMetcalfe]

Good catch — addressed in the latest push (commit 176e0876f on this PR).

The cua-driver --help subprocess at :260 now passes env=_sanitize_subprocess_env(cua_driver_child_env()) with the same lazy import + rationale comment as the manifest probe at :214. cua-driver is a third-party binary, and every other spawn site in this file (manifest probe, MCP spawn, install probe) already uses the sanitized env. The --help probe now matches.

Regression test added: TestDriverSupportsNoOverlay.test_help_probe_passes_sanitized_env in tests/computer_use/test_cua_no_overlay.py — verifies subprocess.run is called with env= and that the env is non-None. File-revert negative test confirms it's load-bearing (fails pre-fix, passes post-fix).

[DavidMetcalfe]

Quick follow-up on the third finding from review #4701565902 (the _config_version additive-default bump concern) — this is resolved by the rebase onto current origin/main rather than a code change.

The original PR commit ee4a69fc bumped _config_version 31 → 32 for computer_use.no_overlay: None (additive default). After cherry-picking onto current origin/main (now at 33), the conflict resolution kept main's 33 — the original PR's bump is effectively dropped. hermes_cli/config.py:3394 correctly stays at 33, with no bump for the additive key, consistent with AGENTS.md's "deep merge handles new keys in existing sections without a version bump."

So no further code change needed for that finding. All three findings from the review are now resolved on this branch (force-pushed as 176e0876f):

• env sanitization: fixed at tools/computer_use/cua_backend.py:264-272
• manifest command in support check: fixed at tools/computer_use/cua_backend.py:235-242
• _config_version bump: dropped via rebase conflict resolution

20/20 in tests/computer_use/test_cua_no_overlay.py, 50/50 in tests/computer_use/, and the existing TestMcpInvocationResolution (8/8) in tests/tools/test_computer_use.py still green. File-revert negative test confirmed the 3 new "manifest/probe" tests are load-bearing.

[OutThisLife]

Superseded by #69903 (or whatever number — will fix).

[OutThisLife]

Superseded by #69903.

That salvage keeps your --no-overlay config + spawn wiring, defaults overlay off on macOS (not just headless/WSL2 Linux), and calls set_agent_cursor_enabled(false) after start_session when the policy is on. You're credited via cherry-pick / Co-authored-by. Thanks for isolating the idle-CPU overlay path.