@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/CHANGELOG.md

@@ -2,8 +2,70 @@
 
 ## Unreleased
 
+## 1.20.64
+
+- **`teams` skill documents the fleet-comms surface (RUSH-1739).** The Monitoring section now points teammates-of-teams at `agents feed` (what agents need from you), `agents mailboxes` / `--watch` / `--graph` / `--between` (what agents say to each other), and the `agents message` / `agents teams message` reply path — so an operator running a team can see and answer the whole conversation. Source: `skills/teams/SKILL.md`.
+- **`agents feed` reskin to shared fleet-comms visual language (RUSH-1738).** Presentation only: amber `they need you` masthead, shared `GLYPH` ask/answered markers (▲ / ✓), and `↳ ag message <id> "…"` reply hints — same product face as `agents mailboxes`. Grouping, fan-out, policy, and JSON contracts are unchanged. Source: `apps/cli/src/commands/feed.ts`.
+- **`agents mailboxes` grows into the fleet-comms surface (RUSH-1737).** The overview now opens with the shared `fleet comms` masthead (`N live · M boxes`, total messages, count still awaiting delivery, last activity) plus a 24-hour hourly-volume sparkline. New views and filters, all mirrored in `--json`: `--watch`/`-f` streams cross-box messages live (`HH:MM:SS  from ─→ toLabel   text`, NDJSON with `--json`, clean Ctrl-C via an AbortController, `--since` backfills the window first, and mail addressed to the watching agent's own `AGENTS_MAILBOX_DIR` box renders as `▲ you` so an orchestrator sees its replies); `--between <a> <b>` reads one relationship as a chronological thread in both directions under an `a ⇄ b · N messages · span` header; `--graph` renders who-talks-to-whom `from └─▶ to ···· count` adjacency, busiest first; `--from`/`--to`/`--since` filter the overview recency log, the watch stream, and the graph. The `<id>` detail view, `--limit`, and the `mailbox` alias are unchanged. Built on the RUSH-1736 comms engine (`lib/comms-render.ts`, `watchMessages`). Source: `apps/cli/src/commands/mailboxes.ts`, `apps/cli/src/commands/mailboxes.test.ts`, `apps/cli/docs/06-observability.md`.
+- **Routines can run a plain shell `command:` — no LLM agent required.** A routine (`JobConfig`) now accepts `command: <shell>` as a third execution mode alongside `agent:` and `workflow:` (exactly one is required). A command routine runs the shell string directly via `/bin/sh -c` (`cmd /c` on Windows) in the **real** environment (no sandbox overlay — it can `npm i -g` / `git pull`), honoring `timeout` with the same SIGTERM→SIGKILL kill the agent path uses, and writes the identical run record (`meta.json` + `stdout.log`, status from exit code) so `agents routines list/runs`, overdue tracking, and device scoping are unchanged. `agents routines add` gains `--command`. This exists because deterministic housekeeping routines (e.g. a built-in update checker) shouldn't depend on a logged-in agent, burn tokens, or gamble on account rotation — a real failure mode where the rotation dispatched an update-check to a logged-out agent version and the run died on "Not logged in." Source: `apps/cli/src/lib/routines.ts` (`JobConfig.command`, `validateJob`), `apps/cli/src/lib/runner.ts` (`executeCommandJob{Foreground,Detached}`), `apps/cli/src/lib/daemon.ts`, `apps/cli/src/commands/routines.ts`.
+- **Shared fleet-comms rendering and mailbox streaming (RUSH-1736).** Adds the common masthead, glyph, sparkline, aggregation, hourly-volume, and route-graph helpers used by `agents mailboxes` and `agents feed`, plus an abortable spool watcher that emits each new box/message pair once without replaying history unless backfill is requested. Source: `apps/cli/src/lib/comms-render.ts`, `apps/cli/src/lib/mailbox.ts`.
+- **Fix: Claude usage bars now render on Linux — so `agents view claude --host <linux-box>` shows them too.** `agents … --host X` runs the whole command on the remote box over SSH, so `agents view` executes on Linux there. Claude usage needs a live OAuth-token fetch, but `loadClaudeOauth` read the token *only* from the OS keychain — which on macOS falls through to `/usr/bin/security` and reads Claude Code's real login-keychain entry, while on Linux it routed to agents-cli's own secret store and never found the token (Claude Code on a headless Linux box writes its OAuth to the plaintext `<home>/.claude/.credentials.json` instead). The token load now falls back to that file when the keychain has no item — the same keychain-then-`.credentials.json` order `readClaudeCredentialsBlob` (`cloud/rush.ts`) already uses — so the live usage fetch succeeds and the bars render. Account + plan were unaffected because those come from the plaintext `.claude.json`. Codex (session logs), Kimi (`kimi-code.json`), and Droid (`auth.v2.file`) were already file-based and unaffected. Source: `apps/cli/src/lib/usage.ts` (`loadClaudeOauth`, `parseClaudeOauthPayload`), `apps/cli/src/lib/__tests__/usage.test.ts`.
+- **`agents mailboxes` — a read-only window onto the agent mailbox spool.** The mailbox spool (`~/.agents/.history/mailbox/<id>/{inbox,processing,consumed}`) is the transport under `agents message` / `agents feed` / `agents teams message`, but until now it had no inspection surface — `agents mailboxes` failed with `unknown command`. The new command lists every box with pending/total counts, last activity, and a live-session label when the owning agent is running, then renders a recency-ordered log of the messages that flowed **between** agents — including already-`consumed` (delivered) mail — so an operator can see agent-to-agent chatter after the fact, not just what a running agent is currently blocked on. `agents mailboxes <id>` shows one box in full across all three buckets; `--json` for machine output, `-n/--limit` bounds the overview log; `mailbox` is an alias. Adds `listBoxes()` (enumerate boxes, consistent with the GC's validity contract) and `readBox()` (read all buckets, tagged by state, non-destructive — unlike `peek`, includes `consumed/`) to the mailbox lib. Source: `apps/cli/src/commands/mailboxes.ts`, `apps/cli/src/lib/mailbox.ts`, `apps/cli/src/lib/mailbox.test.ts`, `apps/cli/src/lib/startup/command-registry.ts`, `apps/cli/src/index.ts`.
+- **`agents usage` now reports live usage for Droid and Kimi, matching `agents view`.** Both agents already render live usage bars in `agents view` — Droid via `GET https://api.factory.ai/api/billing/limits` (decrypted from `~/.factory/auth.v2.file`; 5-hour/weekly/monthly rolling windows), Kimi via its `/usages` API — but the standalone `agents usage` command still marked them "does not publish usage data" because its supported-agent set had drifted from the live sources. `agents usage droid` / `agents usage kimi` now show the same live windows with reset times, and the observability docs reflect that Droid exposes live usage. Source: `apps/cli/src/commands/usage.ts`, `apps/cli/docs/06-observability.md`.
+- **`agents devices list` now shows live resource headroom — which box has room right now.** The list used to show only name / platform / address / reachability. It now probes every reachable device in parallel (one SSH round-trip each: `uptime` + `vm_stat`/`/proc/meminfo` + `nproc`/`hw.ncpu`), bounded by a per-probe timeout so a slow or wedged node degrades to `—` instead of hanging the table, and the local machine is measured directly (no self-SSH). Each row gains **normalized load** (`load1 / cores`), **memory pressure %**, and an **idle / light / busy / loaded** headroom badge (colored by the worse of load and memory); a trailing **fleet-capacity summary** aggregates total cores and free/total RAM (`164 cores · 421G free / 518G RAM (81% free) across 10 reachable devices`). `--full` adds per-device core count and free/total memory; `--no-stats` restores the instant registry-only view; `--json` stays registry-only and fast (the path the Factory extension polls). This is the utilization signal the teammate scheduler doesn't yet consume. Source: `apps/cli/src/lib/devices/health.ts`, `apps/cli/src/commands/ssh.ts`, `apps/cli/src/lib/devices/health.test.ts`.
+- **Portable session export / import over the SSH fleet (RUSH-1710, RUSH-1711, RUSH-1712).** `agents sessions export` bundles selected sessions into a portable, self-describing archive and `agents sessions import` restores one — the user-driven successor to background R2/CRDT sync for the durable-archive / hand-off case (no daemon, no bucket). A bundle is NDJSON (a header line + one line per transcript file) so it pipes over SSH with no external archiver, stays greppable, and carries a per-file AES-256-GCM envelope under `--encrypt`; secrets are redacted by default (`--no-redact` to keep them). Selection reuses the `agents sessions` flags (`--since`, `-n/--limit`, `--all`, `-a/--agent`); dir-shaped sessions (Kimi) carry all their files. Import places each session at the cross-machine mirror keyed by its origin machine, so it shows up in `agents sessions` tagged with that machine and never overwrites your own local sessions; dedup is byte-exact (`--overwrite` to replace conflicts, `--dry-run` to preview). Multi-device transfer rides the existing SSH transport — `agents sessions import --from-host <h>` (and `export --host <h>`) run the export on the peer and stream the bundle back, equivalent to `agents ssh <h> 'agents sessions export --stdout' | agents sessions import -`; no R2, no daemon. Source: `apps/cli/src/lib/session/bundle.ts`, `apps/cli/src/lib/session/remote-bundle.ts`, `apps/cli/src/commands/sessions-export.ts`, `apps/cli/src/commands/sessions-import.ts`.
+- **SSH-first recall is now the documented default; R2/CRDT background sync is demoted to an opt-in backup (RUSH-1714).** `agents sessions --host <box>` reads any online peer's sessions live (no sync, always current) and covers almost all cross-machine recall; export/import handles the offline / hand-off case. Background sync (`agents sessions sync`) stays an opt-in beta, off by default — a passive mirror for when you want offline machines' sessions to appear automatically, not the primary mechanism. Documented in `apps/cli/docs/05-sessions.md`.
+- **Session sync now round-trips directory-shaped sessions (Kimi, Grok) instead of silently dropping the conversation (RUSH-1466).** A session used to be assumed to be one transcript file, so for agents that store a session as a *directory* — Kimi's `session_<id>/state.json` + `agents/<name>/wire.jsonl` + per-tool `tasks/*.json`, Grok's `<uuid>/events.jsonl` — only a single file survived and the actual conversation was never synced. `SyncAgentSpec` gains `dirShaped`/`exts`/`fileFilter`/`mergeableExts`; `listLocalTranscripts` now returns every file of a session (`LocalTranscript.files[]`), each stored under its own R2 sub-key and mirrored at its own relative path. Per-file reconciliation splits by kind: append-only logs (`wire.jsonl`) take the CRDT G-Set union; mutable blobs (`state.json`, task sidecars) take last-writer-wins by `(lastTs, hash)`, where a blob's `lastTs` is derived from its file mtime (blobs carry no event timestamp, so without this LWW degraded to an arbitrary highest-hash-wins that could keep a stale copy). The manifest entry shape is backward-compatible (`ManifestEntry | ManifestEntry[]`) so older CLIs read file-shaped entries byte-identically. Source: `apps/cli/src/lib/session/sync/agents.ts`, `apps/cli/src/lib/session/sync/sync.ts` (`deriveLastTs`, `resolveMirrorWrite`), `apps/cli/src/lib/session/sync/manifest.ts`, and their `*.test.ts`.
+
+## 1.20.63
+
+- **Built-in routines: the daemon now fires routines shipped in the system repo.** Routine discovery (`listJobs`/`readJob`) unions a new system layer — `~/.agents/.system/routines/*.yml` (shipped via `gh:phnx-labs/.agents-system`, which every install pulls at `agents setup`) — under the existing project and user layers. Ordering is project > user > system with first-seen-wins, so a routine shipped as a built-in fires for every install, while a user routine of the same name overrides it and a user copy with `enabled: false` disables it. The daemon (which loads with no `cwd`) sees user + system routines; `writeJob` still only ever writes to the user layer, so built-ins are never mutated in place. This is what lets a routine like `check-updates` ship to all users centrally. Source: `apps/cli/src/lib/state.ts` (`getSystemRoutinesDir`), `apps/cli/src/lib/routines.ts`, `apps/cli/src/lib/routines.test.ts`.
+
+- **`--host` / `--device` work across virtually all first-class subcommand groups (RUSH-1691).** Previously only a handful of groups accepted the flags; `agents repos list --host yosemite-s0` (and the same with `--device`) died with commander's raw `unknown option`. Remote routing now covers `repos`/`repo`, status/inspect groups, config/resource groups (`plugins`, `skills`, `hooks`, `sync`, …), `teams`, `routines`, and more via the central `maybeRunOnHost` allowlist. Commands with their own richer host handling (`run`, `sessions`, `feed`, `computer`, `secrets`, `logs`) still fall through to their actions. Groups with no remote semantics reject the flag with a clear message instead of `unknown option`. Self-host targets strip the routing flags before the local command parses so fall-through never trips an unregistered option. Source: `apps/cli/src/lib/hosts/passthrough.ts`, `apps/cli/src/commands/repo.ts`, `apps/cli/docs/{00-concepts,hosts}.md`.
+- **Subagent integrations are now a declarative capability registry — one table entry per agent instead of copy-pasted `else if (agent === …)` arms across six files (RUSH-1698).** Wiring subagents for an agent used to mean editing the same near-identical per-agent branches in `subagents.ts` (install / list / remove-from-agent / orphan-diff / soft-delete), the staleness writer, and the staleness detector — roughly O(agents × operations), and the top source of merge conflicts when new-agent PRs landed in parallel. All of it now iterates a single `SUBAGENT_TARGETS` table (`apps/cli/src/lib/subagents-registry.ts`) keyed by agent, each entry declaring the target dir, on-disk layout (`flat-file` / `dir-file` / `dir-copy`), transform, and ownership marker; the install/list/detect/orphan/remove engine is generic with zero per-agent branches. Genuinely-bespoke agents keep a handler in the same table (Kimi: two files per subagent + a managed parent index). Adding a standard integration is now one registry entry plus the `subagents` capability gate — the writer, detector, and `subagents.ts` need no new arm, and a test pins `Object.keys(SUBAGENT_TARGETS)` to `capableAgents('subagents')` so the flag and the shape can never drift. This also closed real latent gaps the old hand-written chains had left inconsistent: `droid` (synced to `.factory/droids/` but absent from every `subagents.ts` function, so its subagents could not be listed, pruned, or removed), and `copilot`/`codex` (present in some operations, missing from others) are now uniformly install/list/remove-capable. Behavior for every already-supported agent is unchanged (verified: full subagent + versions suites green, byte-identical trash/list semantics per layout). A documented **integration tier list** (`apps/cli/docs/subagents.md`) scopes future "wire X" tickets by importance instead of treating every agent equally. Source: `apps/cli/src/lib/subagents-registry.ts`, `apps/cli/src/lib/subagents.ts`, `apps/cli/src/lib/staleness/{writers,detectors}/subagents.ts`, `apps/cli/src/lib/subagents-registry.test.ts`, `apps/cli/docs/subagents.md`.
+- **Signed webhook ingress for routines via Tailscale Funnel (RUSH-1456, RUSH-1459, RUSH-1460, RUSH-1461).**
+  Routine triggers now understand both GitHub and Linear event sources, including
+  Linear action/team/label filters. `agents webhook serve --secrets-bundle <name>`
+  exposes signed localhost endpoints at `/hooks/github` and `/hooks/linear` with
+  raw-body HMAC verification, Linear timestamp checks, duplicate delivery
+  suppression, and rate limiting. `agents funnel status/up` wraps the allowed
+  Tailscale Funnel ports through the existing SSH/device path so a webhook
+  receiver can be exposed without hand-written SSH commands. Source:
+  `apps/cli/src/lib/routines.ts`, `apps/cli/src/lib/triggers/webhook.ts`,
+  `apps/cli/src/commands/routines.ts`, `apps/cli/src/commands/webhook.ts`,
+  `apps/cli/src/commands/funnel.ts`, `apps/cli/src/lib/funnel.ts`.
+- **Cross-machine session sync verified end-to-end + documented (RUSH-1464).** The R2/CRDT session-sync beta (Claude + Codex) is now signed off across the full matrix: a machine push with a read-write R2 token uploads with zero errors (the read-only-token 403 from #412 is resolved), a second machine pulls and folds those sessions into its own list, CRDT G-Set union converges byte-identically regardless of sync order, and a machine that fell behind catches up automatically when it returns (a grown session's manifest hash no longer matches the puller's recorded signature, forcing a re-fetch + re-merge). Ships the previously-missing docs: a "Cross-machine sync (R2 + CRDT)" section in `apps/cli/docs/05-sessions.md` covering the single-writer prefix layout, manifest + mirror model, CRDT convergence, client-side AES-256-GCM encryption, the opt-in beta gate, and the `r2.backups` credential bundle (including the read+write scope requirement). Verification only — no runtime change. Source: `apps/cli/docs/05-sessions.md`.
+- **Guided session-sync provisioning in `agents setup` and `agents sessions sync --setup` (RUSH-1468).** Joining a machine to the cross-machine session-sync fabric no longer requires hand-running four `agents secrets add r2.backups …` commands. A new interactive step mints the `r2.backups` bundle (R2 account/bucket/access-key/secret + a generated `R2_SYNC_ENC_KEY`), probes read+write connectivity with a throwaway object, and opts the machine into the `session-sync` beta on success. The first machine mints and prints the shared encryption key; every other machine pastes it so the whole fabric shares one key (an existing key is reused, never overwritten — overwriting would orphan peers' encrypted transcripts). `agents setup` offers it opt-in (default No, never blocks setup); `agents sessions sync --setup` runs it explicitly and can re-show the shared key. Source: `apps/cli/src/lib/session/sync/provision.ts`, `apps/cli/src/lib/session/sync/provision.test.ts`, `apps/cli/src/commands/sync-provision.ts`, `apps/cli/src/commands/setup.ts`, `apps/cli/src/commands/sessions-sync.ts`.
+- **`agents fleet` alias + fleet-wide rollout (RUSH-1632).** `fleet` is an alias
+  for `devices`. New subcommands `update [version]` and `run <cmd…>` roll out
+  across every online device with a per-device result table. Source:
+  `apps/cli/src/commands/ssh.ts`, `apps/cli/src/lib/devices/fleet.ts`.
+- **`agents hosts stop <id>` (alias `kill`) terminates a detached host run from the origin machine (RUSH-1360).**
+  Sends SIGTERM to the remote process group, writes exit `143` only when a live
+  group was signaled (or no `.exit` existed), and keeps the remote log for
+  `agents hosts logs <id>`. Source: `apps/cli/src/lib/hosts/dispatch.ts`,
+  `apps/cli/src/commands/hosts.ts`.
+- **Fix: mailbox GC actually archives expired messages on live boxes (RUSH-1611).**
+  The live-box branch of `gcMailbox` only incremented `messagesDroppedExpired`
+  without moving the file to `consumed/`, so `agents feed --dispatch` could report
+  drops while leaving expired messages in `inbox/`/`processing/`. GC now reuses
+  `sweepExpired` (the same path as drain/peek). Source: `apps/cli/src/lib/mailbox-gc.ts`.
+- **Fix: Antigravity sign-in detection on Linux when the OAuth grant lives in Secret Service (RUSH-1329).** `agy` uses the Go keyring library, which prefers libsecret (gnome-keyring) over the file fallback whenever a Secret Service daemon is running — so `~/.gemini/antigravity-cli/antigravity-oauth-token` may be absent even when the user is signed in. After the file check, `getAccountInfo` now probes `secret-tool lookup service gemini username antigravity` (exit 0 = present; stdout discarded), mirroring the macOS `security find-generic-password` probe from #506. Missing `secret-tool`, locked collections, and timeouts all read as signed out. Opt out with `AGENTS_NO_KEYCHAIN_PROBE=1`. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/agents.test.ts`.
+- **Client-side (zero-knowledge) encryption of session transcripts before R2 upload (RUSH-1463).** Transcripts carry secrets, tokens, and absolute file paths; R2's server-side encryption uses Cloudflare's key, so anyone with bucket-read access (or Cloudflare) could read them as plaintext NDJSON. `agents sessions sync` now seals each transcript BODY client-side with AES-256-GCM before upload and decrypts on pull, so R2 only ever stores ciphertext. The 32-byte key is a new `R2_SYNC_ENC_KEY` in the `r2.backups` bundle — shared across the sync fabric (every machine derives the identical key) and deliberately separate from the R2 access key so rotating the token never orphans encrypted objects. CRDT identity stays over plaintext (the manifest hash is cleartext; pull decrypts before the G-Set union), so cross-machine merge is unaffected. Pull transparently reads legacy plaintext objects (migration-safe); a push with no key configured still uploads but emits a loud per-cycle warning. A new `R2_ENDPOINT` override points sync at any S3-compatible store (MinIO/other providers), which is also how the flow is verified end-to-end without live R2. Source: `apps/cli/src/lib/session/sync/transcript-crypto.ts`, `apps/cli/src/lib/session/sync/transcript-crypto.test.ts`, `apps/cli/src/lib/session/sync/sync.ts`, `apps/cli/src/lib/session/sync/config.ts`, `apps/cli/src/commands/sessions-sync.ts`, `apps/cli/src/lib/daemon.ts`.
+- **Extend session sync to Droid, Grok, Kimi, and OpenCode (RUSH-1467).** `agents sessions sync` now includes these four agents in its upload/download matrix. `SyncAgentSpec` gains an optional `ext` field so agents with non-`.jsonl` transcript files (e.g., Kimi `state.json`) are walked correctly. Droid `.jsonl` rollouts, Grok `events.jsonl` streams, and Kimi `state.json` metadata files round-trip through the R2 mirror; OpenCode is slotted in `SYNC_AGENTS` but remains a placeholder because its sessions live in a SQLite DB and still require an SQLite-to-JSONL export step. Source: `apps/cli/src/lib/session/sync/agents.ts`, `apps/cli/src/lib/session/sync/agents.test.ts`, `apps/cli/src/commands/sessions-sync.ts`.
+- **`agents repos` is canonical (`repo` alias); push/pull echo the resolved target; push no longer no-ops when clean-but-ahead; pull rebases on diverge (RUSH-1454).** Help now prints `Usage: agents repos …`. Push/pull report `user (~/.agents → origin/main): …` instead of the bare alias. `commitAndPush` still `git push`es when the tree is clean but local is ahead of origin (previously returned success without pushing). `pullRepo` uses `git pull --rebase` so divergent branches reconcile instead of failing with a raw git error. Source: `apps/cli/src/commands/repo.ts`, `apps/cli/src/lib/git.ts`, `apps/cli/src/lib/startup/command-registry.ts`.
+- **`agents run --host <name> --copy-creds` provisions runtime credentials on a persistent host (RUSH-1608).**
+  Reuses the `--lease` credential path (`resolveClaudeCredentialsBlob` + the
+  `~/.claude/.credentials.json` bootstrap) but makes copying tokens to a
+  persistent host strictly opt-in per run. The user picks runtimes, sees a
+  consent prompt naming accounts and the Claude OAuth token, and the files are
+  shredded after the run. Source: `apps/cli/src/commands/exec.ts`,
+  `apps/cli/src/lib/hosts/dispatch.ts`, `apps/cli/src/lib/hosts/credentials.ts`,
+  `apps/cli/src/lib/hosts/credentials.test.ts`.
+
 ## 1.20.62
 
+- **Browser downloads land in a known per-profile dir; profile data is consolidated.** A browser profile is now one self-contained tree under `~/.agents/.cache/browser/<profile>/`: `chrome-data/`, `downloads/`, and `sessions/<task>/` (screenshots, PDFs, recordings). Previously downloads had no configured destination — the CLI only set the download dir when the agent explicitly ran `browser download --path`, so absent that call a download fell to Chromium's own default (for an attached user browser like comet, wherever *that* browser was last configured), which is how downloads escaped into random locations. The service now sets the profile's `downloads/` dir browser-global at connect time (both fresh launch and every attach path), so downloads always land somewhere agents-cli controls; `browser download --path` becomes an optional override (omit it to use the profile default) and reports the resolved path. Screenshots/PDFs/recordings moved from the old GLOBAL `browser/sessions/<task>/` root to the per-profile `browser/<profile>/sessions/<task>/`, with a one-shot migration that folds existing captures into the owning profile (attributed via each profile's `tasks.json`; unattributable captures go to a `_legacy` bucket). New `agents browser sessions [--profile <name>] [--open latest|<file>] [--json]` lists a profile's captures + downloads, aliased as `agents sessions --browser`. Source: `apps/cli/src/lib/browser/{profiles,service,ipc,sessions-list}.ts`, `apps/cli/src/lib/migrate.ts`, `apps/cli/src/commands/{browser,sessions}.ts`.
 - **Wire Goose commands support (RUSH-1572).** `agents` now syncs slash commands to Goose as recipe YAML files under `~/.config/goose/commands/<name>.yaml`, each registered in `~/.config/goose/config.yaml` under a `slash_commands: [{ command, recipe_path }]` array (Goose has no native slash-command file format — a slash command IS a recipe). The command recipes live in a dir distinct from the workflow recipes dir (`~/.config/goose/recipes/`) so the workflow detector never treats a command recipe as a workflow. Registration is a read-modify-write that preserves every other `config.yaml` key (`mcp_servers`, `extensions`, …) and other `slash_commands` entries, and removal soft-deletes the recipe + unregisters the entry. Flip Goose's `commands` capability and add `goose` branches to install/list/match/remove, the staleness commands writer, and doctor-diff, backed by a new `goose-commands.ts` module + a `markdownToGooseRecipe` converter. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/goose-commands.ts`, `apps/cli/src/lib/commands.ts`, `apps/cli/src/lib/convert.ts`, `apps/cli/src/lib/staleness/writers/commands.ts`, `apps/cli/src/lib/doctor-diff.ts`.
 - **Fix: Hermes plugin sync no longer disables a plugin the user explicitly enabled.** The plugin install path (RUSH-1688) unconditionally forced `plugins.enabled` to the exec-surface trust verdict on every sync. An ordinary un-flagged background re-sync computes `enable=false` for a plugin with hooks/tools, so it stripped that plugin from the `~/.hermes/config.yaml` allowlist — clobbering a plugin the user deliberately enabled with `--allow-exec-surfaces`. The install path now enables only when trusted and never down-toggles (matching the marketplace flow's add-if-trusted semantics); removal still unregisters explicitly. Source: `apps/cli/src/lib/plugins.ts`.
 - **Wire Goose subagents support (RUSH-1573).** `agents` now syncs subagents to Goose as recipe YAML files under `~/.config/goose/agents/<name>.yaml` — Goose has no dedicated subagent format, so a named subagent IS a recipe (goose auto-discovers `~/.config/goose/agents/` and delegates to them by name in autonomous mode). `transformSubagentForGoose` emits the same recipe schema agents-cli already uses for Goose workflow recipes (`version`/`title`/`description`/`instructions`/`prompt`, plus optional `settings.goose_model`). Flip Goose's `subagents` capability and wire the install/remove/list/orphan/version-remove branches plus the staleness subagents writer and detector. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/subagents.ts`, `apps/cli/src/lib/staleness/{writers,detectors}/subagents.ts`.

package/README.md

@@ -347,6 +347,9 @@ agents hosts check gpu-box              # reachable? which agents-cli version?
 # Run there instead of locally
 agents run claude --host gpu-box "profile this build"   # headless: follows live by default
 agents run claude --host gpu-box                         # no prompt → interactive TTY over SSH (tmux-backed)
+agents run claude --host gpu-box --copy-creds "fix auth" # copy local runtime creds + Claude token, shred after
+agents hosts ps                         # list dispatched runs + terminal status
+agents hosts stop <id>                  # terminate a hung/detached run (alias: kill)
 agents logs --host gpu-box              # pick a dispatched run — concise summary by default
 agents logs <id> --full                 # the full raw transcript / stdout (token-heavy)
 agents logs <id> -f                     # re-attach to a running one and follow
@@ -358,10 +361,19 @@ agents doctor --device mac-mini         # same matrix, scoped to one device
 
 # Your Tailscale fleet, auto-discovered
 agents devices sync                     # ingest `tailscale status`
+agents devices list                     # fleet + live headroom: load, mem, idle/busy — which box has room
+agents devices list --full              # add per-device cores and free/total RAM
+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 devices list` probes every reachable box in parallel (bounded timeout, so a
+slow node degrades to `—` instead of hanging) and shows normalized load, memory
+pressure, and an idle/light/busy/loaded headroom badge, plus a fleet-capacity summary
+(`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).
 
 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>`.
@@ -682,6 +694,13 @@ agents routines add nightly-drain --schedule "0 3 * * *" --agent claude \
 
 agents routines devices nightly-drain --set yosemite-s0,mac-mini  # update allowlist
 agents routines list --host yosemite-s0                            # query another device
+
+# Signed webhook trigger: Linear issue labeled "agent" fires a routine
+agents routines add agent-labeled-issue --on linear:Issue --action update \
+  --team-key RUSH --label agent --agent claude \
+  --prompt "Work the Linear issue that was just labeled agent"
+agents webhook serve --secrets-bundle webhooks --port 8787          # /hooks/linear, /hooks/github
+agents funnel up yosemite-s0 --local-port 8787 --port 443           # public HTTPS ingress
 ```
 
 Jobs run sandboxed -- agents only see directories and tools you explicitly allow.

package/dist/commands/browser.js

@@ -8,6 +8,7 @@ import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } fro
 import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
+import { runBrowserSessions } from '../lib/browser/sessions-list.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { parseTargetFilter } from '../lib/browser/service.js';
 import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest, } from '../lib/browser/ipc.js';
@@ -1850,10 +1851,10 @@ function registerTaskCommands(browser) {
     // ─── Downloads ───────────────────────────────────────────────────────────────
     browser
         .command('download')
-        .description('Set download directory for a task')
+        .description("Set the download directory for a task (defaults to the profile's downloads dir)")
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
-        .requiredOption('-p, --path <dir>', 'Download directory path')
+        .option('-p, --path <dir>', "Download directory path (default: the profile's downloads dir)")
         .action(async (opts) => {
         const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
@@ -1866,7 +1867,16 @@ function registerTaskCommands(browser) {
             console.error(response.error);
             process.exit(1);
         }
-        console.log(`Download path set to ${opts.path}`);
+        console.log(response.downloadPath ? `Download path set to ${response.downloadPath}` : 'Download path set');
+    });
+    browser
+        .command('sessions')
+        .description('List a profile\'s captured screenshots, PDFs, recordings, and downloads')
+        .option('--profile <name>', 'Only this profile (default: all profiles with captures)')
+        .option('--open [selector]', "Open a capture in the OS default app: 'latest' or a filename")
+        .option('--json', 'Emit machine-readable JSON')
+        .action((opts) => {
+        runBrowserSessions({ profile: opts.profile, open: opts.open, json: opts.json });
     });
     // ─── Recording ─────────────────────────────────────────────────────────────
     const record = browser.command('record').description('Record a video of the page');

package/dist/commands/exec.js

@@ -242,6 +242,7 @@ export function registerRunCommand(program) {
         .option('--remote-cwd <dir>', 'Explicit host working directory for --host runs (overrides --cwd; usually --cwd suffices).')
         .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.')
+        .option('--copy-creds', 'With --host, copy the picked runtime credentials (and Claude OAuth token) to the host, then shred them after the run. Opt-in per run.')
         .option('--lease [backend]', 'Invent a disposable cloud box for this run and tear it down after (via crabbox). Optional backend selects the cloud (hetzner/aws/do). Unlike --host, no machine is registered.')
         .option('--keep-box', 'With --lease, keep the box after the run instead of stopping it.');
     // `--on` and `--computer` are hidden aliases of `--host` — same behavior.
@@ -328,41 +329,69 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const backend = typeof options.lease === 'string' ? options.lease : undefined;
-            const { detectSignedInRuntimes, pickRuntimes, resolveClaudeCredentialsBlob } = await import('../lib/crabbox/runtimes.js');
+            // First-run: no provider credential resolves (no env var, no config, no
+            // detectable bundle) → guide the user through one-time setup, then continue.
+            const { resolveLeaseBundle } = await import('../lib/crabbox/cli.js');
+            if (!resolveLeaseBundle()) {
+                const { runLeaseSetup } = await import('./lease.js');
+                const ok = await runLeaseSetup({ provider: backend ?? 'hetzner' });
+                if (!ok) {
+                    console.error(chalk.yellow('Leasing needs a cloud provider set up. Run `agents lease setup` and retry.'));
+                    process.exit(1);
+                }
+            }
+            const { detectSignedInRuntimes, resolveClaudeCredentialsBlob, inferLeaseRuntime } = await import('../lib/crabbox/runtimes.js');
             const { leaseAndRun } = await import('../lib/crabbox/lease.js');
-            const { confirm } = await import('@inquirer/prompts');
+            const { getConfiguredRunStrategy, resolveRunVersion } = await import('../lib/rotate.js');
             const detected = await detectSignedInRuntimes();
-            const runtimes = await pickRuntimes(detected);
-            if (runtimes.length === 0) {
-                console.error(chalk.yellow('No runtimes selected. Sign into one locally (e.g. run `claude` once) then retry.'));
+            const agentName = agentSpec.split('@')[0];
+            const leaseCwd = options.cwd ?? process.cwd();
+            // `--lease` requires a prompt (guarded above), so it is headless by
+            // contract — never block on an interactive picker. Provision exactly the
+            // one runtime this run needs, inferred from the agent, not every
+            // signed-in CLI (which would ship unrelated tokens to a throwaway box).
+            const runtime = inferLeaseRuntime(agentName, detected);
+            if (!runtime) {
+                console.error(chalk.yellow('No signed-in runtime to provision on the box. Sign into one locally (e.g. run `claude` once) then retry.'));
                 process.exit(1);
             }
-            // Security gate: copying auth tokens to an ephemeral cloud box is opt-in
-            // per run. Name the runtimes + accounts so the user sees what ships.
-            const names = runtimes
-                .map((id) => {
-                const d = detected.find((x) => x.id === id);
-                return `${d?.label ?? id}${d?.email ? ` (${d.email})` : ''}`;
-            })
-                .join(', ');
-            // Claude ships its OAuth token (not just the .claude.json config) — name it
-            // explicitly so the consent covers the actual credential transferred.
-            const whatShips = runtimes.includes('claude') ? 'credentials + Claude OAuth token' : 'credentials';
-            const ok = await confirm({
-                message: `Copy ${whatShips} for ${names} to a disposable cloud box, run there, then destroy it?`,
-                default: false,
-            });
-            if (!ok) {
-                console.error(chalk.yellow('Aborted — no credentials pushed, no box leased.'));
-                process.exit(1);
+            const runtimes = [runtime];
+            // Copy the account the run's OWN strategy would pick (default `balanced`:
+            // a healthy, non-rate-limited account weighted by remaining headroom) —
+            // never the raw default signed-in one, which could be throttled or out of
+            // credits and would boot the box straight into a wall.
+            //
+            // Only claude's token is account-switched: resolveClaudeCredentialsBlob
+            // honors preferEmail across version-homes. The other runtimes'
+            // buildCredentialScript copies the single currently-active credential file
+            // with no switching, so run the balanced picker only for claude — otherwise
+            // the notice below would name a balanced-picked account that is NOT the one
+            // actually shipped. Best-effort: fall back to the default account on error.
+            let leaseEmail = detected.find((d) => d.id === runtime)?.email ?? null;
+            if (runtime === 'claude') {
+                try {
+                    const strategy = getConfiguredRunStrategy(runtime, leaseCwd);
+                    const { rotation } = await resolveRunVersion(runtime, strategy, leaseCwd);
+                    if (rotation?.picked.email)
+                        leaseEmail = rotation.picked.email;
+                }
+                catch {
+                    /* strategy resolution is best-effort; keep the default signed-in account */
+                }
             }
+            // Headless-by-contract: don't prompt, but print exactly what ships and
+            // where — copying an auth token to a cloud box is a credential transfer.
+            // The box is destroyed after the run, so the credential's lifetime is
+            // bounded by the run.
+            const whatShips = runtime === 'claude' ? 'credentials + Claude OAuth token' : 'credentials';
+            console.error(chalk.gray(`Leasing a ${backend ?? 'hetzner'} box · shipping ${runtime}${leaseEmail ? ` (${leaseEmail})` : ''} ${whatShips}; the box is destroyed after the run.`));
             // Read the Claude OAuth token from the local Keychain (silent) so it can be
             // written to ~/.claude/.credentials.json on the box — otherwise Claude boots
-            // "Not logged in". Consent above already covered this transfer.
+            // "Not logged in". `preferEmail` targets the strategy-picked account so the
+            // token matches the account this run resolved to.
             let claudeCredentialsJson = null;
-            if (runtimes.includes('claude')) {
-                const claudeEmail = detected.find((d) => d.id === 'claude')?.email ?? null;
-                claudeCredentialsJson = await resolveClaudeCredentialsBlob({ preferEmail: claudeEmail });
+            if (runtime === 'claude') {
+                claudeCredentialsJson = await resolveClaudeCredentialsBlob({ preferEmail: leaseEmail });
                 if (!claudeCredentialsJson) {
                     console.error(chalk.yellow('Warning: could not read the local Claude OAuth token — the box may come up "Not logged in".'));
                 }
@@ -373,7 +402,6 @@ export function registerRunCommand(program) {
             // box-side marker. Rule: only ONE spinner phase is active at a time, and no
             // other output is written to stderr while it spins — so it can never storm.
             const { createLeaseOutputRouter, createSpinner } = await import('../lib/crabbox/progress.js');
-            const agentName = agentSpec.split('@')[0];
             const spinner = createSpinner({ stream: process.stderr });
             let warmupTimer;
             const stopTimer = () => { if (warmupTimer) {
@@ -536,6 +564,44 @@ export function registerRunCommand(program) {
                 // which can't run over a detached remote dispatch — only forward a
                 // concrete id.
                 const resumeId = typeof options.resume === 'string' ? options.resume : undefined;
+                // --copy-creds: provision runtime credentials (and the Claude OAuth token)
+                // on the remote host before the run, then shred them after. Unlike
+                // --lease, a host is persistent, so this is strictly opt-in per run.
+                let hostCopyCreds;
+                if (options.copyCreds) {
+                    const { detectSignedInRuntimes, pickRuntimes, resolveClaudeCredentialsBlob } = await import('../lib/crabbox/runtimes.js');
+                    const { confirm } = await import('@inquirer/prompts');
+                    const detected = await detectSignedInRuntimes();
+                    const runtimes = await pickRuntimes(detected);
+                    if (runtimes.length === 0) {
+                        console.error(chalk.yellow('No runtimes selected. Sign into one locally then retry, or omit --copy-creds.'));
+                        process.exit(1);
+                    }
+                    const names = runtimes
+                        .map((id) => {
+                        const d = detected.find((x) => x.id === id);
+                        return `${d?.label ?? id}${d?.email ? ` (${d.email})` : ''}`;
+                    })
+                        .join(', ');
+                    const whatShips = runtimes.includes('claude') ? 'credentials + Claude OAuth token' : 'credentials';
+                    const ok = await confirm({
+                        message: `Copy ${whatShips} for ${names} to host "${host.name}", run there, then shred them after?`,
+                        default: false,
+                    });
+                    if (!ok) {
+                        console.error(chalk.yellow('Aborted — no credentials pushed, no run dispatched.'));
+                        process.exit(1);
+                    }
+                    let claudeCredentialsJson = null;
+                    if (runtimes.includes('claude')) {
+                        const claudeEmail = detected.find((d) => d.id === 'claude')?.email ?? null;
+                        claudeCredentialsJson = await resolveClaudeCredentialsBlob({ preferEmail: claudeEmail });
+                        if (!claudeCredentialsJson) {
+                            console.error(chalk.yellow('Warning: could not read the local Claude OAuth token — the host may boot Claude "Not logged in".'));
+                        }
+                    }
+                    hostCopyCreds = { runtimes, detected, claudeCredentialsJson };
+                }
                 // Decide whether this host run is interactive. No prompt always means
                 // interactive (matching local resolveInteractive); --interactive forces
                 // interactive even when a prompt is provided; --headless forces headless
@@ -587,6 +653,7 @@ export function registerRunCommand(program) {
                         passthroughArgs,
                         raw: options.raw || options.tmux === false || options.disableTmux === true,
                         forceInteractive: options.interactive,
+                        copyCreds: hostCopyCreds,
                     });
                     process.exit(exitCode);
                 }
@@ -616,6 +683,7 @@ export function registerRunCommand(program) {
                     name: options.name,
                     resume: resumeId,
                     follow: options.follow !== false,
+                    copyCreds: hostCopyCreds,
                 });
                 // Register the dispatched run in the LOCAL session index so it shows
                 // up in `agents sessions` and resolves by id/name, even though its

package/dist/commands/feed.d.ts

@@ -13,6 +13,10 @@ import type { Command } from 'commander';
 import { type OpenBlock } from '../lib/feed.js';
 import { type OutcomeGroup, type SessionOutcomeHint } from '../lib/feed-outcome.js';
 export declare const FEED_NO_FANOUT_ENV = "AGENTS_FEED_LOCAL";
+/** Right-hand masthead summary: `N blocks · M agents`. */
+export declare function formatFeedMastheadRight(blocks: OpenBlock[]): string;
+/** Reply hint matching the shared fleet-comms reply line. */
+export declare function formatFeedReplyHint(mailboxId: string): string;
 export declare function parseRemoteFeed(stdout: string, machine: string): OpenBlock[];
 /** Merge local and remote rows, keeping the first copy of a host/session block. */
 export declare function mergeFeedBlocks(...groups: OpenBlock[][]): OpenBlock[];

package/dist/commands/feed.js

@@ -10,7 +10,17 @@ import { notifyUrgentBlock } from '../lib/notify.js';
 import { gcMailbox } from '../lib/mailbox-gc.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
+import { GLYPH, masthead } from '../lib/comms-render.js';
 export const FEED_NO_FANOUT_ENV = 'AGENTS_FEED_LOCAL';
+/** Right-hand masthead summary: `N blocks · M agents`. */
+export function formatFeedMastheadRight(blocks) {
+    const agents = new Set(blocks.map((b) => b.mailboxId)).size;
+    return `${blocks.length} block${blocks.length === 1 ? '' : 's'} · ${agents} agent${agents === 1 ? '' : 's'}`;
+}
+/** Reply hint matching the shared fleet-comms reply line. */
+export function formatFeedReplyHint(mailboxId) {
+    return `↳ ag message ${mailboxId} "…"`;
+}
 export function parseRemoteFeed(stdout, machine) {
     let parsed;
     try {
@@ -60,7 +70,13 @@ function renderBlock(b, localHost, indent = '') {
     const cls = b.blockClass ? chalk.gray(`(${b.blockClass})`) : '';
     const consequence = b.consequence && b.consequence !== 'normal' ? chalk.red(`[${b.consequence}]`) : '';
     const cost = b.costOfDelay ? chalk.gray(`cost:${b.costOfDelay}`) : '';
-    console.log(`${indent}${chalk.cyan(b.mailboxId)}${host}  ${runtime}  ${age}  ${cls} ${consequence} ${cost}`.trimEnd());
+    // Shared fleet-comms glyphs: ▲ open ask, ✓ answered (see comms-render GLYPH).
+    const marker = b.answer
+        ? chalk.green(GLYPH.delivered)
+        : !b.parkedAt
+            ? chalk.yellow(GLYPH.ask)
+            : ' ';
+    console.log(`${indent}${marker} ${chalk.cyan(b.mailboxId)}${host}  ${runtime}  ${age}  ${cls} ${consequence} ${cost}`.trimEnd());
     for (const question of b.questions) {
         const header = question.header ? chalk.gray(`[${question.header}] `) : '';
         console.log(`${indent}  ${header}${question.text}`);
@@ -77,7 +93,7 @@ function renderBlock(b, localHost, indent = '') {
         console.log(`${indent}  ${chalk.gray(meta)}`);
     }
     if (b.answer) {
-        const verified = b.answer.verified ? chalk.green('✓') : chalk.yellow('?');
+        const verified = b.answer.verified ? chalk.green(GLYPH.delivered) : chalk.yellow('?');
         const who = b.answer.answeredFrom + (b.answer.answeredBy ? ` (${b.answer.answeredBy})` : '');
         console.log(`${indent}  ${chalk.green('answered')} by ${who} ${verified}`);
     }
@@ -98,7 +114,7 @@ function renderBlock(b, localHost, indent = '') {
         console.log(`${indent}  ${chalk.dim('notified')} ${relTime(b.notifiedAt)}`);
     }
     if (!b.answer && !b.parkedAt) {
-        console.log(`${indent}  ${chalk.dim('reply:')} agents message ${b.mailboxId} "<answer>"`);
+        console.log(`${indent}  ${chalk.dim(formatFeedReplyHint(b.mailboxId))}`);
     }
     console.log();
 }
@@ -257,17 +273,20 @@ export function registerFeedCommand(program) {
             console.log(chalk.gray(digest ? 'No open blocks after stall suppression.' : 'No open blocks.'));
             return;
         }
+        // Shared fleet-comms masthead (same family as `agents mailboxes`).
+        console.log(masthead({
+            title: 'they need you',
+            accent: 'amber',
+            host: self,
+            right: formatFeedMastheadRight(blocks),
+        }));
+        console.log();
         if (opts.flat) {
-            console.log(chalk.bold(`${blocks.length} open block${blocks.length === 1 ? '' : 's'}:\n`));
             for (const b of blocks)
                 renderBlock(b, self);
             return;
         }
         const groups = groupBlocksByOutcome(blocks);
-        const openOutcomes = groups.filter((g) => g.counts.open > 0).length;
-        console.log(chalk.bold(`${groups.length} outcome${groups.length === 1 ? '' : 's'} · ${blocks.length} block${blocks.length === 1 ? '' : 's'}` +
-            (openOutcomes > 0 ? ` · ${openOutcomes} need you` : '') +
-            ':\n'));
         for (const g of groups)
             renderOutcomeGroup(g, self);
     });

package/dist/commands/funnel.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `agents funnel` — thin Tailscale Funnel wrapper for webhook ingress nodes.
+ */
+import type { Command } from 'commander';
+export declare function registerFunnelCommand(program: Command): void;

package/dist/commands/funnel.js

@@ -0,0 +1,62 @@
+import chalk from 'chalk';
+import { buildFunnelStatusCommand, buildFunnelUpCommand, parseFunnelPort } from '../lib/funnel.js';
+import { resolveHost } from '../lib/hosts/registry.js';
+import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
+import { sshTargetFor } from '../lib/hosts/types.js';
+import { sshExec } from '../lib/ssh-exec.js';
+async function resolveIngressHost(name) {
+    const host = await resolveHost(name);
+    if (!host)
+        throw new Error(`Unknown host "${name}". Enroll it with agents hosts add, or sync devices first.`);
+    const os = host.os ?? resolveRemoteOsSync(host.name);
+    if (os === 'windows') {
+        throw new Error('Tailscale Funnel requires a host with the Tailscale CLI; Windows cannot host this ingress path.');
+    }
+    return host;
+}
+async function runOnHost(hostName, command) {
+    const host = await resolveIngressHost(hostName);
+    const target = sshTargetFor(host);
+    const result = sshExec(target, command, { timeoutMs: 30_000, multiplex: true });
+    if (result.code !== 0) {
+        throw new Error((result.stderr || result.stdout).trim() || `ssh exited ${result.code ?? 'without a code'}`);
+    }
+    const out = result.stdout.trim();
+    if (out)
+        console.log(out);
+}
+export function registerFunnelCommand(program) {
+    const funnel = program
+        .command('funnel')
+        .description('Manage Tailscale Funnel exposure for a fleet webhook receiver.');
+    funnel
+        .command('status <host>')
+        .description('Show Tailscale Funnel status on a fleet host.')
+        .action(async (host) => {
+        try {
+            await runOnHost(host, buildFunnelStatusCommand());
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    funnel
+        .command('up <host>')
+        .description('Expose a localhost webhook receiver through Tailscale Funnel.')
+        .requiredOption('--local-port <n>', 'Local receiver port on the remote host')
+        .option('--port <n>', 'Public Funnel port: 443, 8443, or 10000', '443')
+        .action(async (host, opts) => {
+        try {
+            const publicPort = parseFunnelPort(opts.port ?? '443');
+            const localPort = Number.parseInt(opts.localPort, 10);
+            const command = buildFunnelUpCommand(publicPort, localPort);
+            await runOnHost(host, command);
+            console.log(chalk.green(`Funnel enabled on ${host}: public :${publicPort} → localhost:${localPort}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/hosts.js

@@ -18,6 +18,7 @@ import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { listTasks, loadTask, findTaskByName, findTaskBySessionId } from '../lib/hosts/tasks.js';
 import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
 import { showHostTaskLog } from '../lib/hosts/logs.js';
+import { stopDispatchedTask } from '../lib/hosts/dispatch.js';
 /** Parse `user@host` or `host` into its pieces. */
 function parseTarget(target) {
     const at = target.indexOf('@');
@@ -201,6 +202,42 @@ async function doLogs(ref, follow, full) {
     if (res.exitCode !== undefined)
         process.exitCode = res.exitCode;
 }
+/** Resolve a host-task ref (id, --name handle, or session id) or null. */
+function resolveTaskRef(ref) {
+    return loadTask(ref) ?? findTaskByName(ref) ?? findTaskBySessionId(ref);
+}
+async function doStop(ref) {
+    // Heal first so we don't try to kill a process that already exited.
+    const current = resolveTaskRef(ref);
+    if (!current) {
+        console.log(chalk.red(`Unknown task "${ref}".`));
+        process.exitCode = 1;
+        return;
+    }
+    const task = reconcileRunningTasks([current])[0] ?? current;
+    if (task.status !== 'running') {
+        console.log(chalk.gray(`Task ${task.id} is already ${task.status}` + (task.exitCode !== undefined ? ` (exit ${task.exitCode})` : '') + '.'));
+        return;
+    }
+    try {
+        const stopped = stopDispatchedTask(task);
+        const statusColor = stopped.status === 'completed' ? chalk.green : chalk.yellow;
+        const exitNote = stopped.exitCode === 143
+            ? 'exit 143 / SIGTERM'
+            : stopped.exitCode !== undefined
+                ? `exit ${stopped.exitCode}`
+                : stopped.status;
+        console.log(chalk.green(`Stopped ${stopped.id}`) +
+            chalk.gray(` on ${stopped.host}`) +
+            '  ' + statusColor(stopped.status) +
+            chalk.gray(` (${exitNote})`));
+        console.log(chalk.gray(`Logs: agents hosts logs ${stopped.id}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err?.message ?? err));
+        process.exitCode = 1;
+    }
+}
 /** Register the `agents hosts` command tree. */
 export function registerHostsCommand(program) {
     const hosts = program
@@ -239,4 +276,9 @@ export function registerHostsCommand(program) {
         .option('-f, --follow', 'Follow live output')
         .option('-m, --full', 'Show the full raw combined-stdout log instead of the concise summary')
         .action((id, opts) => doLogs(id, !!opts.follow, !!opts.full));
+    hosts
+        .command('stop <id>')
+        .alias('kill')
+        .description('Terminate a running host task from this machine (SIGTERM process group; marks failed/143).')
+        .action((id) => doStop(id));
 }