Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

fix(server): usage no longer double-counts forked Codex sessions (#5887)

Theo Browne0d38866dcf63
diff --git a/apps/server/src/usage/usageScanCache.ts b/apps/server/src/usage/usageScanCache.ts
index 0dafa7a6d..cc15ee9ce 100644
--- a/apps/server/src/usage/usageScanCache.ts
+++ b/apps/server/src/usage/usageScanCache.ts
@@ -18,7 +18,9 @@ import type { UsageProviderKind } from "@t3tools/contracts";
import type { UsageRecord } from "./usageTranscripts.ts";
-export const USAGE_SCAN_CACHE_VERSION = 1 as const;
+// v2: Codex fork-copy suppression changed what a file parses to, so v1
+// entries would keep serving double-counted records forever.
+export const USAGE_SCAN_CACHE_VERSION = 2 as const;
export interface CachedFile {
readonly size: number;
diff --git a/apps/server/src/usage/usageTranscripts.test.ts b/apps/server/src/usage/usageTranscripts.test.ts
index 1fec9d28d..8f86a3d83 100644
--- a/apps/server/src/usage/usageTranscripts.test.ts
+++ b/apps/server/src/usage/usageTranscripts.test.ts
@@ -134,6 +134,106 @@ describe("parseCodexLine", () => {
parseCodexLine(turnContext, state);
expect(parseCodexLine(tokenCount(100, 0, 10, 0), state)).not.toBeNull();
});
+
+ // A forked/subagent rollout opens with the parent's history copied in and
+ // every line re-stamped to the fork instant, then the ancestors' session
+ // metas. Counting those again multiplied usage ~1.85x on real data (#5758).
+ describe("forked rollouts", () => {
+ const meta = (overrides: {
+ id: string;
+ timestamp: string;
+ forkedFromId?: string;
+ spawnParentId?: string;
+ }) =>
+ JSON.stringify({
+ type: "session_meta",
+ timestamp: overrides.timestamp,
+ payload: {
+ type: "session_meta",
+ id: overrides.id,
+ ...(overrides.forkedFromId === undefined
+ ? {}
+ : { forked_from_id: overrides.forkedFromId }),
+ ...(overrides.spawnParentId === undefined
+ ? {}
+ : {
+ source: {
+ subagent: { thread_spawn: { parent_thread_id: overrides.spawnParentId } },
+ },
+ }),
+ },
+ });
+ const stamped = (timestamp: string, line: string) => {
+ const parsed = JSON.parse(line) as { timestamp: string };
+ parsed.timestamp = timestamp;
+ return JSON.stringify(parsed);
+ };
+
+ it("keeps the child session id over copied ancestor metas", () => {
+ const state = initialCodexScanState();
+ parseCodexLine(meta({ id: "child", timestamp: "2026-08-01T05:00:00.000Z" }), state);
+ parseCodexLine(meta({ id: "parent", timestamp: "2026-08-01T05:00:00.000Z" }), state);
+ parseCodexLine(turnContext, state);
+ const record = parseCodexLine(tokenCount(100, 0, 10, 0), state);
+
+ expect(record?.sessionId).toBe("child");
+ });
+
+ it("drops the re-stamped copied burst and keeps the first real event", () => {
+ const state = initialCodexScanState();
+ const forkInstant = "2026-08-01T05:00:00.000Z";
+ parseCodexLine(meta({ id: "child", timestamp: forkInstant, forkedFromId: "parent" }), state);
+ parseCodexLine(meta({ id: "parent", timestamp: forkInstant }), state);
+ parseCodexLine(stamped(forkInstant, turnContext), state);
+
+ // Copied history: written in one burst at the fork instant.
+ expect(
+ parseCodexLine(stamped("2026-08-01T05:00:00.001Z", tokenCount(100, 0, 10, 0)), state),
+ ).toBeNull();
+ expect(
+ parseCodexLine(stamped("2026-08-01T05:00:00.002Z", tokenCount(200, 0, 20, 0)), state),
+ ).toBeNull();
+
+ // The child's first genuine turn lands seconds later and must count.
+ const real = parseCodexLine(
+ stamped("2026-08-01T05:00:06.000Z", tokenCount(300, 0, 30, 0)),
+ state,
+ );
+ expect(real).not.toBeNull();
+ expect(real?.totals.outputTokens).toBe(30);
+
+ // Suppression never restarts, even for closely spaced later events.
+ const next = parseCodexLine(
+ stamped("2026-08-01T05:00:06.100Z", tokenCount(400, 0, 40, 0)),
+ state,
+ );
+ expect(next).not.toBeNull();
+ });
+
+ it("recognizes subagent spawns without forked_from_id", () => {
+ const state = initialCodexScanState();
+ const spawnInstant = "2026-08-01T05:00:00.000Z";
+ parseCodexLine(
+ meta({ id: "child", timestamp: spawnInstant, spawnParentId: "parent" }),
+ state,
+ );
+ parseCodexLine(stamped(spawnInstant, turnContext), state);
+ expect(
+ parseCodexLine(stamped("2026-08-01T05:00:00.001Z", tokenCount(100, 0, 10, 0)), state),
+ ).toBeNull();
+ });
+
+ it("does not suppress anything in a rollout that is not a fork", () => {
+ const state = initialCodexScanState();
+ parseCodexLine(meta({ id: "root", timestamp: "2026-08-01T05:00:00.000Z" }), state);
+ parseCodexLine(stamped("2026-08-01T05:00:00.100Z", turnContext), state);
+ const record = parseCodexLine(
+ stamped("2026-08-01T05:00:00.200Z", tokenCount(100, 0, 10, 0)),
+ state,
+ );
+ expect(record).not.toBeNull();
+ });
+ });
});
describe("totalTokens", () => {
diff --git a/apps/server/src/usage/usageTranscripts.ts b/apps/server/src/usage/usageTranscripts.ts
index 338713d8b..49f9a1935 100644
--- a/apps/server/src/usage/usageTranscripts.ts
+++ b/apps/server/src/usage/usageTranscripts.ts
@@ -151,10 +151,42 @@ export interface CodexScanState {
model: string;
sessionId: string;
lastUsageSignature: string | null;
+ sawSessionMeta: boolean;
+ /** While true, leading usage events are re-stamped copies of parent history. */
+ suppressingForkCopies: boolean;
+ forkCopyAnchorMs: number;
}
export function initialCodexScanState(): CodexScanState {
- return { model: "", sessionId: "", lastUsageSignature: null };
+ return {
+ model: "",
+ sessionId: "",
+ lastUsageSignature: null,
+ sawSessionMeta: false,
+ suppressingForkCopies: false,
+ forkCopyAnchorMs: 0,
+ };
+}
+
+/**
+ * A forked or subagent rollout opens with the parent's full history copied in,
+ * every line re-stamped to the fork instant. Those copies are written in one
+ * synchronous burst (observed gaps 0-40ms), while the child's first genuine
+ * usage event only lands after a real model turn (observed 5s+). One second of
+ * separation splits the two cleanly; `ccusage` uses the same threshold.
+ */
+const FORK_COPY_MAX_GAP_MS = 1000;
+
+/** Whether a `session_meta` payload marks the rollout as a fork or subagent. */
+function isForkedSessionMeta(payload: Record<string, unknown>): boolean {
+ if (typeof payload["forked_from_id"] === "string") return true;
+ const source = payload["source"];
+ if (typeof source !== "object" || source === null) return false;
+ const subagent = (source as Record<string, unknown>)["subagent"];
+ if (typeof subagent !== "object" || subagent === null) return false;
+ const spawn = (subagent as Record<string, unknown>)["thread_spawn"];
+ if (typeof spawn !== "object" || spawn === null) return false;
+ return typeof (spawn as Record<string, unknown>)["parent_thread_id"] === "string";
}
/**
@@ -181,8 +213,18 @@ export function parseCodexLine(line: string, state: CodexScanState): UsageRecord
const payloadType = payloadRecord["type"];
if (record["type"] === "session_meta") {
+ // Only the first meta describes this file's own session. A forked rollout
+ // repeats the ancestors' metas right after it; letting those through would
+ // reassign every subsequent record to an ancestor session.
+ if (state.sawSessionMeta) return null;
+ state.sawSessionMeta = true;
const id = payloadRecord["id"] ?? payloadRecord["session_id"];
if (typeof id === "string") state.sessionId = id;
+ const metaTimestampMs = parseTimestampMs(record["timestamp"]);
+ if (metaTimestampMs !== null && isForkedSessionMeta(payloadRecord)) {
+ state.suppressingForkCopies = true;
+ state.forkCopyAnchorMs = metaTimestampMs;
+ }
return null;
}
@@ -213,6 +255,17 @@ export function parseCodexLine(line: string, state: CodexScanState): UsageRecord
if (signature === state.lastUsageSignature) return null;
state.lastUsageSignature = signature;
+ // In a forked rollout the copied parent history was already counted from the
+ // parent's own file. Drop the leading burst; the first usage event separated
+ // from its predecessor by a real turn's worth of time ends it for good.
+ if (state.suppressingForkCopies) {
+ if (timestampMs - state.forkCopyAnchorMs < FORK_COPY_MAX_GAP_MS) {
+ state.forkCopyAnchorMs = timestampMs;
+ return null;
+ }
+ state.suppressingForkCopies = false;
+ }
+
const inputTokens = int(lastRecord["input_tokens"]);
const cachedInputTokens = int(lastRecord["cached_input_tokens"]);
const cacheCreationTokens = int(lastRecord["cache_write_input_tokens"]);
@@ -238,7 +291,8 @@ export function parseCodexLine(line: string, state: CodexScanState): UsageRecord
totals,
// Codex does not report cost in the rollout.
reportedCostUsd: null,
- // Rollout files are unique per session, so events need no global dedup.
+ // Events surviving the fork-copy suppression above are unique to this
+ // rollout, so they need no global dedup.
dedupeKey: null,
};
}