@phnx-labs/agents-cli 1.20.74 → 1.20.77

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.d.ts

@@ -68,6 +68,17 @@ export declare const RUN_OPTION_REJECT_MESSAGES: Record<string, string>;
  * POSIX form, so linux/macos are byte-for-byte unchanged.
  */
 export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string, os?: string, env?: Record<string, string>): string;
+/**
+ * Build a POSIX `export K=V; …` prefix from an env map — empty string when the
+ * map is missing or empty. Values are rendered as shell LITERALS by default
+ * (single-quoted via {@link shellQuote}), so a `$(...)` or backtick in a value
+ * can never execute on the SSH target. Only {@link EXPAND_KEYS} (`PATH`) keep the
+ * expanding double-quote form (`\` and `"` escaped) so the remote `$HOME`/`$PATH`
+ * still resolve. Shared by {@link buildRemoteAgentsInvocation} and the
+ * detached/interactive dispatch builders (dispatch.ts) so every remote path
+ * exports env identically.
+ */
+export declare function posixEnvExports(env?: Record<string, string>): string;
 /** The two remote shell dialects we build commands for. */
 export type RemoteShell = 'posix' | 'powershell';
 /**

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',
@@ -143,18 +144,41 @@ export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd, os, env) {
     }
     const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
     const withCwd = remoteCwd ? `cd ${shellQuote(remoteCwd)} && ${inner}` : inner;
-    if (!env || Object.keys(env).length === 0) {
-        return `bash -lc ${shellQuote(withCwd)}`;
-    }
     // Prepend env exports so the remote command sees the shims dir even when the
     // login shell hasn't sourced the interactive rc files that usually add it.
-    // Values are double-quoted (not single-quoted) so remote variables like
-    // $HOME and $PATH are expanded by the login shell.
-    const exports = Object.entries(env)
-        .map(([k, v]) => `export ${shellQuote(k)}="${v.replace(/[\\"]/g, '\\$&')}"`)
-        .join('; ');
+    const exports = posixEnvExports(env);
+    if (!exports) {
+        return `bash -lc ${shellQuote(withCwd)}`;
+    }
     return `bash -lc ${shellQuote(`${exports}; ${withCwd}`)}`;
 }
+/**
+ * Keys whose values are trusted-static and legitimately need remote shell
+ * expansion — `PATH` references the remote `$HOME`/`$PATH`. Every other key is
+ * rendered as a shell literal, so an attacker-influenceable value (notably actor
+ * provenance, whose name/email can come from a tailnet peer's whois or an
+ * unvalidated `AGENTS_ACTOR_*` env var) can never inject shell into a dispatch.
+ */
+const EXPAND_KEYS = new Set(['PATH']);
+/**
+ * Build a POSIX `export K=V; …` prefix from an env map — empty string when the
+ * map is missing or empty. Values are rendered as shell LITERALS by default
+ * (single-quoted via {@link shellQuote}), so a `$(...)` or backtick in a value
+ * can never execute on the SSH target. Only {@link EXPAND_KEYS} (`PATH`) keep the
+ * expanding double-quote form (`\` and `"` escaped) so the remote `$HOME`/`$PATH`
+ * still resolve. Shared by {@link buildRemoteAgentsInvocation} and the
+ * detached/interactive dispatch builders (dispatch.ts) so every remote path
+ * exports env identically.
+ */
+export function posixEnvExports(env) {
+    if (!env || Object.keys(env).length === 0)
+        return '';
+    return Object.entries(env)
+        .map(([k, v]) => EXPAND_KEYS.has(k)
+        ? `export ${shellQuote(k)}="${v.replace(/[\\"]/g, '\\$&')}"`
+        : `export ${shellQuote(k)}=${shellQuote(v)}`)
+        .join('; ');
+}
 /**
  * Pick the remote shell dialect from a recorded OS/platform string. A Windows
  * host (device-registry `platform: 'windows'`, or an enrolled `HostEntry.os`

package/dist/lib/hosts/remote-session-id.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolve a remote-created session id back to an interactive `--host` launcher.
+ *
+ * A headless `--host` run captures the remote-coined id from the followed log
+ * (the `--emit-session-id` marker — see session-marker.ts). An INTERACTIVE run
+ * has no followed log: the local TTY is wired straight through `sshStream`
+ * (stdio:'inherit'), so nothing can tap the stream for a marker without breaking
+ * the agent's raw-mode TUI. Instead we correlate by AGENT_LAUNCH_ID.
+ *
+ * The launcher forwards a launch id it controls (`--env AGENT_LAUNCH_ID=<id>`);
+ * the remote `agents run` adopts it (exec.ts `resolveLaunchId`), so the remote
+ * SessionStart hook records the agent's REAL session id under that exact key in
+ * `~/.agents/.cache/terminals/sessions/<pid>.json`. After the stream returns we
+ * do ONE ssh read of that dir and pick the record whose `launch_id` matches —
+ * the same launch-id join `agents sessions --active` uses locally
+ * (session/hook-sessions.ts), just across the SSH hop.
+ *
+ * This gives the interactive path a real per-agent id to register in the local
+ * session index and to reconnect against, for Codex/Kimi/Grok/Gemini — closing
+ * the gap RUSH-2033 left for every non-Claude agent (Claude still forces its own
+ * id up front and never reaches here).
+ */
+/**
+ * Pick the real session id for `launchId` from the remote hook records.
+ *
+ * `recordsJson` is the newline-delimited JSON the remote read emits — one record
+ * per line (a `cat` of every `sessions/*.json`). Scan for the record whose
+ * `launch_id` matches and return its `session_id`; when several match (pid reuse,
+ * a lingering file) the NEWEST by `ts` wins, mirroring the local reader's
+ * keep-newest tie-break (session/hook-sessions.ts). Pure so the correlation is
+ * unit-testable from fixtures with no SSH. Returns undefined when no record
+ * carries the launch id (the hook hasn't landed yet, or a hookless harness).
+ */
+export declare function pickRemoteSessionId(recordsJson: string, launchId: string): string | undefined;
+/**
+ * Read the remote hook-session dir over ssh and resolve the real session id the
+ * remote run recorded under `launchId`. One round-trip, best-effort: any ssh
+ * failure, a missing dir, or an absent record yields undefined — the caller then
+ * keeps the un-mapped run rather than a fabricated id.
+ *
+ * `$HOME` expands on the REMOTE login shell (never the local box). The glob is a
+ * literal path with no user input, so it is injection-safe; a `2>/dev/null` on a
+ * globless dir keeps the command quiet when the dir is empty or absent.
+ */
+export declare function resolveRemoteSessionId(target: string, launchId: string, timeoutMs?: number): string | undefined;