@phnx-labs/agents-cli 1.22.38 → 1.22.40

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

@@ -1,28 +1,48 @@
 /**
- * Credential provisioning for `agents run --host --copy-creds`.
+ * Credential provisioning for `agents run --device --copy-creds`.
  *
- * Reuses the lease flow's runtime detection + credential-script builder so a
- * persistent host can boot logged-in the same way an ephemeral leased box does.
- * Unlike `--lease`, a host is persistent, so copying tokens is strictly opt-in
- * per run and we shred the files after the run to bound the credential window.
+ * `--copy-creds` USED TO copy each signed-in runtime's native login to a
+ * persistent host — the Claude OAuth token (`.claude/.credentials.json`) plus
+ * codex/grok/gemini `auth.json`-style files — so the box booted logged-in. Every
+ * one of those is a **rotating, interactive OAuth / session credential**, and
+ * copying it between devices is forbidden by the fleet-auth contract
+ * (`docs/specifications.md` SING-1b, `docs/credential-management.md` invariant 2):
+ * a shared refresh token rotates server-side on the next refresh and invalidates
+ * every other copy — the "droid collapsed 10 boxes to 1 overnight" failure.
+ *
+ * So this module no longer serializes native logins at all. It REFUSES the
+ * transfer and steers to the portable path — a long-lived, non-rotating provider
+ * account (`agents accounts add` / `agents accounts sync`), whose bundle is
+ * policy-`never` and safe to reuse on many devices. That sync rides its own
+ * hardened SSH transport (RUSH-2527); it never touches this path.
  */
 import type { AgentId } from '../types.js';
-import { type DetectedRuntime } from '../crabbox/runtimes.js';
+import type { DetectedRuntime } from '../crabbox/runtimes.js';
+export { isNativeOAuthRuntime, nativeOAuthTransferRefusal } from '../crabbox/runtimes.js';
 export interface HostCredentials {
     runtimes: AgentId[];
     detected: DetectedRuntime[];
     claudeCredentialsJson?: string | null;
 }
 /**
- * Build the setup (write credential files) and teardown (shred them) scripts for
- * a host run. Returns shell snippets meant to be run on the remote host.
+ * Build the setup/teardown scripts for a `--copy-creds` host run.
+ *
+ * Every runtime `--copy-creds` handles is a native OAuth / session login, so this
+ * REFUSES rather than serialize one across the wire (SING-1b) — it throws with the
+ * concrete `agents accounts` steer. The refusal happens BEFORE anything is
+ * serialized, so a native credential can never reach a remote-write script. An
+ * empty runtime set is a no-op (nothing to provision, nothing forbidden).
  */
 export declare function buildHostCredentialScript(opts: HostCredentials): {
     setup: string;
     teardown: string;
 };
 /**
- * Wrap a remote command so credentials are written before it runs and shredded
- * after it exits, regardless of success or failure.
+ * Wrap a remote command with credential setup/teardown for a `--copy-creds` run.
+ *
+ * Delegates to {@link buildHostCredentialScript}, which now refuses to transfer a
+ * native OAuth login — so a `--copy-creds` run against a signed-in native runtime
+ * fails loudly here (before dispatch) with the `agents accounts sync` steer,
+ * rather than shipping a rotating token to another device.
  */
 export declare function wrapHostCommandWithCredentials(innerCommand: string, opts: HostCredentials): string;

package/dist/lib/hosts/credentials.js

@@ -1,37 +1,49 @@
 /**
- * Credential provisioning for `agents run --host --copy-creds`.
+ * Credential provisioning for `agents run --device --copy-creds`.
  *
- * Reuses the lease flow's runtime detection + credential-script builder so a
- * persistent host can boot logged-in the same way an ephemeral leased box does.
- * Unlike `--lease`, a host is persistent, so copying tokens is strictly opt-in
- * per run and we shred the files after the run to bound the credential window.
+ * `--copy-creds` USED TO copy each signed-in runtime's native login to a
+ * persistent host — the Claude OAuth token (`.claude/.credentials.json`) plus
+ * codex/grok/gemini `auth.json`-style files — so the box booted logged-in. Every
+ * one of those is a **rotating, interactive OAuth / session credential**, and
+ * copying it between devices is forbidden by the fleet-auth contract
+ * (`docs/specifications.md` SING-1b, `docs/credential-management.md` invariant 2):
+ * a shared refresh token rotates server-side on the next refresh and invalidates
+ * every other copy — the "droid collapsed 10 boxes to 1 overnight" failure.
+ *
+ * So this module no longer serializes native logins at all. It REFUSES the
+ * transfer and steers to the portable path — a long-lived, non-rotating provider
+ * account (`agents accounts add` / `agents accounts sync`), whose bundle is
+ * policy-`never` and safe to reuse on many devices. That sync rides its own
+ * hardened SSH transport (RUSH-2527); it never touches this path.
  */
