mixdog 0.9.70 → 0.9.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.70",
+  "version": "0.9.71",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -87,6 +87,7 @@
     "test:workflow-editor": "node --test scripts/workflow-id-test.mjs scripts/workflow-pack-editor-test.mjs",
     "test:route-scope": "node --test scripts/route-scope-isolation-test.mjs",
     "test:schedule-reload": "node --test scripts/schedule-reload-arm-test.mjs",
+    "test:media": "node --test src/runtime/media/store.test.mjs",
     "failures": "node scripts/tool-failures.mjs",
     "trace:llm": "node scripts/llm-trace-summary.mjs",
     "diag:sessions": "node scripts/session-diag.mjs",

package/src/runtime/agent/orchestrator/session/manager/pending-messages.mjs

@@ -706,8 +706,22 @@ export function enqueueRemotePendingMessage(sessionId, message) {
 }
 
 // Spool-file mtime gate so the owner's idle poller costs one stat per tick,
-// not a locked read-modify-write.
-let _foreignSpoolScanMtime = 0;
+// not a locked read-modify-write. Keyed PER SESSION: one process can own
+// several sessions (desktop tabs, TUI + engine hosts) and a single shared
+// counter let the first drain of a tick swallow the mtime bump for every
+// other session, stranding their foreign submits until the next spool write.
+const FOREIGN_SPOOL_SCAN_LIMIT = 64;
+const _foreignSpoolScanMtimes = new Map();
+
+function _rememberForeignSpoolScan(sessionId, mtime) {
+    _foreignSpoolScanMtimes.delete(sessionId);
+    _foreignSpoolScanMtimes.set(sessionId, mtime);
+    while (_foreignSpoolScanMtimes.size > FOREIGN_SPOOL_SCAN_LIMIT) {
+        const oldest = _foreignSpoolScanMtimes.keys().next().value;
+        if (oldest === undefined) break;
+        _foreignSpoolScanMtimes.delete(oldest);
+    }
+}
 
 /**
  * Owner-side drain of FOREIGN user injections for a session this process
@@ -721,8 +735,8 @@ export function drainForeignUserInjections(sessionId) {
     if (!isValidPendingSessionId(sessionId)) return [];
     let mtime = 0;
     try { mtime = statSync(pendingMessagesPath()).mtimeMs || 0; } catch { return []; }
-    if (mtime === _foreignSpoolScanMtime) return [];
-    _foreignSpoolScanMtime = mtime;
+    if (_foreignSpoolScanMtimes.get(sessionId) === mtime) return [];
+    _rememberForeignSpoolScan(sessionId, mtime);
     const localIds = new Set();
     for (const map of [_sessionPendingMessages, _pendingPersistBuffers, _hydratedPendingMessages]) {
         for (const entry of map.get(sessionId) || []) {

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -6,7 +6,7 @@
 import { getProvider } from '../../providers/registry.mjs';
 import { normalizeCompactType, DEFAULT_COMPACT_TYPE } from '../compact.mjs';
 import { collectPromptSkillsCached, buildSkillManifest, composeSystemPrompt } from '../../context/collect.mjs';
-import { saveSession, saveSessionAsync, saveSessionAsyncDeferred, loadSession, setLiveSession, readSessionHeartbeatMtime, readSessionPresenceMtime, isSessionPresenceOwnerDead, deleteSessionPresence } from '../store.mjs';
+import { saveSession, saveSessionAsync, saveSessionAsyncDeferred, loadSession, setLiveSession, readSessionHeartbeatMtime, readSessionPresenceMtime, isSessionPresenceOwnerDead, deleteSessionPresence, isSessionHeartbeatOwnerDead, readSessionHeartbeatOwnerPid, deleteHeartbeat, isProcessAlive } from '../store.mjs';
 import { _getRuntimeEntry } from './runtime-liveness.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
 import { getHiddenAgent } from '../../internal-agents.mjs';
@@ -547,6 +547,18 @@ export function prefetchSession(sessionId, preset = 'full') {
     return true;
 }
 
+// Owner-pid hint for liveness signals that carry NO pid of their own:
+// `session.lastHeartbeatAt` is persisted in the session file and therefore
+// survives its writer forever, and pre-pid `.hb` sidecars only hold a
+// timestamp. The recorded client host is the process that created/claimed the
+// runtime for this session; the session-id prefix is the legacy fallback.
+function _recordedOwnerPid(session, sessionId) {
+    const recorded = Number(session?.clientHostPid) || 0;
+    if (recorded > 0) return recorded;
+    const match = /^sess_(\d+)_/.exec(String(sessionId || ''));
+    return Number(match?.[1]) || 0;
+}
+
 function _isActivelyOwnedElsewhere(session, sessionId) {
     // This process already owns the runtime for the id — switching back to
     // one of our own sessions (desktop tab switch, TUI /resume) never attaches.
@@ -560,19 +572,40 @@ function _isActivelyOwnedElsewhere(session, sessionId) {
         deleteSessionPresence(sessionId);
         return false;
     }
+    const now = Date.now();
+    // Presence (`.own`, pid-verified just above) covers the idle gaps between
+    // turns: a live interactive surface keeps refreshing it (~20s) for its
+    // CURRENT session, so cross-opening an idle-but-open session still
+    // attaches as a viewer instead of splitting ownership into two writers
+    // that clobber each other's saves.
+    const presenceAt = Number(readSessionPresenceMtime(sessionId)) || 0;
+    if (presenceAt > 0 && now - presenceAt <= ACTIVE_OWNER_HB_FRESH_MS) return true;
     // Heartbeats publish only while a turn is running (≤5s cadence) and the
     // sidecar is deleted on detach/close, so freshness here means another
-    // process is mid-conversation on this session right now. Presence (`.own`)
-    // covers the idle gaps between turns: a live interactive surface keeps
-    // refreshing it (~20s) for its CURRENT session, so cross-opening an
-    // idle-but-open session still attaches as a viewer instead of splitting
-    // ownership into two writers that clobber each other's saves.
-    const lastHb = Math.max(
-        Number(readSessionHeartbeatMtime(sessionId)) || 0,
-        Number(session.lastHeartbeatAt) || 0,
-        Number(readSessionPresenceMtime(sessionId)) || 0,
-    );
-    return lastHb > 0 && Date.now() - lastHb <= ACTIVE_OWNER_HB_FRESH_MS;
+    // process is mid-conversation on this session right now — PROVIDED that
+    // process still exists. Without the pid check a force-killed owner (app
+    // upgrade restart, crash) kept looking live for the whole freshness
+    // window, so every cross-open attached as a viewer and the user's
+    // messages spooled to a queue nobody drains (silently dropped 30m later).
+    if (isSessionHeartbeatOwnerDead(sessionId)) {
+        void deleteHeartbeat(sessionId);
+        return false;
+    }
+    const sidecarAt = Number(readSessionHeartbeatMtime(sessionId)) || 0;
+    if (sidecarAt > 0 && now - sidecarAt <= ACTIVE_OWNER_HB_FRESH_MS
+        && readSessionHeartbeatOwnerPid(sessionId) > 0) {
+        // Fresh sidecar whose recorded pid is alive: a real owner is driving
+        // this session right now, whatever the session file remembers.
+        return true;
+    }
+    const heartbeatAt = Math.max(sidecarAt, Number(session.lastHeartbeatAt) || 0);
+    if (!(heartbeatAt > 0 && now - heartbeatAt <= ACTIVE_OWNER_HB_FRESH_MS)) return false;
+    // Pid-less evidence only (persisted field / legacy sidecar): fall back to
+    // the recorded client-host pid. A dead host means no owner; an unknown pid
+    // keeps the conservative attach.
+    const ownerPid = _recordedOwnerPid(session, sessionId);
+    if (ownerPid > 0 && !isProcessAlive(ownerPid)) return false;
+    return true;
 }
 
 // Viewer self-heal probe: true when a re-resume of this session would NO

package/src/runtime/agent/orchestrator/session/store/listing.mjs

@@ -10,6 +10,7 @@ import { resolveAgentTerminalReapMs } from '../../../../../session-runtime/confi
 import { getStoreDir, sessionPath } from './paths-heartbeat.mjs';
 import { isCancelledWrite as _isCancelledWrite } from './write-guards.mjs';
 import {
+    SESSION_SUMMARY_INDEX_VERSION,
     summaryIndexPath,
     _sessionSummary,
     _normalizeSummaryIndex,

package/src/runtime/agent/orchestrator/session/store/paths-heartbeat.mjs

@@ -19,13 +19,40 @@ export function sessionPath(id) {
     return join(getStoreDir(), `${id}.json`);
 }
 
+// ── Sidecar owner-pid helpers ─────────────────────────────
+// Liveness sidecars record the publishing process id on their SECOND line so
+// a reader can tell a genuinely live owner from a force-killed one whose
+// timestamp still looks fresh. Legacy (pid-less) sidecars read back as 0.
+export function isProcessAlive(pid) {
+    const target = Number(pid) || 0;
+    if (target <= 0) return false;
+    try {
+        process.kill(target, 0);
+        return true;
+    } catch (error) {
+        // ESRCH: no such process. EPERM means the pid exists (alive).
+        return error?.code !== 'ESRCH';
+    }
+}
+
+function _readSidecarOwnerPid(path) {
+    try {
+        if (!existsSync(path)) return 0;
+        return Number(String(readFileSync(path, 'utf8')).split('\n')[1]) || 0;
+    } catch {
+        return 0;
+    }
+}
+
 // ── Heartbeat publish ─────────────────────────────────────
 // Lightweight per-session timestamp file (`<id>.hb`) consumed by the
 // status aggregator for fresh-session detection. Decoupled from the
 // full session JSON save so it can fire at a tight cadence (≤5s)
-// without serialising the whole payload. The .hb file holds a single
-// ASCII line: `<msTimestamp>\n`. Aggregator scans the same sessions/
-// directory and matches `<id>.hb` to `<id>.json`.
+// without serialising the whole payload. The .hb file holds
+// `<msTimestamp>\n<pid>\n` — readers that only need liveness use the file
+// mtime, while the attach-on-resume guard verifies the recorded pid.
+// Aggregator scans the same sessions/ directory and matches `<id>.hb` to
+// `<id>.json`.
 const _HEARTBEAT_THROTTLE_MS = 5_000;
 const _hbLastAt = new Map();
 const _hbOperations = new Map();
@@ -56,7 +83,7 @@ export function publishHeartbeat(id, ts) {
     }
     const target = _heartbeatPath(id);
     _hbLastAt.set(id, now);
-    return _queueHeartbeatOperation(id, () => fsp.writeFile(target, `${now}\n`, 'utf8'));
+    return _queueHeartbeatOperation(id, () => fsp.writeFile(target, `${now}\n${process.pid}\n`, 'utf8'));
 }
 
 export function deleteHeartbeat(id) {
@@ -91,6 +118,24 @@ export function listSessionHeartbeatMtimes() {
     return result;
 }
 
+// Owner pid recorded in the `<id>.hb` sidecar (0 when absent or written by a
+// pre-pid build).
+export function readSessionHeartbeatOwnerPid(id) {
+    if (!id) return 0;
+    try { return _readSidecarOwnerPid(_heartbeatPath(id)); } catch { return 0; }
+}
+
+// A killed owner never deletes its `.hb` sidecar, so bare mtime freshness
+// would keep the session "actively driven" for the whole freshness window and
+// every cross-open would attach as a viewer whose submits spool to nobody.
+// The recorded pid is authoritative proof; pid-less legacy sidecars return
+// false (unknown, not dead).
+export function isSessionHeartbeatOwnerDead(id) {
+    const pid = readSessionHeartbeatOwnerPid(id);
+    if (!pid) return false;
+    return !isProcessAlive(pid);
+}
+
 // ── Interactive presence publish ──────────────────────────
 // `<id>.own` marks a live interactive surface (TUI/desktop engine) HOLDING
 // the session open — including idle time between turns. Kept separate from
@@ -144,19 +189,7 @@ export function readSessionPresenceMtime(id) {
 export function isSessionPresenceOwnerDead(id) {
     if (!id) return false;
     let pid = 0;
-    try {
-        const path = _presencePath(id);
-        if (!existsSync(path)) return false;
-        pid = Number(String(readFileSync(path, 'utf8')).split('\n')[1]) || 0;
-    } catch {
-        return false;
-    }
+    try { pid = _readSidecarOwnerPid(_presencePath(id)); } catch { return false; }
     if (!pid) return false;
-    try {
-        process.kill(pid, 0);
-        return false;
-    } catch (error) {
-        // ESRCH: no such process. EPERM means the pid exists (alive).
-        return error?.code === 'ESRCH';
-    }
+    return !isProcessAlive(pid);
 }

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -54,6 +54,9 @@ export {
     deleteSessionPresence,
     readSessionPresenceMtime,
     isSessionPresenceOwnerDead,
+    readSessionHeartbeatOwnerPid,
+    isSessionHeartbeatOwnerDead,
+    isProcessAlive,
 } from './store/paths-heartbeat.mjs';
 import { _readStoredSessionCached } from './store/load-cache.mjs';
 import { _sessionForDisk, _renameWithRetrySync, _ensureLifecycleFields, _storedSessionFromFile } from './store/serialize.mjs';

package/src/runtime/media/index.mjs

@@ -10,6 +10,7 @@ export { startMediaJob, getMediaJob, listMediaJobs, cancelMediaJob } from './job
 export {
   listMediaAssets,
   readMediaAsset,
+  resolveMediaFile,
   deleteMediaAsset,
   mediaAssetPath,
   openMediaAsset,

package/src/runtime/media/renditions.mjs

@@ -0,0 +1,203 @@
+/**
+ * Derived renditions for the media gallery (thumb / display / video poster).
+ *
+ * A gallery tile is ~512px and a detail view never exceeds the viewport, so
+ * the original bytes are the wrong unit of transfer: over the remote link one
+ * full-size still costs more than the entire visible grid. Renditions are
+ * generated once, cached on disk beside the assets, and afterwards read back
+ * as small files.
+ *
+ * sharp (stills) and ffmpeg (video posters) are OPTIONAL. When neither can
+ * produce a rendition this module returns null and the caller reduces the
+ * feature (glyph tile) or explicitly asks for the original. It never silently
+ * substitutes full-size bytes for a thumbnail — that hidden path is exactly
+ * what made the remote gallery slow.
+ */
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+import { resolvePluginData } from '../shared/plugin-paths.mjs';
+
+// maxEdge is the long edge in pixels; quality is the webp setting.
+const SPECS = {
+  thumb: { maxEdge: 512, quality: 70 },
+  display: { maxEdge: 2048, quality: 82 },
+};
+// 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 POSTER_TIMEOUT_MS = 20_000;
+const MAX_POSTER_BYTES = 32 * 1024 * 1024;
+
+export const MEDIA_VARIANTS = Object.keys(SPECS);
+
+/** Spec for a variant name, or null when the caller asked for the original. */
+export function renditionSpec(variant) {
+  return SPECS[String(variant || '')] || null;
+}
+
+let sharpPromise;
+async function loadSharp() {
+  sharpPromise ??= import('sharp').then((mod) => mod?.default || mod || null, () => null);
+  return sharpPromise;
+}
+
+let ffmpegPromise;
+// The managed voice runtime already installs ffmpeg; reuse it rather than
+// shipping a second copy. MIXDOG_FFMPEG_PATH overrides for hosts that have
+// their own build.
+async function resolveFfmpeg() {
+  ffmpegPromise ??= (async () => {
+    const explicit = String(process.env.MIXDOG_FFMPEG_PATH || '').trim();
+    if (explicit && existsSync(explicit)) return explicit;
+    try {
+      const { resolveVoiceRuntime } = await import('../channels/lib/voice-runtime-fetcher.mjs');
+      const runtime = resolveVoiceRuntime(resolvePluginData());
+      return runtime?.ffmpegPath && existsSync(runtime.ffmpegPath) ? runtime.ffmpegPath : null;
+    } catch {
+      return null;
+    }
+  })();
+  return ffmpegPromise;
+}
+
+function renditionPath(cacheDir, variant, id, extension) {
+  return join(cacheDir, variant, `${id}${extension}`);
+}
+
+function cachedRendition(cacheDir, variant, id) {
+  for (const [extension, mime] of Object.entries(EXTENSION_MIME)) {
+    const path = renditionPath(cacheDir, variant, id, extension);
+    if (existsSync(path)) return { path, mime, bytes: statSync(path).size };
+  }
+  return null;
+}
+
+/** Drop every cached rendition of one asset (called when the asset dies). */
+export function removeRenditions(cacheDir, id) {
+  for (const variant of MEDIA_VARIANTS) {
+    for (const extension of Object.keys(EXTENSION_MIME)) {
+      try { unlinkSync(renditionPath(cacheDir, variant, id, extension)); } catch { /* absent */ }
+    }
+  }
+}
+
+function writeRendition(cacheDir, variant, id, extension, buffer) {
+  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}.tmp`;
+  writeFileSync(staging, buffer);
+  renameSync(staging, path);
+  return { path, mime: EXTENSION_MIME[extension], bytes: buffer.length };
+}
+
+/** Downscale a still (path or buffer) into a webp; null without sharp. */
+async function encodeStill(input, spec) {
+  const sharp = await loadSharp();
+  if (!sharp) return null;
+  try {
+    const buffer = await sharp(input)
+      // EXIF-rotated phone photos would otherwise land sideways in the grid.
+      .rotate()
+      .resize(spec.maxEdge, spec.maxEdge, { fit: 'inside', withoutEnlargement: true })
+      .webp({ quality: spec.quality })
+      .toBuffer();
+    return { extension: '.webp', buffer };
+  } catch {
+    // sharp present but the source is not a decodable image.
+    return null;
+  }
+}
+
+function parseDurationSeconds(text) {
+  const match = /Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/.exec(text || '');
+  if (!match) return 0;
+  const seconds = Number(match[1]) * 3600 + Number(match[2]) * 60 + Number(match[3]);
+  return Number.isFinite(seconds) ? Math.round(seconds) : 0;
+}
+
+/** First 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 chunks = [];
+    let total = 0;
+    let stderr = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child.kill(); } catch { /* already gone */ }
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(null), POSTER_TIMEOUT_MS);
+    timer.unref?.();
+    child.stdout.on('data', (chunk) => {
+      total += chunk.length;
+      // A corrupt clip could stream frames forever; the poster is one image.
+      if (total > MAX_POSTER_BYTES) {
+        finish(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    child.on('error', () => finish(null));
+    child.on('close', () => {
+      const buffer = Buffer.concat(chunks);
+      finish(buffer.length ? { buffer, durationSeconds: parseDurationSeconds(stderr) } : null);
+    });
+  });
+}
+
+// Two tiles asking for the same missing rendition must not both encode it.
+const inflight = new Map();
+
+async function generate({ id, kind, sourcePath, variant, spec, cacheDir }) {
+  if (kind === 'video') {
+    // Only the tile-sized poster is worth extracting: a "display" frame would
+    // be a still pretending to be a clip.
+    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);
+    return { ...written, durationSeconds: frame.durationSeconds };
+  }
+  const encoded = await encodeStill(sourcePath, spec);
+  return encoded ? writeRendition(cacheDir, variant, id, encoded.extension, encoded.buffer) : null;
+}
+
+/**
+ * Cached rendition for one asset, generating it on first use.
+ * 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 }) {
+  const spec = renditionSpec(variant);
+  if (!spec) return null;
+  const cached = cachedRendition(cacheDir, variant, id);
+  if (cached) return cached;
+  const key = `${variant}:${id}`;
+  const pending = inflight.get(key)
+    ?? generate({ id, kind, sourcePath, variant, spec, cacheDir })
+      .catch(() => null)
+      .finally(() => { inflight.delete(key); });
+  inflight.set(key, pending);
+  return pending;
+}

package/src/runtime/media/store.mjs

@@ -6,12 +6,13 @@
  * (newest first) and is written atomically under a file lock because the
  * desktop and CLI can generate concurrently.
  */
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, statSync } from 'fs';
-import { join } from 'path';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, statSync } from 'fs';
+import { dirname, join, resolve, sep } from 'path';
 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';
 
 const MAX_INDEX_ENTRIES = 2_000;
 // Renderer transport is base64 over IPC: refuse to inline anything larger.
@@ -23,6 +24,7 @@ const EXTENSIONS = {
   'image/webp': 'webp',
   'video/mp4': 'mp4',
 };
+let layoutMigrationChecked = false;
 
 function mediaDir() {
   return join(resolvePluginData(), 'media');
@@ -32,6 +34,12 @@ function assetsDir() {
   return join(mediaDir(), 'assets');
 }
 
+// Derived tile/detail renditions live beside the assets: they are a rebuildable
+// cache, so they never share the asset tree the user browses.
+function renditionsDir() {
+  return join(mediaDir(), 'renditions');
+}
+
 function indexPath() {
   return join(mediaDir(), 'index.json');
 }
@@ -42,6 +50,10 @@ function indexLockPath() {
 
 function ensureDirs() {
   mkdirSync(assetsDir(), { recursive: true });
+  if (!layoutMigrationChecked) {
+    migrateAssetLayout();
+    layoutMigrationChecked = true;
+  }
 }
 
 function readIndex() {
@@ -55,22 +67,86 @@ function readIndex() {
 }
 
 function writeIndex(assets) {
-  writeJsonAtomicSync(indexPath(), { version: 1, assets });
+  writeJsonAtomicSync(indexPath(), { version: 2, assets });
 }
 
 function extensionFor(mime) {
   return EXTENSIONS[String(mime || '').toLowerCase()] || 'bin';
 }
 
+function folderSegment(value, fallback) {
+  const normalized = String(value || '')
+    .normalize('NFKC')
+    .replace(/[<>:"/\\|?*\u0000-\u001f]/g, '-')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/[. ]+$/g, '')
+    .slice(0, 80);
+  if (!normalized || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(normalized)) {
+    return fallback;
+  }
+  return normalized;
+}
+
+function localDateFolder(createdAt) {
+  const date = new Date(Number(createdAt) || Date.now());
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function organizedAssetFile(entry) {
+  const kind = entry.kind === 'video' ? 'videos' : 'images';
+  const lane = folderSegment(entry.lane, 'unknown-provider');
+  const model = folderSegment(entry.model, 'unknown-model');
+  const date = localDateFolder(entry.createdAt);
+  const id = folderSegment(entry.id, 'asset');
+  return [kind, lane, model, date, `${id}.${extensionFor(entry.mime)}`].join('/');
+}
+
+function storedAssetPath(file) {
+  const root = resolve(assetsDir());
+  const path = resolve(root, String(file || ''));
+  return path === root || path.startsWith(`${root}${sep}`) ? path : null;
+}
+
+/** Move flat v1 assets into kind/provider/model/date folders without losing old indexes. */
+function migrateAssetLayout() {
+  withFileLockSync(indexLockPath(), () => {
+    const current = readIndex();
+    let changed = false;
+    const assets = current.map((entry) => {
+      const targetFile = organizedAssetFile(entry);
+      const sourcePath = storedAssetPath(entry.file);
+      const targetPath = storedAssetPath(targetFile);
+      if (!targetPath) return entry;
+      if (String(entry.file || '').replace(/\\/g, '/') === targetFile) return entry;
+      if (existsSync(targetPath)) {
+        changed = true;
+        return { ...entry, file: targetFile };
+      }
+      if (!sourcePath || !existsSync(sourcePath)) return entry;
+      try {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        renameSync(sourcePath, targetPath);
+        changed = true;
+        return { ...entry, file: targetFile };
+      } catch {
+        return entry;
+      }
+    });
+    if (changed) writeIndex(assets);
+  });
+}
+
 /** Persist one generated artifact and return its index entry. */
 export function saveMediaAsset({ kind, lane, model, prompt, options = {}, mime, bytes, meta = {} }) {
   ensureDirs();
   const id = randomUUID();
-  const file = `${id}.${extensionFor(mime)}`;
-  writeFileSync(join(assetsDir(), file), bytes);
+  const createdAt = Date.now();
   const entry = {
     id,
-    file,
     kind,
     lane,
     model,
@@ -78,49 +154,162 @@ export function saveMediaAsset({ kind, lane, model, prompt, options = {}, mime,
     options,
     mime,
     bytes: bytes.length,
-    createdAt: Date.now(),
+    createdAt,
     ...meta,
   };
+  const file = organizedAssetFile(entry);
+  const path = storedAssetPath(file);
+  if (!path) throw new Error('invalid media asset path');
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, bytes);
+  entry.file = file;
   withFileLockSync(indexLockPath(), () => {
     const assets = [entry, ...readIndex()];
     const kept = assets.slice(0, MAX_INDEX_ENTRIES);
     for (const dropped of assets.slice(MAX_INDEX_ENTRIES)) {
-      try { unlinkSync(join(assetsDir(), dropped.file)); } catch {}
+      const droppedPath = storedAssetPath(dropped.file);
+      try { if (droppedPath) unlinkSync(droppedPath); } catch {}
     }
     writeIndex(kept);
   });
+  // The first gallery paint after a generation would otherwise be the one that
+  // pays for the tile rendition; build it now, off the caller's path.
+  void ensureRendition({
+    id: entry.id,
+    kind: entry.kind,
+    sourcePath: path,
+    variant: 'thumb',
+    cacheDir: renditionsDir(),
+  });
   return entry;
 }
 
 export function listMediaAssets({ limit = 60, offset = 0, kind = null } = {}) {
+  ensureDirs();
   const all = readIndex().filter((entry) => (kind ? entry.kind === kind : true));
   const start = Math.max(0, Math.trunc(Number(offset) || 0));
   const count = Math.min(200, Math.max(1, Math.trunc(Number(limit) || 60)));
-  return { total: all.length, assets: all.slice(start, start + count) };
+  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(() => {});
 }
 
 export function getMediaAsset(id) {
+  ensureDirs();
   return readIndex().find((entry) => entry.id === id) || null;
 }
 
-/** Inline an asset for the renderer (base64 + mime). Large files are refused. */
-export function readMediaAsset(id) {
-  const entry = getMediaAsset(id);
-  if (!entry) return null;
-  const path = join(assetsDir(), entry.file);
-  if (!existsSync(path)) return null;
+/** Persist a duration probed while building a poster, so the gallery badge
+ *  survives a restart without decoding the clip again. */
+function rememberDuration(entry, durationSeconds) {
+  if (!durationSeconds || entry.durationSeconds === durationSeconds) return;
+  withFileLockSync(indexLockPath(), () => {
+    const assets = readIndex();
+    const row = assets.find((item) => item.id === entry.id);
+    if (!row || row.durationSeconds === durationSeconds) return;
+    row.durationSeconds = durationSeconds;
+    writeIndex(assets);
+  });
+  entry.durationSeconds = durationSeconds;
+}
+
+/** Base64 for the inline (RPC) path. Large files are refused: bytes that big
+ *  belong on the file route, not in a JSON frame. */
+function inlineBase64(path) {
   const size = statSync(path).size;
   if (size > MAX_INLINE_BYTES) {
     const err = new Error('media asset is too large to preview');
     err.code = 'MEDIA_ASSET_TOO_LARGE';
     throw err;
   }
-  return { ...entry, path, base64: readFileSync(path).toString('base64') };
+  return readFileSync(path).toString('base64');
+}
+
+/**
+ * Locate an asset (or one of its renditions) as a FILE — no inlining.
+ *
+ * This is the unit the media routes serve: the client receives a cacheable,
+ * range-able response instead of a base64 payload riding the RPC lane.
+ * `available: false` means this host cannot build the rendition (no sharp /
+ * no ffmpeg); the caller reduces the feature instead of substituting the
+ * original behind the client's back.
+ */
+export async function resolveMediaFile(id, { variant = 'original' } = {}) {
+  const entry = getMediaAsset(id);
+  if (!entry) return null;
+  const path = storedAssetPath(entry.file);
+  if (!path || !existsSync(path)) return null;
+  if (variant === 'original') return { ...entry, variant: 'original', path, available: true };
+  if (!renditionSpec(variant)) throw new Error(`unknown media variant: ${variant}`);
+  const rendition = await ensureRendition({
+    id: entry.id,
+    kind: entry.kind,
+    sourcePath: path,
+    variant,
+    cacheDir: renditionsDir(),
+  });
+  if (!rendition) return { ...entry, variant, path: '', available: false };
+  rememberDuration(entry, rendition.durationSeconds);
+  return {
+    ...entry,
+    ...(rendition.durationSeconds ? { durationSeconds: rendition.durationSeconds } : {}),
+    variant,
+    path: rendition.path,
+    mime: rendition.mime,
+    bytes: rendition.bytes,
+    available: true,
+  };
+}
+
+/**
+ * Inline an asset for the renderer (base64 + mime).
+ *
+ * `variant` selects a derived rendition ('thumb' | 'display'); the original is
+ * read only when it is asked for. A host that cannot build the rendition says
+ * 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 });
+  if (!file) return null;
+  if (file.available) return { ...file, base64: inlineBase64(file.path) };
+  if (!allowOriginal) return { ...file, base64: '' };
+  const original = await resolveMediaFile(id, { variant: 'original' });
+  if (!original) return null;
+  return { ...original, downgraded: true, base64: inlineBase64(original.path) };
 }
 
 export function mediaAssetPath(id) {
   const entry = getMediaAsset(id);
-  return entry ? join(assetsDir(), entry.file) : null;
+  return entry ? storedAssetPath(entry.file) : null;
 }
 
 /**
@@ -151,12 +340,15 @@ function openWithOs(path) {
 }
 
 export function deleteMediaAsset(id) {
+  ensureDirs();
   let removed = false;
   withFileLockSync(indexLockPath(), () => {
     const assets = readIndex();
     const entry = assets.find((row) => row.id === id);
     if (!entry) return;
-    try { unlinkSync(join(assetsDir(), entry.file)); } catch {}
+    const path = storedAssetPath(entry.file);
+    try { if (path) unlinkSync(path); } catch {}
+    removeRenditions(renditionsDir(), id);
     writeIndex(assets.filter((row) => row.id !== id));
     removed = true;
   });

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

@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+
+test('media assets are organized by kind, provider, model, and local date while flat files migrate', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'mixdog-media-store-'));
+  const previousDataDir = process.env.MIXDOG_DATA_DIR;
+  process.env.MIXDOG_DATA_DIR = root;
+  const assetsDir = join(root, 'media', 'assets');
+  const createdAt = new Date(2026, 6, 5, 12, 0, 0).getTime();
+  mkdirSync(assetsDir, { recursive: true });
+  writeFileSync(join(assetsDir, 'legacy-image.jpg'), Buffer.from('image'));
+  writeFileSync(join(assetsDir, 'legacy-video.mp4'), Buffer.from('video'));
+  writeFileSync(join(root, 'media', 'index.json'), JSON.stringify({
+    version: 1,
+    assets: [
+      {
+        id: 'legacy-image',
+        file: 'legacy-image.jpg',
+        kind: 'image',
+        lane: 'gemini',
+        model: 'image-alpha',
+        prompt: 'image',
+        options: { aspectRatio: '4:3' },
+        mime: 'image/jpeg',
+        bytes: 5,
+        createdAt,
+      },
+      {
+        id: 'legacy-video',
+        file: 'legacy-video.mp4',
+        kind: 'video',
+        lane: 'grok',
+        model: 'video-beta',
+        prompt: 'video',
+        options: { aspectRatio: '16:9' },
+        mime: 'video/mp4',
+        bytes: 5,
+        createdAt,
+      },
+    ],
+  }));
+
+  try {
+    const store = await import(`./store.mjs?test=${Date.now()}`);
+    const listed = store.listMediaAssets({ limit: 10 }).assets;
+    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);
+    assert.equal(
+      (await store.readMediaAsset('legacy-video')).base64,
+      Buffer.from('video').toString('base64'),
+    );
+
+    // 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' });
+    assert.equal(missing.available, false);
+    assert.equal(missing.base64, '');
+    // Callers that can afford full-size bytes (local IPC) opt in explicitly
+    // and get them labelled as a downgrade.
+    const downgraded = await store.readMediaAsset('legacy-image', {
+      variant: 'thumb',
+      allowOriginal: true,
+    });
+    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'),
+    });
+    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);
+    assert.equal(existsSync(join(assetsDir, ...saved.file.split('/'))), false);
+
+    const persisted = JSON.parse(readFileSync(join(root, 'media', 'index.json'), 'utf8'));
+    assert.equal(persisted.version, 2);
+  } finally {
+    if (previousDataDir === undefined) delete process.env.MIXDOG_DATA_DIR;
+    else process.env.MIXDOG_DATA_DIR = previousDataDir;
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/session-runtime/lifecycle-api.mjs

@@ -52,6 +52,15 @@ export function createLifecycleApi(deps) {
     pushTranscriptRebind,
     notificationListeners, remoteStateListeners, desktopSession,
   } = deps;
+  const closeSurfaceSession = (session, reason, options) => {
+    if (!session?.id) return false;
+    // A remote-attached session is only a viewer handle owned by this surface.
+    // Closing it through the shared manager bumps the durable generation and
+    // invalidates the real owner's in-flight turn. Viewer exits therefore
+    // detach locally; only the process that owns the runtime may close it.
+    if (session.remoteAttached === true) return true;
+    return mgr.closeSession(session.id, reason, options);
+  };
   const listLeadSessions = (options = {}) => {
     const heartbeatMtimes = listSessionHeartbeatMtimes();
     return mgr.listSessions({
@@ -245,7 +254,7 @@ export function createLifecycleApi(deps) {
         // first-turn exit could still burn a real session.
         const tombstone = !hasUserConversationMessage(session.messages)
           && !hasUserConversationMessage(session.liveTurnMessages);
-        ok = mgr.closeSession(session.id, reason, { tombstone });
+        ok = closeSurfaceSession(session, reason, { tombstone });
         setSession(null);
       }
       invalidateContextStatusCache();
@@ -345,7 +354,7 @@ export function createLifecycleApi(deps) {
         statusRoutes?.clearGatewaySessionRoute?.(session.id);
         const tombstone = !hasUserConversationMessage(session.messages)
           && !hasUserConversationMessage(session.liveTurnMessages);
-        mgr.closeSession(session.id, cleanupReason, { tombstone });
+        closeSurfaceSession(session, cleanupReason, { tombstone });
         setSession(null);
       }
       setDesktopSession(nextDesktopSession && typeof nextDesktopSession === 'object'
@@ -376,7 +385,7 @@ export function createLifecycleApi(deps) {
         void ingestSessionIntoMemory(session);
         const tombstone = !hasUserConversationMessage(session.messages)
           && !hasUserConversationMessage(session.liveTurnMessages);
-        mgr.closeSession(session.id, 'cli-new', { tombstone });
+        closeSurfaceSession(session, 'cli-new', { tombstone });
         setSession(null);
       }
       invalidateContextStatusCache();
@@ -411,7 +420,7 @@ export function createLifecycleApi(deps) {
         void ingestSessionIntoMemory(prev);
         const tombstone = !hasUserConversationMessage(previousMessages)
           && !hasUserConversationMessage(previousLive);
-        mgr.closeSession(previousId, 'cli-resume', { tombstone });
+        closeSurfaceSession(prev, 'cli-resume', { tombstone });
       }
       setSession(resumed);
       applyResolvedCwd(resolveResumeCwd(resumed, getCurrentCwd()), { markRefresh: false });

package/src/session-runtime/media-api.mjs

@@ -31,8 +31,11 @@ export function createMediaApi() {
     async listMediaAssets(options) {
       return (await media()).listMediaAssets(options || {});
     },
-    async readMediaAsset(id) {
-      return (await media()).readMediaAsset(id);
+    async readMediaAsset(id, options) {
+      return (await media()).readMediaAsset(id, options || {});
+    },
+    async resolveMediaFile(id, options) {
+      return (await media()).resolveMediaFile(id, options || {});
     },
     async deleteMediaAsset(id) {
       return (await media()).deleteMediaAsset(id);

package/src/session-runtime/session-text.mjs

@@ -44,7 +44,6 @@ const SYNTHETIC_SESSION_TEXT_PATTERNS = Object.freeze([
   // "Re-attached after compaction…" rows in Recent (user report). Skipping
   // them titles the session from its first REAL user message instead.
   /^re-attached after compaction\b/i,
-  /^reference files:\s/i,
   /^the async (?:agent|shell) task\b/i,
 ]);
 

package/src/session-runtime/tool-catalog.mjs

@@ -131,6 +131,32 @@ function toolSearchNativePayload(catalog, names, provider = '') {
   };
 }
 
+// Schemas for tools that are ALREADY active. They are deliberately NOT added
+// to toolReferences/openaiTools: re-announcing them would rewrite the request
+// tools array and break the cached prefix. The caller only ever sees names
+// otherwise, so the parameter contract (enums, limits) rides in the RESULT.
+function activeToolSchemas(catalog, session, names) {
+  const wanted = new Set((names || []).map(clean).filter(Boolean));
+  if (!wanted.size) return [];
+  const seen = new Set();
+  const specs = [];
+  for (const pool of [Array.isArray(session?.tools) ? session.tools : [], catalog || []]) {
+    for (const tool of pool) {
+      const name = clean(tool?.name);
+      if (!name || !wanted.has(name) || seen.has(name)) continue;
+      seen.add(name);
+      specs.push({
+        name,
+        description: clean(tool?.description),
+        parameters: tool?.inputSchema && typeof tool.inputSchema === 'object'
+          ? tool.inputSchema
+          : { type: 'object', properties: {} },
+      });
+    }
+  }
+  return specs;
+}
+
 // Plain case-insensitive substring filter over name + description. No scores,
 // no aliases, no auto-selection: tool_search only lists and (via select)
 // loads. Empty query matches every row.
@@ -734,9 +760,14 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
         summary: '',
       })
     : null;
+  const alreadyActiveSchemas = activeToolSchemas(catalog, session, alreadyActive);
   const nativeSummary = [
     ...(loaded.length ? [`Loaded deferred tools: ${loaded.join(', ')}`] : []),
     ...(alreadyActive.length ? [`Already active: ${alreadyActive.join(', ')}`] : []),
+    // The native path replaces the whole JSON result with this summary
+    // (tool-batch), so an already-active tool's schema has to travel here or
+    // the caller keeps guessing its parameters.
+    ...(alreadyActiveSchemas.length ? [`Already-active schemas: ${JSON.stringify(alreadyActiveSchemas)}`] : []),
   ].join('\n');
   const nativeToolSearch = nativeToolSearchBase
     ? { ...nativeToolSearchBase, summary: nativeSummary || nativeToolSearchBase.summary }
@@ -754,6 +785,7 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
     ...(nativeToolSearch ? { nativeToolSearch } : {}),
     loaded,
     alreadyActive,
+    ...(alreadyActiveSchemas.length ? { alreadyActiveSchemas } : {}),
     missing,
     ...(blocked.length ? { blocked } : {}),
     ...mcpFields,

package/src/tui/dist/index.mjs

@@ -23945,7 +23945,6 @@ var SYNTHETIC_SESSION_TEXT_PATTERNS = Object.freeze([
   // "Re-attached after compaction…" rows in Recent (user report). Skipping
   // them titles the session from its first REAL user message instead.
   /^re-attached after compaction\b/i,
-  /^reference files:\s/i,
   /^the async (?:agent|shell) task\b/i
 ]);
 var LATE_TOOL_ANNOUNCEMENT_SENTINEL = "connected after this session started";
@@ -28406,7 +28405,8 @@ function createEngineApiB(bag) {
     // generation start posts a notice so the TUI shows background work.
     listMediaLanes: () => runtime.listMediaLanes?.(),
     listMediaAssets: (options) => runtime.listMediaAssets?.(options),
-    readMediaAsset: (id) => runtime.readMediaAsset?.(id),
+    readMediaAsset: (id, options) => runtime.readMediaAsset?.(id, options),
+    resolveMediaFile: (id, options) => runtime.resolveMediaFile?.(id, options),
     getMediaJob: (id) => runtime.getMediaJob?.(id),
     listMediaJobs: () => runtime.listMediaJobs?.(),
     // No notice on start: the Studio surfaces progress on its own pending tile,

package/src/tui/engine/session-api-ext.mjs

@@ -677,7 +677,8 @@ export function createEngineApiB(bag) {
     // generation start posts a notice so the TUI shows background work.
     listMediaLanes: () => runtime.listMediaLanes?.(),
     listMediaAssets: (options) => runtime.listMediaAssets?.(options),
-    readMediaAsset: (id) => runtime.readMediaAsset?.(id),
+    readMediaAsset: (id, options) => runtime.readMediaAsset?.(id, options),
+    resolveMediaFile: (id, options) => runtime.resolveMediaFile?.(id, options),
     getMediaJob: (id) => runtime.getMediaJob?.(id),
     listMediaJobs: () => runtime.listMediaJobs?.(),
     // No notice on start: the Studio surfaces progress on its own pending tile,