@phnx-labs/agents-cli 1.22.25 → 1.22.27

package/dist/lib/hosts/dispatch.js

@@ -10,7 +10,7 @@
  */
 import { randomUUID } from 'crypto';
 import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
-import { sshTargetFor } from './types.js';
+import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
 import { remoteShellFor, posixEnvExports } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
@@ -156,7 +156,7 @@ function terminateRemoteLaunch(task) {
         `sleep 1; kill -KILL -- -${pid} 2>/dev/null || true; ` +
         `elif kill -0 -- -${pid} 2>/dev/null; then exit 1; fi; ` +
         `rm -f ${task.remoteLog} ${task.remoteExit}`;
-    const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true });
+    const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true, extraSshArgs: task.identityFile ? ['-i', task.identityFile, '-o', 'IdentitiesOnly=yes'] : undefined });
     if (result.code !== 0) {
         throw new Error(`Failed to terminate remote task ${task.id} on ${task.host}: ` +
             `${(result.stderr || result.stdout).trim() || 'ssh error'}`);
@@ -210,7 +210,7 @@ export function stopDispatchedTask(task) {
         throw new Error(`Cannot stop remote task ${task.id}: launch returned no PID.`);
     }
     const command = buildStopRemoteCommand(task.pid, task.remoteExit);
-    const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true });
+    const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true, extraSshArgs: task.identityFile ? ['-i', task.identityFile, '-o', 'IdentitiesOnly=yes'] : undefined });
     if (result.code !== 0) {
         throw new Error(`Failed to stop remote task ${task.id} on ${task.host}: ` +
             `${(result.stderr || result.stdout).trim() || 'ssh error'}`);
@@ -271,6 +271,7 @@ async function launchDetached(host, target, opts) {
         timeoutMs: 30000,
         multiplex: !opts.copyCreds,
         hostKeyOpts: credHostKeyOpts,
+        extraSshArgs: hostIdentityArgs(host),
     });
     if (res.code !== 0) {
         throw new Error(`Failed to launch on "${host.name}": ${(res.stderr || res.stdout).trim() || 'ssh error'}`);
@@ -280,6 +281,7 @@ async function launchDetached(host, target, opts) {
         id,
         host: host.name,
         target,
+        identityFile: host.identityFile,
         agent: opts.agentLabel,
         prompt: opts.promptLabel,
         pid: Number.isFinite(pid) ? pid : undefined,
@@ -311,6 +313,7 @@ async function launchDetached(host, target, opts) {
         taskId: id,
         echo: true,
         timeoutMs: opts.timeoutMs,
+        extraSshArgs: hostIdentityArgs(host),
     });
     // -1 = the follow window closed while the run continues on the host. Leave the
     // record 'running' (do NOT freeze it terminal) so a later `hosts ps`/`logs`
@@ -464,6 +467,7 @@ export async function runInteractiveOnHost(host, opts) {
         tty: process.stdin.isTTY,
         multiplex: !opts.copyCreds,
         hostKeyOpts: credHostKeyOpts,
+        extraSshArgs: hostIdentityArgs(host),
     });
 }
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */

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

@@ -24,6 +24,28 @@ interface RemoteSpec {
     /** Flags appended when running non-interactively (no local TTY / `--no-tty`). */
     nonInteractive?: string[];
 }
+/**
+ * First-class groups that run transparently on a remote via SSH when
+ * `--host`/`--device` is present. Keep both canonical names and aliases
+ * (`repo`/`repos`, `exec`/`run`) so either argv form routes the same way.
+ *
+ * Prefer adding here over per-command SSH code — this is the single choke point.
+ *
+ * Every key MUST be a real top-level command (a `KNOWN_TOP_LEVEL_COMMANDS`
+ * member) — `passthrough.test.ts` asserts it. A key that is not one is dead:
+ * the gate in {@link maybeRunOnHost} rejects the name as unknown before this
+ * table is consulted, and before that gate existed it SSH'd a command the peer
+ * would also reject. `cli`/`packages`/`versions`/`daemon` were exactly that
+ * (the commands are `clis`, `registry`/`search`/`install`/`publish`,
+ * `add`/`use`/`list`, and none) and were removed.
+ */
+export declare const REMOTE_PASSTHROUGH: Record<string, RemoteSpec>;
+/**
+ * Commands that register and interpret `--host`/`--device` themselves — must
+ * fall through to local commander even when the flag is present. Do not add
+ * these to {@link REMOTE_PASSTHROUGH}.
+ */
+export declare const OWN_HOST_COMMANDS: Set<string>;
 /** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
 export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
 /** Injectable dependencies for {@link runFleetPassthrough} — used by tests. */
