@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/usage-refresh.js

@@ -1,52 +1,3 @@
-/**
- * Daemon-owned usage refresher — one poller per account, on a headed box.
- *
- * The routing hot path (`agents run` → collectRunCandidates) reads usage
- * CACHE-ONLY (`getUsageInfoForIdentity`, RUSH-2061) and never blocks
- * on a provider fetch. A headed box (`isHeadedDeviceRole`) polls only the
- * accounts it holds native logins for; a setup-token-only box never polls.
- * A stray `.credentials.json` for an account another headed box already
- * publishes defers to that poller. Auth-health draws from the same
- * per-account call budget so the two stay under the ~100/hr ceiling.
- *
- * Design:
- *
- *  - **Per-host writer.** Each host lists its own credential-backed accounts
- *    and calls providers directly; there is no cross-host broadcast.
- *  - **Fixed 5-minute cadence** (`REFRESH_INTERVAL_MS`). Enough to keep
- *    balanced/`agents view` off multi-hour stale data without thrashing
- *    provider APIs when the user runs agents frequently. The delay helpers
- *    still accept a burn projection for tests/future tuning, but the default
- *    floor and ceiling are both 5 minutes.
- *  - **Hard hourly cap** (`HOURLY_CALL_CAP`) so a stuck "due" loop cannot
- *    hammer an endpoint past ~12 calls/account/hour.
- *  - **429 backoff.** An account (or provider-wide scope) under
- *    `usageRateLimitedUntil` is skipped — no live fetch or re-armed penalty.
- *  - **File-only credentials on the daemon path.** Refresh never opens the
- *    ACL-bound macOS keychain item (Touch ID storm). It uses the no-ACL
- *    access-token cache / setup-token / `.credentials.json` only
- *    (`fileOnly: true` on `getUsageInfo`).
- *  - **Concurrency-safe cache writes.** Usage + headroom files are updated
- *    under `withFileLock` + atomic rename so a concurrent `agents view`
- *    background refresh cannot tear or drop another account's row.
- *
- * Scenarios (what this path must survive):
- *
- *  1. **Daemon tick overlaps a slow tick** — overlap guard in daemon.ts;
- *     second tick is a no-op.
- *  2. **`agents view` writes cache while daemon refreshes** — file lock
- *     serializes read-modify-write; no lost updates.
- *  3. **macOS keychain ACL / Touch ID** — fileOnly refresh never calls
- *     `security find-generic-password` on Claude's ACL item.
- *  4. **Account 429** — that account is skipped until Retry-After while its
- *     siblings continue; a provider-wide penalty still skips all accounts.
- *  5. **Expired access token (no refresh)** — usage path never rotates
- *     single-use refresh tokens; counts as `failed`, reschedules 5m later.
- *  6. **No file credential on this host** — account skipped / failed; no
- *     keychain fallback from the daemon refresher.
- *  7. **Grok/Codex (network:false)** — not listed by `buildLocalUsageAccounts`;
- *     their "cache" is local logs, not this HTTP refresher.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir, getUserAgentsDir } from './state.js';
@@ -58,30 +9,11 @@ import { isHeadedDeviceRole, selfConfiguredDeviceRole } from './device-config.js
 import { machineId, normalizeHost } from './session/sync/config.js';
 import { readFleetSharedDeviceStates } from './fleet-shared-state.js';
 import { USAGE_SYNC_INTERVAL_MS } from './accounting/usage-sync.js';
-/**
- * Default schedule between successful (or attempted) live usage fetches for one
- * account. Floor and ceiling of the delay helper are pinned to this so the
- * daemon does not poll faster than 5 minutes even under high burn, and does not
- * let an idle account rot longer than 5 minutes between attempts.
- */
 export const REFRESH_INTERVAL_MS = 5 * 60 * 1000;
-/** Burn-rate divisor retained for the pure delay helper / tests; with min=max
- * the divisor does not change the scheduled interval. */
 export const REFRESH_BURN_DIVISOR = 4;
