@phnx-labs/agents-cli 1.22.103 → 1.22.105

package/dist/commands/run-device-picker.d.ts

@@ -0,0 +1,58 @@
+import type { AgentId } from '../lib/types.js';
+import { type Headroom } from '../lib/devices/health.js';
+/** One row of the menu, already resolved from disk. Pure data so ordering is testable. */
+export interface RunDeviceRow {
+    name: string;
+    platform?: string;
+    isLocal: boolean;
+    online: 'online' | 'offline' | 'unknown';
+    role?: string;
+    description?: string;
+    loadPercent?: number;
+    memPercent?: number;
+    headroom: Headroom;
+    statsFetchedAt?: number;
+    lastSeenAt?: string;
+    hasAccount?: boolean;
+}
+export interface RunDeviceChoice {
+    name: string;
+    value: string;
+    disabled?: boolean | string;
+}
+/**
+ * Pure. Ordering: this machine first; then online rows by headroom (idle,
+ * light, busy, loaded, unknown) then loadPercent ascending then name; then
+ * unknown-state rows; then offline rows, disabled with the last-seen time.
+ *
+ * `accountLabel` renders the ✓/– account mark on rows whose `hasAccount` the
+ * catalog answered; without it the mark is omitted (hasAccount stays on the
+ * row for the caller either way).
+ */
+export declare function buildRunDeviceChoices(rows: RunDeviceRow[], accountLabel?: string): RunDeviceChoice[];
+/**
+ * Reads devices.yaml + the cached fleet stats + configured roles + (optionally)
+ * whether `accountLabel` exists on each box. ZERO SSH, zero network, never
+ * re-probes. Returns the rows and the age of the newest stats row (undefined
+ * when no cache).
+ */
+export declare function readRunDeviceRows(opts: {
+    agent: AgentId;
+    accountLabel?: string;
+}): {
+    rows: RunDeviceRow[];
+    snapshotAgeMs?: number;
+};
+/**
+ * Interactive menu. Off a TTY: fail loud with the non-interactive forms,
+ * exactly like the account picker. Prompt message: `Select a device for this
+ * run (fleet state as of <age>):` where <age> is e.g. '2 min ago', or
+ * `Select a device for this run (no cached fleet state):`. Returns the device
+ * name, or null when the user cancels (Esc/Ctrl-C) — a cancel launches
+ * nothing. Throws when the registry has no devices at all (the message names
+ * `agents devices add`).
+ */
+export declare function pickRunDevice(opts: {
+    agent: AgentId;
+    accountLabel?: string;
+}): Promise<string | null>;

package/dist/commands/run-device-picker.js

