@phnx-labs/agents-cli 1.20.67 → 1.20.69

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/devices/terminfo.d.ts

@@ -0,0 +1,44 @@
+import { type DeviceProfile } from './registry.js';
+/**
+ * Decide whether an interactive login warrants a terminfo push. Pure so the
+ * gating logic is unit-testable without touching ssh or the filesystem.
+ *
+ * @param interactive true only for a real login (no remote command) on a human tty.
+ */
+export declare function shouldSyncTerminfo(params: {
+    term?: string;
+    shell: DeviceProfile['shell'];
+    interactive: boolean;
+}): boolean;
+/**
+ * Cache key for a device: the remote **user@host**, not just the host. terminfo
+ * is compiled into the *per-user* `~/.terminfo`, so `alice@box` and `bob@box`
+ * are distinct sync targets — keying on host alone would let the first user's
+ * stamp suppress the second user's (never-installed) sync. Mirrors
+ * {@link sshTargetFor}'s user handling; falls back to the device name when the
+ * address is unresolved.
+ */
+export declare function terminfoHostKey(device: Pick<DeviceProfile, 'user' | 'name'>, addr: string | undefined): string;
+/** True when a fresh successful-sync stamp exists for this host+TERM. */
+export declare function terminfoSynced(host: string, term: string, cacheRoot?: string): boolean;
+/** Record a successful sync so repeat logins skip the push. Best-effort. */
+export declare function markTerminfoSynced(host: string, term: string, cacheRoot?: string): void;
+/** Export the local terminfo source for a TERM, or null if it can't be produced. */
+export declare function localTerminfoSource(term: string): string | null;
+/**
+ * Best-effort: ensure `device` has the terminfo entry for the local `$TERM`
+ * before an interactive login. Never throws; returns whether a push succeeded
+ * (false when skipped, already-cached, or failed). `sshArgs`/`sshEnv` are the
+ * SAME host-key + auth options the real login uses, minus the interactive tty —
+ * so a password-auth device resolves through the askpass shim without a second
+ * human prompt.
+ */
+export declare function syncTerminfoToDevice(opts: {
+    device: DeviceProfile;
+    host: string;
+    term: string | undefined;
+    /** ssh argv for a non-interactive `tic -x -` exec against this device. */
+    sshArgs: string[];
+    /** Env overlay for that ssh (askpass wiring for password devices). */
+    sshEnv: Record<string, string>;
+}): boolean;

package/dist/lib/devices/terminfo.js

