@phnx-labs/agents-cli 1.21.2 → 1.22.0

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

@@ -3,6 +3,8 @@ import { type AppInfo } from '../../commands/computer-actions.js';
 import type { VerbDispatcher } from './loop.js';
 declare function rpcMethodFor(verb: string): string;
 declare function toRpcParams(verb: string, input: Record<string, unknown>, pid?: number): Record<string, unknown>;
-export declare function makeVerbDispatcher(client: ComputerClient): VerbDispatcher;
+export declare function makeVerbDispatcher(client: ComputerClient, context?: {
+    host?: string;
+}): VerbDispatcher;
 export { rpcMethodFor, toRpcParams };
 export type { AppInfo };

package/dist/lib/computer/dispatch.js

@@ -5,7 +5,7 @@
 // it names the same RPC methods the explicit `agents computer <verb>` commands
 // call, so the external-agent verb surface is untouched. The daemon stays the
 // single authority on permissions and targeting.
-import { resolveTargetPidDecision } from '../../commands/computer-actions.js';
+import { resolveTargetPidDecision, emitComputerAction } from '../../commands/computer-actions.js';
 // CLI verb -> daemon RPC method. Only the rename cases need listing; the rest
 // pass through by name.
 const RPC_METHOD = {
@@ -102,7 +102,14 @@ function toRpcParams(verb, input, pid) {
 // Build a dispatcher bound to a live client. Every call is a single daemon
 // round-trip; errors are returned (never thrown) so the loop can feed them
 // back to the model as a tool_result.
-export function makeVerbDispatcher(client) {
+//
+// `computer run`'s embedded model loop drives every verb (click, type,
+// screenshot, ...) through THIS single seam rather than the explicit
+// `agents computer <verb>` commands in computer-actions.ts, so it must emit
+// the same `computer.action` event those commands emit — otherwise a session
+// that only used the loop reads back usedComputer=false even though it drove
+// real actions (reviewer-flagged regression on #1864).
+export function makeVerbDispatcher(client, context = {}) {
     return async (call) => {
         const verb = call.name;
         const input = call.input ?? {};
@@ -118,6 +125,7 @@ export function makeVerbDispatcher(client) {
         const res = await client.call(method, params);
         if (res.error)
             return { ok: false, error: `${res.error.code}: ${res.error.message}` };
+        emitComputerAction(verb, pid, { bundle: input.bundle, host: context.host });
         return { ok: true, result: res.result ?? {} };
     };
 }

package/dist/lib/daemon.d.ts

@@ -43,7 +43,11 @@ export declare function writeHeartbeat(pid?: number): void;
 export declare function readHeartbeat(): DaemonHeartbeat | null;
 export declare function removeHeartbeat(): void;
 export declare function isDaemonWedged(): boolean;
-/** Check if the daemon process is alive by sending signal 0 to the stored PID. */
+/**
+ * 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 declare function isDaemonRunning(): boolean;
 /**
  * Single-instance claim for the daemon foreground entrypoint.

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/event-stream.d.ts

@@ -18,6 +18,8 @@ export interface UnifiedQuery {
     eventTypes?: EventType[];
     level?: EventLevel;
     agent?: string;
+    /** Only events stamped with this session id (payload `sessionId`, the provenance floor). */
+    sessionId?: string;
     caller?: string;
     command?: string;
     module?: string;

package/dist/lib/event-stream.js

@@ -29,6 +29,8 @@ function matches(r, q) {
         return false;
     if (q.agent && r.agent !== q.agent)
         return false;
+    if (q.sessionId && r.sessionId !== q.sessionId)
+        return false;
     if (q.caller && r.caller !== q.caller)
         return false;
     if (q.command && r.command !== q.command &&
@@ -51,6 +53,7 @@ export function readUnifiedEvents(q = {}) {
         eventTypes: q.eventTypes,
         level: q.level,
         agent: q.agent,
+        sessionId: q.sessionId,
         caller: q.caller,
         command: q.command,
         module: q.module,

package/dist/lib/events.d.ts

@@ -13,7 +13,7 @@
  */
 import type { ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'computer.action' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 /** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
 export declare const EVENT_TYPES: readonly EventType[];
 /** Runtime guard for an event kind arriving from outside this process. */
@@ -208,6 +208,8 @@ export declare function query(options: {
     eventTypes?: EventType[];
     level?: EventLevel;
     agent?: string;
+    /** Only events stamped with this session id (payload `sessionId`, the provenance floor). */
+    sessionId?: string;
     caller?: string;
     command?: string;
     module?: string;

package/dist/lib/events.js

@@ -84,6 +84,7 @@ const EVENT_TYPE_TABLE = {
     'version.install': true, 'version.switch': true, 'version.remove': true,
     'skill.install': true, 'skill.remove': true,
     'browser.launch': true, 'browser.close': true, 'browser.navigate': true, 'browser.screenshot': true,
+    'computer.action': true,
     'secrets.get': true, 'secrets.unlocked': true, 'secrets.create': true, 'secrets.import': true, 'secrets.export': true, 'secrets.view': true, 'secrets.set': true, 'secrets.delete': true, 'secrets.rename': true,
     'cloud.dispatch': true, 'cloud.complete': true, 'cloud.cancel': true, 'cloud.message': true,
     'teams.create': true, 'teams.add': true, 'teams.start': true, 'teams.complete': true, 'teams.disband': true,
@@ -327,7 +328,6 @@ export function detectCaller(env = process.env, stdoutIsTTY = Boolean(process.st
     }
     return { kind: stdoutIsTTY ? 'terminal' : 'script' };
 }
-// ─── Audit attribution ────────────────────────────────────────────────────────
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
  * Emit a structured event to the append-only audit log.
@@ -729,7 +729,7 @@ export function maybeRotate() {
  * @returns Array of event records
  */
 export function query(options) {
-    const { startDate, endDate = new Date(), eventTypes, level, agent, caller, command, module, limit } = options;
+    const { startDate, endDate = new Date(), eventTypes, level, agent, sessionId, caller, command, module, limit } = options;
     const results = [];
     if (!fs.existsSync(eventsDir()))
         return results;
@@ -774,6 +774,8 @@ export function query(options) {
                     continue;
                 if (agent && record.agent !== agent)
                     continue;
+                if (sessionId && record.sessionId !== sessionId)
+                    continue;
                 if (caller && record.caller !== caller)
                     continue;
                 if (command && record.command !== command &&

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/git.d.ts

@@ -103,6 +103,20 @@ export interface RepoStateSnapshot {
  *  result is stable across git versions and never mutates the tree. Returns null
  *  when the path is not a git worktree. */
 export declare function readRepoState(repoPath: string): RepoStateSnapshot | null;
+/**
+ * The short HEAD sha of the git repo at `repoRoot` (`git -C <repoRoot>
+ * rev-parse --short HEAD`), for provenance — "which commit of this DotAgents
+ * repo was this resource/plugin resolved from". `undefined` when `repoRoot`
+ * isn't a git repo (or has no commits yet), never a throw.
+ *
+ * Deliberately synchronous + resolved once and cached: callers (resources.ts,
+ * plugins.ts) attach this as a lazy getter on the resolved object, so a
+ * consumer that never inspects provenance never pays for the git shell-out —
+ * see {@link ResolvedResource.snapshotSha} / {@link DiscoveredPlugin.snapshotSha}.
+ */
+export declare function resolveSnapshotSha(repoRoot: string): string | undefined;
+/** Test seam: clear the memoized snapshot-sha cache between test cases. */
+export declare function _resetSnapshotShaCacheForTest(): void;
 /**
  * Get the current GitHub username using gh CLI.
  * Returns null if gh is not installed or user is not authenticated.

package/dist/lib/git.js

@@ -371,6 +371,42 @@ export function readRepoState(repoPath) {
     const dirty = porcelain != null && porcelain.length > 0;
     return { branch, head, dirty };
 }
+/** Memoized per repoRoot — a resolveResource()/listResources()/plugin-discovery
+ *  call that touches many resources from the SAME DotAgents repo must not shell
+ *  out to git once per resource. */
+const _snapshotShaCache = new Map();
+/**
+ * The short HEAD sha of the git repo at `repoRoot` (`git -C <repoRoot>
+ * rev-parse --short HEAD`), for provenance — "which commit of this DotAgents
+ * repo was this resource/plugin resolved from". `undefined` when `repoRoot`
+ * isn't a git repo (or has no commits yet), never a throw.
+ *
+ * Deliberately synchronous + resolved once and cached: callers (resources.ts,
+ * plugins.ts) attach this as a lazy getter on the resolved object, so a
+ * consumer that never inspects provenance never pays for the git shell-out —
+ * see {@link ResolvedResource.snapshotSha} / {@link DiscoveredPlugin.snapshotSha}.
+ */
+export function resolveSnapshotSha(repoRoot) {
+    const cached = _snapshotShaCache.get(repoRoot);
+    if (cached !== undefined || _snapshotShaCache.has(repoRoot))
+        return cached;
+    let sha;
+    try {
+        const raw = execFileSync('git', ['-C', repoRoot, 'rev-parse', '--short', 'HEAD'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).toString().trim();
+        sha = raw || undefined;
+    }
+    catch {
+        sha = undefined;
+    }
+    _snapshotShaCache.set(repoRoot, sha);
+    return sha;
+}
+/** Test seam: clear the memoized snapshot-sha cache between test cases. */
+export function _resetSnapshotShaCacheForTest() {
+    _snapshotShaCache.clear();
+}
 /**
  * Get the current GitHub username using gh CLI.
  * Returns null if gh is not installed or user is not authenticated.

package/dist/lib/hooks/profile.js

@@ -12,6 +12,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getLogsDir } from '../state.js';
+import { percentile } from '../percentile.js';
 /**
  * Load every `hook.fire` event from the last `days` daily log files.
  * Lines that aren't JSON or aren't `hook.fire` events are silently skipped —
@@ -53,20 +54,6 @@ export function loadHookFireEvents(days = 7, logsDir = getLogsDir()) {
     }
     return events;
 }
-/** Percentile of a sorted-ascending array. p in [0,100]. Linear interpolation. */
-function percentile(sorted, p) {
-    if (sorted.length === 0)
-        return 0;
-    if (sorted.length === 1)
-        return sorted[0];
-    const rank = (p / 100) * (sorted.length - 1);
-    const lo = Math.floor(rank);
-    const hi = Math.ceil(rank);
-    if (lo === hi)
-        return sorted[lo];
-    const frac = rank - lo;
-    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
-}
 /** Aggregate fire events into a per-hook profile, sorted by p99 desc. */
 export function aggregateHookProfile(events) {
     const byHook = new Map();

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`)