@@ -0,0 +1,222 @@
+/**
+ * Device picker for `agents run <agent>@` (PHNX-4083).
+ *
+ * The menu behind the trailing-`@` form: every registered fleet device,
+ * rendered from files the daemon already keeps on disk — the SSH device
+ * registry, the cached fleet stats (`.fleet-stats.json`), the fleet-synced
+ * device docs (roles + descriptions), and the fleet-synced account catalog.
+ *
+ * This module NEVER probes: no SSH, no network, no re-fetch of stale rows.
+ * `loadFleetStats` re-probes rows older than 3 minutes over SSH, which is the
+ * multi-second hang a mid-run menu cannot afford; the whole point here is that
+ * the picker renders the last cached fleet state, honestly aged ("fleet state
+ * as of 2 min ago"), instead of re-deriving it live.
+ *
+ * PR 2 wires this into `agents run`; this module ships the data + menu only.
+ */
+import { select } from '@inquirer/prompts';
+import { headroom } from '../lib/devices/health.js';
+import { loadDevicesSync } from '../lib/devices/registry.js';
+import { readStatsCache } from '../lib/devices/stats-cache.js';
+import { deviceOnlineState } from '../lib/devices/reachability.js';
+import { isSelfHost } from '../lib/devices/self-host.js';
+import { normalizeHost } from '../lib/machine-id.js';
+import { localMachineId } from '../lib/origin-machine.js';
+import { listConfiguredDeviceRoles, readDeviceConfigValues } from '../lib/device-config.js';
+import { listNativeAccounts } from '../lib/account-registry.js';
+import { readSharedAccountVerdicts } from '../lib/account-catalog.js';
+import { readMeta } from '../lib/state.js';
+import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
+const HEADROOM_ORDER = {
+    idle: 0,
+    light: 1,
+    busy: 2,
+    loaded: 3,
+    unknown: 4,
+};
+function formatPercentCell(value, suffix) {
+    return value === undefined ? '—' : `${Math.round(value)}% ${suffix}`;
+}
+/** 'HH:MM' (local) from an ISO timestamp; the raw string when it does not parse. */
+function formatHourMinute(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const hh = String(d.getHours()).padStart(2, '0');
+    const mm = String(d.getMinutes()).padStart(2, '0');
+    return `${hh}:${mm}`;
+}
+/**
+ * Pure. Ordering: this machine first; then online rows by headroom (idle,
+ * light, busy, loaded, unknown) then loadPercent ascending then name; then
+ * unknown-state rows; then offline rows, disabled with the last-seen time.
+ *
+ * `accountLabel` renders the ✓/– account mark on rows whose `hasAccount` the
+ * catalog answered; without it the mark is omitted (hasAccount stays on the
+ * row for the caller either way).
+ */
+export function buildRunDeviceChoices(rows, accountLabel) {
+    const byHeadroomLoadName = (a, b) => HEADROOM_ORDER[a.headroom] - HEADROOM_ORDER[b.headroom]
+        || (a.loadPercent ?? Number.POSITIVE_INFINITY) - (b.loadPercent ?? Number.POSITIVE_INFINITY)
+        || a.name.localeCompare(b.name);
+    const local = rows.filter((row) => row.isLocal);
+    const online = rows.filter((row) => !row.isLocal && row.online === 'online').sort(byHeadroomLoadName);
+    const unknownState = rows.filter((row) => !row.isLocal && row.online === 'unknown').sort(byHeadroomLoadName);
+    const offline = rows
+        .filter((row) => !row.isLocal && row.online === 'offline')
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const ordered = [...local, ...online, ...unknownState, ...offline];
+    const nameWidth = Math.max(0, ...ordered.map((row) => row.name.length));
+    const platformWidth = Math.max(0, ...ordered.map((row) => row.platform?.length ?? 0));
+    const statusWidth = Math.max(0, ...ordered.map((row) => (row.isLocal ? 'this machine' : row.online).length));
+    const headroomWidth = Math.max(0, ...ordered.map((row) => row.headroom.length));
+    const loadWidth = Math.max(0, ...ordered.map((row) => formatPercentCell(row.loadPercent, 'load').length));
+    const memWidth = Math.max(0, ...ordered.map((row) => formatPercentCell(row.memPercent, 'mem').length));
+    return ordered.map((row) => {
+        const account = accountLabel !== undefined && row.hasAccount !== undefined
+            ? `${row.hasAccount ? '✓' : '–'} ${accountLabel}`
+            : undefined;
+        const name = [
+            row.name.padEnd(nameWidth),
+            (row.platform ?? '').padEnd(platformWidth),
+            (row.isLocal ? 'this machine' : row.online).padEnd(statusWidth),
+            row.headroom.padEnd(headroomWidth),
+            formatPercentCell(row.loadPercent, 'load').padEnd(loadWidth),
+            formatPercentCell(row.memPercent, 'mem').padEnd(memWidth),
+            row.role,
+            account,
+        ].filter((segment) => segment !== undefined && segment !== '').join(' · ');
+        return {
+            name: name.trimEnd(),
+            value: row.name,
+            ...(row.online === 'offline'
+                ? { disabled: row.lastSeenAt ? `offline since ${formatHourMinute(row.lastSeenAt)}` : 'offline' }
+                : {}),
+        };
+    });
+}
+/**
+ * The catalog's per-device answer for one account label, straight off the
+ * fleet-synced shared state (the same rows `agents view` renders): the daemon
+ * on each box publishes an auth verdict per registered account, and absence of
+ * a verdict row on a publishing box means the account is not provisioned
+ * there. A box that publishes no account rows at all (an older release) cannot
+ * be answered for — its devices stay `undefined`, never guessed.
+ */
+function resolveAccountDevices(agent, accountLabel) {
+    const account = listNativeAccounts(readMeta()).find((row) => row.agent === agent && (row.name === accountLabel || row.id === accountLabel));
+    if (!account)
+        return undefined; // the catalog has no such account — it cannot answer for any device
+    const shared = readSharedAccountVerdicts();
+    const publishing = new Set();
+    for (const rows of shared.values()) {
+        for (const row of rows)
+            publishing.add(normalizeHost(row.device));
+    }
+    const byDevice = new Map();
+    for (const row of shared.get(`${agent}:${account.id}`) ?? []) {
+        byDevice.set(normalizeHost(row.device), row.verdict !== 'missing');
+    }
+    return { byDevice, publishing };
+}
+/**
+ * Reads devices.yaml + the cached fleet stats + configured roles + (optionally)
+ * whether `accountLabel` exists on each box. ZERO SSH, zero network, never
+ * re-probes. Returns the rows and the age of the newest stats row (undefined
+ * when no cache).
+ */
+export function readRunDeviceRows(opts) {
+    const registry = loadDevicesSync();
+    const statsCache = readStatsCache();
+    const names = Object.keys(registry);
+    const roles = listConfiguredDeviceRoles(names);
+    const local = normalizeHost(localMachineId());
+    const accountDevices = opts.accountLabel
+        ? resolveAccountDevices(opts.agent, opts.accountLabel)
+        : undefined;
+    let newestFetchedAt;
+    for (const stats of Object.values(statsCache)) {
+        if (newestFetchedAt === undefined || stats.fetchedAt > newestFetchedAt)
+            newestFetchedAt = stats.fetchedAt;
+    }
+    const snapshotAgeMs = newestFetchedAt === undefined ? undefined : Math.max(0, Date.now() - newestFetchedAt);
+    const rows = names.map((name) => {
+        const profile = registry[name];
+        const stats = statsCache[name];
+        const online = deviceOnlineState(profile, stats);
+        const config = readDeviceConfigValues(name);
+        const description = typeof config.description === 'string' ? config.description : undefined;
+        const host = normalizeHost(name);
+        return {
+            name,
+            platform: profile.platform === 'unknown' ? undefined : profile.platform,
+            isLocal: isSelfHost(name) || host === local,
+            online,
+            role: roles[name],
+            description,
+            loadPercent: stats?.loadPercent,
+            memPercent: stats?.memPercent,
+            headroom: headroom(stats),
+            statsFetchedAt: stats?.fetchedAt,
+            lastSeenAt: online === 'offline'
+                ? profile.reachability?.checkedAt ?? profile.tailscale?.lastSeen
+                : undefined,
+            hasAccount: accountDevices
+                ? accountDevices.publishing.has(host)
+                    ? accountDevices.byDevice.get(host) ?? false
+                    : undefined
+                : undefined,
+        };
+    });
+    return { rows, snapshotAgeMs };
+}
+/** Human age for the prompt's "fleet state as of …" note: 'just now', '2 min ago', '3 h ago', … */
+function formatSnapshotAge(ageMs) {
+    if (ageMs < 45_000)
+        return 'just now';
+    if (ageMs < 90_000)
+        return '1 min ago';
+    if (ageMs < 3_600_000)
+        return `${Math.round(ageMs / 60_000)} min ago`;
+    if (ageMs < 86_400_000)
+        return `${Math.round(ageMs / 3_600_000)} h ago`;
+    return `${Math.round(ageMs / 86_400_000)} d ago`;
+}
+/**
+ * Interactive menu. Off a TTY: fail loud with the non-interactive forms,
+ * exactly like the account picker. Prompt message: `Select a device for this
+ * run (fleet state as of <age>):` where <age> is e.g. '2 min ago', or
+ * `Select a device for this run (no cached fleet state):`. Returns the device
+ * name, or null when the user cancels (Esc/Ctrl-C) — a cancel launches
+ * nothing. Throws when the registry has no devices at all (the message names
+ * `agents devices add`).
+ */
+export async function pickRunDevice(opts) {
+    // An empty registry is wrong on every terminal, so it is judged before the
+    // TTY gate: "register a device" is the useful answer, not "need a TTY".
+    const { rows, snapshotAgeMs } = readRunDeviceRows(opts);
+    if (rows.length === 0) {
+        throw new Error('No devices are registered. Add one with: agents devices add <name>');
+    }
+    if (!isInteractiveTerminal()) {
+        requireInteractiveSelection('Selecting a device', [
+            `agents run ${opts.agent} --device <name>`,
+            'agents devices',
+        ]);
+    }
+    const choices = buildRunDeviceChoices(rows, opts.accountLabel);
+    try {
+        return await select({
+            message: snapshotAgeMs !== undefined
+                ? `Select a device for this run (fleet state as of ${formatSnapshotAge(snapshotAgeMs)}):`
+                : 'Select a device for this run (no cached fleet state):',
+            choices,
+            loop: false,
+        });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return null;
+        throw err;
+    }
+}

