fix(server): report incomplete usage scans

[caezium]

What Changed

• Distinguish missing transcript roots from roots that cannot be read.
• Report nested listing/stat/file-read failures as partial coverage while retaining readable buckets.
• Keep failed reads out of the durable cache and avoid pruning unseen cache entries after partial walks.
• Preserve Claude's explicit-config, default nested, and legacy fallback layouts.
• Prefer the healthiest shared source across environments (ok > partial > failed) before deduplicating buckets.

Why

The scanner currently converts I/O failures into empty results and still reports status: "ok". That silently undercounts tokens and cost while claiming complete coverage; a weaker environment can also displace a healthy copy of the same source.

Closes#5798

Verification

• 47 focused server/web tests passed after review fixes.
• Targeted formatting and lint passed.
• Server and web typechecks passed; only pre-existing unrelated Effect suggestions remain.
• Branch rebased on current upstream/main.

Checklist

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

Implemented with gpt-5.6-sol in T3 Code through the Codex harness.

Note

Report incomplete usage scans with partial, failed, and missing source statuses

• listTranscriptFiles in usageTranscriptReader.ts now returns a structured TranscriptFileListing with rootStatus (ok | missing | failed) and a count of failedPaths instead of a plain array.
• readSummary in UsageService.ts uses this richer result to set source status to missing, failed, or partial with descriptive messages; previously all error cases silently produced empty results.
• readFileRecords now returns null on read failure instead of an empty array, so unreadable files are counted as failed rather than appearing as empty transcripts.
• claimSources in usageMerge.ts now assigns shared physical transcript directories to the environment with the best coverage (ok > partial > failed > missing) rather than the first by environment ID.
• Behavioral Change: sources that previously appeared as empty or were silently skipped now surface as partial or failed with explicit messages.

^{Macroscope summarized 8dd5bc2.}

---

Note

Medium Risk
Changes usage aggregation and multi-environment deduplication logic; incorrect status or merge rules could still misreport totals, but behavior is heavily covered by new server and web tests.

Overview
Usage scanning no longer treats I/O failures as empty transcripts with status: "ok". listTranscriptFiles returns a structured listing with missing vs failed roots and a count of paths that could not be walked or stat’d; readSummary maps those to source statuses and partial when some files read but others fail, with explicit “usage may be incomplete” messages.

Failed file reads return null instead of an empty record list so they are not cached as zero usage, and scan-cache pruning only runs after a complete directory walk so partial listings do not evict unseen cached paths. Claude transcript resolution is extracted as resolveClaudeTranscriptDir: explicit homes use projects directly; default installs probe .claude/projects and only fall back to legacy projects when the nested path is absent—probe errors keep the preferred path so unreadable roots surface as failed rather than missing at the legacy location.

On the web side, mergeUsage assigns duplicate physical sources to the environment with the best coverage (ok > partial > failed > missing) instead of the first environment by id.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01df9a9e-59a3-4f10-8894-c20df461a3d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[cursor]

Benign listing races mark scans partial

Medium Severity

Nested readdir and per-file stat failures always increment failedPaths, including ENOENT when a session file or directory disappears mid-walk. Root listing already treats ENOENT as missing, but nested races now force partial and keep the root out of walkedRoots, so normal transcript rotation can suppress cache pruning for the whole provider tree.

Additional Locations (1)

• apps/server/src/usage/UsageService.ts#L385-L388

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new runtime behavior for usage scan status tracking (partial/failed/ok/missing) and changes merge logic to prefer complete coverage over partial - this is behavioral change in billing-adjacent code that warrants human review. Additionally, there is an unresolved Medium severity finding about listing race conditions.