@@ -61,6 +83,29 @@ export declare function runFleetPassthrough(command: string, allArgs: string[],
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
  */
 export declare function maybeRunOnHost(command: string, allArgs: string[], opts?: FleetPassthroughOptions): Promise<boolean>;
+/**
+ * `--host` passthrough for a **standalone binary** whose command name is fixed by
+ * the binary itself (the `browser`/`computer` bins, `dist/browser.js` etc.) rather
+ * than being the first argv token.
+ *
+ * `agents browser … --host <box>` routes through {@link maybeRunOnHost} in
+ * index.ts, but the standalone `browser` binary never enters index.ts — so without
+ * this it dropped `--host` entirely (commander errored with `unknown option
+ * '--host'`). This wires the identical routing: it synthesizes the implicit command
+ * token (`browser`) at the front of the argv so the remote invocation builds as
+ * `agents browser …`, delegates to {@link maybeRunOnHost}, and returns `true` when
+ * it dispatched the run to a remote (the local program must then NOT parse).
+ *
+ * On a local / self-host fall-through it rewrites `process.argv` to the ORIGINAL
+ * args minus the routing flags — never the synthetic command token — so the
+ * standalone commander program parses cleanly and never sees an unknown `--host`.
+ * When no routing flag is present it leaves `process.argv` untouched (the common
+ * case), so an unrelated flag like `--no-tty` is never stripped from a purely local
+ * run.
+ *
+ * @param command the fixed command name the binary stands for (`'browser'`).
+ */
+export declare function maybeRunStandaloneOnHost(command: string, opts?: FleetPassthroughOptions): Promise<boolean>;
 /**
  * Run `agents <forwardedArgs>` on `host` over SSH, streaming its output, and
  * return the exit code. The single place the SSH hop is built, so every remote

package/dist/lib/hosts/passthrough.js

@@ -21,7 +21,7 @@ import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
 import { resolveHost, resolveHostByCap } from './registry.js';
 import { sshTargetFor } from './types.js';
 import { dispatchAgentsCommand, withActorEnv } from './dispatch.js';
-import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
+import { stripRoutingFlags, buildRemoteAgentsInvocation, stripClixml, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
@@ -36,8 +36,16 @@ import { isKnownTopLevelCommand } from '../startup/command-registry.js';
  * (`repo`/`repos`, `exec`/`run`) so either argv form routes the same way.
  *
  * Prefer adding here over per-command SSH code — this is the single choke point.
+ *
+ * Every key MUST be a real top-level command (a `KNOWN_TOP_LEVEL_COMMANDS`
+ * member) — `passthrough.test.ts` asserts it. A key that is not one is dead:
+ * the gate in {@link maybeRunOnHost} rejects the name as unknown before this
+ * table is consulted, and before that gate existed it SSH'd a command the peer
+ * would also reject. `cli`/`packages`/`versions`/`daemon` were exactly that
+ * (the commands are `clis`, `registry`/`search`/`install`/`publish`,
+ * `add`/`use`/`list`, and none) and were removed.
  */
-const REMOTE_PASSTHROUGH = {
+export const REMOTE_PASSTHROUGH = {
     // status / inspect
     view: {},
     inspect: {},
@@ -65,10 +73,8 @@ const REMOTE_PASSTHROUGH = {
     permissions: {},
     perms: {},
     mcp: {},
-    cli: {},
     subagents: {},
     workflows: {},
-    packages: {},
     models: {},
     profiles: {},
     defaults: {},
@@ -89,20 +95,18 @@ const REMOTE_PASSTHROUGH = {
     lock: {},
     feedback: {},
     wallet: {},
-    daemon: {},
     pty: {},
     tmux: {},
     watchdog: {},
     factory: {},
     browser: {},
-    versions: {},
 };
 /**
  * Commands that register and interpret `--host`/`--device` themselves — must
  * fall through to local commander even when the flag is present. Do not add
  * these to {@link REMOTE_PASSTHROUGH}.
  */
-const OWN_HOST_COMMANDS = new Set([
+export const OWN_HOST_COMMANDS = new Set([
     'run',
     'exec', // deprecated alias of run
     'harness', // `--host <agent>` names the host CLI to run under, not a remote device
@@ -186,7 +190,9 @@ function buildFleetForwardedArgs(allArgs) {
 /** Parse stdout as JSON; on failure return an object describing the error. */
 function safeJsonParse(stdout) {
     try {
-        return JSON.parse(stdout);
+        // A Windows device relays its `--json` through PowerShell, which can prefix a
+        // CLIXML banner ahead of the payload — strip it before parsing (RUSH-2286).
+        return JSON.parse(stripClixml(stdout));
     }
     catch {
         return { parseError: 'invalid JSON', snippet: stdout.trim().slice(0, 200) };
@@ -551,6 +557,51 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     });
     return true;
 }
+/**
+ * `--host` passthrough for a **standalone binary** whose command name is fixed by
+ * the binary itself (the `browser`/`computer` bins, `dist/browser.js` etc.) rather
+ * than being the first argv token.
+ *
+ * `agents browser … --host <box>` routes through {@link maybeRunOnHost} in
+ * index.ts, but the standalone `browser` binary never enters index.ts — so without
+ * this it dropped `--host` entirely (commander errored with `unknown option
+ * '--host'`). This wires the identical routing: it synthesizes the implicit command
+ * token (`browser`) at the front of the argv so the remote invocation builds as
+ * `agents browser …`, delegates to {@link maybeRunOnHost}, and returns `true` when
+ * it dispatched the run to a remote (the local program must then NOT parse).
+ *
+ * On a local / self-host fall-through it rewrites `process.argv` to the ORIGINAL
+ * args minus the routing flags — never the synthetic command token — so the
+ * standalone commander program parses cleanly and never sees an unknown `--host`.
+ * When no routing flag is present it leaves `process.argv` untouched (the common
+ * case), so an unrelated flag like `--no-tty` is never stripped from a purely local
+ * run.
+ *
+ * @param command the fixed command name the binary stands for (`'browser'`).
+ */
+export async function maybeRunStandaloneOnHost(command, opts) {
+    const rawArgs = process.argv.slice(2);
+    const hasRoutingFlag = flagValue(rawArgs, 'host', 'H') !== undefined ||
+        flagValue(rawArgs, 'device') !== undefined ||
+        flagValue(rawArgs, 'hosts') !== undefined ||
+        flagValue(rawArgs, 'devices') !== undefined;
+    // No routing flag → nothing to route or strip. Leave argv alone so a purely
+    // local run keeps every flag it passed.
+    if (!hasRoutingFlag)
+        return false;
+    // Keep --help/--version local (docs must work without a reachable host), mirroring
+    // index.ts's `helpOrVersionRequested` guard, but still strip the routing flags
+    // below so commander doesn't choke on them.
+    const helpOrVersion = rawArgs.some((a) => a === '--help' || a === '-h' || a === '--version' || a === '-V');
+    if (!helpOrVersion && (await maybeRunOnHost(command, [command, ...rawArgs], opts))) {
+        return true;
+    }
+    // Local / self-host fall-through (maybeRunOnHost may have rewritten process.argv
+    // with the synthetic command token). Rebuild argv from the original args minus
+    // the routing flags so the standalone program parses cleanly.
+    process.argv = [process.argv[0], process.argv[1], ...stripRoutingFlags(rawArgs, STRIP_SPECS)];
+    return false;
+}
 /**
  * Run `agents <forwardedArgs>` on `host` over SSH, streaming its output, and
  * return the exit code. The single place the SSH hop is built, so every remote

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

@@ -55,6 +55,7 @@ export interface FollowOptions {
     pollMs?: number;
     /** Idle-backoff ceiling (default 4× the fast interval, min 4000ms). */
     maxPollMs?: number;
+    extraSshArgs?: string[];
 }
 /**
  * Build the per-task sentinel that separates the log tail from the exit-file
@@ -124,7 +125,7 @@ export declare function parseStreamingExitFrame(stderr: Buffer, taskId: string):
  * File identity (`dev:ino`) of a path on the remote host, or null if it can't be
  * stat'd. GNU (`-c`) then BSD (`-f`) format, so it works on Linux and macOS hosts.
  */
-export declare function readRemoteFileId(target: string, remotePath: string): string | null;
+export declare function readRemoteFileId(target: string, remotePath: string, extraSshArgs?: string[]): string | null;
 /**
  * True when the local mirror file IS the very file we're tailing — the
  * localhost-as-host case, where `remoteLog` ($HOME-expanded) and `localLogPath`

package/dist/lib/hosts/progress.js

@@ -160,8 +160,8 @@ export function parseStreamingExitFrame(stderr, taskId) {
  * File identity (`dev:ino`) of a path on the remote host, or null if it can't be
  * stat'd. GNU (`-c`) then BSD (`-f`) format, so it works on Linux and macOS hosts.
  */
-export function readRemoteFileId(target, remotePath) {
-    const res = sshExec(target, `stat -c '%d:%i' ${remotePath} 2>/dev/null || stat -f '%d:%i' ${remotePath} 2>/dev/null`, { timeoutMs: 8000 });
+export function readRemoteFileId(target, remotePath, extraSshArgs) {
+    const res = sshExec(target, `stat -c '%d:%i' ${remotePath} 2>/dev/null || stat -f '%d:%i' ${remotePath} 2>/dev/null`, { timeoutMs: 8000, extraSshArgs });
     const id = res.stdout.trim();
     return id || null;
 }
@@ -189,7 +189,7 @@ export async function followHostTask(target, opts) {
     let mirror = true;
     try {
         const s = fs.statSync(local);
-        if (mirrorAliasesSource(`${s.dev}:${s.ino}`, readRemoteFileId(target, opts.remoteLog))) {
+        if (mirrorAliasesSource(`${s.dev}:${s.ino}`, readRemoteFileId(target, opts.remoteLog, opts.extraSshArgs))) {
             mirror = false;
         }
     }
@@ -223,6 +223,7 @@ export async function followHostTask(target, opts) {
                 timeoutMs: remaining,
                 signal: abort.signal,
                 multiplex: true,
+                extraSshArgs: opts.extraSshArgs,
                 onStdout: (chunk) => { gotOutput = flush(chunk) || gotOutput; },
             });
             exitFrame = parseStreamingExitFrame(stream.stderr, opts.taskId);

package/dist/lib/hosts/providers/devices.js

@@ -48,6 +48,7 @@ function deviceToPoolHost(device) {
         source: 'inline',
         address,
         user: device.user,
+        identityFile: device.auth.identityFile,
         ...(device.platform !== 'unknown' ? { os: device.platform } : {}),
         enrolled: true,
         status: statusOf(device),

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

@@ -31,7 +31,7 @@ export declare function remoteAgentsVersion(target: string, os?: string): string
  * equivalents (`Select-Object -Last`, `Test-Path`). Pure/exported. */
 export declare function buildBootstrapCommand(spec: string, os?: string): string;
 /** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
-export declare function bootstrapAgentsCli(target: string, version: string | null, os?: string): {
+export declare function bootstrapAgentsCli(target: string, version: string | null, os?: string, extraSshArgs?: string[]): {
     ok: boolean;
     output: string;
 };
@@ -42,6 +42,8 @@ export interface ReadyProbe {
     version: string | null;
     /** Raw `agents view`/`list` output, for installed-agent checks. */
     view: string;
+    /** True when the ssh probe timed out before the sentinel arrived. */
+    timedOut?: boolean;
 }
 /**
  * Answer every readiness question in ONE ssh round-trip: reachable? (the login
@@ -59,11 +61,13 @@ export interface ReadyProbe {
  * absorbed by its `.trim()`. Pure/exported so both branches are unit-testable.
  */
 export declare function buildReadyProbeCommand(os?: string): string;
-export declare function readyProbe(target: string, os?: string): ReadyProbe;
+export declare function readyProbe(target: string, os?: string, extraSshArgs?: string[]): ReadyProbe;
 /** Pure parser for `readyProbe` output (unit-tested without ssh). */
 export declare function parseReadyProbe(stdout: string): ReadyProbe;
 /** True if `view` output lists the named agent (word-boundary, case-insensitive). */
 export declare function viewHasAgent(view: string, agent: string): boolean;
+/** Read the requested harness's sign-in verdict from `agents view --json`. */
+export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;
 export interface EnsureReadyOptions {
     agent: string;
     /** Throw instead of warn when the agent isn't installed remotely. */

package/dist/lib/hosts/ready.js

@@ -9,7 +9,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { sshExec, shellQuote } from '../ssh-exec.js';
-import { sshTargetFor } from './types.js';
+import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
@@ -87,9 +87,9 @@ export function buildBootstrapCommand(spec, os) {
     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) {
+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 });
+    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. */
@@ -113,15 +113,19 @@ export function buildReadyProbeCommand(os) {
     if (remoteShellFor(os) === 'powershell') {
         const script = `${POWERSHELL_PROGRESS_SILENCE}; ` +
             `agents --version 2>$null; Write-Output "${READY_MARKER}"; ` +
-            `agents view 2>$null; if ($LASTEXITCODE -ne 0) { agents list 2>$null }`;
+            `agents view --json 2>$null; if ($LASTEXITCODE -ne 0) { agents list 2>$null }`;
         return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
     }
     const script = `agents --version 2>/dev/null; printf '\\n${READY_MARKER}\\n'; ` +
-        `agents view 2>/dev/null || agents list 2>/dev/null`;
+        `agents view --json 2>/dev/null || agents list 2>/dev/null`;
     return `bash -lc ${shellQuote(script)}`;
 }
-export function readyProbe(target, os) {
-    const r = sshExec(target, buildReadyProbeCommand(os), { timeoutMs: 20000 });
+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). */
@@ -136,6 +140,22 @@ export function parseReadyProbe(stdout) {
 export function viewHasAgent(view, agent) {
     return new RegExp(`\\b${agent}\\b`, 'i').test(view);
 }
+/** Read the requested harness's sign-in verdict from `agents view --json`. */
+export function viewAgentSignedIn(view, agent) {
+    try {
+        const rows = JSON.parse(view);
+        const row = rows.find((candidate) => candidate.agent?.toLowerCase() === agent.toLowerCase());
+        if (!row)
+            return undefined;
+        const verdicts = (row.versions ?? [])
+            .map((version) => version.signedIn)
+            .filter((value) => typeof value === 'boolean');
+        return verdicts.length === 0 ? undefined : verdicts.some(Boolean);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * 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
@@ -145,7 +165,12 @@ export function viewHasAgent(view, agent) {
  */
 export function ensureHostReady(host, opts) {
     const target = sshTargetFor(host);
-    const probe = readyProbe(target, host.os ?? resolveRemoteOsSync(host.name));
+    const probe = readyProbe(target, host.os ?? resolveRemoteOsSync(host.name), hostIdentityArgs(host));
+    if (probe.timedOut) {
+        throw new Error(`Host "${host.name}" (${target}) did not respond in time — the SSH probe timed out after 20 seconds. ` +
+            `The host may be slow to start a login shell (nvm/sdkman init, cold node startup). ` +
+            `Retry, or run \`agents ssh ${host.name} agents view\` to confirm manually.`);
+    }
     if (!probe.reachable) {
         throw new Error(`Host "${host.name}" (${target}) is not reachable over SSH. Check it's online and key auth works.`);
     }

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

@@ -35,7 +35,7 @@ export declare function classifyExit(res: Pick<SshExecResult, 'code' | 'stdout'
  * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
  * remote shell expands $HOME (same contract as progress.ts's fetch).
  */
-export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number): RemoteExitState;
+export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number, identityFile?: string): 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`

package/dist/lib/hosts/reconcile.js

@@ -10,7 +10,7 @@
  * record. We only ever CONFIRM completion; an unreachable host or an absent
  * `.exit` leaves the record `running` (we never guess failure).
  */
-import { sshExec, sshReachable } from '../ssh-exec.js';
+import { sshExec } from '../ssh-exec.js';
 import { updateTask, terminalPatch } from './tasks.js';
 /**
  * Classify a `cat <remoteExit>` result into a remote run state. Pure: all the
@@ -35,8 +35,12 @@ export function classifyExit(res) {
  * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
  * remote shell expands $HOME (same contract as progress.ts's fetch).
  */
-export function readRemoteExit(target, remoteExit, timeoutMs = 6000) {
-    return classifyExit(sshExec(target, `cat ${remoteExit} 2>/dev/null`, { timeoutMs, multiplex: true }));
+export function readRemoteExit(target, remoteExit, timeoutMs = 6000, identityFile) {
+    return classifyExit(sshExec(target, `cat ${remoteExit} 2>/dev/null`, {
+        timeoutMs,
+        multiplex: true,
+        extraSshArgs: identityFile ? ['-i', identityFile, '-o', 'IdentitiesOnly=yes'] : undefined,
+    }));
 }
 /**
  * Heal one record. Terminal records are immutable (and never re-probed); a
@@ -46,7 +50,7 @@ export function readRemoteExit(target, remoteExit, timeoutMs = 6000) {
 export function reconcileTask(task) {
     if (task.status !== 'running')
         return task;
-    const st = readRemoteExit(task.target, task.remoteExit);
+    const st = readRemoteExit(task.target, task.remoteExit, 6000, task.identityFile);
     if (st.state !== 'done')
         return task;
     return updateTask(task.id, terminalPatch(st.code)) ?? task;
@@ -66,11 +70,16 @@ export function reconcileRunningTasks(tasks) {
     const reachable = new Map();
     const patched = new Map();
     for (const t of running) {
-        if (!reachable.has(t.target))
-            reachable.set(t.target, sshReachable(t.target, 6000));
+        if (!reachable.has(t.target)) {
+            const probe = sshExec(t.target, 'true', {
+                timeoutMs: 6000,
+                extraSshArgs: t.identityFile ? ['-i', t.identityFile, '-o', 'IdentitiesOnly=yes'] : undefined,
+            });
+            reachable.set(t.target, probe.code === 0);
+        }
         if (!reachable.get(t.target))
             continue; // host down → leave running
-        const st = readRemoteExit(t.target, t.remoteExit);
+        const st = readRemoteExit(t.target, t.remoteExit, 6000, t.identityFile);
         if (st.state === 'done') {
             const updated = updateTask(t.id, terminalPatch(st.code));
             if (updated)

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

@@ -6,13 +6,23 @@ export declare const SSH_CONN_FAILURE = 255;
  *  {@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 failed-to-connect reattaches before giving up. Backoff is capped at
- *  {@link MAX_BACKOFF_MS}. A reattach that actually reconnected (then dropped again)
- *  refills the budget, so a long session that blinks all day reconnects every time
- *  — only consecutive UNREACHABLE attempts exhaust it. */
+/** 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 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. */
+export declare const MIN_HOLD_MS = 10000;
 export interface ReconnectState {
-    /** Consecutive failed-to-connect reattaches since the last genuine reconnection. */
+    /** Consecutive unproductive reattaches since the last genuine reconnection — one
+     *  that reached the host and held for {@link MIN_HOLD_MS}. */
     attempt: number;
 }
 export interface ReconnectOutcome {
@@ -20,8 +30,13 @@ export interface ReconnectOutcome {
     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. Drives the budget refill (see file head). */
+     *  that couldn't reach the host is not. Half of the budget refill (see file head). */
     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. */
+    heldMs: number;
 }
 export type ReconnectDecision = {
     action: 'stop';
@@ -34,6 +49,14 @@ 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).
+ */
+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.
@@ -41,15 +64,25 @@ export declare function backoffMs(attempt: number): number;
  *  - 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 DID connect (a genuine reconnection that then
- *    dropped) refills the budget first; a 255 that never connected counts against
- *    it, so a host that stays unreachable gives up after MAX_ATTEMPTS.
+ *  - 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.
  */
 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;
-/** Notice shown once the retry budget is spent. */
+/** 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;
+/** 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;
 /** 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
@@ -75,13 +108,14 @@ export declare function remoteExitNotice(sessionId: string, host: string): strin
  */
 export declare function wrapRemoteExitCode(cmd: string): string;
 /**
- * The remote command a reattach runs — the peer's own reconnect verb
- * (`agents sessions focus <id> --local --attach-only`), 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. Split out from {@link reattachRemoteSession} so it is
- * unit-tested without SSH — mirrors `remoteAgentsJsonCommand` in
- * lib/remote-agents-json.ts.
+ * The remote command a reattach runs — the peer's own recovery verb
+ * (`agents sessions focus <id> --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.
  */
 export declare function reattachRemoteCommand(sessionId: string): string;
 /**
@@ -89,10 +123,11 @@ export declare function reattachRemoteCommand(sessionId: string): string;
  * `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 (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) plus whether this attempt connected.
+ * 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.
  */
 export declare function reattachRemoteSession(host: Host, sessionId: string): ReconnectOutcome;
 export interface ReconnectLoopOpts {