@prohost/cli 0.8.3 → 0.10.0

package/dist/agent/worktrees.d.ts

@@ -0,0 +1,136 @@
+/**
+ * A private checkout of each `--repos` repository, per conversation.
+ *
+ * A coding agent that opens pull requests does it in a git checkout, and until
+ * `--concurrency` there was only ever one run touching it. Two runs sharing one
+ * checkout switch each other's branch mid-edit and commit each other's
+ * half-finished files — the reason runs were serialized in the first place. So
+ * when the operator names the repositories the agent works on, each
+ * conversation gets its own `git worktree` of every one of them:
+ *
+ *     $PROHOST_HOME/worktrees/<conversation>/<repo-name>
+ *
+ * Per *conversation*, not per run, for the same reason sessions are: a
+ * follow-up in the thread ("address the review comments") resumes the session
+ * that made the branch, and must find that branch where it left it. Runs of one
+ * conversation never overlap (see `scheduler.ts`), so one checkout per
+ * conversation is exactly as isolated as one per run and far cheaper.
+ *
+ * The harness makes the worktree; the agent never needs `git worktree add`.
+ * The agent command's working directory does not change — it stays the
+ * workspace, because that is where its `.claude/` configuration lives and what
+ * its sessions are keyed on. The checkouts are named in the prompt and in
+ * `$PROHOST_RUN_REPOS`.
+ *
+ * Worktrees share the source repository's object store, so a branch committed
+ * in one survives the worktree being removed. That is what makes pruning safe:
+ * `git worktree remove` (never `--force`) refuses a checkout with uncommitted
+ * or untracked files, and those are the only things a worktree holds alone.
+ */
+/** Child-process env var naming the directory that holds this run's checkouts. */
+export declare const RUN_REPOS_ENV_VAR = "PROHOST_RUN_REPOS";
+/** A conversation's checkouts idle this long are removed, if clean. */
+export declare const WORKTREE_RETENTION_MS: number;
+export interface RunCheckout {
+    /** Directory name of the repository, e.g. `backend-service`. */
+    name: string;
+    /** This conversation's private worktree of it. */
+    path: string;
+    /** The operator's checkout it was made from — the one the agent must leave alone. */
+    source: string;
+}
+export interface CheckoutFailure {
+    source: string;
+    reason: string;
+}
+export interface PreparedCheckouts {
+    /** Directory holding the checkouts; exported as {@link RUN_REPOS_ENV_VAR}. */
+    dir: string;
+    checkouts: RunCheckout[];
+    failures: CheckoutFailure[];
+}
+export declare class ReposFlagError extends Error {
+}
+export declare function worktreesRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * Directory name for a lane (see `sessionKeyFor`).
+ *
+ * Readable enough to recognise in `ls`, and suffixed with a digest of the whole
+ * key because the readable part is lossy: two keys that differ only in
+ * punctuation, or in the agent they belong to, must not share a checkout.
+ */
+export declare function laneDirName(lane: string): string;
+/**
+ * Read `--repos a,b` into absolute paths, refusing what can never work.
+ *
+ * An empty list and two checkouts with one directory name are always errors.
+ * A path that is not a git checkout is an error only when `requireCheckouts`
+ * is set — which `install-daemon` does and `agent run` does not. At install
+ * time a mistyped path should stop the install; at run time the same check
+ * would make a daemon whose repository was moved, deleted or is on an
+ * unmounted volume exit before connecting, and the service manager restart it
+ * forever. A running harness instead reports the checkout it could not make on
+ * each run, and keeps answering.
+ *
+ * @throws ReposFlagError naming the entry that is wrong.
+ */
+export declare function parseReposFlag(raw: string, options?: {
+    requireCheckouts?: boolean;
+}): string[];
+/** Whether `repo` is the top of a git checkout (a clone, or a worktree of one). */
+export declare function isCheckout(repo: string): boolean;
+export interface WorktreeManagerOptions {
+    /** Absolute paths of the operator's checkouts. Empty disables the feature. */
+    repos: string[];
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+    /** Clock seam for tests. */
+    now?: () => number;
+    retentionMs?: number;
+}
+/**
+ * Makes, reuses and prunes per-conversation worktrees for one harness.
+ *
+ * Every git mutation goes through one in-process queue. Lanes run side by
+ * side, and two `git worktree add` calls against the same repository race for
+ * the same administrative name; pruning, meanwhile, must never remove the
+ * directory a run arriving this instant is about to use.
+ */
+export declare class WorktreeManager {
+    private readonly repos;
+    private readonly env;
+    private readonly log;
+    private readonly now;
+    private readonly retentionMs;
+    private chain;
+    private lastPrunedAt;
+    constructor(options: WorktreeManagerOptions);
+    get enabled(): boolean;
+    private exclusive;
+    /**
+     * Ensure this lane has a worktree of every repository, and say where.
+     *
+     * Never rejects and never fails the run: most runs are questions that touch
+     * no repository at all, so a checkout that could not be made is reported in
+     * {@link PreparedCheckouts.failures} for the prompt to tell the agent about.
+     */
+    prepare(lane: string): Promise<PreparedCheckouts>;
+    /** The repository a checkout's history lives in, as one comparable path. */
+    private commonDir;
+    /**
+     * Keep an existing checkout — once it is proven to be a worktree of `source`.
+     *
+     * The directory is named after the repository's basename, so pointing
+     * `--repos` from `/old/app` to `/new/app` leaves every conversation with an
+     * `app` checkout of the *old* repository. Handing that to the agent as a
+     * checkout of the new one would have it commit to the wrong repository.
+     */
+    private reuse;
+    /** Returns why the worktree could not be made, or `undefined` when it was. */
+    private add;
+    private touch;
+    private pruneIfDue;
+    /** Remove idle conversations' checkouts, never the one about to be used. */
+    private prune;
+    private removeLane;
+}

