usagemax 0.2.0 → 0.3.1

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,24 +78,45 @@ 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.
+Interrupted uploads resume with `bunx usagemax sync`. Server upload runs expire
+after 30 idle days. If the server reports an expired run, use `sync --restart`:
+this preserves the last committed checkpoint and performs a fresh full scan.
+It never automatically replays an old authoritative deletion against newer data.
+
+- The sync payload contains 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.
-- A metadata inventory exits without parsing logs or using the network when
-  nothing changed.
+- A successful previous parse with a complete, unchanged metadata inventory skips
+  parsing and uploading again that day. Inventory stability is independent of
+  deletion authority; a no-change result retains the previous partial coverage
+  label. New sources, date rollover, explicit full/archive requests and weekly
+  reconciliation still trigger the appropriate scan.
 - 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.
+- Full history scans retained local history from 2024 onward. Inventory success
+  does not prove every file parsed. Until the parser certifies source/day coverage,
+  uploads are marked partial and any row with a decreasing counter retains its
+  entire previous vector. This includes explicit zeros and missing sources.
+  Older checkpoints survive incremental windows. Authoritative corrections remain
+  supported by the planner but are not claimed by this parser integration.
+  Deleted or never-persisted usage requires a provider export.
 - 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.
+  its SHA-256 hash. A local config lock prevents overlapping commands from
+  overwriting pending runs; server receipts make repeated uploads 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.
@@ -84,5 +124,36 @@ connector. UsageMax never invents usage that the source did not retain.
 Use `USAGEMAX_CONFIG_DIR` to select another config directory. Development and
 self-hosted installations may set `USAGEMAX_LINK_ENDPOINT` before linking.
 
+## Interrupted uploads and protocol 0.3.1
+
+Before uploading, the CLI saves the exact run, ordered request payloads and next
+checkpoint in the private config. `sync` resumes this journal before scanning new
+data. Local snapshots advance only after completion is acknowledged. A resumed
+command finishes the saved scan; run `sync` again to collect subsequent changes.
+`sync --dry-run` reports pending work without uploading. Do not delete config.json
+to retry a failed upload. A successful relink or unlink replaces/removes the local
+journal along with its credential.
+
+Network failures, malformed success responses, HTTP 429 and 5xx get at most five
+attempts per request with exponential jitter. Retry-After seconds and HTTP dates
+are honored up to 60 seconds; longer waits stop with an instruction to retry later.
+Only completion's `snapshot_run_incomplete` HTTP 409 is retried, because server
+cleanup can still be pending. Authentication, validation and other conflicts fail
+with an actionable message and retain the journal. JSON `accepted` is null for
+uploads because lost responses/replays cannot reliably reconstruct that count;
+`changedRows` is the local planned count, not a server accounting receipt.
+
+Each sorted source/day is sent as ordered chunks of at most 100 rows. Each has a
+unique partitionId, zero-based chunkIndex and shared chunkCount. The payload hash
+covers `{source, day, complete, pricingVersion, chunkIndex, chunkCount, rows}` in
+that order. `partitionCount` counts transmitted chunks. The server must accept
+this protocol, receipt replays, and finish omitted-row cleanup before completing
+an authoritative run.
+
+An abrupt process kill can leave `collector.lock` in the config directory. The
+next command reports the owner PID and exact path. Confirm that process has exited
+before removing only that lock file, then rerun sync. Never remove an active lock
+or the saved config to recover. Normal completion and handled failures release it.
+
 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.2.0",
+  "version": "0.3.1",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "license": "MIT",
   "author": "UsageMax",
@@ -18,10 +18,13 @@
     "usagemax": "src/cli.js"
   },
   "files": [
+    "src/archives.js",
     "src/cli.js",
     "src/core.js",
     "src/installation.js",
     "src/sources.js",
+    "src/transport.js",
+    "src/resume.js",
     "README.md",
     "LICENSE"
   ],

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,17 +9,20 @@ 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, scanPolicy, sourceSummary, validHttpsUrl } from "./core.js";
 import { stableInstallationId } from "./installation.js";
