@phnx-labs/agents-cli 1.22.47 → 1.22.50

package/dist/lib/accounting/account-pool-collect.js

@@ -0,0 +1,71 @@
+import { readAccountRegistry } from '../account-registry.js';
+import { hasKeychainToken } from '../secrets/index.js';
+import { getGlobalDefault, listInstalledVersions } from '../installations/versions.js';
+import { collectRunCandidates } from './rotate.js';
+import { registryPoolCandidates } from './account-pool.js';
+/**
+ * Provider accounts whose credential is present on THIS device, as capability
+ * records. A registry entry with no local secret is skipped: including it would
+ * let `--strategy balanced` pick an account that then fails at spawn and exits the
+ * whole run (`resolveSpawnAccount` throws on a missing credential) instead of
+ * rotating to a healthy one.
+ */
+function localRegistryRecords() {
+    return Object.values(readAccountRegistry().accounts)
+        .filter((a) => hasKeychainToken(a.secretRef))
+        .map((a) => ({ name: a.name, provider: a.provider, auth: a.auth }));
+}
+/**
+ * PURE: fold provider-account candidates into the native version-home list.
+ *
+ * A registry account runs in `runVersion` (the agent's default installed home);
+ * the token/key overrides that home's own login at exec, so any home works. It
+ * carries `providerAccount` so the run path routes it through the existing
+ * `--account` injection (`resolveSpawnAccount` → `accountEnv`). An account already
+ * covered by a native login is skipped by accountKey. With no installed version
+ * there is nowhere to execute a registry account, so the native list passes
+ * through unchanged.
+ */
+export function foldRegistryCandidates(agent, inputs) {
+    const { native, records, runVersion } = inputs;
+    if (!runVersion)
+        return native;
+    const seen = new Set(native.filter((c) => c.accountKey).map((c) => c.accountKey));
+    const extra = registryPoolCandidates(records, agent)
+        .filter((r) => !seen.has(r.accountKey))
+        .map((r) => ({
+        agent,
+        version: runVersion,
+        accountKey: r.accountKey,
+        accountLabel: r.name,
+        email: null,
+        usageKey: null,
+        usageStatus: null,
+        usageSnapshot: null,
+        usageError: null,
+        usageMinutesToLimit: null,
+        plan: null,
+        signedIn: true,
+        authVerdict: null,
+        lastActive: null,
+        providerAccount: r.name,
+    }));
+    return [...native, ...extra];
+}
+/**
+ * Candidate list for the `agents run` strategy pick, account-centric: the usual
+ * native version-home candidates PLUS one candidate per provider account whose
+ * provider can authenticate `agent` and whose credential is present locally
+ * (RUSH-3182). This is what makes a setup-token / API-key account balance-eligible.
+ *
+ * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path
+ * ONLY — the other consumers of {@link collectRunCandidates} (watchdog, session
+ * recovery, teams placement) keep calling it directly and are unaffected. The
+ * existing {@link pickBalancedCandidate} selects over the combined list, so the
+ * revoked / rate-limit / exhausted logic is unchanged.
+ */
+export async function collectRunCandidatesForRun(agent) {
+    const native = await collectRunCandidates(agent);
+    const runVersion = getGlobalDefault(agent) ?? listInstalledVersions(agent)[0];
+    return foldRegistryCandidates(agent, { native, records: localRegistryRecords(), runVersion });
+}

package/dist/lib/accounting/account-pool.d.ts

