tokentracker-cli 1.5.1 → 1.5.3

package/src/lib/provider-status.js

@@ -9,6 +9,8 @@
 // Statuspage.io contract (`/api/v2/status.json`):
 //   { "page": { "updated_at": ISO }, "status": { "indicator": "none|minor|major|critical", "description": "..." } }
 
+const { parseDeepSeekStatusPage } = require("./deepseek-status");
+
 const STATUS_PROBE_TIMEOUT_MS = 6_000;
 // Status pages change on incident timescales; 5 minutes keeps the limits
 // poll (2-min TTL upstream) from hammering statuspage.io every cycle.
@@ -23,6 +25,13 @@ const STATUS_PAGE_SPECS = {
     apiUrl: "https://status.claude.com/api/v2/status.json",
     pageUrl: "https://status.claude.com",
   },
+  deepseek: {
+    // Flashcat-hosted Next.js page: no public JSON API and no CORS. Relayed
+    // server-side here; `format` switches the fetch to HTML + RSC parsing.
+    apiUrl: "https://status.deepseek.com/",
+    pageUrl: "https://status.deepseek.com",
+    format: "deepseek-rsc",
+  },
 };
 
 const VALID_INDICATORS = new Set(["none", "minor", "major", "critical"]);
@@ -68,13 +77,17 @@ async function fetchProviderServiceStatus(providerId, { fetchImpl = fetch, nowMs
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), STATUS_PROBE_TIMEOUT_MS);
     try {
+      const isDeepSeek = spec.format === "deepseek-rsc";
       const res = await fetchImpl(spec.apiUrl, {
         method: "GET",
-        headers: { Accept: "application/json" },
+        headers: { Accept: isDeepSeek ? "text/html" : "application/json" },
         signal: controller.signal,
       });
       if (res.ok) {
-        data = normalizeStatusPayload(await res.json(), spec, nowMs);
+        const payload = isDeepSeek
+          ? parseDeepSeekStatusPage(await res.text())
+          : await res.json();
+        data = normalizeStatusPayload(payload, spec, nowMs);
       }
     } finally {
       clearTimeout(timer);

package/src/lib/qoder-limits.js

@@ -40,6 +40,9 @@ const QODER_ACTIVITY_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const QODER_LIMITS_CACHE_FILE = "qoder-usage-limits-cache.json";
 const QODER_LIMITS_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const QODER_LIMITS_CACHE_UNKNOWN_RESET_TTL_MS = 12 * 60 * 60 * 1000;
+// Align with usage-limits provenance aging (10 min): a cache hit fresher than
+// this inherits its written source and is not flagged stale (#955 self-lock).
+const QODER_LIMITS_CACHE_FRESH_TTL_MS = 10 * 60 * 1000;
 // Qoder Desktop 0.4+ writes its account usage summary to main.log, which can
 // accumulate a whole session before the quota is read. Scan a bounded window
 // backwards instead of assuming the summary is near EOF.
@@ -105,7 +108,10 @@ function normalizeQuotaSummary(summary) {
   if (total === 0 && (used !== 0 || remaining !== 0)) {
     throw new Error("Qoder zero total quota must have zero usage and remaining.");
   }
-  const usagePercentage = providedPercentage ?? (total > 0 ? (used / total) * 100 : 100);
+  // An empty 0/0 quota (no active plan) renders as 0%, matching Qoder's own
+  // Credits UI and the desktop/CLI paths; a server-provided percentage still
+  // wins when present.
+  const usagePercentage = providedPercentage ?? (total > 0 ? (used / total) * 100 : 0);
   return {
     used,
     total,
@@ -131,7 +137,7 @@ function normalizeQoderUsageResponse(response) {
   const usedPercent = shared
     ? total > 0
       ? (used / total) * 100
-      : 100
+      : 0
     : base.usagePercentage;
 
   return {
@@ -279,16 +285,17 @@ function normalizeQoderRpcUsage(response) {
   const used = quota ? finiteNumber(quota.used, "userQuota.used") : 0;
   const total = quota ? finiteNumber(quota.total, "userQuota.total") : 0;
   const remaining = quota ? finiteNumber(quota.remaining, "userQuota.remaining") : 0;
-  const reportedPercent = Number(response.totalUsagePercentage ?? quota?.percentage);
+  // totalUsagePercentage aggregates the plan and add-on buckets and reaches
+  // this function on mixed scales (the OpenAPI returns fractions, the desktop
+  // IPC returns percents), so the primary window always derives its percent
+  // from its own quota numbers.
   const usedPercent = total === 0
     ? 0
     : addOnWindow
       ? (used / total) * 100
       : response.isQuotaExceeded === true
         ? 100
-        : Number.isFinite(reportedPercent)
-          ? reportedPercent
-          : (used / total) * 100;
+        : (used / total) * 100;
   const normalizedExpiry = normalizeResetAt(response.expiresAt);
   const expiryMs = normalizedExpiry ? Date.parse(normalizedExpiry) : NaN;
   return {
@@ -431,6 +438,15 @@ function readQoderLimitsCache({
     if (nowMs - cachedAtMs > QODER_LIMITS_CACHE_MAX_AGE_MS && !hasUnexpiredDatedWindow) {
       return null;
     }
+    // Provenance must describe the data's age, not the transport (#955): a
+    // successful refresh writes this cache and immediately floors later log
+    // scans, so the next refresh re-serves the same payload. Marking every
+    // hit stale/disk-cache made the Limits page permanently partial.
+    const ageMs = nowMs - cachedAtMs;
+    const fresh = ageMs <= QODER_LIMITS_CACHE_FRESH_TTL_MS;
+    const writtenSource = typeof raw.source === "string" && raw.source.trim()
+      ? raw.source.trim()
+      : null;
     return {
       configured: true,
       error: null,
@@ -440,9 +456,9 @@ function readQoderLimitsCache({
       secondary_window: secondaryWindow,
       ...(tertiaryWindow ? { tertiary_window: tertiaryWindow } : {}),
       cached: true,
-      stale: true,
+      stale: !fresh,
       cached_at: raw.cached_at,
-      source: "disk-cache",
+      source: fresh && writtenSource ? writtenSource : "disk-cache",
     };
   } catch (_error) {
     return null;
@@ -463,6 +479,9 @@ function writeQoderLimitsCache(limits, {
       primary_window: limits.primary_window || null,
       secondary_window: limits.secondary_window || null,
       ...(limits.tertiary_window ? { tertiary_window: limits.tertiary_window } : {}),
+      // Remember the winning source so a fresh re-serve keeps honest
+      // provenance instead of always claiming "disk-cache" (#955).
+      source: typeof limits.source === "string" ? limits.source : null,
       cached_at: new Date(nowMs).toISOString(),
     },
   };
@@ -727,6 +746,12 @@ function parseQoderAccountUsageLog(text, { fallbackObservedAtMs = null } = {}) {
     return {
       limits,
       observedAtMs: Number.isFinite(lineObservedAtMs) ? lineObservedAtMs : fallbackObservedAtMs,
+      // The summary's own timestamp, or null when the line carries no parseable
+      // one and observedAtMs fell back to the file mtime. Callers that order
+      // this snapshot against other sources must use it, not observedAtMs: an
+      // mtime bump from an unrelated append would otherwise masquerade as a
+      // fresh observation.
+      lineObservedAtMs: Number.isFinite(lineObservedAtMs) ? lineObservedAtMs : null,
     };
   }
   return null;
@@ -772,7 +797,7 @@ function parseQoderQuotaLog(text) {
 // one; pruning to the current candidate set keeps the map bounded.
 const qoderNoSummaryScans = new Map();
 
-function readQoderLocalQuota({
+function readQoderLocalQuotaWithAge({
   home = os.homedir(),
   platform = process.platform,
   env = process.env,
@@ -780,17 +805,23 @@ function readQoderLocalQuota({
   envPrefix = "QODER",
   nowMs = Date.now(),
   maxAgeMs = QODER_LOG_MAX_AGE_MS,
+  olderThanMs = -Infinity,
 } = {}) {
   const candidates = [];
   for (const logRoot of qoderLogRoots({ home, platform, env, appDir, envPrefix })) {
     for (const entry of listRecentQoderLogs(logRoot)) {
       if (nowMs - entry.mtimeMs > maxAgeMs) continue;
+      // A file last written at or before the cache snapshot cannot hold an
+      // observation newer than it (a line's time never exceeds the file
+      // mtime), so scanning it could never win the timestamp comparison.
+      if (entry.mtimeMs <= olderThanMs) continue;
       candidates.push(entry);
     }
   }
   candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
   const scanned = candidates.slice(0, QODER_LOG_MAX_FILES);
   const seenPaths = new Set();
+  let best = null;
   for (const { full, mtimeMs, size } of scanned) {
     seenPaths.add(full);
     const signature = `${size}:${mtimeMs}`;
@@ -804,7 +835,7 @@ function readQoderLocalQuota({
         return accountUsage;
       }
       const legacy = parseQoderQuotaLog(text);
-      return legacy ? { limits: legacy, observedAtMs: mtimeMs } : null;
+      return legacy ? { limits: legacy, observedAtMs: mtimeMs, lineObservedAtMs: null } : null;
     });
     if (parsed === undefined) continue; // Scan failed (I/O); retry on the next call.
     if (!parsed) {
@@ -813,12 +844,27 @@ function readQoderLocalQuota({
     }
     const observedAtMs = parsed.observedAtMs ?? mtimeMs;
     if (nowMs - observedAtMs > maxAgeMs) continue;
-    return parsed.limits;
+    // A summary that cannot beat the cache cutoff is not eligible: keep
+    // scanning, a deeper file may still hold a newer line that can.
+    if ((parsed.lineObservedAtMs ?? 0) <= olderThanMs) continue;
+    // A file's mtime order need not match its summary-line order: an append
+    // without a fresh summary leaves an old line in a freshly touched file.
+    // Keep the newest eligible line across the whole scan instead of the
+    // first hit — advancing the cache cutoff afterwards must not lock out a
+    // summary that was newer all along.
+    const lineObservedAtMs = parsed.lineObservedAtMs ?? null;
+    if (!best || (lineObservedAtMs ?? 0) > (best.lineObservedAtMs ?? 0)) {
+      best = { limits: parsed.limits, lineObservedAtMs };
+    }
   }
   for (const cachedPath of qoderNoSummaryScans.keys()) {
     if (!seenPaths.has(cachedPath)) qoderNoSummaryScans.delete(cachedPath);
   }
-  return null;
+  return best;
+}
+
+function readQoderLocalQuota(options = {}) {
+  return readQoderLocalQuotaWithAge(options)?.limits ?? null;
 }
 
 function siteFromEnv(value) {
@@ -899,9 +945,34 @@ async function fetchQoderLimits({
     }
   }
 
-  // Once native sources are unavailable, prefer a bounded disk snapshot before
-  // the manual-cookie or local-log fallback.
+  // A 0.4.x desktop app refreshes its main.log summary whenever the account
+  // page reloads, so the newest line can be newer than the last-good cache.
+  // Compare the summary's own timestamp against the cache instead of always
+  // trusting the cache: only a parseable line timestamp may win, and files
+  // last written before the cache are skipped without a scan. Without a valid
+  // cache there is nothing to compare against, so the summary defers to the
+  // live manual-cookie session below and only serves as its fallback.
   const cachedLimits = readQoderLimitsCache({ home, nowMs, namespace: cacheNamespace });
+  const cachedAtMs = Date.parse(cachedLimits?.cached_at || "");
+  const cacheFloorMs = Number.isFinite(cachedAtMs) ? cachedAtMs : -Infinity;
+  const localScan = readQoderLocalQuotaWithAge({
+    home,
+    platform,
+    env,
+    appDir,
+    envPrefix,
+    nowMs,
+    olderThanMs: cacheFloorMs,
+  });
+  if (localScan && Number.isFinite(cacheFloorMs) && (localScan.lineObservedAtMs ?? 0) > cacheFloorMs) {
+    const local = localScan.limits;
+    if (activityWindow) {
+      local.secondary_window = activityWindow;
+      local.source += activitySource === "disk-cache" ? "+cached-activity" : "+activity";
+    }
+    writeQoderLimitsCache(local, { home, nowMs, namespace: cacheNamespace });
+    return local;
+  }
   if (cachedLimits) {
     if (activityWindow) cachedLimits.secondary_window = activityWindow;
     return cachedLimits;
@@ -930,15 +1001,15 @@ async function fetchQoderLimits({
       // Qoder 1.18 can return an all-zero active plan with usage_percentage=0
       // while the desktop client separately marks the account quota-exceeded.
       // Preserve that status as metadata, but match Qoder's Credits UI by
-      // rendering an empty 0/0 bucket as 0%, not a full red 100% bar.
-      const local = result.primary_window?.limit_credits === 0
-        ? readQoderLocalQuota({ home, platform, env, appDir, envPrefix, nowMs })
-        : null;
-      if (local) {
-        result.quota_exceeded = local.quota_exceeded === true;
+      // rendering an empty 0/0 bucket as 0%, not a full red 100% bar. With no
+      // valid cache the log scan above only ran as a companion — it lost its
+      // spot ahead of this session — so its result is still available here.
+      const zeroPlanLocal = result.primary_window?.limit_credits === 0 ? localScan : null;
+      if (zeroPlanLocal) {
+        result.quota_exceeded = zeroPlanLocal.limits.quota_exceeded === true;
         result.primary_window.reset_at = null;
         result.source = "provider-api+local-log";
-        result.plan_label = local.plan_label || null;
+        result.plan_label = zeroPlanLocal.limits.plan_label || null;
       }
       if (activityWindow) {
         result.secondary_window = activityWindow;
@@ -956,8 +1027,8 @@ async function fetchQoderLimits({
     }
   }
 
-  const local = readQoderLocalQuota({ home, platform, env, appDir, envPrefix, nowMs });
-  if (local) {
+  if (localScan) {
+    const local = localScan.limits;
     if (activityWindow) {
       local.secondary_window = activityWindow;
       local.source += activitySource === "disk-cache" ? "+cached-activity" : "+activity";
@@ -965,6 +1036,7 @@ async function fetchQoderLimits({
     writeQoderLimitsCache(local, { home, nowMs, namespace: cacheNamespace });
     return local;
   }
+
   if (activityWindow) {
     return {
       configured: true,

package/src/lib/rollout.js

@@ -35,6 +35,7 @@ const {
   createCompactionResponseIds,
   createUsageRecordState,
   extractTokenUsageRecord,
+  isCodexTotalOnlyResetSentinel,
   isCodexTurnEndEvent,
   isRecordOnly,
   noteLineAfterUsageRecord,
@@ -3606,6 +3607,67 @@ async function enqueueTouchedBuckets({ queuePath, hourlyState, touchedBuckets })
 
   const toAppend = [];
   for (const group of groupedBuckets.values()) {
+    // A local reconstruction may opt into observed-only attribution. Preserve
+    // every model bucket, including unknown, instead of guessing from the
+    // busiest model in the same half-hour. The policy lives in cursor state
+    // so hooks, desktop refreshes, and restarted CLI processes agree.
+    if (hourlyState.modelAttributionPolicy?.[group.source] === "observed") {
+      // A group last aligned under the default policy must not keep the stale
+      // dominant attribution downstream. Mirror the default path's alignment
+      // correction — one zero row for the old model — then observed mode
+      // re-emits every bucket, unknown included, and the alignment state is
+      // dropped so the correction fires at most once per group.
+      const alignedModelBucket = group.buckets.get(DEFAULT_MODEL) || null;
+      const staleAlignedModel = (() => {
+        if (!alignedModelBucket?.alignedModel) return null;
+        const normalized = normalizeModelInput(alignedModelBucket.alignedModel);
+        return normalized && normalized !== DEFAULT_MODEL && !group.buckets.has(normalized)
+          ? normalized
+          : null;
+      })();
+      if (staleAlignedModel) {
+        const zeroTotals = initTotals();
+        toAppend.push(JSON.stringify({
+          source: group.source,
+          model: staleAlignedModel,
+          hour_start: group.hourStart,
+          input_tokens: zeroTotals.input_tokens,
+          cached_input_tokens: zeroTotals.cached_input_tokens,
+          cache_creation_input_tokens: zeroTotals.cache_creation_input_tokens,
+          output_tokens: zeroTotals.output_tokens,
+          reasoning_output_tokens: zeroTotals.reasoning_output_tokens,
+          total_tokens: zeroTotals.total_tokens,
+          billable_total_tokens: zeroTotals.billable_total_tokens,
+          total_cost_usd: zeroTotals.total_cost_usd,
+          conversation_count: zeroTotals.conversation_count,
+        }));
+      }
+      for (const bucket of group.buckets.values()) bucket.alignedModel = null;
+      for (const [model, bucket] of group.buckets.entries()) {
+        const totals = bucket.totals;
+        const usagePrecision = bucket.usage_precision || null;
+        const key = usagePrecision ? `${totalsKey(totals)}|${usagePrecision}` : totalsKey(totals);
+        if (bucket.queuedKey === key) continue;
+        toAppend.push(JSON.stringify({
+          source: group.source,
+          model,
+          hour_start: group.hourStart,
+          input_tokens: totals.input_tokens,
+          cached_input_tokens: totals.cached_input_tokens,
+          cache_creation_input_tokens: totals.cache_creation_input_tokens,
+          output_tokens: totals.output_tokens,
+          reasoning_output_tokens: totals.reasoning_output_tokens,
+          total_tokens: totals.total_tokens,
+          billable_total_tokens: totals.billable_total_tokens ?? totals.total_tokens,
+          total_cost_usd: totals.total_cost_usd || 0,
+          usage_precision: usagePrecision || undefined,
+          ...prioritySubsetOf(totals),
+          conversation_count: totals.conversation_count,
+        }));
+        bucket.queuedKey = key;
+      }
+      continue;
+    }
     const unknownBucket = group.buckets.get(DEFAULT_MODEL) || null;
     const dominantModel = pickDominantModel(group.buckets);
     let alignedModel = null;
@@ -3977,6 +4039,10 @@ function normalizeHourlyState(raw) {
   const rawBuckets = state.buckets && typeof state.buckets === "object" ? state.buckets : {};
   const buckets = {};
   const groupQueued = {};
+  const modelAttributionPolicy = Object.fromEntries(
+    Object.entries(state.modelAttributionPolicy || {})
+      .filter(([, policy]) => policy === "observed"),
+  );
 
   if (!Number.isFinite(version) || version < 2) {
     for (const [key, value] of Object.entries(rawBuckets)) {
@@ -3994,6 +4060,7 @@ function normalizeHourlyState(raw) {
       version: 3,
       buckets,
       groupQueued,
+      ...(Object.keys(modelAttributionPolicy).length > 0 ? { modelAttributionPolicy } : {}),
       updatedAt: typeof state.updatedAt === "string" ? state.updatedAt : null,
     };
   }
@@ -4013,6 +4080,7 @@ function normalizeHourlyState(raw) {
     version: 3,
     buckets,
     groupQueued: version >= 3 ? existingGroupQueued : {},
+    ...(Object.keys(modelAttributionPolicy).length > 0 ? { modelAttributionPolicy } : {}),
     updatedAt: typeof state.updatedAt === "string" ? state.updatedAt : null,
   };
 }
@@ -5246,20 +5314,6 @@ function normalizeUsage(u) {
   return out;
 }
 
-function isCodexTotalOnlyResetSentinel(lastUsage, totalUsage) {
-  const componentTotal = (usage) => [
-    usage?.input_tokens,
-    usage?.cached_input_tokens,
-    usage?.cache_creation_input_tokens ?? usage?.cache_write_input_tokens,
-    usage?.output_tokens,
-    usage?.reasoning_output_tokens,
-  ].reduce((sum, value) => sum + Math.max(0, Number(value) || 0), 0);
-  return Number(lastUsage?.total_tokens || 0) > 0
-    && Number(totalUsage?.total_tokens || 0) === 0
-    && componentTotal(lastUsage) === 0
-    && componentTotal(totalUsage) === 0;
-}
-
 // Stable dedup key for one Claude jsonl entry. Anthropic's official protocol
 // guarantees `message.id` is globally unique per response, so msgId alone is a
 // valid dedup key. Older code required both msgId AND requestId, which short-

package/src/lib/session-analytics.js

@@ -93,6 +93,8 @@ const {
 // date-filtered session views and cached sidecars keep the 6x premium.
 // v27 adds oh-my-pi (omp) sessions from ~/.omp/agent/sessions/**/*.jsonl.
 const SIDECAR_VERSION = 27;
+// Invalidate only Codex token summaries; other sources keep their cached rows.
+const CODEX_USAGE_VERSION = 1;
 const EDIT_TOOLS = new Set([
   "apply_patch",
   "edit",
@@ -803,6 +805,7 @@ async function scanCodexSession(filePath) {
     seenTokenEvents: new Set(),
     collectBreakdowns: false,
     collectModelUsage: true,
+    ledgerUsage: true,
     onObject(obj, model) {
       signalCollector.consume(obj, model);
       performanceCollector.consume(obj, model);
@@ -2273,7 +2276,7 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
       previousMeta = JSON.parse(fs.readFileSync(metaPath, "utf8"));
       const checkedAt = Date.parse(previousMeta.checked_at || previousMeta.generated_at || "");
       if (
-        !retryZcodeScan && !retryOpencodeScan && !retryKimiScan && !retryOmpScan && !retryDshScan && previousMeta.version === SIDECAR_VERSION &&
+        !retryZcodeScan && !retryOpencodeScan && !retryKimiScan && !retryOmpScan && !retryDshScan && previousMeta.version === SIDECAR_VERSION && previousMeta.codex_usage_version === CODEX_USAGE_VERSION &&
         Number.isFinite(checkedAt) &&
         Date.now() - checkedAt < Math.max(0, Number(cacheTtlMs) || 0)
       ) {
@@ -2314,7 +2317,7 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
     // db + its WAL sidecars: the trio is one logical file for change detection.
     ...[...(discovered.zcode || []), ...(discovered.opencode || [])].flatMap((dbPath) => [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]),
   ]);
-  if (!force && !retryZcodeScan && !retryOpencodeScan && !retryKimiScan && !retryOmpScan && !retryDshScan && previousMeta?.version === SIDECAR_VERSION && previousMeta.signature === signature) {
+  if (!force && !retryZcodeScan && !retryOpencodeScan && !retryKimiScan && !retryOmpScan && !retryDshScan && previousMeta?.version === SIDECAR_VERSION && previousMeta.codex_usage_version === CODEX_USAGE_VERSION && previousMeta.signature === signature) {
     await writeAtomic(metaPath, `${JSON.stringify({ ...previousMeta, checked_at: new Date().toISOString() })}\n`);
     return readSidecar(sidecarPath);
   }
@@ -2344,6 +2347,7 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
   // vanished mid-scan). Swallowing these silently made sessions disappear with
   // no signal at all; count them so the API can say so.
   let skippedFiles = 0;
+  let incompleteCodexUsage = false;
   let incompleteZcodeScan = false;
   let incompleteOpencodeScan = false;
   let incompleteKimiScan = false;
@@ -2354,6 +2358,7 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
     const statKey = analyticsEntryStatKey(entry.source, entry.filePath);
     if (!statKey) {
       skippedFiles += 1;
+      if (entry.source === "codex") incompleteCodexUsage = true;
       if (entry.source === "zcode") incompleteZcodeScan = true;
       if (entry.source === "opencode") incompleteOpencodeScan = true;
       if (entry.source === "kimi") incompleteKimiScan = true;
@@ -2362,7 +2367,7 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
       continue;
     }
     let rows = null;
-    if (!force && !(entry.source === "zcode" && retryZcodeScan) && !(entry.source === "opencode" && retryOpencodeScan) && !(entry.source === "kimi" && retryKimiScan) && !(entry.source === "omp" && retryOmpScan) && !(entry.source === "dsh" && retryDshScan) && previousFiles[cacheKey]?.stat_key === statKey) {
+    if (!force && !(entry.source === "codex" && previousMeta?.codex_usage_version !== CODEX_USAGE_VERSION) && !(entry.source === "zcode" && retryZcodeScan) && !(entry.source === "opencode" && retryOpencodeScan) && !(entry.source === "kimi" && retryKimiScan) && !(entry.source === "omp" && retryOmpScan) && !(entry.source === "dsh" && retryDshScan) && previousFiles[cacheKey]?.stat_key === statKey) {
       if (entry.source === "zcode" || entry.source === "opencode" || entry.source === "kimi" || entry.source === "omp" || entry.source === "dsh") {
         // One db scans to many cached rows; recover them all from the previous
         // pass. An empty recovery means the sidecar lost its rows — rescan.
@@ -2392,6 +2397,7 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
         // One active/partial session must not poison the sidecar, but do not
         // pretend it never existed either.
         skippedFiles += 1;
+        if (entry.source === "codex") incompleteCodexUsage = true;
         if (entry.source === "zcode") incompleteZcodeScan = true;
         if (entry.source === "opencode") incompleteOpencodeScan = true;
         if (entry.source === "kimi") incompleteKimiScan = true;
@@ -2455,6 +2461,7 @@ async function buildSessionAnalyticsInternal({ home = os.homedir(), force = fals
     const generatedAt = new Date().toISOString();
     await writeAtomic(metaPath, `${JSON.stringify({
       version: SIDECAR_VERSION,
+      codex_usage_version: incompleteCodexUsage ? 0 : CODEX_USAGE_VERSION,
       signature,
       generated_at: generatedAt,
       checked_at: generatedAt,