@phnx-labs/agents-cli 1.22.27 → 1.22.29

package/dist/lib/hosts/dispatch.js

@@ -12,7 +12,7 @@ import { randomUUID } from 'crypto';
 import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
-import { remoteShellFor, posixEnvExports } from './remote-cmd.js';
+import { encodePowershell, powershellQuote, remoteShellFor, posixEnvExports } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { resolveActor, actorEnv } from '../actor.js';
 import { saveTask, updateTask, terminalPatch } from './tasks.js';
@@ -148,14 +148,52 @@ export function buildDetachedLaunchCommand(inner) {
     ].join(' ');
     return `bash -lc ${shellQuote(`node -e ${shellQuote(nodeScript)}`)}`;
 }
+function windowsRemotePath(path) {
+    return path.startsWith('$HOME/')
+        ? `(Join-Path $HOME ${powershellQuote(path.slice('$HOME/'.length))})`
+        : powershellQuote(path);
+}
+/** Build the detached PowerShell launch protocol used by Windows SSH hosts. */
+export function buildWindowsDetachedLaunchCommand(opts) {
+    const log = windowsRemotePath(opts.remoteLog);
+    const exit = windowsRemotePath(opts.remoteExit);
+    const env = Object.entries(opts.env).map(([key, value]) => `$env:${key} = ${powershellQuote(value)}`);
+    const cwd = opts.remoteCwd
+        ? opts.mirrorCwd
+            ? `try { Set-Location -LiteralPath ${powershellQuote(opts.remoteCwd)} } catch { Set-Location -LiteralPath $HOME }`
+            : `Set-Location -LiteralPath ${powershellQuote(opts.remoteCwd)}`
+        : '';
+    const inner = [
+        `$ProgressPreference = 'SilentlyContinue'`,
+        `$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8'`,
+        ...env,
+        cwd,
+        `$log = ${log}`,
+        `$exit = ${exit}`,
+        `$code = 1`,
+        `try { & ${['agents', ...opts.forwardedArgs].map(powershellQuote).join(' ')} *> $log; if ($null -ne $LASTEXITCODE) { $code = $LASTEXITCODE } } catch { $_ | Out-File -LiteralPath $log -Append; $code = 1 } finally { Set-Content -LiteralPath $exit -Value $code -NoNewline -Encoding ascii }`,
+    ].filter(Boolean).join('; ');
+    const encodedInner = encodePowershell(inner);
+    const outer = [
+        `$dir = Join-Path $HOME '.agents/.cache/hosts'`,
+        `New-Item -ItemType Directory -Force -Path $dir | Out-Null`,
+        `Remove-Item -LiteralPath ${exit} -Force -ErrorAction SilentlyContinue`,
+        `$result = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = ${powershellQuote(`powershell.exe -NoProfile -EncodedCommand ${encodedInner}`)} }`,
+        `if ($result.ReturnValue -ne 0) { throw \"Win32_Process.Create failed with code $($result.ReturnValue)\" }`,
+        `Write-Output $result.ProcessId`,
+    ].join('; ');
+    return `powershell -NoProfile -EncodedCommand ${encodePowershell(outer)}`;
+}
 function terminateRemoteLaunch(task) {
     if (!task.pid)
         throw new Error(`Cannot terminate remote task ${task.id}: launch returned no PID.`);
     const pid = task.pid;
-    const command = `if kill -TERM -- -${pid} 2>/dev/null; then ` +
-        `sleep 1; kill -KILL -- -${pid} 2>/dev/null || true; ` +
-        `elif kill -0 -- -${pid} 2>/dev/null; then exit 1; fi; ` +
-        `rm -f ${task.remoteLog} ${task.remoteExit}`;
+    const command = task.remoteShell === 'powershell'
+        ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`Stop-Process -Id ${pid} -Force -ErrorAction SilentlyContinue; Remove-Item -LiteralPath ${windowsRemotePath(task.remoteLog)}, ${windowsRemotePath(task.remoteExit)} -Force -ErrorAction SilentlyContinue`)}`
+        : `if kill -TERM -- -${pid} 2>/dev/null; then ` +
+            `sleep 1; kill -KILL -- -${pid} 2>/dev/null || true; ` +
+            `elif kill -0 -- -${pid} 2>/dev/null; then exit 1; fi; ` +
+            `rm -f ${task.remoteLog} ${task.remoteExit}`;
     const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true, extraSshArgs: task.identityFile ? ['-i', task.identityFile, '-o', 'IdentitiesOnly=yes'] : undefined });
     if (result.code !== 0) {
         throw new Error(`Failed to terminate remote task ${task.id} on ${task.host}: ` +
@@ -194,6 +232,17 @@ export function buildStopRemoteCommand(pid, remoteExit) {
         `else echo 143 > ${remoteExit}; echo GONE; fi; ` +
         `fi`);
 }
+export function buildWindowsStopRemoteCommand(pid, remoteExit) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        throw new Error(`Invalid remote task pid: ${pid}`);
+    const exit = windowsRemotePath(remoteExit);
+    const script = `$process = Get-Process -Id ${pid} -ErrorAction SilentlyContinue; ` +
+        `function Get-DescendantProcessIds([int]$ParentId) { $children = Get-CimInstance Win32_Process -Filter \"ParentProcessId = $ParentId\"; foreach ($child in $children) { Get-DescendantProcessIds $child.ProcessId; $child.ProcessId } }; ` +
+        `if ($process) { $descendants = @(Get-DescendantProcessIds ${pid}); foreach ($childId in $descendants) { Stop-Process -Id $childId -Force -ErrorAction SilentlyContinue }; Stop-Process -Id ${pid} -Force; Set-Content -LiteralPath ${exit} -Value 143 -NoNewline -Encoding ascii; Write-Output 'SIGNALED' } ` +
+        `elseif (Test-Path -LiteralPath ${exit}) { $code = (Get-Content -LiteralPath ${exit} -Raw).Trim(); if ($code) { Write-Output (\"ALREADY $code\") } else { Set-Content -LiteralPath ${exit} -Value 143 -NoNewline -Encoding ascii; Write-Output 'GONE' } } ` +
+        `else { Set-Content -LiteralPath ${exit} -Value 143 -NoNewline -Encoding ascii; Write-Output 'GONE' }`;
+    return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
+}
 /**
  * Stop a running host task from the origin machine (`agents hosts stop <id>`).
  *
@@ -209,7 +258,9 @@ export function stopDispatchedTask(task) {
     if (!task.pid) {
         throw new Error(`Cannot stop remote task ${task.id}: launch returned no PID.`);
     }
-    const command = buildStopRemoteCommand(task.pid, task.remoteExit);
+    const command = task.remoteShell === 'powershell'
+        ? buildWindowsStopRemoteCommand(task.pid, task.remoteExit)
+        : buildStopRemoteCommand(task.pid, task.remoteExit);
     const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true, extraSshArgs: task.identityFile ? ['-i', task.identityFile, '-o', 'IdentitiesOnly=yes'] : undefined });
     if (result.code !== 0) {
         throw new Error(`Failed to stop remote task ${task.id} on ${task.host}: ` +
@@ -230,21 +281,11 @@ export function stopDispatchedTask(task) {
  * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
  * so the nohup/exit-file/offset-tail machinery lives in exactly one place.
  *
- * Windows remotes are refused up front: the detached launch is only half the
- * contract — the follow/reconcile layer (`progress.ts`/`reconcile.ts`) offset-
- * tails the log with POSIX `tail -c`/`printf`/`cat`/`stat`, which do not exist
- * in cmd.exe/PowerShell. Shipping the launch alone would leave `run --host
- * <windows>` dispatching but hanging on follow forever, so we fail fast with an
- * actionable message instead. Read-only `--host` commands (view/sessions/…) run
- * a single round-trip with no follow protocol and DO work against Windows.
+ * POSIX hosts use a detached bash process group; Windows hosts use a hidden
+ * detached PowerShell process and the same durable log/exit-file protocol.
  */
 async function launchDetached(host, target, opts) {
-    if (remoteShellFor(resolveRemoteOsSync(host.name)) === 'powershell') {
-        throw new Error(`Detached dispatch to Windows host "${host.name}" is not supported yet — the run ` +
-            `follow/reconcile layer is POSIX-only (offset-tails the remote log with tail/cat/stat). ` +
-            `Read-only --host commands (view, sessions, usage, cost, doctor, list, teams) do work ` +
-            `against Windows.`);
-    }
+    const remoteShell = remoteShellFor(host.os ?? resolveRemoteOsSync(host.name));
     const id = randomUUID().slice(0, 8);
     const remoteLog = `${REMOTE_DIR}/${id}.log`;
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
@@ -266,7 +307,16 @@ async function launchDetached(host, target, opts) {
     const credHostKeyOpts = opts.copyCreds ? hostKeyCheckingOpts(true) : undefined;
     // Outer: ensure dir, launch the login-shell wrapper as a new process-group
     // leader, and print that leader PID.
-    const launch = `mkdir -p ${REMOTE_DIR}; ${buildDetachedLaunchCommand(inner)}`;
+    const launch = remoteShell === 'powershell'
+        ? buildWindowsDetachedLaunchCommand({
+            forwardedArgs: opts.forwardedArgs,
+            remoteCwd: opts.remoteCwd,
+            mirrorCwd: opts.mirrorCwd,
+            remoteLog,
+            remoteExit,
+            env: withActorEnv(opts.agentLabel === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {}),
+        })
+        : `mkdir -p ${REMOTE_DIR}; ${buildDetachedLaunchCommand(inner)}`;
     const res = sshExec(target, launch, {
         timeoutMs: 30000,
         multiplex: !opts.copyCreds,
@@ -282,6 +332,7 @@ async function launchDetached(host, target, opts) {
         host: host.name,
         target,
         identityFile: host.identityFile,
+        remoteShell,
         agent: opts.agentLabel,
         prompt: opts.promptLabel,
         pid: Number.isFinite(pid) ? pid : undefined,
@@ -314,6 +365,7 @@ async function launchDetached(host, target, opts) {
         echo: true,
         timeoutMs: opts.timeoutMs,
         extraSshArgs: hostIdentityArgs(host),
+        remoteShell,
     });
     // -1 = the follow window closed while the run continues on the host. Leave the
     // record 'running' (do NOT freeze it terminal) so a later `hosts ps`/`logs`
@@ -446,7 +498,9 @@ export function buildInteractiveRunForwardedArgs(opts) {
  */
 export async function runInteractiveOnHost(host, opts) {
     const target = sshTargetFor(host);
-    const { warnings } = ensureHostReady(host, { agent: opts.agent });
+    // Concrete version pins fail loud here (RUSH-2313) so we never open a TTY
+    // to a box that cannot run the pin.
+    const { warnings } = ensureHostReady(host, { agent: opts.agent, version: opts.version });
     for (const w of warnings)
         process.stderr.write(`[hosts] warning: ${w}\n`);
     const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
@@ -473,7 +527,9 @@ export async function runInteractiveOnHost(host, opts) {
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export async function dispatchToHost(host, opts) {
     const target = sshTargetFor(host);
-    const { warnings } = ensureHostReady(host, { agent: opts.agent });
+    // Concrete agent@version pins fail loud before we print "Dispatched" and
+    // leave a dead remote log (RUSH-2313). Aliases stay remote-resolved.
+    const { warnings } = ensureHostReady(host, { agent: opts.agent, version: opts.version });
     for (const w of warnings)
         process.stderr.write(`[hosts] warning: ${w}\n`);
     return launchDetached(host, target, {

package/dist/lib/hosts/logs.js

@@ -16,6 +16,7 @@ import { loadTask, localLogPath, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { reconcileTask } from './reconcile.js';
 import { sshExecRaw } from '../ssh-exec.js';
+import { encodePowershell } from './remote-cmd.js';
 /** Lines of raw combined-stdout to show in the concise (non-`full`) view. */
 const HOST_LOG_TAIL_LINES = 40;
 /**
@@ -32,6 +33,8 @@ export async function showHostTaskLog(id, follow, full = false) {
             remoteExit: task.remoteExit,
             taskId: id,
             echo: true,
+            remoteShell: task.remoteShell,
+            extraSshArgs: task.identityFile ? ['-i', task.identityFile, '-o', 'IdentitiesOnly=yes'] : [],
         });
         // -1 = follow window closed; the run continues on the host (not a failure,
         // so exit 0). Any real code is the finished run — persist the terminal
@@ -106,7 +109,14 @@ export function tailLines(text, n) {
  * and progress.ts.
  */
 function fetchAndCacheRemoteLog(task) {
-    const res = sshExecRaw(task.target, `cat ${task.remoteLog} 2>/dev/null`, { timeoutMs: 30000, multiplex: true });
+    const command = task.remoteShell === 'powershell'
+        ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`$path = Join-Path $HOME '${task.remoteLog.replace(/^\$HOME\//, '').replace(/'/g, "''")}'; if (Test-Path -LiteralPath $path) { $bytes = [IO.File]::ReadAllBytes($path); [Console]::OpenStandardOutput().Write($bytes, 0, $bytes.Length) }`)}`
+        : `cat ${task.remoteLog} 2>/dev/null`;
+    const res = sshExecRaw(task.target, command, {
+        timeoutMs: 30000,
+        multiplex: true,
+        extraSshArgs: task.identityFile ? ['-i', task.identityFile, '-o', 'IdentitiesOnly=yes'] : undefined,
+    });
     if (res.code !== 0 || res.stdout.length === 0)
         return null;
     // The hosts cache dir already exists (saveTask created it) — write is best-effort.

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

@@ -126,4 +126,9 @@ export declare function streamAgentsOnHost(host: Host, forwardedArgs: string[],
     remoteOs?: string;
     target?: string;
 }): number;
+export declare function passthroughSshOptions(host: Host, interactive: boolean): {
+    tty: boolean;
+    multiplex: true;
+    extraSshArgs: string[];
+};
 export {};

package/dist/lib/hosts/passthrough.js

@@ -19,7 +19,7 @@
 import chalk from 'chalk';
 import { assertValidSshTarget, sshStream } from '../ssh-exec.js';
 import { resolveHost, resolveHostByCap } from './registry.js';
-import { sshTargetFor } from './types.js';
+import { sshTargetFor, hostIdentityArgs } from './types.js';
 import { dispatchAgentsCommand, withActorEnv } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, stripClixml, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
@@ -620,10 +620,13 @@ export function streamAgentsOnHost(host, forwardedArgs, opts = {}) {
     const remoteOs = opts.remoteOs ?? resolveRemoteOsSync(host.name);
     const env = withActorEnv({ ...opts.extraEnv, AGENTS_FLEET_REMOTE: '1' });
     const remoteCmd = buildRemoteAgentsInvocation(forwardedArgs, opts.remoteCwd, remoteOs, env);
-    const code = sshStream(target, remoteCmd, { tty: !!opts.interactive, multiplex: true });
+    const code = sshStream(target, remoteCmd, passthroughSshOptions(host, !!opts.interactive));
     if (code === 255) {
         console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +
             chalk.gray(' Check: agents hosts check ' + host.name));
     }
     return code;
 }
+export function passthroughSshOptions(host, interactive) {
+    return { tty: interactive, multiplex: true, extraSshArgs: hostIdentityArgs(host) };
+}

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

@@ -38,6 +38,7 @@ export declare const REMOTE_MIRROR_MAX_BYTES: number;
 export declare function pullRemoteLogDelta(target: string, opts: {
     remoteLog: string;
     offset: number;
+    extraSshArgs?: string[];
 }): {
     bytes: Buffer;
     newOffset: number;
@@ -56,6 +57,7 @@ export interface FollowOptions {
     /** Idle-backoff ceiling (default 4× the fast interval, min 4000ms). */
     maxPollMs?: number;
     extraSshArgs?: string[];
+    remoteShell?: 'posix' | 'powershell';
 }
 /**
  * Build the per-task sentinel that separates the log tail from the exit-file
@@ -97,10 +99,18 @@ export declare function fetchProgress(target: string, opts: {
     remoteExit: string;
     taskId: string;
     offset: number;
+    extraSshArgs?: string[];
+    remoteShell?: 'posix' | 'powershell';
 }): {
     logChunk: Buffer;
     exit: string;
 } | null;
+export declare function buildWindowsProgressCommand(opts: {
+    remoteLog: string;
+    remoteExit: string;
+    taskId: string;
+    offset: number;
+}): string;
 /**
  * Remote shell for the persistent follow stream.
  *

package/dist/lib/hosts/progress.js

@@ -13,6 +13,7 @@
  */
 import * as fs from 'fs';
 import { sshExec, sshExecRaw, sshExecRawStream } from '../ssh-exec.js';
+import { encodePowershell } from './remote-cmd.js';
 import { localLogPath } from './tasks.js';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -47,7 +48,7 @@ export function pullRemoteLogDelta(target, opts) {
     // single-quote it into a literal `$HOME`, and the tail would find nothing). The
     // hex basename is injection-safe, matching fetchProgress below.
     const remote = `tail -c +${opts.offset + 1} ${opts.remoteLog} 2>/dev/null`;
-    const res = sshExecRaw(target, remote, { timeoutMs: 20000, multiplex: true });
+    const res = sshExecRaw(target, remote, { timeoutMs: 20000, multiplex: true, extraSshArgs: opts.extraSshArgs });
     if (res.code === null)
         return null; // ssh itself failed / timed out
     return { bytes: res.stdout, newOffset: opts.offset + res.stdout.length };
@@ -102,19 +103,35 @@ export function fetchProgress(target, opts) {
     // only escape-sensitive bytes are its newlines (→ `\n`); it carries no `%`,
     // single-quote, or other printf/shell-special chars (task id is hex).
     const printfArg = exitMarker(opts.taskId).replace(/\n/g, '\\n');
-    const remote = `tail -c +${opts.offset + 1} ${opts.remoteLog} 2>/dev/null; ` +
-        `printf '${printfArg}'; ` +
-        `cat ${opts.remoteExit} 2>/dev/null`;
+    const remote = opts.remoteShell === 'powershell'
+        ? buildWindowsProgressCommand(opts)
+        : `tail -c +${opts.offset + 1} ${opts.remoteLog} 2>/dev/null; printf '${printfArg}'; cat ${opts.remoteExit} 2>/dev/null`;
     // Raw bytes (no UTF-8 decode): the log tail must be counted and re-emitted
     // byte-for-byte so a multibyte char split at the `tail -c` boundary neither
     // drifts the offset nor renders as U+FFFD. The exit code is pure ASCII → safe
     // to decode to a string for the caller's `.trim()`.
-    const res = sshExecRaw(target, remote, { timeoutMs: 20000 });
+    const res = sshExecRaw(target, remote, { timeoutMs: 20000, extraSshArgs: opts.extraSshArgs });
     const parts = splitProgressBytes(res.stdout, opts.taskId);
     if (!parts)
         return null;
     return { logChunk: parts.logChunk, exit: parts.exit.toString('utf8') };
 }
+export function buildWindowsProgressCommand(opts) {
+    const windowsPath = (value) => value.startsWith('$HOME/')
+        ? `(Join-Path $HOME '${value.slice('$HOME/'.length).replace(/'/g, "''")}')`
+        : `'${value.replace(/'/g, "''")}'`;
+    const markerBase64 = Buffer.from(exitMarker(opts.taskId), 'utf8').toString('base64');
+    const script = [
+        `$out = [Console]::OpenStandardOutput()`,
+        `$log = ${windowsPath(opts.remoteLog)}`,
+        `$exit = ${windowsPath(opts.remoteExit)}`,
+        `if (Test-Path -LiteralPath $log) { $bytes = [IO.File]::ReadAllBytes($log); if ($bytes.Length -gt ${opts.offset}) { $out.Write($bytes, ${opts.offset}, $bytes.Length - ${opts.offset}) } }`,
+        `$marker = [Convert]::FromBase64String('${markerBase64}')`,
+        `$out.Write($marker, 0, $marker.Length)`,
+        `if (Test-Path -LiteralPath $exit) { $bytes = [IO.File]::ReadAllBytes($exit); $out.Write($bytes, 0, $bytes.Length) }`,
+    ].join('; ');
+    return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
+}
 /**
  * Remote shell for the persistent follow stream.
  *
@@ -208,6 +225,21 @@ export async function followHostTask(target, opts) {
         offset += logChunk.length; // exact wire bytes — no re-encode drift
         return true;
     };
+    if (opts.remoteShell === 'powershell') {
+        for (;;) {
+            if (Date.now() >= deadline)
+                return -1;
+            const fetched = fetchProgress(target, { ...opts, offset, remoteShell: 'powershell' });
+            if (fetched) {
+                flush(fetched.logChunk);
+                const code = parseInt(fetched.exit.trim(), 10);
+                if (Number.isFinite(code))
+                    return code;
+            }
+            await sleep(waitMs);
+            waitMs = Math.min(maxMs, Math.round(waitMs * 1.5));
+        }
+    }
     for (;;) {
         const remaining = deadline - Date.now();
         if (remaining <= 0) {

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

@@ -18,14 +18,14 @@ export declare function buildProbeCommand(os?: string): string;
  * platform / enrolled `HostEntry.os`); when it marks the host Windows we take
  * the PowerShell path and report that known platform, otherwise POSIX + uname.
  */
-export declare function probeHost(target: string, os?: string): {
+export declare function probeHost(target: string, os?: string, extraSshArgs?: string[]): {
     reachable: boolean;
     os?: string;
 };
 /** ssh command that prints the remote agents-cli version. Pure/exported. */
 export declare function buildRemoteVersionCommand(os?: string): string;
 /** Remote agents-cli version (PATH-resolved on the remote), or null if not installed. */
-export declare function remoteAgentsVersion(target: string, os?: string): string | null;
+export declare function remoteAgentsVersion(target: string, os?: string, extraSshArgs?: string[]): string | null;
 /** ssh command that installs/upgrades agents-cli to `spec` then `agents setup`.
  * PowerShell has no `tail`/`[ -d ]`/`||`, so the Windows branch uses native
  * equivalents (`Select-Object -Last`, `Test-Path`). Pure/exported. */
@@ -66,17 +66,56 @@ export declare function readyProbe(target: string, os?: string, extraSshArgs?: s
 export declare function parseReadyProbe(stdout: string): ReadyProbe;
 /** True if `view` output lists the named agent (word-boundary, case-insensitive). */
 export declare function viewHasAgent(view: string, agent: string): boolean;
+/**
+ * True when `version` is a concrete pin the remote must already have installed
+ * (e.g. `0.145.0`, `2.1.207`). Aliases (`latest` / `oldest` / `pinned` /
+ * `default` / `all` / `any`) resolve against the remote's own install set and
+ * are not preflight-checked here.
+ */
+export declare function isConcreteVersionPin(version?: string | null): boolean;
+/**
+ * Installed version strings for `agent` from `agents view --json` output.
+ * Returns `[]` when the agent row is absent, `undefined` when `view` is not
+ * JSON (text `agents list` fallback) so callers can degrade.
+ */
+export declare function viewAgentVersions(view: string, agent: string): string[] | undefined;
+/**
+ * Whether a concrete `agent@version` is installed according to remote view
+ * output. JSON path is authoritative; text listing falls back to a whole-token
+ * version match. `undefined` only when the text path has the agent but no
+ * version token to confirm against (callers treat that as unverified).
+ */
+export declare function viewHasAgentVersion(view: string, agent: string, version: string): boolean | undefined;
+/** Actionable fail-loud message for a missing remote pin (RUSH-2313). */
+export declare function missingPinnedVersionMessage(hostName: string, agent: string, version: string, installed?: string[]): string;
 /** Read the requested harness's sign-in verdict from `agents view --json`. */
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;
 export interface EnsureReadyOptions {
     agent: string;
+    /**
+     * Explicit version pin (e.g. `"0.145.0"`). Concrete pins fail loud when the
+     * remote does not have that version installed so a detached `--no-follow`
+     * dispatch never reports "Dispatched" for a pin the box cannot run
+     * (RUSH-2313). Aliases (`latest` / …) are left for the remote CLI to resolve.
+     */
+    version?: string;
     /** Throw instead of warn when the agent isn't installed remotely. */
     requireAgent?: boolean;
 }
+/**
+ * Pure readiness verdict for the agent/version half of {@link ensureHostReady}
+ * (unit-tested without SSH). Returns warnings for soft agent-missing cases, or
+ * throws (via the caller's `throw new Error`) when a concrete pin is missing.
+ */
+export declare function evaluateHostAgentInstall(view: string, opts: EnsureReadyOptions, hostName: string): {
+    warnings: string[];
+};
 /**
  * Verify a host can run the agent: reachable + agents-cli present. Throws with an
  * actionable message otherwise. Agent-not-installed is a warning by default (the
  * remote `agents run` will surface it); pass requireAgent to make it fatal.
+ * A concrete `version` pin always fails loud when that version is absent
+ * (RUSH-2313) — never a silent "Dispatched" for a pin the box cannot run.
  *
  * One ssh round-trip (`readyProbe`) covers all three checks.
  */

package/dist/lib/hosts/ready.js

@@ -47,8 +47,8 @@ export function buildProbeCommand(os) {
  * platform / enrolled `HostEntry.os`); when it marks the host Windows we take
  * the PowerShell path and report that known platform, otherwise POSIX + uname.
  */
-export function probeHost(target, os) {
-    const r = sshExec(target, buildProbeCommand(os), { timeoutMs: 12000 });
+export function probeHost(target, os, extraSshArgs = []) {
+    const r = sshExec(target, buildProbeCommand(os), { timeoutMs: 12000, extraSshArgs });
     if (r.code !== 0)
         return { reachable: false };
     if (remoteShellFor(os) === 'powershell')
@@ -63,8 +63,8 @@ export function buildRemoteVersionCommand(os) {
         : 'bash -lc "agents --version 2>/dev/null"';
 }
 /** Remote agents-cli version (PATH-resolved on the remote), or null if not installed. */
-export function remoteAgentsVersion(target, os) {
-    const r = sshExec(target, buildRemoteVersionCommand(os), { timeoutMs: 20000 });
+export function remoteAgentsVersion(target, os, extraSshArgs = []) {
+    const r = sshExec(target, buildRemoteVersionCommand(os), { timeoutMs: 20000, extraSshArgs });
     if (r.code !== 0)
         return null;
     const v = r.stdout.trim();
@@ -140,6 +140,73 @@ export function parseReadyProbe(stdout) {
 export function viewHasAgent(view, agent) {
     return new RegExp(`\\b${agent}\\b`, 'i').test(view);
 }
+/**
+ * True when `version` is a concrete pin the remote must already have installed
+ * (e.g. `0.145.0`, `2.1.207`). Aliases (`latest` / `oldest` / `pinned` /
+ * `default` / `all` / `any`) resolve against the remote's own install set and
+ * are not preflight-checked here.
+ */
+export function isConcreteVersionPin(version) {
+    if (!version)
+        return false;
+    const v = version.trim();
+    if (!v)
+        return false;
+    // Keep in lockstep with agent-spec AGENT_QUALIFIERS (+ `any` filter token).
+    if (['latest', 'oldest', 'pinned', 'default', 'all', 'any'].includes(v.toLowerCase()))
+        return false;
+    // Same shape agent-spec accepts for an exact pin (no path traversal / spaces).
+    return /^(?!.*\.\.)[A-Za-z0-9._+-]{1,64}$/.test(v);
+}
+/**
+ * Installed version strings for `agent` from `agents view --json` output.
+ * Returns `[]` when the agent row is absent, `undefined` when `view` is not
+ * JSON (text `agents list` fallback) so callers can degrade.
+ */
+export function viewAgentVersions(view, agent) {
+    try {
+        const rows = JSON.parse(view);
+        if (!Array.isArray(rows))
+            return undefined;
+        const row = rows.find((candidate) => candidate.agent?.toLowerCase() === agent.toLowerCase());
+        if (!row)
+            return [];
+        return (row.versions ?? [])
+            .map((entry) => entry.version)
+            .filter((v) => typeof v === 'string' && v.length > 0);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a concrete `agent@version` is installed according to remote view
+ * output. JSON path is authoritative; text listing falls back to a whole-token
+ * version match. `undefined` only when the text path has the agent but no
+ * version token to confirm against (callers treat that as unverified).
+ */
+export function viewHasAgentVersion(view, agent, version) {
+    const versions = viewAgentVersions(view, agent);
+    if (versions !== undefined)
+        return versions.includes(version);
+    if (!viewHasAgent(view, agent))
+        return false;
+    const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (new RegExp(`\\b${escaped}\\b`).test(view))
+        return true;
+    return undefined;
+}
+/** Actionable fail-loud message for a missing remote pin (RUSH-2313). */
+export function missingPinnedVersionMessage(hostName, agent, version, installed) {
+    let installedHint = '';
+    if (installed) {
+        installedHint = installed.length > 0
+            ? ` Installed on that box: ${installed.join(', ')}.`
+            : ` Agent "${agent}" is not installed there.`;
+    }
+    return (`Pinned ${agent}@${version} is not installed on "${hostName}".${installedHint} ` +
+        `Install it on that box: agents ssh ${hostName} -- agents add ${agent}@${version}`);
+}
 /** Read the requested harness's sign-in verdict from `agents view --json`. */
 export function viewAgentSignedIn(view, agent) {
     try {
@@ -156,10 +223,38 @@ export function viewAgentSignedIn(view, agent) {
         return undefined;
     }
 }
+/**
+ * Pure readiness verdict for the agent/version half of {@link ensureHostReady}
+ * (unit-tested without SSH). Returns warnings for soft agent-missing cases, or
+ * throws (via the caller's `throw new Error`) when a concrete pin is missing.
+ */
+export function evaluateHostAgentInstall(view, opts, hostName) {
+    const warnings = [];
+    if (isConcreteVersionPin(opts.version)) {
+        const version = opts.version.trim();
+        const installed = viewAgentVersions(view, opts.agent);
+        const has = viewHasAgentVersion(view, opts.agent, version);
+        if (has === true)
+            return { warnings };
+        // Missing or unverifiable pin: fail loud. Detached host dispatch used to
+        // print "Dispatched" and only die in the remote log ("codex@0.145.0 is not
+        // installed") — whole fleet drains no-op'd under that silent success.
+        throw new Error(missingPinnedVersionMessage(hostName, opts.agent, version, installed));
+    }
+    if (!viewHasAgent(view, opts.agent)) {
+        const msg = `Agent "${opts.agent}" may not be installed on "${hostName}" (remote \`agents add ${opts.agent}\` to install).`;
+        if (opts.requireAgent)
+            throw new Error(msg);
+        warnings.push(msg);
+    }
+    return { warnings };
+}
 /**
  * Verify a host can run the agent: reachable + agents-cli present. Throws with an
  * actionable message otherwise. Agent-not-installed is a warning by default (the
  * remote `agents run` will surface it); pass requireAgent to make it fatal.
+ * A concrete `version` pin always fails loud when that version is absent
+ * (RUSH-2313) — never a silent "Dispatched" for a pin the box cannot run.
  *
  * One ssh round-trip (`readyProbe`) covers all three checks.
  */
@@ -177,12 +272,5 @@ export function ensureHostReady(host, opts) {
     if (!probe.version) {
         throw new Error(`agents-cli is not installed on "${host.name}". Enroll it first: agents hosts add ${host.name} (bootstraps agents-cli).`);
     }
-    const warnings = [];
-    if (!viewHasAgent(probe.view, opts.agent)) {
-        const msg = `Agent "${opts.agent}" may not be installed on "${host.name}" (remote \`agents add ${opts.agent}\` to install).`;
-        if (opts.requireAgent)
-            throw new Error(msg);
-        warnings.push(msg);
-    }
-    return { warnings };
+    return evaluateHostAgentInstall(probe.view, opts, host.name);
 }

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

@@ -35,7 +35,7 @@ export declare function classifyExit(res: Pick<SshExecResult, 'code' | 'stdout'
  * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
  * remote shell expands $HOME (same contract as progress.ts's fetch).
  */
-export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number, identityFile?: string): RemoteExitState;
+export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number, identityFile?: string, remoteShell?: 'posix' | 'powershell'): RemoteExitState;
 /**
  * Heal one record. Terminal records are immutable (and never re-probed); a
  * `running` record is resolved to completed/failed only when the remote `.exit`
@@ -51,3 +51,4 @@ export declare function reconcileTask(task: HostTask): HostTask;
  * (async) ssh path is deliberately out of scope.
  */
 export declare function reconcileRunningTasks(tasks: HostTask[]): HostTask[];
+export declare function reachabilityProbeCommand(remoteShell?: 'posix' | 'powershell'): string;

package/dist/lib/hosts/reconcile.js

@@ -12,6 +12,7 @@
  */
 import { sshExec } from '../ssh-exec.js';
 import { updateTask, terminalPatch } from './tasks.js';
+import { encodePowershell } from './remote-cmd.js';
 /**
  * Classify a `cat <remoteExit>` result into a remote run state. Pure: all the
  * bug-prone branching (ssh-failure vs absent vs empty vs coded) lives here so it
@@ -35,8 +36,11 @@ export function classifyExit(res) {
  * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
  * remote shell expands $HOME (same contract as progress.ts's fetch).
  */
-export function readRemoteExit(target, remoteExit, timeoutMs = 6000, identityFile) {
-    return classifyExit(sshExec(target, `cat ${remoteExit} 2>/dev/null`, {
+export function readRemoteExit(target, remoteExit, timeoutMs = 6000, identityFile, remoteShell = 'posix') {
+    const command = remoteShell === 'powershell'
+        ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`$path = Join-Path $HOME '${remoteExit.replace(/^\$HOME\//, '').replace(/'/g, "''")}'; if (Test-Path -LiteralPath $path) { Get-Content -LiteralPath $path -Raw }`)}`
+        : `cat ${remoteExit} 2>/dev/null`;
+    return classifyExit(sshExec(target, command, {
         timeoutMs,
         multiplex: true,
         extraSshArgs: identityFile ? ['-i', identityFile, '-o', 'IdentitiesOnly=yes'] : undefined,
@@ -50,7 +54,7 @@ export function readRemoteExit(target, remoteExit, timeoutMs = 6000, identityFil
 export function reconcileTask(task) {
     if (task.status !== 'running')
         return task;
-    const st = readRemoteExit(task.target, task.remoteExit, 6000, task.identityFile);
+    const st = readRemoteExit(task.target, task.remoteExit, 6000, task.identityFile, task.remoteShell);
     if (st.state !== 'done')
         return task;
     return updateTask(task.id, terminalPatch(st.code)) ?? task;
@@ -71,7 +75,8 @@ export function reconcileRunningTasks(tasks) {
     const patched = new Map();
     for (const t of running) {
         if (!reachable.has(t.target)) {
-            const probe = sshExec(t.target, 'true', {
+            const probeCommand = reachabilityProbeCommand(t.remoteShell);
+            const probe = sshExec(t.target, probeCommand, {
                 timeoutMs: 6000,
                 extraSshArgs: t.identityFile ? ['-i', t.identityFile, '-o', 'IdentitiesOnly=yes'] : undefined,
             });
@@ -79,7 +84,7 @@ export function reconcileRunningTasks(tasks) {
         }
         if (!reachable.get(t.target))
             continue; // host down → leave running
-        const st = readRemoteExit(t.target, t.remoteExit, 6000, t.identityFile);
+        const st = readRemoteExit(t.target, t.remoteExit, 6000, t.identityFile, t.remoteShell);
         if (st.state === 'done') {
             const updated = updateTask(t.id, terminalPatch(st.code));
             if (updated)
@@ -88,3 +93,6 @@ export function reconcileRunningTasks(tasks) {
     }
     return tasks.map((t) => patched.get(t.id) ?? t);
 }
+export function reachabilityProbeCommand(remoteShell) {
+    return remoteShell === 'powershell' ? 'powershell -NoProfile -Command "exit 0"' : 'true';
+}