@phnx-labs/agents-cli 1.22.46 → 1.22.47

package/dist/lib/accounting/usage.js

@@ -118,6 +118,57 @@ export function usageUnreachableError(agent, cause) {
         ? `${agent} usage read failed: ${detail}`
         : `${agent} usage read failed.`;
 }
+/**
+ * Marker for a log-based (`network: false`) provider — Codex, Grok — that has
+ * simply never recorded a rate-limit event on this machine yet: no session
+ * log exists, or no session in it carries usage data. Distinct on purpose from
+ * `usageUnreachableError`: that one means the local log COULDN'T be read (a
+ * real failure worth surfacing distinctly); this one means there is nothing to
+ * read because the account has not run here, which is expected for a fresh
+ * install and should render as a benign state, not an error (RUSH-3040).
+ */
+export const USAGE_NO_RECENT_USAGE_MARKER = 'no usage recorded yet';
+export const USAGE_BENIGN_STATE = Symbol('usageBenignState');
+/**
+ * Shared error-classification + 429 backoff for a networked usage fetch whose
+ * only signal is an HTTP status (or none at all, on a network failure) —
+ * Antigravity's :retrieveUserQuota and Muse's Meta Model API probe are both
+ * this shape. They were added to `USAGE_SOURCES` after the four original
+ * `usageXError` constructors and did not get their own scheme (usage.ts's
+ * error handling was written for "four networked providers"; RUSH-3040).
+ * Route every no-snapshot outcome for either through this one function so a
+ * future entry cannot be added second-class again — it owns noting the 429
+ * backoff, so callers must NOT also call {@link noteUsageRateLimited} for the
+ * same response.
+ */
+export function classifyUsageFetchFailure(agent, agentId, status, retryAfterHeader, usageScope) {
+    if (status === 429) {
+        noteUsageRateLimited(agentId, retryAfterHeader ?? null, { account: usageScope });
+        return usageRejectedError(agent, 429);
+    }
+    if (status !== null)
+        return usageRejectedError(agent, status);
+    return usageUnreachableError(agent);
+}
+/** Classify a `UsageInfo.error` string into its {@link UsageErrorKind}, or null when there is no error. */
+export function classifyUsageErrorKind(error) {
+    if (!error)
+        return null;
+    if (isUsageHeadlessScopeError(error))
+        return 'headless-scope';
+    if (error.startsWith('No readable '))
+        return 'no-credential';
+    if (error.includes('credential expired'))
+        return 'expired-credential';
+    if (error.includes('rate-limited this machine') || error.includes('is rate-limiting the usage endpoint')) {
+        return 'rate-limited';
+    }
+    if (error.includes('rejected the usage read'))
+        return 'rejected';
+    if (error.includes('usage read failed'))
+        return 'unreachable';
+    return 'rejected';
+}
 /**
  * True when a Claude OAuth access token is within the refresh leeway of expiry
  * (or already expired) — i.e. it "would need a refresh" before the next use.
@@ -165,6 +216,14 @@ const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
 const EMPTY = '\u2591';
+/** Construct the benign no-local-log result without overloading `error`. */
+export function usageNoRecentUsageInfo() {
+    return { snapshot: null, error: null, [USAGE_BENIGN_STATE]: 'no-recent-usage' };
+}
+/** Read a benign state for the human renderer; symbols are omitted by JSON serialization. */
+export function getUsageBenignState(info) {
+    return info[USAGE_BENIGN_STATE] ?? null;
+}
 /** The single registry of agent usage sources and their transport. */
 const USAGE_SOURCES = {
     claude: { fetch: getClaudeUsageInfo, network: true },
@@ -333,6 +392,9 @@ async function fetchLiveUsageDeduped(input, usageKey, cached, fileOnly) {
                 home: input.home,
                 cliVersion: input.cliVersion,
                 organizationId: input.info.organizationId,
+                // Scope this fetch's 429 backoff to the account being fetched, so one
+                // throttled account cannot park the whole provider (RUSH-3036).
+                usageScope: usageKey,
                 fileOnly,
             });
             if (usage.snapshot) {
@@ -391,6 +453,26 @@ export function pickCompactUsageWindows(windows, maxWindows) {
     }
     return chosen;
 }
