The best way to control Claude Code, Codex and more from any computer or phone
fix(usage): bill Codex requests whose cumulative counters rewind to an earlier snapshot (#29366)
Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Joaquim Peres committed
Nov 12, 2026 at 18:45 UTC
9a614e34a61d4994f1df4a6acd8af86f53ef0013
6 files changed
+225
-29
apps/server/src/provider/Drivers/codexUsage.test.ts
+36
@@ -553,6 +553,42 @@ describe("parseCodexLine", () => {
553
expect(codexUsageFormat.readMalformedRecords?.(state)).toBe(0);
554
});
555
556
+ const later = (line: string) => line.replace("05:17:49.919Z", "07:17:49.919Z");
557
+ it.each([
558
+ {
559
+ name: "bills a later request that continues from an earlier snapshot",
560
+ tail: [
561
+ later(counted(counters(20, 4), counters(130, 26))),
562
+ later(counted(counters(5, 1), counters(135, 27))),
563
+ ],
564
+ processed: [120, 12, 35, 24, 6],
565
+ skipped: 0,
566
+ },
567
+ {
568
+ name: "does not bill a re-emitted earlier snapshot again",
569
+ tail: [counted(counters(10, 2), counters(110, 22))],
570
+ processed: [120, 12, 35, 0],
571
+ skipped: 1,
572
+ },
573
+ ])("$name when cumulative counters rewind", ({ tail, processed, skipped }) => {
574
+ const state = initialCodexScanState();
575
+ parseCodexLine(turnContext, state);
576
+ const billed = [
577
+ counted(counters(100, 20), counters(100, 20)),
578
+ counted(counters(10, 2), counters(110, 22)),
579
+ counted(counters(30, 5), counters(140, 27)),
580
+ ...tail,
581
+ ].map((line) => {
582
+ const record = parseCodexLine(line, state);
583
+ return record === null ? 0 : totalTokens(record.totals);
584
+ });
585
+
586
+ expect({ processed: billed, skipped: codexUsageFormat.readMalformedRecords?.(state) }).toEqual({
587
+ processed,
588
+ skipped,
589
+ });
590
+ });
591
+
592
it("ignores a replay of the current sequence's first request without rewinding the baseline", () => {
593
const state = initialCodexScanState();
594
parseCodexLine(turnContext, state);
apps/server/src/provider/Drivers/codexUsage.ts
+15
-7
@@ -55,8 +55,9 @@ function readCodexTokenUsage(value: unknown): CodexTokenUsage | null {
55
}
56
57
// A zeroed baseline rebases the counters, so the sequence start measured against it is forgotten.
58
-function rebaseCodexUsage(state: CodexScanState, cumulative: CodexTokenUsage) {
58
+function rebaseCodexUsage(state: CodexScanState, cumulative: CodexTokenUsage, timestampMs: number) {
59
state.lastCumulativeUsage = cumulative;
60
+ state.latestCumulativeAtMs = Math.max(state.latestCumulativeAtMs ?? timestampMs, timestampMs);
61
delete state.unreportedRequests;
62
if (cumulative.input_tokens + cumulative.output_tokens === 0) delete state.sequenceStartSignature;
63
}
@@ -121,8 +122,9 @@ export const CodexScanState = Schema.Struct({
122
sessionId: Schema.mutableKey(Schema.String),
123
lastUsageSignature: Schema.mutableKey(Schema.NullOr(Schema.String)),
124
lastCumulativeUsage: Schema.mutableKey(Schema.NullOr(CodexTokenUsage)),
124
- // Optional so scan states cached before this field existed stay valid.
125
+ // Optional so scan states cached before these fields existed stay valid.
126
sequenceStartSignature: Schema.mutableKey(Schema.optionalKey(Schema.String)),
127
+ latestCumulativeAtMs: Schema.mutableKey(Schema.optionalKey(Schema.Finite)),
128
// `token_usage_record` usage since the last cumulative snapshot, one entry per record.
129
unreportedRequests: Schema.mutableKey(
130
Schema.optionalKey(Schema.mutable(Schema.Array(CodexUnreportedRequest))),
@@ -290,7 +292,7 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
292
if (isForkCopy(state, timestampMs)) {
293
// Copied history is already billed in the parent, but establishes the child's baseline.
294
const signature = last === null ? null : JSON.stringify(last);
293
- if (cumulative !== null) rebaseCodexUsage(state, cumulative);
295
+ if (cumulative !== null) rebaseCodexUsage(state, cumulative, timestampMs);
296
else if (!hasCumulative && last !== null && signature !== state.lastUsageSignature) {
297
state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, last);
298
}
@@ -300,14 +302,15 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
302
303
// Context snapshots can rewind on resume and omit compaction spending; identified requests are authoritative.
304
if (state.requestLedgerActive) {
303
- if (cumulative !== null) rebaseCodexUsage(state, cumulative);
305
+ if (cumulative !== null) rebaseCodexUsage(state, cumulative, timestampMs);
306
return [];
307
}
308
309
const previous = state.lastCumulativeUsage;
310
+ const latestCumulativeAtMs = state.latestCumulativeAtMs;
311
const pending = state.unreportedRequests;
312
// A valid snapshot remains the next baseline even when its paired request is malformed.
310
- if (cumulative !== null) rebaseCodexUsage(state, cumulative);
313
+ if (cumulative !== null) rebaseCodexUsage(state, cumulative, timestampMs);
314
if (last === null || (hasCumulative && cumulative === null)) {
315
state.malformedRecords += 1;
316
return [];
@@ -344,10 +347,15 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
347
state.lastCumulativeUsage = previous;
348
return [];
349
}
347
- // Forks and paginated continuations can inherit totals without copying a counter snapshot.
350
+ // Forks and paginated continuations can inherit totals without copying a counter snapshot, and
351
+ // 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.
353
+ const rewound =
354
+ previous !== null &&
355
+ (latestCumulativeAtMs === undefined || timestampMs > latestCumulativeAtMs) &&
356
+ CODEX_USAGE_FIELDS.some((key) => cumulative[key] < previous[key]);
357
const reconciled =
350
- previous === null
358
+ previous === null || rewound
359
? readCodexTokenUsage(
360
Object.fromEntries(CODEX_USAGE_FIELDS.map((key) => [key, cumulative[key] - last[key]])),
361
) !== null
apps/server/src/usage/UsageService.test.ts
+98
-2
@@ -873,6 +873,102 @@ describe("UsageService", () => {
873
}).pipe(Effect.scoped),
874
);
875
876
+ it.live(
877
+ "keeps resolved Codex tiers when a grown pre-v15 cache entry re-parses without history",
878
+ () =>
879
+ Effect.gen(function* () {
880
+ const { home, settings } = yield* setup;
881
+ const sessions = NodePath.join(home, "codex", "sessions");
882
+ const rolloutPath = NodePath.join(sessions, "tier.jsonl");
883
+ const context = (turn_id: string) => ({
884
+ type: "turn_context",
885
+ payload: { model: "gpt-6-astra", turn_id },
886
+ });
887
+ const usage = (output_tokens: number, total_output_tokens: number) => ({
888
+ type: "event_msg",
889
+ timestamp: "2026-08-01T10:00:00Z",
890
+ payload: {
891
+ type: "token_count",
892
+ info: {
893
+ last_token_usage: { input_tokens: 0, output_tokens },
894
+ total_token_usage: { input_tokens: 0, output_tokens: total_output_tokens },
895
+ },
896
+ },
897
+ });
898
+ const lines = (records: readonly unknown[]) =>
899
+ records.map((record) => encodeUnknownJsonString(record)).join("\n") + "\n";
900
+ const verify = (summary: UsageSummary, output: number, cost: number) => {
901
+ assert.strictEqual(totalOutputTokens(summary), output);
902
+ assert.strictEqual(
903
+ summary.buckets.reduce((sum, bucket) => sum + bucket.costUsd, 0),
904
+ cost,
905
+ );
906
+ };
907
+ yield* Effect.promise(async () => {
908
+ await NodeFSP.mkdir(sessions, { recursive: true });
909
+ await NodeFSP.writeFile(
910
+ rolloutPath,
911
+ lines([
912
+ { type: "session_meta", payload: { id: "tier-session", model_provider: "openai" } },
913
+ context("ultra-turn"),
914
+ usage(1, 1),
915
+ // An equal request at the same time, from a turn priced at the standard tier.
916
+ context("standard-turn"),
917
+ usage(1, 2),
918
+ ]),
919
+ );
920
+ });
921
+ yield* Effect.gen(function* () {
922
+ const { stateDir } = yield* ServerConfig.ServerConfig;
923
+ yield* seedCodexHistory({
924
+ id: "ultra-turn",
925
+ sessionId: "tier-session",
926
+ options: [{ id: "serviceTier", value: "ultrafast" }],
927
+ });
928
+ yield* seedCodexHistory({ id: "standard-turn", sessionId: "tier-session", options: [] });
929
+ const first = yield* UsageService.make;
930
+ verify(yield* first.readSummary(WINDOW), 2, 7);
931
+ yield* first.awaitPersisted;
932
+
933
+ // Downgrade the saved cache to v14, whose clean Codex entries cannot resume.
934
+ yield* Effect.promise(async () => {
935
+ const cachePath = NodePath.join(stateDir, SCAN_CACHE_FILE_NAME);
936
+ const document = JSON.parse(await NodeFSP.readFile(cachePath, "utf8"));
937
+ await NodeFSP.rm(cachePath);
938
+ await NodeFSP.writeFile(
939
+ NodePath.join(stateDir, "usage-scan-cache-v14.json"),
940
+ encodeUnknownJsonString({ ...document, version: 14 }),
941
+ );
942
+ await NodeFSP.appendFile(rolloutPath, lines([context("later-turn"), usage(2, 4)]));
943
+ });
944
+ const sql = yield* SqlClient.SqlClient;
945
+ yield* sql`ALTER TABLE orchestration_events RENAME TO unavailable_events`;
946
+ const upgraded = yield* UsageService.make;
947
+ verify(yield* upgraded.readSummary(WINDOW), 4, 9);
948
+ yield* upgraded.awaitPersisted;
949
+ const restarted = yield* UsageService.make;
950
+ verify(yield* restarted.readSummary(WINDOW), 4, 9);
951
+ yield* sql`ALTER TABLE unavailable_events RENAME TO orchestration_events`;
952
+ }).pipe(
953
+ Effect.provide(
954
+ layerService({
955
+ prefix: "usage-reparse-tier",
956
+ home,
957
+ settings,
958
+ ratesDocument: {
959
+ "gpt-6-astra": {
960
+ input_cost_per_token: 0,
961
+ output_cost_per_token: 1,
962
+ input_cost_per_token_ultrafast: 0,
963
+ output_cost_per_token_ultrafast: 6,
964
+ },
965
+ },
966
+ }),
967
+ ),
968
+ );
969
+ }).pipe(Effect.scoped),
970
+ );
971
+
972
it.live(
973
"reads Pi per-model usage and auxiliary costs once across forks and repeated entries",
974
() =>
@@ -2905,7 +3001,7 @@ describe("UsageService", () => {
3001
}).pipe(Effect.scoped),
3002
);
3003
2908
- it.live.each([4, 5, 6, 7, 8, 10, 11, 12, 13])(
3004
+ it.live.each([4, 5, 6, 7, 8, 10, 11, 12, 13, 14])(
3005
"upgrades a v%s cache: reparses live Codex usage, keeps deleted rollouts, removes the old file",
3006
(version) =>
3007
Effect.gen(function* () {
@@ -3006,7 +3102,7 @@ describe("UsageService", () => {
3102
60 + 20 * (version === 4 ? 1 : 2),
3103
);
3104
yield* upgraded.awaitPersisted;
3009
- assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v14.json");
3105
+ assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v15.json");
3106
assert.deepStrictEqual(
3107
(yield* Effect.promise(() => NodeFSP.readdir(stateDir)))
3108
.filter((name) => name.startsWith("usage-scan-cache"))
apps/server/src/usage/UsageService.ts
+34
-11
@@ -553,21 +553,44 @@ export const make = Effect.gen(function* () {
553
failed: true,
554
};
555
556
+ const identity = (record: UsageRecord) =>
557
+ encodeUsageRecordKey([
558
+ record.provider,
559
+ record.sessionId,
560
+ record.timestampMs,
561
+ record.model,
562
+ record.rateModel,
563
+ record.totals,
564
+ record.reportedCostUsd,
565
+ record.dedupeKey,
566
+ ]);
567
+ if (!parsed.resumed && cached !== undefined && cached.provider === provider) {
568
+ // A whole-file re-parse re-emits saved requests unresolved. Keep their saved tier
569
+ // corrections, since the history that resolved them may no longer be available.
570
+ // Equal requests keep their own corrections by matching occurrences in order.
571
+ const saved = new Map<string, UsageRecord[]>();
572
+ for (const previous of [...cached.records, ...cached.tailRecords]) {
573
+ const corrected = correctedRecord(previous);
574
+ const key = identity(corrected);
575
+ const occurrences = saved.get(key);
576
+ if (occurrences === undefined) saved.set(key, [corrected]);
577
+ else occurrences.push(corrected);
578
+ }
579
+ for (const record of [...parsed.records, ...parsed.tailRecords]) {
580
+ const corrected = saved.get(identity(record))?.shift();
581
+ if (
582
+ record.unresolvedServiceTierTurnId !== undefined &&
583
+ corrected !== undefined &&
584
+ corrected.unresolvedServiceTierTurnId === undefined
585
+ ) {
586
+ resolvedRecords.set(record, corrected);
587
+ }
588
+ }
589
+ }
590
if (parsed.resumed && cached !== undefined && cached.tailRecords.length > 0) {
591
// Completing a tentative line reparses it. Reuse its saved correction only when the
592
// same usage is emitted again, without putting inferred tiers in the parser state.
593
const reparsed = [...parsed.records, ...parsed.tailRecords];
560
- const identity = (record: UsageRecord) =>
561
- encodeUsageRecordKey([
562
- record.provider,
563
- record.sessionId,
564
- record.timestampMs,
565
- record.model,
566
- record.rateModel,
567
- record.totals,
568
- record.reportedCostUsd,
569
- record.dedupeKey,
570
- ]);
594
for (const [index, previous] of cached.tailRecords.entries()) {
595
const record = reparsed[index];
596
const corrected = correctedRecord(previous);
apps/server/src/usage/usageScanCache.test.ts
+31
@@ -256,6 +256,37 @@ describe("scan cache round trip", () => {
256
},
257
);
258
259
+ it("re-parses a v14 Codex entry that skipped records and restarts a clean one when it grows", () => {
260
+ const codex = (malformedRecords: number): CachedFile => ({
261
+ size: 10,
262
+ mtimeMs: 100,
263
+ provider: "codex",
264
+ records: [record({ provider: "codex", model: "gpt-6-astra", dedupeKey: null })],
265
+ tailRecords: [],
266
+ malformedRecords,
267
+ position: position({
268
+ state: { ...initialCodexScanState(), model: "gpt-6-astra", sessionId: "session-a" },
269
+ }),
270
+ });
271
+ const original: ScanCache = new Map([
272
+ ["/skipped-codex.jsonl", codex(1)],
273
+ ["/clean-codex.jsonl", codex(0)],
274
+ ]);
275
+ const v14 = { ...parse(makeScanCacheWriter()(original, {})), version: 14 };
276
+
277
+ const restored = decodeScanCache(JSON.parse(JSON.stringify(v14)), TEST_FORMAT_MAP);
278
+ expect(restored.get("/skipped-codex.jsonl")).toEqual({
279
+ ...codex(1),
280
+ size: -1,
281
+ position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
282
+ });
283
+ // Served while unchanged, but its state predates the latest snapshot time, so it cannot resume.
284
+ expect(restored.get("/clean-codex.jsonl")).toEqual({
285
+ ...codex(0),
286
+ position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
287
+ });
288
+ });
289
+
290
it("re-parses a Claude transcript cached before 1-hour cache writes were counted", () => {
291
const original = cacheWith([["/claude.jsonl", 100, [record()]]]);
292
const v12 = { ...parse(makeScanCacheWriter()(original, {})), version: 12 };
apps/server/src/usage/usageScanCache.ts
+11
-9
@@ -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 = 14 as const;
13
+const USAGE_SCAN_CACHE_VERSION = 15 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-v14.json";
21
+export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v15.json";
22
export const LEGACY_SCAN_CACHE_FILE_NAMES = [
23
+ "usage-scan-cache-v14.json",
24
"usage-scan-cache-v13.json",
25
"usage-scan-cache-v12.json",
26
"usage-scan-cache-v11.json",
@@ -297,18 +298,19 @@ export function decodeScanCache(
298
continue;
299
}
300
// Keep history for deleted rollouts, but re-parse incompatible reducer state.
300
- // v14 uses Codex request ledgers, including compaction spending omitted by context snapshots.
301
- // v10 adds Claude advisor calls; before v12 a repeated Claude key kept its first, possibly partial, copy.
302
- // v13 adds Claude 1-hour cache writes.
301
+ // v13 adds Claude 1-hour cache writes; v14 uses Codex request ledgers.
302
+ // v15 repairs skipped Codex requests whose counters rewound; clean v14 entries stay served.
303
const legacy =
304
(entry.p === "claude" && version < 13) ||
305
- (format.state !== undefined && (version < 6 || (entry.p === "codex" && version < 14)));
305
+ (format.state !== undefined &&
306
+ (version < 6 ||
307
+ (entry.p === "codex" && (version < 14 || (version < 15 && malformedRecords > 0)))));
308
// A corrupt state disqualifies the entry: resuming with it would attach
309
// appended usage to the wrong model or replay fork-copied history.
310
if (!legacy && !isValidState.get(entry.p)?.(entry.cs)) continue;
309
- // Before v11 a clean scan could end past an interrupted request whose usage its state dropped,
310
- // so a grown file re-parses whole instead of resuming.
311
- const resumable = !legacy && !(entry.p === "codex" && version < 11);
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);
314
315
const provider = entry.p;
316
const records = decodeRecords(entry.r, provider);