package/dist/commands/setup-computer.js

@@ -9,9 +9,10 @@
  * Idempotent: re-running re-installs the current helper and re-checks trust.
  */
 import os from 'node:os';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import chalk from 'chalk';
 import { installComputerHelperMacLocal, activateComputerHelperMacLocal, probeComputerTrust, } from './computer.js';
+import { resolveComputerBin, ComputerClientError } from '../lib/computer-client.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 const ACCESSIBILITY_PANE = 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility';
 const SCREEN_PANE = 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture';
@@ -36,6 +37,24 @@ export async function runComputerWizard() {
         console.log(chalk.dim('On Windows, provision a remote host from a Mac/Linux box instead: `agents computer setup --device <device>`.'));
         return false;
     }
+    try {
+        resolveComputerBin();
+    }
+    catch (error) {
+        if (!(error instanceof ComputerClientError) || error.code !== 'COMPUTER_BIN_MISSING')
+            throw error;
+        console.log('Installing @phnx-labs/computer-cli@0.1.2…');
+        const installed = spawnSync('npm', ['install', '-g', '@phnx-labs/computer-cli@0.1.2'], { stdio: 'inherit' });
+        if (installed.status !== 0)
+            return false;
+        try {
+            resolveComputerBin();
+        }
+        catch {
+            console.error('Computer CLI installation did not produce an executable on PATH.');
+            return false;
+        }
+    }
     // 1. Download + verify + install the signed, notarized helper.
     console.log(chalk.bold('Installing the Agents Computer helper...'));
     try {

package/dist/commands/setup-secrets.d.ts

@@ -8,8 +8,8 @@
  * `npm i -g`. Users do not set extra env vars.
  */
 import type { Command } from 'commander';
-export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli@0.1.2";
-export declare const INSTALL_HINT = "agents clis install secrets   # or: npm i -g @phnx-labs/secrets-cli@0.1.2";
+export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli@0.1.4";
+export declare const INSTALL_HINT = "agents clis install secrets   # or: npm i -g @phnx-labs/secrets-cli@0.1.4";
 export declare function setupSecretsPrefsPath(): string;
 /** True when the standalone `secrets` executable resolves ($SECRETS_BIN or PATH). */
 export declare function isSecretsCliInstalled(): boolean;

package/dist/commands/setup-secrets.js

@@ -14,7 +14,7 @@ import { spawnSync } from 'node:child_process';
 import { getHistoryDir } from '../lib/state.js';
 import { resolveSecretsBin, invocation, SecretsClientError, _resetSecretsClientForTest } from '../lib/secrets-client.js';
 import { installCli, resolveCliManifest } from '../lib/cli-resources.js';
-export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli@0.1.2';
+export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli@0.1.4';
 export const INSTALL_HINT = `agents clis install secrets   # or: npm i -g ${SECRETS_CLI_PACKAGE}`;
 export function setupSecretsPrefsPath() {
     return path.join(getHistoryDir(), 'setup', 'secrets.json');

package/dist/commands/view.js

@@ -31,7 +31,7 @@ import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins/plugins.js';
 import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts, readMeta } from '../lib/state.js';
 import { findNativeAccountByIdentity } from '../lib/account-registry.js';
-import { accountListJson, loadAccountCatalog, renderAccountRows, secretsUnavailableNote } from '../lib/account-catalog.js';
+import { ACCOUNT_LISTING_LEGEND, accountListJson, loadAccountCatalog, renderAccountRows, secretsUnavailableNote } from '../lib/account-catalog.js';
 import { addSupported } from '../lib/accounts/add.js';
 import { readInstallation } from '../lib/installations/store.js';
 import { isAutoUpdateEnabledForAgent } from '../lib/installations/update-policy.js';
@@ -557,12 +557,10 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
         }
         if (filterAgentId) {
             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'));
         }
