@phnx-labs/agents-cli 1.20.89 → 1.20.90

package/dist/lib/hosts/dispatch.js

@@ -93,7 +93,25 @@ export function remoteCdPrefix(remoteCwd, opts = {}) {
  * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
  */
 export function withActorEnv(env) {
-    return { ...actorEnv(resolveActor()), ...(env ?? {}) };
+    return { ...actorEnv(resolveActor()), ...terminalIdEnv(), ...(env ?? {}) };
+}
+/**
+ * Forward the launching editor tab's `AGENT_TERMINAL_ID` across the SSH hop.
+ *
+ * Factory stamps it on every terminal it spawns, and the remote `agents run`
+ * records it in its pid registry (`writePidSessionEntry`) — which is what lets a
+ * tab ask the device "which session is MY terminal running?" instead of guessing
+ * from local state. Without the forward the remote registry has no terminal id,
+ * that question is unanswerable, and the tab is stuck with its spawn-time id even
+ * after the agent has moved to a different session (a `/clear`, or an exit and
+ * rerun in the same tab).
+ *
+ * Same shape as the actor provenance above: absent when the launch did not come
+ * from a tracked terminal, never fabricated.
+ */
+function terminalIdEnv() {
+    const terminalId = process.env.AGENT_TERMINAL_ID?.trim();
+    return terminalId ? { AGENT_TERMINAL_ID: terminalId } : {};
 }
 /**
  * Launch a detached login-shell command in its own Unix session/process group.

package/dist/lib/hq/floor.js

@@ -30,6 +30,18 @@ function teammateName(session, teammatesById) {
 function moodForSession(session, hasOpenBlock) {
     if (session.status === 'abandoned')
         return 'blocked';
+    // A crashed session is NOT `done` — it stopped without finishing, and its last
+    // parsed turn often still says `working`, which would otherwise reach the Floor
+    // as a happily-running agent. Both lost-host states need a human.
+    if (session.status === 'crashed')
+        return 'blocked';
+    // An orphaned session that is genuinely mid-question needs an answer; one that
+    // is merely idle-and-unwatched needs someone to reattach or clean it up. Same
+    // distinction `isAwaitingUser` draws — giving both the high-intensity "needs
+    // input" alert would train the operator to ignore it.
+    if (session.status === 'orphaned') {
+        return session.activity === 'waiting_input' ? 'waiting' : 'blocked';
+    }
     if (session.status === 'closed')
         return 'done';
     if (session.status === 'input_required' || session.activity === 'waiting_input' || hasOpenBlock)

package/dist/lib/picker.d.ts

@@ -77,9 +77,14 @@ export interface DynamicPickerConfig<T, F> {
     /**
      * Side-effecting keys that don't change the filter (e.g. `y` copies a command).
      * Receives the live search `query` so the effect can be search-aware. Return a
-     * short string to flash under the list.
+     * short string to flash under the list, or `{ flash, reload }` when the effect
+     * changed something the rows RENDER (a star, a mark) and the list has to be
+     * rebuilt — the row labels are memoized, so a flash alone leaves them stale.
      */
-    onKey?: (name: string, filter: F, active: T | undefined, query: string) => string | void;
+    onKey?: (name: string, filter: F, active: T | undefined, query: string) => string | void | {
+        flash?: string;
+        reload?: boolean;
+    };
     /** Key that enters search mode (default `s`). */
     searchKey?: string;
     /** Key that toggles the preview pane (default `tab`). */
@@ -89,6 +94,26 @@ export interface DynamicPickerConfig<T, F> {
     loadingMessage?: string;
     enterHint?: string;
 }
+/**
+ * The lookup token for a hotkey: the literal character the key produced, else
+ * readline's key name (`tab`, `escape`, arrows).
+ *
+ * readline reports both `f` and `F` as name `f` — only `sequence` tells them
+ * apart — and gives a punctuation key like `*` no name at all. Keying on the
+ * character makes shifted letters and punctuation bindable, and is a no-op for
+ * every existing binding: for a plain lowercase letter, sequence === name.
+ *
+ * Callers receiving this in `onKey` see the literal character, so a handler that
+ * wants to accept both cases of a letter must say so (`'y'` and `'Y'`); the
+ * keyBindings lookup falls back to the key NAME, which keeps the shifted form of
+ * an existing single-letter binding working without each caller restating it.
+ */
+export declare function hotkeyToken(key: {
+    name?: string;
+    sequence?: string;
+    ctrl?: boolean;
+    meta?: boolean;
+}): string;
 /** The result returned when the user selects a row: the item plus the live filter. */
 export interface DynamicPicked<T, F> {
     item: T;

package/dist/lib/picker.js

@@ -324,6 +324,28 @@ export function multiItemPicker(config) {
     });
     return prompt(config);
 }
