@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/accounting/usage.js

@@ -26,6 +26,7 @@ import { getCacheDir } from '../state.js';
 import { mapBounded } from '../concurrency.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from '../fs-atomic.js';
 import { withRefreshLease } from '../refresh-coordinator.js';
+import { padToWidth } from '../session/width.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -118,6 +119,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 +217,15 @@ const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
 const EMPTY = '\u2591';
+const PARTIAL_BLOCKS = ['', '\u258F', '\u258E', '\u258D', '\u258C', '\u258B', '\u258A', '\u2589'];
+/** 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 +394,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 +455,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 = [];
@@ -416,11 +500,20 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         // multi-meter agent cannot force the whole table to wrap.
         const selected = pickCompactUsageWindows(snapshot.windows, opts?.maxWindows);
         const hidden = Math.max(0, snapshot.windows.filter((w) => w.key !== 'sonnet_week').length - selected.length);
-        const windowParts = selected.map((window) => {
+        const expected = opts?.expectedWindows;
+        const windowsToRender = expected
+            ? expected.map(({ key, shortLabel }) => ({ window: selected.find((item) => item.key === key), shortLabel }))
+            : selected.map((window) => ({ window, shortLabel: window.shortLabel }));
+        const windowParts = windowsToRender.map(({ window, shortLabel }, index) => {
+            if (!window) {
+                const missing = chalk.red(`${shortLabel}: ${FULL.repeat(COMPACT_BAR_LEN)} unavailable`);
+                return index < windowsToRender.length - 1 ? padToWidth(missing, 20) : missing;
+            }
             const bar = renderCompactUsageBar(window.usedPercent);
             const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
             const reset = window.resetsAt ? chalk.dim(` (${formatResetHint(window.resetsAt)})`) : '';
-            return `${chalk.gray(`${window.shortLabel}:`)} ${bar} ${pct}${reset}`;
+            const rendered = `${chalk.gray(`${shortLabel}:`)} ${bar} ${pct}${reset}`;
+            return index < windowsToRender.length - 1 ? padToWidth(rendered, 20) : rendered;
         });
         if (hidden > 0) {
             windowParts.push(chalk.dim(`+${hidden}`));
@@ -428,6 +521,9 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         if (windowParts.length > 0) {
             parts.push(windowParts.join('  '));
         }
+        else if (snapshot.refreshHint) {
+            parts.push(chalk.dim(snapshot.refreshHint));
+        }
         // The bars came from the cache and the live read that should have confirmed
         // them failed, so they are the last thing we saw — not the current state.
         // Drawing them unmarked is what let a 26h-old "48% used" read as fact.
@@ -445,11 +541,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(opts.noRecentUsageLabel || 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 +699,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 +722,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 +782,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 +798,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 +891,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 +907,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 +1025,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 +1040,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 +1067,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 +1092,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 +1106,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 +1134,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 +1158,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 +1167,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 +1176,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 +1188,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 +1197,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' };
     }
@@ -1313,7 +1424,7 @@ function deleteCachedClaudeOauth(service) {
  * a file-based setup-token and, when none is provisioned, gets `null` — it never
  * reads Claude Code's interactive login (transmitting that ACL-bound OAuth token
  * to Anthropic's API is what gets it revoked; see the branch body and
- * docs/credential-management.md). It is OFF by default so full-credential
+ * docs/secrets.md). It is OFF by default so full-credential
  * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) still
  * read the interactive login. Rush Cloud dispatch does not call this helper
  * at all (SING-1b: the account manifest is email-only; RUSH-2359 removed the
@@ -1346,7 +1457,7 @@ export async function loadClaudeOauth(home, opts) {
         // interactive credential used programmatically, which Anthropic flags and
         // revokes (the fleet-wide-logout class, RUSH-1822), and which violates the
         // invariant that the interactive/rotating login is untouchable
-        // (docs/credential-management.md). Report unprovisioned (-> probe
+        // (docs/secrets.md). Report unprovisioned (-> probe
         // token 'missing' -> auth-health 'unconfigured', benign for rotation); seed a
         // setup-token via the mint-auth path to restore usage/probe for the account.
         return null;
@@ -1507,6 +1618,32 @@ export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeU
         /* best-effort cache write — lock busy or disk full */
     }
 }
