@phnx-labs/agents-cli 1.22.25 → 1.22.27

package/dist/lib/hosts/reconnect.js

@@ -11,19 +11,28 @@
  * SSH automatically, with bounded backoff, until the user detaches cleanly (the
  * remote returns 0) or the agent exits (the tmux session is gone; a non-255 code).
  *
- * The re-attach reuses the peer's OWN reconnect verb — `agents sessions focus <id>
- * --local --attach-only` joins the live local tmux pane there (no fork, no resumed
- * copy) — so there is no second re-attach implementation to keep in sync.
+ * The re-attach reuses the peer's OWN recovery verb — `agents sessions focus <id>
+ * --local` — which JOINS the live local tmux pane there (a second client, no fork)
+ * when it still exists, and RESUMES the session in place when the pane is already
+ * gone. Dropping `--attach-only` is deliberate: a reattach that lands after the
+ * remote pane died must not dead-end at a bare shell (the RUSH-2085 bug), it must
+ * 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
@@ -31,37 +40,37 @@
  *
  * **255 from the REMOTE side should never be trusted as "the link dropped."**
  * `reattachRemoteSession`'s `connected` flag is set as soon as the fast preflight
- * probe succeeds — it says nothing about whether the interactive attach that
- * follows actually reattached a live pane. If the REMOTE command (`agents
- * sessions focus <id> --local --attach-only`) itself ever happened to exit 255
- * for a reason that has nothing to do with the ssh transport, `sshStream` would
- * return that same 255, `reconnectStep` couldn't tell it apart from a genuine
- * drop, and `connected: true` would refill the retry budget forever — "attempt
- * 1/N" printed on every single cycle, the terminal filling with aborted-TTY
- * escape-code garbage, `MAX_ATTEMPTS` never actually bounding anything.
+ * probe succeeds — it says nothing about whether the interactive attach/resume
+ * that follows actually put the user back into the agent. If the REMOTE command
+ * (`agents sessions focus <id> --local`) itself ever happened to exit 255 for a
+ * reason that has nothing to do with the ssh transport, `sshStream` would return
+ * that same 255, `reconnectStep` couldn't tell it apart from a genuine drop, and
+ * `connected: true` would refill the retry budget forever — "attempt 1/N" printed
+ * on every single cycle, the terminal filling with aborted-TTY escape-code
+ * garbage, `MAX_ATTEMPTS` never actually bounding anything.
  *
- * Two candidate producers of that scenario were investigated —
- * `refuseFallback`'s login-shell fallback (commands/go.ts) and `jumpTo`'s
- * nested remote-tmux hop — and both turned out to be UNREACHABLE through this
- * exact remote command: under `--local`, `gatherLiveTargets` never sets a
- * foreign `.machine` (go.ts:61), so `remote` is always `undefined` in both,
- * and neither branch can fire (the same reasoning that made an earlier,
- * narrower fix here dead code — see git history). So this fix does not close
- * a confirmed incident cause; what it closes is the underlying channel-level
- * flaw that would make *any* future remote-side 255 producer — reachable today
- * or not — indistinguishable from a real drop. {@link wrapRemoteExitCode} wraps
- * the entire remote command so that whatever exit code it decides on, a 255 is
- * remapped to {@link REMOTE_EXIT_255_REMAPPED} before `sshStream` ever sees it,
- * regardless of which internal branch produced it and regardless of the peer's
- * `agents` version (the remap happens in the shell wrapper THIS process sends).
+ * The resume fall-through only widens that surface — the peer's focus now runs a
+ * full recovery path (`resumeSessionInPlace` / `runOnPeer`) on a dead pane, any
+ * step of which could in principle exit 255 for its own reasons. So the channel-
+ * level defense is what matters, not an audit of which branch can fire:
+ * {@link wrapRemoteExitCode} wraps the entire remote command so that whatever exit
+ * code it decides on, a 255 is remapped to {@link REMOTE_EXIT_255_REMAPPED} before
+ * `sshStream` ever sees it, regardless of which internal branch produced it and
+ * 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';
@@ -72,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 };
 }
@@ -86,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.
@@ -93,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 } };
@@ -111,9 +140,21 @@ 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. */
+/** 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 — reattach when the network is back:\n  agents sessions focus ${sessionId.slice(0, 8)}\n`;
+    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
@@ -121,7 +162,7 @@ export function exhaustedNotice(sessionId, host) {
  *  {@link wrapRemoteExitCode}). Distinct from {@link exhaustedNotice}, which is
  *  only for a genuinely spent retry budget. */
 export function remoteExitNotice(sessionId, host) {
-    return `\nReattach to ${sessionId.slice(0, 8)} on ${host} ended (not a network drop) — check whether it's still live:\n  agents sessions ${sessionId.slice(0, 8)}\n`;
+    return `\nReattach to ${sessionId.slice(0, 8)} on ${host} ended (not a network drop) — get back in, or check whether it's still live:\n  agents reconnect ${sessionId.slice(0, 8)}\n`;
 }
 /**
  * Wrap `cmd` in `bash -lc` (the login-shell pattern `buildRemoteAgentsInvocation`
@@ -145,16 +186,17 @@ export function wrapRemoteExitCode(cmd) {
     return `bash -lc ${shellQuote(guarded)}`;
 }
 /**
- * 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 function reattachRemoteCommand(sessionId) {
-    const inner = ['agents', 'sessions', 'focus', sessionId, '--local', '--attach-only']
+    const inner = ['agents', 'sessions', 'focus', sessionId, '--local']
         .map(shellQuote)
         .join(' ');
     return wrapRemoteExitCode(inner);
@@ -164,10 +206,11 @@ export function reattachRemoteCommand(sessionId) {
  * `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 function reattachRemoteSession(host, sessionId) {
     const target = sshTargetFor(host);
@@ -175,8 +218,12 @@ export function reattachRemoteSession(host, sessionId) {
     // completed, so a hung/failed connect is never mistaken for a live reconnection.
     const probe = sshExec(target, 'true', { multiplex: false });
     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 });
+    return { code, connected: true, heldMs: Date.now() - startedAt };
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
@@ -189,15 +236,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

@@ -148,11 +148,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,8 @@ export interface HostTask {
     id: string;
     host: string;
     target: string;
+    /** OpenSSH private-key path retained for follow/reconcile/stop calls. */
+    identityFile?: string;
     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/models.d.ts

