fix(stremio_mcp): report ADB failures as actionable, redacted categories

AGENTS.md

@@ -28,6 +28,7 @@ Run commands from the repository root with Python 3.10+ and `uv` installed.
 - Library reads return typed outcomes (`LibraryRead`/`LibraryListRead`/`MetaRead`) that separate an authoritative not-found from an error. Mutations must fail closed: abort without writing on any read error, `_id` mismatch, duplicate row, unrequested extra row, or type mismatch. Never infer "absent" from a failed read.
 - Native `adb` is the transport boundary. Modern Android Wireless Debugging uses TLS (`STLS`), which the former `adb-shell` dependency did not support; do not replace native ADB with a client that lacks this protocol.
 - Wireless Debugging exposes separate, often ephemeral pairing and connection ports. Never assume the pairing port is the runtime port or that modern devices use legacy port `5555`.
+- On macOS, Local Network permission applies to the `adb` binary. The supported pattern is for a permitted GUI terminal to start the shared ADB server, while MCP and other tools use it as localhost clients; automated tooling must not run `adb kill-server` or `adb start-server` or otherwise manage that server lifecycle.
 - A series deep link requires both season and episode; movies and series use different Stremio URI forms. Preserve this distinction and cover dispatch or URI changes with mocked tests.
 - Playback parsing must remain scoped to Stremio's media-session block because other Android sessions can overwrite state. Preserve support for numeric and named states, monotonic position extrapolation, and extractor-based duration fallback in mocked tests.
 - `dist/`, `.venv/`, and Python cache files are generated outputs; do not edit them directly or include them in source changes.

CHANGELOG.md

@@ -14,6 +14,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Changed
 
+- ADB failures now retain bounded categories such as unreachable, ambiguous network, unauthorized, offline, timeout, and transport failure through the controller and tool responses. User-facing guidance and routine logs omit device endpoints, raw ADB output, credentials, URLs, and command payloads. Failed device operations invalidate stale connection state, connection retries are serialized and bounded, and volume changes no longer report success when the shell command fails.
+- macOS ADB troubleshooting now identifies `adb` as the Local Network-permission binary, documents starting the shared server from a permitted GUI terminal for localhost clients, and forbids automated ADB server lifecycle management.
 - All HTTP work now runs on one lifecycle-managed async `httpx` client with explicit connect, read, write, and pool timeouts, a bounded response body, a bounded connection pool, and cancellation support. Previously TMDB requests were synchronous with no timeout and blocked the whole MCP event loop, freezing unrelated device controls.
 - Automatic searches resolve external IDs concurrently under a bounded semaphore instead of issuing up to ten serial requests.
 - Network bounds are configurable through `STREMIO_MCP_*` environment variables; an unparsable or out-of-range value is reported by variable name, without its value, and replaced with the default.

README.md

@@ -222,8 +222,13 @@ adb devices -l
 - Use the current connection port, not the pairing port.
 - Accept the authorization prompt on the TV.
 - If pairing is stale, forget the computer on the TV and pair again.
-- Restart ADB with `adb kill-server && adb start-server`.
-- On macOS, allow the terminal or MCP host under **Privacy & Security → Local Network**.
+- On macOS, grant **Local Network** permission under **Privacy & Security → Local
+  Network** to the `adb` binary itself. A reliable pattern is to start the ADB
+  server once from a permitted GUI terminal, then let the MCP server and other
+  tools act as localhost clients of that existing server.
+- Do not run `adb kill-server` or `adb start-server` from automated tooling: that
+  can discard a permitted server and recreate it under a process without the
+  required macOS permission.
 
 ### Stremio opens but content does not play
 
@@ -277,6 +282,7 @@ See [CONTRIBUTING.md](https://github.com/netixc/stremio-mcp/blob/main/CONTRIBUTI
 
 - Treat `STREMIO_AUTH_KEY` like a password; it permits library reads and writes.
 - Network failures are logged and returned as a category, host, and status code only. Configured credentials and secret-bearing query strings are stripped from every log record and every error the server returns, including tracebacks and third-party HTTP request logs.
+- ADB failures are logged and returned as a bounded category with guidance only, such as unreachable, unauthorized, offline, or timeout; device endpoints, raw ADB output, and command payloads are never logged or returned.
 - Treat ADB authorization as device-control access and protect `~/.android/adbkey`.
 - Never post `.env`, MCP client configuration, auth keys, device IPs, or ADB keys in issues or logs.
 - Review account and device mutations before approving them in your MCP client.