@phnx-labs/agents-cli 1.22.25 → 1.22.27

package/dist/lib/teams/scheduler.d.ts

@@ -1,3 +1,26 @@
+import type { Headroom } from '../devices/health.js';
+/**
+ * Live signal for one pool device, gathered by the caller (SSH probes) and
+ * passed into the pure pick. Every field is optional/best-effort: a device with
+ * no signal is neither excluded nor preferred — it degrades to the roster-count
+ * path. `reachable === false` and `installed === false` are the only two
+ * exclusion signals here; `headroom` drives the overload exclusion + the load
+ * tier of the rank. See {@link DeviceStats}/{@link headroom} in devices/health.
+ */
+export interface DevicePlacementSignal {
+    /** SSH probe answered. `false` → excluded (unreachable). undefined → unknown. */
+    reachable?: boolean;
+    /** Headroom bucket from load+memory. `'loaded'` → excluded (overloaded). */
+    headroom?: Headroom;
+    /** Normalized CPU load percent (finer rank tiebreak within a headroom tier). */
+    loadPercent?: number;
+    /** Memory pressure percent (used with loadPercent for the load cost). */
+    memPercent?: number;
+    /** Requested agent installed on the device. `false` → excluded (can't run). */
+    installed?: boolean;
+    /** Requested agent signed in (best-effort). Ranks a signed-in device first. */
+    signedIn?: boolean;
+}
 /** Team fields the placement cascade reads (a subset of TeamMeta). */
 export interface PlacementTeam {
     devices?: string[];
@@ -14,7 +37,37 @@ export interface PlacementTeam {
  */
 export interface PlacementOptions {
     maxConcurrent?: Record<string, number>;
+    /**
+     * Live per-device signals (RUSH-2002). When present, the many-device pick
+     * filters unreachable/overloaded/not-installed devices and ranks the rest by
+     * health + harness + load. Absent → the pick stays a pure roster count.
+     */
+    signals?: Map<string, DevicePlacementSignal>;
+    /** Human label of the requested agent (e.g. `claude@2.1.112`) for the
+     * fail-loud message. */
+    agentLabel?: string;
+}
+/** Why a device was excluded from the viable set, for the fail-loud message. */
+export type ExclusionReason = 'unreachable' | 'overloaded' | 'capped' | 'not-installed';
+/** A pool device dropped from the auto-pick, with the reason + live detail. */
+export interface ExcludedDevice {
+    device: string;
+    reason: ExclusionReason;
+    /** Present for `capped`: `running/cap`. */
+    detail?: string;
 }
+/**
+ * No device in the pool can host the teammate. Carries the per-device reasons so
+ * the caller can print exactly why the pool is unusable instead of silently
+ * degrading to a local run the user did not ask for.
+ */
+export declare class NoViableDeviceError extends Error {
+    readonly excluded: ExcludedDevice[];
+    readonly agentLabel?: string;
+    constructor(excluded: ExcludedDevice[], agentLabel?: string);
+}
+/** Build the user-facing fail-loud message from the per-device reasons. */
+export declare function formatNoViableMessage(excluded: ExcludedDevice[], agentLabel?: string): string;
 /**
  * A roster entry the load counter reads — the shape any teammate satisfies
  * (AgentProcess included). `status` is compared against `'running'` (the
@@ -45,11 +98,31 @@ export declare function cappedDevices(devices: string[], roster: RosterEntry[],
  * teammate silently landing on a machine its operator capped.
  */
 export declare function pickLeastLoaded(devices: string[], roster: RosterEntry[], maxConcurrent?: Record<string, number>): string;
+/**
+ * Split the pool into the viable set and the excluded set (with reasons), from
+ * the caps + live signals. Pure — the caller decides what to do with an empty
+ * viable set. Reasons are checked in a stable order (unreachable → not-installed
+ * → overloaded → capped) so a device reports its most fundamental blocker first.
+ */
+export declare function classifyExclusions(devices: string[], roster: RosterEntry[], opts?: PlacementOptions): {
+    eligible: string[];
+    excluded: ExcludedDevice[];
+};
+/**
+ * Health-, harness-, and load-aware pick over a pool (RUSH-2002). Filters
+ * unreachable / overloaded / capped / not-installed devices, then ranks the
+ * survivors by: (a) agent signed in, (b) lower load (headroom tier, then raw
+ * load cost), (c) fewer running teammates, ties broken by pool order. Throws
+ * {@link NoViableDeviceError} when nothing survives — never returns a local
+ * fallback. Pure: all I/O is pre-resolved into `opts.signals`.
+ */
+export declare function pickBestDevice(devices: string[], roster: RosterEntry[], opts?: PlacementOptions): string;
 /**
  * Resolve where a teammate runs. Returns `{ device: null }` for a local run
  * (no pin, no pool, or the chosen device is the local machine) and
  * `{ device: <name> }` for a remote placement. See the cascade in the module
- * header.
+ * header. Throws {@link NoViableDeviceError} when a required pool has no viable
+ * host — the caller surfaces it at `teams start` rather than falling back local.
  */
 export declare function resolvePlacement(team: PlacementTeam, explicitDevice: string | null, roster: RosterEntry[], opts?: PlacementOptions): {
     device: string | null;

package/dist/lib/teams/scheduler.js

@@ -8,19 +8,68 @@
  *
  *   1. teammate has an explicit `--device` pin      → that device
  *   2. else the team pool has exactly one device     → that device (whole team)
- *   3. else the team pool has many devices           → least-loaded pick
+ *   3. else the team pool has many devices           → best-viable pick
  *   4. else (no pin, no pool)                         → null == run local
  *
- * Step 3 is cap-aware: a device at its `agents.max-concurrent` cap (from the
- * device doc, passed in via PlacementOptions) is excluded from the auto-pick,
- * and an all-capped pool fails loud. Pins and pools of one are the user's own
- * choice and are never second-guessed.
+ * Step 3 is cap-, health-, and harness-aware (RUSH-2002). When the caller
+ * supplies live {@link DevicePlacementSignal}s (probed reachability, headroom,
+ * load/mem, and whether the requested agent is installed + signed in), the pick:
+ *   - EXCLUDES an unreachable device, an overloaded one (headroom `loaded`), a
+ *     device at its `agents.max-concurrent` cap, and one the requested agent is
+ *     not installed on;
+ *   - RANKS the survivors by (a) agent installed + signed in, (b) lower load /
+ *     memory (by headroom tier, then raw), (c) fewer running teammates, ties
+ *     broken by pool order.
+ * With no signals it degrades to the original cap-aware least-loaded pick, so
+ * the pure roster-count path (and its tests) are unchanged.
+ *
+ * When every pool device is excluded, the pick FAILS LOUD ({@link
+ * NoViableDeviceError}) naming each device's reason — never a silent fall back
+ * to local, since the user asked for a remote pool. Pins are the user's own
+ * choice and are never second-guessed; a pool of one is respected for
+ * load/cap/reachability but still fails loud when the agent is provably not
+ * installed there (running it would be futile).
  *
  * A device whose name equals the local machine id is treated as "local" — it
  * resolves to a null placement so the existing local spawn path runs unchanged,
  * letting the local machine participate in a pool as just another member.
  */
 import { machineId } from '../session/sync/config.js';
+/**
+ * No device in the pool can host the teammate. Carries the per-device reasons so
+ * the caller can print exactly why the pool is unusable instead of silently
+ * degrading to a local run the user did not ask for.
+ */
+export class NoViableDeviceError extends Error {
+    excluded;
+    agentLabel;
+    constructor(excluded, agentLabel) {
+        super(formatNoViableMessage(excluded, agentLabel));
+        this.name = 'NoViableDeviceError';
+        this.excluded = excluded;
+        this.agentLabel = agentLabel;
+    }
+}
+/** Build the user-facing fail-loud message from the per-device reasons. */
+export function formatNoViableMessage(excluded, agentLabel) {
+    const anyNotInstalled = excluded.some((e) => e.reason === 'not-installed');
+    const agent = agentLabel ?? 'the requested agent';
+    const perDevice = excluded
+        .map((e) => (e.detail ? `${e.device} (${e.reason} ${e.detail})` : `${e.device} (${e.reason})`))
+        .join(', ');
+    // When the whole pool lacks the agent, lead with the harness message the
+    // ticket specifies; otherwise summarize the mixed reasons.
+    const head = anyNotInstalled
+        ? `No device in the team pool can run ${agent}.`
+        : `No viable device in the team pool for ${agent}.`;
+    const anyUnreachable = excluded.some((e) => e.reason === 'unreachable');
+    const hint = anyNotInstalled
+        ? " Run 'agents devices ping' to see which devices have the agent installed + signed in, or add the agent to a pool device."
+        : anyUnreachable
+            ? " Add a device to the pool, raise a cap, or wait for the pool to free up / come back online ('agents devices ping')."
+            : ' Add a device to the pool, raise a cap, or bring an overloaded box under load.';
+    return `${head} ${perDevice}.${hint}`;
+}
 /** True when `device` names the local machine (case-insensitive). */
 function isLocalDevice(device) {
     return device.toLowerCase() === machineId();
@@ -97,14 +146,134 @@ export function pickLeastLoaded(devices, roster, maxConcurrent) {
     }
     return best;
 }
+/** Load cost for a signal: worst of load% and mem%, or undefined when neither
+ * was probed. The "how full is this box" number the finer rank tiebreak reads. */
+function loadCost(s) {
+    if (!s)
+        return undefined;
+    const vals = [s.loadPercent, s.memPercent].filter((v) => typeof v === 'number');
+    return vals.length ? Math.max(...vals) : undefined;
+}
+/** Rank a headroom bucket into a load TIER (lower is less loaded). An unprobed
+ * device sits between `light` and `busy` — preferred over a known-busy box but
+ * not over a known-idle one. `loaded` is excluded before ranking, so it never
+ * reaches here. */
+function headroomTier(h) {
+    switch (h) {
+        case 'idle': return 0;
+        case 'light': return 1;
+        case 'busy': return 3;
+        default: return 2; // 'unknown' / undefined
+    }
+}
+/**
+ * Split the pool into the viable set and the excluded set (with reasons), from
+ * the caps + live signals. Pure — the caller decides what to do with an empty
+ * viable set. Reasons are checked in a stable order (unreachable → not-installed
+ * → overloaded → capped) so a device reports its most fundamental blocker first.
+ */
+export function classifyExclusions(devices, roster, opts) {
+    const load = loadByDevice(devices, roster);
+    const caps = opts?.maxConcurrent ?? {};
+    const signals = opts?.signals;
+    const eligible = [];
+    const excluded = [];
+    for (const d of devices) {
+        const s = signals?.get(d);
+        if (s?.reachable === false) {
+            excluded.push({ device: d, reason: 'unreachable' });
+            continue;
+        }
+        if (s?.installed === false) {
+            excluded.push({ device: d, reason: 'not-installed' });
+            continue;
+        }
+        if (s?.headroom === 'loaded') {
+            excluded.push({ device: d, reason: 'overloaded' });
+            continue;
+        }
+        const cap = caps[d];
+        if (cap !== undefined && (load.get(d) ?? 0) >= cap) {
+            excluded.push({ device: d, reason: 'capped', detail: `${load.get(d) ?? 0}/${cap}` });
+            continue;
+        }
+        eligible.push(d);
+    }
+    return { eligible, excluded };
+}
+/**
+ * Health-, harness-, and load-aware pick over a pool (RUSH-2002). Filters
+ * unreachable / overloaded / capped / not-installed devices, then ranks the
+ * survivors by: (a) agent signed in, (b) lower load (headroom tier, then raw
+ * load cost), (c) fewer running teammates, ties broken by pool order. Throws
+ * {@link NoViableDeviceError} when nothing survives — never returns a local
+ * fallback. Pure: all I/O is pre-resolved into `opts.signals`.
+ */
+export function pickBestDevice(devices, roster, opts) {
+    if (devices.length === 0) {
+        throw new Error('pickBestDevice called with an empty device pool');
+    }
+    const load = loadByDevice(devices, roster);
+    const { eligible, excluded } = classifyExclusions(devices, roster, opts);
+    if (eligible.length === 0) {
+        // A pool excluded ONLY for unreachability is a probe MISS / transient infra
+        // blip (a worker went briefly unresponsive during `teams start`), not proof
+        // the agent can't RUN there. Per the fail-loud contract — fire only on
+        // positive evidence (not-installed / saturated), never on a bare
+        // reachability miss — degrade to a best-effort roster-count pick so the wave
+        // retries and the real error surfaces at SSH dispatch, instead of a hard
+        // exit-1 that strands an all-remote pool on a transient blip.
+        const onlyUnreachable = excluded.every((e) => e.reason === 'unreachable');
+        if (!onlyUnreachable) {
+            throw new NoViableDeviceError(excluded, opts?.agentLabel);
+        }
+        let fallback = devices[0];
+        let fallbackLoad = load.get(fallback) ?? 0;
+        for (const d of devices) {
+            const l = load.get(d) ?? 0;
+            if (l < fallbackLoad) {
+                fallback = d;
+                fallbackLoad = l;
+            }
+        }
+        return fallback;
+    }
+    const signals = opts?.signals;
+    const order = new Map(devices.map((d, i) => [d, i]));
+    // Ascending composite sort — the first element is the best placement.
+    return [...eligible].sort((a, b) => {
+        const sa = signals?.get(a);
+        const sb = signals?.get(b);
+        // (a) signed-in agent first.
+        const signedIn = (sa?.signedIn === true ? 0 : 1) - (sb?.signedIn === true ? 0 : 1);
+        if (signedIn !== 0)
+            return signedIn;
+        // (b) lower load — coarse headroom tier, then raw load cost.
+        const tier = headroomTier(sa?.headroom) - headroomTier(sb?.headroom);
+        if (tier !== 0)
+            return tier;
+        // (c) fewer running teammates.
+        const teammates = (load.get(a) ?? 0) - (load.get(b) ?? 0);
+        if (teammates !== 0)
+            return teammates;
+        // finer load tiebreak: a known-lower load wins; unknown sits mid (50).
+        const cost = (loadCost(sa) ?? 50) - (loadCost(sb) ?? 50);
+        if (cost !== 0)
+            return cost;
+        // stable: first declared in the pool wins.
+        return (order.get(a) ?? 0) - (order.get(b) ?? 0);
+    })[0];
+}
 /**
  * Resolve where a teammate runs. Returns `{ device: null }` for a local run
  * (no pin, no pool, or the chosen device is the local machine) and
  * `{ device: <name> }` for a remote placement. See the cascade in the module
- * header.
+ * header. Throws {@link NoViableDeviceError} when a required pool has no viable
+ * host — the caller surfaces it at `teams start` rather than falling back local.
  */
 export function resolvePlacement(team, explicitDevice, roster, opts) {
-    // 1. Explicit pin wins — even without a pool.
+    // 1. Explicit pin wins — even without a pool — and is never second-guessed
+    //    (the remote `agents run` surfaces any install/health issue there).
     if (explicitDevice) {
         return { device: isLocalDevice(explicitDevice) ? null : explicitDevice };
     }
@@ -112,11 +281,19 @@ export function resolvePlacement(team, explicitDevice, roster, opts) {
     // 4. No pool → local, exactly like today.
     if (pool.length === 0)
         return { device: null };
-    // 2. Pool of one → the whole team runs there.
+    // 2. Pool of one → the whole team runs there. Respect the choice for
+    //    load/cap/reachability, but still fail loud when the agent is provably
+    //    NOT installed there — running it would be futile.
     if (pool.length === 1) {
+        if (opts?.signals?.get(pool[0])?.installed === false) {
+            throw new NoViableDeviceError([{ device: pool[0], reason: 'not-installed' }], opts.agentLabel);
+        }
         return { device: isLocalDevice(pool[0]) ? null : pool[0] };
     }
-    // 3. Many → least-loaded across the pool (cap-aware when caps are provided).
-    const picked = pickLeastLoaded(pool, roster, opts?.maxConcurrent);
+    // 3. Many → best viable pick. With live signals, this is health-, harness-,
+    //    and load-aware; without them it degrades to the cap-aware roster count.
+    const picked = opts?.signals
+        ? pickBestDevice(pool, roster, opts)
+        : pickLeastLoaded(pool, roster, opts?.maxConcurrent);
     return { device: isLocalDevice(picked) ? null : picked };
 }

package/dist/lib/tmux/session.d.ts

@@ -179,6 +179,14 @@ export declare const AGENT_HOOK_SCHEMA = 5;
 export declare function agentPaneDiedHook(sessionName: string, agentPane: string): string;
 /** Stamp a session's hook-schema marker to the current version. */
 export declare function markSessionHookSchema(name: string, socket?: string): Promise<void>;
+/**
+ * Decide whether a native resume may attach an existing managed tmux session.
+ * Only a positively resolved, living agent pane is reusable. Metadata-less
+ * legacy sessions and stale metadata resolve their real first pane through
+ * tmux before the decision; a dead or unreadable session is reaped so the
+ * caller can create a fresh wrapper for the resumed harness.
+ */
+export declare function prepareSessionForResume(name: string, socket?: string): Promise<'attach' | 'create'>;
 /**
  * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
  * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:

package/dist/lib/tmux/session.js

@@ -359,6 +359,28 @@ async function lowestPaneId(name, socket) {
         return undefined;
     return ids.reduce((lo, id) => (parseInt(id.slice(1), 10) < parseInt(lo.slice(1), 10) ? id : lo));
 }
+/**
+ * Decide whether a native resume may attach an existing managed tmux session.
+ * Only a positively resolved, living agent pane is reusable. Metadata-less
+ * legacy sessions and stale metadata resolve their real first pane through
+ * tmux before the decision; a dead or unreadable session is reaped so the
+ * caller can create a fresh wrapper for the resumed harness.
+ */
+export async function prepareSessionForResume(name, socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    if (!(await hasSession(name, sock)))
+        return 'create';
+    const recordedPane = readSessionMeta(name)?.pane;
+    const recordedState = recordedPane ? await paneExitStatus(recordedPane, sock) : undefined;
+    const pane = recordedPane && recordedState?.found
+        ? recordedPane
+        : await lowestPaneId(name, sock);
+    const state = pane ? await paneExitStatus(pane, sock) : undefined;
+    if (pane && state?.found && !state.dead)
+        return 'attach';
+    await killSession(name, sock);
+    return 'create';
+}
 /**
  * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
  * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:

package/dist/lib/types.d.ts

@@ -1064,6 +1064,8 @@ export interface HostEntry {
     address?: string;
     /** SSH user — inline hosts only. */
     user?: string;
+    /** Explicit private key inherited from a fleet device profile. */
+    identityFile?: string;
     /** Captured at enroll probe. */
     os?: string;
     /** Free-form capability tags for routing (e.g. ['gpu']). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.25",
+  "version": "1.22.27",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",