@@ -0,0 +1,46 @@
+import type { AgentId } from '../types.js';
+import type { AccountAuthKind } from '../account-provider-registry.js';
+/**
+ * The provider-account side of the run-candidate pool (RUSH-3182).
+ *
+ * `--strategy balanced` used to enumerate only version-home native logins, so a
+ * setup-token / API-key account added via `agents accounts add` never balanced.
+ * This module turns the account registry into the extra candidates the run path
+ * folds in — see `collectRunCandidatesForRun` in `account-pool-collect.ts`.
+ *
+ * Pure + dependency-light so the harness-capability filter is unit-tested in
+ * isolation with fixtures.
+ */
+/** A provider account record as stored in the registry (identity captured separately). */
+export interface RegistryAccountRecord {
+    name: string;
+    provider: string;
+    auth: AccountAuthKind;
+}
+/** A registry account eligible to run one harness, ready to map to a candidate. */
+export interface RegistryAccountInput {
+    /** Agent-scoped key so `(claude, X)` and `(codex, X)` stay distinct. */
+    accountKey: string;
+    email: string | null;
+    name: string;
+    provider: string;
+    auth: AccountAuthKind;
+}
+/**
+ * Which provider accounts can authenticate `agent`. An account is a candidate for
+ * harness H only when its provider adapter has an `envFor(H, kind)` mapping
+ * (`providerAuthenticatesHarness`, the same check the account UI uses) — so a
+ * Cursor key never enters Claude's pool and a Claude setup-token never enters
+ * Codex's. This is registry-driven, no per-harness `else if`: a harness gets a
+ * provider-account pool exactly when the adapter table maps a provider to it —
+ * today claude, codex, grok, cursor, opencode (plus gemini/antigravity). A harness
+ * with only a native OAuth login and no provider adapter — kimi — returns `[]`
+ * here and keeps balancing its native logins only.
+ *
+ * `accountKey` is synthetic here (`${agent}:name=${name}`) — a stable per-account
+ * key so balancing can include it immediately; the real agent-scoped identity
+ * (email / org uuid) is backfilled by identity capture and replaces it. `email`
+ * is null until then, which routes the account as usage-unverified but still a
+ * candidate, never excluded.
+ */
+export declare function registryPoolCandidates(records: RegistryAccountRecord[], agent: AgentId): RegistryAccountInput[];

package/dist/lib/accounting/account-pool.js

@@ -0,0 +1,33 @@
+import { providerAuthenticatesHarness } from '../account-provider-registry.js';
+/**
+ * Which provider accounts can authenticate `agent`. An account is a candidate for
+ * harness H only when its provider adapter has an `envFor(H, kind)` mapping
+ * (`providerAuthenticatesHarness`, the same check the account UI uses) — so a
+ * Cursor key never enters Claude's pool and a Claude setup-token never enters
+ * Codex's. This is registry-driven, no per-harness `else if`: a harness gets a
+ * provider-account pool exactly when the adapter table maps a provider to it —
+ * today claude, codex, grok, cursor, opencode (plus gemini/antigravity). A harness
+ * with only a native OAuth login and no provider adapter — kimi — returns `[]`
+ * here and keeps balancing its native logins only.
+ *
+ * `accountKey` is synthetic here (`${agent}:name=${name}`) — a stable per-account
+ * key so balancing can include it immediately; the real agent-scoped identity
+ * (email / org uuid) is backfilled by identity capture and replaces it. `email`
+ * is null until then, which routes the account as usage-unverified but still a
+ * candidate, never excluded.
+ */
+export function registryPoolCandidates(records, agent) {
+    const out = [];
+    for (const r of records) {
+        if (!providerAuthenticatesHarness(r.provider, r.auth, agent))
+            continue;
+        out.push({
+            accountKey: `${agent}:name=${r.name}`,
+            email: null,
+            name: r.name,
+            provider: r.provider,
+            auth: r.auth,
+        });
+    }
+    return out;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Remaining-capacity weighting for account selection — a pure, dependency-free
+ * primitive shared by the version-home router (`rotate.ts`) and the account pool
+ * (`account-pool.ts`). Kept in its own module so either can import it without
+ * dragging in the heavy usage/secrets graph.
+ */
+/**
+ * How far from its projected cap an account must be to keep its FULL headroom
+ * weight. Inside this horizon the weight is scaled down linearly toward the
+ * floor, so an account racing toward its 5h cap loses priority before it maxes.
+ */
+export declare const PROJECTION_HORIZON_MIN = 30;
+/**
+ * Weight one candidate by remaining routing capacity, deprioritized by how soon
+ * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
+ * an account with no live snapshot is treated as full-capacity (100) since there
+ * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
+ * projection on the 5h session window) then scales that base: >= horizon (or
+ * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
+ * so a launch avoids an account projected to cap soon, not just a 100%-maxed
+ * one. Pure + exported so the deprioritization is unit-tested directly (a
+ * weighted-random draw is not).
+ */
+export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;

package/dist/lib/accounting/capacity.js

@@ -0,0 +1,30 @@
+/**
+ * Remaining-capacity weighting for account selection — a pure, dependency-free
+ * primitive shared by the version-home router (`rotate.ts`) and the account pool
+ * (`account-pool.ts`). Kept in its own module so either can import it without
+ * dragging in the heavy usage/secrets graph.
+ */
+/**
+ * How far from its projected cap an account must be to keep its FULL headroom
+ * weight. Inside this horizon the weight is scaled down linearly toward the
+ * floor, so an account racing toward its 5h cap loses priority before it maxes.
+ */
+export const PROJECTION_HORIZON_MIN = 30;
+/**
+ * Weight one candidate by remaining routing capacity, deprioritized by how soon
+ * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
+ * an account with no live snapshot is treated as full-capacity (100) since there
+ * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
+ * projection on the 5h session window) then scales that base: >= horizon (or
+ * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
+ * so a launch avoids an account projected to cap soon, not just a 100%-maxed
+ * one. Pure + exported so the deprioritization is unit-tested directly (a
+ * weighted-random draw is not).
+ */
+export function capacityWeight(usedPercent, minutesToLimit) {
+    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
+    if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
+        return base;
+    const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));
+    return Math.max(1, base * factor);
+}

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

