@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/hooks.js

@@ -801,6 +801,10 @@ export function parseHookManifest(opts = {}) {
     }
     return merged;
 }
+export function selectHookManifest(manifest, selected) {
+    const selectedHooks = new Set(selected);
+    return Object.fromEntries(Object.entries(manifest).filter(([name, hook]) => selectedHooks.has(name) || selectedHooks.has(path.basename(hook.script))));
+}
 /**
  * Hook script files present on disk that no manifest entry declares — "dead"
  * hooks. The registrar only wires manifest-declared hooks into an agent's
@@ -934,6 +938,15 @@ function sweepOrphanShims(manifest) {
 export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride) {
     const manifest = hookManifest || parseHookManifest();
     if (Object.keys(manifest).length === 0) {
+        if (agentId === 'opencode') {
+            const pluginPath = path.join(versionHome, '.config', 'opencode', 'plugins', 'agents-cli-hooks.ts');
+            try {
+                fs.rmSync(pluginPath, { force: true });
+            }
+            catch (e) {
+                return { registered: [], errors: [`Failed to remove agents-cli-hooks.ts: ${e.message}`] };
+            }
+        }
         return { registered: [], errors: [] };
     }
     sweepOrphanShims(manifest);
@@ -991,6 +1004,9 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'grok') {
         return registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefixes);
     }
+    if (agentId === 'opencode') {
+        return registerHooksForOpenCode(versionHome, manifest, resolveScript);
+    }
     if (agentId === 'kimi') {
         return registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefixes);
     }
@@ -1011,6 +1027,146 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     }
     return { registered: [], errors: [] };
 }
+const OPENCODE_DIRECT_EVENT_MAP = {
+    PreToolUse: 'tool.execute.before',
+    PostToolUse: 'tool.execute.after',
+    UserPromptSubmit: 'chat.message',
+};
+const OPENCODE_LIFECYCLE_EVENT_MAP = {
+    SessionStart: ['session.created'],
+    SessionEnd: ['session.deleted'],
+    Stop: ['session.idle', 'session.error'],
+    PreCompact: ['session.compacted'],
+    OnError: ['session.error'],
+    Notification: ['permission.asked'],
+};
+/**
+ * Compile canonical hooks.yaml entries into a local OpenCode plugin.
+ *
+ * OpenCode has no declarative shell-hook config block. It auto-loads direct
+ * TS/JS modules from ~/.config/opencode/plugins/, and supplies Bun's `$` shell
+ * primitive to each plugin. The generated module subscribes to native plugin
+ * events, sends the event payload to the managed hook script as JSON on stdin,
+ * and surfaces a non-zero script exit as a plugin error.
+ */
+function registerHooksForOpenCode(versionHome, manifest, resolveScript) {
+    const registered = [];
+    const errors = [];
+    const direct = new Map();
+    const lifecycle = new Map();
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const command = resolveHookCommand(name, hookDef, resolveScript);
+        if (!command) {
+            errors.push(`${name}: script not found`);
+            continue;
+        }
+        const generated = {
+            name,
+            command,
+            ...(hookDef.timeout !== undefined ? { timeout: hookDef.timeout } : {}),
+            ...(hookDef.matcher ? { matcher: hookDef.matcher } : {}),
+        };
+        for (const event of hookDef.events) {
+            const directEvent = OPENCODE_DIRECT_EVENT_MAP[event];
+            if (directEvent) {
+                const hooks = direct.get(directEvent) ?? [];
+                hooks.push(generated);
+                direct.set(directEvent, hooks);
+                registered.push(`${name} -> ${directEvent}`);
+            }
+            for (const lifecycleEvent of OPENCODE_LIFECYCLE_EVENT_MAP[event] ?? []) {
+                const hooks = lifecycle.get(lifecycleEvent) ?? [];
+                hooks.push(generated);
+                lifecycle.set(lifecycleEvent, hooks);
+                registered.push(`${name} -> ${lifecycleEvent}`);
+            }
+        }
+    }
+    const serializedDirect = JSON.stringify(Object.fromEntries(direct), null, 2);
+    const serializedLifecycle = JSON.stringify(Object.fromEntries(lifecycle), null, 2);
+    const pluginSource = `// Generated by agents-cli. Re-run agents sync to update.
+const directHooks = ${serializedDirect}
+const lifecycleHooks = ${serializedLifecycle}
+
+function matches(hook, tool) {
+  if (!hook.matcher) return true
+  try {
+    return new RegExp(hook.matcher).test(tool)
+  } catch {
+    return hook.matcher === tool
+  }
+}
+
+async function runHooks(hooks, payload, $, matchTool = false) {
+  for (const hook of hooks ?? []) {
+    if (matchTool && !matches(hook, payload.tool_name ?? "")) continue
+    const input = JSON.stringify(payload)
+    const home = Bun.env.HOME ?? Bun.env.USERPROFILE ?? ""
+    const command = hook.command.startsWith("~/")
+      ? \`\${home}/\${hook.command.slice(2)}\`
+      : hook.command
+    const shell = Bun.which("bash") ?? Bun.which("sh")
+    if (!shell) throw new Error(\`\${hook.name} requires bash or sh\`)
+    const execArgs = [shell, "-c", 'exec "$1"', "agents-hook", command]
+    if (hook.timeout !== undefined) {
+      const child = Bun.spawn(execArgs, {
+        stdin: new Response(input),
+        stdout: "ignore",
+        stderr: "pipe",
+      })
+      let timedOut = false
+      const timer = setTimeout(() => {
+        timedOut = true
+        if (process.platform === "win32") {
+          Bun.spawnSync(["taskkill", "/PID", String(child.pid), "/T", "/F"])
+        } else {
+          child.kill()
+        }
+      }, hook.timeout * 1000)
+      const exitCode = await child.exited.finally(() => clearTimeout(timer))
+      const stderr = await new Response(child.stderr).text()
+      if (timedOut) {
+        throw new Error(\`\${hook.name} timed out after \${hook.timeout} seconds\`)
+      }
+      if (exitCode !== 0) {
+        throw new Error(\`\${hook.name} failed with exit code \${exitCode}: \${stderr.trim()}\`)
+      }
+      continue
+    }
+    const result = await $\`\${shell} -c \${'exec "$1"'} \${"agents-hook"} \${command} < \${new Response(input)}\`.nothrow().quiet()
+    if (result.exitCode !== 0) {
+      throw new Error(\`\${hook.name} failed with exit code \${result.exitCode}: \${result.stderr.toString().trim()}\`)
+    }
+  }
+}
+
+export const AgentsCliHooks = async ({ $ }) => ({
+  event: async ({ event }) => {
+    await runHooks(lifecycleHooks[event.type], { hook_event_name: event.type, ...event }, $)
+  },
+  "chat.message": async (input, output) => {
+    await runHooks(directHooks["chat.message"], { hook_event_name: "UserPromptSubmit", ...input, ...output }, $)
+  },
+  "tool.execute.before": async (input, output) => {
+    await runHooks(directHooks["tool.execute.before"], { hook_event_name: "PreToolUse", tool_name: input.tool, tool_input: output.args, ...input }, $, true)
+  },
+  "tool.execute.after": async (input, output) => {
+    await runHooks(directHooks["tool.execute.after"], { hook_event_name: "PostToolUse", tool_name: input.tool, tool_input: input.args, tool_response: output, ...input }, $, true)
+  },
+})
+`;
+    const pluginDir = path.join(versionHome, '.config', 'opencode', 'plugins');
+    try {
+        fs.mkdirSync(pluginDir, { recursive: true });
+        fs.writeFileSync(path.join(pluginDir, 'agents-cli-hooks.ts'), pluginSource, 'utf-8');
+    }
+    catch (e) {
+        errors.push(`Failed to write agents-cli-hooks.ts: ${e.message}`);
+    }
+    return { registered, errors };
+}
 /**
  * Antigravity (agy) event names differ from agents-cli manifest names. The
  * mapping below is the documented agy schema. PostToolUse has no exact

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

@@ -107,6 +107,13 @@ export interface DispatchOptions {
     name?: string;
     /** Resume an existing session on the host by id (via `agents run --resume`). */
     resume?: string;
