@phnx-labs/agents-cli 1.22.42 → 1.22.44

package/dist/lib/daemon-ticks.js

@@ -17,11 +17,51 @@ export function isFreshFleetAuthSnapshot(value, minimumCapturedAt) {
         && value.authRows.length > 0
         && value.authRows.every(authRow => authRow.health.checkedAt >= minimumCapturedAt);
 }
+/**
+ * How stale a cached auth verdict may get before the periodic tick re-probes.
+ *
+ * The auth verdict rides the same rate-limited `/api/oauth/usage` endpoint as
+ * the usage probe. Firing it every 3-minute tick on every fleet device drove one
+ * per-account request quota to a permanent 429, and the shared backoff then
+ * parked usage fleet-wide and froze the usage cache (RUSH-2998). Re-probing at
+ * most every 20 minutes cuts that endpoint traffic ~5x while still catching a
+ * revocation within one window — and every device keeps a REAL verdict (not a
+ * degraded "unverified"), so `agents devices ping --strict` and the run
+ * auth-preflight keep working on every host, unlike a publisher/subscriber split
+ * that would blind every non-primary box to revocation. Fleet status still
+ * publishes every tick — it does not ride that endpoint.
+ */
+export const AUTH_PROBE_MAX_AGE_MS = 20 * 60_000;
+/**
+ * True when every cached auth row was probed within {@link AUTH_PROBE_MAX_AGE_MS}
+ * — i.e. reusing them would not let a verdict get staler than one probe window.
+ * Empty cache is never fresh (nothing to reuse). Pure — unit-tested.
+ */
+export function isCachedFleetAuthProbeFresh(authRows, now, maxAgeMs = AUTH_PROBE_MAX_AGE_MS) {
+    return authRows.length > 0 && authRows.every((r) => now - r.health.checkedAt < maxAgeMs);
+}
+/**
+ * Whether the tick may reuse the cached auth verdict instead of re-probing the
+ * rate-limited endpoint. `force` (an on-demand `agents devices ping`) ALWAYS
+ * re-probes — the whole point of the command is a genuinely live verdict, and
+ * missing this `!force` is exactly how a `--strict` check silently passed a
+ * revoked account (the second `runFleetPing` call site, RUSH-2998). Pure —
+ * unit-tested so that inversion cannot regress unnoticed.
+ */
+export function shouldReuseCachedAuthProbe(force, cached, now, maxAgeMs = AUTH_PROBE_MAX_AGE_MS) {
+    return !force && isCachedFleetAuthProbeFresh(cached, now, maxAgeMs);
+}
 /**
  * Fleet cache warm: publish THIS host's row for the caches `agents fleet
  * status` / `agents devices list` read (PUBLISH-OWN / READ-UNION, RUSH-2061).
+ *
+ * `force` is set by on-demand callers (`agents devices ping`) that must return a
+ * genuinely live verdict; the periodic daemon tick leaves it unset so it reuses a
+ * recent verdict per {@link AUTH_PROBE_MAX_AGE_MS} instead of hammering the
+ * rate-limited endpoint every 3 minutes (RUSH-2998).
  */