+/** Human label for a classified usage error, for the no-bars branch of {@link formatUsageSummary}. */
+function formatUsageErrorKindLabel(kind, detail) {
+    switch (kind) {
+        case 'no-credential':
+            return 'sign in / provision token';
+        case 'expired-credential':
+            return 're-auth for usage';
+        case 'rate-limited': {
+            const retryHint = detail?.match(/not retrying for (.+)\.$/)?.[1] ?? null;
+            return retryHint ? `rate-limited (retry ~${retryHint})` : 'rate-limited';
+        }
+        case 'rejected':
+        case 'unreachable':
+        case 'headless-scope':
+        case null:
+        case undefined:
+        default:
+            return 'usage unavailable';
+    }
+}
 /** Format a one-line usage summary with compact bars for inline display. */
 export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
     const parts = [];
@@ -445,11 +527,16 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         // mistaken for a missing setup-token or seeding failure (RUSH-2392).
         parts.push(chalk.dim(USAGE_HEADLESS_SCOPE_MARKER));
     }
+    else if (opts?.benignState === 'no-recent-usage') {
+        parts.push(chalk.dim(USAGE_NO_RECENT_USAGE_MARKER));
+    }
     else if (opts?.unavailable) {
         // Signed-in account we could NOT fetch usage for (no live token in a reachable
         // home / org mismatch / fetch error). Say so explicitly instead of drawing a
-        // blank gauge that reads like "0% used".
-        parts.push(chalk.dim('usage unavailable'));
+        // blank gauge that reads like "0% used" — and name the SPECIFIC cause when
+        // the caller passed one, rather than the generic bucket that used to cover
+        // ~6 different failures (RUSH-3040).
+        parts.push(chalk.dim(formatUsageErrorKindLabel(opts.errorKind, opts.errorDetail)));
     }
     return parts.join('  ');
 }
@@ -598,11 +685,17 @@ async function getCodexUsageInfo(options) {
             return { snapshot: null, error: null };
         }
         const files = collectCodexSessionFiles(options?.home, sinceMs);
+        const now = new Date();
         for (const filePath of files) {
             const match = await readLatestCodexRateLimits(filePath);
             if (!match)
                 continue;
-            const windows = normalizeCodexWindows(match.rateLimits);
+            // Same freshness filter Grok already applies (RUSH-3040): a window whose
+            // reset time or windowMinutes-derived expiry has passed is a STALE read,
+            // not a current one — rendering it as-is is how a codex bar kept showing
+            // "100% used" past its own reset. Try the next-older session file rather
+            // than surfacing a stale bar.
+            const windows = normalizeCodexWindows(match.rateLimits).filter((window) => isCachedUsageWindowFresh(window, match.capturedAt, now));
             if (windows.length === 0)
                 continue;
             return {
@@ -615,10 +708,14 @@ async function getCodexUsageInfo(options) {
                 error: null,
             };
         }
-        return { snapshot: null, error: null };
+        // No session ever recorded a rate-limit event on this machine (or none of
+        // the ones found were still fresh) — a benign "nothing to show yet", not a
+        // failure (RUSH-3040). Distinct from the outer catch below, which is a
+        // genuine read/parse failure.
+        return usageNoRecentUsageInfo();
     }
