@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/hooks.js

@@ -68,11 +68,15 @@ function getManagedHookPrefixes() {
  * absolute Windows paths break in bash because backslashes are stripped as
  * escape characters, whereas ~/... paths expand correctly via the ~/.claude
  * symlink/junction on both platforms.
+ *
+ * `home` and `sep` are injectable so the Windows behavior (backslash sep,
+ * drive-letter home) is unit-testable on a POSIX CI host — pass sep='\\' to
+ * simulate Windows. With the defaults this is byte-identical to reading
+ * os.homedir()/path.sep at the call site.
  */
-function toPortableCommand(absPath) {
-    const home = os.homedir();
-    const normalized = absPath.split(path.sep).join('/');
-    const homeNorm = home.split(path.sep).join('/');
+export function toPortableCommand(absPath, home = os.homedir(), sep = path.sep) {
+    const normalized = absPath.split(sep).join('/');
+    const homeNorm = home.split(sep).join('/');
     if (normalized.startsWith(homeNorm + '/')) {
         return '~/' + normalized.slice(homeNorm.length + 1);
     }
@@ -113,8 +117,38 @@ function isManagedHookCommand(command, prefixes) {
     }
     return false;
 }
+/**
+ * Per-version-home command detection. Sync copies each hook script into the
+ * active version's home and registers the command by that version-scoped path
+ * (`~/.agents/.history/versions/<agent>/<version>/home/…`). Because the path
+ * embeds the version number, a later version's sync appends a fresh set whose
+ * paths never string-match (and thus never prune) the prior version's entries —
+ * so entries for every version installed over time pile up in one settings
+ * file, and once a version is removed its entries become dead hooks that error
+ * on every tool call. `versionHomeIdentity` extracts the `<agent>/<version>` a
+ * command (or home path) belongs to so stale sibling-version entries can be
+ * pruned. Returns null for any path outside a per-version home (system hooks,
+ * the user's own custom hooks) — those are never a prune target.
+ */
+const VERSION_HOME_SEGMENT_RE = /\.history\/versions\/([^/]+)\/([^/]+)\/home(?:\/|$)/;
+function versionHomeIdentity(commandOrPath) {
+    const norm = commandOrPath.split(/[\\/]/).join('/');
+    const m = VERSION_HOME_SEGMENT_RE.exec(norm);
+    return m ? { agent: m[1], version: m[2] } : null;
+}
+/**
+ * True when `command` points into a DIFFERENT version home of the same agent as
+ * `current` — i.e. a stale entry left behind by an earlier version's sync.
+ * Non-version-home commands (system + user-custom hooks) always return false.
+ */
+function isStaleSiblingVersionCommand(command, current) {
+    if (!current)
+        return false;
+    const id = versionHomeIdentity(command);
+    return id !== null && id.agent === current.agent && id.version !== current.version;
+}
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
-import { generateHookShim, parseCacheConfig, removeHookShim } from './hooks/cache.js';
+import { generateHookShim, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
 /**
  * Resolve the command path to register for a hook.
@@ -128,6 +162,8 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     const scriptPath = resolveScript(hookDef.script);
     if (!scriptPath)
         return null;
+    if (!isValidHookShimName(name))
+        return null;
     const cache = parseCacheConfig(hookDef.cache);
     if (!cache) {
         // No caching opted in — make sure a previously generated shim from an
@@ -715,6 +751,24 @@ export function parseHookManifest(opts = {}) {
         }
         catch { /* skip unreadable manifest */ }
     }
+    // Extra-repo layer: hooks: section of each enabled extra repo's agents.yaml.
+    // Sits above system but below user, mirroring resolveHookScriptPath's
+    // first-found order (user > extra > system). Without this layer the script
+    // path of an extra-repo hook resolves but its events never register (#602).
+    // Earlier extras win over later ones, so iterate in reverse: the last write
+    // for a given name comes from the earliest-registered repo.
+    for (const { dir } of [...getEnabledExtraRepos()].reverse()) {
+        const extraMetaPath = path.join(dir, 'agents.yaml');
+        if (!fs.existsSync(extraMetaPath))
+            continue;
+        try {
+            const meta = yaml.parse(fs.readFileSync(extraMetaPath, 'utf-8'));
+            if (meta?.hooks)
+                for (const [name, def] of Object.entries(meta.hooks))
+                    merged[name] = def;
+        }
+        catch { /* skip unreadable extra-repo manifest */ }
+    }
     // User layer: hooks: section of agents.yaml.
     const userMetaPath = path.join(getUserAgentsDir(), 'agents.yaml');
     if (fs.existsSync(userMetaPath)) {
@@ -989,15 +1043,21 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
         if (resolved)
             currentManifestPaths.add(resolved);
     }
-    // Remove stale entries: any hook command under a managed root that isn't
-    // in the current manifest is a leftover from a renamed/deleted hook script.
+    // Identity of the version home being synced. Used to prune entries that point
+    // at a DIFFERENT version home of the same agent (see isStaleSiblingVersionCommand).
+    const currentVh = versionHomeIdentity(versionHome);
+    // Remove stale entries: any hook command under a managed root that isn't in
+    // the current manifest is a leftover from a renamed/deleted hook script; any
+    // command pointing at a sibling version's home is a leftover from that
+    // version's sync (its version-scoped path never matches the current set).
     for (const eventEntries of Object.values(hooks)) {
         if (!Array.isArray(eventEntries))
             continue;
         for (const group of eventEntries) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
+            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+                !isStaleSiblingVersionCommand(h.command, currentVh));
         }
     }
     // Remove empty matcher groups left after cleanup
