@phnx-labs/agents-cli 1.22.26 → 1.22.28

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,16 +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. 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 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
@@ -94,7 +126,8 @@ export declare function reattachRemoteCommand(sessionId: string): string;
  * 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) plus whether this attempt connected.
+ * 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 {

package/dist/lib/hosts/reconnect.js

@@ -19,15 +19,20 @@
  * fall through to resume so the user is put back into the agent. There is one
  * re-attach implementation (the peer's focus) to keep in sync.
  *
- * **Why the budget refills on `connected`, not on call duration.** ssh returns 255
- * for BOTH "couldn't connect at all" and "connected, then the link dropped." A
- * failed connect still takes up to `ConnectTimeout` (10s) to return, so timing
- * alone can't tell the two apart — a duration threshold below the connect timeout
- * would classify every hung connect as a live session and retry forever under a
- * sustained outage (the exact failure this feature exists to survive). Instead each
- * attempt runs a fast preflight probe: a reattach that genuinely reconnected (and
- * then dropped again) refills the retry budget; one that never reached the host
- * counts against it, so a sustained outage gives up after MAX_ATTEMPTS.
+ * **What it takes to refill the budget: reached the host AND held the pane.** ssh
+ * returns 255 for BOTH "couldn't connect at all" and "connected, then the link
+ * dropped." A failed connect still takes up to `ConnectTimeout` (10s) to return, so
+ * the duration of the whole call can't tell the two apart — a threshold below the
+ * connect timeout would classify every hung connect as a live session and retry
+ * forever under a sustained outage (the exact failure this feature exists to
+ * survive). So each attempt runs a fast preflight probe FIRST, and only once that
+ * probe proves the host reachable does the interactive attach run — which means the
+ * ATTACH's own duration is a clean signal, measured with the connect phase already
+ * behind it. A reattach that reached the host and then held for at least
+ * {@link MIN_HOLD_MS} refills the retry budget, so a long session that blinks all
+ * day keeps reconnecting. Everything else — never reached the host, or reached it
+ * and died right back — counts against the budget, so a sustained outage and a
+ * fast-flapping link both give up after {@link MAX_ATTEMPTS}.
  *
  * The retry policy is a pure state machine (`reconnectStep`) so it is unit-tested
  * without touching SSH; the loop (`reconnectInteractiveSession`) only adds the real
@@ -54,16 +59,21 @@
  * regardless of the peer's `agents` version (the remap happens in the shell
  * wrapper THIS process sends).
  *
- * This does NOT close every way `reconnectStep` can loop on a real transport
- * 255: a genuinely recurring LOCAL ssh failure (a fast-flapping link, an
- * attach that dies at the TTY stage on every reconnect) still refills the
- * budget every time by design (see "Why the budget refills on `connected`"
- * above) and can still print "attempt 1/N" indefinitely. That's an accepted,
- * pre-existing tradeoff of the original feature, not something this fix
- * changes either way — tracked separately (agents-cli#1884), not fixed here.
+ * A recurring LOCAL ssh failure used to defeat the budget the same way, and the
+ * remap alone did not close it (agents-cli#1884): `connected` was set by the
+ * preflight probe and said nothing about whether the attach that followed held, so
+ * a fast-flapping link — or an attach that died at the TTY-negotiation stage every
+ * single time — refilled the budget on every cycle, printed "attempt 1/N" forever,
+ * and left `MAX_ATTEMPTS` bounding nothing. The {@link MIN_HOLD_MS} floor above is
+ * what closes it: an attach that dies immediately is not a reconnection, so the
+ * budget drains and the loop gives up with {@link unstableNotice}. A flat total-
+ * attempt or wall-clock ceiling that ignored `connected` was the alternative and is
+ * deliberately NOT taken — any fixed total eventually strands the all-day-blinking
+ * session this feature exists for, while the hold floor only ever stops a loop that
+ * is failing to put the user back into the agent.
  */
 import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
-import { sshTargetFor } from './types.js';
+import { hostIdentityArgs, sshTargetFor } 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`. */
 export const SSH_CONN_FAILURE = 255;
@@ -71,13 +81,22 @@ export 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 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 const MAX_ATTEMPTS = 6;
 const BASE_BACKOFF_MS = 2_000;
 const MAX_BACKOFF_MS = 30_000;
+/** How long a reattach must hold the remote pane before it counts as a genuine
+ *  reconnection that refills the budget. Measured on the interactive attach ALONE
+ *  — the preflight probe has already returned by then, so this is not the connect
+ *  timing the file header rules out. 10s is comfortably longer than any attach that
+ *  dies during TTY negotiation and far shorter than a session the user is working
+ *  in; a link that drops the user out inside 10s on every attempt is one this loop
+ *  should stop retrying, not one it should keep re-entering. */
+export const MIN_HOLD_MS = 10_000;
 export function initialReconnectState() {
     return { attempt: 0 };
 }
@@ -85,6 +104,16 @@ export function initialReconnectState() {
 export function backoffMs(attempt) {
     return Math.min(BASE_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
 }
+/**
+ * Did this attempt genuinely put the user back into the agent? Only such an attempt
+ * refills the retry budget — it must have reached the host AND held the pane for at
+ * least {@link MIN_HOLD_MS}. An attach that reached the host and died right back is
+ * a flapping link, not a reconnection, and counts against the budget like an
+ * unreachable host (agents-cli#1884; see the file header).
+ */
+export function refillsBudget(outcome) {
+    return outcome.connected && outcome.heldMs >= MIN_HOLD_MS;
+}
 /**
  * Decide what to do after a run/re-attach returned `outcome`. Pure — the only
  * input is the prior state and the outcome, the only output is the next action.
@@ -92,14 +121,15 @@ export function backoffMs(attempt) {
  *  - 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 function reconnectStep(state, outcome) {
     if (outcome.code !== SSH_CONN_FAILURE)
         return { action: 'stop', code: outcome.code };
-    const attempts = outcome.connected ? 0 : state.attempt;
+    const attempts = refillsBudget(outcome) ? 0 : state.attempt;
     if (attempts >= MAX_ATTEMPTS)
         return { action: 'stop', code: SSH_CONN_FAILURE };
     return { action: 'retry', waitMs: backoffMs(attempts), state: { attempt: attempts + 1 } };
@@ -110,11 +140,22 @@ export function reconnectNotice(sessionId, host, attempt, waitMs) {
     const when = secs <= 1 ? 'now' : `in ${secs} seconds`;
     return `\nConnection to ${host} dropped — the agent is still running there. Reconnecting to ${sessionId.slice(0, 8)} ${when} (attempt ${attempt}/${MAX_ATTEMPTS})…\n`;
 }
-/** Notice shown once the retry budget is spent. 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 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 function exhaustedNotice(sessionId, host) {
     return `\nCouldn't reconnect to ${host} after ${MAX_ATTEMPTS} attempts. The agent may still be running — get back in when the network is back:\n  agents reconnect ${sessionId.slice(0, 8)}\n`;
 }
+/** 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 function unstableNotice(sessionId, host) {
+    const secs = Math.round(MIN_HOLD_MS / 1000);
+    return `\nGave up reconnecting to ${host} after ${MAX_ATTEMPTS} attempts — it kept dropping again within ${secs} seconds of getting back in. The agent may still be running there; reconnect once the link is stable:\n  agents reconnect ${sessionId.slice(0, 8)}\n`;
+}
 /** 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
@@ -168,16 +209,23 @@ export function reattachRemoteCommand(sessionId) {
  * 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) plus whether this attempt connected.
+ * clean detach; other = session ended), whether this attempt connected, and how
+ * long the attach held — the two inputs {@link refillsBudget} decides on.
  */
 export function reattachRemoteSession(host, sessionId) {
     const target = sshTargetFor(host);
+    const extraSshArgs = hostIdentityArgs(host);
     // Fresh (non-multiplexed) reachability probe: code 0 means the handshake actually
     // completed, so a hung/failed connect is never mistaken for a live reconnection.
-    const probe = sshExec(target, 'true', { multiplex: false });
+    // RUSH-2265: pass host identity on every hop (probe + stream), not only the first.
+    const probe = sshExec(target, 'true', { multiplex: false, extraSshArgs });
     if (probe.code !== 0)
-        return { code: SSH_CONN_FAILURE, connected: false };
-    return { code: sshStream(target, reattachRemoteCommand(sessionId), { tty: true }), connected: true };
+        return { code: SSH_CONN_FAILURE, connected: false, heldMs: 0 };
+    // Timed from AFTER the probe returned, so this is the attach's own duration and
+    // carries none of the connect phase the file header rules out as a signal.
+    const startedAt = Date.now();
+    const code = sshStream(target, reattachRemoteCommand(sessionId), { tty: true, extraSshArgs });
+    return { code, connected: true, heldMs: Date.now() - startedAt };
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
@@ -190,15 +238,25 @@ export async function reconnectInteractiveSession(opts) {
     const wait = opts.wait ?? sleep;
     const reattach = opts.reattach ?? reattachRemoteSession;
     let state = initialReconnectState();
-    // The initial run reached the point of running the agent, so it connected.
-    let outcome = { code: opts.initialExit, connected: true };
+    // The initial run reached the point of running the agent, so it connected. Its
+    // hold duration is never measured — exec.ts owns that call — and never needs to
+    // be: refilling is a no-op at attempt 0, which is where the loop starts, so this
+    // outcome can only ever produce the first retry either way.
+    let outcome = { code: opts.initialExit, connected: true, heldMs: 0 };
     for (;;) {
         const decision = reconnectStep(state, outcome);
         if (decision.action === 'stop') {
-            if (decision.code === SSH_CONN_FAILURE)
-                write(exhaustedNotice(opts.sessionId, opts.host.name));
-            else if (decision.code === REMOTE_EXIT_255_REMAPPED)
+            // A spent budget has two shapes and one wrong message: `outcome` is the
+            // reattach that spent it, so an unreachable host reads "couldn't reconnect"
+            // and a link that reconnected but kept dropping reads as exactly that.
+            if (decision.code === SSH_CONN_FAILURE) {
+                write(outcome.connected
+                    ? unstableNotice(opts.sessionId, opts.host.name)
+                    : exhaustedNotice(opts.sessionId, opts.host.name));
+            }
+            else if (decision.code === REMOTE_EXIT_255_REMAPPED) {
                 write(remoteExitNotice(opts.sessionId, opts.host.name));
+            }
             return decision.code;
         }
         write(reconnectNotice(opts.sessionId, opts.host.name, decision.state.attempt, decision.waitMs));

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

@@ -53,8 +53,8 @@ export interface MatchHostOptions {
      * "Unknown device" verdict reachable).
      */
     allowBareLiteral?: boolean;
-    /** Override the affinity pick for the `auto` sentinel (tests). Defaults to
-     * `resolveDeviceAffinity({})` — the same engine `agents run --device auto` uses. */
+    /** Override the affinity pick for generic `auto` host resolution in tests.
+     * Harness-aware run/team placement resolves `auto` before reaching this core. */
     resolveAuto?: () => DeviceAffinityPlan;
 }
 /**

package/dist/lib/hosts/registry.js

@@ -94,6 +94,7 @@ function deviceHost(device, user, overlay) {
         source: 'inline',
         ...(address ? { address } : {}),
         user: user ?? device.user,
+        identityFile: device.auth.identityFile,
         os: device.platform !== 'unknown' ? device.platform : overlay?.os,
         ...(overlay?.caps?.length ? { caps: overlay.caps } : {}),
         enrolled: true,
@@ -148,11 +149,9 @@ function literalHost(token, host, user) {
  * into a dispatch verdict.
  */
 export async function matchHost(name, opts = {}) {
-    // `auto` is the same affinity sentinel `agents run --device auto` resolves
-    // (isDeviceAuto / resolveDeviceAffinity in ../smart-launch.js) — shared here so
-    // every caller through this one core (ssh, teams, dispatch/passthrough) picks a
-    // device the SAME way `run` does instead of rejecting it as "Unknown device
-    // 'auto'" (RUSH-2185). A `null` plan.host means the affinity engine picked this
+    // Generic host-only callers resolve `auto` through the affinity engine here;
+    // harness-aware run/team placement resolves it earlier with live probes. A
+    // `null` plan.host means the affinity engine picked this
     // very machine; resolve that as the local device/host entry (if any) rather than
     // returning nothing — callers that already special-case "target is this
     // machine" (teams add/create, the passthrough self-host check) then treat it as

package/dist/lib/hosts/remote-cmd.d.ts

@@ -140,6 +140,23 @@ export interface WindowsAgentsCommand {
  * not the progress stream.)
  */
 export declare const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'SilentlyContinue'";
+/**
+ * Strip a PowerShell CLIXML wrapper from stdout relayed off a Windows host.
+ *
+ * PowerShell 5.1 serializes progress / error / verbose records to CLIXML when a
+ * stream is a redirected pipe (an ssh capture, not a console): a `#< CLIXML`
+ * banner followed by one or more `<Objs …>…</Objs>` elements. {@link
+ * POWERSHELL_PROGRESS_SILENCE} suppresses the common "Preparing modules for
+ * first use." progress record at the source, but a Windows peer reached WITHOUT
+ * that prelude — a raw `agents ssh <win> 'agents … --json'`, an older peer, or a
+ * record on a stream we did not silence — can still emit the banner ahead of the
+ * real payload, which breaks a naive `JSON.parse` of the relayed `--json`
+ * (RUSH-2286). Remove the banner and every self-contained `<Objs …>…</Objs>`
+ * block, leaving the genuine payload untouched. A no-op (returns the input
+ * unchanged) when no `#< CLIXML` marker is present, so it is safe to apply on
+ * every remote-JSON boundary regardless of the peer's OS.
+ */
+export declare function stripClixml(stdout: string): string;
 export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
 /**
  * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a

package/dist/lib/hosts/remote-cmd.js

@@ -252,6 +252,35 @@ export function decodePowershell(encoded) {
  * not the progress stream.)
  */
 export const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'SilentlyContinue'";
+/**
+ * Strip a PowerShell CLIXML wrapper from stdout relayed off a Windows host.
+ *
+ * PowerShell 5.1 serializes progress / error / verbose records to CLIXML when a
+ * stream is a redirected pipe (an ssh capture, not a console): a `#< CLIXML`
+ * banner followed by one or more `<Objs …>…</Objs>` elements. {@link
+ * POWERSHELL_PROGRESS_SILENCE} suppresses the common "Preparing modules for
+ * first use." progress record at the source, but a Windows peer reached WITHOUT
+ * that prelude — a raw `agents ssh <win> 'agents … --json'`, an older peer, or a
+ * record on a stream we did not silence — can still emit the banner ahead of the
+ * real payload, which breaks a naive `JSON.parse` of the relayed `--json`
+ * (RUSH-2286). Remove the banner and every self-contained `<Objs …>…</Objs>`
+ * block, leaving the genuine payload untouched. A no-op (returns the input
+ * unchanged) when no `#< CLIXML` marker is present, so it is safe to apply on
+ * every remote-JSON boundary regardless of the peer's OS.
+ */
+export function stripClixml(stdout) {
+    if (!stdout.includes('#< CLIXML'))
+        return stdout;
+    // A CLIXML flush is the `#< CLIXML` banner immediately followed by one or more
+    // <Objs …>…</Objs> elements, as one contiguous block. Remove that whole unit,
+    // ANCHORED to the banner: the <Objs> removal is scoped to blocks that follow a
+    // banner, so a stray `<Objs>` appearing inside a legitimate JSON string value
+    // (a session title/prompt that quotes CLIXML text) is never touched — stripping
+    // <Objs> globally would silently delete JSON between two such substrings.
+    return stdout
+        .replace(/#< CLIXML[^\n]*\r?\n?(?:\s*<Objs\b[\s\S]*?<\/Objs>)*/g, '')
+        .trim();
+}
 export function windowsAgentsScript(cmd) {
     const { args, env, cwd, propagateExit = true } = cmd;
     const parts = [POWERSHELL_PROGRESS_SILENCE];

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

@@ -12,6 +12,9 @@ export interface HostTask {
     id: string;
     host: string;
     target: string;
+    /** OpenSSH private-key path retained for follow/reconcile/stop calls. */
+    identityFile?: string;
+    remoteShell?: 'posix' | 'powershell';
     agent: string;
     prompt: string;
     pid?: number;

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

@@ -67,3 +67,4 @@ export interface HostProvider {
  * resolves HostName/User/Port/Identity), else `user@address` (or `address`).
  */
 export declare function sshTargetFor(host: Host): string;
+export declare function hostIdentityArgs(host: Host): string[];

package/dist/lib/hosts/types.js

@@ -37,3 +37,6 @@ export function sshTargetFor(host) {
     }
     return host.user ? `${host.user}@${host.address}` : host.address;
 }
+export function hostIdentityArgs(host) {
+    return host.identityFile ? ['-i', host.identityFile, '-o', 'IdentitiesOnly=yes'] : [];
+}

package/dist/lib/menubar/install-menubar.d.ts

@@ -134,12 +134,11 @@ export declare function disableMenubarService(): void;
  * different CDHashes. Any digest gate therefore reports "changed" for exactly
  * the skew case it was meant to exempt.
  *
- * So ownership decides instead: the plist's `AGENTS_ENTRY` names the owner, and
- * only the owner may reinstall. A non-owner takes over only once the recorded
- * owner is gone from disk, which is what makes the rule converge — a dead
- * install cannot hold the helper hostage, and a live one cannot be fought over.
- * A same-install upgrade keeps its entry path, so `npm update` still installs
- * the new helper normally. Pure so the truth table is unit-testable.
+ * So the installed version decides release skew: a newer signed release takes
+ * ownership immediately, an older release cannot downgrade it, and equal foreign
+ * releases retain the recorded owner. The plist's `AGENTS_ENTRY` remains the
+ * ownership signal for legacy state with no version marker, where the cooldown
+ * bounds takeover churn. Pure so the truth table is unit-testable.
  */
 export declare function mayInstallMenubarHelper(opts: {
     /** `AGENTS_ENTRY` baked into the installed plist — the recorded owner. */
@@ -152,6 +151,10 @@ export declare function mayInstallMenubarHelper(opts: {
     helperExecMissing: boolean;
     /** Installed copy is ad-hoc while the shipped source is Developer ID. */
     needsDevIdHeal: boolean;
+    /** Version stamped beside the installed helper, or null for legacy state. */
+    installedVersion: string | null;
+    /** Version of the agents-cli install now attempting the heal. */
+    currentVersion: string | null;
     /** ms since the last self-heal reinstall, or null if none is recorded. */
     msSinceLastHeal: number | null;
     /** How long a non-owner waits before it may take over. */

package/dist/lib/menubar/install-menubar.js

@@ -23,6 +23,7 @@ import { sleepSync } from '../fs-atomic.js';
 import { getRuntimeStateDir, getHelpersDir } from '../state.js';
 import { getCliVersion, resolveAgentsBin, resolveInstalledLayout } from '../version.js';
 import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
+import { compareVersions } from '../agent-spec/primitives.js';
 const APP_BUNDLE_NAME = 'MenubarHelper.app';
 const INSTALL_DIR_NAME = 'agents-cli';
 const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
@@ -491,12 +492,11 @@ export function disableMenubarService() {
  * different CDHashes. Any digest gate therefore reports "changed" for exactly
  * the skew case it was meant to exempt.
  *
- * So ownership decides instead: the plist's `AGENTS_ENTRY` names the owner, and
- * only the owner may reinstall. A non-owner takes over only once the recorded
- * owner is gone from disk, which is what makes the rule converge — a dead
- * install cannot hold the helper hostage, and a live one cannot be fought over.
- * A same-install upgrade keeps its entry path, so `npm update` still installs
- * the new helper normally. Pure so the truth table is unit-testable.
+ * So the installed version decides release skew: a newer signed release takes
+ * ownership immediately, an older release cannot downgrade it, and equal foreign
+ * releases retain the recorded owner. The plist's `AGENTS_ENTRY` remains the
+ * ownership signal for legacy state with no version marker, where the cooldown
+ * bounds takeover churn. Pure so the truth table is unit-testable.
  */
 export function mayInstallMenubarHelper(opts) {
     // Repairs are never gated: a missing binary or a broken signing identity leaves
@@ -511,10 +511,18 @@ export function mayInstallMenubarHelper(opts) {
     // No owner recorded yet (fresh or pre-`AGENTS_ENTRY` plist) — adopt it.
     if (!opts.plistEntry)
         return true;
-    if (opts.plistEntry === opts.activeEntry)
-        return true; // we are the owner
     if (!opts.ownerEntryExists)
         return true; // the recorded owner is gone
+    if (opts.installedVersion && opts.currentVersion) {
+        const versionOrder = compareVersions(opts.currentVersion, opts.installedVersion);
+        if (versionOrder > 0)
+            return opts.sourceIsDeveloperId;
+        if (versionOrder < 0)
+            return false;
+        return opts.plistEntry === opts.activeEntry;
+    }
+    if (opts.plistEntry === opts.activeEntry)
+        return true; // we are the owner
     // A foreign install while the owner still exists. Refusing outright bounds the
     // loop but strands the user when the recorded owner is a stale copy that simply
     // still sits on disk (an old nvm node dir) while their daily driver upgrades:
@@ -534,7 +542,8 @@ export function mayInstallMenubarHelper(opts) {
     return opts.msSinceLastHeal === null || opts.msSinceLastHeal >= opts.cooldownMs;
 }
 /**
- * How long a non-owner install waits before it may take the helper over. Long
+ * How long a non-owner install waits before it may take an unversioned legacy
+ * helper over. Long
  * enough that a multi-install box restarts the helper at most once an hour
  * instead of every few seconds; short enough that a user who switched installs
  * gets their upgrade without hunting for `agents menubar setup`.
@@ -572,6 +581,8 @@ function mayHealMenubar(needsDevIdHeal) {
         ownerEntryExists: Boolean(plistEntry) && fs.existsSync(plistEntry),
         helperExecMissing: !fs.existsSync(installedExecutablePath()),
         needsDevIdHeal,
+        installedVersion: readInstalledMenubarVersion(),
+        currentVersion: getCliVersion(),
         msSinceLastHeal: msSinceLastMenubarHeal(),
         cooldownMs: MENUBAR_TAKEOVER_COOLDOWN_MS,
         sourceIsDeveloperId: Boolean(src) && hasDeveloperIdSignature(src),

package/dist/lib/menubar/snapshot.js

@@ -1,8 +1,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { buildRoutineListJson } from '../../commands/routines.js';
-import { backfillActiveRowsFromIndex, serializeActiveSessionsForJson, serializeSessionsJson } from '../../commands/sessions.js';
+import { backfillActiveRowsFromIndex, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson } from '../../commands/sessions.js';
 import { getConfigValue } from '../device-config.js';
+import { machineId } from '../machine-id.js';
 import { querySessions } from '../session/db.js';
 import { readActiveSessionsCache } from '../session/session-cache.js';
 import { getRuntimeStateDir } from '../state.js';
@@ -21,7 +22,19 @@ export async function computeMenubarSnapshot() {
         Promise.resolve(querySessions({ limit: 40, skipExistenceCheck: true })),
     ]);
     const active = readActiveSessionsCache('local');
-    const activeSessions = active?.sessions ?? [];
+    const rawSessions = active?.sessions ?? [];
+    // The raw cache is never filtered at write time (RUSH-2336) — it retains
+    // queued/closed/crashed rows so `--queued`/`--closed`/`--crashed` can
+    // recover them, and the daemon's warm-tick gather (unlike the CLI's own
+    // local gather) never stamps `machine` on a row. Stamp self here — this IS
+    // the 'local' scope by construction — then apply the ONE canonical
+    // bare-active selector so the menubar never shows a retained dead/queued
+    // row nor a process row of unverified liveness.
+    const self = machineId();
+    for (const s of rawSessions)
+        if (!s.machine)
+            s.machine = self;
+    const activeSessions = rawSessions.filter(isRunningLiveSession);
     backfillActiveRowsFromIndex(activeSessions);
     return {
         version: 1,