muxplex-deck 0.5.2__tar.gz → 0.6.0__tar.gz

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: muxplex-deck
-Version: 0.5.2
+Version: 0.6.0
 Summary: Hardware probe/diagnostic app for the Elgato Stream Deck+ (seed of the muxplex sidecar)
 Author: Amplifier
 Author-email: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "muxplex-deck"
-version = "0.5.2"
+version = "0.6.0"
 description = "Hardware probe/diagnostic app for the Elgato Stream Deck+ (seed of the muxplex sidecar)"
 readme = "README.md"
 authors = [

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/src/deck_probe/main.py

@@ -34,6 +34,8 @@ from StreamDeck.DeviceManager import DeviceManager, ProbeError
 from StreamDeck.Devices.StreamDeck import StreamDeck
 from StreamDeck.Transport.Transport import TransportError
 
+from muxplex_deck import hidapi_win
+
 from . import capabilities, events
 
 logger = logging.getLogger("deck_probe")
@@ -146,6 +148,10 @@ def _install_signal_handler() -> threading.Event:
 def run() -> int:
     _configure_logging()
 
+    # No-op on non-Windows; on Windows this must run BEFORE DeviceManager()
+    # ever imports/loads the native library -- see hidapi_win's module
+    # docstring for why both of its mechanisms are required.
+    hidapi_win.ensure_hidapi()
     try:
         manager = DeviceManager()
     except ProbeError:

muxplex_deck-0.6.0/src/muxplex_deck/_vendor/hidapi/LICENSE-bsd.txt

@@ -0,0 +1,26 @@
+Copyright (c) 2010, Alan Ott, Signal 11 Software
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Signal 11 Software nor the names of its
+      contributors may be used to endorse or promote products derived from
+      this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

muxplex_deck-0.6.0/src/muxplex_deck/_vendor/hidapi/VERSION

@@ -0,0 +1,31 @@
+Upstream: libusb/hidapi
+Tag:      hidapi-0.15.0
+Release:  https://github.com/libusb/hidapi/releases/tag/hidapi-0.15.0
+Asset:    hidapi-win.zip
+Asset URL: https://github.com/libusb/hidapi/releases/download/hidapi-0.15.0/hidapi-win.zip
+
+sha256 (hidapi-win.zip):     d18c43ec9506a2f6d7faa9c7e0a342c4b64fbae521b71b5d4ac0777fd24dda93
+sha256 (x64/hidapi.dll):     d4c05ba2138cb5259a7f796464b5eaa63b9f8f67bb5cb003f96989244ee01583
+
+Extracted: x64/hidapi.dll only (166912 bytes). The x86 build, headers, and
+.pdb/.lib files from the release asset are not vendored -- this project only
+supports 64-bit Python on Windows (see WINDOWS_NATIVE_SPEC.md section 2.4).
+
+License: BSD 3-clause (see LICENSE-bsd.txt in this directory), one of
+HIDAPI's three available license options. Chosen because its one
+redistribution obligation (reproduce the copyright notice) is trivially
+satisfied and it does not affect muxplex-deck's own license, unlike the
+GPLv3 option.
+
+To bump this vendored DLL to a newer hidapi release:
+1. Download the new release's `hidapi-win.zip` asset from
+   https://github.com/libusb/hidapi/releases
+2. Verify its SHA-256 against the value published in that release's notes
+   (or compute it yourself and record it here -- never vendor an unverified
+   download).
+3. Extract `x64/hidapi.dll` and overwrite the file next to this one.
+4. Update the tag, asset URL, and both SHA-256 values above.
+5. Re-run the full test suite; nothing in this repo depends on the DLL's
+   internal behavior beyond "streamdeck's ctypes probe can load it", which
+   only real Windows hardware can confirm (see AGENTS.md / the sign-off
+   checklist in WINDOWS_NATIVE_SPEC.md section 9).

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/src/muxplex_deck/cli.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import argparse
 import contextlib
 import json
+import os
 import platform
 import shutil
 import subprocess
@@ -328,13 +329,30 @@ def check_config_file(config_path: str | None = None) -> tuple[str, str]:
 
 
 def check_federation_key(key_file: Path) -> tuple[str, str]:
-    """Federation key presence + permission check. Never prints the key itself."""
+    """Federation key presence + permission check. Never prints the key itself.
+
+    On Windows, `Path.chmod()` only toggles the read-only bit -- it does not
+    restrict other users -- so `st_mode` reads back as a permissive value
+    (typically 0o666) no matter what actually protects the file (NTFS ACLs,
+    which are per-user profile directories by default). Warning on every
+    run and recommending a `chmod` that cannot fix anything would violate
+    this repo's own rule (AGENTS.md: never print a command that cannot work
+    on the machine you are printing it to) -- so Windows gets presence-only
+    reporting, no POSIX-mode judgment, and no ACL check (that would be new,
+    untested, platform-specific security code for a file already inside a
+    per-user profile directory; see WINDOWS_NATIVE_SPEC.md section 3.3).
+    """
     if not key_file.exists():
         return "warn", f"Federation key file not found: {key_file}"
     try:
         mode = key_file.stat().st_mode & 0o777
     except OSError as exc:
         return "warn", f"Could not stat federation key file {key_file}: {exc}"
+    if sys.platform == "win32":
+        return "ok", (
+            f"Federation key: {key_file} "
+            "(NTFS ACLs govern access here -- POSIX modes are not enforced)"
+        )
     if mode & 0o077:
         return "warn", (
             f"Federation key file {key_file} is readable by others "
@@ -394,6 +412,53 @@ def check_ca_file(ca_file: Path | None) -> tuple[str, str]:
     )
 
 
+def check_hidapi_dll() -> tuple[str, str] | None:
+    """Windows-only: report which `hidapi.dll` streamdeck's loader will actually use.
+
+    Returns `None` on every other platform (nothing to check -- other OSes
+    use their own dynamic linker conventions and the check is simply
+    skipped, not appended to the doctor output).
+
+    `hidapi_win.ensure_hidapi()` can create a silent shadowing failure mode
+    if something earlier on `%PATH%` wins the load race (see that module's
+    docstring for the mechanism) -- a design that creates a failure mode
+    owes the user a way to see it, so this always prints a line on
+    Windows, not only when something is wrong (WINDOWS_NATIVE_SPEC.md
+    section 2.6).
+    """
+    if sys.platform != "win32":
+        return None
+
+    from . import hidapi_win
+
+    dll_dir = hidapi_win.ensure_hidapi()
+    if dll_dir is None:
+        return "warn", (
+            "hidapi.dll: vendored copy not found in this install (Windows "
+            "arm64, or a source checkout without the vendored binary) -- "
+            "see https://github.com/libusb/hidapi/releases"
+        )
+
+    vendored = str(hidapi_win.vendored_dll_path())
+    resolved = hidapi_win.resolved_library_path()
+    if resolved is None:
+        return "warn", (
+            f"hidapi.dll: vendored copy present at {vendored} but "
+            "ctypes.util.find_library('hidapi') did not resolve anything "
+            "(check %PATH%)"
+        )
+    # Case-insensitive: see hidhelp._windows_guidance()'s comment on the
+    # same comparison -- os.path.normcase only behaves case-insensitively
+    # when the running process actually IS Windows, not when sys.platform
+    # is merely monkeypatched (as tests, and this repo's Linux-only CI, do).
+    if resolved.lower() != vendored.lower():
+        return "warn", (
+            f"hidapi.dll: resolves to {resolved} -- NOT the vendored copy "
+            "(see the WIN-DLL-SHADOW guidance below)"
+        )
+    return "ok", f"hidapi.dll: resolves to the vendored copy ({resolved})"
+
+
 def probe_deck_status(manager: Any) -> dict:
     """Pure: given a `DeviceManager`-shaped object, find + describe the deck.
 
@@ -593,6 +658,60 @@ def check_server_reachable(server_url: str, ca_file: Path | None) -> tuple[str,
         return "warn", f"Server check failed: {exc}"
 
 
+def check_federation_key_auth(
+    server_url: str, federation_key: str, *, verify: bool | str = True
+) -> tuple[str, str]:
+    """Issue ONE authenticated request to confirm `federation_key` is actually accepted.
+
+    `/api/instance-info` (what `check_server_reachable`/`fetch_instance_info`
+    call) is unauthenticated by design on the server -- it proves TLS and
+    reachability, but nothing about a credential. That gap is exactly what
+    let `init` once print a green "Server reachable" check, write config,
+    and offer to install the service for a federation key that was simply
+    wrong -- the user only found out once the running service couldn't
+    authenticate (see AGENTS.md).
+
+    This hits `GET /api/sessions` instead: authenticated, read-only, the
+    same lightweight endpoint the sidecar's own active loop already polls
+    (see `main.py`), with the key sent as `Authorization: Bearer` -- the
+    exact scheme the muxplex server's `auth.py` checks. Returns one of:
+
+      ("ok", ...)      -- HTTP 200: the key is accepted.
+      ("fail", ...)     -- HTTP 401: the key is definitively rejected.
+                           Callers must not save a key that gets this back.
+      ("warn", ...)     -- anything else (timeout, connection error,
+                           unexpected status): could not verify one way or
+                           the other. This is NOT evidence the key is bad --
+                           callers must not print a false success, but also
+                           must not treat an unrelated network hiccup as a
+                           rejected key.
+    """
+    import httpx
+
+    url = f"{server_url.rstrip('/')}/api/sessions"
+    headers = {"Authorization": f"Bearer {federation_key}"}
+    try:
+        with httpx.Client(verify=verify, timeout=5.0) as client:
+            resp = client.get(url, headers=headers)
+    except httpx.TimeoutException as exc:
+        return (
+            "warn",
+            f"Could not verify federation key -- server check timed out: {exc}",
+        )
+    except httpx.ConnectError as exc:
+        return "warn", f"Could not verify federation key -- server unreachable: {exc}"
+    except Exception as exc:  # noqa: BLE001 -- verification must degrade to warn, never raise
+        return "warn", f"Could not verify federation key: {exc}"
+
+    if resp.status_code == 200:
+        return "ok", "Federation key accepted by server"
+    if resp.status_code == 401:
+        return "fail", "Federation key rejected by server (401 Unauthorized)"
+    return "warn", (
+        f"Could not verify federation key -- unexpected response HTTP {resp.status_code}"
+    )
+
+
 def check_service_status() -> tuple[str, str]:
     """Service-state check: not installed / installed but not running / running.
 
@@ -629,6 +748,13 @@ _CHECK_MARKS: dict[str, str] = {
     "ok": "\033[32m\u2713\033[0m",
     "fail": "\033[31m\u2717\033[0m",
     "warn": "\033[33m!\033[0m",
+    # Distinct from "warn": "warn" means a check RAN and found something to
+    # flag; "unknown" means the check could not be run at all yet (e.g. the
+    # currently-running process hasn't published a status write of its own
+    # yet). Conflating the two is what let a dying process's stale-but-
+    # recent status snapshot get reported as definite failures right after
+    # `service restart` -- see AGENTS.md's restart-race incident.
+    "unknown": "\033[36m?\033[0m",
 }
 
 
@@ -668,6 +794,11 @@ def doctor(config_path: str | None = None) -> int:
         ca_file = config_mod._expand(raw["ca_file"])
     checks.append(check_ca_file(ca_file))
 
+    # Windows-only; None (skipped, not appended) on every other platform.
+    hidapi_check = check_hidapi_dll()
+    if hidapi_check is not None:
+        checks.append(hidapi_check)
+
     # Environment guidance (WSL/usbipd/udev-liveness) BEFORE the device
     # checks -- it explains why the next line is about to warn. Returns []
     # on a healthy platform (macOS, or native Linux with udev running), so
@@ -789,7 +920,7 @@ def status(config_path: str | None = None, *, as_json: bool = False) -> int:
     fall back to a direct probe -- this keeps `status` useful even before
     the service has ever been installed.
     """
-    from .service import service_is_active
+    from .service import service_is_active, service_main_pid
     from .statusfile import read_status
 
     running = service_is_active()
@@ -825,13 +956,44 @@ def status(config_path: str | None = None, *, as_json: bool = False) -> int:
 
     if data is None:
         print_check(
-            "warn",
+            "unknown",
             "No status file found even though the service is running -- it "
             "may have just started. Try: muxplex-deck service logs",
         )
         print()
         return 0
 
+    # Is this snapshot from the process running RIGHT NOW, or from a
+    # PREVIOUS incarnation? Age alone can't tell: a process that's about to
+    # be replaced (e.g. by `service restart`) can write its LAST status
+    # moments before exiting, so it still looks "fresh" by age even though
+    # it no longer reflects reality -- exactly the restart-race incident in
+    # AGENTS.md (2 false failures reported from a dying process's stale-but-
+    # recent write). Comparing the recorded pid to the service manager's own
+    # live MainPID is the reliable signal; fall back to the age check only
+    # when the live pid can't be determined at all (unsupported platform,
+    # command failure).
+    current_pid = service_main_pid()
+    recorded_pid = data.get("pid")
+    if current_pid is not None:
+        is_current = recorded_pid == current_pid
+    else:
+        is_current = (
+            time.time() - data.get("updated_at", 0)
+        ) <= _STATUS_STALE_THRESHOLD_SECONDS
+
+    if not is_current:
+        print_check(
+            "unknown",
+            f"Status not yet available for the running process (pid "
+            f"{current_pid if current_pid is not None else '?'}) -- the "
+            f"published status is from a previous run (pid {recorded_pid}). "
+            "This is expected right after (re)starting; try again in a "
+            "moment, or: muxplex-deck service logs",
+        )
+        print()
+        return 0
+
     age = time.time() - data.get("updated_at", 0)
     if age > _STATUS_STALE_THRESHOLD_SECONDS:
         print_check(
@@ -886,8 +1048,6 @@ def _find_uv() -> str | None:
 
 
 def _is_executable(path: str) -> bool:
-    import os
-
     return os.access(path, os.X_OK)
 
 
@@ -977,8 +1137,6 @@ def update(*, force: bool = False) -> None:
     if was_active:
         print("  Stopping service...")
         if sys.platform == "darwin":
-            import os
-
             uid = os.getuid()
             subprocess.run(
                 ["launchctl", "bootout", f"gui/{uid}/com.muxplex-deck"],

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/src/muxplex_deck/device_real.py

@@ -19,6 +19,7 @@ from StreamDeck.DeviceManager import ProbeError as _LibProbeError
 from StreamDeck.Devices.StreamDeck import StreamDeck as _LibStreamDeck
 from StreamDeck.Transport.Transport import TransportError
 
+from . import hidapi_win
 from .device import (
     DeckDevice,
     DeviceProbeError,
@@ -34,8 +35,13 @@ _MISSING_HIDAPI_MESSAGE = (
     "Install it for your platform, then try again:\n"
     "  macOS:          brew install hidapi\n"
     "  Debian/Ubuntu:  sudo apt install libhidapi-libusb0\n"
-    "  Windows:        bundled with the 'streamdeck' wheel; if missing, install\n"
-    "                  hidapi via your package manager of choice.\n"
+    "  Windows:        muxplex-deck bundles hidapi.dll -- if you're seeing this,\n"
+    "                  either the vendored copy is missing from this install\n"
+    "                  (arm64 Windows, or a source checkout without the binary),\n"
+    "                  or a different hidapi.dll earlier on %PATH% shadowed it.\n"
+    "                  Run 'muxplex-deck doctor' for which DLL actually resolved,\n"
+    "                  or get one yourself: https://github.com/libusb/hidapi/releases\n"
+    "                  (the loader also honors ./hidapi.dll in the current directory).\n"
 )
 
 
@@ -147,6 +153,11 @@ class RealDeviceManager:
     """
 
     def __init__(self) -> None:
+        # No-op on non-Windows; on Windows this must run BEFORE
+        # _LibDeviceManager() ever imports/loads the native library -- see
+        # hidapi_win's module docstring for why both of its mechanisms are
+        # required to make the vendored DLL win the load-path race.
+        hidapi_win.ensure_hidapi()
         try:
             self._manager = _LibDeviceManager()
         except _LibProbeError as exc:

muxplex_deck-0.6.0/src/muxplex_deck/hidapi_win.py

@@ -0,0 +1,113 @@
+"""Windows-only: make the vendored `hidapi.dll` resolvable by streamdeck's loader.
+
+`StreamDeck/Transport/LibUSBHIDAPI.py` probes for a native HIDAPI shared
+library by name via ctypes -- Windows ships no such library, so without
+this module a Windows user gets `ProbeError: ... Is the 'hidapi.dll'
+library installed?` (see WINDOWS_NATIVE_SPEC.md section 2).
+
+**The load-path trap this module exists to close** (verified by reading
+CPython + streamdeck source, section 2.1 of the spec):
+
+    for lib_name in library_search_list:                      # streamdeck
+        found_lib = ctypes.util.find_library(name_no_ext)      # <-- FIRST
+        HIDAPI_INSTANCE = ctypes.cdll.LoadLibrary(found_lib or lib_name)
+
+`ctypes.util.find_library()` on Windows (the `nt` branch) searches
+**`%PATH%` only** and returns the first match. `ctypes.CDLL`'s own loader
+(reached when `find_library` returns `None`) uses
+`LOAD_LIBRARY_SEARCH_DEFAULT_DIRS`, which honors `os.add_dll_directory()`
+but does **not** consult `%PATH%`. Net effect: a stray or wrong-arch
+`hidapi.dll` earlier on `%PATH%` wins over anything registered via
+`add_dll_directory`, `LoadLibrary` on it fails, the bare `except: pass` in
+streamdeck's probe swallows the failure, and the vendored DLL is never
+tried at all. This is a silent failure mode and both mechanisms below are
+required to close it -- neither one alone is sufficient.
+
+No-op (returns `None`, touches nothing) on every non-Windows platform.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+__all__ = ["ensure_hidapi", "resolved_library_path", "vendored_dll_path"]
+
+# Holds the `os.add_dll_directory()` return value. That object's __del__
+# un-registers the directory when garbage collected -- keeping it at module
+# scope for the life of the process is what makes the registration stick.
+_dll_directory_cookie: object | None = None
+
+
+def vendored_dll_path() -> Path:
+    """Path where the vendored `x64/hidapi.dll` is expected, whether or not it exists.
+
+    A plain path computation, not an existence check -- callers that need
+    to know if it's actually there should check `.exists()` themselves or
+    call `ensure_hidapi()`, which does.
+    """
+    return Path(__file__).parent / "_vendor" / "hidapi" / "x64" / "hidapi.dll"
+
+
+def ensure_hidapi() -> Path | None:
+    """Register the vendored HIDAPI directory so streamdeck's loader finds it.
+
+    No-op on non-Windows (returns `None` immediately, no filesystem or
+    environment changes). On `win32`:
+
+    - Returns `None` if the vendored DLL is absent (arm64 Windows, or a
+      source checkout that doesn't carry the binary blob) -- callers fall
+      back to guidance (see `hidhelp._windows_guidance`'s `WIN-NOHIDAPI`);
+      this function never raises.
+    - Otherwise registers the DLL's directory via `os.add_dll_directory()`
+      *and* prepends it to `%PATH%` (both are required -- see the module
+      docstring), then returns the directory.
+
+    Idempotent: safe to call from every entry point (`RealDeviceManager`,
+    `deck-probe`) without worrying about double-registration -- the
+    `add_dll_directory` cookie is only created once, and the `%PATH%`
+    prepend is skipped if our directory is already present.
+    """
+    global _dll_directory_cookie
+
+    if sys.platform != "win32":
+        return None
+
+    dll_path = vendored_dll_path()
+    if not dll_path.exists():
+        return None
+
+    dll_dir = dll_path.parent
+
+    if _dll_directory_cookie is None:
+        _dll_directory_cookie = os.add_dll_directory(str(dll_dir))  # type: ignore[attr-defined]
+
+    dir_str = str(dll_dir)
+    current_path = os.environ.get("PATH", "")
+    existing_entries = current_path.split(os.pathsep) if current_path else []
+    if dir_str not in existing_entries:
+        os.environ["PATH"] = (
+            f"{dir_str}{os.pathsep}{current_path}" if current_path else dir_str
+        )
+
+    return dll_dir
+
+
+def resolved_library_path() -> str | None:
+    """What `ctypes.util.find_library("hidapi")` actually resolves to, right now.
+
+    `None` on non-Windows (nothing to resolve -- other platforms use their
+    own dynamic linker conventions) or if nothing on `%PATH%` matches.
+    Does **not** call `ensure_hidapi()` itself -- callers that want "as
+    streamdeck will actually see it" must call `ensure_hidapi()` first, so
+    the comparison reflects the same environment streamdeck's probe runs
+    in. This split (rather than folding the call in here) keeps this
+    function a pure read of current process state, easy to test without
+    also exercising the registration side effects.
+    """
+    if sys.platform != "win32":
+        return None
+    import ctypes.util
+
+    return ctypes.util.find_library("hidapi")

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/src/muxplex_deck/hidhelp.py

@@ -230,6 +230,149 @@ def impostor_message(paths: wsl.UsbipdPaths) -> str:
     )
 
 
+# ---------------------------------------------------------------------------
+# Native Windows guidance (WINDOWS_NATIVE_SPEC.md section 4) -- the win32
+# counterpart of the WSL states above. Same contract: `_windows_guidance()`
+# returns [] on a healthy box, so `doctor()`'s output stays unchanged there.
+# ---------------------------------------------------------------------------
+
+WIN_ELGATO_MESSAGE = (
+    "The official Elgato Stream Deck app is running and holds exclusive HID\n"
+    "access to the device -- muxplex-deck cannot open it while that app is\n"
+    "open. Close it (system tray -> Quit), then:\n"
+    "    muxplex-deck service restart"
+)
+
+WIN_NOHIDAPI_MESSAGE = (
+    "The bundled HIDAPI library (hidapi.dll) is missing from this install --\n"
+    "this happens on Windows arm64 (no official prebuilt for it) or a source\n"
+    "checkout without the vendored binary. Get one yourself:\n"
+    "    https://github.com/libusb/hidapi/releases\n"
+    "and either put hidapi.dll on your PATH, or drop it into the directory\n"
+    "you run muxplex-deck from (the loader also checks ./hidapi.dll)."
+)
+
+
+def win_usbip_message(device: wsl.UsbipdDevice) -> str:
+    return (
+        f"Stream Deck (BUSID {device.busid}, {device.vid_pid}) is currently handed to\n"
+        "WSL -- Windows cannot see it. No administrator rights needed:\n"
+        f"    usbipd detach --busid {device.busid}\n"
+        "Then physically unplug and replug the deck. Verified: after detach, the\n"
+        "deck keeps rendering whatever WSL last drew, and native Windows cannot\n"
+        "claim it until it is power-cycled -- this is a real step, not a quirk."
+    )
+
+
+def win_dll_shadow_message(resolved: str, vendored: str) -> str:
+    return (
+        "A different hidapi.dll is shadowing the one muxplex-deck bundles:\n"
+        f"    resolved (what streamdeck will actually load): {resolved}\n"
+        f"    bundled (what muxplex-deck vendors):            {vendored}\n"
+        "Something earlier on %PATH% is winning the load race. Remove or\n"
+        "reorder it, then run muxplex-deck doctor again to confirm."
+    )
+
+
+def _elgato_app_running() -> bool | None:
+    """Best-effort: is a process resembling the official Elgato app running?
+
+    `None` if it could not be determined (e.g. `tasklist` missing, timed
+    out, or any other failure) -- callers must not treat "could not check"
+    as "not running", the same never-guess discipline every other
+    fact-gatherer in this module follows.
+    """
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["tasklist"], capture_output=True, text=True, timeout=5, check=False
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    return "streamdeck" in result.stdout.lower()
+
+
+def _win_usbip_guidance(*, allow_usbipd_query: bool) -> Guidance | None:
+    """WIN-USBIP: the deck is currently bound to WSL, invisible to native Windows.
+
+    Reuses `wsl.find_usbipd()` / `wsl.list_devices()` as-is -- `usbipd.exe
+    list`'s output is the same text whether invoked from WSL or native
+    PowerShell. `wsl.attach()` is never called from this path; it remains
+    the one mutating function in the whole surface, WSL-only.
+    """
+    if not allow_usbipd_query:
+        return None
+    paths = wsl.find_usbipd()
+    if paths.windows is None:
+        return None
+    devices = wsl.list_devices(paths.windows, vendor_id=_ELGATO_VENDOR_ID)
+    if not devices:
+        return None
+    device = devices[0]
+    if device.state != "attached":
+        return None
+    return Guidance(status="warn", message=win_usbip_message(device), state="WIN-USBIP")
+
+
+def _windows_guidance(*, allow_usbipd_query: bool = True) -> list[Guidance]:
+    """Native-Windows environment guidance. Returns [] on a healthy box.
+
+    Checked in priority order -- each state, once true, fully explains "no
+    device" on its own, and the remaining checks would either be moot (the
+    app holds the device -- nothing else matters) or misleading (once
+    WIN-USBIP explains why Windows can't see the device at all, checking
+    hidapi resolution is a distraction):
+
+    1. WIN-ELGATO -- the #1 native-Windows failure and cheaply detectable;
+       say it specifically instead of a bare "no device found".
+    2. WIN-USBIP -- the deck is handed to WSL.
+    3. WIN-NOHIDAPI -- the vendored DLL itself is missing.
+    4. WIN-DLL-SHADOW -- the vendored DLL exists but something else on
+       %PATH% won the load race (see `hidapi_win`'s module docstring for
+       the mechanism this closes).
+
+    `allow_usbipd_query=False` skips WIN-ELGATO and WIN-USBIP (both shell
+    out) -- the same escape hatch `explain_environment()` honors for
+    contexts that must not shell out.
+    """
+    if allow_usbipd_query and _elgato_app_running():
+        return [Guidance(status="warn", message=WIN_ELGATO_MESSAGE, state="WIN-ELGATO")]
+
+    usbip_guidance = _win_usbip_guidance(allow_usbipd_query=allow_usbipd_query)
+    if usbip_guidance is not None:
+        return [usbip_guidance]
+
+    from . import hidapi_win
+
+    dll_dir = hidapi_win.ensure_hidapi()
+    if dll_dir is None:
+        return [
+            Guidance(status="warn", message=WIN_NOHIDAPI_MESSAGE, state="WIN-NOHIDAPI")
+        ]
+
+    resolved = hidapi_win.resolved_library_path()
+    vendored = str(hidapi_win.vendored_dll_path())
+    # Case-insensitive: Windows paths are case-insensitive, and a bare
+    # `os.path.normcase` comparison would only behave that way when the
+    # process actually running is Windows (it's bound to ntpath vs
+    # posixpath at interpreter start, unaffected by monkeypatching
+    # `sys.platform` in tests) -- `.lower()` keeps this deterministic
+    # everywhere the check runs, including this repo's Linux-only CI.
+    if resolved is not None and resolved.lower() != vendored.lower():
+        return [
+            Guidance(
+                status="warn",
+                message=win_dll_shadow_message(resolved, vendored),
+                state="WIN-DLL-SHADOW",
+            )
+        ]
+
+    return []
+
+
 # ---------------------------------------------------------------------------
 # Public API
 # ---------------------------------------------------------------------------
@@ -251,7 +394,9 @@ def explain_environment(*, allow_usbipd_query: bool = True) -> list[Guidance]:
     info = wsl.detect()
 
     if not info.is_wsl:
-        if sys.platform not in ("darwin", "win32") and not usbnode.udev_is_live():
+        if sys.platform == "win32":
+            return _windows_guidance(allow_usbipd_query=allow_usbipd_query)
+        if sys.platform != "darwin" and not usbnode.udev_is_live():
             guidances.append(
                 Guidance(
                     status="warn", message=u_dead_container_message(), state="U-DEAD"

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/src/muxplex_deck/init_wizard.py

@@ -207,10 +207,24 @@ def _resolve_ca(
 def _resolve_federation_key(
     key_file_path: Path,
     *,
+    server_url: str,
+    ca_file: str | None,
     non_interactive: bool,
     input_func: Callable[[str], str],
     getpass_func: Callable[[str], str],
 ) -> None:
+    """Resolve, VALIDATE, and write the federation key.
+
+    A pasted/loaded key is never written on faith. `/api/instance-info`
+    (already used above to verify the server) is unauthenticated and proves
+    nothing about a credential -- this is exactly the gap that let `init`
+    once print a green "Server reachable" check, write config, and offer to
+    install the service for a federation key that was simply wrong; the
+    user only found out once the running service couldn't authenticate
+    (see AGENTS.md). `cli.check_federation_key_auth` issues one real
+    authenticated request and this loops until it's accepted, or the user
+    gives up (Ctrl-C/EOF, handled by `run_init`'s caller).
+    """
     if key_file_path.exists() and key_file_path.stat().st_size > 0:
         if non_interactive:
             print(f"  Federation key: keeping existing {key_file_path}")
@@ -237,17 +251,38 @@ def _resolve_federation_key(
         "read ~/.config/muxplex/federation_key there. SSH fallback:"
     )
     print(f"    scp <your-server>:.config/muxplex/federation_key {key_file_path}")
-    pasted = getpass_func("Federation key (or path): ")
-    value = pasted.strip()
-    candidate_path = Path(value).expanduser() if value else None
 
-    if candidate_path is not None and candidate_path.is_file():
-        key_value = candidate_path.read_text(encoding="utf-8").strip()
-    else:
-        key_value = value
+    verify: bool | str = ca_file if ca_file else True
+    key_value = ""
+    while True:
+        pasted = getpass_func("Federation key (or path): ")
+        value = pasted.strip()
+        candidate_path = Path(value).expanduser() if value else None
+
+        if candidate_path is not None and candidate_path.is_file():
+            key_value = candidate_path.read_text(encoding="utf-8").strip()
+        else:
+            key_value = value
 
-    if not key_value:
-        raise _InitError("no federation key provided")
+        if not key_value:
+            raise _InitError("no federation key provided")
+
+        status, message = cli_mod.check_federation_key_auth(
+            server_url, key_value, verify=verify
+        )
+        if status == "ok":
+            cli_mod.print_check("ok", "Federation key: verified against server")
+            break
+        if status == "fail":
+            cli_mod.print_check("fail", message)
+            print("  Try again -- paste the correct key, or a path to it.")
+            continue
+        # status == "warn": could not verify one way or the other (network
+        # hiccup, timeout) -- not evidence the key itself is wrong, so
+        # don't loop forever on something re-pasting can't fix. Still,
+        # never claim a check that didn't actually run succeeded.
+        cli_mod.print_check("warn", message)
+        break
 
     key_file_path.parent.mkdir(parents=True, exist_ok=True)
     key_file_path.parent.chmod(0o700)
@@ -311,6 +346,8 @@ def _run_init_impl(
     key_file_raw = raw.get("key_file") or config_mod.DEFAULT_KEY_FILE
     _resolve_federation_key(
         config_mod._expand(key_file_raw),
+        server_url=server_url,
+        ca_file=ca_file_value,
         non_interactive=non_interactive,
         input_func=input_func,
         getpass_func=getpass_func,

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/src/muxplex_deck/service.py

@@ -72,6 +72,20 @@ _LAUNCHD_ALREADY_LOADED_EXIT = 5
 _LAUNCHD_BOOTOUT_POLL_INTERVAL_SECONDS = 0.2
 _LAUNCHD_BOOTOUT_TIMEOUT_SECONDS = 5.0
 
+# `systemctl restart` / `launchctl bootstrap` both return once the new
+# process has been LAUNCHED, not once it has done anything -- the new
+# sidecar needs at least one poll cycle to open the device (or notice it
+# can't) and publish its first status write via `statusfile.StatusReporter`.
+# Until then, `status.json` still holds the PREVIOUS process's last
+# snapshot, which `muxplex-deck status` would otherwise present as current,
+# healthy truth (the restart-race incident in AGENTS.md: 2 false failures
+# read from a dying process's stale-but-recent write, moments before it
+# exited). `restart` polls for a status write from the NEW process (by pid,
+# via `service_main_pid()`) before reporting success, bounded so a genuinely
+# slow-starting sidecar can't hang the command forever.
+_RESTART_STATUS_POLL_INTERVAL_SECONDS = 0.2
+_RESTART_STATUS_TIMEOUT_SECONDS = 5.0
+
 # Elgato Stream Deck USB vendor id -- used to detect an existing udev rule.
 _ELGATO_VENDOR_ID = "0fd9"
 _UDEV_RULE_DIRS: tuple[Path, ...] = (
@@ -309,6 +323,70 @@ def service_is_active() -> bool:
     return result.returncode == 0
 
 
+def service_main_pid() -> int | None:
+    """Best-effort PID of the currently-running muxplex-deck service process.
+
+    Never raises -- matches `service_is_active()`'s contract: any failure
+    (service manager missing, service not running, unexpected/unparseable
+    output) reads as "cannot determine", which callers must treat as "don't
+    know", never as a false positive or negative on its own.
+
+    This is what lets `status()` (and `_wait_for_fresh_status()` below) tell
+    whether a published `status.json` (`statusfile.build_status()`'s own
+    `pid` field) was written by the process running RIGHT NOW under the
+    service, or by a PREVIOUS incarnation whose last write can look
+    deceptively fresh by age alone -- see the restart-race incident in
+    AGENTS.md: the old process's last write happened moments before it
+    exited, so an age-only staleness check saw it as "recent" and reported
+    it as current truth. Comparing pids is the only way to tell those apart.
+    """
+    if _is_darwin():
+        uid = os.getuid()
+        try:
+            result = subprocess.run(
+                ["launchctl", "print", f"gui/{uid}/{_LAUNCHD_LABEL}"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except FileNotFoundError:
+            return None
+        if result.returncode != 0:
+            return None
+        for line in result.stdout.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("pid = "):
+                try:
+                    return int(stripped[len("pid = ") :].strip())
+                except ValueError:
+                    return None
+        return None
+
+    try:
+        result = subprocess.run(
+            [
+                "systemctl",
+                "--user",
+                "show",
+                "muxplex-deck",
+                "--property=MainPID",
+                "--value",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return None
+    if result.returncode != 0:
+        return None
+    try:
+        pid = int(result.stdout.strip())
+    except ValueError:
+        return None
+    return pid if pid > 0 else None
+
+
 def service_is_installed() -> bool:
     """Is the muxplex-deck unit/plist file present on disk?
 
@@ -502,6 +580,56 @@ def _systemd_stop() -> None:
     subprocess.run(["systemctl", "--user", "stop", "muxplex-deck"], check=False)
 
 
+def _wait_for_fresh_status(timeout: float | None = None) -> bool:
+    """Poll until `status.json`'s recorded pid matches the service's live
+    MainPID, or `timeout` elapses.
+
+    See `_RESTART_STATUS_TIMEOUT_SECONDS`'s docstring for why this exists:
+    the process a restart just launched needs at least one poll cycle
+    before it publishes its own status, and comparing pids (not wall-clock
+    age) is the only reliable way to tell "this snapshot belongs to the
+    process running right now" from "this is the previous process's last
+    write" -- the exact restart-race incident in AGENTS.md.
+
+    Returns True once a matching status is observed; False if `timeout`
+    elapses first. Never raises -- `service_main_pid()` and
+    `statusfile.read_status()` are both best-effort/never-raise themselves.
+    """
+    from . import statusfile
+
+    if timeout is None:
+        timeout = _RESTART_STATUS_TIMEOUT_SECONDS
+    deadline = time.monotonic() + timeout
+    while True:
+        current_pid = service_main_pid()
+        if current_pid is not None:
+            data = statusfile.read_status()
+            if data is not None and data.get("pid") == current_pid:
+                return True
+        if time.monotonic() >= deadline:
+            return False
+        time.sleep(_RESTART_STATUS_POLL_INTERVAL_SECONDS)
+
+
+def _report_restart_result(success_message: str) -> None:
+    """Print the final restart line: success only once fresh status is
+    actually observed, otherwise an honest "still waiting" warning.
+
+    Shared by systemd and launchd so both platforms make the same promise:
+    never print a success line for a step (the new process being up and
+    reporting) that was not actually verified -- see AGENTS.md's restart-
+    race incident, which this directly closes.
+    """
+    if _wait_for_fresh_status():
+        _step_ok(success_message)
+    else:
+        _step_warn(
+            "Restart command sent, but the service has not published fresh "
+            f"status within {_RESTART_STATUS_TIMEOUT_SECONDS:.0f}s -- it may "
+            "still be starting. Check: muxplex-deck status"
+        )
+
+
 def _systemd_restart() -> None:
     # `systemctl restart` is a single atomic transaction (unlike launchd's
     # separate bootout + bootstrap), so it needs no unload-race handling --
@@ -513,12 +641,12 @@ def _systemd_restart() -> None:
         text=True,
         check=False,
     )
-    if result.returncode == 0:
-        _step_ok("Restarted the service")
-    else:
+    if result.returncode != 0:
         _report_systemctl_failure("restart", result)
         sys.exit(1)
 
+    _report_restart_result("Restarted the service")
+
 
 def _systemd_status() -> None:
     subprocess.run(
@@ -704,13 +832,15 @@ def _launchd_restart() -> None:
 
     result = _launchd_bootstrap()
     if result.returncode == 0:
-        _step_ok("Restarted the service (launchctl bootstrap)")
+        success_message = "Restarted the service (launchctl bootstrap)"
     elif result.returncode == _LAUNCHD_ALREADY_LOADED_EXIT:
-        _step_ok("Service is running")
+        success_message = "Service is running"
     else:
         _report_launchctl_failure("bootstrap", result)
         sys.exit(1)
 
+    _report_restart_result(success_message)
+
 
 def _launchd_status() -> None:
     uid = os.getuid()

{muxplex_deck-0.5.2 → muxplex_deck-0.6.0}/src/muxplex_deck/statusfile.py

@@ -33,6 +33,7 @@ import contextlib
 import json
 import logging
 import os
+import sys
 import tempfile
 import time
 from pathlib import Path
@@ -45,6 +46,43 @@ SCHEMA_VERSION = 1
 _STATUS_DIR_NAME = "muxplex-deck"
 _STATUS_FILE_NAME = "status.json"
 
+# Windows only: os.replace() raises PermissionError when the destination is
+# open by another process -- and cli.status()/_wait_for_fresh_status() read
+# this exact file while the sidecar is writing it. The blanket `except
+# Exception` below already degrades a dropped write to a logged warning
+# (never a crash), but a dropped write during the restart-wait window could
+# manufacture exactly the false "has not published fresh status" alarm
+# v0.5.3 was released to eliminate -- see WINDOWS_NATIVE_SPEC.md section
+# 3.4. POSIX `rename()`/`replace()` has no such failure mode (an open file
+# descriptor doesn't block a rename), so this retry is Windows-only and
+# does not change behavior anywhere else.
+_WIN_REPLACE_RETRY_ATTEMPTS = 3
+_WIN_REPLACE_RETRY_DELAY_SECONDS = 0.05
+
+
+def _replace_with_windows_retry(src: str, dst: Path) -> None:
+    """`os.replace(src, dst)`, retrying on Windows if the destination is locked.
+
+    Elsewhere this is just `os.replace(src, dst)` -- no retry, no delay,
+    byte-for-byte the previous behavior. On `win32`, retries up to
+    `_WIN_REPLACE_RETRY_ATTEMPTS` times, `_WIN_REPLACE_RETRY_DELAY_SECONDS`
+    apart, before giving up; the final attempt's exception (if it still
+    fails) propagates to the caller's existing `except Exception` handler,
+    which logs and swallows it exactly as before this retry existed.
+    """
+    if sys.platform != "win32":
+        os.replace(src, dst)
+        return
+
+    for attempt in range(_WIN_REPLACE_RETRY_ATTEMPTS):
+        try:
+            os.replace(src, dst)
+            return
+        except PermissionError:
+            if attempt == _WIN_REPLACE_RETRY_ATTEMPTS - 1:
+                raise
+            time.sleep(_WIN_REPLACE_RETRY_DELAY_SECONDS)
+
 
 def default_status_dir() -> Path:
     """`$XDG_STATE_HOME/muxplex-deck`, default `~/.local/state/muxplex-deck`."""
@@ -129,7 +167,7 @@ def write_status(status: dict[str, Any], path: Path | None = None) -> None:
         try:
             with os.fdopen(fd, "w", encoding="utf-8") as f:
                 json.dump(status, f, indent=2)
-            os.replace(tmp_path, target)
+            _replace_with_windows_retry(tmp_path, target)
             tmp_path = None
         finally:
             if tmp_path is not None: