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

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