From ee592cc21bb23a363e1e0abacadccfbd45c13ffb Mon Sep 17 00:00:00 2001
From: Jane Alesi <ja@satware.ai>
Date: Thu, 21 May 2026 11:15:14 +0200
Subject: [PATCH] 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
---
 ansible/roles/hyprland/tasks/main.yml    | 15 ++++-
 docs/adr/0004-start-hyprland-override.md | 72 ++++++++++++++++++++++++
 docs/hyprland-uwsm.md                    | 12 ++++
 3 files changed, 96 insertions(+), 3 deletions(-)
 create mode 100644 docs/adr/0004-start-hyprland-override.md

diff --git a/ansible/roles/hyprland/tasks/main.yml b/ansible/roles/hyprland/tasks/main.yml
index 1cb5ce0..5ab9335 100644
--- a/ansible/roles/hyprland/tasks/main.yml
+++ b/ansible/roles/hyprland/tasks/main.yml
@@ -53,14 +53,23 @@
   notify: rebuild initramfs
   tags: [hyprland, nvidia]
 
-- name: Hyprland - register Wayland session desktop entry
+- name: Hyprland - override Wayland session desktop entry (local user)
+  # Overrides /usr/share/wayland-sessions/hyprland.desktop with start-hyprland
+  # as the Exec target. This ensures Hyprland is launched through the watchdog
+  # binary (start-hyprland) for proper crash diagnostics and signal handling.
+  # XDG_DATA_DIRS priority: ~/.local/share > /usr/share.
+  # See: docs/adr/0004-start-hyprland-override.md
   copy:
-    dest: /usr/share/wayland-sessions/hyprland.desktop
+    dest: /home/{{ system_user }}/.local/share/wayland-sessions/hyprland.desktop
+    owner: "{{ system_user }}"
+    group: "{{ system_user }}"
+    mode: '0644'
     content: |
       [Desktop Entry]
       Name=Hyprland
       Comment=An intelligent dynamic tiling Wayland compositor
-      Exec=Hyprland
+      Exec=start-hyprland
+      TryExec=start-hyprland
       Type=Application
       DesktopNames=Hyprland
   tags: [hyprland, session]
diff --git a/docs/adr/0004-start-hyprland-override.md b/docs/adr/0004-start-hyprland-override.md
new file mode 100644
index 0000000..17012b1
--- /dev/null
+++ b/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.
diff --git a/docs/hyprland-uwsm.md b/docs/hyprland-uwsm.md
index 3e75b9d..7aefd13 100644
--- a/docs/hyprland-uwsm.md
+++ b/docs/hyprland-uwsm.md
@@ -55,6 +55,18 @@ hypr launcher config: `~/.config/hypr/hyprlauncher.conf`
 Config: `/etc/greetd/config.toml`
 Default command: `tuigreet --time --remember --asterisks --cmd 'uwsm start -e -D Hyprland hyprland.desktop'`
 
+### Wayland Session Override (start-hyprland)
+
+The package provides `/usr/share/wayland-sessions/hyprland.desktop` with
+`Exec=Hyprland` (direct binary), but Hyprland 0.53+ requires launching through
+`start-hyprland` (watchdog parent process) for crash diagnostics and proper
+signal handling. Otherwise a warning banner appears on login.
+
+A local override at `~/.local/share/wayland-sessions/hyprland.desktop` sets
+`Exec=start-hyprland`, which uwsm then manages inside the systemd session.
+XDG_DATA_DIRS priority ensures the override wins without touching system files.
+Managed by Ansible role `hyprland` — see `docs/adr/0004-start-hyprland-override.md`.
+
 ## Key Categories
 
 | Category | Modifier | Keys | Action |