@phnx-labs/agents-cli 1.22.24 → 1.22.26

package/dist/lib/feed-outcome.js

@@ -152,21 +152,22 @@ export function groupBlocksByOutcome(blocks) {
     const groups = [];
     for (const { outcome, blocks: members } of byKey.values()) {
         const mailboxes = new Set(members.map((b) => b.mailboxId));
-        let open = 0;
-        let answered = 0;
-        let parked = 0;
+        const states = new Map();
         for (const b of members) {
-            if (b.parkedAt)
-                parked += 1;
-            else if (b.answer || b.defaultedAt || b.continuedAt)
-                answered += 1;
-            else
-                open += 1;
+            const next = b.parkedAt
+                ? 'parked'
+                : b.answer || b.defaultedAt || b.continuedAt ? 'answered' : 'open';
+            const current = states.get(b.mailboxId);
+            // One agent occupies one state. Its most actionable block wins.
+            if (!current || next === 'open' || (next === 'parked' && current === 'answered')) {
+                states.set(b.mailboxId, next);
+            }
         }
+        const count = (state) => [...states.values()].filter((value) => value === state).length;
         groups.push({
             outcome,
             blocks: members,
-            counts: { agents: mailboxes.size, open, answered, parked },
+            counts: { agents: mailboxes.size, open: count('open'), answered: count('answered'), parked: count('parked') },
         });
     }
     groups.sort((a, b) => {
@@ -222,6 +223,13 @@ export function enrichBlockFromSession(block, hint) {
         next.worktreeSlug = hint.worktreeSlug;
     if (!next.project && hint.project)
         next.project = hint.project;
+    if (hint.host && hint.host !== 'terminal' && next.runtime === 'terminal')
+        next.runtime = hint.host;
+    if (hint.origin === 'routine') {
+        next.origin = 'routine';
+        if (hint.routineName)
+            next.routineName = hint.routineName;
+    }
     return next;
 }
 /**

package/dist/lib/feed.d.ts

@@ -36,6 +36,10 @@ export interface OpenBlock {
     mailboxId: string;
     host: string;
     runtime: string;
+    /** Indexed launch origin, added at read time when the live session is known. */
+    origin?: 'cli' | 'routine';
+    /** Routine definition name when origin is `routine`. */
+    routineName?: string;
     /** Project/repo name this block belongs to (derived from cwd, worktree-aware). */
     project?: string;
     ts: string;

package/dist/lib/fleet/apply.d.ts

@@ -8,6 +8,7 @@
  * (`readyProbe`, `bootstrapAgentsCli`, `buildRemoteAgentsInvocation`, `sshExec`).
  */
 import type { DeviceProfile } from '../devices/registry.js';
+import { type RemoteBackend } from '../secrets/push.js';
 import type { DeviceDesired, DeviceProbe, DeviceDiff, FleetAction, FleetPlan, AuthFilePayload } from './types.js';
 /** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
 export declare function agentIdOf(spec: string): string;
@@ -54,21 +55,76 @@ export interface DiffContext {
     /** agents-cli version the source is on — the fleet target version. */
     targetCliVersion: string;
     sourceAuth: SourceAuth;
-    /** Secrets-bundle names the profile declares. Values are keychain-local and
-     * can't be pushed, so each reachable device surfaces them as a manual recreate
-     * (`needs-secret`) — informational, never an executed mutation. */
+    /** Secrets-bundle names the profile declares. */
     secretsBundles?: string[];
+    /** `--provision-secrets`. OFF by default: pushing a bundle moves credential
+     *  VALUES to another machine, so it is opted into per invocation and never
+     *  defaulted from the shared `agents.yaml` (RUSH-1968). */
+    provisionSecrets?: boolean;
+    /** Is this device's host key pinned? Injected so `decideSecretPush` stays pure
+     *  and its refusals are testable against real known_hosts fixtures with no
+     *  network. Absent = treated as unpinned, i.e. refuse. */
+    isHostPinned?: (device: string) => boolean;
+    /** `--force`: push a declared bundle even when the device already has it. */
+    forceSecrets?: boolean;
 }
 /** Pure: desired vs probed -> per-device diff + flat action list. */
 export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;
+/** Why a declared bundle is or is not pushed to one device. */
+export interface SecretPushDecision {
+    push: boolean;
+    /** Where it would land on the remote. Only meaningful when `push`. */
+    backend: RemoteBackend;
+    /** Set when `push` is false — rendered as the `needs-secret` reminder. */
+    reason: string;
+}
+/**
+ * Decide whether `fleet apply` may push one declared bundle to one device.
+ *
+ * PURE — no ssh, no keychain, no filesystem beyond the injectable pin check — so
+ * every branch is unit-testable with no live fleet. Three gates, in order, and
+ * each REFUSAL still yields a `needs-secret` reminder rather than silence:
+ *
+ *   1. `--provision-secrets` must be set. Off by default, and deliberately a
+ *      flag rather than an `agents.yaml` field: the manifest is shared, so a
+ *      file-level default means someone else's `apply -y` ships credential
+ *      values without deciding to (RUSH-1968's shape of accident).
+ *   2. The device must be reachable — nothing to push to otherwise.
+ *   3. The host key must be PINNED. This moves credential values to another
+ *      machine, so it reuses the same bar `agents exec --copy-creds` already
+ *      sets (EXEC-34): an unpinned device earns its pin through a normal
+ *      `agents ssh <device>` first.
+ *
+ * Backend follows the platform, and this is the load-bearing default of the
+ * whole feature: **file on Linux, keychain on macOS/Windows**. A headless Linux
+ * box has no keychain (`lib/secrets/linux.ts`), and the file store there
+ * auto-provisions its OWN machine-local key — so each box ends up with an
+ * unshared at-rest key and NO passphrase is forwarded. That is the direct
+ * alternative to the fleet-wide shared secret this ticket exists to remove.
+ */
+export declare function decideSecretPush(bundle: string, desired: DeviceDesired, probe: DeviceProbe, ctx: DiffContext): SecretPushDecision;
 export interface ProbeOptions {
     /** Also fetch per-agent installed versions (one extra `agents view --json`
      * round-trip). Enable only when the plan has a version-pinned spec. */
     withVersions?: boolean;
+    /** Also fetch which secrets bundles the device already has (one extra
+     *  `agents secrets list --json`). Enable only when the manifest declares
+     *  bundles and provisioning is on — same cost discipline as `withVersions`. */
+    withSecrets?: boolean;
 }
 /** Probe one device: reachability + agents-cli version + installed agent ids
  * (and, when `withVersions`, the installed version strings per agent). */
 export declare function probeDevice(device: DeviceProfile, opts?: ProbeOptions): DeviceProbe;
+/**
+ * Narrow a remote `secrets list --json` payload to `name -> updated_at`.
+ *
+ * Exported and pure so the parse is unit-tested against real payload shapes with
+ * no live fleet. Returns `{}` rather than throwing on anything unexpected: the
+ * remote runs its own agents-cli version, and a parse failure must degrade to
+ * "unknown, so push" — never to "present, so skip", which would silently leave a
+ * device unprovisioned.
+ */
+export declare function parseRemoteBundles(stdout: string): Record<string, string>;
 export interface ApplyStep {
     kind: FleetAction['kind'];
     ok: boolean;

package/dist/lib/fleet/apply.js

@@ -8,6 +8,7 @@
  * (`readyProbe`, `bootstrapAgentsCli`, `buildRemoteAgentsInvocation`, `sshExec`).
  */
 import * as os from 'os';
+import { pushBundleToHost } from '../secrets/push.js';
 import { sshTargetFor } from '../devices/connect.js';
 import { readyProbe, bootstrapAgentsCli } from '../hosts/ready.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
@@ -167,14 +168,33 @@ export function diffFleet(desired, probes, ctx) {
                     }
                 }
             }
-            // secrets — surfaced, never pushed (values are keychain-local). Declared
-            // once at the manifest level, so every reachable device gets the same
-            // manual-recreate reminder. Not an executable action (see idempotence
-            // check in commands/apply.ts, which excludes needs-* kinds).
+            // secrets. Declared once at the manifest level, so every reachable device
+            // is considered. Historically this was ALWAYS a manual reminder — "surfaced,
+            // never pushed" — and that gap is a direct cause of RUSH-1968: an operator
+            // who needed secrets on a worker box had no supported path, so they
+            // hand-exported the file store's master key across the fleet instead.
+            //
+            // It is now pushable, but only deliberately. `--provision-secrets` is off by
+            // default and is a FLAG, not a manifest field: `agents.yaml` is shared, and
+            // a file-level default would mean someone else's `apply -y` silently ships
+            // credential values — the same shape of accident this ticket is about.
+            // Everything the gate refuses stays a `needs-secret` reminder, so nothing
+            // is ever silently skipped.
             if (ctx.secretsBundles && ctx.secretsBundles.length > 0) {
                 for (const bundle of ctx.secretsBundles) {
-                    secretsNeeded.push(bundle);
-                    rowActions.push({ device: d.device, kind: 'needs-secret', detail: `recreate secrets bundle '${bundle}' (\`agents secrets create ${bundle}\`)` });
+                    const decision = decideSecretPush(bundle, d, probe, ctx);
+                    if (decision.push) {
+                        rowActions.push({
+                            device: d.device,
+                            kind: 'push-secret',
+                            bundle,
+                            detail: `push secrets bundle '${bundle}' (${decision.backend} backend)`,
+                        });
+                    }
+                    else {
+                        secretsNeeded.push(bundle);
+                        rowActions.push({ device: d.device, kind: 'needs-secret', bundle, detail: decision.reason });
+                    }
                 }
             }
         }
