[juliusmarminge]

Stacked on https://git.cafe/pingdotgg/t3code/pulls/29724.

After a restart with a cold or stale scan cache, the first server.getUsageSummary paid for parsing every changed transcript while the user waited: p50 8.6s and p95 34s on a fresh install. The per-file scan cache is persisted, so this work only has to happen once per new or changed file, and it can happen before anyone opens the usage page.

Change

• UsageService.warmScanCache resolves the transcript directories and parses the default 30-day window (31 days, to cover the client's local-midnight start) into the scan cache, then persists it. It only covers transcript directories; account-based scan readers (Cursor, etc.) still run on request because they make network calls.
• UsageService.layerWarmup forks it with forkParked, so it starts only after server activation and never delays readiness. It is wired in next to the other post-activation background layers in server.ts. Parsing runs in the layer-1 child processes, so the server's main thread stays mostly idle.
• A summary that arrives during the warm-up waits for it (a new UsageService.awaitWarmup span) and then reads the warmed cache, instead of parsing the same files a second time. The warm-up skips itself if a summary is already in flight, because that summary warms the cache anyway. Later restarts only parse files that are new or grew.

Before / after

On cups, against the real ~/.claude + ~/.codex data (3,779 files, 292k records, 30-day window):

• before: the first summary after a cold start parses everything: 7.8–10.9s wall with layer 1, 10.3–12.7s without it.
• after: that parse runs in the background right after activation. Once it finishes, a summary does the file walk and stat (175–300 ms for 3,802 files), cache lookups, and aggregation, and parses only files that changed since the warm-up.

Tests

A new UsageService.test.ts case:

• builds the warm-up layer while activation is still pending. The build returns, so startup does not wait, and nothing has been parsed yet.
• completes activation and gates the warm-up's parse on a Deferred.
• starts a summary and races "summary waits on the warm-up" (observed via the span) against "summary starts its own parse". It asserts the file was parsed only once, then that the summary totals are correct. Without the wait, the test fails with two parses of the same file.

No sleeps or polling.

Scope and approval: maintainer-approved direction from the 2026-11-02 fleet trace audit

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Approved at 6806f5b

Macroscope's review found this PR approvable — Warms the existing usage cache after server activation and shares that work with concurrent summaries. The change reuses existing parsing and persistence paths without changing usage defaults or source transcripts.

No code changes detected at b581f66. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Codex	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Codex	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Codex	Live turn WebSocket decoded	—	21.6 KiB	—	24.4 KiB	✅
Codex	Live turn messages	—	2	—	8	✅
Claude	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Claude	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Claude	Live turn WebSocket wire	—	1.3 KiB	—	2.0 KiB	✅
Claude	Live turn WebSocket decoded	—	21.9 KiB	—	24.4 KiB	✅
Claude	Live turn messages	—	2	—	8	✅

Baseline: unavailable · PR result: b581f66 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

Dismissing prior approval to re-evaluate b7aa3ff

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: pingdotgg/t3code
• Branch: t3/usage-warm-scan-cache
• File: .coderabbit.config.ts
• Commit: b581f66
• Layers: Repository TS config
• Review profile: CHILL
• Plan: Team
• Run ID: 66f5796f-6511-42fc-8999-b284c5b6b5d3

Commits

Reviewing files that changed from the base of the PR and between b7aa3ff and b581f66.

Files selected for processing: 2

• apps/server/src/usage/UsageService.test.ts
• apps/server/src/usage/UsageService.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

Walkthrough

UsageService now warms its scan cache with transcripts from the prior 31 days after server activation. Summary scans coordinate with warm-up, and rate loading starts while a summary waits. Tests cover activation gating, shared parsing, and scanning older transcripts omitted by a shorter summary window.

Changes: Usage cache warm-up

Layer / File(s)	Summary
Cache scanning and coordination apps/server/src/usage/UsageService.ts	UsageService adds a 31-day cache warm-up scan and shared completion state. Summary scans wait for active warm-up, while rate loading can proceed during that wait. Warm-up loads the scan cache and settings, scans transcript directories, schedules persistence, and logs failures.
Activation and server wiring apps/server/src/usage/UsageService.ts, apps/server/src/server.ts, apps/server/src/usage/UsageService.test.ts	The server application includes the warm-up layer. The layer starts warm-up after activation without blocking its launch. Tests cover activation gating, shared parsing, and scanning an older transcript omitted by a one-day summary.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Sequence Diagram(s)

sequenceDiagram
  participant ServerActivation
  participant layerWarmup
  participant UsageService
  participant scanSummary
  ServerActivation->>layerWarmup: releases activation
  layerWarmup->>UsageService: starts warmScanCache
  scanSummary->>UsageService: waits while warm-up is active
  UsageService->>scanSummary: signals warm-up completion

Loading

Possibly related issues

• [Bug]: OpenCode usage scan takes ~5 min on a large OpenCode 2 database, repeats on every refresh and stalls the server #28430 — The change adds scan-cache warm-up, which relates to the report of repeated, slow usage scans. The retrieved issue summary notes that OpenCode account-based readers may remain outside this warm-up path.

Possibly related PRs

• pingdotgg/t3code#21776 — This PR adds the warm-up layer to the startup activation wiring introduced there.
• pingdotgg/t3code#28111 — This PR warms the scan cache using the 31-day window and settings used by the retention behavior changed there.
• pingdotgg/t3code#29724 — This PR starts cache warm-up through UsageService and exercises the parser-backed scan implementation added there.

Suggested reviewers: maria-rcks, t3dotgg, pixpmusic

Merge Risk: Minimal · up to b581f

The startup cache warm-up remains active, and the previously reported delays have been addressed. No actionable merge-blocking risk remains after normal checks.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: warming the server usage scan cache after startup.
Description check		The description explains the problem, implementation, scope approval, performance impact, and focused tests. It uses a "Tests" heading instead of the required "Verification" heading, but the required …
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description explains the problem, implementation, scope approval, performance impact, and focused tests. It uses a "Tests" heading instead of the required "Verification" heading, but the required verification details are present.

Finishing Touches

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

CodeRabbit Verify

• Run CodeRabbit Verify to test the changes in this pull request.

[coderabbitai]

• Fix comments: Fix CodeRabbit comments on this PR

Dismissing prior approval to re-evaluate 6806f5b