@phnx-labs/agents-cli 1.22.63 → 1.22.65

package/dist/lib/accounting/rotate.js

@@ -98,6 +98,26 @@ export function isLaunchableSignedIn(signedIn, presence) {
         return true;
     return presence.perVersion;
 }
+/**
+ * Whether a SPECIFIC installed version is launchable-signed-in on THIS device,
+ * plus the account email when it is. Mirrors EXACTLY the per-version gate
+ * {@link collectRunCandidates} applies (getVersionHomePath -> getAccountInfo ->
+ * {@link isLaunchableSignedIn} over {@link credentialPresence}), so the
+ * pre-launch `run.launch` event can report the same signed-in verdict the
+ * balanced router computes for that version.
+ *
+ * The point is to make a launch into a logged-out version VISIBLE at spawn time:
+ * `--device auto` only guarantees SOME account is ready on the device, not that
+ * the specific version launched is signed in there (the yosemite-m3 2.1.219
+ * incident — 2.1.219 was logged out, the router correctly excluded it, yet it
+ * launched). Non-fatal by construction: callers wrap it best-effort.
+ */
+export async function isVersionLaunchableHere(agent, version) {
+    const home = getVersionHomePath(agent, version);
+    const info = await getAccountInfo(agent, home);
+    const launchable = isLaunchableSignedIn(info.signedIn, credentialPresence(agent, home));
+    return { launchable, email: launchable ? info.email : null };
+}
 function isAvailableEligible(candidate) {
     return isRotationEligible(candidate);
 }
@@ -111,6 +131,27 @@ function isAvailableEligible(candidate) {
  * launched into it while the account was actually at its weekly cap.
  */
 export const USAGE_DECISION_MAX_AGE_MS = 5 * 60 * 1000;
+/**
+ * How old a usage snapshot may be before routing REFUSES to run at all
+ * (NO_VERIFIED_USAGE), as opposed to merely declining to *weight* by its number.
+ *
+ * These are two different risks and now two different bars. Weighting on a
+ * slightly-old number is cheap to get wrong (a floored weight, {@link
+ * USAGE_DECISION_MAX_AGE_MS} = 5 min); refusing to launch at all is expensive to
+ * get wrong — it fails the user's `agents run` outright. The daemon's usage
+ * refresher paces proactive fetches under a fixed per-provider budget
+ * (`usage-refresh.ts`, PROVIDER_HOURLY_BUDGET), so on a multi-account fleet an
+ * IDLE account is deliberately refreshed on a stretched round-robin cadence
+ * (bounded at N × spacing — ~16 min at 8 accounts, ~32 min at 16) rather than
+ * every 5 min, which would 429 the endpoint and park it for up to an hour. A
+ * budget-paced idle reading of 10–30 min is NOT the failure this refusal exists
+ * to catch. That failure is the `yosemite-s1` case: a box whose refresh is
+ * genuinely BROKEN, holding readings 26 h – 2.7 d old. 40 min sits comfortably
+ * above the worst-case budget cadence and still an order of magnitude below the
+ * multi-hour staleness of a broken box — and actively-used accounts refresh for
+ * free via the statusline ingest, so a *busy* account is never even this old.
+ */
+export const USAGE_STALE_REFUSAL_MAX_AGE_MS = 40 * 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.
@@ -132,24 +173,30 @@ export function isUsageVerified(candidate, nowMs = Date.now()) {
     return nowMs - capturedAt.getTime() <= USAGE_DECISION_MAX_AGE_MS;
 }
 /**
- * Whether this candidate carries a STALE-but-present usage number: a snapshot
- * with windows whose capture time is older than {@link USAGE_DECISION_MAX_AGE_MS}.
+ * Whether this candidate carries a GENUINELY-STALE usage number: a snapshot with
+ * windows whose capture time is older than {@link USAGE_STALE_REFUSAL_MAX_AGE_MS}.
  *
  * This is the misleading case the initial route must refuse — the number reads
  * "48% used" with the same confidence whether captured a minute or three days
- * ago, and a box whose refresh is failing stays wrong indefinitely. It is
- * deliberately NARROWER than "not verified": a BLIND candidate with no snapshot
- * (or a plan-only meterless one with no windows) carries no number to be misled
- * by — a worker box whose usage endpoint 403s (RUSH-2392), or a meterless Grok
- * login — so it is not "stale", and an entirely-blind pool still draws a pick
- * (PHNX-3392) rather than fail loud with NO_VERIFIED_USAGE.
+ * ago, and a box whose refresh is failing stays wrong indefinitely. Two things
+ * make it NARROWER than "not verified":
+ *   1. It uses the wider REFUSAL bar, not the 5-min weighting bar. A merely
+ *      budget-paced idle account (10–30 min old) is not-verified — so it weights
+ *      at the floor, conservatively — but it is NOT "stale" and must not, on its
+ *      own, drive the whole provider to a NO_VERIFIED_USAGE refusal. Only a
+ *      genuinely broken refresh (hours old) trips this.
+ *   2. A BLIND candidate with no snapshot (or a plan-only meterless one with no
+ *      windows) carries no number to be misled by — a worker box whose usage
+ *      endpoint 403s (RUSH-2392), or a meterless Grok login — so it is not
+ *      "stale", and an entirely-blind pool still draws a pick (PHNX-3392) rather
+ *      than fail loud with NO_VERIFIED_USAGE.
  */
 export function hasStaleUsage(candidate, nowMs = Date.now()) {
     const snapshot = candidate.usageSnapshot;
     const capturedAt = snapshot?.capturedAt;
     if (!capturedAt || !snapshot?.windows.length)
         return false;
-    return nowMs - capturedAt.getTime() > USAGE_DECISION_MAX_AGE_MS;
+    return nowMs - capturedAt.getTime() > USAGE_STALE_REFUSAL_MAX_AGE_MS;
 }
 function hasUsageAvailable(candidate) {
     const snapshot = candidate.usageSnapshot;
@@ -609,7 +656,7 @@ export function formatNoVerifiedUsageError(agent, strategy, candidates, nowMs =
             const staleness = age === null ? 'no usage snapshot' : `usage ${age}m old`;
             return `${c.version} (${staleness})`;
         }).join(', ');
-    const maxAgeMin = Math.round(USAGE_DECISION_MAX_AGE_MS / 60_000);
+    const maxAgeMin = Math.round(USAGE_STALE_REFUSAL_MAX_AGE_MS / 60_000);
     return `agents: NO_VERIFIED_USAGE — no signed-in ${agent} account has usage newer than ${maxAgeMin}m under strategy '${strategy}', so routing refuses to guess on a stale number: ${detail}. Refresh usage (agents view ${agent}) or pin the default with --strategy pinned.`;
 }
 /**

package/dist/lib/accounting/usage.d.ts

@@ -172,6 +172,18 @@ export interface UsageSnapshot {
     sourceLabel: string;
     capturedAt: Date | null;
     windows: UsageWindow[];
+    /**
+     * Last-known windows the freshness gate DROPPED from `windows` — expired by
+     * `resetsAt`/`windowMinutes`, or from a rolled-over billing period. VIEW-ONLY:
+     * `agents view` renders these with a staleness age ("30% · 6h old") so the
+     * user always sees the last number instead of a bare "unavailable". Routing
+     * MUST NEVER read this field — `isUsageVerified`/`hasStaleUsage`/
+     * `hasUsageAvailable`/`deriveUsageStatusFromSnapshot` consult only `windows`,
+     * so a stale number rendered here can never make a stale account read as
+     * verified or eligible (the RUSH-2858 property). Never serialized to the
+     * on-disk cache or `--json` (both project `windows` explicitly).
+     */
+    staleWindows?: UsageWindow[];
     plan?: string | null;
     /** Action that makes an event-fed source emit a current reading. */
     refreshHint?: string | null;

package/dist/lib/accounting/usage.js

