@phnx-labs/agents-cli 1.20.64 → 1.20.66

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

@@ -0,0 +1,129 @@
+/**
+ * Shared types for the fleet profile-sync feature (`agents apply` / `ag apply`).
+ *
+ * `agents.yaml` gains an additive `fleet:` block that declares a *profile*: which
+ * agents every device should have installed, which config scopes to reconcile,
+ * and whether logins/tokens propagate. `apply` reconciles the live fleet to it.
+ *
+ * These types are the contract shared by the manifest parser (`manifest.ts`),
+ * the reconcile engine (`apply.ts`), the auth propagation (`auth-sync.ts`), and
+ * the command (`commands/apply.ts`). Runtime probe/diff shapes live here too so
+ * the pure diff can be unit-tested without SSH.
+ */
+/**
+ * How login/token state propagates to a device.
+ * - `sync` (default): push portable credentials where possible, surface the rest
+ *   as a manual login.
+ * - `skip`: probe/report only; take no login action.
+ * (A per-agent interactive `prompt` mode is intentionally not offered yet — it
+ * was removed rather than accepted as a silent no-op that behaves like `skip`.)
+ */
+export type FleetLoginMode = 'sync' | 'skip';
+/** Defaults applied to every targeted device unless a per-device entry overrides. */
+export interface FleetDefaults {
+    /** Agent specs to ensure installed, e.g. `['claude@latest', 'codex@latest']`. */
+    agents?: string[];
+    /** Config sync scopes to reconcile on each device, e.g. `['user']`. */
+    sync?: string[];
+    /** Login propagation strategy. Default `'sync'`. */
+    login?: FleetLoginMode;
+}
+/** Per-device override; any omitted field inherits from `defaults`. */
+export interface FleetDeviceOverride {
+    agents?: string[];
+    sync?: string[];
+    login?: FleetLoginMode;
+}
+/**
+ * The `fleet:` block as it appears in `agents.yaml` (or any `-f` file). `devices`
+ * is either the literal string `'all'` (every online registered device minus the
+ * source machine) or an explicit map of device-name -> override.
+ */
+export interface FleetManifest {
+    defaults?: FleetDefaults;
+    devices: 'all' | Record<string, FleetDeviceOverride>;
+}
+/**
+ * A device's desired state after merging defaults with its override and
+ * expanding `devices: all`. This is what the reconcile engine drives toward.
+ */
+export interface DeviceDesired {
+    /** Registered device name (from `agents devices`). */
+    device: string;
+    /** Resolved agent specs to ensure installed. */
+    agents: string[];
+    /** Config sync scopes. */
+    sync: string[];
+    /** Login propagation strategy for this device. */
+    login: FleetLoginMode;
+}
+/**
+ * What a probe found on one device. Populated from `readyProbe` plus an
+ * installed-agents listing; `reachable: false` short-circuits everything else.
+ */
+export interface DeviceProbe {
+    device: string;
+    reachable: boolean;
+    /** Platform of the device (`linux` | `macos` | `windows`), for login classification. */
+    platform?: string;
+    /** agents-cli version present on the device (undefined if not installed). */
+    cliVersion?: string;
+    /** Agent ids currently installed on the device. */
+    installedAgents: string[];
+    /** Reason string when `reachable` is false or the probe partially failed. */
+    note?: string;
+}
+/** One planned action against a device, in a single reconcile dimension. */
+export type FleetActionKind = 'install-cli' | 'upgrade-cli' | 'add-agent' | 'sync-config' | 'push-login' | 'needs-login';
+export interface FleetAction {
+    device: string;
+    kind: FleetActionKind;
+    /** Agent id for agent/login actions; undefined for cli/config actions. */
+    agent?: string;
+    /** Human, one-line description of the action. */
+    detail: string;
+}
+/**
+ * The full reconcile plan: per-device desired vs probed, plus the flat list of
+ * actions. Pure output of `diffFleet(desired, probes)` — drives both `--plan`
+ * rendering and the confirm prompt.
+ */
+export interface FleetPlan {
+    devices: DeviceDiff[];
+    actions: FleetAction[];
+}
+/** Per-device diff row rendered in the plan matrix. */
+export interface DeviceDiff {
+    device: string;
+    desired: DeviceDesired;
+    probe: DeviceProbe;
+    actions: FleetAction[];
+    /** Agents that must be logged in on the device but can't be propagated
+     * (source token is device-bound, e.g. macOS keychain). Surfaced, not faked. */
+    loginBlocked: string[];
+}
+/** A portable auth file captured from a source agent home, ready to propagate. */
+export interface AuthFilePayload {
+    /** Agent id this file belongs to. */
+    agent: string;
+    /** Path relative to the agent's config dir (or $HOME), reconstructed on target. */
+    rel: string;
+    /** File contents, base64. */
+    contentB64: string;
+    /** POSIX mode to restore (e.g. 0o600 for credentials). */
+    mode: number;
+}
+/** The plaintext we encrypt before shipping auth over the wire. */
+export interface AuthBundle {
+    /** Schema version for forward-compat. */
+    v: 1;
+    /** Source machine name the snapshot was taken on. */
+    source: string;
+    files: AuthFilePayload[];
+}
+/** Result of classifying one source agent's auth for propagation. */
+export interface AuthSnapshotResult {
+    files: AuthFilePayload[];
+    /** Agent ids whose auth is device-bound (keychain) and cannot be captured. */
+    bound: string[];
+}