+/**
+ * The lookup token for a hotkey: the literal character the key produced, else
+ * readline's key name (`tab`, `escape`, arrows).
+ *
+ * readline reports both `f` and `F` as name `f` — only `sequence` tells them
+ * apart — and gives a punctuation key like `*` no name at all. Keying on the
+ * character makes shifted letters and punctuation bindable, and is a no-op for
+ * every existing binding: for a plain lowercase letter, sequence === name.
+ *
+ * Callers receiving this in `onKey` see the literal character, so a handler that
+ * wants to accept both cases of a letter must say so (`'y'` and `'Y'`); the
+ * keyBindings lookup falls back to the key NAME, which keeps the shifted form of
+ * an existing single-letter binding working without each caller restating it.
+ */
+export function hotkeyToken(key) {
+    const seq = key.sequence;
+    // Printable single characters only — a control code's sequence (`\t`, `\r`,
+    // `\x7f`) must keep resolving to its name.
+    if (!key.ctrl && !key.meta && seq && seq.length === 1 && seq > ' ' && seq !== '\x7f')
+        return seq;
+    return key.name ?? '';
+}
 /**
  * Async-refetch variant of {@link itemPicker}. Holds a `filter` object in state and
  * re-runs `load(filter)` whenever a keybinding mutates it (with a loading placeholder
@@ -349,11 +371,32 @@ export function dynamicPicker(config) {
         const [previewOpen, setPreviewOpen] = useState(Boolean(cfg.buildPreview));
         const [active, setActive] = useState(0);
         const [flash, setFlash] = useState('');
+        // Bumped by an `onKey` that asks for a reload; a dep of the load effect, so a
+        // side effect that changed the rows can rebuild them without a filter change.
+        const [reloadNonce, setReloadNonce] = useState(0);
+        // The counter lives in a ref, not in the state read back from the keypress
+        // closure: that closure can hold a STALE `reloadNonce`, so a second reload
+        // would recompute the same value, the state would not change, and the
+        // repaint would silently never happen (the first star appeared, the second
+        // did not). A ref is always current.
+        const reloadCount = useRef(0);
+        // Bumped when a load RESOLVES. `load` is async, so the render that follows
+        // `setReloadNonce` still sees the pre-load data — memoizing the row labels on
+        // the nonce alone rendered each press's result one press late. Keying them on
+        // load COMPLETION is what actually makes them current.
+        const [loadedSeq, setLoadedSeq] = useState(0);
+        const loadedCount = useRef(0);
         const prefix = usePrefix({ status, theme });
         // Guards against a slow load resolving after a newer filter superseded it.
         const gen = useRef(0);
+        // The filter the last load ran on, so a nonce-only reload (a row's own state
+        // changed) can keep the cursor where the user left it. Snapping back to the
+        // top every time you star a row would make the key unusable for a second one.
+        const loadedFilter = useRef(undefined);
         useEffect(() => {
             const my = ++gen.current;
+            const filterChanged = loadedFilter.current !== filter;
+            loadedFilter.current = filter;
             setLoading(true);
             Promise.resolve(cfg.load(filter))
                 .then((rows) => {
@@ -361,7 +404,9 @@ export function dynamicPicker(config) {
                     return;
                 setItems(rows);
                 setLoading(false);
-                setActive(0);
+                setLoadedSeq((loadedCount.current += 1));
+                if (filterChanged)
+                    setActive(0);
             })
                 .catch(() => {
                 if (my !== gen.current)
@@ -369,7 +414,7 @@ export function dynamicPicker(config) {
                 setItems([]);
                 setLoading(false);
             });
-        }, [filter]);
+        }, [filter, reloadNonce]);
         const results = useMemo(() => {
             const q = query.trim();
             const pool = q && cfg.matches ? items.filter((it) => cfg.matches(it, q)) : items;
@@ -377,7 +422,12 @@ export function dynamicPicker(config) {
                 value: item,
                 label: cfg.labelFor(item, q),
             }));
-        }, [items, query]);
+            // `loadedSeq` is a dep because a reload can legitimately return the SAME
+            // array — `load` hands back its cached pool unchanged when no filter is
+            // active — while what a row RENDERS has changed underneath it. Without this
+            // the labels stay memoized on the old state and the side effect looks like
+            // it silently did nothing (starring a row left the star invisible).
+        }, [items, query, loadedSeq]);
         useEffect(() => {
             if (active >= results.length)
                 setActive(0);
@@ -462,7 +512,13 @@ export function dynamicPicker(config) {
                 setPreviewOpen(!previewOpen);
                 return;
             }
-            const binding = cfg.keyBindings?.[key.name ?? ''];
+            const token = hotkeyToken(key);
+            // Exact character first (so `*` and a shifted `F` are addressable), then
+            // the readline name. The fallback is what preserves the shifted form of an
+            // existing single-letter hotkey: `R`/`C`/`A` used to reach their bindings
+            // via `key.name`, and keying on the character alone would silently retire
+            // them for anyone with caps lock on.
+            const binding = cfg.keyBindings?.[token] ?? cfg.keyBindings?.[key.name ?? ''];
             if (binding) {
                 const next = binding(filter);
                 if (!Object.is(next, filter))
@@ -470,9 +526,17 @@ export function dynamicPicker(config) {
                 return;
             }
             if (cfg.onKey) {
-                const msg = cfg.onKey(key.name ?? '', filter, selected?.value, query);
-                if (msg)
-                    setFlash(msg);
+                const res = cfg.onKey(token, filter, selected?.value, query);
+                if (typeof res === 'string')
+                    setFlash(res);
+                else if (res) {
+                    if (res.flash)
+                        setFlash(res.flash);
+                    // The rows themselves changed — force the load effect to re-run so the
+                    // memoized labels are rebuilt.
+                    if (res.reload)
+                        setReloadNonce((reloadCount.current += 1));
+                }
             }
         });
         const message = theme.style.message(cfg.message, status);

package/dist/lib/profiles.d.ts

@@ -29,6 +29,18 @@ export interface Profile {
     description?: string;
     preset?: string;
     provider?: string;
+    /**
+     * Human-facing label for the harness — what `agents view` prints as the
+     * agent-type header, the same slot `AGENTS[id].name` fills for a native
+     * harness. Defaults to the profile name when unset.
+     */
+    label?: string;
+    /**
+     * Name of the harness this one was forked from — either a native agent id
+     * (`claude`, `opencode`) or another custom harness. Display-only lineage:
+     * the fork is a full copy, so deleting the source never affects it.
+     */
+    forkedFrom?: string;
     /**
      * Optional secondary model retried on the same host when the primary model
      * env value hits a rate limit. Reuses the `--fallback` cascade in
@@ -45,12 +57,19 @@ export interface Profile {
  */
 export interface ProfileSummary {
     name: string;
+    /** Human-facing header label — `label` when set, else the profile name. */
+    label: string;
     agent: AgentId;
     host: string;
+    /** Host version pin, or null when the harness follows the host's default. */
+    hostVersion: string | null;
     provider: string;
     model: string;
     auth: string;
     path: string;
+    description: string | null;
+    /** Native agent id or custom harness this one was forked from, if recorded. */
+    forkedFrom: string | null;
 }
 /** Get the directory where profile YAML files are stored. */
 export declare function getProfilesDir(): string;