-import { CCUSAGE_VERSION, ccusageEnvironment, SOURCE_INVENTORY_VERSION, sourceInventory, SUPPORTED_SOURCES } from "./sources.js";
+import { requestSnapshot } from "./transport.js";
+import { resumeUpload, restartExpiredUpload, withConfigLock } from "./resume.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.1";
+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;
 
 function configDirectory() {
   if (process.env.USAGEMAX_CONFIG_DIR) return process.env.USAGEMAX_CONFIG_DIR;
@@ -31,6 +34,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 +53,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 +104,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] [--restart] [--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 +132,33 @@ 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) {
+  return requestSnapshot(snapshotEndpoint(config), config, operation, payload, { timeout });
+}
+
+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 +179,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 +198,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 +209,145 @@ 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");
+  if (args.includes("--restart") && !dryRun) {
+    restartExpiredUpload(config);
+    await writeConfig(config);
+  }
+  if (config.pendingSync) {
+    if (dryRun) {
+      const result = { ...config.pendingSync.result, dryRun: true, pendingRunId: config.pendingSync.runId };
+      process.stdout.write(json ? `${JSON.stringify(result)}\n` : `Dry run: saved run ${config.pendingSync.runId} awaits resume; no upload.\n`);
+      return result;
+    }
+    const result = await resumeUpload(config, { save: writeConfig, request: snapshotRequest, warn: warnVersion });
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : "Resumed and completed the saved sync. Run sync again to scan newer local changes.\n");
+    return result;
+  }
+  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
-    || !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`);
+  const { bootstrap, full, skip, inventoryStable } = scanPolicy(config, inventory, {
+    today, now: Date.now(), inventoryVersion: SOURCE_INVENTORY_VERSION, requestedFull, requestedArchives,
+  });
+  if (skip) {
+    const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: config.lastCoverage || "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}`);
-  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),
-    });
-    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;
-    config.lastSyncAt = new Date().toISOString();
-    await writeConfig(config);
+  const report = await ccusageJson(config, { env: recovery.env, full });
+  // ccusage v20 exposes aggregates, not proof that every discovered file was
+  // parsed. Inventory success alone cannot authorize destructive corrections.
+  const authoritative = false;
+  const legacySnapshotBootstrap = bootstrap
+    && 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,
+    complete: authoritative,
+    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: null,
+    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: authoritative ? regressions.length : 0,
+    protectedRegressions: authoritative ? 0 : regressions.length,
+    partitions: partitions.length,
+    scanned: true,
+    full,
+    coverage: authoritative ? "complete" : "partial",
+    coverageReason: "Parser does not certify complete source/day coverage; decreases and deletions are protected.",
+    range: { from: days[0], to: days.at(-1) },
+  };
+  if (requestedArchives) {
+    result.archives = recovery.archives;
+    result.unsupportedArchives = recovery.unsupported;
   }
-  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;
+  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} protected regression(s). ${result.coverageReason}\n`);
+    }
+    return result;
+  }
+  const requests = [{ operation: "begin", payload: {
+      runId,
+      mode: requestedArchives ? "archives" : full ? "full" : "incremental",
+      baselineMode: legacySnapshotBootstrap ? "adopt-current" : "apply",
+      sourceCount: sources.length,
+      partitionCount: partitions.length,
+      inventoryComplete: authoritative,
+      inventoryErrors: inventory.errors,
+      inventoryTruncated: inventory.truncated,
+      coverageStartDay: days[0],
+      coverageEndDay: days.at(-1),
+    } }];
+  for (let offset = 0; offset < sessions.length; offset += 100) {
+    requests.push({ operation: "sessions", payload: { runId, sessions: sessions.slice(offset, offset + 100) } });
+  }
+  for (let offset = 0; offset < partitions.length; offset += 10) {
+    requests.push({ operation: "partitions", payload: { runId, partitions: partitions.slice(offset, offset + 10) } });
+  }
+  requests.push({ operation: "complete", payload: { runId } });
+  const syncedAt = new Date().toISOString();
+  config.pendingSync = {
+    version: 1, runId, cursor: 0, requests, result,
+    checkpoint: {
+      snapshots: nextSnapshots, snapshotProtocolVersion: 2,
+      lastSyncAt: syncedAt, lastReconciledDay: today, lastSyncComplete: authoritative,
+      lastScanSucceeded: true, lastCoverage: result.coverage,
+      sourceInventoryVersion: SOURCE_INVENTORY_VERSION,
+      knownSources: [...new Set([...knownSources, ...inventory.sources, ...sources])].sort(),
+      sourceFingerprint: inventoryStable ? inventory.fingerprint : null,
+      ...(full ? { lastFullSyncAt: syncedAt } : {}),
+    },
+  };
+  config.lastSyncComplete = false;
   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`);