+        // Overview renders the same account rows with footer:false, so both paths
+        // need the legend the shared renderer would otherwise have printed.
+        console.log(chalk.gray(`  ${ACCOUNT_LISTING_LEGEND}\n`));
     }
     if (versionManaged.length > 0 && viewOpts?.versions) {
         // Calculate column widths across all agents for alignment

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

@@ -201,8 +201,29 @@ 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;
+/**
+ * A state worth an operator's attention, rendered at the END of the row.
+ * `live`, `ready`, `unverified` and `per-device` are the ordinary cases: they
+ * were on every row of the old table and pushed it past the terminal width
+ * without telling anyone anything. They stay in `accounts list --fleet`,
+ * `accounts view <name>` and `--json`.
+ */
+export declare function verdictNote(verdict: AccountVerdict): string | null;
+/**
+ * Device coverage, but only when it SPLITS the fleet: some boxes can use the
+ * account and some cannot. Full coverage is the ordinary case, and "none of
+ * them" is already exactly what the row's state note says, so both render
+ * nothing — `accounts list --fleet` is the per-device table.
+ */
+export declare function coverageNote(row: NativeAccountCatalogRow, localDevice: string): string | null;
 export declare const OVERVIEW_MAX_USAGE_WINDOWS = 2;
+/**
+ * The one line under an account listing. It explains the two marks a row can
+ * carry and names where the columns the listing no longer prints — identity,
+ * per-device state — still live. Shared with `agents view` so the two surfaces
+ * cannot drift.
+ */
+export declare const ACCOUNT_LISTING_LEGEND = "* stale usage \u00B7 a healthy account carries no state \u00B7 identity + per-box state: agents accounts list --fleet";
 /** Shared text renderer used by both `accounts list` and account-first `view`. */
 export declare function renderAccountRows(rows: NativeAccountCatalogRow[], opts: {
     heading?: boolean;

package/dist/lib/account-catalog.js

@@ -367,35 +367,55 @@ export function accountListJson(native, providers = [], harness) {
         ],
     };
 }
-function verdictText(verdict) {
+/**
+ * A state worth an operator's attention, rendered at the END of the row.
+ * `live`, `ready`, `unverified` and `per-device` are the ordinary cases: they
+ * were on every row of the old table and pushed it past the terminal width
+ * without telling anyone anything. They stay in `accounts list --fleet`,
+ * `accounts view <name>` and `--json`.
+ */
+export function verdictNote(verdict) {
     if (verdict === 'rate_limited')
-        return 'LIMITED';
-    return verdict.toUpperCase();
+        return chalk.yellow('rate-limited');
+    if (verdict === 'expired' || verdict === 'revoked' || verdict === 'missing') {
+        return chalk.red(verdict);
+    }
+    return null;
 }
-export function whereText(row, localDevice) {
+/**
+ * Device coverage, but only when it SPLITS the fleet: some boxes can use the
+ * account and some cannot. Full coverage is the ordinary case, and "none of
+ * them" is already exactly what the row's state note says, so both render
+ * nothing — `accounts list --fleet` is the per-device table.
+ */
+export function coverageNote(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.
+    // observation is this box — that is a gap in what we can see, not a gap in
+    // provisioning, so it is not an alarm.
     if (names.length === 1 && names[0] === localDevice)
-        return 'this box';
-    // 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
+        return null;
+    // Per-device accounts are provisioned per box; name the boxes it is NOT on
+    // rather than a usable/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';
+        const absent = row.devices.filter((device) => device.verdict === 'missing').map((device) => device.device);
+        return absent.length > 0 && absent.length < row.devices.length ? `not on ${absent.join(', ')}` : null;
     }
     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`;
+    if (usable === 0 || usable === provisioned)
+        return null;
+    return `usable on ${usable} of ${provisioned} boxes`;
 }
 export const OVERVIEW_MAX_USAGE_WINDOWS = 2;
+/**
+ * The one line under an account listing. It explains the two marks a row can
+ * carry and names where the columns the listing no longer prints — identity,
+ * per-device state — still live. Shared with `agents view` so the two surfaces
+ * cannot drift.
+ */
+export const ACCOUNT_LISTING_LEGEND = '* stale usage · a healthy account carries no state · identity + per-box state: agents accounts list --fleet';
 function usageText(row, maxWindows) {
     if (row.usageSnapshot) {
         const usageInfo = { snapshot: row.usageSnapshot, error: row.usageError ?? null };
@@ -411,13 +431,35 @@ function usageText(row, maxWindows) {
     const percent = `${row.usage.usedPercent}%${row.usage.stale ? '*' : ''}`;
     return `${renderBar(row.usage.usedPercent, LISTING_USAGE_BAR_LEN)} ${percent}`;
 }
+/**
+ * True only when the USAGE cell is certain to print a throttle marker, so the
+ * `rate-limited` note would say the same thing twice. Mirrors `usageText`
+ * branch for branch: with a snapshot, `formatUsageSummary` appends
+ * 'out of credits' or 'session-limited (…)' exactly for these `unavailable`
+ * reasons; without one, `usageText` prints 'limited' or 'no credits'. A verdict
+ * thrown by a maxed WINDOW is deliberately NOT here: the overview caps the cell
+ * at `OVERVIEW_MAX_USAGE_WINDOWS`, so the window that tripped it can be hidden
+ * behind the `+N` count with no color at all, and the note is the only signal.
+ */
+function usageCellNamesThrottle(row) {
+    if (row.usageSnapshot) {
+        const unavailable = row.usageSnapshot.unavailable;
+        return unavailable?.reason === 'out_of_credits'
+            || (unavailable?.reason === 'session_limit' && !!unavailable.resetsAt);
+    }
+    return row.usage?.status === 'out_of_credits'
+        || (row.usage?.status === 'rate_limited' && (row.usage.usedPercent === null || row.usage.usedPercent === undefined));
+}
 function nativeLine(row, localDevice, maxWindows) {
     return {
-        name: row.name ?? 'unnamed',
-        identityLabel: row.identityLabel,
-        verdict: row.verdict,
-        where: whereText(row, localDevice),
-        fix: row.fix,
+        // A discovered login nobody has named is still identified by what it is:
+        // the row no longer carries an IDENTITY column, so the identity IS the name.
+        name: row.name ?? row.identityLabel,
+        notes: [
+            usageCellNamesThrottle(row) && row.verdict === 'rate_limited' ? null : verdictNote(row.verdict),
+            coverageNote(row, localDevice),
+            row.fix ? chalk.gray(`fix: ${row.fix}`) : null,
+        ].filter((note) => !!note),
         usage: usageText(row, maxWindows),
         isDefault: row.isDefault,
     };
@@ -425,32 +467,27 @@ function nativeLine(row, localDevice, maxWindows) {
 function providerLine(row, harness) {
     return {
         name: row.name,
-        identityLabel: row.identityLabel,
-        verdict: row.verdict,
-        where: '—',
-        fix: row.fix,
+        notes: [
+            verdictNote(row.verdict),
+            row.fix ? chalk.gray(`fix: ${row.fix}`) : null,
+        ].filter((note) => !!note),
         usage: '',
         isDefault: harness ? row.defaultFor.includes(harness) : false,
     };
 }
-function formatListingLine(line, nameW, identityW, stateW, whereW, usageW) {
+function formatListingLine(line, nameW, usageW) {
     const marker = line.isDefault ? '*' : ' ';
-    const fix = line.fix ? `fix: ${line.fix}` : '';
     return (`  ${chalk.green(marker)} ${chalk.cyan(line.name.padEnd(nameW))}  `
-        + `${line.identityLabel.padEnd(identityW)}  `
-        + `${verdictText(line.verdict).padEnd(stateW)}  `
-        + `${line.where.padEnd(whereW)}  `
         + `${padToWidth(line.usage, usageW)}  `
-        + `${fix ? chalk.gray(fix) : ''}`).trimEnd();
+        + line.notes.join(chalk.gray(' · '))).trimEnd();
 }
 function pushGroup(out, title, lines, widths, harnessHeadings) {
     if (lines.length === 0)
         return;
     if (harnessHeadings)
         out.push(chalk.bold(title));
-    out.push(chalk.gray(`  ${'ACCOUNT'.padEnd(widths.nameW + 2)}${'IDENTITY'.padEnd(widths.identityW + 2)}${'STATE'.padEnd(widths.stateW + 2)}${'WHERE'.padEnd(widths.whereW + 2)}${'USAGE'.padEnd(widths.usageW + 2)}FIX`));
     for (const line of lines) {
-        out.push(formatListingLine(line, widths.nameW, widths.identityW, widths.stateW, widths.whereW, widths.usageW));
+        out.push(formatListingLine(line, widths.nameW, widths.usageW));
     }
     out.push('');
 }
@@ -501,9 +538,6 @@ export function renderAccountRows(rows, opts) {
         const allLines = [...grouped.values()].flat().concat(orphans);
         const widths = {
             nameW: Math.max(7, ...allLines.map((line) => line.name.length)),
-            identityW: Math.max(8, ...allLines.map((line) => line.identityLabel.length)),
-            stateW: Math.max(5, ...allLines.map((line) => verdictText(line.verdict).length)),
-            whereW: Math.max(5, ...allLines.map((line) => line.where.length)),
             usageW: Math.max(5, ...allLines.map((line) => stringWidth(line.usage))),
         };
         for (const [harness, lines] of grouped) {
@@ -519,7 +553,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'));
+        out.push(chalk.gray(ACCOUNT_LISTING_LEGEND));
     }
     return out.join('\n').trimEnd();
 }

package/dist/lib/accounting/usage.js

@@ -624,12 +624,13 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         parts.push(chalk.gray(plan.padEnd(planWidth)));
     }
     if (snapshot) {
-        if (snapshot.unavailable?.reason === 'out_of_credits') {
-            parts.push(chalk.red('out of credits'));
-        }
-        else if (snapshot.unavailable?.reason === 'session_limit' && snapshot.unavailable.resetsAt) {
-            parts.push(chalk.yellow(`session-limited (${formatResetHint(snapshot.unavailable.resetsAt)})`));
-        }
+        // A blocking marker renders AFTER the bars: leading it pushed every gauge
+        // out of its column, so one throttled account misaligned the whole table.
+        const blocked = snapshot.unavailable?.reason === 'out_of_credits'
+            ? chalk.red('out of credits')
+            : snapshot.unavailable?.reason === 'session_limit' && snapshot.unavailable.resetsAt
+                ? chalk.yellow(`session-limited (${formatResetHint(snapshot.unavailable.resetsAt)})`)
+                : null;
         // Compact rows show BLOCKING windows — the same set
         // deriveUsageStatusFromSnapshot uses for the rate-limited badge — so an
         // account throttled by its month window (Droid meters on 5h/week/month)
@@ -698,6 +699,8 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         else if (opts?.unverified) {
             parts.push(chalk.yellow('unverified'));
         }
+        if (blocked)
+            parts.push(blocked);
     }
     else if (opts?.headless) {
         // No bars at all: still name the scope gap so "usage pending" is not
@@ -2357,7 +2360,7 @@ function formatAgeShort(diffMs) {
  * Staleness suffix for a last-known window the freshness gate dropped. A window
  * whose reset/period boundary passed while the sample itself is still inside its
  * `windowMinutes` rolled OVER — the number describes a period that is done, so
- * name it ("period ended 1h ago", e.g. Grok's weekly billing period). A window
+ * name it ("period ended 1h", e.g. Grok's weekly billing period). A window
  * that aged past its own `windowMinutes` (Claude's 5h session read never
  * refreshed in time) is a stale sample of a still-rolling window, so report the
  * capture age ("6h old"). Falls back to the reset age, then a bare "stale".
@@ -2368,25 +2371,26 @@ function formatStaleWindowSuffix(window, capturedAt, now) {
         window.windowMinutes !== null &&
         capturedAt.getTime() + window.windowMinutes * 60 * 1000 <= now.getTime();
     if (resetPassed && !captureExpired) {
-        return `stale (period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())} ago)`;
+        return `period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())}`;
     }
     if (capturedAt)
         return `${formatAgeShort(now.getTime() - capturedAt.getTime())} old`;
     if (resetPassed)
-        return `stale (period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())} ago)`;
+        return `period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())}`;
     return 'stale';
 }
 /**
- * Render a dropped-but-last-known window as "S: ▍░░░░ 30% · 6h old": the gauge
- * and percentage exactly as a live bar, then a dim staleness suffix so the
- * number is always visible and unmistakably not current. VIEW-ONLY — these
- * windows are never in `snapshot.windows`, so routing never sees them.
+ * Render a dropped-but-last-known window as "S: ▍░░░░ 30%* (6h old)": the gauge
+ * and percentage exactly as a live bar, then the `*` stale marker the listing
+ * legend explains and a dim age, so the number is always visible and
+ * unmistakably not current. VIEW-ONLY — these windows are never in
+ * `snapshot.windows`, so routing never sees them.
  */
 function renderStaleUsageWindow(window, capturedAt, shortLabel, now) {
     const bar = renderCompactUsageBar(window.usedPercent);
     const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
     const suffix = formatStaleWindowSuffix(window, capturedAt, now);
-    return `${chalk.gray(`${shortLabel}:`)} ${bar} ${pct} ${chalk.dim(`· ${suffix}`)}`;
+    return `${chalk.gray(`${shortLabel}:`)} ${bar} ${pct}${chalk.dim('*')} ${chalk.dim(`(${suffix})`)}`;
 }
 /** Format a reset timestamp as a human-readable relative or absolute time. */
 function formatResetAt(date) {

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

@@ -24,6 +24,7 @@ export declare const GEMINI_HOOKS_MIN_VERSION = "0.26.0";
  * section, even though the user had nothing to import.
  */
 interface NativeBinaryResolutionOptions {
+    accept?: (candidate: string) => boolean;
     shimsDir?: string;
     historyDir?: string;
 }