@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/lib/hosts/ready.js

@@ -0,0 +1,88 @@
+/**
+ * Host readiness + bootstrap.
+ *
+ * Before a dispatch we ensure the box is reachable and has agents-cli. Enrollment
+ * can additionally install/upgrade agents-cli to match the local version (version
+ * parity) using the same shape as scripts/sandbox.sh. We never copy `.history`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { sshExec, sshReachable, shellQuote } from '../ssh-exec.js';
+import { sshTargetFor } from './types.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));
+    for (let i = 0; i < 8; i++) {
+        const pkg = path.join(dir, 'package.json');
+        try {
+            const data = JSON.parse(fs.readFileSync(pkg, 'utf-8'));
+            if (data.name && data.version)
+                return data.version;
+        }
+        catch {
+            /* keep walking */
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    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 });
+    if (r.code !== 0)
+        return { reachable: false };
+    const os = r.stdout.trim();
+    return { reachable: true, os: os && os !== 'unknown' ? os : 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 });
+    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';
+    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 { ok: r.code === 0, output: (r.stdout + r.stderr).trim() };
+}
+/**
+ * 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.
+ */
+export function ensureHostReady(host, opts) {
+    const target = sshTargetFor(host);
+    if (!sshReachable(target)) {
+        throw new Error(`Host "${host.name}" (${target}) is not reachable over SSH. Check it's online and key auth works.`);
+    }
+    if (!remoteAgentsVersion(target)) {
+        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)) {
+        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 };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Host provider registry.
+ *
+ * Mirrors the cloud provider registry: a Map of provider id → implementation,
+ * instantiated once. v1 registers only `local`; adding `rush`/`tailscale`/
+ * `crabbox` later is a one-line `providers.set(...)` with no caller changes.
+ */
+import type { Host, HostProvider, HostProviderId } from './types.js';
+export declare function getProvider(id: HostProviderId): HostProvider;
+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).
+ */
+export declare function resolveHost(name: string): Promise<Host | null>;
+/**
+ * Resolve a host by capability tag (e.g. `--host gpu`). Returns the single
+ * matching host, or throws on 0 or >1 matches unless `any` is set (then first).
+ */
+export declare function resolveHostByCap(cap: string, any?: boolean): Promise<Host>;

package/dist/lib/hosts/registry.js

@@ -0,0 +1,65 @@
+/**
+ * Host provider registry.
+ *
+ * Mirrors the cloud provider registry: a Map of provider id → implementation,
+ * instantiated once. v1 registers only `local`; adding `rush`/`tailscale`/
+ * `crabbox` later is a one-line `providers.set(...)` with no caller changes.
+ */
+import { LocalHostProvider } from './providers/local.js';
+const providers = new Map();
+function initProviders() {
+    if (providers.size > 0)
+        return;
+    providers.set('local', new LocalHostProvider());
+}
+export function getProvider(id) {
+    initProviders();
+    const provider = providers.get(id);
+    if (!provider) {
+        throw new Error(`Unknown host provider: ${id}. Available: ${[...providers.keys()].join(', ')}`);
+    }
+    return provider;
+}
+export function getAllProviders() {
+    initProviders();
+    return [...providers.values()];
+}
+/** Every host across all registered providers, deduped by name (first wins). */
+export async function listAllHosts() {
+    const seen = new Set();
+    const out = [];
+    for (const provider of getAllProviders()) {
+        for (const host of await provider.list()) {
+            if (seen.has(host.name))
+                continue;
+            seen.add(host.name);
+            out.push(host);
+        }
+    }
+    return out;
+}
+/**
+ * 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).
+ */
+export async function resolveHost(name) {
+    for (const provider of getAllProviders()) {
+        const host = await provider.resolve(name);
+        if (host)
+            return host;
+    }
+    return null;
+}
+/**
+ * Resolve a host by capability tag (e.g. `--host gpu`). Returns the single
+ * matching host, or throws on 0 or >1 matches unless `any` is set (then first).
+ */
+export async function resolveHostByCap(cap, any = false) {
+    const matches = (await listAllHosts()).filter((h) => h.caps?.includes(cap));
+    if (matches.length === 0)
+        throw new Error(`No host tagged "${cap}". Tag one with: agents hosts add <name> --cap ${cap}`);
+    if (matches.length > 1 && !any) {
+        throw new Error(`Multiple hosts tagged "${cap}": ${matches.map((h) => h.name).join(', ')}. Name one, or pass --any.`);
+    }
+    return matches[0];
+}

