@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/hosts/reconnect.js

@@ -1,64 +1,26 @@
-/**
- * Auto-reconnect for an interactive `agents run --device` session whose SSH link
- * dropped. ssh exit 255 triggers bounded-backoff re-attaches via the peer's own
- * `agents sessions focus <id> --local`, which joins a surviving tmux pane or
- * resumes the session in place. The retry window bounds unproductive streaks,
- * resetting when an attach reaches the host and holds the pane.
- *
- * A remote interactive session MUST be tmux-wrapped: with the wrap on, the agent
- * runs in a DETACHED tmux pane on the peer, so a blink kills only the ssh client
- * and the reattach rejoins the live pane; with it off, the agent is a child of
- * the sshd session and a blink SIGHUPs it, losing the in-flight turn (the
- * reattach then resumes the harness from disk). See lib/exec.ts `runInTmux`.
- */
 import { sshExec, sshStream, shellQuote, SSH_CONN_FAILURE_CODE } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { RUN_AUTO_KEYWORD } from '../types.js';
-/** ssh's connection-layer failure code — re-exported from ssh-exec.ts. */
 export const SSH_CONN_FAILURE = SSH_CONN_FAILURE_CODE;
-/**
- * ssh returns 255 for BOTH "couldn't connect" and "connected then dropped", so a
- * remote-origin 255 (the focus command's own exit) is remapped to 254 before the
- * reconnect loop sees it — inside the loop, 255 therefore always means a network
- * drop, never a code the remote command chose.
- */
 export const REMOTE_EXIT_255_REMAPPED = 254;
-/**
- * Wall-clock window bounding unproductive reconnect streaks, not the total
- * session. A reattach that reaches the host and holds resets the budget.
- */
 export const RECONNECT_WINDOW_MS = 15 * 60_000;
-/** Backoff curve: 2s, 4s, 8s, 16s, 30s, then 30s until the window closes. */
 const BASE_BACKOFF_MS = 2_000;
 const MAX_BACKOFF_MS = 30_000;
-/**
- * A genuine reconnection must hold the remote pane this long before refilling
- * the retry budget. It is the minimum time to clear TTY negotiation and confirm
- * a working session, distinguishing that from an attach that reconnects and
- * immediately re-drops; otherwise a flapping link would retry forever.
- */
 export const MIN_HOLD_MS = 10_000;
 export function initialReconnectState() {
     return { attempt: 0, unproductiveMs: 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);
 }
-/** True when the attempt both connected and held long enough to refill the budget. */
 export function refillsBudget(outcome) {
     return outcome.connected && outcome.heldMs >= MIN_HOLD_MS;
 }
-/**
- * Decide the next action from a run/re-attach outcome. Non-255 exits stop and
- * surface that code; 255 retries until the unproductive window is spent.
- */
 export function reconnectStep(state, outcome) {
     if (outcome.code !== SSH_CONN_FAILURE)
         return { action: 'stop', code: outcome.code };
     const productive = refillsBudget(outcome);
     const attempts = productive ? 0 : state.attempt;
-    // The attach's own duration counts against the window.
     const burned = productive ? 0 : state.unproductiveMs + outcome.heldMs;
     if (burned >= RECONNECT_WINDOW_MS)
         return { action: 'stop', code: SSH_CONN_FAILURE };
@@ -70,55 +32,38 @@ export function reconnectStep(state, outcome) {
         remainingMs: Math.max(0, RECONNECT_WINDOW_MS - (burned + waitMs)),
     };
 }
-/** "14m51s", "51s" — a duration a waiting human can read at a glance. */
 export function formatDuration(ms) {
     const total = Math.max(0, Math.round(ms / 1000));
     const m = Math.floor(total / 60);
     const sec = total % 60;
     return m > 0 ? `${m}m${String(sec).padStart(2, '0')}s` : `${sec}s`;
 }
-/** Notice shown before each reconnect wait. */
 export function reconnectNotice(target, host, attempt, waitMs, remainingMs) {
     const secs = Math.round(waitMs / 1000);
     const when = secs <= 1 ? 'now' : `in ${secs}s`;
-    // A tmux-wrapped run is still live; a bare run was SIGHUPed and focus will
-    // resume it from disk. This wording is truthful for either peer configuration.
     return `\nConnection to ${host} dropped — reconnecting to ${targetLabel(target)}.`
         + `\n  Reconnecting ${when} · ${formatDuration(remainingMs)} left · attempt ${attempt} · Ctrl-C to stop\n`;
 }
