usagemax 0.3.3 → 0.3.6

package/README.md

@@ -1,200 +1,218 @@
 # UsageMax CLI
 
-Connect aggregate coding-agent usage from every computer to one private UsageMax workspace.
+Connect the AI usage history on a computer to one private UsageMax workspace.
+The CLI is deliberately short-lived: it scans locally, uploads bounded
+aggregates, and exits.
 
-## Quick start
+[UsageMax](https://usagemax.com) · [Account](https://usagemax.com/account) ·
+[CLI documentation](https://usagemax.com/cli.md) ·
+[API contract](https://usagemax.com/openapi.json) ·
+[npm package](https://www.npmjs.com/package/usagemax) ·
+[source repository](https://github.com/SYMBaiEX/usagemax/tree/main/packages/cli)
+
+This package is the open-source `usagemax` command-line collector. It is not a
+JavaScript or Python SDK and does not expose an import API. For programmatic
+integrations, use the documented [OpenAPI contract](https://usagemax.com/openapi.json)
+or the public [agent surfaces](https://usagemax.com/?mode=agent); the package
+itself is intended to be invoked as a short-lived local process.
 
-1. Sign in at [usagemax.com/account](https://usagemax.com/account).
-2. Choose **Link a computer** and copy the one-time command.
-3. Run it in each operating-system environment that contains usage history:
+## Requirements
+
+- Node.js 20 or newer
+- Bun or npm
+- A UsageMax account and one link code per computer or WSL distribution
+
+## Quick start
 
 ```bash
+# Create a one-use code at https://usagemax.com/account.
 bunx usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
+
+# npm users can run the same one-shot command with npx.
+npx --yes usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
+
+# Preview, then upload changed local usage.
+bunx usagemax sync --dry-run --explain
+bunx usagemax sync
+```
+
+Agent-friendly checks can request JSON and keep the secret out of arguments and
+logs. This example only inspects local source coverage:
+
+```bash
+set +x
+bunx usagemax doctor --deep --json | jq '{complete, sources: [.sources[] | {name, status}]}'
 ```
 
-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. 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 JSON shape is intended for local automation; unsupported or unavailable
+sources remain explicitly reported rather than being inferred.
+
+The link code expires after ten minutes and is consumed once. The account-side
+computer name is retained. Pass `--name "Work laptop"` only when the current
+CLI should explicitly override it.
 
-The CLI stores the resulting collector key in a user-only config file, then runs
-a one-shot full-history sync. Running it again, changing the display name, or
-relinking an installation does not create a second device: the private random
-installation identity remains stable.
+Each installation gets a stable random ID and a new write-only collector key.
+Relinking or renaming that installation rotates the key without creating a
+second device. Do not link two installations to the same copied or
+network-mounted log tree; cross-installation duplicate history is ambiguous.
 
 ## Commands
 
+```text
+usagemax                         Sync changed local usage
+usagemax link <code> [options]   Link and sync a computer
+usagemax sync [options]          Reconcile local usage once
+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 service install        Opt into periodic OS checkpoints
+usagemax service status|run|uninstall
+usagemax unlink [--revoke]       Remove local credentials
+```
+
+Useful options:
+
 ```bash
-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 --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
+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 doctor --deep --json        # parse and audit retained history
+bunx usagemax link UMX-… --no-sync        # link without uploading yet
 ```
 
+## Sources and coverage
+
 UsageMax pins [ccusage v20.0.20](https://github.com/ccusage/ccusage/releases/tag/v20.0.20)
-and supports all 16 adapters shipped in that release: Amp, Claude Code, Codebuff,
-Codex, GitHub Copilot CLI, Factory Droid, Gemini CLI, Goose, Grok Build, Hermes,
-Kilo Code, Kimi CLI, OpenClaw, OpenCode, Pi, and Qwen Code. Named Pi-format
-stores configured through ccusage are also discovered.
-
-The source inventory follows ccusage's environment overrides, including
-`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `OPENCODE_DATA_DIR`, `AMP_DATA_DIR`,
-`DROID_SESSIONS_DIR`, `CODEBUFF_DATA_DIR`, `HERMES_HOME`, `PI_AGENT_DIR`,
-`GOOSE_PATH_ROOT`, `OPENCLAW_DIR`, `KILO_DATA_DIR`, `KIMI_DATA_DIR`,
-`QWEN_DATA_DIR`, `COPILOT_OTEL_FILE_EXPORTER_PATH`, `GEMINI_DATA_DIR`, and
-`GROK_HOME`. It also follows XDG Claude configuration and Windows Goose storage.
-
-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
-through UsageMax's native or OTLP endpoint, or through a future provider billing
-connector. UsageMax never invents usage that the source did not retain.
-
-## Privacy, correctness, and load
-
-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 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 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. 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.
-
-Use `USAGEMAX_CONFIG_DIR` to select another config directory. Development and
-self-hosted installations may set `USAGEMAX_LINK_ENDPOINT` before linking.
-
-## Optional automatic sync
-
-Automatic sync is **off by default**. Install a persistent CLI first (a bunx/npx
-cache can disappear), link the computer if needed, then opt in:
+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 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
+one collector for the Windows provider homes it can read instead of linking the
+same history again from Windows.
+
+Full scans catalog retained history from 2024 onward. `sync --archives` safely
+extracts supported Claude JSONL members into a private temporary directory and
+removes them after reconciliation. Normal runs do not crawl the whole disk or
+unpack archives.
+
+Cursor, Windsurf, Aider, Continue, Cline, Roo Code, hosted agents, and direct
+provider API traffic may not leave a stable local token ledger. Use UsageMax's
+native or OTLP/HTTP JSON contract, or a provider billing export, when local
+evidence is unavailable. Unsupported usage is never guessed.
+
+## Safe collector diagnostics
+
+An advanced key from **Advanced · custom telemetry collector** is a
+`umx_` prefix followed by 64 lowercase hexadecimal characters. Pipe it through
+stdin; never pass it as an argument or put it in a URL:
+
+```bash
+set +x
+printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
+  | bunx usagemax@latest token status \
+      --device-id "$USAGEMAX_INSTALLATION_ID" \
+      --json
+```
+
+The `token status` command is included in CLI `0.3.6`. If the public npm tag
+does not yet contain `0.3.6`, run `node packages/cli/src/cli.js token status`
+from the UsageMax repository until that release is published.
+
+The response is read-only and contains only status, type, scopes, profile/name,
+activation state, and a binding result of `unbound`, `bound`, `matched`, or
+`mismatch`. It never returns the token, hash, or raw authorized UUID.
+
+For a numeric-only result suitable for a smoke check:
+
+```bash
+set +x
+printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
+  | bunx usagemax@latest token status \
+      --device-id "$USAGEMAX_INSTALLATION_ID" --json \
+  | jq -r '[.httpStatus, (if .ingestAuthorized then 1 else 0 end)] | @tsv'
+```
+
+`200 1` is active and ingestion-authorized. `200 0` is recognized but blocked;
+inspect `status` and `scopeStatus` in the unfiltered JSON. `409 0` is a device
+binding mismatch. `401 0` means the format/key was rejected.
+
+New advanced keys are active immediately and need no activation or propagation.
+They bind on their first valid write. Linked CLI keys are bound during the link
+exchange. A `401` means the key format is invalid or the key is unknown,
+revoked, disabled, or from another deployment. A `409` means the supplied
+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.
+
+## Privacy and resource use
+
+The CLI uploads aggregate token counters, provider/model names, source names,
+dates, cost provenance, coverage state, and opaque SHA-256 session identities.
+It never uploads prompts, completions, source code, file contents, project
+paths, tool payloads, or provider credentials.
+
+Every sync is one-shot. A complete unchanged inventory can skip parsing and
+uploading; date rollover, new sources, a weekly reconciliation, `--full`, or
+`--archives` triggers the appropriate bounded scan. Decreases and deletions are
+protected while coverage is incomplete.
+
+Optional scheduling invokes the same process at low priority:
 
 ```bash
 bun install -g usagemax
 usagemax service install                 # approximately every 15 minutes
-usagemax service install --every 30      # change interval; 5–1440 minutes
-usagemax service status                  # scheduler reachability + last result
-usagemax service run                     # run now, respecting failure backoff
-usagemax service uninstall               # stop future jobs; retain account/data
+usagemax service install --every 30      # 5–1440 minutes
+usagemax service status
+usagemax service uninstall
 ```
 
-Uses a user LaunchAgent on macOS, a user systemd timer on Linux/WSL, and Task
-Scheduler on Windows. No admin/root access, resident daemon, file watcher,
-automatic package updates, or package downloads per run. Each job runs the normal
-incremental sync and exits. No-change runs skip parsing/uploading when the source
-inventory is complete and unchanged. The metadata inventory still costs disk I/O;
-an active or first/full-history scan costs more. This is periodic, not live telemetry.
-
-Schedules are spread by up to a minute. macOS/Linux jobs have reduced CPU/I/O
-priority. Windows jobs require a signed-in user and defer starting on battery.
-Jobs do not wake a sleeping computer. Linux needs a running systemd user manager;
-WSL must already be running with systemd enabled. UsageMax does not enable linger
-or keep a WSL distro alive. Missed intervals are not replayed as a backlog.
-
-The existing collector lock prevents overlapping uploads. Failures back off
-exponentially (up to six hours); manually running `usagemax sync` is available for
-diagnosis without waiting. `service-state.json` retains only the latest bounded
-status, timestamps, duration, and failure count, not raw logs or credentials.
-If a process was forcibly killed, inspect the PID reported by `sync` before
-removing its stale `collector.lock`; never delete `config.json` to retry.
-
-Re-run `service install` after upgrading/moving the CLI or changing source-path
-environment variables. Only an explicit allowlist of discovery settings is saved,
-not your shell's secrets. Jobs run from your home directory; repository-local
-`.ccusage/ccusage.json` configuration is not automatically used. Keep the runtime
-and global CLI installed. `service uninstall` leaves existing usage, link credentials,
-checkpoints, and last-run status intact; an in-flight sync may finish.
-
-## 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.
+The scheduler uses a user LaunchAgent on macOS, a user systemd timer on
+Linux/WSL, and Task Scheduler on Windows. It does not install a resident
+watcher, wake a sleeping computer, download packages per run, or replay missed
+intervals. Failures back off for up to six hours and the collector lock prevents
+overlapping syncs.
+
+## Recovery and checkpoints
+
+Uploads are idempotent and resumable. Before network I/O, the CLI saves a
+bounded journal containing the current run, ordered operations, and next
+checkpoint in the user-only config directory. If a process or network request
+fails, rerun:
+
+```bash
+usagemax sync
+```
+
+An expired run can be restarted with `sync --restart`; already accepted usage
+remains safe. Do not delete `config.json` to retry a failed upload. See the
+[operations runbook](https://github.com/SYMBaiEX/usagemax/blob/main/docs/operations-runbook.md)
+for recovery guidance.
+
+## Development
+
+From the repository root:
+
+```bash
+bun install
+bun run --cwd packages/cli test
+bun run --cwd packages/cli pack:check  # dry-run; lifecycle scripts disabled
+```
+
+`pack:check` only inspects the local archive shape. It does not publish, contact
+the npm registry, or establish that any registry tag contains this version.
+
+The package is MIT-licensed. See the included [LICENSE](LICENSE), the
+repository [LICENSE](https://github.com/SYMBaiEX/usagemax/blob/main/LICENSE),
+[security policy](https://github.com/SYMBaiEX/usagemax/blob/main/SECURITY.md),
+and [contributing guide](https://github.com/SYMBaiEX/usagemax/blob/main/CONTRIBUTING.md).

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "usagemax",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Link local coding-agent usage to your UsageMax profile",
+  "keywords": [
+    "usagemax",
+    "ai-usage",
+    "usage-analytics",
+    "coding-agents",
+    "agent-usage",
+    "telemetry",
+    "observability",
+    "usage",
+    "ccusage",
+    "claude-code",
+    "codex",
+    "privacy"
+  ],
   "license": "MIT",
   "author": "UsageMax",
   "homepage": "https://usagemax.com",
@@ -37,7 +51,7 @@
   },
   "scripts": {
     "test": "node --test src/*.test.js",
-    "pack:check": "npm pack --dry-run",
+    "pack:check": "npm pack --dry-run --ignore-scripts",
     "prepublishOnly": "npm test"
   },
   "dependencies": {

package/src/cli.js

@@ -14,17 +14,24 @@ import { prepareArchiveRecovery } from "./archives.js";
 import { buildSessionPlan, buildSnapshotPlan, normalizeLinkCode, reportDateArgs, scanPolicy, sourceSummary, validHttpsUrl } from "./core.js";
 import { stableInstallationId } from "./installation.js";
 import { intervalMinutes, manageService, runScheduledSync } from "./service.js";
-import { requestSnapshot } from "./transport.js";
+import { collectorStatusView, requestCollectorStatus, 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";
 
+// Make the short-lived collector recognizable in Activity Monitor and `ps`.
+// Windows may still display the underlying node.exe image name in Task Manager.
+process.title = "UsageMax";
+
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.3.3";
+const VERSION = "0.3.6";
 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`;
 const CONFIG_FILE = "config.json";
 const MAX_REPORT_BYTES = 100 * 1024 * 1024;
+const TOKEN_PATTERN = /^umx_[a-f0-9]{64}$/;
+const DEVICE_PATTERN = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
 
 function configDirectory() {
   if (process.env.USAGEMAX_CONFIG_DIR) return process.env.USAGEMAX_CONFIG_DIR;
@@ -51,18 +58,21 @@ function isLegacyDirectApi(config) {
 async function readConfig() {
   try {
     const parsed = JSON.parse(await readFile(configPath(), "utf8"));
-    if (!parsed || parsed.version !== 1 || !/^umx_[a-f0-9]{64}$/.test(parsed.token || "")) return null;
+    if (!parsed || parsed.version !== 1 || !TOKEN_PATTERN.test(parsed.token || "")) return null;
     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.statusUrl = `${PUBLIC_API_ORIGIN}/v1/devices/status`;
       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.statusUrl = validHttpsUrl(parsed.statusUrl, { allowLocalhost: true })
+      || parsed.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/status");
     parsed.revokeUrl = validHttpsUrl(parsed.revokeUrl, { allowLocalhost: true })
       || parsed.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/revoke");
     return parsed;
@@ -109,6 +119,9 @@ function help() {
   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("           --remote [--json]        Verify the stored collector credential without printing it\n");
+  process.stdout.write("  usagemax token status [--device-id <uuid>] [--json]\n");
+  process.stdout.write("                                  Diagnose a key piped on stdin; never pass it as an argument\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");
@@ -167,7 +180,8 @@ async function link(args) {
   const configuredEndpoint = process.env.USAGEMAX_LINK_ENDPOINT || DEFAULT_LINK_ENDPOINT;
   const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
   if (!endpoint) throw new Error("USAGEMAX_LINK_ENDPOINT must use HTTPS, except for localhost development.");
-  const name = (option(args, "--name") || deviceLabel()).trim().slice(0, 80);
+  const requestedName = option(args, "--name");
+  const name = requestedName?.trim().slice(0, 80) || undefined;
   const previous = await readConfig();
   const deviceId = await stableInstallationId(configDirectory(), previous?.deviceId);
   const headers = { "content-type": "application/json" };
@@ -175,33 +189,36 @@ async function link(args) {
   const response = await fetch(endpoint, {
     method: "POST",
     headers,
-    body: JSON.stringify({ code, name, platform: platform(), cliVersion: VERSION, deviceId }),
+    body: JSON.stringify({ code, ...(name ? { name, nameExplicit: true } : {}), platform: platform(), cliVersion: VERSION, deviceId }),
     signal: AbortSignal.timeout(15_000),
   });
   const body = await response.json().catch(() => ({}));
   if (!response.ok) throw new Error(body?.error === "invalid_or_expired_link_code" ? "That link code is invalid, expired, or already used." : "UsageMax could not link this computer.");
   const ingestUrl = validHttpsUrl(body.ingestUrl, { allowLocalhost: true });
   const snapshotUrl = validHttpsUrl(body.snapshotUrl, { allowLocalhost: true }) || ingestUrl?.replace(/\/v1\/telemetry\/llm$/, "/v2/usage/snapshots");
+  const statusUrl = validHttpsUrl(body.statusUrl, { allowLocalhost: true }) || ingestUrl?.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/status");
   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.");
+  if (!TOKEN_PATTERN.test(body.token || "") || !ingestUrl || !snapshotUrl || !statusUrl || !revokeUrl) throw new Error("UsageMax returned an invalid link response.");
   const profileHandle = typeof body.profileHandle === "string" ? body.profileHandle : undefined;
+  const savedName = typeof body.deviceName === "string" && body.deviceName.trim() ? body.deviceName.trim().slice(0, 80) : (name || deviceLabel());
   const sameAccount = Boolean(previous && previous.profileHandle && previous.profileHandle === profileHandle);
   const config = {
     version: 1,
     token: body.token,
     ingestUrl,
     snapshotUrl,
+    statusUrl,
     revokeUrl,
     profileUrl: validHttpsUrl(body.profileUrl) || "https://usagemax.com/account",
     profileHandle,
     deviceId,
-    deviceName: name,
+    deviceName: savedName,
     linkedAt: new Date().toISOString(),
     snapshots: sameAccount ? previous.snapshots : {},
   };
   await writeConfig(config);
   warnVersion(body);
-  process.stdout.write(`Linked ${name} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
+  process.stdout.write(`Linked ${savedName} 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");
     return;
@@ -352,9 +369,37 @@ async function syncPrepared(args, suppliedConfig, recovery) {
   return result;
 }
 
-async function status() {
+function collectorStatusEndpoint(config) {
+  return validHttpsUrl(process.env.USAGEMAX_STATUS_ENDPOINT, { allowLocalhost: true })
+    || validHttpsUrl(config.statusUrl, { allowLocalhost: true })
+    || config.ingestUrl.replace(/\/v1\/telemetry\/llm$/, "/v1/devices/status");
+}
+
+function printRemoteStatus(view) {
+  process.stdout.write(`Remote credential: ${view.status || "unavailable"}${view.httpStatus ? ` (HTTP ${view.httpStatus})` : ""}\n`);
+  if (view.reason) process.stdout.write(`${view.reason}\n`);
+  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 (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`);
+  if (view.platform || view.cliVersion) process.stdout.write(`Runtime: ${view.platform || "unknown"}${view.cliVersion ? ` · CLI ${view.cliVersion}` : ""}\n`);
+  if (view.activation) process.stdout.write(`Activation: ${view.activation}\n`);
+  if (view.expiresAt === null) process.stdout.write("Expiration: none\n");
+  if (view.lastSuccessAt) process.stdout.write(`Last accepted write: ${new Date(view.lastSuccessAt).toISOString()}\n`);
+  if (view.lastFailureAt) process.stdout.write(`Last rejected write: ${new Date(view.lastFailureAt).toISOString()}${view.lastFailureCode ? ` · ${view.lastFailureCode}` : ""}\n`);
+}
+
+async function status(args = []) {
   const config = await readConfig();
+  const remote = args.includes("--remote");
+  const json = args.includes("--json");
   if (!config) {
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ linked: false, remote: remote ? { status: "not_linked" } : undefined })}\n`);
+      return;
+    }
     process.stdout.write("Not linked. Open https://usagemax.com/account to connect this computer.\n");
     return;
   }
@@ -363,11 +408,70 @@ async function status() {
     config.deviceId = stableId;
     await writeConfig(config);
   }
+  const local = {
+    linked: true,
+    deviceName: config.deviceName || deviceLabel(),
+    profileHandle: config.profileHandle || null,
+    deviceIdConfigured: Boolean(config.deviceId),
+    lastSyncAt: config.lastSyncAt || null,
+    lastFullSyncAt: config.lastFullSyncAt || null,
+    pendingSync: config.pendingSync?.runId || null,
+    profileUrl: config.profileUrl || "https://usagemax.com/account",
+  };
+  let remoteView;
+  if (remote) {
+    try {
+      const result = await requestCollectorStatus(collectorStatusEndpoint(config), config);
+      remoteView = collectorStatusView(result.httpStatus, result.body, config.token);
+    } catch (error) {
+      remoteView = { tokenFormat: "valid", status: "unavailable", reason: error instanceof Error ? error.message : "Collector status unavailable." };
+    }
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ ...local, remote: remoteView })}\n`);
+      return;
+    }
+  }
+  if (json) {
+    process.stdout.write(`${JSON.stringify(local)}\n`);
+    return;
+  }
   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`);
+  if (remote) printRemoteStatus(remoteView);
+}
+
+async function readTokenFromStdin() {
+  if (process.stdin.isTTY) throw new Error("Pipe the collector token on stdin; never pass it as a command-line argument.");
+  // fs.promises.readFile does not consistently accept file descriptor 0
+  // across the Node versions supported by the CLI. Read the pipe as a stream
+  // instead, and bound it so an accidental large stdin cannot be buffered.
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += String(chunk);
+    if (input.length > 256) throw new Error("stdin did not contain a valid UsageMax collector token.");
+  }
+  const token = input.trim();
+  if (!TOKEN_PATTERN.test(token)) throw new Error("stdin did not contain a valid UsageMax collector token (expected umx_ plus 64 lowercase hexadecimal characters).");
+  return token;
+}
+
+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 token = await readTokenFromStdin();
+  const configuredEndpoint = process.env.USAGEMAX_STATUS_ENDPOINT || DEFAULT_STATUS_ENDPOINT;
+  const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
+  if (!endpoint) throw new Error("USAGEMAX_STATUS_ENDPOINT must use HTTPS, except for localhost development.");
+  const result = await requestCollectorStatus(endpoint, { token, deviceId: requestedDeviceId });
+  const view = collectorStatusView(result.httpStatus, result.body, token);
+  if (args.includes("--json")) process.stdout.write(`${JSON.stringify(view)}\n`);
+  else {
+    process.stdout.write("Credential format: valid (umx_ + 64 lowercase hexadecimal characters)\n");
+    printRemoteStatus(view);
+  }
 }
 
 async function doctor(args = []) {
@@ -436,8 +540,10 @@ async function removeLink(args = []) {
     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 }),
+      headers: {
+        authorization: `Bearer ${config.token}`,
+        "x-usagemax-device-id": config.deviceId,
+      },
       signal: AbortSignal.timeout(15_000),
     });
     if (!response.ok) throw new Error("UsageMax could not revoke this collector. It remains linked locally.");
@@ -474,11 +580,12 @@ async function main() {
     return;
   }
   if (command === "report") return report(args.slice(1));
+  if (command === "token" && args[1] === "status") return tokenStatus(args.slice(2));
   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 === "status") return status(args.slice(1));
       if (command === "doctor") return doctor(args.slice(1));
       return removeLink(args.slice(1));
     });

package/src/service.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { access, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { access, chmod, copyFile, mkdir, readFile, readdir, realpath, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { promisify } from "node:util";
@@ -27,13 +27,73 @@ export function assertDurablePath(path) {
   }
 }
 
+export function brandedRuntimePath(directory, platform = process.platform) {
+  if (platform !== "darwin" && platform !== "win32") return null;
+  return platform === "win32"
+    ? join(directory, "runtime", "UsageMax.exe")
+    : join(directory, "runtime", "bin", "UsageMax");
+}
+
+/**
+ * Give scheduled jobs a stable product-facing image name on platforms where
+ * the JavaScript runtime otherwise appears as `node` in process browsers.
+ * The copied runtime is intentionally private to this installation and is
+ * refreshed on every service install, so upgrading Node or UsageMax never
+ * leaves the scheduler pointing at an ephemeral cache path.
+ */
+export async function ensureBrandedRuntime(directory, executable, platform = process.platform) {
+  const target = brandedRuntimePath(directory, platform);
+  if (!target) return executable;
+  const source = await realpath(executable);
+  const runtimeBinDirectory = dirname(target);
+  if (source === target) return target;
+  await mkdir(runtimeBinDirectory, { recursive: true, mode: 0o700 });
+  const temporary = join(runtimeBinDirectory, `.${platform === "win32" ? "UsageMax.exe" : "UsageMax"}.${randomUUID()}.tmp`);
+  try {
+    await copyFile(source, temporary);
+    if (platform !== "win32") await chmod(temporary, 0o700);
+    await rename(temporary, target);
+    if (platform === "darwin") {
+      // Homebrew Node uses @rpath/libnode.<n>.dylib next to its bin folder;
+      // the official Node distribution is self-contained. Copy only adjacent
+      // dylibs when they exist, keeping both layouts runnable.
+      const sourceLibraryDirectory = resolve(dirname(source), "../lib");
+      const runtimeLibraryDirectory = resolve(runtimeBinDirectory, "../lib");
+      const sourceLibraries = await readdir(sourceLibraryDirectory, { withFileTypes: true }).catch((error) => {
+        if (error?.code === "ENOENT") return [];
+        throw error;
+      });
+      const libraries = sourceLibraries.filter((entry) => entry.isFile() && entry.name.endsWith(".dylib"));
+      if (libraries.length) await mkdir(runtimeLibraryDirectory, { recursive: true, mode: 0o700 });
+      for (const library of libraries) {
+        const libraryTemporary = join(runtimeLibraryDirectory, `.${library.name}.${randomUUID()}.tmp`);
+        try {
+          await copyFile(join(sourceLibraryDirectory, library.name), libraryTemporary);
+          await chmod(libraryTemporary, 0o700);
+          await rename(libraryTemporary, join(runtimeLibraryDirectory, library.name));
+        } finally {
+          await unlink(libraryTemporary).catch(() => undefined);
+        }
+      }
+    }
+  } finally {
+    await unlink(temporary).catch(() => undefined);
+  }
+  return target;
+}
+
 export function servicePlan({ directory, executable, cli, minutes = 15, platform = process.platform, home = homedir(), uid = process.getuid?.(), configHome = join(home, ".config"), now = Date.now() }) {
   minutes = intervalMinutes(minutes);
   for (const path of [directory, executable, cli, home, configHome]) if (/[\x00-\x1f]/.test(path)) throw new Error("Scheduler paths cannot contain control characters.");
   const id = createHash("sha256").update(directory).digest("hex").slice(0, 12);
-  const name = `com.usagemax.sync.${id}`;
+  const name = `com.UsageMax.sync.${id}`;
   const args = [cli, "service", "run", "--config-dir", directory];
-  const command = [executable, ...args];
+  // Linux can execute the published shebang entry point directly. macOS and
+  // Windows launch the staged UsageMax runtime so process browsers do not show
+  // the generic JavaScript runtime image name.
+  const command = platform === "win32" || platform === "darwin"
+    ? [executable, ...args]
+    : [cli, "service", "run", "--config-dir", directory];
   if (platform === "darwin") {
     const file = join(home, "Library", "LaunchAgents", `${name}.plist`);
     const domain = `gui/${uid}`;
@@ -88,7 +148,8 @@ export async function manageService(action, { directory, cli, minutes, env = pro
   const settingsPath = join(directory, "service.json");
   const settings = await readJson(settingsPath);
   const configHome = settings?.configHome || env.XDG_CONFIG_HOME || join(home, ".config");
-  const plan = servicePlan({ directory, cli, executable: process.execPath, minutes: minutes ?? settings?.minutes ?? 15, configHome, home, platform });
+  const executable = brandedRuntimePath(directory, platform) || process.execPath;
+  const plan = servicePlan({ directory, cli, executable, minutes: minutes ?? settings?.minutes ?? 15, configHome, home, platform });
   if (action === "status") {
     let registered = false;
     try { await executeCommand(plan.probe); registered = true; } catch { /* Not installed, inactive, or unavailable. */ }
@@ -105,8 +166,9 @@ export async function manageService(action, { directory, cli, minutes, env = pro
   }
   if (action !== "install") throw new Error("Use service install [--every 15], status, run, or uninstall.");
   assertDurablePath(await realpath(cli));
-  assertDurablePath(await realpath(process.execPath));
+  if (platform === "darwin" || platform === "win32") assertDurablePath(await realpath(process.execPath));
   await access(join(directory, "config.json"));
+  if (platform === "darwin" || platform === "win32") await ensureBrandedRuntime(directory, process.execPath, platform);
   // Check the user manager before writing anything. WSL without systemd fails clearly.
   if (plan.backend === "systemd") await executeCommand(["systemctl", ["--user", "show-environment"]]);
   if (settings) {

package/src/transport.js

@@ -7,6 +7,82 @@ export function retryAfterMs(value, now = Date.now()) {
   return Number.isFinite(date) ? Math.max(0, date - now) : 0;
 }
 
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+const collectorStates = new Set(["active", "revoked", "workspace_disabled", "membership_inactive", "device_mismatch", "scope_missing"]);
+const deviceBindings = new Set(["unbound", "bound", "matched", "mismatch"]);
+const collectorTokenPattern = /umx_[a-f0-9]{64}/gi;
+
+function safeText(value, secret) {
+  let text = value;
+  if (secret) text = text.split(secret).join("[redacted]");
+  return text.replace(collectorTokenPattern, "[redacted]").slice(0, 160);
+}
+
+// Only copy the documented diagnostic projection. This keeps a compromised or
+// misconfigured endpoint from echoing a collector secret through the CLI.
+export function collectorStatusView(httpStatus, value, secret) {
+  const body = record(value);
+  const view = { tokenFormat: "valid", httpStatus };
+  if (!body) {
+    return {
+      ...view,
+      status: httpStatus === 401 ? "rejected" : "unavailable",
+      reason: httpStatus === 401
+        ? "UsageMax did not accept this collector token. It may be unknown, revoked, disabled, or from another deployment."
+        : "UsageMax returned no machine-readable collector status.",
+    };
+  }
+
+  if (typeof body.status === "string" && collectorStates.has(body.status)) view.status = body.status;
+  if (body.credentialType === "collector") view.credentialType = body.credentialType;
+  if (body.writeOnly === true) view.writeOnly = true;
+  if (body.activation === "not_required") view.activation = body.activation;
+  if (body.expiresAt === null) view.expiresAt = null;
+  if (Array.isArray(body.scopes)) view.scopes = body.scopes.filter((scope) => typeof scope === "string").slice(0, 16);
+  if (body.scopeStatus === "valid" || body.scopeStatus === "missing_telemetry_write") view.scopeStatus = body.scopeStatus;
+  if (typeof body.ingestAuthorized === "boolean") view.ingestAuthorized = body.ingestAuthorized;
+  if (typeof body.deviceBinding === "string" && deviceBindings.has(body.deviceBinding)) view.deviceBinding = body.deviceBinding;
+  for (const key of ["profileHandle", "deviceName", "platform", "cliVersion", "lastFailureCode"]) {
+    if (typeof body[key] === "string") view[key] = safeText(body[key], secret);
+  }
+  for (const key of ["createdAt", "lastSeenAt", "lastSuccessAt", "lastFailureAt"]) {
+    if (typeof body[key] === "number" && Number.isSafeInteger(body[key])) view[key] = body[key];
+    else if (body[key] === null) view[key] = null;
+  }
+  if (!view.status) {
+    view.status = httpStatus === 401 ? "rejected" : "unavailable";
+    view.reason = httpStatus === 401
+      ? "UsageMax did not accept this collector token. It may be unknown, revoked, disabled, or from another deployment."
+      : "UsageMax returned an incomplete collector status.";
+  }
+  return view;
+}
+
+export async function requestCollectorStatus(endpoint, config, {
+  timeout = 15_000,
+  fetchImpl = fetch,
+} = {}) {
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "GET",
+      headers: {
+        authorization: `Bearer ${config.token}`,
+        ...(config.deviceId ? { "x-usagemax-device-id": config.deviceId } : {}),
+      },
+      cache: "no-store",
+      signal: AbortSignal.timeout(timeout),
+    });
+  } catch {
+    throw new Error("Collector status could not reach UsageMax or timed out. Check your network connection.");
+  }
+  const body = await response.json().catch(() => null);
+  return { httpStatus: response.status, body };
+}
+
 // 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, {