usagemax 0.3.8 → 0.3.10

package/README.md

@@ -40,10 +40,14 @@ bunx usagemax sync --dry-run --explain
 bunx usagemax sync
 ```
 
-The CLI checks npm's `latest` dist-tag at most twice per day and never replaces
-itself silently. Run `usagemax update sync` to hand a command to the current
-release without typing `@latest`, or set `USAGEMAX_AUTO_UPDATE=1` for an
-explicit automatic handoff. Use `--no-update-check` or set
+The CLI checks npm's `latest` dist-tag at most twice per day. Run
+`usagemax update` to update a global installation through the package manager
+that launched it (Bun or npm). Add `--check` for a read-only check, or
+`--json` for automation. A command suffix such as `usagemax update sync` hands
+that command to the newest release without typing `@latest`. When `--check` or
+`--no-install` is present, the suffix is reported in JSON and never handed off;
+in a terminal, install the update and then run the printed command. Set
+`USAGEMAX_AUTO_UPDATE=1` for an explicit automatic handoff. Use `--no-update-check` or set
 `USAGEMAX_DISABLE_UPDATE_CHECK=1` in offline environments. Interactive
 terminals show a small stderr progress line; JSON,
 quiet, CI, and scheduled runs remain machine-readable and quiet.
@@ -78,9 +82,13 @@ usagemax status                  Show local link state
 usagemax doctor                  Check discovered sources
 usagemax report [ccusage args]   Run a local ccusage report
 usagemax token status            Diagnose a key piped on stdin
+usagemax telemetry test          Send one zero-token write-path smoke event
 usagemax service install        Opt into periodic OS checkpoints
 usagemax service status|run|uninstall
 usagemax unlink [--revoke]       Remove local credentials
+usagemax update                  Update the global CLI through Bun or npm
+usagemax update --check          Check without installing
+usagemax update sync             Run sync through the newest CLI release
 ```
 
 Useful options:
@@ -90,21 +98,29 @@ bunx usagemax sync --full                 # all retained local history
 bunx usagemax sync --archives             # one-time compressed-history recovery
 bunx usagemax sync --restart              # restart an expired saved upload
 bunx usagemax status --remote --json      # remote check; secret is never printed
+bunx usagemax telemetry test --json       # one observability event; no accounting change
 bunx usagemax doctor --deep --json        # parse and audit retained history
 bunx usagemax link UMX-… --no-sync        # link without uploading yet
 bunx usagemax --version --json             # print CLI and ccusage versions
-bunx usagemax update --json                # machine-readable release check
+bunx usagemax update --json                # update and return machine-readable status
+bunx usagemax update --check --json        # check without installing
 bunx usagemax unlink --json                # safe automation result; no secret output
 ```
 
 ## Sources and coverage
 
-UsageMax pins [ccusage v20.0.23](https://github.com/ccusage/ccusage/releases/tag/v20.0.23)
+UsageMax pins [ccusage v20.0.24](https://github.com/ccusage/ccusage/releases/tag/v20.0.24)
 and supports its 16 adapters: Amp, Claude Code, Codebuff, Codex, GitHub Copilot
 CLI, Factory Droid, Gemini CLI, Goose, Grok Build, Hermes, Kilo Code, Kimi CLI,
 OpenClaw, OpenCode, Pi, and Qwen Code. Named Pi-format stores are discovered as
 well.
 
+The collector explicitly requests ccusage's per-model breakdown so models used
+on the same day remain individually attributed instead of collapsing into a
+generic `mixed` row. This collector update triggers one full reconciliation of
+retained history from 2024-01-01 on the next sync; subsequent runs return to the
+normal incremental schedule.
+
 The collector follows the supported provider environment overrides and bounded
 home locations. It recognizes Claude Desktop sessions, `.cc-mirror`, renamed
 Claude/Codex backup folders, and supported Windows homes from WSL. In WSL, use
@@ -129,14 +145,14 @@ stdin; never pass it as an argument or put it in a URL:
 
 ```bash
 set +x
+set -o pipefail
 printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
   | bunx usagemax token status \
-      --device-id "$USAGEMAX_INSTALLATION_ID" \
       --json
 ```
 
-The `token status` command is included in CLI `0.3.8`. If a fresh environment
-still has an older npm tag, run `usagemax update token status` or
+The `token status` and `telemetry test` commands are included in CLI `0.3.10`.
+If a fresh environment still has an older npm tag, run `usagemax update token status` or
 `node packages/cli/src/cli.js token status` from this repository until the new
 package is published.
 
@@ -148,9 +164,10 @@ For a numeric-only result suitable for a smoke check:
 
 ```bash
 set +x
+set -o pipefail
 printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
   | bunx usagemax token status \