package/dist/lib/fleet/types.js

@@ -0,0 +1,13 @@
+/**
+ * Shared types for the fleet profile-sync feature (`agents apply` / `ag apply`).
+ *
+ * `agents.yaml` gains an additive `fleet:` block that declares a *profile*: which
+ * agents every device should have installed, which config scopes to reconcile,
+ * and whether logins/tokens propagate. `apply` reconciles the live fleet to it.
+ *
+ * These types are the contract shared by the manifest parser (`manifest.ts`),
+ * the reconcile engine (`apply.ts`), the auth propagation (`auth-sync.ts`), and
+ * the command (`commands/apply.ts`). Runtime probe/diff shapes live here too so
+ * the pure diff can be unit-tested without SSH.
+ */
+export {};

package/dist/lib/git.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Git operations for the agents-cli system repo and package repositories.
+ *
+ * Handles cloning, pulling, syncing, and inspecting git repos used by
+ * the agents version management and plugin/package system. Includes
+ * source parsing for GitHub shorthand, SSH, HTTPS, and local paths.
+ */
+import { SimpleGit } from 'simple-git';
 /**
  * Validate that a clone/pull source uses a safe git transport before it is
  * handed to `git`.
@@ -16,6 +24,25 @@
  * @throws Error if the source uses a disallowed transport.
  */
 export declare function assertSafeGitTransport(source: string): void;
+/**
+ * Validate a branch name before it is passed to `git push` / `git pull`.
+ *
+ * A name beginning with `-` is parsed by git as a command-line option
+ * (e.g. `--mirror`, `--receive-pack=…`), not a ref. Pure string check —
+ * identical on every OS, no spawn.
+ *
+ * @throws Error if the name is empty or would be interpreted as a git option.
+ */
+export declare function assertValidBranchName(branch: string): void;
+/**
+ * `git push origin <branch>` with option-injection hardening:
+ *   1. {@link assertValidBranchName} rejects leading `-`
+ *   2. `--` ends option parsing so a hostile ref cannot be read as a flag
+ *
+ * Prefer this over `git.push(remote, branch)` whenever the branch comes from
+ * repo state rather than a hard-coded literal.
+ */
+export declare function pushOrigin(git: SimpleGit, branch: string): Promise<void>;
 /** Parsed representation of a git source string (GitHub, generic URL, or local path). */
 export interface GitSource {
     type: 'github' | 'url' | 'local';

package/dist/lib/git.js

@@ -51,6 +51,36 @@ export function assertSafeGitTransport(source) {
     }
     // No scheme -> SCP-style SSH ("git@host:path") or a local path; both safe.
 }
