@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/CHANGELOG.md

@@ -1,6 +1,50 @@
 # Changelog
 
-## Unreleased
+## 1.20.66
+
+- **Fix (`agents monitors`, RUSH-1782 follow-up): `--watch-device` no longer silently watches the local machine on a bad name.** An unregistered or mistyped `--watch-device` name is now rejected at `add` time (same registry gate as `--device`/`--devices`), and the device source evaluator returns an explicit `device not registered` observation instead of falling back to local stats if a watched device is removed later — closing a "monitors the wrong box, silently" gap. The rate-limit firehose trip now also writes a fire record (`ok:false, error:'rate limited'`), so `agents monitors runs` reflects the auto-pause that `view`'s `last fired` already showed. Adds `sources/device.test.ts`. Source: `apps/cli/src/lib/monitors/sources/device.ts`, `apps/cli/src/commands/monitors.ts`, `apps/cli/src/lib/monitors/engine.ts`.
+
+- **`agents monitors` — durable event-triggered watchers (RUSH-1782).** A monitor watches a SOURCE, detects a CONDITION change, and fires an ACTION — a routine whose trigger is a *watched source* instead of a *clock*, reusing the routines daemon, dispatch (`executeJobDetached`), device model, and notify path. Sources: `--watch`/`--poll` (a shell command's stdout), `--poll-http` (a URL's status+body), `--watch-file`, `--watch-device` (fleet reachability + load headroom, the first scheduler consumer of `devices/health.ts`), plus `--ws`/`--on` (push sources, accepted; delivery wired in a follow-up). Conditions: `--on-change` (default; first observation is a silent baseline), `--match <regex>` (fires once per distinct matched token), `--every`, with `--dedupe-key`. Actions: `--run <agent> --prompt` (the event is injected as `{event}`), `--routine`, `--notify`, `--webhook-out`. Pin-to-one placement: `--device <name>` names the single OWNER machine (exactly-once, v1 — no distributed lock); `--devices` is the advanced allowlist; `--run-on` offloads the action over SSH. The one genuinely new primitive is a native state-diff store (`~/.agents/.history/monitors/<name>/state.json`) that replaces the hand-rolled markdown memory files ad-hoc watchers needed. `agents monitors test <name>` is a dry-run that evaluates the source once and prints the emitted event + would-fire decision without acting. A `rateLimit: {max, per}` firehose guard auto-pauses a runaway monitor. The daemon hosts a `MonitorEngine` beside the cron scheduler, reloading on SIGHUP. Source: `apps/cli/src/lib/monitors/*` (`config.ts`, `state.ts`, `engine.ts`, `dispatch.ts`, `sources/*`), `apps/cli/src/lib/daemon.ts`, `apps/cli/src/lib/state.ts`, `apps/cli/src/commands/monitors.ts`, `apps/cli/src/lib/hosts/passthrough.ts`, `apps/cli/docs/10-monitors.md`.
+
+- **NEW: `agents share <file>` — publish any HTML to a shareable link on your own Cloudflare R2, for ~$0 (RUSH-1791).** A one-command "publish" for agent-generated artifacts (plans, viz, reports). `agents share setup` provisions an R2 bucket + a ~30-line Worker on **your** Cloudflare (read from your `cloudflare.com` secrets bundle), enables the free `*.workers.dev` subdomain, and — if your token owns the zone — maps a custom domain like `share.agents-cli.sh`; `agents share plan.html [--slug x] [--expire 30d]` then does an authed `PUT` and prints the link. R2 has **zero egress** and a 10 GB free tier, so this is effectively free even at scale. The Worker is the ingress: uploads are bearer-gated through it (its R2 binding does the write, so the client needs no S3 keys) and **reads are public** — the link outlives the agent, since the page is stored in R2, not streamed. **Fleet/central mode**: the owner provisions one endpoint and every fleet/cloud/ephemeral agent publishes through it via the shared write token (a `share` secrets bundle) + synced `share:` config in `agents.yaml` (`agents share join` uses an existing endpoint with no provisioning). Expiry is per-object (`x-share-expires-at` metadata → the Worker 410s + lazily deletes past that instant). Source: `apps/cli/src/commands/share.ts`, `apps/cli/src/lib/share/{worker-template,provision,publish,config}.ts` (+ `Meta.share` in `apps/cli/src/lib/types.ts`).
+
+- **`agents share` now auto-generates an OG cover so links unfurl (RUSH-1809).** Publishing an HTML page screenshots its own hero at 1200×630 and attaches it as `og:image` + `twitter:card`, so a `share.agents-cli.sh/<slug>` link previews as a rich card in Slack, iMessage, Twitter/X, and Discord. The capture is client-side (no central render service, ~$0): it reuses the CLI's browser detector (`findFirstInstalledBrowser`) and falls back to a managed Chromium in the Playwright/Puppeteer caches, skipping poor headless hosts; if nothing headless-capable is present the cover is skipped and the plain link still publishes. Pass `--no-cover` to opt out. Default slugs are now Notion-style **`<project>-<feature>-<hash>`** (the repo name scopes the link; a random tail keeps it unguessable). New: `apps/cli/src/lib/share/{capture,og}.ts`; wired through `publish.ts` and the `agents share` command.
+
+- **SSH host-key pinning for credential-copy and `agents ssh` (Security, RUSH-1767).** `--copy-creds` now refuses to ship credentials to a `--host` whose SSH host key is not pinned, and `agents ssh` pins a host key (via `ssh-keyscan` into a managed `~/.agents/.cache/devices/known_hosts`) on first connect, resolving an ssh-config alias to its real HostName so the pin target and the strict-check target line up. Scope: this hardens the `--copy-creds` gate and the `agents ssh` pin path specifically; other SSH call sites still use OpenSSH default `~/.ssh/known_hosts` (wiring them onto the managed store is follow-up). Source: apps/cli/src/lib/devices/known-hosts.ts, apps/cli/src/lib/ssh-exec.ts, apps/cli/src/commands/exec.ts.
+
+## 1.20.65
+
+- **`agents serve --control` — the authenticated anchor for the iOS/iPadOS cockpit (RUSH-1731).** The read-only `agents serve` gains an opt-in control mode: a bearer-gated HTTP surface that adds `POST /api/run` (dispatch a headless `agents run`, local or `--host <device>`, returning a server-minted session id so the run is immediately addressable) and `POST /api/session/:id/message` (steer a running agent via `agents message`), on top of the existing `GET /api/state` + SSE `/events` — which are reused verbatim, not duplicated. It adds no execution machinery: both mutations re-invoke the same CLI paths (inheriting host offload, secrets, and detached dispatch), so a run outlives the request. Every request is verified against a token whose **SHA-256 hash only** is stored on disk (`<cache>/serve/control-tokens.json`, 0600) — the raw token is shown once at first `--control` boot and never persisted; `--bind <addr>` allows reaching it from a paired phone over the tailnet (keep it on the tailnet, never public Funnel). First step of the "Fleet Cockpit" — iOS is a control plane, not a compute worker. Source: `apps/cli/src/lib/serve/control.ts`, `apps/cli/src/lib/serve/token.ts`, `apps/cli/src/lib/serve/server.ts` (extracted `handleServeGet`), `apps/cli/src/commands/serve.ts`, `+ control.test.ts` / `token.test.ts`.
+
+- **Live NDJSON event stream for the iOS cockpit — `GET /api/session/:id/stream` (RUSH-1732).** The authenticated control server (`agents serve --control`) can now stream a run's events to the phone as Server-Sent Events. A control-mode run is launched with `--json` and its harness output captured to a per-session NDJSON file (`<cache>/serve/streams/<id>.ndjson`); the stream route offset-tails that file — the same resumable pattern `hosts/progress.ts` uses — normalizing each line to `{type, raw}` (message / tool_use / tool_result / result / error) and emitting one SSE frame per event. Each frame's `id:` is the exact byte offset past its line, so a phone that drops mid-run reconnects with `?offset=<bytes>` or the standard `Last-Event-ID` header and loses or duplicates nothing; the stream closes on the terminal `result`/`error` event. Scope: streams anchor-local runs; streaming a `--host`-offloaded run reuses `pullRemoteLogDelta` and is a follow-up. Source: `apps/cli/src/lib/serve/stream.ts`, `apps/cli/src/lib/serve/control.ts` (`startSessionStream`, `defaultRunner` capture, `spawnDetached` stdio), `+ stream.test.ts` / `control.test.ts`.
+
+- **Devices gain a `control` role + `agents devices pair-ios` for the iOS cockpit (RUSH-1733).** A `DeviceProfile` now carries an optional `role: 'worker' | 'control'` (absent = `worker`). A **control** device is a cockpit that drives the fleet but never runs agents itself (an iPhone/iPad running the companion app): it appears in the fleet but is skipped from the `agents sessions --active` SSH fan-out (`remote-list.ts` now bails on `isControlDevice(d)` regardless of platform, so a control node is never dialed and never burns a ConnectTimeout). The team scheduler is unaffected — it only places onto a user-declared device pool. New `agents devices pair-ios [name]` (run on the anchor) mints a bearer token for `agents serve --control` (hash-only on disk, shown once), marks a matching registered device `role=control` so the fleet stops dialing it, and prints how to point the app at the anchor over the tailnet. Source: `apps/cli/src/lib/devices/registry.ts` (`DeviceRole`, `deviceRole`, `isControlDevice`, `DeviceInput.role`), `apps/cli/src/lib/session/remote-list.ts`, `apps/cli/src/commands/ssh.ts`, `apps/cli/src/lib/devices/registry.test.ts`.
+
+- **Project-scoped MCP servers are untrusted by default (RUSH-1776).** A cloned repo's `<repo>/.agents/mcp/*.yaml` defines an arbitrary command spawned under the agent's authority, so merely using a hostile repo no longer auto-registers or runs it. Project-scoped MCPs now enter the register/spawn path only after an explicit per-project opt-in (`agents mcp trust`, revoke with `agents mcp untrust`), recorded in a user-owned store (`~/.agents/mcp-trust.yaml`) that a cloned repo can't write to. The gate lives at the register/spawn choke point (`getMcpServersByName` → `installMcpServers` and workflow assembly) and in the sync path, and it also closes the name-collision case where an untrusted project entry could shadow a same-named user entry. `agents mcp list` now flags an untrusted project server and shows the exact command+args that would run. User- and system-scoped MCPs (`~/.agents/mcp/*`) remain trusted and unchanged. Source: `apps/cli/src/lib/mcp.ts` (`isProjectMcpTrusted`, `trustProjectMcp`, `untrustProjectMcp`, `listMcpServerConfigs`, `getMcpServersByName`), `apps/cli/src/lib/versions.ts`, `apps/cli/src/commands/mcp.ts`.
+
+- **`agents view` surfaces Claude org identity per account — same-email installs in different orgs now read distinctly.** Two Claude installs signed into the same email (a personal Max plan and a Team seat) used to render identically. `getAccountInfo` now reads `organizationType`/`organizationName` from each version home's `.claude.json` `oauthAccount` (file-only, no keychain access, so no macOS ACL prompts); `agents view` appends an org badge inside the existing account column — `taylor@modsquad.com (ModSquad · Team)`, `taylor@turingsaas.com (Max)` — mapping known tiers (Max/Pro/Team/Enterprise/Free) and title-casing unknown future ones, showing the org *name* only for team/enterprise seats (a personal org's name is auto-generated boilerplate). The `agents use` version picker gets the same badge, and `view --json` emits the raw `organizationType`/`organizationName` fields. Companion fix: `agents view --prune` now keys duplicate detection on `accountKey` (account + org) instead of email alone, so a Max + Team install sharing one email is no longer proposed for deletion. Source: `apps/cli/src/lib/agents.ts` (`formatClaudeOrgLabel`, `accountOrgBadge`), `apps/cli/src/commands/view.ts`, `apps/cli/src/commands/versions.ts`.
+
+- **`agents view` compact usage bars now show every blocking window — Droid gains its monthly bar (`M:`).** Droid meters usage on three windows (5-hour, weekly, monthly), but the compact row hard-filtered to session + week, so an account throttled by an exhausted month window could read as rate-limited with no bar explaining why. The compact filter now renders every blocking window (all except Claude's non-blocking per-model `sonnet_week`), matching the exact set `deriveUsageStatusFromSnapshot` already uses for the rate-limited badge. Claude, Codex, and Kimi rows are byte-identical (their fetchers emit no month window), and row alignment is unaffected. Source: `apps/cli/src/lib/usage.ts` (`formatUsageSummary`).
+
+- **`agents apply` / `ag apply` — one-command fleet profile sync.** A new declarative command reconciles every registered device to a profile declared in the `fleet:` block of any `-f` file (default `agents.yaml`): ensure agents installed, sync config, and **propagate login** so a machine that is signed in once seeds the fleet — killing the "6 hosts × ~8 harnesses = ~48 OAuth flows" slog. `--plan`/`--dry-run` renders a device×dimension matrix (agents-cli · agents · config · login) without changing anything; `-y/--yes` skips the confirm; `--device <name>` scopes to one device; `--only agents,config,login` limits dimensions; `--no-login` skips login propagation. Login propagation captures portable credential files on the source (claude, codex, gemini, grok, kimi, opencode, droid, antigravity) and streams them to each target over the existing encrypted SSH channel (`sshExec` stdin, never shell-interpolated); an internal `--recv-auth` receiver validates + materializes them at 0600 and rejects path traversal. **Honest boundary:** macOS keychain-bound tokens (claude, antigravity) can't be read from the ACL-locked keychain — those are surfaced as a one-time manual login, never faked. `fleet:` is additive to the `Meta` schema; project `agents:` version-pins are untouched. Source: `apps/cli/src/commands/apply.ts`, `apps/cli/src/lib/fleet/{types,manifest,apply,auth-sync}.ts` (+ tests), `apps/cli/src/lib/hosts/passthrough.ts` (apply owns `--device`), `apps/cli/src/lib/types.ts` (`Meta.fleet`).
+
+- **Hosts become first-class run/task execution options.** (1) `agents cloud run --host <name>` dispatches onto your own machines through a new `host` cloud provider — tasks visible in both `agents cloud ps` and `agents hosts ps` (one sidecar store, two views); status reconciles from the remote `.exit` with a per-target reachability memo, never guessing failure. (2) `agents run --host` gains a forwarding contract (`RUN_OPTION_FORWARDING`): `--effort --env --add-dir --timeout --strategy/--balanced/--fallback`, the `--loop` family, `--json --verbose --yes --acp` and `--` passthrough now forward to the remote; `--secrets*`, bare `--resume`, `--resume-checkpoint` reject loud before dispatch (all previously silently dropped) — locked by a commander-introspection test. (3) Devices join the host pool via a `devices` HostProvider: `agents hosts list` shows them, capability routing reaches them, `agents hosts add <device> --cap` enrolls from the device profile. (4) Routines placement: `agents routines add --run-on <host> [--run-cwd <dir>]` executes the job body on a machine (auto-pins `devices:` to the adding machine against duplicate fleet fires; daemon finalizes from the remote exit). Auto-dispatch projects can pin `provider: 'host'` + `host:`. Also fixes `--no-auto-secrets` being a local no-op (commander stores it as `autoSecrets`). Source: `apps/cli/src/lib/hosts/{run-target,remote-cmd,dispatch,registry,types}.ts`, `apps/cli/src/lib/hosts/providers/devices.ts`, `apps/cli/src/lib/cloud/{host,types,registry}.ts`, `apps/cli/src/lib/{runner,routines,auto-dispatch,auto-dispatch-provider}.ts`, `apps/cli/src/commands/{exec,cloud,routines,hosts}.ts`.
+- **Fix: `agents run <agent>@<version> --host <host>` now forwards the version pin and most run flags to the remote host.** Previously the `--host` branch stripped `@version` and ignored `--strategy`, `--effort`, `--add-dir`, `--json`, `--verbose`, `--timeout`, `--yes`, and `--acp`, so the remote host applied its own defaults. The local CLI now parses `agent@version` verbatim, normalizes `--strategy`/`--balanced`, makes `--add-dir` paths remote-portable, and forwards all of these flags to the remote `agents run` invocation. `--add-dir` portability uses the same `~`/`$HOME` re-rooting that `--cwd` already uses, so a Linux remote resolves home paths against its own `/home/<user>`. Source: `apps/cli/src/lib/hosts/dispatch.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/hosts/dispatch.test.ts`.
+- **Fix: routine edits no longer rewrite the whole YAML file, so `~/.agents` stays clean and `agents repo pull` can sync routines across the fleet.** `writeJob` previously re-emitted the entire document via `yaml.stringify` on every mutation (pause/resume, `routines devices --set`, add), restyling untouched scalars — unquoting `schedule`, re-wrapping the folded `prompt` block — which left the git-backed user repo perpetually dirty. That made cross-device `agents repo pull` refuse ("uncommitted changes"), so a `devices:` pin set on one machine never reached the others and `Devices: all` routines kept firing on every box. A new `serializeJob` edits only the changed keys via the YAML Document API, preserving byte-for-byte formatting of untouched nodes; new/unparseable/non-mapping files fall back to canonical stringify. Source: `apps/cli/src/lib/routines.ts`, `apps/cli/src/lib/__tests__/routines.serialize.test.ts`.
+
+- **`agents secrets` gains a server-independent recovery path (RUSH-1414).** Secrets recovery no longer hard-depends on `api.prix.dev`: `secrets export --to-file <path>` writes an encrypted offline bundle (AES-256-GCM via the existing `encryptForFallback`, mode `0600`) and `secrets import --from-file <path>` restores it — both gated on `AGENTS_SECRETS_PASSPHRASE`, never auto-provisioned. `secrets import --from-ssh --host <peer>` pulls a bundle straight from a fleet peer over the existing encrypted SSH channel, mirroring the `export --host` push mechanics. Source: `apps/cli/src/commands/secrets.ts` (`exportBundleToFile`, `importBundleFromFile`, `--from-ssh`), `apps/cli/src/commands/secrets.test.ts`.
+
+- **`agents sessions <id> --json` now carries `session.todos` — checklist progress from the state engine (RUSH-1503).** The single-session JSON already surfaced `session.plan` (the last `ExitPlanMode`); it now also carries `todos` — the most-recent checklist write as `{ items: [{ content, status, activeForm }], done, total, activeForm }`, computed from the **unfiltered** transcript so it's stable regardless of any `--include` filter. This lets the Factory extension read the CLI's computed checklist instead of re-parsing raw JSONL itself. The state engine's todo extraction now also covers **Codex `update_plan`** (`plan: [{ step, status }]`), not just Claude `TodoWrite`, so `--active --json` (`ActiveSession.todos`) and the Factory Floor show live plan progress for Codex sessions too. `TodoItem`/`TodoProgress` moved from `lib/session/state.ts` to `lib/session/types.ts` (re-exported from `state.ts`) so `SessionMeta` can carry `todos` without an import cycle. Source: `apps/cli/src/lib/session/state.ts` (`extractTodoProgress`, `inferActivity`), `apps/cli/src/lib/session/types.ts` (`SessionMeta.todos`), `apps/cli/src/commands/sessions.ts` (json branch), `apps/cli/src/lib/session/{state,render}.test.ts`.
+
+- **Plugin installs strip symlinks that escape the install root and gate OpenCode exec surfaces (Security, RUSH-1755, RUSH-1756).** Installing a plugin ran a recursive `fs.cpSync` that preserved symlinks verbatim, so a plugin carrying a symlink pointing outside its source root could redirect a follow-up managed-marker write through that link and clobber an arbitrary file on disk. Every per-agent install path — Claude/Codex marketplace, Gemini, Goose, and now Hermes — audits the copied tree and removes any symlink whose resolved target escapes both the destination and source roots, while preserving internal (in-tree) symlinks. Separately, OpenCode plugins with executable surfaces (hooks/bin/scripts/`.mcp.json`/settings) are no longer auto-enabled on sync; they require explicit `--allow-exec-surfaces` consent like the other agents. Source: `apps/cli/src/lib/plugins.ts` (`stripEscapingSymlinks`, `installHermesPlugin`, `syncPluginToVersion`), `apps/cli/src/lib/plugin-marketplace.ts` (`copyPluginToMarketplace`).
+
+- **`agents serve` now rejects non-loopback `Host` headers (Security, RUSH-1766).** The read-only viewer binds `127.0.0.1`, but binding alone didn't stop DNS-rebinding: a remote page could point a hostname at `127.0.0.1` and drive the victim's browser to `GET /api/state`, exfiltrating uncommitted `git diff HEAD` of every worktree plus routine/cloud config. The server now serves only requests whose `Host` header is loopback (`localhost`/`127.0.0.1`/`[::1]`, any port); a missing `Host` (raw non-browser client) is still allowed, and the authenticated `--control` server is unaffected (it gates on a bearer token and is intended to be reachable off-box). Source: `apps/cli/src/lib/serve/server.ts` (`isAllowedServeHost`).
+
+- **Secrets `daily` hold is now reliable, configurable, and diagnosable.** Three changes to the secrets-agent so a `daily`-policy bundle actually stays silent after its first Touch ID: (1) **reliability** — the auto-cache warms an already-running broker *synchronously* (gated on a real liveness ping, not a lingering socket file) instead of firing a detached worker that lost the race under load, so a short-lived reader (`agents secrets export`, a release loop) no longer exits before the cache populates and re-prompts on every read; a dead/stale-socket broker still costs the foreground read nothing (it drops to the detached path). (2) **Configurable hold cap** — a new `secrets.agent.holdMs` key in `agents.yaml` caps how long an unlocked/auto-cached bundle is held before the next re-prompt (default 7 days; e.g. `86400000` for 24h), clamped to `[1m, 30d]` and applied consistently across the value read-path, the `secrets list` metadata cache, and `unlock`. (3) **Diagnostic** — `agents secrets status` now shows the hold window, a version-skew warning (a broker on an older build gets torn down on `agents-cli-update`, wiping held bundles — the top "why did `daily` re-prompt" cause), and clear held-vs-prompts-once guidance. Source: `apps/cli/src/lib/secrets/agent.ts` (`secretsHoldMs`/`clampHoldMs`, `agentReachableSync`, load-truthful `runAgentLoadFromStdin`), `apps/cli/src/lib/secrets/bundles.ts`, `apps/cli/src/commands/secrets.ts` (`formatHoldWindow`, status diagnostic), `apps/cli/src/lib/types.ts` (`Meta.secrets.agent.holdMs`).
+
+- **Secrets headless-read guard — background processes never raise an unwatched Touch ID prompt (#1212).** A background/headless read (scheduled routine, teammate, detached release script, the daemon sync loop, `agents run --headless`, `agents secrets export` in a pipe) now resolves broker-only and fails with an actionable "run `agents secrets unlock <b>` first" message instead of popping a Touch ID sheet on the interactive user's screen. Interactive terminal reads still prompt; file-backed bundles and non-macOS platforms are unaffected. Gated by `isHeadlessSecretsContext()` (macOS-keychain-only; false off-darwin) across every `readAndResolveBundleEnv` call site. Source: `apps/cli/src/lib/secrets/bundles.ts`, `apps/cli/src/commands/{exec,secrets,browser,ssh}.ts`, `apps/cli/src/lib/{session/sync/config,cloud/antigravity,browser/chrome,crabbox/cli,secrets/mcp}.ts`.
+
+- **Fix: workflow routines that orchestrate subagents no longer silently no-op.** A `WORKFLOW.md` `tools:` list becomes Claude's `--tools` allowlist, which *restricts* the available built-ins. A workflow that ships a `subagents/` dir — whose files `agents run <workflow>` copies into the shared agents dir *specifically so the `Task` tool can dispatch them* — but whose `tools:` omits `Task` had its one dispatch path stripped: the orchestrator ran with no way to reach its own subagents and degenerated to a one-line no-op ("I'll wait for the completion notification") before the process exited. This bit every subagent-orchestrating workflow run headlessly (e.g. the `doc-gaps` / `blog-engine` / `iterate-until-good` routines, which showed "failed" on schedule). `agents run <workflow>` now keeps `Task` in the restricted tool set whenever the run installs ≥1 dispatchable subagent, so a `tools:` list that forgets `Task` can't strip an orchestrator's ability to orchestrate. Source: `apps/cli/src/lib/workflows.ts` (`ensureSubagentDispatchTool`), `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/workflows.test.ts`.
 
 ## 1.20.64
 
@@ -81,6 +125,7 @@
 - **Wire Antigravity workflows support (RUSH-1580).** `agents` now syncs workflows to Antigravity as markdown files with the required `description` frontmatter plus an `agents_workflow` ownership marker, invocable as `/<name>` slash commands. Antigravity workflows are the one non-version-isolated target: `agy` scans a single shared, HOME-global `~/.gemini/config/global_workflows/` at startup (a real home directory, never symlinked per version — verified via strace of `agy`), so the writer and detector both resolve that shared dir for every installed version instead of a per-version home. Gated at `>= 1.0.6`. The ownership marker prevents overwriting or removing user-authored workflows of the same name. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/workflows.ts`, `apps/cli/src/lib/staleness/detectors/workflows.ts`.
 
 ## 1.20.60
+
 - **Fix Goose skill sync status for its native central-storage path.** `agents skills list goose@<version>` now reports skills under `~/.agents/skills/` as installed instead of falsely requiring a per-version `.config/goose/skills/` copy that Goose never reads. Source: `apps/cli/src/lib/skills.ts`.
 - **Correct the documented `auto` and ACP `skip` semantics.** The README and bundled `run` skill now distinguish Kimi's interactive `--auto` from its already-auto-approved headless `-p` path, document Droid's native `--auto high`, and explain that ACP `skip` prefers `allow_always` but falls back to the first permission option offered by the server. Documentation only; runtime behavior is unchanged. Source: `README.md`, `skills/run/SKILL.md`.
 - **Wire Antigravity subagents and Kimi workflow sync (RUSH-1548, RUSH-1581).** Antigravity now receives subagents as custom-agent Markdown under `~/.gemini/config/agents/<name>/agent.md` with the `>= 1.0.16` version gate enforced during sync. Kimi receives workflows as managed `type: flow` skills under `.kimi-code/skills/<name>/SKILL.md`, using the canonical slug as the flow name and an `agents_workflow` marker so native user-owned flows are not overwritten or removed. Antigravity workflows are wired separately in RUSH-1580 (they target a shared HOME-global dir, not a version home). Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/subagents.ts`, `apps/cli/src/lib/workflows.ts`.
@@ -132,6 +177,7 @@
 
 - **Fix native routine schedulers rejecting the published CLI as a Bun virtual path.** Bun's standalone runtime reports the embedded `/$bunfs/root/agents` entry as existing at `process.argv[1]`, while the real physical executable lives at `process.execPath`. Daemon resolution now substitutes that physical executable before generating launchd/systemd manifests or detached launches; the existing virtual-path guard still rejects any virtual path that reaches supervision. Source: `apps/cli/src/lib/daemon.ts`.
 - **Fix: `agents teams`, `agents message`, and `agents profiles check` work again on the signed standalone binary (regression from #315).** When `agents` resolves to the bun-compiled Mach-O (shipped since 1.20.53), three self-spawn sites relaunched the CLI as `[process.execPath, process.argv[1], …]` — but under a bun standalone executable `process.argv[1]` is the virtual entry `/$bunfs/root/agents`, so the child died with `unknown command '/$bunfs/root/agents'` (or `/bin/sh: /$bunfs/root/agents: No such file or directory`). Every teammate spawned by a compiled-binary install failed in 0s. New shared `getAgentsInvocation(subArgs)` (`apps/cli/src/lib/daemon.ts`) resolves the real on-disk binary — mapping the `/$bunfs/root/…` virtual path to `process.execPath`, running a `.js` entry under node, and a native binary directly — and `teams/agents.ts`, `commands/message.ts`, and `commands/profiles.ts` route through it. Verified end-to-end: a teammate spawned by the freshly-compiled binary runs to `completed` with no `$bunfs` error. Source: `apps/cli/src/lib/daemon.ts` (`getAgentsInvocation`), `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/commands/{message,profiles}.ts`.
+
 ## 1.20.55
 
 - **Routine scheduler health is now observable and self-healing.** `agents routines status` distinguishes `running`, `wedged`, and `stopped`, and reports the daemon binary plus heartbeat age. Routine listing/status opportunistically finalize orphaned runs; PID reuse checks and a 24-hour wall-clock limit prevent stale `running` records; daemon startup rejects bun virtual paths and warns about worktree binaries that can disappear. Source: `apps/cli/src/lib/daemon.ts`, `apps/cli/src/lib/runner.ts`, `apps/cli/src/commands/routines.ts`.
@@ -264,25 +310,27 @@
 - **The npm release can now be driven from a Linux box** by offloading the Mac-only helper signing to a remote sign host. The tarball bundles two signed macOS `.app` helpers a Linux runner can't build — `bin/Agents CLI.app` (the keychain helper: `swiftc` universal → codesign with entitlements + embedded provisioning profile → `notarytool` → staple) and `bin/MenubarHelper.app` (the menu-bar status item: `swift build` → codesign, no notarization) — which is the only reason publishing was macOS-pinned. New `scripts/remote-sign-mac.sh` (invoked automatically by `release.sh` when it runs on a non-macOS host and the signed apps are absent, or on any host with `FORCE_REMOTE_SIGN=1`) rsyncs the build inputs to `${SIGN_HOST:-mac-mini}`, runs both Mac build scripts there under the appliance's headless signing creds (unlocks `rush-signing.keychain-db`, injects Apple notary creds via the `apple.com` secrets bundle), then pulls the signed `bin/*.app` back and re-verifies the keychain sha locally. The `build` script now copies the helpers into `dist/` on a **presence** gate (`[ -d 'bin/…' ]`) instead of `[ "$(uname)" = 'Darwin' ]`, so a Linux box that pulled the pre-signed bundles packages them, and `prepack`'s sha gate uses `shasum` or `sha256sum` (whichever is present) so it works on Linux too. Override the sign host with `SIGN_HOST` and its checkout with `SIGN_HOST_REPO`. Source: `apps/cli/scripts/remote-sign-mac.sh`, `apps/cli/scripts/release.sh`, `apps/cli/scripts/verify-keychain-helper.sh`, `apps/cli/package.json`.
 
 - **The shim self-heal now repairs shims that point at a *removed* install and prunes orphaned command shims.** A dispatch shim bakes its `AGENTS_BIN` (the agents-cli entrypoint it execs) at generation time, so when that install moves or is deleted — a dev build under `~/.local/agents-cli-dev`, an old npm-global under `/opt/homebrew`, a rotated version dir — the shim keeps pointing at the dead path. Agent shims survive it via their runtime self-recovery block, but the previous self-heal only compared the *schema marker*, so a schema-current shim aimed at a removed install read as healthy and was never repaired. Two additions to the `shims` self-heal check (daemon + interactive startup): (1) **drift repair** — an agent shim whose baked `AGENTS_BIN` names a *different, now-missing* install is force-regenerated to the current install (`shimPointsAtLiveInstall`); a shim pointing at another install that still exists is left alone, so two live installs sharing the shims dir can't ping-pong. (2) **orphan prune** — legacy standalone command shims (`browser`/`secrets`/`sessions`/`teams`/`pty`) that a removed install left in the shims dir, which the current source never regenerates and which either die with `exit 127` or shadow the real package bin on PATH, are removed when their baked install is gone (`pruneOrphanedCommandShim`); user `agents alias` shims and any shim whose install still exists are spared. Verified end-to-end against a real machine carrying a deleted dev build + a removed Homebrew install: the agent shims repoint to the live install and five dead command shims are pruned. Source: `apps/cli/src/lib/shims.ts` (`shimPointsAtLiveInstall`, `pruneOrphanedCommandShim`, `listShimFileNames`), `apps/cli/src/lib/self-heal/checks/shims.ts`.
+
 ## 1.20.47
 
 - **Quick-issue bar (`Cmd-Shift-O`): `Cmd-V` now pastes into the note field, and double-clicking a screenshot thumbnail opens it in Preview.** Two fixes from dogfooding the new bar. (1) The panel is a borderless `.accessory` window with **no main menu**, so the standard clipboard key-equivalents (`Cmd-V`/`C`/`X`/`A`) were never dispatched to the field editor — paste silently did nothing. `PromptPanel.performKeyEquivalent` now routes them through the responder chain so the text field handles them. (2) Thumbnails are small, so there was no way to confirm which screenshot you were attaching: **single click still toggles selection, double click opens the full image in the default viewer (Preview)**. The single-click toggle is deferred by the double-click interval so a double-click previews without also flipping the selection, and the bar suppresses its own click-outside dismissal while Preview takes focus (so summoning Preview never closes the bar or drops your typed note; it re-arms when the bar regains focus). Source: `apps/cli/menubar/Sources/MenubarHelper/PromptPanel.swift`.
 - **Fix: the headless file-store fallback no longer silently shadows the OS keyring; NEW `agents secrets import-keyring` migrates stranded secrets into it.** On headless Linux/Windows the encrypted-file store is *sticky* — once any item is on disk, `preflight()` routed **every** op to the file store and never consulted GNOME Keyring / Windows Credential Manager again, so a secret written earlier into the native store (e.g. while a desktop keyring was unlocked) read back **empty** with no hint. This stranded real Linear CLI credentials in a locked keyring while other bundles lived in the file store, silently breaking the SessionStart hook. Two fixes: (1) `get`/`has` now **read through** to the native store on a file-store *miss* (the fast path and the non-fallback keychain-first path are untouched — the file store is still checked first), emitting a one-time stderr notice pointing at `import-keyring`; once a locked/`1312` error is seen the store is marked unreachable so it stops re-probing a known-dead store. (2) NEW **`agents secrets import-keyring`** — the Linux/Windows analogue of the macOS `migrate-acl`/orphan sweep — enumerates `agents-cli` items in the native store and copies them into the encrypted file store (the durable, passwordless headless backend). Dry-run by default; `--commit` writes; existing file-store items are never overwritten; Windows enumeration is floored to the `agents-cli.` namespace since Credential Manager targets have no service scoping. macOS is unaffected (it has no file fallback and keeps `migrate-acl`). Source: `apps/cli/src/lib/secrets/{fallback,linux,windows,index}.ts`, `apps/cli/src/commands/{secrets-import,secrets}.ts`, `apps/cli/docs/secrets.md`.
 - **Launch-health self-heal now covers Windows, and the daemon repairs a gutted install proactively — before your next `agents run`.** #764 gave `agents run` an install/run-time self-heal (probe `<binary> --version`; clean-reinstall in place, else fall back to another installed version that launches), but it **skipped the probe on Windows** — `verifyInstalledBinaryLaunches` returned healthy on `win32` unconditionally, because probing the extensionless `.bin/<cli>` wrapper would ENOENT even on a *healthy* install. So the exact Windows failure the self-heal was built for went unhealed: a vendor auto-update renames the native `claude.exe` to `claude.exe.old.<epochMs>` and never lands the replacement, leaving the shim chain intact but pointing at a missing file, and every launch dies with `'…claude.exe' is not recognized`. The probe now runs on Windows against the **real launch target** — the npm `.cmd` wrapper `agents run` actually execs (`getBinaryPath + '.cmd'`, resolved via `cmd.exe`), which chains to the native `.exe` — so a gutted install trips the existing missing-binary signature (`is not recognized`) and is repaired by the same `ensureAgentRunnable` machinery; a missing `.cmd` (a non-npm/global agent like `droid.exe`) is still treated as healthy so a good install is never destroyed. Separately, the **daemon** now runs a proactive launch-health pass (`healBrokenDefaultLaunches`) ~90s after startup and every ~6h: it probes each agent's default version and, if it won't launch, repairs it in the background — so a gutted install is fixed *before* the next `agents run` hits the ENOENT, not at spawn time (the run-time `ensureAgentRunnable` only fires once a run is already starting). Verified end-to-end on a real Windows host: renaming `claude.exe` to `.old` makes the `.cmd` probe emit `is not recognized`; restoring it returns `2.1.191 (Claude Code)`. Source: `apps/cli/src/lib/versions.ts` (`verifyInstalledBinaryLaunches`, `healBrokenDefaultLaunches`), `apps/cli/src/lib/daemon.ts`.
 
-## 1.20.45
-
 ## 1.20.46
 
 - **NEW: `Cmd-Shift-O` opens a Spotlight-style quick-issue bar in the menu-bar helper — type a sentence, attach recent screenshots, and an agent files the Linear ticket for you.** The menu-bar helper already turned a screenshot into a `<host>:<path>` token with `Cmd-Shift-V` (clip capture), but there was no path from "I see a bug" to "a triaged ticket exists." The new chord summons a borderless panel (a thin capture surface, not another form): you type a one-line note, optionally toggle one or more recent screenshots (from the system screencapture folder, CleanShot's export path, or the clip history) as a thumbnail strip (the newest is pre-selected when it's fresh), and hit Return. It then **dispatches a headless agent** (`agents run claude --mode auto`, isolated behind one `AgentsCLI.dispatchTicketAgent` call so a cloud pod is a later swap) that reads the screenshots, runs `agents sessions` to identify which repo/project this concerns, does a brief investigation for real context, and files the ticket via `~/.agents/skills/linear/scripts/linear create` with an honest priority + a `repo:<name>` label — no preview step, the panel closes immediately and a notification reports the created `RUSH-####`. Focus is handled for a no-Dock `.accessory` app (`NSApp.activate` → `makeKeyAndOrderFront` → `makeFirstResponder`, with a borderless `NSPanel` overriding `canBecomeKey`; click-outside dismissal is armed only after the summon settles so the activation race can't self-dismiss the panel). The `Cmd-Shift-V` clip hotkey is unchanged — the Carbon hotkey manager now demultiplexes both chords by `EventHotKeyID.id` through one installed handler. Self-test: `MENUBAR_ISSUE_TEST=1 MenubarHelper` exercises screenshot selection, ticket-id parsing, and the meta-prompt contract; `MENUBAR_PROMPT_PREVIEW=1` renders the panel without the global hotkey for QA. Source: `apps/cli/menubar/Sources/MenubarHelper/{PromptPanel,Hotkey,AgentsCLI,main,IssueSelfTest,Clip}.swift`.
 - **NEW: a unified self-heal subsystem — the shim/PATH "repair" notice no longer nags on every terminal, and the daemon now heals shim drift in the background.** agents-cli had accumulated ~37 separate repair routines scattered across the daemon, every CLI startup, and a handful of commands, each hand-rolling its own detect+fix on its own trigger. The most visible symptom: the interactive shim bootstrap (`maybeBootstrapShimIntegration`) regenerated shims, adopted shadowing launchers, and offered to add the shims dir to PATH **in the foreground on every invocation**, suppressed only by a `process.ppid`-keyed temp sentinel — so a new terminal re-ran the whole detect-and-nag, and the underlying condition was never permanently fixed. This lands a single `HealCheck` registry (`lib/self-heal/`) with one runner (`runSelfHeal`) driven by two front doors — the daemon (on its existing ~30s-after-start + ~6h `safe`-mode cycle) and the interactive startup — sharing the same checks: `shims` (regenerate stale shims/aliases), `shadowing` (adopt symlink launchers; report real-binary shadows), `path` (add the shims dir to PATH once), and `resources` (the existing `heal()` engine, wrapped unchanged). The daemon's heal cycle now runs all four in `safe` mode (low-risk fixes silently; risky ones reported), replacing the resource-only `heal()` call — and drops the desktop toast for background heals (the log is the record). The interactive startup now heals **silently** and prints at most a **persistent, once-per-condition** notice (`lib/shim-heal.ts`, keyed to a signature of the actionable state under `~/.agents/.cache/state/shim-notice.json`) for what a machine genuinely can't fix for you — a real native binary shadowing the shim — instead of re-nagging every shell. What changes is *where* the repairs run (background/silent) and *how often* you hear about them (once, not every terminal). Source: `apps/cli/src/lib/self-heal/` (new), `apps/cli/src/lib/shim-heal.ts` (new), `apps/cli/src/lib/daemon.ts`, `apps/cli/src/index.ts`, `apps/cli/src/lib/shims.ts` (`isShimCurrent` exported).
+
 ## 1.20.45
+
 - **NEW: `agents run <agent> --host <name>` without a prompt forwards your TTY over SSH and runs the agent interactively on the remote host.** Previously `--host` runs required a prompt and were always headless (`agents run <agent> "<task>" --host <name>`). Now, omitting the prompt takes the interactive path: when local stdin is a TTY, the local CLI SSHes with `-tt`, runs `agents run <agent>` on the host, and lets the remote machine's `agents` start its normal tmux wrapper. The tmux session lives on the remote box, so detaching (`Ctrl-b d`) ends the SSH connection but keeps the agent running; you can reattach from the host or resume by session id. Session ids for Claude are still minted up front so `agents sessions` can surface and resolve the remote run. `--no-follow` is rejected for interactive host runs (it is meaningless for an attached TTY), and `--mode`, `--model`, `--name`, passthrough args after `--`, and `--raw`/`--no-tmux` are forwarded to the remote invocation. Source: `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/hosts/dispatch.ts`, `apps/cli/src/lib/hosts/session-index.ts`, `apps/cli/docs/hosts.md`.
 - **`agents secrets export --host` now works against Windows targets, and a new `agents secrets unlock --host` unlocks a bundle on a remote machine.** The export push was POSIX-only (`bash -lc`, `--from /dev/stdin`, `create … || true`, `IFS= read`), so a Windows remote died with `'true' is not recognized … cannot find the path specified`. Two changes fix it: `agents secrets import` now accepts **`--from -`** (read the `.env` from stdin, replacing the POSIX-only `/dev/stdin`), and the push is **platform-aware** — `bash -lc` on POSIX, `powershell -EncodedCommand` on Windows, with the target's OS taken from the device registry. Because the npm `agents.ps1` shim does **not** forward ssh-piped stdin to the underlying node process (a raw `--from -` read hangs), the Windows keychain push bridges the piped `.env` through PowerShell into a temp file and imports `--from <file>` (deleted afterwards). File-backend export to a Windows target is refused cleanly rather than emitting broken PowerShell. Verified end-to-end: `agents secrets export linear.app --host win-mini` imported all 13 keys. Separately, **`agents secrets unlock --host <machine> <bundle>`** runs the unlock ON the remote over `ssh -tt`, so a **file-backed** bundle's passphrase prompt surfaces on your terminal — the "unlock the Mac from the road with its password" path; keychain/biometry bundles are GUI-only (a local Touch-ID/passcode sheet can't cross SSH) and can't be remote-unlocked. `unlock`'s `--host` is single-valued so it never swallows the positional bundle name. Source: `apps/cli/src/commands/secrets.ts`, `apps/cli/src/lib/hosts/remote-cmd.ts`.
 - **A session now has ONE name, not two. `--name` seeds the session label instead of a parallel column.** Shipping `agents run --name` (1.20.43) as a separate immutable `name` column created two look-alike fields — an unshown, frozen `name` and the shown, searchable `label` — that both resolved `agents sessions <ref>` and forced tie-break bookkeeping nobody could keep straight. They unify into one field. `--name` is now the universal way to *seed* the `label` at launch — the same field an agent-generated title (Claude's `/rename`) later refines and `agents sessions` displays and searches — and it works consistently across interactive, headless, `--host`, and teams teammate runs (a teammate's friendly name now seeds its session label; before, teammate sessions had no name at all). Priority is a plain fallback chain resolved at scan time, no stored winner: an agent-generated title wins, else the `--name` seed, else the listing falls back to `topic`. So a Claude run's `--name` shows until Claude titles it (your seed, then refined); a non-Claude run keeps its `--name` as the label (it has no auto-title). The seeded name is now fuzzy-searchable in FTS (the old `name` column was not). `agents hosts logs <name>` is unchanged — it resolves against the host-task sidecar, not the session column. Schema v10 folds any existing `name` into `label` (where the label was empty), mirrors it into the FTS row, then drops the `name` column; the run-name sidecars re-seed every scan (`seedLabelsFromNames`), so no rescan is needed. Reworks the 1.20.43 `--name` design (partly reverts its separate-column approach). Source: `apps/cli/src/lib/session/{db,discover,run-names,types}.ts`, `apps/cli/src/lib/hosts/session-index.ts`, `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/docs/{05-sessions,hosts}.md`.
 - **NEW: `agents teams add`/`start` warns when a *version-pinned* teammate is on a throttled or signed-out account.** The 1.20.43 `balanced`-default fix keeps *bare* teammates off rate-limited accounts (they route through bare `agents run`, which rotates), but a **version-pinned** (`claude@2.1.112`) or **profile** teammate spawns `agents run <agent>@<version>` / `agents run <profile>`, and a pin/profile deliberately *bypasses* rotation — so it would launch straight onto a maxed account and 429 on the first request, with no mid-run failover either (that only arms when a non-pinned strategy actually rotated). `agents teams add` (at add time) and `agents teams start` (per staged teammate, deduped by `agent@version`) now pre-check a **version-pinned** teammate's account and print an advisory when it's rate-limited, out of credits, or not signed in — reusing the router's *exact* eligibility gate (`checkRunAccountReadiness` → `hasUsageAvailable`, the same session-inclusive signal the `agents view` badge uses), so the warning can never disagree with what the spawn would actually do. It **warns, never blocks** (mirroring the existing "may not be signed in" advisory); `--force` silences it. Scoped to version-pinned teammates on purpose: bare teammates are already handled by rotation, and a profile injects its own auth (a different account than the version home carries) that isn't locally checkable — so no unreliable profile warning is emitted. Source: `apps/cli/src/lib/rotate.ts` (`readinessFromCandidate`, `checkRunAccountReadiness`, `rotate.test.ts`), `apps/cli/src/commands/teams.ts`.
 
 ## 1.20.44
+
 - **Every `logs` command is concise by default; the token-heavy raw dump is now opt-in behind `--full`.** Agents that spin up agents on other machines or add teammates were pulling whole transcripts just to glance at status — `agents logs <session>` printed the full markdown transcript, and `agents hosts logs` / `agents teams logs` / `agents routines logs` each `cat`'d their entire captured stdout, because each subsystem had hand-rolled its own "cat the log" verb over its own storage. All four now default to a bounded, concise view, with `-m/--full` for the raw log: `agents logs <session>` renders the same summary digest as `agents sessions <id>` (a real session shrank 92% — 29.9 KB → 2.6 KB); `agents routines logs <name>` shows a status header + the extracted report (a real run shrank 99.5% — 386 KB → 1.8 KB), falling back to a bounded stdout tail when no report was extracted; `agents teams logs <teammate>` renders the teammate's session summary (its agentId **is** the session id), with `-n <lines>` / `--full` for raw stdout; `agents hosts logs <id>` shows a bounded tail of the captured stdout (`tailLines`, with a "… N earlier lines hidden — pass --full" note) instead of the whole log. `renderSessionLog` now takes a mode and defaults to `'summary'`; `agents sessions <id>` was already summary-by-default and is unchanged. Regression-tested: `tailLines` truncation/elision math (`hosts/logs.test.ts`) and `formatRunDuration` human-time formatting (`routines-logs.test.ts`). Source: `apps/cli/src/commands/{logs,sessions,hosts,teams,routines}.ts`, `apps/cli/src/lib/hosts/logs.ts`. Scoped follow-up (not in this PR): host-task and sandboxed-routine runs write their real transcript on the remote / in an overlay HOME, so `logs` can't yet resolve them to the full `renderSummary` — making those runs discoverable is a separate change; until then the bounded tail / extracted report is the safe concise default.
 - **The daemon now self-heals the `pane-died` hook on already-running `agents run` sessions.** The v1.20.42 fix that stops exiting a split from kicking you out of tmux is installed once, at session creation — so sessions already alive under the long-lived shared tmux server keep the old, unconditional `detach-client` hook until they exit or the server is recycled. On a machine that's never "between sessions," that meant hand-repairing live sessions. The daemon now runs `reconcileSessionHooks()` ~20s after startup and every ~5 min: it walks the managed `ag-` sessions on the shared socket and retrofits the `#{hook_pane}`-guarded hook onto any whose hook predates the current schema. It is strictly **non-destructive — `set-hook` only, never a `kill-pane` or `detach-client`** — so it is safe to run against sessions you're attached to; a per-session `@ag_hook_schema` marker makes steady-state a no-op. The hook string is now built in one place (`agentPaneDiedHook`) shared by the spawn-wrap and the reconcile so they can't drift. Source: `apps/cli/src/lib/tmux/session.ts`, `apps/cli/src/lib/daemon.ts`, `apps/cli/src/lib/exec.ts`.
 - **NEW: `agents run` self-heals a gutted install instead of crashing with `ENOENT`.** The recurring failure: an npm agent whose native binary ships as an optional per-arch dependency (codex → `@openai/codex-<platform>`) can have that tarball extract **partially** — the platform package's `package.json` lands, its `vendor/<triple>/…/codex` binary does not (an interrupted or concurrently-raced `agents add` into the same version dir). The CLI's wrapper `require.resolve`s the platform package, finds the `package.json`, and sails straight past its own "missing optional dependency" guard into a `spawn(binaryPath)` that dies with a raw `ENOENT`. `agents run` now probes the version it's about to launch and, if the binary can't run, **repairs it in place** (a *clean* reinstall — the partial `node_modules` is wiped first, because npm treats the present-but-gutted platform package as already installed and would otherwise skip re-fetching it), then falls back to another installed version that launches (re-pinning it as the default so the shim path heals too), then to installing `latest` — only erroring if nothing can be made runnable. `installVersion` gained a `{ clean }` option for the wipe-then-reinstall. Source: `apps/cli/src/lib/versions.ts` (`ensureAgentRunnable`), `apps/cli/src/commands/exec.ts`.

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, drive browsers and Electron apps, store secrets behind Touch ID, and file tickets from a menu-bar bar — all from one CLI.
+**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.
 
 <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,6 +52,7 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 - [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)
 - [Teams](#teams)
 - [Cloud](#cloud)
@@ -59,6 +60,7 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 - [Browser](#browser)
 - [Secrets](#secrets)
 - [Routines](#routines)
+- [Monitors](#monitors)
 - [PTY](#pty)
 - [Portable setup](#portable-setup)
 - [Menu bar](#menu-bar)
@@ -124,6 +126,11 @@ Write one `AGENTS.md`. It becomes `CLAUDE.md` for Claude Code, `GEMINI.md` for G
 
 ## Run any agent
 
+<p align="center">
+  <img src="assets/run-agent.svg" alt="agents run: one command runs any harness (claude/codex/gemini) against the project-pinned version, with an automatic rate-limit fallback chain." width="100%" />
+</p>
+
+
 ```bash
 agents run claude "Find all auth vulnerabilities in src/"
 agents run codex "Fix the issues Claude found"
@@ -205,6 +212,11 @@ ACP adapters are documented for claude, codex, gemini, cursor, opencode, opencla
 
 ## Sessions across agents
 
+<p align="center">
+  <img src="assets/sessions.svg" alt="agents sessions: search transcripts across Claude, Codex, Gemini, and OpenCode at once, plus a live --active panel showing each running session's state (working / waiting / idle)." width="100%" />
+</p>
+
+
 When you run multiple agents, conversations scatter across tools. Session search brings them together.
 
 ```bash
@@ -235,6 +247,22 @@ agents sessions --active            # every live run across the fleet, with stat
 agents sessions focus a1b2c3d4      # jump back into one — attach in place, or resume
 ```
 
+On a terminal, `agents sessions --active` (and a bare `agents sessions`) open the **interactive session browser** — one filter you drive with single keys, re-pulled live across the fleet:
+
+| key | filters by | flag it mirrors |
+|---|---|---|
+| `s` | search text | `--query` / positional |
+| `r` | running only | `--active` |
+| `c` | team sessions | `--teams` |
+| `a` | agent (cycles) | `-a` |
+| `d` | device (cycles) | `--device` |
+| `p` | this repo ↔ all dirs | `--all` |
+| `w` | time window | `--since` |
+| `⏎` | resume / attach | `resume` / `focus` |
+| `y` | copy the equivalent command | `--print-cmd` |
+
+Filters **stack** (they AND together), the active set shows in the header, and the highlighted row previews below. Because every hotkey has a flag, the view you build by hand is a real command: press `y` (or run `--print-cmd`) to get the exact `ag sessions …` line — explore interactively, hand the line to an agent. Piped output, `--json`, or `--no-interactive` keep the plain listing for scripts. Peek without opening the pager with `agents sessions <id> --preview`.
+
 Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), or `idle`, alongside badges for the PR it opened, the worktree it sits in, and the ticket it's working. `agents sessions focus [id]` attaches the live pane in place -- the tmux split locally or over SSH, or its Ghostty tab -- and falls back to a fresh tab + resume when the terminal is gone.
 
 Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work, and the last test verdict -- the signals to reload a task in seconds.
@@ -295,6 +323,39 @@ agents watchdog --watch    # daemon loop: a tick every --interval
 
 ---
 
+## Sync the fleet
+
+<p align="center">
+  <img src="assets/fleet-sync.svg" alt="agents apply: reconcile every device to one profile from agents.yaml — install missing agents, sync config, and propagate logins across the fleet." width="100%" />
+</p>
+
+
+One machine is set up the way you like it. Make every other machine match -- same agents installed, same config, logins seeded -- in one command.
+
+```yaml
+# agents.yaml -- add a fleet: block
+fleet:
+  devices: all              # every online registered device (minus this one)
+  defaults:
+    agents: [claude@latest, codex@latest, gemini@latest]
+    sync: [user]            # config scopes to reconcile
+    login: sync             # propagate logins where the token is portable
+```
+
+```bash
+agents apply --plan                 # device x dimension matrix; changes nothing
+agents apply                        # reconcile the fleet (confirms first; -y to skip)
+agents apply --device yosemite-s0   # scope to one device
+agents apply --only agents,config   # limit dimensions (agents, config, login)
+agents apply --no-login             # skip login propagation
+```
+
+`agents apply` (`ag apply`) probes every target over the existing SSH transport, then reconciles it to the profile: installs missing agents, upgrades `agents-cli`, syncs the named config scopes, and **propagates logins** so a host signed in once seeds the fleet -- turning "6 hosts x 8 harnesses = 48 OAuth flows" into one. Portable credential files (claude, codex, gemini, grok, kimi, opencode, droid, antigravity) stream to each target over encrypted SSH stdin, never shell-interpolated, and land at `0600`. **Honest boundary:** macOS keychain-bound tokens (claude, antigravity on a Mac target) can't be extracted -- those surface as a one-time manual login, never faked. `--plan` / `--dry-run` shows the full matrix without touching anything.
+
+See [docs/fleet.md](apps/cli/docs/fleet.md) for the manifest schema and reconcile semantics.
+
+---
+
 ## Run open models through Claude Code (experimental)
 
 > **Note:** Profiles are experimental, but available by default — no enable step needed.
@@ -337,6 +398,11 @@ Profile YAML has no secrets -- safe to `agents repo push` to a shared repo. `age
 
 ## Run on your own machines
 
+<p align="center">
+  <img src="assets/hosts.svg" alt="agents hosts: dispatch agents run and config commands to another machine over plain SSH (no daemon); the Tailscale fleet is auto-discovered." width="100%" />
+</p>
+
+
 Dispatch any read-only or config command -- and `agents run` itself -- to another machine over SSH. No daemon.
 
 ```bash
@@ -366,6 +432,12 @@ agents devices list --full              # add per-device cores and free/total RA
 agents devices list --no-stats          # instant: names/addresses only, skip the probe
 agents ssh mac-mini                     # hardened SSH: fails fast if offline,
                                         # PowerShell on Windows, password-from-Keychain
+agents hosts list                       # devices show up here too (one host pool)
+agents hosts add mac-mini --cap gpu     # tag a device for capability routing (--host gpu)
+
+# Hosts as a task backend + scheduled placement
+agents cloud run "nightly benchmark" --host gpu-box --agent claude   # task in cloud ps AND hosts ps
+agents routines add nightly -s "0 2 * * *" -a claude -p "run the sweep" --run-on gpu-box
 ```
 
 `agents devices list` probes every reachable box in parallel (bounded timeout, so a
@@ -374,7 +446,7 @@ pressure, and an idle/light/busy/loaded headroom badge, plus a fleet-capacity su
 (`164 cores · 421G free / 518G RAM`). It answers "which machine has room right now?" —
 the utilization signal the teammate scheduler doesn't yet see.
 
-**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. See [docs/00-concepts.md](apps/cli/docs/00-concepts.md#devices--hosts).
+**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>`.
 
@@ -382,6 +454,11 @@ Every `--host` command rides one multiplexed SSH engine, tuned for driving a fle
 
 ## Teams
 
+<p align="center">
+  <img src="assets/teams.svg" alt="agents teams: parallel agents in dependency order, each detached in its own worktree with boundary contracts." width="100%" />
+</p>
+
+
 ```bash
 agents teams create auth-feature
 
@@ -402,7 +479,7 @@ Team state is observable via `agents teams list --json` / `agents teams status -
 
 ## Cloud
 
-Some work shouldn't tie up your laptop. `agents cloud run` hands a task to a managed provider that clones the repo, plans, implements, tests, and opens a PR -- while your terminal stays free.
+Some work shouldn't tie up your laptop. `agents cloud run` hands a task to a managed provider that clones the repo, plans, implements, tests, and opens a PR -- while your terminal stays free. A fifth provider, `host`, dispatches the same way onto machines you own: `agents cloud run "…" --host gpu-box` (tasks track in `agents cloud ps` and `agents hosts ps` alike).
 
 <p align="center">
   <img src="assets/cloud.svg" alt="agents cloud run dispatches one prompt to a managed provider (Rush, Codex, Factory, or Antigravity) that clones, plans, tests, and opens a pull request while you keep working" width="100%" />
@@ -434,6 +511,11 @@ Auto-routes each `--agent` to its native cloud, or pin the backend with `--provi
 
 ## Workflows
 
+<p align="center">
+  <img src="assets/workflows.svg" alt="agents workflows: bundle an orchestrator prompt with optional subagents, skills, and plugins into a named, reusable pipeline invoked as one agent." width="100%" />
+</p>
+
+
 Bundle an orchestrator prompt with optional subagents, skills, and plugins into a named, reusable pipeline. One bundle, one invocation.
 
 ```bash
@@ -485,6 +567,11 @@ Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` over
 
 ## Plugins
 
+<p align="center">
+  <img src="assets/plugins.svg" alt="agents plugins: bundle skills, commands, hooks, and MCP servers under one manifest, mirrored into every installed agent version automatically." width="100%" />
+</p>
+
+
 Bundle skills, commands, hooks, MCP servers, settings, and permissions under a single manifest. One source dir at `~/.agents/plugins/<name>/`, mirrored into every installed Claude / OpenClaw version automatically.
 
 ```bash
@@ -535,6 +622,10 @@ Plugins live in the user repo (`~/.agents/plugins/`), not inside any single vers
 
 ## Browser
 
+<p align="center">
+  <img src="assets/browser.svg" alt="agents browser drives your real, already-installed Chrome over CDP — the CLI issues start / refs / click / type / screenshot; the browser exposes numbered element refs and returns a token-efficient screenshot. Same fingerprint, same IP, so sites can't detect automation — it works where Playwright gets blocked." width="100%" />
+</p>
+
 Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.
 
 ```bash
@@ -707,8 +798,70 @@ Jobs run sandboxed -- agents only see directories and tools you explicitly allow
 
 ---
 
+## Monitors
+
+<p align="center">
+  <img src="assets/monitors.svg" alt="agents monitors: a watched source (poll a command, an HTTP endpoint, a file, or a fleet device) flows into a condition (changed? matched? deduped by a native state store) that fires an action — run an agent with the event in its prompt, kick a routine, or notify. Pin the owner device for exactly-once." width="100%" />
+</p>
+
+```bash
+# Routines fire on a clock. Monitors fire on a change: watch a source, and when
+# it flips, spawn an agent, kick a routine, or notify. The cross-agent layer --
+# agents watching sources (including the fleet and other agents) and reacting.
+
+# CI goes red -> a Claude agent triages it (poll a command, diff, match a pattern)
+agents monitors add ci-red \
+  --poll 'gh pr checks 1249 --json name,bucket' 30s --match fail \
+  --run claude --prompt 'CI failed: {event}. Diagnose and fix.' \
+  --device yosemite-s0
+
+# A fleet box goes unreachable or overloaded -> notify (watch the fleet itself)
+agents monitors add box-down --watch-device mac-mini --on-change --notify telegram
+
+# Poll an endpoint every 8h; fire once when the body flips to "issued"
+agents monitors add cert-issued \
+  --poll-http 'https://secure.ssl.com/.../order' 8h --match issued --notify telegram
+
+agents monitors test ci-red    # Dry-run: evaluate the source once, show what it would fire -- no action
+agents monitors list           # Every monitor: source, owner device, last fired
+```
+
+Sources: a command's stdout (`--watch` / `--poll`), an HTTP endpoint (`--poll-http`), a file (`--watch-file`), or a fleet device's reachability + load (`--watch-device`). Push sources -- a signed webhook (`--on`) and a WebSocket (`--ws`) -- are accepted today and delivered through a receiver wired in a follow-up. Conditions: fire on any change (`--on-change`), on a regex (`--match`), or `--every` tick -- deduped by a native state store, so a monitor stays silent until something *actually* changes. Actions: `--run <agent>` (the event is injected into the prompt as `{event}`), `--routine`, `--notify`, or `--webhook-out`. Pin a monitor to one owner device with `--device` (exactly-once), or offload the action elsewhere with `--run-on`. Runs in the routines daemon; `agents monitors pause` / `resume` any time.
+
+---
+
+## Share
+
+```bash
+# Publish an HTML artifact to a public link on your own Cloudflare R2 (~$0).
+agents share setup                                  # once: provision bucket + Worker on your CF
+agents share plan.html --slug fleet --expire 30d    # → https://<base>/fleet
+agents share status                                 # show the endpoint
+```
+
+`agents share` closes the loop: an agent makes work (a plan, a viz, a report),
+publishes it, and you open the link to see it. `setup` reads a Cloudflare API token
+from your `cloudflare.com` secrets bundle (or `--token`), creates an R2 bucket, uploads
+a tiny Worker, and enables the free `*.workers.dev` subdomain (or maps `--domain
+share.example.com` when the token owns the zone). Writes are bearer-gated **through**
+the Worker (its R2 binding does the put, so the client needs no S3 keys); reads are
+**public**, so a link outlives the agent. R2 has zero egress + a 10 GB free tier, so
+this is effectively free.
+
+**Fleet mode:** provision one endpoint, then every fleet / cloud / ephemeral agent
+publishes through it with a shared write token — `agents share join <baseUrl>` uses an
+existing endpoint with no provisioning. `--expire 30d|12h|<date>` auto-expires a link.
+See [docs/share.md](apps/cli/docs/share.md).
+
+---
+
 ## PTY
 
+<p align="center">
+  <img src="assets/pty.svg" alt="agents pty: give an agent a real terminal for REPLs and TUIs; a sidecar server holds sessions alive between CLI calls." width="100%" />
+</p>
+
+
 ```bash
 # Give agents a real terminal for REPLs, TUIs, interactive programs.
 SID=$(agents pty start)

package/dist/commands/apply.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents apply` (alias `ag apply`) — reconcile the whole fleet to a declared
+ * profile in one command: install agents-cli + agents, sync config, and
+ * propagate login so a machine that's signed in once seeds every device. Kills
+ * the "6 hosts x ~8 harnesses = ~48 OAuth flows" slog.
+ *
+ * The manifest is the `fleet:` block of any `-f` file (default `agents.yaml`).
+ */
+import { Command } from 'commander';
+/** padEnd on the visible width, ignoring chalk color codes. Exported for tests. */
+export declare function stripPad(s: string, width: number): string;
+export declare function registerApplyCommand(program: Command): void;