@oar-sh/oar 0.9.23 → 0.9.25

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,12 +27,30 @@ 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
-// messages.) Any other table with a row makes the start refuse.
-export const STARTUP_TABLES = Object.freeze(['model_variants', 'model_selector_state', 'relay_restart_orchestrator']);
+// catalog and its refresh state, the restart orchestrator's one row, the
+// media index's extractor version (migration 0039; its items and queue
+// follow messages and stay empty without them). (The shadow tables of the
+// message search are left out too: they follow messages.) Any other table
+// with a row makes the start refuse.
+export const STARTUP_TABLES = Object.freeze(['model_variants', 'model_selector_state', 'relay_restart_orchestrator', 'media_index_meta']);
 
 /** A database's files: the main file, its -wal and its -shm. */
 export function sideFiles(name) {

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,7 +9,7 @@ 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 copies the install-time rescue of 0.9.14 to 0.9.22 made, in the data folder.
@@ -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/generated-image-cleanup-service.mjs

@@ -25,7 +25,8 @@ function parseMessageAttachments(rawAttachments, { parseAttachments, hydrateAtta
   return attachments.map((entry) => hydrateAttachment(entry)).filter(Boolean);
 }
 
-function resolveGeneratedImagePath({
+/** The file of a generated-image attachment under `root`, or null for one that would leave its folder. */
+export function resolveGeneratedImagePath({
   root,
   sessionId,
   relativePath,

package/server/services/generated-image-files.mjs

@@ -0,0 +1,110 @@
+'use strict';
+
+import fs from 'fs';
+
+import { IMAGE_HEADER_BYTES, readImageHeader } from '../../shared/image-header.mjs';
+import { resolveGeneratedImagePath } from './generated-image-cleanup-service.mjs';
+
+// A generated image's attachment as GET /api/conversation/:id serves it: its
+// absolute file on this relay (`generatedImage.path`) and its pixel size, so
+// another relay's agent can name the file in a later send. The path is worked
+// out on every read, never stored: checkouts and state folders move.
+
+// PNG and WebP headers sit in the first bytes; a JPEG's frame header comes
+// after its EXIF/ICC blocks, so only a JPEG that needs more reads further.
+const FIRST_READ_BYTES = 4096;
+
+// The conversation page is polled: a file read once is not read again while
+// its size and time stay the same.
+const HEADER_CACHE_MAX = 500;
+const headerCache = new Map();
+
+function readFirstBytes(filePath, length) {
+  let fd = null;
+  try {
+    fd = fs.openSync(filePath, 'r');
+    const buffer = Buffer.alloc(length);
+    const read = fs.readSync(fd, buffer, 0, length, 0);
+    return buffer.subarray(0, read);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); } catch {}
+    }
+  }
+}
+
+function imageHeaderOf(filePath, stat) {
+  const cached = headerCache.get(filePath);
+  if (cached && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) return cached.header;
+  const first = readFirstBytes(filePath, Math.min(FIRST_READ_BYTES, stat.size));
+  let header = first ? readImageHeader(first) : null;
+  if (!header && first && first[0] === 0xff && first[1] === 0xd8 && stat.size > first.length) {
+    const more = readFirstBytes(filePath, Math.min(IMAGE_HEADER_BYTES, stat.size));
+    header = more ? readImageHeader(more) : null;
+  }
+  if (headerCache.size >= HEADER_CACHE_MAX) headerCache.delete(headerCache.keys().next().value);
+  headerCache.set(filePath, { size: stat.size, mtimeMs: stat.mtimeMs, header });
+  return header;
+}
+
+function positiveInt(value) {
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+function withFile(attachment, root) {
+  const { path: _stored, ...generatedImage } = attachment.generatedImage;
+  const bare = { ...attachment, generatedImage };
+  const filePath = resolveGeneratedImagePath({
+    root,
+    sessionId: generatedImage.sessionId,
+    relativePath: generatedImage.relativePath,
+  });
+  if (!filePath) return bare;
+  let stat = null;
+  try {
+    stat = fs.statSync(filePath, { throwIfNoEntry: false }) || null;
+  } catch {}
+  if (!stat?.isFile()) return bare;
+  const width = positiveInt(attachment.width);
+  const height = positiveInt(attachment.height);
+  // New attachments carry their size; older ones are read.
+  const header = width && height ? null : imageHeaderOf(filePath, stat);
+  return {
+    ...bare,
+    ...(header ? { width: header.width, height: header.height } : {}),
+    ...(!attachment.type && header?.mime ? { type: header.mime } : {}),
+    generatedImage: { ...generatedImage, path: filePath },
+  };
+}
+
+/**
+ * `messages` with each generated-image attachment given its file path and
+ * pixel size, when the file is there. Messages without one come back as they
+ * are; a missing or unreadable file leaves the attachment without a path.
+ * Never throws.
+ */
+export function withGeneratedImageFiles(messages, { resolveSessionStateRoot } = {}) {
+  if (!Array.isArray(messages) || typeof resolveSessionStateRoot !== 'function') return messages;
+  let root = '';
+  try {
+    root = String(resolveSessionStateRoot() || '').trim();
+  } catch {}
+  if (!root) return messages;
+  return messages.map((message) => {
+    const attachments = Array.isArray(message?.attachments) ? message.attachments : null;
+    if (!attachments || !attachments.some((entry) => entry?.generatedImage && typeof entry.generatedImage === 'object')) return message;
+    return {
+      ...message,
+      attachments: attachments.map((entry) => {
+        if (!entry?.generatedImage || typeof entry.generatedImage !== 'object') return entry;
+        try {
+          return withFile(entry, root);
+        } catch {
+          return entry;
+        }
+      }),
+    };
+  });
+}