@maudecode/talaria-web 1.18.0 → 1.20.0

package/dist/providers/catalog.js

@@ -1,15 +1,6 @@
-/**
- * Provider cards, the model picker catalog, live model lists, quotas and cost
- * history (Python `api/providers.py`, the `/api/models` parts of
- * `api/config.py`, `_handle_live_models`).
- *
- * The Agent's own primitives (registry, auth status, live model ids, account
- * usage) come through the sidecar; the static tables and key detection live
- * here. ponytail: one live-id cache with a 24h TTL replaces the Python
- * publisher/provenance machinery; `refresh()` evicts it.
- */
+import { updateDocument } from '../sessions/storage/document.js';
 import { homeDotenvKeys } from '../cli/dotenv.js';
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { atomicWriteText } from '../fs/atomic.js';
@@ -17,7 +8,7 @@ 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';
+import { activeProviderFromConfig, canonicaliseProviderId, configuredModelIds, configuredModelOptions, customProviderEntries, customProviderSlug, dict, effectiveDefaultModel, isDict, modelSection, parseProviderQualifiedModel, providerIdentity, resolveProviderAlias, } from '../config/agent-config.js';
 /** 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();
@@ -133,16 +124,19 @@ export function stampAuxiliarySelections(aux, catalog) {
         const match = provider === 'auto' ? undefined : options.find((o) => o.provider === key && o.bare === model);
         if (match)
             return { value_label: match.label || match.bare, provider_label: match.group, option_id: match.id };
-        const group = catalog.groups.find((g) => canonicaliseProviderId(g.provider_id) === key);
-        return { value_label: model || null, provider_label: provider === 'auto' ? null : group?.provider ?? displayName(provider), option_id: null };
+        return { value_label: model || null, provider_label: provider === 'auto' ? null : providerLabel(catalog, provider), option_id: null };
     };
     // Auto falls back to the main chat model; name the effective one the catalog resolved (a legacy string `model` or a
     // `HERMES_MODEL`-style override never reaches `aux.main`).
     const mainParsed = parseProviderQualifiedModel(catalog.default_model);
     const main = describe(mainParsed?.[1] ?? catalog.active_provider ?? aux.main.provider, mainParsed?.[0] ?? (catalog.default_model || aux.main.model));
-    const tasks = aux.tasks.map((t) => {
-        if ((str(t.provider).trim() || 'auto') === 'auto' && !str(t.model).trim())
-            return { ...t, is_auto: true, value_label: main.value_label, provider_label: main.provider_label, selected_option_id: null, in_catalog: true };
+    const isAuto = (route) => (str(route.provider).trim() || 'auto') === 'auto' && !str(route.model).trim();
+    const tasks = aux.tasks.map(({ effective, ...t }) => {
+        if (isAuto(t)) {
+            // TAL-800: an Auto task that inherits another slot runs on that slot's route, the main model only when it is Auto too.
+            const base = isDict(effective) && !isAuto(effective) ? describe(effective.provider, effective.model) : main;
+            return { ...t, is_auto: true, value_label: base.value_label, provider_label: base.provider_label, selected_option_id: null, in_catalog: true };
+        }
         const pinned = describe(t.provider, t.model);
         return { ...t, is_auto: false, value_label: pinned.value_label, provider_label: pinned.provider_label, selected_option_id: pinned.option_id, in_catalog: pinned.option_id !== null };
     });
@@ -167,7 +161,13 @@ const unqualifiedModelId = (id) => parseProviderQualifiedModel(id)?.[0] ?? id.tr
 const MODEL_PICKER_OVERFLOW_THRESHOLD = 25;
 const MODEL_PICKER_VISIBLE_TARGET = 15;
 const ACCOUNT_USAGE_CACHE_TTL_S = 45;
+/** TAL-807: the oldest account-usage read the picker still shows a quota level from. */
+const PICKER_USAGE_MAX_AGE_S = 600;
+/** TAL-807: how long a picker read waits for a provider's first account-usage read. */
+const PICKER_USAGE_WAIT_MS = 2_000;
 const LIVE_TTL_S = 86_400;
+/** TAL-799: the Agent's `_PROVIDER_MODELS_FALLBACK_TTL`; its placeholder for an unreachable catalog is re-probed soon. */
+const FALLBACK_TTL_S = 60;
 const PROVIDERS_TTL_S = 30;
 /** The sidecar reads a balance endpoint with a 15 s timeout of its own. */
 const BALANCE_TIMEOUT_MS = 20_000;
@@ -343,6 +343,11 @@ export function classifyQuotaSource(source, t) {
         urgency: { remaining: urgency(source.windows[0]).remaining, pace: urgency(source.windows[source.pace_window_index ?? 0]).pace },
     };
 }
+/** A provider's name as the catalog lists it (a named custom endpoint's configured name, a plugin's display name), else its static display name. */
+export function providerLabel(catalog, provider) {
+    const key = canonicaliseProviderId(provider);
+    return catalog?.groups.find((g) => canonicaliseProviderId(g.provider_id) === key)?.provider ?? displayName(provider);
+}
 export function displayName(pid) {
     return PROVIDER_DISPLAY[pid] ?? pid.split('-').map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w)).join(' ');
 }
@@ -391,6 +396,10 @@ function looksLikeCodexOauthToken(value) {
         return false;
     }
 }
