@phnx-labs/agents-cli 1.22.26 → 1.22.27

package/dist/lib/smart-launch.d.ts

@@ -1,11 +1,13 @@
 /**
- * Device affinity for `--device auto` / `--host auto`.
+ * Device placement for `--device auto` / `--host auto`.
  *
- * Picks a host from 14d session usage (launches by machine), weighted sample
- * among online devices. Most-used has highest probability — not a hard lock.
+ * Explicit auto placement probes live fleet health and harness readiness.
+ * Historical affinity remains for generic host resolution callers.
  * Account selection is separate (`--strategy balanced` / rotate.ts).
  */
 import { type AffinityRow } from './session/db.js';
+import { type DevicePlacementSignal } from './teams/scheduler.js';
+import type { AgentType } from './teams/agents.js';
 /** Peakiness of usage weights; >1 amplifies the most-used option. */
 export declare const DEFAULT_AFFINITY_ALPHA = 1.3;
 export interface WeightedCandidate {
@@ -45,6 +47,29 @@ export interface DeviceAffinityPlan {
     deviceCandidates: WeightedCandidate[];
     pickedDeviceKey: string | null;
 }
+/** Live placement plan used by the explicit `--device auto` surface. */
+export interface DeviceAutoPlan {
+    /** null means the local machine won the comparison. */
+    host: string | null;
+    candidates: Array<{
+        key: string;
+        loadPercent?: number;
+        installed?: boolean;
+        signedIn?: boolean;
+    }>;
+    pickedDeviceKey: string;
+}
+/**
+ * Pick the least-loaded healthy device that can run `agent` when the harness is
+ * known. `run auto` omits the agent and ranks the same live health/load signals
+ * without an installed-harness filter. The local machine participates in the
+ * same probe; a fully unusable fleet degrades to local instead of stranding a run.
+ */
+export declare function resolveDeviceAuto(agent?: string, opts?: {
+    eligibleHosts?: string[];
+    localMachine?: string;
+    probe?: (pool: string[], agent?: AgentType) => Promise<Map<string, DevicePlacementSignal>>;
+}): Promise<DeviceAutoPlan>;
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
  */
@@ -81,6 +106,7 @@ export type DeviceAutoApplyResult = {
  * returns `skipped` — never throws; callers must not hard-exit.
  */
 export declare function applyDeviceAutoToOptions(options: DeviceAutoHostOptions, deps?: {
-    resolve?: () => DeviceAffinityPlan;
+    resolve?: () => DeviceAutoPlan | Promise<DeviceAutoPlan>;
+    agent?: string;
     accountPickerRequested?: boolean;
-}): DeviceAutoApplyResult;
+}): Promise<DeviceAutoApplyResult>;

package/dist/lib/smart-launch.js

@@ -1,14 +1,16 @@
 /**
- * Device affinity for `--device auto` / `--host auto`.
+ * Device placement for `--device auto` / `--host auto`.
  *
- * Picks a host from 14d session usage (launches by machine), weighted sample
- * among online devices. Most-used has highest probability — not a hard lock.
+ * Explicit auto placement probes live fleet health and harness readiness.
+ * Historical affinity remains for generic host resolution callers.
  * Account selection is separate (`--strategy balanced` / rotate.ts).
  */
 import { queryAffinityRollup } from './session/db.js';
 import { localMachineId } from './session/origin-machine.js';
 import { loadDevicesSync } from './devices/registry.js';
 import { normalizeHost } from './machine-id.js';
