@phnx-labs/agents-cli 1.22.7 → 1.22.9

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 1.22.9
+
+- **`agents ssh auto` and `agents teams add --device auto` no longer reject with "Unknown device 'auto'" (RUSH-2185).** The `auto` affinity sentinel was a `run`-only preprocessing step (`applyDeviceAutoToOptions` in `smart-launch.ts`, wired only from `agents run`'s exec path) — every other `--host`/`--device` caller went straight to the shared resolver, which had no idea what `auto` meant and reported it as an unregistered device. `matchHost` (the one core every `--host`/`--device` caller shares) now resolves `auto` directly via the same `resolveDeviceAffinity` engine `run` uses, so `agents ssh`, `agents teams add`, and anything else routed through `matchHost`/`resolveHost` (including the generic `--host`/`--device` passthrough) pick a device the same way. `agents teams add --device auto` landing on the local machine now just runs the teammate locally, matching `run`'s "null pick = local" outcome; `agents ssh auto` refuses a local pick with a clear message instead of self-SSHing, since `agents ssh` exists to dial OUT to a remote box. Source: `apps/cli/src/lib/hosts/registry.ts`, `apps/cli/src/lib/devices/resolve-target.ts`, `apps/cli/src/commands/ssh.ts`, `apps/cli/src/commands/teams.ts`, `apps/cli/docs/00-concepts.md`, `apps/cli/docs/hosts.md`, `apps/cli/docs/teams.md`.
+
+- **`agents harness edit` gains `--auth-provider`, `--fallback-model`, and `--from-secrets`; `add`/`fork` gain an interactive wizard and `--from-secrets`.** `edit` (already shipped with `--model`/`--base-url`/`--version`/`--description`) now also repoints auth at a different keychain-backed provider, sets or clears (`--fallback-model ""`) the same-host fallback model retried on a rate limit, and — like `add`/`fork` — accepts `--from-secrets <bundle>[:<key>]` to copy a value out of an existing `agents secrets` bundle into the harness's own keychain item once, instead of retyping a key already stored elsewhere (the item it writes to, `agents-cli.<provider>.token`, is never gated behind the biometry-required prefixes, so later reads stay silent). `agents harness add`/`fork` now accept `[name]`/`[source] [name]` as optional positionals — run either with insufficient flags in an interactive terminal and a picker (fork from a native host or existing harness → a built-in preset or "build custom" → the harness's name, pre-filled with the preset's own name → how to get the key) replaces the old hard error; flags remain fully supported for scripts, and a non-interactive shell still gets the original error. Source: `apps/cli/src/commands/harness.ts`, `apps/cli/src/commands/profiles.ts`, `apps/cli/docs/profiles.md`.
+
+- **`agents run --lease` is reuse-first against the crabbox profile pool, with a
+  `--fresh` opt-out.** A bare `--lease` used to always lease a brand-new box, so
+  bursts of runs (e.g. resumed sessions) stacked up idle `keep=true` boxes at
+  full monthly cost. Now, before warming a new box, the run looks for a warm box
+  carrying the same `profile` label the warmup would use (read from the repo's
+  `.crabbox.yaml`, matching `scripts/sandbox.sh`'s `pick_ready_box`) and the same
+  network mode — a tailnet box is never handed to a public run or vice versa —
+  and reuses the first one `crabbox status` reports SSH-ready, keeping it after
+  the run. A not-ready pool box is skipped, never stopped. `--fresh` forces the
+  old behavior (brand-new box, torn down after the run); `--box <slug>` is
+  unchanged. Source: `apps/cli/src/lib/crabbox/lease.ts`,
+  `apps/cli/src/lib/crabbox/cli.ts`, `apps/cli/src/lib/crabbox/config.ts`,
+  `apps/cli/src/commands/exec.ts`.
+
+- **The menu bar now notices and reports when the scheduler dies — instead of
+  staying silent forever.** The only proactive "routines overdue / scheduler
+  down" signal was `notifyOverdue` (`src/lib/overdue.ts`), fired from inside
+  `runDaemon()` — so it could never fire while the daemon itself was down, the
+  exact outage it exists to report. `MenubarHelper` is a separate launchd
+  KeepAlive service that stays alive when the daemon dies, so its 10s tick now
+  polls daemon liveness independently of the dropdown ever being opened; once
+  it has been continuously unreachable for ~30s (debounced past a routine
+  restart blip), it fires one native notification ("Scheduler stopped —
+  routines won't run") through its own `NSUserNotificationCenter` delivery —
+  no daemon, no CLI spawn required — and lights the always-visible menu-bar
+  badge (`⏻`) until the scheduler comes back. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`.
+
+- **Observe umbrella aliases: `inbox`, `timeline`, `roster` (Phase 3 surface consolidation).**
+  Thin doors onto existing readers (no store merge): `agents inbox` ≡ `feed`,
+  `agents timeline` ≡ `feed --filter updates`, `agents roster` ≡ `sessions --active`.
+  Root help gains an Observe section; `agents audit` stays the tamper-evident run
+  log (not an events alias). Source: `apps/cli/src/lib/observe-aliases.ts`,
+  `apps/cli/src/commands/feed.ts`, `apps/cli/src/commands/sessions.ts`.
+
+- **Daemon usage refresh is a fixed 5-minute per-host schedule, concurrency-safe, and Touch-ID-free.**
+  Each machine's daemon still owns its own usage cache (no fleet-wide store). Account live
+  fetches are now scheduled every **5 minutes** (was adaptive 90s–15m), with a 60s wake to
+  notice due accounts after backoff ends. Cache writes use a file lock + atomic rename so a
+  concurrent `agents view` background refresh cannot tear or drop rows. The daemon path
+  loads Claude credentials with **`fileOnly`** (setup-token / no-ACL cache / `.credentials.json`
+  only) and never opens the ACL-bound macOS keychain item, so a background tick cannot pop
+  Touch ID. Refresh still skips a provider under 429 backoff and still never rotates
+  single-use Claude refresh tokens.
+
+## 1.22.8
+
+- **`agents browser` now gates cross-machine drives behind per-device consent.** `agents browser <cmd> --host <device>` already routes a browser command to another fleet machine over SSH and drives its browser — but nothing asked that machine's permission, so any box you could SSH to, you could drive. A new device-local `browser.remote-control` setting (off by default, never synced) fixes that: a fleet-remote `browser --host <this-machine> start` is refused with an actionable message until the owner runs `agents browser remote-control on` here. Local starts (no `--host`) are never gated. The fleet passthrough marks every `--host` dispatch with `AGENTS_FLEET_REMOTE` so the far side can tell a cross-machine drive from a local one. New command: `agents browser remote-control [on|off]` (no arg prints status; `--json` supported). Source: `apps/cli/src/lib/browser/remote-control.ts`, `apps/cli/src/commands/browser.ts`, `apps/cli/src/lib/hosts/passthrough.ts`, `apps/cli/src/lib/device-config.ts`, `apps/cli/docs/browser.md`.
+
+- **`agents browser` tasks are now attributed to the caller that ran `start`, not
+  to the browser daemon.** `Task.owner` (RUSH-2020) was resolved with
+  `resolveActor()` *inside* the shared, long-lived browser daemon, so every task —
+  no matter which agent or person opened it — was stamped with the identity of
+  whoever happened to start the daemon. The caller's identity is now forwarded over
+  IPC: the CLI (the caller's own process) puts `actor` (`resolveActor().id`) and
+  `launchId` (`$AGENT_LAUNCH_ID`, the per-run id `exec.ts` injects for every harness)
+  on the `start` request, and the daemon stamps exactly those. Adds `Task.launchId` —
+  which run created a task — the scope a later `browser status --mine` and the
+  no-flag current-task default will filter on. Source:
+  `apps/cli/src/lib/browser/types.ts`, `apps/cli/src/lib/browser/service.ts`,
+  `apps/cli/src/lib/browser/ipc.ts`, `apps/cli/src/commands/browser.ts`.
+
+- **`agents harness edit` and `agents harness rename` are now real commands.** `editProfile` and `renameProfile` already existed in `lib/profiles.ts` but nothing on the CLI surface reached them, so changing a custom harness meant hand-editing its YAML. `agents harness edit <name>` applies `--model`, `--base-url`, `--version`, and `--description` in place, preserving fork lineage (an edit never marks a harness as forked from itself). `agents harness rename <name> <new-name>` renames the YAML file and its `name` field, and rewrites `forkedFrom` on every harness that pointed at the old name so the fork graph stays accurate. There is deliberately no `--label`: the header `agents view` prints is derived from the harness name, so renaming is how you change it.
+
+- **Run-time messages call a custom harness a "custom harness", not a "profile".** When you `agents run <name>` a custom harness (created with `agents harness add`), the CLI now says `Resolved custom harness '<name>'` and, for a discarded cost tier, `cost tiers don't apply to custom harness '<name>'` — instead of the legacy internal noun "profile". The `--strategy` and account-picker notices on a custom-harness run are aligned too. Behavior is unchanged; the legacy `agents profiles` alias still works. Source: `apps/cli/src/commands/exec.ts`.
+
+- **Placement model + `agents run --where` (Phase 2 surface consolidation).**
+  "Where does the body run?" is one shared object (`local | device | fleet | cloud | lease`)
+  in `src/lib/placement.ts`. `agents run --where device:<name>|auto|lease[:backend]|local`
+  expands into the existing `--host` / `--lease` paths; mixing doors fails loud. Docs
+  (`00-concepts.md` § Placement, `hosts.md`) and help on run / routines / monitors teach
+  the matrix — including that monitors `--device` is **owner**, not body placement.
+  Old flags remain aliases. Source: `apps/cli/src/lib/placement.ts`, `apps/cli/src/commands/exec.ts`.
+
+- **`agents harness fork` no longer accepts `--label` (breaking change).** The `--label` flag was used to set a human-facing display name for a custom harness. Display names are now always derived from the profile's `name` via a curated vendor/brand table (`deepseek-flash` → `DeepSeek Flash`, `spark` → `Spark`), so the flag is superfluous. Any script that passes `--label` to `agents harness fork` will receive a CLI error; remove the flag to migrate.
+
+- **`agents run` no longer auto-picks an account whose token the server has already rejected.** Account rotation judged an account "signed in" from a local heuristic — a credential file is present and its email decodes — which cannot tell a good token from a revoked-but-unexpired one, so `balanced`/`available`/`run auto` could route into a `revoked` account and die at spawn ("session expired"). Eligibility now also reads the daemon's live auth-health probe (`auth-health.ts`): a `revoked` (401/403) account is excluded from the pick, reported as `revoked` by the pre-flight readiness check, shown as "needs re-login" in the account picker, and named in the teams throttle warning. Fail-open: a missing probe or any non-revoked verdict never blocks a launch (a cached `revoked` keeps gating until the daemon's next probe clears it). Source: `apps/cli/src/lib/rotate.ts`, `apps/cli/src/commands/run-account-picker.ts`, `apps/cli/src/commands/teams.ts`, `apps/cli/docs/hosts.md`.
+
+- **Scheduled routines no longer overlap or outlive their configured timeout (RUSH-2186).** Detached cron, catchup, and monitor launches now take a cross-process per-routine claim and refuse a second fire while the prior run is alive. The configured deadline is persisted in run metadata; both the live runner and the restart-recovery monitor kill the owned process tree and record `timeout` when it expires. Source: `apps/cli/src/lib/runner.ts`, `apps/cli/src/lib/routines.ts`, `apps/cli/docs/03-routines.md`.
+
+- **`agents snapshot` — one-process poll for inventory + active sessions (Phase 4 surface consolidation).**
+  Consumers (Factory, scripts, menubar) were forking `view --json` × N harnesses plus
+  `sessions --active --json` (and sometimes feed) on every tick. `agents snapshot --json`
+  returns the same shapes in one invocation: `inventory` (view), `sessions` (active rows),
+  optional `--with-feed` / `--with-sync`. Default sessions scope is this machine; `--all-hosts`
+  matches full `sessions --active` fan-out. Does **not** redefine `agents status`, which stays
+  the UnifiedSyncStatus sync contract. Source: `apps/cli/src/commands/snapshot.ts`,
+  `apps/cli/src/lib/snapshot.ts`.
+
 ## 1.22.7
 
 - **`agents feed --project <name>` scopes the whole feed to one project.** Open
@@ -939,6 +1034,8 @@
 
 ## 1.20.92
 
+- **`agents sessions render <id...>` produces shareable, redacted Markdown instead of raw harness JSONL.** Claude, Codex, Kimi, Grok, Cursor, and Droid transcripts flow through the existing normalized `SessionEvent[]` parsers, then render with the same session-browser preview at the top, ordered user/assistant turns, fenced shell commands, JSON tool arguments, and explicitly truncated tool results. Redaction remains on by default through the canonical redactor, now also masking Unix/macOS/Windows home-directory identities and live secret values; `--no-redact` is local-only. Reasoning defaults to omitted and can be folded or included explicitly. One or several selected sessions can be written to a mode-`0600` Markdown file, and `--json` exposes the rendered documents for machine callers. The repo session skill and transcript-sharing guidance now require rendering `.md` before creating a confidential gist. Source: `apps/cli/src/commands/sessions-render.ts`, `apps/cli/src/lib/session/render.ts`, `apps/cli/src/lib/redact.ts`, `.agents/skills/sessions/SKILL.md`.
+
 - **`agents sessions` rows show creation time as well as last activity (RUSH-2107).**
   The trailing time cell used to carry one unlabeled "X ago" — last activity — so a
   row could not say when the session began or how long it had been alive. It now

package/README.md

@@ -255,6 +255,9 @@ agents sessions --project my-app
 # Read a full conversation
 agents sessions a1b2c3d4 --markdown
 
+# Render a shareable, redacted Markdown transcript with the session preview on top
+agents sessions render a1b2c3d4 -o session.md
+
 # Just the last 3 turns, user messages only
 agents sessions a1b2c3d4 --last 3 --include user
 
@@ -323,6 +326,8 @@ Each live session resolves to `working`, `waiting_input` (with why -- a question
 
 Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work (including parsed Bash commands -- `git`, `npm`, `ffmpeg`, `ssh`, and so on), and the last test verdict -- the signals to reload a task in seconds.
 
+Sharing a session uses `agents sessions render <id> -o session.md`, not the raw harness JSONL. The document starts with that same preview, then presents user and assistant turns, fenced commands, structured tool arguments, and bounded tool output. Credential-shaped values and local home paths are redacted by default; `--no-redact` is for local-only inspection.
+
 ### Resume anywhere — and stay resumed
 
 Pick up any past conversation and drop it back into a terminal:

package/dist/commands/browser.js

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBrowserProfile, getConfiguredDefaultProfileName, DEFAULT_BROWSER_PROFILE_NAME, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
 import { updateMeta } from '../lib/state.js';
+import { resolveActor } from '../lib/actor.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
 import { parseSecretRef } from '../lib/browser/secret-ref.js';
 import { readAndResolveBundleEnv, isHeadlessSecretsContext, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
@@ -13,6 +14,8 @@ import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.
 import { parseTargetFilter } from '../lib/browser/service.js';
 import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest, } from '../lib/browser/ipc.js';
 import { browserTaskPicker } from './browser-picker.js';
+import { assertRemoteControlAllowed } from '../lib/browser/remote-control.js';
+import { getConfigValue, setConfigValue } from '../lib/device-config.js';
 import { isInteractiveTerminal } from './utils.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { buildHar } from '../lib/browser/har.js';
@@ -76,6 +79,12 @@ export function registerBrowserCommand(program) {
       agents browser navigate https://example.com
       agents browser screenshot
 
+      # Drive another machine's browser (needs its consent — see remote-control)
+      agents browser start --host zion
+
+      # Allow / deny other fleet machines driving THIS machine's browser
+      agents browser remote-control on
+
       # End the session when done
       agents browser done
     `,
@@ -609,6 +618,42 @@ function registerProfilesCommands(browser) {
     });
 }
 function registerTaskCommands(browser) {
+    browser
+        .command('remote-control [state]')
+        .description("Allow or deny other fleet machines driving THIS machine's browser over `browser --host`. " +
+        '`on`/`off` to set (device-local, never synced); no argument prints the current value. Default off.')
+        .option('--json', 'Output as JSON')
+        .action((state, opts) => {
+        const KEY = 'browser.remote-control';
+        if (state === undefined) {
+            const cur = getConfigValue(KEY).value === true;
+            if (opts.json) {
+                console.log(JSON.stringify({ remoteControl: cur }));
+                return;
+            }
+            console.log(`Remote browser control (this machine): ${cur ? 'on' : 'off'}`);
+            if (!cur)
+                console.log('Enable with: agents browser remote-control on');
+            return;
+        }
+        const norm = state.toLowerCase();
+        const onWords = ['on', 'true', 'yes', 'allow', 'enable'];
+        const offWords = ['off', 'false', 'no', 'deny', 'disable'];
+        if (!onWords.includes(norm) && !offWords.includes(norm)) {
+            console.error(`Expected "on" or "off", got "${state}".`);
+            process.exit(1);
+        }
+        const value = onWords.includes(norm);
+        setConfigValue(KEY, value);
+        if (opts.json) {
+            console.log(JSON.stringify({ remoteControl: value }));
+            return;
+        }
+        console.log(`Remote browser control (this machine) is now ${value ? 'on' : 'off'}.`);
+        console.log(value
+            ? 'Other fleet machines can now drive this browser via `browser --host <this-device>`.'
+            : 'Cross-machine `browser --host` drives to this machine are refused.');
+    });
     browser
         .command('start')
         .description('Start a browser task. Pass --profile <name>; omit to use your configured default (`agents browser profiles set-default`), else auto-pick an installed Chromium-family browser.')
@@ -622,6 +667,16 @@ function registerTaskCommands(browser) {
         .option('--duration <sec>', 'Recording duration cap in seconds (with --record; default 60)', (v) => parseInt(v, 10))
         .option('--max-mb <mb>', 'Recording size cap in MB (with --record; default 25)', (v) => parseInt(v, 10))
         .action(async (opts) => {
+        // Consent gate: a fleet-remote `browser --host <this-machine> start` may
+        // only open a browser here if the owner opted in. Refuse before we resolve
+        // or auto-create any profile. Local starts are never gated.
+        try {
+            assertRemoteControlAllowed();
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
         let profileName = opts.profile;
         if (!profileName) {
             try {
@@ -698,6 +753,12 @@ function registerTaskCommands(browser) {
             url: opts.url,
             endpoint: opts.endpoint,
             skipDomainSkill: opts.skills === false,
+            // Forward the caller's identity: the browser daemon is shared, so it
+            // cannot resolve who/which-run called `start`. `resolveActor()` runs
+            // here in the CLI (the caller's process); `$AGENT_LAUNCH_ID` is the
+            // per-run id exec.ts injects for every harness.
+            actor: resolveActor().id,
+            launchId: process.env.AGENT_LAUNCH_ID,
         });
         if (!response.ok) {
             console.error(response.error);

package/dist/commands/exec.js

@@ -553,15 +553,17 @@ export function registerRunCommand(program) {
         .option('--budget <tokens>', 'Loop token hard-cap: stop once cumulative tokens reach this (stoppedBy: budget), enforced outside the agent. Loop only.')
         .option('--until <signal>', 'Loop stop condition. `signal` reads <runDir>/loop-signal.json {continue,reason} each iteration; absent or continue:false stops (fail-closed). Loop only.')
         .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.')
-        .option('--host <name>', 'Offload this run onto another machine over SSH — a device name, registered host, or user@host. Pass "auto" to pick from 14d usage affinity (most-used online device has highest probability). See `agents devices`.')
-        .option('--device <name>', 'Alias of --host. Pass "auto" for affinity-based device pick (same as --host auto).')
+        .option('--where <spec>', 'Where this run\'s body executes (one placement door): local | device:<name> | auto | lease[:backend]. Expands to --host/--lease. Do not combine with those flags. See docs/00-concepts.md#placement.')
+        .option('--host <name>', 'Offload this run onto another machine over SSH — a device name, registered host, or user@host. Pass "auto" to pick from 14d usage affinity (most-used online device has highest probability). Same as --where device:<name>. See `agents devices`.')
+        .option('--device <name>', 'Alias of --host. Pass "auto" for affinity-based device pick (same as --where auto).')
         .option('--remote-cwd <dir>', "Explicit host working directory for --host runs, used VERBATIM (overrides --cwd; usually --cwd suffices — it re-roots a local-home path onto the remote home). Pass a single-quoted '$HOME/…' or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you).")
         .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('--lease [backend]', "Run on a cloud box (via crabbox) and tear it down after — reuses a warm box from the repo's profile pool when one is ready (--fresh forces a new box). Optional backend selects the cloud (hetzner/aws/do). Same as --where lease[:backend]. Unlike --host, no machine is registered.")
         .option('--box <slug>', 'Reuse an existing warm crabbox box for this run instead of provisioning a disposable --lease box.')
         .option('--keep-box', 'With --lease, keep the box after the run instead of stopping it.')
+        .option('--fresh', "With --lease, always provision a brand-new box (skip the warm profile-pool reuse) and tear it down after the run.")
         .option('--reuse', 'With --lease, reuse the most-recently-used warm box if one exists (else provision fresh). The scriptable form of the interactive reuse picker.')
         .option('--bare', 'With --lease, skip copying your local ~/.agents setup (skills/hooks/commands/MCP) onto the box.')
         .option('--tailscale', 'Lease the box onto your tailnet (reachable only over Tailscale) rather than a public IP.')
@@ -601,6 +603,11 @@ export function registerRunCommand(program) {
       agents run auto "fix the flaky test" --mode edit
       agents run auto --host yosemite-s0 "fix the flaky test"   # pin the host
 
+      # Placement (one door — where the body runs). Old flags still work.
+      agents run claude "…" --where device:yosemite-s0   # = --host yosemite-s0
+      agents run claude "…" --where auto                 # = --device auto
+      agents run claude "fix CI" --where lease --mode edit
+
       # Open the session in a terminal tab — detected from where your sessions
       # already run (Ghostty / iTerm / Terminal.app); force one with a value
       agents run claude --terminal
@@ -615,6 +622,14 @@ export function registerRunCommand(program) {
       # Inject a keychain-backed secrets bundle
       agents run claude "deploy the worker" --secrets prod --mode edit
 
+      # Run on a cloud box — reuses a warm box from the repo's profile pool when
+      # one is ready (kept after the run), else leases a fresh box, torn down after
+      agents run claude "fix the failing tests" --lease
+
+      # Force a brand-new box (destroyed after), or target a warm box by slug
+      agents run claude "fix the failing tests" --lease --fresh
+      agents run claude "fix the failing tests" --box warm-one
+
       # Pass arbitrary native flags to the underlying CLI via -- separator
       agents run kimi -- --plan --some-kimi-option value
       agents run claude "fix the bug" -- --custom-flag
@@ -688,6 +703,36 @@ export function registerRunCommand(program) {
             await handleTerminalHandoff(agentSpec, options, prompt);
             return;
         }
+        // Placement: --where expands into --host / --lease before any dispatch.
+        // One door for "where does the body run?" — old flags remain aliases.
+        // See lib/placement.ts and docs/00-concepts.md#placement.
+        {
+            const { placementFromRunFlags, expandPlacementToRunFlags, PlacementError } = await import('../lib/placement.js');
+            try {
+                const placement = placementFromRunFlags(options);
+                if (options.where) {
+                    const expanded = expandPlacementToRunFlags(placement);
+                    if (expanded.host !== undefined)
+                        options.host = expanded.host;
+                    if (expanded.device !== undefined)
+                        options.device = expanded.device;
+                    if (expanded.lease !== undefined)
+                        options.lease = expanded.lease;
+                    if (expanded.box !== undefined)
+                        options.box = expanded.box;
+                    // Clear the where flag so remote re-entry (host dispatch) does not
+                    // re-expand and conflict with the concrete host we just set.
+                    options.where = undefined;
+                }
+            }
+            catch (err) {
+                if (err instanceof PlacementError) {
+                    console.error(chalk.red(err.message));
+                    process.exit(1);
+                }
+                throw err;
+            }
+        }
         // --notify: post a desktop notification when this run finishes. Armed on
         // process exit so it covers EVERY dispatch path below (local, --host,
         // --lease, the error path) instead of one branch. Only for headless runs
@@ -788,6 +833,14 @@ export function registerRunCommand(program) {
                 console.error(chalk.red('Pass either --lease to provision a disposable box, or --box <slug> to reuse a warm box — not both.'));
                 process.exit(1);
             }
+            if (options.fresh && options.box) {
+                console.error(chalk.red('--fresh forces a brand-new box; it cannot be combined with --box <slug> (which reuses one).'));
+                process.exit(1);
+            }
+            if (options.fresh && options.reuse) {
+                console.error(chalk.red('--fresh forces a brand-new box; it cannot be combined with --reuse.'));
+                process.exit(1);
+            }
             const backend = typeof options.lease === 'string' ? options.lease : undefined;
             // crabbox syncs this directory to the box via `git ls-files`; outside a
             // git repo that fails with "build sync file list: exit status 128" — but
@@ -812,12 +865,21 @@ export function registerRunCommand(program) {
             // ── F3 reuse (RUSH-1922) + F5 net-mode (RUSH-1924) ───────────────────
             // Resolve which box this run targets and how it is networked BEFORE any
             // provisioning. `--box` is an explicit reuse; otherwise, on an
-            // interactive tty, offer the warm boxes as a reuse picker (headless /
-            // --json never blocks — it provisions fresh unless --reuse/--box).
+            // interactive tty, offer the warm boxes as a reuse picker. Headless runs
+            // never block: leaseAndRun itself is reuse-first against the profile
+            // pool (a ready pool box is reused; none ready → warm a fresh one).
+            // `--fresh` opts out of every reuse path.
             const leaseSecretsBundle = process.env.AGENTS_LEASE_SECRETS_BUNDLE;
             const nowSecs = Math.floor(Date.now() / 1000);
             let reuseSlug = options.box;
-            if (options.lease && !reuseSlug) {
+            // The profile this run's pool/box carries: the repo's .crabbox.yaml
+            // `profile:` when declared (what crabbox warmup would label a fresh box
+            // with), else crabbox's default. Passing it to leaseAndRun makes the
+            // pool-reuse match interchangeable with a fresh warmup.
+            const repoRoot = gitToplevel(leaseCwd);
+            const { readCrabboxRepoProfile } = await import('../lib/crabbox/config.js');
+            const poolProfile = repoRoot ? readCrabboxRepoProfile(repoRoot) : undefined;
+            if (options.lease && !reuseSlug && !options.fresh) {
                 const { crabboxList } = await import('../lib/crabbox/cli.js');
                 const { reusableBoxes, formatBoxRow } = await import('./lease.js');
                 let warm = [];
@@ -825,9 +887,8 @@ export function registerRunCommand(program) {
                     warm = reusableBoxes(crabboxList({ secretsBundle: leaseSecretsBundle }), nowSecs);
                 }
                 catch {
-                    warm = []; // crabbox unavailable / no creds → just provision fresh
+                    warm = []; // crabbox unavailable / no creds → the pool check in leaseAndRun decides
                 }
-                const repoRoot = gitToplevel(leaseCwd);
                 const alwaysFresh = repoRoot ? isAlwaysFreshRepo(readAlwaysFreshRepos(), repoRoot) : false;
                 if (warm.length > 0 && !alwaysFresh) {
                     if (options.reuse) {
@@ -860,7 +921,8 @@ export function registerRunCommand(program) {
                             console.error(chalk.yellow('Selection cancelled — provisioning a fresh box.'));
                         }
                     }
-                    // Headless with no --reuse falls through here → provision fresh.
+                    // Headless with no --reuse falls through here → leaseAndRun's
+                    // profile-pool check decides (reuse a ready pool box, else warm fresh).
                 }
                 else if (options.reuse && warm.length > 0) {
                     // --reuse still honors a warm box even when the picker is suppressed.
@@ -979,12 +1041,16 @@ export function registerRunCommand(program) {
                         : `${runtime} credentials`;
             const boxLifecycle = reuseSlug
                 ? `Reusing crabbox box ${reuseSlug}`
-                : `Leasing a ${backend ?? 'hetzner'} box${netMode === 'tailscale' ? ' on your tailnet' : ''}`;
+                : options.fresh
+                    ? `Leasing a fresh ${backend ?? 'hetzner'} box${netMode === 'tailscale' ? ' on your tailnet' : ''}`
+                    : `Leasing a ${backend ?? 'hetzner'} box${netMode === 'tailscale' ? ' on your tailnet' : ''} (a ready box from the '${poolProfile ?? 'default'}' pool is reused when one exists)`;
             const boxAfterRun = reuseSlug
                 ? 'the box is kept after the run'
                 : options.keepBox
                     ? 'the box is kept after the run'
-                    : 'the box is destroyed after the run';
+                    : options.fresh
+                        ? 'the box is destroyed after the run'
+                        : 'a fresh box is destroyed after the run; a reused pool box is kept';
             console.error(chalk.gray(`${boxLifecycle} · shipping ${whatShips}${credentialRuntimes.length > 0 && leaseEmail ? ` (${leaseEmail})` : ''}; ${boxAfterRun}.`));
             // 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
@@ -1064,6 +1130,8 @@ export function registerRunCommand(program) {
                     secretsBundle: leaseSecretsBundle,
                     keep: options.keepBox,
                     reuseBox: reuseSlug,
+                    fresh: options.fresh,
+                    profile: poolProfile,
                     copySetup,
                     netMode,
                     onData: (chunk) => router.push(chunk),
@@ -1615,7 +1683,7 @@ export function registerRunCommand(program) {
         const cwd = options.cwd ?? process.cwd();
         if (accountPickerRequested && !isValidAgent(rawAgent)) {
             if (profileExists(rawAgent)) {
-                console.error(chalk.red(`Account selection is not available for profile '${rawAgent}'. Run its concrete host agent with @ instead.`));
+                console.error(chalk.red(`Account selection is not available for custom harness '${rawAgent}'. Run its concrete host agent with @ instead.`));
                 process.exit(1);
             }
             if (resolveWorkflowRef(rawAgent, cwd)) {
@@ -1675,7 +1743,7 @@ export function registerRunCommand(program) {
                 profileEnv = resolved.env;
                 profileFallbackModel = resolved.fallbackModel;
                 fromProfile = true;
-                process.stderr.write(chalk.gray(`Resolved profile '${resolved.profileName}' -> ${agent}${version ? `@${version}` : ''}\n`));
+                process.stderr.write(chalk.gray(`Resolved custom harness '${resolved.profileName}' -> ${agent}${version ? `@${version}` : ''}\n`));
                 if (resolved.tierNote) {
                     process.stderr.write(chalk.gray(`[agents] ${resolved.tierNote}\n`));
                 }
@@ -1685,7 +1753,7 @@ export function registerRunCommand(program) {
                 // native, HOST-catalog tier block below. When the profile has no
                 // `models:` opt-in at all, resolvedModel stays undefined and
                 // options.model is left as the raw tier token on purpose — the
-                // "cost tiers don't apply to profile ..." discard guard further
+                // "cost tiers don't apply to custom harness ..." discard guard further
                 // down this function is the canonical fallback for that case, and
                 // this block must not race it with a second, differently-worded
                 // message.
@@ -1894,7 +1962,7 @@ export function registerRunCommand(program) {
             else {
                 console.error(chalk.red(`Unknown agent: ${rawAgent}`));
                 console.error(chalk.gray(`Available agents: ${ALL_AGENT_IDS.join(', ')}`));
-                console.error(chalk.gray(`Or add a profile: agents profiles add <name>`));
+                console.error(chalk.gray(`Or add a custom harness: agents harness add <name>`));
                 process.exit(1);
             }
         }
@@ -2062,7 +2130,7 @@ export function registerRunCommand(program) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }
             else if (fromProfile) {
-                process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: profile pins its own version/auth\n`));
+                process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: custom harness pins its own version/auth\n`));
             }
             else {
                 try {
@@ -2312,12 +2380,12 @@ export function registerRunCommand(program) {
                 ? (workflowModel ?? (options.fallback ? undefined : runDefaults.model))
                 : undefined);
         // Cost tiers (cheap|default|best|ultra) resolve against a harness's own model
-        // catalog. A profile's model comes from its endpoint, not the host harness, so a
-        // tier here would forward an incompatible host-harness model to a different API.
-        // Discard it loudly and let the profile's configured model stand.
+        // catalog. A custom harness's model comes from its endpoint, not the host
+        // harness, so a tier here would forward an incompatible host-harness model to a
+        // different API. Discard it loudly and let the custom harness's own model stand.
         if (fromProfile && model && isTierToken(model)) {
-            process.stderr.write(chalk.yellow(`[agents] --model ${model}: cost tiers don't apply to profile '${rawAgent}' ` +
-                `(its model comes from the endpoint) — ignoring the tier, using the profile's configured model\n`));
+            process.stderr.write(chalk.yellow(`[agents] --model ${model}: cost tiers don't apply to custom harness '${rawAgent}' ` +
+                `(its model comes from the endpoint) — ignoring the tier, using the custom harness's configured model\n`));
             model = undefined;
         }
         const execOptions = {

package/dist/commands/feed.js

@@ -222,7 +222,7 @@ export function sessionHintsFromActive(sessions) {
 export function registerFeedCommand(program) {
     const feed = program
         .command('feed')
-        .description('Open blocks (needs you) + agent status posts (feed post)')
+        .description('Operator inbox + agent status posts (aliases: inbox = needs-you; timeline = --filter updates)')
         .option('--json', 'Output as JSON (each block stamped with its outcome + ask class)')
         .option('--filter <view>', 'What to show: needs (default) · updates · all', 'needs')
         .option('--flat', 'List one block per agent instead of grouping by outcome')
@@ -572,6 +572,43 @@ docs/06-observability.md.
             renderOutcomeGroup(g, self);
         await renderTrailingActivity();
     });
+    // Observe-umbrella aliases (Phase 3): intentional second names, not deprecations.
+    // Re-parse into `feed` so flags/help stay single-sourced. See lib/observe-aliases.ts.
+    registerFeedObserveAliases(program);
+}
+/**
+ * `inbox` / `timeline` → feed. Loaded with the feed module so lazy COMMAND_LOADERS
+ * for those names also get the real `feed` command registered for re-parse.
+ */
+function registerFeedObserveAliases(program) {
+    const reparse = async (alias) => {
+        const { expandObserveAlias } = await import('../lib/observe-aliases.js');
+        const rest = process.argv.slice(3);
+        const expanded = expandObserveAlias(alias, rest);
+        if (!expanded) {
+            console.error(chalk.red(`Unknown observe alias: ${alias}`));
+            process.exit(1);
+        }
+        if (process.stderr.isTTY)
+            process.stderr.write(chalk.gray(`${expanded.note}\n`));
+        await program.parseAsync(['node', 'agents', ...expanded.argv]);
+    };
+    program
+        .command('inbox')
+        .description('Needs-you inbox (alias of `agents feed`). Open blocks waiting on you.')
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        await reparse('inbox');
+    });
+    program
+        .command('timeline')
+        .description('Agent progress stream (alias of `agents feed --filter updates`). What agents posted recently.')
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        await reparse('timeline');
+    });
 }
 /**
  * Mirror a written post to the configured sinks (`feed.broadcast` in

package/dist/commands/harness.d.ts

@@ -11,7 +11,8 @@
  * native harness registry. The `agents profiles` tree stays unchanged.
  */
 import type { Command } from 'commander';