+  await resumeUpload(config, { save: writeConfig, request: snapshotRequest, warn: warnVersion });
+  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
+      ? `Completed ${partitions.length} usage chunk(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; prior counter dimensions were preserved because coverage is incomplete.\n`);
+    if (!authoritative) process.stdout.write(`${result.coverageReason}\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() {
@@ -231,23 +364,48 @@ async function status() {
   process.stdout.write(`Linked: ${config.deviceName || deviceLabel()}${config.profileHandle ? ` → @${config.profileHandle}` : ""}\n`);
   process.stdout.write(`Last sync: ${config.lastSyncAt || "never"}\n`);
   process.stdout.write(`Last full reconciliation: ${config.lastFullSyncAt || "never"}\n`);
+  if (config.pendingSync) process.stdout.write(`Pending sync: ${config.pendingSync.runId}; rerun sync to resume\n`);
   process.stdout.write(`Profile: ${config.profileUrl || "https://usagemax.com/account"}\n`);
 }
 
 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 +422,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() {
@@ -280,12 +451,16 @@ async function main() {
   const command = args[0] || "sync";
   if (["--help", "-h", "help"].includes(command)) return help();
   if (["--version", "-v"].includes(command)) return process.stdout.write(`${VERSION}\n`);
-  if (command === "link") return link(args.slice(1));
-  if (command === "sync") return sync(args.slice(1));
-  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 (["link", "sync", "status", "doctor", "unlink"].includes(command)) {
+    return withConfigLock(configDirectory(), async () => {
+      if (command === "link") return link(args.slice(1));
+      if (command === "sync") return sync(args.slice(1));
+      if (command === "status") return status();
+      if (command === "doctor") return doctor(args.slice(1));
+      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");
 }
@@ -186,7 +262,7 @@ export function buildDeltaPlan(report, priorSnapshots, deviceId, pricingVersion
         pricingVersion,
         status: "ok",
         state: "synced",
-        occurredAt: `${row.period}T12:00:00.000Z`,
+        occurredAt: `${row.period}T00:00:00.000Z`,
         completeness: "estimated",
       },
     });
@@ -195,6 +271,149 @@ 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();
+  // Carry forward history outside this scan's window. Only reconciled keys may
+  // replace or remove a checkpoint, including legacy three-part identities.
+  const nextSnapshots = Object.fromEntries([...priorRows].map(([key, row]) => [key, row.current]));
+  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();
+    let current = currentRow?.current ?? snapshotCounters();
+    const regressed = snapshotCounterFields.some((field) => current[field] < previous[field]);
+    if (regressed) regressions.push(key);
+    // A larger total can conceal a missing dimension. Keep the coherent prior
+    // vector (including in the checkpoint) until coverage is authoritative.
+    if (!complete && regressed) current = { ...previous };
+    if (!sameCounters(current, snapshotCounters())) nextSnapshots[key] = current;
+    else delete nextSnapshots[key];
+    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)}`),
+      // A daily aggregate has no exact event time. Use the start of its UTC day
+      // so today's partition is valid even when the collector runs before noon.
+      lastUsedAt: Date.parse(`${identity.period}T00: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 chunkCount = Math.ceil(wireRows.length / 100);
+    for (let chunkIndex = 0; chunkIndex < chunkCount; chunkIndex += 1) {
+      const rows = wireRows.slice(chunkIndex * 100, (chunkIndex + 1) * 100);
+      const payloadHash = sha256(JSON.stringify({ source, day, complete, pricingVersion, chunkIndex, chunkCount, rows }));
+      partitions.push({
+        partitionId: `${runId}:${sha256(partitionKey).slice(0, 24)}:${chunkIndex}`,
+        payloadHash,
+        revision,
+        source,
+        day,
+        complete,
+        pricingVersion,
+        chunkIndex,
+        chunkCount,
+        rows,
+      });
+    }
+  }
+  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)}`;
+}
+
+// Inventory stability certifies that repeating a successful parse is unnecessary;
+// it does not certify authority to remove server history. Bootstrap is separate.
+export function scanPolicy(config, inventory, { today, now, inventoryVersion, requestedFull = false, requestedArchives = false }) {
+  const knownSources = Array.isArray(config.knownSources) ? config.knownSources : [];
+  const lastFull = Date.parse(config.lastFullSyncAt || "");
+  const bootstrap = config.snapshotProtocolVersion !== 2;
+  const full = requestedFull || requestedArchives || bootstrap
+    || config.sourceInventoryVersion !== inventoryVersion
+    || !Number.isFinite(lastFull) || now - lastFull >= 7 * 24 * 60 * 60 * 1000
+    || inventory.sources.some((source) => !knownSources.includes(source));
+  const inventoryStable = inventory.complete && !inventory.truncated && inventory.errors === 0;
+  const skip = !config.pendingSync && !full && inventoryStable && config.lastScanSucceeded === true
+    && config.lastReconciledDay === today && config.sourceFingerprint === inventory.fingerprint;
+  return { bootstrap, full, skip, inventoryStable };
+}
+
+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/resume.js

