fix(server): report incomplete transcript usage scans

[maria-rcks]

Transcript listing, stat, and read failures silently dropped usage while the source still reported ok.

listTranscriptFiles now counts directories and files it could not read (files that vanish mid-walk are still treated as normal rotation). The usage service adds unreadable transcripts to that count and marks the source partial with a message. Cached usage for those files is still counted, and the next healthy scan returns to ok.

Refs #5798. Adapts the scan-health idea from #5812 and #7221.

Verification (Blacksmith, non-root): apps/server/src/usage/ 106 tests passed, including a new case that makes one transcript unreadable, expects partial with the readable usage, then restores it and expects ok. Server typecheck and scoped lint passed (one pre-existing unused layerTest warning). Windows/macOS behavior is unverified.

Written by claude-opus-5-5 via Claude Code in T3 Code

[macroscopeapp]

Approvability

Verdict: Approved at 6fd2a9d

Macroscope's review found this PR approvable — This is a localized usage-scanning bug fix that reports incomplete transcript reads through an already supported partial status while preserving cached totals and normal scan behavior. It includes focused coverage for unreadable-file recovery and introduces no schema, deployment, security, billing, default, or static-analysis changes.

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

[coderabbitai]

Warning

Review limit reached

Only developers with an assigned seat can use this organization's usage-based review budget, and seats here are assigned manually. Ask an admin to assign a seat, or change the review continuation mode in Billing.

Next included review available in 16 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3e7f216a-8833-4901-8ca6-5fdb389e22fa

---

📥 Commits

Reviewing files that changed from the base of the PR and between 0d95b24 and 6fd2a9d.

---

📒 Files selected for processing (3)

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

---

---

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: d9f9e32e-b5b9-4060-9e6b-3a16cc7fedf5

---

📥 Commits

Reviewing files that changed from the base of the PR and between 4ee6bfd and 0d95b24.

---

📒 Files selected for processing (4)

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

---

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

---

---

📝 Walkthrough

Walkthrough

Transcript discovery now reports root and path failures. Usage scans retain readable or cached records and report partial or failed status. Tests cover permission failures and recovery.

Changes

Usage scan health

Layer / File(s)	Summary
Transcript listing results and failure counts apps/server/src/usage/usageTranscriptReader.ts, apps/server/src/usage/usageTranscriptReader.test.ts	listTranscriptFiles returns readable files with root status and a count of failed paths. Tests cover missing and invalid roots, symlinks, and filename filtering.
Usage scan status and cached records apps/server/src/usage/UsageService.ts, apps/server/src/usage/UsageService.test.ts	Usage scans retain cached records after transcript read failures. They report failed status for root failures, partial status for path failures, and ok status when no failures occur. Tests cover permission restoration, scan recovery, and the updated filesystem probe.

Priority: ➖ Normal

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

Change: Bug fix

Suggested reviewers: t3dotgg

---

Merge Risk: ⚪ Minimal · up to 0d95b

Transcript scan failures are reported without discarding available usage. No actionable merge-blocking issue remains after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 0d95b

The change makes incomplete usage scans more visible without an identified expansion of filesystem access or request authority. Readable and cached usage remain available during failures. Deployment permissions and integrated client behavior remain unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected impact is bounded to usage derived from configured provider transcript directories on the server's host and the summaries returned to usage callers. No broader asset or environment authority is established by the new listing fields; actual filesystem exposure still depends on deployment permissions.

Trust Boundaries and Controls

• observed — The usage-summary WebSocket handler delegates to readSummary. In the inspected scan path, transcript directories are resolved from server/provider settings and host environment rather than accepted as filesystem paths from the summary request.

Resilience and Maintainability Implications

• observed — The current consumer preserves walk-order cache publication and guards against older overlapping reads replacing newer entries. Persistence is serialized and failed writes restore the dirty flag. Identical requests share detached scan work, with terminal cleanup completing waiting callers even when an individual caller departs.

---

---

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check		The title clearly summarizes the main change: reporting incomplete transcript usage scans in the server.
Description check		The description explains the problem, the implementation, references the related issue, and reports focused verification results. It does not use the required section headings and does not provide exp…

---

---

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

---

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

---

_{Comment @coderabbitai help to get the list of available commands.}

Dismissing prior approval to re-evaluate 643fdcd

Dismissing prior approval to re-evaluate 6fd2a9d