botmux 3.10.0 → 3.11.0

package/dist/core/cost-calculator.d.ts

@@ -55,6 +55,19 @@ type CachedUsageKind = UsageKind | 'aiden';
 /** Token usage is advisory. Never let dashboard row rendering synchronously
  *  scan pathological multi-GB transcripts. */
 export declare const MAX_USAGE_TRANSCRIPT_BYTES: number;
+/** Codex token_count events are cumulative snapshots, so an oversized cold
+ *  restore starts from a bounded tail window and recovers the latest usage
+ *  card from it. Real 150MiB+ rollouts almost always carry a token_count
+ *  snapshot in the last 4MiB, so this window is the common-case fast path. */
+export declare const CODEX_USAGE_TRANSCRIPT_TAIL_BYTES: number;
+/** When the last tail window is missing a metric (a single huge turn can push
+ *  the newest token_count snapshot — or the model line — out of it), do ONE
+ *  bounded widen to this size and re-scan that whole window. It is the width of
+ *  the single widened pass, NOT a cumulative ladder: the worst-case synchronous
+ *  dashboard read is `tail + this`, and past it we fail closed (yield whatever
+ *  the widened window found, never inheriting a possibly-stale value across an
+ *  unverifiable generation boundary). */
+export declare const CODEX_USAGE_MAX_BACKSCAN_BYTES: number;
 export declare function __resetSessionUsageCachesForTest(): void;
 /** Read a transcript's token usage through the stat/incremental cache.
  *  This is the reusable entry point for dashboard rows and, later, the

package/dist/core/cost-calculator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cost-calculator.d.ts","sourceRoot":"","sources":["../../src/core/cost-calculator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAgBtD,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;SAIS;AACT,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;gFAIgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;kEAC8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;sFACkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjF;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAOjF;AAqID;+EAC+E;AAC/E,KAAK,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AA6OhE,KAAK,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC;AAoB3C;8CAC8C;AAC9C,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAO3D,wBAAgB,gCAAgC,IAAI,IAAI,CAIvD;AAiJD;;+BAE+B;AAC/B,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,iBAAiB,GAAG,IAAI,CAEnI;AA4ED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,sBAAsB,GAAG,iBAAiB,GAAG,IAAI,CAExF;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,sBAAsB,GAAG,oBAAoB,CAevF;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C"}
+{"version":3,"file":"cost-calculator.d.ts","sourceRoot":"","sources":["../../src/core/cost-calculator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAgBtD,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;SAIS;AACT,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;gFAIgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;kEAC8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;sFACkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjF;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAOjF;AAwID;+EAC+E;AAC/E,KAAK,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAmRhE,KAAK,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC;AAwB3C;8CAC8C;AAC9C,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAC3D;;;8EAG8E;AAC9E,eAAO,MAAM,iCAAiC,QAAkB,CAAC;AAEjE;;;;;;yCAMyC;AACzC,eAAO,MAAM,8BAA8B,QAAmB,CAAC;AAO/D,wBAAgB,gCAAgC,IAAI,IAAI,CAIvD;AA0fD;;+BAE+B;AAC/B,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,iBAAiB,GAAG,IAAI,CAEnI;AA4ED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,sBAAsB,GAAG,iBAAiB,GAAG,IAAI,CAExF;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,sBAAsB,GAAG,oBAAoB,CAevF;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/core/cost-calculator.js

@@ -1,11 +1,11 @@
 /**
  * Session cost calculator — computes token usage from JSONL logs.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
 import { logger } from '../utils/logger.js';
 import { findAidenLatestCheckpointByBotmuxSessionId, findAidenLatestCheckpointBySessionId } from '../services/aiden-checkpoints.js';
 import { __resetTranscriptResolverCacheForTest, cachedTranscriptPathLookup, resolveSessionTranscriptPath, } from '../services/transcript-resolver.js';
-import { scanJsonlFromOffset } from '../services/jsonl-cursor.js';
+import { scanJsonlFromFd, scanJsonlFromOffset } from '../services/jsonl-cursor.js';
 import { isMeaningfulQueuedCommand, isMeaningfulUserEvent, } from '../services/claude-transcript.js';
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 export function getSessionJsonlPath(sessionId, cwd) {
@@ -123,6 +123,16 @@ function extractCodexContextUsage(entry) {
         ...(percentUsed !== undefined ? { percentUsed } : {}),
     };
 }
+const CODEX_USAGE_SOURCE_RECORD_MAX_BYTES = 64 * 1024;
+function sourceRecordForLine(line, lineStart) {
+    if (lineStart === undefined || lineStart < 0)
+        return null;
+    if (Buffer.byteLength(line, 'utf8') > CODEX_USAGE_SOURCE_RECORD_MAX_BYTES)
+        return null;
+    return {
+        offset: lineStart,
+    };
+}
 function usageKindForCli(cliId) {
     switch (cliId) {
         case 'claude-code':
@@ -155,6 +165,9 @@ function newTokenUsageAggregate() {
         turns: 0,
         latestCodexUsage: null,
         latestContextUsage: null,
+        latestCodexUsageSource: null,
+        latestContextUsageSource: null,
+        modelSource: null,
         turnInputTokens: 0,
         turnOutputTokens: 0,
     };
@@ -217,18 +230,28 @@ function foldClaudeLine(agg, seenMessageIds, entry) {
 /** Codex rollouts report cumulative totals via event_msg/token_count; only
  *  the latest snapshot counts. The active model rides on turn_context /
  *  session_meta payloads (latest wins — sessions can switch models). */
