Merge pull request 'Milestone 127: recommendation quality — provenance, tiered mixes, For You v2, tuning lab' (#107 ) from dev into main

test(web/tuning): marker summary appears in tooltips too — use getAllByText
The knob-turn summary renders both as the sparkline tick tooltips (one per series) and in the list under the chart; the single-element query tripped on the duplicates in CI run 1906. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TsF3cNoKrqCYsU78cXC8U6
2026-07-03 10:13:49 -04:00 · 2026-07-03 09:35:51 -04:00 · 2026-07-03 09:29:33 -04:00 · 2026-07-03 09:22:03 -04:00 · 2026-07-03 09:02:35 -04:00 · 2026-07-03 08:54:20 -04:00
300 changed files with 19445 additions and 2828 deletions
@@ -2,8 +2,8 @@ name: release

 # Builds and pushes the minstrel container image to the Gitea registry.
 #
-#   push to main             → :main and :latest (no APK bundled)
-#   push tag vYYYY.MM.DD     → :vYYYY.MM.DD and :latest (APK bundled)
+#   push to main             → :main and :latest (latest-release APK bundled)
+#   push tag vYYYY.MM.DD     → :vYYYY.MM.DD and :latest (freshly-built APK bundled)
 #   workflow_dispatch        → manual trigger (same rules based on the ref)
 #
 # Release model: per-day CalVer tags (no trailing patch digit). The day's
@@ -20,6 +20,14 @@ name: release
 # happens in the same android-release job, so the Release-page download
 # link and the in-image bundled APK are both populated atomically.
 #
+# :latest always carries an APK. Because every main push also moves
+# :latest (not just tags), a main build with no APK would silently strip
+# the in-app update channel off :latest until the next release. So on
+# non-tag builds image-release pulls the MOST RECENT release's signed APK
+# and reconstructs its exact versionName (tag + commit-count, the same
+# formula android-release bakes in) for the version sidecar — no rebuild,
+# just rebundle. Tag builds keep bundling their own freshly-built APK.
+#
 # Android testing (lint + detekt + unit tests, debug APK upload on main)
 # lives in android.yml and runs independently on every push.

@@ -181,6 +189,12 @@ jobs:
    steps:
      - name: Checkout
        uses: actions/checkout@v4
+        with:
+          # Full history + tags so non-tag :latest builds can resolve the
+          # latest release tag's commit count and reconstruct the bundled
+          # APK's exact versionName (see "Bundle latest release APK" below).
+          fetch-depth: 0
+          fetch-tags: true

      - name: Detect buildable project
        id: guard
@@ -221,9 +235,8 @@ jobs:
            | docker login git.fabledsword.com -u "${{ github.actor }}" --password-stdin

      - name: Download signed APK artifact
-        # Tag pushes only — android-release just produced this. Main
-        # pushes skip and the image ships with empty client/ (the
-        # /api/client/version endpoint then returns 404 by design).
+        # Tag pushes only — android-release just produced this. Non-tag
+        # builds take the "Bundle latest release APK" path below instead.
        if: steps.guard.outputs.ready == 'true' && startsWith(github.ref, 'refs/tags/v')
        uses: actions/download-artifact@v3
        with:
@@ -247,6 +260,42 @@ jobs:
          echo "${APK_VERSION_NAME}" > client/minstrel.apk.version
          ls -lh client/

+      - name: Bundle latest release APK (non-tag :latest builds)
+        # Main pushes don't build an APK, but they DO move :latest — so
+        # without this the in-app update channel would vanish from :latest
+        # until the next tag. Pull the most-recent release's signed APK and
+        # reconstruct its exact versionName (${TAG#v}.$(git rev-list --count
+        # TAG) — identical to android-release's formula) so the version
+        # sidecar the server hands clients matches the installed build.
+        # Degrades to an empty client/ (404 update channel) — never a wrong
+        # version — if no release / APK asset / tag-count can be resolved.
+        if: steps.guard.outputs.ready == 'true' && !startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        env:
+          CI_TOKEN: ${{ secrets.CI_TOKEN }}
+        run: |
+          set -eu
+          REPO="${GITHUB_REPOSITORY}"
+          REL_JSON="$(curl -fsSL -H "Authorization: token ${CI_TOKEN}" \
+            "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/latest" || true)"
+          if [ -z "${REL_JSON}" ]; then
+            echo "::notice::no published release — image ships without bundled APK"; exit 0
+          fi
+          TAG="$(printf '%s' "${REL_JSON}" | grep -oP '"tag_name":\s*"\K[^"]+' | head -1)"
+          APK_URL="$(printf '%s' "${REL_JSON}" | grep -oP '"browser_download_url":\s*"\K[^"]+' | grep -E '\.apk$' | head -1)"
+          if [ -z "${TAG}" ] || [ -z "${APK_URL}" ]; then
+            echo "::notice::latest release '${TAG:-?}' has no APK asset — image ships without bundled APK"; exit 0
+          fi
+          COUNT="$(git rev-list --count "${TAG}" 2>/dev/null || true)"
+          if [ -z "${COUNT}" ]; then
+            echo "::notice::could not resolve commit count for ${TAG} (tag not fetched?) — skipping APK bundle"; exit 0
+          fi
+          VERSION_NAME="${TAG#v}.${COUNT}"
+          curl -fsSL -H "Authorization: token ${CI_TOKEN}" -o client/minstrel.apk "${APK_URL}"
+          echo "${VERSION_NAME}" > client/minstrel.apk.version
+          echo "::notice::bundled release APK ${TAG} as version ${VERSION_NAME}"
+          ls -lh client/
+
      - name: Build and push
        if: steps.guard.outputs.ready == 'true'
        run: |
@@ -116,6 +116,27 @@ jobs:
          # Wait for Postgres to accept TCP (no health-check dependency).
          for i in $(seq 1 60); do (echo > "/dev/tcp/${PG_IP}/5432") 2>/dev/null && break; sleep 2; done

+          # Relax durability on the throwaway CI Postgres. Our test pattern
+          # is dbtest.ResetDB → TRUNCATE … RESTART IDENTITY CASCADE before
+          # every test, and the per-TRUNCATE commit fsync is the dominant
+          # cost of the integration suite. The CI DB is rebuilt every run so
+          # fsync / full_page_writes / synchronous_commit buy nothing. Apply
+          # via docker exec because:
+          #  - The act_runner `services:` block can't override the container
+          #    command, so `postgres -c fsync=off` at boot isn't an option.
+          #  - ALTER SYSTEM cannot run inside a transaction; psql -c
+          #    auto-commits each statement, which is what we need.
+          #  - fsync / full_page_writes are sighup GUCs and
+          #    synchronous_commit is user-context, so pg_reload_conf() picks
+          #    all three up with no restart.
+          # Non-fatal: a perms surprise degrades to "slower", never red CI.
+          docker exec "$PG_ID" psql -U minstrel -d minstrel_test \
+            -c "ALTER SYSTEM SET fsync = off" \
+            -c "ALTER SYSTEM SET synchronous_commit = off" \
+            -c "ALTER SYSTEM SET full_page_writes = off" \
+            -c "SELECT pg_reload_conf()" \
+            || echo "WARN: durability relax failed; continuing"
+
          # Apply embedded migrations to the fresh test DB, then run the
          # full suite (no -short → integration tests execute). -p 1:
          # every integration package TRUNCATEs the one shared test DB;
@@ -4,7 +4,7 @@ A self-hosted music server that thinks for you. Smart shuffle, contextual likes,

 > State and intelligence belong on the server, not the client.

-<!-- TODO: screenshot of the home page -->
+<a href="docs/screenshots/home.png"><img src="docs/screenshots/home.png" width="820" alt="Minstrel home — your library at a glance"></a>

 ## Highlights

@@ -13,7 +13,7 @@ A self-hosted music server that thinks for you. Smart shuffle, contextual likes,
 - **ListenBrainz radio.** Session-aware "more like this" pulls from ListenBrainz similarity data, not a static genre tag.
 - **Lidarr integration.** Triggered scans, request-driven album imports, and a quarantine flow when something doesn't fit.
 - **Built-in web SPA.** Full-feature library, search, queue, playlists, and admin — no separate frontend container to deploy.
- **Flutter mobile client in flight.** Tracking issue [#356](https://git.fabledsword.com/bvandeusen/minstrel/issues/356).
+- **Native Android client, shipped with the server.** The signed APK is bundled into every image and attached to each [release](https://git.fabledsword.com/bvandeusen/minstrel/releases) — sideload it once, then the app self-updates straight from your own server (no app store, no separate download to track).

 ## Quickstart

@@ -24,10 +24,18 @@ services:
    image: git.fabledsword.com/bvandeusen/minstrel:latest
    ports: ['4533:4533']
    volumes:
+      # Your music library. Point ./music at wherever your audio files
+      # live. Mounted read-only — Minstrel never writes to your library.
      - ./music:/music:ro
-      - minstrel-data:/data
+      # Generated data: playlist cover collages, artist art, caches.
+      # The path must match MINSTREL_STORAGE_DATA_DIR, which the image
+      # sets to /app/data — keep this mount on /app/data or your cache
+      # won't survive a container recreate.
+      - minstrel-data:/app/data
    environment:
      MINSTREL_DATABASE_URL: postgres://minstrel:minstrel@db:5432/minstrel?sslmode=disable
+      # Colon-separated library roots to scan; must match the container
+      # path of the read-only music mount above (/music here).
      MINSTREL_LIBRARY_SCAN_PATHS: /music
    depends_on: [db]

@@ -37,6 +45,8 @@ services:
      POSTGRES_USER: minstrel
      POSTGRES_PASSWORD: minstrel
      POSTGRES_DB: minstrel
+    # Postgres data dir — users, likes, play history, sessions, settings.
+    # The one volume you must never lose; back it up with pg_dump.
    volumes: [pgdata:/var/lib/postgresql/data]

 volumes:
@@ -48,7 +58,29 @@ volumes:
 docker compose up -d
 ```

-After the stack is up, visit `http://localhost:4533/register` and create your admin account. The first user to register on a fresh instance is automatically marked as the administrator; subsequent users can register through the same form (or via invite tokens generated from the admin Users panel, depending on how you configure registration).
+## First run
+
+With the stack up, a handful of in-app steps get you to a working library. Use your own host in place of `localhost` if you're reaching the server over a LAN/VPN address (plain `http://` is fine — no TLS required).
+
+**1. Create your admin account.** Visit `http://localhost:4533/register`. The first account on a fresh instance is automatically the administrator; later users join through the same form or an invite token (step 5).
+
+<a href="docs/screenshots/register.png"><img src="docs/screenshots/register.png" width="320" alt="Creating the first (admin) account on a fresh instance"></a>
+
+**2. Let the first library scan finish.** `scan_on_startup` is on by default, so Minstrel walks your mounted library on boot and imports artists, albums, and tracks — no button to press. Watch progress (and re-scan any time) on the **Admin** page (`/admin`); the scan runs in stages and is incremental, so later restarts only pick up what changed.
+
+<a href="docs/screenshots/library-scan.png"><img src="docs/screenshots/library-scan.png" width="820" alt="The Admin page, where the library scan runs and reports progress"></a>
+
+**3. (Optional) Name the instance and wire up integrations.** In admin **Settings → Integrations** (`/admin/integrations`), add a ListenBrainz token (scrobbling + similarity radio) and/or a Lidarr URL + API key (the request flow). These live in the UI and apply without a restart; the display name can also be set via `MINSTREL_BRANDING_APP_NAME`.
+
+<a href="docs/screenshots/integrations.png"><img src="docs/screenshots/integrations.png" width="820" alt="ListenBrainz and Lidarr integration cards in admin Settings"></a>
+
+**4. Install the Android app.** Open **Settings** (`/settings`) and use the *Install the Android app* card to download the APK that ships inside this server image, then sign in with the same account. From then on the app self-updates straight from your server.
+
+<a href="docs/screenshots/android-download.png"><img src="docs/screenshots/android-download.png" width="820" alt="The &quot;Install the Android app&quot; download card in Settings"></a>
+
+**5. Invite the rest of the household.** From admin **Users** (`/admin/users`), generate an invite token (or enable open registration). Each person gets their own account, so likes, play history, and recommendations stay per-user.
+
+<a href="docs/screenshots/invite-users.png"><img src="docs/screenshots/invite-users.png" width="820" alt="Generating an invite token in admin Users"></a>

 For the full configuration surface, see [`config.example.yaml`](./config.example.yaml).

@@ -57,7 +89,7 @@ For the full configuration surface, see [`config.example.yaml`](./config.example
 Most operators only need the env vars in the quickstart above. A few extras worth knowing:

 - `MINSTREL_BRANDING_APP_NAME` — rename the instance ("Family Jukebox", "Office Music"). Surfaces in the header, browser tab, and OG share previews.
- `MINSTREL_STORAGE_DATA_DIR` — defaults to `./data`. Holds playlist cover collages and other generated artefacts.
+- `MINSTREL_STORAGE_DATA_DIR` — where generated artefacts (playlist cover collages, artist art, caches) are written. The container image sets this to `/app/data`, which is why the quickstart mounts the `minstrel-data` volume there.
 - `MINSTREL_LIBRARY_SCAN_PATHS` — colon-separated list of music library roots to scan. Supports multiple roots (`/music:/podcasts`).

 ListenBrainz integration (per-user scrobble + similarity tokens) and Lidarr integration (URL + API key) are configured through the admin Settings UI rather than env vars or yaml — per Minstrel's "config in UI" rule, integration settings live where operators can edit them without restarting.
@@ -66,8 +98,13 @@ Most operational keys have a `MINSTREL_<SECTION>_<FIELD>` env override. Recommen

 ## Updating

- `:main` — rolling, follows the dev branch's tested tip. Recommended only for the operator who's running an upstream-watching deployment.
- `:v1.0.x` — pinned releases. Recommended default. Database migrations run automatically at startup; rollbacks require restoring a Postgres dump.
+Image tags (`git.fabledsword.com/bvandeusen/minstrel:<tag>`):
+
+- `:latest` — the newest blessed image. Moves on every `main` push **and** every release. Recommended for most operators.
+- `:vYYYY.MM.DD` — immutable per-day release tags. Pin one of these for a deployment you don't want moving under you. (Per-day CalVer — no trailing patch digit; a same-day re-cut moves the tag forward.)
+- `:main` — the rolling post-merge tip. Same image as `:latest` at push time; choose it if you want to track `main` explicitly rather than the release line.
+
+Every `:latest` and every `:vYYYY.MM.DD` bundles the current signed Android APK, so the in-app update channel is always live. Database migrations run automatically at startup; rollbacks require restoring a Postgres dump.

 ## Specs

@@ -1754,6 +1754,19 @@
          <option name="screenX" value="1600" />
          <option name="screenY" value="2560" />
        </PersistentDeviceSelectionData>
+        <PersistentDeviceSelectionData>
+          <option name="api" value="36" />
+          <option name="brand" value="google" />
+          <option name="codename" value="tangorpro" />
+          <option name="formFactor" value="Tablet" />
+          <option name="id" value="tangorpro" />
+          <option name="labId" value="google" />
+          <option name="manufacturer" value="Google" />
+          <option name="name" value="Pixel Tablet" />
+          <option name="screenDensity" value="320" />
+          <option name="screenX" value="1600" />
+          <option name="screenY" value="2560" />
+        </PersistentDeviceSelectionData>
        <PersistentDeviceSelectionData>
          <option name="api" value="35" />
          <option name="brand" value="google" />
@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="ExternalStorageConfigurationManager" enabled="true" />
  <component name="ProjectRootManager" version="2" languageLevel="JDK_21" default="true" project-jdk-name="jbr-21" project-jdk-type="JavaSDK">
@@ -0,0 +1,690 @@
+{
+  "formatVersion": 1,
+  "database": {
+    "version": 6,
+    "identityHash": "fb73ed8674efb1d82a586551baba5ef0",
+    "entities": [
+      {
+        "tableName": "sync_metadata",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER NOT NULL, `cursor` INTEGER NOT NULL, `lastSyncAt` INTEGER, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "cursor",
+            "columnName": "cursor",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "lastSyncAt",
+            "columnName": "lastSyncAt",
+            "affinity": "INTEGER"
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_artists",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` TEXT NOT NULL, `name` TEXT NOT NULL, `sortName` TEXT NOT NULL, `mbid` TEXT, `artistThumbPath` TEXT, `artistFanartPath` TEXT, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "name",
+            "columnName": "name",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "sortName",
+            "columnName": "sortName",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "mbid",
+            "columnName": "mbid",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "artistThumbPath",
+            "columnName": "artistThumbPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "artistFanartPath",
+            "columnName": "artistFanartPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_albums",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` TEXT NOT NULL, `artistId` TEXT NOT NULL, `title` TEXT NOT NULL, `sortTitle` TEXT NOT NULL, `releaseDate` TEXT, `coverPath` TEXT, `mbid` TEXT, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "artistId",
+            "columnName": "artistId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "title",
+            "columnName": "title",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "sortTitle",
+            "columnName": "sortTitle",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "releaseDate",
+            "columnName": "releaseDate",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "coverPath",
+            "columnName": "coverPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "mbid",
+            "columnName": "mbid",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_tracks",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` TEXT NOT NULL, `albumId` TEXT NOT NULL, `artistId` TEXT NOT NULL, `title` TEXT NOT NULL, `durationMs` INTEGER NOT NULL, `trackNumber` INTEGER, `discNumber` INTEGER, `filePath` TEXT, `fileFormat` TEXT, `genre` TEXT, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "albumId",
+            "columnName": "albumId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "artistId",
+            "columnName": "artistId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "title",
+            "columnName": "title",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "durationMs",
+            "columnName": "durationMs",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "trackNumber",
+            "columnName": "trackNumber",
+            "affinity": "INTEGER"
+          },
+          {
+            "fieldPath": "discNumber",
+            "columnName": "discNumber",
+            "affinity": "INTEGER"
+          },
+          {
+            "fieldPath": "filePath",
+            "columnName": "filePath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fileFormat",
+            "columnName": "fileFormat",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "genre",
+            "columnName": "genre",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_likes",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`userId` TEXT NOT NULL, `entityType` TEXT NOT NULL, `entityId` TEXT NOT NULL, `likedAt` INTEGER NOT NULL, PRIMARY KEY(`userId`, `entityType`, `entityId`))",
+        "fields": [
+          {
+            "fieldPath": "userId",
+            "columnName": "userId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "entityType",
+            "columnName": "entityType",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "entityId",
+            "columnName": "entityId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "likedAt",
+            "columnName": "likedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "userId",
+            "entityType",
+            "entityId"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_playlists",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` TEXT NOT NULL, `userId` TEXT NOT NULL, `name` TEXT NOT NULL, `description` TEXT NOT NULL, `isPublic` INTEGER NOT NULL, `coverPath` TEXT, `trackCount` INTEGER NOT NULL, `durationSec` INTEGER NOT NULL, `systemVariant` TEXT, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "userId",
+            "columnName": "userId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "name",
+            "columnName": "name",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "description",
+            "columnName": "description",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "isPublic",
+            "columnName": "isPublic",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "coverPath",
+            "columnName": "coverPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "trackCount",
+            "columnName": "trackCount",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "durationSec",
+            "columnName": "durationSec",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "systemVariant",
+            "columnName": "systemVariant",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_playlist_tracks",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`playlistId` TEXT NOT NULL, `trackId` TEXT NOT NULL, `position` INTEGER NOT NULL, PRIMARY KEY(`playlistId`, `trackId`))",
+        "fields": [
+          {
+            "fieldPath": "playlistId",
+            "columnName": "playlistId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "trackId",
+            "columnName": "trackId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "position",
+            "columnName": "position",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "playlistId",
+            "trackId"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_quarantine_mine",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`trackId` TEXT NOT NULL, `reason` TEXT NOT NULL, `notes` TEXT, `createdAt` TEXT NOT NULL, `trackTitle` TEXT NOT NULL, `trackDurationMs` INTEGER NOT NULL, `albumId` TEXT NOT NULL, `albumTitle` TEXT NOT NULL, `albumCoverArtPath` TEXT, `artistId` TEXT NOT NULL, `artistName` TEXT NOT NULL, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`trackId`))",
+        "fields": [
+          {
+            "fieldPath": "trackId",
+            "columnName": "trackId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "reason",
+            "columnName": "reason",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "notes",
+            "columnName": "notes",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "createdAt",
+            "columnName": "createdAt",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "trackTitle",
+            "columnName": "trackTitle",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "trackDurationMs",
+            "columnName": "trackDurationMs",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "albumId",
+            "columnName": "albumId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "albumTitle",
+            "columnName": "albumTitle",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "albumCoverArtPath",
+            "columnName": "albumCoverArtPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "artistId",
+            "columnName": "artistId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "artistName",
+            "columnName": "artistName",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "trackId"
+          ]
+        }
+      },
+      {
+        "tableName": "audio_cache_index",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`trackId` TEXT NOT NULL, `path` TEXT NOT NULL, `sizeBytes` INTEGER NOT NULL, `cachedAt` INTEGER NOT NULL, `lastPlayedAt` INTEGER, `source` TEXT NOT NULL, PRIMARY KEY(`trackId`))",
+        "fields": [
+          {
+            "fieldPath": "trackId",
+            "columnName": "trackId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "path",
+            "columnName": "path",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "sizeBytes",
+            "columnName": "sizeBytes",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "cachedAt",
+            "columnName": "cachedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "lastPlayedAt",
+            "columnName": "lastPlayedAt",
+            "affinity": "INTEGER"
+          },
+          {
+            "fieldPath": "source",
+            "columnName": "source",
+            "affinity": "TEXT",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "trackId"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_mutations",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, `kind` TEXT NOT NULL, `payload` TEXT NOT NULL, `createdAt` INTEGER NOT NULL, `lastAttemptAt` INTEGER, `attempts` INTEGER NOT NULL)",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "kind",
+            "columnName": "kind",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "payload",
+            "columnName": "payload",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "createdAt",
+            "columnName": "createdAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "lastAttemptAt",
+            "columnName": "lastAttemptAt",
+            "affinity": "INTEGER"
+          },
+          {
+            "fieldPath": "attempts",
+            "columnName": "attempts",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": true,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_resume_state",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER NOT NULL, `json` TEXT NOT NULL, `updatedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "json",
+            "columnName": "json",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "updatedAt",
+            "columnName": "updatedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_home_index",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`section` TEXT NOT NULL, `position` INTEGER NOT NULL, `entityType` TEXT NOT NULL, `entityId` TEXT NOT NULL, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`section`, `position`))",
+        "fields": [
+          {
+            "fieldPath": "section",
+            "columnName": "section",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "position",
+            "columnName": "position",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "entityType",
+            "columnName": "entityType",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "entityId",
+            "columnName": "entityId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "section",
+            "position"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_history_snapshot",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER NOT NULL, `json` TEXT NOT NULL, `updatedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "json",
+            "columnName": "json",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "updatedAt",
+            "columnName": "updatedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "auth_session",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER NOT NULL, `sessionCookie` TEXT, `baseUrl` TEXT NOT NULL, `userJson` TEXT, `themeMode` TEXT, `clientId` TEXT, `cacheSettingsJson` TEXT, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "sessionCookie",
+            "columnName": "sessionCookie",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "baseUrl",
+            "columnName": "baseUrl",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "userJson",
+            "columnName": "userJson",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "themeMode",
+            "columnName": "themeMode",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "clientId",
+            "columnName": "clientId",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "cacheSettingsJson",
+            "columnName": "cacheSettingsJson",
+            "affinity": "TEXT"
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      }
+    ],
+    "setupQueries": [
+      "CREATE TABLE IF NOT EXISTS room_master_table (id INTEGER PRIMARY KEY,identity_hash TEXT)",
+      "INSERT OR REPLACE INTO room_master_table (id,identity_hash) VALUES(42, 'fb73ed8674efb1d82a586551baba5ef0')"
+    ]
+  }
+}
@@ -21,6 +21,9 @@ import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.navigation.compose.rememberNavController
 import com.fabledsword.minstrel.auth.ui.AuthGateViewModel
 import com.fabledsword.minstrel.cache.CachedTrackIds
+import com.fabledsword.minstrel.connectivity.LocalServerHealth
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.nav.DetailSeedCache
 import com.fabledsword.minstrel.nav.LocalDetailSeedCache
 import com.fabledsword.minstrel.nav.MinstrelNavGraph
@@ -38,6 +41,7 @@ import javax.inject.Inject
 class MainActivity : ComponentActivity() {
    @Inject lateinit var seedCache: DetailSeedCache
    @Inject lateinit var cachedTrackIds: CachedTrackIds
+    @Inject lateinit var serverHealth: NetworkStatusController

    // Flipped to true when the user taps the media notification (or
    // any other entry point that asks for the full player). The App
@@ -54,6 +58,7 @@ class MainActivity : ComponentActivity() {
            App(
                seedCache = seedCache,
                cachedTrackIds = cachedTrackIds,
+                serverHealth = serverHealth,
                pendingOpenNowPlaying = pendingOpenNowPlaying.asStateFlow(),
                onOpenedNowPlaying = { pendingOpenNowPlaying.value = false },
            )
@@ -86,6 +91,7 @@ class MainActivity : ComponentActivity() {
 private fun App(
    seedCache: DetailSeedCache,
    cachedTrackIds: CachedTrackIds,
+    serverHealth: NetworkStatusController,
    pendingOpenNowPlaying: StateFlow<Boolean>,
    onOpenedNowPlaying: () -> Unit,
    themeVm: ThemePreferenceViewModel = hiltViewModel(),
@@ -93,11 +99,13 @@ private fun App(
 ) {
    val theme by themeVm.themeMode.collectAsStateWithLifecycle()
    val cached by cachedTrackIds.ids.collectAsStateWithLifecycle()
+    val health: ServerHealth by serverHealth.state.collectAsStateWithLifecycle()
    val pending by pendingOpenNowPlaying.collectAsStateWithLifecycle()
    MinstrelTheme(darkOverride = theme.toDarkOverride()) {
        CompositionLocalProvider(
            LocalDetailSeedCache provides seedCache,
            LocalCachedTrackIds provides cached,
+            LocalServerHealth provides health,
        ) {
            val startDestination by gate.startDestination.collectAsStateWithLifecycle()
            val resolved = startDestination
@@ -10,6 +10,8 @@ import com.fabledsword.minstrel.cache.CacheIndexer
 import com.fabledsword.minstrel.cache.mutations.MutationReplayer
 import com.fabledsword.minstrel.cache.sync.SyncController
 import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.diagnostics.DiagnosticsReporter
+import com.fabledsword.minstrel.diagnostics.DiagnosticsUploader
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.events.LiveEventsDispatcher
 import com.fabledsword.minstrel.metadata.FreshnessSweeper
@@ -19,7 +21,7 @@ import com.fabledsword.minstrel.player.PlayEventsReporter
 import com.fabledsword.minstrel.player.PlaybackErrorReporter
 import com.fabledsword.minstrel.player.ResumeController
 import com.fabledsword.minstrel.update.data.UpdateBannerController
-import com.fabledsword.minstrel.update.data.VersionCheckController
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import dagger.hilt.android.HiltAndroidApp
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.launch
@@ -114,12 +116,13 @@ class MinstrelApplication :
    @Suppress("unused") @Inject lateinit var audioPrefetcher: AudioPrefetcher

    /**
-     * Same construct-the-singleton trick — VersionCheckController's
-     * init block starts a 5-min poll loop against /healthz so the
-     * shell-level VersionTooOldBanner can surface min_client_version
-     * mismatches without waiting for the next user-driven request.
+     * Same construct-the-singleton trick — NetworkStatusController owns the
+     * /healthz poll loop + the device-link collector + the reachability state
+     * machine, and is the single authority on the tri-state ServerHealth
+     * signal (plus the VersionTooOld byproduct). It must exist from launch so
+     * the poll loop runs and the StateFlow stays warm for every consumer.
     */
-    @Suppress("unused") @Inject lateinit var versionCheckController: VersionCheckController
+    @Suppress("unused") @Inject lateinit var networkStatusController: NetworkStatusController

    /**
     * Same construct-the-singleton trick — UpdateBannerController polls
@@ -154,6 +157,11 @@ class MinstrelApplication :
     */
    @Suppress("unused") @Inject lateinit var liveEventsDispatcher: LiveEventsDispatcher

+    // Device diagnostics (M9). The reporter gates itself on the account's
+    // debug flag; the uploader drains its buffer on a tick / recovery.
+    @Suppress("unused") @Inject lateinit var diagnosticsReporter: DiagnosticsReporter
+    @Suppress("unused") @Inject lateinit var diagnosticsUploader: DiagnosticsUploader
+
    @Inject @ApplicationScope lateinit var appScope: CoroutineScope

    override fun onCreate() {
@@ -4,6 +4,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.admin.data.AdminInvitesRepository
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.models.Invite
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.channels.Channel
@@ -25,6 +27,7 @@ data class AdminInvitesUiState(
@HiltViewModel
 class AdminInvitesViewModel @Inject constructor(
    private val repository: AdminInvitesRepository,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

    private val internal = MutableStateFlow(AdminInvitesUiState())
@@ -36,6 +39,13 @@ class AdminInvitesViewModel @Inject constructor(

    init {
        refresh()
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value.message != null) refresh()
+            }
+        }
    }

    fun refresh() {
@@ -29,6 +29,7 @@ import androidx.navigation.NavHostController
 import com.fabledsword.minstrel.models.AdminQuarantineItemRef
 import com.fabledsword.minstrel.nav.AdminQuarantine
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -62,9 +63,10 @@ fun AdminQuarantineScreen(
                    body = "When users flag tracks as bad rips, wrong tags, or " +
                        "duplicates, their reports get aggregated and surfaced here.",
                )
-                is AdminQuarantineUiState.Error -> EmptyState(
+                is AdminQuarantineUiState.Error -> ErrorRetry(
                    title = "Couldn't load queue",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                )
                is AdminQuarantineUiState.Success -> QueueList(
                    rows = s.rows,
@@ -4,6 +4,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.admin.data.AdminQuarantineRepository
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.AdminQuarantineItemRef
 import dagger.hilt.android.lifecycle.HiltViewModel
@@ -26,6 +28,7 @@ sealed interface AdminQuarantineUiState {
 class AdminQuarantineViewModel @Inject constructor(
    private val repository: AdminQuarantineRepository,
    private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

    private val internal = MutableStateFlow<AdminQuarantineUiState>(AdminQuarantineUiState.Loading)
@@ -38,6 +41,13 @@ class AdminQuarantineViewModel @Inject constructor(
                .filter { it.kind.startsWith("quarantine.") }
                .collect { refresh() }
        }
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AdminQuarantineUiState.Error) refresh()
+            }
+        }
    }

    fun refresh(): Job = viewModelScope.launch {
@@ -28,6 +28,7 @@ import androidx.navigation.NavHostController
 import com.fabledsword.minstrel.models.RequestRef
 import com.fabledsword.minstrel.nav.AdminRequests
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -61,9 +62,10 @@ fun AdminRequestsScreen(
                    body = "When users ask Lidarr for new music, their pending " +
                        "requests show up here for approval.",
                )
-                is AdminRequestsUiState.Error -> EmptyState(
+                is AdminRequestsUiState.Error -> ErrorRetry(
                    title = "Couldn't load requests",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                )
                is AdminRequestsUiState.Success -> RequestList(
                    rows = s.rows,
@@ -5,6 +5,8 @@ import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.admin.data.AdminRequestsRepository
 import com.fabledsword.minstrel.admin.data.AdminUsersRepository
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.RequestRef
 import dagger.hilt.android.lifecycle.HiltViewModel
@@ -35,6 +37,7 @@ class AdminRequestsViewModel @Inject constructor(
    private val repository: AdminRequestsRepository,
    private val usersRepository: AdminUsersRepository,
    private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

    private val internal = MutableStateFlow<AdminRequestsUiState>(AdminRequestsUiState.Loading)
@@ -47,6 +50,13 @@ class AdminRequestsViewModel @Inject constructor(
                .filter { it.kind in RELEVANT_EVENT_KINDS }
                .collect { refresh() }
        }
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AdminRequestsUiState.Error) refresh()
+            }
+        }
    }

    fun refresh(): Job = viewModelScope.launch {
@@ -4,6 +4,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.admin.data.AdminUsersRepository
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.models.AdminUserRef
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
@@ -23,6 +25,7 @@ sealed interface AdminUsersUiState {
@HiltViewModel
 class AdminUsersViewModel @Inject constructor(
    private val repository: AdminUsersRepository,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

    private val internal = MutableStateFlow<AdminUsersUiState>(AdminUsersUiState.Loading)
@@ -30,6 +33,13 @@ class AdminUsersViewModel @Inject constructor(

    init {
        refresh()
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AdminUsersUiState.Error) refresh()
+            }
+        }
    }

    fun refresh(): Job = viewModelScope.launch {
@@ -1,6 +1,7 @@
 package com.fabledsword.minstrel.api

 import com.fabledsword.minstrel.BuildConfig
+import com.fabledsword.minstrel.connectivity.ReachabilityReportingInterceptor
 import com.jakewharton.retrofit2.converter.kotlinx.serialization.asConverterFactory
 import dagger.Module
 import dagger.Provides
@@ -45,9 +46,15 @@ object NetworkModule {
    fun provideOkHttp(
        baseUrl: BaseUrlInterceptor,
        auth: AuthCookieInterceptor,
+        reachability: ReachabilityReportingInterceptor,
        logging: HttpLoggingInterceptor,
    ): OkHttpClient =
        OkHttpClient.Builder()
+            // ReachabilityReportingInterceptor MUST run first: it identifies
+            // Minstrel-bound requests by the still-unrewritten PLACEHOLDER_HOST
+            // (so external artwork fetches don't read as server reachability)
+            // and observes the final transport outcome by wrapping the chain.
+            .addInterceptor(reachability)
            // AuthCookieInterceptor MUST run before BaseUrlInterceptor.
            // Both scope on `host == PLACEHOLDER_HOST` to distinguish
            // Minstrel-server requests from external image fetches
@@ -39,11 +39,18 @@ data class StreamTokenRequest(
 /**
 * Response body. [url] is a fully-formed stream URL with [token] and
 * [exp] already embedded as query params — callers pass it verbatim
- * to `AVTransport.SetAVTransportURI`.
+ * to `AVTransport.SetAVTransportURI`. [mime] + [title] are the bits
+ * the client needs to build DIDL-Lite metadata for that call: Sonos
+ * rejects empty DIDL with vendor error 1023, so the server hands back
+ * the track's MIME (from `tracks.file_format`) and title so the
+ * client can populate `<res protocolInfo>` and `<dc:title>` without
+ * a follow-up round trip.
 */
@Serializable
 data class StreamTokenResponse(
    val token: String,
    val exp: Long,
    val url: String,
+    val mime: String = "audio/mpeg",
+    val title: String = "",
 )
@@ -0,0 +1,36 @@
+package com.fabledsword.minstrel.api.endpoints
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+import retrofit2.http.Body
+import retrofit2.http.POST
+
+/**
+ * Retrofit interface for device diagnostics ingest (M9). One call
+ * uploads a batch of buffered events. The server stores them only when
+ * the account's debug_mode_enabled flag is on (it returns 204 otherwise,
+ * which the uploader treats as success so it can drop the batch).
+ */
+interface DiagnosticsApi {
+    @POST("api/diagnostics")
+    suspend fun report(@Body body: DiagnosticsReportRequest)
+}
+
+@Serializable
+data class DiagnosticsReportRequest(
+    @SerialName("client_id") val clientId: String,
+    @SerialName("app_version") val appVersion: String? = null,
+    @SerialName("os_version") val osVersion: String? = null,
+    val events: List<DiagnosticEventWire>,
+)
+
+@Serializable
+data class DiagnosticEventWire(
+    val kind: String,
+    // Device-clock epoch milliseconds. The server stamps its own
+    // received_at; both are stored so a skewed device clock is visible.
+    @SerialName("occurred_at") val occurredAt: Long,
+    // Opaque structured payload carrying the event sub-type + fields.
+    val payload: JsonElement,
+)
@@ -2,6 +2,7 @@ package com.fabledsword.minstrel.api.endpoints

 import com.fabledsword.minstrel.models.wire.AlbumDetailWire
 import com.fabledsword.minstrel.models.wire.ArtistDetailWire
+import com.fabledsword.minstrel.models.wire.ArtistWire
 import com.fabledsword.minstrel.models.wire.TrackWire
 import retrofit2.http.GET
 import retrofit2.http.Path
@@ -35,9 +36,26 @@ interface LibraryApi {
    @GET("api/artists/{id}/tracks")
    suspend fun getArtistTracks(@Path("id") id: String): List<TrackWire>

+    @GET("api/artists/{id}/similar")
+    suspend fun getSimilarArtists(
+        @Path("id") id: String,
+        @Query("limit") limit: Int = SIMILAR_ARTISTS_LIMIT,
+    ): List<ArtistWire>
+
+    @GET("api/artists/{id}/top-tracks")
+    suspend fun getArtistTopTracks(
+        @Path("id") id: String,
+        @Query("limit") limit: Int = TOP_TRACKS_LIMIT,
+    ): List<TrackWire>
+
    @GET("api/albums/{id}")
    suspend fun getAlbumDetail(@Path("id") id: String): AlbumDetailWire

    @GET("api/library/shuffle")
    suspend fun shuffleLibrary(@Query("limit") limit: Int = 100): List<TrackWire>
+
+    private companion object {
+        const val SIMILAR_ARTISTS_LIMIT = 12
+        const val TOP_TRACKS_LIMIT = 5
+    }
 }
@@ -1,6 +1,7 @@
 package com.fabledsword.minstrel.auth

 import com.fabledsword.minstrel.api.endpoints.AuthApi
+import com.fabledsword.minstrel.api.endpoints.MeApi
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.models.UserRef
 import com.fabledsword.minstrel.models.wire.LoginRequestBody
@@ -35,6 +36,7 @@ class AuthController @Inject constructor(
    retrofit: Retrofit,
 ) {
    private val api: AuthApi = retrofit.create()
+    private val meApi: MeApi = retrofit.create()

    private val currentUserState = MutableStateFlow<UserRef?>(null)
    val currentUser: StateFlow<UserRef?> = currentUserState.asStateFlow()
@@ -55,6 +57,10 @@ class AuthController @Inject constructor(
                currentUserState.value = raw?.let { decodeUser(it) }
            }
        }
+        // Refresh from /api/me on startup so a remotely-changed account
+        // flag (e.g. admin enabling debug mode, M9) reaches the device
+        // without a re-login. Best-effort; failures keep the cached value.
+        scope.launch { refreshProfile() }
    }

    /**
@@ -72,9 +78,32 @@ class AuthController @Inject constructor(
        )
        currentUserState.value = user
        authStore.setUserJson(json.encodeToString(UserRef.serializer(), user))
+        // Pull the fuller /me shape (carries debug_mode_enabled) right
+        // after login so the diagnostics gate is correct without waiting
+        // for the next startup refresh.
+        scope.launch { refreshProfile() }
        return user
    }

+    /**
+     * Re-fetch the caller's profile from /api/me and update currentUser
+     * + persisted userJson. Carries account-level flags (debug mode)
+     * that aren't in the login response. Best-effort: a network failure
+     * leaves the cached identity untouched. No-op when signed out.
+     */
+    suspend fun refreshProfile() {
+        if (!isSignedIn) return
+        val p = runCatching { meApi.getProfile() }.getOrNull() ?: return
+        val user = UserRef(
+            id = p.id,
+            username = p.username,
+            isAdmin = p.isAdmin,
+            debugModeEnabled = p.debugModeEnabled,
+        )
+        currentUserState.value = user
+        authStore.setUserJson(json.encodeToString(UserRef.serializer(), user))
+    }
+
    /**
     * Clears the local session immediately and best-effort hits
     * `/api/auth/logout` so the server can drop its session row.
@@ -59,6 +59,9 @@ class AuthStore @Inject constructor(
    private val cacheSettingsState = MutableStateFlow(CacheSettings.DEFAULT)
    val cacheSettings: StateFlow<CacheSettings> = cacheSettingsState.asStateFlow()

+    private val diagnosticsOptOutState = MutableStateFlow(false)
+    val diagnosticsOptOut: StateFlow<Boolean> = diagnosticsOptOutState.asStateFlow()
+
    private val json = Json { ignoreUnknownKeys = true }

    init {
@@ -70,6 +73,7 @@ class AuthStore @Inject constructor(
                themeModeState.value = row?.themeMode
                clientIdState.value = row?.clientId
                cacheSettingsState.value = decodeCacheSettings(row?.cacheSettingsJson)
+                diagnosticsOptOutState.value = row?.diagnosticsOptOut ?: false
            }
        }
    }
@@ -112,6 +116,11 @@ class AuthStore @Inject constructor(
        scope.launch { persistCacheSettings(encoded) }
    }

+    fun setDiagnosticsOptOut(value: Boolean) {
+        diagnosticsOptOutState.value = value
+        scope.launch { persistDiagnosticsOptOut(value) }
+    }
+
    private suspend fun persistCookie(value: String?) {
        if (dao.get() == null) {
            dao.upsert(currentEntity().copy(sessionCookie = value))
@@ -160,6 +169,14 @@ class AuthStore @Inject constructor(
        }
    }

+    private suspend fun persistDiagnosticsOptOut(value: Boolean) {
+        if (dao.get() == null) {
+            dao.upsert(currentEntity().copy(diagnosticsOptOut = value))
+        } else {
+            dao.setDiagnosticsOptOut(value)
+        }
+    }
+
    private fun currentEntity(): AuthSessionEntity = AuthSessionEntity(
        id = ROW_ID,
        sessionCookie = sessionCookieState.value,
@@ -171,6 +188,7 @@ class AuthStore @Inject constructor(
            CacheSettings.serializer(),
            cacheSettingsState.value,
        ),
+        diagnosticsOptOut = diagnosticsOptOutState.value,
    )

    companion object {
@@ -16,6 +16,7 @@ import com.fabledsword.minstrel.cache.db.dao.CachedResumeStateDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistTrackDao
 import com.fabledsword.minstrel.cache.db.dao.CachedQuarantineDao
 import com.fabledsword.minstrel.cache.db.dao.CachedTrackDao
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
 import com.fabledsword.minstrel.cache.db.dao.SyncMetadataDao
 import com.fabledsword.minstrel.cache.db.entities.AudioCacheIndexEntity
 import com.fabledsword.minstrel.cache.db.entities.AuthSessionEntity
@@ -30,6 +31,7 @@ import com.fabledsword.minstrel.cache.db.entities.CachedResumeStateEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistTrackEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedQuarantineEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedTrackEntity
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
 import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity

 /**
@@ -61,8 +63,11 @@ import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
        CachedHomeIndexEntity::class,
        CachedHistorySnapshotEntity::class,
        AuthSessionEntity::class,
+        DiagnosticEventEntity::class,
    ],
-    version = 6,
+    // v7: + diagnostic_events table (M9) and the diagnosticsOptOut column
+    // on auth_session. Pre-v1 destructive fallback rebuilds on mismatch.
+    version = 7,
    exportSchema = true,
 )
@TypeConverters(MinstrelTypeConverters::class)
@@ -81,4 +86,5 @@ abstract class AppDatabase : RoomDatabase() {
    abstract fun cachedHomeIndexDao(): CachedHomeIndexDao
    abstract fun cachedHistorySnapshotDao(): CachedHistorySnapshotDao
    abstract fun authSessionDao(): AuthSessionDao
+    abstract fun diagnosticEventDao(): DiagnosticEventDao
 }
@@ -10,6 +10,7 @@ import com.fabledsword.minstrel.cache.db.dao.CachedHistorySnapshotDao
 import com.fabledsword.minstrel.cache.db.dao.CachedHomeIndexDao
 import com.fabledsword.minstrel.cache.db.dao.CachedLikeDao
 import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistTrackDao
 import com.fabledsword.minstrel.cache.db.dao.CachedQuarantineDao
@@ -105,5 +106,10 @@ object DatabaseModule {
    fun provideAudioCacheIndexDao(db: AppDatabase): AudioCacheIndexDao =
        db.audioCacheIndexDao()

+    @Provides
+    @Singleton
+    fun provideDiagnosticEventDao(db: AppDatabase): DiagnosticEventDao =
+        db.diagnosticEventDao()
+
    private const val DATABASE_NAME = "minstrel.db"
 }
@@ -42,4 +42,8 @@ interface AuthSessionDao {
    /** Partial update: change only the serialized cache settings. */
    @Query("UPDATE auth_session SET cacheSettingsJson = :json WHERE id = 0")
    suspend fun setCacheSettingsJson(json: String?)
+
+    /** Partial update: change only the per-device diagnostics opt-out. */
+    @Query("UPDATE auth_session SET diagnosticsOptOut = :optOut WHERE id = 0")
+    suspend fun setDiagnosticsOptOut(optOut: Boolean)
 }
@@ -24,6 +24,14 @@ interface CachedAlbumDao {
    @Query("SELECT * FROM cached_albums WHERE id = :id")
    fun observeById(id: String): Flow<CachedAlbumEntity?>

+    @Query(
+        "SELECT * FROM cached_albums " +
+            "WHERE title LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "ORDER BY sortTitle COLLATE NOCASE ASC " +
+            "LIMIT :limit",
+    )
+    suspend fun searchByTitle(q: String, limit: Int): List<CachedAlbumEntity>
+
    @Query("SELECT id FROM cached_albums WHERE fetchedAt < :before LIMIT :limit")
    suspend fun idsStaleBefore(before: Long, limit: Int): List<String>

@@ -18,6 +18,14 @@ interface CachedArtistDao {
    @Query("SELECT * FROM cached_artists WHERE id = :id")
    fun observeById(id: String): Flow<CachedArtistEntity?>

+    @Query(
+        "SELECT * FROM cached_artists " +
+            "WHERE name LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "ORDER BY sortName COLLATE NOCASE ASC " +
+            "LIMIT :limit",
+    )
+    suspend fun searchByName(q: String, limit: Int): List<CachedArtistEntity>
+
    @Query("SELECT id FROM cached_artists WHERE fetchedAt < :before LIMIT :limit")
    suspend fun idsStaleBefore(before: Long, limit: Int): List<String>

@@ -31,6 +31,20 @@ interface CachedPlaylistDao {
    @Query("SELECT * FROM cached_playlists WHERE id = :id")
    suspend fun getById(id: String): CachedPlaylistEntity?

+    /**
+     * Per-playlist count of member tracks resident in the audio cache index.
+     * LEFT JOINs so playlists with zero cached tracks still appear
+     * (cachedCount = 0). Drives the offline "fully cached" greying.
+     */
+    @Query(
+        "SELECT p.id AS playlistId, COUNT(a.trackId) AS cachedCount " +
+            "FROM cached_playlists p " +
+            "LEFT JOIN cached_playlist_tracks t ON t.playlistId = p.id " +
+            "LEFT JOIN audio_cache_index a ON a.trackId = t.trackId " +
+            "GROUP BY p.id",
+    )
+    fun observeCachedCounts(): Flow<List<PlaylistCachedCount>>
+
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun upsertAll(rows: List<CachedPlaylistEntity>)

@@ -24,6 +24,14 @@ interface CachedTrackDao {
    @Query("SELECT * FROM cached_tracks WHERE id IN (:ids)")
    suspend fun getByIds(ids: List<String>): List<CachedTrackEntity>

+    @Query(
+        "SELECT * FROM cached_tracks " +
+            "WHERE title LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "ORDER BY title COLLATE NOCASE ASC " +
+            "LIMIT :limit",
+    )
+    suspend fun searchByTitle(q: String, limit: Int): List<CachedTrackEntity>
+
    @Query("SELECT id FROM cached_tracks WHERE fetchedAt < :before LIMIT :limit")
    suspend fun idsStaleBefore(before: Long, limit: Int): List<String>

@@ -0,0 +1,35 @@
+package com.fabledsword.minstrel.cache.db.dao
+
+import androidx.room.Dao
+import androidx.room.Insert
+import androidx.room.Query
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
+
+@Dao
+interface DiagnosticEventDao {
+    @Insert
+    suspend fun insert(row: DiagnosticEventEntity): Long
+
+    /** FIFO drain order so the uploader sends oldest-first. */
+    @Query("SELECT * FROM diagnostic_events ORDER BY id ASC LIMIT :limit")
+    suspend fun takeBatch(limit: Int): List<DiagnosticEventEntity>
+
+    @Query("SELECT COUNT(*) FROM diagnostic_events")
+    suspend fun count(): Int
+
+    @Query("DELETE FROM diagnostic_events WHERE id IN (:ids)")
+    suspend fun deleteByIds(ids: List<Long>)
+
+    /**
+     * Ring-buffer trim: drop the oldest rows beyond [keep]. Called after
+     * insert so a long offline stretch can't grow the buffer unbounded.
+     */
+    @Query(
+        "DELETE FROM diagnostic_events WHERE id NOT IN " +
+            "(SELECT id FROM diagnostic_events ORDER BY id DESC LIMIT :keep)",
+    )
+    suspend fun trimToNewest(keep: Int)
+
+    @Query("DELETE FROM diagnostic_events")
+    suspend fun clear()
+}
@@ -0,0 +1,11 @@
+package com.fabledsword.minstrel.cache.db.dao
+
+/**
+ * Projection: how many of a playlist's member tracks are resident in the audio
+ * cache index. Backs the offline "fully cached" greying — a playlist is fully
+ * available offline when [cachedCount] reaches its `trackCount`.
+ */
+data class PlaylistCachedCount(
+    val playlistId: String,
+    val cachedCount: Int,
+)
@@ -36,4 +36,11 @@ data class AuthSessionEntity(
     * CacheSettings shape evolves.
     */
    val cacheSettingsJson: String? = null,
+    /**
+     * Per-device opt-out of diagnostics reporting (M9). When the
+     * account's debug mode is enabled by an admin, the user can still
+     * turn reporting OFF on this device (battery/privacy) — that local
+     * choice lives here. Default false = honor the account flag.
+     */
+    val diagnosticsOptOut: Boolean = false,
 )
@@ -14,6 +14,11 @@ import kotlinx.datetime.Instant
 *   - "rediscover_artists"
 *   - "most_played_tracks"
 *   - "last_played_artists"
+ *   - "you_might_like_albums"
+ *   - "you_might_like_artists"
+ *
+ * New `section` values need no schema change — the column stores the
+ * string verbatim and the DAO keys on it.
 *
 * `entityType` is "album" | "artist" | "track" — dispatches hydration
 * to the right per-entity endpoint when a tile is rendered.
@@ -0,0 +1,28 @@
+package com.fabledsword.minstrel.cache.db.entities
+
+import androidx.room.Entity
+import androidx.room.PrimaryKey
+
+/**
+ * One buffered device-diagnostics event (M9). The DiagnosticsReporter
+ * writes rows here when the account's debug mode is on; the
+ * DiagnosticsUploader drains them to POST /api/diagnostics and deletes
+ * on success.
+ *
+ * This is a deliberate ring buffer that is NOT routed through the offline
+ * MutationQueue: diagnostics are high-volume, best-effort telemetry, and
+ * the bug we're chasing (roaming / dead-zone recovery) happens WHILE
+ * offline — so events must persist locally through the dead zone and
+ * upload on recovery, without clogging the user-data mutation replay.
+ *
+ * `occurredAtMillis` is the device-clock epoch-ms when the event happened
+ * (the server also stamps its own received_at). `payloadJson` is an
+ * opaque JSON object carrying the event sub-type + fields.
+ */
+@Entity(tableName = "diagnostic_events")
+data class DiagnosticEventEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val kind: String,
+    val occurredAtMillis: Long,
+    val payloadJson: String,
+)
@@ -2,12 +2,18 @@ package com.fabledsword.minstrel.cache.mutations

 import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
 import com.fabledsword.minstrel.cache.db.entities.CachedMutationEntity
+import kotlinx.coroutines.channels.BufferOverflow
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.SharedFlow
+import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
 import javax.inject.Inject
 import javax.inject.Singleton

+private const val QUEUED_MESSAGE = "Saved — will sync when online"
+
 /**
 * Stable mutation kinds the queue knows how to replay. Strings are
 * persisted in `cached_mutations.kind` so renaming a variant breaks
@@ -22,6 +28,13 @@ object MutationKind {
    const val PLAY_OFFLINE: String = "play_offline"
    const val REQUEST_CANCEL: String = "request_cancel"
    const val PLAYBACK_ERROR_REPORT: String = "playback_error_report"
+
+    // Durable close-by-id for a play whose server row is already open
+    // (play_started succeeded). Distinct from PLAY_OFFLINE, which records
+    // a *whole* play when no server row exists. Using close-by-id on
+    // background avoids the duplicate + orphan row the old offline-on-stop
+    // path produced (see 2026-06-11 contract audit).
+    const val PLAY_ENDED: String = "play_ended"
 }

 /**
@@ -71,61 +84,79 @@ class MutationQueue @Inject constructor(
    private val dao: CachedMutationDao,
    private val json: Json,
 ) {
+    // capacity=1 DROP_OLDEST so a burst of user enqueues (e.g. liking N
+    // tracks while offline) surfaces as one snackbar rather than queueing
+    // N. replay=0 because a hint observed at enqueue time isn't useful
+    // to a screen that mounts later.
+    private val _userEnqueueHints = MutableSharedFlow<String>(
+        replay = 0,
+        extraBufferCapacity = 1,
+        onBufferOverflow = BufferOverflow.DROP_OLDEST,
+    )
+
+    /**
+     * Hint stream consumed by [com.fabledsword.minstrel.shared.widgets.ShellScaffold]
+     * to surface "Saved — will sync when online" as a snackbar whenever a
+     * user-driven write hits the offline-fallback path. Background-only
+     * enqueues (play-events, playback-error reports) do not emit — those
+     * fire from non-foreground paths where a snackbar would be either
+     * dropped (no shell mounted) or jarring (lock-screen toggle).
+     */
+    val userEnqueueHints: SharedFlow<String> = _userEnqueueHints.asSharedFlow()
+
    suspend fun enqueueLikeToggle(
        entityType: String,
        entityId: String,
        desiredState: Boolean,
-    ): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.LIKE_TOGGLE,
-            payload = json.encodeToString(
+    ): Long = insertUserDriven(
+        MutationKind.LIKE_TOGGLE,
+        json.encodeToString(
            LikeTogglePayload.serializer(),
            LikeTogglePayload(entityType, entityId, desiredState),
        ),
-        ),
    )

-    suspend fun enqueueRequestCreate(payload: RequestCreatePayload): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.REQUEST_CREATE,
-            payload = json.encodeToString(RequestCreatePayload.serializer(), payload),
-        ),
+    suspend fun enqueueRequestCreate(payload: RequestCreatePayload): Long = insertUserDriven(
+        MutationKind.REQUEST_CREATE,
+        json.encodeToString(RequestCreatePayload.serializer(), payload),
    )

-    suspend fun enqueueQuarantineUnflag(trackId: String): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.QUARANTINE_UNFLAG,
-            payload = json.encodeToString(
+    suspend fun enqueueQuarantineUnflag(trackId: String): Long = insertUserDriven(
+        MutationKind.QUARANTINE_UNFLAG,
+        json.encodeToString(
            QuarantineUnflagPayload.serializer(),
            QuarantineUnflagPayload(trackId),
        ),
-        ),
    )

    suspend fun enqueuePlaylistAppend(
        playlistId: String,
        trackIds: List<String>,
-    ): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.PLAYLIST_APPEND,
-            payload = json.encodeToString(
+    ): Long = insertUserDriven(
+        MutationKind.PLAYLIST_APPEND,
+        json.encodeToString(
            PlaylistAppendPayload.serializer(),
            PlaylistAppendPayload(playlistId, trackIds),
        ),
-        ),
    )

    suspend fun enqueueQuarantineFlag(
        trackId: String,
        reason: String,
        notes: String,
-    ): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.QUARANTINE_FLAG,
-            payload = json.encodeToString(
+    ): Long = insertUserDriven(
+        MutationKind.QUARANTINE_FLAG,
+        json.encodeToString(
            QuarantineFlagPayload.serializer(),
            QuarantineFlagPayload(trackId, reason, notes),
        ),
+    )
+
+    suspend fun enqueueRequestCancel(requestId: String): Long = insertUserDriven(
+        MutationKind.REQUEST_CANCEL,
+        json.encodeToString(
+            RequestCancelPayload.serializer(),
+            RequestCancelPayload(requestId),
        ),
    )

@@ -136,22 +167,29 @@ class MutationQueue @Inject constructor(
        ),
    )

-    suspend fun enqueueRequestCancel(requestId: String): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.REQUEST_CANCEL,
-            payload = json.encodeToString(
-                RequestCancelPayload.serializer(),
-                RequestCancelPayload(requestId),
-            ),
-        ),
-    )
-
    suspend fun enqueuePlaybackErrorReport(payload: PlaybackErrorReportPayload): Long = dao.insert(
        CachedMutationEntity(
            kind = MutationKind.PLAYBACK_ERROR_REPORT,
            payload = json.encodeToString(PlaybackErrorReportPayload.serializer(), payload),
        ),
    )
+
+    /**
+     * Durable close-by-id for an already-open server play row. Background
+     * path only (no user hint) — same as [enqueuePlayOffline].
+     */
+    suspend fun enqueuePlayEnded(payload: PlayEndedPayload): Long = dao.insert(
+        CachedMutationEntity(
+            kind = MutationKind.PLAY_ENDED,
+            payload = json.encodeToString(PlayEndedPayload.serializer(), payload),
+        ),
+    )
+
+    private suspend fun insertUserDriven(kind: String, payload: String): Long {
+        val id = dao.insert(CachedMutationEntity(kind = kind, payload = payload))
+        _userEnqueueHints.tryEmit(QUEUED_MESSAGE)
+        return id
+    }
 }

 /**
@@ -203,6 +241,19 @@ data class PlayOfflinePayload(
    val source: String? = null,
 )

+/**
+ * Persisted payload for `MutationKind.PLAY_ENDED`. The replayer re-fires
+ * `POST /api/events` with type=play_ended, closing the already-open server
+ * row [playEventId] at [durationPlayedMs]. Server-side close-by-id is
+ * idempotent (re-ending updates the same row and skips a duplicate
+ * skip_events insert), so a lost-response retry can't duplicate history.
+ */
+@Serializable
+data class PlayEndedPayload(
+    val playEventId: String,
+    val durationPlayedMs: Long,
+)
+
 /**
 * Persisted payload for `MutationKind.REQUEST_CANCEL` — the
 * `POST /api/requests/{id}/cancel` call lost during a connectivity
@@ -1,3 +1,5 @@
+@file:Suppress("TooManyFunctions") // one dispatcher per mutation kind + replay helpers
+
 package com.fabledsword.minstrel.cache.mutations

 import com.fabledsword.minstrel.api.endpoints.AppendTracksRequest
@@ -10,6 +12,9 @@ import com.fabledsword.minstrel.api.endpoints.PlaybackErrorsApi
 import com.fabledsword.minstrel.api.endpoints.PlaylistsApi
 import com.fabledsword.minstrel.api.endpoints.QuarantineApi
 import com.fabledsword.minstrel.api.endpoints.RequestsApi
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.models.wire.PlayEndedRequest
 import com.fabledsword.minstrel.models.wire.PlayOfflineRequest
 import com.fabledsword.minstrel.auth.AuthStore
 import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
@@ -19,12 +24,16 @@ import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.models.wire.CreateRequestBody
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.datetime.Clock
+import kotlinx.serialization.SerializationException
 import kotlinx.serialization.json.Json
+import retrofit2.HttpException
 import retrofit2.Retrofit
 import retrofit2.create
 import javax.inject.Inject
@@ -34,25 +43,24 @@ import javax.inject.Singleton
 * Drains the offline MutationQueue. Reads pending rows in FIFO order,
 * re-fires each call against the raw Retrofit API (NOT the high-level
 * Repository, which would re-enqueue on failure → infinite loop), and
- * deletes the row on 2xx success.
+ * resolves each to an [Outcome]:
+ *  - SENT  — server accepted (2xx) → delete the row.
+ *  - DROP  — permanently un-sendable (4xx, unknown kind/variant, corrupt
+ *            payload) → delete the row so it can't wedge the queue forever.
+ *  - RETRY — transient (transport, 5xx, 408, 429) → leave queued, bump
+ *            attempts, retry on the next trigger.
 *
 * Triggered by:
- *   - app start (MinstrelApplication @Inject forces the singleton's
- *     init block to subscribe)
- *   - every time AuthStore.sessionCookie transitions to a non-null
- *     value (sign-in, app launch with persisted cookie)
+ *   - app start (MinstrelApplication @Inject forces the singleton's init)
+ *   - AuthStore.sessionCookie transitioning to non-null (sign-in / cold
+ *     start with a persisted cookie)
+ *   - NetworkStatusController recovering to Healthy (server reachable again
+ *     mid-session — covers offline→online without needing a cold start)
 *
- * Single in-flight via the `mutex` — back-to-back triggers collapse
- * into one drain pass. A proper connectivity-listener / WorkManager
- * job that re-tries on Wi-Fi-came-back is a follow-up; for MVP the
- * sign-in + app-open triggers cover the common offline → online
- * transition (operator unlocks phone, opens app).
- *
- * Failed rows stay in the queue with their `attempts` and
- * `lastAttemptAt` updated. They get another chance on the next
- * trigger; no exponential backoff or max-attempts yet — the rows are
- * small (low single-digit count for typical use) so retry-forever is
- * cheap.
+ * Single in-flight via the [mutex]; back-to-back triggers collapse into one
+ * drain pass. No exponential backoff / max-attempts: the rows are few for
+ * typical use, and permanent failures are now dropped rather than retried
+ * forever.
 */
@Singleton
 class MutationReplayer @Inject constructor(
@@ -60,6 +68,7 @@ class MutationReplayer @Inject constructor(
    private val authStore: AuthStore,
    private val json: Json,
    @ApplicationScope private val scope: CoroutineScope,
+    networkStatus: NetworkStatusController,
    retrofit: Retrofit,
 ) {
    private val likesApi: LikesApi = retrofit.create()
@@ -72,6 +81,8 @@ class MutationReplayer @Inject constructor(

    private val mutex = Mutex()

+    private enum class Outcome { SENT, DROP, RETRY }
+
    init {
        scope.launch {
            authStore.sessionCookie
@@ -79,6 +90,16 @@ class MutationReplayer @Inject constructor(
                .distinctUntilChanged()
                .collect { drainSafe() }
        }
+        // Server-reachable-again: replay queued writes the moment the
+        // health signal recovers, so an offline→online transition mid-
+        // session doesn't wait for the next cold start / re-auth.
+        scope.launch {
+            networkStatus.state
+                .map { it == ServerHealth.Healthy }
+                .distinctUntilChanged()
+                .filter { it }
+                .collect { drainSafe() }
+        }
    }

    /** Public entry-point; coalesces concurrent triggers via a Mutex. */
@@ -93,69 +114,98 @@ class MutationReplayer @Inject constructor(

    private suspend fun drain() {
        val rows = dao.getAll()
+        // Collapse superseded like-toggles: only the latest desired state per
+        // (entity) is replayed; older toggles for the same entity are dropped
+        // unsent. Without this, partial-failure + differential retry could
+        // replay an older toggle last and invert the final like state.
+        val superseded = supersededLikeToggleIds(rows)
        for (row in rows) {
-            val sent = runCatching { dispatch(row) }.getOrDefault(false)
-            if (sent) {
+            if (row.id in superseded) {
                dao.delete(row.id)
-            } else {
-                dao.recordAttempt(row.id, Clock.System.now())
+                continue
+            }
+            when (outcomeFor(row)) {
+                Outcome.SENT, Outcome.DROP -> dao.delete(row.id)
+                Outcome.RETRY -> dao.recordAttempt(row.id, Clock.System.now())
            }
        }
    }

+    /** Row ids of like-toggles superseded by a later toggle for the same entity. */
+    private fun supersededLikeToggleIds(rows: List<CachedMutationEntity>): Set<Long> {
+        val latestByEntity = HashMap<String, Long>()
+        val superseded = HashSet<Long>()
+        rows.asSequence()
+            .filter { it.kind == MutationKind.LIKE_TOGGLE }
+            .forEach { row ->
+                val decoded = runCatching {
+                    json.decodeFromString(LikeTogglePayload.serializer(), row.payload)
+                }.getOrNull()
+                if (decoded != null) {
+                    val key = "${decoded.entityType}:${decoded.entityId}"
+                    // `rows` is ascending by id, so a prior entry is always older.
+                    latestByEntity.put(key, row.id)?.let(superseded::add)
+                }
+            }
+        return superseded
+    }
+
+    private suspend fun outcomeFor(row: CachedMutationEntity): Outcome = try {
+        dispatch(row)
+    } catch (e: HttpException) {
+        if (isPermanent(e.code())) Outcome.DROP else Outcome.RETRY
+    } catch (@Suppress("SwallowedException") e: SerializationException) {
+        // Corrupt / schema-incompatible payload — permanent, drop it.
+        Outcome.DROP
+    } catch (@Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable) {
+        // Transport / unknown — leave queued for the next pass.
+        Outcome.RETRY
+    }
+
+    /** 4xx are permanent except the two "retry me" statuses. */
+    private fun isPermanent(code: Int): Boolean =
+        code in HTTP_CLIENT_ERR_MIN..HTTP_CLIENT_ERR_MAX &&
+            code != HTTP_TIMEOUT && code != HTTP_TOO_MANY
+
    /**
-     * Returns true if the server accepted the call, false on any
-     * failure (transport, server error, decode). The replayer treats
-     * false as "leave the row for next pass" — it doesn't try to
-     * distinguish permanent rejections from transient ones; a row
-     * that consistently fails will accumulate attempt count and
-     * lastAttemptAt for diagnostics.
+     * Returns the outcome of replaying one row. SENT on a 2xx; DROP for an
+     * unknown kind/variant. Network / HTTP failures THROW and are classified
+     * by [outcomeFor] — dispatchers no longer swallow.
     */
-    private suspend fun dispatch(row: CachedMutationEntity): Boolean = when (row.kind) {
+    private suspend fun dispatch(row: CachedMutationEntity): Outcome = when (row.kind) {
        MutationKind.LIKE_TOGGLE -> dispatchLikeToggle(row.payload)
        MutationKind.REQUEST_CREATE -> dispatchRequestCreate(row.payload)
        MutationKind.QUARANTINE_UNFLAG -> dispatchQuarantineUnflag(row.payload)
        MutationKind.PLAYLIST_APPEND -> dispatchPlaylistAppend(row.payload)
        MutationKind.QUARANTINE_FLAG -> dispatchQuarantineFlag(row.payload)
        MutationKind.PLAY_OFFLINE -> dispatchPlayOffline(row.payload)
+        MutationKind.PLAY_ENDED -> dispatchPlayEnded(row.payload)
        MutationKind.REQUEST_CANCEL -> dispatchRequestCancel(row.payload)
        MutationKind.PLAYBACK_ERROR_REPORT -> dispatchPlaybackErrorReport(row.payload)
-        else -> {
-            // Unknown kind — drop the row by claiming success so a
-            // stale schema entry can't wedge the queue forever.
-            true
-        }
+        // Unknown kind — drop so a stale schema entry can't wedge the queue.
+        else -> Outcome.DROP
    }

-    private suspend fun dispatchLikeToggle(payload: String): Boolean {
+    private suspend fun dispatchLikeToggle(payload: String): Outcome {
        val decoded = json.decodeFromString(LikeTogglePayload.serializer(), payload)
        val kindPath = when (decoded.entityType) {
            LikesRepository.ENTITY_ARTIST -> "artists"
            LikesRepository.ENTITY_ALBUM -> "albums"
            LikesRepository.ENTITY_TRACK -> "tracks"
-            else -> return true  // unknown variant — drop.
+            else -> return Outcome.DROP
        }
-        return try {
        if (decoded.desiredState) {
            likesApi.like(kindPath, decoded.entityId)
        } else {
            likesApi.unlike(kindPath, decoded.entityId)
        }
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: the row stays in the queue with
-            // attempts + lastAttemptAt incremented; next drain pass
-            // retries. Per-attempt diagnostic logging lands when we
-            // wire up Timber at the replayer level.
-            false
-        }
+        return Outcome.SENT
    }

-    private suspend fun dispatchRequestCreate(payload: String): Boolean {
+    private suspend fun dispatchRequestCreate(payload: String): Outcome {
        val decoded = json.decodeFromString(RequestCreatePayload.serializer(), payload)
-        val body = CreateRequestBody(
+        discoverApi.createRequest(
+            CreateRequestBody(
                kind = decoded.kind,
                artistMbid = decoded.artistMbid,
                artistName = decoded.artistName,
@@ -163,56 +213,28 @@ class MutationReplayer @Inject constructor(
                albumTitle = decoded.albumTitle,
                trackMbid = decoded.trackMbid,
                trackTitle = decoded.trackTitle,
+            ),
        )
-        return try {
-            discoverApi.createRequest(body)
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: the row stays in the queue with
-            // attempts + lastAttemptAt incremented; next drain pass
-            // retries. Per-attempt diagnostic logging lands when we
-            // wire up Timber at the replayer level.
-            false
-        }
+        return Outcome.SENT
    }

-    private suspend fun dispatchQuarantineUnflag(payload: String): Boolean {
+    private suspend fun dispatchQuarantineUnflag(payload: String): Outcome {
        val decoded = json.decodeFromString(QuarantineUnflagPayload.serializer(), payload)
-        return try {
        quarantineApi.unflag(decoded.trackId)
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: the row stays in the queue with
-            // attempts + lastAttemptAt incremented; next drain pass
-            // retries. Per-attempt diagnostic logging lands when we
-            // wire up Timber at the replayer level.
-            false
-        }
+        return Outcome.SENT
    }

-    private suspend fun dispatchPlaylistAppend(payload: String): Boolean {
+    private suspend fun dispatchPlaylistAppend(payload: String): Outcome {
        val decoded = json.decodeFromString(PlaylistAppendPayload.serializer(), payload)
-        return try {
        playlistsApi.appendTracks(
            playlistId = decoded.playlistId,
            body = AppendTracksRequest(trackIds = decoded.trackIds),
        )
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
-        }
+        return Outcome.SENT
    }

-    private suspend fun dispatchQuarantineFlag(payload: String): Boolean {
+    private suspend fun dispatchQuarantineFlag(payload: String): Outcome {
        val decoded = json.decodeFromString(QuarantineFlagPayload.serializer(), payload)
-        return try {
        quarantineApi.flag(
            FlagRequest(
                trackId = decoded.trackId,
@@ -220,18 +242,11 @@ class MutationReplayer @Inject constructor(
                notes = decoded.notes,
            ),
        )
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
-        }
+        return Outcome.SENT
    }

-    private suspend fun dispatchPlayOffline(payload: String): Boolean {
+    private suspend fun dispatchPlayOffline(payload: String): Outcome {
        val decoded = json.decodeFromString(PlayOfflinePayload.serializer(), payload)
-        return try {
        eventsApi.playOffline(
            PlayOfflineRequest(
                trackId = decoded.trackId,
@@ -241,31 +256,28 @@ class MutationReplayer @Inject constructor(
                source = decoded.source,
            ),
        )
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
-        }
+        return Outcome.SENT
    }

-    private suspend fun dispatchRequestCancel(payload: String): Boolean {
+    private suspend fun dispatchPlayEnded(payload: String): Outcome {
+        val decoded = json.decodeFromString(PlayEndedPayload.serializer(), payload)
+        eventsApi.playEnded(
+            PlayEndedRequest(
+                playEventId = decoded.playEventId,
+                durationPlayedMs = decoded.durationPlayedMs,
+            ),
+        )
+        return Outcome.SENT
+    }
+
+    private suspend fun dispatchRequestCancel(payload: String): Outcome {
        val decoded = json.decodeFromString(RequestCancelPayload.serializer(), payload)
-        return try {
        requestsApi.cancel(decoded.requestId)
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
-        }
+        return Outcome.SENT
    }

-    private suspend fun dispatchPlaybackErrorReport(payload: String): Boolean {
+    private suspend fun dispatchPlaybackErrorReport(payload: String): Outcome {
        val decoded = json.decodeFromString(PlaybackErrorReportPayload.serializer(), payload)
-        return try {
        playbackErrorsApi.report(
            PlaybackErrorReportRequest(
                trackId = decoded.trackId,
@@ -274,12 +286,13 @@ class MutationReplayer @Inject constructor(
                clientId = decoded.clientId,
            ),
        )
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
+        return Outcome.SENT
    }
+
+    private companion object {
+        const val HTTP_CLIENT_ERR_MIN = 400
+        const val HTTP_CLIENT_ERR_MAX = 499
+        const val HTTP_TIMEOUT = 408
+        const val HTTP_TOO_MANY = 429
    }
 }
@@ -0,0 +1,20 @@
+package com.fabledsword.minstrel.cache.mutations
+
+import androidx.lifecycle.ViewModel
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.Flow
+import javax.inject.Inject
+
+/**
+ * Hilt-injectable wrapper exposing [MutationQueue.userEnqueueHints] to
+ * ShellScaffold. The queue itself is an app-scoped singleton; this VM
+ * just bridges its SharedFlow into a `hiltViewModel()`-resolvable
+ * surface so ShellScaffold can collect it without an EntryPoint
+ * accessor. Mirrors PlaybackErrorViewModel.
+ */
+@HiltViewModel
+class OfflineWriteHintViewModel @Inject constructor(
+    mutationQueue: MutationQueue,
+) : ViewModel() {
+    val messages: Flow<String> = mutationQueue.userEnqueueHints
+}
@@ -1,7 +1,10 @@
 package com.fabledsword.minstrel.cache.sync

+import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.api.endpoints.SyncApi
 import com.fabledsword.minstrel.auth.AuthStore
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
 import com.fabledsword.minstrel.cache.db.dao.CachedAlbumDao
 import com.fabledsword.minstrel.cache.db.dao.CachedArtistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedTrackDao
@@ -15,9 +18,15 @@ import com.fabledsword.minstrel.models.wire.SyncAlbumWire
 import com.fabledsword.minstrel.models.wire.SyncArtistWire
 import com.fabledsword.minstrel.models.wire.SyncTrackWire
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
 import kotlinx.datetime.Clock
 import retrofit2.Retrofit
 import retrofit2.create
@@ -50,10 +59,26 @@ class SyncController @Inject constructor(
    private val trackDao: CachedTrackDao,
    private val authStore: AuthStore,
    @ApplicationScope private val scope: CoroutineScope,
+    networkStatus: NetworkStatusController,
    retrofit: Retrofit,
 ) {
    private val api: SyncApi = retrofit.create()

+    // Single in-flight guard: the cookie + health-recovery triggers (and a
+    // pull-to-refresh) can fire concurrently; coalesce them into one pass.
+    private val mutex = Mutex()
+
+    private val lastSyncErrorInternal = MutableStateFlow<String?>(null)
+
+    /**
+     * Human copy for the most recent sync failure; null after any clean
+     * pass. Lets the Library screen distinguish "empty because the first
+     * sync failed" (show error + retry) from "genuinely empty library"
+     * (show welcome copy) — a failed sync over a populated cache stays
+     * silent, since the cached content is still the better surface.
+     */
+    val lastSyncError: StateFlow<String?> = lastSyncErrorInternal.asStateFlow()
+
    init {
        scope.launch {
            authStore.sessionCookie
@@ -61,11 +86,27 @@ class SyncController @Inject constructor(
                .distinctUntilChanged()
                .collect { syncSafe() }
        }
+        // Re-sync when the server becomes reachable again mid-session, so a
+        // delta missed while offline lands without waiting for a cold start.
+        scope.launch {
+            networkStatus.state
+                .map { it == ServerHealth.Healthy }
+                .distinctUntilChanged()
+                .filter { it }
+                .collect { syncSafe() }
+        }
    }

-    /** Public entry-point for "Sync now" affordances. Swallows errors. */
+    /** Public entry-point for "Sync now" affordances. Swallows errors into [lastSyncError]. */
    suspend fun syncSafe() {
+        if (!mutex.tryLock()) return
+        try {
            runCatching { sync() }
+                .onSuccess { lastSyncErrorInternal.value = null }
+                .onFailure { lastSyncErrorInternal.value = ErrorCopy.fromThrowable(it) }
+        } finally {
+            mutex.unlock()
+        }
    }

    private suspend fun sync() {
@@ -14,11 +14,23 @@ import javax.inject.Inject
 import javax.inject.Singleton

 /**
- * Single source of truth for the device's "is the internet usable
- * right now" signal — wraps [ConnectivityManager] and exposes a hot
- * cold-startable Flow that emits `false` while the active network
- * lacks INTERNET + VALIDATED capabilities (airplane mode, no carrier,
- * captive portal, etc.) and `true` once a usable network appears.
+ * Single source of truth for "does the device have a network link at
+ * all" — wraps [ConnectivityManager] and exposes a hot cold-startable
+ * Flow that emits `false` only when there is no active INTERNET-capable
+ * network (airplane mode, no carrier/Wi-Fi) and `true` once any network
+ * link appears.
+ *
+ * Deliberately does NOT require `NET_CAPABILITY_VALIDATED`. VALIDATED
+ * tracks whether Android reached its own WAN internet-validation probe
+ * (Google's `generate_204`) — which is the wrong question for a
+ * self-hosted server that is usually on the LAN. A transient WAN/DNS
+ * blip (or Android's periodic re-validation) momentarily drops VALIDATED
+ * while the Minstrel box stays perfectly reachable; gating on it flipped
+ * the app to Offline with no debounce and fast-failed in-flight playback
+ * via [com.fabledsword.minstrel.player.OfflineGatedDataSource]. The
+ * authority on whether *Minstrel* is reachable is the `/healthz` poll
+ * ([com.fabledsword.minstrel.connectivity.NetworkStatusController], which
+ * has its own failure hysteresis), not this coarse device-link signal.
 *
 * Used by the shell-level ConnectionErrorBanner; downstream
 * repositories can also collect this to gate retry loops.
@@ -35,21 +47,22 @@ class ConnectivityObserver @Inject constructor(
            .build()
        val callback = object : ConnectivityManager.NetworkCallback() {
            override fun onAvailable(network: Network) {
-                trySend(hasUsableInternet())
+                trySend(hasActiveNetwork())
            }
            override fun onLost(network: Network) {
-                trySend(hasUsableInternet())
+                trySend(hasActiveNetwork())
            }
            override fun onCapabilitiesChanged(
                network: Network,
                capabilities: NetworkCapabilities,
            ) {
+                // INTERNET only -- NOT VALIDATED. A WAN/validation flicker
+                // must not read as "device offline" when the LAN (and the
+                // Minstrel server on it) is still reachable. /healthz is the
+                // authority on server reachability.
                trySend(
                    capabilities.hasCapability(
                        NetworkCapabilities.NET_CAPABILITY_INTERNET,
-                    ) &&
-                        capabilities.hasCapability(
-                            NetworkCapabilities.NET_CAPABILITY_VALIDATED,
                    ),
                )
            }
@@ -57,14 +70,13 @@ class ConnectivityObserver @Inject constructor(
        cm.registerNetworkCallback(request, callback)
        // Seed the initial value so the banner doesn't flash before the
        // first capability callback fires.
-        trySend(hasUsableInternet())
+        trySend(hasActiveNetwork())
        awaitClose { cm.unregisterNetworkCallback(callback) }
    }.distinctUntilChanged()

-    private fun hasUsableInternet(): Boolean {
+    private fun hasActiveNetwork(): Boolean {
        val caps = cm.activeNetwork?.let { cm.getNetworkCapabilities(it) }
        return caps != null &&
-            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
-            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
+            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
    }
 }
@@ -0,0 +1,176 @@
+package com.fabledsword.minstrel.connectivity
+
+import androidx.compose.runtime.staticCompositionLocalOf
+import com.fabledsword.minstrel.BuildConfig
+import com.fabledsword.minstrel.auth.AuthStore
+import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.update.api.HealthzApi
+import com.fabledsword.minstrel.update.api.HealthzResponse
+import com.fabledsword.minstrel.update.data.VersionResult
+import com.fabledsword.minstrel.update.data.isVersionNewer
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import retrofit2.Retrofit
+import timber.log.Timber
+import java.util.concurrent.atomic.AtomicLong
+import javax.inject.Inject
+import javax.inject.Singleton
+
+private const val POLL_HEALTHY_MS = 5 * 60 * 1000L
+private const val POLL_DEGRADED_MS = 20_000L
+private const val ARBITRATE_MIN_GAP_MS = 2_000L
+
+/**
+ * THE single authority on network/server reachability. Absorbs the former
+ * VersionCheckController (the /healthz poll + version parsing) and
+ * ServerHealthController (the tri-state derive) into one signal-driven unit so
+ * the app has one place that answers "can we reach Minstrel?" — not three
+ * half-systems reporting differently.
+ *
+ * Inputs (all funnel through a single-consumer intent channel for thread
+ * safety — [reportSuccess]/[reportFailure] are called from the audio read path
+ * and OkHttp threads):
+ *  - device link transitions ([ConnectivityObserver]); link-return triggers an
+ *    immediate probe so recovery is near-instant (fixes the sticky banner).
+ *  - periodic /healthz probe, adaptive cadence (calm when Healthy, fast when down).
+ *  - reportSuccess / reportFailure from the API interceptor, the audio data
+ *    source, and the playback-error reporter.
+ *  - recheck() from pull-to-refresh and the banner.
+ *
+ * Version compatibility is a byproduct of the same /healthz response.
+ *
+ * Constructed at launch via the construct-the-singleton trick in
+ * [com.fabledsword.minstrel.MinstrelApplication].
+ */
+@Singleton
+class NetworkStatusController @Inject constructor(
+    @ApplicationScope private val scope: CoroutineScope,
+    connectivity: ConnectivityObserver,
+    private val authStore: AuthStore,
+    retrofit: Retrofit,
+) {
+    private val api: HealthzApi = retrofit.create(HealthzApi::class.java)
+    private val machine = ReachabilityMachine()
+    private val lastProbeAtMs = AtomicLong(0)
+
+    private val stateInternal = MutableStateFlow(ServerHealth.Healthy)
+    val state: StateFlow<ServerHealth> = stateInternal.asStateFlow()
+
+    private val versionInternal = MutableStateFlow(VersionResult.SKIPPED)
+    val versionResult: StateFlow<VersionResult> = versionInternal.asStateFlow()
+
+    private sealed interface Intent {
+        data class Link(val up: Boolean) : Intent
+        data class Probe(val resp: HealthzResponse?) : Intent
+        object OpSuccess : Intent
+        object OpFailure : Intent
+    }
+
+    private val intents = Channel<Intent>(Channel.UNLIMITED)
+
+    init {
+        scope.launch { reduceLoop() }
+        scope.launch {
+            connectivity.online.collect { up ->
+                intents.trySend(Intent.Link(up))
+                if (up) probeOnce()
+            }
+        }
+        scope.launch { pollLoop() }
+    }
+
+    /** A real server op verifiably succeeded — self-proving recovery. Cheap; safe on hot paths. */
+    fun reportSuccess() {
+        if (stateInternal.value != ServerHealth.Healthy) intents.trySend(Intent.OpSuccess)
+    }
+
+    /** A real network op failed — triggers /healthz arbitration. No-op when already Offline. */
+    fun reportFailure() {
+        if (stateInternal.value == ServerHealth.Offline) return
+        intents.trySend(Intent.OpFailure)
+    }
+
+    /** One-shot recheck for pull-to-refresh and the banner. */
+    fun recheck() {
+        scope.launch { probeOnce(force = true) }
+    }
+
+    private suspend fun reduceLoop() {
+        for (intent in intents) {
+            val now = System.currentTimeMillis()
+            when (intent) {
+                is Intent.Link -> machine.onLinkChange(intent.up)
+                is Intent.Probe -> applyProbe(intent.resp, now)
+                Intent.OpSuccess -> machine.onSuccess()
+                Intent.OpFailure -> {
+                    machine.onOpFailure(now)
+                    // Arbitrate off the reducer thread: awaiting a stalled
+                    // /healthz here would block a concurrent self-proving
+                    // success from snapping us straight back to Healthy.
+                    scope.launch { probeOnce() }
+                }
+            }
+            emit(machine.health())
+        }
+    }
+
+    private fun applyProbe(resp: HealthzResponse?, now: Long) {
+        if (resp == null) {
+            machine.onProbeFailure(now)
+        } else {
+            machine.onSuccess()
+            versionInternal.value = versionResultFor(resp)
+        }
+    }
+
+    private fun emit(next: ServerHealth) {
+        if (stateInternal.value != next) {
+            Timber.w("NetworkStatus -> %s", next)
+            stateInternal.value = next
+        }
+    }
+
+    private suspend fun pollLoop() {
+        probeOnce()
+        while (true) {
+            val interval =
+                if (stateInternal.value == ServerHealth.Healthy) POLL_HEALTHY_MS
+                else POLL_DEGRADED_MS
+            delay(interval)
+            probeOnce()
+        }
+    }
+
+    private suspend fun probeOnce(force: Boolean = false) {
+        // Startup guard: don't poll the localhost placeholder before AuthStore
+        // hydrates the real base URL — that false failure used to flash the banner.
+        if (authStore.baseUrl.value == AuthStore.DEFAULT_BASE_URL) return
+        val now = System.currentTimeMillis()
+        if (!force && now - lastProbeAtMs.get() < ARBITRATE_MIN_GAP_MS) return
+        lastProbeAtMs.set(now)
+        val resp = runCatching { api.check() }.getOrNull()
+        intents.trySend(Intent.Probe(resp))
+    }
+
+    private fun versionResultFor(resp: HealthzResponse): VersionResult {
+        val min = resp.minClientVersion
+        return when {
+            min.isEmpty() -> VersionResult.SKIPPED
+            isVersionNewer(min, BuildConfig.VERSION_NAME) -> VersionResult.TOO_OLD
+            else -> VersionResult.OK
+        }
+    }
+}
+
+/**
+ * Reactive [ServerHealth] snapshot provided once at the app root. Lets leaf
+ * composables (TrackRow gating, write-affordance disabling) branch on health
+ * without re-injecting the controller. Defaults to Healthy so previews/tests
+ * don't crash.
+ */
+val LocalServerHealth = staticCompositionLocalOf { ServerHealth.Healthy }
@@ -0,0 +1,88 @@
+package com.fabledsword.minstrel.connectivity
+
+internal const val ESCALATE_AFTER_MS = 120_000L
+internal const val CORROBORATION_WINDOW_MS = 30_000L
+internal const val CORROBORATION_OP_THRESHOLD = 2
+
+/**
+ * Pure reachability state machine. No Android, no coroutines, no real clock —
+ * every entry point takes `nowMs`, so it is fully deterministic and unit-
+ * testable. [NetworkStatusController] wires real time + signals around it.
+ *
+ * Reachability (independent of the device link):
+ *  - Reachable   last evidence says the server answered.
+ *  - Unstable    a probe failed; arbitration/escalation pending.
+ *  - Unreachable corroborated or sustained failure.
+ *
+ * [health] folds the device link over that: no link → Offline; otherwise the
+ * reachability maps Reachable→Healthy, Unstable→Unstable, Unreachable→ServerDown.
+ *
+ * Principle: **success is self-proving, failure is ambiguous.** [onSuccess]
+ * (a real server byte-read or API 2xx, or a successful /healthz) snaps straight
+ * back to Reachable. A failure only escalates when a /healthz probe corroborates
+ * it ([onProbeFailure]) — either via fresh op-failure corroboration or the
+ * sustained-time backstop.
+ */
+class ReachabilityMachine {
+
+    private enum class Reachability { Reachable, Unstable, Unreachable }
+
+    private var linkUp = true
+    private var reachability = Reachability.Reachable
+    private var failureStreakStartMs: Long? = null
+    private val recentOpFailures = ArrayDeque<Long>()
+
+    fun onLinkChange(up: Boolean) {
+        linkUp = up
+        // Link transitions don't reset reachability — a restored link keeps the
+        // last-known server reachability until a fresh probe/op result arrives.
+        if (!up) recentOpFailures.clear()
+    }
+
+    /** A real successful server op (stream read, API 2xx) or a successful /healthz. */
+    fun onSuccess() {
+        reachability = Reachability.Reachable
+        failureStreakStartMs = null
+        recentOpFailures.clear()
+    }
+
+    /** A real network op failed. Ambiguous on its own — records corroboration. */
+    fun onOpFailure(nowMs: Long) {
+        pruneOpFailures(nowMs)
+        recentOpFailures.addLast(nowMs)
+    }
+
+    /** A /healthz probe failed — the arbiter. Escalates per corroboration/backstop. */
+    fun onProbeFailure(nowMs: Long) {
+        pruneOpFailures(nowMs)
+        if (reachability == Reachability.Reachable) {
+            reachability = Reachability.Unstable
+            failureStreakStartMs = nowMs
+        }
+        if (reachability == Reachability.Unstable && shouldEscalate(nowMs)) {
+            reachability = Reachability.Unreachable
+        }
+    }
+
+    fun health(): ServerHealth = when {
+        !linkUp -> ServerHealth.Offline
+        reachability == Reachability.Reachable -> ServerHealth.Healthy
+        reachability == Reachability.Unstable -> ServerHealth.Unstable
+        else -> ServerHealth.ServerDown
+    }
+
+    private fun shouldEscalate(nowMs: Long): Boolean {
+        val corroborated = recentOpFailures.size >= CORROBORATION_OP_THRESHOLD
+        val sustained =
+            failureStreakStartMs?.let { nowMs - it >= ESCALATE_AFTER_MS } ?: false
+        return corroborated || sustained
+    }
+
+    private fun pruneOpFailures(nowMs: Long) {
+        while (recentOpFailures.isNotEmpty() &&
+            nowMs - recentOpFailures.first() > CORROBORATION_WINDOW_MS
+        ) {
+            recentOpFailures.removeFirst()
+        }
+    }
+}
@@ -0,0 +1,49 @@
+package com.fabledsword.minstrel.connectivity
+
+import com.fabledsword.minstrel.api.BaseUrlInterceptor.Companion.PLACEHOLDER_HOST
+import dagger.Lazy
+import okhttp3.Interceptor
+import okhttp3.Response
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+private const val HEALTHZ_PATH = "/healthz"
+
+/**
+ * Feeds real Minstrel API outcomes into [NetworkStatusController]. A 2xx is
+ * self-proving proof the server is reachable → reportSuccess(); a transport
+ * [IOException] (no response at all) → reportFailure(), which triggers /healthz
+ * arbitration.
+ *
+ * MUST run first in the OkHttp chain (before [BaseUrlInterceptor]) so the host
+ * is still the [PLACEHOLDER_HOST] sentinel: this shared client also fetches
+ * EXTERNAL artwork (musicbrainz / coverartarchive), and an external image
+ * loading must NOT be read as "our server is reachable" — only sentinel-host
+ * requests are Minstrel-bound. 5xx is deliberately NOT a failure (the server
+ * answered), and /healthz is skipped to avoid a feedback loop with the poll.
+ *
+ * [NetworkStatusController] is injected as a [Lazy] to break the Hilt cycle:
+ * the controller needs `Retrofit`, which needs `OkHttpClient`, which needs this
+ * interceptor. By the time a request flows through, the controller singleton is
+ * already constructed (construct-the-singleton trick in MinstrelApplication).
+ */
+@Singleton
+class ReachabilityReportingInterceptor @Inject constructor(
+    private val networkStatus: Lazy<NetworkStatusController>,
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request()
+        val isMinstrel = request.url.host == PLACEHOLDER_HOST
+        val isHealthz = request.url.encodedPath.endsWith(HEALTHZ_PATH)
+        if (!isMinstrel || isHealthz) return chain.proceed(request)
+        return try {
+            val response = chain.proceed(request)
+            if (response.isSuccessful) networkStatus.get().reportSuccess()
+            response
+        } catch (e: IOException) {
+            networkStatus.get().reportFailure()
+            throw e
+        }
+    }
+}
@@ -0,0 +1,27 @@
+package com.fabledsword.minstrel.connectivity
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.drop
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.flow.map
+
+/**
+ * Emits once each time server health RETURNS to [ServerHealth.Healthy]
+ * after the collector subscribed — the StateFlow's replayed current value
+ * is dropped, so only genuine down→up transitions fire (a screen that
+ * subscribes while already Healthy doesn't double-load).
+ *
+ * This is the screen-level half of the recovery idiom the app-lifetime
+ * singletons (SyncController / MutationReplayer / DiagnosticsUploader)
+ * already use: a ViewModel collects this in its viewModelScope and re-runs
+ * its load, so a surface that failed while the server was unreachable
+ * heals itself the moment connectivity returns instead of sitting in the
+ * failed state until a manual pull-to-refresh.
+ */
+fun NetworkStatusController.recoveries(): Flow<Unit> = state
+    .map { it == ServerHealth.Healthy }
+    .distinctUntilChanged()
+    .drop(1)
+    .filter { it }
+    .map { }
@@ -0,0 +1,15 @@
+package com.fabledsword.minstrel.connectivity
+
+/**
+ * The single reachability signal every consumer branches on.
+ *
+ *  - [Healthy]    link up, /healthz ok — normal network behavior.
+ *  - [Unstable]   link up, a recent failure with arbitration pending —
+ *                 INFORMATIONAL ONLY. Does NOT gate playback; preserves the
+ *                 anti-flicker intent of commit 5c0db429 while still warning
+ *                 the user that something is flaky.
+ *  - [ServerDown] link up but /healthz failing, corroborated or sustained —
+ *                 gate to cache-only.
+ *  - [Offline]    no device link at all — gate to cache-only.
+ */
+enum class ServerHealth { Healthy, Unstable, ServerDown, Offline }
@@ -14,77 +14,121 @@ import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.unit.dp
 import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.SavedStateHandle
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
-import androidx.lifecycle.viewModelScope
 import com.composables.icons.lucide.CloudOff
 import com.composables.icons.lucide.Lucide
-import com.fabledsword.minstrel.connectivity.ConnectivityObserver
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
 import dagger.hilt.android.lifecycle.HiltViewModel
-import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.StateFlow
-import kotlinx.coroutines.flow.stateIn
 import javax.inject.Inject

-private const val ONLINE_SHARE_STOP_TIMEOUT_MS = 5_000L
+private const val BACK_ONLINE_FLASH_MS = 2_000L

 /**
- * Tiny VM that just lifts the [ConnectivityObserver] singleton's
- * Flow into a StateFlow with the standard sharing strategy. Keeps
- * the banner composable pure-presentation.
+ * Exposes [NetworkStatusController]'s tri-state directly to the banner. No
+ * re-wrapping StateFlow — the controller's is already app-scoped and warm.
 */
@HiltViewModel
 class ConnectivityBannerViewModel @Inject constructor(
-    observer: ConnectivityObserver,
+    networkStatus: NetworkStatusController,
    @Suppress("UnusedPrivateProperty") savedStateHandle: SavedStateHandle,
 ) : ViewModel() {
-    val online: StateFlow<Boolean> = observer.online.stateIn(
-        scope = viewModelScope,
-        started = SharingStarted.WhileSubscribed(ONLINE_SHARE_STOP_TIMEOUT_MS),
-        initialValue = true,
-    )
+    val health: StateFlow<ServerHealth> = networkStatus.state
 }

 /**
- * Banner shown at the top of the shell when the device has no usable
- * internet. Mirrors Flutter's ConnectionErrorBanner: red-tinted error
- * surface, CloudOff icon, "No connection — check Wi-Fi or mobile
- * data" copy. Auto-hides via slide+fade when connectivity returns.
+ * Shell banner. Tells the user *why* they're degraded — no link vs server-down
+ * — plus a non-alarming "Reconnecting…" for the transient [ServerHealth.Unstable]
+ * window, and a brief "Back online" confirmation when health recovers so
+ * recovery is unmistakable. Sentence case, understated voice (design system).
 */
@Composable
 fun ConnectionErrorBanner(
    viewModel: ConnectivityBannerViewModel = hiltViewModel(),
 ) {
-    val online by viewModel.online.collectAsStateWithLifecycle()
+    val health by viewModel.health.collectAsStateWithLifecycle()
+    var showBackOnline by remember { mutableStateOf(false) }
+    var wasDown by remember { mutableStateOf(false) }
+
+    LaunchedEffect(health) {
+        val down = health == ServerHealth.Offline || health == ServerHealth.ServerDown
+        if (health == ServerHealth.Healthy && wasDown) {
+            // try/finally so a mid-delay cancellation (health flips again) can't
+            // orphan the flag and leave "Back online" stuck on screen.
+            try {
+                showBackOnline = true
+                delay(BACK_ONLINE_FLASH_MS)
+            } finally {
+                showBackOnline = false
+            }
+        }
+        wasDown = down
+    }
+
    AnimatedVisibility(
-        visible = !online,
+        visible = health != ServerHealth.Healthy || showBackOnline,
        enter = expandVertically() + fadeIn(),
        exit = shrinkVertically() + fadeOut(),
    ) {
+        BannerContent(health = health, backOnline = showBackOnline)
+    }
+}
+
+@Composable
+private fun BannerContent(health: ServerHealth, backOnline: Boolean) {
+    val scheme = MaterialTheme.colorScheme
+    val background: Color
+    val foreground: Color
+    when {
+        backOnline -> {
+            background = scheme.secondaryContainer
+            foreground = scheme.onSecondaryContainer
+        }
+        health == ServerHealth.Unstable -> {
+            background = scheme.surfaceVariant
+            foreground = scheme.onSurfaceVariant
+        }
+        else -> {
+            background = scheme.errorContainer
+            foreground = scheme.onErrorContainer
+        }
+    }
    Row(
        modifier = Modifier
            .fillMaxWidth()
-                .background(MaterialTheme.colorScheme.errorContainer)
+            .background(background)
            .padding(horizontal = 16.dp, vertical = 10.dp),
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.spacedBy(12.dp),
    ) {
-            Icon(
-                imageVector = Lucide.CloudOff,
-                contentDescription = null,
-                tint = MaterialTheme.colorScheme.onErrorContainer,
-            )
+        Icon(imageVector = Lucide.CloudOff, contentDescription = null, tint = foreground)
        Text(
-                text = "No connection — check Wi-Fi or mobile data.",
+            text = bannerText(health, backOnline),
            style = MaterialTheme.typography.bodyMedium,
-                color = MaterialTheme.colorScheme.onErrorContainer,
+            color = foreground,
        )
    }
-    }
+}
+
+private fun bannerText(health: ServerHealth, backOnline: Boolean): String = when {
+    backOnline -> "Back online."
+    health == ServerHealth.Offline -> "No connection — check Wi-Fi or mobile data."
+    health == ServerHealth.ServerDown ->
+        "Server unreachable — your cached content is still available."
+    health == ServerHealth.Unstable -> "Reconnecting…"
+    else -> ""
 }
@@ -0,0 +1,328 @@
+package com.fabledsword.minstrel.diagnostics
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.os.PowerManager
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.core.content.ContextCompat
+import androidx.lifecycle.ProcessLifecycleOwner
+import com.fabledsword.minstrel.auth.AuthController
+import com.fabledsword.minstrel.auth.AuthStore
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
+import com.fabledsword.minstrel.connectivity.ConnectivityObserver
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.player.PlayerController
+import com.fabledsword.minstrel.player.RemotePlayerState
+import com.fabledsword.minstrel.player.output.OutputPickerController
+import com.fabledsword.minstrel.player.output.OutputRoute
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.combine
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.launch
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.put
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * On-device diagnostics collector (M9). Active only while the account's
+ * debug mode is enabled (server flag, read via AuthController.currentUser)
+ * AND the user hasn't opted out locally. When active it taps existing
+ * connectivity / player / UPnP / power seams READ-ONLY and writes a
+ * timeseries of events into the [DiagnosticEventDao] ring buffer; the
+ * [DiagnosticsUploader] drains that buffer to the server.
+ *
+ * The aim is to explain two failure classes after the fact: roaming /
+ * poor-data recovery (connectivity + server-health transitions) and
+ * locked-phone UPnP desync (power/Doze transitions correlated with the
+ * Sonos-vs-local position deltas captured in the heartbeat).
+ */
+@Suppress("TooManyFunctions") // one collector + one (un)register pair per signal; cohesive
+@Singleton
+class DiagnosticsReporter @Inject constructor(
+    @ApplicationContext private val context: Context,
+    @ApplicationScope private val scope: CoroutineScope,
+    private val dao: DiagnosticEventDao,
+    private val authController: AuthController,
+    private val authStore: AuthStore,
+    private val connectivity: ConnectivityObserver,
+    private val networkStatus: NetworkStatusController,
+    private val playerController: PlayerController,
+    private val outputPicker: OutputPickerController,
+    private val remoteState: RemotePlayerState,
+    private val json: Json,
+) {
+    @Volatile private var enabled = false
+    private var collectorJob: Job? = null
+    private var powerReceiver: BroadcastReceiver? = null
+    private var lifecycleObserver: DefaultLifecycleObserver? = null
+
+    init {
+        // Gate = account flag (currentUser.debugModeEnabled) AND not the
+        // per-device local opt-out.
+        scope.launch {
+            combine(authController.currentUser, authStore.diagnosticsOptOut) { user, optOut ->
+                (user?.debugModeEnabled == true) && !optOut
+            }.distinctUntilChanged().collect { setEnabled(it) }
+        }
+        // Periodically re-pull /me so a remote admin flip propagates
+        // without a re-login or app restart.
+        scope.launch {
+            while (true) {
+                delay(GATE_REFRESH_MS)
+                authController.refreshProfile()
+            }
+        }
+    }
+
+    private fun setEnabled(value: Boolean) {
+        if (value == enabled) return
+        enabled = value
+        if (value) start() else stop()
+    }
+
+    private fun start() {
+        registerPowerReceiver()
+        registerLifecycleObserver()
+        collectorJob = scope.launch {
+            record("lifecycle", buildJsonObject { put("event", "reporting_started") })
+            launch { collectConnectivity() }
+            launch { collectServerHealth() }
+            launch { collectUpnpDrops() }
+            launch { collectPlayerState() }
+            launch { collectTrackChanges() }
+            launch { collectRoutes() }
+            launch { heartbeatLoop() }
+        }
+    }
+
+    private fun stop() {
+        collectorJob?.cancel()
+        collectorJob = null
+        unregisterPowerReceiver()
+        unregisterLifecycleObserver()
+        // Off means off: drop any unsent buffer (honors the user OFF
+        // intent and avoids leaking data captured before disable).
+        scope.launch { runCatching { dao.clear() } }
+    }
+
+    private suspend fun collectConnectivity() {
+        connectivity.online.distinctUntilChanged().collect { online ->
+            record("connectivity", buildJsonObject {
+                put("event", "online_changed")
+                put("online", online)
+            })
+        }
+    }
+
+    private suspend fun collectServerHealth() {
+        // state is a StateFlow — already conflated/distinct, so no
+        // distinctUntilChanged (it's a deprecation warning = build error).
+        networkStatus.state.collect { s ->
+            record("connectivity", buildJsonObject {
+                put("event", "server_health")
+                put("state", s.name)
+            })
+        }
+    }
+
+    private suspend fun collectUpnpDrops() {
+        playerController.dropEvents.collect { msg ->
+            record("upnp_sync", buildJsonObject {
+                put("event", "drop")
+                put("message", msg)
+            })
+        }
+    }
+
+    private suspend fun collectPlayerState() {
+        // 'playback', not 'upnp_sync' — player state applies to every output
+        // route (phone speaker, Bluetooth, UPnP), not just casting.
+        playerController.uiState
+            .map { Triple(it.currentSource, it.isUpnpLoading, it.playbackError) }
+            .distinctUntilChanged()
+            .collect { (source, upnpLoading, err) ->
+                record("playback", buildJsonObject {
+                    put("event", "player_state")
+                    put("source", source ?: "")
+                    put("upnp_loading", upnpLoading)
+                    if (err != null) put("error", err)
+                })
+            }
+    }
+
+    // Emit a snapshot at each track/queue-index change — captures a
+    // skip-induced local↔Sonos desync at the INSTANT it happens, which the
+    // 45s heartbeat misses. Note: uiState is a conflated StateFlow, so a
+    // very rapid skip burst may coalesce intermediate indices (we still get
+    // the boundaries + the local-vs-Sonos snapshot).
+    private suspend fun collectTrackChanges() {
+        playerController.uiState
+            .map { it.queueIndex to it.currentTrack?.id }
+            .distinctUntilChanged()
+            .collect { (index, _) ->
+                val ui = playerController.uiState.value
+                val casting = outputPicker.routesState.value.current.protocol !=
+                    OutputRoute.Protocol.SYSTEM
+                record("playback", buildJsonObject {
+                    put("event", "track_change")
+                    put("local_index", index)
+                    // Track IDENTITY, not just index — indices wobble across
+                    // re-casts, so the id + Sonos URI make a desync unambiguous.
+                    put("local_track_id", ui.currentTrack?.id ?: "")
+                    put("local_pos_ms", ui.positionMs)
+                    putSonos(this, casting)
+                    put("upnp_loading", ui.isUpnpLoading)
+                    put("server_health", networkStatus.state.value.name)
+                    put("route", outputPicker.routesState.value.current.name)
+                })
+            }
+    }
+
+    private suspend fun collectRoutes() {
+        // 'playback' — route changes happen for all outputs. This only ever
+        // logs the ACTIVE route (routesState.current), so no "connected" flag.
+        outputPicker.routesState.map { it.current }.distinctUntilChanged().collect { r ->
+            record("playback", buildJsonObject {
+                put("event", "route")
+                put("id", r.id)
+                put("name", r.name)
+                put("kind", r.kind.name)
+                put("protocol", r.protocol.name)
+            })
+        }
+    }
+
+    private suspend fun heartbeatLoop() {
+        while (true) {
+            delay(HEARTBEAT_MS)
+            val ui = playerController.uiState.value
+            val route = outputPicker.routesState.value.current
+            val routeActive = route.protocol != OutputRoute.Protocol.SYSTEM
+            // Idle = nothing worth sampling. Skip to keep the buffer lean.
+            if (!ui.isPlaying && !routeActive) continue
+            record("heartbeat", buildJsonObject {
+                put("server_health", networkStatus.state.value.name)
+                put("is_playing", ui.isPlaying)
+                put("source", ui.currentSource ?: "")
+                put("local_index", ui.queueIndex)
+                put("local_track_id", ui.currentTrack?.id ?: "")
+                put("local_pos_ms", ui.positionMs)
+                put("route", route.name)
+                put("route_protocol", route.protocol.name)
+                putSonos(this, routeActive)
+                addPowerFields(this)
+            })
+        }
+    }
+
+    // --- power + lifecycle taps -------------------------------------------
+
+    private fun registerPowerReceiver() {
+        if (powerReceiver != null) return
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(c: Context?, intent: Intent?) {
+                val action = intent?.action ?: return
+                if (!enabled) return
+                scope.launch { record("power", powerEvent(action)) }
+            }
+        }
+        val filter = IntentFilter().apply {
+            addAction(Intent.ACTION_SCREEN_ON)
+            addAction(Intent.ACTION_SCREEN_OFF)
+            addAction(PowerManager.ACTION_DEVICE_IDLE_MODE_CHANGED)
+        }
+        // System-protected broadcasts, but pass NOT_EXPORTED explicitly so
+        // the API 34+ registerReceiver flag requirement is satisfied.
+        ContextCompat.registerReceiver(
+            context, receiver, filter, ContextCompat.RECEIVER_NOT_EXPORTED,
+        )
+        powerReceiver = receiver
+    }
+
+    private fun unregisterPowerReceiver() {
+        powerReceiver?.let { runCatching { context.unregisterReceiver(it) } }
+        powerReceiver = null
+    }
+
+    private fun registerLifecycleObserver() {
+        if (lifecycleObserver != null) return
+        val obs = object : DefaultLifecycleObserver {
+            override fun onStart(owner: LifecycleOwner) = logLifecycle("app_foreground")
+            override fun onStop(owner: LifecycleOwner) = logLifecycle("app_background")
+        }
+        lifecycleObserver = obs
+        scope.launch(Dispatchers.Main) {
+            ProcessLifecycleOwner.get().lifecycle.addObserver(obs)
+        }
+    }
+
+    private fun unregisterLifecycleObserver() {
+        val obs = lifecycleObserver ?: return
+        lifecycleObserver = null
+        scope.launch(Dispatchers.Main) {
+            ProcessLifecycleOwner.get().lifecycle.removeObserver(obs)
+        }
+    }
+
+    private fun logLifecycle(event: String) {
+        if (!enabled) return
+        scope.launch { record("lifecycle", buildJsonObject { put("event", event) }) }
+    }
+
+    private fun powerEvent(action: String): JsonObject = buildJsonObject {
+        put("event", action.substringAfterLast('.'))
+        addPowerFields(this)
+    }
+
+    // Sonos/UPnP remote-vs-local desync fields. Only meaningful while a
+    // remote route is active; zeroed otherwise so a stale RemotePlayerState
+    // from a just-ended cast can't masquerade as live Sonos data (the
+    // cast→phone handoff artifact). currentTrackUri is the desync ground
+    // truth — it carries the track the speaker is actually streaming.
+    private fun putSonos(builder: kotlinx.serialization.json.JsonObjectBuilder, casting: Boolean) {
+        builder.put("sonos_track", if (casting) remoteState.trackNumber else 0)
+        builder.put("sonos_pos_ms", if (casting) remoteState.positionMs else 0)
+        builder.put("sonos_playing", casting && remoteState.isPlaying)
+        if (casting) builder.put("sonos_uri", remoteState.currentTrackUri)
+    }
+
+    private fun addPowerFields(builder: kotlinx.serialization.json.JsonObjectBuilder) {
+        val pm = context.getSystemService(Context.POWER_SERVICE) as PowerManager
+        builder.put("doze", pm.isDeviceIdleMode)
+        builder.put("screen_on", pm.isInteractive)
+        builder.put("battery_opt_ignored", pm.isIgnoringBatteryOptimizations(context.packageName))
+    }
+
+    private suspend fun record(kind: String, payload: JsonObject) {
+        runCatching {
+            val id = dao.insert(
+                DiagnosticEventEntity(
+                    kind = kind,
+                    occurredAtMillis = System.currentTimeMillis(),
+                    payloadJson = json.encodeToString(JsonObject.serializer(), payload),
+                ),
+            )
+            if (id % TRIM_INTERVAL == 0L) dao.trimToNewest(MAX_BUFFER)
+        }
+    }
+
+    private companion object {
+        const val HEARTBEAT_MS = 45_000L
+        const val GATE_REFRESH_MS = 300_000L // re-pull /me every 5 min
+        const val MAX_BUFFER = 5_000 // ring-buffer ceiling, oldest dropped
+        const val TRIM_INTERVAL = 50L // trim every N inserts, not every one
+    }
+}
@@ -0,0 +1,118 @@
+package com.fabledsword.minstrel.diagnostics
+
+import android.os.Build
+import com.fabledsword.minstrel.BuildConfig
+import com.fabledsword.minstrel.api.endpoints.DiagnosticEventWire
+import com.fabledsword.minstrel.api.endpoints.DiagnosticsApi
+import com.fabledsword.minstrel.api.endpoints.DiagnosticsReportRequest
+import com.fabledsword.minstrel.auth.AuthStore
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.di.ApplicationScope
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.serialization.json.Json
+import retrofit2.Retrofit
+import retrofit2.create
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Drains the [DiagnosticEventDao] ring buffer to POST /api/diagnostics
+ * (M9). Triggers mirror [com.fabledsword.minstrel.cache.mutations.MutationReplayer]:
+ * a periodic tick, a sign-in (sessionCookie non-null), and a server-health
+ * recovery to [ServerHealth.Healthy] — so a dead-zone's buffered events
+ * upload the moment the link comes back.
+ *
+ * Deliberately NOT the MutationQueue: diagnostics are high-volume,
+ * best-effort telemetry. A failed upload just retries on the next tick;
+ * the server no-ops (204) when the account's debug flag is off, which the
+ * uploader treats as success so the buffer drains either way.
+ */
+@Singleton
+class DiagnosticsUploader @Inject constructor(
+    private val dao: DiagnosticEventDao,
+    private val authStore: AuthStore,
+    private val json: Json,
+    @ApplicationScope private val scope: CoroutineScope,
+    networkStatus: NetworkStatusController,
+    retrofit: Retrofit,
+) {
+    private val api: DiagnosticsApi = retrofit.create()
+    private val mutex = Mutex()
+
+    init {
+        scope.launch {
+            while (true) {
+                delay(UPLOAD_INTERVAL_MS)
+                drainSafe()
+            }
+        }
+        scope.launch {
+            authStore.sessionCookie.filterNotNull().distinctUntilChanged().collect { drainSafe() }
+        }
+        scope.launch {
+            networkStatus.state
+                .map { it == ServerHealth.Healthy }
+                .distinctUntilChanged()
+                .filter { it }
+                .collect { drainSafe() }
+        }
+    }
+
+    /** Coalesces concurrent triggers via tryLock — a drain in flight wins. */
+    private suspend fun drainSafe() {
+        val clientId = authStore.clientId.value
+        // Signed out / no client id yet → nothing to do. Single guard keeps
+        // the return count within the detekt gate.
+        if (authStore.sessionCookie.value.isNullOrEmpty() || clientId == null) return
+        if (!mutex.tryLock()) return
+        try {
+            drain(clientId)
+        } finally {
+            mutex.unlock()
+        }
+    }
+
+    private suspend fun drain(clientId: String) {
+        var more = true
+        while (more) {
+            val batch = runCatching { dao.takeBatch(BATCH_SIZE) }.getOrNull().orEmpty()
+            val sent = batch.isNotEmpty() && runCatching { upload(clientId, batch) }.isSuccess
+            if (sent) runCatching { dao.deleteByIds(batch.map { it.id }) }
+            // Keep going only while a full batch sent cleanly; otherwise stop
+            // (empty buffer, or a failure to retry on the next trigger).
+            more = sent && batch.size >= BATCH_SIZE
+        }
+    }
+
+    private suspend fun upload(clientId: String, batch: List<DiagnosticEventEntity>) {
+        api.report(
+            DiagnosticsReportRequest(
+                clientId = clientId,
+                appVersion = BuildConfig.VERSION_NAME,
+                osVersion = "Android ${Build.VERSION.RELEASE} (${Build.MODEL})",
+                events = batch.map { row ->
+                    DiagnosticEventWire(
+                        kind = row.kind,
+                        occurredAt = row.occurredAtMillis,
+                        payload = json.parseToJsonElement(row.payloadJson),
+                    )
+                },
+            ),
+        )
+    }
+
+    private companion object {
+        const val UPLOAD_INTERVAL_MS = 60_000L
+        const val BATCH_SIZE = 100
+    }
+}
@@ -41,6 +41,7 @@ import com.fabledsword.minstrel.models.ArtistSuggestionRef
 import com.fabledsword.minstrel.models.LidarrRequestKind
 import com.fabledsword.minstrel.models.LidarrSearchResultRef
 import com.fabledsword.minstrel.nav.Discover
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -109,6 +110,7 @@ private fun DiscoverBody(
                            snackbar.showSnackbar(snackbarFor(outcome, s.name))
                        }
                    },
+                    onRetry = { viewModel.loadSuggestions() },
                )
                ResultsState.Loading -> LoadingCentered()
                is ResultsState.Loaded -> ResultsList(
@@ -121,7 +123,11 @@ private fun DiscoverBody(
                        }
                    },
                )
-                is ResultsState.Error -> CenteredMessage("Search failed: ${r.message}")
+                is ResultsState.Error -> ErrorRetry(
+                    title = "Search failed",
+                    message = r.message,
+                    onRetry = viewModel::runSearch,
+                )
            }
        }
    }
@@ -177,10 +183,15 @@ private fun SuggestionsPane(
    state: SuggestionState,
    locallyRequestedMbids: Set<String>,
    onRequest: (ArtistSuggestionRef) -> Unit,
+    onRetry: () -> Unit,
 ) {
    when (state) {
        SuggestionState.Loading -> LoadingCentered()
-        is SuggestionState.Error -> CenteredMessage("Couldn't load suggestions.")
+        is SuggestionState.Error -> ErrorRetry(
+            title = "Couldn't load suggestions",
+            message = state.message,
+            onRetry = onRetry,
+        )
        is SuggestionState.Loaded -> SuggestionsList(
            items = state.items.filter { it.mbid !in locallyRequestedMbids },
            onRequest = onRequest,
@@ -3,6 +3,8 @@ package com.fabledsword.minstrel.discover.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.discover.data.DiscoverRepository
 import com.fabledsword.minstrel.discover.data.RequestOutcome
 import com.fabledsword.minstrel.models.ArtistSuggestionRef
@@ -46,6 +48,7 @@ sealed interface ResultsState {
@HiltViewModel
 class DiscoverViewModel @Inject constructor(
    private val repository: DiscoverRepository,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

    private val internal = MutableStateFlow(DiscoverState())
@@ -53,6 +56,15 @@ class DiscoverViewModel @Inject constructor(

    init {
        loadSuggestions()
+        // Screen-level auto-recovery (issue #1245): re-run whichever pane
+        // failed while the server was unreachable once health returns.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                val s = internal.value
+                if (s.suggestions is SuggestionState.Error) loadSuggestions()
+                if (s.results is ResultsState.Error) runSearch()
+            }
+        }
    }

    fun setQuery(value: String) {
@@ -19,6 +19,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.history.data.HistoryEntry
 import com.fabledsword.minstrel.history.data.HistoryRepository
 import com.fabledsword.minstrel.models.TrackRef
@@ -26,6 +28,7 @@ import com.fabledsword.minstrel.player.PlayerController
 import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.widgets.TrackRow
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.TrackCoverThumb
@@ -56,6 +59,7 @@ private const val SHARE_STOP_TIMEOUT_MS = 5_000L
 class HistoryTabViewModel @Inject constructor(
    private val repository: HistoryRepository,
    private val player: PlayerController,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

    private val refreshError = MutableStateFlow<String?>(null)
@@ -82,6 +86,11 @@ class HistoryTabViewModel @Inject constructor(

    init {
        refresh()
+        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // health returns, so a load that failed offline heals unprompted.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
    }

    fun refresh(): Job = viewModelScope.launch {
@@ -116,9 +125,10 @@ fun HistoryTab(
                title = "No listening history yet",
                body = "Play something — your recent plays will show up here.",
            )
-            is UiState.Error -> EmptyState(
+            is UiState.Error -> ErrorRetry(
                title = "Couldn't load history",
-                body = s.message,
+                message = s.message,
+                onRetry = { viewModel.refresh() },
            )
            is UiState.Success -> HistoryList(
                entries = s.data,
@@ -39,6 +39,9 @@ import javax.inject.Singleton
 * pre-warms the top artists via [HomeArtistPrewarmer].
 */
@Singleton
+// Per-section observe accessors (one per Home row) inflate the function
+// count past detekt's 11 default — accessor density, not complexity.
+@Suppress("TooManyFunctions")
 class HomeRepository @Inject constructor(
    private val homeIndexDao: CachedHomeIndexDao,
    private val metadataProvider: MetadataProvider,
@@ -76,6 +79,12 @@ class HomeRepository @Inject constructor(
    fun observeLastPlayedArtists(): Flow<List<HomeTile<ArtistRef>>> =
        observeArtistSection(SECTION_LAST_PLAYED_ARTISTS)

+    fun observeYouMightLikeAlbums(): Flow<List<HomeTile<AlbumRef>>> =
+        observeAlbumSection(SECTION_YOU_MIGHT_LIKE_ALBUMS)
+
+    fun observeYouMightLikeArtists(): Flow<List<HomeTile<ArtistRef>>> =
+        observeArtistSection(SECTION_YOU_MIGHT_LIKE_ARTISTS)
+
    /**
     * Pulls /api/home/index, replaces each cached_home_index section,
     * and pre-warms the top artists. The section Flows re-fire on the
@@ -88,7 +97,11 @@ class HomeRepository @Inject constructor(
        replaceSection(SECTION_REDISCOVER_ARTISTS, "artist", wire.rediscoverArtists)
        replaceSection(SECTION_MOST_PLAYED_TRACKS, "track", wire.mostPlayedTracks)
        replaceSection(SECTION_LAST_PLAYED_ARTISTS, "artist", wire.lastPlayedArtists)
-        prewarmer.warm(wire.rediscoverArtists + wire.lastPlayedArtists)
+        replaceSection(SECTION_YOU_MIGHT_LIKE_ALBUMS, "album", wire.youMightLikeAlbums)
+        replaceSection(SECTION_YOU_MIGHT_LIKE_ARTISTS, "artist", wire.youMightLikeArtists)
+        prewarmer.warm(
+            wire.rediscoverArtists + wire.lastPlayedArtists + wire.youMightLikeArtists,
+        )
    }

    private suspend fun replaceSection(section: String, entityType: String, ids: List<String>) {
@@ -148,5 +161,7 @@ class HomeRepository @Inject constructor(
        const val SECTION_REDISCOVER_ARTISTS = "rediscover_artists"
        const val SECTION_MOST_PLAYED_TRACKS = "most_played_tracks"
        const val SECTION_LAST_PLAYED_ARTISTS = "last_played_artists"
+        const val SECTION_YOU_MIGHT_LIKE_ALBUMS = "you_might_like_albums"
+        const val SECTION_YOU_MIGHT_LIKE_ARTISTS = "you_might_like_artists"
    }
 }
@@ -54,6 +54,8 @@ import com.composables.icons.lucide.History
 import com.composables.icons.lucide.Lucide
 import com.composables.icons.lucide.Music
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.home.data.HomeRepository
 import com.fabledsword.minstrel.library.data.LibraryRepository
 import com.fabledsword.minstrel.library.widgets.AlbumCard
@@ -69,13 +71,14 @@ import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.nav.Home
 import com.fabledsword.minstrel.nav.PlaylistDetail
 import com.fabledsword.minstrel.playlists.data.PlaylistsRepository
-import com.fabledsword.minstrel.playlists.data.toPlayableTrackRefs
+import com.fabledsword.minstrel.playlists.data.playPlaylistShuffled
 import com.fabledsword.minstrel.playlists.widgets.OfflinePoolCard
 import com.fabledsword.minstrel.playlists.widgets.PlaylistCard
 import com.fabledsword.minstrel.playlists.widgets.PlaylistPlaceholderCard
 import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.asCacheFirstStateFlow
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.HorizontalScrollRow
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -94,12 +97,11 @@ import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.flow.receiveAsFlow
 import kotlinx.coroutines.flow.stateIn
+import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.launch
-import kotlinx.coroutines.withTimeout
 import javax.inject.Inject

 private const val SHARE_STOP_TIMEOUT_MS = 5_000L
-private const val PLAYLIST_FETCH_TIMEOUT_MS = 8_000L
 private const val BOTTOM_PADDING_FOR_MINIPLAYER_DP = 140
 // Recently Added is laid out in a multi-row LazyHorizontalGrid that
 // scrolls as one panel (same pattern as Most Played). Two rows trades
@@ -117,6 +119,8 @@ data class HomeSections(
    val rediscoverArtists: List<HomeTile<ArtistRef>> = emptyList(),
    val mostPlayedTracks: List<HomeTile<TrackRef>> = emptyList(),
    val lastPlayedArtists: List<HomeTile<ArtistRef>> = emptyList(),
+    val youMightLikeAlbums: List<HomeTile<AlbumRef>> = emptyList(),
+    val youMightLikeArtists: List<HomeTile<ArtistRef>> = emptyList(),
 ) {
    val isAllEmpty: Boolean
        get() = playlists.isEmpty() &&
@@ -124,7 +128,9 @@ data class HomeSections(
            rediscoverAlbums.isEmpty() &&
            rediscoverArtists.isEmpty() &&
            mostPlayedTracks.isEmpty() &&
-            lastPlayedArtists.isEmpty()
+            lastPlayedArtists.isEmpty() &&
+            youMightLikeAlbums.isEmpty() &&
+            youMightLikeArtists.isEmpty()
 }

 // ─── ViewModel ───────────────────────────────────────────────────────
@@ -136,7 +142,8 @@ class HomeViewModel @Inject constructor(
    private val libraryRepository: LibraryRepository,
    private val player: com.fabledsword.minstrel.player.PlayerController,
    private val shuffleSource: com.fabledsword.minstrel.cache.ShuffleSource,
-    connectivity: com.fabledsword.minstrel.connectivity.ConnectivityObserver,
+    private val eventsStream: com.fabledsword.minstrel.events.EventsStream,
+    networkStatus: com.fabledsword.minstrel.connectivity.NetworkStatusController,
 ) : ViewModel() {

    private val systemStatusInternal = MutableStateFlow(SystemPlaylistsStatus())
@@ -144,9 +151,13 @@ class HomeViewModel @Inject constructor(
    /** System-playlist build status for the Home placeholder cards. */
    val systemStatus: StateFlow<SystemPlaylistsStatus> = systemStatusInternal.asStateFlow()

-    /** True when the device has no usable internet — gates the offline-pool cards. */
-    val offline: StateFlow<Boolean> = connectivity.online
-        .map { !it }
+    /**
+     * Cache-only when there's no link OR the server is unreachable. Reads the
+     * unified [NetworkStatusController] (not the raw device link) so Home reacts
+     * to ServerDown too; the transient Unstable state stays calm (not offline).
+     */
+    val offline: StateFlow<Boolean> = networkStatus.state
+        .map { it == ServerHealth.Offline || it == ServerHealth.ServerDown }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(SHARE_STOP_TIMEOUT_MS),
@@ -158,8 +169,31 @@ class HomeViewModel @Inject constructor(
    /** Transient snackbar messages from offline-pool taps. */
    val transientMessages: Flow<String> = poolMessages.receiveAsFlow()

+    /**
+     * Copy for the most recent /home/index refresh failure; null once a
+     * refresh succeeds. Folded into [uiState] so an empty cache + failed
+     * refresh renders as Error (with retry) instead of masquerading as
+     * the "Welcome to Minstrel" empty state.
+     */
+    private val refreshError = MutableStateFlow<String?>(null)
+
    init {
        refresh()
+        // Screen-level auto-recovery (issue #1245): a Home that failed to
+        // load while the server was unreachable re-pulls itself the moment
+        // health returns — same idiom as SyncController, one layer up.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
+        // #968: the daily 03:00 rebuild (and manual refresh) emit
+        // playlist.system_rebuilt; re-pull Home so the system-playlist tiles
+        // and You-might-like rows reflect the new snapshot without a manual
+        // reload. Mirrors the web SSE consumer.
+        viewModelScope.launch {
+            eventsStream.events
+                .filter { it.kind == "playlist.system_rebuilt" }
+                .collect { refresh() }
+        }
    }

    /**
@@ -259,45 +293,9 @@ class HomeViewModel @Inject constructor(
     */
    suspend fun playPlaylist(playlist: PlaylistRef) {
        viewModelScope.launch {
-            val detail = try {
-                withTimeout(PLAYLIST_FETCH_TIMEOUT_MS) {
-                    if (playlist.refreshable && playlist.systemVariant != null) {
-                        playlistsRepository.systemShuffle(playlist.systemVariant)
-                    } else {
-                        playlistsRepository.refreshDetail(playlist.id)
+            playPlaylistShuffled(playlist, playlistsRepository, player) {
+                poolMessages.trySend(it)
            }
-                }
-            } catch (
-                @Suppress("SwallowedException") _: kotlinx.coroutines.TimeoutCancellationException,
-            ) {
-                poolMessages.trySend("Couldn't load playlist - check your connection")
-                return@launch
-            } catch (
-                @Suppress("TooGenericExceptionCaught") e: Throwable,
-            ) {
-                poolMessages.trySend(
-                    "Couldn't load playlist: ${ErrorCopy.fromThrowable(e)}",
-                )
-                return@launch
-            }
-            // Shared with PlaylistDetailViewModel.play - filters out
-            // unplayable rows (missing trackId or empty streamUrl) so the
-            // queue can't end up with tracks Media3 silently rejects.
-            val tracks = detail.tracks.toPlayableTrackRefs()
-            if (tracks.isEmpty()) {
-                poolMessages.trySend("Mix isn't ready yet - try again in a moment")
-                return@launch
-            }
-            // Drift #564: send the BARE systemVariant string, not
-            // "playlist:<variant>" — the server's rotation matcher
-            // (internal/playevents/writer.go systemPlaylistSources)
-            // keys on the bare variant. Web sends the bare form too
-            // (web/src/lib/components/PlaylistCard.svelte:83), so this
-            // brings Android into alignment. Wrong prefix here meant
-            // system-mix plays from Android Home never advanced the
-            // rotation.
-            val source = if (playlist.refreshable) playlist.systemVariant else null
-            player.setQueue(tracks, initialIndex = 0, source = source)
        }.join()
    }

@@ -307,7 +305,14 @@ class HomeViewModel @Inject constructor(
     * actual completion before hiding the indicator.
     */
    fun refresh(): Job = viewModelScope.launch {
-        val home = launch { runCatching { homeRepository.refreshIndex() } }
+        refreshError.value = null
+        val home = launch {
+            // /home/index is the load-bearing pull: its failure drives the
+            // empty-cache Error state. A failure over a populated cache
+            // stays silent — cached sections beat a full-screen error.
+            runCatching { homeRepository.refreshIndex() }
+                .onFailure { refreshError.value = ErrorCopy.fromThrowable(it) }
+        }
        val lists = launch { runCatching { playlistsRepository.refreshList() } }
        val status = launch {
            runCatching { homeRepository.getSystemPlaylistsStatus() }
@@ -322,13 +327,14 @@ class HomeViewModel @Inject constructor(
        combineHomeFlows().asCacheFirstStateFlow(viewModelScope)

    /**
-     * Five home-section flows merged into the sections struct without
-     * playlists; then merged with the playlists flow in [combineHomeFlows].
-     * Splitting it like this keeps each combine call inside the
-     * coroutines built-in arity limit (5) and avoids the typed-vararg
-     * acrobatics needed for a 6-flow combine across heterogeneous types.
+     * The core five section flows merged into the sections struct. Split
+     * out so each combine call stays inside the coroutines built-in arity
+     * limit (5) and avoids the typed-vararg acrobatics a wider combine
+     * across heterogeneous types would need. [observeHomeSections] then
+     * folds in the two you-might-like flows, and [combineHomeFlows] the
+     * playlists flow.
     */
-    private fun observeHomeSections() = combine(
+    private fun observeCoreSections() = combine(
        homeRepository.observeRecentlyAddedAlbums(),
        homeRepository.observeRediscoverAlbums(),
        homeRepository.observeRediscoverArtists(),
@@ -344,10 +350,26 @@ class HomeViewModel @Inject constructor(
        )
    }

+    private fun observeHomeSections() = combine(
+        observeCoreSections(),
+        homeRepository.observeYouMightLikeAlbums(),
+        homeRepository.observeYouMightLikeArtists(),
+    ) { core, ymlAlbums, ymlArtists ->
+        core.copy(youMightLikeAlbums = ymlAlbums, youMightLikeArtists = ymlArtists)
+    }
+
    private fun combineHomeFlows() =
-        observeHomeSections().combine(playlistsRepository.observeAll()) { sections, playlists ->
+        combine(
+            observeHomeSections(),
+            playlistsRepository.observeAll(),
+            refreshError,
+        ) { sections, playlists, err ->
            val merged = sections.copy(playlists = playlists)
-            if (merged.isAllEmpty) UiState.Empty else UiState.Success(merged)
+            when {
+                !merged.isAllEmpty -> UiState.Success(merged)
+                err != null -> UiState.Error(err)
+                else -> UiState.Empty
+            }
        }
 }

@@ -398,9 +420,10 @@ fun HomeScreen(
                            "settings, then come back here for system playlists " +
                            "and recommendations.",
                    )
-                    is UiState.Error -> EmptyState(
+                    is UiState.Error -> ErrorRetry(
                        title = "Couldn't load home",
-                        body = s.message,
+                        message = s.message,
+                        onRetry = { viewModel.refresh() },
                    )
                    is UiState.Success -> HomeSuccessContent(
                        sections = s.data,
@@ -496,6 +519,14 @@ private fun HomeSuccessContent(
                onPlayPlaylist = onPlayPlaylist,
            )
        }
+        youMightLikeSection(
+            albums = sections.youMightLikeAlbums,
+            artists = sections.youMightLikeArtists,
+            onAlbumClick = onAlbumClick,
+            onArtistClick = onArtistClick,
+            onPlayAlbum = onPlayAlbum,
+            onPlayArtist = onPlayArtist,
+        )
        recentlyAddedSection(sections.recentlyAddedAlbums, onAlbumClick, onPlayAlbum)
        rediscoverSection(
            albums = sections.rediscoverAlbums,
@@ -700,6 +731,61 @@ private fun RediscoverBlock(
    }
 }

+/**
+ * "You might like" — in-library albums/artists predicted from the user's
+ * taste that they don't actively spin (server section, daily-built, cold-
+ * start gated). Sits directly under the system-playlists row. Same
+ * albums-then-artists block shape as Rediscover; the artist sub-row drops
+ * its title when an album sub-row precedes it so the two read as one section.
+ */
+private fun LazyListScope.youMightLikeSection(
+    albums: List<HomeTile<AlbumRef>>,
+    artists: List<HomeTile<ArtistRef>>,
+    onAlbumClick: (String) -> Unit,
+    onArtistClick: (String) -> Unit,
+    onPlayAlbum: suspend (String) -> Unit,
+    onPlayArtist: suspend (String) -> Unit,
+) {
+    item {
+        if (albums.isNotEmpty() || artists.isNotEmpty()) {
+            YouMightLikeBlock(
+                albums = albums,
+                artists = artists,
+                onAlbumClick = onAlbumClick,
+                onArtistClick = onArtistClick,
+                onPlayAlbum = onPlayAlbum,
+                onPlayArtist = onPlayArtist,
+            )
+        } else {
+            EmptySection(
+                title = "You might like",
+                body = "We're still learning your taste — keep listening and " +
+                    "picks you might like will show up here.",
+            )
+        }
+    }
+}
+
+@Composable
+private fun YouMightLikeBlock(
+    albums: List<HomeTile<AlbumRef>>,
+    artists: List<HomeTile<ArtistRef>>,
+    onAlbumClick: (String) -> Unit,
+    onArtistClick: (String) -> Unit,
+    onPlayAlbum: suspend (String) -> Unit,
+    onPlayArtist: suspend (String) -> Unit,
+) {
+    Column {
+        if (albums.isNotEmpty()) {
+            AlbumsRow("You might like", albums, onAlbumClick, onPlayAlbum)
+        }
+        if (artists.isNotEmpty()) {
+            val title = if (albums.isEmpty()) "You might like" else ""
+            ArtistsRow(title, artists, onArtistClick, onPlayArtist)
+        }
+    }
+}
+
@Composable
 private fun AlbumsRow(
    title: String,
@@ -739,18 +825,19 @@ private fun PlaylistsRow(
                    icon = iconForPool(item.kind),
                    onClick = { onPlayPool(item.kind) },
                )
-                is PlaylistRowItem.Real -> PlaylistCard(
+                is PlaylistRowItem.Real -> {
+                    // Greyed offline when the tile needs the live server or
+                    // isn't fully cached — dimmed but still tappable into the
+                    // detail to shuffle whatever subset is cached.
+                    val greyed = offline && item.playlist.unavailableOffline
+                    PlaylistCard(
                        playlist = item.playlist,
                        onClick = { onPlaylistClick(item.playlist.id) },
                        onPlay = { onPlayPlaylist(item.playlist) },
-                    // Match Flutter: refreshable system playlists need
-                    // the live server endpoints, so disable their play
-                    // overlay when offline (user can still tap into the
-                    // detail and shuffle all from cache). User playlists
-                    // play from cache + survive offline.
-                    playEnabled = item.playlist.trackCount > 0 &&
-                        !(offline && item.playlist.refreshable),
+                        playEnabled = item.playlist.trackCount > 0 && !greyed,
+                        greyed = greyed,
                    )
+                }
                is PlaylistRowItem.Placeholder -> PlaylistPlaceholderCard(
                    label = item.label,
                    variant = item.variant,
@@ -766,7 +853,7 @@ private fun iconForPool(kind: OfflinePoolKind) = when (kind) {
 }

 /** A cache-backed offline pool, a real playlist tile, or a not-yet-generated slot. */
-private sealed interface PlaylistRowItem {
+internal sealed interface PlaylistRowItem {
    data class OfflinePool(val kind: OfflinePoolKind) : PlaylistRowItem
    data class Real(val playlist: PlaylistRef) : PlaylistRowItem
    data class Placeholder(val label: String, val variant: String) : PlaylistRowItem
@@ -779,55 +866,81 @@ enum class OfflinePoolKind(val label: String) {
 }

 /**
- * Builds the Home Playlists row. When [offline], the two cache-backed
- * pool cards (Recently played, Liked) lead the row. Then For You +
- * Discover + 3× Songs-like fixed slots (real card when generated,
- * placeholder otherwise), then the secondary system kinds (deep cuts /
- * rediscover / new for you / on this day / first listens) when they
- * exist — no placeholders for these since they're conditional on
- * library shape, not guaranteed singletons. Finally user-owned
- * playlists.
+ * Builds the Home Playlists row.
+ *
+ * Online: For You + Discover + 3× Songs-like fixed slots (real card when
+ * generated, placeholder otherwise), then the secondary system kinds (deep cuts
+ * / rediscover / new for you / on this day / first listens) when they exist —
+ * no placeholders for these since they're conditional on library shape — then
+ * user-owned playlists.
+ *
+ * Offline: the two cache-backed pools (Recently played, Liked) lead, then the
+ * same real playlists in curated order but stably partitioned fully-cached
+ * first / greyed after, and the "building/pending" placeholders are dropped
+ * (they need the server to generate, so they're meaningless offline).
 *
 * Diverges from Flutter (`flutter_client/lib/library/home_screen.dart`
 * `_buildPlaylistsRow`) which only shows the 5 fixed slots and never
 * surfaces the secondary kinds on Home. Operator authorized the
 * divergence on 2026-06-01; web UI catch-up tracked as task #53.
 */
-private fun buildPlaylistsRow(
+internal fun buildPlaylistsRow(
    owned: List<PlaylistRef>,
    status: SystemPlaylistsStatus,
    offline: Boolean,
+): List<PlaylistRowItem> {
+    if (!offline) return buildOnlineRow(owned, status)
+    val out = mutableListOf<PlaylistRowItem>(
+        PlaylistRowItem.OfflinePool(OfflinePoolKind.RECENTLY_PLAYED),
+        PlaylistRowItem.OfflinePool(OfflinePoolKind.LIKED),
+    )
+    val (available, greyed) = orderedRealPlaylists(owned).partition { !it.unavailableOffline }
+    (available + greyed).forEach { out += PlaylistRowItem.Real(it) }
+    return out
+}
+
+/** The online layout: fixed system slots (with placeholders), secondary, user. */
+private fun buildOnlineRow(
+    owned: List<PlaylistRef>,
+    status: SystemPlaylistsStatus,
 ): List<PlaylistRowItem> {
    val out = mutableListOf<PlaylistRowItem>()
-    if (offline) {
-        out += PlaylistRowItem.OfflinePool(OfflinePoolKind.RECENTLY_PLAYED)
-        out += PlaylistRowItem.OfflinePool(OfflinePoolKind.LIKED)
-    }
    out += owned.firstOrNull { it.systemVariant == "for_you" }
        ?.let { PlaylistRowItem.Real(it) }
        ?: PlaylistRowItem.Placeholder("For You", variantFor("for-you", status))
    out += owned.firstOrNull { it.systemVariant == "discover" }
        ?.let { PlaylistRowItem.Real(it) }
        ?: PlaylistRowItem.Placeholder("Discover", variantFor("discover", status))
-    val songsLike = owned.filter { it.systemVariant == "songs_like_artist" }.take(3)
+    val songsLike = owned.filter { it.systemVariant == "songs_like_artist" }.take(SONGS_LIKE_SLOTS)
    for (i in 0 until SONGS_LIKE_SLOTS) {
        out += songsLike.getOrNull(i)
            ?.let { PlaylistRowItem.Real(it) }
            ?: PlaylistRowItem.Placeholder("Songs like…", variantFor("songs-like", status))
    }
-    // Secondary system kinds in server-registry order. Only included
-    // when actually generated — these depend on library shape (Deep
-    // cuts needs deep albums, On this day needs prior history, etc.)
-    // so a missing one means "not enough data" rather than "still
-    // building".
    for (variant in SECONDARY_SYSTEM_VARIANTS) {
-        owned.firstOrNull { it.systemVariant == variant }
-            ?.let { out += PlaylistRowItem.Real(it) }
+        owned.firstOrNull { it.systemVariant == variant }?.let { out += PlaylistRowItem.Real(it) }
    }
    owned.filter { it.systemVariant == null }.forEach { out += PlaylistRowItem.Real(it) }
    return out
 }

+/**
+ * Curated real-playlist order (system primaries, then secondary, then user).
+ * Must mirror [buildOnlineRow]'s slot order — the offline row reuses this and
+ * only differs by dropping placeholders + partitioning available-first.
+ */
+private fun orderedRealPlaylists(owned: List<PlaylistRef>): List<PlaylistRef> {
+    val out = mutableListOf<PlaylistRef>()
+    owned.firstOrNull { it.systemVariant == "for_you" }?.let { out += it }
+    owned.firstOrNull { it.systemVariant == "discover" }?.let { out += it }
+    out += owned.filter { it.systemVariant == "songs_like_artist" }.take(SONGS_LIKE_SLOTS)
+    for (variant in SECONDARY_SYSTEM_VARIANTS) {
+        owned.firstOrNull { it.systemVariant == variant }?.let { out += it }
+    }
+    owned.filter { it.systemVariant == null }.forEach { out += it }
+    return out
+}
+
 private fun variantFor(slot: String, s: SystemPlaylistsStatus): String = when {
    s.inFlight -> "building"
    s.lastError != null -> "failed"
@@ -105,6 +105,22 @@ class LibraryRepository @Inject constructor(
    suspend fun fetchArtistTracks(id: String): List<TrackRef> =
        api.getArtistTracks(id).map { it.toDomain() }

+    /**
+     * Pulls related artists for the ArtistDetail "Similar artists"
+     * strip. Network-only — non-critical UI, callers swallow failures
+     * and render nothing rather than blocking the screen.
+     */
+    suspend fun fetchSimilarArtists(id: String): List<ArtistRef> =
+        api.getSimilarArtists(id).map { it.toDomain() }
+
+    /**
+     * Pulls the artist's top tracks for the ArtistDetail "Top tracks"
+     * panel. Network-only; tapping a row plays this exact list as a
+     * queue, so no persistence is needed.
+     */
+    suspend fun fetchArtistTopTracks(id: String): List<TrackRef> =
+        api.getArtistTopTracks(id).map { it.toDomain() }
+
    /**
     * Pulls the album detail (AlbumRef + tracks), persists both, and
     * returns the in-memory snapshot. Lets the AlbumDetail screen
@@ -53,7 +53,7 @@ import com.fabledsword.minstrel.nav.AlbumDetail
 import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.shared.formatDuration
 import com.fabledsword.minstrel.shared.widgets.TrackRow
-import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.ServerImage
@@ -116,9 +116,10 @@ private fun AlbumDetailStateContent(
        when (val s = state) {
            is AlbumDetailUiState.Loading ->
                if (s.seed != null) SeededAlbumLoading(s.seed) else SkeletonTrackList()
-            is AlbumDetailUiState.Error -> EmptyState(
+            is AlbumDetailUiState.Error -> ErrorRetry(
                title = "Couldn't load album",
-                body = s.message,
+                message = s.message,
+                onRetry = { viewModel.refresh() },
            )
            is AlbumDetailUiState.Success -> {
                val albumLiked by viewModel.albumLiked.collectAsStateWithLifecycle()
@@ -5,6 +5,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.toRoute
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.library.data.LibraryRepository
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.models.AlbumDetailRef
@@ -36,6 +38,7 @@ class AlbumDetailViewModel @Inject constructor(
    private val likes: LikesRepository,
    private val player: PlayerController,
    private val seedCache: DetailSeedCache,
+    networkStatus: NetworkStatusController,
    savedStateHandle: SavedStateHandle,
 ) : ViewModel() {

@@ -64,6 +67,14 @@ class AlbumDetailViewModel @Inject constructor(

    init {
        refresh()
+        // Screen-level auto-recovery (issue #1245): a detail that failed to
+        // load while the server was unreachable re-fetches when health
+        // returns, so coming back to the screen shows content, not an error.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AlbumDetailUiState.Error) refresh()
+            }
+        }
    }

    fun refresh(): Job = viewModelScope.launch {
@@ -1,3 +1,5 @@
+@file:Suppress("TooManyFunctions") // Compose screen + private helper composables
+
 package com.fabledsword.minstrel.library.ui

 import androidx.compose.animation.Crossfade
@@ -18,6 +20,7 @@ import androidx.compose.foundation.lazy.grid.GridCells
 import androidx.compose.foundation.lazy.grid.GridItemSpan
 import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
 import androidx.compose.foundation.lazy.grid.items
+import androidx.compose.foundation.lazy.items as lazyItems
 import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.material3.Button
 import androidx.compose.material3.ExperimentalMaterial3Api
@@ -46,21 +49,27 @@ import com.composables.icons.lucide.Lucide
 import com.composables.icons.lucide.Play
 import com.composables.icons.lucide.User
 import com.fabledsword.minstrel.library.widgets.AlbumCard
-import com.fabledsword.minstrel.models.ArtistDetailRef
+import com.fabledsword.minstrel.library.widgets.ArtistCard
 import com.fabledsword.minstrel.models.ArtistRef
+import com.fabledsword.minstrel.models.TrackRef
 import com.fabledsword.minstrel.models.albumCoverPath
 import com.fabledsword.minstrel.nav.AlbumDetail
-import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.nav.ArtistDetail
+import com.fabledsword.minstrel.shared.formatDuration
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
+import com.fabledsword.minstrel.shared.widgets.HorizontalScrollRow
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.ServerImage
 import com.fabledsword.minstrel.shared.widgets.SkeletonAlbumTile
+import com.fabledsword.minstrel.shared.widgets.TrackRow

@OptIn(ExperimentalMaterial3Api::class)
@Composable
 fun ArtistDetailScreen(
    navController: NavHostController,
    viewModel: ArtistDetailViewModel = hiltViewModel(),
+    playerViewModel: com.fabledsword.minstrel.player.ui.PlayerViewModel = hiltViewModel(),
 ) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()
    val snackbarHostState = remember { SnackbarHostState() }
@@ -98,25 +107,38 @@ fun ArtistDetailScreen(
                        } else {
                            SkeletonArtistAlbumsGrid()
                        }
-                    is ArtistDetailUiState.Error -> EmptyState(
+                    is ArtistDetailUiState.Error -> ErrorRetry(
                        title = "Couldn't load artist",
-                        body = s.message,
+                        message = s.message,
+                        onRetry = { viewModel.refresh() },
                    )
-                    is ArtistDetailUiState.Success -> {
-                        val artistLiked by viewModel.artistLiked
-                            .collectAsStateWithLifecycle()
+                    is ArtistDetailUiState.Success ->
+                        ArtistSuccessBody(s, viewModel, playerViewModel, navController)
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun ArtistSuccessBody(
+    state: ArtistDetailUiState.Success,
+    viewModel: ArtistDetailViewModel,
+    playerViewModel: com.fabledsword.minstrel.player.ui.PlayerViewModel,
+    navController: NavHostController,
+) {
+    val artistLiked by viewModel.artistLiked.collectAsStateWithLifecycle()
+    val playerState by playerViewModel.uiState.collectAsStateWithLifecycle()
    ArtistBody(
-                            detail = s.detail,
+        state = state,
        artistLiked = artistLiked,
+        playingTrackId = playerState.currentTrack?.id,
        onPlay = viewModel::playArtist,
        onToggleLike = viewModel::toggleLikeArtist,
        onAlbumClick = { id -> navController.navigate(AlbumDetail(id)) },
+        onTopTrackClick = viewModel::playTopTracks,
+        onSimilarArtistClick = { id -> navController.navigate(ArtistDetail(id)) },
    )
-                    }
-                }
-            }
-        }
-    }
 }

 private fun titleFor(state: ArtistDetailUiState): String = when (state) {
@@ -127,12 +149,16 @@ private fun titleFor(state: ArtistDetailUiState): String = when (state) {

@Composable
 private fun ArtistBody(
-    detail: ArtistDetailRef,
+    state: ArtistDetailUiState.Success,
    artistLiked: Boolean,
+    playingTrackId: String?,
    onPlay: () -> Unit,
    onToggleLike: () -> Unit,
    onAlbumClick: (String) -> Unit,
+    onTopTrackClick: (Int) -> Unit,
+    onSimilarArtistClick: (String) -> Unit,
 ) {
+    val detail = state.detail
    LazyVerticalGrid(
        columns = GridCells.Adaptive(minSize = 176.dp),
        modifier = Modifier.fillMaxSize(),
@@ -149,6 +175,23 @@ private fun ArtistBody(
                onToggleLike = onToggleLike,
            )
        }
+        if (state.topTracks.isNotEmpty()) {
+            item(span = { GridItemSpan(maxLineSpan) }) {
+                TopTracksPanel(
+                    tracks = state.topTracks,
+                    playingTrackId = playingTrackId,
+                    onTrackClick = onTopTrackClick,
+                )
+            }
+        }
+        if (state.similarArtists.isNotEmpty()) {
+            item(span = { GridItemSpan(maxLineSpan) }) {
+                SimilarArtistsStrip(
+                    artists = state.similarArtists,
+                    onArtistClick = onSimilarArtistClick,
+                )
+            }
+        }
        if (detail.albums.isEmpty()) {
            item(span = { GridItemSpan(maxLineSpan) }) {
                EmptyAlbumsHint()
@@ -161,6 +204,67 @@ private fun ArtistBody(
    }
 }

+@Composable
+private fun TopTracksPanel(
+    tracks: List<TrackRef>,
+    playingTrackId: String?,
+    onTrackClick: (Int) -> Unit,
+) {
+    Column(modifier = Modifier.fillMaxWidth()) {
+        Text(
+            text = "Top tracks",
+            style = MaterialTheme.typography.titleLarge,
+            color = MaterialTheme.colorScheme.onBackground,
+            modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
+        )
+        tracks.forEachIndexed { index, track ->
+            TopTrackRow(
+                track = track,
+                nowPlaying = track.id == playingTrackId,
+                onClick = { onTrackClick(index) },
+            )
+        }
+    }
+}
+
+@Composable
+private fun TopTrackRow(
+    track: TrackRef,
+    nowPlaying: Boolean,
+    onClick: () -> Unit,
+) {
+    TrackRow(
+        title = track.title,
+        artist = track.artistName,
+        trackId = track.id,
+        onClick = onClick,
+        nowPlaying = nowPlaying,
+        trailing = {
+            Text(
+                text = formatDuration(track.durationSec, zero = "--:--"),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(start = 12.dp),
+            )
+        },
+    )
+}
+
+@Composable
+private fun SimilarArtistsStrip(
+    artists: List<ArtistRef>,
+    onArtistClick: (String) -> Unit,
+) {
+    HorizontalScrollRow(title = "Similar artists") {
+        lazyItems(items = artists, key = { it.id }) { artist ->
+            ArtistCard(
+                artist = artist,
+                onClick = { onArtistClick(artist.id) },
+            )
+        }
+    }
+}
+
@Composable
 private fun ArtistHeader(
    artist: ArtistRef,
@@ -5,10 +5,13 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.toRoute
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.library.data.LibraryRepository
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.models.ArtistDetailRef
 import com.fabledsword.minstrel.models.ArtistRef
+import com.fabledsword.minstrel.models.TrackRef
 import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.nav.DetailSeedCache
 import com.fabledsword.minstrel.player.PlayerController
@@ -23,13 +26,18 @@ import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.receiveAsFlow
 import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.launch
+import timber.log.Timber
 import javax.inject.Inject

 private const val SHARE_STOP_TIMEOUT_MS = 5_000L

 sealed interface ArtistDetailUiState {
    data class Loading(val seed: ArtistRef? = null) : ArtistDetailUiState
-    data class Success(val detail: ArtistDetailRef) : ArtistDetailUiState
+    data class Success(
+        val detail: ArtistDetailRef,
+        val similarArtists: List<ArtistRef> = emptyList(),
+        val topTracks: List<TrackRef> = emptyList(),
+    ) : ArtistDetailUiState
    data class Error(val message: String) : ArtistDetailUiState
 }

@@ -39,6 +47,7 @@ class ArtistDetailViewModel @Inject constructor(
    private val likes: LikesRepository,
    private val player: PlayerController,
    private val seedCache: DetailSeedCache,
+    networkStatus: NetworkStatusController,
    savedStateHandle: SavedStateHandle,
 ) : ViewModel() {

@@ -63,6 +72,19 @@ class ArtistDetailViewModel @Inject constructor(

    init {
        refresh()
+        // Screen-level auto-recovery (issue #1245). From Error, redo the
+        // whole load; from Success, re-pull just the secondary sections —
+        // their fetch failures are swallowed to emptyList, so a dead zone
+        // during the first load leaves them permanently absent otherwise.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                when (internal.value) {
+                    is ArtistDetailUiState.Error -> refresh()
+                    is ArtistDetailUiState.Success -> loadSecondarySections()
+                    is ArtistDetailUiState.Loading -> Unit
+                }
+            }
+        }
    }

    fun toggleLikeArtist() {
@@ -82,6 +104,7 @@ class ArtistDetailViewModel @Inject constructor(
        try {
            val detail = repository.refreshArtistDetail(artistId)
            internal.value = ArtistDetailUiState.Success(detail)
+            loadSecondarySections()
        } catch (
            @Suppress("TooGenericExceptionCaught") e: Throwable,
        ) {
@@ -89,6 +112,31 @@ class ArtistDetailViewModel @Inject constructor(
        }
    }

+    /**
+     * Pulls the non-critical "Similar artists" + "Top tracks" sections
+     * and folds them into the live Success state. Each failure is
+     * swallowed (logged only) — these sections render absent rather than
+     * blocking, so the core artist view never depends on them.
+     */
+    private suspend fun loadSecondarySections() {
+        val similar = sectionOrEmpty { repository.fetchSimilarArtists(artistId) }
+        val top = sectionOrEmpty { repository.fetchArtistTopTracks(artistId) }
+        val current = internal.value
+        if (current is ArtistDetailUiState.Success) {
+            internal.value = current.copy(similarArtists = similar, topTracks = top)
+        }
+    }
+
+    private inline fun <T> sectionOrEmpty(block: () -> List<T>): List<T> =
+        try {
+            block()
+        } catch (
+            @Suppress("TooGenericExceptionCaught") e: Throwable,
+        ) {
+            Timber.w(e, "Artist secondary section fetch failed for %s", artistId)
+            emptyList()
+        }
+
    /**
     * Pull every track across the artist's albums, shuffle, and start
     * playing. Mirrors Flutter's artist Play button — pressing Play on
@@ -118,4 +166,20 @@ class ArtistDetailViewModel @Inject constructor(
            }
        }
    }
+
+    /**
+     * Plays the loaded "Top tracks" list starting at [index] — the top
+     * tracks are themselves the playable queue (mirrors the web client's
+     * sectionTracks = top-tracks behaviour). No network round-trip; the
+     * list is already in the Success state.
+     */
+    fun playTopTracks(index: Int) {
+        val tracks = (internal.value as? ArtistDetailUiState.Success)?.topTracks.orEmpty()
+        if (tracks.isEmpty()) return
+        player.setQueue(
+            tracks = tracks,
+            initialIndex = index.coerceIn(0, tracks.lastIndex),
+            source = "artist-top:$artistId",
+        )
+    }
 }
@@ -24,11 +24,17 @@ class LibraryViewModel @Inject constructor(
        combine(
            repository.observeArtists(),
            repository.observeAlbums(),
-        ) { artists, albums ->
-            if (artists.isEmpty() && albums.isEmpty()) {
-                UiState.Empty
-            } else {
+            syncController.lastSyncError,
+        ) { artists, albums, syncError ->
+            when {
+                artists.isNotEmpty() || albums.isNotEmpty() ->
                    UiState.Success(LibraryData(artists, albums))
+                // Empty cache + failed sync is a load failure, not an empty
+                // library — surface it so the user gets a Retry instead of
+                // the welcome copy. Heals automatically: SyncController
+                // re-syncs on health recovery, clearing lastSyncError.
+                syncError != null -> UiState.Error(syncError)
+                else -> UiState.Empty
            }
        }
            .asCacheFirstStateFlow(viewModelScope)
@@ -25,6 +25,9 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.NavHostController
+import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.library.widgets.AlbumCard
 import com.fabledsword.minstrel.library.widgets.ArtistCard
@@ -38,6 +41,7 @@ import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.asCacheFirstStateFlow
 import com.fabledsword.minstrel.shared.widgets.TrackRow
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.HorizontalScrollRow
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
@@ -46,6 +50,7 @@ import com.fabledsword.minstrel.shared.widgets.TrackCoverThumb
 import com.fabledsword.minstrel.shared.widgets.trackactions.TrackActionsButton
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.launch
@@ -68,14 +73,25 @@ data class LikedSections(
 class LikedTabViewModel @Inject constructor(
    private val repository: LikesRepository,
    private val player: PlayerController,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

+    /** Copy for the most recent refresh failure; null once one succeeds. */
+    private val refreshError = MutableStateFlow<String?>(null)
+
    init {
        refresh()
+        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // health returns, so a load that failed offline heals unprompted.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
    }

    fun refresh(): Job = viewModelScope.launch {
+        refreshError.value = null
        runCatching { repository.refreshIds() }
+            .onFailure { refreshError.value = ErrorCopy.fromThrowable(it) }
    }

    /**
@@ -92,9 +108,16 @@ class LikedTabViewModel @Inject constructor(
        repository.observeLikedArtists(),
        repository.observeLikedAlbums(),
        repository.observeLikedTracks(),
-    ) { artists, albums, tracks ->
+        refreshError,
+    ) { artists, albums, tracks, err ->
        val sections = LikedSections(artists, albums, tracks)
-        if (sections.isAllEmpty) UiState.Empty else UiState.Success(sections)
+        when {
+            !sections.isAllEmpty -> UiState.Success(sections)
+            // Empty cache + failed refresh is a load failure, not "no
+            // likes yet" — surface Error so the user gets a Retry.
+            err != null -> UiState.Error(err)
+            else -> UiState.Empty
+        }
    }.asCacheFirstStateFlow(viewModelScope)

    /**
@@ -130,9 +153,10 @@ fun LikedTab(
                body = "Tap the heart on an artist, album, or track to start " +
                    "building your liked collection.",
            )
-            is UiState.Error -> EmptyState(
+            is UiState.Error -> ErrorRetry(
                title = "Couldn't load likes",
-                body = s.message,
+                message = s.message,
+                onRetry = { viewModel.refresh() },
            )
            is UiState.Success -> LikedContent(
                sections = s.data,
@@ -20,6 +20,8 @@ data class PlaylistRef(
    val trackCount: Int = 0,
    val coverUrl: String = "",
    val ownerUsername: String = "",
+    /** All member tracks resident in the audio cache — playable fully offline. */
+    val fullyCached: Boolean = false,
 ) {
    val isSystem: Boolean get() = systemVariant != null

@@ -30,6 +32,13 @@ data class PlaylistRef(
     * expose a refresh trigger; rebuilds are scheduler-driven).
     */
    val refreshable: Boolean get() = isSystem && systemVariant != "songs_like_artist"
+
+    /**
+     * Can't be relied on while offline — either it needs the live server to
+     * (re)generate (a refreshable system mix) or not all its tracks are cached.
+     * Callers combine this with the current offline state to grey the tile.
+     */
+    val unavailableOffline: Boolean get() = refreshable || !fullyCached
 }

 /**
@@ -16,4 +16,11 @@ data class UserRef(
    val id: String,
    val username: String,
    val isAdmin: Boolean = false,
+    /**
+     * Account-level diagnostics opt-in (M9). NOT present in the login
+     * response (that's the narrow UserView) — populated by the /api/me
+     * refresh in AuthController so a remote admin flip reaches the
+     * device. Default false until the first refresh.
+     */
+    val debugModeEnabled: Boolean = false,
 )
@@ -1,5 +1,9 @@
+@file:OptIn(ExperimentalSerializationApi::class)
+
 package com.fabledsword.minstrel.models.wire

+import kotlinx.serialization.EncodeDefault
+import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable

@@ -15,7 +19,11 @@ import kotlinx.serialization.Serializable

@Serializable
 data class PlayStartedRequest(
-    val type: String = "play_started",
+    // Discriminator MUST stay on the wire. The app's Json has
+    // encodeDefaults=false, so without this a `type` left at its
+    // default is omitted entirely and the server 400s the event as
+    // "unknown event type" — silently dropping every native play.
+    @EncodeDefault(EncodeDefault.Mode.ALWAYS) val type: String = "play_started",
    @SerialName("track_id") val trackId: String,
    @SerialName("client_id") val clientId: String,
    val source: String? = null,
@@ -28,21 +36,21 @@ data class PlayStartedResponse(

@Serializable
 data class PlayEndedRequest(
-    val type: String = "play_ended",
+    @EncodeDefault(EncodeDefault.Mode.ALWAYS) val type: String = "play_ended",
    @SerialName("play_event_id") val playEventId: String,
    @SerialName("duration_played_ms") val durationPlayedMs: Long,
 )

@Serializable
 data class PlaySkippedRequest(
-    val type: String = "play_skipped",
+    @EncodeDefault(EncodeDefault.Mode.ALWAYS) val type: String = "play_skipped",
    @SerialName("play_event_id") val playEventId: String,
    @SerialName("position_ms") val positionMs: Long,
 )

@Serializable
 data class PlayOfflineRequest(
-    val type: String = "play_offline",
+    @EncodeDefault(EncodeDefault.Mode.ALWAYS) val type: String = "play_offline",
    @SerialName("track_id") val trackId: String,
    @SerialName("client_id") val clientId: String,
    val at: String,
@@ -15,8 +15,12 @@ import kotlinx.serialization.Serializable
 *   - rediscoverArtists    → artist
 *   - mostPlayedTracks     → track
 *   - lastPlayedArtists    → artist
+ *   - youMightLikeAlbums   → album
+ *   - youMightLikeArtists  → artist
 *
- * All slices default to empty so missing keys don't throw on decode.
+ * All slices default to empty so missing keys don't throw on decode —
+ * which also keeps the client safe against older servers that don't
+ * emit the you-might-like sections yet.
 */
@Serializable
 data class HomeIndexWire(
@@ -25,4 +29,6 @@ data class HomeIndexWire(
    @SerialName("rediscover_artists") val rediscoverArtists: List<String> = emptyList(),
    @SerialName("most_played_tracks") val mostPlayedTracks: List<String> = emptyList(),
    @SerialName("last_played_artists") val lastPlayedArtists: List<String> = emptyList(),
+    @SerialName("you_might_like_albums") val youMightLikeAlbums: List<String> = emptyList(),
+    @SerialName("you_might_like_artists") val youMightLikeArtists: List<String> = emptyList(),
 )
@@ -18,4 +18,5 @@ data class MyProfileWire(
    @SerialName("display_name") val displayName: String? = null,
    val email: String? = null,
    @SerialName("is_admin") val isAdmin: Boolean = false,
+    @SerialName("debug_mode_enabled") val debugModeEnabled: Boolean = false,
 )
@@ -58,40 +58,78 @@ class AudioPrefetcher @Inject constructor(
    private val activeJobs = mutableMapOf<String, Job>()
    private val mutex = Mutex()

+    private data class ReconcileInput(
+        val queue: List<Pair<String, String>>,
+        val index: Int,
+        val window: Int,
+        val isPlaying: Boolean,
+    )
+
    init {
        scope.launch {
            combine(
                playerController.uiState.map { it.queue.map { t -> t.id to t.streamUrl } },
                playerController.uiState.map { it.queueIndex },
                authStore.cacheSettings.map { it.prefetchWindow },
-            ) { queue, index, window -> Triple(queue, index, window) }
+                playerController.uiState.map { it.isPlaying },
+            ) { queue, index, window, isPlaying ->
+                ReconcileInput(queue, index, window, isPlaying)
+            }
                .distinctUntilChanged()
-                .collect { (queue, index, window) -> reconcile(queue, index, window) }
+                .collect { input ->
+                    reconcile(input.queue, input.index, input.window, input.isPlaying)
+                }
        }
    }

+    /**
+     * Apply the prefetch window to the current queue.
+     *
+     * Cancellation of out-of-window jobs always runs -- a queue mutation
+     * or skip should free bandwidth from stale prefetches immediately.
+     * Starting new prefetches is gated on [isPlaying]: until the current
+     * track is actually playing, every byte of upstream bandwidth should
+     * land on it, not on upcoming-track prefetches. Without this gate a
+     * cold start fanned out 4-6 concurrent CacheWriter jobs against the
+     * same OkHttp client as the playback DataSource and the user waited
+     * ~25 s for the first audio to start; with the gate the current
+     * track gets the full pipe to its first STATE_READY, then the
+     * prefetcher fills in the next window.
+     */
    private suspend fun reconcile(
        queue: List<Pair<String, String>>,
        index: Int,
        window: Int,
+        isPlaying: Boolean,
    ) {
        mutex.withLock {
-            if (index < 0 || queue.isEmpty() || window <= 0) {
+            val targets = computeTargets(queue, index, window)
+            if (targets.isEmpty()) {
                cancelAllLocked()
                return
            }
-            // Exclude the currently-playing track (it's loaded by the
-            // player itself) and walk `window` tracks forward.
-            val firstIdx = (index + 1).coerceAtMost(queue.size)
-            val lastIdx = (index + window).coerceAtMost(queue.size - 1)
-            if (firstIdx > lastIdx) {
-                cancelAllLocked()
-                return
-            }
-            val targets = queue.subList(firstIdx, lastIdx + 1)
            val targetIds = targets.mapTo(mutableSetOf()) { it.first }
+            // Cancellation always runs so a queue mutation or skip frees
+            // the pipe immediately, even while paused.
+            cancelOutOfWindowLocked(targetIds)
+            if (isPlaying) startInWindowLocked(targets)
+        }
+    }

-            // Cancel jobs for tracks that have slid out of the window.
+    private fun computeTargets(
+        queue: List<Pair<String, String>>,
+        index: Int,
+        window: Int,
+    ): List<Pair<String, String>> {
+        // Exclude the currently-playing track (it's loaded by the player
+        // itself) and walk `window` tracks forward.
+        val firstIdx = index + 1
+        val lastIdx = (index + window).coerceAtMost(queue.size - 1)
+        val isValid = index >= 0 && queue.isNotEmpty() && window > 0 && firstIdx <= lastIdx
+        return if (isValid) queue.subList(firstIdx, lastIdx + 1) else emptyList()
+    }
+
+    private fun cancelOutOfWindowLocked(targetIds: Set<String>) {
        activeJobs.entries
            .filter { it.key !in targetIds }
            .toList()
@@ -99,10 +137,12 @@ class AudioPrefetcher @Inject constructor(
                job.cancel()
                activeJobs.remove(id)
            }
+    }

-            // Start prefetches for new arrivals. Skip blank URLs (these
-            // come from minimal TrackRefs synthesized from playlist rows
-            // when the upstream track was removed from the library).
+    private fun startInWindowLocked(targets: List<Pair<String, String>>) {
+        // Skip blank URLs (these come from minimal TrackRefs synthesized
+        // from playlist rows when the upstream track was removed from
+        // the library).
        for ((trackId, streamUrl) in targets) {
            if (trackId in activeJobs || streamUrl.isBlank()) continue
            val job = scope.launch(Dispatchers.IO) {
@@ -112,7 +152,6 @@ class AudioPrefetcher @Inject constructor(
            activeJobs[trackId] = job
        }
    }
-    }

    private fun cancelAllLocked() {
        activeJobs.values.forEach { it.cancel() }
@@ -0,0 +1,77 @@
+package com.fabledsword.minstrel.player
+
+import android.content.Context
+import android.net.wifi.WifiManager
+import android.os.Build
+import android.os.PowerManager
+import timber.log.Timber
+
+/**
+ * Holds a WiFi + CPU wake lock for the lifetime of an active UPnP cast.
+ *
+ * While casting, the wrapped ExoPlayer is paused, so its automatic
+ * `WAKE_MODE_NETWORK` locks are released and nothing keeps the phone's radio
+ * awake. On a locked, on-battery phone the WiFi enters power-save within
+ * seconds and the CPU dozes; that stalls the 1 Hz liveness poll to the
+ * renderer and the queue-extend calls to the server. The poll then trips the
+ * drop threshold and playback falls back to a phone that *also* has no
+ * network — silence, while the renderer was streaming fine the whole time.
+ *
+ * A high-performance / low-latency [WifiManager.WifiLock] keeps the radio out
+ * of power-save, and a partial [PowerManager.WakeLock] keeps the poll
+ * coroutine scheduled. Both are acquired when a route goes active and released
+ * the moment it drops or the user switches back to the phone.
+ *
+ * All methods are idempotent (`setReferenceCounted(false)` + held-checks) and
+ * synchronized, so they are safe to call from any thread.
+ */
+class CastNetworkLock(context: Context) {
+
+    private val appContext = context.applicationContext
+
+    private val wifiLock: WifiManager.WifiLock? =
+        (appContext.getSystemService(Context.WIFI_SERVICE) as? WifiManager)
+            ?.createWifiLock(wifiLockMode(), LOCK_TAG)
+            ?.apply { setReferenceCounted(false) }
+
+    private val wakeLock: PowerManager.WakeLock? =
+        (appContext.getSystemService(Context.POWER_SERVICE) as? PowerManager)
+            ?.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, LOCK_TAG)
+            ?.apply { setReferenceCounted(false) }
+
+    @Synchronized
+    fun acquire() {
+        runCatching { wifiLock?.takeUnless { it.isHeld }?.acquire() }
+            .onFailure { Timber.w(it, "CastNetworkLock: wifi acquire failed") }
+        runCatching { wakeLock?.takeUnless { it.isHeld }?.acquire() }
+            .onFailure { Timber.w(it, "CastNetworkLock: wake acquire failed") }
+        Timber.w(
+            "CastNetworkLock acquired (wifi=%s wake=%s)",
+            wifiLock?.isHeld, wakeLock?.isHeld,
+        )
+    }
+
+    @Synchronized
+    fun release() {
+        runCatching { wifiLock?.takeIf { it.isHeld }?.release() }
+            .onFailure { Timber.w(it, "CastNetworkLock: wifi release failed") }
+        runCatching { wakeLock?.takeIf { it.isHeld }?.release() }
+            .onFailure { Timber.w(it, "CastNetworkLock: wake release failed") }
+        Timber.w("CastNetworkLock released")
+    }
+
+    private companion object {
+        const val LOCK_TAG = "minstrel:upnp-cast"
+
+        // WIFI_MODE_FULL_LOW_LATENCY (API 29+) both disables power-save and
+        // lowers latency; FULL_HIGH_PERF is the pre-Q equivalent for keeping
+        // the radio fully awake.
+        fun wifiLockMode(): Int =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+                WifiManager.WIFI_MODE_FULL_LOW_LATENCY
+            } else {
+                @Suppress("DEPRECATION")
+                WifiManager.WIFI_MODE_FULL_HIGH_PERF
+            }
+    }
+}
@@ -0,0 +1,640 @@
+@file:Suppress("TooManyFunctions") // Mirrors Player surface: ~16 methods is the API.
+
+package com.fabledsword.minstrel.player
+
+import android.os.Handler
+import android.os.SystemClock
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.ProcessLifecycleOwner
+import androidx.media3.common.ForwardingPlayer
+import androidx.media3.common.MediaItem
+import androidx.media3.common.Player
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.player.output.ActiveUpnp
+import com.fabledsword.minstrel.player.output.ActiveUpnpHolder
+import com.fabledsword.minstrel.player.output.upnp.SoapFaultException
+import com.fabledsword.minstrel.player.output.upnp.TransportState
+import java.io.IOException
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.selects.onTimeout
+import kotlinx.coroutines.selects.select
+import timber.log.Timber
+
+/**
+ * Integration point for UPnP transport parity. Wraps the local
+ * ExoPlayer; every transport method either forwards (local route
+ * active -- the default) or translates into AVTransport SOAP +
+ * [RemotePlayerState] updates (UPnP route active).
+ *
+ * Created inside [MinstrelPlayerService]; runs on the service's main
+ * looper. Network SOAP calls fire on [Dispatchers.IO]. While UPnP is
+ * active, the MediaSession's reads of [Player.isPlaying] and
+ * [Player.getCurrentPosition] pull from [RemotePlayerState]; the
+ * wrapped ExoPlayer stays paused at the position it had when the
+ * route was selected.
+ *
+ * Drop heuristic: the 1 Hz poll loop is the *sole* arbiter of route
+ * liveness -- [RemotePlayerState.recordPollFailure]'s rolling threshold
+ * (DROP_THRESHOLD consecutive failures) fires [onDrop]. A failed transport
+ * command (play/pause/seek/next) does NOT drop on its own: a locked phone's
+ * WiFi power-save can stall a single command's socket I/O for a second or
+ * two while the renderer is perfectly reachable, so commands retry on
+ * transient IO failure and otherwise defer to the poll loop. The factory
+ * wraps the [onDrop] callback into a SharedFlow consumed by the NowPlaying
+ * surface as a snackbar.
+ *
+ * Queue mode: OutputPickerController loads the full queue into Sonos's
+ * native queue via ClearQueue + AddURIToQueue, then points the
+ * transport at x-rincon-queue:<udn>#0. Skip/prev/seekTo delegate to
+ * AVTransport Next/Previous/SeekToTrack so Sonos manages gap-free
+ * advance natively. PollLoop syncs the local cursor by comparing the
+ * 1-based Track index from GetPositionInfo.
+ */
+class MinstrelForwardingPlayer(
+    private val delegate: Player,
+    private val holder: ActiveUpnpHolder,
+    private val remoteState: RemotePlayerState,
+    private val castNetworkLock: CastNetworkLock,
+    private val networkStatus: NetworkStatusController,
+    private val onDrop: (routeName: String) -> Unit,
+) : ForwardingPlayer(delegate) {
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+    private val handler = Handler(delegate.applicationLooper)
+    private var pollJob: Job? = null
+
+    // Tracks consecutive non-PLAYING poll observations so a single transient
+    // PAUSED_PLAYBACK / STOPPED tick during a Sonos track transition does not
+    // flip the play/pause button. Manual pause still feels instant because it
+    // bypasses the poll entirely via applyTransportPaused().
+    @Volatile private var nonPlayingPollStreak = 0
+
+    // Wall-clock of the most-recent within-track seek we issued to Sonos.
+    // pollOnce uses this to suppress position overwrites for SEEK_ACK_WINDOW_MS
+    // -- Sonos can take 1-2s to apply a Seek, and a poll landing inside that
+    // window reports the *old* position. Without the lockout the scrubber
+    // visibly jumps backwards immediately after a drag, then forwards again.
+    @Volatile private var lastSeekIssuedAtMs: Long = 0L
+
+    // Wake channel for the poll loop. requestImmediatePoll() trySend's a Unit;
+    // pollLoop's select{} races the delay against this channel so the next
+    // pollOnce can fire immediately instead of waiting up to POLL_INTERVAL_MS.
+    // Used on activity resume (ProcessLifecycleOwner.ON_RESUME) so the UI
+    // catches up to Sonos within RTT rather than the full poll cadence.
+    // CONFLATED so repeated trySend's between polls don't queue up.
+    private val pollTrigger = Channel<Unit>(Channel.CONFLATED)
+
+    // External Player.Listener registry (separate from super.addListener which
+    // forwards to the wrapped ExoPlayer). The wrapped player is paused with
+    // no audio loaded while UPnP is active, so it never fires events for our
+    // synthesized remote state -- the MediaSession's notification card and
+    // lock-screen scrubber stay frozen on whatever state was last captured
+    // before UPnP took over. We dual-register: super.addListener keeps the
+    // listener attached to the delegate (so local-playback events still
+    // reach it), AND we hold a ref here so we can directly invoke listener
+    // callbacks on remote-state changes. The listener's read of isPlaying /
+    // duration / position then routes through our overrides to remoteState.
+    private val externalListeners = mutableListOf<Player.Listener>()
+
+    @Volatile private var lastNotifiedIsPlaying: Boolean = false
+    @Volatile private var lastNotifiedTrackIdx: Int = -1
+
+    private val lifecycleObserver = object : DefaultLifecycleObserver {
+        override fun onResume(owner: LifecycleOwner) {
+            pollTrigger.trySend(Unit)
+        }
+    }
+
+    init {
+        scope.launch {
+            holder.active.collect { active -> onActiveChanged(active) }
+        }
+        scope.launch {
+            // When the phone's own network recovers, reconcile a held cast
+            // session immediately instead of waiting up to POLL_INTERVAL_MS:
+            // the renderer kept playing, so one round-trip re-confirms it and
+            // resyncs the cursor/position. Only a transition *into* Healthy
+            // while a route is active matters.
+            var prev = networkStatus.state.value
+            networkStatus.state.collect { next ->
+                if (next == ServerHealth.Healthy && prev != ServerHealth.Healthy && isRemote()) {
+                    pollTrigger.trySend(Unit)
+                }
+                prev = next
+            }
+        }
+        // Process lifecycle is observed on the main thread; ProcessLifecycleOwner's
+        // addObserver requires it. The observer just trySend's to the channel.
+        handler.post {
+            ProcessLifecycleOwner.get().lifecycle.addObserver(lifecycleObserver)
+        }
+    }
+
+    private fun isRemote(): Boolean = holder.active.value != null
+
+    /**
+     * Returns true when selectUpnp has marked a UPnP route as the intended
+     * target but loadQueueOnSonos hasn't yet wired ActiveUpnp. During this
+     * window we drop transport commands silently -- they would hit Sonos's
+     * stale state from a prior session and trigger restarts.
+     */
+    private fun isLoadingUpnp(): Boolean =
+        holder.target.value != null && holder.active.value == null
+
+    // ─── setMediaItems intercepts ──────────────────────────────────────
+    // When PlayerController.setQueue replaces the queue while Sonos is the
+    // active route, the wrapped delegate's queue gets the new items but
+    // Sonos's native queue still holds the OLD tracks -- and the play()
+    // that PlayerController fires immediately after setMediaItems would
+    // resume the old Sonos queue (user reported on-device: "player view
+    // updates but Sonos queue does not"). We clear active + set target
+    // synchronously here so the next play() in the same IPC sequence
+    // drops via isLoadingUpnp() = true; the OutputPickerController
+    // observes the uiState.queue change and runs the resync (re-clears
+    // Sonos's native queue + AddURIToQueue the new tracks + Play).
+
+    override fun setMediaItems(mediaItems: List<MediaItem>) {
+        super.setMediaItems(mediaItems)
+        markPendingResyncIfRemote()
+    }
+
+    override fun setMediaItems(mediaItems: List<MediaItem>, resetPosition: Boolean) {
+        super.setMediaItems(mediaItems, resetPosition)
+        markPendingResyncIfRemote()
+    }
+
+    override fun setMediaItems(mediaItems: List<MediaItem>, startIndex: Int, startPositionMs: Long) {
+        super.setMediaItems(mediaItems, startIndex, startPositionMs)
+        markPendingResyncIfRemote()
+    }
+
+    private fun markPendingResyncIfRemote() {
+        val wasActive = holder.active.value ?: return
+        Timber.w(
+            "setMediaItems while UPnP active (%s) -- marking pending resync",
+            wasActive.routeName,
+        )
+        holder.set(null)
+        holder.setTarget(wasActive.routeId)
+    }
+
+    override fun play() {
+        if (isLoadingUpnp()) {
+            Timber.w("ForwardingPlayer.play() dropped -- UPnP loading")
+            return
+        }
+        val active = holder.active.value
+        Timber.w("ForwardingPlayer.play() active=%s", active?.routeName)
+        if (active == null) {
+            super.play()
+        } else {
+            remoteState.setPlayIntent(true)
+            scope.launch {
+                runCatching { retryTransport { active.avTransport.play() } }
+                    .onSuccess {
+                        remoteState.applyTransportPlaying()
+                        notifyRemoteStateChanged()
+                    }
+                    .onFailure { handleTransportFailure(active, it) }
+            }
+        }
+    }
+
+    override fun pause() {
+        if (isLoadingUpnp()) {
+            Timber.w("ForwardingPlayer.pause() dropped -- UPnP loading")
+            return
+        }
+        val active = holder.active.value
+        Timber.w("ForwardingPlayer.pause() active=%s", active?.routeName)
+        if (active == null) {
+            super.pause()
+        } else {
+            remoteState.setPlayIntent(false)
+            scope.launch {
+                runCatching { retryTransport { active.avTransport.pause() } }
+                    .onSuccess {
+                        remoteState.applyTransportPaused()
+                        notifyRemoteStateChanged()
+                    }
+                    .onFailure { handleTransportFailure(active, it) }
+            }
+        }
+    }
+
+    override fun seekTo(positionMs: Long) {
+        if (isLoadingUpnp()) {
+            Timber.w("ForwardingPlayer.seekTo(positionMs) dropped -- UPnP loading")
+            return
+        }
+        val active = holder.active.value
+        Timber.w("ForwardingPlayer.seekTo(%dms) active=%s", positionMs, active?.routeName)
+        if (active == null) {
+            super.seekTo(positionMs)
+        } else {
+            lastSeekIssuedAtMs = SystemClock.elapsedRealtime()
+            remoteState.applyPositionInfo(
+                positionMs = positionMs,
+                durationMs = remoteState.durationMs,
+                trackUri = remoteState.currentTrackUri,
+                trackNumber = remoteState.trackNumber,
+            )
+            scope.launch {
+                runCatching { retryTransport { active.avTransport.seek(positionMs) } }
+                    .onFailure { handleTransportFailure(active, it) }
+            }
+        }
+    }
+
+    /**
+     * Widget-driven track change (user taps a track in the queue widget).
+     * Seeks Sonos to the correct queue slot, then seeks within-track if
+     * [positionMs] is non-zero.
+     */
+    override fun seekTo(mediaItemIndex: Int, positionMs: Long) {
+        if (isLoadingUpnp()) {
+            Timber.w("ForwardingPlayer.seekTo(idx, positionMs) dropped -- UPnP loading")
+            return
+        }
+        val active = holder.active.value
+        Timber.w(
+            "ForwardingPlayer.seekTo(idx=%d, %dms) active=%s",
+            mediaItemIndex, positionMs, active?.routeName,
+        )
+        if (active == null) {
+            super.seekTo(mediaItemIndex, positionMs)
+            return
+        }
+        super.seekTo(mediaItemIndex, positionMs)
+        remoteState.beginPendingTransport(
+            SystemClock.elapsedRealtime() + PENDING_TRANSPORT_SAFETY_TIMEOUT_MS,
+        )
+        scope.launch {
+            runCatching {
+                retryTransport {
+                    active.avTransport.seekToTrack(mediaItemIndex + 1)
+                    if (positionMs > 0L) {
+                        active.avTransport.seek(positionMs)
+                    }
+                }
+            }.onFailure { handleTransportFailure(active, it) }
+        }
+    }
+
+    override fun seekToNextMediaItem() {
+        if (isLoadingUpnp()) {
+            Timber.w("ForwardingPlayer.seekToNextMediaItem() dropped -- UPnP loading")
+            return
+        }
+        val active = holder.active.value
+        Timber.w("ForwardingPlayer.seekToNextMediaItem() active=%s", active?.routeName)
+        if (active == null) {
+            super.seekToNextMediaItem()
+            return
+        }
+        // Super first for immediate local cursor advance (UI feedback);
+        // then delegate to Sonos Next. PollLoop reconciles cursor via
+        // Track index if they diverge.
+        super.seekToNextMediaItem()
+        remoteState.beginPendingTransport(
+            SystemClock.elapsedRealtime() + PENDING_TRANSPORT_SAFETY_TIMEOUT_MS,
+        )
+        scope.launch {
+            runCatching { retryTransport { active.avTransport.next() } }
+                .onFailure { handleTransportFailure(active, it) }
+        }
+    }
+
+    override fun seekToPreviousMediaItem() {
+        if (isLoadingUpnp()) {
+            Timber.w("ForwardingPlayer.seekToPreviousMediaItem() dropped -- UPnP loading")
+            return
+        }
+        val active = holder.active.value
+        Timber.w("ForwardingPlayer.seekToPreviousMediaItem() active=%s", active?.routeName)
+        if (active == null) {
+            super.seekToPreviousMediaItem()
+            return
+        }
+        // Super first for immediate local cursor advance (UI feedback);
+        // then delegate to Sonos Previous. PollLoop reconciles.
+        super.seekToPreviousMediaItem()
+        remoteState.beginPendingTransport(
+            SystemClock.elapsedRealtime() + PENDING_TRANSPORT_SAFETY_TIMEOUT_MS,
+        )
+        scope.launch {
+            runCatching { retryTransport { active.avTransport.previous() } }
+                .onFailure { handleTransportFailure(active, it) }
+        }
+    }
+
+    override fun getCurrentPosition(): Long =
+        if (isRemote()) remoteState.positionMs else super.getCurrentPosition()
+
+    override fun getDuration(): Long =
+        if (isRemote()) remoteState.durationMs else super.getDuration()
+
+    override fun isPlaying(): Boolean =
+        if (isRemote()) remoteState.isPlaying else super.isPlaying()
+
+    override fun getPlaybackState(): Int =
+        if (isRemote()) Player.STATE_READY else super.getPlaybackState()
+
+    // Mirror remote state so any consumer that gates on playWhenReady --
+    // notably MediaSessionService's foreground-keepalive checks and our own
+    // onTaskRemoved -- sees the remote renderer as the source of truth.
+    // Without this, swiping the app away with Sonos playing would stop the
+    // service, kill the poll loop, and leave Sonos orphaned.
+    override fun getPlayWhenReady(): Boolean =
+        if (isRemote()) remoteState.isPlaying else super.getPlayWhenReady()
+
+    override fun addListener(listener: Player.Listener) {
+        super.addListener(listener)
+        synchronized(externalListeners) { externalListeners.add(listener) }
+    }
+
+    override fun removeListener(listener: Player.Listener) {
+        super.removeListener(listener)
+        synchronized(externalListeners) { externalListeners.remove(listener) }
+    }
+
+    /**
+     * Direct-invoke the externally-registered Player.Listeners so the
+     * MediaSession's PlaybackState publisher (notification card, lock-screen
+     * scrubber, BT/AVRCP, Auto, Wear OS tile) re-reads our overridden state.
+     * The listeners then query isPlaying / getDuration / getCurrentPosition,
+     * all of which route through to remoteState while UPnP is active.
+     *
+     * Posted to the player's application looper because Player.Listener
+     * callbacks contract on the application thread.
+     */
+    private fun notifyRemoteStateChanged() {
+        if (!isRemote()) return
+        val playing = remoteState.isPlaying
+        val trackIdx = (remoteState.trackNumber - 1).coerceAtLeast(0)
+        val isPlayingChanged = playing != lastNotifiedIsPlaying
+        val trackChanged = trackIdx != lastNotifiedTrackIdx
+        if (!isPlayingChanged && !trackChanged) return
+        lastNotifiedIsPlaying = playing
+        lastNotifiedTrackIdx = trackIdx
+        val snapshot = synchronized(externalListeners) { externalListeners.toList() }
+        handler.post {
+            for (l in snapshot) {
+                if (isPlayingChanged) {
+                    l.onIsPlayingChanged(playing)
+                    l.onPlaybackStateChanged(Player.STATE_READY)
+                }
+                if (trackChanged) {
+                    val item = if (trackIdx < delegate.mediaItemCount) {
+                        delegate.getMediaItemAt(trackIdx)
+                    } else {
+                        null
+                    }
+                    l.onMediaItemTransition(item, Player.MEDIA_ITEM_TRANSITION_REASON_AUTO)
+                }
+            }
+        }
+    }
+
+    override fun release() {
+        pollJob?.cancel()
+        scope.cancel()
+        handler.post {
+            ProcessLifecycleOwner.get().lifecycle.removeObserver(lifecycleObserver)
+        }
+        super.release()
+    }
+
+    /**
+     * Run a transport SOAP block, retrying transport-level (IO) failures a
+     * few times with backoff. A locked phone's WiFi power-save can stall the
+     * first socket I/O for a second or two; a retry lets the command land once
+     * WiFi wakes instead of being abandoned. A [SoapFaultException] (the
+     * renderer answered and rejected the action) is NOT retried -- the device
+     * is alive and retrying won't change its verdict.
+     */
+    private suspend fun <T> retryTransport(block: suspend () -> T): T =
+        retryTransientIo(TRANSPORT_RETRY_ATTEMPTS, TRANSPORT_RETRY_BACKOFF_MS, block)
+
+    /**
+     * A transport SOAP command failed even after retries. Deliberately does
+     * NOT declare the route dropped: the 1 Hz poll loop is the single arbiter
+     * of liveness (DROP_THRESHOLD consecutive poll failures). A locked phone's
+     * WiFi power-save can fail one command while the renderer is perfectly
+     * reachable; dropping on a single command falsely kicked playback back to
+     * the phone. We log, leave the poll loop running, and nudge an immediate
+     * poll so the UI reconciles to Sonos's actual state -- if the renderer is
+     * truly gone, the poll loop trips the drop on its own.
+     */
+    private fun handleTransportFailure(active: ActiveUpnp, t: Throwable) {
+        if (t is SoapFaultException) {
+            Timber.w(t, "UPnP transport rejected by %s -- device alive, no drop", active.routeName)
+        } else {
+            Timber.w(t, "UPnP transport failed on %s -- poll loop arbitrates", active.routeName)
+        }
+        pollTrigger.trySend(Unit)
+    }
+
+    private fun onActiveChanged(active: ActiveUpnp?) {
+        pollJob?.cancel()
+        nonPlayingPollStreak = 0
+        // Reset notify cache so the first poll after a route flip republishes
+        // playing/track state to the MediaSession even if it happens to match
+        // the prior session's values numerically.
+        lastNotifiedIsPlaying = false
+        lastNotifiedTrackIdx = -1
+        if (active != null) {
+            Timber.w("UPnP active: %s -- pollLoop starting", active.routeName)
+            // Hold the WiFi + CPU awake for the cast: the wrapped ExoPlayer is
+            // about to be paused (releasing its WAKE_MODE_NETWORK locks), so
+            // without this the radio power-saves on a locked screen and the
+            // poll below starves -- see [CastNetworkLock].
+            castNetworkLock.acquire()
+            // Pause the wrapped ExoPlayer so we are not playing local audio
+            // simultaneously with the remote renderer. handler.post targets the
+            // application looper, so this runs on the same thread that processes
+            // our override calls -- no race with the pause() override branching
+            // to SOAP (holder.active is already non-null by the time this post
+            // fires, but delegate.pause() bypasses the override entirely).
+            handler.post { delegate.pause() }
+            pollJob = scope.launch { pollLoop(active) }
+        } else {
+            castNetworkLock.release()
+            remoteState.reset()
+        }
+    }
+
+    @OptIn(ExperimentalCoroutinesApi::class) // onTimeout / select.onReceive
+    private suspend fun pollLoop(active: ActiveUpnp) {
+        var networkDropSuppressed = false
+        while (scope.isActive && holder.active.value?.routeId == active.routeId) {
+            val outcome = runCatching { pollOnce(active) }
+            if (outcome.isSuccess) {
+                remoteState.recordPollSuccess()
+                networkDropSuppressed = false
+            } else if (remoteState.recordPollFailure()) {
+                if (networkStatus.state.value == ServerHealth.Healthy) {
+                    Timber.w("UPnP drop threshold tripped for %s", active.routeName)
+                    handler.post { onDrop(active.routeName) }
+                    return
+                }
+                networkDropSuppressed = suppressDropForNetwork(active, networkDropSuppressed)
+            }
+            // Race the normal cadence against any external wake (activity
+            // resume). Whichever wins continues to the next pollOnce.
+            select<Unit> {
+                onTimeout(POLL_INTERVAL_MS) {}
+                pollTrigger.onReceive {}
+            }
+        }
+    }
+
+    /**
+     * The poll-failure threshold tripped, but the phone's *own* network is down
+     * (state is not [ServerHealth.Healthy]) -- so this is "we can't see the
+     * renderer right now," not "the renderer died." A UPnP renderer streams
+     * autonomously and is almost certainly still playing; meanwhile a local
+     * fallback couldn't reach the server either, so dropping would only blast
+     * local audio out of a pocketed phone while the speaker keeps going. Hold
+     * the route and keep polling -- a successful poll once the network returns
+     * reconciles to the renderer's real state. Clear the failure streak so
+     * recovery re-evaluates the renderer from scratch instead of re-dropping on
+     * the first post-recovery hiccup. Returns the (latched) suppression flag so
+     * the rationale logs once per outage, not every tick.
+     */
+    private fun suppressDropForNetwork(active: ActiveUpnp, alreadySuppressed: Boolean): Boolean {
+        if (!alreadySuppressed) {
+            Timber.w(
+                "UPnP drop suppressed for %s -- phone network %s, holding route",
+                active.routeName, networkStatus.state.value,
+            )
+        }
+        remoteState.recordPollSuccess() // clear streak; not a renderer failure
+        return true
+    }
+
+    /**
+     * One poll tick: read position + transport state from Sonos, apply to
+     * [remoteState], and forward-sync the local cursor to Sonos's Track
+     * index when not in queue load.
+     *
+     * Cursor sync is gated on `holder.target == null` (= not loading)
+     * because during load Sonos reports Track=1 while we're still
+     * appending, and syncing would race the SetAV+Seek that lands
+     * after. Outside load, forward sync catches Sonos auto-advances
+     * (queue end-of-track), Sonos-app driven Next presses, and any
+     * drift after a brief poll-failure burst that didn't trip the
+     * drop threshold. Forward-only because a Next override we just
+     * issued can race with a poll still reporting the prior Track --
+     * the next poll catches up safely.
+     */
+    private suspend fun pollOnce(active: ActiveUpnp) {
+        val info = active.avTransport.getPositionInfo()
+        val now = SystemClock.elapsedRealtime()
+        val inSeekAckWindow = lastSeekIssuedAtMs > 0L &&
+            (now - lastSeekIssuedAtMs) < SEEK_ACK_WINDOW_MS
+        // Inside the seek-ack window, keep the optimistic position we wrote in
+        // seekTo -- the poll's reported position is stale until Sonos finishes
+        // processing the Seek SOAP. Other fields still refresh from the poll.
+        remoteState.applyPositionInfo(
+            positionMs = if (inSeekAckWindow) remoteState.positionMs else info.relTimeMs,
+            durationMs = info.trackDurationMs,
+            trackUri = info.trackUri,
+            trackNumber = info.track,
+        )
+        maybeSyncLocalCursor(info.track)
+        val transport = active.avTransport.getTransportInfo()
+        when (transport.state) {
+            TransportState.PLAYING -> {
+                nonPlayingPollStreak = 0
+                remoteState.applyTransportPlaying()
+            }
+            TransportState.PAUSED -> {
+                nonPlayingPollStreak += 1
+                if (nonPlayingPollStreak >= NON_PLAYING_CONFIRM) {
+                    remoteState.applyTransportPaused()
+                }
+            }
+            TransportState.STOPPED -> {
+                nonPlayingPollStreak += 1
+                if (nonPlayingPollStreak >= NON_PLAYING_CONFIRM) {
+                    remoteState.applyTransportStopped()
+                }
+            }
+            TransportState.TRANSITIONING, TransportState.UNKNOWN -> Unit
+        }
+        notifyRemoteStateChanged()
+    }
+
+    private fun maybeSyncLocalCursor(sonosTrack: Int) {
+        if (holder.target.value != null) return
+        if (sonosTrack <= 0) return
+        val sonosIdx = sonosTrack - 1
+        handler.post {
+            val localIdx = delegate.currentMediaItemIndex
+            if (sonosIdx > localIdx && sonosIdx < delegate.mediaItemCount) {
+                Timber.w(
+                    "UPnP cursor catch-up: local=%d -> sonos=%d",
+                    localIdx, sonosIdx,
+                )
+                delegate.seekTo(sonosIdx, 0L)
+            }
+        }
+    }
+
+    private companion object {
+        const val POLL_INTERVAL_MS = 1_000L
+        const val NON_PLAYING_CONFIRM = 2
+        const val SEEK_ACK_WINDOW_MS = 2_000L
+        // Safety upper bound on how long the polling tick will wait for
+        // Sonos to ack a user transport. The common case clears event-driven
+        // when Sonos's reported Track matches the wrapped player; this only
+        // kicks in if SOAP fails or Sonos drops the ack entirely.
+        const val PENDING_TRANSPORT_SAFETY_TIMEOUT_MS = 5_000L
+        // Transport commands retry transient IO failures so a single WiFi
+        // power-save stall (locked phone) doesn't abandon the command. 3
+        // attempts x the SoapClient's 2s connect timeout + backoff bounds the
+        // worst case at ~7s; a still-failing command then defers to the poll.
+        const val TRANSPORT_RETRY_ATTEMPTS = 3
+        const val TRANSPORT_RETRY_BACKOFF_MS = 400L
+    }
+}
+
+/**
+ * Retry [block] on transient transport-level ([IOException]) failures, with
+ * [backoffMs] between attempts, up to [attempts] total. Anything that is not
+ * an [IOException] -- notably [SoapFaultException], where the renderer
+ * answered and rejected the action -- propagates immediately: the device is
+ * alive, so retrying won't change its verdict. Extracted from
+ * [MinstrelForwardingPlayer] so a locked phone's WiFi power-save stall doesn't
+ * abandon a single transport command (the bug that falsely reverted Sonos
+ * playback to local audio).
+ */
+internal suspend fun <T> retryTransientIo(
+    attempts: Int,
+    backoffMs: Long,
+    block: suspend () -> T,
+): T {
+    var attempt = 0
+    while (true) {
+        try {
+            return block()
+        } catch (io: IOException) {
+            attempt += 1
+            if (attempt >= attempts) throw io
+            Timber.w(io, "transient transport failure (attempt %d) -- retrying", attempt)
+            delay(backoffMs)
+        }
+    }
+}
@@ -72,11 +72,12 @@ class MinstrelPlayerService : MediaSessionService() {

    override fun onCreate() {
        super.onCreate()
-        val player = playerFactory.build()
+        val player: Player = playerFactory.build()
        val callback = LikeMediaCallback(likesRepository, serviceScope)
        val session = MediaSession.Builder(this, player)
            .setSessionActivity(buildNowPlayingPendingIntent())
            .setCallback(callback)
+            .setBitmapLoader(playerFactory.buildBitmapLoader())
            .setMediaButtonPreferences(ImmutableList.of(buildLikeButton(isLiked = false)))
            .build()
        mediaSession = session
@@ -176,7 +177,11 @@ class MinstrelPlayerService : MediaSessionService() {

    override fun onTaskRemoved(rootIntent: Intent?) {
        val player = mediaSession?.player ?: return super.onTaskRemoved(rootIntent)
-        val activelyPlaying = player.playWhenReady && player.playbackState != Player.STATE_ENDED
+        // player.isPlaying is overridden on MinstrelForwardingPlayer to return
+        // remoteState.isPlaying while UPnP is active, so a swipe-away with
+        // Sonos playing keeps the service (and its UPnP poll loop) alive.
+        val activelyPlaying = player.isPlaying ||
+            (player.playWhenReady && player.playbackState != Player.STATE_ENDED)
        if (!activelyPlaying) {
            stopSelf()
        }
@@ -0,0 +1,78 @@
+package com.fabledsword.minstrel.player
+
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
+import androidx.media3.datasource.TransferListener
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import java.io.IOException
+import java.io.InterruptedIOException
+
+/**
+ * DataSource wrapper that fails the network read immediately when
+ * [NetworkStatusController] reports a gating state. CacheDataSource only
+ * calls this upstream factory on cache misses, so playback of cached audio is
+ * unaffected -- only "tap a non-cached track while offline" hits this branch
+ * and gets a fast, meaningful error instead of a multi-second network timeout
+ * (which then surfaced as a silent decode failure to the user).
+ *
+ * Wrapping rather than substituting the OkHttp data source lets the cache
+ * write path remain intact for when health returns and we DO want to fetch:
+ * we keep the same upstream all the time, just gate `open()`.
+ */
+class OfflineGatedDataSource(
+    private val delegate: DataSource,
+    private val health: NetworkStatusController,
+) : DataSource {
+
+    override fun open(dataSpec: DataSpec): Long {
+        gateOnHealth()
+        return try {
+            val opened = delegate.open(dataSpec)
+            health.reportSuccess() // bytes flowing from the server == reachable
+            opened
+        } catch (e: IOException) {
+            health.reportFailure() // real network read failed → arbitrate via /healthz
+            throw e
+        }
+    }
+
+    /** Fast-fail before touching the network when the server can't be reached. */
+    private fun gateOnHealth() {
+        when (health.state.value) {
+            ServerHealth.Offline -> throw OfflineException(
+                "Track not in the on-device cache and the device is offline.",
+            )
+            ServerHealth.ServerDown -> throw OfflineException(
+                "Track not in the on-device cache and the Minstrel server is unreachable.",
+            )
+            // Unstable is non-gating: still try the network. Healthy too.
+            ServerHealth.Unstable, ServerHealth.Healthy -> Unit
+        }
+    }
+
+    override fun close() = delegate.close()
+    override fun getUri() = delegate.uri
+    override fun read(buffer: ByteArray, offset: Int, length: Int): Int =
+        delegate.read(buffer, offset, length)
+    override fun addTransferListener(transferListener: TransferListener) =
+        delegate.addTransferListener(transferListener)
+    override fun getResponseHeaders() = delegate.responseHeaders
+}
+
+class OfflineGatedDataSourceFactory(
+    private val upstream: DataSource.Factory,
+    private val health: NetworkStatusController,
+) : DataSource.Factory {
+    override fun createDataSource(): DataSource =
+        OfflineGatedDataSource(upstream.createDataSource(), health)
+}
+
+/**
+ * Signals the audio-source error path that the request was denied because the
+ * device is offline / the server is unreachable. ExoPlayer's [androidx.media3
+ * .common.PlaybackException] catches it via [InterruptedIOException]'s
+ * `IOException` ancestor and surfaces it as a SOURCE error, which then flows
+ * through the existing [PlaybackErrorReporter] -> snackbar path.
+ */
+class OfflineException(message: String) : IOException(message)
@@ -6,6 +6,7 @@ import androidx.lifecycle.ProcessLifecycleOwner
 import com.fabledsword.minstrel.api.endpoints.EventsApi
 import com.fabledsword.minstrel.auth.AuthStore
 import com.fabledsword.minstrel.cache.mutations.MutationQueue
+import com.fabledsword.minstrel.cache.mutations.PlayEndedPayload
 import com.fabledsword.minstrel.cache.mutations.PlayOfflinePayload
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.models.wire.PlayEndedRequest
@@ -64,11 +65,24 @@ class PlayEventsReporter @Inject constructor(
    private var curLastPositionMs: Long = 0
    private var curDurationMs: Long = 0

+    // Whether the currently-tracked play is actively playing (vs paused).
+    // onStop reads this: a backgrounded play that's still playing is left
+    // to the live path (the foreground service keeps us alive), while a
+    // paused one is durably closed so a kill can't orphan its open row.
+    private var curPlaying: Boolean = false
+
    // Server play_event_id when the live play_started succeeded;
    // null if start failed/offline — then the close is captured into
    // the offline mutation queue instead of a live ended/skipped.
    private var openPlayEventId: String? = null

+    // True from beginTrack until startLive's play_started resolves. When a
+    // close races an in-flight start (id still null), the server row is
+    // being created but we've lost its id — we must NOT also enqueue an
+    // offline play (that would duplicate); the server auto-closes the
+    // orphan on the next play_started instead.
+    private var startInFlight: Boolean = false
+
    private var prevTrackId: String? = null

    init {
@@ -95,7 +109,7 @@ class PlayEventsReporter @Inject constructor(
    ) {
        // Track-change → close the prior tracked play.
        if (trackId != prevTrackId && curTrackId != null) {
-            closeCurrent(viaOffline = false)
+            closeCurrent()
        }

        // Entered playing for a new track → begin tracking it.
@@ -110,6 +124,7 @@ class PlayEventsReporter @Inject constructor(
        if (curTrackId != null && trackId == curTrackId) {
            curLastPositionMs = positionMs
            if (durationMs > 0) curDurationMs = durationMs
+            curPlaying = playing
        }

        prevTrackId = trackId
@@ -121,12 +136,18 @@ class PlayEventsReporter @Inject constructor(
        curSource = source
        curLastPositionMs = 0
        curDurationMs = durationMs
+        curPlaying = true
        openPlayEventId = null
+        startInFlight = true
        startLive(trackId = trackId, source = source)
    }

    private fun startLive(trackId: String, source: String?) {
-        val cid = resolveClientId() ?: return
+        val cid = resolveClientId()
+        if (cid == null) {
+            startInFlight = false
+            return
+        }
        scope.launch {
            try {
                val response = api.playStarted(
@@ -144,47 +165,61 @@ class PlayEventsReporter @Inject constructor(
            ) {
                // Offline / flaky — openPlayEventId stays null; close
                // path will enqueue the completed play for replay.
+            } finally {
+                startInFlight = false
            }
        }
    }

-    private fun closeCurrent(viaOffline: Boolean) {
+    /**
+     * Closes the tracked play. Routes by whether the server already has an
+     * open row, NOT by caller context — this is what keeps background /
+     * track-change / failure paths from each minting a second row:
+     *  - open server row (id) → close it by id; on failure enqueue a durable
+     *    close-by-id (never an offline play).
+     *  - start in flight (no id yet) → leave it; the server auto-closes the
+     *    orphan on the next play_started. Enqueuing offline here would
+     *    duplicate the in-flight row.
+     *  - no server row at all → record the whole play offline.
+     *
+     * Always uses the actual position played; the server's skip rule
+     * (50%/30s defaults) classifies was_skipped from it.
+     */
+    private fun closeCurrent() {
        val trackId = curTrackId
        val startedAt = curStartedAt
        if (trackId == null || startedAt == null) {
            resetCurrent()
            return
        }
-        // Always send the actual position played to; the server's
-        // skip rule (50%/30s defaults, configurable) classifies
-        // was_skipped from this. If the track ran to completion the
-        // last observed position is ~= duration, which gives ratio ~1
-        // and the server records a non-skip. The COMPLETION_TOLERANCE
-        // rounding the prior shape did is no longer needed — the
-        // server's threshold is the source of truth.
        val durationMs = curLastPositionMs
        val source = curSource
        val id = openPlayEventId
+        val inFlight = startInFlight
+        when {
+            id != null -> closeById(id, durationMs)
+            inFlight -> Unit
+            else -> enqueueOffline(trackId, startedAt, source, durationMs)
+        }
+        resetCurrent()
+    }

-        if (!viaOffline && id != null) {
+    private fun closeById(id: String, durationMs: Long) {
        scope.launch {
            try {
                api.playEnded(
-                        PlayEndedRequest(
-                            playEventId = id,
-                            durationPlayedMs = durationMs,
-                        ),
+                    PlayEndedRequest(playEventId = id, durationPlayedMs = durationMs),
                )
            } catch (
                @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
            ) {
-                    enqueueOffline(trackId, startedAt, source, durationMs)
+                // Durable close-by-id (idempotent server-side) — survives a
+                // process kill without orphaning the open row or duplicating.
+                mutationQueue.enqueuePlayEnded(
+                    PlayEndedPayload(playEventId = id, durationPlayedMs = durationMs),
+                )
            }
        }
-        } else {
-            enqueueOffline(trackId, startedAt, source, durationMs)
-        }
-        resetCurrent()
    }

    private fun resetCurrent() {
@@ -193,7 +228,9 @@ class PlayEventsReporter @Inject constructor(
        curSource = null
        curLastPositionMs = 0
        curDurationMs = 0
+        curPlaying = false
        openPlayEventId = null
+        startInFlight = false
    }

    private fun enqueueOffline(
@@ -232,8 +269,17 @@ class PlayEventsReporter @Inject constructor(
    // ── Lifecycle: durable-close on app background / detach ────────

    override fun onStop(owner: LifecycleOwner) {
-        if (curTrackId != null) {
-            closeCurrent(viaOffline = true)
+        // App backgrounded. If the tracked play is still PLAYING, leave it
+        // alone: the foreground media service keeps the process — and this
+        // app-scope uiState collector — alive, so the live state machine
+        // closes the play accurately on the next real track change. Closing
+        // here (the old always-offline behavior) raced the collector's
+        // re-begin and minted a duplicate, skip-misclassified row on every
+        // screen-lock. Only durably close a PAUSED play, where no further
+        // progress will happen and a process kill would otherwise orphan the
+        // open server row. See docs/superpowers/2026-06-11 contract audit.
+        if (curTrackId != null && !curPlaying) {
+            closeCurrent()
        }
    }
 }
@@ -1,5 +1,6 @@
 package com.fabledsword.minstrel.player

+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.di.ApplicationScope
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.channels.Channel
@@ -40,6 +41,7 @@ private const val DEBOUNCE_MS = 2_000L
 class PlaybackErrorReporter @Inject constructor(
    private val playerController: PlayerController,
    private val repository: PlaybackErrorRepository,
+    private val networkStatus: NetworkStatusController,
    @ApplicationScope private val scope: CoroutineScope,
 ) {
    private val outChannel = Channel<String>(Channel.BUFFERED)
@@ -52,6 +54,10 @@ class PlaybackErrorReporter @Inject constructor(
            val buffer = mutableListOf<String>()
            var debounceJob: kotlinx.coroutines.Job? = null
            playerController.playbackErrorEvents.collect { event ->
+                // A track failing to play is ambiguous (dead server vs. one bad
+                // file) — let the controller arbitrate via /healthz. No-op when
+                // already Offline; cheap otherwise.
+                networkStatus.reportFailure()
                // Fire-and-forget the server report — repository handles
                // success/queue branching so callers don't see throws.
                scope.launch { repository.report(event) }
@@ -5,6 +5,8 @@ import android.content.Context
 import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
+import android.os.SystemClock
+import androidx.core.net.toUri
 import androidx.media3.common.MediaItem
 import androidx.media3.common.MediaMetadata
 import androidx.media3.common.Player
@@ -12,6 +14,8 @@ import androidx.media3.session.MediaController
 import androidx.media3.session.SessionToken
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.models.TrackRef
+import com.fabledsword.minstrel.playlists.data.PlaylistsRepository
+import com.fabledsword.minstrel.playlists.data.toPlayableTrackRefs
 import com.fabledsword.minstrel.shared.resolveServerUrl
 import dagger.hilt.android.qualifiers.ApplicationContext
 import kotlinx.coroutines.CoroutineScope
@@ -20,8 +24,10 @@ import kotlinx.coroutines.channels.Channel
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharedFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.receiveAsFlow
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
@@ -59,7 +65,18 @@ class PlayerController @Inject constructor(
    @ApplicationContext private val context: Context,
    @ApplicationScope private val scope: CoroutineScope,
    private val radio: RadioController,
+    private val playlists: PlaylistsRepository,
+    private val playerFactory: PlayerFactory,
+    private val activeUpnpHolder: com.fabledsword.minstrel.player.output.ActiveUpnpHolder,
+    private val remoteState: RemotePlayerState,
 ) {
+
+    /**
+     * UPnP drop events surfaced from [PlayerFactory.dropEvents]. NowPlaying
+     * collects this into its snackbar host so a transport / poll failure
+     * during UPnP playback shows "Disconnected from <name>" to the user.
+     */
+    val dropEvents: SharedFlow<String> = playerFactory.dropEvents
    private val sessionToken =
        SessionToken(context, ComponentName(context, MinstrelPlayerService::class.java))

@@ -97,6 +114,13 @@ class PlayerController @Inject constructor(
     */
    private var lastEvaluatedItemIndex: Int = -1

+    /**
+     * #968: self-heal budget — re-pulls of a stale refreshable queue since
+     * the last successful play. Capped so a still-broken refresh can't loop;
+     * reset when any track loads with real audio.
+     */
+    private var selfHealAttempts = 0
+
    /**
     * Stable queue snapshot kept in sync with the player's MediaItems —
     * the player's own getMediaItem(index) returns Media3 types; we keep
@@ -130,11 +154,24 @@ class PlayerController @Inject constructor(

    // ── Transport (no-op until the controller is connected) ──────────────

-    fun play() { mediaController?.play() }
-    fun pause() { mediaController?.pause() }
-    fun seekTo(positionMs: Long) { mediaController?.seekTo(positionMs) }
-    fun skipToNext() { mediaController?.seekToNextMediaItem() }
-    fun skipToPrevious() { mediaController?.seekToPreviousMediaItem() }
+    // Each transport call must run on the MediaController's
+    // applicationLooper; calling from a background coroutine throws
+    // IllegalStateException (see PlayerController.setQueue's note).
+    // UI tap handlers are already on Main so the in-place branch hits;
+    // the background path only fires for cross-thread callers like
+    // OutputPickerController.selectUpnp (which calls pause() after
+    // handing playback off to a UPnP renderer).
+    fun play() { mediaController?.let { runOnControllerThread(it) { it.play() } } }
+    fun pause() { mediaController?.let { runOnControllerThread(it) { it.pause() } } }
+    fun seekTo(positionMs: Long) {
+        mediaController?.let { runOnControllerThread(it) { it.seekTo(positionMs) } }
+    }
+    fun skipToNext() {
+        mediaController?.let { runOnControllerThread(it) { it.seekToNextMediaItem() } }
+    }
+    fun skipToPrevious() {
+        mediaController?.let { runOnControllerThread(it) { it.seekToPreviousMediaItem() } }
+    }

    /** Flip shuffle on/off. Media3 emits onEvents → uiState reflects. */
    fun toggleShuffle() {
@@ -165,6 +202,20 @@ class PlayerController @Inject constructor(
        controller.play()
    }

+    /**
+     * Align the local cursor to [index] + [positionMs] WITHOUT auto-playing.
+     * Used by the UPnP adopt path: when attaching to a renderer that's already
+     * playing our queue, we sync the local cursor to the renderer's current
+     * track/position so skip/seek and the UI map onto its live session — the
+     * renderer keeps the audio, the local player stays paused. Unlike
+     * [seekToIndex] this issues no play().
+     */
+    fun moveCursorTo(index: Int, positionMs: Long) {
+        val controller = mediaController ?: return
+        if (index !in queueRefs.indices) return
+        runOnControllerThread(controller) { controller.seekTo(index, positionMs) }
+    }
+
    /**
     * Replace the queue with [tracks] starting at [initialIndex].
     * [source] tags the queue with its origin (e.g. "for_you") so the
@@ -299,10 +350,23 @@ class PlayerController @Inject constructor(
     * and advance past the dead track. Otherwise no-op.
     */
    private fun handleZeroDurationIfNeeded(controller: MediaController, idx: Int) {
-        val current = queueRefs.getOrNull(idx) ?: return
+        // Skip during UPnP playback (active) AND during the activation load
+        // window (target set, active not yet wired). ExoPlayer is intentionally
+        // paused throughout both windows so its STATE_READY duration is always
+        // 0 / TIME_UNSET -- without this guard we rapid-advance through the
+        // entire local queue (and spam /api/playback-errors).
+        val current = queueRefs.getOrNull(idx)
+        val upnpEngaged = activeUpnpHolder.active.value != null ||
+            activeUpnpHolder.target.value != null
+        if (current == null || upnpEngaged) return
        val duration = controller.duration
        val isZeroDuration = duration <= 0L || duration == androidx.media3.common.C.TIME_UNSET
-        if (!isZeroDuration) return
+        if (!isZeroDuration) {
+            // A track loaded with real audio — clear the self-heal budget so
+            // a later stale queue can recover again.
+            selfHealAttempts = 0
+            return
+        }
        playbackErrorEventsChannel.trySend(
            PlaybackErrorEvent(
                trackId = current.id,
@@ -318,6 +382,58 @@ class PlayerController @Inject constructor(
        }
    }

+    /**
+     * #968: the queue is fully unplayable (every track failed to load). If it
+     * came from a refreshable source — a system playlist (bare-variant source)
+     * or radio ("radio:<seed>") — the snapshot is probably stale (app/tab left
+     * open across the daily rebuild); re-pull it and resume instead of stopping.
+     * Bounded by [selfHealAttempts]. Album / artist / user-playlist / offline
+     * sources have nothing to refresh — stop.
+     */
+    private fun selfHealOrStop(controller: MediaController) {
+        val source = controller.currentMediaItem
+            ?.mediaMetadata?.extras?.getString(MINSTREL_SOURCE_KEY)
+        if (source == null || selfHealAttempts >= MAX_SELF_HEAL_ATTEMPTS) {
+            controller.stop()
+            return
+        }
+        when {
+            source.startsWith("radio:") -> {
+                selfHealAttempts++
+                scope.launch { selfHealRadio(source.removePrefix("radio:")) }
+            }
+            !source.contains(':') -> { // bare variant = refreshable system playlist
+                selfHealAttempts++
+                scope.launch { selfHealSystem(source) }
+            }
+            else -> controller.stop()
+        }
+    }
+
+    private suspend fun selfHealSystem(variant: String) {
+        val refs = runCatching { playlists.systemShuffle(variant).tracks.toPlayableTrackRefs() }
+            .getOrDefault(emptyList())
+        if (refs.isEmpty()) {
+            stopOnControllerThread()
+            return
+        }
+        setQueue(refs, initialIndex = 0, source = variant)
+    }
+
+    private suspend fun selfHealRadio(seedTrackId: String) {
+        val refs = runCatching { radio.seed(seedTrackId) }.getOrDefault(emptyList())
+        if (refs.isEmpty()) {
+            stopOnControllerThread()
+            return
+        }
+        setQueue(refs, initialIndex = 0, source = "radio:$seedTrackId")
+    }
+
+    private fun stopOnControllerThread() {
+        val controller = mediaController ?: return
+        runOnControllerThread(controller) { controller.stop() }
+    }
+
    // ── Internal: async connect + Listener-driven UI state sync ──────────

    private suspend fun connectAndObserve() {
@@ -341,6 +457,19 @@ class PlayerController @Inject constructor(
        // awaitReady, the Player.Listener is wired too.
        if (!readyDeferred.isCompleted) readyDeferred.complete(Unit)
        startPositionPolling(controller)
+        // Keep isUpnpLoading current between player-event fires: holder state
+        // changes (setTarget / set(active)) are independent of Media3 events, so
+        // onEvents alone would lag behind by up to one event cycle. This collector
+        // runs for the process lifetime alongside the position poller.
+        scope.launch {
+            combine(
+                activeUpnpHolder.target,
+                activeUpnpHolder.active,
+            ) { target, active -> target != null && active == null }
+                .collect { isLoading ->
+                    uiStateInternal.value = uiStateInternal.value.copy(isUpnpLoading = isLoading)
+                }
+        }
        controller.addListener(
            object : Player.Listener {
                override fun onPlayerError(error: androidx.media3.common.PlaybackException) {
@@ -355,6 +484,17 @@ class PlayerController @Inject constructor(
                            detail = error.message,
                        ),
                    )
+                    // A failed load leaves the player IDLE; advance past the bad
+                    // track and re-prepare so one unplayable item doesn't strand
+                    // playback (mirrors the zero_duration skip). At the end of a
+                    // fully-unplayable queue, try to self-heal a stale refreshable
+                    // source before stopping.
+                    if (controller.hasNextMediaItem()) {
+                        controller.seekToNextMediaItem()
+                        controller.prepare()
+                    } else {
+                        selfHealOrStop(controller)
+                    }
                }

                override fun onMediaItemTransition(
@@ -364,6 +504,11 @@ class PlayerController @Inject constructor(
                    // Reset the per-item evaluation guard so the new
                    // item's STATE_READY transition gets a fresh check.
                    lastEvaluatedItemIndex = -1
+                    // The track flipped -- re-anchor the position interpolator
+                    // so the next polling tick treats the new track's
+                    // remoteState.positionMs as fresh rather than carrying the
+                    // old anchor + elapsed forward.
+                    lastSeenRemotePositionMs = -1L
                }

                override fun onPlaybackStateChanged(playbackState: Int) {
@@ -381,15 +526,38 @@ class PlayerController @Inject constructor(
                        ?.mediaMetadata
                        ?.extras
                        ?.getString(MINSTREL_SOURCE_KEY)
+                    val isUpnpLoading = activeUpnpHolder.target.value != null &&
+                        activeUpnpHolder.active.value == null
+                    // When UPnP is active, the wrapped ExoPlayer is paused with
+                    // no real audio loaded -- player.duration / isPlaying /
+                    // currentPosition all reflect that. Read from remoteState
+                    // instead so an onEvents fire (e.g. activity resume) doesn't
+                    // clobber the UI with zeros. Duration falls back to the
+                    // wrapped player's value when Sonos hasn't reported one yet
+                    // (pre-first-poll window, or Sonos still buffering) -- the
+                    // wrapped ExoPlayer was prepared with the same MediaItem so
+                    // it knows the real duration before any SOAP poll lands.
+                    val upnpActive = activeUpnpHolder.active.value != null
                    uiStateInternal.value =
                        PlayerUiState(
                            currentTrack = current,
                            queue = queueRefs,
                            queueIndex = idx,
-                            isPlaying = player.isPlaying,
-                            isBuffering = player.playbackState == Player.STATE_BUFFERING,
-                            positionMs = player.currentPosition.coerceAtLeast(0),
-                            durationMs = player.duration.coerceAtLeast(0),
+                            isPlaying = if (upnpActive) remoteState.isPlaying else player.isPlaying,
+                            isBuffering = !upnpActive &&
+                                player.playbackState == Player.STATE_BUFFERING,
+                            positionMs = if (upnpActive) {
+                                remoteState.positionMs
+                            } else {
+                                player.currentPosition
+                            }.coerceAtLeast(0),
+                            durationMs = effectiveDuration(
+                                upnpActive,
+                                remoteState.durationMs,
+                                player.duration,
+                                desiredIdx = idx,
+                                controllerIdx = idx,
+                            ),
                            bufferedPositionMs = player.bufferedPosition.coerceAtLeast(0),
                            playbackError = player.playerError?.message,
                            currentSource = source,
@@ -399,6 +567,7 @@ class PlayerController @Inject constructor(
                                Player.REPEAT_MODE_ONE -> RepeatMode.ONE
                                else -> RepeatMode.OFF
                            },
+                            isUpnpLoading = isUpnpLoading,
                        )
                }
            },
@@ -423,15 +592,138 @@ class PlayerController @Inject constructor(
        scope.launch(Dispatchers.Main.immediate) {
            while (isActive) {
                delay(POSITION_POLL_INTERVAL_MS)
-                if (!controller.isPlaying) continue
-                uiStateInternal.value = uiStateInternal.value.copy(
-                    positionMs = controller.currentPosition.coerceAtLeast(0),
-                    bufferedPositionMs = controller.bufferedPosition.coerceAtLeast(0),
+                tickPositionPoll(controller)
+            }
+        }
+    }
+
+    /**
+     * One position-polling tick. Owns track-change detection too: when UPnP
+     * is active and the wrapped ExoPlayer is paused, `delegate.seekTo` from
+     * `maybeSyncLocalCursor` may not fire `onMediaItemTransition`, leaving
+     * uiState.queueIndex stuck on the old track even after Sonos has
+     * advanced. So the tick reads Sonos's reported Track as the source of
+     * truth, rebuilds the index/title fields itself, and force-syncs the
+     * wrapped player as defense in depth.
+     */
+    private fun tickPositionPoll(controller: MediaController) {
+        val upnpActive = activeUpnpHolder.active.value != null
+        resolvePendingTransport(controller, upnpActive)
+        val pendingTransport = upnpActive && remoteState.pendingTransportDeadlineMs > 0L
+        val effectiveIsPlaying =
+            if (upnpActive) remoteState.isPlaying else controller.isPlaying
+        val effectivePosition = if (upnpActive) {
+            interpolatedRemotePosition(effectiveIsPlaying)
+        } else {
+            controller.currentPosition
+        }
+        val desiredIdx = desiredQueueIndex(controller, upnpActive)
+        val current = uiStateInternal.value
+        val newPos = effectivePosition.coerceAtLeast(0)
+        val newDur = effectiveDuration(
+            upnpActive,
+            remoteState.durationMs,
+            controller.duration,
+            desiredIdx = desiredIdx,
+            controllerIdx = controller.currentMediaItemIndex,
+        )
+        val newBuf = controller.bufferedPosition.coerceAtLeast(0)
+        // Track adjustments are forward-only AND suppressed while a user
+        // transport press is pending Sonos confirmation. Together those keep
+        // either direction of user input from being undone by a stale poll.
+        val trackChanged = !pendingTransport &&
+            desiredIdx > current.queueIndex &&
+            desiredIdx in queueRefs.indices
+        publishTickIfChanged(
+            current, trackChanged, desiredIdx,
+            effectiveIsPlaying, newPos, newDur, newBuf,
        )
    }
+
+    /**
+     * Event-driven primary path: clear pending the moment Sonos's reported
+     * Track matches the wrapped player's index. Safety fallback: clear on
+     * deadline so we don't ignore Sonos's actual state forever if SOAP fails.
+     */
+    private fun resolvePendingTransport(controller: MediaController, upnpActive: Boolean) {
+        if (!upnpActive || remoteState.pendingTransportDeadlineMs <= 0L) return
+        val sonosIdx = (remoteState.trackNumber - 1).coerceAtLeast(0)
+        val timedOut = SystemClock.elapsedRealtime() > remoteState.pendingTransportDeadlineMs
+        if (sonosIdx == controller.currentMediaItemIndex || timedOut) {
+            remoteState.clearPendingTransport()
        }
    }

+    @Suppress("LongParameterList") // assembled at one tick call site; refactor would cost clarity
+    private fun publishTickIfChanged(
+        current: PlayerUiState,
+        trackChanged: Boolean,
+        desiredIdx: Int,
+        effectiveIsPlaying: Boolean,
+        newPos: Long,
+        newDur: Long,
+        newBuf: Long,
+    ) {
+        val somethingChanged = trackChanged ||
+            current.isPlaying != effectiveIsPlaying ||
+            current.positionMs != newPos ||
+            current.durationMs != newDur
+        if (!somethingChanged) return
+        val newTrack = if (trackChanged) queueRefs[desiredIdx] else current.currentTrack
+        val newIdx = if (trackChanged) desiredIdx else current.queueIndex
+        uiStateInternal.value = current.copy(
+            currentTrack = newTrack,
+            queueIndex = newIdx,
+            isPlaying = effectiveIsPlaying,
+            positionMs = newPos,
+            durationMs = newDur,
+            bufferedPositionMs = newBuf,
+        )
+        // Intentionally do NOT call controller.seekTo here. That would route
+        // through MinstrelForwardingPlayer's seekTo override and re-issue
+        // AVTransport.SeekToTrack to Sonos -- which seeks Sonos back to the
+        // start of the same track it's already playing, restarting the song.
+        // The wrapped player's index is kept in sync by maybeSyncLocalCursor's
+        // delegate.seekTo (which bypasses the override). If it lags briefly,
+        // the next pollOnce catches up; the uiState above already reflects
+        // Sonos's truth for the user.
+    }
+
+    private fun desiredQueueIndex(controller: MediaController, upnpActive: Boolean): Int =
+        if (upnpActive) {
+            (remoteState.trackNumber - 1).coerceAtLeast(0)
+        } else {
+            controller.currentMediaItemIndex
+        }
+
+    // ── Remote position interpolation state ──────────────────────────────
+    // remoteState.positionMs is only refreshed by ForwardingPlayer's 1Hz
+    // SOAP poll (and only when the round-trip completes -- screen-off WiFi
+    // sleep can stall it for many seconds). To keep the scrubber moving
+    // smoothly we anchor each fresh reading + an elapsed-realtime stamp;
+    // between updates we display anchor + elapsed when Sonos is playing.
+    // A real correction lands as soon as the next poll arrives.
+    @Volatile private var lastSeenRemotePositionMs: Long = -1L
+    @Volatile private var positionAnchorMs: Long = 0L
+    @Volatile private var positionAnchorAtRealtimeMs: Long = 0L
+
+    private fun interpolatedRemotePosition(isPlaying: Boolean): Long {
+        val raw = remoteState.positionMs
+        val now = SystemClock.elapsedRealtime()
+        if (raw != lastSeenRemotePositionMs) {
+            lastSeenRemotePositionMs = raw
+            positionAnchorMs = raw
+            positionAnchorAtRealtimeMs = now
+        }
+        if (!isPlaying) return positionAnchorMs
+        // Cap how far past the last anchor we extrapolate. After
+        // MAX_INTERPOLATION_DRIFT_MS without a poll update, freeze the
+        // displayed position at anchor + cap rather than projecting wildly.
+        // The next successful poll re-anchors and motion resumes.
+        val delta = (now - positionAnchorAtRealtimeMs).coerceAtMost(MAX_INTERPOLATION_DRIFT_MS)
+        return positionAnchorMs + delta
+    }
+
    /**
     * Bridges Media3's `ListenableFuture<MediaController>.buildAsync()`
     * to a suspend function without pulling in `kotlinx-coroutines-guava`
@@ -467,7 +759,23 @@ class PlayerController @Inject constructor(
            .setArtist(artistName)
            .setAlbumTitle(albumTitle)
            .apply {
+                // Server-known duration -- gives the lock-screen / notification
+                // scrubber a real total even when the wrapped ExoPlayer is
+                // paused under UPnP (it never probes a duration in that state).
+                if (durationSec > 0) setDurationMs(durationSec.toLong() * MS_PER_SECOND)
                if (source != null) setExtras(sourceExtras(source))
+                // Point the notification / lock-screen art at the SAME album
+                // cover the in-app surfaces use (TrackRef.coverUrl ->
+                // /api/albums/{id}/cover). Without this, Media3 falls back to
+                // whatever art is embedded in the stream's tags, which can be a
+                // different image than the server's album cover. Setting
+                // artworkUri here is load-bearing: MediaMetadata.populate()
+                // overwrites artworkUri + artworkData as a pair, so the
+                // MediaItem's URI clears any embedded artworkData ExoPlayer
+                // extracts from the stream -- the cover endpoint wins on both
+                // surfaces. The session's OkHttp-backed BitmapLoader (see
+                // PlayerFactory) is what makes this authed placeholder URL load.
+                if (coverUrl.isNotEmpty()) setArtworkUri(coverUrl.toUri())
            }
            .build()
        // Server's stream_url is a relative path (/api/tracks/{id}/stream);
@@ -489,8 +797,40 @@ class PlayerController @Inject constructor(
    private fun sourceExtras(source: String): Bundle =
        Bundle().apply { putString(MINSTREL_SOURCE_KEY, source) }

+    /**
+     * Duration to surface to the UI. Priority: Sonos's reported duration
+     * (only when UPnP active and non-zero) -> wrapped ExoPlayer's value
+     * (only valid once it's probed the stream) -> TrackRef.durationSec
+     * (always known from the server response). The third tier is what
+     * keeps the scrubber populated when the user taps Sonos before the
+     * wrapped player has had time to probe its own duration -- without
+     * it, both top tiers report 0/TIME_UNSET and the field reads empty
+     * until the first SOAP poll lands.
+     */
+    @Suppress("ReturnCount") // 3-tier fallback reads cleanest as a ladder of early returns
+    private fun effectiveDuration(
+        upnpActive: Boolean,
+        remoteMs: Long,
+        localMs: Long,
+        desiredIdx: Int,
+        controllerIdx: Int,
+    ): Long {
+        if (upnpActive && remoteMs > 0) return remoteMs
+        // Tier 2 (wrapped player's probed duration) only valid when the
+        // wrapped player is on the same track we're trying to show. After a
+        // Sonos natural advance the polling tick updates desiredIdx from
+        // Sonos's truth while controllerIdx is briefly stale -- using the
+        // wrapped player's duration here would surface the old track's
+        // length under the new track's title.
+        if (localMs > 0 && controllerIdx == desiredIdx) return localMs
+        val ref = queueRefs.getOrNull(desiredIdx) ?: return 0
+        return ref.durationSec.toLong() * MS_PER_SECOND
+    }
+
    companion object {
        const val MINSTREL_SOURCE_KEY: String = "minstrel_source"
+        private const val MS_PER_SECOND = 1_000L
+        private const val MAX_INTERPOLATION_DRIFT_MS = 5_000L
    }
 }

@@ -501,6 +841,10 @@ class PlayerController @Inject constructor(
 // they don't need this poll.
 private const val POSITION_POLL_INTERVAL_MS = 500L

+// #968: at most one stale-queue self-heal re-pull per exhaustion (reset on
+// the next successful play) so a still-broken refresh can't loop.
+private const val MAX_SELF_HEAL_ATTEMPTS = 1
+
 /**
 * Structured playback failure event for [PlaybackErrorReporter]. Drives
 * both the user-facing snackbar ("Couldn't play X — skipping") and the
@@ -3,7 +3,10 @@ package com.fabledsword.minstrel.player
 import android.content.Context
 import androidx.media3.common.AudioAttributes
 import androidx.media3.common.C
+import androidx.media3.common.Player
+import androidx.media3.common.util.BitmapLoader
 import androidx.media3.database.StandaloneDatabaseProvider
+import androidx.media3.datasource.DataSourceBitmapLoader
 import androidx.media3.datasource.cache.CacheDataSink
 import androidx.media3.datasource.cache.CacheDataSource
 import androidx.media3.datasource.cache.LeastRecentlyUsedCacheEvictor
@@ -11,15 +14,21 @@ import androidx.media3.datasource.cache.SimpleCache
 import androidx.media3.datasource.okhttp.OkHttpDataSource
 import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.exoplayer.source.DefaultMediaSourceFactory
+import androidx.media3.session.CacheBitmapLoader
 import com.fabledsword.minstrel.cache.audiocache.CacheConfig
+import com.fabledsword.minstrel.player.output.ActiveUpnpHolder
 import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.channels.BufferOverflow
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.SharedFlow
+import kotlinx.coroutines.flow.asSharedFlow
 import okhttp3.OkHttpClient
 import java.io.File
 import javax.inject.Inject
 import javax.inject.Singleton

 /**
- * Builds the process-singleton ExoPlayer with our shared OkHttp +
+ * Builds the process-singleton player with our shared OkHttp +
 * SimpleCache chain. The MinstrelPlayerService (Phase 6.2) calls
 * `build()` once during onCreate.
 *
@@ -31,12 +40,22 @@ import javax.inject.Singleton
 * (sizeBytes cap = rollingCap); our policy layer in the worker layers
 * the 2-bucket protection on top by feeding `removeSpan` only for
 * unprotected tracks.
+ *
+ * `build()` returns a [MinstrelForwardingPlayer] wrapping the internal
+ * ExoPlayer. When the UPnP route drops (3 consecutive poll failures or
+ * a SOAP failure), [dropEvents] emits the route name so the NowPlaying
+ * surface can show a snackbar. The MutableSharedFlow uses DROP_OLDEST
+ * with capacity=1 so a burst of failures during a single tear-down
+ * surfaces as one event rather than queueing N.
 */
@Singleton
 class PlayerFactory @Inject constructor(
    @ApplicationContext private val context: Context,
    private val okHttpClient: OkHttpClient,
    private val cacheConfig: CacheConfig,
+    private val activeUpnpHolder: ActiveUpnpHolder,
+    private val remoteState: RemotePlayerState,
+    private val serverHealth: com.fabledsword.minstrel.connectivity.NetworkStatusController,
 ) {
    private val cacheDir: File = File(context.cacheDir, "audio_cache").apply { mkdirs() }

@@ -46,11 +65,38 @@ class PlayerFactory @Inject constructor(
        StandaloneDatabaseProvider(context),
    )

-    fun build(): ExoPlayer {
+    // MutableSharedFlow with extraBufferCapacity=1 + DROP_OLDEST so a burst
+    // of drop events (rapid SOAP failures during a single tear-down) surfaces
+    // as one snackbar rather than queueing N.
+    private val dropEventsInternal = MutableSharedFlow<String>(
+        replay = 0,
+        extraBufferCapacity = 1,
+        onBufferOverflow = BufferOverflow.DROP_OLDEST,
+    )
+    val dropEvents: SharedFlow<String> = dropEventsInternal.asSharedFlow()
+
+    fun build(): Player {
+        val exo = buildExoPlayer()
+        return MinstrelForwardingPlayer(
+            delegate = exo,
+            holder = activeUpnpHolder,
+            remoteState = remoteState,
+            castNetworkLock = CastNetworkLock(context),
+            networkStatus = serverHealth,
+            onDrop = { name -> emitDrop(name) },
+        )
+    }
+
+    private fun buildExoPlayer(): ExoPlayer {
        val httpDataSource = OkHttpDataSource.Factory(okHttpClient)
+        // Gate network reads on ServerHealth so a cache miss while offline
+        // fails fast with an OfflineException instead of hitting an OkHttp
+        // timeout. CacheDataSource only consults the upstream factory on a
+        // cache miss, so playback of cached audio is unaffected.
+        val gatedUpstream = OfflineGatedDataSourceFactory(httpDataSource, serverHealth)
        val cacheDataSource = CacheDataSource.Factory()
            .setCache(simpleCache)
-            .setUpstreamDataSourceFactory(httpDataSource)
+            .setUpstreamDataSourceFactory(gatedUpstream)
            .setCacheWriteDataSinkFactory(
                CacheDataSink.Factory()
                    .setCache(simpleCache)
@@ -71,4 +117,26 @@ class PlayerFactory @Inject constructor(
            .setHandleAudioBecomingNoisy(true)
            .build()
    }
+
+    /**
+     * BitmapLoader for the MediaSession's notification / lock-screen art.
+     * Backed by the shared [okHttpClient] so it inherits the same
+     * BaseUrlInterceptor placeholder rewrite + auth cookie that Coil uses
+     * for in-app covers — without it the default DefaultHttpDataSource
+     * loader can't resolve `http://placeholder.invalid/...` and would 401
+     * on the cover endpoint. Wrapped in CacheBitmapLoader so a cover the
+     * notification already fetched isn't re-loaded on every metadata
+     * refresh. Lets the album-cover artworkUri set in
+     * [PlayerController.toMediaItem] actually render on the media card.
+     */
+    fun buildBitmapLoader(): BitmapLoader =
+        CacheBitmapLoader(
+            DataSourceBitmapLoader.Builder(context)
+                .setDataSourceFactory(OkHttpDataSource.Factory(okHttpClient))
+                .build(),
+        )
+
+    private fun emitDrop(routeName: String) {
+        dropEventsInternal.tryEmit(routeName)
+    }
 }
@@ -28,4 +28,6 @@ data class PlayerUiState(
    val currentSource: String? = null,
    val shuffleEnabled: Boolean = false,
    val repeatMode: RepeatMode = RepeatMode.OFF,
+    /** True while the UPnP initial-batch load is in progress (target set, active not yet wired). */
+    val isUpnpLoading: Boolean = false,
 )
@@ -0,0 +1,110 @@
+package com.fabledsword.minstrel.player
+
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Synthesized state for the UPnP route -- what the ForwardingPlayer
+ * exposes via Player.getCurrentPosition / isPlaying / etc. when the
+ * remote leg is active. Not a Player; a container.
+ *
+ * Updates flow in from:
+ *  - 1Hz GetPositionInfo poll -> applyPositionInfo()
+ *  - Transport SOAP calls landing 200 OK -> applyTransport{Playing,Paused,Stopped}()
+ *  - Poll failures -> recordPollFailure()
+ *
+ * The poll-failure counter is the sole drop arbiter: [DROP_THRESHOLD]
+ * consecutive poll failures = remote considered dropped (returns true
+ * from recordPollFailure for the caller to surface). Any success resets it.
+ * Failed transport commands no longer drop the route -- they retry and
+ * otherwise defer to this counter (see MinstrelForwardingPlayer).
+ */
+@Singleton
+class RemotePlayerState @Inject constructor() {
+
+    @Volatile var positionMs: Long = 0L; private set
+    @Volatile var durationMs: Long = 0L; private set
+    @Volatile var isPlaying: Boolean = false; private set
+    @Volatile var currentTrackUri: String = ""; private set
+    @Volatile var lastError: Throwable? = null; private set
+    @Volatile var trackNumber: Int = 0; private set
+
+    // The operator's last explicit transport intent (play=true, pause=false),
+    // distinct from the observed remote isPlaying. handleRemoteDrop resumes
+    // local playback based on THIS, not isPlaying -- so a play() that fails
+    // its SOAP (stale/dead renderer) still resumes on the phone instead of
+    // swallowing the tap. Deliberately NOT cleared by applyError.
+    @Volatile var lastPlayIntent: Boolean = false; private set
+
+    // Pending-transport deadline (SystemClock.elapsedRealtime() at which we
+    // give up waiting). When > 0, a user transport action (next/prev/seekTo
+    // idx) is in flight: ForwardingPlayer has already moved the wrapped
+    // player's index, but Sonos's reported Track hasn't refreshed via a
+    // SOAP poll yet. PlayerController.tickPositionPoll skips track
+    // adjustments while pending is non-zero. Pending clears when:
+    //   (a) [event-driven, primary] a poll lands and Sonos's reported Track
+    //       matches the wrapped player's currentMediaItemIndex; or
+    //   (b) [safety fallback] the deadline expires (covers SOAP-fail cases
+    //       where Sonos never acks).
+    @Volatile var pendingTransportDeadlineMs: Long = 0L; private set
+
+    fun beginPendingTransport(deadlineMs: Long) {
+        pendingTransportDeadlineMs = deadlineMs
+    }
+
+    fun clearPendingTransport() {
+        pendingTransportDeadlineMs = 0L
+    }
+
+    @Volatile private var consecutivePollFailures: Int = 0
+
+    fun applyPositionInfo(positionMs: Long, durationMs: Long, trackUri: String, trackNumber: Int) {
+        this.positionMs = positionMs
+        this.durationMs = durationMs
+        this.currentTrackUri = trackUri
+        this.trackNumber = trackNumber
+    }
+
+    fun applyTransportPlaying() { isPlaying = true }
+    fun applyTransportPaused() { isPlaying = false }
+    fun applyTransportStopped() {
+        isPlaying = false
+        positionMs = 0L
+    }
+
+    fun setPlayIntent(intended: Boolean) { lastPlayIntent = intended }
+
+    fun applyError(t: Throwable) {
+        isPlaying = false
+        lastError = t
+    }
+
+    /** Returns true when the rolling threshold trips this call. */
+    fun recordPollFailure(): Boolean {
+        consecutivePollFailures += 1
+        return consecutivePollFailures >= DROP_THRESHOLD
+    }
+
+    fun recordPollSuccess() { consecutivePollFailures = 0 }
+
+    fun reset() {
+        positionMs = 0L
+        durationMs = 0L
+        isPlaying = false
+        lastPlayIntent = false
+        currentTrackUri = ""
+        lastError = null
+        consecutivePollFailures = 0
+        trackNumber = 0
+        pendingTransportDeadlineMs = 0L
+    }
+
+    private companion object {
+        // ~30 seconds of consecutive poll failures before declaring the route
+        // dropped. Bumped from 3 because screen-off WiFi sleep / brief Doze
+        // can stall socket I/O for several seconds without the renderer
+        // actually being unreachable -- a 3-failure drop kicked us back to
+        // local audio every time the phone went into a pocket.
+        const val DROP_THRESHOLD = 30
+    }
+}
@@ -0,0 +1,24 @@
+package com.fabledsword.minstrel.player
+
+import com.fabledsword.minstrel.api.endpoints.CastApi
+import com.fabledsword.minstrel.api.endpoints.StreamTokenRequest
+import com.fabledsword.minstrel.api.endpoints.StreamTokenResponse
+import retrofit2.Retrofit
+import retrofit2.create
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Mints stream tokens for a given track id. Pulled into its own Hilt
+ * singleton so [MinstrelForwardingPlayer] (service-side) and
+ * [com.fabledsword.minstrel.player.output.OutputPickerController]
+ * (controller-side) don't each construct their own [CastApi] from
+ * Retrofit. The shared Retrofit instance is unchanged.
+ */
+@Singleton
+class StreamTokenProvider @Inject constructor(retrofit: Retrofit) {
+    private val api: CastApi = retrofit.create()
+
+    suspend fun mint(trackId: String): StreamTokenResponse =
+        api.streamToken(StreamTokenRequest(trackId = trackId))
+}
@@ -0,0 +1,43 @@
+package com.fabledsword.minstrel.player.output
+
+import com.fabledsword.minstrel.player.output.upnp.AVTransportClient
+import com.fabledsword.minstrel.player.output.upnp.RenderingControlClient
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Shared singleton handle to the currently-active UPnP route's transport
+ * + rendering clients. Decouples [com.fabledsword.minstrel.player.MinstrelForwardingPlayer]
+ * from [OutputPickerController] -- the picker writes; the forwarding
+ * player reads. Null = no UPnP active (local ExoPlayer path).
+ */
+data class ActiveUpnp(
+    val routeId: String,
+    val routeName: String,
+    val avTransport: AVTransportClient,
+    val rendering: RenderingControlClient?,
+)
+
+@Singleton
+class ActiveUpnpHolder @Inject constructor() {
+
+    private val internal = MutableStateFlow<ActiveUpnp?>(null)
+    val active: StateFlow<ActiveUpnp?> = internal.asStateFlow()
+
+    /**
+     * Pending route id during selectUpnp's queue-load window. Set when
+     * loadQueueOnSonos starts; cleared on completion (success or failure).
+     * ForwardingPlayer overrides treat (target != null && active == null)
+     * as "UPnP intended but SOAP not yet wired" -- drop transport commands
+     * silently rather than send them to a half-loaded queue.
+     */
+    private val targetInternal = MutableStateFlow<String?>(null)
+    val target: StateFlow<String?> = targetInternal.asStateFlow()
+
+    fun set(active: ActiveUpnp?) { internal.value = active }
+
+    fun setTarget(routeId: String?) { targetInternal.value = routeId }
+}
@@ -0,0 +1,21 @@
+package com.fabledsword.minstrel.player.output
+
+/** Action the idle-revert collector should take on a player-state change. */
+internal enum class IdleRevertAction { ARM, CANCEL, IGNORE }
+
+/**
+ * Pure decision for the UPnP idle-revert timer. [armed] is whether the
+ * idle timer Job is currently running. We ARM only on the transition INTO
+ * "engaged + not playing" (so repeated paused emissions don't reset the
+ * countdown), CANCEL whenever playback resumes or UPnP disengages, and
+ * otherwise IGNORE.
+ */
+internal fun idleRevertAction(
+    upnpEngaged: Boolean,
+    isPlaying: Boolean,
+    armed: Boolean,
+): IdleRevertAction = when {
+    upnpEngaged && !isPlaying -> if (armed) IdleRevertAction.IGNORE else IdleRevertAction.ARM
+    armed -> IdleRevertAction.CANCEL
+    else -> IdleRevertAction.IGNORE
+}
@@ -1,24 +1,37 @@
+@file:Suppress("TooManyFunctions") // 5 MediaRouter.Callback overrides inflate the count
 package com.fabledsword.minstrel.player.output

 import android.content.Context
 import androidx.mediarouter.media.MediaControlIntent
 import androidx.mediarouter.media.MediaRouteSelector
 import androidx.mediarouter.media.MediaRouter
-import com.fabledsword.minstrel.api.endpoints.CastApi
-import com.fabledsword.minstrel.api.endpoints.StreamTokenRequest
 import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.models.TrackRef
 import com.fabledsword.minstrel.player.PlayerController
+import com.fabledsword.minstrel.player.PlayerFactory
+import com.fabledsword.minstrel.player.RemotePlayerState
+import com.fabledsword.minstrel.player.StreamTokenProvider
+import com.fabledsword.minstrel.player.output.upnp.AVTransportClient
+import com.fabledsword.minstrel.player.output.upnp.RenderingControlClient
+import com.fabledsword.minstrel.player.output.upnp.SoapClient
+import com.fabledsword.minstrel.player.output.upnp.SoapFaultException
+import com.fabledsword.minstrel.player.output.upnp.TransportState
 import com.fabledsword.minstrel.player.output.upnp.UpnpDiscoveryController
+import com.fabledsword.minstrel.player.output.upnp.bareUdn
 import dagger.hilt.android.qualifiers.ApplicationContext
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.launch
-import retrofit2.Retrofit
-import retrofit2.create
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
+import okhttp3.OkHttpClient
 import timber.log.Timber
 import javax.inject.Inject
 import javax.inject.Singleton
@@ -26,9 +39,9 @@ import javax.inject.Singleton
 /**
 * Snapshot of the audio output route state. [current] is the live
 * route audio is being delivered to. [available] is every route the
- * picker knows about — MediaRouter system routes merged with
- * UPnP/DLNA renderers discovered on the LAN — sorted current-first
- * then by [OutputRoute.Kind] (Bluetooth, Wired, BuiltIn, Other).
+ * picker knows about -- MediaRouter system routes merged with
+ * UPnP/DLNA renderers discovered on the LAN -- with the BuiltIn
+ * "Phone speaker" pinned first, everything else alphabetical.
 */
 data class RouteSnapshot(
    val current: OutputRoute,
@@ -48,7 +61,7 @@ data class RouteSnapshot(
 *  - [OutputRoute.Protocol.SYSTEM] — MediaRouter.selectRoute (built-in,
 *    wired, Bluetooth)
 *  - [OutputRoute.Protocol.UPNP] — mint a signed stream token via
- *    [CastApi.streamToken], drive the discovered renderer with
+ *    [StreamTokenProvider.mint], drive the discovered renderer with
 *    AVTransport.SetAVTransportURI + Play, pause local playback so
 *    audio yields to the network speaker
 *  - [OutputRoute.Protocol.CAST] / [OutputRoute.Protocol.SONOS] —
@@ -65,10 +78,12 @@ class OutputPickerController @Inject constructor(
    @ApplicationScope private val scope: CoroutineScope,
    private val upnpDiscovery: UpnpDiscoveryController,
    private val playerController: PlayerController,
-    retrofit: Retrofit,
+    private val playerFactory: PlayerFactory,
+    private val streamTokens: StreamTokenProvider,
+    private val activeUpnpHolder: ActiveUpnpHolder,
+    private val remoteState: RemotePlayerState,
+    private val okHttp: OkHttpClient,
 ) {
-    private val castApi: CastApi = retrofit.create()
-
    private val mediaRouter = MediaRouter.getInstance(context)

    private val selector = MediaRouteSelector.Builder()
@@ -82,12 +97,26 @@ class OutputPickerController @Inject constructor(
     */
    private val systemRoutesInternal = MutableStateFlow(snapshotFromRouter())

+    private val selectedUpnpRouteIdInternal = MutableStateFlow<String?>(null)
+    private val selectUpnpMutex = Mutex()
+
    val routesState: StateFlow<RouteSnapshot> = combine(
        systemRoutesInternal,
        upnpDiscovery.routes,
-    ) { sys, upnp ->
-        val merged = sys.available + upnp.map { OutputRoute.fromUpnpRoute(it) }
-        RouteSnapshot(current = sys.current, available = sortRoutes(sys.current, merged))
+        upnpDiscovery.sonosTopology,
+        selectedUpnpRouteIdInternal,
+    ) { sys, upnp, _, upnpSelected ->
+        val suppressed = upnpDiscovery.nonCoordinatorMemberUdns()
+        val visibleUpnp = upnp
+            .filter { it.id.bareUdn() !in suppressed } // suppressed set is bare UDNs
+            .map { OutputRoute.fromUpnpRoute(it) }
+        val merged = sys.available + visibleUpnp
+        val current = if (upnpSelected != null) {
+            merged.firstOrNull { it.id == upnpSelected } ?: sys.current
+        } else {
+            sys.current
+        }
+        RouteSnapshot(current = current, available = sortRoutes(merged))
    }.stateIn(scope, SharingStarted.Eagerly, systemRoutesInternal.value)

    private val callback = object : MediaRouter.Callback() {
@@ -113,6 +142,20 @@ class OutputPickerController @Inject constructor(
        ) = refresh()
    }

+    // Last-synced queue identity. Used by observeQueueChangesForSonosResync
+    // to detect when the user has mutated the queue (full replacement,
+    // playNext insert, or radio-append) while UPnP is active and apply the
+    // minimum-incremental set of Sonos SOAP operations to bring its native
+    // queue back in sync. Stored as the full id list (not a join-key) so we
+    // can run the longest-common-prefix / common-suffix diff.
+    private var lastSyncedQueueIds: List<String>? = null
+
+    // Idle-revert timer. Armed when playback is paused/stopped on a UPnP
+    // route; fires revertToPhoneOnIdle after IDLE_REVERT_MS of continuous
+    // non-playing. Cancelled on resume, route change, or explicit disconnect.
+    // See idleRevertAction for the arm/cancel decision.
+    private var idleRevertJob: Job? = null
+
    init {
        // Two-arg addCallback registers with no discovery flag —
        // androidx.mediarouter 1.7.0's default passive behavior:
@@ -120,6 +163,309 @@ class OutputPickerController @Inject constructor(
        // without forcing Bluetooth scans. (There is no
        // CALLBACK_FLAG_PASSIVE_DISCOVERY constant; absent flag = passive.)
        mediaRouter.addCallback(selector, callback)
+        // When MinstrelForwardingPlayer reports the active UPnP route has
+        // dropped (the poll loop's consecutive-failure threshold tripping --
+        // the sole drop arbiter; a failed transport command no longer drops),
+        // clear the UPnP selection state and fall back to local ExoPlayer at
+        // the last-known remote position. This mirrors selectSystem's disconnect
+        // path but skips the Stop SOAP since the device is already unreachable.
+        scope.launch {
+            playerFactory.dropEvents.collect { handleRemoteDrop() }
+        }
+        scope.launch { observeQueueChangesForSonosResync() }
+        scope.launch { observeIdleRevertWhileUpnp() }
+        scope.launch { observeSelectedRouteDisappearance() }
+    }
+
+    /**
+     * Revert the UPnP selection to the phone when the selected renderer leaves
+     * discovery (powered off / off the LAN) while we are NOT actively casting
+     * to it. Without this the selection could pin to a ghost route, so a later
+     * "play" would target a speaker that's gone. An *active* cast is left alone
+     * -- its own poll loop arbitrates liveness and won't drop on a mere
+     * discovery gap. Routes leave discovery via [UpnpDiscoveryController]'s
+     * post-picker-scan prune; this reacts to the resulting routes change.
+     */
+    private suspend fun observeSelectedRouteDisappearance() {
+        upnpDiscovery.routes.collect { routes ->
+            val selected = selectedUpnpRouteIdInternal.value
+            val present = routes.any { it.id == selected }
+            val casting = activeUpnpHolder.active.value?.routeId == selected
+            if (selected != null && !present && !casting) {
+                Timber.w(
+                    "Output: selected UPnP route %s left discovery; reverting to phone",
+                    selected,
+                )
+                selectedUpnpRouteIdInternal.value = null
+            }
+        }
+    }
+
+    /**
+     * Arm/cancel the idle-revert timer as playback state changes while a
+     * UPnP route is engaged. "Engaged" = active OR target set, so the brief
+     * selectUpnp/resync window (active momentarily null, target set) doesn't
+     * spuriously fire. The arm/cancel choice is the pure idleRevertAction.
+     */
+    private suspend fun observeIdleRevertWhileUpnp() {
+        playerController.uiState.collect { state ->
+            val engaged = activeUpnpHolder.active.value != null ||
+                activeUpnpHolder.target.value != null
+            val armed = idleRevertJob?.isActive == true
+            when (idleRevertAction(engaged, state.isPlaying, armed)) {
+                IdleRevertAction.ARM ->
+                    idleRevertJob = scope.launch {
+                        delay(IDLE_REVERT_MS)
+                        revertToPhoneOnIdle()
+                    }
+                IdleRevertAction.CANCEL -> {
+                    idleRevertJob?.cancel()
+                    idleRevertJob = null
+                }
+                IdleRevertAction.IGNORE -> Unit
+            }
+        }
+    }
+
+    /**
+     * Timer fired: the operator paused on a UPnP route and never resumed.
+     * Stop the renderer (best-effort -- it's reachable, unlike a drop),
+     * clear the UPnP overlay so routesState falls back to the phone, and
+     * seek local ExoPlayer to the last remote position. No play(): the
+     * operator was paused, so we revert routing silently. Guarded by the
+     * selectUpnpMutex so it can't race selectUpnp/resync.
+     */
+    private suspend fun revertToPhoneOnIdle() = selectUpnpMutex.withLock {
+        if (remoteState.isPlaying) return@withLock // resumed at the boundary
+        val active = activeUpnpHolder.active.value
+        val capturedPositionMs = remoteState.positionMs
+        runCatching { active?.avTransport?.stop() }
+            .onFailure { Timber.w(it, "UPnP Stop failed during idle revert") }
+        activeUpnpHolder.set(null)
+        activeUpnpHolder.setTarget(null)
+        selectedUpnpRouteIdInternal.value = null
+        idleRevertJob = null
+        playerController.seekTo(capturedPositionMs)
+    }
+
+    /**
+     * When the user plays a different playlist while Sonos is active,
+     * PlayerController.setQueue replaces the local queue but Sonos's
+     * native queue still holds the OLD tracks. MinstrelForwardingPlayer's
+     * setMediaItems override clears holder.active + sets target so the
+     * imminent play() call drops (drops via isLoadingUpnp() = true). Then
+     * this collector observes the uiState.queue change and re-runs
+     * loadQueueOnSonos to push the new tracks to Sonos.
+     *
+     * Discrimination: selectUpnp's initial-load path doesn't change
+     * uiState.queue (the queue was already populated before route
+     * selection), so this collector doesn't fire during that window. Only
+     * a fresh setQueue from PlayerController bumps the joined-ids key.
+     */
+    private suspend fun observeQueueChangesForSonosResync() {
+        playerController.uiState.collect { state ->
+            val newIds = state.queue.map { it.id }
+            val oldIds = lastSyncedQueueIds
+            if (newIds == oldIds) return@collect
+            lastSyncedQueueIds = newIds
+            // Route can be in target (setMediaItems-induced clearing already
+            // ran in ForwardingPlayer) OR in active (queue changed via
+            // addMediaItem / removeMediaItems etc. which don't hit the
+            // markPending hook).
+            val routeId = activeUpnpHolder.target.value
+                ?: activeUpnpHolder.active.value?.routeId
+                ?: return@collect
+            if (state.queue.isEmpty()) {
+                Timber.w("Sonos resync skipped: empty queue (clearing target)")
+                activeUpnpHolder.setTarget(null)
+                return@collect
+            }
+            scope.launch {
+                resyncSonosQueue(routeId, oldIds.orEmpty(), state.queue, state.queueIndex)
+            }
+        }
+    }
+
+    /**
+     * Bring Sonos's native queue back in sync with the local queue after a
+     * mutation. Tries an incremental SOAP diff first (RemoveTrackRangeFromQueue
+     * + AddURIToQueue at the insertion point) so playback continues without
+     * interruption -- that's what playNext / radio-append want. Falls back to
+     * the full removeAllTracks + reload path when the diff implies the current
+     * Sonos track was deleted (e.g. user switched playlists), which is what
+     * the user-reported "Sonos queue does not update" bug needed.
+     */
+    private suspend fun resyncSonosQueue(
+        routeId: String,
+        oldIds: List<String>,
+        newQueue: List<TrackRef>,
+        newCurrentIndex: Int,
+    ) = selectUpnpMutex.withLock {
+        val upnpRoute = upnpDiscovery.routes.value.firstOrNull { it.id == routeId }
+        val transport = upnpDiscovery.transportFor(routeId)
+        if (upnpRoute == null || transport == null) {
+            Timber.w(
+                "Sonos resync: route or transport gone for %s, dropping to local",
+                routeId,
+            )
+            activeUpnpHolder.setTarget(null)
+            selectedUpnpRouteIdInternal.value = null
+            return@withLock
+        }
+        val handledIncrementally = runCatching {
+            tryIncrementalResync(transport, oldIds, newQueue)
+        }.getOrElse { e ->
+            Timber.w(e, "Sonos incremental resync errored; falling back to full reload")
+            false
+        }
+        if (handledIncrementally) {
+            // Active was never cleared on the incremental path; clear any
+            // target that markPendingResyncIfRemote set (it didn't, for
+            // incremental cases that don't go through setMediaItems, but
+            // belt-and-suspenders).
+            activeUpnpHolder.setTarget(null)
+            return@withLock
+        }
+        // Full rebuild: ensure active is cleared so transport calls drop
+        // (markPendingResyncIfRemote may already have done this on the
+        // setMediaItems path).
+        if (activeUpnpHolder.active.value != null) {
+            activeUpnpHolder.set(null)
+            activeUpnpHolder.setTarget(routeId)
+        }
+        val outputRoute = OutputRoute.fromUpnpRoute(upnpRoute)
+        val rendering = renderingClientFor(routeId)
+        Timber.w("Sonos resync: full reload of %d tracks on %s", newQueue.size, outputRoute.name)
+        runCatching {
+            loadQueueOnSonos(transport, outputRoute, newQueue, newCurrentIndex)
+            activeUpnpHolder.set(
+                ActiveUpnp(
+                    routeId = routeId,
+                    routeName = outputRoute.name,
+                    avTransport = transport,
+                    rendering = rendering,
+                ),
+            )
+            activeUpnpHolder.setTarget(null)
+        }.onFailure { e ->
+            Timber.w(e, "Sonos resync (full) failed -- dropping to local")
+            activeUpnpHolder.setTarget(null)
+            selectedUpnpRouteIdInternal.value = null
+        }
+    }
+
+    /**
+     * Diff-based incremental Sonos queue sync. Returns true when the new
+     * queue can be produced from the old one with a remove-then-insert at
+     * the same middle slice -- the common-prefix and common-suffix portions
+     * stay untouched, and the current Sonos track must lie in the preserved
+     * prefix (otherwise the diff would orphan playback). Returns false to
+     * signal the caller to fall back to a full reload.
+     */
+    private suspend fun tryIncrementalResync(
+        transport: AVTransportClient,
+        oldIds: List<String>,
+        newQueue: List<TrackRef>,
+    ): Boolean {
+        val newIds = newQueue.map { it.id }
+        if (oldIds == newIds) return true
+        val prefixLen = commonPrefixLength(oldIds, newIds)
+        val suffixLen = commonSuffixLength(
+            oldIds.subList(prefixLen, oldIds.size),
+            newIds.subList(prefixLen, newIds.size),
+        )
+        val removedCount = oldIds.size - prefixLen - suffixLen
+        val addedCount = newIds.size - prefixLen - suffixLen
+        // Sonos's current track number is 1-based; compare against the
+        // preserved-prefix range as 0-based. If the current track is in
+        // the removed slice, incremental can't preserve playback -- caller
+        // falls back to full rebuild.
+        val currentSonosIdx0 = remoteState.trackNumber - 1
+        val canApply = currentSonosIdx0 in 0 until prefixLen
+        if (canApply) {
+            applyQueueDiff(transport, newQueue, prefixLen, removedCount, addedCount)
+        } else {
+            Timber.w(
+                "Sonos incremental: current track %d not in preserved prefix [0,%d); full rebuild",
+                currentSonosIdx0,
+                prefixLen,
+            )
+        }
+        return canApply
+    }
+
+    private suspend fun applyQueueDiff(
+        transport: AVTransportClient,
+        newQueue: List<TrackRef>,
+        prefixLen: Int,
+        removedCount: Int,
+        addedCount: Int,
+    ) {
+        if (removedCount > 0) {
+            Timber.w(
+                "Sonos incremental: RemoveTrackRangeFromQueue start=%d count=%d",
+                prefixLen + 1,
+                removedCount,
+            )
+            transport.removeTrackRangeFromQueue(
+                startingIndex = prefixLen + 1,
+                numberOfTracks = removedCount,
+            )
+        }
+        if (addedCount == 0) return
+        Timber.w(
+            "Sonos incremental: AddURIToQueue x%d starting at position %d",
+            addedCount,
+            prefixLen + 1,
+        )
+        for (i in 0 until addedCount) {
+            val ref = newQueue[prefixLen + i]
+            val token = streamTokens.mint(ref.id)
+            transport.addURIToQueue(
+                uri = token.url,
+                mime = token.mime,
+                title = token.title,
+                enqueuedURIPosition = prefixLen + i + 1,
+            )
+            if (i > 0) delay(EXTEND_THROTTLE_MS)
+        }
+    }
+
+    private fun commonPrefixLength(a: List<String>, b: List<String>): Int {
+        val limit = minOf(a.size, b.size)
+        for (i in 0 until limit) {
+            if (a[i] != b[i]) return i
+        }
+        return limit
+    }
+
+    private fun commonSuffixLength(a: List<String>, b: List<String>): Int {
+        val limit = minOf(a.size, b.size)
+        for (i in 0 until limit) {
+            if (a[a.size - 1 - i] != b[b.size - 1 - i]) return i
+        }
+        return limit
+    }
+
+    /**
+     * Called when the active UPnP route drops unexpectedly (the poll loop's
+     * consecutive-failure threshold tripping). Captures the last remote
+     * position + play state, clears UPnP selection, and resumes local ExoPlayer at
+     * the same point. Skips the Stop SOAP (device already unreachable).
+     * The snackbar is handled independently by the NowPlaying surface
+     * collecting the same [PlayerFactory.dropEvents] via PlayerController.
+     */
+    private fun handleRemoteDrop() {
+        val capturedPositionMs = remoteState.positionMs
+        // Resume on the operator's last play-intent, not the observed remote
+        // state: after a pause, isPlaying is false, but a failed play() that
+        // triggered this drop means the operator DID ask to play -- honor it.
+        val wasPlayingRemote = remoteState.lastPlayIntent
+        activeUpnpHolder.set(null)
+        activeUpnpHolder.setTarget(null)
+        selectedUpnpRouteIdInternal.value = null
+        playerController.seekTo(capturedPositionMs)
+        if (wasPlayingRemote) playerController.play()
    }

    /**
@@ -163,46 +509,302 @@ class OutputPickerController @Inject constructor(
    }

    private fun selectSystem(route: OutputRoute) {
+        val wasUpnp = selectedUpnpRouteIdInternal.value
+        if (wasUpnp != null) {
+            val active = activeUpnpHolder.active.value
+            val capturedPositionMs = remoteState.positionMs
+            val wasPlayingRemote = remoteState.isPlaying
+            scope.launch {
+                runCatching { active?.avTransport?.stop() }
+                    .onFailure { Timber.w(it, "UPnP Stop failed during disconnect") }
+                activeUpnpHolder.set(null)
+                activeUpnpHolder.setTarget(null)
+                selectedUpnpRouteIdInternal.value = null
+                playerController.seekTo(capturedPositionMs)
+                if (wasPlayingRemote) playerController.play()
+            }
+        }
        val target = mediaRouter.routes.firstOrNull { it.id == route.id } ?: return
        mediaRouter.selectRoute(target)
    }

    /**
-     * Drive the UPnP renderer: mint a token for the currently playing
-     * track, set the renderer's URI, play, then pause local playback so
-     * audio yields to the speaker. Wrapped in `runCatching` at each
-     * step — token failure, transport-lookup failure, and SOAP failure
-     * each abandon the selection cleanly rather than crashing. Failures
-     * log at warn level via Timber so on-device verification can find
-     * the cause in logcat (OkHttp's logger doesn't cover our own
-     * deserialize / SOAP-parse code paths).
+     * Drive the UPnP renderer using Sonos native queue mode:
+     * clear the device's queue, load every track from our local queue
+     * via AddURIToQueue, point the transport at the queue URI, seek to
+     * the current index, and play. Wrapped in `runCatching` — SOAP
+     * failure abandons the selection cleanly.
+     *
+     * Order of operations is deliberate:
+     *  1. Pause local so the user doesn't keep hearing local audio.
+     *  2. Set target early so ForwardingPlayer drops transport taps
+     *     while the 17-second queue load is in progress.
+     *  3. Wire active LAST (after loadQueueOnSonos) so SOAP commands
+     *     are never routed to a half-loaded Sonos queue.
     */
-    private suspend fun selectUpnp(route: OutputRoute) {
-        val trackId = playerController.uiState.value.currentTrack?.id
-        if (trackId == null) {
+    private suspend fun selectUpnp(route: OutputRoute) = selectUpnpMutex.withLock {
+        val uiState = playerController.uiState.value
+        val currentTrack = uiState.currentTrack
+        if (currentTrack == null) {
            Timber.w("UPnP select skipped: no currentTrack (start playback first)")
-            return
+            return@withLock
        }
-        val transport = upnpDiscovery.transportFor(route.id)
+        // Honor Sonos topology: pick the coordinator's route when the user
+        // tapped a group row. Suppression in routesState already keeps the
+        // visible row at the coordinator's id, so this is identity in the
+        // common case -- defensive for follow-up flows.
+        val effectiveRoute = upnpDiscovery.coordinatorRouteFor(route.id)
+            ?.let { OutputRoute.fromUpnpRoute(it) } ?: route
+        val transport = upnpDiscovery.transportFor(effectiveRoute.id)
        if (transport == null) {
            Timber.w(
-                "UPnP select skipped: no transport for route id=${route.id} " +
+                "UPnP select skipped: no transport for route id=${effectiveRoute.id} " +
                    "(route disappeared or id mismatch with discovery list)",
            )
-            return
+            return@withLock
        }
-        runCatching {
-            Timber.i("UPnP select: mint token for track=$trackId, route=${route.name}")
-            val token = castApi.streamToken(StreamTokenRequest(trackId = trackId))
-            Timber.i("UPnP select: SetAVTransportURI to ${token.url}")
-            transport.setAVTransportURI(token.url)
-            Timber.i("UPnP select: Play")
-            transport.play()
+        val rendering = renderingClientFor(effectiveRoute.id)
+        // Pause local before flipping UI state -- user shouldn't keep hearing
+        // local audio while we queue up Sonos.
        playerController.pause()
-            Timber.i("UPnP select: done")
-        }.onFailure { e ->
-            Timber.w(e, "UPnP select failed for route ${route.id}")
+        selectedUpnpRouteIdInternal.value = effectiveRoute.id
+        // If the renderer is already playing this exact queue (a "stray"
+        // session we got disconnected from), attach to it in place instead of
+        // wiping + reloading -- no jarring restart, and skip/seek land on its
+        // live queue. Falls through to the clear+reload path when it isn't ours.
+        if (tryAdoptRunningSession(transport, rendering, effectiveRoute, uiState.queue)) {
+            return@withLock
        }
+        // Mark UPnP loading. ForwardingPlayer overrides drop transport commands
+        // silently while target is set but active is null -- the user's premature
+        // taps don't hit Sonos's stale state from a prior session.
+        activeUpnpHolder.setTarget(effectiveRoute.id)
+        runCatching {
+            loadQueueOnSonos(transport, effectiveRoute, uiState.queue, uiState.queueIndex)
+            // Wire active LAST -- SOAP path is now safe to use.
+            activeUpnpHolder.set(
+                ActiveUpnp(
+                    routeId = effectiveRoute.id,
+                    routeName = effectiveRoute.name,
+                    avTransport = transport,
+                    rendering = rendering,
+                ),
+            )
+            // Selecting a route loads the queue and Plays on the renderer, so
+            // the standing intent is "play" -- a later drop should resume local.
+            remoteState.setPlayIntent(true)
+        }.onFailure { e ->
+            Timber.w(e, "UPnP select failed for route ${effectiveRoute.id}")
+            activeUpnpHolder.set(null)
+            activeUpnpHolder.setTarget(null)
+            selectedUpnpRouteIdInternal.value = null
+        }
+    }
+
+    /**
+     * The renderer's current position + transport state, validated as an
+     * adoptable continuation of our local queue: same track id at the same
+     * 1-based index. Null means "not ours / not playing" -> caller reloads.
+     */
+    private data class AdoptPlan(
+        val localIndex: Int,
+        val positionMs: Long,
+        val durationMs: Long,
+        val trackUri: String,
+        val trackNumber: Int,
+        val playing: Boolean,
+    )
+
+    /**
+     * Attach to a renderer that is *already* playing our queue (a session the
+     * phone got disconnected from but the speaker kept streaming) instead of
+     * clearing + reloading it. Probes the renderer's live state, and if it's
+     * mid-playback on the same track id at the same queue index, syncs the
+     * local cursor to match and wires [ActiveUpnpHolder] -- the speaker never
+     * skips a beat, and skip/seek now drive its live queue. Returns false (and
+     * the caller does the full clear+reload) when the renderer isn't playing
+     * our queue. The local player is already paused by the caller.
+     */
+    private suspend fun tryAdoptRunningSession(
+        transport: AVTransportClient,
+        rendering: RenderingControlClient?,
+        route: OutputRoute,
+        localQueue: List<TrackRef>,
+    ): Boolean {
+        val plan = probeAdoptable(transport, route, localQueue) ?: return false
+        Timber.w(
+            "UPnP adopt: attaching to live session on %s at track %d (%dms)",
+            route.name, plan.trackNumber, plan.positionMs,
+        )
+        // active is still null here, so this aligns the *local* cursor without
+        // emitting SOAP; the holder.set below then starts the poll loop, which
+        // reconciles to the renderer's advancing position from here.
+        playerController.moveCursorTo(plan.localIndex, plan.positionMs)
+        remoteState.applyPositionInfo(
+            positionMs = plan.positionMs,
+            durationMs = plan.durationMs,
+            trackUri = plan.trackUri,
+            trackNumber = plan.trackNumber,
+        )
+        remoteState.setPlayIntent(plan.playing)
+        activeUpnpHolder.set(
+            ActiveUpnp(
+                routeId = route.id,
+                routeName = route.name,
+                avTransport = transport,
+                rendering = rendering,
+            ),
+        )
+        return true
+    }
+
+    private suspend fun probeAdoptable(
+        transport: AVTransportClient,
+        route: OutputRoute,
+        localQueue: List<TrackRef>,
+    ): AdoptPlan? {
+        val probe = runCatching {
+            transport.getTransportInfo() to transport.getPositionInfo()
+        }.getOrElse {
+            Timber.w(it, "UPnP adopt: probe failed for %s; will reload", route.name)
+            return null
+        }
+        val (info, pos) = probe
+        val idx0 = pos.track - 1
+        val playingId = trackIdFromStreamUrl(pos.trackUri)
+        val midPlayback =
+            info.state == TransportState.PLAYING || info.state == TransportState.PAUSED
+        val aligned = midPlayback && playingId != null &&
+            idx0 in localQueue.indices && localQueue[idx0].id == playingId
+        return if (aligned) {
+            AdoptPlan(
+                localIndex = idx0,
+                positionMs = pos.relTimeMs,
+                durationMs = pos.trackDurationMs,
+                trackUri = pos.trackUri,
+                trackNumber = pos.track,
+                playing = info.state == TransportState.PLAYING,
+            )
+        } else {
+            null
+        }
+    }
+
+    /** Extract our track id from a stream URL `.../api/tracks/<id>/stream...`. */
+    private fun trackIdFromStreamUrl(url: String): String? {
+        val segments = url.toHttpUrlOrNull()?.pathSegments ?: return null
+        val i = segments.indexOf("tracks")
+        return if (i >= 0) segments.getOrNull(i + 1) else null
+    }
+
+    private suspend fun loadQueueOnSonos(
+        transport: AVTransportClient,
+        route: OutputRoute,
+        queue: List<TrackRef>,
+        currentIndex: Int,
+    ) {
+        Timber.w("UPnP select: clear queue on %s", route.name)
+        transport.removeAllTracksFromQueue()
+        val initialEnd = (currentIndex + 1).coerceAtMost(queue.size)
+        val initialBatch = queue.subList(0, initialEnd)
+        Timber.w(
+            "UPnP select: add %d initial tracks (currentIndex=%d, totalQueue=%d)",
+            initialBatch.size, currentIndex, queue.size,
+        )
+        initialBatch.forEachIndexed { idx, ref ->
+            val token = streamTokens.mint(ref.id)
+            transport.addURIToQueue(
+                uri = token.url,
+                mime = token.mime,
+                title = token.title,
+                enqueuedURIPosition = idx + 1,
+            )
+        }
+        val coordinatorUdn = route.id.bareUdn()
+        val queueUri = "x-rincon-queue:$coordinatorUdn#0"
+        Timber.w("UPnP select: SetAVTransportURI %s", queueUri)
+        transport.setAVTransportURI(queueUri, "")
+        Timber.w("UPnP select: Seek to track %d", currentIndex + 1)
+        transport.seekToTrack(currentIndex + 1)
+        Timber.w("UPnP select: Play")
+        transport.play()
+        Timber.w("UPnP select: initial done; backgrounding remainder")
+        val remaining = queue.drop(initialEnd)
+        if (remaining.isNotEmpty()) {
+            scope.launch { extendQueueOnSonos(transport, route, remaining, initialEnd) }
+        }
+    }
+
+    /**
+     * Background-append tracks after activation. Runs concurrently with
+     * Sonos playback. Cancels if the user disconnects from this route
+     * (active.routeId changes or becomes null). Tolerates individual
+     * AddURIToQueue failures — log and continue so some tracks loaded
+     * is better than zero tracks loaded.
+     */
+    private suspend fun extendQueueOnSonos(
+        transport: AVTransportClient,
+        route: OutputRoute,
+        tracks: List<TrackRef>,
+        startPosition: Int,
+    ) {
+        Timber.w(
+            "UPnP extend: appending %d tracks starting at position %d",
+            tracks.size, startPosition + 1,
+        )
+        var consecutiveFailures = 0
+        var succeeded = 0
+        var aborted = false
+        for ((i, ref) in tracks.withIndex()) {
+            if (aborted) break
+            if (activeUpnpHolder.active.value?.routeId != route.id) {
+                Timber.w("UPnP extend: cancelled at offset %d (route changed)", i)
+                aborted = true
+            } else {
+                val outcome = runCatching {
+                    val token = streamTokens.mint(ref.id)
+                    transport.addURIToQueue(
+                        uri = token.url,
+                        mime = token.mime,
+                        title = token.title,
+                        enqueuedURIPosition = startPosition + i + 1,
+                    )
+                }
+                if (outcome.isSuccess) {
+                    consecutiveFailures = 0
+                    succeeded += 1
+                    // Throttle the burst so we don't tickle Sonos's burst-add
+                    // rejection -- logcat 2026-06-04 showed 33 consecutive
+                    // failures clustered at ~10ms intervals once offset 39 was
+                    // reached, which looks like a rate-limit kicking in. The
+                    // delay is small enough that extending 100 tracks adds
+                    // only ~5s to background work that's already async.
+                    delay(EXTEND_THROTTLE_MS)
+                } else {
+                    consecutiveFailures += 1
+                    val e = outcome.exceptionOrNull()
+                    val detail = (e as? SoapFaultException)?.let {
+                        "code=${it.code} desc=${it.description}"
+                    } ?: e?.message
+                    Timber.w(e, "UPnP extend: append failed at offset %d -- %s", i, detail)
+                    if (consecutiveFailures >= EXTEND_ABORT_AFTER_FAILURES) {
+                        Timber.w(
+                            "UPnP extend: aborting after %d consecutive failures",
+                            consecutiveFailures,
+                        )
+                        aborted = true
+                    }
+                }
+            }
+        }
+        Timber.w("UPnP extend: done (%d / %d appended)", succeeded, tracks.size)
+    }
+
+    private fun renderingClientFor(routeId: String): RenderingControlClient? {
+        val rcUrl = upnpDiscovery.routes.value
+            .firstOrNull { it.id == routeId }
+            ?.renderingControlUrl ?: return null
+        return RenderingControlClient(SoapClient(okHttp), rcUrl)
    }

    private fun refresh() {
@@ -214,24 +816,26 @@ class OutputPickerController @Inject constructor(
            .filter { it.matchesSelector(selector) }
            .map { OutputRoute.fromRouteInfo(it) }
        val current = OutputRoute.fromRouteInfo(mediaRouter.selectedRoute)
-        return RouteSnapshot(current = current, available = sortRoutes(current, all))
+        return RouteSnapshot(current = current, available = sortRoutes(all))
    }

    /**
-     * Selected first, then Bluetooth, then Wired, then BuiltIn, then
-     * Other (UPnP renderers fall in Other). Keeps the active output at
-     * the top + likely-wanted alternatives next + fallback last.
+     * BuiltIn "Phone speaker" pinned first; everything else
+     * alphabetical. Selection state is conveyed by the radio button
+     * indicator in the picker row, not by sort order.
     */
-    private fun sortRoutes(current: OutputRoute, all: List<OutputRoute>): List<OutputRoute> {
-        val rank: (OutputRoute) -> Int = { route ->
-            when {
-                route.id == current.id -> 0
-                route.kind == OutputRoute.Kind.Bluetooth -> 1
-                route.kind == OutputRoute.Kind.Wired -> 2
-                route.kind == OutputRoute.Kind.BuiltIn -> 3
-                else -> 4
+    private fun sortRoutes(all: List<OutputRoute>): List<OutputRoute> {
+        val (builtIn, rest) = all.partition { it.kind == OutputRoute.Kind.BuiltIn }
+        return builtIn + rest.sortedBy { it.name.lowercase() }
    }
-        }
-        return all.sortedBy(rank)
+
+    private companion object {
+        const val EXTEND_ABORT_AFTER_FAILURES = 3
+        const val EXTEND_THROTTLE_MS = 50L
+
+        // 5 minutes of continuous non-playing on a UPnP route before we
+        // revert to the phone speaker, so a stale Sonos selection can't make
+        // a later "tap play" do nothing.
+        const val IDLE_REVERT_MS = 5 * 60 * 1000L
    }
 }
@@ -4,8 +4,11 @@ import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.heightIn
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
@@ -69,13 +72,20 @@ fun OutputPickerSheet(
                color = MaterialTheme.colorScheme.onSurface,
                modifier = Modifier.padding(vertical = 8.dp),
            )
-            snapshot.available.forEach { route ->
+            LazyColumn(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .heightIn(max = ROUTE_LIST_MAX_HEIGHT_DP.dp),
+                verticalArrangement = Arrangement.spacedBy(4.dp),
+            ) {
+                items(items = snapshot.available, key = { it.id }) { route ->
                    RouteRow(
                        route = route,
                        isSelected = route.id == snapshot.current.id,
                        onClick = { onRouteSelected(route) },
                    )
                }
+            }
            if (permissionDenied) {
                PermissionHintRow()
            }
@@ -123,7 +133,7 @@ private fun RouteRow(
                    maxLines = 2,
                    overflow = TextOverflow.Ellipsis,
                )
-                val subtitle = route.description ?: defaultSubtitle(route)
+                val subtitle = route.description ?: defaultSubtitle(route, isSelected)
                Text(
                    text = subtitle,
                    style = MaterialTheme.typography.bodySmall,
@@ -188,13 +198,17 @@ private fun MulticastHintRow() {
    }
 }

-private fun defaultSubtitle(route: OutputRoute): String = when (route.kind) {
+// isSelected (route == the active/selected route) drives the Bluetooth
+// "Connected" subtitle. RouteInfo.connectionState can't — it stays
+// DISCONNECTED for local SYSTEM routes even when they're in use.
+private fun defaultSubtitle(route: OutputRoute, isSelected: Boolean): String = when (route.kind) {
    OutputRoute.Kind.BuiltIn -> "Phone speaker"
    OutputRoute.Kind.Wired -> "Wired"
-    OutputRoute.Kind.Bluetooth -> if (route.isConnected) "Connected" else "Available"
+    OutputRoute.Kind.Bluetooth -> if (isSelected) "Connected" else "Available"
    OutputRoute.Kind.Cast -> "Cast"
    OutputRoute.Kind.Other -> "Available"
 }

 private const val ROW_ICON_DP = 24
 private const val HINT_ICON_DP = 20
+private const val ROUTE_LIST_MAX_HEIGHT_DP = 400
@@ -24,6 +24,7 @@ import javax.inject.Inject
@HiltViewModel
 class OutputPickerViewModel @Inject constructor(
    private val controller: OutputPickerController,
+    private val activeUpnpHolder: ActiveUpnpHolder,
 ) : ViewModel() {

    val routes: StateFlow<RouteSnapshot> = controller.routesState
@@ -33,6 +34,9 @@ class OutputPickerViewModel @Inject constructor(
            initialValue = controller.routesState.value,
        )

+    val activeUpnp: StateFlow<ActiveUpnp?> = activeUpnpHolder.active
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(STOP_TIMEOUT_MS), null)
+
    private val sheetVisibleInternal = MutableStateFlow(false)
    val sheetVisible: StateFlow<Boolean> = sheetVisibleInternal.asStateFlow()

@@ -21,7 +21,6 @@ data class OutputRoute(
    val description: String?,
    val kind: Kind,
    val protocol: Protocol,
-    val isConnected: Boolean,
 ) {
    enum class Kind { BuiltIn, Wired, Bluetooth, Cast, Other }

@@ -43,9 +42,11 @@ data class OutputRoute(
        /**
         * Lift a MediaRouter [route] into the domain model. Kind is
         * inferred from [MediaRouter.RouteInfo.getDeviceType]; unknown
-         * device types fall through to [Kind.Other]. The
-         * `connectionState` proxy is good enough for the chip's
-         * "Connected"/"Available" subtitle.
+         * device types fall through to [Kind.Other]. "Active" is NOT an
+         * intrinsic of the route — the caller derives it by comparing to
+         * the selected route (RouteSnapshot.current), because
+         * RouteInfo.connectionState only reflects remote-route handshakes
+         * and stays DISCONNECTED for local SYSTEM routes even when in use.
         */
        fun fromRouteInfo(route: MediaRouter.RouteInfo): OutputRoute {
            val kind = when (route.deviceType) {
@@ -58,15 +59,12 @@ data class OutputRoute(
                MediaRouter.RouteInfo.DEVICE_TYPE_SPEAKER -> Kind.Other
                else -> Kind.Other
            }
-            val connected =
-                route.connectionState == MediaRouter.RouteInfo.CONNECTION_STATE_CONNECTED
            return OutputRoute(
                id = route.id,
                name = route.name,
                description = route.description,
                kind = kind,
                protocol = Protocol.SYSTEM,
-                isConnected = connected,
            )
        }

@@ -76,10 +74,10 @@ data class OutputRoute(
         * network speakers into the same `OutputPickerController`
         * routes stream the system routes come through.
         *
-         * `isConnected = false` because UPnP devices have no
-         * MediaRouter connection-state concept — they're always
-         * "available" on the LAN, and the picker's selected-route
-         * rendering handles the "currently playing" indicator.
+         * UPnP devices have no MediaRouter connection-state concept —
+         * they're always "available" on the LAN, and the picker's
+         * selected-route rendering handles the "currently playing"
+         * indicator.
         *
         * Subtitle is `manufacturer modelName` joined by a single
         * space, falling back to "Network speaker" when both fields
@@ -96,7 +94,6 @@ data class OutputRoute(
                description = description,
                kind = Kind.Other,
                protocol = Protocol.UPNP,
-                isConnected = false,
            )
        }
    }
@@ -3,12 +3,13 @@ package com.fabledsword.minstrel.player.output.upnp
 import okhttp3.HttpUrl

 /**
- * High-level wrapper for the UPnP AVTransport service. Three calls
- * for v1: SetAVTransportURI / Play / Stop. Pause + Seek deferred
- * until we have hardware in the loop to verify each device's quirks
- * (Sonos and BubbleUPnP accept the standard shape; some smart TVs
- * reject Pause without DIDL).
+ * High-level wrapper for the UPnP AVTransport service.
+ * Covers SetAVTransportURI / Play / Pause / Stop / Seek /
+ * GetPositionInfo / GetTransportInfo / queue management
+ * (RemoveAllTracksFromQueue, AddURIToQueue, Next, Previous, SeekToTrack).
 */
+// One method per AVTransport SOAP verb; splitting would obscure the 1:1 protocol mapping.
+@Suppress("TooManyFunctions")
 class AVTransportClient(
    private val soap: SoapClient,
    private val controlUrl: HttpUrl,
@@ -26,6 +27,135 @@ class AVTransportClient(
        )
    }

+    /**
+     * Convenience overload that builds DIDL-Lite metadata around [uri]
+     * + [mime] + [title] and forwards to [setAVTransportURI]. Sonos
+     * rejects empty DIDL with vendor error 1023; this constructs the
+     * minimal-but-Sonos-acceptable shape:
+     *   <DIDL-Lite>
+     *     <item id="0" parentID="-1" restricted="1">
+     *       <dc:title>...</dc:title>
+     *       <upnp:class>object.item.audioItem.musicTrack</upnp:class>
+     *       <res protocolInfo="http-get:*:<mime>:*">...</res>
+     *     </item>
+     *   </DIDL-Lite>
+     * Generic UPnP renderers tolerate this shape too — there's no
+     * downside to always sending it. Title falls back to "Minstrel"
+     * when the caller doesn't supply one.
+     */
+    suspend fun setAVTransportURIWithMetadata(uri: String, mime: String, title: String) {
+        val safeTitle = title.ifBlank { "Minstrel" }
+        setAVTransportURI(uri, buildDidlLite(uri, mime, safeTitle))
+    }
+
+    /**
+     * Remove all tracks from the renderer's queue. UPnP action name is
+     * `RemoveAllTracksFromQueue`. Used at activation time to clear out any
+     * leftover queue from prior sessions before loading our local queue.
+     */
+    suspend fun removeAllTracksFromQueue() {
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "RemoveAllTracksFromQueue",
+            args = mapOf("InstanceID" to "0"),
+        )
+    }
+
+    /**
+     * Remove a contiguous range of tracks from the renderer's native queue.
+     * Sonos-specific extension to AVTransport; `UpdateID=0` skips the queue-
+     * version check so this works without first calling GetQueue to learn
+     * the current update id.
+     *
+     * [startingIndex] is 1-based per Sonos convention; [numberOfTracks] is
+     * the count to remove. Used by OutputPickerController's incremental
+     * queue resync path (radio-append: remove tail, then AddURIToQueue
+     * the new items).
+     */
+    suspend fun removeTrackRangeFromQueue(startingIndex: Int, numberOfTracks: Int) {
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "RemoveTrackRangeFromQueue",
+            args = mapOf(
+                "InstanceID" to "0",
+                "UpdateID" to "0",
+                "StartingIndex" to startingIndex.toString(),
+                "NumberOfTracks" to numberOfTracks.toString(),
+            ),
+        )
+    }
+
+    /**
+     * Append a track to the renderer's queue. Sonos returns the assigned
+     * track number + new total queue length in the response, but we don't
+     * read those (we know our intended position). DIDL-Lite metadata is
+     * required; reuses the same shape as [setAVTransportURIWithMetadata].
+     *
+     * [enqueuedURIPosition] is 1-based; 0 means "append to end" per UPnP.
+     * Our caller passes 1, 2, 3, ... to ensure stable order.
+     */
+    suspend fun addURIToQueue(
+        uri: String,
+        mime: String,
+        title: String,
+        enqueuedURIPosition: Int = 0,
+    ) {
+        val safeTitle = title.ifBlank { "Minstrel" }
+        val didl = buildDidlLite(uri, mime, safeTitle)
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "AddURIToQueue",
+            args = mapOf(
+                "InstanceID" to "0",
+                "EnqueuedURI" to uri,
+                "EnqueuedURIMetaData" to didl,
+                "DesiredFirstTrackNumberEnqueued" to enqueuedURIPosition.toString(),
+                "EnqueueAsNext" to "0",
+            ),
+        )
+    }
+
+    /** Skip to the next track in the renderer's queue. */
+    suspend fun next() {
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "Next",
+            args = mapOf("InstanceID" to "0"),
+        )
+    }
+
+    /** Skip to the previous track in the renderer's queue. */
+    suspend fun previous() {
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "Previous",
+            args = mapOf("InstanceID" to "0"),
+        )
+    }
+
+    /**
+     * Seek to a specific track in the queue. UPnP Seek unit "TRACK_NR";
+     * target is the 1-based track index. Separate from the existing
+     * [seek] which uses unit REL_TIME for position-within-track.
+     */
+    suspend fun seekToTrack(trackNumber: Int) {
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "Seek",
+            args = mapOf(
+                "InstanceID" to "0",
+                "Unit" to "TRACK_NR",
+                "Target" to trackNumber.toString(),
+            ),
+        )
+    }
+
    suspend fun play() {
        soap.call(
            controlUrl = controlUrl,
@@ -35,6 +165,15 @@ class AVTransportClient(
        )
    }

+    suspend fun pause() {
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "Pause",
+            args = mapOf("InstanceID" to "0"),
+        )
+    }
+
    suspend fun stop() {
        soap.call(
            controlUrl = controlUrl,
@@ -44,7 +183,114 @@ class AVTransportClient(
        )
    }

+    suspend fun seek(positionMs: Long) {
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "Seek",
+            args = mapOf(
+                "InstanceID" to "0",
+                "Unit" to "REL_TIME",
+                "Target" to formatHhMmSs(positionMs),
+            ),
+        )
+    }
+
+    suspend fun getPositionInfo(): PositionInfo {
+        val result = soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "GetPositionInfo",
+            args = mapOf("InstanceID" to "0"),
+        )
+        return PositionInfo(
+            track = result["Track"]?.toIntOrNull() ?: 0,
+            trackUri = result["TrackURI"].orEmpty(),
+            relTimeMs = parseHhMmSs(result["RelTime"].orEmpty()),
+            trackDurationMs = parseHhMmSs(result["TrackDuration"].orEmpty()),
+        )
+    }
+
+    suspend fun getTransportInfo(): TransportInfo {
+        val result = soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "GetTransportInfo",
+            args = mapOf("InstanceID" to "0"),
+        )
+        val state = when (result["CurrentTransportState"]) {
+            "PLAYING" -> TransportState.PLAYING
+            "PAUSED_PLAYBACK" -> TransportState.PAUSED
+            "STOPPED" -> TransportState.STOPPED
+            "TRANSITIONING" -> TransportState.TRANSITIONING
+            else -> TransportState.UNKNOWN
+        }
+        return TransportInfo(state)
+    }
+
+    private fun buildDidlLite(uri: String, mime: String, title: String): String {
+        // Sonos requires (a) the rinconnetworks namespace declared on
+        // <DIDL-Lite> even if we don't use Rincon elements directly, and
+        // (b) a <desc id="cdudn"> element identifying the URI as an
+        // external (non-Sonos-library) source. Without those, Sonos
+        // discards our metadata content and regenerates its own with
+        // class=object.item and the URL query string as the title
+        // (logcat 2026-06-04 confirmed). Match SoCo's pattern.
+        val safeTitle = title.ifBlank { "Minstrel" }
+        return buildString {
+            append("<DIDL-Lite ")
+            append("xmlns=\"urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/\" ")
+            append("xmlns:dc=\"http://purl.org/dc/elements/1.1/\" ")
+            append("xmlns:upnp=\"urn:schemas-upnp-org:metadata-1-0/upnp/\" ")
+            append("xmlns:r=\"urn:schemas-rinconnetworks-com:metadata-1-0/\">")
+            append("<item id=\"-1\" parentID=\"-1\" restricted=\"true\">")
+            append("<dc:title>").append(xmlEscape(safeTitle)).append("</dc:title>")
+            append("<upnp:class>object.item.audioItem.musicTrack</upnp:class>")
+            append("<res protocolInfo=\"http-get:*:").append(xmlEscape(mime))
+            append(":*\">").append(xmlEscape(uri)).append("</res>")
+            append("<desc id=\"cdudn\" ")
+            append("nameSpace=\"urn:schemas-rinconnetworks-com:metadata-1-0/\">")
+            append("RINCON_AssociatedZPUDN")
+            append("</desc>")
+            append("</item>")
+            append("</DIDL-Lite>")
+        }
+    }
+
+    private fun formatHhMmSs(positionMs: Long): String {
+        val totalSec = (positionMs / MILLIS_PER_SECOND).coerceAtLeast(0)
+        val h = totalSec / SECONDS_PER_HOUR
+        val m = (totalSec % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE
+        val s = totalSec % SECONDS_PER_MINUTE
+        return "%d:%02d:%02d".format(h, m, s)
+    }
+
+    private fun parseHhMmSs(raw: String): Long {
+        val parts = raw.split(':').mapNotNull { it.trim().toLongOrNull() }
+        return if (parts.size == EXPECTED_HMS_PARTS) {
+            val (h, m, s) = parts
+            ((h * SECONDS_PER_HOUR) + (m * SECONDS_PER_MINUTE) + s) * MILLIS_PER_SECOND
+        } else {
+            0L
+        }
+    }
+
    private companion object {
        const val SERVICE_TYPE = "urn:schemas-upnp-org:service:AVTransport:1"
+        const val MILLIS_PER_SECOND = 1000L
+        const val SECONDS_PER_MINUTE = 60L
+        const val SECONDS_PER_HOUR = 3600L
+        const val EXPECTED_HMS_PARTS = 3
    }
 }
+
+data class PositionInfo(
+    val track: Int,
+    val trackUri: String,
+    val relTimeMs: Long,
+    val trackDurationMs: Long,
+)
+
+enum class TransportState { PLAYING, PAUSED, STOPPED, TRANSITIONING, UNKNOWN }
+
+data class TransportInfo(val state: TransportState)
@@ -22,10 +22,12 @@ data class DeviceDescription(
    val modelName: String,
    val avTransportControlUrl: HttpUrl,
    val renderingControlUrl: HttpUrl?,
+    val zoneGroupTopologyControlUrl: HttpUrl? = null,
 ) {
    companion object {
        private const val AVT_SERVICE_TYPE = "urn:schemas-upnp-org:service:AVTransport:1"
        private const val RC_SERVICE_TYPE = "urn:schemas-upnp-org:service:RenderingControl:1"
+        private const val ZGT_SERVICE_TYPE = "urn:schemas-upnp-org:service:ZoneGroupTopology:1"

        private const val TAG_SERVICE = "service"
        private const val TAG_UDN = "UDN"
@@ -43,6 +45,7 @@ data class DeviceDescription(
         */
        fun parse(xml: String, base: HttpUrl): DeviceDescription? {
            val parser = XmlPullParserFactory.newInstance().newPullParser().apply {
+                setFeature(XmlPullParser.FEATURE_PROCESS_NAMESPACES, true)
                setInput(xml.reader())
            }
            val acc = ParseState()
@@ -58,6 +61,7 @@ data class DeviceDescription(
                modelName = acc.modelName,
                avTransportControlUrl = avt,
                renderingControlUrl = acc.rcControlUrl,
+                zoneGroupTopologyControlUrl = acc.zgtControlUrl,
            )
        }

@@ -91,6 +95,7 @@ data class DeviceDescription(
            when (acc.serviceType) {
                AVT_SERVICE_TYPE -> acc.avtControlUrl = resolved
                RC_SERVICE_TYPE -> acc.rcControlUrl = resolved
+                ZGT_SERVICE_TYPE -> acc.zgtControlUrl = resolved
            }
            acc.inService = false
        }
@@ -115,6 +120,7 @@ data class DeviceDescription(
        var modelName: String = ""
        var avtControlUrl: HttpUrl? = null
        var rcControlUrl: HttpUrl? = null
+        var zgtControlUrl: HttpUrl? = null
        var inService: Boolean = false
        var serviceType: String = ""
        var serviceControlUrl: String = ""
@@ -0,0 +1,44 @@
+package com.fabledsword.minstrel.player.output.upnp
+
+import okhttp3.HttpUrl
+
+/**
+ * RenderingControl service wrapper for hardware-volume routing while a
+ * UPnP route is active. GetVolume seeds an in-memory cache; SetVolume
+ * is invoked by NowPlayingScreen's volume-key interceptor. Clamps to
+ * the UPnP-standard 0..100 range.
+ */
+class RenderingControlClient(
+    private val soap: SoapClient,
+    private val controlUrl: HttpUrl,
+) {
+    suspend fun getVolume(channel: String = "Master"): Int {
+        val args = soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "GetVolume",
+            args = mapOf("InstanceID" to "0", "Channel" to channel),
+        )
+        return args["CurrentVolume"]?.toIntOrNull() ?: 0
+    }
+
+    suspend fun setVolume(volume: Int, channel: String = "Master") {
+        val clamped = volume.coerceIn(VOLUME_MIN, VOLUME_MAX)
+        soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "SetVolume",
+            args = mapOf(
+                "InstanceID" to "0",
+                "Channel" to channel,
+                "DesiredVolume" to clamped.toString(),
+            ),
+        )
+    }
+
+    private companion object {
+        const val SERVICE_TYPE = "urn:schemas-upnp-org:service:RenderingControl:1"
+        const val VOLUME_MIN = 0
+        const val VOLUME_MAX = 100
+    }
+}
@@ -1,5 +1,6 @@
 package com.fabledsword.minstrel.player.output.upnp

+import java.util.concurrent.atomic.AtomicInteger
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 import okhttp3.HttpUrl
@@ -8,6 +9,7 @@ import okhttp3.Request
 import okhttp3.RequestBody.Companion.toRequestBody
 import org.xmlpull.v1.XmlPullParser
 import org.xmlpull.v1.XmlPullParserFactory
+import timber.log.Timber

 /**
 * Minimal SOAP/UPnP envelope builder + POST. Hand-rolled rather than
@@ -25,6 +27,7 @@ import org.xmlpull.v1.XmlPullParserFactory
 */
 class SoapClient(
    private val okHttp: OkHttpClient,
+    private val onRawResponse: ((action: String, body: String) -> Unit)? = null,
 ) {
    suspend fun call(
        controlUrl: HttpUrl,
@@ -41,6 +44,7 @@ class SoapClient(
            .build()
        okHttp.newCall(request).execute().use { response ->
            val body = response.body?.string().orEmpty()
+            onRawResponse?.invoke(action, body)
            if (!response.isSuccessful) {
                throw SoapFaultException(faultCodeOf(body), faultDescriptionOf(body))
            }
@@ -69,15 +73,9 @@ class SoapClient(
        append("</s:Envelope>")
    }

-    private fun xmlEscape(v: String): String = v
-        .replace("&", "&amp;")
-        .replace("<", "&lt;")
-        .replace(">", "&gt;")
-        .replace("\"", "&quot;")
-        .replace("'", "&apos;")
-
    private fun parseResponseArgs(body: String, action: String): Map<String, String> {
        val parser = XmlPullParserFactory.newInstance().newPullParser().apply {
+            setFeature(XmlPullParser.FEATURE_PROCESS_NAMESPACES, true)
            setInput(body.reader())
        }
        val responseTag = "${action}Response"
@@ -102,7 +100,7 @@ class SoapClient(
            } else {
                if (inResponse) {
                    val name = parser.name
-                    val text = runCatching { parser.nextText() }.getOrDefault("")
+                    val text = readElementContent(parser, name)
                    args[name] = text
                }
                inResponse
@@ -112,6 +110,59 @@ class SoapClient(
        else -> inResponse
    }

+    /**
+     * Read the content of the currently-started element. Try nextText() first
+     * (works when the content is text -- escaped XML included). If that throws
+     * (because the content is nested elements), manually walk to the matching
+     * END_TAG, accumulating text and re-serializing child elements.
+     *
+     * Some Sonos firmware sends the GetZoneGroupState payload as nested XML
+     * elements without escaping; this fallback recovers that path.
+     */
+    private fun readElementContent(parser: XmlPullParser, tagName: String): String {
+        return runCatching { parser.nextText() }.getOrElse {
+            readUntilEndTag(parser, tagName)
+        }
+    }
+
+    private fun readUntilEndTag(parser: XmlPullParser, tagName: String): String {
+        val sb = StringBuilder()
+        var depth = 1
+        var done = false
+        while (!done && depth > 0) {
+            when (parser.next()) {
+                XmlPullParser.START_TAG -> {
+                    appendStartTag(sb, parser)
+                    depth += 1
+                }
+                XmlPullParser.END_TAG -> {
+                    depth -= 1
+                    if (depth == 0 && parser.name == tagName) {
+                        done = true
+                    } else {
+                        sb.append("</").append(parser.name).append('>')
+                    }
+                }
+                XmlPullParser.TEXT -> sb.append(parser.text.orEmpty())
+                XmlPullParser.END_DOCUMENT -> done = true
+                else -> Unit
+            }
+        }
+        return sb.toString()
+    }
+
+    private fun appendStartTag(sb: StringBuilder, parser: XmlPullParser) {
+        sb.append('<').append(parser.name)
+        for (i in 0 until parser.attributeCount) {
+            sb.append(' ')
+                .append(parser.getAttributeName(i))
+                .append("=\"")
+                .append(parser.getAttributeValue(i))
+                .append('"')
+        }
+        sb.append('>')
+    }
+
    private fun faultCodeOf(body: String): String =
        extractBetween(body, "<errorCode>", "</errorCode>") ?: "unknown"

@@ -138,3 +189,42 @@ class SoapClient(
 */
 class SoapFaultException(val code: String, val description: String) :
    Exception("SOAP fault $code: $description")
+
+private const val MAX_DIAGNOSTIC_RESPONSES = 6  // 3 polls x 2 action types
+private const val MAX_BODY_LOG_CHARS = 2048
+
+/**
+ * Returns a [SoapClient] that logs the raw response body for the first
+ * [MAX_DIAGNOSTIC_RESPONSES] calls for actions in [DIAGNOSTIC_ACTIONS]
+ * (GetPositionInfo, GetTransportInfo, GetZoneGroupState). After that the
+ * callback is a no-op so there is no persistent log spam. Logged at WARN
+ * so release builds capture it without a separate log-level override.
+ */
+internal fun loggingSoapClient(okHttp: OkHttpClient, label: String): SoapClient {
+    val counter = AtomicInteger(0)
+    return SoapClient(okHttp) { action, body ->
+        if (action !in DIAGNOSTIC_ACTIONS) return@SoapClient
+        val n = counter.incrementAndGet()
+        if (n <= MAX_DIAGNOSTIC_RESPONSES) {
+            Timber.w(
+                "UPnP %s response #%d (%s): %s",
+                label, n, action,
+                body.take(MAX_BODY_LOG_CHARS),
+            )
+        }
+    }
+}
+
+private val DIAGNOSTIC_ACTIONS = setOf(
+    "GetPositionInfo",
+    "GetTransportInfo",
+    "GetZoneGroupState",
+)
+
+/** XML-escapes a string value for embedding as text content inside a SOAP envelope. */
+internal fun xmlEscape(v: String): String = v
+    .replace("&", "&amp;")
+    .replace("<", "&lt;")
+    .replace(">", "&gt;")
+    .replace("\"", "&quot;")
+    .replace("'", "&apos;")
@@ -1,10 +1,14 @@
+@file:Suppress("TooManyFunctions") // discovery + Sonos topology + transport-lookup density
 package com.fabledsword.minstrel.player.output.upnp

 import android.content.Context
 import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.player.output.upnp.sonos.SonosZoneGroup
+import com.fabledsword.minstrel.player.output.upnp.sonos.ZoneGroupTopologyClient
 import dagger.hilt.android.qualifiers.ApplicationContext
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
@@ -13,6 +17,9 @@ import okhttp3.HttpUrl
 import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
 import okhttp3.OkHttpClient
 import okhttp3.Request
+import timber.log.Timber
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.TimeUnit
 import javax.inject.Inject
 import javax.inject.Singleton

@@ -41,9 +48,27 @@ class UpnpDiscoveryController @Inject constructor(
 ) {
    private val ssdp = SsdpDiscovery(context)

+    // Transport commands (play/pause/seek/next) and the 1 Hz poll go through
+    // this client. A dead renderer should fail fast so OutputPickerController's
+    // drop-recovery reverts to the phone in ~2 s instead of the shared client's
+    // 10 s connect timeout. Derived via newBuilder() so the connection pool +
+    // dispatcher stay shared with the app client.
+    private val controlHttp: OkHttpClient = okHttp.newBuilder()
+        .connectTimeout(CONTROL_CONNECT_TIMEOUT_SECONDS, TimeUnit.SECONDS)
+        .build()
+
    private val routesInternal = MutableStateFlow<List<UpnpRoute>>(emptyList())
    val routes: StateFlow<List<UpnpRoute>> = routesInternal.asStateFlow()

+    // Wall-clock of the last NOTIFY / M-SEARCH response per route id. Drives
+    // post-active-scan pruning so a powered-off renderer leaves the picker
+    // (and can't pin a stale selection) instead of lingering for the process
+    // lifetime -- upsert only ever added before.
+    private val lastSeenMs = ConcurrentHashMap<String, Long>()
+
+    private val sonosTopologyInternal = MutableStateFlow<List<SonosZoneGroup>>(emptyList())
+    val sonosTopology: StateFlow<List<SonosZoneGroup>> = sonosTopologyInternal.asStateFlow()
+
    init {
        ssdp.start(appScope)
        // appScope is process-lifetime (SupervisorJob + Dispatchers.Default),
@@ -61,7 +86,31 @@ class UpnpDiscoveryController @Inject constructor(
     * that just opened).
     */
    fun upgradeDiscovery() {
-        appScope.launch { ssdp.requestActiveScan() }
+        appScope.launch {
+            val scanStartMs = System.currentTimeMillis()
+            ssdp.requestActiveScan()
+            // Give present devices time to answer the M-SEARCH (+ our follow-up
+            // description fetch), then drop any route that didn't re-announce.
+            // Pruning is tied to picker-open scans only -- no background timer,
+            // so route rows never flicker while the user isn't looking.
+            delay(ACTIVE_SCAN_PRUNE_DELAY_MS)
+            pruneRoutesNotSeenSince(scanStartMs)
+        }
+    }
+
+    /**
+     * Drop routes whose last NOTIFY / M-SEARCH response predates [cutoffMs]
+     * -- i.e. they didn't answer the active scan that just ran, so they're
+     * gone from the LAN. Called only after [upgradeDiscovery]'s scan window.
+     */
+    private fun pruneRoutesNotSeenSince(cutoffMs: Long) {
+        val before = routesInternal.value
+        val survivors = before.filter { (lastSeenMs[it.id] ?: 0L) >= cutoffMs }
+        if (survivors.size == before.size) return
+        val removed = before.filterNot { it in survivors }.map { it.id }
+        removed.forEach { lastSeenMs.remove(it) }
+        Timber.w("UPnP discovery: pruned %d stale route(s): %s", removed.size, removed)
+        routesInternal.value = survivors
    }

    /**
@@ -83,13 +132,78 @@ class UpnpDiscoveryController @Inject constructor(
     */
    fun transportFor(routeId: String): AVTransportClient? {
        val route = routesInternal.value.firstOrNull { it.id == routeId } ?: return null
-        return AVTransportClient(SoapClient(okHttp), route.avTransportControlUrl)
+        return AVTransportClient(
+            loggingSoapClient(controlHttp, route.name),
+            route.avTransportControlUrl,
+        )
    }

    private suspend fun handleDiscovery(locationUrl: String) {
        val route = fetchRoute(locationUrl) ?: return
-        routesInternal.value =
-            routesInternal.value.filterNot { it.id == route.id } + route
+        upsertRoute(route)
+        if (route.manufacturer.contains("Sonos", ignoreCase = true)) {
+            refreshSonosTopology(route)
+        }
+    }
+
+    private fun upsertRoute(route: UpnpRoute) {
+        lastSeenMs[route.id] = System.currentTimeMillis()
+        val current = routesInternal.value
+        val idx = current.indexOfFirst { it.id == route.id }
+        routesInternal.value = if (idx < 0) {
+            current + route
+        } else {
+            current.toMutableList().also { it[idx] = route }
+        }
+    }
+
+    private suspend fun refreshSonosTopology(anySonos: UpnpRoute) {
+        val zgtUrl = anySonos.zoneGroupTopologyControlUrl ?: run {
+            Timber.w(
+                "Sonos %s has no ZoneGroupTopology URL -- topology grouping disabled",
+                anySonos.id,
+            )
+            return
+        }
+        val groups = runCatching {
+            ZoneGroupTopologyClient(
+                loggingSoapClient(okHttp, "ZGT-${anySonos.id}"),
+                zgtUrl,
+            ).getZoneGroupState()
+        }
+            .onFailure { Timber.w(it, "refreshSonosTopology failed for %s", anySonos.id) }
+            .getOrNull() ?: return
+        Timber.w(
+            "Sonos topology refreshed for %s: %d group(s)",
+            anySonos.id,
+            groups.size,
+        )
+        sonosTopologyInternal.value = groups
+    }
+
+    /**
+     * Returns the coordinator UDN's full route for the group [udn] belongs
+     * to, or null if topology hasn't loaded / the udn is in no group. UDN
+     * normalization strips the "uuid:" prefix because DeviceDescription's
+     * <UDN> carries it but Sonos's ZoneGroupState Coordinator attr does not.
+     */
+    fun coordinatorRouteFor(udn: String): UpnpRoute? {
+        val bare = udn.bareUdn()
+        val coord = sonosTopologyInternal.value
+            .firstOrNull { g -> g.members.any { it.udn.bareUdn() == bare } }
+            ?.coordinatorUdn ?: return null
+        return routesInternal.value.firstOrNull { it.id.bareUdn() == coord.bareUdn() }
+    }
+
+    /**
+     * UDNs of every NON-coordinator Sonos group member. The picker
+     * controller suppresses these from the visible list.
+     */
+    fun nonCoordinatorMemberUdns(): Set<String> {
+        return sonosTopologyInternal.value.flatMap { g ->
+            g.members.map { it.udn.bareUdn() }
+                .filter { it != g.coordinatorUdn.bareUdn() }
+        }.toSet()
    }

    /**
@@ -111,6 +225,7 @@ class UpnpDiscoveryController @Inject constructor(
                    modelName = desc.modelName,
                    avTransportControlUrl = desc.avTransportControlUrl,
                    renderingControlUrl = desc.renderingControlUrl,
+                    zoneGroupTopologyControlUrl = desc.zoneGroupTopologyControlUrl,
                )
            }
    }
@@ -153,5 +268,32 @@ class UpnpDiscoveryController @Inject constructor(
        // devices append. Anchored to end-of-string so it never eats
        // a legitimate parenthetical inside a name.
        val IP_SUFFIX_REGEX = Regex("""\s*\(\d+\.\d+\.\d+\.\d+\)$""")
+
+        // Aggressive connect timeout for transport SOAP so a dead renderer
+        // trips the drop-recovery quickly. Conservative enough not to false-drop
+        // a slow-but-alive LAN; read timeout still inherits the shared client.
+        const val CONTROL_CONNECT_TIMEOUT_SECONDS = 2L
+
+        // Grace window after an M-SEARCH burst before pruning non-responders.
+        // Covers the SSDP round-trip plus our per-device description fetch;
+        // generous enough that a present-but-slow renderer isn't false-pruned.
+        const val ACTIVE_SCAN_PRUNE_DELAY_MS = 4_000L
    }
 }
+
+/**
+ * Normalize a Sonos UDN to its bare RINCON form for cross-comparison.
+ *
+ * Three places use UDN strings with different conventions:
+ *  - DeviceDescription's <UDN> tag carries the `uuid:` prefix.
+ *  - Sonos exposes one UDN per embedded device. The MediaRenderer adds
+ *    a `_MR` suffix and the MediaServer adds `_MS`.
+ *  - The ZGT GetZoneGroupState response uses bare `RINCON_xxx` with
+ *    neither the `uuid:` prefix nor any device suffix.
+ *
+ * To compare any pair of those, strip the prefix and the suffix so
+ * everything reduces to the underlying speaker identity.
+ */
+internal fun String.bareUdn(): String = removePrefix("uuid:")
+    .removeSuffix("_MR")
+    .removeSuffix("_MS")
@@ -7,10 +7,10 @@ import okhttp3.HttpUrl
 * Bose SoundTouch, generic DLNA renderers). Lifted out of the SOAP /
 * SSDP details so the picker UI consumes a narrow domain shape.
 *
- * Generic UPnP only for THIS slice — Sonos-specific grouping value-adds
- * (group join/leave, zone topology) live in a separate Sonos extension
- * scoped in
- * docs/superpowers/specs/2026-06-03-android-output-picker-upnp-scope.md.
+ * Sonos devices additionally populate [zoneGroupTopologyControlUrl] from the
+ * ZoneGroupTopology service in their device description; non-Sonos devices
+ * leave it null. The discovery controller uses that URL to aggregate stereo
+ * pairs and multi-speaker groups into single picker rows.
 *
 * [id] is the device UDN (e.g. `uuid:RINCON_ABC...`). [name] is the
 * raw `<friendlyName>` straight from the device description — callers
@@ -24,4 +24,5 @@ data class UpnpRoute(
    val modelName: String,
    val avTransportControlUrl: HttpUrl,
    val renderingControlUrl: HttpUrl?,
+    val zoneGroupTopologyControlUrl: HttpUrl? = null,
 )
@@ -0,0 +1,90 @@
+package com.fabledsword.minstrel.player.output.upnp.sonos
+
+import org.xmlpull.v1.XmlPullParser
+import org.xmlpull.v1.XmlPullParserFactory
+
+/**
+ * One Sonos zone group as exposed by ZoneGroupTopology.GetZoneGroupState.
+ * Stereo pairs and multi-speaker groups all appear as one group with
+ * multiple members; one member is the coordinator we send SOAP to.
+ */
+data class SonosZoneGroup(
+    val coordinatorUdn: String,
+    val name: String,
+    val members: List<SonosZoneMember>,
+)
+
+data class SonosZoneMember(
+    val udn: String,
+    val roomName: String,
+    val location: String?,
+    val channelMapSet: String?,
+)
+
+object SonosTopology {
+
+    fun parse(xml: String): List<SonosZoneGroup> {
+        val effective = if (xml.contains("&lt;ZoneGroup")) {
+            unescapeXmlEntities(xml)
+        } else {
+            xml
+        }
+        return runCatching { parseStrict(effective) }.getOrDefault(emptyList())
+    }
+
+    private fun unescapeXmlEntities(s: String): String = s
+        .replace("&lt;", "<")
+        .replace("&gt;", ">")
+        .replace("&quot;", "\"")
+        .replace("&apos;", "'")
+        .replace("&amp;", "&")  // must be last to avoid double-decoding
+
+    private fun parseStrict(xml: String): List<SonosZoneGroup> {
+        val parser = XmlPullParserFactory.newInstance().newPullParser().apply {
+            setFeature(XmlPullParser.FEATURE_PROCESS_NAMESPACES, true)
+            setInput(xml.reader())
+        }
+        val groups = mutableListOf<SonosZoneGroup>()
+        var currentCoordinator: String? = null
+        var currentMembers: MutableList<SonosZoneMember>? = null
+        while (parser.eventType != XmlPullParser.END_DOCUMENT) {
+            when (parser.eventType) {
+                XmlPullParser.START_TAG -> when (parser.name) {
+                    TAG_ZONE_GROUP -> {
+                        currentCoordinator = parser.getAttributeValue(null, ATTR_COORDINATOR)
+                        currentMembers = mutableListOf()
+                    }
+                    TAG_ZONE_GROUP_MEMBER -> currentMembers?.add(memberOf(parser))
+                }
+                XmlPullParser.END_TAG -> if (parser.name == TAG_ZONE_GROUP) {
+                    val members = currentMembers ?: emptyList()
+                    val coord = currentCoordinator
+                    if (coord != null && members.isNotEmpty()) {
+                        val name = members.firstOrNull { it.udn == coord }?.roomName
+                            ?: members.first().roomName
+                        groups.add(SonosZoneGroup(coord, name, members))
+                    }
+                    currentCoordinator = null
+                    currentMembers = null
+                }
+            }
+            parser.next()
+        }
+        return groups
+    }
+
+    private fun memberOf(parser: XmlPullParser): SonosZoneMember = SonosZoneMember(
+        udn = parser.getAttributeValue(null, ATTR_UUID).orEmpty(),
+        roomName = parser.getAttributeValue(null, ATTR_ZONE_NAME).orEmpty(),
+        location = parser.getAttributeValue(null, ATTR_LOCATION),
+        channelMapSet = parser.getAttributeValue(null, ATTR_CHANNEL_MAP_SET),
+    )
+
+    private const val TAG_ZONE_GROUP = "ZoneGroup"
+    private const val TAG_ZONE_GROUP_MEMBER = "ZoneGroupMember"
+    private const val ATTR_COORDINATOR = "Coordinator"
+    private const val ATTR_UUID = "UUID"
+    private const val ATTR_ZONE_NAME = "ZoneName"
+    private const val ATTR_LOCATION = "Location"
+    private const val ATTR_CHANNEL_MAP_SET = "ChannelMapSet"
+}
@@ -0,0 +1,37 @@
+package com.fabledsword.minstrel.player.output.upnp.sonos
+
+import com.fabledsword.minstrel.player.output.upnp.SoapClient
+import okhttp3.HttpUrl
+import timber.log.Timber
+
+/**
+ * Sonos's proprietary ZoneGroupTopology service. Same SOAP shape as a
+ * standard UPnP service, exposed on port 1400 at
+ * /ZoneGroupTopology/Control. GetZoneGroupState returns the full
+ * network topology as one XML doc wrapped inside a SOAP arg.
+ */
+class ZoneGroupTopologyClient(
+    private val soap: SoapClient,
+    private val controlUrl: HttpUrl,
+) {
+    suspend fun getZoneGroupState(): List<SonosZoneGroup> {
+        val args = soap.call(
+            controlUrl = controlUrl,
+            serviceType = SERVICE_TYPE,
+            action = "GetZoneGroupState",
+            args = emptyMap(),
+        )
+        val inner = args["ZoneGroupState"].orEmpty()
+        Timber.w(
+            "ZGT extracted ZoneGroupState (%d chars): %s",
+            inner.length,
+            inner.take(ZGT_LOG_TRUNCATE_CHARS),
+        )
+        return SonosTopology.parse(inner)
+    }
+
+    private companion object {
+        const val SERVICE_TYPE = "urn:schemas-upnp-org:service:ZoneGroupTopology:1"
+        const val ZGT_LOG_TRUNCATE_CHARS = 2048
+    }
+}
@@ -17,6 +17,7 @@ import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
@@ -164,6 +165,7 @@ fun MiniPlayer(
            MiniRow(
                track = track,
                isPlaying = state.isPlaying,
+                isUpnpLoading = state.isUpnpLoading,
                isLiked = isLiked,
                onExpandClick = onExpandClick,
                onPlayPause = { if (state.isPlaying) viewModel.pause() else viewModel.play() },
@@ -204,6 +206,7 @@ private fun MiniProgressFill(positionMs: Long, durationMs: Long) {
 private fun MiniRow(
    track: TrackRef,
    isPlaying: Boolean,
+    isUpnpLoading: Boolean,
    isLiked: Boolean,
    onExpandClick: () -> Unit,
    onPlayPause: () -> Unit,
@@ -248,15 +251,39 @@ private fun MiniRow(
        }
        LikeButton(liked = isLiked, onToggle = onToggleLike)
        TransportButton(icon = Lucide.SkipBack, description = "Previous", onClick = onPrev)
-        TransportButton(
-            icon = if (isPlaying) Lucide.Pause else Lucide.Play,
-            description = if (isPlaying) "Pause" else "Play",
+        MiniPlayPauseButton(
+            isPlaying = isPlaying,
+            isUpnpLoading = isUpnpLoading,
            onClick = onPlayPause,
        )
        TransportButton(icon = Lucide.SkipForward, description = "Next", onClick = onNext)
    }
 }

+@Composable
+private fun MiniPlayPauseButton(
+    isPlaying: Boolean,
+    isUpnpLoading: Boolean,
+    onClick: () -> Unit,
+) {
+    IconButton(onClick = onClick, enabled = !isUpnpLoading) {
+        if (isUpnpLoading) {
+            CircularProgressIndicator(
+                modifier = Modifier.size(MINI_PLAY_PAUSE_SPINNER_DP.dp),
+                strokeWidth = 2.dp,
+            )
+        } else {
+            Icon(
+                imageVector = if (isPlaying) Lucide.Pause else Lucide.Play,
+                contentDescription = if (isPlaying) "Pause" else "Play",
+                tint = MaterialTheme.colorScheme.onSurface,
+            )
+        }
+    }
+}
+
+private const val MINI_PLAY_PAUSE_SPINNER_DP = 24
+
@Composable
 private fun TransportButton(
    icon: androidx.compose.ui.graphics.vector.ImageVector,
@@ -8,6 +8,7 @@ import androidx.activity.compose.rememberLauncherForActivityResult
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.compose.animation.ExperimentalSharedTransitionApi
 import androidx.compose.foundation.background
+import androidx.compose.foundation.focusable
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.foundation.layout.Arrangement
@@ -25,6 +26,7 @@ import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.widthIn
 import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
@@ -50,10 +52,19 @@ import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
+import androidx.compose.ui.focus.FocusRequester
+import androidx.compose.ui.focus.focusRequester
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
+import androidx.compose.ui.input.key.Key
+import androidx.compose.ui.input.key.KeyEvent
+import androidx.compose.ui.input.key.KeyEventType
+import androidx.compose.ui.input.key.key
+import androidx.compose.ui.input.key.onKeyEvent
+import androidx.compose.ui.input.key.type
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.text.style.TextOverflow
@@ -74,11 +85,13 @@ import com.composables.icons.lucide.Shuffle
 import com.composables.icons.lucide.SkipBack
 import com.composables.icons.lucide.SkipForward
 import com.fabledsword.minstrel.player.RepeatMode
+import com.fabledsword.minstrel.player.output.ActiveUpnp
 import com.fabledsword.minstrel.player.output.DeviceChip
 import com.fabledsword.minstrel.player.output.OutputPickerSheet
 import com.fabledsword.minstrel.player.output.OutputPickerViewModel
 import com.fabledsword.minstrel.player.output.OutputRoute
 import com.fabledsword.minstrel.player.output.RouteSnapshot
+import kotlinx.coroutines.launch
 import com.fabledsword.minstrel.nav.AlbumDetail
 import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.nav.HERO_KEY_NOW_PLAYING_COVER
@@ -129,27 +142,30 @@ fun NowPlayingScreen(
            snackbarHostState.showSnackbar(msg)
        }
    }
+    LaunchedEffect(Unit) {
+        viewModel.dropEvents.collect { snackbarHostState.showSnackbar("Disconnected from $it") }
+    }
    val track = state.currentTrack
    if (track == null) {
-        // Session torn down (queue finished + auto-stop, or user cleared
-        // the queue from elsewhere). Pop back to whichever shell screen
-        // launched NowPlaying rather than stranding the user on an
-        // EmptyState with no escape. A short delay swallows the
-        // momentary null during MediaController IPC bind on cold-mount.
-        LaunchedEffect(Unit) {
-            kotlinx.coroutines.delay(POP_GRACE_MS)
-            if (viewModel.uiState.value.currentTrack == null) {
-                navController.popBackStack()
-            }
-        }
+        NowPlayingNullTrackGuard(navController, viewModel)
        return
    }
+    val outputViewModel: OutputPickerViewModel = hiltViewModel()
+    val activeUpnp by outputViewModel.activeUpnp.collectAsStateWithLifecycle()
+    val onKeyEvent = rememberUpnpVolumeKeyHandler(activeUpnp)
+    val focusRequester = remember { FocusRequester() }
+    LaunchedEffect(activeUpnp) { if (activeUpnp != null) focusRequester.requestFocus() }
    val dominant = rememberDominantColor(track.coverUrl)
    val dismissConnection = rememberDragDismissConnection(
        onDismiss = { navController.popBackStack() },
    )
    Scaffold(
-        modifier = Modifier.fillMaxSize().nestedScroll(dismissConnection),
+        modifier = Modifier
+            .fillMaxSize()
+            .nestedScroll(dismissConnection)
+            .focusRequester(focusRequester)
+            .focusable()
+            .onKeyEvent(onKeyEvent),
        topBar = { NowPlayingTopBar(onClose = { navController.popBackStack() }) },
        snackbarHost = { SnackbarHost(snackbarHostState) },
        containerColor = Color.Transparent,
@@ -166,11 +182,32 @@ fun NowPlayingScreen(
                navController = navController,
                viewModel = viewModel,
                trackActionsViewModel = trackActionsViewModel,
+                outputViewModel = outputViewModel,
            )
        }
    }
 }

+/**
+ * Null-track guard extracted from [NowPlayingScreen] to keep that
+ * function under detekt's LongMethod ceiling. Session torn down
+ * (queue finished + auto-stop, or user cleared the queue from
+ * elsewhere). Pops back after a short grace delay so a momentary
+ * null during MediaController IPC bind on cold-mount doesn't flash.
+ */
+@Composable
+private fun NowPlayingNullTrackGuard(
+    navController: NavHostController,
+    viewModel: PlayerViewModel,
+) {
+    LaunchedEffect(Unit) {
+        kotlinx.coroutines.delay(POP_GRACE_MS)
+        if (viewModel.uiState.value.currentTrack == null) {
+            navController.popBackStack()
+        }
+    }
+}
+
@Composable
 private fun dominantGradient(top: Color): Brush {
    val base = MaterialTheme.colorScheme.background
@@ -270,6 +307,7 @@ private fun NowPlayingTopBar(onClose: () -> Unit) {
    )
 }

+@Suppress("LongParameterList") // Compose screen wiring — layout args, not logic
@Composable
 private fun NowPlayingBody(
    inner: androidx.compose.foundation.layout.PaddingValues,
@@ -278,10 +316,10 @@ private fun NowPlayingBody(
    navController: NavHostController,
    viewModel: PlayerViewModel,
    trackActionsViewModel: TrackActionsViewModel,
+    outputViewModel: OutputPickerViewModel,
 ) {
    val isLiked by trackActionsViewModel.isLikedFlow(track.id)
        .collectAsStateWithLifecycle(initialValue = false)
-    val outputViewModel: OutputPickerViewModel = hiltViewModel()
    val routes by outputViewModel.routes.collectAsStateWithLifecycle()
    val sheetVisible by outputViewModel.sheetVisible.collectAsStateWithLifecycle()
    val permissionDenied = rememberBluetoothPermissionState(sheetVisible)
@@ -387,6 +425,7 @@ private fun PlaybackControlsBlock(
    Spacer(Modifier.height(4.dp))
    TransportRow(
        isPlaying = state.isPlaying,
+        isUpnpLoading = state.isUpnpLoading,
        onPrev = viewModel::skipToPrevious,
        onPlayPause = { if (state.isPlaying) viewModel.pause() else viewModel.play() },
        onNext = viewModel::skipToNext,
@@ -667,6 +706,7 @@ private fun ScrubTrack(fraction: Float, accent: Color) {
@Composable
 private fun TransportRow(
    isPlaying: Boolean,
+    isUpnpLoading: Boolean,
    onPrev: () -> Unit,
    onPlayPause: () -> Unit,
    onNext: () -> Unit,
@@ -685,7 +725,13 @@ private fun TransportRow(
                modifier = Modifier.size(TRANSPORT_ICON_DP.dp),
            )
        }
-        IconButton(onClick = onPlayPause) {
+        IconButton(onClick = onPlayPause, enabled = !isUpnpLoading) {
+            if (isUpnpLoading) {
+                CircularProgressIndicator(
+                    modifier = Modifier.size(PLAY_PAUSE_ICON_DP.dp),
+                    strokeWidth = 3.dp,
+                )
+            } else {
                Icon(
                    imageVector = if (isPlaying) Lucide.Pause else Lucide.Play,
                    contentDescription = if (isPlaying) "Pause" else "Play",
@@ -693,6 +739,7 @@ private fun TransportRow(
                    modifier = Modifier.size(PLAY_PAUSE_ICON_DP.dp),
                )
            }
+        }
        IconButton(onClick = onNext) {
            Icon(
                imageVector = Lucide.SkipForward,
@@ -703,3 +750,40 @@ private fun TransportRow(
        }
    }
 }
+
+/**
+ * Returns a key-event handler that intercepts volume-up/down when a UPnP
+ * route is active and routes the step through [ActiveUpnp.rendering].
+ * Volume is cached locally so rapid key presses don't each wait on a
+ * getVolume() round-trip. Returns false (not consumed) for every event
+ * when no UPnP route is active so the system handles volume normally.
+ */
+@Composable
+private fun rememberUpnpVolumeKeyHandler(activeUpnp: ActiveUpnp?): (KeyEvent) -> Boolean {
+    val scope = rememberCoroutineScope()
+    val cache = remember(activeUpnp?.routeId) { VolumeCache() }
+    return remember(activeUpnp) {
+        handler@{ event: KeyEvent ->
+            val rc = activeUpnp?.rendering ?: return@handler false
+            if (event.type != KeyEventType.KeyDown) return@handler false
+            val delta = when (event.key) {
+                Key.VolumeUp -> VOLUME_KEY_STEP
+                Key.VolumeDown -> -VOLUME_KEY_STEP
+                else -> return@handler false
+            }
+            scope.launch {
+                val current = cache.value ?: runCatching { rc.getVolume() }.getOrNull() ?: 0
+                val next = (current + delta).coerceIn(VOLUME_MIN_PERCENT, VOLUME_MAX_PERCENT)
+                cache.value = next
+                runCatching { rc.setVolume(next) }
+            }
+            true
+        }
+    }
+}
+
+private class VolumeCache(var value: Int? = null)
+
+private const val VOLUME_KEY_STEP = 5
+private const val VOLUME_MIN_PERCENT = 0
+private const val VOLUME_MAX_PERCENT = 100
@@ -4,6 +4,7 @@ import androidx.lifecycle.ViewModel
 import com.fabledsword.minstrel.player.PlayerController
 import com.fabledsword.minstrel.player.PlayerUiState
 import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.SharedFlow
 import kotlinx.coroutines.flow.StateFlow
 import javax.inject.Inject

@@ -24,6 +25,7 @@ class PlayerViewModel @Inject constructor(
 ) : ViewModel() {

    val uiState: StateFlow<PlayerUiState> = controller.uiState
+    val dropEvents: SharedFlow<String> = controller.dropEvents

    fun play() = controller.play()
    fun pause() = controller.pause()
@@ -0,0 +1,71 @@
+package com.fabledsword.minstrel.playlists.data
+
+import com.fabledsword.minstrel.models.PlaylistRef
+import com.fabledsword.minstrel.player.PlayerController
+import com.fabledsword.minstrel.api.ErrorCopy
+import kotlinx.coroutines.TimeoutCancellationException
+import kotlinx.coroutines.withTimeout
+
+private const val PLAYLIST_FETCH_TIMEOUT_MS = 8_000L
+
+/**
+ * Fetch a playlist and hand it to the player as a shuffled queue.
+ *
+ * Behavior matches the tile play-button contract used on Home and the
+ * Playlists list: refreshable system playlists go through systemShuffle
+ * (server-side rotation-aware order; tagging with the variant advances
+ * rotation), everything else uses refreshDetail. System playlists are
+ * then client-side shuffled so the tile feels random rather than
+ * "start at the rotation head". User playlists keep their authored
+ * order.
+ *
+ * Errors and empty mixes surface through [onMessage] for the caller to
+ * present as a snackbar / toast / etc. Returns when the player has
+ * accepted the queue (or an error path bailed).
+ */
+suspend fun playPlaylistShuffled(
+    playlist: PlaylistRef,
+    repository: PlaylistsRepository,
+    player: PlayerController,
+    onMessage: (String) -> Unit,
+) {
+    val detail = fetchPlaylistDetail(playlist, repository, onMessage) ?: return
+    val tracks = detail.tracks.toPlayableTrackRefs()
+    if (tracks.isEmpty()) {
+        onMessage("Mix isn't ready yet - try again in a moment")
+        return
+    }
+    // Drift #564: bare systemVariant string (not "playlist:<variant>") --
+    // server's rotation matcher keys on the bare variant.
+    val source = if (playlist.refreshable) playlist.systemVariant else null
+    // System playlist tile play button == "pick a random song + shuffle
+    // the rest" UX. Server's rotation-aware order still drives rotation
+    // bookkeeping via `source`; the client shuffle just removes the
+    // deterministic "start at rotation head" feel.
+    val ordered = if (playlist.isSystem) tracks.shuffled() else tracks
+    player.setQueue(ordered, initialIndex = 0, source = source)
+}
+
+private suspend fun fetchPlaylistDetail(
+    playlist: PlaylistRef,
+    repository: PlaylistsRepository,
+    onMessage: (String) -> Unit,
+): PlaylistDetailRef? = try {
+    withTimeout(PLAYLIST_FETCH_TIMEOUT_MS) {
+        if (playlist.refreshable && playlist.systemVariant != null) {
+            repository.systemShuffle(playlist.systemVariant)
+        } else {
+            repository.refreshDetail(playlist.id)
+        }
+    }
+} catch (
+    @Suppress("SwallowedException") _: TimeoutCancellationException,
+) {
+    onMessage("Couldn't load playlist - check your connection")
+    null
+} catch (
+    @Suppress("TooGenericExceptionCaught") e: Throwable,
+) {
+    onMessage("Couldn't load playlist: ${ErrorCopy.fromThrowable(e)}")
+    null
+}
@@ -7,6 +7,7 @@ import retrofit2.HttpException
 import java.net.HttpURLConnection
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistTrackDao
+import com.fabledsword.minstrel.cache.db.dao.PlaylistCachedCount
 import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistTrackEntity
 import com.fabledsword.minstrel.cache.mutations.MutationQueue
@@ -18,6 +19,7 @@ import com.fabledsword.minstrel.models.wire.PlaylistTrackWire
 import com.fabledsword.minstrel.models.wire.PlaylistWire
 import com.fabledsword.minstrel.shared.resolveServerUrl
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.map
 import retrofit2.Retrofit
 import retrofit2.create
@@ -51,9 +53,16 @@ class PlaylistsRepository @Inject constructor(

    // ── Reads (Flow, cache-first; the cache is the source of truth) ──

-    /** Owned + public; UI splits by isSystem / userId comparison. */
+    /**
+     * Owned + public; UI splits by isSystem / userId comparison. Joined with
+     * per-playlist cache counts so [PlaylistRef.fullyCached] drives the offline
+     * greying without each consumer re-querying the cache index.
+     */
    fun observeAll(): Flow<List<PlaylistRef>> =
-        playlistDao.observeAll().map { rows -> rows.map { it.toDomain() } }
+        combine(
+            playlistDao.observeAll(),
+            playlistDao.observeCachedCounts(),
+        ) { rows, counts -> mergePlaylistsWithCache(rows, counts) }

    /** User-owned playlists only (systemVariant IS NULL). */
    fun observeUserPlaylists(): Flow<List<PlaylistRef>> =
@@ -233,6 +242,23 @@ fun List<PlaylistTrackRef>.toPlayableTrackRefs(): List<TrackRef> =

 // ── Mappers (internal — keep Room + wire types out of the UI layer) ──

+/**
+ * Maps cached playlist rows to domain refs, stamping [PlaylistRef.fullyCached]
+ * from the cache-index counts. A playlist is fully cached when it has tracks
+ * and every member track is resident (`cachedCount >= trackCount`). Pulled out
+ * of the Flow so the predicate is unit-testable without a Room database.
+ */
+internal fun mergePlaylistsWithCache(
+    rows: List<CachedPlaylistEntity>,
+    counts: List<PlaylistCachedCount>,
+): List<PlaylistRef> {
+    val cachedById = counts.associate { it.playlistId to it.cachedCount }
+    return rows.map { row ->
+        val cached = cachedById[row.id] ?: 0
+        row.toDomain().copy(fullyCached = row.trackCount > 0 && cached >= row.trackCount)
+    }
+}
+
 private fun CachedPlaylistEntity.toDomain(): PlaylistRef =
    PlaylistRef(
        id = id,
@@ -28,15 +28,17 @@ import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.OutlinedButton
 import androidx.compose.material3.Scaffold
+import androidx.compose.material3.SnackbarDuration
+import androidx.compose.material3.SnackbarHost
+import androidx.compose.material3.SnackbarHostState
+import androidx.compose.material3.SnackbarResult
 import androidx.compose.material3.Text
 import androidx.compose.material3.TopAppBar
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
-import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
-import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
@@ -56,6 +58,8 @@ import com.composables.icons.lucide.Play
 import com.composables.icons.lucide.RefreshCw
 import com.composables.icons.lucide.Shuffle
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.events.LiveEvent
 import com.fabledsword.minstrel.models.PlaylistRef
@@ -72,6 +76,7 @@ import com.fabledsword.minstrel.playlists.data.PlaylistsRepository
 import com.fabledsword.minstrel.playlists.data.toPlayableTrackRefs
 import com.fabledsword.minstrel.shared.formatDuration
 import com.fabledsword.minstrel.shared.widgets.TrackRow
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.SkeletonTrackRow
@@ -113,6 +118,7 @@ class PlaylistDetailViewModel @Inject constructor(
    private val player: PlayerController,
    private val eventsStream: EventsStream,
    private val seedCache: DetailSeedCache,
+    networkStatus: NetworkStatusController,
    savedStateHandle: SavedStateHandle,
 ) : ViewModel() {

@@ -139,6 +145,15 @@ class PlaylistDetailViewModel @Inject constructor(
    private val regeneratedChannel = Channel<String>(Channel.BUFFERED)
    val regenerated: Flow<String> = regeneratedChannel.receiveAsFlow()

+    /**
+     * #980: a system-playlist rebuild landed (SSE) while this screen is open —
+     * its list is now stale and the uuid has rotated. Drives a "this mix was
+     * refreshed → Refresh" snackbar rather than yanking the user; Refresh
+     * re-resolves the variant via [reloadRebuilt].
+     */
+    private val staleInternal = MutableStateFlow(false)
+    val stale: StateFlow<Boolean> = staleInternal.asStateFlow()
+
    val likedTrackIds: StateFlow<Set<String>> =
        likes.observeLikedTrackIds()
            .stateIn(
@@ -154,6 +169,14 @@ class PlaylistDetailViewModel @Inject constructor(
                .filter { it.kind.startsWith("playlist.") }
                .collect { handlePlaylistEvent(it) }
        }
+        // Screen-level auto-recovery (issue #1245): a detail that failed to
+        // load while the server was unreachable re-fetches when health
+        // returns, instead of waiting for the Retry tap.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is PlaylistDetailUiState.Error) refresh()
+            }
+        }
    }

    /**
@@ -163,6 +186,12 @@ class PlaylistDetailViewModel @Inject constructor(
     * ignored — the playlists-list screen handles those.
     */
    private fun handlePlaylistEvent(event: LiveEvent) {
+        // #980: a system rebuild carries no playlist_id (it rebuilds all of the
+        // user's system mixes at once) — handle it before the per-id filter.
+        if (event.kind == "playlist.system_rebuilt") {
+            markStaleIfSystem()
+            return
+        }
        val eventPlaylistId = event.data["playlist_id"]?.jsonPrimitive?.contentOrNull
        if (eventPlaylistId != playlistId) return
        when (event.kind) {
@@ -171,6 +200,14 @@ class PlaylistDetailViewModel @Inject constructor(
        }
    }

+    private fun markStaleIfSystem() {
+        val playlist = (internal.value as? PlaylistDetailUiState.Success)
+            ?.detail?.playlist ?: return
+        if (playlist.systemVariant?.takeIf { playlist.refreshable } != null) {
+            staleInternal.value = true
+        }
+    }
+
    fun toggleLikeTrack(trackId: String) {
        val desired = trackId !in likedTrackIds.value
        viewModelScope.launch {
@@ -220,6 +257,30 @@ class PlaylistDetailViewModel @Inject constructor(
        }
    }

+    /**
+     * #980: user tapped Refresh on the stale-view snackbar. The rebuild
+     * already ran server-side (uuid rotated) — re-resolve the variant to the
+     * fresh playlist id and hand it to [regenerated] for navigate-replace.
+     * Unlike [regenerate] this does NOT trigger another rebuild.
+     */
+    fun reloadRebuilt() {
+        val playlist = (internal.value as? PlaylistDetailUiState.Success)
+            ?.detail?.playlist ?: return
+        val variant = playlist.systemVariant?.takeIf { playlist.refreshable } ?: return
+        staleInternal.value = false
+        viewModelScope.launch {
+            runCatching { repository.systemShuffle(variant).playlist.id }
+                .onSuccess { newId ->
+                    if (newId.isNotEmpty()) regeneratedChannel.trySend(newId)
+                }
+        }
+    }
+
+    /** #980: user dismissed the stale-view snackbar without refreshing. */
+    fun dismissStale() {
+        staleInternal.value = false
+    }
+
    /** Play the available tracks starting at [startTrackId] (or first available). */
    fun play(tracks: List<PlaylistTrackRef>, startTrackId: String?) {
        val refs = tracks.toPlayableTrackRefs()
@@ -261,8 +322,25 @@ fun PlaylistDetailScreen(
            }
        }
    }
+    // #980: a rebuild landed while this system-playlist screen is open. Offer a
+    // non-intrusive "refreshed → Refresh" snackbar; Refresh re-resolves the
+    // rotated uuid (via the regenerated navigate-replace flow).
+    val snackbarHostState = remember { SnackbarHostState() }
+    val stale by viewModel.stale.collectAsState()
+    LaunchedEffect(stale) {
+        if (stale) {
+            val result = snackbarHostState.showSnackbar(
+                message = "This mix was refreshed",
+                actionLabel = "Refresh",
+                duration = SnackbarDuration.Indefinite,
+            )
+            if (result == SnackbarResult.ActionPerformed) viewModel.reloadRebuilt()
+            else viewModel.dismissStale()
+        }
+    }
    Scaffold(
        modifier = Modifier.fillMaxSize(),
+        snackbarHost = { SnackbarHost(snackbarHostState) },
        topBar = {
            TopAppBar(
                title = { Text(currentTitle(state)) },
@@ -301,7 +379,11 @@ private fun PlaylistDetailContent(
    Crossfade(targetState = state::class, label = "playlist-detail") { _ -> when (val s = state) {
        is PlaylistDetailUiState.Loading ->
            s.seed?.let { SeededPlaylistLoading(it) } ?: SkeletonPlaylistTrackList()
-        is PlaylistDetailUiState.Error -> ErrorBlock(s.message, viewModel::refresh)
+        is PlaylistDetailUiState.Error -> ErrorRetry(
+            title = "Couldn't load playlist",
+            message = s.message,
+            onRetry = { viewModel.refresh() },
+        )
        is PlaylistDetailUiState.Success -> {
            val likedTrackIds by viewModel.likedTrackIds.collectAsState()
            val playerState by playerViewModel.uiState.collectAsState()
@@ -585,33 +667,6 @@ private fun SeededPlaylistLoading(seed: PlaylistRef) {
    }
 }

-@Composable
-private fun ErrorBlock(message: String, onRetry: () -> Unit) {
-    var retried by remember { mutableStateOf(false) }
-    Column(
-        modifier = Modifier
-            .fillMaxSize()
-            .padding(24.dp),
-        verticalArrangement = Arrangement.Center,
-        horizontalAlignment = Alignment.CenterHorizontally,
-    ) {
-        Text(
-            text = message,
-            color = MaterialTheme.colorScheme.error,
-            style = MaterialTheme.typography.bodyLarge,
-        )
-        Spacer(Modifier.height(12.dp))
-        OutlinedButton(
-            onClick = {
-                if (!retried) {
-                    retried = true
-                    onRetry()
-                }
-            },
-        ) { Text("Retry") }
-    }
-}
-
 // ─── Helpers ─────────────────────────────────────────────────────────

 private const val UNAVAILABLE_ALPHA = 0.4f
@@ -13,9 +13,13 @@ import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
 import androidx.compose.foundation.lazy.grid.items
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Scaffold
+import androidx.compose.material3.SnackbarHost
+import androidx.compose.material3.SnackbarHostState
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.unit.dp
 import androidx.hilt.navigation.compose.hiltViewModel
@@ -23,26 +27,42 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.NavHostController
+import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.PlaylistRef
 import com.fabledsword.minstrel.nav.PlaylistDetail
 import com.fabledsword.minstrel.nav.Playlists
+import com.fabledsword.minstrel.player.PlayerController
 import com.fabledsword.minstrel.playlists.data.PlaylistsRepository
+import com.fabledsword.minstrel.playlists.data.playPlaylistShuffled
 import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.asCacheFirstStateFlow
 import com.fabledsword.minstrel.playlists.widgets.PlaylistCard
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.receiveAsFlow
+import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.launch
 import javax.inject.Inject

+private const val SHARE_STOP_TIMEOUT_MS = 5_000L
+
 // ─── State ───────────────────────────────────────────────────────────

 // ─── ViewModel ───────────────────────────────────────────────────────
@@ -50,9 +70,28 @@ import javax.inject.Inject
@HiltViewModel
 class PlaylistsListViewModel @Inject constructor(
    private val repository: PlaylistsRepository,
+    private val player: PlayerController,
    private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

+    private val poolMessages = Channel<String>(Channel.BUFFERED)
+
+    /** Transient snackbar messages from playlist tile play taps. */
+    val transientMessages: Flow<String> = poolMessages.receiveAsFlow()
+
+    /** Cache-only: no link OR server unreachable (Unstable stays calm). Greys tiles. */
+    val offline: StateFlow<Boolean> = networkStatus.state
+        .map { it == ServerHealth.Offline || it == ServerHealth.ServerDown }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(SHARE_STOP_TIMEOUT_MS),
+            initialValue = false,
+        )
+
+    /** Copy for the most recent list-refresh failure; null once one succeeds. */
+    private val refreshError = MutableStateFlow<String?>(null)
+
    init {
        refresh()
        // Live updates: a playlist created/updated/deleted from another
@@ -62,20 +101,37 @@ class PlaylistsListViewModel @Inject constructor(
                .filter { it.kind.startsWith("playlist.") }
                .collect { refresh() }
        }
+        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // health returns, so a load that failed offline heals unprompted.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
    }

    /** Re-pull the playlists list. Returns the Job for pull-to-refresh awaits. */
    fun refresh(): Job = viewModelScope.launch {
+        refreshError.value = null
        runCatching { repository.refreshList() }
+            .onFailure { refreshError.value = ErrorCopy.fromThrowable(it) }
+    }
+
+    /** Tile play button: shuffle the playlist's tracks and start at index 0. */
+    suspend fun playPlaylist(playlist: PlaylistRef) {
+        viewModelScope.launch {
+            playPlaylistShuffled(playlist, repository, player) {
+                poolMessages.trySend(it)
+            }
+        }.join()
    }

    val uiState: StateFlow<UiState<List<PlaylistRef>>> =
-        repository.observeAll()
-            .map { list ->
-                if (list.isEmpty()) {
-                    UiState.Empty
-                } else {
-                    UiState.Success(list)
+        combine(repository.observeAll(), refreshError) { list, err ->
+            when {
+                list.isNotEmpty() -> UiState.Success(list)
+                // Empty cache + failed refresh is a load failure, not "no
+                // playlists yet" — surface Error so the user gets a Retry.
+                err != null -> UiState.Error(err)
+                else -> UiState.Empty
            }
        }
            .asCacheFirstStateFlow(viewModelScope)
@@ -88,6 +144,10 @@ fun PlaylistsListScreen(
    navController: NavHostController,
    viewModel: PlaylistsListViewModel = hiltViewModel(),
 ) {
+    val snackbar = remember { SnackbarHostState() }
+    LaunchedEffect(Unit) {
+        viewModel.transientMessages.collect { snackbar.showSnackbar(it) }
+    }
    Scaffold(
        modifier = Modifier.fillMaxSize(),
        topBar = {
@@ -97,8 +157,10 @@ fun PlaylistsListScreen(
                currentRouteName = Playlists::class.qualifiedName,
            )
        },
+        snackbarHost = { SnackbarHost(snackbar) },
    ) { inner ->
        val state by viewModel.uiState.collectAsStateWithLifecycle()
+        val offline by viewModel.offline.collectAsStateWithLifecycle()
        PullToRefreshScaffold(
            onRefresh = { viewModel.refresh().join() },
            modifier = Modifier.fillMaxSize().padding(inner),
@@ -111,13 +173,16 @@ fun PlaylistsListScreen(
                        "appear once your library has enough plays. Create your " +
                        "own playlist from any album or track in the meantime.",
                )
-                is UiState.Error -> EmptyState(
+                is UiState.Error -> ErrorRetry(
                    title = "Couldn't load playlists",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                )
                is UiState.Success -> PlaylistsGrid(
                    playlists = s.data,
+                    offline = offline,
                    onPlaylistClick = { id -> navController.navigate(PlaylistDetail(id)) },
+                    onPlay = viewModel::playPlaylist,
                )
            }
        }
@@ -127,7 +192,9 @@ fun PlaylistsListScreen(
@Composable
 private fun PlaylistsGrid(
    playlists: List<PlaylistRef>,
+    offline: Boolean,
    onPlaylistClick: (String) -> Unit,
+    onPlay: suspend (PlaylistRef) -> Unit,
 ) {
    val systemPlaylists = playlists.filter { it.isSystem }
    val userPlaylists = playlists.filter { !it.isSystem }
@@ -142,7 +209,16 @@ private fun PlaylistsGrid(
                SectionHeader("System playlists")
            }
            items(items = systemPlaylists, key = { it.id }) { playlist ->
-                PlaylistCard(playlist = playlist, onClick = { onPlaylistClick(playlist.id) })
+                // Greyed offline when it needs the live server or isn't fully
+                // cached — dimmed but still tappable into the detail.
+                val greyed = offline && playlist.unavailableOffline
+                PlaylistCard(
+                    playlist = playlist,
+                    onClick = { onPlaylistClick(playlist.id) },
+                    onPlay = { onPlay(playlist) },
+                    playEnabled = playlist.trackCount > 0 && !greyed,
+                    greyed = greyed,
+                )
            }
        }
        if (userPlaylists.isNotEmpty()) {
@@ -150,7 +226,14 @@ private fun PlaylistsGrid(
                SectionHeader("Your playlists")
            }
            items(items = userPlaylists, key = { it.id }) { playlist ->
-                PlaylistCard(playlist = playlist, onClick = { onPlaylistClick(playlist.id) })
+                val greyed = offline && playlist.unavailableOffline
+                PlaylistCard(
+                    playlist = playlist,
+                    onClick = { onPlaylistClick(playlist.id) },
+                    onPlay = { onPlay(playlist) },
+                    playEnabled = playlist.trackCount > 0 && !greyed,
+                    greyed = greyed,
+                )
            }
        }
    }
@@ -15,6 +15,7 @@ import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.alpha
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
@@ -40,6 +41,10 @@ import com.fabledsword.minstrel.theme.FabledSwordFlatTokens
 * [playEnabled] disables the overlay (50% alpha + ignore taps) — Home
 * uses it for system playlists in offline mode (their server-side
 * shuffle endpoint is unreachable) and for empty playlists.
+ *
+ * [greyed] dims the whole tile (it can't be reliably played offline) while
+ * keeping it tappable — the detail screen is the escape hatch for shuffling
+ * whatever subset is cached. Greyed always disables the play overlay too.
 */
@Composable
 fun PlaylistCard(
@@ -48,11 +53,13 @@ fun PlaylistCard(
    modifier: Modifier = Modifier,
    onPlay: (suspend () -> Unit)? = null,
    playEnabled: Boolean = true,
+    greyed: Boolean = false,
 ) {
    val seedCache = LocalDetailSeedCache.current
    Surface(
        modifier = modifier
            .width(176.dp)
+            .alpha(if (greyed) GREYED_ALPHA else 1f) // dimmed, still clickable
            .clickable {
                seedCache.stashPlaylist(playlist)
                onClick()
@@ -63,7 +70,7 @@ fun PlaylistCard(
            PlaylistCardCover(
                playlist = playlist,
                onPlay = onPlay,
-                playEnabled = playEnabled,
+                playEnabled = playEnabled && !greyed,
            )
            Spacer(Modifier.height(8.dp))
            Text(
@@ -148,6 +155,7 @@ private fun VariantPill(label: String, modifier: Modifier = Modifier) {
 }

 private const val PILL_BG_ALPHA = 0.85f
+private const val GREYED_ALPHA = 0.45f

 private fun subtitleFor(playlist: PlaylistRef): String = when {
    playlist.trackCount > 0 -> "${playlist.trackCount} tracks"
@@ -27,6 +27,7 @@ import com.composables.icons.lucide.Lucide
 import com.fabledsword.minstrel.models.QuarantineRef
 import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.TrackCoverThumb
@@ -43,9 +44,10 @@ fun HiddenTab(viewModel: HiddenTabViewModel = hiltViewModel()) {
                    "and it'll show up here. The track stays out of system " +
                    "playlists until you unhide it.",
            )
-            is UiState.Error -> EmptyState(
+            is UiState.Error -> ErrorRetry(
                title = "Couldn't load hidden tracks",
-                body = s.message,
+                message = s.message,
+                onRetry = { viewModel.refresh() },
            )
            is UiState.Success -> HiddenList(
                rows = s.data,
@@ -3,6 +3,8 @@ package com.fabledsword.minstrel.quarantine.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.QuarantineRef
 import com.fabledsword.minstrel.shared.UiState
@@ -24,6 +26,7 @@ private const val SHARE_STOP_TIMEOUT_MS = 5_000L
 class HiddenTabViewModel @Inject constructor(
    private val repository: QuarantineRepository,
    private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

    private val refreshError = MutableStateFlow<String?>(null)
@@ -61,6 +64,11 @@ class HiddenTabViewModel @Inject constructor(
                .filter { it.kind.startsWith("quarantine.") }
                .collect { refresh() }
        }
+        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // health returns, so a load that failed offline heals unprompted.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
    }

    fun refresh(): Job = viewModelScope.launch {
@@ -46,6 +46,7 @@ import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.nav.Requests
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -78,9 +79,10 @@ fun RequestsScreen(
                    body = "Use Discover to ask Lidarr for new music; your " +
                        "requests show up here.",
                )
-                is UiState.Error -> EmptyState(
+                is UiState.Error -> ErrorRetry(
                    title = "Couldn't load requests",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                )
                is UiState.Success -> RequestList(
                    rows = s.data,
@@ -3,13 +3,17 @@ package com.fabledsword.minstrel.requests.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.RequestRef
+import com.fabledsword.minstrel.models.RequestStatus
 import com.fabledsword.minstrel.requests.data.CancelOutcome
 import com.fabledsword.minstrel.requests.data.RequestsRepository
 import com.fabledsword.minstrel.shared.UiState
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
@@ -20,10 +24,15 @@ import javax.inject.Inject

 private val RELEVANT_EVENT_KINDS = setOf("request.status_changed")

+// Cadence for in-flight request polling — matches the web client (#369):
+// fast enough to feel live, slow enough not to hammer the server.
+private const val POLL_INTERVAL_MS = 12_000L
+
@HiltViewModel
 class RequestsViewModel @Inject constructor(
    private val repository: RequestsRepository,
    private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {

    private val internal = MutableStateFlow<UiState<List<RequestRef>>>(UiState.Loading)
@@ -31,10 +40,21 @@ class RequestsViewModel @Inject constructor(

    init {
        refresh()
+        // SSE push: reconciler completions arrive here; reload silently so the
+        // row updates in place rather than flashing the loading spinner.
        viewModelScope.launch {
            eventsStream.events
                .filter { it.kind in RELEVANT_EVENT_KINDS }
-                .collect { refresh() }
+                .collect { silentReload() }
+        }
+        viewModelScope.launch { pollWhileInFlight() }
+        // Screen-level auto-recovery (issue #1245): a load that failed while
+        // the server was unreachable heals the moment health returns, without
+        // waiting for the next poll tick.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is UiState.Error) silentReload()
+            }
        }
    }

@@ -54,6 +74,47 @@ class RequestsViewModel @Inject constructor(
        }
    }

+    /**
+     * Auto-poll while any request is mid-ingest (status APPROVED), matching the
+     * web client (#369). Reloads silently every [POLL_INTERVAL_MS] and pauses
+     * when nothing is in-flight — complements the SSE push so progress stays
+     * live even if the event stream drops.
+     */
+    private suspend fun pollWhileInFlight() {
+        while (true) {
+            // Also retry from a failed load (issue #1245): from UiState.Error
+            // the in-flight predicate can never become true, so without this
+            // the poll never self-heals the screen — e.g. after a transient
+            // 500 that health monitoring (transport-level) never saw.
+            if (hasInFlightRequest() || internal.value is UiState.Error) {
+                silentReload()
+            }
+            delay(POLL_INTERVAL_MS)
+        }
+    }
+
+    private fun hasInFlightRequest(): Boolean {
+        val state = internal.value
+        return state is UiState.Success &&
+            state.data.any { it.status == RequestStatus.APPROVED }
+    }
+
+    /**
+     * Reload the list in place without flipping to Loading — used by the poll
+     * loop and the SSE collector so visible rows update without a spinner
+     * flash. A transient failure keeps the current view; the next reload wins.
+     */
+    private suspend fun silentReload() {
+        try {
+            val rows = repository.listMine()
+            internal.value = if (rows.isEmpty()) UiState.Empty else UiState.Success(rows)
+        } catch (
+            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
+        ) {
+            // Keep the current view; the next poll / SSE / pull reconciles.
+        }
+    }
+
    /**
     * Optimistically removes [id] from the success list so the row
     * disappears immediately; on server-side success the row is
--- a/Show More
+++ b/Show More