@phnx-labs/agents-cli 1.22.7 → 1.22.8

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 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

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,13 +553,14 @@ 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]', 'Invent a disposable cloud box for this run and tear it down after (via crabbox). 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('--reuse', 'With --lease, reuse the most-recently-used warm box if one exists (else provision fresh). The scriptable form of the interactive reuse picker.')
@@ -601,6 +602,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
@@ -688,6 +694,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
@@ -1615,7 +1651,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 +1711,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 +1721,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 +1930,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 +2098,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 +2348,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/harness.d.ts

@@ -24,7 +24,6 @@ export interface ForkOptions {
     baseUrl?: string;
     authProvider?: string;
     version?: string;
-    label?: string;
     description?: string;
     keyStdin?: boolean;
     force?: boolean;

package/dist/commands/harness.js

@@ -12,7 +12,7 @@
  */
 import chalk from 'chalk';
 import { addProfile, ensureProviderToken } from './profiles.js';
-import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, editProfile, renameProfile, } from '../lib/profiles.js';
 import { listPresets } from '../lib/profiles-presets.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName } from '../lib/agents.js';
 /** Short capability summary for a native harness — its supported run modes. */
@@ -58,7 +58,6 @@ export function buildFork(source, name, opts) {
             baseUrl: opts.baseUrl,
             provider: opts.authProvider,
             version: opts.version,
-            label: opts.label,
             description: opts.description,
         });
     }
@@ -75,7 +74,6 @@ export function buildFork(source, name, opts) {
         baseUrl: opts.baseUrl,
         provider: opts.authProvider,
         authEnvVar: opts.authProvider ? authEnvKeyForHostOrThrow(host) : undefined,
-        label: opts.label,
         description: opts.description ?? `Forked from ${host}: ${opts.model}`,
     });
 }
@@ -147,7 +145,6 @@ Examples:
         .option('--base-url <url>', 'Custom endpoint base URL (claude/codex hosts)')
         .option('--auth-provider <provider>', 'Attach a keychain-backed API key under this provider')
         .option('--version <version>', 'Pin the host CLI version (e.g., 1.16.0)')
-        .option('--label <text>', 'Human-facing name shown by `agents view` (defaults to <name>)')
         .option('--description <text>', 'One-line description')
         .option('--key-stdin', 'Read the API key from stdin instead of prompting (for scripts/CI)')
         .option('--force', 'Overwrite an existing harness with the same name')
@@ -249,4 +246,63 @@ Examples:
         }
         console.log(chalk.green(`Harness '${name}' removed.`));
     });
