@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/devices/resolve-target.js

@@ -1,33 +1,10 @@
-/**
- * Fan-out + `agents ssh` adapters over the single host/device resolver.
- *
- * Every `--device` / `--device` token becomes a concrete target through one core,
- * {@link matchHost} in ../hosts/registry.ts — the merged directory that reads the
- * devices registry, the agents.yaml overlay, AND ssh_config (RUSH-1967). This
- * module is only the two thin adapters the fan-out and interactive-ssh paths
- * need on top of that core:
- *   - {@link resolveExplicitTargets} — a token list → dialable `{target, machine,
- *     name, os}` rows, so `sessions --device` / session bundles / remote agents-json
- *     dial the exact same address (and machine id) `run --device` does.
- *   - {@link resolveDeviceTarget} — a token → the full {@link DeviceProfile}
- *     `agents ssh` needs (auth, shell, tailscale metadata), with the same
- *     grammar; a bare unregistered alias returns undefined ("Unknown device").
- *
- * The grammar is uniform across the fleet: `name`, `user@name` (same device,
- * login user overridden), a tailnet FQDN, an ssh_config alias, and an ad-hoc
- * `user@host` all resolve identically no matter which subcommand called.
- */
 import chalk from 'chalk';
 import { hostIdentityArgs, sshTargetFor } from '../hosts/types.js';
 import { matchHost, splitUserHost } from '../hosts/registry.js';
 import { normalizeHost } from '../machine-id.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 export { splitUserHost };
-/** Timestamps for a synthesized ad-hoc profile — never persisted, so a constant
- * keeps the value deterministic (and side-effect free) without reading the clock. */
 const SYNTH_TS = '1970-01-01T00:00:00.000Z';
