@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/hosts/option.js

@@ -1,5 +1,5 @@
 /**
- * Shared `--host` option registrar. Every command that can run on a remote host
+ * Shared `--device` option registrar. Every command that can run on a remote device
  * declares the flag through here, so its spelling, help text, and companions
  * (`--remote-cwd`, `--no-tty`, `--any`) stay identical everywhere and show up in
  * each command's `--help`.
@@ -7,14 +7,13 @@
  * The flags are consumed centrally by `maybeRunOnHost` (passthrough.ts) *before*
  * commander parses, so for a real remote run the local action never sees them.
  * Registering them here still matters: it documents the flag and keeps the local
- * fall-through (e.g. `--host <this-machine>`) from erroring on an unknown option.
+ * fall-through (e.g. `--device <this-machine>`) from erroring on an unknown option.
  */
-/** Attach the standard `--host` flag family to a command and return it (chainable). */
+/** Attach the standard `--device` flag family to a command and return it (chainable). */
 export function addHostOption(cmd) {
     return cmd
-        .option('-H, --host <name>', 'Run this command on another machine over SSH instead of locally — a device, an ssh-config host, user@host, or `all` to fan out across every registered device. See `agents devices`.')
-        .option('--device <name>', 'Alias of --host: run this command on a registered device (from `agents devices`), or `all` to run it across the whole fleet.')
-        .option('--remote-cwd <dir>', "Working directory on the host for --host runs. Resolves on the REMOTE host — pass a '$HOME'-relative path (single-quoted so your local shell doesn't expand it) or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you). No effect on 'teams add'.")
-        .option('--no-tty', 'Force non-interactive output for --host runs even from a terminal.')
-        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');
+        .option('-D, --device <name>', 'Run this command on another machine over SSH instead of locally — a registered device, user@host, or `all` to fan out across every registered device. See `agents devices` / `agents hosts`.')
+        .option('--remote-cwd <dir>', "Working directory on the device for --device runs. Resolves on the REMOTE device — pass a '$HOME'-relative path (single-quoted so your local shell doesn't expand it) or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you). No effect on 'teams add'.")
+        .option('--no-tty', 'Force non-interactive output for --device runs even from a terminal.')
+        .option('--any', 'With --device <cap> (a capability tag), pick any matching device instead of erroring when several match.');
 }

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

@@ -1,5 +1,5 @@
 /**
- * Generic `--host` passthrough — the single choke point that runs an allowlisted
+ * Generic `--device` passthrough — the single choke point that runs an allowlisted
  * `agents <command>` on a remote host instead of locally. Called once from
  * `index.ts` before commander parses; returns `true` when it handled the
  * invocation (the local command must then NOT run).
@@ -10,10 +10,10 @@
  * long-running case — `teams start --watch` — dispatches detached so the remote
  * supervisor outlives a dropped connection.
  *
- * Commands with their own richer `--host` handling (`run`/`sessions`/`feed`/
+ * Commands with their own richer `--device` handling (`run`/`sessions`/`feed`/
  * `computer`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
  * fall through to their local actions. Everything else either routes via this
- * table or, when `--host`/`--device` is present, exits with a clear
+ * table or, when `--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
  */
 import { type Host } from './types.js';
@@ -28,7 +28,7 @@ interface RemoteSpec {
 }
 /**
  * First-class groups that run transparently on a remote via SSH when
- * `--host`/`--device` is present. Keep both canonical names and aliases
+ * `--device` is present. Keep both canonical names and aliases
  * (`repo`/`repos`, `exec`/`run`) so either argv form routes the same way.
  *
  * Prefer adding here over per-command SSH code — this is the single choke point.
@@ -43,7 +43,7 @@ interface RemoteSpec {
  */
 export declare const REMOTE_PASSTHROUGH: Record<string, RemoteSpec>;
 /**
- * Commands that register and interpret `--host`/`--device` themselves — must
+ * Commands that register and interpret `--device` themselves — must
  * fall through to local commander even when the flag is present. Do not add
  * these to {@link REMOTE_PASSTHROUGH}.
  */
