feat(usage): add thread and subagent breakdown

[saphid]

What Changed

The Usage page can drill a project, provider, or model total down to its originating threads and expandable subagent rows, including daily cost components. The server maps provider sessions and dedicated worktrees to T3 threads, keeps final progressive snapshots, and returns typed failures when attribution data cannot be read instead of inventing rows.

Why

Aggregate spend identifies what was used but not which conversation produced it. Thread attribution makes unexpected cost traceable while preserving project boundaries, platform-specific path behavior, row caps, and the same immutable records and read time used by the summary.

Stack and Review Scope

This PR is cumulative and lands after #9015. Review the thread/subagent increment; later PRs include this stack.

Verification

Current candidate a67d8f25442c06f9caec12d6173d96256a6130e6 includes upstream main 39802c06117fae0b3da43624b0d54309c5437c72. The focused UsageService and chart-gesture suites passed (36 tests), and the server package typecheck passed. Repository failure doubles follow the current imported-transcript interface. Earlier evidence below retains its stated revision and scope; integrated web evidence and its attribution limits are described below.

A direct Claude Opus 5 high review attempt for this integration batch exited 1 because OAuth expired; no Claude review occurred.

Candidate: c3dab9986a533784af56cfca5ebd3f381b21cd25, including upstream main 82c2b7ffb4d450572f5baf9a70693f1e25cfdfed.

• The full focused contribution check at ba873b8 passed 171 tests across 12 files, plus the affected package typechecks.
• The final 82c2b7f delta removes an unused pricing helper: 7 pricing tests, server typecheck, Knip and git diff --check passed on the pre-repair main composition. The chart/runtime contribution was unchanged by that final delta.
• The chart merge preserves upstream's live column builder and this PR's daily/hourly and range behavior. Fresh independent source review of the shared resolution found no actionable issues.

Focused commands

vp test run apps/server/src/usage/UsageService.test.ts apps/server/src/usage/usageAggregation.test.ts apps/server/src/usage/usagePaths.test.ts apps/server/src/usage/usageScanCache.test.ts apps/server/src/usage/usageThreads.test.ts apps/server/src/usage/usageTranscriptReader.test.ts apps/web/src/components/usage/UsagePage.test.tsx apps/web/src/components/usage/UsageThreadTable.test.tsx apps/web/src/state/usage.test.ts packages/shared/src/usageMerge.test.ts apps/web/src/components/usage/UsageProviderChart.test.ts
vp run --filter t3 typecheck
vp run --filter @t3tools/web typecheck
vp run --filter @t3tools/client-runtime typecheck
vp run --filter @t3tools/contracts typecheck
vp run --filter @t3tools/shared typecheck
vp test run apps/server/src/usage/usagePricing.test.ts
vp run --filter t3 typecheck

Refresh correctness checks

The refresh repair passed the focused UsageService suite (16 tests), 3 chart-gesture regression tests, and 8 web usage-state tests. After the final thread-cache guard, 2 affected service tests were rerun and passed; the earlier full-suite count is not presented as a new full-suite run. The optional thread-refresh contract passed 2 schema tests and the contracts package typecheck. Server and web package typechecks, changed-file formatting/lint and diff checks passed. Independent source review found no actionable issue in this frozen repair.

These repairs cancel a chart gesture if its date window changes, let each environment progress after its own pricing request, and coalesce concurrent tokened summary scans. Thread-enabled branches await their environment summary before refreshing thread rows. The source-scan revision guard prevents older aggregation from pruning files discovered by a newer scan. Integrated web evidence and remaining client limits are described below.

UI Changes

The thread breakdown lists three conversations, expands checkout into daily cost and the accessibility subagent, and collapses back to summary rows. The integration retains this PR’s open-row/toggle behavior; later stack changes add navigation controls and cache-write columns.

Before: upstream main 39802c06117fae0b3da43624b0d54309c5437c72. After: cumulative #9308 integration 7e248026469ec7be6d5c2bdaccf86f380e0c2476, captured in an isolated web preview with two synthetic projects, three conversations and generated transcripts. This reuses the retained feature in the integrated stack; it is not a separate capture of this PR’s individual head. Focused tests above were run on the individual published head. The 30-day preset ends at the last complete day on the integration; main includes the current day. Both captures contain the same fourteen days of synthetic usage.

Clean breakdown recording · Annotated breakdown recording. This shows project → thread → expand → collapse; idle time is trimmed from 109.7 s to 12.57 s, without a performance claim.

Limits: The fixture uses a single environment. Cross-environment attribution, truncation and failure paths remain covered by focused tests rather than this recording. No React Native or SwiftUI mobile capture is represented here. Clean/annotated packet validation passed; uploaded derivatives were retrieved and hash-verified.

Checklist

• The intended increment is focused; its cumulative dependencies are identified above.
• I explained what changed and why.
• Integrated before/after screenshots are attached and their revisions are identified.
• Integrated thread expansion/collapse recording is attached; source attribution and limits are stated.

Implemented and reviewed with GPT-6 and GPT-5.6 Sol in the Codex harness. A direct Claude Opus 5 high availability attempt exited 1 because OAuth had expired; no Opus review occurred.

Note

Add thread, subagent, and project breakdowns to usage tracking

• Adds readThreadBreakdown to UsageService and server.getUsageThreadBreakdown RPC to return per-thread and subagent token/cost totals.
• Adds project attribution to usage aggregation and the UsagePage UI to filter usage by specific projects or outside-project usage.
• Tracks cwd in UsageRecord and the usage scan cache to support project resolution. Bumps USAGE_CONTRACT_VERSION to 9.
• Adds custom date ranges up to 90 days and pointer-drag zoom to the daily UsageProviderChart.
• Risk: USAGE_SCAN_CACHE_VERSION bump to 4 invalidates older usage scan caches. dedupeWithinFile logic changed to retain the final record per key instead of the first, altering token counts for mixed progressive/complete transcripts.

^{Macroscope summarized a67d8f2.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4b516fe. Configure here.}