@maudecode/talaria-web 1.15.0 → 1.17.2

package/dist/providers/catalog.js

@@ -8,17 +8,17 @@
  * 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';
-/** Python `_model_matches_picker_selection`: same bare id, and the routing hints agree when both name one. */
+/** Python `_model_matches_picker_selection`: same bare id, and the routing hints agree when the selection names one. */
 function modelMatchesPickerSelection(modelId, selected, providerId) {
     const candidate = modelId.trim();
     const sel = selected.trim();
@@ -26,12 +26,80 @@ function modelMatchesPickerSelection(modelId, selected, providerId) {
         return false;
     if (candidate === sel)
         return true;
-    const bare = (v) => (v.startsWith('@') && v.includes(':') ? v.slice(v.indexOf(':') + 1) : v);
-    if (bare(sel) !== bare(candidate))
-        return false;
-    const selProvider = sel.startsWith('@') && sel.includes(':') ? sel.slice(1, sel.indexOf(':')).toLowerCase() : '';
-    const candProvider = candidate.startsWith('@') && candidate.includes(':') ? candidate.slice(1, candidate.indexOf(':')).toLowerCase() : providerId.trim().toLowerCase();
-    return !selProvider || !candProvider || selProvider === candProvider;
+    const [candBare, candProvider] = parseProviderQualifiedModel(candidate) ?? [candidate, providerId.trim()];
+    const [selBare, selProvider] = parseProviderQualifiedModel(sel) ?? [sel, ''];
+    return selBare === candBare && (!selProvider || selProvider.toLowerCase() === candProvider.toLowerCase());
+}
+/** TAL-301: every entry names its routing provider and bare id, split once by `parseProviderQualifiedModel`. */
+function stampModelEntries(models, providerId) {
+    return models.map((m) => {
+        const [bare, provider] = parseProviderQualifiedModel(m.id) ?? [m.id, providerId];
+        return { ...m, bare_id: bare, provider_id: provider };
+    });
+}
+/** TAL-301: the catalog entry a stored `(model, provider)` pair selects, so clients render the pairing instead of computing it. */
+export function catalogOptionId(catalog, model, provider) {
+    const bare = str(model).trim();
+    const pid = str(provider).trim().toLowerCase();
+    if (!bare || !pid)
+        return null;
+    for (const g of catalog.groups)
+        for (const e of [...g.models, ...(g.extra_models ?? [])])
+            if (e.bare_id === bare && str(e.provider_id).toLowerCase() === pid)
+                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) {
@@ -82,20 +150,196 @@ 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-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:`). */
-function unqualifiedModelId(id) {
-    const raw = id.trim();
-    return raw.startsWith('@') && raw.includes(':') ? raw.slice(raw.indexOf(':') + 1) : raw;
-}
+const unqualifiedModelId = (id) => parseProviderQualifiedModel(id)?.[0] ?? id.trim();
 /** Python `_MODEL_PICKER_OVERFLOW_THRESHOLD` / `_MODEL_PICKER_VISIBLE_TARGET`. */
 const MODEL_PICKER_OVERFLOW_THRESHOLD = 25;
 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 = {
+    missing_cli: "This provider's CLI was not found on the server. Install it and sign in, then refresh.",
+    needs_setup: "This provider is not set up yet. Finish its setup in Hermes, then refresh.",
+    not_loaded: 'This provider is installed but could not be loaded. Check it with hermes plugins doctor, then restart Talaria Web.',
+    unavailable: "This provider's setup status is unavailable.",
+};
+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. */
+function roundTo(value, digits) {
+    const scale = 10 ** digits;
+    return (Math.sign(value) * Math.round(Math.abs(value) * scale)) / scale;
+}
+const finite = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+/** ISO-8601 UTC for epoch seconds, without a `.000` fraction. */
+export const isoAt = (seconds) => new Date(seconds * 1000).toISOString().replace('.000Z', 'Z');
+/** ISO-8601 UTC (`…Z`) or null. Accepts the pre-TAL-409 sidecar's `str(datetime)` space form; a zone-less stamp is UTC. */
+export function isoUtc(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    let text = value.trim().replace(' ', 'T');
+    if (text.includes('T') && !/(Z|[+-]\d{2}:?\d{2})$/i.test(text))
+        text += 'Z';
+    const ms = Date.parse(text);
+    return Number.isFinite(ms) ? isoAt(ms / 1000) : null;
+}
+/** The forecast a pace implies: per-hour or per-day budget until reset, and whether the projection empties the window first. */
+export function quotaForecast(pace, remaining) {
+    const daily = pace.minutes_to_reset >= 24 * 60;
+    const margin = pace.projected_minutes_to_empty === null ? null : pace.projected_minutes_to_empty - pace.minutes_to_reset;
+    return {
+        outcome: margin === null || margin >= 0 ? 'safe' : 'warning',
+        budget_unit: daily ? 'day' : 'hour',
+        budget_percent: remaining !== null && pace.minutes_to_reset > 0 ? remaining / (pace.minutes_to_reset / (daily ? 24 * 60 : 60)) : null,
+        depletion_margin_minutes: margin,
+    };
+}
+/**
+ * TAL-409: the one normaliser for account-usage windows (Python `_snapshot_windows_payload` plus the pace math the
+ * App used to run). Blank labels drop; `reset_at` becomes ISO `Z`; each window gets its duration, pace and forecast
+ * as of `nowSeconds`; the indexes name the windows the App shows for pace, session and weekly selections.
+ */
+export function normalizeQuotaWindows(raw, nowSeconds) {
+    const nowMs = nowSeconds * 1000;
+    const windows = [];
+    for (const entry of Array.isArray(raw) ? raw : []) {
+        if (!isDict(entry))
+            continue;
+        const label = str(entry.label).trim();
+        if (!label)
+            continue;
+        const usedRaw = finite(entry.used_percent);
+        const remainingRaw = finite(entry.remaining_percent);
+        const clamp = (v) => Math.min(Math.max(v, 0), 100);
+        const used = usedRaw !== null ? clamp(usedRaw) : remainingRaw !== null ? clamp(100 - remainingRaw) : null;
+        const remaining = used === null ? null : 100 - used;
+        const resetAt = isoUtc(entry.reset_at);
+        const resetMs = resetAt === null ? null : Date.parse(resetAt);
+        const minutesToReset = resetMs === null ? null : Math.max(0, roundTo((resetMs - nowMs) / 60_000, 0));
+        const lower = label.toLowerCase();
+        const providedSeconds = finite(entry.window_seconds);
+        const windowSeconds = providedSeconds
+            ?? (lower.includes('week') ? WEEK_WINDOW_S
+                : lower.includes('5h') ? FIVE_HOUR_WINDOW_S
+                    // A "Session" window is 5h, or the weekly window a provider collapsed into one session bucket.
+                    : lower.includes('session') && minutesToReset !== null ? (minutesToReset > 5 * 60 ? WEEK_WINDOW_S : FIVE_HOUR_WINDOW_S)
+                        : null);
+        let pace = null;
+        if (resetAt !== null && resetMs !== null && minutesToReset !== null && resetMs > nowMs && used !== null && remaining !== null
+            && (windowSeconds === FIVE_HOUR_WINDOW_S || windowSeconds === WEEK_WINDOW_S)) {
+            const windowMinutes = windowSeconds / 60;
+            const elapsed = Math.max(0, windowMinutes - minutesToReset);
+            const expectedRemaining = roundTo(Math.min(Math.max((minutesToReset / windowMinutes) * 100, 0), 100), 1);
+            const expectedUsed = roundTo(100 - expectedRemaining, 1);
+            const usagePerMinute = elapsed > 0 ? used / elapsed : 0;
+            pace = {
+                expected_remaining_percent: expectedRemaining,
+                pace_delta_percent: roundTo(remaining - expectedRemaining, 1),
+                burn_rate: expectedUsed > 0 ? roundTo(used / expectedUsed, 2) : 0,
+                minutes_to_reset: minutesToReset,
+                projected_minutes_to_empty: usagePerMinute > 0 ? roundTo(remaining / usagePerMinute, 0) : null,
+                elapsed_minutes: elapsed,
+                valid_until: resetAt,
+            };
+        }
+        windows.push({
+            label, used_percent: usedRaw, remaining_percent: remaining, reset_at: resetAt, detail: typeof entry.detail === 'string' ? entry.detail : null,
+            window_seconds: windowSeconds, pace, forecast: pace ? quotaForecast(pace, remaining) : null,
+        });
+    }
+    const index = (match) => { const i = windows.findIndex(match); return i < 0 ? null : i; };
+    const labelHas = (needle) => (w) => w.label.toLowerCase().includes(needle);
+    const knownPace = (w) => w.window_seconds === FIVE_HOUR_WINDOW_S || w.window_seconds === WEEK_WINDOW_S || ['week', 'session', '5h'].some((n) => labelHas(n)(w));
+    return {
+        windows,
+        pace_window_index: index(labelHas('week')) ?? index(knownPace),
+        session_window_index: index(labelHas('session')) ?? index(labelHas('5h')),
+        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(' ');
 }
@@ -115,9 +359,7 @@ export function formatOllamaLabel(mid) {
 }
 /** Python `_get_label_for_model`: reuse a known label, else prettify the bare id. */
 export function labelForModel(modelId, groups) {
-    let lookup = modelId;
-    if (lookup.startsWith('@') && lookup.includes(':'))
-        lookup = lookup.slice(lookup.indexOf(':') + 1);
+    const lookup = unqualifiedModelId(modelId);
     const hasScheme = (s) => s.includes('://');
     const norm = (s) => (s.includes('/') && !hasScheme(s) ? s.slice(s.indexOf('/') + 1) : s).replaceAll('-', '.').toLowerCase();
     const target = norm(lookup);
@@ -186,12 +428,44 @@ 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);
+    return sources.filter((q, i) => sources.findIndex((o) => o.source_id === q.source_id) === i)
+        .sort((a, b) => cmp(a.provider_id, b.provider_id) || cmp(a.account_label, b.account_label) || cmp(a.source_id, b.source_id));
+}
 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;
     }
@@ -214,6 +488,86 @@ 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) {
+            this.lastModels.delete(profileHome);
+            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) {
+        const catalog = this.lastModels.get(profileHome);
+        if (!catalog) {
+            void this.warmModelOptions(profileHome);
+            return null;
+        }
+        return catalogOptionId(catalog, model, provider);
+    }
+    /**
+     * 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.currentModels(profileHome))
+            return;
+        try {
+            await this.models(profileHome);
+        }
+        catch { /* fail closed: no option ids */ }
     }
     /**
      * The process-environment value of `name` as a named profile may see it: values `loadStartupEnv` copied from the
@@ -224,7 +578,7 @@ export class ProviderCatalog {
             return undefined;
         return this.deps.env[name];
     }
-    /** Python `_provider_has_key` minus the credential pool (the sidecar answers OAuth/pool state). */
+    /** Python `_provider_has_key` minus the credential pool, which `probeKey` reads from the sidecar. */
     providerHasKey(pid, config, envValues, profileHome) {
         const envVar = providerEnvVar(pid);
         if (envVar) {
@@ -262,7 +616,8 @@ 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';
@@ -307,6 +662,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) {
@@ -321,47 +681,83 @@ export class ProviderCatalog {
     /** 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;
     }
+    /**
+     * TAL-288: the model-provider plugins installed and enabled in this profile, as the sidecar reads them from the Agent.
+     * A failed lookup lists none, so every other provider stays usable; an id that cannot be a provider routing hint is dropped.
+     */
+    async pluginProviders(profileHome) {
+        const sidecar = this.deps.sidecar();
+        if (!sidecar)
+            return [];
+        try {
+            const { providers } = await sidecar.call('plugins.providers', { profile_home: profileHome }, { timeoutMs: PLUGIN_LIST_TIMEOUT_MS });
+            return providers.filter((p, i, all) => /^[a-z0-9][a-z0-9._-]{0,63}$/.test(p.name) && all.findIndex((q) => q.name === p.name) === i);
+        }
+        catch (error) {
+            this.deps.log(`[catalog] plugin providers failed: ${str(error.message)}`);
+            return [];
+        }
+    }
     /** 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
+        // does own a `providers.<id>` config entry.
+        const plugins = (await this.pluginProviders(profileHome)).filter((p) => !known.has(p.name) && !known.has(providerIdentity(p.name)));
+        const pluginIds = new Set(plugins.map((p) => p.name));
         const providersCfg = dict(config.providers);
         for (const key of Object.keys(providersCfg)) {
             const identity = canonicaliseProviderId(key);
-            known.add(known.has(identity) ? identity : key);
+            const id = known.has(identity) ? identity : key;
+            if (!pluginIds.has(id))
+                known.add(id);
         }
         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, []) }));
@@ -377,11 +773,12 @@ 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,
@@ -395,6 +792,17 @@ export class ProviderCatalog {
                 models_total: modelsTotal,
             });
         }
+        // TAL-288: a plugin is selectable only once the Agent reports its setup ready; it never borrows a built-in's key.
+        for (const plugin of plugins) {
+            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, configured: ready,
+                configurable: false, is_oauth: false, is_plugin_provider: true, is_self_hosted: false, is_custom: false, key_source: ready ? 'plugin' : 'none',
+                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,
+            });
+        }
         for (const cp of customProviderEntries(config)) {
             const name = str(cp.name).trim();
             if (!name)
@@ -406,7 +814,7 @@ export class ProviderCatalog {
             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));
             rows.push({
-                id: slug, display_name: name, has_key: hasKey,
+                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: str(cp.api_key).trim() ? 'config_yaml' : 'none',
                 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,
             });
@@ -414,12 +822,16 @@ export class ProviderCatalog {
         // 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));
-        const payload = { providers: rows, active_provider: active };
-        this.providersCache.set(profileHome, { at: this.deps.now(), key: cacheKey, payload });
-        return structuredClone(payload);
+        for (const row of rows)
+            row.models = stampModelEntries(row.models, str(row.id));
+        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);
@@ -462,12 +874,18 @@ export class ProviderCatalog {
             if (canonical && this.providerHasKey(canonical, config, envValues, profileHome))
                 detected.add(canonical);
         }
-        // Python: OAuth providers the Agent reports as logged in join the picker with their live catalog (#1567, #2545).
-        const oauthLoggedIn = new Set();
-        for (const row of (await this.providers(profileHome)).providers)
-            if (row.is_oauth === true && row.has_key === true)
-                oauthLoggedIn.add(str(row.id));
-        for (const pid of oauthLoggedIn)
+        // 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, and providers keyed only through the credential pool (TAL-638).
+        const signedIn = new Set();
+        const pluginNames = new Map();
+        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)
+                pluginNames.set(str(row.id), str(row.display_name) || str(row.id));
+        }
+        for (const pid of signedIn)
             detected.add(pid);
         const fallbackCfg = Array.isArray(config.fallback_providers) ? config.fallback_providers.filter(isDict) : [];
         for (const entry of fallbackCfg) {
@@ -500,7 +918,7 @@ export class ProviderCatalog {
             detected.add(named?.[0] ?? active ?? 'custom');
         }
         const groups = [];
-        for (const pid of [...detected].map((p) => (p.startsWith('custom') ? p : canonicaliseProviderId(p) || p)).filter((v, i, a) => v && a.indexOf(v) === i).sort()) {
+        for (const pid of [...detected].map((p) => (p.startsWith('custom') || pluginNames.has(p) ? p : canonicaliseProviderId(p) || p)).filter((v, i, a) => v && a.indexOf(v) === i).sort()) {
             if (pid.startsWith('custom:')) {
                 const g = namedCustom.get(pid);
                 const models = [...(g?.models ?? [])];
@@ -521,12 +939,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) || oauthLoggedIn.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)
@@ -535,7 +956,7 @@ export class ProviderCatalog {
                 if (!raw.some((m) => m.id === id))
                     raw.push({ id, label: labelForModel(id, groups) });
             if (raw.length)
-                groups.push({ provider: displayName(pid), provider_id: pid, models: applyProviderPrefix(raw, pid, active) });
+                groups.push({ provider: pluginNames.get(pid) ?? displayName(pid), provider_id: pid, models: applyProviderPrefix(raw, pid, active) });
         }
         if (defaultModel) {
             const all = new Set(groups.flatMap((g) => g.models.map((m) => m.id)));
@@ -581,10 +1002,21 @@ export class ProviderCatalog {
             for (const [k, v] of Object.entries(rawAliases))
                 if (k && v)
                     aliases[k.trim()] = str(v).trim();
+        const [defaultBare, defaultProvider] = parseProviderQualifiedModel(defaultModel) ?? [defaultModel, active];
+        const defaults = { active_provider: active, default_model: defaultModel, default_provider_id: defaultProvider, default_bare_id: defaultBare };
         if (!kept.length && defaultModel) {
-            return { active_provider: active, default_model: defaultModel, groups: [{ provider: 'Default', provider_id: active ?? 'default', models: [{ id: defaultModel, label: labelForModel(defaultModel, []) }] }], aliases: {}, configured_model_badges: {} };
+            const providerId = active ?? 'default';
+            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: {} });
         }
-        return { active_provider: active, default_model: defaultModel, groups: kept, aliases, configured_model_badges: this.badges(kept, active, defaultModel, fallbackCfg) };
+        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, { 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, 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. */
     badges(groups, active, defaultModel, fallback) {
@@ -640,7 +1072,7 @@ export class ProviderCatalog {
         if (provider !== 'nous' && ids.length > MODEL_PICKER_OVERFLOW_THRESHOLD)
             ids = ids.slice(0, MODEL_PICKER_VISIBLE_TARGET);
         const annotateFastTier = isOpenAiFamilyProvider(provider);
-        const models = ids.filter(Boolean).map((id) => ({ id, label: labelForModel(id, []), ...(annotateFastTier ? { supports_fast_tier: mainModelSupportsServiceTier(id, provider) } : {}) }));
+        const models = stampModelEntries(ids.filter(Boolean).map((id) => ({ id, label: labelForModel(id, []), ...(annotateFastTier ? { supports_fast_tier: mainModelSupportsServiceTier(id, provider) } : {}) })), provider);
         return { provider, source, models, count: models.length };
     }
     /**
@@ -652,7 +1084,7 @@ export class ProviderCatalog {
         const config = await this.deps.config.read(profileHome);
         const section = modelSection(config);
         const pid = canonicaliseProviderId(provider ?? section.provider) || null;
-        const bare = model.replace(/^@[^:]+:/, '');
+        const bare = unqualifiedModelId(model);
         const positive = (v) => { const n = Math.trunc(Number(v)); return Number.isFinite(n) && n > 0 ? n : null; };
         const fromModels = (models) => {
             if (isDict(models)) {
@@ -675,7 +1107,7 @@ export class ProviderCatalog {
         let baseUrl = '';
         let configContextLength = null;
         const sectionModel = str(section.default || (typeof config.model === 'string' ? config.model : '')).trim();
-        if (sectionModel && [model, bare].includes(sectionModel.replace(/^@[^:]+:/, '')))
+        if (sectionModel && [model, bare].includes(unqualifiedModelId(sectionModel)))
             configContextLength = positive(section.context_length);
         if (!pid || canonicaliseProviderId(section.provider) === pid)
             baseUrl = str(section.base_url).trim();
@@ -708,28 +1140,47 @@ 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);
         const config = await this.deps.config.read(profileHome);
         const provider = (providerRaw ?? activeProviderFromConfig(config) ?? '').trim().toLowerCase();
         if (!provider)
-            return { ok: false, provider: null, display_name: null, supported: false, status: 'unavailable', quota: null, message: 'No active provider is configured.' };
+            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) };
                 }
@@ -738,41 +1189,102 @@ export class ProviderCatalog {
                 }
                 this.accountUsageCache.set(cacheKey, { at: this.deps.now(), limits });
             }
+            // The cache keeps the Agent's raw windows; pace is recomputed as of every response.
+            if (limits)
+                limits = { ...limits, ...normalizeQuotaWindows(limits.windows, at), fetched_at: isoUtc(limits.fetched_at) };
             if (limits?.available)
-                return { 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 { 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.` };
-        }
-        if (provider === 'openrouter') {
-            const apiKey = this.apiKeyFor('openrouter', profileHome, config);
-            if (!apiKey)
-                return { 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 { 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 { 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.' };
-        }
-        return { 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;
+            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 });
+        }
+        // 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}.` };
+    }
+    /**
+     * 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;
@@ -807,28 +1319,53 @@ export class ProviderCatalog {
     quotaProfileScopeId(profile) {
         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. */
+    /**
+     * 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 status = await this.providers(profileHome);
+        const at = this.deps.now();
+        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 = 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) }));
+        // 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 });
+            const q = await this.quota(profileHome, d.provider_id, { refresh: opts.refresh ?? false, at, credential: d.credential });
             const limits = dict(q.account_limits);
-            return {
-                source_id: d.source_id, provider_id: d.provider_id, provider_label: d.provider_label, account_label: d.provider_label,
+            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 ?? [], 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, 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) {
@@ -843,56 +1380,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.' };
+        }
+        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 [];
         }
-        let snapshots = read();
+    }
+    /** 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'));