@@ -71,34 +71,34 @@ export declare function markFleetRemote(cmd: string[], device: DeviceProfile): s
 /** 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>;
 /**
- * Route `agents <command> … --host <name>` to a remote if the command is
- * host-routable and a `--host` (or its `--device` alias) was given. Returns
- * `false` (run locally) when neither flag is present, the command owns its own
- * host handling, the target is this very machine, or placement flags need the
- * local action. Returns `true` after printing a clear error when the flag is
- * present on a command that is neither routable nor self-handling — so the user
- * never sees commander's raw `unknown option '--host'`.
+ * Route `agents <command> … --device <name>` to a remote if the command is
+ * device-routable and `--device` (or a fleet sentinel `--hosts`/`--devices`) was
+ * given. Returns `false` (run locally) when no routing flag is present, the
+ * command owns its own device handling, the target is this very machine, or
+ * placement flags need the local action. Returns `true` after printing a clear
+ * error when the flag is present on a command that is neither routable nor
+ * self-handling — so the user never sees commander's raw `unknown option`.
  *
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @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
+ * `--device` 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
+ * `agents browser … --device <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
+ * this it dropped `--device` entirely (commander errored with `unknown option
+ * '--device'`). 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`.
+ * standalone commander program parses cleanly and never sees an unknown `--device`.
  * 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.

package/dist/lib/hosts/passthrough.js

@@ -1,5 +1,5 @@
 /**
- * Generic `--host` passthrough — the single choke point that runs an allowlisted
+ * Generic `--device` passthrough — the single choke point that runs an allowlisted
  * `agents <command>` on a remote host instead of locally. Called once from
  * `index.ts` before commander parses; returns `true` when it handled the
  * invocation (the local command must then NOT run).
@@ -10,10 +10,10 @@
  * long-running case — `teams start --watch` — dispatches detached so the remote
  * supervisor outlives a dropped connection.
  *
- * Commands with their own richer `--host` handling (`run`/`sessions`/`feed`/
+ * Commands with their own richer `--device` handling (`run`/`sessions`/`feed`/
  * `computer`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
  * fall through to their local actions. Everything else either routes via this
- * table or, when `--host`/`--device` is present, exits with a clear
+ * table or, when `--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
  */
 import chalk from 'chalk';
