@devries-cameron20 / t3code-1 / commits / 9ced4f1f45
Fork 0

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);