fix(worker): a corrupt/unreadable album no longer aborts the whole scan

Live-testing #9 surfaced a pre-existing gap: one truncated file mutagen chokes
on ("file said 4 bytes, read 0 bytes") raised out of _process_album and aborted
the entire library scan (worklist abandoned). Now scan_chunk catches a per-album
error, rolls back, logs it, counts it as skipped, marks the item done, and
continues — so a single bad file can't block the rest of the library.

worker tests: new case asserts a corrupt album is skipped while a good one still
imports (and captures its on-disk trackNames).

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

web/prisma/migrations/20260714104932_add_library_track_names/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "LibraryItem" ADD COLUMN     "trackNames" TEXT[] DEFAULT ARRAY[]::TEXT[];

web/prisma/schema.prisma

@@ -82,6 +82,11 @@ model LibraryItem {
   format       String
   qualityClass Int
   importedAt   DateTime @default(now())
+  // The album's on-disk audio filenames ("## Title.ext"), captured at import + scan, so the
+  // Library modal can show the REAL tracks on disk (revealing incomplete/edition mismatches)
+  // instead of MusicBrainz's canonical listing. Empty for items imported before this existed
+  // (re-scan to populate).
+  trackNames   String[] @default([])
 
   @@unique([artist, album])
 }

web/src/app/_ui/album-modal.tsx

@@ -25,8 +25,20 @@ export type AlbumInfo = {
   type?: string | null;
   /** When present, the modal shows a Follow button + links the artist name to their page. */
   artistMbid?: string | null;
+  /** Real on-disk audio filenames (Library items). When present, the modal shows THESE —
+   *  revealing incomplete downloads / edition mismatches — instead of MusicBrainz's listing. */
+  trackNames?: string[] | null;
 };
 
