@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/hosts/reconnect.js

@@ -4,12 +4,24 @@
  *
  * 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
+ * the agent keeps running.
+ *
+ * **That premise is a guarantee, not a hope, only since RUSH-3125.** It used to
+ * rest on the peer's `tmux.enabled`, an ergonomics preference that defaults OFF
+ * — so on a default box the agent was a child of the sshd session, a blink
+ * SIGHUPed it, and this file reconnected to a corpse while telling the user it
+ * was "still running there." The interactive dispatch now exports
+ * REMOTE_INTERACTIVE_ENV and exec.ts `resolveTmuxWrap` wraps on it regardless of
+ * that toggle, so what is written below actually holds. Anything that would let
+ * a remote interactive run reach the peer unwrapped breaks this whole file.
+ *
+ * `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).
+ * remote returns 0), the agent exits (the tmux session is gone; a non-255 code),
+ * or the user interrupts the wait with Ctrl-C ({@link waitOrInterrupt} → 130).
  *
  * The re-attach reuses the peer's OWN recovery verb — `agents sessions focus <id>
  * --local` — which JOINS the live local tmux pane there (a second client, no fork)
@@ -32,7 +44,8 @@
  * {@link MIN_HOLD_MS} refills the retry budget, so a long session that blinks all
  * day keeps reconnecting. Everything else — never reached the host, or reached it
  * and died right back — counts against the budget, so a sustained outage and a
- * fast-flapping link both give up after {@link MAX_ATTEMPTS}.
+ * fast-flapping link both give up once {@link RECONNECT_WINDOW_MS} of unproductive
+ * retrying has elapsed.
  *
  * The retry policy is a pure state machine (`reconnectStep`) so it is unit-tested
  * without touching SSH; the loop (`reconnectInteractiveSession`) only adds the real
@@ -47,7 +60,7 @@
  * that same 255, `reconnectStep` couldn't tell it apart from a genuine drop, and
  * `connected: true` would refill the retry budget forever — "attempt 1/N" printed
  * on every single cycle, the terminal filling with aborted-TTY escape-code
- * garbage, `MAX_ATTEMPTS` never actually bounding anything.
+ * garbage, the retry window never actually bounding anything.
  *
  * The resume fall-through only widens that surface — the peer's focus now runs a
  * full recovery path (`resumeSessionInPlace` / `runOnPeer`) on a dead pane, any
@@ -63,8 +76,8 @@
  * remap alone did not close it (agents-cli#1884): `connected` was set by the
  * preflight probe and said nothing about whether the attach that followed held, so
  * a fast-flapping link — or an attach that died at the TTY-negotiation stage every
- * single time — refilled the budget on every cycle, printed "attempt 1/N" forever,
- * and left `MAX_ATTEMPTS` bounding nothing. The {@link MIN_HOLD_MS} floor above is
+ * single time — refilled the budget on every cycle, printed "attempt 1" forever,
+ * and left the retry window bounding nothing. The {@link MIN_HOLD_MS} floor above is
  * what closes it: an attach that dies immediately is not a reconnection, so the
  * budget drains and the loop gives up with {@link unstableNotice}. A flat total-
  * attempt or wall-clock ceiling that ignored `connected` was the alternative and is
@@ -72,21 +85,37 @@
  * session this feature exists for, while the hold floor only ever stops a loop that
  * is failing to put the user back into the agent.
  */
-import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
+import { sshExec, sshStream, shellQuote, SSH_CONN_FAILURE_CODE } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
+import { RUN_AUTO_KEYWORD } from '../types.js';
 /** ssh's connection-layer failure code — 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;
+ *  than the remote command exiting on its own. Re-exported from ssh-exec.ts, which
+ *  owns the ssh invocation, so the two cannot drift apart. */
+export const SSH_CONN_FAILURE = SSH_CONN_FAILURE_CODE;
 /** What a would-be-255 remote-origin exit code is remapped to by
  *  {@link wrapRemoteExitCode} — see the file header. Never produced by the ssh
  *  transport itself, so it can never be confused with {@link SSH_CONN_FAILURE}. */
 export const REMOTE_EXIT_255_REMAPPED = 254;
-/** Consecutive unproductive reattaches before giving up. Backoff is capped at
- *  {@link MAX_BACKOFF_MS}. A reattach that reconnected and HELD (then dropped again)
- *  refills the budget, so a long session that blinks all day reconnects every time —
- *  an attempt that never reached the host, or reached it and died back inside
- *  {@link MIN_HOLD_MS}, counts against it. */
-export const MAX_ATTEMPTS = 6;
+/**
+ * How long the loop keeps trying across an UNPRODUCTIVE streak before giving up.
+ *
+ * A wall-clock window, not an attempt count, because what it has to outlast is
+ * measured in minutes: a laptop lid close, a Wi-Fi handoff, a VPN or Tailscale
+ * re-auth, a router reboot. The previous `MAX_ATTEMPTS = 6` over a 2/4/8/16/30/30
+ * backoff gave up after about **90 seconds** — shorter than any of them
+ * (RUSH-3125). Worse, timers are suspended across sleep, so on wake the whole
+ * backoff fired back-to-back before the network was up and the budget was gone in
+ * seconds.
+ *
+ * It bounds the STREAK, not the session: a reattach that reconnects and HOLDS
+ * resets it to zero ({@link refillsBudget}), so a session that blinks all day
+ * still reconnects every time. That is the property the file header insists on,
+ * and a flat total would break it — this changes only how a *streak* is bounded.
+ */
+export const RECONNECT_WINDOW_MS = 15 * 60_000;
+/** Backoff curve for a streak: 2s, 4s, 8s, 16s, 30s, then 30s until the window
+ *  closes. Capped so a long outage keeps probing at a useful cadence instead of
+ *  drifting out to multi-minute gaps and missing the moment the link returns. */
 const BASE_BACKOFF_MS = 2_000;
 const MAX_BACKOFF_MS = 30_000;
 /** How long a reattach must hold the remote pane before it counts as a genuine
@@ -98,7 +127,7 @@ const MAX_BACKOFF_MS = 30_000;
  *  should stop retrying, not one it should keep re-entering. */
 export const MIN_HOLD_MS = 10_000;
 export function initialReconnectState() {
-    return { attempt: 0 };
+    return { attempt: 0, unproductiveMs: 0 };
 }
 /** Exponential backoff capped at {@link MAX_BACKOFF_MS}: 2s, 4s, 8s, 16s, 30s… */
 export function backoffMs(attempt) {
@@ -124,27 +153,55 @@ export function refillsBudget(outcome) {
  *  - a 255 from an attempt that reconnected AND held ({@link refillsBudget})
  *    refills the budget first; every other 255 counts against it, so a host that
  *    stays unreachable — and a link that keeps dropping the attach immediately —
- *    both give up after MAX_ATTEMPTS.
+ *    both give up once the retry window closes.
  */
 export function reconnectStep(state, outcome) {
     if (outcome.code !== SSH_CONN_FAILURE)
         return { action: 'stop', code: outcome.code };
-    const attempts = refillsBudget(outcome) ? 0 : state.attempt;
-    if (attempts >= MAX_ATTEMPTS)
+    const productive = refillsBudget(outcome);
+    const attempts = productive ? 0 : state.attempt;
+    // The attach's own duration counts against the window: a 10s connect timeout
+    // burned on every attempt is real elapsed time the user is waiting, and
+    // ignoring it would stretch a "15 minute" window well past fifteen minutes.
+    const burned = productive ? 0 : state.unproductiveMs + outcome.heldMs;
+    if (burned >= RECONNECT_WINDOW_MS)
         return { action: 'stop', code: SSH_CONN_FAILURE };
-    return { action: 'retry', waitMs: backoffMs(attempts), state: { attempt: attempts + 1 } };
+    const waitMs = backoffMs(attempts);
+    return {
+        action: 'retry',
+        waitMs,
+        state: { attempt: attempts + 1, unproductiveMs: burned + waitMs },
+        remainingMs: Math.max(0, RECONNECT_WINDOW_MS - (burned + waitMs)),
+    };
 }
-/** Human-readable notice shown before each reconnect wait. "13 seconds", not "12.8s". */
-export function reconnectNotice(sessionId, host, attempt, waitMs) {
+/** "14m51s", "51s" — a duration a waiting human can read at a glance. */
+export function formatDuration(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const m = Math.floor(total / 60);
+    const sec = total % 60;
+    return m > 0 ? `${m}m${String(sec).padStart(2, '0')}s` : `${sec}s`;
+}
+/**
+ * Notice shown before each reconnect wait.
+ *
+ * Says how long is left in the window rather than "attempt 2/6": with a
+ * wall-clock budget the attempt number no longer tells the user when this stops,
+ * and "how much longer will it keep trying" is the actual question during an
+ * outage. Ctrl-C is advertised because a user who wants their shell back should
+ * not have to guess whether interrupting is safe — it is (the agent keeps
+ * running on the peer, which is the whole point).
+ */
+export function reconnectNotice(target, host, attempt, waitMs, remainingMs) {
     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`;
