From c94dd502bb8bcacb1282dc689636551bca26cb47 Mon Sep 17 00:00:00 2001
From: Andres Bott <contact@andresbott.com>
Date: Wed, 11 Nov 2026 14:15:55 +0100
Subject: [PATCH 1/2] feat(webui): retry failed requests, recover mobile
 playback after network loss, and add a playback log

---
 AGENTS.md                                     |   2 +-
 docs/agents/authentication.md                 |   6 +-
 docs/agents/frontend.md                       |  70 +++-
 .../src/components/about/PlaybackLogPanel.vue | 115 ++++++
 .../about/__tests__/PlaybackLogPanel.spec.ts  |  53 +++
 .../src/composables/__tests__/useAuth.spec.ts |  45 +-
 .../__tests__/useConnectivity.spec.ts         |  81 ++++
 .../__tests__/usePlayer.recoverStream.spec.ts | 385 ++++++++++++++----
 webui/src/composables/useAuth.ts              |  21 +-
 webui/src/composables/useConnectivity.ts      | 136 ++++++-
 webui/src/composables/usePlayer.ts            | 351 ++++++++++++++--
 webui/src/lib/__tests__/playbackLog.spec.ts   |  55 +++
 webui/src/lib/__tests__/retry.spec.ts         | 100 +++++
 webui/src/lib/api/Libraries.ts                |   7 +-
 webui/src/lib/api/Metadata.ts                 |  20 +-
 webui/src/lib/api/Tokens.ts                   |  11 +-
 webui/src/lib/api/__tests__/Tokens.spec.ts    |  10 +-
 webui/src/lib/api/__tests__/client.spec.ts    |  65 +++
 .../lib/api/__tests__/subsonic.remint.spec.ts |  15 +-
 .../lib/api/__tests__/subsonic.retry.spec.ts  | 123 ++++++
 webui/src/lib/api/client.ts                   |  34 ++
 webui/src/lib/api/subsonic.ts                 |  57 ++-
 webui/src/lib/playbackLog.ts                  |  96 +++++
 webui/src/lib/retry.ts                        |  92 +++++
 webui/src/lib/subsonicSession.ts              |  18 +-
 webui/src/main.ts                             |  51 ++-
 webui/src/views/AboutView.vue                 |   6 +
 webui/src/views/__tests__/AboutView.spec.ts   |   4 +-
 28 files changed, 1853 insertions(+), 176 deletions(-)
 create mode 100644 webui/src/components/about/PlaybackLogPanel.vue
 create mode 100644 webui/src/components/about/__tests__/PlaybackLogPanel.spec.ts
 create mode 100644 webui/src/lib/__tests__/playbackLog.spec.ts
 create mode 100644 webui/src/lib/__tests__/retry.spec.ts
 create mode 100644 webui/src/lib/api/__tests__/subsonic.retry.spec.ts
 create mode 100644 webui/src/lib/playbackLog.ts
 create mode 100644 webui/src/lib/retry.ts

