dsh-plugin-subscription-usage 0.0.0-stage → 0.1.0

package/lib/providers/pool-usage.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Quota tracking for pool members: polls the providers' usage endpoints
+ * (the same normalized `ProviderUsage` shape the Settings page consumes) and
+ * turns the windows into a scheduling score.
+ *
+ * The score is a REQUIRED BURN RATE: the fraction of the window that must be
+ * consumed per millisecond for the quota to be exactly used up at reset time
+ * (`remaining / timeUntilReset`). Subscription quota does not roll over, so a
+ * window about to reset with plenty left is the most urgent to spend — the
+ * `quota_aware` strategy therefore prefers the highest-urgency member, which
+ * over time converges on every window hitting zero right at its reset.
+ */
+import type { ProviderUsage, UsageWindow } from './common.js';
+import type { UsageProviderId } from '../usage-providers/index.js';
+import type { ConcretePoolMember } from './pool-family.js';
+/** Near-full members are tried only after members below this fill level. */
+export declare const QUOTA_FULL_PERCENT = 95;
+/** Exhausted subscription windows must not silently spill over into paid credits. */
+export declare const QUOTA_EXHAUSTED_PERCENT = 100;
+/** How long a usage snapshot is trusted before a background refresh. */
+export declare const USAGE_TTL_MS: number;
+/** The scheduling view of one member's quota. */
+export interface MemberQuota {
+    /** False when a window is near-full or the login is gone. */
+    available: boolean;
+    /** A known exhausted window: exclude even if the upstream would accept paid credits. */
+    exhausted?: true;
+    /** Burn rate in strategy-specific units; 0 when unmeasured. */
+    urgency: number;
+    /** Epoch ms of the snapshot this was computed from; 0 when none. */
+    fetchedAt: number;
+}
+/**
+ * Per-ACCOUNT usage snapshots with in-flight dedupe and
+ * stale-while-revalidate refresh. Providers without a usage endpoint
+ * (copilot) resolve no fetcher and score a constant zero urgency — which
+ * naturally ranks them behind every measured member. Fetchers are resolved
+ * lazily per (provider, account) so accounts added after startup join
+ * tracking on their first score.
+ */
+export declare class PoolUsageTracker {
+    private readonly fetcherFor;
+    private readonly ttlMs;
+    private readonly entries;
+    private readonly inflight;
+    constructor(fetcherFor: (provider: UsageProviderId, account: string) => (() => Promise<ProviderUsage>) | undefined, ttlMs?: number);
+    /**
+     * The quota view of one member. A cold cache awaits the first fetch; a
+     * stale non-exhausted snapshot answers immediately while refreshing in the
+     * background. Exhausted snapshots await their expired-cache refresh so a
+     * reset can restore routing on this call. A live failure cooldown never
+     * triggers another fetch.
+     *
+     * Failures discard stale urgency but preserve known exhaustion: an outage
+     * must not turn a blocked subscription into permission to spend credits.
+     * Only a successful usage lookup (or explicit invalidation) clears it.
+     * @param member - the pool member to score (account resolved).
+     * @returns availability plus the urgency score.
+     */
+    quotaFor(member: ConcretePoolMember, normalized?: boolean): Promise<MemberQuota>;
+    /** Keep a known credit-spending risk blocked through usage-endpoint failures. */
+    private failedQuota;
+    /**
+     * Same cache as {@link quotaFor}, for direct display (the Settings page):
+     * the raw snapshot, or the original fetch error, instead of a routing
+     * score.
+     * @param provider - the account's provider.
+     * @param account - the account key.
+     * @param force - bypass a fresh cached SNAPSHOT for an honest re-check (the
+     *   manual Refresh button). A live failure cooldown is never bypassed —
+     *   retrying through it is exactly what turns a 429 into a permanent
+     *   lockout, so even a forced call still answers from the negative cache.
+     * @returns `{ supported: false }` when the provider has no usage fetcher.
+     */
+    snapshotFor(provider: UsageProviderId, account: string, force?: boolean): Promise<ProviderUsage>;
+    /** Decorate a copy for UI consumers; raw snapshots and routing stay unchanged. */
+    displaySnapshotFor(provider: UsageProviderId, account: string, force?: boolean): Promise<ProviderUsage>;
+    /**
+     * Record windows read from a model reply as a fresh snapshot. Windows the
+     * reply carries replace same-kind unscoped windows; the endpoint's other
+     * windows (model-scoped lanes, plan, reset credits) stay as they were.
+     * A live failure cooldown is left in place: it guards the usage endpoint,
+     * which this did not call.
+     * @returns the merged snapshot, or undefined when nothing was recorded.
+     */
+    ingest(provider: UsageProviderId, account: string, windows: readonly UsageWindow[], at?: number): ProviderUsage | undefined;
+    /** Epoch ms of the account's last successful snapshot, live or fetched. */
+    fetchedAt(provider: UsageProviderId, account: string): number | undefined;
+    /** Recheck after an inference quota failure without erasing another model lane's exhaustion. */
+    expire(provider: UsageProviderId, account: string): void;
+    /** Drop cached snapshots: one account, or a whole provider when `account` is omitted. */
+    invalidate(provider: UsageProviderId, account?: string): void;
+    /**
+     * Run (or join) the single in-flight fetch for one account key, caching
+     * either outcome. A missing/invalid credential is deliberately NOT
+     * negative-cached: it costs no network round trip (the session lookup
+     * fails before the request goes out) and re-checking live means the
+     * member rejoins routing the instant its login is fixed, rather than
+     * waiting out a stale cooldown.
+     */
+    private refresh;
+    /** Score one member against a snapshot's windows. */
+    private score;
+}
+/** Dimensionless urgency for the opt-in strategy. Missing timing adds no reset bonus. */
+export declare function normalizedWindowUrgency(window: UsageWindow, now: number): number;

