npm - tokentracker-cli - Versions diffs - 0.84.5 → 0.84.7 - Mend

tokentracker-cli 0.84.5 → 0.84.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (120) hide show

package/dashboard/dist/share.html CHANGED Viewed

@@ -75,8 +75,8 @@
         "description": "Shareable Token Tracker dashboard snapshot."
       }
     </script>
-    <script type="module" crossorigin src="/assets/__vite-browser-external-D3llGq6p.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/__vite-browser-external-WKilYZnq.css">
+    <script type="module" crossorigin src="/assets/__vite-browser-external-BdRrPLk6.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/__vite-browser-external-hXV_ZYTG.css">
   </head>
   <body>
     <main class="aeo-seed-content" aria-label="Token Tracker share page summary">

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "tokentracker-cli",
-  "version": "0.84.5",
-  "description": "Local-first AI coding token usage and cost tracker for 27 tools, with a dashboard, desktop pet, widgets, achievements, and native macOS/Windows apps.",
+  "version": "0.84.7",
+  "description": "Local-first AI coding token usage and cost tracker for 28 tools, with a dashboard, desktop pet, widgets, achievements, and native macOS/Windows apps.",
   "main": "src/cli.js",
   "bin": {
     "tokentracker-cli": "bin/tracker.js",

package/src/commands/init.js CHANGED Viewed

@@ -124,6 +124,7 @@ const SUPPORTED_PROVIDERS = [
   "Droid",
   "Mimo",
   "ZCode",
+  "Qoder",
   "AnythingLLM Desktop",
 ];

package/src/commands/status.js CHANGED Viewed

@@ -47,6 +47,7 @@ const {
   resolveKimiWireFiles,
   resolveKimiCodeWireFiles,
   resolveKiroCliDbPath,
+  resolveKiroCliSessionFiles,
   resolveCodebuddyHome,
   resolveCodebuddyProjectFiles,
   resolveWorkbuddyHome,
@@ -61,6 +62,7 @@ const {
   resolveKilocodeTaskFiles,
   resolveRoocodeTaskFiles,
   resolveZedDbPath,
+  resolveQoderDbPaths,
   resolveAnythingllmDbPath,
   resolveGooseDbPath,
   listDroidSettingsFiles,
@@ -229,12 +231,14 @@ async function cmdStatus(argv = []) {
   const kimiCodeHome = process.env.KIMI_CODE_HOME || path.join(home, ".kimi-code");
   const kimiCodeInstalled = fssync.existsSync(path.join(kimiCodeHome, "sessions"));
-  // Kiro CLI — reads from SQLite at
-  // ~/Library/Application Support/kiro-cli/data.sqlite3. End-user dashboards
-  // show CLI and IDE merged under a single "Kiro" brand; this status line
-  // surfaces the CLI sub-path separately for operators.
+  // Kiro CLI — reads the legacy SQLite/session files and Kiro CLI 2.13+
+  // event sessions. End-user dashboards show them merged under "Kiro"; this
+  // status line surfaces which passive sources are actually present.
   const kiroCliDbPath = resolveKiroCliDbPath(process.env);
-  const kiroCliInstalled = fssync.existsSync(kiroCliDbPath);
+  const kiroCliDbExists = fssync.existsSync(kiroCliDbPath);
+  const kiroCliSessionFiles = resolveKiroCliSessionFiles(process.env);
+  const kiroCliInstalled =
+    kiroCliDbExists || kiroCliSessionFiles.length > 0;
   // AnythingLLM Desktop — per-message token metrics in workspace_chats.
   const anythingllmDbPath = resolveAnythingllmDbPath(process.env);
@@ -318,6 +322,16 @@ async function cmdStatus(argv = []) {
   const zcodeInstalled = zcodeActive.length > 0;
   const zcodeDbPath = zcodeActive.join(" | ");
+  // Qoder Desktop 1.18+ — token usage lives in SharedClientCache/local.db.
+  const qoderPaths = resolveQoderDbPaths({
+    home,
+    env: process.env,
+    platform: process.platform,
+  });
+  const qoderActive = formatResolvedPaths(qoderPaths);
+  const qoderInstalled = qoderActive.length > 0;
+  const qoderDbPath = qoderActive.join(" | ");
   // OpenCode (JSON files + SQLite DB) — passive scan of storage/message/ and opencode.db.
   const opencodeStorageNativeValue = process.env.OPENCODE_HOME || path.join(xdgDataHome, "opencode");
   const wslOpencodeStorageDir = process.platform === "win32" && shouldProbeWsl(process.env)
@@ -634,7 +648,14 @@ async function cmdStatus(argv = []) {
           ? { installed: true, files: kimiWireFiles.length + kimiCodeWireFiles.length }
           : { installed: false },
         kiro_cli: kiroCliInstalled
-          ? { installed: true, detail: kiroCliDbPath }
+          ? {
+              installed: true,
+              detail: kiroCliDbExists
+                ? kiroCliDbPath
+                : path.dirname(kiroCliSessionFiles[0]),
+              database: kiroCliDbExists ? kiroCliDbPath : null,
+              files: kiroCliSessionFiles.length,
+            }
           : { installed: false },
         codebuddy: codebuddyInstalled
           ? { installed: true, files: codebuddyFiles.length }
@@ -663,6 +684,9 @@ async function cmdStatus(argv = []) {
         zcode: zcodeInstalled
           ? { installed: true, detail: zcodeDbPath }
           : { installed: false },
+        qoder: qoderInstalled
+          ? { installed: true, detail: qoderDbPath }
+          : { installed: false },
         kilocode: kilocodeInstalled
           ? { installed: true, files: kilocodeTaskFiles.length }
           : { installed: false },
@@ -746,7 +770,7 @@ async function cmdStatus(argv = []) {
         ? `- Kimi Code: passive reader (${kimiWireFiles.length + kimiCodeWireFiles.length} wire.jsonl file${(kimiWireFiles.length + kimiCodeWireFiles.length) !== 1 ? "s" : ""} found, directories: ${kimiActive.join(" | ") || "none"})`
         : null,
       kiroCliInstalled
-        ? `- Kiro CLI: SQLite data.sqlite3 found (tokens approximated from char lengths, merged under 'kiro' source)`
+        ? `- Kiro CLI: passive reader (${kiroCliSessionFiles.length} session file${kiroCliSessionFiles.length !== 1 ? "s" : ""} found, SQLite ${kiroCliDbExists ? "found" : "not found"}; tokens approximated from char lengths and merged under 'kiro')`
         : null,
       codebuddyInstalled
         ? `- CodeBuddy hooks: ${codebuddyHookConfigured ? "set" : "unset"} (${codebuddyFiles.length} usage file${codebuddyFiles.length !== 1 ? "s" : ""} found)`
@@ -775,6 +799,9 @@ async function cmdStatus(argv = []) {
       zcodeInstalled
         ? `- ZCode: passive reader (${zcodeDbPath})`
         : null,
+      qoderInstalled
+        ? `- Qoder: passive reader (${qoderDbPath})`
+        : null,
       opencodeInstalled
         ? `- OpenCode: passive reader (storage: ${opencodeStorageActive.join(" | ") || "not found"}, DB: ${opencodeDbActive.join(" | ") || "not found"})`
         : null,

package/src/commands/sync.js CHANGED Viewed

@@ -20,6 +20,8 @@ const {
   readOpencodeDbMessages,
   readMimoDbMessages,
   readZcodeDbMessages,
+  resolveQoderDbPaths,
+  readQoderDbMessages,
   resolveKiroDbPath,
   resolveKiroJsonlPath,
   resolveHermesPath,
@@ -35,6 +37,7 @@ const {
   parseGeminiIncremental,
   parseOpencodeIncremental,
   parseOpencodeDbIncremental,
+  parseQoderDbIncremental,
   parseOpenclawIncremental,
   parseCursorApiIncremental,
   parseKiroIncremental,
@@ -113,6 +116,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 +197,17 @@ 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.
+// v2 removes the unreliable multi_agent_version pre-gate and validates every
+// contributing rollout before committing the rebuild. The new key is required
+// so installs that finalized the original migration on a false negative retry.
+const CODEX_USAGE_LINEAGE_REPAIR_KEY = "codexUsageLineageRepair_2026_07_v2";
+// 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;
@@ -236,6 +255,7 @@ const AUTO_SYNC_SOURCES = new Set([
   "opencode",
   "openclaw",
   "pi",
+  "qoder",
   "roocode",
   "workbuddy",
   "zcode",
@@ -457,6 +477,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 +509,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 +565,7 @@ async function cmdSync(argv, context = {}) {
         projectQueueStatePath,
         rolloutFiles,
       });
-      await repairCodexForkReplayInflation({
+      const codexForkRepairRan = await repairCodexForkReplayInflation({
         cursors,
         queuePath,
         queueStatePath,
@@ -532,6 +574,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 +591,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");
@@ -903,6 +981,47 @@ async function cmdSync(argv, context = {}) {
       };
     }
+    let qoderResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    if (sourceAllowed("qoder")) {
+      const qoderPaths = resolveQoderDbPaths({
+        home,
+        env: process.env,
+        platform: process.platform,
+      });
+      if (qoderPaths.native || qoderPaths.wsl) {
+        if (progress?.enabled) {
+          progress.start(`Parsing Qoder ${renderBar(0)} | buckets 0`);
+        }
+        try {
+          const result = await multiInstallParse({
+            paths: qoderPaths,
+            parserFn: async ({ dbPath, ...rest }) => {
+              const dbMessages = await readQoderDbMessages(dbPath);
+              const parsed = await parseQoderDbIncremental({ dbMessages, ...rest });
+              return {
+                recordsProcessed: parsed.messagesProcessed || 0,
+                eventsAggregated: parsed.eventsAggregated || 0,
+                bucketsQueued: parsed.bucketsQueued || 0,
+              };
+            },
+            providerName: "qoder",
+            cursors,
+            queuePath,
+            projectQueuePath,
+            getParams: (dbPath) => ({ dbPath }),
+            onProgress: makeProviderProgress("Qoder"),
+          });
+          qoderResult = {
+            recordsProcessed: result.recordsProcessed || 0,
+            eventsAggregated: result.eventsAggregated || 0,
+            bucketsQueued: result.bucketsQueued || 0,
+          };
+        } catch (err) {
+          warnProviderParseFailure("Qoder", err, opts);
+        }
+      }
+    }
     async function parseOpencodeDbForInstall({ dbPath, readFn, source, cursorKey, ...rest }) {
       if (!dbPath || !fssync.existsSync(dbPath)) {
         return { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
@@ -1326,8 +1445,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
@@ -1996,6 +2116,7 @@ async function cmdSync(argv, context = {}) {
       geminiResult.filesProcessed +
       antigravityResult.filesProcessed +
       opencodeResult.filesProcessed +
+      qoderResult.recordsProcessed +
       cursorResult.recordsProcessed +
       kiroResult.recordsProcessed +
       kiroCliResult.recordsProcessed +
@@ -2025,6 +2146,7 @@ async function cmdSync(argv, context = {}) {
       geminiResult.bucketsQueued +
       antigravityResult.bucketsQueued +
       opencodeResult.bucketsQueued +
+      qoderResult.bucketsQueued +
       cursorResult.bucketsQueued +
       kiroResult.bucketsQueued +
       kiroCliResult.bucketsQueued +
@@ -2339,6 +2461,7 @@ module.exports = {
   migrateRolloutCumulativeDeltaBuckets,
   repairCodexRescanInflation,
   repairCodexForkReplayInflation,
+  repairCodexInterleavedUsageInflation,
   repairDroidDuplicateSessionInflation,
   repairMimoClaudeMislabel,
   reincludeClaudeMemObserverFiles,
@@ -2352,6 +2475,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,
@@ -3405,6 +3529,7 @@ async function repairCodexRescanInflation({
   projectQueuePath,
   projectQueueStatePath,
   rolloutFiles,
+  expectedCodexFileSnapshots = null,
   // The fork-replay repair (#169 follow-up) re-runs this exact rebuild under
   // its own key: the rebuild always uses the CURRENT parser, so any parser fix
   // shipped since the last run is applied to the rebuilt history.
@@ -3593,6 +3718,16 @@ async function repairCodexRescanInflation({
     }
   }
+  const rebuildValidation = expectedCodexFileSnapshots instanceof Map
+    ? await validateCodexRebuildFileSnapshots(rebuilt.files, expectedCodexFileSnapshots)
+    : { ok: true };
+  if (!rebuildValidation.ok) {
+    console.error(
+      `[sync] codex rescan repair: ${rebuildValidation.reason} — skipping to avoid data loss`,
+    );
+    return false;
+  }
   // COMMIT (only after a verified rebuild). A crash partway just leaves the
   // migration to re-run next sync — re-rebuild + re-strip + re-commit converges.
   //
@@ -3828,6 +3963,219 @@ async function repairCodexForkReplayInflation({
   });
 }
+// Rebuild historical Codex usage only when a rollout proves that the old
+// single-baseline parser crossed cumulative SessionState lineages. Detection is
+// based on the token counter stream itself, not multi_agent_version metadata:
+// affected legacy rollouts can predate that marker or carry it only in the
+// middle of a large file. Every contributing rollout must also be valid and
+// stable before the atomic rebuild can replace live history.
+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,
+    expectedCodexFileSnapshots: scan.fileSnapshots,
+    migrationKey: CODEX_USAGE_LINEAGE_REPAIR_KEY,
+    uploadNote: "reset_after_codex_usage_lineage_2026_07_v2",
+  });
+}
+async function scanForInterleavedCodexUsage(
+  rolloutFiles,
+  { maxLineageScanBytes = Infinity } = {},
+) {
+  let affected = false;
+  let remainingBytes = Number.isFinite(maxLineageScanBytes)
+    ? Math.max(0, maxLineageScanBytes)
+    : Infinity;
+  const fileSnapshots = new Map();
+  const seenPaths = 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" || seenPaths.has(fp)) continue;
+    seenPaths.add(fp);
+    const lineage = await scanCodexUsageLineages(fp, remainingBytes);
+    if (lineage.indeterminate) {
+      return { affected: false, indeterminate: true, fileSnapshots: new Map() };
+    }
+    affected ||= lineage.affected;
+    fileSnapshots.set(fp, lineage.fileSnapshot);
+    if (Number.isFinite(remainingBytes)) {
+      remainingBytes = Math.max(0, remainingBytes - lineage.bytesRead);
+    }
+  }
+  return { affected, indeterminate: false, fileSnapshots };
+}
+async function scanCodexUsageLineages(filePath, maxBytes = Infinity) {
+  let stream = null;
+  let rl = null;
+  try {
+    const before = await readCodexFileSnapshot(filePath);
+    const state = createUsageDeltaState();
+    const byteLimit = Number.isFinite(maxBytes) ? Math.max(0, maxBytes) : Infinity;
+    let bytesRead = 0;
+    let affected = false;
+    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.trim()) continue;
+      let obj;
+      try {
+        obj = JSON.parse(line);
+      } catch (_e) {
+        return { affected: false, indeterminate: true };
+      }
+      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) {
+        affected = true;
+      }
+    }
+    const after = await readCodexFileSnapshot(filePath);
+    if (!sameCodexFileSnapshot(before, after)) {
+      return { affected: false, indeterminate: true };
+    }
+    return {
+      affected,
+      indeterminate: false,
+      bytesRead,
+      fileSnapshot: after,
+    };
+  } catch (_e) {
+    return { affected: false, indeterminate: true };
+  } finally {
+    if (rl) rl.close();
+    if (stream) stream.destroy();
+  }
+}
+async function readCodexFileSnapshot(filePath) {
+  const stat = await fs.stat(filePath);
+  return {
+    size: Number(stat.size),
+    mtimeMs: Number(stat.mtimeMs),
+    ctimeMs: Number(stat.ctimeMs),
+    ino: Number(stat.ino),
+    dev: Number(stat.dev),
+  };
+}
+function sameCodexFileSnapshot(left, right) {
+  return Boolean(
+    left &&
+      right &&
+      left.size === right.size &&
+      left.mtimeMs === right.mtimeMs &&
+      left.ctimeMs === right.ctimeMs &&
+      left.ino === right.ino &&
+      left.dev === right.dev
+  );
+}
+async function validateCodexRebuildFileSnapshots(rebuiltFiles, expectedSnapshots) {
+  for (const [filePath, expected] of expectedSnapshots) {
+    let actual;
+    try {
+      actual = await readCodexFileSnapshot(filePath);
+    } catch (_e) {
+      return { ok: false, reason: "a scanned rollout became unreadable during rebuild" };
+    }
+    if (!sameCodexFileSnapshot(expected, actual)) {
+      return { ok: false, reason: "a scanned rollout changed during rebuild" };
+    }
+    const rebuiltCursor = rebuiltFiles?.[filePath];
+    if (!rebuiltCursor) {
+      return { ok: false, reason: "the rebuild omitted a scanned rollout cursor" };
+    }
+    if (Number(rebuiltCursor.offset) !== expected.size) {
+      return { ok: false, reason: "the rebuild did not consume a scanned rollout through EOF" };
+    }
+  }
+  return { ok: true };
+}
+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