chore: refactor systemd and startup patterning for smoother boot

Author: goodroot

config/systemd/hyprwhspr.service

@@ -1,27 +1,28 @@
 [Unit]
 Description=hyprwhspr stt
 Documentation=https://github.com/goodroot/hyprwhspr
-After=graphical-session.target pipewire.service ydotool.service
-StartLimitIntervalSec=300
-StartLimitBurst=5
-Requires=ydotool.service
+
+PartOf=graphical-session.target
+After=graphical-session.target
+
+After=pipewire.service ydotool.service
 Wants=pipewire.service
+Requires=ydotool.service
+
+Wants=wireplumber.service
+After=wireplumber.service
 
 [Service]
 Type=simple
-# Wait for Wayland compositor - check for socket file directly since systemd
-# services don't inherit WAYLAND_DISPLAY from the graphical session
-ExecStartPre=/bin/bash -c 'for i in $(seq 1 30); do ls /run/user/$(id -u)/wayland-* >/dev/null 2>&1 && exit 0; sleep 0.5; done; echo "Warning: Wayland socket not found after 15s"'
+ExecStartPre=/bin/bash -lc 'for i in $(seq 1 60); do ls "$XDG_RUNTIME_DIR"/wayland-* >/dev/null 2>&1 && exit 0; sleep 0.25; done; echo "Wayland socket not found"; exit 1'
 ExecStart=/usr/lib/hyprwhspr/bin/hyprwhspr
-# Ensure virtual keyboard is killed even on crash/SIGKILL to release device grabs
 ExecStopPost=/bin/bash -c 'pkill -9 -f "hyprwhspr-virtual-keyboard" 2>/dev/null || true'
 Environment=HYPRWHSPR_ROOT=/usr/lib/hyprwhspr
 Environment=PYTHONUNBUFFERED=1
 Restart=on-failure
-# Give kernel time to release device grabs after stop
 RestartSec=2
 StandardOutput=journal
 StandardError=journal
 
 [Install]
-WantedBy=default.target
+WantedBy=graphical-session.target

config/systemd/meeting-recorder.service

@@ -1,6 +1,10 @@
 [Unit]
 Description=meeting-recorder (hyprwhspr)
 Documentation=https://github.com/goodroot/hyprwhspr
+
+PartOf=graphical-session.target
+After=graphical-session.target
+
 After=pipewire.service
 Wants=pipewire.service
 
@@ -14,4 +18,4 @@ StandardOutput=journal
 StandardError=journal
 
 [Install]
-WantedBy=default.target
+WantedBy=graphical-session.target

docs/CONFIGURATION.md

@@ -743,6 +743,45 @@ journalctl --user -u ydotool.service -f
 
 If you are using the hyprland input method, do you have shortcuts?
 
+#### Service starts but doesn't work until restarted
+
+`hyprwhspr` must start within an active graphical session.
+
+If the service appears active but hotkeys/transcription don't work until you manually restart, your session environment may not be set up correctly.
+
+Check your session:
+
+```bash
+# Verify graphical-session.target is active
+systemctl --user is-active graphical-session.target
+
+# Verify Wayland env is available to systemd services
+systemctl --user show-environment | grep WAYLAND_DISPLAY
+```
+
+If `WAYLAND_DISPLAY` is missing, add to `~/.config/hypr/hyprland.conf`:
+
+```bash
+# Export session environment to systemd user services
+exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP HYPRLAND_INSTANCE_SIGNATURE
+```
+
+**Hyprland:**
+
+If `graphical-session.target` is inactive, you likely need a session manager to activate it. The recommended approach is to launch Hyprland via [uwsm](https://github.com/Vladimir-csp/uwsm) (it activates `graphical-session.target` and exports the session environment to systemd).
+
+If you *aren't* using a session manager and your system allows it, you can try starting it manually:
+
+```bash
+exec-once = systemctl --user start graphical-session.target
+```
+
+> **Note:** Some distros set `graphical-session.target` with `RefuseManualStart=yes`, in which case the manual start will fail and you should use a session manager like `uwsm` instead.
+
+Then restart Hyprland or log out and back in.
+
+Run `hyprwhspr validate` to confirm the session is configured correctly.
+
 #### Permission denied
 
 ```bash

lib/src/cli_commands.py

@@ -3615,6 +3615,37 @@ def validate_command():
     except Exception:
         pass  # Config validation is optional, don't fail if it errors
 
+    # Check graphical session readiness
+    try:
+        result = subprocess.run(
+            ['systemctl', '--user', 'is-active', 'graphical-session.target'],
+            capture_output=True, text=True, timeout=5, check=False
+        )
+        if result.stdout.strip() == 'active':
+            log_success("✓ graphical-session.target is active")
+        else:
+            log_warning("⚠ graphical-session.target is not active")
+            print("  hyprwhspr starts with the graphical session.")
+            print("  A session manager like uwsm is needed to activate graphical-session.target.")
+            print("  See: https://github.com/Vladimir-csp/uwsm")
+    except Exception:
+        pass
+
+    # Check WAYLAND_DISPLAY in systemd user environment
+    try:
+        result = subprocess.run(
+            ['systemctl', '--user', 'show-environment'],
+            capture_output=True, text=True, timeout=5, check=False
+        )
+        if result.returncode == 0 and 'WAYLAND_DISPLAY=' in result.stdout:
+            log_success("✓ WAYLAND_DISPLAY set in systemd user environment")
+        else:
+            log_warning("⚠ WAYLAND_DISPLAY not found in systemd user environment")
+            print("  Add to ~/.config/hypr/hyprland.conf:")
+            print("    exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP HYPRLAND_INSTANCE_SIGNATURE")
+    except Exception:
+        pass
+
     if all_ok:
         log_success("Validation passed")
     else: