fix(computer_use): Linux multi-monitor X11 AgentCursorOverlay can steal all desktop clicks (MCP path skips --no-overlay)

[pinheij]

Bug Description

On Linux X11 multi-monitor desktops, the cua-driver window Cua.AgentCursorOverlay.default can map as a full virtual-desktop override-redirect InputOutput surface (here 6000x1600+0+0) and intercept all clicks outside Hermes. User symptom: "no other item are clickable and I cant use any other apps." Hermes chat can still accept input, so it looks like a total desktop lockout.

This is related to but not the same as #78599 (embedded unrestricted serve missing --no-overlay). This report covers:

1. User-registered MCP cua-driver with args: [mcp] never receives Hermes overlay policy.
2. Desktop Linux auto-detect leaves computer_use.no_overlay off (_cua_no_overlay() → False when DISPLAY is set).
3. Multi-monitor virtual desktop + InputOutput override-redirect overlay = click sink across all heads.
4. Recovery works via set_agent_cursor_enabled(session, false); teardown/interrupt should not leave the overlay mapped.

Steps to Reproduce

1. Ubuntu 24.04 GNOME on X11, two monitors (laptop + ultrawide), virtual size spans both.
2. Hermes Desktop ≥ v0.20.0 with cua-driver 0.18.0.
3. In ~/.hermes/config.yaml, enable MCP server:

   mcp_servers:
     cua-driver:
       command: /path/to/cua-driver
       args: [mcp]   # no --no-overlay
       enabled: true

4. Leave computer_use.no_overlay unset.
5. In a Desktop chat, run several computer_use captures (list_windows, capture on Hermes / screen). Optionally interrupt a long turn.
6. Observe:

   xwininfo -root -tree | rg AgentCursor
   # Cua.AgentCursorOverlay.default  6000x1600+0+0  Override Redirect yes  InputOutput

7. Clicks miss other apps; Super/Alt-Tab may feel broken depending on grab.

Expected Behavior

• Hermes overlay policy applies to every cua-driver launch path it owns or documents (built-in backend, embedded serve, MCP registration).
• Agent cursor never becomes a full-virtual-desktop click-blocking InputOutput window.
• Session end / turn interrupt / gateway restart unmaps the overlay without a manual MCP call.
• get_agent_cursor_state accepts position: null so stuck-overlay diagnosis works.

Actual Behavior

• Overlay mapped full virtual desktop, override-redirect, InputOutput.
• Other apps unreachable by pointer until:

  set_agent_cursor_enabled(session="default", enabled=false)
  

• Live process: cua-driver mcp without --no-overlay under mcp_stdio_watchdog.py.
• _cua_no_overlay() resolved False on this desktop Linux install; driver does support --no-overlay.

Environment

• OS: Ubuntu 24.04.4 LTS, kernel 7.0.0-28-generic, X11, GNOME Shell 46.0
• Monitors: eDP-1 2560x1600+0+0 + HDMI 3440x1440+2560+0 → 6000x1600 virtual
• Hermes Agent: v0.20.0 (2026.8.3), commit 0957277f2f
• Desktop UI: v0.20.0 (+171)
• cua-driver: 0.18.0
• Python: 3.11.15
• hermes computer-use doctor: green (not a permissions/capture failure)

Error Output

# During incident
0x3e00001 "Cua.AgentCursorOverlay.default"  6000x1600+0+0
  Map State: IsViewable
  Override Redirect State: yes
  Class: InputOutput

# Policy probe
_cua_no_overlay() → False
_cua_driver_supports_no_overlay() → True

# Secondary diagnostic bug
get_agent_cursor_state: Invalid structured content — position None is not of type 'object'

Additional Context

Related

• fix(computer_use): embedded unrestricted daemon ignores no-overlay policy #78599 — embedded unrestricted daemon ignores no_overlay (same family: launch path skips flag)
• computer-use / cua-driver can consume CPU while idle #28152 / [Bug]: cua-driver pegs CPU at 100% indefinitely in cursor-overlay vImage redraw loop (concrete stack for #28152) #47032 — overlay CPU (different symptom)
• Upstream cua-driver (Linux/X11): agent-cursor overlay locks mouse input on daemon start — clicks dead screen-wide trycua/cua#1819, fix: case-insensitive model family matching + compressor init logging #2350 (input intercept / full-root surface) as cited on fix(computer_use): embedded unrestricted daemon ignores no-overlay policy #78599

Local mitigations that worked for reporter

# mcp_servers.cua-driver.args
- mcp
- --no-overlay

computer_use:
  no_overlay: true

(Restart gateway/desktop so MCP args reload.)

