@phnx-labs/agents-cli 1.22.26 → 1.22.28

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/staleness/detectors/skills.d.ts

@@ -1,3 +1,5 @@
 import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
+/** Exported for unit tests (RUSH-2320 #2). Production callers: list() below. */
+export declare function skillDirsMatch(src: string, dest: string): boolean;
 export declare const skillsDetectors: Partial<Record<AgentId, ResourceDetector>>;

package/dist/lib/staleness/detectors/skills.js

@@ -9,7 +9,8 @@ import { capableAgents } from '../../capabilities.js';
 import { resolveSkillSource } from '../writers/sources.js';
 import { lazyAgentMap } from '../writers/lazy-map.js';
 const SKILL_COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);
-function skillDirsMatch(src, dest) {
+/** Exported for unit tests (RUSH-2320 #2). Production callers: list() below. */
+export function skillDirsMatch(src, dest) {
     const entries = fs.readdirSync(src, { withFileTypes: true });
     for (const entry of entries) {
         if (entry.isSymbolicLink())
@@ -25,7 +26,21 @@ function skillDirsMatch(src, dest) {
                 return false;
         }
         else {
-            if (!fs.existsSync(destPath))
+            // Stat-first (RUSH-2320 #2): size mismatch is a definitive miss with no
+            // content reads. Do NOT treat equal mtimes as equal content — src and
+            // dest are different trees (version home vs source), and copyFileSync
+            // does not preserve mtime, so mtime equality is accidental and unsafe.
+            // Content compare only when sizes match.
+            let srcStat;
+            let destStat;
+            try {
+                srcStat = fs.statSync(srcPath);
+                destStat = fs.statSync(destPath);
+            }
+            catch {
+                return false;
+            }
+            if (srcStat.size !== destStat.size)
                 return false;
             if (fs.readFileSync(srcPath, 'utf-8') !== fs.readFileSync(destPath, 'utf-8'))
                 return false;

package/dist/lib/staleness/index.d.ts

@@ -16,7 +16,16 @@ export type { SyncManifest } from './types.js';
 export { MANIFEST_VERSION } from './types.js';
 export declare function loadManifest(agent: AgentId, version: string): SyncManifest | null;
 export declare function saveManifest(agent: AgentId, version: string, manifest: SyncManifest): void;
-export declare function buildManifest(agent: AgentId, version: string, cwd: string): SyncManifest;
+/**
+ * Snapshot current resource fingerprints for `agent@version`.
+ *
+ * When `previous` is supplied (the still-loaded post-guard manifest), any
+ * entry whose stored path/mtime/size still match via the checker's `isFresh`
+ * is carried forward without re-hashing. Measured: full rebuild ~716 ms →
+ * carry-forward near the 5.67 ms `isStale` cost on an unchanged tree
+ * (RUSH-2320 #3).
+ */
+export declare function buildManifest(agent: AgentId, version: string, cwd: string, previous?: SyncManifest | null): SyncManifest;
 /**
  * True when any tracked resource has drifted from the stored manifest.
  * Walks every resource type in turn and returns true at the first miss —

package/dist/lib/staleness/index.js

@@ -69,7 +69,16 @@ export function saveManifest(agent, version, manifest) {
         catch { /* ignore */ }
     }
 }
-export function buildManifest(agent, version, cwd) {
+/**
+ * Snapshot current resource fingerprints for `agent@version`.
+ *
+ * When `previous` is supplied (the still-loaded post-guard manifest), any
+ * entry whose stored path/mtime/size still match via the checker's `isFresh`
+ * is carried forward without re-hashing. Measured: full rebuild ~716 ms →
+ * carry-forward near the 5.67 ms `isStale` cost on an unchanged tree
+ * (RUSH-2320 #3).
+ */
+export function buildManifest(agent, version, cwd, previous) {
     const manifest = {
         v: MANIFEST_VERSION,
         syncedAt: new Date().toISOString(),
@@ -85,14 +94,30 @@ export function buildManifest(agent, version, cwd) {
     };
     for (const { checker, field } of STANDARD_CHECKERS) {
         const target = manifest[field];
+        const prevMap = (previous?.[field] ?? {});
         for (const name of checker.listNames(cwd)) {
+            const prev = prevMap[name];
+            if (prev !== undefined && checker.isFresh(name, prev, cwd)) {
+                target[name] = prev;
+                continue;
+            }
             const entry = checker.build(name, cwd);
             if (entry !== null)
                 target[name] = entry;
         }
     }
-    manifest.rules = buildRules(agent, version, cwd);
-    manifest.permissions = buildPermissions();
+    if (previous?.rules && !isRulesStale(previous.rules, agent, version, cwd)) {
+        manifest.rules = previous.rules;
+    }
+    else {
+        manifest.rules = buildRules(agent, version, cwd);
+    }
+    if (previous?.permissions && !isPermissionsStale(previous.permissions)) {
+        manifest.permissions = previous.permissions;
+    }
+    else {
+        manifest.permissions = buildPermissions();
+    }
     return manifest;
 }
 /**

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

@@ -156,6 +156,7 @@ export declare class AgentProcess {
     worktreePath: string | null;
     hostName: string | null;
     hostTarget: string | null;
+    hostIdentityFile: string | null;
     repoPath: string | null;
     remotePid: number | null;
     remoteLog: string | null;

package/dist/lib/teams/agents.js

@@ -493,6 +493,7 @@ export class AgentProcess {
     // (remotePid/remoteLog/remoteExit) — so the giant constructor stays untouched.
     hostName = null;
     hostTarget = null;
+    hostIdentityFile = null;
     repoPath = null;
     remotePid = null;
     remoteLog = null;
@@ -692,6 +693,7 @@ export class AgentProcess {
         const delta = pullRemoteLogDelta(this.hostTarget, {
             remoteLog: this.remoteLog,
             offset: this.remoteLogOffset,
+            extraSshArgs: this.hostIdentityFile ? ['-i', this.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [],
         });
         if (delta && delta.bytes.length > 0) {
             const stdoutPath = await this.getStdoutPath();
@@ -717,6 +719,7 @@ export class AgentProcess {
             const res = sshExec(this.hostTarget, `cat ${this.remoteExit} 2>/dev/null`, {
                 timeoutMs: 8000,
                 multiplex: true,
+                extraSshArgs: this.hostIdentityFile ? ['-i', this.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [],
             });
             exit = res.code === 0 && res.stdout.trim() !== '' ? res.stdout.trim() : null;
         }
@@ -898,6 +901,7 @@ export class AgentProcess {
             worktree_path: this.worktreePath,
             host_name: this.hostName,
             host_target: this.hostTarget,
+            host_identity_file: this.hostIdentityFile,
             repo_path: this.repoPath,
             remote_pid: this.remotePid,
             remote_log: this.remoteLog,
@@ -952,6 +956,7 @@ export class AgentProcess {
             // constructor signature stays fixed. Null on every pre-existing teammate.
             agent.hostName = meta.host_name || null;
             agent.hostTarget = meta.host_target || null;
+            agent.hostIdentityFile = meta.host_identity_file || null;
             agent.repoPath = meta.repo_path || null;
             agent.remotePid = typeof meta.remote_pid === 'number' ? meta.remote_pid : null;
             agent.remoteLog = meta.remote_log || null;
@@ -980,7 +985,11 @@ export class AgentProcess {
             // interpolate UNQUOTED so `$HOME` expands (shellQuote would defeat it).
             const probe = `test -f ${this.remoteExit} && echo DEAD || ` +
                 `(kill -0 ${this.remotePid} 2>/dev/null && echo ALIVE || echo DEAD)`;
-            const res = sshExec(this.hostTarget, probe, { timeoutMs: 8000, multiplex: true });
+            const res = sshExec(this.hostTarget, probe, {
+                timeoutMs: 8000,
+                multiplex: true,
+                extraSshArgs: this.hostIdentityFile ? ['-i', this.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [],
+            });
             if (res.code === null)
                 return true; // transient ssh failure — don't reap early
             return res.stdout.trim().endsWith('ALIVE');
@@ -1640,10 +1649,16 @@ export class AgentManager {
         if (!host) {
             throw new Error(`Cannot launch remote teammate ${agent.agentId}: device "${agent.hostName}" no longer resolves.`);
         }
-        // Ensure agents-cli is present + version-matched on the host; surface (not
-        // fail on) an agent-not-installed warning like dispatch.ts does.
+        agent.hostIdentityFile = host.identityFile ?? null;
+        // Ensure agents-cli is present + the pin is installed on the host. A bare
+        // agent name still warns (like dispatch.ts); a concrete agent.version pin
+        // fails loud so the teammate never reports launched against a missing pin
+        // (RUSH-2313).
         try {
-            const { warnings } = ensureHostReady(host, { agent: agent.agentType });
+            const { warnings } = ensureHostReady(host, {
+                agent: agent.agentType,
+                version: agent.version ?? undefined,
+            });
             for (const w of warnings)
                 process.stderr.write(`[teams] warning: ${w}\n`);
         }
@@ -1661,7 +1676,9 @@ export class AgentManager {
                 remoteCwd = agent.worktreePath;
             }
             else {
-                const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+                const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName, {
+                    extraSshArgs: agent.hostIdentityFile ? ['-i', agent.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [],
+                });
                 agent.worktreePath = worktreePath;
                 remoteCwd = worktreePath;
             }
@@ -1743,9 +1760,12 @@ export class AgentManager {
         }
         const target = sshTargetFor(host);
         const teamMeta = await getTeam(taskName);
-        const repoRoot = ensureRemoteRepo(target, teamMeta?.repo ?? '', taskName);
+        const repoRoot = ensureRemoteRepo(target, teamMeta?.repo ?? '', taskName, {
+            extraSshArgs: host.identityFile ? ['-i', host.identityFile, '-o', 'IdentitiesOnly=yes'] : [],
+        });
         agent.hostName = host.name;
         agent.hostTarget = target;
+        agent.hostIdentityFile = host.identityFile ?? null;
         agent.repoPath = repoRoot;
         await agent.saveMeta();
     }
@@ -1864,11 +1884,12 @@ export class AgentManager {
             return;
         const byTarget = new Map();
         for (const a of teammates) {
-            const arr = byTarget.get(a.hostTarget) || [];
-            arr.push(a);
-            byTarget.set(a.hostTarget, arr);
+            const key = `${a.hostTarget}\0${a.hostIdentityFile ?? ''}`;
+            const group = byTarget.get(key) || { target: a.hostTarget, agents: [] };
+            group.agents.push(a);
+            byTarget.set(key, group);
         }
-        for (const [target, agents] of byTarget) {
+        for (const { target, agents } of byTarget.values()) {
             // Emit one line per teammate: "<agentId> ALIVE|DEAD <exitOrEmpty>". A single
             // round-trip over the multiplexed socket, regardless of teammate count.
             const parts = agents.map((a) => {
@@ -1883,7 +1904,12 @@ export class AgentManager {
                     `elif kill -0 ${a.remotePid} 2>/dev/null; then printf 'ALIVE\\n'; ` +
                     `else printf 'DEAD\\n'; fi`);
             });
-            const res = sshExec(target, parts.join('; '), { timeoutMs: 12000, multiplex: true });
+            const identityFile = agents[0]?.hostIdentityFile;
+            const res = sshExec(target, parts.join('; '), {
+                timeoutMs: 12000,
+                multiplex: true,
+                extraSshArgs: identityFile ? ['-i', identityFile, '-o', 'IdentitiesOnly=yes'] : [],
+            });
             if (res.code === null)
                 continue; // transient ssh failure — skip this wave, no snapshot
             const snapshots = new Map();
@@ -2155,6 +2181,7 @@ export class AgentManager {
                     sshExec(agent.hostTarget, `kill -TERM -- -${agent.remotePid} 2>/dev/null`, {
                         timeoutMs: 10000,
                         multiplex: true,
+                        extraSshArgs: agent.hostIdentityFile ? ['-i', agent.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [],
                     });
                 }
                 catch {

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

@@ -1,3 +1,6 @@
+interface RemoteSshOptions {
+    extraSshArgs?: string[];
+}
 /**
  * Render a path for safe interpolation into a REMOTE shell, expanding a leading
  * `~`/`~/` to `"$HOME"` so it resolves on the host. A plain `shellQuote('~/x')`
@@ -13,15 +16,15 @@ export declare function remotePathExpr(p: string): string;
  * downstream remote command (launch `cd`, worktree create, polling) works from an
  * absolute path with no tilde-expansion hazard.
  */
-export declare function resolveRemoteRepoRoot(target: string, repoPath: string): string | null;
+export declare function resolveRemoteRepoRoot(target: string, repoPath: string, opts?: RemoteSshOptions): string | null;
 /** True when `repoPath` is a git working tree on the host. */
-export declare function isRemoteGitRepo(target: string, repoPath: string): boolean;
+export declare function isRemoteGitRepo(target: string, repoPath: string, opts?: RemoteSshOptions): boolean;
 /**
  * Resolve the host repo's default branch name (origin/HEAD → `main`/`master`/…).
  * Falls back to `main` when origin/HEAD isn't set, matching the local recipe's
  * `remote set-head` step.
  */
-export declare function remoteDefaultBranch(target: string, repoPath: string): string;
+export declare function remoteDefaultBranch(target: string, repoPath: string, opts?: RemoteSshOptions): string;
 /**
  * Create a worktree on the host for a teammate, branched off the freshly-fetched
  * default branch. Returns the absolute worktree path on the host.
@@ -30,7 +33,7 @@ export declare function remoteDefaultBranch(target: string, repoPath: string): s
  * `worktree add -b … origin/<default>` so a stale checkout can't fork the
  * teammate off old code.
  */
-export declare function createRemoteWorktree(target: string, repoPath: string, worktreeName: string): string;
+export declare function createRemoteWorktree(target: string, repoPath: string, worktreeName: string, opts?: RemoteSshOptions): string;
 /**
  * Ensure the team's repo is present on the host and return its absolute git
  * root. The canonical location is `~/.agents/repos/<slug>` (slug = sanitized
@@ -45,12 +48,13 @@ export declare function createRemoteWorktree(target: string, repoPath: string, w
  * expands `$HOME` — single-quoting the tilde would defeat expansion, the same
  * hazard dispatch.ts avoids.
  */
-export declare function ensureRemoteRepo(target: string, repo: string, slug: string): string;
+export declare function ensureRemoteRepo(target: string, repo: string, slug: string, opts?: RemoteSshOptions): string;
 /** True when the host worktree has uncommitted changes (staged or unstaged). */
-export declare function remoteWorktreeDirty(target: string, worktreePath: string): boolean;
+export declare function remoteWorktreeDirty(target: string, worktreePath: string, opts?: RemoteSshOptions): boolean;
 /**
  * Remove a host worktree and (optionally) its branch. Best-effort: prunes on a
  * "not a working tree" error and ignores a missing branch, matching local
  * `removeWorktree` semantics so cleanup never throws on a half-gone worktree.
  */
-export declare function removeRemoteWorktree(target: string, repoPath: string, worktreeName: string, deleteBranch?: boolean): void;
+export declare function removeRemoteWorktree(target: string, repoPath: string, worktreeName: string, deleteBranch?: boolean, opts?: RemoteSshOptions): void;
+export {};