@phnx-labs/agents-cli 1.20.69 → 1.20.71

package/dist/lib/computer/download.js

@@ -13,7 +13,7 @@
  * A `.app` is a directory, so the asset is a zip (`ditto -c -k --keepParent`);
  * we extract it with `ditto -x -k` after the checksum passes.
  */
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -41,6 +41,11 @@ export function macHelperAssetUrls(version) {
     const base = `https://github.com/${HELPER_RELEASE_REPO}/releases/download/v${version}`;
     return { zip: `${base}/${MAC_HELPER_ASSET}`, sha256: `${base}/${MAC_HELPER_ASSET}.sha256` };
 }
+/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
+ * emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
+export function parseTeamId(codesignInfo) {
+    return codesignInfo.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1] ?? null;
+}
 /**
  * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
  * Team, and notarized (Gatekeeper-accepted). Throws with an actionable message
@@ -55,17 +60,13 @@ export function verifyMacHelper(appPath) {
         throw new Error(`code signature invalid for ${appPath}: ${e.message}`);
     }
     // 2. Team identity — must be our Developer ID, not some other valid signer.
-    let info = '';
-    try {
-        info = execFileSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { stdio: 'pipe' }).toString();
-    }
-    catch (e) {
-        // codesign -dv writes to stderr; capture whatever it emitted.
-        info = (e.stderr?.toString() ?? '') + (e.stdout?.toString() ?? '');
-        if (!info)
-            throw new Error(`could not read code signature of ${appPath}: ${e.message}`);
-    }
-    const team = info.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1];
+    // `codesign -dv` writes its details to STDERR even on success (exit 0), so we
+    // must read stderr, not stdout. spawnSync captures both streams regardless of
+    // exit code; execFileSync would return only (empty) stdout and the Team check
+    // would falsely reject every validly-signed helper.
+    const dv = spawnSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { encoding: 'utf8' });
+    const info = `${dv.stdout ?? ''}${dv.stderr ?? ''}`;
+    const team = parseTeamId(info);
     if (team !== EXPECTED_TEAM_ID) {
         throw new Error(`helper signed by unexpected Team (${team ?? 'none'}), expected ${EXPECTED_TEAM_ID}. Refusing to install.`);
     }

package/dist/lib/daemon.js

@@ -625,6 +625,42 @@ export async function runDaemon() {
     };
     const launchHealthInterval = setInterval(() => { void runLaunchHealthCheck(); }, 6 * 60 * 60_000);
     const launchHealthKickoff = setTimeout(() => { void runLaunchHealthCheck(); }, 90_000);
+    // Fleet cache warm: keep the caches that `agents devices list`, `fleet status`,
+    // and `agents view` read cache-first actually fresh, so a default read never
+    // has to ssh out. Two cheap refreshes: (1) this host's auth-health verdicts
+    // (also feeds the `doctor --json` Auth rollup other hosts read), and (2) the
+    // fleet resource-stats cache (one bounded parallel probe of the tailnet). Both
+    // best-effort + overlap-guarded like the probes above. ~every 3 min, plus once
+    // ~60s after startup (staggered off launch).
+    let warmingFleetCache = false;
+    const runFleetCacheWarm = async () => {
+        if (warmingFleetCache)
+            return;
+        warmingFleetCache = true;
+        try {
+            const { machineId } = await import('./machine-id.js');
+            const self = machineId();
+            const { probeLocalFleetAuth, writeFleetAuthRows } = await import('./auth-health.js');
+            const { getCliVersion } = await import('./version.js');
+            const authRows = await probeLocalFleetAuth({ cliVersion: getCliVersion() });
+            writeFleetAuthRows(self, authRows);
+            const { loadDevices } = await import('./devices/registry.js');
+            const { planFleetTargets } = await import('./devices/fleet.js');
+            const { loadFleetStats } = await import('./devices/stats-cache.js');
+            const reg = await loadDevices();
+            const probeable = planFleetTargets(reg).filter((t) => !t.skip).map((t) => t.device);
+            const res = await loadFleetStats(probeable, { forceRefresh: true, selfName: self });
+            log('INFO', `fleet cache warm: ${authRows.length} auth row(s), ${res.stats.size} device stat(s)`);
+        }
+        catch (err) {
+            log('ERROR', `fleet cache warm failed: ${err.message}`);
+        }
+        finally {
+            warmingFleetCache = false;
+        }
+    };
+    const fleetCacheInterval = setInterval(() => { void runFleetCacheWarm(); }, 3 * 60_000);
+    const fleetCacheKickoff = setTimeout(() => { void runFleetCacheWarm(); }, 60_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -657,6 +693,8 @@ export async function runDaemon() {
         clearTimeout(tmuxReconcileKickoff);
         clearInterval(launchHealthInterval);
         clearTimeout(launchHealthKickoff);
+        clearInterval(fleetCacheInterval);
+        clearTimeout(fleetCacheKickoff);
         hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();

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

@@ -8,6 +8,19 @@ export declare const ASKPASS_KEY_ENV = "AGENTS_SSH_KEY";
  * it against the shared injection guard. Throws if the device has no address.
  */
 export declare function sshTargetFor(device: DeviceProfile): string;
