@maudecode/talaria-web 1.16.1 → 1.18.0

package/dist/providers/catalog.js

@@ -8,13 +8,13 @@
  * here. ponytail: one live-id cache with a 24h TTL replaces the Python
  * publisher/provenance machinery; `refresh()` evicts it.
  */
-import { readCapped } from '../http/capped.js';
 import { homeDotenvKeys } from '../cli/dotenv.js';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { atomicWriteText } from '../fs/atomic.js';
 import { str } from '../util.js';
+import { QUOTA_THRESHOLD_DEFAULTS } from '../settings.js';
 import { loadEnvFile } from './env-file.js';
 import { ACCOUNT_USAGE_PROVIDERS, FALLBACK_MODELS, OAUTH_PROVIDERS, PORTAL_PROVIDERS, PROVIDER_DISPLAY, PROVIDER_ENV_VAR, PROVIDER_ENV_VAR_ALIASES, PROVIDER_MODELS, SELF_HOSTED_PROVIDER_IDS, } from './tables.js';
 import { activeProviderFromConfig, canonicaliseProviderId, configuredModelIds, configuredModelOptions, customProviderEntries, customProviderSlug, dict, effectiveDefaultModel, isDict, isOpenAiFamilyProvider, mainModelSupportsServiceTier, modelSection, parseProviderQualifiedModel, providerIdentity, resolveProviderAlias, } from '../config/agent-config.js';
@@ -49,6 +49,58 @@ export function catalogOptionId(catalog, model, provider) {
                 return e.id;
     return null;
 }
+/** TAL-542: the vendor a first-party provider serves, or a model id names by prefix; '' when neither says. */
+const PROVIDER_VENDOR = { openai: 'openai', 'openai-api': 'openai', 'openai-codex': 'openai', anthropic: 'anthropic', gemini: 'google', google: 'google' };
+function modelVendor(model) {
+    const m = model.trim().toLowerCase();
+    if (m.includes('/'))
+        return { openai: 'openai', anthropic: 'anthropic', google: 'google', gemini: 'google' }[m.slice(0, m.indexOf('/'))] ?? '';
+    return m.startsWith('gpt') ? 'openai' : m.startsWith('claude') ? 'anthropic' : m.startsWith('gemini') ? 'google' : '';
+}
+/**
+ * TAL-542 (Python `_resolve_compatible_session_model_state` + `_repair_foreign_session_model_provider`): the pair a
+ * session's stale model starts on. A model its provider's catalog group does not list moves to the one other provider
+ * that lists it; else, when the model names another vendor than a first-party provider, to the profile default. No
+ * evidence (no group for the provider, a group built from a failed live lookup in `unlisted`, which never names an owner either) keeps the pair, and so does a stored
+ * provider that is the profile's own unless the model names another vendor. `null` keeps the pair.
+ */
+export function repairSessionModel(catalog, model, provider, unlisted = new Set()) {
+    const active = canonicaliseProviderId(catalog.active_provider);
+    const pid = canonicaliseProviderId(provider) || active;
+    if (!model.trim() || !pid || unlisted.has(pid) || !catalog.groups.some((g) => canonicaliseProviderId(g.provider_id) === pid))
+        return null;
+    const loose = (id) => id.trim().toLowerCase().replaceAll('-', '.');
+    const want = loose(model);
+    const entries = catalog.groups.flatMap((g) => [...g.models, ...(g.extra_models ?? [])]);
+    const tail = (id) => loose(id.slice(id.indexOf('/') + 1));
+    const own = entries.filter((e) => canonicaliseProviderId(e.provider_id) === pid).map((e) => str(e.bare_id));
+    if (own.some((bare) => loose(bare) === want))
+        return null;
+    // Equivalence across ids only drops a recognised vendor prefix; another namespace is no evidence. A match starts on the
+    // matching entry's own id, so the turn runs on the id that provider advertises.
+    const vendorless = (id) => loose(id.replace(/^(openai|anthropic|google|gemini)\//i, ''));
+    const same = (bare) => vendorless(bare) === vendorless(model);
+    const here = own.find(same);
+    if (here)
+        return [here, pid];
+    // Python `_catalog_model_id_matches`: a model the provider lists under another namespace is kept, never moved.
+    if (own.some((bare) => tail(bare) === want))
+        return null;
+    if (!provider || pid !== active) {
+        const owners = new Map(entries.filter((e) => same(str(e.bare_id)) && !unlisted.has(canonicaliseProviderId(e.provider_id))).map((e) => [canonicaliseProviderId(e.provider_id), str(e.bare_id)]));
+        const [only] = owners.size === 1 ? [...owners] : [];
+        if (only)
+            return [only[1], only[0]];
+    }
+    const vendor = PROVIDER_VENDOR[pid] ?? '';
+    const named = modelVendor(model);
+    // Python: Codex takes bare ids, so an `openai/` id on it is stale too.
+    if (!vendor || !named || (named === vendor && !(pid === 'openai-codex' && model.includes('/'))))
+        return null;
+    const defaultModel = str(catalog.default_bare_id).trim();
+    const defaultProvider = canonicaliseProviderId(catalog.default_provider_id) || active;
+    return defaultModel && defaultProvider && (defaultModel !== model || defaultProvider !== pid) ? [defaultModel, defaultProvider] : null;
+}
 /** Python `_split_picker_overflow_models`: past 25 rows the picker shows 15, keeping the selected model visible. */
 export function splitPickerOverflow(models, selected, providerId) {
     if (models.length <= MODEL_PICKER_OVERFLOW_THRESHOLD)
@@ -98,6 +150,17 @@ export function stampAuxiliarySelections(aux, catalog) {
 }
 /** Python `_BESPOKE_CATALOG_PROVIDERS`: cards whose catalog is resolved by their own rule, never the generic live probe. */
 const BESPOKE_CATALOG_PROVIDERS = new Set(['openai-codex', 'nous', 'xai-oauth', 'lmstudio', 'opencode-go']);
+/** A provider's configured endpoint: its `providers.<id>.base_url` (alias-aware), else the active model's `base_url`. */
+const configuredBaseUrl = (pid, config) => {
+    const providers = dict(config.providers);
+    const cfg = dict(providers[pid] ?? providers[Object.keys(providers).find((k) => providerIdentity(k) === providerIdentity(pid)) ?? '']);
+    return str(cfg.base_url).trim() || (activeProviderFromConfig(config) === pid ? str(modelSection(config).base_url).trim() : '');
+};
+/** TAL-603: the credential family a card's badge names; `null` when the card holds no credential. */
+const KEY_SOURCE_KINDS = { env_file: 'env', env_var: 'env', env: 'env', oauth: 'oauth', token: 'oauth', config_yaml: 'config', config: 'config', credential_pool: 'pool', plugin: 'plugin' };
+const keySourceKind = (row) => row.has_key === true && row.key_source !== 'none' ? KEY_SOURCE_KINDS[str(row.key_source)] ?? 'other' : null;
+/** TAL-570: Ollama and LM Studio run keyless, so a configured endpoint makes them ready the way a key does. */
+const selfHostedEndpoint = (pid, config) => SELF_HOSTED_PROVIDER_IDS.has(pid) && Boolean(configuredBaseUrl(pid, config));
 /** Python `_unqualified_model_id`: strip a picker routing hint (`@provider:`). */
 const unqualifiedModelId = (id) => parseProviderQualifiedModel(id)?.[0] ?? id.trim();
 /** Python `_MODEL_PICKER_OVERFLOW_THRESHOLD` / `_MODEL_PICKER_VISIBLE_TARGET`. */
@@ -106,8 +169,8 @@ const MODEL_PICKER_VISIBLE_TARGET = 15;
 const ACCOUNT_USAGE_CACHE_TTL_S = 45;
 const LIVE_TTL_S = 86_400;
 const PROVIDERS_TTL_S = 30;
-const QUOTA_TIMEOUT_MS = 15_000;
-const OPENROUTER_KEY_URL = 'https://openrouter.ai/api/v1/key';
+/** The sidecar reads a balance endpoint with a 15 s timeout of its own. */
+const BALANCE_TIMEOUT_MS = 20_000;
 const PLUGIN_LIST_TIMEOUT_MS = 15_000;
 /** TAL-288: the card text for a plugin provider the Agent does not report ready. */
 const PLUGIN_SETUP_ERRORS = {
@@ -118,6 +181,34 @@ const PLUGIN_SETUP_ERRORS = {
 };
 const PLUGIN_NO_MODELS = 'This provider listed no models.';
 const COST_SNAPSHOT_MAX_DAYS = 365;
+/**
+ * The last `days` daily snapshots with their spend deltas, bar heights, monthly pace, and budget standing (the legacy
+ * Web chart's formulas). A drop in `used` is a credit reset, so that day's delta is its `used`.
+ */
+function costHistoryView(rows, days, budget) {
+    const window = rows.slice(-days);
+    const deltas = window.map((e, i) => {
+        const prev = window[i - 1];
+        if (i === 0 || e.used === null || prev?.used === null || prev?.used === undefined)
+            return null;
+        const delta = e.used - prev.used < 0 ? e.used : e.used - prev.used;
+        return Math.abs(delta) < 1e-9 ? 0 : Math.round(delta * 1e6) / 1e6;
+    });
+    const known = deltas.filter((d) => d !== null);
+    const maxDelta = Math.max(...deltas.map((d) => d ?? 0), 1e-9);
+    const pace = known.length ? (known.reduce((a, b) => a + b, 0) / known.length) * 30 : null;
+    const budgetPercent = pace !== null && pace > 0 && budget !== null && budget > 0 ? Math.round((pace / budget) * 100) : null;
+    return {
+        snapshots: window.map((e, i) => {
+            const delta = deltas[i] ?? null;
+            return { date: e.date, used: e.used, delta, bar_percent: delta === null ? 0 : Number(Math.max((delta / maxDelta) * 100, delta > 0 ? 2 : 0).toFixed(1)) };
+        }),
+        monthly_pace: pace === null ? null : Math.round(pace * 100) / 100,
+        has_enough_data: known.length > 0,
+        budget_percent: budgetPercent,
+        budget_level: budgetPercent === null ? null : budgetPercent >= 100 ? 'over' : budgetPercent >= 80 ? 'warn' : 'ok',
+    };
+}
 const FIVE_HOUR_WINDOW_S = 18_000;
 const WEEK_WINDOW_S = 604_800;
 /** Swift `rounded()`: half away from zero. */
@@ -212,6 +303,46 @@ export function normalizeQuotaWindows(raw, nowSeconds) {
         weekly_window_index: index(labelHas('week')),
     };
 }
+/** The burn-rate breakpoints apply once the window is old and used enough and the projection empties it before reset. */
+function projectionEligible(pace, usedPercent, minimumElapsedHours) {
+    return pace.elapsed_minutes >= Math.max(0, minimumElapsedHours) * 60 && usedPercent >= 5 && pace.minutes_to_reset > 20
+        && (pace.projected_minutes_to_empty ?? Infinity) < pace.minutes_to_reset;
+}
+/** The App's former `ProviderQuotaUrgencyCalculator.urgency` for one colour basis; a pace basis without a pace falls back to remaining. */
+function quotaLevel(window, status, basis, t) {
+    if (status === 'stale')
+        return 'stale';
+    const remaining = window?.remaining_percent ?? null;
+    if (status !== 'available' || remaining === null)
+        return status === 'available' ? 'healthy' : 'unavailable';
+    const pace = window?.pace ?? null;
+    if (basis === 'pace' && pace) {
+        const eligible = projectionEligible(pace, 100 - remaining, t.pace_minimum_elapsed_hours);
+        if (eligible && pace.burn_rate >= Math.max(0, t.pace_critical_burn_rate_percent) / 100)
+            return 'critical';
+        if (eligible && pace.burn_rate >= Math.max(0, t.pace_warning_burn_rate_percent) / 100)
+            return 'warning';
+        return pace.pace_delta_percent <= -Math.max(0, t.pace_tolerance_percent) ? 'warning' : 'healthy';
+    }
+    if (remaining <= Math.max(0, t.critical_remaining_percent))
+        return 'critical';
+    if (remaining <= Math.max(0, t.warning_remaining_percent))
+        return 'warning';
+    return 'healthy';
+}
+export function classifyQuotaSource(source, t) {
+    const urgency = (w) => ({ remaining: quotaLevel(w, source.status, 'remaining', t), pace: quotaLevel(w, source.status, 'pace', t) });
+    return {
+        ...source,
+        windows: source.windows.map((w) => ({
+            ...w,
+            pace: w.pace && { ...w.pace, status: w.pace.pace_delta_percent <= -Math.max(0, t.pace_tolerance_percent) ? 'over' : w.pace.pace_delta_percent > 1 ? 'under' : 'on' },
+            projection_eligible: w.pace !== null && w.remaining_percent !== null && projectionEligible(w.pace, 100 - w.remaining_percent, t.pace_minimum_elapsed_hours),
+            urgency: urgency(w),
+        })),
+        urgency: { remaining: urgency(source.windows[0]).remaining, pace: urgency(source.windows[source.pace_window_index ?? 0]).pace },
+    };
+}
 export function displayName(pid) {
     return PROVIDER_DISPLAY[pid] ?? pid.split('-').map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w)).join(' ');
 }
@@ -300,6 +431,25 @@ export function deduplicateModelIds(groups) {
                 m.id = `@${groups[gi].provider_id}:${m.id}`;
         }
 }
