usagemax 0.2.0 → 0.3.0

package/README.md

@@ -14,9 +14,10 @@ bunx usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
 
 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.
+collectors roll up into the same profile. When run inside WSL, UsageMax includes
+readable supported-provider homes under `/mnt/c/Users` automatically. Use the
+WSL collector as the single collector for that Windows PC instead of linking the
+same host history again from Windows.
 
 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
@@ -29,13 +30,17 @@ installation identity remains stable.
 bunx usagemax                       # sync changed usage
 bunx usagemax sync                  # same as above
 bunx usagemax sync --full           # reconcile all retained local history
+bunx usagemax sync --archives       # one-time compressed-history recovery
+bunx usagemax sync --dry-run --explain
+                                      # inspect the exact bounded plan; upload nothing
 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 doctor --deep --json  # machine-readable retained-history audit
 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 --revoke       # disable future uploads, then remove locally
 ```
 
 UsageMax pins [ccusage v20.0.20](https://github.com/ccusage/ccusage/releases/tag/v20.0.20)
@@ -51,6 +56,20 @@ The source inventory follows ccusage's environment overrides, including
 `QWEN_DATA_DIR`, `COPILOT_OTEL_FILE_EXPORTER_PATH`, `GEMINI_DATA_DIR`, and
 `GROK_HOME`. It also follows XDG Claude configuration and Windows Goose storage.
 
+UsageMax also discovers Claude Desktop local-agent sessions, `.cc-mirror`,
+recognizable renamed Claude/Codex backup folders, and supported Windows homes
+from WSL. Discovery is bounded to known locations and immediate home entries;
+normal syncs do not crawl the whole disk.
+On a multi-user WSL host, automatic Windows-home discovery stays off unless
+there is exactly one provider-bearing profile; set `USAGEMAX_ADDITIONAL_HOME`
+to the intended mounted home explicitly.
+
+If `doctor` reports compressed provider archives, run `sync --archives` once.
+Recovery extracts only safe Claude `projects/*.jsonl` members into a private
+temporary directory, performs one full deduplicated reconciliation, and removes
+the temporary files before exit. Weekly and incremental syncs never unpack
+archives.
+
 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
@@ -59,8 +78,9 @@ connector. UsageMax never invents usage that the source did not retain.
 
 ## Privacy, correctness, and load
 
-- The sync payload contains aggregate token counts, model/provider names, costs,
-  source names, and dates.
+- The sync payload contains authoritative aggregate token counts,
+  model/provider names, costs, source names, dates, coverage state, and opaque
+  SHA-256 session identities.
 - 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.
@@ -68,15 +88,24 @@ connector. UsageMax never invents usage that the source did not retain.
   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
+- Full history means all retained local history from 2024 onward. UsageMax
+  publishes complete source/day partitions, so decreased or removed local rows
+  correct the server-owned contribution instead of being silently retained.
+  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.
+- The package contains no shared service credential or private deployment URL.
+  It talks to the versioned `https://usagemax.com/api` contract. The random
+  per-installation write token is the only local secret; the service stores only
+  its hash and applies device binding, replay checks, payload caps, and quotas.
 - 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.
+- The server, not the local checkpoint, owns the accounting baseline. A lost
+  response or interrupted run can be retried without adding the same partition twice.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "license": "MIT",
   "author": "UsageMax",
@@ -18,6 +18,7 @@
     "usagemax": "src/cli.js"
   },
   "files": [
+    "src/archives.js",
     "src/cli.js",
     "src/core.js",
     "src/installation.js",

package/src/archives.js

@@ -0,0 +1,86 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { ccusageHome, discoverProviderArchives } from "./sources.js";
+
+const executeFile = promisify(execFile);
+const MAX_ARCHIVE_LIST_BYTES = 100 * 1024 * 1024;
+
+function archiveFlags(filePath, mode) {
+  const compressed = /(?:\.tar\.gz|\.tgz)$/i.test(filePath);
+  return mode === "list" ? (compressed ? "-tzf" : "-tf") : (compressed ? "-xzf" : "-xf");
+}
+
+export function safeArchiveMember(value, source = "claude") {
+  const normalized = String(value || "").replaceAll("\\", "/");
+  const parts = normalized.split("/").filter((item) => item && item !== ".");
+  const providerDirectory = source === "codex"
+    ? parts.includes("sessions") || parts.includes("archived_sessions")
+    : parts.includes("projects");
+  return !normalized.startsWith("/") && !parts.includes("..") && providerDirectory && normalized.endsWith(".jsonl");
+}
+
+async function findProviderRoots(root, maxDirectories = 10_000) {
+  const claude = [];
+  const codex = [];
+  const stack = [root];
+  let visited = 0;
+  while (stack.length && visited < maxDirectories) {
+    const current = stack.pop();
+    visited += 1;
+    let children;
+    try {
+      children = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const child of children) {
+      if (!child.isDirectory()) continue;
+      const childPath = join(current, child.name);
+      if (child.name === "projects") claude.push(childPath);
+      else if (child.name === "sessions" || child.name === "archived_sessions") codex.push(current);
+      else stack.push(childPath);
+    }
+  }
+  return { claude, codex };
+}
+
+export async function prepareArchiveRecovery(baseEnv) {
+  const detected = await discoverProviderArchives({ env: baseEnv, home: ccusageHome(baseEnv) });
+  const archives = detected.filter((item) => /(?:\.tar(?:\.gz)?|\.tgz)$/i.test(item.path));
+  const unsupported = detected.length - archives.length;
+  if (!archives.length) return { archives: 0, cleanup: async () => undefined, env: baseEnv, unsupported };
+
+  const temporary = await mkdtemp(join(tmpdir(), "usagemax-recover-"));
+  try {
+    for (let index = 0; index < archives.length; index += 1) {
+      const archive = archives[index];
+      const destination = join(temporary, `archive-${index + 1}`);
+      await mkdir(destination, { recursive: true, mode: 0o700 });
+      const { stdout } = await executeFile("tar", [archiveFlags(archive.path, "list"), archive.path], { encoding: "utf8", maxBuffer: MAX_ARCHIVE_LIST_BYTES });
+      const members = stdout.split(/\r?\n/).filter((member) => safeArchiveMember(member, archive.source));
+      for (let offset = 0; offset < members.length; offset += 80) {
+        await executeFile("tar", [archiveFlags(archive.path, "extract"), archive.path, "-C", destination, "--", ...members.slice(offset, offset + 80)], { maxBuffer: 4 * 1024 * 1024 });
+      }
+    }
+    const roots = await findProviderRoots(temporary);
+    const existingClaude = String(baseEnv.CLAUDE_CONFIG_DIR || "").split(",").map((item) => item.trim()).filter(Boolean);
+    const existingCodex = String(baseEnv.CODEX_HOME || "").split(",").map((item) => item.trim()).filter(Boolean);
+    return {
+      archives: archives.length,
+      cleanup: async () => rm(temporary, { force: true, recursive: true }),
+      env: {
+        ...baseEnv,
+        CLAUDE_CONFIG_DIR: [...new Set([...existingClaude, ...roots.claude])].join(","),
+        CODEX_HOME: [...new Set([...existingCodex, ...roots.codex])].join(","),
+      },
+      unsupported,
+    };
+  } catch (error) {
+    await rm(temporary, { force: true, recursive: true });
+    throw error;
+  }
+}

package/src/cli.js

@@ -9,14 +9,16 @@ 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 { prepareArchiveRecovery } from "./archives.js";
+import { buildSessionPlan, buildSnapshotPlan, normalizeLinkCode, sourceSummary, validHttpsUrl } from "./core.js";
 import { stableInstallationId } from "./installation.js";
-import { CCUSAGE_VERSION, ccusageEnvironment, SOURCE_INVENTORY_VERSION, sourceInventory, SUPPORTED_SOURCES } from "./sources.js";
+import { CCUSAGE_VERSION, ccusageEnvironment, ccusageHome, discoverProviderArchives, SOURCE_INVENTORY_VERSION, sourceInventory, SUPPORTED_SOURCES } from "./sources.js";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.2.0";
-const DEFAULT_LINK_ENDPOINT = "https://terrific-bobcat-522.convex.site/v1/devices/link";
+const VERSION = "0.3.0";
+const PUBLIC_API_ORIGIN = "https://usagemax.com/api";
+const DEFAULT_LINK_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/link`;
 const CONFIG_FILE = "config.json";
 const MAX_REPORT_BYTES = 100 * 1024 * 1024;
 const FULL_RECONCILE_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
@@ -31,6 +33,18 @@ function configPath() {
   return join(configDirectory(), CONFIG_FILE);
 }
 
+function isLegacyDirectApi(config) {
+  try {
+    const ingest = new URL(config.ingestUrl);
+    const profile = new URL(config.profileUrl || "https://usagemax.com");
+    return profile.hostname === "usagemax.com"
+      && ingest.hostname.endsWith(".convex.site")
+      && ingest.pathname === "/v1/telemetry/llm";
+  } catch {
+    return false;
+  }
+}
+
 async function readConfig() {
   try {
     const parsed = JSON.parse(await readFile(configPath(), "utf8"));
@@ -38,6 +52,16 @@ async function readConfig() {
     if (!validHttpsUrl(parsed.ingestUrl, { allowLocalhost: true })) return null;
     if (typeof parsed.deviceId !== "string" || !parsed.deviceId) return null;
     parsed.snapshots = parsed.snapshots && typeof parsed.snapshots === "object" ? parsed.snapshots : {};
+    if (isLegacyDirectApi(parsed)) {
+      parsed.ingestUrl = `${PUBLIC_API_ORIGIN}/v1/telemetry/llm`;
+      parsed.snapshotUrl = `${PUBLIC_API_ORIGIN}/v2/usage/snapshots`;
+      parsed.revokeUrl = `${PUBLIC_API_ORIGIN}/v1/devices/revoke`;
+      await writeConfig(parsed);
+    }
+    parsed.snapshotUrl = validHttpsUrl(parsed.snapshotUrl, { allowLocalhost: true })
+      || parsed.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v2/usage/snapshots");
+    parsed.revokeUrl = validHttpsUrl(parsed.revokeUrl, { allowLocalhost: true })
+      || parsed.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/revoke");
     return parsed;
   } catch {
     return null;
@@ -79,19 +103,22 @@ function help() {
   process.stdout.write("  usagemax                         Sync changed local usage\n");
   process.stdout.write("  usagemax link <one-use-code>     Link and sync this computer\n");
   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 sync [--full] [--archives] [--dry-run] [--explain] [--json]\n");
+  process.stdout.write("                                  Reconcile once; --archives performs one-time recovery\n");
   process.stdout.write("  usagemax status                  Show local link status\n");
-  process.stdout.write("  usagemax doctor [--deep]         Check source coverage; --deep parses full history\n");
+  process.stdout.write("  usagemax doctor [--deep] [--json]\n");
+  process.stdout.write("                                  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");
+  process.stdout.write("  usagemax unlink [--revoke]       Remove locally; --revoke also disables uploads\n");
 }
 
 function ccusageCliPath() {
   return join(dirname(require.resolve("ccusage/package.json")), "src", "cli.js");
 }
 
-async function ccusageJson(config, { full = false } = {}) {
+async function ccusageJson(config, { full = false, env } = {}) {
   const args = [ccusageCliPath(), "daily", "--json", "--offline", "--mode", "calculate", "--timezone", "UTC", "--by-agent", "--order", "asc"];
+  args.push("--sections", "daily,session");
   // 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.
@@ -104,11 +131,48 @@ async function ccusageJson(config, { full = false } = {}) {
   const { stdout } = await executeFile(process.execPath, args, {
     encoding: "utf8",
     maxBuffer: MAX_REPORT_BYTES,
-    env: { ...await ccusageEnvironment(), NO_COLOR: "1" },
+    env: { ...(env || await ccusageEnvironment()), NO_COLOR: "1" },
   });
   return JSON.parse(stdout);
 }
 
+function snapshotEndpoint(config) {
+  return validHttpsUrl(config.snapshotUrl, { allowLocalhost: true })
+    || config.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v2/usage/snapshots");
+}
+
+async function snapshotRequest(config, operation, payload, timeout = 30_000) {
+  const response = await fetch(snapshotEndpoint(config), {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${config.token}`,
+      "content-type": "application/json",
+      "x-usagemax-device-id": config.deviceId,
+    },
+    body: JSON.stringify({ operation, ...payload }),
+    signal: AbortSignal.timeout(timeout),
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    if (body?.error === "unauthorized") throw new Error("This collector key is no longer valid. Link the computer again.");
+    throw new Error(`UsageMax rejected ${operation} (${response.status}${body?.error ? `: ${body.error}` : ""}).`);
+  }
+  return body;
+}
+
+function newerVersion(recommended) {
+  if (!/^\d+\.\d+\.\d+$/.test(recommended || "")) return false;
+  const current = VERSION.split(".").map(Number);
+  const next = recommended.split(".").map(Number);
+  return next.some((value, index) => value > current[index] && next.slice(0, index).every((prior, priorIndex) => prior === current[priorIndex]));
+}
+
+function warnVersion(body) {
+  if (newerVersion(body?.recommendedCliVersion)) {
+    process.stderr.write(`UsageMax ${body.recommendedCliVersion} is available. Run \`bunx usagemax@latest\` for current coverage fixes.\n`);
+  }
+}
+
 async function link(args) {
   const code = normalizeLinkCode(args[0]);
   if (!code) throw new Error("Paste the one-use UMX link code shown at usagemax.com/account.");
@@ -129,13 +193,17 @@ async function link(args) {
   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 snapshotUrl = validHttpsUrl(body.snapshotUrl, { allowLocalhost: true }) || ingestUrl?.replace(/\/v1\/telemetry\/llm$/, "/v2/usage/snapshots");
+  const revokeUrl = validHttpsUrl(body.revokeUrl, { allowLocalhost: true }) || ingestUrl?.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/revoke");
+  if (!/^umx_[a-f0-9]{64}$/.test(body.token || "") || !ingestUrl || !snapshotUrl || !revokeUrl) 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,
+    snapshotUrl,
+    revokeUrl,
     profileUrl: validHttpsUrl(body.profileUrl) || "https://usagemax.com/account",
     profileHandle,
     deviceId,
@@ -144,6 +212,7 @@ async function link(args) {
     snapshots: sameAccount ? previous.snapshots : {},
   };
   await writeConfig(config);
+  warnVersion(body);
   process.stdout.write(`Linked ${name} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
   if (args.includes("--no-sync")) {
     process.stdout.write("No usage was uploaded. Run `bunx usagemax sync --full` when you are ready.\n");
@@ -154,67 +223,139 @@ async function link(args) {
 }
 
 async function sync(args, suppliedConfig) {
+  const baseEnv = await ccusageEnvironment();
+  const recovery = args.includes("--archives")
+    ? await prepareArchiveRecovery(baseEnv)
+    : { archives: 0, cleanup: async () => undefined, env: baseEnv, unsupported: 0 };
+  try {
+    return await syncPrepared(args, suppliedConfig, recovery);
+  } finally {
+    await recovery.cleanup();
+  }
+}
+
+async function syncPrepared(args, suppliedConfig, recovery) {
   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 requestedFull = args.includes("--full");
-  const inventory = await sourceInventory();
+  const requestedArchives = args.includes("--archives");
+  const dryRun = args.includes("--dry-run");
+  const explain = args.includes("--explain");
+  const json = args.includes("--json");
+  const inventory = await sourceInventory({ env: recovery.env, home: ccusageHome(recovery.env) });
   const today = new Date().toISOString().slice(0, 10);
   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
+  const fullDue = config.snapshotProtocolVersion !== 2
+    || config.sourceInventoryVersion !== SOURCE_INVENTORY_VERSION
     || !Number.isFinite(lastFullSync)
     || Date.now() - lastFullSync >= FULL_RECONCILE_INTERVAL_MS
     || foundNewSource;
-  const full = requestedFull || fullDue;
+  const full = requestedFull || requestedArchives || 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`);
+    const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: inventory.complete ? "complete" : "partial" };
+    if (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@${CCUSAGE_VERSION}`);
+  const report = await ccusageJson(config, { env: recovery.env, full });
+  const legacySnapshotBootstrap = config.snapshotProtocolVersion !== 2
+    && Object.keys(config.snapshots || {}).length > 0;
+  const runId = randomUUID();
+  const revision = Date.now();
+  const pricingVersion = `ccusage@${CCUSAGE_VERSION}`;
+  const { partitions, nextSnapshots, regressions } = buildSnapshotPlan(report, config.snapshots, {
+    bootstrap: config.snapshotProtocolVersion !== 2,
+    complete: inventory.complete,
+    full,
+    pricingVersion,
+    revision,
+    runId,
+  });
+  const sessions = buildSessionPlan(report, config.deviceId);
+  const sources = sourceSummary(report);
+  const days = Array.isArray(report?.daily)
+    ? report.daily.map((row) => row?.period).filter((day) => /^\d{4}-\d{2}-\d{2}$/.test(day || "")).sort()
+    : [];
+  const result = {
+    accepted: 0,
+    changedRows: partitions.reduce((sum, partition) => sum + partition.rows.filter((row) => JSON.stringify(row.previous) !== JSON.stringify(row.current)).length, 0),
+    sessions: sessions.length,
+    sources,
+    corrections: regressions.length,
+    partitions: partitions.length,
+    scanned: true,
+    full,
+    coverage: inventory.complete && !inventory.truncated && inventory.errors === 0 ? "complete" : "partial",
+    range: { from: days[0], to: days.at(-1) },
+  };
+  if (requestedArchives) {
+    result.archives = recovery.archives;
+    result.unsupportedArchives = recovery.unsupported;
+  }
+  if (dryRun) {
+    if (json) process.stdout.write(`${JSON.stringify({ ...result, dryRun: true })}\n`);
+    else {
+      process.stdout.write(`Dry run: ${partitions.length} partition(s), ${result.changedRows} changed row(s), ${sessions.length} private session identifiers, no upload.\n`);
+      if (explain) process.stdout.write(`Coverage ${result.coverage}; ${sources.length} source(s); ${days[0] || "unknown"} to ${days.at(-1) || "unknown"}; ${regressions.length} downward correction(s).\n`);
+    }
+    return result;
+  }
   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);
-    const events = batch.map((item) => item.event);
-    const response = await fetch(config.ingestUrl, {
-      method: "POST",
-      headers: {
-        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),
+  try {
+    const begin = await snapshotRequest(config, "begin", {
+      runId,
+      mode: requestedArchives ? "archives" : full ? "full" : "incremental",
+      baselineMode: legacySnapshotBootstrap ? "adopt-current" : "apply",
+      sourceCount: sources.length,
+      partitionCount: partitions.length,
+      inventoryComplete: inventory.complete,
+      inventoryErrors: inventory.errors,
+      inventoryTruncated: inventory.truncated,
+      coverageStartDay: days[0],
+      coverageEndDay: days.at(-1),
     });
-    const body = await response.json().catch(() => ({}));
-    if (!response.ok) throw new Error(body?.error === "unauthorized" ? "This collector key is no longer valid. Link the computer again." : `UsageMax rejected a sync batch (${response.status}).`);
-    accepted += Number(body.accepted || 0);
-    for (const item of batch) config.snapshots[item.snapshotKey] = item.snapshot;
+    warnVersion(begin);
+    for (let offset = 0; offset < sessions.length; offset += 100) {
+      await snapshotRequest(config, "sessions", { runId, sessions: sessions.slice(offset, offset + 100) });
+    }
+    for (let offset = 0; offset < partitions.length; offset += 10) {
+      const response = await snapshotRequest(config, "partitions", { runId, partitions: partitions.slice(offset, offset + 10) }, 60_000);
+      result.accepted += Number(response.changedRows || 0);
+      if (!json && process.stderr.isTTY && partitions.length > 10) {
+        process.stderr.write(`UsageMax: uploaded ${Math.min(offset + 10, partitions.length)}/${partitions.length} history partitions\r`);
+      }
+    }
+    if (!json && process.stderr.isTTY && partitions.length > 10) process.stderr.write("\n");
+    const completed = await snapshotRequest(config, "complete", { runId });
+    warnVersion(completed);
+    config.snapshots = nextSnapshots;
+    config.snapshotProtocolVersion = 2;
     config.lastSyncAt = new Date().toISOString();
+    config.lastReconciledDay = today;
+    config.lastSyncComplete = true;
+    config.sourceInventoryVersion = SOURCE_INVENTORY_VERSION;
+    config.knownSources = [...new Set([...knownSources, ...inventory.sources, ...sources])].sort();
+    if (inventory.complete) config.sourceFingerprint = inventory.fingerprint;
+    else delete config.sourceFingerprint;
+    if (full) config.lastFullSyncAt = config.lastSyncAt;
     await writeConfig(config);
+  } catch (error) {
+    await snapshotRequest(config, "fail", { runId, failureCode: error instanceof Error ? error.message.slice(0, 80) : "sync_failed" }).catch(() => undefined);
+    throw error;
   }
-  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`);
+  if (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"}${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`);
+    process.stdout.write(partitions.length || sessions.length
+      ? `Reconciled ${result.accepted} changed usage row(s) and ${sessions.length} session identifier(s) from ${sources.join(", ") || "local agents"}${full ? " across retained history" : ""}.\n`
+      : `Already up to date. No usage rows changed${full ? " after a full-history reconciliation" : ""}.\n`);
+    if (regressions.length) process.stdout.write(`${regressions.length} local row(s) moved backward and were submitted as authoritative corrections.\n`);
+    if (explain) process.stdout.write(`Coverage ${result.coverage}; ${sources.length} source(s); ${days[0] || "unknown"} to ${days.at(-1) || "unknown"}; ${partitions.length} atomic partition(s).\n`);
   }
+  return result;
 }
 
 async function status() {
@@ -236,18 +377,42 @@ async function status() {
 
 async function doctor(args = []) {
   const config = await readConfig();
-  const inventory = await sourceInventory();
+  const env = await ccusageEnvironment();
+  const inventory = await sourceInventory({ env, home: ccusageHome(env) });
+  const archives = await discoverProviderArchives({ env, home: ccusageHome(env) });
+  const homes = String(env.USAGEMAX_DISCOVERED_HOMES || ccusageHome(env)).split(",").filter(Boolean);
+  const result = {
+    linked: Boolean(config),
+    homes,
+    detectedSources: inventory.sources,
+    files: inventory.files,
+    inventoryComplete: inventory.complete,
+    inventoryErrors: inventory.errors,
+    inventoryTruncated: inventory.truncated,
+    supportedSources: SUPPORTED_SOURCES,
+    archives: archives.length,
+    environment: platform() === "linux" && process.env.WSL_DISTRO_NAME ? `WSL ${process.env.WSL_DISTRO_NAME}` : platform(),
+    mode: args.includes("--deep") ? "deep" : "metadata-only",
+  };
+  if (args.includes("--deep")) {
+    const report = await ccusageJson(config, { env, full: true });
+    result.parsedSources = sourceSummary(report);
+    result.sessions = buildSessionPlan(report, config?.deviceId || "unlinked").length;
+  }
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
   process.stdout.write(`Collector: ${config ? "linked" : "not linked"}\n`);
+  process.stdout.write(`Discovered homes: ${homes.length} (${homes.join(", ")})\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`);
+    process.stdout.write(`Environment: WSL ${process.env.WSL_DISTRO_NAME}; readable Windows provider homes are included automatically\n`);
   }
+  if (archives.length) process.stdout.write(`Recovery: ${archives.length} compressed provider archive(s) detected; run \`bunx usagemax sync --archives\` once to reconcile them\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: true });
-    process.stdout.write(`Parsed sources: ${sourceSummary(report).join(", ") || "none"}\n`);
-  }
+  if (result.parsedSources) process.stdout.write(`Parsed sources: ${result.parsedSources.join(", ") || "none"}; ${result.sessions} private session identifiers\n`);
   process.stdout.write(`Mode: one-shot, metadata no-op check, ${args.includes("--deep") ? "deep local parse" : "no log parsing"}\n`);
 }
 
@@ -264,15 +429,28 @@ async function report(args) {
   if (code !== 0) process.exitCode = code;
 }
 
-async function removeLink() {
+async function removeLink(args = []) {
   const path = configPath();
   const config = await readConfig();
   if (!config) {
     process.stdout.write("This computer is not linked.\n");
     return;
   }
+  if (args.includes("--revoke")) {
+    const endpoint = validHttpsUrl(config.revokeUrl, { allowLocalhost: true });
+    if (!endpoint) throw new Error("This collector does not have a valid revoke endpoint. Revoke it at https://usagemax.com/account.");
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { authorization: `Bearer ${config.token}`, "content-type": "application/json" },
+      body: JSON.stringify({ deviceId: config.deviceId }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!response.ok) throw new Error("UsageMax could not revoke this collector. It remains linked locally.");
+  }
   await unlink(path);
-  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");
+  process.stdout.write(args.includes("--revoke")
+    ? "Revoked this collector and removed its local key. Existing usage totals were retained.\n"
+    : "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() {
@@ -285,7 +463,7 @@ async function main() {
   if (command === "status") return status();
   if (command === "doctor") return doctor(args.slice(1));
   if (command === "report") return report(args.slice(1));
-  if (command === "unlink") return removeLink();
+  if (command === "unlink") return removeLink(args.slice(1));
   throw new Error(`Unknown command: ${command}. Run usagemax --help.`);
 }
 

package/src/core.js

@@ -43,6 +43,82 @@ function providerFor(model, source) {
   return source;
 }
 
+const snapshotCounterFields = [
+  "inputTokens",
+  "outputTokens",
+  "cacheReadTokens",
+  "cacheWriteTokens",
+  "reasoningTokens",
+  "unclassifiedTokens",
+  "totalTokens",
+  "costMicros",
+  "requests",
+  "errors",
+];
+
+function snapshotCounters(value = {}) {
+  const inputTokens = number(value.inputTokens);
+  const outputTokens = number(value.outputTokens);
+  const cacheReadTokens = number(value.cacheReadTokens);
+  const cacheWriteTokens = number(value.cacheWriteTokens);
+  const reasoningTokens = number(value.reasoningTokens);
+  const suppliedTotal = number(value.totalTokens);
+  const classified = inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens + reasoningTokens;
+  const unclassifiedTokens = value.unclassifiedTokens === undefined
+    ? Math.max(0, suppliedTotal - classified)
+    : number(value.unclassifiedTokens);
+  return {
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    reasoningTokens,
+    unclassifiedTokens,
+    totalTokens: classified + unclassifiedTokens,
+    costMicros: number(value.costMicros, MAX_SAFE_COST_MICROS),
+    requests: number(value.requests),
+    errors: number(value.errors),
+  };
+}
+
+function sameCounters(left, right) {
+  return snapshotCounterFields.every((field) => left[field] === right[field]);
+}
+
+function snapshotKey(source, period, provider, model) {
+  return `${source}\u001f${period}\u001f${provider}\u001f${model}`;
+}
+
+function readSnapshotKey(key) {
+  const parts = String(key).split("\u001f");
+  if (parts.length === 4) return { source: parts[0], period: parts[1], provider: parts[2], model: parts[3] };
+  if (parts.length === 3) return { source: parts[0], period: parts[1], provider: providerFor(parts[2], parts[0]), model: parts[2] };
+  return null;
+}
+
+function normalizedSnapshotRows(report) {
+  const rows = new Map();
+  for (const row of currentRows(report)) {
+    const provider = providerFor(row.model, row.source);
+    const key = snapshotKey(row.source, row.period, provider, row.model);
+    const current = snapshotCounters(row.current);
+    const existing = rows.get(key);
+    if (existing) {
+      for (const field of snapshotCounterFields) existing.current[field] += current[field];
+    } else {
+      rows.set(key, {
+        key,
+        source: row.source,
+        period: row.period,
+        provider,
+        model: row.model,
+        current,
+      });
+    }
+  }
+  return rows;
+}
+
 function sha256(value) {
   return createHash("sha256").update(value).digest("hex");
 }
@@ -195,6 +271,118 @@ export function buildDeltaPlan(report, priorSnapshots, deviceId, pricingVersion
   return { plan, regressions };
 }
 
+export function buildSnapshotPlan(report, priorSnapshots, {
+  bootstrap = false,
+  complete = true,
+  full = false,
+  pricingVersion = "ccusage",
+  revision = Date.now(),
+  runId = randomPlanId(),
+} = {}) {
+  const rows = normalizedSnapshotRows(report);
+  const priorRows = new Map();
+  const snapshots = priorSnapshots && typeof priorSnapshots === "object" ? priorSnapshots : {};
+  for (const [rawKey, rawValue] of Object.entries(snapshots)) {
+    const identity = readSnapshotKey(rawKey);
+    if (!identity || !/^\d{4}-\d{2}-\d{2}$/.test(identity.period)) continue;
+    const key = snapshotKey(identity.source, identity.period, identity.provider, identity.model);
+    priorRows.set(key, {
+      key,
+      ...identity,
+      current: snapshotCounters(rawValue),
+    });
+  }
+
+  const currentPartitions = new Set([...rows.values()].map((row) => `${row.source}\u001f${row.period}`));
+  const allKeys = new Set(rows.keys());
+  for (const [key, prior] of priorRows) {
+    if (full || currentPartitions.has(`${prior.source}\u001f${prior.period}`)) allKeys.add(key);
+  }
+
+  const grouped = new Map();
+  const nextSnapshots = {};
+  const regressions = [];
+  for (const key of allKeys) {
+    const currentRow = rows.get(key);
+    const priorRow = priorRows.get(key);
+    const identity = currentRow || priorRow;
+    if (!identity) continue;
+    const previous = priorRow?.current ?? snapshotCounters();
+    const current = currentRow?.current ?? snapshotCounters();
+    if (snapshotCounterFields.some((field) => current[field] < previous[field])) regressions.push(key);
+    if (!sameCounters(current, snapshotCounters())) nextSnapshots[key] = current;
+    const partitionKey = `${identity.source}\u001f${identity.period}`;
+    const rowsForPartition = grouped.get(partitionKey) ?? [];
+    rowsForPartition.push({
+      snapshotKey: key,
+      provider: identity.provider,
+      model: identity.model,
+      previous,
+      current,
+      costBasis: "estimated",
+      contentHash: sha256(`${key}\u001f${JSON.stringify(current)}`),
+      lastUsedAt: Date.parse(`${identity.period}T12:00:00.000Z`),
+    });
+    grouped.set(partitionKey, rowsForPartition);
+  }
+
+  const partitions = [];
+  for (const [partitionKey, partitionRows] of grouped) {
+    const [source, day] = partitionKey.split("\u001f");
+    const changed = partitionRows.some((row) => !sameCounters(row.previous, row.current));
+    if (!bootstrap && !full && !changed) continue;
+    partitionRows.sort((left, right) => `${left.provider}/${left.model}`.localeCompare(`${right.provider}/${right.model}`));
+    const wireRows = partitionRows.map(({ provider, model, previous, current, costBasis, contentHash, lastUsedAt }) => ({
+      provider,
+      model,
+      previous,
+      current,
+      costBasis,
+      contentHash,
+      lastUsedAt,
+    }));
+    const payloadHash = sha256(JSON.stringify({ source, day, complete, pricingVersion, rows: wireRows }));
+    partitions.push({
+      partitionId: `${runId}:${sha256(partitionKey).slice(0, 24)}`,
+      payloadHash,
+      revision,
+      source,
+      day,
+      complete,
+      pricingVersion,
+      rows: wireRows,
+    });
+  }
+  partitions.sort((left, right) => left.day === right.day ? left.source.localeCompare(right.source) : left.day.localeCompare(right.day));
+  return { partitions, nextSnapshots, regressions };
+}
+
+function randomPlanId() {
+  return `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function buildSessionPlan(report, deviceId) {
+  const sessionRows = Array.isArray(report?.session) ? report.session : [];
+  const sessions = new Map();
+  for (const row of sessionRows) {
+    if (!row || typeof row !== "object") continue;
+    const source = text(row.agent, "unknown", 60).toLowerCase();
+    const stableIdentity = text(row.period ?? row.sessionId ?? row.id, "", 1000);
+    if (!stableIdentity) continue;
+    const metadata = row.metadata && typeof row.metadata === "object" ? row.metadata : {};
+    const firstActivityAt = Date.parse(metadata.firstActivity ?? metadata.createdAt ?? "");
+    const lastActivityAt = Date.parse(metadata.lastActivity ?? row.lastActivity ?? "");
+    const sessionKey = sha256(`${deviceId}\u001f${source}\u001f${stableIdentity}`);
+    sessions.set(`${source}\u001f${sessionKey}`, {
+      source,
+      sessionKey,
+      ...(Number.isFinite(firstActivityAt) ? { firstActivityAt } : {}),
+      ...(Number.isFinite(lastActivityAt) ? { lastActivityAt } : {}),
+    });
+  }
+  return [...sessions.values()].sort((left, right) => `${left.source}/${left.sessionKey}`.localeCompare(`${right.source}/${right.sessionKey}`));
+}
+
 export function batchId(deviceId, events) {
   const identity = events.map((event) => event.eventKey).join("\u001f");
   return `cli:${deviceId}:${sha256(identity).slice(0, 32)}`;

package/src/sources.js

@@ -4,7 +4,7 @@ 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 SOURCE_INVENTORY_VERSION = 3;
 export const SUPPORTED_SOURCES = [
   "amp",
   "claude",
@@ -25,6 +25,10 @@ export const SUPPORTED_SOURCES = [
 ];
 
 const MAX_FINGERPRINT_FILES = 50_000;
+const WINDOWS_SYSTEM_PROFILES = /^(?:all users|default(?: user)?|defaultuser0|public|temp(?:\.|$)|umfd-)/i;
+const BACKUP_DIRECTORY = /(?:claude|codex).*(?:backup|archive|old|copy|mirror)|(?:backup|archive|old|copy|mirror).*(?:claude|codex)|superclaude/i;
+const ARCHIVE_EXTENSION = /(?:\.tar(?:\.gz)?|\.tgz|\.zip|\.7z)$/i;
+const ARCHIVE_FILE = /(?:claude|codex).*(?:\.tar(?:\.gz)?|\.tgz|\.zip|\.7z)$/i;
 
 function has(env, name) {
   return Object.prototype.hasOwnProperty.call(env, name);
@@ -45,6 +49,127 @@ function expandTilde(value, home, pathApi) {
   return value;
 }
 
+function uniquePaths(values, pathApi) {
+  const seen = new Set();
+  return values.filter((value) => {
+    if (typeof value !== "string" || !value.trim()) return false;
+    const normalized = pathApi.normalize(value.trim());
+    if (seen.has(normalized)) return false;
+    seen.add(normalized);
+    return true;
+  });
+}
+
+async function entries(value) {
+  try {
+    return await readdir(value, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+async function providerBearingHome(home, pathApi) {
+  const markers = [".claude", ".codex", ".factory", ".gemini", ".openclaw", ".hermes", ".grok"];
+  const checks = await Promise.all(markers.map((marker) => existsDirectory(pathApi.join(home, marker))));
+  return checks.some(Boolean);
+}
+
+async function discoverWslWindowsHomes(env, platform, pathApi) {
+  if (platform !== "linux" || !String(env.WSL_DISTRO_NAME ?? "").trim()) return [];
+  const usersRoot = String(env.USAGEMAX_WSL_USERS_DIR ?? "/mnt/c/Users").trim();
+  const candidates = [];
+  for (const entry of await entries(usersRoot)) {
+    if (!entry.isDirectory() || WINDOWS_SYSTEM_PROFILES.test(entry.name)) continue;
+    const candidate = pathApi.join(usersRoot, entry.name);
+    if (await providerBearingHome(candidate, pathApi)) candidates.push(candidate);
+  }
+  // A WSL distro can see every Windows profile. Auto-select only when there is
+  // one unambiguous provider-bearing profile; multi-user systems opt in with
+  // USAGEMAX_ADDITIONAL_HOME so one employee never absorbs another's usage.
+  return candidates.length === 1 ? candidates : [];
+}
+
+async function discoverBackupRoots(home, pathApi) {
+  const claude = [];
+  const codex = [];
+  const containers = [
+    { path: home, requireProviderName: true },
+    { path: pathApi.join(home, ".claude", "backups"), requireProviderName: false },
+    { path: pathApi.join(home, ".codex", "backups"), requireProviderName: false },
+  ];
+  for (const container of containers) {
+    for (const entry of await entries(container.path)) {
+      if (!entry.isDirectory() || (container.requireProviderName && !BACKUP_DIRECTORY.test(entry.name))) continue;
+      const candidate = pathApi.join(container.path, entry.name);
+      const claudeRoots = [candidate, pathApi.join(candidate, ".claude"), pathApi.join(candidate, "config")];
+      for (const root of claudeRoots) {
+        if (await existsDirectory(pathApi.join(root, "projects"))) claude.push(root);
+      }
+      const codexRoots = [candidate, pathApi.join(candidate, ".codex")];
+      for (const root of codexRoots) {
+        if (await existsDirectory(pathApi.join(root, "sessions")) || await existsDirectory(pathApi.join(root, "archived_sessions"))) codex.push(root);
+      }
+    }
+  }
+  return { claude, codex };
+}
+
+async function discoverNestedClaudeRoots(home, pathApi, maxDirectories = 4_096) {
+  const bases = [
+    pathApi.join(home, "Library", "Application Support", "Claude", "local-agent-mode-sessions"),
+    pathApi.join(home, "AppData", "Roaming", "Claude", "local-agent-mode-sessions"),
+  ];
+  const roots = [];
+  for (const base of bases) {
+    if (!await existsDirectory(base)) continue;
+    const stack = [{ directory: base, depth: 0 }];
+    let visited = 0;
+    while (stack.length && visited < maxDirectories) {
+      const { directory, depth } = stack.pop();
+      visited += 1;
+      for (const entry of await entries(directory)) {
+        if (!entry.isDirectory() || entry.name === "node_modules" || entry.name === ".git") continue;
+        const child = pathApi.join(directory, entry.name);
+        if (entry.name === ".claude") {
+          if (await existsDirectory(pathApi.join(child, "projects"))) roots.push(child);
+        } else if (depth < 7) {
+          stack.push({ directory: child, depth: depth + 1 });
+        }
+      }
+    }
+  }
+  return roots;
+}
+
+function setDiscoveredList(effective, name, defaults, additions, pathApi) {
+  if (has(effective, name) && !String(effective[name] ?? "").trim()) return;
+  const configured = has(effective, name) ? commaList(effective[name]) : defaults;
+  effective[name] = uniquePaths([...configured, ...additions], pathApi).join(",");
+}
+
+export async function discoverProviderArchives({ env = process.env, home = ccusageHome(env), pathApi = path } = {}) {
+  const homes = uniquePaths([home, ...commaList(env.USAGEMAX_DISCOVERED_HOMES), ...commaList(env.USAGEMAX_ADDITIONAL_HOME)], pathApi);
+  const archives = [];
+  for (const candidateHome of homes) {
+    const roots = [
+      { path: candidateHome, source: null },
+      { path: pathApi.join(candidateHome, ".claude", "backups"), source: "claude" },
+      { path: pathApi.join(candidateHome, ".codex", "backups"), source: "codex" },
+    ];
+    for (const root of roots) {
+      for (const entry of await entries(root.path)) {
+        if (!entry.isFile() || !ARCHIVE_EXTENSION.test(entry.name) || (!root.source && !ARCHIVE_FILE.test(entry.name))) continue;
+        const filePath = pathApi.join(root.path, entry.name);
+        try {
+          const metadata = await stat(filePath);
+          archives.push({ path: filePath, size: metadata.size, source: root.source || (/codex/i.test(entry.name) ? "codex" : "claude") });
+        } catch {}
+      }
+    }
+  }
+  return archives.filter((archive, index) => archives.findIndex((item) => item.path === archive.path) === index);
+}
+
 export function ccusageHome(env = process.env, fallback = homedir()) {
   for (const value of [env.HOME, env.USERPROFILE]) {
     if (typeof value === "string" && value.trim()) return value;
@@ -156,13 +281,52 @@ export function sourceDefinitions({ env = process.env, home = ccusageHome(env),
 
 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 home = ccusageHome(effective);
+  const configuredHomes = commaList(effective.USAGEMAX_ADDITIONAL_HOME).map((item) => expandTilde(item, home, pathApi));
+  const wslHomes = await discoverWslWindowsHomes(effective, platform, pathApi);
+  const additionalHomes = uniquePaths([...configuredHomes, ...wslHomes], pathApi).filter((item) => pathApi.normalize(item) !== pathApi.normalize(home));
+  const homes = [home, ...additionalHomes];
+  const backups = await Promise.all(homes.map((candidate) => discoverBackupRoots(candidate, pathApi)));
+  const nestedClaude = (await Promise.all(homes.map((candidate) => discoverNestedClaudeRoots(candidate, pathApi)))).flat();
+  const mirroredClaude = [];
+  for (const candidate of homes) {
+    const mirror = pathApi.join(candidate, ".cc-mirror", "mclaude", "config");
+    if (await existsDirectory(pathApi.join(mirror, "projects"))) mirroredClaude.push(mirror);
+  }
+
+  const xdgClaude = pathApi.join(has(effective, "XDG_CONFIG_HOME") ? String(effective.XDG_CONFIG_HOME) : pathApi.join(home, ".config"), "claude");
+  setDiscoveredList(effective, "CLAUDE_CONFIG_DIR", [xdgClaude, pathApi.join(home, ".claude")], [
+    ...additionalHomes.flatMap((candidate) => [pathApi.join(candidate, ".config", "claude"), pathApi.join(candidate, ".claude")]),
+    ...mirroredClaude,
+    ...backups.flatMap((item) => item.claude),
+    ...nestedClaude,
+  ], pathApi);
+  setDiscoveredList(effective, "CODEX_HOME", [pathApi.join(home, ".codex")], [
+    ...additionalHomes.map((candidate) => pathApi.join(candidate, ".codex")),
+    ...backups.flatMap((item) => item.codex),
+  ], pathApi);
+
+  const additions = (segments) => additionalHomes.map((candidate) => pathApi.join(candidate, ...segments));
+  setDiscoveredList(effective, "OPENCODE_DATA_DIR", [pathApi.join(home, ".local", "share", "opencode")], additions([".local", "share", "opencode"]), pathApi);
+  setDiscoveredList(effective, "AMP_DATA_DIR", [pathApi.join(home, ".local", "share", "amp")], additions([".local", "share", "amp"]), pathApi);
+  setDiscoveredList(effective, "DROID_SESSIONS_DIR", [pathApi.join(home, ".factory", "sessions")], additions([".factory", "sessions"]), pathApi);
+  setDiscoveredList(effective, "CODEBUFF_DATA_DIR", ["manicode", "manicode-dev", "manicode-staging"].map((channel) => pathApi.join(home, ".config", channel)), additionalHomes.flatMap((candidate) => ["manicode", "manicode-dev", "manicode-staging"].map((channel) => pathApi.join(candidate, ".config", channel))), pathApi);
+  setDiscoveredList(effective, "HERMES_HOME", [pathApi.join(home, ".hermes")], additions([".hermes"]), pathApi);
+  setDiscoveredList(effective, "PI_AGENT_DIR", [pathApi.join(home, ".pi", "agent", "sessions")], additions([".pi", "agent", "sessions"]), pathApi);
+  setDiscoveredList(effective, "OPENCLAW_DIR", [".openclaw", ".clawdbot", ".moltbot", ".moldbot"].map((name) => pathApi.join(home, name)), additionalHomes.flatMap((candidate) => [".openclaw", ".clawdbot", ".moltbot", ".moldbot"].map((name) => pathApi.join(candidate, name))), pathApi);
+  setDiscoveredList(effective, "KILO_DATA_DIR", [pathApi.join(home, ".local", "share", "kilo")], additions([".local", "share", "kilo"]), pathApi);
+  setDiscoveredList(effective, "KIMI_DATA_DIR", [pathApi.join(home, ".kimi"), pathApi.join(home, ".kimi-code")], additionalHomes.flatMap((candidate) => [pathApi.join(candidate, ".kimi"), pathApi.join(candidate, ".kimi-code")]), pathApi);
+  setDiscoveredList(effective, "QWEN_DATA_DIR", [pathApi.join(home, ".qwen")], additions([".qwen"]), pathApi);
+  setDiscoveredList(effective, "GEMINI_DATA_DIR", [pathApi.join(home, ".gemini", "tmp")], additions([".gemini", "tmp"]), pathApi);
+
+  effective.USAGEMAX_DISCOVERED_HOMES = homes.join(",");
+
+  if (platform === "win32" && !String(effective.GOOSE_PATH_ROOT ?? "").trim() && String(effective.APPDATA ?? "").trim()) {
+    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 {}
   }
-  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;
 }