-/** At most this many live fetches per account per rolling hour (5m cadence ⇒ 12). */
 export const HOURLY_CALL_CAP = 12;
-/** How often the daemon wakes to *consider* a refresh pass (due accounts only). */
 export const USAGE_REFRESH_TICK_MS = 60 * 1000;
 const HOUR_MS = 60 * 60 * 1000;
-/**
- * Minimum wall-clock spacing between two live usage fetches to ONE network
- * provider, across all of its accounts. This is the pacing primitive: refreshes
- * are issued round-robin (stalest account first) no faster than one per spacing,
- * so aggregate endpoint load is a smooth, fixed rate — never the synchronized
- * burst-then-stall a plain rolling-hour cap produces when every account falls
- * due on the same tick. Set to two daemon ticks so the floor-based pacing lands
- * on exact tick boundaries (no drift): one refresh every other tick ⇒ 30/hr.
- */
 export const PROVIDER_MIN_REFRESH_SPACING_MS = 2 * USAGE_REFRESH_TICK_MS;
 /**
  * Aggregate live fetches this daemon may spend on ONE network provider's usage
@@ -109,26 +41,11 @@ export const PROVIDER_MIN_REFRESH_SPACING_MS = 2 * USAGE_REFRESH_TICK_MS;
  * grok/codex read local logs and have no rate-limited endpoint.
  */
 export const PROVIDER_HOURLY_BUDGET = HOUR_MS / PROVIDER_MIN_REFRESH_SPACING_MS;
-/**
- * Most refreshes a single tick may catch up after the daemon has been idle/down
- * (elapsed ≫ spacing). Without this clamp a long gap would grant many tokens at
- * once and re-synchronize every account into the very burst the spacing exists
- * to prevent. A small catch-up keeps the load smooth even after a restart.
- */
 export const PROVIDER_CATCHUP_MAX = 2;
-/**
- * A usage row this recently captured (by the free statusline ingest of a live
- * `agents run`, or any writer) is already fresh — do not spend an API call to
- * re-refresh it. Actively-used accounts stay current at zero endpoint cost, so
- * the proactive budget is reserved for genuinely idle accounts.
- */
-/** Consecutive failed live reads before one broken account is quarantined. */
 export const FAILURE_QUARANTINE_THRESHOLD = 3;
-/** A chronic offender waits this long while healthy siblings keep their cadence. */
 export const FAILURE_QUARANTINE_MS = 30 * 60 * 1000;
 const SKIP_JITTER_MIN_MS = 2_000;
 const SKIP_JITTER_RANGE_MS = 3_001;