-    catch {
-        return { snapshot: null, error: null };
+    catch (err) {
+        return { snapshot: null, error: usageUnreachableError('Codex', err) };
     }
 }
 /**
@@ -671,7 +768,7 @@ async function getClaudeUsageInfo(options) {
         }
         // Honour a live Retry-After rather than re-arming the penalty (see
         // usage-backoff.ts). No request at all while the window is open.
-        const throttledUntil = usageRateLimitedUntil('claude');
+        const throttledUntil = usageRateLimitedUntil('claude', Date.now(), options?.usageScope);
         if (throttledUntil) {
             return { snapshot: null, error: usageThrottledError('Claude', throttledUntil) };
         }
@@ -687,7 +784,7 @@ async function getClaudeUsageInfo(options) {
         });
         if (!response.ok) {
             if (response.status === 429) {
-                noteUsageRateLimited('claude', response.headers.get('retry-after'));
+                noteUsageRateLimited('claude', response.headers.get('retry-after'), { account: options?.usageScope });
             }
             // Setup-token is user:inference only; usage needs user:profile → 403
             // with a scope-requirement body. Distinct from a real rejection so the
@@ -780,7 +877,7 @@ async function getKimiUsageInfo(options) {
         }
         // Honour a live Retry-After rather than re-arming the penalty (see
         // usage-backoff.ts). No request at all while the window is open.
-        const throttledUntil = usageRateLimitedUntil('kimi');
+        const throttledUntil = usageRateLimitedUntil('kimi', Date.now(), options?.usageScope);
         if (throttledUntil) {
             return { snapshot: null, error: usageThrottledError('Kimi', throttledUntil) };
         }
@@ -796,7 +893,7 @@ async function getKimiUsageInfo(options) {
         // way there are no bars to draw, and the status is what tells them apart.
         if (!response.ok) {
             if (response.status === 429) {
-                noteUsageRateLimited('kimi', response.headers.get('retry-after'));
+                noteUsageRateLimited('kimi', response.headers.get('retry-after'), { account: options?.usageScope });
             }
             return { snapshot: null, error: usageRejectedError('Kimi', response.status) };
         }
@@ -914,7 +1011,7 @@ async function getDroidUsageInfo(options) {
         }
         // Honour a live Retry-After rather than re-arming the penalty (see
         // usage-backoff.ts). No request at all while the window is open.
-        const throttledUntil = usageRateLimitedUntil('droid');
+        const throttledUntil = usageRateLimitedUntil('droid', Date.now(), options?.usageScope);
         if (throttledUntil) {
             return { snapshot: null, error: usageThrottledError('Droid', throttledUntil) };
         }
@@ -929,7 +1026,7 @@ async function getDroidUsageInfo(options) {
         // 401 => revoked/expired token. No bars to draw, and the status says why.
         if (!response.ok) {
             if (response.status === 429) {
-                noteUsageRateLimited('droid', response.headers.get('retry-after'));
+                noteUsageRateLimited('droid', response.headers.get('retry-after'), { account: options?.usageScope });
             }
             return { snapshot: null, error: usageRejectedError('Droid', response.status) };
         }
@@ -956,7 +1053,7 @@ async function getDroidUsageInfo(options) {
     }
 }
 /** Probe Claude's OAuth token against the usage endpoint. Never refreshes — reports `expired` for a near-expiry token; see the comment below (RUSH-1822). */