@@ -0,0 +1,58 @@
+// A pending run is saved before network I/O. Persisting the acknowledged cursor
+// after each request permits replays when the response or local write is lost.
+// The server must receipt begin, chunks, sessions and complete idempotently.
+export async function resumeUpload(config, { save, request, warn = () => {} }) {
+  const pending = config.pendingSync;
+  if (!pending || pending.version !== 1 || !Array.isArray(pending.requests)) {
+    throw new Error("Invalid saved sync; preserve the config for recovery.");
+  }
+  try {
+    for (let index = pending.cursor; index < pending.requests.length; index += 1) {
+      const { operation, payload } = pending.requests[index];
+      const response = await request(config, operation, payload, operation === "partitions" ? 60_000 : 30_000);
+      warn(response);
+      pending.cursor = index + 1;
+      await save(config);
+    }
+    // Commit local baseline and remove the journal in the same atomic write.
+    const next = { ...config, ...pending.checkpoint };
+    delete next.pendingSync;
+    await save(next);
+    Object.assign(config, next);
+    delete config.pendingSync;
+    return { ...pending.result, resumed: true };
+  } catch (error) {
+    if (error?.code === "snapshot_run_expired") {
+      pending.terminalError = "snapshot_run_expired";
+      await save(config);
+      throw new Error("Saved upload expired. Run usagemax sync --restart to rescan retained history while preserving the last committed checkpoint. Already accepted usage remains on the server.", { cause: error });
+    }
+    throw new Error(`${error instanceof Error ? error.message : "Upload failed."} Run usagemax sync again to resume saved run ${pending.runId}; its payload and checkpoints have been retained.`, { cause: error });
+  }
+}
+
+export function restartExpiredUpload(config) {
+  if (config.pendingSync?.terminalError !== "snapshot_run_expired") throw new Error("Only an expired upload can restart. Run sync normally to resume or verify its status first.");
+  delete config.pendingSync;
+  config.lastFullSyncAt = undefined;
+  config.sourceFingerprint = null;
+}
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function withConfigLock(directory, action) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, "collector.lock");
+  try {
+    await writeFile(path, `${process.pid}\n`, { flag: "wx", mode: 0o600 });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const owner = (await readFile(path, "utf8").catch(() => "unknown")).trim();
+    throw new Error(`Collector config is locked by PID ${/^\d+$/.test(owner) ? owner : "unknown"}. If that process has exited, remove only ${path} and rerun sync; keep config.json for resume.`);
+  }
+  try {
+    return await action();
+  } finally {
+    await unlink(path);
+  }
+}

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

package/src/transport.js

@@ -0,0 +1,54 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+export function retryAfterMs(value, now = Date.now()) {
+  if (value == null || value === "") return 0;
+  if (/^\d+(?:\.\d+)?$/.test(value)) return Number(value) * 1000;
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, date - now) : 0;
+}
+
+// Only snapshot operations have server receipts. Never automatically replay a
+// one-use link request or apply this policy to arbitrary POST operations.
+export async function requestSnapshot(endpoint, config, operation, payload, {
+  timeout = 30_000, attempts = 5, maxDelayMs = 60_000,
+  fetchImpl = fetch, sleep = delay, random = Math.random, now = Date.now,
+} = {}) {
+  const body = JSON.stringify({ operation, ...payload });
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    let response;
+    let result;
+    let failure;
+    let retryable = true;
+    try {
+      response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { authorization: `Bearer ${config.token}`, "content-type": "application/json", "x-usagemax-device-id": config.deviceId },
+        body,
+        signal: AbortSignal.timeout(timeout),
+      });
+      result = await response.json().catch(() => null);
+      if (response.ok && result?.ok === true) return result;
+      retryable = response.ok || response.status === 429 || response.status >= 500
+        || (operation === "complete" && response.status === 409
+          && String(result?.error).toLowerCase() === "snapshot_run_incomplete");
+      const code = typeof result?.error === "string" ? result.error.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 80) : "invalid_response";
+      const advice = response.status === 401 ? " Link this computer again."
+        : response.status === 403 ? " Check workspace membership and collector permissions."
+        : response.status === 409 ? " The saved run needs reconciliation; do not delete its checkpoint or repeatedly start new runs."
+        : response.status === 400 ? " Check CLI/server protocol compatibility."
+        : "";
+      failure = new Error(`Snapshot ${operation} failed (HTTP ${response.status}: ${code}).${advice}`);
+      failure.code = code;
+    } catch {
+      failure = new Error(`Snapshot ${operation} could not reach UsageMax or timed out. Check your network connection.`);
+    }
+    if (!retryable || attempt + 1 >= attempts) throw failure;
+    const retryAfter = retryAfterMs(response?.headers?.get("retry-after"), now());
+    // Never retry earlier than the server's requested interval. Long backoffs
+    // remain durably resumable instead of blocking the command indefinitely.
+    if (retryAfter > maxDelayMs) throw new Error(`${failure.message} Server requested a longer wait; retry sync after ${Math.ceil(retryAfter / 1000)} seconds.`);
+    const jitter = Math.min(maxDelayMs, 1000 * 2 ** attempt) * (0.5 + random() * 0.5);
+    await sleep(Math.max(retryAfter, jitter));
+  }
+  throw new Error("Snapshot retry budget is empty.");
+}