tokentracker-cli 0.67.0 → 0.68.1

package/src/commands/sync.js

@@ -5,6 +5,9 @@ const fssync = require("node:fs");
 const cp = require("node:child_process");
 const readline = require("node:readline");
 
+const { resolveInstallPaths, ensureFlatCursor } = require("../lib/install-resolver");
+const { multiInstallParse, mergeBothFileSources } = require("../lib/multi-install-parser");
+const wsl = require("../lib/wsl-probe");
 const { ensureDir, readJson, writeJson, openLock } = require("../lib/fs");
 const {
   listRolloutFiles,
@@ -30,6 +33,9 @@ const {
   parseCursorApiIncremental,
   parseKiroIncremental,
   parseHermesIncremental,
+  gooseInstallOwnsCursor,
+  zedInstallOwnsCursor,
+  hermesInstallOwnsCursor,
   parseCopilotIncremental,
   resolveKimiWireFiles,
   parseKimiIncremental,
@@ -697,7 +703,9 @@ async function cmdSync(argv) {
     }
 
     // ── Kilo Code VS Code extension (Cline-style ui_messages.json) ──
-    const kilocodeTaskFiles = sourceAllowed("kilocode") ? resolveKilocodeTaskFiles(process.env) : [];
+    const kilocodeTaskFiles = sourceAllowed("kilocode")
+      ? mergeBothFileSources({ resolveFiles: resolveKilocodeTaskFiles, env: process.env })
+      : [];
     let kilocodeResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     if (kilocodeTaskFiles.length > 0) {
       if (progress?.enabled) {
@@ -728,32 +736,40 @@ async function cmdSync(argv) {
     // ── Goose (Block) — SQLite sessions with cumulative tokens per session ──
     const gooseDbPath = resolveGooseDbPath(process.env);
     let gooseResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    if (sourceAllowed("goose") && gooseDbPath && fssync.existsSync(gooseDbPath)) {
-      if (progress?.enabled) {
-        progress.start(`Parsing Goose ${renderBar(0)} 0 sessions | buckets 0`);
-      }
-      try {
-        gooseResult = await parseGooseIncremental({
-          dbPath: gooseDbPath,
-          cursors,
-          queuePath,
-          onProgress: (p) => {
-            if (!progress?.enabled) return;
-            const pct = p.total > 0 ? p.index / p.total : 1;
-            progress.update(
-              `Parsing Goose ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(
-                p.total,
-              )} sessions | buckets ${formatNumber(p.bucketsQueued)}`,
-            );
-          },
-        });
-      } catch (err) {
-        warnProviderParseFailure("Goose", err, opts);
+    if (sourceAllowed("goose")) {
+      const gooseMode = wsl.getWslMode(process.env);
+      if (gooseMode === "both" && process.platform === "win32") {
+        const home = os.homedir();
+        const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+        const nativeDb = path.join(appData, "goose", "sessions", "sessions.db");
+        const wslDir = wsl.shouldProbeWsl(process.env) ? wsl.discoverWslHome(".local/share/goose/sessions") : null;
+        const wslDb = wslDir ? path.join(wslDir, "sessions.db") : null;
+        const goosePaths = resolveInstallPaths({ nativeValue: nativeDb, wslValue: wslDb });
+        if (goosePaths.native || goosePaths.wsl) {
+          if (progress?.enabled) progress.start(`Parsing Goose ${renderBar(0)} 0 sessions | buckets 0`);
+          try {
+            gooseResult = await multiInstallParse({
+              paths: goosePaths, parserFn: parseGooseIncremental, providerName: "goose",
+              cursors, getParams: (p) => ({ dbPath: p }), queuePath, onProgress: gooseOnProgress,
+              detectInstall: gooseInstallOwnsCursor,
+            });
+          } catch (err) { warnProviderParseFailure("Goose", err, opts); }
+        }
+      } else if (gooseDbPath && fssync.existsSync(gooseDbPath)) {
+        if (progress?.enabled) progress.start(`Parsing Goose ${renderBar(0)} 0 sessions | buckets 0`);
+        ensureFlatCursor(cursors, "goose", process.env);
+        try {
+          gooseResult = await parseGooseIncremental({
+            dbPath: gooseDbPath, cursors, queuePath, onProgress: gooseOnProgress,
+          });
+        } catch (err) { warnProviderParseFailure("Goose", err, opts); }
       }
     }
 
     // ── Droid (Factory CLI) — passive reader for ~/.factory/sessions/*.settings.json ──
-    const droidSettingsFiles = sourceAllowed("droid") ? listDroidSettingsFiles(process.env) : [];
+    const droidSettingsFiles = sourceAllowed("droid")
+      ? mergeBothFileSources({ resolveFiles: listDroidSettingsFiles, env: process.env })
+      : [];
     let droidResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     if (droidSettingsFiles.length > 0) {
       if (progress?.enabled) {
@@ -788,27 +804,33 @@ async function cmdSync(argv) {
     // ── Zed Agent (all providers; cumulative-delta over SQLite threads) ──
     const zedDbPath = resolveZedDbPath(process.env);
     let zedResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    if (sourceAllowed("zed") && zedDbPath && fssync.existsSync(zedDbPath)) {
-      if (progress?.enabled) {
-        progress.start(`Parsing Zed Agent ${renderBar(0)} 0 threads | buckets 0`);
-      }
-      try {
-        zedResult = await parseZedIncremental({
-          dbPath: zedDbPath,
-          cursors,
-          queuePath,
-          onProgress: (p) => {
-            if (!progress?.enabled) return;
-            const pct = p.total > 0 ? p.index / p.total : 1;
-            progress.update(
-              `Parsing Zed Agent ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(
-                p.total,
-              )} threads | buckets ${formatNumber(p.bucketsQueued)}`,
-            );
-          },
-        });
-      } catch (err) {
-        warnProviderParseFailure("Zed Agent", err, opts);
+    if (sourceAllowed("zed")) {
+      const zedMode = wsl.getWslMode(process.env);
+      if (zedMode === "both" && process.platform === "win32") {
+        const home = os.homedir();
+        const local = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+        const nativeDb = path.join(local, "Zed", "threads", "threads.db");
+        const wslThreadsDir = wsl.shouldProbeWsl(process.env) ? wsl.discoverWslHome(".local/share/zed/threads") : null;
+        const wslDb = wslThreadsDir ? path.join(wslThreadsDir, "threads.db") : null;
+        const zedPaths = resolveInstallPaths({ nativeValue: nativeDb, wslValue: wslDb });
+        if (zedPaths.native || zedPaths.wsl) {
+          if (progress?.enabled) progress.start(`Parsing Zed Agent ${renderBar(0)} 0 threads | buckets 0`);
+          try {
+            zedResult = await multiInstallParse({
+              paths: zedPaths, parserFn: parseZedIncremental, providerName: "zed",
+              cursors, getParams: (p) => ({ dbPath: p }), queuePath, onProgress: zedOnProgress,
+              detectInstall: zedInstallOwnsCursor,
+            });
+          } catch (err) { warnProviderParseFailure("Zed Agent", err, opts); }
+        }
+      } else if (zedDbPath && fssync.existsSync(zedDbPath)) {
+        if (progress?.enabled) progress.start(`Parsing Zed Agent ${renderBar(0)} 0 threads | buckets 0`);
+        ensureFlatCursor(cursors, "zed", process.env);
+        try {
+          zedResult = await parseZedIncremental({
+            dbPath: zedDbPath, cursors, queuePath, onProgress: zedOnProgress,
+          });
+        } catch (err) { warnProviderParseFailure("Zed Agent", err, opts); }
       }
     }
 
@@ -920,29 +942,78 @@ async function cmdSync(argv) {
 
     // ── Hermes Agent (SQLite-based) ──
     let hermesResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    const hermesPath = resolveHermesPath();
-    if (sourceAllowed("hermes") && hermesPath && fssync.existsSync(hermesPath)) {
-      if (progress?.enabled) {
-        progress.start(`Parsing Hermes ${renderBar(0)} | buckets 0`);
-      }
-      try {
-        hermesResult = await parseHermesIncremental({
-          hermesPath,
-          cursors,
-          queuePath,
-          onProgress: (p) => {
-            if (!progress?.enabled) return;
-            const pct = p.total > 0 ? p.index / p.total : 1;
-            progress.update(
-              `Parsing Hermes ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(p.total)} sessions | buckets ${formatNumber(p.bucketsQueued)}`,
-            );
-          },
-        });
-      } catch (err) {
-        warnProviderParseFailure("Hermes", err, opts);
+    if (sourceAllowed("hermes")) {
+      const override = process.env.TOKENTRACKER_HERMES_HOME;
+      const overridePath = typeof override === "string" && override.trim().length > 0 ? override.trim() : null;
+      if (overridePath) {
+        if (fssync.existsSync(overridePath)) {
+          if (progress?.enabled) {
+            progress.start(`Parsing Hermes ${renderBar(0)} | buckets 0`);
+          }
+          ensureFlatCursor(cursors, "hermes", process.env);
+          try {
+            hermesResult = await parseHermesIncremental({
+              hermesPath: overridePath,
+              cursors,
+              queuePath,
+              onProgress: hermesOnProgress,
+            });
+          } catch (err) {
+            warnProviderParseFailure("Hermes", err, opts);
+          }
+        }
+      } else {
+        const home = os.homedir();
+        const defaultPath = path.join(home, ".hermes");
+        const nativeValue = process.platform === "win32" && typeof process.env.LOCALAPPDATA === "string"
+          ? path.join(process.env.LOCALAPPDATA.trim(), "hermes") : defaultPath;
+        const hermesPaths = resolveInstallPaths({ nativeValue, wslDir: ".hermes" });
+        if (hermesPaths.native || hermesPaths.wsl) {
+          if (progress?.enabled) {
+            progress.start(`Parsing Hermes ${renderBar(0)} | buckets 0`);
+          }
+          try {
+            hermesResult = await multiInstallParse({
+              paths: hermesPaths,
+              parserFn: parseHermesIncremental,
+              providerName: "hermes",
+              cursors,
+              getParams: (path) => ({ hermesPath: path }),
+              queuePath,
+              onProgress: hermesOnProgress,
+              detectInstall: hermesInstallOwnsCursor,
+            });
+          } catch (err) {
+            warnProviderParseFailure("Hermes", err, opts);
+          }
+        }
       }
     }
 
+    function hermesOnProgress(p) {
+      if (!progress?.enabled) return;
+      const pct = p.total > 0 ? p.index / p.total : 1;
+      progress.update(
+        `Parsing Hermes ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(p.total)} sessions | buckets ${formatNumber(p.bucketsQueued)}`,
+      );
+    }
+
+    function gooseOnProgress(p) {
+      if (!progress?.enabled) return;
+      const pct = p.total > 0 ? p.index / p.total : 1;
+      progress.update(
+        `Parsing Goose ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(p.total)} sessions | buckets ${formatNumber(p.bucketsQueued)}`,
+      );
+    }
+
+    function zedOnProgress(p) {
+      if (!progress?.enabled) return;
+      const pct = p.total > 0 ? p.index / p.total : 1;
+      progress.update(
+        `Parsing Zed Agent ${renderBar(pct)} ${formatNumber(p.index)}/${formatNumber(p.total)} threads | buckets ${formatNumber(p.bucketsQueued)}`,
+      );
+    }
+
     // ── Kiro CLI (reads ~/Library/Application Support/kiro-cli/data.sqlite3
     //    AND live sessions under ~/.kiro/sessions/cli/{uuid}.json) ──
     // Runs IN PARALLEL with the Kiro IDE branch above — NOT instead of it.
@@ -1005,7 +1076,9 @@ async function cmdSync(argv) {
 
     // ── Kimi Code official (@moonshot-ai/kimi-code, ~/.kimi-code) ──
     let kimiCodeResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    const kimiCodeWireFiles = sourceAllowed("kimi-code") ? resolveKimiCodeWireFiles(process.env) : [];
+    const kimiCodeWireFiles = sourceAllowed("kimi-code")
+      ? mergeBothFileSources({ resolveFiles: resolveKimiCodeWireFiles, env: process.env })
+      : [];
     if (kimiCodeWireFiles.length > 0) {
       if (progress?.enabled) {
         progress.start(`Parsing Kimi Code (official) ${renderBar(0)} | buckets 0`);
@@ -1033,7 +1106,9 @@ async function cmdSync(argv) {
     // Tencent's CodeBuddy CLI is a Claude Code clone; no hook system, so we
     // tail the per-session JSONL conversation logs incrementally on each sync.
     let codebuddyResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    const codebuddyFiles = sourceAllowed("codebuddy") ? resolveCodebuddyProjectFiles(process.env) : [];
+    const codebuddyFiles = sourceAllowed("codebuddy")
+      ? mergeBothFileSources({ resolveFiles: resolveCodebuddyProjectFiles, env: process.env })
+      : [];
     if (codebuddyFiles.length > 0) {
       if (progress?.enabled) {
         progress.start(`Parsing CodeBuddy ${renderBar(0)} | buckets 0`);
@@ -1063,7 +1138,9 @@ async function cmdSync(argv) {
     // sub-agent logs nest one level deeper, so the resolver recurses. See the
     // parser comment in rollout.js for the cache-aware token math.
     let workbuddyResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    const workbuddyFiles = sourceAllowed("workbuddy") ? resolveWorkbuddyProjectFiles(process.env) : [];
+    const workbuddyFiles = sourceAllowed("workbuddy")
+      ? mergeBothFileSources({ resolveFiles: resolveWorkbuddyProjectFiles, env: process.env })
+      : [];
     if (workbuddyFiles.length > 0) {
       if (progress?.enabled) {
         progress.start(`Parsing WorkBuddy ${renderBar(0)} | buckets 0`);
@@ -1089,7 +1166,9 @@ async function cmdSync(argv) {
 
     // ── oh-my-pi (passive ~/.omp/agent/sessions/**/*.jsonl reader) ──
     let ompResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    const ompFiles = sourceAllowed("omp") ? resolveOmpSessionFiles(process.env) : [];
+    const ompFiles = sourceAllowed("omp")
+      ? mergeBothFileSources({ resolveFiles: resolveOmpSessionFiles, env: process.env })
+      : [];
     if (ompFiles.length > 0) {
       if (progress?.enabled) {
         progress.start(`Parsing oh-my-pi ${renderBar(0)} | buckets 0`);
@@ -1120,7 +1199,7 @@ async function cmdSync(argv) {
     let piResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     const piFiles = !sourceAllowed("pi") || piAgentDirCollidesWithOmp(process.env)
       ? []
-      : resolvePiSessionFiles(process.env);
+      : mergeBothFileSources({ resolveFiles: resolvePiSessionFiles, env: process.env });
     if (piFiles.length > 0) {
       if (progress?.enabled) {
         progress.start(`Parsing pi ${renderBar(0)} | buckets 0`);
@@ -1146,7 +1225,9 @@ async function cmdSync(argv) {
 
     // ── Craft Agents (passive ~/.craft-agent + workspaces session.jsonl reader) ──
     let craftResult = { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    const craftFiles = sourceAllowed("craft") ? resolveCraftSessionFiles(process.env) : [];
+    const craftFiles = sourceAllowed("craft")
+      ? mergeBothFileSources({ resolveFiles: resolveCraftSessionFiles, env: process.env })
+      : [];
     if (craftFiles.length > 0) {
       if (progress?.enabled) {
         progress.start(`Parsing Craft ${renderBar(0)} | buckets 0`);

package/src/lib/browser-auth.js

@@ -1,6 +1,8 @@
 const http = require("node:http");
 const crypto = require("node:crypto");
 const cp = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
 
 const { DEFAULT_BASE_URL } = require("./runtime-config");
 
@@ -158,8 +160,103 @@ function buildBrowserList() {
   return [def, ...all.filter((b) => b !== def)];
 }
 
-function openInBrowser(url) {
-  const platform = process.platform;
+function isWslSession(env = process.env) {
+  return Boolean(
+    (typeof env.WSL_DISTRO_NAME === "string" && env.WSL_DISTRO_NAME.trim()) ||
+    (typeof env.WSL_INTEROP === "string" && env.WSL_INTEROP.trim()),
+  );
+}
+
+function hasGraphicalSession(env = process.env) {
+  return Boolean(
+    (typeof env.DISPLAY === "string" && env.DISPLAY.trim()) ||
+    (typeof env.WAYLAND_DISPLAY === "string" && env.WAYLAND_DISPLAY.trim()),
+  );
+}
+
+function isCommandAvailable(command, { env = process.env, platform = process.platform } = {}) {
+  if (typeof command !== "string" || !command.trim()) return false;
+
+  const pathEntries = String(env.PATH || "")
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const hasPathSeparator = command.includes("/") || command.includes("\\");
+  const suffixes = platform === "win32"
+    ? String(env.PATHEXT || ".EXE;.CMD;.BAT;.COM")
+      .split(";")
+      .map((ext) => ext.trim())
+      .filter(Boolean)
+    : [""];
+
+  const candidates = [];
+  if (hasPathSeparator) {
+    candidates.push(command);
+  } else {
+    for (const dir of pathEntries) {
+      if (platform === "win32") {
+        candidates.push(path.join(dir, command));
+        for (const ext of suffixes) {
+          candidates.push(path.join(dir, `${command}${ext}`));
+        }
+      } else {
+        candidates.push(path.join(dir, command));
+      }
+    }
+  }
+
+  for (const candidate of candidates) {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return true;
+    } catch (_e) {}
+  }
+  return false;
+}
+
+function resolveBrowserLaunchCommand(
+  url,
+  {
+    platform = process.platform,
+    env = process.env,
+    commandExists = isCommandAvailable,
+  } = {},
+) {
+  if (platform === "win32") {
+    const escapedUrl = String(url).replace(/'/g, "''");
+    return {
+      command: "powershell.exe",
+      args: [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        `Start-Process -FilePath '${escapedUrl}'`,
+      ],
+    };
+  }
+
+  if (isWslSession(env) && commandExists("wslview", { env, platform })) {
+    return { command: "wslview", args: [url] };
+  }
+
+  if (!hasGraphicalSession(env)) return null;
+
+  const candidates = [
+    { command: "xdg-open", args: [url] },
+    { command: "gio", args: ["open", url] },
+    { command: "sensible-browser", args: [url] },
+  ];
+  for (const candidate of candidates) {
+    if (commandExists(candidate.command, { env, platform })) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function openInBrowser(url, { platform = process.platform, env = process.env, spawn = cp.spawn, commandExists = isCommandAvailable } = {}) {
 
   if (platform === "darwin") {
     // On macOS, prefer reusing a matching tab in a supported running browser.
@@ -230,34 +327,33 @@ else
   open location "${url}"
 end if
 `;
-    try {
-      const child = cp.spawn("osascript", ["-e", script], { stdio: "ignore", detached: true });
-      child.unref();
-    } catch (_e) {
-      // Fallback to plain open
+    if (commandExists("osascript", { env, platform })) {
       try {
-        const child = cp.spawn("open", [url], { stdio: "ignore", detached: true });
+        const child = spawn("osascript", ["-e", script], { stdio: "ignore", detached: true });
         child.unref();
+        return true;
+      } catch (_e) {}
+    }
+
+    if (commandExists("open", { env, platform })) {
+      try {
+        const child = spawn("open", [url], { stdio: "ignore", detached: true });
+        child.unref();
+        return true;
       } catch (_e2) {}
     }
-    return;
+    return false;
   }
 
-  let cmd = null;
-  let args = [];
-
-  if (platform === "win32") {
-    cmd = "cmd";
-    args = ["/c", "start", "", url];
-  } else {
-    cmd = "xdg-open";
-    args = [url];
-  }
+  const launch = resolveBrowserLaunchCommand(url, { platform, env, commandExists });
+  if (!launch) return false;
 
   try {
-    const child = cp.spawn(cmd, args, { stdio: "ignore", detached: true });
+    const child = spawn(launch.command, launch.args, { stdio: "ignore", detached: true });
     child.unref();
+    return true;
   } catch (_e) {}
+  return false;
 }
 
 function resolvePostAuthRedirect({ dashboardUrl, authUrl }) {
@@ -277,5 +373,9 @@ function resolvePostAuthRedirect({ dashboardUrl, authUrl }) {
 
 module.exports = {
   beginBrowserAuth,
+  hasGraphicalSession,
+  isCommandAvailable,
+  isWslSession,
   openInBrowser,
+  resolveBrowserLaunchCommand,
 };

package/src/lib/install-resolver.js

@@ -0,0 +1,62 @@
+const fssync = require("node:fs");
+const wsl = require("./wsl-probe");
+
+function resolveInstallPaths({ nativeValue, wslDir, wslValue } = {}, env = process.env, deps = {}) {
+  if (process.platform !== "win32") {
+    return { native: nativeValue ?? null, wsl: null };
+  }
+
+  const wslCandidate = wslValue !== undefined
+    ? (wsl.shouldProbeWsl(env) ? wslValue : null)
+    : (wslDir && wsl.shouldProbeWsl(env) ? wsl.discoverWslHome(wslDir, { ...deps, env }) : null);
+  const nativeCandidate = wsl.shouldProbeNative(env) && nativeValue
+    ? pathExists(nativeValue, deps.existsSync) : null;
+
+  return wsl.resolveAllWin32Paths({ nativeValue: nativeCandidate, wslValue: wslCandidate, env, platform: "win32" });
+}
+
+function pathExists(p, existsSync) {
+  try { return (existsSync || fssync.existsSync)(p) ? p : null; } catch (_e) { return null; }
+}
+
+// Migrate a flat (single-install) cursor to { native, wsl } namespaces.
+// `activeKeys` names the namespaces seeded with a copy of the flat state; the
+// others start empty so their install's full history backfills on first parse.
+// Leaving a namespace empty is only safe when its install was NEVER counted
+// under the flat cursor — the flat state holds the per-session dedup maps, and
+// an already-counted install re-parsed without them double-counts everything.
+// Callers that cannot prove which install the flat cursor tracked must seed
+// ALL namespaces (the default): bounded backfill loss, never a double count.
+function ensureNamespacedCursors(cursors, providerName, activeKeys = ["native", "wsl"]) {
+  const state = cursors[providerName] && typeof cursors[providerName] === "object" ? cursors[providerName] : {};
+
+  if (state.native !== undefined || state.wsl !== undefined) {
+    return state;
+  }
+
+  const keys = Array.isArray(activeKeys) ? activeKeys : [activeKeys];
+  cursors[providerName] = { native: {}, wsl: {} };
+  if (Object.keys(state).length > 0) {
+    for (const key of keys) {
+      cursors[providerName][key] = JSON.parse(JSON.stringify(state));
+    }
+  }
+  return cursors[providerName];
+}
+
+function ensureFlatCursor(cursors, providerName, env) {
+  const state = cursors[providerName];
+  if (!state || typeof state !== "object") return;
+  if (state.native === undefined && state.wsl === undefined) return;
+
+  const mode = wsl.getWslMode(env || process.env);
+  const preferWsl = mode === "wsl-first" || mode === "wsl-only";
+  const merged = preferWsl ? { ...state.native, ...state.wsl } : { ...state.wsl, ...state.native };
+  cursors[providerName] = merged;
+}
+
+module.exports = {
+  resolveInstallPaths,
+  ensureNamespacedCursors,
+  ensureFlatCursor,
+};

package/src/lib/multi-install-parser.js

@@ -0,0 +1,103 @@
+const wsl = require("./wsl-probe");
+const { ensureNamespacedCursors, ensureFlatCursor } = require("./install-resolver");
+
+function emptyResult() {
+  return { recordsProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+}
+
+async function multiInstallParse({ paths, parserFn, providerName, cursors, getParams, onProgress, detectInstall, ...shared }) {
+  const installKeys = Object.keys(paths).filter(k => paths[k]);
+  if (installKeys.length === 0) return emptyResult();
+  const env = shared.env || process.env;
+
+  if (installKeys.length === 1) {
+    ensureFlatCursor(cursors, providerName, env);
+    return await parserFn({
+      ...getParams(paths[installKeys[0]], installKeys[0]),
+      ...shared,
+      cursors,
+      onProgress,
+    });
+  }
+
+  const activeKeys = resolveMigrationSeedKeys({ paths, installKeys, providerName, cursors, detectInstall });
+  const ns = ensureNamespacedCursors(cursors, providerName, activeKeys);
+  let recordsProcessed = 0;
+  let eventsAggregated = 0;
+  let bucketsQueued = 0;
+
+  for (let i = 0; i < installKeys.length; i++) {
+    const key = installKeys[i];
+    cursors[providerName] = ns[key];
+    try {
+      const result = await parserFn({
+        ...getParams(paths[key], key), ...shared, cursors,
+        onProgress: wrapProgress(onProgress, key),
+      });
+      ns[key] = cursors[providerName];
+      recordsProcessed += result.recordsProcessed || 0;
+      eventsAggregated += result.eventsAggregated || 0;
+      bucketsQueued += result.bucketsQueued || 0;
+    } catch (parseErr) {
+      cursors[providerName] = ns;
+      throw parseErr;
+    }
+  }
+  cursors[providerName] = ns;
+
+  return { recordsProcessed, eventsAggregated, bucketsQueued };
+}
+
+// Decide which namespaces the one-time flat→namespaced cursor migration seeds
+// with the flat state. `detectInstall(installPath, flatState, installKey)` is
+// a provider-specific probe answering "does this install's DB contain the
+// flat cursor's session ids?". Only when EXACTLY ONE install matches do we
+// know who owned the flat cursor — the other namespace then starts empty so
+// its full history backfills. No probe, no match, multiple matches, or a
+// probe error all fall back to seeding every namespace: an install re-parsed
+// without its dedup state would double-count its entire history, and a
+// bounded backfill gap is the cheaper failure.
+function resolveMigrationSeedKeys({ paths, installKeys, providerName, cursors, detectInstall }) {
+  if (typeof detectInstall !== "function") return installKeys;
+  const state = cursors[providerName] && typeof cursors[providerName] === "object" ? cursors[providerName] : {};
+  const isFlat = state.native === undefined && state.wsl === undefined;
+  if (!isFlat || Object.keys(state).length === 0) return installKeys;
+
+  const hits = [];
+  for (const key of installKeys) {
+    let owns = false;
+    try {
+      owns = detectInstall(paths[key], state, key) === true;
+    } catch (_e) { }
+    if (owns) hits.push(key);
+  }
+  return hits.length === 1 ? hits : installKeys;
+}
+
+function wrapProgress(onProgress, installKey) {
+  if (!onProgress) return undefined;
+  return (p) => onProgress({ ...p, install: installKey });
+}
+
+function mergeBothFileSources({ resolveFiles, env }) {
+  const isBoth = process.platform === "win32" && wsl.getWslMode(env) === "both";
+  if (!isBoth) {
+    const files = resolveFiles(env);
+    return files;
+  }
+
+  const nativeEnv = { ...env, TOKENTRACKER_WSL_MODE: "native-only" };
+  const wslEnv = { ...env, TOKENTRACKER_WSL_MODE: "wsl-only" };
+
+  const nativeFiles = resolveFiles(nativeEnv);
+  const wslFiles = resolveFiles(wslEnv);
+
+  const seen = new Set();
+  const merged = [];
+  for (const f of [...nativeFiles, ...wslFiles]) {
+    if (!seen.has(f)) { seen.add(f); merged.push(f); }
+  }
+  return merged;
+}
+
+module.exports = { multiInstallParse, emptyResult, mergeBothFileSources };