refrain 0.4.2__tar.gz → 0.4.4__tar.gz

{refrain-0.4.2 → refrain-0.4.4}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,7 +13,7 @@ body:
     attributes:
       label: Refrain version
       description: Run `refrain --version` or check the bottom-right of the settings window.
-      placeholder: "0.4.2"
+      placeholder: "0.4.4"
     validations:
       required: true
 

{refrain-0.4.2 → refrain-0.4.4}/.github/workflows/security.yml

@@ -78,7 +78,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run TruffleHog
-        uses: trufflesecurity/trufflehog@6f3c981e7b77f235fd2702dd74af25fc4b72bf11  # v3.96.0
+        uses: trufflesecurity/trufflehog@bcfcf73aaf4759d4dadc2783177c245a02792318  # v3.97.0
         with:
           # --only-verified: a secret only counts as flagged when TruffleHog
           # successfully validates it against the live service. Drops the

{refrain-0.4.2 → refrain-0.4.4}/CHANGELOG.md

@@ -9,6 +9,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Nothing here
 
+## [0.4.4] - 2026-08-24
+
+Fixed the MPRIS server never registering, so Plasma's media controls
+could not reach Refrain even on installs that had PyGObject.
+
+### Fixed
+
+- **MPRIS server never made it onto the session bus.** `dbus.SessionBus()`
+  is a process-wide singleton: whoever opens it first decides whether that
+  connection carries a main loop, and every later caller gets the same
+  object back. `main()` read the Last.fm credentials out of the Secret
+  Service — which opens the bus — *before* wiring dbus-python into GLib,
+  so `dbus.service.Object` could never export and every start logged
+  `MPRIS server start failed: ... D-Bus connections must be attached to a
+  main loop`. Plasma's media controls therefore never reached Refrain, and
+  installing the advertised `python-gobject` optional dependency made no
+  difference. The GLib wiring now runs before anything touches the bus.
+- **The GLib loop no longer races Qt for the default main context.**
+  `_ensure_dbus_glib_loop()` also started a GLib main loop in a daemon
+  thread before `QApplication` existed. That worker acquired the default
+  `GMainContext` first, so Qt's own glib dispatcher tripped
+  `g_main_context_push_thread_default: assertion 'acquired_context'
+  failed` and the process died with a segfault once timers started
+  crossing threads. Qt's dispatcher already pumps that context, so no
+  loop of our own is needed; one is started only when Qt is not
+  glib-backed (`QT_NO_GLIB=1`), and only once `QApplication` is up.
+
+## [0.4.3] - 2026-08-24
+
+Fixed a startup crash on installs that run against the PySide6 wheel's
+bundled Qt while the distro ships a newer Qt patch release.
+
+### Fixed
+
+- **No Qt platform plugin could be initialized on a patch-version skew.**
+  `_augment_qt_plugin_path()` adds the distro's Qt plugin tree so a
+  pip / pipx / AppImage install can still find the system styles, and it
+  gated that on Qt's `MAJOR.MINOR` alone. That is not the rule Qt
+  enforces: Qt refuses any plugin built against a *newer* Qt than the one
+  running. On a rolling distro one patch ahead of the wheel (bundled Qt
+  6.11.1, system Qt 6.11.2) the check passed, and because
+  `addLibraryPath()` *prepends*, the rejected system `wayland` and `xcb`
+  plugins shadowed the wheel's own working copies instead of falling back
+  to them — the app aborted with "This application failed to start
+  because no Qt platform plugin could be initialized". Two guards now
+  apply: the version check mirrors Qt's actual rule (same `MAJOR.MINOR`
+  *and* the system Qt no newer than ours), and the plugin tree is
+  appended rather than prepended, so the bundled Qt keeps first claim on
+  the platform plugin. A mismatched system tree can now only cost the
+  themed style, never the ability to start. Installs running against the
+  distro PySide6 — the AUR and distro packages — were never affected;
+  they short-circuit before any of this.
+
 ## [0.4.2] - 2026-08-12
 
 Fixed Apple Music RPC URL handling and Discord buttons,
@@ -1237,7 +1290,9 @@ with a proper, installable Linux app.
   pip-audit, trufflehog, release), Dependabot, issue + PR templates,
   `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`.
 
