@phnx-labs/agents-cli 1.22.46 → 1.22.49

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

@@ -1,17 +1,29 @@
 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. Mirrors ssh-exec.ts `sshStream`. */
+ *  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 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}. */
 export declare 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 declare 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 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
@@ -22,8 +34,13 @@ export declare const MAX_ATTEMPTS = 6;
 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}. */
+     *  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. */
     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. */
+    unproductiveMs: number;
 }
 export interface ReconnectOutcome {
     /** Exit code of the run (initial) or the last re-attach. */
@@ -45,6 +62,7 @@ export type ReconnectDecision = {
     action: 'retry';
     waitMs: number;
     state: ReconnectState;
+    remainingMs: number;
 };
 export declare function initialReconnectState(): ReconnectState;
 /** Exponential backoff capped at {@link MAX_BACKOFF_MS}: 2s, 4s, 8s, 16s, 30s… */
@@ -67,28 +85,43 @@ export declare function refillsBudget(outcome: ReconnectOutcome): boolean;
  *  - 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 declare function reconnectStep(state: ReconnectState, outcome: ReconnectOutcome): ReconnectDecision;
-/** Human-readable notice shown before each reconnect wait. "13 seconds", not "12.8s". */
-export declare function reconnectNotice(sessionId: string, host: string, attempt: number, waitMs: number): string;
+/** "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).
+ */
+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. */
-export declare function exhaustedNotice(sessionId: string, host: string): string;
+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. */
-export declare function unstableNotice(sessionId: string, host: string): string;
+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. */
-export declare function remoteExitNotice(sessionId: string, host: string): string;
+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. */
+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
@@ -107,17 +140,141 @@ export declare function remoteExitNotice(sessionId: string, host: string): strin
  * mock needed).
  */
 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.
+ */
+export type ReconnectTarget = {
+    kind: 'session';
+    id: string;
+} | {
+    kind: 'launch';
+    id: string;
+};
+/** 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.
+ */
+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).
+ */
+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.
+ */
+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.
+ */
+export declare function startConnectionTarget(opts: {
+    agent: string;
+    hostSessionId?: string;
+    resumeId?: string;
+}): ReconnectTarget | 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 declare function afterInteractiveRemoteExit(opts: {
+    target?: ReconnectTarget;
+    host: string;
+    exitCode: number;
+    /** True when auto-reconnect will take over (tmux-hosted, not `--raw`). */
+    willReconnect: boolean;
+}): {
+    reconnect: boolean;
+    notice: string | undefined;
+};
+/** What the launcher knows about a run 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.
+ */
+export declare function pickReconnectTarget(inputs: ReconnectTargetInputs): ReconnectTarget | 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 declare function reattachRemoteCommand(sessionId: string): string;
+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`)
@@ -129,18 +286,19 @@ export declare function reattachRemoteCommand(sessionId: string): string;
  * clean detach; other = session ended), whether this attempt connected, and how
  * long the attach held — the two inputs {@link refillsBudget} decides on.
  */
-export declare function reattachRemoteSession(host: Host, sessionId: string): ReconnectOutcome;
+export declare function reattachRemoteSession(host: Host, target: ReconnectTarget): ReconnectOutcome;
 export interface ReconnectLoopOpts {
     host: Host;
-    sessionId: string;
+    target: ReconnectTarget;
     /** The exit code from the initial interactive run (which, having run the agent,
      *  is treated as a connected attempt). */
     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} + `sleep`. */
-    reattach?: (host: Host, sessionId: string) => ReconnectOutcome;
-    wait?: (ms: number) => Promise<void>;
+     *  real {@link reattachRemoteSession} + {@link waitOrInterrupt}. */
+    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;
 }
 /**