Proposed fix directions

1. When normalizing/starting configured MCP servers named cua-driver (or matching the computer-use driver binary), apply _mcp_args_with_overlay_flag() (or equivalent) so user MCP registration cannot silently drop policy.
2. Prefer no_overlay auto true on multi-head Linux, or make doctor warn when overlay is enabled with >1 monitor / large virtual root.
3. Ensure end_session / watchdog death / turn interrupt always unmaps Cua.AgentCursorOverlay.*.
4. Loosen get_agent_cursor_state schema for null position.
5. Document emergency recovery: MCP disable cursor, or kill cua-driver mcp child.

Happy to attach more logs from ~/.hermes/logs/ if useful. Session id on reporter machine: 20260807_094641_13df90.

[alt-glitch]

This was generated by AI during triage.

Related: #78599/#78601 cover the embedded serve launch path. This report concerns user-registered cua-driver mcp and the Linux/X11 multi-monitor overlay lifecycle, so it is not a duplicate.

[alkaiyali]

Additional reproduction: single-monitor Ubuntu X11

I reproduced the same user-visible failure on Ubuntu 24.04.4, GNOME Shell 46, X11, with a single 1920x1080 display and cua-driver 0.20.0. This was running Hermes source commit 951ae62.

During the incident:

• Xorg and GNOME Shell remained alive, and the X server still had Chrome, terminals, and other Ghostty windows.
• xwininfo -root -tree showed a viewable Cua.AgentCursorOverlay.default window sized 1920x1080, Override Redirect: yes, Class: InputOutput.
• _NET_ACTIVE_WINDOW was 0; the visible Ghostty window was the only surface that appeared usable.
• Hermes logged Chromium: CompositorAnimationObserver is active for too long (998.377s).
• Closing Hermes immediately removed the CUA overlay and restored normal window focus/input without restarting GNOME or Xorg.

The current code explains why this can happen: _cua_no_overlay() returns False by default on Linux whenever DISPLAY is set, and set_agent_cursor_enabled(false) is only called after the driver has already started. A stale full-root X11 InputOutput overlay can therefore block the desktop before the post-start safeguard runs. The same failure class is not limited to multi-monitor setups or user-registered MCP entries.

Proposed fix

1. Pass --no-overlay to every Hermes-owned cua-driver launch at process startup, including the normal desktop Linux path and embedded serve path; preserve explicit computer_use.no_overlay: false as an opt-in if the cursor visualization is required.
2. Keep the existing post-start set_agent_cursor_enabled(false) call as a fallback for older drivers, but make interrupt/session teardown unconditionally stop the backend in a finally path so the overlay cannot outlive a turn.
3. Add an X11 regression smoke test that verifies no Cua.AgentCursorOverlay.* full-root InputOutput window remains after a canceled turn or Hermes shutdown.

PR #78601 covers the embedded flag when the policy is already true, and PR #81277 covers user-configured MCP launches. This reproduction suggests the default Linux/X11 policy and interruption lifecycle also need to be covered.

[teknium1]

Status update — part of this has now landed:

1. Default X11 policy: FIXED on main. PR fix(computer-use): Linux X11 desktops no longer wedge behind a stuck overlay window (salvage #88242) #95284 (salvage of fix(computer-use): default the cursor overlay off on Linux X11 #88242 by @alkaiyali, merged c6ae932) makes _cua_no_overlay() auto-detect return True on Linux X11 desktops (Wayland/Windows keep the overlay; explicit no_overlay: false opts back in). This covers proposal (1) for every Hermes-owned launch that goes through _mcp_args_with_overlay_flag() — including the single-monitor Ubuntu/GNOME repro above, which no longer requires per-machine config.
2. Embedded serve path: in flight. PR fix(computer_use): YOLO runs no longer ignore computer_use.no_overlay (#78599, salvage #78601) #95291 (salvage of fix(computer_use): disable overlay for embedded daemons #78601 by @cvillarroel2) routes the embedded unrestricted/bounded daemon's spawn through the same policy helper — CI running now.
3. Still open — user-registered mcp_servers.cua-driver launches. PR fix(computer_use): apply --no-overlay to user-registered cua-driver MCP servers (#81220) #81277 carried this half (looks_like_cua_driver_command + arg normalization in tools/mcp_tool.py) but was withdrawn by its author during backlog cleanup and never landed; user-registered MCP entries bypass Hermes' spawn helpers, so the new default does not reach them. Also still open from the proposal above: unconditional backend teardown in a finally path on interrupt, and an X11 smoke test asserting no Cua.AgentCursorOverlay.* window survives a canceled turn.

Keeping this issue open to track item 3.