One Codex rollout added roughly 331 million tokens that had never been used. The file was valid, and every event parsed cleanly.
The bug was in the meaning of last_token_usage.
Codex can report the latest token delta again without advancing total_token_usage. Summing every delta counts the same turn twice. The cumulative input/output pair is the useful replay signal:
same cumulative pair -> replay, skip
advanced pair -> new usage, count
smaller pair -> compaction reset, count
missing pair -> legacy event, count
A monotonic-only check would be wrong because compaction can move cumulative totals backward. Exact equality is the narrow condition that identifies the observed replay.
We pinned the behavior with six fixture events. Two are original turns, two repeat the same cumulative pairs, one resets after compaction, and one represents an older client without cumulative totals. Four events survive with the expected input and output sums.
Fixing duplicates exposed the opposite accounting error. Codex moves old rollouts from ~/.codex/sessions to ~/.codex/archived_sessions. Scanning only the live tree made history disappear when users archived sessions. On one machine, 2.5 billion July tokens lived only in the archive directory.
The reader now walks both roots through the same streaming parser and cache. It also rejects irrelevant multi-megabyte lines before JSON decoding, since screenshots and tool output are not usage records.
The last decision is time attribution. We attach usage to each event's local timestamp instead of the session start date. A session crossing midnight therefore lands on both days. That keeps daily and weekly views aligned with when the work occurred.
This still produces an estimate, not an invoice. Pricing tables age, provider billing can use information absent from local logs, and cached input needs separate treatment. The UI should say estimated API value, not exact spend.
Agent Island 1.7.1 ships this reader for macOS and Windows. The code is MIT licensed, and the accounting stays local.
Canonical article: https://agent-island.dev/blog/codex-token-replay-guard/
Top comments (1)
Valid and unique are different guarantees. Token events especially need idempotency thinking because retries and replayed signals can look legitimate. I like systems that treat duplicate detection as part of correctness, not as cleanup after the fact.