@phnx-labs/agents-cli 1.22.25 → 1.22.27

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`
@@ -117,7 +150,11 @@ export function sshExec(target, remoteCmd, opts = {}) {
         stdio: ['pipe', 'pipe', 'pipe'],
         windowsHide: true,
     });
-    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
+    // Node's spawnSync with a `timeout` option kills the child via SIGTERM and sets
+    // res.signal (e.g. 'SIGTERM') — it does NOT set res.error.code = 'ETIMEDOUT'.
+    // Check both so the detection fires whether the timeout is signalled or errored.
+    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT') ||
+        (!!opts.timeoutMs && res.signal !== null);
     return {
         code: typeof res.status === 'number' ? res.status : null,
         stdout: res.stdout ?? '',
@@ -206,7 +243,9 @@ export function sshExecRaw(target, remoteCmd, opts = {}) {
         stdio: ['pipe', 'pipe', 'pipe'],
         windowsHide: true,
     });
-    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
+    // Same fix as sshExec: spawnSync sets res.signal, not error.code = 'ETIMEDOUT'.
+    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT') ||
+        (!!opts.timeoutMs && res.signal !== null);
     return {
         code: typeof res.status === 'number' ? res.status : null,
         stdout: res.stdout ?? Buffer.alloc(0),
@@ -286,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

@@ -47,6 +47,7 @@ export declare const loadMonitors: ModuleLoader;
 export declare const loadProjects: ModuleLoader;
 export declare const loadRun: ModuleLoader;
 export declare const loadResume: ModuleLoader;
+export declare const loadReconnect: ModuleLoader;
 export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadSet: ModuleLoader;
@@ -75,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

@@ -25,6 +25,7 @@ export const loadMonitors = async () => (await import('../../commands/monitors.j
 export const loadProjects = async () => (await import('../../commands/projects.js')).registerProjectsCommands;
 export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
 export const loadResume = async () => (await import('../../commands/resume.js')).registerResumeCommand;
+export const loadReconnect = async () => (await import('../../commands/reconnect.js')).registerReconnectCommand;
 export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
 export const loadSet = async () => (await import('../../commands/set.js')).registerSetCommand;
@@ -53,6 +54,8 @@ 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;
 export const loadBudget = async () => (await import('../../commands/budget.js')).registerBudgetCommand;
@@ -98,6 +101,7 @@ export const loadHumans = async () => (await import('../../commands/humans.js'))
 export const LAZY_COMMAND_NAMES = new Set([
     'sessions',
     'resume',
+    'reconnect',
     'roster',
     'teams',
     'cloud',
@@ -156,6 +160,7 @@ export const COMMAND_LOADERS = {
     projects: [loadProjects],
     run: [loadRun],
     resume: [loadResume],
+    reconnect: [loadReconnect],
     fork: [loadFork],
     defaults: [loadDefaults],
     set: [loadSet],
@@ -187,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/agents.d.ts

@@ -1,5 +1,6 @@
 import { captureProcessStartTime } from '../platform/index.js';
 import { AgentType } from './parsers.js';
+import { NoViableDeviceError } from './scheduler.js';
 /**
  * Compute the Lowest Common Ancestor (LCA) of multiple file paths.
  * Returns the deepest common directory shared by all paths.
@@ -405,6 +406,18 @@ export declare class AgentManager {
      * teammate schedules identically no matter how it was fired.
      */
     private maybeSchedulePlacement;
+    /** Human label of a teammate's agent for the placement fail-loud message. */
+    private placementAgentLabel;
+    /**
+     * Pre-flight the team pool at `teams start` (RUSH-2002): probe the pool and
+     * confirm each distinct agent among the pending, unpinned, pooled teammates
+     * has at least one viable device. Returns the first {@link NoViableDeviceError}
+     * so the command can fail loud BEFORE launching a wave, rather than silently
+     * leaving teammates stranded pending. A poolless team (no `--devices`) or a
+     * probe that could not gather positive evidence returns null — fail-loud fires
+     * only on proof that no device can run the agent, never on a probe miss.
+     */
+    preflightPlacement(taskName: string): Promise<NoViableDeviceError | null>;
     /**
      * One-ssh-per-host batched liveness/exit pre-pass for a team's remote teammates.
      * The supervisor calls this each wave BEFORE listByTask() so the per-teammate

package/dist/lib/teams/agents.js

@@ -34,7 +34,8 @@ import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { pullRemoteLogDelta, REMOTE_MIRROR_MAX_BYTES } from '../hosts/progress.js';
 import { createRemoteWorktree, ensureRemoteRepo } from './remoteWorktree.js';
 import { getTeam } from './registry.js';
-import { resolvePlacement, cappedDevices } from './scheduler.js';
+import { resolvePlacement, classifyExclusions, NoViableDeviceError } from './scheduler.js';
+import { probePoolSignals } from './placement-probe.js';
 import { readMaxConcurrentCaps } from '../device-config.js';
 import chalk from 'chalk';
 let lastMemoryWarnAt = 0;
@@ -1756,7 +1757,7 @@ export class AgentManager {
      * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
      * teammate schedules identically no matter how it was fired.
      */
-    async maybeSchedulePlacement(agent, taskName) {
+    async maybeSchedulePlacement(agent, taskName, opts = {}) {
         if (agent.hostName || agent.cloudProvider)
             return;
         const teamMeta = await getTeam(taskName);
@@ -1765,15 +1766,79 @@ export class AgentManager {
         const roster = await this.listByTask(taskName);
         const pool = teamMeta.devices ?? [];
         const maxConcurrent = pool.length > 1 ? readMaxConcurrentCaps(pool) : undefined;
-        if (maxConcurrent) {
-            for (const c of cappedDevices(pool, roster, maxConcurrent)) {
-                console.error(chalk.dim(`[placement] '${c.device}' excluded from auto-pick — at its agents.max-concurrent cap (${c.running}/${c.cap} running)`));
+        // On the start path (opts.probe), gather live signals so the pick is health-,
+        // harness-, and load-aware (RUSH-2002); the add path stays the cap-only
+        // roster count so `teams add` never blocks on an SSH fan-out. Cached per
+        // (pool, agent), so a wave placing many teammates probes the pool once.
+        const signals = opts.probe && pool.length > 0
+            ? await probePoolSignals(pool, agent.agentType, { now: Date.now() })
+            : undefined;
+        const placeOpts = {
+            maxConcurrent,
+            signals,
+            agentLabel: this.placementAgentLabel(agent),
+        };
+        if (signals) {
+            for (const e of classifyExclusions(pool, roster, placeOpts).excluded) {
+                const why = e.reason === 'capped'
+                    ? `at its agents.max-concurrent cap (${e.detail} running)`
+                    : e.reason === 'not-installed'
+                        ? `does not have ${this.placementAgentLabel(agent)} installed`
+                        : e.reason;
+                console.error(chalk.dim(`[placement] '${e.device}' excluded from auto-pick — ${why}`));
             }
         }
-        const { device } = resolvePlacement(teamMeta, null, roster, { maxConcurrent });
+        const { device } = resolvePlacement(teamMeta, null, roster, placeOpts);
         if (device)
             await this.resolveScheduledPlacement(agent, device, taskName);
     }
+    /** Human label of a teammate's agent for the placement fail-loud message. */
+    placementAgentLabel(agent) {
+        return agent.version ? `${agent.agentType}@${agent.version}` : String(agent.agentType);
+    }
+    /**
+     * Pre-flight the team pool at `teams start` (RUSH-2002): probe the pool and
+     * confirm each distinct agent among the pending, unpinned, pooled teammates
+     * has at least one viable device. Returns the first {@link NoViableDeviceError}
+     * so the command can fail loud BEFORE launching a wave, rather than silently
+     * leaving teammates stranded pending. A poolless team (no `--devices`) or a
+     * probe that could not gather positive evidence returns null — fail-loud fires
+     * only on proof that no device can run the agent, never on a probe miss.
+     */
+    async preflightPlacement(taskName) {
+        await this.initialize();
+        const teamMeta = await getTeam(taskName);
+        const pool = teamMeta?.devices ?? [];
+        if (!teamMeta || pool.length === 0)
+            return null;
+        const roster = await this.listByTask(taskName);
+        const pending = roster.filter((a) => a.status === AgentStatus.PENDING && !a.hostName && !a.cloudProvider);
+        if (pending.length === 0)
+            return null;
+        const maxConcurrent = pool.length > 1 ? readMaxConcurrentCaps(pool) : undefined;
+        // One representative teammate per distinct agent type — the signal + gate is
+        // per harness, not per teammate.
+        const byAgent = new Map();
+        for (const a of pending)
+            if (!byAgent.has(a.agentType))
+                byAgent.set(a.agentType, a);
+        for (const [, rep] of byAgent) {
+            const signals = await probePoolSignals(pool, rep.agentType, { now: Date.now() });
+            try {
+                resolvePlacement(teamMeta, null, roster, {
+                    maxConcurrent,
+                    signals,
+                    agentLabel: this.placementAgentLabel(rep),
+                });
+            }
+            catch (err) {
+                if (err instanceof NoViableDeviceError)
+                    return err;
+                throw err;
+            }
+        }
+        return null;
+    }
     /**
      * One-ssh-per-host batched liveness/exit pre-pass for a team's remote teammates.
      * The supervisor calls this each wave BEFORE listByTask() so the per-teammate
@@ -1866,9 +1931,12 @@ export class AgentManager {
             // immediate-add and staged paths agree. A null pick keeps hostName null →
             // local spawn, unchanged. Cloud teammates never schedule.
             try {
-                await this.maybeSchedulePlacement(agent, taskName);
+                await this.maybeSchedulePlacement(agent, taskName, { probe: true });
             }
             catch (err) {
+                // A NoViableDeviceError means the pool cannot host this teammate right
+                // now — leave it PENDING (never a silent local fallback) and surface the
+                // reason; a transient device loss is retried next wave.
                 console.error(`Could not schedule ${agent.agentId} onto the team pool:`, err);
                 continue;
             }

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

@@ -0,0 +1,21 @@
+import { type AgentType } from './agents.js';
+import type { DevicePlacementSignal } from './scheduler.js';
+/** Per-remote readiness probe budget — matches the health probe's short window
+ * (`agents view` on a warm box is sub-second; a wedged one degrades to unknown). */
+export declare const READY_PROBE_TIMEOUT_MS = 8000;
+/** How long a probed pool snapshot is reused within a `teams start` wave. Short
+ * enough that a device coming online / going overloaded is seen next wave, long
+ * enough that placing a wave of teammates does not re-fan-out per teammate. */
+export declare const SIGNAL_TTL_MS = 15000;
+/** Clear the probe cache — for tests and after a device-registry change. */
+export declare function clearPlacementSignalCache(): void;
+/**
+ * Probe every device in the team pool and return a name→signal map for the pure
+ * placement pick. Devices with no data at all are omitted (the pick then neither
+ * excludes nor prefers them). Never throws — a probe failure degrades to a
+ * missing/partial signal.
+ */
+export declare function probePoolSignals(pool: string[], agent?: AgentType, opts?: {
+    force?: boolean;
+    now?: number;
+}): Promise<Map<string, DevicePlacementSignal>>;

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

@@ -0,0 +1,135 @@
+/**
+ * Live pool probing for the teams placement scheduler (RUSH-2002).
+ *
+ * Gathers one {@link DevicePlacementSignal} per pool device so the pure pick in
+ * {@link ./scheduler} can filter unreachable / overloaded / not-installed
+ * devices and rank the rest. Two concerns, both best-effort:
+ *
+ *   - reachability + headroom + load  ← {@link probeFleetStats} (one parallel
+ *     SSH fan-out over the pool; the local box is measured directly).
+ *   - 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-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. 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, 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';
+/** Per-remote readiness probe budget — matches the health probe's short window
+ * (`agents view` on a warm box is sub-second; a wedged one degrades to unknown). */
+export const READY_PROBE_TIMEOUT_MS = 8_000;
+/** How long a probed pool snapshot is reused within a `teams start` wave. Short
+ * enough that a device coming online / going overloaded is seen next wave, long
+ * enough that placing a wave of teammates does not re-fan-out per teammate. */
+export const SIGNAL_TTL_MS = 15_000;
+const cache = new Map();
+function cacheKey(pool, agent) {
+    return `${agent ?? 'any-agent'}::${[...pool].map(normalizeHost).sort().join(',')}`;
+}
+/** Clear the probe cache — for tests and after a device-registry change. */
+export function clearPlacementSignalCache() {
+    cache.clear();
+}
+/**
+ * Whether the requested agent is installed on a REMOTE device, via one SSH
+ * readiness probe. `undefined` when the probe could not answer (ssh/login
+ * 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 probeRemoteReadiness(device, agent) {
+    let args;
+    let env;
+    try {
+        const shim = writeAskpassShim();
+        const cmd = buildReadyProbeCommand(device.shell === 'powershell' ? 'windows' : undefined);
+        // agentOnly: a read-only probe must never force a foreground Touch ID sheet
+        // on a password-auth device (mirrors probeDeviceStats in devices/health).
+        ({ args, env } = buildSshInvocation(device, [cmd], shim, {}, { agentOnly: true }));
+    }
+    catch {
+        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({ installed: undefined, signedIn: undefined });
+            const probe = parseReadyProbe(stdout);
+            if (!probe.reachable)
+                return resolve({ installed: undefined, signedIn: undefined });
+            if (!probe.version)
+                return resolve({ installed: false, signedIn: false });
+            const installed = viewHasAgent(probe.view, agent);
+            resolve({ installed, signedIn: installed ? viewAgentSignedIn(probe.view, agent) : false });
+        });
+    });
+}
+/**
+ * Probe every device in the team pool and return a name→signal map for the pure
+ * placement pick. Devices with no data at all are omitted (the pick then neither
+ * excludes nor prefers them). Never throws — a probe failure degrades to a
+ * missing/partial signal.
+ */
+export async function probePoolSignals(pool, agent, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const key = cacheKey(pool, agent);
+    const cached = cache.get(key);
+    if (!opts.force && cached && now - cached.at < SIGNAL_TTL_MS)
+        return cached.signals;
+    const reg = loadDevicesSync();
+    const self = normalizeHost(localMachineId());
+    const lookup = (name) => reg[name] ?? reg[normalizeHost(name)];
+    const profiles = [];
+    const seen = new Set();
+    for (const name of pool) {
+        const d = lookup(name);
+        if (d && !seen.has(d.name)) {
+            profiles.push(d);
+            seen.add(d.name);
+        }
+    }
+    const selfProfile = profiles.find((d) => normalizeHost(d.name) === self);
+    const stats = await probeFleetStats(profiles, { selfName: selfProfile?.name });
+    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);
+        const s = d ? stats.get(d.name) : undefined;
+        const inst = d ? installed.get(d.name) : undefined;
+        if (!s && !inst)
+            continue; // fully unknown device — leave it out of the map
+        signals.set(name, {
+            reachable: s?.reachable,
+            headroom: s ? headroom(s) : undefined,
+            loadPercent: s?.loadPercent,
+            memPercent: s?.memPercent,
+            installed: inst?.installed,
+            signedIn: inst?.signedIn,
+        });
+    }
+    cache.set(key, { at: now, signals });
+    return signals;
+}