@@ -1049,6 +1109,65 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     }
     return { registered, errors };
 }
+/**
+ * Prune every Claude-family (`settings.json`) hook entry whose command lives
+ * under a removed version's home
+ * (`~/.agents/.history/versions/<agent>/<removedVersion>/home/…`).
+ *
+ * `agents remove <agent>@<version>` soft-deletes the version's files but leaves
+ * the hook entries other version homes registered against it — dead hooks that
+ * error on every tool call ("No such file or directory") until the next sync.
+ * This clears them from a remaining version's settings immediately. Only the
+ * removed version's entries are touched; the current version's entries, system
+ * hooks, and the user's own custom hooks are left intact. Returns the number of
+ * entries removed.
+ */
+export function pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, removedVersion) {
+    if (!fs.existsSync(settingsPath))
+        return 0;
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    }
+    catch {
+        return 0;
+    }
+    if (!config.hooks || typeof config.hooks !== 'object')
+        return 0;
+    const hooks = config.hooks;
+    let removed = 0;
+    for (const eventEntries of Object.values(hooks)) {
+        if (!Array.isArray(eventEntries))
+            continue;
+        for (const group of eventEntries) {
+            if (!group.hooks)
+                continue;
+            const before = group.hooks.length;
+            group.hooks = group.hooks.filter((h) => {
+                const id = versionHomeIdentity(h.command);
+                return !(id !== null && id.agent === agent && id.version === removedVersion);
+            });
+            removed += before - group.hooks.length;
+        }
+    }
+    if (removed === 0)
+        return 0;
+    // Drop matcher groups left empty by the prune.
+    for (const [event, eventEntries] of Object.entries(hooks)) {
+        if (!Array.isArray(eventEntries))
+            continue;
+        hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
+    }
+    try {
+        fs.writeFileSync(settingsPath, JSON.stringify(config, null, 2), 'utf-8');
+    }
+    catch {
+        // Best-effort cleanup: a write failure leaves the dead entry to be pruned
+        // on the next sync (see isStaleSiblingVersionCommand).
+        return 0;
+    }
+    return removed;
+}
 function registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];

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

@@ -21,10 +21,25 @@ export interface DispatchOptions {
     mode?: string;
     model?: string;
     remoteCwd?: string;
+    /**
+     * Force the remote run's NEW session to use this exact id (Claude only, via
+     * `agents run --session-id`). Captured on the task record so the run is
+     * resumable by id. Mutually exclusive with `resume`.
+     */
+    sessionId?: string;
+    /** Resume an existing session on the host by id (via `agents run --resume`). */
+    resume?: string;
     /** Stream progress and block until completion (default true). */
     follow?: boolean;
     timeoutMs?: number;
 }
