@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/daemon.js

@@ -14,6 +14,7 @@ import { getDaemonDir as getDaemonDirRoot } from './state.js';
 import { isAlive, killTree, backgroundSpawnOptions } from './platform/index.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
+import { MonitorEngine } from './monitors/engine.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
 import { detectOverdueJobs, notifyOverdue } from './overdue.js';
 import { BrowserService } from './browser/service.js';
@@ -293,6 +294,21 @@ export async function runDaemon() {
         process.exit(0);
     }
     log('INFO', `Daemon started (PID: ${process.pid})`);
+    // RUSH-1759: the launchd plist / systemd unit no longer bake the Claude OAuth
+    // token onto disk. Obtain it here from the secure `claude` secrets bundle and
+    // inject into this process's env so every routine run this daemon spawns still
+    // receives it (via the sandbox allowlist), without the token ever being
+    // persisted in the service manifest. A read from a file-backed store (Linux)
+    // needs no prompt; on macOS it resolves broker-only from an unlocked
+    // secrets-agent and is otherwise absent (leaving the daemon on its existing
+    // interactive OAuth session), matching the detached-start path. Never blocks.
+    if (!process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+        const oauthToken = readDaemonClaudeOAuthToken();
+        if (oauthToken) {
+            process.env.CLAUDE_CODE_OAUTH_TOKEN = oauthToken;
+            log('INFO', 'Loaded Claude OAuth token from secrets bundle for routine runs');
+        }
+    }
     // Reap any stray duplicate daemon of this install that slipped past the start
     // lock or was orphaned by a hard-crash — before it can double-fire jobs.
     try {
@@ -329,7 +345,12 @@ export async function runDaemon() {
         log('WARN', `Secrets broker host skipped: ${err.message}`);
     }
     const scheduler = new JobScheduler(async (config) => {
-        log('INFO', `Triggering job '${config.name}' (agent: ${config.agent})`);
+        const jobLabel = config.command
+            ? 'command'
+            : config.workflow
+                ? `workflow: ${config.workflow}`
+                : `agent: ${config.agent}`;
+        log('INFO', `Triggering job '${config.name}' (${jobLabel})`);
         try {
             const meta = await executeJobDetached(config);
             log('INFO', `Job '${config.name}' spawned (run: ${meta.runId}, PID: ${meta.pid})`);
@@ -344,6 +365,16 @@ export async function runDaemon() {
     for (const job of scheduled) {
         log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
     }
+    // Monitor engine: event-triggered watchers, beside the cron scheduler. Same
+    // daemon, same dispatch seam — a monitor is a routine whose trigger is a
+    // watched source instead of a clock. Reloads on SIGHUP alongside the scheduler.
+    const monitorEngine = new MonitorEngine((level, message) => log(level, message));
+    try {
+        monitorEngine.start();
+    }
+    catch (err) {
+        log('ERROR', `Monitor engine failed to start: ${err.message}`);
+    }
     // Backlog detection: any enabled recurring job whose most-recent expected
     // fire is older than its most-recent recorded run is overdue. Happens when
     // the laptop was off or the daemon crashed through a scheduled fire.
@@ -598,6 +629,12 @@ export async function runDaemon() {
         scheduler.reloadAll();
         const reloaded = scheduler.listScheduled();
         log('INFO', `Reloaded ${reloaded.length} jobs`);
+        try {
+            monitorEngine.reload();
+        }
+        catch (err) {
+            log('ERROR', `Monitor engine reload failed: ${err.message}`);
+        }
         // Drop the memoized R2 config so rotated/added sync credentials are re-read
         // on the next cycle instead of waiting for a restart.
         void import('./session/sync/config.js').then(m => m.clearR2ConfigCache());
@@ -605,6 +642,7 @@ export async function runDaemon() {
     const handleShutdown = async () => {
         log('INFO', 'Daemon shutting down');
         scheduler.stopAll();
+        monitorEngine.stop();
         await browserIPC.stop();
         clearInterval(monitorInterval);
         clearInterval(syncInterval);
@@ -675,15 +713,18 @@ export function writeOwnerOnlyServiceManifest(filePath, content) {
     fs.rmSync(filePath, { force: true });
     fs.writeFileSync(filePath, content, { encoding: 'utf-8', mode: 0o600 });
 }
-/** Generate a macOS launchd plist for auto-starting the daemon. */
-export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken(), agentsBin = getAgentsBinPath()) {
+/**
+ * Generate a macOS launchd plist for auto-starting the daemon.
+ *
+ * The plist never embeds the Claude OAuth token (RUSH-1759): a persisted service
+ * manifest is a plaintext credential on disk even at 0600. The daemon instead
+ * obtains the token at startup from the `claude` secrets bundle
+ * (readDaemonClaudeOAuthToken, injected in runDaemon), so it stays in the
+ * Keychain-backed secure store and never touches the unit file.
+ */
+export function generateLaunchdPlist(agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
     const logPath = getLogPath();
-    const oauthEntry = oauthToken
-        ? `
-    <key>${DAEMON_OAUTH_KEY}</key>
-    <string>${xmlEscape(oauthToken)}</string>`
-        : '';
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -705,7 +746,7 @@ ${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin</string>${oauthEntry}
+    <string>${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin</string>
   </dict>
 </dict>
 </plist>`;
@@ -714,13 +755,18 @@ ${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</
 function systemdExecArg(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
-/** Generate a Linux systemd user unit for auto-starting the daemon. */
-export function generateSystemdUnit(oauthToken = readDaemonClaudeOAuthToken(), agentsBin = getAgentsBinPath()) {
+/**
+ * Generate a Linux systemd user unit for auto-starting the daemon.
+ *
+ * The unit never embeds the Claude OAuth token (RUSH-1759): a persisted service
+ * manifest is a plaintext credential on disk even at 0600. The daemon instead
+ * obtains the token at startup from the `claude` secrets bundle
+ * (readDaemonClaudeOAuthToken, injected in runDaemon), so it stays in the secure
+ * store and never touches the unit file.
+ */
+export function generateSystemdUnit(agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
     const execStart = [launch.command, ...launch.args].map(systemdExecArg).join(' ');
-    const oauthLine = oauthToken
-        ? `\nEnvironment=${DAEMON_OAUTH_KEY}=${oauthToken}`
-        : '';
     return `[Unit]
 Description=Agents Daemon - Scheduled Job Runner
 After=network.target
@@ -730,7 +776,7 @@ Type=simple
 ExecStart=${execStart}
 Restart=always
 RestartSec=10
-Environment=PATH=${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin${oauthLine}
+Environment=PATH=${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin
 
 [Install]
 WantedBy=default.target`;
@@ -847,9 +893,10 @@ function startDaemonLocked(agentsBin) {
             if (!fs.existsSync(plistDir)) {
                 fs.mkdirSync(plistDir, { recursive: true });
             }
-            // The plist may embed a long-lived OAuth token in EnvironmentVariables;
-            // create owner-only atomically (no world-readable window before chmod).
-            writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist(undefined, agentsBin));
+            // The plist carries no credential (RUSH-1759 — the daemon reads the OAuth
+            // token itself at startup); still create owner-only atomically to match the
+            // detached path and keep the log/PATH surface owner-private.
+            writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist(agentsBin));
             try {
                 execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
@@ -876,8 +923,9 @@ function startDaemonLocked(agentsBin) {
             if (!fs.existsSync(unitDir)) {
                 fs.mkdirSync(unitDir, { recursive: true });
             }
-            // May embed a long-lived OAuth token in an Environment= line; owner-only.
-            writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit(undefined, agentsBin));
+            // Carries no credential (RUSH-1759 — the daemon reads the OAuth token
+            // itself at startup); owner-only to keep the PATH/log surface private.
+            writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit(agentsBin));
             execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'enable', SYSTEMD_UNIT], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'start', SYSTEMD_UNIT], { encoding: 'utf-8' });

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

@@ -7,8 +7,8 @@
  * throws (misconfigured auth, etc.) become `failed` rows — they never abort
  * the remaining devices.
  */
-import type { DeviceProfile, DeviceRegistry } from './registry.js';
-export type FleetSkipReason = 'offline' | 'no-address';
+import { type DeviceProfile, type DeviceRegistry } from './registry.js';
+export type FleetSkipReason = 'offline' | 'no-address' | 'control';
 /** npm dist-tags / semver pins only — rejects shell metacharacters. */
 export declare const FLEET_VERSION_RE: RegExp;
 export interface FleetTarget {
@@ -27,6 +27,7 @@ export interface FleetRunResult {
 /**
  * Classify each registered device for a fleet operation.
  *
+ * - Control-only device (a cockpit, e.g. a paired iPhone) → skip `control`
  * - Tailscale-offline → skip `offline`
  * - No address → skip `no-address`
  * - Everything else is a target (including this machine, reached over ssh when

package/dist/lib/devices/fleet.js

@@ -8,12 +8,14 @@
  * the remaining devices.
  */
 import { spawnSync } from 'child_process';
+import { isControlDevice } from './registry.js';
 import { buildSshInvocation, sshTargetFor, writeAskpassShim } from './connect.js';
 /** npm dist-tags / semver pins only — rejects shell metacharacters. */
 export const FLEET_VERSION_RE = /^[A-Za-z0-9._-]+$/;
 /**
  * Classify each registered device for a fleet operation.
  *
+ * - Control-only device (a cockpit, e.g. a paired iPhone) → skip `control`
  * - Tailscale-offline → skip `offline`
  * - No address → skip `no-address`
  * - Everything else is a target (including this machine, reached over ssh when
@@ -23,6 +25,11 @@ export function planFleetTargets(reg) {
     const names = Object.keys(reg).sort();
     return names.map((name) => {
         const device = reg[name];
+        // A control device drives the fleet but never runs agents — never a target
+        // for update/run/stats, whatever its platform reads as.
+        if (isControlDevice(device)) {
+            return { device, skip: 'control' };
+        }
         if (device.tailscale && !device.tailscale.online) {
             return { device, skip: 'offline' };
         }
@@ -42,6 +49,8 @@ export function skipLabel(reason) {
             return 'offline';
         case 'no-address':
             return 'no address';
+        case 'control':
+            return 'control device';
     }
 }
 /**

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

@@ -0,0 +1,77 @@
+/**
+ * Device resource probing for `agents devices list`.
+ *
+ * One SSH round-trip per device gathers load average, memory pressure, and core
+ * count (mac + linux), parsed into a {@link DeviceStats}. Probes run in parallel
+ * with a bounded timeout so the list stays responsive — a slow or hung box
+ * degrades to "no stats" instead of blocking the whole table.
+ *
+ * The parsers are pure and unit-tested (health.test.ts). They mirror the ones in
+ * the Factory extension (apps/factory/src/core/deviceHealth.ts) — kept as a
+ * separate copy on purpose: the CLI does not import across packages.
+ */
+import type { DeviceProfile } from './registry.js';
+/** Default per-device probe budget. Short enough that the list never hangs on a
+ * wedged box, long enough for a cold relayed SSH handshake. */
+export declare const PROBE_TIMEOUT_MS = 2500;
+export interface DeviceStats {
+    host: string;
+    reachable: boolean;
+    loadAvg1?: number;
+    ncpu?: number;
+    /** loadAvg1 / ncpu * 100 — load normalized to core count (the "has room" number). */
+    loadPercent?: number;
+    memPercent?: number;
+    memTotalBytes?: number;
+    memFreeBytes?: number;
+    fetchedAt: number;
+}
+/** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
+export declare function fmtBytes(bytes: number | undefined): string;
+export declare function parseUptime(out: string): {
+    loadAvg1?: number;
+};
+interface MemStats {
+    memPercent?: number;
+    memTotalBytes?: number;
+    memFreeBytes?: number;
+}
+export declare function parseVmStat(out: string): MemStats;
+export declare function parseLinuxMemInfo(out: string): MemStats;
+export declare function parseNcpu(out: string): {
+    ncpu?: number;
+};
+/** Assemble a DeviceStats from the three snippet sections. */
+export declare function parseProbeOutput(host: string, stdout: string, fetchedAt: number): DeviceStats;
+export interface FleetCapacity {
+    reachable: number;
+    cores: number;
+    memTotalBytes: number;
+    memFreeBytes: number;
+}
+/** Sum cores and memory across reachable devices for the summary footer. */
+export declare function fleetCapacity(statsList: Iterable<DeviceStats>): FleetCapacity;
+/** Headroom bucket from the worst of normalized-load and memory. */
+export type Headroom = 'idle' | 'light' | 'busy' | 'loaded' | 'unknown';
+export declare function headroom(stats: DeviceStats | undefined): Headroom;
+/** Probe one device over the same ssh path as `agents ssh <name>`. Never throws;
+ * an unreachable/slow/misconfigured device resolves to `reachable: false`. */
+export declare function probeDeviceStats(device: DeviceProfile, opts?: {
+    timeoutMs?: number;
+    now?: number;
+}): Promise<DeviceStats>;
+/** Probe the local machine directly (no ssh round-trip) — used for the "this
+ * machine" row so it always shows real numbers even if it isn't ssh-reachable
+ * from itself. */
+export declare function probeLocalStats(host: string, opts?: {
+    timeoutMs?: number;
+    now?: number;
+}): Promise<DeviceStats>;
+/** Probe many devices concurrently; returns a name→stats map. Bounded by the
+ * per-probe timeout, so total wall time ≈ the slowest single probe. The device
+ * named `selfName` is probed locally instead of over ssh. */
+export declare function probeFleetStats(devices: DeviceProfile[], opts?: {
+    timeoutMs?: number;
+    selfName?: string;
+}): Promise<Map<string, DeviceStats>>;
+export {};

package/dist/lib/devices/health.js

@@ -0,0 +1,186 @@
+/**
+ * Device resource probing for `agents devices list`.
+ *
+ * One SSH round-trip per device gathers load average, memory pressure, and core
+ * count (mac + linux), parsed into a {@link DeviceStats}. Probes run in parallel
+ * with a bounded timeout so the list stays responsive — a slow or hung box
+ * degrades to "no stats" instead of blocking the whole table.
+ *
+ * The parsers are pure and unit-tested (health.test.ts). They mirror the ones in
+ * the Factory extension (apps/factory/src/core/deviceHealth.ts) — kept as a
+ * separate copy on purpose: the CLI does not import across packages.
+ */
+import { execFile } from 'child_process';
+import { buildSshInvocation, writeAskpassShim } from './connect.js';
+/** Default per-device probe budget. Short enough that the list never hangs on a
+ * wedged box, long enough for a cold relayed SSH handshake. */
+export const PROBE_TIMEOUT_MS = 2_500;
+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)`;
+/** Compact human byte size: 512M, 64G, 1.5T (binary units, ≤1 decimal). */
+export function fmtBytes(bytes) {
+    if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
+        return '—';
+    const units = ['B', 'K', 'M', 'G', 'T', 'P'];
+    let v = bytes;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    const s = v >= 100 || i <= 1 ? Math.round(v).toString() : v.toFixed(1).replace(/\.0$/, '');
+    return `${s}${units[i]}`;
+}
+export function parseUptime(out) {
+    const m = out.match(/load average[s]?:\s*([0-9]+[.,][0-9]+|[0-9]+)/i);
+    if (!m)
+        return {};
+    const v = parseFloat(m[1].replace(',', '.'));
+    if (!Number.isFinite(v))
+        return {};
+    return { loadAvg1: v };
+}
+export function parseVmStat(out) {
+    const pageSize = parseInt(out.match(/page size of\s+([0-9]+)\s+bytes/)?.[1] ?? '4096', 10);
+    const active = out.match(/Pages active:\s+([0-9]+)/);
+    const wired = out.match(/Pages wired down:\s+([0-9]+)/);
+    const compressed = out.match(/Pages occupied by compressor:\s+([0-9]+)/);
+    const free = out.match(/Pages free:\s+([0-9]+)/);
+    if (!active || !wired || !compressed || !free)
+        return {};
+    // macOS reclaims inactive + speculative pages on demand, so they count as
+    // available — folding them into "free" (as Activity Monitor / vm_pressure do)
+    // rather than "used" keeps the headroom bucket honest on a Mac.
+    const inactive = out.match(/Pages inactive:\s+([0-9]+)/);
+    const speculative = out.match(/Pages speculative:\s+([0-9]+)/);
+    const usedPages = parseInt(active[1], 10) + parseInt(wired[1], 10) + parseInt(compressed[1], 10);
+    const freePages = parseInt(free[1], 10) +
+        parseInt(inactive?.[1] ?? '0', 10) +
+        parseInt(speculative?.[1] ?? '0', 10);
+    const totalPages = usedPages + freePages;
+    if (totalPages <= 0)
+        return {};
+    return {
+        memPercent: (usedPages / totalPages) * 100,
+        memTotalBytes: totalPages * pageSize,
+        memFreeBytes: freePages * pageSize,
+    };
+}
+export function parseLinuxMemInfo(out) {
+    const total = out.match(/^MemTotal:\s+([0-9]+)/im);
+    const available = out.match(/^MemAvailable:\s+([0-9]+)/im);
+    if (!total || !available)
+        return {};
+    const tKb = parseInt(total[1], 10);
+    const aKb = parseInt(available[1], 10);
+    if (tKb <= 0)
+        return {};
+    return {
+        memPercent: Math.max(0, Math.min(100, ((tKb - aKb) / tKb) * 100)),
+        memTotalBytes: tKb * 1024,
+        memFreeBytes: aKb * 1024,
+    };
+}
+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. */
+export function parseProbeOutput(host, stdout, fetchedAt) {
+    const [uptimePart = '', memPart = '', ncpuPart = ''] = stdout.split(SEP);
+    const { loadAvg1 } = parseUptime(uptimePart);
+    const mem = memPart.includes('MemTotal') ? parseLinuxMemInfo(memPart) : parseVmStat(memPart);
+    const { ncpu } = parseNcpu(ncpuPart);
+    const loadPercent = loadAvg1 !== undefined && ncpu ? (loadAvg1 / ncpu) * 100 : undefined;
+    return {
+        host,
+        reachable: true,
+        loadAvg1,
+        ncpu,
+        loadPercent,
+        memPercent: mem.memPercent,
+        memTotalBytes: mem.memTotalBytes,
+        memFreeBytes: mem.memFreeBytes,
+        fetchedAt,
+    };
+}
+/** Sum cores and memory across reachable devices for the summary footer. */
+export function fleetCapacity(statsList) {
+    const cap = { reachable: 0, cores: 0, memTotalBytes: 0, memFreeBytes: 0 };
+    for (const s of statsList) {
+        if (!s.reachable)
+            continue;
+        cap.reachable++;
+        cap.cores += s.ncpu ?? 0;
+        cap.memTotalBytes += s.memTotalBytes ?? 0;
+        cap.memFreeBytes += s.memFreeBytes ?? 0;
+    }
+    return cap;
+}
+export function headroom(stats) {
+    if (!stats || !stats.reachable)
+        return 'unknown';
+    const signals = [stats.loadPercent, stats.memPercent].filter((v) => typeof v === 'number');
+    if (signals.length === 0)
+        return 'unknown';
+    const worst = Math.max(...signals);
+    if (worst < 15)
+        return 'idle';
+    if (worst < 40)
+        return 'light';
+    if (worst < 75)
+        return 'busy';
+    return 'loaded';
+}
+/** Probe one device over the same ssh path as `agents ssh <name>`. Never throws;
+ * an unreachable/slow/misconfigured device resolves to `reachable: false`. */
+export function probeDeviceStats(device, opts = {}) {
+    const host = device.name;
+    const fetchedAt = opts.now ?? Date.now();
+    let args;
+    let env;
+    try {
+        const shim = writeAskpassShim();
+        // buildSshInvocation joins the cmd with spaces and hands the string to the
+        // remote login shell, which evaluates the snippet's `;`/`||` directly — no
+        // `sh -c` wrapper needed (and a wrapper would only re-quote the first token).
+        ({ args, env } = buildSshInvocation(device, [PROBE_SNIPPET], shim));
+    }
+    catch {
+        return Promise.resolve({ host, reachable: false, fetchedAt });
+    }
+    return new Promise((resolve) => {
+        execFile('ssh', args, { encoding: 'utf-8', env: { ...process.env, ...env }, timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS }, (err, stdout) => {
+            if (err || !stdout)
+                return resolve({ host, reachable: false, fetchedAt });
+            resolve(parseProbeOutput(host, stdout, fetchedAt));
+        });
+    });
+}
+/** Probe the local machine directly (no ssh round-trip) — used for the "this
+ * machine" row so it always shows real numbers even if it isn't ssh-reachable
+ * from itself. */
+export function probeLocalStats(host, opts = {}) {
+    const fetchedAt = opts.now ?? Date.now();
+    return new Promise((resolve) => {
+        execFile('sh', ['-c', PROBE_SNIPPET], { encoding: 'utf-8', timeout: opts.timeoutMs ?? PROBE_TIMEOUT_MS }, (err, stdout) => {
+            if (err || !stdout)
+                return resolve({ host, reachable: false, fetchedAt });
+            resolve(parseProbeOutput(host, stdout, fetchedAt));
+        });
+    });
+}
+/** Probe many devices concurrently; returns a name→stats map. Bounded by the
+ * per-probe timeout, so total wall time ≈ the slowest single probe. The device
+ * named `selfName` is probed locally instead of over ssh. */
+export async function probeFleetStats(devices, opts = {}) {
+    const entries = await Promise.all(devices.map(async (d) => {
+        const stats = d.name === opts.selfName
+            ? await probeLocalStats(d.name, opts)
+            : await probeDeviceStats(d, opts);
+        return [d.name, stats];
+    }));
+    return new Map(entries);
+}

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

@@ -1,5 +1,13 @@
 /** Operating-system family of a device, used to pick the remote shell. */
 export type DevicePlatform = 'windows' | 'linux' | 'macos' | 'unknown';
+/**
+ * What a device is *for*. A `worker` (the default) can run agents — it's dialed
+ * over SSH for sessions and eligible for run/team placement. A `control` device
+ * is a cockpit that drives the fleet but never executes agents itself (an
+ * iPhone/iPad running the companion app): it appears in the fleet but is never
+ * dialed for SSH nor scheduled work. Absent `role` means `worker`.
+ */
+export type DeviceRole = 'worker' | 'control';
 /** Remote shell dialect derived from the platform. */
 export type DeviceShell = 'powershell' | 'posix';
 /** How `agents ssh` authenticates to a device. Both are first-class, fully
@@ -41,9 +49,15 @@ export interface DeviceProfile {
     address: DeviceAddress;
     auth: DeviceAuth;
     tailscale?: DeviceTailscale;
+    /** What the device is for. Absent means `worker` (see {@link DeviceRole}). */
+    role?: DeviceRole;
     createdAt: string;
     updatedAt: string;
 }
+/** A device's effective role, defaulting to `worker` when unset. */
+export declare function deviceRole(d: DeviceProfile): DeviceRole;
+/** True for a control-only device (a cockpit) that must never be dialed/scheduled. */
+export declare function isControlDevice(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.). */
@@ -74,6 +88,7 @@ export interface DeviceInput {
     address?: DeviceAddress;
     auth?: DeviceAuth;
     tailscale?: DeviceTailscale;
+    role?: DeviceRole;
 }
 /**
  * Create the device if absent, otherwise merge the supplied fields into the

package/dist/lib/devices/registry.js

@@ -19,6 +19,14 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
 import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
+/** A device's effective role, defaulting to `worker` when unset. */
+export function deviceRole(d) {
+    return d.role ?? 'worker';
+}
+/** True for a control-only device (a cockpit) that must never be dialed/scheduled. */
+export function isControlDevice(d) {
+    return deviceRole(d) === 'control';
+}
 function registryPath() {
     return getDevicesRegistryPath();
 }
@@ -170,6 +178,7 @@ export async function upsertDevice(name, input) {
             address: input.address ?? prev?.address ?? { via: 'manual' },
             auth: input.auth ?? prev?.auth ?? { method: 'key' },
             tailscale: input.tailscale ?? prev?.tailscale,
+            role: input.role ?? prev?.role,
             createdAt: prev?.createdAt ?? now,
             updatedAt: now,
         };

package/dist/lib/exec.d.ts

@@ -120,6 +120,15 @@ export interface ExecOptions {
     mcpConfigPath?: string;
     /** Raw args captured after `--` on the command line, forwarded verbatim to the underlying agent CLI. */
     passthroughArgs?: string[];
+    /**
+     * Tee-and-tail the child's stdout even when no budget cap is active, so the
+     * caller can scan it for rate/usage-limit messages. Claude prints billing
+     * refusals ("monthly spend limit", "out of usage credits") to STDOUT, not
+     * stderr — a fallback chain that only inspects stderr never cascades on
+     * them. Set by runWithFallback for every chain entry; harmless elsewhere
+     * (output is mirrored to the parent's stdout exactly like stdio:'inherit').
+     */
+    captureStdoutTail?: boolean;
     /**
      * Escape hatch for the interactive tmux spawn-wrap (see shouldWrapInTmux):
      * when true, spawn the agent directly instead of inside a shared-socket tmux
@@ -150,7 +159,7 @@ export declare function resolveInteractive(options: Pick<ExecOptions, 'interacti
  * @param piped        true when the parent's stdout is NOT a TTY (output piped)
  * @param capsActive   true when a budget watcher is attached (caps configured)
  */
-export declare function shouldTapStdout(interactive: boolean, piped: boolean, capsActive: boolean): boolean;
+export declare function shouldTapStdout(interactive: boolean, piped: boolean, capsActive: boolean, captureTail?: boolean): boolean;
 /** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
 /**
@@ -274,8 +283,16 @@ export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;
  *     `#{pane_pid}`, clean signal delivery on detach/kill).
  * Keys are filtered to valid identifiers so exported shell functions
  * (`BASH_FUNC_*%%`) can't make `env` choke.
+ *
+ * `redactEnvValues` replaces every value with a `<redacted>` marker while keeping
+ * the KEY names. The env map here carries resolved secrets bundles (options.env),
+ * so the real string would embed secret VALUES — which get persisted verbatim
+ * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
+ * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
-export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv): string;
+export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv, opts?: {
+    redactEnvValues?: boolean;
+}): string;
 /**
  * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
  * (right-stripping each). Used by runInTmux to recap a fast-failed agent's