+    const when = secs <= 1 ? 'now' : `in ${secs}s`;
+    return `\nConnection to ${host} dropped — ${targetLabel(target)} is still running there.`
+        + `\n  Reconnecting ${when} · ${formatDuration(remainingMs)} left · attempt ${attempt} · Ctrl-C to stop\n`;
 }
 /** Notice shown once the retry budget is spent on a host that stayed UNREACHABLE.
  *  Hands back the one verb that re-enters the terminal — attach the live pane if it
  *  survived, else resume. */
-export function exhaustedNotice(sessionId, host) {
-    return `\nCouldn't reconnect to ${host} after ${MAX_ATTEMPTS} attempts. The agent may still be running — get back in when the network is back:\n  agents reconnect ${sessionId.slice(0, 8)}\n`;
+export function exhaustedNotice(target, host) {
+    return `\nCouldn't reconnect to ${host} after ${formatDuration(RECONNECT_WINDOW_MS)}. The agent may still be running — get back in when the network is back:\n${recoveryHint(target, host)}`;
 }
 /** Notice shown when the budget is spent the OTHER way: the last reattach reached
  *  the host and the connection dropped again within {@link MIN_HOLD_MS}. Saying
@@ -152,17 +209,23 @@ export function exhaustedNotice(sessionId, host) {
  *  — and the user needs to know the link, not the host, is the problem. It claims
  *  no count of successful reconnections: the budget can also be spent by a run of
  *  unreachable attempts followed by one that reconnected and dropped straight out. */
-export function unstableNotice(sessionId, host) {
+export function unstableNotice(target, host) {
     const secs = Math.round(MIN_HOLD_MS / 1000);
-    return `\nGave up reconnecting to ${host} after ${MAX_ATTEMPTS} attempts — it kept dropping again within ${secs} seconds of getting back in. The agent may still be running there; reconnect once the link is stable:\n  agents reconnect ${sessionId.slice(0, 8)}\n`;
+    return `\nGave up reconnecting to ${host} after ${formatDuration(RECONNECT_WINDOW_MS)} — it kept dropping again within ${secs} seconds of getting back in. The agent may still be running there; reconnect once the link is stable:\n${recoveryHint(target, host)}`;
 }
 /** Notice shown when a reattach stops on a remapped remote-side exit
  *  ({@link REMOTE_EXIT_255_REMAPPED} — a would-be-255 the remote command decided
  *  on for its own reasons, not the ssh transport dropping; see
  *  {@link wrapRemoteExitCode}). Distinct from {@link exhaustedNotice}, which is
  *  only for a genuinely spent retry budget. */
-export function remoteExitNotice(sessionId, host) {
-    return `\nReattach to ${sessionId.slice(0, 8)} on ${host} ended (not a network drop) — get back in, or check whether it's still live:\n  agents reconnect ${sessionId.slice(0, 8)}\n`;
+export function remoteExitNotice(target, host) {
+    return `\nReattach to ${targetLabel(target)} on ${host} ended (not a network drop) — get back in, or check whether it's still live:\n${recoveryHint(target, host)}`;
+}
+/** Shown when the user Ctrl-Cs out of the wait. The agent is untouched — it is
+ *  detached on the peer — so this says how to get back rather than implying the
+ *  work was lost. */
+export function interruptedNotice(target, host) {
+    return `\nStopped reconnecting. ${targetLabel(target)} is still running on ${host}:\n${recoveryHint(target, host)}`;
 }
 /**
  * Wrap `cmd` in `bash -lc` (the login-shell pattern `buildRemoteAgentsInvocation`
@@ -185,18 +248,138 @@ export function wrapRemoteExitCode(cmd) {
     const guarded = `${cmd}; rc=$?; [ "$rc" = "${SSH_CONN_FAILURE}" ] && rc=${REMOTE_EXIT_255_REMAPPED}; exit "$rc"`;
     return `bash -lc ${shellQuote(guarded)}`;
 }
+/** The short form shown to a human. Both kinds are uuid-shaped, so 8 chars reads the same. */
+export function targetLabel(target) {
+    return target.id.slice(0, 8);
+}
+/**
+ * The command to hand a user whose reconnect gave up.
+ *
+ * A `session` target has a real id, so `agents sessions resume <id>` does the
+ * same attach-else-recover the loop was attempting. The full id is labeled on
+ * its own `Session` line, not only inside the command (RUSH-3227). (It used to
+ * say `agents reconnect`, which is deprecated and hidden — `commands/reconnect.ts`
+ * — so the advice printed at the worst possible moment was itself stale; RUSH-3125.)
+ *
+ * A `launch` target has no id a user-facing verb accepts: the mapping lives in
+ * the peer's hook records, which is exactly why reconnect uses it. So point at
+ * the peer's own resolver rather than inventing a launch-id selector on every
+ * local command for a string no human ever types.
+ */
+export function recoveryHint(target, host) {
+    // The full id is labeled on its own line: burying it only inside a command is
+    // how a dropped SSH tab used to land on a bare shell with nothing copyable
+    // (RUSH-3227). Resume still sits underneath so the user can paste one verb.
+    if (target.kind === 'session') {
+        return `  Session ${target.id}\n  Resume:  agents sessions resume ${target.id}\n`;
+    }
+    return `  Launch ${target.id}\n  agents ssh ${host} 'agents sessions focus --launch-id ${target.id} --local'\n`
+        + `  or pick it:  agents sessions --active\n`;
+}
+/**
+ * Notice shown when an interactive remote connection has ended and the user is
+ * back at a local shell — clean detach, agent exit, or a drop that is NOT
+ * about to auto-reconnect. The OpenSSH close line (`Shared connection to …
+ * closed.`) names the host and nothing else; this is the handle they need to
+ * get back in (RUSH-3227).
+ */
+export function connectionEndedNotice(target, host, opts = {}) {
+    const verb = opts.dropped ? 'dropped' : 'closed';
+    return `\nConnection to ${host} ${verb}.\n${recoveryHint(target, host)}`;
+}
+/**
+ * Banner printed when an interactive `--device` run whose session id is already
+ * known (Claude's forced id, or a resume) is about to take the TTY. The TUI
+ * will cover this; it survives in scrollback so the id exists *while* the
+ * connection exists, not only after it dies (RUSH-3227 plan B). Launch-id
+ * targets are not a resume handle — do not print them here.
+ */
+export function connectionStartedNotice(target, host) {
+    if (target.kind !== 'session')
+        return undefined;
+    return `Session ${target.id} on ${host}\n  Resume later:  agents sessions resume ${target.id}\n`;
+}
+/**
+ * The id to print as an interactive `--device` stream starts. Resume is a
+ * real session id (`resolveHostSessionId` returns undefined on `--resume`);
+ * Claude's forced id is the other. `run auto` is excluded: its forwarded
+ * `--session-id` is only real if the remote pick is Claude.
+ */
+export function startConnectionTarget(opts) {
+    if (opts.agent === RUN_AUTO_KEYWORD)
+        return undefined;
+    const id = opts.hostSessionId ?? opts.resumeId;
+    return id ? { kind: 'session', id } : undefined;
+}
+/**
+ * Decide what happens after an interactive `--device` stream returns.
+ *
+ * Auto-reconnect only when the link dropped (255) AND the run is tmux-hosted
+ * (`willReconnect`). `--raw` is not wrapped, so it never reconnects — but it
+ * still prints the session id: the user is at a shell, and EXEC-55 does not
+ * exempt raw (RUSH-3227). Bundling the notice behind `!isRaw` was the miss.
+ */
+export function afterInteractiveRemoteExit(opts) {
+    if (!opts.target)
+        return { reconnect: false, notice: undefined };
+    if (opts.willReconnect)
+        return { reconnect: true, notice: undefined };
+    return {
+        reconnect: false,
+        notice: connectionEndedNotice(opts.target, opts.host, {
+            dropped: opts.exitCode === SSH_CONN_FAILURE,
+        }),
+    };
+}
+/**
+ * Choose how to name the dropped run when going back for it.
+ *
+ * Order matters, and the last clause is the fix (RUSH-3125):
+ *
+ *  1. `run auto` prefers `resolvedId` — the harness the remote ACTUALLY picked,
+ *     which the launcher's own `--session-id` (adopted only by Claude) may not
+ *     name. Every other agent prefers the id the launcher forced.
+ *  2. `resumeId` covers a run that was continuing a known session.
+ *  3. **`launchId` last, and it is what makes this work at all off-Claude.**
+ *     Every id above either came from the launcher or was read back over SSH —
+ *     and that read happens after the stream returned, i.e. over the link that
+ *     just died, so on a real drop it yields nothing. Falling through to the
+ *     launch id means the reconnect no longer depends on reaching the host to
+ *     learn what to reconnect to; the peer resolves it locally instead.
+ *
+ * Returns undefined only when the launcher has no handle at all (a hookless
+ * harness with no forced id), which is the one case reconnect genuinely cannot
+ * serve. Pure, so the precedence is unit-tested without SSH.
+ */
+export function pickReconnectTarget(inputs) {
+    const { agent, sessionId, resolvedId, resumeId, launchId } = inputs;
+    const preferred = agent === RUN_AUTO_KEYWORD
+        ? resolvedId ?? sessionId
+        : sessionId ?? resolvedId;
+    const id = preferred ?? resumeId;
+    if (id)
+        return { kind: 'session', id };
+    return launchId ? { kind: 'launch', id: launchId } : undefined;
+}
 /**
  * The remote command a reattach runs — the peer's own recovery verb
- * (`agents sessions focus <id> --local`), wrapped by {@link wrapRemoteExitCode}
+ * (`agents sessions focus … --local`), wrapped by {@link wrapRemoteExitCode}
  * so a stray remote-origin 255 (from this command, whatever produces it — see the
  * file header) can never masquerade as a network drop. No `--attach-only`: focus
  * joins the live pane when it survived, else RESUMES the session in place, so a
  * reattach landing after the pane died recovers the agent instead of dead-ending
  * (RUSH-2085). Split out from {@link reattachRemoteSession} so it is unit-tested
  * without SSH — mirrors `remoteAgentsJsonCommand` in lib/remote-agents-json.ts.
+ *
+ * A `launch` target passes `--launch-id`, which focus resolves against the hook
+ * records on the peer itself — no network read from this side, which is the
+ * whole point (see {@link ReconnectTarget}).
  */
-export function reattachRemoteCommand(sessionId) {
-    const inner = ['agents', 'sessions', 'focus', sessionId, '--local']
+export function reattachRemoteCommand(target) {
+    const selector = target.kind === 'launch'
+        ? ['--launch-id', target.id]
+        : [target.id];
+    const inner = ['agents', 'sessions', 'focus', ...selector, '--local', '--reconnect-reattach']
         .map(shellQuote)
         .join(' ');
     return wrapRemoteExitCode(inner);
@@ -212,22 +395,49 @@ export function reattachRemoteCommand(sessionId) {
  * clean detach; other = session ended), whether this attempt connected, and how
  * long the attach held — the two inputs {@link refillsBudget} decides on.
  */
-export function reattachRemoteSession(host, sessionId) {
-    const target = sshTargetFor(host);
+export function reattachRemoteSession(host, target) {
+    const sshTarget = sshTargetFor(host);
     const extraSshArgs = hostIdentityArgs(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.
     // RUSH-2265: pass host identity on every hop (probe + stream), not only the first.
-    const probe = sshExec(target, 'true', { multiplex: false, extraSshArgs });
+    const probe = sshExec(sshTarget, 'true', { multiplex: false, extraSshArgs });
     if (probe.code !== 0)
         return { code: SSH_CONN_FAILURE, connected: false, heldMs: 0 };
     // Timed from AFTER the probe returned, so this is the attach's own duration and
     // carries none of the connect phase the file header rules out as a signal.
     const startedAt = Date.now();
-    const code = sshStream(target, reattachRemoteCommand(sessionId), { tty: true, extraSshArgs });
+    const code = sshStream(sshTarget, reattachRemoteCommand(target), { tty: true, extraSshArgs });
     return { code, connected: true, heldMs: Date.now() - startedAt };
 }
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Wait `ms`, but return early if the user interrupts.
+ *
+ * Without this, Ctrl-C during the backoff killed the whole `agents` process:
+ * node's default SIGINT handler exits, so the loop never got to say what
+ * happened, the terminal was left mid-notice, and the user was dropped at a bare
+ * shell with no hint that the agent was still alive on the peer — the same
+ * dead-end the reconnect exists to prevent. The handler is installed only for
+ * the duration of the wait and always removed, so it can never swallow a Ctrl-C
+ * meant for the attached agent (during an attach, ssh owns the tty and this
+ * process is not in the foreground group anyway).
+ */
+async function waitOrInterrupt(ms) {
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (how) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            process.removeListener('SIGINT', onSigint);
+            resolve(how);
+        };
+        const onSigint = () => finish('interrupted');
+        const timer = setTimeout(() => finish('elapsed'), ms);
+        process.on('SIGINT', onSigint);
+    });
+}
 /**
  * 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
@@ -235,7 +445,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  */
 export async function reconnectInteractiveSession(opts) {
     const write = opts.write ?? ((s) => process.stderr.write(s));
-    const wait = opts.wait ?? sleep;
+    const wait = opts.wait ?? waitOrInterrupt;
     const reattach = opts.reattach ?? reattachRemoteSession;
     let state = initialReconnectState();
     // The initial run reached the point of running the agent, so it connected. Its
@@ -251,17 +461,28 @@ export async function reconnectInteractiveSession(opts) {
             // and a link that reconnected but kept dropping reads as exactly that.
             if (decision.code === SSH_CONN_FAILURE) {
                 write(outcome.connected
-                    ? unstableNotice(opts.sessionId, opts.host.name)
-                    : exhaustedNotice(opts.sessionId, opts.host.name));
+                    ? unstableNotice(opts.target, opts.host.name)
+                    : exhaustedNotice(opts.target, opts.host.name));
             }
             else if (decision.code === REMOTE_EXIT_255_REMAPPED) {
-                write(remoteExitNotice(opts.sessionId, opts.host.name));
+                write(remoteExitNotice(opts.target, opts.host.name));
+            }
+            else {
+                // Clean detach / agent exit after a reattach: the user is at a local
+                // shell and still needs the session id (RUSH-3227). Spent-budget and
+                // remapped-255 notices already carry recoveryHint.
+                write(connectionEndedNotice(opts.target, opts.host.name));
             }
             return decision.code;
         }
-        write(reconnectNotice(opts.sessionId, opts.host.name, decision.state.attempt, decision.waitMs));
-        await wait(decision.waitMs);
+        write(reconnectNotice(opts.target, opts.host.name, decision.state.attempt, decision.waitMs, decision.remainingMs));
+        if (await wait(decision.waitMs) === 'interrupted') {
+            // The user asked for their shell back. Nothing was lost — say where the
+            // agent is and how to return, then exit as an interrupt (128 + SIGINT).
+            write(interruptedNotice(opts.target, opts.host.name));
+            return 130;
+        }
         state = decision.state;
-        outcome = reattach(opts.host, opts.sessionId);
+        outcome = reattach(opts.host, opts.target);
     }
 }

package/dist/lib/hosts/registry.js

@@ -27,6 +27,7 @@ import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices } from '../devices/registry.js';
 import { resolveDeviceProfile } from '../devices/resolve-profile.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../devices/interactive-host.js';
 import { localMachineId } from '../session/origin-machine.js';
 // Re-export so existing importers (tests, commands) keep their path; the class
 // itself lives in types.ts so providers can throw it without a circular import.
@@ -161,6 +162,12 @@ export async function matchHost(name, opts = {}) {
     // returning nothing — callers that already special-case "target is this
     // machine" (teams add/create, the passthrough self-host check) then treat it as
     // local exactly as they would if the user had typed the local name.
+    if (isDeviceInteractive(name)) {
+        const pinned = resolveInteractiveDevice();
+        if (!pinned)
+            throw new Error(interactiveUnsetError());
+        name = pinned;
+    }
     if (isDeviceAuto(name)) {
         const plan = (opts.resolveAuto ?? (() => resolveDeviceAffinity({})))();
         const picked = plan.host ?? normalizeHost(localMachineId());

package/dist/lib/installations/migrate.d.ts

@@ -187,11 +187,10 @@ export declare function migrateWatchdogSentinelToConfig(sentinelPath?: string, e
  */
 export declare function migrateCliDirToClis(agentsDirs: string[]): void;
 /**
- * Cursor's OAuth token historically lived only in the global
- * ~/.config/cursor/auth.json, shared across every version home. Cursor runs now
- * pin XDG_CONFIG_HOME per version home (real per-account isolation — see
- * buildExecEnv), so the current login must be copied into the active account's
- * version home or it would read as logged out after upgrade. The active account
+ * An earlier agents-cli release put Cursor's file-backed OAuth token at
+ * ~/.config/cursor/auth.json. Current Cursor actually writes the file store to
+ * HOME-relative ~/.cursor/auth.json. Copy that legacy token into the active
+ * account's version home. The active account
  * is the home the ~/.cursor symlink currently targets. Idempotent: skips when
  * the home already has its own token, and a no-op for unmanaged Cursor installs
  * (where ~/.cursor is a real dir, not a symlink into a version home).

package/dist/lib/installations/migrate.js

@@ -1641,7 +1641,7 @@ function migrateVersionResourcesToPatterns() {
         }
     }
     if (changed) {
-        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n';
+        const META_HEADER = '# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json\n\n';
         fs.writeFileSync(metaFile, META_HEADER + yaml.stringify(meta), 'utf-8');
         console.error('Migrated agents.yaml versions: entries to pattern format');
     }
@@ -2278,11 +2278,10 @@ function migrateHumans() {
     }
 }
 /**
- * Cursor's OAuth token historically lived only in the global
- * ~/.config/cursor/auth.json, shared across every version home. Cursor runs now
- * pin XDG_CONFIG_HOME per version home (real per-account isolation — see
- * buildExecEnv), so the current login must be copied into the active account's
- * version home or it would read as logged out after upgrade. The active account
+ * An earlier agents-cli release put Cursor's file-backed OAuth token at
+ * ~/.config/cursor/auth.json. Current Cursor actually writes the file store to
+ * HOME-relative ~/.cursor/auth.json. Copy that legacy token into the active
+ * account's version home. The active account
  * is the home the ~/.cursor symlink currently targets. Idempotent: skips when
  * the home already has its own token, and a no-op for unmanaged Cursor installs
  * (where ~/.cursor is a real dir, not a symlink into a version home).
@@ -2305,7 +2304,7 @@ export function seedActiveCursorLoginPerVersion() {
     }
     if (!versionHome.includes(path.join('versions', 'cursor')))
         return;
-    const dest = path.join(versionHome, '.config', 'cursor', 'auth.json');
+    const dest = path.join(versionHome, '.cursor', 'auth.json');
     try {
         if (fs.existsSync(dest))
             return;

package/dist/lib/installations/shims.d.ts

@@ -174,7 +174,7 @@ export declare function removeShim(agent: AgentId): boolean;
  *        sorted alphabetically before the real self-updated grok binary and
  *        was silently launched instead.
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 16;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 18;
 /**
  * Agents whose config directory can be relocated by an environment variable
  * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).

package/dist/lib/installations/shims.js

@@ -942,7 +942,13 @@ export function removeShim(agent) {
  *        sorted alphabetically before the real self-updated grok binary and
  *        was silently launched instead.
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 16;
+// v17 — the claude alias env now reuses the adapter's shimConfigEnvBash (adds the
+//       Linux .oauth_token setup-token fallback the hand-copied subset had dropped),
+//       so existing alias shims must regenerate to pick it up.
+// v18 — Cursor aliases select the file credential store and swap HOME to the
+//       version home because current Cursor writes auth.json under ~/.cursor
+//       and ignores XDG_CONFIG_HOME for credential storage.
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 18;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -990,14 +996,16 @@ export function generateVersionedAliasScript(agent, version) {
     const configDirName = path.relative(os.homedir(), agentConfig.configDir);
     const managedEnv = agent === 'claude'
         ? `
-# Claude stores OAuth credentials in the macOS keychain. Scope them to this
-# version's config directory so direct aliases also switch the live account.
-export CLAUDE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
-# Managed installs are pinned in a per-version dir; Claude Code's background
-# auto-updater would rewrite the pinned binary in place. Disable it so a pin
-# stays a pin. An explicit user value always wins.
-export DISABLE_AUTOUPDATER="\${DISABLE_AUTOUPDATER:-1}"
-`
+# Reuse the main shim's Claude config-env verbatim (CLAUDE_CONFIG_DIR pin,
+# autoupdater off, AND the Linux .oauth_token setup-token fallback), keyed to this
+# version's home via VERSION_DIR. A hand-copied subset here had drifted and lost the
+# .oauth_token fallback, so interactive runs on a keychain-less worker could not
+# authenticate from the attached setup-token — the main shim (generateShimScript)
+# already sources this same adapter block, so sharing it keeps the two in sync.
+# plain (not exported) so it feeds shimConfigEnvBash below but never leaks into the
+# launched agent process — matching the main shim's convention.
+VERSION_DIR="$HOME/.agents/.history/versions/${agent}/${version}"
+${resolveHarnessAdapter(agent).shimConfigEnvBash?.({ configDirName }) ?? ''}`
         : agent === 'codex'
             ? codexHomeShimBash(`$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}`, `$HOME/.agents/.codex-homes/${version}`)
             : agent === 'copilot'
@@ -1037,10 +1045,12 @@ export XDG_DATA_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.
 `
                                 : agent === 'cursor'
                                     ? `
-# Cursor: no config-dir env var. Its OAuth token (the login gate) lives at
-# $XDG_CONFIG_HOME/cursor/auth.json, so pin XDG_CONFIG_HOME at the version home
-# to isolate each account's login for direct aliases (parity with buildExecEnv).
-export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
+# Cursor defaults to one machine-global OS-keychain login on macOS. Force its
+# file store and swap HOME, so ~/.cursor/auth.json belongs to this
+# version and direct aliases cannot fall through to the shared keychain login.
+export AGENTS_REAL_HOME="\${AGENTS_REAL_HOME:-$HOME}"
+export HOME="$HOME/.agents/.history/versions/${agent}/${version}/home"
+export AGENT_CLI_CREDENTIAL_STORE="file"
 `
                                     : '';
     const launchArgs = resolveHarnessAdapter(agent).shimLaunchArgs?.() ?? '';