@phnx-labs/agents-cli 1.21.3 → 1.22.1

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog
 
+## 1.22.1
+
+- **`agents doctor` de-noise: never-synced and cross-version hook drift are warnings, not criticals (RUSH-2162).** The CRITICAL section now holds only "needs you now" problems — a logged-out account, or a hook/plugin missing from a version you keep synced. A version that was never synced (an old/unused install with nothing installed) and a hook that merely *differs* across versions (installed but stale) are surfaced as WARNINGs instead, cutting the critical count on a busy machine from ~11 to the handful that actually need action. Source: `apps/cli/src/lib/devices/doctor-findings.ts`.
+
+- **The "… is damaged and can't be opened" dialog stops — both helper `.app` bundles now install atomically and serialized.** The secrets keychain helper (`Agents CLI.app`) and the menu-bar helper (`MenubarHelper.app`) are each (re)installed on the hot path of ordinary `agents` invocations, and both did a non-atomic `rm -rf dest` + `cp -R src dest` straight onto the live bundle. On a busy box dozens of concurrent invocations raced that path, so a reader (Gatekeeper, or an exec of the bundle) could see a half-written `.app` — a truncated Mach-O / mismatched code signature — which macOS reports as damaged. A new shared installer (`lib/app-bundle-install.ts`, replacing the two duplicated copy functions) stages the copy in a sibling dir and swaps it in with renames (the live bundle is only ever a complete, signed `.app`, and a failed copy never touches it), and serializes concurrent installers behind the shared `withFileLock` with a double-checked skip so a burst copies once instead of stampeding. Source: `apps/cli/src/lib/app-bundle-install.ts`, `apps/cli/src/lib/secrets/install-helper.ts`, `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **`agents doctor --json` no longer stampedes into dozens of concurrent runs — the overview is singleflighted and cached, with a new `--refresh` to force a live recompute.** The bare `doctor --json` overview probes every host CLI, every agent's sign-in, and every agent×version diff — seconds on an idle box, minutes on a loaded one. The menu-bar helper polls it on a timer with only a per-*process* in-flight guard, so a helper relaunch (or any second poller) each launched its own live compute, and a helper killed mid-run orphaned a `doctor --json` that kept spinning — stacking to dozens of concurrent runs pinning the CPU. Now a fresh snapshot (< 90s) serves instantly from a disk cache, and when a live compute IS needed exactly one runs while every other caller serves its result (a lock-directory singleflight that self-heals if the computer dies). `agents doctor --json --refresh` bypasses the cache. Source: `apps/cli/src/lib/devices/doctor-overview-cache.ts`, `apps/cli/src/commands/doctor.ts`.
+
+- **`doctor --json` releases its singleflight lock before it returns.** The overview gate
+  fired the lock release without awaiting it on the path where a waiter serves the winner's
+  fresh snapshot, so the call returned with the lockfile still on disk. The next caller then
+  retried against a lock that was already logically free — the pile-up the gate exists to
+  prevent, narrowed to the window between return and unlink. The release is now awaited.
+  The existing coalescing test failed 5 times in 15 runs before this and 0 in 15 after.
+  Source: `apps/cli/src/lib/devices/doctor-overview-cache.ts`.
+
+- **`agents add grok@latest` no longer strands the freshly-downloaded binary in the old version's home.** When the post-install version probe (`<cli> --version`) transiently failed right after grok's self-updating installer exited, `installVersion` silently fell back to the literal string `'latest'` as the resolved version — creating a bogus `versions/grok/latest/` directory and defeating `relocateGrokBinaryToVersionHome`'s exact-filename match (its regex could never match `grok-latest-...`, since the real file is named `grok-<semver>-<platform>`). The real multi-hundred-MB binary was left behind in the PREVIOUS default's downloads dir, and `agents view grok` never listed the new version as installed even though `agents add` reported success. The probe now retries briefly instead of silently falling back, and fails loudly if it still can't resolve a version rather than corrupting the version bookkeeping. Relocation also now self-heals: if the current `~/.grok` symlink target has nothing matching, it sweeps every other installed grok version home for a binary stranded by a past occurrence of this bug. Source: `apps/cli/src/lib/versions.ts`.
+
+- **A blocked menu-bar row now takes you to the session (RUSH-2110).** A NEEDS-YOU row
+  exists because an agent is waiting on you, but its only action was "Reveal working
+  dir", which unblocks nothing — you still had to go find the session by hand. Blocked
+  rows now lead with **Focus session**, which runs `agents focus <id>`: attach the live
+  terminal, or open a new tab and resume, cross-host. Reveal stays underneath. Both
+  render paths are covered — the single inline row and each entry inside a collapsed
+  multi-waiter group. A row the engine could not identify (a cloud task, a stale
+  sentinel) simply omits the item rather than offering an action that would do nothing.
+  Source: `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`,
+  `AgentsCLI.swift`.
+
+- **Two projects sharing one monorepo checkout are no longer indistinguishable.** Session,
+  activity, and feed attribution anchored a project on `root ?? defaultPath`, so a subproject
+  whose `root` is the monorepo and whose `defaultPath` is a subdir collapsed onto the same
+  path as its umbrella — the longest-match tiebreak had nothing to separate them, and work in
+  `rush/apps/cli` counted toward whichever definition happened to be listed first. A
+  `defaultPath` nested under `root` now takes precedence over that `root` (the root says where
+  the checkout is; `defaultPath` says which work is this project's), and each bound repo's
+  checkout and subpath anchor too. A narrowed `root` still covers the rest of its checkout as
+  a fallback, so a lone project defined with `--path` keeps attributing work across its own
+  repo instead of only inside the subdir. Source: `apps/cli/src/lib/projects.ts`.
+
+- **`agents projects view <name>` now shows more than `status`, not less.** The command you
+  open to learn everything about one project built its own short list — root, repos, a raw
+  Linear project id, an issue count, milestones — and never called the card renderer, so it
+  omitted the agents roster, merged PRs and release, focus areas, the schedule verdict,
+  tickets, and artifacts that `status` had shown all along. `view` and `status` now gather
+  through one function and render through one card; `view` adds every milestone (instead of
+  just the next) and the stored definition in full underneath — each repo with its subpath and
+  checkout, each context with its purpose, each integration with its URL. It also takes
+  `--window <days>` to match `status`. Source: `apps/cli/src/commands/projects.ts`.
+- **The `agents` roster on the card lists live sessions only.** It included every matched
+  session, so a card headed `23 live` went on to print `claude · crashed ×25` — the corpses the
+  `dead` row already reports, counted twice and contradicting the headline. Both now derive
+  from one `isDeadStatus` predicate, pinned by a test across every `ActiveStatus`. Source:
+  `apps/cli/src/lib/project-status.ts`.
+
+- **`--host <self>` and the fleet-health fan-out now short-circuit ALL of the
+  local machine's names, not just its short hostname (RUSH-2114).** A `--host`
+  target or fleet probe that referenced this box by its **tailscale dnsName**
+  (`zion.tail1a85a1.ts.net`) slipped past a `=== machineId()` check and SSH'd to
+  the local box over its own name; on a loaded machine that self-SSH'd `doctor
+  --json` orphaned on timeout and piled up until the host was crushed. A new
+  `isSelfHost()` matches every identity the box answers to (short id, loopback,
+  tailscale dnsName + its short form) and gates all four self-checks — the
+  generic `--host` passthrough (`maybeRunOnHost`), the `--devices`-all fan-out
+  (`runFleetPassthrough`), `remoteFleetTargets`, and `runFleet` — so a
+  self-reference runs locally instead of self-SSHing. Source:
+  `apps/cli/src/lib/devices/self-host.ts`, `apps/cli/src/lib/hosts/passthrough.ts`,
+  `apps/cli/src/lib/devices/fleet.ts`.
+
+## 1.22.0
+
+- **`agents run auto` — full-auto dispatch (RUSH-2132).** `run auto` composes all three routing layers: host (14d launch affinity, unless `--host` is given), harness (installed CLIs weighted by best-account headroom), and account (the configured strategy). `balanced`/`available` now exit nonzero when every installed account is unhealthy — naming each excluded account, the earliest window reset, and the `--strategy pinned` escape hatch — instead of warning "falling back to defaults" and launching the exhausted pinned default. The error text is a machine-readable contract (`no healthy` + `resets <iso-time>`) the Factory watchdog tail-detects for rotate cooldowns. Source: `apps/cli/src/lib/rotate.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/runner.ts`.
+
+- **Bash-command summaries are faster and recognize more of what actually ran (#1830).**
+  `classifyBashCommand` (behind `agents sessions` / `agents activity` summaries) tokenized
+  the *entire* command — every pipeline segment, multi-KB heredoc bodies included — just to
+  read the leading executable, costing up to ~1ms on a big `cat <<HEREDOC …`. It now
+  tokenizes only the head of the first simple command. Coverage gaps that dumped commands
+  into a raw `other` pile are closed too: a `cd` prefix separated by `;` or a newline (not
+  just `&&`) unwraps to the real command, a path/tilde executable
+  (`~/.agents/skills/linear/scripts/linear`) resolves by basename, and the repo's own
+  toolchain (`agents`, `linear`, plus `rmdir`) is recognized — `agents` was the single top
+  unrecognized token. `ag` stays the silver searcher, not an `agents` alias. Source:
+  `apps/cli/src/lib/session/bash-command.ts`.
+
+- **`agents computer describe` now counts toward `usedComputer`.** Every other
+  verb (`click`, `type`, `key`, `screenshot`, `run`, …) fires the
+  `computer.action` event via `emitComputerAction`; `describe` never did, so a
+  session that only ran `agents computer describe` read back
+  `usedComputer=false` — a false-negative in the sessions preview. A new
+  completeness-guard test pins every registered `agents computer` verb command
+  to a matching `emitComputerAction` call so a future verb can't ship the same
+  gap silently. Source: `apps/cli/src/commands/computer-actions.ts`,
+  `apps/cli/src/commands/computer-actions.test.ts`.
+
+- **Pick a model by cost tier — `--model cheap|default|best|ultra` — on `agents run` and `agents teams add`.** Instead of a concrete id that churns per release and differs per harness, a tier resolves per `(harness, installed version)` to a model that version actually ships, ranked by the provider's own lineup (`opus/sonnet/haiku/fable`; Codex "frontier/balanced/fast" → Sol/Terra/Luna), then price, then size tokens. Single-model harnesses (Grok) map the tiers to reasoning effort; Droid uses a curated credit-multiplier map capped at 2x. An unsupported tier clamps to the nearest lower one; an unresolvable tier drops the flag and falls back to the harness default. Concrete model ids keep working unchanged. `agents models [agent[@version]]` now prints the per-harness tier map (with `~$/Mtok` where priced) and emits `tiers` in `--json`, and Droid joins the model-capable set. Also fixes the Claude catalog extractor returning 0 models on the newest native-binary format (a fallback id scan), and refreshes `prices.json` with the GPT-5.6 Sol/Terra/Luna series. Source: `apps/cli/src/lib/model-tiers.ts`, `apps/cli/src/lib/models.ts`, `apps/cli/src/lib/exec.ts`, `apps/cli/src/commands/models.ts`, `apps/cli/docs/model-tiers.md`.
+
+- **`agents projects status` says what was worked on and what the dates prove.** Two new lines.
+  `focus` ranks the directories the window's commits landed in, read from the local checkout
+  with `git log --name-only` — no API call, no credential, no rate-limit budget, measured at
+  0.23s over a 897-commit week. Changelog fragments and lockfiles are excluded from the
+  ranking: this repo files one fragment per PR, so `.changelog` otherwise ranked second and
+  presented PR count as an area of focus. `schedule` states what the milestone dates prove —
+  `overdue by N days`, `due in N days`, `N milestones, no issues filed against any`, or
+  `none dated`. Source: `apps/cli/src/lib/project-focus.ts`, `project-schedule.ts`.
+- **The schedule line will never say "on track".** That verdict needs either project start and
+  target dates to interpolate expected progress, or a scope-history series to extrapolate a
+  finish date. Probed against a live workspace, all of them are absent (`health: null`,
+  `startDate`/`targetDate` null, `scopeHistory` and `completedScopeHistory` empty), so an
+  on-track or at-risk chip would be fabricated — and a confident wrong answer on a status card
+  is unfalsifiable from the card. When a human posts a Linear project health update, it is
+  relayed and attributed (`per Linear: atRisk`), never synthesized.
+
+- **The `--device`/`--host` auto-reconnect loop no longer trusts a remote-origin exit code of 255 as "the SSH link dropped."** `reattachRemoteSession`'s `connected` flag is set as soon as the fast SSH preflight probe succeeds, before the actual reattach runs — so if the remote command it drives (`agents sessions focus <id> --local --attach-only`) ever exited 255 for a reason that had nothing to do with the SSH transport, that would be indistinguishable from the link itself dropping, refill the retry budget every cycle, and loop forever — printing "attempt 1/6" on every cycle and leaving the terminal full of aborted-TTY escape codes. The remote invocation is now wrapped in `bash -lc` so that whatever exit code it decides on, a 255 is remapped to 254 before this process sees it, closing that gap in the exit-code channel regardless of which remote-side path or peer `agents` version might produce it. A genuinely recurring *local* SSH failure can still refill the retry budget on every attempt by design (unchanged, tracked separately: phnx-labs/agents-cli#1884). Source: `apps/cli/src/lib/hosts/reconnect.ts`.
+
+- **`agents sessions` can query distinct tool calls and count static Bash program occurrences locally or across the fleet.** Use `--include tools`, repeat `--query` with `tool:`, `program:`, `input:`, `output:`, `status:`, `exit:`, or `error:` fields, and add `--fleet` for live SSH fan-out. `--count` reports exact occurrence, containing-call, and session totals from ordered `wrapper`/`effective` rows without reparsing; synced mirrors are partitioned by origin so fleet evidence and totals do not duplicate sessions. Historical parsing is explicit and resumable through `agents sessions backfill tools`; normal scans index new and changed sessions once. Codex orchestration wrappers are parsed statically so only literal `tools.exec_command` commands reach the Bash AST, never wrapper code. Each device keeps a redacted, bounded relational SQLite/FTS5 cache, queries perform no transcript I/O or index writes, and no embeddings, vector database, or model calls are used. A sampling script explicitly backfills then extracts redacted shell-command origins from 50–100 sessions over the last seven days into a 16 MiB maximum artifact.
+
+- **Local team worktrees base on freshly-fetched `origin/<default>`, not `HEAD`.**
+  `createWorktree` (and `agents worktree provision` for new branches) now
+  `git fetch origin` then `worktree add -b … origin/<default>`, matching
+  `createRemoteWorktree`. Previously local teammates forked from the
+  orchestrator's current `HEAD`, so a stale checkout made every teammate write
+  on old code and only surface the conflict at merge. Source:
+  `apps/cli/src/lib/teams/worktree.ts`, `apps/cli/src/commands/worktree.ts`,
+  `apps/cli/docs/teams.md`.
+
 ## 1.21.3
 
 - **`agents projects import --from-factory` stops printing raw git errors.** Reading each
@@ -33,6 +159,16 @@
   `agents sessions`'s perf sample for `command.end` now carries the session id
   and agent instead of being anonymous. Source: `apps/cli/src/lib/session/prompt.ts`,
   `apps/cli/src/lib/session/parse.ts`, `apps/cli/src/index.ts`.
+- **`agents routines status` no longer reports "stopped" for a live scheduler, and
+  `agents routines start` can't spawn a second one.** The daemon writes its pid file
+  once (on claim/start) but rewrites the heartbeat every tick. If the pid file was lost
+  while the daemon kept ticking — an earlier status check clearing a stale/reused pid, or
+  the file removed out from under a live daemon — `status` read only the pid file and
+  reported `stopped` for a scheduler that was in fact running and firing jobs, while
+  `claimDaemonInstance()` would start a concurrent `JobScheduler` that double-fires every
+  routine. `isDaemonRunning()` and the single-instance claim now also trust a fresh
+  heartbeat whose pid is alive, re-adopting the pid file to heal the desync.
+  Source: `apps/cli/src/lib/daemon.ts`.
 
 ## 1.21.2
 

package/README.md

@@ -161,7 +161,18 @@ agents run claude@
 agents run codex@ "review this branch"
 ```
 
