@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/device-config.js

@@ -36,7 +36,7 @@ import * as yaml from 'yaml';
 import { META_HEADER, getUserAgentsDir, readMeta, updateMeta, withMetaLock } from './state.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { machineId } from './machine-id.js';
-import { assertValidDeviceName } from './devices/registry.js';
+import { assertValidDeviceName, assertRegistrableDeviceName } from './devices/registry.js';
 import { migrateDeviceConfigStores } from './devices/config-migration.js';
 const DEVICE_PLATFORMS = ['windows', 'linux', 'macos', 'unknown'];
 const SSH_AUTH_METHODS = ['key', 'password'];
@@ -53,7 +53,7 @@ export const CONFIG_KEYS = [
         description: 'Device that shows the user artifacts (browser opens, dashboards) — the "online macOS box" skills should use instead of guessing.',
         validate: (v) => {
             try {
-                assertValidDeviceName(v);
+                assertRegistrableDeviceName(v);
                 return null;
             }
             catch (err) {
@@ -69,7 +69,7 @@ export const CONFIG_KEYS = [
         description: 'Device whose usage snapshots are authoritative for fleet-wide usage reporting.',
         validate: (v) => {
             try {
-                assertValidDeviceName(v);
+                assertRegistrableDeviceName(v);
                 return null;
             }
             catch (err) {
@@ -90,6 +90,18 @@ export const CONFIG_KEYS = [
             ? null
             : `auto.pool must be one of ${AUTO_POOL_MODES.join(' | ')}.`,
     },
+    {
+        name: 'browser.viewer',
+        yamlKey: 'browserViewer',
+        scope: 'device',
+        visibility: 'machine',
+        type: 'string',
+        description: "Which browser THIS machine shows YOU a page in (an .html artifact, `agents feedback`, a login " +
+            "dashboard): a profile name, or `os` for the OS default handler. Unset follows browser.profile. " +
+            "Distinct from browser.profile, which is the profile agents DRIVE — see RUSH-2709 for why " +
+            "collapsing the two was a mistake. Set it to `os` to keep the OS default handler.",
+        validate: (v) => typeof v === 'string' && v.length > 0 ? null : 'browser.viewer must be `os` or a profile name.',
+    },
     {
         name: 'browser.profile',
         yamlKey: 'defaultBrowserProfile',
@@ -144,11 +156,10 @@ export const CONFIG_KEYS = [
         scope: 'device',
         visibility: 'machine',
         type: 'bool',
-        defaultValue: true,
+        defaultValue: false,
         description: 'Whether an interactive `agents run` on this device is wrapped in the shared-socket tmux session. ' +
-            'On gives every agent an addressable pane (`agents sessions --active` tells co-located agents apart, ' +
-            '`agents focus` re-attaches without forking). Off spawns the agent directly on this box — the durable ' +
-            'form of `--no-tmux`, for a machine whose tmux is broken or unwanted.',
+            'Off, the default, spawns the agent directly. Turn it on to give every agent an addressable pane for ' +
+            '`agents message`, injection, and `agents focus` once the tmux mouse, clipboard, and scrollback behavior suits this device.',
     },
     {
         name: 'browser.remote-control',
@@ -179,7 +190,26 @@ export const CONFIG_KEYS = [
         scope: 'device',
         visibility: 'shared',
         type: 'string-list',
-        description: 'Free-form operator notes about this device (one entry per `agents devices config <name> notes <text>`).',
+        description: 'Free-form operator notes about this device (one entry per `agents devices config <name> notes <text>`). ' +
+            'Long-form scratch, never shown in device listings — for the one-line synced summary of what the box is for, use `description`.',
+    },
+    {
+        name: 'description',
+        yamlKey: 'description',
+        scope: 'device',
+        visibility: 'shared',
+        type: 'string',
+        description: 'One line saying what this device is FOR ("gpu box — cuda 12.4"), synced fleet-wide. Kept to one short line ' +
+            'because the device-list renderer will show it (RUSH-3062, `surface` track). ' +
+            'Replaces the value on each set; for appended long-form scratch use `notes`.',
+        validate: (v) => {
+            const s = v;
+            if (s.includes('\n') || s.includes('\r'))
+                return 'description must be a single line.';
+            if (s.length > 80)
+                return `description must be at most 80 characters (got ${s.length}) — it is a one-line table cell.`;
+            return null;
+        },
     },
     {
         name: 'ssh.user',
@@ -593,6 +623,20 @@ export function configuredDeviceRole(name) {
     assertValidDeviceName(name);
     return getConfigValue('role', { device: name }).value;
 }
+/**
+ * The role marked on THIS machine — the one running the CLI — or undefined when
+ * it was never marked. Keyed off {@link machineId} (overridable via
+ * AGENTS_SYNC_MACHINE_ID), so it matches the device's own config-folder key.
+ *
+ * The auth strategy reads this: a `personal` device (the user's own interactive
+ * box) holds a real per-version login and MUST authenticate from it for EVERY
+ * run, interactive or headless; only a `worker` uses the file-based setup-token
+ * (RUSH-2395). `undefined` is treated as non-personal (worker-equivalent) by
+ * that gate — an unmarked box has no login to defer to.
+ */
+export function selfConfiguredDeviceRole() {
+    return configuredDeviceRole(machineId());
+}
 /** Mark a device's role fleet-wide; `undefined` clears the mark. */
 export function setConfiguredDeviceRole(name, role) {
     assertValidDeviceName(name);
@@ -601,6 +645,42 @@ export function setConfiguredDeviceRole(name, role) {
     else
         setConfigValue('role', role, { device: name });
 }
+/**
+ * Devices whose OWN config pins one of the browser profile keys to `profile`.
+ *
+ * Used by `profiles rename` to warn rather than silently leave a peer pointing at
+ * a name that no longer exists. Deliberately read-only: rewriting another
+ * machine's device doc from here would be a cross-machine mutation nobody asked
+ * for, and the pin may well be correct there (a local profile of the same name).
+ */
+export function devicesPinningBrowserProfile(profile) {
+    ensureDeviceConfigMigrated();
+    // Reports WHICH key each device used, not just that it matched. A caller
+    // telling the user to fix `browser.profile` on a device that actually pinned
+    // `browser.viewer` leaves the real pin broken and sets a second key nobody
+    // asked for.
+    const hits = [];
+    const devicesRoot = path.join(getUserAgentsDir(), 'devices');
+    let names = [];
+    try {
+        names = fs
+            .readdirSync(devicesRoot, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return hits;
+    }
+    for (const name of names.sort()) {
+        const cfg = readDeviceDocConfig(name);
+        // A device can pin BOTH; each needs its own fix line.
+        if (cfg.defaultBrowserProfile === profile)
+            hits.push({ device: name, key: 'browser.profile' });
+        if (cfg.browserViewer === profile)
+            hits.push({ device: name, key: 'browser.viewer' });
+    }
+    return hits;
+}
 /**
  * Every device with an effective role, keyed by device name. Layers like every
  * other device-scope key: the fleet default (central fleet.defaults.config)
@@ -720,16 +800,9 @@ export function assertSchedulerEnabled() {
     throw new Error(`The routines scheduler is disabled on this device (scheduler.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
         `Re-enable with: agents devices config ${machineId()} scheduler.enabled on`);
 }
-/**
- * True unless this machine's config turns off the managed tmux wrap for
- * interactive `agents run` launches (`tmux.enabled=false`).
- *
- * Read as one of the guards in `shouldWrapInTmux` (lib/exec.ts) — the durable,
- * per-machine form of `--no-tmux` / `AGENTS_NO_TMUX=1`, for a box whose tmux is
- * broken or unwanted. Unset means today's behavior: wrap.
- */
+/** True only when this machine explicitly enables the managed tmux wrap. */
 export function isTmuxEnabled() {
-    return getConfigValue('tmux.enabled').value !== false;
+    return getConfigValue('tmux.enabled').value === true;
 }
 /** True unless this machine's config disables the daemon outright (top-level kill switch). */
 export function isDaemonEnabled() {

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

@@ -13,6 +13,13 @@
  *       `.history/devices/pins-<host>.json` (pins file wins on conflict — it
  *       is the destination); peers' pins are simply dropped from the tracked
  *       file (each peer owns/rewrites its own pins locally).
+ *   (e) legacy `.history/devices/ignored.json` (per-machine, UNTRACKED — a
+ *       dismissal never reached the rest of the fleet) folds into the central
+ *       TRACKED `fleet.ignored` list (RUSH-3062). Entries keep the legacy
+ *       file's `updatedAt` as `ignoredAt` and take THIS machine's id as
+ *       `ignoredOn` — the legacy store recorded neither, so the folding box
+ *       is the only attribution available. The legacy file is removed only
+ *       AFTER the central write lands.
  *
  * What stays put: a device doc's existing `config:` (already the right home)
  * and its `routines:` list (operator-owned, read cross-device by

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

@@ -13,6 +13,13 @@
  *       `.history/devices/pins-<host>.json` (pins file wins on conflict — it
  *       is the destination); peers' pins are simply dropped from the tracked
  *       file (each peer owns/rewrites its own pins locally).
+ *   (e) legacy `.history/devices/ignored.json` (per-machine, UNTRACKED — a
+ *       dismissal never reached the rest of the fleet) folds into the central
+ *       TRACKED `fleet.ignored` list (RUSH-3062). Entries keep the legacy
+ *       file's `updatedAt` as `ignoredAt` and take THIS machine's id as
+ *       `ignoredOn` — the legacy store recorded neither, so the folding box
+ *       is the only attribution available. The legacy file is removed only
+ *       AFTER the central write lands.
  *
  * What stays put: a device doc's existing `config:` (already the right home)
  * and its `routines:` list (operator-owned, read cross-device by
@@ -33,9 +40,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { META_HEADER, getDevicesAutoLaunchPath, getDevicePinsPath, getUserAgentsDir, readMeta, updateMeta, withMetaLock, } from '../state.js';
+import { META_HEADER, getDevicesAutoLaunchPath, getDevicesIgnoredPath, getDevicePinsPath, getUserAgentsDir, readMeta, updateMeta, withMetaLock, } from '../state.js';
 import { atomicWriteFileSync } from '../fs-atomic.js';
 import { machineId } from '../machine-id.js';
+import { withIgnoredAdded } from './registry.js';
 /** Read every device doc. A doc that fails to parse is loudly skipped. */
 function readDeviceDocs(devicesRoot) {
     const docs = [];
@@ -124,6 +132,32 @@ function readAutoLaunchFlags(autoLaunchPath) {
 function isConfigMap(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
+/**
+ * The legacy per-machine ignored.json. Absent => null. A parse failure is
+ * logged loudly and reported as `undefined` so the caller LEAVES the file in
+ * place for a later retry — never silently emptied, the same corruption
+ * contract the ignore-list itself keeps (registry.ts's loadIgnoredEntries).
+ */
+function readLegacyIgnoredFile(p) {
+    let raw;
+    try {
+        raw = fs.readFileSync(p, 'utf-8');
+    }
+    catch {
+        return null; // absent — nothing to fold
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            names: Array.isArray(parsed.ignored) ? parsed.ignored.filter((n) => typeof n === 'string') : [],
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : undefined,
+        };
+    }
+    catch (err) {
+        console.error(`device config migration: could not parse ${p} (${err.message}); leaving it for a later retry`);
+        return undefined;
+    }
+}
 /**
  * Fold every legacy device-config/pins location into the current layout. Safe
  * to call on every boot / config access: cheap no-op once folded.
@@ -139,6 +173,9 @@ export function migrateDeviceConfigStores() {
     const centralHasConfig = Object.values(centralDevices).some((ov) => ov?.config && Object.keys(ov.config).length > 0);
     const autoLaunchFlags = readAutoLaunchFlags(autoLaunchPath);
     const docs = readDeviceDocs(devicesRoot);
+    const legacyIgnoredPath = getDevicesIgnoredPath();
+    const legacyIgnoredPending = fs.existsSync(legacyIgnoredPath);
+    const legacyIgnored = legacyIgnoredPending ? readLegacyIgnoredFile(legacyIgnoredPath) : null;
     const pinsPath = getDevicePinsPath();
     let selfPins = {};
     try {
@@ -172,7 +209,7 @@ export function migrateDeviceConfigStores() {
         : undefined;
     const hasDestinationWork = plans.length > 0 || newDocs.length > 0 || docAgents !== undefined || docIsolated !== undefined;
     const autoLaunchPending = fs.existsSync(autoLaunchPath);
-    if (!centralHasConfig && !hasDestinationWork && !autoLaunchPending)
+    if (!centralHasConfig && !hasDestinationWork && !autoLaunchPending && !legacyIgnoredPending)
         return;
     // ── 2. Destination writes FIRST (crash-safe), under the meta lock so they
     //    serialize against writeMetaUnlocked's own read-merge-write of the doc.
@@ -221,7 +258,18 @@ export function migrateDeviceConfigStores() {
                     nextDevices[name] = rest;
             }
             const fleet = { ...m.fleet, devices: nextDevices };
-            if (Object.keys(nextDevices).length === 0 && !fleet.defaults && !fleet.secrets && !fleet.routines) {
+            // Drop the whole `fleet` block only when NOTHING else lives in it. Every
+            // resident must be named here: `ignored` holds the user's dismissals and
+            // `discovery` their discovery policy, and deleting the block would not
+            // just lose them locally — `agents repo push` would sync the deletion
+            // fleet-wide. Add any new fleet.* key to this guard.
+            const fleetIsEmpty = Object.keys(nextDevices).length === 0 &&
+                !fleet.defaults &&
+                !fleet.secrets &&
+                !fleet.routines &&
+                !fleet.discovery &&
+                !(fleet.ignored && fleet.ignored.length > 0);
+            if (fleetIsEmpty) {
                 const { fleet: _, ...rest } = m;
                 void _;
                 return rest;
@@ -238,6 +286,22 @@ export function migrateDeviceConfigStores() {
             console.error(`device config migration: could not remove ${autoLaunchPath} (${err.message}); a later run retries`);
         }
     }
+    // ── 4. Legacy ignored.json → central fleet.ignored ───────────────────────
+    // Destination write (updateMeta: withMetaLock + atomic write) lands BEFORE
+    // the legacy file is removed, so a crash re-folds on the next run and
+    // withIgnoredAdded's union-by-name makes that a no-op. A file that failed to
+    // parse (legacyIgnored === undefined) is left in place for that retry.
+    if (legacyIgnored) {
+        if (legacyIgnored.names.length > 0) {
+            updateMeta((m) => withIgnoredAdded(m, legacyIgnored.names, legacyIgnored.updatedAt ?? new Date().toISOString()));
+        }
+        try {
+            fs.rmSync(legacyIgnoredPath, { force: true });
+        }
+        catch (err) {
+            console.error(`device config migration: could not remove ${legacyIgnoredPath} (${err.message}); a later run retries`);
+        }
+    }
 }
 /** Shallow-set equality for folded doc content (values compared deep via JSON). */
 function sameDocContent(a, b) {

package/dist/lib/devices/harness-inventory.js

@@ -27,15 +27,32 @@ import { listNativeAccounts } from '../account-registry.js';
  */
 export function summarizeQuota(snapshot, unavailableReason = null, accountStatus = null) {
     if (!snapshot || snapshot.windows.length === 0) {
-        const status = accountStatus;
+        // An active refusal marker (persisted out_of_credits, or an unexpired
+        // session_limit) blocks even when there are no live utilization windows —
+        // which is the normal state hours/days after a run, once cached windows
+        // expire. Check it BEFORE trusting the coarse account status, which is
+        // hardcoded 'available' for a signed-in Claude; otherwise a tokens-exhausted
+        // account reads ready:true here (RUSH-3018 finding, `agents devices harnesses`).
+        const marker = snapshot?.unavailable;
+        let status = accountStatus;
+        let reason = unavailableReason;
+        if (marker?.reason === 'out_of_credits') {
+            status = 'out_of_credits';
+            reason = 'out of credits';
+        }
+        else if (marker?.reason === 'session_limit' &&
+            (!marker.resetsAt || marker.resetsAt.getTime() > Date.now())) {
+            status = 'rate_limited';
+            reason = 'session-limited';
+        }
         return {
             status,
             verdict: status ?? 'unavailable',
             usedPercent: null,
             stale: false,
             capturedAt: snapshot?.capturedAt?.toISOString() ?? null,
-            resetsAt: null,
-            unavailableReason: status ? null : (unavailableReason ?? 'usage unavailable'),
+            resetsAt: marker?.resetsAt?.toISOString() ?? null,
+            unavailableReason: status ? null : (reason ?? 'usage unavailable'),
         };
     }
     const blocking = snapshot.windows.filter((w) => w.key !== 'sonnet_week');

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

@@ -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
@@ -19,6 +19,19 @@ export declare const PROBE_TIMEOUT_MS = 2500;
  * "Preparing modules for first use" cost on top of PowerShell startup, which
  * routinely blows the 2.5s POSIX budget on a relayed connection. */
 export declare const WIN_PROBE_TIMEOUT_MS = 6000;
+/** One-shot remote snapshot: load, memory, core count, then root filesystem. */
+export declare const PROBE_SNIPPET = "uptime; echo ---AGSTAT---; (vm_stat 2>/dev/null || cat /proc/meminfo 2>/dev/null); echo ---AGSTAT---; (nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null); echo ---AGSTAT---; df -Pk / 2>/dev/null | tail -1";
+/** 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. */
+export declare 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 declare function localProbeInvocation(platform: NodeJS.Platform): {
+    file: string;
+    args: string[];
+};
 export interface DeviceStats {
     host: string;
     reachable: boolean;
@@ -30,6 +43,11 @@ export interface DeviceStats {
     memPercent?: number;
     memTotalBytes?: number;
     memFreeBytes?: number;
+    diskTotalBytes?: number;
+    diskFreeBytes?: number;
+    diskUsedPercent?: number;
+    /** When the static ncpu/RAM/disk totals were last observed. */
+    specsFetchedAt?: number;
     fetchedAt: number;
 }
 /** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
@@ -47,7 +65,14 @@ export declare function parseLinuxMemInfo(out: string): MemStats;
 export declare function parseNcpu(out: string): {
     ncpu?: number;
 };
-/** Assemble a DeviceStats from the three snippet sections. */
+interface DiskStats {
+    diskTotalBytes?: number;
+    diskFreeBytes?: number;
+    diskUsedPercent?: number;
+}
+/** Parse the final data row from `df -k /`, deriving usage from block counts. */
+export declare function parseDf(out: string): DiskStats;
+/** Assemble a DeviceStats from the four snippet sections. */
 export declare function parseProbeOutput(host: string, stdout: string, fetchedAt: number): DeviceStats;
 /** Assemble a DeviceStats from the windows one-liner. A missing marker line
  * (e.g. CIM unavailable) keeps `reachable: true` — ssh answered — with no

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