+/** Atomically merge partial native Claude windows into the current fresh row. */
+export function mergeClaudeUsageCacheWindows(usageKey, snapshot, cachePath = getClaudeUsageCachePath()) {
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const prior = cache[usageKey];
+            const priorSnapshot = prior
+                ? deserializeClaudeUsageSnapshot(prior, snapshot.capturedAt ?? new Date())
+                : null;
+            const windows = new Map(priorSnapshot?.windows.map((window) => [window.key, window]) ?? []);
+            for (const window of snapshot.windows)
+                windows.set(window.key, window);
+            cache[usageKey] = serializeClaudeUsageSnapshot({
+                ...snapshot,
+                windows: [...windows.values()],
+                plan: snapshot.plan ?? priorSnapshot?.plan ?? null,
+                unavailable: carryForwardUnavailable(prior?.unavailable, snapshot.unavailable),
+            });
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
+}
 /** Read the entire usage cache file from disk. */
 function readClaudeUsageCacheFile(cachePath) {
     if (!fs.existsSync(cachePath)) {
@@ -1535,6 +1672,7 @@ function serializeClaudeUsageSnapshot(snapshot) {
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
         plan: snapshot.plan ?? null,
+        refreshHint: snapshot.refreshHint ?? null,
         unavailable: snapshot.unavailable
             ? {
                 reason: snapshot.unavailable.reason,
@@ -1561,6 +1699,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 +1717,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 && !snapshot.refreshHint) {
         return null;
     }
     return {
@@ -1584,6 +1736,7 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         capturedAt,
         windows,
         plan: snapshot.plan ?? null,
+        refreshHint: snapshot.refreshHint ?? null,
         unavailable,
     };
 }
@@ -1862,14 +2015,17 @@ function renderUsageBar(usedPercent) {
 }
 /** Render a compact usage bar for inline summaries. */
 function renderCompactUsageBar(usedPercent) {
-    return renderBar(usedPercent, COMPACT_BAR_LEN, usedPercent > 0 ? 1 : 0);
-}
-/** Render a colored block-character progress bar. */
-export function renderBar(usedPercent, length, minimumVisible = 0) {
-    const rounded = Math.round((usedPercent / 100) * length);
-    const filled = Math.max(minimumVisible, Math.max(0, Math.min(length, rounded)));
+    return renderBar(usedPercent, COMPACT_BAR_LEN);
+}
+/** Render a proportional colored progress bar at one-eighth-cell resolution. */
+export function renderBar(usedPercent, length) {
+    const clamped = Math.max(0, Math.min(100, usedPercent));
+    const eighths = Math.round((clamped / 100) * length * 8);
+    const filled = Math.floor(eighths / 8);
+    const partial = eighths % 8;
     const color = getUsageColor(usedPercent);
-    return color(FULL.repeat(filled)) + chalk.dim(EMPTY.repeat(length - filled));
+    const gauge = FULL.repeat(filled) + PARTIAL_BLOCKS[partial];
+    return color(gauge) + chalk.dim(EMPTY.repeat(length - filled - (partial > 0 ? 1 : 0)));
 }
 /** Apply the appropriate color to a text string based on usage percentage. */
 function colorUsage(text, usedPercent) {
@@ -1955,11 +2111,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 +2125,10 @@ async function getGrokUsageInfo(options) {
         // (see readLatestGrokBilling).
         const now = new Date();
         const windows = match.windows.filter((window) => isCachedUsageWindowFresh(window, match.capturedAt, now));
+        const version = options?.cliVersion;
+        const refreshHint = windows.length === 0
+            ? `run grok${version ? `@${version}` : ''} once to refresh usage`
+            : null;
         return {
             snapshot: {
                 source: 'last_seen',
@@ -1975,12 +2136,13 @@ async function getGrokUsageInfo(options) {
                 capturedAt: match.capturedAt,
                 windows,
                 plan: match.subscriptionTier,
+                refreshHint,
             },
             error: null,
         };
     }
-    catch {
-        return { snapshot: null, error: null };
+    catch (err) {
+        return { snapshot: null, error: usageUnreachableError('Grok', err) };
     }
 }
 /**
@@ -1994,16 +2156,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 +2223,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 +2272,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) {
@@ -2333,7 +2529,7 @@ export function normalizeCursorUsageSummary(data) {
 function readCursorCredentials(base) {
     try {
         const cfgPath = path.join(base, '.cursor', 'cli-config.json');
-        const authPath = path.join(base, '.config', 'cursor', 'auth.json');
+        const authPath = path.join(base, '.cursor', 'auth.json');
         if (!fs.existsSync(cfgPath) || !fs.existsSync(authPath))
             return null;
         const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
@@ -2660,10 +2856,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 +2876,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 +2950,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 +2985,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) };
     }
 }