+/**
+ * The address a fleet fan-out probe should hand to `ssh` for a device: the
+ * registry's known-good Tailscale dnsName/IP (via {@link sshTargetFor}) when
+ * present, else the bare name (an address-less manual device dials by name as
+ * before — never worse than the old behaviour).
+ *
+ * Prefer the registry address so a stale `~/.ssh/config` alias can never shadow
+ * it: dialing the bare device name lets ssh resolve it through the user's config,
+ * where a hand-written `Host <name>` block with a DHCP-drifted LAN IP silently
+ * shadows the correct entry, times out, and makes a reachable box look dead.
+ * Pure/testable.
+ */
+export declare function fleetDialTarget(device: DeviceProfile): string;
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile

package/dist/lib/devices/connect.js

@@ -38,6 +38,26 @@ export function sshTargetFor(device) {
     assertValidSshTarget(target);
     return target;
 }
+/**
+ * The address a fleet fan-out probe should hand to `ssh` for a device: the
+ * registry's known-good Tailscale dnsName/IP (via {@link sshTargetFor}) when
+ * present, else the bare name (an address-less manual device dials by name as
+ * before — never worse than the old behaviour).
+ *
+ * Prefer the registry address so a stale `~/.ssh/config` alias can never shadow
+ * it: dialing the bare device name lets ssh resolve it through the user's config,
+ * where a hand-written `Host <name>` block with a DHCP-drifted LAN IP silently
+ * shadows the correct entry, times out, and makes a reachable box look dead.
+ * Pure/testable.
+ */
+export function fleetDialTarget(device) {
+    try {
+        return sshTargetFor(device);
+    }
+    catch {
+        return device.user ? `${device.user}@${device.name}` : device.name;
+    }
+}
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile

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

@@ -70,17 +70,50 @@ export declare function runOnDevice(device: DeviceProfile, cmd: string[], opts?:
     stdout: string;
     stderr: string;
 };
+/**
+ * Run `cmd` on THIS machine directly — no ssh. Used by {@link runFleet} for the
+ * self target: a box frequently can't ssh to itself (no self-authorized key, as
+ * `agents fleet update` hit trying to reach zion from zion) and doesn't need to —
+ * `agents upgrade` etc. runs identically as a local process. Mirrors
+ * {@link runOnDevice}'s return shape and never throws. The argv is space-joined
+ * and evaluated by a shell — matching the POSIX-shell ssh path (so PATH-resolved
+ * `agents`, quoting, and `;`/`&&` behave the same). It does NOT replicate the
+ * powershell-device encoding runOnDevice uses (`connect.ts` base64 path): a
+ * Windows self runs under the default OS shell (cmd.exe), which still resolves
+ * `agents` on PATH for the only self commands that matter (`agents upgrade …`).
+ */
+export declare function runLocalCommand(cmd: string[], opts?: {
+    timeoutMs?: number;
+}): {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+};
 /**
  * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
  * Rejects anything that is not a plain npm version/tag token so a version pin
  * cannot inject shell metacharacters into the remote command line.
  */
 export declare function upgradeCommand(version?: string): string[];