@@ -38,7 +38,7 @@ import { isKnownTopLevelCommand } from '../startup/command-registry.js';
 export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 /**
  * First-class groups that run transparently on a remote via SSH when
- * `--host`/`--device` is present. Keep both canonical names and aliases
+ * `--device` is present. Keep both canonical names and aliases
  * (`repo`/`repos`, `exec`/`run`) so either argv form routes the same way.
  *
  * Prefer adding here over per-command SSH code — this is the single choke point.
@@ -60,11 +60,9 @@ export const REMOTE_PASSTHROUGH = {
     check: {},
     list: {},
     usage: {},
-    cost: {},
     insights: {},
-    output: {},
-    budget: {},
     // config / resources
+    config: {},
     sync: { nonInteractive: ['--yes'] },
     pull: {},
     push: {},
@@ -82,7 +80,6 @@ export const REMOTE_PASSTHROUGH = {
     subagents: {},
     workflows: {},
     models: {},
-    profiles: {},
     defaults: {},
     alias: {},
     // Installations are per-machine, so updating one on a peer means running it
@@ -109,14 +106,14 @@ export const REMOTE_PASSTHROUGH = {
     browser: {},
 };
 /**
- * Commands that register and interpret `--host`/`--device` themselves — must
+ * Commands that register and interpret `--device` themselves — must
  * fall through to local commander even when the flag is present. Do not add
  * these to {@link REMOTE_PASSTHROUGH}.
  */
 export const OWN_HOST_COMMANDS = new Set([
     'run',
     'exec', // deprecated alias of run
-    'harness', // `--host <agent>` names the host CLI to run under, not a remote device
+    'harness', // `--host <agent>` names the host CLI to run under (not a device routing flag)
     'harnesses',
     'sessions',
     'feed',
@@ -149,7 +146,7 @@ function syntheticHost(target) {
     // Bare name: ssh resolves it from ~/.ssh/config, or connects to it as a hostname.
     return { name: target, provider: 'local', source: 'ssh-config' };
 }
-/** Resolve a `--host` value to a Host: enrolled name → capability tag → raw target. */
+/** Resolve a `--device` value to a Host: enrolled name → capability tag → raw target. */
 async function resolveTargetHost(name, any) {
     const enrolled = await resolveHost(name);
     if (enrolled)
@@ -238,7 +235,7 @@ function formatCompactTokens(n) {
         return `${(n / 1e3).toFixed(1)}K`;
     return String(n);
 }
-/** One-line summary of a per-device `agents output --json` payload. */
+/** One-line summary of a per-device `agents insights output --json` payload. */
 function summarizeOutputResult(json) {
     const p = json;
     const burn = p?.burn;
@@ -254,12 +251,38 @@ function summarizeOutputResult(json) {
         parts.push(`${commits} commits`);
     return parts.length ? parts.join(' · ') : 'ok';
 }
+/**
+ * Summarize a `sync` payload, surfacing anything the peer REFUSED to write.
+ *
+ * The fan-out injects `--json`, so each peer returns the corrected `ok` and
+ * `declined` from RUSH-2700 — but the roster rendered a flat `ok` regardless,
+ * so `agents sync --device all` printed a green row for every box even when a
+ * harness's config was never written. That is the fleet-wide silent success
+ * this ticket exists to remove, one layer above where it was fixed.
+ *
+ * Covers both payload shapes: the umbrella carries a flat `declined`, the
+ * per-agent modes carry one per version.
+ */
+function summarizeSyncResult(json) {
+    const p = json;
+    const flat = Array.isArray(p?.declined) ? p.declined : [];
+    const perVersion = Array.isArray(p?.versions)
+        ? p.versions.flatMap((v) => (Array.isArray(v?.declined) ? v.declined : []))
+        : [];
+    const declined = [...flat, ...perVersion];
+    if (declined.length === 0)
+        return 'ok';
+    return `${declined.length} not written`;
+}
 /** Best-effort summary of any per-device JSON payload. */
 function summarizeResult(command, forwarded, json) {
     if (command === 'view')
         return summarizeViewResult(forwarded, json);
-    if (command === 'output')
+    // #2621 nested `output` under `insights`; main added a sync declined tally.
+    if (command === 'insights' && forwarded[1] === 'output')
         return summarizeOutputResult(json);
+    if (command === 'sync')
+        return summarizeSyncResult(json);
     return 'ok';
 }
 const GROUP_ORDER = ['macOS', 'Linux', 'Windows', 'Other'];
@@ -382,39 +405,37 @@ export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     return true;
 }
 /**
- * Route `agents <command> … --host <name>` to a remote if the command is
- * host-routable and a `--host` (or its `--device` alias) was given. Returns
- * `false` (run locally) when neither flag is present, the command owns its own
- * host handling, the target is this very machine, or placement flags need the
- * local action. Returns `true` after printing a clear error when the flag is
- * present on a command that is neither routable nor self-handling — so the user
- * never sees commander's raw `unknown option '--host'`.
+ * Route `agents <command> … --device <name>` to a remote if the command is
+ * device-routable and `--device` (or a fleet sentinel `--hosts`/`--devices`) was
+ * given. Returns `false` (run locally) when no routing flag is present, the
+ * command owns its own device handling, the target is this very machine, or
+ * placement flags need the local action. Returns `true` after printing a clear
+ * error when the flag is present on a command that is neither routable nor
+ * self-handling — so the user never sees commander's raw `unknown option`.
  *
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
  */
 export async function maybeRunOnHost(command, allArgs, opts) {
-    const hostFlag = flagValue(allArgs, 'host', 'H');
-    const deviceFlag = flagValue(allArgs, 'device');
+    const deviceFlag = flagValue(allArgs, 'device', 'D');
     const hostsFlag = flagValue(allArgs, 'hosts');
     const devicesFlag = flagValue(allArgs, 'devices');
-    let hostName = hostFlag ?? deviceFlag;
-    const fleetAll = isFleetAllSentinel(hostFlag, deviceFlag, hostsFlag, devicesFlag);
+    let hostName = deviceFlag;
+    const fleetAll = isFleetAllSentinel(undefined, deviceFlag, hostsFlag, devicesFlag);
     // Proceed when any routing flag is present, including the plural fleet flags
     // that may carry the `all` sentinel.
     if (!hostName && !hostsFlag && !devicesFlag)
         return false;
-    // Commands with their own richer --host semantics must reach local commander
-    // BEFORE any single-target conflict gate. sessions/feed merge --host and
-    // --device into a multi-host list; rejecting "conflicting" pairs would break
-    // `agents sessions --host a --device b` / `agents feed --host a --device b`.
+    // Commands with their own richer --device semantics must reach local commander
+    // directly. sessions/feed handle multi-host lists themselves; fall through so
+    // those flags reach the local action.
     if (OWN_HOST_COMMANDS.has(command))
         return false;
     // Placement, not routing: `teams add`/`teams create` read `--device`/`--devices`
-    // (and `--host`/`--hosts`) as WHERE to place a teammate / the team pool — the
+    // (and `--hosts`) as WHERE to place a teammate / the team pool — the
     // command itself always runs locally on the orchestrator. Bail before the
     // generic teams routing below so those flags reach the local action. Every
-    // other teams subcommand (`status`/`logs`/`stop`/…) keeps `--host` routing.
+    // other teams subcommand (`status`/`logs`/`stop`/…) keeps `--device` routing.
     // Find the subcommand = the first non-flag token AFTER `teams` (robust to any
     // leading global flags), then bail for the add/create aliases.
     if (command === 'teams') {
@@ -428,7 +449,7 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     // the `all` sentinel, which this module fans out generically. On `routines`,
     // a non-all `--devices` value is placement (which devices may run the routine).
     if (allArgs.includes('--hosts') && hostsFlag?.toLowerCase() !== 'all')
-        return false;
+        return false; // legacy plural sentinel; prefer --devices
     if (allArgs.includes('--devices')) {
         if (devicesFlag === undefined)
             return false; // malformed, let commander error
@@ -438,8 +459,8 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     }
     // 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,
+    // (`agents session resume --device box`) was answered with "does not support
+    // --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.
@@ -449,25 +470,21 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     if (!spec) {
         // Flag was accepted (no raw commander "unknown option") but this group has
         // no remote semantics — say so clearly instead of falling through.
-        console.error(chalk.red(`\`agents ${command}\` does not support --host/--device (no remote interpretation).`) +
-            chalk.gray(' Run without the flag, or use a host-routable group (repos, view, sync, teams, doctor, …).'));
-        process.exitCode = 1;
-        return true;
-    }
-    // Reject a conflicting --host/--device pair before either the fleet fan-out
-    // or single-target path runs. Equal values (e.g. both `all`) are allowed.
-    if (hostFlag && deviceFlag && hostFlag !== deviceFlag) {
-        console.error(chalk.red('Conflicting --host/--device values — pass just one.'));
+        console.error(chalk.red(`\`agents ${command}\` does not support --device (no remote interpretation).`) +
+            chalk.gray(' Run without the flag, or use a device-routable group (repos, view, sync, teams, doctor, …).'));
         process.exitCode = 1;
         return true;
     }
+    // Reject duplicate --device flags before either the fleet fan-out
+    // or single-target path runs. (Conflict detection: only --device exists now.)
+    // No conflict gate needed — a single canonical flag cannot conflict with itself.
     // Generic fleet fan-out for the `all` sentinel — before single-host resolution
     // so `all` is never treated as a literal hostname.
     if (fleetAll) {
         return runFleetPassthrough(command, allArgs, spec, opts);
     }
     // After the bailouts and fleet fan-out above, the only remaining path is a
-    // single-target --host/--device. Guard for the type checker: plural non-all
+    // single-target --device. Guard for the type checker: plural non-all
     // flags and bare flags were already handled.
     if (!hostName)
         return false;
@@ -489,10 +506,10 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     }
     // 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
+    // dnsName), not just machineId() — a `--device <self-dnsName>` used to slip past a
     // short-hostname-only check and self-SSH (RUSH-2114). Strip the routing flags
     // from process.argv so the local command never sees an unregistered
-    // `--host`/`--device` and dies with "unknown option".
+    // `--device` and dies with "unknown option".
     if (isSelfHost(hostName)) {
         const stripped = stripRoutingFlags(allArgs, STRIP_SPECS);
         process.argv = [process.argv[0], process.argv[1], ...stripped];
@@ -551,21 +568,21 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     return true;
 }
 /**
- * `--host` passthrough for a **standalone binary** whose command name is fixed by
+ * `--device` 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
+ * `agents browser … --device <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
+ * this it dropped `--device` entirely (commander errored with `unknown option
+ * '--device'`). 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`.
+ * standalone commander program parses cleanly and never sees an unknown `--device`.
  * 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.

package/dist/lib/hosts/providers/devices.d.ts

@@ -5,7 +5,7 @@
  * registry.json) into the host pool behind the same `HostProvider` seam as
  * `local` — the "tailscale provider" fast-follow named in docs/hosts.md. With
  * it, a machine registered once via `agents devices sync` becomes a resolvable
- * `--host`/`--device` dispatch target, participates in capability routing, and
+ * `--device`/`--device` dispatch target, participates in capability routing, and
  * is enumerable by target pickers — not just resolvable by exact name.
  *
  * Password-auth devices are listed (the pool stays honest about what exists)

package/dist/lib/hosts/providers/devices.js

@@ -5,7 +5,7 @@
  * registry.json) into the host pool behind the same `HostProvider` seam as
  * `local` — the "tailscale provider" fast-follow named in docs/hosts.md. With
  * it, a machine registered once via `agents devices sync` becomes a resolvable
- * `--host`/`--device` dispatch target, participates in capability routing, and
+ * `--device`/`--device` dispatch target, participates in capability routing, and
  * is enumerable by target pickers — not just resolvable by exact name.
  *
  * Password-auth devices are listed (the pool stays honest about what exists)

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

@@ -1,7 +1,7 @@
 /**
  * Reconcile a local host-task record against the remote run's ground truth.
  *
- * A detached `--host` run outlives the local follower: it keeps running and
+ * A detached `--device` run outlives the local follower: it keeps running and
  * writes its exit code to `<id>.exit` on the host even if the laptop sleeps or
  * the SSH connection drops mid-follow. When that happens the local record is
  * left at `status:'running'` forever, because the only path that finalizes it

package/dist/lib/hosts/reconcile.js

@@ -1,7 +1,7 @@
 /**
  * Reconcile a local host-task record against the remote run's ground truth.
  *
- * A detached `--host` run outlives the local follower: it keeps running and
+ * A detached `--device` run outlives the local follower: it keeps running and
  * writes its exit code to `<id>.exit` on the host even if the laptop sleeps or
  * the SSH connection drops mid-follow. When that happens the local record is
  * left at `status:'running'` forever, because the only path that finalizes it

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

@@ -99,7 +99,7 @@ export declare function remoteExitNotice(sessionId: string, host: string): strin
  * {@link REMOTE_EXIT_255_REMAPPED} before the wrapper exits — see the file
  * header for why. Every other code (0, 1, …) passes through unchanged. This
  * carries no PATH bootstrap of its own — `ensureHostReady`/`readyProbe` already
- * gates every `--host` dispatch on `bash -lc 'agents --version'` succeeding
+ * gates every `--device` dispatch on `bash -lc 'agents --version'` succeeding
  * before a run is attempted at all, so the peer's login shell resolving `agents`
  * is an established precondition here too. Pure string-building, so it is
  * unit-tested without SSH (and, since the constructed script is ordinary POSIX,

package/dist/lib/hosts/reconnect.js

@@ -1,5 +1,5 @@
 /**
- * Auto-reconnect for an interactive `agents run --device/--host` session whose
+ * Auto-reconnect for an interactive `agents run --device` session whose
  * SSH link dropped.
  *
  * A remote interactive agent runs in a DETACHED tmux session on the peer (see
@@ -174,7 +174,7 @@ export function remoteExitNotice(sessionId, host) {
  * {@link REMOTE_EXIT_255_REMAPPED} before the wrapper exits — see the file
  * header for why. Every other code (0, 1, …) passes through unchanged. This
  * carries no PATH bootstrap of its own — `ensureHostReady`/`readyProbe` already
- * gates every `--host` dispatch on `bash -lc 'agents --version'` succeeding
+ * gates every `--device` dispatch on `bash -lc 'agents --version'` succeeding
  * before a run is attempted at all, so the peer's login shell resolving `agents`
  * is an established precondition here too. Pure string-building, so it is
  * unit-tested without SSH (and, since the constructed script is ordinary POSIX,

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

@@ -58,7 +58,7 @@ export interface MatchHostOptions {
     resolveAuto?: () => DeviceAffinityPlan;
 }
 /**
- * The one place a `--host` / `--device` token becomes a resolved host. Reads the
+ * The one place a `--device` / `--device` token becomes a resolved host. Reads the
  * devices registry, the agents.yaml overlay, and ssh_config, and merges them
  * per-field (see {@link deviceHost}). One grammar for every caller: `name`,
  * `user@name`, a tailnet FQDN, an ssh_config alias, and a literal `user@host`
@@ -77,8 +77,8 @@ export declare function matchHost(name: string, opts?: MatchHostOptions): Promis
  * with it). Provider order still decides the base row (`local` first). */
 export declare function listAllHosts(): Promise<Host[]>;
 /**
- * Resolve a `--host`/`--device` token for DISPATCH — the shape every offload
- * caller consumes (`run --host`, the generic passthrough, teams placement, the
+ * Resolve a `--device`/`--device` token for DISPATCH — the shape every offload
+ * caller consumes (`run --device`, the generic passthrough, teams placement, the
  * cloud host provider, doctor, funnel, remote secrets). Grammar and merge come
  * from {@link matchHost}; on top, this layer applies the device-only dispatch
  * refusals so they hold even when an inline overlay shadows the device:
@@ -88,11 +88,11 @@ export declare function listAllHosts(): Promise<Host[]>;
  *   - an addressless device has nothing to dial.
  *
  * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`,
- * e.g. `--host gpu`) stays reachable, and an ad-hoc `user@host` still resolves.
+ * e.g. `--device gpu`) stays reachable, and an ad-hoc `user@host` still resolves.
  */
 export declare function resolveHost(name: string): Promise<Host | null>;
 /**
- * Resolve a host by capability tag (e.g. `--host gpu`). Returns the single
+ * Resolve a host by capability tag (e.g. `--device gpu`). Returns the single
  * matching host, or throws on 0 or >1 matches unless `any` is set (then first).
  */
 export declare function resolveHostByCap(cap: string, any?: boolean): Promise<Host>;

package/dist/lib/hosts/registry.js

@@ -141,7 +141,7 @@ function literalHost(token, host, user) {
     };
 }
 /**
- * The one place a `--host` / `--device` token becomes a resolved host. Reads the
+ * The one place a `--device` / `--device` token becomes a resolved host. Reads the
  * devices registry, the agents.yaml overlay, and ssh_config, and merges them
  * per-field (see {@link deviceHost}). One grammar for every caller: `name`,
  * `user@name`, a tailnet FQDN, an ssh_config alias, and a literal `user@host`
@@ -236,8 +236,8 @@ export async function listAllHosts() {
     return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
- * Resolve a `--host`/`--device` token for DISPATCH — the shape every offload
- * caller consumes (`run --host`, the generic passthrough, teams placement, the
+ * Resolve a `--device`/`--device` token for DISPATCH — the shape every offload
+ * caller consumes (`run --device`, the generic passthrough, teams placement, the
  * cloud host provider, doctor, funnel, remote secrets). Grammar and merge come
  * from {@link matchHost}; on top, this layer applies the device-only dispatch
  * refusals so they hold even when an inline overlay shadows the device:
@@ -247,7 +247,7 @@ export async function listAllHosts() {
  *   - an addressless device has nothing to dial.
  *
  * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`,
- * e.g. `--host gpu`) stays reachable, and an ad-hoc `user@host` still resolves.
+ * e.g. `--device gpu`) stays reachable, and an ad-hoc `user@host` still resolves.
  */
 export async function resolveHost(name) {
     const host = await matchHost(name);
@@ -267,7 +267,7 @@ export async function resolveHost(name) {
     return host;
 }
 /**
- * Resolve a host by capability tag (e.g. `--host gpu`). Returns the single
+ * Resolve a host by capability tag (e.g. `--device gpu`). Returns the single
  * matching host, or throws on 0 or >1 matches unless `any` is set (then first).
  */
 export async function resolveHostByCap(cap, any = false) {

package/dist/lib/hosts/remote-cmd.d.ts

@@ -1,5 +1,5 @@
 /**
- * Pure argv helpers for `--host` passthrough — build the remote `agents …`
+ * Pure argv helpers for `--device` passthrough — build the remote `agents …`
  * invocation and strip the local-only routing flags before forwarding.
  *
  * Kept free of any SSH/process side effects so the two-layer quoting and the
@@ -13,7 +13,7 @@ export interface StripSpec {
     long: string;
     /** Optional single-letter short form without the dash, e.g. `H`. */
     short?: string;
-    /** True when the flag takes a following value token (`--host <name>`). */
+    /** True when the flag takes a following value token (`--device <name>`). */
     takesValue: boolean;
 }
 /**
@@ -26,14 +26,13 @@ export interface StripSpec {
  */
 export declare function stripRoutingFlags(args: string[], specs: StripSpec[]): string[];
 /**
- * The routing flags every `--host`-capable command shares. `--device` is a
- * first-class alias of `--host` (the device registry is the source of truth for
- * machine identity — see `agents devices`), mirroring `agents run --device`.
- * Both are stripped before forwarding so the alias never leaks to the remote
- * binary (which would re-trigger routing).
+ * The routing flags every `--device`-capable command shares. Stripped before
+ * forwarding so the flag never leaks to the remote binary (which would
+ * re-trigger routing). `--host`/`-H` are kept for backward-compat strip only
+ * (they are no longer user-facing routing flags).
  */
 export declare const HOST_ROUTING_SPECS: StripSpec[];
-/** How one `agents run` option behaves when the run is offloaded with `--host`. */
+/** How one `agents run` option behaves when the run is offloaded with `--device`. */
 export type RunOptionForwarding = 
 /** Appended to the remote `agents run` argv — same behavior local or remote. */
 'forward'
@@ -42,7 +41,7 @@ export type RunOptionForwarding =
 /** Consumed by the dispatching side (routing, follow rendering, cwd portability). */
  | 'local-only';
 /**
- * The forwarding contract for `agents run … --host`: every option of the `run`
+ * The forwarding contract for `agents run … --device`: every option of the `run`
  * command is classified here, keyed by its commander attribute name. A
  * commander-introspection test (run-forwarding.test.ts) fails when a run
  * option is missing from this table, so a new option can never silently drop
@@ -161,7 +160,7 @@ export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
 /**
  * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a
  * Windows remote: a `powershell -NoProfile -EncodedCommand <base64>` call. The
- * Windows counterpart of `bash -lc '<...>'`, shared by every `--host` site.
+ * Windows counterpart of `bash -lc '<...>'`, shared by every `--device` site.
  */
 export declare function buildWindowsAgentsCommand(cmd: WindowsAgentsCommand): string;
 /**
@@ -180,4 +179,5 @@ export declare function buildWindowsAgentsCommand(cmd: WindowsAgentsCommand): st
  */
 export declare function buildWindowsStdinImportCommand(bundle: string, opts?: {
     force?: boolean;
+    policyNever?: boolean;
 }): string;