+/**
+ * Build the remote `agents run …` argv for a host dispatch. Pure so the
+ * session-id / resume flag wiring is unit-testable without an SSH round-trip.
+ * `--session-id` and `--resume` are mutually exclusive (the CLI rejects both);
+ * resume wins when — defensively — both are set.
+ */
+export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;
 export interface CommandDispatchOptions {

package/dist/lib/hosts/dispatch.js

@@ -12,6 +12,8 @@ import { randomUUID } from 'crypto';
 import { sshExec, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
+import { remoteShellFor } from './remote-cmd.js';
+import { resolveRemoteOsSync } from './remote-os.js';
 import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
@@ -22,8 +24,22 @@ const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
  * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
  * 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.
  */
 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 id = randomUUID().slice(0, 8);
     const remoteLog = `${REMOTE_DIR}/${id}.log`;
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
@@ -45,6 +61,7 @@ async function launchDetached(host, target, opts) {
         agent: opts.agentLabel,
         prompt: opts.promptLabel,
         pid: Number.isFinite(pid) ? pid : undefined,
+        sessionId: opts.sessionId,
         remoteLog,
         remoteExit,
         status: 'running',
@@ -67,24 +84,40 @@ async function launchDetached(host, target, opts) {
     const finished = exitCode === -1 ? task : (updateTask(id, terminalPatch(exitCode)) ?? task);
     return { task: finished, exitCode };
 }
+/**
+ * Build the remote `agents run …` argv for a host dispatch. Pure so the
+ * session-id / resume flag wiring is unit-testable without an SSH round-trip.
+ * `--session-id` and `--resume` are mutually exclusive (the CLI rejects both);
+ * resume wins when — defensively — both are set.
+ */
+export function buildRunForwardedArgs(opts) {
+    const args = ['run', opts.agent, opts.prompt, '--quiet'];
+    if (opts.mode)
+        args.push('--mode', opts.mode);
+    if (opts.model)
+        args.push('--model', opts.model);
+    if (opts.resume)
+        args.push('--resume', opts.resume);
+    else if (opts.sessionId)
+        args.push('--session-id', opts.sessionId);
+    return args;
+}
 /** 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 });
     for (const w of warnings)
         process.stderr.write(`[hosts] warning: ${w}\n`);
-    const forwardedArgs = ['run', opts.agent, opts.prompt, '--quiet'];
-    if (opts.mode)
-        forwardedArgs.push('--mode', opts.mode);
-    if (opts.model)
-        forwardedArgs.push('--model', opts.model);
     return launchDetached(host, target, {
-        forwardedArgs,
+        forwardedArgs: buildRunForwardedArgs(opts),
         remoteCwd: opts.remoteCwd,
         follow: opts.follow,
         timeoutMs: opts.timeoutMs,
         agentLabel: opts.agent,
         promptLabel: opts.prompt,
+        // On resume the remote session keeps its existing id; record that id so the
+        // task stays mapped to the same session.
+        sessionId: opts.resume ?? opts.sessionId,
     });
 }
 /**

package/dist/lib/hosts/logs.js

@@ -11,6 +11,7 @@ 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);
@@ -39,7 +40,35 @@ export async function showHostTaskLog(id, follow) {
         process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
     }
     catch {
-        console.log(chalk.gray('(no local log captured for this task)'));
+        // 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/ready.d.ts

@@ -8,15 +8,30 @@
 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;
+/** 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;
 };
@@ -36,7 +51,15 @@ export interface ReadyProbe {
  * 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).
  */
-export declare function readyProbe(target: string): ReadyProbe;
+/**
+ * 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). */

package/dist/lib/hosts/ready.js

@@ -10,6 +10,8 @@ import * as path from 'path';
 import { fileURLToPath } from 'url';
 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,29 +32,63 @@ 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 };
 }
-/** 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 });
+/** 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 (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;
 }
-/** 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. */
@@ -65,10 +101,25 @@ const READY_MARKER = '@@AGENTS_READY@@';
  * 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).
  */
-export function readyProbe(target) {
+/**
+ * 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`;
-    const r = sshExec(target, `bash -lc ${shellQuote(script)}`, { timeoutMs: 20000 });
+    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). */
@@ -92,7 +143,7 @@ export function viewHasAgent(view, agent) {
  */
 export function ensureHostReady(host, opts) {
     const target = sshTargetFor(host);
-    const probe = readyProbe(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.`);
     }

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

@@ -11,8 +11,25 @@ export declare function getAllProviders(): HostProvider[];
 /** Every host across all registered providers, deduped by name (first wins). */
 export declare function listAllHosts(): Promise<Host[]>;
 /**
- * Resolve a host name to a single host across providers, or null if unknown.
- * First provider that owns the name wins (only `local` in v1).
+ * Thrown when a device resolves but can't be used as an offload target because
+ * it authenticates with a password. The offload path runs over `sshExec`, whose
+ * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
+ * auth can carry a `--host` run. Named so the top-level catch prints the message
+ * cleanly instead of a stack trace.
+ */
+export declare class DeviceOffloadUnsupportedError extends Error {
+    constructor(name: string);
+}
+/**
+ * Resolve a host name to a single host, or null if unknown. Resolution order:
+ *   1. host providers — the `agents hosts` registry (agents.yaml overlay + ssh-config)
+ *   2. the devices registry (`agents devices`) — a machine registered once with
+ *      `agents devices sync` is reachable by `--host`/`--device` with no second enroll
+ *   3. an ad-hoc `user@host` (must contain `@`, validated) — nothing to register
+ *
+ * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`)
+ * stays reachable: `--host gpu` must fall through to a cap lookup, not be misread
+ * as an ad-hoc target.
  */
 export declare function resolveHost(name: string): Promise<Host | null>;
 /**