@phnx-labs/agents-cli 1.22.43 → 1.22.45

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/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

@@ -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/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/hosts/dispatch.d.ts

@@ -168,6 +168,8 @@ export interface InteractiveDispatchOptions {
     agent: string;
     /** Explicit agent version pin (e.g. "2.1.207") to forward as `agent@version`. */
     version?: string;
+    /** Preserve the trailing-@ account picker so selection happens on the execution host. */
+    accountPicker?: boolean;
     /** Explicit run strategy (e.g. "balanced") to forward as `--strategy <strategy>`. */
     strategy?: string;
     /** Named provider account to resolve on the remote host. */

package/dist/lib/hosts/dispatch.js

@@ -417,7 +417,14 @@ export function buildRunForwardedArgs(opts) {
  * infer headless from the prompt).
  */
 export function buildInteractiveRunForwardedArgs(opts) {
-    const agentArg = opts.version ? `${opts.agent}@${opts.version}` : opts.agent;
+    if (opts.version && opts.accountPicker) {
+        throw new Error('Interactive host dispatch cannot combine an account picker with a version pin');
+    }
+    const agentArg = opts.accountPicker
+        ? `${opts.agent}@`
+        : opts.version
+            ? `${opts.agent}@${opts.version}`
+            : opts.agent;
     const args = ['run', agentArg];
     if (opts.prompt && opts.forceInteractive)
         args.push(opts.prompt);

package/dist/lib/hosts/passthrough.js

@@ -95,7 +95,6 @@ export const REMOTE_PASSTHROUGH = {
     restore: {},
     worktree: {},
     events: {},
-    audit: {},
     feedback: {},
     pty: {},
     tmux: {},

package/dist/lib/hosts/providers/devices.js

@@ -17,7 +17,7 @@
  * enrolled host shadows a same-name device in both list dedup and resolve
  * order, exactly like the old tier-2 devices fall-through in resolveHost.
  */
-import { loadDevices, getDevice, isControlDevice } from '../../devices/registry.js';
+import { loadDevices, getDevice } from '../../devices/registry.js';
 import { resolveDeviceProfile } from '../../devices/resolve-profile.js';
 import { DeviceOffloadUnsupportedError } from '../types.js';
 /** Tailscale's own presence bit, when the sync captured one. */
@@ -34,12 +34,6 @@ function statusOf(device) {
  * precedence, carrying the caps.
  */
 function deviceToPoolHost(rawDevice) {
-    // A control device (a cockpit, e.g. a paired iPhone) drives the fleet but
-    // never runs agents — it must never enter the host pool or be resolvable as a
-    // dispatch target, whatever platform it reports (an iPhone syncs as `unknown`,
-    // which remoteShellFor would otherwise default to POSIX and try to SSH).
-    if (isControlDevice(rawDevice))
-        return null;
     // Effective profile: central config (ssh.*/platform) overlays discovery.
     const device = resolveDeviceProfile(rawDevice);
     const address = device.address.dnsName ?? device.address.ip;
@@ -78,12 +72,6 @@ export class DevicesHostProvider {
         const raw = await getDevice(name);
         if (!raw)
             return null;
-        // Resolving is asking to dispatch. A control device can't run agents — fail
-        // loud with a clear message instead of attempting an SSH dispatch onto a
-        // phone (which remoteShellFor would treat as a POSIX host).
-        if (isControlDevice(raw)) {
-            throw new Error(`Device "${raw.name}" is a control device (a cockpit), not an executor — it can't run agents. Dispatch to a worker device instead.`);
-        }
         // Effective profile: central config (ssh.*/platform) overlays discovery —
         // the password-auth refusal and the dial shape both follow the config.
         const device = resolveDeviceProfile(raw);

package/dist/lib/hosts/ready.d.ts

@@ -88,11 +88,20 @@ export declare function viewAgentVersions(view: string, agent: string): string[]
 export declare function viewHasAgentVersion(view: string, agent: string, version: string): boolean | undefined;
 /** Actionable fail-loud message for a missing remote pin (RUSH-2313). */
 export declare function missingPinnedVersionMessage(hostName: string, agent: string, version: string, installed?: string[]): string;
+/** Account eligibility extracted from one device's `agents view --json`. */
+export interface ViewAgentAccountEligibility {
+    /** At least one account can launch immediately. */
+    signedIn: boolean | undefined;
+    /** At least one account can launch immediately or enter the harness login flow. */
+    pickerEligible: boolean | undefined;
+}
 /**
- * Read whether the requested harness has at least one launch-eligible account
- * from `agents view --json`. Signed-in accounts that are rate-limited or out of
- * credits are deliberately false so automatic placement cannot select them.
+ * Read the two account gates automatic placement needs from `agents view
+ * --json`. A picker may route to a signed-out version because launching it is
+ * the login flow, but it must not route to a device whose every signed-in
+ * account is throttled.
  */
+export declare function viewAgentAccountEligibility(view: string, agent: string): ViewAgentAccountEligibility;
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;
 export interface EnsureReadyOptions {
     agent: string;

package/dist/lib/hosts/ready.js

@@ -12,6 +12,7 @@ import { sshExec, shellQuote } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
+import { isDeadVerdict } from '../auth-health.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
 export function localCliVersion() {
     let dir = path.dirname(fileURLToPath(import.meta.url));
@@ -208,27 +209,41 @@ export function missingPinnedVersionMessage(hostName, agent, version, installed)
         `Install it on that box: agents ssh ${hostName} -- agents add ${agent}@${version}`);
 }
 /**
- * Read whether the requested harness has at least one launch-eligible account
- * from `agents view --json`. Signed-in accounts that are rate-limited or out of
- * credits are deliberately false so automatic placement cannot select them.
+ * Read the two account gates automatic placement needs from `agents view
+ * --json`. A picker may route to a signed-out version because launching it is
+ * the login flow, but it must not route to a device whose every signed-in
+ * account is throttled.
  */
-export function viewAgentSignedIn(view, agent) {
+export function viewAgentAccountEligibility(view, agent) {
     try {
         const rows = JSON.parse(view);
         const row = rows.find((candidate) => candidate.agent?.toLowerCase() === agent.toLowerCase());
         if (!row)
-            return undefined;
-        const verdicts = (row.versions ?? [])
-            .map((version) => typeof version.signedIn === 'boolean'
-            ? version.signedIn && version.usageStatus !== 'rate_limited' && version.usageStatus !== 'out_of_credits'
-            : undefined)
-            .filter((value) => typeof value === 'boolean');
-        return verdicts.length === 0 ? undefined : verdicts.some(Boolean);
+            return { signedIn: undefined, pickerEligible: undefined };
+        const verdicts = (row.versions ?? []).flatMap((version) => {
+            if (typeof version.signedIn !== 'boolean')
+                return [];
+            const throttled = version.usageStatus === 'rate_limited' || version.usageStatus === 'out_of_credits';
+            const authBlocked = version.authVerdict !== null
+                && version.authVerdict !== undefined
+                && isDeadVerdict(version.authVerdict);
+            const ready = version.signedIn && !authBlocked && !throttled;
+            return [{ ready, pickerEligible: ready || !version.signedIn || authBlocked }];
+        });
+        if (verdicts.length === 0)
+            return { signedIn: undefined, pickerEligible: undefined };
+        return {
+            signedIn: verdicts.some((verdict) => verdict.ready),
+            pickerEligible: verdicts.some((verdict) => verdict.pickerEligible),
+        };
     }
     catch {
-        return undefined;
+        return { signedIn: undefined, pickerEligible: undefined };
     }
 }
+export function viewAgentSignedIn(view, agent) {
+    return viewAgentAccountEligibility(view, agent).signedIn;
+}
 /**
  * Pure readiness verdict for the agent/version half of {@link ensureHostReady}
  * (unit-tested without SSH). Returns warnings for soft agent-missing cases, or

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

@@ -27,8 +27,8 @@ export declare function getAllProviders(): HostProvider[];
  * A resolved host, carrying the live {@link DeviceProfile} when the token
  * matched a registered device (by normalized name). The device reference lets
  * the `agents ssh` wrapper reach auth/shell/tailscale metadata a plain `Host`
- * doesn't hold, and lets dispatch callers apply the device-only refusals
- * (control device, password auth) without re-reading the registry.
+ * doesn't hold, and lets dispatch callers apply the device-only refusal
+ * (password auth) without re-reading the registry.
  */
 export interface ResolvedHost extends Host {
     device?: DeviceProfile;
@@ -65,7 +65,7 @@ export interface MatchHostOptions {
  * all resolve the same way regardless of which subcommand called.
  *
  * Non-throwing: returns null on an injection-guard failure or an unresolved bare
- * token. Device-only refusals (control device, password auth) are NOT applied
+ * token. The device-only refusal (password auth) is NOT applied
  * here — that is the dispatch wrapper's job ({@link resolveHost}), so the fan-out
  * and `agents ssh` paths, which handle those cases differently, aren't forced
  * into a dispatch verdict.
@@ -81,8 +81,7 @@ export declare function listAllHosts(): Promise<Host[]>;
  * caller consumes (`run --device`, the generic passthrough, teams placement, the
  * cloud host provider, doctor, funnel, remote secrets). Grammar and merge come
  * from {@link matchHost}; on top, this layer applies the device-only dispatch
- * refusals so they hold even when an inline overlay shadows the device:
- *   - a control device (a paired iPhone) can never be a dispatch target;
+ * refusal so it holds even when an inline overlay shadows the device:
  *   - a password-auth device throws the typed {@link DeviceOffloadUnsupportedError}
  *     (offload rides `BatchMode=yes` ssh, which can't answer a prompt);
  *   - an addressless device has nothing to dial.