fix(node): the Music app's tags survive a restart

media_cache held video_meta, photo_meta and thumbs; the audio tags lived
only in the in-memory IndexEntry. So every start re-read every audio file
the node serves, and until that pass landed it served an index with no
artist on any track — one the Music app cannot group. Over a real
6176-file library the pass costs 27.8s cold and 6.4s from audio_meta.

Only what the bytes decided is stored. The filename and folder fallbacks
still run live, or a renamed file would get the old name's answer; the
sibling-cover scan reads the folder, so it stays live too; and a read
that failed is not cached, or one bad read becomes permanent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2 files changed, 129 insertions, 31 deletions

diff --git a/packages/meshbay-node/src/meshbay_node/indexer/enrich_audio.py b/packages/meshbay-node/src/meshbay_node/indexer/enrich_audio.py
index d484e35..dd6b2c0 100644
--- a/packages/meshbay-node/src/meshbay_node/indexer/enrich_audio.py
+++ b/packages/meshbay-node/src/meshbay_node/indexer/enrich_audio.py
@@ -320,16 +320,30 @@ def _read_tags_and_cover(
         tags["title"] = title_parse.strip_track_prefix(tags["title"]) or tags["title"]
 
     if cover is None and not skip_cover:
-        sibling = _find_sibling_cover(path.parent)
-        if sibling is not None:
-            try:
-                cover = sibling.read_bytes()
-            except OSError:
-                cover = None
+        cover = _read_sibling_cover(path)
 
     return tags, duration, cover
 
 
+def _read_sibling_cover(path: Path) -> bytes | None:
+    """
+    The cover image sitting beside the track, as bytes.
+
+    Its own function because it is the one part of the read that depends on the
+    *folder* rather than on the file's bytes: `audio_meta` remembers what the
+    bytes said and lets `AudioEnricher._run` skip opening the file at all, and
+    this still has to run on top of that, or a cover dropped in after the first
+    pass could never be found again. Blocking; called via asyncio.to_thread.
+    """
+    sibling = _find_sibling_cover(path.parent)
+    if sibling is None:
+        return None
+    try:
+        return sibling.read_bytes()
+    except OSError:
+        return None
+
+
 # A folder name used as a last-resort artist/album, cleaned of the
 # punctuation-as-separator and release-tag noise this era of rip is full of
 # (underscores standing in for spaces, a bitrate/quality tag still attached
@@ -450,33 +464,53 @@ class AudioEnricher:
         async with self._sem:
             fields: dict = {}
 
-            # entry.id is the file's own content hash — a cover already
-            # cached under it means this exact content's cover was already
-            # extracted (this run, an earlier one, even a previous daemon
-            # process), so the second file open (embedded APIC/covr scan)
-            # and the sibling-directory disk read are both skippable.
+            # entry.id is the file's own content hash, so everything a read of
+            # those bytes produced is cacheable under it — the tags, the
+            # duration, and whether the embedded-art scan has already run
+            # (media_cache.audio_meta, plus get_thumb_hash_by_file_id for the
+            # cover itself). With both in hand the file is not opened at all,
+            # which is the whole point: this pass used to re-read every audio
+            # file on the node at every start, and until it landed the index
+            # the node served carried no artist on any track.
             #
-            # Tags themselves are *not* skipped this way, deliberately:
-            # unlike a cover, artist/album/title/track_no can fall back to
-            # the filename or the folder name (_artist_album_from_ancestors
-            # above) when no tag is present, which is exactly what a rename
-            # needs re-derived — _reenrich_renamed_audio_entries exists for
-            # precisely that. Caching the *result* the same way enrich.py's
-            # duration/width/height is cached doesn't apply cleanly here:
-            # mutagen reads tags and duration in the same call as cover, so
-            # skipping that call to save time would also skip the
-            # rename-sensitive fields, and skipping only the parts that are
-            # safe to skip needs the cover check below, not a separate
-            # cache of the tag-derived fields.
+            # What is *not* cached, and must not be: the fallbacks below.
+            # artist/album/title/track_no can come from the filename or the
+            # folder name (_artist_album_from_ancestors above) when no tag is
+            # present, and those a rename has to re-derive —
+            # _reenrich_renamed_audio_entries exists for precisely that. The
+            # raw tag is not rename-sensitive, so the tag is what is stored and
+            # the chain still runs live on top of it. The sibling-image scan is
+            # the other one: it reads the folder, not the file, so a cover
+            # dropped in afterwards must still be found.
             cached_thumb_hash = await self._media_cache.get_thumb_hash_by_file_id(entry.id)
-            try:
-                tags, duration, cover = await asyncio.wait_for(
-                    asyncio.to_thread(
-                        _read_tags_and_cover, file_path, skip_cover=bool(cached_thumb_hash)),
-                    timeout=READ_TIMEOUT_SECS)
-            except Exception as e:
-                log.warning("Tag read failed for %s: %s", file_path, e)
-                tags, duration, cover = {}, None, None
+            cached = await self._media_cache.get_audio_meta(entry.id)
+            cover_settled = bool(cached_thumb_hash) or bool(cached and cached["cover_seen"])
+            if cached and cover_settled:
+                tags = {k: cached[k] for k in ("title", "artist", "album", "track_no")
+                        if cached[k] is not None}
+                duration = cached["duration"]
+                cover = None if cached_thumb_hash else await asyncio.to_thread(
+                    _read_sibling_cover, file_path)
+            else:
+                try:
+                    tags, duration, cover = await asyncio.wait_for(
+                        asyncio.to_thread(
+                            _read_tags_and_cover, file_path, skip_cover=bool(cached_thumb_hash)),
+                        timeout=READ_TIMEOUT_SECS)
+                except Exception as e:
+                    # Not cached. A file that genuinely carries no tags reads
+                    # fine and returns an empty dict, which is an answer worth
+                    # keeping; this is a drive that did not answer, and writing
+                    # "says nothing" for it would make one bad read permanent.
+                    log.warning("Tag read failed for %s: %s", file_path, e)
+                    tags, duration, cover = {}, None, None
+                else:
+                    # `cover_seen` is false when the scan was skipped, so a file
+                    # whose cover was cached and has since been evicted is
+                    # looked at again rather than left without one for good.
+                    await self._media_cache.put_audio_meta(
+                        entry.id, tags, int(duration) if duration else None,
+                        cover_seen=not cached_thumb_hash)
 
             if duration:
                 fields["duration"] = int(duration)
diff --git a/packages/meshbay-node/src/meshbay_node/media_cache.py b/packages/meshbay-node/src/meshbay_node/media_cache.py
index 9dfdf73..9c692ca 100644
--- a/packages/meshbay-node/src/meshbay_node/media_cache.py
+++ b/packages/meshbay-node/src/meshbay_node/media_cache.py
@@ -107,6 +107,40 @@ CREATE TABLE IF NOT EXISTS mbid_meta (
 -- hit had already proven unnecessary. thumb_hash is not duplicated here —
 -- get_thumb_hash_by_file_id(file_id) already answers that, and a second copy
 -- would just be one more place for the two to drift.
+-- Music app (docs/MESHBAY_DESIGN.md §9.8): what a read of the file's own bytes
+-- produced. Music was the one app whose index-time enrichment survived
+-- nothing: `video_meta` and `photo_meta` are here, `thumbs` is here, and
+-- artist/album/track_no/title lived only in the in-memory IndexEntry. So every
+-- node start re-read the tags of every audio file it serves, and until that
+-- pass landed the index it served carried no artist on any track — which is an
+-- index the Music app cannot group, and looks from the outside like a tab that
+-- lost its content. Measured over a real 6176-file library: the pass costs
+-- 27.8s with nothing cached and 6.4s with this table populated. It does not
+-- make the node's start-up window vanish — video enrichment and re-sealing an
+-- 8845-entry index dominate that — it makes the artist and the album come back
+-- in seconds rather than in tens of them.
+--
+-- Only what the bytes decide, for the reason video_meta states: `display_title`
+-- and `track_no` as the app finally sees them can also come from the *filename*
+-- (title_parse, and _artist_album_from_ancestors for artist/album), and a
+-- rename has to re-derive those — _reenrich_renamed_audio_entries exists for
+-- it. The raw tag is not rename-sensitive, so it is what is stored, and the
+-- fallback chain still runs live on top of it.
+--
+-- `cover_seen` records that the *embedded* art scan ran for this content;
+-- combined with get_thumb_hash_by_file_id it says whether the file has to be
+-- opened again at all. The sibling-image scan is deliberately not covered by
+-- it — that one reads the *folder*, so a cover dropped in later must still be
+-- found, and it costs 0.8s across the same library.
+CREATE TABLE IF NOT EXISTS audio_meta (
+    file_id     TEXT PRIMARY KEY,
+    title       TEXT,
+    artist      TEXT,
+    album       TEXT,
+    track_no    INTEGER,
+    duration    INTEGER,
+    cover_seen  INTEGER NOT NULL DEFAULT 0
+);
 CREATE TABLE IF NOT EXISTS photo_meta (
     file_id     TEXT PRIMARY KEY,
     width       INTEGER,
@@ -460,6 +494,34 @@ class MediaCache:
         )
         await self._db.commit()
 
+    # ── audio tags (Music app) ───────────────────────────────────────────────
+    #
+    # The tag as read, never the field as the app finally sees it — see the
+    # schema comment on why the filename-derived half stays out.
+
+    async def get_audio_meta(self, file_id: str) -> dict | None:
+        async with self._db.execute(
+            "SELECT title, artist, album, track_no, duration, cover_seen "
+            "FROM audio_meta WHERE file_id = ?",
+            (file_id,),
+        ) as cur:
+            row = await cur.fetchone()
+        if not row:
+            return None
+        return {"title": row[0], "artist": row[1], "album": row[2],
+                "track_no": row[3], "duration": row[4], "cover_seen": bool(row[5])}
+
+    async def put_audio_meta(self, file_id: str, tags: dict, duration: int | None,
+                             cover_seen: bool) -> None:
+        await self._db.execute(
+            "INSERT OR REPLACE INTO audio_meta "
+            "(file_id, title, artist, album, track_no, duration, cover_seen) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (file_id, tags.get("title"), tags.get("artist"), tags.get("album"),
+             tags.get("track_no"), duration, 1 if cover_seen else 0),
+        )
+        await self._db.commit()
+
     # ── video technical fields (Videos app) ──────────────────────────────────
     #
     # duration/width/height only — see the schema comment on why
@@ -498,6 +560,8 @@ class MediaCache:
         await self._db.execute("DELETE FROM thumbs WHERE file_id = ?", (file_id,))
         await self._db.execute("DELETE FROM photo_meta WHERE file_id = ?", (file_id,))
         await self._db.execute("DELETE FROM video_meta WHERE file_id = ?", (file_id,))
+        await self._db.execute(
+            "DELETE FROM audio_meta WHERE file_id = ?", (file_id,))
         await self._db.execute("DELETE FROM file_tmdb WHERE file_id = ?", (file_id,))
         await self._db.execute("DELETE FROM tmdb_override WHERE file_id = ?", (file_id,))
         await self._db.execute("DELETE FROM file_mbid WHERE file_id = ?", (file_id,))