-`--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one.
+`--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one. When every account is rate-limited, the run exits nonzero naming each excluded account and the earliest window reset (use `--strategy pinned` to force the default) -- it never launches into an exhausted account.
+
+### Don't care which harness? `agents run auto`
+
+```bash
+# Picks the host (14d usage affinity), the harness (installed CLIs weighted by
+# best-account headroom), and the account (balanced) -- all three layers.
+agents run auto "summarize recent commits"
+agents run auto --host yosemite-s0 "fix the flaky test"   # pin the host layer
+```
+
+`run auto` excludes any harness whose accounts are all rate-limited or signed out, and exits nonzero with the earliest reset time when nothing anywhere is healthy.
 
 A trailing `@` opens an account picker before either an interactive or prompt-based run. Each installed version shows its account identity, exact version, login state, plan, and every available session, weekly, or monthly limit. Logged-out, rate-limited, and out-of-credit accounts remain visible with the reason they cannot be selected; signed-in accounts whose provider does not expose quota data stay selectable and say `limits unavailable`. The choice pins only that run and does not change your default version.
 
@@ -244,11 +255,26 @@ agents sessions a1b2c3d4 --markdown
 
 # Just the last 3 turns, user messages only
 agents sessions a1b2c3d4 --last 3 --include user
+
+# Calls in recent Codex sessions on one device
+agents sessions --include tools --agent codex --device mac-mini --since 7d
+
+# One session where two different calls match; query every online device
+agents sessions --include tools \
+  --query 'program:git input:merge' \
+  --query 'program:gh output:CONFLICT' \
+  --fleet --json
+
+# Count pre-indexed static git sites, containing calls, and sessions
+agents sessions --include tools --query 'program:git' --count --fleet --json
+
+# Populate historical tool rows once on each device
+agents sessions backfill tools --fleet
 ```
 
 Interactive picker when you're in a terminal. Structured output (`--json`, `--markdown`, filtered by role or turn count) when piped.
 
-Backed by a SQLite + FTS5 index at `~/.agents/.history/sessions/sessions.db` with incremental scanning -- warm reads in ~100ms. External tools can consume `--json` output as a programmatic observability layer; see [docs/05-sessions.md](apps/cli/docs/05-sessions.md) for the schema and [docs/06-observability.md](apps/cli/docs/06-observability.md) for the consumption patterns.
+Backed by a SQLite + FTS5 index at `~/.agents/.history/sessions/sessions.db` with incremental scanning -- warm reads in ~100ms. Tool-call evidence is redacted and bounded before it is cached; repeated `--query` clauses must match distinct calls in one session. Tool queries read SQLite only: `agents sessions backfill tools` performs the one-time historical parse, while normal incremental scans index new and changed sessions. The index stores ordered static Bash program sites, so `--count` reports occurrences, containing tool calls, and distinct sessions without reparsing. `--fleet` executes one origin partition per device, so synced mirrors cannot duplicate compact evidence or counts returned over SSH; transcript bodies stay on their origin machine. This uses relational SQLite rows and literal FTS5 only, with no embeddings, vector database, or model calls. External tools can consume `--json` output as a programmatic observability layer; see [docs/05-sessions.md](apps/cli/docs/05-sessions.md) for the schemas and [docs/06-observability.md](apps/cli/docs/06-observability.md) for the consumption patterns.
 
 ### Live state, and catching up fast
 
@@ -1095,9 +1121,12 @@ Conversations with Claude, Codex, legacy Gemini, and other agents scatter across
 ```bash
 agents sessions "auth middleware"     # Full-text search across all agents
 agents sessions --agent claude --since 7d
