feat(spotify): reconnect a dead session at track boundaries

librespot's core Session does not auto-reconnect: if the connection
drops (laptop sleep/wake, network change, long stall) it shuts down and
stays dead. Previously the session was cached in a OnceLock and reused
forever, so after a drop every subsequent track failed.

Keep the runtime in the OnceLock (it hosts the playing track's Player,
so it must never be dropped) but move the Session into a
Mutex<Option<Session>>. A new session() accessor checks is_invalid() and
reconnects from cached credentials (no re-login — the cached credential
is long-lived) before each track's resolve/open_playback. Playlists now
self-heal across a connection blip at the next track.

The currently-playing track can't be rescued mid-stream (its Player is
bound to the old session), and a single track looping forever won't
recover until restart, since it never reaches a new open_playback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: program247365

CLAUDE.md

@@ -144,10 +144,13 @@ uses librespot:
 - `src/spotify/mod.rs`
   - `is_spotify_url`, URL/URI parsing (`open.spotify.com/...`, `intl-xx`
     prefixes, `spotify:` URIs)
-  - a shared, lazily-connected `Session` (`OnceLock`) built from cached OAuth
-    credentials; `login()` runs the `librespot-oauth` browser flow once.
-    `Session::new` calls `Handle::current()`, so it must be built **inside** the
-    runtime (`runtime.block_on`)
+  - a shared runtime (`OnceLock`, never replaced — it hosts player tasks) plus a
+    rebuildable `Session` (`Mutex<Option<Session>>`). `session()` reconnects from
+    cached credentials when the previous session `is_invalid()` (sleep/wake,
+    network change) — librespot's core `Session` does **not** auto-reconnect, so
+    track transitions self-heal here. `login()` runs the `librespot-oauth`
+    browser flow once. `Session::new` calls `Handle::current()`, so it must be
+    built **inside** the runtime (`runtime.block_on`)
   - `resolve()` → `Vec<TrackInfo>` for a track, playlist, or album, fetching
     track metadata + album art concurrently (bounded batches). Album art is a
     public `i.scdn.co` JPEG keyed by file id, cached under `spotify/art/`
@@ -213,7 +216,7 @@ There are now two major UI modes:
 - the visualizer reads from `sample_buf: Arc<Mutex<VecDeque<f32>>>`
 - prefetch uses a background worker thread
 - some stream-backed audio inputs create a Tokio runtime inside `AudioPlayer`
