@oar-sh/oar 0.9.22 → 0.9.24

package/server/services/claude-api-settings-service.mjs

@@ -7,8 +7,8 @@
 //
 // One key per relay, stored like the DeepSeek and Cursor keys in the settings
 // table and never sent to a browser. Next to it: the switch, the default
-// model, the discovered models and the ones enabled for the composer, and an
-// optional monthly spend cap. Commit attribution, the background command
+// model, the discovered models and which of them are on for the composer
+// (provider-model-state.mjs), and an optional monthly spend cap. Commit attribution, the background command
 // limit, the effort levels and the compaction window are the Claude tab's, so
 // they are not stored here.
 //
@@ -25,6 +25,7 @@ import {
   isClaudeLongContextModelId,
   isSafeClaudeModelId,
 } from '../../shared/model-id.mjs';
+import { createProviderModelStateStore } from './provider-model-state.mjs';
 import { DEFAULT_CLAUDE_REASONING_EFFORTS, withClaudeUltracodeTier } from './provider-reasoning-effort.mjs';
 
 export const CLAUDE_API_PROVIDER_TYPE = 'claude-api';
@@ -34,6 +35,8 @@ export const CLAUDE_API_KEY_SETTING_KEY = 'claude_api_key';
 export const CLAUDE_API_ENABLED_SETTING_KEY = 'claude_api_enabled';
 export const CLAUDE_API_MODEL_SETTING_KEY = 'claude_api_model';
 export const CLAUDE_API_MODELS_SETTING_KEY = 'claude_api_models';
+// The allowlist before 0.9.24: read once to build the model map, then left
+// as it is so an older version still finds it.
 export const CLAUDE_API_ENABLED_MODELS_SETTING_KEY = 'claude_api_enabled_models';
 export const CLAUDE_API_MONTHLY_CAP_SETTING_KEY = 'claude_api_monthly_cap_usd';
 // The derived default a new key replaced, kept until that key's models are