+/** Parse on-disk "## Title.ext" filenames into display tracks (sorted order = position). */
+function parseOnDisk(names: string[]): Track[] {
+  return names.map((name, i) => {
+    const stem = name.replace(/\.[^.]+$/, ""); // drop extension
+    const title = stem.replace(/^\s*\d+(?:[-.\s]+\d+)?[\s._-]+/, "").trim() || stem; // drop leading NN / N-NN
+    return { position: i + 1, title, lengthMs: null };
+  });
+}
+
 /** Reusable album modal: cover art + tracklist (fetched from MB by release-group MBID) with
  *  slots for a status chip and context-specific action buttons. */
 export function AlbumModal({
@@ -43,6 +55,7 @@ export function AlbumModal({
   actions?: ReactNode;
 }) {
   const [tracks, setTracks] = useState<Track[] | "loading" | "error">("loading");
+  const onDisk = (album.trackNames?.length ?? 0) > 0;
   // null = unknown/loading; only meaningful when album.artistMbid is set.
   const [followed, setFollowed] = useState<boolean | null>(null);
 
@@ -100,6 +113,11 @@ export function AlbumModal({
 
   useEffect(() => {
     if (!open) return;
+    // Prefer the REAL on-disk tracks (Library items) — no network, and reveals mismatches.
+    if (album.trackNames?.length) {
+      setTracks(parseOnDisk(album.trackNames));
+      return;
+    }
     const rgMbid = album.rgMbid;
     if (!rgMbid) {
       setTracks("error");
@@ -145,8 +163,15 @@ export function AlbumModal({
         </div>
       </div>
       <div className="album-modal-tracks">
+        {Array.isArray(tracks) ? (
+          <p className="tracks-source">
+            {onDisk ? `On disk · ${tracks.length} tracks` : "MusicBrainz tracklist"}
+          </p>
+        ) : null}
         {tracks === "loading" ? <p className="muted-note">Loading tracks…</p> : null}
-        {tracks === "error" ? <p className="muted-note">No tracklist available.</p> : null}
+        {tracks === "error" ? (
+          <p className="muted-note">No tracklist available.</p>
+        ) : null}
         {Array.isArray(tracks) ? (
           <ol className="tracks">
             {tracks.map((t) => (

web/src/app/design.css

@@ -200,6 +200,10 @@ nav.contents .sep { flex: 1; }
 .modal-artist { display: inline-flex; align-items: center; gap: 12px; flex-wrap: wrap; }
 .modal-artist a { color: inherit; text-decoration: none; border-bottom: 1.5px solid var(--rule-2); }
 .modal-artist a:hover { border-bottom-color: var(--accent); color: var(--accent); }
+.tracks-source {
+  font-family: var(--mono); font-size: 0.62rem; letter-spacing: 0.14em; text-transform: uppercase;
+  color: var(--graphite); margin: 0 0 10px;
+}
 
 /* ── Phase 2: page headers, list rows, tools ──────────── */
 .page-head { margin: 6px 0 26px; }

web/src/app/library/library-client.tsx

@@ -16,6 +16,7 @@ type Album = {
   year: string | null;
   primaryType: string | null;
   artistMbid: string | null;
+  trackNames: string[];
 };
 
 export function LibraryClient() {
@@ -75,7 +76,7 @@ export function LibraryClient() {
         <AlbumModal
           open
           onClose={() => setOpen(null)}
-          album={{ rgMbid: open.rgMbid, album: open.album, artist: open.artist, year: open.year, type: open.primaryType, artistMbid: open.artistMbid }}
+          album={{ rgMbid: open.rgMbid, album: open.album, artist: open.artist, year: open.year, type: open.primaryType, artistMbid: open.artistMbid, trackNames: open.trackNames }}
           status={<span className="chip done">In library · {open.format}</span>}
         />
       ) : null}

worker/lyra_worker/library.py

@@ -26,6 +26,20 @@ _COVER_STEMS = {"cover", "folder", "front"}
 _COVER_EXT = {".jpg", ".jpeg", ".png"}
 
 
+def list_audio_files(folder: str) -> list[str]:
+    """The album's on-disk audio filenames (basenames, sorted) — captured into
+    LibraryItem.trackNames so the UI can show the real tracks on disk. Top-level only
+    (albums are one flat folder here); returns [] if the folder is missing/unreadable."""
+    try:
+        names = [
+            n for n in os.listdir(folder)
+            if os.path.isfile(os.path.join(folder, n)) and os.path.splitext(n)[1].lower() in _AUDIO_EXT
+        ]
+    except OSError:
+        return []
+    return sorted(names)
+
+
 def staging_dir(staging_root: str, job_id: str) -> str:
     """A per-job download staging directory under `staging_root`. The staging root may be a
     volume separate from the library (e.g. local disk while the library is an SMB share):

worker/lyra_worker/pipeline.py

@@ -9,7 +9,7 @@ import psycopg
 
 from lyra_worker.adapters.base import SourceAdapter
 from lyra_worker.confidence import score_confidence
-from lyra_worker.library import album_dir, import_album, staging_dir
+from lyra_worker.library import album_dir, import_album, list_audio_files, staging_dir
 from lyra_worker.quality import quality_class
 from lyra_worker.ranker import rank_candidates
 from lyra_worker.types import Candidate, MBTarget
@@ -186,18 +186,19 @@ def _mark_chosen(conn: psycopg.Connection, job_id: str, source_ref: str) -> None
 def _import(conn: psycopg.Connection, job_id: str, target: MBTarget,
             winner: Candidate, path: str) -> None:
     request_id = _request_id(conn, job_id)
+    track_names = list_audio_files(path)  # the real files just imported into the album folder
     with conn.cursor() as cur:
         cur.execute(
             'INSERT INTO "LibraryItem" (id, "requestId", artist, album, path, source, '
-            'format, "qualityClass", "importedAt") '
-            "VALUES (gen_random_uuid()::text, %s, %s, %s, %s, %s, %s, %s, now()) "
+            'format, "qualityClass", "trackNames", "importedAt") '
+            "VALUES (gen_random_uuid()::text, %s, %s, %s, %s, %s, %s, %s, %s, now()) "
             'ON CONFLICT (artist, album) DO UPDATE SET '
             '  "requestId" = EXCLUDED."requestId", path = EXCLUDED.path, source = EXCLUDED.source, '
             '  format = EXCLUDED.format, "qualityClass" = EXCLUDED."qualityClass", '
-            '  "importedAt" = now() '
+            '  "trackNames" = EXCLUDED."trackNames", "importedAt" = now() '
             'WHERE EXCLUDED."qualityClass" > "LibraryItem"."qualityClass"',
             (request_id, target.artist, target.album, path, winner.source,
-             winner.quality.fmt, quality_class(winner.quality)),
+             winner.quality.fmt, quality_class(winner.quality), track_names),
         )
         cur.execute(
             "UPDATE \"Request\" SET status = 'completed' WHERE id = %s", (request_id,)

worker/lyra_worker/scan.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 
 import psycopg
 
+from lyra_worker.library import list_audio_files
 from lyra_worker.probe import AudioProbe
 
 _AUDIO_EXT = {".flac", ".mp3", ".m4a", ".opus", ".ogg", ".aac", ".wav"}
@@ -80,14 +81,18 @@ def _record_owned(conn, target, quality_class: int, fmt: str, path: str, watched
                 '  "watchedArtistId" = COALESCE("MonitoredRelease"."watchedArtistId", EXCLUDED."watchedArtistId")',
                 (watched_id, target.artist_mbid, target.artist, target.rg_mbid, target.album, quality_class),
             )
+        track_names = list_audio_files(path)  # capture the real on-disk tracks
         cur.execute(
             'INSERT INTO "LibraryItem" (id, "requestId", artist, album, path, source, format, '
-            '"qualityClass", "importedAt") '
-            "VALUES (gen_random_uuid()::text, NULL, %s, %s, %s, 'scan', %s, %s, now()) "
-            'ON CONFLICT (artist, album) DO NOTHING',
-            (target.artist, target.album, path, fmt, quality_class),
+            '"qualityClass", "trackNames", "importedAt") '
+            "VALUES (gen_random_uuid()::text, NULL, %s, %s, %s, 'scan', %s, %s, %s, now()) "
+            # refresh trackNames on re-scan (populates items imported before this column);
+            # xmax=0 ⇒ this was an INSERT (a genuinely new library item) vs an UPDATE.
+            'ON CONFLICT (artist, album) DO UPDATE SET "trackNames" = EXCLUDED."trackNames" '
+            "RETURNING (xmax = 0) AS inserted",
+            (target.artist, target.album, path, fmt, quality_class, track_names),
         )
-        newly = cur.rowcount == 1  # a new LibraryItem means this album wasn't recorded before
+        newly = cur.fetchone()[0]  # a new LibraryItem means this album wasn't recorded before
     conn.commit()
     return newly
 
@@ -164,7 +169,17 @@ def scan_chunk(conn: psycopg.Connection, resolver, probe: AudioProbe, browser,
     imported = skipped = 0
     browsed: set[str] = set()  # artists whose discography we've populated this chunk
     for item_id, artist_name, album_folder, album_path in items:
-        outcome = _process_album(conn, resolver, probe, browser, artist_name, album_folder, album_path, browsed)
+        try:
+            outcome = _process_album(conn, resolver, probe, browser, artist_name, album_folder, album_path, browsed)
+        except Exception as e:
+            # a single unreadable/corrupt album (e.g. a truncated file mutagen chokes on) must
+            # not abort the whole scan — skip it, mark it done, and keep going.
+            try:
+                conn.rollback()
+            except Exception:
+                pass
+            print(f"scan: skipping {artist_name}/{album_folder}: {e}", flush=True)
+            outcome = "skipped"
         if outcome == "imported":
             imported += 1
         elif outcome == "skipped":

worker/tests/test_list_audio_files.py

@@ -0,0 +1,20 @@
+from lyra_worker.library import list_audio_files
+
+
+def test_lists_sorted_audio_basenames_only(tmp_path):
+    (tmp_path / "02 Two.flac").write_bytes(b"")
+    (tmp_path / "01 One.flac").write_bytes(b"")
+    (tmp_path / "10 Ten.mp3").write_bytes(b"")
+    (tmp_path / "cover.jpg").write_bytes(b"")       # non-audio excluded
+    (tmp_path / "notes.txt").write_bytes(b"")       # non-audio excluded
+    (tmp_path / "Disc 1").mkdir()                    # a subdir is not a file
+
+    assert list_audio_files(str(tmp_path)) == ["01 One.flac", "02 Two.flac", "10 Ten.mp3"]
+
+
+def test_missing_dir_returns_empty():
+    assert list_audio_files("/no/such/album/dir") == []
+
+
+def test_empty_dir_returns_empty(tmp_path):
+    assert list_audio_files(str(tmp_path)) == []

worker/tests/test_scan.py

@@ -59,6 +59,29 @@ def test_scan_records_have_monitored_and_follows_artist(conn, tmp_path):
         assert cur.fetchone()[0] is False
 
 
+def test_scan_skips_a_corrupt_album_and_captures_tracknames(conn, tmp_path):
+    _album(tmp_path, "Good Artist", "Good Album (2020)", files=("01 One.flac", "02 Two.flac"))
+    _album(tmp_path, "Bad Artist", "Bad Album (2020)")
+
+    class RaisingProbe:
+        def probe(self, path):
+            if "Bad Artist" in path:  # a truncated/corrupt file mutagen chokes on
+                raise RuntimeError("file said 4 bytes, read 0 bytes")
+            return ProbeResult(artist="", album="", fmt="FLAC", quality_class=3)
+
+    resolver = FakeResolver({
+        ("Good Artist", "Good Album"): MBTarget(
+            artist="Good Artist", album="Good Album", year=2020, rg_mbid="rgG", artist_mbid="aG"),
+    })
+    result = scan_library(conn, resolver, RaisingProbe(), FakeMbBrowser(), dest_root=str(tmp_path))
+
+    # the corrupt album is skipped, the good one still imports — the scan completes, not aborts
+    assert (result.imported, result.skipped) == (1, 1)
+    with conn.cursor() as cur:
+        cur.execute('SELECT "trackNames" FROM "LibraryItem" WHERE artist=%s', ("Good Artist",))
+        assert cur.fetchone()[0] == ["01 One.flac", "02 Two.flac"]  # on-disk tracks captured at scan
+
+
 def test_scan_skips_unmatched_albums(conn, tmp_path):
     _album(tmp_path, "Obscure", "Nope (1999)")
     result = scan_library(conn, FakeResolver({}), FakeProbe(), FakeMbBrowser(), dest_root=str(tmp_path))