-      --device-id "$USAGEMAX_INSTALLATION_ID" --json \
+      --json \
   | jq -r '[.httpStatus, (if .ingestAuthorized then 1 else 0 end)] | @tsv'
 ```
 
@@ -166,10 +183,22 @@ installation does not match. A recognized key missing `telemetry:write` has
 `status: scope_missing`, `scopeStatus: missing_telemetry_write`, and
 `ingestAuthorized: false`.
 
-For a write-path smoke check, the root README includes a `curl` request that
-sends one `agent_state` event with all token counters and `costMicros` set to
-zero. It is observability-only: `agent_state` does not update accounting, and
-the probe may bind an otherwise unbound advanced key.
+For a write-path smoke check, run `usagemax telemetry test`. A linked install
+uses its stored collector key. For an advanced key, pipe it through stdin:
+
+```bash
+set +x
+printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
+  | bunx usagemax telemetry test \
+      --token-stdin \
+      --json
+```
+
+The command sends one `agent_state` event with all token counters and
+`costMicros` set to zero. It never sends prompts or raw logs. The event is
+observability-only and does not update accounting; the first accepted write
+binds an otherwise unbound advanced key to the CLI installation. Rejected
+credentials return a non-zero process exit code for reliable scripts.
 
 ## Privacy and resource use
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "keywords": [
     "usagemax",
@@ -33,6 +33,7 @@
   },
   "files": [
     "src/archives.js",
+    "src/ccusage.js",
     "src/cli.js",
     "src/core.js",
     "src/installation.js",
@@ -57,6 +58,6 @@
     "prepublishOnly": "npm test"
   },
   "dependencies": {
-    "ccusage": "20.0.23"
+    "ccusage": "20.0.24"
   }
 }

package/src/ccusage.js

@@ -0,0 +1,21 @@
+import { reportDateArgs } from "./core.js";
+
+/** Build the stable, model-complete ccusage command used by sync and doctor. */
+export function ccusageDailyArgs(config, options = {}) {
+  return [
+    "daily",
+    "--json",
+    "--offline",
+    "--mode",
+    "calculate",
+    "--timezone",
+    "UTC",
+    "--by-agent",
+    "--breakdown",
+    "--order",
+    "asc",
+    "--sections",
+    "daily,session",
+    ...reportDateArgs(config, options),
+  ];
+}

package/src/cli.js

@@ -11,14 +11,15 @@ import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 
 import { prepareArchiveRecovery } from "./archives.js";
-import { buildSessionPlan, buildSnapshotPlan, normalizeLinkCode, reportDateArgs, scanPolicy, sourceSummary, validHttpsUrl } from "./core.js";
+import { buildSessionPlan, buildSnapshotPlan, normalizeLinkCode, scanPolicy, sourceSummary, validHttpsUrl } from "./core.js";
+import { ccusageDailyArgs } from "./ccusage.js";
 import { stableInstallationId } from "./installation.js";
 import { createProgress } from "./progress.js";
 import { intervalMinutes, manageService, runScheduledSync } from "./service.js";
-import { collectorStatusView, requestCollectorStatus, requestSnapshot } from "./transport.js";
+import { collectorCanWrite, collectorStatusView, requestCollectorStatus, requestSnapshot, requestTelemetrySmokeTest } 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";
-import { checkForUpdate, runLatest } from "./updates.js";
+import { CCUSAGE_VERSION, ccusageEnvironment, ccusageHome, discoverProviderArchives, discoverWslWindowsHomeStatus, SOURCE_INVENTORY_VERSION, sourceInventory, SUPPORTED_SOURCES } from "./sources.js";
+import { checkForUpdate, packageManagerFor, runLatest, updateCommandWillRun, updateGlobal, updateRequest } from "./updates.js";
 
 // Make the short-lived collector recognizable in Activity Monitor and `ps`.
 // Windows may still display the underlying node.exe image name in Task Manager.
@@ -26,7 +27,7 @@ process.title = "UsageMax";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.3.8";
+const VERSION = "0.3.10";
 const PUBLIC_API_ORIGIN = "https://usagemax.com/api";
 const DEFAULT_LINK_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/link`;
 const DEFAULT_STATUS_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/status`;
@@ -111,7 +112,27 @@ function deviceLabel() {
   return "Computer";
 }
 
-function help() {
+function help(command) {
+  if (command) {
+    const usage = {
+      link: "Usage: usagemax link <one-use-code> [--no-sync] [--name <name>] [--json]",
+      sync: "Usage: usagemax sync [--full] [--archives] [--restart] [--dry-run] [--explain] [--json] [--quiet|--no-progress]",
+      status: "Usage: usagemax status [--remote] [--json] [--quiet|--no-progress]",
+      doctor: "Usage: usagemax doctor [--deep] [--json] [--quiet|--no-progress]",
+      "token status": "Usage: printf '%s' \"$USAGEMAX_COLLECTOR_TOKEN\" | usagemax token status [--device-id <uuid>] [--json] [--quiet|--no-progress]\nRead-only credential check; the token is read from stdin and never printed.",
+      "telemetry test": "Usage: usagemax telemetry test [--token-stdin] [--device-id <uuid>] [--json] [--quiet|--no-progress]\nSend one content-free zero-token observability event to verify the write path.",
+      service: "Usage: usagemax service install [--every <minutes>] | status | run | uninstall",
+      "service install": "Usage: usagemax service install [--every <minutes>]",
+      "service status": "Usage: usagemax service status",
+      "service run": "Usage: usagemax service run",
+      "service uninstall": "Usage: usagemax service uninstall",
+      update: "Usage: usagemax update [--check|--no-install] [--json]\n       usagemax update <command args> [--json]",
+      report: "Usage: usagemax report [...ccusage args]",
+      unlink: "Usage: usagemax unlink [--revoke] [--json]",
+    }[command];
+    process.stdout.write(`${usage || `No help is available for '${command}'. Run usagemax --help.`}\n`);
+    return;
+  }
   process.stdout.write(`UsageMax ${VERSION}\n\n`);
   process.stdout.write("Link aggregate coding-agent usage to your UsageMax profile.\n\n");
   process.stdout.write("Commands:\n");
@@ -125,18 +146,59 @@ function help() {
   process.stdout.write("  usagemax status                  Show local link status\n");
   process.stdout.write("           --remote [--json]        Verify the stored collector credential without printing it\n");
   process.stdout.write("           [--quiet|--no-progress]  Disable interactive progress output\n");
-  process.stdout.write("  usagemax token status [--device-id <uuid>] [--json]\n");
+  process.stdout.write("  usagemax token status [--device-id <uuid>] [--json] [--quiet|--no-progress]\n");
   process.stdout.write("                                  Diagnose a key piped on stdin; never pass it as an argument\n");
+  process.stdout.write("  usagemax telemetry test [--token-stdin] [--device-id <uuid>] [--json] [--quiet|--no-progress]\n");
+  process.stdout.write("                                  Send one zero-token observability smoke event\n");
   process.stdout.write("  usagemax service install [--every 15]\n");
   process.stdout.write("                                  Opt into lightweight OS-scheduled sync\n");
   process.stdout.write("  usagemax service status|run|uninstall\n");
   process.stdout.write("  usagemax doctor [--deep] [--json] [--quiet|--no-progress]\n");
   process.stdout.write("                                  Check source coverage; --deep parses full history\n");
-  process.stdout.write("  usagemax update [command args]  Check npm and optionally run the latest CLI\n");
-  process.stdout.write("           [--json]                  Emit machine-readable update status\n");
+  process.stdout.write("  usagemax update                  Update the global CLI through Bun or npm\n");
+  process.stdout.write("           [--check] [--json]       Check only or emit machine-readable status\n");
+  process.stdout.write("  usagemax update <command args>   Run a command through the latest CLI\n");
   process.stdout.write("  usagemax report [...args]        Run a local ccusage report\n");
   process.stdout.write("  usagemax unlink [--revoke]       Remove locally; --revoke also disables uploads\n");
   process.stdout.write("           [--json]                  Emit machine-readable unlink status\n");
+  process.stdout.write("\nAdd --help after a command for its usage.\n");
+}
+
+function validateCommandArgs(command, args) {
+  const specs = {
+    link: { flags: ["--no-sync", "--json", "--check-updates", "--no-update-check"], values: ["--name"], positional: 1 },
+    sync: { flags: ["--full", "--archives", "--restart", "--dry-run", "--explain", "--json", "--quiet", "--no-progress", "--check-updates", "--no-update-check"], values: [], positional: 0 },
+    status: { flags: ["--remote", "--json", "--quiet", "--no-progress"], values: [], positional: 0 },
+    doctor: { flags: ["--deep", "--json", "--quiet", "--no-progress", "--check-updates", "--no-update-check"], values: [], positional: 0 },
+    unlink: { flags: ["--revoke", "--json"], values: [], positional: 0 },
+    "token status": { flags: ["--json", "--quiet", "--no-progress"], values: ["--device-id"], positional: 0 },
+    "telemetry test": { flags: ["--token-stdin", "--json", "--quiet", "--no-progress"], values: ["--device-id"], positional: 0 },
+  };
+  if (command === "service") {
+    const action = args[0] || "status";
+    if (!["install", "status", "run", "uninstall"].includes(action)) throw new Error(`Unknown service action: ${action}. Run usagemax service --help.`);
+    command = `service ${action}`;
+    args = args.slice(1);
+    specs[command] = { flags: [], values: ["--config-dir", ...(action === "install" ? ["--every"] : [])], positional: 0 };
+  }
+  const spec = specs[command];
+  if (!spec) return;
+  let positional = 0;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith("-")) {
+      positional += 1;
+      continue;
+    }
+    if (spec.flags.includes(arg)) continue;
+    if (spec.values.includes(arg)) {
+      if (index + 1 >= args.length || args[index + 1].startsWith("-")) throw new Error(`${arg} requires a value.`);
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option for ${command}: ${arg}. Run usagemax ${command} --help.`);
+  }
+  if (positional > spec.positional) throw new Error(`Unexpected argument for ${command}. Run usagemax ${command} --help.`);
 }
 
 function ccusageCliPath() {
@@ -144,12 +206,10 @@ function ccusageCliPath() {
 }
 
 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");
+  const args = [ccusageCliPath(), ...ccusageDailyArgs(config, { full })];
   // 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.
-  args.push(...reportDateArgs(config, { full }));
   const { stdout } = await executeFile(process.execPath, args, {
     encoding: "utf8",
     maxBuffer: MAX_REPORT_BYTES,
@@ -431,6 +491,7 @@ function printRemoteStatus(view) {
   if (view.credentialType) process.stdout.write(`Type: ${view.credentialType}${view.writeOnly ? "; write-only" : ""}\n`);
   if (view.scopes?.length) process.stdout.write(`Scopes: ${view.scopes.join(", ")}\n`);
   if (view.scopeStatus) process.stdout.write(`Ingest scope: ${view.scopeStatus === "valid" ? "authorized" : "missing telemetry:write"}\n`);
+  if (typeof view.ingestAuthorized === "boolean") process.stdout.write(`Ingestion: ${view.ingestAuthorized ? "authorized" : "blocked"}\n`);
   if (view.deviceBinding) process.stdout.write(`Device binding: ${view.deviceBinding}\n`);
   if (view.profileHandle) process.stdout.write(`Profile: @${view.profileHandle}\n`);
   if (view.deviceName) process.stdout.write(`Computer: ${view.deviceName}\n`);
@@ -449,9 +510,11 @@ async function status(args = []) {
   if (!config) {
     if (json) {
       process.stdout.write(`${JSON.stringify({ linked: false, version: VERSION, ccusageVersion: CCUSAGE_VERSION, configPath: configPath(), remote: remote ? { status: "not_linked" } : undefined })}\n`);
+      if (remote) process.exitCode = 1;
       return;
     }
     process.stdout.write("Not linked. Open https://usagemax.com/account to connect this computer.\n");
+    if (remote) process.exitCode = 1;
     return;
   }
   const stableId = await stableInstallationId(configDirectory(), config.deviceId);
@@ -488,6 +551,7 @@ async function status(args = []) {
     }
     if (json) {
       process.stdout.write(`${JSON.stringify({ ...local, remote: remoteView })}\n`);
+      if (!collectorCanWrite(remoteView)) process.exitCode = 1;
       return;
     }
   }
@@ -504,6 +568,7 @@ async function status(args = []) {
   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`);
   if (remote) printRemoteStatus(remoteView);
+  if (remote && !collectorCanWrite(remoteView)) process.exitCode = 1;
 }
 
 async function readTokenFromStdin() {
@@ -524,6 +589,8 @@ async function readTokenFromStdin() {
 async function tokenStatus(args = []) {
   const requestedDeviceId = option(args, "--device-id");
   if (requestedDeviceId && !DEVICE_PATTERN.test(requestedDeviceId)) throw new Error("--device-id must be a UUID.");
+  const localConfig = await readConfig();
+  const deviceId = requestedDeviceId || localConfig?.deviceId;
   const json = args.includes("--json");
   const progress = createProgress({ json, quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
   progress.start("Checking the collector credential…");
@@ -538,7 +605,7 @@ async function tokenStatus(args = []) {
   const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
   try {
     if (!endpoint) throw new Error("USAGEMAX_STATUS_ENDPOINT must use HTTPS, except for localhost development.");
-    const result = await requestCollectorStatus(endpoint, { token, deviceId: requestedDeviceId });
+    const result = await requestCollectorStatus(endpoint, { token, deviceId });
     const view = collectorStatusView(result.httpStatus, result.body, token);
     progress.succeed("Collector credential checked.");
     if (json) process.stdout.write(`${JSON.stringify(view)}\n`);
@@ -546,6 +613,39 @@ async function tokenStatus(args = []) {
       process.stdout.write("Credential format: valid (umx_ + 64 lowercase hexadecimal characters)\n");
       printRemoteStatus(view);
     }
+    if (!collectorCanWrite(view)) process.exitCode = 1;
+  } catch (error) {
+    progress.stop();
+    throw error;
+  }
+}
+
+async function telemetryTest(args = []) {
+  const requestedDeviceId = option(args, "--device-id");
+  if (requestedDeviceId && !DEVICE_PATTERN.test(requestedDeviceId)) throw new Error("--device-id must be a UUID.");
+  const json = args.includes("--json");
+  const progress = createProgress({ json, quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
+  const localConfig = await readConfig();
+  let token;
+  try {
+    if (!localConfig || args.includes("--token-stdin")) {
+      token = await readTokenFromStdin();
+    } else {
+      token = localConfig.token;
+    }
+    const deviceId = requestedDeviceId || await stableInstallationId(configDirectory(), localConfig?.deviceId);
+    const configuredEndpoint = process.env.USAGEMAX_TELEMETRY_ENDPOINT || localConfig?.ingestUrl || `${PUBLIC_API_ORIGIN}/v1/telemetry/llm`;
+    const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
+    if (!endpoint) throw new Error("USAGEMAX_TELEMETRY_ENDPOINT must use HTTPS, except for localhost development.");
+    progress.start("Sending a zero-token telemetry smoke event…");
+    const result = await requestTelemetrySmokeTest(endpoint, { token, deviceId });
+    if (result.ok) progress.succeed("Telemetry smoke event accepted.");
+    else progress.fail("Telemetry smoke event was rejected.");
+    const summary = { ...result, deviceIdConfigured: true };
+    if (json) process.stdout.write(`${JSON.stringify(summary)}\n`);
+    else if (result.ok) process.stdout.write(`UsageMax accepted the smoke event (HTTP ${result.httpStatus}). No token or cost totals were recorded.\n`);
+    else process.stdout.write(`Telemetry check failed (${result.status}${result.httpStatus ? `, HTTP ${result.httpStatus}` : ""}). Run usagemax token status --device-id ${deviceId} to diagnose the credential.\n`);
+    if (!result.ok) process.exitCode = 1;
   } catch (error) {
     progress.stop();
     throw error;
@@ -560,6 +660,7 @@ async function doctor(args = []) {
     const config = await readConfig();
     const env = await ccusageEnvironment();
     const inventory = await sourceInventory({ env, home: ccusageHome(env) });
+    const windowsHomeDiscovery = await discoverWslWindowsHomeStatus();
     progress.update(`Found ${inventory.sources.length} source${inventory.sources.length === 1 ? "" : "s"} and ${inventory.files}${inventory.truncated ? "+" : ""} local data file${inventory.files === 1 ? "" : "s"}.`);
     const archives = await discoverProviderArchives({ env, home: ccusageHome(env) });
     const homes = String(env.USAGEMAX_DISCOVERED_HOMES || ccusageHome(env)).split(",").filter(Boolean);
@@ -569,6 +670,7 @@ async function doctor(args = []) {
       configPath: configPath(),
       linked: Boolean(config),
       homes,
+      windowsHomeDiscovery,
       detectedSources: inventory.sources,
       files: inventory.files,
       inventoryComplete: inventory.complete,
@@ -595,7 +697,16 @@ async function doctor(args = []) {
     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}; readable Windows provider homes are included automatically\n`);
+      process.stdout.write(`Windows home discovery: ${windowsHomeDiscovery.status}`);
+      if (windowsHomeDiscovery.selected.length) {
+        process.stdout.write(` (${windowsHomeDiscovery.selected.join(", ")})`);
+      }
+      process.stdout.write("\n");
+      if (windowsHomeDiscovery.status === "ambiguous") {
+        process.stdout.write("No Windows profile was selected to avoid mixing users. Set USAGEMAX_ADDITIONAL_HOME to the exact profile path you own, for example /mnt/c/Users/<your-profile>.\n");
+      } else if (windowsHomeDiscovery.status === "unavailable") {
+        process.stdout.write("No supported provider directory was found in readable Windows profiles. If your data is elsewhere, set USAGEMAX_ADDITIONAL_HOME to its exact profile path.\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`);
@@ -621,27 +732,78 @@ async function report(args) {
 }
 
 async function update(args = []) {
-  const json = args.includes("--json");
+  const { json, checkOnly, commandArgs, handoffArgs } = updateRequest(args);
   const check = await checkForUpdate(configDirectory(), VERSION, { force: true });
+  const commandWillRun = updateCommandWillRun({ latest: check.latest, checkOnly, commandArgs });
   if (!check.latest) {
-    const result = { version: VERSION, latest: null, newer: false, status: "unavailable" };
+    const result = {
+      version: VERSION,
+      latest: null,
+      newer: false,
+      status: "unavailable",
+      ...(commandArgs.length ? { command: `usagemax ${commandArgs.join(" ")}`, commandWillRun: false } : {}),
+    };
     process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${VERSION} · update check unavailable.\n`);
+    if (!json && commandArgs.length) process.stdout.write(`The requested command was not run because no release could be verified: \`usagemax ${commandArgs.join(" ")}\`.\n`);
     return;
   }
   if (!check.newer) {
-    const result = { version: VERSION, latest: check.latest, newer: false, status: "current" };
+    const result = {
+      version: VERSION,
+      latest: check.latest,
+      newer: false,
+      status: "current",
+      ...(commandArgs.length ? { command: `usagemax ${commandArgs.join(" ")}`, commandWillRun } : {}),
+    };
     process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${VERSION} is current.\n`);
+    if (commandWillRun) {
+      if (!json) process.stdout.write(`Launching UsageMax ${check.latest}…\n`);
+      return runLatest(handoffArgs);
+    }
+    if (!json && commandArgs.length) process.stdout.write(`Check-only: the requested command was not run: \`usagemax ${commandArgs.join(" ")}\`.\n`);
+    return;
+  }
+  if (handoffArgs.length) {
+    const result = {
+      version: VERSION,
+      latest: check.latest,
+      newer: true,
+      status: "available",
+      command: `usagemax ${commandArgs.join(" ")}`,
+      commandWillRun: true,
+    };
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${check.latest} is available (current ${VERSION}).\n`);
+    if (!json) process.stdout.write(`Launching UsageMax ${check.latest}…\n`);
+    return runLatest(handoffArgs);
+  }
+  const manager = packageManagerFor({ cliPath: process.argv[1], runtime: process.versions, env: process.env });
+  const installCommand = manager === "bun" ? "bun add --global usagemax@latest" : "npm install --global usagemax@latest";
+  const available = {
+    version: VERSION,
+    latest: check.latest,
+    newer: true,
+    status: "available",
+    manager,
+    installCommand,
+    ...(commandArgs.length ? { command: `usagemax ${commandArgs.join(" ")}`, commandWillRun: false } : {}),
+  };
+  if (checkOnly) {
+    process.stdout.write(json ? `${JSON.stringify(available)}\n` : `UsageMax CLI ${check.latest} is available (current ${VERSION}). Run \`${installCommand}\`.\n`);
+    if (!json && commandArgs.length) process.stdout.write(`Check-only: the requested command was not run. After installing, run \`usagemax ${commandArgs.join(" ")}\`.\n`);
     return;
   }
-  const result = { version: VERSION, latest: check.latest, newer: true, status: "available", command: "usagemax update sync" };
-  process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${check.latest} is available (current ${VERSION}).\n`);
-  const commandArgs = args.filter((arg) => arg !== "--check");
-  if (!commandArgs.length || args.includes("--check")) {
-    if (!json) process.stdout.write("Run `usagemax update sync` to hand off the next command to the latest npm release.\n");
+  if (!json) process.stdout.write(`Updating UsageMax ${VERSION} → ${check.latest} via ${manager}…\n`);
+  try {
+    await updateGlobal({ latest: check.latest, manager, quiet: json });
+  } catch (error) {
+    const result = { ...available, status: "failed", error: error instanceof Error ? error.message : String(error) };
+    if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
+    else process.stderr.write(`UsageMax update failed: ${result.error}\n`);
+    process.exitCode = 1;
     return;
   }
-  if (!json) process.stdout.write(`Launching UsageMax ${check.latest}…\n`);
-  return runLatest(commandArgs);
+  const result = { ...available, status: "updated", installedVersion: check.latest };
+  process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI is now ${check.latest}.\n`);
 }
 
 async function maybeUpdate(command, args) {
@@ -694,8 +856,21 @@ async function removeLink(args = []) {
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0] || "sync";
-  if (["--help", "-h", "help"].includes(command)) return help();
+  if (["--help", "-h", "help"].includes(command)) return help(args[1]);
   if (["--version", "-v"].includes(command)) return process.stdout.write(args.includes("--json") ? `${JSON.stringify({ version: VERSION, ccusageVersion: CCUSAGE_VERSION })}\n` : `${VERSION}\n`);
+  if (command === "report") return report(args.slice(1));
+  const invocationHelp = command === "update"
+    ? ["--help", "-h"].includes(args[1])
+    : args.slice(1).some((arg) => arg === "--help" || arg === "-h");
+  if (invocationHelp) {
+    const helpCommand = command === "token" && args[1] === "status" ? "token status"
+      : command === "telemetry" ? "telemetry test"
+        : command === "service" ? `service ${args[1] || "status"}` : command;
+    return help(helpCommand);
+  }
+  if (command === "token" && args[1] !== "status") throw new Error("Use `usagemax token status`; run usagemax --help for all commands.");
+  if (command === "telemetry" && args[1] !== "test") throw new Error("Use `usagemax telemetry test`; run usagemax --help for all commands.");
+  validateCommandArgs(command === "token" ? "token status" : command === "telemetry" ? "telemetry test" : command, command === "service" ? args.slice(1) : command === "token" || command === "telemetry" ? args.slice(2) : args.slice(1));
   if (command === "update") return update(args.slice(1));
   if (await maybeUpdate(command, args)) return;
   if (command === "service") {
@@ -718,8 +893,8 @@ async function main() {
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return;
   }
-  if (command === "report") return report(args.slice(1));
   if (command === "token" && args[1] === "status") return tokenStatus(args.slice(2));
+  if (command === "telemetry" && args[1] === "test") return telemetryTest(args.slice(2));
   if (["link", "sync", "status", "doctor", "unlink"].includes(command)) {
     return withConfigLock(configDirectory(), async () => {
       if (command === "link") return link(args.slice(1));

package/src/sources.js

@@ -3,8 +3,10 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 
-export const CCUSAGE_VERSION = "20.0.23";
-export const SOURCE_INVENTORY_VERSION = 3;
+export const CCUSAGE_VERSION = "20.0.24";
+// Reconcile retained history when the collector output contract changes, not
+// just when a source path is added. v4 enables explicit per-model breakdowns.
+export const SOURCE_INVENTORY_VERSION = 4;
 export const SUPPORTED_SOURCES = [
   "amp",
   "claude",
@@ -69,13 +71,24 @@ async function entries(value) {
 }
 
 async function providerBearingHome(home, pathApi) {
-  const markers = [".claude", ".codex", ".factory", ".gemini", ".openclaw", ".hermes", ".grok"];
+  // Only inspect known provider roots. Avoid treating generic profile folders
+  // (for example .local/share itself) as evidence that a Windows profile is
+  // relevant; that would make multi-user WSL selection noisy and unsafe.
+  const markers = [
+    ".claude", ".config/claude", ".codex", ".factory", ".gemini", ".openclaw", ".clawdbot", ".moltbot", ".moldbot", ".hermes", ".grok",
+    ".kimi", ".kimi-code", ".qwen", ".copilot", ".pi",
+    ".local/share/amp", ".local/share/goose", ".local/share/Block/goose", ".local/share/kilo", ".local/share/opencode",
+    "AppData/Roaming/Block/goose",
+    ".config/manicode", ".config/manicode-dev", ".config/manicode-staging",
+  ];
   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 [];
+export async function discoverWslWindowsHomeStatus({ env = process.env, platform = process.platform, pathApi = path } = {}) {
+  if (platform !== "linux" || !String(env.WSL_DISTRO_NAME ?? "").trim()) {
+    return { status: "not-applicable", candidates: [], selected: [] };
+  }
   const usersRoot = String(env.USAGEMAX_WSL_USERS_DIR ?? "/mnt/c/Users").trim();
   const candidates = [];
   for (const entry of await entries(usersRoot)) {
@@ -86,7 +99,8 @@ async function discoverWslWindowsHomes(env, platform, pathApi) {
   // 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 : [];
+  const status = candidates.length === 1 ? "discovered" : candidates.length > 1 ? "ambiguous" : "unavailable";
+  return { status, candidates, selected: status === "discovered" ? candidates : [] };
 }
 
 async function discoverBackupRoots(home, pathApi) {
@@ -229,15 +243,15 @@ export function sourceDefinitions({ env = process.env, home = ccusageHome(env),
     definitions.push(tree("pi", root, "jsonl"));
   }
 
-  const gooseRoot = String(env.GOOSE_PATH_ROOT ?? "").trim();
-  const gooseDatabases = gooseRoot
-    ? [join(gooseRoot, "data", "sessions", "sessions.db")]
+  const gooseRoots = envList(env, "GOOSE_PATH_ROOT", []);
+  const gooseDatabases = gooseRoots.length
+    ? gooseRoots.map((root) => join(root, "data", "sessions", "sessions.db"))
     : [
         join(home, ".local", "share", "goose", "sessions", "sessions.db"),
         join(home, "Library", "Application Support", "goose", "sessions", "sessions.db"),
         join(home, ".local", "share", "Block", "goose", "sessions", "sessions.db"),
       ];
-  if (!gooseRoot && String(env.APPDATA ?? "").trim()) {
+  if (!gooseRoots.length && String(env.APPDATA ?? "").trim()) {
     gooseDatabases.push(join(String(env.APPDATA).trim(), "Block", "goose", "data", "sessions", "sessions.db"));
   }
   for (const database of gooseDatabases) definitions.push(...db("goose", database));
@@ -260,7 +274,9 @@ export function sourceDefinitions({ env = process.env, home = ccusageHome(env),
     definitions.push(tree("qwen", join(root, "projects"), "jsonl"));
   }
 
-  definitions.push(tree("copilot", join(home, ".copilot", "otel"), "jsonl"));
+  for (const root of envList(env, "COPILOT_OTEL_DIR", [join(home, ".copilot", "otel")])) {
+    definitions.push(tree("copilot", root, "jsonl"));
+  }
   if (String(env.COPILOT_OTEL_FILE_EXPORTER_PATH ?? "").trim()) {
     definitions.push(file("copilot", String(env.COPILOT_OTEL_FILE_EXPORTER_PATH).trim()));
   }
@@ -283,8 +299,29 @@ export async function ccusageEnvironment({ env = process.env, platform = process
   const effective = { ...env };
   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 wslDiscovery = await discoverWslWindowsHomeStatus({ env: effective, platform, pathApi });
+  const wslHomes = wslDiscovery.selected;
   const additionalHomes = uniquePaths([...configuredHomes, ...wslHomes], pathApi).filter((item) => pathApi.normalize(item) !== pathApi.normalize(home));
+  const discoveredWindowsGooseRoots = [];
+  if (platform === "linux" && String(effective.WSL_DISTRO_NAME ?? "").trim()) {
+    for (const candidate of additionalHomes) {
+      const root = pathApi.join(candidate, "AppData", "Roaming", "Block", "goose");
+      if (await existsDirectory(root)) discoveredWindowsGooseRoots.push(root);
+    }
+  }
+  if (discoveredWindowsGooseRoots.length) {
+    const explicitRoots = commaList(effective.GOOSE_PATH_ROOT);
+    const defaultRoots = [
+      pathApi.join(home, ".local", "share", "goose"),
+      pathApi.join(home, "Library", "Application Support", "goose"),
+      pathApi.join(home, ".local", "share", "Block", "goose"),
+      ...(String(effective.APPDATA ?? "").trim() ? [pathApi.join(String(effective.APPDATA).trim(), "Block", "goose")] : []),
+    ];
+    effective.GOOSE_PATH_ROOT = uniquePaths([
+      ...(explicitRoots.length ? explicitRoots : defaultRoots),
+      ...discoveredWindowsGooseRoots,
+    ], pathApi).join(",");
+  }
   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();
@@ -318,6 +355,7 @@ export async function ccusageEnvironment({ env = process.env, platform = process
   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);
+  setDiscoveredList(effective, "COPILOT_OTEL_DIR", [pathApi.join(home, ".copilot", "otel")], additions([".copilot", "otel"]), pathApi);
 
   effective.USAGEMAX_DISCOVERED_HOMES = homes.join(",");
 

package/src/transport.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 
 export function retryAfterMs(value, now = Date.now()) {
@@ -15,6 +16,15 @@ const collectorStates = new Set(["active", "revoked", "workspace_disabled", "mem
 const deviceBindings = new Set(["unbound", "bound", "matched", "mismatch"]);
 const collectorTokenPattern = /umx_[a-f0-9]{64}/gi;
 
+export function collectorCanWrite(view) {
+  return view?.httpStatus === 200
+    && view?.status === "active"
+    && view?.credentialType === "collector"
+    && view?.scopeStatus === "valid"
+    && view?.ingestAuthorized === true
+    && view?.deviceBinding !== "mismatch";
+}
+
 function safeText(value, secret) {
   let text = value;
   if (secret) text = text.split(secret).join("[redacted]");
@@ -83,6 +93,72 @@ export async function requestCollectorStatus(endpoint, config, {
   return { httpStatus: response.status, body };
 }
 
+/** Send one zero-token observability event to prove the authenticated write path. */
+export async function requestTelemetrySmokeTest(endpoint, config, {
+  timeout = 15_000,
+  fetchImpl = fetch,
+  now = Date.now,
+  eventId = randomUUID(),
+} = {}) {
+  const eventKey = `usagemax-cli-test:${eventId}`;
+  const event = {
+    eventKey,
+    eventType: "agent_state",
+    provider: "usagemax-cli",
+    model: "usagemax-connectivity-check",
+    source: "usagemax-cli",
+    agentName: "UsageMax CLI",
+    status: "ok",
+    state: "connected",
+    occurredAt: now(),
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    reasoningTokens: 0,
+    totalTokens: 0,
+    costMicros: 0,
+    costBasis: "unknown",
+    completeness: "unknown",
+    accountingMode: "observability",
+    schemaVersion: 1,
+  };
+  const body = JSON.stringify({ events: [event] });
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${config.token}`,
+        "content-type": "application/json",
+        "x-usagemax-device-id": config.deviceId,
+        "idempotency-key": `usagemax-cli:${config.deviceId}:${eventId}`,
+      },
+      body,
+      cache: "no-store",
+      signal: AbortSignal.timeout(timeout),
+    });
+  } catch {
+    return { ok: false, status: "unavailable", httpStatus: null };
+  }
+  const result = record(await response.json().catch(() => null));
+  const ok = response.ok && result?.ok === true;
+  return {
+    ok,
+    status: ok ? "accepted" : response.status === 401 ? "unauthorized"
+      : response.status === 403 ? "forbidden"
+        : response.status === 409 ? "device_or_idempotency_conflict"
+          : response.status === 429 ? "rate_limited"
+            : response.status >= 500 ? "unavailable" : "rejected",
+    httpStatus: response.status,
+    ...(Number.isSafeInteger(result?.accepted) ? { accepted: result.accepted } : {}),
+    ...(Number.isSafeInteger(result?.duplicates) ? { duplicates: result.duplicates } : {}),
+    ...(typeof result?.replay === "boolean" ? { replay: result.replay } : {}),
+    observabilityOnly: true,
+    accountingUpdated: false,
+  };
+}
+
 // 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, {

package/src/updates.js

@@ -20,6 +20,24 @@ export function compareVersions(left, right) {
   return 0;
 }
 
+/** Parse the read-only and command-handoff options shared by `usagemax update`. */
+export function updateRequest(args = []) {
+  const json = args.includes("--json");
+  const checkOnly = args.includes("--check") || args.includes("--no-install");
+  const commandArgs = args.filter((arg) => !["--check", "--no-install", "--json"].includes(arg));
+  return {
+    json,
+    checkOnly,
+    commandArgs,
+    handoffArgs: commandArgs.length && !checkOnly ? [...commandArgs, ...(json ? ["--json"] : [])] : [],
+  };
+}
+
+/** A command suffix runs only after a usable npm release was confirmed. */
+export function updateCommandWillRun({ latest, checkOnly, commandArgs = [] }) {
+  return Boolean(latest && !checkOnly && commandArgs.length);
+}
+
 function cachePath(directory) {
   return join(directory, "update-check.json");
 }
@@ -76,19 +94,65 @@ export async function checkForUpdate(directory, currentVersion, { force = false,
   return { ...result, newer: compareVersions(result.latest, currentVersion) > 0 };
 }
 
-function runner() {
-  const override = process.env.USAGEMAX_PACKAGE_RUNNER?.trim();
+function runner({ manager, env = process.env, platform = process.platform }) {
+  const override = env.USAGEMAX_PACKAGE_RUNNER?.trim();
   if (override) return { command: override, prefix: [] };
-  if (process.env.npm_execpath) return { command: "npm", prefix: ["exec", "--yes"] };
-  return { command: "bunx", prefix: ["--bun"] };
+  if (manager === "bun") return { command: platform === "win32" ? "bunx.exe" : "bunx", prefix: ["--bun"] };
+  return { command: platform === "win32" ? "npm.cmd" : "npm", prefix: ["exec", "--yes"] };
+}
+
+/**
+ * Pick the package manager that owns the current invocation. Bun's global and
+ * ephemeral package paths are explicit; npm remains the safe default for a
+ * normal Node installation. The override is useful for managed environments
+ * where the executable is wrapped by a fleet-specific package manager.
+ */
+export function packageManagerFor({ cliPath = process.argv[1], runtime = process.versions, env = process.env } = {}) {
+  const override = String(env.USAGEMAX_PACKAGE_MANAGER || "").trim().toLowerCase();
+  if (override === "bun" || override === "npm") return override;
+  const normalizedPath = String(cliPath || "").replaceAll("\\", "/");
+  if (normalizedPath.includes("/.bun/install/") || runtime?.bun) return "bun";
+  if (env.npm_execpath || String(env.npm_config_user_agent || "").startsWith("npm/")) return "npm";
+  return "npm";
+}
+
+/** Install the current public release into the user's global package scope. */
+export async function updateGlobal({ latest = "latest", manager = packageManagerFor(), spawnImpl = spawn, env = process.env, quiet = false, platform = process.platform } = {}) {
+  if (manager !== "bun" && manager !== "npm") throw new Error(`Unsupported package manager: ${manager}`);
+  if (!/^\d+\.\d+\.\d+$/.test(String(latest)) && latest !== "latest") throw new Error("Invalid UsageMax release version.");
+  const command = manager === "bun" ? (platform === "win32" ? "bun.exe" : "bun") : (platform === "win32" ? "npm.cmd" : "npm");
+  const args = manager === "bun"
+    ? ["add", "--global", `usagemax@${latest}`]
+    : ["install", "--global", `usagemax@${latest}`];
+  const child = spawnImpl(command, args, {
+    // Do not leave child output pipes undrained: a JSON-mode package update
+    // can otherwise block once Bun/npm fills the operating-system pipe buffer.
+    stdio: quiet ? "ignore" : "inherit",
+    env: { ...env, NPM_CONFIG_UPDATE_NOTIFIER: "false" },
+  });
+  return new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (status) => {
+      const code = status ?? 1;
+      if (code === 0) resolve({ manager, command, args });
+      else reject(Object.assign(new Error(`${command} ${args.join(" ")} exited with code ${code}.`), { code: "USAGEMAX_UPDATE_FAILED", exitCode: code }));
+    });
+  });
 }
 
 /** Re-run a command through the current npm dist-tag without requiring @latest. */
-export async function runLatest(args, { spawnImpl = spawn } = {}) {
-  const selected = runner();
+export async function runLatest(args, {
+  spawnImpl = spawn,
+  cliPath = process.argv[1],
+  runtime = process.versions,
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const manager = packageManagerFor({ cliPath, runtime, env });
+  const selected = runner({ manager, env, platform });
   const child = spawnImpl(selected.command, [...selected.prefix, "usagemax@latest", "--", ...args], {
     stdio: "inherit",
-    env: { ...process.env, USAGEMAX_UPDATE_HANDOFF: "1" },
+    env: { ...env, USAGEMAX_UPDATE_HANDOFF: "1" },
   });
   const code = await new Promise((resolve, reject) => {
     child.once("error", reject);