+    /**
+     * Forward `--emit-session-id` so the remote run prints its resolved session id
+     * as a stdout sentinel (hosts/session-marker.ts). The launcher parses that id
+     * out of the followed log and stamps it on the task — the join that maps a
+     * remote-created session back home for agents that don't take `--session-id`.
+     */
+    emitSessionId?: boolean;
     /** Stream progress and block until completion (default true). */
     follow?: boolean;
     timeoutMs?: number;

package/dist/lib/hosts/dispatch.js

@@ -298,6 +298,8 @@ export function buildRunForwardedArgs(opts) {
         args.push('--resume', opts.resume);
     else if (opts.sessionId)
         args.push('--session-id', opts.sessionId);
+    if (opts.emitSessionId)
+        args.push('--emit-session-id');
     if (opts.passthroughArgs && opts.passthroughArgs.length > 0)
         args.push('--', ...opts.passthroughArgs);
     return args;

package/dist/lib/hosts/passthrough.js

@@ -98,6 +98,8 @@ const REMOTE_PASSTHROUGH = {
 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
+    'harnesses',
     'sessions',
     'feed',
     'computer',

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

@@ -0,0 +1,78 @@
+import { type Host } from './types.js';
+/** ssh's connection-layer failure code — the signal that the link dropped rather
+ *  than the remote command exiting on its own. Mirrors ssh-exec.ts `sshStream`. */
+export declare const SSH_CONN_FAILURE = 255;
+/** Consecutive failed-to-connect reattaches before giving up. Backoff is capped at
+ *  {@link MAX_BACKOFF_MS}. A reattach that actually reconnected (then dropped again)
+ *  refills the budget, so a long session that blinks all day reconnects every time
+ *  — only consecutive UNREACHABLE attempts exhaust it. */
+export declare const MAX_ATTEMPTS = 6;
+export interface ReconnectState {
+    /** Consecutive failed-to-connect reattaches since the last genuine reconnection. */
+    attempt: number;
+}
+export interface ReconnectOutcome {
+    /** Exit code of the run (initial) or the last re-attach. */
+    code: number;
+    /** Whether the ssh handshake for this attempt actually completed. The initial run
+     *  and any reattach whose preflight probe succeeded are `connected`; a reattach
+     *  that couldn't reach the host is not. Drives the budget refill (see file head). */
+    connected: boolean;
+}
+export type ReconnectDecision = {
+    action: 'stop';
+    code: number;
+} | {
+    action: 'retry';
+    waitMs: number;
+    state: ReconnectState;
+};
+export declare function initialReconnectState(): ReconnectState;
+/** Exponential backoff capped at {@link MAX_BACKOFF_MS}: 2s, 4s, 8s, 16s, 30s… */
+export declare function backoffMs(attempt: number): number;
+/**
+ * Decide what to do after a run/re-attach returned `outcome`. Pure — the only
+ * input is the prior state and the outcome, the only output is the next action.
+ *
+ *  - a non-255 code means the remote command spoke for itself (clean detach = 0,
+ *    agent exit / no live session = non-zero) → stop and surface that code.
+ *  - a 255 means the link dropped → retry, unless the budget is spent.
+ *  - a 255 from an attempt that DID connect (a genuine reconnection that then
+ *    dropped) refills the budget first; a 255 that never connected counts against
+ *    it, so a host that stays unreachable gives up after MAX_ATTEMPTS.
+ */
+export declare function reconnectStep(state: ReconnectState, outcome: ReconnectOutcome): ReconnectDecision;
+/** Human-readable notice shown before each reconnect wait. "13 seconds", not "12.8s". */
+export declare function reconnectNotice(sessionId: string, host: string, attempt: number, waitMs: number): string;
+/** Notice shown once the retry budget is spent. */
+export declare function exhaustedNotice(sessionId: string, host: string): string;
+/**
+ * Re-attach the live remote tmux pane for `sessionId` by driving the peer's own
+ * `agents sessions focus`. A fast, un-multiplexed preflight probe (`ssh … true`)
+ * first establishes whether the host is actually reachable this attempt — that
+ * `connected` bit, not the call duration, is what the retry policy keys on. Only on
+ * a reachable host do we run the interactive attach (which carries no credentials —
+ * the agent already runs on the peer — so it rides the normal transport). Returns
+ * the ssh exit code (255 = dropped again / unreachable; 0 = clean detach; other =
+ * session ended) plus whether this attempt connected.
+ */
+export declare function reattachRemoteSession(host: Host, sessionId: string): ReconnectOutcome;
+export interface ReconnectLoopOpts {
+    host: Host;
+    sessionId: string;
+    /** The exit code from the initial interactive run (which, having run the agent,
+     *  is treated as a connected attempt). */
+    initialExit: number;
+    /** Injected for tests: the real re-attach and wait are swapped for deterministic
+     *  fakes so the loop's control flow is exercised without SSH. Production uses the
+     *  real {@link reattachRemoteSession} + `sleep`. */
+    reattach?: (host: Host, sessionId: string) => ReconnectOutcome;
+    wait?: (ms: number) => Promise<void>;
+    write?: (s: string) => void;
+}
+/**
+ * Drive the reconnect loop from the initial run's outcome to a terminal code.
+ * Only the real SSH re-attach and the wait are side effects; the decision is
+ * {@link reconnectStep}. Returns the exit code the process should ultimately use.
+ */
+export declare function reconnectInteractiveSession(opts: ReconnectLoopOpts): Promise<number>;

package/dist/lib/hosts/reconnect.js

@@ -0,0 +1,127 @@
+/**
+ * Auto-reconnect for an interactive `agents run --device/--host` session whose
+ * SSH link dropped.
+ *
+ * A remote interactive agent runs in a DETACHED tmux session on the peer (see
+ * lib/exec.ts `runInTmux`), so a network blink kills only the local ssh client —
+ * the agent keeps running. `sshStream` reports that drop as exit code 255 (ssh's
+ * own connection-layer failure; see ssh-exec.ts). Without this, exec.ts would
+ * `process.exit(255)` and the user would have to notice, find the session id, and
+ * `agents sessions focus` by hand. Instead we re-attach the live remote pane over
+ * SSH automatically, with bounded backoff, until the user detaches cleanly (the
+ * remote returns 0) or the agent exits (the tmux session is gone; a non-255 code).
+ *
+ * The re-attach reuses the peer's OWN reconnect verb — `agents sessions focus <id>
+ * --local --attach-only` joins the live local tmux pane there (no fork, no resumed
+ * copy) — so there is no second re-attach implementation to keep in sync.
+ *
+ * **Why the budget refills on `connected`, not on call duration.** ssh returns 255
+ * for BOTH "couldn't connect at all" and "connected, then the link dropped." A
+ * failed connect still takes up to `ConnectTimeout` (10s) to return, so timing
+ * alone can't tell the two apart — a duration threshold below the connect timeout
+ * would classify every hung connect as a live session and retry forever under a
+ * sustained outage (the exact failure this feature exists to survive). Instead each
+ * attempt runs a fast preflight probe: a reattach that genuinely reconnected (and
+ * then dropped again) refills the retry budget; one that never reached the host
+ * counts against it, so a sustained outage gives up after MAX_ATTEMPTS.
+ *
+ * The retry policy is a pure state machine (`reconnectStep`) so it is unit-tested
+ * without touching SSH; the loop (`reconnectInteractiveSession`) only adds the real
+ * preflight + `sshStream` re-attach and the wait.
+ */
+import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
+import { sshTargetFor } from './types.js';
+/** ssh's connection-layer failure code — the signal that the link dropped rather
+ *  than the remote command exiting on its own. Mirrors ssh-exec.ts `sshStream`. */
+export const SSH_CONN_FAILURE = 255;
+/** Consecutive failed-to-connect reattaches before giving up. Backoff is capped at
+ *  {@link MAX_BACKOFF_MS}. A reattach that actually reconnected (then dropped again)
+ *  refills the budget, so a long session that blinks all day reconnects every time
+ *  — only consecutive UNREACHABLE attempts exhaust it. */
+export const MAX_ATTEMPTS = 6;
+const BASE_BACKOFF_MS = 2_000;
+const MAX_BACKOFF_MS = 30_000;
+export function initialReconnectState() {
+    return { attempt: 0 };
+}
+/** Exponential backoff capped at {@link MAX_BACKOFF_MS}: 2s, 4s, 8s, 16s, 30s… */
+export function backoffMs(attempt) {
+    return Math.min(BASE_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+}
+/**
+ * Decide what to do after a run/re-attach returned `outcome`. Pure — the only
+ * input is the prior state and the outcome, the only output is the next action.
+ *
+ *  - a non-255 code means the remote command spoke for itself (clean detach = 0,
+ *    agent exit / no live session = non-zero) → stop and surface that code.
+ *  - a 255 means the link dropped → retry, unless the budget is spent.
+ *  - a 255 from an attempt that DID connect (a genuine reconnection that then
+ *    dropped) refills the budget first; a 255 that never connected counts against
+ *    it, so a host that stays unreachable gives up after MAX_ATTEMPTS.
+ */
+export function reconnectStep(state, outcome) {
+    if (outcome.code !== SSH_CONN_FAILURE)
+        return { action: 'stop', code: outcome.code };
+    const attempts = outcome.connected ? 0 : state.attempt;
+    if (attempts >= MAX_ATTEMPTS)
+        return { action: 'stop', code: SSH_CONN_FAILURE };
+    return { action: 'retry', waitMs: backoffMs(attempts), state: { attempt: attempts + 1 } };
+}
+/** Human-readable notice shown before each reconnect wait. "13 seconds", not "12.8s". */
+export function reconnectNotice(sessionId, host, attempt, waitMs) {
+    const secs = Math.round(waitMs / 1000);
+    const when = secs <= 1 ? 'now' : `in ${secs} seconds`;
+    return `\nConnection to ${host} dropped — the agent is still running there. Reconnecting to ${sessionId.slice(0, 8)} ${when} (attempt ${attempt}/${MAX_ATTEMPTS})…\n`;
+}
+/** Notice shown once the retry budget is spent. */
+export function exhaustedNotice(sessionId, host) {
+    return `\nCouldn't reconnect to ${host} after ${MAX_ATTEMPTS} attempts. The agent may still be running — reattach when the network is back:\n  agents sessions focus ${sessionId.slice(0, 8)}\n`;
+}
+/**
+ * Re-attach the live remote tmux pane for `sessionId` by driving the peer's own
+ * `agents sessions focus`. A fast, un-multiplexed preflight probe (`ssh … true`)
+ * first establishes whether the host is actually reachable this attempt — that
+ * `connected` bit, not the call duration, is what the retry policy keys on. Only on
+ * a reachable host do we run the interactive attach (which carries no credentials —
+ * the agent already runs on the peer — so it rides the normal transport). Returns
+ * the ssh exit code (255 = dropped again / unreachable; 0 = clean detach; other =
+ * session ended) plus whether this attempt connected.
+ */
+export function reattachRemoteSession(host, sessionId) {
+    const target = sshTargetFor(host);
+    // Fresh (non-multiplexed) reachability probe: code 0 means the handshake actually
+    // completed, so a hung/failed connect is never mistaken for a live reconnection.
+    const probe = sshExec(target, 'true', { multiplex: false });
+    if (probe.code !== 0)
+        return { code: SSH_CONN_FAILURE, connected: false };
+    const remoteCmd = ['agents', 'sessions', 'focus', sessionId, '--local', '--attach-only']
+        .map(shellQuote)
+        .join(' ');
+    return { code: sshStream(target, remoteCmd, { tty: true }), connected: true };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Drive the reconnect loop from the initial run's outcome to a terminal code.
+ * Only the real SSH re-attach and the wait are side effects; the decision is
+ * {@link reconnectStep}. Returns the exit code the process should ultimately use.
+ */
+export async function reconnectInteractiveSession(opts) {
+    const write = opts.write ?? ((s) => process.stderr.write(s));
+    const wait = opts.wait ?? sleep;
+    const reattach = opts.reattach ?? reattachRemoteSession;
+    let state = initialReconnectState();
+    // The initial run reached the point of running the agent, so it connected.
+    let outcome = { code: opts.initialExit, connected: true };
+    for (;;) {
+        const decision = reconnectStep(state, outcome);
+        if (decision.action === 'stop') {
+            if (decision.code === SSH_CONN_FAILURE)
+                write(exhaustedNotice(opts.sessionId, opts.host.name));
+            return decision.code;
+        }
+        write(reconnectNotice(opts.sessionId, opts.host.name, decision.state.attempt, decision.waitMs));
+        await wait(decision.waitMs);
+        state = decision.state;
+        outcome = reattach(opts.host, opts.sessionId);
+    }
+}

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

@@ -1,29 +1,90 @@
 /**
- * Host provider registry.
+ * Host provider registry + the single host/device resolver.
  *
  * Mirrors the cloud provider registry: a Map of provider id → implementation,
- * 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.
+ * instantiated once. Registers `local` then `devices`; adding `rush`/`crabbox`
+ * later is a one-line `providers.set(...)`.
+ *
+ * Resolution used to fork into two disagreeing chains — a local-provider-first
+ * `resolveHost` (this file) and a devices-only `resolveSshTarget`
+ * (`../devices/resolve-target.ts`). They dialed different boxes for the same
+ * token (RUSH-1967). Now every caller goes through one core, {@link matchHost}:
+ * it merges the two directories per-FIELD instead of letting one provider
+ * shadow the other — the live devices registry supplies address/OS/presence,
+ * the agents.yaml overlay supplies caps/hints, and ssh_config supplies hosts
+ * Tailscale has never seen. The typed wrappers below (`resolveHost`) and in
+ * resolve-target.ts (`resolveExplicitTargets`, `resolveDeviceTarget`) differ
+ * only in what shape they hand back and which literal fallbacks they permit.
  */
 import type { Host, HostProvider, HostProviderId } from './types.js';
 import { DeviceOffloadUnsupportedError } from './types.js';
+import { type DeviceProfile } from '../devices/registry.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). */
+/**
+ * A resolved host, carrying the live {@link DeviceProfile} when the token
+ * matched a registered device (by normalized name). The device reference lets
+ * the `agents ssh` wrapper reach auth/shell/tailscale metadata a plain `Host`
+ * doesn't hold, and lets dispatch callers apply the device-only refusals
+ * (control device, password auth) without re-reading the registry.
+ */
+export interface ResolvedHost extends Host {
+    device?: DeviceProfile;
+    /** True when the host is a synthesized ad-hoc `user@host` / IP / FQDN literal
+     * (never registered) rather than a device or overlay/ssh-config match. Lets the
+     * strict `agents ssh` wrapper accept devices + literals but still report
+     * "Unknown device" for a bare ssh-config-only alias, as it always has. */
+    adhoc?: boolean;
+}
+/** Split a `user@host` / `host` token into its login user (if any) and host part. */
+export declare function splitUserHost(token: string): {
+    user?: string;
+    host: string;
+};
+/** Literal-fallback policy for {@link matchHost}. */
+export interface MatchHostOptions {
+    /**
+     * Also treat an unmatched dotted/colon host literal (a raw IP or FQDN with no
+     * `user@`) as an ad-hoc target. `agents ssh 1.2.3.4` sets this; dispatch and
+     * fan-out leave it off, so only a `user@host` is taken as an ad-hoc literal
+     * (a bare/dotted unknown is a miss, keeping capability-tag routing and the
+     * "Unknown device" verdict reachable).
+     */
+    allowBareLiteral?: boolean;
+}
+/**
+ * The one place a `--host` / `--device` token becomes a resolved host. Reads the
+ * devices registry, the agents.yaml overlay, and ssh_config, and merges them
+ * per-field (see {@link deviceHost}). One grammar for every caller: `name`,
+ * `user@name`, a tailnet FQDN, an ssh_config alias, and a literal `user@host`
+ * all resolve the same way regardless of which subcommand called.
+ *
+ * Non-throwing: returns null on an injection-guard failure or an unresolved bare
+ * token. Device-only refusals (control device, password auth) are NOT applied
+ * here — that is the dispatch wrapper's job ({@link resolveHost}), so the fan-out
+ * and `agents ssh` paths, which handle those cases differently, aren't forced
+ * into a dispatch verdict.
+ */
+export declare function matchHost(name: string, opts?: MatchHostOptions): Promise<ResolvedHost | null>;
+/** Every host across all registered providers, merged by name so a device's
+ * presence/dispatchable/address and an overlay's caps coexist on one row
+ * (RUSH-1967: first-wins dedup used to drop the device row, and its status/caps
+ * with it). Provider order still decides the base row (`local` first). */
 export declare function listAllHosts(): Promise<Host[]>;
 /**
- * Resolve a host name to a single host, or null if unknown. Resolution order:
- *   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
+ * Resolve a `--host`/`--device` token for DISPATCH — the shape every offload
+ * caller consumes (`run --host`, the generic passthrough, teams placement, the
+ * cloud host provider, doctor, funnel, remote secrets). Grammar and merge come
+ * from {@link matchHost}; on top, this layer applies the device-only dispatch
+ * refusals so they hold even when an inline overlay shadows the device:
+ *   - a control device (a paired iPhone) can never be a dispatch target;
+ *   - a password-auth device throws the typed {@link DeviceOffloadUnsupportedError}
+ *     (offload rides `BatchMode=yes` ssh, which can't answer a prompt);
+ *   - an addressless device has nothing to dial.
  *
- * 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
- * as an ad-hoc target.
+ * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`,
+ * e.g. `--host gpu`) stays reachable, and an ad-hoc `user@host` still resolves.
  */
 export declare function resolveHost(name: string): Promise<Host | null>;
 /**