+export interface RunFleetOptions {
+    /**
+     * Name of THIS machine. Its target runs the command **locally** (no ssh) — a
+     * box can't reliably ssh to itself and doesn't need to. Omit to ssh every
+     * target (the old behaviour). Callers pass `machineId()`.
+     */
+    self?: string;
+    /** Injectable ssh runner (tests). */
+    runner?: typeof runOnDevice;
+    /** Injectable local runner (tests). */
+    localRunner?: typeof runLocalCommand;
+}
 /**
  * Execute a command across planned targets. Pure orchestration over
- * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
- * the runner are recorded as `failed` so one bad device never aborts the rest.
+ * {@link runOnDevice} / {@link runLocalCommand}; testable by injecting either.
+ * The `self` target runs locally so `agents fleet update` upgrades this machine
+ * too instead of failing to ssh to itself. Per-device throws from a runner are
+ * recorded as `failed` so one bad device never aborts the rest.
  */
-export declare function runFleet(targets: FleetTarget[], cmd: string[], runner?: typeof runOnDevice): FleetRunResult[];
+export declare function runFleet(targets: FleetTarget[], cmd: string[], opts?: RunFleetOptions): FleetRunResult[];
 /** Run one async probe per device in parallel, preserving input order. */
 export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>): Promise<FanOutDeviceResult<T>[]>;

package/dist/lib/devices/fleet.js

@@ -94,6 +94,39 @@ export function runOnDevice(device, cmd, opts = {}) {
         };
     }
 }