@@ -91,6 +110,11 @@ export declare function profileModelEnvKey(profile: Profile): string | null;
  * - No auth at all: provider only.
  */
 export declare function profileAuthLabel(profile: Profile): string;
+/**
+ * Header label for the harness — the slot `AGENTS[id].name` fills for a native
+ * harness, so `agents view` can print custom and native harnesses the same way.
+ */
+export declare function profileLabel(profile: Profile): string;
 /** Build a stable, machine-readable summary for list and view surfaces. */
 export declare function profileSummary(profile: Profile): ProfileSummary;
 /**
@@ -115,6 +139,8 @@ export interface HostModelOptions {
     /** Env var the host reads its auth token from; pair with `provider` to attach keychain auth. */
     authEnvVar?: string;
     description?: string;
+    /** Human-facing header label; defaults to the harness name. */
+    label?: string;
 }
 /**
  * Build a custom-harness profile from a host CLI + model in one shot, without a
@@ -123,6 +149,28 @@ export interface HostModelOptions {
  * (hosts that manage their own login — e.g. opencode — need neither).
  */
 export declare function profileFromHostModel(name: string, host: AgentId, model: string, opts?: HostModelOptions): Profile;
+/** Overrides applied on top of the source when forking a harness. */
+export interface ForkProfileOptions {
+    /** Swap the pinned model. Written onto the source's model env key when it has
+     *  one, else onto the host's canonical model var. */
+    model?: string;
+    /** Swap the endpoint. Only applied for hosts with a known base-URL var. */
+    baseUrl?: string;
+    /** Repoint auth at a different provider's keychain item. */
+    provider?: string;
+    /** Env var the host reads its token from; pair with `provider`. */
+    authEnvVar?: string;
+    /** Re-pin (or unpin, with an empty string) the host CLI version. */
+    version?: string;
+    label?: string;
+    description?: string;
+}
+/**
+ * Copy an existing harness under a new name, applying overrides. The fork is a
+ * full copy — env, auth binding, and fallback model all carry over — so the two
+ * diverge from here and deleting the source never affects the fork.
+ */
+export declare function forkProfile(source: Profile, name: string, opts?: ForkProfileOptions): Profile;
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the

