@phnx-labs/agents-cli 1.22.46 → 1.22.47

package/dist/lib/watchdog/service.d.ts

@@ -3,7 +3,6 @@ import { type WatchdogThresholds, type WatchdogTickResult } from './runner.js';
 export interface WatchdogPassOptions {
     nudge: boolean;
     nudgeText?: string;
-    smart?: boolean;
     smartAgent?: string;
     thresholds?: WatchdogThresholds;
     allowGhosttyFocus?: boolean;

package/dist/lib/watchdog/service.js

@@ -26,7 +26,6 @@ export async function runWatchdogPass(opts) {
     const result = await runWatchdogTick({
         nudge: opts.nudge,
         nudgeText: opts.nudgeText,
-        smart: opts.smart,
         smartAgent: opts.smartAgent,
         thresholds: opts.thresholds,
         allowGhosttyFocus: opts.allowGhosttyFocus,

package/dist/lib/watchdog/watchdog-agent.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The watchdog AGENT — the whole decider, in ONE call per tick.
+ *
+ * The watchdog does not use a heuristic script to guess idle-vs-unfinished. It
+ * hands every idle session's task + tail to an agent (via `agents run <target>
+ * --mode plan`, read-only) and asks it, for each, whether it is idle-but-unfinished
+ * (→ nudge) or idle-and-done / needs-human (→ skip). The whole idle set goes in ONE
+ * invocation, so the cost is one bounded plan-mode call per tick regardless of how
+ * many sessions are idle — not one agent per session, and only when something is
+ * actually idle (the caller does not invoke this with an empty list).
+ *
+ * A resolved `watchdog` workflow (repo > user > system, via resolveWorkflowRef)
+ * runs by name so its WORKFLOW.md body + `model:` frontmatter apply; otherwise the
+ * bare agent runs the built-in WATCHDOG_SYSTEM_PROMPT. Best-effort: any failure
+ * (agent unavailable, timeout, no verdict) yields an empty map, and the caller
+ * treats an unlisted terminal as a SAFE skip — never a blind nudge.
+ */
+import { type WatchdogCandidate, type Decision } from './watchdog.js';
+/** Judge every idle candidate at once; returns decisions keyed by terminalId. */
+export type WatchdogAgentDecider = (candidates: WatchdogCandidate[]) => Promise<Map<string, Decision>>;
+/**
+ * Runs the agent once and returns its raw stdout. Injectable so a test can assert
+ * the ONE-call-per-tick property and the assembled prompt without shelling out.
+ * `runTarget` is the resolved `agents run` target (a `watchdog` workflow or the
+ * bare agent id).
+ */
+export type WatchdogAgentRunner = (runTarget: string, prompt: string) => Promise<string>;
+/**
+ * The default agent decider. `agent` is the harness the built-in prompt runs as
+ * (default 'claude'); `workflowCwd` is where a `watchdog` workflow override is
+ * resolved from (the daemon's cwd — the batch spans many projects, so there is no
+ * single per-session cwd to key on); `run` is the injectable subprocess seam
+ * (tests pass a synthetic one). The whole idle set goes to the runner in ONE call.
+ */
+export declare function makeWatchdogAgentDecider(agent: string, opts?: {
+    workflowCwd?: string;
+    run?: WatchdogAgentRunner;
+}): WatchdogAgentDecider;

package/dist/lib/watchdog/watchdog-agent.js

@@ -0,0 +1,59 @@
+/**
+ * The watchdog AGENT — the whole decider, in ONE call per tick.
+ *
+ * The watchdog does not use a heuristic script to guess idle-vs-unfinished. It
+ * hands every idle session's task + tail to an agent (via `agents run <target>
+ * --mode plan`, read-only) and asks it, for each, whether it is idle-but-unfinished
+ * (→ nudge) or idle-and-done / needs-human (→ skip). The whole idle set goes in ONE
+ * invocation, so the cost is one bounded plan-mode call per tick regardless of how
+ * many sessions are idle — not one agent per session, and only when something is
+ * actually idle (the caller does not invoke this with an empty list).
+ *
+ * A resolved `watchdog` workflow (repo > user > system, via resolveWorkflowRef)
+ * runs by name so its WORKFLOW.md body + `model:` frontmatter apply; otherwise the
+ * bare agent runs the built-in WATCHDOG_SYSTEM_PROMPT. Best-effort: any failure
+ * (agent unavailable, timeout, no verdict) yields an empty map, and the caller
+ * treats an unlisted terminal as a SAFE skip — never a blind nudge.
+ */
+import { renderWatchdogPrompt, parseWatchdogResponse } from './watchdog.js';
+/** The real runner: one `agents run <target> --mode plan <prompt>` subprocess. */
+async function defaultAgentRunner(runTarget, prompt) {
+    const [{ execFile }, { promisify }] = await Promise.all([import('child_process'), import('util')]);
+    const execFileAsync = promisify(execFile);
+    const { stdout } = await execFileAsync('agents', ['run', runTarget, '--mode', 'plan', prompt], {
+        encoding: 'utf8',
+        maxBuffer: 4 * 1024 * 1024,
+        timeout: 120_000,
+    });
+    return stdout;
+}
+/**
+ * The default agent decider. `agent` is the harness the built-in prompt runs as
+ * (default 'claude'); `workflowCwd` is where a `watchdog` workflow override is
+ * resolved from (the daemon's cwd — the batch spans many projects, so there is no
+ * single per-session cwd to key on); `run` is the injectable subprocess seam
+ * (tests pass a synthetic one). The whole idle set goes to the runner in ONE call.
+ */
+export function makeWatchdogAgentDecider(agent, opts = {}) {
+    return async (candidates) => {
+        const result = new Map();
+        if (candidates.length === 0)
+            return result;
+        try {
+            const { resolveWorkflowRef } = await import('../workflows.js');
+            const cwd = opts.workflowCwd || process.cwd();
+            const workflowPath = resolveWorkflowRef('watchdog', cwd);
+            const runTarget = workflowPath ? 'watchdog' : agent;
+            const prompt = renderWatchdogPrompt(candidates);
+            const run = opts.run ?? defaultAgentRunner;
+            const stdout = await run(runTarget, prompt);
+            for (const d of parseWatchdogResponse(stdout))
+                result.set(d.terminalId, d);
+        }
+        catch {
+            // Agent unavailable / timed out — return what we have (possibly empty); the
+            // caller safe-skips any terminal with no verdict. Never a blind nudge.
+        }
+        return result;
+    };
+}

package/dist/lib/watchdog/watchdog.d.ts

@@ -3,12 +3,22 @@ export interface WatchdogCandidate {
     agentType: 'claude' | 'codex' | 'gemini';
     tailLines: string[];
     stalledForMs: number;
+    /** The originating task / first prompt / topic — so the agent can judge "was given a task but hasn't finished it". */
+    task?: string;
+    /** Working directory of the session, for context. */
+    cwd?: string;
 }
 export interface Decision {
     terminalId: string;
     action: 'nudge' | 'skip';
     text: string;
     reason: string;
+    /**
+     * Set by the agent on a SKIP to distinguish "genuinely needs the human"
+     * (true → surface it) from "the task is actually done" (false/absent → leave
+     * it alone, do not poke). `done` is a distinct terminal state from `idle`.
+     */
+    needsHuman?: boolean;
 }
 export type StallStatus = {
     kind: 'active';
@@ -33,8 +43,7 @@ export interface ClassifyInput {
     dormantMs: number;
 }
 export declare function classifyTerminal(input: ClassifyInput): StallStatus;
-export declare const WATCHDOG_SYSTEM_PROMPT = "You are the watchdog for AI coding agents running in terminals. Your one job is to get\nIDLE agents moving to completion: each agent has a goal and is expected to DRIVE TO\nCOMPLETION end-to-end, but the terminals below have gone idle. Read each one's goal and\nWHY it stopped, then decide NUDGE (send a message that unsticks it and drives it to\nfinish) or SKIP (it genuinely needs the human).\n\nRead the transcript before judging \u2014 an agent that already reached a decision needs \"do\nit,\" not \"decide.\"\n\nNUDGE when the agent went idle and could keep going on its own:\n- It asked permission for an obvious or already-authorized next step\n  (\"should I proceed?\", \"want me to continue?\", \"shall I run the tests?\").\n- It asked a question it could answer itself from the available context or a\n  reasonable default, or by using a tool it already has.\n- It announced an action (\"I'll run X\", \"let me write Y\") but no tool call followed.\n- It already decided what to do, then stalled without doing it.\n- It paused with the task incomplete and no real blocker.\n\nThe nudge text MUST carry context, not shove:\n- Restate the goal and reference the conclusion the agent ALREADY reached.\n- Give ONE concrete next step \u2014 the specific action, the sensible default, or a TOOL it\n  forgot it has (e.g. \"agents computer\" to drive the Mac, \"agents browser\" for the web,\n  \"agents ssh <mac> \\\"agents computer \u2026\\\"\" to drive a Mac from another box).\n- Split the ask: drive the reversible, goal-advancing part now; flag only a genuinely\n  disruptive sub-step for the human.\n- Tell it to use best judgment and finish end-to-end WITHOUT asking again.\n- Imperative, 1-2 sentences, no emojis, under 240 characters.\n\nSKIP when the agent genuinely needs the human (these belong in the user's feed, not a\nnudge):\n- Credentials, auth, login, 2FA, or biometric.\n- An irreversible or outward-facing action that needs sign-off (force-push, delete\n  prod data, publish/release, spend money, send an external message) \u2014 UNLESS the House\n  Rules below authorize it.\n- A real product or intent decision with genuine ambiguity (not a trivial default).\n- The task is actually complete.\n- You cannot tell what the agent is doing.\n\nRespond with ONLY a JSON array (no prose, no code fence):\n[{\"terminalId\":\"<id>\",\"action\":\"nudge\"|\"skip\",\"text\":\"<message or empty>\",\"reason\":\"<brief>\"}]";
+export declare const WATCHDOG_SYSTEM_PROMPT = "You are the watchdog for AI coding agents running in terminals. You are given the idle\nsessions on this machine \u2014 each with its originating TASK, how long it has been idle, and\nthe tail of its transcript. Your one job is to tell, for each one, whether it is\nIDLE-BUT-UNFINISHED (it was given a task, went quiet, and has NOT finished or handed it\noff) or IDLE-AND-DONE (it finished, or it genuinely needs the human). Idle-but-unfinished\nis the dangerous state \u2014 the work is most likely to be silently abandoned \u2014 so those get a\nNUDGE that drives them to finish. Everything else is a SKIP.\n\nRead each transcript before judging \u2014 an agent that already reached a decision needs \"do\nit,\" not \"decide.\" Judge from the task + tail, not from keywords.\n\nNUDGE when the agent went idle and could keep going on its own:\n- It asked permission for an obvious or already-authorized next step\n  (\"should I proceed?\", \"want me to continue?\", \"shall I run the tests?\").\n- It asked a question it could answer itself from the available context or a\n  reasonable default, or by using a tool it already has.\n- It announced an action (\"I'll run X\", \"let me write Y\") but no tool call followed.\n- It already decided what to do, then stalled without doing it.\n- It paused with the task incomplete and no real blocker.\n\nThe nudge text MUST carry context, not shove:\n- Restate the goal and reference the conclusion the agent ALREADY reached.\n- Give ONE concrete next step \u2014 the specific action, the sensible default, or a TOOL it\n  forgot it has (e.g. \"agents computer\" to drive the Mac, \"agents browser\" for the web,\n  \"agents ssh <mac> \\\"agents computer \u2026\\\"\" to drive a Mac from another box).\n- Split the ask: drive the reversible, goal-advancing part now; flag only a genuinely\n  disruptive sub-step for the human.\n- Tell it to use best judgment and finish end-to-end WITHOUT asking again.\n- Imperative, 1-2 sentences, no emojis, under 240 characters.\n\nSKIP in two distinct cases \u2014 mark which with \"needsHuman\":\n- needsHuman=true \u2014 the agent is genuinely blocked on a human (these belong in the user's\n  feed): credentials, auth, login, 2FA, or biometric; an irreversible or outward-facing\n  action needing sign-off (force-push, delete prod data, publish/release, spend money,\n  send an external message) UNLESS the House Rules below authorize it; a real product or\n  intent decision with genuine ambiguity (not a trivial default); or you cannot tell what\n  the agent is doing.\n- needsHuman=false \u2014 the task is actually complete (idle-and-done). Leave it alone; do NOT\n  poke a finished session.\n\nRespond with ONLY a JSON array (no prose, no code fence). Include \"needsHuman\" on every\nskip:\n[{\"terminalId\":\"<id>\",\"action\":\"nudge\"|\"skip\",\"text\":\"<message or empty>\",\"reason\":\"<brief>\",\"needsHuman\":true|false}]";
 export declare function composePromptWithPlaybook(basePrompt: string, playbook: string): string;
 export declare function renderWatchdogPrompt(candidates: WatchdogCandidate[], playbook?: string): string;
 export declare function parseWatchdogResponse(stdout: string): Decision[];
-export declare function isLikelyTrulyBlocked(candidate: WatchdogCandidate): boolean;

package/dist/lib/watchdog/watchdog.js

@@ -1,53 +1,9 @@
-// Watchdog: pure logic for detecting stalled agent terminals and rendering
-// prompts to a headless decider instance that decides whether to nudge them.
-// Ported from Swarmify (extension/src/core/watchdog.ts) — behavior verbatim.
-// Terminal/session delivery lives elsewhere; this module reads no files and
-// touches no host APIs so it can be unit-tested in isolation.
-const FORCE_REVIEW_STALL_MS = 15 * 60 * 1000;
-const BLOCKED_HINTS = [
-    'blocked',
-    'stuck',
-    "can't",
-    'cannot',
-    'unable',
-    'failed',
-    'error',
-    'exception',
-    'traceback',
-    'timed out',
-    'timeout',
-    'rate limit',
-    'permission denied',
-];
-const WAITING_HINTS = [
-    'waiting on user',
-    'awaiting user',
-    'askuserquestion',
-];
-const COMPLETION_HINTS = [
-    'done',
-    'completed',
-    'all set',
-    'finished',
-];
-const TOOL_CALL_HINTS = [
-    '"type":"tool_use"',
-    '"type":"tool_call"',
-    '"type":"function_call"',
-];
-const ASSISTANT_LINE_HINTS = [
-    '"type":"assistant"',
-    '"role":"assistant"',
-    '"payload":{"type":"message"',
-];
-const PROMISE_HINTS = [
-    "i'll",
-    'i will',
-    'let me',
-    'going to',
-    "next i'll",
-    'next i will',
-];
+// Watchdog: pure logic for detecting stalled agent terminals and rendering the
+// prompt that the watchdog AGENT reads to decide idle-vs-unfinished and craft a
+// nudge. There is deliberately no heuristic decider here (no regex over the tail
+// guessing "done" vs "stuck") — that judgment is the agent's job. This module
+// only classifies idleness by timestamp and renders/parses the agent's I/O, so
+// it reads no files and touches no host APIs and can be unit-tested in isolation.
 export function classifyTerminal(input) {
     if (input.optedOut)
         return { kind: 'opted_out' };
@@ -64,14 +20,16 @@ export function classifyTerminal(input) {
     }
     return { kind: 'stalled', stalledForMs: age };
 }
-export const WATCHDOG_SYSTEM_PROMPT = `You are the watchdog for AI coding agents running in terminals. Your one job is to get
-IDLE agents moving to completion: each agent has a goal and is expected to DRIVE TO
-COMPLETION end-to-end, but the terminals below have gone idle. Read each one's goal and
-WHY it stopped, then decide NUDGE (send a message that unsticks it and drives it to
-finish) or SKIP (it genuinely needs the human).
+export const WATCHDOG_SYSTEM_PROMPT = `You are the watchdog for AI coding agents running in terminals. You are given the idle
+sessions on this machine — each with its originating TASK, how long it has been idle, and
+the tail of its transcript. Your one job is to tell, for each one, whether it is
+IDLE-BUT-UNFINISHED (it was given a task, went quiet, and has NOT finished or handed it
+off) or IDLE-AND-DONE (it finished, or it genuinely needs the human). Idle-but-unfinished
+is the dangerous state — the work is most likely to be silently abandoned — so those get a
+NUDGE that drives them to finish. Everything else is a SKIP.
 
-Read the transcript before judging — an agent that already reached a decision needs "do
-it," not "decide."
+Read each transcript before judging — an agent that already reached a decision needs "do
+it," not "decide." Judge from the task + tail, not from keywords.
 
 NUDGE when the agent went idle and could keep going on its own:
 - It asked permission for an obvious or already-authorized next step
@@ -92,18 +50,19 @@ The nudge text MUST carry context, not shove:
 - Tell it to use best judgment and finish end-to-end WITHOUT asking again.
 - Imperative, 1-2 sentences, no emojis, under 240 characters.
 
-SKIP when the agent genuinely needs the human (these belong in the user's feed, not a
-nudge):
-- Credentials, auth, login, 2FA, or biometric.
-- An irreversible or outward-facing action that needs sign-off (force-push, delete
-  prod data, publish/release, spend money, send an external message) — UNLESS the House
-  Rules below authorize it.
-- A real product or intent decision with genuine ambiguity (not a trivial default).
-- The task is actually complete.
-- You cannot tell what the agent is doing.
+SKIP in two distinct cases — mark which with "needsHuman":
+- needsHuman=true — the agent is genuinely blocked on a human (these belong in the user's
+  feed): credentials, auth, login, 2FA, or biometric; an irreversible or outward-facing
+  action needing sign-off (force-push, delete prod data, publish/release, spend money,
+  send an external message) UNLESS the House Rules below authorize it; a real product or
+  intent decision with genuine ambiguity (not a trivial default); or you cannot tell what
+  the agent is doing.
+- needsHuman=false — the task is actually complete (idle-and-done). Leave it alone; do NOT
+  poke a finished session.
 
-Respond with ONLY a JSON array (no prose, no code fence):
-[{"terminalId":"<id>","action":"nudge"|"skip","text":"<message or empty>","reason":"<brief>"}]`;
+Respond with ONLY a JSON array (no prose, no code fence). Include "needsHuman" on every
+skip:
+[{"terminalId":"<id>","action":"nudge"|"skip","text":"<message or empty>","reason":"<brief>","needsHuman":true|false}]`;
 // User-editable playbook appended below the built-in prompt. The user maintains
 // the source at ~/.agents/playbooks/watchdog.md (read by the delivery layer);
 // this function is pure so it can be tested without filesystem access.
@@ -115,10 +74,14 @@ export function composePromptWithPlaybook(basePrompt, playbook) {
 }
 export function renderWatchdogPrompt(candidates, playbook = '') {
     const systemPrompt = composePromptWithPlaybook(WATCHDOG_SYSTEM_PROMPT, playbook);
-    const parts = [systemPrompt, '', 'STALLED TERMINALS:', ''];
+    const parts = [systemPrompt, '', 'IDLE SESSIONS:', ''];
     for (const c of candidates) {
         const seconds = Math.round(c.stalledForMs / 1000);
         parts.push(`--- terminal ${c.terminalId} (${c.agentType}, idle ${seconds}s) ---`);
+        if (c.task)
+            parts.push(`task: ${c.task}`);
+        if (c.cwd)
+            parts.push(`cwd: ${c.cwd}`);
         parts.push('last JSONL lines:');
         for (const line of c.tailLines) {
             parts.push(line);
@@ -153,41 +116,11 @@ export function parseWatchdogResponse(stdout) {
         const reason = typeof obj.reason === 'string' ? obj.reason : '';
         if (!terminalId || !action)
             continue;
-        decisions.push({ terminalId, action, text, reason });
+        // needsHuman only meaningful on a skip; a nudge is never "needs human".
+        const needsHuman = action === 'skip' && obj.needsHuman === true ? true
+            : action === 'skip' && obj.needsHuman === false ? false
+                : undefined;
+        decisions.push({ terminalId, action, text, reason, needsHuman });
     }
     return decisions;
 }
-export function isLikelyTrulyBlocked(candidate) {
-    // With no tail to reason over, only a very long stall counts as blocked.
-    if (candidate.tailLines.length === 0)
-        return candidate.stalledForMs >= FORCE_REVIEW_STALL_MS;
-    const lowerTail = candidate.tailLines.join('\n').toLowerCase();
-    // Waiting-on-user and completion hints are checked BEFORE the 15m force-review
-    // short-circuit — a long-idle OPEN QUESTION must defer (not be blindly
-    // force-nudged) and a finished task is done. The old order tested stall age
-    // first, so a 15m-60m idle session whose tail said "waiting on user" / "done"
-    // was force-nudged anyway. Precedence fixed here (watchdog-brain-v2).
-    if (WAITING_HINTS.some((hint) => lowerTail.includes(hint)))
-        return false;
-    if (COMPLETION_HINTS.some((hint) => lowerTail.includes(hint)))
-        return false;
-    if (candidate.stalledForMs >= FORCE_REVIEW_STALL_MS)
-        return true;
-    if (BLOCKED_HINTS.some((hint) => lowerTail.includes(hint)))
-        return true;
-    let sawToolAfter = false;
-    for (let i = candidate.tailLines.length - 1; i >= 0; i--) {
-        const line = candidate.tailLines[i].toLowerCase();
-        if (TOOL_CALL_HINTS.some((hint) => line.includes(hint))) {
-            sawToolAfter = true;
-            continue;
-        }
-        if (!sawToolAfter) {
-            const isAssistantLine = ASSISTANT_LINE_HINTS.some((hint) => line.includes(hint));
-            const hasPromise = PROMISE_HINTS.some((hint) => line.includes(hint));
-            if (isAssistantLine && hasPromise)
-                return true;
-        }
-    }
-    return false;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.46",
+  "version": "1.22.47",
   "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",
@@ -79,7 +79,7 @@
     "multi-agent"
   ],
   "author": "Phoenix Labs",
-  "license": "Apache-2.0",
+  "license": "FSL-1.1-Apache-2.0",
   "engines": {
     "node": ">=22.5.0",
     "npm": ">=9"

package/dist/commands/usage.d.ts

@@ -1,27 +0,0 @@
-/**
- * Usage command -- show rate-limit / quota status for each installed agent.
- *
- * Lists every installed agent with the best available usage snapshot:
- *   - claude: live OAuth API call (cached for 5 minutes)
- *   - codex:  parsed from latest session log's rate_limits event
- *   - kimi:   live Kimi Code /usages API call (cached for 5 minutes)
- *   - droid:  live Factory billing/limits API call (cached for 5 minutes)
- *   - grok:   parsed from the latest local usage event
- *   - cursor: live Cursor usage API call (cached for 5 minutes)
- *   - others: marked as "not exposed by CLI"
- */
-import type { Command } from 'commander';
-import type { AgentId } from '../lib/types.js';
-import { getUsageInfoForIdentity } from '../lib/accounting/usage.js';
-/** One agent's usage snapshot — the unit the text and --json renderers share. */
-export interface AgentUsageRecord {
-    agent: AgentId;
-    /** Plain agent name (no ANSI) — safe to emit in --json; the text table colorizes it. */
-    label: string;
-    status: 'unsupported' | 'no-version' | 'not-signed-in' | 'ok';
-    email?: string;
-    usage?: Awaited<ReturnType<typeof getUsageInfoForIdentity>>;
-}
-export declare function registerUsageCommand(program: Command): void;
-/** Render one usage record as the human table section. */
-export declare function formatAgentUsage(rec: AgentUsageRecord): string;

package/dist/commands/usage.js

@@ -1,96 +0,0 @@
-import { addHostOption } from '../lib/hosts/option.js';
-import chalk from 'chalk';
-import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
-import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/installations/versions.js';
-import { agentReportsUsage, formatUsageSection, getUsageInfoForIdentity } from '../lib/accounting/usage.js';
-export function registerUsageCommand(program) {
-    addHostOption(program.command('usage [agent]'))
-        .description('Show rate-limit / quota usage per agent')
-        .option('--json', 'Emit machine-readable JSON (per-agent usage snapshot) instead of the table')
-        .option('-r, --refresh', 'Collect fresh usage through the shared device coordinator before rendering')
-        .addHelpText('after', `
-Examples:
-  agents usage              Show usage for all installed agents
-  agents usage claude       Show usage for Claude only
-  agents usage codex        Show usage for Codex only
-  agents usage claude --refresh  Explicitly refresh Claude once, device-wide
-  agents usage --json       Machine-readable snapshot for scripts
-`)
-        .action(async (agentFilter, options) => {
-        let filter;
-        if (agentFilter) {
-            const resolved = resolveAgentName(agentFilter);
-            if (!resolved) {
-                console.error(chalk.red(formatAgentError(agentFilter)));
-                process.exit(1);
-            }
-            filter = resolved;
-        }
-        const targets = filter
-            ? [filter]
-            : ALL_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
-        if (targets.length === 0) {
-            if (options.json) {
-                console.log('[]');
-                return;
-            }
-            console.log(chalk.gray('No agents installed. Run `agents add <agent>` first.'));
-            return;
-        }
-        const records = await Promise.all(targets.map((agentId) => collectAgentUsage(agentId, options.refresh === true)));
-        if (options.json) {
-            console.log(JSON.stringify(records, null, 2));
-            return;
-        }
-        console.log(records.map(formatAgentUsage).filter(Boolean).join('\n\n'));
-    });
-}
-/** Gather one agent's usage snapshot as structured data (shared by both renderers). */
-async function collectAgentUsage(agentId, forceRefresh = false) {
-    // Plain name — color is applied only at text-render time (formatAgentUsage), so
-    // `--json` never emits ANSI escapes in `label` (e.g. under FORCE_COLOR=1).
-    const label = AGENTS[agentId].name;
-    if (!agentReportsUsage(agentId)) {
-        return { agent: agentId, label, status: 'unsupported' };
-    }
-    const versions = listInstalledVersions(agentId);
-    const version = getGlobalDefault(agentId) || versions[0];
-    if (!version) {
-        return { agent: agentId, label, status: 'no-version' };
-    }
-    const home = getVersionHomePath(agentId, version);
-    const info = await getAccountInfo(agentId, home);
-    if (!info.usageKey && !info.accountKey) {
-        return { agent: agentId, label, status: 'not-signed-in' };
-    }
-    const usage = await getUsageInfoForIdentity({ agentId, home, info, cliVersion: null }, forceRefresh ? { forceRefresh: true } : undefined);
-    return { agent: agentId, label, status: 'ok', email: info.email ?? undefined, usage };
-}
-/** Render one usage record as the human table section. */
-export function formatAgentUsage(rec) {
-    const cfg = AGENTS[rec.agent];
-    // Colorize the heading here (not in the record) so the plain `label` stays
-    // clean for --json while the text table keeps its per-agent color.
-    const heading = agentLabel(rec.agent);
-    switch (rec.status) {
-        case 'unsupported':
-            return [heading, `  ${chalk.dim(`${cfg.name} CLI does not publish usage data.`)}`].join('\n');
-        case 'no-version':
-            return [heading, `  ${chalk.dim('No version installed.')}`].join('\n');
-        case 'not-signed-in':
-            return [heading, `  ${chalk.dim('Not signed in.')}`].join('\n');
-        case 'ok': {
-            const lines = [heading];
-            if (rec.email)
-                lines.push(`  ${chalk.dim(rec.email)}`);
-            const section = formatUsageSection(rec.usage);
-            if (section.length === 0) {
-                lines.push(`  ${chalk.dim('No usage data available right now.')}`);
-            }
-            else {
-                lines.push(...section);
-            }
-            return lines.join('\n');
-        }
-    }
-}