@@ -6,6 +6,7 @@
  */
 import type { AgentId, RunStrategy } from '../types.js';
 import type { FallbackEntry } from '../exec.js';
+import { PROJECTION_HORIZON_MIN, capacityWeight } from './capacity.js';
 import { type AccountInfo, type CredentialPresence } from '../agents.js';
 import { type UsageSnapshot } from './usage.js';
 import { type AuthVerdict } from '../auth-health.js';
@@ -49,6 +50,15 @@ export interface RotateCandidate {
      */
     authVerdict: AuthVerdict | null;
     lastActive: Date | null;
+    /**
+     * Set only for a candidate that comes from a provider account bundle rather
+     * than a native version-home login (RUSH-3182): the account name to inject via
+     * the `--account` spawn path (`resolveSpawnAccount` → `accountEnv`). Undefined
+     * for a native login, whose credential already lives in `version`'s home. The
+     * run path routes on this so a balanced pick of a setup-token / API-key account
+     * authenticates through the existing provider-account injection.
+     */
+    providerAccount?: string;
 }
 export interface RotateResult {
     /** The version picked for this run. */
@@ -212,24 +222,7 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  * version so behavior stays predictable.
  */
 export declare function pickBalancedCandidate(candidates: RotateCandidate[], nowMs?: number): RotateResult | null;
-/**
- * How far from its projected cap an account must be to keep its FULL headroom
- * weight. Inside this horizon the weight is scaled down linearly toward the
- * floor, so an account racing toward its 5h cap loses priority before it maxes.
- */
-export declare const PROJECTION_HORIZON_MIN = 30;
-/**
- * Weight one candidate by remaining routing capacity, deprioritized by how soon
- * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
- */
-export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;
+export { PROJECTION_HORIZON_MIN, capacityWeight };
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most

package/dist/lib/accounting/rotate.js

@@ -6,6 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { PROJECTION_HORIZON_MIN, capacityWeight } from './capacity.js';
 import { accountDisplayLabel, getAccountInfo, credentialPresence, ALL_AGENT_IDS, } from '../agents.js';
 import { readMeta, writeMeta, getHelpersDir } from '../state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from '../installations/versions.js';
@@ -365,30 +366,11 @@ function preferVerified(pool, nowMs, choose, narrowing = 'any-verified') {
         usageUnverified: !isUsageVerified(picked, nowMs),
     };
 }