package/dist/lib/profiles.js

@@ -197,16 +197,27 @@ export function profileAuthLabel(profile) {
     }
     return provider;
 }
+/**
+ * Header label for the harness — the slot `AGENTS[id].name` fills for a native
+ * harness, so `agents view` can print custom and native harnesses the same way.
+ */
+export function profileLabel(profile) {
+    return profile.label || profile.name;
+}
 /** Build a stable, machine-readable summary for list and view surfaces. */
 export function profileSummary(profile) {
     return {
         name: profile.name,
+        label: profileLabel(profile),
         agent: profile.host.agent,
         host: profileHostLabel(profile),
+        hostVersion: profile.host.version ?? null,
         provider: profileProviderLabel(profile),
         model: profileModelLabel(profile),
         auth: profileAuthLabel(profile),
         path: getProfilePath(profile.name),
+        description: profile.description ?? null,
+        forkedFrom: profile.forkedFrom ?? null,
     };
 }
 /**
@@ -227,6 +238,7 @@ export function profileFromPreset(profileName, preset, version) {
         description: preset.description,
         preset: preset.name,
         provider: preset.provider,
+        forkedFrom: preset.host,
     };
 }
 /**
@@ -285,13 +297,68 @@ export function profileFromHostModel(name, host, model, opts = {}) {
         env,
         description: opts.description ?? `Custom harness: ${host} + ${model}`,
         provider: opts.provider ?? host,
+        forkedFrom: host,
     };
+    if (opts.label)
+        profile.label = opts.label;
     if (opts.provider && opts.authEnvVar) {
         profile.auth = { envVar: opts.authEnvVar, keychainItem: keychainItemName(opts.provider) };
         profile.authOptional = false;
     }
     return profile;
 }
+/**
+ * Copy an existing harness under a new name, applying overrides. The fork is a
+ * full copy — env, auth binding, and fallback model all carry over — so the two
+ * diverge from here and deleting the source never affects the fork.
+ */
+export function forkProfile(source, name, opts = {}) {
+    validateProfileName(name);
+    const host = source.host.agent;
+    const env = { ...source.env };
+    if (opts.model) {
+        env[profileModelEnvKey(source) ?? modelEnvKeyForHost(host)] = opts.model;
+    }
+    if (opts.baseUrl) {
+        const key = baseUrlEnvKeyForHost(host);
+        if (!key) {
+            throw new Error(`Host '${host}' has no known base-URL env var; drop --base-url or fork onto a claude/codex host.`);
+        }
+        env[key] = opts.baseUrl;
+    }
+    const forked = {
+        ...source,
+        name,
+        host: { agent: host, ...(opts.version ? { version: opts.version } : source.host.version ? { version: source.host.version } : {}) },
+        env,
+        // The source's description names the source's model, so inheriting it
+        // across a model swap would describe the fork wrongly.
+        description: opts.description ?? (opts.model ? `Forked from ${source.name}: ${opts.model}` : source.description),
+        forkedFrom: source.name,
+    };
+    // `label` is the header `agents view` prints, so an inherited one would make
+    // the fork and its source visually identical — the ambiguity a per-harness
+    // block exists to remove. A fork carries a label only when it is given one;
+    // otherwise `profileLabel` falls back to the fork's own name.
+    if (opts.label)
+        forked.label = opts.label;
+    else
+        delete forked.label;
+    // A fork that repoints the model or endpoint is no longer that preset — keep
+    // the preset link only while the fork still matches what the preset defines.
+    if (opts.model || opts.baseUrl)
+        delete forked.preset;
+    if (opts.provider) {
+        const envVar = opts.authEnvVar ?? source.auth?.envVar ?? authEnvKeyForHost(host);
+        if (!envVar) {
+            throw new Error(`Host '${host}' has no known auth env var; --provider cannot be attached to this fork.`);
+        }
+        forked.provider = opts.provider;
+        forked.auth = { envVar, keychainItem: keychainItemName(opts.provider) };
+        forked.authOptional = source.authOptional ?? false;
+    }
+    return forked;
+}
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the

