@phnx-labs/agents-cli 1.21.3 → 1.22.0

package/dist/lib/daemon.js

@@ -172,6 +172,16 @@ export function removeHeartbeat() {
     }
     catch { /* already removed */ }
 }
+/**
+ * A heartbeat is "fresh" when its last tick falls inside the wedge window — the
+ * same threshold isDaemonWedged() uses to decide a still-present daemon has gone
+ * unresponsive. A fresh heartbeat whose pid is alive is proof of a live, ticking
+ * daemon even when the pid file has been lost.
+ */
+function isHeartbeatFresh(hb) {
+    const elapsed = Date.now() - Date.parse(hb.lastTick);
+    return elapsed <= WEDGE_THRESHOLD_TICKS * MONITOR_TICK_MS;
+}
 export function isDaemonWedged() {
     const pid = readDaemonPid();
     if (!pid)
@@ -183,22 +193,49 @@ export function isDaemonWedged() {
         return false;
     if (hb.pid !== pid)
         return false;
-    const elapsed = Date.now() - Date.parse(hb.lastTick);
-    return elapsed > WEDGE_THRESHOLD_TICKS * MONITOR_TICK_MS;
+    return !isHeartbeatFresh(hb);
 }
 /** How long stopDaemon waits for a SIGTERMed daemon to exit before escalating. */
 const STOP_GRACE_MS = 5000;
 /** How long it waits after the hard tree-kill before giving up. */
 const STOP_KILL_GRACE_MS = 2000;
-/** Check if the daemon process is alive by sending signal 0 to the stored PID. */
-export function isDaemonRunning() {
+/**
+ * Resolve the PID of the live daemon, tolerant of a pid-file/heartbeat desync.
+ *
+ * The daemon writes the pid file once (on claim/start) but rewrites the
+ * heartbeat every tick. If the pid file is lost while the daemon keeps ticking
+ * — e.g. an earlier isDaemonRunning() found a stale/reused/dead pid and cleared
+ * the file, or it was removed out from under a live daemon — the pid file reads
+ * empty even though a daemon is genuinely alive and firing jobs. Reading only
+ * the pid file then reports "stopped" for a running scheduler, and (worse) lets
+ * claimDaemonInstance() start a SECOND daemon that double-fires every routine.
+ *
+ * So: trust the pid file when its pid is alive; otherwise trust a FRESH
+ * heartbeat whose pid is alive, and re-adopt the pid file so the desync heals.
+ * Returns null only when neither points at a live process (clearing a stale pid
+ * file on the way out).
+ */
+function resolveLiveDaemonPid() {
     const pid = readDaemonPid();
-    if (!pid)
-        return false;
-    if (isAlive(pid))
-        return true;
-    removeDaemonPid();
-    return false;
+    if (pid !== null && isAlive(pid))
+        return pid;
+    const hb = readHeartbeat();
+    if (hb && isAlive(hb.pid) && isHeartbeatFresh(hb)) {
+        if (pid !== hb.pid)
+            writeDaemonPid(hb.pid); // heal the pid-file/heartbeat desync
+        return hb.pid;
+    }
+    if (pid !== null)
+        removeDaemonPid();
+    return null;
+}
+/**
+ * Check whether a daemon is alive — via the pid file, or a fresh heartbeat when
+ * the pid file has been lost (see resolveLiveDaemonPid). Heals the pid file as a
+ * side effect so a subsequent read is consistent.
+ */
+export function isDaemonRunning() {
+    return resolveLiveDaemonPid() !== null;
 }
 /**
  * Single-instance claim for the daemon foreground entrypoint.
@@ -217,16 +254,28 @@ export function isDaemonRunning() {
  */
 export function claimDaemonInstance() {
     const release = acquireStartLock();
+    // acquireStartLock() returns null only when another __daemon-run currently
+    // holds the O_EXCL lock — a dead holder's lock is reclaimed and retried inside
+    // acquireStartLock, so null means a *live* claimer is mid-claim. Bail rather
+    // than run the read-decide-write unlocked: otherwise two first-start processes
+    // could each see no pid file (before either writes one) and both claim,
+    // running the concurrent JobScheduler this guard exists to prevent.
+    if (!release)
+        return false;
     try {
-        const existing = readDaemonPid();
-        if (existing !== null && existing !== process.pid && isAlive(existing)) {
-            return false; // another live daemon already owns the pid file
+        // resolveLiveDaemonPid() also consults a fresh heartbeat, so a live daemon
+        // whose pid file was lost still blocks a second claim — otherwise a missing
+        // pid file would let this instance start a concurrent JobScheduler and
+        // double-fire every routine.
+        const existing = resolveLiveDaemonPid();
+        if (existing !== null && existing !== process.pid) {
+            return false; // another live daemon already owns the instance
         }
         writeDaemonPid(process.pid);
         return true;
     }
     finally {
-        release?.();
+        release();
     }
 }
 /**

package/dist/lib/devices/resolve-target.d.ts

@@ -9,6 +9,10 @@ export interface ResolvedSshTarget {
     name: string;
     os?: string;
 }
+export interface ResolvedExplicitTargetSet {
+    targets: ResolvedSshTarget[];
+    unresolved: string[];
+}
 /**
  * Resolve a target token to a full {@link DeviceProfile} for `agents ssh`. Same
  * grammar as the fan-out, but returns the whole profile (auth, shell, tailscale
@@ -27,3 +31,5 @@ export declare function resolveDeviceTarget(token: string): Promise<DeviceProfil
  * cross-machine fan-out so they can never diverge onto two routes.
  */
 export declare function resolveExplicitTargets(hosts: string[]): Promise<ResolvedSshTarget[]>;
+/** Resolve explicit tokens while retaining failures for coverage-sensitive callers. */
+export declare function resolveExplicitTargetSet(hosts: string[]): Promise<ResolvedExplicitTargetSet>;

package/dist/lib/devices/resolve-target.js

@@ -96,14 +96,20 @@ export async function resolveDeviceTarget(token) {
  * cross-machine fan-out so they can never diverge onto two routes.
  */
 export async function resolveExplicitTargets(hosts) {
-    const out = [];
+    return (await resolveExplicitTargetSet(hosts)).targets;
+}
+/** Resolve explicit tokens while retaining failures for coverage-sensitive callers. */
+export async function resolveExplicitTargetSet(hosts) {
+    const targets = [];
+    const unresolved = [];
     for (const h of hosts) {
         const resolved = await toResolvedTarget(h);
         if (!resolved) {
             process.stderr.write(chalk.gray(`  ${h}: not a resolvable ssh target — skipped\n`));
+            unresolved.push(h);
             continue;
         }
-        out.push(resolved);
+        targets.push(resolved);
     }
-    return out;
+    return { targets, unresolved };
 }

package/dist/lib/exec.js

@@ -13,6 +13,7 @@ import { AGENTS } from './agents.js';
 import { parseTimeout } from './routines.js';
 import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
+import { isTierToken, resolveTier } from './model-tiers.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
@@ -681,10 +682,24 @@ export function buildExecCommand(options) {
             cmd[0] = realBinary && fs.existsSync(realBinary) ? realBinary : versionedName;
         }
     }
+    // Resolve the model up front so the reasoning-flag block can honor a cost tier
+    // that maps to reasoning effort on a single-model harness (e.g. Grok, where the
+    // tier IS the effort dial). `modelVersion` is null when no version resolves;
+    // `tierModel` is the concrete model a tier resolved to (null => drop the flag).
+    const effectiveModel = options.model
+        ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined);
+    const modelVersion = effectiveModel && template.modelFlag
+        ? (options.version || resolveVersion(options.agent, options.cwd || process.cwd()))
+        : null;
+    const tierResolved = effectiveModel && modelVersion && isTierToken(effectiveModel)
+        ? resolveTier(options.agent, modelVersion, effectiveModel)
+        : null;
+    // An explicit --effort wins; otherwise a single-model tier's effort applies.
+    const effortLevel = options.effort !== 'auto' ? options.effort : (tierResolved?.effort ?? options.effort);
     // Add reasoning effort flags (before mode flags for codex -c positioning)
     // For codex, -c must come before 'exec' subcommand, so we insert at position 1
-    if (options.effort !== 'auto') {
-        const reasoningFlags = buildReasoningFlags(options.agent, options.effort);
+    if (effortLevel !== 'auto') {
+        const reasoningFlags = buildReasoningFlags(options.agent, effortLevel);
         if (reasoningFlags.length > 0) {
             if (options.agent === 'codex') {
                 // Insert after 'codex' (or 'codex@version') but before 'exec'
@@ -803,20 +818,36 @@ export function buildExecCommand(options) {
     // carry that setting, so without this it silently defaults to gpt-5.3-codex,
     // which a ChatGPT-tier account can't use (HTTP 400). Forwarding keeps the
     // user's default model setup for both `agents run` and `agents teams`.
-    const effectiveModel = options.model
-        ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined);
     if (effectiveModel && template.modelFlag) {
-        const effectiveVersion = options.version || resolveVersion(options.agent, options.cwd || process.cwd());
-        if (effectiveVersion) {
-            const resolved = resolveModel(options.agent, effectiveVersion, effectiveModel);
+        if (tierResolved) {
+            // Cost tier (cheap|default|best|ultra) -> a concrete model this harness+
+            // version actually ships. Covers `agents run` and `agents teams` (both
+            // funnel here). A null model means nothing resolved -> drop the flag and
+            // let the harness pick its default.
+            if (tierResolved.model) {
+                cmd.push(template.modelFlag, tierResolved.model);
+                if (tierResolved.note)
+                    process.stderr.write(`[agents] --model ${effectiveModel} -> ${tierResolved.model} (${tierResolved.note})\n`);
+            }
+            else {
+                process.stderr.write(`[agents] no model for tier "${effectiveModel}" on ${options.agent}@${modelVersion}; using harness default\n`);
+            }
+        }
+        else if (modelVersion) {
+            const resolved = resolveModel(options.agent, modelVersion, effectiveModel);
             if (resolved.warning) {
                 process.stderr.write(`[agents] ${resolved.warning}\n`);
             }
             cmd.push(template.modelFlag, resolved.forwarded);
         }
-        else {
+        else if (!isTierToken(effectiveModel)) {
             cmd.push(template.modelFlag, effectiveModel);
         }
+        else {
+            // Tier token but no version resolved -> forwarding the literal "best"/etc.
+            // would be rejected by the CLI, so drop the flag (harness default).
+            process.stderr.write(`[agents] cannot resolve tier "${effectiveModel}" without a version; using harness default\n`);
+        }
     }
     // Add JSON output flags if requested
     if (options.json && template.jsonFlags) {

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

@@ -52,6 +52,18 @@ export declare function remoteCdPrefix(remoteCwd?: string, opts?: {
  * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
  */
 export declare function withActorEnv(env?: Record<string, string>): Record<string, string>;
+/**
+ * The shell-export prelude prepended to EVERY remote `agents run` dispatch —
+ * actor provenance plus, for a `run auto` dispatch, the chain-hop guard
+ * (RUN_AUTO_HOST_RESOLVED_ENV): this dispatch already IS the affinity pick, so
+ * the remote CLI must not re-run host affinity and hop to a third host. The
+ * guard MUST be a shell export (landing in the remote CLI's own process.env,
+ * which `runAutoDefaultsToAffinity` reads) — a forwarded `--env` flag would
+ * only reach the spawned agent's env and the remote `run auto` would re-pick.
+ * Shared by the interactive (runInteractiveOnHost) and detached
+ * (launchDetached) paths so both behave identically.
+ */
+export declare function remoteRunShellPrelude(agent: string): string;
 /**
  * Launch a detached login-shell command in its own Unix session/process group.
  *

package/dist/lib/hosts/dispatch.js

@@ -20,6 +20,7 @@ import { followHostTask } from './progress.js';
 import { wrapHostCommandWithCredentials } from './credentials.js';
 import { hostKeyCheckingOpts } from '../devices/known-hosts.js';
 import { toRemotePortable } from '../project-root.js';
+import { RUN_AUTO_KEYWORD, RUN_AUTO_HOST_RESOLVED_ENV } from '../types.js';
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
@@ -95,6 +96,22 @@ export function remoteCdPrefix(remoteCwd, opts = {}) {
 export function withActorEnv(env) {
     return { ...actorEnv(resolveActor()), ...terminalIdEnv(), ...(env ?? {}) };
 }
+/**
+ * The shell-export prelude prepended to EVERY remote `agents run` dispatch —
+ * actor provenance plus, for a `run auto` dispatch, the chain-hop guard
+ * (RUN_AUTO_HOST_RESOLVED_ENV): this dispatch already IS the affinity pick, so
+ * the remote CLI must not re-run host affinity and hop to a third host. The
+ * guard MUST be a shell export (landing in the remote CLI's own process.env,
+ * which `runAutoDefaultsToAffinity` reads) — a forwarded `--env` flag would
+ * only reach the spawned agent's env and the remote `run auto` would re-pick.
+ * Shared by the interactive (runInteractiveOnHost) and detached
+ * (launchDetached) paths so both behave identically.
+ */
+export function remoteRunShellPrelude(agent) {
+    const guard = agent === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {};
+    const exports = posixEnvExports(withActorEnv(guard));
+    return exports ? `${exports}; ` : '';
+}
 /**
  * Forward the launching editor tab's `AGENT_TERMINAL_ID` across the SSH hop.
  *
@@ -233,11 +250,11 @@ async function launchDetached(host, target, opts) {
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
     // Inner command run under a login shell so PATH resolves `agents`. Export the
     // resolved actor provenance first so the detached remote run inherits it
-    // instead of re-resolving from this box's SSH_CONNECTION (RUSH-2028).
+    // instead of re-resolving from this box's SSH_CONNECTION (RUSH-2028); a
+    // `run auto` dispatch also gets the chain-hop guard (remoteRunShellPrelude).
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd, { mirror: opts.mirrorCwd });
-    const actorExports = posixEnvExports(withActorEnv());
-    const prelude = actorExports ? `${actorExports}; ` : '';
+    const prelude = remoteRunShellPrelude(opts.agentLabel);
     let inner = `${prelude}${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
     if (opts.copyCreds) {
         inner = wrapHostCommandWithCredentials(inner, opts.copyCreds);
@@ -432,9 +449,9 @@ export async function runInteractiveOnHost(host, opts) {
     const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd, { mirror: opts.mirrorCwd });
     // Forward actor provenance so the interactive remote run inherits it rather
-    // than re-resolving from this box's SSH_CONNECTION (RUSH-2028).
-    const actorExports = posixEnvExports(withActorEnv());
-    const prelude = actorExports ? `${actorExports}; ` : '';
+    // than re-resolving from this box's SSH_CONNECTION (RUSH-2028); a `run auto`
+    // dispatch also gets the chain-hop guard (remoteRunShellPrelude).
+    const prelude = remoteRunShellPrelude(opts.agent);
     let remoteCmd = `${prelude}${cwd}${invocation}`;
     if (opts.copyCreds) {
         remoteCmd = wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds);

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

@@ -2,6 +2,10 @@ import { type Host } from './types.js';
 /** ssh's connection-layer failure code — the signal that the link dropped rather
  *  than the remote command exiting on its own. Mirrors ssh-exec.ts `sshStream`. */
 export declare const SSH_CONN_FAILURE = 255;
+/** What a would-be-255 remote-origin exit code is remapped to by
+ *  {@link wrapRemoteExitCode} — see the file header. Never produced by the ssh
+ *  transport itself, so it can never be confused with {@link SSH_CONN_FAILURE}. */
+export declare const REMOTE_EXIT_255_REMAPPED = 254;
 /** Consecutive 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
@@ -46,6 +50,40 @@ export declare function reconnectStep(state: ReconnectState, outcome: ReconnectO
 export declare function reconnectNotice(sessionId: string, host: string, attempt: number, waitMs: number): string;
 /** Notice shown once the retry budget is spent. */
 export declare function exhaustedNotice(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
+ *  {@link wrapRemoteExitCode}). Distinct from {@link exhaustedNotice}, which is
+ *  only for a genuinely spent retry budget. */
+export declare function remoteExitNotice(sessionId: string, host: string): string;
+/**
+ * Wrap `cmd` in `bash -lc` (the login-shell pattern `buildRemoteAgentsInvocation`
+ * in remote-cmd.ts uses for its own POSIX callers — see its doc comment for why
+ * a login shell at all; the sibling interactive dispatch in dispatch.ts sends a
+ * bare `agents …` with no shell wrapper, so this is a NEW login-shell hop on the
+ * reattach path specifically, not something already universal here) with a
+ * trailing exit-code remap: whatever `cmd` itself exits with, a 255 becomes
+ * {@link REMOTE_EXIT_255_REMAPPED} before the wrapper exits — see the file
+ * header for why. Every other code (0, 1, …) passes through unchanged. This
+ * carries no PATH bootstrap of its own — `ensureHostReady`/`readyProbe` already
+ * gates every `--host` dispatch on `bash -lc 'agents --version'` succeeding
+ * before a run is attempted at all, so the peer's login shell resolving `agents`
+ * is an established precondition here too. Pure string-building, so it is
+ * unit-tested without SSH (and, since the constructed script is ordinary POSIX,
+ * also exercised by actually running it through a real shell in the test — no
+ * mock needed).
+ */
+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.
+ */
+export declare function reattachRemoteCommand(sessionId: string): string;
 /**
  * Re-attach the live remote tmux pane for `sessionId` by driving the peer's own
  * `agents sessions focus`. A fast, un-multiplexed preflight probe (`ssh … true`)

package/dist/lib/hosts/reconnect.js

@@ -28,12 +28,50 @@
  * The retry policy is a pure state machine (`reconnectStep`) so it is unit-tested
  * without touching SSH; the loop (`reconnectInteractiveSession`) only adds the real
  * preflight + `sshStream` re-attach and the wait.
+ *
+ * **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.
+ *
+ * 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).
+ *
+ * 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.
  */
 import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
 import { 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;
+/** What a would-be-255 remote-origin exit code is remapped to by
+ *  {@link wrapRemoteExitCode} — see the file header. Never produced by the ssh
+ *  transport itself, so it can never be confused with {@link SSH_CONN_FAILURE}. */
+export 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
@@ -77,6 +115,50 @@ export function reconnectNotice(sessionId, host, attempt, waitMs) {
 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`;
 }
+/** Notice shown when a reattach stops on a remapped remote-side exit
+ *  ({@link REMOTE_EXIT_255_REMAPPED} — a would-be-255 the remote command decided
+ *  on for its own reasons, not the ssh transport dropping; see
+ *  {@link wrapRemoteExitCode}). Distinct from {@link exhaustedNotice}, which is
+ *  only for a genuinely spent retry budget. */
+export 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`;
+}
+/**
+ * Wrap `cmd` in `bash -lc` (the login-shell pattern `buildRemoteAgentsInvocation`
+ * in remote-cmd.ts uses for its own POSIX callers — see its doc comment for why
+ * a login shell at all; the sibling interactive dispatch in dispatch.ts sends a
+ * bare `agents …` with no shell wrapper, so this is a NEW login-shell hop on the
+ * reattach path specifically, not something already universal here) with a
+ * trailing exit-code remap: whatever `cmd` itself exits with, a 255 becomes
+ * {@link REMOTE_EXIT_255_REMAPPED} before the wrapper exits — see the file
+ * header for why. Every other code (0, 1, …) passes through unchanged. This
+ * carries no PATH bootstrap of its own — `ensureHostReady`/`readyProbe` already
+ * gates every `--host` dispatch on `bash -lc 'agents --version'` succeeding
+ * before a run is attempted at all, so the peer's login shell resolving `agents`
+ * is an established precondition here too. Pure string-building, so it is
+ * unit-tested without SSH (and, since the constructed script is ordinary POSIX,
+ * also exercised by actually running it through a real shell in the test — no
+ * mock needed).
+ */
+export function wrapRemoteExitCode(cmd) {
+    const guarded = `${cmd}; rc=$?; [ "$rc" = "${SSH_CONN_FAILURE}" ] && rc=${REMOTE_EXIT_255_REMAPPED}; exit "$rc"`;
+    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.
+ */
+export function reattachRemoteCommand(sessionId) {
+    const inner = ['agents', 'sessions', 'focus', sessionId, '--local', '--attach-only']
+        .map(shellQuote)
+        .join(' ');
+    return wrapRemoteExitCode(inner);
+}
 /**
  * Re-attach the live remote tmux pane for `sessionId` by driving the peer's own
  * `agents sessions focus`. A fast, un-multiplexed preflight probe (`ssh … true`)
@@ -94,10 +176,7 @@ export function reattachRemoteSession(host, sessionId) {
     const probe = sshExec(target, 'true', { multiplex: false });
     if (probe.code !== 0)
         return { code: SSH_CONN_FAILURE, connected: false };
-    const remoteCmd = ['agents', 'sessions', 'focus', sessionId, '--local', '--attach-only']
-        .map(shellQuote)
-        .join(' ');
-    return { code: sshStream(target, remoteCmd, { tty: true }), connected: true };
+    return { code: sshStream(target, reattachRemoteCommand(sessionId), { tty: true }), connected: true };
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
@@ -117,6 +196,8 @@ export async function reconnectInteractiveSession(opts) {
         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)
+                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/run-target.js

@@ -55,7 +55,16 @@ export async function resolveHostRunTarget(name, opts = {}) {
 }
 /** Resolve the id the remote host will adopt for a fresh Claude session. */
 export function resolveHostSessionId(agent, resume, sessionId) {
-    return agent === 'claude' && !resume ? sessionId ?? randomUUID() : undefined;
+    if (resume)
+        return undefined;
+    if (agent === 'claude')
+        return sessionId ?? randomUUID();
+    // `run auto`: the harness is picked on the REMOTE. Forward an explicit id so
+    // a claude pick adopts it — but never mint one: minting would suppress the
+    // --emit-session-id marker a non-claude pick needs to register its session.
+    if (agent === 'auto')
+        return sessionId;
+    return undefined;
 }
 /**
  * Dispatch a headless prompt run onto a resolved host, then relate the run's
@@ -77,7 +86,10 @@ export async function dispatchPromptToHost(host, opts) {
     // Ask the remote to print its resolved id whenever we did NOT force one (every
     // non-Claude agent, and Claude-on-resume where the id is already known). No-op
     // when the run isn't followed — nothing tails the log to catch the marker.
-    const emitSessionId = !forcedSessionId && !opts.resume && opts.follow !== false;
+    // `run auto` with an explicit --session-id is the exception: the id is only
+    // ADOPTED when the remote picks claude, so a non-claude pick must still emit
+    // the marker for its own coined id.
+    const emitSessionId = (!forcedSessionId || opts.agent === 'auto') && !opts.resume && opts.follow !== false;
     const result = await dispatchToHost(host, {
         agent: opts.agent,
         prompt: opts.prompt,

package/dist/lib/model-tiers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cost tiers for model selection: cheap / default / best / ultra.
+ *
+ * An orchestrating agent picks a teammate's model by a stable, cost-first tier
+ * instead of a concrete id that churns per release and varies per harness. A
+ * tier resolves, per (harness, installed version), to a model that version
+ * actually ships — so `--model cheap|default|best|ultra` works on `agents run`
+ * and `agents teams add` alike, funnelling through `resolveModel()`.
+ *
+ * Ranking signal, in priority (see apps/cli/docs — model ranking mechanisms):
+ *   1. Provider-declared lineup — the catalog's own family names / descriptions
+ *      (opus/sonnet/haiku/fable; Codex "frontier / balanced / fast"). Most
+ *      drift-proof: the provider tells us its own ranking.
+ *   2. Per-token price (prices.json) — cross-check + the $/Mtok display + budget.
+ *   3. Size-token heuristic (nano|mini|lite|flash cheaper; pro|max|opus dearer).
+ *   4. Reasoning effort for single-model harnesses (Grok) — tiers steer --effort.
+ *
+ * The mechanism differs per provider and drifts across versions, so tiers always
+ * resolve against the installed version's own catalog.
+ */
+import type { AgentId } from './types.js';
+import { type ModelInfo } from './models.js';
+/** The four cross-harness cost tiers, cheapest -> most capable. */
+export declare const MODEL_TIERS: readonly ["cheap", "default", "best", "ultra"];
+export type ModelTier = (typeof MODEL_TIERS)[number];
+/** True if `s` is one of the four tier tokens (not a concrete model id). */
+export declare function isTierToken(s: string | undefined | null): s is ModelTier;
+/** How a single tier resolved for a given (agent, version). */
+export interface TierResolution {
+    tier: ModelTier;
+    /** Concrete model id to forward, or null when nothing resolves (fail-safe). */
+    model: string | null;
+    /** Reasoning effort to forward, for single-model harnesses where the tier is effort, not model. */
+    effort?: string;
+    /** Set when this tier has no rung of its own: the lower tier whose model it borrowed. */
+    clampedFrom?: ModelTier;
+    /** Human note (e.g. why it clamped, or that it is a curated/subscription mapping). */
+    note?: string;
+}
+/**
+ * Resolve all four tiers for an (agent, version). The map is what `agents models`
+ * prints and what `resolveTier` indexes into.
+ */
+export declare function resolveTierMap(agent: AgentId, version: string): Record<ModelTier, TierResolution>;
+/**
+ * Map a harness's catalog models onto the four tiers. Pure (no catalog lookup)
+ * so it is directly testable with synthetic inputs. Ranks the models, collapses
+ * variants, buckets onto cheap/default/best/ultra, and clamps absent tiers down
+ * to the nearest lower one. A single-model harness maps the tiers to reasoning
+ * effort instead of models.
+ */
+export declare function tierizeModels(agent: AgentId, models: ModelInfo[]): Record<ModelTier, TierResolution>;
+/** Resolve one tier for an (agent, version). Null model => caller drops the flag. */
+export declare function resolveTier(agent: AgentId, version: string, tier: ModelTier): TierResolution;