+import { probePoolSignals } from './teams/placement-probe.js';
+import { pickBestDevice } from './teams/scheduler.js';
 /** Peakiness of usage weights; >1 amplifies the most-used option. */
 export const DEFAULT_AFFINITY_ALPHA = 1.3;
 /**
@@ -62,6 +64,39 @@ export function listOnlineDeviceNames(localName = localMachineId()) {
     }
     return [...names];
 }
+/**
+ * Pick the least-loaded healthy device that can run `agent` when the harness is
+ * known. `run auto` omits the agent and ranks the same live health/load signals
+ * without an installed-harness filter. The local machine participates in the
+ * same probe; a fully unusable fleet degrades to local instead of stranding a run.
+ */
+export async function resolveDeviceAuto(agent, opts = {}) {
+    const local = normalizeHost(opts.localMachine ?? localMachineId());
+    const pool = [...new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost))];
+    if (!pool.includes(local))
+        pool.push(local);
+    try {
+        const signals = await (opts.probe ?? probePoolSignals)(pool, agent);
+        const picked = pickBestDevice(pool, [], { signals, agentLabel: agent });
+        return {
+            host: picked === local ? null : picked,
+            pickedDeviceKey: picked,
+            candidates: pool.map((key) => ({
+                key,
+                loadPercent: signals.get(key)?.loadPercent,
+                installed: signals.get(key)?.installed,
+                signedIn: signals.get(key)?.signedIn,
+            })),
+        };
+    }
+    catch {
+        return {
+            host: null,
+            pickedDeviceKey: local,
+            candidates: [{ key: local }],
+        };
+    }
+}
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
  */
@@ -120,7 +155,7 @@ const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
  * Mutates `options` in place. On affinity failure, clears auto slots (local) and
  * returns `skipped` — never throws; callers must not hard-exit.
  */