package/dist/agent/worktrees.js

@@ -0,0 +1,317 @@
+/**
+ * A private checkout of each `--repos` repository, per conversation.
+ *
+ * A coding agent that opens pull requests does it in a git checkout, and until
+ * `--concurrency` there was only ever one run touching it. Two runs sharing one
+ * checkout switch each other's branch mid-edit and commit each other's
+ * half-finished files — the reason runs were serialized in the first place. So
+ * when the operator names the repositories the agent works on, each
+ * conversation gets its own `git worktree` of every one of them:
+ *
+ *     $PROHOST_HOME/worktrees/<conversation>/<repo-name>
+ *
+ * Per *conversation*, not per run, for the same reason sessions are: a
+ * follow-up in the thread ("address the review comments") resumes the session
+ * that made the branch, and must find that branch where it left it. Runs of one
+ * conversation never overlap (see `scheduler.ts`), so one checkout per
+ * conversation is exactly as isolated as one per run and far cheaper.
+ *
+ * The harness makes the worktree; the agent never needs `git worktree add`.
+ * The agent command's working directory does not change — it stays the
+ * workspace, because that is where its `.claude/` configuration lives and what
+ * its sessions are keyed on. The checkouts are named in the prompt and in
+ * `$PROHOST_RUN_REPOS`.
+ *
+ * Worktrees share the source repository's object store, so a branch committed
+ * in one survives the worktree being removed. That is what makes pruning safe:
+ * `git worktree remove` (never `--force`) refuses a checkout with uncommitted
+ * or untracked files, and those are the only things a worktree holds alone.
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmdirSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { prohostHome } from './credentials.js';
+/** Child-process env var naming the directory that holds this run's checkouts. */
+export const RUN_REPOS_ENV_VAR = 'PROHOST_RUN_REPOS';
+/** Touched on every run of a conversation; its mtime is "last used". */
+const MARKER_FILENAME = '.last-used';
+/** A conversation's checkouts idle this long are removed, if clean. */
+export const WORKTREE_RETENTION_MS = 14 * 24 * 3_600_000;
+/** Pruning walks every conversation directory, so it is not done per run. */
+const PRUNE_INTERVAL_MS = 24 * 3_600_000;
+/** Checking out a large repository takes a while; a wedged git must still end. */
+const GIT_TIMEOUT_MS = 10 * 60_000;
+export class ReposFlagError extends Error {
+}
+export function worktreesRoot(env = process.env) {
+    return path.join(prohostHome(env), 'worktrees');
+}
+/**
+ * Directory name for a lane (see `sessionKeyFor`).
+ *
+ * Readable enough to recognise in `ls`, and suffixed with a digest of the whole
+ * key because the readable part is lossy: two keys that differ only in
+ * punctuation, or in the agent they belong to, must not share a checkout.
+ */
+export function laneDirName(lane) {
+    const surface = lane.includes('/') ? lane.slice(lane.indexOf('/') + 1) : lane;
+    const readable = surface.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60);
+    const digest = createHash('sha256').update(lane).digest('hex').slice(0, 8);
+    return readable ? `${readable}-${digest}` : digest;
+}
+function git(args, env) {
+    return new Promise((resolve) => {
+        execFile('git', args, { env: { ...process.env, ...env }, timeout: GIT_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({ ok: error === null, stdout: String(stdout), stderr: String(stderr) || (error?.message ?? '') });
+        });
+    });
+}
+function lastLine(text) {
+    const lines = text.trim().split('\n');
+    return (lines[lines.length - 1] ?? '').trim();
+}
+/**
+ * Read `--repos a,b` into absolute paths, refusing what can never work.
+ *
+ * An empty list and two checkouts with one directory name are always errors.
+ * A path that is not a git checkout is an error only when `requireCheckouts`
+ * is set — which `install-daemon` does and `agent run` does not. At install
+ * time a mistyped path should stop the install; at run time the same check
+ * would make a daemon whose repository was moved, deleted or is on an
+ * unmounted volume exit before connecting, and the service manager restart it
+ * forever. A running harness instead reports the checkout it could not make on
+ * each run, and keeps answering.
+ *
+ * @throws ReposFlagError naming the entry that is wrong.
+ */
+export function parseReposFlag(raw, options = {}) {
+    const entries = raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (entries.length === 0)
+        throw new ReposFlagError('--repos needs at least one path to a git checkout.');
+    const repos = [];
+    const names = new Map();
+    for (const entry of entries) {
+        const repo = path.resolve(entry);
+        if (options.requireCheckouts && !isCheckout(repo)) {
+            throw new ReposFlagError(`--repos: ${repo} is not the top of a git checkout (no .git there).`);
+        }
+        const name = path.basename(repo);
+        const clash = names.get(name);
+        if (clash && clash !== repo) {
+            throw new ReposFlagError(`--repos: ${clash} and ${repo} are both named "${name}"; their checkouts would land in the same directory.`);
+        }
+        if (!clash)
+            repos.push(repo);
+        names.set(name, repo);
+    }
+    return repos;
+}
+/** Whether `repo` is the top of a git checkout (a clone, or a worktree of one). */
+export function isCheckout(repo) {
+    return existsSync(path.join(repo, '.git'));
+}
+/**
+ * Makes, reuses and prunes per-conversation worktrees for one harness.
+ *
+ * Every git mutation goes through one in-process queue. Lanes run side by
+ * side, and two `git worktree add` calls against the same repository race for
+ * the same administrative name; pruning, meanwhile, must never remove the
+ * directory a run arriving this instant is about to use.
+ */
+export class WorktreeManager {
+    repos;
+    env;
+    log;
+    now;
+    retentionMs;
+    chain = Promise.resolve();
+    lastPrunedAt = 0;
+    constructor(options) {
+        this.repos = options.repos;
+        this.env = options.env ?? process.env;
+        this.log = options.log ?? (() => { });
+        this.now = options.now ?? Date.now;
+        this.retentionMs = options.retentionMs ?? WORKTREE_RETENTION_MS;
+    }
+    get enabled() {
+        return this.repos.length > 0;
+    }
+    exclusive(work) {
+        const next = this.chain.then(work, work);
+        this.chain = next.catch(() => { });
+        return next;
+    }
+    /**
+     * Ensure this lane has a worktree of every repository, and say where.
+     *
+     * Never rejects and never fails the run: most runs are questions that touch
+     * no repository at all, so a checkout that could not be made is reported in
+     * {@link PreparedCheckouts.failures} for the prompt to tell the agent about.
+     */
+    prepare(lane) {
+        return this.exclusive(async () => {
+            const dir = path.join(worktreesRoot(this.env), laneDirName(lane));
+            const prepared = { dir, checkouts: [], failures: [] };
+            try {
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                this.touch(dir);
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                prepared.failures = this.repos.map((source) => ({ source, reason }));
+                return prepared;
+            }
+            for (const source of this.repos) {
+                const name = path.basename(source);
+                const target = path.join(dir, name);
+                let failure;
+                try {
+                    failure = isCheckout(target) ? await this.reuse(source, target) : await this.add(source, target);
+                }
+                catch (err) {
+                    failure = err instanceof Error ? err.message : String(err);
+                }
+                if (failure)
+                    prepared.failures.push({ source, reason: failure });
+                else
+                    prepared.checkouts.push({ name, path: target, source });
+            }
+            // Housekeeping for other conversations must not cost this one its run.
+            await this.pruneIfDue(dir).catch((err) => {
+                this.log(`    ! could not prune idle checkouts (${err instanceof Error ? err.message : String(err)})`);
+            });
+            return prepared;
+        });
+    }
+    /** The repository a checkout's history lives in, as one comparable path. */
+    async commonDir(checkout) {
+        const result = await git(['-C', checkout, 'rev-parse', '--path-format=absolute', '--git-common-dir'], this.env);
+        const dir = result.stdout.trim();
+        return result.ok && dir ? dir : undefined;
+    }
+    /**
+     * Keep an existing checkout — once it is proven to be a worktree of `source`.
+     *
+     * The directory is named after the repository's basename, so pointing
+     * `--repos` from `/old/app` to `/new/app` leaves every conversation with an
+     * `app` checkout of the *old* repository. Handing that to the agent as a
+     * checkout of the new one would have it commit to the wrong repository.
+     */
+    async reuse(source, target) {
+        const [mine, theirs] = await Promise.all([this.commonDir(target), this.commonDir(source)]);
+        if (theirs === undefined)
+            return `${source} is not a git checkout`;
+        if (mine === theirs)
+            return undefined;
+        // Not ours to throw away: without `--force`, git removes it only if it
+        // holds nothing uncommitted.
+        const removed = mine === undefined
+            ? { ok: false, stderr: 'it is not a usable git checkout' }
+            : await git(['--git-dir', mine, 'worktree', 'remove', target], this.env);
+        if (!removed.ok) {
+            return (`${target} is a checkout of a different repository and could not be replaced ` +
+                `(${lastLine(removed.stderr) || 'git would not remove it'})`);
+        }
+        this.log(`    ⚙ replaced ${target}: it was a checkout of ${mine}, not of ${source}`);
+        return this.add(source, target);
+    }
+    /** Returns why the worktree could not be made, or `undefined` when it was. */
+    async add(source, target) {
+        // A worktree whose directory was deleted by hand is still registered, and
+        // git refuses to add another at that path until the record is pruned.
+        await git(['-C', source, 'worktree', 'prune'], this.env);
+        // Detached at the remote's default branch: the agent cuts its own branch,
+        // and a detached HEAD cannot collide with a branch checked out elsewhere.
+        let base = 'HEAD';
+        for (const candidate of ['origin/HEAD', 'origin/main', 'origin/master']) {
+            const known = await git(['-C', source, 'rev-parse', '--verify', '--quiet', `${candidate}^{commit}`], this.env);
+            if (known.ok) {
+                base = candidate;
+                break;
+            }
+        }
+        const added = await git(['-C', source, 'worktree', 'add', '--detach', target, base], this.env);
+        if (added.ok) {
+            this.log(`    ⚙ checkout ready: ${target} (worktree of ${source} at ${base})`);
+            return undefined;
+        }
+        // A half-made directory would be mistaken for a checkout on the next run.
+        rmSync(target, { recursive: true, force: true });
+        return lastLine(added.stderr) || 'git worktree add failed';
+    }
+    touch(dir) {
+        const marker = path.join(dir, MARKER_FILENAME);
+        const stamp = new Date(this.now());
+        if (existsSync(marker))
+            utimesSync(marker, stamp, stamp);
+        else {
+            writeFileSync(marker, '');
+            utimesSync(marker, stamp, stamp);
+        }
+    }
+    async pruneIfDue(keep) {
+        if (this.now() - this.lastPrunedAt < PRUNE_INTERVAL_MS)
+            return;
+        this.lastPrunedAt = this.now();
+        await this.prune(keep);
+    }
+    /** Remove idle conversations' checkouts, never the one about to be used. */
+    async prune(keep) {
+        const root = worktreesRoot(this.env);
+        let lanes;
+        try {
+            lanes = readdirSync(root);
+        }
+        catch {
+            return; // nothing has ever been checked out
+        }
+        for (const lane of lanes) {
+            const dir = path.join(root, lane);
+            if (dir === keep)
+                continue;
+            try {
+                if (!statSync(dir).isDirectory())
+                    continue;
+                const marker = path.join(dir, MARKER_FILENAME);
+                const usedAt = (existsSync(marker) ? statSync(marker) : statSync(dir)).mtimeMs;
+                if (this.now() - usedAt < this.retentionMs)
+                    continue;
+                await this.removeLane(dir);
+            }
+            catch (err) {
+                this.log(`    ! could not prune ${dir} (${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
+    }
+    async removeLane(dir) {
+        let kept = 0;
+        for (const name of readdirSync(dir)) {
+            if (name === MARKER_FILENAME)
+                continue;
+            const target = path.join(dir, name);
+            if (!existsSync(path.join(target, '.git'))) {
+                kept += 1;
+                continue;
+            }
+            // Asked of the worktree itself, so pruning still works for a repository
+            // the operator has since dropped from `--repos`.
+            const common = await git(['-C', target, 'rev-parse', '--path-format=absolute', '--git-common-dir'], this.env);
+            const removed = common.ok
+                ? await git(['--git-dir', common.stdout.trim(), 'worktree', 'remove', target], this.env)
+                : common;
+            if (!removed.ok) {
+                kept += 1;
+                this.log(`    ! kept idle checkout ${target} — ${lastLine(removed.stderr) || 'git would not remove it'}`);
+            }
+        }
+        if (kept === 0) {
+            rmSync(path.join(dir, MARKER_FILENAME), { force: true });
+            rmdirSync(dir);
+            this.log(`    ⚙ removed idle checkouts in ${dir}`);
+        }
+    }
+}

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 = [
@@ -25,13 +27,17 @@ function printHelp() {
         'Usage:',
         '  prohost listen --forward-to <local-url> [--api-key <key>] [--url <ws-url>] [--machine <name>] [--subscription-id <id>]',
         '  prohost agent pair --code <pairing-code> [--account <label>] [--webhook-url <https-url>] [--base-url <url>]',
-        "  prohost agent run --exec '<command>' [--idle-timeout <seconds>] [--timeout <seconds>] [--dry-run] [--workdir <dir>]",
+        "  prohost agent run --exec '<command>' [--concurrency <n>] [--repos <checkout,…>] [--idle-timeout <seconds>]",
+        '                    [--timeout <seconds>] [--dry-run] [--workdir <dir>]',
         "  prohost agent install-daemon --exec '<command>' [--workdir <dir>] [--account <label>]   Keep the agent running",
         '  prohost agent uninstall-daemon',
         '  prohost agent account add <label> --runtime claude|codex [--billing subscription|api_key]',
         '  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)',
@@ -53,6 +59,14 @@ function printHelp() {
         '  --timeout        Seconds one run may take before it is killed, however busy it is.',
         '                   Defaults to 0 — no wall-clock limit, because a long run is not a stuck',
         '                   one. Set it if you want a hard ceiling as well as the stall watchdog.',
+        '  --concurrency    How many runs may execute at once, 1 to 16. Defaults to 1. Runs in the same',
+        '                   conversation always take turns, so only different conversations overlap.',
+        '                   Every run spends the same login\'s quota, and they share this machine —',
+        '                   pair it with --repos if the agent edits code.',
+        '  --repos          Comma-separated git checkouts the agent works on. Each conversation gets',
+        '                   its own `git worktree` of every one under $PROHOST_HOME/worktrees, kept for',
+        '                   the life of the thread and removed after 14 idle days if it is clean. The',
+        '                   agent is told to work there and to leave the originals alone.',
         '  --dry-run        Print the reply that would be posted; write nothing.',
         '  --workdir        Working directory for the agent command. Defaults to $PROHOST_HOME/workspace.',
         '                   Avoid pointing it at a code checkout: agents read CLAUDE.md, .claude/settings.json',
@@ -90,9 +104,19 @@ 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, --idle-timeout, --timeout, --machine, --url, --allow-unverified, --safe-tools',
+        '  --workdir, --concurrency, --repos, --idle-timeout, --timeout, --machine, --url,',
+        '  --allow-unverified, --safe-tools',
         '                   — passed to `agent run`.',
         '',
         'Global flags:',
@@ -172,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).`;
+    }
+}