+agents sessions --include tools --query 'program:git' --fleet --json
+agents sessions --include tools --query 'program:git' --count --fleet --json
+agents sessions backfill tools --fleet
 ```
 
-The index lives at `~/.agents/.history/sessions/sessions.db` (SQLite + FTS5). Nothing leaves your machine. See [Sessions](#sessions-across-agents) for full usage.
+The index lives at `~/.agents/.history/sessions/sessions.db` (SQLite + FTS5). A local query stays on the machine; an explicit `--fleet` tool query sends only redacted, bounded match evidence or aggregate counts over SSH. Historical tool parsing is explicit via `sessions backfill tools`; queries never parse transcripts. See [Sessions](#sessions-across-agents) for full usage.
 
 ### Secrets
 

package/dist/commands/computer-actions.js

@@ -413,6 +413,7 @@ export function registerActionCommands(program) {
             if (opts.depth != null)
                 params.max_depth = opts.depth;
             const res = unwrap(await client.call('describe', params));
+            emitComputerAction('describe', pid, opts, { depth: opts.depth });
             // The tree is inherently structured — always JSON, pretty unless --json.
             console.log(JSON.stringify(opts.json ? res : res.tree ?? res, null, 2));
         });

package/dist/commands/doctor.js

@@ -4,6 +4,7 @@ import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
 import { fanOutDevices, planFleetTargets, remoteFleetTargets } from '../lib/devices/fleet.js';
+import { enterDoctorOverviewGate, writeDoctorOverviewCache } from '../lib/devices/doctor-overview-cache.js';
 import { fleetDialTarget } from '../lib/devices/connect.js';
 import { compareFleetInventories } from '../lib/devices/fleet-divergence.js';
 import { collectLocalFleetInventory } from '../lib/devices/fleet-inventory.js';
@@ -1155,12 +1156,18 @@ export function registerDoctorCommand(program) {
         .option('--devices', 'Check agent readiness AND cross-device harness divergence (missing resources/versions, repo drift) on every registered device (alias --hosts)')
         .option('--hosts', 'Alias of --devices')
         .option('--check', 'CI drift gate: exit non-zero when any installed version is out of sync (stale or never-synced), zero when clean. Combine with --devices to gate the whole fleet.')
+        .option('--refresh', 'Bypass the cached overview snapshot: recompute the bare `doctor --json` overview live and refresh the shared cache that the menu-bar and other pollers read')
         .option('-q, --quiet', 'With --check, suppress per-version lines; print only the one-line verdict');
     setHelpSections(doctorCmd, {
         examples: `
       # Overview: CLI availability + sync status + orphans across all defaults
       agents doctor
 
