@phnx-labs/agents-cli 1.22.101 → 1.22.102

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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/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

package/dist/lib/auth-health.js

@@ -32,14 +32,18 @@ export const LIVE_PROBE_AGENTS = new Set(['claude', 'kimi', 'droid']);
 // ---------------------------------------------------------------------------
 // Pure classifiers / render (unit-tested; no network, no fs)
 // ---------------------------------------------------------------------------
-/** 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 function classifyHttpStatus(status) {
     if (status >= 200 && status < 300)
         return 'live';
     if (status === 401 || status === 403)
         return 'revoked';
+    // 429 is probe throttling, not an account throttle — the account's real
+    // throttle state comes from the usage snapshot (deriveUsageStatusFromSnapshot).
+    // Treating it as `rate_limited` let a burst-throttled endpoint mark every
+    // account LIMITED. See mergeAuthHealthEntries for the keep-or-unverified path.
     if (status === 429)
-        return 'rate_limited';
+        return 'error';
     return 'error';
 }
 /** Turn a raw provider probe (from usage.ts) into a verdict. */
@@ -62,6 +66,8 @@ export function probeDetail(probe) {
     if (probe.reason === 'usage_scope') {
         return probe.error ?? USAGE_HEADLESS_SCOPE_MARKER;
     }
+    if (probe.status === 429)
+        return 'probe throttled (HTTP 429)';
     if (probe.status != null && (probe.status < 200 || probe.status >= 300))
         return `HTTP ${probe.status}`;
     if (probe.error)
@@ -345,10 +351,22 @@ export function readFleetAuthRows(host) {
  * 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 function mergeAuthHealthEntries(current, incoming) {
     const merged = { ...current };
     for (const [key, health] of Object.entries(incoming)) {
+        const isProbeThrottled = health.detail === 'probe throttled (HTTP 429)';
+        if (isProbeThrottled) {
+            const prev = merged[key];
+            const fresh = !!prev && prev.verdict !== 'error' && prev.verdict !== 'unconfigured'
+                && (health.checkedAt - prev.checkedAt < AUTH_PROBE_MAX_AGE_MS);
+            if (fresh)
+                continue; // keep previous real verdict
+            merged[key] = { ...health, verdict: 'unverified' };
+            continue;
+        }
         if (health.verdict === 'error' && merged[key])
             continue; // keep last known
         merged[key] = health;
@@ -470,13 +488,22 @@ export async function probeAuthHealth(agent, home, opts) {
  * 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 const AUTH_PROBE_SPACING_MS = 150;
 export function groupFleetAuthInstalls(installs, isMergeable = () => true) {
     const groups = new Map();
     for (const inst of installs) {
-        // The `acct:` / `ver:` tokens make the two branches disjoint, so an account
-        // label can never collide with a version fallback key no matter its content.
-        const key = inst.account && isMergeable(inst)
-            ? `${inst.agent} acct:${inst.account}`
+        // Prefer stable accountId (identity) — a version home and its slot share the
+        // same id, so they collapse to ONE probe per identity (PHNX-4051). Fallback
+        // to the display label when no id is known. The `id:`/`acct:`/`ver:` tokens
+        // keep the three branches disjoint.
+        const mergeKey = inst.accountId
+            ? `id:${inst.accountId}`
+            : inst.account
+                ? `acct:${inst.account}`
+                : null;
+        const key = mergeKey && isMergeable(inst)
+            ? `${inst.agent} ${mergeKey}`
             : `${inst.agent} ver:${inst.version}`;
         const existing = groups.get(key);
         if (existing)
@@ -514,26 +541,37 @@ export async function probeLocalFleetAuth(opts) {
         // A slot already knows its account; a version home is joined by identity.
         inst.accountId ??= findNativeAccountByIdentity(meta, inst.agent, inst.info)?.id;
     }
-    // Probe once per (agent, account) — but only for the network-probing agents
+    // Probe once per (agent, identity) — but only for the network-probing agents
     // that can actually 429; best-effort agents stay per-install (see
-    // groupFleetAuthInstalls). Groups run in parallel: they target distinct
-    // accounts, so no same-account concurrency is left to trip the throttle.
-    const perGroup = await Promise.all(groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent)).map(async (group) => {
+    // groupFleetAuthInstalls). Groups are probed SEQUENTIALLY with a small fixed
+    // delay between them (PHNX-4051) so one box no longer fires 16 requests in
+    // 4s; they target distinct identities, so no same-account concurrency remains.
+    const groups = groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent));
+    const perGroup = [];
+    for (let idx = 0; idx < groups.length; idx++) {
+        const group = groups[idx];
         const rep = group.probe;
         const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info, forceLive: opts?.forceLive, signal: opts?.signal });
         health.account = authAccountLabel(rep.info);
         health.accountId = rep.accountId;
-        if (health.verdict === 'unconfigured')
-            return [];
-        return group.members.map((inst) => ({
-            agent: inst.agent,
-            version: inst.version,
-            account: health.account,
-            accountId: inst.accountId ?? health.accountId,
-            // A distinct object per row so a later mutation of one can't bleed across.
-            health: { ...health },
-        }));
-    }));
+        if (health.verdict === 'unconfigured') {
+            perGroup.push([]);
+        }
+        else {
+            perGroup.push(group.members.map((inst) => ({
+                agent: inst.agent,
+                version: inst.version,
+                account: health.account,
+                accountId: inst.accountId ?? health.accountId,
+                // A distinct object per row so a later mutation of one can't bleed across.
+                health: { ...health },
+            })));
+        }
+        // Space probes; not after the last group and not if the tick is being aborted.
+        if (idx < groups.length - 1 && !opts?.signal?.aborted) {
+            await new Promise((resolve) => setTimeout(resolve, AUTH_PROBE_SPACING_MS));
+        }
+    }
     return perGroup.flat();
 }
 /**

package/dist/lib/auto-pull-worker.js

@@ -51,6 +51,13 @@ function tryAcquireLock(alias) {
         return false;
     }
 }
+function touchLock(alias) {
+    const now = new Date();
+    try {
+        fs.utimesSync(lockFilePath(alias), now, now);
+    }
+    catch { /* lock gone; nothing to extend */ }
+}
 function releaseLock(alias) {
     try {
         fs.unlinkSync(lockFilePath(alias));
@@ -118,6 +125,36 @@ async function processTarget(target) {
         releaseLock(target.alias);
     }
 }
+/**
+ * macOS only: fetch the floor AGI Menu release into the verified cache when the
+ * installed helper is behind it and no bundle ships with this install, so the
+ * next foreground invocation's network-free self-heal has a source to install
+ * from (`sourceAppPath` candidate 4). Same lock discipline as the repo targets.
+ */
+async function prefetchMenubarHelperTarget() {
+    if (process.platform !== 'darwin')
+        return;
+    const alias = 'menubar-helper';
+    if (!tryAcquireLock(alias))
+        return;
+    // The zip fetch may run up to 15 min (helper-download.ts) while the lock
+    // reads as stale after SYNC_LOCK_TTL_MS, and the download lands through one
+    // shared partial file — so keep the lock's mtime fresh for as long as this
+    // worker is actually fetching, or a second worker races onto the same bytes.
+    const heartbeat = setInterval(() => touchLock(alias), SYNC_LOCK_TTL_MS / 2);
+    heartbeat.unref();
+    try {
+        const { prefetchMenubarHelper } = await import('./menubar/install-menubar.js');
+        await prefetchMenubarHelper();
+    }
+    catch {
+        /* network / verification failures are non-fatal; the next cycle retries */
+    }
+    finally {
+        clearInterval(heartbeat);
+        releaseLock(alias);
+    }
+}
 async function main() {
     const targets = [];
     const systemDir = getSystemAgentsDir();
@@ -133,7 +170,7 @@ async function main() {
             targets.push({ alias: extra.alias, dir: extra.dir, mode: 'notify' });
         }
     }
-    await Promise.all(targets.map(processTarget));
+    await Promise.all([...targets.map(processTarget), prefetchMenubarHelperTarget()]);
     // Stamp the cycle so the next foreground CLI invocation can skip the ~7ms
     // detached spawn for SYNC_LOCK_TTL_MS (RUSH-2324). Written even when every
     // target was lock-skipped or the target list was empty — "nothing to do"

package/dist/lib/devices/harness-inventory.d.ts

@@ -36,6 +36,10 @@ export interface HarnessRow {
     reason?: string;
     verdict: AccountVerdict;
     fix: string | null;
+    /** The live usage snapshot backing `quota`, or null when none was collected. */
+    snapshot: UsageSnapshot | null;
+    /** Raw error string from the usage fetch, if any (headless scope, expired, etc.). */
+    usageError: string | null;
 }
 /** One host's rows, or the reason it produced none. */
 export interface HostHarnessResult {

package/dist/lib/devices/harness-inventory.js

@@ -123,7 +123,7 @@ export function applyUsageHonesty(verdict, usage) {
         }
         return { verdict, usage: stripped };
     }
-    if (usage.status === 'rate_limited' && (verdict === 'live' || verdict === 'unverified')) {
+    if ((usage.status === 'rate_limited' || usage.status === 'out_of_credits') && (verdict === 'live' || verdict === 'unverified')) {
         return { verdict: 'rate_limited', usage };
     }
     return { verdict, usage };
@@ -204,6 +204,8 @@ export async function collectLocalHarnessInventory(opts) {
             reason,
             verdict,
             fix: fixFor({ agent, verdict, name: saved?.name, version, provisioning }),
+            snapshot,
+            usageError: usage?.error ?? null,
         };
     });
 }

