@yeaft/webchat-agent 1.0.190 → 1.0.192

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.190",
+  "version": "1.0.192",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/config-api.js

@@ -11,7 +11,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { DEFAULT_YEAFT_DIR } from './init.js';
-import { normalizeProviderModels, serializeModelForPersistence } from './models.js';
+import { normalizeProviderModels, parseModelRef, serializeModelForPersistence } from './models.js';
 import { normaliseYeaftSection } from './config.js';
 import { isGitHubCopilotProvider, serializeKnownProviderForPersistence } from './llm/known-providers.js';
 
@@ -54,6 +54,58 @@ export function getLlmConfig(dir) {
   }
 }
 
+function providerModelIds(provider) {
+  return new Set(normalizeProviderModels(provider).map(model => model.id));
+}
+
+function bareModelOwners(providers, modelId) {
+  const owners = new Set();
+  for (const provider of providers) {
+    if (provider?.name && providerModelIds(provider).has(modelId)) owners.add(provider.name);
+  }
+  return owners;
+}
+
+function modelSelectionIsValid(selection, providers, authoritativeManagedNames) {
+  if (!selection) return false;
+  const parsed = parseModelRef(selection);
+  if (!parsed.modelId) return false;
+  if (!parsed.providerName) return bareModelOwners(providers, parsed.modelId).size === 1;
+  if (!authoritativeManagedNames.has(parsed.providerName)) return true;
+  const provider = providers.find(item => item?.name === parsed.providerName);
+  return !!provider && providerModelIds(provider).has(parsed.modelId);
+}
+
+function normalizeManagedModelDefaults(config) {
+  const providers = Array.isArray(config.providers) ? config.providers : [];
+  const authoritativeManagedProviders = providers.filter(provider =>
+    isGitHubCopilotProvider(provider)
+      && Array.isArray(provider.models)
+      && provider.models.length > 0);
+  if (authoritativeManagedProviders.length === 0) return;
+
+  const authoritativeManagedNames = new Set(authoritativeManagedProviders.map(provider => provider.name));
+  const fallbackProvider = authoritativeManagedProviders.find(provider => providerModelIds(provider).size > 0);
+  const fallbackModelId = fallbackProvider
+    ? providerModelIds(fallbackProvider).values().next().value
+    : null;
+  const managedFallback = fallbackProvider && fallbackModelId
+    ? `${fallbackProvider.name}/${fallbackModelId}`
+    : null;
+
+  if (config.primaryModel
+    && !modelSelectionIsValid(config.primaryModel, providers, authoritativeManagedNames)) {
+    config.primaryModel = managedFallback;
+  }
+  const validPrimary = modelSelectionIsValid(config.primaryModel, providers, authoritativeManagedNames)
+    ? config.primaryModel
+    : managedFallback;
+  if (config.fastModel
+    && !modelSelectionIsValid(config.fastModel, providers, authoritativeManagedNames)) {
+    config.fastModel = validPrimary;
+  }
+}
+
 /**
  * Update the LLM-relevant portion of config.json.
  * Merges into existing config — preserves fields like debug, maxContextTokens, etc.
@@ -109,13 +161,16 @@ export function updateLlmConfig(update, dir) {
     });
   }
 
-  // Update model selections
+  // Update model selections. A managed provider catalog is authoritative:
+  // when it drops the old Agent default, keep no hidden reference to that
+  // model in primaryModel or fastModel.
   if (update.primaryModel !== undefined) {
     existing.primaryModel = update.primaryModel || null;
   }
   if (update.fastModel !== undefined) {
     existing.fastModel = update.fastModel || null;
   }
+  if (update.providers !== undefined) normalizeManagedModelDefaults(existing);
   if (update.language !== undefined) {
     existing.language = update.language;
   }

package/yeaft/engine.js

@@ -683,14 +683,7 @@ export class Engine {
       conversationId: this.#traceId,
     });
 
-    // Build fast config: uses fastModelId for internal tasks (recall, consolidation, dream)
-    // Falls back to primary model if no fastModel configured
-    const fastModelId = config.fastModelId || config.model;
-    if (fastModelId !== config.model) {
-      this.#fastConfig = { ...config, model: fastModelId };
-    } else {
-      this.#fastConfig = config;
-    }
+    this.refreshConfig(config);
   }
 
   /**
@@ -759,6 +752,21 @@ export class Engine {
     this.#config.language = lang;
   }
 
+  /**
+   * Replace the effective runtime config for subsequent queries without
+   * interrupting a turn that already captured its model.
+   *
+   * @param {object} config
+   */
+  refreshConfig(config) {
+    if (!config || typeof config !== 'object') return;
+    this.#config = config;
+    const fastModelId = config.fastModelId || config.model;
+    this.#fastConfig = fastModelId !== config.model
+      ? { ...config, model: fastModelId }
+      : config;
+  }
+
   /**
    * Hot-swap runtime managers for a project-bound Session. The ToolRegistry is
    * shared at the bridge/session layer; these references only decide which

package/yeaft/llm/router.js

@@ -27,6 +27,7 @@ import {
   GITHUB_COPILOT_BASE_URL,
   GITHUB_COPILOT_CREDENTIAL_PROVIDER,
   GITHUB_COPILOT_PROVIDER_NAME,
+  isGitHubCopilotProvider,
   normalizeKnownProviderForRuntime,
 } from './known-providers.js';
 import { pairSanitize } from '../pair-sanitize.js';
@@ -238,9 +239,12 @@ export class AdapterRouter extends LLMAdapter {
   /** @type {Map<string, LLMAdapter>} providerName::protocol → cached adapter */
   #adapterCache;
 
