feat: add start-hyprland watchdog override for uwsm session

Hyprland 0.53+ requires launching via start-hyprland (watchdog) for
proper crash diagnostics and signal handling. Without it a warning
banner appears on login.

Override package-managed hyprland.desktop with local copy pointing to
start-hyprland. XDG_DATA_DIRS priority ensures the override wins
without modifying system files.

- ansible/roles/hyprland/tasks/main.yml: manage override in ~/.local/share/wayland-sessions/
- docs/adr/0004-start-hyprland-override.md: full decision record
- docs/hyprland-uwsm.md: document override behavior

docs/adr/0004-start-hyprland-override.md

@@ -0,0 +1,72 @@
+---
+description: >-
+  Override the package-managed hyprland.desktop with a local copy that points
+  to start-hyprland (watchdog binary), ensuring Hyprland launches with proper
+  crash diagnostics, signal handling, and XDG portal support via uwsm.
+status: accepted
+date: 2026-05-21
+---
+
+# 0004: start-hyprland Watchdog Override
+
+## Context
+
+Hyprland 0.53+ ships `start-hyprland`, a watchdog binary that monitors the
+compositor process, collects crash diagnostics (crash reports, memory dumps),
+and ensures proper signal handling. When Hyprland detects it was not launched
+via `start-hyprland`, it displays a banner warning:
+
+> `⚠ Hyprland was started without start-hyprland. This is highly not
+> recommended unless you are in a debugging environment.`
+
+Our setup uses: greetd → tuigreet → `uwsm start -e -D Hyprland hyprland.desktop`
+
+uwsm reads the `.desktop` file's `Exec=` field and spawns that binary inside
+a systemd user session. The package-provided `hyprland.desktop` has
+`Exec=Hyprland` (direct binary), bypassing the watchdog.
+
+### Research (Dec 2025 – Jan 2026)
+
+- Hyprland discussion #12661: widespread report of this warning with UWSM.
+- UWSM maintainer Vladimir-csp confirmed: "I'd recommend feeding
+  `hyprland.desktop` to uwsm" with the watchdog binary.
+- fufexan (Hyprland maintainer) acknowledged the incompatibility; no upstream
+  fix landed as of Jan 2026.
+- Community consensus: point `.desktop` Exec to `start-hyprland` via local
+  override to preserve uwsm session management while enabling the watchdog.
+
+## Decision
+
+Create a local override at `~/.local/share/wayland-sessions/hyprland.desktop`
+pointing to `start-hyprland`.
+
+### Why local override (not system-wide)?
+
+- The system file (`/usr/share/wayland-sessions/hyprland.desktop`) is owned by
+  the `hyprland` package and gets overwritten on updates.
+- `~/.local/share` has higher XDG_DATA_DIRS priority than `/usr/share`, so
+  greetd/tuigreet discover the override first without touching system files.
+- Ansible manages the override idempotently.
+
+### Why not modify greetd's command?
+
+The greetd command (`uwsm start -e -D Hyprland hyprland.desktop`) references
+`hyprland.desktop` generically. Changing the greeting command to
+`start-hyprland` directly would bypass uwsm entirely. The override approach
+keeps the uwsm session management intact while fixing the watchdog issue.
+
+## Status
+
+Implemented in Ansible role `hyprland/tasks/main.yml`:
+- Task registers the override at `~/.local/share/wayland-sessions/hyprland.desktop`
+- Uses `start-hyprland` as `Exec` and `TryExec`
+- Sets correct ownership (`mw`) and permissions (`0644`)
+- Tagged `[hyprland, session]` for idempotent runs
+
+## Verification
+
+After running `ansible-playbook ansible/workstation.yml`:
+1. `cat ~/.local/share/wayland-sessions/hyprland.desktop` should show
+   `Exec=start-hyprland`
+2. Next login: the warning banner should no longer appear.
+3. `ps aux | grep start-hyprland` should show the watchdog parent process.