Report pacing once per stretch, and stop stranding paused users

[taurheim]

Why

The 2026-07-27 deploy swapped reactive rate-limit handling for preventive pacing. It worked — real Last.fm throttling all but disappeared — but the wait sits at the top of the per-track loop, and RateLimitTracker.msUntilWindowHasRoom only ever frees one slot at a time. So once the rolling window filled, every track took that branch.

scrobble_paused / burst_limit, per day:

	07-17	07-20	07-27	07-28	07-29
rate_limit	327	128	63	5	5
burst_limit	~15	~19	180	427	734

Those 734 came from 5 scrobble_started events. Median wait_ms was 630ms and median burst_count was 500 — pinned exactly at burst_limit. The old code paused 10 minutes and reset the counter, giving one event per ~950 scrobbles; this was roughly one per scrobble.

It wasn't only telemetry. pauseWithCountdown sets paused = true, which swaps the entire template into the paused panel — so users watched the UI flicker in and out of "Paused" once per track. And because it resolves on a 1s interval tick, every sub-second wait was rounded up to a full second.

What changed

Pacing is a stretch, not a pause. beginPacing/endPacing bracket it and report once on entry and once on exit (scrobble_pacing_ended, carrying paced_tracks / paced_wait_ms / pacing_duration_ms). Waits under PACING_COUNTDOWN_THRESHOLD_MS use a plain sleep behind an inline notice.

scrobble_stopped split out of scrobble_paused. Every terminal case previously reused the scrobble_paused name, and repeated_rejections / repeated_failures emitted nothing at all. Now:

• scrobble_paused — transient, auto-resumes: burst_limit, rate_limit, network_error
• scrobble_stopped — terminal: daily_limit, lastfm_daily_limit, rate_limit_exhausted, repeated_rejections, repeated_failures, manual

All terminal paths go through a trackStopped() helper so a new one can't silently skip the event, and each carries auto_saved.

Terminal paths all offer a way back in. The resume button was gated on stopped, which manualPause, repeated_rejections and repeated_failures never set — all three rendered a disabled "Wait Here" button waiting on an auto-resume the loop had already returned from. The only escape was leaving and re-importing. It now keys off canResume (stopped || manuallyPaused), with a manual pause styled info rather than red.

"Pause & Save" actually saves. It never called autoSave(), despite the label; nor did the repeated-failures stop. Note the save happens in the loop's between-tracks pause check, not in manualPause — snapshotting on the click would omit the in-flight track's increment and re-send it on resume, and for a re-tagged play that means a freshly allocated timestamp and a phantom duplicate scrobble.

trackError can no longer throw. It coerced with String(error) and normalised the payload outside its own try/catch, breaking the invariant the file documents. Both throw on a Symbol or an object with a throwing toString, and the global handlers pass through whatever a third party threw — so it lost the report and raised a fresh error out of a catch block. Coercion is now guarded in toError().

Testing

• npm run lint:check — 0 errors (86 pre-existing warnings)
• npm run build — clean
• Two new regression tests, each verified to fail without its fix:
  • preventive pacing keeps scrobbling, it does not pause per track — samples repeatedly for the paused panel, since the bug was a per-track flicker a single check could land between
  • a manual pause saves, offers a way back, and does not re-send the in-flight track — asserts the enabled resume button, absence of "Wait Here", the save confirmation, that the loop halts, and that the resumed run scrobbles each track exactly once
• 16/17 tests pass across Scrobble Step, Rate limit handling, Session Resume, No JS Errors, Import robustness. The one failure, gives up and saves instead of retrying a rate limit forever, is a pre-existing local-Windows flake — confirmed by stashing src/ and reproducing at HEAD; it passes in CI.

Heads-up

scrobble_stopped is a breaking change for any saved PostHog insight that filters scrobble_paused on a terminal reason — those reasons now live on the new event.

Also note burst_limit counts between 2026-07-27 and 2026-07-29 are inflated by this bug and aren't comparable with anything after it. AGENTS.md records that.