@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/hosts/ready.js

@@ -1,10 +1,3 @@
-/**
- * Host readiness + bootstrap.
- *
- * Before a dispatch we ensure the box is reachable and has agents-cli. Enrollment
- * can additionally install/upgrade agents-cli to match the local version (version
- * parity) using the same shape as scripts/sandbox.sh. We never copy `.history`.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
@@ -14,7 +7,6 @@ import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershell
 import { resolveRemoteOsSync } from './remote-os.js';
 import { AUTH_PROBE_MAX_AGE_MS, isDeadVerdict } from '../auth-health.js';
 import { USAGE_STALE_REFUSAL_MAX_AGE_MS } from '../accounting/rotate.js';
-/** Resolve this CLI's own version by walking up to the nearest package.json. */
 export function localCliVersion() {
     let dir = path.dirname(fileURLToPath(import.meta.url));
     for (let i = 0; i < 8; i++) {
@@ -25,7 +17,6 @@ export function localCliVersion() {
                 return data.version;
         }
         catch {
-            /* keep walking */
         }
         const parent = path.dirname(dir);
         if (parent === dir)
@@ -34,21 +25,12 @@ export function localCliVersion() {
     }
     return null;
 }
-/** ssh command that confirms reachability and echoes the OS. POSIX boxes answer
- * `uname -s`; a Windows target has no `uname` (ssh lands in cmd.exe/PowerShell),
- * so it runs a tiny PowerShell probe. Pure/exported so both branches are
- * unit-testable without ssh. */
 export function buildProbeCommand(os) {
     if (remoteShellFor(os) === 'powershell') {
         return `powershell -NoProfile -EncodedCommand ${encodePowershell('[System.Environment]::OSVersion.Platform.ToString()')}`;
     }
     return 'uname -s 2>/dev/null || echo unknown';
 }
-/**
- * Reachability + OS probe over ssh. `os` is the caller's hint (device-registry
- * platform / enrolled `HostEntry.os`); when it marks the host Windows we take
- * the PowerShell path and report that known platform, otherwise POSIX + uname.
- */
 export function probeHost(target, os, extraSshArgs = []) {
     const r = sshExec(target, buildProbeCommand(os), { timeoutMs: 12000, extraSshArgs });
     if (r.code !== 0)
@@ -58,15 +40,11 @@ export function probeHost(target, os, extraSshArgs = []) {
     const uname = r.stdout.trim();
     return { reachable: true, os: uname && uname !== 'unknown' ? uname : undefined };
 }
-/** ssh command that prints the remote agents-cli version. Pure/exported. */
 export function buildRemoteVersionCommand(os) {
     return remoteShellFor(os) === 'powershell'
         ? buildWindowsAgentsCommand({ args: ['--version'] })
         : 'bash -lc "agents --version 2>/dev/null"';
 }
-/** ssh command that installs/upgrades agents-cli to `spec` then `agents setup`.
- * PowerShell has no `tail`/`[ -d ]`/`||`, so the Windows branch uses native
- * equivalents (`Select-Object -Last`, `Test-Path`). Pure/exported. */
 export function buildBootstrapCommand(spec, os) {
     if (remoteShellFor(os) === 'powershell') {
         const script = `${POWERSHELL_PROGRESS_SILENCE}; ` +
@@ -80,38 +58,12 @@ export function buildBootstrapCommand(spec, os) {
         `agents --version`;
     return `bash -lc ${shellQuote(script)}`;
 }
-/** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
 export function bootstrapAgentsCli(target, version, os, extraSshArgs) {
     const spec = version ? `@phnx-labs/agents-cli@${version}` : '@phnx-labs/agents-cli';
     const r = sshExec(target, buildBootstrapCommand(spec, os), { timeoutMs: 300000, extraSshArgs });
     return { ok: r.code === 0, output: (r.stdout + r.stderr).trim() };
 }
-/** Sentinel splitting the version output from the agent listing in one probe. */
 const READY_MARKER = '@@AGENTS_READY@@';
-/**
- * Answer every readiness question in ONE ssh round-trip: reachable? (the login
- * shell ran and echoed our sentinel), agents-cli version, and the installed-agent
- * listing. This replaces three sequential probes (`true` + `agents --version` +
- * `agents view`) — 3 handshakes collapse to 1. Reachability keys off the sentinel
- * rather than the exit code, so a command that ran-but-failed is never mistaken
- * for a dead connection (only ssh's own failure drops the sentinel).
- */
-/**
- * The one-shot readiness command (version + sentinel + agent listing). The
- * Windows branch emits the sentinel with `Write-Output` and branches on
- * `$LASTEXITCODE` (no `printf`/`||`); `parseReadyProbe` keys off the sentinel
- * substring, so the missing leading newline vs the POSIX `printf '\n…'` form is
- * absorbed by its `.trim()`. Pure/exported so both branches are unit-testable.
- *
- * With `ingestUsage`, the probe first runs `agents __usage-ingest` on the
- * dispatcher's daemon-state envelope, which the caller pipes to stdin
- * (PHNX-4116): the chosen worker then holds the dispatcher's current usage
- * numbers at dispatch instead of waiting for the next 15-minute usage-sync
- * tick. The ingest writes nothing to stdout (only `--reply` does), so the
- * version/sentinel/listing shape `parseReadyProbe` reads is unchanged. On
- * Windows the `agents.ps1` shim drops ssh-piped stdin, so PowerShell reads it
- * into a temp file and hands the verb `--from <path>`.
- */
 export function buildReadyProbeCommand(os, opts = {}) {
     if (remoteShellFor(os) === 'powershell') {
         const ingest = opts.ingestUsage
@@ -131,14 +83,11 @@ export function buildReadyProbeCommand(os, opts = {}) {
     return `bash -lc ${shellQuote(script)}`;
 }
 export function readyProbe(target, os, extraSshArgs) {
-    // Disable multiplexing: a stale control socket can hang the local ssh client
-    // until the timeout fires, just like sshExecAsync does for the same reason.
     const r = sshExec(target, buildReadyProbeCommand(os), { timeoutMs: 20000, multiplex: false, extraSshArgs });
     if (r.timedOut)
         return { reachable: false, version: null, view: '', timedOut: true };
     return parseReadyProbe(r.stdout);
 }
-/** Pure parser for `readyProbe` output (unit-tested without ssh). */
 export function parseReadyProbe(stdout) {
     const idx = stdout.indexOf(READY_MARKER);
     if (idx === -1)
@@ -146,33 +95,19 @@ export function parseReadyProbe(stdout) {
     const version = stdout.slice(0, idx).trim().replace(/^v/, '') || null;
     return { reachable: true, version, view: stdout.slice(idx + READY_MARKER.length) };
 }
-/** True if `view` output lists the named agent (word-boundary, case-insensitive). */
 export function viewHasAgent(view, agent) {
     return new RegExp(`\\b${agent}\\b`, 'i').test(view);
 }
-/**
- * True when `version` is a concrete pin the remote must already have installed
- * (e.g. `0.145.0`, `2.1.207`). Aliases (`latest` / `oldest` / `pinned` /
- * `default` / `all` / `any`) resolve against the remote's own install set and
- * are not preflight-checked here.
- */
 export function isConcreteVersionPin(version) {
     if (!version)
         return false;
     const v = version.trim();
     if (!v)
         return false;
-    // Keep in lockstep with agent-spec AGENT_QUALIFIERS (+ `any` filter token).
     if (['latest', 'oldest', 'pinned', 'default', 'all', 'any'].includes(v.toLowerCase()))
         return false;
-    // Same shape agent-spec accepts for an exact pin (no path traversal / spaces).
     return /^(?!.*\.\.)[A-Za-z0-9._+-]{1,64}$/.test(v);
 }
-/**
- * Installed version strings for `agent` from `agents view --json` output.
- * Returns `[]` when the agent row is absent, `undefined` when `view` is not
- * JSON (text `agents list` fallback) so callers can degrade.
- */
 export function viewAgentVersions(view, agent) {
     try {
         const rows = JSON.parse(view);
@@ -189,12 +124,6 @@ export function viewAgentVersions(view, agent) {
         return undefined;
     }
 }
-/**
- * Whether a concrete `agent@version` is installed according to remote view
- * output. JSON path is authoritative; text listing falls back to a whole-token
- * version match. `undefined` only when the text path has the agent but no
- * version token to confirm against (callers treat that as unverified).
- */
 export function viewHasAgentVersion(view, agent, version) {
     const versions = viewAgentVersions(view, agent);
     if (versions !== undefined)
@@ -206,7 +135,6 @@ export function viewHasAgentVersion(view, agent, version) {
         return true;
     return undefined;
 }
-/** Actionable fail-loud message for a missing remote pin (RUSH-2313). */
 export function missingPinnedVersionMessage(hostName, agent, version, installed) {
     let installedHint = '';
     if (installed) {
@@ -252,8 +180,6 @@ export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
             return { signedIn: undefined, pickerEligible: undefined };
         const runReady = row.runReady;
         if (runReady && typeof runReady.ready === 'boolean') {
-            // A signed-out / revoked account is picker-eligible even when not ready —
-            // launching it IS the login flow. A throttled account is not.
             const accounts = runReady.accounts ?? [];
             const pickerEligible = runReady.ready
                 || accounts.some((a) => a.reason === 'signed_out' || a.reason === 'revoked');
@@ -263,12 +189,9 @@ export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
                 reason: runReady.ready ? undefined : runReady.reason,
             };
         }
-        // One-release fallback for an older remote CLI without `runReady`.
         const verdicts = (row.versions ?? []).flatMap((version) => {
             if (typeof version.signedIn !== 'boolean')
                 return [];
-            // Prefer the strict per-version launch signal; fall back to the display
-            // `signedIn` for a CLI old enough to omit `launchable` too.
             const launchable = typeof version.launchable === 'boolean' ? version.launchable : version.signedIn;
             const usageCapturedAt = version.usageCapturedAt ? Date.parse(version.usageCapturedAt) : Number.NaN;
             const usageFresh = Number.isFinite(usageCapturedAt)
@@ -283,13 +206,6 @@ export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
                 && version.authVerdict !== undefined
                 && authFresh
                 && isDeadVerdict(version.authVerdict);
-            // A stale usage/auth reading makes the account UNVERIFIED, not unusable:
-            // the number is ignored (`throttled`/`authBlocked` only trust a fresh one)
-            // and the remote `agents run` weights an unverified account at the floor.
-            // Refusing the whole device on a stale reading turned a fleet-wide
-            // usage-sync lag into "no healthy device can run claude" while
-            // `--device <name>` on the same box launched fine (PHNX-4116/#3700). Only a
-            // FRESH throttle or a FRESH dead auth verdict disqualifies.
             const ready = launchable && !authBlocked && !throttled;
             return [{ ready, pickerEligible: ready || !launchable || authBlocked }];
         });
@@ -307,11 +223,6 @@ export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
 export function viewAgentSignedIn(view, agent) {
     return viewAgentAccountEligibility(view, agent).signedIn;
 }
-/**
- * Pure readiness verdict for the agent/version half of {@link ensureHostReady}
- * (unit-tested without SSH). Returns warnings for soft agent-missing cases, or
- * throws (via the caller's `throw new Error`) when a concrete pin is missing.
- */
 export function evaluateHostAgentInstall(view, opts, hostName) {
     const warnings = [];
     if (isConcreteVersionPin(opts.version)) {
@@ -320,9 +231,6 @@ export function evaluateHostAgentInstall(view, opts, hostName) {
         const has = viewHasAgentVersion(view, opts.agent, version);
         if (has === true)
             return { warnings };
-        // Missing or unverifiable pin: fail loud. Detached host dispatch used to
-        // print "Dispatched" and only die in the remote log ("codex@0.145.0 is not
-        // installed") — whole fleet drains no-op'd under that silent success.
         throw new Error(missingPinnedVersionMessage(hostName, opts.agent, version, installed));
     }
     if (!viewHasAgent(view, opts.agent)) {
@@ -333,15 +241,6 @@ export function evaluateHostAgentInstall(view, opts, hostName) {
     }
     return { warnings };
 }
-/**
- * Verify a host can run the agent: reachable + agents-cli present. Throws with an
- * actionable message otherwise. Agent-not-installed is a warning by default (the
- * remote `agents run` will surface it); pass requireAgent to make it fatal.
- * A concrete `version` pin always fails loud when that version is absent
- * (RUSH-2313) — never a silent "Dispatched" for a pin the box cannot run.
- *
- * One ssh round-trip (`readyProbe`) covers all three checks.
- */
 export function ensureHostReady(host, opts) {
     const target = sshTargetFor(host);
     const probe = readyProbe(target, host.os ?? resolveRemoteOsSync(host.name), hostIdentityArgs(host));

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

@@ -1,15 +1,3 @@
-/**
- * Reconcile a local host-task record against the remote run's ground truth.
- *
- * A detached `--device` run outlives the local follower: it keeps running and
- * writes its exit code to `<id>.exit` on the host even if the laptop sleeps or
- * the SSH connection drops mid-follow. When that happens the local record is
- * left at `status:'running'` forever, because the only path that finalizes it
- * (dispatch's post-follow `updateTask`) never runs. This module re-reads the
- * remote `.exit` on demand — from `agents devices ps` / `agents logs` — and heals the
- * record. We only ever CONFIRM completion; an unreachable host or an absent
- * `.exit` leaves the record `running` (we never guess failure).
- */
 import { type SshExecResult } from '../ssh-exec.js';
 import { type HostTask } from './tasks.js';
 type RemoteExitState = {
@@ -20,36 +8,10 @@ type RemoteExitState = {
 } | {
     state: 'unreachable';
 };
-/**
- * Classify a `cat <remoteExit>` result into a remote run state. Pure: all the
- * bug-prone branching (ssh-failure vs absent vs empty vs coded) lives here so it
- * can be unit-tested without a live host. ssh's own connection failure surfaces
- * as code 255, a spawn error/timeout as `code === null`; neither is the remote
- * command's exit and both mean "unreachable". An empty read is "still running"
- * (the `.exit` is written only after the run ends, so absent `cat` → exit 1 →
- * empty stdout, and a truncate-then-write mid-race is a sub-ms empty window).
- */
 export declare function classifyExit(res: Pick<SshExecResult, 'code' | 'stdout' | 'timedOut'>): RemoteExitState;
 export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number, identityFile?: string, remoteShell?: 'posix' | 'powershell'): RemoteExitState;
-/**
- * Heal one record. Terminal records are immutable (and never re-probed); a
- * `running` record is resolved to completed/failed only when the remote `.exit`
- * holds a code. Returns the (possibly updated) task.
- */
 export declare function reconcileTask(task: HostTask): HostTask;
-/**
- * Async twin of {@link reconcileTask} for the daemon heartbeat tick (PHNX-3695):
- * identical healing logic, non-blocking ssh read via {@link readRemoteExitAsync}.
- */
 export declare function reconcileTaskAsync(task: HostTask): Promise<HostTask>;
-/**
- * Heal a list of records for a listing (`agents devices ps`). Only `running` tasks
- * are probed; each host is reachability-checked ONCE (deduped by target) so a
- * down host costs a single short timeout instead of one per task, and its tasks
- * are left `running` rather than falsely failed. Sequential by design — with the
- * shared ssh control socket the live-host reads are sub-100ms, and a parallel
- * (async) ssh path is deliberately out of scope.
- */
 export declare function reconcileRunningTasks(tasks: HostTask[]): HostTask[];
 export declare function reachabilityProbeCommand(remoteShell?: 'posix' | 'powershell'): string;
 export {};

package/dist/lib/hosts/reconcile.js

@@ -1,27 +1,6 @@
-/**
- * Reconcile a local host-task record against the remote run's ground truth.
- *
- * A detached `--device` run outlives the local follower: it keeps running and
- * writes its exit code to `<id>.exit` on the host even if the laptop sleeps or
- * the SSH connection drops mid-follow. When that happens the local record is
- * left at `status:'running'` forever, because the only path that finalizes it
- * (dispatch's post-follow `updateTask`) never runs. This module re-reads the
- * remote `.exit` on demand — from `agents devices ps` / `agents logs` — and heals the
- * record. We only ever CONFIRM completion; an unreachable host or an absent
- * `.exit` leaves the record `running` (we never guess failure).
- */
 import { sshExec, sshExecAsync } from '../ssh-exec.js';
 import { updateTask, terminalPatch } from './tasks.js';
 import { encodePowershell } from './remote-cmd.js';
-/**
- * Classify a `cat <remoteExit>` result into a remote run state. Pure: all the
- * bug-prone branching (ssh-failure vs absent vs empty vs coded) lives here so it
- * can be unit-tested without a live host. ssh's own connection failure surfaces
- * as code 255, a spawn error/timeout as `code === null`; neither is the remote
- * command's exit and both mean "unreachable". An empty read is "still running"
- * (the `.exit` is written only after the run ends, so absent `cat` → exit 1 →
- * empty stdout, and a truncate-then-write mid-race is a sub-ms empty window).
- */
 export function classifyExit(res) {
     if (res.timedOut || res.code === null || res.code === 255)
         return { state: 'unreachable' };
@@ -31,11 +10,6 @@ export function classifyExit(res) {
     const code = parseInt(out, 10);
     return { state: 'done', code: Number.isFinite(code) ? code : 0 };
 }
-/**
- * Read a task's remote `.exit` over ssh and classify it. `remoteExit` is a
- * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
- * remote shell expands $HOME (same contract as progress.ts's fetch).
- */
 function remoteExitCommand(remoteExit, remoteShell) {
     return remoteShell === 'powershell'
         ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`$path = Join-Path $HOME '${remoteExit.replace(/^\$HOME\//, '').replace(/'/g, "''")}'; if (Test-Path -LiteralPath $path) { Get-Content -LiteralPath $path -Raw }`)}`
@@ -51,20 +25,9 @@ function remoteExitSshOpts(timeoutMs, identityFile) {
 export function readRemoteExit(target, remoteExit, timeoutMs = 6000, identityFile, remoteShell = 'posix') {
     return classifyExit(sshExec(target, remoteExitCommand(remoteExit, remoteShell), remoteExitSshOpts(timeoutMs, identityFile)));
 }
-/**
- * Async twin of {@link readRemoteExit} for the daemon's heartbeat tick — the ssh
- * read runs on the shared event loop, so it MUST NOT block it with a synchronous
- * `spawnSync('ssh', …)` (PHNX-3695). `sshExecAsync` applies the same
- * timeout/kill-grace bound.
- */
 async function readRemoteExitAsync(target, remoteExit, timeoutMs = 6000, identityFile, remoteShell = 'posix') {
     return classifyExit(await sshExecAsync(target, remoteExitCommand(remoteExit, remoteShell), remoteExitSshOpts(timeoutMs, identityFile)));
 }
-/**
- * Heal one record. Terminal records are immutable (and never re-probed); a
- * `running` record is resolved to completed/failed only when the remote `.exit`
- * holds a code. Returns the (possibly updated) task.
- */
 export function reconcileTask(task) {
     if (task.status !== 'running')
         return task;
@@ -73,10 +36,6 @@ export function reconcileTask(task) {
         return task;
     return updateTask(task.id, terminalPatch(st.code)) ?? task;
 }
-/**
- * Async twin of {@link reconcileTask} for the daemon heartbeat tick (PHNX-3695):
- * identical healing logic, non-blocking ssh read via {@link readRemoteExitAsync}.
- */
 export async function reconcileTaskAsync(task) {
     if (task.status !== 'running')
         return task;
@@ -85,14 +44,6 @@ export async function reconcileTaskAsync(task) {
         return task;
     return updateTask(task.id, terminalPatch(st.code)) ?? task;
 }
-/**
- * Heal a list of records for a listing (`agents devices ps`). Only `running` tasks
- * are probed; each host is reachability-checked ONCE (deduped by target) so a
- * down host costs a single short timeout instead of one per task, and its tasks
- * are left `running` rather than falsely failed. Sequential by design — with the
- * shared ssh control socket the live-host reads are sub-100ms, and a parallel
- * (async) ssh path is deliberately out of scope.
- */
 export function reconcileRunningTasks(tasks) {
     const running = tasks.filter((t) => t.status === 'running');
     if (running.length === 0)
@@ -109,7 +60,7 @@ export function reconcileRunningTasks(tasks) {
             reachable.set(t.target, probe.code === 0);
         }
         if (!reachable.get(t.target))
-            continue; // host down → leave running
+            continue;
         const st = readRemoteExit(t.target, t.remoteExit, 6000, t.identityFile, t.remoteShell);
         if (st.state === 'done') {
             const updated = updateTask(t.id, terminalPatch(st.code));

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

@@ -1,37 +1,15 @@
 import { type Host } from './types.js';
-/** ssh's connection-layer failure code — re-exported from ssh-exec.ts. */
 export declare const SSH_CONN_FAILURE = 255;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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. */
     attempt: number;
-    /** Ms burned on the current unproductive streak; compared to the window. */
     unproductiveMs: number;
 }
 export interface ReconnectOutcome {
-    /** Exit code of the run or last re-attach. */
     code: number;
-    /** Whether the ssh handshake completed (preflight probe succeeded). */
     connected: boolean;
-    /** How long the interactive attach held after the probe returned. */
     heldMs: number;
 }
 type ReconnectDecision = {
@@ -44,36 +22,16 @@ type ReconnectDecision = {
     remainingMs: number;
 };
 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;
-/** True when the attempt both connected and held long enough to refill the budget. */
 export declare function refillsBudget(outcome: ReconnectOutcome): boolean;
-/**
- * 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. */
 export declare function reconnectNotice(target: ReconnectTarget, host: string, attempt: number, waitMs: number, remainingMs: number): string;
-/** 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 host reconnects but drops again within {@link MIN_HOLD_MS}. */
 export declare function unstableNotice(target: ReconnectTarget, host: string): string;
-/** Notice shown when a reattach ends with a remapped remote-side exit. */
 export declare function remoteExitNotice(target: ReconnectTarget, host: string): string;
-/** 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` 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.
- * `launch` ids are minted locally before the connection exists, so they survive a drop.
- */
 export type ReconnectTarget = {
     kind: 'session';
     id: string;
@@ -81,47 +39,25 @@ export type ReconnectTarget = {
     kind: 'launch';
     id: string;
 };
-/**
- * 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 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 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. `run auto` is
- * excluded because its forwarded id is only real when the remote picks 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 fires on 255 unless `--raw` opted out; otherwise print recovery info.
- */
 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;
 };
-/** Inputs the launcher has once its interactive stream has returned. */
 interface ReconnectTargetInputs {
     agent: string;
     sessionId?: string;
@@ -129,26 +65,15 @@ interface ReconnectTargetInputs {
     resumeId?: string;
     launchId?: string;
 }
-/**
- * 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 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;
 interface ReconnectLoopOpts {
     host: Host;
     target: ReconnectTarget;
-    /** Exit code from the initial interactive run (treated as connected). */
     initialExit: number;
-    /** Test seams for the re-attach and wait. */
     reattach?: (host: Host, target: ReconnectTarget) => ReconnectOutcome;
     wait?: (ms: number) => Promise<'elapsed' | 'interrupted'>;
     write?: (s: string) => void;
 }
-/** Drive the reconnect loop from the initial run's outcome to a terminal code. */
 export declare function reconnectInteractiveSession(opts: ReconnectLoopOpts): Promise<number>;
 export {};