perf(server): scan only appended transcript bytes for usage summaries

[StiensWout]

Problem

Opening the usage page re-parses any transcript that changed since the last scan from byte 0. The file most likely to have changed is the rollout the user is actively working in, which is also the largest file in the window (1.2 GB rollouts in the wild, see #7088). That makes warm scans cost tens of seconds, on every environment, every time the 60s client cache expires. Field traces in #7088 show 20-60 s warm and up to 7.3 min cold server.getUsageSummary calls.

Solution

Transcripts are append-only, so the scan cache (bumped to v3) now persists a byte-exact parse position per file: resume offset, a 64-byte guard fingerprint, and the Codex reducer state. A file that merely grew parses only its appended bytes; the guard verifies the append-only assumption and any mismatch (rotation, truncation, rewrite) falls back to a full re-parse. Records from a trailing unterminated line are cached separately so completing that line later never double counts.

Two smaller wins ride along, both part of the same investigation:

• Concurrent identical summary requests (usage page open on desktop and phone at once) share one scan instead of racing over the same corpus twice.
• The LiteLLM rate-table fetch runs concurrently with the transcript walk instead of gating it, so a cold fetch on a slow network no longer adds its own delay to the scan.

The reader also switched from readline to buffer-level line splitting (needed for byte-exact offsets), which turned out to make cold parses faster as well.

Proof

Measured against real transcripts (356 files, 318 MB, 30-day window; the largest rollout is 61 MB):

Scenario	Before	After
Warm rescan of the 61 MB rollout after one appended turn	1,247 ms (full re-parse)	3.3 ms (resumed)
Cold parse of the full 30-day corpus	4,309 ms	2,634 ms

Parity check: old and new readers produce byte-identical record sets on all 356 real transcripts (0 mismatches), and the stitched incremental result equals a from-scratch parse of the grown file.

vp test run apps/server/src/usage: 6 files, 64 tests, all passing, including new coverage for resume, guard mismatch, truncation, Codex state carried across the resume boundary, unterminated-tail handling, and scan sharing between concurrent requests.

Related issues: #7088 (this addresses the warm-scan cost; the ~/projects fallback stays with #7177), #5798, #5805.

Implemented by Claude (Fable 5) via Claude Code.

---

Note

Medium Risk
Changes core usage scanning, caching, and concurrency paths where incorrect resume or dedupe logic could misreport token totals; mitigated by guard fallbacks, strict cache decode, and broad new tests.

Overview
Warm usage scans no longer re-read entire transcript files when they only grew. The scan cache (now v3) stores a byte resume point, a 64-byte guard fingerprint, optional Codex reducer state, and tail records for lines not yet newline-terminated; mismatched guards or rewrites fall back to a full parse.

The transcript reader moves from readline to buffer-level streaming so parses can resume at exact offsets and handle huge single-line JSONL. UsageService stitches incremental parses with shared within-file dedupe, runs rate-table fetch in parallel with directory walks, and deduplicates concurrent identical readSummary requests via an in-flight Deferred map (detached scan, interrupt-safe enrollment).

New tests cover resume/guard/truncation, Codex boundary behavior, cache poison rejection, and concurrent scan sharing.

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

Note

Scan only appended transcript bytes for usage summaries

• Rewrites readTranscriptRecords to buffer-level streaming with byte-accurate offsets, enabling incremental resume via FNV-1a guard bytes; grown files parse only appended bytes, while shrunken or guard-mismatched files fall back to cold re-parse
• Adds in-flight scan deduplication in readSummary so concurrent identical requests share a single detached scan; interrupting one waiter does not cancel the scan for others
• Runs rate-table fetching concurrently with transcript scanning instead of gating it
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3 to store tailRecords and resume position; invalid guard metadata, malformed rows, or corrupt Codex state cause the entry to be dropped and the file reparsed cold
• Risk: existing v2 persisted scan caches are ignored, causing a one-time cold re-parse until a new v3 cache is written

^{Macroscope summarized d1f1578.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production usage parsing, persistent cache state, and request concurrency, introducing a substantial byte-resume mechanism rather than an isolated optimization. It also adds file-level static-analysis suppressions in two new test files, so human review is warranted.

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

Confirmed and fixed a cancellation race in shared usage scans.

A controlled scheduler canceled the first request after it enrolled its Deferred and before forkDetach started the scan. The next request for the same window then waited forever. The new test reproduced this at scheduler check 11 on the previous code.

The lookup, enrollment, and detached-fiber creation now run in one short uninterruptible section. Deferred.await remains outside that section, so callers can still cancel their wait. The scan stays detached for other callers and cache warming.

Codex checks:

• vp test run apps/server/src/usage: 67 passed.
• Changed-file format and lint: passed.
• Server typecheck: passed.

[StiensWout]

Problem

Opening the usage page re-parses any transcript that changed since the last scan from byte 0. The file most likely to have changed is the rollout the user is actively working in, which is also the largest file in the window (1.2 GB rollouts in the wild, see #7088). That makes warm scans cost tens of seconds, on every environment, every time the 60s client cache expires. Field traces in #7088 show 20-60 s warm and up to 7.3 min cold server.getUsageSummary calls.

Solution

Transcripts are append-only, so the scan cache (bumped to v3) now persists a byte-exact parse position per file: resume offset, a 64-byte guard fingerprint, and the Codex reducer state. A file that merely grew parses only its appended bytes; the guard verifies the append-only assumption and any mismatch (rotation, truncation, rewrite) falls back to a full re-parse. Records from a trailing unterminated line are cached separately so completing that line later never double counts.

Two smaller wins ride along, both part of the same investigation:

• Concurrent identical summary requests (usage page open on desktop and phone at once) share one scan instead of racing over the same corpus twice.
• The LiteLLM rate-table fetch runs concurrently with the transcript walk instead of gating it, so a cold fetch on a slow network no longer adds its own delay to the scan.

The reader also switched from readline to buffer-level line splitting (needed for byte-exact offsets), which turned out to make cold parses faster as well.

Proof

Measured against real transcripts (356 files, 318 MB, 30-day window; the largest rollout is 61 MB):

Scenario	Before	After
Warm rescan of the 61 MB rollout after one appended turn	1,247 ms (full re-parse)	3.3 ms (resumed)
Cold parse of the full 30-day corpus	4,309 ms	2,634 ms

Parity check: old and new readers produce byte-identical record sets on all 356 real transcripts (0 mismatches), and the stitched incremental result equals a from-scratch parse of the grown file.

vp test run apps/server/src/usage: 6 files, 64 tests, all passing, including new coverage for resume, guard mismatch, truncation, Codex state carried across the resume boundary, unterminated-tail handling, and scan sharing between concurrent requests.

Related issues: #7088 (this addresses the warm-scan cost; the ~/projects fallback stays with #7177), #5798, #5805.

Implemented by Claude (Fable 5) via Claude Code.

---

Note

Medium Risk
Changes core usage scanning, caching, and concurrency paths where incorrect resume or dedupe logic could misreport token totals; mitigated by guard fallbacks, strict cache decode, and broad new tests.

Overview
Warm usage scans no longer re-read entire transcript files when they only grew. The scan cache (now v3) stores a byte resume point, a 64-byte guard fingerprint, optional Codex reducer state, and tail records for lines not yet newline-terminated; mismatched guards or rewrites fall back to a full parse.

The transcript reader moves from readline to buffer-level streaming so parses can resume at exact offsets and handle huge single-line JSONL. UsageService stitches incremental parses with shared within-file dedupe, runs rate-table fetch in parallel with directory walks, and deduplicates concurrent identical readSummary requests via an in-flight Deferred map (detached scan, interrupt-safe enrollment).

New tests cover resume/guard/truncation, Codex boundary behavior, cache poison rejection, and concurrent scan sharing.

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

Note

Scan only appended transcript bytes for usage summaries

• Rewrites readTranscriptRecords to buffer-level streaming with byte-accurate offsets, enabling incremental resume via FNV-1a guard bytes; grown files parse only appended bytes, while shrunken or guard-mismatched files fall back to cold re-parse
• Adds in-flight scan deduplication in readSummary so concurrent identical requests share a single detached scan; interrupting one waiter does not cancel the scan for others
• Runs rate-table fetching concurrently with transcript scanning instead of gating it
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3 to store tailRecords and resume position; invalid guard metadata, malformed rows, or corrupt Codex state cause the entry to be dropped and the file reparsed cold
• Risk: existing v2 persisted scan caches are ignored, causing a one-time cold re-parse until a new v3 cache is written

^{Macroscope summarized d1f1578.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production usage parsing, persistent cache state, and request concurrency, introducing a substantial byte-resume mechanism rather than an isolated optimization. It also adds file-level static-analysis suppressions in two new test files, so human review is warranted.

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

Confirmed and fixed a cancellation race in shared usage scans.

A controlled scheduler canceled the first request after it enrolled its Deferred and before forkDetach started the scan. The next request for the same window then waited forever. The new test reproduced this at scheduler check 11 on the previous code.

The lookup, enrollment, and detached-fiber creation now run in one short uninterruptible section. Deferred.await remains outside that section, so callers can still cancel their wait. The scan stays detached for other callers and cache warming.

Codex checks:

• vp test run apps/server/src/usage: 67 passed.
• Changed-file format and lint: passed.
• Server typecheck: passed.

[StiensWout]

Problem

Opening the usage page re-parses any transcript that changed since the last scan from byte 0. The file most likely to have changed is the rollout the user is actively working in, which is also the largest file in the window (1.2 GB rollouts in the wild, see #7088). That makes warm scans cost tens of seconds, on every environment, every time the 60s client cache expires. Field traces in #7088 show 20-60 s warm and up to 7.3 min cold server.getUsageSummary calls.

Solution

Transcripts are append-only, so the scan cache (bumped to v3) now persists a byte-exact parse position per file: resume offset, a 64-byte guard fingerprint, and the Codex reducer state. A file that merely grew parses only its appended bytes; the guard verifies the append-only assumption and any mismatch (rotation, truncation, rewrite) falls back to a full re-parse. Records from a trailing unterminated line are cached separately so completing that line later never double counts.

Two smaller wins ride along, both part of the same investigation:

• Concurrent identical summary requests (usage page open on desktop and phone at once) share one scan instead of racing over the same corpus twice.
• The LiteLLM rate-table fetch runs concurrently with the transcript walk instead of gating it, so a cold fetch on a slow network no longer adds its own delay to the scan.

The reader also switched from readline to buffer-level line splitting (needed for byte-exact offsets), which turned out to make cold parses faster as well.

Proof

Measured against real transcripts (356 files, 318 MB, 30-day window; the largest rollout is 61 MB):

Scenario	Before	After
Warm rescan of the 61 MB rollout after one appended turn	1,247 ms (full re-parse)	3.3 ms (resumed)
Cold parse of the full 30-day corpus	4,309 ms	2,634 ms

Parity check: old and new readers produce byte-identical record sets on all 356 real transcripts (0 mismatches), and the stitched incremental result equals a from-scratch parse of the grown file.

vp test run apps/server/src/usage: 6 files, 64 tests, all passing, including new coverage for resume, guard mismatch, truncation, Codex state carried across the resume boundary, unterminated-tail handling, and scan sharing between concurrent requests.

Related issues: #7088 (this addresses the warm-scan cost; the ~/projects fallback stays with #7177), #5798, #5805.

Implemented by Claude (Fable 5) via Claude Code.

---

Note

Medium Risk
Changes core usage scanning, caching, and concurrency paths where incorrect resume or dedupe logic could misreport token totals; mitigated by guard fallbacks, strict cache decode, and broad new tests.

Overview
Warm usage scans no longer re-read entire transcript files when they only grew. The scan cache (now v3) stores a byte resume point, a 64-byte guard fingerprint, optional Codex reducer state, and tail records for lines not yet newline-terminated; mismatched guards or rewrites fall back to a full parse.

The transcript reader moves from readline to buffer-level streaming so parses can resume at exact offsets and handle huge single-line JSONL. UsageService stitches incremental parses with shared within-file dedupe, runs rate-table fetch in parallel with directory walks, and deduplicates concurrent identical readSummary requests via an in-flight Deferred map (detached scan, interrupt-safe enrollment).

New tests cover resume/guard/truncation, Codex boundary behavior, cache poison rejection, and concurrent scan sharing.

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

Note

Scan only appended transcript bytes for usage summaries

• Rewrites readTranscriptRecords to buffer-level streaming with byte-accurate offsets, enabling incremental resume via FNV-1a guard bytes; grown files parse only appended bytes, while shrunken or guard-mismatched files fall back to cold re-parse
• Adds in-flight scan deduplication in readSummary so concurrent identical requests share a single detached scan; interrupting one waiter does not cancel the scan for others
• Runs rate-table fetching concurrently with transcript scanning instead of gating it
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3 to store tailRecords and resume position; invalid guard metadata, malformed rows, or corrupt Codex state cause the entry to be dropped and the file reparsed cold
• Risk: existing v2 persisted scan caches are ignored, causing a one-time cold re-parse until a new v3 cache is written

^{Macroscope summarized d1f1578.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production usage parsing, persistent cache state, and request concurrency, introducing a substantial byte-resume mechanism rather than an isolated optimization. It also adds file-level static-analysis suppressions in two new test files, so human review is warranted.

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

Confirmed and fixed a cancellation race in shared usage scans.

A controlled scheduler canceled the first request after it enrolled its Deferred and before forkDetach started the scan. The next request for the same window then waited forever. The new test reproduced this at scheduler check 11 on the previous code.

The lookup, enrollment, and detached-fiber creation now run in one short uninterruptible section. Deferred.await remains outside that section, so callers can still cancel their wait. The scan stays detached for other callers and cache warming.

Codex checks:

• vp test run apps/server/src/usage: 67 passed.
• Changed-file format and lint: passed.
• Server typecheck: passed.

[StiensWout]

Problem

Opening the usage page re-parses any transcript that changed since the last scan from byte 0. The file most likely to have changed is the rollout the user is actively working in, which is also the largest file in the window (1.2 GB rollouts in the wild, see #7088). That makes warm scans cost tens of seconds, on every environment, every time the 60s client cache expires. Field traces in #7088 show 20-60 s warm and up to 7.3 min cold server.getUsageSummary calls.

Solution

Transcripts are append-only, so the scan cache (bumped to v3) now persists a byte-exact parse position per file: resume offset, a 64-byte guard fingerprint, and the Codex reducer state. A file that merely grew parses only its appended bytes; the guard verifies the append-only assumption and any mismatch (rotation, truncation, rewrite) falls back to a full re-parse. Records from a trailing unterminated line are cached separately so completing that line later never double counts.

Two smaller wins ride along, both part of the same investigation:

• Concurrent identical summary requests (usage page open on desktop and phone at once) share one scan instead of racing over the same corpus twice.
• The LiteLLM rate-table fetch runs concurrently with the transcript walk instead of gating it, so a cold fetch on a slow network no longer adds its own delay to the scan.

The reader also switched from readline to buffer-level line splitting (needed for byte-exact offsets), which turned out to make cold parses faster as well.

Proof

Measured against real transcripts (356 files, 318 MB, 30-day window; the largest rollout is 61 MB):

Scenario	Before	After
Warm rescan of the 61 MB rollout after one appended turn	1,247 ms (full re-parse)	3.3 ms (resumed)
Cold parse of the full 30-day corpus	4,309 ms	2,634 ms

Parity check: old and new readers produce byte-identical record sets on all 356 real transcripts (0 mismatches), and the stitched incremental result equals a from-scratch parse of the grown file.

vp test run apps/server/src/usage: 6 files, 64 tests, all passing, including new coverage for resume, guard mismatch, truncation, Codex state carried across the resume boundary, unterminated-tail handling, and scan sharing between concurrent requests.

Related issues: #7088 (this addresses the warm-scan cost; the ~/projects fallback stays with #7177), #5798, #5805.

Implemented by Claude (Fable 5) via Claude Code.

---

Note

Medium Risk
Changes core usage scanning, caching, and concurrency paths where incorrect resume or dedupe logic could misreport token totals; mitigated by guard fallbacks, strict cache decode, and broad new tests.

Overview
Warm usage scans no longer re-read entire transcript files when they only grew. The scan cache (now v3) stores a byte resume point, a 64-byte guard fingerprint, optional Codex reducer state, and tail records for lines not yet newline-terminated; mismatched guards or rewrites fall back to a full parse.

The transcript reader moves from readline to buffer-level streaming so parses can resume at exact offsets and handle huge single-line JSONL. UsageService stitches incremental parses with shared within-file dedupe, runs rate-table fetch in parallel with directory walks, and deduplicates concurrent identical readSummary requests via an in-flight Deferred map (detached scan, interrupt-safe enrollment).

New tests cover resume/guard/truncation, Codex boundary behavior, cache poison rejection, and concurrent scan sharing.

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

Note

Scan only appended transcript bytes for usage summaries

• Rewrites readTranscriptRecords to buffer-level streaming with byte-accurate offsets, enabling incremental resume via FNV-1a guard bytes; grown files parse only appended bytes, while shrunken or guard-mismatched files fall back to cold re-parse
• Adds in-flight scan deduplication in readSummary so concurrent identical requests share a single detached scan; interrupting one waiter does not cancel the scan for others
• Runs rate-table fetching concurrently with transcript scanning instead of gating it
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3 to store tailRecords and resume position; invalid guard metadata, malformed rows, or corrupt Codex state cause the entry to be dropped and the file reparsed cold
• Risk: existing v2 persisted scan caches are ignored, causing a one-time cold re-parse until a new v3 cache is written

^{Macroscope summarized d1f1578.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production usage parsing, persistent cache state, and request concurrency, introducing a substantial byte-resume mechanism rather than an isolated optimization. It also adds file-level static-analysis suppressions in two new test files, so human review is warranted.

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

Confirmed and fixed a cancellation race in shared usage scans.

A controlled scheduler canceled the first request after it enrolled its Deferred and before forkDetach started the scan. The next request for the same window then waited forever. The new test reproduced this at scheduler check 11 on the previous code.

The lookup, enrollment, and detached-fiber creation now run in one short uninterruptible section. Deferred.await remains outside that section, so callers can still cancel their wait. The scan stays detached for other callers and cache warming.

Codex checks:

• vp test run apps/server/src/usage: 67 passed.
• Changed-file format and lint: passed.
• Server typecheck: passed.

[StiensWout]

Problem

Opening the usage page re-parses any transcript that changed since the last scan from byte 0. The file most likely to have changed is the rollout the user is actively working in, which is also the largest file in the window (1.2 GB rollouts in the wild, see #7088). That makes warm scans cost tens of seconds, on every environment, every time the 60s client cache expires. Field traces in #7088 show 20-60 s warm and up to 7.3 min cold server.getUsageSummary calls.

Solution

Transcripts are append-only, so the scan cache (bumped to v3) now persists a byte-exact parse position per file: resume offset, a 64-byte guard fingerprint, and the Codex reducer state. A file that merely grew parses only its appended bytes; the guard verifies the append-only assumption and any mismatch (rotation, truncation, rewrite) falls back to a full re-parse. Records from a trailing unterminated line are cached separately so completing that line later never double counts.

Two smaller wins ride along, both part of the same investigation:

• Concurrent identical summary requests (usage page open on desktop and phone at once) share one scan instead of racing over the same corpus twice.
• The LiteLLM rate-table fetch runs concurrently with the transcript walk instead of gating it, so a cold fetch on a slow network no longer adds its own delay to the scan.

The reader also switched from readline to buffer-level line splitting (needed for byte-exact offsets), which turned out to make cold parses faster as well.

Proof

Measured against real transcripts (356 files, 318 MB, 30-day window; the largest rollout is 61 MB):

Scenario	Before	After
Warm rescan of the 61 MB rollout after one appended turn	1,247 ms (full re-parse)	3.3 ms (resumed)
Cold parse of the full 30-day corpus	4,309 ms	2,634 ms

Parity check: old and new readers produce byte-identical record sets on all 356 real transcripts (0 mismatches), and the stitched incremental result equals a from-scratch parse of the grown file.

vp test run apps/server/src/usage: 6 files, 64 tests, all passing, including new coverage for resume, guard mismatch, truncation, Codex state carried across the resume boundary, unterminated-tail handling, and scan sharing between concurrent requests.

Related issues: #7088 (this addresses the warm-scan cost; the ~/projects fallback stays with #7177), #5798, #5805.

Implemented by Claude (Fable 5) via Claude Code.

---

Note

Medium Risk
Changes core usage scanning, caching, and concurrency paths where incorrect resume or dedupe logic could misreport token totals; mitigated by guard fallbacks, strict cache decode, and broad new tests.

Overview
Warm usage scans no longer re-read entire transcript files when they only grew. The scan cache (now v3) stores a byte resume point, a 64-byte guard fingerprint, optional Codex reducer state, and tail records for lines not yet newline-terminated; mismatched guards or rewrites fall back to a full parse.

The transcript reader moves from readline to buffer-level streaming so parses can resume at exact offsets and handle huge single-line JSONL. UsageService stitches incremental parses with shared within-file dedupe, runs rate-table fetch in parallel with directory walks, and deduplicates concurrent identical readSummary requests via an in-flight Deferred map (detached scan, interrupt-safe enrollment).

New tests cover resume/guard/truncation, Codex boundary behavior, cache poison rejection, and concurrent scan sharing.

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

Note

Scan only appended transcript bytes for usage summaries

• Rewrites readTranscriptRecords to buffer-level streaming with byte-accurate offsets, enabling incremental resume via FNV-1a guard bytes; grown files parse only appended bytes, while shrunken or guard-mismatched files fall back to cold re-parse
• Adds in-flight scan deduplication in readSummary so concurrent identical requests share a single detached scan; interrupting one waiter does not cancel the scan for others
• Runs rate-table fetching concurrently with transcript scanning instead of gating it
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3 to store tailRecords and resume position; invalid guard metadata, malformed rows, or corrupt Codex state cause the entry to be dropped and the file reparsed cold
• Risk: existing v2 persisted scan caches are ignored, causing a one-time cold re-parse until a new v3 cache is written

^{Macroscope summarized d1f1578.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production usage parsing, persistent cache state, and request concurrency, introducing a substantial byte-resume mechanism rather than an isolated optimization. It also adds file-level static-analysis suppressions in two new test files, so human review is warranted.

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

Confirmed and fixed a cancellation race in shared usage scans.

A controlled scheduler canceled the first request after it enrolled its Deferred and before forkDetach started the scan. The next request for the same window then waited forever. The new test reproduced this at scheduler check 11 on the previous code.

The lookup, enrollment, and detached-fiber creation now run in one short uninterruptible section. Deferred.await remains outside that section, so callers can still cancel their wait. The scan stays detached for other callers and cache warming.

Codex checks:

• vp test run apps/server/src/usage: 67 passed.
• Changed-file format and lint: passed.
• Server typecheck: passed.

[StiensWout]

Problem

Opening the usage page re-parses any transcript that changed since the last scan from byte 0. The file most likely to have changed is the rollout the user is actively working in, which is also the largest file in the window (1.2 GB rollouts in the wild, see #7088). That makes warm scans cost tens of seconds, on every environment, every time the 60s client cache expires. Field traces in #7088 show 20-60 s warm and up to 7.3 min cold server.getUsageSummary calls.

Solution

Transcripts are append-only, so the scan cache (bumped to v3) now persists a byte-exact parse position per file: resume offset, a 64-byte guard fingerprint, and the Codex reducer state. A file that merely grew parses only its appended bytes; the guard verifies the append-only assumption and any mismatch (rotation, truncation, rewrite) falls back to a full re-parse. Records from a trailing unterminated line are cached separately so completing that line later never double counts.

Two smaller wins ride along, both part of the same investigation:

• Concurrent identical summary requests (usage page open on desktop and phone at once) share one scan instead of racing over the same corpus twice.
• The LiteLLM rate-table fetch runs concurrently with the transcript walk instead of gating it, so a cold fetch on a slow network no longer adds its own delay to the scan.

The reader also switched from readline to buffer-level line splitting (needed for byte-exact offsets), which turned out to make cold parses faster as well.

Proof

Measured against real transcripts (356 files, 318 MB, 30-day window; the largest rollout is 61 MB):

Scenario	Before	After
Warm rescan of the 61 MB rollout after one appended turn	1,247 ms (full re-parse)	3.3 ms (resumed)
Cold parse of the full 30-day corpus	4,309 ms	2,634 ms

Parity check: old and new readers produce byte-identical record sets on all 356 real transcripts (0 mismatches), and the stitched incremental result equals a from-scratch parse of the grown file.

vp test run apps/server/src/usage: 6 files, 64 tests, all passing, including new coverage for resume, guard mismatch, truncation, Codex state carried across the resume boundary, unterminated-tail handling, and scan sharing between concurrent requests.

Related issues: #7088 (this addresses the warm-scan cost; the ~/projects fallback stays with #7177), #5798, #5805.

Implemented by Claude (Fable 5) via Claude Code.

---

Note

Medium Risk
Changes core usage scanning, caching, and concurrency paths where incorrect resume or dedupe logic could misreport token totals; mitigated by guard fallbacks, strict cache decode, and broad new tests.

Overview
Warm usage scans no longer re-read entire transcript files when they only grew. The scan cache (now v3) stores a byte resume point, a 64-byte guard fingerprint, optional Codex reducer state, and tail records for lines not yet newline-terminated; mismatched guards or rewrites fall back to a full parse.

The transcript reader moves from readline to buffer-level streaming so parses can resume at exact offsets and handle huge single-line JSONL. UsageService stitches incremental parses with shared within-file dedupe, runs rate-table fetch in parallel with directory walks, and deduplicates concurrent identical readSummary requests via an in-flight Deferred map (detached scan, interrupt-safe enrollment).

New tests cover resume/guard/truncation, Codex boundary behavior, cache poison rejection, and concurrent scan sharing.

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

Note

Scan only appended transcript bytes for usage summaries

• Rewrites readTranscriptRecords to buffer-level streaming with byte-accurate offsets, enabling incremental resume via FNV-1a guard bytes; grown files parse only appended bytes, while shrunken or guard-mismatched files fall back to cold re-parse
• Adds in-flight scan deduplication in readSummary so concurrent identical requests share a single detached scan; interrupting one waiter does not cancel the scan for others
• Runs rate-table fetching concurrently with transcript scanning instead of gating it
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3 to store tailRecords and resume position; invalid guard metadata, malformed rows, or corrupt Codex state cause the entry to be dropped and the file reparsed cold
• Risk: existing v2 persisted scan caches are ignored, causing a one-time cold re-parse until a new v3 cache is written

^{Macroscope summarized d1f1578.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production usage parsing, persistent cache state, and request concurrency, introducing a substantial byte-resume mechanism rather than an isolated optimization. It also adds file-level static-analysis suppressions in two new test files, so human review is warranted.

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

Confirmed and fixed a cancellation race in shared usage scans.

A controlled scheduler canceled the first request after it enrolled its Deferred and before forkDetach started the scan. The next request for the same window then waited forever. The new test reproduced this at scheduler check 11 on the previous code.

The lookup, enrollment, and detached-fiber creation now run in one short uninterruptible section. Deferred.await remains outside that section, so callers can still cancel their wait. The scan stays detached for other callers and cache warming.

Codex checks:

• vp test run apps/server/src/usage: 67 passed.
• Changed-file format and lint: passed.
• Server typecheck: passed.

[StiensWout]

Problem

Opening the usage page re-parses any transcript that changed since the last scan from byte 0. The file most likely to have changed is the rollout the user is actively working in, which is also the largest file in the window (1.2 GB rollouts in the wild, see #7088). That makes warm scans cost tens of seconds, on every environment, every time the 60s client cache expires. Field traces in #7088 show 20-60 s warm and up to 7.3 min cold server.getUsageSummary calls.

Solution

Transcripts are append-only, so the scan cache (bumped to v3) now persists a byte-exact parse position per file: resume offset, a 64-byte guard fingerprint, and the Codex reducer state. A file that merely grew parses only its appended bytes; the guard verifies the append-only assumption and any mismatch (rotation, truncation, rewrite) falls back to a full re-parse. Records from a trailing unterminated line are cached separately so completing that line later never double counts.

Two smaller wins ride along, both part of the same investigation:

• Concurrent identical summary requests (usage page open on desktop and phone at once) share one scan instead of racing over the same corpus twice.
• The LiteLLM rate-table fetch runs concurrently with the transcript walk instead of gating it, so a cold fetch on a slow network no longer adds its own delay to the scan.

The reader also switched from readline to buffer-level line splitting (needed for byte-exact offsets), which turned out to make cold parses faster as well.

Proof

Measured against real transcripts (356 files, 318 MB, 30-day window; the largest rollout is 61 MB):

Scenario	Before	After
Warm rescan of the 61 MB rollout after one appended turn	1,247 ms (full re-parse)	3.3 ms (resumed)
Cold parse of the full 30-day corpus	4,309 ms	2,634 ms

Parity check: old and new readers produce byte-identical record sets on all 356 real transcripts (0 mismatches), and the stitched incremental result equals a from-scratch parse of the grown file.

vp test run apps/server/src/usage: 6 files, 64 tests, all passing, including new coverage for resume, guard mismatch, truncation, Codex state carried across the resume boundary, unterminated-tail handling, and scan sharing between concurrent requests.

Related issues: #7088 (this addresses the warm-scan cost; the ~/projects fallback stays with #7177), #5798, #5805.

Implemented by Claude (Fable 5) via Claude Code.

---

Note

Medium Risk
Changes core usage scanning, caching, and concurrency paths where incorrect resume or dedupe logic could misreport token totals; mitigated by guard fallbacks, strict cache decode, and broad new tests.

Overview
Warm usage scans no longer re-read entire transcript files when they only grew. The scan cache (now v3) stores a byte resume point, a 64-byte guard fingerprint, optional Codex reducer state, and tail records for lines not yet newline-terminated; mismatched guards or rewrites fall back to a full parse.

The transcript reader moves from readline to buffer-level streaming so parses can resume at exact offsets and handle huge single-line JSONL. UsageService stitches incremental parses with shared within-file dedupe, runs rate-table fetch in parallel with directory walks, and deduplicates concurrent identical readSummary requests via an in-flight Deferred map (detached scan, interrupt-safe enrollment).

New tests cover resume/guard/truncation, Codex boundary behavior, cache poison rejection, and concurrent scan sharing.

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

Note

Scan only appended transcript bytes for usage summaries

• Rewrites readTranscriptRecords to buffer-level streaming with byte-accurate offsets, enabling incremental resume via FNV-1a guard bytes; grown files parse only appended bytes, while shrunken or guard-mismatched files fall back to cold re-parse
• Adds in-flight scan deduplication in readSummary so concurrent identical requests share a single detached scan; interrupting one waiter does not cancel the scan for others
• Runs rate-table fetching concurrently with transcript scanning instead of gating it
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3 to store tailRecords and resume position; invalid guard metadata, malformed rows, or corrupt Codex state cause the entry to be dropped and the file reparsed cold
• Risk: existing v2 persisted scan caches are ignored, causing a one-time cold re-parse until a new v3 cache is written

^{Macroscope summarized d1f1578.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production usage parsing, persistent cache state, and request concurrency, introducing a substantial byte-resume mechanism rather than an isolated optimization. It also adds file-level static-analysis suppressions in two new test files, so human review is warranted.

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

Confirmed and fixed a cancellation race in shared usage scans.

A controlled scheduler canceled the first request after it enrolled its Deferred and before forkDetach started the scan. The next request for the same window then waited forever. The new test reproduced this at scheduler check 11 on the previous code.

The lookup, enrollment, and detached-fiber creation now run in one short uninterruptible section. Deferred.await remains outside that section, so callers can still cancel their wait. The scan stays detached for other callers and cache warming.

Codex checks:

• vp test run apps/server/src/usage: 67 passed.
• Changed-file format and lint: passed.
• Server typecheck: passed.

[StiensWout]

Problem

Opening the usage page re-parses any transcript that changed since the last scan from byte 0. The file most likely to have changed is the rollout the user is actively working in, which is also the largest file in the window (1.2 GB rollouts in the wild, see #7088). That makes warm scans cost tens of seconds, on every environment, every time the 60s client cache expires. Field traces in #7088 show 20-60 s warm and up to 7.3 min cold server.getUsageSummary calls.

Solution

Transcripts are append-only, so the scan cache (bumped to v3) now persists a byte-exact parse position per file: resume offset, a 64-byte guard fingerprint, and the Codex reducer state. A file that merely grew parses only its appended bytes; the guard verifies the append-only assumption and any mismatch (rotation, truncation, rewrite) falls back to a full re-parse. Records from a trailing unterminated line are cached separately so completing that line later never double counts.

Two smaller wins ride along, both part of the same investigation:

• Concurrent identical summary requests (usage page open on desktop and phone at once) share one scan instead of racing over the same corpus twice.
• The LiteLLM rate-table fetch runs concurrently with the transcript walk instead of gating it, so a cold fetch on a slow network no longer adds its own delay to the scan.

The reader also switched from readline to buffer-level line splitting (needed for byte-exact offsets), which turned out to make cold parses faster as well.

Proof

Measured against real transcripts (356 files, 318 MB, 30-day window; the largest rollout is 61 MB):

Scenario	Before	After
Warm rescan of the 61 MB rollout after one appended turn	1,247 ms (full re-parse)	3.3 ms (resumed)
Cold parse of the full 30-day corpus	4,309 ms	2,634 ms

Parity check: old and new readers produce byte-identical record sets on all 356 real transcripts (0 mismatches), and the stitched incremental result equals a from-scratch parse of the grown file.

vp test run apps/server/src/usage: 6 files, 64 tests, all passing, including new coverage for resume, guard mismatch, truncation, Codex state carried across the resume boundary, unterminated-tail handling, and scan sharing between concurrent requests.

Related issues: #7088 (this addresses the warm-scan cost; the ~/projects fallback stays with #7177), #5798, #5805.

Implemented by Claude (Fable 5) via Claude Code.

---

Note

Medium Risk
Changes core usage scanning, caching, and concurrency paths where incorrect resume or dedupe logic could misreport token totals; mitigated by guard fallbacks, strict cache decode, and broad new tests.

Overview
Warm usage scans no longer re-read entire transcript files when they only grew. The scan cache (now v3) stores a byte resume point, a 64-byte guard fingerprint, optional Codex reducer state, and tail records for lines not yet newline-terminated; mismatched guards or rewrites fall back to a full parse.

The transcript reader moves from readline to buffer-level streaming so parses can resume at exact offsets and handle huge single-line JSONL. UsageService stitches incremental parses with shared within-file dedupe, runs rate-table fetch in parallel with directory walks, and deduplicates concurrent identical readSummary requests via an in-flight Deferred map (detached scan, interrupt-safe enrollment).

New tests cover resume/guard/truncation, Codex boundary behavior, cache poison rejection, and concurrent scan sharing.

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

Note

Scan only appended transcript bytes for usage summaries

• Rewrites readTranscriptRecords to buffer-level streaming with byte-accurate offsets, enabling incremental resume via FNV-1a guard bytes; grown files parse only appended bytes, while shrunken or guard-mismatched files fall back to cold re-parse
• Adds in-flight scan deduplication in readSummary so concurrent identical requests share a single detached scan; interrupting one waiter does not cancel the scan for others
• Runs rate-table fetching concurrently with transcript scanning instead of gating it
• Bumps USAGE_SCAN_CACHE_VERSION from 2 to 3 to store tailRecords and resume position; invalid guard metadata, malformed rows, or corrupt Codex state cause the entry to be dropped and the file reparsed cold
• Risk: existing v2 persisted scan caches are ignored, causing a one-time cold re-parse until a new v3 cache is written

^{Macroscope summarized d1f1578.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production usage parsing, persistent cache state, and request concurrency, introducing a substantial byte-resume mechanism rather than an isolated optimization. It also adds file-level static-analysis suppressions in two new test files, so human review is warranted.

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

[t3dotgg]

Note

🤖 GPT-5.6 Sol responding on behalf of Theo

Confirmed and fixed a cancellation race in shared usage scans.

A controlled scheduler canceled the first request after it enrolled its Deferred and before forkDetach started the scan. The next request for the same window then waited forever. The new test reproduced this at scheduler check 11 on the previous code.

The lookup, enrollment, and detached-fiber creation now run in one short uninterruptible section. Deferred.await remains outside that section, so callers can still cancel their wait. The scan stays detached for other callers and cache warming.

Codex checks:

• vp test run apps/server/src/usage: 67 passed.
• Changed-file format and lint: passed.
• Server typecheck: passed.