@phnx-labs/agents-cli 1.21.3 → 1.22.1

package/dist/lib/project-status.d.ts

@@ -54,6 +54,13 @@ export interface ProjectSessionRollup {
  * with the full definition list to show zero-agent projects.
  */
 export declare function rollupSessionsByProject(defs: ProjectDef[], sessions: ActiveSession[]): Map<string, ProjectSessionRollup>;
+/**
+ * True when a session's status means it is over. Exported so the card can keep
+ * the `agents` roster to live sessions: the headline and the `dead` row already
+ * separate the two, and a roster that reads `crashed ×25` beside `23 live`
+ * makes the reader distrust both numbers.
+ */
+export declare function isDeadStatus(status: string): boolean;
 /** Live vs finished sessions on a project. */
 export interface LiveDeadSplit {
     live: number;

package/dist/lib/project-status.js

@@ -93,6 +93,15 @@ export function rollupSessionsByProject(defs, sessions) {
  * that are running unattended.
  */
 const DEAD_STATUSES = new Set(['closed', 'crashed']);
+/**
+ * True when a session's status means it is over. Exported so the card can keep
+ * the `agents` roster to live sessions: the headline and the `dead` row already
+ * separate the two, and a roster that reads `crashed ×25` beside `23 live`
+ * makes the reader distrust both numbers.
+ */
+export function isDeadStatus(status) {
+    return DEAD_STATUSES.has(status);
+}
 /**
  * Split a rollup's sessions into what is working and what is wreckage.
  *

package/dist/lib/projects.d.ts

@@ -5,8 +5,17 @@
  * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
  * This module adds editable definitions on top: one YAML file per project under
  * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
- * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
- * machines for free via `agents push/pull`). A defined project can name itself
+ * `monitors/`, and `teams/` dirs in the user repo.
+ *
+ * That location makes definitions SYNCABLE, not automatically synced: they ride
+ * the user repo only once they are committed to it, via `agents repo push user`
+ * (`agents push` was removed). Until then the directory is untracked, and a
+ * reconcile that cleans the working tree deletes it — observed twice on one
+ * machine, taking four definitions with it each time. The recovery is an
+ * orphaned `chore(local): save …-sync drift` commit, which is not a guarantee:
+ * unreachable objects are collected. Say "commit them" rather than "for free".
+ *
+ * A defined project can name itself
  * independently of its folder, bind more than one repo, pin a monorepo subpath,
  * describe context subdirectories an agent should start from, carry a Linear
  * link and external integrations, and set an explicit default path.

package/dist/lib/projects.js

@@ -5,8 +5,17 @@
  * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
  * This module adds editable definitions on top: one YAML file per project under
  * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
- * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
- * machines for free via `agents push/pull`). A defined project can name itself
+ * `monitors/`, and `teams/` dirs in the user repo.
+ *
+ * That location makes definitions SYNCABLE, not automatically synced: they ride
+ * the user repo only once they are committed to it, via `agents repo push user`
+ * (`agents push` was removed). Until then the directory is untracked, and a
+ * reconcile that cleans the working tree deletes it — observed twice on one
+ * machine, taking four definitions with it each time. The recovery is an
+ * orphaned `chore(local): save …-sync drift` commit, which is not a guarantee:
+ * unreachable objects are collected. Say "commit them" rather than "for free".
+ *
+ * A defined project can name itself
  * independently of its folder, bind more than one repo, pin a monorepo subpath,
  * describe context subdirectories an agent should start from, carry a Linear
  * link and external integrations, and set an explicit default path.
@@ -235,11 +244,40 @@ export function projectBasePath(def, forRemote) {
 }
 function projectRootsAbs(defs) {
     const out = [];
-    for (const def of defs) {
-        const raw = def.root ?? def.defaultPath;
+    const push = (name, raw) => {
         if (!raw)
-            continue;
-        out.push({ name: def.name, abs: path.resolve(expandLocalHome(raw)) });
+            return;
+        out.push({ name, abs: path.resolve(expandLocalHome(raw)) });
+    };
+    for (const def of defs) {
+        // `root` says where the CHECKOUT is; `defaultPath` says which work is this
+        // project's. For a monorepo subproject those differ, and only the narrower
+        // one is a membership claim — a project scoped to `rush/apps/cli` does not
+        // own `rush/apps/web`.
+        //
+        // The old `root ?? defaultPath` collapsed such a subproject onto the
+        // monorepo root, the same path its umbrella anchors at, so the longest-match
+        // tiebreak below had nothing to separate them and a session in
+        // `rush/apps/cli` counted toward whichever definition was listed first.
+        const rootAbs = def.root ? path.resolve(expandLocalHome(def.root)) : undefined;
+        const defaultAbs = def.defaultPath ? path.resolve(expandLocalHome(def.defaultPath)) : undefined;
+        const narrowed = !!(rootAbs && defaultAbs && defaultAbs !== rootAbs && isUnder(defaultAbs, rootAbs));
+        // A narrowed project's root is a WEAK claim: it still covers the rest of the
+        // checkout when nobody else wants it, but yields to any project that claims
+        // a path outright. Dropping it entirely regressed the single-project case —
+        // `add foo --root ~/src/foo --path apps/web` stopped attributing work
+        // anywhere else in its own repo, and `--path` means where agents START, not
+        // which work counts.
+        if (rootAbs)
+            out.push({ name: def.name, abs: rootAbs, weak: narrowed });
+        if (defaultAbs && defaultAbs !== rootAbs)
+            out.push({ name: def.name, abs: defaultAbs });
+        for (const r of def.repos ?? []) {
+            push(def.name, r.path);
+            // A repo pinned to a monorepo subpath anchors at that subpath too.
+            if (r.path && r.subpath)
+                push(def.name, path.join(expandLocalHome(r.path), r.subpath));
+        }
     }
     return out;
 }
@@ -269,13 +307,23 @@ export function projectNameForCwd(cwd, defs) {
     const abs = path.resolve(expandLocalHome(cwd));
     let best;
     let bestLen = -1;
-    for (const { name, abs: root } of projectRootsAbs(defs)) {
-        if (isUnder(abs, root) && root.length > bestLen) {
+    let weakBest;
+    let weakLen = -1;
+    for (const { name, abs: root, weak } of projectRootsAbs(defs)) {
+        if (!isUnder(abs, root))
+            continue;
+        if (weak) {
+            if (root.length > weakLen) {
+                weakBest = name;
+                weakLen = root.length;
+            }
+        }
+        else if (root.length > bestLen) {
             best = name;
             bestLen = root.length;
         }
     }
-    return best;
+    return best ?? weakBest;
 }
 /**
  * The canonical project label for a cwd, for every surface that buckets work by

package/dist/lib/redact.d.ts

@@ -1,6 +1,8 @@
 /**
  * Shared redaction helpers for text that may be exported or logged.
  */
+/** Remove terminal control sequences from untrusted text before storage or display. */
+export declare function sanitizeForTerminal(text: string): string;
 /**
  * Scrub secrets from `text`. Two passes: format-based patterns (above), then a
  * value-aware pass that masks any `knownValues` verbatim — a credential we

package/dist/lib/redact.js

@@ -20,9 +20,31 @@ const SECRET_PATTERNS = [
     [/\bxapp-[A-Za-z0-9-]{10,}\b/g, '[REDACTED_SLACK_TOKEN]'],
     [/\bnpm_[A-Za-z0-9]{36}\b/g, '[REDACTED_NPM_TOKEN]'],
     [/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED_JWT]'],
+    // Headers frequently appear inside shell arguments. Consume a quoted header
+    // as one unit so cookie attributes after a space do not survive redaction.
+    [/(^|\s)(["'])(Cookie|Set-Cookie|Authorization|Proxy-Authorization)\s*:\s*.*?\2/gi, '$1$2$3: [REDACTED]$2'],
+    [/(^|\s)(["'])(Cookie|Set-Cookie|Authorization|Proxy-Authorization)\s*:\s*(?:(?!\2).)*$/gi, '$1$2$3: [REDACTED]'],
     [/Bearer\s+\S+/gi, 'Bearer [REDACTED]'],
+    [/\b((?:Cookie|Set-Cookie)\s*:\s*)\S+/gi, '$1[REDACTED]'],
+    [/\b(Authorization\s*:\s*)(?!Bearer\s+\[REDACTED\])\S+(?:\s+\S+)?/gi, '$1[REDACTED]'],
+    // Structured secret fields can arrive as raw JSON output rather than an
+    // argument object, so the object walker alone is not sufficient.
+    [/(^[,{\s]|["'])([A-Z0-9_-]*(?:TOKEN|KEY|SECRET|PASSWORD|AUTHORIZATION|COOKIE)[A-Z0-9_-]*["']?\s*:\s*)(["'][^"']*["']|[^,}\]\s]+)/gim, '$1$2"[REDACTED]"'],
+    [/(\s--?(?:password|token|secret|api[_-]?key)(?:=|\s+))(["']?)[^\s"']+\2/gi, '$1[REDACTED]'],
+    [/(\s--user(?:=|\s+))(["']?)[^\s"']+\2/gi, '$1[REDACTED]'],
+    [/(\s-u\s+)(["']?)[^\s"']+\2/g, '$1[REDACTED]'],
+    [/(\s--proxy-user(?:=|\s+))(["']?)[^\s"']+\2/gi, '$1[REDACTED]'],
+    [/(\s-U\s+)(["']?)[^\s"']+\2/g, '$1[REDACTED]'],
+    [/(https?:\/\/)[^/\s:@]+:[^@\s/]+@/gi, '$1[REDACTED]@'],
     [/\b([A-Z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD)[A-Z0-9_]*)=("[^"]*"|'[^']*'|\S+)/gi, '$1=[REDACTED]'],
 ];
+const TERMINAL_ESCAPE_REGEX = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x9d[^\x07\x9c]*(?:\x07|\x9c)|\x1b\[[0-?]*[ -/]*[@-~]|\x9b[0-?]*[ -/]*[@-~]|\x1b[@-_]|[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+/** Remove terminal control sequences from untrusted text before storage or display. */
+export function sanitizeForTerminal(text) {
+    if (!text)
+        return text;
+    return text.replace(TERMINAL_ESCAPE_REGEX, '');
+}
 /** Env vars whose NAME marks their VALUE as a credential worth masking literally. */
 const SECRET_ENV_NAME = /(?:TOKEN|KEY|SECRET|PASSWORD)/i;
 /** Don't literal-mask trivially short values — they collide with ordinary text. */

package/dist/lib/remote-agents-json.d.ts

@@ -10,6 +10,8 @@ export interface RemoteAgentsJsonOptions<T> {
      * printing a line per offline box above its output. Never a silent drop.
      */
     quiet?: boolean;
+    /** Per-peer deadline. Long-running maintenance commands override 12 seconds. */
+    timeoutMs?: number;
 }
 export interface RemoteAgentsJsonParseResult<T> {
     items: T[];

package/dist/lib/remote-agents-json.js

@@ -32,7 +32,7 @@ export function remoteAgentsJsonCommand(args, noFanoutEnv, os) {
     const inner = `${noFanoutEnv}=1 agents ${args.map(shellQuote).join(' ')}`;
     return `bash -lc ${shellQuote(inner)}`;
 }
-function sshCapture(target, remoteCmd) {
+function sshCapture(target, remoteCmd, timeoutMs) {
     assertValidSshTarget(target);
     return new Promise((resolve) => {
         const args = [...SSH_OPTS, ...controlOpts(), target, remoteCmd];
@@ -49,7 +49,7 @@ function sshCapture(target, remoteCmd) {
         const timer = setTimeout(() => {
             child.kill('SIGKILL');
             done(null);
-        }, REMOTE_TIMEOUT_MS);
+        }, timeoutMs);
         child.stdout.on('data', (data) => { stdout += data.toString(); });
         child.on('error', () => done(null));
         child.on('close', (code) => done(code));
@@ -102,7 +102,7 @@ export async function gatherRemoteAgentsJson(options) {
     const parseFailed = [];
     const results = await Promise.all(targets.map(async (target) => {
         const command = remoteAgentsJsonCommand(options.args, options.noFanoutEnv, target.os);
-        const result = await sshCapture(target.target, command);
+        const result = await sshCapture(target.target, command, options.timeoutMs ?? REMOTE_TIMEOUT_MS);
         if (result.code !== 0) {
             skipped.push(target.name);
             if (!options.quiet) {

package/dist/lib/rotate.d.ts

@@ -174,7 +174,81 @@ export declare function capacityWeight(usedPercent: number | null, minutesToLimi
  * usage headroom.
  */
 export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null, nowMs?: number): RotateResult | null;
+/**
+ * Per-harness routing summary for `agents run auto` — the cross-harness layer
+ * that sits above `pickBalancedCandidate` (which is strictly per-harness).
+ */
+export interface HarnessSummary {
+    agent: AgentId;
+    /** Every installed account slot probed for this harness. */
+    candidates: RotateCandidate[];
+    /** Healthy accounts after identity dedupe, sorted by headroom. */
+    healthy: RotateCandidate[];
+    /** The account this harness would route to (best verified headroom). Null when the harness is excluded. */
+    best: RotateCandidate | null;
+    /** Routing used% of `best` (max across non-session windows); null when unknown. */
+    bestUsedPercent: number | null;
+    /** Why the harness was excluded, e.g. ['2 rate_limited', '1 signed_out']. Empty when healthy. */
+    exclusionReasons: string[];
+}
+export interface HarnessPickResult {
+    /** The harness picked for this run. */
+    picked: HarnessSummary;
+    /** Harnesses with ≥1 healthy account (including the picked one). */
+    healthy: HarnessSummary[];
+    /** Harnesses with zero healthy accounts — excluded, not down-weighted. */
+    excluded: HarnessSummary[];
+}
+/**
+ * Classify every harness's candidates into healthy (with a representative
+ * best account) vs excluded (with per-reason counts). Pure — the pick and the
+ * zero-healthy error message both read this, so they can never disagree.
+ *
+ * Health uses the exact account-layer gate (`isRotationEligible`: signed in
+ * AND not maxed on ANY blocking window, weekly included). The representative
+ * best account honors `preferVerified`: confirmed headroom beats apparent
+ * headroom, the same freshness rule the account layer routes on.
+ */
+export declare function classifyHarnessCandidates(byHarness: ReadonlyMap<AgentId, RotateCandidate[]>, nowMs?: number): HarnessSummary[];
+/**
+ * Pick a harness for `agents run auto` using weighted random by best-account
+ * headroom (RUSH-2132).
+ *
+ * A harness's capacity is `100 − min(routingUsed% across its healthy accounts)`
+ * — its best account's headroom. The pick reuses `weightedRandomByCapacity` on
+ * the representative best accounts, so host/harness/account layers all share
+ * one sampling behavior. Harnesses with zero healthy accounts are EXCLUDED,
+ * not down-weighted. Returns null when no harness has any healthy account;
+ * call `classifyHarnessCandidates` for the exclusion detail to message with.
+ */
+export declare function pickHarnessWeighted(byHarness: ReadonlyMap<AgentId, RotateCandidate[]>, nowMs?: number): HarnessPickResult | null;
+/** One-line banner naming the auto-picked harness and why (headroom). */
+export declare function formatHarnessPickBanner(result: HarnessPickResult): string;
+/**
+ * The earliest FUTURE window reset across these candidates' usage snapshots —
+ * when the first exhausted account becomes usable again. Null when no snapshot
+ * carries a reset timestamp.
+ */
+export declare function earliestResetAcross(candidates: RotateCandidate[], nowMs?: number): Date | null;
+/**
+ * The zero-healthy-account error (RUSH-2132). EXACT contract — the Factory
+ * watchdog tail-detects this text: it must contain the literal `no healthy`
+ * and `resets <time>` (parsed for the rotate cooldown). Do not deviate.
+ */
+export declare function formatNoHealthyAccountError(agent: AgentId, strategy: RunStrategy, excluded: RotateCandidate[], nowMs?: number): string;
+/**
+ * The zero-healthy-harness error for `agents run auto` — names each harness's
+ * exclusion reason plus the earliest reset across all snapshots.
+ */
+export declare function formatNoHealthyHarnessError(summaries: HarnessSummary[], nowMs?: number): string;
 export declare function collectRunCandidates(agent: AgentId): Promise<RotateCandidate[]>;
+/**
+ * Collect run candidates for every harness with ≥1 installed version — the
+ * probe `agents run auto` routes on (the same per-harness account probe
+ * `agents view` aggregates). Harnesses with nothing installed are absent from
+ * the map: not a candidate at all, rather than an excluded one.
+ */
+export declare function collectHarnessCandidates(agentIds?: AgentId[]): Promise<Map<AgentId, RotateCandidate[]>>;
 /**
  * Resolve an account identity to the installed version slot that holds it, over
  * an already-collected candidate list. Pure — no I/O — so it is unit-tested
@@ -207,9 +281,18 @@ export declare function resolveAccountVersion(agent: AgentId, account: string):
 export declare function selectBalancedVersion(agent: AgentId): Promise<RotateResult | null>;
 /** Select the configured version if available, otherwise another available version. */
 export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
-export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string): Promise<{
+export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string, collect?: (agent: AgentId) => Promise<RotateCandidate[]>): Promise<{
     version: string | null;
     rotation: RotateResult | null;
+    /**
+     * Set when a non-pinned strategy found ZERO healthy candidates among the
+     * installed versions: the full excluded set, so callers fail loud with
+     * per-account reasons instead of launching the exhausted pinned default
+     * (RUSH-2132). Undefined for pinned, for successful picks, and when no
+     * version is installed at all (the pre-existing not-installed path — there
+     * is no account to be "unhealthy").
+     */
+    exhausted?: RotateCandidate[];
 }>;
 /**
  * Cap on the number of healthy accounts a single run will re-dispatch through

package/dist/lib/rotate.js

@@ -6,7 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { accountDisplayLabel, getAccountInfo } from './agents.js';
+import { accountDisplayLabel, getAccountInfo, ALL_AGENT_IDS } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getProjectRunConfigs } from './run-config.js';
@@ -342,6 +342,136 @@ export function pickAvailableCandidate(candidates, preferredVersion, nowMs = Dat
         : undefined;
     return { picked: preferred ?? bestVerified, healthy: sorted, excluded, usageUnverified };
 }
+/**
+ * Classify every harness's candidates into healthy (with a representative
+ * best account) vs excluded (with per-reason counts). Pure — the pick and the
+ * zero-healthy error message both read this, so they can never disagree.
+ *
+ * Health uses the exact account-layer gate (`isRotationEligible`: signed in
+ * AND not maxed on ANY blocking window, weekly included). The representative
+ * best account honors `preferVerified`: confirmed headroom beats apparent
+ * headroom, the same freshness rule the account layer routes on.
+ */
+export function classifyHarnessCandidates(byHarness, nowMs = Date.now()) {
+    const summaries = [];
+    for (const [agent, candidates] of byHarness) {
+        const eligible = candidates.filter(isRotationEligible);
+        if (eligible.length === 0) {
+            const counts = new Map();
+            for (const c of candidates) {
+                const readiness = readinessFromCandidate(c);
+                const reason = readiness.ready ? 'ineligible' : readiness.reason;
+                counts.set(reason, (counts.get(reason) ?? 0) + 1);
+            }
+            summaries.push({
+                agent,
+                candidates,
+                healthy: [],
+                best: null,
+                bestUsedPercent: null,
+                exclusionReasons: [...counts.entries()].map(([reason, n]) => `${n} ${reason}`),
+            });
+            continue;
+        }
+        const sorted = dedupeAndSortCandidates(eligible);
+        const { picked: best } = preferVerified(sorted, nowMs, (from) => from[0]);
+        summaries.push({
+            agent,
+            candidates,
+            healthy: sorted,
+            best,
+            bestUsedPercent: getRoutingUsedPercent(best.usageSnapshot),
+            exclusionReasons: [],
+        });
+    }
+    return summaries;
+}
+/**
+ * Pick a harness for `agents run auto` using weighted random by best-account
+ * headroom (RUSH-2132).
+ *
+ * A harness's capacity is `100 − min(routingUsed% across its healthy accounts)`
+ * — its best account's headroom. The pick reuses `weightedRandomByCapacity` on
+ * the representative best accounts, so host/harness/account layers all share
+ * one sampling behavior. Harnesses with zero healthy accounts are EXCLUDED,
+ * not down-weighted. Returns null when no harness has any healthy account;
+ * call `classifyHarnessCandidates` for the exclusion detail to message with.
+ */
+export function pickHarnessWeighted(byHarness, nowMs = Date.now()) {
+    const summaries = classifyHarnessCandidates(byHarness, nowMs);
+    const healthy = summaries.filter((s) => s.best !== null);
+    const excluded = summaries.filter((s) => s.best === null);
+    if (healthy.length === 0)
+        return null;
+    const pickedBest = weightedRandomByCapacity(healthy.map((s) => s.best));
+    const picked = healthy.find((s) => s.best === pickedBest);
+    return { picked, healthy, excluded };
+}
+/** One-line banner naming the auto-picked harness and why (headroom). */
+export function formatHarnessPickBanner(result) {
+    const { picked, healthy, excluded } = result;
+    const headroom = picked.bestUsedPercent === null
+        ? 'best account headroom unknown'
+        : `best account ${Math.max(0, Math.round(100 - picked.bestUsedPercent))}% headroom`;
+    const ratio = `${healthy.length} of ${healthy.length + excluded.length} harnesses healthy`;
+    return `[agents] auto picked ${picked.agent} (${headroom}, ${ratio})`;
+}
+/**
+ * The earliest FUTURE window reset across these candidates' usage snapshots —
+ * when the first exhausted account becomes usable again. Null when no snapshot
+ * carries a reset timestamp.
+ */
+export function earliestResetAcross(candidates, nowMs = Date.now()) {
+    let earliest = null;
+    for (const c of candidates) {
+        for (const window of c.usageSnapshot?.windows ?? []) {
+            const t = window.resetsAt?.getTime();
+            if (t != null && t > nowMs && (earliest === null || t < earliest)) {
+                earliest = t;
+            }
+        }
+    }
+    return earliest === null ? null : new Date(earliest);
+}
+/**
+ * The `resets <summary>` fragment both zero-healthy errors share. ISO 8601 so
+ * a watchdog can parse the cooldown straight off the line; `unknown` when no
+ * snapshot carries a reset (a parser falls back to its default cooldown).
+ */
+function formatResetSummary(reset) {
+    return reset ? reset.toISOString() : 'unknown (no reset timestamps in any snapshot)';
+}
+/**
+ * The zero-healthy-account error (RUSH-2132). EXACT contract — the Factory
+ * watchdog tail-detects this text: it must contain the literal `no healthy`
+ * and `resets <time>` (parsed for the rotate cooldown). Do not deviate.
+ */
+export function formatNoHealthyAccountError(agent, strategy, excluded, nowMs = Date.now()) {
+    const excludedStr = excluded.length === 0
+        ? 'no installed versions'
+        : excluded.map((c) => {
+            const readiness = readinessFromCandidate(c);
+            const reason = readiness.ready ? 'ineligible' : readiness.reason;
+            return `${c.version} (${reason})`;
+        }).join(', ');
+    const resetSummary = formatResetSummary(earliestResetAcross(excluded, nowMs));
+    return `agents: no healthy ${agent} account under strategy '${strategy}' — excluded: ${excludedStr}; earliest window resets ${resetSummary}. Use --strategy pinned to force the default.`;
+}
+/**
+ * The zero-healthy-harness error for `agents run auto` — names each harness's
+ * exclusion reason plus the earliest reset across all snapshots.
+ */
+export function formatNoHealthyHarnessError(summaries, nowMs = Date.now()) {
+    const excludedStr = summaries.length === 0
+        ? 'no installed harnesses'
+        : summaries.map((s) => {
+            const n = s.candidates.length;
+            const detail = s.exclusionReasons.length > 0 ? s.exclusionReasons.join(', ') : 'no accounts signed in';
+            return `${s.agent} (${n} account${n === 1 ? '' : 's'}: ${detail})`;
+        }).join(', ');
+    const resetSummary = formatResetSummary(earliestResetAcross(summaries.flatMap((s) => s.candidates), nowMs));
+    return `agents: no healthy harness for 'run auto' — excluded: ${excludedStr}; earliest window resets ${resetSummary}. Sign in an account or wait for a window to reset.`;
+}
 export async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
     const rows = await Promise.all(versions.map(async (version) => {
@@ -400,6 +530,25 @@ export async function collectRunCandidates(agent) {
         };
     });
 }
+/**
+ * Collect run candidates for every harness with ≥1 installed version — the
+ * probe `agents run auto` routes on (the same per-harness account probe
+ * `agents view` aggregates). Harnesses with nothing installed are absent from
+ * the map: not a candidate at all, rather than an excluded one.
+ */
+export async function collectHarnessCandidates(agentIds = ALL_AGENT_IDS) {
+    const entries = await Promise.all(agentIds.map(async (agent) => {
+        if (listInstalledVersions(agent).length === 0)
+            return null;
+        return [agent, await collectRunCandidates(agent)];
+    }));
+    const byHarness = new Map();
+    for (const entry of entries) {
+        if (entry)
+            byHarness.set(entry[0], entry[1]);
+    }
+    return byHarness;
+}
 /**
  * Resolve an account identity to the installed version slot that holds it, over
  * an already-collected candidate list. Pure — no I/O — so it is unit-tested
@@ -478,14 +627,15 @@ function readRotationStamp(agent) {
     catch { /* missing or corrupt — treat as no stamp */ }
     return null;
 }
-export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
+export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), collect = collectRunCandidates) {
     const fallback = resolveVersion(agent, cwd);
     if (strategy === 'pinned') {
         return { version: fallback, rotation: null };
     }
+    const candidates = await collect(agent);
     const rotation = strategy === 'available'
-        ? await selectAvailableVersion(agent, fallback)
-        : await selectBalancedVersion(agent);
+        ? pickAvailableCandidate(candidates, fallback)
+        : pickBalancedCandidate(candidates);
     if (rotation) {
         // `available` is sticky to the pinned default when healthy. Use the 60s
         // anti-collision stamp to nudge parallel callers off the same version.
@@ -503,7 +653,7 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
         emit('rotation.resolved', { module: 'rotate', agent, version: rotation.picked.version, strategy, healthy: rotation.healthy.length, excluded: rotation.excluded.length });
         return { version: rotation.picked.version, rotation };
     }
-    return { version: fallback, rotation: null };
+    return { version: fallback, rotation: null, exhausted: candidates.length > 0 ? candidates : undefined };
 }
 /**
  * Cap on the number of healthy accounts a single run will re-dispatch through

package/dist/lib/runner.d.ts

@@ -17,7 +17,7 @@ import type { JobConfig, RunMeta } from './routines.js';
 import type { AgentId } from './types.js';
 import { type FallbackEntry } from './exec.js';
 import type { LoopDeps } from './loop.js';
-import { type RotateResult } from './rotate.js';
+import { resolveRunVersion, type RotateResult } from './rotate.js';
 /** Result of a completed job execution, including metadata and optional report. */
 export interface RunResult {
     meta: RunMeta;
@@ -49,7 +49,9 @@ export interface RoutineLaunchPlan {
  *
  * Workflows are left alone — `agents run <workflow>` owns selection.
  */
-export declare function resolveRoutineLaunch(config: JobConfig, cwd?: string): Promise<RoutineLaunchPlan>;
+export declare function resolveRoutineLaunch(config: JobConfig, cwd?: string, deps?: {
+    resolveRunVersion?: typeof resolveRunVersion;
+}): Promise<RoutineLaunchPlan>;
 /**
  * Rewrite `cmd[0]` to the absolute binary for `agent@version` when installed.
  * Bypasses the bare-name shim so a sandboxed HOME / missing default pin cannot

package/dist/lib/runner.js

@@ -29,7 +29,7 @@ import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { walkForFiles } from './fs-walk.js';
 import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
-import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
+import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, formatNoHealthyAccountError, } from './rotate.js';
 import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
 import { isSelfUpdatingAgent } from './agents.js';
@@ -330,7 +330,7 @@ function readCommandExitCode(runDir) {
  *
  * Workflows are left alone — `agents run <workflow>` owns selection.
  */
-export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
+export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {}) {
     if (config.workflow) {
         return { chain: [], rotation: null, pinned: false };
     }
@@ -364,10 +364,12 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
     const strategy = getConfiguredRunStrategy(agent, cwd);
     let version;
     let rotation = null;
+    let exhausted;
     try {
-        const resolved = await resolveRunVersion(agent, strategy, cwd);
+        const resolved = await (deps.resolveRunVersion ?? resolveRunVersion)(agent, strategy, cwd);
         version = resolved.version ?? undefined;
         rotation = resolved.rotation;
+        exhausted = resolved.exhausted;
         if (rotation) {
             const label = rotation.picked.email
                 ? `${rotation.picked.email} · ${agent}@${rotation.picked.version}`
@@ -385,7 +387,7 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
                 process.stderr.write(`[agents] routine ${config.name}: skipped ${reasons}\n`);
             }
         }
-        else if (!version) {
+        else if (!version && !exhausted) {
             process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} found no usable ${agent} version; ` +
                 `falling back to default pin\n`);
         }
@@ -393,6 +395,13 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
     catch (err) {
         process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} skipped: ${err.message}\n`);
     }
+    // Zero healthy accounts is NOT a "fall back to the default pin" case — that
+    // pin is exactly the exhausted account an unattended routine would hammer
+    // every tick (RUSH-2132). Throwing fails the job run (nonzero), and the
+    // message text is the contract the Factory watchdog tail-detects.
+    if (exhausted) {
+        throw new Error(formatNoHealthyAccountError(agent, strategy, exhausted));
+    }
     if (!version) {
         version = resolveVersion(agent, cwd) ?? undefined;
     }