handoff: resume the shipping session (paused 2026-11-19)#653
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)
- clone
FindMalek/lodesongandFindMalek/lyterionnext to each other,bun install(note: after #651bun installrunslefthook install, which writes the shared.git/hooks). - read this issue, then run
gh pr list,gh issue list --limit 80and look at the project board: project 21 "Lodesong" (idPVT_kwHOBHAtp84BodQT, Status fieldPVTSSF_lAHOBHAtp84BodQTzhm9TLM, options: Backlogf75ad846, In review4cc61d42, Done98236657). - 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.
- 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. Checkgit 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 usegit 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/). UseCloses #Nonly if the issue is fully done, otherwiseRefs #Nand 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: approveorverdict: 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=errorfails on FORMAT errors too: runbunx biome format --write <files>and READ the output before pushing.bun run colors: only theme tokens inapps/player/src(nobg-black, no raw colors;packages/uiis exempt;look-preset-table.tswas added to the exempt list in #605).bun run size(afterbun 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 fromapp.tsx; keep heavy things lazy.- e2e: a stale
distmakes the Playwright webServer fail to start ("Process from config.webServer was not able to start" = rebuild withbun scripts/build.ts; "port already used" = pick anotherE2E_PORT_OFFSET). Run one spec at a time on a shared machine; the a11y spec alone with--workers=1. Known load flakes: WebKitaudio-output/queue, a11y landmark tests,follow-sync, touch-row tests. mainis not branch protected. The Dokploydeploypreview check failing is infrastructure. CodeRabbit shows as a PENDING status context: not a CI check. Filter__typename==CheckRunwhen counting.- push pitfalls: after
git checkout -B x origin/mainthe branch tracks origin/main, so push with an explicit refspec; after a rebase usegit push --force-with-lease=<branch>:<old sha> origin <branch>; NEVER hide push output; after every push verifygit ls-remote origin refs/heads/<branch>equalsgit rev-parse HEAD; never chain a push behind a rebase or lint you have not read. gh project item-listJSON has control characters: parse with pythonjson.load(f, strict=False), jq fails.ghsometimes 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 earliere2e (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,grayrejected offline, corners slider still reads 0 px with a preset), screenshotsdocs/theme-preset-*.png, reviewer, merge. Decode is vendored from shadcn 4.21.4; the color table is generated byscripts/gen-preset-table.ts.607(re-fetch cover action, issue #607): WIP, the agent was stopped mid-work. Pushed asfeat(covers): wip cover refetch. It has server pieces (cover-overrides, routes, docs/api.md) and menu wiring, and was about to gate the menu onisDemo()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
- 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).
- stray hooks:
~/Projects/lodesong/.git/hooks/pre-commitandprepare-commit-msgwere created by a test oflefthook installand 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 installwill recreate them. - 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.
- approve a design before #581 and #582 are built.
- 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
gh pr view 650 && gh pr view 652: check CI, merge if green and approved, comment on #611 and #621.- open the PR for branch
605with screenshots and run a reviewer. - finish
607with a security-focused review. - then #580, #630, #626 (small slice), #604/#608 follow-ups; ask Malek about #581 and #582.