package/lib/providers/pool-usage.js

@@ -0,0 +1,302 @@
+/**
+ * Quota tracking for pool members: polls the providers' usage endpoints
+ * (the same normalized `ProviderUsage` shape the Settings page consumes) and
+ * turns the windows into a scheduling score.
+ *
+ * The score is a REQUIRED BURN RATE: the fraction of the window that must be
+ * consumed per millisecond for the quota to be exactly used up at reset time
+ * (`remaining / timeUntilReset`). Subscription quota does not roll over, so a
+ * window about to reset with plenty left is the most urgent to spend — the
+ * `quota_aware` strategy therefore prefers the highest-urgency member, which
+ * over time converges on every window hitting zero right at its reset.
+ */
+import { isMissingOrInvalidCredential, OAuthEndpointError } from './common.js';
+/** Near-full members are tried only after members below this fill level. */
+export const QUOTA_FULL_PERCENT = 95;
+/** Exhausted subscription windows must not silently spill over into paid credits. */
+export const QUOTA_EXHAUSTED_PERCENT = 100;
+/** How long a usage snapshot is trusted before a background refresh. */
+export const USAGE_TTL_MS = 5 * 60_000;
+/** Assumed window length when the provider discloses no `resetsAt`. */
+const FALLBACK_HORIZON_MS = {
+    session: 5 * 60 * 60_000,
+    weekly: 7 * 24 * 60 * 60_000,
+    other: 30 * 24 * 60 * 60_000,
+};
+/**
+ * Per-ACCOUNT usage snapshots with in-flight dedupe and
+ * stale-while-revalidate refresh. Providers without a usage endpoint
+ * (copilot) resolve no fetcher and score a constant zero urgency — which
+ * naturally ranks them behind every measured member. Fetchers are resolved
+ * lazily per (provider, account) so accounts added after startup join
+ * tracking on their first score.
+ */
+export class PoolUsageTracker {
+    fetcherFor;
+    ttlMs;
+    entries = new Map();
+    inflight = new Map();
+    constructor(fetcherFor, ttlMs = USAGE_TTL_MS) {
+        this.fetcherFor = fetcherFor;
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * The quota view of one member. A cold cache awaits the first fetch; a
+     * stale non-exhausted snapshot answers immediately while refreshing in the
+     * background. Exhausted snapshots await their expired-cache refresh so a
+     * reset can restore routing on this call. A live failure cooldown never
+     * triggers another fetch.
+     *
+     * Failures discard stale urgency but preserve known exhaustion: an outage
+     * must not turn a blocked subscription into permission to spend credits.
+     * Only a successful usage lookup (or explicit invalidation) clears it.
+     * @param member - the pool member to score (account resolved).
+     * @returns availability plus the urgency score.
+     */
+    async quotaFor(member, normalized = false) {
+        const key = `${member.provider}/${member.account}`;
+        const fetcher = this.fetcherFor(member.provider, member.account);
+        if (fetcher === undefined)
+            return { available: true, urgency: 0, fetchedAt: 0 };
+        const entry = this.entries.get(key);
+        if (entry !== undefined) {
+            const fresh = Date.now() - entry.at < (entry.cooldownMs ?? this.ttlMs);
+            if (entry.snapshot !== undefined) {
+                const quota = this.score(member, entry, normalized);
+                if (fresh)
+                    return quota;
+                if (!quota.exhausted && entry.at !== Number.NEGATIVE_INFINITY) {
+                    void this.refresh(key, fetcher).catch(() => undefined);
+                    return quota;
+                }
+                // A reset may have restored the subscription since the last lookup.
+            }
+            else if (fresh) {
+                return this.failedQuota(member, entry.error, entry.lastSnapshot);
+            }
+            // The cooldown expired: fall through to a fresh, blocking attempt.
+        }
+        try {
+            const snapshot = await this.refresh(key, fetcher);
+            return this.score(member, { snapshot, at: Date.now() }, normalized);
+        }
+        catch (error) {
+            return this.failedQuota(member, error, entry?.snapshot ?? entry?.lastSnapshot);
+        }
+    }
+    /** Keep a known credit-spending risk blocked through usage-endpoint failures. */
+    failedQuota(member, error, snapshot) {
+        const degraded = degradedQuota(error);
+        if (snapshot !== undefined && this.score(member, { snapshot, at: 0 }).exhausted) {
+            return { ...degraded, available: false, exhausted: true };
+        }
+        return degraded;
+    }
+    /**
+     * Same cache as {@link quotaFor}, for direct display (the Settings page):
+     * the raw snapshot, or the original fetch error, instead of a routing
+     * score.
+     * @param provider - the account's provider.
+     * @param account - the account key.
+     * @param force - bypass a fresh cached SNAPSHOT for an honest re-check (the
+     *   manual Refresh button). A live failure cooldown is never bypassed —
+     *   retrying through it is exactly what turns a 429 into a permanent
+     *   lockout, so even a forced call still answers from the negative cache.
+     * @returns `{ supported: false }` when the provider has no usage fetcher.
+     */
+    async snapshotFor(provider, account, force = false) {
+        const fetcher = this.fetcherFor(provider, account);
+        if (fetcher === undefined)
+            return { supported: false };
+        const key = `${provider}/${account}`;
+        const entry = this.entries.get(key);
+        if (entry !== undefined && Date.now() - entry.at < (entry.cooldownMs ?? this.ttlMs)) {
+            if (entry.snapshot !== undefined) {
+                if (!force)
+                    return entry.snapshot;
+            }
+            else if (entry.lastSnapshot !== undefined) {
+                // A stale-but-real snapshot beats surfacing the cooldown error to
+                // every display surface — this is what was previously showing, so
+                // keep showing it (even through a forced refresh: retrying past the
+                // cooldown is exactly the retry storm `cooldownMs` exists to avoid).
+                return entry.lastSnapshot;
+            }
+            else {
+                throw entry.error;
+            }
+        }
+        try {
+            return await this.refresh(key, fetcher);
+        }
+        catch (error) {
+            // Same fallback as the already-cooling-down branch above, for the
+            // fetch that just failed on THIS call: `refresh` recorded whatever
+            // snapshot was on record before it ran onto the new failure entry.
+            const failed = this.entries.get(key);
+            if (failed?.snapshot === undefined && failed?.lastSnapshot !== undefined)
+                return failed.lastSnapshot;
+            throw error;
+        }
+    }
+    /** Decorate a copy for UI consumers; raw snapshots and routing stay unchanged. */
+    async displaySnapshotFor(provider, account, force = false) {
+        const snapshot = await this.snapshotFor(provider, account, force);
+        const entry = this.entries.get(`${provider}/${account}`);
+        if (!entry)
+            return snapshot;
+        const fetchedAt = entry.snapshot !== undefined ? (entry.fetchedAt ?? entry.at) : entry.lastSnapshotAt;
+        return {
+            ...snapshot,
+            ...(fetchedAt === undefined || !Number.isFinite(fetchedAt) ? {} : { fetchedAt, staleAt: fetchedAt + this.ttlMs }),
+            stale: entry.snapshot === undefined || Date.now() - entry.at >= this.ttlMs,
+            refreshFailed: entry.snapshot === undefined,
+            ...(entry.snapshot === undefined ? { retryAt: entry.at + entry.cooldownMs } : {}),
+        };
+    }
+    /**
+     * Record windows read from a model reply as a fresh snapshot. Windows the
+     * reply carries replace same-kind unscoped windows; the endpoint's other
+     * windows (model-scoped lanes, plan, reset credits) stay as they were.
+     * A live failure cooldown is left in place: it guards the usage endpoint,
+     * which this did not call.
+     * @returns the merged snapshot, or undefined when nothing was recorded.
+     */
+    ingest(provider, account, windows, at = Date.now()) {
+        if (windows.length === 0)
+            return undefined;
+        const key = `${provider}/${account}`;
+        const entry = this.entries.get(key);
+        if (entry !== undefined && entry.snapshot === undefined && Date.now() - entry.at < entry.cooldownMs)
+            return undefined;
+        const base = entry?.snapshot ?? entry?.lastSnapshot ?? { supported: true };
+        const replaced = new Set(windows.map(window => window.kind));
+        const kept = (base.windows ?? []).filter(window => window.scope !== undefined || !replaced.has(window.kind));
+        const snapshot = { ...base, supported: true, windows: [...windows, ...kept] };
+        this.entries.set(key, { snapshot, at, fetchedAt: at });
+        return snapshot;
+    }
+    /** Epoch ms of the account's last successful snapshot, live or fetched. */
+    fetchedAt(provider, account) {
+        const entry = this.entries.get(`${provider}/${account}`);
+        if (entry === undefined)
+            return undefined;
+        return entry.snapshot !== undefined ? (entry.fetchedAt ?? entry.at) : entry.lastSnapshotAt;
+    }
+    /** Recheck after an inference quota failure without erasing another model lane's exhaustion. */
+    expire(provider, account) {
+        const key = `${provider}/${account}`;
+        const entry = this.entries.get(key);
+        // Respect a usage-endpoint cooldown; inference errors do not lift it.
+        if (entry?.snapshot !== undefined)
+            this.entries.set(key, { ...entry, at: Number.NEGATIVE_INFINITY });
+    }
+    /** Drop cached snapshots: one account, or a whole provider when `account` is omitted. */
+    invalidate(provider, account) {
+        if (account !== undefined) {
+            this.entries.delete(`${provider}/${account}`);
+            return;
+        }
+        for (const key of [...this.entries.keys()]) {
+            if (key.startsWith(`${provider}/`))
+                this.entries.delete(key);
+        }
+    }
+    /**
+     * Run (or join) the single in-flight fetch for one account key, caching
+     * either outcome. A missing/invalid credential is deliberately NOT
+     * negative-cached: it costs no network round trip (the session lookup
+     * fails before the request goes out) and re-checking live means the
+     * member rejoins routing the instant its login is fixed, rather than
+     * waiting out a stale cooldown.
+     */
+    refresh(key, fetcher) {
+        let pending = this.inflight.get(key);
+        if (pending === undefined) {
+            // Captured before the fetch starts: whichever real snapshot is on
+            // record right now is what a failure below should fall back to. A
+            // failure entry's own `lastSnapshot` counts too — otherwise the stale
+            // snapshot would survive exactly one cooldown and vanish on the next
+            // consecutive failure, even though nothing newer ever replaced it.
+            const prior = this.entries.get(key);
+            const lastSnapshot = prior?.snapshot ?? prior?.lastSnapshot;
+            const lastSnapshotAt = prior?.snapshot !== undefined ? (prior.fetchedAt ?? prior.at) : prior?.lastSnapshotAt;
+            pending = fetcher().then((snapshot) => {
+                const fetchedAt = Date.now();
+                this.entries.set(key, { snapshot, at: fetchedAt, fetchedAt });
+                return snapshot;
+            }, (error) => {
+                if (!isMissingOrInvalidCredential(error)) {
+                    this.entries.set(key, {
+                        error,
+                        at: Date.now(),
+                        cooldownMs: cooldownFor(error, this.ttlMs),
+                        ...lastSnapshot === undefined ? {} : { lastSnapshot },
+                        ...lastSnapshotAt === undefined ? {} : { lastSnapshotAt },
+                    });
+                }
+                throw error;
+            }).finally(() => {
+                this.inflight.delete(key);
+            });
+            this.inflight.set(key, pending);
+        }
+        return pending;
+    }
+    /** Score one member against a snapshot's windows. */
+    score(member, entry, normalized = false) {
+        const windows = (entry.snapshot.windows ?? []).filter(window => windowApplies(window, member.model));
+        let available = true;
+        let urgency = 0;
+        for (const window of windows) {
+            if (window.usedPercent >= QUOTA_FULL_PERCENT)
+                available = false;
+            urgency = Math.max(urgency, normalized ? normalizedWindowUrgency(window, Date.now()) : windowUrgency(window));
+        }
+        const exhausted = windows.some(window => window.usedPercent >= QUOTA_EXHAUSTED_PERCENT);
+        return { available, urgency, fetchedAt: entry.at, ...exhausted ? { exhausted: true } : {} };
+    }
+}
+/**
+ * The routing view of a fetch failure. Logged out: the member cannot serve
+ * at all. Any other failure (network, endpoint rate limit) must not block
+ * routing — the member stays available with a zero score, degrading the
+ * strategy to plain priority order for it.
+ */
+function degradedQuota(error) {
+    return isMissingOrInvalidCredential(error)
+        ? { available: false, urgency: 0, fetchedAt: 0 }
+        : { available: true, urgency: 0, fetchedAt: 0 };
+}
+/** How long to hold a failure in the negative cache: the endpoint's own `retry-after`, or the default TTL. */
+function cooldownFor(error, defaultTtlMs) {
+    return error instanceof OAuthEndpointError && error.retryAfterMs !== undefined ? error.retryAfterMs : defaultTtlMs;
+}
+/**
+ * Whether a window constrains this model: unscoped windows always do; a
+ * model-scoped window (Claude's Opus/Sonnet lanes) applies when its scope
+ * names the model family.
+ */
+function windowApplies(window, model) {
+    if (window.scope === undefined)
+        return true;
+    return model.toLowerCase().includes(window.scope.toLowerCase());
+}
+/** Dimensionless urgency for the opt-in strategy. Missing timing adds no reset bonus. */
+export function normalizedWindowUrgency(window, now) {
+    const remaining = Math.max(0, Math.min(1, 1 - window.usedPercent / 100));
+    const { durationMs, resetsAt } = window;
+    if (durationMs === undefined || !Number.isFinite(durationMs) || durationMs <= 0
+        || resetsAt === undefined || !Number.isFinite(resetsAt))
+        return remaining;
+    const timeFraction = Math.min(1, Math.max(0.001, (resetsAt - now) / durationMs));
+    return remaining / timeFraction;
+}
+/** The required burn rate of one window (fraction per ms). */
+function windowUrgency(window, now = Date.now()) {
+    const remaining = Math.max(0, 1 - window.usedPercent / 100);
+    const horizon = window.resetsAt !== undefined
+        ? Math.max(window.resetsAt - now, 1)
+        : FALLBACK_HORIZON_MS[window.kind];
+    return remaining / horizon;
+}

package/lib/providers/pool.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The pool adapter: same-subscription account routing, plus optional
+ * configured tier extras. The picker is the union of every account's
+ * catalog. A model listed by several accounts failovers; a model listed by
+ * one account is pinned to it. Tiers are extra picker rows. Member
+ * selection is sticky per session (so prompt caches survive) and optionally
+ * quota-aware; failures fail over to the next member as long as no stream
+ * content chunk has been emitted (leading usage remains buffered).
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmResolvedModelInfo, PreparedAdapterCall, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { ProviderId } from '../auth/store.js';
+import type { AccountAwareAdapter } from './accounts.js';
+import type { PoolDefinition, PoolMemberRef } from './pool-family.js';
+import { PoolHealthRegistry } from './pool-health.js';
+import type { PoolUsageTracker } from './pool-usage.js';
+/** Member-selection strategy: plain priority failover or quota-aware scheduling. */
+export type PoolStrategy = 'priority' | 'quota_aware' | 'quota_normalized';
+export interface PoolAdapterOptions {
+    /** The live subscription adapters, by provider route. */
+    adapters: Partial<Record<ProviderId, AccountAwareAdapter>>;
+    health: PoolHealthRegistry;
+    usage: PoolUsageTracker;
+    strategy: PoolStrategy;
+    /** A challenger must out-urgency the sticky member by this factor to take over. */
+    switchMargin: number;
+    /** The default account of one provider (for config members omitting `account`). */
+    defaultAccount: (provider: ProviderId) => Promise<string | undefined>;
+    /** Resolve legacy account aliases before pool deduplication and cache identity. */
+    resolveAccount?: (provider: ProviderId, account: string) => Promise<string>;
+    /** Account pools (auto-aggregated plus config overrides), resolved lazily. */
+    families: () => Promise<Map<string, PoolDefinition>>;
+    /** User-configured extra picker entries (heterogeneous fallbacks), by pool id. */
+    tiers: Record<string, PoolMemberRef[]>;
+    onWarn: (message: string) => void;
+}
+export declare class PoolAdapter extends LlmAdapter {
+    private readonly options;
+    /** sessionId|poolId → member key of the last member that served a chunk. */
+    private readonly sticky;
+    /** Messages already warned about — configuration diagnostics repeat every request otherwise. */
+    private readonly warned;
+    /**
+     * Short-lived pools snapshot. `owns()` runs on every resolveModel — the
+     * model picker issues one per entry — and pool assembly touches every
+     * provider's catalog and account store, so recompute at most this often.
+     * Auth changes bump {@link generation} so a stale snapshot cannot land.
+     */
+    private poolsCache;
+    private poolsInflight;
+    private generation;
+    constructor(options: PoolAdapterOptions);
+    /** Drop the pools snapshot so the next read reflects the current accounts. */
+    invalidate(): void;
+    /** Warn once per distinct message (pools() runs on every request). */
+    private warnOnce;
+    /** Drop members whose adapter is not registered (copy — caller state is shared). */
+    private usable;
+    /** Account pools (auto-aggregated plus config overrides) with usable members. */
+    private familyPools;
+    /** All pools (account pools merged with extra tiers) with usable members. */
+    private pools;
+    /** Recompute the pools snapshot (account pools merged with extra tiers). */
+    private assemblePools;
+    /**
+     * Extra picker rows one provider lists (configured tiers). Account pools
+     * reuse the catalog entry of the same wire id, so they are not listed
+     * again — the picker stays one row per model in ChatGPT / Claude / ….
+     */
+    modelsForProvider(provider: ProviderId): Promise<LlmModelInfo[]>;
+    /**
+     * Whether `model` on `provider`'s route is served here (several accounts
+     * fail over, one account is pinned, or a configured tier).
+     */
+    owns(provider: ProviderId, model: string): Promise<boolean>;
+    /**
+     * Resolve every member's account (config members may omit it to mean "the
+     * default account") and drop members with no resolvable login. Duplicates
+     * collapse — an explicitly pinned account and the default may coincide.
+     */
+    private concrete;
+    /**
+     * Resolve a pool model to the conservative INTERSECTION of its members'
+     * capabilities: the smallest context window and output cap, the reasoning
+     * efforts every member supports, and the modalities all of them accept —
+     * so a request valid for the pool stays valid after a failover. Capability
+     * metadata is account-specific, so every distinct member is resolved.
+     */
+    resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    private streamMembers;
+    /**
+     * Health and known quota exhaustion filter BOTH strategies: >=100% must
+     * never silently spend paid credits. `quota_aware` ranks healthy members
+     * by urgency, then tries near-full (95–<100%) members by urgency too.
+     * Members without telemetry score zero. Stickiness cannot retain an
+     * exhausted member; within the preferred class it uses `switchMargin`.
+     */
+    private select;
+    /** Pin the serving member to the session (with bounded memory). */
+    private remember;
+    /**
+     * The error for an exhausted pool. It says WHY (issue #139): the last
+     * member failure of this request when members were tried, or the cooling
+     * record that kept every member out of the candidate set — and its `code`
+     * is that failure's own code, never a synthetic `RATE_LIMIT` (a transport
+     * blip on a single-member pool used to be reported as a rate limit). The
+     * earliest recovery hint is scoped to THIS pool's members (the health
+     * registry is shared across pools). `retryNow` drops the hint: a member
+     * that returned an empty completion keeps no cooldown and can be retried
+     * at once, so another member's cooldown must not set the wait.
+     */
+    private exhausted;
+}