tokentracker-cli 0.77.1 → 0.77.2

package/src/lib/rollout.js

@@ -3729,7 +3729,11 @@ async function parseKiroIncremental({ dbPath, jsonlPath, cursors, queuePath, onP
         jsonl: { lastLine: jsonlResult.lineCount, updatedAt: new Date().toISOString() },
         updatedAt: new Date().toISOString(),
       };
-      return { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+      return {
+        recordsProcessed: 0,
+        eventsAggregated: 0,
+        bucketsQueued: 0,
+      };
     }
   } else {
     return { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
@@ -4212,7 +4216,11 @@ async function parseHermesIncremental({ hermesPath, dbPath, cursors, queuePath,
     updatedAt, // Update the overall profile state timestamp even if the DB doesn't exist for the fast-path check
   };
 
-  return { recordsProcessed, eventsAggregated, bucketsQueued };
+  return {
+    recordsProcessed,
+    eventsAggregated,
+    bucketsQueued,
+  };
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -4993,7 +5001,11 @@ async function parseKiroCliFromSessionFiles({
       fileOffsets,
       updatedAt: new Date().toISOString(),
     };
-    return { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    return {
+      recordsProcessed: 0,
+      eventsAggregated: 0,
+      bucketsQueued: 0,
+    };
   }
 
   const hourlyState = normalizeHourlyState(cursors?.hourly);
@@ -5124,7 +5136,11 @@ async function parseKiroCliFromSessionFiles({
   cursors.hourly = hourlyState;
   cursors.kiroCli = { ...kiroCliState, seenIds: cappedSeen, fileOffsets, updatedAt };
 
-  return { recordsProcessed, eventsAggregated, bucketsQueued };
+  return {
+    recordsProcessed,
+    eventsAggregated,
+    bucketsQueued,
+  };
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -9264,6 +9280,46 @@ function pickCopilotModel(attrs) {
 }
 
 const COPILOT_PARSER_VERSION = 2;
+const COPILOT_USAGE_CLAIM_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const COPILOT_USAGE_CLAIM_MAX_ENTRIES = 10_000;
+
+function pruneCopilotUsageClaims(
+  events,
+  nowMs = Date.now(),
+  maxEntries = COPILOT_USAGE_CLAIM_MAX_ENTRIES,
+) {
+  const cutoffMs = nowMs - COPILOT_USAGE_CLAIM_RETENTION_MS;
+  const retained = [];
+  for (const event of Array.isArray(events) ? events : []) {
+    if (!event || typeof event !== "object" || event.consumed === true) {
+      continue;
+    }
+    const storedFirstSeenAtMs = Number(event.firstSeenAtMs);
+    const firstSeenAtMs =
+      Number.isFinite(storedFirstSeenAtMs) && storedFirstSeenAtMs > 0
+        ? storedFirstSeenAtMs
+        : nowMs;
+    if (firstSeenAtMs < cutoffMs) continue;
+    retained.push(
+      firstSeenAtMs === storedFirstSeenAtMs
+        ? event
+        : { ...event, firstSeenAtMs },
+    );
+  }
+  return retained.length > maxEntries
+    ? retained.slice(retained.length - maxEntries)
+    : retained;
+}
+
+function replaceCopilotUsageClaims(
+  target,
+  nowMs = Date.now(),
+  maxEntries = COPILOT_USAGE_CLAIM_MAX_ENTRIES,
+) {
+  if (!Array.isArray(target)) return;
+  const retained = pruneCopilotUsageClaims(target, nowMs, maxEntries);
+  target.splice(0, target.length, ...retained);
+}
 
 function isCopilotV1ChatSpan(record) {
   if (!record || record.type !== "span") return false;
@@ -9288,6 +9344,65 @@ function getCopilotDedupKey(record, attrs = record?.attributes || {}) {
   return traceId && spanId ? `${traceId}:${spanId}` : responseId ? `resp:${responseId}` : null;
 }
 
+function copilotUsageMatchKey({
+  sessionId,
+  model,
+  input,
+  output,
+  cacheRead,
+  cacheWrite,
+  reasoning,
+}) {
+  return [
+    sessionId || "",
+    normalizeCopilotAppModel(model) || COPILOT_APP_DEFAULT_MODEL,
+    toNonNegativeInt(input),
+    toNonNegativeInt(output),
+    toNonNegativeInt(cacheRead),
+    toNonNegativeInt(cacheWrite),
+    toNonNegativeInt(reasoning),
+  ].join("|");
+}
+
+function createCopilotStoreUsageMatcher(events) {
+  const candidates = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    if (!event || typeof event !== "object") continue;
+    if (event.consumed === true) continue;
+    const tsMs = Number(event.tsMs);
+    if (!Number.isFinite(tsMs) || tsMs <= 0) continue;
+    const key = copilotUsageMatchKey(event);
+    const list = candidates.get(key) || [];
+    list.push({ tsMs, event });
+    candidates.set(key, list);
+  }
+  for (const list of candidates.values()) {
+    list.sort((a, b) => a.tsMs - b.tsMs);
+  }
+  return {
+    consume(event, toleranceMs = 2_000) {
+      const tsMs = Number(event?.tsMs);
+      if (!Number.isFinite(tsMs) || tsMs <= 0) return false;
+      const key = copilotUsageMatchKey(event || {});
+      const list = candidates.get(key);
+      if (!list || list.length === 0) return false;
+      let bestIndex = -1;
+      let bestDistance = Infinity;
+      for (let i = 0; i < list.length; i++) {
+        const distance = Math.abs(list[i].tsMs - tsMs);
+        if (distance <= toleranceMs && distance < bestDistance) {
+          bestIndex = i;
+          bestDistance = distance;
+        }
+      }
+      if (bestIndex < 0) return false;
+      const [matched] = list.splice(bestIndex, 1);
+      matched.event.consumed = true;
+      return true;
+    },
+  };
+}
+
 // Migration helper: stream the bytes v1 already saw (0 -> prevSize), classify
 // whether the file contains old CLI spans v1 processed, and whether it also
 // contains v2-only chat records v1 skipped. Mixed files must be replayed, but
@@ -9334,7 +9449,54 @@ async function scanCopilotV1MigrationFile(filePath, maxBytes) {
   return result;
 }
 
-async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgress, env } = {}) {
+async function copilotOtelCursorHasLegacyCliUsage(cursors) {
+  const state =
+    cursors?.copilot && typeof cursors.copilot === "object"
+      ? cursors.copilot
+      : {};
+  if (state.legacyCliHistory === true) return true;
+  if (state.usageClaimsComplete === true) return false;
+  const offsets =
+    state.fileOffsets && typeof state.fileOffsets === "object"
+      ? state.fileOffsets
+      : {};
+  const entries = Object.entries(offsets).filter(
+    ([, entry]) => Number(entry?.size) > 0,
+  );
+  const hasSeenIds =
+    Array.isArray(state.seenIds) && state.seenIds.length > 0;
+  if (entries.length === 0) return hasSeenIds;
+  for (const [filePath, entry] of entries) {
+    let stat;
+    try {
+      stat = fssync.statSync(filePath);
+    } catch (_e) {
+      return true;
+    }
+    if (
+      stat.size < Number(entry?.size) ||
+      (typeof entry?.ino === "number" && stat.ino !== entry.ino)
+    ) {
+      return true;
+    }
+    const scan = await scanCopilotV1MigrationFile(
+      filePath,
+      Number(entry?.size) || 0,
+    );
+    if (scan.v1Processed) return true;
+  }
+  return false;
+}
+
+async function parseCopilotIncremental({
+  otelPaths,
+  cursors,
+  queuePath,
+  onProgress,
+  env,
+  skipCliSpans = false,
+  storeUsageEvents,
+} = {}) {
   await ensureDir(path.dirname(queuePath));
   const copilotState = cursors.copilot && typeof cursors.copilot === "object" ? cursors.copilot : {};
   const seenIds = new Set(Array.isArray(copilotState.seenIds) ? copilotState.seenIds : []);
@@ -9344,6 +9506,16 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
       ? copilotState.fileOffsets
       : {};
   const fileOffsets = { ...fileOffsetsRaw };
+  const claimNowMs = Date.now();
+  const recentOtelUsageEvents = pruneCopilotUsageClaims(
+    copilotState.recentUsageEvents,
+    claimNowMs,
+  );
+  replaceCopilotUsageClaims(storeUsageEvents, claimNowMs, Infinity);
+  const hadPriorUsageHistory =
+    seenIds.size > 0 || Object.keys(fileOffsetsRaw).length > 0;
+  let usageClaimsComplete =
+    copilotState.usageClaimsComplete === true || !hadPriorUsageHistory;
   const migrationSkipLineHashes = new Map();
   // One-shot v1->v2 migration:
   // - pure v2-only files: clear offset and re-read all skipped Chat records
@@ -9371,9 +9543,16 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
       version: COPILOT_PARSER_VERSION,
       seenIds: Array.from(seenIds),
       fileOffsets,
+      recentUsageEvents: recentOtelUsageEvents,
+      usageClaimsComplete,
       updatedAt: new Date().toISOString(),
     };
-    return { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    return {
+      recordsProcessed: 0,
+      eventsAggregated: 0,
+      bucketsQueued: 0,
+      usageClaims: recentOtelUsageEvents,
+    };
   }
 
   const hourlyState = normalizeHourlyState(cursors?.hourly);
@@ -9381,6 +9560,7 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
   const cb = typeof onProgress === "function" ? onProgress : null;
   let recordsProcessed = 0;
   let eventsAggregated = 0;
+  const storeUsageMatcher = createCopilotStoreUsageMatcher(storeUsageEvents);
 
   for (let fileIdx = 0; fileIdx < files.length; fileIdx++) {
     const filePath = files[fileIdx];
@@ -9436,6 +9616,10 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
       // gen_ai.response.id is per-LLM-call unique.
       const dedupKey = getCopilotDedupKey(record, attrs);
       if (dedupKey && seenIds.has(dedupKey)) continue;
+      if (skipCliSpans && isCopilotV1ChatSpan(record)) {
+        if (dedupKey) seenIds.add(dedupKey);
+        continue;
+      }
 
       const inputRaw = toNonNegativeInt(attrs["gen_ai.usage.input_tokens"]);
       const output = toNonNegativeInt(attrs["gen_ai.usage.output_tokens"]);
@@ -9495,6 +9679,30 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
       const model =
         normalizeCopilotAppModel(pickCopilotModel(attrs)) ||
         COPILOT_APP_DEFAULT_MODEL;
+      const cliSessionId =
+        typeof attrs["gen_ai.conversation.id"] === "string"
+          ? attrs["gen_ai.conversation.id"].trim()
+          : "";
+      if (cliSpan && !cliSessionId) usageClaimsComplete = false;
+      const matchBase = {
+        sessionId: cliSessionId,
+        model,
+        output: outputWithoutReasoning,
+        cacheRead: cacheReadClamped,
+        cacheWrite: cacheWriteClamped,
+        reasoning: reasoningClamped,
+        tsMs,
+      };
+      const matchedStoreUsage =
+        isCopilotV1ChatSpan(record) &&
+        storeUsageMatcher.consume({
+          ...matchBase,
+          input,
+        });
+      if (matchedStoreUsage) {
+        if (dedupKey) seenIds.add(dedupKey);
+        continue;
+      }
 
       const delta = {
         input_tokens: input,
@@ -9515,6 +9723,13 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
       addTotals(bucket.totals, delta);
       touchedBuckets.add(bucketKey("copilot", model, bucketStart));
       eventsAggregated++;
+      if (cliSpan && cliSessionId) {
+        recentOtelUsageEvents.push({
+          ...matchBase,
+          input,
+          firstSeenAtMs: claimNowMs,
+        });
+      }
       if (dedupKey) seenIds.add(dedupKey);
 
       if (cb) {
@@ -9542,6 +9757,10 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
   // Cap dedup set to last 10k IDs to bound state size
   const seenArr = Array.from(seenIds);
   const cappedSeen = seenArr.length > 10_000 ? seenArr.slice(seenArr.length - 10_000) : seenArr;
+  const retainedRecentOtelUsageEvents = pruneCopilotUsageClaims(
+    recentOtelUsageEvents,
+  );
+  replaceCopilotUsageClaims(storeUsageEvents, Date.now(), Infinity);
 
   const bucketsQueued = await enqueueTouchedBuckets({ queuePath, hourlyState, touchedBuckets });
   const updatedAt = new Date().toISOString();
@@ -9552,10 +9771,914 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
     version: COPILOT_PARSER_VERSION,
     seenIds: cappedSeen,
     fileOffsets,
+    recentUsageEvents: retainedRecentOtelUsageEvents,
+    usageClaimsComplete,
     updatedAt,
   };
 
-  return { recordsProcessed, eventsAggregated, bucketsQueued };
+  return {
+    recordsProcessed,
+    eventsAggregated,
+    bucketsQueued,
+    usageClaims: recentOtelUsageEvents,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GitHub Copilot local runtime — session-store.db assistant_usage_events
+//
+// Copilot CLI 1.0.70+ persists one row per LLM request here. The Copilot App
+// uses the same runtime, so this is the only local source that remains complete
+// when one session moves App -> CLI -> App (or the reverse). data.db only keeps
+// the App-owned portion of those sessions.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const COPILOT_STORE_CURSOR_VERSION = 2;
+const COPILOT_STORE_LEGACY_MODEL = "github-copilot-legacy";
+
+function resolveCopilotDbPaths({ fileName, overrideEnvKey }, env = process.env) {
+  const home =
+    process.platform === "win32"
+      ? env.USERPROFILE || env.HOME || require("node:os").homedir()
+      : env.HOME || require("node:os").homedir();
+  const paths = new Set();
+  const addDbPath = (dbPath) => {
+    const normalized = normalizeCopilotDbPath(dbPath, env);
+    if (normalized) paths.add(normalized);
+  };
+  const addHome = (homePath) => {
+    const normalizedHome = normalizeCopilotDbPath(homePath, env);
+    if (normalizedHome) addDbPath(path.join(normalizedHome, fileName));
+  };
+
+  if (typeof env[overrideEnvKey] === "string" && env[overrideEnvKey].trim()) {
+    addDbPath(env[overrideEnvKey]);
+  }
+  if (typeof env.COPILOT_HOME === "string" && env.COPILOT_HOME.trim()) {
+    addHome(env.COPILOT_HOME);
+  }
+
+  addDbPath(path.join(home, ".copilot", fileName));
+
+  return Array.from(paths).sort();
+}
+
+function resolveCopilotSessionStorePaths(env = process.env) {
+  return resolveCopilotDbPaths(
+    {
+      fileName: "session-store.db",
+      overrideEnvKey: "TOKENTRACKER_COPILOT_SESSION_STORE_DB",
+    },
+    env,
+  );
+}
+
+function copilotStoreRowKey(row) {
+  if (!row) return null;
+  return crypto
+    .createHash("sha256")
+    .update(
+      JSON.stringify([
+        row.max_id ?? row.id,
+        row.session_id,
+        row.model,
+        row.input_tokens,
+        row.output_tokens,
+        row.cache_read_tokens,
+        row.cache_write_tokens,
+        row.reasoning_tokens,
+        row.created_at,
+      ]),
+    )
+    .digest("hex");
+}
+
+function copilotStoreEventFingerprint(row) {
+  const sessionId =
+    typeof row?.session_id === "string" ? row.session_id.trim() : "";
+  if (!sessionId) return null;
+  const normalized = normalizeCopilotSessionStoreUsage(row);
+  const timestamp =
+    parseCopilotAppTimestamp(row?.created_at) ||
+    `invalid:${String(row?.created_at ?? "")}`;
+  return crypto
+    .createHash("sha256")
+    .update(
+      JSON.stringify([
+        sessionId,
+        normalizeCopilotAppModel(row?.model) || COPILOT_APP_DEFAULT_MODEL,
+        normalized.input_tokens,
+        normalized.output_tokens,
+        normalized.cached_input_tokens,
+        normalized.cache_creation_input_tokens,
+        normalized.reasoning_output_tokens,
+        timestamp,
+      ]),
+    )
+    .digest("hex");
+}
+
+function normalizeCopilotFingerprintCounts(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const result = {};
+  for (const [fingerprint, count] of Object.entries(value)) {
+    const normalized = toNonNegativeInt(count);
+    if (/^[a-f0-9]{64}$/.test(fingerprint) && normalized > 0) {
+      result[fingerprint] = normalized;
+    }
+  }
+  return result;
+}
+
+function normalizeCopilotPendingMalformedEvents(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const result = {};
+  for (const [id, fingerprint] of Object.entries(value)) {
+    const normalizedId = toNonNegativeInt(id);
+    if (normalizedId > 0) {
+      result[normalizedId] =
+        typeof fingerprint === "string" ? fingerprint : "";
+    }
+  }
+  return result;
+}
+
+function incrementCopilotFingerprintCount(counts, fingerprint) {
+  if (!fingerprint) return;
+  counts[fingerprint] = toNonNegativeInt(counts[fingerprint]) + 1;
+}
+
+function latestCopilotTimestamp(first, second) {
+  const values = [first, second]
+    .map((value) => parseCopilotAppTimestamp(value))
+    .filter(Boolean);
+  if (values.length === 0) return null;
+  return values.reduce((latest, value) => (value > latest ? value : latest));
+}
+
+function omitCopilotLegacyCatchupState(state) {
+  const clean = { ...(state || {}) };
+  delete clean.pendingCatchupMaxId;
+  delete clean.pendingCatchupFingerprint;
+  delete clean.pendingLegacyCatchup;
+  return clean;
+}
+
+function readCopilotSessionStoreMetadata(
+  dbPath,
+  sqliteOptions = {},
+  cursorId = 0,
+) {
+  const tables = readSqliteJsonRows(
+    dbPath,
+    "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('assistant_usage_events', 'schema_version')",
+    {
+      label: "GitHub Copilot session store",
+      maxBuffer: 4 * 1024 * 1024,
+      timeout: 10_000,
+      readOnly: true,
+      throwOnReadFailure: true,
+      ...sqliteOptions,
+    },
+  );
+  const names = new Set(tables.map((row) => row?.name).filter(Boolean));
+  if (!names.has("assistant_usage_events")) {
+    return { active: false, schemaVersion: null, maxId: 0 };
+  }
+  const maxRows = readSqliteJsonRows(
+    dbPath,
+    `
+      SELECT
+        id AS max_id,
+        session_id,
+        model,
+        input_tokens,
+        output_tokens,
+        cache_read_tokens,
+        cache_write_tokens,
+        reasoning_tokens,
+        created_at
+      FROM assistant_usage_events
+      ORDER BY id DESC
+      LIMIT 1
+    `.trim(),
+    {
+      label: "GitHub Copilot session store",
+      maxBuffer: 4 * 1024 * 1024,
+      timeout: 10_000,
+      readOnly: true,
+      throwOnReadFailure: true,
+      ...sqliteOptions,
+    },
+  );
+  let schemaVersion = null;
+  if (names.has("schema_version")) {
+    const versionRows = readSqliteJsonRows(
+      dbPath,
+      "SELECT version FROM schema_version LIMIT 1",
+      {
+        label: "GitHub Copilot session store",
+        maxBuffer: 4 * 1024 * 1024,
+        timeout: 10_000,
+        readOnly: true,
+        throwOnReadFailure: true,
+        ...sqliteOptions,
+      },
+    );
+    schemaVersion = toNonNegativeInt(versionRows[0]?.version);
+  }
+  let cursorRowKey = null;
+  const normalizedCursorId = toNonNegativeInt(cursorId);
+  if (normalizedCursorId > 0) {
+    if (normalizedCursorId === toNonNegativeInt(maxRows[0]?.max_id)) {
+      cursorRowKey = copilotStoreRowKey(maxRows[0]);
+    } else {
+      const cursorRows = readSqliteJsonRows(
+        dbPath,
+        `
+          SELECT
+            id,
+            session_id,
+            model,
+            input_tokens,
+            output_tokens,
+            cache_read_tokens,
+            cache_write_tokens,
+            reasoning_tokens,
+            created_at
+          FROM assistant_usage_events
+          WHERE id = ${normalizedCursorId}
+          LIMIT 1
+        `.trim(),
+        {
+          label: "GitHub Copilot session store",
+          maxBuffer: 4 * 1024 * 1024,
+          timeout: 10_000,
+          readOnly: true,
+          throwOnReadFailure: true,
+          ...sqliteOptions,
+        },
+      );
+      cursorRowKey = copilotStoreRowKey(cursorRows[0]);
+    }
+  }
+  return {
+    active: true,
+    schemaVersion,
+    maxId: toNonNegativeInt(maxRows[0]?.max_id),
+    lastRowKey: copilotStoreRowKey(maxRows[0]),
+    lastEventAt: parseCopilotAppTimestamp(maxRows[0]?.created_at),
+    cursorRowKey,
+  };
+}
+
+function describeCopilotSessionStoreDb(dbPath, sqliteOptions = {}) {
+  let snap = null;
+  try {
+    snap = snapshotSqliteDb(dbPath);
+    const metadata = readCopilotSessionStoreMetadata(snap.path, sqliteOptions);
+    if (!metadata.active) {
+      return {
+        path: dbPath,
+        active: false,
+        schemaVersion: metadata.schemaVersion,
+        eventCount: 0,
+        lastEventId: 0,
+        lastEventAt: null,
+      };
+    }
+    const countRows = readSqliteJsonRows(
+      snap.path,
+      "SELECT COUNT(*) AS event_count FROM assistant_usage_events",
+      {
+        label: "GitHub Copilot session store",
+        maxBuffer: 4 * 1024 * 1024,
+        timeout: 10_000,
+        readOnly: true,
+        throwOnReadFailure: true,
+        ...sqliteOptions,
+      },
+    );
+    return {
+      path: dbPath,
+      active: true,
+      schemaVersion: metadata.schemaVersion,
+      eventCount: toNonNegativeInt(countRows[0]?.event_count),
+      lastEventId: metadata.maxId,
+      lastEventAt: metadata.lastEventAt,
+    };
+  } finally {
+    if (snap) snap.cleanup();
+  }
+}
+
+function readCopilotSessionStoreUsageRowsWhere(
+  dbPath,
+  whereClause,
+  sqliteOptions = {},
+) {
+  return readSqliteJsonRows(
+    dbPath,
+    `
+      SELECT
+        id,
+        session_id,
+        model,
+        input_tokens,
+        output_tokens,
+        cache_read_tokens,
+        cache_write_tokens,
+        reasoning_tokens,
+        token_details_json,
+        created_at
+      FROM assistant_usage_events
+      WHERE ${whereClause}
+      ORDER BY id ASC
+    `.trim(),
+    {
+      label: "GitHub Copilot session store",
+      maxBuffer: 64 * 1024 * 1024,
+      timeout: 60_000,
+      readOnly: true,
+      throwOnReadFailure: true,
+      ...sqliteOptions,
+    },
+  );
+}
+
+function readCopilotSessionStoreUsageRows(dbPath, lastId, sqliteOptions = {}) {
+  return readCopilotSessionStoreUsageRowsWhere(
+    dbPath,
+    `id > ${toNonNegativeInt(lastId)}`,
+    sqliteOptions,
+  );
+}
+
+function readCopilotSessionStoreUsageRowsByIds(
+  dbPath,
+  ids,
+  sqliteOptions = {},
+) {
+  const normalizedIds = [
+    ...new Set(
+      (Array.isArray(ids) ? ids : [])
+        .map(toNonNegativeInt)
+        .filter((id) => id > 0),
+    ),
+  ];
+  const rows = [];
+  for (let start = 0; start < normalizedIds.length; start += 500) {
+    const chunk = normalizedIds.slice(start, start + 500);
+    rows.push(
+      ...readCopilotSessionStoreUsageRowsWhere(
+        dbPath,
+        `id IN (${chunk.join(",")})`,
+        sqliteOptions,
+      ),
+    );
+  }
+  return rows.sort((a, b) => toNonNegativeInt(a?.id) - toNonNegativeInt(b?.id));
+}
+
+function parseCopilotStoreTokenDetails(raw) {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  let entries;
+  try {
+    entries = JSON.parse(raw);
+  } catch (_e) {
+    return null;
+  }
+  if (!Array.isArray(entries)) return null;
+  const totals = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
+  let recognized = 0;
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    const count = toNonNegativeInt(entry.tokenCount);
+    switch (entry.tokenType) {
+      case "input":
+        totals.input += count;
+        recognized++;
+        break;
+      case "cache_read":
+        totals.cacheRead += count;
+        recognized++;
+        break;
+      case "cache_write":
+        totals.cacheWrite += count;
+        recognized++;
+        break;
+      case "output":
+        totals.output += count;
+        recognized++;
+        break;
+      default:
+        break;
+    }
+  }
+  return recognized > 0 ? totals : null;
+}
+
+function copilotStoreRecentEvent(row, firstSeenAtMs = Date.now()) {
+  const tsIso = parseCopilotAppTimestamp(row?.created_at);
+  const tsMs = tsIso ? Date.parse(tsIso) : NaN;
+  const sessionId =
+    typeof row?.session_id === "string" ? row.session_id.trim() : "";
+  if (!sessionId || !Number.isFinite(tsMs) || tsMs <= 0) return null;
+  const normalized = normalizeCopilotSessionStoreUsage(row);
+  return {
+    id: toNonNegativeInt(row?.id),
+    sessionId,
+    model: normalizeCopilotAppModel(row?.model) || COPILOT_APP_DEFAULT_MODEL,
+    input: normalized.input_tokens,
+    output: normalized.output_tokens,
+    cacheRead: normalized.cached_input_tokens,
+    cacheWrite: normalized.cache_creation_input_tokens,
+    reasoning: normalized.reasoning_output_tokens,
+    tsMs,
+    firstSeenAtMs,
+  };
+}
+
+function normalizeCopilotSessionStoreUsage(row) {
+  const inputRaw = toNonNegativeInt(row?.input_tokens);
+  const outputRaw = toNonNegativeInt(row?.output_tokens);
+  const reasoning = toNonNegativeInt(row?.reasoning_tokens);
+  const details = parseCopilotStoreTokenDetails(row?.token_details_json);
+  let input;
+  let cacheRead;
+  let cacheWrite;
+  let output;
+  let precision = "fallback";
+
+  if (
+    details &&
+    details.input + details.cacheRead + details.cacheWrite === inputRaw &&
+    details.output === outputRaw
+  ) {
+    input = details.input;
+    cacheRead = details.cacheRead;
+    cacheWrite = details.cacheWrite;
+    output = details.output;
+    precision = "exact";
+  } else {
+    cacheRead = Math.min(toNonNegativeInt(row?.cache_read_tokens), inputRaw);
+    cacheWrite = Math.min(
+      toNonNegativeInt(row?.cache_write_tokens),
+      Math.max(0, inputRaw - cacheRead),
+    );
+    input = Math.max(0, inputRaw - cacheRead - cacheWrite);
+    output = outputRaw;
+  }
+
+  const reasoningClamped = Math.min(reasoning, output);
+  const outputWithoutReasoning = Math.max(0, output - reasoningClamped);
+  return {
+    input_tokens: input,
+    cached_input_tokens: cacheRead,
+    cache_creation_input_tokens: cacheWrite,
+    output_tokens: outputWithoutReasoning,
+    reasoning_output_tokens: reasoningClamped,
+    total_tokens:
+      input + cacheRead + cacheWrite + outputWithoutReasoning + reasoningClamped,
+    precision,
+  };
+}
+
+async function parseCopilotSessionStoreIncremental({
+  dbPath,
+  dbPaths,
+  cursors,
+  queuePath,
+  onProgress,
+  env,
+  sqliteOptions,
+  backfillOnFirstRun = false,
+  excludeSessionIdsOnFirstRun,
+  excludeSessionTotalsOnFirstRun,
+  expectedFingerprints,
+  otelUsageEvents,
+} = {}) {
+  await ensureDir(path.dirname(queuePath));
+  const paths = Array.isArray(dbPaths)
+    ? dbPaths
+    : dbPath
+      ? [dbPath]
+      : resolveCopilotSessionStorePaths(env || process.env);
+  const storeState =
+    cursors.copilotStore && typeof cursors.copilotStore === "object"
+      ? cursors.copilotStore
+      : {};
+  const dbStates =
+    storeState.dbs && typeof storeState.dbs === "object" ? { ...storeState.dbs } : {};
+  let uniquePaths = uniqueCopilotDbPaths(
+    paths,
+    env || process.env,
+    Object.keys(dbStates),
+  );
+  const migratedAliasPaths = coalesceCopilotDbStatesByIdentity(
+    dbStates,
+    uniquePaths,
+    mergeCopilotStoreAliasStates,
+  );
+  uniquePaths = uniquePaths.filter(
+    (dbPath) => !migratedAliasPaths.has(dbPath),
+  );
+  const seenSessions = new Set(
+    Array.isArray(storeState.seenSessions) ? storeState.seenSessions : [],
+  );
+  const excludedFirstRunSessions = new Set(
+    Array.isArray(excludeSessionIdsOnFirstRun)
+      ? excludeSessionIdsOnFirstRun.filter((value) => typeof value === "string" && value)
+      : [],
+  );
+  const excludedFirstRunTotals =
+    excludeSessionTotalsOnFirstRun &&
+    typeof excludeSessionTotalsOnFirstRun === "object" &&
+    !Array.isArray(excludeSessionTotalsOnFirstRun)
+      ? excludeSessionTotalsOnFirstRun
+      : {};
+  const legacyResiduals = new Map();
+  const claimNowMs = Date.now();
+  const recentEvents = pruneCopilotUsageClaims(
+    storeState.recentEvents,
+    claimNowMs,
+  );
+  replaceCopilotUsageClaims(otelUsageEvents, claimNowMs, Infinity);
+  const otelUsageMatcher = createCopilotStoreUsageMatcher(otelUsageEvents);
+  const hourlyState = normalizeHourlyState(cursors?.hourly);
+  const touchedBuckets = new Set();
+  const cb = typeof onProgress === "function" ? onProgress : null;
+  const updatedAt = new Date(claimNowMs).toISOString();
+  let activeDbCount = 0;
+  let adoptedThisRun = false;
+  let recordsProcessed = 0;
+  let eventsAggregated = 0;
+  let dbErrors = 0;
+  const canonicalDbPaths = [];
+  const globalAdoptionPending = storeState.active !== true;
+
+  for (const resolvedDb of uniquePaths) {
+    const dbState =
+      dbStates[resolvedDb] && typeof dbStates[resolvedDb] === "object"
+        ? dbStates[resolvedDb]
+        : {};
+    const seenEventCounts = normalizeCopilotFingerprintCounts(
+      dbState.seenEventCounts,
+    );
+    let pendingMalformedEvents = normalizeCopilotPendingMalformedEvents(
+      dbState.pendingMalformedEvents,
+    );
+    let fingerprint = null;
+    let snap = null;
+    try {
+      fingerprint = sqliteSidecarFingerprint(resolvedDb);
+      const expectedFingerprint = expectedFingerprints?.[resolvedDb];
+      if (
+        expectedFingerprint &&
+        !sameSqliteFingerprint(fingerprint, expectedFingerprint)
+      ) {
+        dbStates[resolvedDb] = {
+          ...omitCopilotLegacyCatchupState(dbState),
+          adoptionDeferredAt: updatedAt,
+          updatedAt,
+        };
+        continue;
+      }
+      const currentIno = fingerprint?.db?.ino;
+      const priorLastId = toNonNegativeInt(dbState.lastId);
+      snap = snapshotSqliteDb(resolvedDb);
+      const metadata = readCopilotSessionStoreMetadata(
+        snap.path,
+        sqliteOptions,
+        priorLastId,
+      );
+      if (!metadata.active) {
+        dbStates[resolvedDb] = {
+          ...omitCopilotLegacyCatchupState(dbState),
+          schemaVersion: metadata.schemaVersion,
+          lastError: null,
+          lastErrorAt: null,
+          updatedAt,
+        };
+        continue;
+      }
+
+      const inodeChanged =
+        typeof dbState.dbIno === "number" &&
+        typeof currentIno === "number" &&
+        dbState.dbIno !== currentIno;
+      const cursorRowChanged =
+        priorLastId > 0 &&
+        typeof dbState.lastRowKey === "string" &&
+        dbState.lastRowKey !== metadata.cursorRowKey;
+      const idRegressed = metadata.maxId < priorLastId;
+      const resetDetected =
+        Boolean(dbState.adoptedAt) && (idRegressed || cursorRowChanged);
+      const needsFingerprintSeed =
+        Boolean(dbState.adoptedAt) &&
+        priorLastId > 0 &&
+        Object.keys(seenEventCounts).length === 0;
+      const resetWithoutFingerprintHistory =
+        resetDetected && needsFingerprintSeed;
+      const reconcileAllRows =
+        (resetDetected || inodeChanged) && !resetWithoutFingerprintHistory;
+      const needsAdoption =
+        globalAdoptionPending ||
+        !dbState.adoptedAt ||
+        resetDetected;
+      const baselineOnly =
+        resetWithoutFingerprintHistory ||
+        (needsAdoption && !resetDetected && !backfillOnFirstRun);
+      const incrementalRows = readCopilotSessionStoreUsageRows(
+        snap.path,
+        reconcileAllRows || baselineOnly || needsFingerprintSeed ? 0 : priorLastId,
+        sqliteOptions,
+      );
+      const pendingRetryRows = resetDetected || reconcileAllRows
+        ? []
+        : readCopilotSessionStoreUsageRowsByIds(
+            snap.path,
+            Object.keys(pendingMalformedEvents),
+            sqliteOptions,
+          );
+      const pendingRetryIds = new Set(
+        pendingRetryRows.map((row) => toNonNegativeInt(row?.id)),
+      );
+      if (resetDetected || reconcileAllRows) {
+        pendingMalformedEvents = {};
+      } else {
+        for (const pendingId of Object.keys(pendingMalformedEvents)) {
+          if (!pendingRetryIds.has(toNonNegativeInt(pendingId))) {
+            delete pendingMalformedEvents[pendingId];
+          }
+        }
+      }
+      const rowsById = new Map();
+      for (const row of [...pendingRetryRows, ...incrementalRows]) {
+        rowsById.set(toNonNegativeInt(row?.id), row);
+      }
+      const rows = Array.from(rowsById.values()).sort(
+        (a, b) => toNonNegativeInt(a?.id) - toNonNegativeInt(b?.id),
+      );
+      // Reindex/reset can rewrite every SQLite id. Subtract the exact metadata
+      // multiset already observed so only genuinely new requests are emitted.
+      const historicalFingerprintCounts = reconcileAllRows
+        ? new Map(
+            Object.entries(seenEventCounts).map(([eventFingerprint, count]) => [
+              eventFingerprint,
+              toNonNegativeInt(count),
+            ]),
+          )
+        : null;
+      if (needsAdoption) adoptedThisRun = true;
+      if (expectedFingerprint) {
+        const finalFingerprint = sqliteSidecarFingerprint(resolvedDb);
+        if (!sameSqliteFingerprint(finalFingerprint, expectedFingerprint)) {
+          dbStates[resolvedDb] = {
+            ...omitCopilotLegacyCatchupState(dbState),
+            adoptionDeferredAt: updatedAt,
+            updatedAt,
+          };
+          continue;
+        }
+        fingerprint = finalFingerprint;
+      }
+      let lastId =
+        reconcileAllRows || baselineOnly ? metadata.maxId : priorLastId;
+      for (const row of rows) {
+        recordsProcessed++;
+        const rowId = toNonNegativeInt(row?.id);
+        lastId = Math.max(lastId, rowId);
+        const sessionId =
+          typeof row?.session_id === "string" ? row.session_id.trim() : "";
+        if (!sessionId) {
+          if (rowId > 0) pendingMalformedEvents[rowId] = "";
+          continue;
+        }
+        const eventFingerprint = copilotStoreEventFingerprint(row);
+        if (historicalFingerprintCounts && eventFingerprint) {
+          const historicalCount = toNonNegativeInt(
+            historicalFingerprintCounts.get(eventFingerprint),
+          );
+          if (historicalCount > 0) {
+            historicalFingerprintCounts.set(
+              eventFingerprint,
+              historicalCount - 1,
+            );
+            if (!parseCopilotAppTimestamp(row?.created_at) && rowId > 0) {
+              pendingMalformedEvents[rowId] = eventFingerprint;
+            }
+            seenSessions.add(sessionId);
+            continue;
+          }
+        }
+        const seedOnly =
+          needsFingerprintSeed && rowId <= priorLastId;
+        const recentEvent = copilotStoreRecentEvent(row, claimNowMs);
+        if (pendingRetryIds.has(rowId) && !recentEvent) {
+          if (seedOnly) {
+            incrementCopilotFingerprintCount(
+              seenEventCounts,
+              eventFingerprint,
+            );
+          }
+          pendingMalformedEvents[rowId] = eventFingerprint || "";
+          seenSessions.add(sessionId);
+          continue;
+        }
+        if (rowId > 0) delete pendingMalformedEvents[rowId];
+        const matchedOtelUsage =
+          recentEvent && otelUsageMatcher.consume(recentEvent);
+        if (matchedOtelUsage) recentEvent.consumed = true;
+        if (baselineOnly || seedOnly) {
+          incrementCopilotFingerprintCount(seenEventCounts, eventFingerprint);
+          if (!recentEvent && rowId > 0) {
+            pendingMalformedEvents[rowId] = eventFingerprint || "";
+          }
+          seenSessions.add(sessionId);
+          continue;
+        }
+        incrementCopilotFingerprintCount(seenEventCounts, eventFingerprint);
+        if (needsAdoption && backfillOnFirstRun && excludedFirstRunSessions.has(sessionId)) {
+          if (
+            !matchedOtelUsage &&
+            Object.prototype.hasOwnProperty.call(
+              excludedFirstRunTotals,
+              sessionId,
+            )
+          ) {
+            const normalized = normalizeCopilotSessionStoreUsage(row);
+            const priorResidual = legacyResiduals.get(sessionId) || {
+              storeTokens: 0,
+              lastEventAt: null,
+            };
+            priorResidual.storeTokens += normalized.total_tokens;
+            priorResidual.lastEventAt = latestCopilotTimestamp(
+              priorResidual.lastEventAt,
+              row?.created_at,
+            );
+            legacyResiduals.set(sessionId, priorResidual);
+          }
+          if (recentEvent && !matchedOtelUsage) recentEvents.push(recentEvent);
+          seenSessions.add(sessionId);
+          continue;
+        }
+        if (matchedOtelUsage) {
+          seenSessions.add(sessionId);
+          continue;
+        }
+        if (recentEvent) recentEvents.push(recentEvent);
+        const normalized = normalizeCopilotSessionStoreUsage(row);
+        if (normalized.total_tokens <= 0) {
+          seenSessions.add(sessionId);
+          continue;
+        }
+        const tsIso = parseCopilotAppTimestamp(row.created_at);
+        const bucketStart = tsIso ? toUtcHalfHourStart(tsIso) : null;
+        if (!bucketStart) {
+          if (rowId > 0) {
+            pendingMalformedEvents[rowId] = eventFingerprint || "";
+          }
+          seenSessions.add(sessionId);
+          continue;
+        }
+        const model =
+          normalizeCopilotAppModel(row.model) || COPILOT_APP_DEFAULT_MODEL;
+        const delta = {
+          input_tokens: normalized.input_tokens,
+          cached_input_tokens: normalized.cached_input_tokens,
+          cache_creation_input_tokens: normalized.cache_creation_input_tokens,
+          output_tokens: normalized.output_tokens,
+          reasoning_output_tokens: normalized.reasoning_output_tokens,
+          total_tokens: normalized.total_tokens,
+          conversation_count: seenSessions.has(sessionId) ? 0 : 1,
+        };
+        const bucket = getHourlyBucket(hourlyState, "copilot", model, bucketStart);
+        addTotals(bucket.totals, delta);
+        touchedBuckets.add(bucketKey("copilot", model, bucketStart));
+        seenSessions.add(sessionId);
+        eventsAggregated++;
+        if (cb) {
+          cb({
+            index: recordsProcessed,
+            total: rows.length,
+            recordsProcessed,
+            eventsAggregated,
+            bucketsQueued: touchedBuckets.size,
+          });
+        }
+      }
+
+      dbStates[resolvedDb] = {
+        ...omitCopilotLegacyCatchupState(dbState),
+        adoptedAt: dbState.adoptedAt || updatedAt,
+        resetAt: resetDetected ? updatedAt : dbState.resetAt || null,
+        schemaVersion: metadata.schemaVersion,
+        lastRowKey: metadata.lastRowKey,
+        lastId: Math.max(lastId, metadata.maxId),
+        lastEventAt: latestCopilotTimestamp(
+          dbState.lastEventAt,
+          metadata.lastEventAt,
+        ),
+        seenEventCounts,
+        pendingMalformedEvents,
+        malformedEventCount: Object.keys(pendingMalformedEvents).length,
+        resetGapEventCount:
+          toNonNegativeInt(dbState.resetGapEventCount) +
+          (resetWithoutFingerprintHistory ? rows.length : 0),
+        dbIno: typeof currentIno === "number" ? currentIno : null,
+        lastDbFingerprint: fingerprint,
+        lastError: null,
+        lastErrorAt: null,
+        updatedAt,
+      };
+      canonicalDbPaths.push(resolvedDb);
+      activeDbCount++;
+    } catch (err) {
+      if (err?.code !== "ENOENT") dbErrors++;
+      dbStates[resolvedDb] = {
+        ...omitCopilotLegacyCatchupState(dbState),
+        lastError: err && err.message ? err.message : String(err),
+        lastErrorAt: updatedAt,
+        updatedAt,
+      };
+    } finally {
+      if (snap) snap.cleanup();
+    }
+  }
+
+  for (const [sessionId, residual] of legacyResiduals) {
+    const baseline = excludedFirstRunTotals[sessionId] || {};
+    const appTotals = normalizeCopilotAppTokenDelta(baseline, {
+      input: 0,
+      output: 0,
+      cached: 0,
+      reasoning: 0,
+    });
+    const residualTokens = Math.max(
+      0,
+      toNonNegativeInt(residual.storeTokens) - appTotals.total_tokens,
+    );
+    if (residualTokens <= 0) continue;
+    const timestamp = latestCopilotTimestamp(
+      residual.lastEventAt,
+      baseline.updatedAt,
+    );
+    const bucketStart = timestamp ? toUtcHalfHourStart(timestamp) : null;
+    if (!bucketStart) continue;
+    const bucket = getHourlyBucket(
+      hourlyState,
+      "copilot",
+      COPILOT_STORE_LEGACY_MODEL,
+      bucketStart,
+    );
+    addTotals(bucket.totals, {
+      input_tokens: residualTokens,
+      cached_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+      output_tokens: 0,
+      reasoning_output_tokens: 0,
+      total_tokens: residualTokens,
+      conversation_count: 0,
+    });
+    touchedBuckets.add(
+      bucketKey("copilot", COPILOT_STORE_LEGACY_MODEL, bucketStart),
+    );
+    eventsAggregated++;
+  }
+
+  const bucketsQueued = await enqueueTouchedBuckets({
+    queuePath,
+    hourlyState,
+    touchedBuckets,
+  });
+  const allCurrentPathsHealthy =
+    uniquePaths.length > 0 &&
+    activeDbCount === uniquePaths.length &&
+    dbErrors === 0;
+  const canonicalActive = storeState.active === true || allCurrentPathsHealthy;
+  hourlyState.updatedAt = updatedAt;
+  cursors.hourly = hourlyState;
+  cursors.copilotStore = {
+    ...omitCopilotLegacyCatchupState(storeState),
+    version: COPILOT_STORE_CURSOR_VERSION,
+    active: canonicalActive,
+    dbs: dbStates,
+    seenSessions: Array.from(seenSessions),
+    recentEvents: pruneCopilotUsageClaims(recentEvents),
+    updatedAt,
+  };
+  return {
+    active: canonicalActive,
+    healthy: allCurrentPathsHealthy,
+    adoptedThisRun,
+    canonicalDbPaths,
+    recordsProcessed,
+    eventsAggregated,
+    bucketsQueued,
+    dbErrors,
+    usageClaims: recentEvents,
+  };
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -9567,9 +10690,9 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
 // there before the child has produced any tokens, so parsing event history would
 // double-count parent usage. The only accounting source here is positive deltas
 // from the `sessions.total_*` counters. Those deltas feed the same aggregate
-// `source="copilot"` pipeline as existing OTEL data (dashboard totals, trends,
-// model breakdown, cost), but the cursor is separate (`cursors.copilotApp`) so
-// Copilot CLI / Chat extension OTEL support keeps its existing behavior.
+// `source="copilot"` pipeline during legacy adoption. Once session-store is
+// canonical, this parser runs observe-only so a temporary store outage cannot
+// create duplicate fallback writes when the store returns.
 // Project attribution and per-conversation detail are intentionally absent:
 // data.db's summary columns do not expose privacy-safe project/message metadata.
 // ─────────────────────────────────────────────────────────────────────────────
@@ -9577,44 +10700,169 @@ async function parseCopilotIncremental({ otelPaths, cursors, queuePath, onProgre
 const COPILOT_APP_CURSOR_VERSION = 1;
 const COPILOT_APP_DEFAULT_MODEL = "github-copilot";
 
-function normalizeCopilotAppDbPath(dbPath, env = process.env) {
+function normalizeCopilotDbPath(dbPath, env = process.env) {
   if (typeof dbPath !== "string" || !dbPath.trim()) return null;
-  const expanded = expandHomePath(dbPath.trim(), env);
-  return path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(expanded);
+  const raw = dbPath.trim();
+  const home =
+    process.platform === "win32"
+      ? env.USERPROFILE || env.HOME || require("node:os").homedir()
+      : env.HOME || require("node:os").homedir();
+  const expanded =
+    raw === "~"
+      ? home
+      : raw.startsWith("~/") || raw.startsWith("~\\")
+        ? path.join(home, raw.slice(2))
+        : raw;
+  const normalized =
+    path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(expanded);
+  return normalized;
 }
 
-function resolveCopilotAppDbPaths(env = process.env) {
-  const home = env.HOME || require("node:os").homedir();
-  const paths = new Set();
-  const addDbPath = (dbPath) => {
-    const normalized = normalizeCopilotAppDbPath(dbPath, env);
-    if (normalized) paths.add(normalized);
+function mergeCopilotStoreAliasStates(primary = {}, alias = {}) {
+  const primaryLastId = toNonNegativeInt(primary?.lastId);
+  const aliasLastId = toNonNegativeInt(alias?.lastId);
+  const primaryUpdatedAt = Date.parse(primary?.updatedAt || "") || 0;
+  const aliasUpdatedAt = Date.parse(alias?.updatedAt || "") || 0;
+  const newer =
+    aliasLastId > primaryLastId ||
+    (aliasLastId === primaryLastId && aliasUpdatedAt > primaryUpdatedAt)
+      ? alias
+      : primary;
+  const seenEventCounts = normalizeCopilotFingerprintCounts(
+    primary?.seenEventCounts,
+  );
+  for (const [fingerprint, count] of Object.entries(
+    normalizeCopilotFingerprintCounts(alias?.seenEventCounts),
+  )) {
+    seenEventCounts[fingerprint] = Math.max(
+      toNonNegativeInt(seenEventCounts[fingerprint]),
+      count,
+    );
+  }
+  const pendingMalformedEvents = {
+    ...normalizeCopilotPendingMalformedEvents(
+      primary?.pendingMalformedEvents,
+    ),
+    ...normalizeCopilotPendingMalformedEvents(
+      alias?.pendingMalformedEvents,
+    ),
   };
-  const addHome = (homePath) => {
-    const normalizedHome = normalizeCopilotAppDbPath(homePath, env);
-    if (normalizedHome) addDbPath(path.join(normalizedHome, "data.db"));
+  return {
+    ...primary,
+    ...newer,
+    seenEventCounts,
+    pendingMalformedEvents,
+    malformedEventCount: Object.keys(pendingMalformedEvents).length,
+    resetGapEventCount: Math.max(
+      toNonNegativeInt(primary?.resetGapEventCount),
+      toNonNegativeInt(alias?.resetGapEventCount),
+    ),
   };
+}
 
-  if (typeof env.TOKENTRACKER_COPILOT_APP_DB === "string" && env.TOKENTRACKER_COPILOT_APP_DB.trim()) {
-    addDbPath(env.TOKENTRACKER_COPILOT_APP_DB);
+function coalesceCopilotDbStatesByIdentity(
+  dbStates,
+  selectedPaths,
+  mergeStates,
+) {
+  if (!dbStates || typeof dbStates !== "object") return new Set();
+  const selectedByIdentity = new Map();
+  const selectedByInode = new Map();
+  for (const selectedPath of selectedPaths) {
+    try {
+      const stat = fssync.statSync(selectedPath);
+      selectedByIdentity.set(`${stat.dev}:${stat.ino}`, selectedPath);
+      if (selectedByInode.has(stat.ino)) selectedByInode.set(stat.ino, null);
+      else selectedByInode.set(stat.ino, selectedPath);
+    } catch (_e) {}
   }
-  if (typeof env.COPILOT_HOME === "string" && env.COPILOT_HOME.trim()) {
-    addHome(env.COPILOT_HOME);
+  const migratedPaths = new Set();
+  for (const [statePath, state] of Object.entries({ ...dbStates })) {
+    let dev = null;
+    let ino = null;
+    try {
+      const stat = fssync.statSync(statePath);
+      dev = stat.dev;
+      ino = stat.ino;
+    } catch (_e) {
+      dev = state?.lastDbFingerprint?.db?.dev;
+      ino = state?.lastDbFingerprint?.db?.ino;
+    }
+    const selectedPath =
+      Number.isFinite(dev) && Number.isFinite(ino)
+        ? selectedByIdentity.get(`${dev}:${ino}`)
+        : Number.isFinite(ino)
+          ? selectedByInode.get(ino)
+          : null;
+    if (!selectedPath || selectedPath === statePath) continue;
+    dbStates[selectedPath] = mergeStates(
+      dbStates[selectedPath],
+      state,
+    );
+    delete dbStates[statePath];
+    migratedPaths.add(statePath);
   }
+  return migratedPaths;
+}
 
-  const defaultDb = path.join(home, ".copilot", "data.db");
-  if (process.platform === "win32") {
-    const wslHome = wsl.shouldProbeWsl(env) ? wsl.discoverWslHome(".copilot", { env }) : null;
-    const wslDb = wslHome ? path.join(wslHome, "data.db") : null;
-    const resolved = resolveInstallPaths({ nativeValue: defaultDb, wslValue: wslDb }, env);
-    if (resolved.native) addDbPath(resolved.native);
-    if (resolved.wsl) addDbPath(resolved.wsl);
-    if (paths.size === 0 && wsl.shouldProbeNative(env)) addDbPath(defaultDb);
-  } else {
-    addDbPath(defaultDb);
+function uniqueCopilotDbPaths(
+  paths,
+  env = process.env,
+  preferredPaths = [],
+) {
+  const pathKey = (dbPath) =>
+    process.platform === "win32" ? dbPath.toLowerCase() : dbPath;
+  const preferredKeys = new Set(
+    (Array.isArray(preferredPaths) ? preferredPaths : [])
+      .map((candidate) => normalizeCopilotDbPath(candidate, env))
+      .filter(Boolean)
+      .map(pathKey),
+  );
+  const candidates = (Array.isArray(paths) ? paths : [])
+    .map((candidate, index) => ({
+      index,
+      path: normalizeCopilotDbPath(candidate, env),
+    }))
+    .filter((candidate) => candidate.path)
+    .sort((a, b) => {
+      const preferredDiff =
+        Number(preferredKeys.has(pathKey(b.path))) -
+        Number(preferredKeys.has(pathKey(a.path)));
+      return preferredDiff || a.index - b.index;
+    });
+  const result = [];
+  const identities = new Set();
+  for (const candidate of candidates) {
+    const normalized = candidate.path;
+    let identity =
+      process.platform === "win32"
+        ? `path:${normalized.toLowerCase()}`
+        : `path:${normalized}`;
+    try {
+      const stat = fssync.statSync(normalized);
+      if (
+        Number.isFinite(stat.dev) &&
+        Number.isFinite(stat.ino) &&
+        stat.ino > 0
+      ) {
+        identity = `inode:${stat.dev}:${stat.ino}`;
+      }
+    } catch (_e) {}
+    if (identities.has(identity)) continue;
+    identities.add(identity);
+    result.push(normalized);
   }
+  return result;
+}
 
-  return Array.from(paths).sort();
+function resolveCopilotAppDbPaths(env = process.env) {
+  return resolveCopilotDbPaths(
+    {
+      fileName: "data.db",
+      overrideEnvKey: "TOKENTRACKER_COPILOT_APP_DB",
+    },
+    env,
+  );
 }
 
 function resolveCopilotAppDbPath(env = process.env) {
@@ -9723,6 +10971,7 @@ function sqliteSidecarFingerprint(dbPath) {
       out[suffix || "db"] = {
         size: stat.size,
         mtimeMs: stat.mtimeMs,
+        dev: stat.dev,
         ino: stat.ino,
       };
     } catch (e) {
@@ -9736,6 +10985,10 @@ function sameSqliteFingerprint(a, b) {
   return JSON.stringify(a || {}) === JSON.stringify(b || {});
 }
 
+function getCopilotSqliteFingerprint(dbPath) {
+  return sqliteSidecarFingerprint(dbPath);
+}
+
 function copilotAppBaselineTotal(value) {
   if (!value || typeof value !== "object") return 0;
   return (
@@ -9801,6 +11054,7 @@ async function parseCopilotAppDbIncremental({
   onProgress,
   env,
   sqliteOptions,
+  observeOnly = false,
 } = {}) {
   await ensureDir(path.dirname(queuePath));
   const paths = Array.isArray(dbPaths) && dbPaths.length > 0
@@ -9808,11 +11062,15 @@ async function parseCopilotAppDbIncremental({
     : dbPath
       ? [dbPath]
       : resolveCopilotAppDbPaths(env || process.env);
-  const uniquePaths = [...new Set(paths.map((p) => normalizeCopilotAppDbPath(p, env || process.env)).filter(Boolean))];
   const appState =
     cursors.copilotApp && typeof cursors.copilotApp === "object" ? cursors.copilotApp : {};
   const dbStates =
     appState.dbs && typeof appState.dbs === "object" ? { ...appState.dbs } : {};
+  const uniquePaths = uniqueCopilotDbPaths(
+    paths,
+    env || process.env,
+    Object.keys(dbStates),
+  );
   const hourlyState = normalizeHourlyState(cursors?.hourly);
   const touchedBuckets = new Set();
   const cb = typeof onProgress === "function" ? onProgress : null;
@@ -9895,6 +11153,10 @@ async function parseCopilotAppDbIncremental({
         sessionTotals[sessionId] = { ...curr, model, updatedAt: rowUpdatedAt };
         continue;
       }
+      if (observeOnly) {
+        sessionTotals[sessionId] = { ...curr, model, updatedAt: rowUpdatedAt };
+        continue;
+      }
 
       const bucketStart = toUtcHalfHourStart(rowUpdatedAt);
       if (!bucketStart) {
@@ -10859,8 +12121,16 @@ module.exports = {
   probeWslDistros,
   discoverWslHermesHome,
   resolveCopilotOtelPaths,
+  normalizeCopilotDbPath,
+  uniqueCopilotDbPaths,
+  coalesceCopilotDbStatesByIdentity,
+  resolveCopilotSessionStorePaths,
+  getCopilotSqliteFingerprint,
+  describeCopilotSessionStoreDb,
   resolveCopilotAppDbPath,
   resolveCopilotAppDbPaths,
+  readCopilotSessionStoreUsageRows,
+  normalizeCopilotSessionStoreUsage,
   readCopilotAppSessionsFromSqlite,
   parseRolloutIncremental,
   parseClaudeIncremental,
@@ -10874,7 +12144,10 @@ module.exports = {
   gooseInstallOwnsCursor,
   zedInstallOwnsCursor,
   hermesInstallOwnsCursor,
+  copilotOtelCursorHasLegacyCliUsage,
+  pruneCopilotUsageClaims,
   parseCopilotIncremental,
+  parseCopilotSessionStoreIncremental,
   parseCopilotAppDbIncremental,
   resolveKimiWireFiles,
   resolveKimiDefaultModel,