mixdog 1.3.0 → 1.3.2

package/src/runtime/local-provider/server.mjs

@@ -1,5 +1,4 @@
-import { existsSync } from 'node:fs';
-
+import { fileHasData } from '../shared/file-has-data.mjs';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 import {
   exactLocalProviderFile,
@@ -65,7 +64,7 @@ export async function ensureLocalProviderServer(modelId, { dataDir = resolvePlug
   const contextWindow = localContextSettings(entry, dataDir).contextWindow;
   const executable = localProviderRuntimeExecutable(dataDir);
   const weights = localProviderModelPath(entry, dataDir);
-  if (!executable || !existsSync(executable)) {
+  if (!executable || !fileHasData(executable)) {
     throw new Error('[local-provider] runtime is not installed');
   }
   if (!exactLocalProviderFile(weights, entry.size)) {

package/src/runtime/media/adapters/image-api.mjs

@@ -0,0 +1,89 @@
+/**
+ * Normalized Image API adapter for the `openrouter` and `nano-gpt` lanes.
+ *
+ * Both gateways document the same contract: POST {base}/images with `model`,
+ * `prompt`, the model's advertised enum parameters and `input_references`
+ * (image_url parts; data URLs accepted), answering `data[].b64_json` (NanoGPT
+ * may answer a signed `url` instead) plus `usage`.
+ *   https://openrouter.ai/docs/guides/overview/multimodal/image-generation
+ *   https://docs.nano-gpt.com/api-reference/image-generation
+ */
+import { resolveImageApiAuth } from '../auth.mjs';
+import { timeoutSignal } from '../bounded-signal.mjs';
+import { decodeBase64Media, downloadPublicMedia } from '../download.mjs';
+import { mediaError } from '../lanes.mjs';
+import { imageApiUsage, withReportedUsage } from '../media-usage.mjs';
+import { upstreamError } from '../upstream-error.mjs';
+
+const IMAGE_TIMEOUT_MS = 180_000;
+const LABELS = Object.freeze({ openrouter: 'OpenRouter image', 'nano-gpt': 'NanoGPT image' });
+// Request field per Studio option; values come from the model's own enums.
+const PARAMS = Object.freeze({
+  aspectRatio: 'aspect_ratio',
+  resolution: 'resolution',
+  quality: 'quality',
+  background: 'background',
+});
+
+function referenceUrl(reference) {
+  const data = String(reference?.base64 || '');
+  return data.startsWith('data:') ? data : `data:${reference?.mime || 'image/png'};base64,${data}`;
+}
+
+/** The stored format comes from the bytes, not a label: only rasters the store keeps. */
+function rasterMime(bytes) {
+  if (bytes.length >= 8 && bytes.readUInt32BE(0) === 0x89504e47) return 'image/png';
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg';
+  if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP')
+    return 'image/webp';
+  return '';
+}
+
+export async function generateImage({ lane, model, prompt, options = {}, references = [], signal }) {
+  const label = LABELS[lane] || 'Image API';
+  const { baseURL, token } = resolveImageApiAuth(lane);
+  const body = { model, prompt, n: 1 };
+  for (const [option, param] of Object.entries(PARAMS)) {
+    const value = String(options?.[option] || '').trim();
+    if (value) body[param] = value;
+  }
+  if (references.length) {
+    body.input_references = references.map((reference) => ({
+      type: 'image_url',
+      image_url: { url: referenceUrl(reference) },
+    }));
+  }
+  let res;
+  try {
+    res = await fetch(`${baseURL}/images`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal: timeoutSignal(signal, IMAGE_TIMEOUT_MS),
+    });
+  } catch (error) {
+    if (error?.name === 'TimeoutError') throw mediaError(`${label} timed out`, 'MEDIA_TIMEOUT', 504);
+    throw error;
+  }
+  if (!res.ok) throw upstreamError(label, res.status, (await res.text().catch(() => '')).slice(0, 400));
+  const data = await res.json().catch(() => null);
+  const usage = imageApiUsage(data);
+  const entry = Array.isArray(data?.data) ? data.data[0] : null;
+  let bytes;
+  try {
+    if (entry?.b64_json) bytes = decodeBase64Media(entry.b64_json, label);
+    else if (entry?.url) bytes = await downloadPublicMedia(entry.url, { signal, label });
+    else throw mediaError(`${label} returned no image data`, 'MEDIA_EMPTY_RESULT', 502);
+  } catch (error) {
+    throw withReportedUsage(error, usage);
+  }
+  const mime = rasterMime(bytes);
+  if (!mime) {
+    throw withReportedUsage(
+      mediaError(`${label} returned an unsupported image format`, 'MEDIA_UPSTREAM_FAILED', 502),
+      usage
+    );
+  }
+  return { bytes, mime, revisedPrompt: entry.revised_prompt || null, usage };
+}

package/src/runtime/media/auth.mjs

@@ -5,11 +5,74 @@
  * paths) so the Studio never holds a second copy of a session. API-key lanes
  * read the same keychain-backed store the agent providers use.
  */
-import { getAgentApiKey } from '../shared/provider-api-key.mjs';
+import { readSection } from '../shared/config.mjs';
+import {
+  getAgentApiKey,
+  hasAgentApiKey,
+  hasProviderApiKey,
+  resolveProviderApiKey,
+} from '../shared/provider-api-key.mjs';
 
 export { hasGrokOAuthCredentials } from '../agent/orchestrator/providers/oauth-credential-probes.mjs';
 
 const XAI_BASE_URL = 'https://api.x.ai/v1';
+// Both gateways serve the same normalized Image API (GET /images/models,
+// POST /images) under these documented bases.
+const IMAGE_API_BASE_URL = Object.freeze({
+  openrouter: 'https://openrouter.ai/api/v1',
+  'nano-gpt': 'https://api.nano-gpt.com/api/v1',
+});
+
+/** Lanes served by the normalized Image API adapter. */
+export function imageApiLane(laneId) {
+  return Object.hasOwn(IMAGE_API_BASE_URL, laneId);
+}
+
+function nanoGptHost(baseURL) {
+  try {
+    const host = new URL(String(baseURL || '')).hostname.toLowerCase();
+    return host === 'nano-gpt.com' || host.endsWith('.nano-gpt.com');
+  } catch {
+    return false;
+  }
+}
+
+// NanoGPT is not a built-in provider: it is connected as an OpenAI-compatible
+// custom provider, whose key lives under that provider's own id (keychain or
+// its configured environment variable). The first enabled, keyed endpoint on
+// a NanoGPT host is the lane's credential.
+function nanoGptProviders() {
+  const providers = readSection('agent')?.providers || {};
+  return Object.entries(providers).filter(
+    ([id, entry]) =>
+      id.startsWith('custom-') &&
+      entry?.type === 'custom' &&
+      entry.enabled !== false &&
+      entry.auth !== 'none' &&
+      nanoGptHost(entry.baseURL)
+  );
+}
+
+/** Presence-only probe for an Image API lane's key; no secret is read. */
+export function hasImageApiCredentials(laneId) {
+  if (laneId === 'openrouter') return hasAgentApiKey('openrouter');
+  if (laneId === 'nano-gpt') return nanoGptProviders().some(([id, entry]) => hasProviderApiKey(id, entry));
+  return false;
+}
+
+/** Base URL + bearer for an Image API lane (OpenRouter key, or the connected NanoGPT custom provider's key). */
+export function resolveImageApiAuth(laneId) {
+  let token = '';
+  if (laneId === 'openrouter') token = getAgentApiKey('openrouter') || '';
+  else if (laneId === 'nano-gpt') {
+    for (const [id, entry] of nanoGptProviders()) {
+      token = resolveProviderApiKey(id, entry);
+      if (token) break;
+    }
+  }
+  if (!imageApiLane(laneId) || !token) throw unauthenticated(`${laneId} API key is not configured`);
+  return { baseURL: IMAGE_API_BASE_URL[laneId], token };
+}
 
 // Built here rather than with lanes.mjs's mediaError: importing it would close
 // an auth -> lanes -> catalog -> auth module cycle.

package/src/runtime/media/catalog.mjs

@@ -6,11 +6,26 @@
  */
 import { createHash } from 'node:crypto';
 import { makeModelCache } from '../agent/orchestrator/providers/model-cache.mjs';
-import { resolveAntigravityAuth, resolveGeminiKey, resolveXaiAuth } from './auth.mjs';
+import {
+  imageApiLane,
+  resolveAntigravityAuth,
+  resolveGeminiKey,
+  resolveImageApiAuth,
+  resolveXaiAuth,
+} from './auth.mjs';
 import { catalogHttpError, staleCatalog } from './catalog-errors.mjs';
 
 const TTL_MS = 24 * 60 * 60_000;
 const REQUEST_MS = 10_000;
+// Gateway image catalogs can sit behind a slow edge: api.nano-gpt.com's
+// /models answered only after ~44 s, so the 10 s default would read a slow
+// catalog as an outage. Same budget as custom-provider discovery.
+const GATEWAY_CATALOG_MS = 60_000;
+
+/** Per-lane timeout of one catalog request. */
+export function mediaCatalogTimeoutMs(lane) {
+  return imageApiLane(lane) ? GATEWAY_CATALOG_MS : REQUEST_MS;
+}
 const natural = new Intl.Collator('en', { numeric: true });
 
 function methodsAllow(row, method) {
@@ -39,8 +54,51 @@ function grokLane(lane) {
   return lane === 'xai' || lane === 'grok-oauth';
 }
 
+// Image API catalogs (OpenRouter, NanoGPT) describe each model with typed
+// capability descriptors; only enum values become pickable controls.
+const IMAGE_API_CONTROLS = Object.freeze({
+  aspect_ratio: 'aspectRatio',
+  resolution: 'resolution',
+  quality: 'quality',
+  background: 'background',
+});
+// The request schema's documented ceiling for `input_references`.
+const IMAGE_API_MAX_REFERENCES = 16;
+
+function imageApiOutputsImage(row) {
+  const outputs = row.architecture?.output_modalities;
+  // Image-to-image-only models (upscalers, editors) need an input image;
+  // Studio also runs prompt-only, so they stay out.
+  return Array.isArray(outputs) && outputs.includes('image') && row.capabilities?.image_generation !== false;
+}
+
+function imageApiReferenceCap(row) {
+  const descriptor = row.supported_parameters?.input_references;
+  if (descriptor?.type === 'range' && Number.isFinite(Number(descriptor.max))) {
+    return Math.max(0, Math.min(IMAGE_API_MAX_REFERENCES, Math.trunc(Number(descriptor.max))));
+  }
+  const inputs = row.architecture?.input_modalities;
+  const acceptsImages = Array.isArray(inputs) && inputs.includes('image') && row.capabilities?.image_to_image !== false;
+  return acceptsImages ? IMAGE_API_MAX_REFERENCES : 0;
+}
+
+function imageApiControls(row) {
+  const controls = {};
+  for (const [param, control] of Object.entries(IMAGE_API_CONTROLS)) {
+    const descriptor = row.supported_parameters?.[param];
+    const values =
+      descriptor?.type === 'enum' && Array.isArray(descriptor.values)
+        ? [...new Set(descriptor.values.map((value) => String(value).trim()).filter(Boolean))]
+        : [];
+    if (values.length) controls[control] = values;
+  }
+  controls.maxReferences = imageApiReferenceCap(row);
+  return controls;
+}
+
 function kindFor(lane, row, id) {
   if (row.deprecated === true || row.disabled === true) return null;
+  if (imageApiLane(lane)) return imageApiOutputsImage(row) ? 'image' : null;
   if (lane === 'openai-oauth') return imageToolSupported(row, id) ? 'image' : null;
   if (grokLane(lane)) {
     if (/^grok-imagine-image(?:-|$)/.test(id)) return 'image';
@@ -118,7 +176,9 @@ export function projectMediaModels(lane, rows) {
     const kind = kindFor(lane, row, id);
     if (!kind) continue;
     let controls = {};
-    if (grokLane(lane) && kind === 'video') {
+    if (imageApiLane(lane)) {
+      controls = imageApiControls(row);
+    } else if (grokLane(lane) && kind === 'video') {
       controls = { resolution: ['480p', '720p'] };
     } else if (lane === 'gemini' && /^gemini-omni-/.test(id)) {
       controls = { resolution: [], durations: [], maxReferences: 3 };
@@ -181,6 +241,7 @@ async function providerSource(lane) {
   let auth;
   if (lane === 'gemini') auth = { token: resolveGeminiKey() };
   else if (lane === 'antigravity-oauth') auth = await resolveAntigravityAuth();
+  else if (imageApiLane(lane)) auth = resolveImageApiAuth(lane);
   else auth = await resolveXaiAuth(lane);
   // API-key and OAuth catalogs must not leak availability across credentials.
   // Persist only a one-way scope hash, never a key or a bearer. OAuth bearers
@@ -200,7 +261,7 @@ async function providerSource(lane) {
 }
 
 export async function fetchMediaModelRows({ lane, auth, fetchFn = fetch }) {
-  const signal = AbortSignal.timeout(REQUEST_MS);
+  const signal = AbortSignal.timeout(mediaCatalogTimeoutMs(lane));
   if (lane === 'gemini') {
     const { fetchGeminiModelPages } = await import('../agent/orchestrator/providers/lib/gemini-model-catalog.mjs');
     return fetchGeminiModelPages(auth.token, async (url, init) => {
@@ -217,7 +278,8 @@ export async function fetchMediaModelRows({ lane, auth, fetchFn = fetch }) {
     return Object.entries(models).map(([id, row]) => ({ ...(row && typeof row === 'object' ? row : {}), id }));
   }
   const { getLlmDispatcher } = await import('../shared/llm/http-agent.mjs');
-  const response = await fetchFn(`${auth.baseURL}/models`, {
+  // The Image API lists its generation models apart from the chat catalog.
+  const response = await fetchFn(`${auth.baseURL}/${imageApiLane(lane) ? 'images/models' : 'models'}`, {
     headers: { Authorization: `Bearer ${auth.token}` },
     redirect: 'error',
     signal,

package/src/runtime/media/jobs.mjs

@@ -60,6 +60,10 @@ async function runAdapter({ lane, kind, model, requestModel, prompt, options, re
     const adapter = await import('./adapters/codex-image.mjs');
     return await adapter.generateImage({ model: requestModel || model, prompt, options, references, signal });
   }
+  if (lane.id === 'openrouter' || lane.id === 'nano-gpt') {
+    const adapter = await import('./adapters/image-api.mjs');
+    return await adapter.generateImage({ lane: lane.id, model, prompt, options, references, signal });
+  }
   if (lane.id === 'antigravity-oauth') {
     const adapter = await import('./adapters/antigravity-image.mjs');
     return await adapter.generateImage({ model, prompt, options, references, signal });

package/src/runtime/media/lanes.mjs

@@ -16,6 +16,7 @@ import {
   hasGrokOAuthCredentials,
   hasOpenAIOAuthCredentials,
 } from '../agent/orchestrator/providers/oauth-credential-probes.mjs';
+import { hasImageApiCredentials, imageApiLane } from './auth.mjs';
 import { loadMediaModels, projectMediaModels } from './catalog.mjs';
 import { catalogDiagnostic } from './catalog-errors.mjs';
 import { MEDIA_KINDS } from './tool-defs.mjs';
@@ -98,6 +99,20 @@ const LANES = Object.freeze([
       controls: GEMINI_IMAGE_CONTROLS,
     }),
   }),
+  // Gateway lanes on the normalized Image API: every model advertises its own
+  // parameters in the catalog, so the lane declares no controls of its own.
+  Object.freeze({
+    id: 'openrouter',
+    label: 'OpenRouter',
+    auth: Object.freeze({ type: 'api-key', provider: 'openrouter' }),
+    image: Object.freeze({ controls: Object.freeze({}) }),
+  }),
+  Object.freeze({
+    id: 'nano-gpt',
+    label: 'NanoGPT',
+    auth: Object.freeze({ type: 'api-key', provider: 'nano-gpt' }),
+    image: Object.freeze({ controls: Object.freeze({}) }),
+  }),
 ]);
 
 const LANE_BY_ID = new Map(LANES.map((lane) => [lane.id, lane]));
@@ -117,6 +132,7 @@ const OAUTH_PROBES = Object.freeze({
 
 function laneAuthenticated(lane) {
   try {
+    if (imageApiLane(lane.id)) return hasImageApiCredentials(lane.id);
     if (lane.auth.type === 'api-key') return hasAgentApiKey(lane.auth.provider);
     return OAUTH_PROBES[lane.auth.provider]?.() === true;
   } catch {
@@ -143,8 +159,23 @@ function laneKindView(lane, kind, models) {
   };
 }
 
+const PENDING = Symbol('catalog-pending');
+
+/** The catalog rows, or PENDING when they did not arrive within `budgetMs`
+ *  (0 = wait). The request keeps running; the loader's singleflight lets the
+ *  next listing join it instead of starting over. */
+async function withinBudget(loading, budgetMs) {
+  if (!(budgetMs > 0)) return loading;
+  loading.catch(() => {});
+  let timer;
+  const expired = new Promise((resolve) => {
+    timer = setTimeout(resolve, budgetMs, PENDING);
+  });
+  return Promise.race([loading, expired]).finally(() => clearTimeout(timer));
+}
+
 export function createMediaLaneCatalog({ loadModels = loadMediaModels, authenticated = laneAuthenticated } = {}) {
-  async function laneView(lane) {
+  async function laneView(lane, budgetMs = 0) {
     const signedIn = authenticated(lane);
     const view = {
       id: lane.id,
@@ -161,7 +192,15 @@ export function createMediaLaneCatalog({ loadModels = loadMediaModels, authentic
     };
     if (!signedIn) return view;
     try {
-      const rows = await loadModels(lane.id);
+      const rows = await withinBudget(
+        Promise.resolve().then(() => loadModels(lane.id)),
+        budgetMs
+      );
+      if (rows === PENDING) {
+        // Still loading, not empty: the caller shows that and asks again.
+        view.catalogPending = true;
+        return view;
+      }
       const models = projectMediaModels(lane.id, rows);
       if (rows.catalogWarning) view.catalogWarning = rows.catalogWarning;
       for (const kind of MEDIA_KINDS) {
@@ -187,9 +226,11 @@ export function createMediaLaneCatalog({ loadModels = loadMediaModels, authentic
   }
 
   return {
-    /** Live catalog shared by Studio and the model-facing media tool. */
-    async listMediaLanes() {
-      return (await Promise.all(LANES.map(laneView))).filter(Boolean);
+    /** Live catalog shared by Studio and the model-facing media tool.
+     *  `budgetMs` bounds the wait per lane: a lane whose catalog is slower
+     *  answers `catalogPending` instead of holding every other lane. */
+    async listMediaLanes({ budgetMs = 0 } = {}) {
+      return (await Promise.all(LANES.map((lane) => laneView(lane, budgetMs)))).filter(Boolean);
     },
     async resolveMediaRequest({ lane: laneId, kind, model } = {}) {
       const kindName = String(kind || '').trim();

package/src/runtime/media/media-usage.mjs

@@ -73,6 +73,23 @@ export function xaiUsage(usage) {
   return typeof ticks === 'number' && Number.isFinite(ticks) && ticks >= 0 ? { costUsd: ticks / TICKS_PER_USD } : null;
 }
 
+/**
+ * Image API response usage (OpenRouter / NanoGPT `POST /images`). `usage.cost`
+ * is USD; NanoGPT's top-level `cost` counts only when `paymentSource` says USD
+ * (it may be billed in XNO).
+ */
+export function imageApiUsage(body) {
+  const usage = body?.usage && typeof body.usage === 'object' ? body.usage : {};
+  const tokens = tokenUsage({
+    inputTokens: count(usage.prompt_tokens),
+    outputTokens: count(usage.completion_tokens),
+    outputImageTokens: count(usage.completion_tokens_details?.image_tokens),
+  });
+  const usd = String(body?.paymentSource || '').toUpperCase() === 'USD' ? body?.cost : undefined;
+  const cost = [usage.cost, usd].find((value) => typeof value === 'number' && Number.isFinite(value) && value >= 0);
+  return cost === undefined ? tokens : { ...tokens, costUsd: cost };
+}
+
 /** True when the provider reported something billable for the request. */
 export function hasReportedUsage(usage) {
   if (!usage) return false;

package/src/runtime/media/renditions.mjs

@@ -14,10 +14,11 @@
  * what made the remote gallery slow.
  */
 import { spawn } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
 
+import { writeFileAtomicSync } from '../shared/atomic-file.mjs';
+import { fileHasData } from '../shared/file-has-data.mjs';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 
 // maxEdge is the long edge in pixels; quality is the webp setting.
@@ -100,7 +101,14 @@ function cachedRendition(cacheDir, variant, id) {
     // a plain cache miss into a thrown media request.
     try {
       const info = statSync(path);
-      if (info.isFile()) return { path, mime, bytes: info.size };
+      if (!info.isFile()) continue;
+      // A rendition a crash left empty or NUL-filled would be served forever;
+      // drop it so the miss below rebuilds it.
+      if (!fileHasData(path)) {
+        unlinkSync(path);
+        continue;
+      }
+      return { path, mime, bytes: info.size };
     } catch {
       /* absent or evicted mid-lookup */
     }
@@ -166,21 +174,13 @@ function writeRendition(cacheDir, variant, id, extension, buffer) {
     return null;
   }
   const path = renditionPath(cacheDir, variant, id, extension);
-  mkdirSync(dirname(path), { recursive: true });
-  // Stage-then-rename: a reader must never observe a half-written cache file.
-  const staging = `${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
-  writeFileSync(staging, buffer);
+  // Durable stage-then-rename: a reader never observes a half-written cache
+  // file, and a crash cannot publish one whose bytes are all NUL.
   try {
-    renameSync(staging, path);
+    writeFileAtomicSync(path, buffer);
   } catch (error) {
     // Another process may have won the same cache publication race.
     if (!existsSync(path)) throw error;
-  } finally {
-    try {
-      unlinkSync(staging);
-    } catch {
-      /* renamed or already removed */
-    }
   }
   let bytes = buffer.length;
   try {

package/src/runtime/media/store.mjs

@@ -6,12 +6,12 @@
  * (newest first) and is written atomically under a file lock because the
  * desktop and CLI can generate concurrently.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, statSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
-import { writeJsonAtomicSync, withFileLockSync } from '../shared/atomic-file.mjs';
+import { readJsonStateSync, updateJsonAtomicSync, writeFileAtomicSync } from '../shared/atomic-file.mjs';
 import { cacheRendition, ensureRendition, removeRenditions, renditionSpec } from './renditions.mjs';
 
 // Renderer transport is base64 over IPC: refuse to inline anything larger.
@@ -50,10 +50,6 @@ function indexPath() {
   return join(mediaDir(), 'index.json');
 }
 
-function indexLockPath() {
-  return `${indexPath()}.lock`;
-}
-
 function ensureDirs({ migrate = false } = {}) {
   mkdirSync(assetsDir(), { recursive: true });
   if (migrate && !layoutMigrationChecked) {
@@ -89,42 +85,45 @@ function readIndex() {
     indexCacheHits += 1;
     return indexCacheAssets;
   }
-  let raw;
-  try {
-    raw = readFileSync(path, 'utf8');
-  } catch (error) {
-    // A missing index file is a genuinely empty catalog (first run). Every
-    // OTHER read failure is not: answering with an empty list made the next
-    // save/delete write that emptiness back over every existing asset entry.
-    if (error?.code === 'ENOENT') return rememberIndex(path, signature, []);
-    throw error;
-  }
-  const parsed = JSON.parse(raw);
-  if (!parsed || !Array.isArray(parsed.assets)) {
-    throw new Error(`media index is malformed: ${path}`);
-  }
-  indexDiskReads += 1;
-  return rememberIndex(path, signature, parsed.assets);
+  // A missing index is a genuinely empty catalog (first run). A DAMAGED one
+  // (empty, NUL-filled, truncated, wrong shape) is kept as index.json.corrupt-<ts>
+  // and the last good copy restored, so the gallery lists and saves keep
+  // working. Every other read failure (EACCES, EIO) still throws: answering
+  // with an empty list made the next save/delete write that emptiness back
+  // over every existing asset entry.
+  const assets = readJsonStateSync(path, { validate: catalogAssets, fallback: [] });
+  if (signature !== 'missing') indexDiskReads += 1;
+  return rememberIndex(path, signature, assets);
 }
 
-function writeIndex(assets) {
-  const path = indexPath();
-  writeJsonAtomicSync(path, { version: 2, assets });
-  rememberIndex(path, indexSignature(path), assets);
+function catalogAssets(parsed) {
+  if (!parsed || !Array.isArray(parsed.assets)) throw new Error(`media index is malformed: ${indexPath()}`);
+  return parsed.assets;
 }
 
 /**
  * The one catalog read-modify-write. Every mutation (migrate, save, duration
- * backfill, delete) holds index.lock across a fresh readIndex() and writes back
- * only what the callback returns, so a concurrent CLI/desktop generation can
- * never lose an entry — and a read that FAILS (rather than being absent)
- * propagates out of the lock instead of writing an empty catalog over it.
+ * backfill, delete) holds index.lock across a fresh read and writes back only
+ * what the callback returns, so a concurrent CLI/desktop generation can never
+ * lose an entry — and a read that FAILS (rather than being absent) propagates
+ * out of the lock instead of writing an empty catalog over it. The previous
+ * catalog is kept as index.json.bak.
  */
 function mutateIndex(mutate) {
-  withFileLockSync(indexLockPath(), () => {
-    const next = mutate(readIndex());
-    if (next) writeIndex(next);
-  });
+  // Sets a wrong-shaped catalog aside before the lock below takes the file.
+  readIndex();
+  let written = null;
+  updateJsonAtomicSync(
+    indexPath(),
+    (current) => {
+      const next = mutate(Array.isArray(current?.assets) ? current.assets : []);
+      if (!next) return undefined;
+      written = next;
+      return { version: 2, assets: next };
+    },
+    { backup: true }
+  );
+  if (written) rememberIndex(indexPath(), indexSignature(indexPath()), written);
 }
 
 export function mediaStoreCacheStats() {
@@ -228,7 +227,9 @@ export function saveMediaAsset({ kind, lane, model, prompt, options = {}, mime,
   const path = storedAssetPath(file);
   if (!path) throw new Error('invalid media asset path');
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, bytes);
+  // Durable before the index names it: a crash must not leave a listed asset
+  // whose bytes are all NUL.
+  writeFileAtomicSync(path, bytes);
   entry.file = file;
   // The gallery is NOT capped (user). An entry-count trim used to unlink the
   // oldest files here, which is data loss nobody asked for: a generated asset

package/src/runtime/media/tool.mjs

@@ -28,6 +28,7 @@ const IMAGE_MIME = Object.freeze({
   '.gif': 'image/gif',
 });
 const MAX_REFERENCE_BYTES = 12 * 1024 * 1024;
+const GATEWAY_IMAGE_LANES = new Set(['openrouter', 'nano-gpt']);
 
 let graph = null;
 async function mediaGraph(deps) {
@@ -228,7 +229,13 @@ export function buildOptions(
     if (resolution) {
       validateChoice(controls, 'resolution', resolution, 'resolution');
       options.resolution = resolution;
-    } else if (kind === 'image' && allowed(controls, 'resolution')?.includes('2k')) {
+    } else if (
+      kind === 'image' &&
+      !GATEWAY_IMAGE_LANES.has(lane.id) &&
+      allowed(controls, 'resolution')?.includes('2k')
+    ) {
+      // Gateway models bill per resolution tier: an omitted resolution keeps
+      // the provider's default there instead of silently upscaling.
       options.resolution = '2k';
     }
     if (quality) {

package/src/runtime/memory/lib/cycle-scheduler/health-ledger.mjs

@@ -1,4 +1,4 @@
-import fs from 'node:fs';
+import { writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
 
 const BACKLOG_WARN_COOLDOWN_MS = 10 * 60_000;
 const BACKLOG_WARN_FAILURES = 5;
@@ -16,7 +16,13 @@ export function createCycleHealthLedger({ cycleStateFile, log }) {
 
   function write() {
     try {
-      fs.writeFileSync(cycleStateFile, JSON.stringify({ running, backlog, cycles: health, updatedAt: Date.now() }));
+      // Rewritten on every cycle event and read by a statusline that treats an
+      // unparsable file as "nothing to show", so no fsync; rename keeps it untorn.
+      writeJsonAtomicSync(
+        cycleStateFile,
+        { running, backlog, cycles: health, updatedAt: Date.now() },
+        { compact: true, fsync: false }
+      );
     } catch {
       /* best-effort; statusline just shows nothing */
     }