-export function applyDeviceAutoToOptions(options, deps = {}) {
+export async function applyDeviceAutoToOptions(options, deps = {}) {
     let deprecationSmart = false;
     if (options.smart) {
         const anyHost = HOST_SLOTS.some((k) => typeof options[k] === 'string' && options[k].trim() !== '');
@@ -133,7 +168,8 @@ export function applyDeviceAutoToOptions(options, deps = {}) {
         return { attempted: false, deprecationSmart };
     }
     try {
-        const plan = (deps.resolve ?? (() => resolveDeviceAffinity({})))();
+        const resolve = deps.resolve ?? (() => resolveDeviceAuto(deps.agent));
+        const plan = await resolve();
         const concrete = plan.host; // null = local
         for (const k of HOST_SLOTS) {
             if (isDeviceAuto(options[k])) {
@@ -145,9 +181,9 @@ export function applyDeviceAutoToOptions(options, deps = {}) {
             options.balanced = true;
         }
         const hostLabel = concrete ?? 'local';
-        const deviceHint = plan.deviceCandidates
+        const deviceHint = plan.candidates
             .slice(0, 4)
-            .map((c) => `${c.key}:${c.launches}`)
+            .map((c) => `${c.key}:${c.loadPercent === undefined ? '?' : `${Math.round(c.loadPercent)}%`}`)
             .join(', ');
         const acctNote = accountPickerRequested ? 'accounts=picker' : 'accounts=balanced';
         return {

package/dist/lib/ssh-exec.d.ts

@@ -28,6 +28,31 @@ export declare function shellQuote(s: string): string;
  * long-lived `-N` tunnel can't leave a zombie ssh + socket pinned on the laptop.
  */
 export declare const SSH_OPTS: readonly string[];
+/**
+ * Hard ceiling on the stdout one peer may return before its capture is aborted.
+ * A cross-machine fan-out streams every peer's `agents … --json` into memory in
+ * parallel, so an unbounded buffer means one runaway peer (a corrupt or
+ * pathologically large payload) can exhaust the caller's heap and take the whole
+ * sweep down with it — RUSH-2065 observed ~170MB retained across a single
+ * `--active` gather. 16 MiB is far above any legitimate JSON listing yet small
+ * enough that N peers in flight stay bounded. A peer that overflows is treated as
+ * unreachable rather than trusted with partial output.
+ */
+export declare const REMOTE_STDOUT_MAX_BYTES: number;
+/**
+ * Accumulate SSH stdout as UTF-8 without corrupting a multi-byte code point that
+ * a chunk boundary splits — the streaming `on('data')` callbacks hand us raw
+ * `Buffer`s, and a naive `buf.toString()` per chunk mangles any character the
+ * kernel cut in half. `StringDecoder` holds the trailing partial bytes until the
+ * next chunk completes them.
+ */
+export declare class RemoteUtf8Accumulator {
+    private readonly decoder;
+    private value;
+    write(chunk: Buffer): void;
+    end(): string;
+    current(): string;
+}
 export declare function controlOpts(): string[];
 /**
  * Compose an ssh connection-option prefix.
@@ -128,6 +153,8 @@ export interface SshStreamOptions {
      * interactive credential-copy path (RUSH-1767).
      */
     hostKeyOpts?: string[];
+    /** Additional OpenSSH argv placed before the target (for example `-i <path>`). */
+    extraSshArgs?: string[];
 }
 /**
  * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the

package/dist/lib/ssh-exec.js

@@ -8,6 +8,7 @@
  * canonical definition; `commands/secrets.ts` re-exports it.
  */
 import { spawn, spawnSync } from 'child_process';
+import { StringDecoder } from 'string_decoder';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
@@ -46,6 +47,38 @@ export const SSH_OPTS = [
     '-o', 'ServerAliveInterval=15',
     '-o', 'ServerAliveCountMax=3',
 ];
+/**
+ * Hard ceiling on the stdout one peer may return before its capture is aborted.
+ * A cross-machine fan-out streams every peer's `agents … --json` into memory in
+ * parallel, so an unbounded buffer means one runaway peer (a corrupt or
+ * pathologically large payload) can exhaust the caller's heap and take the whole
+ * sweep down with it — RUSH-2065 observed ~170MB retained across a single
+ * `--active` gather. 16 MiB is far above any legitimate JSON listing yet small
+ * enough that N peers in flight stay bounded. A peer that overflows is treated as
+ * unreachable rather than trusted with partial output.
+ */
+export const REMOTE_STDOUT_MAX_BYTES = 16 * 1024 * 1024;
+/**
+ * Accumulate SSH stdout as UTF-8 without corrupting a multi-byte code point that
+ * a chunk boundary splits — the streaming `on('data')` callbacks hand us raw
+ * `Buffer`s, and a naive `buf.toString()` per chunk mangles any character the
+ * kernel cut in half. `StringDecoder` holds the trailing partial bytes until the
+ * next chunk completes them.
+ */
+export class RemoteUtf8Accumulator {
+    decoder = new StringDecoder('utf8');
+    value = '';
+    write(chunk) {
+        this.value += this.decoder.write(chunk);
+    }
+    end() {
+        this.value += this.decoder.end();
+        return this.value;
+    }
+    current() {
+        return this.value;
+    }
+}
 /**
  * OpenSSH connection-multiplexing options. The first connection to a host opens
  * a control socket; subsequent connections (even from a *separate* `agents`
@@ -292,7 +325,7 @@ export function sshStream(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
     const mux = opts.multiplex === false ? [] : controlOpts();
     const tty = opts.tty ? ['-tt'] : [];
-    const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...tty, target, remoteCmd];
+    const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), ...tty, target, remoteCmd];
     const res = spawnSync('ssh', args, { stdio: 'inherit' });
     if (typeof res.status === 'number')
         return res.status;

package/dist/lib/ssh-tunnel.d.ts

@@ -27,13 +27,14 @@ export interface StartTunnelOptions {
      * of one CDP session and kills it on cleanup.
      */
     detached?: boolean;
+    extraSshArgs?: string[];
 }
 /** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
  *
  * Composes the shared hardened baseline (`SSH_OPTS`) rather than re-listing it,
  * so the tunnel inherits the same options — crucially the keepalive, which lets
  * a dropped `-N` tunnel exit instead of lingering as a zombie on the laptop. */
-export declare function buildTunnelArgs(user: string, host: string, localPort: number, remotePort: number): string[];
+export declare function buildTunnelArgs(user: string, host: string, localPort: number, remotePort: number, extraSshArgs?: string[]): string[];
 /**
  * Spawn `ssh -L localPort:127.0.0.1:remotePort -N user@host`.
  *
@@ -151,7 +152,7 @@ export declare function scpRemotePath(remotePath: string): string;
  * assert the real binary copy path keeps BatchMode and does not route bytes
  * through a PowerShell decoder.
  */
-export declare function buildScpArgs(target: string, remotePath: string, filePath: string): string[];
+export declare function buildScpArgs(target: string, remotePath: string, filePath: string, extraSshArgs?: string[]): string[];
 /**
  * `setup --host`: push the exe, then register + start the LOGON task. Remote
  * PowerShell hops go through `sshExec` (BatchMode key auth — the same hardening

package/dist/lib/ssh-tunnel.js

@@ -28,7 +28,7 @@ import { sshExec, SSH_OPTS, assertValidSshTarget } from './ssh-exec.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
 import { getDevice } from './devices/registry.js';
-import { sshTargetFor } from './devices/connect.js';
+import { deviceIdentityArgs, sshTargetFor } from './devices/connect.js';
 import { hostNameFor } from './devices/ssh-config.js';
 import { getCacheDir } from './state.js';
 import { getCliVersion } from './version.js';
@@ -38,12 +38,13 @@ import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
  * Composes the shared hardened baseline (`SSH_OPTS`) rather than re-listing it,
  * so the tunnel inherits the same options — crucially the keepalive, which lets
  * a dropped `-N` tunnel exit instead of lingering as a zombie on the laptop. */
-export function buildTunnelArgs(user, host, localPort, remotePort) {
+export function buildTunnelArgs(user, host, localPort, remotePort, extraSshArgs = []) {
     return [
         '-L',
         `${localPort}:127.0.0.1:${remotePort}`,
         `${user}@${host}`,
         '-N',
+        ...extraSshArgs,
         ...SSH_OPTS,
     ];
 }
@@ -69,7 +70,7 @@ export function startSSHTunnel(user, host, localPort, remotePort, opts = {}) {
             reject(err);
             return;
         }
-        const args = buildTunnelArgs(user, host, localPort, remotePort);
+        const args = buildTunnelArgs(user, host, localPort, remotePort, opts.extraSshArgs);
         const tunnel = spawn('ssh', args, {
             stdio: opts.detached ? 'ignore' : ['ignore', 'ignore', 'pipe'],
             ...(opts.detached ? backgroundSpawnOptions() : { detached: false, windowsHide: true }),
@@ -360,16 +361,16 @@ export function scpRemotePath(remotePath) {
  * assert the real binary copy path keeps BatchMode and does not route bytes
  * through a PowerShell decoder.
  */
-export function buildScpArgs(target, remotePath, filePath) {
-    return [...SSH_OPTS, filePath, `${target}:${scpRemotePath(remotePath)}`];
+export function buildScpArgs(target, remotePath, filePath, extraSshArgs = []) {
+    return [...extraSshArgs, ...SSH_OPTS, filePath, `${target}:${scpRemotePath(remotePath)}`];
 }
 /**
  * Copy a local file to the remote destination with scp. This is a binary
  * transfer; no base64 transform runs on either side.
  */
-function copyFileOverScp(target, remotePath, filePath, timeoutMs = 600_000) {
+function copyFileOverScp(target, remotePath, filePath, extraSshArgs = [], timeoutMs = 600_000) {
     return new Promise((resolve, reject) => {
-        const child = spawn('scp', buildScpArgs(target, remotePath, filePath), {
+        const child = spawn('scp', buildScpArgs(target, remotePath, filePath, extraSshArgs), {
             stdio: ['ignore', 'ignore', 'pipe'],
         });
         let stderr = '';
@@ -397,11 +398,12 @@ function copyFileOverScp(target, remotePath, filePath, timeoutMs = 600_000) {
  * scp transfer. Throws with the remote stderr on any failure.
  */
 export async function setupRemoteHelper(name) {
-    const { target } = await resolveRemoteDevice(name);
+    const { device, target } = await resolveRemoteDevice(name);
+    const identityArgs = deviceIdentityArgs(device);
     // Local build output, else the checksum-verified GitHub release asset for
     // this CLI version. Throws naming the tag it checked when neither exists.
     const exe = await ensureWinHelperExe();
-    const prep = sshExec(target, encodePowerShell(buildPushScript()), { timeoutMs: 60_000 });
+    const prep = sshExec(target, encodePowerShell(buildPushScript()), { timeoutMs: 60_000, extraSshArgs: identityArgs });
     if (prep.code !== 0) {
         throw new Error(`preparing helper exe path on '${name}' failed (exit ${prep.code ?? 'null'}): ${prep.stderr.trim() || prep.stdout.trim()}`);
     }
@@ -409,12 +411,12 @@ export async function setupRemoteHelper(name) {
     if (!remotePath) {
         throw new Error(`preparing helper exe path on '${name}' did not return a destination path`);
     }
-    const push = await copyFileOverScp(target, remotePath, exe);
+    const push = await copyFileOverScp(target, remotePath, exe, identityArgs);
     if (push.code !== 0) {
         throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim()}`);
     }
     const expectedBytes = fs.statSync(exe).size;
-    const verify = sshExec(target, encodePowerShell(buildVerifyPushScript(remotePath, expectedBytes)), { timeoutMs: 60_000 });
+    const verify = sshExec(target, encodePowerShell(buildVerifyPushScript(remotePath, expectedBytes)), { timeoutMs: 60_000, extraSshArgs: identityArgs });
     if (verify.code !== 0) {
         throw new Error(`verifying helper exe on '${name}' failed (exit ${verify.code ?? 'null'}): ${verify.stderr.trim() || verify.stdout.trim()}`);
     }
@@ -423,7 +425,7 @@ export async function setupRemoteHelper(name) {
     // refuses to start without a token, so a token-less (open-to-any-local-process)
     // daemon can no longer be stood up through the CLI.
     const token = generateToken();
-    const tokWrite = sshExec(target, encodePowerShell(buildWriteTokenScript(token)), { timeoutMs: 60_000 });
+    const tokWrite = sshExec(target, encodePowerShell(buildWriteTokenScript(token)), { timeoutMs: 60_000, extraSshArgs: identityArgs });
     if (tokWrite.code !== 0) {
         throw new Error(`writing helper token on '${name}' failed (exit ${tokWrite.code ?? 'null'}): ${tokWrite.stderr.trim() || tokWrite.stdout.trim()}`);
     }
@@ -434,6 +436,7 @@ export async function setupRemoteHelper(name) {
     // Register + start the LOGON task, pointing it at the token file.
     const reg = sshExec(target, encodePowerShell(buildRegisterTaskScript(REMOTE_HELPER_PORT, REMOTE_TASK_NAME, remoteTokenPath)), {
         timeoutMs: 60_000,
+        extraSshArgs: identityArgs,
     });
     if (reg.code !== 0) {
         throw new Error(`registering scheduled task on '${name}' failed (exit ${reg.code ?? 'null'}): ${reg.stderr.trim() || reg.stdout.trim()}`);
@@ -460,10 +463,13 @@ export function pickFreePort() {
  * the state (and leaves the tunnel running in the background).
  */
 export async function startRemoteTunnel(name) {
-    const { target, user, host } = await resolveRemoteDevice(name);
+    const { device, target, user, host } = await resolveRemoteDevice(name);
     const remotePort = REMOTE_HELPER_PORT;
     const localPort = await pickFreePort();
-    const tunnel = await startSSHTunnel(user, host, localPort, remotePort, { detached: true });
+    const tunnel = await startSSHTunnel(user, host, localPort, remotePort, {
+        detached: true,
+        extraSshArgs: deviceIdentityArgs(device),
+    });
     const tunnelPid = tunnel.pid ?? 0;
     // Verify the daemon answers through the tunnel before we record it. This is
     // the real end-to-end check: tunnel up + daemon listening + RPC round-trips.
@@ -543,8 +549,11 @@ export async function stopRemoteHelper(name) {
     }
     let taskRemoved = false;
     try {
-        const { target } = await resolveRemoteDevice(name);
-        const res = sshExec(target, encodePowerShell(buildUnregisterTaskScript(REMOTE_TASK_NAME)), { timeoutMs: 60_000 });
+        const { device, target } = await resolveRemoteDevice(name);
+        const res = sshExec(target, encodePowerShell(buildUnregisterTaskScript(REMOTE_TASK_NAME)), {
+            timeoutMs: 60_000,
+            extraSshArgs: deviceIdentityArgs(device),
+        });
         taskRemoved = res.code === 0;
     }
     catch {

package/dist/lib/startup/command-registry.d.ts

@@ -76,6 +76,7 @@ export declare const loadUsage: ModuleLoader;
 export declare const loadCost: ModuleLoader;
 export declare const loadInsights: ModuleLoader;
 export declare const loadPerf: ModuleLoader;
+export declare const loadBench: ModuleLoader;
 export declare const loadTrends: ModuleLoader;
 export declare const loadOutput: ModuleLoader;
 export declare const loadBudget: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -54,6 +54,7 @@ export const loadUsage = async () => (await import('../../commands/usage.js')).r
 export const loadCost = async () => (await import('../../commands/cost.js')).registerCostCommand;
 export const loadInsights = async () => (await import('../../commands/insights.js')).registerInsightsCommand;
 export const loadPerf = async () => (await import('../../commands/perf.js')).registerPerfCommand;
+export const loadBench = async () => (await import('../../commands/bench.js')).registerBenchCommand;
 // Thin deprecated alias of `agents insights mix` — no second mix implementation.
 export const loadTrends = async () => (await import('../../commands/trends.js')).registerTrendsCommand;
 export const loadOutput = async () => (await import('../../commands/output.js')).registerOutputCommand;
@@ -191,6 +192,7 @@ export const COMMAND_LOADERS = {
     cost: [loadCost],
     insights: [loadInsights],
     perf: [loadPerf],
+    bench: [loadBench],
     trends: [loadTrends],
     output: [loadOutput],
     budget: [loadBudget],

package/dist/lib/teams/placement-probe.d.ts

@@ -15,7 +15,7 @@ export declare function clearPlacementSignalCache(): void;
  * excludes nor prefers them). Never throws — a probe failure degrades to a
  * missing/partial signal.
  */
-export declare function probePoolSignals(pool: string[], agent: AgentType, opts?: {
+export declare function probePoolSignals(pool: string[], agent?: AgentType, opts?: {
     force?: boolean;
     now?: number;
 }): Promise<Map<string, DevicePlacementSignal>>;

package/dist/lib/teams/placement-probe.js

@@ -7,26 +7,25 @@
  *
  *   - reachability + headroom + load  ← {@link probeFleetStats} (one parallel
  *     SSH fan-out over the pool; the local box is measured directly).
- *   - requested agent installed (+ signed in, locally)  ← a one-shot readiness
+ *   - requested agent installed + signed in (when known) ← a one-shot readiness
  *     probe per remote device ({@link buildReadyProbeCommand} → `agents view`),
  *     the local box via {@link checkCliAvailable}/{@link checkCliSignedIn}.
  *
- * The result is cached briefly per (pool, agent) so a `teams start` wave that
+ * The result is cached briefly per (pool, agent-or-any) so a `teams start` wave that
  * places N teammates probes the pool ONCE, not N times — the roster-count part
  * of the rank stays live (the pure pick recounts the roster each call), only the
  * SSH-measured load/harness snapshot is reused within the TTL.
  *
  * All SSH here is via `execFile` (async, bounded) so the whole pool is probed in
  * parallel; a slow or wedged box degrades to "no signal" instead of blocking the
- * launch. Remote sign-in is deliberately left unknown — sign-in detection is
- * unreliable over SSH (see {@link checkCliSignedIn}); it ranks the local box
- * only, and the install gate (not sign-in) is what drives the fail-loud.
+ * launch. The readiness payload is `agents view --json`, so remote and local
+ * candidates carry the same installed/sign-in verdict.
  */
 import { execFile } from 'child_process';
 import { probeFleetStats, headroom } from '../devices/health.js';
 import { loadDevicesSync } from '../devices/registry.js';
 import { buildSshInvocation, writeAskpassShim } from '../devices/connect.js';
-import { buildReadyProbeCommand, parseReadyProbe, viewHasAgent } from '../hosts/ready.js';
+import { buildReadyProbeCommand, parseReadyProbe, viewAgentSignedIn, viewHasAgent, } from '../hosts/ready.js';
 import { localMachineId } from '../session/origin-machine.js';
 import { normalizeHost } from '../machine-id.js';
 import { checkCliAvailable, checkCliSignedIn } from './agents.js';
@@ -39,7 +38,7 @@ export const READY_PROBE_TIMEOUT_MS = 8_000;
 export const SIGNAL_TTL_MS = 15_000;
 const cache = new Map();
 function cacheKey(pool, agent) {
-    return `${agent}::${[...pool].map(normalizeHost).sort().join(',')}`;
+    return `${agent ?? 'any-agent'}::${[...pool].map(normalizeHost).sort().join(',')}`;
 }
 /** Clear the probe cache — for tests and after a device-registry change. */
 export function clearPlacementSignalCache() {
@@ -51,7 +50,7 @@ export function clearPlacementSignalCache() {
  * failure) — reachability is then left to {@link probeFleetStats}; `false` when
  * the box answered but agents-cli or the agent is absent (a genuine can't-run).
  */
-function probeRemoteInstalled(device, agent) {
+function probeRemoteReadiness(device, agent) {
     let args;
     let env;
     try {
@@ -62,18 +61,19 @@ function probeRemoteInstalled(device, agent) {
         ({ args, env } = buildSshInvocation(device, [cmd], shim, {}, { agentOnly: true }));
     }
     catch {
-        return Promise.resolve(undefined);
+        return Promise.resolve({ installed: undefined, signedIn: undefined });
     }
     return new Promise((resolve) => {
         execFile('ssh', args, { encoding: 'utf-8', env: { ...process.env, ...env }, timeout: READY_PROBE_TIMEOUT_MS }, (err, stdout) => {
             if (err || !stdout)
-                return resolve(undefined);
+                return resolve({ installed: undefined, signedIn: undefined });
             const probe = parseReadyProbe(stdout);
             if (!probe.reachable)
-                return resolve(undefined); // ssh/login issue → unknown
+                return resolve({ installed: undefined, signedIn: undefined });
             if (!probe.version)
-                return resolve(false); // agents-cli missing → cannot run
-            resolve(viewHasAgent(probe.view, agent));
+                return resolve({ installed: false, signedIn: false });
+            const installed = viewHasAgent(probe.view, agent);
+            resolve({ installed, signedIn: installed ? viewAgentSignedIn(probe.view, agent) : false });
         });
     });
 }
@@ -103,17 +103,17 @@ export async function probePoolSignals(pool, agent, opts = {}) {
     }
     const selfProfile = profiles.find((d) => normalizeHost(d.name) === self);
     const stats = await probeFleetStats(profiles, { selfName: selfProfile?.name });
-    const installed = new Map(await Promise.all(profiles.map(async (d) => {
-        const isSelf = normalizeHost(d.name) === self;
-        if (isSelf) {
-            const inst = checkCliAvailable(agent)[0];
-            const signedIn = inst ? await checkCliSignedIn(agent) : undefined;
-            return [d.name, { installed: inst, signedIn }];
-        }
-        // Remote sign-in stays unknown (see the module docblock); the install
-        // gate is what drives the fail-loud.
-        return [d.name, { installed: await probeRemoteInstalled(d, agent), signedIn: undefined }];
-    })));
+    const installed = new Map(agent
+        ? await Promise.all(profiles.map(async (d) => {
+            const isSelf = normalizeHost(d.name) === self;
+            if (isSelf) {
+                const inst = checkCliAvailable(agent)[0];
+                const signedIn = inst ? await checkCliSignedIn(agent) : undefined;
+                return [d.name, { installed: inst, signedIn }];
+            }
+            return [d.name, await probeRemoteReadiness(d, agent)];
+        }))
+        : []);
     const signals = new Map();
     for (const name of pool) {
         const d = lookup(name);

package/dist/lib/tmux/session.d.ts

@@ -179,6 +179,14 @@ export declare const AGENT_HOOK_SCHEMA = 5;
 export declare function agentPaneDiedHook(sessionName: string, agentPane: string): string;
 /** Stamp a session's hook-schema marker to the current version. */
 export declare function markSessionHookSchema(name: string, socket?: string): Promise<void>;
+/**
+ * Decide whether a native resume may attach an existing managed tmux session.
+ * Only a positively resolved, living agent pane is reusable. Metadata-less
+ * legacy sessions and stale metadata resolve their real first pane through
+ * tmux before the decision; a dead or unreadable session is reaped so the
+ * caller can create a fresh wrapper for the resumed harness.
+ */
+export declare function prepareSessionForResume(name: string, socket?: string): Promise<'attach' | 'create'>;
 /**
  * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
  * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:

package/dist/lib/tmux/session.js

@@ -359,6 +359,28 @@ async function lowestPaneId(name, socket) {
         return undefined;
     return ids.reduce((lo, id) => (parseInt(id.slice(1), 10) < parseInt(lo.slice(1), 10) ? id : lo));
 }
+/**
+ * Decide whether a native resume may attach an existing managed tmux session.
+ * Only a positively resolved, living agent pane is reusable. Metadata-less
+ * legacy sessions and stale metadata resolve their real first pane through
+ * tmux before the decision; a dead or unreadable session is reaped so the
+ * caller can create a fresh wrapper for the resumed harness.
+ */
+export async function prepareSessionForResume(name, socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    if (!(await hasSession(name, sock)))
+        return 'create';
+    const recordedPane = readSessionMeta(name)?.pane;
+    const recordedState = recordedPane ? await paneExitStatus(recordedPane, sock) : undefined;
+    const pane = recordedPane && recordedState?.found
+        ? recordedPane
+        : await lowestPaneId(name, sock);
+    const state = pane ? await paneExitStatus(pane, sock) : undefined;
+    if (pane && state?.found && !state.dead)
+        return 'attach';
+    await killSession(name, sock);
+    return 'create';
+}
 /**
  * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
  * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:

package/dist/lib/types.d.ts

@@ -1064,6 +1064,8 @@ export interface HostEntry {
     address?: string;
     /** SSH user — inline hosts only. */
     user?: string;
+    /** Explicit private key inherited from a fleet device profile. */
+    identityFile?: string;
     /** Captured at enroll probe. */
     os?: string;
     /** Free-form capability tags for routing (e.g. ['gpu']). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.26",
+  "version": "1.22.27",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",