usagemax 0.3.2 → 0.3.6

package/README.md

@@ -1,159 +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
 ```
 
-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.
+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 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.
+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.
+
+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.
-
-## 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.
+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      # 5–1440 minutes
+usagemax service status
+usagemax service uninstall
+```
+
+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.2",
+  "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",
@@ -25,6 +39,7 @@
     "src/sources.js",
     "src/transport.js",
     "src/resume.js",
+    "src/service.js",
     "README.md",
     "LICENSE"
   ],
@@ -36,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

@@ -8,21 +8,30 @@ import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import process from "node:process";
 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 { stableInstallationId } from "./installation.js";
-import { requestSnapshot } from "./transport.js";
+import { intervalMinutes, manageService, runScheduledSync } from "./service.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.2";
+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;
@@ -49,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;
@@ -107,6 +119,12 @@ 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");
   process.stdout.write("  usagemax doctor [--deep] [--json]\n");
   process.stdout.write("                                  Check source coverage; --deep parses full history\n");
   process.stdout.write("  usagemax report [...args]        Run a local ccusage report\n");
@@ -127,6 +145,8 @@ async function ccusageJson(config, { full = false, env } = {}) {
   const { stdout } = await executeFile(process.execPath, args, {
     encoding: "utf8",
     maxBuffer: MAX_REPORT_BYTES,
+    timeout: 10 * 60 * 1000,
+    killSignal: "SIGKILL",
     env: { ...(env || await ccusageEnvironment()), NO_COLOR: "1" },
   });
   return JSON.parse(stdout);
@@ -160,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" };
@@ -168,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;
@@ -345,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;
   }
