The best way to control Claude Code, Codex and more from any computer or phone
fix(usage): a re-emitted Codex snapshot is no longer billed as a counter rewind (#36367)
Co-authored-by: rihanaws <rihanawsacc@gmail.com>
Julius Marminge committed
Nov 13, 2026 at 13:23 UTC
9ced4f1f45b784b17097b5de516757cbee37dacc
5 files changed
+182
-11
apps/server/src/provider/Drivers/codexUsage.test.ts
+92
@@ -589,6 +589,98 @@ describe("parseCodexLine", () => {
589
});
590
});
591
592
+ const at = (time: string, line: string) => line.replace("05:17:49.919Z", `${time}.000Z`);
593
+ const anonymousRequest = (time: string, usage: unknown) =>
594
+ JSON.stringify({
595
+ type: "token_usage_record",
596
+ timestamp: `2026-08-01T${time}.000Z`,
597
+ payload: { usage },
598
+ });
599
+ it.each([
600
+ {
601
+ name: "does not bill an older snapshot re-emitted after requests without cumulative counters",
602
+ lines: [
603
+ at("10:00:00", counted(counters(100, 20), counters(100, 20))),
604
+ at("10:00:05", counted(counters(20, 4))),
605
+ at("10:00:10", counted(counters(30, 6))),
606
+ at("10:00:05", counted(counters(20, 4), counters(120, 24))),
607
+ ],
608
+ processed: [120, 24, 36, 0],
609
+ skipped: 1,
610
+ },
611
+ {
612
+ name: "bills a rewind that follows a request without cumulative counters",
613
+ lines: [
614
+ at("10:00:00", counted(counters(100, 20))),
615
+ at("10:00:10", counted(counters(20, 4), counters(60, 12))),
616
+ ],
617
+ processed: [120, 24],
618
+ skipped: 0,
619
+ },
620
+ {
621
+ name: "keeps the baseline when it rejects an older snapshot, so the replay that follows is not billed",
622
+ lines: [
623
+ at("10:00:00", counted(counters(100, 20), counters(100, 20))),
624
+ at("10:00:05", counted(counters(20, 4), counters(120, 24))),
625
+ at("10:00:10", counted(counters(30, 6), counters(150, 30))),
626
+ at("10:00:05", counted(counters(20, 4), counters(120, 24))),
627
+ at("10:00:10", counted(counters(30, 6), counters(150, 30))),
628
+ ],
629
+ processed: [120, 24, 36, 0, 0],
630
+ skipped: 1,
631
+ },
632
+ {
633
+ name: "keeps the baseline when it rejects a lower snapshot from the baseline's own time",
634
+ lines: [
635
+ at("10:00:00", counted(counters(100, 20), counters(100, 20))),
636
+ at("10:00:00", counted(counters(20, 4), counters(120, 24))),
637
+ at("10:00:00", counted(counters(30, 6), counters(150, 30))),
638
+ at("10:00:00", counted(counters(20, 4), counters(120, 24))),
639
+ at("10:00:00", counted(counters(30, 6), counters(150, 30))),
640
+ ],
641
+ processed: [120, 24, 36, 0, 0],
642
+ skipped: 1,
643
+ },
644
+ {
645
+ name: "does not bill replayed snapshots against a cached baseline of unknown age",
646
+ lines: [
647
+ at("10:00:00", counted(counters(100, 20), counters(100, 20))),
648
+ at("10:00:05", counted(counters(20, 4), counters(120, 24))),
649
+ at("10:00:10", counted(counters(30, 6), counters(150, 30))),
650
+ at("10:00:00", counted(counters(100, 20), counters(100, 20))),
651
+ at("10:00:05", counted(counters(20, 4), counters(120, 24))),
652
+ ],
653
+ undatedAfter: 3,
654
+ processed: [120, 24, 36, 0, 0],
655
+ skipped: 1,
656
+ },
657
+ {
658
+ name: "warns about the anonymous request a rewound snapshot does not report",
659
+ lines: [
660
+ at("10:00:00", counted(counters(100, 20), counters(100, 20))),
661
+ anonymousRequest("10:00:05", counters(40, 8)),
662
+ anonymousRequest("10:00:06", counters(20, 4)),
663
+ at("10:00:07", counted(counters(20, 4), counters(60, 12))),
664
+ at("10:00:08", counted(counters(10, 2), counters(70, 14))),
665
+ ],
666
+ processed: [120, 0, 0, 24, 12],
667
+ skipped: 1,
668
+ },
669
+ ])("$name", ({ lines, undatedAfter, processed, skipped }) => {
670
+ const state = initialCodexScanState();
671
+ parseCodexLine(turnContext, state);
672
+ const billed = lines.map((line, index) => {
673
+ if (index === undatedAfter) delete state.latestCumulativeAtMs;
674
+ const record = parseCodexLine(line, state);
675
+ return record === null ? 0 : totalTokens(record.totals);
676
+ });
677
+
678
+ expect({ processed: billed, skipped: codexUsageFormat.readMalformedRecords?.(state) }).toEqual({
679
+ processed,
680
+ skipped,
681
+ });
682
+ });
683
+
684
it("ignores a replay of the current sequence's first request without rewinding the baseline", () => {
685
const state = initialCodexScanState();
686
parseCodexLine(turnContext, state);
apps/server/src/provider/Drivers/codexUsage.ts
+42
-5
@@ -54,10 +54,15 @@ function readCodexTokenUsage(value: unknown): CodexTokenUsage | null {
54
return isCodexTokenUsage(usage) ? usage : null;
55
}
56
57
+// Every move of the baseline dates it, so an older snapshot re-emitted later is never a rewind.
58
+function dateCodexBaseline(state: CodexScanState, timestampMs: number) {
59
+ state.latestCumulativeAtMs = Math.max(state.latestCumulativeAtMs ?? timestampMs, timestampMs);
60
+}
61
+
62
// A zeroed baseline rebases the counters, so the sequence start measured against it is forgotten.
63
function rebaseCodexUsage(state: CodexScanState, cumulative: CodexTokenUsage, timestampMs: number) {
64
state.lastCumulativeUsage = cumulative;
60
- state.latestCumulativeAtMs = Math.max(state.latestCumulativeAtMs ?? timestampMs, timestampMs);
65
+ dateCodexBaseline(state, timestampMs);
66
delete state.unreportedRequests;
67
if (cumulative.input_tokens + cumulative.output_tokens === 0) delete state.sequenceStartSignature;
68
}
@@ -112,6 +117,18 @@ function unreportedRequests(
117
);
118
}
119
120
+// A rewound snapshot vouches only for the request it reports, so the anonymous requests read before
121
+// it can be neither billed nor ruled out as that request's prefix.
122
+function discardedRequests(
123
+ pending: readonly CodexUnreportedRequest[] | undefined,
124
+ last: CodexTokenUsage,
125
+) {
126
+ const final = pending?.at(-1);
127
+ if (pending === undefined || final === undefined) return 0;
128
+ const reported = CODEX_USAGE_FIELDS.every((key) => final.usage[key] === last[key]);
129
+ return pending.length - (reported ? 1 : 0);
130
+}
131
+
132
/**
133
* Codex `token_count` events carry no model or service tier, so both are carried forward: the model
134
* from the most recent `turn_context`, the tier from the most recent `thread_settings_applied`.
@@ -251,6 +268,7 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
268
state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, request.usage);
269
}
270
state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, usage);
271
+ dateCodexBaseline(state, timestampMs);
272
delete state.unreportedRequests;
273
return [
274
...pending.map((request) => codexRequestRecord(state, request.usage, request)),
@@ -295,6 +313,7 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
313
if (cumulative !== null) rebaseCodexUsage(state, cumulative, timestampMs);
314
else if (!hasCumulative && last !== null && signature !== state.lastUsageSignature) {
315
state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, last);
316
+ dateCodexBaseline(state, timestampMs);
317
}
318
state.lastUsageSignature = signature;
319
return [];
@@ -345,15 +364,18 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
364
// Only the same event is a replay; a later request can restart with identical counters.
365
if (restarted && sequenceStart === state.sequenceStartSignature) {
366
state.lastCumulativeUsage = previous;
367
+ // The retained baseline keeps its own age; one of unknown age must not take the replay's.
368
+ if (latestCumulativeAtMs === undefined) delete state.latestCumulativeAtMs;
369
return [];
370
}
371
// Forks and paginated continuations can inherit totals without copying a counter snapshot, and
372
// a later request can continue from an earlier snapshot; a re-emitted old snapshot is not later.
352
- // Only bill the latest request, and require the unseen prefix to be valid usage too.
373
+ // Only bill the latest request, and require the unseen prefix to be valid usage too. A baseline
374
+ // of unknown age (a scan state cached before every move dated it) cannot order the snapshot.
375
+ const lowered =
376
+ previous !== null && CODEX_USAGE_FIELDS.some((key) => cumulative[key] < previous[key]);
377
const rewound =
354
- previous !== null &&
355
- (latestCumulativeAtMs === undefined || timestampMs > latestCumulativeAtMs) &&
356
- CODEX_USAGE_FIELDS.some((key) => cumulative[key] < previous[key]);
378
+ lowered && latestCumulativeAtMs !== undefined && timestampMs > latestCumulativeAtMs;
379
const reconciled =
380
previous === null || rewound
381
? readCodexTokenUsage(
@@ -363,10 +385,24 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
385
if (!restarted && !reconciled) {
386
const bridged = unreportedRequests(previous, cumulative, last, pending);
387
if (bridged === null) {
388
+ // A rejected snapshot from before the baseline's time is a replay, not the next baseline.
389
+ // At the baseline's own time only lower counters are one; zeroed counters still rebase.
390
+ const replayed =
391
+ latestCumulativeAtMs !== undefined &&
392
+ (timestampMs < latestCumulativeAtMs ||
393
+ (timestampMs === latestCumulativeAtMs &&
394
+ lowered &&
395
+ cumulative.input_tokens + cumulative.output_tokens > 0));
396
+ if (replayed) {
397
+ state.lastCumulativeUsage = previous;
398
+ if (pending !== undefined) state.unreportedRequests = pending;
399
+ }
400
state.malformedRecords += 1;
401
return [];
402
}
403
unreported = bridged;
404
+ } else if (!restarted && rewound) {
405
+ state.malformedRecords += discardedRequests(pending, last);
406
}
407
if (restarted) state.sequenceStartSignature = sequenceStart;
408
} else {
@@ -378,6 +414,7 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
414
return [];
415
}
416
state.lastCumulativeUsage = advanced;
417
+ dateCodexBaseline(state, timestampMs);
418
}
419
state.lastUsageSignature = signature;
420
apps/server/src/usage/UsageService.test.ts
+1
-1
@@ -3106,7 +3106,7 @@ describe("UsageService", () => {
3106
60 + 20 * (version === 4 ? 1 : 2),
3107
);
3108
yield* upgraded.awaitPersisted;
3109
- assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v15.json");
3109
+ assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v16.json");
3110
assert.deepStrictEqual(
3111
(yield* Effect.promise(() => NodeFSP.readdir(stateDir)))
3112
.filter((name) => name.startsWith("usage-scan-cache"))
apps/server/src/usage/usageScanCache.test.ts
+40
@@ -285,6 +285,46 @@ describe("scan cache round trip", () => {
285
...codex(0),
286
position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
287
});
288
+ // The migrated entries persist without a state and load again under the current version.
289
+ expect(decodeScanCache(parse(makeScanCacheWriter()(restored, {})), TEST_FORMAT_MAP)).toEqual(
290
+ restored,
291
+ );
292
+ });
293
+
294
+ it("restarts a grown v15 Codex entry, whose baseline time can be older than its totals", () => {
295
+ const request = {
296
+ input_tokens: 100,
297
+ cached_input_tokens: 0,
298
+ cache_write_input_tokens: 0,
299
+ output_tokens: 20,
300
+ reasoning_output_tokens: 0,
301
+ total_tokens: 120,
302
+ };
303
+ const entry: CachedFile = {
304
+ size: 10,
305
+ mtimeMs: 100,
306
+ provider: "codex",
307
+ records: [record({ provider: "codex", model: "gpt-6-astra", dedupeKey: null })],
308
+ tailRecords: [],
309
+ malformedRecords: 0,
310
+ position: position({
311
+ state: {
312
+ ...initialCodexScanState(),
313
+ model: "gpt-6-astra",
314
+ lastCumulativeUsage: request,
315
+ latestCumulativeAtMs: 1_786_000_000_000,
316
+ },
317
+ }),
318
+ };
319
+ const current = parse(makeScanCacheWriter()(new Map([["/codex.jsonl", entry]]), {}));
320
+
321
+ expect(
322
+ decodeScanCache({ ...current, version: 15 }, TEST_FORMAT_MAP).get("/codex.jsonl"),
323
+ ).toEqual({
324
+ ...entry,
325
+ position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
326
+ });
327
+ expect(decodeScanCache(current, TEST_FORMAT_MAP).get("/codex.jsonl")).toEqual(entry);
328
});
329
330
it("re-parses a Claude transcript cached before 1-hour cache writes were counted", () => {
apps/server/src/usage/usageScanCache.ts
+7
-5
@@ -10,7 +10,7 @@ import { CLAUDE_SYNTHETIC_MODEL } from "../provider/Drivers/claudeUsage.ts";
10
import { mergeUsageCopies } from "./usageAggregation.ts";
11
import { GUARD_LENGTH, type TranscriptParsePosition } from "./usageTranscriptReader.ts";
12
13
-const USAGE_SCAN_CACHE_VERSION = 15 as const;
13
+const USAGE_SCAN_CACHE_VERSION = 16 as const;
14
const SPEED_COMPATIBLE_SINCE_VERSION = 4;
15
16
/**
@@ -18,8 +18,9 @@ const SPEED_COMPATIBLE_SINCE_VERSION = 4;
18
* replace it, dropping saved usage for deleted transcripts. Separate files keep
19
* the newer one; older files are removed once it is saved.
20
*/
21
-export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v15.json";
21
+export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v16.json";
22
export const LEGACY_SCAN_CACHE_FILE_NAMES = [
23
+ "usage-scan-cache-v15.json",
24
"usage-scan-cache-v14.json",
25
"usage-scan-cache-v13.json",
26
"usage-scan-cache-v12.json",
@@ -308,9 +309,10 @@ export function decodeScanCache(
309
// A corrupt state disqualifies the entry: resuming with it would attach
310
// appended usage to the wrong model or replay fork-copied history.
311
if (!legacy && !isValidState.get(entry.p)?.(entry.cs)) continue;
311
- // Before v15 the state lacks the latest snapshot time that keeps a re-emitted older snapshot
312
- // from billing twice, so a grown file re-parses whole instead of resuming.
313
- const resumable = !legacy && !(entry.p === "codex" && version < 15);
312
+ // Before v16 a Codex baseline can lack the time of its latest move, or carry an older one,
313
+ // and that time keeps a re-emitted older snapshot from billing twice. A grown file re-parses
314
+ // whole instead of resuming.
315
+ const resumable = !legacy && !(entry.p === "codex" && version < 16);
316
317
const provider = entry.p;
318
const records = decodeRecords(entry.r, provider);