@phnx-labs/agents-cli 1.20.63 → 1.20.64

package/CHANGELOG.md

@@ -2,11 +2,27 @@
 
 ## 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>`
@@ -18,6 +34,7 @@
   `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

package/README.md

@@ -361,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>`.

package/dist/commands/exec.js

@@ -329,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".'));
                 }
@@ -374,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) {

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/lease.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `agents lease` — manage the disposable cloud boxes used by `agents run --lease`.
+ *
+ * Today: `agents lease gc`, which stops expired + idle "orphan" boxes that are
+ * holding a provider's server quota (the cause of the `server_limit` 403 a new
+ * lease hits). Reaping is conservative: only boxes whose lease has expired AND
+ * that have been untouched for a safety window are eligible (see `isReapSafe`),
+ * so a box a concurrent run just reused is never stopped.
+ */
+import type { Command } from 'commander';
+/** Validate a Hetzner token against the live API. Exported for unit tests (fetch injectable). */
+export declare function validateHetznerToken(token: string, fetchImpl?: typeof fetch): Promise<'valid' | 'invalid' | 'unreachable'>;
+/**
+ * One-time credential setup for `agents run --lease` (Hetzner today). Opens the
+ * token page, collects a token, validates it against the live API, stores it in
+ * the keychain bundle `hetzner.com`, and persists it as the default lease bundle
+ * (so `--lease` needs no env var or flag afterward). Returns true on success.
+ * Never throws for expected outcomes (non-interactive, cancel, repeated failure).
+ */
+export declare function runLeaseSetup(opts?: {
+    provider?: string;
+}): Promise<boolean>;
+export declare function registerLeaseCommand(program: Command): void;

package/dist/commands/lease.js