+      # Machine-readable overview (served from a ~90s cache for pollers like the
+      # menu-bar helper); --refresh recomputes live and refreshes that cache
+      agents doctor --json
+      agents doctor --json --refresh
+
       # Full per-resource report for the active default
       agents doctor claude@default
 
@@ -1288,6 +1295,26 @@ export function registerDoctorCommand(program) {
             return;
         }
         if (!target) {
+            // Singleflight + short-TTL cache for the bare `doctor --json` overview.
+            // This overview probes every host CLI, every agent's sign-in, and every
+            // agent×version diff — seconds on an idle box, minutes on a loaded one.
+            // The menu-bar helper polls it with only a per-*process* in-flight guard,
+            // so a helper relaunch (or any second poller) each launched its own live
+            // compute, and a helper killed mid-run orphaned a `doctor --json` that
+            // kept spinning — stacking to dozens of concurrent runs pinning the CPU
+            // (RUSH-2153). Now: a fresh snapshot serves instantly, and when a compute
+            // IS needed exactly one runs while every other caller serves its result.
+            // A crashed computer never wedges the gate — the lock is stolen once its
+            // directory mtime goes stale (see enterDoctorOverviewGate).
+            let releaseOverviewGate;
+            if (opts.json) {
+                const gate = await enterDoctorOverviewGate({ forceRefresh: !!opts.refresh });
+                if (gate.cached !== null) {
+                    console.log(gate.cached);
+                    return;
+                }
+                releaseOverviewGate = gate.release;
+            }
             const clis = checkAllClis();
             const syncRows = checkSyncStatus(cwd);
             const orphanRows = countOrphans();
@@ -1355,7 +1382,7 @@ export function registerDoctorCommand(program) {
                 isolatedVersions,
             });
             if (opts.json) {
-                console.log(JSON.stringify({
+                const overviewPayload = {
                     clis,
                     signIn,
                     // Cached auth-health rollup for THIS host — lets `agents fleet status`
@@ -1398,7 +1425,12 @@ export function registerDoctorCommand(program) {
                         branch: m.branch,
                         fetchedAt: m.fetchedAt,
                     })),
-                }, null, 2));
+                };
+                // Persist for the next poller and release the singleflight lock BEFORE
+                // printing, so a concurrent caller picks up the fresh snapshot at once.
+                writeDoctorOverviewCache(overviewPayload);
+                releaseOverviewGate?.();
+                console.log(JSON.stringify(overviewPayload, null, 2));
                 return;
             }
             // Single-machine hybrid: CRITICAL section + one `▸ <machine>` block.

