@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/daemon.js

@@ -13,10 +13,13 @@ import * as os from 'os';
 import { getDaemonDir as getDaemonDirRoot } from './state.js';
 import { isAlive, killTree, backgroundSpawnOptions } from './platform/index.js';
 import { listJobs as listAllJobs } from './routines.js';
+import { syncAllProjectRoutines } from './routines-project.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 { notifyDesktop } from './menubar/notify-desktop.js';
+import { notifyRoutineStart, notifyRoutineFinish, notifyRoutineStartFailed } from './routine-notify.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
 import { readAndResolveBundleEnv } from './secrets/bundles.js';
@@ -315,10 +318,36 @@ export async function runDaemon() {
     // 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();
+        const bundleEnv = readDaemonClaudeBundleEnv();
+        const oauthToken = (bundleEnv[DAEMON_OAUTH_KEY] ?? '').trim();
         if (oauthToken) {
             process.env.CLAUDE_CODE_OAUTH_TOKEN = oauthToken;
-            log('INFO', 'Loaded Claude OAuth token from secrets bundle for routine runs');
+            // Also inject each per-account CLAUDE_CODE_OAUTH_TOKEN_<slug> present in the
+            // bundle, so a routine authenticates its rotation-pinned account via that
+            // account's own long-lived, non-rotating setup-token (runner.ts
+            // buildRoutineSpawnEnv) instead of the interactive session that rotates and
+            // logs the fleet out (Claude Code #25609 / #56339).
+            let perAccount = 0;
+            for (const [k, v] of Object.entries(bundleEnv)) {
+                if (k.startsWith('CLAUDE_CODE_OAUTH_TOKEN_') && (v ?? '').trim() && !process.env[k]) {
+                    process.env[k] = v.trim();
+                    perAccount++;
+                }
+            }
+            log('INFO', `Loaded Claude OAuth token from secrets bundle for routine runs${perAccount ? ` (+${perAccount} per-account)` : ''}`);
+        }
+        else {
+            // No token available (e.g. a headless macOS daemon whose keychain was
+            // locked at start resolves broker-only and gets nothing). Historically
+            // this was silent, so every Claude routine the daemon spawned failed auth
+            // with no signal. Make it loud: WARN in the log and fire a desktop alert.
+            log('WARN', 'No Claude OAuth token available — Claude routine runs will fail auth on this host. ' +
+                'Restart the daemon with the keychain unlocked, or unlock the `claude` secrets bundle.');
+            notifyDesktop({
+                title: 'agents daemon: no Claude credential',
+                body: 'Claude routines will fail auth on this host. Restart the daemon with the keychain unlocked.',
+                action: 'routines:list',
+            });
         }
     }
     // Reap any stray duplicate daemon of this install that slipped past the start
@@ -363,14 +392,50 @@ export async function runDaemon() {
                 ? `workflow: ${config.workflow}`
                 : `agent: ${config.agent}`;
         log('INFO', `Triggering job '${config.name}' (${jobLabel})`);
+        // RUSH-2030: branded desktop notification on start (agent/workflow routines;
+        // suppressed for command housekeeping). Finish/output is fired from the
+        // onFinish hook below — executeJobDetached finalizes the run in-process, so
+        // the monitor tick never sees the live transition. Never let a notification
+        // failure break the trigger.
         try {
-            const meta = await executeJobDetached(config);
+            notifyRoutineStart(config);
+        }
+        catch { /* best-effort */ }
+        try {
+            const meta = await executeJobDetached(config, {
+                onFinish: (final) => {
+                    try {
+                        notifyRoutineFinish(final);
+                    }
+                    catch { /* best-effort */ }
+                },
+            });
             log('INFO', `Job '${config.name}' spawned (run: ${meta.runId}, PID: ${meta.pid})`);
         }
         catch (err) {
-            log('ERROR', `Job '${config.name}' failed to spawn: ${err.message}`);
+            const message = err.message;
+            log('ERROR', `Job '${config.name}' failed to spawn: ${message}`);
+            // RUSH-2030: the START ping already fired unconditionally above. A pre-spawn
+            // failure produces no run record and thus no onFinish, so send a synthetic
+            // "failed to start" finish here — otherwise the user is left with an orphaned
+            // "Routine started" and never told it failed.
+            try {
+                notifyRoutineStartFailed(config, message);
+            }
+            catch { /* best-effort */ }
         }
     });