-import { buildCredentialScript, CLAUDE_TOKEN_REMOTE } from '../crabbox/runtimes.js';
-function getShredPaths(runtimes) {
-    const pathsById = {
-        claude: ['.claude.json', CLAUDE_TOKEN_REMOTE],
-        codex: ['.codex/auth.json'],
-        gemini: ['.gemini/google_accounts.json'],
-        grok: ['.grok/auth.json'],
-    };
-    return runtimes.flatMap((id) => pathsById[id] ?? []);
-}
+import { isNativeOAuthRuntime, nativeOAuthTransferRefusal } from '../crabbox/runtimes.js';
+// The native-OAuth predicate + refusal are canonical in `crabbox/runtimes.ts`
+// (next to `LEASE_RUNTIMES`), so `--copy-creds` here and `--lease` there refuse
+// against exactly the same set. Re-export for this module's existing consumers.
+export { isNativeOAuthRuntime, nativeOAuthTransferRefusal } from '../crabbox/runtimes.js';
 /**
- * Build the setup (write credential files) and teardown (shred them) scripts for
- * a host run. Returns shell snippets meant to be run on the remote host.
+ * Build the setup/teardown scripts for a `--copy-creds` host run.
+ *
+ * Every runtime `--copy-creds` handles is a native OAuth / session login, so this
+ * REFUSES rather than serialize one across the wire (SING-1b) — it throws with the
+ * concrete `agents accounts` steer. The refusal happens BEFORE anything is
+ * serialized, so a native credential can never reach a remote-write script. An
+ * empty runtime set is a no-op (nothing to provision, nothing forbidden).
  */
 export function buildHostCredentialScript(opts) {
-    const setup = buildCredentialScript(opts.runtimes, opts.detected, {
-        claudeCredentialsJson: opts.claudeCredentialsJson,
-    });
-    const teardown = getShredPaths(opts.runtimes)
-        .map((p) => `rm -f "$HOME/${p}" 2>/dev/null || true`)
-        .join('\n');
-    return { setup, teardown };
+    const native = opts.runtimes.filter(isNativeOAuthRuntime);
+    if (native.length > 0) {
+        throw new Error(nativeOAuthTransferRefusal(native));
+    }
+    return { setup: '', teardown: '' };
 }
 /**
- * Wrap a remote command so credentials are written before it runs and shredded
- * after it exits, regardless of success or failure.
+ * Wrap a remote command with credential setup/teardown for a `--copy-creds` run.
+ *
+ * Delegates to {@link buildHostCredentialScript}, which now refuses to transfer a
+ * native OAuth login — so a `--copy-creds` run against a signed-in native runtime
+ * fails loudly here (before dispatch) with the `agents accounts sync` steer,
+ * rather than shipping a rotating token to another device.
  */
 export function wrapHostCommandWithCredentials(innerCommand, opts) {
     const { setup, teardown } = buildHostCredentialScript(opts);

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

@@ -5,7 +5,7 @@
  * remote log and its exit code to a sibling `.exit` file, so progress survives a
  * dropped connection (followed via offset-tail in progress.ts). This is the
  * offload win: the process/thread/file fan-out happens on the host, not the
- * laptop. `agents run` uses it; `agents teams start --watch --host` reuses the
+ * laptop. `agents run` uses it; `agents teams start --watch --device` reuses the
  * same core so a remote team supervisor keeps running after you disconnect.
  */
 import type { Host } from './types.js';
@@ -221,7 +221,7 @@ export declare function buildInteractiveRunForwardedArgs(opts: InteractiveDispat
  * tmux wrapping; the local machine is just the transport.
  */
 export declare function runInteractiveOnHost(host: Host, opts: InteractiveDispatchOptions): Promise<number>;
-/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
+/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --device` path). */
 export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;
 export interface CommandDispatchOptions {
     /** `agents …` args (command name first), already stripped of routing flags. */
@@ -232,7 +232,7 @@ export interface CommandDispatchOptions {
 }
 /**
  * Dispatch an arbitrary long-running `agents <command>` onto a host detached —
- * used for `teams start --watch --host`, whose supervisor must outlive the SSH
+ * used for `teams start --watch --device`, whose supervisor must outlive the SSH
  * connection. Reachability is assumed (the caller has already resolved the host);
  * a launch failure surfaces the remote stderr.
  */

package/dist/lib/hosts/dispatch.js

@@ -5,7 +5,7 @@
  * remote log and its exit code to a sibling `.exit` file, so progress survives a
  * dropped connection (followed via offset-tail in progress.ts). This is the
  * offload win: the process/thread/file fan-out happens on the host, not the
- * laptop. `agents run` uses it; `agents teams start --watch --host` reuses the
+ * laptop. `agents run` uses it; `agents teams start --watch --device` reuses the
  * same core so a remote team supervisor keeps running after you disconnect.
  */
 import { randomUUID } from 'crypto';
@@ -499,7 +499,7 @@ export async function runInteractiveOnHost(host, opts) {
         extraSshArgs: hostIdentityArgs(host),
     });
 }
-/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
+/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --device` path). */
 export async function dispatchToHost(host, opts) {
     const target = sshTargetFor(host);
     // Concrete agent@version pins fail loud before we print "Dispatched" and
@@ -524,7 +524,7 @@ export async function dispatchToHost(host, opts) {
 }
 /**
  * Dispatch an arbitrary long-running `agents <command>` onto a host detached —
- * used for `teams start --watch --host`, whose supervisor must outlive the SSH
+ * used for `teams start --watch --device`, whose supervisor must outlive the SSH
  * connection. Reachability is assumed (the caller has already resolved the host);
  * a launch failure surfaces the remote stderr.
  */

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

@@ -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,8 +7,8 @@
  * 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.
  */
 import type { Command } from 'commander';
-/** 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 declare function addHostOption(cmd: Command): Command;

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