@phnx-labs/agents-cli 1.20.73 → 1.20.76

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;

package/dist/lib/hosts/session-index.js

@@ -12,8 +12,12 @@
  * local run. The `[host/<name>]` label mirrors the cloud path's
  * `[cloud/<status>]` convention.
  */
+import * as fs from 'fs';
 import { upsertSession } from '../session/db.js';
 import { SESSION_AGENTS } from '../session/types.js';
+import { localLogPath, updateTask } from './tasks.js';
+import { parseSessionIdMarker } from './session-marker.js';
+import { deriveShortId } from '../session/short-id.js';
 /**
  * Build the SessionMeta for a host-dispatched run. Returns null when the run has
  * no captured session id (nothing stable to key/resume on) or its agent isn't a
@@ -27,7 +31,7 @@ export function hostSessionMeta(task, ctx) {
         return null;
     return {
         id,
-        shortId: id.slice(0, 8),
+        shortId: deriveShortId(id),
         agent: task.agent,
         timestamp: task.createdAt,
         cwd: ctx.cwd,
@@ -57,6 +61,37 @@ export function registerHostSession(task, ctx) {
         /* index write is best-effort; the run is already live on the host */
     }
 }
+/**
+ * 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 function captureRemoteSessionId(task) {
+    if (task.sessionId)
+        return null;
+    let text;
+    try {
+        text = fs.readFileSync(localLogPath(task.id), 'utf8');
+    }
+    catch {
+        return null; // no local mirror (unfollowed run, or read raced the follow)
+    }
+    const captured = parseSessionIdMarker(text);
+    if (!captured)
+        return null;
+    return updateTask(task.id, { sessionId: captured });
+}
 /**
  * Register an interactive host run (no prompt, TTY forwarded over SSH) in the
  * local session index. Unlike detached host runs, there is no remote log/exit
@@ -69,7 +104,7 @@ export function registerInteractiveHostSession(ctx) {
     try {
         upsertSession({
             id: ctx.sessionId,
-            shortId: ctx.sessionId.slice(0, 8),
+            shortId: deriveShortId(ctx.sessionId),
             agent: ctx.agent,
             timestamp: ctx.createdAt ?? new Date().toISOString(),
             cwd: ctx.cwd,

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

@@ -0,0 +1,33 @@
+/**
+ * Relate a remote-created session id back to the launching agent.
+ *
+ * A host dispatch (`agents run --host`) launches `agents run` on the remote box.
+ * Only Claude accepts a forced `--session-id`, so for every OTHER agent the
+ * remote run coins its OWN session id (via its SessionStart hook) and the
+ * launcher never learns it — the run is orphaned in `agents sessions`.
+ *
+ * This module closes that gap without an extra SSH round-trip: the dispatch
+ * forwards `--emit-session-id`, which makes the remote `agents run` print its
+ * resolved session id as a stable one-line sentinel to stdout. That line rides
+ * the same combined log the follow already mirrors locally, so the launcher
+ * parses the id straight out of the streamed output and stamps it on the task.
+ *
+ * The marker is a fixed ASCII frame with the id on its own line. A real session
+ * id (`[A-Za-z0-9._-]`) never contains the marker's own bytes, so the parser can
+ * scan for the LAST occurrence and stay robust to an agent echoing the token in
+ * its own output.
+ */
+/**
+ * The single line the remote run prints to stdout so the launcher can capture
+ * the session id the remote coined. Newline-framed on both sides so it lands on
+ * its own line regardless of what the agent last wrote.
+ */
+export declare function sessionIdMarkerLine(sessionId: string): string;
+/**
+ * Extract the session id from a chunk of followed remote output, or null when no
+ * marker is present. Scans for the LAST marker (so an id echoed into the log
+ * earlier can never mask the real trailing sentinel) and validates the captured
+ * token against the session-id charset — a malformed frame yields null rather
+ * than a bogus id that could never match a real session.
+ */
+export declare function parseSessionIdMarker(text: string): string | null;

package/dist/lib/hosts/session-marker.js

