@phnx-labs/agents-cli 1.22.56 → 1.22.58

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

@@ -1,58 +1,37 @@
 import { type Host } 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 declare const SSH_CONN_FAILURE = 255;
-/** 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 declare 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 declare const RECONNECT_WINDOW_MS: number;
-/** 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 declare const MIN_HOLD_MS = 10000;
 export interface ReconnectState {
-    /** Consecutive unproductive reattaches since the last genuine reconnection — one
-     *  that reached the host and held for {@link MIN_HOLD_MS}. Drives the backoff
-     *  curve and the human-facing attempt number; no longer the give-up condition. */
+    /** Consecutive unproductive reattaches since the last genuine reconnection. */
     attempt: number;
-    /** Wall-clock ms burned on the current unproductive streak — the waits plus the
-     *  time each failed attach itself took. Compared against
-     *  {@link RECONNECT_WINDOW_MS}; reset to 0 by a reattach that held. */
+    /** Ms burned on the current unproductive streak; compared to the window. */
     unproductiveMs: number;
 }
 export interface ReconnectOutcome {
-    /** Exit code of the run (initial) or the last re-attach. */
+    /** Exit code of the run or last re-attach. */
     code: number;
-    /** Whether the ssh handshake for this attempt actually completed. The initial run
-     *  and any reattach whose preflight probe succeeded are `connected`; a reattach
-     *  that couldn't reach the host is not. Half of the budget refill (see file head). */
+    /** Whether the ssh handshake completed (preflight probe succeeded). */
     connected: boolean;
-    /** Wall-clock ms the interactive attach ran for, timed from after the preflight
-     *  probe returned. `0` when the attempt never reached the host. The other half of
-     *  the refill: it must be at least {@link MIN_HOLD_MS} to count as a genuine
-     *  reconnection rather than a link that drops the user straight back out. */
+    /** How long the interactive attach held after the probe returned. */
     heldMs: number;
 }
 export type ReconnectDecision = {
@@ -67,93 +46,33 @@ export type ReconnectDecision = {
 export declare function initialReconnectState(): ReconnectState;
 /** Exponential backoff capped at {@link MAX_BACKOFF_MS}: 2s, 4s, 8s, 16s, 30s… */
 export declare function backoffMs(attempt: number): number;
-/**
- * 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 declare function refillsBudget(outcome: ReconnectOutcome): boolean;
 /**
- * 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 declare function reconnectStep(state: ReconnectState, outcome: ReconnectOutcome): ReconnectDecision;
 /** "14m51s", "51s" — a duration a waiting human can read at a glance. */
 export declare function formatDuration(ms: number): string;
-/**
- * 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 declare function reconnectNotice(target: ReconnectTarget, host: string, attempt: number, waitMs: number, remainingMs: number): string;
-/** 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 declare function exhaustedNotice(target: ReconnectTarget, host: string): string;
-/** 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 declare function unstableNotice(target: ReconnectTarget, host: string): string;
-/** 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 declare function remoteExitNotice(target: ReconnectTarget, host: string): string;
-/** 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 declare function interruptedNotice(target: ReconnectTarget, host: string): string;
 /**
- * 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 declare function wrapRemoteExitCode(cmd: string): string;
 /**
  * How a dropped run is named when we go back for it.
- *
- * `session` is the direct case: the id was known before the link died — Claude
- * is handed one up front, and a resumed run already has one.
- *
- * `launch` is what makes reconnect work for every OTHER harness (RUSH-3125).
- * Their real session id is coined on the peer, and the launcher used to read it
- * back over SSH *after* the stream returned — i.e. over the link that had just
- * dropped. That read fails exactly when it matters, leaving `reconnectId`
- * undefined and the process exiting straight to a shell, which is why a Grok tab
- * got no reconnect at all while a Claude tab beside it got a countdown. The
- * launch id is minted locally before the connection exists, so it survives the
- * drop; the peer maps it to the real session with a purely local lookup.
+ * `launch` ids are minted locally before the connection exists, so they survive a drop.
  */
 export type ReconnectTarget = {
     kind: 'session';
@@ -165,43 +84,25 @@ export type ReconnectTarget = {
 /** The short form shown to a human. Both kinds are uuid-shaped, so 8 chars reads the same. */
 export declare function targetLabel(target: ReconnectTarget): string;
 /**
- * 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 declare function recoveryHint(target: ReconnectTarget, host: string): string;
 /**
- * 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 declare function connectionEndedNotice(target: ReconnectTarget, host: string, opts?: {
     dropped?: boolean;
 }): string;
 /**
- * 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 declare function connectionStartedNotice(target: ReconnectTarget, host: string): string | undefined;
 /**
- * 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 declare function startConnectionTarget(opts: {
     agent: string;
@@ -209,15 +110,8 @@ export declare function startConnectionTarget(opts: {
     resumeId?: string;
 }): ReconnectTarget | 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 declare function afterInteractiveRemoteExit(opts: {
     target?: ReconnectTarget;
@@ -229,84 +123,39 @@ export declare function afterInteractiveRemoteExit(opts: {
     reconnect: boolean;
     notice: string | undefined;
 };
-/** What the launcher knows about a run once its interactive stream has returned. */
+/** Inputs the launcher has once its interactive stream has returned. */
 export interface ReconnectTargetInputs {
-    /** The harness (or {@link RUN_AUTO_KEYWORD}) that was dispatched. */
     agent: string;
-    /** An id forced by the launcher up front — Claude's `--session-id`. */
     sessionId?: string;
-    /** An id read back off the peer AFTER the stream returned. Absent on a drop. */
     resolvedId?: string;
-    /** The id of a run that was resuming an existing session. */
     resumeId?: string;
-    /** The launcher-minted AGENT_LAUNCH_ID, known before the connection existed. */
     launchId?: string;
 }
 /**
- * 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 declare function pickReconnectTarget(inputs: ReconnectTargetInputs): ReconnectTarget | 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 declare function reattachRemoteCommand(target: ReconnectTarget): string;
 /**
- * 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 declare function reattachRemoteSession(host: Host, target: ReconnectTarget): ReconnectOutcome;
 export interface ReconnectLoopOpts {
     host: Host;
     target: ReconnectTarget;
-    /** The exit code from the initial interactive run (which, having run the agent,
-     *  is treated as a connected attempt). */
+    /** Exit code from the initial interactive run (treated as connected). */
     initialExit: number;
-    /** Injected for tests: the real re-attach and wait are swapped for deterministic
-     *  fakes so the loop's control flow is exercised without SSH. Production uses the
-     *  real {@link reattachRemoteSession} + {@link waitOrInterrupt}. */
+    /** Test seams for the re-attach and wait. */
     reattach?: (host: Host, target: ReconnectTarget) => ReconnectOutcome;
-    /** Resolves 'interrupted' when the user Ctrl-Cs out of the backoff. */
     wait?: (ms: number) => Promise<'elapsed' | 'interrupted'>;
     write?: (s: string) => void;
 }
-/**
- * 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 declare function reconnectInteractiveSession(opts: ReconnectLoopOpts): Promise<number>;