package/dist/lib/rotate.d.ts

@@ -35,6 +35,12 @@ export interface RotateResult {
     healthy: RotateCandidate[];
     /** Candidates excluded (not signed in, or out of credits). */
     excluded: RotateCandidate[];
+    /**
+     * True when NO candidate on this machine had usage data fresh enough to decide
+     * on, so the pick was made from unverified snapshots. Callers surface it —
+     * routing blind is a fact the operator needs, not an internal detail.
+     */
+    usageUnverified?: boolean;
 }
 export declare const RUN_STRATEGIES: RunStrategy[];
 /**
@@ -60,6 +66,22 @@ export declare function getProjectRunStrategy(agent: AgentId, startPath: string)
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
+/**
+ * How old a usage snapshot may be and still settle a routing DECISION.
+ *
+ * Deliberately far tighter than the 24h stale-while-revalidate window the
+ * display paths use (`USAGE_CACHE_SWR_MS`): `agents view` rendering a slightly
+ * old bar costs nothing, but the router choosing an account from one costs the
+ * whole run. Measured case — `yosemite-s1` held snapshots 26h to 2.7 days old
+ * with a failing refresh, so balanced read `muqsit@getrush.ai` as 48% used and
+ * launched into it while the account was actually at its weekly cap.
+ */
+export declare const USAGE_DECISION_MAX_AGE_MS: number;
+/**
+ * Whether this candidate's usage number is recent enough to route on. A missing
+ * snapshot is unverified by definition — there is no number to trust.
+ */
+export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
 /**
  * Whether a specific account can serve a run right now, and — when it can't —
  * why. `signed_out` covers a missing usable credential; `rate_limited` and
@@ -118,13 +140,13 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
  */
-export declare function pickBalancedCandidate(candidates: RotateCandidate[]): RotateResult | null;
+export declare function pickBalancedCandidate(candidates: RotateCandidate[], nowMs?: number): RotateResult | null;
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most
  * usage headroom.
  */