-/**
- * How far from its projected cap an account must be to keep its FULL headroom
- * weight. Inside this horizon the weight is scaled down linearly toward the
- * floor, so an account racing toward its 5h cap loses priority before it maxes.
- */
-export const PROJECTION_HORIZON_MIN = 30;
-/**
- * Weight one candidate by remaining routing capacity, deprioritized by how soon
- * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
- * an account with no live snapshot is treated as full-capacity (100) since there
- * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
- * projection on the 5h session window) then scales that base: >= horizon (or
- * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
- * so a launch avoids an account projected to cap soon, not just a 100%-maxed
- * one. Pure + exported so the deprioritization is unit-tested directly (a
- * weighted-random draw is not).
- */
-export function capacityWeight(usedPercent, minutesToLimit) {
-    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
-    if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
-        return base;
-    const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));
-    return Math.max(1, base * factor);
-}
+// capacityWeight + PROJECTION_HORIZON_MIN moved to ./capacity.js (a pure,
+// dependency-free module the account pool can import without this file's heavy
+// graph). Imported at the top for internal use; re-exported here so existing
+// importers keep resolving them from rotate.
+export { PROJECTION_HORIZON_MIN, capacityWeight };
 /**
  * Pick one candidate from `sorted` using weights proportional to remaining
  * routing capacity (see {@link capacityWeight}). Floor each weight at 1 so a

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

@@ -125,6 +125,8 @@ export interface UsageSnapshot {
     capturedAt: Date | null;
     windows: UsageWindow[];
     plan?: string | null;
+    /** Action that makes an event-fed source emit a current reading. */
+    refreshHint?: string | null;
     /**
      * A refusal observed from a real harness run, independent of API windows.
      * `session_limit` recovers on a clock (`resetsAt`). `out_of_credits` is a
@@ -306,6 +308,11 @@ export interface FormatUsageSummaryOpts {
      * column width; single-agent and detail views leave this unset.
      */
     maxWindows?: number;
+    /** Windows that must keep a visible slot even when the provider omits one. */
+    expectedWindows?: Array<{
+        key: string;
+        shortLabel: string;
+    }>;
     /**
      * The classified cause of `usageInfo.error` (RUSH-3040), from
      * {@link classifyUsageErrorKind}. Lets the no-bars branch below name the
@@ -326,6 +333,8 @@ export interface FormatUsageSummaryOpts {
     errorDetail?: string | null;
     /** Benign state from {@link getUsageBenignState}; never sourced from `UsageInfo.error`. */
     benignState?: UsageBenignState | null;
+    /** Provider-specific replacement for the generic no-local-event marker. */
+    noRecentUsageLabel?: string | null;
 }
 /** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number, opts?: FormatUsageSummaryOpts): string;
@@ -552,7 +561,7 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * a file-based setup-token and, when none is provisioned, gets `null` — it never
  * reads Claude Code's interactive login (transmitting that ACL-bound OAuth token
  * to Anthropic's API is what gets it revoked; see the branch body and
- * docs/credential-management.md). It is OFF by default so full-credential
+ * docs/secrets.md). It is OFF by default so full-credential
  * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) still
  * read the interactive login. Rush Cloud dispatch does not call this helper
  * at all (SING-1b: the account manifest is email-only; RUSH-2359 removed the
@@ -588,6 +597,8 @@ export declare function readClaudeUsageCache(usageKey: string, cachePath?: strin
 export declare function pruneExpiredClaudeUsageCacheEntry(usageKey: string, cachePath?: string, now?: Date): void;
 /** Write a usage snapshot to the on-disk cache. */
 export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
