usagemax 0.1.1 → 0.2.0

package/README.md

@@ -1,43 +1,88 @@
 # UsageMax CLI
 
-Connect aggregate coding-agent usage from your computer to a private UsageMax workspace.
+Connect aggregate coding-agent usage from every computer to one private UsageMax workspace.
 
 ## Quick start
 
 1. Sign in at [usagemax.com/account](https://usagemax.com/account).
 2. Choose **Link a computer** and copy the one-time command.
-3. Run it locally:
+3. Run it in each operating-system environment that contains usage history:
 
 ```bash
-bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX
+bunx usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
 ```
 
-The link code expires after ten minutes and can be used once. The CLI stores the resulting collector key in a user-only config file, then runs a one-shot sync.
+The link code expires after ten minutes and can be used once. Create a new code
+for each Mac, Windows PC, Linux computer, and WSL distribution. All linked
+collectors roll up into the same profile. Windows and WSL have separate home
+directories, so run UsageMax once in Windows and once inside WSL when both have
+agent history.
+
+The CLI stores the resulting collector key in a user-only config file, then runs
+a one-shot full-history sync. Running it again, changing the display name, or
+relinking an installation does not create a second device: the private random
+installation identity remains stable.
 
 ## Commands
 
 ```bash
-bunx usagemax              # sync changed usage
-bunx usagemax sync         # same as above
-bunx usagemax sync --full  # inspect all available local history
-bunx usagemax link UMX-… --no-sync # link without uploading yet
-bunx usagemax status       # show link and last-sync state
-bunx usagemax doctor       # metadata-only source check; does not parse logs
-bunx usagemax doctor --deep # opt into a full local parser check
-bunx usagemax report       # open ccusage's local daily report
+bunx usagemax                       # sync changed usage
+bunx usagemax sync                  # same as above
+bunx usagemax sync --full           # reconcile all retained local history
+bunx usagemax link UMX-… --no-sync  # link without uploading yet
+bunx usagemax status                # show link and last-sync state
+bunx usagemax doctor                # metadata-only source check
+bunx usagemax doctor --deep         # parse and verify all retained history
+bunx usagemax report                # open ccusage's local daily report
 bunx usagemax report session --breakdown
-bunx usagemax unlink       # remove the local collector key
+bunx usagemax unlink                # remove the local collector key
 ```
 
-UsageMax uses [ccusage](https://github.com/ccusage/ccusage) for local source detection, responsive reports, cached pricing, model breakdowns, date handling, and support for popular coding-agent CLIs. `report` passes its remaining arguments to ccusage.
+UsageMax pins [ccusage v20.0.20](https://github.com/ccusage/ccusage/releases/tag/v20.0.20)
+and supports all 16 adapters shipped in that release: Amp, Claude Code, Codebuff,
+Codex, GitHub Copilot CLI, Factory Droid, Gemini CLI, Goose, Grok Build, Hermes,
+Kilo Code, Kimi CLI, OpenClaw, OpenCode, Pi, and Qwen Code. Named Pi-format
+stores configured through ccusage are also discovered.
+
+The source inventory follows ccusage's environment overrides, including
+`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `OPENCODE_DATA_DIR`, `AMP_DATA_DIR`,
+`DROID_SESSIONS_DIR`, `CODEBUFF_DATA_DIR`, `HERMES_HOME`, `PI_AGENT_DIR`,
+`GOOSE_PATH_ROOT`, `OPENCLAW_DIR`, `KILO_DATA_DIR`, `KIMI_DATA_DIR`,
+`QWEN_DATA_DIR`, `COPILOT_OTEL_FILE_EXPORTER_PATH`, `GEMINI_DATA_DIR`, and
+`GROK_HOME`. It also follows XDG Claude configuration and Windows Goose storage.
 
-## Privacy and load
+Local files are only one coverage layer. Cursor, Windsurf, Aider, Continue,
+Cline, Roo Code, direct provider API traffic, hosted agents, and enterprise
+billing systems do not all expose a stable local token ledger. Capture those
+through UsageMax's native or OTLP endpoint, or through a future provider billing
+connector. UsageMax never invents usage that the source did not retain.
 
-- The sync payload contains aggregate token counts, model/provider names, costs, source names, and dates.
-- It does not upload prompts, completions, source code, file contents, project paths, or provider credentials.
+## Privacy, correctness, and load
+
+- The sync payload contains aggregate token counts, model/provider names, costs,
+  source names, and dates.
+- It does not upload prompts, completions, source code, file contents, project
+  paths, or provider credentials.
 - Sync is one-shot. There is no resident scanner or high-frequency polling loop.
-- After the first import, normal syncs inspect only the current and previous local day; use `sync --full` to reconcile older history.
-- The collector key is written with user-only permissions where the operating system supports them.
-- A separate private random installation ID survives collector rotation, relinking, and display-name changes. It is not a hardware fingerprint; the server stores only its SHA-256 hash. Concurrent or repeated syncs remain idempotent.
+- A metadata inventory exits without parsing logs or using the network when
+  nothing changed.
+- Normal changed syncs parse today or today plus yesterday. A bounded weekly
+  full reconciliation catches restored files, parser changes, and older logs.
+- Full history means all retained local history from 2024 onward. Deleted or
+  never-persisted usage requires a provider export; no local tool can reconstruct it.
+- Source totals that cannot be assigned to a model are retained as
+  `unattributed` rather than silently discarded.
+- The collector key is written with user-only permissions where the operating
+  system supports them.
+- A private random installation ID survives collector rotation, relinking, and
+  display-name changes. It is not a hardware fingerprint; the server stores only
+  its SHA-256 hash. Concurrent and repeated syncs are idempotent.
+- Do not point two different installations at the same copied or network-mounted
+  log tree. Cross-installation copied-history deduplication is inherently
+  ambiguous and intentionally not guessed.
+
+Use `USAGEMAX_CONFIG_DIR` to select another config directory. Development and
+self-hosted installations may set `USAGEMAX_LINK_ENDPOINT` before linking.
 
-Use `USAGEMAX_CONFIG_DIR` to select another config directory. Development/self-hosted installations may set `USAGEMAX_LINK_ENDPOINT` before linking.
+See the [collector coverage audit](../../docs/collector-coverage-audit.md) for
+the full support matrix and known boundaries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "license": "MIT",
   "author": "UsageMax",
@@ -21,6 +21,7 @@
     "src/cli.js",
     "src/core.js",
     "src/installation.js",
+    "src/sources.js",
     "README.md",
     "LICENSE"
   ],

package/src/cli.js

@@ -1,25 +1,25 @@
 #!/usr/bin/env node
 
 import { execFile, spawn } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
-import { chmod, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { homedir, platform } from "node:os";
-import { delimiter, dirname, extname, join } from "node:path";
+import { dirname, join } from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
 
 import { batchId, buildDeltaPlan, normalizeLinkCode, sourceSummary, validHttpsUrl } from "./core.js";
 import { stableInstallationId } from "./installation.js";
+import { CCUSAGE_VERSION, ccusageEnvironment, SOURCE_INVENTORY_VERSION, sourceInventory, SUPPORTED_SOURCES } from "./sources.js";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.1.1";
+const VERSION = "0.2.0";
 const DEFAULT_LINK_ENDPOINT = "https://terrific-bobcat-522.convex.site/v1/devices/link";
 const CONFIG_FILE = "config.json";
 const MAX_REPORT_BYTES = 100 * 1024 * 1024;
-const MAX_FINGERPRINT_FILES = 50_000;
-const USAGE_EXTENSIONS = new Set([".db", ".json", ".jsonl", ".sqlite", ".sqlite3"]);
+const FULL_RECONCILE_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
 
 function configDirectory() {
   if (process.env.USAGEMAX_CONFIG_DIR) return process.env.USAGEMAX_CONFIG_DIR;
@@ -67,6 +67,7 @@ function option(args, name) {
 function deviceLabel() {
   if (platform() === "darwin") return "Mac";
   if (platform() === "win32") return "Windows PC";
+  if (platform() === "linux" && process.env.WSL_DISTRO_NAME) return `WSL · ${process.env.WSL_DISTRO_NAME}`;
   if (platform() === "linux") return "Linux computer";
   return "Computer";
 }
@@ -80,7 +81,7 @@ function help() {
   process.stdout.write("           [--no-sync] [--name <name>]\n");
   process.stdout.write("  usagemax sync [--full] [--json] Sync usage once, then exit\n");
   process.stdout.write("  usagemax status                  Show local link status\n");
-  process.stdout.write("  usagemax doctor [--deep]         Check sources without parsing logs\n");
+  process.stdout.write("  usagemax doctor [--deep]         Check source coverage; --deep parses full history\n");
   process.stdout.write("  usagemax report [...args]        Run a local ccusage report\n");
   process.stdout.write("  usagemax unlink                  Remove the local collector key\n");
 }
@@ -89,91 +90,21 @@ function ccusageCliPath() {
   return join(dirname(require.resolve("ccusage/package.json")), "src", "cli.js");
 }
 
-function configuredPaths(variable, fallbacks) {
-  const configured = process.env[variable];
-  return configured
-    ? configured.split(",").flatMap((group) => group.split(delimiter)).map((value) => value.trim()).filter(Boolean)
-    : fallbacks;
-}
-
-function usageRoots() {
-  const home = homedir();
-  return [
-    ["claude", configuredPaths("CLAUDE_CONFIG_DIR", [join(home, ".config", "claude", "projects"), join(home, ".claude", "projects")])],
-    ["codex", configuredPaths("CODEX_HOME", [join(home, ".codex", "sessions"), join(home, ".codex", "archived_sessions")])],
-    ["opencode", configuredPaths("OPENCODE_DATA_DIR", [join(home, ".local", "share", "opencode")])],
-    ["hermes", configuredPaths("HERMES_HOME", [join(home, ".hermes", "sessions")])],
-    ["pi", configuredPaths("PI_AGENT_DIR", [join(home, ".pi", "agent", "sessions")])],
-    ["copilot", configuredPaths("COPILOT_HOME", [join(home, ".copilot")])],
-    ["gemini", configuredPaths("GEMINI_DATA_DIR", [join(home, ".gemini", "tmp")])],
-  ].flatMap(([source, paths]) => paths.map((path) => ({ source, path })));
-}
-
-async function sourceInventory() {
-  const hash = createHash("sha256");
-  const sources = new Set();
-  const roots = usageRoots();
-  let files = 0;
-  let truncated = false;
-  for (const root of roots) {
-    try {
-      const rootStat = await stat(root.path);
-      if (!rootStat.isDirectory() && !rootStat.isFile()) continue;
-      sources.add(root.source);
-    } catch {
-      continue;
-    }
-    const stack = [root.path];
-    while (stack.length && files < MAX_FINGERPRINT_FILES) {
-      const current = stack.pop();
-      let entries;
-      try {
-        entries = await readdir(current, { withFileTypes: true });
-      } catch {
-        try {
-          const metadata = await stat(current);
-          if (metadata.isFile() && USAGE_EXTENSIONS.has(extname(current).toLowerCase())) {
-            hash.update(`${root.source}\u0000${current}\u0000${metadata.size}\u0000${metadata.mtimeMs}\n`);
-            files += 1;
-          }
-        } catch {}
-        continue;
-      }
-      for (const entry of entries) {
-        const path = join(current, entry.name);
-        if (entry.isDirectory()) {
-          if (!["node_modules", ".git", "cache", "tmp"].includes(entry.name)) stack.push(path);
-          continue;
-        }
-        if (!entry.isFile() || !USAGE_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue;
-        try {
-          const metadata = await stat(path);
-          hash.update(`${root.source}\u0000${path}\u0000${metadata.size}\u0000${metadata.mtimeMs}\n`);
-          files += 1;
-        } catch {}
-        if (files >= MAX_FINGERPRINT_FILES) {
-          truncated = true;
-          break;
-        }
-      }
-    }
-  }
-  return { fingerprint: hash.digest("hex"), sources: [...sources].sort(), files, truncated };
-}
-
 async function ccusageJson(config, { full = false } = {}) {
-  const args = [ccusageCliPath(), "daily", "--json", "--offline", "--by-agent", "--order", "asc"];
+  const args = [ccusageCliPath(), "daily", "--json", "--offline", "--mode", "calculate", "--timezone", "UTC", "--by-agent", "--order", "asc"];
   // Reconcile yesterday once after the UTC date changes. All other incremental
   // scans parse only today; a metadata fingerprint avoids invoking ccusage when
   // no supported local source changed at all.
-  if (!full && config?.lastSyncAt) {
+  if (full) {
+    args.push("--since", "2024-01-01", "--until", new Date().toISOString().slice(0, 10));
+  } else if (config?.lastSyncAt) {
     const today = new Date().toISOString().slice(0, 10);
     args.push("--last", config.lastReconciledDay === today ? "1" : "2");
   }
   const { stdout } = await executeFile(process.execPath, args, {
     encoding: "utf8",
     maxBuffer: MAX_REPORT_BYTES,
-    env: { ...process.env, NO_COLOR: "1" },
+    env: { ...await ccusageEnvironment(), NO_COLOR: "1" },
   });
   return JSON.parse(stdout);
 }
@@ -226,17 +157,27 @@ async function sync(args, suppliedConfig) {
   const config = suppliedConfig || await readConfig();
   if (!config) throw new Error("This computer is not linked. Open https://usagemax.com/account and create a link code.");
   config.deviceId = await stableInstallationId(configDirectory(), config.deviceId);
-  const full = args.includes("--full");
+  const requestedFull = args.includes("--full");
   const inventory = await sourceInventory();
   const today = new Date().toISOString().slice(0, 10);
-  if (!full && config.lastReconciledDay === today && config.sourceFingerprint === inventory.fingerprint) {
-    const result = { accepted: 0, changedRows: 0, sources: inventory.sources, regressions: 0, scanned: false };
+  const knownSources = Array.isArray(config.knownSources) ? config.knownSources : [];
+  const foundNewSource = inventory.sources.some((source) => !knownSources.includes(source));
+  const lastFullSync = Date.parse(config.lastFullSyncAt || "");
+  const fullDue = config.sourceInventoryVersion !== SOURCE_INVENTORY_VERSION
+    || !Number.isFinite(lastFullSync)
+    || Date.now() - lastFullSync >= FULL_RECONCILE_INTERVAL_MS
+    || foundNewSource;
+  const full = requestedFull || fullDue;
+  if (!full && inventory.complete && config.lastSyncComplete && config.lastReconciledDay === today && config.sourceFingerprint === inventory.fingerprint) {
+    const result = { accepted: 0, changedRows: 0, sources: inventory.sources, regressions: 0, scanned: false, full: false };
     if (args.includes("--json")) process.stdout.write(`${JSON.stringify(result)}\n`);
     else process.stdout.write("Already up to date. Local usage files have not changed; no logs were parsed or uploaded.\n");
     return;
   }
   const report = await ccusageJson(config, { full });
-  const { plan, regressions } = buildDeltaPlan(report, config.snapshots, config.deviceId, "ccusage@20.0.20");
+  const { plan, regressions } = buildDeltaPlan(report, config.snapshots, config.deviceId, `ccusage@${CCUSAGE_VERSION}`);
+  config.lastSyncComplete = false;
+  await writeConfig(config);
   let accepted = 0;
   for (let offset = 0; offset < plan.length; offset += 100) {
     const batch = plan.slice(offset, offset + 100);
@@ -257,20 +198,21 @@ async function sync(args, suppliedConfig) {
     accepted += Number(body.accepted || 0);
     for (const item of batch) config.snapshots[item.snapshotKey] = item.snapshot;
     config.lastSyncAt = new Date().toISOString();
-    config.lastReconciledDay = today;
-    config.sourceFingerprint = inventory.fingerprint;
-    await writeConfig(config);
-  }
-  if (!plan.length) {
-    config.lastSyncAt = new Date().toISOString();
-    config.lastReconciledDay = today;
-    config.sourceFingerprint = inventory.fingerprint;
     await writeConfig(config);
   }
-  const result = { accepted, changedRows: plan.length, sources: sourceSummary(report), regressions: regressions.length, scanned: true };
+  config.lastSyncAt = new Date().toISOString();
+  config.lastReconciledDay = today;
+  config.lastSyncComplete = true;
+  config.sourceInventoryVersion = SOURCE_INVENTORY_VERSION;
+  config.knownSources = [...new Set([...knownSources, ...inventory.sources, ...sourceSummary(report)])].sort();
+  if (inventory.complete) config.sourceFingerprint = inventory.fingerprint;
+  else delete config.sourceFingerprint;
+  if (full) config.lastFullSyncAt = config.lastSyncAt;
+  await writeConfig(config);
+  const result = { accepted, changedRows: plan.length, sources: sourceSummary(report), regressions: regressions.length, scanned: true, full };
   if (args.includes("--json")) process.stdout.write(`${JSON.stringify(result)}\n`);
   else {
-    process.stdout.write(plan.length ? `Synced ${accepted} changed usage rows from ${result.sources.join(", ") || "local agents"}.\n` : "Already up to date. No usage rows were uploaded.\n");
+    process.stdout.write(plan.length ? `Synced ${accepted} changed usage rows from ${result.sources.join(", ") || "local agents"}${full ? " (full history)" : ""}.\n` : `Already up to date. No usage rows were uploaded${full ? " after a full-history reconciliation" : ""}.\n`);
     if (regressions.length) process.stdout.write(`${regressions.length} local row(s) moved backward; UsageMax kept the prior high-water mark to prevent double counting.\n`);
   }
 }
@@ -288,6 +230,7 @@ async function status() {
   }
   process.stdout.write(`Linked: ${config.deviceName || deviceLabel()}${config.profileHandle ? ` → @${config.profileHandle}` : ""}\n`);
   process.stdout.write(`Last sync: ${config.lastSyncAt || "never"}\n`);
+  process.stdout.write(`Last full reconciliation: ${config.lastFullSyncAt || "never"}\n`);
   process.stdout.write(`Profile: ${config.profileUrl || "https://usagemax.com/account"}\n`);
 }
 
@@ -296,8 +239,13 @@ async function doctor(args = []) {
   const inventory = await sourceInventory();
   process.stdout.write(`Collector: ${config ? "linked" : "not linked"}\n`);
   process.stdout.write(`Detected sources: ${inventory.sources.join(", ") || "none"} (${inventory.files}${inventory.truncated ? "+" : ""} data files)\n`);
+  process.stdout.write(`Supported sources: ${SUPPORTED_SOURCES.join(", ")} (+ named pi-format stores)\n`);
+  if (platform() === "linux" && process.env.WSL_DISTRO_NAME) {
+    process.stdout.write(`Environment: WSL ${process.env.WSL_DISTRO_NAME}; its Linux home is collected separately from Windows\n`);
+  }
+  if (!inventory.complete) process.stdout.write(`Inventory: incomplete (${inventory.errors} read error(s)${inventory.truncated ? ", file limit reached" : ""}); no-change shortcut disabled\n`);
   if (args.includes("--deep")) {
-    const report = await ccusageJson(config, { full: false });
+    const report = await ccusageJson(config, { full: true });
     process.stdout.write(`Parsed sources: ${sourceSummary(report).join(", ") || "none"}\n`);
   }
   process.stdout.write(`Mode: one-shot, metadata no-op check, ${args.includes("--deep") ? "deep local parse" : "no log parsing"}\n`);
@@ -305,7 +253,10 @@ async function doctor(args = []) {
 
 async function report(args) {
   const forwarded = args.length ? args : ["daily"];
-  const child = spawn(process.execPath, [ccusageCliPath(), ...forwarded], { stdio: "inherit", env: process.env });
+  const child = spawn(process.execPath, [ccusageCliPath(), ...forwarded], {
+    stdio: "inherit",
+    env: await ccusageEnvironment(),
+  });
   const code = await new Promise((resolve, reject) => {
     child.once("error", reject);
     child.once("exit", (status) => resolve(status ?? 1));

package/src/core.js

@@ -22,12 +22,24 @@ function text(value, fallback, maximum = 120) {
 }
 
 function providerFor(model, source) {
-  const name = model.toLowerCase();
+  const displayName = model.toLowerCase().replace(/^\[[^\]]+\]\s*/, "");
+  const name = displayName.replace(/^api[-_:]/, "");
+  if (name.startsWith("openrouter/")) return "openrouter";
+  if (name.startsWith("azure/") || name.startsWith("azure-openai/")) return "azure-openai";
+  if (name.startsWith("bedrock/") || name.startsWith("aws/")) return "aws-bedrock";
+  if (name.startsWith("vertex/") || name.startsWith("vertex_ai/") || name.startsWith("google/")) return "google";
   if (name.includes("claude")) return "anthropic";
   if (/^(?:gpt|o[1345]|codex)/.test(name) || name.includes("openai")) return "openai";
   if (name.includes("gemini")) return "google";
   if (name.includes("grok")) return "xai";
   if (name.includes("deepseek")) return "deepseek";
+  if (name.includes("kimi") || name.includes("moonshot")) return "moonshot";
+  if (name.includes("qwen")) return "alibaba";
+  if (name.includes("glm") || name.includes("zai") || name.includes("z.ai")) return "zai";
+  if (name.includes("mistral") || name.includes("codestral")) return "mistral";
+  if (name.includes("llama") || name.includes("meta/")) return "meta";
+  if (name.includes("minimax")) return "minimax";
+  if (name.includes("command-r") || name.includes("cohere")) return "cohere";
   return source;
 }
 
@@ -74,6 +86,8 @@ function currentRows(report) {
             cacheReadTokens: rawAgent.cacheReadTokens,
             cost: rawAgent.totalCost,
           }];
+      let allocatedTokens = 0;
+      let allocatedCostMicros = 0;
       for (const rawBreakdown of breakdowns) {
         if (!rawBreakdown || typeof rawBreakdown !== "object") continue;
         const model = text(rawBreakdown.modelName, "unknown", 120);
@@ -82,6 +96,10 @@ function currentRows(report) {
         const cacheWriteTokens = number(rawBreakdown.cacheCreationTokens);
         const cacheReadTokens = number(rawBreakdown.cacheReadTokens);
         const costMicros = moneyMicros(rawBreakdown.cost);
+        const classifiedTokens = inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens;
+        const totalTokens = Math.max(classifiedTokens, number(rawBreakdown.totalTokens));
+        allocatedTokens += totalTokens;
+        allocatedCostMicros += costMicros;
         rows.push({
           key: `${source}\u001f${period}\u001f${model}`,
           source,
@@ -92,11 +110,29 @@ function currentRows(report) {
             outputTokens,
             cacheReadTokens,
             cacheWriteTokens,
-            totalTokens: inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens,
+            totalTokens,
             costMicros,
           },
         });
       }
+      const residualTokens = Math.max(0, number(rawAgent.totalTokens) - allocatedTokens);
+      const residualCostMicros = Math.max(0, moneyMicros(rawAgent.totalCost) - allocatedCostMicros);
+      if (residualTokens > 0 || residualCostMicros > 0) {
+        rows.push({
+          key: `${source}\u001f${period}\u001funattributed`,
+          source,
+          period,
+          model: "unattributed",
+          current: {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+            totalTokens: residualTokens,
+            costMicros: residualCostMicros,
+          },
+        });
+      }
     }
   }
   return rows;

package/src/sources.js

@@ -0,0 +1,331 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export const CCUSAGE_VERSION = "20.0.20";
+export const SOURCE_INVENTORY_VERSION = 2;
+export const SUPPORTED_SOURCES = [
+  "amp",
+  "claude",
+  "codebuff",
+  "codex",
+  "copilot",
+  "droid",
+  "gemini",
+  "goose",
+  "grok",
+  "hermes",
+  "kilo",
+  "kimi",
+  "openclaw",
+  "opencode",
+  "pi",
+  "qwen",
+];
+
+const MAX_FINGERPRINT_FILES = 50_000;
+
+function has(env, name) {
+  return Object.prototype.hasOwnProperty.call(env, name);
+}
+
+function commaList(value) {
+  return String(value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+function envList(env, name, fallback, { blankUsesFallback = false } = {}) {
+  if (!has(env, name) || (blankUsesFallback && !String(env[name] ?? "").trim())) return fallback;
+  return commaList(env[name]);
+}
+
+function expandTilde(value, home, pathApi) {
+  if (value === "~") return home;
+  if (value.startsWith("~/") || value.startsWith("~\\")) return pathApi.join(home, value.slice(2));
+  return value;
+}
+
+export function ccusageHome(env = process.env, fallback = homedir()) {
+  for (const value of [env.HOME, env.USERPROFILE]) {
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  const windowsHome = `${env.HOMEDRIVE ?? ""}${env.HOMEPATH ?? ""}`;
+  return windowsHome.trim() || fallback;
+}
+
+function tree(source, root, matcher) {
+  return { source, path: root, kind: "tree", matcher };
+}
+
+function file(source, filePath) {
+  return { source, path: filePath, kind: "file", matcher: "any" };
+}
+
+function db(source, filePath) {
+  return [file(source, filePath), file(source, `${filePath}-wal`), file(source, `${filePath}-shm`)];
+}
+
+export function sourceDefinitions({ env = process.env, home = ccusageHome(env), cwd = process.cwd(), pathApi = path } = {}) {
+  const join = (...parts) => pathApi.join(...parts);
+  const definitions = [];
+
+  const claudeRoots = has(env, "CLAUDE_CONFIG_DIR")
+    ? commaList(env.CLAUDE_CONFIG_DIR).map((item) => expandTilde(item, home, pathApi))
+    : [join(has(env, "XDG_CONFIG_HOME") ? String(env.XDG_CONFIG_HOME) : join(home, ".config"), "claude"), join(home, ".claude")];
+  for (const root of claudeRoots) {
+    const projects = pathApi.basename(root) === "projects" ? root : join(root, "projects");
+    definitions.push(tree("claude", projects, "jsonl"));
+  }
+
+  for (const root of envList(env, "CODEX_HOME", [join(home, ".codex")])) {
+    definitions.push({ source: "codex", path: root, kind: "codex-home", matcher: "jsonl" });
+  }
+  for (const root of envList(env, "OPENCODE_DATA_DIR", [join(home, ".local", "share", "opencode")])) {
+    definitions.push(tree("opencode", root, "opencode"));
+  }
+  for (const root of envList(env, "AMP_DATA_DIR", [join(home, ".local", "share", "amp")])) {
+    definitions.push(tree("amp", join(root, "threads"), "json"));
+  }
+  for (const root of envList(env, "DROID_SESSIONS_DIR", [join(home, ".factory", "sessions")])) {
+    definitions.push(tree("droid", root, "droid"));
+  }
+
+  const codebuffRoots = has(env, "CODEBUFF_DATA_DIR")
+    ? commaList(env.CODEBUFF_DATA_DIR)
+    : ["manicode", "manicode-dev", "manicode-staging"].map((channel) => join(home, ".config", channel));
+  for (const root of codebuffRoots) {
+    definitions.push(tree("codebuff", pathApi.basename(root) === "projects" ? root : join(root, "projects"), "codebuff"));
+  }
+
+  for (const root of envList(env, "HERMES_HOME", [join(home, ".hermes")])) {
+    definitions.push(...db("hermes", join(root, "state.db")));
+  }
+  for (const root of envList(env, "PI_AGENT_DIR", [join(home, ".pi", "agent", "sessions")], { blankUsesFallback: true })) {
+    definitions.push(tree("pi", root, "jsonl"));
+  }
+
+  const gooseRoot = String(env.GOOSE_PATH_ROOT ?? "").trim();
+  const gooseDatabases = gooseRoot
+    ? [join(gooseRoot, "data", "sessions", "sessions.db")]
+    : [
+        join(home, ".local", "share", "goose", "sessions", "sessions.db"),
+        join(home, "Library", "Application Support", "goose", "sessions", "sessions.db"),
+        join(home, ".local", "share", "Block", "goose", "sessions", "sessions.db"),
+      ];
+  if (!gooseRoot && String(env.APPDATA ?? "").trim()) {
+    gooseDatabases.push(join(String(env.APPDATA).trim(), "Block", "goose", "data", "sessions", "sessions.db"));
+  }
+  for (const database of gooseDatabases) definitions.push(...db("goose", database));
+
+  const openClawRoots = envList(env, "OPENCLAW_DIR", [
+    join(home, ".openclaw"),
+    join(home, ".clawdbot"),
+    join(home, ".moltbot"),
+    join(home, ".moldbot"),
+  ], { blankUsesFallback: true });
+  for (const root of openClawRoots) definitions.push(tree("openclaw", root, "openclaw"));
+
+  for (const root of envList(env, "KILO_DATA_DIR", [join(home, ".local", "share", "kilo")])) {
+    definitions.push(...db("kilo", join(root, "kilo.db")));
+  }
+  for (const root of envList(env, "KIMI_DATA_DIR", [join(home, ".kimi"), join(home, ".kimi-code")])) {
+    definitions.push(tree("kimi", join(root, "sessions"), "jsonl"), file("kimi", join(root, "config.json")));
+  }
+  for (const root of envList(env, "QWEN_DATA_DIR", [join(home, ".qwen")])) {
+    definitions.push(tree("qwen", join(root, "projects"), "jsonl"));
+  }
+
+  definitions.push(tree("copilot", join(home, ".copilot", "otel"), "jsonl"));
+  if (String(env.COPILOT_OTEL_FILE_EXPORTER_PATH ?? "").trim()) {
+    definitions.push(file("copilot", String(env.COPILOT_OTEL_FILE_EXPORTER_PATH).trim()));
+  }
+  for (const root of envList(env, "GEMINI_DATA_DIR", [join(home, ".gemini", "tmp")])) {
+    definitions.push(tree("gemini", root, "gemini"));
+  }
+  const grokRoot = String(env.GROK_HOME ?? "").trim() || join(home, ".grok");
+  definitions.push(tree("grok", join(grokRoot, "sessions"), "grok"));
+
+  const configRoots = has(env, "CLAUDE_CONFIG_DIR")
+    ? commaList(env.CLAUDE_CONFIG_DIR)
+    : [join(home, ".config", "claude"), join(home, ".claude")];
+  const configPaths = [join(cwd, ".ccusage", "ccusage.json"), ...configRoots.map((root) => join(root, "ccusage.json"))];
+  for (const configPath of configPaths) definitions.push(file("ccusage-config", configPath));
+
+  return definitions;
+}
+
+export async function ccusageEnvironment({ env = process.env, platform = process.platform, pathApi = path } = {}) {
+  const effective = { ...env };
+  if (platform !== "win32" || String(effective.GOOSE_PATH_ROOT ?? "").trim() || !String(effective.APPDATA ?? "").trim()) {
+    return effective;
+  }
+  const gooseRoot = pathApi.join(String(effective.APPDATA).trim(), "Block", "goose");
+  try {
+    if ((await stat(pathApi.join(gooseRoot, "data", "sessions", "sessions.db"))).isFile()) effective.GOOSE_PATH_ROOT = gooseRoot;
+  } catch {}
+  return effective;
+}
+
+function accepts(matcher, filePath, pathApi) {
+  const name = pathApi.basename(filePath);
+  if (matcher === "any") return true;
+  if (matcher === "jsonl") return name.endsWith(".jsonl");
+  if (matcher === "json") return name.endsWith(".json");
+  if (matcher === "gemini") return name.endsWith(".json") || name.endsWith(".jsonl");
+  if (matcher === "codebuff") return name === "chat-messages.json";
+  if (matcher === "droid") return name.endsWith(".settings.json") || name.endsWith(".jsonl");
+  if (matcher === "openclaw") return name.includes(".jsonl");
+  if (matcher === "grok") return name === "updates.jsonl" || name === "summary.json";
+  if (matcher === "opencode") return name.endsWith(".db") || name.includes(".db-") || name.endsWith(".json");
+  return false;
+}
+
+async function existsDirectory(value) {
+  try {
+    return (await stat(value)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function expandCodexRoots(definitions, pathApi) {
+  const expanded = [];
+  for (const definition of definitions) {
+    if (definition.kind !== "codex-home") {
+      expanded.push(definition);
+      continue;
+    }
+    const sessions = pathApi.join(definition.path, "sessions");
+    const archived = pathApi.join(definition.path, "archived_sessions");
+    const [hasSessions, hasArchived] = await Promise.all([existsDirectory(sessions), existsDirectory(archived)]);
+    if (hasSessions) expanded.push(tree("codex", sessions, "jsonl"));
+    if (hasArchived) expanded.push(tree("codex", archived, "jsonl"));
+    if (!hasSessions && !hasArchived) expanded.push(tree("codex", definition.path, "jsonl"));
+  }
+  return expanded;
+}
+
+function configCandidates(definitions) {
+  return definitions.filter((item) => item.source === "ccusage-config").map((item) => item.path);
+}
+
+async function namedPiStores(definitions, home, pathApi) {
+  for (const configPath of configCandidates(definitions)) {
+    try {
+      const parsed = JSON.parse(await readFile(configPath, "utf8"));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      const stores = Array.isArray(parsed.pi?.stores) ? parsed.pi.stores : [];
+      return stores.flatMap((store) => {
+        if (!store || typeof store.name !== "string" || typeof store.path !== "string" || !store.path.trim()) return [];
+        return [tree(store.name.trim().toLowerCase(), expandTilde(store.path.trim(), home, pathApi), "jsonl")];
+      });
+    } catch {}
+  }
+  return [];
+}
+
+function fileIdentity(source, filePath, metadata) {
+  return `${source}\u0000${filePath}\u0000${metadata.size}\u0000${metadata.mtimeMs}\u0000${metadata.ctimeMs}\n`;
+}
+
+export async function sourceInventory({ env = process.env, cwd = process.cwd(), home = ccusageHome(env), pathApi = path, maxFiles = MAX_FINGERPRINT_FILES } = {}) {
+  const hash = createHash("sha256");
+  hash.update(`inventory:${SOURCE_INVENTORY_VERSION}\nccusage:${CCUSAGE_VERSION}\naliases:${env.CCUSAGE_MODEL_ALIASES ?? ""}\n`);
+  let definitions = sourceDefinitions({ env, cwd, home, pathApi });
+  definitions.push(...await namedPiStores(definitions, home, pathApi));
+  definitions = await expandCodexRoots(definitions, pathApi);
+  definitions.sort((left, right) => `${left.source}\u0000${left.path}`.localeCompare(`${right.source}\u0000${right.path}`));
+
+  const sources = new Set();
+  const seenRoots = new Set();
+  const seenFiles = new Set();
+  let files = 0;
+  let truncated = false;
+  let complete = true;
+  let errors = 0;
+
+  async function addFile(definition, filePath) {
+    const identity = `${definition.source}\u0000${filePath}`;
+    if (seenFiles.has(identity)) return;
+    if (files >= maxFiles) {
+      truncated = true;
+      complete = false;
+      return;
+    }
+    try {
+      const metadata = await stat(filePath);
+      if (!metadata.isFile()) return;
+      seenFiles.add(identity);
+      hash.update(fileIdentity(definition.source, filePath, metadata));
+      if (definition.source === "ccusage-config") {
+        try {
+          hash.update(await readFile(filePath));
+        } catch {
+          complete = false;
+          errors += 1;
+        }
+      } else {
+        sources.add(definition.source);
+      }
+      files += 1;
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        complete = false;
+        errors += 1;
+      }
+    }
+  }
+
+  for (const definition of definitions) {
+    const rootIdentity = `${definition.source}\u0000${definition.kind}\u0000${definition.path}`;
+    if (seenRoots.has(rootIdentity)) continue;
+    seenRoots.add(rootIdentity);
+    hash.update(`root:${rootIdentity}\n`);
+    if (definition.kind === "file") {
+      await addFile(definition, definition.path);
+      continue;
+    }
+    let rootMetadata;
+    try {
+      rootMetadata = await stat(definition.path);
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        complete = false;
+        errors += 1;
+      }
+      continue;
+    }
+    if (!rootMetadata.isDirectory()) continue;
+    const stack = [definition.path];
+    while (stack.length && !truncated) {
+      const current = stack.pop();
+      let entries;
+      try {
+        entries = await readdir(current, { withFileTypes: true });
+      } catch {
+        complete = false;
+        errors += 1;
+        continue;
+      }
+      entries.sort((left, right) => left.name.localeCompare(right.name));
+      for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        const filePath = pathApi.join(current, entry.name);
+        if (entry.isDirectory()) stack.push(filePath);
+        else if (entry.isFile() && accepts(definition.matcher, filePath, pathApi)) await addFile(definition, filePath);
+        if (truncated) break;
+      }
+    }
+  }
+
+  return {
+    complete,
+    errors,
+    files,
+    fingerprint: hash.digest("hex"),
+    sources: [...sources].sort(),
+    supportedSources: SUPPORTED_SOURCES,
+    truncated,
+    version: SOURCE_INVENTORY_VERSION,
+  };
+}