@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/devices/health.js

@@ -1,7 +1,7 @@
 /**
  * Device resource probing for `agents devices list`.
  *
- * One SSH round-trip per device gathers load average, memory pressure, and core
+ * 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
@@ -21,16 +21,20 @@ export const PROBE_TIMEOUT_MS = 2_500;
  * routinely blows the 2.5s POSIX budget on a relayed connection. */
 export const WIN_PROBE_TIMEOUT_MS = 6_000;
 const SEP = '---AGSTAT---';
-/** One-shot remote snapshot: load, then memory (mac vm_stat else linux
- * meminfo), then core count (linux nproc else mac hw.ncpu). */
-const PROBE_SNIPPET = `uptime; echo ${SEP}; (vm_stat 2>/dev/null || cat /proc/meminfo 2>/dev/null); echo ${SEP}; (nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null)`;
+/** 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; Write-Output ('AGWINSTAT load=' + $cpu + ' freeKb=' + $os.FreePhysicalMemory + ' totalKb=' + $os.TotalVisibleMemorySize + ' ncpu=' + $env:NUMBER_OF_PROCESSORS)`;
+export 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)
@@ -99,12 +103,28 @@ export function parseNcpu(out) {
     const n = parseInt(out.trim().split(/\s+/)[0] ?? '', 10);
     return Number.isFinite(n) && n > 0 ? { ncpu: n } : {};
 }
-/** Assemble a DeviceStats from the three snippet sections. */
+/** 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)
+        return {};
+    const totalKb = Number(columns[1]);
+    const freeKb = Number(columns[3]);
+    if (!Number.isFinite(totalKb) || totalKb <= 0 || !Number.isFinite(freeKb) || freeKb < 0)
+        return {};
+    return {
+        diskTotalBytes: totalKb * 1024,
+        diskFreeBytes: freeKb * 1024,
+        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 = ''] = stdout.split(SEP);
+    const [uptimePart = '', memPart = '', ncpuPart = '', diskPart = ''] = stdout.split(SEP);
     const { loadAvg1 } = parseUptime(uptimePart);
     const mem = memPart.includes('MemTotal') ? parseLinuxMemInfo(memPart) : parseVmStat(memPart);
     const { ncpu } = parseNcpu(ncpuPart);
+    const disk = parseDf(diskPart);
     const loadPercent = loadAvg1 !== undefined && ncpu ? (loadAvg1 / ncpu) * 100 : undefined;
     return {
         host,
@@ -115,6 +135,8 @@ export function parseProbeOutput(host, stdout, fetchedAt) {
         memPercent: mem.memPercent,
         memTotalBytes: mem.memTotalBytes,
         memFreeBytes: mem.memFreeBytes,
+        ...disk,
+        specsFetchedAt: fetchedAt,
         fetchedAt,
     };
 }
@@ -122,13 +144,16 @@ export function parseProbeOutput(host, stdout, fetchedAt) {
  * (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]+)/);
+    const m = stdout.match(/AGWINSTAT load=([0-9.]*) freeKb=([0-9]+) totalKb=([0-9]+) ncpu=([0-9]+)(?: diskFreeKb=([0-9.]+) diskTotalKb=([0-9.]+))?/);
     if (!m)
         return { host, reachable: true, fetchedAt };
     const loadPercent = m[1] === '' ? undefined : parseFloat(m[1]);
     const freeKb = parseInt(m[2], 10);
     const totalKb = parseInt(m[3], 10);
     const ncpu = parseInt(m[4], 10);
+    const diskFreeKb = m[5] === undefined ? undefined : Number(m[5]);
+    const diskTotalKb = m[6] === undefined ? undefined : Number(m[6]);
+    const hasDisk = diskTotalKb !== undefined && diskTotalKb > 0 && diskFreeKb !== undefined && diskFreeKb >= 0;
     return {
         host,
         reachable: true,
@@ -137,6 +162,10 @@ export function parseWinProbeOutput(host, stdout, fetchedAt) {
         memPercent: totalKb > 0 ? Math.max(0, Math.min(100, ((totalKb - freeKb) / totalKb) * 100)) : undefined,
         memTotalBytes: totalKb > 0 ? totalKb * 1024 : undefined,
         memFreeBytes: totalKb > 0 ? freeKb * 1024 : undefined,
+        diskTotalBytes: hasDisk ? diskTotalKb * 1024 : undefined,
+        diskFreeBytes: hasDisk ? diskFreeKb * 1024 : undefined,
+        diskUsedPercent: hasDisk ? Math.max(0, Math.min(100, ((diskTotalKb - diskFreeKb) / diskTotalKb) * 100)) : undefined,
+        specsFetchedAt: fetchedAt,
         fetchedAt,
     };
 }
@@ -208,8 +237,9 @@ export function probeDeviceStats(device, opts = {}) {
 export function probeLocalStats(host, opts = {}) {
     const fetchedAt = opts.now ?? Date.now();
     const isWin = process.platform === 'win32';
+    const invocation = localProbeInvocation(process.platform);
     return new Promise((resolve) => {
-        execFile(isWin ? 'powershell' : 'sh', isWin ? ['-NoProfile', '-Command', WIN_PROBE_SNIPPET] : ['-c', PROBE_SNIPPET], { encoding: 'utf-8', timeout: opts.timeoutMs ?? (isWin ? WIN_PROBE_TIMEOUT_MS : PROBE_TIMEOUT_MS) }, (err, stdout) => {
+        execFile(invocation.file, invocation.args, { encoding: 'utf-8', timeout: opts.timeoutMs ?? (isWin ? WIN_PROBE_TIMEOUT_MS : PROBE_TIMEOUT_MS) }, (err, stdout) => {
             if (err || !stdout)
                 return resolve({ host, reachable: false, fetchedAt });
             resolve(isWin ? parseWinProbeOutput(host, stdout, fetchedAt) : parseProbeOutput(host, stdout, fetchedAt));

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

@@ -0,0 +1,15 @@
+/** The reserved `--device` value meaning the box the human is at. */
+export declare const INTERACTIVE_DEVICE_SENTINEL = "interactive";
+/** 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

@@ -0,0 +1,53 @@
+/**
+ * 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. */
+export 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>`);
+}

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

@@ -1,3 +1,5 @@
+import type { Meta } from '../types.js';
+import type { IgnoredDeviceEntry } from '../fleet/types.js';
 /** Operating-system family of a device, used to pick the remote shell. */
 export type DevicePlatform = 'windows' | 'linux' | 'macos' | 'unknown';
 /** Remote shell dialect derived from the platform. */
@@ -84,8 +86,36 @@ export interface DeviceProfile {
 export declare function isDialableDevice(d: DeviceProfile): boolean;
 /** Map of device name to profile. */
 export type DeviceRegistry = Record<string, DeviceProfile>;
-/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+/**
+ * `--device` values that mean "resolve me", not "connect to a box with this
+ * name". A real device registered under one of these would be unreachable,
+ * and pinning `interactive.host` to one is a misconfiguration that has to fail
+ * at WRITE time — otherwise the read side can only report "none is set", which
+ * tells the user to run the command they just ran.
+ */
+export declare const RESERVED_DEVICE_NAMES: Set<string>;
+/**
+ * Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.).
+ *
+ * SHAPE ONLY. Safe on read paths, which must keep working for a name that is
+ * already registered — including one this version would refuse to create.
+ */
 export declare function assertValidDeviceName(name: string): void;
+/**
+ * Throw if `name` cannot be used for a NEW device: bad shape, or a reserved
+ * routing sentinel.
+ *
+ * Deliberately separate from {@link assertValidDeviceName}, and called from
+ * exactly two kinds of place: `agents devices add <name>`, and the config keys
+ * that point AT a device (`interactive.host`).
+ *
+ * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
+ * receive tailnet node names the user never typed — `devices sync` upserts every
+ * observed node in a loop with no per-node catch, so one node named `auto` would
+ * abort the entire sync and register nothing after it. A name the fleet OBSERVES
+ * is not a name anyone CHOSE; only the second kind is policy's business.
+ */
+export declare function assertRegistrableDeviceName(name: string): void;
 /** Map a Tailscale `OS` field to our platform enum. */
 export declare function platformFromOs(os: string | undefined): DevicePlatform;
 /** The remote shell a platform speaks. */
@@ -132,12 +162,39 @@ export declare function upsertDevice(name: string, input: DeviceInput): Promise<
 export declare function writeReachability(updates: Record<string, DeviceReachability>): Promise<string[]>;
 /** Remove a device. Returns false if it was not registered. */
 export declare function removeDevice(name: string): Promise<boolean>;
-/** Load the set of ignored node names. Missing file => empty set. A malformed
- * file is a hard error for the same reason the registry is: silently returning
- * [] would let the next write wipe the user's dismissals. */
+/**
+ * The ignore-list: tailscale node names the user explicitly dismissed from
+ * auto-discovery. A dismissed node is deliberately NOT a device (it never
+ * enters the registry), so it has no per-device doc — its home is the central,
+ * TRACKED `~/.agents/agents.yaml` under a `fleet.ignored` list, which syncs
+ * fleet-wide via `agents repo push/pull`: a dismissal on one box stops the
+ * suggestion on every box (RUSH-3062). Auto-discovery (`runDeviceSync`'s
+ * pending diff) subtracts this set, so an ignored node never re-surfaces as a
+ * suggestion. Writes go through `updateMeta` — the central-config write path
+ * (withMetaLock + atomic write) — so two agents writing concurrently cannot
+ * corrupt it, and no second lock is hand-rolled here.
+ */
+export type { IgnoredDeviceEntry } from '../fleet/types.js';
+/**
+ * The full ignore-list entries — who dismissed a node, when, and on which box —
+ * the typed read side for `agents devices ignored`. Absent `fleet.ignored` =>
+ * []. A malformed block is a hard error for the same reason the registry is:
+ * silently returning [] would let the next write wipe the user's dismissals.
+ */
+export declare function loadIgnoredEntries(meta?: Meta): IgnoredDeviceEntry[];
+/** Load the set of ignored node names. Same corruption contract as
+ * {@link loadIgnoredEntries}. */
 export declare function loadIgnored(): Promise<Set<string>>;
 /** True if `name` is on the ignore-list. */
 export declare function isIgnored(name: string): Promise<boolean>;
+/**
+ * Union `names` into the meta's ignore-list, stamping new entries with
+ * `ignoredAt` and THIS machine's id. Existing entries keep their original
+ * who/when, so re-adding a name is a true no-op. Returns the input unchanged
+ * when no name is new. Exported for the one-shot legacy-store migration in
+ * lib/devices/config-migration.ts.
+ */
+export declare function withIgnoredAdded(meta: Meta, names: string[], ignoredAt: string): Meta;
 /** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
 export declare function addIgnored(name: string): Promise<Set<string>>;
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was

package/dist/lib/devices/registry.js

@@ -17,8 +17,9 @@ import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
 import lockfile from 'proper-lockfile';
-import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
+import { getDevicesRegistryPath, readMeta, updateMeta } from '../state.js';
 import { atomicWriteJsonSync } from '../fs-atomic.js';
+import { machineId } from '../machine-id.js';
 /**
  * Whether a fan-out should dial this device, honouring the preference stated on
  * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
@@ -62,12 +63,46 @@ function registryPath() {
 /** Valid logical device name: the ssh-alias charset, so it renders into an
  * unambiguous `Host` stanza and is safe as an ssh target. */
 const DEVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+/**
+ * `--device` values that mean "resolve me", not "connect to a box with this
+ * name". A real device registered under one of these would be unreachable,
+ * and pinning `interactive.host` to one is a misconfiguration that has to fail
+ * at WRITE time — otherwise the read side can only report "none is set", which
+ * tells the user to run the command they just ran.
+ */
+export const RESERVED_DEVICE_NAMES = new Set(['auto', 'interactive', 'all']);
+/**
+ * Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.).
+ *
+ * SHAPE ONLY. Safe on read paths, which must keep working for a name that is
+ * already registered — including one this version would refuse to create.
+ */
 export function assertValidDeviceName(name) {
     if (!DEVICE_NAME_RE.test(name)) {
         throw new Error(`Invalid device name ${JSON.stringify(name)}. Use letters, digits, '.', '_', '-' (no spaces) — e.g. 'win-mini'.`);
     }
 }
+/**
+ * Throw if `name` cannot be used for a NEW device: bad shape, or a reserved
+ * routing sentinel.
+ *
+ * Deliberately separate from {@link assertValidDeviceName}, and called from
+ * exactly two kinds of place: `agents devices add <name>`, and the config keys
+ * that point AT a device (`interactive.host`).
+ *
+ * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
+ * receive tailnet node names the user never typed — `devices sync` upserts every
+ * observed node in a loop with no per-node catch, so one node named `auto` would
+ * abort the entire sync and register nothing after it. A name the fleet OBSERVES
+ * is not a name anyone CHOSE; only the second kind is policy's business.
+ */
+export function assertRegistrableDeviceName(name) {
+    assertValidDeviceName(name);
+    if (RESERVED_DEVICE_NAMES.has(name.trim().toLowerCase())) {
+        throw new Error(`${JSON.stringify(name)} is a reserved --device value, not a device name. ` +
+            `Reserved: ${[...RESERVED_DEVICE_NAMES].join(', ')}.`);
+    }
+}
 /** Map a Tailscale `OS` field to our platform enum. */
 export function platformFromOs(os) {
     switch ((os ?? '').toLowerCase()) {
@@ -246,55 +281,76 @@ export async function removeDevice(name) {
         return true;
     });
 }
-function ignoredPath() {
-    return getDevicesIgnoredPath();
+/**
+ * The full ignore-list entries — who dismissed a node, when, and on which box —
+ * the typed read side for `agents devices ignored`. Absent `fleet.ignored` =>
+ * []. A malformed block is a hard error for the same reason the registry is:
+ * silently returning [] would let the next write wipe the user's dismissals.
+ */
+export function loadIgnoredEntries(meta = readMeta()) {
+    const raw = meta.fleet?.ignored;
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) ||
+        raw.some((e) => !e ||
+            typeof e.name !== 'string' ||
+            typeof e.ignoredAt !== 'string' ||
+            typeof e.ignoredOn !== 'string')) {
+        throw new Error(`Device ignore-list corrupted in agents.yaml (fleet.ignored): expected a list of { name, ignoredAt, ignoredOn } entries. Inspect and repair ~/.agents/agents.yaml.`);
+    }
+    return raw;
 }
-/** Load the set of ignored node names. Missing file => empty set. A malformed
- * file is a hard error for the same reason the registry is: silently returning
- * [] would let the next write wipe the user's dismissals. */
+/** Load the set of ignored node names. Same corruption contract as
+ * {@link loadIgnoredEntries}. */
 export async function loadIgnored() {
-    const p = ignoredPath();
-    let raw;
-    try {
-        raw = await fs.readFile(p, 'utf-8');
-    }
-    catch (err) {
-        if (err && err.code === 'ENOENT')
-            return new Set();
-        throw err;
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        return new Set(Array.isArray(parsed.ignored) ? parsed.ignored : []);
-    }
-    catch (err) {
-        throw new Error(`Device ignore-list corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
-    }
+    return new Set(loadIgnoredEntries().map((e) => e.name));
 }
 /** True if `name` is on the ignore-list. */
 export async function isIgnored(name) {
     return (await loadIgnored()).has(name);
 }
