@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/teams/parsers.js

@@ -2,9 +2,9 @@
  * Agent event stream parsers.
  *
  * Normalizes the heterogeneous JSON event formats emitted by each agent CLI
- * (Claude, Codex, Gemini, Cursor, OpenCode) into a unified event schema
- * with consistent types: init, message, tool_use, bash, file_read, file_write,
- * file_create, file_delete, result, error, and others.
+ * (Claude, Codex, Gemini, Cursor, OpenCode, Grok, Antigravity) into a unified
+ * event schema with consistent types: init, message, tool_use, bash,
+ * file_read, file_write, file_create, file_delete, result, error, and others.
  */
 import { extractFileOpsFromBash } from './file_ops.js';
 const claudeToolUseMap = new Map();
@@ -25,6 +25,12 @@ export function normalizeEvents(agentType, raw) {
     else if (agentType === 'opencode') {
         return normalizeOpencode(raw);
     }
+    else if (agentType === 'grok') {
+        return normalizeGrok(raw);
+    }
+    else if (agentType === 'antigravity') {
+        return normalizeAntigravity(raw);
+    }
     const timestamp = new Date().toISOString();
     return [{
             type: raw.type || 'unknown',
@@ -824,6 +830,150 @@ function normalizeOpencode(raw) {
             timestamp: timestamp,
         }];
 }
+// --- Grok parsing ---
+// Grok's streaming-json mode emits one JSON object per token, with three event
+// types:
+//   {"type":"thought","data":"<chunk>"}   — reasoning tokens (many, small)
+//   {"type":"text","data":"<chunk>"}      — visible response tokens (many, small)
+//   {"type":"end","stopReason":"EndTurn","sessionId":"<uuid>","requestId":"<uuid>"}
+//
+// Tool calls are NOT exposed as separate events in this format; they appear
+// inside the `thought` text as XML-like markup. Extracting them reliably would
+// require running a streaming XML/markup parser over concatenated thought
+// chunks, which is out of scope for v1. The teams summary will show grok
+// teammates' bash/file ops as empty — known limitation, fixable later by
+// switching to grok's `agent` subcommand (richer event stream) once stable.
+//
+// Tokens are emitted as `message` events with `complete: false` so the
+// summarizer can concatenate them into a final message; `thinking` events are
+// already collapsed by the summarizer's groupAndFlattenEvents pathway.
+function normalizeGrok(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return [{
+                type: 'unknown',
+                agent: 'grok',
+                raw: raw,
+                timestamp: new Date().toISOString(),
+            }];
+    }
+    const eventType = raw.type || 'unknown';
+    const timestamp = new Date().toISOString();
+    if (eventType === 'thought') {
+        const data = typeof raw.data === 'string' ? raw.data : '';
+        if (!data)
+            return [];
+        return [{
+                type: 'thinking',
+                agent: 'grok',
+                content: data,
+                timestamp: timestamp,
+            }];
+    }
+    if (eventType === 'text') {
+        const data = typeof raw.data === 'string' ? raw.data : '';
+        if (!data)
+            return [];
+        return [{
+                type: 'message',
+                agent: 'grok',
+                content: data,
+                complete: false,
+                timestamp: timestamp,
+            }];
+    }
+    if (eventType === 'end') {
+        const stopReason = typeof raw.stopReason === 'string' ? raw.stopReason : '';
+        const status = stopReason === 'EndTurn' || stopReason === 'StopSequence' || stopReason === ''
+            ? 'success'
+            : 'error';
+        return [{
+                type: 'result',
+                agent: 'grok',
+                status: status,
+                stop_reason: stopReason || null,
+                session_id: typeof raw.sessionId === 'string' ? raw.sessionId : null,
+                timestamp: timestamp,
+            }];
+    }
+    return [{
+            type: eventType,
+            agent: 'grok',
+            raw: raw,
+            timestamp: timestamp,
+        }];
+}
+// --- Antigravity parsing ---
+// Intentionally conservative. Antigravity's `agy` binary advertises an
+// `--output-format json` flag in its docs, but the released binary errors with
+// `flags provided but not defined: -output-format` (tracked upstream as
+// google-antigravity/antigravity-cli#7, open as of May 2026). Until JSON
+// streaming stabilizes, this parser treats agy output as a black box:
+//   - non-object input (a plain string line, or null/number) becomes a single
+//     `message` event with the full content and complete:true so the
+//     summarizer captures it without token-level concatenation
+//   - objects with a recognizable `type` field (e.g. `init`, `message`,
+//     `result`) get a minimal shape-preserving normalization
+//   - everything else falls through to the generic unknown-event shape
+// Once agy ships stable streaming JSON, replace this with proper event
+// mapping mirroring normalizeGrok / normalizeClaude.
+function normalizeAntigravity(raw) {
+    const timestamp = new Date().toISOString();
+    if (typeof raw === 'string') {
+        if (!raw)
+            return [];
+        return [{
+                type: 'message',
+                agent: 'antigravity',
+                content: raw,
+                complete: true,
+                timestamp: timestamp,
+            }];
+    }
+    if (!raw || typeof raw !== 'object') {
+        return [{
+                type: 'unknown',
+                agent: 'antigravity',
+                raw: raw,
+                timestamp: timestamp,
+            }];
+    }
+    const eventType = raw.type || 'unknown';
+    if (eventType === 'init') {
+        return [{
+                type: 'init',
+                agent: 'antigravity',
+                session_id: typeof raw.sessionId === 'string' ? raw.sessionId : null,
+                timestamp: timestamp,
+            }];
+    }
+    if (eventType === 'message') {
+        const content = typeof raw.content === 'string' ? raw.content : '';
+        if (!content)
+            return [];
+        return [{
+                type: 'message',
+                agent: 'antigravity',
+                content: content,
+                complete: raw.complete !== false,
+                timestamp: timestamp,
+            }];
+    }
+    if (eventType === 'result') {
+        return [{
+                type: 'result',
+                agent: 'antigravity',
+                status: raw.status === 'error' ? 'error' : 'success',
+                session_id: typeof raw.sessionId === 'string' ? raw.sessionId : null,
+                timestamp: timestamp,
+            }];
+    }
+    return [{
+            type: eventType,
+            agent: 'antigravity',
+            raw: raw,
+            timestamp: timestamp,
+        }];
+}
 /** Parse a single JSONL line into normalized events. Returns null if the line is not valid JSON. */
 export function parseEvent(agentType, line) {
     try {

package/dist/lib/teams/summarizer.js

@@ -159,11 +159,18 @@ export function groupAndFlattenEvents(events) {
         if (eventType === 'message' || eventType === 'thinking') {
             let count = 1;
             let combinedContent = event.content || '';
+            // Streaming token events (complete:false) get concatenated without a
+            // separator so tokens reassemble into readable prose. Whole-turn events
+            // get joined with newlines so distinct turns/thoughts stay separated.
+            const isStreaming = event.complete === false;
             let j = i + 1;
             while (j < events.length && events[j].type === eventType) {
                 count++;
                 if (events[j].content) {
-                    combinedContent += (combinedContent ? '\n' : '') + events[j].content;
+                    const sep = isStreaming || events[j].complete === false
+                        ? ''
+                        : (combinedContent ? '\n' : '');
+                    combinedContent += sep + events[j].content;
                 }
                 j++;
             }
@@ -405,7 +412,16 @@ export function summarizeEvents(agentId, agentType, status, events, duration = n
         else if (eventType === 'message') {
             const content = event.content || '';
             if (content) {
-                summary.finalMessage = content;
+                // Streaming token-by-token messages (e.g., grok) arrive as many small
+                // `message` events with complete:false; concatenate them so the final
+                // turn reads as one message. Whole-turn messages (claude, codex,
+                // gemini) keep their complete:true semantics — last one wins.
+                if (event.complete === false) {
+                    summary.finalMessage = (summary.finalMessage || '') + content;
+                }
+                else {
+                    summary.finalMessage = content;
+                }
             }
         }
         else if (eventType === 'error') {

package/dist/lib/teams/worktree.js

@@ -8,7 +8,9 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs/promises';
 import * as path from 'path';
+import { safeJoin } from '../paths.js';
 const execFileAsync = promisify(execFile);
+const WORKTREE_NAME_RE = /^[A-Za-z0-9_-]+$/;
 export async function isGitRepo(dir) {
     try {
         await execFileAsync('git', ['rev-parse', '--git-dir'], { cwd: dir });
@@ -42,8 +44,11 @@ export async function hasUncommittedChanges(worktreePath) {
  * @returns The absolute path to the created worktree
  */
 export async function createWorktree(repoDir, worktreeName) {
+    if (!WORKTREE_NAME_RE.test(worktreeName)) {
+        throw new Error(`Invalid worktree name: ${worktreeName}`);
+    }
     const gitRoot = await getGitRoot(repoDir);
-    const worktreePath = path.join(gitRoot, '.agents', 'worktrees', worktreeName);
+    const worktreePath = safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
     const branchName = `agents/${worktreeName}`;
     await fs.mkdir(path.dirname(worktreePath), { recursive: true });
     await execFileAsync('git', ['worktree', 'add', '-b', branchName, worktreePath, 'HEAD'], {
@@ -59,8 +64,11 @@ export async function createWorktree(repoDir, worktreeName) {
  * @param deleteBranch - Whether to delete the associated branch
  */
 export async function removeWorktree(repoDir, worktreeName, deleteBranch = true) {
+    if (!WORKTREE_NAME_RE.test(worktreeName)) {
+        throw new Error(`Invalid worktree name: ${worktreeName}`);
+    }
     const gitRoot = await getGitRoot(repoDir);
-    const worktreePath = path.join(gitRoot, '.agents', 'worktrees', worktreeName);
+    const worktreePath = safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
     const branchName = `agents/${worktreeName}`;
     try {
         await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: gitRoot });
@@ -86,7 +94,10 @@ export async function removeWorktree(repoDir, worktreeName, deleteBranch = true)
  * Get the worktree path for a given name.
  */
 export function getWorktreePath(gitRoot, worktreeName) {
-    return path.join(gitRoot, '.agents', 'worktrees', worktreeName);
+    if (!WORKTREE_NAME_RE.test(worktreeName)) {
+        throw new Error(`Invalid worktree name: ${worktreeName}`);
+    }
+    return safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
 }
 /**
  * Get the branch name for a worktree.

package/dist/lib/types.d.ts

@@ -40,6 +40,12 @@ export interface AgentConfig {
         skills: Capability;
         commands: Capability;
         plugins: Capability;
+        /**
+         * Permission modes this agent natively supports. Modes outside this set
+         * are gated by buildExecCommand: `auto` silently degrades to `edit`,
+         * `skip` errors with a clear message naming the supported modes.
+         */
+        modes: Mode[];
         /**
          * Whether the agent natively resolves `@path/to/file` imports inside its
          * rules file at session start. If false, agents-cli must pre-compile the
@@ -60,6 +66,19 @@ export type Capability = boolean | {
 };
 /** Names of every gateable capability on AgentConfig. */
 export type CapabilityName = 'hooks' | 'mcp' | 'allowlist' | 'skills' | 'commands' | 'plugins';
+/**
+ * Permission modes controlling agent autonomy.
+ *   plan  read-only investigation; no writes, no shell side-effects
+ *   edit  may edit files; prompts for shell/risky operations
+ *   auto  smart classifier auto-approves safe operations, prompts for risky ones
+ *   skip  bypasses every permission prompt (dangerously-skip-permissions)
+ *
+ * `full` is accepted as a permanent silent alias for `skip` via normalizeMode().
+ * Per-agent support is declared on AgentConfig.capabilities.modes.
+ */
+export type Mode = 'plan' | 'edit' | 'auto' | 'skip';
+/** Every canonical mode in declaration order. Useful for iteration / validation. */
+export declare const ALL_MODES: readonly Mode[];
 /** Reason a capability check failed. */
 export type CapabilityFailReason = 'unsupported' | 'too_old' | 'too_new';
 /** Result of `supports(agent, cap, version?)`. */
@@ -100,6 +119,36 @@ export interface HookMatches {
     cwd_includes?: string | string[];
     project_has?: string;
 }
+/**
+ * Cache scoping. Determines which cache file a hook invocation reads/writes:
+ *  - `global`      one file per hook, shared across cwds/sessions. Right for
+ *                  SessionStart hooks pulling org-wide context (Linear sprint).
+ *  - `per-cwd`     keyed on the working directory the hook fires from.
+ *  - `per-session` keyed on the agent's session_id (read from stdin JSON).
+ *  - `per-project` keyed on the nearest git repo root above cwd.
+ */
+export type HookCacheKey = 'global' | 'per-cwd' | 'per-session' | 'per-project';
+/** Prefetch strategy when the cache is stale. */
+export type HookCachePrefetch = 'none' | 'background';
+/**
+ * Full hook cache config. Authors usually use the shorthand string form
+ * (`HookCache`) below. Shorthand examples in hooks.yaml:
+ *
+ *   cache: 5m          # → { ttl: 300, key: 'global', prefetch: 'none' }
+ *   cache: 5m-bg       # → { ttl: 300, key: 'global', prefetch: 'background' }
+ *   cache:             # full form
+ *     ttl: 1h
+ *     key: per-cwd
+ *     prefetch: background
+ */
+export interface HookCacheConfig {
+    /** TTL in seconds or duration string ("30s", "5m", "1h"). */
+    ttl: number | string;
+    key?: HookCacheKey;
+    prefetch?: HookCachePrefetch;
+}
+/** Cache shorthand: duration string, optionally suffixed `-bg` for background prefetch. */
+export type HookCache = string | HookCacheConfig;
 /** Hook entry as declared in a package manifest (agents.yaml). */
 export interface ManifestHook {
     script: string;
@@ -114,6 +163,13 @@ export interface ManifestHook {
     override?: boolean;
     /** Optional pre-filter predicates evaluated before invoking the script. */
     matches?: HookMatches;
+    /**
+     * Opt-in caching. When set, the registrar generates a per-hook shim
+     * under the hook shims dir that handles cache lookup, stale-while-revalidate,
+     * and per-invocation timing/logging, then registers that shim with the agent
+     * instead of the raw script. The underlying script is unchanged.
+     */
+    cache?: HookCache;
 }
 /** Lightweight hook descriptor used in resource listings. */
 export interface HookResourceEntry {
@@ -203,9 +259,12 @@ export interface RegistryConfig {
 /** Built-in registry endpoints shipped with agents-cli. */
 export declare const DEFAULT_REGISTRIES: Record<RegistryType, Record<string, RegistryConfig>>;
 /**
- * Registries that ship pre-seeded into new users' agents.yaml once, but are
- * not "defaults" — after seeding they behave like any user-added registry
- * (listable, disable-able, removable, and gone for good once removed).
+ * Third-party registries pre-seeded on first install for discoverability.
+ *
+ * These ship into new users' agents.yaml once, but are not "defaults" — after
+ * seeding they behave like any user-added registry (listable, disable-able,
+ * removable). Removed users can `agents registry remove <name>` to opt out;
+ * once removed they don't come back.
  */
 export declare const SEEDED_REGISTRIES: Record<RegistryType, Record<string, RegistryConfig>>;
 /** A single installable package within an MCP server entry. */
@@ -466,7 +525,7 @@ export interface BrowserProfileConfig {
     };
     /** Directory holding source-side JSONL logs (e.g. ~/.rush/logs). */
     logDir?: string;
-    /** Optional SSH host where logDir lives, e.g. "user@mac-mini". */
+    /** Optional SSH host where logDir lives, e.g. "user@remote-host". */
     logHost?: string;
 }
 /** Options controlling which agents and resources are synced during `agents pull` / `agents use`. */

package/dist/lib/types.js

@@ -5,6 +5,8 @@
  * configuration schemas, resource tracking, registry types, and permission
  * formats for each supported agent.
  */
+/** Every canonical mode in declaration order. Useful for iteration / validation. */
+export const ALL_MODES = ['plan', 'edit', 'auto', 'skip'];
 /** Canonical system repo cloned into ~/.agents-system/. */
 export const DEFAULT_SYSTEM_REPO = 'gh:phnx-labs/.agents-system';
 /** Strip the `gh:` prefix and `.git` suffix to get a GitHub `owner/repo` slug. */
@@ -22,9 +24,12 @@ export const DEFAULT_REGISTRIES = {
     skill: {},
 };
 /**
- * Registries that ship pre-seeded into new users' agents.yaml once, but are
- * not "defaults" — after seeding they behave like any user-added registry
- * (listable, disable-able, removable, and gone for good once removed).
+ * Third-party registries pre-seeded on first install for discoverability.
+ *
+ * These ship into new users' agents.yaml once, but are not "defaults" — after
+ * seeding they behave like any user-added registry (listable, disable-able,
+ * removable). Removed users can `agents registry remove <name>` to opt out;
+ * once removed they don't come back.
  */
 export const SEEDED_REGISTRIES = {
     mcp: {},

package/dist/lib/usage.d.ts

@@ -71,12 +71,37 @@ export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[]): Pr
     usageByKey: Map<string, UsageInfo>;
 }>;
 /**
- * Fetch usage for a single identity, with a 2-minute cache fast path.
- * Falls back to cached data when the live fetch fails.
+ * Fetch usage for a single identity using stale-while-revalidate.
+ *
+ * - Cache fresh (< 2 min): return cached snapshot, NO network.
+ * - Cache stale but < 24h: return cached snapshot instantly, fire background refresh.
+ * - Cache too stale or absent: block on live fetch, fall back to cache on error.
+ *
+ * This keeps `agents run` startup off the network on the hot path. The first
+ * invocation after a cold install or 24h gap still blocks once to seed the
+ * cache; every run after that returns instantly while the cache silently
+ * refreshes in the background.
  */
 export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Promise<UsageInfo>;
 /** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
+/**
+ * Compact colored badge for the account's overall usage status. Renders only
+ * when the account is throttled — `available` and `null` return ''.
+ *
+ * - `out_of_credits` → red "out of credits" (terminal account, all buckets dry)
+ * - `rate_limited`   → yellow "rate-limited" (transient throttling)
+ *
+ * The badge sits between the usage bars and `lastActive` in `agents view`, so
+ * a glance at the row tells the user whether the version can do useful work.
+ * The same signal is exposed as `usageStatus` in `agents view --json` for
+ * programmatic consumers (e.g. the swarmify panel's "resume in healthy agent").
+ *
+ * The switch is exhaustive on purpose — adding a new `AccountInfo.usageStatus`
+ * value without updating the cases here is a build error at `_exhaustive`,
+ * which is exactly the bug class this PR is fixing.
+ */
+export declare function formatUsageStatusBadge(usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null | undefined): string;
 /** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
 /** Load Claude OAuth credentials from the system keychain/keyring. */

package/dist/lib/usage.js

@@ -96,42 +96,95 @@ export async function getUsageInfoByIdentity(inputs) {
         usageByKey: new Map(usageResults.map(({ key, usage }) => [key, usage])),
     };
 }
-const USAGE_CACHE_FRESH_MS = 2 * 60 * 1000; // 2 minutes
+const USAGE_CACHE_FRESH_MS = 2 * 60 * 1000; // 2 minutes — fresh window: don't refresh.
+const USAGE_CACHE_SWR_MS = 24 * 60 * 60 * 1000; // 24 hours — beyond this, block on live fetch.
+/** In-process dedup: don't fire concurrent background refreshes for the same identity. */
+const inFlightRefreshes = new Map();
 /**
- * Fetch usage for a single identity, with a 2-minute cache fast path.
- * Falls back to cached data when the live fetch fails.
+ * Fetch usage for a single identity using stale-while-revalidate.
+ *
+ * - Cache fresh (< 2 min): return cached snapshot, NO network.
+ * - Cache stale but < 24h: return cached snapshot instantly, fire background refresh.
+ * - Cache too stale or absent: block on live fetch, fall back to cache on error.
+ *
+ * This keeps `agents run` startup off the network on the hot path. The first
+ * invocation after a cold install or 24h gap still blocks once to seed the
+ * cache; every run after that returns instantly while the cache silently
+ * refreshes in the background.
  */
 export async function getUsageInfoForIdentity(input) {
     const usageKey = getUsageLookupKey(input.info);
-    // Fast path: serve from cache if fresh. Skips the network call entirely.
-    if (input.agentId === 'claude' && usageKey) {
-        const cached = readClaudeUsageCache(usageKey);
-        if (cached?.capturedAt) {
-            const ageMs = Date.now() - cached.capturedAt.getTime();
-            if (ageMs < USAGE_CACHE_FRESH_MS) {
-                return { snapshot: cached, error: null };
-            }
-        }
+    // Non-Claude or no identity: legacy path, blocking fetch.
+    if (input.agentId !== 'claude' || !usageKey) {
+        return getUsageInfo(input.agentId, {
+            home: input.home,
+            cliVersion: input.cliVersion,
+            organizationId: input.info.organizationId,
+        });
     }
-    // Cache miss or stale -- make the network call.
+    const cached = readClaudeUsageCache(usageKey);
+    const ageMs = cached?.capturedAt ? Date.now() - cached.capturedAt.getTime() : Infinity;
+    // Fresh: cache is recent enough, skip network entirely.
+    if (cached && ageMs < USAGE_CACHE_FRESH_MS) {
+        return { snapshot: cached, error: null };
+    }
+    // Stale-while-revalidate: cache exists and isn't ancient, return it now and
+    // refresh in the background so the next invocation has fresh data.
+    if (cached && ageMs < USAGE_CACHE_SWR_MS) {
+        triggerBackgroundUsageRefresh(input, usageKey);
+        return { snapshot: cached, error: null };
+    }
+    // Cold cache or > 24h old: block on live fetch.
     const usage = await getUsageInfo(input.agentId, {
         home: input.home,
         cliVersion: input.cliVersion,
         organizationId: input.info.organizationId,
     });
-    if (input.agentId !== 'claude' || !usageKey) {
-        return usage;
-    }
     if (usage.snapshot?.source === 'live') {
         writeClaudeUsageCache(usageKey, usage.snapshot);
         return usage;
     }
-    const cached = readClaudeUsageCache(usageKey);
+    // Live fetch failed — last-resort fallback to whatever cache we had.
     if (cached) {
         return { snapshot: cached, error: usage.error };
     }
     return usage;
 }
+/**
+ * Kick off a background refresh of the usage cache. Errors are swallowed —
+ * a failed background refresh leaves the existing cache in place for the
+ * next invocation. The work is deferred to a future event-loop tick via
+ * `setImmediate` because some of the call chain (loadClaudeOauth →
+ * getKeychainToken → execFileSync) does synchronous I/O even though the
+ * functions are declared `async`. Without the defer, that sync I/O blocks
+ * the SWR caller and defeats the whole point of returning the cache instantly.
+ */
+function triggerBackgroundUsageRefresh(input, usageKey) {
+    if (inFlightRefreshes.has(usageKey))
+        return;
+    const promise = new Promise((resolve) => {
+        setImmediate(async () => {
+            try {
+                const usage = await getUsageInfo(input.agentId, {
+                    home: input.home,
+                    cliVersion: input.cliVersion,
+                    organizationId: input.info.organizationId,
+                });
+                if (usage.snapshot?.source === 'live') {
+                    writeClaudeUsageCache(usageKey, usage.snapshot);
+                }
+            }
+            catch {
+                /* background refresh failed — leave existing cache in place */
+            }
+            finally {
+                inFlightRefreshes.delete(usageKey);
+                resolve();
+            }
+        });
+    });
+    inFlightRefreshes.set(usageKey, promise);
+}
 /** Format a one-line usage summary with compact bars for inline display. */
 export function formatUsageSummary(plan, snapshot, planWidth = 3) {
     const parts = [];
@@ -148,6 +201,36 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
     }
     return parts.join('  ');
 }
+/**
+ * Compact colored badge for the account's overall usage status. Renders only
+ * when the account is throttled — `available` and `null` return ''.
+ *
+ * - `out_of_credits` → red "out of credits" (terminal account, all buckets dry)
+ * - `rate_limited`   → yellow "rate-limited" (transient throttling)
+ *
+ * The badge sits between the usage bars and `lastActive` in `agents view`, so
+ * a glance at the row tells the user whether the version can do useful work.
+ * The same signal is exposed as `usageStatus` in `agents view --json` for
+ * programmatic consumers (e.g. the swarmify panel's "resume in healthy agent").
+ *
+ * The switch is exhaustive on purpose — adding a new `AccountInfo.usageStatus`
+ * value without updating the cases here is a build error at `_exhaustive`,
+ * which is exactly the bug class this PR is fixing.
+ */
+export function formatUsageStatusBadge(usageStatus) {
+    if (usageStatus === null || usageStatus === undefined)
+        return '';
+    switch (usageStatus) {
+        case 'available': return '';
+        case 'out_of_credits': return chalk.red('out of credits');
+        case 'rate_limited': return chalk.yellow('rate-limited');
+        default: {
+            const _exhaustive = usageStatus;
+            void _exhaustive;
+            return '';
+        }
+    }
+}
 /** Format a multi-line usage section for detailed agent views. */
 export function formatUsageSection(usage) {
     if (!usage.snapshot && !usage.error) {