@phnx-labs/agents-cli 1.22.7 → 1.22.9

package/dist/lib/browser/types.d.ts

@@ -79,10 +79,20 @@ export interface Task {
     createdAt: number;
     pid: number;
     /**
-     * Resolved actor id (`resolveActor().id`) stamped at task start — who launched
-     * this browser task. Optional: tasks persisted before RUSH-2020 carry none.
+     * Resolved actor id (`resolveActor().id`) stamped at task start — WHO launched
+     * this browser task (a person/agent identity, stable across runs). Forwarded
+     * from the caller over IPC — the daemon is shared, so it cannot resolve the
+     * caller's actor itself. Optional: tasks persisted before RUSH-2020 carry none.
      */
     owner?: string;
+    /**
+     * The caller's per-run launch id (`$AGENT_LAUNCH_ID`, minted by exec.ts for
+     * every harness) stamped at task start — WHICH run created this task. Distinct
+     * from `owner`: two runs by the same actor get different launchIds, which is
+     * the scope the current-task default and `status --mine` filter on. Forwarded
+     * from the caller over IPC. Optional: tasks from before this shipped carry none.
+     */
+    launchId?: string;
     /**
      * Per-tab snapshot of the last ref listing captured for that tab
      * (shortId -> {descriptors, opts}). Persisted to tasks.json so a later
@@ -184,6 +194,8 @@ export interface IPCRequest {
     until?: string;
     appLevel?: string;
     skipDomainSkill?: boolean;
+    actor?: string;
+    launchId?: string;
 }
 /** Subset of IPCResponse describing a recording start result. */
 export interface RecordStartFields {

package/dist/lib/crabbox/cli.d.ts

@@ -114,6 +114,41 @@ export declare function crabboxEnv(opts: CrabboxOptions): NodeJS.ProcessEnv;
 export declare function crabboxList(opts?: CrabboxOptions): CrabboxBox[];
 /** Find one box by slug, or null. */
 export declare function crabboxFind(slug: string, opts?: CrabboxOptions): CrabboxBox | null;
+/**
+ * Whether `crabbox status` reports the box SSH-ready (`ready=true`). A box whose
+ * cloud-init bootstrap failed still LISTS as `running` but never becomes ready —
+ * selecting it burns the full SSH wait before hard-failing. `crabbox status`
+ * flips ready=true only once sshd answers, so warm-pool reuse gates on it
+ * (mirrors scripts/sandbox.sh's `box_ready`).
+ */
+export declare function crabboxStatusReady(slug: string, opts?: CrabboxOptions): boolean;
+export interface PoolMatchOptions {
+    /**
+     * Profile label this run would warm a box with (from the repo's
+     * `.crabbox.yaml`; see config.ts). Both sides normalize an unset profile to
+     * DEFAULT_CRABBOX_PROFILE, so profile-less runs match unlabeled boxes.
+     */
+    profile?: string;
+    /**
+     * Network mode of the run (default 'public'). A tailnet-joined box is never
+     * handed to a public run, nor a public box to a tailnet run — reachability and
+     * exposure differ, so the pool is partitioned by it.
+     */
+    netMode?: 'public' | 'tailscale';
+    /** Injectable clock (unix seconds) for the expiry check. */
+    nowSecs?: number;
+}
+/**
+ * Warm boxes in the profile pool this run could reuse: `running`, same profile
+ * label, same network mode, lease unexpired — most-recently-touched first.
+ *
+ * Readiness is NOT required here (deliberately mirrors sandbox.sh's
+ * `running_slugs_for_profile`, which filters on `status` only): the list `state`
+ * label can lag, so the caller gates each candidate on `crabboxStatusReady`
+ * before committing. A not-ready box is skipped, never stopped — a concurrent
+ * run may be mid-boot on it, and crabbox's idle timeout reaps genuine duds.
+ */
+export declare function poolReusableBoxes(boxes: CrabboxBox[], opts?: PoolMatchOptions): CrabboxBox[];
 export interface WarmupOptions extends CrabboxOptions {
     class?: string;
     profile?: string;

package/dist/lib/crabbox/cli.js

@@ -14,6 +14,7 @@
 import { spawn, spawnSync } from 'child_process';
 import { readAndResolveBundleEnv, listBundles, bundleExists } from '../secrets/bundles.js';
 import { readMeta, writeMeta } from '../state.js';
+import { DEFAULT_CRABBOX_PROFILE } from './config.js';
 /** Locate the crabbox binary, or throw an actionable error. */
 export function findCrabbox() {
     const r = spawnSync('crabbox', ['--help'], { encoding: 'utf-8' });
@@ -301,6 +302,51 @@ export function crabboxList(opts = {}) {
 export function crabboxFind(slug, opts = {}) {
     return crabboxList(opts).find((b) => b.slug === slug) ?? null;
 }
+/**
+ * Whether `crabbox status` reports the box SSH-ready (`ready=true`). A box whose
+ * cloud-init bootstrap failed still LISTS as `running` but never becomes ready —
+ * selecting it burns the full SSH wait before hard-failing. `crabbox status`
+ * flips ready=true only once sshd answers, so warm-pool reuse gates on it
+ * (mirrors scripts/sandbox.sh's `box_ready`).
+ */
+export function crabboxStatusReady(slug, opts = {}) {
+    findCrabbox();
+    const r = spawnSync('crabbox', ['status', '--id', slug], {
+        encoding: 'utf-8',
+        env: crabboxEnv(opts),
+        timeout: opts.timeoutMs ?? 15000,
+    });
+    if (r.status !== 0 || !r.stdout)
+        return false;
+    return /(^|\s)ready=true(\s|$)/m.test(r.stdout);
+}
+/**
+ * Warm boxes in the profile pool this run could reuse: `running`, same profile
+ * label, same network mode, lease unexpired — most-recently-touched first.
+ *
+ * Readiness is NOT required here (deliberately mirrors sandbox.sh's
+ * `running_slugs_for_profile`, which filters on `status` only): the list `state`
+ * label can lag, so the caller gates each candidate on `crabboxStatusReady`
+ * before committing. A not-ready box is skipped, never stopped — a concurrent
+ * run may be mid-boot on it, and crabbox's idle timeout reaps genuine duds.
+ */
+export function poolReusableBoxes(boxes, opts = {}) {
+    const profile = opts.profile ?? DEFAULT_CRABBOX_PROFILE;
+    const netMode = opts.netMode ?? 'public';
+    const nowSecs = opts.nowSecs ?? Math.floor(Date.now() / 1000);
+    return boxes
+        .filter((b) => {
+        if (b.status !== 'running')
+            return false;
+        if ((b.profile ?? DEFAULT_CRABBOX_PROFILE) !== profile)
+            return false;
+        const boxNet = b.tailscaleIPv4 || b.tailscaleFQDN ? 'tailscale' : 'public';
+        if (boxNet !== netMode)
+            return false;
+        return b.expiresAt === null || b.expiresAt > nowSecs;
+    })
+        .sort((a, b) => (b.lastTouchedAt ?? 0) - (a.lastTouchedAt ?? 0));
+}
 /**
  * Lease a box and block until it is ready. Returns the leased box.
  *

package/dist/lib/crabbox/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The repo-local crabbox config (`.crabbox.yaml` at the repo root).
+ *
+ * crabbox itself reads this file when warming a box (the `profile:` key becomes
+ * the box's `profile` label). `agents run --lease` reads it too so the warm-pool
+ * reuse check matches on the SAME profile the warmup would have used — a reused
+ * box is then interchangeable with a fresh one (scripts/sandbox.sh's
+ * `pick_ready_box` resolves the pool the same way).
+ */
+/**
+ * The profile label a box warm pool shares. Matches sandbox.sh's
+ * `PROFILE="${PROFILE:-default}"`: a run with no configured profile and a box
+ * with no `profile` label both normalize here, so they still match each other.
+ */
+export declare const DEFAULT_CRABBOX_PROFILE = "default";
+/**
+ * The `profile:` declared by `<repoRoot>/.crabbox.yaml`, or undefined when the
+ * file is missing, unreadable, or has no profile key (crabbox then applies its
+ * own default, which the pool matcher treats as DEFAULT_CRABBOX_PROFILE).
+ */
+export declare function readCrabboxRepoProfile(repoRoot: string): string | undefined;

package/dist/lib/crabbox/config.js

@@ -0,0 +1,43 @@
+/**
+ * The repo-local crabbox config (`.crabbox.yaml` at the repo root).
+ *
+ * crabbox itself reads this file when warming a box (the `profile:` key becomes
+ * the box's `profile` label). `agents run --lease` reads it too so the warm-pool
+ * reuse check matches on the SAME profile the warmup would have used — a reused
+ * box is then interchangeable with a fresh one (scripts/sandbox.sh's
+ * `pick_ready_box` resolves the pool the same way).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+/**
+ * The profile label a box warm pool shares. Matches sandbox.sh's
+ * `PROFILE="${PROFILE:-default}"`: a run with no configured profile and a box
+ * with no `profile` label both normalize here, so they still match each other.
+ */
+export const DEFAULT_CRABBOX_PROFILE = 'default';
+/**
+ * The `profile:` declared by `<repoRoot>/.crabbox.yaml`, or undefined when the
+ * file is missing, unreadable, or has no profile key (crabbox then applies its
+ * own default, which the pool matcher treats as DEFAULT_CRABBOX_PROFILE).
+ */
+export function readCrabboxRepoProfile(repoRoot) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(repoRoot, '.crabbox.yaml'), 'utf-8');
+    }
+    catch {
+        return undefined; // no repo crabbox config — crabbox's own default applies
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const profile = parsed.profile;
+    return typeof profile === 'string' && profile.length > 0 ? profile : undefined;
+}

package/dist/lib/crabbox/lease.d.ts

@@ -1,10 +1,12 @@
 /**
  * `agents run --lease` orchestrator.
  *
- * Lease an ephemeral crabbox → provision the picked runtime(s) + their
- * credentials → run the agent on the box (via `crabbox run`, which owns the
- * SSH) → tear the box down. The whole box-side sequence rides a single
- * `--script-stdin` body so the token contents never touch argv.
+ * Acquire a box → provision the picked runtime(s) + their credentials → run the
+ * agent on the box (via `crabbox run`, which owns the SSH) → tear the box down.
+ * Acquisition is reuse-first against the warm profile pool (a ready box carrying
+ * the run's profile + netMode labels is reused and kept; `--fresh` opts out and
+ * always leases a new, torn-down box). The whole box-side sequence rides a
+ * single `--script-stdin` body so the token contents never touch argv.
  *
  * ── Command-layer contract (RUSH-1920/1921/1924) ─────────────────────────────
  * Exports the commands layer (exec.ts / lease.ts / ssh.ts) consumes:
@@ -12,7 +14,9 @@
  *     --bare) gates the `copy-setup` progress sentinel; `opts.netMode`
  *     ('public' | 'tailscale', default 'public') adds the `joined-tailnet` step.
  *   • `LeaseRunOptions.copySetup` / `LeaseRunOptions.netMode` — forwarded by
- *     `leaseAndRun` (netMode → `crabboxWarmup`).
+ *     `leaseAndRun` (netMode → `crabboxWarmup`). `LeaseRunOptions.fresh`
+ *     (`--fresh`) skips the warm profile-pool reuse check and always leases a
+ *     new box, torn down after the run.
  *   • `crabboxWarmup(opts.netMode)` — 'tailscale' leases onto the tailnet
  *     (`--network tailscale -tailscale-tags tag:crabbox`); auth key rides the
  *     child env as `CRABBOX_TAILSCALE_AUTH_KEY` (crabboxEnv, cli.ts).
@@ -80,6 +84,12 @@ export interface LeaseRunOptions {
     keep?: boolean;
     /** Existing warm crabbox slug to reuse instead of provisioning a new lease. */
     reuseBox?: string;
+    /**
+     * Force a brand-new box: skip the warm profile-pool reuse check and tear the
+     * box down after the run (the pre-pool `--lease` behavior). `--fresh` at the
+     * command layer.
+     */
+    fresh?: boolean;
     /**
      * Raw wrapped Claude OAuth payload (from `resolveClaudeCredentialsBlob`), written
      * to `~/.claude/.credentials.json` on the box. The command layer resolves it

package/dist/lib/crabbox/lease.js

@@ -1,10 +1,12 @@
 /**
  * `agents run --lease` orchestrator.
  *
- * Lease an ephemeral crabbox → provision the picked runtime(s) + their
- * credentials → run the agent on the box (via `crabbox run`, which owns the
- * SSH) → tear the box down. The whole box-side sequence rides a single
- * `--script-stdin` body so the token contents never touch argv.
+ * Acquire a box → provision the picked runtime(s) + their credentials → run the
+ * agent on the box (via `crabbox run`, which owns the SSH) → tear the box down.
+ * Acquisition is reuse-first against the warm profile pool (a ready box carrying
+ * the run's profile + netMode labels is reused and kept; `--fresh` opts out and
+ * always leases a new, torn-down box). The whole box-side sequence rides a
+ * single `--script-stdin` body so the token contents never touch argv.
  *
  * ── Command-layer contract (RUSH-1920/1921/1924) ─────────────────────────────
  * Exports the commands layer (exec.ts / lease.ts / ssh.ts) consumes:
@@ -12,7 +14,9 @@
  *     --bare) gates the `copy-setup` progress sentinel; `opts.netMode`
  *     ('public' | 'tailscale', default 'public') adds the `joined-tailnet` step.
  *   • `LeaseRunOptions.copySetup` / `LeaseRunOptions.netMode` — forwarded by
- *     `leaseAndRun` (netMode → `crabboxWarmup`).
+ *     `leaseAndRun` (netMode → `crabboxWarmup`). `LeaseRunOptions.fresh`
+ *     (`--fresh`) skips the warm profile-pool reuse check and always leases a
+ *     new box, torn down after the run.
  *   • `crabboxWarmup(opts.netMode)` — 'tailscale' leases onto the tailnet
  *     (`--network tailscale -tailscale-tags tag:crabbox`); auth key rides the
  *     child env as `CRABBOX_TAILSCALE_AUTH_KEY` (crabboxEnv, cli.ts).
@@ -24,7 +28,7 @@
  *     secretsBundle?, userAgentsDir?, onData? }): Promise<CopySetupResult>` — the
  *     push-from-local the command layer runs before the box run.
  */
-import { crabboxFind, crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop } from './cli.js';
+import { crabboxFind, crabboxList, crabboxStatusReady, crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop, poolReusableBoxes } from './cli.js';
 import * as yaml from 'yaml';
 import { buildCredentialScript, buildHomeFileWriteScript, CLAUDE_TOKEN_REMOTE } from './runtimes.js';
 import { LEASE_AGENT_MARKER, leasePhaseSentinel } from './progress.js';
@@ -149,9 +153,32 @@ export function buildBootstrapScript(opts) {
         .filter((l) => l.length > 0)
         .join('\n');
 }
+/**
+ * The first warm box in this run's profile pool that is actually SSH-ready, or
+ * null. Mirrors scripts/sandbox.sh's `pick_ready_box`: list the running boxes
+ * for the run's profile + netMode, then gate each on `crabbox status`
+ * ready=true — a box whose bootstrap failed still lists as `running` and would
+ * burn the whole SSH wait before hard-failing. A skipped box is left alone
+ * (never stopped): a concurrent run may be mid-boot on it, and crabbox's idle
+ * timeout reaps genuine duds.
+ */
+function pickReadyPoolBox(opts) {
+    const candidates = poolReusableBoxes(crabboxList({ secretsBundle: opts.secretsBundle }), {
+        profile: opts.profile,
+        netMode: opts.netMode,
+    });
+    for (const b of candidates) {
+        if (crabboxStatusReady(b.slug, { secretsBundle: opts.secretsBundle }))
+            return b;
+    }
+    return null;
+}
 export async function leaseAndRun(opts) {
     const startedAt = Date.now();
     let box;
+    // A box this run did NOT provision — either the caller named it (`--box`) or
+    // it came out of the warm profile pool. Reused boxes are never torn down.
+    let reused = false;
     if (opts.reuseBox) {
         opts.onPhase?.({ kind: 'reuse', slug: opts.reuseBox });
         const found = crabboxFind(opts.reuseBox, { secretsBundle: opts.secretsBundle });
@@ -160,17 +187,29 @@ export async function leaseAndRun(opts) {
         box = found.ready
             ? found
             : await crabboxWaitReady(opts.reuseBox, { secretsBundle: opts.secretsBundle });
+        reused = true;
     }
     else {
-        opts.onPhase?.({ kind: 'warmup', backend: opts.backend });
-        box = await crabboxWarmup({
-            class: opts.boxClass,
-            profile: opts.profile,
-            provider: opts.backend,
-            secretsBundle: opts.secretsBundle,
-            netMode: opts.netMode,
-        });
-        await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+        // Reuse-first: before paying for a fresh lease, look for a warm box in this
+        // run's profile pool (same profile label the warmup would use, same netMode).
+        // `--fresh` opts out and always provisions.
+        const pooled = opts.fresh ? null : pickReadyPoolBox(opts);
+        if (pooled) {
+            opts.onPhase?.({ kind: 'reuse', slug: pooled.slug });
+            box = pooled;
+            reused = true;
+        }
+        else {
+            opts.onPhase?.({ kind: 'warmup', backend: opts.backend });
+            box = await crabboxWarmup({
+                class: opts.boxClass,
+                profile: opts.profile,
+                provider: opts.backend,
+                secretsBundle: opts.secretsBundle,
+                netMode: opts.netMode,
+            });
+            await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+        }
     }
     opts.onPhase?.({ kind: 'ready', box, elapsedMs: Date.now() - startedAt });
     // Setup-copy (F1, RUSH-1920): push the git-tracked ~/.agents config onto the
@@ -203,8 +242,9 @@ export async function leaseAndRun(opts) {
     }
     finally {
         // Always attempt teardown (bounds credential lifetime to the run) unless the
-        // caller explicitly asked to keep the box or targeted an existing warm box.
-        if (!opts.keep && !opts.reuseBox) {
+        // caller explicitly asked to keep the box or the box was reused (an explicit
+        // --box target or a warm pool box — both outlive this run).
+        if (!opts.keep && !reused) {
             opts.onPhase?.({ kind: 'teardown' });
             toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
         }

package/dist/lib/daemon.js

@@ -888,14 +888,14 @@ export async function runDaemon() {
     };
     const fleetCacheInterval = setInterval(() => { void runFleetCacheWarm(); }, 3 * 60_000);
     const fleetCacheKickoff = setTimeout(() => { void runFleetCacheWarm(); }, 60_000);
-    // Adaptive usage refresh: keep the usage cache the `agents run` router reads
+    // Usage refresh: keep the usage cache the `agents run` router reads
     // (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
-    // This host is the sole writer for its own local accounts. The tick wakes at
-    // the 90s floor, but per-account cadence gates the actual live fetches: an
-    // account racing toward its 5h cap is polled sooner (down to 90s), an idle one
-    // rarely (up to 15min), capped at ~6 provider calls/account/hour and skipped
-    // entirely while its provider is under a 429 backoff. Overlap-guarded like the
-    // probes above; a box signed into no networked-usage account is a clean no-op.
+    // This host is the sole writer for its own local accounts. The tick wakes
+    // every 60s (USAGE_REFRESH_TICK_MS) to consider due accounts; each account
+    // is scheduled at a fixed 5-minute cadence (REFRESH_INTERVAL_MS), capped at
+    // ~12 provider calls/account/hour, skipped under 429 backoff, and fetched
+    // with fileOnly credentials so a background tick never pops macOS Touch ID.
+    // Overlap-guarded: a slow pass cannot stack concurrent refresh loops.
     let refreshingUsage = false;
     const runUsageRefreshTick = async () => {
         if (refreshingUsage)
@@ -910,9 +910,9 @@ export async function runDaemon() {
                 writeUsageCache: writeClaudeUsageCache,
                 backoffUntil: usageRateLimitedUntil,
             });
-            if (r.refreshed > 0 || r.failed > 0) {
-                log('INFO', `usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped`);
-            }
+            // Always log a compact summary so "is refresh working?" is greppable even
+            // when every account was not-due (proves the tick ran).
+            log('INFO', `usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped`);
         }
         catch (err) {
             log('ERROR', `usage refresh failed: ${err.message}`);
@@ -921,7 +921,8 @@ export async function runDaemon() {
             refreshingUsage = false;
         }
     };
-    const usageRefreshInterval = setInterval(() => { void runUsageRefreshTick(); }, 90_000);
+    // 60s wake matches USAGE_REFRESH_TICK_MS in usage-refresh.ts (keep in sync).
+    const usageRefreshInterval = setInterval(() => { void runUsageRefreshTick(); }, 60_000);
     const usageRefreshKickoff = setTimeout(() => { void runUsageRefreshTick(); }, 30_000);
     // RUSH-1817: the startup host decision above is one-shot. If a standalone
     // broker answered agentPing() at daemon start, the daemon declined to host —

package/dist/lib/device-config.js

@@ -67,6 +67,14 @@ export const CONFIG_KEYS = [
         type: 'bool',
         description: 'Whether the routines scheduler (daemon) may fire on this device.',
     },
+    {
+        name: 'browser.remote-control',
+        yamlKey: 'browserRemoteControl',
+        scope: 'device',
+        type: 'bool',
+        description: "Whether other fleet machines may drive THIS device's browser over `browser --host <this-device>`. " +
+            'Default off — a fleet-remote drive is refused until the owner runs `agents browser remote-control on`.',
+    },
     {
         name: 'notes',
         yamlKey: 'notes',

package/dist/lib/devices/resolve-target.d.ts

@@ -1,4 +1,4 @@
-import { splitUserHost } from '../hosts/registry.js';
+import { splitUserHost, type MatchHostOptions } from '../hosts/registry.js';
 import { type DeviceProfile } from './registry.js';
 export { splitUserHost };
 /** A dialable peer: the ssh target, the machine id used to tag its rows, a
@@ -21,9 +21,10 @@ export interface ResolvedExplicitTargetSet {
  * `user@host` / IP / FQDN literal yields a synthesized key-auth profile. A bare
  * unregistered alias (no `@`/dot) — or an ssh_config-only alias, which `agents
  * ssh` has never dialed — returns undefined so the caller reports "Unknown
- * device" rather than dialing a literal.
+ * device" rather than dialing a literal. `token` may also be the `auto`
+ * affinity sentinel (RUSH-2185); `opts.resolveAuto` overrides the pick (tests).
  */
-export declare function resolveDeviceTarget(token: string): Promise<DeviceProfile | undefined>;
+export declare function resolveDeviceTarget(token: string, opts?: Pick<MatchHostOptions, 'resolveAuto'>): Promise<DeviceProfile | undefined>;
 /**
  * Resolve an explicit `--host`/`--device` list to dialable targets. A token that
  * fails the injection guard or names nothing reachable is skipped with a stderr

package/dist/lib/devices/resolve-target.js

@@ -71,10 +71,11 @@ async function toResolvedTarget(token) {
  * `user@host` / IP / FQDN literal yields a synthesized key-auth profile. A bare
  * unregistered alias (no `@`/dot) — or an ssh_config-only alias, which `agents
  * ssh` has never dialed — returns undefined so the caller reports "Unknown
- * device" rather than dialing a literal.
+ * device" rather than dialing a literal. `token` may also be the `auto`
+ * affinity sentinel (RUSH-2185); `opts.resolveAuto` overrides the pick (tests).
  */
-export async function resolveDeviceTarget(token) {
-    const host = await matchHost(token, { allowBareLiteral: true });
+export async function resolveDeviceTarget(token, opts = {}) {
+    const host = await matchHost(token, { allowBareLiteral: true, ...opts });
     if (!host)
         return undefined;
     if (host.device) {

package/dist/lib/hosts/passthrough.d.ts

@@ -16,7 +16,7 @@
  * table or, when `--host`/`--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
  */
-import { type DeviceRegistry } from '../devices/registry.js';
+import { type DeviceProfile, type DeviceRegistry } from '../devices/registry.js';
 import { runLocalCommand, runOnDevice } from '../devices/fleet.js';
 /** Per-command remote behaviour. Absence from this map = not host-routable here. */
 interface RemoteSpec {
@@ -36,6 +36,15 @@ export interface FleetPassthroughOptions {
     /** Override this machine's id (tests). Defaults to `machineId()`. */
     self?: string;
 }
+/**
+ * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
+ * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
+ * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
+ * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
+ * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
+ * self target runs locally and must stay ungated.
+ */
+export declare function markFleetRemote(cmd: string[], device: DeviceProfile): string[];
 /** Run `agents <command> …` across every registered device and render the roster. */
 export declare function runFleetPassthrough(command: string, allArgs: string[], spec: RemoteSpec, opts?: FleetPassthroughOptions): Promise<boolean>;
 /**

package/dist/lib/hosts/passthrough.js

@@ -24,6 +24,7 @@ import { dispatchAgentsCommand, withActorEnv } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
+import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
@@ -319,6 +320,19 @@ function renderFleetRoster(command, forwarded, results, self) {
         console.log(chalk.gray(summaryParts.join(' · ')));
     }
 }
+/**
+ * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
+ * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
+ * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
+ * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
+ * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
+ * self target runs locally and must stay ungated.
+ */
+export function markFleetRemote(cmd, device) {
+    return device.shell === 'powershell'
+        ? [`$env:AGENTS_FLEET_REMOTE='1';`, ...cmd]
+        : ['env', 'AGENTS_FLEET_REMOTE=1', ...cmd];
+}
 /** Run `agents <command> …` across every registered device and render the roster. */
 export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const self = opts.self ?? machineId();
@@ -335,7 +349,12 @@ export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const results = await fanOutDevices(targets, async (target) => {
         const cmd = ['agents', ...forwarded];
         const isSelf = target.device.name.toLowerCase() === self.toLowerCase() || isSelfHost(target.device.name);
-        const res = isSelf ? localRunner(cmd) : runner(target.device, cmd);
+        // Only `browser` consults the fleet-remote marker (its consent gate), and
+        // the fan-out has no separate env channel — the marker must ride the argv.
+        // So scope the env-prefix to a REMOTE browser drive: every other command's
+        // remote argv stays byte-identical, and the self target is never gated.
+        const remoteCmd = !isSelf && command === 'browser' ? markFleetRemote(cmd, target.device) : cmd;
+        const res = isSelf ? localRunner(cmd) : runner(target.device, remoteCmd);
         if (res.code !== 0) {
             const detail = (res.stderr || res.stdout || 'unreachable').trim().slice(0, 200);
             throw new Error(detail || 'unreachable');
@@ -378,7 +397,7 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     const deviceFlag = flagValue(allArgs, 'device');
     const hostsFlag = flagValue(allArgs, 'hosts');
     const devicesFlag = flagValue(allArgs, 'devices');
-    const hostName = hostFlag ?? deviceFlag;
+    let hostName = hostFlag ?? deviceFlag;
     const fleetAll = isFleetAllSentinel(hostFlag, deviceFlag, hostsFlag, devicesFlag);
     // Proceed when any routing flag is present, including the plural fleet flags
     // that may carry the `all` sentinel.
@@ -442,6 +461,22 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     // flags and bare flags were already handled.
     if (!hostName)
         return false;
+    // `auto` is the same affinity sentinel `agents run --device auto` resolves
+    // (RUSH-2185) — pick the concrete target up front via resolveDeviceAffinity so
+    // the isSelfHost check right below (which compares a literal name, not "auto")
+    // still catches a local pick and runs the command locally rather than
+    // resolving to a real Host and self-SSHing (or, if this box isn't itself a
+    // registered device, dialing a literal, nonexistent host named "auto").
+    if (isDeviceAuto(hostName)) {
+        const plan = resolveDeviceAffinity({});
+        if (!plan.host) {
+            const stripped = stripRoutingFlags(allArgs, STRIP_SPECS);
+            process.argv = [process.argv[0], process.argv[1], ...stripped];
+            return false;
+        }
+        process.stderr.write(chalk.gray(`[agents] device=auto → ${plan.host}\n`));
+        hostName = plan.host;
+    }
     // Running against your own machine is just a local run — skip the SSH round-trip.
     // Match EVERY identity the box answers to (short id, loopback, tailscale
     // dnsName), not just machineId() — a `--host <self-dnsName>` used to slip past a
@@ -500,7 +535,10 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     // UNDER the doctor PATH so that PATH still wins — without this the remote
     // re-resolves the actor from THIS box's SSH_CONNECTION and mis-credits it
     // (RUSH-2028). Flows to both POSIX (export) and Windows ($env:) dialects.
-    const env = withActorEnv(doctorPath);
+    // AGENTS_FLEET_REMOTE marks this as a fleet-dispatched `--host` run so the far
+    // side can gate consent-sensitive actions — the browser consent gate
+    // (lib/browser/remote-control.ts) reads it to allow/deny a cross-machine drive.
+    const env = withActorEnv({ ...doctorPath, AGENTS_FLEET_REMOTE: '1' });
     const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, remoteOs, env);
     const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
     if (code === 255) {

package/dist/lib/hosts/registry.d.ts

@@ -19,6 +19,7 @@
 import type { Host, HostProvider, HostProviderId } from './types.js';
 import { DeviceOffloadUnsupportedError } from './types.js';
 import { type DeviceProfile } from '../devices/registry.js';
+import { type DeviceAffinityPlan } from '../smart-launch.js';
 export { DeviceOffloadUnsupportedError };
 export declare function getProvider(id: HostProviderId): HostProvider;
 export declare function getAllProviders(): HostProvider[];
@@ -52,6 +53,9 @@ export interface MatchHostOptions {
      * "Unknown device" verdict reachable).
      */
     allowBareLiteral?: boolean;
+    /** Override the affinity pick for the `auto` sentinel (tests). Defaults to
+     * `resolveDeviceAffinity({})` — the same engine `agents run --device auto` uses. */
+    resolveAuto?: () => DeviceAffinityPlan;
 }
 /**
  * The one place a `--host` / `--device` token becomes a resolved host. Reads the

package/dist/lib/hosts/registry.js

@@ -25,6 +25,8 @@ import { readMeta } from '../state.js';
 import { isSshConfigHost } from './ssh-config.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices, isControlDevice } from '../devices/registry.js';
+import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { localMachineId } from '../session/origin-machine.js';
 // Re-export so existing importers (tests, commands) keep their path; the class
 // itself lives in types.ts so providers can throw it without a circular import.
 export { DeviceOffloadUnsupportedError };
@@ -146,6 +148,20 @@ function literalHost(token, host, user) {
  * into a dispatch verdict.
  */
 export async function matchHost(name, opts = {}) {
+    // `auto` is the same affinity sentinel `agents run --device auto` resolves
+    // (isDeviceAuto / resolveDeviceAffinity in ../smart-launch.js) — shared here so
+    // every caller through this one core (ssh, teams, dispatch/passthrough) picks a
+    // device the SAME way `run` does instead of rejecting it as "Unknown device
+    // 'auto'" (RUSH-2185). A `null` plan.host means the affinity engine picked this
+    // very machine; resolve that as the local device/host entry (if any) rather than
+    // returning nothing — callers that already special-case "target is this
+    // machine" (teams add/create, the passthrough self-host check) then treat it as
+    // local exactly as they would if the user had typed the local name.
+    if (isDeviceAuto(name)) {
+        const plan = (opts.resolveAuto ?? (() => resolveDeviceAffinity({})))();
+        const picked = plan.host ?? normalizeHost(localMachineId());
+        return matchHost(picked, opts);
+    }
     try {
         assertValidSshTarget(name);
     }

package/dist/lib/hosts/remote-cmd.js

@@ -105,6 +105,7 @@ export const RUN_OPTION_FORWARDING = {
     disableTmux: 'local-only',
     host: 'local-only',
     device: 'local-only',
+    where: 'local-only', // expands into host/lease before dispatch; never re-forwarded
     on: 'local-only',
     computer: 'local-only',
     any: 'local-only',
@@ -112,6 +113,7 @@ export const RUN_OPTION_FORWARDING = {
     lease: 'local-only',
     box: 'local-only',
     keepBox: 'local-only',
+    fresh: 'local-only', // skips the warm-pool reuse for --lease; the lease path is always local
     reuse: 'local-only', // reuse-picker choice for --lease; the lease path is always local
     bare: 'local-only', // skips the local setup-copy push; lease-only concern
     tailscale: 'local-only', // --tailscale/--no-tailscale gate the lease net mode; never forwarded