infrastructure/mw-pfeddersheim-workstation

Files

T

ja ee592cc21b 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

2026-05-21 11:15:14 +02:00

2.9 KiB

Raw Blame History

description, status, date

description	status	date
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.	accepted	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:

cat ~/.local/share/wayland-sessions/hyprland.desktop should show Exec=start-hyprland
Next login: the warning banner should no longer appear.
ps aux | grep start-hyprland should show the watchdog parent process.

2.9 KiB Raw Blame History Unescape Escape