package/dist/lib/feed/pr-status.d.ts

@@ -1,4 +1,6 @@
 import type { ActiveSession } from '../session/active.js';
+import type { DetectedPr } from '../session/state.js';
+import type { GhExec } from '../github/pr-mergeable.js';
 import type { PullRequestAttentionSignal } from './attention.js';
 export declare const PR_STATUS_TTL_MS = 45000;
 export declare const PR_STATUS_FIELDS = "number,title,state,isDraft,reviewDecision,mergeable,statusCheckRollup";
@@ -9,6 +11,22 @@ export interface PullRequestStatus extends PullRequestAttentionSignal {
 export declare function readPullRequestStatus(session: ActiveSession, options?: {
     nowMs?: number;
     ttlMs?: number;
+    gh?: GhExec;
 }): Promise<PullRequestStatus | undefined>;
 export declare function projectPullRequestBoard(sessions: ActiveSession[]): Promise<PullRequestStatus[]>;
 export declare function resetPullRequestStatusCache(): void;
+/**
+ * The check rollup folded to one verdict; undefined when the PR has no checks.
+ * `statusCheckRollup` mixes Checks-API runs (`conclusion` + `status`) with
+ * legacy Status-API contexts (`state` only), so both shapes are read.
+ */
+export declare function checksVerdict(rollup?: unknown[]): DetectedPr['checks'];
+/**
+ * The row with its `pr` carrying the fetched status, so a consumer that only
+ * sees the agent row (the menu bar, the extension) can color the chip without
+ * its own `gh` call. A row without a PR, or a status that never resolved, is
+ * returned as is.
+ */
+export declare function withPullRequestStatus<T extends {
+    pr?: DetectedPr;
+}>(row: T, status?: PullRequestStatus): T;

package/dist/lib/feed/pr-status.js

@@ -24,12 +24,10 @@ export async function readPullRequestStatus(session, options = {}) {
     const hit = cache.get(key);
     if (hit && hit.expiresAt > now)
         return hit.value;
+    const cwd = session.cwd;
+    const gh = options.gh ?? (async (args) => (await execFileAsync('gh', args, { cwd, timeout: 15_000, maxBuffer: 1024 * 1024 })).stdout);
     try {
-        const { stdout } = await execFileAsync('gh', ['pr', 'view', String(ref), '--json', PR_STATUS_FIELDS], {
-            cwd: session.cwd,
-            timeout: 15_000,
-            maxBuffer: 1024 * 1024,
-        });
+        const stdout = await gh(['pr', 'view', String(ref), '--json', PR_STATUS_FIELDS]);
         const raw = JSON.parse(stdout);
         const value = { ...raw, url: session.pr?.url, needsHuman: needsHuman(raw) };
         cache.set(key, { expiresAt: now + (options.ttlMs ?? PR_STATUS_TTL_MS), value });
@@ -45,3 +43,43 @@ export async function projectPullRequestBoard(sessions) {
     return rows.filter((row) => row !== undefined);
 }
 export function resetPullRequestStatusCache() { cache.clear(); }
+/**
+ * The check rollup folded to one verdict; undefined when the PR has no checks.
+ * `statusCheckRollup` mixes Checks-API runs (`conclusion` + `status`) with
+ * legacy Status-API contexts (`state` only), so both shapes are read.
+ */
+export function checksVerdict(rollup) {
+    if (!rollup || rollup.length === 0)
+        return undefined;
+    let pending = false;
+    for (const check of rollup) {
+        const row = check;
+        const verdict = (row.conclusion || row.state || '').toUpperCase();
+        if (['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(verdict))
+            return 'failing';
+        if (verdict === '' ? (row.status ?? '').toUpperCase() !== 'COMPLETED' : ['PENDING', 'EXPECTED', 'STALE'].includes(verdict))
+            pending = true;
+    }
+    return pending ? 'pending' : 'passing';
+}
+/**
+ * The row with its `pr` carrying the fetched status, so a consumer that only
+ * sees the agent row (the menu bar, the extension) can color the chip without
+ * its own `gh` call. A row without a PR, or a status that never resolved, is
+ * returned as is.
+ */
+export function withPullRequestStatus(row, status) {
+    if (!row.pr || !status)
+        return row;
+    const pr = {
+        ...row.pr,
+        ...(status.state !== undefined ? { state: status.state } : {}),
+        ...(status.isDraft !== undefined ? { isDraft: status.isDraft } : {}),
+        ...(status.reviewDecision !== undefined ? { reviewDecision: status.reviewDecision } : {}),
+        ...(status.mergeable !== undefined ? { mergeable: status.mergeable } : {}),
+    };
+    const checks = checksVerdict(status.statusCheckRollup);
+    if (checks)
+        pr.checks = checks;
+    return { ...row, pr };
+}

package/dist/lib/feed/watch.d.ts

@@ -1,6 +1,7 @@
 import { type SessionWatchEnvelope, type SessionWatchRow, type SessionWatchScopeStatus, type WatchLocalOptions } from '../session/watch.js';
 import { type AttentionItem } from './attention.js';
 import { type ActivityEvent } from './activity.js';
+import type { GhExec } from '../github/pr-mergeable.js';
 export declare const FEED_WATCH_VERSION: 1;
 type Base = {
     v: 1;
@@ -47,7 +48,7 @@ export declare class FeedWatchState {
     constructor(streamId?: `${string}-${string}-${string}-${string}-${string}`);
     emit(event: FeedWatchPayload): FeedWatchEnvelope;
 }
-export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState): Promise<FeedWatchEnvelope[]>;
+export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState, gh?: GhExec): Promise<FeedWatchEnvelope[]>;
 export interface WatchLocalFeedOptions {
     scope: string;
     signal: AbortSignal;
@@ -58,6 +59,8 @@ export interface WatchLocalFeedOptions {
     reconcileMs?: number;
     /** Session-watch inputs, forwarded verbatim to {@link watchLocalSessions}. */
     sessions?: Pick<WatchLocalOptions, 'readCache' | 'readPrevious' | 'journalPath' | 'journalPollMs' | 'heartbeatMs'>;
+    /** The `gh` runner behind PR status; a test passes a recorded table. */
+    gh?: GhExec;
 }
 export declare function watchLocalFeed(options: WatchLocalFeedOptions): Promise<void>;
 export declare function watchFleetFeed(options: {

package/dist/lib/feed/watch.js

@@ -11,7 +11,7 @@ import { watchLocalSessions } from '../session/watch.js';
 import { readBlock, readResolution, blockIdForSession } from './feed.js';
 import { reconcileAttention } from './attention.js';
 import { ActivityStream } from './activity-stream.js';
-import { PR_STATUS_TTL_MS, readPullRequestStatus } from './pr-status.js';
+import { PR_STATUS_TTL_MS, readPullRequestStatus, withPullRequestStatus } from './pr-status.js';
 export const FEED_WATCH_VERSION = 1;
 export class FeedWatchState {
     streamId;
@@ -21,36 +21,51 @@ export class FeedWatchState {
         return { v: 1, streamId: this.streamId, sequence: ++this.sequence, ...event };
     }
 }
-async function attentionFor(agent) {
-    // Durable Previous rows share the operator stream for Sessions history, but
-    // they are not live work and must never synthesize Needs-you attention.
-    if (!agent.sessionId || agent.previous || agent.context === 'recent')
+/**
+ * Live rows only: durable Previous rows share the operator stream for Sessions
+ * history, but they are not live work and must never synthesize Needs-you
+ * attention or a PR lookup.
+ */
+function isLive(agent) {
+    return Boolean(agent.sessionId) && !agent.previous && agent.context !== 'recent';
+}
+// ActiveSession.host names the terminal app; the feed contract's host is the
+// device scope. Normalize only the reconciler input so lifecycle/PR keys are
+// routable across the fleet while the projected agent row stays compatible.
+function reconcilerSession(agent) {
+    return { ...agent, context: agent.context, host: agent.sourceDevice, viewingIn: undefined };
+}
+/** One `gh pr view` (cached 45 s) feeds both the attention verdict and the row's `pr` status. */
+async function pullRequestFor(agent, gh) {
+    if (!isLive(agent) || !agent.pr)
+        return undefined;
+    return readPullRequestStatus(reconcilerSession(agent), { gh });
+}
+function attentionFor(agent, pullRequest) {
+    if (!isLive(agent) || !agent.sessionId)
         return undefined;
     const blockId = blockIdForSession(agent.sessionId);
-    // ActiveSession.host names the terminal app; the feed contract's host is the
-    // device scope. Normalize only the reconciler input so lifecycle/PR keys are
-    // routable across the fleet while the projected agent row stays compatible.
-    const session = {
-        ...agent,
-        context: agent.context,
-        host: agent.sourceDevice,
-        viewingIn: undefined,
-    };
     return reconcileAttention({
-        block: readBlock(blockId), session,
+        block: readBlock(blockId), session: reconcilerSession(agent),
         resolution: readResolution(blockId),
-        pullRequest: await readPullRequestStatus(session), nowMs: Date.now(),
+        pullRequest, nowMs: Date.now(),
     });
 }
-export async function projectSessionEnvelope(event, state) {
+/** The row as the feed projects it: the session row with its PR status attached. */
+async function projectAgent(agent, gh) {
+    const pullRequest = await pullRequestFor(agent, gh);
+    return { agent: withPullRequestStatus(agent, pullRequest), attention: attentionFor(agent, pullRequest) };
+}
+export async function projectSessionEnvelope(event, state, gh) {
     if (event.type === 'reset') {
-        const attention = (await Promise.all(event.rows.map(attentionFor))).filter((item) => item !== undefined);
-        return [state.emit({ type: 'reset', capturedAt: event.capturedAt, scope: event.scope, agents: event.rows, attention })];
+        const projected = await Promise.all(event.rows.map((row) => projectAgent(row, gh)));
+        const attention = projected.map((p) => p.attention).filter((item) => item !== undefined);
+        return [state.emit({ type: 'reset', capturedAt: event.capturedAt, scope: event.scope, agents: projected.map((p) => p.agent), attention })];
     }
     if (event.type === 'upsert') {
-        const attention = await attentionFor(event.row);
+        const { agent, attention } = await projectAgent(event.row, gh);
         return [
-            state.emit({ type: 'agent.upsert', scope: event.scope, rowKey: event.rowKey, agent: event.row }),
+            state.emit({ type: 'agent.upsert', scope: event.scope, rowKey: event.rowKey, agent }),
             attention
                 ? state.emit({ type: 'attention.upsert', scope: event.scope, rowKey: event.rowKey, attention })
                 : state.emit({ type: 'attention.remove', scope: event.scope, rowKey: event.rowKey }),
@@ -99,10 +114,18 @@ export async function watchLocalFeed(options) {
     let activityCursor = Date.now();
     const agents = new Map();
     const attention = new Map();
+    // The PR status last projected onto each row, so a merge or a check verdict
+    // that lands between session events still reaches the row's consumers.
+    const prStatus = new Map();
     let pending = Promise.resolve();
     const reconcileRows = async () => {
-        for (const [rowKey, agent] of agents) {
-            const item = await attentionFor(agent);
+        for (const [rowKey, raw] of agents) {
+            const { agent, attention: item } = await projectAgent(raw, options.gh);
+            const nextPr = agent.pr ? JSON.stringify(agent.pr) : '';
+            if (agent.pr && prStatus.get(rowKey) !== nextPr) {
+                prStatus.set(rowKey, nextPr);
+                options.emit(state.emit({ type: 'agent.upsert', scope: options.scope, rowKey, agent }));
+            }
             const next = item ? JSON.stringify(item) : '';
             if (attention.get(rowKey) === next)
                 continue;
@@ -150,19 +173,28 @@ export async function watchLocalFeed(options) {
                 else if (event.type === 'remove') {
                     agents.delete(event.rowKey);
                     attention.delete(event.rowKey);
+                    prStatus.delete(event.rowKey);
                 }
-                pending = pending.then(() => projectSessionEnvelope(event, state)).then((events) => {
+                pending = pending.then(() => projectSessionEnvelope(event, state, options.gh)).then((events) => {
                     for (const projected of events) {
                         if (projected.type === 'reset') {
                             attention.clear();
-                            for (const row of projected.agents)
+                            prStatus.clear();
+                            for (const row of projected.agents) {
                                 attention.set(row.rowKey, '');
+                                if (row.pr)
+                                    prStatus.set(row.rowKey, JSON.stringify(row.pr));
+                            }
                             for (const item of projected.attention) {
                                 const row = projected.agents.find((agent) => agent.sessionId === item.sessionId);
                                 if (row)
                                     attention.set(row.rowKey, JSON.stringify(item));
                             }
                         }
+                        else if (projected.type === 'agent.upsert') {
+                            if (projected.agent.pr)
+                                prStatus.set(projected.rowKey, JSON.stringify(projected.agent.pr));
+                        }
                         else if (projected.type === 'attention.upsert')
                             attention.set(projected.rowKey, JSON.stringify(projected.attention));
                         else if (projected.type === 'attention.remove')

package/dist/lib/helper-versions.js

@@ -36,7 +36,7 @@
  * helper release now, off this table entirely.
  */
 export const HELPER_RELEASES = {
-    menubar: { tagPrefix: 'menubar', floor: '1.1.4' },
+    menubar: { tagPrefix: 'menubar', floor: '1.2.3' },
     'computer-mac': { tagPrefix: 'computer-mac', floor: '1.0.0' },
     // The Windows helper is a bare .exe, not an .app bundle, so it does not share
     // helper-download.ts's zip/codesign/notarize machinery -- but it has the same

package/dist/lib/menubar/install-menubar.d.ts

@@ -68,6 +68,8 @@ export declare function resolveInstalledMenubarExecutable(): string | null;
 export declare function menubarDisabledByUser(): boolean;
 /** True if the launchd plist for the menu-bar service is installed. */
 export declare function menubarServiceInstalled(): boolean;
+/** Where a downloaded copy of the floor release sits once fetched and verified. */
+export declare function cachedFloorBundlePath(): string;
 /** True when the bundle carries a signature the kernel will accept at launch. */
 export declare function codesignVerifies(appPath: string): boolean;
 /**
@@ -203,6 +205,33 @@ export declare function isMenubarStale(opts: {
     available: MenubarStamp;
     execExists: boolean;
 }): boolean;
+/**
+ * Pure decision (no I/O): should the detached background worker download the
+ * floor release into the cache so the next startup self-heal has a source?
+ *
+ * The self-heal (`installMenubarLaunchAgentOnUpgrade`) is deliberately
+ * network-free, and the npm tarball ships no bundle, so without this step an
+ * `npm i -g` Mac keeps whatever helper it has — a crashing 1.1.2, a dead 0.1.0 —
+ * until someone runs `agents menubar setup` by hand. The worker fetches only
+ * when the fetch would change something: nothing else can act as a source, the
+ * user has not opted out, and either no service exists yet (the auto-enable the
+ * bootstrap promises) or the installed helper is older than the floor.
+ */
+export declare function menubarHelperPrefetchNeeded(opts: {
+    darwin: boolean;
+    disabledByUser: boolean;
+    /** `sourceAppPath()` found a bundle (shipped or already cached). */
+    hasSource: boolean;
+    serviceInstalled: boolean;
+    stale: boolean;
+}): boolean;
+/**
+ * Background half of the release-path self-heal: download + verify the floor
+ * release into the cache when `menubarHelperPrefetchNeeded` says so. Returns
+ * the cached path, or null when nothing was fetched. Run from the detached
+ * auto-pull worker; the foreground CLI never waits on it.
+ */
+export declare function prefetchMenubarHelper(): Promise<string | null>;
 /**
  * Pure decision (no I/O): did THIS heal actually replace bundle content a live
  * process could be running stale, as opposed to a plist-only repoint?

package/dist/lib/menubar/install-menubar.js

@@ -171,6 +171,13 @@ export function menubarServiceInstalled() {
  *      binary: `import.meta.url` is a virtual `/$bunfs/` path, so the sibling
  *      candidates above can't see the on-disk bundle; recover it via the
  *      `agents` launcher symlink.
+ *   4. the verified download cache for the FLOOR release — the npm tarball ships
+ *      no bundle (PHNX-4036), so on an `npm i -g` machine this is the only
+ *      source there is. It is filled by `agents menubar setup` or by the
+ *      detached background worker (`prefetchMenubarHelper`), never here: this
+ *      resolver stays network-free so the startup self-heal stays cheap. Last
+ *      so a bundle that ships with the build always wins; keyed by the floor
+ *      version so an older cached release is never picked up.
  */
 function sourceAppPath() {
     const candidates = [];
@@ -196,8 +203,15 @@ function sourceAppPath() {
         if (fs.existsSync(p))
             return p;
     }
+    const cached = cachedFloorBundlePath();
+    if (fs.existsSync(cached))
+        return cached;
     return null;
 }
+/** Where a downloaded copy of the floor release sits once fetched and verified. */
+export function cachedFloorBundlePath() {
+    return path.join(menubarHelperCacheDir(helperFloor('menubar')), APP_BUNDLE_NAME);
+}
 /** Resolve the compiled CLI entry (dist/index.js) so the helper can exec node directly. */
 function resolveCliEntry() {
     try {
@@ -640,6 +654,41 @@ function menubarSetupStale() {
         execExists: fs.existsSync(installedExecutablePath()),
     });
 }
+/**
+ * Pure decision (no I/O): should the detached background worker download the
+ * floor release into the cache so the next startup self-heal has a source?
+ *
+ * The self-heal (`installMenubarLaunchAgentOnUpgrade`) is deliberately
+ * network-free, and the npm tarball ships no bundle, so without this step an
+ * `npm i -g` Mac keeps whatever helper it has — a crashing 1.1.2, a dead 0.1.0 —
+ * until someone runs `agents menubar setup` by hand. The worker fetches only
+ * when the fetch would change something: nothing else can act as a source, the
+ * user has not opted out, and either no service exists yet (the auto-enable the
+ * bootstrap promises) or the installed helper is older than the floor.
+ */
+export function menubarHelperPrefetchNeeded(opts) {
+    if (!opts.darwin || opts.disabledByUser || opts.hasSource)
+        return false;
+    return !opts.serviceInstalled || opts.stale;
+}
+/**
+ * Background half of the release-path self-heal: download + verify the floor
+ * release into the cache when `menubarHelperPrefetchNeeded` says so. Returns
+ * the cached path, or null when nothing was fetched. Run from the detached
+ * auto-pull worker; the foreground CLI never waits on it.
+ */
+export async function prefetchMenubarHelper() {
+    const needed = menubarHelperPrefetchNeeded({
+        darwin: onDarwin(),
+        disabledByUser: menubarDisabledByUser(),
+        hasSource: Boolean(sourceAppPath()),
+        serviceInstalled: menubarServiceInstalled(),
+        stale: menubarSetupStale(),
+    });
+    if (!needed)
+        return null;
+    return downloadMenubarHelperApp(helperFloor('menubar'));
+}
 /**
  * Pure decision (no I/O): did THIS heal actually replace bundle content a live
  * process could be running stale, as opposed to a plist-only repoint?

package/dist/lib/session/active.d.ts

@@ -55,7 +55,7 @@ export declare function attributedSetLostPids(prev: Set<number>, next: Set<numbe
 export declare function filterCachedUnattributed(sessions: ActiveSession[], attributed: Set<number>, alive: (pid: number, startedAtMs?: number) => boolean): ActiveSession[];
 type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 /** The SessionMeta fields the live-row backfill reads — the enrichment a running process cannot report. */
-export type BackfillMeta = Pick<SessionMeta, 'version' | 'account' | 'timestamp' | 'label' | 'firstUserMessage' | 'lastUserMessage' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName' | 'harness' | 'tokenCount' | 'durationMs' | 'subAgentCount'>;
+export type BackfillMeta = Pick<SessionMeta, 'version' | 'account' | 'timestamp' | 'label' | 'firstUserMessage' | 'lastUserMessage' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName' | 'harness' | 'tokenCount' | 'durationMs' | 'subAgentCount' | 'lastActivity'>;
 export declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
 export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): void;
 export declare function isRunningLiveSession(s: ActiveSession): boolean;

package/dist/lib/session/active.js

@@ -174,6 +174,13 @@ export function backfillActiveRowsFromMeta(sessions, metaById) {
             s.durationMs = m.durationMs;
         if (s.subAgentCount == null && m.subAgentCount != null)
             s.subAgentCount = m.subAgentCount;
+        // A pane kept open for days has a start time but no activity signal of its
+        // own; the index's last transcript write is what "idle 14d" is read from.
+        if (s.lastActivityMs == null && m.lastActivity) {
+            const ts = Date.parse(m.lastActivity);
+            if (!Number.isNaN(ts))
+                s.lastActivityMs = ts;
+        }
     }
 }
 function loadBackfillMetaFor(sessions) {

package/dist/lib/session/state.d.ts

@@ -56,6 +56,13 @@ export interface StructuredQuestion {
 export interface DetectedPr {
     url: string;
     number?: number;
+    /** `gh pr view` status, attached by the feed watch when it has fetched it. */
+    state?: string;
+    isDraft?: boolean;
+    reviewDecision?: string;
+    mergeable?: string;
+    /** The check rollup folded to one verdict. */
+    checks?: 'passing' | 'failing' | 'pending';
 }
 export interface DetectedWorktree {
     /** Absolute worktree path (the session cwd). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.101",
+  "version": "1.22.102",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",