@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/routines.test-fixture.d.ts

@@ -1,52 +1,20 @@
 import { describe } from 'vitest';
 import { spawnSync, spawn } from 'child_process';
-/**
- * Shared fixture for the routines.*.test.ts suite slices (RUSH-2819).
- *
- * routines.test.ts was one 2,249-line file measured at ~194s of test time —
- * one of the slowest files in CI, serializing an entire fork while every
- * other selected file finished. The suite is split into topical slices so
- * vitest's per-file fork parallelism can spread the subprocess-heavy tests
- * across workers; the helpers each slice shares live here.
- *
- * Every test spawns the real CLI (`node --import tsx src/index.ts routines ...`)
- * against an isolated mkdtemp HOME — no live ~/.agents state, no mocks, no
- * imported writeJob/readJob. Modeled on `routines-webhook.test.ts`.
- */
 export declare const REPO_ROOT: string;
 export declare const TSX_IMPORT: string;
 export declare const CLI_ENTRYPOINT: string;
 export declare const describeRoutines: typeof describe.skip;
-/** Provision an isolated HOME with agents.yaml, .system/.git, and optional routines + device registry. */
 export declare function makeHome(opts?: {
     jobs?: Record<string, unknown>[];
     projectJobs?: Record<string, unknown>[];
     registry?: Record<string, unknown>;
     deviceRoutines?: Record<string, string[]>;
-    /** Full mkdtemp prefix override — the daemon harness scopes its leak sweep by it. */
     tmpPrefix?: string;
 }): string;
-/** Run `agents routines <args>` against an isolated HOME. */
 export declare function run(home: string, args: string[], extraEnv?: Record<string, string>, cwd?: string): ReturnType<typeof spawnSync>;
 export declare function readRoutineYaml(home: string, name: string): Record<string, unknown> | null;
 export declare function writeRunMeta(home: string, jobName: string, runId: string, meta: Record<string, unknown>): void;
 export declare function isProcessAlive(pid: number): boolean;