^{You can customize Macroscope's approvability policy. Learn more.}

[caezium]

What Changed

• Distinguish missing transcript roots from roots that cannot be read.
• Report nested listing/stat/file-read failures as partial coverage while retaining readable buckets.
• Keep failed reads out of the durable cache and avoid pruning unseen cache entries after partial walks.
• Preserve Claude's explicit-config, default nested, and legacy fallback layouts.
• Prefer the healthiest shared source across environments (ok > partial > failed) before deduplicating buckets.

Why

The scanner currently converts I/O failures into empty results and still reports status: "ok". That silently undercounts tokens and cost while claiming complete coverage; a weaker environment can also displace a healthy copy of the same source.

Closes#5798

Verification

• 47 focused server/web tests passed after review fixes.
• Targeted formatting and lint passed.
• Server and web typechecks passed; only pre-existing unrelated Effect suggestions remain.
• Branch rebased on current upstream/main.

Checklist

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

Implemented with gpt-5.6-sol in T3 Code through the Codex harness.

Note

Report incomplete usage scans with partial, failed, and missing source statuses

• listTranscriptFiles in usageTranscriptReader.ts now returns a structured TranscriptFileListing with rootStatus (ok | missing | failed) and a count of failedPaths instead of a plain array.
• readSummary in UsageService.ts uses this richer result to set source status to missing, failed, or partial with descriptive messages; previously all error cases silently produced empty results.
• readFileRecords now returns null on read failure instead of an empty array, so unreadable files are counted as failed rather than appearing as empty transcripts.
• claimSources in usageMerge.ts now assigns shared physical transcript directories to the environment with the best coverage (ok > partial > failed > missing) rather than the first by environment ID.
• Behavioral Change: sources that previously appeared as empty or were silently skipped now surface as partial or failed with explicit messages.

^{Macroscope summarized 8dd5bc2.}

---

Note

Medium Risk
Changes usage aggregation and multi-environment deduplication logic; incorrect status or merge rules could still misreport totals, but behavior is heavily covered by new server and web tests.

Overview
Usage scanning no longer treats I/O failures as empty transcripts with status: "ok". listTranscriptFiles returns a structured listing with missing vs failed roots and a count of paths that could not be walked or stat’d; readSummary maps those to source statuses and partial when some files read but others fail, with explicit “usage may be incomplete” messages.

Failed file reads return null instead of an empty record list so they are not cached as zero usage, and scan-cache pruning only runs after a complete directory walk so partial listings do not evict unseen cached paths. Claude transcript resolution is extracted as resolveClaudeTranscriptDir: explicit homes use projects directly; default installs probe .claude/projects and only fall back to legacy projects when the nested path is absent—probe errors keep the preferred path so unreadable roots surface as failed rather than missing at the legacy location.

On the web side, mergeUsage assigns duplicate physical sources to the environment with the best coverage (ok > partial > failed > missing) instead of the first environment by id.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01df9a9e-59a3-4f10-8894-c20df461a3d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[cursor]

Benign listing races mark scans partial

Medium Severity

Nested readdir and per-file stat failures always increment failedPaths, including ENOENT when a session file or directory disappears mid-walk. Root listing already treats ENOENT as missing, but nested races now force partial and keep the root out of walkedRoots, so normal transcript rotation can suppress cache pruning for the whole provider tree.

Additional Locations (1)

• apps/server/src/usage/UsageService.ts#L385-L388

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new runtime behavior for usage scan status tracking (partial/failed/ok/missing) and changes merge logic to prefer complete coverage over partial - this is behavioral change in billing-adjacent code that warrants human review. Additionally, there is an unresolved Medium severity finding about listing race conditions.

^{You can customize Macroscope's approvability policy. Learn more.}

[caezium]

What Changed

• Distinguish missing transcript roots from roots that cannot be read.
• Report nested listing/stat/file-read failures as partial coverage while retaining readable buckets.
• Keep failed reads out of the durable cache and avoid pruning unseen cache entries after partial walks.
• Preserve Claude's explicit-config, default nested, and legacy fallback layouts.
• Prefer the healthiest shared source across environments (ok > partial > failed) before deduplicating buckets.

Why

The scanner currently converts I/O failures into empty results and still reports status: "ok". That silently undercounts tokens and cost while claiming complete coverage; a weaker environment can also displace a healthy copy of the same source.

Closes#5798

Verification

• 47 focused server/web tests passed after review fixes.
• Targeted formatting and lint passed.
• Server and web typechecks passed; only pre-existing unrelated Effect suggestions remain.
• Branch rebased on current upstream/main.

Checklist

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

Implemented with gpt-5.6-sol in T3 Code through the Codex harness.

Note

Report incomplete usage scans with partial, failed, and missing source statuses

• listTranscriptFiles in usageTranscriptReader.ts now returns a structured TranscriptFileListing with rootStatus (ok | missing | failed) and a count of failedPaths instead of a plain array.
• readSummary in UsageService.ts uses this richer result to set source status to missing, failed, or partial with descriptive messages; previously all error cases silently produced empty results.
• readFileRecords now returns null on read failure instead of an empty array, so unreadable files are counted as failed rather than appearing as empty transcripts.
• claimSources in usageMerge.ts now assigns shared physical transcript directories to the environment with the best coverage (ok > partial > failed > missing) rather than the first by environment ID.
• Behavioral Change: sources that previously appeared as empty or were silently skipped now surface as partial or failed with explicit messages.

^{Macroscope summarized 8dd5bc2.}

---

Note

Medium Risk
Changes usage aggregation and multi-environment deduplication logic; incorrect status or merge rules could still misreport totals, but behavior is heavily covered by new server and web tests.

Overview
Usage scanning no longer treats I/O failures as empty transcripts with status: "ok". listTranscriptFiles returns a structured listing with missing vs failed roots and a count of paths that could not be walked or stat’d; readSummary maps those to source statuses and partial when some files read but others fail, with explicit “usage may be incomplete” messages.

Failed file reads return null instead of an empty record list so they are not cached as zero usage, and scan-cache pruning only runs after a complete directory walk so partial listings do not evict unseen cached paths. Claude transcript resolution is extracted as resolveClaudeTranscriptDir: explicit homes use projects directly; default installs probe .claude/projects and only fall back to legacy projects when the nested path is absent—probe errors keep the preferred path so unreadable roots surface as failed rather than missing at the legacy location.

On the web side, mergeUsage assigns duplicate physical sources to the environment with the best coverage (ok > partial > failed > missing) instead of the first environment by id.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01df9a9e-59a3-4f10-8894-c20df461a3d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[cursor]

Benign listing races mark scans partial

Medium Severity

Nested readdir and per-file stat failures always increment failedPaths, including ENOENT when a session file or directory disappears mid-walk. Root listing already treats ENOENT as missing, but nested races now force partial and keep the root out of walkedRoots, so normal transcript rotation can suppress cache pruning for the whole provider tree.

Additional Locations (1)

• apps/server/src/usage/UsageService.ts#L385-L388

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new runtime behavior for usage scan status tracking (partial/failed/ok/missing) and changes merge logic to prefer complete coverage over partial - this is behavioral change in billing-adjacent code that warrants human review. Additionally, there is an unresolved Medium severity finding about listing race conditions.

^{You can customize Macroscope's approvability policy. Learn more.}

[caezium]

What Changed

• Distinguish missing transcript roots from roots that cannot be read.
• Report nested listing/stat/file-read failures as partial coverage while retaining readable buckets.
• Keep failed reads out of the durable cache and avoid pruning unseen cache entries after partial walks.
• Preserve Claude's explicit-config, default nested, and legacy fallback layouts.
• Prefer the healthiest shared source across environments (ok > partial > failed) before deduplicating buckets.

Why

The scanner currently converts I/O failures into empty results and still reports status: "ok". That silently undercounts tokens and cost while claiming complete coverage; a weaker environment can also displace a healthy copy of the same source.

Closes#5798

Verification

• 47 focused server/web tests passed after review fixes.
• Targeted formatting and lint passed.
• Server and web typechecks passed; only pre-existing unrelated Effect suggestions remain.
• Branch rebased on current upstream/main.

Checklist

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

Implemented with gpt-5.6-sol in T3 Code through the Codex harness.

Note

Report incomplete usage scans with partial, failed, and missing source statuses

• listTranscriptFiles in usageTranscriptReader.ts now returns a structured TranscriptFileListing with rootStatus (ok | missing | failed) and a count of failedPaths instead of a plain array.
• readSummary in UsageService.ts uses this richer result to set source status to missing, failed, or partial with descriptive messages; previously all error cases silently produced empty results.
• readFileRecords now returns null on read failure instead of an empty array, so unreadable files are counted as failed rather than appearing as empty transcripts.
• claimSources in usageMerge.ts now assigns shared physical transcript directories to the environment with the best coverage (ok > partial > failed > missing) rather than the first by environment ID.
• Behavioral Change: sources that previously appeared as empty or were silently skipped now surface as partial or failed with explicit messages.

^{Macroscope summarized 8dd5bc2.}

---

Note

Medium Risk
Changes usage aggregation and multi-environment deduplication logic; incorrect status or merge rules could still misreport totals, but behavior is heavily covered by new server and web tests.

Overview
Usage scanning no longer treats I/O failures as empty transcripts with status: "ok". listTranscriptFiles returns a structured listing with missing vs failed roots and a count of paths that could not be walked or stat’d; readSummary maps those to source statuses and partial when some files read but others fail, with explicit “usage may be incomplete” messages.

Failed file reads return null instead of an empty record list so they are not cached as zero usage, and scan-cache pruning only runs after a complete directory walk so partial listings do not evict unseen cached paths. Claude transcript resolution is extracted as resolveClaudeTranscriptDir: explicit homes use projects directly; default installs probe .claude/projects and only fall back to legacy projects when the nested path is absent—probe errors keep the preferred path so unreadable roots surface as failed rather than missing at the legacy location.

On the web side, mergeUsage assigns duplicate physical sources to the environment with the best coverage (ok > partial > failed > missing) instead of the first environment by id.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01df9a9e-59a3-4f10-8894-c20df461a3d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[cursor]

Benign listing races mark scans partial

Medium Severity

Nested readdir and per-file stat failures always increment failedPaths, including ENOENT when a session file or directory disappears mid-walk. Root listing already treats ENOENT as missing, but nested races now force partial and keep the root out of walkedRoots, so normal transcript rotation can suppress cache pruning for the whole provider tree.

Additional Locations (1)

• apps/server/src/usage/UsageService.ts#L385-L388

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new runtime behavior for usage scan status tracking (partial/failed/ok/missing) and changes merge logic to prefer complete coverage over partial - this is behavioral change in billing-adjacent code that warrants human review. Additionally, there is an unresolved Medium severity finding about listing race conditions.

^{You can customize Macroscope's approvability policy. Learn more.}

[caezium]

What Changed

• Distinguish missing transcript roots from roots that cannot be read.
• Report nested listing/stat/file-read failures as partial coverage while retaining readable buckets.
• Keep failed reads out of the durable cache and avoid pruning unseen cache entries after partial walks.
• Preserve Claude's explicit-config, default nested, and legacy fallback layouts.
• Prefer the healthiest shared source across environments (ok > partial > failed) before deduplicating buckets.

Why

The scanner currently converts I/O failures into empty results and still reports status: "ok". That silently undercounts tokens and cost while claiming complete coverage; a weaker environment can also displace a healthy copy of the same source.

Closes#5798

Verification

• 47 focused server/web tests passed after review fixes.
• Targeted formatting and lint passed.
• Server and web typechecks passed; only pre-existing unrelated Effect suggestions remain.
• Branch rebased on current upstream/main.

Checklist

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

Implemented with gpt-5.6-sol in T3 Code through the Codex harness.

Note

Report incomplete usage scans with partial, failed, and missing source statuses

• listTranscriptFiles in usageTranscriptReader.ts now returns a structured TranscriptFileListing with rootStatus (ok | missing | failed) and a count of failedPaths instead of a plain array.
• readSummary in UsageService.ts uses this richer result to set source status to missing, failed, or partial with descriptive messages; previously all error cases silently produced empty results.
• readFileRecords now returns null on read failure instead of an empty array, so unreadable files are counted as failed rather than appearing as empty transcripts.
• claimSources in usageMerge.ts now assigns shared physical transcript directories to the environment with the best coverage (ok > partial > failed > missing) rather than the first by environment ID.
• Behavioral Change: sources that previously appeared as empty or were silently skipped now surface as partial or failed with explicit messages.

^{Macroscope summarized 8dd5bc2.}

---

Note

Medium Risk
Changes usage aggregation and multi-environment deduplication logic; incorrect status or merge rules could still misreport totals, but behavior is heavily covered by new server and web tests.

Overview
Usage scanning no longer treats I/O failures as empty transcripts with status: "ok". listTranscriptFiles returns a structured listing with missing vs failed roots and a count of paths that could not be walked or stat’d; readSummary maps those to source statuses and partial when some files read but others fail, with explicit “usage may be incomplete” messages.

Failed file reads return null instead of an empty record list so they are not cached as zero usage, and scan-cache pruning only runs after a complete directory walk so partial listings do not evict unseen cached paths. Claude transcript resolution is extracted as resolveClaudeTranscriptDir: explicit homes use projects directly; default installs probe .claude/projects and only fall back to legacy projects when the nested path is absent—probe errors keep the preferred path so unreadable roots surface as failed rather than missing at the legacy location.

On the web side, mergeUsage assigns duplicate physical sources to the environment with the best coverage (ok > partial > failed > missing) instead of the first environment by id.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01df9a9e-59a3-4f10-8894-c20df461a3d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[cursor]

Benign listing races mark scans partial

Medium Severity

Nested readdir and per-file stat failures always increment failedPaths, including ENOENT when a session file or directory disappears mid-walk. Root listing already treats ENOENT as missing, but nested races now force partial and keep the root out of walkedRoots, so normal transcript rotation can suppress cache pruning for the whole provider tree.

Additional Locations (1)

• apps/server/src/usage/UsageService.ts#L385-L388

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new runtime behavior for usage scan status tracking (partial/failed/ok/missing) and changes merge logic to prefer complete coverage over partial - this is behavioral change in billing-adjacent code that warrants human review. Additionally, there is an unresolved Medium severity finding about listing race conditions.

^{You can customize Macroscope's approvability policy. Learn more.}

[caezium]

What Changed

• Distinguish missing transcript roots from roots that cannot be read.
• Report nested listing/stat/file-read failures as partial coverage while retaining readable buckets.
• Keep failed reads out of the durable cache and avoid pruning unseen cache entries after partial walks.
• Preserve Claude's explicit-config, default nested, and legacy fallback layouts.
• Prefer the healthiest shared source across environments (ok > partial > failed) before deduplicating buckets.

Why

The scanner currently converts I/O failures into empty results and still reports status: "ok". That silently undercounts tokens and cost while claiming complete coverage; a weaker environment can also displace a healthy copy of the same source.

Closes#5798

Verification

• 47 focused server/web tests passed after review fixes.
• Targeted formatting and lint passed.
• Server and web typechecks passed; only pre-existing unrelated Effect suggestions remain.
• Branch rebased on current upstream/main.

Checklist

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

Implemented with gpt-5.6-sol in T3 Code through the Codex harness.

Note

Report incomplete usage scans with partial, failed, and missing source statuses

• listTranscriptFiles in usageTranscriptReader.ts now returns a structured TranscriptFileListing with rootStatus (ok | missing | failed) and a count of failedPaths instead of a plain array.
• readSummary in UsageService.ts uses this richer result to set source status to missing, failed, or partial with descriptive messages; previously all error cases silently produced empty results.
• readFileRecords now returns null on read failure instead of an empty array, so unreadable files are counted as failed rather than appearing as empty transcripts.
• claimSources in usageMerge.ts now assigns shared physical transcript directories to the environment with the best coverage (ok > partial > failed > missing) rather than the first by environment ID.
• Behavioral Change: sources that previously appeared as empty or were silently skipped now surface as partial or failed with explicit messages.

^{Macroscope summarized 8dd5bc2.}

---

Note

Medium Risk
Changes usage aggregation and multi-environment deduplication logic; incorrect status or merge rules could still misreport totals, but behavior is heavily covered by new server and web tests.

Overview
Usage scanning no longer treats I/O failures as empty transcripts with status: "ok". listTranscriptFiles returns a structured listing with missing vs failed roots and a count of paths that could not be walked or stat’d; readSummary maps those to source statuses and partial when some files read but others fail, with explicit “usage may be incomplete” messages.

Failed file reads return null instead of an empty record list so they are not cached as zero usage, and scan-cache pruning only runs after a complete directory walk so partial listings do not evict unseen cached paths. Claude transcript resolution is extracted as resolveClaudeTranscriptDir: explicit homes use projects directly; default installs probe .claude/projects and only fall back to legacy projects when the nested path is absent—probe errors keep the preferred path so unreadable roots surface as failed rather than missing at the legacy location.

On the web side, mergeUsage assigns duplicate physical sources to the environment with the best coverage (ok > partial > failed > missing) instead of the first environment by id.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01df9a9e-59a3-4f10-8894-c20df461a3d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[cursor]

Benign listing races mark scans partial

Medium Severity

Nested readdir and per-file stat failures always increment failedPaths, including ENOENT when a session file or directory disappears mid-walk. Root listing already treats ENOENT as missing, but nested races now force partial and keep the root out of walkedRoots, so normal transcript rotation can suppress cache pruning for the whole provider tree.

Additional Locations (1)

• apps/server/src/usage/UsageService.ts#L385-L388

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new runtime behavior for usage scan status tracking (partial/failed/ok/missing) and changes merge logic to prefer complete coverage over partial - this is behavioral change in billing-adjacent code that warrants human review. Additionally, there is an unresolved Medium severity finding about listing race conditions.

^{You can customize Macroscope's approvability policy. Learn more.}

[caezium]

What Changed

• Distinguish missing transcript roots from roots that cannot be read.
• Report nested listing/stat/file-read failures as partial coverage while retaining readable buckets.
• Keep failed reads out of the durable cache and avoid pruning unseen cache entries after partial walks.
• Preserve Claude's explicit-config, default nested, and legacy fallback layouts.
• Prefer the healthiest shared source across environments (ok > partial > failed) before deduplicating buckets.

Why

The scanner currently converts I/O failures into empty results and still reports status: "ok". That silently undercounts tokens and cost while claiming complete coverage; a weaker environment can also displace a healthy copy of the same source.

Closes#5798

Verification

• 47 focused server/web tests passed after review fixes.
• Targeted formatting and lint passed.
• Server and web typechecks passed; only pre-existing unrelated Effect suggestions remain.
• Branch rebased on current upstream/main.

Checklist

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

Implemented with gpt-5.6-sol in T3 Code through the Codex harness.

Note

Report incomplete usage scans with partial, failed, and missing source statuses

• listTranscriptFiles in usageTranscriptReader.ts now returns a structured TranscriptFileListing with rootStatus (ok | missing | failed) and a count of failedPaths instead of a plain array.
• readSummary in UsageService.ts uses this richer result to set source status to missing, failed, or partial with descriptive messages; previously all error cases silently produced empty results.
• readFileRecords now returns null on read failure instead of an empty array, so unreadable files are counted as failed rather than appearing as empty transcripts.
• claimSources in usageMerge.ts now assigns shared physical transcript directories to the environment with the best coverage (ok > partial > failed > missing) rather than the first by environment ID.
• Behavioral Change: sources that previously appeared as empty or were silently skipped now surface as partial or failed with explicit messages.

^{Macroscope summarized 8dd5bc2.}

---

Note

Medium Risk
Changes usage aggregation and multi-environment deduplication logic; incorrect status or merge rules could still misreport totals, but behavior is heavily covered by new server and web tests.

Overview
Usage scanning no longer treats I/O failures as empty transcripts with status: "ok". listTranscriptFiles returns a structured listing with missing vs failed roots and a count of paths that could not be walked or stat’d; readSummary maps those to source statuses and partial when some files read but others fail, with explicit “usage may be incomplete” messages.

Failed file reads return null instead of an empty record list so they are not cached as zero usage, and scan-cache pruning only runs after a complete directory walk so partial listings do not evict unseen cached paths. Claude transcript resolution is extracted as resolveClaudeTranscriptDir: explicit homes use projects directly; default installs probe .claude/projects and only fall back to legacy projects when the nested path is absent—probe errors keep the preferred path so unreadable roots surface as failed rather than missing at the legacy location.

On the web side, mergeUsage assigns duplicate physical sources to the environment with the best coverage (ok > partial > failed > missing) instead of the first environment by id.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01df9a9e-59a3-4f10-8894-c20df461a3d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[cursor]

Benign listing races mark scans partial

Medium Severity

Nested readdir and per-file stat failures always increment failedPaths, including ENOENT when a session file or directory disappears mid-walk. Root listing already treats ENOENT as missing, but nested races now force partial and keep the root out of walkedRoots, so normal transcript rotation can suppress cache pruning for the whole provider tree.

Additional Locations (1)

• apps/server/src/usage/UsageService.ts#L385-L388

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new runtime behavior for usage scan status tracking (partial/failed/ok/missing) and changes merge logic to prefer complete coverage over partial - this is behavioral change in billing-adjacent code that warrants human review. Additionally, there is an unresolved Medium severity finding about listing race conditions.

^{You can customize Macroscope's approvability policy. Learn more.}

[caezium]

What Changed

• Distinguish missing transcript roots from roots that cannot be read.
• Report nested listing/stat/file-read failures as partial coverage while retaining readable buckets.
• Keep failed reads out of the durable cache and avoid pruning unseen cache entries after partial walks.
• Preserve Claude's explicit-config, default nested, and legacy fallback layouts.
• Prefer the healthiest shared source across environments (ok > partial > failed) before deduplicating buckets.

Why

The scanner currently converts I/O failures into empty results and still reports status: "ok". That silently undercounts tokens and cost while claiming complete coverage; a weaker environment can also displace a healthy copy of the same source.

Closes#5798

Verification

• 47 focused server/web tests passed after review fixes.
• Targeted formatting and lint passed.
• Server and web typechecks passed; only pre-existing unrelated Effect suggestions remain.
• Branch rebased on current upstream/main.

Checklist

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

Implemented with gpt-5.6-sol in T3 Code through the Codex harness.

Note

Report incomplete usage scans with partial, failed, and missing source statuses

• listTranscriptFiles in usageTranscriptReader.ts now returns a structured TranscriptFileListing with rootStatus (ok | missing | failed) and a count of failedPaths instead of a plain array.
• readSummary in UsageService.ts uses this richer result to set source status to missing, failed, or partial with descriptive messages; previously all error cases silently produced empty results.
• readFileRecords now returns null on read failure instead of an empty array, so unreadable files are counted as failed rather than appearing as empty transcripts.
• claimSources in usageMerge.ts now assigns shared physical transcript directories to the environment with the best coverage (ok > partial > failed > missing) rather than the first by environment ID.
• Behavioral Change: sources that previously appeared as empty or were silently skipped now surface as partial or failed with explicit messages.

^{Macroscope summarized 8dd5bc2.}

---

Note

Medium Risk
Changes usage aggregation and multi-environment deduplication logic; incorrect status or merge rules could still misreport totals, but behavior is heavily covered by new server and web tests.

Overview
Usage scanning no longer treats I/O failures as empty transcripts with status: "ok". listTranscriptFiles returns a structured listing with missing vs failed roots and a count of paths that could not be walked or stat’d; readSummary maps those to source statuses and partial when some files read but others fail, with explicit “usage may be incomplete” messages.

Failed file reads return null instead of an empty record list so they are not cached as zero usage, and scan-cache pruning only runs after a complete directory walk so partial listings do not evict unseen cached paths. Claude transcript resolution is extracted as resolveClaudeTranscriptDir: explicit homes use projects directly; default installs probe .claude/projects and only fall back to legacy projects when the nested path is absent—probe errors keep the preferred path so unreadable roots surface as failed rather than missing at the legacy location.

On the web side, mergeUsage assigns duplicate physical sources to the environment with the best coverage (ok > partial > failed > missing) instead of the first environment by id.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 01df9a9e-59a3-4f10-8894-c20df461a3d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[cursor]

Benign listing races mark scans partial

Medium Severity

Nested readdir and per-file stat failures always increment failedPaths, including ENOENT when a session file or directory disappears mid-walk. Root listing already treats ENOENT as missing, but nested races now force partial and keep the root out of walkedRoots, so normal transcript rotation can suppress cache pruning for the whole provider tree.

Additional Locations (1)

• apps/server/src/usage/UsageService.ts#L385-L388

^{Reviewed by Cursor Bugbot for commit 8dd5bc2. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new runtime behavior for usage scan status tracking (partial/failed/ok/missing) and changes merge logic to prefer complete coverage over partial - this is behavioral change in billing-adjacent code that warrants human review. Additionally, there is an unresolved Medium severity finding about listing race conditions.

^{You can customize Macroscope's approvability policy. Learn more.}