-export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
+export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null, nowMs?: number): RotateResult | null;
 export declare function collectRunCandidates(agent: AgentId): Promise<RotateCandidate[]>;
 /**
  * Resolve an account identity to the installed version slot that holds it, over

package/dist/lib/rotate.js

@@ -70,6 +70,27 @@ function isRotationEligible(candidate) {
 function isAvailableEligible(candidate) {
     return isRotationEligible(candidate);
 }
+/**
+ * How old a usage snapshot may be and still settle a routing DECISION.
+ *
+ * Deliberately far tighter than the 24h stale-while-revalidate window the
+ * display paths use (`USAGE_CACHE_SWR_MS`): `agents view` rendering a slightly
+ * old bar costs nothing, but the router choosing an account from one costs the
+ * whole run. Measured case — `yosemite-s1` held snapshots 26h to 2.7 days old
+ * with a failing refresh, so balanced read `muqsit@getrush.ai` as 48% used and
+ * launched into it while the account was actually at its weekly cap.
+ */
+export const USAGE_DECISION_MAX_AGE_MS = 5 * 60 * 1000;
+/**
+ * Whether this candidate's usage number is recent enough to route on. A missing
+ * snapshot is unverified by definition — there is no number to trust.
+ */
+export function isUsageVerified(candidate, nowMs = Date.now()) {
+    const capturedAt = candidate.usageSnapshot?.capturedAt;
+    if (!capturedAt)
+        return false;
+    return nowMs - capturedAt.getTime() <= USAGE_DECISION_MAX_AGE_MS;
+}
 function hasUsageAvailable(candidate) {
     const snapshot = candidate.usageSnapshot;
     if (snapshot && snapshot.windows.length > 0) {
@@ -199,7 +220,7 @@ function dedupeAndSortCandidates(candidates) {
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
  */
-export function pickBalancedCandidate(candidates) {
+export function pickBalancedCandidate(candidates, nowMs = Date.now()) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
@@ -217,8 +238,31 @@ export function pickBalancedCandidate(candidates) {
         if (!deduped.has(c))
             excluded.push(c);
     }
-    const picked = weightedRandomByCapacity(sorted);
-    return { picked, healthy: sorted, excluded };
+    const { picked, usageUnverified } = preferVerified(sorted, nowMs, weightedRandomByCapacity);
+    return { picked, healthy: sorted, excluded, usageUnverified };
+}
+/**
+ * Choose from the VERIFIED candidates when any exist, else from the whole pool.
+ *
+ * An eligible account whose usage we could not confirm is a guess, not a green
+ * light: the snapshot reads "48% used" with equal confidence whether it was
+ * captured a minute or three days ago, and a box whose refresh is failing stays
+ * wrong indefinitely. Confirmed headroom therefore beats apparent headroom, even
+ * when the unconfirmed number looks better.
+ *
+ * `healthy` deliberately keeps every eligible candidate rather than just the
+ * verified ones. Declining to *pick* an account on stale data and declining to
+ * *fail over to* it after the primary has already hit a 429 are different risks:
+ * by then the alternative is not launching at all, so the failover chain
+ * (rotationFailoverChain, which reads `healthy`) keeps its full safety net —
+ * exactly on the machines this guard is protecting.
+ */
+function preferVerified(pool, nowMs, choose) {
+    const verified = pool.filter((c) => isUsageVerified(c, nowMs));
+    return {
+        picked: choose(verified.length > 0 ? verified : pool),
+        usageUnverified: verified.length === 0,
+    };
 }
 /**
  * Pick one candidate from `sorted` using weights proportional to remaining
@@ -250,7 +294,7 @@ function weightedRandomByCapacity(sorted) {
  * version has usage available; otherwise routes to the candidate with the most
  * usage headroom.
  */
-export function pickAvailableCandidate(candidates, preferredVersion) {
+export function pickAvailableCandidate(candidates, preferredVersion, nowMs = Date.now()) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
@@ -268,10 +312,17 @@ export function pickAvailableCandidate(candidates, preferredVersion) {
         if (!deduped.has(c))
             excluded.push(c);
     }
+    // `available` sorts by apparent headroom and takes the front of the list, so an
+    // unconfirmed "48% used" outranks an accurate "90% used" — the same inversion
+    // that put a launch on an exhausted account under `balanced`. It routes on the
+    // same cache, so it gets the same rule: confirmed headroom first.
+    const { picked: bestVerified, usageUnverified } = preferVerified(sorted, nowMs, (from) => from[0]);
+    // An explicit version preference is an instruction, not a ranking signal, so it
+    // still wins — but only while that version is actually eligible.
     const preferred = preferredVersion
         ? sorted.find((candidate) => candidate.version === preferredVersion)
         : undefined;
-    return { picked: preferred ?? sorted[0], healthy: sorted, excluded };
+    return { picked: preferred ?? bestVerified, healthy: sorted, excluded, usageUnverified };
 }
 export async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
@@ -299,12 +350,18 @@ export async function collectRunCandidates(agent) {
             lastActive: info.lastActive,
         };
     }));
+    // These candidates feed a routing decision, so cap how stale their usage may
+    // be (see USAGE_DECISION_MAX_AGE_MS). Past that the fetch blocks on a live
+    // read instead of serving the cache — one bounded, parallel round trip per
+    // account, and none at all inside the 2-minute fresh window that back-to-back
+    // launches hit. A failed read still falls back to the cache; the pick then
+    // routes around it via isUsageVerified rather than trusting the old number.
     const { usageByKey } = await getUsageInfoByIdentity(rows.map(({ home, info, version }) => ({
         agentId: agent,
         home,
         cliVersion: version,
         info,
-    })));
+    })), { maxAgeMs: USAGE_DECISION_MAX_AGE_MS });
     return rows.map(({ home: _home, info, ...candidate }) => {
         const usageKey = getUsageLookupKey(info);
         const usage = usageKey ? usageByKey.get(usageKey) : undefined;