@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -32,24 +32,10 @@ export interface FleetHealthRow {
     clis: Record<string, FleetCliStatus>;
     sync: FleetSyncStatus[];
     orphans: FleetOrphanStatus[];
-    /** Cached auth-health rollup for this host (the Auth column). Undefined when
-     *  the host has never been probed (`agents fleet ping`) or the cache is cold. */
     auth?: HostAuthSummary;
-    /** Resolved online/offline verdict (from {@link deviceOnlineState}). Populated
-     *  by `runFleetStatus` for the summary view; undefined in the raw grid. */
     online?: OnlineState;
-    /** When this box was last seen reachable (ISO), for the "last seen …" note on
-     *  an offline row. Sourced from the registry's tailscale snapshot / reachability
-     *  verdict. Undefined when never recorded. */
     lastSeen?: string;
-    /** This host's self-reported harness inventory (resources / agent versions /
-     *  repo state) from its `doctor --json` `fleet` field, for cross-device
-     *  divergence detection (RUSH-2027). Undefined for an unreachable box or an
-     *  older CLI that doesn't emit it. */
     inventory?: FleetInventory;
-    /** This host's live agent workload (running-agent count + per-context / per-
-     *  agent breakdown), from the fleet-status mirror / read-union (RUSH-2061).
-     *  Undefined when no row has been published for the host yet. */
     agents?: FleetAgentCounts;
 }
 interface FleetWarning {
@@ -69,39 +55,16 @@ export declare function buildFleetHealthReport(rows: FleetHealthRow[], now?: Dat
 }): FleetHealthReport;
 export declare function renderFleetWarnings(report: FleetHealthReport): string[];
 export declare function renderFleetMatrix(report: FleetHealthReport): string[];
-/**
- * "as of …" line so cache-served output is honest about age and points at the
- * refresh flag. Stats age comes from `stats.fetchedAt`, auth age from the
- * cached rollup's `oldestCheckedAt`; either may be absent. Returns null when the
- * table carries no timestamped data at all (nothing to date).
- */
 export declare function freshnessFooter(rows: FleetHealthRow[], now?: number): string | null;
-/** Collapse a long dev build (`0.0.0-dev.<sha>[-dirty]`) to `dev`/`dev-dirty`;
- *  released semver is shown verbatim. Keeps the version column narrow and stops
- *  a single dev box from widening every row. */
 export declare function shortVersion(version: string | null | undefined): string;
-/** OS bucket label for grouping. Anything unrecognized falls under "Other". */
 export declare function platformGroupLabel(platform: string | undefined): 'macOS' | 'Linux' | 'Windows' | 'Other';
 interface FleetAttentionItem {
-    /** Leading mark: `○` offline, `⚠` config/CLI/version issue. */
     glyph: 'offline' | 'warn';
     subject: string;
     detail: string;
-    /** The exact command (or instruction) that fixes it. */
     fix: string;
 }
-/**
- * The actionable problems only — each with the command that fixes it. Order:
- * offline boxes, CLI gaps, active-version config drift, then version skew.
- * A healthy fleet returns `[]` (the caller prints an all-clear line).
- */
 export declare function buildFleetAttentionItems(report: FleetHealthReport, now?: number): FleetAttentionItem[];
-/**
- * The default `agents fleet status` view (RUSH-1966): a one-line rollup, a
- * NEEDS ATTENTION list of only the actionable problems (each with its fix
- * command), quiet per-device rows grouped by OS, and an honest footer. The full
- * auth/CLI/sync grid moves behind `--verbose` ({@link renderFleetMatrix}).
- */
 export declare function renderFleetSummary(report: FleetHealthReport, opts?: {
     self?: string;
     now?: number;

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

@@ -61,11 +61,6 @@ export function buildFleetHealthReport(rows, now = new Date(), opts = {}) {
             message: `agents-cli version skew: ${Array.from(versions.keys()).sort().join(', ')}`,
         });
     }