@@ -183,6 +203,66 @@ export function diffFleet(desired, probes, ctx) {
     }
     return { devices, actions };
 }
+/**
+ * Decide whether `fleet apply` may push one declared bundle to one device.
+ *
+ * PURE — no ssh, no keychain, no filesystem beyond the injectable pin check — so
+ * every branch is unit-testable with no live fleet. Three gates, in order, and
+ * each REFUSAL still yields a `needs-secret` reminder rather than silence:
+ *
+ *   1. `--provision-secrets` must be set. Off by default, and deliberately a
+ *      flag rather than an `agents.yaml` field: the manifest is shared, so a
+ *      file-level default means someone else's `apply -y` ships credential
+ *      values without deciding to (RUSH-1968's shape of accident).
+ *   2. The device must be reachable — nothing to push to otherwise.
+ *   3. The host key must be PINNED. This moves credential values to another
+ *      machine, so it reuses the same bar `agents exec --copy-creds` already
+ *      sets (EXEC-34): an unpinned device earns its pin through a normal
+ *      `agents ssh <device>` first.
+ *
+ * Backend follows the platform, and this is the load-bearing default of the
+ * whole feature: **file on Linux, keychain on macOS/Windows**. A headless Linux
+ * box has no keychain (`lib/secrets/linux.ts`), and the file store there
+ * auto-provisions its OWN machine-local key — so each box ends up with an
+ * unshared at-rest key and NO passphrase is forwarded. That is the direct
+ * alternative to the fleet-wide shared secret this ticket exists to remove.
+ */
+export function decideSecretPush(bundle, desired, probe, ctx) {
+    const device = desired.device;
+    const backend = probe.platform === 'linux' ? 'file' : 'keychain';
+    const manual = `recreate secrets bundle '${bundle}' (\`agents ssh ${device} -- secrets create ${bundle}\`)`;
+    if (!ctx.provisionSecrets) {
+        return { push: false, backend, reason: `${manual} — or re-run with --provision-secrets to push it` };
+    }
+    if (!probe.reachable) {
+        return { push: false, backend, reason: manual };
+    }
+    // Already there? Skip — otherwise every `apply` re-resolves the bundle, and a
+    // resolve can prompt for Touch ID, so a converged fleet would nag on every run.
+    //
+    // Known limitation, stated rather than hidden: this compares PRESENCE (and
+    // carries `updated_at` for a future content check). It is a timestamp
+    // heuristic, not a content hash — a bundle whose VALUES changed locally still
+    // reads as present. `--force` is the way to overwrite regardless.
+    // hasOwnProperty, NOT `in`: `in` walks the prototype chain, so a bundle named
+    // `toString` / `constructor` / `valueOf` would read as present on an EMPTY map
+    // and be silently skipped — leaving that device unprovisioned, the worse of the
+    // two errors this gate can make.
+    if (!ctx.forceSecrets && probe.remoteBundles
+        && Object.prototype.hasOwnProperty.call(probe.remoteBundles, bundle)) {
+        return { push: false, backend, reason: `secrets bundle '${bundle}' already present on ${device} — pass --force to overwrite` };
+    }
+    if (!ctx.isHostPinned?.(device)) {
+        // Same bar as `exec --copy-creds`: never ship credential values to a host
+        // whose key we have not pinned.
+        return {
+            push: false,
+            backend,
+            reason: `${manual} — host key not pinned; run \`agents ssh ${device}\` once to pin it, then re-apply`,
+        };
+    }
+    return { push: true, backend, reason: '' };
+}
 // ---- execution (real SSH; verified end-to-end, not unit-mocked) ----
 function osHint(platform) {
     return platform === 'windows' ? 'windows' : undefined;
@@ -225,6 +305,15 @@ export function probeDevice(device, opts) {
         if (vres.code === 0)
             installedVersions = parseInstalledVersions(vres.stdout);
     }
+    let remoteBundles;
+    if (opts?.withSecrets) {
+        // Metadata only — `secrets list --json` returns names + timestamps and never
+        // values, which is why this is safe to run across the fleet.
+        const listCmd = buildRemoteAgentsInvocation(['secrets', 'list', '--json'], undefined, hint, remoteEnv(device.platform));
+        const lres = sshExec(target, listCmd, { timeoutMs: 30000, multiplex: true });
+        if (lres.code === 0)
+            remoteBundles = parseRemoteBundles(lres.stdout);
+    }
     return {
         device: device.name,
         reachable: true,
@@ -232,8 +321,52 @@ export function probeDevice(device, opts) {
         cliVersion: ready.version ?? undefined,
         installedAgents: installed,
         installedVersions,
+        remoteBundles,
     };
 }
+/**
+ * Narrow a remote `secrets list --json` payload to `name -> updated_at`.
+ *
+ * Exported and pure so the parse is unit-tested against real payload shapes with
+ * no live fleet. Returns `{}` rather than throwing on anything unexpected: the
+ * remote runs its own agents-cli version, and a parse failure must degrade to
+ * "unknown, so push" — never to "present, so skip", which would silently leave a
+ * device unprovisioned.
+ */
+export function parseRemoteBundles(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const rows = Array.isArray(parsed)
+            ? parsed
+            : Array.isArray(parsed?.bundles)
+                ? parsed.bundles
+                : [];
+        // Null-prototype: a remote-supplied name is used as a KEY here, so `{}` would
+        // let `__proto__` hit the prototype setter instead of becoming an own
+        // property (and then read back as absent). It also means the presence check
+        // cannot see inherited names.
+        const out = Object.create(null);
+        for (const row of rows) {
+            if (!row || typeof row !== 'object')
+                continue;
+            const r = row;
+            const name = typeof r.name === 'string' ? r.name : undefined;
+            if (!name)
+                continue;
+            // `updatedAt` is the real field name in `secrets list --json` — verified
+            // against a live payload, not assumed. `updated_at` is accepted too so an
+            // older remote is not silently recorded with an empty timestamp.
+            const ts = typeof r.updatedAt === 'string' ? r.updatedAt
+                : typeof r.updated_at === 'string' ? r.updated_at
+                    : '';
+            out[name] = ts;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
 /** Execute one device's planned actions in order. Real SSH — no mocks. */
 export function reconcileDevice(row, device, ctx) {
     if (!row.probe.reachable) {
@@ -290,6 +423,50 @@ export function reconcileDevice(row, device, ctx) {
         steps.push({ kind: 'push-login', ok: r.code === 0, detail: `propagate login: ${pushAgents.join(', ')}` });
         ok = ok && r.code === 0;
     }
+    // 5. secrets provisioning — LAST, and deliberately so. It is the most
+    // sensitive mutation apply performs (credential VALUES crossing to another
+    // machine), so every lower-risk step above is already recorded before we
+    // touch it: a failure here never obscures what did land.
+    //
+    // Resolve ONCE per device even for several bundles is not possible (a resolve
+    // is per bundle), but each bundle resolves once and pushes once — the read can
+    // prompt, so it must not repeat.
+    const pushSecrets = row.actions.filter((a) => a.kind === 'push-secret');
+    for (const action of pushSecrets) {
+        const bundle = action.bundle;
+        if (!bundle) {
+            // A push-secret action without a bundle name is a planner bug, not a
+            // recoverable state — fail loud rather than push nothing and report ok.
+            steps.push({ kind: 'push-secret', ok: false, detail: 'push-secret action carried no bundle name' });
+            ok = false;
+            continue;
+        }
+        const backend = device.platform === 'linux' ? 'file' : 'keychain';
+        try {
+            const out = pushBundleToHost(bundle, target, {
+                remoteBackend: backend,
+                operation: `fleet apply ${row.device}`,
+                // No passphrase, ever, from this path. On the file backend the remote
+                // auto-provisions its OWN machine-local key, which is the entire point:
+                // each box gets an unshared at-rest key instead of the fleet-wide shared
+                // secret RUSH-1968 is about.
+            });
+            steps.push({
+                kind: 'push-secret',
+                ok: out.ok,
+                detail: out.ok
+                    ? `secrets '${bundle}' -> ${row.device} (${backend}): ${out.message}`
+                    : `secrets '${bundle}' -> ${row.device}: ${out.message}`,
+            });
+            ok = ok && out.ok;
+        }
+        catch (e) {
+            // A local resolve failure (locked store, missing bundle, multi-line value)
+            // is reported per bundle rather than aborting the whole device.
+            steps.push({ kind: 'push-secret', ok: false, detail: `secrets '${bundle}': ${e.message}` });
+            ok = false;
+        }
+    }
     // Surface blocked logins as (non-fatal) informational steps.
     for (const blocked of row.loginBlocked) {
         steps.push({ kind: 'needs-login', ok: false, detail: `${blocked} needs a manual login (\`agents ssh ${row.device} -- ${blocked}\`)` });

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

@@ -95,13 +95,28 @@ export interface DeviceProbe {
      * undefined, version-pinned specs fall back to id-level presence.
      */
     installedVersions?: Record<string, string[]>;
+    /**
+     * Secrets bundles already present on the device: name -> `updated_at` (or ''
+     * when the remote reports none). Only populated when the manifest declares
+     * bundles AND `--provision-secrets` is set — a fleet that uses no bundles
+     * never pays for the extra round trip.
+     *
+     * METADATA ONLY. `agents secrets list --json` returns names and timestamps and
+     * explicitly never values, which is what makes this probe safe to run.
+     */
+    remoteBundles?: Record<string, string>;
     /** Reason string when `reachable` is false or the probe partially failed. */
     note?: string;
 }
 /** One planned action against a device, in a single reconcile dimension. */
 export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'push-login' | 'needs-login'
-/** Secrets bundles the profile declares but that can't be pushed (values are
- * keychain-local) — surfaced as a manual recreate, like `needs-login`. */
+/** Push a declared secrets bundle to the device over SSH. Opt-in only
+ * (`--provision-secrets`) and gated on a pinned host key, because this moves
+ * credential VALUES to another machine (RUSH-1968). */
+ | 'push-secret'
+/** A declared secrets bundle that could NOT be pushed — the flag is off, the
+ * host key isn't pinned, or the bundle is already current. Surfaced as a manual
+ * recreate, like `needs-login`. */
  | 'needs-secret';
 export interface FleetAction {
     device: string;
@@ -111,6 +126,10 @@ export interface FleetAction {
     /** Full agent spec for `add-agent` (e.g. `claude@2.1.170`) so the plan can show
      * the exact version being installed; equals the id for a bare/latest spec. */
     spec?: string;
+    /** Bundle name for `push-secret` / `needs-secret`, so the executor pushes the
+     *  bundle the planner decided on rather than re-deriving it from the detail
+     *  string. */
+    bundle?: string;
     /** Human, one-line description of the action. */
     detail: string;
 }

package/dist/lib/hooks/cache.js

@@ -505,6 +505,21 @@ if [ "$CACHE_STATUS" = miss ]; then
     if [ "$_in_backoff" -eq 0 ]; then
       # Fix 1: lockdir — only one background refresh runs at a time.
       LOCK_DIR="$CACHE_FILE.bg.lck"
+      # Fix 4 (RUSH-2259): reclaim a stale lock. The lock is released by the bg
+      # subshell's EXIT trap, but a hard kill (SIGKILL, OOM, reboot) skips the
+      # trap and orphans the dir — after which every future mkdir fails and bg
+      # refresh stops FOREVER while stale cache is served indefinitely. The dir
+      # mtime is fixed at mkdir time (the refresh writes elsewhere), so its age
+      # is the time the lock has been held; treat a lock older than LOCK_TTL_SEC
+      # as abandoned and remove it before locking. LOCK_TTL_SEC is set well above
+      # any real hook runtime so a live refresh is never reclaimed out from under.
+      LOCK_TTL_SEC=300
+      if [ -d "$LOCK_DIR" ]; then
+        _lock_mtime=$("$PY" -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$LOCK_DIR" 2>/dev/null || echo 0)
+        _lock_now_s=$(date +%s)
+        _lock_age=$((_lock_now_s - \${_lock_mtime:-0}))
+        [ "$_lock_age" -ge "$LOCK_TTL_SEC" ] && rm -rf "$LOCK_DIR" 2>/dev/null
+      fi
       if mkdir "$LOCK_DIR" 2>/dev/null; then
         tmp="$CACHE_FILE.new.$$"
         # Fix 3: background subshell captures and logs its own real exit code.

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

@@ -16,6 +16,7 @@
  * table or, when `--host`/`--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
  */
+import { type Host } from './types.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. */
@@ -60,4 +61,47 @@ export declare function runFleetPassthrough(command: string, allArgs: string[],
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
  */
 export declare function maybeRunOnHost(command: string, allArgs: string[], opts?: FleetPassthroughOptions): Promise<boolean>;
+/**
+ * `--host` passthrough for a **standalone binary** whose command name is fixed by
+ * the binary itself (the `browser`/`computer` bins, `dist/browser.js` etc.) rather
+ * than being the first argv token.
+ *
+ * `agents browser … --host <box>` routes through {@link maybeRunOnHost} in
+ * index.ts, but the standalone `browser` binary never enters index.ts — so without
+ * this it dropped `--host` entirely (commander errored with `unknown option
+ * '--host'`). This wires the identical routing: it synthesizes the implicit command
+ * token (`browser`) at the front of the argv so the remote invocation builds as
+ * `agents browser …`, delegates to {@link maybeRunOnHost}, and returns `true` when
+ * it dispatched the run to a remote (the local program must then NOT parse).
+ *
+ * On a local / self-host fall-through it rewrites `process.argv` to the ORIGINAL
+ * args minus the routing flags — never the synthetic command token — so the
+ * standalone commander program parses cleanly and never sees an unknown `--host`.
+ * When no routing flag is present it leaves `process.argv` untouched (the common
+ * case), so an unrelated flag like `--no-tty` is never stripped from a purely local
+ * run.
+ *
+ * @param command the fixed command name the binary stands for (`'browser'`).
+ */
+export declare function maybeRunStandaloneOnHost(command: string, opts?: FleetPassthroughOptions): Promise<boolean>;
+/**
+ * Run `agents <forwardedArgs>` on `host` over SSH, streaming its output, and
+ * return the exit code. The single place the SSH hop is built, so every remote
+ * `agents` invocation carries identical env semantics.
+ *
+ * Forwards actor provenance (`AGENTS_ACTOR`/`GIT_` vars) across the hop, merged UNDER
+ * `extraEnv` so a caller-supplied 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.
+ * AGENTS_FLEET_REMOTE marks this as a fleet-dispatched 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.
+ */
+export declare function streamAgentsOnHost(host: Host, forwardedArgs: string[], opts?: {
+    remoteCwd?: string;
+    interactive?: boolean;
+    extraEnv?: Record<string, string>;
+    remoteOs?: string;
+    target?: string;
+}): number;
 export {};

package/dist/lib/hosts/passthrough.js

@@ -29,6 +29,7 @@ import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
 import { platformGroupLabel } from '../devices/health-report.js';
+import { isKnownTopLevelCommand } from '../startup/command-registry.js';
 /**
  * First-class groups that run transparently on a remote via SSH when
  * `--host`/`--device` is present. Keep both canonical names and aliases
@@ -436,6 +437,15 @@ export async function maybeRunOnHost(command, allArgs, opts) {
         if (!isAll && command !== 'routines')
             return false;
     }
+    // A command that does not exist is an unknown-command error, not a routing
+    // error. The router runs BEFORE commander parses, so without this gate a typo
+    // (`agents session resume --host box`) was answered with "does not support
+    // --host/--device" — a true statement about a command the user never typed,
+    // and the exact opposite of the truth for the `sessions` they meant, which
+    // does support it. Fall through so commander reports `unknown command` (and
+    // its did-you-mean). RUSH-2022.
+    if (!isKnownTopLevelCommand(command))
+        return false;
     const spec = REMOTE_PASSTHROUGH[command];
     if (!spec) {
         // Flag was accepted (no raw commander "unknown option") but this group has
@@ -532,20 +542,82 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     const doctorPath = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
         ? { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' }
         : undefined;
-    // Forward actor provenance (AGENTS_ACTOR*/GIT_*) across the SSH hop, merged
-    // 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.
-    // 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 });
+    process.exitCode = streamAgentsOnHost(host, forwarded, {
+        remoteCwd,
+        interactive,
+        extraEnv: doctorPath,
+        remoteOs,
+        target,
+    });
+    return true;
+}
+/**
+ * `--host` passthrough for a **standalone binary** whose command name is fixed by
+ * the binary itself (the `browser`/`computer` bins, `dist/browser.js` etc.) rather
+ * than being the first argv token.
+ *
+ * `agents browser … --host <box>` routes through {@link maybeRunOnHost} in
+ * index.ts, but the standalone `browser` binary never enters index.ts — so without
+ * this it dropped `--host` entirely (commander errored with `unknown option
+ * '--host'`). This wires the identical routing: it synthesizes the implicit command
+ * token (`browser`) at the front of the argv so the remote invocation builds as
+ * `agents browser …`, delegates to {@link maybeRunOnHost}, and returns `true` when
+ * it dispatched the run to a remote (the local program must then NOT parse).
+ *
+ * On a local / self-host fall-through it rewrites `process.argv` to the ORIGINAL
+ * args minus the routing flags — never the synthetic command token — so the
+ * standalone commander program parses cleanly and never sees an unknown `--host`.
+ * When no routing flag is present it leaves `process.argv` untouched (the common
+ * case), so an unrelated flag like `--no-tty` is never stripped from a purely local
+ * run.
+ *
+ * @param command the fixed command name the binary stands for (`'browser'`).
+ */
+export async function maybeRunStandaloneOnHost(command, opts) {
+    const rawArgs = process.argv.slice(2);
+    const hasRoutingFlag = flagValue(rawArgs, 'host', 'H') !== undefined ||
+        flagValue(rawArgs, 'device') !== undefined ||
+        flagValue(rawArgs, 'hosts') !== undefined ||
+        flagValue(rawArgs, 'devices') !== undefined;
+    // No routing flag → nothing to route or strip. Leave argv alone so a purely
+    // local run keeps every flag it passed.
+    if (!hasRoutingFlag)
+        return false;
+    // Keep --help/--version local (docs must work without a reachable host), mirroring
+    // index.ts's `helpOrVersionRequested` guard, but still strip the routing flags
+    // below so commander doesn't choke on them.
+    const helpOrVersion = rawArgs.some((a) => a === '--help' || a === '-h' || a === '--version' || a === '-V');
+    if (!helpOrVersion && (await maybeRunOnHost(command, [command, ...rawArgs], opts))) {
+        return true;
+    }
+    // Local / self-host fall-through (maybeRunOnHost may have rewritten process.argv
+    // with the synthetic command token). Rebuild argv from the original args minus
+    // the routing flags so the standalone program parses cleanly.
+    process.argv = [process.argv[0], process.argv[1], ...stripRoutingFlags(rawArgs, STRIP_SPECS)];
+    return false;
+}
+/**
+ * Run `agents <forwardedArgs>` on `host` over SSH, streaming its output, and
+ * return the exit code. The single place the SSH hop is built, so every remote
+ * `agents` invocation carries identical env semantics.
+ *
+ * Forwards actor provenance (`AGENTS_ACTOR`/`GIT_` vars) across the hop, merged UNDER
+ * `extraEnv` so a caller-supplied 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.
+ * AGENTS_FLEET_REMOTE marks this as a fleet-dispatched 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.
+ */
+export function streamAgentsOnHost(host, forwardedArgs, opts = {}) {
+    const target = opts.target ?? sshTargetFor(host);
+    const remoteOs = opts.remoteOs ?? resolveRemoteOsSync(host.name);
+    const env = withActorEnv({ ...opts.extraEnv, AGENTS_FLEET_REMOTE: '1' });
+    const remoteCmd = buildRemoteAgentsInvocation(forwardedArgs, opts.remoteCwd, remoteOs, env);
+    const code = sshStream(target, remoteCmd, { tty: !!opts.interactive, multiplex: true });
     if (code === 255) {
         console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +
             chalk.gray(' Check: agents hosts check ' + host.name));
     }
-    process.exitCode = code;
-    return true;
+    return code;
 }

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

@@ -42,6 +42,8 @@ export interface ReadyProbe {
     version: string | null;
     /** Raw `agents view`/`list` output, for installed-agent checks. */
     view: string;
+    /** True when the ssh probe timed out before the sentinel arrived. */
+    timedOut?: boolean;
 }
 /**
  * Answer every readiness question in ONE ssh round-trip: reachable? (the login