@phnx-labs/agents-cli 1.20.64 → 1.20.65

package/dist/lib/hosts/dispatch.js

@@ -235,38 +235,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 +306,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)

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

package/dist/lib/hosts/registry.js

@@ -2,17 +2,23 @@
  * 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 { DeviceOffloadUnsupportedError } from './types.js';
 import { LocalHostProvider } from './providers/local.js';
-import { getDevice } from '../devices/registry.js';
+import { DevicesHostProvider } from './providers/devices.js';
 import { assertValidSshTarget } from '../ssh-exec.js';
+// Re-export so existing importers (tests, commands) keep their path; the class
+// itself lives in types.ts so providers can throw it without a circular import.
+export { DeviceOffloadUnsupportedError };
 const providers = new Map();
 function initProviders() {
     if (providers.size > 0)
         return;
     providers.set('local', new LocalHostProvider());
+    providers.set('devices', new DevicesHostProvider());
 }
 export function getProvider(id) {
     initProviders();
@@ -40,51 +46,13 @@ export async function listAllHosts() {
     }
     return out;
 }
-/**
- * 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 class DeviceOffloadUnsupportedError extends Error {
-    constructor(name) {
-        super(`Device "${name}" uses password auth, which --host offload can't use yet ` +
-            `(runs go over ssh with BatchMode=yes). Switch it to key auth with ` +
-            `\`agents devices set ${name} --auth key\`, or enroll it as a host with ` +
-            `\`agents hosts add ${name}\`.`);
-        this.name = 'DeviceOffloadUnsupportedError';
-    }
-}
-/**
- * Bridge a registered device into a `Host` so `--host <device>` just works.
- * A device's dnsName (preferred) or ip becomes the ssh address; `source: 'inline'`
- * makes `sshTargetFor` emit `user@address`.
- */
-function deviceToHost(device) {
-    if (device.auth.method === 'password') {
-        throw new DeviceOffloadUnsupportedError(device.name);
-    }
-    const address = device.address.dnsName ?? device.address.ip;
-    if (!address) {
-        throw new Error(`Device "${device.name}" has no address (Tailscale DNS name or IP) to reach it by.`);
-    }
-    return {
-        name: device.name,
-        provider: 'local',
-        source: 'inline',
-        address,
-        user: device.user,
-        ...(device.platform !== 'unknown' ? { os: device.platform } : {}),
-        enrolled: true,
-    };
-}
 /**
  * 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
@@ -96,9 +64,6 @@ export async function resolveHost(name) {
         if (host)
             return host;
     }
-    const device = await getDevice(name);
-    if (device)
-        return deviceToHost(device);
     if (name.includes('@')) {
         assertValidSshTarget(name);
         const at = name.indexOf('@');
@@ -111,7 +76,9 @@ export async function resolveHost(name) {
  * matching host, or throws on 0 or >1 matches unless `any` is set (then first).
  */
 export async function resolveHostByCap(cap, any = false) {
-    const matches = (await listAllHosts()).filter((h) => h.caps?.includes(cap));
+    // Non-dispatchable hosts (password-auth devices) are listed for honesty but
+    // must never be picked as a run target.
+    const matches = (await listAllHosts()).filter((h) => h.caps?.includes(cap) && h.dispatchable !== false);
     if (matches.length === 0)
         throw new Error(`No host tagged "${cap}". Tag one with: agents hosts add <name> --cap ${cap}`);
     if (matches.length > 1 && !any) {

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

@@ -33,6 +33,29 @@ export declare function stripRoutingFlags(args: string[], specs: StripSpec[]): s
  * binary (which would re-trigger routing).
  */
 export declare const HOST_ROUTING_SPECS: StripSpec[];
+/** How one `agents run` option behaves when the run is offloaded with `--host`. */
+export type RunOptionForwarding = 
+/** Appended to the remote `agents run` argv — same behavior local or remote. */
+'forward'
+/** Refused with an actionable error BEFORE dispatch — never silently dropped. */
+ | 'reject'
+/** Consumed by the dispatching side (routing, follow rendering, cwd portability). */
+ | 'local-only';
+/**
+ * The forwarding contract for `agents run … --host`: every option of the `run`
+ * command is classified here, keyed by its commander attribute name. A
+ * commander-introspection test (run-forwarding.test.ts) fails when a run
+ * option is missing from this table, so a new option can never silently drop
+ * at the SSH boundary again — the exact bug this table exists to prevent
+ * (--secrets/--effort/--env/--timeout historically vanished on --host runs
+ * with no error).
+ *
+ * Rejections are value-aware at the call site (exec.ts): `--secrets` only
+ * rejects when a bundle was actually passed, `--resume` only when bare.
+ */
+export declare const RUN_OPTION_FORWARDING: Record<string, RunOptionForwarding>;
+/** Actionable messages for value-aware rejections, keyed by attribute name. */
+export declare const RUN_OPTION_REJECT_MESSAGES: Record<string, string>;
 /**
  * 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

package/dist/lib/hosts/remote-cmd.js

@@ -50,6 +50,77 @@ export const HOST_ROUTING_SPECS = [
     { long: 'device', takesValue: true },
     { long: 'remote-cwd', takesValue: true },
 ];
+/**
+ * The forwarding contract for `agents run … --host`: every option of the `run`
+ * command is classified here, keyed by its commander attribute name. A
+ * commander-introspection test (run-forwarding.test.ts) fails when a run
+ * option is missing from this table, so a new option can never silently drop
+ * at the SSH boundary again — the exact bug this table exists to prevent
+ * (--secrets/--effort/--env/--timeout historically vanished on --host runs
+ * with no error).
+ *
+ * Rejections are value-aware at the call site (exec.ts): `--secrets` only
+ * rejects when a bundle was actually passed, `--resume` only when bare.
+ */
+export const RUN_OPTION_FORWARDING = {
+    // forwarded — the remote run behaves exactly like a local one
+    mode: 'forward',
+    effort: 'forward',
+    model: 'forward',
+    env: 'forward',
+    addDir: 'forward',
+    name: 'forward',
+    resume: 'forward', // concrete id only — bare `--resume` rejects (picker can't cross SSH)
+    sessionId: 'forward',
+    timeout: 'forward',
+    fallback: 'forward',
+    balanced: 'forward',
+    strategy: 'forward',
+    loop: 'forward',
+    maxIterations: 'forward',
+    budget: 'forward',
+    until: 'forward',
+    interval: 'forward',
+    json: 'forward', // remote emits ndjson into its log; the local follow streams it verbatim
+    verbose: 'forward',
+    yes: 'forward', // a detached remote run can't answer the budget-confirm prompt
+    acp: 'forward', // the remote CLI routes through ACP on ITS side of the wire
+    autoSecrets: 'forward', // workflow frontmatter secrets resolve on the REMOTE keychain
+    // rejected — cannot cross the SSH boundary; fail loud, never degrade
+    secrets: 'reject',
+    secretsKeys: 'reject',
+    allowExpired: 'reject',
+    resumeCheckpoint: 'reject',
+    // local-only — routing, dispatch-path choice, and follow rendering
+    quiet: 'local-only', // the remote argv always carries --quiet
+    headless: 'local-only',
+    interactive: 'local-only', // the interactive path forwards --interactive itself
+    cwd: 'local-only', // made portable into remoteCwd
+    project: 'local-only',
+    remoteCwd: 'local-only',
+    raw: 'local-only', // interactive builder forwards --raw itself
+    tmux: 'local-only',
+    disableTmux: 'local-only',
+    host: 'local-only',
+    device: 'local-only',
+    on: 'local-only',
+    computer: 'local-only',
+    any: 'local-only',
+    follow: 'local-only',
+    lease: 'local-only',
+    keepBox: 'local-only',
+    copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
+};
+/** Actionable messages for value-aware rejections, keyed by attribute name. */
+export const RUN_OPTION_REJECT_MESSAGES = {
+    secrets: '--secrets cannot cross the SSH boundary — Keychain values are never sent to a host implicitly. ' +
+        'Provision the bundle on the host first (agents secrets export --host <name>), then run without --secrets; ' +
+        'workflow frontmatter secrets resolve from the HOST\'s own keychain.',
+    secretsKeys: '--secrets-keys applies to --secrets bundles, which cannot cross the SSH boundary (see --secrets).',
+    allowExpired: '--allow-expired applies to --secrets bundles, which cannot cross the SSH boundary (see --secrets).',
+    resumeCheckpoint: '--resume-checkpoint reads a local checkpoint.json — it cannot resume a run on another machine. Run it locally, or start a fresh --loop run on the host.',
+    resumeBare: '--resume with no id opens the interactive picker, which cannot run across a detached host dispatch. Pass a concrete session id: agents run <agent> --resume <id> --host <name>.',
+};
 /**
  * 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

package/dist/lib/hosts/run-target.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared host-run dispatch — the one path every surface uses to run an agent on
+ * another machine: `agents run --host` (commands/exec.ts), the `host` cloud
+ * provider (`agents cloud run --provider host`), and host-placed routines.
+ *
+ * Wraps the two steps every caller needs and previously lived inline in
+ * exec.ts's `--host` branch:
+ *   1. resolution — name → capability tag → error, with the same fall-through
+ *      semantics as `agents run --host` (only "Multiple hosts tagged…" is a
+ *      resolution verdict; "no host tagged" degrades to unknown-host), and
+ *   2. headless dispatch — session-id mint (Claude only), detached SSH launch,
+ *      and LOCAL session-index registration so the run shows in `agents sessions`.
+ *
+ * Interactive dispatch stays in exec.ts: it is inherently tied to the caller's
+ * TTY and has no other consumers.
+ */
+import type { Host } from './types.js';
+import type { DispatchResult } from './dispatch.js';
+import type { HostCredentials } from './credentials.js';
+/**
+ * Resolution failed with a user-actionable message the caller should print
+ * verbatim. Distinct from `DeviceOffloadUnsupportedError` (which propagates to
+ * the top-level catch) so callers can tell "bad name" from "bad auth method".
+ */
+export declare class HostResolutionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a `--host` value the way `agents run` does: exact name (providers →
+ * devices → `user@host`), then capability tag. Throws `HostResolutionError`
+ * for an ambiguous tag or an unknown name; lets `DeviceOffloadUnsupportedError`
+ * (password-auth device) propagate untouched for the top-level catch.
+ */
+export declare function resolveHostRunTarget(name: string, opts?: {
+    any?: boolean;
+}): Promise<Host>;
+export interface HostPromptRun {
+    agent: string;
+    prompt: string;
+    /** Explicit agent version pin, forwarded as `agent@version`. */
+    version?: string;
+    mode?: string;
+    model?: string;
+    /** Durable `--name <slug>` handle recorded on the task. */
+    name?: string;
+    /** Resume an existing session on the host by concrete id. */
+    resume?: string;
+    /** Working directory on the host, already made remote-portable by the caller. */
+    remoteCwd?: string;
+    /** Stream progress and block until completion (default true). */
+    follow?: boolean;
+    timeoutMs?: number;
+    /** Local directory to record in the session index (defaults to process.cwd()). */
+    cwd?: string;
+    /** Forwarded run options — see RUN_OPTION_FORWARDING in remote-cmd.ts. */
+    effort?: string;
+    env?: string[];
+    addDir?: string[];
+    timeout?: string;
+    strategy?: string;
+    balanced?: boolean;
+    fallback?: string;
+    loop?: boolean;
+    maxIterations?: string;
+    budget?: string;
+    until?: string;
+    interval?: string;
+    json?: boolean;
+    verbose?: boolean;
+    yes?: boolean;
+    acp?: boolean;
+    autoSecrets?: boolean;
+    passthroughArgs?: string[];
+    /** Copy runtime credentials to the host before the run and shred them after. */
+    copyCreds?: HostCredentials;
+}
+/**
+ * Dispatch a headless prompt run onto a resolved host: mint the forced session
+ * id (Claude is the only agent that accepts `--session-id`; on resume the
+ * remote session keeps its id), launch detached over SSH, and register the run
+ * in the LOCAL session index. Returns the task record and the remote exit code
+ * (`-1` = follow window closed while the run continues).
+ */
+export declare function dispatchPromptToHost(host: Host, opts: HostPromptRun): Promise<DispatchResult>;