usagemax 0.1.0 → 0.2.0

package/README.md

@@ -1,42 +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 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.0",
+  "version": "0.2.0",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "license": "MIT",
   "author": "UsageMax",
@@ -15,11 +15,13 @@
   },
   "type": "module",
   "bin": {
-    "usagemax": "./src/cli.js"
+    "usagemax": "src/cli.js"
   },
   "files": [
     "src/cli.js",
     "src/core.js",
+    "src/installation.js",
+    "src/sources.js",
     "README.md",
     "LICENSE"
   ],

package/src/cli.js

@@ -1,24 +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.0";
+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;
@@ -66,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";
 }
@@ -79,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");
 }
@@ -88,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);
 }
@@ -184,26 +116,32 @@ async function link(args) {
   const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
   if (!endpoint) throw new Error("USAGEMAX_LINK_ENDPOINT must use HTTPS, except for localhost development.");
   const name = (option(args, "--name") || deviceLabel()).trim().slice(0, 80);
+  const previous = await readConfig();
+  const deviceId = await stableInstallationId(configDirectory(), previous?.deviceId);
+  const headers = { "content-type": "application/json" };
+  if (previous?.token) headers.authorization = `Bearer ${previous.token}`;
   const response = await fetch(endpoint, {
     method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ code, name, platform: platform(), cliVersion: VERSION }),
+    headers,
+    body: JSON.stringify({ code, name, platform: platform(), cliVersion: VERSION, deviceId }),
     signal: AbortSignal.timeout(15_000),
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) throw new Error(body?.error === "invalid_or_expired_link_code" ? "That link code is invalid, expired, or already used." : "UsageMax could not link this computer.");
   const ingestUrl = validHttpsUrl(body.ingestUrl, { allowLocalhost: true });
   if (!/^umx_[a-f0-9]{64}$/.test(body.token || "") || !ingestUrl) throw new Error("UsageMax returned an invalid link response.");
+  const profileHandle = typeof body.profileHandle === "string" ? body.profileHandle : undefined;
+  const sameAccount = Boolean(previous && previous.profileHandle && previous.profileHandle === profileHandle);
   const config = {
     version: 1,
     token: body.token,
     ingestUrl,
     profileUrl: validHttpsUrl(body.profileUrl) || "https://usagemax.com/account",
-    profileHandle: typeof body.profileHandle === "string" ? body.profileHandle : undefined,
-    deviceId: randomUUID(),
+    profileHandle,
+    deviceId,
     deviceName: name,
     linkedAt: new Date().toISOString(),
-    snapshots: {},
+    snapshots: sameAccount ? previous.snapshots : {},
   };
   await writeConfig(config);
   process.stdout.write(`Linked ${name} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
@@ -218,17 +156,28 @@ async function link(args) {
 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.");
-  const full = args.includes("--full");
+  config.deviceId = await stableInstallationId(configDirectory(), config.deviceId);
+  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);
@@ -239,6 +188,7 @@ async function sync(args, suppliedConfig) {
         authorization: `Bearer ${config.token}`,
         "content-type": "application/json",
         "idempotency-key": batchId(config.deviceId, events),
+        "x-usagemax-device-id": config.deviceId,
       },
       body: JSON.stringify({ events }),
       signal: AbortSignal.timeout(30_000),
@@ -248,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`);
   }
 }
@@ -272,8 +223,14 @@ async function status() {
     process.stdout.write("Not linked. Open https://usagemax.com/account to connect this computer.\n");
     return;
   }
+  const stableId = await stableInstallationId(configDirectory(), config.deviceId);
+  if (config.deviceId !== stableId) {
+    config.deviceId = stableId;
+    await writeConfig(config);
+  }
   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`);
 }
 
@@ -282,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`);
@@ -291,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));
@@ -307,7 +272,7 @@ async function removeLink() {
     return;
   }
   await unlink(path);
-  process.stdout.write("Removed the local UsageMax collector key. Revoke the collector in your account if this computer is no longer trusted.\n");
+  process.stdout.write("Removed the local UsageMax collector key. This computer's private installation identity was retained so relinking cannot duplicate its usage. Revoke the collector in your account if this computer is no longer trusted.\n");
 }
 
 async function main() {

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/installation.js

@@ -0,0 +1,38 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { platform } from "node:os";
+import { join } from "node:path";
+
+const INSTALLATION_FILE = "installation.json";
+
+export function validInstallationId(value) {
+  return typeof value === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(value);
+}
+
+export async function stableInstallationId(directory, preferred) {
+  const path = join(directory, INSTALLATION_FILE);
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    if (validInstallationId(parsed?.id)) return parsed.id;
+    throw new Error(`UsageMax installation identity is invalid: ${path}`);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+
+  const id = validInstallationId(preferred) ? preferred : randomUUID();
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  try {
+    await writeFile(path, `${JSON.stringify({ version: 1, id }, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+      flag: "wx",
+    });
+    if (platform() !== "win32") await chmod(path, 0o600);
+    return id;
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    if (validInstallationId(parsed?.id)) return parsed.id;
+    throw new Error(`UsageMax installation identity is invalid: ${path}`);
+  }
+}

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,
+  };
+}