@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/commands/teams.js

@@ -1,10 +1,12 @@
 import chalk from 'chalk';
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { AgentManager, checkAllClis, getAgentsDir, } from '../lib/teams/agents.js';
+import { AgentManager, checkAllClis, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { resolveProvider } from '../lib/cloud/registry.js';
+import { runSupervisor } from '../lib/teams/supervisor.js';
 import { handleSpawn, handleStatus, handleStop, handleTasks, } from '../lib/teams/api.js';
 import { createTeam, ensureTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
-import { isVersionInstalled } from '../lib/versions.js';
+import { isVersionInstalled, resolveVersionAlias, resolveVersionAliasLoose } from '../lib/versions.js';
 import { discoverSessions, parseTimeFilter, resolveSessionById } from '../lib/session/discover.js';
 import { buildPreview as buildSessionPreview } from './sessions-picker.js';
 import { parseExecEnv } from '../lib/exec.js';
@@ -21,6 +23,7 @@ const AGENT_NAMES = {
 const VALID_AGENTS = Object.keys(AGENT_NAMES);
 const VALID_MODES = ['plan', 'edit', 'full'];
 const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'auto'];
+const VALID_CLOUD_PROVIDERS = ['rush', 'codex', 'factory'];
 // Auto-enable JSON mode when piped / not a TTY so AI agent consumers get
 // parseable output by default.
 function isJsonMode(opts) {
@@ -57,6 +60,25 @@ function truncate(s, n) {
         return s;
     return s.slice(0, n - 1) + '…';
 }
+function compactPrompt(s, n = 160) {
+    return truncate(s.replace(/\s+/g, ' ').trim(), n);
+}
+function formatTimestamp(iso) {
+    if (!iso)
+        return null;
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    return d.toLocaleString(undefined, {
+        month: 'short',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+    });
+}
+function padRight(s, width) {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
 function fullName(type, version) {
     const name = AGENT_NAMES[type];
     return version ? `${name} ${version}` : name;
@@ -67,15 +89,101 @@ function parseTeammate(spec) {
         die(`Unknown teammate '${name}'. Available: ${VALID_AGENTS.join(', ')}.\n` +
             `  Use the form 'claude' or 'claude@2.1.112' (see 'agents view' for installed versions).`);
     }
-    return { agent: name, version: version || null };
+    const agent = name;
+    return { agent, version: resolveVersionAlias(agent, version) ?? null };
 }
 function shortId(id) {
     return id.slice(0, 8);
 }
-// Pick the display handle for a teammate: their given name if they have one,
-// otherwise the 8-char UUID prefix.
+/**
+ * Preamble injected into every factory worker's prompt. Tells the worker
+ * which team + teammate name + task-type it is, and how to file new tasks.
+ * The actual how-to lives in the /factory-worker skill.
+ */
+function factoryWorkerPreamble(team, name, taskType, after) {
+    const n = name ?? '<anonymous>';
+    const deps = after.length > 0 ? after.join(', ') : '(none)';
+    return [
+        `FACTORY WORKER — team="${team}", name="${n}", task_type="${taskType}", after=${deps}`,
+        `You are a teammate in a Software Factory. Read the /factory-worker skill for the full pattern.`,
+        `Key rules:`,
+        ` - Other teammates may be running now. Coordinate via git and tests only — no direct peer communication.`,
+        ` - If you discover work beyond your task, file a new teammate via Bash:`,
+        `     agents teams add "${team}" claude "<ask>" --name <slug> --task-type <implement|test|review|bugfix|docs> [--after <dep>]`,
+        `   A background supervisor picks up new tasks every wave.`,
+        ``,
+        `YOUR TASK:`,
+    ].join('\n');
+}
+function mkManager() {
+    return new AgentManager();
+}
+/**
+ * Register the generic cloud dispatcher — staged cloud teammates get
+ * dispatched when their --after deps resolve, using repo/branch stored on
+ * the teammate itself so we don't need the original --cloud CLI args.
+ */
+export function wireCloudDispatcher(mgr) {
+    mgr.setCloudDispatcher(async (a) => {
+        if (!a.cloudProvider) {
+            throw new Error(`Teammate ${a.agentId} has no cloud provider set`);
+        }
+        const prov = resolveProvider(a.cloudProvider);
+        const dispatchOpts = {
+            prompt: a.prompt,
+            agent: a.agentType,
+            repo: a.cloudRepo ?? undefined,
+            branch: a.cloudBranch ?? undefined,
+            model: a.model ?? undefined,
+        };
+        const cloudTask = await prov.dispatch(dispatchOpts);
+        return { cloudSessionId: cloudTask.id };
+    });
+}
+/** Single-wave start used by `teams start` without --watch. */
+async function runOneWave(mgr, team, json) {
+    const launched = await mgr.startReady(team);
+    const all = await mgr.listByTask(team);
+    const stillPending = all.filter((a) => a.status === 'pending');
+    if (json) {
+        console.log(JSON.stringify({
+            team,
+            launched: launched.map((a) => ({ agent_id: a.agentId, name: a.name, after: a.after })),
+            still_pending: stillPending.map((a) => ({ agent_id: a.agentId, name: a.name, after: a.after })),
+        }, null, 2));
+        return;
+    }
+    if (launched.length === 0 && stillPending.length === 0) {
+        console.log(chalk.gray(`No pending teammates in team ${team}.`));
+        return;
+    }
+    if (launched.length > 0) {
+        console.log(chalk.green(`Launched ${launched.length} teammate(s) in team ${chalk.cyan(team)}:`));
+        for (const a of launched) {
+            const who = fullName(a.agentType, a.version);
+            const h = a.name || shortId(a.agentId);
+            console.log(`  ${chalk.cyan(h)}  ${who}`);
+        }
+    }
+    if (stillPending.length > 0) {
+        console.log();
+        console.log(chalk.gray(`Still pending (${stillPending.length}):`));
+        for (const a of stillPending) {
+            const h = a.name || shortId(a.agentId);
+            console.log(`  ${chalk.blue(h)}  ${chalk.gray('after')} ${a.after.join(', ')}`);
+        }
+    }
+}
+// Pick the display handle for a teammate: explicit teammate name, Claude
+// session label, then the 8-char UUID prefix.
 function handle(a) {
-    return a.name || shortId(a.agent_id);
+    return a.name || a.session_label || shortId(a.agent_id);
+}
+function displayHandle(a) {
+    if (a.name && a.session_label && a.name !== a.session_label) {
+        return `${a.name} / ${a.session_label}`;
+    }
+    return handle(a);
 }
 // Resolve a teammate reference (name / UUID / UUID prefix) by scanning every
 // meta.json under the agents dir. Team hint narrows the search.
@@ -138,10 +246,26 @@ async function resolveTeammateAcrossTeams(base, ref, teamHint) {
 function printAgentDetail(a, session) {
     const label = statusColor(a.status)(a.status.toUpperCase());
     const who = fullName(a.agent_type, a.version);
-    const h = handle(a);
+    const h = displayHandle(a);
     const secondary = a.name ? chalk.gray(`(${shortId(a.agent_id)})`) : '';
     const duration = a.duration ? `${chalk.gray(' · ')}${chalk.white(a.duration)}` : '';
     console.log(`  ${chalk.cyan(h.padEnd(10))} ${secondary.padEnd(11)} ${who.padEnd(18)} ${label}${duration}`);
+    if (a.task_type) {
+        console.log(`    ${chalk.gray('type    ')} ${chalk.magenta(a.task_type)}`);
+    }
+    if (a.prompt) {
+        console.log(`    ${chalk.gray('task    ')} ${chalk.white(compactPrompt(a.prompt))}`);
+    }
+    const started = formatTimestamp(a.started_at);
+    const completed = formatTimestamp(a.completed_at);
+    if (started || completed) {
+        const parts = [];
+        if (started)
+            parts.push(`started ${started}`);
+        if (completed)
+            parts.push(`ended ${completed}`);
+        console.log(`    ${chalk.gray('time    ')} ${parts.join(chalk.gray(' · '))}`);
+    }
     if (a.after && a.after.length) {
         console.log(`    ${chalk.gray('after   ')} ${a.after.join(', ')}`);
     }
@@ -181,6 +305,13 @@ function printAgentDetail(a, session) {
                 console.log(`    ${chalk.gray('> ' + truncate(firstLine, 96))}`);
         }
     }
+    if (a.recent_tool_calls.length) {
+        console.log(`    ${chalk.gray('tools   ')}`);
+        for (const call of a.recent_tool_calls.slice(-5)) {
+            const when = call.timestamp ? `${relTime(call.timestamp)} ` : '';
+            console.log(`      ${chalk.gray(when)}${chalk.bold(call.tool)} ${chalk.gray(truncate(call.summary, 96))}`);
+        }
+    }
     if (a.has_errors)
         console.log(`    ${chalk.red('! reported an error')}`);
     if (a.pr_url)
@@ -377,6 +508,7 @@ async function pickTeamOr(mgr, command) {
         throw err;
     }
 }
+/** Register the `agents teams` command tree (list, create, add, status, start, remove, disband, logs, doctor). */
 export function registerTeamsCommands(program) {
     const teams = program
         .command('teams')
@@ -389,27 +521,32 @@ create DAG-style dependencies (one teammate waits for another to finish first).
 Teammate sessions appear in 'agents sessions --teams' with a [team/name · mode] tag.
 
 Examples:
-  # Start a new team for a feature
-  agents teams create auth-feature
+  # Spin up a team to ship the new pricing page end-to-end
+  agents teams create pricing-page
+
+  # Backend first: Claude rewrites the billing endpoint
+  agents teams add pricing-page claude "Rewrite /v2/pricing to return tiered plans from billing.plans table" --name backend
 
-  # Add Alice (Claude) to work on the backend
-  agents teams add auth-feature claude "Add JWT auth middleware" --name alice
+  # Frontend can start in parallel — it stubs the API while backend lands
+  agents teams add pricing-page codex "Build the new /pricing route in apps/web with the three-tier layout" --name frontend
 
-  # Add Bob (Codex 0.116.0) to write tests, but wait for Alice to finish first
-  agents teams add auth-feature codex@0.116.0 "Write integration tests" --name bob --after alice
+  # QA waits for both to finish before running e2e
+  agents teams add pricing-page claude "Run the full Playwright suite, fix any flakes, paste failing screenshots" --name qa --after backend,frontend
 
-  # Kick off any staged teammates whose dependencies are satisfied
-  agents teams start auth-feature
+  # Drain the DAG: backend + frontend launch now, qa picks up when they're done
+  agents teams start pricing-page --watch
 
-  # Check in on progress (delta polling with --since for efficiency)
-  agents teams status auth-feature
-  agents teams status auth-feature --since 2026-04-19T10:30:00Z
+  # Check in without re-reading everything (delta poll)
+  agents teams status pricing-page --since 2026-04-24T09:00:00-07:00
 
-  # Let Alice go when she's done
-  agents teams remove auth-feature alice
+  # Pull the live log of one teammate
+  agents teams logs frontend
 
-  # Wind down the whole team when work is complete
-  agents teams disband auth-feature
+  # A teammate is stuck — pull them out, the rest keeps going
+  agents teams remove pricing-page frontend
+
+  # Ship done — wind everyone down
+  agents teams disband pricing-page
 
 Short aliases:
   teams c  = create    teams a  = add       teams s  = status
@@ -433,7 +570,7 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .option('-n, --limit <n>', 'Show at most this many teams (default: 20)', '20')
         .option('--json', 'Output machine-readable JSON instead of formatted table')
         .action(async (query, opts) => {
-        const mgr = new AgentManager();
+        const mgr = mkManager();
         const limit = Math.max(1, parseInt(opts.limit, 10) || 20);
         const [tasks, registry, everyAgent] = await Promise.all([
             handleTasks(mgr, 1000),
@@ -455,7 +592,10 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         }
         // --- --agent: filter teams containing a matching teammate ---
         if (opts.agent) {
-            const [wantType, wantVersion] = opts.agent.split('@');
+            const [wantType, rawVersion] = opts.agent.split('@');
+            const wantVersion = VALID_AGENTS.includes(wantType)
+                ? resolveVersionAliasLoose(wantType, rawVersion)
+                : rawVersion;
             merged = merged.filter((t) => {
                 const teammates = byTeam.get(t.task_name) || [];
                 return teammates.some((m) => m.agent_type === wantType && (!wantVersion || m.version === wantVersion));
@@ -567,6 +707,10 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .option('--env <key=value>', 'Set an environment variable for this teammate (repeatable for multiple vars)', (val, prev) => [...prev, val], [])
         .option('--cwd <dir>', 'Working directory for this teammate (default: current directory)')
         .option('--after <names>', "DAG dependencies: comma-separated teammate names to wait for. Stages as PENDING; run 'teams start' to launch when ready.")
+        .option('--task-type <type>', `Factory label: ${VALID_TASK_TYPES.join('|')}. Drives planner fan-out + test-oracle bugfix loop.`)
+        .option('--cloud <provider>', `Dispatch to cloud backend instead of local CLI: ${VALID_CLOUD_PROVIDERS.join('|')}`)
+        .option('--repo <owner/repo>', 'GitHub repository (required for --cloud rush)')
+        .option('--branch <name>', 'Target git branch for cloud dispatch')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, teammate, task, opts) => {
         if (!VALID_MODES.includes(opts.mode)) {
@@ -575,6 +719,23 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         if (!VALID_EFFORTS.includes(opts.effort)) {
             die(`Invalid effort '${opts.effort}'. Use one of: ${VALID_EFFORTS.join(', ')}`);
         }
+        let taskType = null;
+        if (opts.taskType) {
+            if (!VALID_TASK_TYPES.includes(opts.taskType)) {
+                die(`Invalid task-type '${opts.taskType}'. Use one of: ${VALID_TASK_TYPES.join(', ')}`);
+            }
+            taskType = opts.taskType;
+        }
+        let cloudProviderId = null;
+        if (opts.cloud) {
+            if (!VALID_CLOUD_PROVIDERS.includes(opts.cloud)) {
+                die(`Invalid cloud provider '${opts.cloud}'. Use one of: ${VALID_CLOUD_PROVIDERS.join(', ')}`);
+            }
+            cloudProviderId = opts.cloud;
+            if (cloudProviderId === 'rush' && !opts.repo) {
+                die(`--cloud rush requires --repo <owner/repo>`);
+            }
+        }
         const { agent, version } = parseTeammate(teammate);
         if (version && !isVersionInstalled(agent, version)) {
             die(`${AGENT_NAMES[agent]} ${version} isn't installed.\n` +
@@ -602,9 +763,55 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         // Auto-create the team if it doesn't exist yet (friendlier UX than erroring).
         await ensureTeam(team);
         const cwd = opts.cwd ?? process.cwd();
-        const mgr = new AgentManager();
+        const mgr = mkManager();
+        // Factory teammates: prepend the worker-skill preamble to every task
+        // prompt so implementers/testers/reviewers know about the Ledger, the
+        // dynamic DAG, and the pattern for filing new tasks mid-flight. No
+        // preamble when --task-type isn't set (plain teammates work as before).
+        let effectiveTask = task;
+        if (taskType) {
+            effectiveTask = factoryWorkerPreamble(team, opts.name ?? null, taskType, after) + '\n\n' + task;
+        }
+        // Dispatcher callback: when a staged cloud teammate's deps resolve,
+        // AgentManager.startReady() invokes this to kick off the remote task.
+        if (cloudProviderId) {
+            const providerId = cloudProviderId;
+            mgr.setCloudDispatcher(async (a) => {
+                const prov = resolveProvider(providerId);
+                const dispatchOpts = {
+                    prompt: a.prompt,
+                    agent: a.agentType,
+                    repo: opts.repo,
+                    branch: opts.branch,
+                    model: a.model ?? undefined,
+                };
+                const cloudTask = await prov.dispatch(dispatchOpts);
+                return { cloudSessionId: cloudTask.id };
+            });
+        }
+        let cloudSessionId = null;
+        const isStaged = after.length > 0;
+        if (cloudProviderId && !isStaged) {
+            // Ready to run now: dispatch to the cloud provider before registering
+            // the teammate so we have the remote session id up front.
+            const prov = resolveProvider(cloudProviderId);
+            const dispatchOpts = {
+                prompt: effectiveTask,
+                agent,
+                repo: opts.repo,
+                branch: opts.branch,
+                model: opts.model,
+            };
+            try {
+                const cloudTask = await prov.dispatch(dispatchOpts);
+                cloudSessionId = cloudTask.id;
+            }
+            catch (err) {
+                die(`Cloud dispatch failed: ${err.message}`);
+            }
+        }
         try {
-            const result = await handleSpawn(mgr, team, agent, task, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null);
+            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null);
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(result, null, 2));
                 return;
@@ -623,6 +830,12 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             console.log(`  ${chalk.gray('status  ')}  ${statusColor(result.status)(result.status)}`);
             console.log(`  ${chalk.gray('mode    ')}  ${opts.mode}`);
             console.log(`  ${chalk.gray('working ')}  ${cwd}`);
+            if (result.task_type) {
+                console.log(`  ${chalk.gray('task    ')}  ${chalk.cyan(result.task_type)}`);
+            }
+            if (result.cloud_provider) {
+                console.log(`  ${chalk.gray('cloud   ')}  ${chalk.magenta(result.cloud_provider)}${result.cloud_session_id ? chalk.gray(' — ' + result.cloud_session_id.slice(0, 12)) : ''}`);
+            }
             if (result.after && result.after.length) {
                 console.log(`  ${chalk.gray('after   ')}  ${result.after.join(', ')}`);
             }
@@ -650,7 +863,7 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .action(async (team, opts) => {
         // Map friendly 'working' → internal 'running' for filter.
         const filter = opts.filter === 'working' ? 'running' : opts.filter;
-        const mgr = new AgentManager();
+        const mgr = mkManager();
         // No team given → drop into the picker (TTY) or fail clearly (script).
         if (!team) {
             const picked = await pickTeamOr(mgr, 'agents teams status');
@@ -678,59 +891,101 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             die(`Could not check on team ${team}: ${err.message}`);
         }
     });
+    // active — list every live teammate across every team, grouped by team.
+    teams
+        .command('active')
+        .description('List every teammate running right now, across all teams (PID-alive check).')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (opts) => {
+        const mgr = mkManager();
+        const running = await mgr.listRunning();
+        if (isJsonMode(opts)) {
+            console.log(JSON.stringify({ agents: running.map((a) => ({
+                    agent_id: a.agentId,
+                    team: a.taskName,
+                    name: a.name,
+                    agent_type: a.agentType,
+                    pid: a.pid,
+                    started_at: a.startedAt.toISOString(),
+                    cwd: a.cwd,
+                    version: a.version,
+                })) }, null, 2));
+            return;
+        }
+        if (running.length === 0) {
+            console.log(chalk.gray('No teammates are running right now.'));
+            return;
+        }
+        const byTeam = new Map();
+        for (const a of running) {
+            const arr = byTeam.get(a.taskName) || [];
+            arr.push(a);
+            byTeam.set(a.taskName, arr);
+        }
+        for (const [team, agents] of byTeam) {
+            console.log(chalk.bold(`Team ${chalk.cyan(team)}  ${chalk.gray(`(${agents.length} working)`)}`));
+            for (const a of agents) {
+                const ident = a.name || shortId(a.agentId);
+                const pidStr = a.pid ? chalk.yellow(`pid ${a.pid}`) : chalk.gray('pid ?');
+                const started = chalk.gray(relTime(a.startedAt.toISOString()));
+                console.log(`  ${chalk.magenta(padRight(fullName(a.agentType, a.version), 18))}  ${chalk.white(padRight(ident, 20))}  ${pidStr}  ${started}`);
+            }
+            console.log();
+        }
+        console.log(chalk.gray(`${running.length} teammate${running.length === 1 ? '' : 's'} running. See 'agents sessions --active' for the full cross-context view.`));
+    });
     // start — fire any staged teammates whose --after deps have all completed
     teams
         .command('start [team]')
-        .description('Launch any pending teammates whose --after dependencies are satisfied. Re-run to advance the DAG as teammates finish.')
+        .description('Launch any pending teammates whose --after dependencies are satisfied. Use --watch to keep draining the DAG as teammates finish and as new tasks are added mid-flight.')
         .option('--json', 'Output machine-readable JSON')
+        .option('--watch', 'Keep running: poll every --interval seconds, fire new waves, exit when the DAG drains.')
+        .option('--interval <seconds>', 'Seconds between waves in --watch mode (default 8)', '8')
+        .option('--max-waves <n>', 'Safety cap on waves in --watch mode (default 1000)', '1000')
         .action(async (team, opts) => {
-        const mgr = new AgentManager();
+        const mgr = mkManager();
+        wireCloudDispatcher(mgr);
         if (!team) {
             const picked = await pickTeamOr(mgr, 'agents teams start');
             if (!picked)
                 return;
             team = picked;
         }
-        const launched = await mgr.startReady(team);
-        // Also compute which teammates are still pending + why, so the user
-        // knows what's being waited on.
-        const all = await mgr.listByTask(team);
-        const stillPending = all.filter((a) => a.status === 'pending');
-        if (isJsonMode(opts)) {
-            console.log(JSON.stringify({
-                team,
-                launched: launched.map((a) => ({
-                    agent_id: a.agentId,
-                    name: a.name,
-                    after: a.after,
-                })),
-                still_pending: stillPending.map((a) => ({
-                    agent_id: a.agentId,
-                    name: a.name,
-                    after: a.after,
-                })),
-            }, null, 2));
+        if (!opts.watch) {
+            await runOneWave(mgr, team, Boolean(opts.json));
             return;
         }
-        if (launched.length === 0 && stillPending.length === 0) {
-            console.log(chalk.gray(`No pending teammates in team ${team}.`));
-            return;
+        const intervalMs = Math.max(1000, Number.parseInt(opts.interval, 10) * 1000 || 8000);
+        const maxWaves = Math.max(1, Number.parseInt(opts.maxWaves, 10) || 1000);
+        const json = isJsonMode(opts);
+        const result = await runSupervisor(mgr, {
+            team,
+            intervalMs,
+            maxWaves,
+            onWave: (s) => {
+                const ts = s.timestamp.slice(11, 19);
+                if (json) {
+                    console.log(JSON.stringify({
+                        wave: s.wave, ts, team: s.team, launched: s.launched.length,
+                        pending: s.pending, running: s.running, completed: s.completed, failed: s.failed,
+                    }));
+                    return;
+                }
+                console.log(`[${ts}] wave ${s.wave}  team ${chalk.cyan(s.team)}  ` +
+                    `launched=${chalk.green(s.launched.length)}  running=${chalk.yellow(s.running)}  ` +
+                    `pending=${chalk.blue(s.pending)}  done=${chalk.green(s.completed)}  ` +
+                    `failed=${s.failed > 0 ? chalk.red(s.failed) : '0'}`);
+            },
+        });
+        const elapsed = Math.floor(result.elapsed_ms / 1000);
+        if (result.stoppedBy === 'drained') {
+            console.log(chalk.green(`Factory drained in ${elapsed}s (${result.waves} waves).`));
         }
-        if (launched.length > 0) {
-            console.log(chalk.green(`Launched ${launched.length} teammate(s) in team ${chalk.cyan(team)}:`));
-            for (const a of launched) {
-                const who = fullName(a.agentType, a.version);
-                const h = a.name || shortId(a.agentId);
-                console.log(`  ${chalk.cyan(h)}  ${who}`);
-            }
+        else if (result.stoppedBy === 'max-waves') {
+            console.error(chalk.yellow(`Hit --max-waves=${maxWaves}; stopping. Re-run to continue.`));
         }
-        if (stillPending.length > 0) {
-            console.log();
-            console.log(chalk.gray(`Still pending (${stillPending.length}):`));
-            for (const a of stillPending) {
-                const h = a.name || shortId(a.agentId);
-                console.log(`  ${chalk.blue(h)}  ${chalk.gray('after')} ${a.after.join(', ')}`);
-            }
+        else if (result.stoppedBy === 'signal') {
+            console.error(chalk.yellow(`Stopped by signal after ${result.waves} waves.`));
         }
     });
     // remove
@@ -741,7 +996,7 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .option('--keep-logs', 'Keep their log files on disk (default: delete them)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, ref, opts) => {
-        const mgr = new AgentManager();
+        const mgr = mkManager();
         if (!team) {
             const { names } = await loadTeamRows(mgr);
             requireDestructiveArg({
@@ -805,7 +1060,7 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .option('--keep-logs', 'Keep all teammate logs on disk (default: delete them)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
-        const mgr = new AgentManager();
+        const mgr = mkManager();
         if (!team) {
             const { names } = await loadTeamRows(mgr);
             requireDestructiveArg({
@@ -857,7 +1112,7 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         // No teammate → picker in TTY, hard fail outside.
         let agentId;
         if (!ref) {
-            const mgr = new AgentManager();
+            const mgr = mkManager();
             const picked = await pickTeammateOr(mgr, 'agents teams logs');
             if (!picked)
                 return;
@@ -914,4 +1169,3 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         }
     });
 }
-//# sourceMappingURL=teams.js.map

package/dist/commands/usage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 2 minutes)
+ *   - codex:  parsed from latest session log's rate_limits event
+ *   - others: marked as "not exposed by CLI" (Gemini, OpenCode, Cursor, etc.
+ *     don't publish per-account usage today)
+ */
+import type { Command } from 'commander';
+export declare function registerUsageCommand(program: Command): void;

package/dist/commands/usage.js

@@ -0,0 +1,60 @@
+import chalk from 'chalk';
+import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, } from '../lib/agents.js';
+import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/versions.js';
+import { formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
+/** Agents whose CLI surfaces usage data we can read today. */
+const USAGE_SUPPORTED = new Set(['claude', 'codex']);
+export function registerUsageCommand(program) {
+    program
+        .command('usage [agent]')
+        .description('Show rate-limit / quota usage per agent')
+        .action(async (agentFilter) => {
+        const filter = agentFilter;
+        const targets = filter
+            ? [filter].filter((id) => ALL_AGENT_IDS.includes(id))
+            : ALL_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
+        if (targets.length === 0) {
+            console.log(chalk.gray('No agents installed. Run `agents add <agent>` first.'));
+            return;
+        }
+        const sections = await Promise.all(targets.map(async (agentId) => renderAgentUsage(agentId)));
+        console.log(sections.filter(Boolean).join('\n\n'));
+    });
+}
+async function renderAgentUsage(agentId) {
+    const cfg = AGENTS[agentId];
+    const heading = agentLabel(agentId);
+    if (!USAGE_SUPPORTED.has(agentId)) {
+        return [
+            `${heading}`,
+            `  ${chalk.dim(`${cfg.name} CLI does not publish usage data.`)}`,
+        ].join('\n');
+    }
+    const versions = listInstalledVersions(agentId);
+    const version = getGlobalDefault(agentId) || versions[0];
+    if (!version) {
+        return [`${heading}`, `  ${chalk.dim('No version installed.')}`].join('\n');
+    }
+    const home = getVersionHomePath(agentId, version);
+    const info = await getAccountInfo(agentId, home);
+    if (!info.usageKey && !info.accountKey) {
+        return [`${heading}`, `  ${chalk.dim('Not signed in.')}`].join('\n');
+    }
+    const usage = await getUsageInfoForIdentity({
+        agentId,
+        home,
+        info,
+        cliVersion: null,
+    });
+    const lines = [heading];
+    if (info.email)
+        lines.push(`  ${chalk.dim(info.email)}`);
+    const section = formatUsageSection(usage);
+    if (section.length === 0) {
+        lines.push(`  ${chalk.dim('No usage data available right now.')}`);
+    }
+    else {
+        lines.push(...section);
+    }
+    return lines.join('\n');
+}

package/dist/commands/utils.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Shared utilities for command implementations.
+ *
+ * Small helpers used across multiple commands: prompt cancellation detection,
+ * table formatting, spinner management, and platform-specific workarounds.
+ */
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */
@@ -36,4 +42,3 @@ export declare function parseCommaSeparatedList(value: string | undefined): stri
  * Format a path for display, using ~ for home directory
  */
 export declare function formatPath(fullPath: string, cwd?: string): string;
-//# sourceMappingURL=utils.d.ts.map

package/dist/commands/utils.js

@@ -1,3 +1,9 @@
+/**
+ * Shared utilities for command implementations.
+ *
+ * Small helpers used across multiple commands: prompt cancellation detection,
+ * table formatting, spinner management, and platform-specific workarounds.
+ */
 import * as os from 'os';
 import { spawnSync } from 'child_process';
 import chalk from 'chalk';
@@ -97,4 +103,3 @@ export function formatPath(fullPath, cwd) {
     }
     return fullPath;
 }
-//# sourceMappingURL=utils.js.map