+    cmd
+        .command('edit <name>')
+        .description('Edit a custom harness in place (model, endpoint, host version, description).')
+        // Flags mirror ForkProfileOptions exactly — `editProfile` reuses
+        // `forkProfile`'s override logic, so anything it does not accept would be a
+        // flag that parses and does nothing. There is deliberately no --label: the
+        // header `agents view` prints is derived from the harness name.
+        .option('--model <id>', 'Swap the pinned model (e.g., meta/muse-spark-2.0)')
+        .option('--base-url <url>', 'Set or replace the endpoint base URL (claude/codex hosts)')
+        .option('--version <ver>', 'Re-pin the host CLI version. Empty string unpins (tracks latest).')
+        .option('--description <text>', 'Set the one-line description')
+        .addHelpText('after', `
+Examples:
+  # Upgrade the pinned model
+  agents harness edit spark --model meta/muse-spark-2.0
+
+  # Point to a new private endpoint
+  agents harness edit corp --base-url https://gw.corp/v2
+
+  # Track the host's latest instead of a pinned version
+  agents harness edit spark --version ""
+
+  # The display name is derived from the harness name, so to change it, rename:
+  agents harness rename spark muse-spark
+`)
+        .action((name, opts) => {
+        try {
+            const edited = editProfile(readProfile(name), opts);
+            writeProfile(edited);
+            console.log(chalk.green(`Harness '${name}' updated.`));
+            console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('rename <name> <new-name>')
+        .description('Rename a custom harness — updates the file name and its internal name field.')
+        .addHelpText('after', `
+Examples:
+  # Rename 'spark' to 'muse'
+  agents harness rename spark muse
+
+  # Rename then run under the new name
+  agents harness rename deepseek ds && agents run ds "hello"
+`)
+        .action((name, newName) => {
+        try {
+            renameProfile(name, newName);
+            console.log(chalk.green(`Harness '${name}' renamed to '${newName}'.`));
+            console.log(chalk.gray(`Run: agents run ${newName} "hello"`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
 }

package/dist/commands/monitors.js

@@ -315,9 +315,9 @@ export function registerMonitorsCommands(program) {
         .option('--notify [channel]', 'Notify the owner (notify.owner); [channel] overrides the owner channel')
         .option('--webhook-out <url>', 'POST the event to this URL')
         // PLACEMENT / hygiene
-        .option('--device <name>', 'OWNER device — the single machine that evaluates + fires (exactly-once)')
+        .option('--device <name>', 'OWNER (not body placement) — the single machine that evaluates + fires (exactly-once). See docs/00-concepts.md#placement.')
         .option('--devices <list>', 'Allowlist (comma-separated): each device fires independently')
-        .option('--run-on <host>', 'Execute the ACTION on this machine over SSH (placement)')
+        .option('--run-on <host>', 'BODY placement — execute the ACTION on this machine over SSH (same idea as run --where device:<host>)')
         .option('--rate-limit <spec>', 'Auto-pause if it fires more than N/<interval> (e.g. 5/1m)')
         .option('--disabled', 'Create the monitor paused (enable later with resume)')
         .action(async (nameOrPath, options) => {

package/dist/commands/routines.js

@@ -628,8 +628,8 @@ export function registerRoutinesCommands(program) {
         .option('-t, --timeout <timeout>', 'Kill the agent if it runs longer than this (e.g., 10m, 2h, 3d, 1w; max 1w)', '10m')
         .option('--timezone <tz>', 'Interpret schedule in this timezone (e.g., America/Los_Angeles)')
         .option('--devices <names>', 'Fleet allowlist (comma-separated): only listed devices schedule and fire this routine. Omit for unrestricted.')
-        .option('--run-on <name>', 'Execute the job body on this machine over SSH (a registered host, device, capability tag, or user@host). Sets hostStrategy=host. Placement, not eligibility — see --devices. Auto-pins devices to THIS machine unless --devices is given.')
-        .option('--placement <strategy>', `Where the job body runs: ${HOST_STRATEGIES.join('|')} (default: local, or host when --run-on is set). Not the same as --host (which manages routines on a remote machine).`)
+        .option('--run-on <name>', 'BODY placement: execute the job body on this machine over SSH (registered host, device, capability tag, or user@host). Sets hostStrategy=host. Not eligibility — see --devices. Auto-pins devices to THIS machine unless --devices is given. Same model as agents run --where device:<name> (docs/00-concepts.md#placement).')
+        .option('--placement <strategy>', `BODY placement strategy: ${HOST_STRATEGIES.join('|')} (default: local, or host when --run-on is set). Maps to the shared Placement model (local|device|fleet|cloud). Not the same as --host (which manages routines on a remote machine).`)
         .option('--run-cwd <dir>', 'Working directory on the --run-on host (--remote-cwd is taken by the remote-management passthrough)')
         .option('--at <time>', 'One-shot mode: run once at this time (e.g., "14:30" or "2026-02-24 09:00"), then disable')
         .option('--on <source:event>', 'Webhook trigger instead of/in addition to a schedule: github:pull_request or linear:Issue')

package/dist/commands/run-account-picker.js

@@ -36,6 +36,8 @@ function disabledReason(candidate) {
         return undefined;
     if (readiness.reason === 'signed_out')
         return 'logged out';
+    if (readiness.reason === 'revoked')
+        return 'needs re-login';
     if (readiness.reason === 'out_of_credits')
         return 'out of credits';
     const windows = candidate.usageSnapshot?.windows ?? [];

package/dist/commands/snapshot.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `agents snapshot` — one-process consumer snapshot for pollers.
+ *
+ * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
+ * fork storm with a single command. Does NOT replace `agents status`, which
+ * remains the UnifiedSyncStatus sync contract for menubar / Agency drift.
+ *
+ * JSON shape: {@link FleetSnapshot} in `lib/snapshot.ts` (version: 1).
+ */
+import type { Command } from 'commander';
+export declare function registerSnapshotCommand(program: Command): void;

package/dist/commands/snapshot.js

@@ -0,0 +1,107 @@
+/**
+ * `agents snapshot` — one-process consumer snapshot for pollers.
+ *
+ * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
+ * fork storm with a single command. Does NOT replace `agents status`, which
+ * remains the UnifiedSyncStatus sync contract for menubar / Agency drift.
+ *
+ * JSON shape: {@link FleetSnapshot} in `lib/snapshot.ts` (version: 1).
+ */
+import chalk from 'chalk';
+import { addHostOption } from '../lib/hosts/option.js';
+import { setHelpSections } from '../lib/help.js';
+import { resolveAgentName, AGENTS } from '../lib/agents.js';
+import { computeSnapshot } from '../lib/snapshot.js';
+import { resolveSurface } from './utils.js';
+function resolveAgentFilter(raw) {
+    if (!raw)
+        return undefined;
+    const name = resolveAgentName(raw.split('@')[0]);
+    if (!name) {
+        console.error(chalk.red(`Unknown agent "${raw}".`));
+        process.exit(1);
+    }
+    return name;
+}
+/** Compact human summary — the JSON path is the real contract. */
+function renderHuman(snap) {
+    console.log(chalk.bold('Fleet snapshot') + chalk.gray(`  ·  ${snap.host}  ·  ${snap.capturedAt}`));
+    const invParts = [];
+    for (const a of snap.inventory) {
+        if (a.versions.length === 0)
+            continue;
+        const def = a.versions.find((v) => v.isDefault) ?? a.versions[0];
+        const label = AGENTS[a.agent]?.name ?? a.agent;
+        const signed = def.signedIn ? chalk.green('in') : chalk.gray('out');
+        invParts.push(`${label}@${def.version} (${signed})`);
+    }
+    console.log(`  ${'Inventory'.padEnd(12)} ${invParts.length ? invParts.join(chalk.gray(' · ')) : chalk.gray('(none installed)')}`);
+    const { running, live, byContext, byAgent } = snap.agents;
+    const ctx = Object.entries(byContext)
+        .map(([k, n]) => `${k}:${n}`)
+        .join(' ');
+    const ag = Object.entries(byAgent)
+        .map(([k, n]) => `${k}:${n}`)
+        .join(' ');
+    console.log(`  ${'Sessions'.padEnd(12)} ${live} live · ${running} running` +
+        (snap.remoteDeviceCount > 0 ? chalk.gray(` · ${snap.remoteDeviceCount} remote device(s)`) : '') +
+        (ctx ? chalk.gray(` · ${ctx}`) : '') +
+        (ag ? chalk.gray(` · ${ag}`) : ''));
+    if (snap.feed) {
+        console.log(`  ${'Feed'.padEnd(12)} ${snap.feed.openBlocks} open block${snap.feed.openBlocks === 1 ? '' : 's'}`);
+    }
+    if (snap.sync) {
+        const need = snap.sync.agents.filter((a) => a.needsSync).length;
+        const sys = snap.sync.system.unknown
+            ? 'system unknown'
+            : snap.sync.system.behind > 0
+                ? `system ${snap.sync.system.behind} behind`
+                : 'system ok';
+        console.log(`  ${'Sync'.padEnd(12)} ${sys} · ${need} version${need === 1 ? '' : 's'} need sync`);
+    }
+    console.log(chalk.gray('\n  Machine-readable: agents snapshot --json\n' +
+        '  Sync-only (unchanged): agents status --json'));
+}
+export function registerSnapshotCommand(program) {
+    const cmd = addHostOption(program
+        .command('snapshot')
+        .description('One-process poll snapshot: install inventory + active sessions (optional feed/sync). Not the sync-status command — use `agents status` for drift.'))
+        .option('--json', 'Emit the machine-readable FleetSnapshot contract (version 1)')
+        .option('--all-hosts', 'Include remote devices in the sessions gather (same fan-out as `sessions --active`; default is this machine only)')
+        .option('--with-feed', 'Include open feed-block summary (needs-you count + compact rows)')
+        .option('--with-sync', 'Include UnifiedSyncStatus (same engine as `agents status`; opt-in)')
+        .option('--agent <name>', 'Restrict inventory to one agent (e.g. claude)');
+    setHelpSections(cmd, {
+        examples: `
+      # One-shot inventory + local active sessions (JSON)
+      agents snapshot --json
+
+      # Same, plus open feed blocks for needs-you polls
+      agents snapshot --json --with-feed
+
+      # Fleet-wide active sessions (matches sessions --active scope)
+      agents snapshot --json --all-hosts
+
+      # Inventory for one harness only (Factory-style usage poll)
+      agents snapshot --json --agent claude
+
+      # Run the whole snapshot on another device
+      agents snapshot --json --host yosemite-s0
+    `,
+    });
+    cmd.action(async (opts, command) => {
+        const surface = resolveSurface(command);
+        const agent = resolveAgentFilter(opts.agent);
+        const snap = await computeSnapshot({
+            agent,
+            local: opts.allHosts !== true,
+            withFeed: opts.withFeed === true,
+            withSync: opts.withSync === true,
+        });
+        if (surface.json || opts.json) {
+            console.log(JSON.stringify(snap, null, 2));
+            return;
+        }
+        renderHuman(snap);
+    });
+}

package/dist/commands/teams.js

@@ -275,7 +275,8 @@ function throttleWarningLine(agent, version, r) {
     const acct = r.email ? ` (${r.email})` : '';
     const reason = r.reason === 'out_of_credits' ? 'is out of credits'
         : r.reason === 'signed_out' ? 'is not signed in'
-            : 'is rate-limited right now';
+            : r.reason === 'revoked' ? 'needs re-login (its token was revoked)'
+                : 'is rate-limited right now';
     return (chalk.yellow(`⚠ ${who}${acct} ${reason}.`) +
         chalk.gray(`\n  A pinned version skips account rotation, so it will launch on this account and may immediately hit its limit.` +
             `\n  Use a bare \`${agent}\` teammate to let the team pick a healthy account, or pass --force to silence this.`));

package/dist/commands/view.d.ts

@@ -129,6 +129,13 @@ export declare function parseResourceSections(options: {
     resources?: string | boolean;
     detailed?: boolean;
 } & ViewSectionFilter, jsonMode: boolean): Set<ResourceSection>;
+/**
+ * Collect structured info for one or more agents without rendering to the
+ * terminal. Used by `--json` output and any programmatic consumer (e.g. the
+ * agents-cli extension's "resume current session in best available version"
+ * command).
+ */
+export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSections?: Set<ResourceSection>): Promise<ViewJsonAgent[]>;
 /**
  * Identity key for duplicate-install detection. Prefers accountKey — which
  * encodes account AND org — over the bare email: two installs can share an

package/dist/commands/view.js

@@ -1242,7 +1242,7 @@ export function parseResourceSections(options, jsonMode) {
  * agents-cli extension's "resume current session in best available version"
  * command).
  */
-async function collectAgentsJson(filterAgentId, resourceSections) {
+export async function collectAgentsJson(filterAgentId, resourceSections) {
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
     const wantResources = !!resourceSections && resourceSections.size > 0;
     // Only pay for the git-status + resource scans when resources were requested.

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -317,6 +317,8 @@ Credentials and profiles:
 
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence; --check for the CI drift gate
+  status                          Unified sync status (drift/missing) — not the live fleet snapshot
+  snapshot                        One-process poll: inventory + active sessions (+ optional feed/sync)
   usage [agent]                   Show rate-limit and quota usage per agent
   perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 
@@ -938,6 +940,7 @@ async function registerAllEagerCommands() {
     registerCheckTombstoneCommand(program);
     await reg(loadApply);
     await reg(loadStatus);
+    await reg(loadSnapshot);
     registerExecAliasCommand(program);
     await reg(loadProfiles);
     await reg(loadHarness);

package/dist/lib/browser/ipc.js

@@ -178,6 +178,8 @@ export class BrowserIPCServer {
                     url: request.url,
                     endpointName: request.endpoint,
                     skipDomainSkill: request.skipDomainSkill,
+                    actor: request.actor,
+                    launchId: request.launchId,
                 });
                 return {
                     ok: true,