@phnx-labs/agents-cli 1.20.31 → 1.20.33

package/dist/lib/devices/pending.js

@@ -0,0 +1,103 @@
+/**
+ * "Pending device" sentinels.
+ *
+ * When the daemon's tailscale probe finds a node that is neither registered nor
+ * ignored, it drops a sentinel file under ~/.agents/.cache/state/devices-pending/
+ * — the same filesystem-signal pattern the attention hook uses for the menu bar.
+ * The Swift helper polls that dir every 10s and renders a "NEW DEVICES" section
+ * with Register / Ignore. The file NAME is the device name; the file CONTENT is
+ * the platform (one line), so the tray can show "zion (macos)" without opening
+ * the registry.
+ *
+ * The daemon owns writes (reconcile to match the current pending set); the CLI
+ * `agents devices register|ignore` clears a single sentinel the moment the user
+ * acts, so the badge updates immediately instead of waiting for the next probe.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getDevicesPendingDir } from '../state.js';
+/** Device-name sentinels must be safe filenames (no path traversal). The device
+ * name charset is already the ssh-alias set, but guard defensively. */
+function isSafeName(name) {
+    return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+/**
+ * Make the sentinel dir exactly match `pending`: create a file per pending
+ * device (content = platform), and delete any leftover sentinel whose device is
+ * no longer pending (it got registered, ignored, or left the tailnet). Best-
+ * effort — a filesystem error here must never crash the daemon, so callers pass
+ * this through their existing try/catch.
+ */
+export function reconcilePendingSentinels(pending) {
+    const dir = getDevicesPendingDir();
+    const want = new Map(pending.filter((p) => isSafeName(p.name)).map((p) => [p.name, p.platform]));
+    // Whole body is best-effort: a filesystem error here must never propagate into
+    // the daemon loop or `agents sync`. The top-level mkdir/readdir are guarded
+    // too, so no caller needs its own try/catch.
+    let existing;
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        existing = fs.readdirSync(dir).filter((n) => !n.startsWith('.'));
+    }
+    catch {
+        return;
+    }
+    // Remove sentinels that are no longer pending.
+    for (const name of existing) {
+        if (!want.has(name)) {
+            try {
+                fs.unlinkSync(path.join(dir, name));
+            }
+            catch { /* already gone */ }
+        }
+    }
+    // Write/refresh the sentinels that should exist.
+    for (const [name, platform] of want) {
+        const p = path.join(dir, name);
+        const body = `${platform}\n`;
+        // Only write when missing or changed, to avoid needless mtime churn.
+        let current = null;
+        try {
+            current = fs.readFileSync(p, 'utf-8');
+        }
+        catch {
+            current = null;
+        }
+        if (current !== body) {
+            try {
+                fs.writeFileSync(p, body);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/** Remove one device's pending sentinel (after the user registers or ignores it).
+ * No-op if it doesn't exist. */
+export function clearPendingSentinel(name) {
+    if (!isSafeName(name))
+        return;
+    try {
+        fs.unlinkSync(path.join(getDevicesPendingDir(), name));
+    }
+    catch { /* already gone */ }
+}
+/** Read the current pending sentinels (name + platform). Used by tests and any
+ * TS-side consumer; the menu-bar helper reads the dir directly in Swift. */
+export function readPendingSentinels() {
+    const dir = getDevicesPendingDir();
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => !n.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+    return names.map((name) => {
+        let platform = 'unknown';
+        try {
+            platform = fs.readFileSync(path.join(dir, name), 'utf-8').trim() || 'unknown';
+        }
+        catch { /* keep default */ }
+        return { name, platform };
+    });
+}

package/dist/lib/devices/sync.d.ts

@@ -1,11 +1,22 @@
 import { type TailscaleNode } from './tailscale.js';
+import type { PendingDevice } from './pending.js';
+/**
+ * bootstrap — register every non-ignored node (opt-out). First-run `agents
+ *   setup` and manual `agents devices sync`, so the fleet is usable out of box.
+ * refresh — only refresh reachability of already-registered nodes; a brand-new
+ *   node is NOT auto-added, it is surfaced as `pending` for the user to approve
+ *   (opt-in). Ongoing autosync and the daemon probe use this, so newcomers flow
+ *   through the menu-bar "NEW DEVICES → Register / Ignore" gate instead of
+ *   silently landing in the registry.
+ */
+export type DeviceSyncMode = 'bootstrap' | 'refresh';
 export interface DeviceSyncResult {
     /** False when discovery could not run (e.g. tailscale absent) in soft mode. */
     ok: boolean;
     /** Number of tailscale nodes upserted into the registry. */
     synced: number;
-    /** Node names discovered but neither registered-before nor ignored. */
-    pending: string[];
+    /** Nodes discovered but neither registered-before nor ignored (name+platform). */
+    pending: PendingDevice[];
     /** Populated when ok is false: why discovery was skipped. */
     reason?: string;
 }
@@ -15,6 +26,13 @@ export interface DeviceSyncResult {
  * flag matrix is unit-testable without a live tailnet.
  */
 export declare function computePendingDevices(nodes: TailscaleNode[], registered: Iterable<string>, ignored: Iterable<string>): string[];
+/**
+ * Which discovered nodes to upsert this run — the mode-defining decision, pure
+ * so it is unit-testable without a tailnet. Ignored nodes are always skipped.
+ * In `refresh` mode a node that isn't already registered is skipped too (it
+ * stays pending for approval); `bootstrap` includes every non-ignored node.
+ */
+export declare function selectNodesToUpsert(nodes: TailscaleNode[], registered: Set<string>, ignored: Set<string>, mode: DeviceSyncMode): TailscaleNode[];
 /**
  * Ingest `tailscale status --json` into the registry. In soft mode a missing
  * tailscale binary / unreachable daemon resolves to `{ ok: false }` instead of
@@ -24,6 +42,7 @@ export declare function computePendingDevices(nodes: TailscaleNode[], registered
  */
 export declare function runDeviceSync(opts?: {
     soft?: boolean;
+    mode?: DeviceSyncMode;
 }): Promise<DeviceSyncResult>;
 /**
  * The register/remove/ignore decision for the interactive curation picker.

package/dist/lib/devices/sync.js

@@ -28,6 +28,21 @@ export function computePendingDevices(nodes, registered, ignored) {
         .map((n) => n.name)
         .filter((name) => !known.has(name) && !skip.has(name));
 }
+/**
+ * Which discovered nodes to upsert this run — the mode-defining decision, pure
+ * so it is unit-testable without a tailnet. Ignored nodes are always skipped.
+ * In `refresh` mode a node that isn't already registered is skipped too (it
+ * stays pending for approval); `bootstrap` includes every non-ignored node.
+ */
+export function selectNodesToUpsert(nodes, registered, ignored, mode) {
+    return nodes.filter((n) => {
+        if (ignored.has(n.name))
+            return false;
+        if (mode === 'refresh' && !registered.has(n.name))
+            return false;
+        return true;
+    });
+}
 /**
  * Ingest `tailscale status --json` into the registry. In soft mode a missing
  * tailscale binary / unreachable daemon resolves to `{ ok: false }` instead of
@@ -36,6 +51,7 @@ export function computePendingDevices(nodes, registered, ignored) {
  * "new" means "not previously registered and not ignored".
  */
 export async function runDeviceSync(opts = {}) {
+    const mode = opts.mode ?? 'bootstrap';
     // Soft mode must be non-fatal for ANY failure, not just a missing tailscale:
     // a corrupted registry/ignore file (both throw by design), a disk error, or
     // registry lock contention (plausible when many agents SessionStart-autosync
@@ -44,18 +60,18 @@ export async function runDeviceSync(opts = {}) {
     try {
         const nodes = parseTailscaleStatus(tailscaleStatusJson());
         const [registeredBefore, ignored] = await Promise.all([loadDevices(), loadIgnored()]);
-        const pending = computePendingDevices(nodes, Object.keys(registeredBefore), ignored);
-        // Register/refresh every node the user has NOT dismissed. Skipping ignored
-        // nodes is what makes the "register all" default safe: a phone or someone
-        // else's laptop the user once dismissed never silently comes back.
-        let synced = 0;
-        for (const node of nodes) {
-            if (ignored.has(node.name))
-                continue;
+        const registered = new Set(Object.keys(registeredBefore));
+        const pendingNames = computePendingDevices(nodes, registered, ignored);
+        const byName = new Map(nodes.map((n) => [n.name, n]));
+        const pending = pendingNames.map((name) => ({
+            name,
+            platform: byName.get(name)?.platform ?? 'unknown',
+        }));
+        const toUpsert = selectNodesToUpsert(nodes, registered, ignored, mode);
+        for (const node of toUpsert) {
             await upsertDevice(node.name, nodeToDeviceInput(node));
-            synced++;
         }
-        return { ok: true, synced, pending };
+        return { ok: true, synced: toUpsert.length, pending };
     }
     catch (err) {
         if (opts.soft) {

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

@@ -1,13 +1,20 @@
 /**
- * Dispatch a headless agent run onto a host over SSH.
+ * Dispatch a headless `agents …` command onto a host over SSH.
  *
- * The run is launched detached (`nohup … &`) writing combined output to a 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 agent's process/thread/file fan-out happens on the host, not the laptop.
+ * The command is launched detached (`nohup … &`) writing combined output to a
+ * 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
+ * same core so a remote team supervisor keeps running after you disconnect.
  */
 import type { Host } from './types.js';
 import { type HostTask } from './tasks.js';
+export interface DispatchResult {
+    task: HostTask;
+    /** Exit code when followed; undefined when detached (--no-follow). */
+    exitCode?: number;
+}
 export interface DispatchOptions {
     agent: string;
     prompt: string;
@@ -18,9 +25,19 @@ export interface DispatchOptions {
     follow?: boolean;
     timeoutMs?: number;
 }
-export interface DispatchResult {
-    task: HostTask;
-    /** Exit code when followed; undefined when detached (--no-follow). */
-    exitCode?: number;
-}
+/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;
+export interface CommandDispatchOptions {
+    /** `agents …` args (command name first), already stripped of routing flags. */
+    forwardedArgs: string[];
+    remoteCwd?: string;
+    follow?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Dispatch an arbitrary long-running `agents <command>` onto a host detached —
+ * used for `teams start --watch --host`, whose supervisor must outlive the SSH
+ * connection. Reachability is assumed (the caller has already resolved the host);
+ * a launch failure surfaces the remote stderr.
+ */
+export declare function dispatchAgentsCommand(host: Host, opts: CommandDispatchOptions): Promise<DispatchResult>;

package/dist/lib/hosts/dispatch.js

@@ -1,10 +1,12 @@
 /**
- * Dispatch a headless agent run onto a host over SSH.
+ * Dispatch a headless `agents …` command onto a host over SSH.
  *
- * The run is launched detached (`nohup … &`) writing combined output to a 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 agent's process/thread/file fan-out happens on the host, not the laptop.
+ * The command is launched detached (`nohup … &`) writing combined output to a
+ * 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
+ * same core so a remote team supervisor keeps running after you disconnect.
  */
 import { randomUUID } from 'crypto';
 import { sshExec, shellQuote } from '../ssh-exec.js';
@@ -16,25 +18,22 @@ import { followHostTask } from './progress.js';
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
 const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
-export async function dispatchToHost(host, opts) {
-    const target = sshTargetFor(host);
-    const { warnings } = ensureHostReady(host, { agent: opts.agent });
-    for (const w of warnings)
-        process.stderr.write(`[hosts] warning: ${w}\n`);
+/**
+ * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
+ * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
+ * so the nohup/exit-file/offset-tail machinery lives in exactly one place.
+ */
+async function launchDetached(host, target, opts) {
     const id = randomUUID().slice(0, 8);
     const remoteLog = `${REMOTE_DIR}/${id}.log`;
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
     // Inner command run under a login shell so PATH resolves `agents`.
-    const runParts = ['agents', 'run', shellQuote(opts.agent), shellQuote(opts.prompt), '--quiet'];
-    if (opts.mode)
-        runParts.push('--mode', shellQuote(opts.mode));
-    if (opts.model)
-        runParts.push('--model', shellQuote(opts.model));
+    const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
     const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
-    const inner = `${cwd}${runParts.join(' ')} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
+    const inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
     // Outer: ensure dir, launch detached under bash -lc, print the PID.
     const launch = `mkdir -p ${REMOTE_DIR}; nohup bash -lc ${shellQuote(inner)} >/dev/null 2>&1 & echo $!`;
-    const res = sshExec(target, launch, { timeoutMs: 30000 });
+    const res = sshExec(target, launch, { timeoutMs: 30000, multiplex: true });
     if (res.code !== 0) {
         throw new Error(`Failed to launch on "${host.name}": ${(res.stderr || res.stdout).trim() || 'ssh error'}`);
     }
@@ -43,8 +42,8 @@ export async function dispatchToHost(host, opts) {
         id,
         host: host.name,
         target,
-        agent: opts.agent,
-        prompt: opts.prompt,
+        agent: opts.agentLabel,
+        prompt: opts.promptLabel,
         pid: Number.isFinite(pid) ? pid : undefined,
         remoteLog,
         remoteExit,
@@ -69,3 +68,40 @@ export async function dispatchToHost(host, opts) {
     });
     return { task: finished ?? task, exitCode };
 }
+/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
+export async function dispatchToHost(host, opts) {
+    const target = sshTargetFor(host);
+    const { warnings } = ensureHostReady(host, { agent: opts.agent });
+    for (const w of warnings)
+        process.stderr.write(`[hosts] warning: ${w}\n`);
+    const forwardedArgs = ['run', opts.agent, opts.prompt, '--quiet'];
+    if (opts.mode)
+        forwardedArgs.push('--mode', opts.mode);
+    if (opts.model)
+        forwardedArgs.push('--model', opts.model);
+    return launchDetached(host, target, {
+        forwardedArgs,
+        remoteCwd: opts.remoteCwd,
+        follow: opts.follow,
+        timeoutMs: opts.timeoutMs,
+        agentLabel: opts.agent,
+        promptLabel: opts.prompt,
+    });
+}
+/**
+ * Dispatch an arbitrary long-running `agents <command>` onto a host detached —
+ * used for `teams start --watch --host`, whose supervisor must outlive the SSH
+ * connection. Reachability is assumed (the caller has already resolved the host);
+ * a launch failure surfaces the remote stderr.
+ */
+export async function dispatchAgentsCommand(host, opts) {
+    const target = sshTargetFor(host);
+    return launchDetached(host, target, {
+        forwardedArgs: opts.forwardedArgs,
+        remoteCwd: opts.remoteCwd,
+        follow: opts.follow,
+        timeoutMs: opts.timeoutMs,
+        agentLabel: opts.forwardedArgs[0] ?? 'agents',
+        promptLabel: opts.forwardedArgs.join(' '),
+    });
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Shared `--host` option registrar. Every command that can run on a remote host
+ * 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`.
+ *
+ * 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.
+ */
+import type { Command } from 'commander';
+/** Attach the standard `--host` flag family to a command and return it (chainable). */
+export declare function addHostOption(cmd: Command): Command;

package/dist/lib/hosts/option.js

@@ -0,0 +1,19 @@
+/**
+ * Shared `--host` option registrar. Every command that can run on a remote host
+ * 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`.
+ *
+ * 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.
+ */
+/** Attach the standard `--host` flag family to a command and return it (chainable). */
+export function addHostOption(cmd) {
+    return cmd
+        .option('-H, --host <name>', 'Run this command on a registered host (or user@host) over SSH instead of locally. See `agents hosts`.')
+        .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
+        .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.');
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Generic `--host` passthrough — the single choke point that runs an allowlisted
+ * `agents <command>` on a remote host instead of locally, so read-only and
+ * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
+ * and the team lifecycle (`teams …`) all gain remote support with no per-command
+ * code. Called once from `index.ts` before commander parses; returns `true` when
+ * it handled the invocation (the local command must then NOT run).
+ *
+ * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
+ * choke point already used everywhere, and it gives auth + encryption + host-key
+ * trust for free. Read-only commands stream synchronously (`sshStream`); the one
+ * long-running case — `teams start --watch` — dispatches detached so the remote
+ * supervisor outlives a dropped connection.
+ *
+ * `run` and `sessions` are deliberately absent from the table below: they own
+ * richer `--host` handling in their own command actions (detached run dispatch;
+ * multi-host session fan-out) and must fall through to it.
+ */
+/** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
+export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
+/**
+ * Route `agents <command> … --host <name>` to a remote if the command is
+ * host-routable and a `--host` was given. Returns `false` (run locally) when
+ * there is no `--host`, the command isn't in the table, or the target is this
+ * very machine.
+ *
+ * @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[]): Promise<boolean>;

package/dist/lib/hosts/passthrough.js

@@ -0,0 +1,141 @@
+/**
+ * Generic `--host` passthrough — the single choke point that runs an allowlisted
+ * `agents <command>` on a remote host instead of locally, so read-only and
+ * config commands (`view`, `usage`, `cost`, `doctor`, `inspect`, `list`, `sync`)
+ * and the team lifecycle (`teams …`) all gain remote support with no per-command
+ * code. Called once from `index.ts` before commander parses; returns `true` when
+ * it handled the invocation (the local command must then NOT run).
+ *
+ * Transport is SSH (via `ssh-exec.ts`), never a daemon: SSH is the one hardened
+ * choke point already used everywhere, and it gives auth + encryption + host-key
+ * trust for free. Read-only commands stream synchronously (`sshStream`); the one
+ * long-running case — `teams start --watch` — dispatches detached so the remote
+ * supervisor outlives a dropped connection.
+ *
+ * `run` and `sessions` are deliberately absent from the table below: they own
+ * richer `--host` handling in their own command actions (detached run dispatch;
+ * multi-host session fan-out) and must fall through to it.
+ */
+import chalk from 'chalk';
+import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
+import { resolveHost, resolveHostByCap } from './registry.js';
+import { sshTargetFor } from './types.js';
+import { dispatchAgentsCommand } from './dispatch.js';
+import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
+import { machineId } from '../session/sync/config.js';
+const REMOTE_PASSTHROUGH = {
+    view: {},
+    usage: {},
+    cost: {},
+    doctor: {},
+    inspect: {},
+    list: {},
+    sync: { nonInteractive: ['--yes'] },
+    teams: {},
+};
+/** `--no-tty` is stripped like the routing flags but carries no value. */
+const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];
+/** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
+export function flagValue(args, long, short) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === `--${long}` || (short && a === `-${short}`))
+            return args[i + 1];
+        if (a.startsWith(`--${long}=`))
+            return a.slice(long.length + 3);
+        if (short && a.startsWith(`-${short}=`))
+            return a.slice(short.length + 2);
+        if (short && new RegExp(`^-${short}(.+)`).test(a))
+            return a.slice(2);
+    }
+    return undefined;
+}
+/** Synthesize a `Host` for a raw `user@host` / bare-alias target (not enrolled). */
+function syntheticHost(target) {
+    const at = target.indexOf('@');
+    if (at !== -1) {
+        return { name: target, provider: 'local', source: 'inline', user: target.slice(0, at), address: target.slice(at + 1) };
+    }
+    // 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. */
+async function resolveTargetHost(name, any) {
+    const enrolled = await resolveHost(name);
+    if (enrolled)
+        return enrolled;
+    try {
+        return await resolveHostByCap(name, any);
+    }
+    catch (e) {
+        // "Multiple hosts tagged …" is actionable — surface it. "No host tagged" falls
+        // through to treating the value as a literal ssh target.
+        if (e instanceof Error && e.message.startsWith('Multiple hosts'))
+            throw e;
+    }
+    assertValidSshTarget(name); // rejects injection / flag-smuggling before it reaches ssh
+    return syntheticHost(name);
+}
+/**
+ * Route `agents <command> … --host <name>` to a remote if the command is
+ * host-routable and a `--host` was given. Returns `false` (run locally) when
+ * there is no `--host`, the command isn't in the table, or the target is this
+ * very machine.
+ *
+ * @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) {
+    const spec = REMOTE_PASSTHROUGH[command];
+    if (!spec)
+        return false;
+    const hostName = flagValue(allArgs, 'host', 'H');
+    if (!hostName)
+        return false;
+    // Running against your own machine is just a local run — skip the SSH round-trip.
+    // `machineId()` is the same self-identifier the device registry and session
+    // sync use (lowercased short hostname); compare case-insensitively.
+    if (hostName.toLowerCase() === machineId())
+        return false;
+    const remoteCwd = flagValue(allArgs, 'remote-cwd');
+    const any = allArgs.includes('--any');
+    let host;
+    try {
+        host = await resolveTargetHost(hostName, any);
+    }
+    catch (e) {
+        console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+        process.exitCode = 1;
+        return true;
+    }
+    const target = sshTargetFor(host);
+    // Interactive only when our own stdout is a terminal and the caller didn't opt
+    // out — otherwise force the command's non-interactive path so no half-drawn
+    // picker is piped into a file or another program.
+    const interactive = !!process.stdout.isTTY && !allArgs.includes('--no-tty');
+    let forwarded = stripRoutingFlags(allArgs, STRIP_SPECS);
+    if (!interactive && spec.nonInteractive)
+        forwarded = [...forwarded, ...spec.nonInteractive];
+    // The one long-running case: keep the remote team supervisor alive past a
+    // disconnect by dispatching it detached (nohup), still streaming live.
+    const isWatchedTeamStart = command === 'teams' && forwarded[1] === 'start' && forwarded.includes('--watch');
+    if (isWatchedTeamStart) {
+        try {
+            const { exitCode } = await dispatchAgentsCommand(host, { forwardedArgs: forwarded, remoteCwd });
+            process.exitCode = exitCode && exitCode > 0 ? exitCode : 0;
+        }
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exitCode = 1;
+        }
+        return true;
+    }
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd);
+    const code = sshStream(target, remoteCmd, { tty: 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;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Pure argv helpers for `--host` 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
+ * flag-stripping edge cases (glued short forms, `=value`, variadic) are unit
+ * testable without a live host. The transport itself lives in `ssh-exec.ts`
+ * (`sshExec`/`sshStream`); orchestration lives in `passthrough.ts`.
+ */
+/** A flag to strip from a forwarded argv, with whether it consumes a value. */
+export interface StripSpec {
+    /** Long form without leading dashes, e.g. `host`, `remote-cwd`. */
+    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>`). */
+    takesValue: boolean;
+}
+/**
+ * Remove routing flags (and their values) from a command's args, leaving the
+ * rest untouched and in order so they forward verbatim to the remote binary.
+ * Handles every form commander accepts: `--host h`, `--host=h`, `-H h`, `-H=h`,
+ * and the glued short form `-Hh`.
+ *
+ * @param args the command's args (already past the command name).
+ */
+export declare function stripRoutingFlags(args: string[], specs: StripSpec[]): string[];
+/** The routing flags every `--host`-capable command shares. */
+export declare const HOST_ROUTING_SPECS: StripSpec[];
+/**
+ * Build the single command string for `ssh <target> <cmd>`. The forwarded args
+ * are quoted for the inner login shell, then the whole `agents …` invocation is
+ * quoted again so it survives `bash -lc <...>` — `bash -lc` so the remote login
+ * PATH resolves `agents`. An optional `cd` runs first for `--remote-cwd`.
+ */
+export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string): string;