+/**
+ * Run `cmd` on THIS machine directly — no ssh. Used by {@link runFleet} for the
+ * self target: a box frequently can't ssh to itself (no self-authorized key, as
+ * `agents fleet update` hit trying to reach zion from zion) and doesn't need to —
+ * `agents upgrade` etc. runs identically as a local process. Mirrors
+ * {@link runOnDevice}'s return shape and never throws. The argv is space-joined
+ * and evaluated by a shell — matching the POSIX-shell ssh path (so PATH-resolved
+ * `agents`, quoting, and `;`/`&&` behave the same). It does NOT replicate the
+ * powershell-device encoding runOnDevice uses (`connect.ts` base64 path): a
+ * Windows self runs under the default OS shell (cmd.exe), which still resolves
+ * `agents` on PATH for the only self commands that matter (`agents upgrade …`).
+ */
+export function runLocalCommand(cmd, opts = {}) {
+    try {
+        const res = spawnSync(cmd.join(' '), {
+            shell: true,
+            encoding: 'utf-8',
+            timeout: opts.timeoutMs ?? 600_000,
+        });
+        return {
+            code: res.status,
+            stdout: res.stdout?.toString() ?? '',
+            stderr: (res.stderr?.toString() ?? '') + (res.error ? String(res.error.message) : ''),
+        };
+    }
+    catch (err) {
+        return {
+            code: 1,
+            stdout: '',
+            stderr: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 /**
  * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
  * Rejects anything that is not a plain npm version/tag token so a version pin
@@ -110,10 +143,14 @@ export function upgradeCommand(version) {
 }
 /**
  * Execute a command across planned targets. Pure orchestration over
- * {@link runOnDevice}; testable by injecting `runner`. Per-device throws from
- * the runner are recorded as `failed` so one bad device never aborts the rest.
+ * {@link runOnDevice} / {@link runLocalCommand}; testable by injecting either.
+ * The `self` target runs locally so `agents fleet update` upgrades this machine
+ * too instead of failing to ssh to itself. Per-device throws from a runner are
+ * recorded as `failed` so one bad device never aborts the rest.
  */
-export function runFleet(targets, cmd, runner = runOnDevice) {
+export function runFleet(targets, cmd, opts = {}) {
+    const runner = opts.runner ?? runOnDevice;
+    const localRunner = opts.localRunner ?? runLocalCommand;
     const results = [];
     for (const t of targets) {
         if (t.skip) {
@@ -126,7 +163,8 @@ export function runFleet(targets, cmd, runner = runOnDevice) {
             continue;
         }
         try {
-            const res = runner(t.device, cmd);
+            const isSelf = opts.self !== undefined && t.device.name === opts.self;
+            const res = isSelf ? localRunner(cmd) : runner(t.device, cmd);
             const ok = res.code === 0;
             const detail = (res.stderr || res.stdout).trim().slice(0, 200);
             results.push({

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

@@ -1,4 +1,5 @@
 import { type DeviceStats } from './health.js';
+import { type HostAuthSummary } from '../auth-health.js';
 export interface FleetCliStatus {
     installed: boolean;
     path: string | null;
@@ -28,6 +29,9 @@ 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;
 }
 export interface FleetWarning {
     kind: 'unreachable' | 'drift' | 'cli' | 'version-skew';
@@ -44,3 +48,10 @@ export interface FleetHealthReport {
 export declare function buildFleetHealthReport(rows: FleetHealthRow[], now?: Date): 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;

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

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
-import { padToWidth, terminalWidth, truncateToWidth } from '../session/width.js';
+import { padToWidth, stringWidth, terminalWidth, truncateToWidth } from '../session/width.js';
 import { fmtBytes, headroom } from './health.js';
+import { formatCheckedAge } from '../auth-health.js';
 function driftRows(row) {
     return row.sync.filter((s) => s.status !== 'fresh');
 }
@@ -121,6 +122,47 @@ 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('-');
+    const s = row.auth;
+    if (!s || s.total === 0)
+        return chalk.gray('—');
+    const parts = [];
+    if (s.live > 0)
+        parts.push(chalk.green(`●${s.live}`));
+    if (s.present > 0)
+        parts.push(chalk.gray(`·${s.present}`));
+    if (s.degraded > 0)
+        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) {
+        const t = pick(row);
+        if (t == null)
+            continue;
+        if (oldest === null || t < oldest)
+            oldest = t;
+    }
+    return oldest;
+}
 export function renderFleetWarnings(report) {
     if (report.warnings.length === 0)
         return [chalk.green('Fleet warnings: none')];
@@ -134,14 +176,19 @@ 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).
-    const fixed = 4 + nameW + 2 + 8 + 2 + 9 + 2 + 9 + 2 + versionW + 2 + 9 + 2 + 9;
+    // 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 = [
         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`),
+        chalk.gray(`    ${padToWidth('Device', nameW)}  ${padToWidth('OS', 8)}  ${padToWidth('Health', 9)}  ${padToWidth('Sync', 9)}  ${padToWidth('CLI', 9)}  ${padToWidth('Auth', authW)}  ${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'}` : '');
@@ -150,10 +197,32 @@ export function renderFleetMatrix(report) {
             `${padToWidth(headroomLabel(row), 9)}  ` +
             `${padToWidth(driftLabel(row), 9)}  ` +
             `${padToWidth(cliLabel(row), 9)}  ` +
+            `${padToWidth(authLabel(row), authW)}  ` +
             `${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'));
+    lines.push(chalk.gray('  ● fresh · ◐ drift · ○ unreachable/skipped · Auth ●live ·present ◐degraded ○revoked'));
+    const foot = freshnessFooter(report.devices);
+    if (foot)
+        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);
+    const parts = [];
+    if (oldestStats != null)
+        parts.push(`stats ${formatCheckedAge(oldestStats, now)}`);
+    if (oldestAuth != null)
+        parts.push(`auth ${formatCheckedAge(oldestAuth, now)}`);
+    if (parts.length === 0)
+        return null;
+    return `  updated ${parts.join(' · ')} — pass --refresh (--live) for a live probe`;
+}

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

@@ -0,0 +1,36 @@
+import { probeFleetStats, probeLocalStats, type DeviceStats } from './health.js';
+import type { DeviceProfile } from './registry.js';
+/** 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;
+export 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;
+}
+export 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;
+}
+/**
+ * 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>;

package/dist/lib/devices/stats-cache.js

@@ -0,0 +1,115 @@
+/**
+ * Disk cache for fleet {@link DeviceStats} so `agents devices list` and
+ * `agents fleet status` render instantly from the last probe instead of
+ * live-SSHing every registered box on every invocation.
+ *
+ * The old behaviour probed the whole fleet over ssh on every call
+ * ({@link probeFleetStats}) — with a dozen devices, a few of them cold or
+ * timing out, that turned a status glance into a multi-second hang. This module
+ * makes the reads cache-first:
+ *
+ * - **Default:** serve remote devices from the cache (instant); always probe
+ *   *this* machine locally (no ssh, sub-ms) so the "this machine" row is live;
+ *   probe only the remote devices missing from the cache (first run / a
+ *   newly-added box), then persist them.
+ * - **`--refresh` / `--live`:** skip the cache and live-probe every device,
+ *   rewriting the cache.
+ *
+ * The daemon warms this cache (~every 3 min, see `lib/daemon.ts
+ * runFleetCacheWarm`), so in steady state a default read has zero
+ * remote ssh round-trips and returns immediately with data that is at most a
+ * few minutes old — surfaced to the user as an "as of …" freshness note.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+import { probeFleetStats, probeLocalStats } from './health.js';
+const CACHE_FILE = '.fleet-stats.json';
+function cacheFilePath() {
+    return path.join(getCacheDir(), CACHE_FILE);
+}
+/** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
+export function readStatsCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cacheFilePath(), 'utf-8'));
+        if (parsed && parsed.entries && typeof parsed.entries === 'object')
+            return parsed.entries;
+    }
+    catch {
+        // missing or corrupt — treat as empty
+    }
+    return {};
+}
+/**
+ * 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 function writeStatsCache(entries) {
+    try {
+        const dir = getCacheDir();
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const merged = {
+            version: 1,
+            entries: { ...readStatsCache(), ...entries },
+        };
+        fs.writeFileSync(cacheFilePath(), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // best-effort; a failed write just means the next read falls back to a live probe
+    }
+}
+/**
+ * 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 async function loadFleetStats(devices, opts = {}) {
+    const probeFleet = opts.probeFleet ?? probeFleetStats;
+    const probeLocal = opts.probeLocal ?? probeLocalStats;
+    const readCache = opts.readCache ?? readStatsCache;
+    const writeCache = opts.writeCache ?? writeStatsCache;
+    const self = opts.selfName;
+    const cache = opts.forceRefresh ? {} : readCache();
+    const stats = new Map();
+    const toProbe = [];
+    let servedFromCache = false;
+    for (const d of devices) {
+        if (d.name === self) {
+            // This machine is always probed locally — cheap, no ssh, always live.
+            toProbe.push(d);
+            continue;
+        }
+        const cached = cache[d.name];
+        if (cached) {
+            stats.set(d.name, cached);
+            servedFromCache = true;
+        }
+        else {
+            toProbe.push(d);
+        }
+    }
+    if (toProbe.length > 0) {
+        const probed = await probeFleet(toProbe, { selfName: self });
+        const fresh = {};
+        for (const [name, s] of probed) {
+            stats.set(name, s);
+            fresh[name] = s;
+        }
+        if (Object.keys(fresh).length > 0)
+            writeCache(fresh);
+    }
+    // Guarantee a row for this machine even when it isn't in the passed device
+    // list (e.g. self not registered as an ssh target) — matches the old callers'
+    // explicit local fallback.
+    if (self && !stats.has(self)) {
+        stats.set(self, await probeLocal(self));
+    }
+    let oldest = null;
+    for (const s of stats.values()) {
+        if (oldest === null || s.fetchedAt < oldest)
+            oldest = s.fetchedAt;
+    }
+    return { stats, oldestFetchedAt: oldest, servedFromCache };
+}

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

@@ -69,6 +69,36 @@ export declare function runDeviceSync(opts?: {
     soft?: boolean;
     mode?: DeviceSyncMode;
 }): Promise<DeviceSyncResult>;
+export interface EnsureDevicesResult {
+    /** Names newly resolved from Tailscale and upserted into the registry. */
+    registered: string[];
+    /** Names that could not be resolved (not on the tailnet / tailscale absent). */
+    unresolved: string[];
+}
+/**
+ * Pure decision for `ensureDevicesRegistered`: split the wanted names into those
+ * to resolve+register (missing from the registry, present on the tailnet, not
+ * ignored) vs. unresolved (missing and either off-tailnet or ignored). Already-
+ * registered names need nothing. Pure so the bootstrap's filter matrix is
+ * unit-testable without a tailnet or registry writes.
+ */
+export interface WantedPartition {
+    toRegister: string[];
+    unresolved: string[];
+}
+export declare function partitionWantedDevices(wanted: string[], registered: Set<string>, tailscaleNames: Set<string>, ignored: Set<string>): WantedPartition;
+/**
+ * Fresh-machine bootstrap for `agents apply`: given the device names a `fleet:`
+ * manifest wants, register any that aren't in the local registry by resolving
+ * them LIVE from Tailscale — so a freshly-cloned `agents.yaml` (which carries
+ * names only, never IPs/usernames) reconstructs its roster with zero committed
+ * connection details. Soft by design: a missing tailscale binary or an offline
+ * name yields `unresolved` rather than throwing, so `apply` degrades to "these
+ * devices aren't reachable yet" instead of aborting. Reuses the same
+ * parse→withDefaultUser→upsert path as `runDeviceSync`, so a bootstrapped device
+ * is identical to a synced one.
+ */
+export declare function ensureDevicesRegistered(wantedNames: string[]): Promise<EnsureDevicesResult>;
 /**
  * The register/remove/ignore decision for the interactive curation picker.
  * Pure so the highest-risk reconcile logic is unit-testable without a tailnet

package/dist/lib/devices/sync.js

@@ -125,6 +125,56 @@ export async function runDeviceSync(opts = {}) {
         throw err;
     }
 }
+export function partitionWantedDevices(wanted, registered, tailscaleNames, ignored) {
+    const out = { toRegister: [], unresolved: [] };
+    for (const name of wanted) {
+        if (registered.has(name))
+            continue;
+        if (tailscaleNames.has(name) && !ignored.has(name))
+            out.toRegister.push(name);
+        else
+            out.unresolved.push(name);
+    }
+    return out;
+}
+/**
+ * Fresh-machine bootstrap for `agents apply`: given the device names a `fleet:`
+ * manifest wants, register any that aren't in the local registry by resolving
+ * them LIVE from Tailscale — so a freshly-cloned `agents.yaml` (which carries
+ * names only, never IPs/usernames) reconstructs its roster with zero committed
+ * connection details. Soft by design: a missing tailscale binary or an offline
+ * name yields `unresolved` rather than throwing, so `apply` degrades to "these
+ * devices aren't reachable yet" instead of aborting. Reuses the same
+ * parse→withDefaultUser→upsert path as `runDeviceSync`, so a bootstrapped device
+ * is identical to a synced one.
+ */
+export async function ensureDevicesRegistered(wantedNames) {
+    const registryBefore = await loadDevices();
+    const registered = new Set(Object.keys(registryBefore));
+    const missing = wantedNames.filter((n) => !registered.has(n));
+    if (missing.length === 0)
+        return { registered: [], unresolved: [] };
+    let nodes;
+    try {
+        nodes = parseTailscaleStatus(tailscaleStatusJson());
+    }
+    catch {
+        // Tailscale absent/unreachable — nothing resolvable; report all missing.
+        return { registered: [], unresolved: missing };
+    }
+    const ignored = await loadIgnored();
+    const tailscaleNames = new Set(nodes.map((n) => n.name));
+    const { toRegister, unresolved } = partitionWantedDevices(missing, registered, tailscaleNames, ignored);
+    const byName = new Map(nodes.map((n) => [n.name, n]));
+    const localUser = localLoginUser();
+    const done = [];
+    for (const name of toRegister) {
+        const input = withDefaultUser(nodeToDeviceInput(byName.get(name)), registryBefore[name]?.user, localUser);
+        await upsertDevice(name, input);
+        done.push(name);
+    }
+    return { registered: done, unresolved };
+}
 export function planDeviceReconciliation(allNames, keep, registered, ignored) {
     const keepSet = new Set(keep);
     const regSet = new Set(registered);