@phnx-labs/agents-cli 1.20.65 → 1.20.66

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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`.

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>
@@ -60,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)
@@ -125,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"
@@ -206,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
@@ -236,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.
@@ -298,6 +325,11 @@ 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
@@ -366,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
@@ -417,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
 
@@ -469,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
@@ -520,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
@@ -570,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
@@ -742,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/exec.d.ts

@@ -7,6 +7,54 @@
  */
 import { type Command } from 'commander';
 import type { ExecEffort } from '../lib/exec.js';
+import { type SshGResult } from '../lib/hosts/ssh-config.js';
+/** The host descriptor fields the `--copy-creds` security gate reads. */
+export interface CopyCredsGateHost {
+    name: string;
+    /** Concrete SSH target for inline/provider hosts; unset for ssh-config aliases. */
+    address?: string;
+    /** `devices` = registered Tailscale fleet host; `local` = ssh-config/inline. */
+    provider?: string;
+}
+/** Outcome of the `--copy-creds` security gate (RUSH-1767). */
+export interface CopyCredsGateDecision {
+    /** Ship credentials? True only when the host key is pinned in the managed store. */
+    allowed: boolean;
+    /** The address whose key is checked/pinned — an ssh-config alias resolved to its real HostName. */
+    pinTarget: string;
+    /** True when the non-device self-pin path pinned the target during this call. */
+    selfPinned: boolean;
+}
+/** Injectable network seams so the gate decision is testable without ssh/keyscan. */
+export interface CopyCredsGateDeps {
+    /** Managed known_hosts store file (defaults to the real cache path). */
+    file?: string;
+    /** Resolve an ssh-config alias to its effective HostName/Port (defaults to real `ssh -G`). */
+    resolve?: (name: string) => SshGResult | undefined;
+    /** Self-pin `target` via ssh-keyscan; returns whether it's pinned afterward (defaults to real `pinHostKey`). */
+    selfPin?: (target: string, port: number | undefined, file: string) => boolean;
+}
+/**
+ * Decide whether `--copy-creds` may ship credentials (and the Claude OAuth
+ * token) to `host` (RUSH-1767). Credentials ship only to a host whose SSH host
+ * key is pinned in the managed known_hosts store, so the offload never rides an
+ * accept-new (TOFU) connection a machine-in-the-middle could intercept.
+ *
+ * Resolution:
+ *  - The checked target is the host's concrete `address`, else its ssh-config
+ *    HostName (`ssh -G`), else its name — so an alias is pinned/verified against
+ *    the SAME real host the strict dispatch later connects to.
+ *  - An unpinned NON-device (a bare `~/.ssh/config` `Host` alias or literal,
+ *    which `agents ssh <name>` can't reach — "Unknown device") is self-pinned in
+ *    place via ssh-keyscan. A registered device is left unpinned here — it earns
+ *    its pin through the normal `agents ssh <name>` accept-new connect, so the
+ *    caller steers there instead.
+ *
+ * The network seams (`resolve`, `selfPin`) default to the real ssh -G /
+ * ssh-keyscan implementations and are injectable so the ship/refuse decision is
+ * unit-testable against real known_hosts fixtures with no network.
+ */
+export declare function decideCopyCredsGate(host: CopyCredsGateHost, deps?: CopyCredsGateDeps): CopyCredsGateDecision;
 /**
  * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
  * `loop:` frontmatter block (issue #332). Returns undefined when neither source

package/dist/commands/exec.js

@@ -12,6 +12,8 @@ import { parseLoopInterval } from '../lib/loop.js';
 import { AGENTS } from '../lib/agents.js';
 import { recordDispatchedRun } from '../lib/audit/log.js';
 import { warnUnpushedWork, shouldWarnUnpushed } from '../lib/warn-unpushed.js';
+import { isHostPinned, pinHostKey, managedKnownHostsPath } from '../lib/devices/known-hosts.js';
+import { sshResolve } from '../lib/hosts/ssh-config.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -27,6 +29,46 @@ function formatRotationBanner(result, verb = 'balanced') {
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
     return `[agents] ${verb} picked ${label} (${ratio})`;
 }
+/**
+ * Decide whether `--copy-creds` may ship credentials (and the Claude OAuth
+ * token) to `host` (RUSH-1767). Credentials ship only to a host whose SSH host
+ * key is pinned in the managed known_hosts store, so the offload never rides an
+ * accept-new (TOFU) connection a machine-in-the-middle could intercept.
+ *
+ * Resolution:
+ *  - The checked target is the host's concrete `address`, else its ssh-config
+ *    HostName (`ssh -G`), else its name — so an alias is pinned/verified against
+ *    the SAME real host the strict dispatch later connects to.
+ *  - An unpinned NON-device (a bare `~/.ssh/config` `Host` alias or literal,
+ *    which `agents ssh <name>` can't reach — "Unknown device") is self-pinned in
+ *    place via ssh-keyscan. A registered device is left unpinned here — it earns
+ *    its pin through the normal `agents ssh <name>` accept-new connect, so the
+ *    caller steers there instead.
+ *
+ * The network seams (`resolve`, `selfPin`) default to the real ssh -G /
+ * ssh-keyscan implementations and are injectable so the ship/refuse decision is
+ * unit-testable against real known_hosts fixtures with no network.
+ */
+export function decideCopyCredsGate(host, deps = {}) {
+    const file = deps.file ?? managedKnownHostsPath();
+    const resolve = deps.resolve ?? sshResolve;
+    const selfPin = deps.selfPin ?? ((target, port, f) => pinHostKey(target, { file: f, ...(port ? { port } : {}) }).pinned);
+    // For an ssh-config host `host.address` is unset; ssh -G gives the real
+    // HostName (and Port) the strict dispatch will verify against.
+    const cfg = host.address ? undefined : resolve(host.name);
+    const pinTarget = host.address ?? cfg?.hostname ?? host.name;
+    // Not pinned yet? A registered device earns its pin through the normal
+    // accept-new connect (`agents ssh <name>` / the fleet sweep), so leave it and
+    // let the caller steer there. A bare ssh-config alias / literal is NOT a
+    // registered device — that flow can never pin it — so pin it right here.
+    let selfPinned = false;
+    if (!isHostPinned(pinTarget, file) && host.provider !== 'devices') {
+        const cfgPort = cfg?.port;
+        const port = cfgPort && cfgPort !== '22' ? Number(cfgPort) : undefined;
+        selfPinned = selfPin(pinTarget, port, file);
+    }
+    return { allowed: isHostPinned(pinTarget, file), pinTarget, selfPinned };
+}
 /**
  * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
  * `loop:` frontmatter block (issue #332). Returns undefined when neither source
@@ -581,6 +623,29 @@ export function registerRunCommand(program) {
                 // --lease, a host is persistent, so this is strictly opt-in per run.
                 let hostCopyCreds;
                 if (options.copyCreds) {
+                    // Refuse to copy credentials (and the Claude OAuth token) to a host
+                    // whose SSH host key isn't pinned in the managed known_hosts store:
+                    // the offload transport would otherwise ride an accept-new (TOFU)
+                    // connection, so a machine-in-the-middle on an unverified first
+                    // connect could capture the tokens. The dispatch itself then verifies
+                    // strictly against that pin (see lib/hosts/dispatch.ts) (RUSH-1767).
+                    // The ship/refuse decision — pinTarget resolution, the non-device
+                    // self-pin, and the final pinned check — lives in decideCopyCredsGate
+                    // (unit-tested against real known_hosts fixtures).
+                    const gate = decideCopyCredsGate(host);
+                    if (gate.selfPinned) {
+                        console.error(chalk.gray(`Pinned "${host.name}" (${gate.pinTarget}) into the managed known_hosts store.`));
+                    }
+                    if (!gate.allowed) {
+                        console.error(chalk.red(`Refusing --copy-creds to "${host.name}": its SSH host key isn't pinned, so the ` +
+                            `credentials could be exposed to a machine-in-the-middle on an unverified first connect.`));
+                        console.error(chalk.gray(host.provider === 'devices'
+                            ? `Pin the key first by connecting once so agents records and verifies it:  agents ssh ${host.name}\n` +
+                                `Then re-run with --copy-creds.`
+                            : `Couldn't reach "${gate.pinTarget}" to pin its key (ssh-keyscan returned nothing). ` +
+                                `Make sure the host is reachable over SSH, then re-run with --copy-creds.`));
+                        process.exit(1);
+                    }
                     const { detectSignedInRuntimes, pickRuntimes, resolveClaudeCredentialsBlob } = await import('../lib/crabbox/runtimes.js');
                     const { confirm } = await import('@inquirer/prompts');
                     const detected = await detectSignedInRuntimes();