@@ -437,8 +437,22 @@ export async function getUsageInfoForIdentity(input, opts) {
     // stale snapshot here is safe, and an absent one reports
     // {@link USAGE_NOT_COLLECTED_MARKER}.
     if (readOnly) {
-        if (cached)
+        // A row carries a CONFIRMED reading when it has a fresh window, a
+        // subscription plan (meterless-healthy, e.g. Grok's tier), or a live refusal
+        // (out_of_credits / session_limit). Those report `usageError: null`.
+        if (cached && (cached.windows.length > 0 || cached.plan || cached.unavailable)) {
             return { snapshot: cached, error: null };
+        }
+        // A row whose ONLY content is last-known stale readings — the all-expired
+        // Claude case, its windows moved to `staleWindows` (view-only) so the
+        // TERMINAL view still renders the number with its age — must NOT read as a
+        // healthy account. `staleWindows` is deliberately excluded from `--json`
+        // (which projects only `windows`), so keep `usageError` non-null: a consumer
+        // polling `agents view --json` must still see the staleness signal, the exact
+        // RUSH-2858 weeks-stale case this marker exists for. The snapshot is still
+        // returned, so the human view is unaffected.
+        if (cached)
+            return { snapshot: cached, error: USAGE_NOT_COLLECTED_MARKER };
         return { snapshot: null, error: USAGE_NOT_COLLECTED_MARKER };
     }
     // Explicit refresh: block on the shared device collector.
@@ -590,14 +604,25 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         // multi-meter agent cannot force the whole table to wrap.
         const selected = pickCompactUsageWindows(snapshot.windows, opts?.maxWindows);
         const hidden = Math.max(0, snapshot.windows.filter((w) => w.key !== 'sonnet_week').length - selected.length);
+        // Last-known windows the freshness gate dropped (see UsageSnapshot.staleWindows).
+        // Rendered with an age suffix so a stale reading stays visible instead of a
+        // bare "unavailable"; never in `snapshot.windows`, so routing never sees them.
+        const now = new Date();
+        const staleWindows = snapshot.staleWindows ?? [];
+        const staleByKey = new Map(staleWindows.map((w) => [w.key, w]));
         const expected = opts?.expectedWindows;
         const windowsToRender = expected
-            ? expected.map(({ key, shortLabel }) => ({ window: selected.find((item) => item.key === key), shortLabel }))
-            : selected.map((window) => ({ window, shortLabel: window.shortLabel }));
-        const windowParts = windowsToRender.map(({ window, shortLabel }, index) => {
+            ? expected.map(({ key, shortLabel }) => ({ key, window: selected.find((item) => item.key === key), shortLabel }))
+            : selected.map((window) => ({ key: window.key, window, shortLabel: window.shortLabel }));
+        const windowParts = windowsToRender.map(({ key, window, shortLabel }, index) => {
             if (!window) {
-                const missing = chalk.dim(`${shortLabel}: ${NO_DATA.repeat(COMPACT_BAR_LEN)} unavailable`);
-                return index < windowsToRender.length - 1 ? padToWidth(missing, 20) : missing;
+                // A window we expected but have no fresh reading for: render the
+                // last-known value with its age if we still have it, else "unavailable".
+                const stale = staleByKey.get(key);
+                const rendered = stale
+                    ? renderStaleUsageWindow(stale, snapshot.capturedAt, shortLabel, now)
+                    : chalk.dim(`${shortLabel}: ${NO_DATA.repeat(COMPACT_BAR_LEN)} unavailable`);
+                return index < windowsToRender.length - 1 ? padToWidth(rendered, 20) : rendered;
             }
             const bar = renderCompactUsageBar(window.usedPercent);
             const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
@@ -611,6 +636,16 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         if (windowParts.length > 0) {
             parts.push(windowParts.join('  '));
         }
+        else if (staleWindows.length > 0) {
+            // No fresh bars, but we have last-known readings (e.g. Grok's weekly bar
+            // from an ended billing period): show them with an age suffix rather than
+            // the "run once to refresh" hint, which hid a number we actually had.
+            const cap = opts?.maxWindows ?? staleWindows.length;
+            const rendered = staleWindows
+                .slice(0, cap)
+                .map((w) => renderStaleUsageWindow(w, snapshot.capturedAt, w.shortLabel, now));
+            parts.push(rendered.join('  '));
+        }
         else if (snapshot.refreshHint) {
             parts.push(chalk.dim(snapshot.refreshHint));
         }
@@ -1879,9 +1914,12 @@ function serializeClaudeUsageSnapshot(snapshot) {
  * have burned since. Zeroing-but-keeping it (the previous behavior) rendered a
  * weeks-frozen cache as "S: 0% (now)" with `deriveUsageStatusFromSnapshot` →
  * 'available', so a genuinely rate-limited account read as an idle dispatch
- * candidate (RUSH-2858). Dropping mirrors the Grok collector, and an all-expired
- * snapshot deserializes to null so `readClaudeUsageCache` deletes the entry and
- * callers surface "usage unavailable" plus the recorded throttle reason.
+ * candidate (RUSH-2858). Dropping keeps them out of `windows` (routing stays
+ * blind), but they are preserved on `staleWindows` so the view can render the
+ * last-known number with its age instead of a bare "unavailable" — a row that
+ * carries only stale windows therefore survives (it is worth showing), and only
+ * a row with NOTHING to show — no fresh window, no stale window, no plan, no
+ * refusal — deserializes to null so `readClaudeUsageCache` deletes it.
  *
  * A row that carries a plan survives even with no fresh windows: the plan is a
  * truthful reading in its own right, and losing it is what made the cached view
@@ -1889,16 +1927,21 @@ function serializeClaudeUsageSnapshot(snapshot) {
  */
 function deserializeClaudeUsageSnapshot(snapshot, now) {
     const capturedAt = parseDateValue(snapshot.capturedAt);
-    const windows = snapshot.windows
-        .map((window) => ({
+    const deserialized = snapshot.windows.map((window) => ({
         key: window.key,
         label: window.label,
         shortLabel: window.shortLabel,
         usedPercent: window.usedPercent,
         resetsAt: parseDateValue(window.resetsAt),
         windowMinutes: window.windowMinutes,
-    }))
-        .filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
+    }));
+    const windows = deserialized.filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
+    // The dropped windows are still the LAST reading we saw for those meters —
+    // routing must not trust them (they stay out of `windows`), but the view
+    // renders them with an age suffix rather than a bare "unavailable" (see
+    // UsageSnapshot.staleWindows). Skip any meter that already has a fresh row.
+    const freshKeys = new Set(windows.map((window) => window.key));
+    const staleWindows = deserialized.filter((window) => !freshKeys.has(window.key) && !isCachedUsageWindowFresh(window, capturedAt, now));
     const unavailable = deserializeUnavailable(snapshot.unavailable, now);
     // A windowless row is not automatically worthless. Grok's collector reports
     // the subscription tier and no meters at all, so treating "no fresh windows"
@@ -1910,7 +1953,11 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
     // and `deriveUsageStatusFromSnapshot` still returns null for zero windows, so
     // it can never read as a 0% bar or an "available" badge (the RUSH-2858
     // property that made expired windows drop in the first place).
-    if (windows.length === 0 && !unavailable && !snapshot.plan && !snapshot.refreshHint) {
+    if (windows.length === 0 &&
+        staleWindows.length === 0 &&
+        !unavailable &&
+        !snapshot.plan &&
+        !snapshot.refreshHint) {
         return null;
     }
     return {
@@ -1918,6 +1965,7 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         sourceLabel: CACHED_CLAUDE_USAGE_SOURCE_LABEL,
         capturedAt,
         windows,
+        staleWindows: staleWindows.length > 0 ? staleWindows : undefined,
         plan: snapshot.plan ?? null,
         refreshHint: snapshot.refreshHint ?? null,
         unavailable,
@@ -2246,6 +2294,56 @@ function formatResetHint(date) {
     const days = Math.round(hours / 24);
     return `${days}d`;
 }
+/**
+ * Compact elapsed-time label for a stale reading's age: "30m", "6h", "2d".
+ * Coarse single-unit like {@link formatResetHint}, floored at "1m" so a
+ * just-expired window never reads "0m".
+ */
+function formatAgeShort(diffMs) {
+    const mins = Math.max(1, Math.round(diffMs / 60000));
+    if (mins < 60)
+        return `${mins}m`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.round(hours / 24);
+    return `${days}d`;
+}
+/**
+ * Staleness suffix for a last-known window the freshness gate dropped. A window
+ * whose reset/period boundary passed while the sample itself is still inside its
+ * `windowMinutes` rolled OVER — the number describes a period that is done, so
+ * name it ("period ended 1h ago", e.g. Grok's weekly billing period). A window
+ * that aged past its own `windowMinutes` (Claude's 5h session read never
+ * refreshed in time) is a stale sample of a still-rolling window, so report the
+ * capture age ("6h old"). Falls back to the reset age, then a bare "stale".
+ */
+function formatStaleWindowSuffix(window, capturedAt, now) {
+    const resetPassed = !!window.resetsAt && window.resetsAt.getTime() <= now.getTime();
+    const captureExpired = !!capturedAt &&
+        window.windowMinutes !== null &&
+        capturedAt.getTime() + window.windowMinutes * 60 * 1000 <= now.getTime();
+    if (resetPassed && !captureExpired) {
+        return `stale (period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())} ago)`;
+    }
+    if (capturedAt)
+        return `${formatAgeShort(now.getTime() - capturedAt.getTime())} old`;
+    if (resetPassed)
+        return `stale (period ended ${formatAgeShort(now.getTime() - window.resetsAt.getTime())} ago)`;
+    return 'stale';
+}
+/**
+ * Render a dropped-but-last-known window as "S: ▍░░░░ 30% · 6h old": the gauge
+ * and percentage exactly as a live bar, then a dim staleness suffix so the
+ * number is always visible and unmistakably not current. VIEW-ONLY — these
+ * windows are never in `snapshot.windows`, so routing never sees them.
+ */
+function renderStaleUsageWindow(window, capturedAt, shortLabel, now) {
+    const bar = renderCompactUsageBar(window.usedPercent);
+    const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
+    const suffix = formatStaleWindowSuffix(window, capturedAt, now);
+    return `${chalk.gray(`${shortLabel}:`)} ${bar} ${pct} ${chalk.dim(`· ${suffix}`)}`;
+}
 /** Format a reset timestamp as a human-readable relative or absolute time. */
 function formatResetAt(date) {
     const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -2308,8 +2406,13 @@ async function getGrokUsageInfo(options) {
         // (see readLatestGrokBilling).
         const now = new Date();
         const windows = match.windows.filter((window) => isCachedUsageWindowFresh(window, match.capturedAt, now));
+        // A window from an ended billing period is the LAST reading we saw — routing
+        // must not trust it (kept out of `windows`), but the view renders it with a
+        // "period ended Xh ago" suffix instead of the bare refresh hint. Only when
+        // there is nothing at all to show does the refresh hint stand alone.
+        const staleWindows = match.windows.filter((window) => !isCachedUsageWindowFresh(window, match.capturedAt, now));
         const version = options?.cliVersion;
-        const refreshHint = windows.length === 0
+        const refreshHint = windows.length === 0 && staleWindows.length === 0
             ? `run grok${version ? `@${version}` : ''} once to refresh usage`
             : null;
         return {
@@ -2318,6 +2421,7 @@ async function getGrokUsageInfo(options) {
                 sourceLabel: 'last seen in Grok logs',
                 capturedAt: match.capturedAt,
                 windows,
+                staleWindows: staleWindows.length > 0 ? staleWindows : undefined,
                 plan: match.subscriptionTier,
                 refreshHint,
             },

package/dist/lib/agent-spec/agents.js

@@ -1513,15 +1513,30 @@ function credentialFileExistsUnder(agentId, home) {
     const alternatives = CREDENTIAL_FILE_SEGMENTS[agentId];
     if (!alternatives)
         return false;
-    for (const segments of alternatives) {
+    const hasSegment = alternatives.some((segments) => {
         const p = path.join(home, ...segments);
         try {
-            if (fs.existsSync(p))
-                return true;
+            return fs.existsSync(p);
         }
-        catch { /* unreadable */ }
-    }
-    return false;
+        catch {
+            return false;
+        }
+    });
+    if (!hasSegment)
+        return false;
+    // Claude's `.claude.json` is account METADATA Claude Code writes on any
+    // launch, not the credential itself — a version can carry stale identity
+    // there (e.g. install-time carry-forward) with no usable credential behind
+    // it: a failed OAuth refresh blanks `.credentials.json`, and a Linux worker
+    // can be missing BOTH `.credentials.json` and the `.oauth_token` setup-token
+    // file entirely (PHNX-3502). `credentialPresence` promises to mirror what a
+    // real launch would find, so it must fail whenever `isClaudeCredentialFileBlank`
+    // — the SAME floor `getAccountInfo` applies — would. On macOS that floor is a
+    // no-op (Keychain-only, always "not blank"), so this reduces to the identity
+    // check above, unchanged.
+    if (agentId === 'claude')
+        return !isClaudeCredentialFileBlank(home);
+    return true;
 }
 /**
  * File-presence probe for an agent's credential, split by location: whether it

package/dist/lib/claude-account-token.d.ts

@@ -22,3 +22,29 @@ export declare function readClaudeAccountEmail(home?: string): string | null;
  * authenticate with the shareable setup-token, not the ACL-bound login item.
  */
 export declare function resolveClaudeSetupToken(home?: string): string | null;
+/**
+ * Resolve a long-lived setup-token for an EXPLICIT account email, independent of
+ * any version home's `.claude.json`. This is what lets `agents accounts attach`
+ * provision a headless worker home that has never had an interactive login: the
+ * account's non-rotating setup-token is already fleet-synced in the file-based
+ * `auth` bundle, keyed by email ({@link claudeAccountTokenKey}), so we can write
+ * the home's `.oauth_token` from it without the circular
+ * "read the home's email to resolve the home's token" dependency that
+ * {@link resolveClaudeSetupToken} has. Same file-backed-only, fail-closed,
+ * fingerprint-stable read as the home-keyed path — it is the shared core.
+ *
+ * `cacheKey` scopes the process-local token cache; callers pass a version home
+ * so a home-keyed and email-keyed read of the same account share nothing stale.
+ */
+export declare function resolveClaudeSetupTokenForEmail(email: string, cacheKey?: string): string | null;
+/**
+ * Seed a keychain-less Linux worker's Claude version-home identity so an account's
+ * fleet-synced setup-token resolves for it. A worker home never had an interactive
+ * browser login, so its `.claude.json` carries no `oauthAccount.emailAddress` and
+ * the account reads "signed out" even though its non-rotating setup-token is present
+ * in the `auth` bundle. This writes ONLY the descriptive identity (the email), merged
+ * into both `.claude.json` locations Claude Code reads, preserving every other field.
+ * It never copies a rotating OAuth credential (`.credentials.json`) — the setup-token
+ * stays the credential of record.
+ */
+export declare function seedClaudeWorkerHomeIdentity(versionHome: string, email: string): void;

package/dist/lib/claude-account-token.js

@@ -76,12 +76,32 @@ export function readClaudeAccountEmail(home) {
  * authenticate with the shareable setup-token, not the ACL-bound login item.
  */
 export function resolveClaudeSetupToken(home) {
+    // Require a known account (email) up front: without it we cannot key a
+    // per-account token, and we must NOT fall back to a bare shared key that
+    // would misapply one account's setup-token to another.
+    const email = readClaudeAccountEmail(home);
+    if (!email)
+        return null;
+    return resolveClaudeSetupTokenForEmail(email, home ?? os.homedir());
+}
+/**
+ * Resolve a long-lived setup-token for an EXPLICIT account email, independent of
+ * any version home's `.claude.json`. This is what lets `agents accounts attach`
+ * provision a headless worker home that has never had an interactive login: the
+ * account's non-rotating setup-token is already fleet-synced in the file-based
+ * `auth` bundle, keyed by email ({@link claudeAccountTokenKey}), so we can write
+ * the home's `.oauth_token` from it without the circular
+ * "read the home's email to resolve the home's token" dependency that
+ * {@link resolveClaudeSetupToken} has. Same file-backed-only, fail-closed,
+ * fingerprint-stable read as the home-keyed path — it is the shared core.
+ *
+ * `cacheKey` scopes the process-local token cache; callers pass a version home
+ * so a home-keyed and email-keyed read of the same account share nothing stale.
+ */
+export function resolveClaudeSetupTokenForEmail(email, cacheKey) {
     try {
-        // Require a known account (email) up front: without it we cannot key a
-        // per-account token, and we must NOT fall back to a bare shared key that
-        // would misapply one account's setup-token to another.
-        const email = readClaudeAccountEmail(home);
-        if (!email)
+        const trimmed = email.trim();
+        if (!trimmed)
             return null;
         if (!bundleExists(AUTH_BUNDLE))
             return null;
@@ -92,25 +112,26 @@ export function resolveClaudeSetupToken(home) {
             // hint that the seeded setup-token was being ignored.
             throw new ReservedBundleWrongBackendError(AUTH_BUNDLE, backend);
         }
-        const cacheKey = home ?? os.homedir();
-        const item = secretsKeychainItem(AUTH_BUNDLE, claudeAccountTokenKey(email));
+        const key = claudeAccountTokenKey(trimmed);
+        const ck = cacheKey ?? `email:${trimmed}`;
+        const item = secretsKeychainItem(AUTH_BUNDLE, key);
         const credentialPath = fileStoreItemPath(item);
         for (let attempt = 0; attempt < 2; attempt++) {
             const before = credentialFingerprint(credentialPath);
-            const cached = setupTokenCache.get(cacheKey);
+            const cached = setupTokenCache.get(ck);
             if (cached?.credentialPath === credentialPath && cached.fingerprint === before) {
                 return cached.token;
             }
             if (before === 'missing') {
-                setupTokenCache.set(cacheKey, { credentialPath, fingerprint: before, token: null });
+                setupTokenCache.set(ck, { credentialPath, fingerprint: before, token: null });
                 return null;
             }
             const { env } = readAndResolveBundleEnv(AUTH_BUNDLE, { caller: 'usage', agentOnly: true });
-            const v = (env[claudeAccountTokenKey(email)] ?? '').trim();
+            const v = (env[key] ?? '').trim();
             const token = v.length > 0 && isValidClaudeSetupToken(v) ? v : null;
             const after = credentialFingerprint(credentialPath);
             if (before === after) {
-                setupTokenCache.set(cacheKey, { credentialPath, fingerprint: after, token });
+                setupTokenCache.set(ck, { credentialPath, fingerprint: after, token });
                 return token;
             }
         }
@@ -124,3 +145,36 @@ export function resolveClaudeSetupToken(home) {
         return null;
     }
 }
+/**
+ * Seed a keychain-less Linux worker's Claude version-home identity so an account's
+ * fleet-synced setup-token resolves for it. A worker home never had an interactive
+ * browser login, so its `.claude.json` carries no `oauthAccount.emailAddress` and
+ * the account reads "signed out" even though its non-rotating setup-token is present
+ * in the `auth` bundle. This writes ONLY the descriptive identity (the email), merged
+ * into both `.claude.json` locations Claude Code reads, preserving every other field.
+ * It never copies a rotating OAuth credential (`.credentials.json`) — the setup-token
+ * stays the credential of record.
+ */
+export function seedClaudeWorkerHomeIdentity(versionHome, email) {
+    const trimmed = email.trim();
+    if (!trimmed)
+        return;
+    for (const p of [
+        path.join(versionHome, '.claude', '.claude.json'),
+        path.join(versionHome, '.claude.json'),
+    ]) {
+        let doc = {};
+        try {
+            doc = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        }
+        catch {
+            // Missing or unreadable at this location — write a fresh minimal document.
+        }
+        const existing = (doc.oauthAccount && typeof doc.oauthAccount === 'object'
+            ? doc.oauthAccount
+            : {});
+        doc.oauthAccount = { ...existing, emailAddress: trimmed };
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(doc));
+    }
+}

package/dist/lib/daemon-ticks.js

@@ -114,17 +114,21 @@ export async function runFleetCacheWarmTick() {
  */
 export async function runUsageRefreshTick() {
     const { runUsageRefresh, buildLocalUsageAccounts } = await import('./usage-refresh.js');
-    const { writeClaudeUsageCache } = await import('./accounting/usage.js');
+    const { writeClaudeUsageCache, readClaudeUsageCache } = await import('./accounting/usage.js');
     const { usageRateLimitedUntil } = await import('./usage-backoff.js');
     const r = await runUsageRefresh({
         listAccounts: buildLocalUsageAccounts,
         writeUsageCache: writeClaudeUsageCache,
         backoffUntil: (agentId, usageKey) => usageRateLimitedUntil(agentId, Date.now(), usageKey),
+        // The free statusline ingest of a live `agents run` writes this same cache,
+        // so a recent capture means the account is already fresh at zero API cost —
+        // the refresher re-derives headroom from it and skips the API fetch.
+        readCachedSnapshot: (usageKey) => readClaudeUsageCache(usageKey),
     });
     const { listProfiles } = await import('./profiles.js');
     const { refreshDueByokUsage } = await import('./byok-usage.js');
     const byok = await refreshDueByokUsage(listProfiles());
-    console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped; BYOK ${byok.refreshed} refreshed, ${byok.skipped} not-due`);
+    console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped, ${r.skippedBudget} over-budget, ${r.skippedFresh} statusline-fresh; BYOK ${byok.refreshed} refreshed, ${byok.skipped} not-due`);
 }
 /**
  * Active-sessions warm (RUSH-2062 / RUSH-2484): publish THIS host's live session

package/dist/lib/event-families.js

@@ -36,7 +36,7 @@ export function parseFamilyList(raw, flagName) {
 /** Command-churn event kinds. */
 export const COMMAND_EVENT_TYPES = ['command.start', 'command.end'];
 /** Run-dispatch outcome kinds (replaces the separate audit/log.jsonl product). */
-export const RUN_EVENT_TYPES = ['run.dispatched', 'agent.run.end'];
+export const RUN_EVENT_TYPES = ['run.dispatched', 'run.launch', 'agent.run.end'];
 /**
  * Fold family include/exclude into a UnifiedQuery.
  * Precedence: family narrows sources/types; field filters (module, event, …)

package/dist/lib/exec.d.ts

@@ -1,4 +1,5 @@
-import type { AgentId, Mode } from './types.js';
+import type { AgentId, Mode, RunStrategy } from './types.js';
+import { type EventPayload } from './feed/events.js';
 import { type UsernsStatus } from './linux-userns.js';
 /**
  * Agent execution modes. Canonical name `skip` (dangerously skip permissions);
@@ -212,6 +213,31 @@ export interface ExecOptions {
      * session. Also forced off by AGENTS_NO_TMUX=1. No effect on headless runs.
      */
     raw?: boolean;
+    /**
+     * The run strategy that resolved this launch (pinned/available/balanced).
+     * Observability-only: threaded from the `agents run` command purely so the
+     * pre-launch `run.launch` event can record HOW the version was chosen. Never
+     * read by the spawn itself.
+     */
+    strategy?: RunStrategy;
+    /**
+     * How the launched version was resolved (e.g. 'pinned-default', 'rotated',
+     * 'explicit-pin'), when cheaply determinable. Observability-only, carried on
+     * `run.launch`. Optional — omitted when the caller can't attribute it.
+     */
+    resolvedVia?: string;
+    /**
+     * Precomputed launchable-signed-in verdict for the launched version, supplied
+     * by a caller that already computed it via the identical gate (a rotated pick
+     * carries `rotationResult.picked.signedIn`). When present, `run.launch` uses it
+     * instead of re-probing the version home — removing a double fs read on the hot
+     * path and any disagreement window. `undefined` means "not precomputed" (the
+     * pinned-default / shim paths), which makes `emitRunLaunch` fall back to
+     * {@link isVersionLaunchableHere}. Observability-only.
+     */
+    launchSignedIn?: boolean | null;
+    /** Precomputed account email companion to {@link launchSignedIn}. */
+    launchEmail?: string | null;
 }
 /**
  * Identity a custom-harness run stamps on env / pid-registry / sidecars.
@@ -550,6 +576,45 @@ export declare function writeTmuxEnvFile(env: NodeJS.ProcessEnv, filePath: strin
  * `[detached]` the pane-died hook otherwise leaves behind.
  */
 export declare function formatPaneTail(raw: string, maxLines?: number): string;
+/**
+ * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
+ *
+ * Stderr is always piped so the caller can inspect it (e.g., for rate-limit
+ * detection) while also forwarding every chunk to process.stderr in real time --
+ * the user sees the same output they would with stdio: 'inherit'. Stdout keeps
+ * the original behavior: 'pipe' when downstream output is piped (so `agents
+ * run ... | ...` composes cleanly), otherwise 'inherit' so TTY output is
+ * unbuffered.
+ */
+/** Inputs the pre-launch `run.launch` payload is built from. */
+export interface RunLaunchInput {
+    agent: AgentId;
+    harnessName?: string;
+    /** The version being launched, or undefined when none could be resolved. */
+    version?: string;
+    strategy?: RunStrategy;
+    /**
+     * Whether the launched version is launchable-signed-in on THIS device
+     * ({@link isVersionLaunchableHere}). `null` when the verdict is unknown — a
+     * missing verdict must NOT be read as logged out.
+     */
+    signedIn: boolean | null;
+    /** Account email of the version home when signed in, else null. */
+    email: string | null;
+    /** How the version was resolved (explicit-pin / rotated / pinned-default). */
+    resolvedVia?: string;
+}
+/**
+ * Build the `run.launch` event payload. Pure and exported so the signedIn ->
+ * launchedLoggedOut mapping is unit-testable without spawning. Mirrors the
+ * buildRotationDecisionEvent / emitRotationDecision split in rotate.ts.
+ *
+ * `launchedLoggedOut` is the headline flag — true ONLY when `signedIn` was
+ * resolved to false (a launch into a logged-out version, the yosemite-m3 2.1.219
+ * incident). An UNKNOWN verdict (`signedIn === null`) is never treated as
+ * logged out.
+ */
+export declare function buildRunLaunchPayload(input: RunLaunchInput): EventPayload;
 /** Exit code spawnAgent resolves with when a run is killed for crossing a budget cap. */
 export declare const BUDGET_KILL_EXIT_CODE = 7;
 /**