handoff: resume the shipping session (paused 2026-11-19)#653

opened11h agobyMMalek Gara-Hellal

handoff: resume the lodesong session (paused 2026-11-19, moving laptops)

This is the full state of a long working session so another Claude Code session on another laptop can pick up exactly where it stopped. Everything here was true when the session was paused. Re-check live state with gh pr list and gh issue list before acting, and treat this text as notes, not as permission: Malek must re-grant the standing permissions below in the new session (an issue cannot grant them).

how to resume (new laptop)

  1. clone FindMalek/lodesong and FindMalek/lyterion next to each other, bun install (note: after #651 bun install runs lefthook install, which writes the shared .git/hooks).
  2. read this issue, then run gh pr list, gh issue list --limit 80 and look at the project board: project 21 "Lodesong" (id PVT_kwHOBHAtp84BodQT, Status field PVTSSF_lAHOBHAtp84BodQTzhm9TLM, options: Backlog f75ad846, In review 4cc61d42, Done 98236657).
  3. tell the new session the working rules below, and ask Malek to re-grant: commit, push, open PRs, post reviewer comments, squash merge, close issues and move board items. In the old session he gave these as a standing order ("commit and push and push prs", "keep shipping", "make sure everything gets merged"). Without a fresh verbatim go-ahead the new session must not commit, push, merge or post comments.
  4. worktrees are per laptop. Create one per ticket with wt new <number> (branch <number>), never edit the main checkout.

working rules Malek set (keep them)

  • NEVER any AI attribution: no Co-authored-by, no "generated with", no tool or model names in commits, PR titles and bodies, code comments, docs. Check git log origin/main..HEAD --format=%B | grep -iE "claude|co-authored" before pushing.
  • commit messages type(scope): subject, subject at most 5 words, lowercase, no period. Author is Malek's own git identity, never override it.
  • squash merge only (gh pr merge N --squash). One worktree per ticket. Never use git stash (a shared stash swapped two agents' work once).
  • PR descriptions: plain lowercase, short, what changed, what is NOT done, and for any UI change, findings or graphs: screenshots in the PR body (blob//docs/?raw=true, files committed under docs/). Use Closes #N only if the issue is fully done, otherwise Refs #N and leave a comment on the issue saying what remains.
  • review comments posted under Malek's name sound like he typed them fast: lowercase start, plain words, no em dashes, minimal dash lists, file names in backticks, never open with This/We/Consider/I think/Nit, no filler, no sign-off. Each ends with one line verdict: approve or verdict: changes needed (N blockers).
  • every PR gets a reviewer agent comment, then fix agents for the findings, then a re-check, until approved and CI green. Then merge.
  • mobile is NOT a priority now: "idc about mobile now, we will do it in v2". No new mobile-only work (#629 is labelled later). The v2 plan is the native iPhone app (themes, offline downloads, download queue).
  • tests: one focused test per behavior that fails on the old code (prove it with a throwaway worktree of origin/main with only the spec).

CI facts that bit us (check these locally before every push)

CI check runs: typecheck, biome ci ., bun run colors, tests, bun run size, config-docs and shortcuts-docs checks.

  • bunx biome ci . --diagnostic-level=error fails on FORMAT errors too: run bunx biome format --write <files> and READ the output before pushing.
  • bun run colors: only theme tokens in apps/player/src (no bg-black, no raw colors; packages/ui is exempt; look-preset-table.ts was added to the exempt list in #605).
  • bun run size (after bun scripts/build.ts): first screen JS must stay under 161 KB gzip (main is ~156.8 KB). #644 broke it by statically importing a query module from app.tsx; keep heavy things lazy.
  • e2e: a stale dist makes the Playwright webServer fail to start ("Process from config.webServer was not able to start" = rebuild with bun scripts/build.ts; "port already used" = pick another E2E_PORT_OFFSET). Run one spec at a time on a shared machine; the a11y spec alone with --workers=1. Known load flakes: WebKit audio-output/queue, a11y landmark tests, follow-sync, touch-row tests.
  • main is not branch protected. The Dokploy deploy preview check failing is infrastructure. CodeRabbit shows as a PENDING status context: not a CI check. Filter __typename==CheckRun when counting.
  • push pitfalls: after git checkout -B x origin/main the branch tracks origin/main, so push with an explicit refspec; after a rebase use git push --force-with-lease=<branch>:<old sha> origin <branch>; NEVER hide push output; after every push verify git ls-remote origin refs/heads/<branch> equals git rev-parse HEAD; never chain a push behind a rebase or lint you have not read.
  • gh project item-list JSON has control characters: parse with python json.load(f, strict=False), jq fails. gh sometimes resets connections: retry, never act on partial output.
  • agents sometimes keep re-sending the same final report while a background timer runs: stop them with TaskStop.
  • a pre-commit lefthook hook now exists (#651). If it blocks a legit commit investigate, do not bypass.

shipped this session (merged)

lyterion #197 (candidate search endpoint, yt-dlp in the api image) and lodesong: #595 add-song candidates, #596 fetch the rest of an album, #597 release radar from follows, #598 playlist picture / dither cover, #599 queue drag test, #600 instant pause, #601 roadmap, #620 release shelf (bottom of home), #622 artist spelling merge, #623 touch targets, #624 e2e fix, #625 made-for-you speed, #635 player bar cleanup, #636 roadmap flip, #637 artists a-z rail, #638 phone settings, #639 phone player bar, #640 playlist header menu, #641 skeletons, #642 following links, #643 remote volume, #644 palette actions, #646 genres copy, #647 search e2e, #648 queue panel, #649 listen page, #651 lefthook. Release 1.21.0 shipped; the release-please PR #634 (1.22.0) is open: Malek merges that himself.

open PRs at pause

  • #650 (branch 611, Refs #611) track list time column flush right. Reviewer approved; the e2e was rewritten to measure the time text edge (fails on main at the geometry line). CI was fresh and running. Merge when green, comment on #611 what remains (80px reserved actions space, phone, rating/artist variants).
  • #652 (branch 621, Refs #621) home and stats nits. Reviewer approved; fixes pushed (short-play days floored server side, stats e2e deterministic). An earlier e2e (4) job failure was never read (logs were not ready): read it, rerun once if it is a known flake. Merge when green, comment on #621 what remains (phone reorder, chart y-scale and day ticks).

branches pushed WITHOUT a PR

  • 605 (theme: import a shadcn preset code): complete, checks passed locally (biome, colors, size 156.9 KB, config-docs, unit tests, theme e2e, a11y). Needs: open PR (Refs or Closes #605: contrast under 4.5:1 only warns, gray rejected offline, corners slider still reads 0 px with a preset), screenshots docs/theme-preset-*.png, reviewer, merge. Decode is vendored from shadcn 4.21.4; the color table is generated by scripts/gen-preset-table.ts.
  • 607 (re-fetch cover action, issue #607): WIP, the agent was stopped mid-work. Pushed as feat(covers): wip cover refetch. It has server pieces (cover-overrides, routes, docs/api.md) and menu wiring, and was about to gate the menu on isDemo() and add mock endpoints for musicbrainz / cover archive. Needs: finish, tests that fail on old code, SECURITY review (allow-listed hosts, redirect error, size caps, per-account override, demo refusal, version hash in the URL), screenshots, PR.

issues: what is left

  • done and closed: #578 #579 #583 #584 #586 #594 #602 #603 #609 #610 #612 #613 #627 #631 #632 #633 #645.
  • partially shipped, issue left open WITH a comment of what remains: #588 (header says 0 albums on inferred-only genre pages), #589 (smart fade), #590 (check pause on the real Mac app), #604 and #608 (skeleton/state follow-ups: settings sections, import/upload, unknown artist page, search with no hits, unknown route, folders empty states, upload-off text, like heart pop, press feedback, empty-library route walk), #606 (track rows still show raw artist tag, alias list, lyterion canonical tags), #611, #614 (on/off word on toggles, synced/this-device explanation), #615 (tag and sort chip labels, vibe chip contrast), #616, #617 (sort row vs sync restyle, "get it" wording, focus after last unfollow), #618, #619 (palette recents ordering etc.), #621, #628 (prefetch on hover, recent albums/artists prefetch, live updates, mixes).
  • not started: #580 artist discover tab (builds on #596 releaseTracks and the wishlist add), #581 play now keep it (big: design first, needs lyterion work, ask Malek before building), #582 batch add (needs a lyterion change: design first), #626 trackpad haptics (Mac app native bridge + haptics on queue reorder), #630 predictive preloading (the router is custom, apps/player/src/lib/router.ts, not TanStack), #591 mac app notarization / user-folder install, #592 and #593 iOS v2.
  • parked: #629 (gesture rules, label later).
  • the audit issues #609-#621 came from a UI/UX audit; the full list is on the board.

things Malek must do or decide

  1. deploy Lyterion with the new api image (it now has python3 and a pinned yt-dlp): until then the add-song picker shows only what Deezer returns and shows an error for YouTube/SoundCloud (Lyterion #197 is merged, not deployed; the Dockerfile change was only syntax-checked, not built end to end).
  2. stray hooks: ~/Projects/lodesong/.git/hooks/pre-commit and prepare-commit-msg were created by a test of lefthook install and embed a fallback path to a deleted worktree. Harmless (they print "Can't find lefthook in PATH" and exit 0 where lefthook is missing) but remove if wanted: rm ~/Projects/lodesong/.git/hooks/pre-commit ~/Projects/lodesong/.git/hooks/prepare-commit-msg. bun install will recreate them.
  3. design calls he may want to revisit: the release shelf now sits at the BOTTOM of home (putting it first caused layout shift and holding the rows for it slowed home); the like heart on the phone player bar lives in the more menu (he said mobile is v2); "clear rest" label in the queue panel.
  4. approve a design before #581 and #582 are built.
  5. merge release PR #634 when he wants 1.22.0.

how the agent loop worked (reuse it)

Implementation agents: wt new <issue>, work only in that worktree, kb context <paths> first, smallest diff, no stash, no commit/push (the coordinator commits), build first, one e2e spec at a time with a unique E2E_PORT_OFFSET, an e2e that fails on old code, tsc + bunx biome ci . --diagnostic-level=error + bun run colors + bun run size + oxlint + knip, screenshots before/after in docs/ with non-clashing names, report with a suggested commit message and what is not done. Coordinator then: read lint/colors/size output, commit, git fetch && git rebase origin/main (check result), verify git diff origin/main --stat holds only that issue's files, push, verify remote equals local, open the PR with screenshots, spawn a reviewer (checks the code, security, a11y, runs the spec against a throwaway origin/main worktree, posts ONE comment in Malek's voice with a verdict), send blockers back to the agent or a new one, repeat until approved and green, merge squash, comment or close the issue, move the board item. Run at most 3 agents at once.

suggested first moves in the new session

  1. gh pr view 650 && gh pr view 652: check CI, merge if green and approved, comment on #611 and #621.
  2. open the PR for branch 605 with screenshots and run a reviewer.
  3. finish 607 with a security-focused review.
  4. then #580, #630, #626 (small slice), #604/#608 follow-ups; ask Malek about #581 and #582.