@@ -0,0 +1,167 @@
+/**
+ * Terminfo propagation for `agents ssh` interactive logins.
+ *
+ * Modern terminals (Ghostty, kitty, Alacritty, WezTerm, foot, rio) advertise a
+ * custom `TERM` (e.g. `xterm-ghostty`) whose terminfo entry ships with the
+ * terminal, not with the remote host's ncurses. SSH into a box that lacks the
+ * entry and the session is subtly broken: wrong backspace, missing colors, a
+ * garbled clear/alt-screen. Ghostty's own shell integration fixes this for the
+ * bare `ssh` command, but `agents ssh` (Tailscale-relayed, spawned directly)
+ * bypasses that wrapper — so we handle it here.
+ *
+ * Strategy: on an interactive POSIX login, if the local `$TERM` is one the
+ * remote is unlikely to have, export it locally (`infocmp -x`) and compile it on
+ * the remote (`tic -x -`, writes to the user's `~/.terminfo`, no sudo). This is
+ * the canonical, terminal-agnostic technique.
+ *
+ * Two invariants keep it safe and cheap:
+ *  - **Fail-safe.** Every failure is swallowed. A push that errors, times out,
+ *    or hits a remote without `tic` leaves the user exactly where they are today
+ *    — it never blocks or delays the actual login beyond the short push timeout.
+ *  - **Cached.** A successful sync stamps a local marker keyed by host+TERM, so
+ *    only the first login to each host pays the one extra round-trip; every
+ *    repeat login is zero-cost.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+/**
+ * Terminfo names that ncurses ships essentially everywhere, so pushing them is
+ * wasted work. Anything NOT in this set (the exotic terminal entries) is a sync
+ * candidate. Kept deliberately conservative: when unsure, we push — `tic` is
+ * idempotent and the result is cached.
+ */
+const UNIVERSAL_TERMS = new Set([
+    'dumb',
+    'ansi',
+    'vt100',
+    'vt102',
+    'vt220',
+    'linux',
+    'cygwin',
+    'xterm',
+    'xterm-color',
+    'xterm-16color',
+    'xterm-256color',
+    'screen',
+    'screen-256color',
+    'tmux',
+    'tmux-256color',
+    'rxvt',
+    'rxvt-unicode',
+    'rxvt-unicode-256color',
+]);
+/** How long a successful sync suppresses re-syncing the same host+TERM. */
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/** Cap on the push so a stalled remote can't delay the login indefinitely. */
+const PUSH_TIMEOUT_MS = 8000;
+/**
+ * Decide whether an interactive login warrants a terminfo push. Pure so the
+ * gating logic is unit-testable without touching ssh or the filesystem.
+ *
+ * @param interactive true only for a real login (no remote command) on a human tty.
+ */
+export function shouldSyncTerminfo(params) {
+    if (!params.interactive)
+        return false;
+    if (params.shell === 'powershell')
+        return false; // Windows console ignores terminfo
+    const term = params.term?.trim();
+    if (!term)
+        return false;
+    if (UNIVERSAL_TERMS.has(term))
+        return false;
+    return true;
+}
+/**
+ * Cache key for a device: the remote **user@host**, not just the host. terminfo
+ * is compiled into the *per-user* `~/.terminfo`, so `alice@box` and `bob@box`
+ * are distinct sync targets — keying on host alone would let the first user's
+ * stamp suppress the second user's (never-installed) sync. Mirrors
+ * {@link sshTargetFor}'s user handling; falls back to the device name when the
+ * address is unresolved.
+ */
+export function terminfoHostKey(device, addr) {
+    const host = addr ?? device.name;
+    return device.user ? `${device.user}@${host}` : host;
+}
+/** Directory holding per-host+TERM sync stamps. `cacheRoot` override is for tests. */
+function stampDir(cacheRoot) {
+    return path.join(cacheRoot ?? getCacheDir(), 'devices', 'terminfo');
+}
+/** Filesystem-safe stamp name for a host+TERM pair. */
+function stampFile(host, term, cacheRoot) {
+    const safe = `${host}__${term}`.replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(stampDir(cacheRoot), safe);
+}
+/** True when a fresh successful-sync stamp exists for this host+TERM. */
+export function terminfoSynced(host, term, cacheRoot) {
+    try {
+        const st = fs.statSync(stampFile(host, term, cacheRoot));
+        return Date.now() - st.mtimeMs < CACHE_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/** Record a successful sync so repeat logins skip the push. Best-effort. */
+export function markTerminfoSynced(host, term, cacheRoot) {
+    try {
+        fs.mkdirSync(stampDir(cacheRoot), { recursive: true });
+        fs.writeFileSync(stampFile(host, term, cacheRoot), `${new Date().toISOString()}\n`);
+    }
+    catch {
+        /* a cache write failure just means we re-sync next time — never fatal */
+    }
+}
+/** Export the local terminfo source for a TERM, or null if it can't be produced. */
+export function localTerminfoSource(term) {
+    try {
+        const res = spawnSync('infocmp', ['-x', term], {
+            encoding: 'utf8',
+            timeout: 4000,
+        });
+        if (res.status === 0 && res.stdout && res.stdout.trim().length > 0) {
+            return res.stdout;
+        }
+    }
+    catch {
+        /* infocmp missing or errored — nothing we can push */
+    }
+    return null;
+}
+/**
+ * Best-effort: ensure `device` has the terminfo entry for the local `$TERM`
+ * before an interactive login. Never throws; returns whether a push succeeded
+ * (false when skipped, already-cached, or failed). `sshArgs`/`sshEnv` are the
+ * SAME host-key + auth options the real login uses, minus the interactive tty —
+ * so a password-auth device resolves through the askpass shim without a second
+ * human prompt.
+ */
+export function syncTerminfoToDevice(opts) {
+    const term = opts.term?.trim();
+    if (!term)
+        return false;
+    if (terminfoSynced(opts.host, term))
+        return false;
+    const source = localTerminfoSource(term);
+    if (!source)
+        return false;
+    try {
+        const res = spawnSync('ssh', opts.sshArgs, {
+            input: source,
+            env: { ...process.env, ...opts.sshEnv },
+            timeout: PUSH_TIMEOUT_MS,
+            stdio: ['pipe', 'ignore', 'ignore'],
+        });
+        if (res.status === 0) {
+            markTerminfoSynced(opts.host, term);
+            return true;
+        }
+    }
+    catch {
+        /* connection failed / timed out — fail-safe, login proceeds unaffected */
+    }
+    return false;
+}

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)}`;
     }