@@ -0,0 +1,51 @@
+/**
+ * Relate a remote-created session id back to the launching agent.
+ *
+ * A host dispatch (`agents run --host`) launches `agents run` on the remote box.
+ * Only Claude accepts a forced `--session-id`, so for every OTHER agent the
+ * remote run coins its OWN session id (via its SessionStart hook) and the
+ * launcher never learns it — the run is orphaned in `agents sessions`.
+ *
+ * This module closes that gap without an extra SSH round-trip: the dispatch
+ * forwards `--emit-session-id`, which makes the remote `agents run` print its
+ * resolved session id as a stable one-line sentinel to stdout. That line rides
+ * the same combined log the follow already mirrors locally, so the launcher
+ * parses the id straight out of the streamed output and stamps it on the task.
+ *
+ * The marker is a fixed ASCII frame with the id on its own line. A real session
+ * id (`[A-Za-z0-9._-]`) never contains the marker's own bytes, so the parser can
+ * scan for the LAST occurrence and stay robust to an agent echoing the token in
+ * its own output.
+ */
+const MARKER_PREFIX = '@@AGENTS_SESSION_ID ';
+const MARKER_SUFFIX = '@@';
+/** Only characters a real agent session id can hold — no marker bytes, no spaces. */
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+/**
+ * The single line the remote run prints to stdout so the launcher can capture
+ * the session id the remote coined. Newline-framed on both sides so it lands on
+ * its own line regardless of what the agent last wrote.
+ */
+export function sessionIdMarkerLine(sessionId) {
+    return `\n${MARKER_PREFIX}${sessionId}${MARKER_SUFFIX}\n`;
+}
+/**
+ * Extract the session id from a chunk of followed remote output, or null when no
+ * marker is present. Scans for the LAST marker (so an id echoed into the log
+ * earlier can never mask the real trailing sentinel) and validates the captured
+ * token against the session-id charset — a malformed frame yields null rather
+ * than a bogus id that could never match a real session.
+ */
+export function parseSessionIdMarker(text) {
+    const last = text.lastIndexOf(MARKER_PREFIX);
+    if (last === -1)
+        return null;
+    const start = last + MARKER_PREFIX.length;
+    const end = text.indexOf(MARKER_SUFFIX, start);
+    if (end === -1)
+        return null;
+    const id = text.slice(start, end).trim();
+    if (!SESSION_ID_RE.test(id))
+        return null;
+    return id;
+}

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

@@ -24,10 +24,14 @@ export interface HostTask {
      */
     name?: string;
     /**
-     * The agent session id the remote run was launched with (Claude only — the
-     * only agent that accepts `--session-id` to force a NEW session's id). Lets
-     * `agents sessions`/resume-by-id map a discovered session back to the host it
-     * lives on. Absent for agents that don't take an explicit session id.
+     * The remote run's agent session id, so `agents sessions`/resume-by-id can map
+     * a discovered session back to the host it lives on. Two sources: for Claude
+     * (the only agent that accepts `--session-id`) it's the id we FORCED at
+     * dispatch; for every other agent it's the id the remote COINED, captured from
+     * the run's stdout sentinel (`--emit-session-id`, see session-marker.ts) once
+     * the follow returns and stamped on the record via `captureRemoteSessionId`.
+     * Absent only until that capture lands — e.g. an unfollowed (`--no-follow`)
+     * non-Claude run whose id the reconcile path fills in later.
      */
     sessionId?: string;
     /** Remote paths (under the host's ~/.agents/.cache/hosts/). */

package/dist/lib/import.d.ts

@@ -111,3 +111,28 @@ export declare function importInstallScriptBinary(spec: AgentBinarySpec, version
  *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
  */
 export declare function resolvePackageDirFromBinary(binaryPath: string): string | null;
+/**
+ * Seed an ISOLATED version's home from the user's real `~/.<agent>` — the mirror of
+ * {@link importAgentConfig}, which adopts.
+ *
+ * The difference is the whole point: this COPIES and leaves the original in place,
+ * never symlinks it, never sets a default, never creates a shim. So an isolated copy
+ * can start from the setup the user already has instead of from nothing, which was
+ * the only way to get a working sandbox before.
+ *
+ * Credentials are skipped by default and reported, not silently included. An isolated
+ * copy is a separate principal — `agents add --isolated` already tells the user to
+ * sign in on first run — and copying tokens into it should be a choice, not a side
+ * effect of wanting your settings. `--with-auth` opts in.
+ */
+export declare function seedIsolatedConfigFromLocal(agentId: AgentId, version: string, opts?: {
+    withAuth?: boolean;
+    all?: boolean;
+}): {
+    seeded: boolean;
+    from: string;
+    to: string;
+    skippedAuth: string[];
+    skippedRuntime: string[];
+    error?: string;
+};