@@ -180,8 +183,8 @@ function normalizeStoredModel(entry) {
 }
 
 /**
- * Reads `{ apiKey?, enabled?, model?, enabledModels?, monthlyCapUsd?,
- * remove? }` from a request body. The key is never echoed in an error, and a
+ * Reads `{ apiKey?, enabled?, model?, enabledModels?, autoEnableNew?,
+ * monthlyCapUsd?, remove? }` from a request body. The key is never echoed in an error, and a
  * Claude login token or an Admin key is refused by its prefix.
  */
 export function parseClaudeApiSettingsUpdateRequest(body = {}) {
@@ -212,6 +215,14 @@ export function parseClaudeApiSettingsUpdateRequest(body = {}) {
     if (!Array.isArray(payload.enabledModels)) return { ok: false, error: 'enabledModels must be a list' };
     update.enabledModels = uniqueModels(payload.enabledModels);
   }
+  if (hasOwn(payload, 'shownModels')) {
+    if (!Array.isArray(payload.shownModels)) return { ok: false, error: 'shownModels must be a list' };
+    update.shownModels = uniqueModels(payload.shownModels);
+  }
+  if (hasOwn(payload, 'autoEnableNew')) {
+    if (typeof payload.autoEnableNew !== 'boolean') return { ok: false, error: 'autoEnableNew must be true or false' };
+    update.autoEnableNew = payload.autoEnableNew;
+  }
   if (hasOwn(payload, 'monthlyCapUsd')) {
     const cap = parseClaudeApiMonthlyCap(payload.monthlyCapUsd);
     if (!cap.ok) return { ok: false, error: cap.error };
@@ -240,7 +251,11 @@ export function createClaudeApiSettingsService({
   // Where OAR_ANTHROPIC_API_BASE_URL is read (a loopback fake API in tests).
   env = process.env,
   now = () => new Date(),
+  // (result) after each discovery: the model refresh ledger's clock.
+  onModelsRefreshed = () => {},
 } = {}) {
+  const modelState = createProviderModelStateStore({ readSetting, writeSetting, now });
+
   function readClaudeSettings() {
     try {
       const settings = getClaudeProviderSettings();
@@ -321,10 +336,13 @@ export function createClaudeApiSettingsService({
     const model = stored && isUsableModelId(stored) ? stored : defaultModelFor(offered, claudeSettings, carried);
     const availableModels = uniqueModels([model, ...offered]);
     const availableKeys = new Set(availableModels.map((id) => id.toLowerCase()));
-    const storedEnabled = uniqueModels(readJsonList(CLAUDE_API_ENABLED_MODELS_SETTING_KEY))
-      .filter((entry) => availableKeys.has(entry.toLowerCase()));
-    // The default model always stays enabled; with no choice stored, all are.
-    const models = storedEnabled.length ? uniqueModels([model, ...storedEnabled]) : availableModels;
+    // The default model always stays on; the others as the model map says.
+    const enabled = modelState.resolve(CLAUDE_API_PROVIDER_TYPE, {
+      availableModels,
+      defaultModel: model,
+      legacyAllowlist: () => uniqueModels(readJsonList(CLAUDE_API_ENABLED_MODELS_SETTING_KEY)),
+    });
+    const models = uniqueModels(enabled.models);
 
     const detailsByBase = new Map(discovered.map((entry) => [entry.id.toLowerCase(), entry]));
     const claudeEfforts = claudeSettings?.effortsByModel && typeof claudeSettings.effortsByModel === 'object'
@@ -381,6 +399,9 @@ export function createClaudeApiSettingsService({
       models,
       availableModels,
       enabledModels: models,
+      autoEnableNew: enabled.autoEnableNew,
+      fallback: enabled.fallback,
+      unseenModels: enabled.unseen,
       discovered: discovered.length > 0,
       effortsByModel,
       contextWindowsByModel,
@@ -463,9 +484,9 @@ export function createClaudeApiSettingsService({
           activeQueueConversationCount: counts.queued,
         };
       }
+      // The model map stays: a key added again finds its models as they were.
       deleteSetting(CLAUDE_API_KEY_SETTING_KEY);
       deleteSetting(CLAUDE_API_MODELS_SETTING_KEY);
-      deleteSetting(CLAUDE_API_ENABLED_MODELS_SETTING_KEY);
       deleteSetting(CLAUDE_API_CARRIED_MODEL_SETTING_KEY);
       writeSetting(CLAUDE_API_ENABLED_SETTING_KEY, 'false', stamp);
       return {
@@ -498,12 +519,16 @@ export function createClaudeApiSettingsService({
       if (parsed.model) writeSetting(CLAUDE_API_MODEL_SETTING_KEY, parsed.model, stamp);
       else deleteSetting(CLAUDE_API_MODEL_SETTING_KEY);
     }
-    if (hasOwn(parsed, 'enabledModels')) {
-      if (parsed.enabledModels.length) {
-        writeSetting(CLAUDE_API_ENABLED_MODELS_SETTING_KEY, JSON.stringify(parsed.enabledModels), stamp);
-      } else {
-        deleteSetting(CLAUDE_API_ENABLED_MODELS_SETTING_KEY);
-      }
+    if (hasOwn(parsed, 'enabledModels') || hasOwn(parsed, 'autoEnableNew')) {
+      // The models Select Models showed are set as ticked; an empty list
+      // leaves the default model alone, never all.
+      modelState.select(CLAUDE_API_PROVIDER_TYPE, {
+        enabledModels: parsed.enabledModels,
+        // The rows the browser drew; an older page sends none.
+        shownModels: parsed.shownModels || previous.availableModels,
+        defaultModel: getSettings().model,
+        autoEnableNew: parsed.autoEnableNew,
+      });
     }
     if (hasOwn(parsed, 'monthlyCapUsd')) {
       if (parsed.monthlyCapUsd === null) deleteSetting(CLAUDE_API_MONTHLY_CAP_SETTING_KEY);
@@ -530,6 +555,12 @@ export function createClaudeApiSettingsService({
    * new key's.
    */
   async function refreshModels() {
+    const result = await discoverModels();
+    try { onModelsRefreshed(result); } catch { /* the clock is best-effort */ }
+    return result;
+  }
+
+  async function discoverModels() {
     const settings = getSettings();
     if (!settings.configured) return { ok: false, models: settings.availableModels, error: 'Claude API key is not configured' };
     const redact = (text) => String(text ?? '').split(settings.apiKey).join('[redacted]');
@@ -560,7 +591,9 @@ export function createClaudeApiSettingsService({
       writeSetting?.(CLAUDE_API_MODELS_SETTING_KEY, JSON.stringify(models), now().toISOString());
       // The key's own list now decides the default.
       deleteSetting?.(CLAUDE_API_CARRIED_MODEL_SETTING_KEY);
-      return { ok: true, models: getSettings().availableModels, error: null };
+      const availableModels = getSettings().availableModels;
+      const { added } = modelState.reconcile(CLAUDE_API_PROVIDER_TYPE, { availableModels });
+      return { ok: true, models: availableModels, newModels: added, error: null };
     } catch (error) {
       return {
         ok: false,
@@ -571,5 +604,9 @@ export function createClaudeApiSettingsService({
     }
   }
 
-  return { getSettings, describe, update, refreshModels, contextWindowFor };
+  function markModelsSeen() {
+    return modelState.markSeen(CLAUDE_API_PROVIDER_TYPE);
+  }
+
+  return { getSettings, describe, update, refreshModels, contextWindowFor, markModelsSeen };
 }

package/server/services/cli-install-service.mjs

@@ -70,8 +70,9 @@ const GENERIC_VERSION_PATTERN = /(\d+\.\d+(?:\.\d+)*)/;
 /**
  * The frozen descriptor table: the only place an install command exists.
  *
- * Cursor is deliberately absent — `@cursor/sdk` is a pure npm package and the
- * relay never invokes a `cursor-agent` binary, so an install button there would
+ * Cursor is deliberately absent — `@cursor/sdk` is an npm package the relay
+ * installs on demand (agent-sdk-store.mjs) and the relay never invokes a
+ * `cursor-agent` binary, so an install button there would
  * install a CLI nothing runs (plan §2.4). Adding it back later is a data change
  * here, not a code change.
  *

package/server/services/copilot-model-discovery-service.mjs

@@ -44,6 +44,9 @@ export function createCopilotModelDiscoveryService({
   updateModelCatalog,
   timeoutMs = DEFAULT_COPILOT_MODEL_DISCOVERY_TIMEOUT_MS,
   bootDelayMs = DEFAULT_COPILOT_MODEL_DISCOVERY_BOOT_DELAY_MS,
+  // (result, reason) after each refresh that got past the CLI check: the
+  // model refresh ledger's clock (the boot refresh included).
+  onRefreshed = () => {},
   logger = console,
 } = {}) {
   if (typeof createClient !== 'function' || typeof updateModelCatalog !== 'function') {
@@ -151,7 +154,10 @@ export function createCopilotModelDiscoveryService({
         }
         activeRefresh = null;
       }
-    })();
+    })().then((result) => {
+      try { onRefreshed(result, reason); } catch { /* the clock is best-effort */ }
+      return result;
+    });
     return activeRefresh;
   }
 

package/server/services/database-file.mjs

@@ -27,7 +27,23 @@ const CHECK_DIR_PREFIX = '.database-file-check-';
 // one's work, not no rows: every start writes these settings (seen on a
 // real start of 0.9.19 on an empty folder). A later boot-time key goes here
 // deliberately; any other key makes the start refuse.
-export const STARTUP_SETTING_KEYS = Object.freeze(['push_vapid_public_key', 'push_vapid_private_key', 'relay_last_exit']);
+// Since 0.9.24 a start also writes each provider's model map as it finds
+// it (provider-model-state.mjs) and the last model refresh. A version that
+// runs on copilot.db writes none of them; a start of this one, which the
+// browser test uses as its stand-in, writes several.
+export const STARTUP_SETTING_KEYS = Object.freeze([
+  'push_vapid_public_key',
+  'push_vapid_private_key',
+  'relay_last_exit',
+  'copilot_model_state',
+  'openai_model_state',
+  'claude_model_state',
+  'cursor_model_state',
+  'grok_model_state',
+  'deepseek_model_state',
+  'claude_api_model_state',
+  'model_refresh_last',
+]);
 // And the tables such a start fills that hold no one's work: the model
 // catalog and its refresh state, the restart orchestrator's one row. (The
 // shadow tables of the message search are left out too: they follow

package/server/services/deepseek-settings-service.mjs

@@ -4,10 +4,11 @@
 //
 // One API key per relay, stored like the OpenAI and Cursor keys in the
 // settings table and never sent to the browser. Next to it: the switch, the
-// default model, the discovered models and the ones enabled for the
-// composer, an optional base URL, and the commit attribution of DeepSeek
-// chats. Discovery asks DeepSeek's `GET /models` (shared/deepseek-api.mjs);
-// when it has not run or failed, the built-in list stands in.
+// default model, the discovered models and which of them are on for the
+// composer (provider-model-state.mjs), an optional base URL, and the commit
+// attribution of DeepSeek chats. Discovery asks DeepSeek's `GET /models`
+// (shared/deepseek-api.mjs); when it has not run or failed, the built-in list
+// stands in.
 
 import { createDeepSeekApiClient, normalizeDeepSeekBaseUrl } from '../../shared/deepseek-api.mjs';
 import {
@@ -22,11 +23,14 @@ import {
 } from '../../shared/deepseek-models.mjs';
 import { DEEPSEEK_PRICE_CURRENCIES } from '../../shared/deepseek-pricing.mjs';
 import { isSafeDeepSeekModelId } from '../../shared/model-id.mjs';
+import { createProviderModelStateStore } from './provider-model-state.mjs';
 
 export const DEEPSEEK_API_KEY_SETTING_KEY = 'deepseek_api_key';
 export const DEEPSEEK_ENABLED_SETTING_KEY = 'deepseek_enabled';
 export const DEEPSEEK_MODEL_SETTING_KEY = 'deepseek_model';
 export const DEEPSEEK_MODELS_SETTING_KEY = 'deepseek_models';
+// The allowlist before 0.9.24: read once to build the model map, then left
+// as it is so an older version still finds it.
 export const DEEPSEEK_ENABLED_MODELS_SETTING_KEY = 'deepseek_enabled_models';
 export const DEEPSEEK_BASE_URL_SETTING_KEY = 'deepseek_base_url';
 export const DEEPSEEK_ATTRIBUTION_SETTING_KEY = 'deepseek_attribution';
@@ -95,9 +99,9 @@ function parseMonthlyBudgetCurrency(value) {
 }
 
 /**
- * Reads `{ apiKey?, enabled?, model?, enabledModels?, baseUrl?, attribution?,
- * monthlyBudget?, monthlyBudgetCurrency?, startingBalance?,
- * startingBalanceEdited?, remove? }` from a
+ * Reads `{ apiKey?, enabled?, model?, enabledModels?, autoEnableNew?,
+ * baseUrl?, attribution?, monthlyBudget?, monthlyBudgetCurrency?,
+ * startingBalance?, startingBalanceEdited?, remove? }` from a
  * request body. The
  * key is never echoed in an error.
  */
@@ -124,6 +128,14 @@ export function parseDeepSeekSettingsUpdateRequest(body = {}) {
     if (!Array.isArray(payload.enabledModels)) return { ok: false, error: 'enabledModels must be a list' };
     update.enabledModels = uniqueModels(payload.enabledModels);
   }
+  if (hasOwn(payload, 'shownModels')) {
+    if (!Array.isArray(payload.shownModels)) return { ok: false, error: 'shownModels must be a list' };
+    update.shownModels = uniqueModels(payload.shownModels);
+  }
+  if (hasOwn(payload, 'autoEnableNew')) {
+    if (typeof payload.autoEnableNew !== 'boolean') return { ok: false, error: 'autoEnableNew must be true or false' };
+    update.autoEnableNew = payload.autoEnableNew;
+  }
   if (hasOwn(payload, 'baseUrl')) {
     const normalized = normalizeDeepSeekBaseUrl(payload.baseUrl === null ? '' : payload.baseUrl);
     if (!normalized.ok) return { ok: false, error: normalized.error };
@@ -168,7 +180,11 @@ export function createDeepSeekSettingsService({
   listProviderCandidates = () => [],
   fetchImpl = globalThis.fetch,
   now = () => new Date(),
+  // (result) after each discovery: the model refresh ledger's clock.
+  onModelsRefreshed = () => {},
 } = {}) {
+  const modelState = createProviderModelStateStore({ readSetting, writeSetting, now });
+
   function readList(settingKey) {
     try {
       const parsed = JSON.parse(readSetting(settingKey) || '[]');
@@ -220,10 +236,13 @@ export function createDeepSeekSettingsService({
     const model = readModel();
     const discovered = readList(DEEPSEEK_MODELS_SETTING_KEY);
     const availableModels = uniqueModels([model, ...(discovered.length ? discovered : DEFAULT_DEEPSEEK_MODELS)]);
-    const storedEnabled = readList(DEEPSEEK_ENABLED_MODELS_SETTING_KEY)
-      .filter((entry) => availableModels.some((candidate) => candidate.toLowerCase() === entry.toLowerCase()));
-    // The default model always stays enabled; with no choice stored, all are.
-    const models = storedEnabled.length ? uniqueModels([model, ...storedEnabled]) : availableModels;
+    // The default model always stays on; the others as the model map says.
+    const enabled = modelState.resolve(DEEPSEEK_PROVIDER_TYPE, {
+      availableModels,
+      defaultModel: model,
+      legacyAllowlist: () => readList(DEEPSEEK_ENABLED_MODELS_SETTING_KEY),
+    });
+    const models = uniqueModels(enabled.models);
     return {
       configured: !!apiKey,
       enabled: !!apiKey && (enabledSetting === '' || enabledSetting === 'true'),
@@ -231,6 +250,9 @@ export function createDeepSeekSettingsService({
       model,
       models,
       availableModels,
+      autoEnableNew: enabled.autoEnableNew,
+      fallback: enabled.fallback,
+      unseenModels: enabled.unseen,
       discovered: discovered.length > 0,
       baseUrl: readBaseUrl(),
       attribution: readAttribution(),
@@ -291,9 +313,9 @@ export function createDeepSeekSettingsService({
           activeQueueConversationCount: counts.queued,
         };
       }
+      // The model map stays: a key added again finds its models as they were.
       deleteSetting(DEEPSEEK_API_KEY_SETTING_KEY);
       deleteSetting(DEEPSEEK_MODELS_SETTING_KEY);
-      deleteSetting(DEEPSEEK_ENABLED_MODELS_SETTING_KEY);
       writeSetting(DEEPSEEK_ENABLED_SETTING_KEY, 'false', stamp);
       return { ok: true, removed: true, keyChanged: previous.configured, discover: false, settings: describe() };
     }
@@ -315,12 +337,16 @@ export function createDeepSeekSettingsService({
     }
     if (hasOwn(parsed, 'enabled') || keyChanged) writeSetting(DEEPSEEK_ENABLED_SETTING_KEY, nextEnabled ? 'true' : 'false', stamp);
     if (hasOwn(parsed, 'model')) writeSetting(DEEPSEEK_MODEL_SETTING_KEY, parsed.model, stamp);
-    if (hasOwn(parsed, 'enabledModels')) {
-      if (parsed.enabledModels.length) {
-        writeSetting(DEEPSEEK_ENABLED_MODELS_SETTING_KEY, JSON.stringify(parsed.enabledModels), stamp);
-      } else {
-        deleteSetting(DEEPSEEK_ENABLED_MODELS_SETTING_KEY);
-      }
+    if (hasOwn(parsed, 'enabledModels') || hasOwn(parsed, 'autoEnableNew')) {
+      // The models Select Models showed are set as ticked; an empty list
+      // leaves the default model alone, never all.
+      modelState.select(DEEPSEEK_PROVIDER_TYPE, {
+        enabledModels: parsed.enabledModels,
+        // The rows the browser drew; an older page sends none.
+        shownModels: parsed.shownModels || previous.availableModels,
+        defaultModel: readModel(),
+        autoEnableNew: parsed.autoEnableNew,
+      });
     }
     if (hasOwn(parsed, 'attribution')) writeSetting(DEEPSEEK_ATTRIBUTION_SETTING_KEY, parsed.attribution, stamp);
     if (hasOwn(parsed, 'monthlyBudget')) {
@@ -361,6 +387,12 @@ export function createDeepSeekSettingsService({
    * failure keeps what was stored, so the pickers never empty out.
    */
   async function refreshModels() {
+    const result = await discoverModels();
+    try { onModelsRefreshed(result); } catch { /* the clock is best-effort */ }
+    return result;
+  }
+
+  async function discoverModels() {
     const settings = getSettings();
     if (!settings.configured) return { ok: false, models: settings.availableModels, error: 'DeepSeek API key is not configured' };
     try {
@@ -370,11 +402,17 @@ export function createDeepSeekSettingsService({
         return { ok: false, models: settings.availableModels, error: 'DeepSeek listed no DeepSeek models' };
       }
       writeSetting?.(DEEPSEEK_MODELS_SETTING_KEY, JSON.stringify(models), now().toISOString());
-      return { ok: true, models: getSettings().availableModels, error: null };
+      const availableModels = getSettings().availableModels;
+      const { added } = modelState.reconcile(DEEPSEEK_PROVIDER_TYPE, { availableModels });
+      return { ok: true, models: availableModels, newModels: added, error: null };
     } catch (error) {
       return { ok: false, models: settings.availableModels, error: error?.message || 'DeepSeek model discovery failed', code: error?.code || null };
     }
   }
 
-  return { getSettings, describe, update, refreshModels };
+  function markModelsSeen() {
+    return modelState.markSeen(DEEPSEEK_PROVIDER_TYPE);
+  }
+
+  return { getSettings, describe, update, refreshModels, markModelsSeen };
 }

package/server/services/earlier-database-service.mjs

@@ -9,10 +9,10 @@ import {
 } from './database-file.mjs';
 import { resolveOarRoot } from './oar-state-migration-service.mjs';
 import { resolveStateLayout } from './oar-state-layout.mjs';
-import { defaultIsProcessAlive, lockHolderMayRun, processStartedAt as defaultProcessStartedAt } from './relay-singleton-guard.mjs';
+import { defaultIsProcessAlive, lockHolderMayRun, processImageName, processStartedAt as defaultProcessStartedAt } from './relay-singleton-guard.mjs';
 
 const SHA256_NAME = /^[a-f0-9]{64}$/;
-// The install-time rescue's copies (package-data-rescue.mjs), in the data folder.
+// The copies the install-time rescue of 0.9.14 to 0.9.22 made, in the data folder.
 export const RESCUE_DIR_NAME = 'rescued-package-data';
 // What was looked at already: never offered again unless it changed.
 export const CHECKED_FILE = 'earlier-databases.json';
@@ -94,6 +94,8 @@ function adopt({
   platform = process.platform,
   isProcessAlive = defaultIsProcessAlive,
   processStartedAt = (pid) => defaultProcessStartedAt(pid, { platform }),
+  // What a pid runs, when its start cannot be told (Windows without koffi).
+  imageNameOf = processImageName,
   bootTime = Date.now() - os.uptime() * 1000,
   now = () => new Date(),
   clock = Date.now,
@@ -234,7 +236,7 @@ function adopt({
       fsImpl,
       rename,
       exists,
-      lockMayRun: (lock) => lockHolderMayRun({ lock, isProcessAlive, startedAtOf: processStartedAt, bootTime }),
+      lockMayRun: (lock) => lockHolderMayRun({ lock, isProcessAlive, startedAtOf: processStartedAt, bootTime, platform, imageNameOf }),
       normalize,
       progress,
     });

package/server/services/file-serving.mjs

@@ -60,6 +60,19 @@ export function withFileVersion(url, version) {
   return appendUrlParam(String(url || ''), 'v', String(version || ''));
 }
 
+/**
+ * One of the relay's own files (sw.js, the socket.io client) through
+ * res.sendFile, rooted at its folder. Given a bare absolute path, express 5's
+ * send refuses any path with a dot folder in it (dotfiles 'ignore' looks at
+ * every segment without a root): a 404 for an install under ~/.oar, nvm or
+ * ~/.npm-global. With the folder as root only the file name is looked at.
+ */
+export function sendOwnFile(res, absolutePath, next) {
+  res.sendFile(path.basename(absolutePath), { root: path.dirname(absolutePath) }, (error) => {
+    if (error) next(error);
+  });
+}
+
 /**
  * `cacheControl` replaces the no-store default for content whose URL names
  * its bytes (an upload addressed by its hash): such an answer may be kept.

package/server/services/model-refresh-scheduler.mjs

@@ -0,0 +1,153 @@
+'use strict';
+
+// The background "Check for new models" (Settings → General → Models).
+//
+// A minute after boot, then every quarter of an hour, the scheduler asks
+// which providers are due and refreshes those through the same helper as the
+// Select Models Refresh button (provider-model-refresh.mjs), with reason
+// `background`. A provider is due when the check is on, the provider is not
+// left out, it is enabled and set up, its last successful refresh (by
+// anything: the button, a save, a login, the boot) is at least the interval
+// old, and its last failure at least an hour old. A provider never refreshed
+// is due at the first tick, which is how an overdue provider is checked after
+// boot. Time and timers are injected so a test can drive it with a fake clock.
+
+import {
+  MODEL_REFRESH_FAILURE_RETRY_MS,
+  MODEL_REFRESH_FIRST_TICK_MS,
+  MODEL_REFRESH_PROVIDERS,
+  MODEL_REFRESH_TICK_MS,
+} from '../../shared/model-refresh-schedule.mjs';
+import { modelRefreshErrorSummary } from './provider-model-refresh.mjs';
+
+const HOUR_MS = 60 * 60 * 1000;
+
+function timeOf(value) {
+  const ms = Date.parse(String(value || ''));
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function notInFuture(ms, nowMs) {
+  return ms !== null && ms > nowMs ? null : ms;
+}
+
+/**
+ * The providers due at `nowMs`, in the canonical order. `settings` is
+ * `{ auto, intervalHours, excluded }`, `last` the ledger's entries, `table`
+ * the provider table (buildProviderRefreshTable).
+ */
+export function dueModelRefreshProviders({ settings = {}, last = {}, table = {}, nowMs = Date.now() } = {}) {
+  if (settings.auto === false) return [];
+  const intervalMs = Math.max(1, Number(settings.intervalHours) || 24) * HOUR_MS;
+  const excluded = new Set(Array.isArray(settings.excluded) ? settings.excluded : []);
+  const due = [];
+  for (const { id } of MODEL_REFRESH_PROVIDERS) {
+    const entry = table[id];
+    if (!entry || excluded.has(id) || typeof entry.refresh !== 'function') continue;
+    let setUp = false;
+    try {
+      setUp = entry.isSetUp?.() === true;
+    } catch {
+      setUp = false;
+    }
+    if (!setUp) continue;
+    // A stamp later than now (a clock set back, a hand edit) cannot be
+    // trusted: the provider is due rather than skipped until then.
+    const lastOk = notInFuture(timeOf(last[id]?.lastOkAt), nowMs);
+    const lastFailure = notInFuture(timeOf(last[id]?.lastFailureAt), nowMs);
+    if (lastOk !== null && nowMs - lastOk < intervalMs) continue;
+    if (lastFailure !== null && nowMs - lastFailure < MODEL_REFRESH_FAILURE_RETRY_MS) continue;
+    due.push(id);
+  }
+  return due;
+}
+
+export function createModelRefreshScheduler({
+  // () => { auto, intervalHours, excluded }
+  getSettings = () => ({ auto: true, intervalHours: 24, excluded: [] }),
+  // () => { <provider>: { lastOkAt, lastFailureAt } } (the ledger)
+  getLast = () => ({}),
+  // () => the provider table (buildProviderRefreshTable)
+  getTable = () => ({}),
+  // ({ providers, reason }) => Promise<{ results, changed }>
+  refreshProviders = async () => ({ results: {}, changed: false }),
+  now = () => Date.now(),
+  setTimeoutFn = setTimeout,
+  clearTimeoutFn = clearTimeout,
+  firstTickMs = MODEL_REFRESH_FIRST_TICK_MS,
+  tickMs = MODEL_REFRESH_TICK_MS,
+  logger = console,
+} = {}) {
+  let timer = null;
+  let running = null;
+  let disposed = false;
+  // Set by the routes layer, which owns the models_updated payload.
+  let onModelsChanged = () => {};
+
+  function schedule(delayMs) {
+    if (disposed) return;
+    if (timer) clearTimeoutFn(timer);
+    timer = setTimeoutFn(() => {
+      timer = null;
+      void tick().finally(() => schedule(tickMs));
+    }, Math.max(0, Number(delayMs) || 0));
+    timer?.unref?.();
+  }
+
+  /** One look: refreshes what is due. Never rejects; one run at a time. */
+  async function tick() {
+    if (disposed) return { providers: [], results: {}, changed: false };
+    if (running) return running;
+    // Cleared in a .finally of its own: a run with nothing due settles
+    // before the assignment would otherwise have happened.
+    running = (async () => {
+      let providers = [];
+      try {
+        providers = dueModelRefreshProviders({ settings: getSettings(), last: getLast(), table: getTable(), nowMs: now() });
+        if (!providers.length) return { providers, results: {}, changed: false };
+        logger.log?.(`[model-refresh] background model refresh: ${providers.join(', ')}`);
+        const { results = {}, changed = false } = await refreshProviders({ providers, reason: 'background' }) || {};
+        const failed = providers.filter((id) => results[id] && results[id].ok !== true && results[id].skipped !== true);
+        if (failed.length) {
+          // The provider and the kind of failure only: an answer's body may
+          // echo what was sent with the request.
+          logger.warn?.(`[model-refresh] background model refresh failed for ${failed.map((id) => `${id} (${modelRefreshErrorSummary(results[id].error)})`).join(', ')}`);
+        }
+        if (changed && !disposed) {
+          try {
+            onModelsChanged();
+          } catch (error) {
+            logger.warn?.(`[model-refresh] models-changed listener failed: ${error?.message || error}`);
+          }
+        }
+        return { providers, results, changed };
+      } catch (error) {
+        logger.warn?.(`[model-refresh] background model refresh failed: ${modelRefreshErrorSummary(error?.message || error)}`);
+        return { providers, results: {}, changed: false };
+      }
+    })().finally(() => {
+      running = null;
+    });
+    return running;
+  }
+
+  function start() {
+    if (disposed || timer) return;
+    schedule(firstTickMs);
+  }
+
+  function setOnModelsChanged(listener) {
+    onModelsChanged = typeof listener === 'function' ? listener : () => {};
+  }
+
+  async function dispose() {
+    disposed = true;
+    if (timer) {
+      clearTimeoutFn(timer);
+      timer = null;
+    }
+    try { await running; } catch { /* tick() never rejects */ }
+  }
+
+  return { start, tick, dispose, setOnModelsChanged, isStarted: () => timer !== null };
+}