-/**
- * Per-file isolated-daemon harness (RUSH-2367, RUSH-2819). Each slice that
- * spawns a real `__daemon-run` process against an isolated HOME calls this
- * once at module scope and registers its own leak detector — the tracked pid
- * set MUST be private to the file that spawned it, since vitest's per-file
- * fork isolation means the leak sweep only ever needs to answer for what THIS
- * file started.
- *
- * `fileSlug` MUST be unique per test file: it names the mkdtemp prefix
- * `makeDaemonHome` uses, and the CI leak sweep matches ONLY that prefix.
- * The suite slices run in parallel forks, so a sweep over the shared
- * `agents-routines-test-` prefix would catch a sibling file's still-running
- * daemon and kill it mid-test — exactly what failed the first CI run of the
- * RUSH-2819 split (run 32552954164: add's sweep killed a live daemon whose
- * HOME belonged to a concurrently running slice).
- */
 export declare function createDaemonHarness(fileSlug: string): {
     startIsolatedDaemon: (home: string) => {
         child: ReturnType<typeof spawn>;
@@ -80,7 +48,5 @@ export declare const registry: {
 };
 export declare function readDeviceRoutines(home: string, device: string): string[];
 export declare function writeDeviceRoutines(home: string, device: string, routines: string[]): void;
-/** Write a minimal project YAML so listProjectDefs() sees it. */
 export declare function writeProject(home: string, name: string): void;
-/** Env that points the projects dir at the isolated home. */
 export declare function projectsEnv(home: string): Record<string, string>;

package/dist/commands/routines.test-fixture.js

@@ -6,30 +6,11 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'module';
-/**
- * Shared fixture for the routines.*.test.ts suite slices (RUSH-2819).
- *
- * routines.test.ts was one 2,249-line file measured at ~194s of test time —
- * one of the slowest files in CI, serializing an entire fork while every
- * other selected file finished. The suite is split into topical slices so
- * vitest's per-file fork parallelism can spread the subprocess-heavy tests
- * across workers; the helpers each slice shares live here.
- *
- * Every test spawns the real CLI (`node --import tsx src/index.ts routines ...`)
- * against an isolated mkdtemp HOME — no live ~/.agents state, no mocks, no
- * imported writeJob/readJob. Modeled on `routines-webhook.test.ts`.
- */
 export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const require = createRequire(import.meta.url);
-// `--import` takes a module specifier, not a path: a bare Windows path like
-// `D:\a\...\tsx\dist\loader.mjs` is parsed as a URL with protocol 'd:' and the
-// child dies with ERR_UNSUPPORTED_ESM_URL_SCHEME before running the CLI. Same
-// pattern as sessions.test.ts:21.
 export const TSX_IMPORT = pathToFileURL(require.resolve('tsx')).href;
 export const CLI_ENTRYPOINT = path.join(REPO_ROOT, 'src', 'index.ts');
-// win32: subprocess CLI + process-group signals / path spawn assumptions (RUSH-2215).
 export const describeRoutines = process.platform === 'win32' ? describe.skip : describe;
-/** Provision an isolated HOME with agents.yaml, .system/.git, and optional routines + device registry. */
 export function makeHome(opts = {}) {
     const home = fs.mkdtempSync(opts.tmpPrefix ?? path.join(os.tmpdir(), 'agents-routines-test-'));
     const agentsDir = path.join(home, '.agents');
@@ -57,7 +38,6 @@ export function makeHome(opts = {}) {
     }
     return home;
 }
-/** Run `agents routines <args>` against an isolated HOME. */
 export function run(home, args, extraEnv = {}, cwd = REPO_ROOT) {
     return spawnSync('node', ['--import', TSX_IMPORT, CLI_ENTRYPOINT, 'routines', ...args], {
         cwd,
@@ -65,9 +45,6 @@ export function run(home, args, extraEnv = {}, cwd = REPO_ROOT) {
             ...process.env,
             HOME: home,
             USERPROFILE: home,
-            // Point the device registry at this test's home (RUSH-2042): getDevicesDir()
-            // reads AGENTS_DEVICES_DIR, and the parent vitest fork exports its own via
-            // setup.ts — override it so the child reads the registry makeHome() wrote.
             AGENTS_DEVICES_DIR: path.join(home, '.agents', '.history', 'devices'),
             AGENTS_SKIP_MIGRATION: '1',
             ...extraEnv,
@@ -107,35 +84,9 @@ export function isProcessAlive(pid) {
         return false;
     }
 }
-/**
- * Per-file isolated-daemon harness (RUSH-2367, RUSH-2819). Each slice that
- * spawns a real `__daemon-run` process against an isolated HOME calls this
- * once at module scope and registers its own leak detector — the tracked pid
- * set MUST be private to the file that spawned it, since vitest's per-file
- * fork isolation means the leak sweep only ever needs to answer for what THIS
- * file started.
- *
- * `fileSlug` MUST be unique per test file: it names the mkdtemp prefix
- * `makeDaemonHome` uses, and the CI leak sweep matches ONLY that prefix.
- * The suite slices run in parallel forks, so a sweep over the shared
- * `agents-routines-test-` prefix would catch a sibling file's still-running
- * daemon and kill it mid-test — exactly what failed the first CI run of the
- * RUSH-2819 split (run 32552954164: add's sweep killed a live daemon whose
- * HOME belonged to a concurrently running slice).
- */
 export function createDaemonHarness(fileSlug) {
     const homePrefix = path.join(os.tmpdir(), `agents-routines-${fileSlug}-`);
-    /**
-     * Every daemon pid spawned via `startIsolatedDaemon` in this file, live for as
-     * long as `stopIsolatedDaemon` has not yet reaped it. Backstops the per-test
-     * try/finally: this file's `afterAll` (registered via `registerLeakDetector`)
-     * asserts the set is empty and force-kills + fails the suite on anything left
-     * in it — a leaked real daemon process is exactly the RUSH-2367 bug (three
-     * left running for up to 3.5 days on a fleet box, invisible to `agents daemon`
-     * because each served its own fixture HOME/registry).
-     */
     const trackedDaemonPids = new Set();
-    /** Start the real scheduler foreground process against an isolated HOME. */
     function startIsolatedDaemon(home) {
         const child = spawn('node', ['--import', 'tsx', 'src/index.ts', '__daemon-run'], {
             cwd: REPO_ROOT,
@@ -143,16 +94,8 @@ export function createDaemonHarness(fileSlug) {
                 ...process.env,
                 HOME: home,
                 USERPROFILE: home,
-                // Without this override the daemon inherits the parent vitest process's real
-                // AGENTS_HISTORY_DIR (pointing at ~/.agents/.history). The daemon's SIGTERM
-                // sweep then reads live session records from the production history directory
-                // and kills real tmux-wrapped processes every five-minute tick (RUSH-2545).
                 AGENTS_HISTORY_DIR: path.join(home, '.agents', '.history'),
                 AGENTS_SKIP_MIGRATION: '1',
-                // PHNX-2545 test-home tripwire: name the isolated home this daemon must
-                // resolve its state dir under. If the HOME override above ever failed to
-                // reach the child, runDaemon()'s assertTestDaemonHome() refuses to boot
-                // instead of ticking its scheduler against the operator's real host.
                 AGENTS_DAEMON_TEST_HOME: home,
             },
             detached: true,
@@ -177,7 +120,6 @@ export function createDaemonHarness(fileSlug) {
         });
         return { child, pidPromise };
     }
-    /** Terminate a daemon process started by startIsolatedDaemon and wait for it to exit. */
     async function stopIsolatedDaemon(child) {
         const pid = child.pid;
         try {
@@ -203,7 +145,6 @@ export function createDaemonHarness(fileSlug) {
                     }
                 }
                 catch {
-                    // already gone
                 }
             };
             signal('SIGTERM');
@@ -216,33 +157,6 @@ export function createDaemonHarness(fileSlug) {
                 trackedDaemonPids.delete(pid);
         }
     }
-    /**
-     * Suite-level leak detector (RUSH-2367). Every per-test try/finally above
-     * already reaps its own daemon on success, failure, or a thrown assertion —
-     * but nothing in JS runs if the whole vitest worker is killed externally
-     * before reaching `finally`, which is what actually produced three real
-     * orphaned daemons found alive on a fleet box for up to 3.5 days: their
-     * fixture HOME dirs still existed (the `finally`'s `fs.rmSync` never ran
-     * either), so no amount of in-test cleanup logic would have caught it. This
-     * is the second line of defense, not a substitute for the self-terminate
-     * guard in the daemon itself (`runDaemon`'s state-dir check).
-     *
-     * Two checks, after every test in this file has run:
-     *  1. Always: nothing THIS run spawned via `startIsolatedDaemon` may still be
-     *     alive — `trackedDaemonPids` is only ever non-empty here if a bug (not
-     *     an external kill) let one slip past its own test's `finally`.
-     *  2. CI only: sweep for any OTHER live `__daemon-run` process whose HOME
-     *     sits under THIS FILE's unique `agents-routines-<fileSlug>-` prefix —
-     *     a leak from a previous interrupted run of this same file. Scoped to
-     *     the per-file prefix because sibling slices run in parallel forks and
-     *     legitimately have live daemons under their own prefixes. POSIX-only
-     *     (`/proc`); best-effort and skipped where `/proc` is unavailable
-     *     (macOS CI legs).
-     *
-     * Either check force-kills what it finds and fails the suite — a silent
-     * "still running, we'll get it next time" is exactly how the original three
-     * accumulated.
-     */
     function registerLeakDetector() {
         afterAll(() => {
             const leaks = [];
@@ -250,11 +164,11 @@ export function createDaemonHarness(fileSlug) {
                 try {
                     process.kill(-pid, 'SIGKILL');
                 }
-                catch { /* already gone, or never its own group leader */ }
+                catch { }
                 try {
                     process.kill(pid, 'SIGKILL');
                 }
-                catch { /* already gone */ }
+                catch { }
             };
             for (const pid of trackedDaemonPids) {
                 if (isProcessAlive(pid)) {
@@ -269,7 +183,7 @@ export function createDaemonHarness(fileSlug) {
                 try {
                     psOut = execFileSync('ps', ['-eo', 'pid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
                 }
-                catch { /* ps unavailable — nothing to sweep */ }
+                catch { }
                 for (const line of psOut.split('\n')) {
                     const m = line.trim().match(/^(\d+)\s+(.*)$/);
                     if (!m)
@@ -288,7 +202,7 @@ export function createDaemonHarness(fileSlug) {
                     }
                     catch {
                         continue;
-                    } // /proc unreadable (macOS, permissions) — best-effort only
+                    }
                     if (!home || !home.startsWith(prefix))
                         continue;
                     leaks.push(`pid ${pid} HOME=${home} (leaked from a previous interrupted run of this file)`);
@@ -301,7 +215,6 @@ export function createDaemonHarness(fileSlug) {
             }
         });
     }
-    /** makeHome under this file's unique prefix — REQUIRED for any home a daemon runs against. */
     function makeDaemonHome(opts = {}) {
         return makeHome({ ...opts, tmpPrefix: homePrefix });
     }
@@ -312,11 +225,7 @@ export const baseJob = {
     schedule: '0 3 * * *',
     agent: 'claude',
     prompt: 'noop',
-    // Agent routines now need an execution anchor to activate (RUSH-2290); home
-    // is a valid one and keeps these device/eligibility fixtures ready.
     cwd: '~',
-    // Legacy fixture state: tests that specifically cover the new manifest model
-    // materialize a device document below.
     enabled: true,
 };
 export const registry = {
@@ -335,16 +244,11 @@ export function writeDeviceRoutines(home, device, routines) {
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(path.join(dir, 'agents.yaml'), yaml.stringify({ routines }));
 }
-// ---------------------------------------------------------------------------
-// Project-tagging tests (--project / --all-projects / list --json projectGroup)
-// ---------------------------------------------------------------------------
-/** Write a minimal project YAML so listProjectDefs() sees it. */
 export function writeProject(home, name) {
     const dir = path.join(home, '.agents', 'projects');
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(path.join(dir, `${name}.yaml`), yaml.stringify({ name }));
 }
-/** Env that points the projects dir at the isolated home. */
 export function projectsEnv(home) {
     return { AGENTS_PROJECTS_DIR: path.join(home, '.agents', 'projects') };
 }

package/dist/commands/rules.d.ts

@@ -1,11 +1,2 @@
-/**
- * Rules management commands for controlling agent behavior via persistent instructions.
- *
- * Implements `agents rules` -- list, add, view, and remove markdown rule files
- * (AGENTS.md, CLAUDE.md, .cursorrules, etc.) that guide agent behavior across
- * sessions. Central storage lives in ~/.agents/rules/ and rules are synced
- * to individual version homes.
- */
 import type { Command } from 'commander';
-/** Register the `agents rules` command tree (list, add, view, remove). */
 export declare function registerRulesCommands(program: Command): void;

package/dist/commands/rules.js

@@ -14,7 +14,6 @@ import { recordVersionResources, getActiveRulesPreset, setActiveRulesPreset } fr
 import { discoverRulesLayers } from '../lib/rules/compose.js';
 import * as yaml from 'yaml';
 import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, requireDestructiveArg, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
-/** Register the `agents rules` command tree (list, add, view, remove). */
 export function registerRulesCommands(program) {
     const rulesCmd = program
         .command('rules')
@@ -177,7 +176,6 @@ Project rules & @-imports:
                 const projectInstr = installed.find((i) => i.scope === 'project');
                 const hasUser = userInstr?.exists;
                 const hasProject = projectInstr?.exists;
-                // Skip agents with nothing to show
                 if (!hasUser && !hasProject)
                     continue;
                 console.log(`  ${chalk.bold(agentLabel(aid))}:`);
@@ -460,8 +458,6 @@ Examples:
 `)
         .action((agentArg) => {
         if (!agentArg) {
-            // Only list agents that actually have a rules file installed — avoids
-            // suggesting agents the user hasn't touched.
             const candidates = MANAGED_AGENT_IDS.filter((id) => instructionsExists(id));
             requireDestructiveArg({
                 argName: 'agent',
@@ -548,7 +544,6 @@ Examples:
                 console.log(chalk.gray(`Installed: ${installed.join(', ') || 'none'}`));
                 process.exit(1);
             }
-            // Discover available presets across layers (highest-priority defines, lowers union in).
             const layers = discoverRulesLayers();
             const presetSet = new Set();
             for (const layer of layers) {
@@ -560,7 +555,7 @@ Examples:
                     for (const name of Object.keys(parsed?.presets || {}))
                         presetSet.add(name);
                 }
-                catch { /* malformed yaml — skip */ }
+                catch { }
             }
             const presets = Array.from(presetSet).sort();
             if (presets.length === 0) {

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

@@ -4,15 +4,9 @@ interface RunAccountChoice {
     name: string;
     value: string;
     disabled?: string;
-    /** Can serve a run right now: signed in, authenticated, and under quota. */
     ready: boolean;
-    /**
-     * Selectable, but picking it launches the harness so you can authenticate
-     * first (RUSH-2334). Mutually exclusive with `ready`; never `disabled`.
-     */
     signInRequired: boolean;
 }
-/** One named account row for `agents accounts default` (reuses this picker's layout). */
 export interface SwitchAccountRow {
     accountName: string;
     kind: 'provider' | 'native';
@@ -20,77 +14,24 @@ export interface SwitchAccountRow {
     current: boolean;
     candidate: RotateCandidate | null;
 }
-/** Human-readable remaining capacity for every window the provider exposes. */
 export declare function formatAccountLimits(candidate: RotateCandidate): string;
-/** Build aligned picker rows with usable accounts first and unsafe rows disabled. */
 export declare function buildRunAccountChoices(candidates: RotateCandidate[], globalDefault: string | null): RunAccountChoice[];
-/**
- * Aligned picker rows for `accounts default`. Same columns as the run picker
- * (identity, status, limits) but the value is the named account to make default.
- * Rows stay selectable: setting a default is not a launch.
- */
 export declare function buildSwitchAccountChoices(rows: SwitchAccountRow[]): RunAccountChoice[];
-/**
- * Prompt for the named account that becomes this harness's default.
- * A cancelled picker writes nothing.
- */
 export declare function pickSwitchAccount(agent: AgentId, rows: SwitchAccountRow[]): Promise<string | null>;
-/**
- * The two-condition "human-facing" gate behind signInLaunchDecision and
- * noVerifiedUsageDecision: a real TTY and no `--json`. Off a TTY nobody can
- * answer a prompt, and `--json` marks a MACHINE consumer, which must never be
- * handed a picker or dropped into a login TUI. Mirrors the canonical
- * `Surface.interactive = tty && !json` in `commands/utils.ts`.
- */
 export declare function isHumanFacingRun(input: {
     tty: boolean;
     json: boolean;
 }): boolean;
-/**
- * Whether a zero-healthy run may recover by launching for a login, or must keep
- * failing loud. Three inputs, all of which have to hold:
- *
- * - `recoverable` — at least one excluded account is only auth-blocked. An
- *   all-throttled set is never launched (RUSH-2132): only a window reset clears it.
- * - `tty` — a login needs a human present; off a TTY nobody can complete one.
- * - `json` — `--json` marks a MACHINE consumer, which must never be handed a
- *   picker or dropped into a login TUI. This mirrors the canonical
- *   `Surface.interactive = tty && !json` in `commands/utils.ts`; a `--json` caller
- *   gets the parseable fail-loud error instead.
- */
 export declare function signInLaunchDecision(input: {
     recoverable: number;
     tty: boolean;
     json: boolean;
 }): 'launch' | 'fail-loud';
-/**
- * How a `balanced`/`available` run reacts when every account's usage is stale and
- * none is verified (PHNX-2526). A human present at a real terminal gets the
- * account `picker` — they can choose knowing the numbers are stale — while every
- * unattended shape (`--headless`, `--json`, or no TTY) `fail-loud`s with
- * NO_VERIFIED_USAGE rather than silently guess on a stale snapshot. `headless`
- * joins the gate because a routine/machine dispatch can carry a TTY yet have no
- * human to answer a picker; the split mirrors `signInLaunchDecision`.
- */
 export declare function noVerifiedUsageDecision(input: {
     tty: boolean;
     json: boolean;
     headless: boolean;
 }): 'picker' | 'fail-loud';
-/**
- * Choose which installed version to launch so the user can authenticate, when a
- * strategy found zero healthy accounts but at least one is merely signed out
- * (RUSH-2334). Returns the version to launch, or null if the user cancelled.
- *
- * A single candidate does NOT prompt — a one-item picker is pure noise, and the
- * only thing to decide has one answer. Several candidates fall through to the
- * normal account picker, which shows every account with its state so the choice
- * is informed (throttled rows stay disabled there).
- *
- * Callers MUST have already confirmed an interactive terminal: off a TTY there
- * is nobody to complete the login, and the run should fail loud instead.
- */
 export declare function pickSignInLaunchVersion(agent: AgentId, recoverable: RotateCandidate[], quiet?: boolean): Promise<string | null>;
-/** Prompt for one safe installed account/version. A cancelled picker launches nothing. */
 export declare function pickRunAccountCandidate(agent: AgentId): Promise<RotateCandidate | null>;
 export {};

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

@@ -18,7 +18,6 @@ function formatPercent(value) {
     const rounded = Math.round(value * 10) / 10;
     return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
 }
-/** Human-readable remaining capacity for every window the provider exposes. */
 export function formatAccountLimits(candidate) {
     const windows = candidate.usageSnapshot?.windows;
     if (!windows || windows.length === 0)
@@ -33,16 +32,6 @@ export function formatAccountLimits(candidate) {
     })
         .join(' · ');
 }
-/**
- * Why a row cannot be picked. Only a THROTTLE disables a row: the account is
- * signed in and out of capacity, so launching it just hammers an exhausted
- * account (RUSH-2132) and nothing the user does at this prompt helps.
- *
- * An AUTH exclusion (`signed_out` / `revoked`) is deliberately NOT disabled —
- * the harness's own TUI is the login surface, so picking that row and launching
- * is the only way to sign in through agents-cli. Disabling it left a fully
- * logged-out harness with no reachable account at all (RUSH-2334).
- */
 function disabledReason(candidate, readiness) {
     if (readiness.ready)
         return undefined;
@@ -60,7 +49,6 @@ function disabledReason(candidate, readiness) {
         ? `${exhausted.join(' and ')} ${exhausted.length === 1 ? 'limit' : 'limits'} reached`
         : 'rate limit reached';
 }
-/** Build aligned picker rows with usable accounts first and unsafe rows disabled. */
 export function buildRunAccountChoices(candidates, globalDefault) {
     const rows = candidates.map((candidate) => {
         const readiness = readinessFromCandidate(candidate);
@@ -83,8 +71,6 @@ export function buildRunAccountChoices(candidates, globalDefault) {
             candidate,
             account: marked,
             verdict,
-            // An auth-blocked row shows what picking it DOES; its quota is moot until
-            // there is a credential to spend it with.
             limits: !readiness.ready && readiness.reason === 'revoked'
                 ? 'launch to re-authenticate'
                 : !readiness.ready && readiness.reason === 'signed_out'
@@ -95,8 +81,6 @@ export function buildRunAccountChoices(candidates, globalDefault) {
             signInRequired,
         };
     });
-    // Ready accounts first, then the ones a login would unlock (actionable), then
-    // the throttled rows the user can do nothing about at this prompt.
     const rank = (row) => row.ready ? 0 : row.signInRequired ? 1 : 2;
     rows.sort((a, b) => {
         if (rank(a) !== rank(b))
@@ -150,11 +134,6 @@ function switchRowStatus(row) {
             : formatAccountLimits(row.candidate);
     return { status, limits, ready: readiness.ready };
 }
-/**
- * Aligned picker rows for `accounts default`. Same columns as the run picker
- * (identity, status, limits) but the value is the named account to make default.
- * Rows stay selectable: setting a default is not a launch.
- */
 export function buildSwitchAccountChoices(rows) {
     const rendered = rows.map((row) => {
         const { status, limits, ready } = switchRowStatus(row);
@@ -177,10 +156,6 @@ export function buildSwitchAccountChoices(rows) {
         signInRequired: false,
     }));
 }
-/**
- * Prompt for the named account that becomes this harness's default.
- * A cancelled picker writes nothing.
- */
 export async function pickSwitchAccount(agent, rows) {
     if (!isInteractiveTerminal()) {
         requireInteractiveSelection(`Selecting a ${agentLabel(agent)} account`, [
@@ -204,58 +179,17 @@ export async function pickSwitchAccount(agent, rows) {
         throw err;
     }
 }
-/**
- * The two-condition "human-facing" gate behind signInLaunchDecision and
- * noVerifiedUsageDecision: a real TTY and no `--json`. Off a TTY nobody can
- * answer a prompt, and `--json` marks a MACHINE consumer, which must never be
- * handed a picker or dropped into a login TUI. Mirrors the canonical
- * `Surface.interactive = tty && !json` in `commands/utils.ts`.
- */
 export function isHumanFacingRun(input) {
     return input.tty && !input.json;
 }
-/**
- * Whether a zero-healthy run may recover by launching for a login, or must keep
- * failing loud. Three inputs, all of which have to hold:
- *
- * - `recoverable` — at least one excluded account is only auth-blocked. An
- *   all-throttled set is never launched (RUSH-2132): only a window reset clears it.
- * - `tty` — a login needs a human present; off a TTY nobody can complete one.
- * - `json` — `--json` marks a MACHINE consumer, which must never be handed a
- *   picker or dropped into a login TUI. This mirrors the canonical
- *   `Surface.interactive = tty && !json` in `commands/utils.ts`; a `--json` caller
- *   gets the parseable fail-loud error instead.
- */
 export function signInLaunchDecision(input) {
     const humanPresent = isHumanFacingRun(input);
     return input.recoverable > 0 && humanPresent ? 'launch' : 'fail-loud';
 }
-/**
- * How a `balanced`/`available` run reacts when every account's usage is stale and
- * none is verified (PHNX-2526). A human present at a real terminal gets the
- * account `picker` — they can choose knowing the numbers are stale — while every
- * unattended shape (`--headless`, `--json`, or no TTY) `fail-loud`s with
- * NO_VERIFIED_USAGE rather than silently guess on a stale snapshot. `headless`
- * joins the gate because a routine/machine dispatch can carry a TTY yet have no
- * human to answer a picker; the split mirrors `signInLaunchDecision`.
- */
 export function noVerifiedUsageDecision(input) {
     const humanPresent = input.tty && !input.json && !input.headless;
     return humanPresent ? 'picker' : 'fail-loud';
 }
-/**
- * Choose which installed version to launch so the user can authenticate, when a
- * strategy found zero healthy accounts but at least one is merely signed out
- * (RUSH-2334). Returns the version to launch, or null if the user cancelled.
- *
- * A single candidate does NOT prompt — a one-item picker is pure noise, and the
- * only thing to decide has one answer. Several candidates fall through to the
- * normal account picker, which shows every account with its state so the choice
- * is informed (throttled rows stay disabled there).
- *
- * Callers MUST have already confirmed an interactive terminal: off a TTY there
- * is nobody to complete the login, and the run should fail loud instead.
- */
 export async function pickSignInLaunchVersion(agent, recoverable, quiet = false) {
     if (recoverable.length === 0)
         return null;
@@ -274,7 +208,6 @@ export async function pickSignInLaunchVersion(agent, recoverable, quiet = false)
     }
     return only.version;
 }
-/** Prompt for one safe installed account/version. A cancelled picker launches nothing. */
 export async function pickRunAccountCandidate(agent) {
     if (!isInteractiveTerminal()) {
         requireInteractiveSelection(`Selecting a ${agentLabel(agent)} account`, [
@@ -287,10 +220,6 @@ export async function pickRunAccountCandidate(agent) {
         throw new Error(`No installed ${agentLabel(agent)} versions are available. Run: agents add ${agent}@latest`);
     }
     const choices = buildRunAccountChoices(candidates, getGlobalDefault(agent));
-    // "Selectable" is broader than "ready": an auth-blocked row is pickable so the
-    // launch can carry you into the harness's login (RUSH-2334). Only offer the
-    // bail-out row when literally nothing can be chosen — i.e. every account is
-    // throttled, which no amount of signing in fixes.
     const hasSelectableAccount = choices.some((choice) => !choice.disabled);
     const needsSignIn = choices.some((choice) => choice.signInRequired);
     const promptChoices = choices.map(({ ready: _ready, signInRequired: _signInRequired, ...choice }) => choice);

package/dist/commands/run-broadcast.d.ts

@@ -1,9 +1,3 @@
-/**
- * `agents run --broadcast` — run the same task/prompt across an agent × model
- * matrix (formerly `agents bench`).
- *
- * Task definitions live under cli/bench/tasks/<id>/task.json.
- */
 interface BroadcastOpts {
     listTasks?: boolean;
     results?: string | true;
@@ -11,12 +5,9 @@ interface BroadcastOpts {
     model?: string;
     concurrency?: string;
     json?: boolean;
-    /** Comma-separated agents from the run [agent] positional when broadcasting. */
     agentsCsv?: string;
     prompt?: string;
-    /** When true, run the matrix (not just list/results). */
     requireRun?: boolean;
 }
-/** Handle --broadcast / --list-tasks / --results on `agents run`. Always completes the path. */
 export declare function handleBroadcast(opts: BroadcastOpts): Promise<void>;
 export {};

package/dist/commands/run-broadcast.js

@@ -1,9 +1,3 @@
-/**
- * `agents run --broadcast` — run the same task/prompt across an agent × model
- * matrix (formerly `agents bench`).
- *
- * Task definitions live under cli/bench/tasks/<id>/task.json.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
@@ -31,7 +25,6 @@ function renderResult(result) {
     for (const cell of result.cells)
         console.log(`${cell.status === 'passed' ? 'PASS' : 'FAIL'}  ${cell.agent}${cell.model ? `/${cell.model}` : ''}  ${cell.wall_ms} ms  exit ${cell.exit ?? 'spawn-error'}`);
 }
-/** Handle --broadcast / --list-tasks / --results on `agents run`. Always completes the path. */
 export async function handleBroadcast(opts) {
     if (opts.listTasks) {
         const tasks = taskIds();

package/dist/commands/run-cloud.d.ts

@@ -1,26 +1,11 @@
 import type { Command } from 'commander';
 import type { CloudProvider } from '../lib/cloud/types.js';
-/** Error type for run --cloud validation failures (exit 1, red message). */
 export declare class RunCloudError extends Error {
     constructor(message: string);
 }
-/** Flags the user passed that cannot ride a cloud placement. */
 export declare function runCloudConflicts(options: Record<string, unknown>): string[];
-/** Cloud-only flags passed without the --cloud placement. */
 export declare function cloudFlagsWithoutCloud(options: Record<string, unknown>): string[];
-/** Agents that route to a native cloud provider (the registry's truth). */
 export declare function cloudCapableAgentIds(): string[];
-/**
- * Resolve the cloud provider for a run: explicit --provider wins, else the
- * agent's native cloud. An agent with no native cloud fails loud with the
- * capable list — never a silent ride onto the configured default.
- */
 export declare function resolveRunCloudProvider(agentId: string, explicitProvider?: string): CloudProvider;
-/** Validate the agent half of `agents run <agent> --cloud` and return the registry id. */
 export declare function resolveRunCloudAgent(agentSpec: string): string;
-/**
- * Handle `agents run <agent> [prompt] --cloud`. Validation lives in the
- * exported helpers above (unit-tested); this wires them to the shared
- * dispatch core and dies on any validation failure.
- */
 export declare function handleRunCloud(agentSpec: string, prompt: string | undefined, options: Record<string, unknown>, command: Command): Promise<void>;