fix: recover Wayland display at startup

Author: goodroot

docs/CONFIGURATION.md

@@ -1263,6 +1263,12 @@ If `WAYLAND_DISPLAY` is missing, add to `~/.config/hypr/hyprland.conf`:
 exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP HYPRLAND_INSTANCE_SIGNATURE
 ```
 
+hyprwhspr also has a startup fallback: if `WAYLAND_DISPLAY` is unset but a
+Wayland socket exists in `XDG_RUNTIME_DIR`, it will use the newest `wayland-*`
+socket for its own process and children. The compositor environment export above
+is still the recommended fix because it makes the correct display available to
+all systemd user services.
+
 **Niri:**
 
 hyprwhspr uses `niri msg --json focused-window` to detect the focused app and choose the correct paste shortcut. That requires `NIRI_SOCKET` to be available in the systemd user environment used by `hyprwhspr.service`.

lib/main.py

@@ -74,6 +74,7 @@ def _looks_like_wlroots_session() -> bool:
 from config_manager import ConfigManager
 from audio_capture import AudioCapture
 from whisper_manager import WhisperManager
+from session_environment import ensure_wayland_display
 from text_injector import TextInjector
 from global_shortcuts import GlobalShortcuts
 from audio_manager import AudioManager
@@ -91,6 +92,8 @@ class hyprwhsprApp:
     """Main application class for hyprwhspr voice dictation (Headless Mode)"""
 
     def __init__(self):
+        ensure_wayland_display()
+
         # Initialize core components
         self.config = ConfigManager()
 

lib/src/session_environment.py

@@ -0,0 +1,46 @@
+"""
+Session environment fallbacks for service startup.
+"""
+
+import os
+import stat
+from pathlib import Path
+
+
+def ensure_wayland_display():
+    """
+    Populate WAYLAND_DISPLAY from XDG_RUNTIME_DIR when systemd has not imported it.
+
+    This is a best-effort fallback for compositor startup races. It intentionally
+    does not override an existing WAYLAND_DISPLAY value.
+    """
+    if os.environ.get("WAYLAND_DISPLAY"):
+        return
+
+    runtime_dir = os.environ.get("XDG_RUNTIME_DIR")
+    if not runtime_dir:
+        print("[WARN] WAYLAND_DISPLAY unset and XDG_RUNTIME_DIR missing", flush=True)
+        return
+
+    runtime_path = Path(runtime_dir)
+    if not runtime_path.is_dir():
+        print("[WARN] WAYLAND_DISPLAY unset and XDG_RUNTIME_DIR is not a directory", flush=True)
+        return
+
+    candidates = []
+    for path in runtime_path.glob("wayland-*"):
+        try:
+            path_stat = path.stat()
+        except OSError:
+            continue
+        if stat.S_ISSOCK(path_stat.st_mode):
+            candidates.append((path_stat.st_mtime, path.name, path))
+
+    if not candidates:
+        return
+
+    # A newly bound compositor socket is the most likely active display after a
+    # startup race leaves WAYLAND_DISPLAY out of the systemd user environment.
+    _mtime, display_name, _path = max(candidates)
+    os.environ["WAYLAND_DISPLAY"] = display_name
+    print(f"[INIT] WAYLAND_DISPLAY was unset; using {display_name}", flush=True)

tests/test_session_environment.py

@@ -0,0 +1,113 @@
+import os
+import stat as stat_module
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "lib" / "src"))
+
+from session_environment import ensure_wayland_display
+
+
+class SessionEnvironmentTests(unittest.TestCase):
+    def _socket_file_at(self, path, mtime=100):
+        path.write_text("", encoding="utf-8")
+        path.chmod(0o600)
+        os.utime(path, (mtime, mtime))
+        return path
+
+    def _non_socket_file_at(self, path, mtime=100):
+        path.write_text("", encoding="utf-8")
+        path.chmod(0o644)
+        os.utime(path, (mtime, mtime))
+        return path
+
+    def _socket_mode_patch(self):
+        # The sandbox can deny AF_UNIX bind() in temp dirs, so tests mark fake
+        # sockets with a distinct mode while production uses the real stat check.
+        return mock.patch(
+            "session_environment.stat.S_ISSOCK",
+            side_effect=lambda mode: stat_module.S_IMODE(mode) == 0o600,
+        )
+
+    def test_does_nothing_when_wayland_display_already_set(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._socket_file_at(Path(tmpdir) / "wayland-1")
+            with (
+                mock.patch.dict(
+                    os.environ,
+                    {"WAYLAND_DISPLAY": "wayland-existing", "XDG_RUNTIME_DIR": tmpdir},
+                    clear=True,
+                ),
+                mock.patch("builtins.print") as print_mock,
+                self._socket_mode_patch(),
+            ):
+                ensure_wayland_display()
+                self.assertEqual(os.environ.get("WAYLAND_DISPLAY"), "wayland-existing")
+
+        print_mock.assert_not_called()
+
+    def test_sets_wayland_display_when_one_socket_exists(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._socket_file_at(Path(tmpdir) / "wayland-1")
+            with (
+                mock.patch.dict(os.environ, {"XDG_RUNTIME_DIR": tmpdir}, clear=True),
+                self._socket_mode_patch(),
+            ):
+                ensure_wayland_display()
+                self.assertEqual(os.environ.get("WAYLAND_DISPLAY"), "wayland-1")
+
+    def test_chooses_newest_socket_when_multiple_exist(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            runtime_dir = Path(tmpdir)
+            self._socket_file_at(runtime_dir / "wayland-0", mtime=100)
+            self._socket_file_at(runtime_dir / "wayland-1", mtime=200)
+
+            with (
+                mock.patch.dict(os.environ, {"XDG_RUNTIME_DIR": tmpdir}, clear=True),
+                self._socket_mode_patch(),
+            ):
+                ensure_wayland_display()
+                self.assertEqual(os.environ.get("WAYLAND_DISPLAY"), "wayland-1")
+
+    def test_ignores_non_socket_files_matching_wayland_pattern(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            runtime_dir = Path(tmpdir)
+            self._non_socket_file_at(runtime_dir / "wayland-9", mtime=300)
+            self._socket_file_at(runtime_dir / "wayland-1", mtime=100)
+
+            with (
+                mock.patch.dict(os.environ, {"XDG_RUNTIME_DIR": tmpdir}, clear=True),
+                self._socket_mode_patch(),
+            ):
+                ensure_wayland_display()
+                self.assertEqual(os.environ.get("WAYLAND_DISPLAY"), "wayland-1")
+
+    def test_does_nothing_when_runtime_dir_has_no_sockets(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            runtime_dir = Path(tmpdir)
+            self._non_socket_file_at(runtime_dir / "wayland-0")
+
+            with (
+                mock.patch.dict(os.environ, {"XDG_RUNTIME_DIR": tmpdir}, clear=True),
+                self._socket_mode_patch(),
+            ):
+                ensure_wayland_display()
+                self.assertIsNone(os.environ.get("WAYLAND_DISPLAY"))
+
+    def test_does_not_raise_when_xdg_runtime_dir_unset_or_missing(self):
+        with mock.patch.dict(os.environ, {}, clear=True):
+            ensure_wayland_display()
+            self.assertIsNone(os.environ.get("WAYLAND_DISPLAY"))
+
+        with mock.patch.dict(os.environ, {"XDG_RUNTIME_DIR": "/path/that/does/not/exist"}, clear=True):
+            ensure_wayland_display()
+            self.assertIsNone(os.environ.get("WAYLAND_DISPLAY"))
+
+
+if __name__ == "__main__":
+    unittest.main()