@phnx-labs/agents-cli 1.22.45 → 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 = [];
@@ -398,7 +480,10 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         parts.push(chalk.gray(plan.padEnd(planWidth)));
     }
     if (snapshot) {
-        if (snapshot.unavailable?.reason === 'session_limit') {
+        if (snapshot.unavailable?.reason === 'out_of_credits') {
+            parts.push(chalk.red('out of credits'));
+        }
+        else if (snapshot.unavailable?.reason === 'session_limit' && snapshot.unavailable.resetsAt) {
             parts.push(chalk.yellow(`session-limited (${formatResetHint(snapshot.unavailable.resetsAt)})`));
         }
         // Compact rows show BLOCKING windows — the same set
@@ -442,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('  ');
 }
@@ -472,8 +562,14 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
 export function deriveUsageStatusFromSnapshot(snapshot) {
     if (!snapshot)
         return null;
-    if (snapshot.unavailable && snapshot.unavailable.resetsAt.getTime() > Date.now()) {
-        return 'rate_limited';
+    if (snapshot.unavailable) {
+        // out_of_credits has no clock — it stays blocking until a successful run
+        // clears it. session_limit blocks only until its reset time.
+        if (snapshot.unavailable.reason === 'out_of_credits')
+            return 'rate_limited';
+        if (snapshot.unavailable.resetsAt && snapshot.unavailable.resetsAt.getTime() > Date.now()) {
+            return 'rate_limited';
+        }
     }
     if (snapshot.windows.length === 0)
         return null;
@@ -589,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 {
@@ -606,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) };
     }
 }
 /**
@@ -662,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) };
         }
@@ -678,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
@@ -771,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) };
         }
@@ -787,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) };
         }
@@ -905,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) };
         }
@@ -920,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) };
         }
@@ -947,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
@@ -972,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, {
@@ -986,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).
@@ -1014,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' };
@@ -1038,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, {
@@ -1047,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' };
     }
@@ -1056,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)
@@ -1068,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, {
@@ -1077,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' };
     }
@@ -1487,12 +1593,9 @@ export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeU
             // refresh cannot drop another account's row (lost update).
             const cache = readClaudeUsageCacheFile(cachePath);
             const prior = cache[usageKey];
-            const priorReset = parseDateValue(prior?.unavailable?.resetsAt);
             cache[usageKey] = serializeClaudeUsageSnapshot({
                 ...snapshot,
-                unavailable: priorReset && priorReset.getTime() > Date.now()
-                    ? { reason: 'session_limit', resetsAt: priorReset }
-                    : snapshot.unavailable,
+                unavailable: carryForwardUnavailable(prior?.unavailable, snapshot.unavailable),
             });
             atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
         });
@@ -1530,7 +1633,10 @@ function serializeClaudeUsageSnapshot(snapshot) {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
         plan: snapshot.plan ?? null,
         unavailable: snapshot.unavailable
-            ? { reason: snapshot.unavailable.reason, resetsAt: snapshot.unavailable.resetsAt.toISOString() }
+            ? {
+                reason: snapshot.unavailable.reason,
+                resetsAt: snapshot.unavailable.resetsAt?.toISOString(),
+            }
             : undefined,
         windows: snapshot.windows.map((window) => ({
             key: window.key,
@@ -1552,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);
@@ -1565,11 +1675,18 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         windowMinutes: window.windowMinutes,
     }))
         .filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
-    const unavailableReset = parseDateValue(snapshot.unavailable?.resetsAt);
-    const unavailable = unavailableReset && unavailableReset.getTime() > now.getTime()
-        ? { reason: 'session_limit', resetsAt: unavailableReset }
-        : undefined;
-    if (windows.length === 0 && !unavailable) {
+    const unavailable = deserializeUnavailable(snapshot.unavailable, now);
+    // 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 {
@@ -1581,6 +1698,82 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         unavailable,
     };
 }
+/**
+ * Carry a prior refusal marker forward across a daemon usage refresh, and drop
+ * an expired one. A live `snapshot.unavailable` (a refusal just observed) wins.
+ * `out_of_credits` survives refreshes with no reset — only a successful run
+ * clears it (clearClaudeAccountRefusal). A `session_limit` survives only while
+ * its reset time is still in the future.
+ */
+function carryForwardUnavailable(prior, live) {
+    if (live)
+        return live;
+    if (!prior)
+        return undefined;
+    if (prior.reason === 'out_of_credits')
+        return { reason: 'out_of_credits' };
+    const reset = parseDateValue(prior.resetsAt);
+    return reset && reset.getTime() > Date.now()
+        ? { reason: 'session_limit', resetsAt: reset }
+        : undefined;
+}
+/**
+ * Deserialize a cached `unavailable` marker, dropping an expired session_limit
+ * but keeping a clock-less out_of_credits.
+ */
+function deserializeUnavailable(cached, now) {
+    if (!cached)
+        return undefined;
+    if (cached.reason === 'out_of_credits')
+        return { reason: 'out_of_credits' };
+    const reset = parseDateValue(cached.resetsAt);
+    return reset && reset.getTime() > now.getTime()
+        ? { reason: 'session_limit', resetsAt: reset }
+        : undefined;
+}
+/**
+ * Persist a Claude tokens/credits exhaustion (`out of usage credits` / `monthly
+ * spend limit`) from a real run. Unlike a rate/session limit this does NOT reset
+ * on a clock, so no reset time is stored — rotation excludes the account until a
+ * later successful run clears it via {@link clearClaudeAccountRefusal}.
+ */
+export function noteClaudeOutOfCredits(usageKey, cachePath = getClaudeUsageCachePath()) {
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const existing = cache[usageKey] ?? { capturedAt: null, windows: [] };
+            cache[usageKey] = { ...existing, unavailable: { reason: 'out_of_credits' } };
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
+}
+/**
+ * Clear any persisted refusal marker for an account after a run SUCCEEDS on it.
+ * This is the recovery path for `out_of_credits` (which has no clock) and also
+ * proactively clears a stale `session_limit` the moment the account serves again.
+ */
+export function clearClaudeAccountRefusal(usageKey, cachePath = getClaudeUsageCachePath()) {
+    try {
+        if (!fs.existsSync(cachePath))
+            return;
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const existing = cache[usageKey];
+            if (!existing?.unavailable)
+                return;
+            const { unavailable: _drop, ...rest } = existing;
+            cache[usageKey] = rest;
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write */
+    }
+}
 /**
  * Persist a Claude session-limit refusal from a real run until its stated reset.
  * This quota is not part of Anthropic's five-hour/weekly usage response.
@@ -1873,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,
@@ -1886,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',
@@ -1897,8 +2095,8 @@ async function getGrokUsageInfo(options) {
             error: null,
         };
     }
-    catch {
-        return { snapshot: null, error: null };
+    catch (err) {
+        return { snapshot: null, error: usageUnreachableError('Grok', err) };
     }
 }
 /**
@@ -1912,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. */
@@ -1955,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');
@@ -2001,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) {
@@ -2578,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, {
@@ -2594,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) {
@@ -2665,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 };
@@ -2688,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) };
     }
 }