[Bug]: Usage scans report complete coverage after transcript read failures
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 23k
- Forks
- 5.9k
- Avg merge
- 11h 14m
- Merged PRs (30d)
- 357
Description
Before submitting
- I searched existing issues and did not find a duplicate.
- I included enough detail to reproduce or investigate the problem.
Area
apps/server
Steps to reproduce
- Configure Claude Code or Codex with an existing transcript directory containing at least one readable
.jsonlusage transcript. - Make a nested transcript directory unreadable, or make one listed
.jsonltranscript unreadable before requesting a usage summary. - Request the usage summary from the Usage page or
server.getUsageSummaryRPC. - Inspect the matching
UsageSourceentry.
Expected behavior
The scan should retain usage from readable transcripts while reporting incomplete coverage deterministically. A root that cannot be listed should report failed; a nested directory, entry, or transcript read failure should report partial, with a bounded diagnostic that makes the omitted coverage visible. A missing transcript root should remain distinct from an unreadable one.
Actual behavior
listTranscriptFiles swallows directory and entry errors, and readTranscriptRecords returns null on a read failure. UsageService then converts failed file reads to empty record arrays, increments skippedFiles, and always reports an existing source as status: "ok" with malformedRecords: 0 and message: null. The returned buckets can therefore omit usage while the source claims complete coverage.
Impact
Major degradation or frequent failure
Usage and API-equivalent cost totals can silently undercount on permission errors, transient file races, filesystem faults, or unreadable nested directories. Because the source remains ok, callers cannot distinguish a trustworthy zero/partial result from an incomplete scan.
Version or commit
main @ 963ebf5bd7cce00d40ff60c258b34c12dcab271e
Environment
Provider transcript scans on any supported server environment; observed from source on macOS with Bun.
Logs or stack traces
No error is logged or returned; the failure is currently swallowed.
Screenshots, recordings, or supporting files
Not applicable; this is backend response correctness.
Workaround
Verify transcript directory/file readability out of band and retry the scan. The usage response itself does not reveal when this is necessary.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing listTranscriptFiles and readTranscriptRecords into UsageService, then inspect the UsageSource returned by the server.getUsageSummary RPC. Reproduce failures with unreadable roots, nested directories, entries, and transcripts. Done means readable usage is retained, coverage reports failed or partial deterministically, missing roots remain distinct, and diagnostics are bounded.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, backend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100