@@ -0,0 +1,201 @@
+/**
+ * `agents lease` — manage the disposable cloud boxes used by `agents run --lease`.
+ *
+ * Today: `agents lease gc`, which stops expired + idle "orphan" boxes that are
+ * holding a provider's server quota (the cause of the `server_limit` 403 a new
+ * lease hits). Reaping is conservative: only boxes whose lease has expired AND
+ * that have been untouched for a safety window are eligible (see `isReapSafe`),
+ * so a box a concurrent run just reused is never stopped.
+ */
+import { spawn } from 'child_process';
+import chalk from 'chalk';
+import { crabboxList, reapSafeOrphans, reapOrphans, setLeaseSecretsBundle } from '../lib/crabbox/cli.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { bundleExists, readBundle, writeBundle, keychainRef, bundleItemStore } from '../lib/secrets/bundles.js';
+import { secretsKeychainItem } from '../lib/secrets/index.js';
+function fmtIdle(box) {
+    if (box.lastTouchedAt === null)
+        return 'idle ?';
+    const iso = new Date(box.lastTouchedAt * 1000).toISOString().slice(0, 16).replace('T', ' ');
+    return `idle since ${iso}Z`;
+}
+const HETZNER_BUNDLE = 'hetzner.com';
+const HCLOUD_KEY = 'HCLOUD_TOKEN';
+const HETZNER_CONSOLE_URL = 'https://console.hetzner.cloud/';
+/** Best-effort: open a URL in the user's default browser. Never throws. */
+function openUrl(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        const p = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        p.on('error', () => { });
+        p.unref();
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Validate a Hetzner token against the live API. Exported for unit tests (fetch injectable). */
+export async function validateHetznerToken(token, fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl('https://api.hetzner.cloud/v1/servers?per_page=1', {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (res.ok)
+            return 'valid';
+        if (res.status === 401 || res.status === 403)
+            return 'invalid';
+        return 'unreachable';
+    }
+    catch {
+        return 'unreachable';
+    }
+}
+/**
+ * One-time credential setup for `agents run --lease` (Hetzner today). Opens the
+ * token page, collects a token, validates it against the live API, stores it in
+ * the keychain bundle `hetzner.com`, and persists it as the default lease bundle
+ * (so `--lease` needs no env var or flag afterward). Returns true on success.
+ * Never throws for expected outcomes (non-interactive, cancel, repeated failure).
+ */
+export async function runLeaseSetup(opts = {}) {
+    const provider = opts.provider ?? 'hetzner';
+    if (provider !== 'hetzner') {
+        console.error(chalk.yellow(`lease setup: only 'hetzner' is supported today (got '${provider}').`));
+        return false;
+    }
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('lease setup needs an interactive terminal. For CI/headless, set AGENTS_LEASE_SECRETS_BUNDLE ' +
+            'or store HCLOUD_TOKEN in a keychain bundle.'));
+        return false;
+    }
+    console.error(chalk.bold('\nSet up leasing (Hetzner) — one time (~30s):'));
+    console.error(chalk.dim('Opening the Hetzner console. Create/select a project, then Security → API Tokens →'));
+    console.error(chalk.dim('Generate a token with Read & Write permission, and copy it.\n'));
+    openUrl(HETZNER_CONSOLE_URL);
+    const { password } = await import('@inquirer/prompts');
+    const ora = (await import('ora')).default;
+    try {
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const token = (await password({ message: 'Paste your Hetzner API token:', mask: true })).trim();
+            if (!token) {
+                console.error(chalk.yellow('No token entered.'));
+                continue;
+            }
+            const spinner = ora('Validating token against the Hetzner API…').start();
+            const result = await validateHetznerToken(token);
+            if (result === 'invalid') {
+                spinner.fail('Token rejected by Hetzner (401/403). Try again.');
+                continue;
+            }
+            if (result === 'unreachable')
+                spinner.warn('Could not reach the Hetzner API to validate — storing anyway.');
+            else
+                spinner.succeed('Token valid — Hetzner API reachable.');
+            // Store into the `hetzner.com` keychain bundle (mirrors writeSyncBundle).
+            const bundle = bundleExists(HETZNER_BUNDLE)
+                ? readBundle(HETZNER_BUNDLE)
+                : { name: HETZNER_BUNDLE, description: 'Hetzner Cloud API token for crabbox leases', vars: {} };
+            const store = bundleItemStore(bundle.backend);
+            store.set(secretsKeychainItem(HETZNER_BUNDLE, HCLOUD_KEY), token);
+            bundle.vars[HCLOUD_KEY] = keychainRef(HCLOUD_KEY);
+            writeBundle(bundle);
+            setLeaseSecretsBundle(HETZNER_BUNDLE);
+            console.error(chalk.green(`\n✔ Stored in keychain bundle '${HETZNER_BUNDLE}' and set as the default lease provider.`));
+            console.error(chalk.dim('  Run `agents run <agent> "…" --lease` — no env var, no flag needed.'));
+            return true;
+        }
+        console.error(chalk.yellow('lease setup: no valid token after 3 attempts — aborted.'));
+        return false;
+    }
+    catch (e) {
+        if (isPromptCancelled(e)) {
+            console.error(chalk.yellow('lease setup cancelled.'));
+            return false;
+        }
+        throw e;
+    }
+}
+export function registerLeaseCommand(program) {
+    const lease = program
+        .command('lease')
+        .description('Manage the disposable cloud boxes used by `agents run --lease`.');
+    lease
+        .command('setup')
+        .description('One-time credential setup so `agents run --lease` works with no env var or flag.')
+        .option('--provider <name>', 'Cloud provider (only hetzner today)', 'hetzner')
+        .action(async (opts) => {
+        const ok = await runLeaseSetup({ provider: opts.provider });
+        process.exit(ok ? 0 : 1);
+    });
+    lease
+        .command('gc')
+        .description('Stop expired, idle lease boxes that are holding your provider quota. Safe: never stops a box in active use.')
+        .option('--dry-run', 'List reap-safe orphan boxes without stopping any', false)
+        .option('--yes', 'Stop them without the interactive confirm', false)
+        .option('--json', 'Output JSON', false)
+        .action(async (opts) => {
+        const boxOpts = { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE };
+        const nowSecs = Math.floor(Date.now() / 1000);
+        let candidates;
+        try {
+            candidates = reapSafeOrphans(crabboxList(boxOpts), nowSecs);
+        }
+        catch (e) {
+            console.error(chalk.red(`lease gc: ${e.message}`));
+            process.exit(1);
+            return;
+        }
+        if (candidates.length === 0) {
+            if (opts.json)
+                console.log(JSON.stringify({ candidates: [], reaped: [] }));
+            else
+                console.error(chalk.gray('No reap-safe orphan boxes — nothing to collect.'));
+            return;
+        }
+        if (!opts.json) {
+            console.error(chalk.bold(`${candidates.length} reap-safe orphan box(es):`));
+            for (const b of candidates) {
+                console.error(`  ${chalk.cyan(b.slug)} ${chalk.dim(`(${b.class ?? '?'}, ${fmtIdle(b)})`)}`);
+            }
+        }
+        if (opts.dryRun) {
+            if (opts.json)
+                console.log(JSON.stringify({ candidates, reaped: [] }, null, 2));
+            else
+                console.error(chalk.gray('\n--dry-run: nothing stopped. Re-run with --yes to stop them.'));
+            return;
+        }
+        // Destructive: stopping boxes the agent did not create needs an explicit yes.
+        if (!opts.yes) {
+            const { isInteractiveTerminal, isPromptCancelled } = await import('./utils.js');
+            if (!isInteractiveTerminal()) {
+                console.error(chalk.yellow('Refusing to stop boxes without --yes in a non-interactive shell.'));
+                process.exit(1);
+                return;
+            }
+            try {
+                const { confirm } = await import('@inquirer/prompts');
+                const ok = await confirm({ message: `Stop these ${candidates.length} box(es)?`, default: false });
+                if (!ok) {
+                    console.error(chalk.yellow('Aborted — no boxes stopped.'));
+                    return;
+                }
+            }
+            catch (e) {
+                if (isPromptCancelled(e)) {
+                    console.error(chalk.yellow('Aborted — no boxes stopped.'));
+                    return;
+                }
+                throw e;
+            }
+        }
+        // Re-list at stop time (freshness re-check) so a box touched since the
+        // preview is not stopped out from under an active run.
+        const { candidates: stopped, reaped } = reapOrphans({ ...boxOpts, nowSecs });
+        if (opts.json)
+            console.log(JSON.stringify({ candidates: stopped, reaped }, null, 2));
+        else
+            console.error(chalk.green(`Stopped ${reaped.length}/${stopped.length} box(es): ${reaped.join(', ') || '(none)'}`));
+    });
+}

package/dist/commands/mailboxes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `agents mailboxes` — fleet comms: 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`:
+ * one box per logical agent (session UUID / teams agentId / loop runId). This
+ * command surfaces which boxes exist, how much mail each holds, the messages that
+ * flowed BETWEEN agents (including already-consumed ones), and — with `--watch` —
+ * the live stream as it happens. Rendering rides the shared comms engine
+ * (`lib/comms-render.ts`): masthead, sparkline, aggregate, graphEdges.
+ *
+ *   agents mailboxes                     overview: masthead + 24h sparkline + boxes + recent log
+ *   agents mailboxes <id>                one box in full (inbox / processing / consumed)
+ *   agents mailboxes --watch             live tail of cross-box traffic until ⌃C
+ *   agents mailboxes --between <a> <b>   one relationship as a thread, either direction
+ *   agents mailboxes --graph             who-talks-to-whom adjacency, busiest first
+ *   --from/--to/--since                  filter the overview log and the --watch stream
+ */
+import type { Command } from 'commander';
+export declare function registerMailboxesCommand(program: Command): void;