-/** Notice shown once the retry budget is spent on an unreachable host. */
 export function exhaustedNotice(target, host) {
     return `\nCouldn't reconnect to ${host} after ${formatDuration(RECONNECT_WINDOW_MS)}. The agent may still be running — get back in when the network is back:\n${recoveryHint(target, host)}`;
 }
-/** Notice shown when the host reconnects but drops again within {@link MIN_HOLD_MS}. */
 export function unstableNotice(target, host) {
     const secs = Math.round(MIN_HOLD_MS / 1000);
     return `\nGave up reconnecting to ${host} after ${formatDuration(RECONNECT_WINDOW_MS)} — it kept dropping again within ${secs} seconds of getting back in. The agent may still be running there; reconnect once the link is stable:\n${recoveryHint(target, host)}`;
 }
-/** Notice shown when a reattach ends with a remapped remote-side exit. */
 export function remoteExitNotice(target, host) {
     return `\nReattach to ${targetLabel(target)} on ${host} ended (not a network drop) — get back in, or check whether it's still live:\n${recoveryHint(target, host)}`;
 }
-/** Notice shown when the user stops the wait with Ctrl-C. */
 export function interruptedNotice(target, host) {
     return `\nStopped reconnecting to ${targetLabel(target)} on ${host}. Recover it when the link is stable:\n${recoveryHint(target, host)}`;
 }
-/**
- * Wrap `cmd` in `bash -lc` with an exit-code remap: 255 becomes
- * {@link REMOTE_EXIT_255_REMAPPED} so a remote-origin 255 cannot pass as ssh drop.
- */
 export function wrapRemoteExitCode(cmd) {
     const guarded = `${cmd}; rc=$?; [ "$rc" = "${SSH_CONN_FAILURE}" ] && rc=${REMOTE_EXIT_255_REMAPPED}; exit "$rc"`;
     return `bash -lc ${shellQuote(guarded)}`;
 }
-/** The short form shown to a human. Both kinds are uuid-shaped, so 8 chars reads the same. */
 function targetLabel(target) {
     return target.id.slice(0, 8);
 }
-/**
- * The command a user can run to re-enter a session after reconnect gives up.
- * The full id is printed on its own line so it remains copyable after a drop.
- */
 export function recoveryHint(target, host) {
     if (target.kind === 'session') {
         return `  Session ${target.id}\n  Resume:  agents sessions resume ${target.id}\n`;
@@ -126,37 +71,21 @@ export function recoveryHint(target, host) {
     return `  Launch ${target.id}\n  agents ssh ${host} 'agents sessions focus --launch-id ${target.id} --local'\n`
         + `  or pick it:  agents sessions --active\n`;
 }
-/**
- * Notice shown when an interactive remote connection ends and no auto-reconnect
- * follows. Prints the session id/handle so the user can get back in.
- */
 export function connectionEndedNotice(target, host, opts = {}) {
     const verb = opts.dropped ? 'dropped' : 'closed';
     return `\nConnection to ${host} ${verb}.\n${recoveryHint(target, host)}`;
 }
-/**
- * Banner printed as an interactive `--device` run takes the TTY, so the id is
- * visible in scrollback while the connection exists.
- */
 export function connectionStartedNotice(target, host) {
     if (target.kind !== 'session')
         return undefined;
     return `Session ${target.id} on ${host}\n  Resume later:  agents sessions resume ${target.id}\n`;
 }
-/**
- * The id to print as an interactive `--device` stream starts. `run auto` is
- * excluded because its forwarded id is only real when the remote picks Claude.
- */
 export function startConnectionTarget(opts) {
     if (opts.agent === RUN_AUTO_KEYWORD)
         return undefined;
     const id = opts.hostSessionId ?? opts.resumeId;
     return id ? { kind: 'session', id } : undefined;
 }
-/**
- * Decide what happens after an interactive `--device` stream returns. Auto-
- * reconnect fires on 255 unless `--raw` opted out; otherwise print recovery info.
- */
 export function afterInteractiveRemoteExit(opts) {
     if (!opts.target)
         return { reconnect: false, notice: undefined };
@@ -169,10 +98,6 @@ export function afterInteractiveRemoteExit(opts) {
         }),
     };
 }