-    // Cross-device harness divergence (RUSH-2027): compare every device's
-    // self-reported inventory against the local baseline and roll the findings up
-    // into one warning per affected device. Only runs when a baseline (`self`) is
-    // named and at least one device carries an inventory — an older-CLI fleet with
-    // no `fleet` field simply produces no divergence warning.
     if (opts.self && rows.some((r) => r.inventory)) {
         const divergence = compareFleetInventories(rows.map((r) => ({ name: r.name, inventory: r.inventory ?? null })), opts.self);
         const byDevice = new Map();
@@ -142,16 +137,6 @@ function loadLabel(stats) {
     const mem = stats.memPercent === undefined ? '-' : `${Math.round(stats.memPercent)}%`;
     return `${load}/${mem}`;
 }
-/**
- * Compact per-host auth cell. Four buckets, deliberately distinct so the column
- * doesn't cry wolf on healthy accounts:
- *   `●{live}`     green  — live-verified
- *   `·{present}`  gray   — signed in but no live probe (codex/grok/…): benign
- *   `◐{degraded}` yellow — soft/self-healing (expired/limited/error)
- *   `○{revoked}`  red    — server rejected the token: re-login now
- * A host with no cached auth rows shows "—"; an unreachable/skipped row shows
- * "-" like the other probe columns.
- */
 function authLabel(row) {
     if (row.error || row.skipped)
         return chalk.gray('-');
@@ -167,11 +152,8 @@ function authLabel(row) {
         parts.push(chalk.yellow(`◐${s.degraded}`));
     if (s.revoked > 0)
         parts.push(chalk.red(`○${s.revoked}`));
-    // All-zero can't happen (total > 0); but if only present/degraded exist we
-    // still lead with them — never show an empty cell for a probed host.
     return parts.length > 0 ? parts.join(' ') : chalk.gray('—');
 }
-/** Oldest epoch-ms timestamp across rows for a field, or null when none present. */
 function oldestAcross(rows, pick) {
     let oldest = null;
     for (const row of rows) {
@@ -196,14 +178,8 @@ export function renderFleetMatrix(report) {
         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)));
-    // Auth cells are variable-length (up to four space-separated buckets, e.g.
-    // `●2 ·3 ◐1 ○1`); size the column to the widest so a mixed-auth row can't
-    // overflow the fixed slot and shove every later column out of alignment.
     const authW = Math.max(9, ...report.devices.map((r) => stringWidth(authLabel(r))));
     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).
-    // Columns: Device, OS(8), Health(9), Sync(9), CLI(9), Auth(authW), Version, Load/Mem(9), then Note.
     const fixed = 4 + nameW + 2 + 8 + 2 + 9 + 2 + 9 + 2 + 9 + 2 + authW + 2 + versionW + 2 + 9;
     const noteW = Math.max(12, width - fixed);
     const lines = [
@@ -228,12 +204,6 @@ export function renderFleetMatrix(report) {
         lines.push(chalk.gray(foot));
     return lines;
 }
-/**
- * "as of …" line so cache-served output is honest about age and points at the
- * refresh flag. Stats age comes from `stats.fetchedAt`, auth age from the
- * cached rollup's `oldestCheckedAt`; either may be absent. Returns null when the
- * table carries no timestamped data at all (nothing to date).
- */
 export function freshnessFooter(rows, now = Date.now()) {
     const oldestStats = oldestAcross(rows, (r) => r.stats?.fetchedAt);
     const oldestAuth = oldestAcross(rows, (r) => r.auth?.oldestCheckedAt);
@@ -246,13 +216,6 @@ export function freshnessFooter(rows, now = Date.now()) {
         return null;
     return `  updated ${parts.join(' · ')} — pass --refresh (--live) for a live probe`;
 }
-// ---------------------------------------------------------------------------
-// Summary view (default): rollup + NEEDS ATTENTION + OS groups + footer.
-// The full grid above is kept for `--verbose`. (RUSH-1966)
-// ---------------------------------------------------------------------------
-/** Collapse a long dev build (`0.0.0-dev.<sha>[-dirty]`) to `dev`/`dev-dirty`;
- *  released semver is shown verbatim. Keeps the version column narrow and stops
- *  a single dev box from widening every row. */
 export function shortVersion(version) {
     if (!version)
         return '—';
@@ -261,7 +224,6 @@ export function shortVersion(version) {
         return /dirty/.test(version) ? 'dev-dirty' : 'dev';
     return version;
 }
-/** OS bucket label for grouping. Anything unrecognized falls under "Other". */
 export function platformGroupLabel(platform) {
     const p = (platform ?? '').toLowerCase();
     if (p === 'macos' || p === 'darwin')
@@ -273,50 +235,29 @@ export function platformGroupLabel(platform) {
     return 'Other';
 }
 const GROUP_ORDER = ['macOS', 'Linux', 'Windows', 'Other'];
-/** Non-fresh sync rows for the ACTIVE (default) version only — the drift that a
- *  running install actually feels, not stale/cold counts across old orphans. */
 function activeDriftRows(row) {
     return row.sync.filter((s) => s.isDefault && s.status !== 'fresh');
 }
 function isOffline(row) {
-    // Prefer the resolved verdict; fall back to a probe error/skip when the caller
-    // didn't populate it (e.g. a raw report). Only a positive 'online' is "up".
     if (row.online)
         return row.online !== 'online';
     return Boolean(row.error || row.skipped);
 }
-/** A box with a real offline verdict — as opposed to `unknown` (registered but
- *  never addressed/probed). Only a genuine offline is a "check the box" item;
- *  an unknown box is unconfigured, not down. */
 function isGenuinelyOffline(row) {
     return row.online === 'offline' || (!row.online && Boolean(row.error || row.skipped));
 }
-/** A CLI count is only worth flagging when it's stark — the box is missing more
- *  than two-thirds of the known agent CLIs (e.g. 1/9), which signals a
- *  broken/half-set-up box. A normal partial install (a box that just doesn't run
- *  every agent) is not a problem, so this deliberately does NOT fire at 4/9 or
- *  6/9. The full count stays visible under `--verbose`. */
 function starkCliGap(row) {
     const { installed, total } = installedCliCount(row);
     return total > 0 && installed * 3 < total ? { installed, total } : null;
 }
-/**
- * The actionable problems only — each with the command that fixes it. Order:
- * offline boxes, CLI gaps, active-version config drift, then version skew.
- * A healthy fleet returns `[]` (the caller prints an all-clear line).
- */
 export function buildFleetAttentionItems(report, now = Date.now()) {
     const items = [];
-    // 1) Genuinely-offline boxes (not `unknown`/unconfigured), each individually.
     for (const row of report.devices) {
         if (!isGenuinelyOffline(row))
             continue;
         const seen = row.lastSeen ? ` · last seen ${formatCheckedAge(Date.parse(row.lastSeen), now)}` : '';
         items.push({ glyph: 'offline', subject: row.name, detail: `offline${seen}`, fix: 'check the box' });
     }
-    // 2) Boxes that need `agents fleet apply` — merge config drift and a stark CLI gap
-    // into ONE item per box (both are fixed by the same command, so don't
-    // double-list). An offline box's config/CLI is unknowable, so skip it.
     for (const row of report.devices) {
         if (isOffline(row))
             continue;
@@ -330,7 +271,6 @@ export function buildFleetAttentionItems(report, now = Date.now()) {
             items.push({ glyph: 'warn', subject: row.name, detail: reasons.join(' · '), fix: `agents fleet apply --device ${row.name}` });
         }
     }
-    // 3) Version skew across the fleet — one line.
     const skew = report.warnings.find((w) => w.kind === 'version-skew');
     if (skew) {
         const counts = new Map();
@@ -346,7 +286,6 @@ export function buildFleetAttentionItems(report, now = Date.now()) {
             .join(' · ');
         items.push({ glyph: 'warn', subject: 'version skew', detail: summary, fix: 'agents upgrade --fleet' });
     }
-    // 4) Cross-device harness divergence — one item per diverged box (RUSH-2027).
     for (const w of report.warnings) {
         if (w.kind !== 'divergence')
             continue;
@@ -359,8 +298,6 @@ export function buildFleetAttentionItems(report, now = Date.now()) {
     }
     return items;
 }
-/** Right-aligned `<content>` on the same line as `left`, clamped so it never
- *  overlaps the left text on a narrow terminal. */
 function alignRight(left, right, width) {
     const gap = width - stringWidth(left) - stringWidth(right);
     return gap > 1 ? `${left}${' '.repeat(gap)}${right}` : `${left}  ${right}`;
@@ -382,12 +319,6 @@ function versionCell(row) {
         return chalk.gray('—');
     return shortVersion(row.version);
 }
-/**
- * The default `agents fleet status` view (RUSH-1966): a one-line rollup, a
- * NEEDS ATTENTION list of only the actionable problems (each with its fix
- * command), quiet per-device rows grouped by OS, and an honest footer. The full
- * auth/CLI/sync grid moves behind `--verbose` ({@link renderFleetMatrix}).
- */
 export function renderFleetSummary(report, opts = {}) {
     const now = opts.now ?? Date.now();
     const width = terminalWidth();
@@ -416,8 +347,6 @@ export function renderFleetSummary(report, opts = {}) {
         }
         lines.push('');
     }
-    // Per-device rows, grouped by OS. Within a group, this machine floats to the
-    // top; the rest stay alphabetical.
     const nameW = Math.min(18, Math.max(6, ...rows.map((r) => r.name.length)));
     const headW = Math.max(...rows.map((r) => stringWidth(headroomWord(r))));
     const loadW = Math.max(...rows.map((r) => stringWidth(loadMemCell(r))));
@@ -459,8 +388,6 @@ export function renderFleetSummary(report, opts = {}) {
         }
         lines.push('');
     }
-    // Footer: orphan-version nudge (a `prune` concern, not drift), then an honest
-    // freshness line naming the cache age and what --live/--verbose add.
     const orphaned = rows.filter((r) => r.orphans.length > 0).length;
     if (orphaned > 0) {
         const subject = orphaned === 1 ? '1 device carries' : `${orphaned} devices carry`;

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

@@ -1,53 +1,8 @@
-/**
- * Device resource probing for `agents devices list`.
- *
- * One SSH round-trip per device gathers load average, memory pressure, disk, and core
- * 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
- * AGI EXT (apps/ext/src/core/deviceHealth.ts) — kept as a
- * separate copy on purpose: the CLI does not import across packages.
- */
 import type { DeviceProfile } from './registry.js';
-/** Default per-device probe budget, for a device reachable over a DIRECT
- * Tailscale path. Short enough that the list never hangs on a wedged box. */
 export declare const PROBE_TIMEOUT_MS = 2500;
-/**
- * Probe budget for a device whose last handshake was DERP-relayed
- * ({@link DeviceTailscale.direct} === false).
- *
- * This constant used to not exist: 2.5s was applied to every device and its
- * docstring claimed to be "long enough for a cold relayed SSH handshake". That
- * was false, and on a fleet with no direct paths it broke `--device auto`
- * outright (PHNX-3682). Measured on a 9-box relayed fleet, probed in parallel
- * with cold paths: 1686/1805/1914/2688/2706/2749/3082/5586/6588 ms — six of nine
- * over budget, every one of them healthy (rc=0 within 10s). Warm, the same
- * probes take 512-872ms, which is what made the failure intermittent.
- *
- * A relayed hop pays DERP path setup on top of the TCP+SSH handshake, so it
- * gets the same budget the readiness probe already allows
- * (`READY_PROBE_TIMEOUT_MS`) rather than the direct-path one.
- */
 export declare const RELAYED_PROBE_TIMEOUT_MS = 8000;
-/**
- * The probe budget for one device. A relayed peer gets
- * {@link RELAYED_PROBE_TIMEOUT_MS}; a direct (or unknown-path) peer keeps the
- * tight {@link PROBE_TIMEOUT_MS}. Windows keeps its own larger budget, which
- * already exceeds both.
- *
- * `direct` is only meaningful when a tailscale snapshot exists — a
- * `via:"manual"` device never gets a peer entry, so absence is "unknown path",
- * not "relayed", and must not silently widen every manual device's budget.
- */
 export declare function probeBudgetMs(device: DeviceProfile): number;
-/** 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;
-/** One-shot remote snapshot: load, memory, core count, then root filesystem. */
 export declare const PROBE_SNIPPET = "uptime; echo ---AGSTAT---; (vm_stat 2>/dev/null || cat /proc/meminfo 2>/dev/null); echo ---AGSTAT---; (nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null); echo ---AGSTAT---; df -Pk / 2>/dev/null | tail -1";
 export declare function localProbeInvocation(platform: NodeJS.Platform): {
     file: string;
@@ -56,18 +11,9 @@ export declare function localProbeInvocation(platform: NodeJS.Platform): {
 export interface DeviceStats {
     host: string;
     reachable: boolean;
-    /**
-     * The probe exceeded its budget rather than being refused or unresolvable.
-     * Only meaningful when `reachable` is false — it separates "this box did not
-     * answer in time" from "this box actively could not be reached", so callers
-     * report a slow link honestly instead of calling a healthy device offline
-     * (PHNX-3682).
-     */
     timedOut?: boolean;
     loadAvg1?: number;
     ncpu?: 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;
@@ -75,11 +21,9 @@ export interface DeviceStats {
     diskTotalBytes?: number;
     diskFreeBytes?: number;
     diskUsedPercent?: number;
-    /** When the static ncpu/RAM/disk totals were last observed. */
     specsFetchedAt?: number;
     fetchedAt: number;
 }
-/** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
 export declare function fmtBytes(bytes: number | undefined): string;
 export declare function parseUptime(out: string): {
     loadAvg1?: number;
@@ -99,13 +43,8 @@ interface DiskStats {
     diskFreeBytes?: number;
     diskUsedPercent?: number;
 }
-/** Parse the final data row from `df -k /`, deriving usage from block counts. */
 export declare function parseDf(out: string): DiskStats;
-/** Assemble a DeviceStats from the four 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;
 interface FleetCapacity {
     reachable: number;
@@ -113,27 +52,17 @@ interface FleetCapacity {
     memTotalBytes: number;
     memFreeBytes: number;
 }
-/** Sum cores and memory across reachable devices for the summary footer. */
 export declare function fleetCapacity(statsList: Iterable<DeviceStats>): FleetCapacity;
-/** Headroom bucket from the worst of normalized-load and memory. */
 export type Headroom = 'idle' | 'light' | 'busy' | 'loaded' | 'unknown';
 export declare function headroom(stats: DeviceStats | undefined): Headroom;
-/** Probe one device over the same ssh path as `agents ssh <name>`. Never throws;
- * an unreachable/slow/misconfigured device resolves to `reachable: false`. */
 export declare function probeDeviceStats(device: DeviceProfile, opts?: {
     timeoutMs?: number;
     now?: number;
 }): Promise<DeviceStats>;
-/** Probe the local machine directly (no ssh round-trip) — used for the "this
- * machine" row so it always shows real numbers even if it isn't ssh-reachable
- * from itself. */
 export declare function probeLocalStats(host: string, opts?: {
     timeoutMs?: number;
     now?: number;
 }): Promise<DeviceStats>;
-/** Probe many devices concurrently; returns a name→stats map. Bounded by the
- * per-probe timeout, so total wall time ≈ the slowest single probe. The device
- * named `selfName` is probed locally instead of over ssh. */
 export declare function probeFleetStats(devices: DeviceProfile[], opts?: {
     timeoutMs?: number;
     selfName?: string;

package/dist/lib/devices/health.js

@@ -1,48 +1,8 @@
-/**
- * Device resource probing for `agents devices list`.
- *
- * One SSH round-trip per device gathers load average, memory pressure, disk, and core
- * 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
- * AGI EXT (apps/ext/src/core/deviceHealth.ts) — kept as a
- * separate copy on purpose: the CLI does not import across packages.
- */
 import { execFile } from 'child_process';
 import { buildSshInvocation, writeAskpassShim } from './connect.js';
-/** Default per-device probe budget, for a device reachable over a DIRECT
- * Tailscale path. Short enough that the list never hangs on a wedged box. */
 export const PROBE_TIMEOUT_MS = 2_500;
-/**
- * Probe budget for a device whose last handshake was DERP-relayed
- * ({@link DeviceTailscale.direct} === false).
- *
- * This constant used to not exist: 2.5s was applied to every device and its
- * docstring claimed to be "long enough for a cold relayed SSH handshake". That
- * was false, and on a fleet with no direct paths it broke `--device auto`
- * outright (PHNX-3682). Measured on a 9-box relayed fleet, probed in parallel
- * with cold paths: 1686/1805/1914/2688/2706/2749/3082/5586/6588 ms — six of nine
- * over budget, every one of them healthy (rc=0 within 10s). Warm, the same
- * probes take 512-872ms, which is what made the failure intermittent.
- *
- * A relayed hop pays DERP path setup on top of the TCP+SSH handshake, so it
- * gets the same budget the readiness probe already allows
- * (`READY_PROBE_TIMEOUT_MS`) rather than the direct-path one.
- */
 export const RELAYED_PROBE_TIMEOUT_MS = 8_000;
-/**
- * The probe budget for one device. A relayed peer gets
- * {@link RELAYED_PROBE_TIMEOUT_MS}; a direct (or unknown-path) peer keeps the
- * tight {@link PROBE_TIMEOUT_MS}. Windows keeps its own larger budget, which
- * already exceeds both.
- *
- * `direct` is only meaningful when a tailscale snapshot exists — a
- * `via:"manual"` device never gets a peer entry, so absence is "unknown path",
- * not "relayed", and must not silently widen every manual device's budget.
- */
+// Only measured relayed peers receive the wider budget; unknown/manual peers are not assumed relayed.
 export function probeBudgetMs(device) {
     if (device.shell === 'powershell')
         return WIN_PROBE_TIMEOUT_MS;
@@ -50,26 +10,15 @@ export function probeBudgetMs(device) {
         ? RELAYED_PROBE_TIMEOUT_MS
         : PROBE_TIMEOUT_MS;
 }
-/** 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, memory, core count, then root filesystem. */
 export 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); echo ${SEP}; df -Pk / 2>/dev/null | tail -1`;
-/** 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; $disk = Get-CimInstance Win32_LogicalDisk -Filter "DeviceID='C:'"; Write-Output ('AGWINSTAT load=' + $cpu + ' freeKb=' + $os.FreePhysicalMemory + ' totalKb=' + $os.TotalVisibleMemorySize + ' ncpu=' + $env:NUMBER_OF_PROCESSORS + ' diskFreeKb=' + ($disk.FreeSpace / 1KB) + ' diskTotalKb=' + ($disk.Size / 1KB))`;
 export function localProbeInvocation(platform) {
     return platform === 'win32'
         ? { file: 'powershell', args: ['-NoProfile', '-Command', WIN_PROBE_SNIPPET] }
         : { file: 'sh', args: ['-c', PROBE_SNIPPET] };
 }
-/** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
 export function fmtBytes(bytes) {
     if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
         return '—';
@@ -100,9 +49,6 @@ export function parseVmStat(out) {
     const free = out.match(/Pages free:\s+([0-9]+)/);
     if (!active || !wired || !compressed || !free)
         return {};
-    // macOS reclaims inactive + speculative pages on demand, so they count as
-    // available — folding them into "free" (as Activity Monitor / vm_pressure do)
-    // rather than "used" keeps the headroom bucket honest on a Mac.
     const inactive = out.match(/Pages inactive:\s+([0-9]+)/);
     const speculative = out.match(/Pages speculative:\s+([0-9]+)/);
     const usedPages = parseInt(active[1], 10) + parseInt(wired[1], 10) + parseInt(compressed[1], 10);
@@ -137,7 +83,6 @@ export function parseNcpu(out) {
     const n = parseInt(out.trim().split(/\s+/)[0] ?? '', 10);
     return Number.isFinite(n) && n > 0 ? { ncpu: n } : {};
 }
-/** Parse the final data row from `df -k /`, deriving usage from block counts. */
 export function parseDf(out) {
     const columns = out.trim().split(/\s+/);
     if (columns.length < 4)
@@ -152,7 +97,6 @@ export function parseDf(out) {
         diskUsedPercent: Math.max(0, Math.min(100, ((totalKb - freeKb) / totalKb) * 100)),
     };
 }
-/** Assemble a DeviceStats from the four snippet sections. */
 export function parseProbeOutput(host, stdout, fetchedAt) {
     const [uptimePart = '', memPart = '', ncpuPart = '', diskPart = ''] = stdout.split(SEP);
     const { loadAvg1 } = parseUptime(uptimePart);
@@ -174,15 +118,8 @@ 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]+)(?: diskFreeKb=([0-9.]+) diskTotalKb=([0-9.]+))?/);
-    // Unparseable output still means the probe RAN — the box answered, we just
-    // could not read it. Stamp specsFetchedAt anyway so a hardware-fact carry
-    // forward (retainHardwareFacts, RUSH-3096) has a real observation moment
-    // instead of undefined.
     if (!m)
         return { host, reachable: true, fetchedAt, specsFetchedAt: fetchedAt };
     const loadPercent = m[1] === '' ? undefined : parseFloat(m[1]);
@@ -207,7 +144,6 @@ export function parseWinProbeOutput(host, stdout, fetchedAt) {
         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 };
     for (const s of statsList) {
@@ -235,8 +171,7 @@ export function headroom(stats) {
         return 'busy';
     return 'loaded';
 }
-/** Probe one device over the same ssh path as `agents ssh <name>`. Never throws;
- * an unreachable/slow/misconfigured device resolves to `reachable: false`. */
+// Stats probes are agentOnly so listing devices never opens credential UI; a timeout means slow, not conclusively unreachable.
 export function probeDeviceStats(device, opts = {}) {
     const host = device.name;
     const fetchedAt = opts.now ?? Date.now();
@@ -245,13 +180,6 @@ export function probeDeviceStats(device, opts = {}) {
     let env;
     try {
         const shim = writeAskpassShim();
-        // 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).
-        // For powershell devices it base64-encodes the snippet instead.
-        // agentOnly: this is a read-only stats probe. A password-auth device must
-        // resolve its bundle broker-only — never force a foreground Touch ID sheet
-        // just to render the load/mem columns of `agents devices` (RUSH-1970).
         ({ args, env } = buildSshInvocation(device, [isWin ? WIN_PROBE_SNIPPET : PROBE_SNIPPET], shim, {}, { agentOnly: true }));
     }
     catch {
@@ -263,8 +191,6 @@ export function probeDeviceStats(device, opts = {}) {
             env: { ...process.env, ...env },
             timeout: opts.timeoutMs ?? probeBudgetMs(device),
         }, (err, stdout) => {
-            // execFile kills an over-budget child with a signal; that is a slow link,
-            // not an unreachable box, and the two must not read the same downstream.
             if (err || !stdout) {
                 const timedOut = Boolean(err && err.killed);
                 return resolve(timedOut ? { host, reachable: false, timedOut, fetchedAt } : { host, reachable: false, fetchedAt });
@@ -273,9 +199,6 @@ export function probeDeviceStats(device, opts = {}) {
         });
     });
 }
-/** Probe the local machine directly (no ssh round-trip) — used for the "this
- * machine" row so it always shows real numbers even if it isn't ssh-reachable
- * from itself. */
 export function probeLocalStats(host, opts = {}) {
     const fetchedAt = opts.now ?? Date.now();
     const isWin = process.platform === 'win32';
@@ -288,9 +211,6 @@ export function probeLocalStats(host, opts = {}) {
         });
     });
 }
-/** Probe many devices concurrently; returns a name→stats map. Bounded by the
- * per-probe timeout, so total wall time ≈ the slowest single probe. The device
- * named `selfName` is probed locally instead of over ssh. */
 export async function probeFleetStats(devices, opts = {}) {
     const entries = await Promise.all(devices.map(async (d) => {
         const stats = d.name === opts.selfName

package/dist/lib/devices/interactive-host.d.ts

@@ -1,13 +1,3 @@
-/** True when a host flag value is the interactive sentinel. */
 export declare function isDeviceInteractive(value: string | undefined | null): boolean;
-/**
- * The device pinned as `interactive.host`, or null when unset.
- *
- * Callers MUST refuse on null rather than falling back to the local machine.
- * The whole point of the sentinel is reaching a screen someone is watching;
- * silently running on a headless worker instead is the exact failure it exists
- * to prevent, and it would fail invisibly.
- */
 export declare function resolveInteractiveDevice(): string | null;
-/** The actionable error for an unset pin — shared so every call site says the same thing. */
 export declare function interactiveUnsetError(): string;

package/dist/lib/devices/interactive-host.js

@@ -1,52 +1,18 @@
-/**
- * The `interactive` device sentinel: "wherever the human is sitting".
- *
- * `--device auto` means "pick a box by load". This means the opposite — one
- * specific box, the one whose screen a person is actually looking at, pinned as
- * `interactive.host`.
- *
- * It exists because a skill cannot teach a host name. Guidance that says
- * "deliver it to zion" is wrong on every other fleet and stale the moment the
- * pin changes, so agents were left to infer the target or to skip the step. A
- * fixed token is something a SKILL.md can state literally and have be correct
- * everywhere.
- *
- * Resolution happens at the dispatch site, before `isSelfHost`, exactly like
- * `auto` — so a pin naming this machine runs locally instead of self-SSHing, and
- * the forwarded argv has the routing flag stripped, which is what keeps this
- * from recursing.
- */
 import { getConfigValue } from '../device-config.js';
 import { RESERVED_DEVICE_NAMES } from './registry.js';
-/** The reserved `--device` value meaning the box the human is at. */
 const INTERACTIVE_DEVICE_SENTINEL = 'interactive';
-/** True when a host flag value is the interactive sentinel. */
 export function isDeviceInteractive(value) {
     return typeof value === 'string' && value.trim().toLowerCase() === INTERACTIVE_DEVICE_SENTINEL;
 }
-/**
- * The device pinned as `interactive.host`, or null when unset.
- *
- * Callers MUST refuse on null rather than falling back to the local machine.
- * The whole point of the sentinel is reaching a screen someone is watching;
- * silently running on a headless worker instead is the exact failure it exists
- * to prevent, and it would fail invisibly.
- */
 export function resolveInteractiveDevice() {
     const pinned = getConfigValue('interactive.host').value;
     if (typeof pinned !== 'string' || !pinned.trim())
         return null;
     const host = pinned.trim();
-    // Defensive only. `interactive.host` rejects every reserved sentinel at WRITE
-    // time (assertValidDeviceName), so a pin of "interactive" or "auto" cannot be
-    // stored in the first place — which is the right layer, because refusing on
-    // read could only ever say "none is set" and send the user back to the command
-    // they just ran. This catches a config written by an older version.
     if (RESERVED_DEVICE_NAMES.has(host.toLowerCase()))
         return null;
     return host;
 }
-/** The actionable error for an unset pin — shared so every call site says the same thing. */
 export function interactiveUnsetError() {
     return (`--device interactive needs an interactive host pinned, and none is set.\n` +
         `  Set it on the machine you sit at:  agents config set interactive.host <device>`);