package/dist/lib/hosts/ssh-config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Read the user's SSH config as a host directory — we never copy or rewrite it.
+ *
+ * `~/.ssh/config` is the source of truth for connection details; we only parse
+ * `Host` stanzas to list candidate names and `ssh -G <name>` to resolve them for
+ * display. `known_hosts` is a secondary candidate source for enrollment.
+ */
+/**
+ * Parse `Host` stanza names from ssh config text. Wildcard/negated patterns
+ * (`*`, `?`, `!`) are skipped — they're match rules, not concrete hosts.
+ * Pure (text in, names out) so it's unit-testable.
+ */
+export declare function parseSshConfigHosts(content: string): string[];
+/**
+ * Parse hostnames from known_hosts text. Hashed entries (`|1|…`) carry no
+ * recoverable hostname and are skipped; `[host]:port` and comma lists are split.
+ * Pure for testability.
+ */
+export declare function parseKnownHosts(content: string): string[];
+/** `Host` names from ~/.ssh/config, following `Include` globs (best-effort). */
+export declare function listSshConfigHosts(): string[];
+/** Hostnames recorded in ~/.ssh/known_hosts (hashed entries skipped). */
+export declare function listKnownHosts(): string[];
+/** True if `name` is a concrete `Host` stanza in ssh config. */
+export declare function isSshConfigHost(name: string): boolean;
+export interface SshGResult {
+    hostname?: string;
+    user?: string;
+    port?: string;
+}
+/**
+ * Authoritative resolution of a host's effective ssh config via `ssh -G <name>`
+ * (honors Match/Include). Returns undefined if `ssh` is unavailable. Note:
+ * `ssh -G` returns defaults even for unknown names — pair with `isSshConfigHost`
+ * to decide whether a name is actually configured.
+ */
+export declare function sshResolve(name: string): SshGResult | undefined;

package/dist/lib/hosts/ssh-config.js