+    // Materialise opted-in project routines into the user layer on every start
+    // so a fresh daemon picks up project YAML without a separate sync step.
+    try {
+        const result = syncAllProjectRoutines();
+        const n = result.projects.reduce((acc, p) => acc + p.synced.length, 0);
+        if (n > 0)
+            log('INFO', `Project routines sync: ${n} job(s) from ${result.projects.length} project(s)`);
+    }
+    catch (err) {
+        log('WARN', `Project routines sync failed: ${err.message}`);
+    }
     scheduler.loadAll();
     const scheduled = scheduler.listScheduled();
     log('INFO', `Loaded ${scheduled.length} jobs`);
@@ -623,9 +688,16 @@ export async function runDaemon() {
         checkingLaunchHealth = true;
         try {
             const { healBrokenDefaultLaunches } = await import('./versions.js');
-            const repaired = await healBrokenDefaultLaunches((m) => log('INFO', `launch-health: ${m}`));
+            // Unattended pass: repair the current default in place, but NEVER repoint
+            // the global default (allowDefaultSwitch: false). A background default
+            // switch installs a fresh version home → a fresh empty Claude credential
+            // scope, i.e. a silent logout uncorrelated with anything the user did.
+            const { repaired, unhealed } = await healBrokenDefaultLaunches((m) => log('INFO', `launch-health: ${m}`), { allowDefaultSwitch: false });
             if (repaired.length)
                 log('INFO', `launch-health: repaired ${repaired.join(', ')}`);
+            if (unhealed.length) {
+                log('WARN', `launch-health: ${unhealed.join(', ')} won't launch and will not be auto-switched — choose a version with \`agents use <agent> <version>\` or \`agents add <agent>@latest\``);
+            }
         }
         catch (err) {
             log('ERROR', `launch-health check failed: ${err.message}`);
@@ -705,6 +777,19 @@ export async function runDaemon() {
     const brokerSelfHealInterval = setInterval(() => { void runBrokerSelfHeal(); }, 60_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
+        // Refresh user-layer copies of opted-in project routines BEFORE the
+        // scheduler reloads, so YAML edits under `<project>/.agents/routines/`
+        // take effect on the next fire without a manual `routines sync`.
+        try {
+            const result = syncAllProjectRoutines();
+            const n = result.projects.reduce((acc, p) => acc + p.synced.length, 0);
+            if (n > 0 || result.missing.length > 0) {
+                log('INFO', `Project routines sync: ${n} updated, ${result.missing.length} missing roots`);
+            }
+        }
+        catch (err) {
+            log('WARN', `Project routines sync failed: ${err.message}`);
+        }
         scheduler.reloadAll();
         const reloaded = scheduler.listScheduled();
         log('INFO', `Reloaded ${reloaded.length} jobs`);
@@ -758,17 +843,26 @@ export async function runDaemon() {
  * token leaves the daemon on its existing interactive OAuth session.
  */
 export function readDaemonClaudeOAuthToken(opts = {}) {
+    const token = (readDaemonClaudeBundleEnv(opts)[DAEMON_OAUTH_KEY] ?? '').trim();
+    return token.length > 0 ? token : null;
+}
+/**
+ * Read the FULL `claude` bundle env — the main `CLAUDE_CODE_OAUTH_TOKEN` plus any
+ * per-account `CLAUDE_CODE_OAUTH_TOKEN_<slug>` setup-tokens. Same resolution and
+ * never-throws contract as {@link readDaemonClaudeOAuthToken}; returns `{}` when
+ * the bundle can't be read (broker-only headless miss, absent bundle, etc.).
+ */
+export function readDaemonClaudeBundleEnv(opts = {}) {
     try {
         const allowPrompt = opts.allowPrompt ?? Boolean(process.stdin.isTTY);
         const { env } = readAndResolveBundleEnv(DAEMON_OAUTH_BUNDLE, {
             caller: 'daemon',
             agentOnly: !allowPrompt,
         });
-        const token = (env[DAEMON_OAUTH_KEY] ?? '').trim();
-        return token.length > 0 ? token : null;
+        return env;
     }
     catch {
-        return null;
+        return {};
     }
 }
 /** Escape a string for safe inclusion in an XML <string> node. */
@@ -996,11 +1090,20 @@ function startDaemonLocked(agentsBin) {
  * the daemon then passes it to every routine run it spawns. An already-set
  * value (e.g. inherited from launchd) is left untouched.
  */
-export function buildDetachedDaemonEnv(baseEnv = process.env, oauthToken = readDaemonClaudeOAuthToken()) {
+export function buildDetachedDaemonEnv(baseEnv = process.env, bundleEnv = readDaemonClaudeBundleEnv()) {
     const env = { ...baseEnv };
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
-        if (oauthToken)
-            env.CLAUDE_CODE_OAUTH_TOKEN = oauthToken;
+        const main = (bundleEnv[DAEMON_OAUTH_KEY] ?? '').trim();
+        if (main)
+            env.CLAUDE_CODE_OAUTH_TOKEN = main;
+    }
+    // Per-account setup-tokens — same rationale as the runDaemon startup injection:
+    // a routine authenticates its rotation-pinned account via that account's own
+    // long-lived, non-rotating token. An already-set value wins.
+    for (const [k, v] of Object.entries(bundleEnv)) {
+        if (k.startsWith('CLAUDE_CODE_OAUTH_TOKEN_') && (v ?? '').trim() && !env[k]) {
+            env[k] = v.trim();
+        }
     }
     return env;
 }

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

@@ -3,6 +3,14 @@ import { type DeviceProfile } from './registry.js';
 export declare const ASKPASS_BUNDLE_ENV = "AGENTS_SSH_BUNDLE";
 /** Env var the askpass shim reads to know which key in the bundle is the password. */
 export declare const ASKPASS_KEY_ENV = "AGENTS_SSH_KEY";
+/**
+ * Env var that forces the askpass bundle resolve to be broker-only (`agentOnly`)
+ * regardless of TTY. A read-only stats probe (`agents devices` load/mem columns)
+ * sets this so an uncached password-auth device resolves from the already-unlocked
+ * secrets broker or degrades to an unreachable row — never a foreground Touch ID
+ * sheet. See {@link buildSshInvocation}'s `agentOnly` option and `runAskpass`. (RUSH-1970)
+ */
+export declare const ASKPASS_AGENT_ONLY_ENV = "AGENTS_SSH_AGENT_ONLY";
 /**
  * Build the `user@host` (or bare `host`) ssh target for a device and validate
  * it against the shared injection guard. Throws if the device has no address.
@@ -51,8 +59,14 @@ export interface SshHostKeyOptions {
  * Host-key checking runs against the CLI-managed known_hosts store (never the
  * user's `~/.ssh/known_hosts`): strict once `hostKey.pinned` is set, else
  * `accept-new` to learn+pin the key on first connect (RUSH-1767).
+ *
+ * `opts.agentOnly` marks the connection as a read-only probe: for password auth
+ * it sets {@link ASKPASS_AGENT_ONLY_ENV} in the overlay so the askpass resolve
+ * stays broker-only and never pops a foreground biometric (RUSH-1970).
  */
-export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string, hostKey?: SshHostKeyOptions): {
+export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string, hostKey?: SshHostKeyOptions, opts?: {
+    agentOnly?: boolean;
+}): {
     args: string[];
     env: Record<string, string>;
 };

package/dist/lib/devices/connect.js

@@ -25,6 +25,14 @@ import { hostNameFor } from './ssh-config.js';
 export const ASKPASS_BUNDLE_ENV = 'AGENTS_SSH_BUNDLE';
 /** Env var the askpass shim reads to know which key in the bundle is the password. */
 export const ASKPASS_KEY_ENV = 'AGENTS_SSH_KEY';
+/**
+ * Env var that forces the askpass bundle resolve to be broker-only (`agentOnly`)
+ * regardless of TTY. A read-only stats probe (`agents devices` load/mem columns)
+ * sets this so an uncached password-auth device resolves from the already-unlocked
+ * secrets broker or degrades to an unreachable row — never a foreground Touch ID
+ * sheet. See {@link buildSshInvocation}'s `agentOnly` option and `runAskpass`. (RUSH-1970)
+ */
+export const ASKPASS_AGENT_ONLY_ENV = 'AGENTS_SSH_AGENT_ONLY';
 /**
  * Build the `user@host` (or bare `host`) ssh target for a device and validate
  * it against the shared injection guard. Throws if the device has no address.
@@ -83,8 +91,12 @@ export function wrapRemoteCommand(device, cmd) {
  * Host-key checking runs against the CLI-managed known_hosts store (never the
  * user's `~/.ssh/known_hosts`): strict once `hostKey.pinned` is set, else
  * `accept-new` to learn+pin the key on first connect (RUSH-1767).
+ *
+ * `opts.agentOnly` marks the connection as a read-only probe: for password auth
+ * it sets {@link ASKPASS_AGENT_ONLY_ENV} in the overlay so the askpass resolve
+ * stays broker-only and never pops a foreground biometric (RUSH-1970).
  */
-export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}) {
+export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}, opts = {}) {
     const target = sshTargetFor(device);
     const remote = wrapRemoteCommand(device, cmd);
     const env = {};
@@ -100,6 +112,8 @@ export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}) {
         env.SSH_ASKPASS_REQUIRE = 'force';
         env[ASKPASS_BUNDLE_ENV] = device.auth.bundle;
         env[ASKPASS_KEY_ENV] = device.auth.bundleKey ?? 'password';
+        if (opts.agentOnly)
+            env[ASKPASS_AGENT_ONLY_ENV] = '1';
         args.push('-o', 'PreferredAuthentications=password', '-o', 'PubkeyAuthentication=no', '-o', 'NumberOfPasswordPrompts=1');
     }
     else {

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

@@ -8,6 +8,7 @@
  * the remaining devices.
  */
 import { type DeviceProfile, type DeviceRegistry } from './registry.js';
+import type { DeviceStats } from './health.js';
 export type FleetSkipReason = 'offline' | 'no-address' | 'control';
 /** npm dist-tags / semver pins only — rejects shell metacharacters. */
 export declare const FLEET_VERSION_RE: RegExp;
@@ -55,6 +56,26 @@ export declare function planFleetTargets(reg: DeviceRegistry): FleetTarget[];
  * surface — so their `skip` reason still flows through as an `unreachable` row.
  */
 export declare function remoteFleetTargets(planned: FleetTarget[], self: string): FleetTarget[];
+/**
+ * Decide whether a fleet-health target should skip the expensive version+doctor
+ * dials (`agents fleet status`). The cheap stats probe (~2.5s, same registry
+ * address) has already tried this box one step earlier. If it came back
+ * unreachable, dialing `agents --version` (15s) + `agents doctor --json` (30s)
+ * would almost certainly fail the same way — just 45s slower — so one
+ * genuinely-offline box would stall the whole matrix (the ~60s hang, RUSH-1964).
+ *
+ * We trust the stats verdict on the DEFAULT path, not only under
+ * `--refresh`/`--live`: `probeDeviceStats` and the version/doctor dials share
+ * one ssh path (`fleetDialTarget`), so reachability is not per-probe. The
+ * verdict is either freshly probed this run or daemon-warmed (~3min) with the
+ * live write-back from RUSH-1965, so a box that came online in the last few
+ * minutes is the only false-negative window — it renders `unreachable` until the
+ * next stats warm, which beats letting it hang the status glance for 45s.
+ *
+ * An existing skip (control/offline/no-address from {@link planFleetTargets})
+ * always wins — those are classified before any probe.
+ */
+export declare function fleetHealthSkip(currentSkip: FleetSkipReason | string | undefined, stats: DeviceStats | undefined): FleetSkipReason | string | undefined;
 /** Human label for a skip reason. */
 export declare function skipLabel(reason: FleetSkipReason): string;
 /**
@@ -115,5 +136,20 @@ export interface RunFleetOptions {
  * recorded as `failed` so one bad device never aborts the rest.
  */
 export declare function runFleet(targets: FleetTarget[], cmd: string[], opts?: RunFleetOptions): FleetRunResult[];
+export interface FanOutDeviceOptions {
+    /**
+     * Per-device deadline in milliseconds. When set, any probe that does not
+     * settle within this window is abandoned via `Promise.race` against a
+     * rejection timer and recorded as a `failed` result with the message
+     * `'timed out'`. There is no AbortController — the underlying probe
+     * continues running in the background; cancellation of the in-flight work
+     * is the caller's responsibility. In practice `probeRemoteAuth` relies on
+     * `sshExecAsync`'s own 15 s timer to kill the ssh child independently.
+     * The per-device ssh timeout passed directly to {@link sshExecAsync} is
+     * the first line of defence; this acts as a hard backstop so one slow
+     * device can never stall the entire fan-out past its budget.
+     */
+    perDeviceTimeoutMs?: number;
+}
 /** Run one async probe per device in parallel, preserving input order. */
-export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>): Promise<FanOutDeviceResult<T>[]>;
+export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>, opts?: FanOutDeviceOptions): Promise<FanOutDeviceResult<T>[]>;