@@ -356,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 = []) {
@@ -429,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.");
@@ -446,12 +559,33 @@ async function main() {
   const command = args[0] || "sync";
   if (["--help", "-h", "help"].includes(command)) return help();
   if (["--version", "-v"].includes(command)) return process.stdout.write(`${VERSION}\n`);
+  if (command === "service") {
+    const action = args[1] || "status";
+    const directory = option(args, "--config-dir") || configDirectory();
+    process.env.USAGEMAX_CONFIG_DIR = directory;
+    let result;
+    if (action === "run") {
+      result = await runScheduledSync(directory, () => withConfigLock(directory, () => sync(["--json"])));
+      if (result.status === "error") process.exitCode = 1;
+    } else if (action === "status") {
+      result = await manageService(action, { directory, cli: fileURLToPath(import.meta.url) });
+    } else {
+      result = await withConfigLock(directory, async () => {
+        if (action === "install" && !await readConfig()) throw new Error("Link this computer before enabling automatic sync.");
+        if (args.includes("--every") && option(args, "--every") === undefined) throw new Error("--every requires a number of minutes.");
+        return manageService(action, { directory, cli: fileURLToPath(import.meta.url), minutes: args.includes("--every") ? intervalMinutes(option(args, "--every")) : undefined });
+      });
+    }
+    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 (["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/resume.js

@@ -48,7 +48,9 @@ export async function withConfigLock(directory, action) {
   } catch (error) {
     if (error.code !== "EEXIST") throw error;
     const owner = (await readFile(path, "utf8").catch(() => "unknown")).trim();
-    throw new Error(`Collector config is locked by PID ${/^\d+$/.test(owner) ? owner : "unknown"}. If that process has exited, remove only ${path} and rerun sync; keep config.json for resume.`);
+    const busy = new Error(`Collector config is locked by PID ${/^\d+$/.test(owner) ? owner : "unknown"}. If that process has exited, remove only ${path} and rerun sync; keep config.json for resume.`);
+    busy.code = "USAGEMAX_BUSY";
+    throw busy;
   }
   try {
     return await action();

package/src/service.js

@@ -0,0 +1,212 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+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";
+
+const execute = promisify(execFile);
+const ENV_KEYS = ["PATH", "XDG_CONFIG_HOME", "APPDATA", "LOCALAPPDATA", "WSL_DISTRO_NAME", "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", "GEMINI_DATA_DIR", "GROK_HOME", "COPILOT_OTEL_FILE_EXPORTER_PATH", "USAGEMAX_ADDITIONAL_HOME", "USAGEMAX_WSL_USERS_DIR", "CCUSAGE_MODEL_ALIASES"];
+const xml = (value) => String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+const unitQuote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%").replaceAll("$", () => "$$")}"`;
+const windowsQuote = (value) => `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`;
+
+export function intervalMinutes(value = 15) {
+  if (!/^\d+$/.test(String(value)) || Number(value) < 5 || Number(value) > 1440) throw new Error("--every must be an integer from 5 to 1440 minutes.");
+  return Number(value);
+}
+
+export function capturedEnvironment(env) {
+  // Never persist the whole shell environment: it can contain provider secrets.
+  return Object.fromEntries(ENV_KEYS.filter((key) => typeof env[key] === "string").map((key) => [key, env[key]]));
+}
+
+export function assertDurablePath(path) {
+  if (!isAbsolute(path) || /[\x00-\x1f]/.test(path) || /\/(?:_npx|cache|fnm_multishells)\//i.test(path.replaceAll("\\", "/"))) {
+    throw new Error("Automatic sync needs a persistent installation. Run `bun install -g usagemax`, then `usagemax service install`; do not install a scheduler from bunx/npx caches.");
+  }
+}
+
+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 args = [cli, "service", "run", "--config-dir", directory];
+  // 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}`;
+    return { backend: "launchd", name, files: [[file, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict><key>Label</key><string>${name}</string>
+<key>ProgramArguments</key><array>${command.map((s) => `<string>${xml(s)}</string>`).join("")}</array>
+<key>WorkingDirectory</key><string>${xml(home)}</string>
+<key>StartInterval</key><integer>${minutes * 60 + parseInt(id.slice(0, 4), 16) % 60}</integer>
+<key>ProcessType</key><string>Background</string><key>Nice</key><integer>10</integer>
+<key>LowPriorityIO</key><true/><key>StandardOutPath</key><string>/dev/null</string>
+<key>StandardErrorPath</key><string>/dev/null</string></dict></plist>
+`]], probe: ["launchctl", ["print", `${domain}/${name}`]], install: [["launchctl", ["bootstrap", domain, file]], ["launchctl", ["enable", `${domain}/${name}`]]], uninstall: [["launchctl", ["bootout", `${domain}/${name}`]]] };
+  }
+  if (platform === "linux") {
+    const root = join(configHome, "systemd", "user");
+    return { backend: "systemd", name, files: [
+      [join(root, `${name}.service`), `[Unit]\nDescription=UsageMax incremental usage sync\n[Service]\nType=oneshot\nExecStart=${command.map(unitQuote).join(" ")}\nWorkingDirectory=${unitQuote(home)}\nNice=10\nIOSchedulingClass=idle\nTimeoutStartSec=infinity\nStandardOutput=null\nStandardError=null\n`],
+      [join(root, `${name}.timer`), `[Unit]\nDescription=UsageMax automatic sync\n[Timer]\nOnActiveSec=1m\nOnUnitInactiveSec=${minutes}m\nRandomizedDelaySec=60\nAccuracySec=30s\n[Install]\nWantedBy=timers.target\n`],
+    ], probe: ["systemctl", ["--user", "is-active", `${name}.timer`]], install: [["systemctl", ["--user", "daemon-reload"]], ["systemctl", ["--user", "enable", "--now", `${name}.timer`]]], uninstall: [["systemctl", ["--user", "disable", "--now", `${name}.timer`]]] };
+  }
+  if (platform === "win32") {
+    const file = join(directory, "service-task.xml");
+    return { backend: "task-scheduler", name, files: [[file, `<?xml version="1.0" encoding="UTF-8"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+<Triggers><TimeTrigger><Repetition><Interval>PT${minutes}M</Interval><StopAtDurationEnd>false</StopAtDurationEnd></Repetition><StartBoundary>${new Date(now + 60000).toISOString()}</StartBoundary><Enabled>true</Enabled><RandomDelay>PT1M</RandomDelay></TimeTrigger></Triggers>
+<Principals><Principal id="Author"><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+<Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><DisallowStartIfOnBatteries>true</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries><StartWhenAvailable>true</StartWhenAvailable><Enabled>true</Enabled><WakeToRun>false</WakeToRun><ExecutionTimeLimit>PT0S</ExecutionTimeLimit><Priority>7</Priority></Settings>
+<Actions Context="Author"><Exec><Command>${xml(executable)}</Command><Arguments>${xml(args.map(windowsQuote).join(" "))}</Arguments><WorkingDirectory>${xml(home)}</WorkingDirectory></Exec></Actions></Task>
+`]], probe: ["schtasks.exe", ["/Query", "/TN", name, "/XML"]], install: [["schtasks.exe", ["/Create", "/TN", name, "/XML", file, "/F"]]], uninstall: [["schtasks.exe", ["/Delete", "/TN", name, "/F"]]] };
+  }
+  throw new Error("Automatic sync supports macOS, Windows, and Linux with a user systemd manager (including running WSL distributions).");
+}
+
+async function readJson(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function atomicWrite(path, content) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, content, { mode: 0o600, flag: "wx" });
+    await rename(temp, path);
+  } finally { await unlink(temp).catch(() => {}); }
+}
+
+const runCommand = ([command, args]) => execute(command, args, { timeout: 15000, maxBuffer: 256 * 1024, windowsHide: true });
+
+export async function manageService(action, { directory, cli, minutes, env = process.env, executeCommand = runCommand, home = homedir(), platform = process.platform }) {
+  directory = resolve(directory);
+  const settingsPath = join(directory, "service.json");
+  const settings = await readJson(settingsPath);
+  const configHome = settings?.configHome || env.XDG_CONFIG_HOME || join(home, ".config");
+  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. */ }
+    return { installed: Boolean(settings), schedulerReachable: registered, backend: plan.backend, minutes: settings?.minutes ?? null, lastRun: await readJson(join(directory, "service-state.json")), hint: registered ? "Check lastRun for sync health. Windows task registration does not prove it is enabled." : "Scheduler is not active/reachable. On WSL, start the distro and enable its systemd user manager." };
+  }
+  if (action === "uninstall") {
+    if (!settings) return { installed: false };
+    // Failure is surfaced: do not claim removal while a scheduler might still run.
+    for (const command of plan.uninstall) await executeCommand(command);
+    for (const [file] of plan.files) await unlink(file).catch((error) => { if (error.code !== "ENOENT") throw error; });
+    await unlink(settingsPath);
+    if (plan.backend === "systemd") await executeCommand(["systemctl", ["--user", "daemon-reload"]]);
+    return { installed: false, retained: "Account link, usage checkpoints, and last-run status retained. An in-flight sync may finish." };
+  }
+  if (action !== "install") throw new Error("Use service install [--every 15], status, run, or uninstall.");
+  assertDurablePath(await realpath(cli));
+  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) {
+    let registered = false;
+    try { await executeCommand(plan.probe); registered = true; } catch { /* Missing registration can be repaired. */ }
+    if (registered) for (const command of plan.uninstall) await executeCommand(command);
+  }
+  const next = { version: 1, minutes: intervalMinutes(minutes ?? settings?.minutes ?? 15), configHome, env: capturedEnvironment(env), installedAt: new Date().toISOString() };
+  await atomicWrite(settingsPath, JSON.stringify(next));
+  for (const [file, content] of plan.files) await atomicWrite(file, content);
+  try {
+    for (const command of plan.install) await executeCommand(command);
+    await executeCommand(plan.probe);
+  } catch (error) {
+    throw new Error("Scheduler registration failed. Settings were retained for repair; rerun service install or check service status.", { cause: error });
+  }
+  return { installed: true, backend: plan.backend, minutes: next.minutes, note: "Opt-in one-shot jobs; no daemon, auto-updater, or wake-from-sleep. Reinstall after moving/upgrading the CLI or changing source paths." };
+}
+
+export async function runScheduledSync(directory, action, { now = () => Date.now(), env = process.env } = {}) {
+  const settings = await readJson(join(directory, "service.json"));
+  if (!settings) return { status: "disabled" };
+  const path = join(directory, "service-state.json");
+  const previous = await readJson(path) || {};
+  if (previous.nextAttemptAt > now()) return { status: "backoff", nextAttemptAt: previous.nextAttemptAt };
+  Object.assign(env, capturedEnvironment(settings.env || {}));
+  const start = now();
+  let state;
+  try {
+    await action();
+    state = { status: "ok", failures: 0, lastSuccessAt: new Date(now()).toISOString() };
+  } catch (error) {
+    if (error.code === "USAGEMAX_BUSY") return { status: "busy" };
+    const failures = Math.min((previous.failures || 0) + 1, 10);
+    // Save no command output, tokens, paths, or raw server error bodies.
+    state = { status: "error", failures, lastSuccessAt: previous.lastSuccessAt ?? null, nextAttemptAt: now() + Math.min(6 * 60, settings.minutes * 2 ** failures) * 60000, hint: "Run usagemax sync manually to diagnose; checkpoints are preserved." };
+  }
+  state = { ...state, attemptedAt: new Date(start).toISOString(), durationMs: now() - start };
+  await atomicWrite(path, JSON.stringify(state));
+  return state;
+}

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, {