trcc-linux 8.3.1__tar.gz → 8.3.3__tar.gz

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trcc-linux
-Version: 8.3.1
+Version: 8.3.3
 Summary: Linux implementation of Thermalright LCD Control Center
 Project-URL: Homepage, https://github.com/Lexonight1/thermalright-trcc-linux
 Project-URL: Documentation, https://github.com/Lexonight1/thermalright-trcc-linux#readme
@@ -74,7 +74,7 @@ Description-Content-Type: text/markdown
 [![Platform](https://img.shields.io/badge/platform-Linux-FCC624?logo=linux&logoColor=black)](https://github.com/Lexonight1/thermalright-trcc-linux)
 
 [![CI](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml/badge.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-4734_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-4802_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/badge/coverage-73%25-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
 [![Code Style](https://img.shields.io/badge/code_style-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
@@ -186,13 +186,13 @@ Pre-built packages are available for every major distro. No pip, no venv, no PEP
 
 **Fedora / openSUSE / Nobara:**
 ```bash
-sudo dnf install https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.1-1.fc43.noarch.rpm
+sudo dnf install https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.3-1.fc43.noarch.rpm
 ```
 
 **Ubuntu 24.04+ / Debian 13+ / Mint 22+ / Pop!_OS 24.04+ / Zorin 17+:**
 ```bash
-curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux_8.3.1-1_all.deb
-sudo dpkg -i trcc-linux_8.3.1-1_all.deb
+curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux_8.3.3-1_all.deb
+sudo dpkg -i trcc-linux_8.3.3-1_all.deb
 sudo apt-get install -f    # pulls in any missing dependencies
 ```
 
@@ -200,8 +200,8 @@ sudo apt-get install -f    # pulls in any missing dependencies
 
 **Arch / CachyOS / Manjaro / EndeavourOS / Garuda:**
 ```bash
-curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.1-1-any.pkg.tar.zst
-sudo pacman -U trcc-linux-8.3.1-1-any.pkg.tar.zst
+curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.3-1-any.pkg.tar.zst
+sudo pacman -U trcc-linux-8.3.3-1-any.pkg.tar.zst
 ```
 
 **NixOS** — add to your `flake.nix` inputs:

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/README.md

@@ -10,7 +10,7 @@
 [![Platform](https://img.shields.io/badge/platform-Linux-FCC624?logo=linux&logoColor=black)](https://github.com/Lexonight1/thermalright-trcc-linux)
 
 [![CI](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml/badge.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-4734_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-4802_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/badge/coverage-73%25-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
 [![Code Style](https://img.shields.io/badge/code_style-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
@@ -122,13 +122,13 @@ Pre-built packages are available for every major distro. No pip, no venv, no PEP
 
 **Fedora / openSUSE / Nobara:**
 ```bash
-sudo dnf install https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.1-1.fc43.noarch.rpm
+sudo dnf install https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.3-1.fc43.noarch.rpm
 ```
 
 **Ubuntu 24.04+ / Debian 13+ / Mint 22+ / Pop!_OS 24.04+ / Zorin 17+:**
 ```bash
-curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux_8.3.1-1_all.deb
-sudo dpkg -i trcc-linux_8.3.1-1_all.deb
+curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux_8.3.3-1_all.deb
+sudo dpkg -i trcc-linux_8.3.3-1_all.deb
 sudo apt-get install -f    # pulls in any missing dependencies
 ```
 
@@ -136,8 +136,8 @@ sudo apt-get install -f    # pulls in any missing dependencies
 
 **Arch / CachyOS / Manjaro / EndeavourOS / Garuda:**
 ```bash
-curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.1-1-any.pkg.tar.zst
-sudo pacman -U trcc-linux-8.3.1-1-any.pkg.tar.zst
+curl -LO https://github.com/Lexonight1/thermalright-trcc-linux/releases/latest/download/trcc-linux-8.3.3-1-any.pkg.tar.zst
+sudo pacman -U trcc-linux-8.3.3-1-any.pkg.tar.zst
 ```
 
 **NixOS** — add to your `flake.nix` inputs:

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trcc-linux"
-version = "8.3.1"
+version = "8.3.3"
 description = "Linux implementation of Thermalright LCD Control Center"
 readme = "README.md"
 license = "GPL-3.0-or-later"

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/src/trcc/__version__.py

@@ -1,4 +1,4 @@
 """TRCC Linux version information. History in doc/CHANGELOG.md."""
 
-__version__ = "8.3.1"
+__version__ = "8.3.3"
 __version_info__ = tuple(int(x) for x in __version__.split("."))

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/src/trcc/api/__init__.py

@@ -250,9 +250,10 @@ def mount_static_dirs(width: int, height: int) -> None:
              width, height, theme_dir, web_dir, masks_dir)
 
 
-# ── Token auth middleware (optional, enabled via --token) ─────────────
+# ── Token auth + pairing ──────────────────────────────────────────────
 
 _api_token: str | None = None
+_pairing_code: str | None = None  # Ephemeral 6-char code, shown in terminal
 
 
 def configure_auth(token: str | None) -> None:
@@ -261,10 +262,20 @@ def configure_auth(token: str | None) -> None:
     _api_token = token
 
 
+def set_pairing_code(code: str) -> None:
+    """Set the ephemeral pairing code (displayed in terminal)."""
+    global _pairing_code  # noqa: PLW0603
+    _pairing_code = code
+
+
+# Paths exempt from token auth — pairing needs to work before the phone has a token
+_AUTH_EXEMPT = {"/health", "/pair"}
+
+
 @app.middleware("http")
 async def check_token(request: Request, call_next):
     """Reject requests without valid token (if token is configured)."""
-    if _api_token and request.url.path != "/health":
+    if _api_token and request.url.path not in _AUTH_EXEMPT:
         header_token = request.headers.get("X-API-Token", "")
         if not hmac.compare_digest(header_token, _api_token):
             return JSONResponse(status_code=401, content={"detail": "Invalid token"})
@@ -279,6 +290,37 @@ def health() -> dict:
     return {"status": "ok", "version": __version__}
 
 
+# ── Pairing endpoint (no auth required) ───────────────────────────────
+
+@app.post("/pair")
+def pair_device(code: str):
+    """Pair a remote device using the 6-char code shown in the terminal.
+
+    Returns the persistent API token on success. The remote app stores
+    this token and uses it for all future requests (X-API-Token header).
+    No re-pairing needed after server restart.
+    """
+    if not _pairing_code:
+        return JSONResponse(
+            status_code=503,
+            content={"detail": "Pairing not available (server started with --token)"},
+        )
+
+    if not hmac.compare_digest(code.upper(), _pairing_code.upper()):
+        log.warning("Pairing attempt with wrong code")
+        return JSONResponse(
+            status_code=403, content={"detail": "Invalid pairing code"},
+        )
+
+    if not _api_token:
+        return JSONResponse(
+            status_code=500, content={"detail": "No API token configured"},
+        )
+
+    log.info("Remote device paired successfully")
+    return {"success": True, "token": _api_token}
+
+
 # ── Register routers ──────────────────────────────────────────────────
 
 from trcc.api.devices import router as devices_router  # noqa: E402

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/src/trcc/api/devices.py

@@ -83,22 +83,22 @@ def select_device(device_id: int) -> dict:
     api.stop_video_playback()
     api.stop_overlay_loop()
 
-    # Check if GUI daemon is running — if so, route through IPC
-    from trcc.ipc import IPCClient
+    # Check if another instance (GUI) already owns the device
+    from trcc.core.instance import find_active
+    from trcc.ipc import create_lcd_proxy, create_led_proxy
 
-    if IPCClient.available():
-        from trcc.ipc import IPCDisplayProxy, IPCLEDProxy
+    active = find_active()
 
-        api._display_dispatcher = IPCDisplayProxy()
-        api._led_dispatcher = IPCLEDProxy()
+    if active is not None:
+        api._display_dispatcher = create_lcd_proxy(active)
+        api._led_dispatcher = create_led_proxy(active)
 
-        # Daemon already discovered resolution — sync it to DeviceInfo
-        # so static dirs mount correctly and response has real resolution
+        # Active instance already discovered resolution — sync to DeviceInfo
         proxy_res = api._display_dispatcher.resolution
         if proxy_res != (0, 0):
             dev.resolution = proxy_res
 
-        log.info("Using GUI daemon for device %s", dev.name)
+        log.info("Using %s instance for device %s", active.value, dev.name)
     else:
         # Standalone mode — API manages device directly
         _device_svc.on_frame_sent = api.set_current_image
@@ -121,6 +121,11 @@ def select_device(device_id: int) -> dict:
             api._display_dispatcher = lcd
 
             w_res, h_res = dev.resolution or (320, 320)
+
+            # Download/extract theme data for this resolution (no-op if cached)
+            from trcc.adapters.infra.data_repository import DataManager
+            DataManager.ensure_all(w_res, h_res)
+
             api.set_current_image(ImageService.solid_color(0, 0, 0, w_res, h_res))
 
             lcd.restore_device_settings()

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/src/trcc/api/themes.py

@@ -44,6 +44,21 @@ def _preview_url(theme_name: str, theme_dir: str) -> str:
     return ""
 
 
+@router.post("/init")
+def init_theme_data(resolution: str = "320x320") -> dict:
+    """Download and extract theme/web/mask archives for a resolution.
+
+    Safe to call repeatedly — no-op if data is already cached.
+    Designed for remote apps to call on startup before listing themes.
+    """
+    w, h = _parse_resolution(resolution)
+
+    from trcc.adapters.infra.data_repository import DataManager
+    DataManager.ensure_all(w, h)
+
+    return {"success": True, "resolution": f"{w}x{h}"}
+
+
 @router.get("")
 def list_themes(resolution: str = "320x320") -> list[ThemeResponse]:
     """List available local themes for a given resolution."""
@@ -51,7 +66,8 @@ def list_themes(resolution: str = "320x320") -> list[ThemeResponse]:
 
     from pathlib import Path
 
-    from trcc.adapters.infra.data_repository import ThemeDir
+    from trcc.adapters.infra.data_repository import DataManager, ThemeDir
+    DataManager.ensure_themes(w, h)
     td = ThemeDir.for_resolution(w, h)
     theme_dir = Path(str(td))
     themes = ThemeService.discover_local(theme_dir, (w, h))
@@ -73,6 +89,7 @@ def list_web_themes(resolution: str = "320x320") -> list[WebThemeResponse]:
     w, h = _parse_resolution(resolution)
 
     from trcc.adapters.infra.data_repository import DataManager
+    DataManager.ensure_web(w, h)
     web_dir = DataManager.get_web_dir(w, h)
 
     results: list[WebThemeResponse] = []
@@ -163,6 +180,7 @@ def list_masks(resolution: str = "320x320") -> list[MaskResponse]:
     w, h = _parse_resolution(resolution)
 
     from trcc.adapters.infra.data_repository import DataManager
+    DataManager.ensure_web_masks(w, h)
     masks_dir = DataManager.get_web_masks_dir(w, h)
 
     results: list[MaskResponse] = []
@@ -188,23 +206,70 @@ def list_masks(resolution: str = "320x320") -> list[MaskResponse]:
 def load_theme(body: ThemeLoadRequest) -> dict:
     """Load a theme by name and send to device.
 
-    Thin adapter — routes through LCDDevice.load_theme_by_name().
+    Full pipeline matching GUI/CLI behavior:
+    1. Stop any running video/overlay
+    2. load_theme_by_name() → select + send + persist
+    3. Start video playback for animated themes
+    4. Start overlay loop for themes with config1.dc
+    5. Update preview image for WebSocket stream
+
     Works in both standalone and IPC (GUI daemon) modes.
+    In IPC mode, the GUI daemon handles the full pipeline.
     """
-    from trcc.api import _display_dispatcher, stop_overlay_loop, stop_video_playback
+    import trcc.api as api
     from trcc.api.models import dispatch_result
 
-    if not _display_dispatcher or not _display_dispatcher.connected:
+    if not api._display_dispatcher or not api._display_dispatcher.connected:
         raise HTTPException(status_code=409, detail="No LCD device selected. POST /devices/{id}/select first.")
 
-    stop_video_playback()
-    stop_overlay_loop()
+    api.stop_video_playback()
+    api.stop_overlay_loop()
 
     w, h = 0, 0
     if body.resolution:
         w, h = _parse_resolution(body.resolution)
 
-    result = _display_dispatcher.load_theme_by_name(body.name, w, h)
+    result = api._display_dispatcher.load_theme_by_name(body.name, w, h)
+    if not result.get("success"):
+        return dispatch_result(result)
+
+    # Update preview image for WebSocket stream
+    image = result.get("image")
+    if image:
+        api.set_current_image(image)
+
+    # Standalone mode — start video/overlay loops (GUI handles its own)
+    is_animated = result.get("is_animated", False)
+    theme_path = result.get("theme_path")
+    config_path = result.get("config_path")
+
+    if not w or not h:
+        res = getattr(api._display_dispatcher, 'resolution', None)
+        if res:
+            w, h = res
+        else:
+            w, h = getattr(api._display_dispatcher, 'lcd_size', (320, 320))
+
+    if is_animated and theme_path:
+        # Find video file (Theme.zt or .mp4)
+        from pathlib import Path
+        theme_dir = Path(str(theme_path))
+        video_path = None
+        for ext in ('.zt', '.mp4'):
+            for name in ('Theme', 'theme'):
+                candidate = theme_dir / f"{name}{ext}"
+                if candidate.exists():
+                    video_path = str(candidate)
+                    break
+            if video_path:
+                break
+        if video_path:
+            api.start_video_playback(video_path, w, h, loop=True)
+
+    elif config_path and os.path.isfile(config_path) and image:
+        # Static theme with overlay config — start metrics loop
+        api.start_overlay_loop(image, str(config_path), w, h)
+
     return dispatch_result(result)
 
 

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/src/trcc/cli/__init__.py

@@ -728,10 +728,10 @@ def _cmd_perf(
     _ensure_renderer()
 
     if device:
-        from trcc.ipc import IPCClient
+        from trcc.core.instance import InstanceKind, find_active
         from trcc.services.perf import run_device_benchmarks
 
-        gui_running = IPCClient.available()
+        gui_running = find_active() == InstanceKind.GUI
         if gui_running:
             print("GUI daemon detected — pausing display refresh...")
         print("Running device I/O benchmarks (this takes ~10s)...")
@@ -836,9 +836,27 @@ def _cmd_serve(
     )] = None,
 ) -> int:
     """Start REST API server."""
-    import uvicorn  # noqa: I001
+    import secrets  # noqa: I001
+    import string
+
+    import uvicorn
+
+    from trcc.api import app as api_app, configure_auth, set_pairing_code  # noqa: I001
+    from trcc.conf import Settings
+
+    # Token resolution: explicit --token > persistent config > auto-generate
+    pairing_code: Optional[str] = None
+    if token is not None:
+        # Explicit --token: save it, no pairing code needed
+        Settings.save_api_token(token)
+    else:
+        # Use persistent token (generated on first run, reused forever)
+        token = Settings.get_api_token()
+        # Generate ephemeral 6-char pairing code for phone to enter
+        alphabet = string.ascii_uppercase + string.digits
+        pairing_code = ''.join(secrets.choice(alphabet) for _ in range(6))
+        set_pairing_code(pairing_code)
 
-    from trcc.api import app as api_app, configure_auth
     configure_auth(token)
 
     ssl_kwargs: dict = {}
@@ -851,12 +869,18 @@ def _cmd_serve(
         ssl_kwargs = {"ssl_certfile": certs[0], "ssl_keyfile": certs[1]}
 
     # Warn if token travels in plaintext over LAN
-    if token and host != "127.0.0.1" and not ssl_kwargs:
-        print("WARNING: --token without --tls exposes your API key in plaintext on the network.")
+    if host != "127.0.0.1" and not ssl_kwargs:
+        print("WARNING: No --tls — traffic is unencrypted on the network.")
         print("         Add --tls for HTTPS, or use --cert/--key for a custom certificate.")
 
     scheme = "https" if ssl_kwargs else "http"
     print(f"Serving on {scheme}://{host}:{port}")
+
+    if pairing_code:
+        print(f"\n  Pairing code:  {pairing_code}\n")
+        print("  Enter this code in TRCC Remote to pair your phone.")
+        print("  After pairing, the phone stays connected across restarts.\n")
+
     _print_serve_qr(host, port, token, bool(ssl_kwargs))
     uvicorn.run(api_app, host=host, port=port, **ssl_kwargs)
     return 0

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/src/trcc/cli/_display.py

@@ -21,18 +21,22 @@ from trcc.core.models import parse_hex_color as _parse_hex
 def _connect_or_fail(device: str | None = None) -> tuple[LCDDevice, int]:
     """Create device, connect. Returns (device, exit_code).
 
-    When the GUI daemon is running and no explicit device path is given,
-    returns an IPC proxy that routes all commands through the daemon.
+    Composition root: injects instance detection (find_active) and proxy
+    factory so core routes through GUI/API if one is already running.
     """
-    if device is None:
-        from trcc.ipc import IPCClient, IPCDisplayProxy
-        if IPCClient.available():
-            return IPCDisplayProxy(), 0  # type: ignore[return-value]
-    lcd = LCDDevice()
+    from trcc.core.instance import find_active
+    from trcc.ipc import create_lcd_proxy
+
+    lcd = LCDDevice(
+        find_active_fn=find_active,
+        proxy_factory_fn=create_lcd_proxy,
+    )
     result = lcd.connect(device)
     if not result["success"]:
         print(result["error"])
         return lcd, 1
+    if result.get("proxy"):
+        print(f"Routing through {result['proxy'].value} instance")
     return lcd, 0
 
 

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/src/trcc/cli/_led.py

@@ -16,18 +16,23 @@ from trcc.core.models import parse_hex_color as _parse_hex
 def _connect_or_fail() -> tuple[LEDDevice, int]:
     """Create device, connect. Returns (device, exit_code).
 
-    When the GUI daemon is running, returns an IPC proxy that routes
-    all commands through the daemon.
+    Composition root: injects instance detection (find_active) and proxy
+    factory so core routes through GUI/API if one is already running.
     """
-    from trcc.ipc import IPCClient, IPCLEDProxy
-    if IPCClient.available():
-        return IPCLEDProxy(), 0  # type: ignore[return-value]
-    led = LEDDevice()
+    from trcc.core.instance import find_active
+    from trcc.ipc import create_led_proxy
+
+    led = LEDDevice(
+        find_active_fn=find_active,
+        proxy_factory_fn=create_led_proxy,
+    )
     result = led.connect()
     if not result["success"]:
         print("No LED device found.")
         return led, 1
-    if result.get("status"):
+    if result.get("proxy"):
+        print(f"Routing through {result['proxy'].value} instance")
+    elif result.get("status"):
         print(result["status"])
     return led, 0
 

{trcc_linux-8.3.1 → trcc_linux-8.3.3}/src/trcc/conf.py

@@ -366,6 +366,32 @@ class Settings:
         config.pop("installed_resolutions", None)
         save_config(config)
 
+    @staticmethod
+    def get_api_token() -> str:
+        """Get persistent API token, generating one on first call.
+
+        Stored in config.json so it survives restarts — phone pairs once,
+        stays trusted forever.
+        """
+        import secrets
+        import string
+
+        config = load_config()
+        token = config.get('api_token')
+        if not token:
+            alphabet = string.ascii_letters + string.digits
+            token = ''.join(secrets.choice(alphabet) for _ in range(16))
+            config['api_token'] = token
+            save_config(config)
+        return token
+
+    @staticmethod
+    def save_api_token(token: str) -> None:
+        """Save an explicit API token (from --token flag)."""
+        config = load_config()
+        config['api_token'] = token
+        save_config(config)
+
     # --- Instance methods and properties ---
 
     def __init__(self) -> None:

trcc_linux-8.3.3/src/trcc/core/instance.py

@@ -0,0 +1,78 @@
+"""Unified instance detection — which trcc process owns the device?
+
+Pure core module: no adapter imports, no framework deps.
+Any adapter (GUI, CLI, API) calls find_active() before touching USB.
+
+Priority: GUI > API > direct.
+"""
+from __future__ import annotations
+
+import enum
+import logging
+import os
+import socket
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+# Default API port — single source of truth (used by CLI serve and detection)
+DEFAULT_API_PORT = 9876
+
+# IPC socket name — matches ipc.py
+_SOCK_NAME = "trcc-linux.sock"
+
+
+class InstanceKind(enum.Enum):
+    """Which type of trcc instance is running."""
+    GUI = "gui"
+    API = "api"
+
+
+def _socket_path() -> Path:
+    return Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / _SOCK_NAME
+
+
+def _gui_running() -> bool:
+    """Check if GUI daemon is listening on IPC socket."""
+    path = _socket_path()
+    if not path.exists():
+        return False
+    try:
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(1.0)
+        s.connect(str(path))
+        s.close()
+        return True
+    except OSError:
+        return False
+
+
+def _api_running(port: int = DEFAULT_API_PORT) -> bool:
+    """Check if API server responds on localhost."""
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(1.0)
+        s.connect(("127.0.0.1", port))
+        # Send minimal HTTP GET /health
+        s.sendall(b"GET /health HTTP/1.0\r\nHost: 127.0.0.1\r\n\r\n")
+        data = s.recv(512)
+        s.close()
+        return b"200" in data and b"trcc" in data.lower()
+    except OSError:
+        return False
+
+
+def find_active(port: int = DEFAULT_API_PORT) -> InstanceKind | None:
+    """Detect which trcc instance (if any) currently owns the device.
+
+    Check order: GUI (IPC socket) > API (HTTP health) > None.
+    Returns None when no other instance is running — caller should
+    take device ownership directly.
+    """
+    if _gui_running():
+        log.info("Detected running GUI daemon (IPC socket)")
+        return InstanceKind.GUI
+    if _api_running(port):
+        log.info("Detected running API server (port %d)", port)
+        return InstanceKind.API
+    return None