+/** Atomically merge partial native Claude windows into the current fresh row. */
+export declare function mergeClaudeUsageCacheWindows(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
 /**
  * Persist a Claude tokens/credits exhaustion (`out of usage credits` / `monthly
  * spend limit`) from a real run. Unlike a rate/session limit this does NOT reset
@@ -614,8 +625,8 @@ export declare function parseClaudeSessionLimitReset(text: string, nowMs?: numbe
  * Returns true only when a valid access token can be obtained.
  */
 export declare function isClaudeAuthValid(home?: string): Promise<boolean>;
-/** Render a colored block-character progress bar. */
-export declare function renderBar(usedPercent: number, length: number, minimumVisible?: number): string;
+/** Render a proportional colored progress bar at one-eighth-cell resolution. */
+export declare function renderBar(usedPercent: number, length: number): string;
 /** Return a chalk color function based on the usage percentage threshold. */
 export declare function getUsageColor(usedPercent: number): (text: string) => string;
 /** Parse the latest billing info from Grok's unified log. */

package/dist/lib/accounting/usage.js

@@ -26,6 +26,7 @@ import { getCacheDir } from '../state.js';
 import { mapBounded } from '../concurrency.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from '../fs-atomic.js';
 import { withRefreshLease } from '../refresh-coordinator.js';
+import { padToWidth } from '../session/width.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -216,6 +217,7 @@ const COMPACT_BAR_LEN = 5;
 const USAGE_BAR_LEN = 10;
 const FULL = '\u2588';
 const EMPTY = '\u2591';
+const PARTIAL_BLOCKS = ['', '\u258F', '\u258E', '\u258D', '\u258C', '\u258B', '\u258A', '\u2589'];
 /** Construct the benign no-local-log result without overloading `error`. */
 export function usageNoRecentUsageInfo() {
     return { snapshot: null, error: null, [USAGE_BENIGN_STATE]: 'no-recent-usage' };
@@ -498,11 +500,20 @@ 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);
-        const windowParts = selected.map((window) => {
+        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) => {
+            if (!window) {
+                const missing = chalk.red(`${shortLabel}: ${FULL.repeat(COMPACT_BAR_LEN)} unavailable`);
+                return index < windowsToRender.length - 1 ? padToWidth(missing, 20) : missing;
+            }
             const bar = renderCompactUsageBar(window.usedPercent);
             const pct = colorUsage(`${Math.round(window.usedPercent)}%`, window.usedPercent);
             const reset = window.resetsAt ? chalk.dim(` (${formatResetHint(window.resetsAt)})`) : '';
-            return `${chalk.gray(`${window.shortLabel}:`)} ${bar} ${pct}${reset}`;
+            const rendered = `${chalk.gray(`${shortLabel}:`)} ${bar} ${pct}${reset}`;
+            return index < windowsToRender.length - 1 ? padToWidth(rendered, 20) : rendered;
         });
         if (hidden > 0) {
             windowParts.push(chalk.dim(`+${hidden}`));
@@ -510,6 +521,9 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         if (windowParts.length > 0) {
             parts.push(windowParts.join('  '));
         }
+        else if (snapshot.refreshHint) {
+            parts.push(chalk.dim(snapshot.refreshHint));
+        }
         // The bars came from the cache and the live read that should have confirmed
         // them failed, so they are the last thing we saw — not the current state.
         // Drawing them unmarked is what let a 26h-old "48% used" read as fact.
@@ -528,7 +542,7 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         parts.push(chalk.dim(USAGE_HEADLESS_SCOPE_MARKER));
     }
     else if (opts?.benignState === 'no-recent-usage') {
-        parts.push(chalk.dim(USAGE_NO_RECENT_USAGE_MARKER));
+        parts.push(chalk.dim(opts.noRecentUsageLabel || USAGE_NO_RECENT_USAGE_MARKER));
     }
     else if (opts?.unavailable) {
         // Signed-in account we could NOT fetch usage for (no live token in a reachable
@@ -1410,7 +1424,7 @@ function deleteCachedClaudeOauth(service) {
  * a file-based setup-token and, when none is provisioned, gets `null` — it never
  * reads Claude Code's interactive login (transmitting that ACL-bound OAuth token
  * to Anthropic's API is what gets it revoked; see the branch body and
- * docs/credential-management.md). It is OFF by default so full-credential
+ * docs/secrets.md). It is OFF by default so full-credential
  * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) still
  * read the interactive login. Rush Cloud dispatch does not call this helper
  * at all (SING-1b: the account manifest is email-only; RUSH-2359 removed the
@@ -1443,7 +1457,7 @@ export async function loadClaudeOauth(home, opts) {
         // interactive credential used programmatically, which Anthropic flags and
         // revokes (the fleet-wide-logout class, RUSH-1822), and which violates the
         // invariant that the interactive/rotating login is untouchable
-        // (docs/credential-management.md). Report unprovisioned (-> probe
+        // (docs/secrets.md). Report unprovisioned (-> probe
         // token 'missing' -> auth-health 'unconfigured', benign for rotation); seed a
         // setup-token via the mint-auth path to restore usage/probe for the account.
         return null;
@@ -1604,6 +1618,32 @@ export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeU
         /* best-effort cache write — lock busy or disk full */
     }
 }
