docs(android): the identity is read back, not declared twice

android-tier.md carried a warning block telling the reader not to use
run:device or deploy-device, and offered a manual sequence instead.
Both are wrong now: the tasks are the way in, and the warning would
read as a live hazard. It becomes a note about what changed, and the
manual sequence stays as the smallest thing that works when you want no
script between you and adb.

"The identity is declared twice" was the section this file had carried
for five phases saying nothing enforced that the two ids agree. It
describes the enforcement now, plus what APP_ID means since it stopped
being a setting it never was.

NOTES.md takes the four measurements: that the uninstall existed only
to cover a missing -r (which is what makes deleting it a fix rather
than a trade), that the emulator tasks installed on a phone, what
reading the id back costs, and the boot-wait race filed as #162.

.gitea/workflows/android-apk.yml

@@ -139,6 +139,23 @@ jobs:
             echo "skip=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+
+          # Nor is a prerelease, and this trigger is `v*`, which matches
+          # `v0.4.0-beta.1`.  Two reasons it is worst here.  The APK goes
+          # to the *generic* registry, which is readable without
+          # credentials so Obtainium can poll a plain URL — a beta would
+          # be offered to every device on it.  And the versionCode maths
+          # below splits on dots and would read "1" out of "0-beta",
+          # producing a code that is wrong rather than a build that
+          # fails: Android orders releases by that integer and refuses
+          # anything not greater than what is installed.
+          case "$v" in
+            *-*)
+              echo "v$v is a prerelease; not publishing an APK for it"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
           echo "skip=false" >> "$GITHUB_OUTPUT"
 
           # Android orders releases by an integer and refuses anything

.gitea/workflows/arch-package.yml

@@ -72,6 +72,22 @@ jobs:
             exit 0
           fi
 
+          # A prerelease is not a shipment either, and this trigger is
+          # `v*` — which matches `v0.4.0-beta.1`.  Nothing produces one
+          # today; the guard is here because the thing that would is
+          # semantic-release's `prerelease: true` channel, a one-line
+          # change in .releaserc.yml whose blast radius is four public
+          # package channels.  Same argument as release.yml's
+          # `chore(release):` guard: cheap, against something a future
+          # edit turns on somewhere else entirely.
+          case "$v" in
+            *-*)
+              echo "$v is a prerelease; not packaging it for pacman"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
+
           echo "skip=false" >> "$GITHUB_OUTPUT"
           echo "tag=$v"     >> "$GITHUB_OUTPUT"
           echo "building $v"

.gitea/workflows/desktop-assets.yml

@@ -95,6 +95,19 @@ jobs:
             exit 0
           fi
 
+          # Nor is a prerelease, and this trigger is `v*`, which matches
+          # `v0.4.0-beta.1`.  The mildest of the four — assets attach to
+          # the prerelease's own Gitea release and no package manager
+          # reads them — but four workflows sharing one trigger should
+          # share one answer about what a shipment is.
+          case "$v" in
+            *-*)
+              echo "$v is a prerelease; not attaching desktop assets"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
+
           echo "skip=false"   >> "$GITHUB_OUTPUT"
           echo "tag=$v"       >> "$GITHUB_OUTPUT"
           echo "version=${v#v}" >> "$GITHUB_OUTPUT"

.gitea/workflows/homebrew-formula.yml

@@ -56,6 +56,18 @@ jobs:
             echo "skip=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+
+          # Nor is a prerelease, and this trigger is `v*`, which matches
+          # `v0.4.0-beta.1`.  It matters most here of the four: the tap
+          # is public, and `brew upgrade` would offer a beta to everyone
+          # on it.
+          case "$VERSION" in
+            *-*)
+              echo "$TAG is a prerelease; not syncing it to a public tap"
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
           echo "skip=false" >> "$GITHUB_OUTPUT"
 
           TARBALL="${SOURCE_TARBALL_BASE}/${TAG}.tar.gz"

.gitea/workflows/release.yml

@@ -1,11 +1,36 @@
 name: Release
 
 # The sixth workflow, and the one that decides whether the other three
-# run at all.  On every push to main it reads the Conventional Commits
-# since the last tag, and if any of them is releasable it writes the
-# changelog, pushes the tag, and creates the Gitea release whose body is
-# that changelog section.  The publishing workflows are keyed on `v*`, so
-# the tag push is what starts them.
+# run at all.  It reads the Conventional Commits since the last tag, and
+# if any of them is releasable it writes the changelog, pushes the tag,
+# and creates the Gitea release whose body is that changelog section.
+# The publishing workflows are keyed on `v*`, so the tag push is what
+# starts them.
+#
+# **It is triggered by hand, and there is deliberately no `push`
+# trigger.**  There was one, on `main`, which made the trigger "a PR was
+# merged" and nothing else: eight releases in twenty-two hours
+# (v0.0.1 -> v0.3.1) for one session's work, each fanning out to four
+# publishers on a runner with capacity 1, so ~40 packaging jobs shipped
+# three issues and ordinary PR CI queued behind them.  A version per
+# merged PR is a version per unit of *work*, not per *shipment*, and
+# pacman, Homebrew and Obtainium see every one.
+#
+# Nothing else had to change to batch them: semantic-release already
+# reads every commit since the last tag, so five fixes and two feats
+# become one minor release with all seven in the notes.  Release
+# frequency was only ever how often this file fired.
+#
+# This is the rule `index-artifact.yml` states and is the other instance
+# of: **a job that mutates state which cannot be rebuilt in ten minutes
+# is triggered deliberately, not by a push.**  A release here is a tag,
+# a Gitea release, an Arch package, a Homebrew formula, a signed APK and
+# desktop assets — and an Android version going backwards costs the user
+# their library (docs/android-release.md).
+#
+# A schedule was considered and rejected: a cron batches without anyone
+# having to remember, but it puts the decision back on a timer, which is
+# the thing being removed.
 #
 # **Why the tag is pushed with PACKAGE_TOKEN and not the Actions token.**
 # Gitea, like GitHub, does not start a workflow from a ref pushed by a
@@ -19,9 +44,12 @@ name: Release
 # instead.
 
 on:
-  push:
-    branches: [main]
   workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Report what would be released and stop"
+        required: false
+        default: "false"
 
 # Cutting a tag is not a thing to cancel halfway: a superseded run must
 # finish, not be killed between `git push --tags` and the release POST.
@@ -163,14 +191,32 @@ jobs:
       # been right, the tag would have been right, every job would have
       # been green, and the release body would have been empty.  Check the
       # notes, not the exit code, before moving any of these.
+      # The point of a manual trigger is deliberateness, and deliberate
+      # means being able to look before pulling the lever.  `--dry-run`
+      # reports the version and the notes and writes nothing: no tag, no
+      # release, no publishers.  `make release-dry` is the same answer
+      # locally; this is it from the runner, against the same commit and
+      # the same tag history, which is what actually decides.
       - name: Run semantic-release
         if: steps.guard.outputs.skip == 'false'
         working-directory: /src
+        env:
+          DRY_RUN: ${{ inputs.dry_run }}
         run: |
           set -eu
           git config user.name  "yellowjacket-ci"
           git config user.email "yj@yellowjacket.app"
 
+          # Anything but a literal "true" releases for real.  A typo in a
+          # dispatch box must not silently turn a shipment into a no-op
+          # that reports success — the failure worth avoiding is the one
+          # where nothing happens and the run is green.
+          dry=""
+          if [ "${DRY_RUN:-false}" = "true" ]; then
+            echo "DRY RUN — no tag will be pushed and no release created"
+            dry="--dry-run"
+          fi
+
           npx --yes \
             -p semantic-release@25 \
             -p @semantic-release/commit-analyzer@13 \
@@ -178,5 +224,5 @@ jobs:
             -p @semantic-release/changelog@7 \
             -p @semantic-release/exec@7 \
             -p conventional-changelog-conventionalcommits@9 \
-            semantic-release \
+            semantic-release $dry \
               --repository-url "https://x-access-token:${PACKAGE_TOKEN}@${SERVER_URL#https://}/${REPO}.git"

.gitea/workflows/unclaim.yml

@@ -0,0 +1,107 @@
+name: Unclaim
+
+# A `Closes #N` footer in a commit body closes the issue on merge — and
+# leaves `Status/In Progress` on it, because Gitea's auto-close touches
+# state and nothing else.  So #100 was closed and simultaneously marked
+# as being actively worked on, and `scripts/issue.sh close` (which does
+# drop the label) is exactly the thing the footer exists to avoid
+# calling.
+#
+# **This hooks the close, not the merge.**  Stripping the label in the
+# PR would work and would be a per-PR habit; habits are what the footer
+# removed.  `issues: [closed]` covers every path an issue can close by —
+# the footer on merge, `issue.sh close`, someone clicking Close in the
+# web UI — and asks nothing of anyone at any of them.
+#
+# **Reopening deliberately does not restore it.**  Reopening says the
+# work was not finished, not that somebody is at a keyboard doing it
+# now; the claim gets re-made by whoever picks it up.
+#
+# **This is not instant, and should not be described as it.**  The
+# runner has capacity 1 and is shared with an index build that can hold
+# it for three hours, so a label tweak can queue behind one. Stale for
+# an afternoon beats stale forever, which is what it was.
+#
+# The audit that answers "is this still firing" stays in CLAUDE.md and
+# is one command:
+#
+#   ./scripts/issue.sh list --state closed --label "Status/In Progress"
+#
+# A workflow that silently stops working is the failure mode this whole
+# area has already produced once.
+
+on:
+  issues:
+    types: [closed]
+
+jobs:
+  unclaim:
+    runs-on: ubuntu-latest
+    container:
+      image: ubuntu:24.04
+
+    steps:
+      - name: Drop the claim label
+        # **Inside a container the act runner selects `sh`, not bash**, so
+        # `set -o pipefail` fails the job on its second line with "Illegal
+        # option" and the step never reaches the API.  `homebrew-formula.yml`
+        # carries the same `set -euo pipefail` without trouble because it
+        # runs with **no container**, on the host image where bash is the
+        # default — so "another workflow does it" is not evidence here.
+        shell: bash
+        env:
+          # The automatic Actions token, as release.yml uses for the
+          # floor tag.  It needs no more than write access to this repo.
+          TOKEN: ${{ secrets.GITEA_TOKEN }}
+          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          ISSUE: ${{ github.event.issue.number }}
+        run: |
+          set -euo pipefail
+
+          # `ca-certificates` is named because `--no-install-recommends`
+          # skips it, and `ubuntu:24.04` ships no CA bundle of its own —
+          # so curl comes up unable to verify TLS against our own Gitea
+          # and fails with "error setting certificate file" (exit 77).
+          # Every other containerised workflow here spells it out for the
+          # same reason; this one did not, and cost a release cycle.
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends \
+            ca-certificates curl jq >/dev/null
+
+          label_id=$(
+            curl -sSf -H "Authorization: token $TOKEN" "$API/labels?limit=100" |
+              jq -r '.[] | select(.name == "Status/In Progress") | .id'
+          )
+
+          # The label not existing is a repo somebody reorganised, not a
+          # failure of this run — say so and stop, rather than failing a
+          # job on every close from then on.
+          if [ -z "$label_id" ]; then
+            echo "unclaim: no 'Status/In Progress' label in this repo; nothing to do"
+            exit 0
+          fi
+
+          # DELETE is idempotent here: an issue that never carried the
+          # label answers the same as one that did, which is what makes
+          # this safe to run on *every* close rather than only the ones
+          # that were claimed.
+          # The body is captured, not discarded, so a refusal is
+          # diagnosable from this log alone.  Whether the automatic
+          # token carries issue-write scope is still unproven, and
+          # "DELETE returned 403" without Gitea's own sentence costs
+          # another merge to find out which of the two it is.
+          body=$(mktemp)
+          code=$(
+            curl -sS -o "$body" -w '%{http_code}' -X DELETE \
+              -H "Authorization: token $TOKEN" \
+              "$API/issues/$ISSUE/labels/$label_id"
+          )
+
+          case "$code" in
+            204) echo "unclaim: #$ISSUE is closed and unclaimed" ;;
+            *)
+              echo "unclaim: DELETE returned $code for #$ISSUE" >&2
+              cat "$body" >&2
+              exit 1
+              ;;
+          esac

.pi/journal.md

@@ -1,118 +0,0 @@
-# Work log
-
-Temporal memory: what happened and what's next. Structure lives in
-`CLAUDE.md`, operational instructions in `.pi/skills/yellowjacket-dev/`,
-measured discoveries in `.planning/NOTES.md`. Don't duplicate those here.
-
-## Current state
-
-Plan 005 (agent development harness) is **complete — all seven
-phases**. Everything from phase 1 onward is still **uncommitted**: one
-large but coherent working-tree diff, nothing pushed.
-
-All four tiers verified green from a cold, cleaned state:
-`make ui-test` 313 passed, `make lint` 0 issues × 3 configurations,
-`make test` green × 3 passes, `make e2e` 19 passed. Both CI jobs
-verified green in a bare `ubuntu:24.04` container, including 19/19 on
-WebKit.
-
-**Committed and pushed** as `5ca6cad` (the harness) + `ccacd67` (a CI
-fix), and **green on the real runner**: job `check` ~4 min, job `e2e`
-~3 min with 19/19 chromium *and* 19/19 webkit. One commit rather than
-seven because the working tree was the end state, not per-phase
-snapshots — `Makefile`, `CLAUDE.md` and `lefthook.yml` are touched by
-nearly every phase, so a split would have been fabricated history.
-
-Still unverified, because no run has failed yet: the
-`actions/upload-artifact` step (`continue-on-error`, so it cannot mask
-a real failure) and whether pnpm honours `npm_config_store_dir` for
-store caching. Worth checking the next time a spec legitimately fails.
-
-- [ ] `gitea_ci`'s `job_logs` returns 404 on Gitea 1.27.1 — the endpoint
-      is not exposed. Logs come from the VPS instead: `zstdcat` the file
-      under `gitea/actions_log/<owner>/<repo>/<xx>/<task_id>.log.zst`,
-      and note `zstdcat` is not in the gitea container, so
-      `docker cp` it out first. Job status is `action_run_job.status`
-      (1 success, 2 failure, 4 skipped, 5 waiting, 6 running).
-      Probably belongs in the `gitea` skill, not here.
-
-Open items deliberately not fixed: WAV tags are write-only
-(`TestWAVTagsAreNotReadableYet`), `themeStore.loadFromBackend`'s failure
-handler cannot recover, `backend/playlist` has no CRUD suite.
-
-## Log
-
-### 2026-08-11 — cold skill run, then phase 7 (CI)
-
-- **Followed the skill cold first**, as the last session asked. It
-  works: app up from a wiped `.dev/`, an undocumented flow driven
-  (queue panel + shuffle, asserted on `QueueModeChanged`), stopped —
-  ~1 minute, no dead ends. One real config bug: `outputDir` in
-  `.playwright/cli.config.json` resolves against **cwd**, not the
-  config file's directory (only `initScript` does that), so snapshots
-  were landing above the repo and a *stale* one from the previous
-  session answered `ls -t` instead. That cost a DOM walk to disprove a
-  regression that did not exist. Four smaller doc gaps fixed
-  (`sandbox-seed` already runs `testdata`; `ui-setup`/`e2e-setup` were
-  undocumented prerequisites; `snapshot` prints a path; `dev-stop`
-  leaves the browser open), plus `dev-headless.sh`'s own banner, which
-  was suggesting the bare `window.go` call its next paragraph warns
-  against.
-- **Built both CI jobs as container scripts before writing any YAML**,
-  then transcribed the YAML back out and re-ran it to prove the
-  transcription. Push-and-see is a bad loop on a self-hosted runner.
-- **It found a real bug immediately**: `make lint` omitted
-  `webkit2_41` on all three passes, so it was linting configurations
-  nothing builds. Invisible on Arch (which still ships
-  `webkit2gtk-4.0.pc`), fatal on Ubuntu 24.04. Tag sets now match
-  `make test`.
-- **Both open decisions settled by measurement**: ALSA `null` PCM for
-  audio (no daemon; the elapsed clock really advances), dead-address
-  stub for the explore artifact (and setting it for the *app* run, not
-  just seeding, is worth 8x on suite wall clock). **WebKit is a
-  required step** — it had never been run anywhere, so one throwaway
-  container run replaced a coin flip with 19/19 at +11 s.
-
-### 2026-08-10 — phase 6, pi affordances
-
-- Added `.pi/skills/yellowjacket-dev/` as a directory rather than a flat
-  file: only the description is always in context, so `SKILL.md` stays
-  short enough that reading it whole is never a decision, and the deeper
-  material sits in `references/{harness,fixtures,ui-tier,schema-change}.md`.
-- Settled the CLAUDE.md-vs-skill split **grammatically, not topically**,
-  because a topical split is what rots — every new fact gets two
-  plausible homes. Three docs, three tenses: NOTES.md is past
-  (measured, dated, append-only), CLAUDE.md is present (what the system
-  is), the skill is imperative (what to run). A new paragraph's tense
-  decides where it goes.
-- The five gotchas (binding timeouts, first-run wizard, `pkill -f`,
-  seeds-by-running, WebKit-is-CI-only) went **inline in SKILL.md**, not
-  into a reference: you need them before the failure, not after.
-- Trimmed CLAUDE.md's "Fixtures and the headless harness" section by
-  about half — the command sequences and gotchas it was carrying are now
-  the skill's, and leaving both would have created exactly the duplicate
-  description this repo has a standing rule against.
-- Added `make skill-check` / `scripts/skill-check.sh` + a pre-commit
-  hook: every command in `.pi/**/*.md` must be a real `make` target, so
-  the Makefile stays the source of truth for invocation and a renamed
-  target fails a commit instead of misleading an agent later. Verified
-  it fails (it caught its own not-yet-created target) and passes.
-- Added the `/e2e` prompt template: promoting a hand-driven
-  `playwright-cli` session into a spec is a transcription with four
-  fixed substitutions (refs → testids, sleeps → `waitForEvent`, raw
-  `window.go` → `callBinding`, short fixture → `LONG_TRACK`), plus three
-  runs — pass, pass again, pass after a DB restore — because the usual
-  failure is a spec depending on state the hand-driving left behind.
-- One shell trap: under `set -euo pipefail`, `x="$(make -pqRr | …)"`
-  fails the whole assignment, because `make -q` exits non-zero when a
-  target is out of date and `pipefail` propagates it.
-
-### Earlier
-
-Phases 1–5 of plan 005: fixture generator and manifest, headless launch
-and seeds, the event bridge + `data-testid` pass + `backend/testctl` +
-`e2e/`, the Vitest component tier + `make bindings-check`, and the
-`events.Emit` wrapper with its in-process service-event tests. Recaps
-and the five "verified end to end" blocks are in
-`.planning/plans/active/005-agent-development-harness.md`; the lessons
-are in `.planning/NOTES.md`.

.pi/skills/yellowjacket-dev/SKILL.md

@@ -195,6 +195,12 @@ Two rules about climbing:
 - **Do not write an e2e spec first.** Drive the flow by hand, then
   promote it with `/e2e`. Specs written blind assert on selectors that
   do not exist.
+- **Not every view has a nav item.** Since #25 the destinations are
+  configurable, Autotag is hidden by default and Downloads is absent
+  until a download client exists — so `getByTestId('nav-<view>')` waits
+  30 s for a locator that will never resolve. `navigateTo(page, view)`
+  (`e2e/support/fixtures.ts`) dispatches the app's own `navigate` event.
+  Click the nav item when the *nav* is what the spec is about.
 
 Before a commit, the gate is `make lint`, `make test`, `make ui-test`,
 `make bindings-check`, `make css-check` and — from `frontend/` —

.pi/skills/yellowjacket-dev/references/android-tier.md

@@ -194,9 +194,13 @@ like the app's fault and none is:
 |---|---|---|
 | x86_64 | modernc's raw `lstat` vs seccomp | SIGSYS, syscall 6 |
 | arm64, translated | Go reads `ID_AA64ISAR0_EL1` | SIGILL |
-| arm64, real device | — | unverified, still |
+| arm64, real device | **runs** (2026-08-20) | — |
 
-**A physical arm64 device remains the only verification path.**
+**A physical arm64 device remains the only verification path**, and it
+has now been walked: a Light Phone III (TLP301, Android 14 / SDK 34,
+arm64-v8a, WebView Chrome 113 at 424x439). The app builds, installs,
+launches and stays up; `make android-smoke SECONDS=60` passes on it.
+What that run *found* is the lifecycle fault below.
 
 ### What was fixed to get here
 
@@ -210,6 +214,11 @@ no-op. `backend/system` gained no import of the Wails application
 package, which matters for the same reason `backend/events` is split by
 the `indexbuild` tag.
 
+**And `main()` is now latched to one run per process** (#52). That is
+the second `os.Exit(1)` in this file's history and it had the same
+signature as the first, which is the argument for #160: both were named
+exactly by an `slog` line that went to `/dev/null`.
+
 ### What is still not done
 
 The shell is still a desktop shell, and the x86_64 half of the APK is
@@ -249,10 +258,25 @@ one.
 `build/android/Taskfile.yml` ships more than the Makefile wraps, and
 they are the right thing to reach for when you want something one-off:
 
+> **These four were unsafe until #159 and are now the way in.** All of
+> them began with `adb uninstall {{.APP_ID}}`, where `APP_ID` defaulted
+> to `app.yellowjacket` — the **release** id — while `run` and
+> `run:device` build the **debug** variant, whose id is
+> `app.yellowjacket.dev`. So they uninstalled the user's app, taking
+> the library with it, installed a different package, and then failed
+> to launch the one they had removed.
+>
+> They share `scripts/android-deploy.sh` now, which **never**
+> uninstalls (`install -r`, and a changed signing certificate is
+> reported with the command rather than acted on), reads the package id
+> back out of the built APK, and refuses a target that is not the kind
+> the task names. There is nothing left to avoid; the manual sequence
+> below is kept because it is still the smallest thing that works.
+
 ```
 wails3 task android:run              # debug build + emulator install + launch
-wails3 task android:run:device       # same, first connected physical device
-wails3 task android:deploy-device    # production APK to a device
+wails3 task android:run:device       # debug build + install + launch on a phone
+wails3 task android:deploy-device    # release build, same
 wails3 task android:bundle:fat       # AAB, for a Play Store upload
 wails3 task android:studio           # open build/android/ in Android Studio
 wails3 task android:device:list
@@ -260,6 +284,16 @@ wails3 task android:logs:all
 wails3 task android:clean
 ```
 
+**`run` and `deploy-emulator` mean the emulator, and now say so to
+adb.** They used a bare `adb install`, which with exactly one device
+attached picks that device whatever it is — so with a phone plugged in
+and no emulator running, the task whose summary reads "in the Android
+Emulator" installed on the phone. They pass `--target emulator` and
+refuse with `make android-emulator` as the remedy.
+
+**`DEVICE_ID=<serial>` still names a device, and several attached
+devices is now an error rather than a silent pick of the first.**
+
 Two are deliberately **not** wrapped. `android:logs` greps logcat for
 `(Wails|yellowjacket)`, which catches the `WailsBridge` tag but misses
 the app's own process tag (`app.yellowjacket` — lowercase, so `Wails`
@@ -269,16 +303,51 @@ instead. And `ensure-emulator` boots whatever `-list-avds | tail -1`
 returns, with no pidfile and no boot wait, so it cannot be stopped or
 sequenced.
 
-## The identity is declared twice
+## The identity is read back from the APK
 
+It used to be **declared twice**, and that is what #159 was.
 `applicationId` in `build/android/app/build.gradle` is what Gradle
-installs. `APP_ID` in `build/android/Taskfile.yml` is what every
-adb-driven task uninstalls, launches and filters. **Nothing enforces
-that they agree**, and `ANDROID.md`'s advice to set `APP_ID` in
-`build/config.yml` does not work in beta.8 — `wails3 task` never reads
-that file (verified with `--dry`), and even when set it feeds only the
-adb commands, never Gradle. Change both or the official `run`/`deploy`
-tasks address a package that is not installed.
+installs; `APP_ID` in `build/android/Taskfile.yml` was what every
+adb-driven task uninstalled, launched and filtered, and nothing
+enforced that they agree. They did not: the debug buildType carries
+`applicationIdSuffix ".dev"`, so every task that assembles a debug APK
+addressed the release id. This file flagged the hazard for five phases
+and it cashed out twice — once as a wrong `am start`, once as an
+uninstall of the user's library.
+
+**`scripts/android-pkgid.sh` is the one answer now.** It prints the
+package id an APK declares (`aapt2 dump packagename`, falling back to
+`aapt dump badging`), and the deploy path installs and launches *that*.
+The APK is the authority because the task that installs it has just
+built it: whatever Gradle resolved the applicationId to, suffixes and
+flavours included, is in the file, and no default can disagree with it.
+An APK it cannot read is a hard failure, never a fallback to a written
+down default — guessing is the bug.
+
+**`APP_ID` survives as an assertion, not a setting**, and has no
+default. `wails3 task android:run APP_ID=app.yellowjacket` says "this
+build had better declare that id" and is refused, naming both, *before*
+anything is installed or a device is even chosen. It could never have
+been a setting: `ANDROID.md`'s advice to put it in `build/config.yml`
+does not work in beta.8 — `wails3 task` never reads that file (verified
+with `--dry`) — and even when set it fed only the adb commands, never
+Gradle.
+
+`scripts/android-emulator.sh` derives `PKG` the same way, from
+`bin/yellowjacket.apk` when one is built, so `make android-install`,
+`android-launch`, `android-logs` and `android-smoke` follow whichever
+variant is actually in `bin/`. `YJ_ANDROID_PKG` still overrides, and
+the old literal survives only for a tree with no APK built yet.
+
+**The uninstall is gone and is not coming back.** It existed to make
+the bare `install` on the next line work at all — without `-r` Android
+refuses an install over an existing package — so `install -r` removes
+the *reason* for it rather than merely removing it. What is left is the
+one case an uninstall really is the remedy, a changed signing
+certificate, and that is exactly the case where performing it silently
+costs the user their library. So it is named and not done, which is the
+answer `scripts/android-emulator.sh` had already reached for
+`make android-install`.
 
 Related, and it will bite once: the launcher activity is
 `com.wails.app.MainActivity` and the applicationId is
@@ -287,6 +356,27 @@ resolves the leading dot against the *applicationId* and fails with a
 class-not-found that reads like a broken build. Always the
 fully-qualified form.
 
+**`wails3 task android:run:device` is the way to put a debug build on a
+real device**, since #159. What #52 used, before it was safe, was the
+longer form, and it is still the smallest thing that works if you want
+no script between you and adb:
+
+```bash
+wails3 task android:build ARCH=arm64 && wails3 task android:assemble:apk
+adb install -r bin/yellowjacket.apk      # -r, never uninstall
+adb shell am start -n app.yellowjacket.dev/com.wails.app.MainActivity
+```
+
+The id in that last line is the one thing to keep an eye on by hand —
+`./scripts/android-pkgid.sh bin/yellowjacket.apk` is what the tasks ask,
+and it is a good habit before any `am start` written out in full.
+
+`YJ_ANDROID_PKG=app.yellowjacket.dev` still overrides what
+`scripts/android-emulator.sh` — and therefore `make android-smoke`,
+`android-logs`, `android-launch` — addresses, but it is rarely needed
+now: that default is read from `bin/yellowjacket.apk`, so it already
+follows whichever variant was built last.
+
 ## What only a device can answer
 
 The emulator cannot run this app (three separate reasons, none of them
@@ -311,6 +401,91 @@ system bars, the back gesture, focus and audio interruptions,
 permission dialogs, the keyboard — not about what the app draws. The
 drawing is what the other five tiers already cover.
 
+**The third such fault was the activity lifecycle** (#52), and it is
+the one to re-check after touching `main()`, `WailsBridge` or
+`MainActivity`. Android destroys and recreates an activity **without
+restarting the process**, and Wails' `nativeInit` — which
+`MainActivity.onCreate` calls — runs `go mainFunc()` every time. So
+Go's `main()` ran again on a live app, `app.Run()` refused (`a.starting`
+is still true behind Android's `select{}`), and the `os.Exit(1)` under
+it took the healthy first app down with it.
+
+### The lifecycle check, and how to trigger it on demand
+
+This is the regression guard for #52 on this tier, because no other
+tier runs `main()` on Android at all. The Go-side guard
+(`TestMainClaimsBeforeItDoesAnything`) catches work creeping above the
+latch; only the device catches the latch not working.
+
+**Trigger a relaunch with a configuration change the manifest does not
+declare.** `AndroidManifest.xml` lists
+`orientation|screenSize|keyboardHidden|uiMode`, so those are handled
+in-place and are *not* triggers. `fontScale` is not listed, and it is a
+one-liner:
+
+```bash
+adb shell settings put system font_scale 1.15   # restore the old value after
+```
+
+That is the same in-process destroy/recreate that "Don't keep
+activities", a locale change and a memory trim produce, but on demand.
+
+**"Don't keep activities" is the report's own lever and did not work on
+this device**: `settings put global always_finish_activities 1` reads
+back as `1`, `am set-always-finish-activities` does not exist on this
+build, and the activity was never finished on backgrounding. Do not
+spend an afternoon on it; use the config change.
+
+**The assertion is the pid, and the tell is two bridge inits in one.**
+
+```bash
+adb logcat -d | grep -E "Wails bridge initialized|has died|finishDrawing of relaunch"
+```
+
+Healthy is one pid appearing twice — the process surviving the
+recreation:
+
+```
+I/WailsBridge(28420): Wails bridge initialized
+I/WailsBridge(28420): Wails bridge initialized     <- same pid, recreated
+```
+
+Broken is that pair followed within a second by:
+
+```
+I/WindowManager: finishDrawing of relaunch: Window{...MainActivity} 603ms
+I/ActivityManager: Process app.yellowjacket.dev (pid 22956) has died: fg  TOP
+W/ActivityTaskManager: Force removing ActivityRecord{...}: app died, no saved state
+```
+
+Two things about reading that. **`has died: fg  TOP` is not a memory
+kill** — the system does not reclaim the foreground process, so this is
+the app leaving of its own accord. And there is **no crash record
+anywhere**: `logcat -b crash` is empty, no `AndroidRuntime`, no
+`libc: Fatal signal`, no tombstone. That is the `os.Exit` signature,
+and it is why "the system killed it" is the wrong first hypothesis.
+
+**Surviving is only half of it — check the recreated WebView is still
+wired to the running app.** A plausible-looking fix (making
+`WailsBridge.initialized` static, so the second `nativeInit` is skipped)
+keeps the process alive and silently breaks this, because `nativeInit`
+is also what re-points the JNI reference at the new bridge. Go would go
+on executing JavaScript against the destroyed activity's WebView: the
+app opens, renders, and never receives another backend event.
+
+Ask the page, after a relaunch and a resume:
+
+```bash
+make android-inspect
+make android-eval EXPR='(()=>{window.__probe=[];const o=window._wails.dispatchWailsEvent.bind(window._wails);window._wails.dispatchWailsEvent=(e)=>{window.__probe.push(e&&e.name);return o(e)};return "ok"})()'
+# background and foreground the app, then:
+make android-eval EXPR='JSON.stringify(window.__probe)'
+```
+
+A healthy build answers with events from the live services —
+`["IndexStatusChanged","JobsChanged","JobsChanged","android:storageAccess"]`.
+`[]` means the bridge reference is stale.
+
 ## Asking the device, not just looking at it
 
 A real phone can be inspected, and that turns this tier from "reported

.planning/NOTES.md

@@ -3445,3 +3445,800 @@ their own output, and leave the previous snapshots in place.
 makes it worth having: a restored snapshot resolves to `refresh` and
 folds in the incremental listens since — minutes, against the 3–23 h a
 rebuild was estimating.
+
+## A green release pipeline can ship an empty changelog (2026-08-18)
+
+`conventional-changelog-conventionalcommits@10` is silently incompatible
+with the writer `@semantic-release/release-notes-generator@14` depends on
+(`conventional-changelog-writer@^8`). Every release note renders as a bare
+`## 0.0.1 (date)` heading with **no sections and no commits under it**, no
+step fails, and the release ships with an empty body.
+
+It is pinned to `9` in `.gitea/workflows/release.yml` and in
+`make release-dry`, which must stay identical. **Check the rendered notes,
+never the exit code** — this is invisible to every tick in the pipeline.
+
+## semantic-release needs push rights to the branch even when it never pushes to it (2026-08-18)
+
+Core runs `git push --dry-run HEAD:<branch>` as a permission check, before
+and independently of any plugin. With `@semantic-release/git` removed
+nothing ever pushes to `main`, and the check still runs.
+
+Two things this looked like and was not:
+
+- **Not branch protection.** A `--dry-run` push does not reach the
+  pre-receive hook: pushing one to protected `main` with a write-scoped
+  token succeeds. So `main`'s `enable_push: false` is not what fails here.
+- **A flat `403 Forbidden`, not Gitea's protection message.** That is the
+  tell. `PACKAGE_TOKEN` had package-write and repo-*read* — enough to
+  clone a private repo, so every other workflow was fine — and needed
+  `write:repository`.
+
+## A tag-triggered workflow runs the workflow file at the *tagged* commit (2026-08-18)
+
+Not the one on `main`. Moving `v0.0.0` onto a pre-merge commit ran that
+commit's version of `homebrew-formula.yml`, which predated the `v0.0.0`
+skip guard added in the same plan, and it pushed a `0.0.0` formula to the
+public tap.
+
+A guard added today does not protect a tag that points at yesterday. When
+re-pointing a tag, check what the workflows looked like *there*.
+
+## A tag reader looks at exactly one spelling of "total" (measured 2026-08-18)
+
+Writing #16's totals means matching the reader, which is
+`dhowden/tag`, and it is narrower than the specs are:
+
+- **Vorbis (FLAC, OGG): `TRACKTOTAL` and `DISCTOTAL` only.**
+  `vorbis.go`'s `Track()` reads `tracknumber` and `tracktotal` and
+  nothing else, so `TOTALTRACKS` — which several taggers write and
+  which xiph lists — and a `1/12` packed into `TRACKNUMBER` both read
+  back as *no total*. They write successfully. Nothing errors.
+- **ID3v2 (MP3): `TRCK`/`TPOS` as `n/N`**, via `parseXofN`. That is one
+  frame carrying two facts, which is why `applyPositionFrame` reads the
+  existing frame before writing either half.
+- **WAV: nothing at all.** There is no RIFF reader in the module, so a
+  WAV's `id3 ` chunk is invisible to `metadata.ExtractTags` — every
+  field, not just the totals. Filed as #104.
+
+The general shape, and the reason this is written down: a tag written
+under a name the reader does not look at is indistinguishable from one
+never written. So the tests assert the round trip through
+`metadata.ExtractTags` — the reader the *scan* uses — rather than
+through the bytes the writer produced.
+
+## The published catalog artifact predates `total_tracks` (measured 2026-08-18)
+
+```
+$ curl -sSI .../generic/yellowjacket-core-index/latest/core-index.db.zst
+last-modified: Mon, 10 Aug 2026 04:38:16 GMT
+content-length: 75417037
+
+$ sqlite3 core-index.db \
+    "SELECT COUNT(*) FROM pragma_table_info('explore_index') WHERE name='total_tracks';"
+0
+$ sqlite3 core-index.db "SELECT COUNT(*) FROM explore_index;"
+1079667
+```
+
+The column landed in the schema on 2026-08-16; the artifact is from
+08-10, and `index-artifact.yml` is a weekly cron, not a push trigger.
+So `completenessAnswer()`'s catalog fallback answers 0 for **every**
+user today — the machinery is correct and `artifactHasTotals()` is
+doing precisely its job, there is just no data behind it. Same position
+the credit tables are in; both ride on the next publish (#88).
+
+The general point, which is why this is written down rather than just
+fixed: **a probe that makes a column optional also makes its absence
+silent.** `artifactHasTotals` and `artifactHasCredits` are both correct
+and both mean a feature can ship, pass every test, and produce nothing
+for anybody without a single failure anywhere. Checking the *published
+file* is one query and is not implied by any tick in CI.
+
+## "Do I own this" has two answers in the schema, and one of them is a flag (2026-08-19)
+
+Decided while doing #38, and it outlives it because every future
+catalog surface has to pick one.
+
+`explore_index` carries both `in_library` and `local_artist_id` /
+`local_release_group_id` / `local_recording_id`. They are written by
+the same pass (`collectLibraryEntities`), so on a healthy database they
+agree, and the code read them as an OR — `inLibrary || localId > 0` —
+at eight call sites.
+
+They are not the same kind of thing:
+
+- **`local_*_id` is a fact with an owner.** Every query that sets one
+  joins `audio_files`, and `pruneStaleLocalCrossReferences` clears it
+  with an existence test that is a file test in all three cases. It is
+  the same rule `explore-album-details`'s `filePaths` implements, one
+  layer down and computed once per scan.
+- **`in_library` is a ratchet.** `upsertBatch` raises it with
+  `MAX(in_library, excluded.in_library)` and the prune is the only
+  thing that lowers it — gated on the local id being non-null, so a row
+  holding the flag *without* an id is a fixed point nothing can clear.
+  Filed as #118; it still drives search scoring, the popularity-floor
+  bypass and two Explore shelves, so routing the UI around it was not a
+  fix.
+
+What made the choice concrete rather than theoretical: on
+`explore-artist-details` the *same card* used both. The context menu
+gated Play on `localId > 0`; the badge used `inLibrary`. An album with
+the flag and no local row drew a green tick saying it was in your
+library, offered no Play, and — the request item being gated on *not*
+owned — offered no way to ask for it either.
+
+The rejected alternative is worth keeping: batching a real file lookup
+per screenful, the way `credit-store` coalesces. It would have answered
+for **recordings** (`GetFilePathsByRecordingMBIDs`) and most of the
+cards on these surfaces are release groups, so it would have made track
+rows strong, left album cards exactly where they were, and cost a new
+store. The batch that *was* worth adding is a different question —
+`GetAlbumsCompleteness`, "how much of this album is here", which no
+per-card flag can answer at all.
+
+The general point: **two columns that agree today are not one column.**
+Which of them a new surface reads should be decided by which one has
+something that can un-set it.
+
+## The queue panel was a column that could not afford to be one (measured 2026-08-19)
+
+Plan 018, issue #24. Measured against the running app (`make
+dev-headless SEED=default`, Chromium) on Playlists, sweeping the
+viewport with the queue open and closed. Main panel width, and how much
+of the page header survived:
+
+| viewport | sidebar | main (queue open) | actions clipped |
+|---|---|---|---|
+| 1280×800 | 200 | 759 | — |
+| 1000×700 | 200 | 479 | 2 of 3 |
+| **900×600** | 200 | **379** | all three |
+| 800×600 | 56 | 423 | all three |
+| 390×780 | — | **69** | all three |
+| 320×600 | — | **0** | all three |
+| 800×600 | 56 | 744 *(closed)* | New Smart Playlist, 158/162px |
+
+Five things came out of it that the issue did not say.
+
+- **The header clips at the enforced minimum with the queue closed.**
+  800×600 is the only size this app promises, and "New Smart Playlist"
+  loses 4px of its 162 there. The queue makes it dramatic; it is not
+  the cause.
+- **900×600 is worse than 800×600.** `AUTO_COLLAPSE_VIEWPORT` collapses
+  the sidebar *below* 900, so the main panel is 843px at 899 and 700px
+  at 900. **The worst desktop case is the top of the Compact band, not
+  the enforced floor** — so every viewport list that stopped at "the
+  minimum" was missing its own worst case. `layout-overflow.spec.ts`
+  carries 900 now.
+- **At 320px the main panel was 0px.** The panel is `flex-shrink: 0` in
+  the flow of `.content-area`, so an open queue is paid for by the
+  content rather than covering it. Not degraded — gone. That is the
+  measurement #55 wanted and did not have.
+- **Only Playlists overflows.** All ten primary views swept at 900×600
+  and 390×780; every other header reports `scrollWidth ==
+  clientWidth`, and Albums at 390 renders title, count and sort legibly
+  (checked on a screenshot, not just the number). So #69 is one view's
+  action set — three text buttons totalling 390px — and not a systemic
+  header failure.
+- **Both reasons in `MinWidth`'s comment had expired.** The subtitle is
+  `display: none` from 899 down, and the sidebar host is
+  `overflow-y: auto` (at 600×460, `scrollHeight` 434 against a 332px
+  client, Settings reachable after scrolling). The floor is right; its
+  stated defence was two mechanisms that can no longer happen, which is
+  worse than either answer because nobody can argue with it.
+
+**A correction worth keeping, because it nearly went in the plan.** My
+first probe for the sidebar's scroller searched
+`shadowRoot.querySelectorAll('*')` and reported "no scroller — items
+are unreachable", which reads exactly like a live Settings-unreachable
+bug. The scroller is the **host**, and a host is not inside its own
+shadow root. CLAUDE.md was right and the probe was wrong.
+
+**And one claim in the plan's first draft was too strong**: that the
+overlay "removes the desktop half of #69". After phase 2, at 900×600,
+open and closed are now *identical* (main 700, one action clipped)
+where open used to be main 379 with all three clipped. The queue's
+contribution is gone; the header's own overflow remains and is still a
+live defect at a supported size.
+
+### The mode cannot be a media query
+
+The panel is drag-resizable 200–500px and persisted, so a viewport
+breakpoint assumes the default 320 and is wrong by up to 180px for a
+user who widened it — in the direction that hurts, since a wider queue
+is exactly when the content can least afford it. It is computed from
+`.content-area`'s width instead (which already accounts for the
+sidebar's collapse), and the component test that matters widens the
+panel at a *fixed* parent width and asserts the flip.
+
+The floor (480) is a judgement, and the measurement is why: there is no
+cliff. The track list rescales its columns continuously — 213px down to
+124px between main widths of 900 and 544, `rowOverflow=0` at every step
+— and the album grid steps 3 columns to 2 somewhere between 564 and 644
+without breaking. So 480 is anchored at both ends instead: it keeps the
+default 1100px window inline, and puts every measured-broken case on
+the overlay side.
+
+The scrim is perceptible but subtle on a dark ramp, which is worth
+knowing before someone "fixes" it as broken: sampled from screenshots at
+900×600, the main panel's background goes 33,37,41 → 18,20,23 and a
+row's text 242 → 133. It covers the content area only — not the sidebar
+or the transport — because the queue is not modal.
+
+## No test tier can see a `hover:` media query (measured 2026-08-19)
+
+Gating an affordance on `(hover: hover) and (pointer: fine)` — #68's fix
+for the play button that flashed on a long-press — is invisible to both
+browser tiers, in *different* ways, and neither of them fails.
+
+- **`make ui-test`**: CDP's `Emulation.setEmulatedMedia` with a `hover`
+  feature does not reach the tier's iframe. The call succeeds and
+  `matchMedia('(hover: hover)')` still answers `true` afterwards. So
+  there is no way to render a component as a phone would and read the
+  computed style.
+- **`make e2e`**: both projects are desktop (`Desktop Chrome`,
+  `Desktop Safari`), and the phone specs reach phone *width* with
+  `setViewportSize`, which changes no media feature but `width`. So the
+  phone specs run with `hover: hover` and the gate is never exercised.
+
+What does work, and what the fix was verified with, is a second browser
+context under a device descriptor: `chromium.newContext(devices['Pixel
+5'])` reports `hover=false pointer:fine=false` and the button computes
+`display: none`, against `flex` at 1440px. That is a one-off script, not
+a spec — `isMobile` is Chromium-only, so it cannot become an e2e project
+without losing the WebKit half.
+
+`hover-affordance.test.ts` therefore asserts the *parsed stylesheet* —
+that the reveal rule sits inside the media query — which catches the
+regression that actually threatens it: someone hoisting the rule back out
+as a tidy-up, a change nothing on a desktop renders differently.
+
+Related: a width-gated decision **is** testable at both tiers, which is
+why #61's phone mini player is a `matchMedia` stub in the component test
+and needs nothing special.
+
+## A default that is an *absent* key survives an existing seed (2026-08-19)
+
+The skill warns that a seed freezes every default it has already
+persisted, so changing one in `backend/config` is invisible against an
+existing `YJ_HOME` while CI, which seeds by running the app, tests the
+new one. That warning is about defaults stored as *values*.
+
+#25's Autotag-hidden default is stored as the **absence of a key**:
+`GeneralConfig.ViewVisibility` is a map, an id it does not mention takes
+`backend/config.Views`' answer, and only what the user changed is ever
+written. So a seed built before the feature existed showed the new
+default immediately — verified against `.dev/seeds/default.tar`, whose
+`config.toml` has no `[General.ViewVisibility]` table at all, and whose
+sidebar came up without Autotag on the first launch of the new binary.
+After toggling it on and off again the file carries exactly one line,
+`autotag = false`.
+
+The general form is worth keeping: **a default expressed as a zero value
+needs a re-seed to observe; a default expressed as an absent key does
+not**, and it needs no migration for existing installs either. It is the
+same property that makes removing a view later free (an unknown key is
+dropped on load), which is what the `#25 → #27` ordering on #73 rests on.
+
+## A spec cannot assume a destination has a nav item (2026-08-19)
+
+Since #25, `getByTestId('nav-<view>')` is not a reliable way to reach a
+view: Autotag is hidden by default and Downloads is absent without a
+download client, so four existing specs failed on a 30 s timeout waiting
+for a locator that will never resolve. `navigateTo(page, view)` in
+`e2e/support/fixtures.ts` dispatches the app's own `navigate` event
+instead, which is what every nav item, card and detail view dispatches —
+so it is the mechanism and not a test-only door.
+
+Use the nav item when the *nav* is the subject, and `navigateTo` when
+the view is.
+
+## `config-section .header` is ambiguous once a job exists (2026-08-19)
+
+#27 embeds `<job-panel>` inside four Settings sections, and a panel with
+any job in it also mounts a `job-details-drawer` — whose own header
+carries the class `.header`. So `config-page config-section .header`,
+which `settings-reach.spec.ts` had used since plan 007, resolves to two
+elements and fails Playwright's strict mode the moment a scan has run.
+
+Two things follow. A spec asserting on a section's *disclosure* should
+locate it by role and name (`getByRole('button', {name: heading})`) or
+scope per section and take `.first()`, not by that class. And this is a
+worked example of the more general trap: a class name is not a
+selector's contract, and a component that embeds another inherits its
+class names into every ancestor query.
+
+It also only appears in a suite that has *done* something — the
+sections are empty on a fresh app, so this cannot be reproduced by
+opening Settings and looking.
+
+**And it appears on the second engine, not the first.** CI runs
+chromium then webkit against **one app**, so a spec that scans in the
+chromium pass leaves a finished job the webkit pass then trips over.
+Three specs used that selector; two failed locally and the third
+(`failure-voice.spec.ts`) was green on chromium and red on webkit in
+the same run. Reproducing it locally is running the suite twice against
+one `make dev-headless` — which is worth doing for any change that
+leaves state behind, since it is the only place a cross-engine order
+dependency shows up.
+
+## `scrollWidth` counts the left padding and not the right (measured 2026-08-20)
+
+The obvious predicate for "does this flex row fit" is
+`el.scrollWidth <= el.clientWidth`, and on a box with symmetric gutters
+it **under-reports by one gutter**. `scrollWidth` is the extent of the
+scrollable content area, which includes `padding-left` and excludes
+`padding-right`; `clientWidth` includes both. So a child may end up to
+`padding-right` past where content is allowed to go while the box
+reports a perfect fit.
+
+Measured on the top bar (`padding: 0 2em`) at 700x600 with a long-titled
+scan staged: `clientWidth 700`, `scrollWidth 700` — and
+`job-indicator`'s right edge at 700 against a content edge of 668, i.e.
+sitting in the whole right gutter. `#143`'s first fix passed its own
+measurement and left the indicator visibly jammed against the window
+edge.
+
+The predicate `services/top-bar-fit.ts` uses instead is the one its
+spec asserts: no in-flow child's rect outside the parent's *content*
+box, both edges, with half a pixel of slack for fractional flex widths.
+
+This is the same family as #69's title trap — the measurement easiest to
+reach for is the one that cannot see the failure — and it is worth
+knowing before writing the next one of these: **the fit test and the
+assertion that proves it should be the same test.** It was found only
+because `top-bar-fit.spec.ts` measures per child rather than asserting
+on the container, which is exactly why #69 needed
+`header-action-overflow.spec.ts`.
+
+## The top bar's overflow is 11px idle and 262px while working (measured 2026-08-20)
+
+#143 was filed as "11px at 600x600" and re-measured as 171. Both are the
+same defect seen with different jobs running: `job-indicator` is
+`hidden` when idle, ~144px wide showing "Scanning Music", and **235px**
+showing a real library's scan title ("Scanning Music from the external
+drive"), because the label is capped at 12rem and gets there.
+
+Swept against the running app with that job staged, `header.top-bar`
+client vs scroll:
+
+| width | idle | with the long-titled scan |
+|---|---|---|
+| 320, 390, 599 | fits | fits (the phone rules drop the filter and the label) |
+| 600 | 611 | **862** |
+| 700 | fits | 862 |
+| 800 | fits | 862 |
+| 899 | fits | 899 (fits) |
+| 900 | fits | 946 |
+| 1100, 1440 | fits | fits |
+
+Two things worth keeping. The band is **600–610 idle and 600–900 while
+working**, so "a narrow corner" and "the header is crowded from 900
+down" are both true and the difference is entirely what is in flight —
+which is the case a seeded, settled app can never show you. And 899
+fits while 900 does not, because `nav-history` appears at 900: the worst
+width for the header is not the narrowest one, the same way 900 rather
+than 800 is the worst width for the content area.
+
+Staging it is `/__test/emit` with a `JobsChanged` snapshot; a job with
+`state: "running"` never completes, so it stays up until an empty
+snapshot is emitted, which is what makes an idle re-measurement look
+like the fix not working.
+
+## Two repaint mechanisms, and neither is pinned alone (measured 2026-08-20)
+
+`CLAUDE.md` already states the rule — *a virtualized list repaints only
+when you tell it to, and the accidental way you were telling it may be
+the thing you are about to delete* — found in `artists-view` and
+`genres-view`. `queue-panel` is a second instance with numbers, and the
+numbers are the part worth keeping.
+
+It repaints its rows **two** ways:
+
+- `onSelectionChanged()` calls `virtualizer.requestUpdate()`, which is
+  the intended one and the one `track-list` has always had;
+- `.keyFunction=${(track) => track.id}` is a **per-render arrow**, so it
+  is a changed property on every host update and repaints the rows by
+  itself.
+
+Removing *either* alone changes nothing observable. That is why #43
+could not be settled by reading the code: the hypothesis in its Findings
+(the repaint is missing) was checkable, false, and would have looked
+identical either way.
+
+Removing **both** does not break selection either — it delays it. Time
+from click to `aria-selected`, three clicks each:
+
+| build | ms to highlight |
+|---|---|
+| healthy | 5, 16, 17 |
+| both mechanisms removed | 134, 3,866, 5,816 |
+
+The highlight arrives on whatever unrelated render happens next (the
+player's 1 Hz position report is the usual candidate). **Four seconds is
+indistinguishable from broken to a user, and invisible to a spec** —
+`expect.poll`'s default 5 s timeout passes the degraded build on every
+assertion. `queue-selection.spec.ts` bounds its selection assertions at
+500 ms for that reason, which is ~30x the healthy case and an order of
+magnitude under the degraded one.
+
+The general form, for the next spec about anything push-driven: **a poll
+generous enough to be stable is generous enough to miss a latency
+regression entirely.** If "late" is a failure mode worth having, the
+timeout has to say so.
+
+## A hit-scan says how much of a row is not selectable (measured 2026-08-20)
+
+`explore-link` stops the click's propagation on purpose — "the row must
+not also treat it as a selection" — so a click on a track, album or
+artist *name* navigates and selects nothing. That is app-wide and
+deliberate, and the useful question about any given list is how much of
+its row it costs.
+
+Asking `elementFromPoint` what is under each x across a row, at three
+heights:
+
+| list | link coverage |
+|---|---|
+| queue panel | 12% |
+| track list | 21% |
+
+This killed a fix in progress. #43 reads as "selection is broken in the
+queue panel, and fine in the track list", the obvious mechanism is that
+the queue's narrow rows are mostly name, and it is **wrong**: the panel
+is *less* link-covered than the list it is being compared against. The
+scan takes a minute and is worth running before demoting anybody's links
+— `explore-album-details`'s tracklist (number / title / artist /
+duration) is the one that plausibly *is* mostly link, and is the one
+#5 is about to add selection to.
+
+## A layout is still moving when a guard says it has arrived (measured 2026-08-20)
+
+`album-dropdown.spec.ts` failed with `Expected 80, Received 10` twice
+over two sessions, and #133 already strengthened its guard from
+"scrollable at all" to "has at least the range the assertion needs".
+That was necessary and could not be sufficient, and the reason is
+structural rather than a matter of thresholds: **a guard and the write
+it guards are separate CDP round trips**, so the page is free to
+re-lay-out between them. Polling harder cannot close a window between
+two moments; only removing the window can.
+
+Measured directly, sampling `scrollHeight - clientHeight` on
+`.grid-scroll-container` every frame across a 1440x900 → 900x600 resize,
+three runs:
+
+| t (ms) | range |
+|---|---|
+| 0 | 0 |
+| 1 | **88** |
+| 8–14 | 330 (settled) |
+
+88 satisfies a guard asking for 80 and is not the settled value, so the
+guard can pass while the grid is one layout pass from done. Under
+full-suite load the transient is worse — the observed failure had 10 —
+which is why it shows up on the second run of a suite and not in ten
+consecutive runs of the file alone (0/10 both before and after the fix).
+
+The shape to write instead: **one page-side call that performs the
+action and returns what it observes**, with `expect.poll` retrying
+*that*. `scrollTo()` sets `scrollTop` and returns `scrollTop`, so the
+assertion is about what the grid did rather than about what it was
+ready to do. `layout-overflow.spec.ts`'s sidebar probe already had the
+fused half and was missing the retry; it has both now.
+
+Worth generalising: a spec that resizes and then measures is asserting
+about a moving target for the next dozen frames. Fuse, then poll.
+
+## "The first N tracks" is not a way to ask for an ordinary one (2026-08-20)
+
+`queue-selection.spec.ts` staged its queue from the first few rows of
+`library.Library.GetTracks(0)` and clicked a track *name*, which
+`explore-link` routes to that track's **album** page. Four tracks in the
+fixture library have no album at all — `01 Tone A`, `02 Tone B`,
+`Title Only`, `no-tags-at-all` — and a name with nothing to route to
+renders as **plain text**, not as a link.
+
+Two things follow, and the second is the sharper one.
+
+**The order is the scan's.** `GetTracks` returns `audio_files.id` order,
+i.e. the order the scan inserted rows, which depends on concurrency and
+directory traversal. Locally the first eight are all from two proper
+albums, so the spec passed twice over; CI rebuilds its seed with a real
+scan, got a different eight, and failed on both engines. This is the
+same family as "a seed freezes every default it has already persisted" —
+the fixture library is not a list, it is a *set* with an incidental
+order, and no spec should depend on that order.
+
+**A loose locator hid it.** The row was located with
+`.locator('.explore-link').first()`, and a row has two — the title and
+the artist. When the title is plain text, `first()` silently resolves to
+the **artist** link, so the click went somewhere real and the assertion
+was about a destination the test had not exercised. `.track-title
+.explore-link` is the locator that says which one it means; the loose
+one turned a fixture problem into a mystery.
+
+The general rule for this repo's fixture library: it is deliberately
+full of edge cases (untagged, unicode, duplicates, extremes), so a spec
+that wants an *ordinary* track has to **say so** — filter on the
+property it depends on rather than slicing.
+## A nested rule starting with an element name is dropped on the phone (2026-08-20)
+
+`CLAUDE.md` records that the device renders in **Chrome 113**, which
+does not have relaxed CSS nesting (Chrome 120). The consequence is
+sharper than "some syntax is unavailable": a nested rule whose selector
+begins with a bare identifier is not a parse error you would notice, it
+is **silently dropped**.
+
+Three such rules were live in `frontend/index.css`, all inside
+`.bottom-bar`, and all therefore dead on the phone and only on the
+phone:
+
+```css
+.bottom-bar {
+    #track-info { p { … } }   /* the metadata's ellipsis */
+    now-playing { overflow: hidden; }
+    audio-player { margin: 0.5em 1em; }
+}
+```
+
+The first is the interesting one: it is the *ellipsis* on the bottom
+bar's track title and artist, so on the device that text has never
+truncated — the same class of fault as `now-playing`'s marquee, whose
+`text-overflow` sat on the wrong box and had never produced an ellipsis
+in any mode. Both are invisible to every assertion and visible in a
+screenshot.
+
+`& p`, `& now-playing`, `& audio-player` are valid in both, so the fix
+is one character per rule. What is worth keeping is the rule of thumb:
+**inside a nested block, always write `&`** — and note that a rule
+inside `@media` is *not* nested, so `@media … { bottom-nav { … } }`
+elsewhere in that file is fine and needs nothing.
+
+`make css-check` does not catch this (it looks for backticks that end a
+tagged template early). Filed as an issue: the check is the natural
+place for it, being the same shape of trap — a silent, phone-only,
+screenshot-only failure.
+
+## Centring a bar costs the control in the middle of it (measured 2026-08-20)
+
+#23 asks for the transport centred in the bottom bar. The obvious
+implementation — make the outer two grid tracks the same width, so the
+middle is centred by construction — is right, and the first cut of it
+was a regression, because "the same width" was taken to mean *the
+metadata's* width on both sides.
+
+Measured at 800px, with the seek bar's own track:
+
+| layout | seek track | transport column |
+|---|---|---|
+| `320px 1fr auto` (before) | 257 | 407 |
+| both sides `--now-playing-width` | **61** | 179 |
+| both sides `min(--now-playing-width, 25%)` | 246 | 364 |
+
+At 200% text the middle row is worse still: 130 before, **0** with the
+uncapped sides. Centring is free at 1440 and expensive at 800, so a
+change checked only at a comfortable width looks perfect.
+
+The general form: **a symmetric layout reserves space on the side that
+does not need it.** The right-hand group here is ~141px (volume plus
+the queue button) and was being given 320 to keep the arithmetic
+symmetric. Cap the side tracks against the *bar*, not against their
+content, and the middle gets the difference.
+
+The spec that pins this is two assertions, not one, and that split is
+deliberate: an uncapped build is *perfectly centred* and fails only the
+seek-bar width, so a spec asserting centring alone would have passed
+the regression.
+
+## The phone's way into Now Playing was under the artwork (measured 2026-08-20)
+
+`phone-shell.spec.ts`'s "opens the full-screen now playing" failed in CI
+on both engines, three times across two branches that could not have
+caused it, and passed on re-run each time. It was filed as a flake
+(#150). It is not one: **it depends on which track is playing.**
+
+`.expand` — the phone's only route into `<now-playing-view>` — is
+`position: absolute; inset: 0` inside `.cover-art-wrapper`, and
+`.cover-art` is a **later sibling**. Both have `z-index: auto`, so they
+tie on paint order and the later one wins. With an `<img>` that costs
+nothing; with no artwork the placeholder `wa-icon` renders and takes
+every click aimed at the button underneath it.
+
+Measured at 390px with `elementFromPoint` at the button's centre:
+
+| playing track | hit test |
+|---|---|
+| has artwork | `button.expand` |
+| no artwork | **`wa-icon`** |
+| no artwork, with `z-index: 1` | `button.expand` |
+
+So on a phone, the only way into the full-screen player stopped working
+whenever the current song had no cover — and this has nothing to do with
+the fixture: any library has untagged files.
+
+Three things worth keeping.
+
+**"Flaky in CI" was the wrong diagnosis and it cost three cycles.** The
+spec starts the *first* row of the track list, so which track it plays
+is the order the scan inserted rows in — the same root cause as #156,
+one spec over. A test whose subject is a hit test has to *choose* the
+case that breaks it.
+
+**The first two hypotheses were both wrong, and both were plausible.**
+A custom element's upgrade replacing its own contents, and the cover
+preview's `mouseenter` opening a popup under the pointer. Neither
+survived contact with `elementFromPoint`, which took a minute and would
+have saved the other two cycles.
+
+**And the spec that pins it needs the 90-second track**, because a
+2-second one finishes before the assertions run — the trap
+`fixtures.ts` already documents. Note the filter that does *not* work:
+`library.Track.CoverArt` is empty for all 31 fixture rows, so "the
+first track with no cover art" selects nothing in particular. The
+placeholder's presence is asserted instead, which is the property the
+test actually depends on.
+
+## An activity recreation kills the process, deterministically (measured 2026-08-20)
+
+#52's report was "sometimes crashes or restarts when reopened after
+running in the background". Measured on a real device, the *fault* is
+not intermittent at all — only its trigger is.
+
+Device: Light Phone III (TLP301), Android 14 / SDK 34, arm64-v8a,
+WebView **Chrome 113** at 424x439 CSS px. Debug build
+(`app.yellowjacket.dev`), installed beside the released `v0.3.1` with
+`install -r`.
+
+**Conditional on the activity actually being recreated in a live
+process, the process died 8 times out of 8** — 3 by hand, then 5/5 in a
+scripted loop. The runs where it survived were runs where no recreation
+happened (one `Wails bridge initialized` in the log rather than two), so
+they are inconclusive rather than passes; a harness that does not check
+for the second init reports those as green and reads as flakiness.
+After the fix: 5/5 recreations survived, plus 6 background/foreground
+cycles and 3 interleaved recreations on one pid.
+
+The mechanism is three log lines:
+
+```
+12:47:56.159 I/WailsBridge(22956): Wails bridge initialized
+12:48:38.898 I/WailsBridge(22956): Wails bridge initialized   <- same pid
+12:48:39.357 I/ActivityManager: Process app.yellowjacket.dev (pid 22956) has died: fg  TOP
+```
+
+`nativeInit` runs `go mainFunc()` on every activity creation; the second
+`main()` reaches `app.Run()`, which refuses because `a.starting` is
+still true behind Android's `select{}`, and `os.Exit(1)` takes the whole
+process — including the healthy first app — with it.
+
+Four things worth keeping:
+
+- **`has died: fg  TOP` is not a memory kill.** The system does not
+  reclaim the foreground process. This reads as "the OS killed us",
+  which is the wrong hypothesis and the reason the issue sat unverified.
+- **There is no crash record of any kind**: `logcat -b crash` empty, no
+  `AndroidRuntime`, no `libc: Fatal signal`, no tombstone. `os.Exit` is
+  not a crash. The one line that named the fault —
+  `slog.Error("application error", "err", ...)`, carrying
+  `"application is running or a previous run has failed"` — went to
+  `/dev/null`. That is #160.
+- **"Don't keep activities" does not work on this device.**
+  `settings put global always_finish_activities 1` reads back as `1`,
+  `am set-always-finish-activities` does not exist on this build, and
+  the activity was never finished on backgrounding. The report's own
+  suggested lever is a dead end here. What *does* work, deterministically
+  and in one line, is a configuration change the manifest does not
+  declare: `adb shell settings put system font_scale 1.15`
+  (`AndroidManifest.xml` declares `orientation|screenSize|
+  keyboardHidden|uiMode`, so none of those are triggers).
+- **Surviving is only half the property.** The recreated WebView has to
+  still be wired to the running app, which was verified by hooking
+  `window._wails.dispatchWailsEvent` and backgrounding/foregrounding:
+  `["IndexStatusChanged","JobsChanged","JobsChanged",
+  "android:storageAccess"]`. The tempting Java-side fix — making
+  `WailsBridge.initialized` static — passes the pid check and fails
+  this one, because `nativeInit` is also what re-points the JNI
+  reference at the new bridge.
+
+## The Taskfile's device tasks uninstall the released app (2026-08-20)
+
+`android:run:device` builds the **debug** variant
+(`applicationIdSuffix ".dev"`) and then runs
+`adb uninstall {{.APP_ID}}`, where `APP_ID` defaults to
+`app.yellowjacket` — the **release** id. So it deletes the user's
+installed app and its library, installs a different package, and then
+fails to launch the one it removed. `deploy-device` carries the same
+uninstall. Filed as #159; `android-tier.md` had been recommending
+`run:device` as the way onto a device.
+
+This is the hazard that file already names — "The identity is declared
+twice ... **Nothing enforces that they agree**" — reached by a second
+route: the two ids differ not because someone edited one, but because
+the debug buildType suffixes it.
+
+## The uninstall was there to make a bare `install` work (measured 2026-08-20)
+
+Fixing #159 turned up *why* the `adb uninstall` was in all four tasks,
+which the issue does not say and which decides whether it can simply be
+deleted. The line under it was `adb install`, with **no `-r`** — and
+Android refuses an install over an existing package without it. So the
+uninstall was not a deliberate clean-slate step; it was the price of
+the missing flag, paid on every run, and `install -r` removes the
+reason for it rather than merely removing it.
+
+That matters because "should the uninstall go at all" looked like a
+trade — drop it and a signing-certificate change fails with
+`INSTALL_FAILED_UPDATE_INCOMPATIBLE` instead of being handled. It is
+not a trade: nothing else was relying on it. The certificate case is
+reported with the command to run, which is what
+`scripts/android-emulator.sh` already did for `make android-install`,
+so this is one existing judgement applied consistently rather than a
+new one.
+
+## `wails3 task android:run` installs on a phone (measured 2026-08-20)
+
+The emulator tasks (`run`, `deploy-emulator`) used a bare `adb install`
+with no `-s`. adb with exactly one device attached uses that device
+whatever kind it is, so with a phone plugged in and no emulator
+running, the task whose summary reads "in the Android Emulator"
+installed on the phone — and, before #159 was fixed, ran
+`adb uninstall app.yellowjacket` against it first. The reported data
+loss was reachable from the *emulator* task, which is not what the
+issue describes and is worse, because nothing in the name warns you.
+
+Measured after the fix, phone attached and emulator stopped:
+
+```
+$ ./scripts/android-deploy.sh --apk bin/yellowjacket.apk --target emulator
+android-deploy: no emulator target is online.
+    LP3LHMA531900746	device
+    Start one with:  make android-emulator
+```
+
+The general form: **a task that names a target has to say so to adb.**
+The device tasks always filtered on `$1 !~ /^emulator-/`; the emulator
+tasks filtered on nothing at all.
+
+## The package id can be read back, and costs nothing (2026-08-20)
+
+`aapt2 dump packagename <apk>` answers in one word and ~40 ms, from
+`$ANDROID_HOME/build-tools/*/aapt2` (versioned, so resolved not
+pinned); `aapt dump badging` is the fallback for older build-tools and
+is what #159's own measurement used. That is cheap enough to do on
+every deploy, which is what makes "the two ids agree by construction"
+affordable rather than aspirational — the alternative considered was
+giving the debug-flavoured tasks `APP_ID` + `.dev`, which is one line
+and leaves the class of bug alive for the next flavour or suffix.
+
+The guard runs **before** a target is chosen, deliberately: it is a
+question about the artifact, so it can be exercised with nothing
+plugged in, and a build whose id is wrong should be refused whether or
+not there is anything to install it onto. That is what let the negative
+test run safely with the user's phone attached:
+
+```
+$ ./scripts/android-deploy.sh --apk bin/yellowjacket.apk \
+      --target device --expect app.yellowjacket
+android-pkgid: refusing to act on a package this APK does not declare.
+    the APK declares:  app.yellowjacket.dev
+    the task expects:  app.yellowjacket
+rc=2
+```
+
+That is exactly #159's configuration — debug APK, release id, real
+device — refused with no adb call made.
+
+## `make android-emulator`'s boot wait can be satisfied by a phone (2026-08-20)
+
+Noticed while booting the emulator for #159's verification, with a
+phone also attached. `scripts/android-emulator.sh start` reported
+`waiting for boot ok / android 14` about **eight seconds** after
+launching the emulator, which had not appeared in `adb devices` yet —
+`pick_device`'s last resort is "exactly one device online", and at that
+moment the one online device was the phone. So it waited for the
+phone's boot, found it long since booted, and returned. The emulator
+took another ~10 s to come up.
+
+Harmless here (the emulator was up before anything used it) and a
+straightforward race otherwise: `start` should wait for a device that
+is an emulator, not for whatever `pick_device` returns. Filed as #162.

.planning/audits/2026-08-11-ui/hands-on.md

@@ -13,7 +13,7 @@ reviews. Nothing was changed.
 
 Findings below are numbered `H-n` (hands-on) and cross-reference the
 static reports where they overlap. The reconciliation plan built from
-all four files is `.planning/plans/pending/007-ui-reconciliation.md`.
+all four files is `.planning/plans/completed/007-ui-reconciliation.md`.
 
 ---
 

.planning/plans/active/017-release-automation.md

@@ -1,358 +0,0 @@
-# 017 — Releases that happen by themselves
-
-> **Status: built, not yet run.** Phases 0–4 have landed on this branch;
-> phase 5 is the merge itself and cannot be done until then. The old
-> `v1.x` tags are already deleted from `origin`. Verified locally against
-> a scratch remote: semantic-release computes **0.0.1** from these
-> commits and renders correct sectioned notes.
->
-> **One thing found by testing that no amount of reading would have
-> caught.** `conventional-changelog-conventionalcommits@10` — the current
-> release, and my first pin — is silently incompatible with the writer
-> `release-notes-generator@14` depends on: the version is right, the tag
-> is right, every step reports success, and the release body is a bare
-> `## 0.0.1 (date)` heading with **nothing under it**. It is pinned to 9
-> in both `release.yml` and `make release-dry`, with the reason written
-> beside it. Four of my seven original pins were wrong majors besides;
-> they were guesses, and `npm view` was the fix.
-
-The goal in one sentence: **a merge to `main` computes the next version
-from the commits it contains, cuts a tag and a Gitea release whose body
-is the changelog, and every publishing channel builds that tag.** The
-first release under this scheme is `v0.0.1`, and the five existing `v1.x`
-tags go.
-
-## What is there now
-
-Measured, not remembered:
-
-- **Five tags and zero releases.** `v1.3.0`, `v1.4.0`, `v1.4.1`,
-  `v1.5.0`, `v1.6.0` exist on `origin`;
-  `GET /api/v1/repos/yonlu/yellowjacket/releases` returns `[]`. So there
-  is no release page to preserve and nothing but the tags to remove.
-- **`CHANGELOG.md` is stale and belongs to another repo.** Its newest
-  entry is `1.3.0` and every link in it points at
-  `github.com/onion-4-dinner/yellowjacket` — it was written by a
-  semantic-release run against a GitHub remote this project no longer
-  has.
-- **`.releaserc.yml` is a complete semantic-release config that nothing
-  invokes**, which CLAUDE.md already says in as many words.
-- **Root `package.json` is literally `{}`** — the stub left behind by
-  whatever was going to run it.
-- The triggers today are: `arch-package` on **push to `main`**,
-  `homebrew-formula` on **`v*`**, `android-apk` on **`v*`**, `ci` on
-  every branch, `index-artifact` on cron/dispatch. So Arch publishes a
-  `git describe` version on every merge and the other two publish only
-  when a human remembers to push a tag.
-
-## Decision 1 — semantic-release, with `exec` in place of the `github` plugin
-
-**Revised: the first draft of this plan proposed a shell script and the
-argument for it does not hold.** Recorded here rather than deleted,
-because the reasoning is what the decision rests on.
-
-What I said, and what checking it showed:
-
-- *"The two plugins that would carry the work do not fit."* Half true.
-  `@semantic-release/github` genuinely does not speak Gitea's `/api/v1`
-  — but the replacement is **`@semantic-release/exec`**, which is
-  first-party, published 2026-06, and peer-deps `semantic-release >=24.1`.
-  Its `publishCmd` is one `curl` at the Gitea release endpoint with
-  `${nextRelease.notes}` as the body. The Gitea-shaped part of this is
-  five lines, and the part I proposed to hand-roll — parsing conventional
-  commits, ordering semver, rendering grouped notes — is the part with
-  the edge cases and none of it is Gitea-shaped at all.
-- *"`@semantic-release/git` commits the changelog back to `main`, which
-  re-triggers everything."* True, and it is the one real risk — but it
-  is a two-line guard (skip the job when `HEAD`'s subject is
-  `chore(release):`), not a reason to write a version calculator. That
-  guard is needed under **either** design, since either one writes a
-  changelog commit.
-- *"A Node dependency tree at the root of a Go repo."* The commitlint
-  precedent does not transfer. commitlint was a dependency to regex one
-  line; this is a dependency to do something with real complexity, it is
-  `npx`-only so nothing lands in the repo, and Node is already installed
-  in CI for the frontend.
-- *"It cannot be told to produce `0.0.1`."* Wrong — that is a property
-  of which commits are in the range, not of the tool. Identical under
-  both designs. See below.
-
-Note also that **`@saithodev/semantic-release-gitea` is a dead end** and
-should not be reached for: last published 2022, depends on `got@10` and
-`fs-extra@8`, and declares no peer dependency on semantic-release at all
-— i.e. it is untested against anything since v19, against a core now at
-v25. `exec` + `curl` is both simpler and maintained.
-
-So `.releaserc.yml` stays, and its plugin list becomes five **first-party**
-plugins, all published within the last six months:
-
-| plugin | job |
-| --- | --- |
-| `commit-analyzer` | the version |
-| `release-notes-generator` | the notes |
-| `changelog` | writes `CHANGELOG.md` |
-| `git` | commits it back |
-| `exec` | `curl`s the Gitea release |
-
-The `releaseRules` and `presetConfig` blocks already in the file are
-kept verbatim — they are the same bump table `commit-check.sh` already
-enforces the grammar for, and nothing about the project's commit
-convention changes.
-
-Two mechanical details that decide whether this works at all:
-
-- **semantic-release pushes the tag itself**, as core behaviour, using
-  `repositoryUrl`. The remote here is `ssh://git@git.ljones.me:2222/…`,
-  which would need an SSH key in CI — so the run passes
-  `--repository-url "https://x-access-token:$PACKAGE_TOKEN@git.ljones.me/yonlu/yellowjacket.git"`
-  on the command line rather than committing a token to the config.
-  **That is also what satisfies Decision 2**: the tag push is attributed
-  to a real user, not to the Actions token.
-- **The empty root `package.json` (`{}`) goes.** semantic-release does
-  not need one when `--repository-url` is explicit, and leaving a
-  package manifest at the root of a Go repo invites the npm plugin and
-  every tool that looks for one.
-
-Invocation is pinned in the workflow, not installed into the repo:
-
-```
-npx --yes \
-  -p semantic-release@25 \
-  -p @semantic-release/commit-analyzer@14 \
-  -p @semantic-release/release-notes-generator@15 \
-  -p @semantic-release/changelog@6 \
-  -p @semantic-release/git@10 \
-  -p @semantic-release/exec@7 \
-  -p conventional-changelog-conventionalcommits@9 \
-  semantic-release --repository-url "…"
-```
-
-(Exact majors get pinned from `npm view` at implementation time;
-`conventional-changelog-conventionalcommits` is in the list because both
-the analyzer and the notes generator name that preset and neither
-depends on it.)
-
-## Decision 2 — how the publish workflows learn about the tag
-
-**Gitea, like GitHub, does not start a workflow from a tag pushed by a
-workflow's own token** (go-gitea#33123, and the forum thread it points
-at). This is the one load-bearing unknown in the plan.
-
-The remedy is to push the tag with a *user* PAT — `secrets.PACKAGE_TOKEN`
-is already in this repo and already used by `arch-package` and
-`android-apk` to clone and to publish — so the push is attributed to a
-person and the `v*` triggers fire normally. That keeps the three publish
-workflows completely unchanged in shape.
-
-**It is verified in phase 5, not assumed.** The fallback, if it does not
-fire, is an explicit `POST
-/api/v1/repos/{owner}/{repo}/actions/workflows/{file}/dispatches` per
-channel from the release job. That needs `workflow_dispatch` (with a
-`version` input) added to `homebrew-formula.yml` and `arch-package.yml`;
-`android-apk.yml` already has both. **Add those inputs in phase 3
-regardless** — a hand-triggered rebuild of one channel is worth having
-whether or not the fallback is needed.
-
-The alternative — one `release.yml` with the three publishes as
-`needs:` jobs — is rejected: it means either copying ~400 lines of
-Android and Arch setup into it or relying on `workflow_call`, and it
-puts every merge to `main` behind an up-to-60-minute Android build on a
-runner with capacity 1.
-
-## Decision 3 — 1.6.0 → 0.0.1 is a downgrade, and the answer is reinstall
-
-**Decided: no version-code offset, no epoch. The version number stays
-honest and existing installs are replaced by hand.** Every channel is a
-downgrade and each declines differently, so what to expect:
-
-- **Arch: no upgrade is offered, silently.** `pkgver()` derives from
-  `git describe`, so after the wipe it reads `0.0.1.rN.gHASH`, which
-  pacman orders *below* the `1.3.0.rN.*` in the registry. `pacman -R
-  yellowjacket && pacman -S yellowjacket` is the remedy. (`epoch=1` in
-  the PKGBUILD would have avoided it for one line — but an epoch can
-  never be removed, and it puts a permanent `1:` in front of every
-  version string this project will ever have.)
-- **Homebrew: no upgrade is offered, silently.** Brew has no epoch at
-  all. `brew uninstall yellowjacket && brew install …`.
-- **Android: a hard refusal.** `versionCode` is
-  `maj*10000 + min*100 + pat`, so `0.0.1` is **1** against the **10300**
-  an installed 1.3.0 carries, and the install fails with
-  `INSTALL_FAILED_VERSION_DOWNGRADE`. Uninstall first — **and that takes
-  the app's library and config with it**, which is the same data loss
-  `android-apk.yml`'s keystore guard exists to prevent, arrived at from
-  the other direction. The workflow's own `code -le 0` guard still passes
-  at 1, so nothing in CI stops or warns about this.
-
-All three go in the release notes for `v0.0.1` and in
-`packaging/homebrew/README.md` / `docs/android-release.md`, because a
-channel that silently offers no upgrade is indistinguishable from a
-broken pipeline six months from now.
-
-## Landing exactly `v0.0.1`
-
-Determinism comes from two things:
-
-1. **Seed `v0.0.0` on `6fb7b5e`** (current `origin/main`) after wiping
-   the old tags. That is the floor, and the analyser's range starts
-   there.
-2. **This branch carries no `feat:` commit.** Everything in it is
-   `ci:`/`docs:`/`chore:`/`build:`, plus at least one `fix:` — which is
-   honest, since wiring up release machinery that was configured and
-   never run *is* a fix. One patch-level commit in `v0.0.0..HEAD`
-   computes `0.0.1` and nothing else can.
-
-This is a property of the commit range, not of the tool — it would have
-been the same constraint under the shell script.
-
-This is a real constraint on the branch, not an accounting trick: a
-single `feat:` commit here makes the first release `v0.1.0`.
-
-`v0.0.0` itself gets no release object — it is a floor, not a shipment.
-
-## Decision 4 — what the release page carries
-
-Four artifacts, and the fourth is the interesting one. Measured on this
-machine rather than assumed:
-
-| asset | built by | state |
-| --- | --- | --- |
-| `yellowjacket-<v>-android-arm64.apk` | `android-apk.yml` | already built, verified, signed |
-| `yellowjacket-<v>-linux-amd64.tar.gz` | new job | binary + `.desktop` + icon |
-| `yellowjacket-<v>-x86_64.pkg.tar.zst` | `arch-package.yml` | already built; free to attach |
-| `yellowjacket-<v>-windows-amd64.zip` | new job | **compiles; has never been run** |
-
-**macOS cannot be one of them.** `GOOS=darwin CGO_ENABLED=0` fails at
-`wails/v3/pkg/mac: build constraints exclude all Go files` — the darwin
-backend is Objective-C behind cgo, so a `.app` needs a macOS host and
-the runner is a Linux container. That is precisely why the Homebrew
-channel builds from source on the user's own Mac, and it stays the
-answer for macOS.
-
-**Windows is newly possible and should be labelled honestly.**
-`GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -tags production`
-succeeds in 2.5 s and produces a 40 MB `.exe` — nothing in the audio,
-database or webview path needs cgo on Windows (oto uses WinMM through
-`x/sys`, sqlite is modernc's pure-Go driver, WebView2 is COM syscalls,
-and MPRIS is `linux && !android`-tagged). But **compiling is not
-running**: no Windows build of this app has ever been started, no CI tier
-can exercise one, and `backend/system`'s `%LOCALAPPDATA%` path has never
-resolved on a real machine. It ships marked as untested in the release
-notes, or it does not ship — an unlabelled Windows download is a promise
-nothing here can keep.
-
-### The race the ordering creates
-
-semantic-release runs **prepare** (changelog commit, tag push) before
-**publish** (the `exec` curl that creates the release object). The tag
-push is what starts the publishing workflows — so a fast one can reach
-its upload step *before the release exists*, and
-`POST /releases/{id}/assets` needs an id.
-
-The capacity-1 runner serialises things enough that this would usually
-work, which is the worst kind of bug. So each upload step **polls
-`GET /api/v1/repos/…/releases/tags/{tag}` with a bounded retry** before
-uploading, and fails loudly on timeout rather than skipping the asset.
-That is ~8 lines of shell, shared by all three publishers.
-
-## Phases
-
-**Phase 0 — clear the ground.**
-Delete `v1.3.0`–`v1.6.0` locally and on `origin`; push `v0.0.0` at
-`6fb7b5e` — this is the floor semantic-release reads, and without it the
-first release is `1.0.0` by its own rule. Delete the empty root
-`package.json`. Truncate `CHANGELOG.md` to a header plus a line saying
-history before `0.0.1` is in `git log` — the existing content is another
-repo's links and cannot be repaired, only replaced, and the `changelog`
-plugin prepends to whatever it finds.
-
-**Phase 1 — `.releaserc.yml`.**
-Swap `@semantic-release/github` for `@semantic-release/exec`, whose
-`publishCmd` POSTs to
-`/api/v1/repos/yonlu/yellowjacket/releases` with `tag_name`, `name` and
-`body` taken from `${nextRelease.*}`. Keep `commit-analyzer`,
-`release-notes-generator`, `changelog` and `git` exactly as written; fix
-the `git` plugin's commit message so it passes `commit-check`
-(`chore(release): ${nextRelease.version}` — the existing one already
-does, but the trailing `${nextRelease.notes}` in the body is worth
-keeping deliberate rather than incidental). `make release-dry` wraps
-`semantic-release --dry-run` so the next version is answerable without
-pushing anything.
-
-`scripts/commit-check.sh`'s header already points at `.releaserc.yml`
-for the type list and stays correct — that coupling survives this plan
-rather than being broken by it.
-
-**Phase 2 — `.gitea/workflows/release.yml`.**
-On `push: branches: [main]`. Node 22, the pinned `npx` line from
-Decision 1, `--repository-url` carrying `PACKAGE_TOKEN`. Concurrency
-group `release-main` with `cancel-in-progress: false` — cutting a tag is
-not a thing to cancel halfway.
-
-The one guard that matters: **the job exits early when `HEAD`'s subject
-starts `chore(release):`**, so the changelog commit the `git` plugin
-pushes cannot re-enter this workflow. That is checked in shell rather
-than left to `[skip ci]`, whose handling in Gitea is one more thing that
-would have to be verified.
-
-**Phase 3 — rewire the publish workflows.**
-`arch-package.yml` moves from `push: branches: [main]` to
-`push: tags: ['v*']` plus `workflow_dispatch`, so a merge no longer
-publishes an untagged package. `homebrew-formula.yml` gains
-`workflow_dispatch` with a `version` input and takes its version from
-the input when there is no tag. `android-apk.yml` needs neither.
-
-**Phase 3b — the assets.**
-`scripts/release-asset.sh` is the shared uploader: wait for the release
-by tag, then `POST /releases/{id}/assets?name=…`. `android-apk.yml` and
-`arch-package.yml` each call it with the artifact they already built.
-A new `desktop-assets` job — `push: tags: ['v*']`, in the same
-`ubuntu:24.04` container `ci.yml` uses — builds the Linux binary via
-`make build-prod` and the Windows one via the `CGO_ENABLED=0`
-cross-compile, and uploads both. It is a separate job from the Arch one
-because that runs in an `archlinux` container as an unprivileged
-`makepkg` user, and grafting two unrelated builds onto it would make one
-failure look like the other.
-
-**Phase 4 — say that the upgrade is a reinstall, and that Windows is untried.**
-No code change: a note in `packaging/homebrew/README.md`, one in
-`docs/android-release.md`, the three-channel downgrade warning written
-into the `v0.0.1` release notes, and a standing line in the notes
-template marking the Windows asset unverified until someone runs it.
-
-**Phase 5 — cut it and watch.** *(the only phase left)*
-Merge, then verify with `gitea_ci` that (a) `release.yml` ran, seeded
-`v0.0.0` and produced `v0.0.1`, (b) the release exists **with a non-empty
-body** — check the body, not the exit code — and (c) **all four publish
-workflows started from the tag**. If (c) is empty, that is Decision 2's
-fallback and the `workflow_dispatch` inputs added in phase 3 are already
-there to drive it.
-
-The expected sequence on the merge is: `release.yml` seeds `v0.0.0`
-(triggering nothing), releases `0.0.1`, and pushes both the changelog
-commit and the tag — at which point `release.yml` fires a second time on
-the changelog commit and exits at the `chore(release):` guard, while the
-four `v*` workflows start. On a capacity-1 runner they will queue behind
-each other, Android last and longest.
-
-**Phase 6 — the documentation that will otherwise be wrong.**
-CLAUDE.md's *Commits* section currently explains `.releaserc.yml` and
-says nothing runs it; the CI section says there are five workflows and
-that only `ci.yml` gates. Both change. `docs/android-release.md`
-describes tags as hand-pushed. `make skill-check` fails on a `.pi/`
-reference to a make target that does not exist, so `make release-dry`
-gets documented or nothing does.
-
-## Open questions for you
-
-1. **Ship the Windows `.exe` or not?** It builds, and it has never run.
-   Marked-as-untested is the assumption; say if you would rather hold it
-   back until someone boots it.
-
-Resolved: semantic-release stays, with `exec` in place of the `github`
-plugin (Decision 1). Reinstalls are accepted, so no epoch and no
-versionCode offset (Decision 3). The release carries the APK, a Linux
-tarball, the Arch package and — pending (1) — a Windows zip; macOS is
-not buildable here and stays a Homebrew-from-source channel (Decision 4).
-`v0.0.0` has to be a real tag under this design — semantic-release reads
-git tags for its floor and has no "treat absence as 0.0.0" knob that
-also stops it calling the first release `1.0.0`.

.planning/plans/completed/012-api-call-audit.md

@@ -1,5 +1,7 @@
 # 012 — What we ask the network for, and what we already had
 
+> **Completed.** Findings 1, 2 and 4 shipped. Finding 3 — the bound-but-uncalled methods — is now **#86**.
+
 **Status:** all four findings fixed. Lint (3 configs), Go tests (3
 configs), `tsc` and 752 Vitest tests pass; **not driven against the
 real app**, so the numbers below are read off the code, not measured.

.planning/plans/completed/015-android-release-pipeline.md

@@ -1,5 +1,7 @@
 # 015 — Android release pipeline
 
+> **Completed.** The pipeline ships a signed APK from CI on every `v*` tag; `docs/android-release.md` is its operating document.
+
 Ship an Android APK from CI on every version tag, published to the Gitea
 generic package registry so Obtainium can poll a plain URL.
 

.planning/plans/completed/015-multi-artist-credits.md

@@ -1,5 +1,7 @@
 # 015 — Multi-artist credits, navigable
 
+> **Completed.** Phases 1, 2 and 4 shipped. Running the ingest against the real dump and publishing an artifact that carries credits is **#88**; Phase 3 (`file_artists`) is **#89**, blocked on it.
+
 ## The problem
 
 A track credited to more than one artist has exactly one navigable

.planning/plans/completed/016-android-feature-parity.md

@@ -1,5 +1,7 @@
 # 016 — What Android parity would actually take
 
+> **Completed.** Sections A, B1, B2 and B4 shipped. B3, writing tags on the device, is now **#87**; the device-found UI faults are #51–#72, sequenced by #73.
+
 > **Status: all of section A is done.** A1–A3 landed with "let the app
 > reach the user's music"; A4 (MediaSession, transport notification,
 > audio focus) landed with "survive the screen locking". The direction

.planning/plans/completed/017-release-automation.md

@@ -0,0 +1,87 @@
+# 017 — Releases that happen by themselves
+
+**Shipped as `v0.0.1`.** A merge to `main` now reads the Conventional
+Commits since the last tag, cuts the tag and the Gitea release whose body
+is the generated changelog, and the four publishing workflows build that
+tag and attach their artifacts. Nothing is released by hand.
+
+## What it looks like now
+
+`release.yml` on push to `main` → semantic-release → tag → four `v*`
+workflows in parallel (serialised in practice by the capacity-1 runner):
+
+| workflow | publishes | attaches |
+| --- | --- | --- |
+| `arch-package` | pacman registry | `…-x86_64.pkg.tar.zst` |
+| `android-apk` | generic registry (Obtainium) | `…-android-arm64.apk` |
+| `desktop-assets` | — | `…-linux-amd64.tar.gz` |
+| `homebrew-formula` | the public tap | — (builds from source) |
+
+Verified on the real thing: all five green, three assets on the release,
+the tap at `0.0.1`, and the Obtainium `latest` URL serving 200.
+
+## The five decisions, and what they cost
+
+1. **semantic-release, not a shell script.** The first draft of this plan
+   proposed hand-rolling it and the argument did not survive checking:
+   `@semantic-release/exec` is first-party and current, and the
+   Gitea-shaped part is one `curl`. What I would have hand-rolled —
+   commit parsing, semver ordering, note rendering — is the part with the
+   edge cases and none of it is Gitea-shaped.
+2. **`@saithodev/semantic-release-gitea` is a dead end** and was offered
+   before it was checked: last published 2022, `got@10`, and no peer
+   dependency on semantic-release at all.
+3. **No `@semantic-release/git`.** `main` is protected, so a changelog
+   commit-back is rejected by the pre-receive hook — and would be
+   rejected *after* the tag was pushed, leaving a tagged release the run
+   reports as failed. The release page is the changelog;
+   `.release-notes.md` is a gitignored carrier and `CHANGELOG.md` is a
+   signpost.
+4. **Versions restart at `0.0.1`**, a downgrade on every channel. No
+   `epoch`, no `versionCode` offset: both are permanent, a reinstall is
+   once. Documented in `packaging/homebrew/README.md` and
+   `docs/android-release.md`.
+5. **No macOS and no Windows.** `GOOS=darwin CGO_ENABLED=0` fails at
+   `wails/v3/pkg/mac` and there is no macOS runner, so Homebrew-from-source
+   stays that channel. Windows cross-compiles in ~2.5 s and is withheld
+   because no build of it has ever been *run*.
+
+## Four things that only showed up by running it
+
+- **`conventional-changelog-conventionalcommits@10` renders empty
+  notes.** Silently: right version, right tag, every step green, and a
+  release body that is a bare `## 0.0.1 (date)` heading with nothing
+  beneath it. Held at `9`, in `release.yml` and `make release-dry`, with
+  the reason beside both. **Check the rendered notes, never the exit
+  code.**
+- **semantic-release core dry-run-pushes to the release branch** as a
+  permission check, independently of any plugin. `PACKAGE_TOKEN` had
+  package-write and repo-*read* — enough to clone, not enough for this —
+  and it failed with a flat `403 Forbidden` that reads exactly like
+  branch protection. It is not: a `--dry-run` push never reaches the
+  pre-receive hook, which a one-line experiment settled. The token needed
+  `write:repository`.
+- **The floor tag must go on `HEAD^`, not `HEAD`.** Seeded on the merge
+  commit itself it leaves nothing between the floor and HEAD, and
+  semantic-release correctly reports there is nothing to release. The
+  first run did exactly that and cut nothing.
+- **A tag-triggered workflow runs from the tagged commit's tree.**
+  Moving `v0.0.0` back to `6fb7b5e` ran the *pre-merge* homebrew
+  workflow, which predates the `v0.0.0` skip guard, and pushed a `0.0.0`
+  formula to the public tap. Self-corrected at `0.0.1`. The corollary is
+  general: a guard added today does not protect a tag pointing at
+  yesterday.
+
+## Two mechanisms confirmed, having been assumptions
+
+- **A tag pushed with a user PAT does start the `v*` workflows**; one
+  pushed with the Actions token does not (go-gitea#33123). Both halves
+  are load-bearing and both were observed: the floor seed triggered
+  nothing, and the release tag triggered all four.
+- **Tags are not protected** on this repo, only `main` — which is what
+  lets semantic-release tag at all.
+
+## Left behind deliberately
+
+`v0.0.0` stays on `origin` as the floor. It carries no release, and all
+four publishers skip it by name.

.planning/plans/completed/018-supported-sizes-and-the-queue-model.md

@@ -0,0 +1,327 @@
+# 018 — Supported sizes, and what the queue panel is
+
+**Issue:** #24 (`Area/Shell-Nav`, `Priority/High`, `Reviewed/Confirmed`)
+**Unblocks:** #55 (queue as a screen) — a real Gitea dependency
+**Relates:** #69 (page-header overflow), #12 (mini-player), #51 (small-screen umbrella)
+**Status:** complete — #24 shipped as PR #132, and the matrix's last
+unkept promise closed with #69.
+
+#73 puts this first in Phase 2 and hangs the rest of the phase off it,
+so the decision has to be written down and arguable before any CSS
+moves. This document is the decision. Everything below the matrix is
+either a measurement or an argument for one of the four choices #24
+asks for.
+
+---
+
+## What is actually wrong, measured
+
+Against the running app (`make dev-headless SEED=default`, Chromium),
+Playlists, sweeping the viewport with the queue open and closed. The
+number that matters is how much of the page header survives.
+
+| viewport | sidebar | queue | main panel | header needs | actions clipped |
+|---|---|---|---|---|---|
+| 1280×800 | 200 | open 321 | 759 | 759 | — |
+| 1000×700 | 200 | open 321 | 479 | 747 | New Playlist, New Smart Playlist |
+| **900×600** | 200 | open 321 | **379** | 747 | **all three** |
+| 800×600 | 56 | open 321 | 423 | 747 | all three |
+| 700×600 | 56 | open 321 | 323 | 747 | all three |
+| 390×780 | — | open 321 | **69** | 747 | all three |
+| 320×600 | — | open 321 | **0** | 747 | all three |
+| 900×600 | 200 | closed | 700 | 747 | New Smart Playlist |
+| **800×600** | 56 | closed | 744 | 747 | **New Smart Playlist (158/162px)** |
+| 320×600 | — | closed | 320 | 747 | all three |
+
+Five things in that table are not in the issue.
+
+**The header clips at the supported minimum with the queue closed.**
+At 800×600 — the size `backend/config/window.go` enforces and the only
+size this app *promises* — "New Smart Playlist" loses 4px of its 162.
+#24 reads as a queue-panel bug; the queue makes it dramatic, but the
+header overflows on its own at the minimum window.
+
+**900×600 is worse than 800×600, because the sidebar expands at 900.**
+`AUTO_COLLAPSE_VIEWPORT` collapses the sidebar to icons *below* 900, so
+at 899px the main panel is 843px and at 900px it is 700px. The worst
+desktop case is therefore not the minimum window; it is the pixel
+immediately above the collapse. Anything that tests "the minimum" and
+stops has not tested the worst case, which is what
+`layout-overflow.spec.ts` does today.
+
+**At phone widths the queue is not a drawer, it is an amputation.**
+`queue-panel`'s host is `flex-shrink: 0; width: 0`, going to
+`width: var(--queue-width, 320px)` under `[open]` — it is *in the flow*
+of `.content-area`, so it takes its width from the main panel rather
+than covering it. At 390px that leaves 69px of the page; at 320px it
+leaves **0px**, and the app is not degraded but gone. This is the
+measurement #55 needs and did not have.
+
+**Only Playlists overflows.** Sweeping all ten primary views at 900×600
+and at 390×780, every other header reports `scrollWidth ==
+clientWidth`, and Albums at 390px renders title, count and sort
+legibly (checked on a screenshot, not just the number). #69 is
+therefore one view's action set — three text buttons totalling 390px —
+and not a systemic header failure, though the *rule* still belongs in
+`page-header`.
+
+**Both reasons in `MinWidth`'s comment are stale.** It says the floor is
+800×600 because "below ~780 the header's subtitle wraps" and "below
+~600 tall the eleven sidebar items no longer fit". The subtitle is
+`display: none` below 900 (index.css), and the sidebar host is
+`overflow-y: auto` — at 600×460 its `scrollHeight` is 434 against a
+332px client, and Settings is reachable after scrolling. Neither
+mechanism can happen any more. That does not mean the floor should
+move; it means its stated reason no longer supports it, which is worse
+than either answer.
+
+*(Care needed: my first probe for the sidebar scroller searched
+`shadowRoot.querySelectorAll('*')` and reported "items are
+unreachable", because the scroller is the **host** and a host is not in
+its own shadow root. The claim in CLAUDE.md is correct.)*
+
+---
+
+## Decision 1 — the supported size matrix
+
+Three bands. Two of them already exist and are already argued; what is
+new is that they are written down as a *promise*, and that the queue is
+part of it.
+
+| band | width | navigation | queue | promise |
+|---|---|---|---|---|
+| **Phone** | < 600 | `bottom-nav` + drawer | overlay, full width | reflows; nothing needs sideways scrolling; fits 320px |
+| **Compact** | 600 – 899 | icon sidebar | overlay + scrim | nothing is clipped or unreachable at any width in the band |
+| **Desktop** | ≥ 900 | labelled sidebar | inline where it fits (see decision 2), else overlay | as Compact |
+
+And one promise across all three: **no action is ever unreachable.**
+That is the sentence #69 asks for and it is the one the matrix exists
+to make checkable.
+
+**400% zoom** keeps the meaning it already has: WCAG 1.4.10 names 320px
+as the reflow target, the phone band covers it, and
+`layout-overflow.spec.ts` already asserts a 320px viewport needs no
+sideways scrolling. What changes is that the *queue* must be part of
+that assertion — it is not today, and with the queue open at 320px the
+main panel is 0px wide, which no current test can see.
+
+**The window minimum stays 800×600**, and its comment gets the real
+reason. The old mechanisms are gone, but the floor is still where the
+Compact band's chrome stops being comfortable, and lowering it would
+mean promising the desktop layout at sizes where only the phone layout
+works. The interesting consequence is decision 4.
+
+---
+
+## Decision 2 — the queue is an overlay when it cannot afford to be a column
+
+**The rule.** The queue panel renders inline — in the flow, as today —
+only while
+
+```
+viewport − sidebar − queueWidth ≥ 480
+```
+
+and as an overlay with a scrim otherwise.
+
+**Why it cannot be a media query**, which is the load-bearing half:
+the queue's width is *user state*. It is drag-resizable between 200 and
+500px and persisted (`--queue-width`, `MIN_WIDTH`/`MAX_WIDTH` in
+`queue-panel.ts`). A breakpoint at a fixed viewport width silently
+assumes the default 320, and is wrong by 180px for a user who has
+dragged the panel wide — in the direction that hurts, since a wider
+queue is exactly when the content can least afford it. So the mode is
+computed from the measured widths and published as an attribute, the
+way `data-active-view` already is, and the CSS keys off that.
+
+**Why 480, honestly.** There is no cliff to derive it from. The track
+list rescales its columns continuously — at main widths from 900 down
+to 544 its `--grid-cols` shrink from 213px to 124px with
+`rowOverflow=0` throughout — and the album grid steps 3 columns to 2
+somewhere between 564 and 644 without breaking. So this is a judgement,
+anchored on two things: it keeps the *default* window (1100 wide, main
+= 580) inline, because the inline queue is a desktop affordance people
+choose and turning it into an overlay for the common case would be a
+regression in feel; and it puts every case measured as broken —
+900×600 at main=379, and every phone width — on the overlay side.
+1024×768 lands at main=504 and stays inline.
+
+**The scrim is the other half of the issue's complaint** ("make the
+queue obviously an overlay *over* the content so it reads as something
+to close"). An overlay queue gets a scrim, closes on scrim click and on
+Escape, and returns focus to `#queue-button`.
+
+**What must not change**: #55's Direction is explicit — one component,
+two mount points, do not fork it. The overlay is a *presentation* of
+the same `queue-panel`, so the roving tab stop, Alt+Arrow reorder, drag
+reorder, selection semantics and the `virtualizer.requestUpdate()` on
+selection and current-track change all come along untouched. This
+decision deliberately stops short of #55's detail-view mount, but it is
+the shape that makes it possible, and it unblocks it.
+
+---
+
+## Decision 3 — #69 is its own PR, and here is the finding that decides it
+
+`page-header` **cannot collapse its own actions**, and that is not an
+effort estimate but a fact about the API. Actions arrive through
+`<slot name="actions">` as arbitrary light-DOM markup — Playlists slots
+a `<div class="header-actions">` of three `<button>`s with click
+handlers, drag handlers and a conditional class. A component cannot
+move another component's light-DOM children into a dropdown and keep
+their behaviour; there is nothing generic to render as a menu item.
+
+So the overflow rule needs an *actions API* — hosts declaring
+`{icon, label, handler, priority}` data that `page-header` can render
+either as buttons or as menu items — which is a change to all three
+hosts that slot actions, not a rule added in one place. That is a
+different piece of work from this one, it is independently verifiable,
+and the desktop half of #69's symptom is removed by decision 2 anyway
+(the queue stops eating the header's width).
+
+It therefore stays #69, gets the finding above recorded on it, and
+follows immediately after this. What *this* plan owes it is the
+promise in the matrix — no action unreachable at any supported size —
+and the measurement that the only offender today is Playlists.
+
+**And the promise is not kept yet, which is the honest version of a
+claim this document made in its first draft.** "Decision 2 removes the
+desktop half of #69's symptom" was too strong. Measured after phase 2,
+at 900×600 on Playlists:
+
+| | before | after |
+|---|---|---|
+| queue open | main 379px, **all three** actions clipped | main 700px, **one** clipped |
+| queue closed | main 700px, one clipped | unchanged |
+
+So the queue's *contribution* is gone — open and closed are now
+identical, which is the whole of what this decision owed — and the
+residual "New Smart Playlist: 114/162px" is the header overflowing on
+its own, at a size the queue never touched. #69 is still a live defect
+at a supported size, and the matrix's promise is what will close it.
+
+---
+
+## Decision 4 — a very small window becomes the phone layout, not the mini-player
+
+#24 asks whether a very small window should switch to the mini-player
+(#12) "or simply refuse to go there". Both options in the question are
+worse than the one the codebase already has.
+
+**#12 is a second window, not a mode.** Its findings say so: v3
+supports multiple windows, `AlwaysOnTop` is a window *option*, and the
+frontend would need an entry branch mounting only the mini-player root
+for a second window loading the same bundle. Turning the main window
+into a mini-player at some width conflates the two: it would throw away
+the user's navigation state on a resize, and it puts the MPRIS question
+(#12's own open question — media controls are process-level and must
+not be per-window) on a code path that a drag can trigger by accident.
+
+**And "refuses" is unnecessary, because the reflow already exists.**
+The phone band is real, tested, and reached by width alone — a desktop
+window narrowed below 600px already gets `bottom-nav` and the phone
+shell. That is a better answer than refusing: it is strictly more
+usable than a hard minimum, it costs nothing new, and it is the same
+code Android runs, so it stays exercised.
+
+So: the main window reflows and never becomes a mini-player; #12 stays
+a separate always-on-top window and is not blocked by, or coupled to,
+this decision. The window minimum stays 800×600 for the reason in
+decision 1 — but the phone band is what happens below it, not a
+refusal, which is why the minimum is a comfort floor rather than a
+correctness one.
+
+---
+
+## Phases
+
+1. **This document**, linked from #24, with the matrix reported on the
+   issue and #55 told whether it is unblocked. *(no code)* — **done**
+2. **The queue's overlay mode** — computed mode attribute, scrim,
+   Escape and scrim-click close, focus return. The inline path is
+   unchanged above the threshold. — **done**
+3. **The window minimum's comment** — replace both stale reasons with
+   the measured ones. No value change. — **done**
+4. **Verification**, below. Including the specs that must change
+   because they assert the old behaviour. — **done**
+
+#69 follows as its own branch; #55 became unblocked at phase 2.
+
+## What landed, measured
+
+Main panel width with the queue open, before and after:
+
+| viewport | before | after | mode |
+|---|---|---|---|
+| 1280×800 | 759 | 759 | inline |
+| 1100×720 (default window) | 579 | 579 | inline |
+| 1024×768 | 503 | 503 | inline |
+| 900×600 | **379** | **700** | overlay |
+| 800×600 | 423 | 744 | overlay |
+| 390×780 | **69** | **390** | overlay |
+| 320×600 | **0** | **320** | overlay |
+
+The scrim is perceptible but subtle on a dark ramp, which is worth
+knowing before someone "fixes" it: sampled from the screenshots at
+900×600, the main panel's background goes 33,37,41 → 18,20,23 and a
+row's text 242 → 133. It covers the **content area only** — not the
+sidebar or the transport — on purpose: the queue is not modal, and
+leaving the navigation live means the scrim reads as "this is over the
+content" (which is what #24 asked for) without pretending the rest of
+the app is unavailable.
+
+## What #69 did with the promise, and one thing this plan got wrong
+
+#69 landed on its own branch as decision 3 said it would, and the
+matrix's *no action is ever unreachable at any supported size* is now
+kept rather than promised. Measured on Playlists, actions clipped:
+
+| viewport | before #24 | after #24 | after #69 |
+|---|---|---|---|
+| 900×600, queue open | all three | one (114/162px) | none |
+| 900×600, queue closed | one | one | none |
+| 800×600, queue closed | one (158/162px) | one | none |
+| 390×780 | all three | all three | none |
+| 320×600 | all three | all three | none |
+
+The shape was the one decision 3 predicted — an actions API first, an
+overflow rule second — and all three hosts that slot actions migrated.
+
+**What this document got wrong is smaller and worth keeping.** Decision
+1 says the header's minimum is a *comfort* floor and that only the
+queue and the actions compete for the header's width. They are not the
+only two: every child of that flex row was `flex-shrink: 0`, so
+whatever came last lost, and the actions come last. At 320px the sort
+control alone is 172px of the header — so with every action already
+collapsed into the menu, the *menu button* was 76px off the right edge.
+The promise was still broken with nothing left to collapse.
+
+That is why #69 also had to decide what gives way: the title (which the
+navigation also states) and, below 600px, the word "Sort:" (which the
+direction arrow implies). Neither is an action, which is the rule the
+matrix actually encodes — **an action is a capability and everything
+else on that row is a label.**
+
+## Verification, and what each tier cannot see
+
+- `make ui-test` — the queue panel's mode logic is component-tier
+  work and belongs there. It **cannot** see the shell: the threshold is
+  computed from the sidebar and viewport, which do not exist in that
+  tier.
+- `make e2e` — `layout-overflow.spec.ts` gains the queue-open case at
+  every band (it has none today, which is why main=0px at 320px has
+  never failed anything) and **gains 900×600**, since the minimum is
+  not the worst case. `queue-toggle-state.spec.ts` and
+  `phone-shell.spec.ts` both touch the panel and must be re-read before
+  editing.
+- **Screenshots at every band, read by a human.** This is not optional
+  here: `layout-overflow.spec.ts` asserts the *shell* needs no sideways
+  scrolling and passes on a build whose album header clips its own
+  buttons (measured this session at 390px; filed on #66). Clipping
+  *inside* a component is invisible to it, and clipping is this issue.
+- `make ui-visual` **cannot help at all** — the component tier renders
+  the token fallbacks, because the theme only reaches `:root` in the
+  real app.
+- Accessible names via `page.getByRole(...)`, never a shadow-root
+  query. A drawer with a scrim is exactly the shape that grows a
+  nameless control, and this repo has shipped one three times.

.planning/plans/completed/autotag-v1.3.md

@@ -1,5 +1,7 @@
 # Autotag (v1.3) — MusicBrainz Autotagger
 
+> **Historical record.** Phases 008–010 shipped, and the scoring engine was subsequently overhauled (`recommend.go`, `rank.go`, `mixedbag.go`), which makes the 011/012 sections below stale in their details. What is actually left is **#90** (auto-accept and entry points) and **#91** (settings, and a way back from the dismissed file-write warning).
+
 The MusicBrainz autotagger, collectively **v1.3**. Builds on the explore-browser API client + cache foundation. Five sequential phases (008–012), each depending on the prior one.
 
 | Phase | Title | Status |

.planning/plans/pending/010-owned-album-catalog-offline.md

@@ -1,195 +0,0 @@
-# 010 — Owned albums, offline
-
-**Status:** not started — and **much smaller than when it was written**
-**Branch:** none yet
-**Created:** 2026-08-13
-**Depends on:** nothing
-**Related:** the `AlbumReleasesFailed` fix that prompted it, and the
-tag-derived completeness that landed after it (same session)
-
----
-
-## What already shipped, and what it leaves
-
-The common case is solved without this plan. `GetAlbumCompleteness`
-reads the "5/12" denominator off the files' own tags — persisted to
-`release_group_recordings.total_tracks`, having been extracted at every
-scan since forever and discarded — and an album that is **MBID-matched
-and complete** now opens with **no catalog call at all**. Identity from
-the MBID, tracklist from the tags; those were the two things the browse
-was being spent on.
-
-So the set this plan still has to serve is not "albums you own a track
-of". It is:
-
-- albums that are genuinely **incomplete** (the catalog is the only way
-  to say *which* tracks are missing — tags give the count, not the
-  names), and
-- albums whose tags **never declared a total**, where completeness is
-  unknowable locally and the catalog is the only source.
-
-On a well-tagged library that is a small minority, which changes the
-economics below considerably: the run is shorter, and the rate limiter
-contention that dominates this design is proportionally less severe.
-Re-measure before building — the answer may now be "the prefetch is
-enough".
-
----
-
-## The problem
-
-Opening an album detail page for an album **you already own** hits
-MusicBrainz. Every time it is not in the response cache, which for most
-of a library is every time, because nothing warms that cache except a
-capped prefetch on the artist page.
-
-The user's framing: *this is a classic example of an album we should
-have had locally.*
-
-## Why we do not have it, despite the discography backfill
-
-`BackfillLibraryDiscographies` / `EnsureArtistDiscography`
-(`backend/explore/searchindex.go:301`, `:397`) do less than the name
-suggests. Per artist, `indexOneArtist` fetches:
-
-- `fetchTopReleaseGroups` — capped at `indexMaxRGs` (50)
-- `fetchTopRecordings` — capped at `indexMaxRecs` (200)
-
-and writes them as **flat `explore_index` rows**. There is no release
-group → tracklist relation anywhere in the index, and no release-level
-rows at all. `explore_index` recordings carry `caa_release_mbid` and
-`release_name`, which name the release used for cover art — not a
-tracklist.
-
-So "we have full discographies for library artists" means *we know
-which albums the artist made, offline*. It has never meant we know
-what is on any of them.
-
-The only store of release-level catalog data in the app is `http_cache`
-under `mb:browse:releases:<rg>` (90-day TTL, `musicbrainz.go:27`),
-populated **only** by a live `BrowseReleases` with
-`Includes: ["recordings", "media"]` at `MaxLimit` — the most expensive
-call the app makes to MusicBrainz. It is warmed by exactly one thing:
-`PrefetchReleases` (`explore.go:746`), capped at 8, called only when an
-artist page renders.
-
-An album opened from the library grid therefore always browses live.
-
-## What to build
-
-**A post-scan backfill that warms the release cache for release groups
-that are owned but not known-complete** — bounded, resumable, and
-shaped exactly like `BackfillLibraryDiscographies`, which is the proven
-pattern for this in the codebase.
-
-The scoping rule is the user's and it is the right one: not "every
-album by every artist in the library" (50 release groups per artist,
-mostly never opened) but albums with owned tracks — narrowed further,
-now, to the ones a local answer cannot already cover. The query gains
-one clause: skip release groups whose `GetAlbumCompleteness` reports
-`complete`.
-
-Sketch:
-
-1. A query for release groups with ≥1 owned track and no warm release
-   cache entry. `release_groups.mbid` is the key; the owned-track join
-   is `audio_files → recordings → release_group_recordings`, the same
-   shape `unenrichedLibraryArtistMBIDs` already uses one table over.
-2. Order by owned-track count descending, so the albums the user has
-   most of are warmed first — same reasoning as the discography
-   backfill's ordering, same benefit if a run is cut short.
-3. Run through `releasesSF`, so it never double-fetches a release group
-   an interactive open is already handling.
-4. Bound a run (`discogBackfillMaxPerRun` has a value to copy) and make
-   it resumable: the resume marker is the response cache itself —
-   `BrowseReleasesCached` already answers "is this one done", so unlike
-   the discography path this needs **no new flag column**.
-5. Trigger it where `BackfillLibraryDiscographies` is triggered, and
-   register it with `jobs` so it has progress, pause and cancel like
-   every other long-running operation.
-
-### The rate limiter is the whole design constraint
-
-> **Update (2026-08-13): the priority half is built, and the sentence
-> below is wrong on a detail.** `e.mb` runs on `mbSearchLimiter`
-> (`NewRateLimiterBurst(3, 1)`); the 1 req/s `NewRateLimiter()` cited
-> here is the *artist image* limiter. Both are shared and both were
-> FIFO. `RateLimiter.WithBackgroundLane` + `WithBackgroundPriority(ctx)`
-> now make a marked caller yield to interactive work and pace at 1/s,
-> and `jobs.KindCatalogEnrich` + `startBackfillJob` give the existing
-> backfills progress and cancel. **"Do not start until the priority
-> question has an answer" is satisfied** — mark this backfill's context
-> and register it the way `BackfillLibraryDiscographies` now is.
-> `PrefetchReleases`' cap of 8 is still unrevisited.
-
-One shared `NewRateLimiter()` at 1 req/s (`explore.go:84`) serves this,
-`PrefetchReleases`, and every interactive browse. A backfill over a
-few thousand owned albums is *hours* of wall clock at that rate — which
-is fine for a background job, and not fine if it starves the album page
-the user is looking at right now.
-
-That is the real work in this plan, and it is not the query:
-
-- Interactive browses need to **jump the queue**. Today they cannot;
-  there is one limiter and it is FIFO.
-- `PrefetchReleases`' cap of 8 was sized when nothing else competed for
-  the limiter. Revisit it in the same change.
-- The 60 s fallback the `AlbumReleasesFailed` fix installed is sized
-  for today's contention. If a backfill can queue behind it, that
-  number is wrong again — which is an argument for priority, not for a
-  bigger number.
-
-Do not start the query until the priority question has an answer.
-
-## The alternative that was considered and rejected
-
-**Project release-group tracklists in the dump build and ship them in
-the artifact.** The data is there: `canonical_musicbrainz_data.csv`
-carries `release_mbid` *and* `recording_mbid`
-(`dumpcatalog.go:520`), and `release_to_rg` already maps release →
-release group. It is derivable from bytes the index build already
-streams, with no new API surface at all, and it would work offline on
-first launch with no per-user backfill.
-
-It is rejected **for this plan** because the artifact is built
-centrally and is byte-identical for every user, so "albums the user
-owns a track of" cannot be a filter on it. Shipping tracklists for the
-whole catalog means per-recording rows against a ~900 MB artifact
-budget (~426 B/row measured), and gating on a popularity floor means it
-is absent for exactly the obscure albums a local backfill would have
-covered.
-
-Worse than absent, in fact — and this is the argument that actually
-kills it. The floor is not one number over artists; it is a **per
-artist track budget** (`dumpcatalog.go:58-89`): 50 tracks for a tier-A
-artist, 25 for tier B, 12 for tier C. A projected tracklist would
-therefore be *whichever* of an album's tracks survived that budget,
-with nothing marking the rest as absent — so the album page would count
-owned against a truncated denominator and render "Play 7 of 9" for a
-twelve-track album. That is a confident lie, where the honest states
-this plan's alternative produces (complete / incomplete / unknown) are
-at worst silent.
-
-Note that `markLibraryArtists` (`dumpcatalog.go:246`) already grants
-every library artist full coverage — 500 tracks, 100 release groups —
-by reading the local library, so the per-user tailoring this option
-supposedly cannot have does exist in code. It is a no-op in the CI
-build (empty library), and reaching it means a **local** dump build:
-the ~205 GB, half-a-day download the entire artifact design exists to
-avoid. Whoever finds that function next should read this paragraph
-before getting excited about it.
-
-Worth revisiting if the artifact ever gains per-user tailoring, or if a
-measurement shows the row count is smaller than feared. Note it also
-yields the *canonical* tracklist rather than MusicBrainz's full version
-list, so the versions dropdown would still browse live when opened.
-
-## Done when
-
-- Opening an owned album that has never been opened before renders its
-  catalog tracklist with no network call, after one backfill run.
-- An interactive browse issued while the backfill is running is not
-  delayed by it.
-- The backfill appears in the jobs indicator, and can be paused and
-  cancelled there.
-- A second run after a completed one does approximately nothing.

.releaserc.yml

@@ -1,8 +1,19 @@
 # semantic-release configuration.
 #
-# Runs on pushes to main from .gitea/workflows/release.yml: determine the
-# version from the Conventional Commits since the last tag, write the
-# changelog, commit it, push the tag, and create the Gitea release.
+# Run by hand from .gitea/workflows/release.yml, which has no push
+# trigger: determine the version from the Conventional Commits since the
+# last tag, write the changelog, push the tag, and create the Gitea
+# release.  A release is a shipment rather than a merge, and the commits
+# accumulate until someone says so -- this file needs to know nothing
+# about that, because reading everything since the last tag is what it
+# already did.
+#
+# `branches` is main and only main.  A `prerelease: true` channel is the
+# obvious next edit here and is the one to think twice about: all four
+# publishing workflows trigger on `v*`, which matches `v0.4.0-beta.1`.
+# They carry a prerelease guard now, so the failure is a clean skip
+# rather than a beta in a public tap -- but they are four separate files
+# and this is the line that would turn them on.
 #
 # **There is no `@semantic-release/github` plugin here and there must not
 # be.** Gitea's API is `/api/v1` and is not GitHub's surface. The Gitea

CHANGELOG.md

@@ -5,15 +5,20 @@ The changelog is the releases page:
 <https://git.ljones.me/yonlu/yellowjacket/releases>
 
 Every release there is generated from the Conventional Commits it
-contains, by `.gitea/workflows/release.yml` on merge to `main`. Each one
-carries its notes as its body, grouped by change type, with a link to the
-commit behind every line.
+contains, by `.gitea/workflows/release.yml`. Each one carries its notes
+as its body, grouped by change type, with a link to the commit behind
+every line.
+
+That workflow is **run by hand**, so a release holds everything merged
+since the last one rather than one PR's worth. It used to fire on every
+push to `main`, which made a version per merged PR (issue #115).
 
 **This file is not generated and is not a copy of that.** `main` is a
 protected branch, so nothing pushes a changelog commit back to it — and a
 file that claimed to be a changelog while silently never updating would
-be worse than no file at all. `make release-dry` prints what the next
-merge would release.
+be worse than no file at all. `make release-dry` prints what a release
+run would cut right now, and the workflow's own `dry_run` input answers
+the same question from CI.
 
 History before `v0.0.1` is in `git log`. The versions before it were cut
 by hand and are not on the releases page; the entries this file used to

CLAUDE.md

@@ -6,16 +6,121 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 YellowJacket is a cross-platform desktop music player built with Go (backend) and TypeScript/Lit (frontend), using the Wails framework to bridge them. It supports MP3, FLAC, OGG Vorbis, and WAV playback.
 
+## Issues
+
+**The tracker is the source of truth for what is wanted and what is
+already being worked on**, and it is shared with a collaborator who
+cannot see this session. `scripts/issue.sh` is the whole interface to
+it (`list`, `mine`, `search`, `show`, `new`, `claim`, `unclaim`,
+`comment`, `close`, `label`, `depends`, `labels`); it needs a
+`GITEA_TOKEN` with `write:issue`.
+
+**Search the tracker before starting any work, and claim what you
+find.** Fifty-odd issues make that a real lookup rather than a
+formality. `./scripts/issue.sh search <terms>` covers open and closed —
+closed matters, because "that was fixed three weeks ago" is the
+cheapest possible answer.
+
+**Claiming happens before the first edit, not before the commit.** The
+whole point is that the collaborator can see the work is taken *while
+it is being done*, so `claim` sets the assignee, applies
+`Status/In Progress` and posts a comment naming the branch and the
+approach — all three, or none. It refuses outright if somebody else
+already holds it, and that refusal is the feature: talk to them rather
+than working around it.
+
+**If no issue covers the work, open one first.** The issue exists
+before the branch does. That is what makes the tracker a description
+of the project rather than a description of the past.
+
+**Findings get filed.** A bug tripped over while doing something else
+is an issue with a reproduction, not a sentence in a chat message
+nobody can search. So is a piece of work deliberately not done — the
+issue is where "we decided not to, and here is why" survives.
+
+Four conventions are already established and are not up for
+reinvention:
+
+- **The labels are a taxonomy**, not tags: `Kind/*`, `Area/*`,
+  `Priority/*`, `Platform/*`, plus `Reviewed/Confirmed` (the code was
+  read and the defect confirmed) and the `Status/*` family. `Status/*`
+  and `Reviewed/*` are **exclusive scopes** — one of each at most, so
+  applying a second replaces the first.
+- **#73 is the roadmap.** It states the order the backlog should be
+  worked in and the soft relations that are not expressible as
+  blockers. Picking work off the open list by eye when a meta issue
+  states the sequence is how the sequence stops meaning anything.
+- **Hard blockers are real Gitea dependencies**, which render on the
+  issue itself, and the blocked issue carries `Status/Blocked`.
+- **A PR body carries a commit-to-issue table, the verification
+  actually run, and a `Closes` list** — PR #83 is the shape. That list
+  is for whoever reads the PR; what actually closes an issue is the
+  footer below.
+
+**The closing keyword goes in the commit body, one issue per line.**
+
+```
+docs: delete four documents that contradict the code
+
+<body>
+
+Closes #98
+```
+
+**Gitea parses commit messages that reach `main`; it does not parse the
+PR body**, which only closes anything if the merge happens to copy it
+into the merge commit. Both halves of that were measured. #83's merge
+commit carried `Closes #9, #13, #14, …` and closed **five of ten** — a
+comma list is partially matched. #93's merge commit body was one
+`Reviewed-on:` trailer, so #92 stayed open behind a perfectly correct
+`Closes` line in the PR description.
+
+A footer costs nothing elsewhere: Conventional Commits allows one,
+`scripts/commit-check.sh` only regexes the subject, and
+semantic-release reads the type from the subject — so this changes no
+release decision. The rule that the issue number stays out of the
+**subject** is unaffected, and was never about the body.
+
+**Check it anyway.** A squash, or a merge message edited by hand,
+still drops the footer. `./scripts/issue.sh list --state open` after a
+merge, looking for what you just shipped; `./scripts/issue.sh close
+<n>` for whatever did not take, with a comment naming the commit.
+
+**Unclaiming is automatic, and it is hooked to the close rather than
+to the merge.** Gitea's auto-close changes state and nothing else, so a
+footer left `Status/In Progress` on a closed issue — #100 was closed
+and marked as being actively worked on at the same time.
+`.gitea/workflows/unclaim.yml` runs on `issues: [closed]`, which covers
+the footer, `issue.sh close` and a click in the web UI alike; stripping
+the label in the PR instead would have been a per-PR habit, and habits
+are what the footer removed. It is not instant — the runner has
+capacity 1 — and reopening deliberately does not restore the label.
+`./scripts/issue.sh list --state closed --label "Status/In Progress"`
+is how you find out it has stopped firing.
+
 ## Planning
 
-Active and historical plans live in `.planning/`:
+`.planning/` is **design documents and measured history**, not a queue
+— the queue is the tracker, and a plan file that describes work nobody
+has started is a second, staler answer to "what are we doing next".
 
-- `.planning/NOTES.md` — gotchas, deferred items, open architecture questions, the "we already considered and rejected" list.
-- `.planning/plans/active/` — work currently in progress (read first).
-- `.planning/plans/pending/` — sequenced future work.
-- `.planning/plans/completed/` — one concise recap per shipped milestone.
+- `.planning/NOTES.md` — gotchas, measured facts, open architecture
+  questions, and the "we already considered and rejected" list. Dated,
+  because several are properties of someone else's server. **This is
+  where a decision reached on an issue gets written down** when it
+  outlives the issue.
+- `.planning/plans/completed/` — one recap per shipped milestone, kept
+  for the arguments in it. Where a plan shipped incompletely, its
+  header says which issue carries the remainder.
+- `.planning/audits/` — the read-only audits that produced the
+  reconciliation plans. Historical evidence; not a backlog.
+- `.planning/plans/active/` — a multi-phase design document for work
+  **in flight**, linked from the issue that tracks it. Empty is the
+  normal state. There is no `pending/`: a plan nobody is executing is
+  an issue.
 
-Numbering is sequential and stable across status moves (a plan keeps its `NNN-` prefix as it migrates between `pending → active → completed`). Abandoned plans are deleted; paused work stays in `pending/`.
+Numbering is sequential and stable across status moves (a plan keeps
+its `NNN-` prefix). Abandoned plans are deleted.
 
 ## Commands
 
@@ -212,6 +317,60 @@ stacking dialogs. Window state moved off that path entirely, onto a
 window still exists and `OnShutdown` has neither a context nor a
 window.
 
+**An activity is a view onto the process, and `main()` runs once per
+process.** On Android the Wails entry point is `nativeInit`, which
+`MainActivity.onCreate` calls — and it does two things: it re-points the
+native library's global JNI reference at the calling `WailsBridge`, and
+it runs `go mainFunc()`. Android destroys and recreates an activity
+**without restarting the process** (a configuration change the manifest
+does not declare, memory pressure, or every background under "Don't keep
+activities"), so `main()` ran again on a live app. `application.New`
+returns the *existing* app rather than building a second one,
+`app.Run()` then refuses — `a.starting` is still true, because Android's
+`platformRun` is `select{}` and never returns — and the `os.Exit(1)`
+under that error took the **first**, healthy app down with it: its
+database, its queue, and the audio a `mediaPlayback` foreground service
+was holding the process alive to play. `mainStarted` latches it, first
+statement in `main()`.
+
+Four things about it are load-bearing.
+
+**The answer to "restore the session or cold-start" is settled by
+playback, not by preference.** The audio lives in the Go process, so a
+cold start on every activity recreation would stop the music mid-song —
+which is the exact thing the foreground service exists to prevent. The
+activity is a view; the app is the process. The frontend already
+cooperates, because a recreated WebView loads the page fresh and fetches
+its state from a backend that never went away.
+
+**Returning early is not a degraded mode, and that is why the latch is
+in Go rather than in Java.** The obvious fix — making
+`WailsBridge.initialized` `static`, so the second `nativeInit` is
+skipped — keeps the process alive and silently breaks the app, because
+skipping `nativeInit` skips the reference re-point too: Go would keep
+executing JavaScript against the *destroyed* activity's WebView, and the
+app would open, render, and never receive another backend event. The
+latch lets `nativeInit` do its first job and declines only its second.
+
+**`ServiceShutdown` has never run on Android**, and nothing should be
+built on the assumption that it will. `App.Quit()` reaches an
+`androidApp.destroy()` that is an empty method, and `Run()`'s deferred
+`shutdownServices()` cannot fire behind `select{}`. Durability on this
+platform is the persist writers, which submit on every mutation rather
+than at exit — which is also why `MainActivity.onDestroy` no longer
+calls `bridge.shutdown()`: the activity going away is not the app
+shutting down, and there is no callback for the process going away
+because Android simply kills it.
+
+**No tier here can see any of this**, so the guard is split. A source
+sweep (`TestMainClaimsBeforeItDoesAnything`) asserts the latch is the
+*first* statement of `main()` — the failure it exists for is not
+deletion, which is loud, but a line creeping in above it, since a second
+`NewYellowJacketApp` opens the SQLite database again on every
+recreation. The rest is a documented device check in
+`.pi/skills/yellowjacket-dev/references/android-tier.md`, with the
+logcat signature and a one-line way to force a recreation.
+
 `internalServiceMethods` auto-excludes `ServiceStartup`,
 `ServiceShutdown`, `ServiceName` and `ServeHTTP` from bindings, so this
 shape **removed** 12 spurious bindings and the bogus `context` model
@@ -409,6 +568,36 @@ rather than renaming them.
   the autotag apply are registered; anything that is not registered has
   none of that, which is exactly how the three gaps the audit found
   came about.
+
+  **Its rows are shown where the work is started, not on a page of
+  their own.** #27 folded the Jobs destination away, and the shape it
+  folded into is `<job-panel kinds="…">` embedded four times — scans in
+  Settings → Libraries, index and enrichment in Settings → Search
+  Index, downloads under the download clients, the autotag apply in
+  `autotag-view`. One "Background jobs" section in Settings was the
+  obvious reading of the report and is the tab again under another
+  name.
+
+  Four things about it are load-bearing. **Four of the five kinds
+  already had a home** that showed their work — the tier list, the
+  download list, the apply ring — and what none of them had is the
+  *generic* affordances, so the panel carries pause, cancel, Details
+  and the log to each rather than replacing what is there. **The
+  controls are `applyJobControl`**, not a reimplementation, which is
+  what keeps the "you will discard hours of downloading" confirmation
+  alive: it is keyed on `KindIndexBuild` inside the shared handler, and
+  a host drawing its own buttons would drop it silently. **A panel with
+  nothing to say is `hidden`**, host margin included, because an idle
+  panel in four places is four pieces of furniture describing an
+  absence. And **there is no "Clear finished"** in it, because
+  `ClearFinishedJobs` is global — a Clear under Libraries would discard
+  the index build's history too; a finished row dismisses itself.
+
+  The header `job-indicator` is untouched and is still the one view of
+  everything at once, from every page. One consequence worth knowing
+  before writing a spec: a section holding a `job-panel` also holds a
+  `job-details-drawer`, whose own header carries `.header` — so
+  `config-section .header` is ambiguous the moment a job exists.
 - `config` — TOML-based settings. Settings page uses HTMX + templ for server-rendered HTML fragments.
 - `playlist` / `smartplaylist` — Playlist CRUD and rule-based smart playlists.
 - `mediacontrols` — OS media controls behind one `Handler`: MPRIS over
@@ -840,13 +1029,167 @@ change at all.
 
 Two rules hold it up. The **first** navigation *replaces* the launch
 entry rather than pushing one, or every launch costs a back press before
-the app will close. And the in-app back buttons (`navigate-back`, fired
+the app will close. **There are two launch navigations**, which is what
+defeated that rule for five phases: the eager `navigate → home` at the
+foot of `index.ts` and the configured page `GetDefaultPage()` resolves
+to later. Only the first replaced, so a fresh session was already one
+entry deep, the first back press replayed home over home, and on Android
+`canGoBack()` was true so the press that should have exited the app did
+nothing (#142). The landing-page navigation carries `_replace`, honoured
+only while still at index 0 — past that the user has navigated during
+the backend call, and a slow answer must not overwrite an entry they
+made. And the in-app back buttons (`navigate-back`, fired
 by the detail views and `now-playing-view`) go through `history.back()`
 rather than a stack of their own: the old `navStack` is **deleted**, not
 kept beside it, because two stacks is precisely how a view's own back
 button and the phone's gesture come to disagree about what one press
 means.
 
+**And there is one statement of which view is active**, for the same
+reason: `popstate` calls `handleNavigate()` directly and dispatches no
+`navigate`, so the two nav components — which learned the active view
+from that event — kept highlighting the view the user had just *left*.
+`store/active-view-store.ts` is the shell saying where the user is, and
+both navs read it through `ActiveViewController` rather than holding an
+`activeView` of their own.
+
+Four things about it are load-bearing.
+
+**"Please go to X" and "the active view is now X" are different
+statements**, and only the first existed — dispatched from 28 call
+sites across 18 files. A re-dispatch from inside `handleNavigate` is
+not the fix and cannot be: that function is the `document` listener for
+`navigate`, so it is an infinite loop.
+
+**It is a store rather than an event, because a component that mounts
+after a navigation still has to know.** `bottom-nav`'s "More" drawer
+creates its `<app-sidebar>` on open, and that copy had heard no
+`navigate` at all — standing on Albums, the drawer opened highlighting
+Home. An event has no answer for a listener that was not there.
+
+**A detail view is not a view here**, so the destination it was opened
+from stays lit. `app-sidebar` did that by accident (it guarded on
+`navItems.some(...)`, so an unmatched name left its highlight alone)
+and `bottom-nav` had no such guard and so lit *nothing* — which is why
+one looked right and the other looked broken on the same screen.
+Whether a view is primary is the shell's fact: `view in VIEW_TAGS` is
+passed to `setView`, never re-derived, because a second copy of that
+list is a second thing to forget.
+
+**Nothing is lit until the shell has navigated.** The store starts
+empty rather than defaulting to `home`, which is what `app-sidebar`'s
+field used to do to match the landing view — a default that is correct
+only while `GetDefaultPage()` agrees with it.
+
+**Back and forward are chrome, and the depth is the shell's own
+count.** `<nav-history>` in the top bar is #6: the stack was always
+global — every navigation is an entry and `popstate` restores any of
+them in either direction — so what was missing was an affordance, since
+the only way back was a detail view's own button, which leaves the
+screen with the view it belongs to. The buttons dispatch
+`navigate-back` / `navigate-forward` and the shell owns both guards,
+for the reason the old `navStack` was deleted: a second caller reaching
+for `history` is how two stacks come to disagree.
+
+Three things about it are load-bearing. **Forward is not back
+negated**, so the single `pushedEntries` counter could not express it —
+`popstate` carries no direction and fires identically both ways, so a
+counter decremented on every pop reads a forward as a second back. Each
+entry carries its index (`yjIdx`) and the shell keeps the current one
+and a high-water mark; that also survives a jump of more than one,
+which `history.go(-n)` and a long-press on a browser's back button both
+produce. **A control that cannot act is `disabled` here**, which is the
+documented exception to `library-status-indicator`'s rule: the two are
+a pair whose positions the user learns, and hiding one moves the other
+under the cursor. And **it stands down below 900px** — the top bar is
+what runs out of room first below that (it already overflows 600px by
+11px, #143), and nothing becomes unreachable: `nav.back` / `nav.forward`
+(`Alt+Left` / `Alt+Right`, the browser's own combination, and clear of
+the bare arrows that seek) are global at every width, and the phone has
+the platform's gesture.
+
+The assertion is `aria-current="page"`, in
+`e2e/specs/back-navigation.spec.ts`. That file existed throughout the
+bug, covered exactly these journeys, and asserted only
+`data-active-view` — the shell's own bookkeeping, which was right the
+whole way through — so it was green on the broken build. Same trap as
+`layout-overflow.spec.ts` and `page-header`: a spec named for the
+behaviour, measuring the plumbing.
+
+**Which destinations exist is configuration, and hiding one takes away
+the nav item and nothing else.** Eleven sidebar entries is more than
+most libraries need (#25), so each is toggleable from Settings →
+Navigation, Autotag is off until asked for, and Downloads is absent
+until there is a client to download with — a destination for a feature
+that cannot work is worse than none. `navigate` still resolves a hidden
+view, which is not a nicety: detail views navigate into these and the
+launch page is one of them. Nothing needed a special case for the
+highlight either, because the paragraph above moved that onto
+`active-view-store`: the sidebar asks `isActive(id)` per *rendered*
+item, so a hidden view lights nothing exactly as a detail view does.
+
+Five things about it are load-bearing.
+
+**The stored shape is a map keyed by view id, and an absent key means
+that view's own default** (`backend/config.Views`). That is what makes
+this need no migration in either direction, and it is the polarity rule
+`AllowMeteredCatalogDownload` states: the zero value is the intended
+answer. A `HiddenViews []string` cannot express "Autotag off by
+default" at all — its zero value is *hide nothing* — and a struct with
+a boolean per view turns a view that later stops existing into stored
+garbage. Here an unknown key is dropped on load and a view added later
+gets its own default rather than being invisible or forcibly visible.
+It is also what makes #73's `#25 → #27` order safe rather than
+backwards: when Jobs folds into Settings, `jobs = true` in somebody's
+config is a key nothing asks about.
+
+**Two states the user could not get out of are refused, in the config
+and not in the checkbox.** Settings is never hideable and the launch
+page is not hideable while it is the launch page. `config.toml` is
+hand-editable, so a disabled checkbox is the affordance and
+`SetViewVisible` is the rule — an app that can be locked out of its own
+Settings by a typo in TOML is a support problem nobody can debug
+remotely. On *load* the launch page is instead un-hidden rather than
+refused: there is nobody to tell, and the honest reading of "my launch
+page is Autotag" is that this user wants Autotag, not that their launch
+page should be silently reset to something they did not choose.
+
+**Downloads is gated at the nav and not in the config**, on
+`downloadStore.available`, so switching it on in Settings still means
+what it says once a client exists and the tab appears without a restart
+(#37's rule). `available` is false until the providers have loaded,
+which makes the item *appear* on a fresh launch rather than appearing
+and then vanishing.
+
+**The tab bar honours the toggles too, and the reason is local rather
+than a general rule about phones.** `PHONE_COLUMN_IDS` is the precedent
+for "what a phone shows is a different question", and it would apply —
+except that `bottom-nav`'s "More" opens the *same* `<app-sidebar>`,
+which filters, so an unfiltered bar would contradict its own drawer one
+tap away. Which four tabs is still plan 016's committed subset; this
+only removes from it, and "More" is never filtered because it is how
+everything else stays reachable.
+
+**A retired destination is the one shape this does not make free.** An
+absent visibility key takes its default and an unknown one is dropped,
+but `DefaultPage` is a *value*: a launch page naming a view that no
+longer exists fails validation, and on the load path that means the app
+refuses to start for whoever had it selected. `RetiredViews` is that
+list, and `ApplyDefaults` treats a retired name as a zero value while
+an unknown-but-not-retired one still errors — a typo is worth being
+told about. #27 retiring `jobs` is its first entry.
+
+**The list of destinations is `services/view-meta.ts`**, on
+`shortcut-meta.ts`'s pattern, because #25 gave it a second reader:
+Settings renders a toggle per view and needs the same labels in the
+same order. Which views exist and what an unconfigured install shows is
+Go's (`backend/config.Views`, which `DefaultPage`'s validation reads
+too, so the launchable set is not a second list); how they are *drawn*
+is the frontend's, beside the rest of the icon vocabulary. The binding
+returns the **resolved** map for every view, so the frontend holds no
+copy of the defaults — which would be the copy that shipped in the
+binary rather than the one being edited.
+
 **A primary view is cached, not unmounted.** `index.ts` keeps every
 primary view in the DOM and toggles a `.view-hidden` class, because that
 is what preserves `scrollTop` across navigation — so
@@ -1223,6 +1566,164 @@ is 32px each. Which four is plan 016's committed subset, and everything
 else — Settings included, because a phone still needs it — is behind
 "More".
 
+**There are three supported size bands, and the queue is part of the
+promise.** Plan 018 (#24) wrote them down: **Phone** below 600 (bottom
+nav, reflows, fits 320px exactly), **Compact** 600–899 (icon sidebar),
+**Desktop** from 900 (labelled sidebar) — plus one sentence across all
+three, *no action is ever unreachable at any supported size*. The bands
+themselves already existed; what was new is that they are a promise and
+that the queue panel is inside it.
+
+**The top bar decides what it can afford, and what it gives up is never
+an action.** Its five children do not fit at the bottom of the Compact
+band: the bar was 611px inside a 600px viewport idle and **862px while
+a scan ran**, because `job-indicator` is `hidden` when idle and 235px
+wide showing a real library's scan title (#143). So `services/
+top-bar-fit.ts` is `page-header`'s treatment one bar up — a
+ResizeObserver, every pass starting from all-visible, hiding the
+lowest-priority child until it fits.
+
+Five things about it are load-bearing.
+
+**It is measured rather than breakpointed for a reason specific to this
+bar**: three of its five children are as wide as their *content* — the
+library filter is a `<select>` sized by the longest library name, the
+indicator by the running job's title, the search box by its view-scoped
+placeholder — so any width picked is right for one library, one job and
+one view. Swept with a long-titled scan staged, the bar overflowed at
+**every** width from 600 to 899 *and* at 900 where `nav-history`
+appears, while 899 fits; a breakpoint fixing "600 to 610" would have
+fixed whichever case happened to be idle when it was measured.
+
+**What yields is decided by the promise above, which rules out the two
+cheapest answers.** Hiding the library filter takes away an action —
+`library-filter` is the only control in the app that calls
+`setSelectedLibrary` — so it trades this promise for the same promise
+(#148 is the phone already doing that). Collapsing the search box to an
+icon is what #57 wants and #57 is blocked behind #62, so building it
+here is building it without the thing that blocks it. The two that
+yield are the two that are **not** actions: the wordmark, which the
+window's own title bar repeats and which #48 wants down to "YJ" at
+every width anyway, and then the job indicator's *label*, leaving the
+ring — which is not a new judgement, since the component already drops
+it below 600px and its `sr-only` live region is what announces the
+state either way.
+
+**The wordmark yields its width, not its existence.** The collapsed
+rule is visually-hidden rather than `display: none`, because that `h1`
+is the document's top-level heading as well as the brand.
+
+**"Fits" is the children against the content box, and `scrollWidth`
+cannot express it.** `scrollWidth` counts a box's left padding and not
+its right, so with 2em gutters it under-reports by 32px: the first fix
+read `700/700` — a perfect fit — with the indicator sitting in the
+whole right gutter. Same family as #69's title trap, and found only
+because `top-bar-fit.spec.ts` measures **per child**, which is what
+`layout-overflow.spec.ts` cannot do and why that spec was green
+throughout the defect.
+
+And **the bar does not resize when a job starts**, which is the case the
+whole thing is for — a ResizeObserver on the header alone never fires,
+so every element child is observed too.
+
+**The bottom bar is three columns whose outer two are the same width,
+and that is what "centred" means.** It was `320px 1fr auto`, so the
+transport sat in the middle of the space the metadata and the queue
+button did not use — its centre was ~140px right of the window's at
+every size (#23). The outer tracks are now the same expression, so the
+middle one is centred by construction rather than by arithmetic that
+has to be redone whenever a control joins the bar.
+
+Four things about it are load-bearing.
+
+**The side width is the metadata's, capped at a quarter of the bar**,
+and the cap is not tidiness — it was measured as a regression first.
+Reserving the full `--now-playing-width` on *both* sides costs the
+transport twice: at 800px the outer pair wanted 640 of 800 and the seek
+bar's track fell from **257px to 61px**, and to 0 at 200% text. The
+control you drag was being squeezed to centre the buttons above it.
+With the cap it is 246px at 800, which is parity with the uncentred
+layout.
+
+**The cap is a `min()` rather than a breakpoint** because
+`--now-playing-width` is *user state* — the metadata panel has a drag
+handle — and the same reasoning the queue panel's overlay mode uses
+applies: a rule that assumed the default 320 would be wrong by whatever
+the user dragged. Tying both sides to that variable is also what keeps
+the handle meaningful; a plain `1fr … 1fr` would centre the transport
+just as well and silently make dragging a no-op.
+
+**The volume moved out of `audio-player` and into the bar** (#42),
+because the transport column has to hold the transport and nothing
+else or "centred" means centred with a slider bolted to one side. It
+lives in `.bar-end` with the queue button — one cell, not two columns,
+since the centring compares *columns* and a separate volume track would
+make the outer pair unequal by whatever the slider measures.
+
+And **the slider is inline by default, with the popup as a setting**
+whose stored flag names the *popup*: `backend/config`'s polarity rule,
+where the zero value has to be the intended answer, so an existing
+`config.toml` with no key gets the new default without a migration.
+Inline, the icon becomes the mute toggle and is named after that action
+rather than after the state, because with the slider beside it there is
+nothing left to disclose. It stands down below 600px whatever the
+setting says — that is about the platform rather than preference, and
+is why `mediacontrols`' Android handler implements no volume callback.
+
+**900 is the worst desktop width, not the 800×600 minimum.** The
+sidebar collapses to icons *below* 900, so the main panel is 843px at
+899 and 700px at 900 — the narrowest content area any desktop width
+produces is at the top of the Compact band, not at the enforced floor.
+Every viewport list that stopped at "the minimum" was therefore missing
+its own worst case, which is why `layout-overflow.spec.ts` carries 900
+now. And **both reasons in `MinWidth`'s comment had expired** — the
+subtitle is `display: none` from 899 down and the sidebar host scrolls
+(`overflow-y: auto`; at 600×460 its `scrollHeight` is 434 against a
+332px client) — so 800×600 is a *comfort* floor for desktop chrome and
+not a correctness one. Below it the phone layout takes over, which is
+also why a very small window reflows rather than becoming a
+mini-player: **#12 is a second always-on-top window, not a mode of this
+one**, and making it a mode would discard navigation state on a resize
+and put the process-level MPRIS question on a path a drag can trigger.
+
+**The queue panel is a column only while the content can spare the
+width, and that cannot be a media query.** In flow the host is
+`flex-shrink: 0`, so an open queue is paid for by the main panel: it
+left 379px at 900×600 (with all three of the Playlists header's actions
+clipped), 69px at 390, and **0px** at 320 — the content was not
+degraded but gone. It goes to an overlay with a scrim when
+`available - panelWidth < 480`, where `available` is
+`.content-area`'s width and therefore already accounts for the
+sidebar's collapse.
+
+Four things about it are load-bearing. **The mode is computed, not
+breakpointed**, because the panel's width is user state — drag-resizable
+200–500px and persisted — so a viewport breakpoint silently assumes the
+default 320 and is wrong by up to 180px in the direction that hurts;
+widening the panel at a fixed window size must flip it, and
+`queue-overlay-mode.test.ts` is written around exactly that. **480 is a
+judgement and says so**: there is no cliff to derive it from (the track
+list rescales continuously, 213px to 124px columns with no row
+overflow), so it is anchored to keep the default 1100px window inline
+and put every measured-broken case on the overlay side. **The scrim
+covers the content area only** — not the sidebar or the transport —
+because the queue is not modal, and it is subtle on a dark ramp by
+arithmetic rather than by accident (33,37,41 → 18,20,23). And **the
+overlay is a presentation, not a fork**: #55 asks for one component
+with two mount points, so the roving tab stop, Alt+Arrow reorder, drag
+reorder, selection semantics and `virtualizer.requestUpdate()` all come
+along untouched. Escape closes it and returns focus, and is attached
+only while the overlay is up — it is a dismissal, not a shortcut, which
+is why it is not a panel-scoped binding.
+
+What this does **not** fix is `page-header` overflowing on its own:
+at 900×600 "New Smart Playlist" is still clipped to 114 of 162px with
+the queue *closed*. That is #69, and it cannot be fixed in
+`page-header` alone — actions arrive through `<slot name="actions">` as
+arbitrary light-DOM markup with their own handlers, so collapsing them
+into a "More actions" menu needs an actions *API* (data, not markup)
+across all three hosts that slot them.
+
 **The phone section of `index.css` is last on purpose.** A media query
 adds no specificity, so a `@media (max-width: 599px)` block placed
 above the plain rules it overrides loses to them — which is how phase 1
@@ -1343,6 +1844,52 @@ is therefore **reported at runtime** to `window.__yjIconMisses` and
 drawn as a fallback — an e2e sweep asserts there are none — since a
 missing icon used to be impossible, the CDN having had everything.
 
+**What each icon *means* is a second table, and it is
+`utils/icon-language.ts`.** Bundling answers "does this name resolve";
+nothing answered "does this name mean what the one next to it means",
+and a wrong-but-real icon renders perfectly. So `plus` came to mean add
+to the queue, add to a playlist, make a new playlist **and** you do not
+own this — the first two *adjacent in the same context menu* — while
+`list` meant the queue, the Playlists destination and adding to the
+queue.
+
+The rule the table is built on: **an icon names the noun it acts on,
+not the verb.** "Add to queue" and "add to playlist" are one verb on
+two nouns, so the noun is what has to differ — which is why adding to a
+playlist wears the Playlists destination's own icon, and why the queue
+got `bars-staggered` and stopped wearing Playlists'. `plus` keeps the
+one meaning it is unambiguous about, making something that is not there
+yet.
+
+Four things about it are load-bearing:
+
+- **The request toggle is one glyph in two weights**
+  (`regular/bookmark` → `solid/bookmark`), because two states of a
+  toggle have to read as each other's opposite and a plus against a
+  bookmark does not. The pair was *already in the app and already
+  right* on `explore-album-details`'s "Request this" button while the
+  badge forty pixels away showed a plus — `utils/library-status.ts`'s
+  fault one layer down, having made the two agree on what wanting means
+  and left them disagreeing on what it looks like.
+- **Downloads keeps the solid bookmark, deliberately.** That is the
+  same word twice, not two words: the badge says "this is on your
+  list" and the nav item is that list.
+- **`icon-language.test.ts` sweeps the source**, because the rule is
+  about every call site and checking one checks nothing — the same
+  shape as `TestNoDirectRuntimeEmits`. It reads every `src/**/*.ts` as
+  raw text and fails on a literal `name="plus"` or `icon: 'list'`
+  outside the table, and its **first assertion is that it read
+  anything at all**, since a sweep over an empty glob passes.
+- **It also asserts every `ICON_*` is bundled**, which closes the loop
+  the runtime cannot: `bookmark-check` is Font Awesome **Pro** and sat
+  on `explore-artist-details`'s Follow button, drawn for every followed
+  artist as a circled question mark. `offline-icons.spec.ts` sweeps
+  `__yjIconMisses` and could not see it, because no spec had ever
+  followed an artist — the same fault `requested-badge.spec.ts` was
+  written for, one component over, still live. A name computed from
+  state was only checkable from the state; now it is checkable from the
+  table.
+
 **An album page says how much of the album is yours.**
 `explore-album-details` is a *catalog* page and there is no
 library-side album detail page at all, so the album on it may be
@@ -1442,11 +1989,55 @@ shape as the encoding probe beside it.
 
 What neither side can give is *which* tracks are missing, only how many
 — so an incomplete album still browses, and that is now the exception
-rather than every album load. Two smaller consequences: existing databases
-read "unknown" until a rescan repopulates the column (which degrades to
-exactly the old behaviour, so nothing breaks), and our own `tagwriter`
-writes track and disc *numbers* but not totals, so autotagging a folder
-currently degrades the field this rests on.
+rather than every album load. One smaller consequence: existing databases
+read "unknown" until a rescan repopulates the column, which degrades to
+exactly the old behaviour, so nothing breaks.
+
+**And our own writers declare the total, because for a long time they
+did not.** `tagwriter` wrote track and disc *numbers* and dropped the
+totals, so autotagging an album actively **erased** the evidence this
+rests on: the release became MBID-matched — a green tick — while the
+field `GetAlbumCompleteness` reads stayed absent, which is exactly the
+"2 of 10 tracks, reported as in your library" the report described.
+`FieldTotalTracks` / `FieldTotalDiscs` are written by the autotag apply
+pass and by the download importer, and `dbsync` persists the track
+total to the row so the album page agrees with the file without waiting
+for a rescan.
+
+Five things about it are load-bearing, and four of them fail silently:
+
+- **The total is per *disc*, not per release**, because that is what
+  the tag form declares and what `GetAlbumCompleteness` **sums** per
+  disc — a release total written on every file multiplies a two-disc
+  album's expectation by two, and no library can then satisfy it.
+  `backend/tagtotals` is that derivation, once, because the two callers
+  must not import each other or the writer.
+- **The Vorbis names are `TRACKTOTAL` and `DISCTOTAL` and no other
+  spelling.** `dhowden/tag`'s Vorbis reader looks at exactly those two
+  keys, so a perfectly reasonable `TOTALTRACKS`, or a `1/12` inside
+  `TRACKNUMBER`, is written successfully and reads back as no total at
+  all. The tests assert the round trip through the reader the *scan*
+  uses rather than through the bytes, for that reason.
+- **ID3's number and total share one frame**, so writing either alone
+  has to read the other off the existing tag or it silently discards
+  it. A total with no number is not written: `/12` is what a reader
+  parses as track 0.
+- **The totals are written unconditionally, not on a diff.** The case
+  this exists for is a file that declares *no* total, which compares
+  equal to nothing and is exactly what a "only if it changed" guard
+  skips.
+- **A single-track download must not be totalled.** A `RecordingMBID`
+  anchor resolves `Expected` to that one track, so the same code would
+  tag a track off a twelve-track album "1 of 1" — and a declared total
+  outranks the catalog total that would otherwise have answered
+  correctly. Confidently wrong is worse than absent here, which is the
+  same rule `Known` exists for.
+
+One gap this did not close, and it is older: **`dhowden/tag` has no
+RIFF reader**, so nothing the tag writer puts in a WAV's `id3 ` chunk
+is visible to `metadata.ExtractTags` — not the totals and not the title
+either. `wav_test.go` reads that chunk itself, which is why no test
+ever noticed.
 
 **The absence is what gets marked, not the presence.** The tracklist
 put a green tick against every owned track and a legend underneath
@@ -1463,6 +2054,59 @@ not about plumbing — it says rows may be missing from the page
 altogether, which nothing on screen can show. (`explore-artist-details`
 still uses `loading`; it has no equivalent per-row signal.)
 
+**And that treatment is the app's, not the page's.**
+`utils/ownership.ts` is the rule written once, because it was written
+at eight call sites and so none of them had the whole of it: Explore's
+cards, `top-results-row` and the artist page's three card shapes all
+mixed owned and unowned with a small badge as the only difference, and
+the badge on the *owned* ones was a green tick — the mark on the common
+case this tracklist removed. Owned is plain and draws no badge at all;
+unowned is dimmed, says so in its accessible name, and keeps its
+request affordance; a partly-held album says how partly.
+
+Four things about it are load-bearing.
+
+**Ownership is `localId`, and `inLibrary` is deliberately not
+consulted.** The album page answers with `filePaths`, a real file per
+displayed track, and a card grid cannot afford that — but it does not
+need to, because `explore_index.local_*_id` is built by
+`collectLibraryEntities` from queries that every one join `audio_files`
+and cleared by `pruneStaleLocalCrossReferences`, whose existence test
+is a file test in all three cases. That is the same "ownership is a
+file" rule computed once per scan instead of once per screenful.
+`in_library` is written by the same pass, so the two agree in a healthy
+database, but it is a one-way ratchet
+(`MAX(in_library, excluded.in_library)`) whose only clearing pass is
+gated on a non-null local id: it cannot be un-set on its own (#118).
+One is a fact with an owner; the other is a flag that happens to agree.
+Both `explore-view` and `explore-artist-details` additionally kept a
+`libraryMBIDs` set that accumulated every MBID ever seen with the flag
+and cleared it never, in views that never unmount; both are gone.
+
+**The two answers used to sit on one card.**
+`renderReleaseMenuItems` gates Play on `release.localId > 0` while the
+badge used `inLibrary`, so an album with the flag and no local row drew
+a tick saying it was in your library, offered no Play, and — the
+request item being gated on *not* owned — offered no way to ask for it
+either. Any new surface that asks the question twice will reproduce it.
+
+**`aria-disabled` goes on rows and not on cards.** An unowned *row*
+cannot be activated; an unowned *card* still navigates to the catalog
+page for it, which is a perfectly good thing to do with something you
+do not own. The accessible name carries the state either way, which is
+why it is one helper and not a class.
+
+**The count is batched, not looked up.** `store/completeness-store.ts`
+is `credit-store` one question over: `request()` is per-card and
+coalesces a screenful into one `GetAlbumsCompleteness`, absence is
+cached as an answer (or the albums with no totals re-ask forever), and
+the whole cache is dropped on a scan, a retag or a removal rather than
+aged. `library-status.ts`'s `albumBadgeFor` is where that meets
+`Known`: a total that was never declared is a plain `in-library`, never
+a ring at 0%. One consequence in the badge itself — a `partial` badge
+is *actionable*, and a control named after its action alone dropped the
+count from the one state the ring exists for, so its name is both.
+
 **A partly-owned album draws the release, not the part.** Once the tags
 say nine of twelve, `buildLibraryEntry` shows the *catalog's* twelve
 with three dimmed, rather than the nine on disk — the missing tracks
@@ -1474,6 +2118,32 @@ side-effect worth knowing: this is what finally makes `ownership()`
 say something true here, since counting the displayed tracklist of a
 library-only entry could only ever produce "9 of 9".
 
+**And it can be asked, because the rule alone reaches too few albums.**
+That guard depends on two inputs the user does not control: the files
+declaring a per-disc total, and the catalog's own `total_tracks`. Where
+neither says — which is a great deal of any library, and *every* library
+until an artifact carrying the column is published — a partly-owned
+album showed only the tracks on disk with nothing to say the rest
+existed. `renderTracklistScope()` is the explicit route: a
+"Show the whole album" switch that flips the synthetic "Your Library"
+entry between the local files and the release, which is the rendering
+the page could already do and could only be *triggered* automatically.
+
+Three things about it are load-bearing. **`showFullTracklist` is a
+tri-state**, `null` meaning "follow the automatic rule": the rule is
+right when it fires and the switch has to be able to agree with the page
+it sits on rather than starting out contradicting it, which a plain
+boolean would need recomputed every time the completeness answer moved
+underneath it. **`fullReleaseCluster()` falls back to the
+highest-scoring cluster**, because `findLibraryCluster` is a guess over
+the `inLibrary` flags and returns *nothing* when none are set — which is
+exactly the untagged library the switch exists for, so without the
+fallback the control would be absent precisely where it is needed. And
+**it is shown only where it can change what is on screen**: against the
+library entry, with a release to switch to, and only when the two
+tracklists differ — the same test the version dropdown answers, one
+control over.
+
 **A dropdown is only a choice if the choices differ.** The version
 selector tested `versionEntries.length`, but a release group routinely
 has several releases — reissues, regional pressings, a remaster — whose
@@ -1644,6 +2314,79 @@ that corrects itself a moment later is worse than saying nothing. And
 the field, the direction and their persistence, so the control cannot
 disagree with the list.
 
+**And an action is data, on that same rule: the header decides what
+fits, the host decides what happens.** Playlists slotted three buttons
+totalling 390px into a header that gets 700px at 900×600, so "New Smart
+Playlist" rendered **114 of its 162px** with the queue closed — and on a
+phone none of them could be reached at all, which is what #69 reported.
+A host passes `PageAction[]` (`{id, label, icon, onSelect, priority,
+drop?}`) and `page-header` renders each one as a button or as an item in
+one "More actions" menu.
+
+**It could not have been a rule added in one place**, and that is a fact
+about the API rather than an effort estimate: actions used to arrive
+through `<slot name="actions">` as arbitrary light-DOM markup, and a
+component cannot move another component's light-DOM children into a
+dropdown and keep their behaviour — there is nothing generic in markup
+to render as a menu item. The slot survives for markup a data list
+cannot express, at the stated cost that **a slotted action does not
+collapse** and must therefore fit at 800×600.
+
+Six things about it are load-bearing:
+
+- **The fit is measured, never breakpointed.** A ResizeObserver drives
+  it, and each pass starts from *all visible* and hides the
+  lowest-priority action until it fits — so the collapsed set is a pure
+  function of the current width rather than of how the window got
+  there. A rule that only ever added to the set would never give a
+  button back, and one that adjusted by a step would need a hysteresis
+  band to stop it oscillating on the pixel where a button exactly fits.
+- **"Fits" means nothing is clipped, which is not the same as the
+  header not overflowing.** The title can ellipsis, and the moment it
+  can it absorbs the pressure: `scrollWidth` reports a header that fits
+  perfectly while the heading reads "Playlis…". That is this bug moved
+  from the button to the title, invisible to the same measurement that
+  missed it the first time — so the heading's own truncation counts as
+  not fitting, and an action is collapsed before the title gives way.
+  Below that, at 320px, the title *is* what yields: the navigation also
+  says which page you are on, and an action has nowhere else to be said.
+- **The measurement flips `hidden` on the rendered nodes rather than
+  re-rendering between steps.** Reading `scrollWidth` forces layout,
+  which is the point; awaiting a Lit update between steps instead lets
+  the intermediate all-visible state paint, so the fix would flash the
+  overflow it exists to prevent.
+- **Priority is what a *capability* costs, not what a button is worth.**
+  New Playlist is highest because it is the **drop target** and a closed
+  menu cannot be one; that is also why `PageAction.drop` carries the
+  host's own `dragover`/`dragleave`/`drop` handlers rather than the
+  header owning a notion of dropping, and why the affordance is simply
+  absent from the overflow rather than approximated there.
+- **`aria-controls` names a panel that is always in the DOM** —
+  `config-section`'s rule, and `wa-popup` hides it when inactive — and
+  the keyboard model is `MenuKeyboard`, shared with every other menu in
+  the app so this is not a second one.
+- **It is checked per button, because `layout-overflow.spec.ts` cannot
+  see this.** That spec asserts the *shell* needs no sideways
+  scrolling and passed on the broken build; clipping *inside* a
+  component is invisible to it, which is exactly why the defect
+  survived a spec named for it.
+  `e2e/specs/header-action-overflow.spec.ts` measures each button
+  against its header at 900×600, 800×600, 390×780 and 320×600, and
+  asserts buttons **plus** menu account for every declared action —
+  without that half it would pass vacuously on a build that renders no
+  actions at all.
+
+One thing it deliberately does **not** grow is a phone mode for the
+actions. `PHONE_COLUMN_IDS` is the precedent for "what is drawn and
+what can be sorted are different questions", but it exists because the
+track list's columns cannot be derived from a width; these can, and a
+second declaration of what a phone shows is a second thing to keep in
+step. What the header *does* state at phone width is one word: below
+600px the sort control's "Sort:" label is visually hidden — 172px of a
+320px header for a label the adjacent direction arrow implies — and it
+stays in the accessibility tree, because it is the select's accessible
+name and hiding it outright is `config-field`'s bug one component over.
+
 **The header search box is view-scoped, and now says so.** It sits in
 the app header and reads as global; typing `tide` on Playlists answered
 "No playlists match your search" with three *Tideline* tracks in the
@@ -2033,6 +2776,23 @@ Pre-commit hooks verify generated code is fresh — always run `make generate` a
   mistyped `feat` ships a minor version. `make release-dry` answers "what
   would this merge release" without pushing.
 
+  **The analyzer reads the type and ignores the scope, so a CI-only change
+  is `ci:` and never `fix(ci):`.** The scope is decoration; `fix` is a
+  patch whatever is in the brackets. Two commits touching nothing but
+  `.gitea/workflows/unclaim.yml` were written `fix(ci):` and cut `v0.2.1`
+  and `v0.2.2` — real releases, published to Arch, Homebrew and the APK
+  registry, containing no user-facing change. They were left in place
+  rather than deleted, because a version that vanishes is worse for
+  whoever pulled it than one that turns out to be empty.
+
+  **The blast radius is bigger than the version number**, which is what
+  makes this worth a paragraph. A merge to `main` starts two workflows;
+  if `release.yml` then pushes a tag, that tag push starts **four more**
+  (`arch-package`, `homebrew-formula`, `android-apk`, `desktop-assets`) —
+  on a runner with capacity 1, where the APK build alone is tens of
+  minutes. `make release-dry` before merging is how you find out, and it
+  is cheaper than every one of those.
+
   **`@semantic-release/github` is not in that config and must not be.**
   Gitea's API is `/api/v1` and is not GitHub's surface, so
   `@semantic-release/exec` calls `scripts/gitea-release.sh` instead — one
@@ -2066,23 +2826,75 @@ branch** (`enable_push: false`, an empty push whitelist, and `CI / check*`
 the pre-receive hook. This file said otherwise for a long time. Tags are
 *not* protected, which is what lets `release.yml` push one.
 
+**A branch answers a claimed issue** — see "Issues" above. The commit
+grammar is unchanged and is load-bearing for a different reason
+(semantic-release reads it), so the issue number lives in the branch
+name and the PR body rather than in the commit subject.
+
+**A batch of small fixes can be one PR**, which is what #83 did: eight
+branches preserved as merges under one integration branch, so
+authorship survives and the batch lands as one release rather than
+eight. The cost is that its `Closes` list has to be checked afterwards
+— it half-worked.
+
 Pre-commit runs vet, lint, codegen check, and frontend typecheck in parallel. Pre-push runs the full test suite.
 
 ## CI
 
-Seven workflows in `.gitea/workflows/`. Five of them package and
+Eight workflows in `.gitea/workflows/`. Five of them package and
 publish (`arch-package`, `homebrew-formula`, `index-artifact`,
 `android-apk`, `desktop-assets`); `release.yml` decides *whether* four of
-those run at all; only `ci.yml` gates, and it is the one to look at when
+those run at all; `unclaim.yml` is housekeeping on the tracker and
+touches no code; only `ci.yml` gates, and it is the one to look at when
 deciding whether a push was healthy.
 
-**`release.yml` is the entry point for all of it.** On every push to
-`main` it reads the Conventional Commits since the last tag and, if any
+**`release.yml` is the entry point for all of it, and it is triggered by
+hand.** It reads the Conventional Commits since the last tag and, if any
 is releasable, writes the changelog, pushes the tag and creates the Gitea
 release whose body is that changelog section. `arch-package`,
 `homebrew-formula`, `android-apk` and `desktop-assets` are all keyed on
-`v*`, so **the tag push is what starts them** — nothing is released by
-hand any more.
+`v*`, so **the tag push is what starts them** — the version, the notes
+and the packaging are still nobody's manual work; *when* is the only
+decision left to a person.
+
+**It used to fire on every push to `main`, which made the trigger "a PR
+was merged".** That is a version per unit of *work* rather than per
+*shipment*: eight releases in twenty-two hours (`v0.0.1` → `v0.3.1`) for
+one session, each fanning out to four publishers on a runner with
+capacity 1 — ~40 packaging jobs to ship three issues, with ordinary PR CI
+queued behind them. Nothing else had to change to batch them, because
+**semantic-release already reads every commit since the last tag**: five
+`fix`es and two `feat`s become one minor release with all seven in the
+notes. Release frequency was only ever how often the workflow fired.
+
+This is the same rule `index-artifact.yml` states — *a job that mutates
+state which cannot be rebuilt in ten minutes is triggered deliberately,
+not by a push* — and the two are now the only workflows with no push
+trigger. A schedule was considered and rejected: a cron batches without
+anyone having to remember, but it puts the decision back on a timer,
+which is the thing being removed. A `beta` integration branch was
+considered and rejected too (#115): it relocates the trigger rather than
+removing one, needs a second protected branch carrying the same required
+checks, and *adds* a full `check` + `e2e` run per batch on the very
+runner whose queue is the complaint.
+
+**`dry_run` is why the manual trigger is usable.** The point of pulling
+a lever by hand is being able to look first, so the dispatch takes a
+flag that runs `semantic-release --dry-run`: the version and the notes,
+no tag, no release, no publishers. Anything but the literal string
+`true` releases for real — a typo in a dispatch box must not silently
+turn a shipment into a green no-op.
+
+**A prerelease tag is not a shipment, and all four publishers now say
+so.** Their trigger is `v*`, which matches `v0.4.0-beta.1`; they guarded
+`v0.0.0` and nothing else. Nothing produces a prerelease today — the
+guard is there because the thing that would is `prerelease: true` in
+`.releaserc.yml`, one line whose blast radius is a public Homebrew tap
+and a credential-free APK registry that Obtainium polls. `android-apk`
+is the worst of the four twice over, since its `versionCode` maths
+splits on dots and would read `1` out of `0-beta` — a wrong number
+rather than a failed build, and Android refuses anything not greater
+than what is installed.
 
 Four things about it are load-bearing:
 

Makefile

@@ -192,15 +192,21 @@ skill-check: ## Fail if the agent docs name a missing make target, or AGENTS.md
 commit-check: ## Fail if a commit subject is not a Conventional Commit
 	@./scripts/commit-check.sh $(if $(RANGE),--range $(RANGE))
 
-# What a merge to main would release, without releasing it.  Reads the
-# same .releaserc.yml CI does, so "why did that not cut a version" is
-# answerable locally instead of by pushing and watching.  Needs no
-# credentials: --dry-run neither tags nor publishes.
+# What running the release workflow now would ship, without shipping it.
+# Reads the same .releaserc.yml CI does, so "why did that not cut a
+# version" is answerable locally instead of by pushing and watching.
+# Needs no credentials: --dry-run neither tags nor publishes.
+#
+# release.yml is dispatch-only, so this answers the question that
+# actually gets asked now -- what has accumulated since the last tag --
+# rather than what one merge would have done.  The workflow's own
+# `dry_run` input is the same answer from the runner, against whatever
+# main points at rather than the working tree.
 #
 # The pins must stay identical to release.yml's, which is where the note
 # on holding the conventionalcommits preset at 9 lives -- at 10 the
 # release notes come out empty with everything green.
-release-dry: ## Print the version a merge to main would release
+release-dry: ## Print the version a release run would cut right now
 	@npx --yes \
 		-p semantic-release@25 \
 		-p @semantic-release/commit-analyzer@13 \

README.md

@@ -106,5 +106,8 @@ make dev          # run with hot-reload
 make build-prod   # produce a release binary
 ```
 
-More detail for contributors lives in
-[`docs/dev/overview.md`](./docs/dev/overview.md) and [`CLAUDE.md`](./CLAUDE.md).
+More detail for contributors lives in [`CLAUDE.md`](./CLAUDE.md) — the
+architecture, the conventions and the reasons behind them. What is
+being worked on is [the issue
+tracker](https://git.ljones.me/yonlu/yellowjacket/issues); #73 is the
+roadmap.

backend/autotag/apply.go

@@ -8,6 +8,7 @@ import (
 	"log/slog"
 
 	"yellowjacket/backend/database/sql/sqlcgen"
+	"yellowjacket/backend/tagtotals"
 )
 
 // TagChanges mirrors tagwriter.TagChanges — redefined here so the
@@ -28,6 +29,8 @@ const (
 	FieldYear        = "year"
 	FieldTrackNumber = "track_number"
 	FieldDiscNumber  = "disc_number"
+	FieldTotalTracks = "total_tracks"
+	FieldTotalDiscs  = "total_discs"
 	FieldCoverArt    = "cover_art"
 )
 
@@ -418,5 +421,32 @@ func buildChanges(
 		changes[FieldDiscNumber] = track.DiscNumber
 	}
 
+	// The totals are what says "2 of 10" rather than a bare tick, and
+	// dropping them here is what made autotagging an album *erase* the
+	// evidence: the release becomes MBID-matched while the field
+	// GetAlbumCompleteness reads stays absent.
+	//
+	// They are written unconditionally where the candidate has a
+	// tracklist, not only when they differ from the local value, because
+	// the common case is a file that declares no total at all -- which
+	// compares equal to nothing and would be skipped by a diff guard.
+	if tracks, discs := tagtotals.For(
+		candidatePositions(cand), track.DiscNumber,
+	); tracks > 0 {
+		changes[FieldTotalTracks] = tracks
+		changes[FieldTotalDiscs] = discs
+	}
+
 	return changes
 }
+
+// candidatePositions is the candidate's tracklist as bare positions.
+func candidatePositions(cand Candidate) []tagtotals.Position {
+	out := make([]tagtotals.Position, 0, len(cand.Tracks))
+
+	for _, t := range cand.Tracks {
+		out = append(out, tagtotals.Position{Disc: t.DiscNumber, Track: t.Position})
+	}
+
+	return out
+}

backend/autotag/buildchanges_test.go

@@ -0,0 +1,90 @@
+package autotag
+
+import "testing"
+
+// Autotagging an album used to *erase* the evidence that says "2 of 10":
+// the release became MBID-matched while the totals the files declared
+// went unwritten, so the album page showed a plain tick.  These pin the
+// two halves of the fix that are easy to get wrong silently.
+func TestBuildChanges_Totals(t *testing.T) {
+	t.Parallel()
+
+	twoDiscs := Candidate{
+		Tracks: []CandidateTrack{
+			{DiscNumber: 1, Position: 1},
+			{DiscNumber: 1, Position: 2},
+			{DiscNumber: 2, Position: 1},
+			{DiscNumber: 2, Position: 2},
+			{DiscNumber: 2, Position: 3},
+		},
+	}
+
+	tests := []struct {
+		name       string
+		cand       Candidate
+		local      LocalTrack
+		track      CandidateTrack
+		wantTracks any
+		wantDiscs  any
+	}{
+		{
+			// The common case, and the one a diff guard would skip: the
+			// file declares no total at all, so the total "has not
+			// changed" and would never be written.
+			name: "a file with no total gets one",
+			cand: Candidate{Tracks: []CandidateTrack{
+				{Position: 1}, {Position: 2}, {Position: 3},
+			}},
+			local:      LocalTrack{TrackNumber: 1},
+			track:      CandidateTrack{Position: 1},
+			wantTracks: 3,
+			wantDiscs:  1,
+		},
+		{
+			// 5 here would be the release's track count.  Summed once
+			// per disc by GetAlbumCompleteness that claims a ten-track
+			// expectation for a five-track album, which no library can
+			// ever satisfy.
+			name:       "a multi-disc release totals the track's own disc",
+			cand:       twoDiscs,
+			local:      LocalTrack{},
+			track:      CandidateTrack{DiscNumber: 2, Position: 1},
+			wantTracks: 3,
+			wantDiscs:  2,
+		},
+		{
+			name:       "the other disc gets its own total",
+			cand:       twoDiscs,
+			local:      LocalTrack{},
+			track:      CandidateTrack{DiscNumber: 1, Position: 1},
+			wantTracks: 2,
+			wantDiscs:  2,
+		},
+		{
+			// A candidate with no tracklist knows nothing, and writing
+			// a zero would claim it did.
+			name:       "a candidate with no tracklist writes no total",
+			cand:       Candidate{},
+			local:      LocalTrack{},
+			track:      CandidateTrack{Position: 1},
+			wantTracks: nil,
+			wantDiscs:  nil,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			changes := buildChanges(tc.local, tc.cand, tc.track)
+
+			if got := changes[FieldTotalTracks]; got != tc.wantTracks {
+				t.Errorf("%s: got %v, want %v", FieldTotalTracks, got, tc.wantTracks)
+			}
+
+			if got := changes[FieldTotalDiscs]; got != tc.wantDiscs {
+				t.Errorf("%s: got %v, want %v", FieldTotalDiscs, got, tc.wantDiscs)
+			}
+		})
+	}
+}

backend/autotag/recommend.go

@@ -17,6 +17,34 @@ const (
 	RecommendationStrong Recommendation = "strong"
 )
 
+// ConfidentTier is the tier at which this package considers a match
+// good enough to act on without being asked to look.
+//
+// It exists as a name rather than as `== RecommendationStrong` at
+// each call site because two features read it and they must not
+// disagree about what "high confidence" means: the album page tells
+// the user unprompted that the autotagger has a match (#28), and
+// strict auto-accept will rewrite the files without asking (#90).
+// A page that says "we are sure" about something the auto-accept
+// pass would decline is the app contradicting itself.
+//
+// What the two do *not* share is everything else. Surfacing a match
+// is a suggestion with a confirm dialog behind it; auto-accept is an
+// irreversible on-disk rewrite, and #90 gates it on further
+// conditions this tier cannot express — exact track count, every
+// title matching, lengths within a couple of seconds, no cover
+// replacement, no MBID conflict. So this is the floor both stand on,
+// not the whole of either test.
+const ConfidentTier = RecommendationStrong
+
+// Confident reports whether a tier clears ConfidentTier.
+//
+// A comparison rather than an equality, so adding a tier above
+// "strong" later does not silently stop qualifying.
+func Confident(r Recommendation) bool {
+	return recommendationRank(r) >= recommendationRank(ConfidentTier)
+}
+
 const (
 	// Absolute score tiers.
 	strongScoreThresh = 0.90

backend/autotag/recommend_test.go

@@ -168,3 +168,34 @@ func TestRecommend_LocalCandidatesWithoutRGMBIDCompareByTitle(t *testing.T) {
 		t.Errorf("different-title rival: Recommend = %q, want medium", got)
 	}
 }
+
+// The tier both features stand on is one name, checked here rather
+// than assumed at two call sites.
+//
+// #28 renders "we have a match for this album" on the album page and
+// #90 will rewrite files without asking; a page that claims confidence
+// the auto-accept pass would decline is the app contradicting itself.
+// What they do not share is everything else — auto-accept adds gates
+// this tier cannot express — so this pins the floor, not the whole of
+// either test.
+func TestConfidentIsTheOneSharedFloor(t *testing.T) {
+	t.Parallel()
+
+	if ConfidentTier != RecommendationStrong {
+		t.Errorf("ConfidentTier = %q, want strong", ConfidentTier)
+	}
+
+	for _, tc := range []struct {
+		rec  Recommendation
+		want bool
+	}{
+		{RecommendationNone, false},
+		{RecommendationLow, false},
+		{RecommendationMedium, false},
+		{RecommendationStrong, true},
+	} {
+		if got := Confident(tc.rec); got != tc.want {
+			t.Errorf("Confident(%q) = %v, want %v", tc.rec, got, tc.want)
+		}
+	}
+}

backend/autotagservice/albummatch.go

@@ -0,0 +1,145 @@
+package autotagservice
+
+import (
+	"database/sql"
+	"fmt"
+
+	"yellowjacket/backend/autotag"
+)
+
+// AlbumMatchView is "the autotagger already has a confident match for
+// the album you are looking at".
+//
+// It is deliberately not a score. The album page renders a suggestion,
+// and a suggestion has to be actionable: which release, what it is
+// called, and whether acting on it here would do the whole album or
+// only part of it.
+type AlbumMatchView struct {
+	// GroupKey is the tagging group the actions operate on.
+	GroupKey string `json:"groupKey"`
+
+	// Recommendation is the tier, as a string, for a caller that
+	// wants to render the strength rather than trust the filter.
+	Recommendation string `json:"recommendation"`
+
+	// Score is the top candidate's raw score, 0..1.
+	Score float64 `json:"score"`
+
+	// ReleaseMBID is the release Apply would write.
+	ReleaseMBID string `json:"releaseMbid"`
+
+	// Title and ArtistCredit name that release, so the banner can say
+	// what it is offering rather than "a match".
+	Title        string `json:"title"`
+	ArtistCredit string `json:"artistCredit"`
+
+	// TrackCount is the group's local track count.
+	TrackCount int64 `json:"trackCount"`
+
+	// GroupCount is how many tagging groups this album spans.
+	//
+	// More than one means a multi-disc album (one group per disc), and
+	// it is the reason this is a field rather than an implementation
+	// detail: applying "the album" from a single button would retag
+	// one disc of three and leave the folder holding a mix of old and
+	// new tags. The caller offers review instead.
+	GroupCount int `json:"groupCount"`
+}
+
+// MatchForAlbum answers "does the autotagger have something confident
+// to say about this album", for the album detail page.
+//
+// Three things about it are load-bearing.
+//
+// **It costs no MusicBrainz request.** Everything it needs is already
+// on disk: `tagging_items` carries the top score and release from the
+// background prefetch, and `tagging_candidates` durably holds the
+// scored list. The rate limiters here are shared with every page the
+// user can open, so a lookup that fires on page load must not join
+// that queue — which also means this returns nothing for a folder
+// nobody has scored yet, rather than scoring it now. That is the
+// right trade: the prefetch will get to it, and a page that silently
+// spends a minute of somebody's MusicBrainz budget to draw a banner
+// is worse than a page that says nothing.
+//
+// **The tier is computed, not read.** `tagging_items.score` is the raw
+// number and `Recommend` is what turns it into a claim — capping it
+// for an ambiguous runner-up, an incomplete alignment or a folder too
+// small to corroborate itself. Filtering on the raw score would
+// promise confidence the scorer had explicitly withheld.
+//
+// **Nothing is said about an album the user has already answered
+// for.** Only a `pending` group qualifies: `confirmed` covers both a
+// finished apply and an explicit "leave as is", and `skipped` is the
+// user saying not now. Re-offering either is nagging, and "leave as
+// is" would be actively wrong to argue with.
+func (s *Service) MatchForAlbum(albumID int64) (*AlbumMatchView, error) {
+	if albumID <= 0 {
+		return nil, nil //nolint:nilnil // "no album" is not an error.
+	}
+
+	rows, err := s.db.Queries.GetTaggingItemsForAlbum(
+		s.ctx, sql.NullInt64{Int64: albumID, Valid: true},
+	)
+	if err != nil {
+		return nil, fmt.Errorf("tagging items for album: %w", err)
+	}
+
+	pending := rows[:0:0]
+
+	for _, row := range rows {
+		if row.Status == "pending" {
+			pending = append(pending, row)
+		}
+	}
+
+	if len(pending) == 0 {
+		return nil, nil //nolint:nilnil // nothing to say is not an error.
+	}
+
+	// Rows arrive best-score-first, so the first pending one is the
+	// group worth describing. On a multi-disc album that is one disc
+	// of several and GroupCount says so.
+	best := pending[0]
+
+	cands := s.lookupCachedCandidates(best.GroupKey)
+	if len(cands) == 0 {
+		return nil, nil //nolint:nilnil // not scored yet; see the doc comment.
+	}
+
+	locals, err := s.scorer.LocalTracksForGroup(s.ctx, best.GroupKey)
+	if err != nil {
+		return nil, fmt.Errorf("local tracks for group: %w", err)
+	}
+
+	group := autotag.Group{
+		AlbumName:   best.AlbumName,
+		AlbumArtist: best.AlbumArtist,
+		Tracks:      locals,
+		Synthetic:   best.Synthetic != 0,
+	}
+
+	rec := autotag.Recommend(group, cands)
+	if !autotag.Confident(rec) {
+		return nil, nil //nolint:nilnil // not confident enough to interrupt.
+	}
+
+	top := cands[0]
+
+	// The release the banner names must be the release Apply would
+	// write. Apply with an empty MBID takes the top cached candidate,
+	// which is what this reads — but it is passed explicitly anyway,
+	// so a rescore between the page rendering and the user clicking
+	// cannot swap the album out from under a button they have already
+	// read.
+	return &AlbumMatchView{
+		GroupKey:       best.GroupKey,
+		Recommendation: string(rec),
+		Score:          top.Score,
+		ReleaseMBID:    top.ReleaseMBID,
+		Title:          top.Title,
+		ArtistCredit:   top.ArtistCredit,
+		TrackCount:     best.TrackCount,
+		GroupCount:     len(pending),
+	}, nil
+}

backend/autotagservice/albummatch_test.go

@@ -0,0 +1,320 @@
+package autotagservice
+
+import (
+	"encoding/json"
+	"testing"
+
+	"yellowjacket/backend/autotag"
+	"yellowjacket/backend/database"
+)
+
+// seedAlbumGroup writes one album's files, its tagging item and the
+// durable candidate blob the prefetch would have left behind.
+//
+// The candidate list is what a real one looks like in the two ways
+// that decide the tier: a per-track alignment for every local track,
+// and a runner-up far enough away not to count as ambiguity.
+func seedAlbumGroup(
+	t *testing.T,
+	db *database.DB,
+	groupKey string,
+	tracks int,
+	status string,
+	score float64,
+) int64 {
+	t.Helper()
+
+	for i := 1; i <= tracks; i++ {
+		database.InsertTestTrack(t, db, database.TestTrack{
+			FilePath:    filePathFor(groupKey, i),
+			Title:       titleFor(i),
+			Artist:      "Tideline",
+			Album:       "Glass Harbour",
+			AlbumArtist: "Tideline",
+			TrackNumber: int64(i),
+			LengthMs:    200000,
+			LibraryID:   0,
+			GroupKey:    groupKey,
+		})
+	}
+
+	if _, err := db.ExecContext(`
+		INSERT INTO tagging_items
+		    (group_key, library_id, track_count, album_name, album_artist,
+		     disc_number, status, score, best_match_release_mbid)
+		VALUES (?, 0, ?, 'Glass Harbour', 'Tideline', 0, ?, ?, 'rel-1')
+	`, groupKey, tracks, status, score); err != nil {
+		t.Fatalf("insert tagging item: %v", err)
+	}
+
+	var albumID int64
+	if err := db.QueryRowWriter(
+		`SELECT album_id FROM audio_files WHERE group_key = ? LIMIT 1`, groupKey,
+	).Scan(&albumID); err != nil {
+		t.Fatalf("read album id: %v", err)
+	}
+
+	return albumID
+}
+
+func filePathFor(groupKey string, n int) string {
+	return "/music/" + groupKey + "/0" + string(rune('0'+n)) + ".mp3"
+}
+
+func titleFor(n int) string {
+	return "Track " + string(rune('0'+n))
+}
+
+// storeCandidates writes the durable blob GetCandidates would have
+// cached, with `top` as the winning score.
+func storeCandidates(
+	t *testing.T, db *database.DB, groupKey string, tracks int, top float64,
+) {
+	t.Helper()
+
+	aligns := make([]autotag.TrackAlignment, 0, tracks)
+	for i := range tracks {
+		aligns = append(aligns, autotag.TrackAlignment{
+			Status:     autotag.AlignmentMatched,
+			LocalIndex: i,
+		})
+	}
+
+	cands := []autotag.Candidate{
+		{
+			ReleaseMBID:      "rel-1",
+			ReleaseGroupMBID: "rg-1",
+			Title:            "Glass Harbour",
+			ArtistCredit:     "Tideline",
+			TrackCount:       tracks,
+			Alignments:       aligns,
+			Score:            top,
+		},
+		{
+			ReleaseMBID:      "rel-2",
+			ReleaseGroupMBID: "rg-2",
+			Title:            "Something Else",
+			ArtistCredit:     "Another Band",
+			TrackCount:       tracks,
+			Score:            0.40,
+		},
+	}
+
+	blob, err := json.Marshal(cands)
+	if err != nil {
+		t.Fatalf("marshal candidates: %v", err)
+	}
+
+	if _, err := db.ExecContext(
+		`INSERT INTO tagging_candidates (group_key, candidates) VALUES (?, ?)`,
+		groupKey, string(blob),
+	); err != nil {
+		t.Fatalf("insert candidates: %v", err)
+	}
+}
+
+// A confident match is what the album page exists to surface.
+func TestMatchForAlbumSurfacesAConfidentMatch(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	albumID := seedAlbumGroup(t, db, "grp-1", 8, "pending", 0.95)
+	storeCandidates(t, db, "grp-1", 8, 0.95)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got == nil {
+		t.Fatal("no match returned for a strong candidate")
+	}
+
+	if got.Recommendation != string(autotag.RecommendationStrong) {
+		t.Errorf("recommendation = %q, want strong", got.Recommendation)
+	}
+
+	// The release named is the release Apply would write — the page
+	// must not offer one album and tag another.
+	if got.ReleaseMBID != "rel-1" || got.Title != "Glass Harbour" {
+		t.Errorf("named %q/%q, want rel-1/Glass Harbour", got.ReleaseMBID, got.Title)
+	}
+
+	if got.GroupCount != 1 {
+		t.Errorf("groupCount = %d, want 1", got.GroupCount)
+	}
+}
+
+// The tier is computed from the candidates, not read off the raw
+// score — a high number the scorer would have capped must not reach
+// the page as confidence it withheld.
+func TestMatchForAlbumDoesNotTrustTheStoredScore(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	// Two tracks: below the evidence floor, so `Recommend` caps this
+	// at medium however well it scores.
+	albumID := seedAlbumGroup(t, db, "grp-2", 2, "pending", 0.99)
+	storeCandidates(t, db, "grp-2", 2, 0.99)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got != nil {
+		t.Errorf("surfaced %+v for a two-track folder, want nothing", got)
+	}
+}
+
+// A weak match is not worth interrupting for.
+func TestMatchForAlbumStaysQuietBelowTheTier(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	albumID := seedAlbumGroup(t, db, "grp-3", 8, "pending", 0.60)
+	storeCandidates(t, db, "grp-3", 8, 0.60)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got != nil {
+		t.Errorf("surfaced %+v for a 0.60 match, want nothing", got)
+	}
+}
+
+// An album the user has already answered for is not re-offered.
+//
+// `confirmed` covers both a finished apply and an explicit "leave as
+// is", and arguing with the second would be actively wrong.
+func TestMatchForAlbumRespectsAnAnswerAlreadyGiven(t *testing.T) {
+	t.Parallel()
+
+	for _, status := range []string{"confirmed", "skipped", "matched"} {
+		t.Run(status, func(t *testing.T) {
+			t.Parallel()
+
+			db := database.NewTestDB(t)
+			svc := newTestService(t, db)
+
+			albumID := seedAlbumGroup(t, db, "grp-"+status, 8, status, 0.95)
+			storeCandidates(t, db, "grp-"+status, 8, 0.95)
+
+			got, err := svc.MatchForAlbum(albumID)
+			if err != nil {
+				t.Fatalf("MatchForAlbum: %v", err)
+			}
+
+			if got != nil {
+				t.Errorf("surfaced %+v for a %s group, want nothing", got, status)
+			}
+		})
+	}
+}
+
+// A folder nobody has scored yet says nothing, rather than scoring it
+// now: the MusicBrainz limiter is shared with every page the user can
+// open, and this runs on page load.
+func TestMatchForAlbumMakesNoNetworkCallForAnUnscoredFolder(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	// No storeCandidates: the prefetch has not reached this folder.
+	albumID := seedAlbumGroup(t, db, "grp-4", 8, "pending", 0.95)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got != nil {
+		t.Errorf("surfaced %+v with no cached candidates, want nothing", got)
+	}
+}
+
+// A multi-disc album is several groups, and the count is what stops
+// the page offering one button that would retag one disc of two.
+func TestMatchForAlbumCountsEveryGroupOfTheAlbum(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	albumID := seedAlbumGroup(t, db, "grp-d1", 8, "pending", 0.95)
+	storeCandidates(t, db, "grp-d1", 8, 0.95)
+
+	// Disc two: same album row, its own folder and tagging group.
+	for i := 1; i <= 6; i++ {
+		database.InsertTestTrack(t, db, database.TestTrack{
+			FilePath:    filePathFor("grp-d2", i),
+			Title:       titleFor(i),
+			Artist:      "Tideline",
+			Album:       "Glass Harbour",
+			AlbumArtist: "Tideline",
+			TrackNumber: int64(i),
+			DiscNumber:  2,
+			LengthMs:    200000,
+			LibraryID:   0,
+			GroupKey:    "grp-d2",
+		})
+	}
+
+	if _, err := db.ExecContext(`
+		INSERT INTO tagging_items
+		    (group_key, library_id, track_count, album_name, album_artist,
+		     disc_number, status, score)
+		VALUES ('grp-d2', 0, 6, 'Glass Harbour', 'Tideline', 2, 'pending', 0.93)
+	`); err != nil {
+		t.Fatalf("insert disc two: %v", err)
+	}
+
+	storeCandidates(t, db, "grp-d2", 6, 0.93)
+
+	got, err := svc.MatchForAlbum(albumID)
+	if err != nil {
+		t.Fatalf("MatchForAlbum: %v", err)
+	}
+
+	if got == nil {
+		t.Fatal("no match returned")
+	}
+
+	if got.GroupCount != 2 {
+		t.Errorf("groupCount = %d, want 2", got.GroupCount)
+	}
+
+	// Best-first: the 0.95 disc is the one described.
+	if got.GroupKey != "grp-d1" {
+		t.Errorf("described %q, want the higher-scoring grp-d1", got.GroupKey)
+	}
+}
+
+// An album with no local files at all — a pure catalog page — is not
+// a question this can answer.
+func TestMatchForAlbumSaysNothingWithoutAnAlbum(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	svc := newTestService(t, db)
+
+	for _, id := range []int64{0, -1, 4242} {
+		got, err := svc.MatchForAlbum(id)
+		if err != nil {
+			t.Fatalf("MatchForAlbum(%d): %v", id, err)
+		}
+
+		if got != nil {
+			t.Errorf("MatchForAlbum(%d) = %+v, want nil", id, got)
+		}
+	}
+}

backend/autotagservice/fieldnames_test.go

@@ -0,0 +1,38 @@
+package autotagservice
+
+import (
+	"testing"
+
+	"yellowjacket/backend/autotag"
+	"yellowjacket/backend/tagwriter"
+)
+
+// twAdapter passes the diff map through unchanged, so autotag's field
+// constants and tagwriter's are the same keys written down twice --
+// deliberately, to keep autotag out of the write pipeline's import
+// graph.  A key that drifts does not fail to compile and does not fail
+// to write: the writer simply finds no entry under the name it looks
+// for, and the field is silently dropped.  That is what this pins, and
+// this package is the one place that imports both.
+func TestAutotagAndTagwriterAgreeOnFieldNames(t *testing.T) {
+	t.Parallel()
+
+	pairs := map[string][2]string{
+		"title":        {autotag.FieldTitle, tagwriter.FieldTitle},
+		"artist":       {autotag.FieldArtist, tagwriter.FieldArtist},
+		"album":        {autotag.FieldAlbum, tagwriter.FieldAlbum},
+		"album artist": {autotag.FieldAlbumArtist, tagwriter.FieldAlbumArtist},
+		"year":         {autotag.FieldYear, tagwriter.FieldYear},
+		"track number": {autotag.FieldTrackNumber, tagwriter.FieldTrackNumber},
+		"disc number":  {autotag.FieldDiscNumber, tagwriter.FieldDiscNumber},
+		"total tracks": {autotag.FieldTotalTracks, tagwriter.FieldTotalTracks},
+		"total discs":  {autotag.FieldTotalDiscs, tagwriter.FieldTotalDiscs},
+		"cover art":    {autotag.FieldCoverArt, tagwriter.FieldCoverArt},
+	}
+
+	for name, pair := range pairs {
+		if pair[0] != pair[1] {
+			t.Errorf("%s: autotag says %q, tagwriter says %q", name, pair[0], pair[1])
+		}
+	}
+}

backend/config/config.go

@@ -411,9 +411,10 @@ func (c *Config) SetDownloadPreferences(prefs download.AutoDownloadPrefs) error
 		formats = append(formats, string(f))
 	}
 
-	c.Downloads.MinFileSizeMB = prefs.MinSizeMB
+	c.Downloads.MinKbps = prefs.MinKbps
+	c.Downloads.MaxKbps = prefs.MaxKbps
+	c.Downloads.PreferredKbps = prefs.PreferredKbps
 	c.Downloads.MaxFileSizeMB = prefs.MaxSizeMB
-	c.Downloads.PreferredFileSizeMB = prefs.PreferredSizeMB
 	c.Downloads.AllowedFormats = formats
 
 	if err := c.Save(); err != nil {
@@ -543,7 +544,7 @@ func (c *Config) SetDefaultPage(page string) error {
 		c.General.ApplyDefaults()
 	}
 
-	c.General.DefaultPage = DefaultPage(page)
+	c.General.DefaultPage = View(page)
 
 	if err := c.General.Validate(); err != nil {
 		return fmt.Errorf(
@@ -665,6 +666,124 @@ func (c *Config) SetAllowMeteredCatalogDownload(allow bool) error {
 	return nil
 }
 
+// GetPopupVolume reports whether the bottom bar's volume control is a
+// click-to-open popup rather than an inline slider (#42).
+func (c *Config) GetPopupVolume() bool {
+	if c.General == nil {
+		return false
+	}
+
+	return c.General.PopupVolume
+}
+
+// SetPopupVolume saves the volume control's presentation.
+//
+// Nothing to validate: both values are legal at every width, and the
+// frontend additionally stands the inline slider down below the phone
+// breakpoint whatever this says, because that is about room rather than
+// about preference.
+func (c *Config) SetPopupVolume(popup bool) error {
+	if c.General == nil {
+		c.General = &GeneralConfig{}
+		c.General.ApplyDefaults()
+	}
+
+	c.General.PopupVolume = popup
+
+	if err := c.Save(); err != nil {
+		return fmt.Errorf(
+			"could not save config: %w", err,
+		)
+	}
+
+	events.Emit(
+		c.ctx,
+		events.GeneralConfigChanged,
+		map[string]any{
+			"PopupVolume": popup,
+		},
+	)
+
+	c.logger.Info("volume control presentation updated", "popup", popup)
+
+	return nil
+}
+
+// GetViewVisibility reports which primary views the sidebar should
+// show, answered for every known view rather than only the ones the
+// config mentions -- so the frontend filters on a value and never has
+// to hold a second copy of the defaults.
+func (c *Config) GetViewVisibility() map[string]bool {
+	if c.General == nil {
+		general := &GeneralConfig{}
+		general.ApplyDefaults()
+
+		return general.ResolvedViewVisibility()
+	}
+
+	return c.General.ResolvedViewVisibility()
+}
+
+// SetViewVisible shows or hides one primary view.
+//
+// Two refusals, both about a state the user cannot get out of from the
+// UI they would be left with: Settings is never hideable, and the
+// launch page is never hideable while it is the launch page (change it
+// first). Hiding a view does not make it unreachable -- `navigate`
+// still resolves it, which detail views depend on -- it only takes the
+// nav item away.
+func (c *Config) SetViewVisible(view string, visible bool) error {
+	spec, known := LookupView(view)
+	if !known {
+		return fmt.Errorf("%w: %q", errUnknownView, view)
+	}
+
+	if c.General == nil {
+		c.General = &GeneralConfig{}
+		c.General.ApplyDefaults()
+	}
+
+	if !visible {
+		if !spec.Hideable {
+			return fmt.Errorf("%w: %q", errViewNotHideable, view)
+		}
+
+		if spec.ID == c.General.DefaultPage {
+			return fmt.Errorf("%w: %q", errViewIsLaunchPage, view)
+		}
+	}
+
+	if c.General.ViewVisibility == nil {
+		c.General.ViewVisibility = make(map[string]bool, len(Views))
+	}
+
+	c.General.ViewVisibility[view] = visible
+
+	if err := c.General.Validate(); err != nil {
+		return fmt.Errorf("invalid view visibility: %w", err)
+	}
+
+	if err := c.Save(); err != nil {
+		return fmt.Errorf("could not save config: %w", err)
+	}
+
+	events.Emit(
+		c.ctx,
+		events.GeneralConfigChanged,
+		map[string]any{
+			"ViewVisibility": c.General.ResolvedViewVisibility(),
+		},
+	)
+
+	c.logger.Info(
+		"view visibility updated",
+		"view", view,
+		"visible", visible,
+	)
+
+	return nil
+}
+
 // GetTrackListColumns returns the configured track-list columns.
 func (c *Config) GetTrackListColumns() []tracklist.Column {
 	if c.TrackList == nil {

backend/config/emit_test.go

@@ -188,3 +188,43 @@ func TestEmit_FavoritesChangeCarriesFullConfig(t *testing.T) {
 		}
 	}
 }
+
+// TestEmit_PopupVolumeRoundTripsAndDefaultsToInline pins both halves of
+// #42's storage decision.
+//
+// The **default** is the load-bearing one: inline is what a fresh
+// install and an existing `config.toml` with no such key must both
+// produce, which is why the field names the popup rather than the
+// inline slider. A flag spelled the other way round would default to
+// false, hand every existing install the popup this issue exists to
+// stop being the only option, and need a migration to say otherwise.
+func TestEmit_PopupVolumeRoundTripsAndDefaultsToInline(t *testing.T) {
+	t.Parallel()
+
+	conf, rec := setupRecordedConfig(t)
+
+	if conf.GetPopupVolume() {
+		t.Error("a config with no PopupVolume key wants the popup, want inline")
+	}
+
+	if err := conf.SetPopupVolume(true); err != nil {
+		t.Fatalf("SetPopupVolume: %v", err)
+	}
+
+	if !conf.GetPopupVolume() {
+		t.Error("GetPopupVolume = false after setting it true")
+	}
+
+	data := payloadMap(t, rec, events.GeneralConfigChanged)
+	if data["PopupVolume"] != true {
+		t.Errorf("PopupVolume = %v, want true", data["PopupVolume"])
+	}
+
+	if err := conf.SetPopupVolume(false); err != nil {
+		t.Fatalf("SetPopupVolume(false): %v", err)
+	}
+
+	if conf.GetPopupVolume() {
+		t.Error("GetPopupVolume = true after setting it false")
+	}
+}

backend/config/general.go

@@ -5,27 +5,13 @@ import (
 	"fmt"
 )
 
-// DefaultPage identifies which view the app opens to on launch.
-type DefaultPage string
-
-// Valid DefaultPage values, matching the frontend's top-level route ids.
-const (
-	DefaultPageHome      DefaultPage = "home"
-	DefaultPageTracks    DefaultPage = "tracks"
-	DefaultPageAlbums    DefaultPage = "albums"
-	DefaultPageArtists   DefaultPage = "artists"
-	DefaultPageGenres    DefaultPage = "genres"
-	DefaultPagePlaylists DefaultPage = "playlists"
-	DefaultPageExplore   DefaultPage = "explore"
-	DefaultPageDownloads DefaultPage = "downloads"
-	DefaultPageAutotag   DefaultPage = "autotag"
-	DefaultPageJobs      DefaultPage = "jobs"
-)
-
 // DefaultDefaultPage is the launch page for a fresh install.
-const DefaultDefaultPage = DefaultPageHome
+const DefaultDefaultPage = ViewHome
 
-var errUnknownDefaultPage = errors.New("unknown default page")
+var (
+	errUnknownDefaultPage = errors.New("unknown default page")
+	errViewCannotLaunch   = errors.New("view cannot be the launch page")
+)
 
 // QueueFallback identifies what plays, if anything, once the queue
 // runs out with nothing left to auto-advance to.
@@ -46,18 +32,52 @@ var errUnknownQueueFallback = errors.New("unknown queue fallback")
 // GeneralConfig holds general application preferences that don't
 // belong to a more specific subsystem.
 type GeneralConfig struct {
-	DefaultPage   DefaultPage   `toml:"DefaultPage"`
+	DefaultPage   View          `toml:"DefaultPage"`
 	QueueFallback QueueFallback `toml:"QueueFallback"`
+	// ViewVisibility says which sidebar destinations are shown, keyed by
+	// view id.
+	//
+	// **An absent key means that view's own default** (`Views`), and that
+	// is the whole reason this is a map rather than a `HiddenViews
+	// []string` or a struct of booleans. A list's zero value is "hide
+	// nothing", which cannot express Autotag being off by default without
+	// a migration; a struct field for a view that later stops existing is
+	// stored garbage somebody has to deprecate. Here a view added later
+	// gets its own default rather than being invisible or forcibly
+	// visible, an unknown key is dropped on load, and no install needs
+	// migrating in either direction. Same polarity rule as
+	// AllowMeteredCatalogDownload: the zero value is the intended answer.
+	ViewVisibility map[string]bool `toml:"ViewVisibility"`
 	// AllowMeteredCatalogDownload permits the ~0.6 GB Explore catalog to
 	// be fetched on a connection the platform calls cellular. It defaults
 	// to false, which is the whole point: the zero value is the safe one,
 	// so an existing config with no such key refuses by default rather
 	// than needing a migration to become careful.
 	AllowMeteredCatalogDownload bool `toml:"AllowMeteredCatalogDownload"`
+	// PopupVolume draws the bottom bar's volume as a click-to-open popup
+	// instead of a slider that is always there (#42).
+	//
+	// The polarity is the rule this file already states twice: **the
+	// zero value is the intended answer**. Inline is the new default, so
+	// the flag has to name the *other* choice — an `InlineVolume bool`
+	// would default to false and give every existing install the popup
+	// this issue exists to stop being the only option, and would need a
+	// migration to say otherwise.
+	PopupVolume bool `toml:"PopupVolume"`
 }
 
 // ApplyDefaults fills zero-value fields with sensible defaults.
+//
+// A launch page naming a *retired* view is treated as a zero value
+// rather than as an error, because the alternative is an app that will
+// not start for anyone who had that page selected when it was removed.
+// An unknown-but-not-retired name still fails Validate: that is a typo,
+// and telling someone about it is the useful answer.
 func (c *GeneralConfig) ApplyDefaults() {
+	if _, retired := RetiredViews[c.DefaultPage]; retired {
+		c.DefaultPage = ""
+	}
+
 	if c.DefaultPage == "" {
 		c.DefaultPage = DefaultDefaultPage
 	}
@@ -71,15 +91,17 @@ func (c *GeneralConfig) ApplyDefaults() {
 func (c *GeneralConfig) Validate() error {
 	c.ApplyDefaults()
 
-	switch c.DefaultPage {
-	case DefaultPageHome, DefaultPageTracks, DefaultPageAlbums, DefaultPageArtists,
-		DefaultPageGenres, DefaultPagePlaylists, DefaultPageExplore, DefaultPageDownloads,
-		DefaultPageAutotag, DefaultPageJobs:
-		// Valid.
-	default:
+	spec, known := LookupView(string(c.DefaultPage))
+	if !known {
 		return fmt.Errorf("%w: %q", errUnknownDefaultPage, c.DefaultPage)
 	}
 
+	if !spec.CanLaunch {
+		return fmt.Errorf("%w: %q", errViewCannotLaunch, c.DefaultPage)
+	}
+
+	c.normalizeViewVisibility()
+
 	switch c.QueueFallback {
 	case QueueFallbackStop, QueueFallbackFavorites, QueueFallbackDynamicMix:
 		// Valid.
@@ -89,3 +111,51 @@ func (c *GeneralConfig) Validate() error {
 
 	return nil
 }
+
+// normalizeViewVisibility drops what the stored map may not say, and
+// repairs the one invariant the shell depends on.
+//
+// Three things are dropped or forced, and all three are reachable only
+// from a hand-edited config or from a version that knew different
+// views: an unknown id (a view removed since, e.g. when #27 folds Jobs
+// into Settings) says nothing to anybody; a view that is not Hideable
+// cannot be false; and **the launch page is always visible**, because
+// otherwise an install lands on a page with no nav item pointing at it.
+//
+// That last one is a *repair* here and an *error* at the setter
+// (SetViewVisible), deliberately. On load there is nobody to tell and
+// the honest reading of "my launch page is Autotag" is that this user
+// wants Autotag, so it is un-hidden rather than the launch page being
+// silently reset to something they did not choose. At the setter the
+// user is right there and can act, so it refuses and says why.
+func (c *GeneralConfig) normalizeViewVisibility() {
+	for id := range c.ViewVisibility {
+		spec, known := LookupView(id)
+		if !known || !spec.Hideable {
+			delete(c.ViewVisibility, id)
+		}
+	}
+
+	if visible, ok := c.ViewVisibility[string(c.DefaultPage)]; ok && !visible {
+		c.ViewVisibility[string(c.DefaultPage)] = true
+	}
+}
+
+// ResolvedViewVisibility answers for every known view, so no caller has
+// to know the defaults -- the frontend included, which is why the
+// binding returns this rather than the stored map.
+func (c *GeneralConfig) ResolvedViewVisibility() map[string]bool {
+	resolved := make(map[string]bool, len(Views))
+
+	for _, v := range Views {
+		visible := v.VisibleByDefault
+
+		if stored, ok := c.ViewVisibility[string(v.ID)]; ok && v.Hideable {
+			visible = stored
+		}
+
+		resolved[string(v.ID)] = visible
+	}
+
+	return resolved
+}

backend/config/views.go

@@ -0,0 +1,103 @@
+package config
+
+import "errors"
+
+var (
+	errUnknownView      = errors.New("unknown view")
+	errViewNotHideable  = errors.New("view cannot be hidden")
+	errViewIsLaunchPage = errors.New("view is the launch page")
+)
+
+// View identifies one of the shell's primary destinations -- the
+// things the sidebar lists and `index.ts` knows as `VIEW_TAGS`.
+type View string
+
+// The primary views, in no particular order: the sidebar owns the order
+// it draws them in, because that is presentation.
+const (
+	ViewHome      View = "home"
+	ViewPlaylists View = "playlists"
+	ViewArtists   View = "artists"
+	ViewGenres    View = "genres"
+	ViewAlbums    View = "albums"
+	ViewTracks    View = "tracks"
+	ViewExplore   View = "explore"
+	ViewDownloads View = "downloads"
+	ViewAutotag   View = "autotag"
+	ViewSettings  View = "settings"
+)
+
+// RetiredViews are destinations that used to exist and no longer do.
+//
+// A *visibility* entry for a removed view needs no such list: it is a
+// key in a map, and an unknown key is dropped on load. A `DefaultPage`
+// is a **value**, and an unknown one fails validation -- which on the
+// load path means the app refuses to start rather than a setting being
+// ignored. So the one shape that cannot be retired for free is named
+// here and reset to the default instead.
+//
+// `jobs` was folded into Settings by #27: library scans under
+// Libraries, index work under Search Index, downloads under the
+// download clients, and the autotag apply into the Autotag view.
+var RetiredViews = map[View]struct{}{
+	"jobs": {},
+}
+
+// ViewSpec is what the backend knows about a destination. The label and
+// the icon are deliberately absent: those are presentation, they live
+// beside the rest of the app's icon vocabulary in
+// `frontend/src/utils/icon-language.ts`, and a Go copy of them would be
+// a second thing to keep in step for nothing.
+type ViewSpec struct {
+	// ID is the view name the frontend navigates by.
+	ID View
+	// VisibleByDefault is what an install gets when the config says
+	// nothing about this view -- which is every install until somebody
+	// changes it, and every view added after this one shipped.
+	VisibleByDefault bool
+	// Hideable is false for Settings alone. It is a property of the
+	// view rather than a check in the setter because `config.toml` is
+	// hand-editable, and an app that can be locked out of its own
+	// Settings by a typo is a support problem nobody can debug
+	// remotely.
+	Hideable bool
+	// CanLaunch reports whether the view may be the launch page.
+	// Settings is the only one that may not, which is the shape the
+	// DefaultPage enum already had.
+	CanLaunch bool
+}
+
+// Views is the one list of primary destinations, in the order Settings
+// offers them.
+//
+// It is the single source for three things that used to be written down
+// separately: which views exist, which of them may be the launch page
+// (`DefaultPage`'s validation reads it), and what an unconfigured
+// install shows.
+//
+// Autotag is the one view hidden by default: it rewrites tags on disk,
+// which is not what most libraries want on day one, and #25 asks for it
+// to be turned on deliberately.
+var Views = []ViewSpec{
+	{ID: ViewHome, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewPlaylists, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewArtists, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewGenres, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewAlbums, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewTracks, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewExplore, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewDownloads, VisibleByDefault: true, Hideable: true, CanLaunch: true},
+	{ID: ViewAutotag, VisibleByDefault: false, Hideable: true, CanLaunch: true},
+	{ID: ViewSettings, VisibleByDefault: true, Hideable: false, CanLaunch: false},
+}
+
+// LookupView returns the spec for a view id.
+func LookupView(id string) (ViewSpec, bool) {
+	for _, v := range Views {
+		if string(v.ID) == id {
+			return v, true
+		}
+	}
+
+	return ViewSpec{}, false
+}

backend/config/views_test.go

@@ -0,0 +1,307 @@
+package config
+
+import (
+	"errors"
+	"log/slog"
+	"path/filepath"
+	"testing"
+)
+
+// newViewTestConfig builds a Config backed by a temp file, which is all
+// SetViewVisible needs: it saves and emits, and the emit is a no-op
+// without a running app.
+func newViewTestConfig(t *testing.T) *Config {
+	t.Helper()
+
+	c := &Config{
+		logger:   slog.Default(),
+		filePath: filepath.Join(t.TempDir(), "config.toml"),
+	}
+
+	// Load a file that is not there: that is what marks the config
+	// loaded, without which Save refuses on the *second* write.
+	if err := c.Load(); err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	return c
+}
+
+// A view the config says nothing about takes its own default, which is
+// what makes this need no migration in either direction: an existing
+// install gets Autotag hidden without a key, and a view added later
+// gets its own answer rather than the list's.
+func TestViewVisibilityDefaults(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{}
+	general.ApplyDefaults()
+
+	resolved := general.ResolvedViewVisibility()
+
+	if len(resolved) != len(Views) {
+		t.Fatalf("resolved %d views, want %d", len(resolved), len(Views))
+	}
+
+	if resolved[string(ViewAutotag)] {
+		t.Error("autotag should be hidden by default")
+	}
+
+	for _, v := range Views {
+		if v.ID == ViewAutotag {
+			continue
+		}
+
+		if !resolved[string(v.ID)] {
+			t.Errorf("%s should be visible by default", v.ID)
+		}
+	}
+}
+
+// A stored answer wins over the default, in both directions -- turning
+// Autotag on is the whole user-facing point.
+func TestViewVisibilityStoredWins(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{
+		ViewVisibility: map[string]bool{
+			string(ViewAutotag): true,
+			string(ViewExplore): false,
+		},
+	}
+	general.ApplyDefaults()
+
+	resolved := general.ResolvedViewVisibility()
+
+	if !resolved[string(ViewAutotag)] {
+		t.Error("autotag was switched on and should be visible")
+	}
+
+	if resolved[string(ViewExplore)] {
+		t.Error("explore was switched off and should be hidden")
+	}
+}
+
+// A key for a view that no longer exists is discarded rather than
+// migrated. This is the property the #25-before-#27 ordering rests on:
+// when Jobs folds into Settings, `jobs = true` in somebody's config is
+// a key nothing asks about, not a cleanup task.
+func TestValidateDropsUnknownAndUnhideableViews(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{
+		ViewVisibility: map[string]bool{
+			"a-view-that-was-removed": true,
+			string(ViewSettings):      false,
+			string(ViewAutotag):       true,
+		},
+	}
+
+	if err := general.Validate(); err != nil {
+		t.Fatalf("Validate() error: %v", err)
+	}
+
+	if _, ok := general.ViewVisibility["a-view-that-was-removed"]; ok {
+		t.Error("an unknown view id should be dropped on load")
+	}
+
+	if _, ok := general.ViewVisibility[string(ViewSettings)]; ok {
+		t.Error("settings is not hideable and should not be stored")
+	}
+
+	if !general.ResolvedViewVisibility()[string(ViewSettings)] {
+		t.Error("settings must resolve visible whatever the file said")
+	}
+}
+
+// On load there is nobody to tell, so a launch page hidden by a
+// hand-edited file is un-hidden rather than the launch page being
+// reset to something the user did not choose.
+func TestValidateRevealsAHiddenLaunchPage(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{
+		DefaultPage: ViewAutotag,
+		ViewVisibility: map[string]bool{
+			string(ViewAutotag): false,
+		},
+	}
+
+	if err := general.Validate(); err != nil {
+		t.Fatalf("Validate() error: %v", err)
+	}
+
+	if !general.ResolvedViewVisibility()[string(ViewAutotag)] {
+		t.Error("the launch page must be visible")
+	}
+}
+
+// A launch page naming a view that no longer exists resets to the
+// default instead of failing validation, which on the load path would
+// mean the app refusing to start for whoever had it selected.
+//
+// This is the one shape #25's storage decision does *not* make free: a
+// visibility entry is a key and an unknown key is dropped, but a launch
+// page is a value.
+func TestARetiredLaunchPageFallsBackToTheDefault(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{DefaultPage: "jobs"}
+
+	if err := general.Validate(); err != nil {
+		t.Fatalf("Validate() error: %v", err)
+	}
+
+	if general.DefaultPage != DefaultDefaultPage {
+		t.Errorf("DefaultPage = %q, want %q", general.DefaultPage, DefaultDefaultPage)
+	}
+}
+
+// A name that is merely wrong is still an error: that is a typo, and
+// saying so is more useful than ignoring it.
+func TestAnUnknownLaunchPageIsStillAnError(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{DefaultPage: "nonsense"}
+
+	if err := general.Validate(); !errors.Is(err, errUnknownDefaultPage) {
+		t.Fatalf("Validate() error = %v, want errUnknownDefaultPage", err)
+	}
+}
+
+// A retired view is not a view, so nothing offers it and nothing
+// resolves it -- the visibility map included.
+func TestARetiredViewIsGone(t *testing.T) {
+	t.Parallel()
+
+	for id := range RetiredViews {
+		if _, ok := LookupView(string(id)); ok {
+			t.Errorf("%s is retired but still in Views", id)
+		}
+
+		general := &GeneralConfig{}
+		general.ApplyDefaults()
+
+		if _, ok := general.ResolvedViewVisibility()[string(id)]; ok {
+			t.Errorf("%s is retired but still resolves a visibility", id)
+		}
+	}
+}
+
+// Settings may not be the launch page, which is the shape the old
+// DefaultPage enum had and is now read off the same table.
+func TestValidateRejectsAnUnlaunchablePage(t *testing.T) {
+	t.Parallel()
+
+	general := &GeneralConfig{DefaultPage: ViewSettings}
+
+	err := general.Validate()
+	if !errors.Is(err, errViewCannotLaunch) {
+		t.Fatalf("Validate() error = %v, want errViewCannotLaunch", err)
+	}
+}
+
+// At the setter the user is present and can act, so the two states
+// they could not get out of are refused rather than repaired.
+func TestSetViewVisibleRefusals(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		view    string
+		visible bool
+		want    error
+	}{
+		{"settings is never hideable", string(ViewSettings), false, errViewNotHideable},
+		{"the launch page is not hideable", string(ViewHome), false, errViewIsLaunchPage},
+		{"an unknown view is not a setting", "nonsense", false, errUnknownView},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			c := newViewTestConfig(t)
+
+			err := c.SetViewVisible(tt.view, tt.visible)
+			if !errors.Is(err, tt.want) {
+				t.Fatalf("SetViewVisible() error = %v, want %v", err, tt.want)
+			}
+		})
+	}
+}
+
+// Showing a view is never refused, including Settings and the launch
+// page -- there is no state to be stuck in.
+func TestSetViewVisibleShowsAnything(t *testing.T) {
+	t.Parallel()
+
+	c := newViewTestConfig(t)
+
+	for _, v := range Views {
+		if err := c.SetViewVisible(string(v.ID), true); err != nil {
+			t.Fatalf("SetViewVisible(%q, true) error: %v", v.ID, err)
+		}
+	}
+
+	if !c.GetViewVisibility()[string(ViewAutotag)] {
+		t.Error("autotag was switched on and should be visible")
+	}
+}
+
+// The stored map survives a save/load round trip, which is what a
+// map-valued TOML key is worth checking for.
+func TestViewVisibilityRoundTrips(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "config.toml")
+
+	original := &Config{logger: slog.Default(), filePath: path}
+	if err := original.Load(); err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	if err := original.SetViewVisible(string(ViewAutotag), true); err != nil {
+		t.Fatalf("SetViewVisible() error: %v", err)
+	}
+
+	if err := original.SetViewVisible(string(ViewExplore), false); err != nil {
+		t.Fatalf("SetViewVisible() error: %v", err)
+	}
+
+	loaded := &Config{logger: slog.Default(), filePath: path}
+	if err := loaded.Load(); err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	resolved := loaded.GetViewVisibility()
+
+	if !resolved[string(ViewAutotag)] {
+		t.Error("autotag should have loaded as visible")
+	}
+
+	if resolved[string(ViewExplore)] {
+		t.Error("explore should have loaded as hidden")
+	}
+}
+
+// Every view the shell can launch into is a view the sidebar can show,
+// or an install could land on a page with no nav item and no setting
+// pointing at it.
+func TestEveryLaunchableViewIsAView(t *testing.T) {
+	t.Parallel()
+
+	for _, v := range Views {
+		if !v.CanLaunch {
+			continue
+		}
+
+		if !v.Hideable {
+			continue
+		}
+
+		if _, ok := LookupView(string(v.ID)); !ok {
+			t.Errorf("%s is launchable but not a known view", v.ID)
+		}
+	}
+}

backend/config/window.go

@@ -13,13 +13,31 @@ const (
 	// enforces this at runtime; it is also the floor below which a
 	// reported size is treated as bogus and not persisted.
 	//
-	// 800x600 is where the shell was measured to still work, rather
-	// than a round number: below ~780 the header's subtitle wraps and
-	// pushes the title out of the 4em top bar, and below ~600 tall the
-	// eleven sidebar items no longer fit at once.  The previous
-	// 512x384 was aspirational — at 700x480 the sidebar overflowed
-	// behind the player bar with no scroll and Settings and Jobs could
-	// not be reached at all.
+	// **Both reasons this comment used to give have expired**, and the
+	// value is right for a third one.  It said the floor was 800x600
+	// because "below ~780 the header's subtitle wraps and pushes the
+	// title out of the 4em top bar" and "below ~600 tall the eleven
+	// sidebar items no longer fit at once".  Neither mechanism can
+	// happen now: the subtitle is display:none from 899px down
+	// (index.css), and the sidebar host is overflow-y:auto — measured
+	// at 600x460, its scrollHeight is 434 against a 332px client and
+	// Settings is reachable after scrolling.  A floor defended by two
+	// mechanisms that no longer exist is a number nobody can argue
+	// with, which is worse than either answer.
+	//
+	// It stays 800x600 because that is where the *desktop* chrome
+	// stops being comfortable — the Compact band of plan 018's size
+	// matrix (#24) — and not because the app breaks below it.  It does
+	// not: under 600px wide the phone layout takes over (bottom-nav,
+	// no sidebar) and the shell fits 320px exactly, which is what
+	// makes this a comfort floor rather than a correctness one, and
+	// why a very small window reflows instead of becoming a
+	// mini-player (#12 is a second always-on-top window, not a mode of
+	// this one).
+	//
+	// The previous 512x384 was aspirational — at 700x480 the sidebar
+	// overflowed behind the player bar with no scroll and Settings and
+	// Jobs could not be reached at all.
 	MinWidth = 800
 	// MinHeight is the smallest allowed window height in pixels.
 	MinHeight = 600

backend/database/sql/queries/albums.sql

@@ -135,3 +135,49 @@ SELECT
     ) AS INTEGER) AS known
 FROM audio_files a
 WHERE a.album_id = sqlc.arg(album_id);
+
+-- name: GetAlbumsCompleteness :many
+-- The same question as GetAlbumCompleteness, asked of a screenful of
+-- albums at once.
+--
+-- A card grid cannot afford one query per card, and the answer it wants
+-- is the one thing a badge cannot guess: an album held 9 tracks of 12
+-- must show the count, never a bare tick.  So this is one query for the
+-- whole grid, asked only of the cards that have a local album id.
+--
+-- It is two grouping levels rather than the single-album form's
+-- correlated subqueries, because a correlated subquery in the FROM
+-- clause is not something SQLite will reliably do -- and because the
+-- slice may only be spelled once, or sqlc expands it twice with
+-- independently numbered placeholders.
+--
+-- The per-disc level is where the meaning is, and it is the same
+-- meaning as the single-album query.  `owned` counts DISTINCT track
+-- numbers within a disc (this app detects duplicates, and counting two
+-- files of track 3 twice would report a short album as complete), with
+-- a file that declares no track number falling back to its own id
+-- because three untagged files are three tracks and not one.
+-- `expected` takes each disc's declared total and sums over discs,
+-- since a total is declared per disc and a release total written on
+-- every file of a two-disc album would double its expectation.  A disc
+-- whose files declared nothing contributes a NULL that SUM ignores,
+-- and `known` is what says the album is therefore unanswerable.
+WITH per_disc AS (
+    SELECT
+        album_id AS album_id,
+        COUNT(DISTINCT COALESCE(CAST(track_number AS TEXT), 'f' || id))
+            AS owned_on_disc,
+        MAX(total_tracks) AS disc_total,
+        SUM(CASE WHEN total_tracks IS NULL THEN 1 ELSE 0 END)
+            AS discs_without_a_total
+    FROM audio_files
+    WHERE album_id IN (sqlc.slice('album_ids'))
+    GROUP BY album_id, COALESCE(disc_number, 1)
+)
+SELECT
+    CAST(album_id AS INTEGER) AS album_id,
+    CAST(SUM(owned_on_disc) AS INTEGER) AS owned,
+    CAST(COALESCE(SUM(disc_total), 0) AS INTEGER) AS expected,
+    CAST(SUM(discs_without_a_total) = 0 AS INTEGER) AS known
+FROM per_disc
+GROUP BY album_id;

backend/database/sql/queries/tagging_items.sql

@@ -342,3 +342,35 @@ WHERE ti.status = 'pending'
   )
 ORDER BY ti.group_key
 LIMIT 1;
+
+-- name: GetTaggingItemsForAlbum :many
+-- Every tagging group holding a file of this album.
+--
+-- The join is `audio_files.group_key`, not a key derived from the
+-- album's folder path: a group carved out of a mixed-bag folder by
+-- SplitMixedFolder is keyed on its tags rather than on a directory,
+-- so a path-derived key finds nothing for exactly the messiest
+-- libraries this is meant to help.
+--
+-- Usually one row. A multi-disc album is one group per disc, which
+-- the caller has to know about rather than average over -- applying
+-- to "the album" would silently retag one disc of three.
+SELECT
+  ti.group_key,
+  ti.status,
+  ti.score,
+  ti.best_match_release_mbid,
+  ti.track_count,
+  ti.album_name,
+  ti.album_artist,
+  ti.synthetic
+FROM tagging_items ti
+WHERE ti.group_key IN (
+    SELECT DISTINCT af.group_key
+    FROM audio_files af
+    WHERE af.album_id = sqlc.arg(album_id) AND af.group_key != ''
+  )
+  AND ti.cleared_at IS NULL
+-- Best first, with an unscored group last rather than first: NULL
+-- sorts low in SQLite and DESC would put it at the top.
+ORDER BY ti.score IS NULL, ti.score DESC, ti.group_key;

backend/database/sql/sqlcgen/albums.sql.go

@@ -8,6 +8,7 @@ package sqlcgen
 import (
 	"context"
 	"database/sql"
+	"strings"
 )
 
 const deleteAlbum = `-- name: DeleteAlbum :exec
@@ -234,6 +235,98 @@ func (q *Queries) GetAlbumsByArtistName(ctx context.Context, arg GetAlbumsByArti
 	return items, nil
 }
 
+const getAlbumsCompleteness = `-- name: GetAlbumsCompleteness :many
+WITH per_disc AS (
+    SELECT
+        album_id AS album_id,
+        COUNT(DISTINCT COALESCE(CAST(track_number AS TEXT), 'f' || id))
+            AS owned_on_disc,
+        MAX(total_tracks) AS disc_total,
+        SUM(CASE WHEN total_tracks IS NULL THEN 1 ELSE 0 END)
+            AS discs_without_a_total
+    FROM audio_files
+    WHERE album_id IN (/*SLICE:album_ids*/?)
+    GROUP BY album_id, COALESCE(disc_number, 1)
+)
+SELECT
+    CAST(album_id AS INTEGER) AS album_id,
+    CAST(SUM(owned_on_disc) AS INTEGER) AS owned,
+    CAST(COALESCE(SUM(disc_total), 0) AS INTEGER) AS expected,
+    CAST(SUM(discs_without_a_total) = 0 AS INTEGER) AS known
+FROM per_disc
+GROUP BY album_id
+`
+
+type GetAlbumsCompletenessRow struct {
+	AlbumID  int64
+	Owned    int64
+	Expected int64
+	Known    int64
+}
+
+// The same question as GetAlbumCompleteness, asked of a screenful of
+// albums at once.
+//
+// A card grid cannot afford one query per card, and the answer it wants
+// is the one thing a badge cannot guess: an album held 9 tracks of 12
+// must show the count, never a bare tick.  So this is one query for the
+// whole grid, asked only of the cards that have a local album id.
+//
+// It is two grouping levels rather than the single-album form's
+// correlated subqueries, because a correlated subquery in the FROM
+// clause is not something SQLite will reliably do -- and because the
+// slice may only be spelled once, or sqlc expands it twice with
+// independently numbered placeholders.
+//
+// The per-disc level is where the meaning is, and it is the same
+// meaning as the single-album query.  `owned` counts DISTINCT track
+// numbers within a disc (this app detects duplicates, and counting two
+// files of track 3 twice would report a short album as complete), with
+// a file that declares no track number falling back to its own id
+// because three untagged files are three tracks and not one.
+// `expected` takes each disc's declared total and sums over discs,
+// since a total is declared per disc and a release total written on
+// every file of a two-disc album would double its expectation.  A disc
+// whose files declared nothing contributes a NULL that SUM ignores,
+// and `known` is what says the album is therefore unanswerable.
+func (q *Queries) GetAlbumsCompleteness(ctx context.Context, albumIds []sql.NullInt64) ([]GetAlbumsCompletenessRow, error) {
+	query := getAlbumsCompleteness
+	var queryParams []interface{}
+	if len(albumIds) > 0 {
+		for _, v := range albumIds {
+			queryParams = append(queryParams, v)
+		}
+		query = strings.Replace(query, "/*SLICE:album_ids*/?", strings.Repeat(",?", len(albumIds))[1:], 1)
+	} else {
+		query = strings.Replace(query, "/*SLICE:album_ids*/?", "NULL", 1)
+	}
+	rows, err := q.db.QueryContext(ctx, query, queryParams...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []GetAlbumsCompletenessRow
+	for rows.Next() {
+		var i GetAlbumsCompletenessRow
+		if err := rows.Scan(
+			&i.AlbumID,
+			&i.Owned,
+			&i.Expected,
+			&i.Known,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const getAlbumsWithPendingReleaseMBID = `-- name: GetAlbumsWithPendingReleaseMBID :many
 SELECT id, pending_release_mbid FROM albums
 WHERE pending_release_mbid IS NOT NULL AND pending_release_mbid != ''

backend/database/sql/sqlcgen/tagging_items.sql.go

@@ -231,6 +231,82 @@ func (q *Queries) GetTaggingItem(ctx context.Context, groupKey string) (TaggingI
 	return i, err
 }
 
+const getTaggingItemsForAlbum = `-- name: GetTaggingItemsForAlbum :many
+SELECT
+  ti.group_key,
+  ti.status,
+  ti.score,
+  ti.best_match_release_mbid,
+  ti.track_count,
+  ti.album_name,
+  ti.album_artist,
+  ti.synthetic
+FROM tagging_items ti
+WHERE ti.group_key IN (
+    SELECT DISTINCT af.group_key
+    FROM audio_files af
+    WHERE af.album_id = ?1 AND af.group_key != ''
+  )
+  AND ti.cleared_at IS NULL
+ORDER BY ti.score IS NULL, ti.score DESC, ti.group_key
+`
+
+type GetTaggingItemsForAlbumRow struct {
+	GroupKey             string
+	Status               string
+	Score                sql.NullFloat64
+	BestMatchReleaseMbid sql.NullString
+	TrackCount           int64
+	AlbumName            string
+	AlbumArtist          string
+	Synthetic            int64
+}
+
+// Every tagging group holding a file of this album.
+//
+// The join is `audio_files.group_key`, not a key derived from the
+// album's folder path: a group carved out of a mixed-bag folder by
+// SplitMixedFolder is keyed on its tags rather than on a directory,
+// so a path-derived key finds nothing for exactly the messiest
+// libraries this is meant to help.
+//
+// Usually one row. A multi-disc album is one group per disc, which
+// the caller has to know about rather than average over -- applying
+// to "the album" would silently retag one disc of three.
+// Best first, with an unscored group last rather than first: NULL
+// sorts low in SQLite and DESC would put it at the top.
+func (q *Queries) GetTaggingItemsForAlbum(ctx context.Context, albumID sql.NullInt64) ([]GetTaggingItemsForAlbumRow, error) {
+	rows, err := q.db.QueryContext(ctx, getTaggingItemsForAlbum, albumID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []GetTaggingItemsForAlbumRow
+	for rows.Next() {
+		var i GetTaggingItemsForAlbumRow
+		if err := rows.Scan(
+			&i.GroupKey,
+			&i.Status,
+			&i.Score,
+			&i.BestMatchReleaseMbid,
+			&i.TrackCount,
+			&i.AlbumName,
+			&i.AlbumArtist,
+			&i.Synthetic,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const listAudioFilesInTaggingGroup = `-- name: ListAudioFilesInTaggingGroup :many
 SELECT
   af.id,

backend/download/config.go

@@ -34,13 +34,29 @@ type UserConfig struct {
 	// in one burst that every provider sees as a flood.
 	WantedBatch int `toml:"WantedBatch"`
 
-	// MinFileSizeMB, MaxFileSizeMB and PreferredFileSizeMB bound and
-	// nudge what auto-pick (interactive or via the request list) may
-	// grab without asking.  Zero on any of them is permissive: see
-	// AutoDownloadPrefs.
-	MinFileSizeMB       int `toml:"MinFileSizeMB"`
-	MaxFileSizeMB       int `toml:"MaxFileSizeMB"`
-	PreferredFileSizeMB int `toml:"PreferredFileSizeMB"`
+	// MinKbps, MaxKbps and PreferredKbps bound and nudge what auto-pick
+	// (interactive or via the request list) may grab without asking.
+	// Zero on any of them is permissive: see AutoDownloadPrefs.
+	//
+	// They replaced MinFileSizeMB / MaxFileSizeMB /
+	// PreferredFileSizeMB, which were megabytes and so said nothing
+	// without knowing how long the release was.  The old keys are
+	// deliberately *not* read back: a number that meant "300 MB" cannot
+	// be reinterpreted as a bitrate without knowing the album it was
+	// aimed at, so migrating it would be inventing an intent the user
+	// never expressed.  An existing config falls back to no window,
+	// which is the permissive default and matches a fresh install —
+	// and MaxFileSizeMB is the one that does carry over, because a
+	// ceiling on total bytes still means exactly what it did.
+	MinKbps       int `toml:"MinKbps"`
+	MaxKbps       int `toml:"MaxKbps"`
+	PreferredKbps int `toml:"PreferredKbps"`
+
+	// MaxFileSizeMB is a hard ceiling on a candidate's total size, kept
+	// in megabytes on purpose — it is a question about disk space, not
+	// about quality, and it has to apply to a candidate whose bitrate
+	// cannot be worked out at all.
+	MaxFileSizeMB int `toml:"MaxFileSizeMB"`
 
 	// AllowedFormats restricts auto-pick to these formats.  Empty means
 	// no restriction.  Values are Format strings ("flac", "mp3", ...).
@@ -56,10 +72,11 @@ func (c *UserConfig) AutoDownloadPrefs() AutoDownloadPrefs {
 	}
 
 	return AutoDownloadPrefs{
-		MinSizeMB:       c.MinFileSizeMB,
-		MaxSizeMB:       c.MaxFileSizeMB,
-		PreferredSizeMB: c.PreferredFileSizeMB,
-		AllowedFormats:  formats,
+		MinKbps:        c.MinKbps,
+		MaxKbps:        c.MaxKbps,
+		PreferredKbps:  c.PreferredKbps,
+		MaxSizeMB:      c.MaxFileSizeMB,
+		AllowedFormats: formats,
 	}
 }
 

backend/download/importer.go

@@ -12,6 +12,7 @@ import (
 	"strconv"
 	"strings"
 
+	"yellowjacket/backend/tagtotals"
 	"yellowjacket/backend/tagwriter"
 )
 
@@ -275,6 +276,25 @@ func (i *Importer) tagFile(p plannedFile, dl Download) error {
 		changes[tagwriter.FieldDiscNumber] = p.Track.DiscNumber
 	}
 
+	// An imported file should arrive knowing how much of the album it
+	// is one of, or the album reads as "in your library" from its first
+	// imported track onward.
+	//
+	// A *track* download is the case this must not touch: a
+	// RecordingMBID anchor resolves Expected to exactly that one track,
+	// so totalling it would write "1 of 1" onto a track off a
+	// twelve-track album -- a confident lie, and one that outranks the
+	// catalog's own total, which is the fallback that would otherwise
+	// have answered correctly.
+	if dl.RecordingMBID == "" {
+		if tracks, discs := tagtotals.For(
+			expectedPositions(dl.Expected), p.Track.DiscNumber,
+		); tracks > 0 {
+			changes[tagwriter.FieldTotalTracks] = tracks
+			changes[tagwriter.FieldTotalDiscs] = discs
+		}
+	}
+
 	if err := i.tags.WriteUntrackedFileTags(p.Source, changes); err != nil {
 		return fmt.Errorf("write tags: %w", err)
 	}
@@ -282,6 +302,18 @@ func (i *Importer) tagFile(p plannedFile, dl Download) error {
 	return nil
 }
 
+// expectedPositions is the download's resolved tracklist as bare
+// positions.
+func expectedPositions(expected []ExpectedTrack) []tagtotals.Position {
+	out := make([]tagtotals.Position, 0, len(expected))
+
+	for _, t := range expected {
+		out = append(out, tagtotals.Position{Disc: t.DiscNumber, Track: t.Position})
+	}
+
+	return out
+}
+
 // destinationFor computes a file's library path from the template.
 func (i *Importer) destinationFor(
 	p plannedFile,

backend/download/importer_test.go

@@ -446,3 +446,77 @@ func keysOf(m map[string]tagwriter.TagChanges) []string {
 
 	return out
 }
+
+// An imported album should arrive knowing its own size, or the album
+// page reads "in your library" from its first imported track onward --
+// which is the badge complaint this exists to answer.
+func TestImportWritesTheAlbumTotals(t *testing.T) {
+	t.Parallel()
+
+	f := newImportFixture(t,
+		"01 - Airbag.flac",
+		"02 - Paranoid Android.flac",
+		"03 - Subterranean Homesick Alien.flac",
+		"04 - Exit Music (For a Film).flac",
+	)
+
+	if _, err := f.importer.Import(
+		context.Background(),
+		fourTrackDownload(),
+		Result{Dir: f.dir, Files: f.files},
+		ImportOptions{LibraryRoot: f.root, WriteTags: true},
+	); err != nil {
+		t.Fatalf("Import: %v", err)
+	}
+
+	changes := f.tags.writes["01 - Airbag.flac"]
+	if changes == nil {
+		t.Fatal("no tag write recorded for the first track")
+	}
+
+	if got := changes[tagwriter.FieldTotalTracks]; got != 4 {
+		t.Errorf("%s: got %v, want 4", tagwriter.FieldTotalTracks, got)
+	}
+
+	if got := changes[tagwriter.FieldTotalDiscs]; got != 1 {
+		t.Errorf("%s: got %v, want 1", tagwriter.FieldTotalDiscs, got)
+	}
+}
+
+// A RecordingMBID anchor resolves Expected to exactly the one track it
+// asked for, so totalling it would tag a track off a twelve-track album
+// as "1 of 1" -- worse than saying nothing, because a declared total
+// outranks the catalog total that would have answered correctly.
+func TestImportWritesNoTotalsForATrackDownload(t *testing.T) {
+	t.Parallel()
+
+	f := newImportFixture(t, "01 - Airbag.flac")
+
+	dl := Download{
+		ID:            "dl-track",
+		LibraryID:     1,
+		RecordingMBID: "mbid-recording",
+		Artist:        "Radiohead",
+		Album:         "OK Computer",
+		Expected:      []ExpectedTrack{{Position: 1, Title: "Airbag"}},
+	}
+
+	if _, err := f.importer.Import(
+		context.Background(),
+		dl,
+		Result{Dir: f.dir, Files: f.files},
+		ImportOptions{LibraryRoot: f.root, WriteTags: true},
+	); err != nil {
+		t.Fatalf("Import: %v", err)
+	}
+
+	changes := f.tags.writes["01 - Airbag.flac"]
+	if changes == nil {
+		t.Fatal("no tag write recorded")
+	}
+
+	if _, ok := changes[tagwriter.FieldTotalTracks]; ok {
+		t.Errorf("%s written for a single-track download: %v",
+			tagwriter.FieldTotalTracks, changes[tagwriter.FieldTotalTracks])
+	}
+}

backend/download/manager.go

@@ -236,6 +236,12 @@ func (m *Manager) AutoPickable(dl Download, ranked []Candidate) bool {
 	return AutoPickable(dl, ranked, m.preferences())
 }
 
+// AutoPickVeto wraps the package function the same way, and is what the
+// request list quotes back to the user.
+func (m *Manager) AutoPickVeto(dl Download, ranked []Candidate) string {
+	return AutoPickVeto(dl, ranked, m.preferences())
+}
+
 // Reload rebuilds every provider from stored config.  Called at startup
 // and after any provider settings change.
 //
@@ -612,16 +618,8 @@ func (m *Manager) Attempt(
 		return false, "", err
 	}
 
-	if !m.AutoPickable(dl, ranked) {
-		best := ranked[0]
-
-		return false, fmt.Sprintf(
-			"best of %d found is not a confident enough match "+
-				"(match %.0f%%, quality %.0f%%)",
-			len(ranked),
-			best.Match.Overall*100, //nolint:mnd // percent
-			best.Quality.Overall*100,
-		), nil
+	if veto := m.AutoPickVeto(dl, ranked); veto != "" {
+		return false, veto, nil
 	}
 
 	if err := m.store.CreateDownload(ctx, dl); err != nil {

backend/download/manager_test.go

@@ -218,8 +218,17 @@ func TestManagerEndToEndAutoPick(t *testing.T) {
 	}, "staging was never released, or the library was never rescanned")
 }
 
-// An ambiguous result set must park for the user rather than guess.
-func TestManagerWaitsWhenAmbiguous(t *testing.T) {
+// Two equally good copies are not an ambiguity — they are a spare.
+//
+// This asserted the opposite for as long as auto-pick required 0.08 of
+// daylight over the runner-up, and that rule was wrong in exactly the
+// case it fired hardest: a popular album turns up several *correct*
+// copies, all matching the tracklist, differing only in format and
+// seeders. There is no question there about what to fetch, only about
+// which copy, and the ranking already answers that — closest to the
+// preferred bitrate first. A candidate does not have to be better than
+// the field, only good enough on its own terms.
+func TestManagerAutoPicksAmongEquallyGoodCopies(t *testing.T) {
 	t.Parallel()
 
 	f := newManagerFixture(t)
@@ -237,11 +246,41 @@ func TestManagerWaitsWhenAmbiguous(t *testing.T) {
 		t.Fatalf("Start: %v", err)
 	}
 
-	if f.manager.AutoPickable(dl, ranked) {
-		t.Fatal("two equivalent candidates must not auto-pick")
+	if veto := f.manager.AutoPickVeto(dl, ranked); veto != "" {
+		t.Fatalf("two equally good copies must auto-pick, got veto: %s", veto)
+	}
+
+	waitForDownloadState(t, f.store, dl.ID, StateComplete)
+
+	// Exactly one of them was fetched, not both.
+	if grabs := a.GrabCalls + b.GrabCalls; grabs != 1 {
+		t.Errorf("grabs = %d, want exactly 1", grabs)
+	}
+}
+
+// The user can still pick explicitly when auto-pick is not what
+// happened — a candidate the ranking did not choose is still grabbable.
+func TestManagerPickIsExplicit(t *testing.T) {
+	t.Parallel()
+
+	f := newManagerFixture(t)
+
+	a := fakeWithAlbum(1, "source-a", ".flac")
+	b := fakeWithAlbum(2, "source-b", ".flac")
+
+	f.manager.installProvider(Config{ID: 1, Priority: 50}, a)
+	f.manager.installProvider(Config{ID: 2, Priority: 50}, b)
+
+	// No tracklist: never auto-picks, so the result set parks for the
+	// user and Pick is the only way anything is fetched.
+	dl := fourTrackDownload()
+	dl.Expected = nil
+
+	ranked, err := f.manager.Start(context.Background(), dl)
+	if err != nil {
+		t.Fatalf("Start: %v", err)
 	}
 
-	// Nothing was grabbed while waiting for the user.
 	if a.GrabCalls != 0 || b.GrabCalls != 0 {
 		t.Errorf(
 			"grabs happened without a pick: a=%d b=%d",
@@ -258,7 +297,6 @@ func TestManagerWaitsWhenAmbiguous(t *testing.T) {
 		t.Errorf("stored request id = %s, want %s", stored.ID, dl.ID)
 	}
 
-	// The user picks the second one explicitly.
 	if err := f.manager.Pick(
 		context.Background(), dl.ID, ranked[1].ID,
 	); err != nil {

backend/download/rank.go

@@ -1,6 +1,7 @@
 package download
 
 import (
+	"fmt"
 	"math"
 	"sort"
 	"strings"
@@ -34,38 +35,102 @@ const (
 	weightArtistFit    = 0.12
 )
 
-// Quality sub-weights.  They sum to 1.0 along with weightSizeFit below.
+// Quality sub-weights.  Each set sums to 1.0.
+//
+// There are two of them because a stated preference changes what the
+// other numbers are *for*.  `formatRank` and `bitrateScore` are the
+// app guessing at how good a copy is — FLAC over MP3, 320 over 128 —
+// and that guess exists precisely because the user has not said.  Once
+// they have, the guess should not outvote them: with the old single set
+// a preference of 320 kbps moved a candidate's score by at most 0.05
+// against the 0.42 riding on format, so asking for 320 and being handed
+// a FLAC every time was the *designed* behaviour.  That is the same
+// fault the megabyte window had — a preference the user can express and
+// the ranking can ignore.
 const (
-	weightFormat   = 0.42
-	weightBitrate  = 0.23
-	weightHealth   = 0.20
-	weightPriority = 0.10
-	weightSizeFit  = 0.05
+	weightFormat     = 0.42
+	weightBitrate    = 0.23
+	weightHealth     = 0.20
+	weightPriority   = 0.10
+	weightBitrateFit = 0.05
 )
 
+// Quality sub-weights when the user has named a preferred bitrate.
+// The weight comes off format and bitrate — the two proxies the
+// preference replaces — and health and priority are untouched, since
+// neither is a stand-in for anything the user just said.
+const (
+	statedWeightFormat     = 0.20
+	statedWeightBitrate    = 0.10
+	statedWeightHealth     = 0.20
+	statedWeightPriority   = 0.10
+	statedWeightBitrateFit = 0.40
+)
+
+// qualityWeights picks the set, in the order scoreQuality applies them.
+func qualityWeights(p AutoDownloadPrefs) (
+	format, bitrate, health, priority, fit float64,
+) {
+	if p.PreferredKbps > 0 {
+		return statedWeightFormat,
+			statedWeightBitrate,
+			statedWeightHealth,
+			statedWeightPriority,
+			statedWeightBitrateFit
+	}
+
+	return weightFormat,
+		weightBitrate,
+		weightHealth,
+		weightPriority,
+		weightBitrateFit
+}
+
 // unanchoredCap bounds the match score of a free-text request.  Without
 // an MBID there is no tracklist to be right about, so a confident-
 // looking score would be a lie — and auto-pick keys off this.
 const unanchoredCap = 0.65
 
 // AutoDownloadPrefs gates and scores what AutoPickable may choose
-// without asking.  Zero values are permissive: no size window and no
-// format restriction.
+// without asking.  Zero values are permissive: no bitrate window, no
+// size ceiling and no format restriction.
+//
+// **The window is a rate, not a size.**  It used to be three numbers in
+// megabytes, which cannot mean anything on their own: 300 MB is a
+// generous FLAC single and a suspiciously small boxset, and the user
+// setting the number has no idea which release the pipeline will
+// eventually apply it to.  A bitrate is the same statement normalised
+// by how long the music is, so one number holds across a 9-minute EP
+// and a 3-hour opera — and it is the unit the thing being described is
+// actually measured in.  The runtime is known for every request
+// auto-pick can act on (`Download.Expected` carries per-track lengths,
+// and an anchored request is the only kind that reaches here), so this
+// costs no extra lookup.
 type AutoDownloadPrefs struct {
-	// MinSizeMB and MaxSizeMB bound what auto-pick will grab.  Zero
-	// means no bound on that side.  A candidate outside the window is
-	// filtered out of auto-pick entirely, not merely scored down — a
-	// tiny "sampler" torrent or a boxset ten times the expected size is
-	// usually the wrong thing entirely, not a worse copy of the right
-	// thing.
-	MinSizeMB int `json:"minSizeMb"`
-	MaxSizeMB int `json:"maxSizeMb"`
+	// MinKbps and MaxKbps bound the average bitrate auto-pick will
+	// grab.  Zero means no bound on that side.  A candidate outside the
+	// window is filtered out of auto-pick entirely, not merely scored
+	// down — a 96 kbps rip of the right album is not a worse copy the
+	// user might accept, it is one they said not to take unattended.
+	//
+	// For reference: 320 is the top of MP3, ~500–1000 is FLAC depending
+	// on the material, and anything under ~128 is a transcode.
+	MinKbps int `json:"minKbps"`
+	MaxKbps int `json:"maxKbps"`
 
-	// PreferredSizeMB nudges the score toward a target size within the
-	// min/max window (a lossless rip and a heavily-padded lossless rip
-	// can both pass the window).  Zero disables the nudge; sizeFit then
-	// returns a neutral value that does not affect ranking.
-	PreferredSizeMB int `json:"preferredSizeMb"`
+	// PreferredKbps nudges the score toward a target rate within the
+	// window, and breaks the tie when several candidates are equally
+	// good matches.  Zero disables the nudge; bitrateFit then returns a
+	// neutral value that does not affect ranking.
+	PreferredKbps int `json:"preferredKbps"`
+
+	// MaxSizeMB is a hard ceiling on the whole candidate, and it is
+	// deliberately still a size.  It answers a different question from
+	// the window above — not "is this the quality I want" but "is this
+	// going to fill the disk" — and it has to hold even for a candidate
+	// whose bitrate cannot be worked out, which is exactly the shape a
+	// mislabelled boxset arrives in.  Zero means no ceiling.
+	MaxSizeMB int `json:"maxSizeMb"`
 
 	// AllowedFormats restricts auto-pick to candidates whose audio
 	// files are all in one of these formats.  Empty means no
@@ -74,19 +139,33 @@ type AutoDownloadPrefs struct {
 }
 
 // eligible reports whether a candidate may be auto-picked under these
-// preferences: within the size window (when set) and, when a format
-// list is given, every audio file in an allowed format.
-func (p AutoDownloadPrefs) eligible(c Candidate) bool {
+// preferences: inside the bitrate window and the size ceiling (when
+// set) and, when a format list is given, every audio file in an
+// allowed format.
+//
+// `runtimeMillis` is how long the requested release is, and 0 means
+// nobody knows.  An unknown runtime **passes** the bitrate window
+// rather than failing it: the window is a statement about quality, and
+// refusing everything the moment a tracklist is missing a length would
+// turn a gap in MusicBrainz into a silent embargo.  The size ceiling
+// still applies, which is why it exists separately.
+func (p AutoDownloadPrefs) eligible(c Candidate, runtimeMillis int64) bool {
 	const bytesPerMB = 1 << 20
 
-	if p.MinSizeMB > 0 && c.TotalSize < int64(p.MinSizeMB)*bytesPerMB {
-		return false
-	}
-
 	if p.MaxSizeMB > 0 && c.TotalSize > int64(p.MaxSizeMB)*bytesPerMB {
 		return false
 	}
 
+	if kbps := candidateKbps(c, runtimeMillis); kbps > 0 {
+		if p.MinKbps > 0 && kbps < float64(p.MinKbps) {
+			return false
+		}
+
+		if p.MaxKbps > 0 && kbps > float64(p.MaxKbps) {
+			return false
+		}
+	}
+
 	if len(p.AllowedFormats) == 0 {
 		return true
 	}
@@ -107,11 +186,14 @@ func (p AutoDownloadPrefs) eligible(c Candidate) bool {
 
 // filter returns only the candidates these preferences allow to be
 // auto-picked, in the same (already ranked) order.
-func (p AutoDownloadPrefs) filter(ranked []Candidate) []Candidate {
+func (p AutoDownloadPrefs) filter(
+	ranked []Candidate,
+	runtimeMillis int64,
+) []Candidate {
 	out := make([]Candidate, 0, len(ranked))
 
 	for _, c := range ranked {
-		if p.eligible(c) {
+		if p.eligible(c, runtimeMillis) {
 			out = append(out, c)
 		}
 	}
@@ -119,32 +201,116 @@ func (p AutoDownloadPrefs) filter(ranked []Candidate) []Candidate {
 	return out
 }
 
-// sizeFit scores how close totalSize is to PreferredSizeMB, 0..1,
-// falling off linearly as the size doubles or halves away from it.
-// Returns a neutral 0.5 when no preference is set, so the absence of a
-// preference does not bias ranking.
-func (p AutoDownloadPrefs) sizeFit(totalSize int64) float64 {
+// bitrateFit scores how close a candidate's average bitrate is to
+// PreferredKbps, falling off linearly as it doubles or halves away
+// from it.
+//
+// The range is **0.5 to 1.0, not 0 to 1**, and the floor is the point.
+// This carries 0.40 of the quality score once a preference is set, so a
+// span down to zero would let a preference of 320 kbps push a perfectly
+// good FLAC under `minQuality` and out of auto-pick altogether —
+// turning "I like 320" into "never take anything else", silently.  A
+// preference may promote the copy that matches it; it may not
+// disqualify the others.  That is what `MinKbps`/`MaxKbps` are for, and
+// they say so out loud.
+//
+// Returns the neutral floor when no preference is set or the rate
+// cannot be worked out, so neither an absent preference nor an absent
+// runtime biases ranking.
+func (p AutoDownloadPrefs) bitrateFit(
+	c Candidate,
+	runtimeMillis int64,
+) float64 {
 	const (
-		bytesPerMB = 1 << 20
-		neutral    = 0.5
+		neutral = 0.5
+		span    = 0.5
 	)
 
-	if p.PreferredSizeMB <= 0 || totalSize <= 0 {
+	if p.PreferredKbps <= 0 {
 		return neutral
 	}
 
-	preferred := float64(p.PreferredSizeMB) * bytesPerMB
-	ratio := float64(totalSize) / preferred
+	kbps := candidateKbps(c, runtimeMillis)
+	if kbps <= 0 {
+		return neutral
+	}
 
+	ratio := kbps / float64(p.PreferredKbps)
 	if ratio < 1 {
 		ratio = 1 / ratio
 	}
 
 	// ratio is now >= 1: 1.0 is an exact match, 2.0 is double or half
-	// the preferred size.  Falls to 0 at 2x away and beyond.
-	fit := 1 - (ratio - 1)
+	// the preferred rate, where the closeness term reaches 0.
+	return neutral + span*clamp01(1-(ratio-1))
+}
 
-	return clamp01(fit)
+// candidateKbps is a candidate's average audio bitrate, or 0 when it
+// cannot be worked out.
+//
+// Two sources, in this order, and the order matters:
+//
+//   - **Derived from bytes over runtime**, which is the honest one. It
+//     covers lossless (where a stated bitrate rarely exists), it cannot
+//     be lied to by a filename, and it is what the user's window means.
+//     Only the *audio* files count: cover scans and a log file are not
+//     part of the bitrate, and a folder with 30 MB of artwork would
+//     otherwise read as a better rip than the same music without it.
+//   - **The mean stated bitrate**, when the runtime is unknown. Weaker
+//     — a provider that parses it from an MP3 header states it and one
+//     that guesses from the filename also "states" it — but a number
+//     from the file itself beats no number at all.
+func candidateKbps(c Candidate, runtimeMillis int64) float64 {
+	const bitsPerByte = 8
+
+	audio := c.AudioFiles()
+	if len(audio) == 0 {
+		return 0
+	}
+
+	if runtimeMillis > 0 {
+		var bytes int64
+		for _, f := range audio {
+			bytes += f.Size
+		}
+
+		if bytes > 0 {
+			// bytes×8 bits over seconds, expressed in kbps: the two
+			// factors of 1000 (millis→seconds, bits→kilobits) cancel.
+			return float64(bytes) * bitsPerByte /
+				float64(runtimeMillis)
+		}
+	}
+
+	var (
+		sum   int
+		count int
+	)
+
+	for _, f := range audio {
+		if f.Bitrate > 0 {
+			sum += f.Bitrate
+			count++
+		}
+	}
+
+	if count == 0 {
+		return 0
+	}
+
+	return float64(sum) / float64(count)
+}
+
+// runtimeMillis is how long the requested release is, summed over its
+// expected tracklist.  Zero when the tracklist is absent or carries no
+// lengths, which is what every caller here treats as "unknown".
+func (d Download) runtimeMillis() int64 {
+	var total int64
+	for _, t := range d.Expected {
+		total += t.LengthMillis
+	}
+
+	return total
 }
 
 // Score fills a candidate's Match, Quality and Score fields.
@@ -160,7 +326,9 @@ func Score(dl Download, c Candidate, priority int, prefs AutoDownloadPrefs) Cand
 	c.Files = mergeMatched(c.Files, matched)
 
 	c.Match = scoreMatch(dl, c, audio, titleFit)
-	c.Quality = scoreQuality(c, audio, priority, prefs)
+	c.Quality = scoreQuality(
+		c, audio, priority, prefs, dl.runtimeMillis(),
+	)
 
 	c.Score = weightMatch*c.Match.Overall + weightQuality*c.Quality.Overall
 
@@ -279,11 +447,12 @@ func scoreQuality(
 	audio []CandidateFile,
 	priority int,
 	prefs AutoDownloadPrefs,
+	runtimeMillis int64,
 ) QualityScore {
 	q := QualityScore{
-		Health:   clamp01(c.Health),
-		Priority: clamp01(float64(priority) / 100.0),
-		SizeFit:  prefs.sizeFit(c.TotalSize),
+		Health:     clamp01(c.Health),
+		Priority:   clamp01(float64(priority) / 100.0),
+		BitrateFit: prefs.bitrateFit(c, runtimeMillis),
 	}
 
 	if len(audio) == 0 {
@@ -310,11 +479,13 @@ func scoreQuality(
 	q.FormatRank = worst
 	q.Bitrate = bitrateScore(audio)
 
-	q.Overall = weightFormat*q.FormatRank +
-		weightBitrate*q.Bitrate +
-		weightHealth*q.Health +
-		weightPriority*q.Priority +
-		weightSizeFit*q.SizeFit
+	wFormat, wBitrate, wHealth, wPriority, wFit := qualityWeights(prefs)
+
+	q.Overall = wFormat*q.FormatRank +
+		wBitrate*q.Bitrate +
+		wHealth*q.Health +
+		wPriority*q.Priority +
+		wFit*q.BitrateFit
 
 	if q.Mixed {
 		q.Overall *= 0.9
@@ -444,6 +615,19 @@ func Rank(
 			return out[i].Match.Overall > out[j].Match.Overall
 		}
 
+		// Closest to the preferred bitrate wins the tie.
+		//
+		// This is what decides which copy is taken now that auto-pick
+		// no longer requires the winner to be clear of the field: when
+		// several candidates are equally good matches of equal overall
+		// quality, the one the user said they wanted the shape of is
+		// the answer, ahead of provider priority.  With no preference
+		// set every BitrateFit is the same neutral value and this
+		// falls through, exactly as before.
+		if out[i].Quality.BitrateFit != out[j].Quality.BitrateFit {
+			return out[i].Quality.BitrateFit > out[j].Quality.BitrateFit
+		}
+
 		if out[i].Quality.Priority != out[j].Quality.Priority {
 			return out[i].Quality.Priority > out[j].Quality.Priority
 		}
@@ -454,19 +638,58 @@ func Rank(
 	return out
 }
 
-// AutoPickable reports whether a ranked list has a clear enough winner
-// to grab without asking.  It demands an anchored request, a high match,
-// decent quality, and daylight between first and second place — if two
-// candidates are close, the choice is the user's.
-func AutoPickable(dl Download, ranked []Candidate, prefs AutoDownloadPrefs) bool {
-	const (
-		minMatch   = 0.85
-		minQuality = 0.5
-		minLead    = 0.08
-	)
+// Auto-pick gates.  Named rather than inlined because AutoPickVeto
+// reports which of them refused, and a number in a sentence the user
+// reads should be the same number the decision used.
+const (
+	minMatch   = 0.85
+	minQuality = 0.5
+)
 
-	if !dl.Anchored() || len(ranked) == 0 {
-		return false
+// AutoPickable reports whether a ranked list has a candidate worth
+// grabbing without asking: an anchored request with a tracklist behind
+// it, and a candidate that clears the match and quality bars inside the
+// user's guardrails.
+//
+// **It does not require the winner to be better than the runner-up.**
+// It used to demand 0.08 of daylight on the combined score, which meant
+// the check fired hardest in the case it was never written for: a
+// popular album turns up five *correct* copies, all matching the
+// tracklist at 95%+ and differing only in format and seeders, their
+// scores land within a point of each other, and auto-pick refused
+// forever on the grounds that the choice was the user's.  It was not.
+// There was no question about *what* to fetch, only about which copy —
+// and abundance is the one condition under which that question matters
+// least.  A candidate does not need to be the best one, only one that
+// meets the criteria; where several do, `Rank` puts the one closest to
+// the preferred bitrate first.
+func AutoPickable(dl Download, ranked []Candidate, prefs AutoDownloadPrefs) bool {
+	return AutoPickVeto(dl, ranked, prefs) == ""
+}
+
+// AutoPickVeto returns the reason auto-pick declined, or "" when it
+// would go ahead.
+//
+// It exists because "it rejected all of them" was indistinguishable
+// from "it found nothing good".  The request list's message was built
+// from `ranked[0]` — the best candidate *before* the size and format
+// guardrails, and before the lead check — so a request refused because
+// the user's maximum size excluded every copy, or because three equally
+// good copies were found, reported "best of 12 found is not a confident
+// enough match (match 96%, quality 88%)".  Numbers that clear both
+// thresholds, beside a refusal, is a message that teaches the user the
+// matcher is broken.  Each gate names itself now.
+func AutoPickVeto(
+	dl Download,
+	ranked []Candidate,
+	prefs AutoDownloadPrefs,
+) string {
+	if len(ranked) == 0 {
+		return "nothing found"
+	}
+
+	if !dl.Anchored() {
+		return "the request is free text, so there is no release to be right about"
 	}
 
 	// An anchor with no tracklist behind it is an anchor in name only:
@@ -474,29 +697,42 @@ func AutoPickable(dl Download, ranked []Candidate, prefs AutoDownloadPrefs) bool
 	// is exactly the evidence a wrong-album candidate also has.  This
 	// matters most for the request list, where nobody is watching.
 	if len(dl.Expected) == 0 {
-		return false
+		return "no tracklist for this release is known yet, so a candidate cannot be checked against it"
 	}
 
-	// The guardrails apply before the match/quality/lead checks: a
-	// candidate outside the allowed size or format is not a worse
-	// choice, it is not a choice auto-pick may make at all, so it must
-	// not count as "the winner" nor as "second place" for the lead
-	// check below.
-	eligible := prefs.filter(ranked)
+	// The guardrails apply before the match and quality checks: a
+	// candidate outside the allowed bitrate, size or format is not a
+	// worse choice, it is not a choice auto-pick may make at all, so it
+	// must not count as "the winner" either.
+	eligible := prefs.filter(ranked, dl.runtimeMillis())
 	if len(eligible) == 0 {
-		return false
+		return fmt.Sprintf(
+			"all %d found are outside the auto-download bitrate, size or format limits",
+			len(ranked),
+		)
 	}
 
 	best := eligible[0]
-	if best.Match.Overall < minMatch || best.Quality.Overall < minQuality {
-		return false
+
+	if best.Match.Overall < minMatch {
+		return fmt.Sprintf(
+			"best of %d found matches this release only %.0f%% (needs %.0f%%)",
+			len(ranked),
+			best.Match.Overall*100, //nolint:mnd // percent
+			minMatch*100,           //nolint:mnd // percent
+		)
 	}
 
-	if len(eligible) > 1 && best.Score-eligible[1].Score < minLead {
-		return false
+	if best.Quality.Overall < minQuality {
+		return fmt.Sprintf(
+			"best of %d found is the right release but scores %.0f%% on quality (needs %.0f%%)",
+			len(ranked),
+			best.Quality.Overall*100, //nolint:mnd // percent
+			minQuality*100,           //nolint:mnd // percent
+		)
 	}
 
-	return true
+	return ""
 }
 
 // mergeMatched copies MatchedTo assignments from the audio-only slice

backend/download/rank_test.go

@@ -1,6 +1,34 @@
 package download
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
+
+// trackMillis is five minutes; okComputer's four of them make a
+// twenty-minute release, which is what turns a candidate's byte count
+// into a bitrate the assertions below can name.
+const trackMillis = 5 * 60 * 1000
+
+// okComputerRuntime is that release's runtime, for the helpers that
+// need it directly.
+const okComputerRuntime = 4 * trackMillis
+
+// kbpsCandidate builds an annotated candidate whose audio adds up to
+// the given average bitrate over okComputer's runtime.
+func kbpsCandidate(id, ext string, kbps int) Candidate {
+	// bits = kbps × 1000 × (runtimeMillis / 1000), so the thousands
+	// cancel and the byte count is kbps × runtimeMillis / 8.
+	const bitsPerByte = 8
+
+	total := int64(kbps) * okComputerRuntime / bitsPerByte
+
+	c := candidateFor(id, allTitles(), ext, total/int64(len(allTitles())))
+	c.Files = AnnotateFiles(c.Files)
+	c.TotalSize = total
+
+	return c
+}
 
 // okComputer is the reference request used across ranking tests.
 func okComputer() Download {
@@ -8,11 +36,15 @@ func okComputer() Download {
 		ReleaseMBID: "mbid-ok-computer",
 		Artist:      "Radiohead",
 		Album:       "OK Computer",
+		// Four five-minute tracks: twenty minutes, so a candidate's
+		// bitrate is a number these tests can state exactly. Without
+		// lengths there is no runtime and the bitrate window has
+		// nothing to divide by.
 		Expected: []ExpectedTrack{
-			{Position: 1, Title: "Airbag"},
-			{Position: 2, Title: "Paranoid Android"},
-			{Position: 3, Title: "Subterranean Homesick Alien"},
-			{Position: 4, Title: "Exit Music (For a Film)"},
+			{Position: 1, Title: "Airbag", LengthMillis: trackMillis},
+			{Position: 2, Title: "Paranoid Android", LengthMillis: trackMillis},
+			{Position: 3, Title: "Subterranean Homesick Alien", LengthMillis: trackMillis},
+			{Position: 4, Title: "Exit Music (For a Film)", LengthMillis: trackMillis},
 		},
 	}
 }
@@ -187,7 +219,7 @@ func TestUnanchoredMatchIsCapped(t *testing.T) {
 	}
 }
 
-func TestAutoPickableRequiresAnchorAndLead(t *testing.T) {
+func TestAutoPickableRequiresAnchorAndTracklist(t *testing.T) {
 	t.Parallel()
 
 	dl := okComputer()
@@ -211,14 +243,18 @@ func TestAutoPickableRequiresAnchorAndLead(t *testing.T) {
 		}
 	})
 
-	t.Run("two close candidates are not", func(t *testing.T) {
+	// Two identical copies are a spare, not an ambiguity. This
+	// asserted the opposite while auto-pick required daylight over the
+	// runner-up — a rule that made abundance the thing that stopped a
+	// request being satisfied, which is backwards.
+	t.Run("two equally good candidates still are", func(t *testing.T) {
 		t.Parallel()
 
 		twin := best
 		twin.ID = "twin"
 
-		if AutoPickable(dl, []Candidate{best, twin}, AutoDownloadPrefs{}) {
-			t.Error("identical candidates must not auto-pick")
+		if !AutoPickable(dl, []Candidate{best, twin}, AutoDownloadPrefs{}) {
+			t.Error("identical good candidates must auto-pick")
 		}
 	})
 
@@ -300,18 +336,11 @@ func TestProviderPriorityBreaksTies(t *testing.T) {
 	}
 }
 
-const mb = 1 << 20
-
 func TestAutoDownloadPrefsEligible(t *testing.T) {
 	t.Parallel()
 
-	flacCandidate := candidateFor("c", allTitles(), ".flac", 30_000_000)
-	flacCandidate.Files = AnnotateFiles(flacCandidate.Files)
-	flacCandidate.TotalSize = 300 * mb
-
-	mp3Candidate := candidateFor("c", allTitles(), ".mp3", 3_000_000)
-	mp3Candidate.Files = AnnotateFiles(mp3Candidate.Files)
-	mp3Candidate.TotalSize = 30 * mb
+	flacCandidate := kbpsCandidate("c", ".flac", 900)
+	mp3Candidate := kbpsCandidate("c", ".mp3", 128)
 
 	tests := []struct {
 		name  string
@@ -321,18 +350,25 @@ func TestAutoDownloadPrefsEligible(t *testing.T) {
 	}{
 		{"zero value is permissive", AutoDownloadPrefs{}, flacCandidate, true},
 		{
-			"within min/max window",
-			AutoDownloadPrefs{MinSizeMB: 100, MaxSizeMB: 500},
+			"within the bitrate window",
+			AutoDownloadPrefs{MinKbps: 320, MaxKbps: 1200},
 			flacCandidate, true,
 		},
 		{
-			"below minimum",
-			AutoDownloadPrefs{MinSizeMB: 400},
+			"below the minimum bitrate",
+			AutoDownloadPrefs{MinKbps: 500},
+			mp3Candidate, false,
+		},
+		{
+			"above the maximum bitrate",
+			AutoDownloadPrefs{MaxKbps: 500},
 			flacCandidate, false,
 		},
 		{
-			"above maximum",
-			AutoDownloadPrefs{MaxSizeMB: 200},
+			// The ceiling is bytes, not a rate, and it is the guard
+			// that still works when the bitrate cannot be worked out.
+			"above the hard size ceiling",
+			AutoDownloadPrefs{MaxSizeMB: 50},
 			flacCandidate, false,
 		},
 		{
@@ -351,57 +387,131 @@ func TestAutoDownloadPrefsEligible(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			if got := tt.prefs.eligible(tt.c); got != tt.want {
+			got := tt.prefs.eligible(tt.c, okComputerRuntime)
+			if got != tt.want {
 				t.Errorf("eligible() = %v, want %v", got, tt.want)
 			}
 		})
 	}
 }
 
+// A release nobody knows the length of cannot be judged on bitrate, and
+// the window must not become a silent embargo because MusicBrainz is
+// missing a track length.  The size ceiling still applies — that is why
+// it is a separate field.
+func TestBitrateWindowPassesAnUnknownRuntime(t *testing.T) {
+	t.Parallel()
+
+	c := kbpsCandidate("c", ".mp3", 128)
+	prefs := AutoDownloadPrefs{MinKbps: 900}
+
+	if !prefs.eligible(c, 0) {
+		t.Error("an unknown runtime must pass the bitrate window")
+	}
+
+	if prefs.eligible(c, okComputerRuntime) {
+		t.Error("a known runtime must still be judged")
+	}
+
+	ceiling := AutoDownloadPrefs{MaxSizeMB: 1}
+	if ceiling.eligible(c, 0) {
+		t.Error("the size ceiling must apply even with no runtime")
+	}
+}
+
+// Artwork is not part of the bitrate.  A folder carrying 30 MB of
+// scans would otherwise read as a better rip than the same music
+// without them, which is backwards.
+func TestBitrateIgnoresNonAudioFiles(t *testing.T) {
+	t.Parallel()
+
+	c := kbpsCandidate("c", ".mp3", 320)
+	bare := candidateKbps(c, okComputerRuntime)
+
+	c.Files = append(c.Files, CandidateFile{
+		Path: "Radiohead - OK Computer/cover.jpg",
+		Size: 30 << 20,
+	})
+	c.Files = AnnotateFiles(c.Files)
+
+	if got := candidateKbps(c, okComputerRuntime); got != bare {
+		t.Errorf("bitrate with artwork = %f, want %f", got, bare)
+	}
+}
+
+// Where no runtime is known, a stated per-file bitrate is better than
+// no answer at all.
+func TestBitrateFallsBackToTheStatedRate(t *testing.T) {
+	t.Parallel()
+
+	c := candidateFor("c", allTitles(), ".mp3", 3_000_000)
+	for i := range c.Files {
+		c.Files[i].Bitrate = 192
+	}
+
+	c.Files = AnnotateFiles(c.Files)
+
+	if got := candidateKbps(c, 0); got != 192 {
+		t.Errorf("stated bitrate = %f, want 192", got)
+	}
+}
+
 func TestAutoDownloadPrefsFilter(t *testing.T) {
 	t.Parallel()
 
-	small := candidateFor("small", allTitles(), ".flac", 10_000_000)
-	small.TotalSize = 50 * mb
+	lossy := kbpsCandidate("lossy", ".mp3", 128)
+	lossless := kbpsCandidate("lossless", ".flac", 900)
 
-	big := candidateFor("big", allTitles(), ".flac", 30_000_000)
-	big.TotalSize = 500 * mb
+	prefs := AutoDownloadPrefs{MinKbps: 500}
 
-	prefs := AutoDownloadPrefs{MinSizeMB: 100, MaxSizeMB: 600}
+	filtered := prefs.filter(
+		[]Candidate{lossy, lossless}, okComputerRuntime,
+	)
 
-	filtered := prefs.filter([]Candidate{small, big})
-
-	if len(filtered) != 1 || filtered[0].ID != "big" {
+	if len(filtered) != 1 || filtered[0].ID != "lossless" {
 		t.Errorf("filter() = %v, want only the in-window candidate", filtered)
 	}
 }
 
-func TestAutoDownloadPrefsSizeFit(t *testing.T) {
+func TestAutoDownloadPrefsBitrateFit(t *testing.T) {
 	t.Parallel()
 
 	const neutral = 0.5
 
 	tests := []struct {
-		name      string
-		prefs     AutoDownloadPrefs
-		totalSize int64
-		want      float64
+		name  string
+		prefs AutoDownloadPrefs
+		c     Candidate
+		want  float64
 	}{
-		{"no preference is neutral", AutoDownloadPrefs{}, 300 * mb, neutral},
+		{
+			"no preference is neutral",
+			AutoDownloadPrefs{},
+			kbpsCandidate("c", ".flac", 900), neutral,
+		},
 		{
 			"exact match scores 1",
-			AutoDownloadPrefs{PreferredSizeMB: 300},
-			300 * mb, 1.0,
+			AutoDownloadPrefs{PreferredKbps: 320},
+			kbpsCandidate("c", ".mp3", 320), 1.0,
 		},
 		{
-			"double the preferred size scores 0",
-			AutoDownloadPrefs{PreferredSizeMB: 300},
-			600 * mb, 0.0,
+			// The floor is neutral, not zero: this term carries 0.40
+			// of the quality score once a preference is set, and a
+			// span to zero would let "I like 320" quietly disqualify
+			// every FLAC from auto-pick.
+			"double the preferred rate falls to the neutral floor",
+			AutoDownloadPrefs{PreferredKbps: 320},
+			kbpsCandidate("c", ".flac", 640), neutral,
 		},
 		{
-			"half the preferred size scores 0",
-			AutoDownloadPrefs{PreferredSizeMB: 300},
-			150 * mb, 0.0,
+			"half the preferred rate falls to the neutral floor",
+			AutoDownloadPrefs{PreferredKbps: 320},
+			kbpsCandidate("c", ".mp3", 160), neutral,
+		},
+		{
+			"an unknowable rate is neutral",
+			AutoDownloadPrefs{PreferredKbps: 320},
+			kbpsCandidate("c", ".mp3", 320), neutral,
 		},
 	}
 
@@ -409,30 +519,223 @@ func TestAutoDownloadPrefsSizeFit(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			if got := tt.prefs.sizeFit(tt.totalSize); got != tt.want {
-				t.Errorf("sizeFit(%d) = %f, want %f", tt.totalSize, got, tt.want)
+			// The last case deliberately withholds the runtime.
+			runtime := int64(okComputerRuntime)
+			if tt.name == "an unknowable rate is neutral" {
+				runtime = 0
+			}
+
+			if got := tt.prefs.bitrateFit(tt.c, runtime); got != tt.want {
+				t.Errorf("bitrateFit() = %f, want %f", got, tt.want)
 			}
 		})
 	}
 }
 
 // An otherwise-perfect candidate must not auto-pick when it falls
-// outside the configured size guard: the guardrail applies before the
-// match/quality/lead checks, not as one more input averaged into them.
-func TestAutoPickableRejectsCandidateOutsideSizeGuard(t *testing.T) {
+// outside the configured guardrails: they apply before the match and
+// quality checks, not as one more input averaged into them.
+func TestAutoPickableRejectsCandidateOutsideTheGuardrails(t *testing.T) {
 	t.Parallel()
 
 	dl := okComputer()
-	best := Score(dl, candidateFor("a", allTitles(), ".flac", 30_000_000), 50, AutoDownloadPrefs{})
-	best.TotalSize = 500 * mb
+	best := Score(dl, kbpsCandidate("a", ".flac", 900), 50, AutoDownloadPrefs{})
 
 	if !AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{}) {
 		t.Fatal("expected this candidate to be auto-pickable with no guardrails")
 	}
 
-	tight := AutoDownloadPrefs{MinSizeMB: 10, MaxSizeMB: 100}
+	if AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{MaxKbps: 320}) {
+		t.Error("candidate above the bitrate window must not auto-pick")
+	}
 
-	if AutoPickable(dl, []Candidate{best}, tight) {
-		t.Error("candidate outside the size guard must not auto-pick")
+	if AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{MaxSizeMB: 1}) {
+		t.Error("candidate above the size ceiling must not auto-pick")
+	}
+}
+
+// The refusal has to name the gate that refused.
+//
+// Before AutoPickVeto, every one of these came back as the same
+// sentence built from `ranked[0]` — the best candidate before the size
+// and format guardrails — so a request refused because the user's size
+// window excluded every copy reported a match and a quality that both
+// cleared their thresholds.  A refusal quoting numbers that pass is
+// what made the matcher look broken from outside.
+func TestAutoPickVetoNamesTheGate(t *testing.T) {
+	t.Parallel()
+
+	dl := okComputer()
+	best := Score(
+		dl,
+		candidateFor("a", allTitles(), ".flac", 30_000_000),
+		50,
+		AutoDownloadPrefs{},
+	)
+
+	// candidateFor sizes the files and leaves TotalSize at 0, which is
+	// what the guardrails read.
+	sized := func(c Candidate, total int64) Candidate {
+		c.TotalSize = total
+
+		return c
+	}
+
+	tests := []struct {
+		name    string
+		dl      Download
+		ranked  []Candidate
+		prefs   AutoDownloadPrefs
+		wantSub string
+	}{
+		{
+			name:    "nothing found",
+			dl:      dl,
+			ranked:  nil,
+			wantSub: "nothing found",
+		},
+		{
+			name:    "free text",
+			dl:      Download{Artist: "Radiohead", Album: "OK Computer"},
+			ranked:  []Candidate{best},
+			wantSub: "free text",
+		},
+		{
+			name: "no tracklist behind the anchor",
+			dl: Download{
+				ReleaseMBID: "mbid-ok-computer",
+				Artist:      "Radiohead",
+				Album:       "OK Computer",
+			},
+			ranked:  []Candidate{best},
+			wantSub: "no tracklist",
+		},
+		{
+			// The candidate is 120 MB and the window tops out at 1 MB:
+			// the old message reported its match and quality instead.
+			name:    "outside the size window",
+			dl:      dl,
+			ranked:  []Candidate{sized(best, 120<<20)},
+			prefs:   AutoDownloadPrefs{MaxSizeMB: 1},
+			wantSub: "bitrate, size or format limits",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := AutoPickVeto(tt.dl, tt.ranked, tt.prefs)
+			if !strings.Contains(got, tt.wantSub) {
+				t.Errorf("veto = %q, want it to mention %q", got, tt.wantSub)
+			}
+		})
+	}
+}
+
+// A clear winner has no veto at all — the sentence is empty, which is
+// what AutoPickable reads.
+func TestAutoPickVetoIsEmptyForAClearWinner(t *testing.T) {
+	t.Parallel()
+
+	dl := okComputer()
+	best := Score(
+		dl,
+		candidateFor("a", allTitles(), ".flac", 30_000_000),
+		50,
+		AutoDownloadPrefs{},
+	)
+	weak := Score(
+		dl,
+		candidateFor("b", allTitles()[:2], ".mp3", 1_000_000),
+		50,
+		AutoDownloadPrefs{},
+	)
+
+	if got := AutoPickVeto(dl, []Candidate{best, weak}, AutoDownloadPrefs{}); got != "" {
+		t.Errorf("veto = %q, want none", got)
+	}
+}
+
+// With several candidates that all clear the bar, the preferred
+// bitrate decides which one is taken.
+//
+// This is what replaced the daylight requirement.  Auto-pick no longer
+// refuses when the field is close; it takes the copy nearest the shape
+// the user asked for, which is the question they actually answered in
+// Settings.
+func TestPreferredBitrateBreaksTheTie(t *testing.T) {
+	t.Parallel()
+
+	dl := okComputer()
+	prefs := AutoDownloadPrefs{PreferredKbps: 320}
+
+	// Same album, same completeness, same health, same provider — the
+	// only difference between them is the rate.
+	lossless := kbpsCandidate("lossless", ".flac", 900)
+	perfect := kbpsCandidate("perfect", ".mp3", 320)
+
+	ranked := Rank(
+		dl, []Candidate{lossless, perfect}, nil, prefs,
+	)
+
+	if ranked[0].ID != "perfect" {
+		t.Errorf(
+			"winner = %q (fit %f) over %q (fit %f), want the 320 kbps copy",
+			ranked[0].ID, ranked[0].Quality.BitrateFit,
+			ranked[1].ID, ranked[1].Quality.BitrateFit,
+		)
+	}
+
+	if AutoPickVeto(dl, ranked, prefs) != "" {
+		t.Error("a close field must still auto-pick")
+	}
+}
+
+// With no preference set, nothing changes: BitrateFit is the same
+// neutral value for every candidate and the older tie-breaks decide.
+func TestNoPreferredBitrateLeavesRankingAlone(t *testing.T) {
+	t.Parallel()
+
+	dl := okComputer()
+
+	lossless := kbpsCandidate("lossless", ".flac", 900)
+	lossy := kbpsCandidate("lossy", ".mp3", 320)
+
+	ranked := Rank(
+		dl, []Candidate{lossy, lossless}, nil, AutoDownloadPrefs{},
+	)
+
+	if ranked[0].ID != "lossless" {
+		t.Errorf(
+			"winner = %q, want the lossless copy on format alone",
+			ranked[0].ID,
+		)
+	}
+}
+
+// A preferred bitrate promotes the copy that matches it and must never
+// disqualify the ones that do not.  It carries 0.40 of the quality
+// score, so a fit spanning down to zero would put a perfectly good FLAC
+// under minQuality and out of auto-pick — turning a preference into a
+// prohibition without saying so.  MinKbps and MaxKbps are how a user
+// says that on purpose.
+func TestAPreferredBitrateNeverDisqualifies(t *testing.T) {
+	t.Parallel()
+
+	dl := okComputer()
+	far := AutoDownloadPrefs{PreferredKbps: 128}
+
+	lossless := Score(dl, kbpsCandidate("flac", ".flac", 900), 50, far)
+
+	if lossless.Quality.Overall < minQuality {
+		t.Errorf(
+			"quality = %f under a far-off preference, want >= %f",
+			lossless.Quality.Overall, minQuality,
+		)
+	}
+
+	if veto := AutoPickVeto(dl, []Candidate{lossless}, far); veto != "" {
+		t.Errorf("a far-off preference vetoed the candidate: %s", veto)
 	}
 }

backend/download/reconcile.go

@@ -310,15 +310,35 @@ func (r *Reconciler) run(ctx context.Context, force bool) (Summary, error) {
 
 	summary.Synced = r.syncExternalLists(ctx)
 
-	attempted, started, err := r.attemptDue(ctx, force)
-	if err != nil {
-		return summary, err
+	// Nothing is searched for when there is nothing to search with, and
+	// the point is what that *does not* do to the list.
+	//
+	// Attempting anyway is not merely wasted work: every request comes
+	// back "no download clients are enabled", which RecordAttempt writes
+	// down as an attempt and schedules a retry for -- so a user who has
+	// deliberately built a wanted list with no client watched their
+	// requests accrue failures and announce "next check in 6 hours"
+	// about a check that cannot happen. Wanting something without a way
+	// to fetch it is a supported thing to do; being told it is being
+	// looked for is a lie.
+	//
+	// Everything above this line still runs: an artist subscription
+	// still expands, and a request the user satisfied by some other
+	// route -- ripped, bought, copied in -- is still retired, because
+	// neither needs a provider.
+	summary.NoProviders = len(r.manager.enabledProviders()) == 0
+
+	if !summary.NoProviders {
+		attempted, started, err := r.attemptDue(ctx, force)
+		if err != nil {
+			return summary, err
+		}
+
+		summary.Attempted = attempted
+		summary.Started = started
 	}
 
-	summary.Attempted = attempted
-	summary.Started = started
 	summary.Waiting = r.countWaiting(ctx)
-	summary.NoProviders = len(r.manager.enabledProviders()) == 0
 
 	r.logger.Info(
 		"reconciled request list",

backend/download/reconcile_test.go

@@ -453,6 +453,15 @@ func TestReconcileRespectsBatchSize(t *testing.T) {
 	f := newReconcileFixture(t)
 	ctx := context.Background()
 
+	// A client that searches and finds nothing. The batch size is about
+	// how many requests one pass *searches for*, which only means
+	// anything when there is something to search with -- a pass with no
+	// provider now attempts nothing at all, deliberately.
+	f.manager.installProvider(
+		Config{ID: 1, Priority: 50},
+		NewFakeProvider(1, "finds-nothing", Caps{CanSearch: true}),
+	)
+
 	f.reconciler.SetBatch(2)
 
 	for _, mbid := range []string{"rg-1", "rg-2", "rg-3", "rg-4"} {
@@ -593,3 +602,72 @@ func TestSummaryReportsNoProviders(t *testing.T) {
 		t.Error("summary did not report that no download client is enabled")
 	}
 }
+
+// ...and it does not search, which is the part the user sees.
+//
+// Attempting with no provider fails every request with "no download
+// clients are enabled", and RecordAttempt writes that down as an
+// attempt and schedules a retry -- so a wanted list built deliberately
+// without a client accrued failures and announced "next check in 6
+// hours" about a check that cannot happen. Wanting something with no
+// way to fetch it is supported; being told it is being looked for is
+// a lie.
+func TestNoProvidersMeansNoAttempt(t *testing.T) {
+	t.Parallel()
+
+	f := newReconcileFixture(t)
+	ctx := context.Background()
+
+	id, err := f.store.AddRequest(ctx, Request{
+		MBID:      "rg-1",
+		Entity:    EntityReleaseGroup,
+		LibraryID: 1,
+		Title:     "OK Computer",
+	})
+	if err != nil {
+		t.Fatalf("AddRequest: %v", err)
+	}
+
+	f.catalog.tracklists["rg-1"] = fourTrackDownload().Expected
+
+	summary, err := f.reconciler.RunNow(ctx)
+	if err != nil {
+		t.Fatalf("RunNow: %v", err)
+	}
+
+	if summary.Attempted != 0 {
+		t.Errorf("attempted %d requests with no client to search with, want 0",
+			summary.Attempted)
+	}
+
+	// The list still knows what is on it: "nothing happened" has to be
+	// reportable as "nothing was searched for, of the one thing you
+	// want" rather than as silence.
+	if summary.Waiting != 1 {
+		t.Errorf("summary reported %d waiting, want 1", summary.Waiting)
+	}
+
+	req, err := f.store.GetRequest(ctx, id)
+	if err != nil {
+		t.Fatalf("GetRequest: %v", err)
+	}
+
+	if req.Attempts != 0 {
+		t.Errorf("attempts = %d, want 0: a pass that could not search did not",
+			req.Attempts)
+	}
+
+	if req.LastError != "" {
+		t.Errorf("lastError = %q, want empty: the request did not fail, it "+
+			"was never tried", req.LastError)
+	}
+
+	// A new request is due immediately (next_try_at is set to now on
+	// insert), so the fault is not the presence of a time -- it is a
+	// time pushed into the future by a failed attempt, which is what the
+	// UI renders as "next check in 6 hours".
+	if req.NextTryAt.After(time.Now().Add(time.Minute)) {
+		t.Errorf("next try scheduled for %v: a check that cannot happen was "+
+			"put on the clock", req.NextTryAt)
+	}
+}

backend/download/service_test.go

@@ -36,13 +36,24 @@ func newServiceFixture(t *testing.T) serviceFixture {
 	// assertion read it; the second is that same goroutine still writing
 	// into `t.TempDir()` after the test returned. One cause, two shapes.
 	//
-	// Putting the candidate outside the auto-pick size window stops the
+	// Putting the candidate outside the auto-pick guardrails stops the
 	// grab from ever starting, which is better than waiting for it: there
 	// is no goroutine to be slow, so the tests state what they mean
 	// ("the request exists, in this state") without a timing assumption
 	// underneath. A test that does want the download has `managerFixture`
 	// and sets its own preferences.
-	mf.manager.SetPreferences(AutoDownloadPrefs{MaxSizeMB: 1})
+	//
+	// The guard is a *format* the fake never produces, and it used to be
+	// `MaxSizeMB: 1`, which never fired: the size gates read
+	// `Candidate.TotalSize`, which real providers fill and the fake
+	// leaves at zero, and zero is under every ceiling. So the grab went
+	// ahead anyway and the second failure shape above — the TempDir
+	// cleanup race — kept happening, reproducibly, roughly one run in
+	// fifteen. A guard has to be keyed on something the fixture
+	// actually sets.
+	mf.manager.SetPreferences(AutoDownloadPrefs{
+		AllowedFormats: []Format{FormatWMA},
+	})
 
 	return serviceFixture{managerFixture: mf, svc: svc}
 }
@@ -182,6 +193,11 @@ func TestManualDownloadSatisfiesRequestOnSuccess(t *testing.T) {
 	f := newServiceFixture(t)
 	ctx := context.Background()
 
+	// This is the one test here that is *about* the download, so it
+	// undoes the fixture's guard rather than relying on it — which is
+	// what it was doing implicitly while the guard did not work.
+	f.manager.SetPreferences(AutoDownloadPrefs{})
+
 	provider := fakeWithAlbum(1, "source", ".flac")
 	f.manager.installProvider(Config{ID: 1, Priority: 50}, provider)
 

backend/download/types.go

@@ -302,7 +302,12 @@ type QualityScore struct {
 	Bitrate    float64 `json:"bitrate"`
 	Health     float64 `json:"health"`   // seeders, free slots
 	Priority   float64 `json:"priority"` // user's per-provider preference
-	SizeFit    float64 `json:"sizeFit"`  // closeness to the preferred download size
+	// BitrateFit is closeness to the preferred *rate*, which is what
+	// the auto-download window is expressed in.  It replaced a
+	// `SizeFit` measured in megabytes: a size means nothing without
+	// knowing how long the music is, so the same number described a
+	// generous single and a suspiciously small boxset.
+	BitrateFit float64 `json:"bitrateFit"`
 
 	// Mixed marks a candidate whose files are not all the same format,
 	// which usually means a hand-assembled folder rather than a rip.

backend/explore/coverartproxy.go

@@ -25,8 +25,26 @@ const (
 	// where cached cover art thumbnails are stored.
 	thumbnailDir = CoverArtCacheDirName
 
-	// thumbnailTimeout is the HTTP timeout for fetching a thumbnail.
-	thumbnailTimeout = 10 * time.Second
+	// thumbnailTimeout is the HTTP timeout for fetching a thumbnail,
+	// and it has to cover a redirect the Cover Art Archive does not
+	// serve itself.
+	//
+	// `coverartarchive.org` answers `front-250` with a 307 to an
+	// Internet Archive storage node (`dn######.us.archive.org`), and
+	// those nodes are routinely slow: measured against the twelve
+	// albums on Explore's own shelves, a successful fetch took 14–16 s
+	// and a failing one 13–17 s. At 10 s *every* cover on the page
+	// timed out — 24 cards, 5 of which had art, all of those from the
+	// disk cache — which reads as "Explore has no album art" rather
+	// than as a slow upstream, because a timeout writes nothing and
+	// says nothing.
+	//
+	// 30 s is chosen to clear that measured range with room, not to be
+	// generous: the fetch is off the critical path (each one is its own
+	// goroutine behind an 8/s limiter, and the frontend renders a
+	// placeholder until it lands), so the cost of waiting is nothing
+	// and the cost of giving up early is a blank page.
+	thumbnailTimeout = 30 * time.Second
 
 	// thumbnailMaxSize is the maximum image size to cache (2 MB).
 	thumbnailMaxSize = 2 * 1024 * 1024
@@ -97,6 +115,20 @@ func (p *CoverArtProxy) GetThumbnail(
 		return ""
 	}
 
+	// A 404 is an answer, and it is already on disk.
+	//
+	// `writeCache(mbid, nil)` has recorded "the archive has no art for
+	// this" as an empty file since this was written, and nothing has
+	// ever read it back: `readCache` returns "" for an empty file,
+	// which is indistinguishable from a miss, so every art-less release
+	// group was re-fetched from the network on every render that asked
+	// about it. On Explore's shelves a third of the cards are art-less,
+	// so that was a third of the page spending a live CAA request to be
+	// told again what the last one said.
+	if p.knownMissing(releaseGroupMBID) {
+		return ""
+	}
+
 	// Source 3: fetch from Cover Art Archive (slow, cached to disk).
 	url := CoverArtGroupURL(releaseGroupMBID)
 	data, cacheable, err := p.fetch(url)
@@ -177,8 +209,9 @@ func (p *CoverArtProxy) GetCandidateThumbnail(
 		}
 	}
 
-	// Network fetch on release group.
-	if releaseGroupMBID != "" {
+	// Network fetch on release group — unless a previous one was told
+	// there is none. See `knownMissing`.
+	if releaseGroupMBID != "" && !p.knownMissing(releaseGroupMBID) {
 		url := CoverArtGroupURL(releaseGroupMBID)
 		data, cacheable, err := p.fetch(url)
 
@@ -194,7 +227,7 @@ func (p *CoverArtProxy) GetCandidateThumbnail(
 	}
 
 	// Network fetch on release (fallback).
-	if releaseMBID != "" {
+	if releaseMBID != "" && !p.knownMissing(releaseMBID) {
 		url := CoverArtURL(releaseMBID)
 		data, cacheable, err := p.fetch(url)
 
@@ -285,6 +318,17 @@ func (p *CoverArtProxy) cachePath(mbid string) string {
 	return filepath.Join(p.cacheDir, mbid+".jpg")
 }
 
+// knownMissing reports whether a previous fetch was told the archive
+// has no art for this MBID — the empty file `writeCache(mbid, nil)`
+// leaves behind. It is deliberately separate from `readCache`, which
+// answers "what are the bytes" and cannot express the difference
+// between no answer and an answer of none.
+func (p *CoverArtProxy) knownMissing(mbid string) bool {
+	info, err := os.Stat(p.cachePath(mbid))
+
+	return err == nil && info.Size() == 0
+}
+
 func (p *CoverArtProxy) readCache(mbid string) string {
 	path := p.cachePath(mbid)
 

backend/explore/explore.go

@@ -2212,6 +2212,7 @@ func (e *Service) gatherTopCandidates(
 				ArtistType: a.Type,
 				Country:    a.Country,
 				InLibrary:  a.InLibrary,
+				LocalID:    a.LocalID,
 			},
 			category:     "artist",
 			qualityScore: quality,
@@ -2243,6 +2244,7 @@ func (e *Service) gatherTopCandidates(
 				ArtistType: a.Type,
 				Country:    a.Country,
 				InLibrary:  a.InLibrary,
+				LocalID:    a.LocalID,
 			},
 			category:     "artist",
 			qualityScore: quality,
@@ -2275,6 +2277,7 @@ func (e *Service) gatherTopCandidates(
 				PrimaryType:  rg.PrimaryType,
 				Year:         year,
 				InLibrary:    rg.InLibrary,
+				LocalID:      rg.LocalID,
 			},
 			category:     "release_group",
 			qualityScore: quality,
@@ -2320,6 +2323,7 @@ func (e *Service) gatherTopCandidates(
 				PrimaryType:  rg.PrimaryType,
 				Year:         year,
 				InLibrary:    rg.InLibrary,
+				LocalID:      rg.LocalID,
 			},
 			category:     "release_group",
 			qualityScore: quality,
@@ -2347,6 +2351,7 @@ func (e *Service) gatherTopCandidates(
 				CAAReleaseMBID: r.CAAReleaseMBID,
 				ReleaseName:    r.ReleaseName,
 				InLibrary:      r.InLibrary,
+				LocalID:        r.LocalID,
 			},
 			category:     "recording",
 			qualityScore: quality,
@@ -2403,6 +2408,7 @@ func (e *Service) gatherTopCandidates(
 				CAAReleaseMBID: r.CAAReleaseMBID,
 				ReleaseName:    r.ReleaseName,
 				InLibrary:      r.InLibrary,
+				LocalID:        r.LocalID,
 			},
 			category:     "recording",
 			qualityScore: quality,
@@ -2425,6 +2431,7 @@ func (e *Service) gatherTopCandidates(
 					ArtistType: m.ArtistType,
 					Country:    m.Country,
 					InLibrary:  m.InLibrary || m.LocalArtistID > 0,
+					LocalID:    m.LocalArtistID,
 				},
 				category:     "artist",
 				qualityScore: quality,
@@ -2445,6 +2452,7 @@ func (e *Service) gatherTopCandidates(
 					PrimaryType:  m.PrimaryType,
 					Year:         year,
 					InLibrary:    m.InLibrary || m.LocalReleaseGroupID > 0,
+					LocalID:      m.LocalReleaseGroupID,
 				},
 				category:     "release_group",
 				qualityScore: quality,
@@ -2459,6 +2467,7 @@ func (e *Service) gatherTopCandidates(
 					ArtistMBID:   m.ArtistMBID,
 					Length:       m.Duration,
 					InLibrary:    m.InLibrary || m.LocalRecordingID > 0,
+					LocalID:      m.LocalRecordingID,
 				},
 				category:     "recording",
 				qualityScore: quality,

backend/explore/prune_test.go

@@ -82,6 +82,100 @@ func TestPruneStaleLocalCrossReferences(t *testing.T) {
 	}
 }
 
+// TestPruneClearsInLibraryWithNoLocalID covers the fixed point: a row
+// carrying in_library with a NULL local_*_id.  The upsert's conflict
+// clause is `in_library = MAX(in_library, excluded.in_library)`, so it
+// can only ever raise the flag, and this pass used to be gated on the id
+// being present — which meant nothing in the app could clear such a row,
+// ever.  It is asserted for all three entity types because the gate was
+// written once and used three times, so a fix applied to one is a fix
+// that looks complete.
+//
+// The rows are seeded with raw SQL rather than through seedIndexResult
+// deliberately: upsertBatch writes a zero LocalArtistID as literal 0,
+// not NULL, and 0 satisfies `IS NOT NULL` — so the old gate already
+// caught that shape and a fixture built through the upsert cannot
+// reproduce this at all.  NULL is what the artifact importer and any
+// older writer leave behind, the column being nullable with no default.
+func TestPruneClearsInLibraryWithNoLocalID(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	si := NewSearchIndex(db, nil, nil, slog.Default())
+
+	// A genuinely owned artist, to prove the wider gate does not simply
+	// clear everything it now looks at.
+	database.InsertTestTrack(t, db, database.TestTrack{
+		FilePath: "/music/owned.mp3",
+		Artist:   "Owned",
+	})
+
+	artist, err := db.Queries.GetArtistByName(t.Context(), "Owned")
+	if err != nil {
+		t.Fatalf("read seeded artist: %v", err)
+	}
+
+	seedIndexResult(t, db, SearchIndexResult{
+		EntityType:    EntityArtist,
+		MBID:          testMBID("owned"),
+		Title:         "Owned",
+		ArtistName:    "Owned",
+		ArtistMBID:    testMBID("owned"),
+		InLibrary:     true,
+		LocalArtistID: artist.ID,
+	})
+
+	orphans := []struct {
+		name       string
+		entityType string
+		mbid       string
+	}{
+		{"artist", EntityArtist, "orphan-artist"},
+		{"release group", EntityReleaseGroup, "orphan-release-group"},
+		{"recording", EntityRecording, "orphan-recording"},
+	}
+
+	for _, o := range orphans {
+		if _, err := db.ExecContext(
+			`INSERT INTO explore_index
+			     (entity_type, mbid, title, artist_name, artist_mbid,
+			      in_library,
+			      local_artist_id, local_release_group_id, local_recording_id)
+			 VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?)`,
+			dbEntityType(o.entityType), dbMBID(testMBID(o.mbid)), o.name, o.name,
+			dbMBID(testMBID(o.mbid)),
+			nil, nil, nil,
+		); err != nil {
+			t.Fatalf("seed %s orphan: %v", o.name, err)
+		}
+	}
+
+	si.pruneStaleLocalCrossReferences()
+
+	inLibrary := func(t *testing.T, mbid string) int {
+		t.Helper()
+
+		var flag int
+		if err := db.QueryRowWriter(
+			"SELECT in_library FROM explore_index WHERE mbid = ?", dbMBID(mbid),
+		).Scan(&flag); err != nil {
+			t.Fatalf("read in_library for %q: %v", mbid, err)
+		}
+
+		return flag
+	}
+
+	for _, o := range orphans {
+		if got := inLibrary(t, testMBID(o.mbid)); got != 0 {
+			t.Errorf("%s with a NULL local id: in_library = %d, want 0", o.name, got)
+		}
+	}
+
+	if got := inLibrary(t, testMBID("owned")); got != 1 {
+		t.Errorf("owned artist: in_library = %d, want 1 (it still has a file)", got)
+	}
+}
+
 // TestUnenrichedLibraryArtistMBIDs_OrdersByOwnedTrackCount verifies the
 // backfill queue prioritizes artists by how many tracks the user actually
 // owns, not by how many duplicate-mbid artist rows happen to exist (the

backend/explore/searchindex.go

@@ -2562,6 +2562,19 @@ func (si *SearchIndex) PopulateLocalCrossReferences() {
 // The row itself is left in place (it may still be part of the shipped
 // catalog, just no longer owned) — only the "this is mine" bookkeeping
 // is cleared.
+//
+// It is gated on the flag *or* the id, not on the id alone.  Gated on
+// the id, `in_library = 1 AND local_*_id IS NULL` is a fixed point: the
+// upsert can only ever raise the flag and this pass skipped such a row
+// by construction, so nothing in the app could clear it — a row claiming
+// to be owned, permanently, with no local row to check the claim
+// against.  Nothing in the tree writes that shape today
+// (collectLibraryEntities sets both together), which is exactly why it
+// is worth closing now: the exposure is a database written by an older
+// version, and the next writer that sets the flag without an id, which
+// nothing structurally prevents.  A NULL id fails the existence test on
+// its own, so the wider gate needs no second clause to say what "not
+// owned" means.
 func (si *SearchIndex) pruneStaleLocalCrossReferences() {
 	type prune struct {
 		entityType string
@@ -2594,7 +2607,8 @@ func (si *SearchIndex) pruneStaleLocalCrossReferences() {
 		result, err := si.db.ExecContext(
 			`UPDATE explore_index
 			 SET in_library = 0, `+p.column+` = NULL
-			 WHERE entity_type = ? AND `+p.column+` IS NOT NULL
+			 WHERE entity_type = ?
+			   AND (`+p.column+` IS NOT NULL OR in_library = 1)
 			   AND NOT EXISTS (`+p.exists+`)`,
 			dbEntityType(p.entityType),
 		)

backend/explore/types.go

@@ -41,7 +41,16 @@ type TopResult struct {
 	ReleaseGroupMBID string `json:"releaseGroupMbid,omitempty"`
 	ReleaseName      string `json:"releaseName,omitempty"`
 	// Library status — populated from index cross-reference columns.
-	InLibrary bool `json:"inLibrary"`
+	//
+	// LocalID is the one the cards read.  It is the local row behind
+	// this entity — an album, a file, an artist — and it is set and
+	// cleared by a test against `audio_files`, so it means "there is
+	// something of mine here".  InLibrary is written by the same pass
+	// but is a one-way ratchet the prune can only clear alongside a
+	// local id, so it is the weaker of the two and stays for scoring
+	// (`fwInLibrary`), which is where an approximate answer is fine.
+	InLibrary bool  `json:"inLibrary"`
+	LocalID   int64 `json:"localId,omitempty"`
 }
 
 // MBArtist is a Wails-friendly projection of a MusicBrainz artist.

backend/library/completeness_test.go

@@ -232,3 +232,112 @@ func TestGetAlbumCompleteness_EmptyAlbum(t *testing.T) {
 		t.Errorf("empty album reported %+v, want zero and unknown", got)
 	}
 }
+
+// The batch and the single-album query are two spellings of one
+// question, and the thing worth pinning is that they never disagree.
+//
+// They are genuinely different SQL — the single-album form is
+// correlated subqueries over one album, the batch is two grouping
+// levels over a slice — so the risk is not a typo but a drift in
+// meaning: a disc's total counted once per file, a duplicate counted
+// twice, a disc with no total silently covered by one that had one.
+// Every shape the table above cares about is staged here at once,
+// because a batch that is only ever asked about one album is not being
+// asked the question that can go wrong.
+func TestGetAlbumsCompletenessAgreesWithTheSingleAlbumQuery(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+
+	shapes := map[int][]track{
+		1: disc(1, 100, 12, 12),
+		2: disc(1, 200, 9, 12),
+		3: disc(1, 300, 13, 12),
+		4: {{recordingID: 400, disc: 1, number: 1}},
+		5: append(disc(1, 500, 10, 10), disc(2, 600, 2, 5)...),
+		6: append(
+			disc(1, 700, 10, 10),
+			track{recordingID: 750, disc: 2, number: 1},
+		),
+		7: append(
+			disc(1, 800, 5, 6),
+			track{recordingID: 899, disc: 1, number: 3, total: 6},
+		),
+	}
+
+	ids := make([]int64, 0, len(shapes))
+
+	for albumID, tracks := range shapes {
+		stageAlbum(t, lib, albumID, tracks)
+		ids = append(ids, albumIDFor(t, lib, albumID))
+	}
+
+	batch, err := lib.GetAlbumsCompleteness(ids)
+	if err != nil {
+		t.Fatalf("GetAlbumsCompleteness: %v", err)
+	}
+
+	if len(batch) != len(ids) {
+		t.Fatalf("batch answered for %d albums, want %d", len(batch), len(ids))
+	}
+
+	for _, id := range ids {
+		one, err := lib.GetAlbumCompleteness(id)
+		if err != nil {
+			t.Fatalf("GetAlbumCompleteness(%d): %v", id, err)
+		}
+
+		if got := batch[id]; got != one {
+			t.Errorf("album %d: batch says %+v, single says %+v", id, got, one)
+		}
+	}
+}
+
+// An album with no files is absent from the batch, not zeroed.
+//
+// "I have none of this" and "I have no idea" are the third state Known
+// exists to keep apart, and a caller reading a missing key gets nothing
+// rather than a confident zero it would have to know to distrust.
+func TestGetAlbumsCompletenessOmitsAnAlbumWithNoFiles(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+
+	stageAlbum(t, lib, 1, disc(1, 100, 3, 3))
+
+	held := albumIDFor(t, lib, 1)
+
+	got, err := lib.GetAlbumsCompleteness([]int64{held, 4242})
+	if err != nil {
+		t.Fatalf("GetAlbumsCompleteness: %v", err)
+	}
+
+	if _, ok := got[4242]; ok {
+		t.Errorf("an album with no files answered %+v, want absent", got[4242])
+	}
+
+	if !got[held].Complete {
+		t.Errorf("held album reported %+v, want complete", got[held])
+	}
+}
+
+// A caller with nothing to ask about must not issue a query at all —
+// sqlc's empty-slice branch rewrites the placeholder to NULL, which is
+// a perfectly valid query returning nothing, so this is about the round
+// trip rather than the answer.
+func TestGetAlbumsCompletenessAsksNothingForAnEmptyList(t *testing.T) {
+	t.Parallel()
+
+	lib, _ := setupTestLibrary(t)
+
+	for _, ids := range [][]int64{nil, {}, {0}, {-1, 0}} {
+		got, err := lib.GetAlbumsCompleteness(ids)
+		if err != nil {
+			t.Fatalf("GetAlbumsCompleteness(%v): %v", ids, err)
+		}
+
+		if len(got) != 0 {
+			t.Errorf("GetAlbumsCompleteness(%v) = %+v, want empty", ids, got)
+		}
+	}
+}

backend/library/library.go

@@ -289,8 +289,13 @@ func (l *Library) scanInternal(
 		l.mu.Unlock()
 	}()
 
+	// The configured mode, not a hardcoded "auto".  `ScanConcurrency`
+	// has been a validated config field with three values and one
+	// caller passing a constant, so choosing `ssd` or `hdd` by hand
+	// did nothing at all.
+	diskProfile := system.ProfileForPath(libraryPath)
 	workerCount := resolveScanWorkerCount(
-		ScanConcurrencyAuto,
+		l.conf.ScanConcurrency,
 		libraryPath,
 	)
 
@@ -300,6 +305,10 @@ func (l *Library) scanInternal(
 		"libraryName", libraryName,
 		"libraryPath", libraryPath,
 		"workers", workerCount,
+		"mode", l.conf.ScanConcurrency,
+		"device", diskProfile.Device,
+		"rotational", diskProfile.Rotational,
+		"queueDepth", diskProfile.QueueDepth,
 	)
 
 	// Helper to build a ScanProgress with library identification.
@@ -818,7 +827,7 @@ func (l *Library) scanInternal(
 	g := new(errgroup.Group)
 	g.SetLimit(workerCount)
 
-	for work := range workChan {
+	for work := range readaheadWork(scanCtx, workChan, diskProfile) {
 		g.Go(func() error {
 			if err := l.waitIfPaused(scanCtx); err != nil {
 				return err
@@ -1285,9 +1294,101 @@ func surveyAudioFiles(
 	return count, maxModTime
 }
 
-// hddWorkerCount is the maximum number of concurrent extraction
-// workers when the library resides on a spinning disk.
-const hddWorkerCount = 2
+// How many extraction workers a spinning disk gets, and why it is two
+// numbers rather than one.
+//
+// Extraction is not CPU work — every parser here reads headers and
+// returns — so on a spinning disk the whole cost is seek latency, and
+// the only question worth asking is how many reads should be in flight
+// at once.  That has two different right answers and the drive says
+// which:
+//
+//   - A drive with command queueing (NCQ: /sys/block/<dev>/device/
+//     queue_depth reports 31 or 32 on any SATA disk with it enabled)
+//     reorders outstanding reads into the order its head passes over
+//     them.  Handing it several at once is most of why a parallel scan
+//     beats a serial one at all, and four is where the returns flatten:
+//     the drive needs a few requests to have anything to reorder, and
+//     past that it is queueing requests it was already going to
+//     service in that order.
+//   - A drive without it — queue_depth 1, which is what a USB bridge
+//     or a pre-2004 disk reports — services one command at a time in
+//     the order given.  Every extra worker there is one more seek
+//     competing for one head, and the scan gets *slower* the harder it
+//     is pushed.  Two is kept rather than one because the readahead
+//     hints (see readaheadWork) do the overlapping that concurrency
+//     was standing in for, and one worker cannot hide a stall.
+//
+// This used to be a flat 2 for anything rotational, which is a
+// pre-NCQ assumption: it left a modern spinning disk with a quarter of
+// the queue depth it can use.
+const (
+	hddWorkerCountQueued = 4
+	hddWorkerCountSerial = 2
+)
+
+// Readahead tuning.
+const (
+	// readaheadDepth is how many files ahead of the workers the
+	// prefetcher runs.  It is the channel's buffer, so it is also the
+	// number of `WILLNEED` hints outstanding at once — comfortably more
+	// than a queueing drive's 32-command window is worth filling with
+	// one library, and small enough that a cancelled scan is not
+	// holding a long tail of queued reads.
+	readaheadDepth = 16
+
+	// readaheadBytes is how much of each file to pull in.  Everything
+	// the scanner reads lives at the head: ID3v2 and FLAC's
+	// STREAMINFO/VORBIS_COMMENT/PICTURE blocks, and the first MPEG
+	// frame with its Xing header.  512 KB covers a tag carrying
+	// embedded cover art, which is the large case — and reading a
+	// little too much sequentially costs a spinning disk almost
+	// nothing next to the seek that got there.
+	readaheadBytes = 512 << 10
+)
+
+// readaheadWork forwards scan work while asking the kernel to fetch
+// each file's header before a worker reaches it.
+//
+// The buffered channel *is* the lookahead: this goroutine runs ahead
+// of the workers until the buffer fills, hinting every file as it goes,
+// so by the time a worker takes an item the read it needs has been in
+// flight for `readaheadDepth` files' worth of parsing.  That is the
+// only thing that helps a spinning disk here, because the per-file work
+// is already header-only — every parser in `backend/metadata` reads a
+// few hundred bytes and returns, so the scan is not waiting on CPU or
+// on bytes, it is waiting on the head to arrive.
+//
+// It runs on rotational disks only.  An SSD has no seek to hide and
+// already has one worker per core; issuing hints there is pure syscall
+// overhead against an OS readahead that is already ahead of us.
+func readaheadWork(
+	ctx context.Context,
+	in <-chan scanWork,
+	profile system.DiskProfile,
+) <-chan scanWork {
+	if !profile.Rotational {
+		return in
+	}
+
+	out := make(chan scanWork, readaheadDepth)
+
+	go func() {
+		defer close(out)
+
+		for work := range in {
+			hintReadahead(work.absolutePath, readaheadBytes)
+
+			select {
+			case out <- work:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}()
+
+	return out
+}
 
 // resolveScanWorkerCount returns the number of concurrent
 // extraction workers based on the configured concurrency mode
@@ -1296,20 +1397,45 @@ func resolveScanWorkerCount(
 	mode ScanConcurrency,
 	libraryPath string,
 ) int {
+	return workersForProfile(
+		mode,
+		system.ProfileForPath(libraryPath),
+		goruntime.NumCPU(),
+	)
+}
+
+// workersForProfile is the policy on its own, so it can be tested
+// against drives this machine does not have.
+//
+// `hdd` and `ssd` override what the device says rather than being a
+// separate branch: the mode is the user overruling detection, and
+// detection is right about the queue depth either way — a user who
+// picks `hdd` on a queueing drive still wants that drive's queue used.
+func workersForProfile(
+	mode ScanConcurrency,
+	profile system.DiskProfile,
+	cpus int,
+) int {
+	spinning := profile.Rotational
+
 	switch mode {
 	case ScanConcurrencySSD:
-		return goruntime.NumCPU()
+		spinning = false
 	case ScanConcurrencyHDD:
-		return min(hddWorkerCount, goruntime.NumCPU())
-	default: // auto
-		if system.IsRotationalDisk(libraryPath) {
-			return min(
-				hddWorkerCount, goruntime.NumCPU(),
-			)
-		}
-
-		return goruntime.NumCPU()
+		spinning = true
+	case ScanConcurrencyAuto:
 	}
+
+	if !spinning {
+		return cpus
+	}
+
+	workers := hddWorkerCountSerial
+	if profile.Queues() {
+		workers = hddWorkerCountQueued
+	}
+
+	return min(workers, cpus)
 }
 
 // scanWork represents a file to be processed by a worker.

backend/library/query.go

@@ -244,6 +244,65 @@ func (l *Library) GetAlbumCompleteness(albumID int64) (AlbumCompleteness, error)
 	}, nil
 }
 
+// GetAlbumsCompleteness answers the same question for a screenful of
+// albums in one query, keyed by album id.
+//
+// A card grid asks this about every card that has a local album behind
+// it, and one query per card is how a grid of fifty albums becomes
+// fifty round trips. The answer matters there for the reason it
+// matters on the album page: an album held 9 tracks of 12 has to show
+// the count, and a bare tick saying "in your library" is the complaint
+// this whole rule came from.
+//
+// An album with no row in the result is one with no files, and it is
+// absent rather than zeroed — "I have none of this" and "I have no
+// idea" are the same third state `Known` exists to keep apart, and a
+// caller reading a missing key gets nothing rather than a confident 0.
+func (l *Library) GetAlbumsCompleteness(
+	albumIDs []int64,
+) (map[int64]AlbumCompleteness, error) {
+	out := make(map[int64]AlbumCompleteness, len(albumIDs))
+
+	if len(albumIDs) == 0 {
+		return out, nil
+	}
+
+	keys := make([]sql.NullInt64, 0, len(albumIDs))
+
+	for _, id := range albumIDs {
+		if id <= 0 {
+			continue
+		}
+
+		keys = append(keys, sql.NullInt64{Int64: id, Valid: true})
+	}
+
+	if len(keys) == 0 {
+		return out, nil
+	}
+
+	rows, err := l.db.ReadQueries.GetAlbumsCompleteness(l.ctx, keys)
+	if err != nil {
+		l.logger.Error("could not get album completeness in batch",
+			"albums", len(keys), "error", err)
+
+		return nil, fmt.Errorf("could not get album completeness: %w", err)
+	}
+
+	for _, row := range rows {
+		known := row.Known != 0 && row.Expected > 0
+
+		out[row.AlbumID] = AlbumCompleteness{
+			Owned:    int(row.Owned),
+			Expected: int(row.Expected),
+			Known:    known,
+			Complete: known && row.Owned >= row.Expected,
+		}
+	}
+
+	return out, nil
+}
+
 // GetAlbumTracks returns one album's tracks in disc/track order.
 func (l *Library) GetAlbumTracks(albumID, libraryID int64) ([]Track, error) {
 	rows, err := l.db.ReadQueries.GetTracksByAlbum(

backend/library/readahead_linux.go

@@ -0,0 +1,38 @@
+//go:build linux
+
+package library
+
+import (
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+// hintReadahead asks the kernel to start fetching the head of a file
+// that is about to be read.
+//
+// `POSIX_FADV_WILLNEED` returns immediately and queues the read, which
+// is the whole point: on a spinning disk the first access to a file
+// costs a seek of several milliseconds, and that latency can only be
+// hidden by having the next seek already in flight while the current
+// file is being parsed.  A drive with command queueing can then service
+// the queued reads in head order rather than in the order they were
+// asked for.
+//
+// Errors are dropped on purpose.  This is a hint: a file that has since
+// been deleted, a filesystem that does not implement fadvise, or a
+// permission the walk saw and this open does not, all mean "no
+// prefetch", never "fail the scan".  The read that follows is what
+// reports a genuine problem.
+func hintReadahead(path string, bytes int64) {
+	f, err := os.Open(path)
+	if err != nil {
+		return
+	}
+
+	defer func() { _ = f.Close() }()
+
+	_ = unix.Fadvise(
+		int(f.Fd()), 0, bytes, unix.FADV_WILLNEED,
+	)
+}

backend/library/readahead_other.go

@@ -0,0 +1,13 @@
+//go:build !linux
+
+package library
+
+// hintReadahead is a no-op off Linux.
+//
+// macOS has `F_RDADVISE` and Windows has `FILE_FLAG_SEQUENTIAL_SCAN`,
+// and neither is wired up here for the reason the scan concurrency
+// heuristic is not either: this package cannot tell a spinning disk
+// from an SSD on those platforms (see system.ProfileForPath), so it
+// would be prefetching without knowing whether prefetching is what the
+// device wants.
+func hintReadahead(_ string, _ int64) {}

backend/library/scan_workers_test.go

@@ -0,0 +1,122 @@
+package library
+
+import (
+	"context"
+	"testing"
+
+	"yellowjacket/backend/system"
+)
+
+// How many workers a scan gets is decided by two facts about the
+// device, and the second one is new: a spinning disk that can queue
+// commands wants several reads in flight, and one that cannot wants
+// almost none.  Before this it was a flat 2 for anything rotational,
+// which is a pre-NCQ assumption — a modern SATA disk reports a queue
+// depth of 32 and was being given a quarter of what it can use.
+func TestWorkersForProfile(t *testing.T) {
+	t.Parallel()
+
+	const cpus = 16
+
+	ssd := system.DiskProfile{Device: "sda", QueueDepth: 32}
+	hddQueued := system.DiskProfile{
+		Device: "sdb", Rotational: true, QueueDepth: 32,
+	}
+	hddSerial := system.DiskProfile{
+		Device: "sdc", Rotational: true, QueueDepth: 1,
+	}
+	// Neither NVMe nor a device-mapper volume publishes queue_depth.
+	// An unknown depth must not be read as "cannot queue", or every
+	// such device would be scanned as if it were a 2003 drive.
+	unknown := system.DiskProfile{Device: "dm-0", Rotational: true}
+
+	tests := []struct {
+		name    string
+		mode    ScanConcurrency
+		profile system.DiskProfile
+		want    int
+	}{
+		{"ssd auto", ScanConcurrencyAuto, ssd, cpus},
+		{"queueing hdd auto", ScanConcurrencyAuto, hddQueued, hddWorkerCountQueued},
+		{"serial hdd auto", ScanConcurrencyAuto, hddSerial, hddWorkerCountSerial},
+		{"unknown depth queues", ScanConcurrencyAuto, unknown, hddWorkerCountQueued},
+
+		// The mode overrules detection about the *disk*, never about
+		// its queue: forcing hdd on a queueing drive still uses it.
+		{"forced hdd on an ssd", ScanConcurrencyHDD, ssd, hddWorkerCountQueued},
+		{"forced ssd on an hdd", ScanConcurrencySSD, hddQueued, cpus},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			if got := workersForProfile(tt.mode, tt.profile, cpus); got != tt.want {
+				t.Errorf(
+					"workersForProfile(%q, %+v) = %d, want %d",
+					tt.mode, tt.profile, got, tt.want,
+				)
+			}
+		})
+	}
+}
+
+// A machine with fewer cores than the policy asks for gets its cores.
+func TestWorkersNeverExceedTheCPUCount(t *testing.T) {
+	t.Parallel()
+
+	hdd := system.DiskProfile{Rotational: true, QueueDepth: 32}
+
+	if got := workersForProfile(ScanConcurrencyAuto, hdd, 1); got != 1 {
+		t.Errorf("single-core hdd = %d workers, want 1", got)
+	}
+}
+
+// The prefetch stage must forward every item and nothing else: it is a
+// pass-through with a side effect, and a scan that drops a file because
+// of a *hint* would be a spectacular way to lose part of a library.
+func TestReadaheadForwardsEveryFile(t *testing.T) {
+	t.Parallel()
+
+	in := make(chan scanWork, 4)
+	for _, p := range []string{"/a", "/b", "/c", "/d"} {
+		in <- scanWork{absolutePath: p}
+	}
+
+	close(in)
+
+	var got []string
+	for w := range readaheadWork(
+		context.Background(),
+		in,
+		system.DiskProfile{Rotational: true, QueueDepth: 32},
+	) {
+		got = append(got, w.absolutePath)
+	}
+
+	want := []string{"/a", "/b", "/c", "/d"}
+	if len(got) != len(want) {
+		t.Fatalf("forwarded %v, want %v", got, want)
+	}
+
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("item %d = %q, want %q", i, got[i], want[i])
+		}
+	}
+}
+
+// On an SSD the stage is not inserted at all — the channel comes back
+// unchanged, so a scan there pays nothing for a feature it cannot use.
+func TestReadaheadIsSkippedOnSolidState(t *testing.T) {
+	t.Parallel()
+
+	in := make(chan scanWork)
+	out := readaheadWork(
+		context.Background(), in, system.DiskProfile{QueueDepth: 32},
+	)
+
+	if out != (<-chan scanWork)(in) {
+		t.Error("an ssd must get the original channel, unwrapped")
+	}
+}

backend/mediacontrols/mpris_linux.go

@@ -279,17 +279,19 @@ func (h *MPRISHandler) enqueue(fn func()) {
 	}
 }
 
-// UpdateMetadata pushes track metadata to D-Bus.
-func (h *MPRISHandler) UpdateMetadata(meta Metadata) {
-	h.mu.Lock()
-	h.trackID++
-	tid := h.trackID
-	h.mu.Unlock()
-
-	m := map[string]interface{}{
+// metadataMap builds the org.mpris.MediaPlayer2.Player Metadata value
+// for one track.
+//
+// It is separated from UpdateMetadata, which needs a live D-Bus
+// connection, so the map's contents can be asserted on: this file is
+// behind a build tag and everything in it that touches h is reachable
+// only from a session bus, which is the same reason the Android
+// contract lives in an untagged androidpayload.go.
+func metadataMap(meta Metadata, trackID uint64) map[string]any {
+	m := map[string]any{
 		"mpris:trackid": dbus.ObjectPath(
 			fmt.Sprintf(
-				"/org/yellowjacket/Track/%d", tid,
+				"/org/yellowjacket/Track/%d", trackID,
 			),
 		),
 	}
@@ -306,16 +308,45 @@ func (h *MPRISHandler) UpdateMetadata(meta Metadata) {
 		m["xesam:album"] = meta.Album
 	}
 
+	// Always present, even with nothing to point at.
+	//
+	// Every other key here can be omitted safely because a client
+	// reading the map sees a track with no title or no album and
+	// renders it that way. Art is different: KDE's applet (and
+	// others) treat an *absent* mpris:artUrl as "no news about the
+	// art" and keep drawing whatever the last track had, so playing
+	// something with no cover left the previous album's sleeve on
+	// screen — which reads as the wrong track playing rather than as
+	// missing artwork.
+	//
+	// An empty string is the honest answer and is what the spec's
+	// "URI" type degrades to; a client that cannot load it falls back
+	// to its own placeholder, which is the behaviour wanted.
+	artURL := ""
 	if meta.ArtFilePath != "" {
-		m["mpris:artUrl"] = "file://" + meta.ArtFilePath
+		artURL = "file://" + meta.ArtFilePath
 	}
 
+	m["mpris:artUrl"] = artURL
+
 	if meta.DurationSec > 0 {
 		m["mpris:length"] = int64(
 			meta.DurationSec,
 		) * usPerSec
 	}
 
+	return m
+}
+
+// UpdateMetadata pushes track metadata to D-Bus.
+func (h *MPRISHandler) UpdateMetadata(meta Metadata) {
+	h.mu.Lock()
+	h.trackID++
+	tid := h.trackID
+	h.mu.Unlock()
+
+	m := metadataMap(meta, tid)
+
 	h.enqueue(func() {
 		h.props.SetMust(playerIf, "Metadata", m)
 	})

backend/mediacontrols/mpris_linux_test.go

@@ -0,0 +1,86 @@
+//go:build linux && !android
+
+package mediacontrols
+
+import "testing"
+
+// The one key that must be present even when it is empty.
+//
+// Everything else in the map may be omitted, because a client reading
+// it renders a track with no title as a track with no title. Art is
+// different: KDE's applet treats an *absent* mpris:artUrl as no news
+// about the art and keeps drawing the last one it saw, so a track with
+// no cover wore the previous album's sleeve — which reads as the wrong
+// track playing rather than as missing artwork.
+func TestMetadataMapAlwaysCarriesArtURL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		meta Metadata
+		want string
+	}{
+		{
+			name: "no art at all",
+			meta: Metadata{Title: "Blue in Green"},
+			want: "",
+		},
+		{
+			name: "art on disk",
+			meta: Metadata{
+				Title:       "Blue in Green",
+				ArtFilePath: "/covers/kind-of-blue_lg.jpg",
+			},
+			want: "file:///covers/kind-of-blue_lg.jpg",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			m := metadataMap(tt.meta, 1)
+
+			got, ok := m["mpris:artUrl"]
+			if !ok {
+				t.Fatal("mpris:artUrl is absent; it must always be sent")
+			}
+
+			if got != tt.want {
+				t.Errorf("mpris:artUrl = %v, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// The trackid has to change between tracks or a client is entitled to
+// treat the metadata as describing the same track it already has.
+func TestMetadataMapTrackIDVaries(t *testing.T) {
+	t.Parallel()
+
+	first := metadataMap(Metadata{Title: "A"}, 1)["mpris:trackid"]
+	second := metadataMap(Metadata{Title: "B"}, 2)["mpris:trackid"]
+
+	if first == second {
+		t.Errorf("trackid did not change: %v", first)
+	}
+}
+
+// The optional keys stay optional — this is what makes artUrl's
+// always-present treatment a deliberate exception rather than drift.
+func TestMetadataMapOmitsEmptyOptionalFields(t *testing.T) {
+	t.Parallel()
+
+	m := metadataMap(Metadata{}, 1)
+
+	for _, key := range []string{
+		"xesam:title",
+		"xesam:artist",
+		"xesam:album",
+		"mpris:length",
+	} {
+		if _, ok := m[key]; ok {
+			t.Errorf("%s is present for an empty Metadata", key)
+		}
+	}
+}

backend/player/buffered_stall_test.go

@@ -0,0 +1,188 @@
+package player
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/gopxl/beep/v2"
+)
+
+// errTestDecode stands in for a decoder blowing up mid-track.
+var errTestDecode = errors.New("decode blew up")
+
+// stalledStreamer never produces a sample and never reports
+// end-of-stream: (0, true), forever. A damaged file that decodes to
+// nothing looks like this, and so does any source whose producer has
+// quietly stopped.
+type stalledStreamer struct{}
+
+func (stalledStreamer) Stream(_ [][2]float64) (int, bool) { return 0, true }
+func (stalledStreamer) Err() error                        { return nil }
+
+// failingStreamer produces n good samples and then fails, which is
+// what a decode error mid-track looks like: the same (0, false) a
+// finished track returns, distinguishable only by Err.
+type failingStreamer struct {
+	remaining int
+	err       error
+}
+
+func (f *failingStreamer) Stream(samples [][2]float64) (int, bool) {
+	if f.remaining <= 0 {
+		return 0, false
+	}
+
+	n := min(len(samples), f.remaining)
+
+	for i := range n {
+		samples[i] = [2]float64{1, 1}
+	}
+
+	f.remaining -= n
+
+	return n, true
+}
+
+func (f *failingStreamer) Err() error { return f.err }
+
+// drainUntilEnd calls Stream until it reports end-of-stream, or gives
+// up. It returns whether the stream ended.
+//
+// The give-up bound is wall clock rather than a call count: the stall
+// budget is a duration, so a tight loop has to actually wait it out.
+func drainUntilEnd(bs *BufferedStreamer, within time.Duration) bool {
+	buf := make([][2]float64, 512)
+	deadline := time.Now().Add(within)
+
+	for time.Now().Before(deadline) {
+		if _, ok := bs.Stream(buf); !ok {
+			return true
+		}
+
+		time.Sleep(time.Millisecond)
+	}
+
+	return false
+}
+
+// A source that stops producing without ever ending is the fault this
+// whole file exists for: Stream used to answer with silence and ok
+// forever, so the chain never ended, the player stayed in Playing
+// with the button showing pause, and the decoder's position never
+// moved -- a frozen seek bar over a track that was not playing.
+func TestAStalledSourceEndsTheStream(t *testing.T) {
+	bs := NewBufferedStreamer(stalledStreamer{}, 2048)
+	defer bs.Close()
+
+	if !drainUntilEnd(bs, maxStarvedDuration+2*time.Second) {
+		t.Fatal(
+			"a stalled source never ended the stream: the player " +
+				"would sit in Playing with a frozen position",
+		)
+	}
+
+	if !errors.Is(bs.Err(), errSourceStalled) {
+		t.Fatalf(
+			"expected the stall to be reported, got %v", bs.Err(),
+		)
+	}
+}
+
+// Close is the other exit that used to leave `done` false, with the
+// same consequence: the ring drains and every call after it is
+// silence that claims to be audio.
+func TestClosingEndsTheStream(t *testing.T) {
+	bs := NewBufferedStreamer(finiteStreamer(1<<20), 2048)
+
+	// Let the read-ahead fill something, so this exercises the drain
+	// after Close rather than a buffer that was empty anyway.
+	time.Sleep(20 * time.Millisecond)
+	bs.Close()
+
+	if !drainUntilEnd(bs, 2*time.Second) {
+		t.Fatal("a closed streamer never reported end-of-stream")
+	}
+}
+
+// A source that fails is not a source that finished, and only Err
+// tells them apart. Before this, the player reported a mid-track
+// decode failure to the queue as a natural end, so the queue
+// auto-advanced in silence and counted the broken track as played.
+func TestAFailedSourceReportsItsError(t *testing.T) {
+	src := &failingStreamer{remaining: 4096, err: errTestDecode}
+
+	bs := NewBufferedStreamer(src, 2048)
+	defer bs.Close()
+
+	if !drainUntilEnd(bs, 2*time.Second) {
+		t.Fatal("a failing source never reported end-of-stream")
+	}
+
+	if !errors.Is(bs.Err(), errTestDecode) {
+		t.Fatalf(
+			"expected the source's error to survive, got %v",
+			bs.Err(),
+		)
+	}
+}
+
+// The ordinary case has to keep working: a source that ends cleanly
+// ends with no error, or every finished track would be reported as a
+// failure and skipped.
+func TestADrainedSourceReportsNoError(t *testing.T) {
+	bs := NewBufferedStreamer(finiteStreamer(4096), 2048)
+	defer bs.Close()
+
+	if !drainUntilEnd(bs, 2*time.Second) {
+		t.Fatal("a finite source never reported end-of-stream")
+	}
+
+	if bs.Err() != nil {
+		t.Fatalf(
+			"a track that finished normally reported %v", bs.Err(),
+		)
+	}
+}
+
+// A slow source is exactly what the read-ahead exists to absorb, so
+// underruns must not be charged cumulatively -- otherwise a file on a
+// slow disk ends itself partway through.
+func TestUnderrunsDoNotAccumulateAcrossASlowSource(t *testing.T) {
+	const total = 8192
+
+	src := &slowStreamer{
+		inner: finiteStreamer(total),
+		delay: 2 * time.Millisecond,
+	}
+
+	bs := NewBufferedStreamer(src, 1024)
+	defer bs.Close()
+
+	buf := make([][2]float64, 256)
+	got := 0
+
+	for {
+		n, ok := bs.Stream(buf)
+		if !ok {
+			break
+		}
+
+		for i := range n {
+			if buf[i][0] != 0 {
+				got++
+			}
+		}
+	}
+
+	if got != total {
+		t.Fatalf(
+			"a slow but healthy source was cut short: got %d of %d "+
+				"samples",
+			got, total,
+		)
+	}
+}
+
+// beep.Streamer is what the player wraps; keep the type honest.
+var _ beep.Streamer = (*BufferedStreamer)(nil)

backend/player/buffered_streamer.go

@@ -1,6 +1,7 @@
 package player
 
 import (
+	"errors"
 	"sync"
 	"time"
 
@@ -34,8 +35,45 @@ type BufferedStreamer struct {
 	done    bool
 	err     error
 	closed  chan struct{}
+
+	// starved counts consecutive Stream calls served with silence
+	// because the ring was empty, and starvedSince is when that run
+	// began.  An underrun is legitimate for a moment -- that is what
+	// the read-ahead exists to absorb -- but it is not legitimate
+	// forever, and "forever" is indistinguishable from healthy
+	// playback everywhere above this type: the chain never ends, so
+	// the player stays in Playing with the button showing pause, and
+	// the decoder's position never moves, so the 1 Hz report pins the
+	// seek bar and suppresses its interpolation.
+	starved      int
+	starvedSince time.Time
 }
 
+// The silence fill is bounded by both a duration and a run of calls,
+// and it needs both.
+//
+// Duration alone is the real measure -- the speaker paces itself, so
+// wall clock is what says whether the source has actually stopped --
+// but a caller draining in a tight loop (a test, a decode-to-buffer)
+// makes hundreds of calls in microseconds and would trip nothing.
+// A call count alone is the opposite failure: the same tight loop
+// spends the whole budget before the read-ahead goroutine has been
+// scheduled once, and ends a perfectly good stream at sample zero.
+//
+// The duration is longer than the 2 s read-ahead it is there to
+// outlast, and the count is short enough that the speaker (~200 ms a
+// call) reaches it well inside that.
+const (
+	maxStarvedDuration = 3 * time.Second
+	minStarvedCalls    = 8
+)
+
+// errSourceStalled is returned by Err when the source stopped
+// producing samples without ever reporting end-of-stream.
+var errSourceStalled = errors.New(
+	"audio source stopped producing samples",
+)
+
 // NewBufferedStreamer creates a BufferedStreamer that pre-fills
 // bufferSize samples from source via a background goroutine.
 // A typical bufferSize is 2× the sample rate (~2 seconds of audio).
@@ -54,8 +92,24 @@ func NewBufferedStreamer(
 	return bs
 }
 
+// finish marks the stream ended, recording err as the reason when
+// there is one.  Every exit from readAhead goes through it: an exit
+// that leaves done false strands Stream in its underrun branch,
+// where it returns silence and ok forever.
+func (bs *BufferedStreamer) finish(err error) {
+	bs.mu.Lock()
+	defer bs.mu.Unlock()
+
+	bs.done = true
+
+	if err != nil && bs.err == nil {
+		bs.err = err
+	}
+}
+
 // readAhead continuously reads from the source into the ring buffer
 // until the source is drained, an error occurs, or Close is called.
+// It always marks the stream done on the way out.
 func (bs *BufferedStreamer) readAhead() {
 	// Temporary buffer for reading from source outside the lock.
 	// 512 samples per chunk keeps the critical section short.
@@ -63,6 +117,13 @@ func (bs *BufferedStreamer) readAhead() {
 
 	tmp := make([][2]float64, chunkSize)
 
+	// Every exit marks the stream done.  An exit that does not is what
+	// stranded Stream in its underrun branch, returning silence and ok
+	// for the rest of the process's life.
+	var exitErr error
+
+	defer func() { bs.finish(exitErr) }()
+
 	for {
 		// Check if closed.
 		select {
@@ -72,6 +133,15 @@ func (bs *BufferedStreamer) readAhead() {
 		}
 
 		bs.mu.Lock()
+
+		// Stream gave up waiting for us.  Nothing downstream is
+		// listening any more, so filling the ring is work for nobody.
+		if bs.done {
+			bs.mu.Unlock()
+
+			return
+		}
+
 		space := len(bs.ring) - bs.count
 
 		if space == 0 {
@@ -115,14 +185,12 @@ func (bs *BufferedStreamer) readAhead() {
 		}
 
 		if !ok {
-			bs.mu.Lock()
-			bs.done = true
-
-			if srcErr := bs.source.Err(); srcErr != nil {
-				bs.err = srcErr
-			}
-
-			bs.mu.Unlock()
+			// A drained source and a failed one both land here and are
+			// not the same event: one is a track that ended, the other
+			// is a track that broke.  Err is what tells them apart, and
+			// it is why the player must ask before treating this as a
+			// natural finish.
+			exitErr = bs.source.Err()
 
 			return
 		}
@@ -154,7 +222,27 @@ func (bs *BufferedStreamer) Stream(
 	}
 
 	if bs.count == 0 {
-		// Buffer temporarily empty — fill with silence.
+		// The read-ahead has not caught up.  Silence buys it time --
+		// but only for a bounded stretch, because "forever" is
+		// reported upward as healthy playback and there is no watchdog
+		// above this to notice otherwise.
+		bs.starved++
+
+		if bs.starvedSince.IsZero() {
+			bs.starvedSince = time.Now()
+		}
+
+		if bs.starved >= minStarvedCalls &&
+			time.Since(bs.starvedSince) > maxStarvedDuration {
+			bs.done = true
+
+			if bs.err == nil {
+				bs.err = errSourceStalled
+			}
+
+			return 0, false
+		}
+
 		for i := range samples {
 			samples[i] = [2]float64{}
 		}
@@ -162,6 +250,9 @@ func (bs *BufferedStreamer) Stream(
 		return len(samples), true
 	}
 
+	// Samples arrived, so whatever the stall was, it is over.
+	bs.resetStarvationLocked()
+
 	// Copy available samples from ring buffer.
 	n := len(samples)
 	if n > bs.count {
@@ -197,6 +288,19 @@ func (bs *BufferedStreamer) Flush() {
 	bs.readPos = 0
 	bs.writPos = 0
 	bs.count = 0
+
+	// A seek empties the ring on purpose, and the refill that follows
+	// is exactly the stall the budget exists to tolerate.  Charging it
+	// against a budget the previous underrun already spent would end
+	// the track on a seek near the end of a slow file.
+	bs.resetStarvationLocked()
+}
+
+// resetStarvationLocked forgets an underrun run.  Must be called with
+// bs.mu held.
+func (bs *BufferedStreamer) resetStarvationLocked() {
+	bs.starved = 0
+	bs.starvedSince = time.Time{}
 }
 
 // LockSource blocks the read-ahead goroutine from touching the

backend/player/loadstate_test.go

@@ -0,0 +1,213 @@
+package player
+
+import (
+	"log/slog"
+	"testing"
+	"time"
+
+	"github.com/wailsapp/wails/v3/pkg/application"
+
+	"yellowjacket/backend/events"
+	"yellowjacket/internal/testfixtures"
+)
+
+// fixtureSampleRate is what cmd/gentestdata writes (audio.go).  It is
+// deliberately not the speaker rate, which is what lets these tests
+// tell the decoder's format from the player's default.
+const fixtureSampleRate = 22050
+
+// newTestPlayer is a player with a context and no database, so the
+// track-metadata lookup cannot succeed.
+func newTestPlayer(t *testing.T) *Player {
+	t.Helper()
+
+	p := NewPlayer(slog.Default(), nil)
+	rec := events.NewRecorder()
+
+	_ = p.ServiceStartup(
+		events.WithSink(t.Context(), rec),
+		application.ServiceOptions{},
+	)
+
+	return p
+}
+
+// loadFileLocked needs no speaker: it decodes, builds the chain and
+// registers it paused. speaker.Play on an uninitialised device is
+// what the integration guard elsewhere is about, so these assert on
+// the state the load computed rather than on playback.
+
+// p.format used to be assigned once, in the constructor, to the
+// *speaker's* rate -- so it claimed 44.1 kHz for every file ever
+// loaded. Play()'s replay-after-finish path resamples from it, so a
+// finished track played again was resampled from a rate the decoder
+// never produced: audibly the wrong speed and pitch, and wrong
+// length and position arithmetic with it.
+//
+// The fixtures are 22050 Hz, which is exactly the point -- any of
+// them disagrees with the speaker rate.
+func TestLoadRecordsTheDecodersOwnFormat(t *testing.T) {
+	m := testfixtures.Load(t)
+	path := m.Case(t, testfixtures.CaseCoverDedup)[0]
+
+	p := newTestPlayer(t)
+
+	if got := p.format.SampleRate; got != speakerSampleRate {
+		t.Fatalf(
+			"precondition: a fresh player should hold the speaker "+
+				"rate, got %d",
+			got,
+		)
+	}
+
+	if err := p.LoadFile(path); err != nil {
+		t.Fatalf("LoadFile(%s): %v", path, err)
+	}
+
+	if p.format.SampleRate == speakerSampleRate {
+		t.Fatalf(
+			"p.format still holds the speaker rate (%d) after "+
+				"loading a %d Hz file: the replay path would "+
+				"resample from the wrong rate",
+			speakerSampleRate, fixtureSampleRate,
+		)
+	}
+
+	if got := int(p.format.SampleRate); got != fixtureSampleRate {
+		t.Errorf(
+			"expected the decoder's rate %d, got %d",
+			fixtureSampleRate, got,
+		)
+	}
+}
+
+// trackLengthMs is written only when the database has a row for the
+// file and cleared only by UnloadTrack, so a track with no row used
+// to inherit whatever the last track's duration was -- and every
+// position report is scaled by it, so the whole seek bar was then
+// reporting one track's progress on another track's scale.
+//
+// There is no database here, so the lookup cannot succeed: exactly
+// the case that used to inherit.
+func TestLoadDoesNotInheritThePreviousTracksDuration(t *testing.T) {
+	m := testfixtures.Load(t)
+	path := m.Case(t, testfixtures.CaseCoverDedup)[0]
+
+	p := newTestPlayer(t)
+
+	// Stand in for a previous track whose duration was resolved.
+	p.trackLengthMs = 9_999_000
+
+	if err := p.LoadFile(path); err != nil {
+		t.Fatalf("LoadFile(%s): %v", path, err)
+	}
+
+	if p.trackLengthMs == 9_999_000 {
+		t.Fatal(
+			"the previous track's duration survived the load: every " +
+				"position report for this track would be scaled by it",
+		)
+	}
+}
+
+// A new chain supersedes the old one's pending finished callback.
+// Without this, a callback that queued for p.mu behind a LoadFile
+// woke up and rewound, stopped and auto-advanced the *new* track.
+func TestANewChainSupersedesTheOldFinishedCallback(t *testing.T) {
+	m := testfixtures.Load(t)
+	paths := m.Case(t, testfixtures.CaseCoverDedup)
+
+	if len(paths) < 2 {
+		t.Skip("need two fixture tracks")
+	}
+
+	p := newTestPlayer(t)
+
+	if err := p.LoadFile(paths[0]); err != nil {
+		t.Fatalf("LoadFile(%s): %v", paths[0], err)
+	}
+
+	stale := p.chainID
+
+	if err := p.LoadFile(paths[1]); err != nil {
+		t.Fatalf("LoadFile(%s): %v", paths[1], err)
+	}
+
+	if p.chainID == stale {
+		t.Fatal("loading a second file did not supersede the chain")
+	}
+
+	called := false
+
+	p.SetPlaybackFinishedHandler(func(error) { called = true })
+
+	// The first track's callback, arriving late.
+	p.onPlaybackFinished(stale, nil)
+
+	if called {
+		t.Error(
+			"a superseded chain's callback drove auto-advance: the " +
+				"track that is loaded now would be skipped",
+		)
+	}
+
+	if p.state == Stopped {
+		t.Error(
+			"a superseded chain's callback stopped the current track",
+		)
+	}
+}
+
+// The decoder is read by the read-ahead goroutine and by every
+// position emit, and those used to be guarded by different mutexes:
+// the read by srcMu, the position by the speaker lock, which
+// read-ahead never takes. Under -race this failed on the emit that
+// LoadFile itself makes.
+//
+// It needs the read-ahead goroutine to actually be running, so it
+// keeps asking for the position for long enough to overlap it.
+func TestPositionReadsDoNotRaceTheReadAhead(t *testing.T) {
+	m := testfixtures.Load(t)
+	path := m.Case(t, testfixtures.CaseFLACAlbum)[0]
+
+	p := newTestPlayer(t)
+
+	if err := p.LoadFile(path); err != nil {
+		t.Fatalf("LoadFile(%s): %v", path, err)
+	}
+
+	for range 200 {
+		if _, err := p.CurrentPositionSeconds(); err != nil {
+			t.Fatalf("CurrentPositionSeconds: %v", err)
+		}
+	}
+}
+
+// Seeking emits the landing position, and that emit reads the
+// decoder -- so the source lock the seek holds must be released
+// before it. A reentrant take here is a deadlock, not a failure,
+// which is why this test exists rather than a comment.
+func TestSeekEmitsWithoutDeadlocking(t *testing.T) {
+	m := testfixtures.Load(t)
+	path := m.Case(t, testfixtures.CaseFLACAlbum)[0]
+
+	p := newTestPlayer(t)
+
+	if err := p.LoadFile(path); err != nil {
+		t.Fatalf("LoadFile(%s): %v", path, err)
+	}
+
+	done := make(chan struct{})
+
+	go func() {
+		defer close(done)
+
+		_ = p.Seek(1)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		t.Fatal("Seek deadlocked: the position emit re-took the source lock")
+	}
+}

backend/player/player.go

@@ -52,9 +52,17 @@ type Player struct {
 	control                 *beep.Ctrl
 	volume                  *effects.Volume
 	speakerStreamer         beep.Streamer
-	playbackFinishedHandler func()
+	playbackFinishedHandler func(error)
 	trackChangeID           uint64
-	mediaControls           mediacontrols.Handler
+
+	// chainID identifies the streamer chain currently registered with
+	// the speaker.  updateStreamers bumps it, and the finished
+	// callback carries the value it was registered with, so a callback
+	// that queued for p.mu behind a LoadFile can tell that the player
+	// has moved on and return rather than rewinding somebody else's
+	// track.
+	chainID       uint64
+	mediaControls mediacontrols.Handler
 
 	// duckAmount is the attenuation currently applied on top of the
 	// user's volume, in the same base-2 exponent effects.Volume uses.
@@ -180,11 +188,18 @@ func (p *Player) InitSpeaker() error {
 }
 
 // SetPlaybackFinishedHandler sets a callback invoked when a track
-// finishes naturally. This allows the queue to drive auto-advance
+// stops streaming. This allows the queue to drive auto-advance
 // without circular imports.
 //
+// The error says *why* the track stopped: nil for a track that
+// reached its end, non-nil for one that broke partway through.  Both
+// arrive here because both look identical to the speaker, and only
+// the queue holds the metadata a PlaybackFailed needs -- but they are
+// not the same event, and reporting a decode failure as a natural
+// finish is how a broken file used to auto-advance in silence.
+//
 //wails:ignore // internal wiring, not part of the app's IPC surface.
-func (p *Player) SetPlaybackFinishedHandler(handler func()) {
+func (p *Player) SetPlaybackFinishedHandler(handler func(error)) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
@@ -424,6 +439,19 @@ func (p *Player) updateStreamers(
 	newBaseStreamer beep.StreamSeeker,
 	sr beep.SampleRate,
 ) error {
+	// A new chain supersedes the old one, so any finished callback the
+	// old one still owes is stale from here on.
+	p.chainID++
+
+	// The previous read-ahead goroutine reads the same decoder this
+	// one is about to, under its own srcMu -- two goroutines, two
+	// mutexes, one decoder that is not safe for concurrent use.  The
+	// replay-after-finish path rebuilds from p.seeker without going
+	// through LoadFile, which is where that pair could meet.
+	if p.buffered != nil {
+		p.buffered.Close()
+	}
+
 	// set base streamer
 	p.baseStreamer = newBaseStreamer
 	p.seeker = newBaseStreamer
@@ -474,23 +502,57 @@ func (p *Player) startPaused() {
 	p.control.Paused = true
 	speaker.Unlock()
 
+	// Captured, not read at callback time: by then p.chainID names
+	// whatever is loaded *now*, which is the thing the guard exists to
+	// distinguish this chain from.
+	chainID := p.chainID
+	buffered := p.buffered
+
 	// The beep.Callback runs with the speaker mutex held, so we
 	// dispatch to a goroutine that can safely acquire p.mu.
 	speaker.Play(beep.Seq(
 		p.speakerStreamer,
 		beep.Callback(func() {
-			go p.onPlaybackFinished()
+			// Asked here rather than under p.mu: this is the chain that
+			// just ended, and by the time the goroutine holds the lock
+			// p.buffered may be a different one.
+			var err error
+			if buffered != nil {
+				err = buffered.Err()
+			}
+
+			go p.onPlaybackFinished(chainID, err)
 		}),
 	))
 
 	p.state = Paused
 }
 
-// onPlaybackFinished handles the natural end of a track. It is
-// called on a new goroutine from the beep callback (which holds
-// the speaker lock) so that it can safely acquire p.mu.
-func (p *Player) onPlaybackFinished() {
+// onPlaybackFinished handles a track that stopped streaming, whether
+// it ended or broke. It is called on a new goroutine from the beep
+// callback (which holds the speaker lock) so that it can safely
+// acquire p.mu.
+//
+// chainID names the streamer chain the callback fired for and srcErr
+// says why it stopped.
+func (p *Player) onPlaybackFinished(chainID uint64, srcErr error) {
 	p.mu.Lock()
+
+	// The player has moved on while this callback queued for the lock
+	// -- a user pressing Next during the last second of a track is
+	// enough. Everything below is about the *current* track: rewinding
+	// the decoder, saying playback stopped, asking the queue to
+	// advance. Doing any of it now would do it to the wrong track.
+	if chainID != p.chainID {
+		p.mu.Unlock()
+		p.logger.Debug(
+			"Ignoring finished callback for a superseded chain",
+			"chain", chainID, "current", p.chainID,
+		)
+
+		return
+	}
+
 	p.state = Stopped
 	handler := p.playbackFinishedHandler
 	mc := p.mediaControls
@@ -501,10 +563,11 @@ func (p *Player) onPlaybackFinished() {
 	// the Stopped state anyway, so this only moves the decoder.
 	p.rewindLocked()
 	p.emitPositionLocked()
-	p.mu.Unlock()
 
-	// Emit Wails events outside the lock — these are non-blocking
-	// calls that don't need player state.
+	// Emitted under p.mu, like every other transition in this file.
+	// Outside it, a Play() taking the lock in the gap emits `playing`
+	// first and this stale `stopped` lands last -- leaving the button
+	// showing play over a track that is audibly running.
 	p.emitPlaybackFinished()
 
 	events.Emit(
@@ -513,6 +576,8 @@ func (p *Player) onPlaybackFinished() {
 		map[string]string{"state": string(Stopped)},
 	)
 
+	p.mu.Unlock()
+
 	// Notify media controls outside the lock. The track just
 	// ended so position is 0.
 	if mc != nil {
@@ -521,12 +586,19 @@ func (p *Player) onPlaybackFinished() {
 		)
 	}
 
-	p.logger.Info("Playback finished naturally")
+	if srcErr != nil {
+		p.logger.Error(
+			"Playback stopped: the audio source failed",
+			"err", srcErr,
+		)
+	} else {
+		p.logger.Info("Playback finished naturally")
+	}
 
 	// Notify queue for auto-advance. Called without p.mu held
 	// because it re-enters the player via LoadFile/Play.
 	if handler != nil {
-		handler()
+		handler(srcErr)
 	}
 }
 
@@ -587,6 +659,18 @@ func (p *Player) loadFileLocked(filePath string) error {
 
 	p.currentFile = f
 
+	// The decoder's own format, kept for the paths that rebuild the
+	// chain later: Play()'s replay branch resamples from it, so a
+	// stale rate there plays a finished track back at the wrong speed.
+	p.format = format
+
+	// The previous track's duration must not outlive it.  This is set
+	// again by emitTrackChanged below, but only when the database has
+	// a row for the file -- and every position this player reports is
+	// scaled by it, so inheriting means every report is wrong by the
+	// ratio between two unrelated tracks.
+	p.trackLengthMs = 0
+
 	if err := p.updateStreamers(
 		streamer, format.SampleRate,
 	); err != nil {
@@ -906,6 +990,8 @@ func (p *Player) CurrentPosition() (int, error) {
 		return 0, errNoAudioFileLoaded
 	}
 
+	defer p.lockSourceLocked()()
+
 	speaker.Lock()
 	pos := math.Round(
 		100.0 * float64(p.seeker.Position()) /
@@ -924,6 +1010,28 @@ func (p *Player) Seek(targetSeconds int) error {
 	return p.seekLocked(targetSeconds)
 }
 
+// lockSourceLocked blocks the read-ahead goroutine from touching the
+// decoder and returns the function that releases it, so a caller can
+// `defer p.lockSourceLocked()()`.
+//
+// Reading the decoder's position is a read *of the decoder*, and the
+// speaker lock does not exclude the read-ahead goroutine -- it never
+// takes it.  That was a genuine data race on every position emit,
+// once a second for the whole of playback.
+//
+// srcMu is not reentrant, so nothing that already holds it may call
+// this; seekSourceLocked exists to keep that region free of emits.
+// Must be called with p.mu held.
+func (p *Player) lockSourceLocked() func() {
+	if p.buffered == nil {
+		return func() {}
+	}
+
+	p.buffered.LockSource()
+
+	return p.buffered.UnlockSource
+}
+
 // rewindLocked returns the decoder to the start of the track without
 // touching playback state.  Must be called with p.mu held.
 func (p *Player) rewindLocked() {
@@ -959,6 +1067,46 @@ func (p *Player) seekLocked(targetSeconds int) error {
 		return fmt.Errorf("cannot get track length: %w", err)
 	}
 
+	// The source lock is released before anything below is emitted:
+	// emitPositionLocked reads the decoder's position and takes the
+	// same lock, which is not reentrant.
+	seekErr := p.seekSourceLocked(targetSeconds, lengthSecs)
+	if seekErr != nil {
+		p.logger.Warn(
+			"Seek failed, playback will start from "+
+				"the beginning",
+			"target-seconds", targetSeconds,
+			"err", seekErr,
+		)
+
+		// The optimistic move the UI already made has to be taken
+		// back, and only the backend knows it did not happen.
+		events.Emit(p.ctx, events.SeekFailed)
+		p.emitPositionLocked()
+
+		return fmt.Errorf("failed to seek: %w", seekErr)
+	}
+
+	if p.mediaControls != nil {
+		p.mediaControls.NotifySeek(targetSeconds)
+	}
+
+	// Report the landing position immediately rather than leaving the
+	// UI to guess until the next tick — this is the half of H-3 that
+	// desynced the seek bar by 30 s over four keyboard seeks.
+	p.emitPositionLocked()
+
+	return nil
+}
+
+// seekSourceLocked moves the decoder and flushes the stale read-ahead
+// behind it.  It owns the source lock for exactly that long and
+// emits nothing, so its caller is free to read the position
+// afterwards.  Must be called with p.mu held.
+func (p *Player) seekSourceLocked(
+	targetSeconds int,
+	lengthSecs int,
+) error {
 	// Block the read-ahead goroutine from reading the source while
 	// we seek it. The decoder (e.g. FLAC's bufseekio.ReadSeeker) is
 	// not safe for concurrent Read+Seek, and read-ahead runs on its
@@ -1014,19 +1162,11 @@ func (p *Player) seekLocked(targetSeconds int) error {
 	if seekErr != nil {
 		speaker.Unlock()
 
-		p.logger.Warn(
-			"Seek failed, playback will start from "+
-				"the beginning",
-			"target-seconds", targetSeconds,
-			"samples", samples,
-			"err", seekErr,
+		p.logger.Debug(
+			"seek rejected by the decoder",
+			"samples", samples, "err", seekErr,
 		)
 
-		// The optimistic move the UI already made has to be taken
-		// back, and only the backend knows it did not happen.
-		events.Emit(p.ctx, events.SeekFailed)
-		p.emitPositionLocked()
-
 		return fmt.Errorf("failed to seek: %w", seekErr)
 	}
 
@@ -1039,15 +1179,6 @@ func (p *Player) seekLocked(targetSeconds int) error {
 		p.buffered.Flush()
 	}
 
-	if p.mediaControls != nil {
-		p.mediaControls.NotifySeek(targetSeconds)
-	}
-
-	// Report the landing position immediately rather than leaving the
-	// UI to guess until the next tick — this is the half of H-3 that
-	// desynced the seek bar by 30 s over four keyboard seeks.
-	p.emitPositionLocked()
-
 	return nil
 }
 
@@ -1140,6 +1271,10 @@ func (p *Player) seekerLengthSecsLocked() (int, error) {
 		return 0, errNoAudioFileLoaded
 	}
 
+	// Len is fixed for the life of the decoder, so unlike Position it
+	// races with nothing and needs no source lock -- which it must not
+	// take anyway: displayPositionSecsLocked calls this while holding
+	// it, and srcMu is not reentrant.
 	speaker.Lock()
 	length := p.seeker.Len() / int(p.format.SampleRate)
 	speaker.Unlock()
@@ -1156,6 +1291,8 @@ func (p *Player) displayPositionSecsLocked() int {
 		return 0
 	}
 
+	defer p.lockSourceLocked()()
+
 	speaker.Lock()
 	pos := p.seeker.Position()
 	total := p.seeker.Len()

backend/queue/emit.go

@@ -81,6 +81,7 @@ func (q *Queue) emitTracksModified(
 			Index:        index,
 			Positions:    positions,
 			CurrentIndex: q.currentIndex,
+			Source:       q.source,
 		},
 	)
 }

backend/queue/emit_test.go

@@ -219,6 +219,56 @@ func TestEmit_AddTrackSendsDeltaNotSnapshot(t *testing.T) {
 	}
 }
 
+// The append clears the source, and the delta is the only event those
+// paths emit — so if it does not carry the source, the frontend keeps
+// the label it was last given and goes on offering a link back to an
+// album the queue no longer holds until something forces a full state.
+func TestEmit_AppendDeltaCarriesClearedSource(t *testing.T) {
+	t.Parallel()
+
+	q, db, rec := setupRecordedQueue(t)
+	paths := seedAudioFiles(t, db, 4)
+
+	q.SetQueue(
+		paths[:3], 0, false,
+		Source{Type: "album", ID: 1, Label: "Abbey Road"},
+	)
+
+	if _, ok := rec.Wait(events.QueueChanged, waitFor); !ok {
+		t.Fatalf("no QueueChanged after SetQueue; got %v", rec.Names())
+	}
+
+	rec.Reset()
+	q.AddTrack(paths[3])
+
+	if got := modifiedOf(t, rec).Source; got != (Source{}) {
+		t.Errorf("delta source = %+v, want zero value", got)
+	}
+}
+
+// And a delta that did not clear it still reports the source it has,
+// or the frontend would drop a perfectly good label on every removal.
+func TestEmit_NonAppendDeltaCarriesSource(t *testing.T) {
+	t.Parallel()
+
+	q, db, rec := setupRecordedQueue(t)
+	paths := seedAudioFiles(t, db, 4)
+
+	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
+	q.SetQueue(paths, 0, false, album)
+
+	if _, ok := rec.Wait(events.QueueChanged, waitFor); !ok {
+		t.Fatalf("no QueueChanged after SetQueue; got %v", rec.Names())
+	}
+
+	rec.Reset()
+	q.RemoveTrack(3)
+
+	if got := modifiedOf(t, rec).Source; got != album {
+		t.Errorf("delta source = %+v, want %+v", got, album)
+	}
+}
+
 func TestEmit_RemoveTracksReportsPositions(t *testing.T) {
 	t.Parallel()
 

backend/queue/fallback_test.go

@@ -83,7 +83,7 @@ func TestFallback_TriggersOnNaturalFinish(t *testing.T) {
 	q.SetFallbackSource(fake)
 
 	q.SetQueue(seedPaths, 0, false, Source{Type: "album", ID: 1, Label: "Seed Album"})
-	q.OnPlaybackFinished()
+	q.OnPlaybackFinished(nil)
 
 	waitUntil(t, func() bool { return fake.callCount() == 1 }, "fallback to be resolved")
 	waitUntil(t, func() bool {
@@ -159,7 +159,7 @@ func TestFallback_EmptyResultLeavesQueueExhausted(t *testing.T) {
 	q.SetFallbackSource(fake)
 
 	q.SetQueue(seedPaths, 0, false, Source{})
-	q.OnPlaybackFinished()
+	q.OnPlaybackFinished(nil)
 
 	waitUntil(t, func() bool { return fake.callCount() == 1 }, "fallback to be resolved")
 
@@ -193,7 +193,7 @@ func TestFallback_StaleResolutionDiscarded(t *testing.T) {
 	q.SetFallbackSource(fake)
 
 	q.SetQueue(seedPaths, 0, false, Source{})
-	q.OnPlaybackFinished() // starts resolving, blocked on gate
+	q.OnPlaybackFinished(nil) // starts resolving, blocked on gate
 
 	time.Sleep(20 * time.Millisecond) // let the goroutine reach the gate
 

backend/queue/finished_test.go

@@ -0,0 +1,78 @@
+package queue
+
+import (
+	"errors"
+	"testing"
+
+	"yellowjacket/backend/events"
+)
+
+// errTestDecode stands in for a decoder blowing up mid-track.
+var errTestDecode = errors.New("decode blew up")
+
+// currentIndex == -1 against a non-empty queue is a state this
+// package produces on purpose: onQueueExhausted(false) sets it and
+// deliberately leaves the finished track loaded in the player, so it
+// stays on the now-playing bar. Pressing play from there and letting
+// it finish re-enters OnPlaybackFinished with exactly that pair --
+// which used to index q.tracks[-1] and panic, on a goroutine
+// dispatched from the audio callback with no caller to recover it.
+func TestFinishedWithNoCurrentTrackDoesNotPanic(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		index int
+	}{
+		{"exhausted queue leaves -1", -1},
+		{"index past the end", 3},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			q, _, _ := setupRecordedQueue(t)
+			q.tracks = []Track{
+				{FilePath: "/a.mp3"},
+				{FilePath: "/b.mp3"},
+			}
+			q.currentIndex = tt.index
+
+			// The assertion is that this returns at all.
+			q.OnPlaybackFinished(nil)
+
+			if q.currentIndex != tt.index {
+				t.Errorf(
+					"an out-of-range index was acted on: %d became %d",
+					tt.index, q.currentIndex,
+				)
+			}
+		})
+	}
+}
+
+// A track that broke mid-playback is not a track that was listened
+// to. The player cannot say so itself -- the metadata is here -- so
+// it hands the reason over and this is where it becomes a
+// PlaybackFailed rather than a silent auto-advance.
+func TestAFailedTrackIsReportedAndNotCountedAsAPlay(t *testing.T) {
+	t.Parallel()
+
+	q, _, rec := setupRecordedQueue(t)
+	q.tracks = []Track{
+		{FilePath: "/a.mp3", Title: "A", AudioFileID: 1},
+		{FilePath: "/b.mp3", Title: "B", AudioFileID: 2},
+	}
+	q.currentIndex = 0
+
+	q.OnPlaybackFinished(errTestDecode)
+
+	if _, ok := rec.Last(events.PlaybackFailed); !ok {
+		t.Errorf(
+			"a track that failed mid-playback told the user nothing; "+
+				"got %v",
+			rec.Names(),
+		)
+	}
+}

backend/queue/handlers.go

@@ -1,18 +1,45 @@
 package queue
 
-// OnPlaybackFinished is called when a track finishes playing naturally.
-// This drives the auto-advance behavior and records the play.
-func (q *Queue) OnPlaybackFinished() {
+// OnPlaybackFinished is called when a track stops streaming. This
+// drives the auto-advance behavior and records the play.
+//
+// srcErr says why the track stopped: nil for one that reached its
+// end, non-nil for one that broke partway through.  The player cannot
+// tell the user which, because the metadata lives here -- so a failure
+// is reported as PlaybackFailed and *not* recorded as a play, while
+// the advance happens either way.  Before this, a file that failed
+// mid-track advanced in silence and was counted as listened to.
+//
+//wails:ignore // internal wiring, not part of the app's IPC surface.
+func (q *Queue) OnPlaybackFinished(srcErr error) {
 	q.mu.Lock()
 
-	if len(q.tracks) == 0 {
+	// currentIndex is -1 whenever the queue has been exhausted, and
+	// onQueueExhausted deliberately leaves the finished track loaded
+	// in the player -- so a natural finish can re-enter here against a
+	// queue that is not empty and an index that is not valid.  Every
+	// other path in this package bounds-checks before indexing; this
+	// one panicked, on a goroutine with no caller to recover it.
+	if q.currentIndex < 0 || q.currentIndex >= len(q.tracks) {
 		q.mu.Unlock()
 
 		return
 	}
 
 	// Capture the track that just finished before advancing.
-	finishedID := q.tracks[q.currentIndex].AudioFileID
+	finished := q.tracks[q.currentIndex]
+	finishedID := finished.AudioFileID
+
+	if srcErr != nil {
+		q.emitPlaybackFailed(finished, srcErr)
+	}
+
+	// A track that broke was not listened to.
+	recordFinished := func() {
+		if srcErr == nil {
+			q.recordPlay(finishedID)
+		}
+	}
 
 	// Repeat One: replay the current track.
 	if q.repeatMode == RepeatOne {
@@ -21,7 +48,7 @@ func (q *Queue) OnPlaybackFinished() {
 		}
 
 		q.mu.Unlock()
-		q.recordPlay(finishedID)
+		recordFinished()
 
 		return
 	}
@@ -31,7 +58,7 @@ func (q *Queue) OnPlaybackFinished() {
 		// Queue exhausted — this is the extension point for a future fallback playlist.
 		q.onQueueExhausted(false)
 		q.mu.Unlock()
-		q.recordPlay(finishedID)
+		recordFinished()
 
 		return
 	}
@@ -44,12 +71,12 @@ func (q *Queue) OnPlaybackFinished() {
 	if !q.playCurrentOrSkip(true, q.nextIndex) {
 		q.onQueueExhausted(false)
 		q.mu.Unlock()
-		q.recordPlay(finishedID)
+		recordFinished()
 
 		return
 	}
 
 	q.emitIndexChanged()
 	q.mu.Unlock()
-	q.recordPlay(finishedID)
+	recordFinished()
 }

backend/queue/playbackfailed_test.go

@@ -107,7 +107,7 @@ func TestPlaybackFailed_AutoAdvanceSkipsPastIt(t *testing.T) {
 
 	// The first track finished: auto-advance lands on the missing
 	// file and must step over it rather than stopping dead.
-	q.OnPlaybackFinished()
+	q.OnPlaybackFinished(nil)
 
 	if got := q.GetState().CurrentIndex; got != 2 {
 		t.Errorf("currentIndex after skipping: got %d, want 2", got)
@@ -183,7 +183,7 @@ func TestQueueExhausted_KeepsTheFinishedTrackLoaded(t *testing.T) {
 
 	q.SetQueue(paths, 0, false, Source{})
 	q.Play()
-	q.OnPlaybackFinished()
+	q.OnPlaybackFinished(nil)
 
 	if q.GetState().CurrentIndex != -1 {
 		t.Errorf(

backend/queue/queue.go

@@ -156,12 +156,21 @@ type PlaybackFailure struct {
 }
 
 // TracksModified is the payload for the QueueTracksModified event.
+//
+// Source is carried because an append is exactly what can *invalidate*
+// it: a queue built from one album stops being that album the moment a
+// track from somewhere else is added to it. The delta is the only event
+// those paths emit, so without this the frontend would keep the label
+// it was last given and go on saying "Playing from" an album that is no
+// longer what is queued — an event carrying what its consumer needs, so
+// nothing has to invalidate anything.
 type TracksModified struct {
 	Action       string  `json:"action"`
 	Tracks       []Track `json:"tracks,omitempty"`
 	Index        int     `json:"index"`
 	Positions    []int   `json:"positions,omitempty"`
 	CurrentIndex int     `json:"currentIndex"`
+	Source       Source  `json:"source"`
 }
 
 // Queue manages an ordered list of tracks for playback.
@@ -455,6 +464,8 @@ func (q *Queue) AddTrack(filePath string) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistAddTrack(track)
 	q.persistState()
 	q.emitTracksModified(
@@ -505,6 +516,8 @@ func (q *Queue) AddTracks(filePaths []string) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistAddTracks(newTracks)
 	q.persistState()
 	q.emitTracksModified(
@@ -563,6 +576,8 @@ func (q *Queue) InsertNextTracks(filePaths []string) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistInsertTracks(newTracks, insertPos)
 	q.persistState()
 	q.emitTracksModified(
@@ -613,6 +628,8 @@ func (q *Queue) InsertNext(filePath string) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistInsertTracks([]Track{track}, insertPos)
 	q.persistState()
 	q.emitTracksModified(
@@ -680,6 +697,8 @@ func (q *Queue) InsertTracksAt(filePaths []string, index int) {
 		q.generateShuffleOrder()
 	}
 
+	q.dropSource()
+
 	q.persistInsertTracks(newTracks, index)
 	q.persistState()
 	q.emitTracksModified(
@@ -1537,6 +1556,31 @@ func (q *Queue) reindexPositions() {
 	}
 }
 
+// dropSource forgets which collection the queue was built from.
+//
+// A Source is a claim that everything queued came from one album,
+// playlist, genre or artist, and the frontend renders it as a
+// "Playing from X" link back to that page. Adding or inserting a track
+// makes the claim false — the queue is now that album *plus* something
+// else — so every path that does so calls this.
+//
+// It was set by SetQueue and cleared in exactly one place, Clear, so a
+// label survived every append. It is persisted too (source_type /
+// source_id / source_label on the queue state row), which is what made
+// a wrong label outlive the session that earned it: an album queued on
+// Monday, added to on Tuesday, still offered a link back to that album
+// on Friday.
+//
+// Removing, reordering and shuffling deliberately do not call this. A
+// queue with a track taken out of it, or played in another order, is
+// still that album — the link still goes somewhere true. Only the
+// arrival of a track from elsewhere makes it a lie.
+//
+// The caller must hold q.mu.
+func (q *Queue) dropSource() {
+	q.source = Source{}
+}
+
 // commitMutation persists the current queue state after a mutation.
 // When reindex is true, track positions are renumbered first.
 // The caller must hold q.mu.

backend/queue/queue_test.go

@@ -126,6 +126,117 @@ func TestClear_ResetsSource(t *testing.T) {
 	}
 }
 
+// A queue built from one album stops being that album the moment a
+// track from somewhere else joins it, so every path that adds one
+// drops the source. Before this, SetQueue was the only writer and
+// Clear the only clearer, so "Playing from Abbey Road" outlived every
+// append — and, being persisted, every restart too.
+func TestAppendPathsDropSource(t *testing.T) {
+	t.Parallel()
+
+	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
+
+	tests := []struct {
+		name   string
+		append func(q *Queue, paths []string)
+	}{
+		{
+			name: "AddTrack",
+			append: func(q *Queue, paths []string) {
+				q.AddTrack(paths[5])
+			},
+		},
+		{
+			name: "AddTracks",
+			append: func(q *Queue, paths []string) {
+				q.AddTracks(paths[5:7])
+			},
+		},
+		{
+			name: "InsertNext",
+			append: func(q *Queue, paths []string) {
+				q.InsertNext(paths[5])
+			},
+		},
+		{
+			name: "InsertNextTracks",
+			append: func(q *Queue, paths []string) {
+				q.InsertNextTracks(paths[5:7])
+			},
+		},
+		{
+			name: "InsertTracksAt",
+			append: func(q *Queue, paths []string) {
+				q.InsertTracksAt(paths[5:7], 1)
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			q, db := setupTestQueue(t)
+			paths := seedAudioFiles(t, db, 8)
+
+			q.SetQueue(paths[:5], 0, false, album)
+
+			if got := q.GetState().Source; got != album {
+				t.Fatalf("source before append: got %+v, want %+v", got, album)
+			}
+
+			tt.append(q, paths)
+
+			if got := q.GetState().Source; got != (Source{}) {
+				t.Errorf(
+					"source after %s: got %+v, want zero value",
+					tt.name, got,
+				)
+			}
+		})
+	}
+}
+
+// Removing and reordering deliberately do not drop it: a queue with a
+// track taken out of it is still that album, and the link still goes
+// somewhere true.
+func TestRemoveAndMoveKeepSource(t *testing.T) {
+	t.Parallel()
+
+	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
+
+	t.Run("RemoveTrack", func(t *testing.T) {
+		t.Parallel()
+
+		q, db := setupTestQueue(t)
+		paths := seedAudioFiles(t, db, 5)
+
+		q.SetQueue(paths, 0, false, album)
+		q.RemoveTrack(3)
+
+		if got := q.GetState().Source; got != album {
+			t.Errorf("source after RemoveTrack: got %+v, want %+v", got, album)
+		}
+	})
+
+	t.Run("MoveQueueTracks", func(t *testing.T) {
+		t.Parallel()
+
+		q, db := setupTestQueue(t)
+		paths := seedAudioFiles(t, db, 5)
+
+		q.SetQueue(paths, 0, false, album)
+		q.MoveQueueTracks([]int{0}, 3)
+
+		if got := q.GetState().Source; got != album {
+			t.Errorf(
+				"source after MoveQueueTracks: got %+v, want %+v",
+				got, album,
+			)
+		}
+	})
+}
+
 func TestSetQueue_WithStartIndex(t *testing.T) {
 	t.Parallel()
 

backend/shortcuts/config.go

@@ -24,10 +24,19 @@ func DefaultBindings() map[string]string {
 		"player.repeat":      "R",
 		"player.mute":        "M",
 
-		// Navigation (Global scope)
+		// Navigation (Global scope).  Back and forward are the browser's
+		// own combination on every platform, which is the whole design
+		// brief for them: the app has one global history and this is the
+		// gesture people already have for it.  The modifier is what keeps
+		// them clear of `player.seekBack`/`seekForward`, which are the
+		// bare arrows -- a binding is matched on its full canonical
+		// string, so "Alt+Left" and "Left" are different keys and not a
+		// conflict.
 		"nav.search":    "/",
 		"nav.searchAlt": "Ctrl+F",
 		"nav.queue":     "Q",
+		"nav.back":      "Alt+Left",
+		"nav.forward":   "Alt+Right",
 
 		// App actions
 		"app.selectAll": "Ctrl+A",

backend/smartplaylist/smartplaylist.go

@@ -28,6 +28,7 @@ var (
 	errUnsupportedOp    = errors.New("unsupported operator")
 	errInvalidSortField = errors.New("invalid sort field: not in allowed field list")
 	errNotNumeric       = errors.New("value must be numeric")
+	errInvalidMatch     = errors.New("match must be \"all\" or \"any\"")
 )
 
 // Rule represents a single filter condition for a smart playlist.
@@ -37,13 +38,45 @@ type Rule struct {
 	Value    string `json:"value"`
 }
 
+// MatchType decides how a rule set's conditions combine.
+//
+// The rules used to be joined with " AND " and nothing else, so a
+// playlist could only ever narrow: "jazz released after 1960" was
+// expressible and "jazz or blues" was not, which is most of what
+// anyone reaches for a second rule to say.
+type MatchType string
+
+const (
+	// MatchAll requires every rule to hold — the historical behaviour,
+	// and what an empty match means so that every rule set written
+	// before this existed keeps the meaning it was saved with.
+	MatchAll MatchType = "all"
+	// MatchAny requires at least one rule to hold.
+	MatchAny MatchType = "any"
+)
+
+// joiner returns the SQL keyword that combines two conditions.
+// An unrecognised value cannot reach here — ParseRuleSet rejects one
+// — so the default is about the empty string, which is every rule set
+// saved before this field existed.
+func (m MatchType) joiner() string {
+	if m == MatchAny {
+		return " OR "
+	}
+
+	return " AND "
+}
+
 // RuleSet holds the complete filter configuration for a smart
 // playlist, including optional sort and limit.
 type RuleSet struct {
-	Rules     []Rule `json:"rules"`
-	Limit     int    `json:"limit,omitempty"`
-	SortField string `json:"sort_field,omitempty"`
-	SortDir   string `json:"sort_dir,omitempty"`
+	Rules []Rule `json:"rules"`
+	// Match is "all" or "any"; empty means "all". It is omitempty so
+	// an untouched playlist's stored JSON does not change shape.
+	Match     MatchType `json:"match,omitempty"`
+	Limit     int       `json:"limit,omitempty"`
+	SortField string    `json:"sort_field,omitempty"`
+	SortDir   string    `json:"sort_dir,omitempty"`
 }
 
 // fieldMap maps user-facing rule field names to track_metadata column
@@ -116,7 +149,12 @@ const genreDelimiter = "||"
 // slice of rules. It is a pure function — no database access needed.
 // Returns the clause (without the leading "WHERE"), the parameter
 // args, and any validation error.
-func BuildWhereClause(rules []Rule) (string, []any, error) {
+//
+// match decides how the conditions combine; an empty match is MatchAll,
+// which is what every rule set saved before the field existed means.
+func BuildWhereClause(
+	rules []Rule, match MatchType,
+) (string, []any, error) {
 	if len(rules) == 0 {
 		return "", nil, nil
 	}
@@ -179,7 +217,28 @@ func BuildWhereClause(rules []Rule) (string, []any, error) {
 		args = append(args, condArgs...)
 	}
 
-	return strings.Join(conditions, " AND "), args, nil
+	// Under OR, each condition is parenthesised; under AND it is not.
+	//
+	// The asymmetry is deliberate rather than an omission. AND is the
+	// tighter operator in SQL, so an OR-join has to protect any
+	// condition that contains a top-level AND of its own or the halves
+	// come apart: `days_since_played less_than` is
+	// `last_played IS NOT NULL AND <expr> < ?`, which read without
+	// brackets under an OR-join happens to still parse correctly and
+	// would stop doing so the moment a condition grows a top-level OR.
+	// Bracketing under AND would be a no-op semantically and would
+	// rewrite the clause every existing test pins, so the brackets go
+	// exactly where they change something.
+	if match == MatchAny {
+		bracketed := make([]string, len(conditions))
+		for i, cond := range conditions {
+			bracketed[i] = "(" + cond + ")"
+		}
+
+		conditions = bracketed
+	}
+
+	return strings.Join(conditions, match.joiner()), args, nil
 }
 
 // validateOperator checks that the operator is valid for the field
@@ -599,7 +658,7 @@ func Evaluate(
 	start := time.Now()
 	logger := db.Logger()
 
-	where, args, err := BuildWhereClause(ruleSet.Rules)
+	where, args, err := BuildWhereClause(ruleSet.Rules, ruleSet.Match)
 	if err != nil {
 		return nil, fmt.Errorf(
 			"smart playlist rule error: %w", err,
@@ -1036,6 +1095,16 @@ func ParseRuleSet(jsonStr string) (RuleSet, error) {
 		)
 	}
 
+	// A match nobody recognises would otherwise fall through to AND,
+	// which is a playlist quietly returning the wrong tracks rather
+	// than refusing to be saved. This is the only place a rule set
+	// enters the backend, so it is the only place that has to ask.
+	if rs.Match != "" && rs.Match != MatchAll && rs.Match != MatchAny {
+		return RuleSet{}, fmt.Errorf(
+			"%w: %q", errInvalidMatch, rs.Match,
+		)
+	}
+
 	return rs, nil
 }
 

backend/smartplaylist/smartplaylist_test.go

@@ -1,6 +1,7 @@
 package smartplaylist
 
 import (
+	"errors"
 	"strings"
 	"testing"
 
@@ -170,7 +171,7 @@ func TestBuildWhereClause_TextIs(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -189,7 +190,7 @@ func TestBuildWhereClause_TextIsNot(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is_not", Value: "Queen"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -209,7 +210,7 @@ func TestBuildWhereClause_TextContains(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "contains", Value: "Black"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -231,7 +232,7 @@ func TestBuildWhereClause_TextDoesNotContain(t *testing.T) {
 			Field: "title", Operator: "does_not_contain",
 			Value: "Black",
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -251,7 +252,7 @@ func TestBuildWhereClause_TextStartsWith(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "starts_with", Value: "Back"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -270,7 +271,7 @@ func TestBuildWhereClause_TextEndsWith(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "ends_with", Value: "Black"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -292,7 +293,7 @@ func TestBuildWhereClause_TextIsAnyOf(t *testing.T) {
 			Field: "artist", Operator: "is_any_of",
 			Value: `["Queen","AC/DC"]`,
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -312,7 +313,7 @@ func TestBuildWhereClause_NumericIs(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "is", Value: "1980"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -331,7 +332,7 @@ func TestBuildWhereClause_NumericIsNot(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "is_not", Value: "1980"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -350,7 +351,7 @@ func TestBuildWhereClause_NumericGreaterThan(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "greater_than", Value: "2000"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -369,7 +370,7 @@ func TestBuildWhereClause_NumericLessThan(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "less_than", Value: "1980"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -391,7 +392,7 @@ func TestBuildWhereClause_NumericBetween(t *testing.T) {
 			Field: "year", Operator: "between",
 			Value: "1975,1985",
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -414,7 +415,7 @@ func TestBuildWhereClause_NumericBetweenJSON(t *testing.T) {
 			Field: "year", Operator: "between",
 			Value: `["1975","1985"]`,
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -434,7 +435,7 @@ func TestBuildWhereClause_GenreIsProducesSubquery(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "is", Value: "Rock"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -466,7 +467,7 @@ func TestBuildWhereClause_GenreIsNotProducesSubquery(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "is_not", Value: "Rock"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -495,7 +496,7 @@ func TestBuildWhereClause_GenreIsAnyOfProducesSubquery(t *testing.T) {
 			Field: "genre", Operator: "is_any_of",
 			Value: `["Rock","Pop"]`,
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -524,7 +525,7 @@ func TestBuildWhereClause_GenreContainsUsesSubquery(t *testing.T) {
 
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "contains", Value: "Rock"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -557,7 +558,7 @@ func TestBuildWhereClause_MultipleRulesAND(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
 		{Field: "year", Operator: "greater_than", Value: "1975"},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -572,6 +573,110 @@ func TestBuildWhereClause_MultipleRulesAND(t *testing.T) {
 	}
 }
 
+func TestBuildWhereClause_MultipleRulesOR(t *testing.T) {
+	t.Parallel()
+
+	clause, args, err := BuildWhereClause([]Rule{
+		{Field: "artist", Operator: "is", Value: "Queen"},
+		{Field: "year", Operator: "greater_than", Value: "1975"},
+	}, MatchAny)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	want := "(artist_name = ? COLLATE NOCASE) OR (year > ?)"
+	if clause != want {
+		t.Errorf("clause = %q, want %q", clause, want)
+	}
+
+	if len(args) != 2 || args[0] != "Queen" || args[1] != int64(1975) {
+		t.Errorf("args = %v, want [Queen 1975]", args)
+	}
+}
+
+// An empty match is what every rule set saved before the field existed
+// carries, and it has to keep meaning AND — a playlist silently
+// widening to OR on upgrade is the whole risk of adding this field.
+func TestBuildWhereClause_EmptyMatchIsAll(t *testing.T) {
+	t.Parallel()
+
+	rules := []Rule{
+		{Field: "artist", Operator: "is", Value: "Queen"},
+		{Field: "year", Operator: "greater_than", Value: "1975"},
+	}
+
+	empty, _, err := BuildWhereClause(rules, "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	all, _, err := BuildWhereClause(rules, MatchAll)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if empty != all {
+		t.Errorf("empty match = %q, want the same as MatchAll %q",
+			empty, all)
+	}
+}
+
+// A condition carrying its own top-level AND is what makes the
+// bracketing under OR load-bearing: `days_since_played less_than`
+// is two predicates, and both belong to the same rule.
+func TestBuildWhereClause_ORBracketsCompoundCondition(t *testing.T) {
+	t.Parallel()
+
+	clause, _, err := BuildWhereClause([]Rule{
+		{Field: "artist", Operator: "is", Value: "Queen"},
+		{
+			Field:    "days_since_played",
+			Operator: "less_than",
+			Value:    "30",
+		},
+	}, MatchAny)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if !strings.Contains(clause, "(last_played IS NOT NULL AND") {
+		t.Errorf(
+			"compound condition is not bracketed under OR: %q",
+			clause,
+		)
+	}
+}
+
+func TestParseRuleSet_RejectsUnknownMatch(t *testing.T) {
+	t.Parallel()
+
+	_, err := ParseRuleSet(`{"rules":[],"match":"either"}`)
+	if err == nil {
+		t.Fatal("expected an error for an unknown match type")
+	}
+
+	if !errors.Is(err, errInvalidMatch) {
+		t.Errorf("err = %v, want errInvalidMatch", err)
+	}
+}
+
+func TestParseRuleSet_AcceptsAnyAndAll(t *testing.T) {
+	t.Parallel()
+
+	for _, want := range []MatchType{MatchAll, MatchAny} {
+		rs, err := ParseRuleSet(
+			`{"rules":[],"match":"` + string(want) + `"}`,
+		)
+		if err != nil {
+			t.Fatalf("match %q: unexpected error: %v", want, err)
+		}
+
+		if rs.Match != want {
+			t.Errorf("match = %q, want %q", rs.Match, want)
+		}
+	}
+}
+
 func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 	t.Parallel()
 
@@ -581,7 +686,7 @@ func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 			Field: "genre", Operator: "does_not_contain",
 			Value: "Punk",
 		},
-	})
+	}, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -609,7 +714,7 @@ func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 func TestBuildWhereClause_EmptyRules(t *testing.T) {
 	t.Parallel()
 
-	clause, args, err := BuildWhereClause(nil)
+	clause, args, err := BuildWhereClause(nil, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -631,7 +736,7 @@ func TestBuildWhereClause_InvalidField(t *testing.T) {
 			Field: "nonexistent", Operator: "is",
 			Value: "anything",
 		},
-	})
+	}, MatchAll)
 	if err == nil {
 		t.Fatal("expected error for invalid field, got nil")
 	}
@@ -654,7 +759,7 @@ func TestBuildWhereClause_InvalidOperatorForNumeric(t *testing.T) {
 
 	_, _, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "contains", Value: "1980"},
-	})
+	}, MatchAll)
 	if err == nil {
 		t.Fatal(
 			"expected error for text operator on numeric field",
@@ -676,7 +781,7 @@ func TestBuildWhereClause_InvalidOperatorForText(t *testing.T) {
 			Field: "artist", Operator: "greater_than",
 			Value: "Queen",
 		},
-	})
+	}, MatchAll)
 	if err == nil {
 		t.Fatal(
 			"expected error for numeric operator on text field",
@@ -723,6 +828,80 @@ func TestEvaluate_TextIs(t *testing.T) {
 	}
 }
 
+// Two rules that share no track at all: under AND this is empty, and
+// under OR it is the union. Before Match existed only the first was
+// expressible, so a playlist could only ever narrow — "jazz or blues"
+// had no way to be said.
+func TestEvaluate_MatchAnyUnionsWhereMatchAllIntersects(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	seedSmartPlaylistData(t, db)
+
+	// Queen has two tracks; Beyoncé has one; no track is by both.
+	rules := []Rule{
+		{Field: "artist", Operator: "is", Value: "Queen"},
+		{Field: "artist", Operator: "is", Value: "Beyoncé"},
+	}
+
+	all, err := Evaluate(db, RuleSet{Rules: rules, Match: MatchAll})
+	if err != nil {
+		t.Fatalf("Evaluate(all): %v", err)
+	}
+
+	if len(all) != 0 {
+		t.Errorf("match=all returned %d tracks, want 0", len(all))
+	}
+
+	either, err := Evaluate(db, RuleSet{Rules: rules, Match: MatchAny})
+	if err != nil {
+		t.Fatalf("Evaluate(any): %v", err)
+	}
+
+	if len(either) != 3 {
+		t.Fatalf("match=any returned %d tracks, want 3", len(either))
+	}
+
+	for _, tr := range either {
+		if tr.ArtistName != "Queen" && tr.ArtistName != "Beyoncé" {
+			t.Errorf(
+				"track %q has artist %q, want Queen or Beyoncé",
+				tr.TrackName, tr.ArtistName,
+			)
+		}
+	}
+}
+
+// An empty match is what every playlist saved before the field existed
+// carries, and it has to keep meaning AND all the way through Evaluate
+// — a stored playlist silently widening on upgrade is the only real
+// risk in adding this.
+func TestEvaluate_EmptyMatchStillIntersects(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	seedSmartPlaylistData(t, db)
+
+	tracks, err := Evaluate(db, RuleSet{
+		Rules: []Rule{
+			{Field: "artist", Operator: "is", Value: "Queen"},
+			{Field: "year", Operator: "greater_than", Value: "1979"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("Evaluate: %v", err)
+	}
+
+	// Only "Another One Bites the Dust" (Queen, 1980) satisfies both.
+	if len(tracks) != 1 {
+		t.Fatalf("got %d tracks, want 1", len(tracks))
+	}
+
+	if want := "Another One Bites the Dust"; tracks[0].TrackName != want {
+		t.Errorf("got %q, want %q", tracks[0].TrackName, want)
+	}
+}
+
 // TestEvaluate_ArtworkEnrichment verifies the presentation-only
 // cover-art and MusicBrainz-ID fields are attached to matched tracks
 // by the batched fetchArtwork pass (they are no longer part of the
@@ -1340,7 +1519,7 @@ func TestSQLInjection_FieldName(t *testing.T) {
 			Field:    "title; DROP TABLE playlists",
 			Operator: "is", Value: "x",
 		},
-	})
+	}, MatchAll)
 	if err == nil {
 		t.Fatal(
 			"expected error for injected field name, got nil",

backend/system/disktype_linux.go

@@ -16,32 +16,107 @@ var errNoBlockDevice = errors.New(
 	"no matching block device found",
 )
 
-// IsRotationalDisk reports whether the block device backing the
-// given path is a rotational (spinning) disk.  Detection uses the
-// Linux sysfs interface at /sys/block/<dev>/queue/rotational.
-// Returns false on any error (assumes SSD).
-func IsRotationalDisk(path string) bool {
-	dev, err := deviceForPath(path)
-	if err != nil {
-		return false
-	}
+// DiskProfile is what the scanner needs to know about the device a
+// library sits on.  Both fields are about the same question — how many
+// reads should be in flight at once — and they answer different halves
+// of it, so they travel together rather than as two probes.
+type DiskProfile struct {
+	// Device is the whole-disk kernel name ("sdb"), or "" when the
+	// path could not be resolved to one.
+	Device string
 
-	rotational, err := os.ReadFile(
-		filepath.Join(
-			"/sys/block", dev, "queue", "rotational",
-		),
-	)
-	if err != nil {
-		return false
-	}
+	// Rotational is /sys/block/<dev>/queue/rotational: true for a
+	// spinning disk, where a seek costs milliseconds.
+	Rotational bool
 
-	return strings.TrimSpace(string(rotational)) == "1"
+	// QueueDepth is /sys/block/<dev>/device/queue_depth — how many
+	// commands the drive will accept and reorder at once.  This is
+	// NCQ: a SATA disk with it enabled reports 31 or 32, and one
+	// without reports 1.  Zero means the file was not there to read,
+	// which is the case for anything that is not a SCSI/SATA device
+	// (NVMe, MMC, device-mapper, loop, a VM's virtio disk).
+	//
+	// It is the difference between concurrency helping and hurting.
+	// With queueing, several outstanding reads let the drive service
+	// them in the order its head passes over them, which is most of
+	// why a parallel scan is faster at all.  Without it, every extra
+	// worker is one more seek competing for one head, and the scan
+	// gets slower the harder it is pushed.
+	QueueDepth int
 }
 
-// deviceForPath resolves a filesystem path to its underlying block
-// device name (e.g. "sda") by matching the device major:minor
-// from stat(2) against /sys/block/ entries.
-func deviceForPath(path string) (string, error) {
+// Queues reports whether the drive can reorder outstanding commands.
+//
+// An unknown depth (0) counts as queueing: everything that does not
+// publish this file is a device where concurrency is fine — NVMe has
+// its own queues, virtio and device-mapper are not the physical layer
+// at all.  The only case worth being careful about is the one that
+// says so explicitly.
+func (p DiskProfile) Queues() bool {
+	return p.QueueDepth != 1
+}
+
+// IsRotationalDisk reports whether the block device backing the
+// given path is a rotational (spinning) disk.  Returns false on any
+// error (assumes SSD).
+func IsRotationalDisk(path string) bool {
+	return ProfileForPath(path).Rotational
+}
+
+// ProfileForPath describes the device backing a filesystem path.  A
+// path that cannot be resolved yields the zero profile, which reads as
+// "not rotational, queueing" — the permissive answer, since assuming a
+// spinning disk on an SSD would halve a scan for nothing.
+func ProfileForPath(path string) DiskProfile {
+	dev, err := diskForPath(path)
+	if err != nil {
+		return DiskProfile{}
+	}
+
+	return DiskProfile{
+		Device:     dev,
+		Rotational: sysfsInt(dev, "queue", "rotational") == 1,
+		QueueDepth: sysfsInt(dev, "device", "queue_depth"),
+	}
+}
+
+// sysfsInt reads one small integer out of /sys/block/<dev>/<parts...>,
+// returning 0 when it is absent or unparseable.  Every attribute here
+// is optional: sysfs layout varies by driver, and a missing file is
+// "this device does not say", never an error worth propagating.
+func sysfsInt(dev string, parts ...string) int {
+	p := filepath.Join(
+		append([]string{"/sys/block", dev}, parts...)...,
+	)
+
+	data, err := os.ReadFile(p) //nolint:gosec // sysfs, name from the kernel
+	if err != nil {
+		return 0
+	}
+
+	n, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	if err != nil {
+		return 0
+	}
+
+	return n
+}
+
+// diskForPath resolves a filesystem path to the *whole disk* backing
+// it — "sdb" for a file on "sdb3".
+//
+// It goes through /sys/dev/block/<major>:<minor>, which the kernel
+// maintains as a symlink to the device's own sysfs directory, and then
+// walks up to the parent when that directory turns out to be a
+// partition.  The previous implementation scanned /sys/block comparing
+// dev numbers and, failing an exact match, took the first entry whose
+// *major* agreed — and every SATA disk shares major 8.  So a library on
+// /dev/sdb3 resolved to whatever /sys/block listed first, which is
+// alphabetical, which is sda.  On the machine this was found on that
+// meant a 6 TB spinning disk was read as the SSD next to it and scanned
+// with one worker per core.  Matching on major alone cannot be right
+// whenever a machine has two disks, which is the case this exists for.
+func diskForPath(path string) (string, error) {
 	var st syscall.Stat_t
 	if err := syscall.Stat(path, &st); err != nil {
 		return "", fmt.Errorf(
@@ -49,48 +124,50 @@ func deviceForPath(path string) (string, error) {
 		)
 	}
 
-	// Extract major and minor device numbers.
-	major := (st.Dev >> 8) & 0xff
-	minor := st.Dev & 0xff
+	// Linux packs dev_t as 12 bits of major and 20 of minor, split
+	// across the word.  Masking the low byte of each — which is what
+	// this used to do — is right only for the first 256 of either.
+	major := unixMajor(uint64(st.Dev))
+	minor := unixMinor(uint64(st.Dev))
 
-	// Scan /sys/block/ for a matching device.
-	entries, err := os.ReadDir("/sys/block")
+	link := filepath.Join(
+		"/sys/dev/block",
+		strconv.FormatUint(major, 10)+":"+
+			strconv.FormatUint(minor, 10),
+	)
+
+	target, err := filepath.EvalSymlinks(link)
 	if err != nil {
 		return "", fmt.Errorf(
-			"could not read /sys/block: %w", err,
+			"%w: %s (%w)", errNoBlockDevice, link, err,
 		)
 	}
 
-	majorStr := strconv.FormatUint(major, 10)
-	devStr := majorStr + ":" +
-		strconv.FormatUint(minor, 10)
+	// A partition's directory sits inside its disk's, and only the
+	// disk carries `queue`. Climb at most one level: sysfs nests a
+	// partition exactly one deep under its disk.
+	name := filepath.Base(target)
 
-	for _, entry := range entries {
-		devFile := filepath.Join(
-			"/sys/block", entry.Name(), "dev",
-		)
-
-		data, err := os.ReadFile(devFile)
-		if err != nil {
-			continue
-		}
-
-		content := strings.TrimSpace(string(data))
-
-		if content == devStr {
-			return entry.Name(), nil
-		}
-
-		// The filesystem might be on a partition (e.g. sda1)
-		// whose parent block device is sda.  Check if the
-		// major number matches.
-		parts := strings.SplitN(content, ":", 2)
-		if len(parts) == 2 && parts[0] == majorStr {
-			return entry.Name(), nil
-		}
+	if _, err := os.Stat(filepath.Join(target, "queue")); err != nil {
+		name = filepath.Base(filepath.Dir(target))
 	}
 
-	return "", fmt.Errorf(
-		"%w for %s", errNoBlockDevice, devStr,
-	)
+	if name == "" || name == "." || name == string(filepath.Separator) {
+		return "", fmt.Errorf(
+			"%w for %d:%d", errNoBlockDevice, major, minor,
+		)
+	}
+
+	return name, nil
+}
+
+// unixMajor and unixMinor decode a Linux dev_t.  Spelled out rather
+// than taken from golang.org/x/sys/unix so this file stays readable
+// beside the encoding it is undoing.
+func unixMajor(dev uint64) uint64 {
+	return (dev>>8)&0xfff | (dev >> 32 & ^uint64(0xfff))
+}
+
+func unixMinor(dev uint64) uint64 {
+	return dev&0xff | (dev >> 12 & ^uint64(0xff))
 }

backend/system/disktype_other.go

@@ -2,9 +2,34 @@
 
 package system
 
+// DiskProfile is what the scanner needs to know about the device a
+// library sits on.  See the Linux implementation for what each field
+// means; off Linux nothing fills them, because neither macOS nor
+// Windows publishes an equivalent of sysfs's `rotational` and
+// `queue_depth` without going through platform APIs this package
+// deliberately does not link.
+type DiskProfile struct {
+	Device     string
+	Rotational bool
+	QueueDepth int
+}
+
+// Queues reports whether the drive can reorder outstanding commands.
+// Always true here: an unknown depth is the permissive answer, and
+// assuming otherwise would halve every scan on every Mac.
+func (p DiskProfile) Queues() bool {
+	return p.QueueDepth != 1
+}
+
 // IsRotationalDisk reports whether the block device backing the
 // given path is a rotational (spinning) disk.  On non-Linux
 // platforms this always returns false (assumes SSD).
 func IsRotationalDisk(_ string) bool {
 	return false
 }
+
+// ProfileForPath describes the device backing a filesystem path.  Off
+// Linux that is the zero profile, which reads as "an SSD that queues".
+func ProfileForPath(_ string) DiskProfile {
+	return DiskProfile{}
+}

backend/tagtotals/tagtotals.go

@@ -0,0 +1,56 @@
+// Package tagtotals derives the totals a tag's "5/12" form declares.
+//
+// It exists because the two writers that know a release's full
+// tracklist -- the autotag apply pass and the download importer --
+// must not import each other or the tag writer, and because getting
+// the denominator wrong is invisible: a total that is too large marks
+// a complete album incomplete forever, and nothing fails.
+package tagtotals
+
+// Position is one track's place in a release.  A zero Disc means the
+// release did not say, which is disc 1.
+type Position struct {
+	Disc  int
+	Track int
+}
+
+// For returns the totals to write on a file sitting on disc `disc`:
+// how many tracks that disc has, and how many discs the release has.
+//
+// The track total is **per disc** and not the release's track count,
+// because that is what the tag form means and what
+// GetAlbumCompleteness sums -- summing a release total once per disc
+// would multiply a two-disc album's expectation by two.
+//
+// Tracks are counted by distinct position rather than by row: a
+// tracklist that lists a position twice is a defect in the source, and
+// counting it twice would put an album permanently out of reach of its
+// own total.
+func For(all []Position, disc int) (tracks, discs int) {
+	disc = normaliseDisc(disc)
+
+	seenTracks := make(map[int]struct{}, len(all))
+	seenDiscs := make(map[int]struct{}, 1)
+
+	for _, p := range all {
+		d := normaliseDisc(p.Disc)
+		seenDiscs[d] = struct{}{}
+
+		if d != disc || p.Track <= 0 {
+			continue
+		}
+
+		seenTracks[p.Track] = struct{}{}
+	}
+
+	return len(seenTracks), len(seenDiscs)
+}
+
+// normaliseDisc treats an undeclared disc as disc 1.
+func normaliseDisc(d int) int {
+	if d <= 0 {
+		return 1
+	}
+
+	return d
+}

backend/tagtotals/tagtotals_test.go

@@ -0,0 +1,92 @@
+package tagtotals_test
+
+import (
+	"testing"
+
+	"yellowjacket/backend/tagtotals"
+)
+
+func TestFor(t *testing.T) {
+	t.Parallel()
+
+	singleDisc := []tagtotals.Position{
+		{Disc: 0, Track: 1}, {Disc: 0, Track: 2}, {Disc: 0, Track: 3},
+	}
+
+	twoDiscs := []tagtotals.Position{
+		{Disc: 1, Track: 1},
+		{Disc: 1, Track: 2},
+		{Disc: 2, Track: 1},
+		{Disc: 2, Track: 2},
+		{Disc: 2, Track: 3},
+	}
+
+	tests := []struct {
+		name       string
+		all        []tagtotals.Position
+		disc       int
+		wantTracks int
+		wantDiscs  int
+	}{
+		{
+			name: "a single-disc release totals its own tracks",
+			all:  singleDisc, disc: 0, wantTracks: 3, wantDiscs: 1,
+		},
+		{
+			// An undeclared disc is disc 1, on both sides of the
+			// question -- a file tagged "disc 1" and a tracklist that
+			// declares no disc describe the same disc.
+			name: "an undeclared disc is disc 1",
+			all:  singleDisc, disc: 1, wantTracks: 3, wantDiscs: 1,
+		},
+		{
+			// The whole point: 5 here would be the release's track
+			// count, which summed once per disc claims a ten-track
+			// expectation for a five-track album.
+			name: "a multi-disc release totals the file's own disc",
+			all:  twoDiscs, disc: 2, wantTracks: 3, wantDiscs: 2,
+		},
+		{
+			name: "the other disc gets its own total",
+			all:  twoDiscs, disc: 1, wantTracks: 2, wantDiscs: 2,
+		},
+		{
+			// A disc the tracklist does not mention cannot be totalled,
+			// and 0 is how the caller is told to write nothing.
+			name: "a disc with no tracks totals nothing",
+			all:  twoDiscs, disc: 3, wantTracks: 0, wantDiscs: 2,
+		},
+		{
+			name: "an empty tracklist totals nothing",
+			all:  nil, disc: 1, wantTracks: 0, wantDiscs: 0,
+		},
+		{
+			// A source that lists a position twice would otherwise put
+			// the album permanently one track short of its own total.
+			name: "a repeated position counts once",
+			all: []tagtotals.Position{
+				{Disc: 1, Track: 1}, {Disc: 1, Track: 1}, {Disc: 1, Track: 2},
+			},
+			disc: 1, wantTracks: 2, wantDiscs: 1,
+		},
+		{
+			name: "a track with no position is not counted",
+			all: []tagtotals.Position{
+				{Disc: 1, Track: 0}, {Disc: 1, Track: 1},
+			},
+			disc: 1, wantTracks: 1, wantDiscs: 1,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			tracks, discs := tagtotals.For(tc.all, tc.disc)
+			if tracks != tc.wantTracks || discs != tc.wantDiscs {
+				t.Errorf("For(%v, %d) = (%d, %d), want (%d, %d)",
+					tc.all, tc.disc, tracks, discs, tc.wantTracks, tc.wantDiscs)
+			}
+		})
+	}
+}

backend/tagwriter/dbsync.go

@@ -183,6 +183,15 @@ func syncDatabase(
 		discNum = toNullInt64(v)
 	}
 
+	// The completeness evidence.  Without this the row keeps whatever
+	// the last scan read while the file on disk now declares a total,
+	// so the album stays "unknown" until a full rescan -- which is the
+	// state the report describes.
+	totalTracks := old.TotalTracks
+	if v, ok := asInt(params.changes[FieldTotalTracks]); ok {
+		totalTracks = toNullInt64(v)
+	}
+
 	composer := old.Composer
 	if v, ok := params.changes[FieldComposer].(string); ok {
 		composer = v
@@ -207,7 +216,7 @@ func syncDatabase(
 		AlbumID:            albumID,
 		TrackNumber:        trackNum,
 		DiscNumber:         discNum,
-		TotalTracks:        old.TotalTracks,
+		TotalTracks:        totalTracks,
 		Year:               year,
 		Composer:           composer,
 		Comment:            old.Comment,

backend/tagwriter/flac.go

@@ -101,6 +101,11 @@ func applyFlacTextChanges(cmt *flacvorbis.MetaDataBlockVorbisComment, changes Ta
 		{FieldYear, flacvorbis.FIELD_DATE, true},
 		{FieldTrackNumber, flacvorbis.FIELD_TRACKNUMBER, true},
 		{FieldDiscNumber, "DISCNUMBER", true},
+		// TRACKTOTAL/DISCTOTAL and no other spelling: dhowden/tag's
+		// Vorbis reader looks at exactly these two keys, so TOTALTRACKS
+		// or a "1/12" inside TRACKNUMBER reads back as no total at all.
+		{FieldTotalTracks, "TRACKTOTAL", true},
+		{FieldTotalDiscs, "DISCTOTAL", true},
 		{FieldComposer, "COMPOSER", false},
 	}
 

backend/tagwriter/mp3.go

@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"os"
 	"strconv"
+	"strings"
 
 	id3v2 "github.com/bogem/id3v2/v2"
 
@@ -66,17 +67,10 @@ func applyTextChanges(tag *id3v2.Tag, changes TagChanges) {
 		tag.SetYear(strconv.Itoa(v))
 	}
 
-	if v, ok := asInt(changes[FieldTrackNumber]); ok {
-		trckID := tag.CommonID("Track number/Position in set")
-		tag.DeleteFrames(trckID)
-		tag.AddTextFrame(trckID, id3v2.EncodingUTF8, strconv.Itoa(v))
-	}
-
-	if v, ok := asInt(changes[FieldDiscNumber]); ok {
-		tposID := tag.CommonID("Part of a set")
-		tag.DeleteFrames(tposID)
-		tag.AddTextFrame(tposID, id3v2.EncodingUTF8, strconv.Itoa(v))
-	}
+	applyPositionFrame(tag, "Track number/Position in set", changes,
+		FieldTrackNumber, FieldTotalTracks)
+	applyPositionFrame(tag, "Part of a set", changes,
+		FieldDiscNumber, FieldTotalDiscs)
 
 	if v, ok := changes[FieldComposer].(string); ok {
 		tag.DeleteFrames("TCOM")
@@ -90,6 +84,64 @@ func applyTextChanges(tag *id3v2.Tag, changes TagChanges) {
 	}
 }
 
+// applyPositionFrame writes an ID3v2 position frame (TRCK or TPOS) in
+// the "n/N" form the readers parse.
+//
+// The number and the total are separate diff entries and either may be
+// absent, so the frame's *existing* value is the base: writing a total
+// alone must not discard the number that is already there, and writing
+// a number alone must not discard a total the file already declared.
+// A total with no number at all is not written, since "/12" says
+// nothing a reader can use.
+func applyPositionFrame(
+	tag *id3v2.Tag, description string, changes TagChanges, numKey, totalKey string,
+) {
+	_, hasNum := changes[numKey]
+	_, hasTotal := changes[totalKey]
+
+	if !hasNum && !hasTotal {
+		return
+	}
+
+	frameID := tag.CommonID(description)
+
+	num, total := parseXofN(
+		strings.TrimRight(tag.GetTextFrame(frameID).Text, "\x00 \t\n\r"),
+	)
+
+	if v, ok := asInt(changes[numKey]); ok {
+		num = v
+	}
+
+	if v, ok := asInt(changes[totalKey]); ok {
+		total = v
+	}
+
+	if num <= 0 {
+		return
+	}
+
+	value := strconv.Itoa(num)
+	if total > 0 {
+		value += "/" + strconv.Itoa(total)
+	}
+
+	tag.DeleteFrames(frameID)
+	tag.AddTextFrame(frameID, id3v2.EncodingUTF8, value)
+}
+
+// parseXofN splits an ID3v2 "n/N" position value.  A bare "n" yields a
+// zero total, and anything unparseable yields zeros — the same reading
+// dhowden/tag gives the frame.
+func parseXofN(s string) (int, int) {
+	numText, totalText, _ := strings.Cut(s, "/")
+
+	num, _ := strconv.Atoi(strings.TrimSpace(numText))
+	total, _ := strconv.Atoi(strings.TrimSpace(totalText))
+
+	return num, total
+}
+
 // applyCoverArtChanges handles the FieldCoverArt entry in the diff map.
 //
 //   - []byte with len > 0: embed the given image as front cover.

backend/tagwriter/ogg_vorbis.go

@@ -166,6 +166,8 @@ var oggFieldMappings = []struct { //nolint:gochecknoglobals // field mapping tab
 	{FieldYear, "DATE", true},
 	{FieldTrackNumber, "TRACKNUMBER", true},
 	{FieldDiscNumber, "DISCNUMBER", true},
+	{FieldTotalTracks, "TRACKTOTAL", true},
+	{FieldTotalDiscs, "DISCTOTAL", true},
 	{FieldComposer, "COMPOSER", false},
 }
 

backend/tagwriter/pipeline_test.go

@@ -333,3 +333,31 @@ func TestWriteTrackTags_DBSync(t *testing.T) {
 		t.Error("expected FTS5 result for 'New Title'")
 	}
 }
+
+// The row is what the album page reads, and it is only refreshed by a
+// scan.  Leaving total_tracks at whatever the last scan saw means an
+// album autotagged just now stays "unknown" -- a plain tick on an album
+// the user holds two tracks of -- until a full rescan happens to run.
+func TestWriteTrackTags_PersistsTheTotal(t *testing.T) {
+	db := database.NewTestDB(t)
+	dir := t.TempDir()
+	trackID := seedTestTrack(t, db, createPipelineTestMP3(t, dir))
+
+	tw := NewTagWriter(testLogger(), db, &mockPlayer{}, &mockPipelineLocker{})
+
+	if err := tw.WriteTrackTags(trackID, TagChanges{
+		FieldTrackNumber: 2,
+		FieldTotalTracks: 10,
+	}); err != nil {
+		t.Fatalf("WriteTrackTags: %v", err)
+	}
+
+	af, err := db.Queries.GetAudioFile(context.Background(), trackID)
+	if err != nil {
+		t.Fatalf("get audio file: %v", err)
+	}
+
+	if !af.TotalTracks.Valid || af.TotalTracks.Int64 != 10 {
+		t.Errorf("total_tracks: got %v, want 10", af.TotalTracks)
+	}
+}

backend/tagwriter/tagwriter.go

@@ -26,6 +26,15 @@ const (
 	FieldDiscNumber  = "disc_number"
 	FieldComposer    = "composer"
 	FieldCoverArt    = "cover_art" // []byte for set, nil for clear
+
+	// FieldTotalTracks is how many tracks are on *this file's disc*, not
+	// in the whole release.  That is what the "5/12" form declares and
+	// what GetAlbumCompleteness sums per disc; a release total written
+	// here would multiply the expectation by the number of discs.
+	FieldTotalTracks = "total_tracks"
+
+	// FieldTotalDiscs is how many discs the release has.
+	FieldTotalDiscs = "total_discs"
 )
 
 // AudioFormat represents a supported audio file format.

backend/tagwriter/totals_test.go

@@ -0,0 +1,199 @@
+package tagwriter
+
+import (
+	"path/filepath"
+	"testing"
+
+	"yellowjacket/backend/metadata"
+)
+
+// The totals are the evidence GetAlbumCompleteness reads, and every way
+// of getting them wrong is silent: a tag written under a name the
+// reader does not look at reads back as no total at all, which is
+// indistinguishable from never having written one.  So these assert the
+// round trip through the *reader the scan uses*, not the bytes.
+//
+// WAV is the exception and it is not this change's: dhowden/tag has no
+// RIFF reader at all, so metadata.ExtractTags cannot see a WAV's ID3
+// chunk -- which is why every other test here reads that chunk itself.
+func TestWriteTotals_RoundTripsInEveryFormat(t *testing.T) {
+	t.Parallel()
+
+	changes := TagChanges{
+		FieldTitle:       "Some Song",
+		FieldTrackNumber: 2,
+		FieldTotalTracks: 10,
+		FieldDiscNumber:  1,
+		FieldTotalDiscs:  2,
+	}
+
+	viaScanner := func(t *testing.T, path string) *metadata.TrackMetadata {
+		t.Helper()
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		return meta
+	}
+
+	tests := []struct {
+		name  string
+		write func(t *testing.T, dir string) string
+		read  func(t *testing.T, path string) *metadata.TrackMetadata
+	}{
+		{
+			name: "mp3",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := createTestMP3(t, dir, "totals.mp3", nil)
+				if err := writeMp3Tags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeMp3Tags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "flac",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := filepath.Join(dir, "totals.flac")
+				makeMinimalFLAC(t, path)
+
+				if err := writeFlacTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeFlacTags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "ogg",
+			read: viaScanner,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := filepath.Join(dir, "totals.ogg")
+				createTestOGG(t, path)
+
+				if err := writeOggTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeOggTags: %v", err)
+				}
+
+				return path
+			},
+		},
+		{
+			name: "wav",
+			read: readWavID3Tags,
+			write: func(t *testing.T, dir string) string {
+				t.Helper()
+
+				path := createTestWAV(t, dir, "totals.wav", nil)
+
+				if err := writeWavTags(testLogger(), path, changes); err != nil {
+					t.Fatalf("writeWavTags: %v", err)
+				}
+
+				return path
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			meta := tc.read(t, tc.write(t, t.TempDir()))
+
+			assertIntField(t, "TrackNumber", meta.TrackNumber, 2)
+			assertIntField(t, "TotalTracks", meta.TotalTracks, 10)
+			assertIntField(t, "DiscNumber", meta.DiscNumber, 1)
+			assertIntField(t, "TotalDiscs", meta.TotalDiscs, 2)
+		})
+	}
+}
+
+// A number and a total are separate diff entries, so writing one must
+// not discard the other.  For ID3v2 they share a single "n/N" frame,
+// which is the only place this can go wrong -- and it goes wrong by
+// silently zeroing a total the file already declared.
+func TestWriteMp3Totals_PartialUpdateKeepsTheOtherHalf(t *testing.T) {
+	t.Parallel()
+
+	t.Run("writing the number keeps the total", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "seeded.mp3", TagChanges{
+			FieldTrackNumber: 2,
+			FieldTotalTracks: 10,
+		})
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTrackNumber: 4,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 4)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 10)
+	})
+
+	t.Run("writing the total keeps the number", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "seeded.mp3", TagChanges{
+			FieldTrackNumber: 7,
+		})
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTotalTracks: 12,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 7)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 12)
+	})
+
+	// "/12" says nothing a reader can use, and dhowden/tag reads it as
+	// track 0 -- which the scan would store as a real track number.
+	t.Run("a total with no number writes nothing", func(t *testing.T) {
+		t.Parallel()
+
+		dir := t.TempDir()
+		path := createTestMP3(t, dir, "bare.mp3", nil)
+
+		if err := writeMp3Tags(testLogger(), path, TagChanges{
+			FieldTotalTracks: 12,
+		}); err != nil {
+			t.Fatalf("writeMp3Tags: %v", err)
+		}
+
+		meta, err := metadata.ExtractTags(path)
+		if err != nil {
+			t.Fatalf("ExtractTags: %v", err)
+		}
+
+		assertIntField(t, "TrackNumber", meta.TrackNumber, 0)
+		assertIntField(t, "TotalTracks", meta.TotalTracks, 0)
+	})
+}

backend/tagwriter/wav_test.go

@@ -522,19 +522,20 @@ func readWavID3Tags(
 		}
 	}
 
-	// Track number (TRCK).
+	// Track number and total (TRCK), disc number and total (TPOS).
+	// Both carry the "n/N" form, so they are read the way a reader
+	// reads them rather than with Atoi -- which sees "2/10" as 0.
 	trckID := parsed.CommonID("Track number/Position in set")
 	if frames := parsed.GetFrames(trckID); len(frames) > 0 {
 		if tf, ok := frames[0].(id3v2.TextFrame); ok {
-			meta.TrackNumber = atoiSafe(tf.Text)
+			meta.TrackNumber, meta.TotalTracks = parseXofN(tf.Text)
 		}
 	}
 
-	// Disc number (TPOS).
 	tposID := parsed.CommonID("Part of a set")
 	if frames := parsed.GetFrames(tposID); len(frames) > 0 {
 		if tf, ok := frames[0].(id3v2.TextFrame); ok {
-			meta.DiscNumber = atoiSafe(tf.Text)
+			meta.DiscNumber, meta.TotalDiscs = parseXofN(tf.Text)
 		}
 	}
 

build/android/Taskfile.yml

@@ -4,18 +4,28 @@ includes:
   common: ../Taskfile.yml
 
 vars:
-  # The *installed* package name, which every adb-driven task below uses
-  # to uninstall, launch and filter. It must agree with `applicationId`
-  # in app/build.gradle, and nothing enforces that.
+  # APP_ID is an *assertion*, not a setting, and it has no default.
   #
-  # ANDROID.md says to set this in build/config.yml. That does not work
-  # in beta.8, checked both ways: `wails3 task` builds its var set from
-  # CLI KEY=VALUE arguments and the Taskfile tree only -- nothing reads
-  # config.yml -- and even when set it feeds only these adb commands,
-  # never Gradle. So the identity is declared twice, here and in
-  # build.gradle, and a change to one alone means the official run and
-  # deploy tasks address a package that is not installed.
-  APP_ID: '{{.APP_ID | default "app.yellowjacket"}}'
+  # It used to be the id every adb-driven task below uninstalled,
+  # launched and filtered, defaulting to "app.yellowjacket". It could
+  # never have been a setting: `wails3 task` builds its var set from CLI
+  # KEY=VALUE arguments and the Taskfile tree only -- nothing reads
+  # build/config.yml, contrary to ANDROID.md, checked with --dry -- and
+  # even when set it fed only the adb commands, never Gradle. So the
+  # identity was declared twice, here and as `applicationId` in
+  # app/build.gradle, with nothing enforcing that they agree.
+  #
+  # They did not agree. The debug buildType carries
+  # `applicationIdSuffix ".dev"`, so the tasks that assemble a debug APK
+  # addressed the *release* id -- on a device, the user's installed app
+  # and their library (#159).
+  #
+  # The id is now read back from the built APK by scripts/android-
+  # pkgid.sh, so the thing installed and the thing launched agree by
+  # construction. Passing APP_ID= says "this build had better declare
+  # that id", and the deploy refuses before touching anything if it does
+  # not -- which is the check that would have caught #159 statically.
+  APP_ID: '{{.APP_ID | default ""}}'
   MIN_SDK: '21'
   TARGET_SDK: '35'
   # The emulator runs the host architecture; physical devices are arm64
@@ -372,9 +382,7 @@ tasks:
           ARCH: '{{.ARCH | default .HOST_ARCH}}'
     cmds:
       - task: ensure-emulator
-      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
-      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
-      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target emulator{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
 
   run:
     summary: Build, install and launch a debug build in the Android Emulator
@@ -383,9 +391,7 @@ tasks:
       - task: build
     cmds:
       - task: assemble:apk
-      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
-      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
-      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target emulator{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
 
   device:list:
     summary: Lists connected Android devices and emulators (serials)
@@ -400,25 +406,7 @@ tasks:
           ARCH: arm64
     cmds:
       - task: assemble:apk
-      - |
-        DEVICE='{{.DEVICE_ID | default ""}}'
-        if [ -z "$DEVICE" ]; then
-          DEVICE="${DEVICE_ID:-}"
-        fi
-        if [ -z "$DEVICE" ]; then
-          DEVICE=$("{{.ADB}}" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1; exit }')
-        fi
-        if [ -z "$DEVICE" ]; then
-          echo "Error: no connected physical Android device found."
-          echo "Pass DEVICE_ID=<serial> to target a device explicitly."
-          echo "Find connected device serials with: {{.ADB}} devices"
-          exit 1
-        fi
-
-        echo "Deploying {{.BIN_DIR}}/{{.APP_NAME}}.apk to device $DEVICE..."
-        "{{.ADB}}" -s "$DEVICE" uninstall {{.APP_ID}} 2>/dev/null || true
-        "{{.ADB}}" -s "$DEVICE" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"
-        "{{.ADB}}" -s "$DEVICE" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target device{{if .DEVICE_ID}} --serial "{{.DEVICE_ID}}"{{end}}{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
     preconditions:
       - sh: '[ -x "{{.ADB}}" ] || command -v adb'
         msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
@@ -430,25 +418,7 @@ tasks:
         vars:
           ARCH: arm64
     cmds:
-      - |
-        DEVICE='{{.DEVICE_ID | default ""}}'
-        if [ -z "$DEVICE" ]; then
-          DEVICE="${DEVICE_ID:-}"
-        fi
-        if [ -z "$DEVICE" ]; then
-          DEVICE=$("{{.ADB}}" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1; exit }')
-        fi
-        if [ -z "$DEVICE" ]; then
-          echo "Error: no connected physical Android device found."
-          echo "Pass DEVICE_ID=<serial> to target a device explicitly."
-          echo "Find connected device serials with: {{.ADB}} devices"
-          exit 1
-        fi
-
-        echo "Deploying {{.BIN_DIR}}/{{.APP_NAME}}.apk to device $DEVICE..."
-        "{{.ADB}}" -s "$DEVICE" uninstall {{.APP_ID}} 2>/dev/null || true
-        "{{.ADB}}" -s "$DEVICE" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"
-        "{{.ADB}}" -s "$DEVICE" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target device{{if .DEVICE_ID}} --serial "{{.DEVICE_ID}}"{{end}}{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
     preconditions:
       - sh: '[ -x "{{.ADB}}" ] || command -v adb'
         msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"

build/android/app/src/main/java/com/wails/app/MainActivity.java

@@ -891,13 +891,41 @@ public class MainActivity extends AppCompatActivity {
         }
     }
 
+    /**
+     * The activity going away is not the app shutting down.
+     *
+     * <p>The scaffold called {@code bridge.shutdown()} here, which is
+     * the natural reading of onDestroy and is wrong for this app twice
+     * over. Android destroys and recreates an activity for a
+     * configuration change the manifest does not declare, under memory
+     * pressure, and on every background if the user has "Don't keep
+     * activities" on -- all **without restarting the process**. And
+     * when the user really does leave, this app's reason for existing
+     * in the background is that a song is playing, which is what the
+     * {@code mediaPlayback} foreground service is holding the process
+     * alive for. Either way, tearing the Go side down here would stop
+     * the music.
+     *
+     * <p>It was harmless only by accident: {@code nativeShutdown} calls
+     * {@code App.Quit()}, whose Android {@code destroy()} is an empty
+     * method, and {@code Run()}'s deferred {@code shutdownServices()}
+     * can never fire because Android's {@code platformRun} is
+     * {@code select{}} and does not return. So no {@code
+     * ServiceShutdown} has ever run on Android, and removing this call
+     * changes nothing today -- it stops the day someone implements
+     * {@code destroy()} from silently killing playback on a rotation.
+     *
+     * <p>There is no callback for "the process is going away"; Android
+     * simply kills it. Durability on this platform is the persist
+     * writers, which submit on every mutation rather than at exit.
+     *
+     * <p>See #52, and CLAUDE.md, "An activity is a view onto the
+     * process".
+     */
     @Override
     protected void onDestroy() {
         super.onDestroy();
         unregisterSystemEventReceivers();
-        if (bridge != null) {
-            bridge.shutdown();
-        }
         if (webView != null) {
             webView.destroy();
         }

build/android/app/src/main/java/com/wails/app/WailsBridge.java

@@ -129,7 +129,24 @@ public class WailsBridge {
     }
 
     /**
-     * Initialize the native Go library
+     * Initialize the native Go library.
+     *
+     * <p><b>{@code initialized} is deliberately per-instance, and making
+     * it {@code static} is the trap this comment exists for.</b> A
+     * recreated activity builds a new bridge and calls this again, in a
+     * process where the native library is already loaded and Go's
+     * {@code main()} is already running -- so "initialise once per
+     * process" looks like exactly the right rule. It is not, because
+     * {@code nativeInit} does <i>two</i> things: it runs
+     * {@code go mainFunc()}, and it stores the global JNI reference to
+     * <i>this</i> bridge. Skip it and Go keeps executing JavaScript
+     * against the destroyed activity's WebView: the app opens, renders,
+     * and never receives another backend event.
+     *
+     * <p>So this is called every time, and the half that must not repeat
+     * is latched on the Go side instead, at the top of {@code main()} --
+     * which is also where the damage was ({@code os.Exit(1)}), and the
+     * only place that can see it. See #52.
      */
     public void initialize() {
         if (initialized) {

docs/android-release.md

@@ -7,12 +7,22 @@ which is what lets Obtainium poll a plain URL with no token. It also
 attaches the same file to the Gitea release, which is what a person
 looking at the release page downloads.
 
-**Tags are not pushed by hand any more.** `.gitea/workflows/release.yml`
-reads the Conventional Commits on every merge to `main`, decides the
-version, and pushes the tag this workflow is keyed on — so releasing the
-APK means merging a `fix:` or `feat:` commit, not running `git tag`. The
-`workflow_dispatch` path below remains, for rebuilding a tag that already
-exists.
+**Tags are not pushed by hand any more, but releasing is a decision.**
+`.gitea/workflows/release.yml` reads the Conventional Commits since the
+last tag, decides the version, and pushes the tag this workflow is keyed
+on — so releasing the APK means **running that workflow**, not running
+`git tag`. It has no push trigger: merging a `fix:` or `feat:` used to
+be enough and produced a version per merged PR (issue #115). Run it with
+`dry_run` first to see what the accumulated commits would ship. The
+`workflow_dispatch` path below is a different thing and remains, for
+rebuilding a tag that already exists.
+
+**A prerelease tag is skipped here**, cleanly. This workflow triggers on
+`v*`, which matches `v0.4.0-beta.1`, and it is the one where that would
+hurt most: the APK goes to the credential-free generic registry that
+Obtainium polls, and the `versionCode` maths below splits on dots — it
+would read `1` out of `0-beta` and produce a wrong number rather than a
+failed build.
 
 ## The 1.x installs cannot be upgraded to 0.0.x
 

docs/dev/config-suggestions.md

@@ -1,194 +0,0 @@
-# Config Improvement Suggestions
-
-Remaining suggestions for improving the configuration system in YellowJacket.
-
-## 2. Thread Safety Concerns
-
-The current `Config` struct lacks synchronization:
-- `Load()` and `Save()` can race with concurrent reads
-- `handleConfigUpdate()` in library mutates `l.conf.DirectoryPath` without locks
-
-**Suggestion:** Add a `sync.RWMutex` to protect config access, especially if config is read during scans.
-
-```go
-type Config struct {
-    mu       sync.RWMutex
-    ctx      context.Context
-    logger   *slog.Logger
-    // ...
-}
-
-func (c *Config) Load() error {
-    c.mu.Lock()
-    defer c.mu.Unlock()
-    // ...
-}
-```
-
-## 3. Nil Safety in Validation
-
-In `config.go`, validation only runs if `c.Library != nil`, but `handleConfigPost` dereferences `postedConfig.Library` without checking for nil:
-
-```go
-if postedConfig.Library != nil {
-    c.Library = postedConfig.Library
-    // ...
-}
-```
-
-**Status:** Partially addressed in the event refactor, but consider adding explicit nil checks in `Validate()` as well.
-
-## 4. Inconsistent Error Handling on HTTP Responses
-
-In `httphandler.go:28-31`, `WriteHeader` is called *after* rendering the error template, which won't work as expected (headers must be set before writing body):
-
-```go
-c.formSubmitError(err.Error()).Render(r.Context(), w)
-w.WriteHeader(http.StatusInternalServerError)  // Too late!
-```
-
-**Fix:** Set the status code before rendering:
-
-```go
-w.WriteHeader(http.StatusInternalServerError)
-c.formSubmitError(err.Error()).Render(r.Context(), w)
-```
-
-## 5. Make `scanWorkerCount` Configurable
-
-There's a TODO at `library.go:289`:
-```go
-// TODO: make configurable via Config.
-var scanWorkerCount = goruntime.NumCPU()
-```
-
-**Suggestion:** Add this to `library.Config`:
-
-```go
-type Config struct {
-    DirectoryPath Directory `form:"Directory" schema:"directory,required"`
-    ScanWorkers   int       `form:"ScanWorkers" schema:"scan_workers"`
-}
-```
-
-Then in `NewLibrary()` or `Scan()`:
-
-```go
-workers := l.conf.ScanWorkers
-if workers <= 0 {
-    workers = goruntime.NumCPU()
-}
-```
-
-## 6. Consider Config Defaults
-
-Currently if no config exists, an empty one is saved. Consider providing sensible defaults (e.g., common music directories like `~/Music`).
-
-```go
-func (c *Config) setDefaults() {
-    if c.Library == nil {
-        c.Library = &library.Config{}
-    }
-    if c.Library.DirectoryPath == "" {
-        // Try common music directories
-        home, _ := os.UserHomeDir()
-        musicDir := filepath.Join(home, "Music")
-        if info, err := os.Stat(musicDir); err == nil && info.IsDir() {
-            c.Library.DirectoryPath = library.Directory(musicDir)
-        }
-    }
-}
-```
-
-## 7. Config Reload/Watch Capability
-
-The config is only loaded at startup. Consider adding:
-- File watcher for external config changes (using `fsnotify`)
-- Explicit reload method callable from UI
-
-```go
-func (c *Config) Watch() error {
-    watcher, err := fsnotify.NewWatcher()
-    if err != nil {
-        return err
-    }
-    
-    go func() {
-        for event := range watcher.Events {
-            if event.Op&fsnotify.Write == fsnotify.Write {
-                c.Load()
-                // Emit event for listeners
-            }
-        }
-    }()
-    
-    return watcher.Add(c.filePath)
-}
-```
-
-## 8. Validation Should Return Structured Errors
-
-Currently validation returns combined errors. Consider returning a structured validation result that the UI can map to specific fields for better user feedback.
-
-```go
-type ValidationError struct {
-    Field   string
-    Message string
-}
-
-type ValidationResult struct {
-    Valid  bool
-    Errors []ValidationError
-}
-
-func (c *Config) ValidateStructured() ValidationResult {
-    var result ValidationResult
-    result.Valid = true
-    
-    if c.Library != nil {
-        if err := c.Library.Validate(); err != nil {
-            result.Valid = false
-            result.Errors = append(result.Errors, ValidationError{
-                Field:   "Library.DirectoryPath",
-                Message: err.Error(),
-            })
-        }
-    }
-    
-    return result
-}
-```
-
-## 9. Use Standard Library for Config Paths
-
-The path construction in `system/userdata.go` doesn't respect `$XDG_CONFIG_HOME` on Linux or use the standard Go `os.UserConfigDir()`.
-
-**Current implementation:**
-```go
-case "linux":
-    return fmt.Sprintf("/home/%s/%s/yellowjacket", username, unixSubdirs[dt]), nil
-```
-
-**Suggested improvement:**
-```go
-func GetUserConfigDirPath() (string, error) {
-    baseDir, err := os.UserConfigDir()  // Respects XDG_CONFIG_HOME
-    if err != nil {
-        return "", fmt.Errorf("could not get user config directory: %w", err)
-    }
-    
-    path := filepath.Join(baseDir, "yellowjacket")
-    
-    if err := os.MkdirAll(path, 0o755); err != nil {
-        return "", fmt.Errorf("could not create config directory: %w", err)
-    }
-    
-    return path, nil
-}
-```
-
-This approach:
-- Respects `$XDG_CONFIG_HOME` on Linux
-- Uses proper macOS paths (`~/Library/Application Support`)
-- Uses `%AppData%` on Windows
-- Is more portable and follows platform conventions

docs/dev/overview.md

@@ -1,53 +0,0 @@
-# Development Overview
-
-YellowJacket is a moderately complex application. This document gives an overview of how development of it works.
-
-## Logical Breakdown
-
-YellowJacket can be thought about in a heirarchy of logical modules and components. The borders of these logical sections are mostly represented in the code and directory structure as well.
-
-- Frontend
-  - UI Components (see [Lit](###lit-web-components))
-- Backend
-  - App
-    - Asset Handler
-    - Logging
-    - System
-  - Player
-  - Library
-  - Config
-  - Database
-    - Queries (see [sqlc](###sqlc))
-
-## Dependencies
-
-YellowJacket uses many tools and libraries to provide its functionality. 
-This section lists each of these dependencies and explains how they are used.
-
-### [Wails](https://wails.io)
-
-Used to create desktop apps with Go and web technologies.
-
-### [SQLite](https://github.com/mattn/go-sqlite3?tab=readme-ov-file#go-sqlite3)
-
-Used for local database.
-
-### [sqlc](https://sqlc.dev/)
-
-Used to generate Go code from SQL.
-
-### [Templ](https://templ.guide/)
-
-Used to generate HTML templates with Go code.
-
-### [Beep](https://github.com/gopxl/beep?tab=readme-ov-file#beep)
-
-Used for audio playback.
-
-### [Lit Web Components](https://lit.dev/)
-
-Used for dynamic/reactive frontend components.
-
-### [HTMX](https://htmx.org/)
-
-Used for requesting HTML fragments from the backend and rendering them on the frontend.