fix(server): include Claude advisor calls in usage totals

[LukasWallrich]

The problem

The usage dashboard provides clarity on token usage through the harnesses across interfaces. Even though T3 Code does not yet support Claude's advisor mode (see #9640), cost incurred through that in Claude Code should show up in the usage tracker here so that the numbers are accurate.

What Changed

The Usage dashboard now includes Claude advisor calls as separate usage records, priced at the advisor model's rates. Executor usage remains counted once, and advisor records use distinct keys so repeated content blocks and copied transcripts do not multiply their usage. The scan cache version is bumped to reprocess existing transcripts.

Why

Claude reports advisor sub-inferences in usage.iterations with type: "advisor_message". Those tokens are excluded from top-level executor usage (Anthropic documentation). The parser previously ignored them, so advisor tokens and estimated costs were absent from the Usage dashboard.

Related: #9640 explicitly leaves advisor token/cost attribution outside its scope. This change is limited to transcript-based Usage reporting.

Validation

• 76 tests pass across the usage parser, transcript reader, scan cache, aggregation, pricing, and Usage service suites.
• Regression coverage includes multiple advisor calls, cached tokens, malformed and empty entries, per-model pricing, resumed scans, duplicate content blocks, copied transcripts, and invalidation of the previous cache version.
• Targeted lint and formatting checks pass; server typecheck passes.
• Independent Fable review approved the final diff with no blocking findings.

Checklist

• This PR is small and focused
• I explained what changed and why

Written by GPT-6 in Codex. Reviewed by Claude Fable through Claude Code (claude -p --model fable).

Note

Include Claude advisor calls in usage totals via parseClaudeLine

• Refactors parseClaudeLine in usageTranscripts.ts to return a read-only list of usage records instead of a single nullable record, emitting separate nonzero-token advisor records from nested iterations with distinct deduplication keys
• Reported cost stays on the executor record; advisor records inherit transcript metadata and their own token totals from their iteration
• Updates usageTranscriptReader.ts to append every record returned for a Claude line instead of at most one
• Bumps usage scan cache schema version from 3 to 4 in usageScanCache.ts to force re-parsing of existing transcripts
• Behavioral Change: version-3 cache entries are treated as stale; old caches are rebuilt on next scan

^{Macroscope summarized e8cb5ed.}

Summary by CodeRabbit

• Bug Fixes

  • Claude usage tracking now includes advisor iterations with separate token totals and model attribution.
  • Usage totals and pricing remain accurate when transcripts contain resumed or repeated messages.
  • Invalid or incomplete transcript entries are handled more reliably without disrupting usage processing.

• Improvements

  • Existing Claude usage data is reprocessed to apply the updated accounting behavior.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-07T09:51:09.096191Z	e8cb5ed	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[macroscopeapp]

Approvability

Verdict: Approved at e8cb5ed

Macroscope's review found this PR approvable — This focused fix corrects Claude usage totals by parsing advisor records through the existing aggregation and pricing pipeline, with cache invalidation and substantial regression coverage. Its runtime impact is confined to usage reporting and the expected one-time re-scan of stale cached transcripts.

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 6a8a3235-36ee-4566-b1df-acec76fe35cd

📥 Commits

Reviewing files that changed from the base of the PR and between e8cb5ed and 38858d8.

📒 Files selected for processing (1)

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

🚧 Files skipped from review as they are similar to previous changes (1)

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

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The Claude transcript parser now emits separate executor and advisor usage records. The transcript reader handles multiple records per line. Cache version 4 re-parses existing Claude transcripts, and tests validate deduplication and pricing.

Changes

Claude usage parsing

Layer / File(s)	Summary
Parse executor and advisor records apps/server/src/usage/usageTranscripts.ts, apps/server/src/usage/usageTranscripts.test.ts	parseClaudeLine returns arrays with executor and valid advisor records. Advisor records include separate models, token totals, and deduplication keys. Invalid and zero-token advisor entries are skipped.
Integrate records and refresh cache apps/server/src/usage/usageTranscriptReader.ts, apps/server/src/usage/usageTranscriptReader.test.ts, apps/server/src/usage/usageScanCache.ts, apps/server/src/usage/usageScanCache.test.ts	The transcript reader appends all parsed Claude records. Integration tests validate resume handling, deduplication, aggregation, and pricing. Cache version 4 re-parses existing Claude transcripts.

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

Merge Risk: ⚪ Minimal · up to 38858

This updates Usage reporting to include distinct Claude advisor records alongside executor usage. No current merge-blocking risk is identified.

Sequence Diagram(s)

sequenceDiagram
  participant TranscriptReader
  participant parseClaudeLine
  participant UsageAggregator
  TranscriptReader->>parseClaudeLine: Parse Claude line
  parseClaudeLine-->>TranscriptReader: Return executor and advisor records
  TranscriptReader->>UsageAggregator: Aggregate parsed records

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: adding Claude advisor calls to server usage totals.
Description check	✅ Passed	The description explains the problem, change, rationale, validation, scope, and checklist. It is mostly complete and matches the required template; the UI Changes section is correctly omitted because …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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