@@ -0,0 +1,157 @@
+/**
+ * Read the user's SSH config as a host directory — we never copy or rewrite it.
+ *
+ * `~/.ssh/config` is the source of truth for connection details; we only parse
+ * `Host` stanzas to list candidate names and `ssh -G <name>` to resolve them for
+ * display. `known_hosts` is a secondary candidate source for enrollment.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { assertValidSshTarget } from '../ssh-exec.js';
+const SSH_DIR = path.join(os.homedir(), '.ssh');
+const SSH_CONFIG = path.join(SSH_DIR, 'config');
+const KNOWN_HOSTS = path.join(SSH_DIR, 'known_hosts');
+/**
+ * Parse `Host` stanza names from ssh config text. Wildcard/negated patterns
+ * (`*`, `?`, `!`) are skipped — they're match rules, not concrete hosts.
+ * Pure (text in, names out) so it's unit-testable.
+ */
+export function parseSshConfigHosts(content) {
+    const names = [];
+    const seen = new Set();
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const m = /^Host\s+(.+)$/i.exec(line);
+        if (!m)
+            continue;
+        for (const tok of m[1].split(/\s+/)) {
+            if (!tok || /[*?!]/.test(tok))
+                continue;
+            if (seen.has(tok))
+                continue;
+            seen.add(tok);
+            names.push(tok);
+        }
+    }
+    return names;
+}
+/**
+ * Parse hostnames from known_hosts text. Hashed entries (`|1|…`) carry no
+ * recoverable hostname and are skipped; `[host]:port` and comma lists are split.
+ * Pure for testability.
+ */
+export function parseKnownHosts(content) {
+    const names = [];
+    const seen = new Set();
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const first = line.split(/\s+/)[0];
+        if (!first || first.startsWith('|'))
+            continue; // hashed
+        for (const entry of first.split(',')) {
+            // strip [host]:port → host
+            const host = entry.replace(/^\[/, '').replace(/\](:\d+)?$/, '');
+            if (!host || /[*?]/.test(host) || seen.has(host))
+                continue;
+            seen.add(host);
+            names.push(host);
+        }
+    }
+    return names;
+}
+/** `Host` names from ~/.ssh/config, following `Include` globs (best-effort). */
+export function listSshConfigHosts() {
+    const names = new Set();
+    const visit = (file, depth) => {
+        if (depth > 8)
+            return;
+        let content;
+        try {
+            content = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            return;
+        }
+        for (const name of parseSshConfigHosts(content))
+            names.add(name);
+        // Follow Include directives (best-effort, relative to ~/.ssh).
+        for (const rawLine of content.split('\n')) {
+            const m = /^\s*Include\s+(.+)$/i.exec(rawLine);
+            if (!m)
+                continue;
+            for (const pat of m[1].trim().split(/\s+/)) {
+                const abs = path.isAbsolute(pat) ? pat : path.join(SSH_DIR, pat.replace(/^~\//, ''));
+                for (const f of globMaybe(abs))
+                    visit(f, depth + 1);
+            }
+        }
+    };
+    visit(SSH_CONFIG, 0);
+    return [...names];
+}
+/** Minimal glob: expand a single trailing `*` in the basename, else literal. */
+function globMaybe(pattern) {
+    if (!pattern.includes('*')) {
+        return fs.existsSync(pattern) ? [pattern] : [];
+    }
+    const dir = path.dirname(pattern);
+    const base = path.basename(pattern);
+    const re = new RegExp('^' + base.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$');
+    try {
+        return fs.readdirSync(dir).filter((f) => re.test(f)).map((f) => path.join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/** Hostnames recorded in ~/.ssh/known_hosts (hashed entries skipped). */
+export function listKnownHosts() {
+    try {
+        return parseKnownHosts(fs.readFileSync(KNOWN_HOSTS, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+}
+/** True if `name` is a concrete `Host` stanza in ssh config. */
+export function isSshConfigHost(name) {
+    return listSshConfigHosts().includes(name);
+}
+/**
+ * Authoritative resolution of a host's effective ssh config via `ssh -G <name>`
+ * (honors Match/Include). Returns undefined if `ssh` is unavailable. Note:
+ * `ssh -G` returns defaults even for unknown names — pair with `isSshConfigHost`
+ * to decide whether a name is actually configured.
+ */
+export function sshResolve(name) {
+    // Same target-injection guard as sshExec: a name starting with `-` (or
+    // carrying shell metacharacters) must never reach `ssh` as a bare argv where
+    // it could be parsed as a flag (e.g. `-oProxyCommand=…`).
+    try {
+        assertValidSshTarget(name);
+    }
+    catch {
+        return undefined;
+    }
+    const res = spawnSync('ssh', ['-G', name], { encoding: 'utf-8', timeout: 5000 });
+    if (res.status !== 0 || !res.stdout)
+        return undefined;
+    const out = {};
+    for (const line of res.stdout.split('\n')) {
+        const [key, ...rest] = line.trim().split(/\s+/);
+        const val = rest.join(' ');
+        if (key === 'hostname')
+            out.hostname = val;
+        else if (key === 'user')
+            out.user = val;
+        else if (key === 'port')
+            out.port = val;
+    }
+    return out;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Local record of dispatched host tasks.
+ *
+ * Each dispatch writes a `<id>.json` sidecar next to its `<id>.log` (and the
+ * remote's `<id>.exit`) under ~/.agents/.cache/hosts/, so `agents hosts ps/logs`
+ * can list runs and follow output across CLI invocations. (Folding these into
+ * the cloud SQLite store so `agents cloud ps` sees them is a fast-follow — it
+ * needs care around the cloud status-refresh path.)
+ */
+export type HostTaskStatus = 'running' | 'completed' | 'failed' | 'unknown';
+export interface HostTask {
+    id: string;
+    host: string;
+    target: string;
+    agent: string;
+    prompt: string;
+    pid?: number;
+    /** Remote paths (under the host's ~/.agents/.cache/hosts/). */
+    remoteLog: string;
+    remoteExit: string;
+    status: HostTaskStatus;
+    exitCode?: number;
+    createdAt: string;
+    finishedAt?: string;
+}
+export declare function hostsCacheDir(): string;
+/** Local path we mirror a task's remote log into while following. */
+export declare function localLogPath(id: string): string;
+export declare function saveTask(task: HostTask): void;
+export declare function loadTask(id: string): HostTask | null;
+export declare function updateTask(id: string, patch: Partial<HostTask>): HostTask | null;
+export declare function listTasks(): HostTask[];

package/dist/lib/hosts/tasks.js

@@ -0,0 +1,58 @@
+/**
+ * Local record of dispatched host tasks.
+ *
+ * Each dispatch writes a `<id>.json` sidecar next to its `<id>.log` (and the
+ * remote's `<id>.exit`) under ~/.agents/.cache/hosts/, so `agents hosts ps/logs`
+ * can list runs and follow output across CLI invocations. (Folding these into
+ * the cloud SQLite store so `agents cloud ps` sees them is a fast-follow — it
+ * needs care around the cloud status-refresh path.)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+export function hostsCacheDir() {
+    return path.join(getCacheDir(), 'hosts');
+}
+function taskFile(id) {
+    return path.join(hostsCacheDir(), `${id}.json`);
+}
+/** Local path we mirror a task's remote log into while following. */
+export function localLogPath(id) {
+    return path.join(hostsCacheDir(), `${id}.log`);
+}
+export function saveTask(task) {
+    fs.mkdirSync(hostsCacheDir(), { recursive: true });
+    fs.writeFileSync(taskFile(task.id), JSON.stringify(task, null, 2));
+}
+export function loadTask(id) {
+    try {
+        return JSON.parse(fs.readFileSync(taskFile(id), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function updateTask(id, patch) {
+    const task = loadTask(id);
+    if (!task)
+        return null;
+    const next = { ...task, ...patch };
+    saveTask(next);
+    return next;
+}
+export function listTasks() {
+    let files;
+    try {
+        files = fs.readdirSync(hostsCacheDir()).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const tasks = [];
+    for (const f of files) {
+        const task = loadTask(f.replace(/\.json$/, ''));
+        if (task)
+            tasks.push(task);
+    }
+    return tasks.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Agent-host provider contract.
+ *
+ * A `HostProvider` answers "what are my hosts, and how do I reach them?" — the
+ * pluggable directory/metadata/reachability layer. v1 ships only the `local`
+ * provider (ssh-config ∪ inline registry); `rush`/`tailscale`/`crabbox` are
+ * additive fast-follows behind this same contract. Capability-gated so partial
+ * providers are first-class (mirrors the cloud provider registry).
+ */
+import type { HostEntry } from '../types.js';
+export type HostProviderId = 'local';
+export type HostStatus = 'online' | 'offline' | 'unknown';
+/** A host as seen at runtime: its persisted entry plus name/provider/status. */
+export interface Host extends HostEntry {
+    name: string;
+    provider: HostProviderId;
+    /** True when the host has an explicit overlay/inline entry in the registry. */
+    enrolled?: boolean;
+    status?: HostStatus;
+}
+export interface HostProviderCapabilities {
+    /** Can list/track hosts. */
+    directory: boolean;
+    /** Can add/remove hosts. */
+    mutate: boolean;
+    /** Reports online/offline without an explicit probe. */
+    presence: boolean;
+    /** Can dispatch a command without an SSH address (its own relay). */
+    relay: boolean;
+    /** Can provision new hosts. */
+    lease: boolean;
+}
+export interface HostProvider {
+    id: HostProviderId;
+    capabilities(): HostProviderCapabilities;
+    /** Every host this provider knows about. */
+    list(): Promise<Host[]>;
+    /** Resolve one host by name, or null if unknown to this provider. */
+    resolve(name: string): Promise<Host | null>;
+    /** Persist a host (mutate-capable providers only). */
+    register?(spec: Host): Promise<Host>;
+    /** Remove a host (mutate-capable providers only). */
+    remove?(name: string): Promise<void>;
+    /** Presence without an explicit probe (presence-capable providers only). */
+    presence?(name: string): Promise<HostStatus>;
+}
+/**
+ * The ssh target string for a host: the bare name for ssh-config hosts (ssh
+ * resolves HostName/User/Port/Identity), else `user@address` (or `address`).
+ */
+export declare function sshTargetFor(host: Host): string;

package/dist/lib/hosts/types.js

@@ -0,0 +1,21 @@
+/**
+ * Agent-host provider contract.
+ *
+ * A `HostProvider` answers "what are my hosts, and how do I reach them?" — the
+ * pluggable directory/metadata/reachability layer. v1 ships only the `local`
+ * provider (ssh-config ∪ inline registry); `rush`/`tailscale`/`crabbox` are
+ * additive fast-follows behind this same contract. Capability-gated so partial
+ * providers are first-class (mirrors the cloud provider registry).
+ */
+/**
+ * The ssh target string for a host: the bare name for ssh-config hosts (ssh
+ * resolves HostName/User/Port/Identity), else `user@address` (or `address`).
+ */
+export function sshTargetFor(host) {
+    if (host.source === 'ssh-config')
+        return host.name;
+    if (!host.address) {
+        throw new Error(`Host "${host.name}" is inline but has no address.`);
+    }
+    return host.user ? `${host.user}@${host.address}` : host.address;
+}

package/dist/lib/loop.d.ts

@@ -104,6 +104,15 @@ export declare function loopSignalPath(runDir: string): string;
  * agent both recalls the prior turn AND knows what to do this iteration.
  */
 export declare function buildLoopContinuePrompt(prevSessionId: string, entrypoint: string): string;
+/**
+ * The universal (Tier-2) resume directive: a `/continue <id>` first message that
+ * tells the agent to load the prior transcript via `agents sessions <id>` and
+ * pick up. Works for ANY agent that ships the `/continue` command — the resume
+ * path for agents without a native `--resume` (gemini, grok, opencode, …). An
+ * optional follow-on prompt is appended after a blank line; omitted when empty so
+ * a bare resume sends just the directive.
+ */
+export declare function buildContinuePrompt(sessionId: string, prompt?: string): string;
 /**
  * Resolve a loop interval string to milliseconds. `"0"` is an explicit
  * back-to-back run (0ms). Any other string must parse via parseTimeout

package/dist/lib/loop.js

@@ -49,7 +49,19 @@ export function loopSignalPath(runDir) {
  * agent both recalls the prior turn AND knows what to do this iteration.
  */
 export function buildLoopContinuePrompt(prevSessionId, entrypoint) {
-    return `/continue ${prevSessionId}\n\n${entrypoint}`;
+    return buildContinuePrompt(prevSessionId, entrypoint);
+}
+/**
+ * The universal (Tier-2) resume directive: a `/continue <id>` first message that
+ * tells the agent to load the prior transcript via `agents sessions <id>` and
+ * pick up. Works for ANY agent that ships the `/continue` command — the resume
+ * path for agents without a native `--resume` (gemini, grok, opencode, …). An
+ * optional follow-on prompt is appended after a blank line; omitted when empty so
+ * a bare resume sends just the directive.
+ */
+export function buildContinuePrompt(sessionId, prompt) {
+    const directive = `/continue ${sessionId}`;
+    return prompt && prompt.trim() ? `${directive}\n\n${prompt}` : directive;
 }
 /**
  * Resolve a loop interval string to milliseconds. `"0"` is an explicit

package/dist/lib/mcp.js

@@ -13,6 +13,7 @@ import * as yaml from 'yaml';
 import { execFileSync } from 'child_process';
 import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir } from './state.js';
 import { getBinaryPath, getVersionHomePath } from './versions.js';
+import { IS_WINDOWS, needsWindowsShell } from './platform/index.js';
 import { AGENTS } from './agents.js';
 import { isCapable } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
@@ -217,6 +218,7 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
+            shell: needsWindowsShell(binaryPath),
         });
     }
     else {
@@ -225,6 +227,7 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
+            shell: needsWindowsShell(binaryPath),
         });
     }
 }
@@ -245,6 +248,7 @@ function installMcpViaCodex(binaryPath, server, versionHome) {
             stdio: 'pipe',
             timeout: 30000,
             env: { ...process.env, HOME: versionHome },
+            shell: needsWindowsShell(binaryPath),
         });
     }
     // Note: Codex may not support HTTP MCPs
@@ -274,7 +278,7 @@ function registerMcpCommand(agentId, name, commandSpec, scope, transport, option
             ? ['mcp', 'add', '--transport', transport, '--scope', scope, name, '--', ...commandArgs]
             : ['mcp', 'add', name, '--', ...commandArgs];
         const env = options.home ? { ...process.env, HOME: options.home } : process.env;
-        execFileSync(bin, args, { stdio: 'pipe', timeout: 30000, env });
+        execFileSync(bin, args, { stdio: 'pipe', timeout: 30000, env, shell: needsWindowsShell(bin) });
         return { success: true };
     }
     catch (err) {
@@ -442,9 +446,14 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
     }
     const applied = [];
     const errors = [];
-    // Get binary path for CLI-based agents
+    // Get binary path for CLI-based agents. On Windows npm drops a `.cmd` launcher
+    // next to the extensionless POSIX wrapper in node_modules/.bin; prefer it so
+    // the CLI is actually executable (the bare wrapper is a shell script).
     const cliCommand = AGENTS[agentId].cliCommand;
-    const binaryPath = path.join(getVersionsDir(), agentId, version, 'node_modules', '.bin', cliCommand);
+    let binaryPath = path.join(getVersionsDir(), agentId, version, 'node_modules', '.bin', cliCommand);
+    if (IS_WINDOWS && fs.existsSync(binaryPath + '.cmd')) {
+        binaryPath += '.cmd';
+    }
     for (const server of servers) {
         try {
             if (agentId === 'claude') {