+/**
+ * Union `names` into the meta's ignore-list, stamping new entries with
+ * `ignoredAt` and THIS machine's id. Existing entries keep their original
+ * who/when, so re-adding a name is a true no-op. Returns the input unchanged
+ * when no name is new. Exported for the one-shot legacy-store migration in
+ * lib/devices/config-migration.ts.
+ */
+export function withIgnoredAdded(meta, names, ignoredAt) {
+    const entries = loadIgnoredEntries(meta); // throws on a corrupted block — never wipe it
+    const have = new Set(entries.map((e) => e.name));
+    const fresh = names.filter((n) => !have.has(n));
+    if (fresh.length === 0)
+        return meta;
+    const fleet = (meta.fleet ?? { devices: {} });
+    const ignored = [
+        ...entries,
+        ...fresh.map((name) => ({ name, ignoredAt, ignoredOn: machineId() })),
+    ].sort((a, b) => a.name.localeCompare(b.name));
+    const nextFleet = { ...fleet, ignored };
+    return { ...meta, fleet: nextFleet };
+}
 /** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
 export async function addIgnored(name) {
     assertValidDeviceName(name);
-    const p = ignoredPath();
-    return withRegistryLock(p, async () => {
-        const set = await loadIgnored();
-        set.add(name);
-        atomicWriteJsonSync(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
-        return set;
-    });
+    const meta = updateMeta((m) => withIgnoredAdded(m, [name], new Date().toISOString()));
+    return new Set(loadIgnoredEntries(meta).map((e) => e.name));
 }
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was
  * not ignored. */
 export async function removeIgnored(name) {
-    const p = ignoredPath();
-    return withRegistryLock(p, async () => {
-        const set = await loadIgnored();
-        if (!set.delete(name))
-            return false;
-        atomicWriteJsonSync(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
-        return true;
+    let removed = false;
+    updateMeta((m) => {
+        const fleet = m.fleet;
+        if (!fleet?.ignored)
+            return m;
+        const entries = loadIgnoredEntries(m);
+        const next = entries.filter((e) => e.name !== name);
+        if (next.length === entries.length)
+            return m;
+        removed = true;
+        const nextFleet = { ...fleet, ignored: next };
+        return { ...m, fleet: nextFleet };
     });
+    return removed;
 }

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

@@ -8,8 +8,32 @@ import type { DeviceProfile } from './registry.js';
  * rewrites the cache, unreachable boxes included).
  */
 export declare const STATS_STALE_MS: number;
+/** Static hardware totals are valid for seven days. */
+export declare const SPECS_STALE_MS: number;
 /** True when a cached row is still within {@link STATS_STALE_MS}. */
 export declare function isFreshDeviceStats(stats: DeviceStats, now?: number): boolean;
+/** True when cached core, RAM-total, and disk-total facts remain current. */
+export declare function isFreshDeviceSpecs(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>;
 /**
@@ -30,6 +54,8 @@ export interface FleetStatsResult {
 export interface LoadFleetStatsOptions {
     /** Skip the cache and live-probe every device (the `--refresh`/`--live` path). */
     forceRefresh?: boolean;
+    /** Read only static hardware facts, whose cache lifetime is seven days. */
+    specsOnly?: 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). */

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

@@ -37,10 +37,55 @@ const CACHE_FILE = '.fleet-stats.json';
  * rewrites the cache, unreachable boxes included).
  */
 export const STATS_STALE_MS = 3 * 60_000;
+/** Static hardware totals are valid for seven days. */
+export const SPECS_STALE_MS = 7 * 24 * 60 * 60_000;
 /** True when a cached row is still within {@link STATS_STALE_MS}. */
 export function isFreshDeviceStats(stats, now = Date.now()) {
     return now - stats.fetchedAt <= STATS_STALE_MS;
 }
+/** True when cached core, RAM-total, and disk-total facts remain current. */
+export function isFreshDeviceSpecs(stats, now = Date.now()) {
+    const fetchedAt = stats.specsFetchedAt ?? stats.fetchedAt;
+    return now - fetchedAt <= SPECS_STALE_MS;
+}
+/**
+ * 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 function retainHardwareFacts(probed, prior) {
+    if (probed.reachable || !prior)
+        return probed;
+    const ncpu = probed.ncpu ?? prior.ncpu;
+    const memTotalBytes = probed.memTotalBytes ?? prior.memTotalBytes;
+    const diskTotalBytes = probed.diskTotalBytes ?? prior.diskTotalBytes;
+    if (ncpu === probed.ncpu &&
+        memTotalBytes === probed.memTotalBytes &&
+        diskTotalBytes === probed.diskTotalBytes) {
+        return probed;
+    }
+    return {
+        ...probed,
+        ncpu,
+        memTotalBytes,
+        diskTotalBytes,
+        specsFetchedAt: prior.specsFetchedAt ?? prior.fetchedAt,
+    };
+}
 function cacheFilePath() {
     return path.join(getCacheDir(), CACHE_FILE);
 }
@@ -88,18 +133,22 @@ export async function loadFleetStats(devices, opts = {}) {
     const writeCache = opts.writeCache ?? writeStatsCache;
     const self = opts.selfName;
     const now = opts.now ?? Date.now();
-    const cache = opts.forceRefresh ? {} : readCache();
+    // Always read the cache, even under --refresh. It is not *served* then, but it
+    // is the only record of each box's hardware, and a failed probe must not erase
+    // it — see {@link retainHardwareFacts}.
+    const cache = readCache();
     const stats = new Map();
     const toProbe = [];
     let servedFromCache = false;
     for (const d of devices) {
-        if (d.name === self) {
+        if (d.name === self && !opts.specsOnly) {
             // This machine is always probed locally — cheap, no ssh, always live.
             toProbe.push(d);
             continue;
         }
-        const cached = cache[d.name];
-        if (cached && isFreshDeviceStats(cached, now)) {
+        const cached = opts.forceRefresh ? undefined : cache[d.name];
+        const cacheFresh = cached && (opts.specsOnly ? isFreshDeviceSpecs(cached, now) : isFreshDeviceStats(cached, now));
+        if (cached && cacheFresh) {
             stats.set(d.name, cached);
             servedFromCache = true;
         }
@@ -113,8 +162,11 @@ export async function loadFleetStats(devices, opts = {}) {
         const probed = await probeFleet(toProbe, { selfName: self });
         const fresh = {};
         for (const [name, s] of probed) {
-            stats.set(name, s);
-            fresh[name] = s;
+            // A box that just failed to answer keeps the hardware it was last seen
+            // with, so this call and the cache it writes both carry the spec.
+            const row = retainHardwareFacts(s, cache[name]);
+            stats.set(name, row);
+            fresh[name] = row;
         }
         if (Object.keys(fresh).length > 0)
             writeCache(fresh);
@@ -123,7 +175,7 @@ export async function loadFleetStats(devices, opts = {}) {
     // 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));
+        stats.set(self, retainHardwareFacts(await probeLocal(self), cache[self]));
     }
     let oldest = null;
     for (const s of stats.values()) {

package/dist/lib/devices/worker-pick.d.ts

@@ -0,0 +1,48 @@
+import { type DevicePlacementSignal } from '../teams/scheduler.js';
+/** Why a candidate was dropped, for the fail-loud error message. */
+export interface WorkerExclusion {
+    device: string;
+    reason: 'unreachable' | 'overloaded' | 'wrong-platform' | 'interactive';
+}
+export interface WorkerPickPlan {
+    /** The chosen device name. Never the local box unless it is an auto-pool member. */
+    device: string;
+    /** True when the pick IS this machine (the caller should run in place). */
+    isLocal: boolean;
+    candidates: Array<{
+        device: string;
+        loadPercent?: number;
+        headroom?: string;
+    }>;
+    excluded: WorkerExclusion[];
+}
+export interface WorkerPickOptions {
+    /** Restrict to these platforms. Defaults to POSIX (`linux`, `macos`). */
+    platforms?: string[];
+    /** Override the candidate pool (tests). */
+    eligibleHosts?: string[];
+    localMachine?: string;
+    /** Injected probe (tests). */
+    probe?: (pool: string[]) => Promise<Map<string, DevicePlacementSignal>>;
+}
+/**
+ * Platforms a bun/vitest offload can actually run on.
+ *
+ * Windows is excluded by policy, not by accident: `AGENTS.md` states Windows is
+ * not a required PR or ordinary-release platform and `tests.yml` runs it only as
+ * a `continue-on-error` post-merge smoke. Silently shipping the tree to
+ * `win-mini` would produce a confusing failure for a platform whose result
+ * nobody gates on.
+ */
+export declare const POSIX_PLATFORMS: readonly ["linux", "macos"];
+/**
+ * Resolve the least-loaded eligible worker.
+ *
+ * Throws — never returns a degraded answer. An offload helper that quietly
+ * decided "no worker, run here" would recreate exactly the failure the offload
+ * exists to prevent: the operator believes the work went to the fleet while
+ * their laptop is pinned. Callers surface the thrown message verbatim.
+ */
+export declare function resolveWorkerDevice(opts?: WorkerPickOptions): Promise<WorkerPickPlan>;
+/** The one no-worker message, naming every candidate and why it was dropped. */
+export declare function formatNoWorkerError(excluded: WorkerExclusion[], platforms: Set<string>): string;