@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/lib/hosts/reconnect.js

@@ -1,131 +1,42 @@
 /**
- * Auto-reconnect for an interactive `agents run --device` session whose
- * SSH link dropped.
+ * Auto-reconnect for an interactive `agents run --device` session whose SSH link
+ * dropped. ssh exit 255 triggers bounded-backoff re-attaches via the peer's own
+ * `agents sessions focus <id> --local`, which joins a surviving tmux pane or
+ * resumes the session in place. The retry window bounds unproductive streaks,
+ * resetting when an attach reaches the host and holds the pane.
  *
- * What the reconnect lands on depends on the peer's `tmux.enabled`
- * (PHNX-3316). With the wrap opted in, the 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 and the reattach below rejoins the live pane.
- * With the wrap off — the fleet default — the remote agent is a child of the
- * sshd session and a blink SIGHUPs it: the in-flight turn is lost, and the
- * reattach RESUMES the harness session from disk instead. Both outcomes go
- * through the same verb below; what changed in PHNX-3316 is that "resumed"
- * is once again an honest, expected result rather than a corpse this file
- * pretended was alive (the pre-RUSH-3125 bug), and RUSH-3125's forced wrap —
- * which made the pane a guarantee by overriding the operator's tmux.enabled —
- * is gone with it.
- *
- * `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 over SSH automatically,
- * with bounded backoff, until the user detaches cleanly (the remote returns 0),
- * the agent exits (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)
- * when it exists, and RESUMES the session in place when there is no pane — which
- * is every drop on a default (wrap-off) box. Dropping `--attach-only` is
- * deliberate: a reattach that finds no pane must not dead-end at a bare shell
- * (the RUSH-2085 bug), it must fall through to resume so the user is put back
- * into the agent. There is one re-attach implementation (the peer's focus) to
- * keep in sync.
- *
- * **What it takes to refill the budget: reached the host AND held the pane.** 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
- * the duration of the whole call can't tell the two apart — a 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). So each attempt runs a fast preflight probe FIRST, and only once that
- * probe proves the host reachable does the interactive attach run — which means the
- * ATTACH's own duration is a clean signal, measured with the connect phase already
- * behind it. A reattach that reached the host and then held for at least
- * {@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 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
- * preflight + `sshStream` re-attach and the wait.
- *
- * **255 from the REMOTE side should never be trusted as "the link dropped."**
- * `reattachRemoteSession`'s `connected` flag is set as soon as the fast preflight
- * probe succeeds — it says nothing about whether the interactive attach/resume
- * that follows actually put the user back into the agent. If the REMOTE command
- * (`agents sessions focus <id> --local`) itself ever happened to exit 255 for a
- * reason that has nothing to do with the ssh transport, `sshStream` would return
- * 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, 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
- * step of which could in principle exit 255 for its own reasons. So the channel-
- * level defense is what matters, not an audit of which branch can fire:
- * {@link wrapRemoteExitCode} wraps the entire remote command so that whatever exit
- * code it decides on, a 255 is remapped to {@link REMOTE_EXIT_255_REMAPPED} before
- * `sshStream` ever sees it, regardless of which internal branch produced it and
- * regardless of the peer's `agents` version (the remap happens in the shell
- * wrapper THIS process sends).
- *
- * A recurring LOCAL ssh failure used to defeat the budget the same way, and the
- * 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" 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
- * deliberately NOT taken — any fixed total eventually strands the all-day-blinking
- * 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.
+ * A remote interactive session MUST be tmux-wrapped: with the wrap on, the agent
+ * runs in a DETACHED tmux pane on the peer, so a blink kills only the ssh client
+ * and the reattach rejoins the live pane; with it off, the agent is a child of
+ * the sshd session and a blink SIGHUPs it, losing the in-flight turn (the
+ * reattach then resumes the harness from disk). See lib/exec.ts `runInTmux`.
  */
 import { sshExec, sshStream, shellQuote, SSH_CONN_FAILURE_CODE } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { RUN_AUTO_KEYWORD } from '../types.js';
-/** ssh's connection-layer failure code — the signal that the link dropped rather
- *  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. */
+/** ssh's connection-layer failure code — re-exported from ssh-exec.ts. */
 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}. */
