PLAYER: Fixed connected device logic.

Cargo.lock

@@ -1418,7 +1418,7 @@ checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
 
 [[package]]
 name = "furumusic"
-version = "0.1.21"
+version = "0.2.2"
 dependencies = [
  "anyhow",
  "async-trait",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "furumusic"
-version = "0.1.22"
+version = "0.2.3"
 edition = "2024"
 description = "Reusable web-app boilerplate: auth, OIDC/SSO, admin panel, user management, i18n, PostgreSQL"
 

src/agent/cover_art.rs

@@ -323,33 +323,51 @@ pub async fn save_cover_to_storage(
     let hash = hash_image(&cover.data);
 
     // Check if we already have this exact image in the DB
-    let existing: Option<(i64,)> = sqlx::query_as(
-        "SELECT id FROM furumusic__media_file WHERE sha256_hash = $1 AND file_type = 'cover_art' LIMIT 1",
+    let existing: Option<(i64, String)> = sqlx::query_as(
+        "SELECT id, file_path FROM furumusic__media_file WHERE sha256_hash = $1 AND file_type = 'cover_art' LIMIT 1",
     )
     .bind(&hash)
     .fetch_optional(pool)
     .await?;
 
-    if let Some((id,)) = existing {
-        if let Some((file_path,)) = sqlx::query_as::<_, (String,)>(
-            "SELECT file_path FROM furumusic__media_file WHERE id = $1",
-        )
-        .bind(id)
-        .fetch_optional(pool)
-        .await?
-        {
-            let path = PathBuf::from(&file_path);
-            let path = if path.is_absolute() {
-                path
-            } else {
-                Path::new(storage_dir).join(path)
-            };
+    if let Some((id, file_path)) = existing {
+        let path = crate::media_paths::resolve_media_file_path(storage_dir, &file_path);
+        let is_inside_storage = crate::media_paths::path_for_root(storage_dir, &path).is_some();
+        if !is_inside_storage {
+            tracing::warn!(
+                media_file_id = id,
+                path = %path.display(),
+                "Ignoring duplicate cover hash whose stored file is outside agent_storage_dir"
+            );
+        } else if !path.exists() {
+            if let Some(parent) = path.parent() {
+                tokio::fs::create_dir_all(parent).await?;
+            }
+            match tokio::fs::write(&path, &cover.data).await {
+                Ok(()) => {
+                    tracing::info!(
+                        media_file_id = id,
+                        path = %path.display(),
+                        "Restored missing cover file for existing MediaFile"
+                    );
+                }
+                Err(err) => {
+                    tracing::warn!(
+                        media_file_id = id,
+                        path = %path.display(),
+                        error = %err,
+                        "Failed to restore missing cover file for existing MediaFile; creating a new cover file"
+                    );
+                }
+            }
+        }
+        if is_inside_storage && path.exists() {
             if let Err(err) = crate::agent::cover_variants::ensure_cover_variants(&path).await {
                 tracing::warn!(media_file_id = id, error = %err, "Failed to generate cover variants");
             }
-        }
             return Ok(id);
         }
+    }
 
     let ext = extension_for_mime(&cover.mime_type);
     let filename = format!("cover.{ext}");
@@ -357,7 +375,9 @@ pub async fn save_cover_to_storage(
     let artist_dir = sanitize_dir_name(artist_name);
     let album_dir = sanitize_dir_name(release_title);
 
-    let dest_dir = Path::new(storage_dir).join(&artist_dir).join(&album_dir);
+    let dest_dir = crate::media_paths::resolve_config_path_buf(storage_dir)
+        .join(&artist_dir)
+        .join(&album_dir);
     tokio::fs::create_dir_all(&dest_dir).await?;
 
     let dest_path = dest_dir.join(&filename);
@@ -365,7 +385,13 @@ pub async fn save_cover_to_storage(
     // Write image data
     tokio::fs::write(&dest_path, &cover.data).await?;
 
-    let relative_path = dest_path.to_string_lossy().to_string();
+    let relative_path = crate::media_paths::media_file_path_for_storage(storage_dir, &dest_path)
+        .ok_or_else(|| {
+            anyhow::anyhow!(
+                "cover destination is outside agent_storage_dir: {}",
+                dest_path.display()
+            )
+        })?;
     let file_size = cover.data.len() as i64;
 
     let media_file = crate::music::MediaFile::create(

src/config.rs

@@ -329,8 +329,8 @@ impl_env_overrides!(
 
 impl AppConfig {
     fn normalize_host_paths(&mut self) {
-        self.agent_inbox_dir = normalize_host_path(&self.agent_inbox_dir);
-        self.agent_storage_dir = normalize_host_path(&self.agent_storage_dir);
+        self.agent_inbox_dir = crate::media_paths::resolve_config_path(&self.agent_inbox_dir);
+        self.agent_storage_dir = crate::media_paths::resolve_config_path(&self.agent_storage_dir);
     }
 
     /// Build config: start from defaults, then overlay env vars.
@@ -413,47 +413,16 @@ impl AppConfig {
     }
 }
 
-fn normalize_host_path(value: &str) -> String {
-    let trimmed = value.trim();
-    if trimmed.is_empty() {
-        return String::new();
-    }
-
-    normalize_windows_user_path(trimmed).unwrap_or_else(|| trimmed.to_owned())
-}
-
-#[cfg(not(windows))]
-fn normalize_windows_user_path(value: &str) -> Option<String> {
-    let normalized = value.replace('\\', "/");
-    let mut parts = normalized.split('/').filter(|part| !part.is_empty());
-    let drive = parts.next()?;
-    if drive.len() != 2 || !drive.ends_with(':') {
-        return None;
-    }
-    if !parts.next()?.eq_ignore_ascii_case("Users") {
-        return None;
-    }
-    let user = parts.next()?;
-    if user.is_empty() {
-        return None;
-    }
-
-    let mut out = format!("/Users/{user}");
-    for part in parts {
-        out.push('/');
-        out.push_str(part);
-    }
-    Some(out)
-}
-
-#[cfg(windows)]
-fn normalize_windows_user_path(_value: &str) -> Option<String> {
-    None
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::sync::{Mutex, MutexGuard};
+
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    fn lock_env() -> MutexGuard<'static, ()> {
+        ENV_LOCK.lock().unwrap_or_else(|err| err.into_inner())
+    }
 
     #[test]
     fn defaults_are_sane() {
@@ -462,25 +431,29 @@ mod tests {
         assert_eq!(cfg.log_level, "info");
     }
 
-    #[cfg(not(windows))]
     #[test]
-    fn normalizes_windows_user_path_on_unix() {
+    fn resolves_relative_media_paths_from_working_dir() {
+        let expected = std::env::current_dir()
+            .unwrap()
+            .join("media")
+            .join("uploads")
+            .to_string_lossy()
+            .to_string();
         assert_eq!(
-            normalize_host_path(r"C:\Users\ab\repos\furumusic\media\uploads"),
-            "/Users/ab/repos/furumusic/media/uploads"
+            crate::media_paths::resolve_config_path("media/uploads"),
+            expected
         );
     }
 
-    #[cfg(not(windows))]
     #[test]
-    fn leaves_unix_path_unchanged() {
+    fn keeps_absolute_windows_media_paths() {
         assert_eq!(
-            normalize_host_path("/Users/ab/repos/furumusic/media/uploads"),
-            "/Users/ab/repos/furumusic/media/uploads"
+            crate::media_paths::resolve_config_path(r"C:\Users\ab\repos\furumusic\media\uploads"),
+            "C:/Users/ab/repos/furumusic/media/uploads"
         );
     }
 
-    // SAFETY: tests run with --test-threads=1 so no concurrent env access.
+    // SAFETY: environment-mutating tests take ENV_LOCK before changing vars.
     unsafe fn set(k: &str, v: &str) {
         unsafe { std::env::set_var(k, v) };
     }
@@ -490,6 +463,7 @@ mod tests {
 
     #[test]
     fn env_override_string_field() {
+        let _guard = lock_env();
         unsafe {
             set("FURU_OIDC_ISSUER", "https://example.com");
         }
@@ -502,6 +476,7 @@ mod tests {
 
     #[test]
     fn env_override_bool_field() {
+        let _guard = lock_env();
         unsafe {
             set("FURU_AUTH_SSO_ENABLED", "true");
         }
@@ -514,6 +489,7 @@ mod tests {
 
     #[test]
     fn source_tracking_env() {
+        let _guard = lock_env();
         unsafe {
             set("FURU_OIDC_ISSUER", "https://tracked.example.com");
         }

src/i18n/phrases.rs

@@ -296,6 +296,8 @@ translations! {
     player_likes_playlist:   "Likes"                           , "Лайки";
     player_listened:         "listened"                        , "прослушано";
     player_search_placeholder: "Search artists, releases, tracks..." , "Поиск артистов, релизов, треков...";
+    player_connection_lost: "Server connection lost"             , "Нет соединения с сервером";
+    player_connection_lost_detail: "Player cannot reach the server. Retrying..." , "Плеер не может связаться с сервером. Повторяю...";
     player_no_results:       "No results found"                , "Ничего не найдено";
     player_new_playlist:     "New Playlist"                    , "Новый плейлист";
     player_rename_playlist:  "Rename Playlist"                 , "Переименовать плейлист";
@@ -336,6 +338,10 @@ translations! {
     player_lastfm_connected: "Connected as {user}"             , "Подключён: {user}";
     player_lastfm_reconnect: "Reconnect Last.fm"               , "Переподключить Last.fm";
     player_lastfm_not_configured: "Last.fm is not configured"  , "Last.fm не настроен";
+    player_lastfm_status_connect: "connect account"            , "подключить аккаунт";
+    player_lastfm_status_connected: "connected"                , "подключён";
+    player_lastfm_status_reconnect: "reconnect account"        , "переподключить аккаунт";
+    player_lastfm_status_not_configured: "not configured"      , "не настроен";
     player_lastfm_disconnect_confirm: "Disconnect Last.fm account {user}?" , "Отвязать аккаунт Last.fm {user}?";
     player_lastfm_connect_failed: "Could not open Last.fm connection" , "Не удалось открыть подключение Last.fm";
     player_lastfm_disconnect_failed: "Could not disconnect Last.fm" , "Не удалось отвязать Last.fm";

src/jobs/artwork_backfill.rs

@@ -1,7 +1,10 @@
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 
 use reqwest::Client;
-use serde::Deserialize;
+use serde::{
+    Deserialize,
+    de::{self, DeserializeOwned},
+};
 
 use crate::agent::cover_art::{self, CoverImage, CoverSource};
 use crate::agent::cover_variants;
@@ -26,6 +29,13 @@ struct ArtistCandidate {
     name: String,
 }
 
+#[derive(Debug, sqlx::FromRow)]
+struct ArtworkRefCandidate {
+    entity_id: i64,
+    media_file_id: i64,
+    file_path: Option<String>,
+}
+
 #[derive(Debug, Deserialize)]
 struct LastfmAlbumResponse {
     album: Option<LastfmImageContainer>,
@@ -42,30 +52,20 @@ struct LastfmArtistResponse {
 
 #[derive(Debug, Deserialize)]
 struct LastfmTopAlbumsResponse {
-    topalbums: Option<LastfmTopAlbums>,
+    topalbums: Option<LastfmTopAlbumsContainer>,
     error: Option<i32>,
     message: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]
-struct LastfmTopAlbums {
-    album: Option<OneOrMany<LastfmImageContainer>>,
+struct LastfmTopAlbumsContainer {
+    #[serde(default, deserialize_with = "deserialize_one_or_many")]
+    album: Vec<LastfmTopAlbum>,
 }
 
 #[derive(Debug, Deserialize)]
-#[serde(untagged)]
-enum OneOrMany<T> {
-    One(T),
-    Many(Vec<T>),
-}
-
-impl<T> OneOrMany<T> {
-    fn into_vec(self) -> Vec<T> {
-        match self {
-            Self::One(value) => vec![value],
-            Self::Many(values) => values,
-        }
-    }
+struct LastfmTopAlbum {
+    image: Option<Vec<LastfmImage>>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -82,12 +82,16 @@ struct LastfmImage {
 
 #[derive(Default)]
 struct ArtworkStats {
+    broken_release_refs_cleared: u64,
+    broken_track_refs_cleared: u64,
+    broken_artist_refs_cleared: u64,
     release_local_assigned: u64,
     release_lastfm_assigned: u64,
     release_lastfm_not_found: u64,
     release_skipped_no_audio: u64,
     artist_lastfm_assigned: u64,
     artist_lastfm_not_found: u64,
+    artist_album_fallback_assigned: u64,
     variants_created: usize,
     variants_unchanged: usize,
     variants_missing_original: usize,
@@ -125,6 +129,17 @@ impl Job for ArtworkBackfillJob {
             .build()?;
         let mut stats = ArtworkStats::default();
 
+        let normalized_paths =
+            crate::media_paths::normalize_media_file_paths(&ctx.pool, storage_dir).await?;
+        if normalized_paths > 0 {
+            log.info(&format!(
+                "Media path normalization pass: rewrote {normalized_paths} media file path(s) to relative storage paths"
+            ));
+        } else {
+            log.info("Media path normalization pass: all media file paths are already relative");
+        }
+
+        repair_missing_artwork_refs(ctx, log, storage_dir, &mut stats).await?;
         backfill_release_local(ctx, log, storage_dir, &mut stats).await?;
 
         let api_key = ctx.config.lastfm_api_key.trim();
@@ -135,16 +150,21 @@ impl Job for ArtworkBackfillJob {
             backfill_artist_lastfm(ctx, log, storage_dir, api_key, &client, &mut stats).await?;
         }
 
+        backfill_artist_album_fallbacks(ctx, log, &mut stats).await?;
         repair_cover_variants(ctx, log, storage_dir, &mut stats).await?;
 
         log.info(&format!(
-            "Artwork backfill complete: release_local_assigned={}, release_lastfm_assigned={}, release_lastfm_not_found={}, release_skipped_no_audio={}, artist_lastfm_assigned={}, artist_lastfm_not_found={}, variants_created={}, variants_unchanged={}, variants_missing_original={}, failed={}",
+            "Artwork backfill complete: broken_release_refs_cleared={}, broken_track_refs_cleared={}, broken_artist_refs_cleared={}, release_local_assigned={}, release_lastfm_assigned={}, release_lastfm_not_found={}, release_skipped_no_audio={}, artist_lastfm_assigned={}, artist_lastfm_not_found={}, artist_album_fallback_assigned={}, variants_created={}, variants_unchanged={}, variants_missing_original={}, failed={}",
+            stats.broken_release_refs_cleared,
+            stats.broken_track_refs_cleared,
+            stats.broken_artist_refs_cleared,
             stats.release_local_assigned,
             stats.release_lastfm_assigned,
             stats.release_lastfm_not_found,
             stats.release_skipped_no_audio,
             stats.artist_lastfm_assigned,
             stats.artist_lastfm_not_found,
+            stats.artist_album_fallback_assigned,
             stats.variants_created,
             stats.variants_unchanged,
             stats.variants_missing_original,
@@ -154,6 +174,188 @@ impl Job for ArtworkBackfillJob {
     }
 }
 
+async fn repair_missing_artwork_refs(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    storage_dir: &str,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    repair_missing_release_cover_refs(ctx, log, storage_dir, stats).await?;
+    repair_missing_track_cover_refs(ctx, log, storage_dir, stats).await?;
+    repair_missing_artist_image_refs(ctx, log, storage_dir, stats).await?;
+    Ok(())
+}
+
+async fn repair_missing_release_cover_refs(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    storage_dir: &str,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    let rows = sqlx::query_as::<_, ArtworkRefCandidate>(
+        r#"SELECT r.id AS entity_id,
+                  r.cover_file_id AS media_file_id,
+                  mf.file_path::text AS file_path
+             FROM furumusic__release r
+             LEFT JOIN furumusic__media_file mf ON mf.id = r.cover_file_id
+            WHERE r.cover_file_id IS NOT NULL
+              AND r.is_hidden = false
+            ORDER BY r.id"#,
+    )
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    for row in rows {
+        if artwork_ref_exists(storage_dir, row.file_path.as_deref()) {
+            continue;
+        }
+
+        let result = sqlx::query(
+            r#"UPDATE furumusic__release
+                  SET cover_file_id = NULL,
+                      updated_at = $3
+                WHERE id = $1
+                  AND cover_file_id = $2"#,
+        )
+        .bind(row.entity_id)
+        .bind(row.media_file_id)
+        .bind(now_iso())
+        .execute(&ctx.pool)
+        .await?;
+
+        if result.rows_affected() > 0 {
+            reset_lookup_state(&ctx.pool, "release", row.entity_id).await?;
+            stats.broken_release_refs_cleared += 1;
+            log.warn(&format!(
+                "Release {}: cleared missing cover reference media_file_id={}{}",
+                row.entity_id,
+                row.media_file_id,
+                artwork_ref_location(storage_dir, row.file_path.as_deref())
+            ));
+        }
+    }
+
+    Ok(())
+}
+
+async fn repair_missing_track_cover_refs(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    storage_dir: &str,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    let rows = sqlx::query_as::<_, ArtworkRefCandidate>(
+        r#"SELECT t.id AS entity_id,
+                  t.cover_file_id AS media_file_id,
+                  mf.file_path::text AS file_path
+             FROM furumusic__track t
+             LEFT JOIN furumusic__media_file mf ON mf.id = t.cover_file_id
+            WHERE t.cover_file_id IS NOT NULL
+              AND t.is_hidden = false
+            ORDER BY t.id"#,
+    )
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    for row in rows {
+        if artwork_ref_exists(storage_dir, row.file_path.as_deref()) {
+            continue;
+        }
+
+        let result = sqlx::query(
+            r#"UPDATE furumusic__track
+                  SET cover_file_id = NULL,
+                      updated_at = $3
+                WHERE id = $1
+                  AND cover_file_id = $2"#,
+        )
+        .bind(row.entity_id)
+        .bind(row.media_file_id)
+        .bind(now_iso())
+        .execute(&ctx.pool)
+        .await?;
+
+        if result.rows_affected() > 0 {
+            stats.broken_track_refs_cleared += 1;
+            log.warn(&format!(
+                "Track {}: cleared missing cover reference media_file_id={}{}",
+                row.entity_id,
+                row.media_file_id,
+                artwork_ref_location(storage_dir, row.file_path.as_deref())
+            ));
+        }
+    }
+
+    Ok(())
+}
+
+async fn repair_missing_artist_image_refs(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    storage_dir: &str,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    let rows = sqlx::query_as::<_, ArtworkRefCandidate>(
+        r#"SELECT a.id AS entity_id,
+                  a.image_file_id AS media_file_id,
+                  mf.file_path::text AS file_path
+             FROM furumusic__artist a
+             LEFT JOIN furumusic__media_file mf ON mf.id = a.image_file_id
+            WHERE a.image_file_id IS NOT NULL
+              AND a.is_hidden = false
+            ORDER BY a.id"#,
+    )
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    for row in rows {
+        if artwork_ref_exists(storage_dir, row.file_path.as_deref()) {
+            continue;
+        }
+
+        let result = sqlx::query(
+            r#"UPDATE furumusic__artist
+                  SET image_file_id = NULL,
+                      updated_at = $3
+                WHERE id = $1
+                  AND image_file_id = $2"#,
+        )
+        .bind(row.entity_id)
+        .bind(row.media_file_id)
+        .bind(now_iso())
+        .execute(&ctx.pool)
+        .await?;
+
+        if result.rows_affected() > 0 {
+            reset_lookup_state(&ctx.pool, "artist", row.entity_id).await?;
+            stats.broken_artist_refs_cleared += 1;
+            log.warn(&format!(
+                "Artist {}: cleared missing image reference media_file_id={}{}",
+                row.entity_id,
+                row.media_file_id,
+                artwork_ref_location(storage_dir, row.file_path.as_deref())
+            ));
+        }
+    }
+
+    Ok(())
+}
+
+fn artwork_ref_exists(storage_dir: &str, file_path: Option<&str>) -> bool {
+    file_path
+        .map(|value| crate::media_paths::resolve_media_file_path(storage_dir, value).exists())
+        .unwrap_or(false)
+}
+
+fn artwork_ref_location(storage_dir: &str, file_path: Option<&str>) -> String {
+    file_path
+        .map(|value| {
+            let path = crate::media_paths::resolve_media_file_path(storage_dir, value);
+            format!(" at {}", path.display())
+        })
+        .unwrap_or_else(|| " with missing media_file row".to_string())
+}
+
 async fn backfill_release_local(
     ctx: &JobContext,
     log: &mut JobLog,
@@ -221,7 +423,7 @@ async fn backfill_release_local(
 
         let audio_files: Vec<PathBuf> = audio_paths
             .iter()
-            .map(|path| resolve_media_path(storage_dir, path))
+            .map(|path| crate::media_paths::resolve_media_file_path(storage_dir, path))
             .collect();
         let Some(folder) = audio_files.first().and_then(|path| path.parent()) else {
             stats.failed += 1;
@@ -491,11 +693,15 @@ async fn backfill_artist_lastfm(
     let artists = sqlx::query_as::<_, ArtistCandidate>(
         r#"SELECT a.id, a.name::text AS name
              FROM furumusic__artist a
+             LEFT JOIN furumusic__media_file mf ON mf.id = a.image_file_id
              LEFT JOIN furumusic__artwork_lookup_state s
                ON s.entity_kind = 'artist'
               AND s.entity_id = a.id
               AND s.source = 'lastfm'
-            WHERE a.image_file_id IS NULL
+            WHERE (
+                    a.image_file_id IS NULL
+                 OR mf.file_path NOT LIKE '%/__artist_image__/%'
+                  )
               AND a.is_hidden = false
               AND (
                     s.entity_id IS NULL
@@ -548,7 +754,15 @@ async fn backfill_artist_lastfm(
                                       SET image_file_id = $1,
                                           updated_at = $3
                                     WHERE id = $2
-                                      AND image_file_id IS NULL"#,
+                                      AND (
+                                            image_file_id IS NULL
+                                         OR EXISTS (
+                                                SELECT 1
+                                                  FROM furumusic__media_file mf
+                                                 WHERE mf.id = furumusic__artist.image_file_id
+                                                   AND mf.file_path NOT LIKE '%/__artist_image__/%'
+                                            )
+                                          )"#,
                         )
                         .bind(image_file_id)
                         .bind(artist.id)
@@ -605,13 +819,35 @@ async fn backfill_artist_lastfm(
                 }
             },
             Ok(None) => {
-                stats.artist_lastfm_not_found += 1;
                 record_lookup_state(&ctx.pool, "artist", artist.id, "not_found", None, None)
                     .await?;
                 log.info(&format!(
                     "Artist {} \"{}\": Last.fm did not return artwork",
                     artist.id, artist.name
                 ));
+                stats.artist_lastfm_not_found += 1;
+                match assign_artist_album_fallback(ctx, artist.id).await {
+                    Ok(Some(media_file_id)) => {
+                        stats.artist_album_fallback_assigned += 1;
+                        log.info(&format!(
+                            "Artist {} \"{}\": assigned random local album cover (media_file_id={media_file_id})",
+                            artist.id, artist.name
+                        ));
+                    }
+                    Ok(None) => {
+                        log.info(&format!(
+                            "Artist {} \"{}\": no local album cover available for fallback",
+                            artist.id, artist.name
+                        ));
+                    }
+                    Err(err) => {
+                        stats.failed += 1;
+                        log.warn(&format!(
+                            "Artist {} \"{}\": failed to assign album fallback artwork: {err}",
+                            artist.id, artist.name
+                        ));
+                    }
+                }
             }
             Err(err) if err.to_string().contains("rate limit") => {
                 stats.failed += 1;
@@ -653,6 +889,70 @@ async fn backfill_artist_lastfm(
     Ok(())
 }
 
+async fn backfill_artist_album_fallbacks(
+    ctx: &JobContext,
+    log: &mut JobLog,
+    stats: &mut ArtworkStats,
+) -> anyhow::Result<()> {
+    let artists = sqlx::query_as::<_, ArtistCandidate>(
+        r#"SELECT a.id, a.name::text AS name
+             FROM furumusic__artist a
+            WHERE a.image_file_id IS NULL
+              AND a.is_hidden = false
+              AND EXISTS (
+                    SELECT 1
+                      FROM furumusic__release_artist ra
+                      JOIN furumusic__release r ON r.id = ra.release_id
+                     WHERE ra.artist_id = a.id
+                       AND r.cover_file_id IS NOT NULL
+                       AND r.is_hidden = false
+                    UNION
+                    SELECT 1
+                      FROM furumusic__track_artist ta
+                      JOIN furumusic__track t ON t.id = ta.track_id
+                      JOIN furumusic__release r ON r.id = t.release_id
+                     WHERE ta.artist_id = a.id
+                       AND r.cover_file_id IS NOT NULL
+                       AND r.is_hidden = false
+                  )
+            ORDER BY a.id"#,
+    )
+    .fetch_all(&ctx.pool)
+    .await?;
+
+    if artists.is_empty() {
+        log.info("Artist album fallback pass: no artists need local album fallback");
+        return Ok(());
+    }
+
+    log.info(&format!(
+        "Artist album fallback pass: checking {} artist(s) without images",
+        artists.len()
+    ));
+
+    for artist in artists {
+        match assign_artist_album_fallback(ctx, artist.id).await {
+            Ok(Some(media_file_id)) => {
+                stats.artist_album_fallback_assigned += 1;
+                log.info(&format!(
+                    "Artist {} \"{}\": assigned local album cover fallback (media_file_id={media_file_id})",
+                    artist.id, artist.name
+                ));
+            }
+            Ok(None) => {}
+            Err(err) => {
+                stats.failed += 1;
+                log.warn(&format!(
+                    "Artist {} \"{}\": failed to assign album fallback artwork: {err}",
+                    artist.id, artist.name
+                ));
+            }
+        }
+    }
+
+    Ok(())
+}
+
 async fn repair_cover_variants(
     ctx: &JobContext,
     log: &mut JobLog,
@@ -660,22 +960,30 @@ async fn repair_cover_variants(
     stats: &mut ArtworkStats,
 ) -> anyhow::Result<()> {
     let rows: Vec<(i64, String)> = sqlx::query_as(
-        "SELECT id, file_path FROM furumusic__media_file WHERE file_type = 'cover_art' ORDER BY id",
+        r#"SELECT DISTINCT mf.id, mf.file_path::text
+             FROM furumusic__media_file mf
+            WHERE mf.file_type = 'cover_art'
+              AND (
+                    EXISTS (SELECT 1 FROM furumusic__release r WHERE r.cover_file_id = mf.id)
+                 OR EXISTS (SELECT 1 FROM furumusic__track t WHERE t.cover_file_id = mf.id)
+                 OR EXISTS (SELECT 1 FROM furumusic__artist a WHERE a.image_file_id = mf.id)
+                  )
+            ORDER BY mf.id"#,
     )
     .fetch_all(&ctx.pool)
     .await?;
 
     if rows.is_empty() {
-        log.info("Cover variant pass: no cover art media files found");
+        log.info("Cover variant pass: no referenced cover art media files found");
         return Ok(());
     }
     log.info(&format!(
-        "Cover variant pass: checking {} cover art media file(s)",
+        "Cover variant pass: checking {} referenced cover art media file(s)",
         rows.len()
     ));
 
     for (media_file_id, file_path) in rows {
-        let path = resolve_media_path(storage_dir, &file_path);
+        let path = crate::media_paths::resolve_media_file_path(storage_dir, &file_path);
         if !path.exists() {
             stats.variants_missing_original += 1;
             log.warn(&format!(
@@ -705,6 +1013,59 @@ async fn repair_cover_variants(
     Ok(())
 }
 
+async fn assign_artist_album_fallback(
+    ctx: &JobContext,
+    artist_id: i64,
+) -> anyhow::Result<Option<i64>> {
+    let media_file_id: Option<i64> = sqlx::query_scalar(
+        r#"SELECT media_file_id
+             FROM (
+                    SELECT DISTINCT r.cover_file_id AS media_file_id
+                      FROM furumusic__release r
+                      JOIN furumusic__release_artist ra ON ra.release_id = r.id
+                     WHERE ra.artist_id = $1
+                       AND r.cover_file_id IS NOT NULL
+                       AND r.is_hidden = false
+                    UNION
+                    SELECT DISTINCT r.cover_file_id AS media_file_id
+                      FROM furumusic__release r
+                      JOIN furumusic__track t ON t.release_id = r.id
+                      JOIN furumusic__track_artist ta ON ta.track_id = t.id
+                     WHERE ta.artist_id = $1
+                       AND r.cover_file_id IS NOT NULL
+                       AND r.is_hidden = false
+                  ) covers
+            ORDER BY random()
+            LIMIT 1"#,
+    )
+    .bind(artist_id)
+    .fetch_optional(&ctx.pool)
+    .await?;
+
+    let Some(media_file_id) = media_file_id else {
+        return Ok(None);
+    };
+
+    let result = sqlx::query(
+        r#"UPDATE furumusic__artist
+              SET image_file_id = $1,
+                  updated_at = $3
+            WHERE id = $2
+              AND image_file_id IS NULL"#,
+    )
+    .bind(media_file_id)
+    .bind(artist_id)
+    .bind(now_iso())
+    .execute(&ctx.pool)
+    .await?;
+
+    if result.rows_affected() == 0 {
+        Ok(None)
+    } else {
+        Ok(Some(media_file_id))
+    }
+}
+
 async fn fetch_lastfm_album_image(
     client: &Client,
     api_key: &str,
@@ -746,6 +1107,18 @@ async fn fetch_lastfm_artist_image(
     client: &Client,
     api_key: &str,
     artist: &str,
+) -> anyhow::Result<Option<String>> {
+    if let Some(image_url) = fetch_lastfm_artist_info_image(client, api_key, artist).await? {
+        return Ok(Some(image_url));
+    }
+
+    fetch_lastfm_artist_top_album_image(client, api_key, artist).await
+}
+
+async fn fetch_lastfm_artist_info_image(
+    client: &Client,
+    api_key: &str,
+    artist: &str,
 ) -> anyhow::Result<Option<String>> {
     let response = client
         .get("https://ws.audioscrobbler.com/2.0/")
@@ -772,14 +1145,9 @@ async fn fetch_lastfm_artist_image(
             parsed.message.unwrap_or_default()
         );
     }
-    if let Some(url) = parsed
+    Ok(parsed
         .artist
-        .and_then(|artist| choose_best_image(artist.image))
-    {
-        return Ok(Some(url));
-    }
-
-    fetch_lastfm_artist_top_album_image(client, api_key, artist).await
+        .and_then(|artist| choose_best_image(artist.image)))
 }
 
 async fn fetch_lastfm_artist_top_album_image(
@@ -816,8 +1184,7 @@ async fn fetch_lastfm_artist_top_album_image(
 
     let albums = parsed
         .topalbums
-        .and_then(|topalbums| topalbums.album)
-        .map(OneOrMany::into_vec)
+        .map(|topalbums| topalbums.album)
         .unwrap_or_default();
     Ok(albums
         .into_iter()
@@ -825,6 +1192,28 @@ async fn fetch_lastfm_artist_top_album_image(
         .next())
 }
 
+fn deserialize_one_or_many<'de, D, T>(deserializer: D) -> Result<Vec<T>, D::Error>
+where
+    D: de::Deserializer<'de>,
+    T: DeserializeOwned,
+{
+    let value = Option::<serde_json::Value>::deserialize(deserializer)?;
+    let Some(value) = value else {
+        return Ok(Vec::new());
+    };
+
+    match value {
+        serde_json::Value::Array(values) => values
+            .into_iter()
+            .map(|value| serde_json::from_value(value).map_err(de::Error::custom))
+            .collect(),
+        serde_json::Value::Object(_) => serde_json::from_value(value)
+            .map(|item| vec![item])
+            .map_err(de::Error::custom),
+        _ => Ok(Vec::new()),
+    }
+}
+
 fn choose_best_image(images: Option<Vec<LastfmImage>>) -> Option<String> {
     let mut images = images.unwrap_or_default();
     images.sort_by_key(|image| image_size_rank(&image.size));
@@ -935,6 +1324,24 @@ async fn record_lookup_state(
     Ok(())
 }
 
+async fn reset_lookup_state(
+    pool: &sqlx::PgPool,
+    entity_kind: &str,
+    entity_id: i64,
+) -> anyhow::Result<()> {
+    sqlx::query(
+        r#"DELETE FROM furumusic__artwork_lookup_state
+            WHERE entity_kind = $1
+              AND entity_id = $2
+              AND source = 'lastfm'"#,
+    )
+    .bind(entity_kind)
+    .bind(entity_id)
+    .execute(pool)
+    .await?;
+    Ok(())
+}
+
 fn cover_source_description(source: &CoverSource) -> String {
     match source {
         CoverSource::FolderFile(path) => format!("folder: {}", path.display()),
@@ -943,15 +1350,6 @@ fn cover_source_description(source: &CoverSource) -> String {
     }
 }
 
-fn resolve_media_path(storage_dir: &str, file_path: &str) -> PathBuf {
-    let path = PathBuf::from(file_path);
-    if path.is_absolute() {
-        path
-    } else {
-        Path::new(storage_dir).join(path)
-    }
-}
-
 fn cutoff_iso(days: i64) -> String {
     (chrono::Utc::now() - chrono::Duration::days(days))
         .format("%Y-%m-%dT%H:%M:%SZ")

src/jobs/inbox_discover.rs

@@ -75,7 +75,9 @@ impl Job for InboxDiscoverJob {
 
         for (_folder, files) in &groups {
             for file_path in files {
-                let input_path_str = file_path.to_string_lossy().to_string();
+                let input_path_str =
+                    crate::media_paths::path_for_root(&config.agent_inbox_dir, file_path)
+                        .unwrap_or_else(|| file_path.to_string_lossy().to_string());
 
                 // Skip if a PendingReview already exists for this path
                 match PendingReview::exists_for_path(&ctx.db, &input_path_str).await {

src/jobs/inbox_process.rs

@@ -225,14 +225,13 @@ fn group_reviews_by_folder(
     reviews: &[PendingReview],
     inbox_dir: &str,
 ) -> Vec<(String, Vec<PendingReview>)> {
-    let inbox = Path::new(inbox_dir);
     let mut map: HashMap<String, Vec<PendingReview>> = HashMap::new();
 
     for r in reviews {
-        let path = Path::new(r.input_path_str());
-        let folder = path.parent().unwrap_or(path);
-        let rel = folder.strip_prefix(inbox).unwrap_or(folder);
-        let key = rel.to_string_lossy().to_string();
+        let path = crate::media_paths::resolve_path_from_root(inbox_dir, r.input_path_str());
+        let folder = path.parent().unwrap_or(path.as_path());
+        let key = crate::media_paths::path_for_root(inbox_dir, folder)
+            .unwrap_or_else(|| folder.to_string_lossy().to_string());
         map.entry(key).or_default().push(r.clone());
     }
 
@@ -287,8 +286,9 @@ async fn process_folder_batch(
     let mut failed_reviews: Vec<PendingReview> = Vec::new();
 
     for mut review in reviews {
-        let input_path_str = review.input_path_str().to_owned();
-        let file_path = Path::new(&input_path_str);
+        let stored_input_path = review.input_path_str().to_owned();
+        let file_path =
+            crate::media_paths::resolve_path_from_root(&config.agent_inbox_dir, &stored_input_path);
         let filename = file_path
             .file_name()
             .and_then(|n| n.to_str())
@@ -336,7 +336,7 @@ async fn process_folder_batch(
             };
 
         // Parse path hints
-        let relative = file_path.strip_prefix(inbox_path).unwrap_or(file_path);
+        let relative = file_path.strip_prefix(inbox_path).unwrap_or(&file_path);
         let uploader = crate::jobs::uploader_from_relative_path(pool, relative).await;
         let hinted_relative = crate::jobs::strip_user_upload_prefix(relative);
         let hints = crate::agent::path_hints::parse(&hinted_relative);
@@ -471,8 +471,11 @@ async fn process_folder_batch(
 
     // Build folder context from the first file's folder
     let folder_ctx = {
-        let first_path = Path::new(prepared[0].review.input_path_str());
-        let folder = first_path.parent().unwrap_or(first_path);
+        let first_path = crate::media_paths::resolve_path_from_root(
+            &config.agent_inbox_dir,
+            prepared[0].review.input_path_str(),
+        );
+        let folder = first_path.parent().unwrap_or(first_path.as_path());
         let mut folder_files: Vec<String> = std::fs::read_dir(folder)
             .ok()
             .map(|rd| {
@@ -631,7 +634,11 @@ async fn process_folder_batch(
         p.review.result_json = Some(result_json);
         let _ = p.review.save(db).await;
 
-        let input_path_str = p.review.input_path_str().to_owned();
+        let input_path = crate::media_paths::resolve_path_from_root(
+            &config.agent_inbox_dir,
+            p.review.input_path_str(),
+        );
+        let input_path_str = input_path.to_string_lossy().to_string();
 
         if confidence >= config.agent_confidence_threshold {
             match finalize_approved(
@@ -787,10 +794,10 @@ pub async fn finalize_approved(
         format!("{}.{}", sanitize_filename(track_title), ext)
     };
 
-    let storage_dir = Path::new(storage_dir_str);
+    let storage_dir = crate::media_paths::resolve_config_path_buf(storage_dir_str);
     let storage_path = if source_path.exists() {
         match mover::move_to_storage(
-            storage_dir,
+            &storage_dir,
             artist_name,
             release_title,
             &dest_filename,
@@ -798,16 +805,29 @@ pub async fn finalize_approved(
         )
         .await?
         {
-            mover::MoveOutcome::Moved(p) => p.to_string_lossy().to_string(),
-            mover::MoveOutcome::Merged(p) => p.to_string_lossy().to_string(),
+            mover::MoveOutcome::Moved(p) | mover::MoveOutcome::Merged(p) => {
+                crate::media_paths::media_file_path_for_storage(storage_dir_str, &p).ok_or_else(
+                    || {
+                        anyhow::anyhow!(
+                            "storage destination is outside agent_storage_dir: {}",
+                            p.display()
+                        )
+                    },
+                )?
+            }
         }
     } else {
-        storage_dir
+        let expected_path = storage_dir
             .join(sanitize_filename(artist_name))
             .join(sanitize_filename(release_title))
-            .join(&dest_filename)
-            .to_string_lossy()
-            .to_string()
+            .join(&dest_filename);
+        crate::media_paths::media_file_path_for_storage(storage_dir_str, &expected_path)
+            .ok_or_else(|| {
+                anyhow::anyhow!(
+                    "storage destination is outside agent_storage_dir: {}",
+                    expected_path.display()
+                )
+            })?
     };
 
     let media_file = MediaFile::create(

src/jobs/metadata_backfill.rs

@@ -1,5 +1,3 @@
-use std::path::{Path, PathBuf};
-
 use crate::scheduler::{Job, JobContext, JobLog};
 
 #[derive(Debug, Clone, Copy)]
@@ -104,11 +102,15 @@ pub async fn run_with_options(
 
     for row in rows {
         scanned += 1;
-        let Some(path) = resolve_media_path(&row.file_path, &ctx.config.agent_storage_dir) else {
+        let path = crate::media_paths::resolve_media_file_path(
+            &ctx.config.agent_storage_dir,
+            &row.file_path,
+        );
+        if !path.exists() {
             missing += 1;
             log.warn(&format!("missing file: {}", row.file_path));
             continue;
-        };
+        }
 
         let extract_path = path.clone();
         let raw_meta = match tokio::task::spawn_blocking(move || {
@@ -218,17 +220,3 @@ fn should_update<T>(current: Option<T>, overwrite: bool) -> bool {
 fn should_update_duration(current: Option<f64>, overwrite: bool) -> bool {
     overwrite || current.unwrap_or(0.0) <= 0.0
 }
-
-fn resolve_media_path(file_path: &str, storage_dir: &str) -> Option<PathBuf> {
-    let path = Path::new(file_path);
-    if path.exists() {
-        return Some(path.to_path_buf());
-    }
-    if path.is_relative() && !storage_dir.is_empty() {
-        let joined = Path::new(storage_dir).join(path);
-        if joined.exists() {
-            return Some(joined);
-        }
-    }
-    None
-}

src/main.rs

@@ -6,6 +6,7 @@ mod config;
 mod i18n;
 mod jobs;
 mod lastfm;
+mod media_paths;
 mod music;
 mod oidc;
 mod player;

src/media_paths.rs

@@ -0,0 +1,256 @@
+use std::path::{Component, Path, PathBuf};
+
+pub fn resolve_config_path(value: &str) -> String {
+    let path = resolve_config_path_buf(value);
+    if path.as_os_str().is_empty() {
+        String::new()
+    } else {
+        path.to_string_lossy().to_string()
+    }
+}
+
+pub fn resolve_config_path_buf(value: &str) -> PathBuf {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return PathBuf::new();
+    }
+
+    let normalized = normalize_slashes(trimmed);
+    if is_absolute_path(&normalized) {
+        PathBuf::from(normalized)
+    } else {
+        app_root().join(slash_path(&normalized))
+    }
+}
+
+pub fn resolve_media_file_path(storage_dir: &str, file_path: &str) -> PathBuf {
+    resolve_path_from_root(storage_dir, file_path)
+}
+
+pub fn media_file_path_for_storage(storage_dir: &str, path: &Path) -> Option<String> {
+    path_for_root(storage_dir, path)
+}
+
+pub fn resolve_path_from_root(root_dir: &str, stored_path: &str) -> PathBuf {
+    let normalized = normalize_slashes(stored_path.trim());
+    if is_absolute_path(&normalized) {
+        PathBuf::from(normalized)
+    } else {
+        resolve_config_path_buf(root_dir).join(slash_path(&normalized))
+    }
+}
+
+pub fn path_for_root(root_dir: &str, path: &Path) -> Option<String> {
+    let root = resolve_config_path_buf(root_dir);
+    let normalized = normalize_slashes(&path.to_string_lossy());
+    if is_absolute_path(&normalized) {
+        return strip_root_prefix(&root, &normalized);
+    }
+
+    relative_path_string(path)
+}
+
+pub async fn normalize_media_file_paths(
+    pool: &sqlx::PgPool,
+    storage_dir: &str,
+) -> anyhow::Result<u64> {
+    normalize_table_paths(pool, "furumusic__media_file", "file_path", storage_dir).await
+}
+
+pub async fn normalize_pending_review_paths(
+    pool: &sqlx::PgPool,
+    inbox_dir: &str,
+) -> anyhow::Result<u64> {
+    normalize_table_paths(pool, "furumusic__pending_review", "input_path", inbox_dir).await
+}
+
+async fn normalize_table_paths(
+    pool: &sqlx::PgPool,
+    table: &str,
+    column: &str,
+    root_dir: &str,
+) -> anyhow::Result<u64> {
+    let sql = format!("SELECT id, {column} FROM {table} WHERE {column} IS NOT NULL ORDER BY id");
+    let rows: Vec<(i64, String)> = sqlx::query_as(&sql).fetch_all(pool).await?;
+
+    let mut updated = 0;
+    for (id, stored_path) in rows {
+        let Some(normalized) = normalize_stored_path(root_dir, &stored_path) else {
+            continue;
+        };
+        if normalized == stored_path {
+            continue;
+        }
+
+        let sql = format!("UPDATE {table} SET {column} = $1 WHERE id = $2");
+        sqlx::query(&sql)
+            .bind(&normalized)
+            .bind(id)
+            .execute(pool)
+            .await?;
+        updated += 1;
+    }
+
+    Ok(updated)
+}
+
+fn normalize_stored_path(root_dir: &str, stored_path: &str) -> Option<String> {
+    let normalized = normalize_slashes(stored_path);
+    if normalized.is_empty() {
+        return None;
+    }
+
+    if is_absolute_path(&normalized) {
+        strip_root_prefix(&resolve_config_path_buf(root_dir), &normalized)
+    } else {
+        normalize_relative_path(&normalized)
+    }
+}
+
+fn app_root() -> PathBuf {
+    std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
+}
+
+fn normalize_slashes(value: &str) -> String {
+    value.trim().replace('\\', "/")
+}
+
+fn is_absolute_path(value: &str) -> bool {
+    value.starts_with('/') || Path::new(value).is_absolute() || looks_like_windows_absolute(value)
+}
+
+fn looks_like_windows_absolute(value: &str) -> bool {
+    let bytes = value.as_bytes();
+    bytes.len() >= 3 && bytes[1] == b':' && bytes[2] == b'/' && bytes[0].is_ascii_alphabetic()
+}
+
+fn slash_path(value: &str) -> PathBuf {
+    value
+        .split('/')
+        .filter(|part| !part.is_empty() && *part != ".")
+        .fold(PathBuf::new(), |mut path, part| {
+            path.push(part);
+            path
+        })
+}
+
+fn normalize_relative_path(value: &str) -> Option<String> {
+    let parts: Vec<&str> = value
+        .split('/')
+        .filter(|part| !part.is_empty() && *part != ".")
+        .collect();
+    if parts.is_empty() || parts.iter().any(|part| *part == "..") {
+        return None;
+    }
+    Some(parts.join("/"))
+}
+
+fn strip_root_prefix(root: &Path, normalized_path: &str) -> Option<String> {
+    let root_string = normalize_slashes(&root.to_string_lossy());
+    let root_trimmed = root_string.trim_end_matches('/');
+    let path_trimmed = normalized_path.trim();
+
+    let root_cmp = comparable_path(root_trimmed);
+    let path_cmp = comparable_path(path_trimmed);
+    if path_cmp == root_cmp {
+        return None;
+    }
+
+    let prefix = format!("{root_cmp}/");
+    if path_cmp.starts_with(&prefix) {
+        let tail = &path_trimmed[root_trimmed.len() + 1..];
+        return normalize_relative_path(tail);
+    }
+
+    None
+}
+
+fn comparable_path(value: &str) -> String {
+    let normalized = normalize_slashes(value).trim_end_matches('/').to_owned();
+    if cfg!(windows) || looks_like_windows_absolute(&normalized) {
+        normalized.to_ascii_lowercase()
+    } else {
+        normalized
+    }
+}
+
+fn relative_path_string(path: &Path) -> Option<String> {
+    let mut parts = Vec::new();
+    for component in path.components() {
+        match component {
+            Component::Normal(value) => parts.push(value.to_string_lossy().to_string()),
+            Component::CurDir => {}
+            _ => return None,
+        }
+    }
+    if parts.is_empty() {
+        None
+    } else {
+        Some(parts.join("/"))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn resolves_relative_config_path_from_app_root() {
+        let expected = app_root().join("media").join("library");
+        assert_eq!(resolve_config_path_buf("media/library"), expected);
+    }
+
+    #[test]
+    fn keeps_absolute_config_path() {
+        assert_eq!(resolve_config_path_buf("/media"), PathBuf::from("/media"));
+    }
+
+    #[test]
+    fn resolves_relative_media_file_under_storage_root() {
+        assert_eq!(
+            resolve_media_file_path("/media", "Buckethead/Pike/cover.jpg"),
+            PathBuf::from("/media")
+                .join("Buckethead")
+                .join("Pike")
+                .join("cover.jpg")
+        );
+    }
+
+    #[test]
+    fn keeps_absolute_media_file_path() {
+        assert_eq!(
+            resolve_media_file_path("/media", "/media/Buckethead/Pike/cover.jpg"),
+            PathBuf::from("/media/Buckethead/Pike/cover.jpg")
+        );
+    }
+
+    #[test]
+    fn stores_path_relative_to_storage_root() {
+        let storage = app_root().join("media").join("library");
+        let path = storage.join("Artist").join("Album").join("track.flac");
+        assert_eq!(
+            media_file_path_for_storage(&storage.to_string_lossy(), &path).as_deref(),
+            Some("Artist/Album/track.flac")
+        );
+    }
+
+    #[test]
+    fn stores_windows_path_relative_to_windows_storage_root() {
+        assert_eq!(
+            path_for_root(
+                r"C:\Users\ab\repos\furumusic\library",
+                Path::new(r"C:\Users\ab\repos\furumusic\library\Artist\Album\track.mp3"),
+            )
+            .as_deref(),
+            Some("Artist/Album/track.mp3")
+        );
+    }
+
+    #[test]
+    fn normalizes_relative_backslashes() {
+        assert_eq!(
+            normalize_stored_path("/media", r"Artist\Album\track.mp3").as_deref(),
+            Some("Artist/Album/track.mp3")
+        );
+    }
+}

src/player/dto.rs

@@ -137,6 +137,77 @@ pub(super) struct PlaybackStateDto {
     pub(super) volume: f64,
 }
 
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct DeviceHeartbeatRequest {
+    pub(super) device_id: String,
+    pub(super) user_agent: Option<String>,
+    pub(super) playback_state: Option<PlayerDevicePlaybackStateDto>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct DeviceSelectRequest {
+    pub(super) device_id: String,
+    pub(super) current_device_id: Option<String>,
+}
+
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(super) struct DeviceCommandRequest {
+    pub(super) target_device_id: Option<String>,
+    pub(super) command: String,
+    #[serde(default)]
+    pub(super) payload: serde_json::Value,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct PlayerDeviceDto {
+    pub(super) id: String,
+    pub(super) name: String,
+    pub(super) kind: String,
+    pub(super) is_current: bool,
+    pub(super) is_active: bool,
+    pub(super) last_seen_ms: i64,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct PlayerDeviceCommandDto {
+    pub(super) id: String,
+    pub(super) command: String,
+    pub(super) payload: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub(super) struct PlayerDevicePlaybackStateDto {
+    pub(super) track: Option<serde_json::Value>,
+    #[serde(default)]
+    pub(super) tracks: Vec<serde_json::Value>,
+    pub(super) index: i32,
+    pub(super) position_seconds: f64,
+    pub(super) duration_seconds: f64,
+    pub(super) paused: bool,
+    pub(super) shuffle: bool,
+    pub(super) repeat_mode: String,
+    pub(super) volume: f64,
+    #[serde(default)]
+    pub(super) updated_at_ms: i64,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct PlayerDevicesResponse {
+    pub(super) device_id: String,
+    pub(super) active_device_id: Option<String>,
+    pub(super) devices: Vec<PlayerDeviceDto>,
+    pub(super) playback_state: Option<PlayerDevicePlaybackStateDto>,
+}
+
+#[derive(Debug, Serialize, JsonSchema)]
+pub(super) struct PlayerDevicePollResponse {
+    pub(super) device_id: String,
+    pub(super) active_device_id: Option<String>,
+    pub(super) devices: Vec<PlayerDeviceDto>,
+    pub(super) commands: Vec<PlayerDeviceCommandDto>,
+    pub(super) playback_state: Option<PlayerDevicePlaybackStateDto>,
+}
+
 #[derive(Debug, Serialize, JsonSchema)]
 pub(super) struct PlaylistDetail {
     pub(super) id: i64,

src/player/mod.rs

@@ -1,4 +1,5 @@
-use std::sync::Arc;
+use std::collections::{HashMap, VecDeque};
+use std::sync::{Arc, Mutex};
 
 use cot::db::Database;
 use cot::http::StatusCode;
@@ -50,6 +51,399 @@ struct LocalUploadResponse {
     size: u64,
 }
 
+const PLAYER_DEVICE_TTL_MS: i64 = 30_000;
+const PLAYER_DEVICE_COMMAND_TTL_MS: i64 = 20_000;
+const PLAYER_DEVICE_MAX_COMMANDS: usize = 32;
+
+#[derive(Debug, Clone)]
+struct PlayerDevice {
+    id: String,
+    name: String,
+    kind: String,
+    last_seen_ms: i64,
+}
+
+#[derive(Debug, Clone)]
+struct PendingPlayerDeviceCommand {
+    id: String,
+    command: String,
+    payload: serde_json::Value,
+    created_at_ms: i64,
+}
+
+#[derive(Debug, Default)]
+struct PlayerDeviceHubState {
+    devices_by_user: HashMap<i64, HashMap<String, PlayerDevice>>,
+    active_device_by_user: HashMap<i64, String>,
+    commands_by_device: HashMap<(i64, String), VecDeque<PendingPlayerDeviceCommand>>,
+    playback_state_by_user: HashMap<i64, PlayerDevicePlaybackStateDto>,
+}
+
+#[derive(Debug, Default)]
+struct PlayerDeviceHub {
+    state: Mutex<PlayerDeviceHubState>,
+}
+
+impl PlayerDeviceHub {
+    fn heartbeat(
+        &self,
+        user_id: i64,
+        device_id: &str,
+        user_agent: Option<&str>,
+        playback_state: Option<PlayerDevicePlaybackStateDto>,
+    ) -> PlayerDevicesResponse {
+        let now = current_millis();
+        let mut state = self.state.lock().expect("player device hub lock");
+        self.prune_locked(&mut state, now);
+        self.touch_locked(&mut state, user_id, device_id, user_agent, now);
+        self.update_playback_state_locked(&mut state, user_id, device_id, playback_state, now);
+        self.snapshot_locked(&state, user_id, device_id, now)
+    }
+
+    fn poll(
+        &self,
+        user_id: i64,
+        device_id: &str,
+        user_agent: Option<&str>,
+        playback_state: Option<PlayerDevicePlaybackStateDto>,
+    ) -> PlayerDevicePollResponse {
+        let now = current_millis();
+        let mut state = self.state.lock().expect("player device hub lock");
+        self.prune_locked(&mut state, now);
+        self.touch_locked(&mut state, user_id, device_id, user_agent, now);
+        self.update_playback_state_locked(&mut state, user_id, device_id, playback_state, now);
+        let commands = state
+            .commands_by_device
+            .remove(&(user_id, device_id.to_string()))
+            .unwrap_or_default()
+            .into_iter()
+            .map(|cmd| PlayerDeviceCommandDto {
+                id: cmd.id,
+                command: cmd.command,
+                payload: cmd.payload,
+            })
+            .collect();
+        let snapshot = self.snapshot_locked(&state, user_id, device_id, now);
+        PlayerDevicePollResponse {
+            device_id: snapshot.device_id,
+            active_device_id: snapshot.active_device_id,
+            devices: snapshot.devices,
+            commands,
+            playback_state: snapshot.playback_state,
+        }
+    }
+
+    fn select(
+        &self,
+        user_id: i64,
+        current_device_id: &str,
+        target_device_id: &str,
+    ) -> Option<PlayerDevicesResponse> {
+        let now = current_millis();
+        let mut state = self.state.lock().expect("player device hub lock");
+        self.prune_locked(&mut state, now);
+        let devices = state.devices_by_user.get(&user_id)?;
+        if !devices.contains_key(target_device_id) {
+            return None;
+        }
+        let previous_active_id = state.active_device_by_user.get(&user_id).cloned();
+        let transfer_state = state
+            .playback_state_by_user
+            .get(&user_id)
+            .cloned()
+            .map(|playback_state| playback_state_at(playback_state, now));
+        state
+            .active_device_by_user
+            .insert(user_id, target_device_id.to_string());
+        if previous_active_id.as_deref() != Some(target_device_id) {
+            if let Some(transfer_state) = transfer_state {
+                state
+                    .playback_state_by_user
+                    .insert(user_id, transfer_state.clone());
+                if let Ok(payload) = serde_json::to_value(transfer_state) {
+                    self.enqueue_command_locked(
+                        &mut state,
+                        user_id,
+                        target_device_id,
+                        "transfer_state",
+                        payload,
+                        now,
+                    );
+                }
+            }
+        }
+        Some(self.snapshot_locked(&state, user_id, current_device_id, now))
+    }
+
+    fn enqueue_command(
+        &self,
+        user_id: i64,
+        target_device_id: Option<&str>,
+        command: &str,
+        payload: serde_json::Value,
+    ) -> Result<(), &'static str> {
+        let now = current_millis();
+        let mut state = self.state.lock().expect("player device hub lock");
+        self.prune_locked(&mut state, now);
+
+        let target_id = match target_device_id {
+            Some(id) => id.to_string(),
+            None => state
+                .active_device_by_user
+                .get(&user_id)
+                .cloned()
+                .ok_or("no active device")?,
+        };
+
+        let devices = state
+            .devices_by_user
+            .get(&user_id)
+            .ok_or("target device is offline")?;
+        if !devices.contains_key(&target_id) {
+            return Err("target device is offline");
+        }
+
+        self.enqueue_command_locked(&mut state, user_id, &target_id, command, payload, now);
+        Ok(())
+    }
+
+    fn enqueue_command_locked(
+        &self,
+        state: &mut PlayerDeviceHubState,
+        user_id: i64,
+        target_device_id: &str,
+        command: &str,
+        payload: serde_json::Value,
+        now: i64,
+    ) {
+        let queue = state
+            .commands_by_device
+            .entry((user_id, target_device_id.to_string()))
+            .or_default();
+        while queue.len() >= PLAYER_DEVICE_MAX_COMMANDS {
+            queue.pop_front();
+        }
+        queue.push_back(PendingPlayerDeviceCommand {
+            id: uuid::Uuid::new_v4().simple().to_string(),
+            command: command.to_string(),
+            payload,
+            created_at_ms: now,
+        });
+    }
+
+    fn touch_locked(
+        &self,
+        state: &mut PlayerDeviceHubState,
+        user_id: i64,
+        device_id: &str,
+        user_agent: Option<&str>,
+        now: i64,
+    ) {
+        let devices = state.devices_by_user.entry(user_id).or_default();
+        let device = PlayerDevice {
+            id: device_id.to_string(),
+            name: device_name_from_user_agent(user_agent),
+            kind: device_kind_from_user_agent(user_agent).to_string(),
+            last_seen_ms: now,
+        };
+        devices.insert(device_id.to_string(), device);
+
+        let active_online = state
+            .active_device_by_user
+            .get(&user_id)
+            .is_some_and(|active_id| devices.contains_key(active_id));
+        if !active_online {
+            state
+                .active_device_by_user
+                .insert(user_id, device_id.to_string());
+        }
+    }
+
+    fn update_playback_state_locked(
+        &self,
+        state: &mut PlayerDeviceHubState,
+        user_id: i64,
+        device_id: &str,
+        playback_state: Option<PlayerDevicePlaybackStateDto>,
+        now: i64,
+    ) {
+        let is_active = state
+            .active_device_by_user
+            .get(&user_id)
+            .is_some_and(|active_id| active_id == device_id);
+        if !is_active {
+            return;
+        }
+        let Some(mut playback_state) = playback_state else {
+            return;
+        };
+        playback_state.updated_at_ms = now;
+        state.playback_state_by_user.insert(user_id, playback_state);
+    }
+
+    fn snapshot_locked(
+        &self,
+        state: &PlayerDeviceHubState,
+        user_id: i64,
+        current_device_id: &str,
+        now: i64,
+    ) -> PlayerDevicesResponse {
+        let active_device_id = state.active_device_by_user.get(&user_id).cloned();
+        let mut devices: Vec<PlayerDeviceDto> = state
+            .devices_by_user
+            .get(&user_id)
+            .map(|devices| {
+                devices
+                    .values()
+                    .map(|device| PlayerDeviceDto {
+                        id: device.id.clone(),
+                        name: device.name.clone(),
+                        kind: device.kind.clone(),
+                        is_current: device.id == current_device_id,
+                        is_active: active_device_id.as_deref() == Some(device.id.as_str()),
+                        last_seen_ms: now.saturating_sub(device.last_seen_ms),
+                    })
+                    .collect()
+            })
+            .unwrap_or_default();
+        devices.sort_by(|a, b| {
+            b.is_active
+                .cmp(&a.is_active)
+                .then_with(|| b.is_current.cmp(&a.is_current))
+                .then_with(|| a.name.cmp(&b.name))
+        });
+        PlayerDevicesResponse {
+            device_id: current_device_id.to_string(),
+            active_device_id,
+            devices,
+            playback_state: state.playback_state_by_user.get(&user_id).cloned(),
+        }
+    }
+
+    fn prune_locked(&self, state: &mut PlayerDeviceHubState, now: i64) {
+        state.devices_by_user.retain(|user_id, devices| {
+            devices.retain(|_, device| {
+                now.saturating_sub(device.last_seen_ms) <= PLAYER_DEVICE_TTL_MS
+            });
+            let active_valid = state
+                .active_device_by_user
+                .get(user_id)
+                .is_some_and(|active_id| devices.contains_key(active_id));
+            if !active_valid {
+                if let Some(first_device_id) = devices.keys().next().cloned() {
+                    state
+                        .active_device_by_user
+                        .insert(*user_id, first_device_id);
+                } else {
+                    state.active_device_by_user.remove(user_id);
+                    state.playback_state_by_user.remove(user_id);
+                }
+            }
+            !devices.is_empty()
+        });
+        state
+            .playback_state_by_user
+            .retain(|user_id, _| state.devices_by_user.contains_key(user_id));
+
+        state
+            .commands_by_device
+            .retain(|(user_id, device_id), queue| {
+                let device_online = state
+                    .devices_by_user
+                    .get(user_id)
+                    .is_some_and(|devices| devices.contains_key(device_id));
+                if !device_online {
+                    return false;
+                }
+                queue.retain(|cmd| {
+                    now.saturating_sub(cmd.created_at_ms) <= PLAYER_DEVICE_COMMAND_TTL_MS
+                });
+                !queue.is_empty()
+            });
+    }
+}
+
+fn current_millis() -> i64 {
+    chrono::Utc::now().timestamp_millis()
+}
+
+fn playback_state_at(
+    mut playback_state: PlayerDevicePlaybackStateDto,
+    now: i64,
+) -> PlayerDevicePlaybackStateDto {
+    if !playback_state.paused && playback_state.updated_at_ms > 0 {
+        let elapsed_seconds = now.saturating_sub(playback_state.updated_at_ms) as f64 / 1000.0;
+        playback_state.position_seconds += elapsed_seconds;
+        if playback_state.duration_seconds > 0.0 {
+            playback_state.position_seconds = playback_state
+                .position_seconds
+                .min(playback_state.duration_seconds);
+        }
+    }
+    playback_state.updated_at_ms = now;
+    playback_state
+}
+
+fn normalize_device_id(raw: &str) -> Option<String> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() || trimmed.len() > 128 {
+        return None;
+    }
+    if !trimmed
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_')
+    {
+        return None;
+    }
+    Some(trimmed.to_string())
+}
+
+fn device_name_from_user_agent(user_agent: Option<&str>) -> String {
+    let ua = user_agent.unwrap_or_default().to_ascii_lowercase();
+    let browser = if ua.contains("edg/") || ua.contains("edgios/") || ua.contains("edga/") {
+        "Edge"
+    } else if ua.contains("firefox/") || ua.contains("fxios/") {
+        "Firefox"
+    } else if ua.contains("opr/") || ua.contains("opera") {
+        "Opera"
+    } else if ua.contains("chrome/") || ua.contains("crios/") {
+        "Chrome"
+    } else if ua.contains("safari/") {
+        "Safari"
+    } else {
+        "Browser"
+    };
+
+    let os = if ua.contains("iphone") {
+        "iPhone"
+    } else if ua.contains("ipad") {
+        "iPad"
+    } else if ua.contains("android") {
+        "Android"
+    } else if ua.contains("windows") {
+        "Windows"
+    } else if ua.contains("mac os") || ua.contains("macintosh") {
+        "macOS"
+    } else if ua.contains("linux") {
+        "Linux"
+    } else {
+        "Device"
+    };
+
+    format!("{browser} on {os}")
+}
+
+fn device_kind_from_user_agent(user_agent: Option<&str>) -> &'static str {
+    let ua = user_agent.unwrap_or_default().to_ascii_lowercase();
+    if ua.contains("iphone") || (ua.contains("android") && ua.contains("mobile")) {
+        "phone"
+    } else if ua.contains("ipad") || ua.contains("tablet") || ua.contains("android") {
+        "tablet"
+    } else {
+        "computer"
+    }
+}
+
 #[derive(Debug, sqlx::FromRow)]
 struct LastfmAccountApiRow {
     session_key: String,
@@ -217,10 +611,10 @@ async fn lastfm_connect_handler(
     };
     let (config, _) = AppConfig::load_with_db(&db).await;
     let Some(credentials) = LastfmCredentials::from_config(&config) else {
-        return Ok(redirect_response("/?lastfm=not_configured"));
+        return Ok(redirect_response("/"));
     };
     let Some(origin) = request_origin(&request) else {
-        return Ok(redirect_response("/?lastfm=bad_origin"));
+        return Ok(redirect_response("/"));
     };
 
     let state = uuid::Uuid::new_v4().simple().to_string();
@@ -270,7 +664,7 @@ async fn lastfm_callback_handler(
         .map(str::trim)
         .filter(|v| !v.is_empty())
     else {
-        return Ok(redirect_response("/?lastfm=missing_token"));
+        return Ok(redirect_response("/"));
     };
     let Some(state) = query
         .0
@@ -279,7 +673,7 @@ async fn lastfm_callback_handler(
         .map(str::trim)
         .filter(|v| !v.is_empty())
     else {
-        return Ok(redirect_response("/?lastfm=missing_state"));
+        return Ok(redirect_response("/"));
     };
 
     let state_user_id = sqlx::query_scalar::<_, i64>(
@@ -290,7 +684,7 @@ async fn lastfm_callback_handler(
     .await
     .map_err(|e| cot::Error::internal(e.to_string()))?;
     if state_user_id != Some(user.id) {
-        return Ok(redirect_response("/?lastfm=bad_state"));
+        return Ok(redirect_response("/"));
     }
     sqlx::query("DELETE FROM furumusic__lastfm_auth_state WHERE state = $1")
         .bind(state)
@@ -300,7 +694,7 @@ async fn lastfm_callback_handler(
 
     let (config, _) = AppConfig::load_with_db(&db).await;
     let Some(credentials) = LastfmCredentials::from_config(&config) else {
-        return Ok(redirect_response("/?lastfm=not_configured"));
+        return Ok(redirect_response("/"));
     };
     let client = LastfmClient::new(credentials).map_err(|e| cot::Error::internal(e.to_string()))?;
     match client.get_session(token).await {
@@ -324,11 +718,11 @@ async fn lastfm_callback_handler(
             .execute(pool)
             .await
             .map_err(|e| cot::Error::internal(e.to_string()))?;
-            Ok(redirect_response("/?lastfm=connected"))
+            Ok(redirect_response("/"))
         }
         Err(err) => {
             tracing::warn!("Last.fm auth failed for user {}: {err}", user.id);
-            Ok(redirect_response("/?lastfm=auth_failed"))
+            Ok(redirect_response("/"))
         }
     }
 }
@@ -1452,7 +1846,8 @@ async fn stream_handler(
         return Ok(json_error(StatusCode::NOT_FOUND, "track not found"));
     };
 
-    let full_path = std::path::Path::new(&config.agent_storage_dir).join(&media.file_path);
+    let full_path =
+        crate::media_paths::resolve_media_file_path(&config.agent_storage_dir, &media.file_path);
 
     if !full_path.exists() {
         return Ok(json_error(
@@ -1521,7 +1916,7 @@ async fn local_upload_handler(
             "agent_inbox_dir is not configured",
         ));
     }
-    let inbox_root = std::path::PathBuf::from(inbox_dir);
+    let inbox_root = crate::media_paths::resolve_config_path_buf(inbox_dir);
     if !inbox_root.is_absolute() {
         return Ok(json_error(
             StatusCode::BAD_REQUEST,
@@ -1744,7 +2139,8 @@ async fn cover_response(
         return Ok(json_error(StatusCode::NOT_FOUND, "media file not found"));
     };
 
-    let full_path = std::path::Path::new(&config.agent_storage_dir).join(&media.file_path);
+    let full_path =
+        crate::media_paths::resolve_media_file_path(&config.agent_storage_dir, &media.file_path);
 
     if !full_path.exists() {
         return Ok(json_error(StatusCode::NOT_FOUND, "file not found on disk"));
@@ -1777,6 +2173,113 @@ async fn cover_response(
     Ok(response)
 }
 
+// ---------------------------------------------------------------------------
+// Player devices
+// ---------------------------------------------------------------------------
+
+async fn devices_heartbeat_handler(
+    session: Session,
+    db: Database,
+    hub: Arc<PlayerDeviceHub>,
+    Json(dto): Json<DeviceHeartbeatRequest>,
+) -> cot::Result<cot::response::Response> {
+    let Some(user) = auth::get_session_user(&session, &db).await else {
+        return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
+    };
+    let Some(device_id) = normalize_device_id(&dto.device_id) else {
+        return Ok(json_error(StatusCode::BAD_REQUEST, "invalid device id"));
+    };
+
+    let response = hub.heartbeat(
+        user.id,
+        &device_id,
+        dto.user_agent.as_deref(),
+        dto.playback_state,
+    );
+    Json(response).into_response()
+}
+
+async fn devices_poll_handler(
+    session: Session,
+    db: Database,
+    hub: Arc<PlayerDeviceHub>,
+    Json(dto): Json<DeviceHeartbeatRequest>,
+) -> cot::Result<cot::response::Response> {
+    let Some(user) = auth::get_session_user(&session, &db).await else {
+        return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
+    };
+    let Some(device_id) = normalize_device_id(&dto.device_id) else {
+        return Ok(json_error(StatusCode::BAD_REQUEST, "invalid device id"));
+    };
+
+    let response = hub.poll(
+        user.id,
+        &device_id,
+        dto.user_agent.as_deref(),
+        dto.playback_state,
+    );
+    Json(response).into_response()
+}
+
+async fn devices_select_handler(
+    session: Session,
+    db: Database,
+    hub: Arc<PlayerDeviceHub>,
+    Json(dto): Json<DeviceSelectRequest>,
+) -> cot::Result<cot::response::Response> {
+    let Some(user) = auth::get_session_user(&session, &db).await else {
+        return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
+    };
+    let Some(target_device_id) = normalize_device_id(&dto.device_id) else {
+        return Ok(json_error(StatusCode::BAD_REQUEST, "invalid device id"));
+    };
+    let current_device_id = dto
+        .current_device_id
+        .as_deref()
+        .and_then(normalize_device_id)
+        .unwrap_or_else(|| target_device_id.clone());
+
+    let Some(response) = hub.select(user.id, &current_device_id, &target_device_id) else {
+        return Ok(json_error(
+            StatusCode::BAD_REQUEST,
+            "target device is offline",
+        ));
+    };
+    Json(response).into_response()
+}
+
+async fn devices_command_handler(
+    session: Session,
+    db: Database,
+    hub: Arc<PlayerDeviceHub>,
+    Json(dto): Json<DeviceCommandRequest>,
+) -> cot::Result<cot::response::Response> {
+    let Some(user) = auth::get_session_user(&session, &db).await else {
+        return Ok(json_error(StatusCode::UNAUTHORIZED, "not authenticated"));
+    };
+    let command = dto.command.trim();
+    if command.is_empty() || command.len() > 64 {
+        return Ok(json_error(StatusCode::BAD_REQUEST, "invalid command"));
+    }
+    let target_device_id = match dto.target_device_id.as_deref() {
+        Some(raw) => {
+            let Some(device_id) = normalize_device_id(raw) else {
+                return Ok(json_error(
+                    StatusCode::BAD_REQUEST,
+                    "invalid target device id",
+                ));
+            };
+            Some(device_id)
+        }
+        None => None,
+    };
+
+    match hub.enqueue_command(user.id, target_device_id.as_deref(), command, dto.payload) {
+        Ok(()) => Json(serde_json::json!({"ok": true})).into_response(),
+        Err(message) => Ok(json_error(StatusCode::BAD_REQUEST, message)),
+    }
+}
+
 // ---------------------------------------------------------------------------
 // GET /api/player/state
 // ---------------------------------------------------------------------------
@@ -2959,6 +3462,7 @@ async fn tracks_by_ids_handler(
 pub struct PlayerApp {
     config: Arc<AppConfig>,
     scheduler_handle: Arc<tokio::sync::OnceCell<Arc<SchedulerHandle>>>,
+    device_hub: Arc<PlayerDeviceHub>,
 }
 
 impl PlayerApp {
@@ -2969,6 +3473,7 @@ impl PlayerApp {
         Self {
             config,
             scheduler_handle,
+            device_hub: Arc::new(PlayerDeviceHub::default()),
         }
     }
 }
@@ -2983,6 +3488,7 @@ impl App for PlayerApp {
         let pool: Arc<tokio::sync::OnceCell<sqlx::PgPool>> = Arc::new(tokio::sync::OnceCell::new());
         let torrent_service: Arc<tokio::sync::OnceCell<Arc<TorrentService>>> =
             Arc::new(tokio::sync::OnceCell::new());
+        let device_hub = Arc::clone(&self.device_hub);
 
         Router::with_urls([
             // -- Current user profile --
@@ -3905,7 +4411,6 @@ impl App for PlayerApp {
                 {
                     let pool = Arc::clone(&pool);
                     let pool_config = Arc::clone(&pool_config);
-                    let config = Arc::clone(&self.config);
                     get(
                         move |session: Session,
                               db: Database,
@@ -3913,7 +4418,6 @@ impl App for PlayerApp {
                               request: cot::request::Request| {
                             let pool = Arc::clone(&pool);
                             let pool_config = Arc::clone(&pool_config);
-                            let config = Arc::clone(&config);
                             async move {
                                 let pg_pool = pool
                                     .get_or_init(|| async {
@@ -3924,7 +4428,9 @@ impl App for PlayerApp {
                                             .expect("player pool")
                                     })
                                     .await;
-                                stream_handler(session, db, pg_pool, &config, &request, path).await
+                                let (live_config, _) = AppConfig::load_with_db(&db).await;
+                                stream_handler(session, db, pg_pool, &live_config, &request, path)
+                                    .await
                             }
                         },
                     )
@@ -3937,12 +4443,10 @@ impl App for PlayerApp {
                 {
                     let pool = Arc::clone(&pool);
                     let pool_config = Arc::clone(&pool_config);
-                    let config = Arc::clone(&self.config);
                     get(
                         move |session: Session, db: Database, path: Path<PathMediaFileVariant>| {
                             let pool = Arc::clone(&pool);
                             let pool_config = Arc::clone(&pool_config);
-                            let config = Arc::clone(&config);
                             async move {
                                 let pg_pool = pool
                                     .get_or_init(|| async {
@@ -3953,7 +4457,9 @@ impl App for PlayerApp {
                                             .expect("player pool")
                                     })
                                     .await;
-                                cover_variant_handler(session, db, pg_pool, &config, path).await
+                                let (live_config, _) = AppConfig::load_with_db(&db).await;
+                                cover_variant_handler(session, db, pg_pool, &live_config, path)
+                                    .await
                             }
                         },
                     )
@@ -3965,12 +4471,10 @@ impl App for PlayerApp {
                 {
                     let pool = Arc::clone(&pool);
                     let pool_config = Arc::clone(&pool_config);
-                    let config = Arc::clone(&self.config);
                     get(
                         move |session: Session, db: Database, path: Path<PathMediaFileId>| {
                             let pool = Arc::clone(&pool);
                             let pool_config = Arc::clone(&pool_config);
-                            let config = Arc::clone(&config);
                             async move {
                                 let pg_pool = pool
                                     .get_or_init(|| async {
@@ -3981,13 +4485,59 @@ impl App for PlayerApp {
                                             .expect("player pool")
                                     })
                                     .await;
-                                cover_handler(session, db, pg_pool, &config, path).await
+                                let (live_config, _) = AppConfig::load_with_db(&db).await;
+                                cover_handler(session, db, pg_pool, &live_config, path).await
                             }
                         },
                     )
                 },
                 "player_cover",
             ),
+            // -- Active browser devices --
+            Route::with_handler_and_name(
+                "/devices/heartbeat",
+                post({
+                    let device_hub = Arc::clone(&device_hub);
+                    move |session: Session, db: Database, json: Json<DeviceHeartbeatRequest>| {
+                        let device_hub = Arc::clone(&device_hub);
+                        async move { devices_heartbeat_handler(session, db, device_hub, json).await }
+                    }
+                }),
+                "player_devices_heartbeat",
+            ),
+            Route::with_handler_and_name(
+                "/devices/poll",
+                post({
+                    let device_hub = Arc::clone(&device_hub);
+                    move |session: Session, db: Database, json: Json<DeviceHeartbeatRequest>| {
+                        let device_hub = Arc::clone(&device_hub);
+                        async move { devices_poll_handler(session, db, device_hub, json).await }
+                    }
+                }),
+                "player_devices_poll",
+            ),
+            Route::with_handler_and_name(
+                "/devices/active",
+                post({
+                    let device_hub = Arc::clone(&device_hub);
+                    move |session: Session, db: Database, json: Json<DeviceSelectRequest>| {
+                        let device_hub = Arc::clone(&device_hub);
+                        async move { devices_select_handler(session, db, device_hub, json).await }
+                    }
+                }),
+                "player_devices_active",
+            ),
+            Route::with_handler_and_name(
+                "/devices/command",
+                post({
+                    let device_hub = Arc::clone(&device_hub);
+                    move |session: Session, db: Database, json: Json<DeviceCommandRequest>| {
+                        let device_hub = Arc::clone(&device_hub);
+                        async move { devices_command_handler(session, db, device_hub, json).await }
+                    }
+                }),
+                "player_devices_command",
+            ),
             // -- Playback state GET --
             Route::with_handler_and_name(
                 "/state",

src/scheduler/mod.rs

@@ -1471,6 +1471,31 @@ pub async fn start_scheduler(
         Err(e) => tracing::error!("Failed to recover stale reviews: {e}"),
     }
 
+    let (live_config, _) = AppConfig::load_with_db(&db).await;
+    if !live_config.agent_storage_dir.trim().is_empty() {
+        match crate::media_paths::normalize_media_file_paths(&pool, &live_config.agent_storage_dir)
+            .await
+        {
+            Ok(0) => {}
+            Ok(n) => tracing::info!("Normalized {n} media file path(s) to relative storage paths"),
+            Err(e) => tracing::warn!("Failed to normalize media file paths: {e:#}"),
+        }
+    }
+    if !live_config.agent_inbox_dir.trim().is_empty() {
+        match crate::media_paths::normalize_pending_review_paths(
+            &pool,
+            &live_config.agent_inbox_dir,
+        )
+        .await
+        {
+            Ok(0) => {}
+            Ok(n) => {
+                tracing::info!("Normalized {n} pending review path(s) to relative inbox paths")
+            }
+            Err(e) => tracing::warn!("Failed to normalize pending review paths: {e:#}"),
+        }
+    }
+
     // Upsert ScheduledJob rows
     for job in registry.all_jobs() {
         ScheduledJob::upsert(&db, job.name(), job.description(), job.default_cron())

src/torrents.rs

@@ -1242,7 +1242,7 @@ fn validate_selection(files: &[TorrentFileDto], selected_files: &[usize]) -> any
 
 fn validate_inbox_dir(inbox_dir: &str) -> anyhow::Result<PathBuf> {
     let trimmed = inbox_dir.trim();
-    let path = PathBuf::from(trimmed);
+    let path = crate::media_paths::resolve_config_path_buf(trimmed);
     if !path.is_absolute() {
         bail!(
             "agent_inbox_dir must be an absolute path for this host, got `{}`",

templates/player/scripts.html

@@ -35,9 +35,15 @@ const T = {
     lastfmConnected: "{{ t.player_lastfm_connected }}",
     lastfmReconnect: "{{ t.player_lastfm_reconnect }}",
     lastfmNotConfigured: "{{ t.player_lastfm_not_configured }}",
+    lastfmStatusConnect: "{{ t.player_lastfm_status_connect }}",
+    lastfmStatusConnected: "{{ t.player_lastfm_status_connected }}",
+    lastfmStatusReconnect: "{{ t.player_lastfm_status_reconnect }}",
+    lastfmStatusNotConfigured: "{{ t.player_lastfm_status_not_configured }}",
     lastfmDisconnectConfirm: "{{ t.player_lastfm_disconnect_confirm }}",
     lastfmConnectFailed: "{{ t.player_lastfm_connect_failed }}",
     lastfmDisconnectFailed: "{{ t.player_lastfm_disconnect_failed }}",
+    connectionLost: "{{ t.player_connection_lost }}",
+    connectionLostDetail: "{{ t.player_connection_lost_detail }}",
     trackWord: "{{ t.player_tracks_count }}",
     clientIdle: "{{ t.player_client_idle }}",
     active: "{{ t.player_active }}",
@@ -115,6 +121,42 @@ function coverVariantUrl(url, variant) {
 }
 
 document.addEventListener('alpine:init', () => {
+    // -----------------------------------------------------------------------
+    // Connection monitor
+    // -----------------------------------------------------------------------
+    Alpine.store('connection', {
+        failureCount: 0,
+        disconnected: false,
+        threshold: 2,
+
+        init() {
+            if (navigator.onLine === false) {
+                this.failureCount = this.threshold;
+                this.disconnected = true;
+            }
+            window.addEventListener('online', () => this.recordSuccess());
+            window.addEventListener('offline', () => this.recordFailure());
+        },
+
+        message() {
+            return T.connectionLostDetail;
+        },
+
+        recordSuccess() {
+            this.failureCount = 0;
+            this.disconnected = false;
+        },
+
+        recordFailure() {
+            this.failureCount += 1;
+            if (this.failureCount >= this.threshold) {
+                this.disconnected = true;
+            }
+        },
+    });
+
+    installConnectionFetchMonitor();
+
     // -----------------------------------------------------------------------
     // Audio element
     // -----------------------------------------------------------------------
@@ -174,10 +216,19 @@ document.addEventListener('alpine:init', () => {
         lastfmBusy: false,
 
         init() {
+            this.cleanLastfmQuery();
             this.load();
             this.loadLastfm();
         },
 
+        cleanLastfmQuery() {
+            const url = new URL(window.location.href);
+            if (!url.searchParams.has('lastfm')) return;
+            url.searchParams.delete('lastfm');
+            const clean = `${url.pathname}${url.search}${url.hash}`;
+            window.history.replaceState({}, document.title, clean || '/');
+        },
+
         async load() {
             try {
                 const res = await fetch('/api/player/me');
@@ -210,6 +261,16 @@ document.addEventListener('alpine:init', () => {
             return T.lastfmConnect;
         },
 
+        lastfmStatusLabel() {
+            if (!this.lastfm?.configured) return T.lastfmStatusNotConfigured;
+            if (this.lastfm?.connected && this.lastfm?.reauth_required) return T.lastfmStatusReconnect;
+            if (this.lastfm?.connected) {
+                const user = this.lastfm.username || T.unknown;
+                return `${T.lastfmStatusConnected}: ${user}`;
+            }
+            return T.lastfmStatusConnect;
+        },
+
         lastfmClass() {
             if (!this.lastfm?.configured) return 'not-configured';
             if (this.lastfm?.connected && this.lastfm?.reauth_required) return 'needs-auth';
@@ -359,6 +420,10 @@ document.addEventListener('alpine:init', () => {
         _playbackStartedAt: null,
         _listenedSeconds: 0,
         _lastAudioTime: 0,
+        _remoteExecuting: false,
+        _remoteStateBaseTime: 0,
+        _remoteStateReceivedAt: 0,
+        _remoteStateTimer: null,
 
         init() {
             audio.volume = this.volume;
@@ -393,29 +458,100 @@ document.addEventListener('alpine:init', () => {
 
             // Periodic state save
             this._saveTimer = setInterval(() => {
-                this._saveState();
+                if (this._isLocalPlaybackDevice()) this._saveState();
             }, 10000);
+            this._remoteStateTimer = setInterval(() => {
+                this._tickRemoteProgress();
+            }, 250);
 
             // Restore state
             this._restoreState();
 
             // Save state on page unload
             window.addEventListener('beforeunload', () => {
-                this._saveStateSync();
+                if (this._isLocalPlaybackDevice()) this._saveStateSync();
             });
         },
 
         play(track) {
+            if (!track) return;
+            if (this._shouldSendRemote()) {
+                this._mirrorRemoteTrack(track, true, 0);
+                this._sendRemote('play_track', this._remotePlaybackPayload(track, {
+                    position_seconds: 0,
+                    paused: false,
+                }));
+                return;
+            }
+            this._playLocal(track);
+        },
+
+        playQueueIndex(idx) {
+            const queue = Alpine.store('queue');
+            if (!queue || idx < 0 || idx >= queue.tracks.length) return;
+            queue.currentIndex = idx;
+            const track = queue.tracks[idx];
+            if (this._shouldSendRemote()) {
+                this._mirrorRemoteTrack(track, true, 0);
+                this._sendRemote('play_from_index', this._remotePlaybackPayload(track, {
+                    index: idx,
+                    position_seconds: 0,
+                    paused: false,
+                }));
+                return;
+            }
+            this._playLocal(track);
+        },
+
+        _playLocal(track, options = {}) {
             this.currentTrack = track;
             this._historyRecorded = false;
             this._resetPlaybackTracking();
             audio.src = track.stream_url;
+            const seekSeconds = Number(options.position_seconds || 0);
+            if (seekSeconds > 0) {
+                const onLoaded = () => {
+                    audio.currentTime = seekSeconds;
+                    this._lastAudioTime = audio.currentTime || 0;
+                    audio.removeEventListener('loadedmetadata', onLoaded);
+                };
+                audio.addEventListener('loadedmetadata', onLoaded);
+            }
+            if (options.paused) {
+                audio.pause();
+                this.isPlaying = false;
+            } else {
                 audio.play().catch(() => {});
+            }
             this._updateMediaSession();
         },
 
-        pause() { audio.pause(); },
-        resume() { audio.play().catch(() => {}); },
+        _pauseLocal() {
+            audio.pause();
+            this.isPlaying = false;
+        },
+
+        pause() {
+            if (this._shouldSendRemote()) {
+                this.isPlaying = false;
+                this._remoteStateBaseTime = this.currentTime;
+                this._remoteStateReceivedAt = Date.now();
+                this._sendRemote('pause');
+                return;
+            }
+            this._pauseLocal();
+        },
+
+        resume() {
+            if (this._shouldSendRemote()) {
+                this.isPlaying = true;
+                this._remoteStateBaseTime = this.currentTime;
+                this._remoteStateReceivedAt = Date.now();
+                this._sendRemote('resume');
+                return;
+            }
+            audio.play().catch(() => {});
+        },
 
         toggle() {
             if (!this.currentTrack) return;
@@ -424,14 +560,25 @@ document.addEventListener('alpine:init', () => {
         },
 
         seek(time) {
-            audio.currentTime = time;
+            const nextTime = Math.max(0, Number(time || 0));
+            if (this._shouldSendRemote()) {
+                this.currentTime = nextTime;
+                this.progress = this.duration > 0 ? (this.currentTime / this.duration) * 100 : 0;
+                this._remoteStateBaseTime = nextTime;
+                this._remoteStateReceivedAt = Date.now();
+                this._sendRemote('seek', { time: nextTime });
+                return;
+            }
+            audio.currentTime = nextTime;
             this._lastAudioTime = audio.currentTime || 0;
         },
 
         seekRelative(delta) {
             if (!this.currentTrack) return;
-            audio.currentTime = Math.max(0, Math.min(audio.duration || 0, audio.currentTime + delta));
-            this._lastAudioTime = audio.currentTime || 0;
+            const duration = this.duration || audio.duration || 0;
+            const current = this._shouldSendRemote() ? this.currentTime : audio.currentTime;
+            const max = duration > 0 ? duration : Number.MAX_SAFE_INTEGER;
+            this.seek(Math.max(0, Math.min(max, current + delta)));
         },
 
         seekFromClick(event) {
@@ -444,12 +591,23 @@ document.addEventListener('alpine:init', () => {
         },
 
         next() {
+            if (this._shouldSendRemote()) {
+                this._sendRemote('next', {
+                    shuffle: this.shuffle,
+                    repeat_mode: this.repeatMode,
+                });
+                return;
+            }
             const queue = Alpine.store('queue');
             if (queue.tracks.length === 0) return;
 
+            this._recordHistoryIfListenThresholdReached();
+
             let nextIdx;
             if (this.repeatMode === 'one') {
                 this.seek(0);
+                this._historyRecorded = false;
+                this._resetPlaybackTracking();
                 this.resume();
                 return;
             } else if (this.shuffle) {
@@ -465,10 +623,14 @@ document.addEventListener('alpine:init', () => {
                     }
                 }
             }
-            queue.playFromIndex(nextIdx);
+            this.playQueueIndex(nextIdx);
         },
 
         prev() {
+            if (this._shouldSendRemote()) {
+                this._sendRemote('prev');
+                return;
+            }
             if (this.currentTime > 3) {
                 this.seek(0);
                 return;
@@ -485,11 +647,18 @@ document.addEventListener('alpine:init', () => {
                     return;
                 }
             }
-            queue.playFromIndex(prevIdx);
+            this.playQueueIndex(prevIdx);
         },
 
         setVolume(v) {
-            this.volume = Math.max(0, Math.min(1, v));
+            this._setVolumeLocal(v);
+            if (this._shouldSendRemote()) {
+                this._sendRemote('set_volume', { volume: this.volume });
+            }
+        },
+
+        _setVolumeLocal(v) {
+            this.volume = Math.max(0, Math.min(1, Number(v || 0)));
             audio.volume = this.volume;
         },
 
@@ -532,12 +701,160 @@ document.addEventListener('alpine:init', () => {
 
         toggleShuffle() {
             this.shuffle = !this.shuffle;
+            if (this._shouldSendRemote()) {
+                this._sendRemote('set_options', {
+                    shuffle: this.shuffle,
+                    repeat_mode: this.repeatMode,
+                });
+            }
         },
 
         cycleRepeat() {
             if (this.repeatMode === 'off') this.repeatMode = 'all';
             else if (this.repeatMode === 'all') this.repeatMode = 'one';
             else this.repeatMode = 'off';
+            if (this._shouldSendRemote()) {
+                this._sendRemote('set_options', {
+                    shuffle: this.shuffle,
+                    repeat_mode: this.repeatMode,
+                });
+            }
+        },
+
+        _isLocalPlaybackDevice() {
+            const devices = Alpine.store('devices');
+            return !devices || devices.isActive();
+        },
+
+        _shouldSendRemote() {
+            const devices = Alpine.store('devices');
+            return !!devices && !this._remoteExecuting && !devices.isActive();
+        },
+
+        _sendRemote(command, payload = {}) {
+            const devices = Alpine.store('devices');
+            if (!devices) return false;
+            devices.sendCommand(command, payload);
+            return true;
+        },
+
+        _remotePlaybackPayload(track, overrides = {}) {
+            const queue = Alpine.store('queue');
+            const tracks = queue?.tracks?.length ? queue.tracks : (track ? [track] : []);
+            let index = Number.isInteger(overrides.index) ? overrides.index : (queue?.currentIndex ?? 0);
+            if (track && tracks[index]?.id !== track.id) {
+                const foundIndex = tracks.findIndex(item => item.id === track.id);
+                index = foundIndex >= 0 ? foundIndex : 0;
+            }
+            return {
+                track,
+                tracks,
+                index,
+                position_seconds: overrides.position_seconds ?? this.currentTime,
+                duration_seconds: overrides.duration_seconds ?? this._trackDuration(),
+                paused: overrides.paused ?? !this.isPlaying,
+                shuffle: this.shuffle,
+                repeat_mode: this.repeatMode,
+                volume: this.volume,
+            };
+        },
+
+        _devicePlaybackStatePayload() {
+            const queue = Alpine.store('queue');
+            const track = this.currentTrack || queue?.tracks?.[queue.currentIndex] || null;
+            if (!track && (!queue || queue.tracks.length === 0)) return null;
+            return this._remotePlaybackPayload(track, {
+                position_seconds: audio.currentTime || this.currentTime || 0,
+                duration_seconds: this._trackDuration(),
+                paused: !this.isPlaying,
+            });
+        },
+
+        _mirrorRemoteTrack(track, playing, positionSeconds = null) {
+            if (!track) return;
+            this.currentTrack = track;
+            this.isPlaying = !!playing;
+            if (positionSeconds !== null) this.currentTime = Math.max(0, Number(positionSeconds || 0));
+            this.duration = Number(track.duration_seconds || this.duration || 0);
+            this.progress = this.duration > 0 ? (this.currentTime / this.duration) * 100 : 0;
+            this._remoteStateBaseTime = this.currentTime;
+            this._remoteStateReceivedAt = Date.now();
+            this._updateMediaSession();
+        },
+
+        _applyRemotePlaybackState(state) {
+            if (!state) return;
+            const queue = Alpine.store('queue');
+            const tracks = Array.isArray(state.tracks) ? state.tracks.filter(Boolean) : [];
+            if (queue && tracks.length > 0) {
+                queue.tracks = tracks;
+                queue.currentIndex = Math.max(0, Math.min(Number(state.index || 0), tracks.length - 1));
+            }
+            const track = state.track || queue?.tracks?.[queue.currentIndex] || null;
+            if (track) {
+                this.currentTrack = track;
+            }
+            this.shuffle = !!state.shuffle;
+            this.repeatMode = state.repeat_mode || 'off';
+            if (typeof state.volume === 'number') this._setVolumeLocal(state.volume);
+            this.duration = Number(state.duration_seconds || track?.duration_seconds || this.duration || 0);
+            this.isPlaying = !state.paused;
+            this._remoteStateBaseTime = Math.max(0, Number(state.position_seconds || 0));
+            this._remoteStateReceivedAt = Date.now();
+            this._tickRemoteProgress(true);
+            this._updateMediaSession();
+        },
+
+        _tickRemoteProgress(force = false) {
+            if (this._isLocalPlaybackDevice() || !this.currentTrack) return;
+            if (!force && !this.isPlaying) return;
+            let nextTime = Number(this._remoteStateBaseTime || 0);
+            if (this.isPlaying && this._remoteStateReceivedAt > 0) {
+                nextTime += (Date.now() - this._remoteStateReceivedAt) / 1000;
+            }
+            const duration = Number(this.duration || this.currentTrack?.duration_seconds || 0);
+            if (duration > 0) nextTime = Math.min(nextTime, duration);
+            this.currentTime = Math.max(0, nextTime);
+            this.progress = duration > 0 ? (this.currentTime / duration) * 100 : 0;
+        },
+
+        _executeRemoteCommand(command) {
+            if (!command || !command.command) return;
+            const payload = command.payload || {};
+            const queue = Alpine.store('queue');
+            this._remoteExecuting = true;
+            try {
+                if (typeof payload.shuffle === 'boolean') this.shuffle = payload.shuffle;
+                if (payload.repeat_mode) this.repeatMode = payload.repeat_mode;
+                if (typeof payload.volume === 'number') this._setVolumeLocal(payload.volume);
+
+                if (command.command === 'play_track' || command.command === 'play_from_index' || command.command === 'transfer_state') {
+                    if (Array.isArray(payload.tracks) && payload.tracks.length > 0) {
+                        queue.tracks = payload.tracks;
+                        queue.currentIndex = Math.max(0, Math.min(Number(payload.index || 0), queue.tracks.length - 1));
+                    }
+                    const track = payload.track || queue.tracks[queue.currentIndex];
+                    if (track) this._playLocal(track, payload);
+                } else if (command.command === 'pause') {
+                    this.pause();
+                } else if (command.command === 'resume') {
+                    this.resume();
+                } else if (command.command === 'seek') {
+                    this.seek(Number(payload.time || 0));
+                } else if (command.command === 'next') {
+                    this.next();
+                } else if (command.command === 'prev') {
+                    this.prev();
+                } else if (command.command === 'set_volume') {
+                    this.setVolume(payload.volume);
+                } else if (command.command === 'set_options') {
+                    // Options were already applied above.
+                }
+                this._saveState();
+                Alpine.store('devices')?.heartbeat();
+            } finally {
+                this._remoteExecuting = false;
+            }
         },
 
         _updateMediaSession() {
@@ -594,7 +911,7 @@ document.addEventListener('alpine:init', () => {
                 const state = await res.json();
                 this.shuffle = state.shuffle || false;
                 this.repeatMode = state.repeat_mode || 'off';
-                this.setVolume(typeof state.volume === 'number' ? state.volume : 0.7);
+                this._setVolumeLocal(typeof state.volume === 'number' ? state.volume : 0.7);
 
                 // Restore queue if there are track IDs
                 if (state.queue && state.queue.length > 0) {
@@ -655,6 +972,18 @@ document.addEventListener('alpine:init', () => {
             }).catch(() => {});
         },
 
+        _recordHistoryIfListenThresholdReached() {
+            if (this._historyRecorded || !this.currentTrack) return false;
+            this._trackListenedDelta();
+            const duration = this._trackDuration();
+            if (duration <= 0) return false;
+            const listened = Math.floor(Number(this._listenedSeconds || 0));
+            const threshold = Math.ceil(duration / 2);
+            if (threshold <= 0 || listened < threshold) return false;
+            this._recordHistory(true);
+            return true;
+        },
+
         _resetPlaybackTracking() {
             this._nowPlayingSent = false;
             this._playbackStartedAt = null;
@@ -720,6 +1049,157 @@ document.addEventListener('alpine:init', () => {
         },
     });
 
+    // -----------------------------------------------------------------------
+    // Playback devices store
+    // -----------------------------------------------------------------------
+    Alpine.store('devices', {
+        id: null,
+        devices: [],
+        activeDeviceId: null,
+        open: false,
+        _pollTimer: null,
+        _stateRefreshTick: 0,
+
+        init() {
+            this.id = this._ensureId();
+            this.heartbeat();
+            this._pollTimer = setInterval(() => this.poll(), 500);
+            document.addEventListener('visibilitychange', () => {
+                if (!document.hidden) this.poll();
+            });
+        },
+
+        _ensureId() {
+            let id = sessionStorage.getItem('furu_player_device_id');
+            if (!id) {
+                id = (crypto.randomUUID ? crypto.randomUUID() : this._fallbackId()).replace(/[^a-zA-Z0-9_-]/g, '');
+                sessionStorage.setItem('furu_player_device_id', id);
+            }
+            return id;
+        },
+
+        _fallbackId() {
+            return 'device-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2);
+        },
+
+        requestPayload() {
+            const player = Alpine.store('player');
+            return {
+                device_id: this.id,
+                user_agent: navigator.userAgent || '',
+                playback_state: player && this.isActive() ? player._devicePlaybackStatePayload() : null,
+            };
+        },
+
+        async heartbeat() {
+            try {
+                const res = await fetch('/api/player/devices/heartbeat', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(this.requestPayload()),
+                });
+                if (!res.ok) return;
+                this._apply(await res.json());
+            } catch {}
+        },
+
+        async poll() {
+            try {
+                const res = await fetch('/api/player/devices/poll', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(this.requestPayload()),
+                });
+                if (!res.ok) return;
+                const data = await res.json();
+                this._apply(data);
+
+                const player = Alpine.store('player');
+                if (player && Array.isArray(data.commands)) {
+                    data.commands.forEach(command => player._executeRemoteCommand(command));
+                }
+                if (player && !this.isActive()) {
+                    if (data.playback_state) {
+                        player._applyRemotePlaybackState(data.playback_state);
+                    } else if (++this._stateRefreshTick % 8 === 0) {
+                        player._restoreState();
+                    }
+                }
+            } catch {}
+        },
+
+        _apply(data) {
+            const wasActive = this.isActive();
+            this.activeDeviceId = data.active_device_id || null;
+            this.devices = Array.isArray(data.devices) ? data.devices : [];
+            if (wasActive && !this.isActive()) {
+                Alpine.store('player')?._pauseLocal();
+            }
+        },
+
+        isActive() {
+            return !this.activeDeviceId || this.activeDeviceId === this.id;
+        },
+
+        activeLabel() {
+            const active = this.devices.find(device => device.id === this.activeDeviceId);
+            return active ? active.name : 'Devices';
+        },
+
+        toggle() {
+            this.open = !this.open;
+            if (this.open) this.poll();
+        },
+
+        async select(deviceId) {
+            if (!deviceId) return;
+            const player = Alpine.store('player');
+
+            try {
+                const res = await fetch('/api/player/devices/active', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        device_id: deviceId,
+                        current_device_id: this.id,
+                    }),
+                });
+                if (!res.ok) return;
+                const data = await res.json();
+                this._apply(data);
+                this.open = false;
+
+                if (deviceId === this.id && data.playback_state && player) {
+                    player._executeRemoteCommand({
+                        command: 'transfer_state',
+                        payload: data.playback_state,
+                    });
+                } else if (deviceId !== this.id && player && this.id !== this.activeDeviceId) {
+                    player._applyRemotePlaybackState(data.playback_state);
+                }
+            } catch {}
+        },
+
+        async sendCommand(command, payload = {}, targetDeviceId = null) {
+            const target = targetDeviceId || this.activeDeviceId;
+            if (!target || target === this.id) return false;
+            try {
+                const res = await fetch('/api/player/devices/command', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        target_device_id: target,
+                        command,
+                        payload,
+                    }),
+                });
+                return res.ok;
+            } catch {
+                return false;
+            }
+        },
+    });
+
     // -----------------------------------------------------------------------
     // Queue store
     // -----------------------------------------------------------------------
@@ -749,8 +1229,7 @@ document.addEventListener('alpine:init', () => {
 
         playFromIndex(idx) {
             if (idx < 0 || idx >= this.tracks.length) return;
-            this.currentIndex = idx;
-            Alpine.store('player').play(this.tracks[idx]);
+            Alpine.store('player').playQueueIndex(idx);
         },
 
         remove(idx) {
@@ -2294,4 +2773,39 @@ document.addEventListener('alpine:init', () => {
         },
     });
 });
+
+function installConnectionFetchMonitor() {
+    if (window.__furumusicConnectionMonitorInstalled || !window.fetch) return;
+    window.__furumusicConnectionMonitorInstalled = true;
+    const nativeFetch = window.fetch.bind(window);
+
+    window.fetch = async (...args) => {
+        const tracked = isTrackedPlayerRequest(args[0]);
+        try {
+            const response = await nativeFetch(...args);
+            if (tracked) {
+                if (response.status >= 500) {
+                    Alpine.store('connection')?.recordFailure();
+                } else {
+                    Alpine.store('connection')?.recordSuccess();
+                }
+            }
+            return response;
+        } catch (error) {
+            if (tracked) Alpine.store('connection')?.recordFailure();
+            throw error;
+        }
+    };
+}
+
+function isTrackedPlayerRequest(input) {
+    const rawUrl = typeof input === 'string' ? input : input?.url;
+    if (!rawUrl) return false;
+    try {
+        const url = new URL(rawUrl, window.location.href);
+        return url.origin === window.location.origin && url.pathname.startsWith('/api/player/');
+    } catch {
+        return false;
+    }
+}
 </script>

templates/player/shell.html

@@ -41,9 +41,15 @@
                 <button class="lastfm-profile-action"
                         :class="$store.user.lastfmClass()"
                         :disabled="$store.user.lastfmBusy || !$store.user.lastfm?.configured"
-                        @click="$store.user.handleLastfm()">
+                        @click="$store.user.handleLastfm()"
+                        :title="$store.user.lastfmLabel()"
+                        :aria-label="$store.user.lastfmLabel()">
                     <span class="lastfm-dot"></span>
-                    <span class="lastfm-profile-text" x-text="$store.user.lastfmLabel()"></span>
+                    <span class="lastfm-profile-text">
+                        <span class="lastfm-profile-brand">{{ t.player_lastfm_profile }}</span>
+                        <span class="lastfm-profile-separator">·</span>
+                        <span class="lastfm-profile-status" x-text="$store.user.lastfmStatusLabel()"></span>
+                    </span>
                 </button>
             </div>
             <div class="sidebar-header">
@@ -275,6 +281,20 @@
                         <path d="M4 4.5A2.5 2.5 0 016.5 2H20v20H6.5A2.5 2.5 0 014 19.5z"/>
                     </svg>
                 </button>
+                <div class="connection-alert"
+                     x-show="$store.connection.disconnected"
+                     x-cloak
+                     :title="$store.connection.message()"
+                     role="status"
+                     aria-live="polite">
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                        <path d="M2 8.82a15 15 0 0120 0"/>
+                        <path d="M5 12.86a10 10 0 0114 0"/>
+                        <path d="M8.5 16.43a5 5 0 017 0"/>
+                        <line x1="2" y1="2" x2="22" y2="22"/>
+                    </svg>
+                    <span class="connection-alert-text">{{ t.player_connection_lost }}</span>
+                </div>
                 <div class="search-bar">
                     <span class="search-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg></span>
                     <input id="search-input" type="text" placeholder="{{ t.player_search_placeholder }}"
@@ -334,9 +354,15 @@
                     <button class="lastfm-profile-action"
                             :class="$store.user.lastfmClass()"
                             :disabled="$store.user.lastfmBusy || !$store.user.lastfm?.configured"
-                            @click="$store.user.handleLastfm()">
+                            @click="$store.user.handleLastfm()"
+                            :title="$store.user.lastfmLabel()"
+                            :aria-label="$store.user.lastfmLabel()">
                         <span class="lastfm-dot"></span>
-                        <span class="lastfm-profile-text" x-text="$store.user.lastfmLabel()"></span>
+                        <span class="lastfm-profile-text">
+                            <span class="lastfm-profile-brand">{{ t.player_lastfm_profile }}</span>
+                            <span class="lastfm-profile-separator">·</span>
+                            <span class="lastfm-profile-status" x-text="$store.user.lastfmStatusLabel()"></span>
+                        </span>
                     </button>
                     <button class="modal-btn modal-btn-primary mobile-account-logout"
                             @click="$store.user.logout()">
@@ -1032,5 +1058,50 @@
             <button class="queue-toggle-btn" :class="{ active: $store.queue.visible }" @click="$store.queue.visible = !$store.queue.visible" title="{{ t.player_queue }}">
                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="8" y1="6" x2="21" y2="6"/><line x1="8" y1="12" x2="21" y2="12"/><line x1="8" y1="18" x2="21" y2="18"/><line x1="3" y1="6" x2="3.01" y2="6"/><line x1="3" y1="12" x2="3.01" y2="12"/><line x1="3" y1="18" x2="3.01" y2="18"/></svg>
             </button>
+            <div class="device-picker" @click.outside="$store.devices.open = false">
+                <button class="queue-toggle-btn device-toggle-btn"
+                        :class="{ active: $store.devices.isActive() }"
+                        @click="$store.devices.toggle()"
+                        :title="$store.devices.activeLabel()"
+                        aria-label="Devices">
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                        <rect x="3" y="4" width="18" height="12" rx="2"/>
+                        <path d="M8 20h8"/>
+                        <path d="M12 16v4"/>
+                    </svg>
+                </button>
+                <div class="device-popover" x-show="$store.devices.open" x-transition x-cloak>
+                    <template x-for="device in $store.devices.devices" :key="device.id">
+                        <button class="device-row"
+                                :class="{ active: device.is_active }"
+                                @click="$store.devices.select(device.id)">
+                            <span class="device-row-icon">
+                                <template x-if="device.kind === 'phone'">
+                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                                        <rect x="7" y="2" width="10" height="20" rx="2"/>
+                                        <path d="M11 18h2"/>
+                                    </svg>
+                                </template>
+                                <template x-if="device.kind !== 'phone'">
+                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                                        <rect x="3" y="4" width="18" height="12" rx="2"/>
+                                        <path d="M8 20h8"/>
+                                        <path d="M12 16v4"/>
+                                    </svg>
+                                </template>
+                            </span>
+                            <span class="device-row-main">
+                                <span class="device-row-name" x-text="device.name"></span>
+                                <span class="device-row-current" x-show="device.is_current">This device</span>
+                            </span>
+                            <span class="device-row-check" x-show="device.is_active">
+                                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4">
+                                    <polyline points="20 6 9 17 4 12"/>
+                                </svg>
+                            </span>
+                        </button>
+                    </template>
+                </div>
+            </div>
         </div>
     </div>

templates/player/styles.html

@@ -219,12 +219,32 @@ button.user-stat:hover {
 }
 
 .lastfm-profile-text {
+    min-width: 0;
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    overflow: hidden;
+    font-size: 11px;
+    font-weight: 650;
+    white-space: nowrap;
+}
+
+.lastfm-profile-brand {
+    flex: 0 0 auto;
+    color: var(--text-primary);
+    font-weight: 800;
+}
+
+.lastfm-profile-separator {
+    flex: 0 0 auto;
+    color: var(--text-subdued);
+}
+
+.lastfm-profile-status {
     min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
-    font-size: 11px;
-    font-weight: 650;
 }
 
 .sidebar-header {
@@ -1342,6 +1362,104 @@ button.user-stat:hover {
 .queue-toggle-btn.active { color: var(--accent); }
 .queue-toggle-btn svg { width: 18px; height: 18px; }
 
+.device-picker {
+    position: relative;
+    display: flex;
+    align-items: center;
+}
+
+.device-toggle-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.device-popover {
+    position: absolute;
+    right: 0;
+    bottom: 38px;
+    width: 260px;
+    max-width: calc(100vw - 24px);
+    max-height: min(320px, calc(100dvh - var(--player-bar-space) - 24px));
+    overflow-y: auto;
+    padding: 6px;
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    background: var(--bg-elevated);
+    box-shadow: 0 16px 46px rgba(0,0,0,0.48);
+    z-index: 45;
+}
+
+.device-row {
+    width: 100%;
+    min-height: 44px;
+    border: 0;
+    border-radius: 6px;
+    background: transparent;
+    color: var(--text-secondary);
+    display: grid;
+    grid-template-columns: 28px minmax(0, 1fr) 22px;
+    align-items: center;
+    gap: 9px;
+    padding: 7px 8px;
+    cursor: pointer;
+    text-align: left;
+}
+
+.device-row:hover,
+.device-row.active {
+    background: var(--bg-hover);
+    color: var(--text-primary);
+}
+
+.device-row.active {
+    color: var(--accent);
+}
+
+.device-row-icon,
+.device-row-check {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.device-row-icon svg {
+    width: 18px;
+    height: 18px;
+}
+
+.device-row-check svg {
+    width: 16px;
+    height: 16px;
+}
+
+.device-row-main {
+    min-width: 0;
+}
+
+.device-row-name {
+    display: block;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.device-row-name {
+    color: inherit;
+    font-size: 13px;
+    font-weight: 650;
+}
+
+.device-row-current {
+    display: block;
+    margin-top: 2px;
+    color: var(--text-subdued);
+    font-size: 11px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
 /* Loading */
 .loading-spinner {
     display: flex;
@@ -1377,6 +1495,37 @@ button.user-stat:hover {
     margin-bottom: 20px;
 }
 
+.connection-alert {
+    flex: 0 0 auto;
+    min-width: 42px;
+    height: 42px;
+    padding: 0 12px;
+    border: 1px solid rgba(248, 113, 113, 0.34);
+    border-radius: 8px;
+    background: rgba(127, 29, 29, 0.2);
+    color: #f87171;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+}
+
+.connection-alert svg {
+    width: 18px;
+    height: 18px;
+    flex: 0 0 auto;
+}
+
+.connection-alert-text {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: #fecaca;
+    font-size: 12px;
+    font-weight: 700;
+}
+
 /* Search bar */
 .search-bar {
     position: relative;
@@ -2676,6 +2825,15 @@ button.user-stat:hover {
         flex: 1 1 auto;
     }
 
+    .connection-alert {
+        width: 42px;
+        padding: 0;
+    }
+
+    .connection-alert-text {
+        display: none;
+    }
+
     .mobile-library-btn {
         display: flex;
     }
@@ -3186,6 +3344,14 @@ button.user-stat:hover {
         bottom: calc(var(--player-bar-space) + 8px);
     }
 
+    .device-popover {
+        position: fixed;
+        right: 8px;
+        bottom: calc(var(--player-bar-space) + 8px);
+        width: min(280px, calc(100vw - 16px));
+        max-height: 42dvh;
+    }
+
     .player-bar {
         gap: 8px;
         padding-left: 10px;