Make Rescan non-destructive — it silently wipes usage history

[OtoGodfrey]

The problem

The Rescan button (and its POST /api/rescan handler) does a full rebuild: it unlink()s usage.db and re-scans from the JSONL transcripts on disk.

That is silent, unrecoverable data loss. Claude Code prunes old session transcripts on a rolling basis (cleanupPeriodDays), so on any given day ~/.claude/projects only holds roughly the last few weeks. usage.db is append-only, which makes it the only place older history survives. Deleting it and rebuilding from disk therefore permanently discards every day older than the current on-disk retention window — with no warning and no backup. The tooltip actively invites the click ("Use if data looks stale or costs seem wrong").

Repro

1. Run the tool for a while so usage.db accumulates history (e.g. a few months).
2. Claude Code, meanwhile, deletes transcripts older than its retention window.
3. Click Rescan.
4. All history older than what's still on disk is gone. In my case a one-month-old install with data back to mid-February was reduced to the last ~30 days the instant Rescan ran.

The fix

• Remove the Rescan button, its click handler, and its CSS.
• Keep POST /api/rescan, but make it append-only: it now calls scanner.scan() without unlinking the DB. scanner.scan() already tracks processed files and only inserts new turns, so a refresh updates the DB without ever destroying history.

Net diff is small (+6 / −23). All 103 existing tests pass (including test_api_rescan_returns_json).

Note

I kept /api/rescan as a safe incremental refresh rather than removing the endpoint outright, since it's the more conservative change. If you'd rather drop the endpoint entirely (the button was its only caller), or instead keep a destructive rebuild but back the DB up first, happy to adjust.

🤖 Generated with Claude Code

[phuryn]

Thank you for catching this, @OtoGodfrey — and for the detailed write-up. You're exactly right: usage.db is append-only and the only durable record once Claude Code prunes transcripts past cleanupPeriodDays, so the wipe-and-rebuild in /api/rescan was silent data loss. Sorry it cost you history.

I've landed the core of your fix on DEV (97e1d91), with credit to you via a Co-Authored-By trailer. One deliberate divergence: I kept the button rather than removing it. Auto-refresh only re-reads /api/data and never scans, so the button is the only in-session way to ingest new turns — without it you'd have to restart the server to see fresh usage. Instead I made the endpoint itself safe (incremental scanner.scan(), no unlink()) and reworded the tooltip to describe the additive behaviour, so the button keeps its useful job while losing its destructive one.

Also added a regression test (test_api_rescan_is_non_destructive) that seeds history with no on-disk JSONL and asserts it survives a rescan — it fails against the old code, so this won't regress.

Ships in v1.2.6. Since the safety fix is now on DEV (in slightly modified form), I'll let the maintainer decide whether to close this — but the substance of your report is fixed and credited. 🙏

[phuryn]

Landed in v1.2.6 (just released) — the safety fix is on main and shipped, credited to you via a Co-Authored-By trailer on 97e1d91. As noted above, the only divergence is that we kept the Rescan button and made the endpoint itself non-destructive, rather than removing the button. Closing since the substance of your report is fixed. Thanks again for catching this, @OtoGodfrey! 🙏