tokentracker-cli 0.84.4 → 0.84.6

package/src/commands/sync.js

@@ -113,6 +113,11 @@ const {
 } = require("../lib/cursor-store");
 const { resolveTrackerPaths } = require("../lib/tracker-paths");
 const { resolveRuntimeConfig } = require("../lib/runtime-config");
+const { extractTokenCount } = require("../lib/codex-rollout-parser");
+const {
+  consumeUsageDelta,
+  createUsageDeltaState,
+} = require("../lib/codex-token-usage");
 
 const CURSOR_UNKNOWN_MIGRATION_KEY = "cursorUnknownPurge_2026_04";
 const ROLLOUT_CUMULATIVE_DELTA_MIGRATION_KEY = "rolloutCumulativeDeltaReparse_2026_05";
@@ -189,6 +194,14 @@ const CODEX_RESCAN_DEDUP_REPAIR_KEY = "codexRescanDedupRepair_2026_06";
 // offset reset for the cloud overwrite). Pre-gated: installs with no forked
 // rollout on disk carry no fork phantom and mark done without the rebuild.
 const CODEX_FORK_REPLAY_REPAIR_KEY = "codexForkReplayRepair_2026_07";
+// One-time repair for Codex rollouts that contain token counters from multiple
+// interleaved SessionState instances. Older parsers subtracted each cumulative
+// total from the most recently observed total, even when it belonged to another
+// state, which could turn an ordinary turn into a multi-billion-token delta.
+const CODEX_USAGE_LINEAGE_REPAIR_KEY = "codexUsageLineageRepair_2026_07";
+// Keep the one escalated desktop refresh bounded; explicit full syncs can retry
+// the same migration without this ceiling when the history needs a deeper scan.
+const CODEX_BACKGROUND_LINEAGE_SCAN_MAX_BYTES = 1024 * 1024;
 const DROID_DUP_SESSION_REPAIR_KEY = "droidDupSessionInflationRepair_2026_06";
 const CODEX_COLD_SCAN_AUDIT_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const NOTIFY_LOCK_WAIT_MS = 130_000;
@@ -457,6 +470,28 @@ async function cmdSync(argv, context = {}) {
       if (autoSourceScope) return sources.includes(autoSourceScope);
       return true;
     };
