THE LOOP
  agent-desktop snapshot --app Finder --skeleton -i --compact
  agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact
  agent-desktop click @s8f3k2p9:e5
  agent-desktop wait --element @s8f3k2p9:e9 --predicate actionable --timeout 5000
  Observe, act on a ref, then observe again to verify. Use `wait` instead of
  sleeping, and `wait --event <kind>` for window, app, focus or surface changes.

REF IDs
  snapshot emits qualified refs such as @s8f3k2p9:e1 in depth-first order; they
  embed their snapshot ID, and a bare @eN is rejected.
  Refs go stale when the UI changes: STALE_REF and AMBIGUOUS_TARGET mean
  snapshot again and pick a fresh ref. A ref action never guesses between
  candidates. `session start` returns an ID but does not activate later
  processes: pass it with --session or AGENT_DESKTOP_SESSION.
  On Windows, quote every ref in PowerShell ('@s8f3k2p9:e1'): a bare @token
  is its splatting operator and the argument disappears.

RESULTS AND RETRIES
  Every response is one JSON envelope with ok and data, or ok and error. An
  action reports data.disposition, or error.disposition when it fails; read
  disposition.delivery and disposition.retry before acting again, and repeat
  an action only when retry is "safe". Ref actions are headless by default;
  --headed allows focus changes and real pointer and keyboard input.

KEY COMBOS
  Keys: return, escape, tab, space, delete, up, down, left, right, f1-f12
  Modifiers: cmd, ctrl, alt, shift. Use cmd+c on macOS and ctrl+c on Windows,
  where cmd and meta map to the Windows key.

ENVIRONMENT
  AGENT_DESKTOP_SESSION      Session ID fallback when --session is not passed
  AGENT_DESKTOP_AGENT_ID     Subagent ID fallback when --agent-id is not passed
                             (1-64 letters, digits, hyphen or underscore)
  AGENT_DESKTOP_HOME         Relocates the state root (absolute path; default
                             ~/.agent-desktop); `status` reports it as state_root