-[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.4.2...HEAD
+[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.4.4...HEAD
+[0.4.4]: https://github.com/Rockykln/refrain/compare/v0.4.3...v0.4.4
+[0.4.3]: https://github.com/Rockykln/refrain/compare/v0.4.2...v0.4.3
 [0.4.2]: https://github.com/Rockykln/refrain/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/Rockykln/refrain/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/Rockykln/refrain/compare/v0.3.0...v0.4.0

{refrain-0.4.2 → refrain-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: refrain
-Version: 0.4.2
+Version: 0.4.4
 Summary: Discord Rich Presence for Apple Music on Linux
 Project-URL: Homepage, https://github.com/Rockykln/refrain
 Project-URL: Repository, https://github.com/Rockykln/refrain

{refrain-0.4.2 → refrain-0.4.4}/packaging/appimage/AppImageBuilder.yml

@@ -30,7 +30,7 @@ AppDir:
     id: io.github.Rockykln.Refrain
     name: Refrain
     icon: refrain
-    version: 0.4.2
+    version: 0.4.4
     exec: usr/bin/python3
     exec_args: -m refrain $@
 

{refrain-0.4.2 → refrain-0.4.4}/packaging/aur/refrain/.SRCINFO

@@ -1,6 +1,6 @@
 pkgbase = refrain
 	pkgdesc = Discord Rich Presence for Apple Music on Linux
-	pkgver = 0.4.2
+	pkgver = 0.4.4
 	pkgrel = 1
 	url = https://github.com/Rockykln/refrain
 	arch = any
@@ -14,7 +14,7 @@ pkgbase = refrain
 	depends = python-dbus
 	depends = pyside6
 	optdepends = python-gobject: enables MPRIS-server publication so Plasma media controls reach Refrain
-	source = refrain-0.4.2.tar.gz::https://github.com/Rockykln/refrain/archive/v0.4.2.tar.gz
-	sha256sums = d5558cd419c8d46bdc958064cb97f963d1ea793866414c025906ec15033512ed
+	source = refrain-0.4.4.tar.gz::https://github.com/Rockykln/refrain/archive/v0.4.4.tar.gz
+	sha256sums = 0000000000000000000000000000000000000000000000000000000000000000
 
 pkgname = refrain

{refrain-0.4.2 → refrain-0.4.4}/packaging/aur/refrain/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Rockykln <contact@rockykln.com>
 
 pkgname=refrain
-pkgver=0.4.2
+pkgver=0.4.4
 pkgrel=1
 pkgdesc="Discord Rich Presence for Apple Music on Linux"
 arch=('any')
@@ -23,7 +23,9 @@ makedepends=(
     'python-wheel'
 )
 source=("$pkgname-$pkgver.tar.gz::https://github.com/Rockykln/refrain/archive/v$pkgver.tar.gz")
-sha256sums=('d5558cd419c8d46bdc958064cb97f963d1ea793866414c025906ec15033512ed')
+# Filled in once the v0.4.4 tarball exists (after the tag is pushed):
+#   updpkgsums && makepkg --printsrcinfo > .SRCINFO
+sha256sums=('0000000000000000000000000000000000000000000000000000000000000000')
 
 build() {
     cd "$pkgname-$pkgver"

{refrain-0.4.2 → refrain-0.4.4}/packaging/aur/refrain-git/.SRCINFO

@@ -1,6 +1,6 @@
 pkgbase = refrain-git
 	pkgdesc = Discord Rich Presence for Apple Music on Linux (git)
-	pkgver = 0.4.2.r108.gb4e0e07
+	pkgver = 0.4.4.r120.gb834822
 	pkgrel = 1
 	url = https://github.com/Rockykln/refrain
 	arch = any

{refrain-0.4.2 → refrain-0.4.4}/packaging/aur/refrain-git/PKGBUILD

@@ -2,7 +2,7 @@
 
 pkgname=refrain-git
 _pkgname=refrain
-pkgver=0.4.2.r108.gb4e0e07
+pkgver=0.4.4.r120.gb834822
 pkgrel=1
 pkgdesc="Discord Rich Presence for Apple Music on Linux (git)"
 arch=('any')

{refrain-0.4.2 → refrain-0.4.4}/packaging/flatpak/io.github.Rockykln.Refrain.metainfo.xml

@@ -51,6 +51,24 @@
   <content_rating type="oars-1.1" />
 
   <releases>
+    <release version="0.4.4" date="2026-08-24">
+      <description>
+        <p>
+          Fixed the MPRIS server never registering on the session bus, which
+          left Plasma's media controls unable to reach Refrain even with
+          PyGObject installed.
+        </p>
+      </description>
+    </release>
+    <release version="0.4.3" date="2026-08-24">
+      <description>
+        <p>
+          Fixed a startup crash on systems whose Qt is a patch release ahead
+          of the one bundled with PySide6, which left pip, pipx and AppImage
+          installs unable to initialise any Qt platform plugin.
+        </p>
+      </description>
+    </release>
     <release version="0.4.2" date="2026-08-12">
       <description>
         <p>

{refrain-0.4.2 → refrain-0.4.4}/packaging/flatpak/io.github.Rockykln.Refrain.yaml

@@ -102,5 +102,5 @@ modules:
     sources:
       - type: git
         url: https://github.com/Rockykln/refrain.git
-        tag: v0.4.2
-        commit: b4e0e07a3cfcb55499e0fd87652ff9b508d32f6e
+        tag: v0.4.4
+        commit: b834822f0cca13e65aece18bf58ab0314b9413cf

{refrain-0.4.2 → refrain-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "refrain"
-version = "0.4.2"
+version = "0.4.4"
 description = "Discord Rich Presence for Apple Music on Linux"
 readme = "README.md"
 requires-python = ">=3.11"

refrain-0.4.4/src/refrain/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.4"

{refrain-0.4.2 → refrain-0.4.4}/src/refrain/app.py

@@ -123,6 +123,40 @@ def _detect_system_qt6_version() -> str | None:
     return None
 
 
+def _qt_version_tuple(version: str) -> tuple[int, ...]:
+    """Parse ``"6.11.2"`` into ``(6, 11, 2)``, stopping at the first
+    non-numeric component so suffixed versions still compare sanely."""
+    parts: list[int] = []
+    for chunk in version.split("."):
+        digits = ""
+        for ch in chunk:
+            if not ch.isdigit():
+                break
+            digits += ch
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts)
+
+
+def _system_qt_plugins_loadable(bundled: str, system: str) -> bool:
+    """Whether the system Qt's plugins can load into our bundled Qt.
+
+    Qt refuses a plugin built against a *newer* Qt than the one running,
+    so the system tree is only usable when it shares our MAJOR.MINOR and
+    is no newer at the patch level. A distro that is a single patch ahead
+    (bundled 6.11.1, system 6.11.2 — the common case on a rolling distro)
+    would otherwise hand us platform plugins Qt then rejects.
+    """
+    b = _qt_version_tuple(bundled)
+    s = _qt_version_tuple(system)
+    if len(b) < 2 or len(s) < 2:
+        return False
+    if b[:2] != s[:2]:
+        return False
+    return s <= b
+
+
 # Where distros put Qt 6 plugins. Order matters: try the
 # multiarch path first (Debian/Ubuntu derivatives), then lib64
 # (Fedora/RHEL/openSUSE), then the plain lib (Arch/CachyOS).
@@ -151,10 +185,11 @@ def _augment_qt_plugin_path() -> None:
     visibly different from the AUR / system build that runs against the
     distro PySide6.
 
-    If a system Qt 6 plugin tree exists and the system Qt's MAJOR.MINOR
-    matches ours, we prepend it so Qt finds the styles. We require a
-    minor-version match because mixing plugins across Qt minors risks
-    a silent ABI break.
+    If a system Qt 6 plugin tree exists and its plugins can actually load
+    into our Qt (see ``_system_qt_plugins_loadable``), we *append* it so
+    Qt finds the styles. Appending matters: the bundled Qt must keep first
+    claim on the platform plugin, otherwise a system plugin that Qt then
+    refuses takes the whole startup down with it.
 
     Must be called before ``QApplication`` is constructed — Qt resolves
     the platform/style plugin during construction.
@@ -174,13 +209,11 @@ def _augment_qt_plugin_path() -> None:
     if not system_version:
         log.debug("Could not determine system Qt 6 version; not augmenting plugin path")
         return
-    bundled_minor = ".".join(bundled_version.split(".")[:2])
-    system_minor = ".".join(system_version.split(".")[:2])
-    if bundled_minor != system_minor:
+    if not _system_qt_plugins_loadable(bundled_version, system_version):
         log.debug(
-            "Qt minor mismatch (bundled=%s system=%s); not augmenting plugin path",
-            bundled_version,
+            "System Qt %s cannot supply plugins for bundled Qt %s; not augmenting plugin path",
             system_version,
+            bundled_version,
         )
         return
     log.info(
@@ -189,7 +222,10 @@ def _augment_qt_plugin_path() -> None:
         bundled_version,
         system_version,
     )
-    QCoreApplication.addLibraryPath(str(system_plugins))
+    # Append, never prepend (``addLibraryPath`` prepends): the bundled Qt
+    # keeps first claim on the platform plugin, so a mismatched system tree
+    # can only cost us the styles, never the ability to start.
+    QCoreApplication.setLibraryPaths(QCoreApplication.libraryPaths() + [str(system_plugins)])
 
 
 def _user_apps_dir() -> Path:
@@ -569,6 +605,20 @@ def main() -> int:
     log_bridge = attach_qt_log_bridge()
     qInstallMessageHandler(_qt_message_handler)
 
+    # Wire dbus-python's dispatch into GLib *before anything opens the
+    # session bus*. `dbus.SessionBus()` is a process-wide singleton, so
+    # the first caller fixes whether that connection carries a main loop
+    # and everyone after gets the same object. The Last.fm keyring
+    # lookup below opens the bus, as do MPRISSource / BluetoothSource
+    # later — win that race or our MPRIS server can never export.
+    # No-op if PyGObject is missing; Discord RPC + tray keep working.
+    try:
+        from refrain.sources.mpris_server import _ensure_dbus_glib_loop
+
+        _ensure_dbus_glib_loop()
+    except Exception as e:
+        log.debug("dbus-glib loop init skipped: %s", e)
+
     config = Config.load()
     # Last.fm secrets live in the OS keyring, never in config.toml.
     # Overlay them onto the in-memory config (and migrate any legacy
@@ -584,23 +634,19 @@ def main() -> int:
     # else touches the filesystem.
     cleanup_orphan_downloads()
 
-    # Wire dbus-python's dispatch into a GLib main loop *before* anything
-    # touches the session bus. Has to happen before MPRISSource /
-    # BluetoothSource construct their first SessionBus, otherwise the
-    # bus connection won't have a main loop attached and our published
-    # MPRIS server fails to register ("D-Bus connections must be
-    # attached to a main loop"). No-op if PyGObject is missing — the
-    # Discord-RPC + tray sides keep working without it.
-    try:
-        from refrain.sources.mpris_server import _ensure_dbus_glib_loop
-
-        _ensure_dbus_glib_loop()
-    except Exception as e:
-        log.debug("dbus-glib loop init skipped: %s", e)
-
     _augment_qt_plugin_path()
 
     app = QApplication(sys.argv)
+    # Qt's glib dispatcher now owns the default GMainContext, so this is
+    # normally a no-op; it only spins our own loop when Qt isn't
+    # glib-backed. Must come after QApplication — starting a GLib loop
+    # first makes it grab the context and segfaults Qt's dispatcher.
+    try:
+        from refrain.sources.mpris_server import ensure_dbus_dispatch_pump
+
+        ensure_dbus_dispatch_pump()
+    except Exception as e:
+        log.debug("dbus dispatch pump skipped: %s", e)
     app.setApplicationName("Refrain")
     app.setApplicationDisplayName("Refrain")
     app.setApplicationVersion(__version__)

{refrain-0.4.2 → refrain-0.4.4}/src/refrain/sources/mpris_server.py

@@ -42,17 +42,23 @@ _GLIB_THREAD: threading.Thread | None = None
 
 
 def _ensure_dbus_glib_loop() -> bool:
-    """Start the GLib main loop in a background thread so dbus-python
-    can deliver method calls / signals into our service objects.
-
-    Qt's event loop owns the main thread; dbus-python needs its own
-    GLib loop to pump messages. Running it in a daemon thread is the
-    documented workaround for "dbus-python in a Qt app". Returns True
-    on success, False if PyGObject isn't installed (in which case the
-    MPRIS server falls back to polling-only mode and Plasma controls
+    """Attach dbus-python's dispatch to the GLib main loop.
+
+    Must run **before the process opens its first session bus**.
+    ``dbus.SessionBus()`` is a process-wide singleton: whoever creates it
+    first decides whether that connection carries a main loop, and every
+    later caller gets the same object back. Register too late and
+    ``dbus.service.Object`` can never export ("D-Bus connections must be
+    attached to a main loop"), which silently costs us Plasma's media
+    controls.
+
+    This only wires up the dispatch; it deliberately does *not* spin a
+    GLib loop of its own — see ``ensure_dbus_dispatch_pump``. Returns
+    True on success, False if PyGObject isn't installed (in which case
+    the MPRIS server falls back to polling-only mode and Plasma controls
     won't reach us, but the rest of refrain keeps working).
     """
-    global _DBUS_LOOP_INITIALIZED, _DBUS_LOOP_INIT_FAILED, _GLIB_THREAD
+    global _DBUS_LOOP_INITIALIZED, _DBUS_LOOP_INIT_FAILED
     if _DBUS_LOOP_INITIALIZED:
         return True
     if _DBUS_LOOP_INIT_FAILED:
@@ -61,7 +67,7 @@ def _ensure_dbus_glib_loop() -> bool:
         # False instead of a duplicate WARNING in the log.
         return False
     try:
-        from gi.repository import GLib
+        import gi.repository.GLib  # noqa: F401  — availability probe only
     except ImportError as e:
         _DBUS_LOOP_INIT_FAILED = True
         log.warning(
@@ -73,15 +79,68 @@ def _ensure_dbus_glib_loop() -> bool:
         )
         return False
     DBusGMainLoop(set_as_default=True)
+    _DBUS_LOOP_INITIALIZED = True
+    log.debug("MPRIS server: dbus-python dispatch wired into GLib")
+    return True
+
+
+def _qt_pumps_glib_context() -> bool:
+    """Whether Qt's event dispatcher already runs the default GMainContext.
+
+    On Linux Qt normally uses ``QEventDispatcherGlib``, which pumps the
+    default context for us — that is exactly what dbus-python needs, so
+    no loop of our own is required. Builds with glib disabled (or
+    ``QT_NO_GLIB=1``) use ``QEventDispatcherUNIX`` instead and leave the
+    context unpumped.
+    """
+    try:
+        from PySide6.QtCore import QAbstractEventDispatcher, QCoreApplication
+
+        if QCoreApplication.instance() is None:
+            return False
+        dispatcher = QAbstractEventDispatcher.instance()
+        if dispatcher is None:
+            return False
+        # "QPAEventDispatcherGlib" / "QEventDispatcherGlib" vs
+        # "QEventDispatcherUNIX". className() is a str.
+        return "Glib" in dispatcher.metaObject().className()
+    except Exception as e:  # pragma: no cover - defensive; Qt should be importable
+        # Don't swallow silently: a wrong answer here costs Plasma's
+        # media controls or spins a loop we don't need.
+        log.debug("Could not classify Qt's event dispatcher (%s); assuming non-glib", e)
+        return False
+
+
+def ensure_dbus_dispatch_pump() -> None:
+    """Guarantee something actually pumps dbus-python's dispatch.
+
+    Call once ``QApplication`` exists. Normally a no-op: Qt's glib event
+    dispatcher already runs the default GMainContext on the main thread.
+    Only when Qt is *not* glib-backed do we fall back to our own GLib
+    loop in a daemon thread.
+
+    Starting that thread unconditionally — and worse, before
+    ``QApplication`` is constructed — makes the worker acquire the
+    default context first, so Qt's own dispatcher then trips
+    ``g_main_context_push_thread_default: assertion 'acquired_context'
+    failed`` and the process dies with a segfault once timers start
+    crossing threads.
+    """
+    global _GLIB_THREAD
+    if not _DBUS_LOOP_INITIALIZED or _GLIB_THREAD is not None:
+        return
+    if _qt_pumps_glib_context():
+        log.debug("MPRIS server: Qt's glib dispatcher pumps dbus; no extra loop")
+        return
+    from gi.repository import GLib
+
     _GLIB_THREAD = threading.Thread(
         target=GLib.MainLoop().run,
         name="refrain-glib-loop",
         daemon=True,
     )
     _GLIB_THREAD.start()
-    _DBUS_LOOP_INITIALIZED = True
-    log.debug("MPRIS server: GLib main loop started for dbus-python dispatch")
-    return True
+    log.debug("MPRIS server: Qt is not glib-backed; started our own GLib loop")
 
 
 _BUS_NAME = "org.mpris.MediaPlayer2.refrain"

refrain-0.4.4/tests/test_dbus_dispatch.py

@@ -0,0 +1,200 @@
+"""dbus-python dispatch setup must not cost us the MPRIS server — or the process.
+
+Two regressions are guarded here, both from 0.4.3.
+
+1. **The MPRIS server never registered on distro installs.**
+   ``dbus.SessionBus()`` is a process-wide singleton: the first caller
+   decides whether that connection carries a main loop, and everyone
+   after gets the same object back. ``app.main`` read the Last.fm
+   secrets out of the Secret Service — opening the bus — *before*
+   wiring dbus into GLib, so ``dbus.service.Object`` could never export
+   ("D-Bus connections must be attached to a main loop"). Plasma's media
+   controls silently never worked, even with PyGObject installed.
+
+2. **Starting our own GLib loop segfaulted Qt.**
+   The naive fix (just moving the init earlier) let the worker thread
+   acquire the default GMainContext before ``QApplication`` existed. Qt's
+   own glib dispatcher then tripped ``g_main_context_push_thread_default:
+   assertion 'acquired_context' failed`` and the process died with
+   SIGSEGV once timers began crossing threads. Qt's dispatcher already
+   pumps the default context, so the extra loop is only a fallback for a
+   Qt that isn't glib-backed, and it may only start once Qt is up.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("PySide6")
+
+
+# ---------------------------------------------------------------------------
+# Ordering invariant (regression 1)
+# ---------------------------------------------------------------------------
+def test_dbus_loop_is_wired_before_anything_opens_the_bus():
+    """``_ensure_dbus_glib_loop()`` must precede the keyring lookup.
+
+    Asserted against the source of ``main`` because the failure is one of
+    *ordering*: both calls succeed on their own, and the damage only shows
+    up later as an MPRIS server that cannot export.
+    """
+    import refrain.app as app
+
+    src = Path(app.__file__).read_text()
+    body = src[src.index("def main(") :]
+
+    loop_at = body.index("_ensure_dbus_glib_loop()")
+    keyring_at = body.index("_load_lastfm_secrets(")
+    assert loop_at < keyring_at, (
+        "_ensure_dbus_glib_loop() must run before the Secret Service lookup — "
+        "dbus.SessionBus() is a singleton and the first caller wins"
+    )
+
+
+def test_dispatch_pump_starts_only_after_qapplication():
+    """The pump call must sit after ``QApplication`` is constructed."""
+    import refrain.app as app
+
+    src = Path(app.__file__).read_text()
+    body = src[src.index("def main(") :]
+
+    qapp_at = body.index("QApplication(sys.argv)")
+    pump_at = body.index("ensure_dbus_dispatch_pump()")
+    assert qapp_at < pump_at, (
+        "ensure_dbus_dispatch_pump() must run after QApplication — starting a "
+        "GLib loop first steals the default GMainContext and segfaults Qt"
+    )
+
+
+def test_ensure_dbus_glib_loop_starts_no_thread_of_its_own():
+    """Wiring the dispatch must not spin a loop; that is the pump's job."""
+    import refrain.sources.mpris_server as M
+
+    src = Path(M.__file__).read_text()
+    fn = src[src.index("def _ensure_dbus_glib_loop(") : src.index("def _qt_pumps_glib_context(")]
+    assert "Thread(" not in fn, (
+        "_ensure_dbus_glib_loop() must not start a GLib thread — it runs before QApplication exists"
+    )
+    assert "DBusGMainLoop(set_as_default=True)" in fn
+
+
+# ---------------------------------------------------------------------------
+# Dispatcher classification (regression 2)
+# ---------------------------------------------------------------------------
+class _FakeMeta:
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    def className(self) -> str:
+        return self._name
+
+
+class _FakeDispatcher:
+    def __init__(self, name: str) -> None:
+        self._meta = _FakeMeta(name)
+
+    def metaObject(self) -> _FakeMeta:
+        return self._meta
+
+
+@pytest.mark.parametrize(
+    ("class_name", "pumps"),
+    [
+        ("QPAEventDispatcherGlib", True),
+        ("QEventDispatcherGlib", True),
+        ("QEventDispatcherUNIX", False),
+    ],
+)
+def test_qt_pumps_glib_context_classification(monkeypatch, class_name, pumps):
+    """className() is a ``str`` — comparing it against ``bytes`` raised a
+    TypeError that the defensive except swallowed, so every install took
+    the fallback path."""
+    import PySide6.QtCore as QtCore
+
+    import refrain.sources.mpris_server as M
+
+    monkeypatch.setattr(
+        QtCore.QCoreApplication, "instance", staticmethod(lambda: object()), raising=False
+    )
+    monkeypatch.setattr(
+        QtCore.QAbstractEventDispatcher,
+        "instance",
+        staticmethod(lambda: _FakeDispatcher(class_name)),
+        raising=False,
+    )
+    assert M._qt_pumps_glib_context() is pumps
+
+
+def test_qt_pumps_glib_context_false_without_qapplication(monkeypatch):
+    import PySide6.QtCore as QtCore
+
+    import refrain.sources.mpris_server as M
+
+    monkeypatch.setattr(
+        QtCore.QCoreApplication, "instance", staticmethod(lambda: None), raising=False
+    )
+    assert M._qt_pumps_glib_context() is False
+
+
+# ---------------------------------------------------------------------------
+# Pump behaviour
+# ---------------------------------------------------------------------------
+def test_pump_is_a_noop_when_qt_already_pumps(monkeypatch):
+    import refrain.sources.mpris_server as M
+
+    monkeypatch.setattr(M, "_DBUS_LOOP_INITIALIZED", True)
+    monkeypatch.setattr(M, "_GLIB_THREAD", None)
+    monkeypatch.setattr(M, "_qt_pumps_glib_context", lambda: True)
+
+    M.ensure_dbus_dispatch_pump()
+
+    assert M._GLIB_THREAD is None
+
+
+def test_pump_does_nothing_when_dispatch_was_never_wired(monkeypatch):
+    """No PyGObject means no dispatch and no loop — just graceful degradation."""
+    import refrain.sources.mpris_server as M
+
+    monkeypatch.setattr(M, "_DBUS_LOOP_INITIALIZED", False)
+    monkeypatch.setattr(M, "_GLIB_THREAD", None)
+
+    def _boom():  # pragma: no cover - must not be reached
+        raise AssertionError("must not classify the dispatcher without dbus wired up")
+
+    monkeypatch.setattr(M, "_qt_pumps_glib_context", _boom)
+
+    M.ensure_dbus_dispatch_pump()
+
+    assert M._GLIB_THREAD is None
+
+
+def test_pump_is_idempotent(monkeypatch):
+    import refrain.sources.mpris_server as M
+
+    sentinel = object()
+    monkeypatch.setattr(M, "_DBUS_LOOP_INITIALIZED", True)
+    monkeypatch.setattr(M, "_GLIB_THREAD", sentinel)
+
+    def _boom():  # pragma: no cover - must not be reached
+        raise AssertionError("must not re-classify once a loop is running")
+
+    monkeypatch.setattr(M, "_qt_pumps_glib_context", _boom)
+
+    M.ensure_dbus_dispatch_pump()
+
+    assert M._GLIB_THREAD is sentinel
+
+
+def test_warning_names_the_distro_packages():
+    """The PyGObject hint is the only thing a user sees when controls are
+    missing — keep it actionable."""
+    import refrain.sources.mpris_server as M
+
+    src = Path(M.__file__).read_text()
+    fn = src[src.index("def _ensure_dbus_glib_loop(") : src.index("def _qt_pumps_glib_context(")]
+    for pkg in ("python-gobject", "python3-gi"):
+        assert pkg in fn
+    assert re.search(r"PyGObject not installed", fn)