-function foldCodexLine(agg, entry) {
+function foldCodexLine(agg, entry, getSource) {
     const contextUsage = extractCodexContextUsage(entry);
-    if (contextUsage)
+    let source;
+    const sourceForTrackedMetric = () => {
+        source ??= getSource();
+        return source;
+    };
+    if (contextUsage) {
         agg.latestContextUsage = contextUsage;
+        agg.latestContextUsageSource = sourceForTrackedMetric();
+    }
     const codexUsage = extractCodexTokenCountUsage(entry);
     if (codexUsage) {
         agg.latestCodexUsage = codexUsage;
+        agg.latestCodexUsageSource = sourceForTrackedMetric();
         return;
     }
     const m = entry?.payload?.model ?? entry?.payload?.collaboration_mode?.settings?.model;
-    if (typeof m === 'string' && m)
+    if (typeof m === 'string' && m) {
         agg.model = m;
+        agg.modelSource = sourceForTrackedMetric();
+    }
 }
 /** CoCo events: only assistant messages with response_meta.usage count; the
  *  agent_end summary repeats the last turn's usage and must not be counted. */
@@ -300,12 +323,12 @@ function foldGenericLine(agg, seenMessageIds, entry) {
         agg.model = native.model;
     agg.turns++;
 }
-function foldUsageLine(kind, agg, seenMessageIds, entry) {
+function foldUsageLine(kind, agg, seenMessageIds, entry, getSource) {
     switch (kind) {
         case 'claude':
             return foldClaudeLine(agg, seenMessageIds, entry);
         case 'codex':
-            return foldCodexLine(agg, entry);
+            return foldCodexLine(agg, entry, getSource ?? (() => null));
         case 'coco':
             return foldCocoLine(agg, entry);
         case 'pi':
@@ -322,7 +345,7 @@ function readTokenUsageAggregate(path, kind) {
     try {
         let scanError = null;
         const scanned = scanJsonlFromOffset(path, 0, {
-            onLine: (line) => foldUsageJsonLine(kind, agg, seenMessageIds, line),
+            onLine: (line, lineStart) => foldUsageJsonLine(kind, agg, seenMessageIds, line, lineStart),
             onError: (error) => { scanError = error; },
         });
         if (!scanned)
@@ -362,6 +385,20 @@ const USAGE_REPARSE_MIN_INTERVAL_MS = 15_000;
 /** Token usage is advisory. Never let dashboard row rendering synchronously
  *  scan pathological multi-GB transcripts. */
 export const MAX_USAGE_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+/** Codex token_count events are cumulative snapshots, so an oversized cold
+ *  restore starts from a bounded tail window and recovers the latest usage
+ *  card from it. Real 150MiB+ rollouts almost always carry a token_count
+ *  snapshot in the last 4MiB, so this window is the common-case fast path. */
+export const CODEX_USAGE_TRANSCRIPT_TAIL_BYTES = 4 * 1024 * 1024;
+const CODEX_USAGE_REPLAY_BYTES = 4 * 1024 * 1024;
+/** When the last tail window is missing a metric (a single huge turn can push
+ *  the newest token_count snapshot — or the model line — out of it), do ONE
+ *  bounded widen to this size and re-scan that whole window. It is the width of
+ *  the single widened pass, NOT a cumulative ladder: the worst-case synchronous
+ *  dashboard read is `tail + this`, and past it we fail closed (yield whatever
+ *  the widened window found, never inheriting a possibly-stale value across an
+ *  unverifiable generation boundary). */
+export const CODEX_USAGE_MAX_BACKSCAN_BYTES = 32 * 1024 * 1024;
 /** Aiden checkpoint paths move as the session progresses (latest.json points
  *  at a new checkpoint id per turn), so positive hits expire quickly too. */
 const AIDEN_PATH_HIT_TTL_MS = 15_000;
@@ -384,14 +421,337 @@ function foldUsageText(kind, agg, seenMessageIds, text) {
         catch { /* skip malformed lines */ }
     }
 }
-function foldUsageJsonLine(kind, agg, seenMessageIds, line) {
+function foldUsageJsonLine(kind, agg, seenMessageIds, line, lineStart) {
     if (!line.trim())
         return;
     try {
-        foldUsageLine(kind, agg, seenMessageIds, JSON.parse(line));
+        const entry = JSON.parse(line);
+        if (kind !== 'codex') {
+            foldUsageLine(kind, agg, seenMessageIds, entry);
+            return;
+        }
+        let sourceCalculated = false;
+        let source = null;
+        foldUsageLine(kind, agg, seenMessageIds, entry, () => {
+            if (!sourceCalculated) {
+                source = sourceRecordForLine(line, lineStart);
+                sourceCalculated = true;
+            }
+            return source;
+        });
     }
     catch { /* skip malformed lines */ }
 }
+function readFdProbe(fd, offset, length) {
+    if (length <= 0)
+        return Buffer.alloc(0);
+    try {
+        const buf = Buffer.alloc(length);
+        const read = readSync(fd, buf, 0, length, offset);
+        return buf.subarray(0, read);
+    }
+    catch {
+        return null;
+    }
+}
+function isJsonlLineBoundaryFd(fd, offset) {
+    if (offset <= 0)
+        return true;
+    const probe = readFdProbe(fd, offset - 1, 1);
+    return !!probe && probe.length === 1 && probe[0] === 0x0a;
+}
+function aggregateHasCodexUsage(agg) {
+    return !!agg.latestCodexUsage || !!agg.latestContextUsage;
+}
+/** The two cumulative-usage metrics recovered. Used to decide when the bounded
+ *  widen can stop: cumulative and context can sit on different lines, so a
+ *  window that caught only one is not complete. Model is handled separately
+ *  (see the model back-fill below) — it is a stable session-level attribute, so
+ *  gating the (bounded) widen on it would force a re-scan for every rollout that
+ *  simply never re-emits a model line inside the tail window. */
+function aggregateHasAllCodexMetrics(agg) {
+    return !!agg.latestCodexUsage && !!agg.latestContextUsage;
+}
+function ensureUsageFileCacheCapacity(key) {
+    if (usageFileCache.size >= USAGE_FILE_CACHE_MAX_ENTRIES && !usageFileCache.has(key)) {
+        const oldest = usageFileCache.keys().next().value;
+        if (oldest !== undefined)
+            usageFileCache.delete(oldest);
+    }
+}
+function canReuseUsageCache(cached, st) {
+    if (!cached.canReadIncrementally)
+        return false;
+    if (st.size < cached.offset)
+        return false;
+    return cached.dev === st.dev && cached.ino === st.ino;
+}
+function earliestCodexReplaySourceOffset(previous) {
+    if (!previous)
+        return null;
+    const offsets = [];
+    if (previous.latestCodexUsage) {
+        if (!previous.latestCodexUsageSource)
+            return null;
+        offsets.push(previous.latestCodexUsageSource.offset);
+    }
+    if (previous.latestContextUsage) {
+        if (!previous.latestContextUsageSource)
+            return null;
+        offsets.push(previous.latestContextUsageSource.offset);
+    }
+    if (previous.model) {
+        if (!previous.modelSource)
+            return null;
+        offsets.push(previous.modelSource.offset);
+    }
+    return offsets.length > 0 ? Math.min(...offsets) : null;
+}
+function cacheUsageRead(key, st, entry) {
+    ensureUsageFileCacheCapacity(key);
+    usageFileCache.set(key, {
+        ...entry,
+        mtimeMs: st.mtimeMs,
+        ctimeMs: st.ctimeMs,
+        size: st.size,
+        dev: st.dev,
+        ino: st.ino,
+    });
+}
+function readCodexTokenAggregateCached(key, path, st, cached, now, retryOnRace = true) {
+    let fd = null;
+    let fdStat;
+    try {
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+        fdStat = fstatSync(fd);
+        if (!fdStat.isFile()) {
+            closeSync(fd);
+            usageFileCache.delete(key);
+            return { agg: newTokenUsageAggregate(), result: null };
+        }
+    }
+    catch (error) {
+        if (fd !== null)
+            closeSync(fd);
+        logger.error(`Failed to open Codex transcript ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        usageFileCache.delete(key);
+        return null;
+    }
+    if (fdStat.dev !== st.dev || fdStat.ino !== st.ino || fdStat.size !== st.size) {
+        closeSync(fd);
+        usageFileCache.delete(key);
+        if (retryOnRace) {
+            return readCodexTokenAggregateCached(key, path, fdStat, undefined, now, false);
+        }
+        return { agg: newTokenUsageAggregate(), result: null };
+    }
+    let state;
+    let seenMessageIds;
+    let baseOffset = 0;
+    const previousAgg = cached?.previewAgg ? cloneAggregate(cached.previewAgg) : undefined;
+    const sameOpenFileAsCache = !!cached
+        && cached.dev === fdStat.dev
+        && cached.ino === fdStat.ino;
+    const canConsiderReplay = !!cached
+        && sameOpenFileAsCache
+        && cached.canReadIncrementally
+        && cached.offset > 0
+        && fdStat.size >= cached.offset;
+    const oversized = fdStat.size > MAX_USAGE_TRANSCRIPT_BYTES;
+    const candidateReplayBaseOffset = canConsiderReplay
+        ? earliestCodexReplaySourceOffset(previousAgg)
+        : null;
+    const candidateReplaySpan = candidateReplayBaseOffset === null
+        ? Number.POSITIVE_INFINITY
+        : fdStat.size - candidateReplayBaseOffset;
+    const replayBaseOffset = candidateReplaySpan <= CODEX_USAGE_REPLAY_BYTES
+        && candidateReplayBaseOffset !== null
+        && isJsonlLineBoundaryFd(fd, candidateReplayBaseOffset)
+        ? candidateReplayBaseOffset
+        : null;
+    const replaySpan = replayBaseOffset === null ? Number.POSITIVE_INFINITY : fdStat.size - replayBaseOffset;
+    const reuseTrackedReplay = replayBaseOffset !== null && replaySpan <= CODEX_USAGE_REPLAY_BYTES;
+    const scanFromWindow = (from, knownLineBoundary) => {
+        const windowState = newTokenUsageAggregate();
+        const windowSeen = new Set();
+        // Replay/full-file reads start on a proven line boundary (offset 0, or an
+        // offset already validated by isJsonlLineBoundaryFd), so they need no extra
+        // probe. Only a widened bounded-tail window lands at an arbitrary byte and
+        // must drop the partial leading record.
+        let dropResidual = !knownLineBoundary && from > 0 && !isJsonlLineBoundaryFd(fd, from);
+        let droppedResidual = false;
+        let windowScanError = null;
+        const windowScanned = scanJsonlFromFd(fd, from, {
+            endOffset: fdStat.size,
+            onLine: (line, lineStart) => {
+                if (dropResidual) {
+                    dropResidual = false;
+                    droppedResidual = true;
+                    return;
+                }
+                foldUsageJsonLine('codex', windowState, windowSeen, line, lineStart);
+            },
+            onError: (error) => { windowScanError = error; },
+        });
+        if (!windowScanned) {
+            logger.error(`Failed to read Codex transcript slice ${path}: ${windowScanError instanceof Error ? windowScanError.message : String(windowScanError)}`);
+            return null;
+        }
+        let windowPreview = windowState;
+        const windowTail = windowScanned.pendingTail.trim();
+        const residualTailPending = dropResidual && !droppedResidual;
+        if (windowTail && !residualTailPending) {
+            windowPreview = cloneAggregate(windowState);
+            foldUsageText('codex', windowPreview, new Set(windowSeen), windowTail);
+        }
+        return {
+            state: windowState,
+            seenMessageIds: windowSeen,
+            scanned: windowScanned,
+            completeBytes: windowScanned.newOffset - from,
+            previewAgg: windowPreview,
+            pendingTailIsInitialResidualLine: residualTailPending,
+        };
+    };
+    let scanned;
+    let completeBytes;
+    let previewAgg;
+    let pendingTailIsInitialResidualLine;
+    if (reuseTrackedReplay) {
+        baseOffset = replayBaseOffset;
+        const win = scanFromWindow(baseOffset, true);
+        if (!win) {
+            closeSync(fd);
+            usageFileCache.delete(key);
+            return null;
+        }
+        ({ state, seenMessageIds, scanned, completeBytes, previewAgg, pendingTailIsInitialResidualLine } = win);
+    }
+    else if (!oversized) {
+        baseOffset = 0;
+        const win = scanFromWindow(baseOffset, true);
+        if (!win) {
+            closeSync(fd);
+            usageFileCache.delete(key);
+            return null;
+        }
+        ({ state, seenMessageIds, scanned, completeBytes, previewAgg, pendingTailIsInitialResidualLine } = win);
+    }
+    else {
+        // Oversized cold/bounded read. Fast path: scan the last tail window. Widen
+        // ONCE to the back-scan budget and re-scan that whole window when the fast
+        // path is incomplete — either the two usage metrics (cumulative/context)
+        // are not both present, or this session is KNOWN to carry a model (the
+        // cached read had one) but the fast window has none. A single >4MiB turn can
+        // push the newest token_count — or a just-switched model line — out of the
+        // tail window; the widen recovers the true latest of all of them. A single
+        // widened pass (not a 4/8/.../32 ladder) keeps the worst-case synchronous
+        // read at tail + budget, not their sum. Each pass scans from a fresh state;
+        // Codex token_count/model are latest-wins, so re-folding older lines first
+        // and letting the newest overwrite last is exact. Model is NOT inherited
+        // from cache: a widen that still finds none fails closed to empty rather
+        // than risk shipping a stale model (which mis-prices the ledger) after an
+        // append-only model switch.
+        const cachedHadModel = sameOpenFileAsCache && !!previousAgg?.model;
+        baseOffset = Math.max(0, fdStat.size - CODEX_USAGE_TRANSCRIPT_TAIL_BYTES);
+        let win = scanFromWindow(baseOffset, false);
+        if (!win) {
+            closeSync(fd);
+            usageFileCache.delete(key);
+            return null;
+        }
+        const fastPathIncomplete = !aggregateHasAllCodexMetrics(win.previewAgg)
+            || (cachedHadModel && !win.previewAgg.model);
+        if (fastPathIncomplete && baseOffset > 0) {
+            const widenedBaseOffset = Math.max(0, fdStat.size - CODEX_USAGE_MAX_BACKSCAN_BYTES);
+            if (widenedBaseOffset < baseOffset) {
+                const widened = scanFromWindow(widenedBaseOffset, false);
+                if (!widened) {
+                    closeSync(fd);
+                    usageFileCache.delete(key);
+                    return null;
+                }
+                baseOffset = widenedBaseOffset;
+                win = widened;
+            }
+        }
+        ({ state, seenMessageIds, scanned, completeBytes, previewAgg, pendingTailIsInitialResidualLine } = win);
+    }
+    const nextOffset = pendingTailIsInitialResidualLine ? baseOffset : baseOffset + completeBytes;
+    let endStat;
+    try {
+        endStat = fstatSync(fd);
+    }
+    catch {
+        closeSync(fd);
+        usageFileCache.delete(key);
+        return { agg: newTokenUsageAggregate(), result: null };
+    }
+    if (endStat.dev !== fdStat.dev
+        || endStat.ino !== fdStat.ino
+        || endStat.size !== fdStat.size
+        || endStat.mtimeMs !== fdStat.mtimeMs
+        || endStat.ctimeMs !== fdStat.ctimeMs) {
+        closeSync(fd);
+        usageFileCache.delete(key);
+        if (retryOnRace) {
+            return readCodexTokenAggregateCached(key, path, endStat, undefined, now, false);
+        }
+        return { agg: newTokenUsageAggregate(), result: null };
+    }
+    let pathStat;
+    try {
+        pathStat = statSync(path);
+    }
+    catch {
+        closeSync(fd);
+        usageFileCache.delete(key);
+        return { agg: newTokenUsageAggregate(), result: null };
+    }
+    if (pathStat.dev !== fdStat.dev
+        || pathStat.ino !== fdStat.ino
+        || pathStat.size !== fdStat.size
+        || pathStat.mtimeMs !== fdStat.mtimeMs
+        || pathStat.ctimeMs !== fdStat.ctimeMs) {
+        closeSync(fd);
+        usageFileCache.delete(key);
+        if (retryOnRace) {
+            return readCodexTokenAggregateCached(key, path, pathStat, undefined, now, false);
+        }
+        return { agg: newTokenUsageAggregate(), result: null };
+    }
+    if (pendingTailIsInitialResidualLine) {
+        // The bounded window starts in the middle of a JSONL record and no newline
+        // has arrived yet. Cache safe stat/throttle metadata only; the stored
+        // offset is not a reusable durable cursor, so any later change reboots from
+        // a bounded tail instead of turning that suffix into a fake complete line.
+        const result = finalizeTokenUsage(previewAgg);
+        cacheUsageRead(key, fdStat, {
+            offset: nextOffset,
+            state,
+            seenMessageIds,
+            previewAgg,
+            result,
+            parsedAtMs: now,
+            canReadIncrementally: false,
+        });
+        closeSync(fd);
+        return { agg: previewAgg, result };
+    }
+    const result = finalizeTokenUsage(previewAgg);
+    const canReadIncrementally = aggregateHasCodexUsage(previewAgg);
+    cacheUsageRead(key, fdStat, {
+        offset: nextOffset,
+        state,
+        seenMessageIds,
+        previewAgg,
+        result,
+        parsedAtMs: now,
+        canReadIncrementally,
+    });
+    closeSync(fd);
+    return { agg: previewAgg, result };
+}
 function readSessionTokenAggregateCached(path, kind, opts) {
     const key = `${kind}:${path}`;
     let st = null;
@@ -402,8 +762,11 @@ function readSessionTokenAggregateCached(path, kind, opts) {
         st = null;
     }
     if (!st) {
-        // Unstat-able (file gone, or mocked fs in unit tests): parse directly, uncached.
         usageFileCache.delete(key);
+        if (kind === 'codex') {
+            return { agg: newTokenUsageAggregate(), result: null };
+        }
+        // Unstat-able (file gone, or mocked fs in unit tests): parse directly, uncached.
         if (kind === 'aiden') {
             const result = readTokenUsageFromAidenCheckpoint(path);
             return result ? { agg: newTokenUsageAggregate(), result } : null;
@@ -413,13 +776,16 @@ function readSessionTokenAggregateCached(path, kind, opts) {
     }
     const now = Date.now();
     const cached = usageFileCache.get(key);
-    if (cached) {
-        const unchanged = cached.mtimeMs === st.mtimeMs && cached.size === st.size;
+    if (cached && cached.dev === st.dev && cached.ino === st.ino) {
+        const unchanged = cached.mtimeMs === st.mtimeMs && cached.ctimeMs === st.ctimeMs && cached.size === st.size;
         const throttled = !opts?.fresh && now - cached.parsedAtMs < USAGE_REPARSE_MIN_INTERVAL_MS;
         if (unchanged || throttled) {
             return { agg: cached.previewAgg, result: cached.result };
         }
     }
+    if (kind === 'codex') {
+        return readCodexTokenAggregateCached(key, path, st, cached, now);
+    }
     if (st.size > MAX_USAGE_TRANSCRIPT_BYTES) {
         // Warn once per transcript, not per observed size: an actively-growing
         // oversized file would otherwise re-warn and leak a Set entry every reparse.
@@ -432,31 +798,25 @@ function readSessionTokenAggregateCached(path, kind, opts) {
             return { agg: cached.previewAgg, result: cached.result };
         return { agg: newTokenUsageAggregate(), result: null };
     }
-    if (usageFileCache.size >= USAGE_FILE_CACHE_MAX_ENTRIES && !usageFileCache.has(key)) {
-        const oldest = usageFileCache.keys().next().value;
-        if (oldest !== undefined)
-            usageFileCache.delete(oldest);
-    }
     if (kind === 'aiden') {
         // Checkpoints are rewritten whole — nothing incremental to exploit.
         const result = readTokenUsageFromAidenCheckpoint(path);
         const blank = newTokenUsageAggregate();
-        usageFileCache.set(key, {
-            mtimeMs: st.mtimeMs,
-            size: st.size,
+        cacheUsageRead(key, st, {
             offset: -1,
             state: blank,
             seenMessageIds: new Set(),
             previewAgg: blank,
             result,
             parsedAtMs: now,
+            canReadIncrementally: false,
         });
         return { agg: blank, result };
     }
     let state;
     let seenMessageIds;
     let baseOffset;
-    if (cached && cached.offset > 0 && st.size >= cached.offset) {
+    if (cached && cached.offset > 0 && canReuseUsageCache(cached, st)) {
         // Append-only growth: continue folding from the durable frontier.
         state = cached.state;
         seenMessageIds = cached.seenMessageIds;
@@ -470,7 +830,7 @@ function readSessionTokenAggregateCached(path, kind, opts) {
     let scanError = null;
     const scanned = scanJsonlFromOffset(path, baseOffset, {
         endOffset: st.size,
-        onLine: (line) => foldUsageJsonLine(kind, state, seenMessageIds, line),
+        onLine: (line, lineStart) => foldUsageJsonLine(kind, state, seenMessageIds, line, lineStart),
         onError: (error) => { scanError = error; },
     });
     if (!scanned) {
@@ -490,15 +850,14 @@ function readSessionTokenAggregateCached(path, kind, opts) {
         foldUsageText(kind, previewAgg, new Set(seenMessageIds), tailText);
     }
     const result = finalizeTokenUsage(previewAgg);
-    usageFileCache.set(key, {
-        mtimeMs: st.mtimeMs,
-        size: st.size,
+    cacheUsageRead(key, st, {
         offset: baseOffset + completeBytes,
         state,
         seenMessageIds,
         previewAgg,
         result,
         parsedAtMs: now,
+        canReadIncrementally: true,
     });
     return { agg: previewAgg, result };
 }