+/** Atomically merge partial native Claude windows into the current fresh row. */
+export function mergeClaudeUsageCacheWindows(usageKey, snapshot, cachePath = getClaudeUsageCachePath()) {
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const prior = cache[usageKey];
+            const priorSnapshot = prior
+                ? deserializeClaudeUsageSnapshot(prior, snapshot.capturedAt ?? new Date())
+                : null;
+            const windows = new Map(priorSnapshot?.windows.map((window) => [window.key, window]) ?? []);
+            for (const window of snapshot.windows)
+                windows.set(window.key, window);
+            cache[usageKey] = serializeClaudeUsageSnapshot({
+                ...snapshot,
+                windows: [...windows.values()],
+                plan: snapshot.plan ?? priorSnapshot?.plan ?? null,
+                unavailable: carryForwardUnavailable(prior?.unavailable, snapshot.unavailable),
+            });
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
+}
 /** Read the entire usage cache file from disk. */
 function readClaudeUsageCacheFile(cachePath) {
     if (!fs.existsSync(cachePath)) {
@@ -1632,6 +1672,7 @@ function serializeClaudeUsageSnapshot(snapshot) {
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
         plan: snapshot.plan ?? null,
+        refreshHint: snapshot.refreshHint ?? null,
         unavailable: snapshot.unavailable
             ? {
                 reason: snapshot.unavailable.reason,
@@ -1686,7 +1727,7 @@ 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) {
+    if (windows.length === 0 && !unavailable && !snapshot.plan && !snapshot.refreshHint) {
         return null;
     }
     return {
@@ -1695,6 +1736,7 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         capturedAt,
         windows,
         plan: snapshot.plan ?? null,
+        refreshHint: snapshot.refreshHint ?? null,
         unavailable,
     };
 }
@@ -1973,14 +2015,17 @@ function renderUsageBar(usedPercent) {
 }
 /** Render a compact usage bar for inline summaries. */
 function renderCompactUsageBar(usedPercent) {
-    return renderBar(usedPercent, COMPACT_BAR_LEN, usedPercent > 0 ? 1 : 0);
-}
-/** Render a colored block-character progress bar. */
-export function renderBar(usedPercent, length, minimumVisible = 0) {
-    const rounded = Math.round((usedPercent / 100) * length);
-    const filled = Math.max(minimumVisible, Math.max(0, Math.min(length, rounded)));
+    return renderBar(usedPercent, COMPACT_BAR_LEN);
+}
+/** Render a proportional colored progress bar at one-eighth-cell resolution. */
+export function renderBar(usedPercent, length) {
+    const clamped = Math.max(0, Math.min(100, usedPercent));
+    const eighths = Math.round((clamped / 100) * length * 8);
+    const filled = Math.floor(eighths / 8);
+    const partial = eighths % 8;
     const color = getUsageColor(usedPercent);
-    return color(FULL.repeat(filled)) + chalk.dim(EMPTY.repeat(length - filled));
+    const gauge = FULL.repeat(filled) + PARTIAL_BLOCKS[partial];
+    return color(gauge) + chalk.dim(EMPTY.repeat(length - filled - (partial > 0 ? 1 : 0)));
 }
 /** Apply the appropriate color to a text string based on usage percentage. */
 function colorUsage(text, usedPercent) {
@@ -2080,10 +2125,10 @@ async function getGrokUsageInfo(options) {
         // (see readLatestGrokBilling).
         const now = new Date();
         const windows = match.windows.filter((window) => isCachedUsageWindowFresh(window, match.capturedAt, now));
-        // NOTE: an empty `windows` here (all windows expired) still returns a real
-        // snapshot, not the no-recent-usage marker — the plan/tier is still valid
-        // and callers (e.g. `formatUsageSummary`) render "no bars" correctly from
-        // an empty array. The marker above is only for "nothing was ever recorded".
+        const version = options?.cliVersion;
+        const refreshHint = windows.length === 0
+            ? `run grok${version ? `@${version}` : ''} once to refresh usage`
+            : null;
         return {
             snapshot: {
                 source: 'last_seen',
@@ -2091,6 +2136,7 @@ async function getGrokUsageInfo(options) {
                 capturedAt: match.capturedAt,
                 windows,
                 plan: match.subscriptionTier,
+                refreshHint,
             },
             error: null,
         };
@@ -2483,7 +2529,7 @@ export function normalizeCursorUsageSummary(data) {
 function readCursorCredentials(base) {
     try {
         const cfgPath = path.join(base, '.cursor', 'cli-config.json');
-        const authPath = path.join(base, '.config', 'cursor', 'auth.json');
+        const authPath = path.join(base, '.cursor', 'auth.json');
         if (!fs.existsSync(cfgPath) || !fs.existsSync(authPath))
             return null;
         const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));

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

@@ -1504,12 +1504,9 @@ const CREDENTIAL_FILE_SEGMENTS = {
     // Muse Code stores OAuth / API credentials at ~/.config/muse/auth.json
     // (or META_API_KEY in the environment, which is not a file).
     muse: [['.config', 'muse', 'auth.json']],
-    // Cursor's OAuth token — the login gate — is at $XDG_CONFIG_HOME/cursor/auth.json
-    // (~/.config/cursor/auth.json by default). cli-config.json holds only account
-    // metadata; the token file is what a real launch authenticates from, so a
-    // version home with no token of its own is genuinely logged out once runs pin
-    // XDG_CONFIG_HOME per home (see buildExecEnv).
-    cursor: [['.config', 'cursor', 'auth.json']],
+    // With AGENT_CLI_CREDENTIAL_STORE=file, Cursor stores both OAuth tokens at
+    // ~/.cursor/auth.json. cli-config.json holds account metadata only.
+    cursor: [['.cursor', 'auth.json']],
 };
 /** Whether an agent's credential file exists under a given home. */
 function credentialFileExistsUnder(agentId, home) {
@@ -2112,7 +2109,7 @@ export async function getAccountInfo(agentId, home) {
             case 'cursor': {
                 // Cursor CLI keeps account metadata in ~/.cursor/cli-config.json
                 // (authInfo: { email, userId, authId }) and its OAuth tokens SEPARATELY
-                // in ~/.config/cursor/auth.json ({ accessToken, refreshToken }). Presence
+                // in ~/.cursor/auth.json ({ accessToken, refreshToken }). Presence
                 // of an access token is the signed-in signal; email/ids come from
                 // cli-config. authId is the OAuth subject (e.g. "google-oauth2|<n>") — the
                 // same value the usage endpoint keys on (see getCursorUsageInfo).
@@ -2126,7 +2123,7 @@ export async function getAccountInfo(agentId, home) {
                     const accountId = normalizeIdentityPart(authInfo?.authId ?? authInfo?.userId);
                     if (!email && !accountId)
                         return { ...empty, lastActive };
-                    const authPath = resolveAccountCredentialPath(base, '.config', 'cursor', 'auth.json');
+                    const authPath = resolveAccountCredentialPath(base, '.cursor', 'auth.json');
                     let hasToken = false;
                     if (authPath) {
                         try {
@@ -2135,8 +2132,13 @@ export async function getAccountInfo(agentId, home) {
                         }
                         catch { /* unreadable token file */ }
                     }
+                    // cli-config survives logout and may describe a different keychain
+                    // account. Without this version's file token, its identity is stale
+                    // metadata rather than a usable managed login.
+                    if (!hasToken)
+                        return { ...empty, lastActive };
                     const accountKey = buildIdentityKey(agentId, [['user', accountId]]);
-                    return { ...empty, email, accountId, accountKey, signedIn: hasToken || !!email, lastActive };
+                    return { ...empty, email, accountId, accountKey, signedIn: true, lastActive };
                 }
                 catch { }
                 return { ...empty, lastActive };

package/dist/lib/browser/drivers/ssh.d.ts

@@ -16,13 +16,27 @@ export interface SSHConnection {
  * strings differ (no `&` backgrounding, no `lsof`, `.exe` instead of `.app`).
  */
 export type RemoteOs = 'windows' | 'posix';
+export interface SSHConnectOptions {
+    /**
+     * Attach to a browser another device already declared (identity-bearing or
+     * a fungible name we don't declare here). Do not launch a fresh remote
+     * chrome-data, and do not kill that browser when the tunnel closes — it
+     * holds the logins the caller is trying to reach.
+     */
+    persistRemote?: boolean;
+}
+/** Lifecycle for a registry-driven tunnel vs a profile the daemon launched. */
+export declare function persistRemoteLifecycle(persistRemote: boolean): {
+    launchRemote: boolean;
+    killOnCleanup: boolean;
+};
 export declare function connectSSH(endpoint: string, profile: BrowserProfile, 
 /**
- * Runtime key (`<profile>@<endpoint>`) this connection is stored under. It
+ * Runtime key (`<profile>@<device>`) this connection is stored under. It
  * keys the tunnel's runtime record; `profile.name` is the bare, user-facing
  * name and appears only in messages (RUSH-2709).
  */
-key: ConnectionKey): Promise<SSHConnection>;
+key: ConnectionKey, opts?: SSHConnectOptions): Promise<SSHConnection>;
 /**
  * Wrap a PowerShell script as a `-EncodedCommand` invocation. Base64 of the
  * UTF-16LE bytes is a single quote-free token, so it rides through Node spawn