-- Spotify owns a process-wide Tokio runtime + connected `Session` in `src/spotify/` (`OnceLock`); librespot's `Player` and the end-of-track loop listener run on it. The bridge's end-of-track listener is aborted when the `AudioPlayer`'s `SpotifyPlayback` drops, releasing the `Player`
+- Spotify owns a process-wide Tokio runtime in `src/spotify/` (`OnceLock`, never replaced — librespot's `Player` and the end-of-track loop listener run on it). The `Session` lives in a `Mutex<Option<Session>>` and is rebuilt by `session()` when `is_invalid()`, so a dropped connection reconnects at the next track (the currently-playing track's `Player` is bound to the old session and can't self-heal mid-stream; a single track looping forever won't recover until restart). The bridge's end-of-track listener is aborted when the `AudioPlayer`'s `SpotifyPlayback` drops, releasing the `Player`
 - media-key events from `souvlaki` arrive on the OS-specific thread (macOS: main / AppKit; Linux: souvlaki's own DBus thread) and are forwarded to the TUI thread via an `mpsc::Receiver<KeyCommand>` drained inside `run_loop`
 
 ## Notable Design Decisions

src/spotify/mod.rs

@@ -13,7 +13,7 @@
 mod sink;
 
 use std::path::{Path, PathBuf};
-use std::sync::{Arc, OnceLock};
+use std::sync::{Arc, Mutex, OnceLock};
 use std::time::Duration;
 
 use color_eyre::eyre::{eyre, Result, WrapErr};
@@ -87,40 +87,41 @@ pub fn login() -> Result<()> {
 pub fn resolve(url: &str) -> Result<Vec<TrackInfo>> {
     let uri = parse_uri(url)?;
     let ctx = ctx()?;
+    let session = session()?;
     match &uri {
         SpotifyUri::Track { .. } => {
             let info = ctx.runtime.block_on(async {
-                let track = Track::get(&ctx.session, &uri)
+                let track = Track::get(&session, &uri)
                     .await
                     .map_err(|e| eyre!("failed to fetch Spotify track metadata: {e}"))?;
                 let track_uri = uri
                     .to_uri()
                     .map_err(|e| eyre!("failed to build Spotify track URI: {e}"))?;
-                ensure_track_available(&ctx.session, &uri).await?;
+                ensure_track_available(&session, &uri).await?;
                 let thumbnail = download_cover(&HttpClient::new(), &track, &art_dir()?, 0).await;
                 Ok::<_, color_eyre::eyre::Report>(track_info(track, track_uri, None, thumbnail))
             })?;
             Ok(vec![info])
         }
         SpotifyUri::Playlist { .. } => {
             let tracks = ctx.runtime.block_on(async {
-                let playlist = Playlist::get(&ctx.session, &uri)
+                let playlist = Playlist::get(&session, &uri)
                     .await
                     .map_err(|e| eyre!("failed to fetch Spotify playlist: {e}"))?;
                 let name = Some(playlist.name().to_string());
                 let uris: Vec<SpotifyUri> = playlist.tracks().cloned().collect();
-                fetch_track_infos(&ctx.session, uris, name).await
+                fetch_track_infos(&session, uris, name).await
             })?;
             ensure_nonempty(tracks, "playlist")
         }
         SpotifyUri::Album { .. } => {
             let tracks = ctx.runtime.block_on(async {
-                let album = Album::get(&ctx.session, &uri)
+                let album = Album::get(&session, &uri)
                     .await
                     .map_err(|e| eyre!("failed to fetch Spotify album: {e}"))?;
                 let name = Some(album.name.clone());
                 let uris: Vec<SpotifyUri> = album.tracks().cloned().collect();
-                fetch_track_infos(&ctx.session, uris, name).await
+                fetch_track_infos(&session, uris, name).await
             })?;
             ensure_nonempty(tracks, "album")
         }
@@ -292,19 +293,20 @@ pub fn open_playback(
     repeat: bool,
 ) -> Result<(SpotifySource, SpotifyPlayback, u32, u16, Option<Duration>)> {
     let ctx = ctx()?;
+    let session = session()?;
     let uri =
         SpotifyUri::from_uri(track_uri).map_err(|e| eyre!("invalid Spotify track URI: {e}"))?;
     let (spotify_sink, source, end_signal) = sink::bridge();
 
     let (player, duration, listener) = ctx.runtime.block_on(async move {
-        let duration = match Track::get(&ctx.session, &uri).await {
+        let duration = match Track::get(&session, &uri).await {
             Ok(track) => Some(Duration::from_millis(track.duration.max(0) as u64)),
             Err(_) => None,
         };
 
         let player = Player::new(
             PlayerConfig::default(),
-            ctx.session.clone(),
+            session,
             Box::new(NoOpVolume),
             move || Box::new(spotify_sink),
         );
@@ -346,41 +348,62 @@ pub fn open_playback(
     ))
 }
 
-/// Shared, connected librespot session plus the runtime its tasks run on.
+/// Shared librespot runtime plus a session that can be rebuilt on demand. The
+/// runtime is created once and never replaced — it hosts every track's player
+/// tasks, so dropping it would kill playback. Only the session is swapped when
+/// its connection dies.
 struct SpotifyCtx {
     runtime: Runtime,
-    session: Session,
+    session: Mutex<Option<Session>>,
 }
 
 static CTX: OnceLock<SpotifyCtx> = OnceLock::new();
 
-/// Lazily connect (once per process) and return the shared context. Calls
-/// after the first reuse the same connection.
+/// The shared runtime + session slot, created once per process. Does not
+/// connect — that happens lazily in [`session`].
 fn ctx() -> Result<&'static SpotifyCtx> {
     if let Some(ctx) = CTX.get() {
         return Ok(ctx);
     }
-    let ctx = init_ctx()?;
+    let ctx = SpotifyCtx {
+        runtime: build_runtime()?,
+        session: Mutex::new(None),
+    };
     // A racing thread may have set it first; that's fine, drop ours.
     let _ = CTX.set(ctx);
     Ok(CTX.get().expect("context was just set"))
 }
 
-fn init_ctx() -> Result<SpotifyCtx> {
-    let runtime = build_runtime()?;
+/// A connected librespot session (a cheap `Arc` clone). Reconnects from cached
+/// credentials if the previous session died — e.g. after sleep/wake or a
+/// network change — so playback recovers at the next track instead of failing.
+/// librespot's core `Session` does not auto-reconnect, so we do it here. Called
+/// at each track boundary (resolve / open_playback), never inside an async
+/// context, so the blocking reconnect is safe.
+fn session() -> Result<Session> {
+    let ctx = ctx()?;
+    let mut slot = ctx.session.lock().unwrap();
+    let needs_connect = slot.as_ref().map_or(true, |session| session.is_invalid());
+    if needs_connect {
+        *slot = Some(connect_session(&ctx.runtime)?);
+    }
+    Ok(slot.as_ref().expect("session connected above").clone())
+}
+
+/// Connect a fresh session from cached OAuth credentials (no re-login needed —
+/// the cached credential is long-lived). `Session::new` calls
+/// `Handle::current()`, so it must be built inside the runtime.
+fn connect_session(runtime: &Runtime) -> Result<Session> {
     let cache = open_cache()?;
     let credentials = cache
         .credentials()
         .ok_or_else(|| eyre!("not logged in to Spotify — run `looper spotify login` first"))?;
-    // `Session::new` calls `Handle::current()`, so build + connect it inside the
-    // runtime context.
-    let session = runtime
+    runtime
         .block_on(async move {
             let session = Session::new(SessionConfig::default(), Some(cache));
             session.connect(credentials, true).await.map(|()| session)
         })
-        .wrap_err("failed to connect to Spotify (is your Premium login still valid?)")?;
-    Ok(SpotifyCtx { runtime, session })
+        .wrap_err("failed to connect to Spotify (is your Premium login still valid?)")
 }
 
 fn open_cache() -> Result<Cache> {