@@ -43,7 +43,7 @@ export interface ModelCatalog {
     aliases: Record<string, string>;
 }
 /** How the model catalog source was obtained. */
-export type ModelSourceKind = 'bundle' | 'binary' | 'js' | 'cli';
+export type ModelSourceKind = 'bundle' | 'binary' | 'cli';
 /** Describes the location and extraction strategy for a model catalog source. */
 export interface ModelSource {
     path: string;
@@ -76,6 +76,35 @@ export declare function locateModelSource(agent: AgentId, version: string): Mode
  * current model and is kept.
  */
 export declare function dropBareLegacyIds(ids: string[]): string[];
+/**
+ * Scan raw binary/bundle text for canonical Claude model ids, then drop bare
+ * legacy prefixes (issue #1892). Two independent guards keep non-model strings
+ * out of the catalog:
+ *
+ *  - **Word-boundary anchors on the id regex.** The id must not be glued to a
+ *    surrounding identifier character, and must not be the truncated prefix of a
+ *    longer *version* token. `(?<![A-Za-z0-9_])` rejects a glued prefix;
+ *    `(?![A-Za-z0-9])` rejects a glued alnum suffix; `(?!\.\d)` rejects a
+ *    dotted-version continuation — so the bare-major prefix of the binary's own
+ *    "Typo in model ID" troubleshooting string `claude-sonnet-4.6` is not
+ *    scraped as `claude-sonnet-4`, while a real id followed by an unrelated `.`
+ *    suffix (`claude-fable-5.md`) still matches. Dash-separated segments only:
+ *    the dotted form never appears in a genuine id.
+ *
+ *    The id body is captured inside a lookahead (`(?=(...))\1`) so the greedy
+ *    `-\d+` run matches **atomically**: without it, a suffix-glued token like
+ *    `claude-opus-4-1x` would fail the trailing anchor on the full match, then
+ *    backtrack a segment and re-emit the bare `claude-opus-4` — the exact 404-able
+ *    id this scan exists to suppress (two packed strings can end up glued with no
+ *    separator in the extracted binary text). The atomic match fails outright
+ *    instead of degrading to the bare form.
+ *  - **`dropBareLegacyIds`.** A standalone `.includes("claude-opus-4")` prefix
+ *    check is a fully delimited string the anchors cannot tell apart from a real
+ *    bare id, so a bare `claude-<family>-<major>` is dropped only when a
+ *    more-specific sibling (`claude-opus-4-8`) is also present; a genuinely bare
+ *    current id with no sibling (`claude-sonnet-5`) is kept.
+ */
+export declare function scanClaudeCatalogIds(text: string): string[];
 /**
  * Parse `grok models` stdout into a catalog. Exported for unit tests.
  *