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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: muxplex-deck
-Version: 0.5.3
+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.3 → muxplex_deck-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "muxplex-deck"
-version = "0.5.3"
+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.3 → 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.3 → 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.
 
@@ -729,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
@@ -978,8 +1048,6 @@ def _find_uv() -> str | None:
 
 
 def _is_executable(path: str) -> bool:
-    import os
-
     return os.access(path, os.X_OK)
 
 
@@ -1069,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.3 → 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.3 → 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.3 → 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: