@phnx-labs/agents-cli 1.20.74 → 1.20.76

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>;
 /**

package/dist/lib/hosts/registry.js

@@ -1,15 +1,30 @@
 /**
- * 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 { DeviceOffloadUnsupportedError } from './types.js';
 import { LocalHostProvider } from './providers/local.js';
 import { DevicesHostProvider } from './providers/devices.js';
 import { assertValidSshTarget } from '../ssh-exec.js';
+import { normalizeHost } from '../machine-id.js';
+import { readMeta } from '../state.js';
+import { isSshConfigHost } from './ssh-config.js';
+import { resolveRemoteOsSync } from './remote-os.js';
+import { loadDevices, isControlDevice } from '../devices/registry.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 };
@@ -32,44 +47,204 @@ export function getAllProviders() {
     initProviders();
     return [...providers.values()];
 }
-/** Every host across all registered providers, deduped by name (first wins). */
+/** 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) {
+    const address = device.address.dnsName ?? device.address.ip;
+    return {
+        name: device.name,
+        provider: 'devices',
+        source: 'inline',
+        ...(address ? { address } : {}),
+        user: user ?? device.user,
+        os: device.platform !== 'unknown' ? device.platform : overlay?.os,
+        ...(overlay?.caps?.length ? { caps: overlay.caps } : {}),
+        enrolled: true,
+        status: deviceStatus(device),
+        dispatchable: device.auth.method !== 'password',
+        device,
+    };
+}
+/** 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,
+        provider: 'local',
+        enrolled: true,
+        source: entry.source,
+        ...(entry.address ? { address: entry.address } : {}),
+        user: user ?? entry.user,
+        ...(entry.os ? { os: entry.os } : {}),
+        ...(entry.caps?.length ? { caps: entry.caps } : {}),
+        ...(entry.addedAt ? { addedAt: entry.addedAt } : {}),
+        status: 'unknown',
+        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,
+        provider: 'local',
+        source: 'inline',
+        address: host,
+        ...(user ? { user } : {}),
+        status: 'unknown',
+        dispatchable: true,
+        adhoc: true,
+    };
+}
+/**
+ * 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 async function matchHost(name, opts = {}) {
+    try {
+        assertValidSshTarget(name);
+    }
+    catch {
+        return null;
+    }
+    const { user, host } = splitUserHost(name);
+    let reg;
+    try {
+        reg = await loadDevices();
+    }
+    catch {
+        reg = {};
+    }
+    const overlay = readMeta().hosts?.[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 seen = new Set();
-    const out = [];
+    const byName = new Map();
     for (const provider of getAllProviders()) {
         for (const host of await provider.list()) {
-            if (seen.has(host.name))
+            const prev = byName.get(host.name);
+            if (!prev) {
+                byName.set(host.name, host);
                 continue;
-            seen.add(host.name);
-            out.push(host);
+            }
+            // 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,
+                user: host.user ?? prev.user,
+                os: host.os ?? prev.os,
+                status: host.status ?? prev.status,
+                dispatchable: host.dispatchable ?? prev.dispatchable,
+            });
         }
     }
-    return out;
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
- * 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 async function resolveHost(name) {
-    for (const provider of getAllProviders()) {
-        const host = await provider.resolve(name);
-        if (host)
-            return host;
-    }
-    if (name.includes('@')) {
-        assertValidSshTarget(name);
-        const at = name.indexOf('@');
-        return { name, provider: 'local', source: 'inline', user: name.slice(0, at), address: name.slice(at + 1) };
+    const host = await matchHost(name);
+    if (!host)
+        return null;
+    if (host.device) {
+        if (isControlDevice(host.device)) {
+            throw new Error(`Device "${host.device.name}" is a control device (a cockpit), not an executor — it can't run agents. Dispatch to a worker device instead.`);
+        }
+        if (host.device.auth.method === 'password') {
+            throw new DeviceOffloadUnsupportedError(host.device.name);
+        }
+        if (!host.address) {
+            throw new Error(`Device "${host.device.name}" has no address (Tailscale DNS name or IP) to reach it by.`);
+        }
     }
-    return null;
+    return host;
 }
 /**
  * Resolve a host by capability tag (e.g. `--host gpu`). Returns the single

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

@@ -86,6 +86,7 @@ export const RUN_OPTION_FORWARDING = {
     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
+    emitSessionId: 'forward', // remote prints its session id as a stdout sentinel the launcher captures (session-marker.ts)
     // rejected — cannot cross the SSH boundary; fail loud, never degrade
     secrets: 'reject',
     secretsKeys: 'reject',

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

@@ -75,10 +75,18 @@ export interface HostPromptRun {
     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).
+ * Dispatch a headless prompt run onto a resolved host, then relate the run's
+ * session id back to this launcher for EVERY agent — not just Claude.
+ *
+ * Claude is the only agent that accepts a forced `--session-id`, so we mint one
+ * up front and know it immediately. For every other agent the remote run coins
+ * its OWN id; we forward `--emit-session-id` so the remote prints that id as a
+ * stdout sentinel (hosts/session-marker.ts), and once the follow returns we parse
+ * it out of the mirrored local log and stamp it on the task before registering —
+ * so `agents sessions`/resume-by-id can map the discovered session home. On
+ * resume the remote session keeps its existing id (passed through, no capture).
+ *
+ * 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>;

package/dist/lib/hosts/run-target.js

@@ -17,7 +17,7 @@
 import { randomUUID } from 'crypto';
 import { resolveHost, resolveHostByCap } from './registry.js';
 import { dispatchToHost } from './dispatch.js';
-import { registerHostSession } from './session-index.js';
+import { registerHostSession, captureRemoteSessionId } from './session-index.js';
 /**
  * Resolution failed with a user-actionable message the caller should print
  * verbatim. Distinct from `DeviceOffloadUnsupportedError` (which propagates to
@@ -54,14 +54,26 @@ export async function resolveHostRunTarget(name, opts = {}) {
     return host;
 }
 /**
- * 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).
+ * Dispatch a headless prompt run onto a resolved host, then relate the run's
+ * session id back to this launcher for EVERY agent — not just Claude.
+ *
+ * Claude is the only agent that accepts a forced `--session-id`, so we mint one
+ * up front and know it immediately. For every other agent the remote run coins
+ * its OWN id; we forward `--emit-session-id` so the remote prints that id as a
+ * stdout sentinel (hosts/session-marker.ts), and once the follow returns we parse
+ * it out of the mirrored local log and stamp it on the task before registering —
+ * so `agents sessions`/resume-by-id can map the discovered session home. On
+ * resume the remote session keeps its existing id (passed through, no capture).
+ *
+ * Returns the task record and the remote exit code (`-1` = follow window closed
+ * while the run continues).
  */
 export async function dispatchPromptToHost(host, opts) {
-    const sessionId = opts.agent === 'claude' && !opts.resume ? randomUUID() : undefined;
+    const forcedSessionId = opts.agent === 'claude' && !opts.resume ? randomUUID() : undefined;
+    // Ask the remote to print its resolved id whenever we did NOT force one (every
+    // non-Claude agent, and Claude-on-resume where the id is already known). No-op
+    // when the run isn't followed — nothing tails the log to catch the marker.
+    const emitSessionId = !forcedSessionId && !opts.resume && opts.follow !== false;
     const result = await dispatchToHost(host, {
         agent: opts.agent,
         prompt: opts.prompt,
@@ -69,7 +81,8 @@ export async function dispatchPromptToHost(host, opts) {
         mode: opts.mode,
         model: opts.model,
         remoteCwd: opts.remoteCwd,
-        sessionId,
+        sessionId: forcedSessionId,
+        emitSessionId,
         name: opts.name,
         resume: opts.resume,
         follow: opts.follow !== false,
@@ -94,6 +107,9 @@ export async function dispatchPromptToHost(host, opts) {
         passthroughArgs: opts.passthroughArgs,
         copyCreds: opts.copyCreds,
     });
-    registerHostSession(result.task, { cwd: opts.cwd ?? process.cwd(), prompt: opts.prompt });
-    return result;
+    // Capture the remote-coined id from the followed log (non-Claude); harmlessly a
+    // no-op when the task already carries a forced/resumed id or no marker landed.
+    const task = emitSessionId ? captureRemoteSessionId(result.task) ?? result.task : result.task;
+    registerHostSession(task, { cwd: opts.cwd ?? process.cwd(), prompt: opts.prompt });
+    return { ...result, task };
 }

package/dist/lib/hosts/session-index.d.ts

@@ -13,7 +13,7 @@
  * `[cloud/<status>]` convention.
  */
 import type { SessionMeta } from '../session/types.js';
-import type { HostTask } from './tasks.js';
+import { type HostTask } from './tasks.js';
 export interface HostSessionContext {
     /** Local directory the `agents run --host` was invoked from. */
     cwd: string;
@@ -32,6 +32,23 @@ export declare function hostSessionMeta(task: HostTask, ctx: HostSessionContext)
  * break the dispatch itself, which has already been launched on the host.
  */
 export declare function registerHostSession(task: HostTask, ctx: HostSessionContext): void;
+/**
+ * Relate a remote-created session id back to a followed host dispatch.
+ *
+ * The remote run (dispatched with `--emit-session-id`) prints its resolved id as
+ * a stdout sentinel (see session-marker.ts) that rides the followed log into the
+ * task's local mirror. Read that mirror, parse the id, and stamp it on the task
+ * so `findTaskBySessionId` and the session-index registration work for agents
+ * that never take a forced `--session-id` — closing the gap where every
+ * non-Claude host run was orphaned.
+ *
+ * Returns the updated task when an id was captured (and differs from what's on
+ * the record), else null. A task that already carries an id (Claude's forced id,
+ * a resume) is left untouched — the marker only fills a genuinely empty slot, so
+ * it can never overwrite an authoritative id with a stale echo. Best-effort: a
+ * missing/unreadable mirror or absent marker yields null, never an exception.
+ */
+export declare function captureRemoteSessionId(task: HostTask): HostTask | null;
 export interface InteractiveHostSessionContext {
     cwd: string;
     host: string;