package/dist/commands/exec.d.ts

@@ -7,6 +7,7 @@
  */
 import { type Command } from 'commander';
 import type { ExecEffort } from '../lib/exec.js';
+import { RUN_AUTO_KEYWORD } from '../lib/types.js';
 import { type SshGResult } from '../lib/hosts/ssh-config.js';
 export interface RunAccountPickerRequest {
     requested: boolean;
@@ -41,6 +42,32 @@ export declare function runAccountPickerConflicts(options: {
     on?: string;
     computer?: string;
 }): string[];
+export { RUN_AUTO_KEYWORD };
+/**
+ * Whether `run auto` should default its host layer to the affinity pick (the
+ * same machinery as `--device auto`). False when the caller pinned any host
+ * flag, and false when this process was itself dispatched by a host run — the
+ * dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
+ * (hosts/dispatch.ts remoteRunShellPrelude) because it already resolved the
+ * host layer, and re-picking here would chain-hop the run across the fleet.
+ * Pure so the pinning matrix is unit-testable.
+ */
+export declare function runAutoDefaultsToAffinity(options: {
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+}, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether an interactive host dispatch must mint a correlation launch id and
+ * resolve the remote session via the launch-id join (RUSH-2034), rather than
+ * trusting a pre-known session id. `run auto` ALWAYS joins: the harness is
+ * picked on the remote, so an explicit --session-id is only adopted when the
+ * pick lands on claude — pre-registering it would strand a stale session-index
+ * entry naming an id a non-claude pick never used (RUSH-2132). Pure so the
+ * decision matrix is unit-testable.
+ */
+export declare function hostInteractiveNeedsCorrelationId(runAgent: string, hostSessionId: string | undefined, resumeId: string | undefined): boolean;
 /** The host descriptor fields the `--copy-creds` security gate reads. */
 export interface CopyCredsGateHost {
     name: string;

package/dist/commands/exec.js

@@ -7,6 +7,7 @@
  */
 import { Option } from 'commander';
 import chalk from 'chalk';
+import { RUN_AUTO_KEYWORD } from '../lib/types.js';
 import { setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { getUserAgentsDir } from '../lib/state.js';
@@ -66,6 +67,39 @@ export function runAccountPickerConflicts(options) {
 function isValidAgent(agent) {
     return agent in AGENTS;
 }
+// Reserved `<agent>` keyword for `agents run auto` — canonical definition in
+// lib/types.ts (shared with the host dispatch layer); re-exported here.
+export { RUN_AUTO_KEYWORD };
+/**
+ * Whether `run auto` should default its host layer to the affinity pick (the
+ * same machinery as `--device auto`). False when the caller pinned any host
+ * flag, and false when this process was itself dispatched by a host run — the
+ * dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
+ * (hosts/dispatch.ts remoteRunShellPrelude) because it already resolved the
+ * host layer, and re-picking here would chain-hop the run across the fleet.
+ * Pure so the pinning matrix is unit-testable.
+ */
+export function runAutoDefaultsToAffinity(options, env = process.env) {
+    if (hostTargetGiven(options).length > 0)
+        return false;
+    return env.AGENTS_RUN_AUTO_HOST_RESOLVED !== '1';
+}
+/**
+ * Whether an interactive host dispatch must mint a correlation launch id and
+ * resolve the remote session via the launch-id join (RUSH-2034), rather than
+ * trusting a pre-known session id. `run auto` ALWAYS joins: the harness is
+ * picked on the remote, so an explicit --session-id is only adopted when the
+ * pick lands on claude — pre-registering it would strand a stale session-index
+ * entry naming an id a non-claude pick never used (RUSH-2132). Pure so the
+ * decision matrix is unit-testable.
+ */
+export function hostInteractiveNeedsCorrelationId(runAgent, hostSessionId, resumeId) {
+    if (resumeId)
+        return false;
+    if (runAgent === RUN_AUTO_KEYWORD)
+        return true;
+    return !hostSessionId && isSessionTrackedAgent(runAgent);
+}
 /** Build a one-line banner describing which version the strategy picked. */
 function formatRotationBanner(result, verb = 'balanced') {
     const { picked, healthy, excluded } = result;
@@ -483,7 +517,7 @@ export function registerRunCommand(program) {
         .description('Execute an agent. Pass a prompt for headless runs; omit it to launch the agent interactively.')
         .option('-m, --mode <mode>', 'How much the agent can do: plan (read-only), edit (can write files), auto (smart classifier auto-approves safe ops, prompts for risky), skip (bypass all permission prompts). \'full\' accepted as alias for skip.', 'plan')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto (claude and codex only)', 'auto')
-        .option('--model <model>', 'Override the model directly (e.g., claude-opus-4-6)')
+        .option('--model <model>', 'Cost tier (cheap|default|best|ultra) or a concrete model id; tiers resolve per harness+version to a supported model')
         .option('--env <key=value>', 'Pass environment variable to the agent (repeatable, e.g., --env DEBUG=1 --env API_KEY=xyz)', (val, prev) => [...prev, val], [])
         .option('--secrets <bundle>', 'Inject a secrets bundle (repeatable). Values resolve from macOS Keychain at run time. See `agents secrets`.', (val, prev) => [...prev, val], [])
         .option('--no-auto-secrets', 'Skip auto-injection of secrets declared by a workflow\'s frontmatter `secrets:` field. Has no effect on bare-agent runs.')
@@ -561,6 +595,11 @@ export function registerRunCommand(program) {
       # Pick a signed-in account/version for only this run
       agents run claude@
 
+      # Full-auto: affinity-pick the host, then the harness with the most
+      # account headroom, then a balanced account on it
+      agents run auto "fix the flaky test" --mode edit
+      agents run auto --host yosemite-s0 "fix the flaky test"   # pin the host
+
       # Open the session in a terminal tab — detected from where your sessions
       # already run (Ghostty / iTerm / Terminal.app); force one with a value
       agents run claude --terminal
@@ -599,6 +638,13 @@ export function registerRunCommand(program) {
         balanced   distribute load across healthy accounts by remaining capacity (default)
         A version/account is skipped when it is rate-limited right now — any usage window (incl. the 5-hour session window) at 100%, matching the 'agents view' badge.
         --balanced is shorthand for --strategy balanced. Ignored when @version is pinned, when a profile is used, or with --fallback.
+        Zero healthy accounts under balanced/available exits nonzero naming each
+        excluded account and the earliest window reset — use --strategy pinned to force.
+
+      'auto' harness (agents run auto): picks the host (14d usage affinity,
+      unless --host is given), the harness (installed CLIs weighted by
+      best-account headroom), and the account (the strategy above). Zero
+      healthy accounts on any harness exits nonzero with the earliest reset.
 
       Account picker: append @ with no version (agents run claude@) to choose one
         installed account for this run. Rows show identity, login state, plan,
@@ -682,6 +728,32 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
+        // `agents run auto`: the reserved harness keyword — full-auto dispatch
+        // (host affinity → cross-harness balance → account balance, RUSH-2132).
+        if (normalizedAgentSpec.split('@')[0] === RUN_AUTO_KEYWORD && normalizedAgentSpec !== RUN_AUTO_KEYWORD) {
+            console.error(chalk.red(`agents run auto picks the harness itself — a @version pin does not apply. ` +
+                `Pin a concrete harness instead: agents run <harness>@<version>.`));
+            process.exit(1);
+        }
+        const autoHarnessRequested = normalizedAgentSpec === RUN_AUTO_KEYWORD;
+        if (autoHarnessRequested) {
+            // `auto` is reserved. If a future harness registers that id, the
+            // keyword collides — fail loud rather than silently shadow the harness.
+            if (RUN_AUTO_KEYWORD in AGENTS) {
+                console.error(chalk.red(`'${RUN_AUTO_KEYWORD}' is now a registered harness and collides with the reserved 'run auto' keyword. ` +
+                    `Run the harness by name instead.`));
+                process.exit(1);
+            }
+            if (accountPickerRequested) {
+                console.error(chalk.red(`agents run auto picks the harness and account itself — the trailing-@ account picker needs a concrete harness (agents run <harness>@).`));
+                process.exit(1);
+            }
+            // Host layer: with no explicit --host/--device, default to the
+            // affinity pick. Skipped on a host-dispatched run — its dispatcher
+            // already resolved this layer (see runAutoDefaultsToAffinity).
+            if (runAutoDefaultsToAffinity(options))
+                options.device = 'auto';
+        }
         // --device auto / --host auto (and deprecated --smart): affinity-pick host.
         // Harness is always the agent the user typed — never auto-picked.
         // Affinity failure degrades to local (does not kill the run).
@@ -1062,6 +1134,10 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const hostName = hostGiven[0];
+            // Note: a `run auto` dispatch needs no marker forwarded from here — the
+            // dispatch layer (hosts/dispatch.ts remoteRunShellPrelude) exports the
+            // chain-hop guard into the remote shell for BOTH interactive and
+            // headless paths, keyed off the agent name being `auto`.
             const { resolveHostRunTarget, resolveHostSessionId, dispatchPromptToHost, HostResolutionError } = await import('../lib/hosts/run-target.js');
             const { runInteractiveOnHost } = await import('../lib/hosts/dispatch.js');
             const { registerInteractiveHostSession } = await import('../lib/hosts/session-index.js');
@@ -1242,11 +1318,16 @@ export function registerRunCommand(program) {
                     // the stream we resolve the id by one ssh read of the remote hook
                     // record — the same launch-id join used locally (RUSH-2034). Not
                     // needed for Claude (id forced) or resume (id already known).
-                    const correlationLaunchId = !hostSessionId && !resumeId && isSessionTrackedAgent(runAgent) ? randomUUID() : undefined;
+                    // `run auto` ALWAYS joins: the remote picks the harness, so an
+                    // explicit --session-id is only adopted by a claude pick.
+                    const correlationLaunchId = hostInteractiveNeedsCorrelationId(runAgent, hostSessionId, resumeId) ? randomUUID() : undefined;
                     const hostEnv = correlationLaunchId
                         ? [...options.env, `AGENT_LAUNCH_ID=${correlationLaunchId}`]
                         : options.env;
-                    if (hostSessionId) {
+                    // `run auto` never pre-registers: the explicit id is only real when
+                    // the remote pick lands on claude. The launch-id join below records
+                    // the id the remote ACTUALLY used, whatever the pick.
+                    if (hostSessionId && runAgent !== RUN_AUTO_KEYWORD) {
                         registerInteractiveHostSession({
                             cwd: process.cwd(),
                             host: host.name,
@@ -1316,7 +1397,11 @@ export function registerRunCommand(program) {
                     // re-attach the live pane automatically instead of exiting — the user
                     // never has to notice the drop and `agents sessions focus` by hand.
                     // `raw` runs aren't tmux wrapped, so there is nothing to reconnect to.
-                    const reconnectId = hostSessionId ?? resolvedRemoteId ?? resumeId;
+                    // For `run auto` prefer the join-resolved id (the harness the remote
+                    // ACTUALLY picked) over the explicit --session-id only claude adopts.
+                    const reconnectId = (runAgent === RUN_AUTO_KEYWORD
+                        ? resolvedRemoteId ?? hostSessionId
+                        : hostSessionId ?? resolvedRemoteId) ?? resumeId;
                     if (reconnectId && !isRaw) {
                         const { reconnectInteractiveSession, SSH_CONN_FAILURE } = await import('../lib/hosts/reconnect.js');
                         if (exitCode === SSH_CONN_FAILURE) {
@@ -1482,7 +1567,7 @@ export function registerRunCommand(program) {
                 await warnUnpushedWork(resumeExec.cwd ?? process.cwd());
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports }, { shareRuntimeEnv },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports }, { shareRuntimeEnv },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -1537,7 +1622,28 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
-        if (isValidAgent(rawAgent)) {
+        if (autoHarnessRequested) {
+            // Harness layer (RUSH-2132): weighted pick across installed harnesses
+            // by best-account headroom. Zero healthy accounts anywhere fails loud
+            // — launching a default "because it's there" is how a rotate loop
+            // hammers an exhausted account.
+            const byHarness = await collectHarnessCandidates();
+            const harnessPick = pickHarnessWeighted(byHarness);
+            if (!harnessPick) {
+                console.error(chalk.red(formatNoHealthyHarnessError(classifyHarnessCandidates(byHarness))));
+                process.exit(1);
+            }
+            agent = harnessPick.picked.agent;
+            if (!options.quiet) {
+                process.stderr.write(chalk.gray(formatHarnessPickBanner(harnessPick) + '\n'));
+            }
+            // --session-id keeps its claude-only semantics: honored when auto
+            // picks claude, ignored (loudly) otherwise.
+            if (options.sessionId && agent !== 'claude' && !options.quiet) {
+                process.stderr.write(chalk.yellow(`[agents] --session-id ignored: auto picked ${agent} (only claude accepts a forced session id)\n`));
+            }
+        }
+        else if (isValidAgent(rawAgent)) {
             agent = rawAgent;
         }
         else if (profileExists(rawAgent)) {
@@ -1929,6 +2035,15 @@ export function registerRunCommand(program) {
             else {
                 try {
                     const resolved = await resolveRunVersion(agent, strategy, cwd);
+                    if (resolved.exhausted) {
+                        // Fail loud (RUSH-2132): the old behavior warned "found no
+                        // usable version; falling back to defaults" and launched the
+                        // pinned default anyway — the exact move that loops a rotate
+                        // into an exhausted account. The message text is a contract
+                        // the Factory watchdog tail-detects; do not reword it.
+                        console.error(chalk.red(formatNoHealthyAccountError(agent, strategy, resolved.exhausted)));
+                        process.exit(1);
+                    }
                     if (resolved.version) {
                         version = resolved.version;
                         rotationResult = resolved.rotation;
@@ -1938,6 +2053,8 @@ export function registerRunCommand(program) {
                         }
                     }
                     else if (!options.quiet) {
+                        // No installed version at all (not "accounts exhausted" — that
+                        // fails loud above): keep the pre-existing default resolution.
                         process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} found no usable ${agent} version; falling back to defaults\n`));
                     }
                 }