-/**
- * Choose how to name the dropped run. `launchId` is last because it is minted
- * locally before the connection exists, so it survives the drop.
- */
 export function pickReconnectTarget(inputs) {
     const { agent, sessionId, resolvedId, resumeId, launchId } = inputs;
     const preferred = agent === RUN_AUTO_KEYWORD
@@ -183,10 +108,6 @@ export function pickReconnectTarget(inputs) {
         return { kind: 'session', id };
     return launchId ? { kind: 'launch', id: launchId } : undefined;
 }
-/**
- * The peer's recovery verb wrapped so a remote-origin 255 cannot masquerade as
- * a network drop. No `--attach-only`: focus resumes in place when no pane survived.
- */
 export function reattachRemoteCommand(target) {
     const selector = target.kind === 'launch'
         ? ['--launch-id', target.id]
@@ -196,30 +117,16 @@ export function reattachRemoteCommand(target) {
         .join(' ');
     return wrapRemoteExitCode(inner);
 }
-/**
- * Re-attach the live remote pane by driving the peer's `agents sessions focus`.
- * A fast preflight probe decides reachability; only then do we run the
- * interactive attach/resume. Returns the exit code, connected bit, and hold time.
- */
 function reattachRemoteSession(host, target) {
     const sshTarget = sshTargetFor(host);
     const extraSshArgs = hostIdentityArgs(host);
-    // Fresh (non-multiplexed) reachability probe: only a completed handshake is
-    // counted as connected.
     const probe = sshExec(sshTarget, 'true', { multiplex: false, extraSshArgs });
     if (probe.code !== 0)
         return { code: SSH_CONN_FAILURE, connected: false, heldMs: 0 };
-    // Timed from after the probe returns, so this measures only the attach itself.
     const startedAt = Date.now();
     const code = sshStream(sshTarget, reattachRemoteCommand(target), { tty: true, extraSshArgs });
     return { code, connected: true, heldMs: Date.now() - startedAt };
 }
-/**
- * Wait `ms`, but return early if the user interrupts.
- *
- * Installs a SIGINT handler only for the wait so Ctrl-C gives a graceful
- * "agent still running" message instead of killing the local process silently.
- */
 async function waitOrInterrupt(ms) {
     return new Promise((resolve) => {
         let done = false;
@@ -236,18 +143,15 @@ async function waitOrInterrupt(ms) {
         process.on('SIGINT', onSigint);
     });
 }
-/** Drive the reconnect loop from the initial run's outcome to a terminal code. */
 export async function reconnectInteractiveSession(opts) {
     const write = opts.write ?? ((s) => process.stderr.write(s));
     const wait = opts.wait ?? waitOrInterrupt;
     const reattach = opts.reattach ?? reattachRemoteSession;
     let state = initialReconnectState();
-    // The initial run connected; its hold duration doesn't matter at attempt 0.
     let outcome = { code: opts.initialExit, connected: true, heldMs: 0 };
     for (;;) {
         const decision = reconnectStep(state, outcome);
         if (decision.action === 'stop') {
-            // Spent budget: unreachable host vs. unstable link need different messages.
             if (decision.code === SSH_CONN_FAILURE) {
                 write(outcome.connected
                     ? unstableNotice(opts.target, opts.host.name)
@@ -257,14 +161,12 @@ export async function reconnectInteractiveSession(opts) {
                 write(remoteExitNotice(opts.target, opts.host.name));
             }
             else {
-                // Clean detach / agent exit: still print the session handle.
                 write(connectionEndedNotice(opts.target, opts.host.name));
             }
             return decision.code;
         }
         write(reconnectNotice(opts.target, opts.host.name, decision.state.attempt, decision.waitMs, decision.remainingMs));
         if (await wait(decision.waitMs) === 'interrupted') {
-            // User interrupted; the agent is still running on the peer.
             write(interruptedNotice(opts.target, opts.host.name));
             return 130;
         }

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

@@ -1,21 +1,3 @@
-/**
- * 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`; 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';
@@ -23,75 +5,19 @@ import { type DeviceAffinityPlan } from '../smart-launch.js';
 export { DeviceOffloadUnsupportedError };
 export declare function getProvider(id: HostProviderId): HostProvider;
 export declare function getAllProviders(): HostProvider[];
-/**
- * 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 refusal
- * (password auth) without re-reading the registry.
- */
 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;
-    /** Override the affinity pick for generic `auto` host resolution in tests.
-     * Harness-aware run/team placement resolves `auto` before reaching this core. */
     resolveAuto?: () => DeviceAffinityPlan;
 }
-/**
- * The one place a `--device` / `--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. The device-only refusal (password auth) is 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 `--device`/`--device` token for DISPATCH — the shape every offload
- * caller consumes (`run --device`, 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
- * refusal so it holds even when an inline overlay shadows the device:
- *   - 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`,
- * e.g. `--device gpu`) stays reachable, and an ad-hoc `user@host` still resolves.
- */
 export declare function resolveHost(name: string): Promise<Host | null>;
-/**
- * Resolve a host by capability tag (e.g. `--device gpu`). Returns the single
- * matching host, or throws on 0 or >1 matches unless `any` is set (then first).
- */
 export declare function resolveHostByCap(cap: string, any?: boolean): Promise<Host>;

package/dist/lib/hosts/registry.js

@@ -1,21 +1,3 @@
-/**
- * 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`; 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 { DeviceOffloadUnsupportedError } from './types.js';
 import { LocalHostProvider } from './providers/local.js';
 import { DevicesHostProvider } from './providers/devices.js';
@@ -30,8 +12,6 @@ import { resolveDeviceProfile } from '../devices/resolve-profile.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
 import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../devices/interactive-host.js';
 import { localMachineId } from '../session/origin-machine.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() {
@@ -52,47 +32,22 @@ export function getAllProviders() {
     initProviders();
     return [...providers.values()];
 }
-/** Split a `user@host` / `host` token into its login user (if any) and host part. */
 export function splitUserHost(token) {
     const at = token.indexOf('@');
     return at === -1 ? { host: token } : { user: token.slice(0, at), host: token.slice(at + 1) };
 }
-/** True when a token is clearly a network target (a `user@`, or a dotted/IPv6
- * host / IP) rather than a bare alias. A bare unknown word is a typo, so a
- * strict caller (`agents ssh foo`) reports "Unknown device" instead of dialing
- * a literal `foo`. */
 function looksLikeHostLiteral(token) {
     return token.includes('@') || token.includes('.') || token.includes(':');
 }
-/**
- * Match a host part (the piece after any `user@`) to a registered device: exact
- * registry key first, then a normalized-host match so `yosemite-s0` and
- * `yosemite-s0.<tailnet>.ts.net` land on the same profile. This normalized
- * grammar used to live only in the devices chain (RUSH-1967 divergence #3/#4);
- * it is now shared by every caller.
- */
 function matchDevice(host, reg) {
     return reg[host] ?? Object.values(reg).find((d) => normalizeHost(d.name) === normalizeHost(host));
 }
-/** Tailscale's own presence bit for a device, when the sync captured one. */
 function deviceStatus(device) {
     if (!device.tailscale)
         return 'unknown';
     return device.tailscale.online ? 'online' : 'offline';
 }
-/**
- * Merge a matched device with any same-name agents.yaml overlay into one Host,
- * per-FIELD (the core of the RUSH-1967 fix). The live registry owns address, OS
- * and presence — so `agents devices sync` takes effect without re-enrolling and
- * an enrolled route can never freeze — while the overlay contributes capability
- * tags (the reason to enroll at all) and an OS hint when the device platform is
- * unknown. `dispatchable` follows the device's auth method, so a password-auth
- * device can never be made dispatchable by shadowing it with an inline entry.
- */
 function deviceHost(device, user, overlay) {
-    // Effective profile: the central config's ssh.*/platform keys overlay the
-    // discovery record, so an operator edit via `agents devices config` is
-    // honored at dispatch time.
     const resolved = resolveDeviceProfile(device);
     const address = resolved.address.dnsName ?? resolved.address.ip;
     return {
@@ -110,9 +65,6 @@ function deviceHost(device, user, overlay) {
         device: resolved,
     };
 }
-/** Build a Host from a bare overlay entry (inline or ssh-config), applying any
- * `user@` override. Inline/ssh-config hosts authenticate over key / ssh-config,
- * so they are dispatchable; presence is unknown without an explicit probe. */
 function overlayHost(name, entry, user) {
     return {
         name,
@@ -128,8 +80,6 @@ function overlayHost(name, entry, user) {
         dispatchable: true,
     };
 }
-/** Synthesize an ad-hoc inline Host for a `user@host` / `host` literal so a box
- * that was never registered still dials. sshTargetFor emits `user@address`. */
 function literalHost(token, host, user) {
     return {
         name: token,
@@ -142,27 +92,7 @@ function literalHost(token, host, user) {
         adhoc: true,
     };
 }
-/**
- * The one place a `--device` / `--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. The device-only refusal (password auth) is 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 async function matchHost(name, opts = {}) {
-    // Generic host-only callers resolve `auto` through the affinity engine here;
-    // harness-aware run/team placement resolves it earlier with live probes. A
-    // `null` plan.host means the affinity engine picked this
-    // very machine; resolve that as the local device/host entry (if any) rather than
-    // returning nothing — callers that already special-case "target is this
-    // machine" (teams add/create, the passthrough self-host check) then treat it as
-    // local exactly as they would if the user had typed the local name.
     if (isDeviceInteractive(name)) {
         const pinned = resolveInteractiveDevice();
         if (!pinned)
@@ -188,34 +118,21 @@ export async function matchHost(name, opts = {}) {
     catch {
         reg = {};
     }
-    // The effective host overlay is the cross-box union of every device doc's
-    // `hosts:` block (PHNX-3315), plus any lingering central-legacy entry.
     const overlay = { ...readMeta().hosts, ...unionDeviceHosts() }[host];
-    // 1. A registered device (normalized match) — its live address/OS/presence win.
     const device = matchDevice(host, reg);
     if (device)
         return deviceHost(device, user, overlay);
-    // 2. An agents.yaml overlay entry keyed by the host part (inline or ssh-config).
     if (overlay)
         return overlayHost(host, overlay, user);
-    // 3. A bare ssh_config alias Tailscale has never seen — dial by name (ssh
-    //    applies the stanza). A `user@alias` is handled as a literal below so the
-    //    `user@` reaches ssh, which overrides the stanza's User.
     if (!user && isSshConfigHost(host)) {
         return { name: host, provider: 'local', source: 'ssh-config', os: resolveRemoteOsSync(host), status: 'unknown', dispatchable: true };
     }
-    // 4. An ad-hoc literal target. `user@host` always; a bare IP/FQDN only when the
-    //    caller opted in (`agents ssh`). A bare unknown word is a miss (null).
     if (name.includes('@') || (opts.allowBareLiteral && looksLikeHostLiteral(name))) {
         assertValidSshTarget(name);
         return literalHost(name, host, user);
     }
     return 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 async function listAllHosts() {
     const byName = new Map();
     for (const provider of getAllProviders()) {
@@ -225,14 +142,6 @@ export async function listAllHosts() {
                 byName.set(host.name, host);
                 continue;
             }
-            // Same name from a later provider (a device behind an enrolled overlay):
-            // `prev` is the local/overlay row (`local` registers first), `host` is the
-            // live device row. Keep the overlay's caps/source/addedAt as the base, but
-            // the DEVICE wins every field it owns — address, user, OS, presence and
-            // dispatchable — so this matches `deviceHost()`'s per-field precedence and
-            // an enrolled device can never serve a frozen address. Getting this
-            // backwards reintroduced the frozen route through `resolveHostByCap`,
-            // which hands a `listAllHosts()` row straight to dispatch.
             byName.set(host.name, {
                 ...prev,
                 address: host.address ?? prev.address,
@@ -245,19 +154,6 @@ export async function listAllHosts() {
     }
     return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
-/**
- * Resolve a `--device`/`--device` token for DISPATCH — the shape every offload
- * caller consumes (`run --device`, 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
- * refusal so it holds even when an inline overlay shadows the device:
- *   - 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`,
- * e.g. `--device gpu`) stays reachable, and an ad-hoc `user@host` still resolves.
- */
 export async function resolveHost(name) {
     const host = await matchHost(name);
     if (!host)
@@ -272,13 +168,7 @@ export async function resolveHost(name) {
     }
     return host;
 }
-/**
- * Resolve a host by capability tag (e.g. `--device gpu`). Returns the single
- * matching host, or throws on 0 or >1 matches unless `any` is set (then first).
- */
 export async function resolveHostByCap(cap, any = false) {
-    // 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}". See registered devices: agents devices list`);