package/dist/commands/monitors.js

@@ -118,6 +118,8 @@ function buildSource(options) {
     if (options.watchFile)
         chosen.push({ type: 'file', source: { type: 'file', path: options.watchFile } });
     if (options.watchDevice) {
+        // Name is validated against the registry in the async add handler (fail fast,
+        // same gate as --device/--devices) — buildSource is sync so it can't await.
         chosen.push({ type: 'device', source: { type: 'device', device: options.watchDevice } });
     }
     if (options.on) {
@@ -343,6 +345,12 @@ export function registerMonitorsCommands(program) {
             process.exit(1);
         }
         const source = buildSource(options);
+        // A --watch-device source name must resolve to a registered fleet member —
+        // validate it (fail fast with the registered list) so a typo/removed device
+        // can't silently watch the local machine (same gate as --device/--devices).
+        if (source.type === 'device' && source.device) {
+            source.device = await validateDevice(source.device);
+        }
         const condition = buildCondition(options);
         const action = buildAction(options);
         // Placement.

package/dist/commands/plugins.js

@@ -573,6 +573,7 @@ Examples:
     pluginsCmd
         .command('update [name]')
         .description('Re-pull a plugin from its original source and re-sync to all versions')
+        .option('--allow-exec-surfaces', 'Consent to an update that introduces new executable surfaces (hooks/, bin/, scripts/, .mcp.json, settings.json, permissions/)')
         .addHelpText('after', `
 Examples:
   # Update a specific plugin
@@ -580,8 +581,11 @@ Examples:
 
   # Update all plugins
   agents plugins update
+
+  # Trust an update that adds new executable surfaces
+  agents plugins update rush-toolkit --allow-exec-surfaces
 `)
-        .action(async (nameArg) => {
+        .action(async (nameArg, options) => {
         const plugins = nameArg ? [getPlugin(nameArg)].filter(Boolean) : discoverPlugins();
         if (nameArg && plugins.length === 0) {
             console.log(chalk.red(`Plugin '${nameArg}' not found`));
@@ -591,24 +595,41 @@ Examples:
             console.log(chalk.gray('No plugins installed.'));
             return;
         }
+        const allowExec = options.allowExecSurfaces === true;
         for (const plugin of plugins) {
             process.stdout.write(`Updating ${plugin.name}... `);
-            const result = await updatePlugin(plugin.name);
+            const result = await updatePlugin(plugin.name, { allowExecSurfaces: allowExec });
             if (!result.success) {
-                console.log(chalk.red(`failed — ${result.error || 'unknown error'}`));
+                if (result.blockedByExecSurfaces) {
+                    // Security (RUSH-1757): the update introduced new executable surfaces.
+                    // Refuse without renewed consent; the last-good content stays in place.
+                    console.log(chalk.yellow('skipped'));
+                    console.log(chalk.yellow(`  Update introduces new executable surfaces: ${(result.newExecSurfaces || []).join(', ')}`));
+                    console.log(chalk.gray('  Kept the currently-installed revision. Re-run with --allow-exec-surfaces if you trust the source.'));
+                }
+                else {
+                    console.log(chalk.red(`failed — ${result.error || 'unknown error'}`));
+                }
                 continue;
             }
             console.log(chalk.green('done'));
-            // Re-sync to all supported installed versions
+            // Reload the plugin so the re-sync reads the freshly-applied revision.
+            const updated = getPlugin(plugin.name) ?? plugin;
+            // Re-sync to all supported installed versions. When the applied revision
+            // carries executable surfaces, only enable them if the user consented on
+            // this update (--allow-exec-surfaces); otherwise the benign content syncs
+            // but stays disabled, matching the install-time trust gate.
             for (const agentId of capableAgents('plugins')) {
-                if (!pluginSupportsAgent(plugin, agentId))
+                if (!pluginSupportsAgent(updated, agentId))
                     continue;
                 const versions = listInstalledVersions(agentId);
                 const defaultVer = getGlobalDefault(agentId);
                 const targetVersions = defaultVer ? [defaultVer] : versions.slice(-1);
                 for (const version of targetVersions) {
-                    const syncResult = syncResourcesToVersion(agentId, version, { plugins: [plugin.name] });
-                    if (syncResult.plugins.length > 0) {
+                    const didSync = allowExec
+                        ? syncPluginToVersion(updated, agentId, getVersionHomePath(agentId, version), { allowExecSurfaces: true, version }).success
+                        : syncResourcesToVersion(agentId, version, { plugins: [updated.name] }).plugins.length > 0;
+                    if (didSync) {
                         console.log(chalk.gray(`  Re-synced to ${agentLabel(agentId)}@${version}`));
                     }
                 }

package/dist/commands/sessions-browser.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Interactive fleet-wide session browser — the human front-end of `agents sessions`.
+ *
+ * One canonical filter state (device / agent / project / window / running / teams),
+ * driven by single-key hotkeys, re-pulling live over the same fleet fan-out the flag
+ * surface uses. The identical state is expressible as flags (the agent front-end);
+ * `y` / `--print-cmd` round-trips a hand-built view into a copy-pasteable command.
+ *
+ * Built on {@link dynamicPicker}; every data source (discover, fleet, live index,
+ * preview, resume dispatch) is reused from the existing sessions plumbing.
+ */
+import type { SessionMeta } from '../lib/session/types.js';
+/**
+ * The single canonical filter state. Every field has a flag equivalent, so the
+ * same view is reachable interactively (hotkeys) or from the command line (flags).
+ */
+export interface BrowserFilter {
+    /** running-only — the `R` key / `--active`. */
+    running: boolean;
+    /** include team-spawned sessions — the `C` key / `--teams`. */
+    teams: boolean;
+    /** filter to one agent, or all — the `A` key / `-a`. */
+    agent?: string;
+    /** filter to one machine, or all — the `D` key / `--device`. */
+    device?: string;
+    /** this-repo subtree vs every directory — the `P` key / `--all`. */
+    projectScope: 'repo' | 'all';
+    /** time window (undefined = all time) — the `W` key / `--since`. */
+    window?: string;
+}
+/** Return the next value in `[undefined, ...options]`, wrapping. */
+export declare function cycle(current: string | undefined, options: string[]): string | undefined;
+export declare function cycleWindow(current: string | undefined): string | undefined;
+/**
+ * Cheap client-side match for the `S` search — a plain substring test over a
+ * row's visible fields. Deliberately NOT the FTS `filterSessionsByQuery`: that
+ * runs a content-index scan per call, which is fine once over a pool but a
+ * CPU sink when a picker calls it per-row on every keystroke.
+ */
+export declare function sessionMatchesQuery(s: SessionMeta, query: string): boolean;
+/**
+ * The canonical `ag sessions …` command for a filter state (+ optional search) —
+ * the agent-facing twin of the interactive view. Shared by the `y` hotkey and
+ * `--print-cmd`.
+ */
+export declare function browserFilterToArgv(f: BrowserFilter, query?: string): string[];
+/** Normalize a `--host`/`--device` token (`alias`, `user@host`, `host.domain`) to
+ * the canonical machine id the rows carry in `.machine`, so a flag seed matches
+ * (the `d` hotkey already cycles canonical ids). Mirrors sessions.ts `hostToken`. */
+export declare function normalizeDeviceSeed(host: string | undefined): string | undefined;
+/**
+ * The initial filter for the `--active` browser: fleet-wide (matches the static
+ * `renderActiveSessions`, which has no project scoping — the `p` hotkey narrows to
+ * this repo), running-only, with the device seed normalized and `--since` seeding
+ * the window. Pure, so the routing call site is unit-testable.
+ */
+export declare function activeBrowserSeed(opts: {
+    teams?: boolean;
+    agent?: string;
+    host?: string[];
+    since?: string;
+}): Partial<BrowserFilter>;
+/**
+ * The initial filter for the bare interactive listing: current-repo subtree by
+ * default (matches the static overview's cwd scoping), `--all` widens to every
+ * directory, `--since` seeds the window.
+ */
+export declare function bareBrowserSeed(opts: {
+    teams?: boolean;
+    agent?: string;
+    all?: boolean;
+    since?: string;
+}): Partial<BrowserFilter>;
+/**
+ * Launch the interactive session browser. `initial` seeds the filter (e.g.
+ * `{ running: true }` for `--active`). Resolves after the user resumes a session
+ * or cancels — the picked row is dispatched through the shared resume/focus path.
+ */
+export declare function runSessionBrowser(initial?: Partial<BrowserFilter>, opts?: {
+    local?: boolean;
+    hosts?: string[];
+}): Promise<void>;