@phnx-labs/agents-cli 1.22.101 → 1.22.103

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.22.103
+
+- **`agents run claude` no longer dies with `secrets request failed: spawnSync sh ETIMEDOUT` on a loaded machine (PHNX-4078).** Every synchronous secrets request spawns a fresh `secrets __serve` process, so its bound has to cover a cold Node boot of the standalone, not just the tens-of-milliseconds operation. The bound was 3 s; on a desktop at load average ~100 each spawn measured 0.4–2.6 s and sometimes more, so the account listing on the launch path timed out and the run aborted before Claude started (also why AGI EXT tabs opened to a bare shell there). The sync bound is now 30 s — enough to boot under load, still well under the standalone's own 60 s self-deadline — and a timeout names the cause ("the standalone secrets CLI did not answer within 30s … check with secrets --version") instead of the raw `spawnSync` errno. Source: `cli/src/lib/secrets-client.ts`, `cli/src/lib/secrets-client.test.ts`, `cli/docs/secrets-client.md`.
+
+## 1.22.102
+
+- **AGI Menu updates itself on npm-installed Macs (PHNX-4036).** The npm tarball ships no helper bundle, and the startup self-heal is network-free by design, so an `npm i -g` Mac kept whatever helper it had — the crashing 1.1.2, a dead 0.1.0 — until someone ran `agents menubar setup` by hand. The detached background sync now downloads and verifies the floor release into the helper cache whenever the installed helper is behind it (or no service exists yet and the user has not opted out), and the self-heal treats that cached bundle as a source, so the next `agents` invocation installs it with no foreground network. `agents menubar status` names the pending download instead of "missing (cannot enable)". Source: `cli/src/lib/menubar/install-menubar.ts`, `cli/src/lib/auto-pull-worker.ts`.
+
+- **`agents view` STATE is honest and WHERE reads like English (PHNX-3940, PHNX-4051).** A probe 429 no longer marks the account LIMITED — the probe keeps the previous verdict within 20 min, otherwise `unverified` with `probe throttled (HTTP 429)`; the account's real throttle is the usage snapshot (`deriveUsageStatusFromSnapshot` / `applyUsageHonesty`). Fleet merge no longer lets a remote `rate_limited` override a fresh local `available` read (`stale:false`) — remote `revoked`/`expired` still win and rows stay in `--json`. The daemon probes each account identity once per tick (version home + slot collapse by `accountId`) and spaces probes ~150 ms so one box no longer fires 16 requests in 4 s. WHERE now reads `this box`, `on N boxes`, or `on N of M boxes` instead of `+N`; a gray footer legend explains STATE values and `*` stale. Source: `cli/src/lib/auth-health.ts`, `cli/src/lib/account-catalog.ts`, `cli/src/commands/view.ts`, `cli/src/commands/accounts.ts`, `cli/docs/credential-management.md`.
+
+- **Feed rows carry their PR status.** `agents feed watch --json` now attaches the `gh pr view` status it already fetches for attention to each agent row's `pr` (`state`, `isDraft`, `reviewDecision`, `mergeable`, and a one-word `checks` verdict), and re-emits the row when that status changes, so AGI Menu and the extension can color a PR chip merged / open / failing without their own `gh` calls. Source: `cli/src/lib/feed/watch.ts`, `cli/src/lib/feed/pr-status.ts`.
+
+- **Restore per-window usage bars in `agents view <agent>` account rows (PHNX-3940).** Account rows now render every blocking window side by side (`S: ███░░ 58% (3d)  W: ██░░░ 41% (5d)`) via the canonical `formatUsageSummary` / `pickCompactUsageWindows` path instead of a single max-percent bar. The overview caps at 2 windows and single-harness views show all blocking windows; provider rows with no windows keep their current rendering. Source: `cli/src/lib/account-catalog.ts`, `cli/src/lib/devices/harness-inventory.ts`, `cli/src/commands/view.ts`.
+
 ## 1.22.101
 
 - **`agents sync status` names what drifted, and a merged system-layer skill or subagent reaches the next `agents run` on every box (PHNX-4056).** The status readout said `11 drifted` per install and nothing more, although `AgentVersionStatus.resources` already carried the rows; both human renderers (`agents sync status`, the drift summary `agents sync` prints) now list each drifted or missing resource as `drifted skills/artifacts` under its install line, with the differ's detail when it has one. And when `~/.agents/.system/skills` or `subagents` changed since the last launch of an (agent, version), `agents run` rewrites those resources into the version home through the registered writers before spawning, filtered by the active resource profile like the full sync, with the same stat-tier sentinel shape as the rules run-sync: on 2026-09-10 a merged skill change left 31 of 33 installed copies stale until the 4-hour umbrella autosync, because the shim's `--launch` path mirrors project resources only. Source: `cli/src/lib/system-run-sync.ts`, `cli/src/lib/sync-status.ts`, `cli/src/commands/status.ts`, `cli/src/lib/drift-sync.ts`, `cli/src/lib/exec.ts`, `cli/src/commands/exec.ts`.

