@oar-sh/oar 0.9.23 → 0.9.25

package/server/routes/sessions-routes.mjs

@@ -42,6 +42,7 @@ import { mapUsageSnapshotRow, fetchUsageSummaryPromise } from '../services/usage
 import { readStoredClaudeContextUsage, resolveAutoCompactWindowStatus } from '../services/claude-context-usage.mjs';
 import { buildContextUsageView } from '../services/context-usage-view.mjs';
 import { cleanupGeneratedImagesForConversation as cleanupGeneratedImagesForConversationDefault } from '../services/generated-image-cleanup-service.mjs';
+import { withGeneratedImageFiles } from '../services/generated-image-files.mjs';
 import { stopSessionWorkerProcesses } from '../services/session-worker-stop-service.mjs';
 import { isWorkerOnOtherBuild } from '../services/worker-recycle-service.mjs';
 import { createClaudeAuthService } from '../services/claude-auth-service.mjs';
@@ -97,6 +98,30 @@ import {
   isSafeProviderModelId,
 } from '../../shared/model-id.mjs';
 import { openAIReasoningEffortsForModel } from '../../shared/openai-reasoning.mjs';
+import {
+  IMAGE_INPUT_REFUSED_CODE,
+  OPENAI_IMAGE_MODEL_NEEDS_OPENAI_CODE,
+  OPENAI_IMAGE_NO_MODEL_CODE,
+  isOpenAIImageModelId,
+  openAIImageModelNeedsOpenAIText,
+  openAIImageNoModelText,
+  pickOpenAIImageDefaultModel,
+  validateOpenAIImageOptions,
+} from '../../shared/openai-image-options.mjs';
+import {
+  OPENAI_IMAGE_DAILY_CAP_DEFAULT_USD,
+  OPENAI_IMAGE_PRESETS_PATH,
+  OPENAI_IMAGE_SETTINGS_FIELDS,
+  OPENAI_IMAGE_SPEND_SETTING_KEYS,
+} from '../../shared/openai-image-spend.mjs';
+import {
+  OPENAI_IMAGE_PRESET_REFUSED_CODE,
+  OPENAI_IMAGE_PRESETS_SETTING_KEY,
+  applyOwnOpenAIImagePresetChange,
+  listOpenAIImagePresets,
+  parseOwnOpenAIImagePresets,
+} from '../../shared/openai-image-presets.mjs';
+import { buildOpenAIImagePlanCard } from '../services/plan-usage-openai-image.mjs';
 import { stripModelTierSuffix } from '../../shared/claude-cloud/repo-url.mjs';
 import {
   REMOTE_RELAY_ERROR_CODES,
@@ -155,6 +180,8 @@ import { deepseekStartingBalanceNote } from '../services/plan-usage-deepseek.mjs
 import { appendTokenSections } from '../services/plan-usage-tokens.mjs';
 import { DEEPSEEK_USAGE_CHECKPOINTS_TABLE } from '../migrations/0024-deepseek-usage-totals.mjs';
 import { claudeProjectDirSlug } from '../services/claude-session-root-service.mjs';
+import { buildProviderRefreshTable, refreshProviderModels } from '../services/provider-model-refresh.mjs';
+import { MODEL_REFRESH_INTERVAL_HOURS_CHOICES, MODEL_REFRESH_PROVIDERS, DEFAULT_MODEL_REFRESH_AUTO, DEFAULT_MODEL_REFRESH_INTERVAL_HOURS } from '../../shared/model-refresh-schedule.mjs';
 
 export { mapUsageSnapshotRow };
 
@@ -305,8 +332,11 @@ export function parseOpenAISettingsUpdateRequest(body = {}) {
   const hasEnabled = typeof payload.enabled === 'boolean';
   const hasBaseUrl = Object.prototype.hasOwnProperty.call(payload, 'baseUrl');
   const baseUrl = hasBaseUrl ? String(payload.baseUrl || '').trim() : undefined;
-  if (!remove && !hasModel && !apiKey && !hasEnabled && !hasBaseUrl) {
-    return { ok: false, error: 'No OpenAI settings update provided' };
+  const hasEnabledModels = Array.isArray(payload.enabledModels);
+  const hasAutoEnableNew = typeof payload.autoEnableNew === 'boolean';
+  if (!remove && !hasModel && !apiKey && !hasEnabled && !hasBaseUrl && !hasEnabledModels && !hasAutoEnableNew) {
+    // `empty`: the body may still carry the image cap fields alone.
+    return { ok: false, empty: true, error: 'No OpenAI settings update provided' };
   }
   if (hasModel && !isSafeProviderModelId(model)) {
     return { ok: false, error: 'Invalid OpenAI model ID' };
@@ -326,10 +356,46 @@ export function parseOpenAISettingsUpdateRequest(body = {}) {
     apiKey,
     ...(hasModel ? { model } : {}),
     ...(hasBaseUrl ? { baseUrl } : {}),
+    ...(hasEnabledModels ? { enabledModels: payload.enabledModels } : {}),
+    ...(hasAutoEnableNew ? { autoEnableNew: payload.autoEnableNew } : {}),
+    ...(Array.isArray(payload.shownModels) ? { shownModels: payload.shownModels } : {}),
     enabled: hasEnabled ? payload.enabled : (apiKey ? true : undefined),
   };
 }
 
+// The highest daily cap of OpenAI image spend the settings take, in USD.
+export const OPENAI_IMAGE_DAILY_CAP_MAX_USD = 10_000;
+
+/**
+ * The image cap fields of POST /api/settings/openai: `imageDailyCapUsd` (USD,
+ * 0 to OPENAI_IMAGE_DAILY_CAP_MAX_USD, to the cent; 0 or null: no cap) and
+ * `allowImagesToday` (true sets the owner's override for the relay's day,
+ * false clears it). `{ ok, present, dailyCapUsd?, allowToday? }`, or
+ * `{ ok:false, present:true, error }`.
+ */
+export function parseOpenAIImageSpendSettingsRequest(body = {}) {
+  const payload = body && typeof body === 'object' ? body : {};
+  const capField = OPENAI_IMAGE_SETTINGS_FIELDS.dailyCapUsd;
+  const allowField = OPENAI_IMAGE_SETTINGS_FIELDS.allowToday;
+  const hasCap = payload[capField] !== undefined;
+  const hasAllow = payload[allowField] !== undefined;
+  if (!hasCap && !hasAllow) return { ok: true, present: false };
+  const result = { ok: true, present: true };
+  if (hasCap) {
+    const raw = payload[capField];
+    const number = raw === null ? 0 : (typeof raw === 'string' && raw.trim() ? Number(raw.trim()) : raw);
+    if (typeof number !== 'number' || !Number.isFinite(number) || number < 0 || number > OPENAI_IMAGE_DAILY_CAP_MAX_USD) {
+      return { ok: false, present: true, error: `${capField} must be a number of USD from 0 (no cap) to ${OPENAI_IMAGE_DAILY_CAP_MAX_USD}` };
+    }
+    result.dailyCapUsd = Math.round(number * 100) / 100;
+  }
+  if (hasAllow) {
+    if (typeof payload[allowField] !== 'boolean') return { ok: false, present: true, error: `${allowField} must be true or false` };
+    result.allowToday = payload[allowField];
+  }
+  return result;
+}
+
 export function parseClaudeSettingsUpdateRequest(body = {}) {
   const payload = body && typeof body === 'object' ? body : {};
   const hasEnabled = typeof payload.enabled === 'boolean';
@@ -337,13 +403,14 @@ export function parseClaudeSettingsUpdateRequest(body = {}) {
   const model = hasModel ? (String(payload.model || '').trim() || 'claude-sonnet-5') : undefined;
   const hasModels = Array.isArray(payload.models);
   const hasEnabledModels = Array.isArray(payload.enabledModels);
+  const hasAutoEnableNew = typeof payload.autoEnableNew === 'boolean';
   const hasAttributionMode = Object.prototype.hasOwnProperty.call(payload, 'attributionMode');
   const attributionMode = hasAttributionMode ? normalizeClaudeAttributionMode(payload.attributionMode) : undefined;
   const hasBackgroundCommandLimit = Object.prototype.hasOwnProperty.call(payload, 'backgroundCommandLimitMinutes');
   const backgroundCommandLimit = hasBackgroundCommandLimit
     ? parseClaudeBackgroundCommandLimitUpdate(payload.backgroundCommandLimitMinutes)
     : null;
-  if (!hasEnabled && !hasModel && !hasModels && !hasEnabledModels && !hasAttributionMode && !hasBackgroundCommandLimit) {
+  if (!hasEnabled && !hasModel && !hasModels && !hasEnabledModels && !hasAutoEnableNew && !hasAttributionMode && !hasBackgroundCommandLimit) {
     return { ok: false, error: 'No Claude settings update provided' };
   }
   if (backgroundCommandLimit && !backgroundCommandLimit.ok) {
@@ -361,6 +428,8 @@ export function parseClaudeSettingsUpdateRequest(body = {}) {
     ...(hasModel ? { model } : {}),
     ...(hasModels ? { models: payload.models } : {}),
     ...(hasEnabledModels ? { enabledModels: payload.enabledModels } : {}),
+    ...(hasAutoEnableNew ? { autoEnableNew: payload.autoEnableNew } : {}),
+    ...(Array.isArray(payload.shownModels) ? { shownModels: payload.shownModels } : {}),
     ...(hasAttributionMode ? { attributionMode } : {}),
     // Clamped to 30 min … 8 h and snapped to 30-minute steps.
     ...(backgroundCommandLimit ? { backgroundCommandLimitMinutes: backgroundCommandLimit.minutes } : {}),
@@ -459,7 +528,8 @@ export function parseCursorSettingsUpdateRequest(body = {}) {
   const apiKey = String(payload.apiKey || '').trim();
   const hasEnabled = typeof payload.enabled === 'boolean';
   const hasEnabledModels = Array.isArray(payload.enabledModels);
-  if (!remove && !hasModel && !apiKey && !hasEnabled && !hasEnabledModels) {
+  const hasAutoEnableNew = typeof payload.autoEnableNew === 'boolean';
+  if (!remove && !hasModel && !apiKey && !hasEnabled && !hasEnabledModels && !hasAutoEnableNew) {
     return { ok: false, error: 'No Cursor settings update provided' };
   }
   if (hasModel && !isSafeCursorModelId(model)) {
@@ -480,6 +550,8 @@ export function parseCursorSettingsUpdateRequest(body = {}) {
     apiKey,
     ...(hasModel ? { model } : {}),
     ...(hasEnabledModels ? { enabledModels: payload.enabledModels } : {}),
+    ...(hasAutoEnableNew ? { autoEnableNew: payload.autoEnableNew } : {}),
+    ...(Array.isArray(payload.shownModels) ? { shownModels: payload.shownModels } : {}),
     enabled: hasEnabled ? payload.enabled : (apiKey ? true : undefined),
   };
 }
@@ -491,7 +563,8 @@ export function parseGrokSettingsUpdateRequest(body = {}) {
   const model = hasModel ? (String(payload.model || '').trim() || 'grok-4.5') : undefined;
   const hasModels = Array.isArray(payload.models);
   const hasEnabledModels = Array.isArray(payload.enabledModels);
-  if (!hasEnabled && !hasModel && !hasModels && !hasEnabledModels) {
+  const hasAutoEnableNew = typeof payload.autoEnableNew === 'boolean';
+  if (!hasEnabled && !hasModel && !hasModels && !hasEnabledModels && !hasAutoEnableNew) {
     return { ok: false, error: 'No Grok settings update provided' };
   }
   if (hasModel && !isSafeGrokModelId(model)) {
@@ -503,6 +576,8 @@ export function parseGrokSettingsUpdateRequest(body = {}) {
     ...(hasModel ? { model } : {}),
     ...(hasModels ? { models: payload.models } : {}),
     ...(hasEnabledModels ? { enabledModels: payload.enabledModels } : {}),
+    ...(hasAutoEnableNew ? { autoEnableNew: payload.autoEnableNew } : {}),
+    ...(Array.isArray(payload.shownModels) ? { shownModels: payload.shownModels } : {}),
   };
 }
 
@@ -529,6 +604,42 @@ function copilotListedModelIds(modelState = {}) {
   );
 }
 
+/**
+ * A Copilot catalog without its image ids (gpt-image-*, dall-e-*): the
+ * Copilot runtime cannot serve them, so neither New Chat, the composer nor
+ * relay_info offers them for Copilot. The OpenAI layer adds back the ones
+ * the OpenAI provider lists, as that provider's alone.
+ */
+export function withoutCopilotImageModels(modelState = {}) {
+  const models = Array.isArray(modelState?.models) ? modelState.models : [];
+  if (!models.some((modelId) => isOpenAIImageModelId(modelId))) return modelState;
+  const kept = models.filter((modelId) => !isOpenAIImageModelId(modelId));
+  const withoutImageKeys = (map) => (map && typeof map === 'object' && !Array.isArray(map)
+    ? Object.fromEntries(Object.entries(map).filter(([modelId]) => !isOpenAIImageModelId(modelId)))
+    : map);
+  const listedOr = (modelId) => (isOpenAIImageModelId(modelId) ? (kept[0] || '') : modelId);
+  return {
+    ...modelState,
+    models: kept,
+    ...(modelState.currentModel !== undefined ? { currentModel: listedOr(modelState.currentModel) } : {}),
+    ...(modelState.defaultModel !== undefined ? { defaultModel: listedOr(modelState.defaultModel) } : {}),
+    ...(modelState.reasoningByModel ? { reasoningByModel: withoutImageKeys(modelState.reasoningByModel) } : {}),
+    ...(modelState.contextLimitsByModel ? { contextLimitsByModel: withoutImageKeys(modelState.contextLimitsByModel) } : {}),
+    ...(modelState.modelMetadataByModel ? { modelMetadataByModel: withoutImageKeys(modelState.modelMetadataByModel) } : {}),
+    ...(modelState.providersByModel ? { providersByModel: withoutImageKeys(modelState.providersByModel) } : {}),
+    ...(Array.isArray(modelState.unavailableModels)
+      ? { unavailableModels: modelState.unavailableModels.filter((modelId) => !isOpenAIImageModelId(modelId)) }
+      : {}),
+  };
+}
+
+/** The refusal of a Copilot chat on an image model (400), or null for any other model. */
+function copilotImageModelRefusal(model = '') {
+  const modelId = String(model || '').trim();
+  if (!isOpenAIImageModelId(modelId)) return null;
+  return { ok: false, error: openAIImageModelNeedsOpenAIText(modelId), code: OPENAI_IMAGE_MODEL_NEEDS_OPENAI_CODE };
+}
+
 export function buildModelCatalogWithClaudeProvider(modelState = {}, claudeSettings = {}) {
   const configured = claudeSettings?.enabled === true;
   const model = String(claudeSettings?.model || '').trim();
@@ -964,11 +1075,6 @@ function normalizeRequestedProviderType(value = '') {
   return '';
 }
 
-function isOpenAIImageModelId(model = '') {
-  const normalized = String(model || '').trim().toLowerCase().replace(/^openai\//, '');
-  return normalized.startsWith('gpt-image-') || normalized.startsWith('dall-e-');
-}
-
 function isPidAlive(pidValue) {
   const pid = Number(pidValue);
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -2199,11 +2305,27 @@ export function registerSessionsRoutes(app, deps) {
     deleteOrphanedUploads,
     cleanupGeneratedImagesForConversation = cleanupGeneratedImagesForConversationDefault,
     queueCounts,
-    getModelCatalogState,
+    getModelCatalogState: readCopilotModelCatalogState,
     updateModelCatalog,
     listModelVariantRows,
     refreshModelVariantCatalogFromCli,
     setEnabledModelVariants,
+    // Copilot's model map (model-variant-catalog-service.mjs) and the other
+    // providers' (provider-model-state.mjs): the switch, the "New" flags.
+    getCopilotModelState = () => ({ autoEnableNew: false, unseen: [] }),
+    setCopilotAutoEnableNew = null,
+    markCopilotModelsSeen = () => false,
+    markProviderModelsSeen = () => false,
+    // When each provider was last refreshed and the new models the next
+    // models_updated carries (provider-model-refresh.mjs), the background
+    // check's settings and the check itself. Absent in most tests.
+    modelRefreshLedger = null,
+    modelRefreshSettings = null,
+    modelRefreshScheduler = null,
+    // Whether Claude and Grok are set up for the background check (their CLI
+    // or their login); absent, switched on is enough.
+    isClaudeModelRefreshSetUp = () => true,
+    isGrokModelRefreshSetUp = () => true,
     SUPPORTED_REASONING_EFFORTS,
     buildRelayReadyBannerData,
     workspaceRootPayload,
@@ -2269,6 +2391,12 @@ export function registerSessionsRoutes(app, deps) {
     // Tokens per turn and per day (services/token-usage-service.mjs): a
     // deleted chat drops its turn rows. Absent in older wiring and most tests.
     tokenUsageService = null,
+    // OpenAI image spend (shared/openai-image-spend.mjs): the state for the
+    // Check Usage card (`({ conversationId? }) → state`), and the call that
+    // re-announces it after the cap or the override changed. Absent in older
+    // wiring and most tests: no card, nothing announced.
+    getOpenAIImageSpendState = null,
+    notifyOpenAIImageSpendChanged = () => {},
     reconcileUnstartedConversationProviders = async () => ({
       updatedUnstartedConversations: 0,
       skippedStartedConversations: 0,
@@ -2399,6 +2527,9 @@ export function registerSessionsRoutes(app, deps) {
     // the wiring does not pass one.
     shareRepository = null,
   } = deps;
+  // Copilot's catalog as every route here serves it: without the image ids
+  // its runtime cannot serve (an OpenAI Image chat takes them from OpenAI).
+  const getModelCatalogState = () => withoutCopilotImageModels(readCopilotModelCatalogState());
   const sdkSessionSyncService = createSdkSessionSyncService(db);
   // Built on first use: many route tests hand in a database without tables.
   let shareRepositoryInstance = shareRepository;
@@ -2664,10 +2795,62 @@ export function registerSessionsRoutes(app, deps) {
     );
   }
 
+  // The providers the Refresh button and the background check ask, with
+  // their enablement and refresh functions (provider-model-refresh.mjs).
+  const providerRefreshTable = buildProviderRefreshTable({
+    getOpenAIProviderSettings,
+    refreshOpenAIProviderModels,
+    getClaudeProviderSettings,
+    refreshClaudeProviderModels,
+    getCursorProviderSettings,
+    refreshCursorProviderModels,
+    getGrokProviderSettings,
+    refreshGrokProviderModels,
+    deepseekSettingsService,
+    claudeApiSettingsService,
+    copilotModelDiscoveryService,
+    isClaudeSetUp: isClaudeModelRefreshSetUp,
+    isGrokSetUp: isGrokModelRefreshSetUp,
+  });
+
+  /** Models flagged new on the enabled providers: the Select Models menu dot. */
+  function countUnseenNewModels() {
+    let count = 0;
+    for (const settings of [
+      getOpenAIProviderSettings(),
+      getClaudeProviderSettings(),
+      getCursorProviderSettings(),
+      getGrokProviderSettings(),
+      getDeepSeekProviderSettings(),
+      getClaudeApiProviderSettings(),
+    ]) {
+      if (settings?.enabled === true && Array.isArray(settings.unseenModels)) count += settings.unseenModels.length;
+    }
+    const copilot = getCopilotModelState();
+    return count + (Array.isArray(copilot?.unseen) ? copilot.unseen.length : 0);
+  }
+
+  /**
+   * What models_updated carries: the catalog, the menu dot's count and, once,
+   * the models a refresh found for the first time (the toast).
+   */
+  function modelsUpdatedPayload(modelState, openAISettings = getOpenAIProviderSettings()) {
+    const newModels = modelRefreshLedger?.takeNewModels?.() || [];
+    return {
+      ...buildModelCatalogWithProviders(modelState, openAISettings),
+      unseenNewModelCount: countUnseenNewModels(),
+      ...(newModels.length ? { newModels } : {}),
+    };
+  }
+
   // A discovery that lands outside any route (the deferred boot refresh) still
   // has to reach connected pickers the way a snapshot POST does.
   copilotModelDiscoveryService?.setOnCatalogUpdated?.(() => {
-    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
+  });
+  // So does a background check that changed a provider's models.
+  modelRefreshScheduler?.setOnModelsChanged?.(() => {
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
   });
 
   // The client address as Express derives it through `trust proxy`: a
@@ -4972,7 +5155,9 @@ export function registerSessionsRoutes(app, deps) {
       group: conversationGroupPayload(resolvedConversationId, req),
       // Its place in the group's hand order, as on the list rows.
       groupPosition: conversationGroupPositionOf(conv),
-      messages: history.messages,
+      // Generated images with their file on this relay and their size, for
+      // this page's rows only (agents on other relays name the files).
+      messages: withGeneratedImageFiles(history.messages, { resolveSessionStateRoot }),
       pageInfo: history.pageInfo,
     });
   });
@@ -5247,6 +5432,18 @@ export function registerSessionsRoutes(app, deps) {
         return res.status(503).json({ error: 'This setting is unavailable until the relay restarts (its storage is missing).' });
       }
     }
+    // A Copilot chat cannot move to an image model: its runtime cannot serve
+    // one. The model it has already is written back as before.
+    if (
+      existing
+      && Object.prototype.hasOwnProperty.call(req.body || {}, 'preferredModel')
+      && normalizePreferredModel(req.body.preferredModel) !== normalizePreferredModel(existing.preferred_model)
+    ) {
+      const runtime = stmts.getRuntimeSessionByConversation?.get?.(conversationId) || null;
+      const provider = String(runtime?.provider_type || '').trim().toLowerCase();
+      const imageRefusal = provider === 'github' ? copilotImageModelRefusal(req.body.preferredModel) : null;
+      if (imageRefusal) return res.status(400).json(imageRefusal);
+    }
     if (remoteRequest && readPlanOnly(existing)
       && Object.prototype.hasOwnProperty.call(req.body || {}, 'preferredRelayMode')
       && planOnlyRefusesMode(req.body.preferredRelayMode)) {
@@ -5260,7 +5457,7 @@ export function registerSessionsRoutes(app, deps) {
   // ─── PATCH /api/conversation/:id/settings — the relay_tool's update_session ───
   //
   // `{ settings: { model, effort, mode, auto_compact_window, title, group,
-  // thinking_enabled, thinking_display, cwd }, dry_run, owner_approved }`.
+  // thinking_enabled, thinking_display, cwd, image }, dry_run, owner_approved }`.
   // Reached by an agent of this relay (the loopback) and by a paired relay's
   // agent (under the inbound switch); the owner may call it too. It applies
   // this relay's own rule: an agent changes freely only a session its own
@@ -5277,11 +5474,21 @@ export function registerSessionsRoutes(app, deps) {
 
   const SESSION_SETTINGS_INVALID = 'SESSION_SETTINGS_INVALID';
 
+  /** An image session's defaults as stored (`{}` for none, or for any other session). */
+  function readImageDefaults(conversationId) {
+    try {
+      return stmts.readConversationImageDefaults?.(conversationId) || {};
+    } catch {
+      return {};
+    }
+  }
+
   function currentSessionSettings(conversationId) {
     const conv = stmts.getConvAnyStatus.get(conversationId) || {};
     const runtime = stmts.getRuntimeSessionByConversation?.get?.(conversationId) || null;
     const workspace = resolveConversationWorkspaceState?.({ conversationId }) || null;
     const window = parseAutoCompactWindow(conv.auto_compact_window);
+    const imageDefaults = readImageDefaults(conversationId);
     return {
       model: normalizePreferredModel(conv.preferred_model) || String(runtime?.provider_model || runtime?.model || '').trim() || null,
       effort: normalizePreferredReasoningEffort(conv.preferred_reasoning_effort) || null,
@@ -5293,6 +5500,7 @@ export function registerSessionsRoutes(app, deps) {
       thinking_display: parseThinkingDisplay(conv.thinking_display),
       cwd: String(workspace?.currentWorkspaceRootPath || workspace?.configuredWorkspaceRootPath || conv.configured_workspace_root_path || '').trim() || null,
       planOnly: readPlanOnly(conv),
+      ...(Object.keys(imageDefaults).length ? { image: imageDefaults } : {}),
     };
   }
 
@@ -5345,6 +5553,8 @@ export function registerSessionsRoutes(app, deps) {
     const change = (key) => { if (!plan.changed.includes(key)) plan.changed.push(key); };
 
     if (wanted.model !== undefined && normalizePreferredModel(wanted.model) !== normalizePreferredModel(conversation.preferred_model)) {
+      const imageRefusal = provider === 'github' ? copilotImageModelRefusal(wanted.model) : null;
+      if (imageRefusal) return fail(400, `${imageRefusal.error} Nothing was changed.`, { code: imageRefusal.code });
       plan.preferences.preferredModel = wanted.model;
       change('model');
     }
@@ -5466,6 +5676,29 @@ export function registerSessionsRoutes(app, deps) {
         change('cwd');
       }
     }
+    // An image session's defaults: what is named replaces the stored value of
+    // that option, the rest stays. Checked against the model the session has
+    // after this call; any other session is refused.
+    if (wanted.image !== undefined) {
+      // The model an image turn runs: the runtime session's (the send path's),
+      // or the one this call moves it to.
+      const imageModel = String(plan.preferences.preferredModel || runtime?.provider_model || runtime?.model || current.model || '').trim();
+      if (provider === 'github' && isOpenAIImageModelId(imageModel)) {
+        return fail(400, `${openAIImageModelNeedsOpenAIText(imageModel)} Nothing was changed.`, { code: OPENAI_IMAGE_MODEL_NEEDS_OPENAI_CODE });
+      }
+      if (provider !== 'openai' || !isOpenAIImageModelId(imageModel)) {
+        return fail(400, `Image defaults go to an OpenAI image session; this session runs ${imageModel || provider}. Nothing was changed.`, { code: IMAGE_INPUT_REFUSED_CODE });
+      }
+      const stored = readImageDefaults(conversationId);
+      const checkedImage = validateOpenAIImageOptions({ ...stored, ...wanted.image }, { model: imageModel });
+      if (!checkedImage.ok) return fail(400, `${checkedImage.error}. Nothing was changed.`, { code: IMAGE_INPUT_REFUSED_CODE });
+      const sameAsStored = Object.keys(checkedImage.values).length === Object.keys(stored).length
+        && Object.entries(checkedImage.values).every(([key, value]) => stored[key] === value);
+      if (!sameAsStored) {
+        plan.image = checkedImage.values;
+        change('image');
+      }
+    }
     plan.changed.sort((a, b) => REMOTE_RELAY_SESSION_SETTINGS.indexOf(a) - REMOTE_RELAY_SESSION_SETTINGS.indexOf(b));
     return { ok: true, plan };
   }
@@ -5627,13 +5860,22 @@ export function registerSessionsRoutes(app, deps) {
       if (!titled.ok) return failAfter(titled.statusCode || 500, { error: titled.error || 'Failed to update the title.' });
       written.push('title');
     }
+    if (plan.image) {
+      try {
+        if (typeof stmts.writeConversationImageDefaults !== 'function') throw new Error('Image session defaults are unavailable on this relay');
+        stmts.writeConversationImageDefaults(conversationId, plan.image);
+      } catch (error) {
+        return failAfter(503, { code: 'IMAGE_DEFAULTS_UNAVAILABLE', error: `${error?.message || 'The image defaults could not be stored'}.` });
+      }
+      written.push('image');
+    }
     if (Object.keys(plan.preferences).length) {
       applyConversationPreferences({
         conversationId,
         existing: stmts.getConvAnyStatus.get(conversationId),
         body: plan.preferences,
       });
-      written.push(...plan.changed.filter((key) => !['cwd', 'title', 'group'].includes(key)));
+      written.push(...plan.changed.filter((key) => !['cwd', 'title', 'group', 'image'].includes(key)));
     }
     // Groups through the agent path: an owner's group the session leaves is
     // never removed (it stays, empty if it was the last member); a group an
@@ -6674,6 +6916,12 @@ export function registerSessionsRoutes(app, deps) {
       requestedBootstrapModel
       || (isProviderModelAvailable(catalogSelectedModel, availableModels) ? catalogSelectedModel : '')
     );
+    // An OpenAI Image chat asked for without a model starts on the image
+    // default the OpenAI list offers (else its first gpt-image), never on
+    // the shared catalog's current model, which makes no images.
+    const openAIImageDefaultModel = requestedProviderType === 'openai-image' && !requestedBootstrapModel
+      ? pickOpenAIImageDefaultModel([...availableOpenAIModels])
+      : '';
     const providerModelSelection = useClaudeCloudProvider
       // The cloud takes plain ids; with no model in the request the tab's
       // default applies (never the shared catalog's current model).
@@ -6690,7 +6938,7 @@ export function registerSessionsRoutes(app, deps) {
         })
       : useOpenAIProvider
       ? resolveProviderModelSelection({
-          requestedModel: providerRequestedModel(availableOpenAIModels),
+          requestedModel: openAIImageDefaultModel || providerRequestedModel(availableOpenAIModels),
           // The removed resolveOpenAISessionModel carried this last-resort id.
           configuredModel: openAISettings.model || 'gpt-4o',
           availableModels: availableOpenAIModels,
@@ -6749,6 +6997,12 @@ export function registerSessionsRoutes(app, deps) {
         supportedModels: providerModelSelection.availableModels || [],
       });
     }
+    const useCopilotProvider = !useClaudeCloudProvider && !useOpenAIProvider && !useClaudeProvider && !useCursorProvider
+      && !useGrokProvider && !useDeepSeekProvider && !useClaudeApiProvider;
+    // A Copilot chat on an image id would reach the Copilot runtime, which
+    // cannot serve it: refused before anything is written.
+    const copilotImageRefusal = useCopilotProvider ? copilotImageModelRefusal(requestedBootstrapModel || catalogSelectedModel) : null;
+    if (copilotImageRefusal) return res.status(400).json(copilotImageRefusal);
     // Copilot falls back to the catalogue's current model for an id it does
     // not list, which New Chat (it only offers listed ids) never meets. An
     // agent naming a mistyped id ("gpt-5-4") would get a session on another
@@ -6887,6 +7141,11 @@ export function registerSessionsRoutes(app, deps) {
     }
 
     const selectedModel = providerModelSelection ? providerModelSelection.model : (copilotBoundModel || catalogSelectedModel);
+    // Asked for without a model, an image chat needs a gpt-image model in the
+    // OpenAI list; it never falls back to a chat model, which makes no images.
+    if (requestedProviderType === 'openai-image' && !requestedBootstrapModel && !openAIImageDefaultModel) {
+      return res.status(400).json({ ok: false, error: openAIImageNoModelText(), code: OPENAI_IMAGE_NO_MODEL_CODE });
+    }
     if (requestedProviderType === 'openai-image' && !isOpenAIImageModelId(selectedModel)) {
       return res.status(400).json({
         ok: false,
@@ -7152,8 +7411,12 @@ export function registerSessionsRoutes(app, deps) {
           runtimeSessionId: runtimeSession?.id || null,
           status: workerState?.status || 'ready',
         });
-        const pendingDepth = Number(queueCounts?.().pendingCount || 0);
-        sessionWorkerSupervisor?.markIdle?.(ownerSessionId, pendingDepth);
+        // A deferred start (the agent SDK still installs) has no worker to
+        // call idle: it launches when the install ends.
+        if (!ensureResult.deferred) {
+          const pendingDepth = Number(queueCounts?.().pendingCount || 0);
+          sessionWorkerSupervisor?.markIdle?.(ownerSessionId, pendingDepth);
+        }
       } else if (ownerSessionId) {
         // Same state as the 409 above: the conversation is committed, only the
         // worker is missing, so the client gets what it needs to open it.
@@ -7345,6 +7608,73 @@ export function registerSessionsRoutes(app, deps) {
     });
   });
 
+  // ─── OpenAI image spend: the daily cap and the owner's override ─────────────
+  // app_settings values here are JSON; a bare string reads as itself.
+  const readJsonAppSetting = (key) => {
+    let row = null;
+    try {
+      row = stmts.getAppSetting?.get?.(key) || null;
+    } catch {
+      row = null;
+    }
+    if (!row || row.value === null || row.value === undefined) return undefined;
+    try {
+      return JSON.parse(row.value);
+    } catch {
+      return row.value;
+    }
+  };
+  // The relay's local day, the one image spend is booked and capped by.
+  const relayLocalDay = () => {
+    try {
+      const day = String(tokenUsageService?.localDay?.() || '');
+      if (/^\d{4}-\d{2}-\d{2}$/.test(day)) return day;
+    } catch {}
+    const now = new Date();
+    return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+  };
+  /**
+   * The cap fields every OpenAI settings answer carries: `imageDailyCapUsd`
+   * (USD; 0 = no cap; never saved = the default), `imagesAllowedToday` (the
+   * owner allowed image turns past the cap for the relay's current day) and
+   * `imagesAllowedAt` (when, while it holds).
+   */
+  const openAIImageSpendSettingsPayload = () => {
+    const stored = readJsonAppSetting(OPENAI_IMAGE_SPEND_SETTING_KEYS.dailyCapUsd);
+    const cap = stored === undefined ? OPENAI_IMAGE_DAILY_CAP_DEFAULT_USD : Number(stored);
+    const allowed = readJsonAppSetting(OPENAI_IMAGE_SPEND_SETTING_KEYS.overrideDay) === relayLocalDay();
+    const allowedAt = allowed ? readJsonAppSetting(OPENAI_IMAGE_SPEND_SETTING_KEYS.overrideAt) : null;
+    return {
+      // An unreadable value is the default, never "no cap".
+      imageDailyCapUsd: Number.isFinite(cap) && cap >= 0 ? cap : OPENAI_IMAGE_DAILY_CAP_DEFAULT_USD,
+      imagesAllowedToday: allowed,
+      imagesAllowedAt: allowed && typeof allowedAt === 'string' ? allowedAt : null,
+    };
+  };
+  /** Writes the parsed cap fields together; throws when the settings cannot be written. */
+  const writeOpenAIImageSpendSettings = (change) => {
+    if (typeof stmts?.upsertAppSetting?.run !== 'function' || typeof stmts?.deleteAppSetting?.run !== 'function') {
+      throw new Error('OpenAI image settings are unavailable');
+    }
+    const nowIso = new Date().toISOString();
+    db.transaction(() => {
+      if (change.dailyCapUsd !== undefined) {
+        stmts.upsertAppSetting.run(OPENAI_IMAGE_SPEND_SETTING_KEYS.dailyCapUsd, JSON.stringify(change.dailyCapUsd), nowIso);
+      }
+      // Changing the cap keeps the override; only the switch sets or ends it.
+      if (change.allowToday === true) {
+        stmts.upsertAppSetting.run(OPENAI_IMAGE_SPEND_SETTING_KEYS.overrideDay, JSON.stringify(relayLocalDay()), nowIso);
+        stmts.upsertAppSetting.run(OPENAI_IMAGE_SPEND_SETTING_KEYS.overrideAt, JSON.stringify(nowIso), nowIso);
+      } else if (change.allowToday === false) {
+        stmts.deleteAppSetting.run(OPENAI_IMAGE_SPEND_SETTING_KEYS.overrideDay);
+        stmts.deleteAppSetting.run(OPENAI_IMAGE_SPEND_SETTING_KEYS.overrideAt);
+      }
+    })();
+    try {
+      notifyOpenAIImageSpendChanged();
+    } catch {}
+  };
+
   app.get('/api/settings/openai', auth, (_req, res) => {
     const settings = getOpenAIProviderSettings();
     return res.json({
@@ -7352,12 +7682,43 @@ export function registerSessionsRoutes(app, deps) {
       enabled: settings?.enabled === true,
       model: String(settings?.model || 'gpt-4o').trim() || 'gpt-4o',
       baseUrl: String(settings?.baseUrl || 'https://api.openai.com/v1').trim() || 'https://api.openai.com/v1',
+      // What New Chat preselects for an OpenAI Image chat (null: no image model on).
+      imageDefaultModel: settings?.enabled === true
+        ? (pickOpenAIImageDefaultModel([settings.model, ...(Array.isArray(settings.models) ? settings.models : [])]) || null)
+        : null,
+      ...openAIImageSpendSettingsPayload(),
     });
   });
 
   app.post('/api/settings/openai', auth, async (req, res) => {
+    // The image cap and "Allow for today" are the owner's alone: an agent of
+    // this relay or a paired one could lift the cap on itself. Nothing of the
+    // request is applied then.
+    const imageSpend = parseOpenAIImageSpendSettingsRequest(req.body);
+    if (imageSpend.present && readRemoteRelayRequest(req, remoteRelayInbound).remote) {
+      return res.status(403).json({ error: 'The OpenAI image cap and "Allow for today" are this relay\'s owner\'s settings alone.' });
+    }
+    if (!imageSpend.ok) return res.status(400).json({ error: imageSpend.error });
     const parsed = parseOpenAISettingsUpdateRequest(req.body);
-    if (!parsed.ok) return res.status(400).json({ error: parsed.error });
+    if (!parsed.ok && !(parsed.empty && imageSpend.present)) return res.status(400).json({ error: parsed.error });
+    if (!parsed.ok) {
+      // The cap fields alone: the provider settings stay as they are.
+      try {
+        writeOpenAIImageSpendSettings(imageSpend);
+      } catch (error) {
+        return res.status(500).json({ error: String(error?.message || error) });
+      }
+      const current = getOpenAIProviderSettings();
+      const payload = {
+        configured: current?.configured === true,
+        enabled: current?.enabled === true,
+        model: String(current?.model || 'gpt-4o').trim() || 'gpt-4o',
+        baseUrl: String(current?.baseUrl || 'https://api.openai.com/v1').trim() || 'https://api.openai.com/v1',
+        ...openAIImageSpendSettingsPayload(),
+      };
+      io.emit('openai_settings_updated', payload);
+      return res.json({ ok: true, ...payload, models: [], warning: null });
+    }
     const previous = getOpenAIProviderSettings();
     const result = setOpenAIProviderSettings(parsed);
     if (!result?.ok) {
@@ -7370,6 +7731,14 @@ export function registerSessionsRoutes(app, deps) {
         activeQueueConversationCount: Number(result?.activeQueueConversationCount || 0),
       });
     }
+    let imageSpendError = null;
+    if (imageSpend.present) {
+      try {
+        writeOpenAIImageSpendSettings(imageSpend);
+      } catch (error) {
+        imageSpendError = `The image cap was not saved: ${String(error?.message || error)}`;
+      }
+    }
     const shouldDiscover = result.enabled === true && (
       !!parsed.apiKey
       || previous?.enabled !== true
@@ -7408,8 +7777,9 @@ export function registerSessionsRoutes(app, deps) {
       model: String(currentSettings?.model || result.model || 'gpt-4o').trim() || 'gpt-4o',
       baseUrl: String(currentSettings?.baseUrl || 'https://api.openai.com/v1').trim() || 'https://api.openai.com/v1',
       reconciliation,
+      ...openAIImageSpendSettingsPayload(),
     };
-    io.emit('models_updated', buildModelCatalogWithProviders(
+    io.emit('models_updated', modelsUpdatedPayload(
       getModelCatalogState(),
       currentSettings,
     ));
@@ -7421,12 +7791,60 @@ export function registerSessionsRoutes(app, deps) {
       ok: true,
       ...settingsPayload,
       models: Array.isArray(discovery?.models) ? discovery.models : [],
-      warning: reconciliationFailures.length
+      warning: imageSpendError || (reconciliationFailures.length
         ? `${reconciliationFailures.length} unstarted conversation(s) could not switch provider.`
-        : (discovery?.ok ? null : (discovery?.error || 'OpenAI model discovery failed')),
+        : (discovery?.ok ? null : (discovery?.error || 'OpenAI model discovery failed'))),
     });
   });
 
+  // ─── OpenAI image presets ─────────────────────────────────────────────────
+  // The built-ins and the owner's own (app_settings openai_image_presets).
+  // Every change is one preset, read and written in one transaction, so two
+  // pages saving at once cannot drop each other's preset. A paired relay's
+  // agent may read them (relay_info lists them) but never change them.
+  const readOwnOpenAIImagePresets = () => parseOwnOpenAIImagePresets(readJsonAppSetting(OPENAI_IMAGE_PRESETS_SETTING_KEY) ?? []);
+  const openAIImagePresetsPayload = (own = readOwnOpenAIImagePresets()) => ({ presets: listOpenAIImagePresets(own) });
+  const changeOwnOpenAIImagePresets = (req, res, change) => {
+    if (readRemoteRelayRequest(req, remoteRelayInbound).remote) {
+      return res.status(403).json({ error: 'Image presets are changed by this relay\'s owner only.' });
+    }
+    if (typeof stmts?.upsertAppSetting?.run !== 'function') {
+      return res.status(500).json({ error: 'Image preset settings are unavailable' });
+    }
+    let outcome;
+    try {
+      outcome = db.transaction(() => {
+        const applied = applyOwnOpenAIImagePresetChange(readOwnOpenAIImagePresets(), change);
+        if (applied.ok) {
+          stmts.upsertAppSetting.run(OPENAI_IMAGE_PRESETS_SETTING_KEY, JSON.stringify(applied.presets), new Date().toISOString());
+        }
+        return applied;
+      })();
+    } catch (error) {
+      return res.status(500).json({ error: String(error?.message || error) });
+    }
+    if (!outcome.ok) {
+      return res.status(400).json({ error: outcome.error, code: OPENAI_IMAGE_PRESET_REFUSED_CODE });
+    }
+    const payload = openAIImagePresetsPayload(outcome.presets);
+    io.emit('openai_image_presets_updated', payload);
+    return res.json({ ok: true, ...payload });
+  };
+
+  app.get(OPENAI_IMAGE_PRESETS_PATH, auth, (_req, res) => res.json(openAIImagePresetsPayload()));
+
+  // body { preset: { name, size?, quality?, count?, output_format?, background? }, replace? }
+  app.put(OPENAI_IMAGE_PRESETS_PATH, auth, (req, res) => changeOwnOpenAIImagePresets(req, res, {
+    op: 'put',
+    preset: req.body?.preset ?? null,
+    replace: req.body?.replace === true,
+  }));
+
+  app.delete(`${OPENAI_IMAGE_PRESETS_PATH}/:name`, auth, (req, res) => changeOwnOpenAIImagePresets(req, res, {
+    op: 'delete',
+    name: String(req.params?.name ?? ''),
+  }));
+
   // Copilot has no credentials or model list of its own in settings (it
   // authenticates through the host's `copilot` login and its catalog comes from
   // the CLI), so this pair carries exactly one thing: which engine runs it.
@@ -7523,7 +7941,7 @@ export function registerSessionsRoutes(app, deps) {
       ...claudeBackgroundCommandLimitSettingsFields(currentSettings),
       reconciliation,
     };
-    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
     io.emit('claude_settings_updated', settingsPayload);
     const reconciliationFailures = Array.isArray(reconciliation?.failedConversations)
       ? reconciliation.failedConversations
@@ -7646,7 +8064,7 @@ export function registerSessionsRoutes(app, deps) {
       console.log(`[claude-auth] model refresh after login failed: ${error?.message || error}`);
     }
     const settings = getClaudeProviderSettings();
-    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
     io.emit('claude_settings_updated', {
       configured: settings?.configured === true,
       enabled: settings?.enabled === true,
@@ -7738,7 +8156,7 @@ export function registerSessionsRoutes(app, deps) {
         console.log(`[cli-install] Grok model refresh after install failed: ${error?.message || error}`);
       }
       const settings = getGrokProviderSettings();
-      io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+      io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
       io.emit('grok_settings_updated', {
         configured: settings?.configured === true,
         enabled: settings?.enabled === true,
@@ -7755,7 +8173,7 @@ export function registerSessionsRoutes(app, deps) {
         console.log(`[cli-install] Claude model refresh after install failed: ${error?.message || error}`);
       }
       const settings = getClaudeProviderSettings();
-      io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+      io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
       io.emit('claude_settings_updated', {
         configured: settings?.configured === true,
         enabled: settings?.enabled === true,
@@ -7939,7 +8357,7 @@ export function registerSessionsRoutes(app, deps) {
       console.log(`[grok-auth] model refresh after login failed: ${error?.message || error}`);
     }
     const settings = getGrokProviderSettings();
-    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
     io.emit('grok_settings_updated', {
       configured: settings?.configured === true,
       enabled: settings?.enabled === true,
@@ -8040,7 +8458,7 @@ export function registerSessionsRoutes(app, deps) {
       availableModels: Array.isArray(currentSettings?.availableModels) ? currentSettings.availableModels : [],
       reconciliation,
     };
-    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
     io.emit('grok_settings_updated', settingsPayload);
     const reconciliationFailures = Array.isArray(reconciliation?.failedConversations)
       ? reconciliation.failedConversations
@@ -8176,7 +8594,7 @@ export function registerSessionsRoutes(app, deps) {
       availableModels: Array.isArray(currentSettings?.availableModels) ? currentSettings.availableModels : [],
       reconciliation,
     };
-    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
     io.emit('cursor_settings_updated', settingsPayload);
     const reconciliationFailures = Array.isArray(reconciliation?.failedConversations)
       ? reconciliation.failedConversations
@@ -8270,7 +8688,7 @@ export function registerSessionsRoutes(app, deps) {
         failedConversations,
       },
     };
-    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
     io.emit('deepseek_settings_updated', settingsPayload);
     return res.json({
       ok: true,
@@ -8324,7 +8742,7 @@ export function registerSessionsRoutes(app, deps) {
         failedConversations,
       },
     };
-    io.emit('models_updated', buildModelCatalogWithProviders(getModelCatalogState()));
+    io.emit('models_updated', modelsUpdatedPayload(getModelCatalogState()));
     io.emit('claude_api_settings_updated', settingsPayload);
     try { claudeApiStopLedger?.clearAll?.(); } catch {}
     try { checkClaudeApiCap('settings'); } catch {}
@@ -8910,9 +9328,19 @@ export function registerSessionsRoutes(app, deps) {
     });
   });
 
+  // Each provider tab's switch, "New" tags and fallback warning.
+  function modelStateFields(settings) {
+    return {
+      autoEnableNew: settings?.autoEnableNew !== false,
+      unseen: Array.isArray(settings?.unseenModels) ? settings.unseenModels : [],
+      fallback: settings?.fallback === true,
+    };
+  }
+
   function buildModelVariantCatalogPayloadForRoute() {
     const rows = typeof listModelVariantRows === 'function' ? listModelVariantRows() : [];
     const modelState = getModelCatalogState();
+    const openAISettings = getOpenAIProviderSettings();
     const claudeSettings = getClaudeProviderSettings();
     const cursorSettings = getCursorProviderSettings();
     const grokSettings = getGrokProviderSettings();
@@ -8926,11 +9354,21 @@ export function registerSessionsRoutes(app, deps) {
         contextLimitsByModel: modelState.contextLimitsByModel || {},
         modelMetadataByModel: modelState.modelMetadataByModel || {},
       }),
+      copilotModelState: getCopilotModelState(),
+      openaiModels: openAISettings?.enabled === true
+        ? {
+            defaultModel: openAISettings.model,
+            availableModels: Array.isArray(openAISettings.availableModels) ? openAISettings.availableModels : [],
+            enabledModels: Array.isArray(openAISettings.models) ? openAISettings.models : [],
+            ...modelStateFields(openAISettings),
+          }
+        : null,
       claudeModels: claudeSettings?.enabled === true
         ? {
             defaultModel: claudeSettings.model,
             availableModels: Array.isArray(claudeSettings.availableModels) ? claudeSettings.availableModels : [],
             enabledModels: Array.isArray(claudeSettings.models) ? claudeSettings.models : [],
+            ...modelStateFields(claudeSettings),
           }
         : null,
       cursorModels: cursorSettings?.enabled === true
@@ -8938,6 +9376,7 @@ export function registerSessionsRoutes(app, deps) {
             defaultModel: cursorSettings.model,
             availableModels: Array.isArray(cursorSettings.availableModels) ? cursorSettings.availableModels : [],
             enabledModels: Array.isArray(cursorSettings.models) ? cursorSettings.models : [],
+            ...modelStateFields(cursorSettings),
           }
         : null,
       grokModels: grokSettings?.enabled === true
@@ -8945,6 +9384,7 @@ export function registerSessionsRoutes(app, deps) {
             defaultModel: grokSettings.model,
             availableModels: Array.isArray(grokSettings.availableModels) ? grokSettings.availableModels : [],
             enabledModels: Array.isArray(grokSettings.models) ? grokSettings.models : [],
+            ...modelStateFields(grokSettings),
           }
         : null,
       deepseekModels: deepseekSettings?.enabled === true
@@ -8952,6 +9392,7 @@ export function registerSessionsRoutes(app, deps) {
             defaultModel: deepseekSettings.model,
             availableModels: Array.isArray(deepseekSettings.availableModels) ? deepseekSettings.availableModels : [],
             enabledModels: Array.isArray(deepseekSettings.models) ? deepseekSettings.models : [],
+            ...modelStateFields(deepseekSettings),
           }
         : null,
       // The Select Models → Claude API tab: its own list, "[1m]" ids included
@@ -8962,6 +9403,7 @@ export function registerSessionsRoutes(app, deps) {
             availableModels: Array.isArray(claudeApiSettings.availableModels) ? claudeApiSettings.availableModels : [],
             enabledModels: Array.isArray(claudeApiSettings.models) ? claudeApiSettings.models : [],
             discovered: claudeApiSettings.discovered === true,
+            ...modelStateFields(claudeApiSettings),
           }
         : null,
     };
@@ -8978,101 +9420,28 @@ export function registerSessionsRoutes(app, deps) {
       return res.status(501).json({ error: 'Model refresh is unavailable' });
     }
     try {
-      const openAISettings = getOpenAIProviderSettings();
-      const claudeSettings = getClaudeProviderSettings();
-      const cursorSettings = getCursorProviderSettings();
-      const grokSettings = getGrokProviderSettings();
-      const deepseekSettings = getDeepSeekProviderSettings();
-      const claudeApiSettings = getClaudeApiProviderSettings();
-      const refreshTasks = [
+      // The help-text CLI refresh beside every enabled provider's discovery
+      // (provider-model-refresh.mjs; Copilot discovery gates itself on an
+      // installed CLI). Only a failed CLI refresh fails the request.
+      const [cliRefresh, providerRefresh] = await Promise.allSettled([
         refreshModelVariantCatalogFromCli(),
-        openAISettings?.enabled === true
-          ? refreshOpenAIProviderModels()
-          : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
-        claudeSettings?.enabled === true
-          ? refreshClaudeProviderModels()
-          : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
-        cursorSettings?.enabled === true
-          ? refreshCursorProviderModels()
-          : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
-        grokSettings?.enabled === true
-          ? refreshGrokProviderModels()
-          : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
-        // Copilot SDK discovery self-gates on an installed CLI (skipped:true
-        // when there is none), so unlike the providers above it has no
-        // enablement flag to check here.
-        typeof copilotModelDiscoveryService?.refresh === 'function'
-          ? copilotModelDiscoveryService.refresh('manual-refresh')
-          : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
-        deepseekSettings?.enabled === true && deepseekSettingsService
-          ? deepseekSettingsService.refreshModels()
-          : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
-        claudeApiSettings?.enabled === true && claudeApiSettingsService
-          ? claudeApiSettingsService.refreshModels()
-          : Promise.resolve({ ok: true, skipped: true, models: [], error: null }),
-      ];
-      const [
-        cliRefresh, openAIRefresh, claudeRefresh, cursorRefresh, grokRefresh, copilotDiscoveryRefresh, deepseekRefresh, claudeApiRefresh,
-      ] = await Promise.allSettled(refreshTasks);
+        refreshProviderModels({ table: providerRefreshTable, reason: 'manual-refresh' }),
+      ]);
       if (cliRefresh.status === 'rejected') throw cliRefresh.reason;
-      const openAIModelDiscovery = openAIRefresh.status === 'fulfilled'
-        ? openAIRefresh.value
-        : {
-            ok: false,
-            models: Array.isArray(openAISettings?.models) ? openAISettings.models : [],
-            error: openAIRefresh.reason?.message || 'OpenAI model discovery failed',
-          };
-      const claudeModelDiscovery = claudeRefresh.status === 'fulfilled'
-        ? claudeRefresh.value
-        : {
-            ok: false,
-            models: Array.isArray(claudeSettings?.models) ? claudeSettings.models : [],
-            error: claudeRefresh.reason?.message || 'Claude model discovery failed',
-          };
-      const cursorModelDiscovery = cursorRefresh.status === 'fulfilled'
-        ? cursorRefresh.value
-        : {
-            ok: false,
-            models: Array.isArray(cursorSettings?.models) ? cursorSettings.models : [],
-            error: cursorRefresh.reason?.message || 'Cursor model discovery failed',
-          };
-      const grokModelDiscovery = grokRefresh.status === 'fulfilled'
-        ? grokRefresh.value
-        : {
-            ok: false,
-            models: Array.isArray(grokSettings?.models) ? grokSettings.models : [],
-            error: grokRefresh.reason?.message || 'Grok model discovery failed',
-          };
-      const deepseekModelDiscovery = deepseekRefresh.status === 'fulfilled'
-        ? deepseekRefresh.value
-        : {
-            ok: false,
-            models: Array.isArray(deepseekSettings?.models) ? deepseekSettings.models : [],
-            error: deepseekRefresh.reason?.message || 'DeepSeek model discovery failed',
-          };
-      const claudeApiModelDiscovery = claudeApiRefresh.status === 'fulfilled'
-        ? claudeApiRefresh.value
-        : {
-            ok: false,
-            models: Array.isArray(claudeApiSettings?.models) ? claudeApiSettings.models : [],
-            error: claudeApiRefresh.reason?.message || 'Claude API model discovery failed',
-          };
-      const copilotModelDiscovery = copilotDiscoveryRefresh.status === 'fulfilled'
-        ? copilotDiscoveryRefresh.value
-        : { ok: false, models: [], error: copilotDiscoveryRefresh.reason?.message || 'Copilot model discovery failed' };
-      io.emit('models_updated', buildModelCatalogWithProviders(
+      const results = providerRefresh.status === 'fulfilled' ? providerRefresh.value.results : {};
+      io.emit('models_updated', modelsUpdatedPayload(
         getModelCatalogState(),
       ));
       return res.json({
         ok: true,
         ...buildModelVariantCatalogPayloadForRoute(),
-        openAIModelDiscovery,
-        claudeModelDiscovery,
-        cursorModelDiscovery,
-        grokModelDiscovery,
-        deepseekModelDiscovery,
-        claudeApiModelDiscovery,
-        copilotModelDiscovery,
+        openAIModelDiscovery: results.openai,
+        claudeModelDiscovery: results.claude,
+        cursorModelDiscovery: results.cursor,
+        grokModelDiscovery: results.grok,
+        deepseekModelDiscovery: results.deepseek,
+        claudeApiModelDiscovery: results['claude-api'],
+        copilotModelDiscovery: results.github,
       });
     } catch (error) {
       return res.status(500).json({
@@ -9087,11 +9456,28 @@ export function registerSessionsRoutes(app, deps) {
     if (typeof setEnabledModelVariants !== 'function') {
       return res.status(501).json({ error: 'Model variant updates are unavailable' });
     }
-    const enabledVariantIds = Array.isArray(req.body?.enabledVariantIds)
+    const hasVariantIds = Array.isArray(req.body?.enabledVariantIds);
+    const autoEnableNew = req.body?.autoEnableNew;
+    if (autoEnableNew !== undefined && typeof autoEnableNew !== 'boolean') {
+      return res.status(400).json({ error: 'autoEnableNew must be true or false' });
+    }
+    if (!hasVariantIds && autoEnableNew === undefined) {
+      return res.status(400).json({ error: 'No model variant update provided' });
+    }
+    const enabledVariantIds = hasVariantIds
       ? req.body.enabledVariantIds.map((value) => String(value || '').trim()).filter(Boolean)
       : [];
-    setEnabledModelVariants(enabledVariantIds);
-    io.emit('models_updated', buildModelCatalogWithProviders(
+    // Every row off would leave the pickers with the fallback model only.
+    if (hasVariantIds && !enabledVariantIds.length) {
+      return res.status(400).json({ error: 'Select at least one model variant' });
+    }
+    // The rows the browser drew: only those change (an older page sends none).
+    const shownVariantIds = Array.isArray(req.body?.shownVariantIds)
+      ? req.body.shownVariantIds.map((value) => String(value || '').trim()).filter(Boolean)
+      : null;
+    if (hasVariantIds) setEnabledModelVariants(enabledVariantIds, shownVariantIds ? { shownVariantIds } : undefined);
+    if (typeof autoEnableNew === 'boolean') setCopilotAutoEnableNew?.(autoEnableNew);
+    io.emit('models_updated', modelsUpdatedPayload(
       getModelCatalogState(),
     ));
     return res.json({
@@ -9100,6 +9486,74 @@ export function registerSessionsRoutes(app, deps) {
     });
   });
 
+  // Select Models was opened: every provider's "New" flags clear.
+  app.post('/api/model-variants/seen', auth, (req, res) => {
+    ensureSessionId(req, res);
+    const markers = [
+      () => markCopilotModelsSeen(),
+      () => markProviderModelsSeen('openai'),
+      () => markProviderModelsSeen('claude'),
+      () => markProviderModelsSeen('cursor'),
+      () => markProviderModelsSeen('grok'),
+      () => deepseekSettingsService?.markModelsSeen?.() === true,
+      () => claudeApiSettingsService?.markModelsSeen?.() === true,
+    ];
+    let changed = false;
+    for (const mark of markers) {
+      try {
+        if (mark() === true) changed = true;
+      } catch {
+        /* one provider's map does not hold up the others */
+      }
+    }
+    if (changed) {
+      io.emit('models_updated', modelsUpdatedPayload(
+        getModelCatalogState(),
+      ));
+    }
+    return res.json({ ok: true, unseenNewModelCount: countUnseenNewModels() });
+  });
+
+  // "Check for new models" (Settings → General → Models): the switch, the
+  // interval, the providers left out, and each enabled provider's last check.
+  function modelRefreshSettingsPayload(settings) {
+    const last = modelRefreshLedger?.readLast?.() || {};
+    const lastOf = (id) => (last[id] ? { at: last[id].at, ok: last[id].ok, error: last[id].error } : null);
+    const ask = (id, gate) => {
+      try {
+        return providerRefreshTable[id]?.[gate]?.() === true;
+      } catch {
+        return false;
+      }
+    };
+    // Every switched-on provider; one that is not set up is not checked and
+    // says so.
+    const providers = MODEL_REFRESH_PROVIDERS
+      .filter(({ id }) => ask(id, 'isEnabled'))
+      .map(({ id, label }) => ({ id, label, setUp: ask(id, 'isSetUp'), last: lastOf(id) }));
+    return {
+      auto: settings.auto,
+      intervalHours: settings.intervalHours,
+      intervalChoices: [...MODEL_REFRESH_INTERVAL_HOURS_CHOICES],
+      default: { auto: DEFAULT_MODEL_REFRESH_AUTO, intervalHours: DEFAULT_MODEL_REFRESH_INTERVAL_HOURS },
+      excluded: settings.excluded,
+      providers,
+      last: Object.fromEntries(Object.keys(last).map((id) => [id, { at: last[id].at, ok: last[id].ok }])),
+    };
+  }
+
+  app.get('/api/model-refresh-settings', auth, (_req, res) => {
+    if (!modelRefreshSettings) return res.status(501).json({ error: 'Model refresh settings are unavailable' });
+    return res.json(modelRefreshSettingsPayload(modelRefreshSettings.get()));
+  });
+
+  app.post('/api/model-refresh-settings', auth, (req, res) => {
+    if (!modelRefreshSettings) return res.status(501).json({ error: 'Model refresh settings are unavailable' });
+    const result = modelRefreshSettings.update(req.body);
+    if (!result.ok) return res.status(400).json({ error: result.error });
+    return res.json(modelRefreshSettingsPayload(result.settings));
+  });
+
   app.get('/api/models', auth, (req, res) => {
     ensureSessionId(req, res);
     const modelState = buildModelCatalogWithProviders(
@@ -9121,6 +9575,8 @@ export function registerSessionsRoutes(app, deps) {
       claudeContextTiersByModel: modelState.claudeContextTiersByModel || {},
       claudeApiContextTiersByModel: modelState.claudeApiContextTiersByModel || {},
       providersByModel: modelState.providersByModel || {},
+      // Models flagged new in Select Models: the menu item's dot.
+      unseenNewModelCount: countUnseenNewModels(),
       stale: modelState.stale,
       metadataValid: modelState.metadataValid === true,
       reasoningMetadataValid: modelState.reasoningMetadataValid === true,
@@ -9142,7 +9598,7 @@ export function registerSessionsRoutes(app, deps) {
       source: source || 'relay-extension',
       error,
     });
-    io.emit('models_updated', buildModelCatalogWithProviders(
+    io.emit('models_updated', modelsUpdatedPayload(
       getModelCatalogState(),
     ));
     res.json({
@@ -9326,6 +9782,23 @@ export function registerSessionsRoutes(app, deps) {
       deepseekActuals: deepseekEnabled ? readDeepSeekActuals() : null,
       claudeApiCard,
     });
+    // OpenAI images: today's spend against the daily cap, from the booking.
+    if (typeof getOpenAIImageSpendState === 'function') {
+      const conversationId = String(req.query?.conversationId || '').trim();
+      let imageSpendState = null;
+      let imageSpendError = null;
+      try {
+        imageSpendState = await getOpenAIImageSpendState(conversationId ? { conversationId } : {});
+      } catch (error) {
+        imageSpendError = String(error?.message || error);
+      }
+      let openAIConfigured = false;
+      try {
+        openAIConfigured = getOpenAIProviderSettings()?.configured === true;
+      } catch {}
+      const imageCard = buildOpenAIImagePlanCard({ state: imageSpendState, error: imageSpendError, configured: openAIConfigured });
+      if (imageCard && Array.isArray(report.providers)) report.providers.push(imageCard);
+    }
     // Every tab's Tokens sections, from the token booking.
     if (tokenUsageService) {
       appendTokenSections(report.providers, (options) => tokenUsageService.readPeriods(options), {