-  /** @type {object[]} raw providers array */
+  /** @type {object[]} normalized providers array */
   #providers;
 
+  /** @type {Set<string>} managed providers backed by an explicit model catalog */
+  #authoritativeManagedProviders;
+
   /** @type {number} per-SSE-chunk silence budget; <= 0 disables the guard */
   #streamIdleTimeoutMs;
 
@@ -267,8 +271,13 @@ export class AdapterRouter extends LLMAdapter {
    * @param {object[]} providers
    */
   refreshProviders(providers) {
-    this.#providers = (Array.isArray(providers) ? providers : [])
-      .map(provider => normalizeKnownProviderForRuntime(provider));
+    const rawProviders = Array.isArray(providers) ? providers : [];
+    this.#authoritativeManagedProviders = new Set(rawProviders
+      .filter(provider => isGitHubCopilotProvider(provider)
+        && Array.isArray(provider.models)
+        && provider.models.length > 0)
+      .map(provider => provider.name || GITHUB_COPILOT_PROVIDER_NAME));
+    this.#providers = rawProviders.map(provider => normalizeKnownProviderForRuntime(provider));
     this.#modelToProvider = new Map();
     this.#adapterCache = new Map();
 
@@ -306,6 +315,10 @@ export class AdapterRouter extends LLMAdapter {
 
     const candidates = this.#providers.filter(p => p && p.name === parsed.providerName);
     if (candidates.length === 0) return null;
+    // An explicit managed catalog is authoritative. A qualified ref is not
+    // permission to resurrect a model that catalog just removed. Legacy rows
+    // with no models still use the bundled fallback catalog above.
+    if (this.#authoritativeManagedProviders.has(parsed.providerName)) return null;
 
     const inferred = inferProtocolFromModelId(parsed.modelId);
     if (!inferred) return null;

package/yeaft/sessions/session-config.js

@@ -7,30 +7,27 @@
  * Session config is user-level state. Project `.yeaft` directories may provide
  * project assets such as skills/MCP config, but must not own Session config.
  *
- * v1 schema (intentionally tiny — extend via additive keys only):
+ * Public v1 schema:
  *   {
  *     "model": "my-proxy/claude-sonnet-4-20250514",  // optional
  *     "modelEffort": "high"                          // optional
  *   }
  *
- * Missing file or `{}` → no session-level override. Missing field → fall back to user-level
- * config (`~/.yeaft/config.json` via loadConfig()). Resolution is a
- * shallow overlay for send-time effective config.
- *
- * Storage layer only — no engine wiring, no validation of model strings
- * against the provider registry (that's done lazily at resolve time by
- * the engine when it tries to dispatch to AdapterRouter).
+ * Missing file or `{}` means no Session-level override. Managed provider
+ * catalogs are authoritative: an override removed from such a catalog cannot
+ * reach the adapter and falls back to the current Agent default.
  */
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { writeAtomic } from '../storage/index.js';
+import { isGitHubCopilotProvider } from '../llm/known-providers.js';
 import { sessionsRoot } from './session-crud.js';
 
 const CONFIG_FILE = 'config.json';
-
-/** Whitelist of persisted session model-override fields. Reject everything else. */
-const ALLOWED_KEYS = new Set(['model', 'modelEffort']);
+const MODEL_SOURCE_EXPLICIT = 'explicit';
+const WRITABLE_KEYS = new Set(['model', 'modelEffort']);
+const STORED_KEYS = new Set([...WRITABLE_KEYS, 'modelSource']);
 const ALLOWED_EFFORTS = new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
 
 export class SessionConfigError extends Error {
@@ -41,36 +38,30 @@ export class SessionConfigError extends Error {
   }
 }
 
-/**
- * Resolve the on-disk path for a session's config.json. Always uses the
- * agent-local Yeaft root (`~/.yeaft` in production), not a project `.yeaft`.
- */
+/** Resolve the agent-local path for a Session's config.json. */
 export function sessionConfigPath(yeaftDir, sessionId) {
   if (!yeaftDir) return null;
   return join(sessionsRoot(yeaftDir), sessionId, CONFIG_FILE);
 }
 
-/**
- * Read a session's config.json. Returns `{}` when the file is missing or
- * corrupt — callers fall back to user-level defaults via
- * `resolveSessionConfig`. We never auto-write on read.
- *
- * @param {string} yeaftDir
- * @param {string} sessionId
- * @returns {object}
- */
-export function loadSessionConfig(yeaftDir, sessionId) {
+function publicConfig(stored) {
+  const out = {};
+  for (const key of WRITABLE_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(stored || {}, key)) out[key] = stored[key];
+  }
+  return out;
+}
+
+function loadStoredSessionConfig(yeaftDir, sessionId) {
   if (!sessionId || !yeaftDir) return {};
   const path = sessionConfigPath(yeaftDir, sessionId);
   if (!path || !existsSync(path)) return {};
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf8'));
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
-    // Strip unknown keys at read time too — defensive against
-    // hand-edited files that predate a key removal.
     const out = {};
-    for (const k of Object.keys(parsed)) {
-      if (ALLOWED_KEYS.has(k)) out[k] = parsed[k];
+    for (const key of Object.keys(parsed)) {
+      if (STORED_KEYS.has(key)) out[key] = parsed[key];
     }
     return out;
   } catch {
@@ -78,21 +69,27 @@ export function loadSessionConfig(yeaftDir, sessionId) {
   }
 }
 
+function persistStoredSessionConfig(yeaftDir, sessionId, stored) {
+  const path = sessionConfigPath(yeaftDir, sessionId);
+  writeAtomic(path, `${JSON.stringify(stored, null, 2)}\n`);
+}
+
 /**
- * Validate a partial group-config object. Throws SessionConfigError on
- * any unknown key or malformed value. Empty / null values for known
- * keys are allowed — they signal "fall back to user default".
- *
- * @param {object} cfg
+ * Read public Session config. Internal provenance never crosses this boundary.
  */
+export function loadSessionConfig(yeaftDir, sessionId) {
+  return publicConfig(loadStoredSessionConfig(yeaftDir, sessionId));
+}
+
+/** Validate a user/wire supplied partial Session config. */
 export function validateSessionConfig(cfg) {
   if (cfg === null || cfg === undefined) return;
   if (typeof cfg !== 'object' || Array.isArray(cfg)) {
     throw new SessionConfigError('invalid_shape', 'config must be an object');
   }
-  for (const k of Object.keys(cfg)) {
-    if (!ALLOWED_KEYS.has(k)) {
-      throw new SessionConfigError('unknown_key', `unknown config key: ${k}`);
+  for (const key of Object.keys(cfg)) {
+    if (!WRITABLE_KEYS.has(key)) {
+      throw new SessionConfigError('unknown_key', `unknown config key: ${key}`);
     }
   }
   if ('model' in cfg && cfg.model !== null && cfg.model !== undefined && cfg.model !== '') {
@@ -108,68 +105,154 @@ export function validateSessionConfig(cfg) {
 }
 
 /**
- * Shallow-merge `partial` into the group's existing config.json and
- * persist atomically. Returns the resulting object. Passing `null` or
- * empty string for a known key removes that key (so the group falls
- * back to the user default).
- *
- * @param {string} yeaftDir
- * @param {string} sessionId
- * @param {object} partial
- * @returns {object}
+ * Persist an explicit Session config change. `modelSource` is internal and is
+ * set here rather than accepted from clients, so future migrations can
+ * distinguish a user choice from the retired automatic default seed.
  */
 export function saveSessionConfig(yeaftDir, sessionId, partial) {
   if (!sessionId) throw new SessionConfigError('missing_group_id', 'sessionId required');
   validateSessionConfig(partial);
-  const current = loadSessionConfig(yeaftDir, sessionId);
-  const next = { ...current };
-  for (const [k, v] of Object.entries(partial || {})) {
-    if (!ALLOWED_KEYS.has(k)) continue;
-    if (v === null || v === undefined || v === '') {
-      delete next[k];
-    } else {
-      next[k] = typeof v === 'string' ? v.trim() : v;
+  const next = { ...loadStoredSessionConfig(yeaftDir, sessionId) };
+  for (const [key, value] of Object.entries(partial || {})) {
+    if (!WRITABLE_KEYS.has(key)) continue;
+    if (value === null || value === undefined || value === '') {
+      delete next[key];
+      if (key === 'model') delete next.modelSource;
+      continue;
     }
+    next[key] = typeof value === 'string' ? value.trim() : value;
+    if (key === 'model') next.modelSource = MODEL_SOURCE_EXPLICIT;
   }
-  const path = sessionConfigPath(yeaftDir, sessionId);
-  writeAtomic(path, `${JSON.stringify(next, null, 2)}\n`);
-  return next;
+  persistStoredSessionConfig(yeaftDir, sessionId, next);
+  return publicConfig(next);
 }
 
-/**
- * Initialise an empty config.json next to a brand-new group. Idempotent —
- * leaves an existing file untouched. Called by `createSessionFromSpec`.
- */
+/** Create an empty Session config file without inventing an override. */
 export function ensureSessionConfigFile(yeaftDir, sessionId) {
   const path = sessionConfigPath(yeaftDir, sessionId);
   if (!path || existsSync(path)) return;
   try {
-    writeAtomic(path, `${JSON.stringify({}, null, 2)}\n`);
+    persistStoredSessionConfig(yeaftDir, sessionId, {});
   } catch {
-    // Best-effort — a permission failure here should never break group
-    // create. Read path returns {} on missing file anyway.
+    // Best-effort — a permission failure must not break Session creation.
   }
 }
 
+function modelRefIdentity(value) {
+  const text = String(value || '');
+  const slash = text.indexOf('/');
+  return slash < 0
+    ? { provider: '', modelId: text }
+    : { provider: text.slice(0, slash), modelId: text.slice(slash + 1) };
+}
+
+function modelRefsEquivalent(left, right) {
+  if (!left || !right) return false;
+  if (left === right) return true;
+  const a = modelRefIdentity(left);
+  const b = modelRefIdentity(right);
+  if (a.modelId !== b.modelId) return false;
+  return !a.provider || !b.provider || a.provider === b.provider;
+}
+
+function hasAuthoritativeCatalog(provider) {
+  if (!provider || typeof provider !== 'object') return false;
+  if (provider.managed === true) return true;
+  if (typeof provider.managed === 'string' && provider.managed.trim()) return true;
+  return isGitHubCopilotProvider(provider);
+}
+
+function resolveAllowedModelRef(config, modelRef) {
+  const identity = modelRefIdentity(modelRef);
+  const providers = Array.isArray(config?.providers) ? config.providers : [];
+  const availableModels = Array.isArray(config?.availableModels) ? config.availableModels : [];
+
+  if (identity.provider) {
+    const provider = providers.find(item => item?.name === identity.provider);
+    if (!hasAuthoritativeCatalog(provider)) return modelRef;
+    const match = availableModels.find(model => model?.ref === modelRef
+      || (model?.provider === identity.provider && model?.id === identity.modelId));
+    return match?.ref || (match ? `${identity.provider}/${identity.modelId}` : null);
+  }
+
+  const authoritativeProviderNames = new Set(providers
+    .filter(hasAuthoritativeCatalog)
+    .map(provider => provider.name)
+    .filter(Boolean));
+  if (authoritativeProviderNames.size === 0) return modelRef;
+
+  const candidates = new Map();
+  for (const model of availableModels) {
+    const candidateIdentity = modelRefIdentity(model?.ref || '');
+    const candidateId = model?.id || candidateIdentity.modelId;
+    const providerName = model?.provider || candidateIdentity.provider;
+    if (candidateId !== identity.modelId || !providerName) continue;
+    candidates.set(model?.ref || `${providerName}/${candidateId}`, providerName);
+  }
+  if (candidates.size !== 1) return null;
+  const [[ref]] = candidates;
+  return ref;
+}
+
 /**
- * Resolve the effective config for a group by overlaying group-level
- * overrides on top of the user-level config.
- *
- * Only fields that the per-group schema knows about are overlaid;
- * everything else (providers, language, token budgets, ...) is taken
- * verbatim from the user config.
+ * Normalize persisted config at the Agent/Session boundary.
  *
- * @param {object} userConfig — loadConfig() result
- * @param {object} sessionConfig — loadSessionConfig() result
- * @returns {object} — A new config object safe to hand to the engine.
+ * - Managed catalog misses are always removed: they are no longer valid.
+ * - Legacy rows have no source bit. An unmarked value equal to the Agent's
+ *   previous default is the retired automatic seed and becomes inheritance.
+ * - Values written through the explicit update path carry `modelSource` and
+ *   are preserved while they remain in the authoritative catalog.
  */
+export function normalizeSessionConfig(
+  yeaftDir,
+  sessionId,
+  userConfig,
+  { previousDefaultModel = null } = {},
+) {
+  const stored = loadStoredSessionConfig(yeaftDir, sessionId);
+  if (!stored.model || typeof stored.model !== 'string') return publicConfig(stored);
+
+  const allowedModel = resolveAllowedModelRef(userConfig, stored.model);
+  // The retired create path wrote the then-current Agent default without a
+  // source bit. New explicit writes always carry modelSource, so this is the
+  // only deterministic compatibility rule available for legacy rows.
+  const legacyAutoSeed = stored.modelSource !== MODEL_SOURCE_EXPLICIT
+    && modelRefsEquivalent(stored.model, previousDefaultModel);
+  if (allowedModel && !legacyAutoSeed) {
+    const next = { ...stored };
+    let changed = false;
+    if (next.model !== allowedModel) {
+      next.model = allowedModel;
+      changed = true;
+    }
+    // Resolve every legacy row once while the old Agent default is known. A
+    // different value could only have come from an explicit Session choice;
+    // backfill provenance so a later default change cannot misclassify it.
+    if (previousDefaultModel && next.modelSource !== MODEL_SOURCE_EXPLICIT) {
+      next.modelSource = MODEL_SOURCE_EXPLICIT;
+      changed = true;
+    }
+    if (changed) persistStoredSessionConfig(yeaftDir, sessionId, next);
+    return publicConfig(next);
+  }
+
+  const next = { ...stored };
+  delete next.model;
+  delete next.modelSource;
+  persistStoredSessionConfig(yeaftDir, sessionId, next);
+  return publicConfig(next);
+}
+
+/** Overlay a valid Session override on the Agent config. */
 export function resolveSessionConfig(userConfig, sessionConfig) {
   const base = userConfig ? { ...userConfig } : {};
   const overrides = sessionConfig && typeof sessionConfig === 'object' ? sessionConfig : {};
   if (overrides.model && typeof overrides.model === 'string' && overrides.model.trim()) {
-    const model = overrides.model.trim();
-    base.model = model;
-    base.primaryModel = model;
+    const model = resolveAllowedModelRef(base, overrides.model.trim());
+    if (model) {
+      base.model = model;
+      base.primaryModel = model;
+    }
   }
   if (overrides.modelEffort && typeof overrides.modelEffort === 'string' && ALLOWED_EFFORTS.has(overrides.modelEffort)) {
     base.modelEffort = overrides.modelEffort;

package/yeaft/status-cache.js

@@ -6,6 +6,7 @@
  * never clear the model list just because a refresh failed.
  */
 
+import { createHash } from 'node:crypto';
 import ctx from '../context.js';
 import { sendToServer } from '../connection/buffer.js';
 import { loadConfig } from './config.js';
@@ -23,6 +24,16 @@ function normalizeAvailableModels(models) {
     .filter(Boolean);
 }
 
+function catalogDigest(model, availableModels) {
+  return createHash('sha256')
+    .update(JSON.stringify({ model: model || null, availableModels: normalizeAvailableModels(availableModels) }))
+    .digest('hex');
+}
+
+function createCatalogEpoch(now) {
+  return `${process.pid}-${now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
 function buildEvent(snapshot) {
   return {
     type: 'yeaft_status',
@@ -33,7 +44,12 @@ function buildEvent(snapshot) {
     tools: snapshot.tools,
     yeaftDir: snapshot.yeaftDir || null,
     refreshedAt: snapshot.refreshedAt || null,
+    catalogRefreshedAt: snapshot.catalogRefreshedAt || null,
+    catalogEpoch: snapshot.catalogEpoch || null,
+    catalogRevision: snapshot.catalogRevision || null,
+    catalogDigest: snapshot.catalogDigest || null,
     refreshStartedAt: snapshot.refreshStartedAt || null,
+    refreshReason: snapshot.refreshReason || null,
     refreshError: snapshot.refreshError || null,
     refreshing: !!snapshot.refreshing,
   };
@@ -54,6 +70,13 @@ export function createYeaftStatusCache(options = {}) {
   let timer = null;
   let inFlight = null;
   let generation = 0;
+  let forceTail = Promise.resolve();
+  let pendingForceRefreshes = 0;
+  let hasConfigCatalog = false;
+  let lastCatalogRefreshedAt = 0;
+  let catalogEpoch = createCatalogEpoch(now);
+  let catalogRevision = 0;
+  let lastCatalogDigest = null;
 
   function current() {
     return snapshot ? { ...snapshot, availableModels: normalizeAvailableModels(snapshot.availableModels) } : null;
@@ -80,15 +103,26 @@ export function createYeaftStatusCache(options = {}) {
         const config = await load({ ...(yeaftDir && { dir: yeaftDir }) });
         if (refreshGeneration !== generation) return current();
         const previous = snapshot || {};
+        const nextModel = config.primaryModel || config.model || previous.model || null;
+        const nextModels = normalizeAvailableModels(config.availableModels);
+        const nextDigest = catalogDigest(nextModel, nextModels);
+        hasConfigCatalog = true;
+        lastCatalogRefreshedAt = now();
+        if (nextDigest !== lastCatalogDigest) catalogRevision += 1;
+        lastCatalogDigest = nextDigest;
         snapshot = {
           ...previous,
-          model: config.primaryModel || config.model || previous.model || null,
-          availableModels: normalizeAvailableModels(config.availableModels),
+          model: nextModel,
+          availableModels: nextModels,
           yeaftDir: config.dir || yeaftDir || previous.yeaftDir || null,
           skills: sessionStatus?.skills ?? previous.skills,
           mcpServers: sessionStatus?.mcpServers ?? previous.mcpServers,
           tools: sessionStatus?.tools ?? previous.tools,
-          refreshedAt: now(),
+          refreshedAt: lastCatalogRefreshedAt,
+          catalogRefreshedAt: lastCatalogRefreshedAt,
+          catalogEpoch,
+          catalogRevision,
+          catalogDigest: lastCatalogDigest,
           refreshStartedAt: startedAt,
           refreshReason: reason,
           refreshError: null,
@@ -104,6 +138,10 @@ export function createYeaftStatusCache(options = {}) {
           ...previous,
           availableModels: normalizeAvailableModels(previous.availableModels),
           refreshedAt: previous.refreshedAt || null,
+          catalogRefreshedAt: previous.catalogRefreshedAt || null,
+          catalogEpoch: previous.catalogEpoch || null,
+          catalogRevision: previous.catalogRevision || null,
+          catalogDigest: previous.catalogDigest || null,
           refreshStartedAt: startedAt,
           refreshReason: reason,
           refreshError: message,
@@ -118,35 +156,54 @@ export function createYeaftStatusCache(options = {}) {
     return refreshPromise;
   }
 
-  async function forceRefresh(options = {}) {
-    // Invalidate any disk read that started before the config write, wait for it
-    // to drain, then start a new read. A plain refresh() intentionally dedupes
-    // concurrent callers, which is wrong after a successful config update.
+  function forceRefresh(options = {}) {
+    // Serialize post-save reads. Every caller invalidates work that started
+    // before its config write, then reads only after earlier forced refreshes
+    // have drained. A counter keeps Session hydration from cancelling the
+    // newest refresh when an older caller finishes first.
     generation += 1;
-    if (inFlight) await inFlight;
-    return refresh({ ...options, emitRefreshing: options.emitRefreshing ?? false });
+    pendingForceRefreshes += 1;
+    const run = async () => {
+      try {
+        if (inFlight) await inFlight;
+        return await refresh({ ...options, emitRefreshing: options.emitRefreshing ?? false });
+      } finally {
+        pendingForceRefreshes -= 1;
+      }
+    };
+    const result = forceTail.then(run, run);
+    forceTail = result.catch(() => null);
+    return result;
   }
 
   function hydrateFromSession(sessionLike, { reason = 'session_ready', emitEvent = true } = {}) {
     if (!sessionLike) return null;
-    // Session hydration is authoritative. Any refresh that started before this
-    // point loaded an older disk snapshot and must not overwrite it when it
-    // resolves later.
-    generation += 1;
+    // Session hydration fills runtime status only. The provider/model catalog
+    // is owned by config.json, so hydration never invalidates a config read.
+    // A config write invalidates stale reads through forceRefresh() instead.
     const previous = snapshot || {};
+    const sessionModels = normalizeAvailableModels(sessionLike.config?.availableModels);
     snapshot = {
       ...previous,
-      model: sessionLike.config?.model || previous.model || null,
-      availableModels: normalizeAvailableModels(sessionLike.config?.availableModels || previous.availableModels),
+      model: hasConfigCatalog
+        ? (previous.model || sessionLike.config?.model || null)
+        : (sessionLike.config?.model || previous.model || null),
+      availableModels: hasConfigCatalog
+        ? normalizeAvailableModels(previous.availableModels)
+        : (sessionModels.length > 0 ? sessionModels : normalizeAvailableModels(previous.availableModels)),
       yeaftDir: sessionLike.yeaftDir || sessionLike.config?.dir || previous.yeaftDir || null,
       skills: sessionLike.status?.skills ?? previous.skills,
       mcpServers: sessionLike.status?.mcpServers ?? previous.mcpServers,
       tools: sessionLike.status?.tools ?? previous.tools,
       refreshedAt: now(),
+      catalogRefreshedAt: hasConfigCatalog ? lastCatalogRefreshedAt : null,
+      catalogEpoch: hasConfigCatalog ? catalogEpoch : null,
+      catalogRevision: hasConfigCatalog ? catalogRevision : null,
+      catalogDigest: hasConfigCatalog ? lastCatalogDigest : null,
       refreshStartedAt: previous.refreshStartedAt || null,
       refreshReason: reason,
-      refreshError: null,
-      refreshing: false,
+      refreshError: previous.refreshError || null,
+      refreshing: pendingForceRefreshes > 0 || !!previous.refreshing,
     };
     return emitEvent ? emitSnapshot() : buildEvent(snapshot);
   }