package/dist/bootstrap.js

@@ -385,6 +385,21 @@ async function installResolvedPackage(metadata) {
     // The macOS Keychain helper this used to force-refresh on upgrade moved with
     // the standalone `secrets` engine (PHNX-3989) — it downloads and verifies its
     // own helper release now, off this CLI's upgrade path entirely.
+    //
+    // The menu-bar helper still rides this path: an installed release build moves
+    // to the newest published one (verified download, atomic swap at the same
+    // path and identity so the Accessibility grant survives, restart). The new
+    // package is on disk, so the import resolves the fresh module. Best-effort;
+    // the daemon's self-heal tick repeats it every six hours.
+    if (process.platform === 'darwin') {
+        try {
+            const { updateMenubarHelperIfNewer } = await import('./lib/menubar/install-menubar.js');
+            await updateMenubarHelperIfNewer({ force: true });
+        }
+        catch {
+            // Non-fatal.
+        }
+    }
 }
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {

package/dist/commands/accounts.js

@@ -554,7 +554,7 @@ export function registerAccountsCommand(program) {
 agents accounts list claude
 agents accounts list --json
 agents accounts list --fleet`,
-        notes: 'One row per account per harness. STATE is the daemon verdict. WHERE is `this box` when only this device reports (peers on an older release publish no slot verdicts), else live-device coverage. USAGE is the bar + percent. FIX is the exact repair command — empty when there is none. Reserved credential stores are not listed here; `agents secrets` is the place those show.',
+        notes: 'One row per account per harness. STATE is the usage snapshot (`deriveUsageStatusFromSnapshot`/`applyUsageHonesty`, never a probe 429 — a throttled probe keeps the previous verdict within 20 min, otherwise `unverified` with `probe throttled (HTTP 429)`; `LIMITED` only when the local usage snapshot is `rate_limited`/`out_of_credits`, remote `rate_limited` only when no local snapshot). WHERE is `this box` when only this device reports; otherwise `on N boxes` when every provisioned device is usable (`live`/`rate_limited`/`unverified`), `on N of M boxes` when some are not, `—` when nothing is provisioned; per-device accounts list present devices. USAGE is the bar + percent (`*` stale). FIX is the exact repair command — empty when there is none. Reserved credential stores are not listed here; `agents secrets` is the place those show.',
     });
     registerMintCommand(accounts, undefined, { hidden: true });
     const addCmd = accounts.command('add <target> [name]')

package/dist/commands/menubar.js

@@ -30,7 +30,10 @@ function printStatus(s, opts = {}) {
     console.log(`  helper installed   ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
     console.log(`  helper available   ${chalk.gray(s.currentVersion)}`);
     console.log(`  CLI version        ${chalk.gray(s.cliVersion)}`);
-    console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
+    const pendingSource = s.disabledByUser
+        ? chalk.gray('none (disabled by user — `agents menubar enable` fetches it)')
+        : chalk.yellow(`not fetched yet — the background sync downloads ${s.currentVersion}; \`agents menubar setup\` fetches it now`);
+    console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : pendingSource}`);
     console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
     // Two copies of the INSTALLED bundle is the duplicate the user sees as two
     // agents marks in the menu bar. It used to read as a healthy `running: yes`.

package/dist/commands/ssh.js

@@ -53,6 +53,7 @@ import { stringWidth, stripAnsi, terminalWidth, truncateToWidth } from '../lib/s
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
 import { collectLocalHarnessInventory, groupByAccount, renderAccountsMatrix, renderHarnessMatrix, } from '../lib/devices/harness-inventory.js';
+import { usageErrorForDisplay } from '../lib/accounting/usage.js';
 import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js';
 import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort, registerLeaseCommand } from './lease.js';
 import { registerSnapshotCommand } from './snapshot.js';
@@ -934,16 +935,23 @@ export async function collectFleetHarnesses(opts) {
 async function runDevicesHarnesses(opts) {
     if (opts.local) {
         const rows = await collectLocalHarnessInventory({ agents: opts.agents, refresh: opts.refresh });
-        if (opts.json)
-            console.log(JSON.stringify({ host: machineId(), rows }));
+        if (opts.json) {
+            const sanitized = rows.map((row) => ({ ...row, usageError: usageErrorForDisplay(row.usageError) }));
+            console.log(JSON.stringify({ host: machineId(), rows: sanitized }));
+        }
         else
             for (const line of renderHarnessMatrix([{ host: machineId(), rows }]))
                 console.log(line);
         return;
     }
     const results = await collectFleetHarnesses(opts);
-    if (opts.json)
-        console.log(JSON.stringify(results, null, 2));
+    if (opts.json) {
+        const sanitized = results.map((result) => ({
+            ...result,
+            rows: result.rows.map((row) => ({ ...row, usageError: usageErrorForDisplay(row.usageError) })),
+        }));
+        console.log(JSON.stringify(sanitized, null, 2));
+    }
     else
         for (const line of renderHarnessMatrix(results))
             console.log(line);

package/dist/commands/view.d.ts

@@ -2,14 +2,12 @@ import type { Command } from 'commander';
 import { accountDisplayLabel } from '../lib/agents.js';
 import type { AccountInfo } from '../lib/agents.js';
 import type { AgentId } from '../lib/types.js';
-import type { FormatUsageSummaryOpts, UsageInfo } from '../lib/accounting/usage.js';
 import { type ConfiguredDeviceRole } from '../lib/device-config.js';
 import { type NativeAccountCatalogRow } from '../lib/account-catalog.js';
 import type { ResourceSection, ViewJsonAgent } from '../lib/view-types.js';
 export type { ResourceItemJson, ResourceSection, SyncState, VersionResourcesJson, ViewJsonAgent, ViewJsonVersion } from '../lib/view-types.js';
 import { type ProfileSummary } from '../lib/profiles.js';
 import { type ByokUsageResult } from '../lib/byok-usage.js';
-export declare function viewUsageSummaryOptions(agentId: AgentId, signedIn: boolean, usageInfo: UsageInfo | undefined, maxWindows: number | undefined, version?: string): FormatUsageSummaryOpts;
 /** Shared account identity formatter, re-exported for the view-specific tests. */
 export declare const accountColumnLabel: typeof accountDisplayLabel;
 /**

package/dist/commands/view.js

@@ -17,7 +17,8 @@ import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanag
 import { ambientClaudeToken, loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, readAuthHealthCache } from '../lib/auth-health.js';
-import { agentReportsUsage, classifyUsageErrorKind, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageBenignState, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, usageErrorForDisplay, } from '../lib/accounting/usage.js';
+import { deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, usageErrorForDisplay, viewUsageSummaryOptions, } from '../lib/accounting/usage.js';
+import { OVERVIEW_MAX_USAGE_WINDOWS } from '../lib/account-catalog.js';
 import { isHeadedDeviceRole, selfConfiguredDeviceRole } from '../lib/device-config.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/installations/versions.js';
@@ -47,25 +48,6 @@ import { renderHarnessDetail } from './harness.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
-export function viewUsageSummaryOptions(agentId, signedIn, usageInfo, maxWindows, version) {
-    const headless = isUsageHeadlessScopeError(usageInfo?.error);
-    const benignState = usageInfo ? getUsageBenignState(usageInfo) : null;
-    return {
-        unavailable: agentReportsUsage(agentId) && signedIn && !usageInfo?.snapshot && !headless && !benignState,
-        unverified: !headless && !!usageInfo?.snapshot && !!usageInfo.error,
-        headless,
-        maxWindows,
-        expectedWindows: agentId === 'claude'
-            ? [{ key: 'session', shortLabel: 'S' }, { key: 'week', shortLabel: 'W' }]
-            : undefined,
-        errorKind: classifyUsageErrorKind(usageInfo?.error),
-        errorDetail: usageInfo?.error ?? null,
-        benignState,
-        noRecentUsageLabel: agentId === 'grok'
-            ? `run grok${version ? `@${version}` : ''} once to refresh usage`
-            : null,
-    };
-}
 /** Shared account identity formatter, re-exported for the view-specific tests. */
 export const accountColumnLabel = accountDisplayLabel;
 /**
@@ -107,13 +89,6 @@ export function compareAccountOrderedVersions(a, b, globalDefault) {
     }
     return compareVersions(b.version, a.version);
 }
-/**
- * Overview (`agents view` with no agent filter) caps compact usage windows so
- * multi-meter agents (Antigravity's four model quotas, Droid's three buckets)
- * cannot force every row to pad past the terminal width and wrap. Single-agent
- * views leave the cap unset and show every blocking window.
- */
-const OVERVIEW_MAX_USAGE_WINDOWS = 2;
 /**
  * Join fixed view columns with a consistent two-space gutter. Empty trailing
  * columns are dropped so a row without an auth chip does not grow a dangling
@@ -561,6 +536,7 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                     harnessHeadings: false,
                     providers,
                     harness: agentId,
+                    maxUsageWindows: usageWindowCap,
                     localDevice: machineId(),
                 }));
             }
@@ -580,7 +556,12 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
             console.log();
         }
         if (filterAgentId) {
-            console.log(chalk.gray(`  Add an account: agents accounts add ${filterAgentId} [name]\n`));
+            console.log(chalk.gray(`  Add an account: agents accounts add ${filterAgentId} [name]`));
+            console.log(chalk.gray('  STATE: LIVE ready · LIMITED rate-limited · EXPIRED needs refresh · REVOKED needs login · UNVERIFIED unconfirmed · MISSING not provisioned · * stale usage\n'));
+        }
+        else {
+            // Overview also renders account tables (footer:false) — explain STATE there too.
+            console.log(chalk.gray('  STATE: LIVE ready · LIMITED rate-limited · EXPIRED needs refresh · REVOKED needs login · UNVERIFIED unconfirmed · MISSING not provisioned · * stale usage\n'));
         }
     }
     if (versionManaged.length > 0 && viewOpts?.versions) {

package/dist/lib/account-catalog.d.ts

@@ -4,6 +4,7 @@ import type { AgentId, Meta } from './types.js';
 import { type AuthVerdict } from './auth-health.js';
 import { applyUsageHonesty, type QuotaSummary } from './devices/harness-inventory.js';
 import { type AccountProvisioning, type AccountVerdict } from './signin-badge.js';
+import type { UsageSnapshot } from './accounting/usage.js';
 export { applyUsageHonesty };
 /**
  * Strict "is this home actually connected?" — a live CREDENTIAL in that exact
@@ -78,6 +79,17 @@ export interface NativeAccountCatalogRow {
     checkedAt: string | null;
     devices: AccountDeviceVerdict[];
     usage: QuotaSummary | null;
+    /**
+     * The live usage snapshot backing `usage`, or null when none was collected.
+     * Carried alongside the collapsed `QuotaSummary` so the per-window bars
+     * (S: session 5h, W: week 7d, etc.) can render via the canonical
+     * `formatUsageSummary` / `pickCompactUsageWindows` path instead of the
+     * single max-percent bar. Added non-breaking: JSON clients keep `usage`
+     * and may read this when present.
+     */
+    usageSnapshot?: UsageSnapshot | null;
+    /** Raw usage fetch error, for headless/unverified labeling alongside the bars. */
+    usageError?: string | null;
     fix: string | null;
 }
 export interface AccountDeviceVerdict {
@@ -141,6 +153,9 @@ export interface AccountListEntryJson {
         verdict: AccountDeviceVerdict['verdict'];
     }>;
     usage: QuotaSummary | null;
+    /** The live usage snapshot backing `usage`, when available — additive, not breaking. */
+    usageSnapshot?: UsageSnapshot | null;
+    usageError?: string | null;
     fix: string | null;
 }
 export interface AccountListJson {
@@ -186,6 +201,8 @@ export declare function loadAccountCatalog(): Promise<AccountCatalog>;
  */
 export declare function secretsUnavailableNote(catalog: Pick<AccountCatalog, 'secretsUnavailable'>): string | null;
 export declare function accountListJson(native: NativeAccountCatalogRow[], providers?: ProviderAccountCatalogRow[], harness?: AgentId): AccountListJson;
+export declare function whereText(row: NativeAccountCatalogRow, localDevice: string): string;
+export declare const OVERVIEW_MAX_USAGE_WINDOWS = 2;
 /** Shared text renderer used by both `accounts list` and account-first `view`. */
 export declare function renderAccountRows(rows: NativeAccountCatalogRow[], opts: {
     heading?: boolean;
@@ -194,6 +211,12 @@ export declare function renderAccountRows(rows: NativeAccountCatalogRow[], opts:
     providers?: ProviderAccountCatalogRow[];
     /** When set, emit only this harness's group — never a sibling or empty group. */
     harness?: AgentId;
+    /**
+     * Cap for compact usage windows — overview (no harness filter) passes 2,
+     * single-harness view leaves it undefined to show all blocking windows.
+     * Mirrors `OVERVIEW_MAX_USAGE_WINDOWS` in view.ts.
+     */
+    maxUsageWindows?: number;
     /**
      * Device name treated as "this box" in WHERE when it is the only reporter.
      * The command layer passes `machineId()`; this renderer never resolves it.
@@ -227,3 +250,4 @@ export declare function resolveLocalAccountObservation(slot: LocalSlotObservatio
     authMode?: AccountDeviceVerdict['authMode'];
     checkedAt?: string;
 };
+export declare function aggregateAccountVerdict(provisioning: AccountProvisioning, devices: AccountDeviceVerdict[], localQuota?: QuotaSummary | null): AccountVerdict;

package/dist/lib/account-catalog.js

@@ -14,7 +14,7 @@ import { machineId } from './machine-id.js';
 import { isHeadedDeviceRole, selfConfiguredDeviceRole } from './device-config.js';
 import { applyUsageHonesty, collectLocalHarnessInventory, } from './devices/harness-inventory.js';
 import { fixFor, } from './signin-badge.js';
-import { renderBar } from './accounting/usage.js';
+import { formatUsageSummary, renderBar, usageErrorForDisplay, viewUsageSummaryOptions, } from './accounting/usage.js';
 import { padToWidth, stringWidth } from './text/width.js';
 export { applyUsageHonesty };
 import chalk from 'chalk';
@@ -184,6 +184,8 @@ export function buildNativeCatalog(rows, meta, globalDefault = getGlobalDefault)
             checkedAt: null,
             devices: [],
             usage: null,
+            usageSnapshot: null,
+            usageError: null,
             fix: fixFor({
                 agent: group.agent,
                 verdict: signedIn ? 'unverified' : 'missing',
@@ -275,11 +277,15 @@ export async function loadAccountCatalog() {
             ? (shared.get(`${row.agent}:${row.id}`) ?? [])
             : (shared.get(`label:${row.agent}:${row.identityLabel}`) ?? []);
         row.devices = mergeDeviceVerdicts(fromFleet, local);
-        row.verdict = aggregateAccountVerdict(row.provisioning, row.devices);
+        const localQuota = localHome ? (inventoryByHome.get(`${row.agent}:${localHome.label}`)?.quota ?? null) : null;
+        row.verdict = aggregateAccountVerdict(row.provisioning, row.devices, localQuota);
         row.checkedAt = newestCheckedAt(row.devices);
-        const honest = applyUsageHonesty(row.verdict, localHome ? (inventoryByHome.get(`${row.agent}:${localHome.label}`)?.quota ?? null) : null);
+        const honest = applyUsageHonesty(row.verdict, localQuota);
         row.verdict = honest.verdict;
         row.usage = honest.usage;
+        const inv = localHome ? inventoryByHome.get(`${row.agent}:${localHome.label}`) : undefined;
+        row.usageSnapshot = inv?.snapshot ?? null;
+        row.usageError = inv?.usageError ?? null;
         row.fix = fixFor({
             agent: row.agent,
             verdict: row.verdict,
@@ -353,6 +359,8 @@ export function accountListJson(native, providers = [], harness) {
                 checkedAt: row.checkedAt,
                 devices: row.devices.map(({ device, authMode, verdict }) => ({ device, authMode, verdict })),
                 usage: row.usage,
+                ...(row.usageSnapshot ? { usageSnapshot: row.usageSnapshot } : {}),
+                ...((() => { const v = usageErrorForDisplay(row.usageError); return v ? { usageError: v } : {}; })()),
                 fix: row.fix,
             })),
             ...providers.flatMap((row) => providerJsonEntries(row, harness)),
@@ -364,24 +372,35 @@ function verdictText(verdict) {
         return 'LIMITED';
     return verdict.toUpperCase();
 }
-function whereText(row, localDevice) {
+export function whereText(row, localDevice) {
     const names = [...new Set(row.devices.map((device) => device.device))];
     // Peers on an older release do not publish slot verdicts, so the only
-    // observation is this box — say so rather than a coverage count of +1.
+    // observation is this box — say so rather than a coverage count.
     if (names.length === 1 && names[0] === localDevice)
         return 'this box';
-    const live = row.devices.filter((device) => device.verdict === 'live').length;
-    if (live > 0)
-        return `+${live}`;
+    // Per-device accounts are provisioned per box; show which boxes are present
+    // rather than a live/total fraction — the fraction would hide that each box
+    // is its own account.
     if (row.provisioning === 'per-device') {
         const present = row.devices
             .filter((device) => device.verdict !== 'missing')
             .map((device) => device.device);
         return present.join(', ') || 'this box';
     }
-    return '—';
+    const provisioned = row.devices.filter((device) => device.verdict !== 'missing').length;
+    if (provisioned === 0)
+        return '—';
+    const usable = row.devices.filter((device) => device.verdict === 'live' || device.verdict === 'rate_limited' || device.verdict === 'unverified').length;
+    if (usable === provisioned)
+        return `on ${usable} ${usable === 1 ? 'box' : 'boxes'}`;
+    return `on ${usable} of ${provisioned} boxes`;
 }
-function usageText(row) {
+export const OVERVIEW_MAX_USAGE_WINDOWS = 2;
+function usageText(row, maxWindows) {
+    if (row.usageSnapshot) {
+        const usageInfo = { snapshot: row.usageSnapshot, error: row.usageError ?? null };
+        return formatUsageSummary(null, usageInfo.snapshot, 3, viewUsageSummaryOptions(row.agent, row.state === 'connected', usageInfo, maxWindows));
+    }
     if (row.usage?.status === 'rate_limited' && (row.usage.usedPercent === null || row.usage.usedPercent === undefined)) {
         return 'limited';
     }
@@ -392,14 +411,14 @@ function usageText(row) {
     const percent = `${row.usage.usedPercent}%${row.usage.stale ? '*' : ''}`;
     return `${renderBar(row.usage.usedPercent, LISTING_USAGE_BAR_LEN)} ${percent}`;
 }
-function nativeLine(row, localDevice) {
+function nativeLine(row, localDevice, maxWindows) {
     return {
         name: row.name ?? 'unnamed',
         identityLabel: row.identityLabel,
         verdict: row.verdict,
         where: whereText(row, localDevice),
         fix: row.fix,
-        usage: usageText(row),
+        usage: usageText(row, maxWindows),
         isDefault: row.isDefault,
     };
 }
@@ -465,10 +484,11 @@ export function renderAccountRows(rows, opts) {
                     harnesses.add(agent);
             }
         }
+        const maxWindows = opts.maxUsageWindows ?? (opts.harness ? undefined : OVERVIEW_MAX_USAGE_WINDOWS);
         const grouped = new Map();
         for (const harness of [...harnesses].sort((a, b) => a.localeCompare(b))) {
             const lines = [
-                ...visibleNative.filter((row) => row.agent === harness).map((row) => nativeLine(row, localDevice)),
+                ...visibleNative.filter((row) => row.agent === harness).map((row) => nativeLine(row, localDevice, maxWindows)),
                 ...visibleProviders.filter((row) => row.harnesses.includes(harness)).map((row) => providerLine(row, harness)),
             ];
             if (lines.length === 0)
@@ -499,6 +519,7 @@ export function renderAccountRows(rows, opts) {
         const count = visibleNative.filter((row) => !!row.fix).length
             + visibleProviders.filter((row) => !!row.fix).length;
         out.push(chalk.gray(`${count} accounts need you · add: agents accounts add <harness>`));
+        out.push(chalk.gray('STATE: LIVE ready · LIMITED rate-limited · EXPIRED needs refresh · REVOKED needs login · UNVERIFIED unconfirmed · MISSING not provisioned · * stale usage'));
     }
     return out.join('\n').trimEnd();
 }
@@ -574,13 +595,22 @@ function mergeDeviceVerdicts(fleet, local) {
     byDevice.set(local.device, local);
     return [...byDevice.values()].sort((a, b) => a.device.localeCompare(b.device));
 }
-function aggregateAccountVerdict(provisioning, devices) {
+export function aggregateAccountVerdict(provisioning, devices, localQuota) {
     const verdicts = devices.map((row) => row.verdict);
     if (verdicts.includes('revoked'))
         return 'revoked';
     if (verdicts.includes('expired'))
         return 'expired';
-    if (verdicts.includes('rate_limited'))
+    // LIMITED comes from the usage snapshot only (PHNX-3940/4051): an account's
+    // quota is one shared identity and `deriveUsageStatusFromSnapshot` already
+    // applies the freshness gate (expired windows -> staleWindows), so a
+    // `last_seen` snapshot whose blocking windows are below 100% is trustworthy
+    // for "not throttled". A remote `rate_limited` (probe 429) never sets STATE;
+    // only the local `QuotaSummary.status` (`rate_limited`/`out_of_credits` via
+    // `applyUsageHonesty`) does. When this box has no usage snapshot at all
+    // (no windows, `usedPercent === null`), the remote `rate_limited` may stand.
+    const hasLocalSnapshot = !!localQuota && localQuota.usedPercent !== null && localQuota.usedPercent !== undefined;
+    if (!hasLocalSnapshot && verdicts.includes('rate_limited'))
         return 'rate_limited';
     if (verdicts.includes('live'))
         return 'live';

package/dist/lib/accounting/usage.d.ts

@@ -447,6 +447,13 @@ export interface FormatUsageSummaryOpts {
     /** Provider-specific replacement for the generic no-local-event marker. */
     noRecentUsageLabel?: string | null;
 }
+/**
+ * Shared builder for {@link formatUsageSummary} options in `agents view` and
+ * account-catalog rows. One builder, no copy — captures `headless`,
+ * `unverified`, `expectedWindows`, `errorKind`, `benignState`, and the grok
+ * `noRecentUsageLabel` consistently.
+ */
+export declare function viewUsageSummaryOptions(agentId: AgentId, signedIn: boolean, usageInfo: UsageInfo | undefined, maxWindows: number | undefined, version?: string): FormatUsageSummaryOpts;
 /** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number, opts?: FormatUsageSummaryOpts): string;
 /**

package/dist/lib/accounting/usage.js

@@ -559,6 +559,31 @@ export function pickCompactUsageWindows(windows, maxWindows) {
     }
     return chosen;
 }
+/**
+ * Shared builder for {@link formatUsageSummary} options in `agents view` and
+ * account-catalog rows. One builder, no copy — captures `headless`,
+ * `unverified`, `expectedWindows`, `errorKind`, `benignState`, and the grok
+ * `noRecentUsageLabel` consistently.
+ */
+export function viewUsageSummaryOptions(agentId, signedIn, usageInfo, maxWindows, version) {
+    const headless = isUsageHeadlessScopeError(usageInfo?.error);
+    const benignState = usageInfo ? getUsageBenignState(usageInfo) : null;
+    return {
+        unavailable: agentReportsUsage(agentId) && signedIn && !usageInfo?.snapshot && !headless && !benignState,
+        unverified: !headless && !!usageInfo?.snapshot && !!usageInfo.error,
+        headless,
+        maxWindows,
+        expectedWindows: agentId === 'claude'
+            ? [{ key: 'session', shortLabel: 'S' }, { key: 'week', shortLabel: 'W' }]
+            : undefined,
+        errorKind: classifyUsageErrorKind(usageInfo?.error),
+        errorDetail: usageInfo?.error ?? null,
+        benignState,
+        noRecentUsageLabel: agentId === 'grok'
+            ? `run grok${version ? `@${version}` : ''} once to refresh usage`
+            : null,
+    };
+}
 /** Human label for a classified usage error, for the no-bars branch of {@link formatUsageSummary}. */
 function formatUsageErrorKindLabel(kind, detail) {
     switch (kind) {

package/dist/lib/auth-health.d.ts

@@ -7,11 +7,18 @@ import { type ProviderProbe } from './accounting/usage.js';
  *                   setup-token `user:profile` scope denials (those are
  *                   `unverified` via `reason: 'usage_scope'` — RUSH-2392).
  * - `expired`     — locally-detected expiry; not network-verified (no refresh on the read path).
- * - `rate_limited`— token works but is throttled right now (429).
+ * - `rate_limited`— the account is throttled per its usage snapshot
+ *                   ({@link deriveUsageStatusFromSnapshot} / {@link applyUsageHonesty}),
+ *                   not per a probe HTTP 429. A 429 from the usage endpoint is
+ *                   probe throttling and never produces `rate_limited`: it keeps
+ *                   the previous real verdict when one exists within
+ *                   {@link AUTH_PROBE_MAX_AGE_MS}, otherwise `unverified` with
+ *                   detail `probe throttled (HTTP 429)` (PHNX-4051).
  * - `unverified`  — credential present, not locally expired, but this agent has
  *                   no in-repo probe endpoint (codex/grok), OR the probe
  *                   endpoint cannot prove live for a known non-revocation
- *                   reason (Claude setup-token usage-scope gap — RUSH-2392).
+ *                   reason (Claude setup-token usage-scope gap — RUSH-2392),
+ *                   OR a throttled probe with no fresh previous verdict (PHNX-4051).
  * - `unconfigured`— no usable credential on disk.
  * - `error`       — network/other failure; verdict indeterminate (keep the last known one).
  */
@@ -31,7 +38,7 @@ export interface AuthHealth {
 export declare const AUTH_PROBE_MAX_AGE_MS: number;
 /** Agents with a live network probe wired up today. The rest are best-effort. */
 export declare const LIVE_PROBE_AGENTS: ReadonlySet<AgentId>;
-/** Map an HTTP status from a live probe to a verdict. */
+/** Map an HTTP status from a live probe to a verdict. Probe 429 never yields `rate_limited` (PHNX-4051). */
 export declare function classifyHttpStatus(status: number): AuthVerdict;
 /** Turn a raw provider probe (from usage.ts) into a verdict. */
 export declare function verdictFromProbe(probe: ProviderProbe): AuthVerdict;
@@ -202,7 +209,9 @@ export declare function readFleetAuthRows(host: string): AuthProbeRow[];
  * known verdict — otherwise one 8s timeout flips a `live` chip to `error`,
  * exactly the "cry wolf" the verdict model avoids for `expired`. This is the
  * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
- * one"). Pure, so it's unit-tested directly. */
+ * one"). A probe-throttled 429 (detail `probe throttled (HTTP 429)`) keeps the
+ * previous real verdict when one exists within {@link AUTH_PROBE_MAX_AGE_MS},
+ * otherwise becomes `unverified` (PHNX-4051). Pure, so it's unit-tested directly. */
 export declare function mergeAuthHealthEntries(current: Record<string, AuthHealth>, incoming: Record<string, AuthHealth>): Record<string, AuthHealth>;
 /**
  * Merge one or more entries into the cache (best-effort write).
@@ -247,6 +256,8 @@ export interface FleetAuthInstall {
     version: string;
     /** Human account label from {@link authAccountLabel}, or undefined when none resolves. */
     account: string | undefined;
+    /** Stable account id when known (slot or resolved via registry) — preferred dedup key. */
+    accountId?: string | undefined;
 }
 /**
  * A set of installs that share one provider account and MUST be probed once.
@@ -278,6 +289,8 @@ export interface FleetAuthProbeGroup<T extends FleetAuthInstall> {
  * per-install probe (also the `unconfigured` case dropped downstream). Pure: no
  * fs, no network, so the dedup decision is unit-tested directly.
  */
+/** Small fixed delay between live probes so one box no longer fires 16 requests in 4s (PHNX-4051). */
+export declare const AUTH_PROBE_SPACING_MS = 150;
 export declare function groupFleetAuthInstalls<T extends FleetAuthInstall>(installs: readonly T[], isMergeable?: (install: T) => boolean): FleetAuthProbeGroup<T>[];
 /**
  * Enumerate every installed (agent, version) on THIS host and return one row per