@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/hosts/logs.js

@@ -0,0 +1,74 @@
+/**
+ * Shared host-task log viewer — the show-or-follow core behind both
+ * `agents hosts logs <id>` and the top-level `agents logs <id>`.
+ *
+ * A running task with follow re-enters the offset-tail (`followHostTask`);
+ * otherwise the captured local mirror (`localLogPath`) is printed. Kept in one
+ * place so the two commands can never drift.
+ */
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { loadTask, localLogPath, updateTask, terminalPatch } from './tasks.js';
+import { followHostTask } from './progress.js';
+import { reconcileTask } from './reconcile.js';
+import { sshExecRaw } from '../ssh-exec.js';
+/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
+export async function showHostTaskLog(id, follow) {
+    const task = loadTask(id);
+    if (!task)
+        return { found: false };
+    if (follow && task.status === 'running') {
+        const code = await followHostTask(task.target, {
+            remoteLog: task.remoteLog,
+            remoteExit: task.remoteExit,
+            taskId: id,
+            echo: true,
+        });
+        // -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
+        // status the killed dispatch follower would have written.
+        if (code === -1)
+            return { found: true, exitCode: 0 };
+        updateTask(id, terminalPatch(code));
+        return { found: true, exitCode: code };
+    }
+    // Non-follow view: heal a still-'running' record from the remote `.exit` so a
+    // plain `logs <id>` also unsticks a task whose follower was killed. No-op (no
+    // ssh) once the record is already terminal.
+    reconcileTask(task);
+    try {
+        process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
+    }
+    catch {
+        // No local log — task was dispatched with --no-follow. Fetch from the remote
+        // on demand and cache locally so subsequent calls are instant.
+        const remote = fetchAndCacheRemoteLog(task);
+        if (remote !== null) {
+            process.stdout.write(remote);
+        }
+        else {
+            process.stdout.write(chalk.gray('(no local log captured for this task)\n'));
+        }
+    }
+    return { found: true, exitCode: 0 };
+}
+/**
+ * Fetch a task's remote log over SSH, write it to the local mirror path (for
+ * future instant reads), and return its content. Returns null when the host is
+ * unreachable or the remote log is empty/absent.
+ *
+ * `remoteLog` is a $HOME-prefixed path with a safe (hex) basename — intentionally
+ * unquoted so the remote shell expands $HOME, matching the contract in reconcile.ts
+ * and progress.ts.
+ */
+function fetchAndCacheRemoteLog(task) {
+    const res = sshExecRaw(task.target, `cat ${task.remoteLog} 2>/dev/null`, { timeoutMs: 30000, multiplex: true });
+    if (res.code !== 0 || res.stdout.length === 0)
+        return null;
+    // The hosts cache dir already exists (saveTask created it) — write is best-effort.
+    try {
+        fs.writeFileSync(localLogPath(task.id), res.stdout);
+    }
+    catch { /* best-effort cache */ }
+    return res.stdout;
+}

package/dist/lib/hosts/option.js