+/**
+ * Validate a branch name before it is passed to `git push` / `git pull`.
+ *
+ * A name beginning with `-` is parsed by git as a command-line option
+ * (e.g. `--mirror`, `--receive-pack=…`), not a ref. Pure string check —
+ * identical on every OS, no spawn.
+ *
+ * @throws Error if the name is empty or would be interpreted as a git option.
+ */
+export function assertValidBranchName(branch) {
+    const b = branch.trim();
+    if (!b) {
+        throw new Error(`Invalid branch name ${JSON.stringify(branch)}: branch name is empty.`);
+    }
+    if (b.startsWith('-')) {
+        throw new Error(`Invalid branch name ${JSON.stringify(branch)}: a name starting with "-" is interpreted as a git option.`);
+    }
+}
+/**
+ * `git push origin <branch>` with option-injection hardening:
+ *   1. {@link assertValidBranchName} rejects leading `-`
+ *   2. `--` ends option parsing so a hostile ref cannot be read as a flag
+ *
+ * Prefer this over `git.push(remote, branch)` whenever the branch comes from
+ * repo state rather than a hard-coded literal.
+ */
+export async function pushOrigin(git, branch) {
+    assertValidBranchName(branch);
+    await git.raw(['push', '--', 'origin', branch]);
+}
 /**
  * Whether installing a cloned/pulled repo's `.githooks/` is enabled.
  *
@@ -377,6 +407,7 @@ export async function commitAndPush(repoPath, message) {
         const git = simpleGit(repoPath);
         let status = await git.status();
         const branch = status.current || 'main';
+        assertValidBranchName(branch);
         let committed = false;
         if (status.files.length > 0) {
             await git.add('-A');
@@ -402,7 +433,7 @@ export async function commitAndPush(repoPath, message) {
         catch {
             /* origin/<branch> may not exist yet (first push) */
         }
-        await git.push('origin', branch);
+        await pushOrigin(git, branch);
         let after = '';
         try {
             after = (await git.raw(['rev-parse', '--short=8', 'HEAD'])).trim();
@@ -735,12 +766,13 @@ export async function syncRepoGit(dir, opts) {
             };
         }
         const branch = status.current || 'main';
+        assertValidBranchName(branch);
         await git.fetch('origin');
         await git.pull('origin', branch, { '--rebase': 'true' });
         installGithooksSymlinks(dir);
         let pushed = false;
         if (opts.push) {
-            await git.push('origin', branch);
+            await pushOrigin(git, branch);
             pushed = true;
         }
         const log = await git.log({ maxCount: 1 });

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