+/**
+ * ssh returns 255 for BOTH "couldn't connect" and "connected then dropped", so a
+ * remote-origin 255 (the focus command's own exit) is remapped to 254 before the
+ * reconnect loop sees it — inside the loop, 255 therefore always means a network
+ * drop, never a code the remote command chose.
+ */
 export const REMOTE_EXIT_255_REMAPPED = 254;
 /**
- * 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.
+ * Wall-clock window bounding unproductive reconnect streaks, not the total
+ * session. A reattach that reaches the host and holds resets the budget.
  */
 export const RECONNECT_WINDOW_MS = 15 * 60_000;
-/** Backoff curve 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. */
+/** Backoff curve: 2s, 4s, 8s, 16s, 30s, then 30s until the window closes. */
 const BASE_BACKOFF_MS = 2_000;
 const MAX_BACKOFF_MS = 30_000;
-/** How long a reattach must hold the remote pane before it counts as a genuine
- *  reconnection that refills the budget. Measured on the interactive attach ALONE
- *  — the preflight probe has already returned by then, so this is not the connect
- *  timing the file header rules out. 10s is comfortably longer than any attach that
- *  dies during TTY negotiation and far shorter than a session the user is working
- *  in; a link that drops the user out inside 10s on every attempt is one this loop
- *  should stop retrying, not one it should keep re-entering. */
+/**
+ * A genuine reconnection must hold the remote pane this long before refilling
+ * the retry budget. It is the minimum time to clear TTY negotiation and confirm
+ * a working session, distinguishing that from an attach that reconnects and
+ * immediately re-drops; otherwise a flapping link would retry forever.
+ */
 export const MIN_HOLD_MS = 10_000;
 export function initialReconnectState() {
     return { attempt: 0, unproductiveMs: 0 };
@@ -134,36 +45,20 @@ export function initialReconnectState() {
 export function backoffMs(attempt) {
     return Math.min(BASE_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
 }
-/**
- * Did this attempt genuinely put the user back into the agent? Only such an attempt
- * refills the retry budget — it must have reached the host AND held the pane for at
- * least {@link MIN_HOLD_MS}. An attach that reached the host and died right back is
- * a flapping link, not a reconnection, and counts against the budget like an
- * unreachable host (agents-cli#1884; see the file header).
- */
+/** True when the attempt both connected and held long enough to refill the budget. */
 export function refillsBudget(outcome) {
     return outcome.connected && outcome.heldMs >= MIN_HOLD_MS;
 }
 /**
- * Decide 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 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 once the retry window closes.
+ * Decide the next action from a run/re-attach outcome. Non-255 exits stop and
+ * surface that code; 255 retries until the unproductive window is spent.
  */
 export function reconnectStep(state, outcome) {
     if (outcome.code !== SSH_CONN_FAILURE)
         return { action: 'stop', code: outcome.code };
     const productive = refillsBudget(outcome);
     const attempts = productive ? 0 : state.attempt;
-    // The attach's own duration counts against the window: 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.
+    // The attach's own duration counts against the window.
     const burned = productive ? 0 : state.unproductiveMs + outcome.heldMs;
     if (burned >= RECONNECT_WINDOW_MS)
         return { action: 'stop', code: SSH_CONN_FAILURE };
@@ -182,68 +77,33 @@ export function formatDuration(ms) {
     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).
- */
+/** Notice shown before each reconnect wait. */
 export function reconnectNotice(target, host, attempt, waitMs, remainingMs) {
     const secs = Math.round(waitMs / 1000);
     const when = secs <= 1 ? 'now' : `in ${secs}s`;
     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. */
+/** Notice shown once the retry budget is spent on an unreachable host. */
 export function exhaustedNotice(target, host) {
     return `\nCouldn't reconnect to ${host} after ${formatDuration(RECONNECT_WINDOW_MS)}. The agent may still be running — get back in when the network is back:\n${recoveryHint(target, host)}`;
 }
-/** Notice shown when the budget is spent the OTHER way: the last reattach reached
- *  the host and the connection dropped again within {@link MIN_HOLD_MS}. Saying
- *  "couldn't reconnect" there would be false — it did reconnect and could not stay
- *  — 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. */
+/** Notice shown when the host reconnects but drops again within {@link MIN_HOLD_MS}. */
 export function unstableNotice(target, host) {
     const secs = Math.round(MIN_HOLD_MS / 1000);
     return `\nGave up reconnecting to ${host} after ${formatDuration(RECONNECT_WINDOW_MS)} — it kept dropping again within ${secs} seconds of getting back in. The agent may still be running there; reconnect once the link is stable:\n${recoveryHint(target, host)}`;
 }
-/** Notice shown when a reattach 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. */
+/** Notice shown when a reattach ends with a remapped remote-side exit. */
 export function remoteExitNotice(target, host) {
     return `\nReattach to ${targetLabel(target)} on ${host} ended (not a network drop) — get back in, or check whether it's still live:\n${recoveryHint(target, host)}`;
 }
-/** 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. */
+/** Notice shown when the user stops the wait with Ctrl-C. */
 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`
- * in remote-cmd.ts uses for its own POSIX callers — see its doc comment for why
- * a login shell at all; the sibling interactive dispatch in dispatch.ts sends a
- * bare `agents …` with no shell wrapper, so this is a NEW login-shell hop on the
- * reattach path specifically, not something already universal here) with a
- * trailing exit-code remap: whatever `cmd` itself exits with, a 255 becomes
- * {@link REMOTE_EXIT_255_REMAPPED} before the wrapper exits — see the file
- * header for why. Every other code (0, 1, …) passes through unchanged. This
- * carries no PATH bootstrap of its own — `ensureHostReady`/`readyProbe` already
- * gates every `--device` dispatch on `bash -lc 'agents --version'` succeeding
- * before a run is attempted at all, so the peer's login shell resolving `agents`
- * is an established precondition here too. Pure string-building, so it is
- * unit-tested without SSH (and, since the constructed script is ordinary POSIX,
- * also exercised by actually running it through a real shell in the test — no
- * mock needed).
+ * Wrap `cmd` in `bash -lc` with an exit-code remap: 255 becomes
+ * {@link REMOTE_EXIT_255_REMAPPED} so a remote-origin 255 cannot pass as ssh drop.
  */
 export function wrapRemoteExitCode(cmd) {
     const guarded = `${cmd}; rc=$?; [ "$rc" = "${SSH_CONN_FAILURE}" ] && rc=${REMOTE_EXIT_255_REMAPPED}; exit "$rc"`;
@@ -254,23 +114,10 @@ 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.
+ * The command a user can run to re-enter a session after reconnect gives up.
+ * The full id is printed on its own line so it remains copyable after a drop.
  */
 export function recoveryHint(target, host) {
-    // 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`;
     }
@@ -278,22 +125,16 @@ export function recoveryHint(target, host) {
         + `  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).
+ * Notice shown when an interactive remote connection ends and no auto-reconnect
+ * follows. Prints the session id/handle so the user can get back in.
  */
 export function connectionEndedNotice(target, host, opts = {}) {
     const verb = opts.dropped ? 'dropped' : 'closed';
     return `\nConnection to ${host} ${verb}.\n${recoveryHint(target, host)}`;
 }
 /**
- * Banner printed 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.
+ * Banner printed as an interactive `--device` run takes the TTY, so the id is
+ * visible in scrollback while the connection exists.
  */
 export function connectionStartedNotice(target, host) {
     if (target.kind !== 'session')
@@ -301,10 +142,8 @@ export function connectionStartedNotice(target, host) {
     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.
+ * The id to print as an interactive `--device` stream starts. `run auto` is
+ * excluded because its forwarded id is only real when the remote picks Claude.
  */
 export function startConnectionTarget(opts) {
     if (opts.agent === RUN_AUTO_KEYWORD)
@@ -313,15 +152,8 @@ export function startConnectionTarget(opts) {
     return id ? { kind: 'session', id } : undefined;
 }
 /**
- * Decide what happens after an interactive `--device` stream returns.
- *
- * Auto-reconnect fires whenever the link dropped (255) and the run did not opt
- * out with `--raw` (`willReconnect`) — wrap or no wrap. A wrapped run's pane
- * survived, so the reattach rejoins it; a bare run's agent died with the link,
- * so the same verb resumes the session in place from disk (PHNX-3316). `--raw`
- * 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.
+ * Decide what happens after an interactive `--device` stream returns. Auto-
+ * reconnect fires on 255 unless `--raw` opted out; otherwise print recovery info.
  */
 export function afterInteractiveRemoteExit(opts) {
     if (!opts.target)
@@ -336,24 +168,8 @@ export function afterInteractiveRemoteExit(opts) {
     };
 }
 /**
- * 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.
+ * Choose how to name the dropped run. `launchId` is last because it is minted
+ * locally before the connection exists, so it survives the drop.
  */
 export function pickReconnectTarget(inputs) {
     const { agent, sessionId, resolvedId, resumeId, launchId } = inputs;
@@ -366,18 +182,8 @@ export function pickReconnectTarget(inputs) {
     return launchId ? { kind: 'launch', id: launchId } : undefined;
 }
 /**
- * The remote command a reattach runs — the peer's own recovery verb
- * (`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}).
+ * The peer's recovery verb wrapped so a remote-origin 255 cannot masquerade as
+ * a network drop. No `--attach-only`: focus resumes in place when no pane survived.
  */
 export function reattachRemoteCommand(target) {
     const selector = target.kind === 'launch'
@@ -389,27 +195,19 @@ export function reattachRemoteCommand(target) {
     return wrapRemoteExitCode(inner);
 }
 /**
- * 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-or-resume (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), whether this attempt connected, and how
- * long the attach held — the two inputs {@link refillsBudget} decides on.
+ * Re-attach the live remote pane by driving the peer's `agents sessions focus`.
+ * A fast preflight probe decides reachability; only then do we run the
+ * interactive attach/resume. Returns the exit code, connected bit, and hold time.
  */
 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.
+    // Fresh (non-multiplexed) reachability probe: only a completed handshake is
+    // counted as connected.
     const probe = sshExec(sshTarget, 'true', { multiplex: false, extraSshArgs });
     if (probe.code !== 0)
         return { code: SSH_CONN_FAILURE, connected: false, heldMs: 0 };
-    // Timed from AFTER the probe returned, so this is the attach's own duration and
-    // carries none of the connect phase the file header rules out as a signal.
+    // Timed from after the probe returns, so this measures only the attach itself.
     const startedAt = Date.now();
     const code = sshStream(sshTarget, reattachRemoteCommand(target), { tty: true, extraSshArgs });
     return { code, connected: true, heldMs: Date.now() - startedAt };
@@ -417,14 +215,8 @@ export function reattachRemoteSession(host, target) {
 /**
  * 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).
+ * Installs a SIGINT handler only for the wait so Ctrl-C gives a graceful
+ * "agent still running" message instead of killing the local process silently.
  */
 async function waitOrInterrupt(ms) {
     return new Promise((resolve) => {
@@ -442,27 +234,18 @@ async function waitOrInterrupt(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
- * {@link reconnectStep}. Returns the exit code the process should ultimately use.
- */
+/** Drive the reconnect loop from the initial run's outcome to a terminal code. */
 export async function reconnectInteractiveSession(opts) {
     const write = opts.write ?? ((s) => process.stderr.write(s));
     const wait = opts.wait ?? waitOrInterrupt;
     const reattach = opts.reattach ?? reattachRemoteSession;
     let state = initialReconnectState();
-    // The initial run reached the point of running the agent, so it connected. Its
-    // hold duration is never measured — exec.ts owns that call — and never needs to
-    // be: refilling is a no-op at attempt 0, which is where the loop starts, so this
-    // outcome can only ever produce the first retry either way.
+    // The initial run connected; its hold duration doesn't matter at attempt 0.
     let outcome = { code: opts.initialExit, connected: true, heldMs: 0 };
     for (;;) {
         const decision = reconnectStep(state, outcome);
         if (decision.action === 'stop') {
-            // A spent budget has two shapes and one wrong message: `outcome` is the
-            // reattach that spent it, so an unreachable host reads "couldn't reconnect"
-            // and a link that reconnected but kept dropping reads as exactly that.
+            // Spent budget: unreachable host vs. unstable link need different messages.
             if (decision.code === SSH_CONN_FAILURE) {
                 write(outcome.connected
                     ? unstableNotice(opts.target, opts.host.name)
@@ -472,17 +255,14 @@ export async function reconnectInteractiveSession(opts) {
                 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.
+                // Clean detach / agent exit: still print the session handle.
                 write(connectionEndedNotice(opts.target, opts.host.name));
             }
             return decision.code;
         }
         write(reconnectNotice(opts.target, opts.host.name, decision.state.attempt, decision.waitMs, decision.remainingMs));
         if (await wait(decision.waitMs) === 'interrupted') {
-            // 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).
+            // User interrupted; the agent is still running on the peer.
             write(interruptedNotice(opts.target, opts.host.name));
             return 130;
         }