@phnx-labs/agents-cli 1.22.26 → 1.22.28

package/CHANGELOG.md

@@ -1,5 +1,298 @@
 # Changelog
 
+## 1.22.28
+
+- **`agents run` / `agents teams` `--device`/`--host`: fail loud when a pinned harness version is not installed on the target (RUSH-2313).** A concrete pin like `codex@0.145.0` is checked against the remote `agents view --json` listing during `ensureHostReady` *before* the run is marked dispatched. Missing pins exit non-zero naming the box, the pin, what is installed there, and `agents ssh <box> -- agents add <agent>@<ver>` — so detached fleet drains no longer print `Dispatched` and then die only in the remote log. Aliases (`@latest` / …) still resolve on the remote; a bare agent name still only warns. Source: `apps/cli/src/lib/hosts/ready.ts`, `dispatch.ts`, `teams/agents.ts`.
+
+- **fix: Windows-host e2e suites can resolve `win-mini` again under the hermetic device registry.** `tests/setup.ts` (RUSH-2042 / #1572) redirects `AGENTS_DEVICES_DIR` to an empty fork-private directory so unit fixtures never leak into the real fleet registry. The live `ssh-tunnel.e2e` / `browser/drivers/ssh.e2e` suites still need a real `DeviceProfile` for `AGENTS_TEST_WIN_HOST`, so after #1572 every `tests-windows-host-e2e.yml` run failed immediately with `Unknown device 'win-mini'` — even on a tailnet-joined runner that could ssh to the box. The setup file now seeds the private registry from the real fleet entry (or synthesizes one from `ssh -G <host>`) when `AGENTS_TEST_WIN_HOST` is set; the real registry is never written. Source: `apps/cli/tests/seed-e2e-win-host.ts`, `apps/cli/tests/setup.ts`.
+
+- **OpenCode timeout-sample spool dir is Windows-safe (#1869).** The generated
+  `agents-cli-hooks.ts` plugin used `PERF_SPOOL.slice(0, PERF_SPOOL.lastIndexOf("/"))`
+  to mkdir the perf spool parent. On Windows `getPerfDir()` is backslash-separated,
+  so `lastIndexOf("/")` returned -1 and the slice dropped one character — the
+  sample write was fail-silent and never landed. The plugin now imports
+  `node:path` and uses `path.dirname(PERF_SPOOL)`. Source: `apps/cli/src/lib/hooks.ts`.
+
+- **Bash-command classifier: single-source tool registry + broader unwrap (#1889).** The embedded Python activity-log hook (`ACTIVITY_LOG_HOOK_SCRIPT` in `activity.ts`) hand-duplicated `bash-command.ts`'s `TOOL_REGISTRY` and `VALUE_FLAGS` with a "keep them in sync" comment — the two had already drifted (Python was missing `rmdir`, and `agents`/`linear` two-level tools). Both tables are now generated from the TypeScript source (`pythonToolRegistryLiteral` / `pythonValueFlagsLiteral`) at module load. Separately, `unwrapCommand` (and the matching Python `_unwrap_command`) now peels `export VAR=…`, `set -euo pipefail`, `for`/`until` loop bodies, `if`/`then` branches, and `(command)` subshell prefixes that previously classified as `other`. Source: `apps/cli/src/lib/session/bash-command.ts`, `apps/cli/src/lib/activity.ts`.
+
+- **Active-session polls skip re-parsing quiet transcripts (#2047).** `computeLiveSignals` (the per-session tail/parse behind `agents sessions --active` and the menu-bar badge tick) now memoizes by transcript path + mtime + `pidAlive` inside the process, so a 30s poll no longer re-tails every live session whose file has not changed. Positive Claude transcript-path resolutions are also memoized while the file still exists, avoiding a full walk of every Claude version-home `projects/` tree per pid per tick. Source: `apps/cli/src/lib/session/active.ts`.
+
+- perf(sessions): throttle headless `ps`/`lsof` scan + memoize process table across an active-session poll (#2047)
+
+- **`agents routines devices --set` / `--clear` no longer abort when a fleet peer is offline (#2118).** Pinning a routine used to fan out pause/resume to every registered device and throw on the first unreachable one — often *after* the pin had already succeeded on the target — so a single asleep laptop made fleet pins unusable and the error looked like the pin failed. Offline peers are now skipped with a warning; the command exits non-zero only when a *selected* target device cannot be reached. Source: `apps/cli/src/commands/routines.ts`.
+
+- **`agents models claude` no longer lists a per-cloud bare-minor id as a plain catalog entry (#2233).** The id-scan fallback (`scanClaudeCatalogIds`, used when the structured alias/perCloud maps yield fewer than two models) used to surface short forms like `claude-opus-4-1` that only appear as a `foundry:` / cloud-scoped field next to a real firstParty id (`claude-opus-4-1-20250805`). `dropBareLegacyIds` now drops **any** id that is a dash-boundary prefix of a more-specific sibling also present in the scan — covering both the bare-major `.includes("claude-opus-4")` artifacts (#1892) and these bare-minor cloud-metadata values — while keeping genuine bare currents with no sibling (`claude-sonnet-5`) and not collapsing `claude-opus-4-1` into `claude-opus-4-10`. Source: `apps/cli/src/lib/models.ts`.
+
+- **Menu-bar dropdown density toggle removed.** The `Density: Auto/Rich/Compact` footer item and the whole rich/compact rendering fork are gone; the dropdown now always renders the rich rows (session/work titles, expanded Routines and Recent sections). Removes the `menubarDensity` UserDefaults key and `MENUBAR_DENSITY` env override, and updates the menu-bar docs to match. Source: `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`, `apps/cli/docs/menubar.md`.
+
+- **The macOS secrets broker can now hold an explicit key subset under its own lease id and expiry (RUSH-2255).** `agents secrets lease <bundle> --keys K1,K2 --for 8h` authenticates once, stores only those resolved values in broker memory and the restart session, and reports lease metadata without exposing values. Unknown, missing, and expired keys fail closed. Source: `apps/cli/src/{commands/secrets.ts,lib/secrets/{agent,lease,session-store}.ts}`.
+
+- **Scoped leases can now be listed and revoked by id (RUSH-2256).** `agents secrets leases` shows bundle, keys, and remaining lifetime; `agents secrets revoke <lease-id>` wipes exactly that broker grant and its restart session. Source: `apps/cli/src/{commands/secrets.ts,lib/secrets/{agent,session-store}.ts}`.
+
+- **Fleet devices accept an explicit SSH private-key path (RUSH-2265).** `agents devices set <name> --auth key --identity-file <path>` stores the path on that device and every shared SSH invocation passes it to OpenSSH with `-i`, so devices no longer depend on whichever key the ambient ssh agent happens to offer. Switching a device from password to key auth also removes stale password-bundle metadata from the registry.
+
+- **Detached agent dispatch now runs on Windows OpenSSH hosts (RUSH-2267).** Headless `agents run … --host <windows>` launches through a hidden PowerShell process, preserves actor/session/env context, and uses durable Windows-native log, follow, reconcile, stop, and cleanup operations.
+
+- **`agents repo pull` fast-forwards a clean behind-only checkout instead of failing with "Cannot rebase onto multiple branches" (RUSH-2282).** After fetch, a 1-behind tree integrates via `merge --ff-only` against the tracking ref; only genuinely diverged histories enter rebase. Avoids re-running `git pull --rebase` on a multi-entry `FETCH_HEAD` (common after bare fetch when the remote has several branches, or under concurrent fleet fetch). Source: `apps/cli/src/lib/git.ts` `pullRepo`.
+
+- **`agents perf` splits intentional deny (exit 2) from crashes (exit 1) — hook health is readable again (RUSH-2294).** Deny-by-design guards (`ask-user-question-guard`, `plan-html-reminder`, `git-guard`, …) exit 2 on purpose; the warehouse previously counted any nonzero exit as `errorCount`, so a working guard read as a "92%-error" hook. Exit 0 = allow, exit 2 = `blockCount`/`blockRate`, exit 1 / other = `errorCount`/`errorRate`. The hooks table column is now `ERR/BLOCK/TO` (`err:…% block:…% to:…%`). JSON rows gain `blockCount`/`blockRate`. Source: `apps/cli/src/lib/perf/db.ts`, `apps/cli/src/lib/hooks/profile.ts`, `apps/cli/src/commands/perf.ts`.
+
+- **Claude launches reuse an unchanged file-backed setup-token instead of decrypting it on every exec (RUSH-2317).** The process-lifetime cache is isolated by version home and invalidates from the encrypted credential file's identity, ctime, mtime, and size; token rotation is picked up on the next launch, missing per-account tokens are negatively cached, and plaintext tokens remain memory-only. Source: `apps/cli/src/lib/claude-account-token.ts`, `apps/cli/src/lib/secrets/filestore.ts`.
+
+- **Repeated full session listings reuse stable transcript membership (RUSH-2318).** The process briefly caches settled transcript directories by mtime+size, rereads recently changed directories, and expires every entry within the filesystem timestamp-precision window, avoiding burst-time repeat reads without hiding filesystem-only creates or deletes. Source: `apps/cli/src/lib/session/db.ts`.
+
+- **`agents sync --yes` drops ~1s/agent of dead work and reuses still-fresh fingerprints (RUSH-2320).** Measured on a real install: `getActuallySyncedResources` was ~1055 ms/agent on the unattended path that never reads it; `buildManifest` re-hashed every file (~716 ms) after a no-op force sync; the guard-hit path spent ~12 ms building inventories it then discarded. Unattended sync now skips the interactive inventory, the skills detector is stat-first on size before any content read, `buildManifest` carries still-fresh fingerprints from the previous manifest, and `syncResourcesToVersion` runs its no-change guard before pattern expansion (accepting a caller-supplied `available` inventory so multi-version fan-out does not re-scan). Source: `apps/cli/src/lib/refresh.ts`, `apps/cli/src/lib/versions.ts`, `apps/cli/src/lib/staleness/`.
+
+- **fix: `agents run <agent>` no longer dead-ends when every account is logged out — it launches so you can sign in.** A harness with one installed, signed-out version had no reachable login path at all: `agents run cursor` exited with `no healthy cursor account under strategy 'balanced' — excluded: 2026.07.23 (signed_out)`, the `agents run cursor@` account picker marked the logged-out row `disabled` and offered only `No usable accounts — cancel`, and `agents use cursor` only set a default. The zero-healthy guard (RUSH-2132) treated a missing login like an exhausted account, but they are opposites — a throttled account must not be launched, while a signed-out one is fixed precisely BY launching, since the harness's own TUI is the login surface. On a human-facing terminal run (a real TTY and no `--json`), a single sign-in-recoverable account now launches directly (naming the version and the login command) and several open the account picker with auth-blocked rows selectable and labelled `launch to sign in`; `rate_limited` / `out_of_credits` still fail loud, and off a TTY — or under `--json` — both classes keep the exact watchdog-parsed error, now with the harness's login command alongside `--strategy pinned`. Source: `apps/cli/src/lib/rotate.ts` (`isSignInRecoverable`, `signInRecoverableCandidates`), `apps/cli/src/commands/run-account-picker.ts` (`pickSignInLaunchVersion`), `apps/cli/src/commands/exec.ts`. (RUSH-2334)
+
+- **`sessions --active` no longer shows retained dead/queued rows, and every process row now carries its PID (RUSH-2336).** Bare `--active` (CLI table/JSON, the interactive browser, `focus`, and the menu bar) previously kept a row alive as long as its pid wasn't *known* dead — so a queued-but-not-started row, or a process of genuinely unverified liveness, could still show up. The canonical selector (`isRunningLiveSession`) now excludes `queued`/`closed`/`crashed` outright (still reachable via `--queued`/`--closed`/`--crashed`) and requires a real process row to positively verify its machine, a positive pid, and `pidAlive === true`; a cloud row stays active on its provider + task id alone. Every process-backed `--active --json` row now guarantees `machine`/`pid`/`pidAlive: true`, and the human CLI row and the menu bar's session detail both show the matching `machine:pid` (or `provider · taskId` for cloud) locator. Source: `apps/cli/src/commands/sessions.ts`, `apps/cli/src/lib/menubar/snapshot.ts`, `apps/cli/menubar/Sources/MenubarHelper/`.
+
+- **`agents projects status` card scans faster: grouped warnings, a fleet health summary, and a truthful `dead` label (RUSH-2337).** On a busy fleet the card printed each host's git drift twice — once in the inline `fleet` table, then again as one 2-line block per host in the warnings footer (18 lines for 3 facts) — and read `dead 41 finished or lost (41 crashed)`, which contradicts itself when every dead session is a crash. Now: (1) the warnings footer **groups by root cause** — all behind hosts collapse to one warning listing each with its count (`4 hosts behind origin/main — mac-mini ↓172, yosemite-m2 ↓217, …`) under one shared remediation, dirty/missing the same, a lone host keeps its full sentence, grouped per probed path so two repos never merge (mirrors doctor's `emitGroup`); (2) a one-line **fleet health summary** (`6/13 clean · 4 behind · 4 dirty · 1 missing`) sits above the per-host table, which keeps its branch/drift detail; (3) the `dead` row names the status directly when singular (`dead  41 crashed`); (4) the fleet-wide rollup carries a `fleet snapshot · as of HH:MM` stamp; (5) `linear` shows a completion percent (`468/547 done (86%)`). Source: apps/cli/src/lib/project-probe.ts, apps/cli/src/lib/project-status.ts, apps/cli/src/commands/projects.ts, apps/cli/docs/11-projects.md.
+
+## 1.22.27
+
+- **`agents sessions --teams` groups sessions by team (RUSH-1997).** Instead of one flat list with a `[team/handle]` tag, `--teams` now prints a report grouped by team: each team names its spawner (the orchestrator session that created it) and spawn time, and every teammate row shows its mode + handle. Team-flagged spawns that carry no teammate `meta.json` — headless `agents run` sessions, or teammates whose team record aged out — sink into a trailing `(no team)` bucket, so a real `agents teams` teammate and a bare SDK spawn are never shown as the same thing. `--teams --flat`/`--tree` keep the plain inline table, and a search query keeps the interactive picker. `TeamOrigin` (also on `--teams --json`) now carries the teammate's `startedAt` spawn time and a `source` (`meta` = teammate, `entrypoint` = bare spawn). Source: `apps/cli/src/lib/session/team-filter.ts`, `apps/cli/src/commands/sessions.ts`.
+
+- **`agents run --device auto` and `agents teams add --device auto` now choose from live fleet health instead of 14-day launch affinity (RUSH-2001).** The picker probes candidates in parallel, excludes unreachable, overloaded, and missing-agent machines, prefers signed-in candidates with the lowest normalized load, and keeps execution local when no remote is better. Remote readiness now uses `agents view --json`, preserving the installed/sign-in split instead of treating every remote sign-in state as unknown. Source: `apps/cli/src/lib/smart-launch.ts`, `apps/cli/src/lib/teams/placement-probe.ts`, `apps/cli/src/lib/hosts/ready.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/src/commands/teams.ts`.
+
+- **`agents devices harnesses` / `agents devices accounts` — per-device harness + account readiness (RUSH-2003).** Two new fleet lenses: `harnesses` lists every installed `agent@version` across the fleet with its account, signed-in state, quota (highest usage-window utilization; `*` = cached snapshot), and a single `ready` verdict (signed in AND not rate-limited); `accounts` collapses that to one row per account, naming which harnesses share it. Both SSH-probe each online device (bounded like `fleet ping`, so one unreachable box can't stall the glance) and read the daemon-warmed usage cache — `--refresh` (`--live`) forces a live quota read. Scope with `--agents <csv>` / `--device <csv>`; `--json` emits per-host rows (harnesses) or account groups (accounts). Source: `apps/cli/src/lib/devices/harness-inventory.ts`, `apps/cli/src/commands/ssh.ts`.
+
+- **A session that ran on another device now resumes ON that device, and a typo'd
+  command with `--host` says `unknown command` (RUSH-2022).** Two bugs found while
+  recovering ~15 sessions after a machine crash, both of which sent recovery down the
+  wrong path.
+
+  (1) **`agents resume <id>` restarted a remote session locally.** The harness keeps its
+  conversation state on the machine that produced the session, but nothing checked which
+  machine that was — so a peer-owned session started the agent here, against state this
+  box had never seen (`sessions-resume.ts` even swapped in `process.cwd()` when the
+  recorded directory did not exist locally). `agents resume` now re-runs itself on the
+  owning device over SSH; `--here` overrides. The bare `agents sessions` picker routes
+  the same way, and `agents sessions attach` hops as an **attach** (its detach record and
+  the headless process it stops both live on the owner). The multi-select
+  `agents sessions resume` inherits it: each tab it opens runs the canonical
+  `agents resume <id>`, which now routes itself, and its no-tab-backend path routes
+  explicitly. Root cause of
+  the population that made this common: a run dispatched with `agents run --device
+  <box>` was indexed with no origin machine at all, so the index claimed the dispatching
+  box; it now records `<box>`, which also means such a run finally shows up under
+  `agents sessions --host <box>`. Source: `apps/cli/src/lib/session/resume-owner.ts`,
+  `apps/cli/src/lib/hosts/session-index.ts`, `apps/cli/src/commands/resume.ts`.
+
+  The hop carries its "don't route again" pin as an exported env var, not a flag, so it
+  works against a peer still on an older CLI. Sessions indexed *before* this release keep
+  their old machine tag — re-dispatch or a fresh scan corrects them.
+
+  (2) **The `--host`/`--device` router answered for commands that do not exist.** It runs
+  before commander parses, so `agents session resume --host <box>` (one letter off
+  `sessions`, which *does* accept `--host`) reported ``  `agents session` does not support
+  --host/--device `` — a true statement about a command nobody typed and the opposite of
+  the truth for the one they meant. Unknown names now fall through to `unknown command
+  '<name>'` with a did-you-mean, and the spellcheck can suggest the lazily-registered
+  groups (`sessions`/`teams`/`cloud`/…) it previously could not see. A real command with
+  no remote semantics still gets the flag-support error. Source:
+  `apps/cli/src/lib/hosts/passthrough.ts`, `apps/cli/src/lib/startup/command-registry.ts`.
+
+- **`agents publish` is in the lazy command table.** `commands/packages.ts` registers it at
+  top level but the registry did not list it, so it only resolved through the
+  unknown-command fallback that loads the whole command tree. Found by the new test that
+  pins the command-name set against the real tree.
+
+- **A mistyped command keeps its `--host`.** The distance-1 auto-correct now runs *before*
+  the router instead of after commander gave up, so `agents docto --host <box>` corrects to
+  `doctor` **and** runs on `<box>` — previously the corrected command re-parsed locally with
+  a `--host` it did not accept. Four routing-table entries naming commands that do not exist
+  (`cli`, `packages`, `versions`, `daemon`) were removed; a test now keeps both routing
+  tables to real command names.
+
+- **Cross-machine `agents … --json` fan-out caps each peer's stdout at 16 MiB
+  instead of buffering it unbounded (RUSH-2065).** The shared fan-out
+  (`gatherRemoteAgentsJson`, behind `agents sessions --active`, `agents feed`, and
+  every other fleet-wide JSON sweep) streamed each peer's output into memory with
+  no ceiling, under one `Promise.all` — so a single peer returning a corrupt or
+  pathologically large payload could retain ~170 MB and OOM the whole sweep. Each
+  peer's capture now stops and SIGKILLs the connection once it would exceed the
+  ceiling, treating that box as unreachable (reported in `skipped`) so the rest of
+  the fleet still renders. The bound and the UTF-8-safe accumulator now live once
+  in `apps/cli/src/lib/ssh-exec.ts`, shared with the `agents sessions` browse
+  fan-out that already had the guard. Source: `apps/cli/src/lib/remote-agents-json.ts`,
+  `apps/cli/src/lib/ssh-exec.ts`, `apps/cli/src/lib/session/remote-list.ts`.
+
+- **Auth-health probes once per account, not once per version home (RUSH-2111).**
+  The daemon's every-3-minute auth-health refresh fanned `probeLocalFleetAuth`
+  over *every* installed version home at once, so a box with several Claude homes
+  signed into one account fired that many concurrent requests at the same
+  provider OAuth endpoint — racing its rate limit into a `429` that then parked
+  the whole box's usage reads behind a `Retry-After` penalty (`usage-backoff.ts`
+  survives that penalty; this removes its cause). Installs are now grouped by
+  account and the live probe runs once per (agent, account), fanning the one
+  verdict out to each home's per-version cache row. Homes with no resolvable
+  account are still probed individually. Source: `apps/cli/src/lib/auth-health.ts`.
+
+- **Fallback-chain agents now receive their own active rules preset before dispatch (RUSH-2129).** `runWithFallback` resolves each attempted entry's harness/version home and runs the same skip-fast preset synchronization as the primary `agents run` path, so a rate-limit handoff cannot launch against stale rules. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/rules/run-sync.ts`.
+
+- **Gemini hard-deprecation: routines daemon can no longer execute a legacy Gemini routine (RUSH-2202).** RUSH-2060 gated `agents add`/`import`/`sync`/`run`/`routines add` against a hard-deprecated harness, but the routines daemon's own executor (`runner.ts`) had no equivalent gate — a Gemini routine written before RUSH-2060, or synced/edited on disk directly, would still fire and try to build a `gemini …` command against a backend Google retired. `executeJob`/`executeJobDetached` now reject a hard-deprecated agent up front, before any version/account resolution or sandbox prep, and record a `failed` run with the same deprecation message every other entry point already shows. Also removed the now-unreachable Gemini model-catalog extractor (`models.ts`), Factory's Gemini model-catalog fetch (`agentModels.ts`), and the dead Gemini sandbox-config writer (`sandbox.ts`/`gemini-settings.ts` — its generic JSON helpers stay, since Antigravity's permission writer reuses them), plus a stale `profiles.md` doc line still listing `gemini` as a live profile agent. Source: `apps/cli/src/lib/runner.ts`, `apps/cli/src/lib/models.ts`, `apps/cli/src/lib/sandbox.ts`, `apps/cli/src/lib/gemini-settings.ts`, `apps/factory/src/core/agentModels.ts`.
+
+- **Routine transcripts now archive as `origin='routine'` sessions (RUSH-2271).** A
+  Claude (and Codex) routine writes its transcript to the per-version `CLAUDE_CONFIG_DIR`
+  / `CODEX_HOME` home, not the sandbox overlay the archiver scanned — so routine runs
+  were indexed as ordinary `origin='cli'` sessions and never linked to their routine or
+  run. `archiveRoutineTranscripts` now reads the same per-version home `buildExecEnv`
+  writes to (re-pointed to each failover attempt's account as the chain advances), scoped
+  by a pre-spawn baseline so it copies only that run's transcript out of the shared home,
+  and `agents sessions --routine` shows them again. Kimi relocates too but its
+  routine-archive discovery reader is a separate follow-up. Source:
+  `apps/cli/src/lib/runner.ts`, `apps/cli/src/lib/routines.ts`.
+
+- **Release lease detects a holder killed from outside (RUSH-2274).** An externally
+  killed release (SIGKILL, a severed ssh, a rebooted box) left its lease on `origin`
+  and `scripts/release-lease.sh status` read `held` for up to the 30-minute TTL with
+  nothing actually releasing. The lease now records the holding `host`, `pid`, and
+  that pid's start time, and `status` reports `holder-alive=yes|no|unknown`. A holder
+  that is provably gone is reclaimed by the next `claim` immediately instead of
+  waiting out the TTL, and a new `release-lease.sh clear` drops such a lease without
+  starting a release. A live holder is never taken at any age, an unprobeable one
+  (another box, or a lease from an older release) still falls back to the TTL, and a
+  reused pid or an unreaped zombie counts as dead rather than as a live release.
+  Source: `apps/cli/scripts/release-lease.sh`, `apps/cli/scripts/release.sh`.
+
+- **`agents output` and the session index no longer under-count Windows hosts
+  (RUSH-2286).** A Windows box could report zero token burn / zero sessions even
+  when it was actively used, because two per-harness scanners in
+  `session/discover.ts` failed on Windows: the OpenClaw scan gated on `which
+  openclaw`, which is POSIX-only (`which` throws ENOENT on Windows, so the whole
+  OpenClaw scan silently returned before indexing anything), and the Grok scanner
+  recovered a session's version from `summary.grok_home` with a `/`-only regex
+  that never matched a backslash-separated Windows path. The OpenClaw presence
+  check now uses the cross-platform `hasCommand`, its `openclaw` invocations route
+  through `execFileShellSpec` so a Windows `.cmd`/`.ps1` shim actually launches,
+  and the Grok version regex normalizes separators first. Separately, JSON relayed
+  from a Windows peer over SSH (`agents output --host <win> --json`,
+  `agents sessions … --json`) is now stripped of any PowerShell `#< CLIXML`
+  banner before parsing (`stripClixml` in `hosts/remote-cmd.ts`), so a fleet-wide
+  rollup that folds in a Windows box no longer drops it on a `JSON.parse` failure.
+  The banner strip is applied at every remote-`--json` boundary a Windows peer's
+  output flows through: the `remote-agents-json` fan-out, the session
+  `remote-list` list/payload/tool-search parsers, the `--host` fleet passthrough
+  (`agents view --host all`), and `agents output`'s per-device fetch.
+  Source: `apps/cli/src/lib/session/discover.ts`,
+  `apps/cli/src/lib/hosts/remote-cmd.ts`, `apps/cli/src/lib/hosts/passthrough.ts`,
+  `apps/cli/src/lib/remote-agents-json.ts`,
+  `apps/cli/src/lib/session/remote-list.ts`, `apps/cli/src/commands/output.ts`.
+
+- **`agents output` now reports the burn split and a `--pricing no-cache` scenario (RUSH-2287).**
+  The productivity rollup collapsed token burn into a single counter. It now
+  breaks the burn into uncached **input** / **cache-read** / **cache-write** tokens
+  wherever the harness records a per-message cache split (Claude, Codex, Gemini,
+  Droid) — a `burn split:` line in the text report and the three counts on `burn`
+  and every `breakdown` row in `--json`. New `--pricing no-cache` reprices cached
+  tokens at the model's full input rate to model "what would this cost with caching
+  off?"; the text report leads with that figure (breakdown column `burn(nc)`) while
+  `--json` always carries **both** `costUsd` and `costUsdNoCache` so a dashboard can
+  choose. The saving is surfaced in actual mode too (`caching: actual $X vs no-cache
+  $Y`). Backed by four new session columns (`input_tokens`, `cache_read_tokens`,
+  `cache_write_tokens`, `cost_usd_nocache`, schema v37) populated at scan time;
+  pre-upgrade sessions show total-only until re-scanned. Source:
+  `apps/cli/src/commands/output.ts`, `apps/cli/src/lib/session/{db,discover}.ts`,
+  `apps/cli/src/lib/pricing/cost.ts`.
+
+- **Routine failures now reach the owner's phone, not just the local desktop (RUSH-2288).**
+  A `failed`/`timeout` routine finish, or a pre-spawn failure such as `auth_failed`, now
+  also pings the owner over the same channel stack `agents notify` uses (the
+  `owner.channels` in `humans.yaml`, or the legacy `notify.owner`), delivered in-process by
+  the daemon — no shelling out to `ssh mac-mini agents notify`. This closes the gap where a
+  failed scheduled routine on a headless fleet box was invisible, and specifically covers
+  the `auth_failed` case the per-routine `agents notify` prompt can never send (its agent
+  never spawned). If the primary owner channel cannot deliver from the box, the daemon walks
+  the remaining configured channels as fallbacks (Telegram and intrusive/voice channels are
+  excluded). Green routines of any kind stay silent, the existing desktop thresholds are
+  unchanged, and delivery is deduped per job+runId. Source:
+  `apps/cli/src/lib/routine-notify-owner.ts`, `apps/cli/src/lib/daemon.ts`.
+
+- Add `agents bench list`, `agents bench run`, and `agents bench results`: benchmark cells fan out through the existing `agents run` path with isolated fixture copies, bounded concurrency, custom harness names, wall-time/exit/token capture, and durable JSON results under `~/.agents/.history/bench/` (RUSH-2302, RUSH-2303).
+
+- **New user quickstart: install, harnesses, teams, fleet.** `apps/cli/docs/QUICKSTART.md` walks a fresh install through `agents setup`, adding and logging into harnesses, a minimal `agents teams` smoke test, and setting up a fleet (`agents devices sync`, `agents devices set-interactive`, `agents apply`) — linked from `docs/README.md` and the root README's Quickstart. Docs only — no runtime change. Source: `apps/cli/docs/QUICKSTART.md`, `apps/cli/docs/README.md`, `README.md`.
+
+- **`agents insights` detects agent silent stalls (model goes idle until you resume).**
+  When the assistant is last to speak and the next user message is ≥5 minutes later,
+  facets count duration-bucketed `silent stall: 5-15m` / `15-60m` / `1h+` friction
+  signals; resume nudges (`continue`, `keep going`, …) after that silence also count
+  as `resume after silent stall`. Report, actions, `--narrative`, and
+  `/sessions-insights` instruct models to call these out (not reframe as "user was
+  slow"). Extractor version bumped to 5 so cached facets recompute. Source:
+  `apps/cli/src/lib/session/insights.ts`, `commands/insights.ts`,
+  `docs/06-observability.md`.
+
+- **`agents insights` splits silent stalls by harness and model.** The By-agent/account
+  table now shows per-group stall and resume-nudge counts (so laziness is visible without
+  `--json`). Stalls are also attributed to the model that last spoke
+  (`silentStallsByModel`, "Silent stalls by model" section). Extractor version 6.
+  Source: `apps/cli/src/lib/session/insights.ts`, `commands/insights.ts`.
+
+- **Redact Claude OAuth setup-tokens (`sk-ant-oat01-…`) from logs and exports, and reject a malformed one before it reaches the auth header (#1767).** The log redactor masked API keys (`sk-ant-api03-…`) but not OAuth setup-tokens — the generic `sk-` rule can't reach an `oat01` token because the hyphen after `ant` breaks its run — so a captured setup-token could leak verbatim into a run log or session export. `resolveClaudeSetupToken` also now validates the stored value: a corrupt `auth` bundle entry (e.g. a captured `claude setup-token` TTY banner+ANSI blob, the exact #1767 shape) is refused instead of being injected as `CLAUDE_CODE_OAUTH_TOKEN` → an invalid `Authorization: Bearer` header that crashes the run; the caller falls back to the normal login. Source: `apps/cli/src/lib/redact.ts`, `apps/cli/src/lib/claude-account-token.ts`.
+
+- **Stop the interactive host auto-reconnect spinning forever on a flapping link
+  (#1884).** A reattach only refills the retry budget now if it reached the host
+  **and** held the remote pane for at least 10 seconds. Before, the budget refilled
+  on the preflight probe alone, so a link that reconnected and dropped the user
+  straight back out — or an attach that died at TTY negotiation every time — printed
+  `Reconnecting … (attempt 1/6)` on every cycle forever and `MAX_ATTEMPTS` bounded
+  nothing. A link that keeps dropping now spends the budget and gives up with a
+  message that says so ("kept dropping again within 10 seconds of getting back in"),
+  distinct from the unreachable-host "couldn't reconnect". A session that blinks all
+  day and reconnects into a working pane each time is unaffected. Source:
+  `apps/cli/src/lib/hosts/reconnect.ts`, `docs/hosts.md`.
+
+- **`agents models claude` no longer lists bare legacy ids that 404 (#1892).** The
+  native-binary id-scan fallback (`scanClaudeCatalogIds`, used when the curated maps
+  come up empty) is now word-boundary anchored and matches the id body atomically, so
+  it can't scrape a bare-major prefix (`claude-sonnet-4`) out of the binary's own dotted
+  `claude-sonnet-4.6` "Typo in model ID" troubleshooting string, out of a suffix-glued
+  token (`claude-opus-4-1x`), or out of a token glued to a preceding identifier char. The
+  existing `dropBareLegacyIds` sibling-drop still removes the standalone
+  `.includes("claude-opus-4")` prefix-check artifacts; genuine bare currents
+  (`claude-sonnet-5`) are kept. Catalog output is unchanged across all shipped Claude
+  binaries. Source: `apps/cli/src/lib/models.ts`.
+
+- **Make ended-session focus open the correct recovery target (#2108).** `agents sessions focus <id>` now reaps metadata-less dead tmux panes, proves the indexed transcript belongs to the exact active version home before native resume, launches Claude from the transcript's original project directory, and passes replacement-version `/continue` as an interactive positional prompt. Source: `apps/cli/src/lib/session/recovery.ts`, `apps/cli/src/lib/tmux/session.ts`, `apps/cli/src/lib/exec.ts`.
+
+- **The multi-install warning now inventories copies outside `PATH` and flags
+  legacy installs that can corrupt the shared macOS helper bundle (#2147).**
+  Discovery covers NVM, fnm, Volta, Bun, common npm global prefixes, and npm's
+  `_npx` cache in addition to resolving every `agents` entry on `PATH`. Dev
+  installs are no longer hidden: a copy without the atomic
+  `app-bundle-install` module is labelled `unsafe legacy helper installer —
+  remove this copy`, because invoking it can still replace a live `.app` with a
+  partial bundle. Source: `apps/cli/src/lib/self-update.ts`,
+  `apps/cli/src/index.ts`.
+
+- **Newest signed agents-cli install owns the menu-bar helper (#2210).** On multi-install Macs (e.g. Homebrew + nvm), a newer release now takes over the helper immediately and an older install can no longer reclaim or downgrade it. Equal-version foreign installs keep the existing owner; missing-helper, Developer-ID repair, and unversioned legacy cooldown behavior are unchanged. Source: `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **Layered resource listing is ~40% faster.** `getActiveResourceProfile()` read
+  `agents.yaml` twice per call — once up front, then again inside
+  `getActiveResourceProfileName()` — and `listResources()` calls it once per
+  resolved resource, so a listing paid two memoized `readMeta()` round-trips
+  (`ensureAgentsDir()` plus four `stat`s each) for every entry. Reading it only
+  after the profile name is known drops one of them. Measured on `yosemite-s1`
+  against the real `~/.agents`: one pass over all eight resource kinds (135
+  entries) went 10.52 ms → 6.23 ms, and `agents doctor --json` spends ~243 ms in
+  this path across 95 listings. No behavior change: the read count is never
+  higher on any path and is unchanged whenever a profile name resolves — the one
+  saved read is the up-front one that the `if (!name) return null;` guard now
+  skips. The `ensureAgentsDir()` side effect is unchanged because
+  `getActiveResourceProfileName()` always reaches `readMeta()`, via
+  `brand.ts` `listBrands()` when a brand is set and via
+  `resource-profiles.ts` otherwise. Source:
+  `apps/cli/src/lib/resource-profiles.ts`.
+
+- **Routine session discovery now supports an interactive picker and fuzzy names (RUSH-1998).** `agents sessions --routine` opens a routine picker on a TTY with each routine's last run, run count, and latest-run session count; the selected sessions are grouped by run ID and timestamp. `--routine <name>` accepts exact, substring, or unambiguous typo matches, and `--routines` is an alias for the same session filter.
+
+- **Secret leases now have one scoped, time-boxed domain model (RUSH-2254).** A lease names one bundle, an explicit validated key subset, an absolute expiry, harness scope, and sleep-persistence posture. Durations use the broker's 1-minute to 30-day safety bounds, duplicate keys normalize once, unknown keys fail closed, and expired leases cannot project values. Source: `apps/cli/src/lib/secrets/lease.ts`.
+
+- **Fleet devices accept an explicit SSH private-key path (RUSH-2265).** `agents devices set <name> --auth key --identity-file <path>` stores the path on that device and every shared SSH invocation passes it to OpenSSH with `-i`, so devices no longer depend on whichever key the ambient ssh agent happens to offer. Switching a device from password to key auth also removes stale password-bundle metadata from the registry.
+
+- **`agents doctor` diagnoses Windows OpenSSH public-key enrollment (RUSH-2266).** On Windows it reads the effective `AuthorizedKeysFile`, selects the ProgramData administrator file or per-user profile file, verifies a public-key record is present, and checks that the administrator file grants `FullControl` to only `SYSTEM` and `Administrators`. The audit is read-only and never reads or prints private keys or passwords; fleet doctor forwards a locally authored summary and directs operators to run doctor on that box for details.
+
 ## 1.22.26
 
 - Make bare `agents setup` a re-runnable onboarding hub with live capability status and direct access to browser, computer, secrets, fleet, share, watchdog, and preference wizards.

package/README.md

@@ -11,7 +11,7 @@
   <a href="https://github.com/phnx-labs/agents-cli"><img src="https://img.shields.io/badge/github-phnx--labs%2Fagents--cli-blue?style=flat-square" alt="github" /></a>
 </p>
 
-**The missing toolchain for CLI coding agents.** Run any agent on your existing subscription. Spawn parallel teams in isolated terminals or dispatch to the cloud for a PR. Watch live state across the fleet, nudge stalled runs, and message agents mid-flight. Schedule routines and set monitors that fire an agent when a source changes, drive browsers and Electron apps, store secrets behind Touch ID, and file tickets from a menu-bar bar — all from one CLI.
+**A framework for running a distributed agent factory.** Dispatch Claude, Codex, Antigravity, Grok, and more across your own machines, in parallel, on your existing subscriptions. Measure every run with `agents perf` / `agents insights`, fold what you learn back into `AGENTS.md` and skills, then put the loop on a schedule with routines and monitors. Spawn parallel teams in isolated terminals or dispatch to the cloud for a PR. Watch live state across the fleet, nudge stalled runs, and message agents mid-flight. Store secrets behind Touch ID, drive real browsers and Electron apps, and steer the whole fleet from a menu bar — all from one CLI.
 
 <p align="center">
   <a href="https://github.com/anthropics/claude-code" title="Claude Code"><img src="assets/harnesses/anthropic.svg" height="32" alt="Claude Code" /></a>
@@ -52,26 +52,33 @@ agents run claude "explain this repo"  # run any agent on your existing subscrip
 
 `agents setup` is interactive and idempotent -- safe to re-run on any machine. Once core setup exists, it opens a status-aware menu for browser, computer, secrets, fleet, share, watchdog, and device preferences; each choice delegates to the same wizard available under `agents setup <capability>`. In CI or another non-TTY, bare setup prints the checklist without prompting. The `agi-cli.sh` one-liner installs this same canonical `@phnx-labs/agents-cli` package. Prefer bun? `bun install -g @phnx-labs/agents-cli` works too.
 
+Full path -- installing harnesses, logging in, smoke-testing `agents teams`, and setting up your own fleet: [`apps/cli/docs/QUICKSTART.md`](apps/cli/docs/QUICKSTART.md).
+
 Already installed? `agents upgrade` updates agents-cli itself to the latest version (`agents upgrade 1.2.3` for a specific version or dist-tag, `-y` to skip the confirm prompt). The command is `upgrade` on every platform -- there is no `agents update` (on macOS, `agents helper update` is a different command that reinstalls the keychain helper, not agents-cli).
 
 Source: [github.com/phnx-labs/agents-cli](https://github.com/phnx-labs/agents-cli)
 
 Also available as `ag` -- all commands work with both `agents` and `ag`.
 
-- [Pin versions per project](#pin-versions-per-project)
+- [Factory loop](#factory-loop)
 - [One config, every agent](#one-config-every-agent)
 - [Run any agent](#run-any-agent)
 - [Sessions across agents](#sessions-across-agents)
 - [Control the fleet](#control-the-fleet)
 - [Sync the fleet](#sync-the-fleet)
-- [Run open models through Claude Code](#run-open-models-through-claude-code)
+- [Pin versions per project](#pin-versions-per-project)
+- [Run open models through Claude Code](#run-open-models-through-claude-code-experimental)
+- [Run on your own machines](#run-on-your-own-machines)
 - [Teams](#teams)
 - [Cloud](#cloud)
 - [Workflows](#workflows)
+- [Plugins](#plugins)
+- [Make it yours](#make-it-yours)
 - [Browser](#browser)
 - [Secrets](#secrets)
 - [Routines](#routines)
 - [Monitors](#monitors)
+- [Share](#share)
 - [PTY](#pty)
 - [Portable setup](#portable-setup)
 - [Menu bar](#menu-bar)
@@ -82,34 +89,35 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 
 ---
 
-## Pin versions per project
+## Factory loop
 
-```bash
-# This project needs claude@2.0.65 -- newer versions changed tool calling.
-agents use claude@2.0.65 -p
-
-# The monorepo uses codex@0.116.0 across the team.
-agents use codex@0.116.0 -p
-```
-
-This creates an `agents.yaml` at the project root:
-
-```yaml
-# agents.yaml (commit this to your repo)
-agents:
-  claude: "2.0.65"
-  codex: "0.116.0"
-```
-
-Think `requirements.txt` for CLI coding agents, on steroids. A shim reads `agents.yaml` from the project root and routes `claude` / `codex` / `antigravity` / `grok` (and others) to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources.
+The same loop whether it's one agent on your laptop or a fleet across a dozen machines: dispatch work, measure what happened, fold the lesson back into the harness, then put it on a schedule.
 
 ```bash
-agents add claude@2.0.65     # Install a specific version
-agents add codex@latest       # Install latest
-agents add codex@oldest       # Install the oldest published version
-agents view                   # See everything installed
+# Dispatch a team across the fleet -- each teammate in its own worktree
+agents teams create checkout --devices yosemite-s0,yosemite-s1
+agents teams add checkout claude "Owns: app/payments/*" --name payments
+agents teams add checkout codex  "Write tests for the new code" --name qa --after payments
+agents teams start checkout --watch
+
+# Measure what happened -- latency, friction, dead-weight skills
+agents perf commands --days 7      # slowest CLI entrypoints
+agents insights --since 30d        # friction, harness comparison, ranked actions
+
+# Fold the lesson back into the harness -- every agent picks it up next run
+agents rules add ~/lessons/payments-review.md --agents claude
+agents skills add ~/skills/payments-review --agents claude
+
+# Put it on a schedule so it runs itself
+agents routines add nightly-payments-audit \
+  --schedule "0 2 * * *" --agent claude --prompt "Audit payments/* for regressions"
+
+# Steer the fleet this loop runs on from the menu bar
+agents menubar setup
 ```
 
+`agents perf` reads a disposable warehouse at `~/.agents/.cache/perf/perf.db` -- hook, command, and run timing rollups, deletable any time. `agents insights` (alias `agents sessions insights`) is deterministic and offline: it caches per-session facets, compares harnesses, and ranks actions by evidence count -- no model call unless you pass `--narrative`. Routines put any of this on a cron ([Routines](#routines)); monitors fire it on a change instead of a clock ([Monitors](#monitors)); the menu bar is the always-on control surface for the fleet these commands drive ([Menu bar](#menu-bar)).
+
 ---
 
 ## One config, every agent
@@ -370,7 +378,7 @@ agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # original harness/version/d
 agents run auto --resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # adapt if its account is unavailable
 ```
 
-`agents sessions resume` reopens several sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. `agents resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and recover on the source device. If the origin version is installed, signed in, and healthy, its isolated home performs native resume. Otherwise a healthy version of the **same harness** starts with `/continue <id>`, which reads the indexed transcript even when the old version home is retained under version trash. It never native-resumes from a different isolated home. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
+`agents sessions resume` reopens several sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. `agents resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and recover on the source device. If the origin version is installed, signed in, healthy, and still owns the indexed transcript, its isolated home performs native resume. Claude launches that native resume from the original project directory recorded before the first turn, so its `projects/<cwd-key>` lookup reaches the conversation even when the session later changed directories. Otherwise a healthy version of the **same harness** starts with `/continue <id>`, which reads the indexed transcript even when the old version home is retained under version trash or the same version number was reinstalled into a new home. It never native-resumes from a different isolated home. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
 
 ### Send an agent to the background — and bring it back
 
@@ -462,6 +470,36 @@ See [docs/fleet.md](apps/cli/docs/fleet.md) for the manifest schema and reconcil
 
 ---
 
+## Pin versions per project
+
+```bash
+# This project needs claude@2.0.65 -- newer versions changed tool calling.
+agents use claude@2.0.65 -p
+
+# The monorepo uses codex@0.116.0 across the team.
+agents use codex@0.116.0 -p
+```
+
+This creates an `agents.yaml` at the project root:
+
+```yaml
+# agents.yaml (commit this to your repo)
+agents:
+  claude: "2.0.65"
+  codex: "0.116.0"
+```
+
+Think `requirements.txt` for CLI coding agents, on steroids. A shim reads `agents.yaml` from the project root and routes `claude` / `codex` / `antigravity` / `grok` (and others) to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources.
+
+```bash
+agents add claude@2.0.65     # Install a specific version
+agents add codex@latest       # Install latest
+agents add codex@oldest       # Install the oldest published version
+agents view                   # See everything installed
+```
+
+---
+
 ## Run open models through Claude Code (experimental)
 
 > **Note:** Profiles are experimental, but available by default — no enable step needed.
@@ -546,6 +584,9 @@ agents fleet status                     # online/offline rollup + NEEDS ATTENTIO
 agents fleet status --verbose           # full per-device auth/CLI/sync/version grid
 agents fleet status --live              # force a live resource probe (alias of --refresh)
 agents fleet status --json --strict     # scriptable fleet health gate
+agents devices harnesses                # per device: agent@version · account · signed · quota · ready
+agents devices accounts                 # same, one row per account (which harnesses share it)
+agents devices harnesses --agents claude,codex --json   # scoped, machine-readable
 agents doctor --check --devices         # CI drift gate across every registered device
 
 # Your Tailscale fleet, auto-discovered
@@ -594,6 +635,18 @@ endpoint — e.g. codex/grok — benign), `◐degraded` (soft/self-healing: expi
 rate-limited), and `○revoked` (server rejected — re-login now). Only `○` means a real
 re-login is needed. Run `agents fleet ping` to force a live re-verification across the fleet.
 
+`agents devices harnesses` answers "what can each box actually run right now?" — one row
+per installed `agent@version` across the fleet with its **account**, **signed-in**,
+**quota** (highest usage-window utilization; `*` = from the cached snapshot), and a single
+**ready** verdict (signed in AND not rate-limited). It SSH-probes each online device
+(bounded, so one unreachable box can't stall the glance) and reuses the daemon-warmed usage
+cache, so it never blocks on a per-account network fetch — pass `--refresh` (`--live`) for a
+live quota read. `agents devices accounts` is the same data through the **identity lens**:
+one row per account, collapsing the installs that share it (e.g. five claude versions on one
+email) and naming which harnesses use it — the fast way to see which accounts are logged in
+and healthy across every machine. Scope either with `--agents <csv>` / `--device <csv>`, and
+add `--json` for the machine-readable per-host rows.
+
 **Hosts** (`agents hosts`) are git-synced dispatch targets in `agents.yaml`; **devices** (`agents devices`) are your Tailscale machines in a local registry. Both ride SSH and feed one host pool: devices appear in `agents hosts list` and capability routing without a second enrollment. On `--host` runs every `agents run` option is either forwarded (`--effort --env --timeout --loop …`), rejected loud (`--secrets` never crosses SSH implicitly), or consumed locally — nothing silently drops. See [docs/00-concepts.md](apps/cli/docs/00-concepts.md#devices--hosts).
 
 Every `--host` command rides one multiplexed SSH engine, tuned for driving a fleet from a small laptop: the first call to a machine opens a control socket and every later call reuses it (no repeat TCP+auth handshake), connections carry keepalive so a dropped link dies in ~45 s instead of zombying, and following a remote run polls in a single round-trip per cycle. Measured against a Tailscale-relayed host: repeated calls **~6–7× faster**, dispatch readiness **~2×**, and the follow loop **~21× faster with 50% fewer local ssh spawns**. Design: [docs/09-ssh-transport.md](apps/cli/docs/09-ssh-transport.md) · reproduce: `node scripts/bench-ssh.mjs <host>`.

package/dist/commands/bench.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBenchCommand(program: Command): void;

package/dist/commands/bench.js

@@ -0,0 +1,101 @@
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { detectSignedInRuntimes } from "../lib/crabbox/runtimes.js";
+import { listRuns, loadRun, loadTask, runCells, saveRun, } from "../lib/bench/index.js";
+import { setHelpSections } from "../lib/help.js";
+const TASKS_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bench/tasks");
+function csv(value) {
+    return (value
+        ?.split(",")
+        .map((item) => item.trim())
+        .filter(Boolean) ?? []);
+}
+function taskIds(root = TASKS_ROOT) {
+    if (!fs.existsSync(root))
+        return [];
+    return fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() &&
+        fs.existsSync(path.join(root, entry.name, "task.json")))
+        .map((entry) => entry.name)
+        .sort();
+}
+function renderResult(result) {
+    console.log(`Run ${result.run_id}${result.task_id ? ` · ${result.task_id}` : ""}`);
+    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"}`);
+}
+export function registerBenchCommand(program) {
+    const bench = program
+        .command("bench")
+        .description("Run the same task across agent and model cells, with isolated fixtures and durable JSON results.");
+    setHelpSections(bench, {
+        examples: `agents bench list\nagents bench run hello-repo --agent claude,codex --model cheap,default\nagents bench results --json`,
+        notes: `Task definitions live under apps/cli/bench/tasks/<id>/task.json. Custom harness names accepted by agents run are valid --agent values.`,
+    });
+    bench
+        .command("list")
+        .description("List available benchmark tasks.")
+        .option("--json", "Emit JSON.")
+        .action((options) => {
+        const tasks = taskIds();
+        if (options.json)
+            console.log(JSON.stringify(tasks, null, 2));
+        else if (tasks.length === 0)
+            console.log("No benchmark tasks installed.");
+        else
+            tasks.forEach((id) => console.log(id));
+    });
+    bench
+        .command("results [run-id]")
+        .description("Show one saved run, or list saved runs newest first.")
+        .option("--json", "Emit JSON.")
+        .action((runId, options) => {
+        const value = runId ? loadRun(runId) : listRuns();
+        if (options.json)
+            console.log(JSON.stringify(value, null, 2));
+        else if (Array.isArray(value)) {
+            if (value.length === 0)
+                console.log("No benchmark results yet.");
+            else
+                value.forEach(renderResult);
+        }
+        else
+            renderResult(value);
+    });
+    bench
+        .command("run [task-id]")
+        .description("Run one task or prompt across an agent × model matrix.")
+        .option("--prompt <text>", "Prompt to benchmark instead of a house task.")
+        .option("--agent <names>", "Comma-separated native agents or custom harness names. Defaults to signed-in native agents.")
+        .option("--model <models>", "Comma-separated model tiers or concrete model ids.")
+        .option("--concurrency <n>", "Maximum cells running at once.", "3")
+        .option("--json", "Emit the saved JSON result.")
+        .action(async (taskId, options) => {
+        if (!!taskId === !!options.prompt)
+            throw new Error("Pass exactly one of <task-id> or --prompt.");
+        const task = taskId ? loadTask(taskId, TASKS_ROOT) : undefined;
+        const prompt = options.prompt ?? task.prompt;
+        let agents = csv(options.agent);
+        if (agents.length === 0)
+            agents = (await detectSignedInRuntimes())
+                .filter((runtime) => runtime.signedIn)
+                .map((runtime) => runtime.id);
+        if (agents.length === 0)
+            throw new Error("No signed-in native agents found. Pass --agent <name>.");
+        const models = csv(options.model);
+        const cells = agents.flatMap((agent) => models.length > 0
+            ? models.map((model) => ({ agent, model }))
+            : [{ agent }]);
+        const concurrency = Number(options.concurrency);
+        const result = await runCells({ task, prompt, cells, concurrency });
+        saveRun(result);
+        if (options.json)
+            console.log(JSON.stringify(result, null, 2));
+        else
+            renderResult(result);
+        if (result.cells.some((cell) => cell.status === "failed"))
+            process.exitCode = 1;
+    });
+}