+    // Desktop refreshes are deliberately lightweight, but that also means a
+    // migration wired only to full sync would never repair an existing native
+    // install. Escalate exactly the first eligible background run: fresh
+    // installs have no persisted Codex buckets to repair, while retryable
+    // failures remain reserved for an explicit full sync instead of turning
+    // every five-minute refresh into a deep historical scan.
+    const backgroundCodexUsageMigrationEligible = Boolean(
+      isBackgroundLightweightSync &&
+      sourceAllowed("codex") &&
+      !cursors.migrations?.[CODEX_USAGE_LINEAGE_REPAIR_KEY]
+    );
+    const hasPersistedCodexUsage = Object.keys(cursors.hourly?.buckets || {})
+      .some((key) => key.startsWith("codex|"));
+    const backgroundCodexUsageRepair =
+      backgroundCodexUsageMigrationEligible && hasPersistedCodexUsage;
+    if (backgroundCodexUsageMigrationEligible && !hasPersistedCodexUsage) {
+      // A fresh install has no old-parser buckets to repair. Mark it complete
+      // before the first bounded parse so the next refresh does not mistake
+      // newly parsed, already-correct data for legacy history.
+      (cursors.migrations ||= {})[CODEX_USAGE_LINEAGE_REPAIR_KEY] =
+        new Date().toISOString();
+    }
 
     const sources = [];
     if (sourceAllowed("codex")) {
@@ -467,13 +502,13 @@ async function cmdSync(argv, context = {}) {
       const codexPaths = resolveInstallPaths({ nativeValue: codexNativeValue, wslValue: wslCodexDir });
       if (codexPaths.native) {
         sources.push({ source: "codex", sessionsDir: path.join(codexPaths.native, "sessions"), codexInventoryCache: true });
-        if (!isBackgroundLightweightSync) {
+        if (!isBackgroundLightweightSync || backgroundCodexUsageRepair) {
           sources.push({ source: "codex", sessionsDir: path.join(codexPaths.native, "archived_sessions"), deep: true });
         }
       }
       if (codexPaths.wsl) {
         sources.push({ source: "codex", sessionsDir: path.join(codexPaths.wsl, "sessions"), codexInventoryCache: true });
-        if (!isBackgroundLightweightSync) {
+        if (!isBackgroundLightweightSync || backgroundCodexUsageRepair) {
           sources.push({ source: "codex", sessionsDir: path.join(codexPaths.wsl, "archived_sessions"), deep: true });
         }
       }
@@ -523,7 +558,7 @@ async function cmdSync(argv, context = {}) {
         projectQueueStatePath,
         rolloutFiles,
       });
-      await repairCodexForkReplayInflation({
+      const codexForkRepairRan = await repairCodexForkReplayInflation({
         cursors,
         queuePath,
         queueStatePath,
@@ -532,6 +567,15 @@ async function cmdSync(argv, context = {}) {
         rolloutFiles,
         legacyRepairRan: codexRescanRepairRan,
       });
+      await repairCodexInterleavedUsageInflation({
+        cursors,
+        queuePath,
+        queueStatePath,
+        projectQueuePath,
+        projectQueueStatePath,
+        rolloutFiles,
+        legacyRepairRan: codexRescanRepairRan || codexForkRepairRan,
+      });
       await repairDroidDuplicateSessionInflation({ cursors, queuePath, queueStatePath });
       await repairMimoClaudeMislabel({
         cursors,
@@ -540,6 +584,33 @@ async function cmdSync(argv, context = {}) {
         projectQueuePath,
         projectQueueStatePath,
       });
+    } else if (backgroundCodexUsageRepair) {
+      await cursorStore.materializeAllCodexState(cursors);
+      try {
+        await repairCodexInterleavedUsageInflation({
+          cursors,
+          queuePath,
+          queueStatePath,
+          projectQueuePath,
+          projectQueueStatePath,
+          rolloutFiles,
+          maxLineageScanBytes: CODEX_BACKGROUND_LINEAGE_SCAN_MAX_BYTES,
+        });
+      } catch (err) {
+        warnProviderParseFailure("Codex usage lineage repair", err, opts);
+      } finally {
+        // Rebuild failures intentionally leave the migration key unset so a
+        // future full sync can retry. Record a retryable sentinel here to keep
+        // routine native background refreshes bounded after that first attempt.
+        const migrations = (cursors.migrations ||= {});
+        if (!migrations[CODEX_USAGE_LINEAGE_REPAIR_KEY]) {
+          migrations[CODEX_USAGE_LINEAGE_REPAIR_KEY] = {
+            skipped: true,
+            reason: "background_repair_requires_full_sync",
+            at: new Date().toISOString(),
+          };
+        }
+      }
     }
 
     const codexColdSkipEnabled = opts.auto && sourceAllowed("codex");
@@ -1326,8 +1397,9 @@ async function cmdSync(argv, context = {}) {
       );
     }
 
-    // ── Kiro CLI (reads ~/Library/Application Support/kiro-cli/data.sqlite3
-    //    AND live sessions under ~/.kiro/sessions/cli/{uuid}.json) ──
+    // ── Kiro CLI (reads ~/Library/Application Support/kiro-cli/data.sqlite3,
+    //    legacy ~/.kiro/sessions/cli/{uuid}.json, and Kiro CLI 2.13+
+    //    ~/.kiro/sessions/{workspace}/sess_{uuid}/messages.jsonl) ──
     // Runs IN PARALLEL with the Kiro IDE branch above — NOT instead of it.
     // Both emit source='kiro' so totals merge transparently; cursor state
     // is isolated in cursors.kiroCli. Kiro CLI does not persist explicit
@@ -2339,6 +2411,7 @@ module.exports = {
   migrateRolloutCumulativeDeltaBuckets,
   repairCodexRescanInflation,
   repairCodexForkReplayInflation,
+  repairCodexInterleavedUsageInflation,
   repairDroidDuplicateSessionInflation,
   repairMimoClaudeMislabel,
   reincludeClaudeMemObserverFiles,
@@ -2352,6 +2425,7 @@ module.exports = {
   ROLLOUT_CUMULATIVE_DELTA_MIGRATION_KEY,
   CODEX_RESCAN_DEDUP_REPAIR_KEY,
   CODEX_FORK_REPLAY_REPAIR_KEY,
+  CODEX_USAGE_LINEAGE_REPAIR_KEY,
   DROID_DUP_SESSION_REPAIR_KEY,
   CLAUDE_MEM_OBSERVER_REINCLUDE_KEY,
   GROK_APPEND_ONLY_REPAIR_MIGRATION_KEY,
@@ -3828,6 +3902,260 @@ async function repairCodexForkReplayInflation({
   });
 }
 
+// Rebuild historical Codex usage only when a rollout proves that the old
+// single-baseline parser crossed cumulative SessionState lineages. The cheap
+// head gate keeps the one-time migration from fully reading installations that
+// predate Codex multi-agent support; the rebuild itself retains the existing
+// missing-history, project-queue, atomic-swap, and upload-reset guards.
+async function repairCodexInterleavedUsageInflation({
+  cursors,
+  queuePath,
+  queueStatePath,
+  projectQueuePath,
+  projectQueueStatePath,
+  rolloutFiles,
+  // Either older guarded repair rebuilt every Codex file with the current
+  // parser earlier in this sync, so a second full rebuild is unnecessary.
+  legacyRepairRan = false,
+  maxLineageScanBytes = Infinity,
+}) {
+  if (!cursors || typeof cursors !== "object") return false;
+  const migrations = (cursors.migrations ||= {});
+  const prior = migrations[CODEX_USAGE_LINEAGE_REPAIR_KEY];
+  if (prior && !(typeof prior === "object" && prior.skipped)) return false;
+
+  if (legacyRepairRan) {
+    migrations[CODEX_USAGE_LINEAGE_REPAIR_KEY] = new Date().toISOString();
+    return false;
+  }
+
+  const scan = await scanForInterleavedCodexUsage(rolloutFiles, {
+    maxLineageScanBytes,
+  });
+  if (scan.indeterminate) {
+    migrations[CODEX_USAGE_LINEAGE_REPAIR_KEY] = {
+      skipped: true,
+      reason: "usage_lineage_scan_indeterminate",
+      at: new Date().toISOString(),
+    };
+    return false;
+  }
+
+  if (!scan.affected) {
+    if (!isCodexHistoryCovered(cursors, rolloutFiles)) {
+      migrations[CODEX_USAGE_LINEAGE_REPAIR_KEY] = {
+        skipped: true,
+        reason: "codex_history_not_covered",
+        at: new Date().toISOString(),
+      };
+      return false;
+    }
+    migrations[CODEX_USAGE_LINEAGE_REPAIR_KEY] = new Date().toISOString();
+    return false;
+  }
+
+  return repairCodexRescanInflation({
+    cursors,
+    queuePath,
+    queueStatePath,
+    projectQueuePath,
+    projectQueueStatePath,
+    rolloutFiles,
+    migrationKey: CODEX_USAGE_LINEAGE_REPAIR_KEY,
+    uploadNote: "reset_after_codex_usage_lineage_2026_07",
+  });
+}
+
+async function scanForInterleavedCodexUsage(
+  rolloutFiles,
+  { maxLineageScanBytes = Infinity } = {},
+) {
+  for (const entry of Array.isArray(rolloutFiles) ? rolloutFiles : []) {
+    const fp = typeof entry === "string" ? entry : entry?.path;
+    const src = typeof entry === "string" ? "codex" : String(entry?.source || "codex");
+    if (!fp || src !== "codex") continue;
+
+    const head = await scanCodexMultiAgentHead(fp);
+    if (head.indeterminate) return { affected: false, indeterminate: true };
+    if (!head.candidate) continue;
+
+    const lineage = await scanCodexUsageLineages(fp, maxLineageScanBytes);
+    if (lineage.indeterminate) return { affected: false, indeterminate: true };
+    if (lineage.affected) return { affected: true, indeterminate: false };
+  }
+  return { affected: false, indeterminate: false };
+}
+
+// New rollouts emit multi_agent_version in the initial turn_context. A session
+// created by an older Codex build can later be resumed under a multi-agent
+// build, though, so an inactive initial context also checks the final context
+// from a bounded tail read. The 1 MiB ceilings protect this one-time migration
+// from malformed metadata; an inconclusive bound is retryable, never a final
+// "not affected" verdict.
+async function scanCodexMultiAgentHead(filePath) {
+  const MAX_BYTES = 1024 * 1024;
+  let stream = null;
+  let rl = null;
+  let needsTail = false;
+  try {
+    stream = fssync.createReadStream(filePath, {
+      encoding: "utf8",
+      highWaterMark: 32 * 1024,
+    });
+    rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let bytesRead = 0;
+    for await (const line of rl) {
+      bytesRead += Buffer.byteLength(line, "utf8") + 1;
+      if (line.includes('"turn_context"')) {
+        let obj;
+        try {
+          obj = JSON.parse(line);
+        } catch (_e) {
+          return { candidate: false, indeterminate: true };
+        }
+        if (obj?.type === "turn_context") {
+          if (isActiveMultiAgentVersion(obj?.payload?.multi_agent_version)) {
+            return { candidate: true, indeterminate: false };
+          }
+          needsTail = true;
+        }
+      }
+      if (line.includes('"token_count"')) {
+        needsTail = true;
+        break;
+      }
+      if (bytesRead >= MAX_BYTES) return { candidate: false, indeterminate: true };
+    }
+  } catch (_e) {
+    return { candidate: false, indeterminate: true };
+  } finally {
+    if (rl) rl.close();
+    if (stream) stream.destroy();
+  }
+  if (needsTail) return scanCodexMultiAgentTail(filePath);
+  return { candidate: false, indeterminate: false };
+}
+
+async function scanCodexMultiAgentTail(filePath) {
+  const MAX_BYTES = 1024 * 1024;
+  let handle = null;
+  try {
+    handle = await fs.open(filePath, "r");
+    const stat = await handle.stat();
+    const size = Number(stat.size || 0);
+    const start = Math.max(0, size - MAX_BYTES);
+    const length = Math.max(0, size - start);
+    const buffer = Buffer.alloc(length);
+    let bytesRead = 0;
+    while (bytesRead < length) {
+      const result = await handle.read(
+        buffer,
+        bytesRead,
+        length - bytesRead,
+        start + bytesRead,
+      );
+      if (result.bytesRead <= 0) break;
+      bytesRead += result.bytesRead;
+    }
+    if (bytesRead !== length) return { candidate: false, indeterminate: true };
+    const lines = buffer.toString("utf8").split("\n");
+    if (start > 0) lines.shift(); // discard a line truncated by the tail boundary
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      const line = lines[index];
+      if (!line.includes('"turn_context"')) continue;
+      let obj;
+      try {
+        obj = JSON.parse(line);
+      } catch (_e) {
+        return { candidate: false, indeterminate: true };
+      }
+      if (obj?.type !== "turn_context") continue;
+      return {
+        candidate: isActiveMultiAgentVersion(obj?.payload?.multi_agent_version),
+        indeterminate: false,
+      };
+    }
+    return { candidate: false, indeterminate: start > 0 };
+  } catch (_e) {
+    return { candidate: false, indeterminate: true };
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+}
+
+function isActiveMultiAgentVersion(value) {
+  if (value === true) return true;
+  if (typeof value !== "string") return false;
+  const normalized = value.trim().toLowerCase();
+  return Boolean(
+    normalized &&
+      normalized !== "off" &&
+      normalized !== "none" &&
+      normalized !== "disabled",
+  );
+}
+
+async function scanCodexUsageLineages(filePath, maxBytes = Infinity) {
+  let stream = null;
+  let rl = null;
+  try {
+    const state = createUsageDeltaState();
+    const byteLimit = Number.isFinite(maxBytes) ? Math.max(0, maxBytes) : Infinity;
+    let bytesRead = 0;
+    stream = fssync.createReadStream(filePath, {
+      encoding: "utf8",
+      highWaterMark: 32 * 1024,
+    });
+    rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) {
+      bytesRead += Buffer.byteLength(line, "utf8") + 1;
+      if (bytesRead > byteLimit) return { affected: false, indeterminate: true };
+      if (!line.includes('"token_count"')) continue;
+      let obj;
+      try {
+        obj = JSON.parse(line);
+      } catch (_e) {
+        continue;
+      }
+      const token = extractTokenCount(obj);
+      const info = token?.info;
+      if (!info || typeof info !== "object") continue;
+      consumeUsageDelta(state, info.last_token_usage, info.total_token_usage);
+      if (state.sawInterleaved || state.sawDivergentCumulative) {
+        return { affected: true, indeterminate: false };
+      }
+    }
+    return { affected: false, indeterminate: false };
+  } catch (_e) {
+    return { affected: false, indeterminate: true };
+  } finally {
+    if (rl) rl.close();
+    if (stream) stream.destroy();
+  }
+}
+
+function isCodexHistoryCovered(cursors, rolloutFiles) {
+  const scannedPaths = new Set();
+  const scannedSessionIds = new Set();
+  for (const entry of Array.isArray(rolloutFiles) ? rolloutFiles : []) {
+    const fp = typeof entry === "string" ? entry : entry?.path;
+    const src = typeof entry === "string" ? "codex" : String(entry?.source || "codex");
+    if (!fp || src !== "codex") continue;
+    scannedPaths.add(fp);
+    const id = codexSessionIdFromPath(fp);
+    if (id) scannedSessionIds.add(id);
+  }
+  if (!cursors.files || typeof cursors.files !== "object") return true;
+  for (const fp of Object.keys(cursors.files)) {
+    if (!isCodexSessionCursorPath(fp)) continue;
+    if (scannedPaths.has(fp)) continue;
+    const id = codexSessionIdFromPath(fp);
+    if (id && scannedSessionIds.has(id)) continue;
+    return false;
+  }
+  return true;
+}
+
 // Scans codex rollout heads for the fork marker. The child session_meta (with
 // forked_from_id) is the FIRST line of a forked rollout — observed at byte
 // offset ≤169 across every local sample — so a bounded head read is

package/src/lib/codex-rollout-parser.js

@@ -11,6 +11,12 @@ const path = require("node:path");
 const readline = require("node:readline");
 
 const { listRolloutFiles } = require("./rollout");
+const {
+  consumeUsageDelta,
+  createUsageDeltaState,
+  snapshotUsageBaselines,
+  totalsReset,
+} = require("./codex-token-usage");
 const {
   emptyTotals,
   addInto,
@@ -434,42 +440,10 @@ function normalizeUsage(u) {
   return out;
 }
 
-function totalsReset(curr, prev) {
-  const a = Number(curr?.total_tokens);
-  const b = Number(prev?.total_tokens);
-  if (!Number.isFinite(a) || !Number.isFinite(b)) return false;
-  return a < b;
-}
-
 function pickDelta(lastUsage, totalUsage, prevTotals) {
-  const hasLast = lastUsage && typeof lastUsage === "object";
-  const hasTotal = totalUsage && typeof totalUsage === "object";
-  const hasPrev = prevTotals && typeof prevTotals === "object";
-
-  if (hasTotal && hasPrev) {
-    if (totalsReset(totalUsage, prevTotals)) {
-      const resetUsage = hasLast ? lastUsage : totalUsage;
-      return normalizeUsage(resetUsage);
-    }
-    const delta = {};
-    for (const k of [
-      "input_tokens",
-      "cached_input_tokens",
-      "cache_creation_input_tokens",
-      "output_tokens",
-      "reasoning_output_tokens",
-      "total_tokens",
-    ]) {
-      const a = Number(totalUsage[k]);
-      const b = Number(prevTotals[k]);
-      if (Number.isFinite(a) && Number.isFinite(b)) delta[k] = Math.max(0, a - b);
-    }
-    return normalizeUsage(delta);
-  }
-
-  if (hasLast) return normalizeUsage(lastUsage);
-  if (hasTotal) return normalizeUsage(totalUsage);
-  return null;
+  const state = createUsageDeltaState({ lastTotal: prevTotals });
+  const delta = consumeUsageDelta(state, lastUsage, totalUsage);
+  return delta ? normalizeUsage(delta) : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -596,7 +570,10 @@ async function parseCodexRolloutFile(filePath, {
   let provider = isResuming ? resumeState.provider || null : null;
   let cliVersion = isResuming ? resumeState.cliVersion || null : null;
 
-  let prevTotals = isResuming ? resumeState.prevTotals || null : null;
+  const usageDeltaState = createUsageDeltaState({
+    lastTotal: isResuming ? resumeState.prevTotals || null : null,
+    baselines: isResuming ? resumeState.tokenUsageBaselines || null : null,
+  });
   let pendingToolNames = isResuming
     ? Array.from(resumeState.pendingToolNames || [])
     : [];
@@ -875,8 +852,8 @@ async function parseCodexRolloutFile(filePath, {
       const info = tokenCount.info;
       const lastUsage = info?.last_token_usage;
       const totalUsage = info?.total_token_usage;
-      const delta = pickDelta(lastUsage, totalUsage, prevTotals);
-      if (totalUsage && typeof totalUsage === "object") prevTotals = totalUsage;
+      const rawDelta = consumeUsageDelta(usageDeltaState, lastUsage, totalUsage);
+      const delta = rawDelta ? normalizeUsage(rawDelta) : null;
       const isNewResumeEvent = noteTokenEvent(ts, lastUsage, totalUsage);
       if (inRequestedRange) {
         const eventSessionId = sessionId || rolloutSessionIdFromPath(primaryFilePath) || primaryFilePath;
@@ -927,7 +904,8 @@ async function parseCodexRolloutFile(filePath, {
       model,
       provider,
       cliVersion,
-      prevTotals,
+      prevTotals: usageDeltaState.lastTotal,
+      tokenUsageBaselines: snapshotUsageBaselines(usageDeltaState),
       pendingToolNames,
       pendingSkills,
       pendingExecDetails,

package/src/lib/codex-token-usage.js

@@ -0,0 +1,195 @@
+"use strict";
+
+// A rollout can contain TokenCount events from more than one Codex SessionState
+// (for example, a parent agent and an embedded reviewer). Each SessionState has
+// its own cumulative total, but the event does not carry a stable stream id.
+// Recover the stream from Codex's invariant: total - last = that stream's prior
+// total. Keeping a small LRU of stream heads also makes repeated rate-limit
+// snapshots idempotent when the streams are interleaved.
+
+const USAGE_FIELDS = [
+  "input_tokens",
+  "cached_input_tokens",
+  "cache_creation_input_tokens",
+  "output_tokens",
+  "reasoning_output_tokens",
+  "total_tokens",
+];
+const MAX_USAGE_BASELINES = 32;
+
+function canonicalUsage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const out = {};
+  let sawNumber = false;
+  for (const field of USAGE_FIELDS) {
+    const raw = field === "cache_creation_input_tokens"
+      ? value.cache_creation_input_tokens ?? value.cache_write_input_tokens
+      : value[field];
+    const number = Number(raw);
+    if (Number.isFinite(number) && number >= 0) {
+      out[field] = Math.floor(number);
+      sawNumber = true;
+    } else {
+      out[field] = 0;
+    }
+  }
+  return sawNumber ? out : null;
+}
+
+function usageSignature(value) {
+  const usage = canonicalUsage(value);
+  return usage ? USAGE_FIELDS.map((field) => usage[field]).join(":") : null;
+}
+
+function sameUsage(left, right) {
+  const leftSignature = usageSignature(left);
+  return leftSignature !== null && leftSignature === usageSignature(right);
+}
+
+function subtractUsage(totalUsage, lastUsage) {
+  const total = canonicalUsage(totalUsage);
+  const last = canonicalUsage(lastUsage);
+  if (!total || !last) return null;
+  const previous = {};
+  for (const field of USAGE_FIELDS) {
+    if (total[field] < last[field]) return null;
+    previous[field] = total[field] - last[field];
+  }
+  return previous;
+}
+
+function diffUsage(totalUsage, previousUsage) {
+  const total = canonicalUsage(totalUsage);
+  const previous = canonicalUsage(previousUsage);
+  if (!total || !previous) return null;
+  const delta = {};
+  for (const field of USAGE_FIELDS) {
+    delta[field] = Math.max(0, total[field] - previous[field]);
+  }
+  return delta;
+}
+
+function totalsReset(totalUsage, previousUsage) {
+  const total = canonicalUsage(totalUsage);
+  const previous = canonicalUsage(previousUsage);
+  return Boolean(total && previous && total.total_tokens < previous.total_tokens);
+}
+
+function createUsageDeltaState({ lastTotal = null, baselines = null } = {}) {
+  const state = {
+    lastTotal: null,
+    baselines: [],
+    sawDivergentCumulative: false,
+    sawInterleaved: false,
+  };
+  for (const baseline of Array.isArray(baselines) ? baselines : []) {
+    touchBaseline(state, baseline);
+  }
+  if (canonicalUsage(lastTotal)) touchBaseline(state, lastTotal);
+  return state;
+}
+
+function snapshotUsageBaselines(state) {
+  return Array.isArray(state?.baselines)
+    ? state.baselines.map((usage) => ({ ...usage }))
+    : [];
+}
+
+function consumeUsageDelta(state, lastUsage, totalUsage) {
+  if (!state || typeof state !== "object") {
+    throw new TypeError("usage delta state is required");
+  }
+  if (!Array.isArray(state.baselines)) state.baselines = [];
+
+  const last = canonicalUsage(lastUsage);
+  const total = canonicalUsage(totalUsage);
+  if (!total) return last;
+
+  const activeSignature = usageSignature(state.lastTotal);
+  const duplicateIndex = findBaselineIndex(state, total);
+  if (duplicateIndex >= 0) {
+    if (
+      activeSignature !== null &&
+      usageSignature(state.baselines[duplicateIndex]) !== activeSignature
+    ) {
+      state.sawInterleaved = true;
+    }
+    touchBaselineAt(state, duplicateIndex, total);
+    return null;
+  }
+
+  if (last) {
+    const expectedPrevious = subtractUsage(total, last);
+    const lineageIndex = findBaselineIndex(state, expectedPrevious);
+    if (lineageIndex >= 0) {
+      if (
+        activeSignature !== null &&
+        usageSignature(state.baselines[lineageIndex]) !== activeSignature
+      ) {
+        state.sawInterleaved = true;
+      }
+      touchBaselineAt(state, lineageIndex, total);
+      return last;
+    }
+    if (expectedPrevious) {
+      if (canonicalUsage(state.lastTotal)) state.sawDivergentCumulative = true;
+      touchBaseline(state, total);
+      return last;
+    }
+  }
+
+  const active = canonicalUsage(state.lastTotal);
+  if (active && !totalsReset(total, active)) {
+    const delta = diffUsage(total, active);
+    if (!last || Number(delta?.total_tokens || 0) <= Number(last.total_tokens || 0)) {
+      const activeIndex = findBaselineIndex(state, active);
+      touchBaselineAt(state, activeIndex, total);
+      return delta;
+    }
+
+    // A cumulative jump larger than last usage cannot come from the normal
+    // append_last_usage path. Treat it as a new stream instead of charging the
+    // unrelated cumulative gap; a later event will establish its lineage.
+    state.sawDivergentCumulative = true;
+  }
+
+  touchBaseline(state, total);
+  return last || total;
+}
+
+function findBaselineIndex(state, usage) {
+  const signature = usageSignature(usage);
+  if (signature === null) return -1;
+  return state.baselines.findIndex((baseline) => usageSignature(baseline) === signature);
+}
+
+function touchBaselineAt(state, index, usage) {
+  const canonical = canonicalUsage(usage);
+  if (!canonical) return;
+  if (Number.isInteger(index) && index >= 0 && index < state.baselines.length) {
+    state.baselines.splice(index, 1);
+  } else {
+    const duplicateIndex = findBaselineIndex(state, canonical);
+    if (duplicateIndex >= 0) state.baselines.splice(duplicateIndex, 1);
+  }
+  state.baselines.push(canonical);
+  while (state.baselines.length > MAX_USAGE_BASELINES) state.baselines.shift();
+  state.lastTotal = canonical;
+}
+
+function touchBaseline(state, usage) {
+  touchBaselineAt(state, findBaselineIndex(state, usage), usage);
+}
+
+module.exports = {
+  MAX_USAGE_BASELINES,
+  canonicalUsage,
+  consumeUsageDelta,
+  createUsageDeltaState,
+  diffUsage,
+  sameUsage,
+  snapshotUsageBaselines,
+  subtractUsage,
+  totalsReset,
+  usageSignature,
+};