Handoff audit: fix upstream-failure 500s + Safari/live bugs, add self-enforcing guardrails

[betmoar]

Full-codebase audit with remediation and permanent guardrails. Every fix has a regression test; the architecture invariants are now enforced by tests instead of prose.

Bug fixes (each verified with a reproducing test first)

Backend

• Upstream failures no longer 500. pytubefix exceptions are mapped to YouTubeError in the adapter and handled globally: dead/private video → 404 VIDEO_UNAVAILABLE, anti-bot wall → 503 YOUTUBE_BLOCKED, pytubefix breakage → 502 UPSTREAM_FAILURE, YouTube unreachable → 502 UPSTREAM_UNREACHABLE. Previously /api/video, /proxy/audio|stream, and /api/hls all returned bare 500s on the most common runtime failures (expired cached itag, removed video). Replaces the dead HumError class.
• HLS sidx parser crash. A sidx box extending past the 64 KB head fetch raised struct.error → 500. Now returns None → 415 → clean direct-stream fallback.
• Finished live streams never ended. The tail-trim rewriter dropped #EXT-X-ENDLIST (it was queued as a per-segment tag with no following segment), so players polled a dead stream forever. It's now re-emitted after the kept segments.
• SSRF via redirect. follow_redirects=True only allowlist-checked the initial URL; an httpx request event hook now enforces the YouTube host allowlist on every hop.
• Non-ASCII bearer header → 401 instead of 500 (compare_digest on bytes).
• Live master-manifest cache no longer grows unbounded (evict expired on write).
• /api/debug/live/* (leaks raw CDN URLs) now requires DEBUG=true, not just the bearer.

Frontend

• Safari replayed expired signed URLs after reload. hlsUrl survived queue persistence while audioUrl was stripped, so pickVodSrc() returned a dead URL and the rehydrate refetch never ran. Now stripped on flush and rehydrate.
• Search race. Debounced typing fired overlapping requests with last-write-wins; a slow early query could overwrite newer results. Requests are now sequenced.
• play() promise rejections caught (safePlay()); 20-listener audio event logger gated behind import.meta.env.DEV.

Guardrails & tooling

• tests/unit/test_invariants.py — the three load-bearing rules enforced as tests: pytubefix imported only in the adapter, single httpx.AsyncClient, every route bearer-authed or signature-verified (route-table introspection), adapter never emits CDN URLs.
• tests/unit/test_audit_regressions.py — one test per fix above, each commented with the failure it locks out.
• scripts/check.sh — single pre-push gate mirroring CI exactly; removed the stale StreamTube-era dev-setup.sh (installed a nonexistent extra) and test.sh.
• CI/release now lint tests too (ruff check ., with test-appropriate ignores; existing violations fixed).
• Dockerfile runs as non-root; pytubefix's token-cache dir pre-created so enabling po_token later (the usual YouTube-block mitigation) doesn't crash.

Handoff docs

• CLAUDE.md — mental model, load-bearing map, landmines, change-X-update-Y couplings.
• docs/PLAYBOOKS.md — step-by-step procedures: "pytubefix broke", adding endpoints, adding signed-URL types, touching the stream cache or Player.
• docs/BACKLOG.md — prioritized residual risks and debt (top item: CSP to neutralize the localStorage-token XSS exposure).
• Fixed doc drift: repo links still pointing at betmoar/streamtube, stale test counts, routes.ts naming, CI listed as a non-goal despite existing.

Verification

./scripts/check.sh fully green: ruff clean (app + tests), mypy --strict clean, 157 backend tests (was 143), 148 frontend tests (was 146), svelte-check 0 errors, vite build OK.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EAANTDpjvHuz7DXt8M8dhZ

---

Generated by Claude Code