-/** Synthesize a throwaway device profile for an ad-hoc `user@host` / `host`
- * literal so `agents ssh` can dial a box that was never registered. */
 function adHocDevice(token, host, user) {
     const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
     return {
@@ -41,13 +18,6 @@ function adHocDevice(token, host, user) {
         updatedAt: SYNTH_TS,
     };
 }
-/**
- * Resolve one token to a dialable {@link ResolvedSshTarget}, or undefined when it
- * fails the injection guard or names nothing reachable. A registered device (or
- * `user@device`) dials its live Tailscale route; an ssh_config-only alias dials
- * by its bare name (ssh applies the stanza) — now visible to the fan-out too; an
- * ad-hoc `user@host` dials the literal.
- */
 async function toResolvedTarget(token) {
     const host = await matchHost(token);
     if (!host)
@@ -57,7 +27,7 @@ async function toResolvedTarget(token) {
         target = sshTargetFor(host);
     }
     catch {
-        return undefined; // matched a device/host with no address to dial
+        return undefined;
     }
     const hostPart = host.device ? host.device.name : splitUserHost(host.name).host;
     const name = host.device ? host.device.name : host.name;
@@ -70,17 +40,6 @@ async function toResolvedTarget(token) {
         ...(extraSshArgs.length > 0 ? { extraSshArgs } : {}),
     };
 }
-/**
- * Resolve a target token to a full {@link DeviceProfile} for `agents ssh`. Same
- * grammar as the fan-out, but returns the whole profile (auth, shell, tailscale
- * metadata) `buildSshInvocation` needs. A registered `name` / `user@device`
- * yields that profile (login user overridden by any `user@`); an ad-hoc
- * `user@host` / IP / FQDN literal yields a synthesized key-auth profile. A bare
- * unregistered alias (no `@`/dot) — or an ssh_config-only alias, which `agents
- * ssh` has never dialed — returns undefined so the caller reports "Unknown
- * device" rather than dialing a literal. `token` may also be the `auto`
- * affinity sentinel (RUSH-2185); `opts.resolveAuto` overrides the pick (tests).
- */
 export async function resolveDeviceTarget(token, opts = {}) {
     const host = await matchHost(token, { allowBareLiteral: true, ...opts });
     if (!host)
@@ -93,20 +52,11 @@ export async function resolveDeviceTarget(token, opts = {}) {
         const { user, host: hostPart } = splitUserHost(token);
         return adHocDevice(token, hostPart, user);
     }
-    // An overlay / ssh_config-only match is not a device — `agents ssh` stays
-    // devices-and-literals only, so report it as unknown.
     return undefined;
 }
-/**
- * Resolve an explicit `--device`/`--device` list to dialable targets. A token that
- * fails the injection guard or names nothing reachable is skipped with a stderr
- * note (never fatal — one bad token must not blank the fan-out). Shared by every
- * cross-machine fan-out so they can never diverge onto two routes.
- */
 export async function resolveExplicitTargets(hosts) {
     return (await resolveExplicitTargetSet(hosts)).targets;
 }
-/** Resolve explicit tokens while retaining failures for coverage-sensitive callers. */
 export async function resolveExplicitTargetSet(hosts) {
     const targets = [];
     const unresolved = [];

package/dist/lib/devices/rollout-verify.d.ts

@@ -1,102 +1,22 @@
-/**
- * Post-rollout verification for `agents fleet update` / `agents devices update`.
- *
- * The rollout runs `agents upgrade --yes` per box and calls a box `ok` on
- * `exit 0` alone ({@link ../devices/fleet.js runFleet}, `fleet.ts:262`), rendered
- * as `ok  exit 0` (`commands/ssh.ts:416`). That exit code says the npm global was
- * upgraded — it says nothing about **which copy `agents` resolves to on that
- * box**. Any install earlier on PATH than the npm global — a stale copy in
- * another node prefix, a Homebrew shim, a hand-made symlink — keeps winning the
- * name after the upgrade. The upgrade then succeeds, the rollout prints `ok`,
- * and every `agents` command on that box still runs the old code (RUSH-2446).
- *
- * `scripts/install.sh` used to be the usual culprit, linking its side-by-side
- * dev build over `~/.local/bin/agents`; it now publishes `agents-dev` instead and
- * cleans up the links it left. This probe stays as the general backstop — it is
- * name-based (`command -v agents`), so it catches every other cause too.
- *
- * So the rollout asks each box one more question after upgrading: what does
- * `agents` resolve to here, and what version does it report? A box whose
- * resolved `agents` is not on the target is reported as **not upgraded**, and a
- * dev stamp is named as such — never counted as a success.
- *
- * Everything below the probe argv is pure: the shell output is parsed and
- * classified without touching a filesystem or a network, so the verdicts are
- * unit-tested against real probe output rather than a mocked fleet.
- */
 import { runLocalCommand, runOnDevice, type FleetRunResult, type FleetTarget } from './fleet.js';
-/**
- * Argv for the verification probe, run on each box right after its upgrade.
- *
- * Space-joined and evaluated by a shell on both fleet paths — `runOnDevice`
- * hands the tokens to ssh (the remote shell parses them) and `runLocalCommand`
- * joins them under `shell: true` (`fleet.ts:runLocalCommand` docblock) — so the
- * quoting here is the same on the self target and every peer.
- *
- * POSIX only, deliberately: the two `sh` builtins it needs (`command -v`,
- * parameter substitution) do not exist in cmd.exe, so a Windows box yields no
- * parseable output and {@link classifyRolloutVerification} reports it
- * `unverified` rather than silently passing it.
- *
- * `command -v agents` is the resolution the user's own shell performs;
- * `readlink -f` follows the npm/dev bin symlink to the copy that actually runs,
- * falling back to the unresolved path where `readlink -f` is unavailable.
- */
 export declare function rolloutVerifyCommand(): string[];
 interface RolloutProbe {
-    /** Path the box's own `agents` resolves to, symlinks followed. */
     resolvedPath?: string;
-    /** Version that resolved copy reports. */
     reportedVersion?: string;
 }
-/** Parse the probe's stdout. Unlabelled lines (shell banners, motd) are ignored. */
 export declare function parseRolloutVerifyOutput(stdout: string): RolloutProbe;
-export type RolloutVerdict = 
-/** The resolved `agents` reports the target version. */
-'on-target'
-/** The resolved `agents` is a `scripts/install.sh` dev build shadowing the upgraded global. */
- | 'dev-shadowed'
-/** The resolved `agents` reports some other version — the upgrade did not reach it. */
- | 'not-upgraded'
-/** The probe produced no usable answer, so upgraded-ness is unknown. */
- | 'unverified';
+export type RolloutVerdict = 'on-target' | 'dev-shadowed' | 'not-upgraded' | 'unverified';
 export interface RolloutVerification extends RolloutProbe {
     verdict: RolloutVerdict;
-    /** One-line human reason, always set for a non-`on-target` verdict. */
     detail: string;
 }
-/** A verdict other than `on-target` MUST NOT be reported as a successful rollout. */
 export declare function isRolloutSuccess(verdict: RolloutVerdict): boolean;
-/**
- * Resolve the version the rollout was aiming at.
- *
- * An explicit `agents fleet update <version>` names it. A bare
- * `agents fleet update` resolves the `latest` dist-tag independently on every
- * box, so the aggregator never sees a number — it is derived here as the highest
- * **released** version any probed box reports. Dev stamps are excluded from that
- * derivation: a fleet of dev builds must not elect one of them as the target and
- * report itself upgraded. Returns undefined when nothing released was observed,
- * which makes every box `unverified` rather than falsely `on-target`.
- */
 export declare function resolveRolloutTarget(explicitVersion: string | undefined, probes: RolloutProbe[]): string | undefined;
-/** Classify one box's probe against the rollout target. */
 export declare function classifyRolloutVerification(probe: RolloutProbe, targetVersion: string | undefined): RolloutVerification;
 interface VerifyFleetRolloutOptions {
-    /** Name of THIS machine; its target is probed locally, mirroring `runFleet`. */
     self?: string;
-    /** Injectable ssh runner (tests). */
     runner?: typeof runOnDevice;
-    /** Injectable local runner (tests). */
     localRunner?: typeof runLocalCommand;
 }
-/**
- * Probe every box the upgrade reported `ok` and classify what its `agents`
- * actually resolves to. Keyed by device name.
- *
- * Only `ok` boxes are probed: a `skipped` or `failed` row already reports itself
- * loudly, and re-probing it would add a second confusing line for one fault.
- * A probe that throws or exits non-zero yields `unverified`, never `on-target` —
- * "we could not check" and "it is upgraded" are different answers.
- */
 export declare function verifyFleetRollout(targets: FleetTarget[], results: FleetRunResult[], explicitVersion: string | undefined, opts?: VerifyFleetRolloutOptions): Map<string, RolloutVerification>;
 export {};

package/dist/lib/devices/rollout-verify.js

@@ -1,57 +1,9 @@
-/**
- * Post-rollout verification for `agents fleet update` / `agents devices update`.
- *
- * The rollout runs `agents upgrade --yes` per box and calls a box `ok` on
- * `exit 0` alone ({@link ../devices/fleet.js runFleet}, `fleet.ts:262`), rendered
- * as `ok  exit 0` (`commands/ssh.ts:416`). That exit code says the npm global was
- * upgraded — it says nothing about **which copy `agents` resolves to on that
- * box**. Any install earlier on PATH than the npm global — a stale copy in
- * another node prefix, a Homebrew shim, a hand-made symlink — keeps winning the
- * name after the upgrade. The upgrade then succeeds, the rollout prints `ok`,
- * and every `agents` command on that box still runs the old code (RUSH-2446).
- *
- * `scripts/install.sh` used to be the usual culprit, linking its side-by-side
- * dev build over `~/.local/bin/agents`; it now publishes `agents-dev` instead and
- * cleans up the links it left. This probe stays as the general backstop — it is
- * name-based (`command -v agents`), so it catches every other cause too.
- *
- * So the rollout asks each box one more question after upgrading: what does
- * `agents` resolve to here, and what version does it report? A box whose
- * resolved `agents` is not on the target is reported as **not upgraded**, and a
- * dev stamp is named as such — never counted as a success.
- *
- * Everything below the probe argv is pure: the shell output is parsed and
- * classified without touching a filesystem or a network, so the verdicts are
- * unit-tested against real probe output rather than a mocked fleet.
- */
 import { compareVersions } from '../agent-spec/primitives.js';
 import { isDevVersionStamp } from '../startup/dev-build.js';
 import { runLocalCommand, runOnDevice, } from './fleet.js';
 import { isSelfHost } from './self-host.js';
-/**
- * Line prefixes the probe emits. Prefixed rather than positional because a
- * login shell can print its own banner lines into the same stdout, and a
- * rollout that mis-reads a motd line as a version would report a false verdict.
- */
 const PATH_PREFIX = 'agents-rollout-path=';
 const VERSION_PREFIX = 'agents-rollout-version=';
-/**
- * Argv for the verification probe, run on each box right after its upgrade.
- *
- * Space-joined and evaluated by a shell on both fleet paths — `runOnDevice`
- * hands the tokens to ssh (the remote shell parses them) and `runLocalCommand`
- * joins them under `shell: true` (`fleet.ts:runLocalCommand` docblock) — so the
- * quoting here is the same on the self target and every peer.
- *
- * POSIX only, deliberately: the two `sh` builtins it needs (`command -v`,
- * parameter substitution) do not exist in cmd.exe, so a Windows box yields no
- * parseable output and {@link classifyRolloutVerification} reports it
- * `unverified` rather than silently passing it.
- *
- * `command -v agents` is the resolution the user's own shell performs;
- * `readlink -f` follows the npm/dev bin symlink to the copy that actually runs,
- * falling back to the unresolved path where `readlink -f` is unavailable.
- */
 export function rolloutVerifyCommand() {
     const script = [
         'p=$(command -v agents || true)',
@@ -61,7 +13,6 @@ export function rolloutVerifyCommand() {
     ].join('; ');
     return ['sh', '-c', `'${script}'`];
 }
-/** Parse the probe's stdout. Unlabelled lines (shell banners, motd) are ignored. */
 export function parseRolloutVerifyOutput(stdout) {
     const probe = {};
     for (const raw of stdout.split('\n')) {
@@ -79,21 +30,9 @@ export function parseRolloutVerifyOutput(stdout) {
     }
     return probe;
 }
-/** A verdict other than `on-target` MUST NOT be reported as a successful rollout. */
 export function isRolloutSuccess(verdict) {
     return verdict === 'on-target';
 }
-/**
- * Resolve the version the rollout was aiming at.
- *
- * An explicit `agents fleet update <version>` names it. A bare
- * `agents fleet update` resolves the `latest` dist-tag independently on every
- * box, so the aggregator never sees a number — it is derived here as the highest
- * **released** version any probed box reports. Dev stamps are excluded from that
- * derivation: a fleet of dev builds must not elect one of them as the target and
- * report itself upgraded. Returns undefined when nothing released was observed,
- * which makes every box `unverified` rather than falsely `on-target`.
- */
 export function resolveRolloutTarget(explicitVersion, probes) {
     if (explicitVersion && !isDistTag(explicitVersion))
         return explicitVersion;
@@ -107,15 +46,9 @@ export function resolveRolloutTarget(explicitVersion, probes) {
     }
     return best;
 }
-/**
- * A dist-tag (`latest`, `next`) is not a comparable version. `agents fleet update`
- * accepts either (`fleet.ts:upgradeCommand`), so a tag argument is treated the
- * same as no argument: derive the number from what the fleet reports.
- */
 function isDistTag(version) {
     return !/^\d/.test(version);
 }
-/** Classify one box's probe against the rollout target. */
 export function classifyRolloutVerification(probe, targetVersion) {
     const { resolvedPath, reportedVersion } = probe;
     if (!reportedVersion) {
@@ -152,17 +85,7 @@ export function classifyRolloutVerification(probe, targetVersion) {
             `${resolvedPath ? ` (resolves to ${resolvedPath})` : ''}`,
     };
 }
-/** Probe deadline. The probe is two shell builtins plus `agents --version`. */
 const VERIFY_TIMEOUT_MS = 60_000;
-/**
- * Probe every box the upgrade reported `ok` and classify what its `agents`
- * actually resolves to. Keyed by device name.
- *
- * Only `ok` boxes are probed: a `skipped` or `failed` row already reports itself
- * loudly, and re-probing it would add a second confusing line for one fault.
- * A probe that throws or exits non-zero yields `unverified`, never `on-target` —
- * "we could not check" and "it is upgraded" are different answers.
- */
 export function verifyFleetRollout(targets, results, explicitVersion, opts = {}) {
     const runner = opts.runner ?? runOnDevice;
     const localRunner = opts.localRunner ?? runLocalCommand;

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

@@ -1,9 +1,2 @@
-/**
- * True when `name` refers to the local machine. Case-insensitive and
- * trailing-dot-tolerant. Use this everywhere a `--device`/fleet target is compared
- * against "self" so a tailscale-name reference short-circuits to a local run
- * instead of self-SSHing.
- */
 export declare function isSelfHost(name: string | undefined | null): boolean;
-/** Test hook: drop the memoized alias set so a fresh registry/env is re-read. */
 export declare function resetSelfHostCache(): void;

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

@@ -1,30 +1,10 @@
-/**
- * "Is this hostname the local machine?" — matched against every identity the box
- * answers to, not just its short id.
- *
- * The self-checks that gate `--device` dispatch and the fleet-health fan-out used to
- * compare only against {@link machineId} (the lowercased short hostname, e.g.
- * `zion`). A caller that referenced the box by its **tailscale MagicDNS name**
- * (`zion.tail1a85a1.ts.net`) — which is exactly what `fleetDialTarget` and the
- * Factory floor's `--device` probes use — slipped past the check and SSH'd to the
- * LOCAL box over its own tailscale name. On a loaded machine that self-SSH'd
- * `doctor --json` orphaned on timeout and piled up until the host was crushed
- * (RUSH-2114). Matching the full identity set closes that gap at the source.
- */
 import { machineId } from '../machine-id.js';
 import { loadDevicesSync } from './registry.js';
 const LOOPBACK = ['localhost', '127.0.0.1', '::1'];
-/** Lowercase + strip a trailing dot (FQDNs are equivalent with or without it). */
 function normalize(name) {
     return name.trim().toLowerCase().replace(/\.$/, '');
 }
 let cached = null;
-/**
- * Every name that resolves to THIS machine: the short id, loopback, and the self
- * device's tailscale dnsName plus its short form. Computed once per process — the
- * self identity does not change under a running CLI — and reads the registry
- * best-effort (an unreadable registry still leaves the short id + loopback).
- */
 function selfAliases() {
     if (cached)
         return cached;
@@ -34,28 +14,20 @@ function selfAliases() {
         if (dns) {
             const d = normalize(dns);
             aliases.add(d);
-            aliases.add(d.split('.')[0]); // the short form of the FQDN
+            aliases.add(d.split('.')[0]);
         }
     }
     catch {
-        /* registry unreadable — the short id + loopback aliases still hold */
     }
     cached = aliases;
     return cached;
 }
-/**
- * True when `name` refers to the local machine. Case-insensitive and
- * trailing-dot-tolerant. Use this everywhere a `--device`/fleet target is compared
- * against "self" so a tailscale-name reference short-circuits to a local run
- * instead of self-SSHing.
- */
 export function isSelfHost(name) {
     if (!name)
         return false;
     const n = normalize(name);
     return n.length > 0 && selfAliases().has(n);
 }
-/** Test hook: drop the memoized alias set so a fresh registry/env is re-read. */
 export function resetSelfHostCache() {
     cached = null;
 }

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

@@ -1,21 +1,3 @@
-/**
- * Render the device registry into an OpenSSH `ssh_config` include block.
- *
- * Writing a managed include (e.g. `~/.ssh/config.d/agents`) makes every tool
- * that speaks ssh — plain `ssh`/`scp`/`rsync`/`git`, and `agents sessions
- * --device` — resolve the registry's logical device names transparently, without
- * each of them learning about the registry. `agents ssh` stays the value-add
- * layer (preflight, password-from-bundle auth, platform-aware exec) on top.
- *
- * `renderSshConfig` is a pure function (registry in, config text out) so the
- * exact rendering is unit-testable.
- */
 import { type DeviceProfile, type DeviceRegistry } from './registry.js';
-/** The HostName an ssh client should dial for a device: DNS name first, then IP. */
 export declare function hostNameFor(device: DeviceProfile): string | undefined;
-/**
- * Render the whole registry into ssh_config text. Devices are emitted in
- * stable alphabetical order (so the file does not churn between runs) and
- * addressless devices are skipped.
- */
 export declare function renderSshConfig(reg: DeviceRegistry): string;

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

@@ -4,14 +4,10 @@ const HEADER = [
     '# Regenerate with: agents devices render',
     '# Include from ~/.ssh/config with:  Include config.d/agents',
 ].join('\n');
-/** The HostName an ssh client should dial for a device: DNS name first, then IP. */
 export function hostNameFor(device) {
     return device.address.dnsName ?? device.address.ip;
 }
-/** Render a single device into an ssh_config `Host` stanza, or null if it has no address. */
 function renderHost(device) {
-    // Effective profile: operator config (ssh.user / ssh.identity-file) overlaid
-    // on the discovery record, so the rendered stanza matches what `agents ssh` dials.
     const resolved = resolveDeviceProfile(device);
     const hostName = hostNameFor(resolved);
     if (!hostName)
@@ -24,11 +20,6 @@ function renderHost(device) {
     }
     return lines.join('\n');
 }
-/**
- * Render the whole registry into ssh_config text. Devices are emitted in
- * stable alphabetical order (so the file does not churn between runs) and
- * addressless devices are skipped.
- */
 export function renderSshConfig(reg) {
     const stanzas = [];
     for (const name of Object.keys(reg).sort()) {

package/dist/lib/devices/stats-cache.d.ts

@@ -1,73 +1,25 @@
 import { probeFleetStats, probeLocalStats, type DeviceStats } from './health.js';
 import type { DeviceProfile } from './registry.js';
-/**
- * Freshness bound for a cached row. Matches the agent-count mirror's window
- * (`AGENT_STATUS_STALE_MS` in `commands/ssh.ts`) so both columns of
- * `devices list` / `fleet status` share one staleness model. A row older than
- * this is never served as current — it is re-probed live (and the probe result
- * rewrites the cache, unreachable boxes included).
- */
 export declare const STATS_STALE_MS: number;
-/** True when a cached row is still within {@link STATS_STALE_MS}. */
 export declare function isFreshDeviceStats(stats: DeviceStats, now?: number): boolean;
-/**
- * Carry a device's last successfully-probed hardware facts onto a row whose
- * probe just came back unreachable (RUSH-3096).
- *
- * A failed probe knows nothing about the box — `probeDeviceStats` resolves
- * `{ host, reachable: false, fetchedAt }` — and that bare row then replaced the
- * cached one, so `agents devices list` rendered an offline device with an empty
- * `spec` cell and forgot its cores/RAM/disk until it came back up. Cores, total
- * RAM, and root-disk capacity do not change while a machine is down, so they
- * survive the failure; `loadPercent`, `memPercent`, and the free-byte counts are
- * current-state readings and stay absent rather than render a stale number as
- * live.
- *
- * `specsFetchedAt` keeps the moment the facts were actually observed while
- * `fetchedAt` advances to this attempt, so the row reads "this hardware, seen
- * then; unreachable, as of now" instead of backdating a reading that never
- * happened. A reachable probe is returned untouched — its own reading is the
- * truth, including a fact the box has stopped reporting.
- */
 export declare function retainHardwareFacts(probed: DeviceStats, prior: DeviceStats | undefined): DeviceStats;
-/** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
 export declare function readStatsCache(): Record<string, DeviceStats>;
-/**
- * Merge freshly-probed rows into the on-disk cache (best-effort write). Rows for
- * devices not in `entries` are preserved, so a partial probe (gap-fill, or a
- * single-device refresh) never drops the rest of the fleet's cached stats.
- */
 export declare function writeStatsCache(entries: Record<string, DeviceStats>): void;
-/** Drop one removed device so cache-only rows cannot outlive the registry. */
 export declare function removeStatsCacheEntry(name: string): void;
-/** Immutable cache pruning primitive, exported for lifecycle regression tests. */
 export declare function pruneStatsCache(entries: Record<string, DeviceStats>, name: string): Record<string, DeviceStats>;
 interface FleetStatsResult {
-    /** name → stats for every requested device (cache-served + freshly probed). */
     stats: Map<string, DeviceStats>;
-    /** Oldest `fetchedAt` among the returned rows, or null when empty. Drives the
-     *  "as of …" freshness note. */
     oldestFetchedAt: number | null;
-    /** True when at least one row was served from cache rather than probed this call. */
     servedFromCache: boolean;
 }
 interface LoadFleetStatsOptions {
-    /** Skip the cache and live-probe every device (the `--refresh`/`--live` path). */
     forceRefresh?: boolean;
-    /** Device name of THIS machine — always probed locally (no ssh), never cached-served. */
     selfName?: string;
-    /** Injectable probes + cache IO for tests (default to the real ssh/local/disk ones). */
     probeFleet?: typeof probeFleetStats;
     probeLocal?: typeof probeLocalStats;
     readCache?: typeof readStatsCache;
     writeCache?: typeof writeStatsCache;
-    /** Clock override for tests (drives the {@link STATS_STALE_MS} bound). */
     now?: number;
 }
-/**
- * Load fleet stats cache-first. See the module doc for the default vs
- * `--refresh` behaviour. Never throws — an unreachable box degrades to a
- * `reachable: false` row exactly as the live probe does.
- */
 export declare function loadFleetStats(devices: DeviceProfile[], opts?: LoadFleetStatsOptions): Promise<FleetStatsResult>;
 export {};