-import { type Profile } from '../lib/profiles.js';
+import { type AddProfileOptions } from './profiles.js';
+import { type Profile, type ForkProfileOptions } from '../lib/profiles.js';
 /**
  * Print one custom harness. Shared by `agents harness view <name>` and by
  * `agents view <name>` — a custom harness resolves as an agent type there, so
@@ -24,11 +25,26 @@ export interface ForkOptions {
     baseUrl?: string;
     authProvider?: string;
     version?: string;
-    label?: string;
     description?: string;
+    /** `<bundle>` or `<bundle>:<key>` — see {@link applyFromSecrets} in ./profiles.js. */
+    fromSecrets?: string;
     keyStdin?: boolean;
     force?: boolean;
 }
+/** Options accepted by `agents harness edit`. */
+export interface EditOptions {
+    model?: string;
+    baseUrl?: string;
+    authProvider?: string;
+    /** Empty string ('') unpins the host CLI version. */
+    version?: string;
+    description?: string;
+    /** Empty string ('') clears the fallback model. */
+    fallbackModel?: string;
+    /** `<bundle>` or `<bundle>:<key>` — see {@link applyFromSecrets} in ./profiles.js. */
+    fromSecrets?: string;
+    keyStdin?: boolean;
+}
 /**
  * Build the new harness for `agents harness fork <source> <name>`.
  *
@@ -38,4 +54,26 @@ export interface ForkOptions {
  * copy a model from.
  */
 export declare function buildFork(source: string, name: string, opts: ForkOptions): Profile;
