@prohost/cli 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ Versions follow [semver](https://semver.org/). Publishing is automated: merging
 a version bump to `main` triggers `.github/workflows/npm-publish-cli.yml`, which
 builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
+## 0.10.0
+
+Every Claude Code and Codex login on a machine can report its remaining
+capacity and token use to ProhostAI, without pairing an agent.
+
+- **`prohost usage connect [--key <key>]`** stores an API key with the
+  `usage:write` scope in `$PROHOST_HOME/usage.json` (`0600`, never printed). A
+  machine that already paired an agent can skip `--key`; its credential is
+  accepted.
+- **Discovery.** `connect`, `usage discover [--dry-run]` and every `usage start`
+  register the config directories already on the machine — `~/.claude*`,
+  `~/.codex*`, `$CLAUDE_CONFIG_DIR`, `$CODEX_HOME` — in the machine-wide account
+  registry, labelled from the directory name (`~/.claude-work` → `work`). Only
+  directory names and non-secret markers are looked at.
+- **`prohost usage start`** reports every 5 minutes (`POST /v1/usage/reports`,
+  source `cli`): each login's windows from the same idle probes `agent run`
+  uses, asked at most every 15 minutes per login, three at a time.
+- **Token totals** from the CLIs' own session logs, summed per local day,
+  login, model and project folder name (`POST /v1/usage/token-totals`). Claude
+  Code responses are counted once however often their lines repeat; Codex usage
+  is the growth of each session's running total, with cached input split out.
+  The first run looks back 30 days, then reads only appended lines. No prompt
+  text is read into the totals or sent.
+  Totals for a login are sent only once a capacity report for it has been
+  accepted (`acceptedAccountKeys` when the server names them; otherwise any
+  non-zero `accepted`), so a first run or a newly found login reports first.
+  Skipped rows follow the server's `skipped[].reason`: `not_owned`,
+  `other_source` and `out_of_range` are dropped (logged once), `throttled` is
+  retried next pass, `not_reported` waits for the next accepted report. Rows
+  skipped without a reason are retried at most three times.
+- **Fails soft.** A 401/403/404 (routes not deployed, feature off, key without
+  the scope) is logged once and retried every 30 minutes; network errors back
+  off exponentially. A tick never throws.
+- **`prohost usage install-daemon` / `uninstall-daemon`** keep it running under
+  launchd with its own label (`ai.prohost.usage.*`), next to any agent daemon.
+  **`prohost usage status`** shows what was last sent and local totals.
+- `prohost agent account remove` on a login registered from an existing
+  directory forgets it and leaves the directory in place.
+
 ## 0.9.0
 
 A quick question no longer waits behind a long job in another thread.

package/README.md

@@ -1,12 +1,15 @@
 # `@prohost/cli`
 
-The [ProhostAI](https://www.prohost.ai) command-line tool. Two things it does:
+The [ProhostAI](https://www.prohost.ai) command-line tool. Three things it does:
 
 - **`prohost agent`** — run your own local agent as a ProhostAI teammate. Someone
   @-mentions it in the app, it runs on your machine, and its answer is posted
   back into the conversation.
 - **`prohost listen`** — stream your account's webhooks to a local HTTP endpoint
   while you develop against them (like `stripe listen`).
+- **`prohost usage`** — show your workspace how much Claude Code and Codex
+  capacity every login on this machine has left, and how many tokens each one
+  used, without pairing an agent.
 
 You need a ProhostAI account and **Node.js 18 or newer**. Nothing to install —
 `npx` fetches it on demand:
@@ -728,6 +731,75 @@ through ProhostAI's own approval path, not around it via an API key.
 
 ---
 
+## AI usage reporting
+
+`prohost usage` reports, for every Claude Code and Codex login on this machine,
+how much of its subscription is left (the 5-hour and weekly windows, with their
+reset times) and how many tokens it used per day, model and project folder.
+ProhostAI shows it in the workspace's AI Usage view. No agent pairing needed.
+
+```bash
+# 1. In ProhostAI: Settings → API keys → create a key with the usage:write scope.
+#    (A machine with a paired agent can skip --key: its credential is accepted.)
+npx @prohost/cli usage connect --key <api-key>
+
+# 2. Report now, then every 5 minutes, in the foreground…
+npx @prohost/cli usage start
+
+# …or keep it running across reboots (macOS launchd; prints a systemd unit on Linux).
+npx @prohost/cli usage install-daemon
+
+npx @prohost/cli usage status    # logins, last report, local token totals
+```
+
+**Which logins.** `connect`, `discover` and every `start` register the config
+directories already on this machine: `~/.claude`, `~/.codex` (as `default`) and
+any `~/.claude-<name>` / `~/.codex-<name>` (as `<name>` — `~/.claude-work` is
+`work`), plus `$CLAUDE_CONFIG_DIR` and `$CODEX_HOME`. They join the same
+machine-wide registry `prohost agent account` uses (`~/.prohost-accounts`), so a
+login added there is reported too. `prohost usage discover --dry-run` shows what
+would be registered without writing anything. Removing a discovered login with
+`prohost agent account remove` leaves its directory alone.
+
+**Capacity.** Each login is asked at most every 15 minutes, three at a time,
+through the unmodified CLI with that login's directory — `claude`'s `get_usage`
+control request and `codex app-server`'s `account/rateLimits/read`. Neither
+spends a model turn. Sign-in state comes from `claude auth status` /
+`codex login status`. `prohost` never opens a credential file or keychain item.
+
+**Tokens.** Read from the session logs the CLIs already write —
+`<config dir>/projects/**/*.jsonl` for Claude Code, `sessions/**/rollout-*.jsonl`
+for Codex — and summed per local day, login, model and project, where the
+project is the **name** of the working directory (`backend-service`, never its
+path). Only usage counters are read: no prompt, reply, tool call or file content
+is kept or sent. The first run looks back 30 days; after that only what was
+appended is read, using a cursor in `$PROHOST_HOME/usage/`. A day that changes
+is re-sent whole, and the server replaces it.
+Totals for a login go only after the server has accepted a capacity report
+for it (the server ignores totals for logins it hasn't seen), so each pass
+reports first. When the server says why it skipped a login's rows, the reason
+decides: another user's or another source's login, or a day out of range, is
+dropped (logged once); `throttled` is retried next pass; `not_reported` waits
+for the next accepted report. Unexplained skips are retried at most three
+times, so a login the server never takes is never resent forever and never
+holds up the others.
+
+**If the server says no.** Before the feature is enabled for your workspace
+(or with a key that lacks `usage:write`) the server answers 403/404. The reporter
+logs that once, waits 30 minutes, and tries again — it never exits over it.
+Network errors are retried with backoff. Logs go to `$PROHOST_HOME/usage.log`
+under the daemon.
+
+| Command | What it does |
+| --- | --- |
+| `usage connect [--key <key>] [--base-url <url>]` | Store the key (`$PROHOST_HOME/usage.json`, `0600`; `$PROHOST_API_KEY` works too), then discover logins. |
+| `usage discover [--dry-run]` | Register logins found on this machine. |
+| `usage start [--once] [--machine <name>]` | Report every 5 minutes; `--once` runs one pass and exits. |
+| `usage status` | Connection, daemon, last report and upload, and each login's local totals. |
+| `usage install-daemon [--machine <name>]` / `uninstall-daemon` | Keep `usage start` running (its own launchd job, separate from the agent's). |
+
+---
+
 ## Local webhook forwarding
 
 ```bash

package/dist/agent/accounts.d.ts

@@ -81,9 +81,25 @@ export declare function addAccount(options: {
     runtime: AccountRuntime;
     billing?: AccountBilling;
 }, env?: NodeJS.ProcessEnv): AccountRecord;
+/**
+ * Register a config directory that already exists — a login the operator made
+ * outside this CLI (`~/.claude-work`, a `$CODEX_HOME`). Nothing in it is read
+ * or written; signing in stays the agent CLI's own business. A directory that
+ * is already registered (under any label) is not registered twice.
+ */
+export declare function registerAccountDir(options: {
+    label: string;
+    runtime: AccountRuntime;
+    dir: string;
+    billing?: AccountBilling;
+}, env?: NodeJS.ProcessEnv): AccountRecord;
+/** Whether removing this account deletes its directory (only ones this CLI created). */
+export declare function ownsAccountDir(record: AccountRecord, env?: NodeJS.ProcessEnv): boolean;
 /**
  * Forget an account and delete its config directory (the login inside it goes
- * with it). The implicit default can't be removed — it is the CLI's own login.
+ * with it) — but only a directory this CLI created; a registered existing one
+ * is left where it is. The implicit default can't be removed — it is the CLI's
+ * own login.
  */
 export declare function removeAccount(label: string, runtime: AccountRuntime, env?: NodeJS.ProcessEnv): AccountRecord;
 export declare function runtimeName(runtime: AccountRuntime): string;

package/dist/agent/accounts.js

@@ -236,9 +236,50 @@ function addAccountLocked(label, runtime, billing, env) {
     saveAccounts([...loadAccounts(env), record], env);
     return record;
 }
+/**
+ * Register a config directory that already exists — a login the operator made
+ * outside this CLI (`~/.claude-work`, a `$CODEX_HOME`). Nothing in it is read
+ * or written; signing in stays the agent CLI's own business. A directory that
+ * is already registered (under any label) is not registered twice.
+ */
+export function registerAccountDir(options, env = process.env) {
+    const { label, runtime } = options;
+    if (!isValidLabel(label) || label === DEFAULT_ACCOUNT_LABEL) {
+        throw new AccountError(`"${label}" is not a usable label for an existing login directory.`);
+    }
+    const dir = path.resolve(options.dir);
+    return withRegistryLock(env, () => {
+        const accounts = loadAccounts(env);
+        const same = accounts.find((a) => a.runtime === runtime && a.dir !== null && path.resolve(a.dir) === dir);
+        if (same)
+            return same;
+        if (findAccount(label, runtime, env)) {
+            throw new AccountError(`A ${runtimeName(runtime)} account named "${label}" already exists on this machine.`);
+        }
+        if (accounts.filter((a) => a.label !== DEFAULT_ACCOUNT_LABEL).length >= MAX_REPORTED_ACCOUNTS - 2) {
+            throw new AccountError(`This machine already has ${MAX_REPORTED_ACCOUNTS - 2} accounts, the most ProhostAI can show. Remove one first.`);
+        }
+        const record = {
+            key: randomUUID(),
+            label,
+            runtime,
+            billing: options.billing ?? 'subscription',
+            dir,
+            created_at: new Date().toISOString(),
+        };
+        saveAccounts([...accounts, record], env);
+        return record;
+    });
+}
+/** Whether removing this account deletes its directory (only ones this CLI created). */
+export function ownsAccountDir(record, env = process.env) {
+    return !!record.dir && record.dir.startsWith(path.join(accountsRoot(env), 'accounts') + path.sep);
+}
 /**
  * Forget an account and delete its config directory (the login inside it goes
- * with it). The implicit default can't be removed — it is the CLI's own login.
+ * with it) — but only a directory this CLI created; a registered existing one
+ * is left where it is. The implicit default can't be removed — it is the CLI's
+ * own login.
  */
 export function removeAccount(label, runtime, env = process.env) {
     if (label === DEFAULT_ACCOUNT_LABEL) {
@@ -253,7 +294,7 @@ export function removeAccount(label, runtime, env = process.env) {
         return found;
     });
     // Only ever a directory this module created under the root.
-    if (record.dir && record.dir.startsWith(path.join(accountsRoot(env), 'accounts') + path.sep)) {
+    if (ownsAccountDir(record, env) && record.dir) {
         rmSync(record.dir, { recursive: true, force: true });
     }
     return record;

package/dist/agent/agent_commands.js

@@ -4,7 +4,7 @@
  * `accounts.ts`, `list.ts` and `workspace.ts`.
  */
 import process from 'node:process';
-import { AccountError, addAccount, checkAuth, loadAccounts, parseAccountRuntime, removeAccount, runtimeName, signInCommand, waitForSignIn, } from './accounts.js';
+import { AccountError, addAccount, checkAuth, loadAccounts, ownsAccountDir, parseAccountRuntime, removeAccount, runtimeName, signInCommand, waitForSignIn, } from './accounts.js';
 import { ensureWorkspace } from './credentials.js';
 import { findAgentHomes, renderAgentList } from './list.js';
 import { WorkspaceInitError, initDeveloperWorkspace } from './workspace.js';
@@ -118,8 +118,9 @@ export async function accountCommand(args, flags, io = defaultIO) {
                 'Move them to another account first, or pass --force.');
             return 1;
         }
+        let removed;
         try {
-            removeAccount(label, target?.runtime ?? runtime ?? 'claude_code', env);
+            removed = removeAccount(label, target?.runtime ?? runtime ?? 'claude_code', env);
         }
         catch (err) {
             if (err instanceof AccountError) {
@@ -128,7 +129,9 @@ export async function accountCommand(args, flags, io = defaultIO) {
             }
             throw err;
         }
-        io.out(`✓ Removed "${label}" and its login directory.`);
+        io.out(ownsAccountDir(removed, env)
+            ? `✓ Removed "${label}" and its login directory.`
+            : `✓ Removed "${label}". Its login directory${removed.dir ? ` (${removed.dir})` : ''} was left in place.`);
         return 0;
     }
     io.err('Expected: prohost agent account add|list|remove');

package/dist/agent/api.d.ts

@@ -68,6 +68,12 @@ export declare function describeFailure(result: ApiResult): string;
  * cached, and the next replay receives its response.
  */
 export declare function isIdempotencyInFlight(result: ApiResult): boolean;
+/**
+ * POST a JSON body with the API key. Never throws: every failure comes back as
+ * an {@link ApiResult}. Exported for the `prohost usage` reporter, which owns
+ * its own paths.
+ */
+export declare function postJson(options: ApiOptions, path: string, body: unknown, idempotencyKey?: string, captureBody?: boolean, timeoutMs?: number): Promise<ApiResult>;
 /**
  * Post the agent's reply into the conversation that triggered the run.
  *

package/dist/agent/api.js

@@ -52,7 +52,12 @@ export function describeFailure(result) {
 export function isIdempotencyInFlight(result) {
     return result.status === 409 && (result.error ?? '').includes('idempotency_key_in_flight');
 }
-async function post(options, path, body, idempotencyKey, captureBody = false, timeoutMs = DEFAULT_TIMEOUT_MS) {
+/**
+ * POST a JSON body with the API key. Never throws: every failure comes back as
+ * an {@link ApiResult}. Exported for the `prohost usage` reporter, which owns
+ * its own paths.
+ */
+export async function postJson(options, path, body, idempotencyKey, captureBody = false, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const controller = new AbortController();
     const deadlineMs = options.timeoutMs ?? timeoutMs;
@@ -126,7 +131,7 @@ export async function postReply(options, path, bodyKey, message, runId, extra) {
     // thing in this request that must survive.
     // Byte-identical on every attempt: the server hashes the body against the
     // key, so a replay must serialise exactly as the original did.
-    return post(options, path, { ...extra, [bodyKey]: message }, `prohost-cli-run-${runId}`, false, SEND_TIMEOUT_MS);
+    return postJson(options, path, { ...extra, [bodyKey]: message }, `prohost-cli-run-${runId}`, false, SEND_TIMEOUT_MS);
 }
 function booleanField(body, key) {
     if (!body)
@@ -154,7 +159,7 @@ function booleanField(body, key) {
  */
 export async function heartbeatRun(options, path, progress) {
     const trimmed = progress?.trim();
-    const result = await post(options, path, trimmed ? { progress: trimmed.slice(0, MAX_PROGRESS_CHARS) } : {}, undefined, true);
+    const result = await postJson(options, path, trimmed ? { progress: trimmed.slice(0, MAX_PROGRESS_CHARS) } : {}, undefined, true);
     if (result.ok)
         return { kind: 'alive', cancelRequested: booleanField(result.body, 'cancel_requested') };
     if (result.status === 404)
@@ -180,7 +185,7 @@ export async function completeRun(options, path, outcome, model) {
         : { status: RUN_STATUS_FAILED, error: outcome.error.slice(0, MAX_ERROR_CHARS) };
     if (model)
         body.model = model.slice(0, MAX_MODEL_CHARS);
-    const result = await post(options, path, body, undefined, false, SEND_TIMEOUT_MS);
+    const result = await postJson(options, path, body, undefined, false, SEND_TIMEOUT_MS);
     if (result.status === 409)
         return { ...result, ok: true };
     return result;
@@ -195,5 +200,5 @@ export async function completeRun(options, path, outcome, model) {
  * over-fills one gets it clipped rather than rejected whole.
  */
 export async function postToolEvents(options, path, events) {
-    return post(options, path, { events: events.slice(0, MAX_TOOL_EVENTS_PER_BATCH) });
+    return postJson(options, path, { events: events.slice(0, MAX_TOOL_EVENTS_PER_BATCH) });
 }

package/dist/index.d.ts

@@ -8,6 +8,7 @@
  *     npx @prohost/cli agent pair --code <pairing-code>
  *     npx @prohost/cli agent run --exec 'claude -p'
  *     npx @prohost/cli agent install-daemon --exec 'claude -p'
+ *     npx @prohost/cli usage connect --key <api-key>
  *
  * Parses arguments with a zero-dep, zero-magic flag parser so the published
  * binary stays small and starts fast.

package/dist/index.js

@@ -8,6 +8,7 @@
  *     npx @prohost/cli agent pair --code <pairing-code>
  *     npx @prohost/cli agent run --exec 'claude -p'
  *     npx @prohost/cli agent install-daemon --exec 'claude -p'
+ *     npx @prohost/cli usage connect --key <api-key>
  *
  * Parses arguments with a zero-dep, zero-magic flag parser so the published
  * binary stays small and starts fast.
@@ -17,6 +18,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { runAgent } from './agent/command.js';
 import { DEFAULT_WS_URL, runListen } from './listen.js';
+import { runUsage } from './usage/command.js';
 import { CLI_VERSION } from './version.js';
 function printHelp() {
     const lines = [
@@ -33,6 +35,9 @@ function printHelp() {
         '  prohost agent account list | remove <label>',
         '  prohost agent list                   Every paired agent on this machine, and its accounts',
         '  prohost agent workspace init --developer --repo <checkout> [--workdir <dir>]',
+        '  prohost usage connect [--key <api-key>] [--base-url <url>]   Report AI usage without pairing an agent',
+        '  prohost usage discover [--dry-run] | start [--once] [--machine <name>] | status',
+        '  prohost usage install-daemon [--machine <name>] | uninstall-daemon',
         '',
         'listen flags:',
         '  --forward-to     Local URL to POST each webhook payload to (required)',
@@ -99,6 +104,15 @@ function printHelp() {
         '  Adds the ProhostAI PR-protocol skill and the `gh pr create` gate hook from --repo (a',
         '  backend-service checkout) to the agent workspace\'s .claude/. Opt-in; nothing else changes.',
         '',
+        'Usage reporting (observer mode):',
+        '  `usage connect` stores an API key with the usage:write scope ($PROHOST_HOME/usage.json, owner-only;',
+        '  a machine with a paired agent can reuse its credential) and registers every Claude Code and Codex',
+        '  login it finds: ~/.claude*, ~/.codex*, $CLAUDE_CONFIG_DIR, $CODEX_HOME (`~/.claude-work` → "work").',
+        '  `usage start` then reports, every 5 minutes, each login\'s remaining capacity — asked of the',
+        '  unmodified CLI, at most every 15 minutes per login — and daily token totals per model and project',
+        '  folder, read from the local session logs (last 30 days, then incrementally). Never prompt text.',
+        '  `--once` runs one pass and exits. `usage status` shows what was last sent.',
+        '',
         'agent install-daemon flags:  (macOS: launchd; Linux: prints a systemd-user unit)',
         '  --exec           The same command you would pass to `agent run` (required).',
         '  --workdir, --concurrency, --repos, --idle-timeout, --timeout, --machine, --url,',
@@ -182,6 +196,9 @@ async function main(argv) {
     if (command === 'agent') {
         return runAgent(subcommand, flags, printHelp, args);
     }
+    if (command === 'usage') {
+        return runUsage(subcommand, flags, printHelp);
+    }
     if (command !== 'listen') {
         process.stderr.write(`Unknown command: ${command}\n\n`);
         printHelp();

package/dist/usage/backoff.d.ts

@@ -0,0 +1,42 @@
+/**
+ * When the usage reporter may try an endpoint again, and what it says about it.
+ *
+ * The reporter runs for weeks under launchd, so it must never crash and never
+ * fill a log. Three kinds of failure, treated differently:
+ *
+ * - **Gated** — 401, 403, 404. The routes are not deployed yet, the workspace
+ *   doesn't have the feature, or the key lacks `usage:write`. None of that
+ *   changes in minutes, so wait {@link GATED_BACKOFF_MS} and say so once —
+ *   not on every retry.
+ * - **Transient** — no response, 408, 429, 5xx. Retry with exponential backoff
+ *   from {@link BASE_BACKOFF_MS} up to {@link MAX_BACKOFF_MS}; logged once
+ *   per streak.
+ * - **Rejected** — any other 4xx. A body this build got wrong; retrying soon
+ *   won't fix it, so it waits like a gated one and logs the server's reason.
+ *
+ * A success after any of these says "recovered" once and resets everything.
+ */
+import type { ApiResult } from '../agent/api.js';
+export declare const BASE_BACKOFF_MS = 60000;
+export declare const MAX_BACKOFF_MS: number;
+export declare const GATED_BACKOFF_MS: number;
+export type FailureKind = 'gated' | 'transient' | 'rejected';
+export declare function classifyFailure(result: ApiResult): FailureKind;
+export declare class Backoff {
+    private readonly name;
+    private readonly now;
+    private nextAt;
+    private failures;
+    private lastKind;
+    private lastStatus;
+    constructor(name: string, now?: () => number);
+    /** Whether a request may be made now. */
+    ready(): boolean;
+    /** When the next attempt is allowed (epoch ms; 0 = now). */
+    retryAt(): number;
+    /**
+     * Record an attempt's outcome. Returns a line to log, or `undefined` when
+     * this outcome was already reported.
+     */
+    record(result: ApiResult): string | undefined;
+}

package/dist/usage/backoff.js

@@ -0,0 +1,85 @@
+/**
+ * When the usage reporter may try an endpoint again, and what it says about it.
+ *
+ * The reporter runs for weeks under launchd, so it must never crash and never
+ * fill a log. Three kinds of failure, treated differently:
+ *
+ * - **Gated** — 401, 403, 404. The routes are not deployed yet, the workspace
+ *   doesn't have the feature, or the key lacks `usage:write`. None of that
+ *   changes in minutes, so wait {@link GATED_BACKOFF_MS} and say so once —
+ *   not on every retry.
+ * - **Transient** — no response, 408, 429, 5xx. Retry with exponential backoff
+ *   from {@link BASE_BACKOFF_MS} up to {@link MAX_BACKOFF_MS}; logged once
+ *   per streak.
+ * - **Rejected** — any other 4xx. A body this build got wrong; retrying soon
+ *   won't fix it, so it waits like a gated one and logs the server's reason.
+ *
+ * A success after any of these says "recovered" once and resets everything.
+ */
+import { describeFailure } from '../agent/api.js';
+export const BASE_BACKOFF_MS = 60_000;
+export const MAX_BACKOFF_MS = 30 * 60_000;
+export const GATED_BACKOFF_MS = 30 * 60_000;
+export function classifyFailure(result) {
+    const { status } = result;
+    if (status === 401 || status === 403 || status === 404)
+        return 'gated';
+    if (status === 0 || status === 408 || status === 429 || status >= 500)
+        return 'transient';
+    return 'rejected';
+}
+export class Backoff {
+    name;
+    now;
+    nextAt = 0;
+    failures = 0;
+    lastKind;
+    lastStatus;
+    constructor(name, now = Date.now) {
+        this.name = name;
+        this.now = now;
+    }
+    /** Whether a request may be made now. */
+    ready() {
+        return this.now() >= this.nextAt;
+    }
+    /** When the next attempt is allowed (epoch ms; 0 = now). */
+    retryAt() {
+        return this.nextAt;
+    }
+    /**
+     * Record an attempt's outcome. Returns a line to log, or `undefined` when
+     * this outcome was already reported.
+     */
+    record(result) {
+        if (result.ok) {
+            const wasFailing = this.failures > 0;
+            this.failures = 0;
+            this.nextAt = 0;
+            this.lastKind = undefined;
+            this.lastStatus = undefined;
+            return wasFailing ? `${this.name}: recovered` : undefined;
+        }
+        const kind = classifyFailure(result);
+        this.failures += 1;
+        const delay = kind === 'transient'
+            ? Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** Math.min(this.failures - 1, 16))
+            : GATED_BACKOFF_MS;
+        this.nextAt = this.now() + delay;
+        const repeat = this.lastKind === kind && (kind === 'transient' || this.lastStatus === result.status);
+        this.lastKind = kind;
+        this.lastStatus = result.status;
+        if (repeat)
+            return undefined;
+        const minutes = Math.round(delay / 60_000);
+        if (kind === 'gated') {
+            return (`${this.name}: ${describeFailure(result)} — usage reporting is not available for this key yet ` +
+                `(not deployed, not enabled for the workspace, or the key lacks usage:write). ` +
+                `Retrying every ${minutes} min.`);
+        }
+        if (kind === 'rejected') {
+            return `${this.name}: ${describeFailure(result)} rejected${result.error ? ` (${result.error.slice(0, 200)})` : ''}. Retrying in ${minutes} min.`;
+        }
+        return `${this.name}: ${describeFailure(result)}. Retrying with backoff (next in ${minutes} min).`;
+    }
+}

package/dist/usage/command.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `prohost usage …` — observer mode: report this machine's Claude Code and
+ * Codex capacity and token totals to ProhostAI without pairing an agent.
+ *
+ * Flag plumbing only; the work lives in `discovery.ts`, `quota.ts`,
+ * `scanner.ts` and `service.ts`.
+ */
+import type { DiscoveryResult } from './discovery.js';
+type Flags = Record<string, string | boolean>;
+export interface UsageIO {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+}
+/** launchd label prefix for the usage reporter — distinct from the agent daemon's. */
+export declare const USAGE_LAUNCHD_PREFIX = "ai.prohost.usage";
+/** Label for the usage daemon serving one `$PROHOST_HOME`. Same digest as the agent's, other prefix. */
+export declare function usageLaunchdLabel(home: string): string;
+export declare function usageLogPath(env?: NodeJS.ProcessEnv): string;
+/** `prohost usage start` argv for a supervisor. */
+export declare function usageDaemonArguments(options: {
+    execPath: string;
+    scriptPath: string;
+    machine?: string;
+}): string[];
+/** Dispatch a `usage` subcommand. Returns the exit code. */
+export declare function runUsage(subcommand: string | undefined, flags: Flags, printHelp: () => void, io?: UsageIO): Promise<number>;
+export declare function renderDiscovery(result: DiscoveryResult, env: NodeJS.ProcessEnv, dryRun: boolean): string[];
+/** `1234567` → `1.2M`. */
+export declare function compactTokens(n: number): string;
+export {};