mixdog 0.9.87 → 0.9.88

package/src/runtime/agent/orchestrator/tools/shell-command.mjs

@@ -214,6 +214,7 @@ export function execShellCommand({
     let failureReason = null;
     let spawnError = null;
     let pendingChildError = null;
+    let childGuardian = null;
     let settle = null;
     let settled = false;
     let timer = null;
@@ -398,10 +399,11 @@ export function execShellCommand({
       child = spawned.child;
       spawned.adoptErrorHandler(_onChildError);
       }
-      startChildGuardian({
+      childGuardian = startChildGuardian({
         childPid: child.pid,
         childGroupPid: child.pid,
         label: 'shell-command',
+        protectHostMemory: true,
       });
       // Windows has no process-group handle. Begin observing while the owned
       // root still exists so descendants can be proven before root exit.
@@ -579,10 +581,18 @@ export function execShellCommand({
         // pool when clean, tree-kills it otherwise) and the lease frees after.
         const lease = resourceLease;
         resourceLease = null;
+        // The standby root survives this command and may return to the pool.
+        // Stop this command-scoped guardian so every reuse does not leave
+        // another detached Node process watching the same pwsh forever.
+        const standbyGuardian = childGuardian;
+        childGuardian = null;
         void _standby.recycle()
           .catch(() => false)
-          .then(() => { try { return Promise.resolve(lease?.release()).catch(() => {}); } catch { return null; } });
+          .then(() => { try { return Promise.resolve(lease?.release()).catch(() => {}); } catch { return null; } })
+          .finally(() => standbyGuardian?.stop?.());
       } else {
+      childGuardian?.stop?.();
+      childGuardian = null;
       const leaseSettlement = resourceLeaseSettlement
         || releaseResourceLeaseWhenTreeQuiescent(child.pid);
       leaseSettlement.tracker?.rootExited?.();

package/src/runtime/media/lanes.mjs

@@ -7,7 +7,7 @@
  * already signed in to. No lane owns a fallback to another lane's credential —
  * an unauthenticated lane fails closed.
  */
-import { getAgentApiKey } from '../shared/provider-api-key.mjs';
+import { hasAgentApiKey } from '../shared/provider-api-key.mjs';
 // Credential probes are file-level checks: the catalog must not drag the whole
 // provider graph in just to render lane availability.
 import {
@@ -155,7 +155,7 @@ const LANE_BY_ID = new Map(LANES.map((lane) => [lane.id, lane]));
 
 function laneAuthenticated(lane) {
   try {
-    if (lane.auth.type === 'api-key') return Boolean(getAgentApiKey(lane.auth.provider));
+    if (lane.auth.type === 'api-key') return hasAgentApiKey(lane.auth.provider);
     if (lane.auth.provider === 'grok-oauth') return hasGrokOAuthCredentials();
     if (lane.auth.provider === 'openai-oauth') return hasOpenAIOAuthCredentials();
   } catch {

package/src/runtime/media/renditions.mjs

@@ -26,9 +26,15 @@ const SPECS = {
 };
 // Probe order when reading a cached rendition: sharp writes webp, the
 // ffmpeg-only poster path writes png.
-const EXTENSION_MIME = { '.webp': 'image/webp', '.png': 'image/png' };
+const EXTENSION_MIME = {
+  '.webp': 'image/webp',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+};
 const POSTER_TIMEOUT_MS = 20_000;
 const MAX_POSTER_BYTES = 32 * 1024 * 1024;
+const FAILED_RENDITION_COOLDOWN_MS = 30_000;
+const MAX_CACHED_RENDITION_BYTES = 4 * 1024 * 1024;
 
 const MEDIA_VARIANTS = Object.keys(SPECS);
 
@@ -93,6 +99,40 @@ function writeRendition(cacheDir, variant, id, extension, buffer) {
   return { path, mime: EXTENSION_MIME[extension], bytes: buffer.length };
 }
 
+export function createPriorityScheduler(limit = 2) {
+  const foreground = [];
+  const background = [];
+  let active = 0;
+  let backgroundActive = 0;
+  const concurrency = Math.max(1, limit);
+  const backgroundConcurrency = Math.max(1, concurrency - 1);
+  const pump = () => {
+    while (active < concurrency) {
+      const foregroundEntry = foreground.shift();
+      const entry = foregroundEntry
+        ?? (backgroundActive < backgroundConcurrency ? background.shift() : null);
+      if (!entry) return;
+      active += 1;
+      if (!foregroundEntry) backgroundActive += 1;
+      void Promise.resolve()
+        .then(entry.task)
+        .then(entry.resolve, entry.reject)
+        .finally(() => {
+          active -= 1;
+          if (!foregroundEntry) backgroundActive -= 1;
+          pump();
+        });
+    }
+  };
+  return (task, priority = 'foreground') => new Promise((resolve, reject) => {
+    const queue = priority === 'background' ? background : foreground;
+    queue.push({ task, resolve, reject });
+    pump();
+  });
+}
+
+const scheduleRendition = createPriorityScheduler(2);
+
 /** Downscale a still (path or buffer) into a webp; null without sharp. */
 async function encodeStill(input, spec) {
   const sharp = await loadSharp();
@@ -118,20 +158,33 @@ function parseDurationSeconds(text) {
   return Number.isFinite(seconds) ? Math.round(seconds) : 0;
 }
 
-/** First frame + duration of a clip, straight from ffmpeg; null when the
+export function videoPosterArguments(sourcePath, spec) {
+  return [
+    '-hide_banner', '-nostdin',
+    '-i', sourcePath,
+    // The encoded first frame is frequently a black transition. An accurate
+    // post-input seek gives generated clips a representative early poster.
+    '-ss', '0.12',
+    '-frames:v', '1',
+    '-vf', `scale='min(${spec.maxEdge},iw)':-2`,
+    // Emit the tile JPEG directly. The old PNG -> sharp -> webp second encode
+    // doubled cold-video latency and failed when sharp was unavailable.
+    '-q:v', '4',
+    '-f', 'image2', '-vcodec', 'mjpeg', 'pipe:1',
+  ];
+}
+
+/** Representative frame + duration of a clip, straight from ffmpeg; null when the
  *  managed runtime is not installed. */
 async function grabVideoFrame(sourcePath, spec) {
   const ffmpeg = await resolveFfmpeg();
   if (!ffmpeg) return null;
   return new Promise((resolve) => {
-    const child = spawn(ffmpeg, [
-      '-hide_banner', '-nostdin',
-      '-i', sourcePath,
-      '-frames:v', '1',
-      // Never upscale a small clip: -2 keeps the height even for the encoder.
-      '-vf', `scale='min(${spec.maxEdge},iw)':-2`,
-      '-f', 'image2', '-vcodec', 'png', 'pipe:1',
-    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawn(
+      ffmpeg,
+      videoPosterArguments(sourcePath, spec),
+      { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true },
+    );
     const chunks = [];
     let total = 0;
     let stderr = '';
@@ -165,6 +218,7 @@ async function grabVideoFrame(sourcePath, spec) {
 
 // Two tiles asking for the same missing rendition must not both encode it.
 const inflight = new Map();
+const failedUntil = new Map();
 
 async function generate({ id, kind, sourcePath, variant, spec, cacheDir }) {
   if (kind === 'video') {
@@ -173,10 +227,7 @@ async function generate({ id, kind, sourcePath, variant, spec, cacheDir }) {
     if (variant !== 'thumb') return null;
     const frame = await grabVideoFrame(sourcePath, spec);
     if (!frame) return null;
-    const encoded = await encodeStill(frame.buffer, spec);
-    const written = encoded
-      ? writeRendition(cacheDir, variant, id, encoded.extension, encoded.buffer)
-      : writeRendition(cacheDir, variant, id, '.png', frame.buffer);
+    const written = writeRendition(cacheDir, variant, id, '.jpg', frame.buffer);
     return { ...written, durationSeconds: frame.durationSeconds };
   }
   const encoded = await encodeStill(sourcePath, spec);
@@ -188,16 +239,49 @@ async function generate({ id, kind, sourcePath, variant, spec, cacheDir }) {
  * Returns `{ path, mime, bytes, durationSeconds? }`, or null when this host
  * cannot produce it (no sharp / no ffmpeg / undecodable source).
  */
-export async function ensureRendition({ id, kind, sourcePath, variant, cacheDir }) {
+export async function ensureRendition({
+  id,
+  kind,
+  sourcePath,
+  variant,
+  cacheDir,
+  priority = 'foreground',
+  generate = true,
+}) {
   const spec = renditionSpec(variant);
   if (!spec) return null;
   const cached = cachedRendition(cacheDir, variant, id);
   if (cached) return cached;
+  if (!generate) return null;
   const key = `${variant}:${id}`;
+  if ((failedUntil.get(key) || 0) > Date.now()) return null;
   const pending = inflight.get(key)
-    ?? generate({ id, kind, sourcePath, variant, spec, cacheDir })
-      .catch(() => null)
+    ?? scheduleRendition(
+      () => generate({ id, kind, sourcePath, variant, spec, cacheDir }),
+      priority,
+    )
+      .then((result) => {
+        if (result) failedUntil.delete(key);
+        else failedUntil.set(key, Date.now() + FAILED_RENDITION_COOLDOWN_MS);
+        return result;
+      })
+      .catch(() => {
+        failedUntil.set(key, Date.now() + FAILED_RENDITION_COOLDOWN_MS);
+        return null;
+      })
       .finally(() => { inflight.delete(key); });
   inflight.set(key, pending);
   return pending;
 }
+
+/** Persist a small browser-generated fallback so a codec miss is paid once. */
+export function cacheRendition({ id, variant = 'thumb', mime, buffer, cacheDir }) {
+  if (!renditionSpec(variant)) return null;
+  const extension = mime === 'image/webp'
+    ? '.webp'
+    : mime === 'image/png' ? '.png'
+      : mime === 'image/jpeg' ? '.jpg' : '';
+  if (!extension || !buffer?.length || buffer.length > MAX_CACHED_RENDITION_BYTES) return null;
+  failedUntil.delete(`${variant}:${id}`);
+  return writeRendition(cacheDir, variant, id, extension, buffer);
+}

package/src/runtime/media/renditions.test.mjs

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+  createPriorityScheduler,
+  videoPosterArguments,
+} from './renditions.mjs';
+
+test('video posters seek off frame zero and encode one JPEG without a second still pass', () => {
+  const args = videoPosterArguments('clip.mp4', { maxEdge: 512 });
+  assert.deepEqual(args.slice(args.indexOf('-ss'), args.indexOf('-ss') + 2), ['-ss', '0.12']);
+  assert.equal(args[args.indexOf('-vcodec') + 1], 'mjpeg');
+  assert.equal(args.includes('png'), false);
+});
+
+test('rendition scheduler bounds work and prioritizes visible requests over queued warmups', async () => {
+  const schedule = createPriorityScheduler(2);
+  const releases = [];
+  const started = [];
+  let active = 0;
+  let peak = 0;
+  const blocked = (name) => schedule(() => new Promise((resolve) => {
+    started.push(name);
+    active += 1;
+    peak = Math.max(peak, active);
+    releases.push(() => {
+      active -= 1;
+      resolve(name);
+    });
+  }), 'background');
+  const first = blocked('background-a');
+  const second = blocked('background-b');
+  const third = blocked('background-c');
+  const foreground = schedule(async () => {
+    started.push('foreground');
+    active += 1;
+    peak = Math.max(peak, active);
+    active -= 1;
+    return 'foreground';
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(started, ['background-a', 'foreground'],
+    'one slot must stay available for a visible request');
+  assert.equal(await foreground, 'foreground');
+  releases.shift()();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(started, ['background-a', 'foreground', 'background-b']);
+  releases.shift()();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(started, ['background-a', 'foreground', 'background-b', 'background-c']);
+  releases.shift()();
+  await Promise.all([first, second, third]);
+  assert.equal(peak, 2);
+});

package/src/runtime/media/store.mjs

@@ -12,11 +12,17 @@ import { randomUUID } from 'crypto';
 import { spawn } from 'child_process';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 import { writeJsonAtomicSync, withFileLockSync } from '../shared/atomic-file.mjs';
-import { ensureRendition, removeRenditions, renditionSpec } from './renditions.mjs';
+import {
+  cacheRendition,
+  ensureRendition,
+  removeRenditions,
+  renditionSpec,
+} from './renditions.mjs';
 
 const MAX_INDEX_ENTRIES = 2_000;
 // Renderer transport is base64 over IPC: refuse to inline anything larger.
 const MAX_INLINE_BYTES = 48 * 1024 * 1024;
+const MAX_CACHED_THUMBNAIL_BYTES = 4 * 1024 * 1024;
 
 const EXTENSIONS = {
   'image/png': 'png',
@@ -25,6 +31,12 @@ const EXTENSIONS = {
   'video/mp4': 'mp4',
 };
 let layoutMigrationChecked = false;
+let indexCachePath = '';
+let indexCacheSignature = '';
+let indexCacheAssets = [];
+let indexCacheById = new Map();
+let indexDiskReads = 0;
+let indexCacheHits = 0;
 
 function mediaDir() {
   return join(resolvePluginData(), 'media');
@@ -48,26 +60,60 @@ function indexLockPath() {
   return `${indexPath()}.lock`;
 }
 
-function ensureDirs() {
+function ensureDirs({ migrate = false } = {}) {
   mkdirSync(assetsDir(), { recursive: true });
-  if (!layoutMigrationChecked) {
+  if (migrate && !layoutMigrationChecked) {
     migrateAssetLayout();
     layoutMigrationChecked = true;
   }
 }
 
+function indexSignature(path) {
+  try {
+    const info = statSync(path);
+    return `${info.mtimeMs}:${info.ctimeMs}:${info.size}`;
+  } catch {
+    return 'missing';
+  }
+}
+
+function rememberIndex(path, signature, assets) {
+  indexCachePath = path;
+  indexCacheSignature = signature;
+  indexCacheAssets = assets;
+  indexCacheById = new Map(assets.map((entry) => [entry.id, entry]));
+  return assets;
+}
+
 function readIndex() {
+  const path = indexPath();
+  const signature = indexSignature(path);
+  if (path === indexCachePath && signature === indexCacheSignature) {
+    indexCacheHits += 1;
+    return indexCacheAssets;
+  }
   try {
-    const raw = readFileSync(indexPath(), 'utf8');
+    const raw = readFileSync(path, 'utf8');
     const parsed = JSON.parse(raw);
-    return Array.isArray(parsed?.assets) ? parsed.assets : [];
+    indexDiskReads += 1;
+    return rememberIndex(path, signature, Array.isArray(parsed?.assets) ? parsed.assets : []);
   } catch {
-    return [];
+    return rememberIndex(path, signature, []);
   }
 }
 
 function writeIndex(assets) {
-  writeJsonAtomicSync(indexPath(), { version: 2, assets });
+  const path = indexPath();
+  writeJsonAtomicSync(path, { version: 2, assets });
+  rememberIndex(path, indexSignature(path), assets);
+}
+
+export function mediaStoreCacheStats() {
+  return {
+    indexDiskReads,
+    indexCacheHits,
+    indexEntries: indexCacheAssets.length,
+  };
 }
 
 function extensionFor(mime) {
@@ -142,7 +188,9 @@ function migrateAssetLayout() {
 
 /** Persist one generated artifact and return its index entry. */
 export function saveMediaAsset({ kind, lane, model, prompt, options = {}, mime, bytes, meta = {} }) {
-  ensureDirs();
+  // Moving legacy files is a write-side maintenance task. Running it from
+  // list/resolve made the first Studio read synchronously wait on index.lock.
+  ensureDirs({ migrate: true });
   const id = randomUUID();
   const createdAt = Date.now();
   const entry = {
@@ -180,6 +228,7 @@ export function saveMediaAsset({ kind, lane, model, prompt, options = {}, mime,
     sourcePath: path,
     variant: 'thumb',
     cacheDir: renditionsDir(),
+    priority: 'background',
   });
   return entry;
 }
@@ -190,41 +239,13 @@ export function listMediaAssets({ limit = 60, offset = 0, kind = null } = {}) {
   const start = Math.max(0, Math.trunc(Number(offset) || 0));
   const count = Math.min(200, Math.max(1, Math.trunc(Number(limit) || 60)));
   const assets = all.slice(start, start + count);
-  // Assets generated before this cache existed have no tile rendition, so the
-  // first gallery paint used to wait on an encode per visible tile. Listing is
-  // the earliest moment the host knows WHICH tiles are coming: warm them here,
-  // off the caller's path (ensureRendition dedupes the concurrent request).
-  void prewarmThumbs(assets);
   return { total: all.length, assets };
 }
 
-// Bounded: the encoder is shared with generation, and a large page must not
-// turn one listing into dozens of parallel sharp/ffmpeg jobs.
-const PREWARM_LIMIT = 24;
-const PREWARM_CONCURRENCY = 2;
-
-async function prewarmThumbs(assets) {
-  const queue = assets.slice(0, PREWARM_LIMIT);
-  const workers = Array.from({ length: PREWARM_CONCURRENCY }, async () => {
-    for (let entry = queue.shift(); entry; entry = queue.shift()) {
-      const path = storedAssetPath(entry.file);
-      if (!path || !existsSync(path)) continue;
-      const rendition = await ensureRendition({
-        id: entry.id,
-        kind: entry.kind,
-        sourcePath: path,
-        variant: 'thumb',
-        cacheDir: renditionsDir(),
-      }).catch(() => null);
-      if (rendition?.durationSeconds) rememberDuration(entry, rendition.durationSeconds);
-    }
-  });
-  await Promise.all(workers).catch(() => {});
-}
-
 function getMediaAsset(id) {
   ensureDirs();
-  return readIndex().find((entry) => entry.id === id) || null;
+  readIndex();
+  return indexCacheById.get(id) || null;
 }
 
 /** Persist a duration probed while building a poster, so the gallery badge
@@ -262,7 +283,10 @@ function inlineBase64(path) {
  * no ffmpeg); the caller reduces the feature instead of substituting the
  * original behind the client's back.
  */
-export async function resolveMediaFile(id, { variant = 'original' } = {}) {
+export async function resolveMediaFile(id, {
+  variant = 'original',
+  generate = true,
+} = {}) {
   const entry = getMediaAsset(id);
   if (!entry) return null;
   const path = storedAssetPath(entry.file);
@@ -275,6 +299,7 @@ export async function resolveMediaFile(id, { variant = 'original' } = {}) {
     sourcePath: path,
     variant,
     cacheDir: renditionsDir(),
+    generate,
   });
   if (!rendition) return { ...entry, variant, path: '', available: false };
   rememberDuration(entry, rendition.durationSeconds);
@@ -297,8 +322,12 @@ export async function resolveMediaFile(id, { variant = 'original' } = {}) {
  * so (`available: false`) instead of quietly shipping full-size bytes — the
  * caller that can afford them (local IPC) opts in with `allowOriginal`.
  */
-export async function readMediaAsset(id, { variant = 'original', allowOriginal = false } = {}) {
-  const file = await resolveMediaFile(id, { variant });
+export async function readMediaAsset(id, {
+  variant = 'original',
+  allowOriginal = false,
+  generate = true,
+} = {}) {
+  const file = await resolveMediaFile(id, { variant, generate });
   if (!file) return null;
   if (file.available) return { ...file, base64: inlineBase64(file.path) };
   if (!allowOriginal) return { ...file, base64: '' };
@@ -307,6 +336,39 @@ export async function readMediaAsset(id, { variant = 'original', allowOriginal =
   return { ...original, downgraded: true, base64: inlineBase64(original.path) };
 }
 
+/** Cache a bounded thumbnail produced by Chromium when native codecs miss. */
+export function cacheMediaThumbnail(id, input = {}) {
+  const entry = getMediaAsset(id);
+  if (!entry) return null;
+  const base64 = typeof input.base64 === 'string' ? input.base64 : '';
+  if (!base64 || base64.length > Math.ceil(MAX_CACHED_THUMBNAIL_BYTES * 4 / 3) + 8) {
+    return { id, available: false };
+  }
+  const buffer = Buffer.from(base64, 'base64');
+  if (!buffer.length || buffer.length > MAX_CACHED_THUMBNAIL_BYTES) {
+    return { id, available: false };
+  }
+  const mime = String(input.mime || 'image/jpeg').toLowerCase();
+  const rendition = cacheRendition({
+    id: entry.id,
+    variant: 'thumb',
+    mime,
+    buffer,
+    cacheDir: renditionsDir(),
+  });
+  if (!rendition) return { id, available: false };
+  const durationSeconds = Math.max(0, Math.round(Number(input.durationSeconds) || 0));
+  if (durationSeconds) rememberDuration(entry, durationSeconds);
+  return {
+    id,
+    available: true,
+    variant: 'thumb',
+    mime: rendition.mime,
+    bytes: rendition.bytes,
+    ...(durationSeconds ? { durationSeconds } : {}),
+  };
+}
+
 export function mediaAssetPath(id) {
   const entry = getMediaAsset(id);
   return entry ? storedAssetPath(entry.file) : null;
@@ -322,8 +384,14 @@ export function openMediaAsset(id) {
   return { id, opened: openWithOs(path) };
 }
 
-/** Open the assets directory itself (Studio → folder button). */
-export function openMediaFolder() {
+/** Open one asset's containing directory, or the Studio assets root. */
+export function openMediaFolder(id = '') {
+  if (id) {
+    const path = mediaAssetPath(id);
+    if (!path || !existsSync(path)) return { id, path: '', opened: false };
+    const folder = dirname(path);
+    return { id, path: folder, opened: openWithOs(folder) };
+  }
   ensureDirs();
   return { path: assetsDir(), opened: openWithOs(assetsDir()) };
 }

package/src/runtime/media/store.test.mjs

@@ -52,12 +52,42 @@ test('media assets are organized by kind, provider, model, and local date while
 
   try {
     const store = await import(`./store.mjs?test=${Date.now()}`);
-    const listed = store.listMediaAssets({ limit: 10 }).assets;
+    const beforeMigration = store.listMediaAssets({ limit: 10 }).assets;
+    assert.equal(beforeMigration[0].file, 'legacy-image.jpg',
+      'read-only listing must not run the write-side layout migration');
+    const saved = store.saveMediaAsset({
+      kind: 'video',
+      lane: 'gemini',
+      model: 'veo:3/preview',
+      prompt: 'new clip',
+      options: { aspectRatio: '16:9' },
+      mime: 'video/mp4',
+      bytes: Buffer.from('new-video'),
+    });
+    const migrated = store.listMediaAssets({ limit: 10 }).assets;
+    const listed = ['legacy-image', 'legacy-video'].map((id) =>
+      migrated.find((entry) => entry.id === id));
     assert.equal(listed[0].file, 'images/gemini/image-alpha/2026-07-05/legacy-image.jpg');
     assert.equal(listed[1].file, 'videos/grok/video-beta/2026-07-05/legacy-video.mp4');
     assert.equal(existsSync(join(assetsDir, ...listed[0].file.split('/'))), true);
     assert.equal(existsSync(join(assetsDir, ...listed[1].file.split('/'))), true);
     assert.equal(existsSync(join(assetsDir, 'legacy-image.jpg')), false);
+    const cacheBeforeReads = store.mediaStoreCacheStats();
+    await Promise.all([
+      store.resolveMediaFile('legacy-image'),
+      store.resolveMediaFile('legacy-video'),
+      store.resolveMediaFile('legacy-image'),
+    ]);
+    const cacheAfterReads = store.mediaStoreCacheStats();
+    assert.equal(cacheAfterReads.indexDiskReads, cacheBeforeReads.indexDiskReads,
+      'a thumbnail-resolution burst must reuse the parsed media index');
+    assert.ok(cacheAfterReads.indexCacheHits >= cacheBeforeReads.indexCacheHits + 3);
+    const cachedOnlyMiss = await store.resolveMediaFile('legacy-image', {
+      variant: 'thumb',
+      generate: false,
+    });
+    assert.equal(cachedOnlyMiss.available, false,
+      'a local protocol probe must not start native rendition generation on a cache miss');
     assert.equal(
       (await store.readMediaAsset('legacy-video')).base64,
       Buffer.from('video').toString('base64'),
@@ -66,7 +96,10 @@ test('media assets are organized by kind, provider, model, and local date while
     // A tile-sized rendition is impossible for these stub bytes (and video
     // needs ffmpeg): the read must REPORT the miss instead of quietly
     // shipping the original, which is what made the remote gallery slow.
-    const missing = await store.readMediaAsset('legacy-image', { variant: 'thumb' });
+    const missing = await store.readMediaAsset('legacy-image', {
+      variant: 'thumb',
+      generate: false,
+    });
     assert.equal(missing.available, false);
     assert.equal(missing.base64, '');
     // Callers that can afford full-size bytes (local IPC) opt in explicitly
@@ -74,20 +107,29 @@ test('media assets are organized by kind, provider, model, and local date while
     const downgraded = await store.readMediaAsset('legacy-image', {
       variant: 'thumb',
       allowOriginal: true,
+      generate: false,
     });
     assert.equal(downgraded.variant, 'original');
     assert.equal(downgraded.downgraded, true);
     assert.equal(downgraded.base64, Buffer.from('image').toString('base64'));
-
-    const saved = store.saveMediaAsset({
-      kind: 'video',
-      lane: 'gemini',
-      model: 'veo:3/preview',
-      prompt: 'new clip',
-      options: { aspectRatio: '16:9' },
-      mime: 'video/mp4',
-      bytes: Buffer.from('new-video'),
+    const browserThumb = Buffer.from('browser-generated-thumbnail');
+    const cached = store.cacheMediaThumbnail('legacy-video', {
+      mime: 'image/jpeg',
+      base64: browserThumb.toString('base64'),
+      durationSeconds: 7,
     });
+    assert.equal(cached.available, true);
+    const cachedTarget = await store.resolveMediaFile('legacy-video', {
+      variant: 'thumb',
+      generate: false,
+    });
+    assert.equal(cachedTarget.available, true,
+      'a cache-only local protocol probe must serve a browser-generated rendition');
+    const cachedRead = await store.readMediaAsset('legacy-video', { variant: 'thumb' });
+    assert.equal(cachedRead.mime, 'image/jpeg');
+    assert.equal(cachedRead.base64, browserThumb.toString('base64'));
+    assert.equal(cachedRead.durationSeconds, 7);
+
     assert.match(saved.file, /^videos\/gemini\/veo-3-preview\/\d{4}-\d{2}-\d{2}\/[0-9a-f-]+\.mp4$/);
     assert.equal(existsSync(join(assetsDir, ...saved.file.split('/'))), true);
     assert.equal(store.deleteMediaAsset(saved.id).removed, true);