+const BALANCE_PROVIDERS = ['openrouter', 'deepseek', 'opencode-go'];
+function isBalanceProvider(pid) {
+    return BALANCE_PROVIDERS.some((provider) => provider === pid);
+}
 function valueCountsAsApiKey(pid, value) {
     const text = str(value).trim();
     if (!text)
@@ -458,9 +467,14 @@ export function uniqueQuotaSources(sources) {
 }
 export class ProviderCatalog {
     deps;
+    scopedKeyRevisions = new Map();
+    scopedKeyAuthority = new Map();
+    modelGenerations = new Map();
+    modelReads = new Map();
+    credentialReads = new Map();
     /** 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). */
+    /** `source`: the `sourceFingerprint` the ids were fetched under; another one makes them stale (TAL-542). `ttl`: seconds they stay fresh. */
     liveIds = new Map();
     liveInflight = new Map();
     /** `pooled`: the fill's `poolProviders` answer, null when unknown (TAL-638). */
@@ -482,15 +496,32 @@ export class ProviderCatalog {
         }
         return { groups: this.liveIds.size, models, age_seconds: oldest === null ? null : Math.max(0, Math.round(this.deps.now() - oldest)) };
     }
-    invalidate(profileHome, provider) {
+    invalidate(profileHome, provider, opts = {}) {
+        // Explicit refresh retires builds without changing the credential identity of confirmed live ids.
+        if (profileHome)
+            this.modelGenerations.set(profileHome, (this.modelGenerations.get(profileHome) ?? 0) + 1);
+        else
+            for (const [home, generation] of this.modelGenerations)
+                this.modelGenerations.set(home, generation + 1);
         for (const key of [...this.liveIds.keys()]) {
             if (profileHome && !key.startsWith(`${profileHome}\0`))
                 continue;
             if (provider && !key.endsWith(`\0${provider}`))
                 continue;
-            this.liveIds.delete(key);
+            if (opts.preserveConfirmed)
+                this.liveIds.get(key).ttl = 0;
+            else
+                this.liveIds.delete(key);
         }
         this.providersCache.clear();
+        for (const key of this.pickerLimitsCache.keys())
+            if (!profileHome || key === profileHome)
+                this.pickerLimitsCache.delete(key);
+        if (opts.preserveConfirmed)
+            return;
+        for (const key of [...this.lastQuotaSources.keys()])
+            if (!profileHome || key.startsWith(`${profileHome}\0`))
+                this.lastQuotaSources.delete(key);
         // 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`))
@@ -514,27 +545,44 @@ export class ProviderCatalog {
         }
         return catalogOptionId(catalog, model, provider);
     }
+    /** TAL-821: `providerLabel` against the last catalog built for this home; a cold home starts building one. */
+    providerLabel(profileHome, provider) {
+        const catalog = this.lastModels.get(profileHome);
+        if (!catalog)
+            void this.warmModelOptions(profileHome);
+        return providerLabel(catalog, 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.
+     * makes both stale. Opaque scoped-key revisions cover external secret sources without exposing their keys.
      */
-    sourceFingerprint(profileHome) {
+    sourceFingerprint(profileHome, includeScoped = true) {
         const stamp = (name) => {
             try {
                 const st = statSync(join(profileHome, name), { bigint: true });
-                return `${String(st.mtimeNs)}:${String(st.size)}:${String(st.ino)}`;
+                return `${String(st.mtimeNs)}:${String(st.ctimeNs)}:${String(st.size)}:${String(st.ino)}`;
             }
             catch {
                 return 'missing';
             }
         };
-        return [this.deps.config.fingerprint(profileHome), ...['.env', 'auth.json', 'plugins'].map(stamp)].join('|');
+        const names = new Set([...Object.values(PROVIDER_ENV_VAR), ...Object.values(PROVIDER_ENV_VAR_ALIASES).flat()]);
+        const config = this.deps.config.peek(profileHome, { refresh: false }) ?? {};
+        for (const cp of [modelSection(config), ...Object.values(dict(config.providers)).filter(isDict), ...customProviderEntries(config)]) {
+            for (const name of [str(cp.key_env).trim(), /^\$\{([^}]+)\}$/.exec(str(cp.api_key).trim())?.[1]])
+                if (name)
+                    names.add(name);
+        }
+        const credentials = [...names].sort().map((name) => [name, this.processEnv(name, profileHome)]);
+        const models = ['HERMES_MODEL', 'OPENAI_MODEL', 'LLM_MODEL'].map((name) => [name, this.deps.env[name]]);
+        const environment = createHash('sha256').update(JSON.stringify([credentials, models, includeScoped ? this.scopedKeyRevisions.get(profileHome) ?? '[]' : '[]'])).digest('hex');
+        return [profileHome, environment, 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;
+        return this.scopedKeyAuthority.get(profileHome) !== false && 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
@@ -543,17 +591,19 @@ export class ProviderCatalog {
      */
     sessionModelRepair(profileHome, model, provider) {
         const catalog = this.currentModels(profileHome, PROVIDERS_TTL_S);
-        if (!catalog) {
-            void this.warmSessionModelRepair(profileHome);
+        const pid = canonicaliseProviderId(provider) || canonicaliseProviderId(catalog?.active_provider);
+        if (!catalog || this.lastModelsMeta.get(profileHome)?.unconfirmed.has(pid))
+            void this.models(profileHome).catch(() => undefined);
+        if (!catalog)
             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.
+     * Explicitly await discovery, or start it in the background from `sessionModelRepair`. Admission never awaits it.
+     * A source that changed while the build awaited makes that build stale, so it is rebuilt once.
      */
     async warmSessionModelRepair(profileHome) {
+        await this.poolProviders(profileHome);
         for (let attempt = 0; attempt < 2 && !this.currentModels(profileHome, PROVIDERS_TTL_S); attempt += 1) {
             try {
                 await this.models(profileHome);
@@ -563,8 +613,14 @@ export class ProviderCatalog {
             }
         }
     }
+    /** TAL-1381: warms this home's catalog once, then answers `modelOptionFor` synchronously for every row of a batch. */
+    async modelOptionResolver(profileHome) {
+        await this.warmModelOptions(profileHome);
+        return (model, provider) => this.modelOptionFor(profileHome, model, provider);
+    }
     /** 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) {
+        await this.poolProviders(profileHome);
         if (this.currentModels(profileHome))
             return;
         try {
@@ -613,18 +669,14 @@ export class ProviderCatalog {
         return false;
     }
     async authStatus(profileHome, pid) {
-        const sidecar = this.deps.sidecar();
-        if (!sidecar)
-            return null;
-        try {
-            return (await sidecar.call('providers.auth_status', { profile_home: profileHome, provider: pid })).status;
-        }
-        catch {
-            return null;
-        }
+        return this.poolLookup(profileHome, `auth\0${pid}`, async (sidecar) => {
+            const { status } = await sidecar.call('providers.auth_status', { profile_home: profileHome, provider: pid });
+            return { logged_in: status.logged_in, key_source: str(status.key_source), error: str(status.error) };
+        });
     }
     /** `pooled`: the providers whose persisted credential pool holds an added account (TAL-638). */
-    async probeKey(profileHome, pid, config, envValues, pooled) {
+    async probeKey(profileHome, pid, config, envValues, pooled, scopedKeys) {
+        let authoritative = true;
         let hasKey = this.providerHasKey(pid, config, envValues, profileHome);
         let isOauth = OAUTH_PROVIDERS.has(pid);
         let keySource = 'none';
@@ -632,7 +684,9 @@ export class ProviderCatalog {
         let removable = false;
         if (isOauth) {
             keySource = 'oauth';
-            const status = await this.authStatus(profileHome, pid);
+            const lookup = await this.authStatus(profileHome, pid);
+            authoritative = lookup.authoritative;
+            const status = lookup.value;
             if (status?.logged_in) {
                 hasKey = true;
                 keySource = str(status.key_source) || 'oauth';
@@ -677,8 +731,16 @@ export class ProviderCatalog {
             hasKey = true;
             keySource = 'credential_pool';
         }
+        else if (isBalanceProvider(pid)) {
+            if (scopedKeys[pid]?.present) {
+                hasKey = true;
+                keySource = 'env';
+            }
+        }
         else if (!providerEnvVar(pid) && /^[a-z][a-z0-9_-]{0,63}$/.test(pid)) {
-            const status = await this.authStatus(profileHome, pid);
+            const lookup = await this.authStatus(profileHome, pid);
+            authoritative = lookup.authoritative;
+            const status = lookup.value;
             if (status?.logged_in) {
                 hasKey = true;
                 const raw = str(status.key_source);
@@ -686,14 +748,21 @@ export class ProviderCatalog {
                 isOauth = true;
             }
         }
-        return { hasKey, keySource, authError, isOauth, removable };
+        return { authoritative, hasKey, keySource, authError, isOauth, removable };
     }
     /** Live model ids from the Agent for one provider, cached per profile home. */
     async liveModelIds(profileHome, pid, opts = {}) {
+        const inputSource = this.sourceFingerprint(profileHome, false);
+        if (!opts.source || opts.source !== this.sourceFingerprint(profileHome))
+            await this.poolProviders(profileHome);
         const key = `${profileHome}\0${pid}`;
-        const source = this.sourceFingerprint(profileHome);
+        const source = inputSource === this.sourceFingerprint(profileHome, false) ? this.sourceFingerprint(profileHome) : inputSource;
         const hit = this.liveIds.get(key);
-        if (hit?.source === source && !opts.force && this.deps.now() - hit.at < LIVE_TTL_S)
+        if (this.scopedKeyAuthority.get(profileHome) === false) {
+            this.liveFailed.add(`${key}\0${source}`);
+            return hit?.source === source ? hit.ids : [];
+        }
+        if (hit?.source === source && !opts.force && this.deps.now() - hit.at < hit.ttl)
             return hit.ids;
         // A lookup started under another source answers for the old endpoint or credential; this one starts its own.
         const flightKey = `${key}\0${source}`;
@@ -704,51 +773,75 @@ export class ProviderCatalog {
         // 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 ?? [];
+            return hit?.source === source && source === this.sourceFingerprint(profileHome) ? 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, 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 ?? []; })
+            .then((r) => {
+            if (source !== this.sourceFingerprint(profileHome)) {
+                this.liveFailed.add(flightKey);
+                return [];
+            }
+            if (r.fallback && hit?.source === source && hit.confirmed) {
+                this.liveFailed.add(flightKey);
+                return hit.ids;
+            }
+            this.liveIds.set(key, { at: this.deps.now(), ids: r.model_ids, source, ttl: r.fallback ? FALLBACK_TTL_S : LIVE_TTL_S, confirmed: !r.fallback });
+            // TAL-799: the Agent's curated placeholder for an unreachable catalog is a failed lookup that still lists models.
+            if (r.fallback)
+                this.liveFailed.add(flightKey);
+            else
+                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?.source === source && source === this.sourceFingerprint(profileHome) ? hit.ids : []; })
             .finally(() => { this.liveInflight.delete(flightKey); });
         this.liveInflight.set(flightKey, run);
         return run;
     }
+    /** Whether the last live lookup for this provider under `source` failed or answered with the Agent's placeholder list. */
+    liveLookupFailed(profileHome, pid, source = this.sourceFingerprint(profileHome)) {
+        return this.liveFailed.has(`${profileHome}\0${pid}\0${source}`);
+    }
     /**
      * 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 {
+        return this.poolLookup(profileHome, 'plugins', async (sidecar) => {
             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 [];
-        }
+        });
+    }
+    /**
+     * TAL-798: the GGUFs staged for the Agent's managed llama.cpp provider, selectable before its server runs (a turn boots
+     * it). Null when none are staged or the listing failed, so every other provider stays usable.
+     */
+    async localModels(profileHome) {
+        return this.poolLookup(profileHome, 'local-models', async (sidecar) => sidecar.call('providers.local_models', { profile_home: profileHome }, { timeoutMs: PLUGIN_LIST_TIMEOUT_MS }));
     }
     /** 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) {
+    async providerRows(profileHome, pool) {
         const config = await this.deps.config.read(profileHome);
         const envValues = loadEnvFile(join(profileHome, '.env'));
-        const cacheKey = JSON.stringify([config, envValues]);
+        pool ??= await this.poolProviders(profileHome);
+        const source = this.sourceFingerprint(profileHome);
+        const cacheKey = source;
         const hit = this.providersCache.get(profileHome);
-        if (hit?.key === cacheKey && this.deps.now() - hit.at < PROVIDERS_TTL_S)
+        if (pool.authoritative && hit?.key === cacheKey && this.deps.now() - hit.at < PROVIDERS_TTL_S)
             return hit;
-        const pooledIds = await this.poolProviders(profileHome);
+        const pooledIds = pool.value?.providers ?? null;
+        const pluginLookup = await this.pluginProviders(profileHome);
+        let authoritative = pool.authoritative && pluginLookup.authoritative;
         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 plugins = (pluginLookup.value ?? []).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)) {
@@ -759,7 +852,8 @@ export class ProviderCatalog {
         }
         const rows = [];
         for (const pid of [...known].sort()) {
-            const probe = await this.probeKey(profileHome, pid, config, envValues, pooled);
+            const probe = await this.probeKey(profileHome, pid, config, envValues, pooled, pool.value?.keys ?? {});
+            authoritative &&= probe.authoritative;
             if (pid === 'openai' && !probe.hasKey && looksLikeCodexOauthToken(str(envValues[providerEnvVar('openai') ?? ''] ?? this.deps.env.OPENAI_API_KEY)))
                 continue;
             const configured = probe.hasKey || selfHostedEndpoint(pid, config);
@@ -768,7 +862,7 @@ export class ProviderCatalog {
             // 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 (configured && (probe.isOauth || pid === 'lmstudio' || pid === 'nous' || !BESPOKE_CATALOG_PROVIDERS.has(pid))) {
-                const live = await this.liveModelIds(profileHome, pid);
+                const live = await this.liveModelIds(profileHome, pid, { source });
                 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, []) }));
                     modelsTotal = live.length;
@@ -843,20 +937,47 @@ export class ProviderCatalog {
             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);
+        authoritative &&= source === this.sourceFingerprint(profileHome);
+        const availability = this.availability(source, authoritative, Boolean(pool.value));
+        const entry = { at: this.deps.now(), key: cacheKey, payload: { providers: rows, active_provider: active, availability }, pooled: pooledIds };
+        if (authoritative)
+            this.providersCache.set(profileHome, entry);
         return entry;
     }
     /** Python `get_available_models` (static catalog + live ids for keyed providers). */
-    async models(profileHome) {
+    async models(profileHome, attempt = 0) {
+        const generation = this.modelGenerations.get(profileHome) ?? 0;
+        this.modelGenerations.set(profileHome, generation);
+        const inputSource = this.sourceFingerprint(profileHome, false);
+        const pool = await this.poolProviders(profileHome);
+        if (generation !== this.modelGenerations.get(profileHome) || inputSource !== this.sourceFingerprint(profileHome, false)) {
+            if (attempt === 0)
+                return this.models(profileHome, 1);
+            throw new Error('Provider configuration changed during catalog lookup. Try again.');
+        }
         const source = this.sourceFingerprint(profileHome);
+        const key = `${source}\0${generation}`;
+        const pending = this.modelReads.get(key);
+        if (pending)
+            return structuredClone(await pending);
+        const read = this.buildModels(profileHome, pool, source, generation, attempt).finally(() => { this.modelReads.delete(key); });
+        this.modelReads.set(key, read);
+        return structuredClone(await read);
+    }
+    async buildModels(profileHome, pool, source, generation, attempt) {
+        const providerState = (await this.providerRows(profileHome, pool)).payload;
         const unconfirmed = new Set();
         const config = await this.deps.config.read(profileHome);
         const envValues = loadEnvFile(join(profileHome, '.env'));
-        const active = activeProviderFromConfig(config);
         const model = modelSection(config);
         const defaultModel = effectiveDefaultModel(config, this.deps.env);
         const cfgBaseUrl = str(model.base_url).trim();
+        const localLookup = await this.localModels(profileHome);
+        const local = localLookup.value?.models.length ? localLookup.value : null;
+        const configured = activeProviderFromConfig(config);
+        // A `custom` main model at the running local server's endpoint is that server: its Local group owns the selection.
+        const atLocalServer = configured === 'custom' && Boolean(cfgBaseUrl) && cfgBaseUrl.replace(/\/+$/, '') === str(local?.current_endpoint).replace(/\/+$/, '');
+        const active = local && atLocalServer ? local.provider_id : configured;
         const detected = new Set();
         const configuredIds = new Map();
         const append = (pid, id) => {
@@ -870,6 +991,8 @@ export class ProviderCatalog {
         };
         if (active)
             detected.add(active);
+        if (local)
+            detected.add(local.provider_id);
         const providersCfg = dict(config.providers);
         const rawKeyFor = new Map();
         for (const [key, value] of Object.entries(providersCfg)) {
@@ -897,8 +1020,8 @@ export class ProviderCatalog {
         // 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'))
+        for (const row of providerState.providers) {
+            if (row.has_key !== true || (row.is_oauth !== true && row.is_plugin_provider !== true && row.key_source !== 'credential_pool' && row.key_source !== 'env'))
                 continue;
             signedIn.add(str(row.id));
             if (row.is_plugin_provider === true)
@@ -936,8 +1059,15 @@ export class ProviderCatalog {
             const named = [...namedCustom.entries()].find(([, v]) => customProviderEntries(config).some((e) => customProviderSlug(e.name) === customProviderSlug(v.name) && str(e.base_url).trim().replace(/\/+$/, '') === cfgBaseUrl.replace(/\/+$/, '')));
             detected.add(named?.[0] ?? active ?? 'custom');
         }
+        // TAL-911: Agent pickers drop `model_catalog.excluded_providers` under any of their aliases, the active provider included.
+        const excludedCfg = dict(config.model_catalog).excluded_providers;
+        const excluded = new Set(Array.isArray(excludedCfg) ? excludedCfg.map(providerIdentity).filter(Boolean) : []);
+        const isExcluded = (pid) => excluded.has(providerIdentity(pid));
+        const pickerDefault = isExcluded(active) || isExcluded(parseProviderQualifiedModel(defaultModel)?.[1]) ? '' : defaultModel;
         const groups = [];
         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 (isExcluded(pid))
+                continue;
             if (pid.startsWith('custom:')) {
                 const g = namedCustom.get(pid);
                 const models = [...(g?.models ?? [])];
@@ -945,6 +1075,11 @@ export class ProviderCatalog {
                     groups.push({ provider: g?.name ?? pid.replace('custom:', ''), provider_id: pid, models: applyProviderPrefix(models, pid, active) });
                 continue;
             }
+            if (pid === local?.provider_id) {
+                // A GGUF's id is its file name, quant tag included (`Q4_K_M`); prettifying would mangle it.
+                groups.push({ provider: 'Local', provider_id: pid, models: applyProviderPrefix(local.models.map((id) => ({ id, label: id })), pid, active) });
+                continue;
+            }
             if (pid === 'custom') {
                 const models = [...customModels];
                 for (const id of configuredIds.get(pid) ?? [])
@@ -956,20 +1091,25 @@ export class ProviderCatalog {
             }
             const providerCfg = dict(providersCfg[rawKeyFor.get(pid) ?? pid]);
             let raw = [];
+            let allowFallback = false;
             if ('models' in providerCfg && providerCfg.models_discovered !== true)
                 raw = configuredModelOptions(providerCfg.models);
-            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}`))
+            if (!raw.length) {
+                // TAL-799: a provider without credentials lists the Agent's curated catalog too; the static tables only cover a missing sidecar.
+                const keyed = this.providerHasKey(pid, config, envValues, profileHome) || selfHostedEndpoint(pid, config) || signedIn.has(pid);
+                const live = await this.liveModelIds(profileHome, pid, { source });
+                const failed = this.liveLookupFailed(profileHome, pid, source);
+                // TAL-542: a failed lookup, or a curated list no account confirmed, leaves this group unconfirmed, so the stale-model repair never trusts it.
+                allowFallback = failed || !keyed;
+                if (allowFallback)
                     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}\0${source}`))
+                else if (keyed && pid === 'nous' && !failed)
                     continue;
             }
-            if (!raw.length)
+            if (!raw.length && allowFallback)
                 raw = pid === 'openrouter' ? FALLBACK_MODELS.map((m) => ({ id: m.id, label: m.label })) : [...(PROVIDER_MODELS[pid] ?? [])];
             for (const id of configuredIds.get(pid) ?? [])
                 if (!raw.some((m) => m.id === id))
@@ -977,7 +1117,7 @@ export class ProviderCatalog {
             if (raw.length)
                 groups.push({ provider: pluginNames.get(pid) ?? displayName(pid), provider_id: pid, models: applyProviderPrefix(raw, pid, active) });
         }
-        if (defaultModel) {
+        if (pickerDefault) {
             const all = new Set(groups.flatMap((g) => g.models.map((m) => m.id)));
             if (!all.has(defaultModel) && !all.has(`@${active ?? ''}:${defaultModel}`)) {
                 const label = labelForModel(defaultModel, groups);
@@ -1010,11 +1150,6 @@ export class ProviderCatalog {
             }
         const rank = (g) => (g.provider_id === active ? 0 : g.provider_id.startsWith('custom:') ? 1 : withKeys.has(g.provider_id) ? 2 : 3);
         kept.sort((a, b) => rank(a) - rank(b) || (a.provider_id < b.provider_id ? -1 : a.provider_id > b.provider_id ? 1 : 0));
-        for (const g of kept)
-            if (isOpenAiFamilyProvider(g.provider_id))
-                for (const m of g.models)
-                    if (/^(@[^:]+:)?(openai\/)?(gpt-5|o[0-9])/.test(m.id))
-                        m.supports_fast_tier = true;
         const aliases = {};
         const rawAliases = model.aliases;
         if (isDict(rawAliases))
@@ -1022,19 +1157,136 @@ export class ProviderCatalog {
                 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) {
+        if (source !== this.sourceFingerprint(profileHome)) {
+            if (attempt === 0)
+                return this.models(profileHome, 1);
+            throw new Error('Provider configuration changed during catalog lookup. Try again.');
+        }
+        if (!providerState.availability.authoritative || !localLookup.authoritative)
+            for (const g of kept)
+                unconfirmed.add(g.provider_id);
+        const previous = this.currentModels(profileHome);
+        const availability = this.availability(source, providerState.availability.authoritative && localLookup.authoritative && !unconfirmed.size && source === this.sourceFingerprint(profileHome), previous?.availability?.status === 'available' || previous?.availability?.status === 'stale');
+        for (const g of kept)
+            g.availability = this.availability(source, !unconfirmed.has(g.provider_id) && providerState.availability.authoritative, Boolean(previous?.groups.some((old) => old.provider_id === g.provider_id && old.availability?.status !== 'unavailable')));
+        const defaults = { availability, active_provider: active, default_model: defaultModel, default_provider_id: defaultProvider, default_bare_id: defaultBare };
+        if (!kept.length && pickerDefault) {
             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 this.remember(profileHome, { source, generation, unconfirmed, attempt }, { ...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, { source, unconfirmed }, { ...defaults, groups: stamped, aliases, configured_model_badges: this.badges(kept, active, defaultModel, fallbackCfg) });
+        return this.remember(profileHome, { source, generation, unconfirmed, attempt }, { ...defaults, groups: stamped, aliases, configured_model_badges: this.badges(kept, active, defaultModel, fallbackCfg) });
+    }
+    pickerLimitsCache = new Map();
+    /** Bounded, shared pool-limit reads; a warm picker serves its snapshot during refresh. */
+    async pickerLimits(profileHome, providers) {
+        const fingerprint = this.sourceFingerprint(profileHome);
+        const source = JSON.stringify([fingerprint, providers]);
+        let cached = this.pickerLimitsCache.get(profileHome);
+        if (cached?.source !== source) {
+            cached = { source, limits: {} };
+            this.pickerLimitsCache.set(profileHome, cached);
+        }
+        const entry = cached;
+        if ((entry.at === undefined || this.deps.now() - entry.at >= ACCOUNT_USAGE_CACHE_TTL_S) && !entry.read) {
+            entry.read = (async () => {
+                try {
+                    const sidecar = this.deps.sidecar();
+                    entry.limits = sidecar ? (await sidecar.call('usage.limits', { profile_home: profileHome, providers }, { timeoutMs: 3_000 })).limits : {};
+                }
+                catch (error) {
+                    entry.limits = {};
+                    this.deps.log(`[catalog] pool limits failed: ${str(error.message)}`);
+                }
+                entry.at = this.deps.now();
+            })().finally(() => { delete entry.read; });
+        }
+        if (entry.at === undefined)
+            await entry.read;
+        return fingerprint === this.sourceFingerprint(profileHome) && this.pickerLimitsCache.get(profileHome) === entry ? entry.limits : {};
+    }
+    /** TAL-807: the picker adds pool limits and quota levels without storing them in the model catalog. */
+    async pickerModels(profileHome, profile) {
+        const catalog = await this.models(profileHome);
+        const entries = (g) => [...g.models, ...(g.extra_models ?? [])];
+        const providers = catalog.groups.map((g) => ({ slug: g.provider_id, models: entries(g).map((e) => e.bare_id ?? e.id) }));
+        const limits = await this.pickerLimits(profileHome, providers);
+        const active = (resetsAt) => Date.parse(resetsAt) / 1000 > this.deps.now();
+        for (const g of catalog.groups) {
+            const limit = limits[g.provider_id];
+            if (limit?.scope === 'account' && active(limit.resets_at))
+                g.limit = limit;
+            if (limit?.scope === 'models') {
+                // The sidecar answers by bare id; the picker names entries by id.
+                const cooled = {};
+                for (const e of entries(g)) {
+                    const resetsAt = limit.models[e.bare_id ?? e.id];
+                    if (resetsAt && active(resetsAt)) {
+                        e.limit = { scope: 'model', resets_at: resetsAt };
+                        cooled[e.id] = resetsAt;
+                    }
+                }
+                if (Object.keys(cooled).length)
+                    g.limit = { scope: 'models', models: cooled };
+            }
+        }
+        const thresholds = (await this.deps.quotaThresholds?.(profile)) ?? QUOTA_THRESHOLD_DEFAULTS;
+        // An account limit already says the login is out; the quota level would only repeat it.
+        const levels = await Promise.all(catalog.groups.map((g) => (g.limit?.scope === 'account' ? Promise.resolve(null) : this.pickerQuotaLevel(profileHome, g.provider_id, thresholds))));
+        catalog.groups.forEach((g, i) => { const level = levels[i]; if (level)
+            g.quota_level = level; });
+        return catalog;
+    }
+    /** TAL-807: account-usage reads the picker started, by `accountUsageCache` key. */
+    pickerUsageReads = new Map();
+    /**
+     * TAL-807: the TAL-411 `remaining` level of the tightest account-scope window in the provider's cached account-usage
+     * read; a model-family window (Opus or Sonnet weekly) never counts. A read past the cache TTL starts a new one, which
+     * the picker waits for only when it has no read at all, and then for at most `PICKER_USAGE_WAIT_MS`; one past
+     * `PICKER_USAGE_MAX_AGE_S` shows nothing.
+     */
+    async pickerQuotaLevel(profileHome, pid, t) {
+        if (!ACCOUNT_USAGE_PROVIDERS.has(pid))
+            return null;
+        const key = `${profileHome}\0${pid}\0`;
+        let cached = this.accountUsageCache.get(key);
+        if (cached?.source !== this.sourceFingerprint(profileHome))
+            cached = undefined;
+        if (!cached || this.deps.now() - cached.at > ACCOUNT_USAGE_CACHE_TTL_S) {
+            let read = this.pickerUsageReads.get(key);
+            if (!read) {
+                read = this.quota(profileHome, pid).then(() => undefined, () => undefined).finally(() => this.pickerUsageReads.delete(key));
+                this.pickerUsageReads.set(key, read);
+            }
+            if (!cached) {
+                let timer;
+                await Promise.race([read, new Promise((resolve) => { timer = setTimeout(resolve, PICKER_USAGE_WAIT_MS); })]);
+                clearTimeout(timer);
+                cached = this.accountUsageCache.get(key);
+            }
+        }
+        const limits = cached?.limits;
+        if (cached?.source !== this.sourceFingerprint(profileHome) || !limits?.available || this.deps.now() - cached.at > PICKER_USAGE_MAX_AGE_S)
+            return null;
+        const raw = (Array.isArray(limits.windows) ? limits.windows : []).filter((w) => isDict(w) && w.scope !== 'model');
+        const tightest = normalizeQuotaWindows(raw, this.deps.now()).windows
+            .reduce((a, w) => (w.remaining_percent !== null && w.remaining_percent < (a?.remaining_percent ?? Infinity) ? w : a), undefined);
+        return tightest ? quotaLevel(tightest, limits.stale ? 'stale' : 'available', 'remaining', t) : null;
     }
     /** Stamps the default's entry id and keeps the catalog for `modelOptionFor`. */
-    remember(profileHome, meta, catalog) {
+    async remember(profileHome, meta, catalog) {
+        if (catalog.availability)
+            for (const group of catalog.groups)
+                group.availability ??= catalog.availability;
+        await this.stampSpeedTiers(profileHome, catalog.groups.flatMap((g) => [...g.models, ...(g.extra_models ?? [])]));
+        if (meta.generation !== this.modelGenerations.get(profileHome) || meta.source !== this.sourceFingerprint(profileHome)) {
+            if (meta.attempt === 0)
+                return this.models(profileHome, 1);
+            throw new Error('Provider configuration changed during catalog lookup. Try again.');
+        }
         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() });
+        this.lastModelsMeta.set(profileHome, { source: meta.source, unconfirmed: meta.unconfirmed, at: this.deps.now() });
         return structuredClone(catalog);
     }
     /** Python `_configured_model_badges_from_static_catalog`: which picker rows are the main/fallback selections. */
@@ -1066,14 +1318,17 @@ export class ProviderCatalog {
         return badges;
     }
     /** Python `_handle_live_models`. */
-    async liveModels(profileHome, providerRaw) {
+    async liveModels(profileHome, providerRaw, attempt = 0) {
+        const fingerprint = this.sourceFingerprint(profileHome);
         const config = await this.deps.config.read(profileHome);
         let provider = providerRaw.trim().toLowerCase() || str(modelSection(config).provider).trim().toLowerCase();
         if (!provider)
             return { error: 'no_provider', models: [] };
         provider = resolveProviderAlias(provider);
         let ids = await this.liveModelIds(profileHome, provider);
-        let source = 'live';
+        if (fingerprint !== this.sourceFingerprint(profileHome))
+            return attempt === 0 ? this.liveModels(profileHome, providerRaw, 1) : { availability: this.availability(this.sourceFingerprint(profileHome), false, false), provider, source: 'unavailable', models: [], count: 0 };
+        let source = this.liveLookupFailed(profileHome, provider, fingerprint) ? 'fallback' : 'live';
         if (!ids.length) {
             const fromConfig = [];
             if (provider === 'custom' || provider.startsWith('custom:')) {
@@ -1083,16 +1338,33 @@ export class ProviderCatalog {
                         fromConfig.push(...[str(cp.model).trim(), ...configuredModelIds(cp.models)].filter(Boolean));
                 }
             }
-            ids = fromConfig.length ? [...new Set(fromConfig)] : (PROVIDER_MODELS[provider] ?? []).map((m) => m.id);
-            source = fromConfig.length ? 'config' : 'static';
+            if (fromConfig.length) {
+                ids = [...new Set(fromConfig)];
+                source = 'config';
+            }
+            else if (source === 'fallback') {
+                ids = (PROVIDER_MODELS[provider] ?? []).map((m) => m.id);
+                source = 'static';
+            }
         }
-        // Python: the dropdown-enrichment surface keeps the picker's visibility budget (15 rows past 25) and annotates
-        // OpenAI-family rows with `supports_fast_tier`; the answer carries `count`.
         if (provider !== 'nous' && ids.length > MODEL_PICKER_OVERFLOW_THRESHOLD)
             ids = ids.slice(0, MODEL_PICKER_VISIBLE_TARGET);
-        const annotateFastTier = isOpenAiFamilyProvider(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 };
+        const models = stampModelEntries(ids.filter(Boolean).map((id) => ({ id, label: labelForModel(id, []) })), provider);
+        await this.stampSpeedTiers(profileHome, models);
+        if (fingerprint !== this.sourceFingerprint(profileHome))
+            return attempt === 0 ? this.liveModels(profileHome, providerRaw, 1) : { availability: this.availability(this.sourceFingerprint(profileHome), false, false), provider, source: 'unavailable', models: [], count: 0 };
+        return { availability: this.availability(fingerprint, source === 'live' || source === 'config', source === 'fallback' && models.length > 0), provider, source, models, count: models.length };
+    }
+    async stampSpeedTiers(profileHome, entries) {
+        if (!entries.length)
+            return;
+        const config = await this.deps.config.read(profileHome);
+        // An unavailable Agent offers no paid tier; writes still require a successful lookup.
+        const tiers = await this.deps.config.speedTiers(profileHome, config, entries.map((e) => ({ model: e.bare_id ?? e.id, provider: e.provider_id ?? '' }))).catch(() => []);
+        entries.forEach((entry, i) => {
+            entry.supported_speed_tiers = tiers[i] ?? [];
+            entry.supports_fast_tier = entry.supported_speed_tiers.some((t) => t.service_tier === 'priority');
+        });
     }
     /**
      * Python `_resolve_model_context_length` inputs: the effective base URL, key, and any configured window for this
@@ -1155,27 +1427,35 @@ export class ProviderCatalog {
         if (envVar) {
             for (const name of [envVar, ...(PROVIDER_ENV_VAR_ALIASES[pid] ?? [])]) {
                 const v = str(envValues[name] ?? this.processEnv(name, profileHome)).trim();
+                // A reference owns this slot; only the Agent can resolve it before lower-priority keys.
                 if (v)
-                    return v;
+                    return v.startsWith('op://') ? null : v;
             }
         }
         // 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();
+            return str(model.api_key).trim().startsWith('op://') ? null : 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 str(value.api_key).trim().startsWith('op://') ? null : str(value.api_key).trim();
         }
         return null;
     }
+    /** A raw key or the names the Agent resolves inside the profile's secret scope. */
+    usageKey(pid, apiKey) {
+        const envVar = providerEnvVar(pid);
+        return apiKey ? { api_key: apiKey } : { env_vars: envVar ? [envVar, ...(PROVIDER_ENV_VAR_ALIASES[pid] ?? [])] : [] };
+    }
     /** Account-usage snapshots by profile home, provider, and pool account. */
     accountUsageCache = new Map();
+    quotaReadSequence = 0;
     /**
      * 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 sequence = opts.sequence ?? ++this.quotaReadSequence;
         const at = opts.at ?? this.deps.now();
         const computed_at = isoAt(at);
         const config = await this.deps.config.read(profileHome);
@@ -1193,7 +1473,9 @@ export class ProviderCatalog {
             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}\0${credential?.credential_id ?? ''}`;
-            const cached = this.accountUsageCache.get(cacheKey);
+            const hit = this.accountUsageCache.get(cacheKey);
+            const source = this.sourceFingerprint(profileHome);
+            const cached = hit?.source === source ? hit : undefined;
             if (cached && !opts.refresh && this.deps.now() - cached.at <= ACCOUNT_USAGE_CACHE_TTL_S)
                 limits = cached.limits;
             else if (sidecar) {
@@ -1206,7 +1488,12 @@ export class ProviderCatalog {
                 catch (error) {
                     limits = { available: false, unavailable_reason: str(error.message), windows: [], details: [] };
                 }
-                this.accountUsageCache.set(cacheKey, { at: this.deps.now(), limits });
+                if (source === this.sourceFingerprint(profileHome)) {
+                    if ((this.accountUsageCache.get(cacheKey)?.sequence ?? -1) <= sequence)
+                        this.accountUsageCache.set(cacheKey, { at: this.deps.now(), limits, source, sequence });
+                }
+                else
+                    limits = null;
             }
             // The cache keeps the Agent's raw windows; pace is recomputed as of every response.
             if (limits)
@@ -1216,11 +1503,11 @@ export class ProviderCatalog {
             const reason = str(limits?.unavailable_reason).trim();
             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') {
+        if (isBalanceProvider(provider)) {
             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;
+            const key = credential ? { credential_id: credential.credential_id } : this.usageKey(provider, apiKey);
+            const read = await this.balance(profileHome, provider, key);
+            const status = 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.');
@@ -1254,7 +1541,7 @@ export class ProviderCatalog {
             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)) ?? [];
+        const entries = credential ? [credential] : (await this.poolEntries(profileHome, provider, null)).value?.entries ?? [];
         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 });
@@ -1266,7 +1553,7 @@ export class ProviderCatalog {
      * `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);
+        return this.poolLookup(profileHome, `pool\0${pid}`, (sidecar) => sidecar.call('usage.pool', { profile_home: profileHome, provider: pid, ...this.usageKey(pid, apiKey) }));
     }
     /** The last answer of each credential-pool lookup, by profile home and lookup. */
     lastPoolAnswers = new Map();
@@ -1275,23 +1562,48 @@ export class ProviderCatalog {
      * 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 source = this.sourceFingerprint(profileHome);
         const key = `${profileHome}\0${lookup}`;
         try {
             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;
+            if (source !== this.sourceFingerprint(profileHome))
+                return { value: null, authoritative: false };
+            this.lastPoolAnswers.set(key, { source, value: answer });
+            return { value: answer, authoritative: true };
         }
         catch (error) {
             this.deps.log(`[catalog] credential pool lookup ${lookup.replace('\0', ' ')} failed: ${str(error.message)}`);
-            return this.lastPoolAnswers.get(key) ?? null;
+            const hit = this.lastPoolAnswers.get(key);
+            return { value: hit?.source === source && source === this.sourceFingerprint(profileHome) ? hit.value : null, authoritative: false };
         }
     }
-    /** TAL-548: the providers whose persisted credential pool holds an added account; none when the sidecar cannot say. */
+    /** One shared read of pool membership and scoped key revisions before reusing catalog data. */
     poolProviders(profileHome) {
-        return this.poolLookup(profileHome, 'providers', async (sidecar) => (await sidecar.call('usage.pool_providers', { profile_home: profileHome })).providers);
+        const inputSource = this.sourceFingerprint(profileHome, false);
+        const readKey = this.sourceFingerprint(profileHome);
+        const pending = this.credentialReads.get(readKey);
+        if (pending)
+            return pending;
+        const read = (async () => {
+            const config = await this.deps.config.read(profileHome);
+            const key_envs = Object.fromEntries(BALANCE_PROVIDERS.filter((pid) => this.apiKeyFor(pid, profileHome, config) === null).map((pid) => [pid, this.usageKey(pid, null).env_vars ?? []]));
+            const result = await this.poolLookup(profileHome, 'providers', (sidecar) => sidecar.call('usage.pool_providers', { profile_home: profileHome, key_envs }));
+            if (inputSource !== this.sourceFingerprint(profileHome, false))
+                return { value: null, authoritative: false };
+            this.scopedKeyAuthority.set(profileHome, result.authoritative);
+            if (result.authoritative)
+                this.scopedKeyRevisions.set(profileHome, JSON.stringify(Object.entries(result.value?.keys ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([pid, state]) => [pid, state.revision])));
+            return result;
+        })().catch(() => {
+            if (inputSource === this.sourceFingerprint(profileHome, false))
+                this.scopedKeyAuthority.set(profileHome, false);
+            return { value: null, authoritative: false };
+        }).finally(() => { this.credentialReads.delete(readKey); });
+        this.credentialReads.set(readKey, read);
+        return read;
     }
     /** 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) {
@@ -1308,52 +1620,46 @@ export class ProviderCatalog {
     }
     quotaScopeCache = null;
     /** Python `_quota_server_scope_id`: a 32-hex id persisted at `<state>/.quota_scope_id` (created atomically once). */
-    quotaServerScopeId() {
+    async quotaServerScopeId() {
         if (this.quotaScopeCache)
             return this.quotaScopeCache;
-        const dir = this.deps.stateDir;
-        if (!dir) {
+        const documents = this.deps.documents;
+        if (!documents) {
             this.quotaScopeCache = randomUUID().replaceAll('-', '');
             return this.quotaScopeCache;
         }
-        const path = join(dir, '.quota_scope_id');
-        let stored = '';
-        try {
-            stored = readFileSync(path, 'utf8').trim().toLowerCase();
-        }
-        catch {
-            stored = '';
-        }
-        if (!/^[0-9a-f]{32}$/.test(stored)) {
-            stored = randomUUID().replaceAll('-', '');
-            mkdirSync(dir, { recursive: true });
-            const temporary = `${path}.tmp.${String(process.pid)}`;
-            writeFileSync(temporary, `${stored}\n`, 'utf8');
-            renameSync(temporary, path);
-        }
+        const stored = await updateDocument(documents, 'catalog', 'quota-scope', (value) => {
+            const previous = typeof value === 'string' ? value.trim().toLowerCase() : '';
+            if (/^[0-9a-f]{32}$/.test(previous))
+                return { value, result: previous };
+            const id = randomUUID().replaceAll('-', '');
+            return { value: `${id}\n`, result: id };
+        });
         this.quotaScopeCache = stored;
         return stored;
     }
     /** Python `_quota_profile_scope_id`. */
-    quotaProfileScopeId(profile) {
-        return `qscope_${createHash('sha256').update(`${this.quotaServerScopeId()}\0${profile}`).digest('hex').slice(0, 32)}`;
+    async quotaProfileScopeId(profile) {
+        return `qscope_${createHash('sha256').update(`${(await this.quotaServerScopeId())}\0${profile}`).digest('hex').slice(0, 32)}`;
     }
     /**
      * 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 = {}) {
+    async quotas(profileHome, profile, opts = {}, attempt = 0) {
+        const sequence = ++this.quotaReadSequence;
+        const source = this.sourceFingerprint(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);
+        const scopeId = (await this.quotaProfileScopeId(profile));
         // 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;
+        let poolUnknown = !status.availability.authoritative;
         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) => {
@@ -1361,30 +1667,80 @@ export class ProviderCatalog {
             const label = str(p.display_name) || pid;
             const apiKey = this.apiKeyFor(pid, profileHome, config);
             const found = await this.poolEntries(profileHome, pid, apiKey);
-            if (!found)
+            if (!found.authoritative)
                 poolUnknown = true;
-            const entries = found ?? [];
+            const entries = found.value?.entries ?? [];
             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));
+            const ownKey = found.authoritative && ((!entries.length && (p.has_key === true || p.is_custom === true) && !pooled.has(pid)) || ((apiKey !== null || found.value?.has_api_key === true) && !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 membership = new Set(descriptors.map((d) => d.source_id));
         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, credential: d.credential });
+        const thresholds = (await this.deps.quotaThresholds?.(profile)) ?? QUOTA_THRESHOLD_DEFAULTS;
+        let sources = await Promise.all(descriptors.map(async (d) => {
+            const q = await this.quota(profileHome, d.provider_id, { refresh: opts.refresh ?? false, at, credential: d.credential, sequence });
             const limits = dict(q.account_limits);
             return classifyQuotaSource({
-                source_id: d.source_id, provider_id: d.provider_id, provider_label: d.provider_label, account_label: d.account_label,
+                computed_at: isoAt(at), 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 ?? [],
                 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 && !poolUnknown), sources };
+        if (source !== this.sourceFingerprint(profileHome) && attempt === 0)
+            return this.quotas(profileHome, profile, opts, 1);
+        poolUnknown ||= source !== this.sourceFingerprint(profileHome);
+        const cacheKey = `${profileHome}\0${scopeId}`;
+        const cached = source === this.sourceFingerprint(profileHome) ? this.lastQuotaSources.get(cacheKey) : undefined;
+        const prior = cached?.source === source ? cached : undefined;
+        const previous = prior?.sources ?? [];
+        if (!poolUnknown) {
+            sources = sources.map((s) => {
+                const old = previous.find((p) => p.source_id === s.source_id);
+                return s.status === 'unavailable' && old ? this.staleQuotaSource(old, str(s.unavailable_reason || s.message)) : s;
+            });
+            const latestMembership = prior && prior.sequence > sequence ? prior.membership : membership;
+            const sourceSequences = new Map(prior?.sourceSequences);
+            const merged = new Map(previous.filter((s) => latestMembership.has(str(s.source_id))).map((s) => [str(s.source_id), s]));
+            for (const value of sources) {
+                const id = str(value.source_id);
+                if (!latestMembership.has(id) || (sourceSequences.get(id) ?? -1) > sequence)
+                    continue;
+                merged.set(id, value);
+                sourceSequences.set(id, sequence);
+            }
+            for (const id of sourceSequences.keys())
+                if (!latestMembership.has(id))
+                    sourceSequences.delete(id);
+            const snapshot = uniqueQuotaSources([...merged.values()]);
+            this.lastQuotaSources.set(cacheKey, { source, sequence: Math.max(sequence, prior?.sequence ?? -1), membership: latestMembership, sources: snapshot, sourceSequences });
+            // A delayed read answers with the newest confirmed projection, including confirmed removals.
+            sources = snapshot.filter((s) => !requested || s.source_id === requested);
+        }
+        else {
+            sources = previous.filter((s) => !requested || s.source_id === requested).map((s) => this.staleQuotaSource(s));
+        }
+        const currentSource = this.sourceFingerprint(profileHome);
+        if (currentSource !== source) {
+            poolUnknown = true;
+            sources = [];
+        }
+        const latestMembership = this.lastQuotaSources.get(cacheKey)?.membership;
+        const availability = this.availability(currentSource, !poolUnknown, sources.length > 0);
+        return { availability, version: 1, computed_at: isoAt(at), scope_id: scopeId, profile_id: profile, active_provider: active, requested_source_id: requested, missing_source: Boolean(requested && !poolUnknown && !latestMembership?.has(requested)), sources };
+    }
+    lastQuotaSources = new Map();
+    staleQuotaSource(source, reason = 'Provider data is temporarily unavailable. Showing last-confirmed data.') {
+        return { ...source, status: 'stale', unavailable_reason: reason, message: reason, urgency: { remaining: 'stale', pace: 'stale' } };
+    }
+    availability(source, authoritative, cached) {
+        return { authoritative, status: authoritative ? 'available' : cached ? 'stale' : 'unavailable',
+            unavailable_reason: authoritative ? null : cached ? 'Provider data is temporarily unavailable. Showing last-confirmed data.' : 'Provider data is temporarily unavailable. Try again.',
+            generation: createHash('sha256').update(source).digest('hex') };
     }
     /** Python `get_provider_cost_history` (OpenRouter only; daily snapshots under `<home>/cost-snapshots`). */
     async costHistory(profileHome, providerRaw, days) {
@@ -1397,9 +1753,9 @@ export class ProviderCatalog {
         const budget = this.deps.costBudget();
         const config = await this.deps.config.read(profileHome);
         const apiKey = this.apiKeyFor('openrouter', profileHome, config);
-        if (!apiKey)
+        const info = await this.balance(profileHome, 'openrouter', this.usageKey('openrouter', apiKey));
+        if (info?.status === 'no_key')
             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 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.' };
         }