diff --git a/AGENTS.md b/AGENTS.md
index fc22207e..b6a4325d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -74,7 +74,7 @@ a server behind a portal, offered on native servers too (see
 | `WishlistAddView` | `/wishlist/new` | `SearchView`'s layout pointed at MusicBrainz: one pill search box (the shared `SearchField`) with a Search button, and an All / Albums / Artists / Songs filter row (`?kind=`, absent for All). It searches only on Enter, the button or a filter click — never per keystroke, MusicBrainz allows one request per second — and `useWishlistSearch` caches each kind's answer for the submitted text, so narrowing All costs no request. Results come in sections (`WishlistResultRow`); picks survive a new search and the selection pill under the filters adds them all in one request. Results already listed read "On wishlist" and cannot be picked; results already in the catalog link there. Below the search, whatever it shows, `WishlistManualForm` adds an entry by hand (type, title, optional description) for music MusicBrainz does not list — no MBID, so no scan can mark it found — and returns to the wishlist |
 | `WishlistItemView` | `/wishlist/:id` | One entry: found status and, once found, the link to it in the library (`lib/wishlist.ts` `wishlistLibraryRoute`: the artist, the album, or a song's album), a MusicBrainz link (none for an entry added by hand), and editing through `EditActionBar` (Delete removes the entry): a MusicBrainz pick edits only its description (`note` in the API) — the rest is its MusicBrainz snapshot — while an entry added by hand edits every field, type, title and description (`PUT /wishlist/{id}` is a partial update; the server refuses `title`/`kind` on a pick) |
 | `UserSettingsView` | `/user-settings/:tab?` | Personal settings (identity, theme, change password, API tokens). Vertical tablist whose active section is the `tab` path segment (`general` \| `account` \| `access`), so a reload or shared link reopens it; bare `/user-settings` is General, an unknown/unavailable section rewrites back to it. `account` holds the change-password form and appears only in native mode when signed in; `access` needs a signed-in user and `useAuth().managementApi`, so a key session has no Connected apps tab. Reached from the sidebar's `UserMenu` popup, not from `/settings` |
-| `AboutView` | `/about` | About Aether (keyboard shortcuts reference, build info, source link). In the desktop app the build info also lists the player's version (App) and the server's address (Server), and labels the server's version as such. Reached from the `UserMenu` popup |
+| `AboutView` | `/about` | About Aether (keyboard shortcuts reference, build info, the playback log — `PlaybackLogPanel`, the on-device record of player and page-lifecycle events for diagnosing stops on a locked phone — source link). In the desktop app the build info also lists the player's version (App) and the server's address (Server), and labels the server's version as such. Reached from the `UserMenu` popup |
 
 **Settings views** — nested under `/settings` with `meta: { layout: 'settings' }` (not the music layout); `/settings` redirects to `/settings/libraries`. Settings is administration only: account concerns (user settings, logout) live in the sidebar's `UserMenu` popup. The whole area is **admin-only**: `useAuth().isAdmin && managementApi` (a key session has no `/api/v0`) gates the `UserMenu` Admin entry and `App.vue` redirects everyone else landing on a settings route; the backend enforces it with 403 on `/api/v0` (see `docs/agents/authentication.md`):
 
diff --git a/docs/agents/authentication.md b/docs/agents/authentication.md
index e23478d2..7c3d24ae 100644
--- a/docs/agents/authentication.md
+++ b/docs/agents/authentication.md
@@ -213,7 +213,11 @@ mirroring the tokenID oracle the `pat` library warns about.
 
 Mint-time sweep is per-device (see "One session per device" above);
 `GET /api/v0/auth/tokens` reports live spa tokens as `kind: "session"` and drops
-expired ones. A boot-mint that
+expired ones. A boot mint that gets no answer at all (`remintApiKey` →
+`unreachable`) is not a verdict on the session: it raises the connectivity
+banner, spends no retry budget, and the credential watcher mints again once
+the banner's probe finds the server (`onReconnect` in `useAuth.ts`) — the login
+gate's purge would empty the queue over a network blip. A boot mint that
 keeps failing for a non-401 reason surfaces the login gate, whose purge refetches
 `/me` and re-runs the mint watcher — so the SPA caps consecutive failed mints
 (`MAX_MINT_ATTEMPTS` in `webui/src/lib/subsonicSession.ts`) and then leaves the
diff --git a/docs/agents/frontend.md b/docs/agents/frontend.md
index 1f8ec7f5..216bae61 100644
--- a/docs/agents/frontend.md
+++ b/docs/agents/frontend.md
@@ -138,6 +138,25 @@ When a view diverges from these registries, the registry wins.
   `isMeResponse` is what counts as Aether's `/me`: `getMe` rejects any other
   answer with `NotAetherMeError`, and the probe applies the same check.
 - `types/` — one file per API domain, mirroring backend response shapes.
+- `lib/retry.ts` + `composables/useConnectivity.ts` — **network failures heal
+  on their own.** Both clients retry a request that got no answer (or a
+  502/503/504) twice, 400 ms then 1.5 s: `subsonic.ts` `send()` for every
+  `/rest` call except the additive ones (`createPlaylist`, `updatePlaylist`,
+  `createInternetRadioStation`, `scrobble` — a dropped request may have
+  landed), `client.ts`'s first response interceptor for GET/HEAD/OPTIONS/PUT/
+  DELETE and a POST that passes `idempotent: true` (the per-device mint, the
+  reads carried in a body). Anything the server answered is final. Past that,
+  a failure raises the connectivity banner, and while it is up a probe —
+  `checkSession()` (a `/rest` ping, which re-mints an expired key on the way),
+  or `/api/v0/version` before the client is configured — runs on a 2 s → 30 s
+  backoff, at once on the browser's `online` event or when the page is shown
+  again (both are hints, never proof: a phone's are unreliable). Recovery runs
+  the `onReconnect` listeners: `main.ts` refetches every errored active query,
+  the credential watcher re-runs a mint the network swallowed, and the player
+  resumes a track that died with it. Queries and mutations run with
+  `networkMode: 'always'` — the default parks them as paused on `offline` until
+  an `online` that may never come, which was the "works again only after a
+  reload" bug.
 - `lib/apiError.ts` — **the only place a thrown API error becomes text.** Use
   `apiErrorMessage(err, fallback)` instead of re-deriving
   `err?.response?.data?.error ?? err.message`: it reads the server's
@@ -404,8 +423,9 @@ folder's, so a key session offers it only for an upload staged in that edit.
 `canSignOut` (a native or a key session) is what shows Log out. In a key
 session `client.ts` refuses to send at all, and a `/rest` error 40 or 44 sets
 `sessionExpired` instead of minting (`handleRestAuthFailure` in
-`lib/subsonicSession.ts`; `remintApiKey` answers `failed` without a verdict, so
-a media element error reports connectivity rather than signing out); the expiry
+`lib/subsonicSession.ts`; `remintApiKey` answers `failed` without a verdict, and
+the player's recovery asks a ping before it re-points, so a media element error
+alone never signs out); the expiry
 purge forgets the key (`clearApiKey`) before the usual scrub.
 
 `useMe` is disabled until a server is known (`enabled` — a disabled query is
@@ -825,8 +845,9 @@ the note that it blocks saving (above).
 
 **One `<audio>` element** (`new Audio()`, created once, never in the DOM) plays
 every track: a track change — `ended`, a skip, a pick — re-points its `src` and
-calls `play()`. Nothing is fetched ahead, so each change costs the next track's
-fetch and decode before it sounds; there is no gapless playback.
+calls `play()`. Nothing is buffered ahead (the warm-up below only wakes the
+connection), so each change costs the next track's fetch and decode before it
+sounds; there is no gapless playback.
 
 Two elements swapping roles — one playing while the other pre-buffered the next
 track — were tried for seamless transitions and removed (2026-10-25). Live
@@ -848,6 +869,47 @@ to come back. `usePlayer.trackChange.spec.ts` pins both: its fake element
 refuses `play()` until a tap has started it, and the assertions run straight
 after the event, with no await.
 
+**Staying alive on a locked phone.** The track boundary is where a backgrounded
+phone stops playback: the next track is the first request in minutes, and it
+meets a dozing radio, a Wi-Fi ↔ mobile handover or an expired key. Four pieces
+cover it, all in `usePlayer.ts`:
+
+- **Intent, not element state.** `wantsPlayback` is set by `play()` and
+  cleared by any pause that is not a track's end (`el.ended` — the user's, or
+  the system's: headphones out, a call), by `clearQueue`, by the queue running
+  out, and by a refused session. Recovery and the watchdog act only on it, so
+  they never start sound nobody asked for.
+- **Recovery** (`recover` → `attemptRecovery`): an element `error`, a `play()`
+  rejected for anything but autoplay (`NotAllowedError` just stops wanting
+  playback — only a tap can help) or a stall is recovered in place, at its
+  position. Each attempt asks `subsonicClient.checkSession()` first: `ok` →
+  re-point at the fresh URL and resume from `loadedmetadata`; `unreachable` →
+  banner, then retry after 1 s, 2 s … 30 s, or at once on `onReconnect`;
+  `refused` → stop, the session handling owns it. A direct `streamUrl` (radio)
+  is re-pointed without asking. A track that keeps failing with a decode/format
+  error while the server answers is skipped after two re-points; a broken-off
+  transfer (`MEDIA_ERR_NETWORK`) or a stall never counts toward that. Any
+  track change cancels the recovery under way.
+- **Stall watchdog**: armed by `play()` and by `waiting`/`stalled`, disarmed by
+  progress. A position that has not moved for 15 s while playback is wanted is
+  recovered — a swallowed load does not always end in an error.
+- **Warm-up**: 30 s before a track ends, a `Range: bytes=0-65535` request for
+  the next one (through `httpFetch`, body drained and dropped) wakes the radio
+  and the connection while the page is still busy playing. An answer that is
+  not audio (a refused key's Subsonic error) or none at all runs
+  `checkSession()`, so the next URL is built with a good key, or the banner is
+  already up. It is not pre-buffering: the element still fetches the track
+  itself, and the single-element rule above stands.
+
+**Playback log** (`lib/playbackLog.ts`): the last 300 player and page-lifecycle
+events — loads, `playing`, `ended`, errors with their `MediaError` code,
+`waiting`/`stalled`, recovery attempts and session checks, warm-ups, the page
+hidden/shown/frozen/resumed, browser online/offline — persisted to
+localStorage (`aether:playbackLog`), shown newest first on About
+(`PlaybackLogPanel`, with Copy and Clear). A locked phone leaves no other
+trace. **Never log a URL**: stream URLs carry the `apiKey`; entries name track
+ids only.
+
 `loadTrack` seeds `duration` from the catalog's length until the element reports
 the stream's own, so the timeline and the lock screen read right while the next
 track loads. Queue/volume/shuffle/repeat persist to localStorage.
diff --git a/webui/src/components/about/PlaybackLogPanel.vue b/webui/src/components/about/PlaybackLogPanel.vue
new file mode 100644
index 00000000..ad1085c9
--- /dev/null
+++ b/webui/src/components/about/PlaybackLogPanel.vue
@@ -0,0 +1,115 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import Button from 'primevue/button'
+import { clearPlaybackLog, formatPlaybackLog, formatTime, playbackLog } from '@/lib/playbackLog'
+
+// The player's on-device log (lib/playbackLog.ts), newest first: the only
+// record of why playback stopped on a locked phone. Copy hands the whole log,
+// oldest first, to a bug report.
+const newestFirst = computed(() => [...playbackLog.value].reverse())
+
+const copied = ref(false)
+let copiedTimer: ReturnType<typeof setTimeout> | null = null
+
+async function copyLog(): Promise<void> {
+    try {
+        await navigator.clipboard.writeText(formatPlaybackLog(playbackLog.value))
+        copied.value = true
+        if (copiedTimer) clearTimeout(copiedTimer)
+        copiedTimer = setTimeout(() => (copied.value = false), 2000)
+    } catch {
+        // No clipboard (insecure origin, denied): the log stays readable here.
+    }
+}
+</script>
+
+<template>
+    <div class="playback-log">
+        <p class="log-intro">
+            What the player and the page went through — track loads, errors, stalls, recovery
+            attempts, the page being hidden or frozen. When playback stops on its own, copy this
+            into a bug report.
+        </p>
+        <div class="log-actions">
+            <Button
+                class="playback-log-copy"
+                size="small"
+                severity="secondary"
+                :label="copied ? 'Copied' : 'Copy'"
+                :icon="copied ? 'ms-check' : 'ms-content-copy'"
+                :disabled="playbackLog.length === 0"
+                @click="copyLog"
+            />
+            <Button
+                class="playback-log-clear"
+                size="small"
+                severity="secondary"
+                text
+                label="Clear"
+                :disabled="playbackLog.length === 0"
+                @click="clearPlaybackLog"
+            />
+        </div>
+        <p v-if="playbackLog.length === 0" class="log-empty">Nothing recorded yet.</p>
+        <ol v-else class="log-list">
+            <li v-for="(entry, i) in newestFirst" :key="playbackLog.length - i" class="log-entry">
+                <time class="log-time">{{ formatTime(entry.at) }}</time>
+                <span class="log-event">{{ entry.event }}</span>
+                <span v-if="entry.detail" class="log-detail">{{ entry.detail }}</span>
+            </li>
+        </ol>
+    </div>
+</template>
+
+<style scoped>
+.log-intro,
+.log-empty {
+    margin: 0;
+    color: var(--app-text-secondary);
+}
+
+.log-actions {
+    display: flex;
+    gap: 0.5rem;
+    margin: 0.75rem 0;
+}
+
+.log-empty {
+    font-size: 0.9rem;
+}
+
+.log-list {
+    list-style: none;
+    margin: 0;
+    padding: 0.5rem 0.75rem;
+    max-height: 20rem;
+    overflow-y: auto;
+    border: 1px solid var(--app-border);
+    border-radius: 6px;
+    background: var(--app-surface);
+    font-family: monospace;
+    font-size: 0.8rem;
+}
+
+.log-entry {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0 0.75rem;
+    padding: 0.15rem 0;
+}
+
+.log-time {
+    color: var(--app-text-secondary);
+}
+
+.log-event {
+    color: var(--app-text-primary);
+    font-weight: 600;
+}
+
+.log-detail {
+    color: var(--app-text-secondary);
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+</style>
diff --git a/webui/src/components/about/__tests__/PlaybackLogPanel.spec.ts b/webui/src/components/about/__tests__/PlaybackLogPanel.spec.ts
new file mode 100644
index 00000000..c101f0ef
--- /dev/null
+++ b/webui/src/components/about/__tests__/PlaybackLogPanel.spec.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import PrimeVue from 'primevue/config'
+import PlaybackLogPanel from '@/components/about/PlaybackLogPanel.vue'
+import { clearPlaybackLog, logPlayback } from '@/lib/playbackLog'
+
+const mountPanel = () => mount(PlaybackLogPanel, { global: { plugins: [PrimeVue] } })
+
+beforeEach(() => {
+    clearPlaybackLog()
+})
+
+describe('PlaybackLogPanel', () => {
+    it('says so when nothing is recorded, with its buttons disabled', () => {
+        const wrapper = mountPanel()
+        expect(wrapper.find('.log-empty').exists()).toBe(true)
+        expect(wrapper.find('.playback-log-copy').attributes('disabled')).toBeDefined()
+        expect(wrapper.find('.playback-log-clear').attributes('disabled')).toBeDefined()
+    })
+
+    it('lists the entries newest first', () => {
+        logPlayback('load', 'tr-1')
+        logPlayback('error', 'tr-1 code 2')
+        const wrapper = mountPanel()
+        const events = wrapper.findAll('.log-event').map((e) => e.text())
+        expect(events).toEqual(['error', 'load'])
+        expect(wrapper.find('.log-detail').text()).toBe('tr-1 code 2')
+    })
+
+    it('copies the log oldest first', async () => {
+        const writeText = vi.fn(() => Promise.resolve())
+        vi.stubGlobal('navigator', { ...navigator, clipboard: { writeText } })
+        logPlayback('load', 'tr-1')
+        logPlayback('ended')
+        const wrapper = mountPanel()
+
+        await wrapper.find('.playback-log-copy').trigger('click')
+        await flushPromises()
+
+        const text = (writeText.mock.calls[0] as unknown as [string])[0]
+        expect(text.split('\n')).toHaveLength(2)
+        expect(text).toMatch(/load tr-1\n.* ended$/)
+        expect(wrapper.find('.playback-log-copy').text()).toContain('Copied')
+        vi.unstubAllGlobals()
+    })
+
+    it('clears', async () => {
+        logPlayback('load')
+        const wrapper = mountPanel()
+        await wrapper.find('.playback-log-clear').trigger('click')
+        expect(wrapper.find('.log-empty').exists()).toBe(true)
+    })
+})
diff --git a/webui/src/composables/__tests__/useAuth.spec.ts b/webui/src/composables/__tests__/useAuth.spec.ts
index 148ae289..2a26b9c3 100644
--- a/webui/src/composables/__tests__/useAuth.spec.ts
+++ b/webui/src/composables/__tests__/useAuth.spec.ts
@@ -4,6 +4,11 @@ import { mount } from '@vue/test-utils'
 import { VueQueryPlugin, QueryClient } from '@tanstack/vue-query'
 import { flushPromises } from '@vue/test-utils'
 import type { MeResponse } from '@/types/users'
+import { retryDelays } from '@/lib/retry'
+
+// A request the network fails is sent this many times: once, plus the
+// transport's retries (lib/retry.ts).
+const ATTEMPTS = 1 + retryDelays().length
 
 const { getMe, login, logout, clearQueue, stopSync, mintSpaToken } = vi.hoisted(() => ({
     getMe: vi.fn(),
@@ -477,6 +482,36 @@ describe('useAuth', () => {
             expect(subsonicReady.value).toBe(false)
         })
 
+        // A mint the network swallowed is not a refused session: no login gate
+        // (whose purge would empty the queue), the connectivity banner instead,
+        // and a fresh mint once the probe finds the server again.
+        it('waits for the network instead of logging out when the boot mint gets no answer', async () => {
+            const connectivity = await import('@/composables/useConnectivity')
+            const { isOffline } = connectivity.useConnectivity()
+            mintSpaToken.mockRejectedValueOnce(
+                Object.assign(new Error('Network Error'), { isAxiosError: true, code: 'ERR_NETWORK' })
+            )
+            mintSpaToken.mockResolvedValue({
+                token: 'aether_test_key',
+                tokenId: 'tid1',
+                expiresAt: '2999-01-01T00:00:00Z'
+            })
+            getMe.mockResolvedValue(meAlice)
+            withAuth()
+            await flushPromises()
+
+            expect(sessionExpired.value).toBe(false)
+            expect(subsonicReady.value).toBe(false)
+            expect(clearQueue).not.toHaveBeenCalled()
+            expect(isOffline.value).toBe(true)
+
+            connectivity.dismissBanner() // what the probe does once the server answers
+            await flushPromises()
+
+            expect(mintSpaToken).toHaveBeenCalledTimes(2)
+            expect(subsonicReady.value).toBe(true)
+        })
+
         // The failure feedback loop: flipping sessionExpired opens the login
         // gate, whose purge refetches /me and re-runs this watcher. With a
         // persistent non-401 failure that is an unbounded mint loop, so the
@@ -1456,7 +1491,7 @@ describe('useAuth', () => {
             await qc.invalidateQueries({ queryKey: userQueryKeys.restIdentity })
             await flushPromises()
 
-            expect(fetchMock).toHaveBeenCalledTimes(2)
+            expect(fetchMock).toHaveBeenCalledTimes(1 + ATTEMPTS)
             expect(auth.needsServer.value).toBe(false)
             expect(auth.currentUser.value).toEqual({ login: 'alice', role: 'user' })
         })
@@ -1506,7 +1541,7 @@ describe('useAuth', () => {
             const auth = withAuth()
             await flushPromises()
             expect(auth.needsServer.value).toBe(true)
-            expect(fetchMock).toHaveBeenCalledTimes(1)
+            expect(fetchMock).toHaveBeenCalledTimes(ATTEMPTS)
 
             // As setServerUrl(url, 'apiKey') leaves the host's refs for a different
             // server. The watchers flush before the login view calls serverSaved().
@@ -1516,7 +1551,7 @@ describe('useAuth', () => {
             auth.serverSaved()
             await flushPromises()
 
-            expect(fetchMock).toHaveBeenCalledTimes(1)
+            expect(fetchMock).toHaveBeenCalledTimes(ATTEMPTS)
             expect(auth.needsServer.value).toBe(false)
             expect(auth.needsApiKey.value).toBe(true)
             expect(subsonicReady.value).toBe(false)
@@ -1534,7 +1569,7 @@ describe('useAuth', () => {
             const auth = withAuth()
             await flushPromises()
             expect(auth.needsServer.value).toBe(true)
-            expect(fetchMock).toHaveBeenCalledTimes(1)
+            expect(fetchMock).toHaveBeenCalledTimes(ATTEMPTS)
 
             // The server is back.
             fetchMock.mockResolvedValue({
@@ -1544,7 +1579,7 @@ describe('useAuth', () => {
             auth.serverSaved()
             await flushPromises()
 
-            expect(fetchMock).toHaveBeenCalledTimes(2)
+            expect(fetchMock).toHaveBeenCalledTimes(ATTEMPTS + 1)
             expect(auth.needsServer.value).toBe(false)
             expect(auth.currentUser.value).toEqual({ login: 'alice', role: 'user' })
             expect(apiKey.value).toBe('aether_k3y')
diff --git a/webui/src/composables/__tests__/useConnectivity.spec.ts b/webui/src/composables/__tests__/useConnectivity.spec.ts
index 48da4922..1b0ac054 100644
--- a/webui/src/composables/__tests__/useConnectivity.spec.ts
+++ b/webui/src/composables/__tests__/useConnectivity.spec.ts
@@ -113,3 +113,84 @@ describe('useConnectivity window event handlers', () => {
         expect(isOffline.value).toBe(false)
     })
 })
+
+describe('useConnectivity probe', () => {
+    type Mod = typeof import('@/composables/useConnectivity')
+    let mod: Mod
+
+    beforeEach(async () => {
+        vi.useFakeTimers()
+        vi.resetModules()
+        mod = await import('@/composables/useConnectivity')
+    })
+
+    afterEach(() => {
+        mod.resetConnectivityForTests()
+        vi.useRealTimers()
+    })
+
+    it('probes on a backoff while offline and recovers when the server answers', async () => {
+        const probe = vi.fn().mockResolvedValueOnce(false).mockResolvedValue(true)
+        const reconnected = vi.fn()
+        mod.setConnectivityProbe(probe)
+        mod.onReconnect(reconnected)
+        const { isOffline } = mod.useConnectivity()
+
+        mod.reportNetworkError()
+        await vi.advanceTimersByTimeAsync(2_000)
+        expect(probe).toHaveBeenCalledTimes(1)
+        expect(isOffline.value).toBe(true)
+        expect(reconnected).not.toHaveBeenCalled()
+
+        await vi.advanceTimersByTimeAsync(5_000)
+        expect(probe).toHaveBeenCalledTimes(2)
+        expect(isOffline.value).toBe(false)
+        expect(reconnected).toHaveBeenCalledTimes(1)
+
+        // Recovered: no more probing.
+        await vi.advanceTimersByTimeAsync(60_000)
+        expect(probe).toHaveBeenCalledTimes(2)
+    })
+
+    // A phone's 'online' event (or coming back to the page) is a hint, not proof.
+    it('checks at once on a hint instead of trusting it', async () => {
+        const probe = vi.fn().mockResolvedValue(false)
+        mod.setConnectivityProbe(probe)
+        const { isOffline } = mod.useConnectivity()
+        mod.reportNetworkError()
+
+        mod.checkConnectivityNow()
+        await vi.advanceTimersByTimeAsync(0)
+        expect(probe).toHaveBeenCalledTimes(1)
+        expect(isOffline.value).toBe(true)
+    })
+
+    it('does not probe while online', async () => {
+        const probe = vi.fn().mockResolvedValue(true)
+        mod.setConnectivityProbe(probe)
+        mod.checkConnectivityNow()
+        await vi.advanceTimersByTimeAsync(60_000)
+        expect(probe).not.toHaveBeenCalled()
+    })
+
+    it('runs the reconnect listeners when a request succeeds during an outage', () => {
+        const reconnected = vi.fn()
+        mod.onReconnect(reconnected)
+        mod.reportNetworkError()
+        mod.markOnline()
+        expect(reconnected).toHaveBeenCalledTimes(1)
+        // Already online: nothing to recover from.
+        mod.markOnline()
+        expect(reconnected).toHaveBeenCalledTimes(1)
+    })
+
+    it('keeps probing when the probe throws', async () => {
+        const probe = vi.fn().mockRejectedValueOnce(new Error('boom')).mockResolvedValue(true)
+        mod.setConnectivityProbe(probe)
+        const { isOffline } = mod.useConnectivity()
+        mod.reportNetworkError()
+        await vi.advanceTimersByTimeAsync(2_000 + 5_000)
+        expect(probe).toHaveBeenCalledTimes(2)
+        expect(isOffline.value).toBe(false)
+    })
+})
diff --git a/webui/src/composables/__tests__/usePlayer.recoverStream.spec.ts b/webui/src/composables/__tests__/usePlayer.recoverStream.spec.ts
index d0a6fcc6..6676fa40 100644
--- a/webui/src/composables/__tests__/usePlayer.recoverStream.spec.ts
+++ b/webui/src/composables/__tests__/usePlayer.recoverStream.spec.ts
@@ -1,43 +1,57 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-
-// The mint returns whatever the test set, so both the recoverable and the
-// dead-session paths can be driven.
-const remintApiKey = vi.fn(() => Promise.resolve('ok' as 'ok' | 'failed' | 'session-gone'))
-vi.mock('@/lib/subsonicSession', () => ({ remintApiKey }))
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+// The session check answers whatever the test set, so the reachable, the
+// unreachable and the refused paths can all be driven.
+type SessionCheck = 'ok' | 'unreachable' | 'refused'
+const { checkSession, reportNetworkError, reconnectListeners, httpFetch } = vi.hoisted(() => ({
+    checkSession: vi.fn<() => Promise<SessionCheck>>(),
+    reportNetworkError: vi.fn(),
+    reconnectListeners: [] as Array<() => void>,
+    httpFetch: vi.fn()
+}))
 
-// Spy the connectivity signal so tests can assert whether a media error was
-// reported to the user as a server-unreachable failure.
-const { reportNetworkError } = vi.hoisted(() => ({ reportNetworkError: vi.fn() }))
 vi.mock('@/composables/useConnectivity', () => ({
     reportNetworkError,
+    onReconnect: (cb: () => void) => {
+        reconnectListeners.push(cb)
+        return () => {}
+    },
     dismissBanner: vi.fn(),
     markOnline: vi.fn(),
     useConnectivity: () => ({ isOffline: { value: false } })
 }))
 
+vi.mock('@/lib/host', () => ({ httpFetch }))
+
 let streamKey = 'old'
 vi.mock('@/lib/api/subsonic', () => ({
     subsonicClient: {
         isConfigured: () => true,
         getStreamUrl: (id: string) => `https://example.test/stream/${id}?apiKey=${streamKey}`,
-        scrobble: vi.fn(() => Promise.resolve())
+        scrobble: vi.fn(() => Promise.resolve()),
+        checkSession
     }
 }))
 
-// Audio stub that behaves like a real element on the one point under test:
-// assigning a fresh src drops metadata, and setting currentTime before
-// 'loadedmetadata' throws InvalidStateError (as browsers do).
+// Audio stub that behaves like a real element on the points under test:
+// assigning a fresh src drops metadata, setting currentTime before
+// 'loadedmetadata' throws InvalidStateError (as browsers do), and play() can be
+// made to refuse.
 class FakeAudio {
     volume = 1
     duration = 0
     preload = ''
+    paused = true
+    ended = false
+    error: { code: number } | null = null
     playCalls = 0
     loadCalls = 0
+    playResult: () => Promise<void> = () => Promise.resolve()
     private _src = ''
     private _currentTime = 0
     hasMetadata = false
     seekErrors = 0
-    listeners: Record<string, Array<() => void>> = {}
+    listeners: Record<string, Array<(e: Event) => void>> = {}
 
     get src(): string {
         return this._src
@@ -63,11 +77,11 @@ class FakeAudio {
         this.hasMetadata = true
         this._currentTime = seconds
     }
-    addEventListener(type: string, cb: () => void, opts?: { once?: boolean }) {
+    addEventListener(type: string, cb: (e: Event) => void, opts?: { once?: boolean }) {
         const wrapped = opts?.once
-            ? () => {
+            ? (e: Event) => {
                   this.listeners[type] = (this.listeners[type] ?? []).filter((c) => c !== wrapped)
-                  cb()
+                  cb(e)
               }
             : cb
         ;(this.listeners[type] ||= []).push(wrapped)
@@ -78,7 +92,7 @@ class FakeAudio {
     }
     play() {
         this.playCalls++
-        return Promise.resolve()
+        return this.playResult()
     }
     pause() {}
     /** Drive the metadata arrival the browser would report after load(). */
@@ -87,8 +101,18 @@ class FakeAudio {
         this.duration = duration
         this.fire('loadedmetadata')
     }
+    /** A load failure; MediaError code 2 is MEDIA_ERR_NETWORK, 4 SRC_NOT_SUPPORTED. */
+    fail(code = 4) {
+        this.error = { code }
+        this.fire('error')
+    }
+    /** Playback reaching `seconds`, as the browser reports it. */
+    progress(seconds: number) {
+        this._currentTime = seconds
+        this.fire('timeupdate')
+    }
     fire(type: string) {
-        for (const cb of [...(this.listeners[type] ?? [])]) cb()
+        for (const cb of [...(this.listeners[type] ?? [])]) cb({ type } as Event)
     }
 }
 
@@ -108,36 +132,46 @@ const song = (id: string, duration: number) => ({ id, title: id, duration })
 
 let usePlayer: (typeof import('@/composables/usePlayer'))['usePlayer']
 
+/** Let pending promises and timers up to `ms` run. */
+const settle = (ms = 0) => vi.advanceTimersByTimeAsync(ms)
+
 beforeEach(async () => {
+    vi.useFakeTimers()
     localStorage.clear()
     created.length = 0
+    reconnectListeners.length = 0
     streamKey = 'old'
-    remintApiKey.mockClear()
-    remintApiKey.mockResolvedValue('ok')
+    checkSession.mockReset()
+    checkSession.mockResolvedValue('ok')
     reportNetworkError.mockClear()
+    httpFetch.mockReset()
     vi.resetModules()
     usePlayer = (await import('@/composables/usePlayer')).usePlayer
 })
 
+afterEach(() => {
+    vi.useRealTimers()
+})
+
 const activeAudio = () => created[0]!
 
 describe('usePlayer stream recovery', () => {
-    // The regression this file exists for: assigning currentTime straight after
-    // a fresh src happens before metadata loads, so the seek is dropped (or
-    // throws). The position must be restored from a one-shot 'loadedmetadata'.
+    // Assigning currentTime straight after a fresh src happens before metadata
+    // loads, so the seek is dropped (or throws). The position must be restored
+    // from a one-shot 'loadedmetadata'.
     it('restores the position only once metadata has loaded', async () => {
         const player = usePlayer()
         player.playAlbum([song('tr-1', 200)])
         const el = activeAudio()
         el.seedPosition(42)
-        el.playCalls = 0
 
         streamKey = 'new'
-        el.fire('error')
-        await vi.waitFor(() => expect(remintApiKey).toHaveBeenCalledTimes(1))
+        el.fail()
+        await settle()
 
-        // The fresh src is installed with the new key, and NOTHING has tried to
-        // seek yet — an eager assignment here is exactly the bug.
+        // The session was checked (re-minting an expired key on the way), the
+        // fresh src carries the new key, and NOTHING has tried to seek yet.
+        expect(checkSession).toHaveBeenCalledTimes(1)
         expect(el.src).toContain('apiKey=new')
         expect(el.seekErrors).toBe(0)
         expect(el.currentTime).toBe(0)
@@ -146,16 +180,15 @@ describe('usePlayer stream recovery', () => {
         expect(el.currentTime).toBe(42)
     })
 
-    it('resumes playback after the position is restored when it was playing', async () => {
+    it('resumes playback after the position is restored', async () => {
         const player = usePlayer()
         player.playAlbum([song('tr-1', 200)])
         const el = activeAudio()
         el.seedPosition(10)
-        el.fire('play') // isPlaying = true
         el.playCalls = 0
 
-        el.fire('error')
-        await vi.waitFor(() => expect(remintApiKey).toHaveBeenCalledTimes(1))
+        el.fail()
+        await settle()
         // Not yet: play() waits for the restored position.
         expect(el.playCalls).toBe(0)
 
@@ -164,105 +197,295 @@ describe('usePlayer stream recovery', () => {
         expect(el.playCalls).toBe(1)
     })
 
-    it('does not resume a paused element', async () => {
+    // A pause the user (or the system: headphones out, a call) made means no
+    // sound is wanted, so a recovered stream is left paused.
+    it('does not resume after a pause', async () => {
         const player = usePlayer()
         player.playAlbum([song('tr-1', 200)])
         const el = activeAudio()
         el.seedPosition(10)
-        el.fire('pause') // isPlaying = false
+        el.fire('pause')
         el.playCalls = 0
 
-        el.fire('error')
-        await vi.waitFor(() => expect(remintApiKey).toHaveBeenCalledTimes(1))
+        el.fail()
+        await settle()
         el.arriveMetadata()
 
         expect(el.currentTime).toBe(10)
         expect(el.playCalls).toBe(0)
     })
 
-    // One attempt per loaded track: a second error on the same track is a real
-    // playback failure, not an expired credential.
-    it('retries at most once per track', async () => {
+    it('waits for the network instead of touching the element when the server is unreachable', async () => {
+        checkSession.mockResolvedValue('unreachable')
         const player = usePlayer()
         player.playAlbum([song('tr-1', 200)])
         const el = activeAudio()
-        el.seedPosition(5)
+        el.seedPosition(30)
+        const srcBefore = el.src
 
-        el.fire('error')
-        await vi.waitFor(() => expect(remintApiKey).toHaveBeenCalledTimes(1))
+        el.fail(2)
+        await settle()
+
+        expect(reportNetworkError).toHaveBeenCalledTimes(1)
+        expect(el.src).toBe(srcBefore)
+        expect(el.currentTime).toBe(30)
+
+        // The backoff runs out and the server answers again.
+        checkSession.mockResolvedValue('ok')
+        await settle(1_000)
+        expect(checkSession).toHaveBeenCalledTimes(2)
+        expect(el.loadCalls).toBe(1)
         el.arriveMetadata()
+        expect(el.currentTime).toBe(30)
+    })
 
-        el.fire('error')
-        await Promise.resolve()
-        expect(remintApiKey).toHaveBeenCalledTimes(1)
+    it('tries again as soon as connectivity comes back', async () => {
+        checkSession.mockResolvedValue('unreachable')
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200)])
+        const el = activeAudio()
+        el.seedPosition(30)
+
+        el.fail(2)
+        await settle()
+        expect(checkSession).toHaveBeenCalledTimes(1)
+
+        checkSession.mockResolvedValue('ok')
+        reconnectListeners.forEach((cb) => cb())
+        await settle()
+
+        expect(checkSession).toHaveBeenCalledTimes(2)
+        expect(el.loadCalls).toBe(1)
     })
 
-    it('does not touch the element when the mint fails', async () => {
-        remintApiKey.mockResolvedValue('failed')
+    it('leaves a refused session to the session handling', async () => {
+        checkSession.mockResolvedValue('refused')
         const player = usePlayer()
         player.playAlbum([song('tr-1', 200)])
         const el = activeAudio()
         el.seedPosition(30)
         const srcBefore = el.src
 
-        el.fire('error')
-        await vi.waitFor(() => expect(remintApiKey).toHaveBeenCalledTimes(1))
+        el.fail()
+        await settle(60_000)
 
+        expect(checkSession).toHaveBeenCalledTimes(1)
+        expect(reportNetworkError).not.toHaveBeenCalled()
         expect(el.src).toBe(srcBefore)
-        expect(el.currentTime).toBe(30)
     })
 
-    // clearQueue resets the per-track bookkeeping, so the next session's first
-    // track gets a fresh recovery attempt rather than inheriting a spent one.
-    it('re-arms the recovery budget after clearQueue', async () => {
+    // The server answers, the key is good, and the track still will not load:
+    // the file is unplayable. Skip it rather than retry forever.
+    it('skips a track that keeps failing while the server answers', async () => {
         const player = usePlayer()
-        player.playAlbum([song('tr-1', 200)])
+        player.playAlbum([song('tr-1', 200), song('tr-2', 200)])
         const el = activeAudio()
-        el.seedPosition(5)
-        el.fire('error')
-        await vi.waitFor(() => expect(remintApiKey).toHaveBeenCalledTimes(1))
 
-        player.clearQueue()
-        player.playAlbum([song('tr-1', 200)])
-        const next = activeAudio()
-        next.seedPosition(0)
-        next.fire('error')
-        await vi.waitFor(() => expect(remintApiKey).toHaveBeenCalledTimes(2))
+        el.fail()
+        await settle()
+        expect(player.currentTrack.value?.id).toBe('tr-1')
+
+        el.fail()
+        await settle(1_000)
+        expect(player.currentTrack.value?.id).toBe('tr-1')
+
+        el.fail()
+        await settle(2_000)
+        expect(player.currentTrack.value?.id).toBe('tr-2')
+    })
+
+    // A transfer that broke off says nothing about the file: keep retrying.
+    it('never skips a track for network errors', async () => {
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200), song('tr-2', 200)])
+        const el = activeAudio()
+
+        for (const wait of [0, 1_000, 2_000, 4_000]) {
+            el.fail(2)
+            await settle(wait)
+        }
+        expect(player.currentTrack.value?.id).toBe('tr-1')
+        expect(el.loadCalls).toBe(4)
     })
 
     // Regression: clearQueue empties the audio element's src, and the browser
     // fires an 'error' for the now-sourceless element. That is a deliberate stop,
-    // not a connectivity failure — it must not raise the server-unreachable banner.
-    it('does not report a network error when the queue is cleared', async () => {
+    // not a connectivity failure.
+    it('does nothing for the error a cleared queue fires', async () => {
         const player = usePlayer()
         player.playAlbum([song('tr-1', 200)])
         const el = activeAudio()
         el.seedPosition(5)
-        reportNetworkError.mockClear()
 
         player.clearQueue() // sets currentTrack = null and audio.src = ''
-        el.fire('error') // the empty-src error a real <audio> element fires here
+        el.fire('error')
+        await settle(60_000)
 
-        // Flush a full macrotask so the internal dynamic import()/report path,
-        // if reached, has definitely run before we assert it did not.
-        await new Promise((resolve) => setTimeout(resolve, 0))
+        expect(checkSession).not.toHaveBeenCalled()
         expect(reportNetworkError).not.toHaveBeenCalled()
     })
 
-    // The genuine failure path is preserved: a second error on the same loaded
-    // track (after its one retry) is a real stream failure and IS reported.
-    it('reports a network error when a track fails again after its one retry', async () => {
+    it('drops a recovery the next track overtook', async () => {
+        let answer!: (v: SessionCheck) => void
+        checkSession.mockReturnValue(new Promise<SessionCheck>((r) => (answer = r)))
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200), song('tr-2', 200)])
+        const el = activeAudio()
+
+        el.fail()
+        await settle()
+        player.playNext()
+        const loadsBefore = el.loadCalls
+        answer('ok')
+        await settle()
+
+        expect(el.src).toContain('tr-2')
+        expect(el.loadCalls).toBe(loadsBefore)
+    })
+})
+
+describe('usePlayer stall watchdog', () => {
+    it('recovers a load that sits waiting without progress', async () => {
         const player = usePlayer()
         player.playAlbum([song('tr-1', 200)])
         const el = activeAudio()
-        el.seedPosition(5)
+        el.paused = false
+        // Playing, at 12s — the progress stands the start-of-play watch down.
+        el.progress(12)
 
-        el.fire('error') // first error → retry with a re-mint
-        await vi.waitFor(() => expect(remintApiKey).toHaveBeenCalledTimes(1))
-        el.arriveMetadata()
-        reportNetworkError.mockClear()
+        el.fire('waiting')
+        await settle(14_000)
+        expect(checkSession).not.toHaveBeenCalled()
+
+        await settle(1_000)
+        expect(checkSession).toHaveBeenCalledTimes(1)
+        expect(el.loadCalls).toBe(1)
+    })
+
+    it('stands down once playback moves again', async () => {
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200)])
+        const el = activeAudio()
+        el.paused = false
+        // Playing, at 12s — the progress stands the start-of-play watch down.
+        el.progress(12)
+
+        el.fire('waiting')
+        await settle(5_000)
+        el.progress(13)
+        await settle(20_000)
+
+        expect(checkSession).not.toHaveBeenCalled()
+    })
+
+    it('does not watch a paused player', async () => {
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200)])
+        const el = activeAudio()
+        player.pause()
+
+        el.fire('stalled')
+        await settle(30_000)
+
+        expect(checkSession).not.toHaveBeenCalled()
+    })
+
+    // The autoplay policy refused: only a tap can start sound, so retrying would
+    // just loop.
+    it('gives up on a play() the autoplay policy refused', async () => {
+        const player = usePlayer()
+        const el = activeAudio()
+        el.playResult = () => Promise.reject(new DOMException('needs a tap', 'NotAllowedError'))
+        player.playAlbum([song('tr-1', 200)])
+        await settle(30_000)
+
+        expect(checkSession).not.toHaveBeenCalled()
+        expect(el.playCalls).toBe(1)
+    })
+
+    // The pause a browser fires as a track ends is not the user's: the next
+    // track must still be watched.
+    it('keeps watching across a track change', async () => {
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200), song('tr-2', 200)])
+        const el = activeAudio()
+        el.ended = true
+        el.fire('pause')
+        el.fire('ended')
+        el.ended = false
+        expect(player.currentTrack.value?.id).toBe('tr-2')
+
+        await settle(15_000)
+        expect(checkSession).toHaveBeenCalledTimes(1)
+    })
+})
+
+describe('usePlayer next-track warm-up', () => {
+    const audioAnswer = () => ({
+        ok: true,
+        status: 206,
+        headers: new Headers({ 'content-type': 'audio/flac' }),
+        arrayBuffer: () => Promise.resolve(new ArrayBuffer(0))
+    })
+
+    it('asks for the first bytes of the next track near the end of this one', async () => {
+        httpFetch.mockResolvedValue(audioAnswer())
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200), song('tr-2', 200)])
+        const el = activeAudio()
+        el.duration = 200
+
+        el.progress(100)
+        expect(httpFetch).not.toHaveBeenCalled()
+
+        el.progress(175)
+        el.progress(176)
+        await settle()
+        expect(httpFetch).toHaveBeenCalledTimes(1)
+        const [url, init] = httpFetch.mock.calls[0]!
+        expect(url).toContain('/stream/tr-2')
+        expect(init.headers.Range).toBe('bytes=0-65535')
+        expect(checkSession).not.toHaveBeenCalled()
+    })
+
+    it('checks the session when the warm-up is refused, so the next URL gets a good key', async () => {
+        httpFetch.mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: new Headers({ 'content-type': 'application/json' }),
+            arrayBuffer: () => Promise.resolve(new ArrayBuffer(0))
+        })
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200), song('tr-2', 200)])
+        const el = activeAudio()
+        el.duration = 200
+
+        el.progress(180)
+        await settle()
+        expect(checkSession).toHaveBeenCalledTimes(1)
+    })
+
+    it('raises the banner when the warm-up finds no server', async () => {
+        httpFetch.mockRejectedValue(new TypeError('Failed to fetch'))
+        checkSession.mockResolvedValue('unreachable')
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200), song('tr-2', 200)])
+        const el = activeAudio()
+        el.duration = 200
+
+        el.progress(180)
+        await settle()
+        expect(reportNetworkError).toHaveBeenCalledTimes(1)
+    })
+
+    it('does nothing at the end of the queue', async () => {
+        const player = usePlayer()
+        player.playAlbum([song('tr-1', 200)])
+        const el = activeAudio()
+        el.duration = 200
 
-        el.fire('error') // second error on the same track → real failure
-        await vi.waitFor(() => expect(reportNetworkError).toHaveBeenCalledTimes(1))
+        el.progress(190)
+        await settle()
+        expect(httpFetch).not.toHaveBeenCalled()
     })
 })
diff --git a/webui/src/composables/useAuth.ts b/webui/src/composables/useAuth.ts
index e8eaad86..d40275f4 100644
--- a/webui/src/composables/useAuth.ts
+++ b/webui/src/composables/useAuth.ts
@@ -1,9 +1,10 @@
-import { computed, effectScope, nextTick, watch } from 'vue'
+import { computed, effectScope, nextTick, ref, watch } from 'vue'
 import { useMutation, useQueryClient, type QueryClient } from '@tanstack/vue-query'
 import * as AuthApi from '@/lib/api/Auth'
 import { useMe, useRestIdentity, userQueryKeys } from '@/composables/useUsers'
 import { usePlayer } from '@/composables/usePlayer'
 import { useQueueSync } from '@/composables/useQueueSync'
+import { onReconnect, reportNetworkError } from '@/composables/useConnectivity'
 import { explicitLogout, lastServerUrl, sessionExpired } from '@/lib/authState'
 import { DEVICE_ID_KEY } from '@/lib/deviceIdentity'
 import {
@@ -142,8 +143,16 @@ export function useAuth() {
             // authenticated modes (native, proxy-header) an established
             // identity mints the spa token first. Runs again after login
             // (invalidateQueries refetches /me) and after a key is saved.
+            // A boot mint the network swallowed is tried again once the
+            // connection is back (useConnectivity's probe finds the server):
+            // bumping this re-runs the credential watcher.
+            const mintRetry = ref(0)
+            onReconnect(() => {
+                if (!subsonicReady.value) mintRetry.value++
+            })
+
             watch(
-                [me.data, sessionExpired, sessionKind, apiKey],
+                [me.data, sessionExpired, sessionKind, apiKey, mintRetry],
                 async ([data, expired, kind, key], [, , previousKind, previousKey]) => {
                     // A key session that is left — the server step saved a cookie
                     // server, or the kind was switched — or that loses the key it
@@ -191,6 +200,14 @@ export function useAuth() {
                             // server chosen since, without login, would never
                             // render). That one has watcher runs of its own.
                             if (sessionGeneration() !== generation) return
+                            // No answer: not the session's fault. Raise the
+                            // connectivity banner, whose probe re-runs this
+                            // watcher once the server answers — the login gate
+                            // (and its purge of the queue) is for real refusals.
+                            if (result === 'unreachable') {
+                                reportNetworkError()
+                                return
+                            }
                             // A boot-mint failure for any non-401 reason (409
                             // ErrTooManyTokens, 500, network blip) would leave
                             // subsonicReady=false and sessionExpired=false,
diff --git a/webui/src/composables/useConnectivity.ts b/webui/src/composables/useConnectivity.ts
index f68578c2..e6962d2b 100644
--- a/webui/src/composables/useConnectivity.ts
+++ b/webui/src/composables/useConnectivity.ts
@@ -2,35 +2,149 @@ import { ref, readonly } from 'vue'
 
 // Module-level singleton state: ONE app-wide connectivity indicator, not
 // per-request toasts. isOffline stays false until reportNetworkError flips it
-// true; it auto-dismisses on any successful request (dismissBanner) or when the
-// browser reports reconnection (window 'online' event).
+// true. It clears on any successful request (dismissBanner), or when the probe
+// finds the server answering again.
+//
+// While offline, a cheap probe (main.ts installs it: a /rest ping, which also
+// re-mints an expired key) runs on a backoff, and again straight away when the
+// browser reports a reconnection or the page comes back to the foreground. A
+// phone's 'online' event is not reliable on its own — it can fire before the
+// route works, or not at all after a Wi-Fi ↔ mobile handover — so it only
+// triggers a probe, never declares recovery itself. Recovery runs the
+// onReconnect listeners: errored queries refetch, and a track that died with the
+// network resumes. Without this, a blip left views broken until a reload.
 const _isOffline = ref(false)
 
+type Probe = () => Promise<boolean>
+let probe: Probe | null = null
+let probeTimer: ReturnType<typeof setTimeout> | null = null
+let probeInFlight = false
+let probeAttempt = 0
+const reconnectListeners = new Set<() => void>()
+
+// Waits between probes while offline; the last one repeats.
+const PROBE_DELAYS_MS = [2_000, 5_000, 10_000, 20_000, 30_000]
+
+/** Install the check that tells whether the server is reachable again. */
+export function setConnectivityProbe(p: Probe | null): void {
+    probe = p
+}
+
+/**
+ * Run `cb` every time connectivity comes back after a reported failure.
+ * Returns the function that unsubscribes it.
+ */
+export function onReconnect(cb: () => void): () => void {
+    reconnectListeners.add(cb)
+    return () => reconnectListeners.delete(cb)
+}
+
+function cancelProbe(): void {
+    if (probeTimer !== null) clearTimeout(probeTimer)
+    probeTimer = null
+}
+
+function scheduleProbe(): void {
+    if (!probe || probeTimer !== null || probeInFlight) return
+    const delay = PROBE_DELAYS_MS[Math.min(probeAttempt, PROBE_DELAYS_MS.length - 1)]
+    probeAttempt++
+    probeTimer = setTimeout(() => {
+        probeTimer = null
+        void runProbe()
+    }, delay)
+}
+
+async function runProbe(): Promise<void> {
+    if (!probe || probeInFlight) return
+    probeInFlight = true
+    let reachable = false
+    try {
+        reachable = await probe()
+    } catch {
+        reachable = false
+    } finally {
+        probeInFlight = false
+    }
+    if (reachable) {
+        recovered()
+    } else if (_isOffline.value) {
+        scheduleProbe()
+    }
+}
+
+function recovered(): void {
+    const wasOffline = _isOffline.value
+    _isOffline.value = false
+    probeAttempt = 0
+    cancelProbe()
+    if (!wasOffline) return
+    for (const cb of [...reconnectListeners]) {
+        try {
+            cb()
+        } catch (err) {
+            console.error('reconnect listener failed:', err)
+        }
+    }
+}
+
 /**
- * Mark the app as offline. Idempotent: while the banner is already showing,
- * further failures do nothing (no spam).
+ * Mark the app as offline and start probing for the way back. Idempotent: while
+ * the banner is already showing, further failures do nothing (no spam).
  */
 export function reportNetworkError(): void {
     _isOffline.value = true
+    scheduleProbe()
 }
 
 /**
- * Dismiss the connectivity banner. Called when any request succeeds or the
- * browser reports reconnection.
+ * Check right now instead of waiting for the next probe: the browser reported a
+ * reconnection, or the page came back to the foreground. Without a probe there
+ * is nothing to check, and the hint is taken at its word.
+ */
+export function checkConnectivityNow(): void {
+    if (!_isOffline.value) return
+    if (!probe) {
+        recovered()
+        return
+    }
+    cancelProbe()
+    void runProbe()
+}
+
+/**
+ * Dismiss the connectivity banner. Called when any request succeeds or the user
+ * closes it; a dismissal that ends an outage runs the reconnect listeners.
  */
 export function dismissBanner(): void {
-    _isOffline.value = false
+    recovered()
 }
 
 // Alias for clarity in the QueryCache success handler.
 export const markOnline = dismissBanner
 
-// Register window offline/online listeners EXACTLY ONCE at module scope (NOT
-// inside the useConnectivity function body — avoid duplicate listeners on
-// repeated calls). Guard for SSR / test environments where window is undefined.
+// Register window/document listeners EXACTLY ONCE at module scope (NOT inside
+// the useConnectivity function body — avoid duplicate listeners on repeated
+// calls). Guard for SSR / test environments where window is undefined.
 if (typeof window !== 'undefined') {
     window.addEventListener('offline', reportNetworkError)
-    window.addEventListener('online', dismissBanner)
+    window.addEventListener('online', checkConnectivityNow)
+}
+if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+    // A backgrounded phone throttles or freezes the probe's timers: check as soon
+    // as the user is looking again.
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'visible') checkConnectivityNow()
+    })
+}
+
+/** Test hook: forget the probe, its timer and every listener. */
+export function resetConnectivityForTests(): void {
+    cancelProbe()
+    probe = null
+    probeInFlight = false
+    probeAttempt = 0
+    reconnectListeners.clear()
+    _isOffline.value = false
 }
 
 /**
diff --git a/webui/src/composables/usePlayer.ts b/webui/src/composables/usePlayer.ts
index 8cbe4b6f..6741bfa0 100644
--- a/webui/src/composables/usePlayer.ts
+++ b/webui/src/composables/usePlayer.ts
@@ -1,6 +1,9 @@
 import { ref, computed, watch } from 'vue'
 import type { Song, PlayerState } from '@/types/subsonic'
-import { subsonicClient } from '@/lib/api/subsonic'
+import { subsonicClient, type SessionCheck } from '@/lib/api/subsonic'
+import { httpFetch } from '@/lib/host'
+import { installPlaybackLifecycleLog, logPlayback } from '@/lib/playbackLog'
+import { onReconnect, reportNetworkError } from '@/composables/useConnectivity'
 import { saveToLocalStorage, loadFromLocalStorage } from '@/utils/localStorage'
 import { reorderQueue } from '@/utils/queueReorder'
 import {
@@ -55,10 +58,12 @@ const SCROBBLE_MIN_DURATION = 30
 const SCROBBLE_CAP_SECONDS = 240
 let scrobbledTrackId: string | null = null
 
-// One stream-recovery attempt per loaded track: an expired apiKey kills the
-// src URL, which surfaces as an element error, not a JSON response. Re-mint
-// once and re-point; a second failure is a real playback error.
-let streamRetriedTrackId: string | null = null
+// Whether the user wants sound: set by play(), cleared by a pause — theirs, or
+// one the system made (headphones unplugged, a call) — by clearing the queue,
+// and by the queue running out. Recovery and the stall watchdog act only while
+// it is set, so they never start audio nobody asked for. Distinct from
+// isPlaying, which follows the element and is false while a track loads.
+let wantsPlayback = false
 
 const maybeScrobble = (el: HTMLAudioElement): void => {
     const track = currentTrack.value
@@ -71,32 +76,164 @@ const maybeScrobble = (el: HTMLAudioElement): void => {
     void subsonicClient.scrobble(track.id)
 }
 
-const recoverStream = async (el: HTMLAudioElement): Promise<void> => {
+const getTrackUrl = (track: Song | null): string | null => {
+    if (!track) return null
+    if (track.streamUrl) return track.streamUrl
+    if (!subsonicClient.isConfigured()) return null
+    return subsonicClient.getStreamUrl(track.id)
+}
+
+// ---- Stream recovery --------------------------------------------------------
+//
+// A track that fails to load — an element error, a play() the browser rejected
+// for a reason other than autoplay, or a load the stall watchdog gave up on — is
+// recovered in place, at its position. A phone that slept for minutes is the
+// usual cause: the next track is the first request in a while, and it meets a
+// dozing radio, a Wi-Fi ↔ mobile handover or an expired key. Each attempt first
+// asks the server with a cheap ping (subsonicClient.checkSession), which also
+// re-mints an expired key, and only then re-points the element:
+// - the server answers → re-point at the fresh URL and resume;
+// - no answer → raise the connectivity banner and try again after a backoff,
+//   or as soon as the connectivity probe sees the server again (onReconnect);
+// - the session is refused → stop; the session handling owns that.
+// A track that keeps failing while the server answers is unplayable, and is
+// skipped rather than retried forever.
+
+// Waits before the second and later attempts; the first runs at once.
+const RECOVERY_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 15_000, 30_000]
+// Re-points that failed again although the server answered.
+const MAX_FAILURES_WHILE_REACHABLE = 2
+
+interface Recovery {
+    trackId: string
+    reason: string
+    attempts: number
+    failuresWhileReachable: number
+    // Where to resume: the position the failure interrupted, kept across
+    // attempts (a fresh src reads 0 until its metadata loads).
+    position: number
+    timer: ReturnType<typeof setTimeout> | null
+    running: boolean
+    // The last check found no server: a reconnect is worth acting on.
+    waitingForNetwork: boolean
+}
+
+let recovery: Recovery | null = null
+
+const cancelRecovery = (): void => {
+    if (recovery?.timer) clearTimeout(recovery.timer)
+    recovery = null
+}
+
+const recover = (el: HTMLAudioElement, reason: string): void => {
     const track = currentTrack.value
     if (!track) {
         // Nothing is playing (e.g. the queue was cleared): a media error here is
         // a deliberate stop, not a connectivity failure. Stay silent.
         return
     }
-    if (streamRetriedTrackId === track.id) {
-        // Already retried this track once and it failed again — a real stream
-        // failure. Report it so the connectivity banner surfaces.
-        const { reportNetworkError } = await import('@/composables/useConnectivity')
-        reportNetworkError()
+    const position = el.currentTime || 0
+    if (!recovery || recovery.trackId !== track.id) {
+        cancelRecovery()
+        recovery = {
+            trackId: track.id,
+            reason,
+            attempts: 0,
+            failuresWhileReachable: 0,
+            position,
+            timer: null,
+            running: false,
+            waitingForNetwork: false
+        }
+    } else {
+        recovery.reason = reason
+        if (position > 0) recovery.position = position
+    }
+    // One attempt at a time: an error and a rejected play() for the same load
+    // arrive together.
+    if (recovery.running || recovery.timer) return
+    if (recovery.attempts === 0) {
+        void attemptRecovery(el)
         return
     }
-    streamRetriedTrackId = track.id
-    const { remintApiKey } = await import('@/lib/subsonicSession')
-    const result = await remintApiKey()
-    if (result !== 'ok') {
-        // Dead session or failed re-mint — report connectivity failure.
-        const { reportNetworkError } = await import('@/composables/useConnectivity')
+    scheduleRecovery(el)
+}
+
+const scheduleRecovery = (el: HTMLAudioElement): void => {
+    const r = recovery
+    if (!r || r.timer || r.running) return
+    const index = r.attempts - 1
+    if (index >= RECOVERY_DELAYS_MS.length) {
+        // Out of timed attempts. A reconnect can still bring the track back
+        // while the user wants it (see onReconnect below).
+        logPlayback('recover-gave-up', `${r.trackId} after ${r.attempts} attempts`)
+        return
+    }
+    r.timer = setTimeout(() => {
+        r.timer = null
+        if (recovery === r) void attemptRecovery(el)
+    }, RECOVERY_DELAYS_MS[index])
+}
+
+// checkSession turns every failure into an answer; this keeps an unexpected
+// throw from leaving a recovery marked as running forever.
+const checkSession = async (): Promise<SessionCheck> => {
+    try {
+        return await subsonicClient.checkSession()
+    } catch {
+        return 'unreachable'
+    }
+}
+
+const attemptRecovery = async (el: HTMLAudioElement): Promise<void> => {
+    const r = recovery
+    if (!r) return
+    r.running = true
+    r.attempts++
+    logPlayback('recover', `${r.trackId} attempt ${r.attempts} (${r.reason})`)
+    const track = currentTrack.value
+    // A direct stream URL (a radio station) is not this server's: re-point it
+    // without asking.
+    const status = track?.streamUrl ? 'ok' : await checkSession()
+    r.running = false
+    // A track change or a cleared queue overtook the check.
+    if (recovery !== r || currentTrack.value?.id !== r.trackId) return
+    logPlayback('session-check', status)
+    if (status === 'unreachable') {
+        r.waitingForNetwork = true
         reportNetworkError()
+        scheduleRecovery(el)
         return
     }
-    const wasPlaying = isPlaying.value
-    const position = el.currentTime || 0
-    el.src = subsonicClient.getStreamUrl(track.id)
+    r.waitingForNetwork = false
+    if (status === 'refused') {
+        // A dead session: in a cookie session the re-mint already failed with a
+        // 401 and the login gate is coming; a refused key opens the key card.
+        // Nothing to retry until then, so the watchdog stands down too.
+        cancelRecovery()
+        wantsPlayback = false
+        disarmStallWatchdog()
+        return
+    }
+    // Only a decode or format error says the track itself is bad; a broken-off
+    // transfer or a stall on a slow link is the network's, and is retried.
+    if (r.attempts > 1 && r.reason === 'error') r.failuresWhileReachable++
+    if (r.failuresWhileReachable >= MAX_FAILURES_WHILE_REACHABLE) {
+        logPlayback('skip-unplayable', r.trackId)
+        cancelRecovery()
+        if (wantsPlayback && playNextFn) playNextFn()
+        return
+    }
+    repoint(el, r.position)
+}
+
+// Re-point the element at the current track's URL (with whatever key is
+// installed now) and resume at `position`.
+const repoint = (el: HTMLAudioElement, position: number): void => {
+    const url = getTrackUrl(currentTrack.value)
+    if (!url) return
+    el.src = url
+    el.volume = volume.value
     // A fresh src resets the element to "no metadata", where assigning
     // currentTime is dropped (or throws InvalidStateError). Restore the position
     // once the new stream is seekable, then pick playback back up.
@@ -108,20 +245,125 @@ const recoverStream = async (el: HTMLAudioElement): Promise<void> => {
                 // Non-seekable stream: resume from the start rather than fail.
             }
         }
-        if (wasPlaying) {
-            void el.play()
-        }
+        if (wantsPlayback) startPlayback(el)
     }
     el.addEventListener('loadedmetadata', resume, { once: true })
     el.load()
+    // A re-point that never gets as far as metadata is a stall too.
+    if (wantsPlayback) armStallWatchdog(el, 'reload')
+}
+
+// ---- Stall watchdog ---------------------------------------------------------
+//
+// A load the network swallows does not always end in an error: the element can
+// sit in 'waiting' forever. While the user wants sound, a position that has not
+// moved for STALL_TIMEOUT_MS after the element said it was waiting (or after a
+// play() call) is treated as a failed load and recovered.
+const STALL_TIMEOUT_MS = 15_000
+let stallTimer: ReturnType<typeof setTimeout> | null = null
+let stallMark = 0
+
+const disarmStallWatchdog = (): void => {
+    if (stallTimer) clearTimeout(stallTimer)
+    stallTimer = null
+}
+
+const armStallWatchdog = (el: HTMLAudioElement, why: string): void => {
+    if (!wantsPlayback || !currentTrack.value || stallTimer) return
+    stallMark = el.currentTime || 0
+    stallTimer = setTimeout(() => {
+        stallTimer = null
+        if (!wantsPlayback || !currentTrack.value) return
+        if (!el.paused && (el.currentTime || 0) > stallMark + 0.5) return
+        logPlayback('stall-timeout', `${currentTrack.value.id} (${why})`)
+        recover(el, 'stall')
+    }, STALL_TIMEOUT_MS)
+}
+
+// ---- Starting playback ------------------------------------------------------
+
+const startPlayback = (el: HTMLAudioElement): void => {
+    wantsPlayback = true
+    armStallWatchdog(el, 'start')
+    el.play().catch((err: { name?: string; message?: string }) => {
+        // A newer src or pause() interrupted this play() — not a failure.
+        if (err?.name === 'AbortError') return
+        logPlayback('play-rejected', err?.name ?? 'unknown')
+        if (err?.name === 'NotAllowedError') {
+            // Autoplay policy: nothing here can start sound until the user taps
+            // play. Stop wanting it, so the watchdog does not retry in a loop.
+            wantsPlayback = false
+            disarmStallWatchdog()
+            return
+        }
+        console.error('Failed to play:', err)
+        recover(el, 'play-rejected')
+    })
+}
+
+// ---- Warming the next track -------------------------------------------------
+//
+// Near the end of a track, ask the server for the first bytes of the next one.
+// It wakes the radio and the connection while the page is still busy playing,
+// and finds a dead key or a dead network before the handoff needs them: the
+// check re-mints an expired key, so the next track's URL is built with a good
+// one. The answer is thrown away; the element fetches the track itself.
+const WARM_AHEAD_SECONDS = 30
+const WARM_RANGE = 'bytes=0-65535'
+let warmedForTrackId: string | null = null
+
+const maybeWarmNext = (el: HTMLAudioElement): void => {
+    const track = currentTrack.value
+    if (!wantsPlayback || !track || warmedForTrackId === track.id || track.streamUrl) return
+    const total = el.duration || track.duration || 0
+    if (!total || !isFinite(total) || total - (el.currentTime || 0) > WARM_AHEAD_SECONDS) return
+    warmedForTrackId = track.id
+    const nextIndex = resolveStep(1)
+    const next = nextIndex === null ? null : queue.value[nextIndex]
+    if (!next || next.streamUrl || !subsonicClient.isConfigured()) return
+    void warmUp(next.id)
+}
+
+const warmUp = async (id: string): Promise<void> => {
+    try {
+        const response = await httpFetch(subsonicClient.getStreamUrl(id), {
+            headers: { Range: WARM_RANGE }
+        })
+        const type = response.headers.get('content-type') ?? ''
+        // Drain the body so the connection can be reused.
+        await response.arrayBuffer().catch(() => undefined)
+        // A refused key answers a Subsonic error document, not audio.
+        if (response.ok && !type.includes('json') && !type.includes('xml')) {
+            logPlayback('warm-next', `${id} ok`)
+            return
+        }
+        logPlayback('warm-next', `${id} refused (${response.status})`)
+    } catch {
+        logPlayback('warm-next', `${id} no answer`)
+    }
+    const status = await checkSession()
+    logPlayback('session-check', status)
+    if (status === 'unreachable') reportNetworkError()
 }
 
 const initAudio = (): void => {
     if (audio) return
+    installPlaybackLifecycleLog()
     const el = new Audio()
     el.addEventListener('timeupdate', () => {
-        currentTime.value = el.currentTime || 0
+        const now = el.currentTime || 0
+        currentTime.value = now
         maybeScrobble(el)
+        if (stallTimer && now > stallMark + 0.5) disarmStallWatchdog()
+        // Well past where it was recovered: the track is healthy again.
+        if (
+            recovery &&
+            recovery.trackId === currentTrack.value?.id &&
+            now > recovery.position + 5
+        ) {
+            cancelRecovery()
+        }
+        maybeWarmNext(el)
     })
     el.addEventListener('durationchange', () => {
         duration.value = el.duration || 0
@@ -130,30 +372,57 @@ const initAudio = (): void => {
     // suspend a background page soon after its audio stops, so anything awaited
     // in between would wait for the user to come back to it.
     el.addEventListener('ended', () => {
+        logPlayback('ended', currentTrack.value?.id)
         if (playNextFn) playNextFn()
     })
     el.addEventListener('play', () => {
         isPlaying.value = true
     })
+    el.addEventListener('playing', () => {
+        logPlayback('playing', currentTrack.value?.id)
+    })
     el.addEventListener('pause', () => {
         isPlaying.value = false
+        // The pause a track's end brings is not the user's: the next track is
+        // about to start. Any other pause — the user's, or one the system made
+        // (headphones unplugged, a call) — means they no longer want sound. A
+        // pause event that arrives after play() was called again (queued by a
+        // src change, say) is stale: the element is not paused any more.
+        if (el.ended || !el.paused) return
+        wantsPlayback = false
+        disarmStallWatchdog()
+        logPlayback('paused', currentTrack.value?.id)
     })
+    const onWaiting = (event: Event): void => {
+        logPlayback(event.type, currentTrack.value?.id)
+        armStallWatchdog(el, event.type)
+    }
+    el.addEventListener('waiting', onWaiting)
+    el.addEventListener('stalled', onWaiting)
     el.addEventListener('error', () => {
         // An error on a sourceless element is a deliberate stop (clearQueue
         // empties the src), not a stream failure — never alarm the user for it.
-        if (!el.src) return
-        void recoverStream(el)
+        if (!el.src || !currentTrack.value) return
+        const code = el.error?.code
+        logPlayback('error', `${currentTrack.value.id} code ${code ?? '?'}`)
+        // MEDIA_ERR_NETWORK: the transfer broke off, the file is fine.
+        recover(el, code === 2 ? 'network' : 'error')
+    })
+    // The server is back after an outage: a track that died with the network,
+    // or is still waiting out a backoff, gets a fresh attempt now.
+    onReconnect(() => {
+        if (!wantsPlayback || !currentTrack.value) return
+        const r = recovery
+        if (!r || r.trackId !== currentTrack.value.id || r.running) return
+        if (!r.waitingForNetwork) return
+        logPlayback('reconnected', r.trackId)
+        if (r.timer) clearTimeout(r.timer)
+        r.timer = null
+        void attemptRecovery(el)
     })
     audio = el
 }
 
-const getTrackUrl = (track: Song | null): string | null => {
-    if (!track) return null
-    if (track.streamUrl) return track.streamUrl
-    if (!subsonicClient.isConfigured()) return null
-    return subsonicClient.getStreamUrl(track.id)
-}
-
 // Draw a fresh random order over the queue, starting at the given track so the
 // shuffled run begins where playback currently is.
 const rebuildShuffleOrder = (startId?: string): void => {
@@ -304,14 +573,12 @@ export function usePlayer() {
             loadTrack(0)
         }
         if (!audio || !audio.src) return
-        audio.play().catch((err) => {
-            if (err.name !== 'AbortError') {
-                console.error('Failed to play:', err)
-            }
-        })
+        startPlayback(audio)
     }
 
     const pause = (): void => {
+        wantsPlayback = false
+        disarmStallWatchdog()
         audio?.pause()
         isPlaying.value = false
     }
@@ -333,7 +600,11 @@ export function usePlayer() {
         // the timeline — and a phone's lock screen — reads right while it loads.
         duration.value = currentTrack.value?.duration ?? 0
         scrobbledTrackId = null
-        streamRetriedTrackId = null
+        // A new load: whatever was being recovered or watched belonged to the
+        // track before.
+        cancelRecovery()
+        disarmStallWatchdog()
+        logPlayback('load', currentTrack.value?.id)
         const url = getTrackUrl(currentTrack.value)
         if (url && audio) {
             audio.src = url
@@ -516,7 +787,7 @@ export function usePlayer() {
         // logout purge clears the queue, and the next session's first track must
         // start with a fresh scrobble and stream-recovery budget.
         scrobbledTrackId = null
-        streamRetriedTrackId = null
+        cancelRecovery()
         pause()
         if (audio) audio.src = ''
     }
diff --git a/webui/src/lib/__tests__/playbackLog.spec.ts b/webui/src/lib/__tests__/playbackLog.spec.ts
new file mode 100644
index 00000000..6d488b81
--- /dev/null
+++ b/webui/src/lib/__tests__/playbackLog.spec.ts
@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+type Mod = typeof import('@/lib/playbackLog')
+let mod: Mod
+
+beforeEach(async () => {
+    localStorage.clear()
+    vi.resetModules()
+    mod = await import('@/lib/playbackLog')
+})
+
+describe('playbackLog', () => {
+    it('records entries oldest first and survives a reload', async () => {
+        mod.logPlayback('load', 'tr-1')
+        mod.logPlayback('ended')
+        expect(mod.playbackLog.value.map((e) => e.event)).toEqual(['load', 'ended'])
+        expect(mod.playbackLog.value[0]!.detail).toBe('tr-1')
+        expect(mod.playbackLog.value[1]).not.toHaveProperty('detail')
+
+        vi.resetModules()
+        const reloaded = await import('@/lib/playbackLog')
+        expect(reloaded.playbackLog.value.map((e) => e.event)).toEqual(['load', 'ended'])
+    })
+
+    it('keeps only the latest entries', () => {
+        for (let i = 0; i < 350; i++) mod.logPlayback('tick', String(i))
+        expect(mod.playbackLog.value).toHaveLength(300)
+        expect(mod.playbackLog.value[0]!.detail).toBe('50')
+        expect(mod.playbackLog.value.at(-1)!.detail).toBe('349')
+    })
+
+    it('clears', () => {
+        mod.logPlayback('load')
+        mod.clearPlaybackLog()
+        expect(mod.playbackLog.value).toEqual([])
+        expect(JSON.parse(localStorage.getItem('aether:playbackLog')!)).toEqual([])
+    })
+
+    it('starts empty from unreadable storage', async () => {
+        localStorage.setItem('aether:playbackLog', '{not json')
+        vi.resetModules()
+        const reloaded = await import('@/lib/playbackLog')
+        expect(reloaded.playbackLog.value).toEqual([])
+    })
+
+    it('formats one line per entry', () => {
+        const at = new Date(2026, 10, 10, 9, 5, 7, 42).getTime()
+        expect(
+            mod.formatPlaybackLog([
+                { at, event: 'error', detail: 'tr-1 code 2' },
+                { at, event: 'page-hidden' }
+            ])
+        ).toBe('2026-11-10 09:05:07.042 error tr-1 code 2\n2026-11-10 09:05:07.042 page-hidden')
+    })
+})
diff --git a/webui/src/lib/__tests__/retry.spec.ts b/webui/src/lib/__tests__/retry.spec.ts
new file mode 100644
index 00000000..a99a26ac
--- /dev/null
+++ b/webui/src/lib/__tests__/retry.spec.ts
@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { AxiosError } from 'axios'
+import {
+    isNetworkFailure,
+    retryDelays,
+    setRetryDelaysForTests,
+    TransientHttpError,
+    withRetry
+} from '@/lib/retry'
+
+const defaultDelays = retryDelays()
+
+afterEach(() => {
+    setRetryDelaysForTests(defaultDelays)
+    vi.useRealTimers()
+})
+
+describe('isNetworkFailure', () => {
+    it('recognises a request that got no answer', () => {
+        expect(isNetworkFailure(new TypeError('Failed to fetch'))).toBe(true)
+        // The desktop transport rejects with a bare string.
+        expect(isNetworkFailure('error sending request for url (…)')).toBe(true)
+        expect(isNetworkFailure(new AxiosError('Network Error', 'ERR_NETWORK'))).toBe(true)
+        expect(isNetworkFailure(new AxiosError('timeout', 'ECONNABORTED'))).toBe(true)
+    })
+
+    it('counts a gateway that could not reach the server', () => {
+        expect(isNetworkFailure(new TransientHttpError(503))).toBe(true)
+        const gateway = new AxiosError('bad gateway', 'ERR_BAD_RESPONSE', undefined, undefined, {
+            status: 502
+        } as never)
+        expect(isNetworkFailure(gateway)).toBe(true)
+    })
+
+    it('does not count anything the server answered, nor an abort', () => {
+        const refused = new AxiosError('nope', 'ERR_BAD_REQUEST', undefined, undefined, {
+            status: 404
+        } as never)
+        expect(isNetworkFailure(refused)).toBe(false)
+        const crashed = new AxiosError('boom', 'ERR_BAD_RESPONSE', undefined, undefined, {
+            status: 500
+        } as never)
+        expect(isNetworkFailure(crashed)).toBe(false)
+        expect(isNetworkFailure(new DOMException('aborted', 'AbortError'))).toBe(false)
+        expect(isNetworkFailure(new AxiosError('canceled', 'ERR_CANCELED'))).toBe(false)
+        expect(isNetworkFailure(new Error('Subsonic said no'))).toBe(false)
+        expect(isNetworkFailure(null)).toBe(false)
+    })
+})
+
+describe('withRetry', () => {
+    it('retries a network failure and returns the first success', async () => {
+        const attempt = vi
+            .fn()
+            .mockRejectedValueOnce(new TypeError('Failed to fetch'))
+            .mockResolvedValueOnce('ok')
+        await expect(withRetry(attempt)).resolves.toBe('ok')
+        expect(attempt).toHaveBeenCalledTimes(2)
+    })
+
+    it('gives up after its retries and rethrows the last failure', async () => {
+        const failure = new TypeError('Failed to fetch')
+        const attempt = vi.fn().mockRejectedValue(failure)
+        await expect(withRetry(attempt)).rejects.toBe(failure)
+        expect(attempt).toHaveBeenCalledTimes(1 + retryDelays().length)
+    })
+
+    it('does not retry an answer', async () => {
+        const attempt = vi.fn().mockRejectedValue(new Error('HTTP error! status: 500'))
+        await expect(withRetry(attempt)).rejects.toThrow('500')
+        expect(attempt).toHaveBeenCalledTimes(1)
+    })
+
+    it('stops once its signal is aborted', async () => {
+        const controller = new AbortController()
+        const attempt = vi.fn().mockImplementation(() => {
+            controller.abort()
+            return Promise.reject(new TypeError('Failed to fetch'))
+        })
+        await expect(withRetry(attempt, { signal: controller.signal })).rejects.toThrow()
+        expect(attempt).toHaveBeenCalledTimes(1)
+    })
+
+    it('waits the configured delays between attempts', async () => {
+        vi.useFakeTimers()
+        setRetryDelaysForTests([400, 1500])
+        const attempt = vi.fn().mockRejectedValue(new TypeError('Failed to fetch'))
+        const result = withRetry(attempt).catch(() => 'failed')
+
+        await vi.advanceTimersByTimeAsync(0)
+        expect(attempt).toHaveBeenCalledTimes(1)
+        await vi.advanceTimersByTimeAsync(400)
+        expect(attempt).toHaveBeenCalledTimes(2)
+        await vi.advanceTimersByTimeAsync(1499)
+        expect(attempt).toHaveBeenCalledTimes(2)
+        await vi.advanceTimersByTimeAsync(1)
+        expect(attempt).toHaveBeenCalledTimes(3)
+        await expect(result).resolves.toBe('failed')
+    })
+})
diff --git a/webui/src/lib/api/Libraries.ts b/webui/src/lib/api/Libraries.ts
index 320004aa..1788d863 100644
--- a/webui/src/lib/api/Libraries.ts
+++ b/webui/src/lib/api/Libraries.ts
@@ -58,7 +58,12 @@ export async function browseFolders(
 }
 
 export async function previewLibrary(filters: LibraryFilter[], signal?: AbortSignal): Promise<LibraryPreview> {
-    const { data } = await apiClient.post<LibraryPreview>('/libraries/preview', { filters }, { signal })
+    // A read whose filters ride in the body: safe to retry.
+    const { data } = await apiClient.post<LibraryPreview>(
+        '/libraries/preview',
+        { filters },
+        { signal, idempotent: true }
+    )
     return data
 }
 
diff --git a/webui/src/lib/api/Metadata.ts b/webui/src/lib/api/Metadata.ts
index 5bc9ddf0..65c7b2fa 100644
--- a/webui/src/lib/api/Metadata.ts
+++ b/webui/src/lib/api/Metadata.ts
@@ -66,10 +66,12 @@ export async function updateTracks(body: UpdateTracksRequest): Promise<UpdateTra
 // production reverse proxy's header buffer (HTTP 431) — the same fix as
 // getPictures below.
 export async function getRawTags(scanFolder: string, paths: string[]) {
-    const { data } = await apiClient.post<RawTagsResponse>('/metadata/tracks/raw-tags', {
-        scan_folder: scanFolder,
-        paths
-    })
+    const { data } = await apiClient.post<RawTagsResponse>(
+        '/metadata/tracks/raw-tags',
+        { scan_folder: scanFolder, paths },
+        // A read carried in a POST body: safe to retry.
+        { idempotent: true }
+    )
     return data
 }
 
@@ -149,10 +151,12 @@ export async function applyPicture(form: FormData) {
 // production reverse proxy's header buffer (HTTP 431). The image endpoint it
 // returns stays a GET, keyed on one resolved file instead of the selection.
 export async function getPictures(scanFolder: string, paths: string[]): Promise<PictureInfo[]> {
-    const { data } = await apiClient.post<PicturesResponse>('/metadata/pictures/inventory', {
-        scan_folder: scanFolder,
-        paths
-    })
+    const { data } = await apiClient.post<PicturesResponse>(
+        '/metadata/pictures/inventory',
+        { scan_folder: scanFolder, paths },
+        // A read carried in a POST body: safe to retry.
+        { idempotent: true }
+    )
     return data.pictures ?? []
 }
 
diff --git a/webui/src/lib/api/Tokens.ts b/webui/src/lib/api/Tokens.ts
index 5e1ed2c2..e7473f02 100644
--- a/webui/src/lib/api/Tokens.ts
+++ b/webui/src/lib/api/Tokens.ts
@@ -18,10 +18,13 @@ import type {
  * signed in from several first-party apps, each listed under its deviceName.
  */
 export async function mintSpaToken(): Promise<MintSpaTokenResponse> {
-    const { data } = await apiClient.post<MintSpaTokenResponse>('/auth/token', {
-        deviceId: getDeviceId(),
-        deviceName: getDeviceName()
-    })
+    // Safe to retry: a mint supersedes this device's previous token, so a
+    // duplicate that reached the server leaves one live token either way.
+    const { data } = await apiClient.post<MintSpaTokenResponse>(
+        '/auth/token',
+        { deviceId: getDeviceId(), deviceName: getDeviceName() },
+        { idempotent: true }
+    )
     return data
 }
 
diff --git a/webui/src/lib/api/__tests__/Tokens.spec.ts b/webui/src/lib/api/__tests__/Tokens.spec.ts
index 9b2d67fe..504042d4 100644
--- a/webui/src/lib/api/__tests__/Tokens.spec.ts
+++ b/webui/src/lib/api/__tests__/Tokens.spec.ts
@@ -32,10 +32,12 @@ describe('Tokens API', () => {
 
         const res = await Tokens.mintSpaToken()
 
-        expect(post).toHaveBeenCalledWith('/auth/token', {
-            deviceId: getDeviceId(),
-            deviceName: getDeviceName()
-        })
+        expect(post).toHaveBeenCalledWith(
+            '/auth/token',
+            { deviceId: getDeviceId(), deviceName: getDeviceName() },
+            // A mint supersedes this device's token: safe to retry.
+            { idempotent: true }
+        )
         expect(res.tokenId).toBe('tid1')
     })
 
diff --git a/webui/src/lib/api/__tests__/client.spec.ts b/webui/src/lib/api/__tests__/client.spec.ts
index 653c29ff..881de959 100644
--- a/webui/src/lib/api/__tests__/client.spec.ts
+++ b/webui/src/lib/api/__tests__/client.spec.ts
@@ -226,3 +226,68 @@ describe('apiClient in the browser', () => {
         expect(sessionExpired.value).toBe(true)
     })
 })
+
+// A dropped request is retried when sending it twice is harmless: HTTP's
+// idempotent methods, and a POST that says so. Anything the server answered is
+// final, and so is a POST that would create something twice.
+describe('apiClient transport retries', () => {
+    const dropped = () => Promise.reject(new TypeError('Failed to fetch'))
+
+    it('retries a GET the network dropped', async () => {
+        const host = fakeHost(true, SERVER)
+        host.httpFetch.mockImplementationOnce(dropped).mockResolvedValue(jsonResponse({ ok: 1 }))
+        const { apiClient } = await loadClient(host)
+
+        const { data } = await apiClient.get('/version')
+
+        expect(data).toEqual({ ok: 1 })
+        expect(host.httpFetch).toHaveBeenCalledTimes(2)
+    })
+
+    it('retries a gateway error on a GET', async () => {
+        const host = fakeHost(true, SERVER)
+        host.httpFetch
+            .mockResolvedValueOnce(jsonResponse({}, 503))
+            .mockResolvedValue(jsonResponse({ ok: 1 }))
+        const { apiClient } = await loadClient(host)
+
+        await expect(apiClient.get('/version')).resolves.toMatchObject({ data: { ok: 1 } })
+        expect(host.httpFetch).toHaveBeenCalledTimes(2)
+    })
+
+    it('does not retry an answer', async () => {
+        const host = fakeHost(true, SERVER)
+        host.httpFetch.mockResolvedValue(jsonResponse({ title: 'boom' }, 500))
+        const { apiClient } = await loadClient(host)
+
+        await expect(apiClient.get('/version')).rejects.toBeInstanceOf(AxiosError)
+        expect(host.httpFetch).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not retry a POST', async () => {
+        const host = fakeHost(true, SERVER)
+        host.httpFetch.mockImplementation(dropped)
+        const { apiClient } = await loadClient(host)
+
+        await expect(apiClient.post('/wishlist', { items: [] })).rejects.toBeInstanceOf(AxiosError)
+        expect(host.httpFetch).toHaveBeenCalledTimes(1)
+    })
+
+    it('retries a POST marked idempotent', async () => {
+        const host = fakeHost(true, SERVER)
+        host.httpFetch.mockImplementationOnce(dropped).mockResolvedValue(jsonResponse({ token: 't' }))
+        const { apiClient } = await loadClient(host)
+
+        await apiClient.post('/auth/token', {}, { idempotent: true })
+        expect(host.httpFetch).toHaveBeenCalledTimes(2)
+    })
+
+    it('still flags a lost session when the retry answers 401', async () => {
+        const host = fakeHost(true, SERVER)
+        host.httpFetch.mockImplementationOnce(dropped).mockResolvedValue(jsonResponse({}, 401))
+        const { apiClient, sessionExpired } = await loadClient(host)
+
+        await expect(apiClient.get('/me')).rejects.toBeInstanceOf(AxiosError)
+        expect(sessionExpired.value).toBe(true)
+    })
+})
diff --git a/webui/src/lib/api/__tests__/subsonic.remint.spec.ts b/webui/src/lib/api/__tests__/subsonic.remint.spec.ts
index 51042e9d..ada5dedd 100644
--- a/webui/src/lib/api/__tests__/subsonic.remint.spec.ts
+++ b/webui/src/lib/api/__tests__/subsonic.remint.spec.ts
@@ -110,13 +110,26 @@ describe('transparent re-mint', () => {
         expect(sessionExpired.value).toBe(true)
     })
 
-    it('returns failed for non-401 errors (409, 500, network)', async () => {
+    it('returns failed for other refusals (409, 500)', async () => {
         vi.mocked(TokensApi.mintSpaToken).mockRejectedValue({ response: { status: 409 } })
         const result = await remintApiKey()
         expect(result).toBe('failed')
         expect(sessionExpired.value).toBe(false)
     })
 
+    // No answer says nothing about the session, and must not spend the budget
+    // that keeps a refusing server from looping the login gate.
+    it('returns unreachable when the mint got no answer, spending no budget', async () => {
+        vi.mocked(TokensApi.mintSpaToken).mockRejectedValue(
+            Object.assign(new Error('Network Error'), { isAxiosError: true, code: 'ERR_NETWORK' })
+        )
+        for (let i = 0; i < MAX_MINT_ATTEMPTS; i++) {
+            expect(await remintApiKey()).toBe('unreachable')
+        }
+        expect(sessionExpired.value).toBe(false)
+        expect(mintRetriesExhausted()).toBe(false)
+    })
+
     it('discards a mint result when logout happens mid-flight', async () => {
         let resolveDelayedMint: (value: any) => void
         vi.mocked(TokensApi.mintSpaToken).mockReturnValue(
diff --git a/webui/src/lib/api/__tests__/subsonic.retry.spec.ts b/webui/src/lib/api/__tests__/subsonic.retry.spec.ts
new file mode 100644
index 00000000..d5b460d6
--- /dev/null
+++ b/webui/src/lib/api/__tests__/subsonic.retry.spec.ts
@@ -0,0 +1,123 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { subsonicClient } from '@/lib/api/subsonic'
+import { resetSubsonicSession } from '@/lib/subsonicSession'
+import { retryDelays } from '@/lib/retry'
+import * as TokensApi from '@/lib/api/Tokens'
+
+vi.mock('@/lib/api/Tokens', () => ({ mintSpaToken: vi.fn() }))
+
+const ATTEMPTS = 1 + retryDelays().length
+
+const json = (body: unknown, status = 200) => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: () => Promise.resolve(body)
+})
+const okPing = { 'subsonic-response': { status: 'ok' } }
+const failed44 = {
+    'subsonic-response': { status: 'failed', error: { code: 44, message: 'Invalid API key' } }
+}
+
+describe('subsonic client transport retries', () => {
+    beforeEach(() => {
+        resetSubsonicSession()
+        subsonicClient.setApiKey('aether_key')
+    })
+    afterEach(() => {
+        vi.unstubAllGlobals()
+        vi.clearAllMocks()
+    })
+
+    it('retries a request the network dropped', async () => {
+        const fetchMock = vi
+            .fn()
+            .mockRejectedValueOnce(new TypeError('Failed to fetch'))
+            .mockResolvedValueOnce(json(okPing))
+        vi.stubGlobal('fetch', fetchMock)
+
+        await expect(subsonicClient.ping()).resolves.toBe(true)
+        expect(fetchMock).toHaveBeenCalledTimes(2)
+    })
+
+    it('retries a gateway that could not reach the server', async () => {
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(json({}, 503))
+            .mockResolvedValueOnce(json(okPing))
+        vi.stubGlobal('fetch', fetchMock)
+
+        await expect(subsonicClient.ping()).resolves.toBe(true)
+        expect(fetchMock).toHaveBeenCalledTimes(2)
+    })
+
+    it('does not retry an answer the server gave', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(json({}, 500))
+        vi.stubGlobal('fetch', fetchMock)
+
+        await expect(subsonicClient.ping()).resolves.toBe(false)
+        expect(fetchMock).toHaveBeenCalledTimes(1)
+    })
+
+    // A dropped request may still have reached the server: counting the play
+    // twice is worse than missing it.
+    it('never repeats a call that adds something', async () => {
+        const fetchMock = vi.fn().mockRejectedValue(new TypeError('Failed to fetch'))
+        vi.stubGlobal('fetch', fetchMock)
+
+        vi.spyOn(console, 'warn').mockImplementation(() => {})
+        await subsonicClient.scrobble('s1')
+        expect(fetchMock).toHaveBeenCalledTimes(1)
+    })
+})
+
+describe('subsonicClient.checkSession', () => {
+    beforeEach(() => {
+        resetSubsonicSession()
+        subsonicClient.setApiKey('aether_key')
+    })
+    afterEach(() => {
+        vi.unstubAllGlobals()
+        vi.clearAllMocks()
+    })
+
+    it('answers ok when the ping does', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(json(okPing)))
+        await expect(subsonicClient.checkSession()).resolves.toBe('ok')
+    })
+
+    it('answers unreachable when no attempt gets an answer', async () => {
+        const fetchMock = vi.fn().mockRejectedValue(new TypeError('Failed to fetch'))
+        vi.stubGlobal('fetch', fetchMock)
+        await expect(subsonicClient.checkSession()).resolves.toBe('unreachable')
+        expect(fetchMock).toHaveBeenCalledTimes(ATTEMPTS)
+    })
+
+    // The point of checking with a ping: an expired key is replaced on the way.
+    it('re-mints an expired key and answers ok', async () => {
+        vi.mocked(TokensApi.mintSpaToken).mockResolvedValue({
+            token: 'aether_fresh',
+            tokenId: 'tid',
+            expiresAt: '2999-01-01T00:00:00Z'
+        })
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce(json(failed44))
+            .mockResolvedValueOnce(json(okPing))
+        vi.stubGlobal('fetch', fetchMock)
+
+        await expect(subsonicClient.checkSession()).resolves.toBe('ok')
+        expect(TokensApi.mintSpaToken).toHaveBeenCalledTimes(1)
+        expect(subsonicClient.getStreamUrl('s1')).toContain('apiKey=aether_fresh')
+    })
+
+    it('answers refused when the server rejects the session', async () => {
+        vi.mocked(TokensApi.mintSpaToken).mockRejectedValue({ response: { status: 401 } })
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(json(failed44)))
+        await expect(subsonicClient.checkSession()).resolves.toBe('refused')
+    })
+
+    it('answers refused without a configured client', async () => {
+        resetSubsonicSession()
+        await expect(subsonicClient.checkSession()).resolves.toBe('refused')
+    })
+})
diff --git a/webui/src/lib/api/client.ts b/webui/src/lib/api/client.ts
index e43e30e2..1d08e3b3 100644
--- a/webui/src/lib/api/client.ts
+++ b/webui/src/lib/api/client.ts
@@ -1,6 +1,7 @@
 import axios, { type CreateAxiosDefaults } from 'axios'
 import { sessionExpired } from '@/lib/authState'
 import { httpFetch, isDesktopApp, serverUrl, sessionKind } from '@/lib/host'
+import { isNetworkFailure, retryDelays } from '@/lib/retry'
 
 const API_BASE_URL = import.meta.env.VITE_SERVER_URL_V0 || '/api/v0'
 
@@ -44,6 +45,39 @@ if (isDesktopApp()) {
     })
 }
 
+declare module 'axios' {
+    interface AxiosRequestConfig {
+        /**
+         * Marks a POST or PATCH as safe to send twice (a read carried in a body,
+         * the per-device token mint), so a network failure retries it like a
+         * GET. Every other non-idempotent request fails on the first error.
+         */
+        idempotent?: boolean
+        /** How many retries this request has had; set by the retry interceptor. */
+        retryCount?: number
+    }
+}
+
+// HTTP's idempotent methods: running one twice leaves the server as running it once.
+const IDEMPOTENT_METHODS = new Set(['get', 'head', 'options', 'put', 'delete'])
+
+// Registered before the 401 interceptor, so a request retried here into a 401
+// still reaches it. A retry re-sends through apiClient, so the desktop app's
+// base-URL interceptor runs again and the retry goes to the server set now.
+apiClient.interceptors.response.use(undefined, async (error) => {
+    const config = error?.config
+    if (!config || !isNetworkFailure(error)) return Promise.reject(error)
+    const method = (config.method ?? 'get').toLowerCase()
+    if (!IDEMPOTENT_METHODS.has(method) && !config.idempotent) return Promise.reject(error)
+    const attempt = config.retryCount ?? 0
+    const delays = retryDelays()
+    if (attempt >= delays.length || config.signal?.aborted) return Promise.reject(error)
+    const delay = delays[attempt] ?? 0
+    if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay))
+    if (config.signal?.aborted) return Promise.reject(error)
+    return apiClient.request({ ...config, retryCount: attempt + 1 })
+})
+
 // A 401 from any /api/v0 call means the session is gone (expired, or the
 // server restarted with fresh cookie keys) — flag it so the SPA renders the
 // login view. The login endpoint itself is exempt: its 401 is the uniform
diff --git a/webui/src/lib/api/subsonic.ts b/webui/src/lib/api/subsonic.ts
index eaf7d0d0..21bb38dc 100644
--- a/webui/src/lib/api/subsonic.ts
+++ b/webui/src/lib/api/subsonic.ts
@@ -26,6 +26,25 @@ import type {
 } from '@/types/subsonic'
 import { ref } from 'vue'
 import { httpFetch, isDesktopApp, serverUrl } from '@/lib/host'
+import { isNetworkFailure, isTransientStatus, TransientHttpError, withRetry } from '@/lib/retry'
+
+/** What {@link SubsonicClient.checkSession} found. */
+export type SessionCheck = 'ok' | 'unreachable' | 'refused'
+
+// /rest calls that change something additively: run twice, they add the songs
+// twice, create a second playlist or station, or count the play twice. Every
+// other call reads, or sets state to a value, and is safe to repeat.
+const NOT_RETRYABLE = new Set([
+    'createPlaylist.view',
+    'updatePlaylist.view',
+    'createInternetRadioStation.view',
+    'scrobble.view'
+])
+
+function isRetryable(url: string): boolean {
+    const endpoint = new URL(url).pathname.split('/').pop() ?? ''
+    return !NOT_RETRYABLE.has(endpoint)
+}
 
 // The apiKey is REACTIVE on purpose. getCoverArtUrl/getStreamUrl are called
 // from component computeds, which bake the key into the URL they return; a
@@ -153,9 +172,25 @@ class SubsonicClient {
         return u.toString()
     }
 
+    /**
+     * One HTTP round trip, retried on a network failure or a gateway status
+     * (lib/retry.ts) — unless the endpoint must not run twice: a request that
+     * failed in flight may still have reached the server, and adding the same
+     * songs or creating the same playlist again is worse than an error.
+     */
+    private async send(url: string, init?: RequestInit): Promise<Response> {
+        const attempt = async (): Promise<Response> => {
+            const response = await httpFetch(url, init)
+            if (isTransientStatus(response.status)) throw new TransientHttpError(response.status)
+            return response
+        }
+        if (!isRetryable(url)) return attempt()
+        return withRetry(attempt, { signal: init?.signal })
+    }
+
     private async fetchJson(url: string, init?: RequestInit): Promise<any> {
         const generation = this.sessionGeneration
-        const response = await httpFetch(url, init)
+        const response = await this.send(url, init)
         if (!response.ok) {
             throw new Error(`HTTP error! status: ${response.status}`)
         }
@@ -173,7 +208,7 @@ class SubsonicClient {
             const result = await handleRestAuthFailure()
             if (result === 'ok') {
                 const retryUrl = this.rebuildWithFreshKey(url)
-                const retry = await httpFetch(retryUrl, init)
+                const retry = await this.send(retryUrl, init)
                 if (!retry.ok) {
                     throw new Error(`HTTP error! status: ${retry.status}`)
                 }
@@ -206,6 +241,24 @@ class SubsonicClient {
         }
     }
 
+    /**
+     * The cheapest round trip that proves the session works: a ping. A refused
+     * key on it takes the usual path in fetchJson — re-mint and retry in a
+     * cookie session — so 'ok' also means any expired key has been replaced.
+     * - 'ok': the server answered and accepted the credential
+     * - 'unreachable': no answer (or only a gateway's), after the retries
+     * - 'refused': the server answered and the session is not usable
+     */
+    async checkSession(): Promise<SessionCheck> {
+        if (!this.isConfigured()) return 'refused'
+        try {
+            await this.request('ping.view')
+            return 'ok'
+        } catch (err) {
+            return isNetworkFailure(err) ? 'unreachable' : 'refused'
+        }
+    }
+
     /**
      * The caller's own record. Aether answers the resolved owner whatever the
      * `username` parameter says, so none is sent: a key session learns its login
diff --git a/webui/src/lib/playbackLog.ts b/webui/src/lib/playbackLog.ts
new file mode 100644
index 00000000..e172b93a
--- /dev/null
+++ b/webui/src/lib/playbackLog.ts
@@ -0,0 +1,96 @@
+// A small on-device record of what the player and the page went through:
+// element events, recovery attempts, play() refusals, and the page lifecycle
+// (hidden, frozen, back online). Playback that stops on a locked phone leaves
+// no trace anywhere else — there is no console to read on the device — so the
+// About page shows this log, and it can be copied into a bug report.
+//
+// It survives a reload (localStorage), keeps only the latest entries, and
+// never records a URL: stream URLs carry the session's apiKey.
+import { readonly, ref } from 'vue'
+
+export interface PlaybackLogEntry {
+    /** Epoch milliseconds. */
+    at: number
+    event: string
+    detail?: string
+}
+
+const STORAGE_KEY = 'aether:playbackLog'
+const MAX_ENTRIES = 300
+
+function load(): PlaybackLogEntry[] {
+    try {
+        const raw = localStorage.getItem(STORAGE_KEY)
+        const parsed: unknown = raw ? JSON.parse(raw) : []
+        return Array.isArray(parsed) ? (parsed as PlaybackLogEntry[]).slice(-MAX_ENTRIES) : []
+    } catch {
+        return []
+    }
+}
+
+const entries = ref<PlaybackLogEntry[]>(load())
+
+/** The entries, oldest first. */
+export const playbackLog = readonly(entries)
+
+function persist(): void {
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(entries.value))
+    } catch {
+        // Storage full or blocked: the in-memory log still works.
+    }
+}
+
+/** Record one event. `detail` must never hold a URL or a credential. */
+export function logPlayback(event: string, detail?: string): void {
+    const entry: PlaybackLogEntry =
+        detail === undefined ? { at: Date.now(), event } : { at: Date.now(), event, detail }
+    const next = [...entries.value, entry]
+    entries.value = next.length > MAX_ENTRIES ? next.slice(-MAX_ENTRIES) : next
+    persist()
+}
+
+export function clearPlaybackLog(): void {
+    entries.value = []
+    persist()
+}
+
+/** One line per entry, local time with milliseconds — for copying into a report. */
+export function formatPlaybackLog(list: readonly PlaybackLogEntry[]): string {
+    return list
+        .map((e) => `${formatTime(e.at)} ${e.event}${e.detail ? ` ${e.detail}` : ''}`)
+        .join('\n')
+}
+
+export function formatTime(at: number): string {
+    const d = new Date(at)
+    const pad = (n: number, w = 2) => String(n).padStart(w, '0')
+    return (
+        `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+        `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`
+    )
+}
+
+let lifecycleInstalled = false
+
+/**
+ * Record the page lifecycle next to the player's events: whether the page was
+ * hidden, frozen (Chrome's Page Lifecycle `freeze`/`resume`) or offline when
+ * playback stopped is exactly what the log is for. Installed once.
+ */
+export function installPlaybackLifecycleLog(): void {
+    if (lifecycleInstalled || typeof window === 'undefined' || typeof document === 'undefined')
+        return
+    lifecycleInstalled = true
+    document.addEventListener('visibilitychange', () =>
+        logPlayback(`page-${document.visibilityState}`)
+    )
+    document.addEventListener('freeze', () => logPlayback('page-frozen'))
+    document.addEventListener('resume', () => logPlayback('page-resumed'))
+    window.addEventListener('pagehide', () => logPlayback('page-hide'))
+    window.addEventListener('pageshow', (e) =>
+        logPlayback('page-show', (e as PageTransitionEvent).persisted ? 'from bfcache' : undefined)
+    )
+    window.addEventListener('online', () => logPlayback('browser-online'))
+    window.addEventListener('offline', () => logPlayback('browser-offline'))
+}
diff --git a/webui/src/lib/retry.ts b/webui/src/lib/retry.ts
new file mode 100644
index 00000000..0fdeea2c
--- /dev/null
+++ b/webui/src/lib/retry.ts
@@ -0,0 +1,92 @@
+// Transient-failure retry for the SPA's HTTP calls. A phone that wakes, switches
+// from Wi-Fi to mobile data or simply drops a packet fails a request that would
+// succeed a second later; retrying it here keeps that blip from surfacing as an
+// error, or worse, from leaving a view broken until a reload. Only failures
+// that say nothing about the request itself are retried: no answer at all, or a
+// gateway that could not reach the server. Anything the server answered — a
+// 4xx, a 500 — is final.
+
+/** HTTP statuses a proxy or load balancer answers while the server is unreachable. */
+const TRANSIENT_STATUSES = new Set([502, 503, 504])
+
+/**
+ * A response that arrived with one of the transient gateway statuses, thrown so
+ * the retry loop and {@link isNetworkFailure} can tell it from a real answer.
+ */
+export class TransientHttpError extends Error {
+    constructor(readonly status: number) {
+        super(`HTTP error! status: ${status}`)
+        this.name = 'TransientHttpError'
+    }
+}
+
+export function isTransientStatus(status: number): boolean {
+    return TRANSIENT_STATUSES.has(status)
+}
+
+/**
+ * True when `err` means the server was never reached: the desktop transport's
+ * bare-string rejection, fetch's TypeError
+ * ("Failed to fetch", "Load failed", "NetworkError when attempting…"), axios'
+ * ERR_NETWORK / timeout codes, or a transient gateway status. An abort is not
+ * one — whoever aborted wanted the request gone.
+ */
+export function isNetworkFailure(err: unknown): boolean {
+    if (err instanceof TransientHttpError) return true
+    // The desktop app's HTTP plugin rejects a request that got no answer with a
+    // bare string (lib/apiError.ts reads it the same way).
+    if (typeof err === 'string') return true
+    if (typeof err !== 'object' || err === null) return false
+    const e = err as { name?: string; code?: string; response?: unknown; isAxiosError?: boolean }
+    if (e.name === 'AbortError' || e.name === 'CanceledError' || e.code === 'ERR_CANCELED') {
+        return false
+    }
+    if (e.isAxiosError) {
+        if (e.response) return isTransientStatus((e.response as { status: number }).status)
+        return e.code === 'ERR_NETWORK' || e.code === 'ECONNABORTED' || e.code === 'ETIMEDOUT'
+    }
+    return err instanceof TypeError
+}
+
+// The waits before the second and third attempts. Short: these cover a blip,
+// not an outage — vue-query's own retries and the connectivity probe
+// (useConnectivity) take over for anything longer. Specs run without the waits
+// (many reload their modules, so a setup-file override would not stick); one
+// about the timing sets its own with setRetryDelaysForTests.
+let retryDelaysMs: readonly number[] = import.meta.env.MODE === 'test' ? [0, 0] : [400, 1500]
+
+/** The waits between attempts; its length is the number of retries. */
+export function retryDelays(): readonly number[] {
+    return retryDelaysMs
+}
+
+/** Test hook: specs run with zero waits so a retried failure costs no time. */
+export function setRetryDelaysForTests(delays: readonly number[]): void {
+    retryDelaysMs = delays
+}
+
+const sleep = (ms: number): Promise<void> =>
+    ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve()
+
+/**
+ * Runs `attempt`, and again after each of {@link retryDelays} while it fails
+ * with an error `shouldRetry` accepts (by default {@link isNetworkFailure}).
+ * The last failure is rethrown unchanged. `signal`, when given, stops the
+ * retries once it is aborted.
+ */
+export async function withRetry<T>(
+    attempt: () => Promise<T>,
+    opts: { shouldRetry?: (err: unknown) => boolean; signal?: AbortSignal | null } = {}
+): Promise<T> {
+    const shouldRetry = opts.shouldRetry ?? isNetworkFailure
+    const delays = retryDelaysMs
+    for (let i = 0; ; i++) {
+        try {
+            return await attempt()
+        } catch (err) {
+            if (i >= delays.length || opts.signal?.aborted || !shouldRetry(err)) throw err
+            await sleep(delays[i] ?? 0)
+            if (opts.signal?.aborted) throw err
+        }
+    }
+}
diff --git a/webui/src/lib/subsonicSession.ts b/webui/src/lib/subsonicSession.ts
index 84891afc..93b5e1bf 100644
--- a/webui/src/lib/subsonicSession.ts
+++ b/webui/src/lib/subsonicSession.ts
@@ -8,6 +8,7 @@ import { subsonicClient } from '@/lib/api/subsonic'
 import { mintSpaToken } from '@/lib/api/Tokens'
 import { sessionExpired } from '@/lib/authState'
 import { clearSession, sessionKind, setSession } from '@/lib/host'
+import { isNetworkFailure } from '@/lib/retry'
 
 /** /rest calls may fire: auth "none", or a token is installed. App.vue gates on it. */
 export const subsonicReady = ref(false)
@@ -22,9 +23,9 @@ export const spaTokenId = ref<string | null>(null)
 // an expiry on a session that is already over. The reset also lets go of the
 // mint still out, so the next session mints for itself instead of joining a
 // discarded one.
-let mintInFlight: Promise<'ok' | 'session-gone' | 'failed'> | null = null
+let mintInFlight: Promise<MintResult> | null = null
 
-type MintResult = 'ok' | 'session-gone' | 'failed'
+export type MintResult = 'ok' | 'session-gone' | 'failed' | 'unreachable'
 
 /**
  * The current session's generation, bumped by every resetSubsonicSession — the
@@ -65,8 +66,11 @@ export function resetMintAttempts(): void {
  * Mint a fresh spa token and install it on the subsonic client.
  * - 'ok': minted and installed
  * - 'session-gone': mint answered 401 (sessionExpired is flipped)
- * - 'failed': other failure (409 ErrTooManyTokens, 500, network blip), or a
- *   mint whose session was reset while it was out, whatever it answered
+ * - 'unreachable': no answer, even after the transport's retries — says
+ *   nothing about the session, and spends no retry budget
+ * - 'failed': the server refused for another reason (409 ErrTooManyTokens,
+ *   500), or a mint whose session was reset while it was out, whatever it
+ *   answered
  */
 export function remintApiKey(): Promise<MintResult> {
     // A key session has nothing to mint and gives no verdict here: the player
@@ -106,8 +110,10 @@ export function remintApiKey(): Promise<MintResult> {
                     sessionExpired.value = true
                     return 'session-gone' as const
                 }
-                // Non-401 failures (409 ErrTooManyTokens, 500, network blip)
-                // leave the session state alone — the watcher will decide
+                // No answer at all is the network, not the session: the caller
+                // waits for the connection to come back rather than giving up.
+                if (isNetworkFailure(err)) return 'unreachable' as const
+                // Other refusals (409 ErrTooManyTokens, 500) leave the session state alone — the watcher will decide
                 // whether to surface the login gate or a retry affordance.
                 consecutiveMintFailures++
                 return 'failed' as const
diff --git a/webui/src/main.ts b/webui/src/main.ts
index 4803fe2b..d590780e 100644
--- a/webui/src/main.ts
+++ b/webui/src/main.ts
@@ -12,8 +12,16 @@ import Ripple from 'primevue/ripple'
 import CustomTheme from './theme'
 import { useTheme } from './composables/useTheme'
 import { apiErrorMessage, NETWORK_MESSAGE } from './lib/apiError'
-import { reportNetworkError, dismissBanner } from './composables/useConnectivity'
+import {
+    reportNetworkError,
+    dismissBanner,
+    onReconnect,
+    setConnectivityProbe
+} from './composables/useConnectivity'
 import { initHost } from './lib/host'
+import { isNetworkFailure } from './lib/retry'
+import { subsonicClient } from './lib/api/subsonic'
+import { getVersion } from './lib/api/Version'
 import 'primeflex/primeflex.css'
 import 'virtual:material-symbols.css'
 import '@fontsource-variable/inter'
@@ -62,22 +70,34 @@ app.use(ConfirmationService)
 app.use(createPinia())
 app.use(router)
 
+// A connectivity failure, whichever client it came through: axios' "no response"
+// (apiErrorMessage's NETWORK_MESSAGE) or a /rest fetch that never got an answer.
+const isConnectivityError = (error: unknown): boolean =>
+    isNetworkFailure(error) || apiErrorMessage(error) === NETWORK_MESSAGE
+
 const queryClient = new QueryClient({
     defaultOptions: {
         queries: {
             refetchOnWindowFocus: false,
+            // 'always', not the default 'online': vue-query would otherwise park
+            // every query in a "paused" state on the browser's 'offline' event and
+            // wait for its 'online' one — which a phone does not always send, so
+            // the view sat loading until a reload. Failing instead lets the
+            // connectivity probe below bring it back.
+            networkMode: 'always',
             retry: 3,
             staleTime: 1000 * 60 * 5,
             gcTime: 1000 * 60 * 30
         },
         mutations: {
+            networkMode: 'always',
             retry: false
         }
     },
     queryCache: new QueryCache({
         onError: (error) => {
             // Queries retry 3 times, so this fires only after retries are exhausted.
-            if (apiErrorMessage(error) === NETWORK_MESSAGE) {
+            if (isConnectivityError(error)) {
                 reportNetworkError()
             }
         },
@@ -89,7 +109,7 @@ const queryClient = new QueryClient({
     mutationCache: new MutationCache({
         onError: (error) => {
             // Mutations retry: false — show immediately on first network error.
-            if (apiErrorMessage(error) === NETWORK_MESSAGE) {
+            if (isConnectivityError(error)) {
                 reportNetworkError()
             }
         }
@@ -98,6 +118,31 @@ const queryClient = new QueryClient({
 
 app.use(VueQueryPlugin, { queryClient })
 
+// While the banner is up, useConnectivity probes the server with this: a /rest
+// ping once the client is configured — cheap, and an expired key on it is
+// re-minted on the way — or the public version endpoint before that. Any answer
+// counts as reachable; only "no answer" keeps the banner up.
+setConnectivityProbe(async () => {
+    if (subsonicClient.isConfigured()) {
+        return (await subsonicClient.checkSession()) !== 'unreachable'
+    }
+    try {
+        await getVersion()
+        return true
+    } catch (err) {
+        return !isNetworkFailure(err)
+    }
+})
+
+// Back online: whatever failed while the server was unreachable tries again, so
+// a view left on an error recovers without a reload.
+onReconnect(() => {
+    void queryClient.refetchQueries({
+        type: 'active',
+        predicate: (query) => query.state.status === 'error'
+    })
+})
+
 // The host settles where the server is — and inside the desktop app how requests
 // reach it — before anything renders, so the first /me request already goes to
 // the right place. An async function rather than a top-level await, which Vite's
diff --git a/webui/src/views/AboutView.vue b/webui/src/views/AboutView.vue
index ff988b57..09f706c1 100644
--- a/webui/src/views/AboutView.vue
+++ b/webui/src/views/AboutView.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import ContentScaffold from '@/components/layout/ContentScaffold.vue'
+import PlaybackLogPanel from '@/components/about/PlaybackLogPanel.vue'
 import { useVersion } from '@/composables/useVersion'
 import { useViewport } from '@/composables/useViewport'
 import { appVersion, isDesktopApp, serverUrl } from '@/lib/host'
@@ -107,6 +108,11 @@ const buildTime = computed(() => serverVersion.value?.build_time || '')
                     </dl>
                 </section>
 
+                <section class="about-section">
+                    <h2>Playback log</h2>
+                    <PlaybackLogPanel />
+                </section>
+
                 <section class="about-section">
                     <h2>Source</h2>
                     <p>
diff --git a/webui/src/views/__tests__/AboutView.spec.ts b/webui/src/views/__tests__/AboutView.spec.ts
index cf657599..d8ab3eac 100644
--- a/webui/src/views/__tests__/AboutView.spec.ts
+++ b/webui/src/views/__tests__/AboutView.spec.ts
@@ -57,10 +57,10 @@ describe('AboutView', () => {
         expect(w.find('.scaffold-title h1').text()).toBe('About')
     })
 
-    it('orders the sections shortcuts, build, source, credits with no brand hero', () => {
+    it('orders the sections shortcuts, build, playback log, source, credits with no brand hero', () => {
         const w = mountView()
         const headers = w.findAll('.about-section h2').map((h) => h.text())
-        expect(headers).toEqual(['Keyboard shortcuts', 'Build', 'Source', 'Credits'])
+        expect(headers).toEqual(['Keyboard shortcuts', 'Build', 'Playback log', 'Source', 'Credits'])
         expect(w.find('.about-hero').exists()).toBe(false)
     })
 

From 460f234e99570aed305e13969fd836aa12da94ac Mon Sep 17 00:00:00 2001
From: Andres Bott <contact@andresbott.com>
Date: Wed, 11 Nov 2026 18:19:54 +0100
Subject: [PATCH 2/2] ci: cap player job and apt step runtime and retry apt
 downloads

---
 .github/workflows/player.yml  | 8 ++++++--
 .github/workflows/release.yml | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/player.yml b/.github/workflows/player.yml
index b796bcf8..7a2eebe3 100644
--- a/.github/workflows/player.yml
+++ b/.github/workflows/player.yml
@@ -15,6 +15,9 @@ jobs:
   lint-and-test:
     name: lint + test
     runs-on: ubuntu-latest
+    # A cold run takes ~10 min; the cap keeps a hung step (e.g. apt during a
+    # mirror/DNS outage) from holding the PR for GitHub's 6-hour default.
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v4
 
@@ -22,9 +25,10 @@ jobs:
       # keyring's secret-service backend. Same list as release.yml's player job,
       # player/Makefile and docs/agents/player/testing.md — keep them in sync.
       - name: Install system dependencies
+        timeout-minutes: 10
         run: |
-          sudo apt-get update
-          sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
+          sudo apt-get -o Acquire::Retries=3 update
+          sudo apt-get -o Acquire::Retries=3 install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
             libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev \
             libasound2-dev libdbus-1-dev
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index cf9dad65..c4a5c610 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -161,6 +161,9 @@ jobs:
             target: x86_64-apple-darwin
             bundles: dmg
     runs-on: ${{ matrix.os }}
+    # A cold build takes ~10 min; the cap keeps a hung step (e.g. apt during a
+    # mirror/DNS outage) from holding the release for GitHub's 6-hour default.
+    timeout-minutes: 45
     defaults:
       run:
         # One set of steps for all three OSes (Windows defaults to PowerShell).
@@ -172,9 +175,10 @@ jobs:
       # Same list as player.yml plus patchelf for the AppImage.
       - name: Install system dependencies (linux)
         if: runner.os == 'Linux'
+        timeout-minutes: 10
         run: |
-          sudo apt-get update
-          sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
+          sudo apt-get -o Acquire::Retries=3 update
+          sudo apt-get -o Acquire::Retries=3 install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
             libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev \
             libasound2-dev libdbus-1-dev patchelf