@@ -12,7 +12,7 @@
 /** Attach the standard `--host` flag family to a command and return it (chainable). */
 export function addHostOption(cmd) {
     return cmd
-        .option('-H, --host <name>', 'Run this command on a registered host (or user@host) over SSH instead of locally. See `agents hosts`.')
+        .option('-H, --host <name>', 'Run this command on another machine over SSH instead of locally — a device, a registered host, or user@host. See `agents devices` / `agents hosts`.')
         .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
         .option('--no-tty', 'Force non-interactive output for --host runs even from a terminal.')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');

package/dist/lib/hosts/passthrough.js

@@ -22,6 +22,7 @@ import { resolveHost, resolveHostByCap } from './registry.js';
 import { sshTargetFor } from './types.js';
 import { dispatchAgentsCommand } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
+import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
 const REMOTE_PASSTHROUGH = {
     view: {},
@@ -32,6 +33,7 @@ const REMOTE_PASSTHROUGH = {
     list: {},
     sync: { nonInteractive: ['--yes'] },
     teams: {},
+    message: {},
 };
 /** `--no-tty` is stripped like the routing flags but carries no value. */
 const STRIP_SPECS = [...HOST_ROUTING_SPECS, { long: 'no-tty', takesValue: false }];
@@ -130,7 +132,7 @@ export async function maybeRunOnHost(command, allArgs) {
         }
         return true;
     }
-    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd);
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, resolveRemoteOsSync(host.name));
     const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
     if (code === 255) {
         console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +

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

@@ -5,6 +5,13 @@
  * a sibling `.exit` file. We poll `tail -c +<offset>` (durable, offset-tracked —
  * a dropped connection resumes from the saved offset) and finish when `.exit`
  * appears. Rich transcript-parser rendering is a fast-follow.
+ *
+ * Efficiency: each cycle is a SINGLE ssh round-trip that returns the new log
+ * bytes, a per-task sentinel, then the exit-file contents — half the process +
+ * handshake cost of the old tail-then-cat pair. It rides the default control
+ * socket (multiplex on) that the launch opened, and eases the poll interval off
+ * toward `maxPollMs` while the job is idle, so a quiet long-running follow no
+ * longer spawns thousands of ssh processes per hour on the laptop.
  */
 export interface FollowOptions {
     remoteLog: string;
@@ -15,7 +22,66 @@ export interface FollowOptions {
     echo?: boolean;
     /** Overall wall-clock cap; returns -1 on timeout. */
     timeoutMs?: number;
+    /** Fast poll interval while output is flowing (default 1500ms). */
     pollMs?: number;
+    /** Idle-backoff ceiling (default 4× the fast interval, min 4000ms). */
+    maxPollMs?: number;
 }
+/**
+ * Build the per-task sentinel that separates the log tail from the exit-file
+ * contents in one combined fetch. The task id (8 hex chars) makes collision with
+ * the agent's own output effectively impossible; callers still split on the LAST
+ * occurrence so a token echoed into the log can never be mistaken for the real
+ * trailing marker.
+ */
+export declare function exitMarker(taskId: string): string;
+/**
+ * Split a combined fetch (`<log bytes><marker><exit>`) back into its parts at the
+ * BYTE level. Splits on the LAST marker occurrence, so even if the agent's own
+ * output happened to echo the token, the real trailing sentinel still wins.
+ * Returns null when the marker is absent (a transient fetch miss — the remote
+ * shell never ran our printf), telling the caller to retry without advancing.
+ *
+ * Byte-level (not string) is load-bearing: `logChunk.length` is the EXACT number
+ * of log bytes consumed on the wire, which the follow loop adds to its offset. A
+ * string split would first UTF-8-decode, turning any multibyte char split at the
+ * `tail -c` boundary into a U+FFFD whose re-encoded length ≠ the wire bytes,
+ * drifting the offset (see followHostTask). `consumed` is returned explicitly for
+ * clarity; it always equals `logChunk.length`.
+ */
+export declare function splitProgressBytes(buf: Buffer, taskId: string): {
+    logChunk: Buffer;
+    exit: Buffer;
+    consumed: number;
+} | null;
+/**
+ * One round-trip: new log bytes since `offset`, the sentinel, then the exit
+ * file. Returns null on a transient fetch miss (ssh error / marker absent) so
+ * the caller simply retries next cycle without advancing the offset.
+ *
+ * `remoteLog`/`remoteExit` are $HOME-prefixed paths with safe (hex) basenames —
+ * intentionally unquoted so the remote shell expands $HOME.
+ */
+export declare function fetchProgress(target: string, opts: {
+    remoteLog: string;
+    remoteExit: string;
+    taskId: string;
+    offset: number;
+}): {
+    logChunk: Buffer;
+    exit: string;
+} | null;
+/**
+ * File identity (`dev:ino`) of a path on the remote host, or null if it can't be
+ * stat'd. GNU (`-c`) then BSD (`-f`) format, so it works on Linux and macOS hosts.
+ */
+export declare function readRemoteFileId(target: string, remotePath: string): string | null;
+/**
+ * True when the local mirror file IS the very file we're tailing — the
+ * localhost-as-host case, where `remoteLog` ($HOME-expanded) and `localLogPath`
+ * resolve to the same inode. Appending our read bytes back into it would feed the
+ * tail and multiply the log, so the caller must skip the mirror write.
+ */
+export declare function mirrorAliasesSource(localId: string | null, remoteId: string | null): boolean;
 /** Tail the remote log to stdout until the run finishes; return its exit code. */
 export declare function followHostTask(target: string, opts: FollowOptions): Promise<number>;

package/dist/lib/hosts/progress.js

@@ -5,45 +5,153 @@
  * a sibling `.exit` file. We poll `tail -c +<offset>` (durable, offset-tracked —
  * a dropped connection resumes from the saved offset) and finish when `.exit`
  * appears. Rich transcript-parser rendering is a fast-follow.
+ *
+ * Efficiency: each cycle is a SINGLE ssh round-trip that returns the new log
+ * bytes, a per-task sentinel, then the exit-file contents — half the process +
+ * handshake cost of the old tail-then-cat pair. It rides the default control
+ * socket (multiplex on) that the launch opened, and eases the poll interval off
+ * toward `maxPollMs` while the job is idle, so a quiet long-running follow no
+ * longer spawns thousands of ssh processes per hour on the laptop.
  */
 import * as fs from 'fs';
-import { sshExec } from '../ssh-exec.js';
+import { sshExec, sshExecRaw } from '../ssh-exec.js';
 import { localLogPath } from './tasks.js';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Build the per-task sentinel that separates the log tail from the exit-file
+ * contents in one combined fetch. The task id (8 hex chars) makes collision with
+ * the agent's own output effectively impossible; callers still split on the LAST
+ * occurrence so a token echoed into the log can never be mistaken for the real
+ * trailing marker.
+ */
+export function exitMarker(taskId) {
+    return `\n@@AGENTS_HOST_EXIT_${taskId}@@\n`;
+}
+/**
+ * Split a combined fetch (`<log bytes><marker><exit>`) back into its parts at the
+ * BYTE level. Splits on the LAST marker occurrence, so even if the agent's own
+ * output happened to echo the token, the real trailing sentinel still wins.
+ * Returns null when the marker is absent (a transient fetch miss — the remote
+ * shell never ran our printf), telling the caller to retry without advancing.
+ *
+ * Byte-level (not string) is load-bearing: `logChunk.length` is the EXACT number
+ * of log bytes consumed on the wire, which the follow loop adds to its offset. A
+ * string split would first UTF-8-decode, turning any multibyte char split at the
+ * `tail -c` boundary into a U+FFFD whose re-encoded length ≠ the wire bytes,
+ * drifting the offset (see followHostTask). `consumed` is returned explicitly for
+ * clarity; it always equals `logChunk.length`.
+ */
+export function splitProgressBytes(buf, taskId) {
+    const marker = Buffer.from(exitMarker(taskId), 'utf8'); // ASCII-only, unambiguous
+    const idx = buf.lastIndexOf(marker);
+    if (idx === -1)
+        return null;
+    return {
+        logChunk: buf.subarray(0, idx),
+        exit: buf.subarray(idx + marker.length),
+        consumed: idx,
+    };
+}
+/**
+ * One round-trip: new log bytes since `offset`, the sentinel, then the exit
+ * file. Returns null on a transient fetch miss (ssh error / marker absent) so
+ * the caller simply retries next cycle without advancing the offset.
+ *
+ * `remoteLog`/`remoteExit` are $HOME-prefixed paths with safe (hex) basenames —
+ * intentionally unquoted so the remote shell expands $HOME.
+ */
+export function fetchProgress(target, opts) {
+    // Derive the printf format from the SAME exitMarker the parser splits on, so
+    // the emitted sentinel and the one we look for can never desync. The marker's
+    // 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`;
+    // 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 parts = splitProgressBytes(res.stdout, opts.taskId);
+    if (!parts)
+        return null;
+    return { logChunk: parts.logChunk, exit: parts.exit.toString('utf8') };
+}
+/**
+ * File identity (`dev:ino`) of a path on the remote host, or null if it can't be
+ * stat'd. GNU (`-c`) then BSD (`-f`) format, so it works on Linux and macOS hosts.
+ */
+export function readRemoteFileId(target, remotePath) {
+    const res = sshExec(target, `stat -c '%d:%i' ${remotePath} 2>/dev/null || stat -f '%d:%i' ${remotePath} 2>/dev/null`, { timeoutMs: 8000 });
+    const id = res.stdout.trim();
+    return id || null;
+}
+/**
+ * True when the local mirror file IS the very file we're tailing — the
+ * localhost-as-host case, where `remoteLog` ($HOME-expanded) and `localLogPath`
+ * resolve to the same inode. Appending our read bytes back into it would feed the
+ * tail and multiply the log, so the caller must skip the mirror write.
+ */
+export function mirrorAliasesSource(localId, remoteId) {
+    return localId !== null && remoteId !== null && localId === remoteId;
+}
 /** Tail the remote log to stdout until the run finishes; return its exit code. */
 export async function followHostTask(target, opts) {
-    const pollMs = opts.pollMs ?? 1500;
+    const fastMs = opts.pollMs ?? 1500;
+    const maxMs = Math.max(opts.maxPollMs ?? fastMs * 4, 4000);
     const deadline = Date.now() + (opts.timeoutMs ?? 3600_000);
     const local = localLogPath(opts.taskId);
     let offset = 0;
-    const drain = () => {
-        // remoteLog is a $HOME-prefixed path with a safe (hex) basename — intentionally
-        // unquoted so the remote shell expands $HOME.
-        const chunk = sshExec(target, `tail -c +${offset + 1} ${opts.remoteLog} 2>/dev/null`, { timeoutMs: 20000 });
-        if (chunk.stdout) {
-            if (opts.echo)
-                process.stdout.write(chunk.stdout);
+    let waitMs = fastMs;
+    // localhost-as-host guard: when the local mirror and the remote log are the
+    // same physical file, appending our read bytes back would feed the tail and
+    // multiply the log (a plain `--host localhost` follow otherwise tripled it).
+    // Detect via file identity and echo-only in that case.
+    let mirror = true;
+    try {
+        const s = fs.statSync(local);
+        if (mirrorAliasesSource(`${s.dev}:${s.ino}`, readRemoteFileId(target, opts.remoteLog))) {
+            mirror = false;
+        }
+    }
+    catch { /* mirror absent or unstattable → distinct file, keep mirroring */ }
+    const flush = (logChunk) => {
+        if (logChunk.length === 0)
+            return false;
+        if (opts.echo)
+            process.stdout.write(logChunk);
+        if (mirror) {
             try {
-                fs.appendFileSync(local, chunk.stdout);
+                fs.appendFileSync(local, logChunk);
             }
             catch { /* best-effort */ }
-            offset += Buffer.byteLength(chunk.stdout, 'utf8');
         }
+        offset += logChunk.length; // exact wire bytes — no re-encode drift
+        return true;
     };
     for (;;) {
-        drain();
-        const exit = sshExec(target, `cat ${opts.remoteExit} 2>/dev/null`, { timeoutMs: 12000 });
-        if (exit.code === 0 && exit.stdout.trim() !== '') {
-            drain(); // final flush
-            const code = parseInt(exit.stdout.trim(), 10);
+        const r = fetchProgress(target, { remoteLog: opts.remoteLog, remoteExit: opts.remoteExit, taskId: opts.taskId, offset });
+        const gotOutput = r ? flush(r.logChunk) : false;
+        if (r && r.exit.trim() !== '') {
+            // Finished — one final fetch catches bytes written between our tail and
+            // the exit file appearing.
+            const tail = fetchProgress(target, { remoteLog: opts.remoteLog, remoteExit: opts.remoteExit, taskId: opts.taskId, offset });
+            if (tail)
+                flush(tail.logChunk);
+            const code = parseInt(r.exit.trim(), 10);
             return Number.isFinite(code) ? code : 0;
         }
         if (Date.now() > deadline) {
             process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents hosts logs ' + opts.taskId + ' -f\n');
             return -1;
         }
-        await sleep(pollMs);
+        // Fast while output flows; ease toward maxMs when idle so a quiet job isn't
+        // polled needlessly. New output snaps the cadence back to fast.
+        waitMs = gotOutput ? fastMs : Math.min(maxMs, Math.round(waitMs * 1.5));
+        await sleep(waitMs);
     }
 }

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

@@ -8,20 +8,62 @@
 import type { Host } from './types.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
 export declare function localCliVersion(): string | null;
-/** uname over ssh → reachable + OS string. */
-export declare function probeHost(target: string): {
+/** ssh command that confirms reachability and echoes the OS. POSIX boxes answer
+ * `uname -s`; a Windows target has no `uname` (ssh lands in cmd.exe/PowerShell),
+ * so it runs a tiny PowerShell probe. Pure/exported so both branches are
+ * unit-testable without ssh. */
+export declare function buildProbeCommand(os?: string): string;
+/**
+ * Reachability + OS probe over ssh. `os` is the caller's hint (device-registry
+ * 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): {
     reachable: boolean;
     os?: string;
 };
-/** Remote agents-cli version (login shell for PATH), or null if not installed. */
-export declare function remoteAgentsVersion(target: string): string | null;
-/** True if the named agent CLI is installed on the remote (best-effort). */
-export declare function remoteAgentInstalled(target: string, agent: string): boolean;
+/** 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;
+/** 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. */
+export declare function buildBootstrapCommand(spec: string, os?: string): string;
 /** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
-export declare function bootstrapAgentsCli(target: string, version: string | null): {
+export declare function bootstrapAgentsCli(target: string, version: string | null, os?: string): {
     ok: boolean;
     output: string;
 };
+export interface ReadyProbe {
+    /** ssh connected and the remote login shell ran (our sentinel came back). */
+    reachable: boolean;
+    /** Remote agents-cli version (no leading `v`), or null if not installed. */
+    version: string | null;
+    /** Raw `agents view`/`list` output, for installed-agent checks. */
+    view: string;
+}
+/**
+ * Answer every readiness question in ONE ssh round-trip: reachable? (the login
+ * shell ran and echoed our sentinel), agents-cli version, and the installed-agent
+ * listing. This replaces three sequential probes (`true` + `agents --version` +
+ * `agents view`) — 3 handshakes collapse to 1. Reachability keys off the sentinel
+ * rather than the exit code, so a command that ran-but-failed is never mistaken
+ * for a dead connection (only ssh's own failure drops the sentinel).
+ */
+/**
+ * The one-shot readiness command (version + sentinel + agent listing). The
+ * Windows branch emits the sentinel with `Write-Output` and branches on
+ * `$LASTEXITCODE` (no `printf`/`||`); `parseReadyProbe` keys off the sentinel
+ * substring, so the missing leading newline vs the POSIX `printf '\n…'` form is
+ * absorbed by its `.trim()`. Pure/exported so both branches are unit-testable.
+ */
+export declare function buildReadyProbeCommand(os?: string): string;
+export declare function readyProbe(target: string, os?: string): ReadyProbe;
+/** Pure parser for `readyProbe` output (unit-tested without ssh). */
+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;
 export interface EnsureReadyOptions {
     agent: string;
     /** Throw instead of warn when the agent isn't installed remotely. */
@@ -31,6 +73,8 @@ export interface EnsureReadyOptions {
  * 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.
+ *
+ * One ssh round-trip (`readyProbe`) covers all three checks.
  */
 export declare function ensureHostReady(host: Host, opts: EnsureReadyOptions): {
     warnings: string[];

package/dist/lib/hosts/ready.js

@@ -8,8 +8,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { sshExec, sshReachable, shellQuote } from '../ssh-exec.js';
+import { sshExec, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
+import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote } from './remote-cmd.js';
+import { resolveRemoteOsSync } from './remote-os.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
 export function localCliVersion() {
     let dir = path.dirname(fileURLToPath(import.meta.url));
@@ -30,55 +32,126 @@ export function localCliVersion() {
     }
     return null;
 }
-/** uname over ssh → reachable + OS string. */
-export function probeHost(target) {
-    const r = sshExec(target, 'uname -s 2>/dev/null || echo unknown', { timeoutMs: 12000 });
+/** ssh command that confirms reachability and echoes the OS. POSIX boxes answer
+ * `uname -s`; a Windows target has no `uname` (ssh lands in cmd.exe/PowerShell),
+ * so it runs a tiny PowerShell probe. Pure/exported so both branches are
+ * unit-testable without ssh. */
+export function buildProbeCommand(os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return `powershell -NoProfile -EncodedCommand ${encodePowershell('[System.Environment]::OSVersion.Platform.ToString()')}`;
+    }
+    return 'uname -s 2>/dev/null || echo unknown';
+}
+/**
+ * Reachability + OS probe over ssh. `os` is the caller's hint (device-registry
+ * 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 });
     if (r.code !== 0)
         return { reachable: false };
-    const os = r.stdout.trim();
-    return { reachable: true, os: os && os !== 'unknown' ? os : undefined };
+    if (remoteShellFor(os) === 'powershell')
+        return { reachable: true, os };
+    const uname = r.stdout.trim();
+    return { reachable: true, os: uname && uname !== 'unknown' ? uname : undefined };
+}
+/** ssh command that prints the remote agents-cli version. Pure/exported. */
+export function buildRemoteVersionCommand(os) {
+    return remoteShellFor(os) === 'powershell'
+        ? buildWindowsAgentsCommand({ args: ['--version'] })
+        : 'bash -lc "agents --version 2>/dev/null"';
 }
-/** Remote agents-cli version (login shell for PATH), or null if not installed. */
-export function remoteAgentsVersion(target) {
-    const r = sshExec(target, 'bash -lc "agents --version 2>/dev/null"', { timeoutMs: 20000 });
+/** 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 });
     if (r.code !== 0)
         return null;
     const v = r.stdout.trim();
     return v || null;
 }
-/** True if the named agent CLI is installed on the remote (best-effort). */
-export function remoteAgentInstalled(target, agent) {
-    // `agents view` (formerly `agents list`) prints capitalized display names
-    // (e.g. "Claude"), so match case-insensitively.
-    const r = sshExec(target, `bash -lc "agents view 2>/dev/null || agents list 2>/dev/null"`, { timeoutMs: 20000 });
-    if (r.code !== 0)
-        return false;
-    return new RegExp(`\\b${agent}\\b`, 'i').test(r.stdout);
-}
-/** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
-export function bootstrapAgentsCli(target, version) {
-    const spec = version ? `@phnx-labs/agents-cli@${version}` : '@phnx-labs/agents-cli';
+/** 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. */
+export function buildBootstrapCommand(spec, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        const script = `npm install -g ${powershellQuote(spec)} 2>&1 | Select-Object -Last 3; ` +
+            `if (-not (Test-Path "$HOME/.agents/.system")) { agents setup 2>&1 | Select-Object -Last 3 }; ` +
+            `agents --version`;
+        return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
+    }
     const script = `npm install -g ${shellQuote(spec)} 2>&1 | tail -3; ` +
         `if [ ! -d ~/.agents/.system ]; then agents setup 2>&1 | tail -3 || true; fi; ` +
         `agents --version`;
-    const r = sshExec(target, `bash -lc ${shellQuote(script)}`, { timeoutMs: 300000 });
+    return `bash -lc ${shellQuote(script)}`;
+}
+/** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
+export function bootstrapAgentsCli(target, version, os) {
+    const spec = version ? `@phnx-labs/agents-cli@${version}` : '@phnx-labs/agents-cli';
+    const r = sshExec(target, buildBootstrapCommand(spec, os), { timeoutMs: 300000 });
     return { ok: r.code === 0, output: (r.stdout + r.stderr).trim() };
 }
+/** Sentinel splitting the version output from the agent listing in one probe. */
+const READY_MARKER = '@@AGENTS_READY@@';
+/**
+ * Answer every readiness question in ONE ssh round-trip: reachable? (the login
+ * shell ran and echoed our sentinel), agents-cli version, and the installed-agent
+ * listing. This replaces three sequential probes (`true` + `agents --version` +
+ * `agents view`) — 3 handshakes collapse to 1. Reachability keys off the sentinel
+ * rather than the exit code, so a command that ran-but-failed is never mistaken
+ * for a dead connection (only ssh's own failure drops the sentinel).
+ */
+/**
+ * The one-shot readiness command (version + sentinel + agent listing). The
+ * Windows branch emits the sentinel with `Write-Output` and branches on
+ * `$LASTEXITCODE` (no `printf`/`||`); `parseReadyProbe` keys off the sentinel
+ * substring, so the missing leading newline vs the POSIX `printf '\n…'` form is
+ * absorbed by its `.trim()`. Pure/exported so both branches are unit-testable.
+ */
+export function buildReadyProbeCommand(os) {
+    if (remoteShellFor(os) === 'powershell') {
+        const script = `agents --version 2>$null; Write-Output "${READY_MARKER}"; ` +
+            `agents view 2>$null; if ($LASTEXITCODE -ne 0) { agents list 2>$null }`;
+        return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
+    }
+    const script = `agents --version 2>/dev/null; printf '\\n${READY_MARKER}\\n'; ` +
+        `agents view 2>/dev/null || agents list 2>/dev/null`;
+    return `bash -lc ${shellQuote(script)}`;
+}
+export function readyProbe(target, os) {
+    const r = sshExec(target, buildReadyProbeCommand(os), { timeoutMs: 20000 });
+    return parseReadyProbe(r.stdout);
+}
+/** Pure parser for `readyProbe` output (unit-tested without ssh). */
+export function parseReadyProbe(stdout) {
+    const idx = stdout.indexOf(READY_MARKER);
+    if (idx === -1)
+        return { reachable: false, version: null, view: '' };
+    const version = stdout.slice(0, idx).trim().replace(/^v/, '') || null;
+    return { reachable: true, version, view: stdout.slice(idx + READY_MARKER.length) };
+}
+/** True if `view` output lists the named agent (word-boundary, case-insensitive). */
+export function viewHasAgent(view, agent) {
+    return new RegExp(`\\b${agent}\\b`, 'i').test(view);
+}
 /**
  * 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.
+ *
+ * One ssh round-trip (`readyProbe`) covers all three checks.
  */
 export function ensureHostReady(host, opts) {
     const target = sshTargetFor(host);
-    if (!sshReachable(target)) {
+    const probe = readyProbe(target, host.os ?? resolveRemoteOsSync(host.name));
+    if (!probe.reachable) {
         throw new Error(`Host "${host.name}" (${target}) is not reachable over SSH. Check it's online and key auth works.`);
     }
-    if (!remoteAgentsVersion(target)) {
+    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 (!remoteAgentInstalled(target, opts.agent)) {
+    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);