-/** Test seam for the headroom cache path (see usage.ts `setClaudeUsageCachePathForTest`). */
 let headroomCachePathOverride = null;
 export function setHeadroomCachePathForTest(cachePath) {
     const prev = headroomCachePathOverride;
@@ -138,7 +55,6 @@ export function setHeadroomCachePathForTest(cachePath) {
 function headroomCachePath() {
     return headroomCachePathOverride ?? path.join(getCacheDir(), '.usage-headroom.json');
 }
-/** Read the whole headroom cache (best-effort; missing/corrupt → empty map). */
 function readHeadroomCache() {
     try {
         const parsed = JSON.parse(fs.readFileSync(headroomCachePath(), 'utf-8'));
@@ -146,21 +62,17 @@ function readHeadroomCache() {
             return parsed.entries;
     }
     catch {
-        // missing or corrupt — treat as empty
     }
     return {};
 }
-/** Read one account's headroom entry, or null. */
 export function readHeadroomEntry(usageKey) {
     return readHeadroomCache()[usageKey] ?? null;
 }
-/** Merge entries into the cache (best-effort; preserves other accounts' rows). */
 export function writeHeadroomEntries(entries) {
     try {
         const cachePath = headroomCachePath();
         ensureLockTarget(cachePath, JSON.stringify({ version: 1, entries: {} }, null, 2));
         withFileLock(cachePath, () => {
-            // Re-read under the lock so a concurrent tick/view cannot drop rows.
             const merged = {
                 version: 1,
                 entries: { ...readHeadroomCache(), ...entries },
@@ -169,15 +81,8 @@ export function writeHeadroomEntries(entries) {
         });
     }
     catch {
-        // best-effort; a failed write just means the router sees no projection
     }
 }
-/**
- * Interval until the next refresh attempt, clamped to [minMs, maxMs].
- * Defaults pin both ends to {@link REFRESH_INTERVAL_MS} (5 minutes) so the
- * live daemon path is a fixed schedule. Tests may pass a wider range to
- * exercise burn-aware scheduling without changing production cadence.
- */
 export function computeNextRefreshDelayMs(minutesToLimit, opts = {}) {
     const minMs = opts.minMs ?? REFRESH_INTERVAL_MS;
     const maxMs = opts.maxMs ?? REFRESH_INTERVAL_MS;
@@ -187,16 +92,10 @@ export function computeNextRefreshDelayMs(minutesToLimit, opts = {}) {
     const targetMs = (minutesToLimit / divisor) * 60_000;
     return Math.max(minMs, Math.min(maxMs, targetMs));
 }
-/** Recent call timestamps trimmed to the trailing hour. */
 export function pruneCallTimestamps(timestamps, now, windowMs = HOUR_MS) {
     const floor = now - windowMs;
     return timestamps.filter((ts) => ts > floor);
 }
-/**
- * Whether an account may be live-refreshed right now: it is due (past its
- * scheduled `nextRefreshAt`) AND under the rolling-hour call cap. Pure so the
- * cadence + cap arithmetic is unit-tested without a daemon or a network call.
- */
 export function shouldRefreshAccount(entry, now, opts = {}) {
     const cap = opts.hourlyCap ?? HOURLY_CALL_CAP;
     const windowMs = opts.windowMs ?? HOUR_MS;
@@ -206,11 +105,6 @@ export function shouldRefreshAccount(entry, now, opts = {}) {
     const recent = pruneCallTimestamps(entry?.callTimestamps ?? [], now, windowMs);
     return recent.length < cap;
 }
-/**
- * Build the next headroom entry after a live refresh: project headroom from the
- * new snapshot against the prior sample, schedule the next refresh from the
- * projection, and record this call for the hourly cap.
- */
 export function nextHeadroomEntry(prev, snapshot, now) {
     const headroom = deriveUsageHeadroom(snapshot, prev && prev.capturedAt !== null && prev.sessionUsedPercent !== null
         ? { capturedAt: prev.capturedAt, usedPercent: prev.sessionUsedPercent }
@@ -228,7 +122,6 @@ export function nextHeadroomEntry(prev, snapshot, now) {
         consecutiveFailures: snapshot ? 0 : (prev?.consecutiveFailures ?? 0) + 1,
     };
 }
-/** Stable per-account delay in [2s, 5s], used to spread skipped accounts. */
 function skipJitterMs(usageKey) {
     let hash = 0;
     for (const char of usageKey)
@@ -247,17 +140,9 @@ function skippedHeadroomEntry(prev, usageKey, now, index) {
         consecutiveFailures: prev?.consecutiveFailures ?? 0,
     };
 }
-/**
- * Reschedule an account we skipped because a free statusline ingest already
- * captured it inside {@link REFRESH_INTERVAL_MS}. The statusline row IS a real,
- * live sample, so RE-DERIVE headroom (status / minutesToLimit) from it against
- * the prior sample — otherwise `status`/`minutesToLimit` would freeze at their
- * last API-refresh value forever for exactly the actively-used accounts that
- * stay statusline-fresh, and `capacityWeight` reads `minutesToLimit`. No call
- * timestamp is recorded (this cost zero API budget); the next proactive attempt
- * is pushed to one interval past the free capture.
- */
 function freshHeadroomEntry(prev, snapshot, now, capturedAtMs) {
+    // A recent statusline row is a free live sample: re-derive headroom without
+    // recording an API call, then schedule the next proactive refresh from it.
     const headroom = deriveUsageHeadroom(snapshot, prev && prev.capturedAt !== null && prev.sessionUsedPercent !== null
         ? { capturedAt: prev.capturedAt, usedPercent: prev.sessionUsedPercent }
         : null);
@@ -268,18 +153,11 @@ function freshHeadroomEntry(prev, snapshot, now, capturedAtMs) {
         sessionUsedPercent: session?.usedPercent ?? prev?.sessionUsedPercent ?? null,
         capturedAt: snapshot.capturedAt?.getTime() ?? prev?.capturedAt ?? null,
         nextRefreshAt: capturedAtMs + REFRESH_INTERVAL_MS,
-        // Not an API call — do NOT record a timestamp (would wrongly spend budget).
         callTimestamps: pruneCallTimestamps(prev?.callTimestamps ?? [], now),
         computedAt: now,
         consecutiveFailures: 0,
     };
 }
-/**
- * Most-recent live-fetch time per network provider (the max call timestamp
- * across its accounts, 0 when none), which the smooth per-provider pacing spaces
- * the next refresh from. Non-network providers are omitted — they have no
- * rate-limited endpoint to pace.
- */
 export function providerLastCall(accounts, cache) {
     const last = new Map();
     for (const account of accounts) {
@@ -294,19 +172,7 @@ export function providerLastCall(accounts, cache) {
     }
     return last;
 }
-/**
- * How many live fetches the smooth pacing permits a provider THIS tick: one per
- * elapsed {@link PROVIDER_MIN_REFRESH_SPACING_MS} since its last fetch, clamped
- * to {@link PROVIDER_CATCHUP_MAX} so a long idle gap (or a cold provider with no
- * prior fetch) cannot re-burst the whole due set at once. At the daemon's 60 s
- * tick this yields at most one fetch every other tick in steady state (⇒ the
- * hourly budget), while a small fleet whose total demand fits under budget is
- * never throttled — the {@link PROVIDER_HOURLY_BUDGET} rolling cap is the only
- * gate that binds it.
- */
 export function providerSpacingTokens(lastCallMs, now) {
-    // A cold provider (never fetched) is treated as maximally idle: grant the
-    // catch-up ceiling so a couple of accounts warm immediately without bursting.
     const elapsed = lastCallMs <= 0 ? Infinity : now - lastCallMs;
     if (elapsed < PROVIDER_MIN_REFRESH_SPACING_MS)
         return 0;
@@ -319,20 +185,14 @@ function failedHeadroomEntry(prev, now) {
     }
     return next;
 }
-/**
-/** Daemon auth-health may hit `/oauth/usage` only on a headed box, unless forceLive. */
 export function mayIssueUsageEndpointProbe(opts) {
     if (opts.forceLive === true)
         return true;
     return isHeadedDeviceRole(opts.role);
 }
-/**
- * Sticky one-poller election: lex-least among this box (if it holds a native
- * login) and peer devices that published a `freshnessSource=poll` row. Statusline
- * ingest does not claim. Two headed boxes therefore converge on one poller
- * instead of each deferring to the other.
- */
 export function electUsagePoller(opts) {
+    // Only native-login headed devices contend; statusline ingest never claims
+    // ownership. Lexical election converges multiple headed devices on one poller.
     const names = new Set();
     if (opts.selfHoldsNativeLogin)
         names.add(normalizeHost(opts.selfDevice));
@@ -356,13 +216,11 @@ export function shouldPollUsageAccount(candidate, opts) {
     });
     return elected === normalizeHost(opts.selfDevice);
 }
-/** Native rotating login on this home — Claude's `.credentials.json` blob, else a credential file. */
 export function homeHoldsNativeLogin(agentId, home) {
     if (agentId === 'claude')
         return claudeHomeHasNativeOauthFile(home);
     return credentialPresence(agentId, home).perVersion;
 }
-/** usageKey → devices that published a `poll` row (statusline/sync do not claim). */
 export function pollerClaimsFromSharedStore(selfDevice, userAgentsDir = getUserAgentsDir()) {
     const claims = {};
     const read = readFleetSharedDeviceStates(userAgentsDir);
@@ -387,13 +245,8 @@ export function pollerClaimsFromSharedStore(selfDevice, userAgentsDir = getUserA
     }
     return claims;
 }
-/**
- * Spend one live usage-endpoint call from the shared per-account / per-provider
- * budget. Auth-health and the usage poller both go through here so they cannot
- * together exceed {@link PROVIDER_HOURLY_BUDGET} (~30/hr, well under ~100/hr).
- * Returns false when the call must not fire.
- */
 export function trySpendUsageApiCall(usageKey, agentId, now) {
+    // Auth-health and refresh share this per-account and per-provider budget.
     if (!agentUsesNetworkUsage(agentId))
         return true;
     const cache = readHeadroomCache();
@@ -425,19 +278,8 @@ export function trySpendUsageApiCall(usageKey, agentId, now) {
     });
     return true;
 }
-/**
- * Order a pass STALEST-FIRST so a scarce per-provider budget
- * ({@link PROVIDER_HOURLY_BUDGET}) is always spent on the accounts most in need
- * of a fresh reading, and no account is starved indefinitely.
- *
- *  - **Cold accounts** (never refreshed → no cache entry) are maximally stale
- *    and lead the pass. They rotate by `tick` so, when the budget can't cover
- *    them all in one tick, a different cold account leads each tick.
- *  - **Cached accounts** follow, oldest `capturedAt` first (a null capture time
- *    counts as maximally stale). As accounts refresh their `capturedAt` advances,
- *    so the next pass naturally rotates to whoever is now most out of date.
- */
 export function orderUsageAccounts(accounts, cache, tick) {
+    // Spend scarce provider budget stalest-first; rotate cold accounts per tick.
     const rotate = (group) => {
         if (group.length < 2)
             return group;
@@ -450,13 +292,6 @@ export function orderUsageAccounts(accounts, cache, tick) {
     const byStalest = [...cached].sort((a, b) => staleness(a) - staleness(b));
     return [...rotate(cold), ...byStalest];
 }
-/**
- * Aggregate live calls a network provider has already spent in the trailing hour,
- * summed across the accounts in this pass. Seeds the per-provider budget counter
- * so {@link PROVIDER_HOURLY_BUDGET} bounds the rolling-hour total, not just this
- * one tick. Non-network providers (grok/codex, local logs) are excluded — they
- * have no rate-limited endpoint to budget.
- */
 export function providerRecentCalls(accounts, cache, now) {
     const counts = new Map();
     for (const account of accounts) {
@@ -467,11 +302,6 @@ export function providerRecentCalls(accounts, cache, now) {
     }
     return counts;
 }
-/**
- * Enumerate the usage accounts THIS headed box should poll — native logins it
- * holds, minus accounts another headed poller already claims. A worker or
- * setup-token-only box returns [].
- */
 export async function buildLocalUsageAccounts(opts = {}) {
     const role = opts.role ?? selfConfiguredDeviceRole();
     if (!isHeadedDeviceRole(role))
@@ -492,16 +322,13 @@ export async function buildLocalUsageAccounts(opts = {}) {
         for (const [usageKey, fetchInput] of usageFetchInputs) {
             const canonical = canonicalByUsageKey.get(usageKey);
             if (!canonical?.signedIn)
-                continue; // only refresh accounts actually usable here
+                continue;
             const home = fetchInput.home ?? getVersionHomePath(agentId, fetchInput.cliVersion ?? '');
             if (!shouldPollUsageAccount({ usageKey, holdsNativeLogin: nativeAt(agentId, home) }, { role, selfDevice, peerPollers: claimedBy[usageKey] }))
                 continue;
             accounts.push({
                 usageKey,
                 agentId,
-                // Native file login: skip setup-token (403s on /oauth/usage) and the
-                // ACL keychain (Touch ID). Linux headed boxes store the rotating blob
-                // in `.credentials.json`; a missing file is a no-op fetch.
                 fetch: async (signal) => {
                     const { getUsageInfoForIdentity } = await import('./accounting/usage.js');
                     return getUsageInfoForIdentity({
@@ -516,12 +343,6 @@ export async function buildLocalUsageAccounts(opts = {}) {
     }
     return accounts;
 }
-/**
- * One refresher tick: for each local account that is due, under its hourly cap,
- * and not backed off, live-fetch its usage, update the cache, and
- * reschedule from the new burn projection. Never throws — a single account's
- * failed fetch leaves its cache untouched and counts as `failed`.
- */
 export async function runUsageRefresh(deps) {
     const now = deps.now ?? Date.now();
     const result = {
@@ -535,15 +356,6 @@ export async function runUsageRefresh(deps) {
     };
     const cache = readHeadroomCache();
     const accounts = orderUsageAccounts(await deps.listAccounts(), cache, Math.floor(now / USAGE_REFRESH_TICK_MS));
-    // Per-provider pacing. Two gates keep aggregate endpoint load smooth and bounded:
-    //  - a rolling-hour ceiling (PROVIDER_HOURLY_BUDGET) — the hard cap, seeded
-    //    with calls already spent in the trailing hour;
-    //  - a min-spacing token count (PROVIDER_MIN_REFRESH_SPACING_MS) — the smoother,
-    //    which issues refreshes round-robin at a fixed rate instead of the
-    //    synchronized burst-then-stall a plain rolling cap produces when every
-    //    account falls due on the same tick.
-    // Both are per-provider and network-only; accounts are ordered stalest-first, so
-    // the scarce budget always serves the account most in need and none is starved.
     const budgetSpent = providerRecentCalls(accounts, cache, now);
     const lastCall = providerLastCall(accounts, cache);
     const spacingTokens = new Map();
@@ -555,8 +367,6 @@ export async function runUsageRefresh(deps) {
     for (const [index, account] of accounts.entries()) {
         const entry = cache[account.usageKey] ?? null;
         const network = agentUsesNetworkUsage(account.agentId);
-        // A penalized account/provider is off-limits — poking it re-arms the
-        // penalty (the whole reason usage-backoff exists).
         if ((deps.backoffUntil(account.agentId, account.usageKey) ?? 0) > now) {
             updates[account.usageKey] = skippedHeadroomEntry(entry, account.usageKey, now, index);
             result.skippedBackoff += 1;
@@ -569,10 +379,6 @@ export async function runUsageRefresh(deps) {
                 result.skippedCap += 1;
             continue;
         }
-        // A live `agents run` already refreshed this account's usage row for free via
-        // the statusline ingest — re-derive headroom from that row and skip the API
-        // call. Network providers only: a local-log provider's cache is always its
-        // own last write, so this must not suppress its refresh (grok/codex).
         if (network) {
             const cached = deps.readCachedSnapshot?.(account.usageKey) ?? null;
             const capturedAtMs = cached?.capturedAt?.getTime() ?? null;
@@ -582,15 +388,10 @@ export async function runUsageRefresh(deps) {
                 continue;
             }
         }
-        // Global per-provider budget: cap aggregate endpoint traffic so it does not
-        // scale linearly with account count and trip the ~100/hr rate limit, and pace
-        // it smoothly. Non-network providers (local logs) have no endpoint to protect.
         if (network) {
             const overHourly = (budgetSpent.get(account.agentId) ?? 0) >= PROVIDER_HOURLY_BUDGET;
             const overSpacing = (spacingUsed.get(account.agentId) ?? 0) >= (spacingTokens.get(account.agentId) ?? 0);
             if (overHourly || overSpacing) {
-                // Leave the entry untouched so this still-due account competes again next
-                // tick, when budget/spacing frees — never starved (stalest-first serves it).
                 result.skippedBudget += 1;
                 continue;
             }
@@ -600,9 +401,6 @@ export async function runUsageRefresh(deps) {
         try {
             const usage = await account.fetch(deps.signal);
             if (usage.snapshot) {
-                // `source` is provenance, not freshness. A forced collection that just
-                // reread a local harness event returns `last_seen`; that is still a
-                // successful collection and belongs in the shared read cache.
                 const stamped = deps.pollerDevice
                     ? { ...usage.snapshot, freshness: { source: 'poll', poller: deps.pollerDevice } }
                     : usage.snapshot;
@@ -612,14 +410,12 @@ export async function runUsageRefresh(deps) {
                 refreshedKeys.push(account.usageKey);
             }
             else {
-                // No live snapshot (expired token / fetch miss): don't rewrite the usage
-                // cache, but still record the call + reschedule so a broken account
-                // isn't retried every tick.
                 updates[account.usageKey] = failedHeadroomEntry(entry, now);
                 result.failed += 1;
             }
         }
         catch {
+            // A failed fetch changes headroom scheduling only, never the usage cache.
             updates[account.usageKey] = failedHeadroomEntry(entry, now);
             result.failed += 1;
         }

package/dist/lib/verbs.d.ts

@@ -1,15 +1,4 @@
 import type { Command } from 'commander';
-/**
- * The ONE place that defines the CLI's standard short-form verb aliases.
- *
- * These are the canonical short forms an agent or user reaches for on a
- * command group's CRUD verbs — `ls` for `list`, `rm` for `remove`, and so on.
- * They are NOT cross-verb synonyms (`info`/`install`/`create`); those are
- * per-command back-compat aliases owned by the individual commands.
- *
- * Apply them with {@link withAliases} so every group stays in lockstep instead
- * of each command hand-rolling its own `.alias('rm')`.
- */
 export declare const CANONICAL_ALIASES: {
     readonly list: readonly ["ls"];
     readonly view: readonly ["show"];
@@ -19,6 +8,5 @@ export declare const CANONICAL_ALIASES: {
     readonly edit: readonly [];
 };
 type CanonicalVerb = keyof typeof CANONICAL_ALIASES;
-/** Apply the standard aliases for `verb` to an already-created subcommand, returning it. */
 export declare function withAliases(cmd: Command, verb: CanonicalVerb): Command;
 export {};

package/dist/lib/verbs.js

@@ -1,14 +1,3 @@
-/**
- * The ONE place that defines the CLI's standard short-form verb aliases.
- *
- * These are the canonical short forms an agent or user reaches for on a
- * command group's CRUD verbs — `ls` for `list`, `rm` for `remove`, and so on.
- * They are NOT cross-verb synonyms (`info`/`install`/`create`); those are
- * per-command back-compat aliases owned by the individual commands.
- *
- * Apply them with {@link withAliases} so every group stays in lockstep instead
- * of each command hand-rolling its own `.alias('rm')`.
- */
 export const CANONICAL_ALIASES = {
     list: ['ls'],
     view: ['show'],
@@ -17,7 +6,6 @@ export const CANONICAL_ALIASES = {
     rename: ['mv'],
     edit: [],
 };
-/** Apply the standard aliases for `verb` to an already-created subcommand, returning it. */
 export function withAliases(cmd, verb) {
     const aliases = CANONICAL_ALIASES[verb];
     return aliases.length ? cmd.aliases([...aliases]) : cmd;

package/dist/lib/version-duplicates.d.ts

@@ -9,12 +9,6 @@ interface NewerDuplicateVersion {
     email: string | null;
     plan: string | null;
 }
-/**
- * Return installed versions newer than selectedVersion that share the same
- * account identity. This is intentionally pure so command output can share one
- * duplicate rule with tests.
- */
 export declare function findNewerDuplicateVersions(entries: VersionAccountEntry[], selectedVersion: string): NewerDuplicateVersion[];
-/** Format the non-interactive guidance shown by view/run when duplicates exist. */
 export declare function formatNewerDuplicateNotice(agentId: AgentId, selectedVersion: string, duplicates: NewerDuplicateVersion[], selectedLabel?: string): string;
 export {};

package/dist/lib/version-duplicates.js

@@ -10,11 +10,6 @@ function duplicateIdentity(info) {
         return usageKey;
     return info.email ? `email:${info.email.toLowerCase()}` : null;
 }
-/**
- * Return installed versions newer than selectedVersion that share the same
- * account identity. This is intentionally pure so command output can share one
- * duplicate rule with tests.
- */
 export function findNewerDuplicateVersions(entries, selectedVersion) {
     const selected = entries.find((entry) => entry.version === selectedVersion);
     const selectedIdentity = duplicateIdentity(selected?.info);
@@ -31,7 +26,6 @@ export function findNewerDuplicateVersions(entries, selectedVersion) {
         plan: entry.info.plan,
     }));
 }
-/** Format the non-interactive guidance shown by view/run when duplicates exist. */
 export function formatNewerDuplicateNotice(agentId, selectedVersion, duplicates, selectedLabel = '') {
     if (duplicates.length === 0)
         return '';

package/dist/lib/version.d.ts

@@ -1,66 +1,11 @@
-/**
- * Well-known locations of the `agents` launcher for PATH-less GUI/launchd
- * processes (the menu-bar helper inherits no login PATH). Also the anchor for
- * recovering the on-disk install layout when the CLI runs as a Bun single-file
- * binary — see {@link resolveInstalledLayout}.
- */
 export declare function resolveAgentsBin(): string | null;
 interface InstallLayout {
-    /** The install's `dist/` directory (holds `index.js` + `lib/`). */
     distDir: string;
-    /** The compiled CLI entry, `dist/index.js`. */
     entryPath: string;
-    /** The shipping `package.json`, `dist/../package.json`. */
     pkgJsonPath: string;
 }
-/**
- * Pure derivation (no I/O) of an install's on-disk layout from the realpath of
- * its `agents` launcher. A launcher lives at `<pkg>/dist/bin/agents`, so two
- * levels up is `<pkg>/dist`. Exported for unit testing so the dirname chain the
- * Bun-binary fallback depends on stays locked.
- */
 export declare function installLayoutFromBin(realBin: string): InstallLayout;
-/**
- * Resolve the on-disk install layout of the running CLI by following the
- * `agents` launcher symlink.
- *
- * When the CLI runs as a Bun single-file executable, `import.meta.url` points
- * inside the virtual bundle (`/$bunfs/…`), so sibling-relative resolution can't
- * see the shipped `package.json`, `dist/index.js`, or `MenubarHelper.app` on
- * disk. The launcher symlink points at the real files; walk up from it. Returns
- * null when no launcher is found (dev/tsx runs, or a box without the helper) —
- * callers keep their in-bundle resolution as the primary path and use this only
- * as the fallback.
- */
 export declare function resolveInstalledLayout(): InstallLayout | null;
-/**
- * Resolve the CLI version from the shipping package.json. Used by the daemon
- * to answer `IPCAction: 'version'` and by the client to detect daemon drift —
- * a dev-build CLI talking to a launchd-managed registry daemon would silently
- * get stale behavior without this check.
- *
- * Primary read is relative to this module; when that fails (the Bun single-file
- * binary can't read its own bundled package.json), fall back to the on-disk
- * install found via the launcher symlink so callers like the menu bar don't see
- * a bogus `unknown`.
- *
- * `pkgJsonPath` is an optional override of the shipping package.json path,
- * accepted by both this function and {@link getCliVersionFresh}. Every
- * production call site uses the zero-argument form and gets the real on-disk
- * path below; the parameter exists only so a unit test can point both
- * functions at a fixture package.json instead of the real one shared by every
- * parallel test fork.
- */
 export declare function getCliVersion(pkgJsonPath?: string): string;
-/**
- * Read the version from package.json on disk every call, bypassing the cache.
- *
- * `getCliVersion()` memoizes the version a long-running process *started* with.
- * After `npm i -g` overwrites the install in place, the on-disk package.json
- * changes but the running process keeps its old in-memory code. Comparing this
- * fresh read against the cached startup value is how a daemon/broker detects it
- * is now stale and should reload onto the new code (self-healing). Returns
- * 'unknown' on any error.
- */
 export declare function getCliVersionFresh(pkgJsonPath?: string): string;
 export {};