package/dist/lib/devices/fleet.js

@@ -54,6 +54,32 @@ export function planFleetTargets(reg) {
 export function remoteFleetTargets(planned, self) {
     return planned.filter((t) => t.device.name !== self && t.skip !== 'control');
 }
+/**
+ * Decide whether a fleet-health target should skip the expensive version+doctor
+ * dials (`agents fleet status`). The cheap stats probe (~2.5s, same registry
+ * address) has already tried this box one step earlier. If it came back
+ * unreachable, dialing `agents --version` (15s) + `agents doctor --json` (30s)
+ * would almost certainly fail the same way — just 45s slower — so one
+ * genuinely-offline box would stall the whole matrix (the ~60s hang, RUSH-1964).
+ *
+ * We trust the stats verdict on the DEFAULT path, not only under
+ * `--refresh`/`--live`: `probeDeviceStats` and the version/doctor dials share
+ * one ssh path (`fleetDialTarget`), so reachability is not per-probe. The
+ * verdict is either freshly probed this run or daemon-warmed (~3min) with the
+ * live write-back from RUSH-1965, so a box that came online in the last few
+ * minutes is the only false-negative window — it renders `unreachable` until the
+ * next stats warm, which beats letting it hang the status glance for 45s.
+ *
+ * An existing skip (control/offline/no-address from {@link planFleetTargets})
+ * always wins — those are classified before any probe.
+ */
+export function fleetHealthSkip(currentSkip, stats) {
+    if (currentSkip)
+        return currentSkip;
+    if (stats?.reachable === false)
+        return 'unreachable';
+    return undefined;
+}
 /** Human label for a skip reason. */
 export function skipLabel(reason) {
     switch (reason) {
@@ -186,7 +212,7 @@ export function runFleet(targets, cmd, opts = {}) {
     return results;
 }
 /** Run one async probe per device in parallel, preserving input order. */
-export async function fanOutDevices(targets, probe) {
+export async function fanOutDevices(targets, probe, opts = {}) {
     return Promise.all(targets.map(async (target) => {
         if (target.skip) {
             return {
@@ -196,10 +222,18 @@ export async function fanOutDevices(targets, probe) {
             };
         }
         try {
+            let probePromise = probe(target);
+            if (opts.perDeviceTimeoutMs) {
+                const timeoutMs = opts.perDeviceTimeoutMs;
+                probePromise = Promise.race([
+                    probePromise,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('timed out')), timeoutMs)),
+                ]);
+            }
             return {
                 name: target.name,
                 status: 'ok',
-                value: await probe(target),
+                value: await probePromise,
             };
         }
         catch (err) {

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

@@ -1,5 +1,6 @@
 import { type DeviceStats } from './health.js';
 import { type HostAuthSummary } from '../auth-health.js';
+import type { OnlineState } from './reachability.js';
 export interface FleetCliStatus {
     installed: boolean;
     path: string | null;
@@ -32,6 +33,13 @@ export interface FleetHealthRow {
     /** Cached auth-health rollup for this host (the Auth column). Undefined when
      *  the host has never been probed (`agents fleet ping`) or the cache is cold. */
     auth?: HostAuthSummary;
+    /** Resolved online/offline verdict (from {@link deviceOnlineState}). Populated
+     *  by `runFleetStatus` for the summary view; undefined in the raw grid. */
+    online?: OnlineState;
+    /** When this box was last seen reachable (ISO), for the "last seen …" note on
+     *  an offline row. Sourced from the registry's tailscale snapshot / reachability
+     *  verdict. Undefined when never recorded. */
+    lastSeen?: string;
 }
 export interface FleetWarning {
     kind: 'unreachable' | 'drift' | 'cli' | 'version-skew';
@@ -55,3 +63,33 @@ export declare function renderFleetMatrix(report: FleetHealthReport): string[];
  * table carries no timestamped data at all (nothing to date).
  */
 export declare function freshnessFooter(rows: FleetHealthRow[], now?: number): string | null;
+/** Collapse a long dev build (`0.0.0-dev.<sha>[-dirty]`) to `dev`/`dev-dirty`;
+ *  released semver is shown verbatim. Keeps the version column narrow and stops
+ *  a single dev box from widening every row. */
+export declare function shortVersion(version: string | null | undefined): string;
+/** OS bucket label for grouping. Anything unrecognized falls under "Other". */
+export declare function platformGroupLabel(platform: string | undefined): 'macOS' | 'Linux' | 'Windows' | 'Other';
+export interface FleetAttentionItem {
+    /** Leading mark: `○` offline, `⚠` config/CLI/version issue. */
+    glyph: 'offline' | 'warn';
+    subject: string;
+    detail: string;
+    /** The exact command (or instruction) that fixes it. */
+    fix: string;
+}
+/**
+ * The actionable problems only — each with the command that fixes it. Order:
+ * offline boxes, CLI gaps, active-version config drift, then version skew.
+ * A healthy fleet returns `[]` (the caller prints an all-clear line).
+ */
+export declare function buildFleetAttentionItems(report: FleetHealthReport, now?: number): FleetAttentionItem[];
+/**
+ * The default `agents fleet status` view (RUSH-1966): a one-line rollup, a
+ * NEEDS ATTENTION list of only the actionable problems (each with its fix
+ * command), quiet per-device rows grouped by OS, and an honest footer. The full
+ * auth/CLI/sync grid moves behind `--verbose` ({@link renderFleetMatrix}).
+ */
+export declare function renderFleetSummary(report: FleetHealthReport, opts?: {
+    self?: string;
+    now?: number;
+}): string[];

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

@@ -226,3 +226,217 @@ export function freshnessFooter(rows, now = Date.now()) {
         return null;
     return `  updated ${parts.join(' · ')} — pass --refresh (--live) for a live probe`;
 }
+// ---------------------------------------------------------------------------
+// Summary view (default): rollup + NEEDS ATTENTION + OS groups + footer.
+// The full grid above is kept for `--verbose`. (RUSH-1966)
+// ---------------------------------------------------------------------------
+/** Collapse a long dev build (`0.0.0-dev.<sha>[-dirty]`) to `dev`/`dev-dirty`;
+ *  released semver is shown verbatim. Keeps the version column narrow and stops
+ *  a single dev box from widening every row. */
+export function shortVersion(version) {
+    if (!version)
+        return '—';
+    const m = version.match(/-dev\b/);
+    if (m)
+        return /dirty/.test(version) ? 'dev-dirty' : 'dev';
+    return version;
+}
+/** OS bucket label for grouping. Anything unrecognized falls under "Other". */
+export function platformGroupLabel(platform) {
+    const p = (platform ?? '').toLowerCase();
+    if (p === 'macos' || p === 'darwin')
+        return 'macOS';
+    if (p === 'linux')
+        return 'Linux';
+    if (p.startsWith('win'))
+        return 'Windows';
+    return 'Other';
+}
+const GROUP_ORDER = ['macOS', 'Linux', 'Windows', 'Other'];
+/** Non-fresh sync rows for the ACTIVE (default) version only — the drift that a
+ *  running install actually feels, not stale/cold counts across old orphans. */
+function activeDriftRows(row) {
+    return row.sync.filter((s) => s.isDefault && s.status !== 'fresh');
+}
+function isOffline(row) {
+    // Prefer the resolved verdict; fall back to a probe error/skip when the caller
+    // didn't populate it (e.g. a raw report). Only a positive 'online' is "up".
+    if (row.online)
+        return row.online !== 'online';
+    return Boolean(row.error || row.skipped);
+}
+/** A box with a real offline verdict — as opposed to `unknown` (registered but
+ *  never addressed/probed). Only a genuine offline is a "check the box" item;
+ *  an unknown box is unconfigured, not down. */
+function isGenuinelyOffline(row) {
+    return row.online === 'offline' || (!row.online && Boolean(row.error || row.skipped));
+}
+/** A CLI count is only worth flagging when it's stark — the box is missing more
+ *  than two-thirds of the known agent CLIs (e.g. 1/9), which signals a
+ *  broken/half-set-up box. A normal partial install (a box that just doesn't run
+ *  every agent) is not a problem, so this deliberately does NOT fire at 4/9 or
+ *  6/9. The full count stays visible under `--verbose`. */
+function starkCliGap(row) {
+    const { installed, total } = installedCliCount(row);
+    return total > 0 && installed * 3 < total ? { installed, total } : null;
+}
+/**
+ * The actionable problems only — each with the command that fixes it. Order:
+ * offline boxes, CLI gaps, active-version config drift, then version skew.
+ * A healthy fleet returns `[]` (the caller prints an all-clear line).
+ */
+export function buildFleetAttentionItems(report, now = Date.now()) {
+    const items = [];
+    // 1) Genuinely-offline boxes (not `unknown`/unconfigured), each individually.
+    for (const row of report.devices) {
+        if (!isGenuinelyOffline(row))
+            continue;
+        const seen = row.lastSeen ? ` · last seen ${formatCheckedAge(Date.parse(row.lastSeen), now)}` : '';
+        items.push({ glyph: 'offline', subject: row.name, detail: `offline${seen}`, fix: 'check the box' });
+    }
+    // 2) Boxes that need `agents apply` — merge config drift and a stark CLI gap
+    // into ONE item per box (both are fixed by the same command, so don't
+    // double-list). An offline box's config/CLI is unknowable, so skip it.
+    for (const row of report.devices) {
+        if (isOffline(row))
+            continue;
+        const reasons = [];
+        if (activeDriftRows(row).length > 0)
+            reasons.push('config drift');
+        const stark = starkCliGap(row);
+        if (stark)
+            reasons.push(`only ${stark.installed} of ${stark.total} agent CLIs installed`);
+        if (reasons.length > 0) {
+            items.push({ glyph: 'warn', subject: row.name, detail: reasons.join(' · '), fix: `agents apply ${row.name}` });
+        }
+    }
+    // 3) Version skew across the fleet — one line.
+    const skew = report.warnings.find((w) => w.kind === 'version-skew');
+    if (skew) {
+        const counts = new Map();
+        for (const row of report.devices) {
+            if (!row.version)
+                continue;
+            const v = shortVersion(row.version);
+            counts.set(v, (counts.get(v) ?? 0) + 1);
+        }
+        const summary = Array.from(counts.entries())
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .map(([v, n]) => `${n}× ${v}`)
+            .join(' · ');
+        items.push({ glyph: 'warn', subject: 'version skew', detail: summary, fix: 'agents upgrade --fleet' });
+    }
+    return items;
+}
+/** Right-aligned `<content>` on the same line as `left`, clamped so it never
+ *  overlaps the left text on a narrow terminal. */
+function alignRight(left, right, width) {
+    const gap = width - stringWidth(left) - stringWidth(right);
+    return gap > 1 ? `${left}${' '.repeat(gap)}${right}` : `${left}  ${right}`;
+}
+function headroomWord(row) {
+    if (isOffline(row))
+        return chalk.gray(row.online === 'unknown' ? 'unknown' : 'offline');
+    return headroomLabel(row);
+}
+function loadMemCell(row) {
+    if (isOffline(row) || !row.stats?.reachable)
+        return chalk.gray('—');
+    const load = row.stats.loadPercent === undefined ? '—' : `${Math.round(row.stats.loadPercent)}%`;
+    const mem = row.stats.memPercent === undefined ? '—' : `${Math.round(row.stats.memPercent)}%`;
+    return `${load} / ${mem}`;
+}
+function versionCell(row) {
+    if (isOffline(row))
+        return chalk.gray('—');
+    return shortVersion(row.version);
+}
+/**
+ * The default `agents fleet status` view (RUSH-1966): a one-line rollup, a
+ * NEEDS ATTENTION list of only the actionable problems (each with its fix
+ * command), quiet per-device rows grouped by OS, and an honest footer. The full
+ * auth/CLI/sync grid moves behind `--verbose` ({@link renderFleetMatrix}).
+ */
+export function renderFleetSummary(report, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const width = terminalWidth();
+    const rows = report.devices;
+    if (rows.length === 0)
+        return [chalk.gray('No registered devices. Run `agents devices` to register some.')];
+    const online = rows.filter((r) => !isOffline(r)).length;
+    const offline = rows.length - online;
+    const oldestStats = oldestAcross(rows, (r) => r.stats?.fetchedAt);
+    const cachedAge = oldestStats != null ? `cached ${formatCheckedAge(oldestStats, now)}` : null;
+    const rollupRight = [opts.self, cachedAge].filter(Boolean).join(' · ');
+    const rollupLeft = `${chalk.bold('Fleet')}   ${chalk.green('●')} ${online} online   ${chalk.gray('○')} ${offline} offline`;
+    const lines = [rollupRight ? alignRight(rollupLeft, chalk.gray(rollupRight), width) : rollupLeft, ''];
+    const items = buildFleetAttentionItems(report, now);
+    if (items.length === 0) {
+        lines.push(chalk.green('Everything looks healthy.'), '');
+    }
+    else {
+        lines.push(chalk.bold(`NEEDS ATTENTION (${items.length})`));
+        const subjW = Math.max(...items.map((i) => i.subject.length));
+        const detailW = Math.max(...items.map((i) => stringWidth(i.detail)));
+        for (const it of items) {
+            const glyph = it.glyph === 'offline' ? chalk.gray('○') : chalk.yellow('⚠');
+            const subject = it.glyph === 'offline' ? chalk.gray(it.subject) : it.subject;
+            lines.push(`  ${glyph}  ${padToWidth(subject, subjW)}   ${padToWidth(it.detail, detailW)}   ${chalk.cyan(`→ ${it.fix}`)}`);
+        }
+        lines.push('');
+    }
+    // Per-device rows, grouped by OS. Within a group, this machine floats to the
+    // top; the rest stay alphabetical.
+    const nameW = Math.min(18, Math.max(6, ...rows.map((r) => r.name.length)));
+    const headW = Math.max(...rows.map((r) => stringWidth(headroomWord(r))));
+    const loadW = Math.max(...rows.map((r) => stringWidth(loadMemCell(r))));
+    const verW = Math.max(7, ...rows.map((r) => stringWidth(versionCell(r))));
+    const grouped = new Map();
+    for (const r of rows) {
+        const g = platformGroupLabel(r.platform);
+        (grouped.get(g) ?? grouped.set(g, []).get(g)).push(r);
+    }
+    for (const group of GROUP_ORDER) {
+        const members = grouped.get(group);
+        if (!members || members.length === 0)
+            continue;
+        members.sort((a, b) => (a.name === opts.self ? -1 : b.name === opts.self ? 1 : 0) || a.name.localeCompare(b.name));
+        lines.push(chalk.bold(group));
+        for (const row of members) {
+            const isSelf = row.name === opts.self;
+            const prefix = isSelf ? chalk.cyan('▸') : ' ';
+            const marks = [];
+            if (!isOffline(row)) {
+                const stark = starkCliGap(row);
+                if (stark)
+                    marks.push(chalk.yellow(`⚠ CLIs ${stark.installed}/${stark.total}`));
+            }
+            else if (isGenuinelyOffline(row) && row.lastSeen) {
+                marks.push(chalk.gray(`last seen ${formatCheckedAge(Date.parse(row.lastSeen), now)}`));
+            }
+            if (isSelf)
+                marks.push(chalk.cyan('← this machine'));
+            const note = marks.length ? `   ${marks.join('   ')}` : '';
+            lines.push(` ${prefix} ${padToWidth(truncateToWidth(row.name, nameW), nameW)}  ` +
+                `${padToWidth(headroomWord(row), headW)}  ` +
+                `${padToWidth(loadMemCell(row), loadW)}  ` +
+                `${padToWidth(versionCell(row), verW)}` +
+                note);
+        }
+        lines.push('');
+    }
+    // Footer: orphan-version nudge (a `prune` concern, not drift), then an honest
+    // freshness line naming the cache age and what --live/--verbose add.
+    const orphaned = rows.filter((r) => r.orphans.length > 0).length;
+    if (orphaned > 0) {
+        const subject = orphaned === 1 ? '1 device carries' : `${orphaned} devices carry`;
+        lines.push(chalk.gray(`${subject} orphaned versions · run  ${chalk.cyan('agents prune')}  to reclaim disk`));
+    }
+    const freshBits = [
+        cachedAge,
+        'pass --live to re-probe auth + reachability',
+        'pass --verbose for the auth/CLI/sync columns',
+    ].filter(Boolean);
+    lines.push(chalk.gray(freshBits.join(' · ')));
+    return lines;
+}