+/** OpenCode Go's usage windows: their label and length (Python `_sanitize_opencode_go_account_limits`). */
+const OPENCODE_GO_WINDOWS = { rolling: ['5-hour', FIVE_HOUR_WINDOW_S], weekly: ['Weekly', WEEK_WINDOW_S], monthly: ['Monthly', null] };
+/** One pool account's local state as account limits; `status` is the account's, which its quota source shows. */
+function poolEntryLimits(entry, at) {
+    return {
+        source: 'local_pool', title: 'Credential pool', status: entry.status, available: entry.status === 'available', plan: null, details: [],
+        unavailable_reason: entry.unavailable_reason, retry_after: entry.retry_after, fetched_at: null, ...normalizeQuotaWindows([], at),
+    };
+}
+/** Python `_local_pool_snapshot`: a provider's pool accounts summarised as account limits. */
+function poolLimits(entries, at) {
+    const count = (status) => entries.filter((e) => e.status === status).length;
+    const [available, exhausted, dead] = [count('available'), count('exhausted'), count('dead')];
+    const details = [`${String(available)}/${String(entries.length)} credentials available`, ...(exhausted ? [`${String(exhausted)} exhausted`] : []), ...(dead ? [`${String(dead)} dead`] : [])];
+    return {
+        source: 'local_pool', title: 'Credential pool', available: available > 0, plan: null, details, unavailable_reason: available ? null : 'All pool credentials are unavailable.', fetched_at: null,
+        ...normalizeQuotaWindows([], at),
+    };
+}
 /** Quota sources keep the first row per source id, ordered by provider id, account label, then source id (TAL-272). */
 export function uniqueQuotaSources(sources) {
     const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
@@ -308,12 +458,17 @@ export function uniqueQuotaSources(sources) {
 }
 export class ProviderCatalog {
     deps;
+    /** Failed live lookups by home, provider, and the `sourceFingerprint` they ran under (TAL-542). */
     liveFailed = new Set();
+    /** `source`: the `sourceFingerprint` the ids were fetched under; another one makes them stale (TAL-542). */
     liveIds = new Map();
     liveInflight = new Map();
+    /** `pooled`: the fill's `poolProviders` answer, null when unknown (TAL-638). */
     providersCache = new Map();
     /** TAL-301: the last catalog served per profile home, for the sync session payloads' `model_option_id`. */
     lastModels = new Map();
+    /** TAL-542: per `lastModels` catalog, the `sourceFingerprint` it was built from, when, and the providers whose group came from a failed live lookup. */
+    lastModelsMeta = new Map();
     constructor(deps) {
         this.deps = deps;
     }
@@ -336,11 +491,19 @@ export class ProviderCatalog {
             this.liveIds.delete(key);
         }
         this.providersCache.clear();
+        // Credentials changed: the last pool answers no longer stand in for a failed lookup.
+        for (const key of [...this.lastPoolAnswers.keys()])
+            if (!profileHome || key.startsWith(`${profileHome}\0`))
+                this.lastPoolAnswers.delete(key);
         // The picker catalog changed: option ids rebuild on the next read rather than pairing against the old one.
-        if (profileHome)
+        if (profileHome) {
             this.lastModels.delete(profileHome);
-        else
+            this.lastModelsMeta.delete(profileHome);
+        }
+        else {
             this.lastModels.clear();
+            this.lastModelsMeta.clear();
+        }
     }
     /** TAL-301: the entry id a stored `(model, provider)` pair selects in the last catalog built for this home; a cold home starts building one. */
     modelOptionFor(profileHome, model, provider) {
@@ -351,9 +514,58 @@ export class ProviderCatalog {
         }
         return catalogOptionId(catalog, model, provider);
     }
-    /** Builds the catalog `modelOptionFor` reads once per home; an unavailable catalog leaves every option id null. */
+    /**
+     * TAL-542: the identity of the files a catalog and its live ids derive from: config.yaml, `.env`, the Agent's sign-in
+     * store (`auth.json`, rewritten by an account switch), and the installed plugins directory, so a change outside Web
+     * makes both stale.
+     */
+    sourceFingerprint(profileHome) {
+        const stamp = (name) => {
+            try {
+                const st = statSync(join(profileHome, name), { bigint: true });
+                return `${String(st.mtimeNs)}:${String(st.size)}:${String(st.ino)}`;
+            }
+            catch {
+                return 'missing';
+            }
+        };
+        return [this.deps.config.fingerprint(profileHome), ...['.env', 'auth.json', 'plugins'].map(stamp)].join('|');
+    }
+    /** The last catalog built for this home, younger than `maxAgeS`, while its source files are unchanged since (TAL-542). */
+    currentModels(profileHome, maxAgeS = Infinity) {
+        const meta = this.lastModelsMeta.get(profileHome);
+        return meta?.source === this.sourceFingerprint(profileHome) && this.deps.now() - meta.at < maxAgeS ? this.lastModels.get(profileHome) : undefined;
+    }
+    /**
+     * TAL-542: `repairSessionModel` against this home's catalog. Agent-owned sign-in and plugin state has no file to
+     * fingerprint, so the repair also needs a catalog no older than the providers listing it read (`PROVIDERS_TTL_S`);
+     * a cold or stale one keeps the pair and starts a rebuild.
+     */
+    sessionModelRepair(profileHome, model, provider) {
+        const catalog = this.currentModels(profileHome, PROVIDERS_TTL_S);
+        if (!catalog) {
+            void this.warmSessionModelRepair(profileHome);
+            return null;
+        }
+        return repairSessionModel(catalog, model, provider, this.lastModelsMeta.get(profileHome)?.unconfirmed);
+    }
+    /**
+     * Builds the catalog `sessionModelRepair` reads unless a fresh enough one exists; call it after the request's last
+     * await. A source that changed while the build awaited makes that build stale, so it is rebuilt once.
+     */
+    async warmSessionModelRepair(profileHome) {
+        for (let attempt = 0; attempt < 2 && !this.currentModels(profileHome, PROVIDERS_TTL_S); attempt += 1) {
+            try {
+                await this.models(profileHome);
+            }
+            catch {
+                return; /* fail closed: the pair is kept */
+            }
+        }
+    }
+    /** Builds the catalog `modelOptionFor` reads once per home, again after config.yaml or `.env` changes; an unavailable catalog leaves every option id null. */
     async warmModelOptions(profileHome) {
-        if (this.lastModels.has(profileHome))
+        if (this.currentModels(profileHome))
             return;
         try {
             await this.models(profileHome);
@@ -364,16 +576,20 @@ export class ProviderCatalog {
      * The process-environment value of `name` as a named profile may see it: values `loadStartupEnv` copied from the
      * default profile's `.env` belong to that profile only, so they never count for another profile.
      */
-    processEnv(name, profileHome) {
-        if (!this.deps.isRootProfileHome(profileHome) && homeDotenvKeys(this.deps.env).has(name))
+    /** `cleared`: the variable a key delete clears, which also retires its `.env`-owned startup copy (TAL-641). */
+    processEnv(name, profileHome, cleared) {
+        if ((name === cleared || !this.deps.isRootProfileHome(profileHome)) && homeDotenvKeys(this.deps.env).has(name))
             return undefined;
         return this.deps.env[name];
     }
-    /** Python `_provider_has_key` minus the credential pool (the sidecar answers OAuth/pool state). */
-    providerHasKey(pid, config, envValues, profileHome) {
+    /**
+     * Python `_provider_has_key` minus the credential pool, which `probeKey` reads from the sidecar.
+     * `cleared` (TAL-641) answers for after `setProviderKey(…, null)`: that variable's `.env` entry and startup copy are gone.
+     */
+    providerHasKey(pid, config, envValues, profileHome, cleared) {
         const envVar = providerEnvVar(pid);
         if (envVar) {
-            if (valueCountsAsApiKey(pid, envValues[envVar]) || valueCountsAsApiKey(pid, this.processEnv(envVar, profileHome)))
+            if ((envVar !== cleared && valueCountsAsApiKey(pid, envValues[envVar])) || valueCountsAsApiKey(pid, this.processEnv(envVar, profileHome, cleared)))
                 return true;
             for (const alias of PROVIDER_ENV_VAR_ALIASES[pid] ?? [])
                 if (valueCountsAsApiKey(pid, envValues[alias]) || valueCountsAsApiKey(pid, this.processEnv(alias, profileHome)))
@@ -407,11 +623,13 @@ export class ProviderCatalog {
             return null;
         }
     }
-    async probeKey(profileHome, pid, config, envValues) {
+    /** `pooled`: the providers whose persisted credential pool holds an added account (TAL-638). */
+    async probeKey(profileHome, pid, config, envValues, pooled) {
         let hasKey = this.providerHasKey(pid, config, envValues, profileHome);
         let isOauth = OAUTH_PROVIDERS.has(pid);
         let keySource = 'none';
         let authError = null;
+        let removable = false;
         if (isOauth) {
             keySource = 'oauth';
             const status = await this.authStatus(profileHome, pid);
@@ -431,8 +649,10 @@ export class ProviderCatalog {
         else if (hasKey) {
             const envVar = providerEnvVar(pid);
             if (envVar) {
-                if (valueCountsAsApiKey(pid, envValues[envVar]))
+                if (valueCountsAsApiKey(pid, envValues[envVar])) {
                     keySource = 'env_file';
+                    removable = !pooled.has(pid) && !this.providerHasKey(pid, config, envValues, profileHome, envVar);
+                }
                 else if (valueCountsAsApiKey(pid, this.processEnv(envVar, profileHome)))
                     keySource = 'env_var';
                 else {
@@ -452,6 +672,11 @@ export class ProviderCatalog {
             else
                 keySource = 'config_yaml';
         }
+        else if (pooled.has(pid)) {
+            // Python `_has_explicit_pool_credentials`: keys added with `hermes auth add` live only in the Agent's pool.
+            hasKey = true;
+            keySource = 'credential_pool';
+        }
         else if (!providerEnvVar(pid) && /^[a-z][a-z0-9_-]{0,63}$/.test(pid)) {
             const status = await this.authStatus(profileHome, pid);
             if (status?.logged_in) {
@@ -461,25 +686,31 @@ export class ProviderCatalog {
                 isOauth = true;
             }
         }
-        return { hasKey, keySource, authError, isOauth };
+        return { hasKey, keySource, authError, isOauth, removable };
     }
     /** Live model ids from the Agent for one provider, cached per profile home. */
     async liveModelIds(profileHome, pid, opts = {}) {
         const key = `${profileHome}\0${pid}`;
+        const source = this.sourceFingerprint(profileHome);
         const hit = this.liveIds.get(key);
-        if (hit && !opts.force && this.deps.now() - hit.at < LIVE_TTL_S)
+        if (hit?.source === source && !opts.force && this.deps.now() - hit.at < LIVE_TTL_S)
             return hit.ids;
-        const inflight = this.liveInflight.get(key);
+        // A lookup started under another source answers for the old endpoint or credential; this one starts its own.
+        const flightKey = `${key}\0${source}`;
+        const inflight = this.liveInflight.get(flightKey);
         if (inflight && !opts.force)
             return inflight;
         const sidecar = this.deps.sidecar();
-        if (!sidecar)
+        // No sidecar is a failed lookup for this source: the ids it keeps showing never confirm a stale-model repair (TAL-542).
+        if (!sidecar) {
+            this.liveFailed.add(flightKey);
             return hit?.ids ?? [];
+        }
         const run = sidecar.call('providers.model_ids', { profile_home: profileHome, provider: pid, ...(opts.force ? { force_refresh: true } : {}) }, { timeoutMs: 30_000 })
-            .then((r) => { this.liveIds.set(key, { at: this.deps.now(), ids: r.model_ids }); this.liveFailed.delete(key); return r.model_ids; })
-            .catch((error) => { this.deps.log(`[catalog] live model ids for ${pid} failed: ${str(error.message)}`); this.liveFailed.add(key); return hit?.ids ?? []; })
-            .finally(() => { this.liveInflight.delete(key); });
-        this.liveInflight.set(key, run);
+            .then((r) => { this.liveIds.set(key, { at: this.deps.now(), ids: r.model_ids, source }); this.liveFailed.delete(flightKey); return r.model_ids; })
+            .catch((error) => { this.deps.log(`[catalog] live model ids for ${pid} failed: ${str(error.message)}`); this.liveFailed.add(flightKey); return hit?.ids ?? []; })
+            .finally(() => { this.liveInflight.delete(flightKey); });
+        this.liveInflight.set(flightKey, run);
         return run;
     }
     /**
@@ -501,12 +732,18 @@ export class ProviderCatalog {
     }
     /** Python `get_providers`. */
     async providers(profileHome) {
+        return structuredClone((await this.providerRows(profileHome)).payload);
+    }
+    /** The cached `providers` answer, shared with `quotas`; callers never mutate it. */
+    async providerRows(profileHome) {
         const config = await this.deps.config.read(profileHome);
         const envValues = loadEnvFile(join(profileHome, '.env'));
         const cacheKey = JSON.stringify([config, envValues]);
         const hit = this.providersCache.get(profileHome);
         if (hit?.key === cacheKey && this.deps.now() - hit.at < PROVIDERS_TTL_S)
-            return structuredClone(hit.payload);
+            return hit;
+        const pooledIds = await this.poolProviders(profileHome);
+        const pooled = new Set(pooledIds ?? []);
         const active = activeProviderFromConfig(config);
         const known = new Set([...Object.keys(PROVIDER_DISPLAY), ...Object.keys(PROVIDER_MODELS), ...OAUTH_PROVIDERS]);
         // A plugin never stands in for a built-in provider, by id or alias (that would route to the built-in's billing); it
@@ -522,14 +759,15 @@ export class ProviderCatalog {
         }
         const rows = [];
         for (const pid of [...known].sort()) {
-            const probe = await this.probeKey(profileHome, pid, config, envValues);
+            const probe = await this.probeKey(profileHome, pid, config, envValues, pooled);
             if (pid === 'openai' && !probe.hasKey && looksLikeCodexOauthToken(str(envValues[providerEnvVar('openai') ?? ''] ?? this.deps.env.OPENAI_API_KEY)))
                 continue;
+            const configured = probe.hasKey || selfHostedEndpoint(pid, config);
             let models = pid === 'openrouter' ? FALLBACK_MODELS.map((m) => ({ id: m.id, label: m.label })) : [...(PROVIDER_MODELS[pid] ?? [])];
             let modelsTotal = models.length;
             // Python: the card prefers the live catalog for every keyed provider (exactly like the picker), keeping the
             // static list as the cold/failed-probe fallback; Nous renders a featured subset with the full count.
-            if (probe.hasKey && (probe.isOauth || pid === 'lmstudio' || pid === 'nous' || !BESPOKE_CATALOG_PROVIDERS.has(pid))) {
+            if (configured && (probe.isOauth || pid === 'lmstudio' || pid === 'nous' || !BESPOKE_CATALOG_PROVIDERS.has(pid))) {
                 const live = await this.liveModelIds(profileHome, pid);
                 if (live.length) {
                     models = pid === 'nous' ? live.slice(0, 25).map((id) => ({ id: `@nous:${id}`, label: `${formatOllamaLabel(id.includes('/') ? id.slice(id.indexOf('/') + 1) : id)} (via Nous)` })) : live.map((id) => ({ id, label: labelForModel(id, []) }));
@@ -545,17 +783,19 @@ export class ProviderCatalog {
                 if (pid !== 'nous')
                     modelsTotal += added.length;
             }
-            const baseUrl = str(providerCfg.base_url).trim() || (active === pid ? str(modelSection(config).base_url).trim() : '') || null;
+            const baseUrl = configuredBaseUrl(pid, config) || null;
             rows.push({
                 id: pid,
                 display_name: displayName(pid),
                 has_key: probe.hasKey,
+                configured,
                 configurable: !probe.isOauth && Boolean(providerEnvVar(pid)),
                 is_oauth: probe.isOauth,
                 is_plugin_provider: false,
                 is_self_hosted: SELF_HOSTED_PROVIDER_IDS.has(pid),
                 is_custom: false,
                 key_source: probe.keySource,
+                removable: probe.removable && !SELF_HOSTED_PROVIDER_IDS.has(pid),
                 base_url: baseUrl,
                 auth_error: probe.authError,
                 env_var: providerEnvVar(pid),
@@ -568,8 +808,8 @@ export class ProviderCatalog {
             const ready = plugin.setup === 'ready';
             const live = ready ? await this.liveModelIds(profileHome, plugin.name) : [];
             rows.push({
-                id: plugin.name, display_name: plugin.display_name || plugin.name, has_key: ready,
-                configurable: false, is_oauth: false, is_plugin_provider: true, is_self_hosted: false, is_custom: false, key_source: ready ? 'plugin' : 'none',
+                id: plugin.name, display_name: plugin.display_name || plugin.name, has_key: ready, configured: ready,
+                configurable: false, is_oauth: false, is_plugin_provider: true, is_self_hosted: false, is_custom: false, key_source: ready ? 'plugin' : 'none', removable: false,
                 base_url: null, auth_error: plugin.setup === 'ready' ? (live.length ? null : PLUGIN_NO_MODELS) : PLUGIN_SETUP_ERRORS[plugin.setup], env_var: null,
                 models: live.map((id) => ({ id, label: labelForModel(id, []) })), models_total: live.length,
             });
@@ -583,24 +823,34 @@ export class ProviderCatalog {
             // Python: an `api_key: ${VAR}` reference counts when the variable resolves.
             const cpKey = str(cp.api_key).trim();
             const envRef = /^\$\{([^}]+)\}$/.exec(cpKey)?.[1] ?? '';
-            const hasKey = envRef ? Boolean((this.processEnv(envRef, profileHome) ?? '').trim()) : valueCountsAsApiKey(slug, cp.api_key) || Boolean(str(cp.key_env).trim() && this.processEnv(str(cp.key_env).trim(), profileHome));
+            const yamlKey = !envRef && valueCountsAsApiKey(slug, cp.api_key);
+            const hasKey = envRef ? Boolean((this.processEnv(envRef, profileHome) ?? '').trim()) : yamlKey || Boolean(str(cp.key_env).trim() && this.processEnv(str(cp.key_env).trim(), profileHome));
+            // TAL-603: a `${VAR}` reference or `key_env` credential comes from the environment.
+            const keySource = yamlKey ? 'config_yaml' : hasKey ? 'env_var' : cpKey ? 'config_yaml' : 'none';
             rows.push({
-                id: slug, display_name: name, has_key: hasKey,
-                configurable: false, is_oauth: false, is_plugin_provider: false, is_self_hosted: false, is_custom: true, key_source: str(cp.api_key).trim() ? 'config_yaml' : 'none',
+                id: slug, display_name: name, has_key: hasKey, configured: hasKey,
+                configurable: false, is_oauth: false, is_plugin_provider: false, is_self_hosted: false, is_custom: true, key_source: keySource, removable: false,
                 base_url: str(cp.base_url).trim() || null, auth_error: null, env_var: null, models: ids.map((id) => ({ id, label: labelForModel(id, []) })), models_total: ids.length,
             });
         }
         // Python `_provider_sort_key`: active first, then `custom:*`, then keyed providers, then the rest (alphabetical within).
         const rank = (p) => (str(p.id) === active ? 0 : str(p.id).startsWith('custom:') ? 1 : p.has_key ? 2 : 3);
         rows.sort((a, b) => rank(a) - rank(b) || (str(a.id) < str(b.id) ? -1 : str(a.id) > str(b.id) ? 1 : 0));
-        for (const row of rows)
+        for (const row of rows) {
             row.models = stampModelEntries(row.models, str(row.id));
-        const payload = { providers: rows, active_provider: active };
-        this.providersCache.set(profileHome, { at: this.deps.now(), key: cacheKey, payload });
-        return structuredClone(payload);
+            // TAL-603: the server decides the Active badge, the key badge and the count; a featured list never outnumbers its total.
+            row.is_active = str(row.id) === active;
+            row.key_source_kind = keySourceKind(row);
+            row.models_total = Math.max(Number(row.models_total), row.models.length);
+        }
+        const entry = { at: this.deps.now(), key: cacheKey, payload: { providers: rows, active_provider: active }, pooled: pooledIds };
+        this.providersCache.set(profileHome, entry);
+        return entry;
     }
     /** Python `get_available_models` (static catalog + live ids for keyed providers). */
     async models(profileHome) {
+        const source = this.sourceFingerprint(profileHome);
+        const unconfirmed = new Set();
         const config = await this.deps.config.read(profileHome);
         const envValues = loadEnvFile(join(profileHome, '.env'));
         const active = activeProviderFromConfig(config);
@@ -644,11 +894,11 @@ export class ProviderCatalog {
                 detected.add(canonical);
         }
         // Python: OAuth providers the Agent reports as logged in join the picker with their live catalog (#1567, #2545); so do
-        // ready plugin providers (TAL-288), under their own name.
+        // ready plugin providers (TAL-288), under their own name, and providers keyed only through the credential pool (TAL-638).
         const signedIn = new Set();
         const pluginNames = new Map();
-        for (const row of (await this.providers(profileHome)).providers) {
-            if (row.has_key !== true || (row.is_oauth !== true && row.is_plugin_provider !== true))
+        for (const row of (await this.providerRows(profileHome)).payload.providers) {
+            if (row.has_key !== true || (row.is_oauth !== true && row.is_plugin_provider !== true && row.key_source !== 'credential_pool'))
                 continue;
             signedIn.add(str(row.id));
             if (row.is_plugin_provider === true)
@@ -708,12 +958,15 @@ export class ProviderCatalog {
             let raw = [];
             if ('models' in providerCfg && providerCfg.models_discovered !== true)
                 raw = configuredModelOptions(providerCfg.models);
-            if (!raw.length && (this.providerHasKey(pid, config, envValues, profileHome) || signedIn.has(pid))) {
+            if (!raw.length && (this.providerHasKey(pid, config, envValues, profileHome) || selfHostedEndpoint(pid, config) || signedIn.has(pid))) {
                 const live = await this.liveModelIds(profileHome, pid);
+                // TAL-542: a failed lookup leaves this group's list unconfirmed, so the stale-model repair never trusts it.
+                if (this.liveFailed.has(`${profileHome}\0${pid}\0${source}`))
+                    unconfirmed.add(pid);
                 if (live.length)
                     raw = live.map((id) => ({ id, label: pid === 'nous' ? `${formatOllamaLabel(id.includes('/') ? id.slice(id.indexOf('/') + 1) : id)} (via Nous)` : labelForModel(id, []) }));
                 // Python (#1567): an authenticated Nous account with an empty live catalog shows no group; only a failed lookup falls back to the curated list.
-                else if (pid === 'nous' && !this.liveFailed.has(`${profileHome}\0${pid}`))
+                else if (pid === 'nous' && !this.liveFailed.has(`${profileHome}\0${pid}\0${source}`))
                     continue;
             }
             if (!raw.length)
@@ -772,15 +1025,16 @@ export class ProviderCatalog {
         const defaults = { active_provider: active, default_model: defaultModel, default_provider_id: defaultProvider, default_bare_id: defaultBare };
         if (!kept.length && defaultModel) {
             const providerId = active ?? 'default';
-            return this.remember(profileHome, { ...defaults, groups: [{ provider: 'Default', provider_id: providerId, models: stampModelEntries([{ id: defaultModel, label: labelForModel(defaultModel, []) }], providerId) }], aliases: {}, configured_model_badges: {} });
+            return this.remember(profileHome, { source, unconfirmed }, { ...defaults, groups: [{ provider: 'Default', provider_id: providerId, models: stampModelEntries([{ id: defaultModel, label: labelForModel(defaultModel, []) }], providerId) }], aliases: {}, configured_model_badges: {} });
         }
         const stamped = kept.map((g) => ({ ...g, models: stampModelEntries(g.models, g.provider_id), ...(g.extra_models ? { extra_models: stampModelEntries(g.extra_models, g.provider_id) } : {}) }));
-        return this.remember(profileHome, { ...defaults, groups: stamped, aliases, configured_model_badges: this.badges(kept, active, defaultModel, fallbackCfg) });
+        return this.remember(profileHome, { source, unconfirmed }, { ...defaults, groups: stamped, aliases, configured_model_badges: this.badges(kept, active, defaultModel, fallbackCfg) });
     }
     /** Stamps the default's entry id and keeps the catalog for `modelOptionFor`. */
-    remember(profileHome, catalog) {
+    remember(profileHome, meta, catalog) {
         catalog.default_option_id = catalogOptionId(catalog, catalog.default_bare_id ?? null, catalog.default_provider_id ?? null);
         this.lastModels.set(profileHome, catalog);
+        this.lastModelsMeta.set(profileHome, { ...meta, at: this.deps.now() });
         return structuredClone(catalog);
     }
     /** Python `_configured_model_badges_from_static_catalog`: which picker rows are the main/fallback selections. */
@@ -905,11 +1159,22 @@ export class ProviderCatalog {
                     return v;
             }
         }
-        const p = dict(dict(config.providers)[pid]);
-        return str(p.api_key).trim() || null;
+        // The same config sources `providerHasKey` counts, so a provider shown as keyed resolves its key.
+        const model = modelSection(config);
+        if (canonicaliseProviderId(model.provider) === canonicaliseProviderId(pid) && valueCountsAsApiKey(pid, model.api_key))
+            return str(model.api_key).trim();
+        for (const [key, value] of Object.entries(dict(config.providers))) {
+            if (providerIdentity(key) === providerIdentity(pid) && isDict(value) && valueCountsAsApiKey(pid, value.api_key))
+                return str(value.api_key).trim();
+        }
+        return null;
     }
-    /** Python `get_provider_quota`. */
+    /** Account-usage snapshots by profile home, provider, and pool account. */
     accountUsageCache = new Map();
+    /**
+     * Python `get_provider_quota`. `credential` scopes the read to one credential-pool account (TAL-548): a benched account
+     * answers with its local pool state, and every other read uses that account's key.
+     */
     async quota(profileHome, providerRaw, opts = {}) {
         const at = opts.at ?? this.deps.now();
         const computed_at = isoAt(at);
@@ -918,17 +1183,23 @@ export class ProviderCatalog {
         if (!provider)
             return { computed_at, ok: false, provider: null, display_name: null, supported: false, status: 'unavailable', quota: null, message: 'No active provider is configured.' };
         const name = displayName(provider);
+        const credential = opts.credential ?? null;
+        const answer = (ok, status, message, extra = {}) => ({ computed_at, ok, provider, display_name: name, supported: true, status, quota: null, ...extra, message });
+        if (credential && credential.status !== 'available') {
+            return answer(false, 'unavailable', `${name} credential is unavailable. ${str(credential.unavailable_reason)}`.trim(), { account_limits: poolEntryLimits(credential, at) });
+        }
         if (ACCOUNT_USAGE_PROVIDERS.has(provider)) {
             const sidecar = this.deps.sidecar();
             let limits = null;
             // Python `_ACCOUNT_USAGE_CACHE_TTL_SECONDS`: a snapshot answers repeat polls for 45 s unless `refresh` is set.
-            const cacheKey = `${profileHome}\0${provider}`;
+            const cacheKey = `${profileHome}\0${provider}\0${credential?.credential_id ?? ''}`;
             const cached = this.accountUsageCache.get(cacheKey);
             if (cached && !opts.refresh && this.deps.now() - cached.at <= ACCOUNT_USAGE_CACHE_TTL_S)
                 limits = cached.limits;
             else if (sidecar) {
                 try {
-                    const snapshot = (await sidecar.call('usage.account', { profile_home: profileHome, provider, ...(opts.refresh ? { refresh: true } : {}) }, { timeoutMs: 35_000 })).snapshot;
+                    const params = { profile_home: profileHome, provider, ...(opts.refresh ? { refresh: true } : {}), ...(credential ? { credential_id: credential.credential_id } : {}) };
+                    const snapshot = (await sidecar.call('usage.account', params, { timeoutMs: 35_000 })).snapshot;
                     if (snapshot)
                         limits = { ...snapshot, title: str(snapshot.title) || 'Account limits', available: snapshot.available && !str(snapshot.unavailable_reason) };
                 }
@@ -941,40 +1212,98 @@ export class ProviderCatalog {
             if (limits)
                 limits = { ...limits, ...normalizeQuotaWindows(limits.windows, at), fetched_at: isoUtc(limits.fetched_at) };
             if (limits?.available)
-                return { computed_at, ok: true, provider, display_name: name, supported: true, status: limits.stale ? 'stale' : 'available', label: limits.title, quota: null, account_limits: limits, message: limits.stale ? `${name} refresh failed; showing last-known account limits.` : `${name} account limits loaded.` };
+                return answer(true, limits.stale ? 'stale' : 'available', limits.stale ? `${name} refresh failed; showing last-known account limits.` : `${name} account limits loaded.`, { label: limits.title, account_limits: limits });
             const reason = str(limits?.unavailable_reason).trim();
-            return { computed_at, ok: false, provider, display_name: name, supported: true, status: 'unavailable', quota: null, account_limits: limits, message: reason ? `${name} account limits are unavailable. ${reason}` : `${name} account limits are unavailable. Confirm provider authentication and try again.` };
+            return answer(false, 'unavailable', reason ? `${name} account limits are unavailable. ${reason}` : `${name} account limits are unavailable. Confirm provider authentication and try again.`, { account_limits: limits });
+        }
+        if (provider === 'openrouter' || provider === 'deepseek' || provider === 'opencode-go') {
+            const apiKey = this.apiKeyFor(provider, profileHome, config);
+            const key = credential ? { credential_id: credential.credential_id } : apiKey ? { api_key: apiKey } : null;
+            const read = key ? await this.balance(profileHome, provider, key) : null;
+            const status = !key || read?.status === 'no_key' ? 'no_key' : read?.status === 'ok' ? 'ok' : read?.status === 'http_error' ? read.http_status : null;
+            if (provider === 'openrouter') {
+                if (status === 'no_key')
+                    return answer(false, 'no_key', 'OpenRouter quota status needs an OPENROUTER_API_KEY configured on the server.');
+                if (status === 'ok' && read?.quota) {
+                    // The cost chart follows the configured key, so another pool account's spend never lands in it.
+                    if (!credential || credential.matches_api_key)
+                        this.recordCostSnapshot(profileHome, read.quota, at);
+                    return answer(true, 'available', 'OpenRouter quota status loaded.', { label: 'OpenRouter credits', quota: read.quota });
+                }
+                return status === 401 || status === 403 ? answer(false, 'invalid_key', 'OpenRouter rejected the configured API key.') : answer(false, 'unavailable', 'OpenRouter quota status is temporarily unavailable.');
+            }
+            if (provider === 'deepseek') {
+                if (status === 'no_key')
+                    return answer(false, 'no_key', 'DeepSeek balance needs a DEEPSEEK_API_KEY configured on the server.', { balances: [] });
+                if (status === 'ok' && read) {
+                    const available = read.is_available === true;
+                    return answer(available, available ? 'available' : 'exhausted', available ? 'DeepSeek balance loaded.' : 'DeepSeek balance is exhausted.', { label: 'DeepSeek balance', balances: read.balances });
+                }
+                return status === 401 || status === 403 ? answer(false, 'invalid_key', 'DeepSeek rejected the configured API key.', { balances: [] }) : answer(false, 'unavailable', 'DeepSeek balance is temporarily unavailable.', { balances: [] });
+            }
+            if (status === 'no_key')
+                return answer(false, 'no_key', 'OpenCode Go account limits need an API key configured on the server.', { account_limits: null });
+            if (status === 'ok' && read) {
+                // Python `_sanitize_opencode_go_account_limits`: the rolling, weekly and monthly windows of the Go plan.
+                const windows = read.windows.map((w) => ({ label: OPENCODE_GO_WINDOWS[w.key][0], window_seconds: OPENCODE_GO_WINDOWS[w.key][1], used_percent: w.used_percent, reset_at: w.reset_at, detail: w.rate_limited ? 'Rate limited' : null }));
+                const limits = { provider, source: 'usage_api', title: 'Account limits', plan: 'Go', details: [], available: true, unavailable_reason: null, fetched_at: isoAt(at), ...normalizeQuotaWindows(windows, at) };
+                return answer(true, 'available', 'OpenCode Go account limits loaded.', { label: 'OpenCode Go usage', account_limits: limits });
+            }
+            if (status === 401)
+                return answer(false, 'invalid_key', 'OpenCode Go rejected the configured API key.', { account_limits: null });
+            return answer(false, 'unavailable', status === 403 ? 'OpenCode Go account limits require an active subscription.' : 'OpenCode Go account limits are temporarily unavailable.', { account_limits: null });
         }
-        if (provider === 'openrouter') {
-            const apiKey = this.apiKeyFor('openrouter', profileHome, config);
-            if (!apiKey)
-                return { computed_at, ok: false, provider, display_name: name, supported: true, status: 'no_key', quota: null, message: 'OpenRouter quota status needs an OPENROUTER_API_KEY configured on the server.' };
-            const info = await this.fetchOpenRouterKey(apiKey);
-            if (info.kind === 'ok')
-                return { computed_at, ok: true, provider, display_name: name, supported: true, status: 'available', label: 'OpenRouter credits', quota: info.quota, message: 'OpenRouter quota status loaded.' };
-            const status = info.kind === 'invalid_key' ? 'invalid_key' : 'unavailable';
-            return { computed_at, ok: false, provider, display_name: name, supported: true, status, quota: null, message: status === 'invalid_key' ? 'OpenRouter rejected the configured API key.' : 'OpenRouter quota status is temporarily unavailable.' };
+        // Python `_local_pool_snapshot`: any other provider with a credential pool shows its accounts' local state.
+        const entries = credential ? [credential] : (await this.poolEntries(profileHome, provider, null)) ?? [];
+        if (entries.length) {
+            const limits = credential ? poolEntryLimits(credential, at) : poolLimits(entries, at);
+            return limits.available ? answer(true, 'available', `${name} credential pool status loaded.`, { label: 'Credential pool', account_limits: limits }) : answer(false, 'unavailable', `${name} credential pool: all credentials are unavailable.`, { account_limits: limits });
         }
         return { computed_at, ok: false, provider, display_name: name, supported: false, status: 'unsupported', quota: null, message: `No verified server-side quota or balance endpoint is available for ${name}.` };
     }
-    async fetchOpenRouterKey(apiKey) {
-        const f = this.deps.fetch ?? fetch;
+    /**
+     * TAL-548: the provider's credential-pool accounts as the sidecar reads them locally. Each says whether it holds
+     * `apiKey`, the provider's configured key. Null when the pool is unknown (see `poolLookup`).
+     */
+    poolEntries(profileHome, pid, apiKey) {
+        return this.poolLookup(profileHome, `pool\0${pid}`, async (sidecar) => (await sidecar.call('usage.pool', { profile_home: profileHome, provider: pid, ...(apiKey ? { api_key: apiKey } : {}) })).entries);
+    }
+    /** The last answer of each credential-pool lookup, by profile home and lookup. */
+    lastPoolAnswers = new Map();
+    /**
+     * TAL-548: one credential-pool lookup through the sidecar. A failed lookup answers with the last answer to the same
+     * lookup, else null: an unknown pool, never an empty one, so no pool account is ever reported as removed.
+     */
+    async poolLookup(profileHome, lookup, call) {
+        const key = `${profileHome}\0${lookup}`;
         try {
-            const res = await f(OPENROUTER_KEY_URL, { headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' }, signal: AbortSignal.timeout(QUOTA_TIMEOUT_MS) });
-            if (!res.ok)
-                return { kind: res.status === 401 || res.status === 403 ? 'invalid_key' : 'unavailable' };
-            const raw = await readCapped(res, 256 * 1024);
-            if (!raw)
-                return { kind: 'unavailable' };
-            let payload = JSON.parse(raw.toString('utf8'));
-            if (isDict(payload) && isDict(payload.data))
-                payload = payload.data;
-            const d = dict(payload);
-            const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
-            return { kind: 'ok', quota: { limit_remaining: num(d.limit_remaining), usage: num(d.usage), limit: num(d.limit) }, label: str(d.label).trim() || null };
+            const sidecar = this.deps.sidecar();
+            if (!sidecar)
+                throw new Error('the sidecar is not running');
+            const answer = await call(sidecar);
+            this.lastPoolAnswers.set(key, answer);
+            return answer;
         }
-        catch {
-            return { kind: 'unavailable' };
+        catch (error) {
+            this.deps.log(`[catalog] credential pool lookup ${lookup.replace('\0', ' ')} failed: ${str(error.message)}`);
+            return this.lastPoolAnswers.get(key) ?? null;
+        }
+    }
+    /** TAL-548: the providers whose persisted credential pool holds an added account; none when the sidecar cannot say. */
+    poolProviders(profileHome) {
+        return this.poolLookup(profileHome, 'providers', async (sidecar) => (await sidecar.call('usage.pool_providers', { profile_home: profileHome })).providers);
+    }
+    /** TAL-548: one key-based balance read through the sidecar, which resolves a pool account's key itself; null when it fails. */
+    async balance(profileHome, provider, key) {
+        const sidecar = this.deps.sidecar();
+        if (!sidecar)
+            return null;
+        try {
+            return await sidecar.call('usage.balance', { profile_home: profileHome, provider, ...key }, { timeoutMs: BALANCE_TIMEOUT_MS });
+        }
+        catch (error) {
+            this.deps.log(`[catalog] ${provider} balance failed: ${str(error.message)}`);
+            return null;
         }
     }
     quotaScopeCache = null;
@@ -1010,31 +1339,52 @@ export class ProviderCatalog {
         return `qscope_${createHash('sha256').update(`${this.quotaServerScopeId()}\0${profile}`).digest('hex').slice(0, 32)}`;
     }
     /**
-     * Python `get_provider_quotas`: one source per keyed provider, in the stable-identity envelope the iOS widget persists.
-     * Each source id appears once (two custom providers can share a slug), ordered by provider, account label, then source id.
+     * Python `get_provider_quotas`: the stable-identity envelope the iOS widget persists. A keyed provider is one source per
+     * credential-pool account, else one for its own key (Python `_quota_source_descriptors`, TAL-548). Each source id appears
+     * once (two custom providers can share a slug), ordered by provider, account label, then source id.
      */
     async quotas(profileHome, profile, opts = {}) {
         const at = this.deps.now();
-        const status = await this.providers(profileHome);
+        const { payload: status, pooled: pooledIds } = await this.providerRows(profileHome);
         const active = status.active_provider;
         const scopeId = this.quotaProfileScopeId(profile);
-        // Python `_quota_source_id(profile, provider, "provider")`: the single-credential descriptor per provider.
-        const sourceId = (pid) => `qsrc_${createHash('sha256').update(`${scopeId}\0${pid}\0provider`).digest('hex').slice(0, 32)}`;
-        let descriptors = uniqueQuotaSources(status.providers.filter((p) => p.has_key || p.is_custom).map((p) => ({ source_id: sourceId(str(p.id)), provider_id: str(p.id), provider_label: str(p.display_name) || str(p.id), account_label: str(p.display_name) || str(p.id) })));
+        // Python `_quota_source_id(profile, provider, credential_id)`: a pool account's id, or "provider" for the provider's own key.
+        const sourceId = (pid, credential) => `qsrc_${createHash('sha256').update(`${scopeId}\0${pid}\0${credential}`).digest('hex').slice(0, 32)}`;
+        // A provider configured only through `hermes auth add` has no key in .env or config.yaml, yet its pool accounts are
+        // sources, including a signed-out OAuth provider's. An unknown pool (a failed lookup with no earlier answer) never
+        // reports a requested source as missing.
+        let poolUnknown = pooledIds === null;
+        const pooled = new Set(pooledIds ?? []);
+        const config = await this.deps.config.read(profileHome);
+        const perProvider = await Promise.all(status.providers.filter((p) => p.has_key || p.is_custom || pooled.has(str(p.id))).map(async (p) => {
+            const pid = str(p.id);
+            const label = str(p.display_name) || pid;
+            const apiKey = this.apiKeyFor(pid, profileHome, config);
+            const found = await this.poolEntries(profileHome, pid, apiKey);
+            if (!found)
+                poolUnknown = true;
+            const entries = found ?? [];
+            const accounts = entries.map((e) => ({ source_id: sourceId(pid, e.credential_id), provider_id: pid, provider_label: label, account_label: e.label, credential: e }));
+            // The provider's own key is a source unless a pool account already holds it.
+            const ownKey = !entries.length || (apiKey !== null && !entries.some((e) => e.matches_api_key));
+            return ownKey ? [{ source_id: sourceId(pid, 'provider'), provider_id: pid, provider_label: label, account_label: label, credential: null }, ...accounts] : accounts;
+        }));
+        let descriptors = uniqueQuotaSources(perProvider.flat());
         const requested = str(opts.sourceId).trim() || null;
         if (requested)
             descriptors = descriptors.filter((d) => d.source_id === requested);
+        const thresholds = this.deps.quotaThresholds?.(profile) ?? QUOTA_THRESHOLD_DEFAULTS;
         const sources = await Promise.all(descriptors.map(async (d) => {
-            const q = await this.quota(profileHome, d.provider_id, { refresh: opts.refresh ?? false, at });
+            const q = await this.quota(profileHome, d.provider_id, { refresh: opts.refresh ?? false, at, credential: d.credential });
             const limits = dict(q.account_limits);
-            return {
+            return classifyQuotaSource({
                 source_id: d.source_id, provider_id: d.provider_id, provider_label: d.provider_label, account_label: d.account_label,
                 is_active_provider: d.provider_id === active, supported: q.supported === true, status: str(limits.status) || str(q.status) || 'unavailable',
-                plan: limits.plan ?? null, windows: limits.windows ?? [], pace_window_index: limits.pace_window_index ?? null, session_window_index: limits.session_window_index ?? null, weekly_window_index: limits.weekly_window_index ?? null, quota: q.quota ?? null, balances: q.balances ?? [], details: limits.details ?? [],
+                plan: limits.plan ?? null, windows: (limits.windows ?? []), pace_window_index: (limits.pace_window_index ?? null), session_window_index: limits.session_window_index ?? null, weekly_window_index: limits.weekly_window_index ?? null, quota: q.quota ?? null, balances: q.balances ?? [], details: limits.details ?? [],
                 unavailable_reason: limits.unavailable_reason ?? null, retry_after: limits.retry_after ?? null, fetched_at: limits.fetched_at ?? null, message: q.message ?? null,
-            };
+            }, thresholds);
         }));
-        return { version: 1, computed_at: isoAt(at), scope_id: scopeId, profile_id: profile, active_provider: active, requested_source_id: requested, missing_source: Boolean(requested && !descriptors.length), sources };
+        return { version: 1, computed_at: isoAt(at), scope_id: scopeId, profile_id: profile, active_provider: active, requested_source_id: requested, missing_source: Boolean(requested && !descriptors.length && !poolUnknown), sources };
     }
     /** Python `get_provider_cost_history` (OpenRouter only; daily snapshots under `<home>/cost-snapshots`). */
     async costHistory(profileHome, providerRaw, days) {
@@ -1049,56 +1399,46 @@ export class ProviderCatalog {
         const apiKey = this.apiKeyFor('openrouter', profileHome, config);
         if (!apiKey)
             return { ok: false, provider, display_name: name, supported: true, status: 'no_key', monthly_budget: budget, message: 'OpenRouter cost history needs an OPENROUTER_API_KEY configured on the server.' };
-        const file = join(profileHome, 'cost-snapshots', 'openrouter.json');
-        const read = () => {
-            try {
-                const data = JSON.parse(readFileSync(file, 'utf8'));
-                return (Array.isArray(data.snapshots) ? data.snapshots : []).filter(isDict).map((e) => ({ date: str(e.date).trim(), used: typeof e.used === 'number' ? e.used : null, limit: typeof e.limit === 'number' ? e.limit : null })).filter((e) => e.date).sort((a, b) => (a.date < b.date ? -1 : 1));
-            }
-            catch {
-                return [];
-            }
-        };
-        const deltas = (rows) => {
-            const window = rows.slice(-days);
-            return window.map((e, i) => {
-                let delta = null;
-                const prev = window[i - 1];
-                if (i > 0 && e.used !== null && prev?.used !== null && prev?.used !== undefined) {
-                    delta = e.used - prev.used;
-                    if (delta < 0)
-                        delta = e.used;
-                    delta = Math.abs(delta) < 1e-9 ? 0 : Math.round(delta * 1e6) / 1e6;
-                }
-                return { date: e.date, used: e.used, delta };
-            });
-        };
-        const info = await this.fetchOpenRouterKey(apiKey);
-        if (info.kind !== 'ok') {
-            return { ok: false, provider, display_name: name, supported: true, status: 'unavailable', window_days: days, snapshots: deltas(read()), limit: null, label: null, monthly_budget: budget, message: 'OpenRouter cost history is temporarily unavailable. Showing last known data.' };
+        const info = await this.balance(profileHome, 'openrouter', { api_key: apiKey });
+        if (info?.status !== 'ok' || !info.quota) {
+            return { ok: false, provider, display_name: name, supported: true, status: 'unavailable', window_days: days, ...costHistoryView(this.readCostSnapshots(profileHome), days, budget), limit: null, label: null, monthly_budget: budget, message: 'OpenRouter cost history is temporarily unavailable. Showing last known data.' };
         }
-        let snapshots = read();
+        const snapshots = this.recordCostSnapshot(profileHome, info.quota, this.deps.now());
+        return { ok: true, provider, display_name: name, supported: true, status: 'available', window_days: days, ...costHistoryView(snapshots, days, budget), limit: info.quota.limit, label: info.label ?? 'OpenRouter credits', monthly_budget: budget, message: 'OpenRouter cost history loaded.' };
+    }
+    readCostSnapshots(profileHome) {
+        try {
+            const data = JSON.parse(readFileSync(join(profileHome, 'cost-snapshots', 'openrouter.json'), 'utf8'));
+            return (Array.isArray(data.snapshots) ? data.snapshots : []).filter(isDict).map((e) => ({ date: str(e.date).trim(), used: typeof e.used === 'number' ? e.used : null, limit: typeof e.limit === 'number' ? e.limit : null })).filter((e) => e.date).sort((a, b) => (a.date < b.date ? -1 : 1));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Writes or updates the UTC day's OpenRouter usage snapshot; every successful key read (quota or cost history) records one. */
+    recordCostSnapshot(profileHome, quota, at) {
+        let snapshots = this.readCostSnapshots(profileHome);
         try {
-            const today = new Date().toISOString().slice(0, 10);
-            const usage = info.quota.usage;
-            const limit = info.quota.limit;
+            const today = isoAt(at).slice(0, 10);
+            const used = finite(quota.usage);
+            const limit = finite(quota.limit);
             const existing = snapshots.find((e) => e.date === today);
             if (existing) {
-                existing.used = usage;
+                existing.used = used;
                 existing.limit = limit;
             }
             else
-                snapshots.push({ date: today, used: usage, limit });
+                snapshots.push({ date: today, used, limit });
             snapshots.sort((a, b) => (a.date < b.date ? -1 : 1));
             if (snapshots.length > COST_SNAPSHOT_MAX_DAYS)
                 snapshots = snapshots.slice(-COST_SNAPSHOT_MAX_DAYS);
             mkdirSync(join(profileHome, 'cost-snapshots'), { recursive: true });
-            atomicWriteText(file, JSON.stringify({ provider, snapshots }, null, 2));
+            atomicWriteText(join(profileHome, 'cost-snapshots', 'openrouter.json'), JSON.stringify({ provider: 'openrouter', snapshots }, null, 2));
+            return snapshots;
         }
         catch {
-            snapshots = read();
+            return this.readCostSnapshots(profileHome);
         }
-        return { ok: true, provider, display_name: name, supported: true, status: 'available', window_days: days, snapshots: deltas(snapshots), limit: info.quota.limit, label: info.label ?? 'OpenRouter credits', monthly_budget: budget, message: 'OpenRouter cost history loaded.' };
     }
 }
 export const envFileExists = (profileHome) => existsSync(join(profileHome, '.env'));