-export async function probeClaudeStatus(home, cliVersion) {
+export async function probeClaudeStatus(home, cliVersion, usageScope) {
     // accessTokenCache: the daemon warms this probe every ~3 min per account, so it
     // reads ONLY the file-based setup-token and never the interactive login —
     // transmitting that ACL-bound token to the usage API from a background loop is
@@ -981,7 +1078,7 @@ export async function probeClaudeStatus(home, cliVersion) {
     // window is open, report the throttle from the recorded state instead of
     // firing again and re-arming it (usage-backoff.ts). This 3-min-cadence
     // probe is what created the loop it now respects.
-    if (usageRateLimitedUntil('claude'))
+    if (usageRateLimitedUntil('claude', Date.now(), usageScope))
         return { status: 429, token: 'present' };
     try {
         const response = await fetch(CLAUDE_USAGE_URL, {
@@ -995,7 +1092,7 @@ export async function probeClaudeStatus(home, cliVersion) {
             signal: AbortSignal.timeout(8000),
         });
         if (response.status === 429) {
-            noteUsageRateLimited('claude', response.headers.get('retry-after'));
+            noteUsageRateLimited('claude', response.headers.get('retry-after'), { account: usageScope });
         }
         // Setup-token is user:inference only; usage needs user:profile → 403.
         // That is NOT a revocation — the account still runs (RUSH-2392).
@@ -1023,7 +1120,7 @@ export async function probeClaudeStatus(home, cliVersion) {
     }
 }
 /** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
-export async function probeKimiStatus(home) {
+export async function probeKimiStatus(home, usageScope) {
     const credPath = resolveKimiCredentialPath(home);
     if (!credPath)
         return { status: null, token: 'missing' };
@@ -1047,7 +1144,7 @@ export async function probeKimiStatus(home) {
     // is what created the loop it now respects. It sits AFTER the local
     // missing/expired checks — as in probeClaudeStatus and probeDroidStatus — so
     // a genuinely broken credential is never misreported as merely throttled.
-    if (usageRateLimitedUntil('kimi'))
+    if (usageRateLimitedUntil('kimi', Date.now(), usageScope))
         return { status: 429, token: 'present' };
     try {
         const response = await fetch(KIMI_USAGES_URL, {
@@ -1056,7 +1153,7 @@ export async function probeKimiStatus(home) {
             signal: AbortSignal.timeout(8000),
         });
         if (response.status === 429) {
-            noteUsageRateLimited('kimi', response.headers.get('retry-after'));
+            noteUsageRateLimited('kimi', response.headers.get('retry-after'), { account: usageScope });
         }
         return { status: response.status, token: 'present' };
     }
@@ -1065,7 +1162,7 @@ export async function probeKimiStatus(home) {
     }
 }
 /** Probe Droid's WorkOS token against the billing-limits endpoint. Never refreshes (single-use rotation — see getDroidUsageInfo). */
-export async function probeDroidStatus(home) {
+export async function probeDroidStatus(home, usageScope) {
     const cred = decryptDroidAuthPayload(home || os.homedir());
     const accessToken = cred?.access_token;
     if (typeof accessToken !== 'string' || !accessToken)
@@ -1077,7 +1174,7 @@ export async function probeDroidStatus(home) {
     // window is open, report the throttle from the recorded state instead of
     // firing again and re-arming it (usage-backoff.ts). This 3-min-cadence
     // probe is what created the loop it now respects.
-    if (usageRateLimitedUntil('droid'))
+    if (usageRateLimitedUntil('droid', Date.now(), usageScope))
         return { status: 429, token: 'present' };
     try {
         const response = await fetch(DROID_USAGE_URL, {
@@ -1086,7 +1183,7 @@ export async function probeDroidStatus(home) {
             signal: AbortSignal.timeout(8000),
         });
         if (response.status === 429) {
-            noteUsageRateLimited('droid', response.headers.get('retry-after'));
+            noteUsageRateLimited('droid', response.headers.get('retry-after'), { account: usageScope });
         }
         return { status: response.status, token: 'present' };
     }
@@ -1561,6 +1658,10 @@ function serializeClaudeUsageSnapshot(snapshot) {
  * candidate (RUSH-2858). Dropping mirrors the Grok collector, and an all-expired
  * snapshot deserializes to null so `readClaudeUsageCache` deletes the entry and
  * callers surface "usage unavailable" plus the recorded throttle reason.
+ *
+ * A row that carries a plan survives even with no fresh windows: the plan is a
+ * truthful reading in its own right, and losing it is what made the cached view
+ * contradict the refreshed one for meterless harnesses. See the guard below.
  */
 function deserializeClaudeUsageSnapshot(snapshot, now) {
     const capturedAt = parseDateValue(snapshot.capturedAt);
@@ -1575,7 +1676,17 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
     }))
         .filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
     const unavailable = deserializeUnavailable(snapshot.unavailable, now);
-    if (windows.length === 0 && !unavailable) {
+    // A windowless row is not automatically worthless. Grok's collector reports
+    // the subscription tier and no meters at all, so treating "no fresh windows"
+    // as "nothing cached" deleted the only truthful thing we knew about the
+    // account: `--refresh` wrote {plan: 'SuperGrok Heavy', windows: []}, the very
+    // next plain `agents view` deserialized it to null, `readClaudeUsageCache`
+    // pruned the row, and the row rendered "usage unavailable" one read after a
+    // successful refresh. Keep a plan-bearing row — it renders as the plan alone,
+    // and `deriveUsageStatusFromSnapshot` still returns null for zero windows, so
+    // it can never read as a 0% bar or an "available" badge (the RUSH-2858
+    // property that made expired windows drop in the first place).
+    if (windows.length === 0 && !unavailable && !snapshot.plan) {
         return null;
     }
     return {
@@ -1955,11 +2066,12 @@ async function getGrokUsageInfo(options) {
     try {
         const base = options?.home || os.homedir();
         const logPath = path.join(base, '.grok', 'logs', 'unified.jsonl');
+        // No log yet: a benign "nothing recorded here", not a failure (RUSH-3040).
         if (!fs.existsSync(logPath))
-            return { snapshot: null, error: null };
+            return usageNoRecentUsageInfo();
         const match = await readLatestGrokBilling(logPath);
         if (!match)
-            return { snapshot: null, error: null };
+            return usageNoRecentUsageInfo();
         // Grok has no live usage API (`network: false`) — bars are last-seen from
         // this machine's unified.jsonl only. Drop windows whose billing period has
         // already ended so a stale 100% does not paint "rate-limited" after reset,
@@ -1968,6 +2080,10 @@ async function getGrokUsageInfo(options) {
         // (see readLatestGrokBilling).
         const now = new Date();
         const windows = match.windows.filter((window) => isCachedUsageWindowFresh(window, match.capturedAt, now));
+        // NOTE: an empty `windows` here (all windows expired) still returns a real
+        // snapshot, not the no-recent-usage marker — the plan/tier is still valid
+        // and callers (e.g. `formatUsageSummary`) render "no bars" correctly from
+        // an empty array. The marker above is only for "nothing was ever recorded".
         return {
             snapshot: {
                 source: 'last_seen',
@@ -1979,8 +2095,8 @@ async function getGrokUsageInfo(options) {
             error: null,
         };
     }
-    catch {
-        return { snapshot: null, error: null };
+    catch (err) {
+        return { snapshot: null, error: usageUnreachableError('Grok', err) };
     }
 }
 /**
@@ -1994,16 +2110,40 @@ async function getGrokUsageInfo(options) {
 async function getMuseUsageInfo(options) {
     try {
         const base = options?.home || os.homedir();
-        const live = await probeMuseRateLimits(base);
-        if (live)
-            return { snapshot: live, error: null };
+        // Honour a live Retry-After rather than re-arming the penalty (see
+        // usage-backoff.ts). The local log fallback still works while the live
+        // probe is throttled — only report the throttle when there is truly
+        // nothing else to show.
+        const throttledUntil = usageRateLimitedUntil('muse', Date.now(), options?.usageScope);
+        if (throttledUntil) {
+            const local = await readMuseLocalSessionUsage(base);
+            if (local)
+                return { snapshot: local, error: null };
+            return { snapshot: null, error: usageThrottledError('Muse', throttledUntil) };
+        }
+        const probe = await probeMuseRateLimits(base);
+        if (probe.snapshot)
+            return { snapshot: probe.snapshot, error: null };
         const local = await readMuseLocalSessionUsage(base);
-        if (!local)
-            return { snapshot: null, error: null };
-        return { snapshot: local, error: null };
+        if (local)
+            return { snapshot: local, error: null };
+        // No live snapshot and no local log — every source came up empty. Only
+        // now does the probe's own outcome become the reported error, mirroring
+        // Cursor's "surface the last resort's failure" pattern above.
+        if (!probe.hasKey)
+            return { snapshot: null, error: usageNoCredentialError('Muse') };
+        if (probe.noHeaders)
+            return usageNoRecentUsageInfo();
+        return {
+            snapshot: null,
+            error: classifyUsageFetchFailure('Muse', 'muse', probe.status, probe.retryAfter, options?.usageScope),
+        };
     }
-    catch {
-        return { snapshot: null, error: null };
+    catch (err) {
+        // A thrown request (timeout, DNS, TLS, a malformed payload) is a failed
+        // read like any other — staying silent here would hand the caller a stale
+        // snapshot to render as confirmed (RUSH-3040).
+        return { snapshot: null, error: usageUnreachableError('Muse', err) };
     }
 }
 /** Resolve a Muse API key from env or auth.json without logging the value. */
@@ -2037,25 +2177,28 @@ function resolveMuseApiKey(base) {
 }
 /**
  * Probe Meta Model API for rate-limit headers. Uses GET /v1/models (no token
- * spend). Returns null when unauthenticated or the headers are absent.
+ * spend). The 429 backoff is noted by the CALLER via
+ * {@link classifyUsageFetchFailure}, not here, so a throttled read is recorded
+ * exactly once regardless of which branch of `getMuseUsageInfo` observes it.
  */
 async function probeMuseRateLimits(base) {
-    if (usageRateLimitedUntil('muse'))
-        return null;
     const key = resolveMuseApiKey(base);
     if (!key)
-        return null;
+        return { snapshot: null, hasKey: false, status: null, retryAfter: null, noHeaders: false };
     try {
         const response = await fetch('https://api.meta.ai/v1/models', {
             headers: { Authorization: `Bearer ${key}` },
             signal: AbortSignal.timeout(8_000),
         });
-        if (response.status === 429) {
-            noteUsageRateLimited('muse', response.headers.get('retry-after'));
-            return null;
+        if (!response.ok) {
+            return {
+                snapshot: null,
+                hasKey: true,
+                status: response.status,
+                retryAfter: response.headers.get('retry-after'),
+                noHeaders: false,
+            };
         }
-        if (!response.ok)
-            return null;
         const limitTokens = headerNumber(response.headers, 'x-ratelimit-limit-tokens');
         const remainingTokens = headerNumber(response.headers, 'x-ratelimit-remaining-tokens');
         const limitRequests = headerNumber(response.headers, 'x-ratelimit-limit-requests');
@@ -2083,18 +2226,25 @@ async function probeMuseRateLimits(base) {
                 windowMinutes: 1,
             });
         }
-        if (windows.length === 0)
-            return null;
+        if (windows.length === 0) {
+            return { snapshot: null, hasKey: true, status: response.status, retryAfter: null, noHeaders: true };
+        }
         return {
-            source: 'live',
-            sourceLabel: 'Meta Model API rate limits',
-            capturedAt: new Date(),
-            windows,
-            plan: 'Meta Model API',
+            snapshot: {
+                source: 'live',
+                sourceLabel: 'Meta Model API rate limits',
+                capturedAt: new Date(),
+                windows,
+                plan: 'Meta Model API',
+            },
+            hasKey: true,
+            status: response.status,
+            retryAfter: null,
+            noHeaders: false,
         };
     }
     catch {
-        return null;
+        return { snapshot: null, hasKey: true, status: null, retryAfter: null, noHeaders: false };
     }
 }
 function headerNumber(headers, name) {
@@ -2660,10 +2810,14 @@ async function refreshAntigravityAccessToken(refreshToken) {
 }
 /**
  * POST :retrieveUserQuota against the Code Assist endpoints in order, returning
- * the first successful bucket list. null when every endpoint rejects (expired
- * token, no quota API for the account) or the network fails.
+ * the first successful bucket list. `buckets: null` when every endpoint rejects
+ * (expired token, no quota API for the account) or the network fails — `status`
+ * carries the LAST rejection's HTTP status (or null when every attempt threw)
+ * so the caller can classify the failure instead of it reading as silence.
  */
 async function fetchAntigravityQuota(accessToken) {
+    let lastStatus = null;
+    let lastRetryAfter = null;
     for (const url of ANTIGRAVITY_QUOTA_URLS) {
         try {
             const response = await fetch(url, {
@@ -2676,16 +2830,19 @@ async function fetchAntigravityQuota(accessToken) {
                 body: '{}',
                 signal: AbortSignal.timeout(5000),
             });
-            if (!response.ok)
+            if (!response.ok) {
+                lastStatus = response.status;
+                lastRetryAfter = response.headers.get('retry-after');
                 continue;
+            }
             const data = (await response.json());
-            return Array.isArray(data?.buckets) ? data.buckets : [];
+            return { buckets: Array.isArray(data?.buckets) ? data.buckets : [], status: response.status, retryAfter: null };
         }
         catch {
             continue;
         }
     }
-    return null;
+    return { buckets: null, status: lastStatus, retryAfter: lastRetryAfter };
 }
 /** Compact model tag for the inline bar — 'gemini-2.5-flash-lite' => '2.5FL'. */
 export function antigravityModelShortLabel(modelId) {
@@ -2747,16 +2904,28 @@ async function getAntigravityUsageInfo(options) {
     try {
         const token = await loadAntigravityOauth(options?.home);
         if (!token)
-            return { snapshot: null, error: null };
+            return { snapshot: null, error: usageNoCredentialError('Antigravity') };
         let accessToken = normalizeString(token.access_token);
         if ((!accessToken || antigravityTokenNeedsRefresh(token.expiry)) && token.refresh_token) {
             accessToken = await refreshAntigravityAccessToken(token.refresh_token);
         }
         if (!accessToken)
-            return { snapshot: null, error: null };
-        const buckets = await fetchAntigravityQuota(accessToken);
-        if (!buckets)
-            return { snapshot: null, error: null };
+            return { snapshot: null, error: usageExpiredCredentialError('Antigravity') };
+        // Honour a live Retry-After rather than re-arming the penalty (see
+        // usage-backoff.ts). No request at all while the window is open. Antigravity
+        // previously had NO rate-limit backoff at all (RUSH-3040) — every refresh
+        // re-hit a throttled endpoint.
+        const throttledUntil = usageRateLimitedUntil('antigravity', Date.now(), options?.usageScope);
+        if (throttledUntil) {
+            return { snapshot: null, error: usageThrottledError('Antigravity', throttledUntil) };
+        }
+        const { buckets, status, retryAfter } = await fetchAntigravityQuota(accessToken);
+        if (!buckets) {
+            return {
+                snapshot: null,
+                error: classifyUsageFetchFailure('Antigravity', 'antigravity', status, retryAfter, options?.usageScope),
+            };
+        }
         const windows = normalizeAntigravityWindows(buckets);
         if (windows.length === 0)
             return { snapshot: null, error: null };
@@ -2770,7 +2939,10 @@ async function getAntigravityUsageInfo(options) {
             error: null,
         };
     }
-    catch {
-        return { snapshot: null, error: null };
+    catch (err) {
+        // A thrown request (timeout, DNS, TLS, a malformed payload) is a failed
+        // read like any other — staying silent here would hand the caller a stale
+        // snapshot to render as confirmed (RUSH-3040).
+        return { snapshot: null, error: usageUnreachableError('Antigravity', err) };
     }
 }

package/dist/lib/agent-modes.js

@@ -14,9 +14,28 @@ import { resolveRunDefaults } from './run-defaults.js';
 export const MODE_DESCRIPTIONS = {
     plan: 'read-only investigation; no writes, no shell side-effects',
     edit: 'may edit files; prompts for shell / risky operations',
-    auto: 'smart classifier auto-approves safe ops, prompts for risky',
+    auto: 'more autonomy than edit; the exact policy is per-harness (see notes)',
     skip: 'bypass every permission prompt (dangerously-skip-permissions)',
 };
+/**
+ * What `auto` actually does, per harness. Two genuinely different mechanisms
+ * wear the same mode name, and conflating them is a safety error in both
+ * directions: telling a claude operator that auto never prompts invites an
+ * unattended run that stalls on a risky-operation gate, and telling a codex
+ * operator that auto prompts for risky work asserts a gate codex does not have.
+ * Absent entry = no extra note; the row's own text suffices.
+ */
+const AUTO_SEMANTICS = {
+    // Classifier-style: still escalates. --permission-mode auto / --autopilot.
+    claude: 'a smart classifier auto-approves safe operations and still prompts for risky ones.',
+    copilot: 'a smart classifier auto-approves safe operations and still prompts for risky ones.',
+    // Approvals off, sandbox kept: never escalates. A denied command just fails.
+    codex: 'approval_policy=never over the same sandbox as edit — it never prompts, and a sandbox-denied command fails instead of raising an approval request.',
+    muse: 'runs --disable-approval, which turns approvals off while keeping the sandbox — like codex, it never prompts and a denied command fails.',
+    // Native autonomy dial at its top setting.
+    droid: 'runs --auto high, droid\'s full-autonomy setting.',
+    kimi: "runs kimi's native --auto.",
+};
 /**
  * Build the permission-mode catalog for one harness.
  * `version` only affects the configured run.defaults lookup (modes themselves
@@ -42,6 +61,15 @@ export function getAgentModesCatalog(agent, version, cwd = process.cwd()) {
     if (unsupported.includes('auto')) {
         notes.push(`--mode auto degrades to edit on ${agent} (no native auto classifier).`);
     }
+    // MODE_DESCRIPTIONS is one flat Record<Mode, string> rendered for every agent,
+    // so it cannot name any single harness's mechanism without lying about the
+    // others: claude/copilot auto STILL PROMPTS for risky operations, while codex
+    // auto never prompts at all. The row states only what is true everywhere; the
+    // mechanism rides here, per harness.
+    const autoSemantics = AUTO_SEMANTICS[agent];
+    if (autoSemantics && supported.includes('auto')) {
+        notes.push(`${agent} --mode auto: ${autoSemantics}`);
+    }
     if (unsupported.includes('plan')) {
         notes.push(`--mode plan degrades to ${defaultMode} on ${agent} (no native read-only mode).`);
     }

package/dist/lib/agent-spec/agents.d.ts

@@ -552,9 +552,9 @@ export declare function resolveAgentName(input: string): AgentId | null;
 /** Check whether the input string matches any known agent name or alias. */
 export declare function isAgentName(input: string): boolean;
 /**
- * Split a CLI-provided `<agent>[@<version>]` spec into its bare agent id and
- * optional exact version token, the same way `agents run` does
- * (commands/exec.ts parses its positional with a plain `split('@')`) — NOT the
+ * Split a CLI-provided `<agent>[@<version>][#<label>]` spec into its bare agent
+ * id, optional exact version token, and optional account label, the same way
+ * `agents run` does — NOT the
  * agent-spec qualifier engine (`@latest`/`@all`), which enumerates installed
  * versions for read/diagnostic commands, not a single launch target. Returns an
  * error message rather than throwing so callers decide exit-vs-continue.
@@ -562,6 +562,7 @@ export declare function isAgentName(input: string): boolean;
 export declare function parseAgentVersionSpec(raw: string): {
     agent: AgentId;
     version?: string;
+    label?: string;
 } | {
     error: string;
 };