+/** Map `agents harness edit` flags onto {@link ForkProfileOptions} — the same
+ * override shape `editProfile`/`forkProfile` apply. `--version ''` (unpin) is
+ * handled by the caller ({@link buildEdit}), not here: `forkProfile`'s own
+ * ternary treats an empty string as "no override" and would otherwise inherit
+ * the source's version instead of clearing it. */
+export declare function buildEditOverrides(opts: EditOptions): ForkProfileOptions;
+/** True when at least one recognized edit flag was given. */
+export declare function hasEditFlags(opts: EditOptions): boolean;
+/**
+ * Build the edited harness for `agents harness edit <name>` — the profile-shape
+ * transform only; the caller applies `--from-secrets`/`--auth-provider` (async
+ * keychain side effects) and persists with `writeProfile`. Mirrors
+ * {@link buildFork}'s split between a pure builder and the action's IO.
+ */
+export declare function buildEdit(name: string, opts: EditOptions): Profile;
+/** True when `agents harness fork` was given too little to proceed without the wizard. */
+export declare function forkNeedsWizard(source: string | undefined, name: string | undefined, opts: ForkOptions): boolean;
+/** True when `agents harness add` was given too little to proceed without the wizard.
+ * Mirrors {@link addProfile}'s own error condition in ./profiles.js so a bare
+ * `agents harness add <preset-name>` (no flags) still resolves via the preset
+ * fallback instead of being routed into the wizard. */
+export declare function addNeedsWizard(name: string | undefined, opts: AddProfileOptions): boolean;
 export declare function registerHarnessCommands(program: Command): void;