@@ -62,24 +62,37 @@ export interface DispatchOptions {
     prompt: string;
     /** Explicit agent version pin (e.g. "2.1.207") to forward as `agent@version`. */
     version?: string;
-    /** Explicit run strategy (e.g. "balanced") to forward as `--strategy <strategy>`. */
+    /** Run strategy (e.g. "balanced") — the remote picks among ITS signed-in accounts. */
     strategy?: string;
+    balanced?: boolean;
+    fallback?: string;
     mode?: string;
     model?: string;
-    /** Reasoning effort to forward as `--effort <effort>`. */
+    /** Reasoning effort — forwarded unless 'auto' (the remote default). */
     effort?: string;
-    /** Additional directories to grant, already made remote-portable. */
+    /** `--env k=v` pairs, forwarded verbatim (the remote CLI parses them). */
+    env?: string[];
+    /** `--add-dir` grants, already made remote-portable. */
     addDir?: string[];
-    /** Stream events as JSON lines. */
+    /** Agent wall-clock cap, forwarded as `--timeout <duration>` for the REMOTE to enforce. */
+    timeout?: string;
+    /** Loop family — the loop driver runs on the host. */
+    loop?: boolean;
+    maxIterations?: string;
+    budget?: string;
+    until?: string;
+    interval?: string;
+    /** Remote emits ndjson into its log; the local follow streams it verbatim. */
     json?: boolean;
-    /** Show detailed execution logs. */
     verbose?: boolean;
-    /** Kill the agent after this duration, forwarded as `--timeout <duration>`. */
-    timeout?: string;
-    /** Skip the interactive budget-confirm prompt. */
+    /** Skip the budget-confirm prompt — a detached remote run can't answer one. */
     yes?: boolean;
     /** Route through the Agent Client Protocol. */
     acp?: boolean;
+    /** False forwards --no-auto-secrets (workflow secrets resolve on the REMOTE keychain). */
+    autoSecrets?: boolean;
+    /** Native-CLI passthrough (everything after `--`), appended last. */
+    passthroughArgs?: string[];
     remoteCwd?: string;
     /**
      * Force the remote run's NEW session to use this exact id (Claude only, via
@@ -105,6 +118,10 @@ export interface DispatchOptions {
  * session-id / resume flag wiring is unit-testable without an SSH round-trip.
  * `--session-id` and `--resume` are mutually exclusive (the CLI rejects both);
  * resume wins when — defensively — both are set.
+ *
+ * Every field here is classified 'forward' in RUN_OPTION_FORWARDING
+ * (remote-cmd.ts) — keep the two in lockstep; run-forwarding.test.ts asserts
+ * the table side.
  */
 export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
 export interface InteractiveDispatchOptions {
@@ -139,6 +156,10 @@ export interface InteractiveDispatchOptions {
     raw?: boolean;
     /** Forward `--interactive` to the remote so a prompt-bearing run still starts the TUI. */
     forceInteractive?: boolean;
+    /** `--env k=v` pairs, forwarded verbatim (the remote CLI parses them). */
+    env?: string[];
+    balanced?: boolean;
+    fallback?: string;
     /** Copy runtime credentials to the host before the run and shred them after. */
     copyCreds?: HostCredentials;
 }

package/dist/lib/hosts/dispatch.js

@@ -17,6 +17,7 @@ import { resolveRemoteOsSync } from './remote-os.js';
 import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { wrapHostCommandWithCredentials } from './credentials.js';
+import { hostKeyCheckingOpts } from '../devices/known-hosts.js';
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
@@ -180,10 +181,19 @@ async function launchDetached(host, target, opts) {
     if (opts.copyCreds) {
         inner = wrapHostCommandWithCredentials(inner, opts.copyCreds);
     }
+    // When credentials ride this launch, verify the host key strictly against the
+    // managed pin (the gate in exec.ts already required the host to be pinned) and
+    // force a fresh connection — reusing a control socket opened by an earlier
+    // accept-new connection would bypass the strict check (RUSH-1767).
+    const credHostKeyOpts = opts.copyCreds ? hostKeyCheckingOpts(true) : undefined;
     // Outer: ensure dir, launch the login-shell wrapper as a new process-group
     // leader, and print that leader PID.
     const launch = `mkdir -p ${REMOTE_DIR}; ${buildDetachedLaunchCommand(inner)}`;
-    const res = sshExec(target, launch, { timeoutMs: 30000, multiplex: true });
+    const res = sshExec(target, launch, {
+        timeoutMs: 30000,
+        multiplex: !opts.copyCreds,
+        hostKeyOpts: credHostKeyOpts,
+    });
     if (res.code !== 0) {
         throw new Error(`Failed to launch on "${host.name}": ${(res.stderr || res.stdout).trim() || 'ssh error'}`);
     }
@@ -235,38 +245,61 @@ async function launchDetached(host, target, opts) {
  * session-id / resume flag wiring is unit-testable without an SSH round-trip.
  * `--session-id` and `--resume` are mutually exclusive (the CLI rejects both);
  * resume wins when — defensively — both are set.
+ *
+ * Every field here is classified 'forward' in RUN_OPTION_FORWARDING
+ * (remote-cmd.ts) — keep the two in lockstep; run-forwarding.test.ts asserts
+ * the table side.
  */
 export function buildRunForwardedArgs(opts) {
     const agentArg = opts.version ? `${opts.agent}@${opts.version}` : opts.agent;
     const args = ['run', agentArg, opts.prompt, '--quiet'];
-    if (opts.strategy)
-        args.push('--strategy', opts.strategy);
     if (opts.mode)
         args.push('--mode', opts.mode);
     if (opts.model)
         args.push('--model', opts.model);
-    if (opts.effort)
+    // 'auto' is the remote default — forwarding it would only add noise.
+    if (opts.effort && opts.effort !== 'auto')
         args.push('--effort', opts.effort);
-    if (opts.addDir) {
-        for (const dir of opts.addDir)
-            args.push('--add-dir', dir);
-    }
+    for (const kv of opts.env ?? [])
+        args.push('--env', kv);
+    for (const dir of opts.addDir ?? [])
+        args.push('--add-dir', dir);
+    if (opts.timeout)
+        args.push('--timeout', opts.timeout);
+    if (opts.strategy)
+        args.push('--strategy', opts.strategy);
+    if (opts.balanced)
+        args.push('--balanced');
+    if (opts.fallback)
+        args.push('--fallback', opts.fallback);
+    if (opts.loop)
+        args.push('--loop');
+    if (opts.maxIterations)
+        args.push('--max-iterations', opts.maxIterations);
+    if (opts.budget)
+        args.push('--budget', opts.budget);
+    if (opts.until)
+        args.push('--until', opts.until);
+    if (opts.interval)
+        args.push('--interval', opts.interval);
     if (opts.json)
         args.push('--json');
     if (opts.verbose)
         args.push('--verbose');
-    if (opts.timeout)
-        args.push('--timeout', opts.timeout);
     if (opts.yes)
         args.push('--yes');
     if (opts.acp)
         args.push('--acp');
+    if (opts.autoSecrets === false)
+        args.push('--no-auto-secrets');
     if (opts.name)
         args.push('--name', opts.name);
     if (opts.resume)
         args.push('--resume', opts.resume);
     else if (opts.sessionId)
         args.push('--session-id', opts.sessionId);
+    if (opts.passthroughArgs && opts.passthroughArgs.length > 0)
+        args.push('--', ...opts.passthroughArgs);
     return args;
 }
 /**
@@ -283,24 +316,29 @@ export function buildInteractiveRunForwardedArgs(opts) {
         args.push(opts.prompt);
     if (opts.forceInteractive)
         args.push('--interactive');
-    if (opts.strategy)
-        args.push('--strategy', opts.strategy);
     if (opts.mode)
         args.push('--mode', opts.mode);
     if (opts.model)
         args.push('--model', opts.model);
-    if (opts.effort)
+    // 'auto' is the remote default — forwarding it would only add noise.
+    if (opts.effort && opts.effort !== 'auto')
         args.push('--effort', opts.effort);
-    if (opts.addDir) {
-        for (const dir of opts.addDir)
-            args.push('--add-dir', dir);
-    }
+    for (const kv of opts.env ?? [])
+        args.push('--env', kv);
+    for (const dir of opts.addDir ?? [])
+        args.push('--add-dir', dir);
+    if (opts.timeout)
+        args.push('--timeout', opts.timeout);
+    if (opts.strategy)
+        args.push('--strategy', opts.strategy);
+    if (opts.balanced)
+        args.push('--balanced');
+    if (opts.fallback)
+        args.push('--fallback', opts.fallback);
     if (opts.json)
         args.push('--json');
     if (opts.verbose)
         args.push('--verbose');
-    if (opts.timeout)
-        args.push('--timeout', opts.timeout);
     if (opts.yes)
         args.push('--yes');
     if (opts.acp)
@@ -334,7 +372,15 @@ export async function runInteractiveOnHost(host, opts) {
     if (opts.copyCreds) {
         remoteCmd = wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds);
     }
-    return sshStream(target, remoteCmd, { tty: process.stdin.isTTY, multiplex: true });
+    // Credentials ride this stream when --copy-creds is set: verify the host key
+    // strictly against the managed pin and force a fresh connection so a stale
+    // accept-new control socket can't bypass the check (RUSH-1767).
+    const credHostKeyOpts = opts.copyCreds ? hostKeyCheckingOpts(true) : undefined;
+    return sshStream(target, remoteCmd, {
+        tty: process.stdin.isTTY,
+        multiplex: !opts.copyCreds,
+        hostKeyOpts: credHostKeyOpts,
+    });
 }
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export async function dispatchToHost(host, opts) {

package/dist/lib/hosts/passthrough.js

@@ -107,6 +107,8 @@ const OWN_HOST_COMMANDS = new Set([
     'ssh',
     'devices',
     'fleet', // alias of devices
+    'apply', // `--device` scopes the fleet reconcile to one device (it targets devices itself)
+    'monitors', // `--device` names the OWNER machine (pin-to-one), not a routing target
 ]);
 /** `--no-tty` is stripped like the routing flags but carries no value. */
 const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];

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

@@ -0,0 +1,27 @@
+/**
+ * Devices host provider: the Tailscale fleet as dispatch targets.
+ *
+ * Bridges the devices registry (`agents devices`, ~/.agents/.history/devices/
+ * 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` shows up in
+ * `agents hosts list`, 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)
+ * but marked `dispatchable: false`; resolving one for dispatch throws the same
+ * typed `DeviceOffloadUnsupportedError` as before — offload rides `sshExec`,
+ * whose SSH_OPTS force `BatchMode=yes`.
+ *
+ * Precedence is unchanged: this provider registers AFTER `local`, so an
+ * enrolled host shadows a same-name device in both list dedup and resolve
+ * order, exactly like the old tier-2 devices fall-through in resolveHost.
+ */
+import type { Host, HostProvider, HostProviderCapabilities, HostStatus } from '../types.js';
+export declare class DevicesHostProvider implements HostProvider {
+    readonly id: "devices";
+    capabilities(): HostProviderCapabilities;
+    list(): Promise<Host[]>;
+    resolve(name: string): Promise<Host | null>;
+    presence(name: string): Promise<HostStatus>;
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Devices host provider: the Tailscale fleet as dispatch targets.
+ *
+ * Bridges the devices registry (`agents devices`, ~/.agents/.history/devices/
+ * 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` shows up in
+ * `agents hosts list`, 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)
+ * but marked `dispatchable: false`; resolving one for dispatch throws the same
+ * typed `DeviceOffloadUnsupportedError` as before — offload rides `sshExec`,
+ * whose SSH_OPTS force `BatchMode=yes`.
+ *
+ * Precedence is unchanged: this provider registers AFTER `local`, so an
+ * enrolled host shadows a same-name device in both list dedup and resolve
+ * order, exactly like the old tier-2 devices fall-through in resolveHost.
+ */
+import { loadDevices, getDevice, isControlDevice } from '../../devices/registry.js';
+import { DeviceOffloadUnsupportedError } from '../types.js';
+/** Tailscale's own presence bit, when the sync captured one. */
+function statusOf(device) {
+    if (!device.tailscale)
+        return 'unknown';
+    return device.tailscale.online ? 'online' : 'offline';
+}
+/**
+ * Bridge a device profile into a `Host`. dnsName (stable across IP churn) is
+ * preferred over ip; `source: 'inline'` makes `sshTargetFor` emit `user@address`.
+ * Capability tags attach by enrolling the device (`agents hosts add <device>
+ * --cap …` sources the target from this profile) — the enrolled entry then
+ * shadows this row by provider precedence, carrying the caps.
+ */
+function deviceToPoolHost(device) {
+    // A control device (a cockpit, e.g. a paired iPhone) drives the fleet but
+    // never runs agents — it must never enter the host pool or be resolvable as a
+    // dispatch target, whatever platform it reports (an iPhone syncs as `unknown`,
+    // which remoteShellFor would otherwise default to POSIX and try to SSH).
+    if (isControlDevice(device))
+        return null;
+    const address = device.address.dnsName ?? device.address.ip;
+    if (!address)
+        return null; // unreachable profile — nothing to dispatch to
+    return {
+        name: device.name,
+        provider: 'devices',
+        source: 'inline',
+        address,
+        user: device.user,
+        ...(device.platform !== 'unknown' ? { os: device.platform } : {}),
+        enrolled: true,
+        status: statusOf(device),
+        dispatchable: device.auth.method !== 'password',
+    };
+}
+export class DevicesHostProvider {
+    id = 'devices';
+    capabilities() {
+        // mutate stays false: `agents devices sync/add/set` own the registry.
+        return { directory: true, mutate: false, presence: true, relay: false, lease: false };
+    }
+    async list() {
+        const devices = await loadDevices();
+        const out = [];
+        for (const device of Object.values(devices)) {
+            const host = deviceToPoolHost(device);
+            if (host)
+                out.push(host);
+        }
+        return out.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async resolve(name) {
+        const device = await getDevice(name);
+        if (!device)
+            return null;
+        // Resolving is asking to dispatch. A control device can't run agents — fail
+        // loud with a clear message instead of attempting an SSH dispatch onto a
+        // phone (which remoteShellFor would treat as a POSIX host).
+        if (isControlDevice(device)) {
+            throw new Error(`Device "${device.name}" is a control device (a cockpit), not an executor — it can't run agents. Dispatch to a worker device instead.`);
+        }
+        // Keep the long-standing typed refusal for password auth (BatchMode=yes
+        // can't answer a prompt).
+        if (device.auth.method === 'password') {
+            throw new DeviceOffloadUnsupportedError(device.name);
+        }
+        const host = deviceToPoolHost(device);
+        if (!host) {
+            throw new Error(`Device "${device.name}" has no address (Tailscale DNS name or IP) to reach it by.`);
+        }
+        return host;
+    }
+    async presence(name) {
+        const device = await getDevice(name);
+        return device ? statusOf(device) : 'unknown';
+    }
+}

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

@@ -2,30 +2,24 @@
  * Host provider registry.
  *
  * Mirrors the cloud provider registry: a Map of provider id → implementation,
- * instantiated once. v1 registers only `local`; adding `rush`/`tailscale`/
- * `crabbox` later is a one-line `providers.set(...)` with no caller changes.
+ * instantiated once. Registers `local` then `devices` (order is precedence:
+ * an enrolled host shadows a same-name device); adding `rush`/`crabbox` later
+ * is a one-line `providers.set(...)` with no caller changes.
  */
 import type { Host, HostProvider, HostProviderId } from './types.js';
+import { DeviceOffloadUnsupportedError } from './types.js';
+export { DeviceOffloadUnsupportedError };
 export declare function getProvider(id: HostProviderId): HostProvider;
 export declare function getAllProviders(): HostProvider[];
 /** Every host across all registered providers, deduped by name (first wins). */
 export declare function listAllHosts(): Promise<Host[]>;
-/**
- * Thrown when a device resolves but can't be used as an offload target because
- * it authenticates with a password. The offload path runs over `sshExec`, whose
- * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
- * auth can carry a `--host` run. Named so the top-level catch prints the message
- * cleanly instead of a stack trace.
- */
-export declare class DeviceOffloadUnsupportedError extends Error {
-    constructor(name: string);
-}
 /**
  * Resolve a host name to a single host, or null if unknown. Resolution order:
- *   1. host providers — the `agents hosts` registry (agents.yaml overlay + ssh-config)
- *   2. the devices registry (`agents devices`) — a machine registered once with
- *      `agents devices sync` is reachable by `--host`/`--device` with no second enroll
- *   3. an ad-hoc `user@host` (must contain `@`, validated) — nothing to register
+ *   1. host providers, in registration order — the `agents hosts` registry
+ *      (`local`: agents.yaml overlay + ssh-config), then the devices registry
+ *      (`devices`: a machine registered once with `agents devices sync` is
+ *      reachable by `--host`/`--device` with no second enroll)
+ *   2. an ad-hoc `user@host` (must contain `@`, validated) — nothing to register
  *
  * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`)
  * stays reachable: `--host gpu` must fall through to a cap lookup, not be misread