-export async function refreshLocalFleetAuthState() {
+export async function refreshLocalFleetAuthState(opts) {
+    const force = opts?.force === true;
     const { machineId } = await import('./machine-id.js');
     const { probeLocalFleetAuth, readFleetAuthRows, writeFleetAuthRows } = await import('./auth-health.js');
     const { getCliVersion } = await import('./version.js');
@@ -40,11 +80,18 @@ export async function refreshLocalFleetAuthState() {
             return { row, authRows: readFleetAuthRows(self) };
         },
         // A recent daemon publication is the completed result, not a reason to probe
-        // every provider a second time.
-        isCompleted: (value) => isFreshFleetAuthSnapshot(value, minimumCapturedAt),
+        // every provider a second time. An on-demand caller (force) never accepts a
+        // cached snapshot — it must return a genuinely live verdict.
+        isCompleted: (value) => !force && isFreshFleetAuthSnapshot(value, minimumCapturedAt),
         refresh: async () => {
-            const authRows = await probeLocalFleetAuth({ cliVersion: getCliVersion() });
-            writeFleetAuthRows(self, authRows);
+            // Re-probe the rate-limited /oauth/usage endpoint at most every
+            // AUTH_PROBE_MAX_AGE_MS; reuse the last real verdict in between (RUSH-2998).
+            // Fleet status publishes every tick regardless — it does not ride that endpoint.
+            const cached = readFleetAuthRows(self);
+            const reuse = shouldReuseCachedAuthProbe(force, cached, requestedAt);
+            const authRows = reuse ? cached : await probeLocalFleetAuth({ cliVersion: getCliVersion() });
+            if (!reuse)
+                writeFleetAuthRows(self, authRows);
             const row = await publishLocalFleetStatus(self);
             return { row, authRows };
         },

package/dist/lib/device-config.js

@@ -243,8 +243,7 @@ export const CONFIG_KEYS = [
         type: 'string',
         description: "What this device is for, fleet-wide: 'worker' (a box agents run on) or 'personal' (a machine you sit at — never " +
             'picked automatically). Marking ANY device worker turns automatic placement into an allowlist: `--device auto` then ' +
-            'picks only from the marked workers. (A paired iPhone/iPad cockpit is marked control by `agents devices pair-ios` ' +
-            'and is excluded from placement by that role, not this key.)',
+            'picks only from the marked workers.',
         validate: (v) => DEVICE_ROLES.includes(v)
             ? null
             : `role must be one of ${DEVICE_ROLES.join(' | ')}.`,

package/dist/lib/devices/discovery-policy.d.ts

@@ -19,9 +19,9 @@ export declare function loadDeviceDiscoveryPolicies(): Map<string, DeviceDiscove
  * Only devices with an EXPLICIT entry in the synced policy are touched. A
  * device absent from the map is left alone, whether or not the map itself is
  * defined — the map is not treated as authoritative-by-omission, because not
- * every local registration path writes a policy entry (pair-ios control
- * devices, daemon/umbrella auto-refresh, and any device registered before this
- * feature shipped). Wiping those on the next `agents repo pull user` would be
+ * every local registration path writes a policy entry (daemon/umbrella
+ * auto-refresh, and any device registered before this feature shipped).
+ * Wiping those on the next `agents repo pull user` would be
  * silent, fleet-wide data loss for a decision (e.g. "ignore this one iPad")
  * that never meant to touch them.
  */

package/dist/lib/devices/discovery-policy.js

@@ -48,9 +48,9 @@ export function loadDeviceDiscoveryPolicies() {
  * Only devices with an EXPLICIT entry in the synced policy are touched. A
  * device absent from the map is left alone, whether or not the map itself is
  * defined — the map is not treated as authoritative-by-omission, because not
- * every local registration path writes a policy entry (pair-ios control
- * devices, daemon/umbrella auto-refresh, and any device registered before this
- * feature shipped). Wiping those on the next `agents repo pull user` would be
+ * every local registration path writes a policy entry (daemon/umbrella
+ * auto-refresh, and any device registered before this feature shipped).
+ * Wiping those on the next `agents repo pull user` would be
  * silent, fleet-wide data loss for a decision (e.g. "ignore this one iPad")
  * that never meant to touch them.
  */

package/dist/lib/devices/doctor-findings.js

@@ -42,7 +42,7 @@ import { AGENTS, ALL_AGENT_IDS, supportsAccountInspection } from '../agents.js';
 import { blocksLocalScripts } from '../platform/winpath.js';
 import { loginHint } from '../signin-badge.js';
 import { CONFIG_ENV_ISOLATED_AGENTS } from '../installations/shims.js';
-import { padToWidth, stringWidth } from '../session/width.js';
+import { padToWidth, stringWidth } from '../text/width.js';
 import { windowsSshEnrollmentProblem } from './windows-ssh-enrollment.js';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 /** Agents with NO per-version credential isolation: their login is shared across

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

@@ -7,9 +7,9 @@
  * throws (misconfigured auth, etc.) become `failed` rows — they never abort
  * the remaining devices.
  */
-import { type DeviceProfile, type DeviceRegistry } from './registry.js';
+import type { DeviceProfile, DeviceRegistry } from './registry.js';
 import type { DeviceStats } from './health.js';
-export type FleetSkipReason = 'offline' | 'no-address' | 'control';
+export type FleetSkipReason = 'offline' | 'no-address';
 /** npm dist-tags / semver pins only — rejects shell metacharacters. */
 export declare const FLEET_VERSION_RE: RegExp;
 export interface FleetTarget {
@@ -39,7 +39,6 @@ export interface FanOutDeviceResult<T> {
 /**
  * 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
@@ -48,10 +47,7 @@ export interface FanOutDeviceResult<T> {
 export declare function planFleetTargets(reg: DeviceRegistry): FleetTarget[];
 /**
  * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
- * `doctor --check --devices`): every planned device except this machine and control-only
- * cockpits. A control device never runs agents (mirrors doctor's fan-out, which
- * drops it via `isControlDevice`), so counting it as unreachable/drift would make
- * the CI gate fail on every run for a fleet that merely has a cockpit registered.
+ * `doctor --check --devices`): every planned device except this machine.
  * Offline / no-address devices are kept — those are genuine faults a gate should
  * surface — so their `skip` reason still flows through as an `unreachable` row.
  */
@@ -72,7 +68,7 @@ export declare function remoteFleetTargets(planned: FleetTarget[], self: string)
  * 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})
+ * An existing skip (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;

package/dist/lib/devices/fleet.js

@@ -8,7 +8,6 @@
  * the remaining devices.
  */
 import { spawnSync } from 'child_process';
-import { isControlDevice } from './registry.js';
 import { isSelfHost } from './self-host.js';
 import { buildSshInvocation, sshTargetFor, writeAskpassShim } from './connect.js';
 /** npm dist-tags / semver pins only — rejects shell metacharacters. */
@@ -16,7 +15,6 @@ 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
@@ -26,11 +24,6 @@ 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' };
         }
@@ -45,10 +38,7 @@ export function planFleetTargets(reg) {
 }
 /**
  * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
- * `doctor --check --devices`): every planned device except this machine and control-only
- * cockpits. A control device never runs agents (mirrors doctor's fan-out, which
- * drops it via `isControlDevice`), so counting it as unreachable/drift would make
- * the CI gate fail on every run for a fleet that merely has a cockpit registered.
+ * `doctor --check --devices`): every planned device except this machine.
  * Offline / no-address devices are kept — those are genuine faults a gate should
  * surface — so their `skip` reason still flows through as an `unreachable` row.
  */
@@ -57,7 +47,7 @@ export function remoteFleetTargets(planned, self) {
     // device referenced by its dnsName slipped past the bare name check and got a
     // remote version+doctor dial back to THIS box, which orphaned on timeout and
     // piled up (RUSH-2114). `isSelfHost` matches every alias the box answers to.
-    return planned.filter((t) => t.device.name !== self && !isSelfHost(t.device.name) && t.skip !== 'control');
+    return planned.filter((t) => t.device.name !== self && !isSelfHost(t.device.name));
 }
 /**
  * Decide whether a fleet-health target should skip the expensive version+doctor
@@ -75,7 +65,7 @@ export function remoteFleetTargets(planned, self) {
  * 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})
+ * An existing skip (offline/no-address from {@link planFleetTargets})
  * always wins — those are classified before any probe.
  */
 export function fleetHealthSkip(currentSkip, stats) {
@@ -92,8 +82,6 @@ export function skipLabel(reason) {
             return 'offline';
         case 'no-address':
             return 'no address';
-        case 'control':
-            return 'control device';
     }
 }
 /**

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

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { padToWidth, stringWidth, terminalWidth, truncateToWidth } from '../session/width.js';
+import { padToWidth, stringWidth, terminalWidth, truncateToWidth } from '../text/width.js';
 import { fmtBytes, headroom } from './health.js';
 import { formatCheckedAge } from '../auth-health.js';
 import { compareFleetInventories } from './fleet-divergence.js';
@@ -314,7 +314,7 @@ export function buildFleetAttentionItems(report, now = Date.now()) {
         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
+    // 2) Boxes that need `agents fleet 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) {
@@ -327,7 +327,7 @@ export function buildFleetAttentionItems(report, now = Date.now()) {
         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}` });
+            items.push({ glyph: 'warn', subject: row.name, detail: reasons.join(' · '), fix: `agents fleet apply --device ${row.name}` });
         }
     }
     // 3) Version skew across the fleet — one line.
@@ -354,7 +354,7 @@ export function buildFleetAttentionItems(report, now = Date.now()) {
             glyph: 'warn',
             subject: w.devices[0] ?? 'fleet',
             detail: w.message.replace(`${w.devices[0]} `, ''),
-            fix: `agents apply ${w.devices[0] ?? ''}`.trim(),
+            fix: `agents fleet apply --device ${w.devices[0] ?? ''}`.trim(),
         });
     }
     return items;

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

@@ -19,12 +19,6 @@
  *
  * `auto.pool all` turns the allowlist off; `personal` stays excluded, because a
  * machine the user sits at is marked precisely so agents stay off it.
- *
- * Paired cockpits (an iPhone/iPad, `role: control` in the device registry, set
- * by `agents devices pair-ios`) are excluded by the CALLER that reads the
- * registry — `listOnlineDeviceNames` in `lib/smart-launch.ts` — not here. That
- * role is machine-local by nature and already has a home; duplicating it in the
- * shared config would be a second store for one concept.
  */
 import { type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
 export interface AutoPoolOptions {

package/dist/lib/devices/pool.js

@@ -19,12 +19,6 @@
  *
  * `auto.pool all` turns the allowlist off; `personal` stays excluded, because a
  * machine the user sits at is marked precisely so agents stay off it.
- *
- * Paired cockpits (an iPhone/iPad, `role: control` in the device registry, set
- * by `agents devices pair-ios`) are excluded by the CALLER that reads the
- * registry — `listOnlineDeviceNames` in `lib/smart-launch.ts` — not here. That
- * role is machine-local by nature and already has a home; duplicating it in the
- * shared config would be a second store for one concept.
  */
 import { autoPoolMode, listConfiguredDeviceRoles } from '../device-config.js';
 import { normalizeHost } from '../machine-id.js';

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

@@ -1,13 +1,5 @@
 /** 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
@@ -73,15 +65,9 @@ export interface DeviceProfile {
      * cached {@link DeviceTailscale.online} snapshot when rendering online/offline,
      * because the live probe reflects whether the box answered right now. */
     reachability?: DeviceReachability;
-    /** 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;
 /**
  * Whether a fan-out should dial this device, honouring the preference stated on
  * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
@@ -127,7 +113,6 @@ export interface DeviceInput {
     auth?: DeviceAuth;
     tailscale?: DeviceTailscale;
     reachability?: DeviceReachability;
-    role?: DeviceRole;
 }
 /**
  * Create the device if absent, otherwise merge the supplied fields into the

package/dist/lib/devices/registry.js

@@ -19,14 +19,6 @@ import * as path from 'path';
 import lockfile from 'proper-lockfile';
 import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
 import { atomicWriteJsonSync } from '../fs-atomic.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';
-}
 /**
  * Whether a fan-out should dial this device, honouring the preference stated on
  * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
@@ -198,7 +190,6 @@ export async function upsertDevice(name, input) {
             auth: input.auth ?? prev?.auth ?? { method: 'key' },
             tailscale: input.tailscale ?? prev?.tailscale,
             reachability: input.reachability ?? prev?.reachability,
-            role: input.role ?? prev?.role,
             createdAt: prev?.createdAt ?? now,
             updatedAt: now,
         };

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

@@ -1,5 +1,15 @@
 import { probeFleetStats, probeLocalStats, type DeviceStats } from './health.js';
 import type { DeviceProfile } from './registry.js';
+/**
+ * Freshness bound for a cached row. Matches the agent-count mirror's window
+ * (`AGENT_STATUS_STALE_MS` in `commands/ssh.ts`) so both columns of
+ * `devices list` / `fleet status` share one staleness model. A row older than
+ * this is never served as current — it is re-probed live (and the probe result
+ * rewrites the cache, unreachable boxes included).
+ */
+export declare const STATS_STALE_MS: number;
+/** True when a cached row is still within {@link STATS_STALE_MS}. */
+export declare function isFreshDeviceStats(stats: DeviceStats, now?: number): boolean;
 /** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
 export declare function readStatsCache(): Record<string, DeviceStats>;
 /**
@@ -27,6 +37,8 @@ export interface LoadFleetStatsOptions {
     probeLocal?: typeof probeLocalStats;
     readCache?: typeof readStatsCache;
     writeCache?: typeof writeStatsCache;
+    /** Clock override for tests (drives the {@link STATS_STALE_MS} bound). */
+    now?: number;
 }
 /**
  * Load fleet stats cache-first. See the module doc for the default vs

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

@@ -15,16 +15,32 @@
  * - **`--refresh` / `--live`:** skip the cache and live-probe every device,
  *   rewriting the cache.
  *
- * The daemon warms this cache (~every 3 min, see `lib/daemon/daemon.ts
- * runFleetCacheWarm`), so in steady state a default read has zero
- * remote ssh round-trips and returns immediately with data that is at most a
- * few minutes old — surfaced to the user as an "as of …" freshness note.
+ * Every cached row is bounded by {@link STATS_STALE_MS}: a row older than the
+ * window is treated exactly like a missing one — re-probed live this call and
+ * rewritten — so the default read is itself the cache's writer and a value can
+ * never fossilize at the last manual `--refresh`. (The daemon used to warm this
+ * cache every ~3 min; RUSH-2061 removed that N² fleet probe, which left the
+ * unbounded read serving multi-day-old rows as current fleet state — the
+ * scheduler, `--device auto`, and the session-start banner all read these
+ * numbers. See #2666.)
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from '../state.js';
 import { probeFleetStats, probeLocalStats } from './health.js';
 const CACHE_FILE = '.fleet-stats.json';
+/**
+ * Freshness bound for a cached row. Matches the agent-count mirror's window
+ * (`AGENT_STATUS_STALE_MS` in `commands/ssh.ts`) so both columns of
+ * `devices list` / `fleet status` share one staleness model. A row older than
+ * this is never served as current — it is re-probed live (and the probe result
+ * rewrites the cache, unreachable boxes included).
+ */
+export const STATS_STALE_MS = 3 * 60_000;
+/** True when a cached row is still within {@link STATS_STALE_MS}. */
+export function isFreshDeviceStats(stats, now = Date.now()) {
+    return now - stats.fetchedAt <= STATS_STALE_MS;
+}
 function cacheFilePath() {
     return path.join(getCacheDir(), CACHE_FILE);
 }
@@ -71,6 +87,7 @@ export async function loadFleetStats(devices, opts = {}) {
     const readCache = opts.readCache ?? readStatsCache;
     const writeCache = opts.writeCache ?? writeStatsCache;
     const self = opts.selfName;
+    const now = opts.now ?? Date.now();
     const cache = opts.forceRefresh ? {} : readCache();
     const stats = new Map();
     const toProbe = [];
@@ -82,11 +99,13 @@ export async function loadFleetStats(devices, opts = {}) {
             continue;
         }
         const cached = cache[d.name];
-        if (cached) {
+        if (cached && isFreshDeviceStats(cached, now)) {
             stats.set(d.name, cached);
             servedFromCache = true;
         }
         else {
+            // Missing OR beyond the staleness bound: a stale number rendered as
+            // current is worse than the probe's cost, so re-probe live (#2666).
             toProbe.push(d);
         }
     }

package/dist/lib/drift-sync.d.ts

@@ -1,6 +1,6 @@
 /**
  * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
- * action, shared by `agents status`, `agents doctor`, and the menu-bar "NEEDS
+ * action, shared by `agents sync status`, `agents doctor`, and the menu-bar "NEEDS
  * SYNC" row.
  *
  * It composes existing pieces, re-implementing nothing:

package/dist/lib/drift-sync.js

@@ -1,6 +1,6 @@
 /**
  * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
- * action, shared by `agents status`, `agents doctor`, and the menu-bar "NEEDS
+ * action, shared by `agents sync status`, `agents doctor`, and the menu-bar "NEEDS
  * SYNC" row.
  *
  * It composes existing pieces, re-implementing nothing:
@@ -115,7 +115,7 @@ export async function promptDriftSync(opts = {}) {
     if (opts.yes || !isInteractiveTerminal()) {
         if (!opts.yes) {
             // Non-TTY without --yes: report, don't act, don't throw.
-            console.log(chalk.gray('\nRun `agents status --yes` to sync, or `agents status` in a terminal to choose.'));
+            console.log(chalk.gray('\nRun `agents sync status --yes` to sync, or `agents sync status` in a terminal to choose.'));
             return base;
         }
         const systemPulled = await pullSystem(status);

package/dist/lib/drift.d.ts

@@ -62,7 +62,7 @@ export interface DriftSummary {
      * True when the install is out of sync: any installed version is stale,
      * never-synced, carries unwired hooks, or has a broken generated hook runtime,
      * OR a source layer is behind origin.
-     * `agents doctor` surfaces it as "run `agents status`"; `agents doctor --check`
+     * `agents doctor` surfaces it as "run `agents sync status`"; `agents doctor --check`
      * maps it to a non-zero exit. Orphans are a `prune` concern, not sync drift, so they do
      * NOT set this flag (mirrors the sync-status engine: an orphan alone never
      * flags needsSync).

package/dist/lib/exec.js

@@ -37,6 +37,8 @@ import { applyAddDirs } from './add-dir.js';
 import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
 import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js';
 import { resolveConfigVersion } from './harness/exec-config-version.js';
+import { getAccountInfo } from './agents.js';
+import { getUsageLookupKey, noteClaudeSessionLimit, parseClaudeSessionLimitReset } from './accounting/usage.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -2083,12 +2085,20 @@ export async function runWithFallback(options) {
             }
             throw err;
         }
-        if (result.exitCode === 0)
+        const output = `${result.stderr}\n${result.stdout}`;
+        const sessionLimitReset = agent === 'claude' ? parseClaudeSessionLimitReset(output) : null;
+        if (sessionLimitReset && version) {
+            const account = await getAccountInfo(agent, getVersionHomePath(agent, version));
+            const usageKey = getUsageLookupKey(account);
+            if (usageKey)
+                noteClaudeSessionLimit(usageKey, sessionLimitReset);
+        }
+        if (result.exitCode === 0 && !sessionLimitReset)
             return 0;
         const isLast = i === chain.length - 1;
         if (isLast)
-            return result.exitCode;
-        if (!detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
+            return result.exitCode || 1;
+        if (!sessionLimitReset && !detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
             return result.exitCode;
         }
         const next = chain[i + 1];

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

@@ -15,7 +15,7 @@
  */
 import type { FleetManifest, FleetDefaults } from './types.js';
 export interface CaptureInputs {
-    /** Registered, non-control device names to record (the roster — names only). */
+    /** Registered device names to record (the roster — names only). */
     devices: string[];
     /** Optional per-device agent specs (e.g. from `--from-pins`), keyed by name. */
     agentsByDevice?: Record<string, string[]>;

package/dist/lib/fleet/manifest.js

@@ -124,7 +124,7 @@ export function readFleetFile(filePath) {
     }
     const fleet = doc.fleet;
     if (fleet === undefined) {
-        throw new Error(`${filePath} has no fleet: block. Add one to declare the profile (see \`agents apply --help\`).`);
+        throw new Error(`${filePath} has no fleet: block. Add one to declare the profile (see \`agents fleet apply --help\`).`);
     }
     return parseFleetManifest(fleet);
 }

package/dist/lib/fleet/remote-login.d.ts

@@ -63,7 +63,7 @@ export interface SelectLoginOptions {
  *
  * A pair is pending when its cached verdict {@link isPendingVerdict} (or
  * `includeLoggedIn` forces it). Agents with no defined login flow are dropped
- * silently (nothing to log into). Control devices are excluded by the caller.
+ * silently (nothing to log into).
  */
 export declare function selectLoginTargets(devices: DeviceProfile[], agents: (AgentId | string)[], cache: Record<string, AuthHealth>, opts?: SelectLoginOptions): PendingLogin[];
 /**
@@ -146,7 +146,7 @@ export interface DetectOptions {
     includeLoggedIn?: boolean;
 }
 /**
- * Resolve the online (non-control) fleet devices, then compute pending logins
+ * Resolve the online fleet devices, then compute pending logins
  * from the shared auth-health cache (populated by `agents fleet ping`). Thin I/O
  * over the pure {@link selectLoginTargets}. Devices/agents can be narrowed by the
  * caller's flags; the default agent set is every agent with a defined flow.

package/dist/lib/fleet/remote-login.js

@@ -27,7 +27,6 @@
  * human works through the earlier ones.
  */
 import * as http from 'http';
-import { isControlDevice } from '../devices/registry.js';
 import { loadDevices } from '../devices/registry.js';
 import { deviceIdentityArgs, fleetDialTarget } from '../devices/connect.js';
 import { planFleetTargets } from '../devices/fleet.js';
@@ -117,7 +116,7 @@ function worstCachedVerdict(cache, host, agent) {
  *
  * A pair is pending when its cached verdict {@link isPendingVerdict} (or
  * `includeLoggedIn` forces it). Agents with no defined login flow are dropped
- * silently (nothing to log into). Control devices are excluded by the caller.
+ * silently (nothing to log into).
  */
 export function selectLoginTargets(devices, agents, cache, opts = {}) {
     const out = [];
@@ -408,7 +407,7 @@ export async function driveRemoteLogin(target, flow, driver, opts = {}, extraSsh
     }
 }
 /**
- * Resolve the online (non-control) fleet devices, then compute pending logins
+ * Resolve the online fleet devices, then compute pending logins
  * from the shared auth-health cache (populated by `agents fleet ping`). Thin I/O
  * over the pure {@link selectLoginTargets}. Devices/agents can be narrowed by the
  * caller's flags; the default agent set is every agent with a defined flow.
@@ -417,7 +416,7 @@ export async function detectPending(opts = {}) {
     const reg = await loadDevices();
     const self = machineId();
     const online = planFleetTargets(reg)
-        .filter((t) => !t.skip && t.device.name !== self && !isControlDevice(t.device))
+        .filter((t) => !t.skip && t.device.name !== self)
         .map((t) => t.device);
     const deviceFilter = opts.devices && opts.devices.length > 0 ? new Set(opts.devices) : null;
     const devices = deviceFilter ? online.filter((d) => deviceFilter.has(d.name)) : online;

package/dist/lib/format.d.ts

@@ -27,6 +27,15 @@ export declare function formatDie(msg: string, opts?: DieOptions): {
  * keep the original red-stderr behavior.
  */
 export declare function die(msg: string, code?: number, opts?: DieOptions): never;
+/**
+ * Await a command action and turn a thrown Error into a clean `die(message)`
+ * instead of Node's raw stack dump — bootstrap's parseAsync catch deliberately
+ * rethrows plain Errors as engineering bugs, so a command whose helpers throw
+ * user-actionable errors (auth, org) wraps its `.action(...)` call site with
+ * this. The helpers keep throwing so tests can assert on them. Pass `json`
+ * so a `--json` caller still gets the structured `{"error"}` payload.
+ */
+export declare function runOrDie(fn: () => void | Promise<void>, opts?: DieOptions): Promise<void>;
 /**
  * `die()` with a structured friction event attached. Use this at CLI error
  * chokepoints so the nightly routine can classify and rank recurring failures

package/dist/lib/format.js

@@ -44,6 +44,22 @@ export function die(msg, code = 1, opts = {}) {
         console.error(text);
     process.exit(code);
 }
+/**
+ * Await a command action and turn a thrown Error into a clean `die(message)`
+ * instead of Node's raw stack dump — bootstrap's parseAsync catch deliberately
+ * rethrows plain Errors as engineering bugs, so a command whose helpers throw
+ * user-actionable errors (auth, org) wraps its `.action(...)` call site with
+ * this. The helpers keep throwing so tests can assert on them. Pass `json`
+ * so a `--json` caller still gets the structured `{"error"}` payload.
+ */
+export async function runOrDie(fn, opts = {}) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        die(err instanceof Error ? err.message : String(err), 1, opts);
+    }
+}
 /**
  * `die()` with a structured friction event attached. Use this at CLI error
  * chokepoints so the nightly routine can classify and rank recurring failures