@phnx-labs/agents-cli 1.20.67 → 1.20.68

package/dist/lib/devices/fleet.js

@@ -42,6 +42,18 @@ export function planFleetTargets(reg) {
         return { device };
     });
 }
+/**
+ * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
+ * `check --devices`): every planned device except this machine and control-only
+ * cockpits. A control device never runs agents (mirrors doctor's fan-out, which
+ * drops it via `isControlDevice`), so counting it as unreachable/drift would make
+ * the CI gate fail on every run for a fleet that merely has a cockpit registered.
+ * Offline / no-address devices are kept — those are genuine faults a gate should
+ * surface — so their `skip` reason still flows through as an `unreachable` row.
+ */
+export function remoteFleetTargets(planned, self) {
+    return planned.filter((t) => t.device.name !== self && t.skip !== 'control');
+}
 /** Human label for a skip reason. */
 export function skipLabel(reason) {
     switch (reason) {
@@ -135,3 +147,29 @@ export function runFleet(targets, cmd, runner = runOnDevice) {
     }
     return results;
 }
+/** Run one async probe per device in parallel, preserving input order. */
+export async function fanOutDevices(targets, probe) {
+    return Promise.all(targets.map(async (target) => {
+        if (target.skip) {
+            return {
+                name: target.name,
+                status: 'skipped',
+                reason: target.skip,
+            };
+        }
+        try {
+            return {
+                name: target.name,
+                status: 'ok',
+                value: await probe(target),
+            };
+        }
+        catch (err) {
+            return {
+                name: target.name,
+                status: 'failed',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }));
+}

package/dist/lib/devices/health-report.d.ts

@@ -0,0 +1,46 @@
+import { type DeviceStats } from './health.js';
+export interface FleetCliStatus {
+    installed: boolean;
+    path: string | null;
+    error: string | null;
+}
+export interface FleetSyncStatus {
+    agent: string;
+    version: string;
+    status: 'fresh' | 'stale' | 'never-synced';
+    isDefault: boolean;
+    divergence?: string[];
+}
+export interface FleetOrphanStatus {
+    agent: string;
+    version: string;
+    commands: number;
+    skills: number;
+    hooks: number;
+}
+export interface FleetHealthRow {
+    name: string;
+    platform?: string;
+    version?: string | null;
+    stats?: DeviceStats;
+    error?: string;
+    skipped?: string;
+    clis: Record<string, FleetCliStatus>;
+    sync: FleetSyncStatus[];
+    orphans: FleetOrphanStatus[];
+}
+export interface FleetWarning {
+    kind: 'unreachable' | 'drift' | 'cli' | 'version-skew';
+    devices: string[];
+    message: string;
+}
+export interface FleetHealthReport {
+    generatedAt: string;
+    devices: FleetHealthRow[];
+    warnings: FleetWarning[];
+    hasWarnings: boolean;
+    hasDrift: boolean;
+}
+export declare function buildFleetHealthReport(rows: FleetHealthRow[], now?: Date): FleetHealthReport;
+export declare function renderFleetWarnings(report: FleetHealthReport): string[];
+export declare function renderFleetMatrix(report: FleetHealthReport): string[];

package/dist/lib/devices/health-report.js

@@ -0,0 +1,159 @@
+import chalk from 'chalk';
+import { padToWidth, terminalWidth, truncateToWidth } from '../session/width.js';
+import { fmtBytes, headroom } from './health.js';
+function driftRows(row) {
+    return row.sync.filter((s) => s.status !== 'fresh');
+}
+function installedCliCount(row) {
+    const statuses = Object.values(row.clis);
+    return {
+        installed: statuses.filter((s) => s.installed).length,
+        total: statuses.length,
+    };
+}
+export function buildFleetHealthReport(rows, now = new Date()) {
+    const warnings = [];
+    const unreachable = rows
+        .filter((r) => r.error || r.skipped)
+        .map((r) => r.name);
+    if (unreachable.length > 0) {
+        warnings.push({
+            kind: 'unreachable',
+            devices: unreachable,
+            message: `${unreachable.length} device${unreachable.length === 1 ? '' : 's'} unreachable or skipped`,
+        });
+    }
+    const drifted = rows.filter((r) => driftRows(r).length > 0).map((r) => r.name);
+    if (drifted.length > 0) {
+        warnings.push({
+            kind: 'drift',
+            devices: drifted,
+            message: `${drifted.length} device${drifted.length === 1 ? '' : 's'} have sync drift`,
+        });
+    }
+    const cliIssues = rows
+        .filter((r) => {
+        const counts = installedCliCount(r);
+        return counts.total > 0 && counts.installed < counts.total;
+    })
+        .map((r) => r.name);
+    if (cliIssues.length > 0) {
+        warnings.push({
+            kind: 'cli',
+            devices: cliIssues,
+            message: `${cliIssues.length} device${cliIssues.length === 1 ? ' is' : 's are'} missing one or more agent CLIs`,
+        });
+    }
+    const versions = new Map();
+    for (const row of rows) {
+        if (!row.version)
+            continue;
+        const list = versions.get(row.version) ?? [];
+        list.push(row.name);
+        versions.set(row.version, list);
+    }
+    if (versions.size > 1) {
+        warnings.push({
+            kind: 'version-skew',
+            devices: rows.filter((r) => r.version).map((r) => r.name),
+            message: `agents-cli version skew: ${Array.from(versions.keys()).sort().join(', ')}`,
+        });
+    }
+    return {
+        generatedAt: now.toISOString(),
+        devices: rows,
+        warnings,
+        hasWarnings: warnings.length > 0,
+        hasDrift: drifted.length > 0 || unreachable.length > 0,
+    };
+}
+function statusGlyph(row) {
+    if (row.error || row.skipped)
+        return chalk.red('○');
+    if (driftRows(row).length > 0)
+        return chalk.yellow('◐');
+    return chalk.green('●');
+}
+function headroomLabel(row) {
+    const h = headroom(row.stats);
+    switch (h) {
+        case 'idle':
+            return chalk.green('idle');
+        case 'light':
+            return chalk.green('light');
+        case 'busy':
+            return chalk.yellow('busy');
+        case 'loaded':
+            return chalk.red('loaded');
+        case 'unknown':
+            return chalk.gray('unknown');
+    }
+}
+function driftLabel(row) {
+    if (row.error)
+        return chalk.red('probe failed');
+    if (row.skipped)
+        return chalk.gray(row.skipped);
+    const drift = driftRows(row);
+    if (drift.length === 0)
+        return chalk.green('fresh');
+    const stale = drift.filter((r) => r.status === 'stale').length;
+    const cold = drift.filter((r) => r.status === 'never-synced').length;
+    const parts = [];
+    if (stale)
+        parts.push(`${stale} stale`);
+    if (cold)
+        parts.push(`${cold} cold`);
+    return chalk.yellow(parts.join(' · '));
+}
+function cliLabel(row) {
+    if (row.error || row.skipped)
+        return chalk.gray('-');
+    const { installed, total } = installedCliCount(row);
+    if (total === 0)
+        return chalk.gray('none');
+    return installed === total ? chalk.green(`${installed}/${total}`) : chalk.yellow(`${installed}/${total}`);
+}
+function loadLabel(stats) {
+    if (!stats?.reachable)
+        return chalk.gray('-');
+    const load = stats.loadPercent === undefined ? '-' : `${Math.round(stats.loadPercent)}%`;
+    const mem = stats.memPercent === undefined ? '-' : `${Math.round(stats.memPercent)}%`;
+    return `${load}/${mem}`;
+}
+export function renderFleetWarnings(report) {
+    if (report.warnings.length === 0)
+        return [chalk.green('Fleet warnings: none')];
+    return [
+        chalk.bold(`Fleet warnings (${report.warnings.length})`),
+        ...report.warnings.map((w) => `  ${chalk.yellow(w.kind.padEnd(12))} ${w.message} ${chalk.gray(`(${w.devices.join(', ')})`)}`),
+    ];
+}
+export function renderFleetMatrix(report) {
+    if (report.devices.length === 0)
+        return [chalk.gray('No registered devices. Run `agents devices` to register some.')];
+    const nameW = Math.min(22, Math.max(6, ...report.devices.map((r) => r.name.length)));
+    const versionW = Math.min(14, Math.max(7, ...report.devices.map((r) => (r.version ?? '-').length)));
+    const width = terminalWidth();
+    // 4 = leading "  " + the per-row status glyph + its trailing space (rows prefix
+    // `  ${statusGlyph} `; the header reserves the same 4 cols so every column lines up).
+    const fixed = 4 + nameW + 2 + 8 + 2 + 9 + 2 + 9 + 2 + versionW + 2 + 9 + 2 + 9;
+    const noteW = Math.max(12, width - fixed);
+    const lines = [
+        chalk.bold('Fleet status'),
+        chalk.gray(`    ${padToWidth('Device', nameW)}  ${padToWidth('OS', 8)}  ${padToWidth('Health', 9)}  ${padToWidth('Sync', 9)}  ${padToWidth('CLI', 9)}  ${padToWidth('Version', versionW)}  ${padToWidth('Load/Mem', 9)}  Note`),
+    ];
+    for (const row of report.devices) {
+        const note = row.error ?? row.skipped ?? (row.orphans.length > 0 ? `${row.orphans.length} orphaned version${row.orphans.length === 1 ? '' : 's'}` : '');
+        lines.push(`  ${statusGlyph(row)} ${padToWidth(truncateToWidth(row.name, nameW), nameW)}  ` +
+            `${padToWidth(truncateToWidth(row.platform ?? '-', 8), 8)}  ` +
+            `${padToWidth(headroomLabel(row), 9)}  ` +
+            `${padToWidth(driftLabel(row), 9)}  ` +
+            `${padToWidth(cliLabel(row), 9)}  ` +
+            `${padToWidth(truncateToWidth(row.version ?? '-', versionW), versionW)}  ` +
+            `${padToWidth(loadLabel(row.stats), 9)}  ` +
+            chalk.gray(truncateToWidth(note || `free ${fmtBytes(row.stats?.memFreeBytes)}`, noteW)));
+    }
+    lines.push(chalk.gray('  ● fresh · ◐ drift · ○ unreachable/skipped'));
+    return lines;
+}

package/dist/lib/devices/health.d.ts

@@ -2,9 +2,10 @@
  * Device resource probing for `agents devices list`.
  *
  * One SSH round-trip per device gathers load average, memory pressure, and core
- * count (mac + linux), parsed into a {@link DeviceStats}. Probes run in parallel
- * with a bounded timeout so the list stays responsive — a slow or hung box
- * degrades to "no stats" instead of blocking the whole table.
+ * count (mac + linux via a POSIX snippet, windows via a CIM one-liner), parsed
+ * into a {@link DeviceStats}. Probes run in parallel with a bounded timeout so
+ * the list stays responsive — a slow or hung box degrades to "no stats" instead
+ * of blocking the whole table.
  *
  * The parsers are pure and unit-tested (health.test.ts). They mirror the ones in
  * the Factory extension (apps/factory/src/core/deviceHealth.ts) — kept as a
@@ -14,12 +15,17 @@ import type { DeviceProfile } from './registry.js';
 /** Default per-device probe budget. Short enough that the list never hangs on a
  * wedged box, long enough for a cold relayed SSH handshake. */
 export declare const PROBE_TIMEOUT_MS = 2500;
+/** Windows probe budget. The first CIM query of a PowerShell session pays a
+ * "Preparing modules for first use" cost on top of PowerShell startup, which
+ * routinely blows the 2.5s POSIX budget on a relayed connection. */
+export declare const WIN_PROBE_TIMEOUT_MS = 6000;
 export interface DeviceStats {
     host: string;
     reachable: boolean;
     loadAvg1?: number;
     ncpu?: number;
-    /** loadAvg1 / ncpu * 100 — load normalized to core count (the "has room" number). */
+    /** Load normalized to core count (the "has room" number): loadAvg1 / ncpu *
+     * 100 on mac/linux, CPU utilization % directly on windows (no loadAvg1). */
     loadPercent?: number;
     memPercent?: number;
     memTotalBytes?: number;
@@ -43,6 +49,10 @@ export declare function parseNcpu(out: string): {
 };
 /** Assemble a DeviceStats from the three snippet sections. */
 export declare function parseProbeOutput(host: string, stdout: string, fetchedAt: number): DeviceStats;
+/** Assemble a DeviceStats from the windows one-liner. A missing marker line
+ * (e.g. CIM unavailable) keeps `reachable: true` — ssh answered — with no
+ * numbers, mirroring how garbage POSIX output degrades. */
+export declare function parseWinProbeOutput(host: string, stdout: string, fetchedAt: number): DeviceStats;
 export interface FleetCapacity {
     reachable: number;
     cores: number;

package/dist/lib/devices/health.js

@@ -2,9 +2,10 @@
  * Device resource probing for `agents devices list`.
  *
  * One SSH round-trip per device gathers load average, memory pressure, and core
- * count (mac + linux), parsed into a {@link DeviceStats}. Probes run in parallel
- * with a bounded timeout so the list stays responsive — a slow or hung box
- * degrades to "no stats" instead of blocking the whole table.
+ * count (mac + linux via a POSIX snippet, windows via a CIM one-liner), parsed
+ * into a {@link DeviceStats}. Probes run in parallel with a bounded timeout so
+ * the list stays responsive — a slow or hung box degrades to "no stats" instead
+ * of blocking the whole table.
  *
  * The parsers are pure and unit-tested (health.test.ts). They mirror the ones in
  * the Factory extension (apps/factory/src/core/deviceHealth.ts) — kept as a
@@ -15,10 +16,21 @@ import { buildSshInvocation, writeAskpassShim } from './connect.js';
 /** Default per-device probe budget. Short enough that the list never hangs on a
  * wedged box, long enough for a cold relayed SSH handshake. */
 export const PROBE_TIMEOUT_MS = 2_500;
+/** Windows probe budget. The first CIM query of a PowerShell session pays a
+ * "Preparing modules for first use" cost on top of PowerShell startup, which
+ * routinely blows the 2.5s POSIX budget on a relayed connection. */
+export const WIN_PROBE_TIMEOUT_MS = 6_000;
 const SEP = '---AGSTAT---';
 /** One-shot remote snapshot: load, then memory (mac vm_stat else linux
  * meminfo), then core count (linux nproc else mac hw.ncpu). */
 const PROBE_SNIPPET = `uptime; echo ${SEP}; (vm_stat 2>/dev/null || cat /proc/meminfo 2>/dev/null); echo ${SEP}; (nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null)`;
+/** Windows equivalent, one labeled line via CIM. PowerShell 5.1-safe: no `||`
+ * chaining, plain string concatenation. `LoadPercentage` is $null on some
+ * hosts/VMs, which concatenates to an empty field — the parser treats that as
+ * "no load signal" and headroom falls back to memory pressure alone.
+ * wrapRemoteCommand base64-encodes this for powershell-shell devices, so the
+ * quoting survives ssh intact. */
+const WIN_PROBE_SNIPPET = `$os = Get-CimInstance Win32_OperatingSystem; $cpu = (Get-CimInstance Win32_Processor | Measure-Object -Property LoadPercentage -Average).Average; Write-Output ('AGWINSTAT load=' + $cpu + ' freeKb=' + $os.FreePhysicalMemory + ' totalKb=' + $os.TotalVisibleMemorySize + ' ncpu=' + $env:NUMBER_OF_PROCESSORS)`;
 /** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
 export function fmtBytes(bytes) {
     if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
@@ -106,6 +118,28 @@ export function parseProbeOutput(host, stdout, fetchedAt) {
         fetchedAt,
     };
 }
+/** Assemble a DeviceStats from the windows one-liner. A missing marker line
+ * (e.g. CIM unavailable) keeps `reachable: true` — ssh answered — with no
+ * numbers, mirroring how garbage POSIX output degrades. */
+export function parseWinProbeOutput(host, stdout, fetchedAt) {
+    const m = stdout.match(/AGWINSTAT load=([0-9.]*) freeKb=([0-9]+) totalKb=([0-9]+) ncpu=([0-9]+)/);
+    if (!m)
+        return { host, reachable: true, fetchedAt };
+    const loadPercent = m[1] === '' ? undefined : parseFloat(m[1]);
+    const freeKb = parseInt(m[2], 10);
+    const totalKb = parseInt(m[3], 10);
+    const ncpu = parseInt(m[4], 10);
+    return {
+        host,
+        reachable: true,
+        ncpu: Number.isFinite(ncpu) && ncpu > 0 ? ncpu : undefined,
+        loadPercent: loadPercent !== undefined && Number.isFinite(loadPercent) ? loadPercent : undefined,
+        memPercent: totalKb > 0 ? Math.max(0, Math.min(100, ((totalKb - freeKb) / totalKb) * 100)) : undefined,
+        memTotalBytes: totalKb > 0 ? totalKb * 1024 : undefined,
+        memFreeBytes: totalKb > 0 ? freeKb * 1024 : undefined,
+        fetchedAt,
+    };
+}
 /** Sum cores and memory across reachable devices for the summary footer. */
 export function fleetCapacity(statsList) {
     const cap = { reachable: 0, cores: 0, memTotalBytes: 0, memFreeBytes: 0 };
@@ -139,6 +173,7 @@ export function headroom(stats) {
 export function probeDeviceStats(device, opts = {}) {
     const host = device.name;
     const fetchedAt = opts.now ?? Date.now();
+    const isWin = device.shell === 'powershell';
     let args;
     let env;
     try {
@@ -146,16 +181,21 @@ export function probeDeviceStats(device, opts = {}) {
         // buildSshInvocation joins the cmd with spaces and hands the string to the
         // remote login shell, which evaluates the snippet's `;`/`||` directly — no
         // `sh -c` wrapper needed (and a wrapper would only re-quote the first token).
-        ({ args, env } = buildSshInvocation(device, [PROBE_SNIPPET], shim));
+        // For powershell devices it base64-encodes the snippet instead.
+        ({ args, env } = buildSshInvocation(device, [isWin ? WIN_PROBE_SNIPPET : PROBE_SNIPPET], shim));
     }
     catch {
         return Promise.resolve({ host, reachable: false, fetchedAt });
     }
     return new Promise((resolve) => {
-        execFile('ssh', args, { encoding: 'utf-8', env: { ...process.env, ...env }, timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS }, (err, stdout) => {
+        execFile('ssh', args, {
+            encoding: 'utf-8',
+            env: { ...process.env, ...env },
+            timeout: opts.timeoutMs ?? (isWin ? WIN_PROBE_TIMEOUT_MS : PROBE_TIMEOUT_MS),
+        }, (err, stdout) => {
             if (err || !stdout)
                 return resolve({ host, reachable: false, fetchedAt });
-            resolve(parseProbeOutput(host, stdout, fetchedAt));
+            resolve(isWin ? parseWinProbeOutput(host, stdout, fetchedAt) : parseProbeOutput(host, stdout, fetchedAt));
         });
     });
 }
@@ -164,11 +204,12 @@ export function probeDeviceStats(device, opts = {}) {
  * from itself. */
 export function probeLocalStats(host, opts = {}) {
     const fetchedAt = opts.now ?? Date.now();
+    const isWin = process.platform === 'win32';
     return new Promise((resolve) => {
-        execFile('sh', ['-c', PROBE_SNIPPET], { encoding: 'utf-8', timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS }, (err, stdout) => {
+        execFile(isWin ? 'powershell' : 'sh', isWin ? ['-NoProfile', '-Command', WIN_PROBE_SNIPPET] : ['-c', PROBE_SNIPPET], { encoding: 'utf-8', timeout: opts.timeoutMs ?? (isWin ? WIN_PROBE_TIMEOUT_MS : PROBE_TIMEOUT_MS) }, (err, stdout) => {
             if (err || !stdout)
                 return resolve({ host, reachable: false, fetchedAt });
-            resolve(parseProbeOutput(host, stdout, fetchedAt));
+            resolve(isWin ? parseWinProbeOutput(host, stdout, fetchedAt) : parseProbeOutput(host, stdout, fetchedAt));
         });
     });
 }

package/dist/lib/git.d.ts

@@ -95,6 +95,16 @@ export declare function getGitHubUsername(): Promise<string | null>;
  * Get the remote URL for origin in a git repo.
  */
 export declare function getRemoteUrl(repoPath: string): Promise<string | null>;
+/**
+ * Canonical `host/owner/repo` form of a git remote, transport-agnostic, so the
+ * same repo cloned over SSH vs HTTPS compares equal. Strips protocol, any
+ * `user@`, a trailing `.git`, and folds the scp-style `host:owner/repo` colon to
+ * a slash. Lower-cased. Used to decide whether an existing checkout is "the same
+ * repo" as a requested source before adopting it.
+ */
+export declare function canonicalGitRemote(url: string): string;
+/** True when two git remote URLs point at the same repo across transport forms. */
+export declare function sameGitRemote(a: string | null | undefined, b: string | null | undefined): boolean;
 /**
  * Set the remote URL for origin in a git repo.
  */

package/dist/lib/git.js

@@ -365,6 +365,29 @@ export async function getRemoteUrl(repoPath) {
         return null;
     }
 }
+/**
+ * Canonical `host/owner/repo` form of a git remote, transport-agnostic, so the
+ * same repo cloned over SSH vs HTTPS compares equal. Strips protocol, any
+ * `user@`, a trailing `.git`, and folds the scp-style `host:owner/repo` colon to
+ * a slash. Lower-cased. Used to decide whether an existing checkout is "the same
+ * repo" as a requested source before adopting it.
+ */
+export function canonicalGitRemote(url) {
+    return url
+        .trim()
+        .replace(/\/+$/, '') // trailing slashes first, so a trailing-slash-after-.git still strips
+        .replace(/\.git$/i, '')
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, '') // strip scheme (https://, ssh://, git://)
+        .replace(/^[^@/]+@/, '') // strip user@ (git@, ssh user)
+        .replace(':', '/') // scp-style host:owner/repo → host/owner/repo (first colon only)
+        .toLowerCase();
+}
+/** True when two git remote URLs point at the same repo across transport forms. */
+export function sameGitRemote(a, b) {
+    if (!a || !b)
+        return false;
+    return canonicalGitRemote(a) === canonicalGitRemote(b);
+}
 /**
  * Set the remote URL for origin in a git repo.
  */

package/dist/lib/hosts/option.js

@@ -14,7 +14,7 @@ export function addHostOption(cmd) {
     return cmd
         .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('--device <name>', 'Alias of --host: run this command on a registered device (from `agents devices`).')
-        .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
+        .option('--remote-cwd <dir>', "Working directory on the host for --host runs. Resolves on the REMOTE host — pass a '$HOME'-relative path (single-quoted so your local shell doesn't expand it) or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you). No effect on 'teams add'.")
         .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/ready.js

@@ -10,7 +10,7 @@ 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 { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } 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() {
@@ -75,7 +75,8 @@ export function remoteAgentsVersion(target, os) {
  * 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; ` +
+        const script = `${POWERSHELL_PROGRESS_SILENCE}; ` +
+            `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)}`;
@@ -110,7 +111,8 @@ const READY_MARKER = '@@AGENTS_READY@@';
  */
 export function buildReadyProbeCommand(os) {
     if (remoteShellFor(os) === 'powershell') {
-        const script = `agents --version 2>$null; Write-Output "${READY_MARKER}"; ` +
+        const script = `${POWERSHELL_PROGRESS_SILENCE}; ` +
+            `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)}`;
     }

package/dist/lib/hosts/remote-cmd.d.ts

@@ -117,6 +117,18 @@ export interface WindowsAgentsCommand {
  * `& agents …` invokes the CLI from the machine PATH (Windows has no login
  * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
  */
+/**
+ * PowerShell prelude that silences the progress stream. PowerShell 5.1 serializes
+ * progress records ("Preparing modules for first use.") to CLIXML when stderr is a
+ * redirected pipe (an ssh capture, not a console), so a remote `agents …` result
+ * otherwise comes back wrapped in a raw `#< CLIXML <Objs …>` blob — unreadable to
+ * humans and to the JSON parsers that consume doctor / fleet-status output. Prepend
+ * this to EVERY Windows script that invokes `agents` (there is more than one builder
+ * in this file). Verified against a live win-mini (PowerShell 5.1): this clears it.
+ * (`-OutputFormat Text` does NOT — it governs success-stream object serialization,
+ * not the progress stream.)
+ */
+export declare const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'SilentlyContinue'";
 export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
 /**
  * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a

package/dist/lib/hosts/remote-cmd.js

@@ -110,6 +110,7 @@ export const RUN_OPTION_FORWARDING = {
     lease: 'local-only',
     keepBox: 'local-only',
     copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
+    authCheck: 'local-only', // --no-auth-check gates the local interactive login preflight; --host runs skip that preflight entirely
 };
 /** Actionable messages for value-aware rejections, keyed by attribute name. */
 export const RUN_OPTION_REJECT_MESSAGES = {
@@ -190,9 +191,21 @@ export function decodePowershell(encoded) {
  * `& agents …` invokes the CLI from the machine PATH (Windows has no login
  * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
  */
+/**
+ * PowerShell prelude that silences the progress stream. PowerShell 5.1 serializes
+ * progress records ("Preparing modules for first use.") to CLIXML when stderr is a
+ * redirected pipe (an ssh capture, not a console), so a remote `agents …` result
+ * otherwise comes back wrapped in a raw `#< CLIXML <Objs …>` blob — unreadable to
+ * humans and to the JSON parsers that consume doctor / fleet-status output. Prepend
+ * this to EVERY Windows script that invokes `agents` (there is more than one builder
+ * in this file). Verified against a live win-mini (PowerShell 5.1): this clears it.
+ * (`-OutputFormat Text` does NOT — it governs success-stream object serialization,
+ * not the progress stream.)
+ */
+export const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'SilentlyContinue'";
 export function windowsAgentsScript(cmd) {
     const { args, env, cwd, propagateExit = true } = cmd;
-    const parts = [];
+    const parts = [POWERSHELL_PROGRESS_SILENCE];
     if (env)
         for (const [k, v] of Object.entries(env))
             parts.push(`$env:${k} = ${powershellQuote(v)}`);
@@ -232,6 +245,9 @@ export function buildWindowsStdinImportCommand(bundle, opts = {}) {
     // the secret-bearing temp file would otherwise be left behind (RUSH-1764). $tmp
     // starts null so a GetTempFileName that itself throws leaves nothing to remove.
     const script = [
+        // Same CLIXML guard as windowsAgentsScript — this builder also runs `& agents …`
+        // and its raw stderr is printed to the user on failure (secrets export --host <win>).
+        POWERSHELL_PROGRESS_SILENCE,
         '$in = [Console]::In.ReadToEnd()',
         '$tmp = $null',
         `try { $tmp = [System.IO.Path]::GetTempFileName(); [System.IO.File]::WriteAllText($tmp, $in); ` +

package/dist/lib/mcp.d.ts

@@ -108,6 +108,27 @@ export declare function registerMcpCommandToTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string, commandSpec: McpCommandSpec, scope?: 'user' | 'project', transport?: string): Promise<McpTargetOperationResult[]>;
+/**
+ * MCP server shaped for direct config-file serialization.
+ */
+export interface WritableMcpServer {
+    name: string;
+    transport: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Serialize MCP servers into an agent-specific config file.
+ *
+ * `mode: 'overwrite'` replaces the whole MCP section (used for tool-managed
+ * version-home configs). `mode: 'merge'` updates/adds the provided server
+ * entries while preserving existing entries (used for project-level configs
+ * that users may hand-edit or populate via agent CLI commands).
+ */
+export declare function writeMcpConfig(agentId: AgentId, configPath: string, servers: WritableMcpServer[], mode?: 'overwrite' | 'merge'): void;
 /**
  * Install MCP servers to an agent.
  * For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)