@1agh/maude 0.55.0 → 0.57.0

package/apps/studio/bin/_smart-frames.mjs

@@ -22,7 +22,8 @@
 // are unit-tested in _smart-frames.test.mjs.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -37,9 +38,24 @@ export function hasCommand(cmd) {
   return r.status === 0;
 }
 
-/** Resolve a python that can `import mlx_vlm`, or null. Honors $MAUDE_MLX_PYTHON. */
+/** The Maude-managed mlx-vlm venv python (mirrors generation/gemma-models.ts —
+ *  the Settings install command creates this venv, so the CLI must look there). */
+export function mlxVenvPython(env = process.env) {
+  const xdg = env.XDG_CACHE_HOME;
+  const base = xdg && xdg.length > 0 ? join(xdg, 'maude') : join(homedir(), '.maude');
+  return join(base, 'mlx-venv', 'bin', 'python3');
+}
+
+/** Resolve a python that can `import mlx_vlm`, or null. Order: $MAUDE_MLX_PYTHON
+ *  → the Maude-managed venv → PATH pythons. */
 export function resolveMlxPython(env = process.env) {
-  const candidates = [env.MAUDE_MLX_PYTHON, 'python3', 'python'].filter(Boolean);
+  const venvPy = mlxVenvPython(env);
+  const candidates = [
+    env.MAUDE_MLX_PYTHON,
+    existsSync(venvPy) ? venvPy : null,
+    'python3',
+    'python',
+  ].filter(Boolean);
   for (const py of candidates) {
     const r = spawnSync(py, ['-c', 'import mlx_vlm'], { stdio: 'ignore' });
     if (r.status === 0) return py;
@@ -47,22 +63,88 @@ export function resolveMlxPython(env = process.env) {
   return null;
 }
 
-export function detectAvailability(env = process.env) {
+/** Loopback-only literal hosts (mirrors the DDR-185 curl-local posture). No DNS
+ *  names besides `localhost` — a resolvable name could point anywhere (and
+ *  rebind between probe and use). */
+export function isLoopbackHostname(hostname) {
+  const h = (hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  return h === 'localhost' || h === '::1' || /^127(\.\d{1,3}){3}$/.test(h);
+}
+
+/** Local Ollama endpoint. Honors $OLLAMA_HOST (with or without scheme) but pins
+ *  it to loopback: the footage pipeline is egress-free by design (DDR-183) —
+ *  frames must never leave this machine, so a remote/LAN Ollama is refused
+ *  rather than silently uploaded to. Returns null when the value isn't loopback. */
+export function ollamaHost(env = process.env) {
+  const raw = (env.OLLAMA_HOST || '').trim();
+  if (!raw) return 'http://127.0.0.1:11434';
+  const url = /^https?:\/\//.test(raw) ? raw.replace(/\/$/, '') : `http://${raw}`;
+  try {
+    return isLoopbackHostname(new URL(url).hostname) ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Pick a vision-capable gemma tag from an /api/tags listing. gemma3:1b is
+ *  text-only and gemma3n is not multimodal in Ollama — exclude both.
+ *  $MAUDE_OLLAMA_MODEL wins verbatim. */
+export function pickOllamaGemmaTag(tags, env = process.env) {
+  const explicit = env.MAUDE_OLLAMA_MODEL;
+  if (explicit && explicit.length > 0) return explicit;
+  // Keep this predicate byte-identical to generation/gemma-models.ts's copy.
+  return tags.find((t) => /^gemma3:(?!1b)/.test(t) || t === 'gemma3') ?? null;
+}
+
+/** Probe a running Ollama server for a usable gemma vision model.
+ *  Returns { host, model } or null. */
+export async function detectOllama(env = process.env) {
+  const host = ollamaHost(env);
+  if (!host) return null; // $OLLAMA_HOST steered off loopback — refused
+  try {
+    // redirect: 'manual' — a redirecting "Ollama" is not Ollama; following one
+    // could carry the request off loopback.
+    const res = await fetch(`${host}/api/tags`, {
+      signal: AbortSignal.timeout(1500),
+      redirect: 'manual',
+    });
+    if (!res.ok) return null;
+    if (Number(res.headers.get('content-length') || 0) > 1024 * 1024) return null;
+    const body = await res.json();
+    const tags = (body.models || []).map((m) => m?.name).filter(Boolean);
+    const model = pickOllamaGemmaTag(tags, env);
+    return model ? { host, model } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Probe what's installed. `engine` lets us SKIP the Ollama network probe when it
+ *  can't change the outcome — an explicit `blind`/`ffmpeg` run, no ffmpeg at all,
+ *  or mlx-vlm already resolved (mlx wins anyway). A `--engine blind` run should
+ *  touch no sockets. */
+export async function detectAvailability(env = process.env, engine = 'auto') {
+  const ffmpeg = hasCommand('ffmpeg') && hasCommand('ffprobe');
+  const mlxPython = resolveMlxPython(env);
+  const ollamaCouldMatter =
+    ffmpeg && !mlxPython && (engine === 'auto' || engine === 'gemma' || !engine);
   return {
-    ffmpeg: hasCommand('ffmpeg') && hasCommand('ffprobe'),
-    mlxPython: resolveMlxPython(env),
+    ffmpeg,
+    mlxPython,
+    ollama: ollamaCouldMatter ? await detectOllama(env) : null,
   };
 }
 
 /** Pick the tier to actually run. Explicit engine wins (and errors if its deps are
  *  missing — no silent downgrade when the user asked for one); `auto` degrades
- *  gemma → ffmpeg → blind based on what's installed. */
+ *  gemma → ffmpeg → blind based on what's installed. The gemma tier runs on
+ *  either scout runtime: mlx-vlm (preferred — the benchmarked path) or Ollama. */
 export function selectTier(engine, avail) {
-  const gemmaOk = Boolean(avail.ffmpeg && avail.mlxPython);
+  const gemmaOk = Boolean(avail.ffmpeg && (avail.mlxPython || avail.ollama));
   if (engine && engine !== 'auto') {
     if (engine === 'gemma' && !gemmaOk)
       throw new Error(
-        'engine "gemma" needs ffmpeg + mlx-vlm (Apple Silicon). Install both or use --engine ffmpeg|blind|auto.'
+        'engine "gemma" needs ffmpeg + a scout runtime — mlx-vlm (Apple Silicon) or Ollama with a gemma3 vision model. Install one or use --engine ffmpeg|blind|auto.'
       );
     if (engine === 'ffmpeg' && !avail.ffmpeg)
       throw new Error(
@@ -87,6 +169,16 @@ export function parseSceneCuts(stderr) {
   return out.filter((t) => Number.isFinite(t));
 }
 
+/** Model-authored free text that lands in the manifest (and later in agent
+ *  prompts): strip control chars, cap the length. Injection-hardening — the
+ *  scout text is untrusted model output (DDR-183). */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control chars is the point.
+const CONTROL_CHARS = /[\x00-\x1f\x7f]/g;
+
+function sanitizeWhat(s) {
+  return (s || '').replace(CONTROL_CHARS, ' ').trim().slice(0, 120);
+}
+
 /** Parse a Gemma scout's text → beat timestamps. Accepts both `TIME=<sec>` and the
  *  `M:SS | what` shape the small model tends to emit. */
 export function parseBeats(text, durationSec) {
@@ -98,7 +190,7 @@ export function parseBeats(text, durationSec) {
   const reMS = /(?:^|\n)\s*(\d+):(\d{2}(?:\.\d+)?)\s*\|\s*([^\n]*)/g;
   // biome-ignore lint/suspicious/noAssignInExpressions: standard regex-exec loop.
   while ((m = reMS.exec(text)))
-    beats.push({ t: Number(m[1]) * 60 + Number(m[2]), what: (m[3] || '').trim() });
+    beats.push({ t: Number(m[1]) * 60 + Number(m[2]), what: sanitizeWhat(m[3]) });
   return beats.filter((b) => Number.isFinite(b.t) && b.t >= 0 && b.t <= durationSec);
 }
 
@@ -194,6 +286,65 @@ function extractFrame(clip, t, outPath) {
 const SCOUT_PROMPT = (dur) =>
   `You are a shot-list scout watching a ${dur}-second video clip. List the KEY moments an editor must see: the start of each distinct shot AND any peak action beat (a snap, a catch, a big movement, a reveal) — even inside a continuous shot. Do NOT space them evenly; pick only moments where something meaningful happens or changes. Output ONE line per moment, formatted EXACTLY as: TIME=<seconds> | <a few words>. Seconds must be real numbers between 0 and ${dur}.`;
 
+/** Ollama scout — same job as the mlx scout, different transport. Ollama has no
+ *  --video input, so we sample ≤16 evenly-spaced frames ourselves (ffmpeg is
+ *  guaranteed present in this tier), tell the model each frame's timestamp, and
+ *  send them as images to /api/chat. Coarser than mlx's native video path, but
+ *  scout beats only ADD candidate frames — ffmpeg cuts stay the precise backbone
+ *  (DDR-183), so coarse is acceptable. */
+export function ollamaScoutPrompt(durationSec, times) {
+  const map = times.map((t, i) => `frame ${i + 1} = t=${t.toFixed(2)}s`).join(', ');
+  return (
+    `${SCOUT_PROMPT(durationSec)}\n` +
+    `You are given ${times.length} frames sampled from the clip: ${map}. ` +
+    `Use these timestamps (or values between adjacent ones) as your TIME= values.`
+  );
+}
+
+async function ollamaScout(clip, durationSec, { host, model, fps }) {
+  const n = Math.max(4, Math.min(16, Math.round(durationSec * fps)));
+  const times = [];
+  for (let k = 0; k < n; k++)
+    times.push(
+      +Math.min(Math.max(0.05, (k * durationSec) / Math.max(1, n - 1)), durationSec - 0.05).toFixed(
+        3
+      )
+    );
+  const dir = mkdtempSync(join(tmpdir(), 'smart-frames-scout-'));
+  try {
+    const images = [];
+    for (const [i, t] of times.entries()) {
+      const png = join(dir, `s_${String(i + 1).padStart(2, '0')}.png`);
+      if (extractFrame(clip, t, png)) images.push(readFileSync(png).toString('base64'));
+    }
+    if (!images.length) return { beats: [], ok: false, raw: 'no scout frames extracted' };
+    const res = await fetch(`${host}/api/chat`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        model,
+        stream: false,
+        messages: [{ role: 'user', content: ollamaScoutPrompt(durationSec, times), images }],
+        options: { num_predict: 300 },
+      }),
+      // big vision models on CPU are slow — generous, but bounded
+      signal: AbortSignal.timeout(300_000),
+      redirect: 'manual', // never follow a redirect off the pinned loopback host
+    });
+    if (!res.ok) return { beats: [], ok: false, raw: `ollama HTTP ${res.status}` };
+    if (Number(res.headers.get('content-length') || 0) > 4 * 1024 * 1024)
+      return { beats: [], ok: false, raw: 'ollama response too large' };
+    const body = await res.json();
+    // A 300-token completion is a few KB — cap what enters the parse/manifest.
+    const text = (body?.message?.content || '').slice(0, 64 * 1024);
+    return { beats: parseBeats(text, durationSec), ok: true, raw: text };
+  } catch (e) {
+    return { beats: [], ok: false, raw: e?.message ? e.message : 'ollama scout failed' };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 function gemmaScout(clip, durationSec, { python, model, fps }) {
   const r = spawnSync(
     python,
@@ -301,7 +452,7 @@ function parseArgs(argv) {
   return o;
 }
 
-function main() {
+async function main() {
   const o = parseArgs(process.argv.slice(2));
   if (o.help || !o.asset) {
     process.stdout.write(
@@ -318,7 +469,7 @@ function main() {
     if (pref) o.engine = pref;
   }
 
-  const avail = detectAvailability();
+  const avail = await detectAvailability(process.env, o.engine);
   let tier;
   try {
     tier = selectTier(o.engine, avail);
@@ -362,17 +513,32 @@ function main() {
   const cuts = ffmpegSceneCuts(clip, o.sceneThresh);
   let beats = [];
   let method = 'ffmpeg';
+  let scoutKind = null;
   if (tier === 'gemma') {
-    const model = process.env.MAUDE_GEMMA_MODEL || 'mlx-community/gemma-4-e4b-it-4bit';
-    const scout = gemmaScout(clip, meta.durationSec, {
-      python: avail.mlxPython,
-      model,
-      fps: o.scoutFps,
-    });
+    // mlx-vlm preferred (benchmarked, native video input); Ollama is the
+    // accessible alternative runtime when mlx isn't installed.
+    let scout;
+    if (avail.mlxPython) {
+      scoutKind = 'mlx';
+      const model = process.env.MAUDE_GEMMA_MODEL || 'mlx-community/gemma-4-e4b-it-4bit';
+      scout = gemmaScout(clip, meta.durationSec, {
+        python: avail.mlxPython,
+        model,
+        fps: o.scoutFps,
+      });
+    } else {
+      scoutKind = 'ollama';
+      scout = await ollamaScout(clip, meta.durationSec, {
+        host: avail.ollama.host,
+        model: avail.ollama.model,
+        fps: o.scoutFps,
+      });
+    }
     if (scout.ok && scout.beats.length) {
       beats = scout.beats;
       method = 'gemma';
     } else {
+      scoutKind = null;
       process.stderr.write(
         'smart-frames: gemma scout produced no beats — falling back to ffmpeg tier\n'
       );
@@ -404,6 +570,7 @@ function main() {
     width: meta.width,
     height: meta.height,
     method,
+    scout: scoutKind,
     sceneCuts: cuts,
     scoutBeats: beats,
     outDir,
@@ -411,9 +578,9 @@ function main() {
   };
   process.stdout.write(`${JSON.stringify(manifest)}\n`);
   process.stderr.write(
-    `smart-frames: engine=${method} · ${frames.length} frames · ${cuts.length} scene cuts · ${beats.length} scout beats\n`
+    `smart-frames: engine=${method}${scoutKind ? ` (${scoutKind})` : ''} · ${frames.length} frames · ${cuts.length} scene cuts · ${beats.length} scout beats\n`
   );
 }
 
 // run only as a CLI, not when imported by the test
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) main();
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) await main();

package/apps/studio/bin/_smart-frames.test.mjs

@@ -10,8 +10,11 @@ import { join } from 'node:path';
 import {
   clipCandidates,
   mergeTimestamps,
+  ollamaHost,
+  ollamaScoutPrompt,
   parseBeats,
   parseSceneCuts,
+  pickOllamaGemmaTag,
   readEnginePref,
   selectTier,
 } from './_smart-frames.mjs';
@@ -85,17 +88,26 @@ describe('mergeTimestamps', () => {
 });
 
 describe('selectTier', () => {
-  const gemmaReady = { ffmpeg: true, mlxPython: 'python3' };
-  const ffmpegOnly = { ffmpeg: true, mlxPython: null };
-  const bare = { ffmpeg: false, mlxPython: null };
+  const gemmaReady = { ffmpeg: true, mlxPython: 'python3', ollama: null };
+  const ollamaReady = {
+    ffmpeg: true,
+    mlxPython: null,
+    ollama: { host: 'http://127.0.0.1:11434', model: 'gemma3:4b' },
+  };
+  const ffmpegOnly = { ffmpeg: true, mlxPython: null, ollama: null };
+  const bare = { ffmpeg: false, mlxPython: null, ollama: null };
 
   test('auto degrades gemma → ffmpeg → blind', () => {
     expect(selectTier('auto', gemmaReady)).toBe('gemma');
     expect(selectTier('auto', ffmpegOnly)).toBe('ffmpeg');
     expect(selectTier('auto', bare)).toBe('blind');
   });
+  test('ollama alone unlocks the gemma tier (no mlx-vlm needed)', () => {
+    expect(selectTier('auto', ollamaReady)).toBe('gemma');
+    expect(selectTier('gemma', ollamaReady)).toBe('gemma');
+  });
   test('explicit engine errors when its deps are missing (no silent downgrade)', () => {
-    expect(() => selectTier('gemma', ffmpegOnly)).toThrow(/mlx-vlm/);
+    expect(() => selectTier('gemma', ffmpegOnly)).toThrow(/mlx-vlm|Ollama/);
     expect(() => selectTier('ffmpeg', bare)).toThrow(/ffmpeg/);
   });
   test('blind is always allowed', () => {
@@ -103,6 +115,49 @@ describe('selectTier', () => {
   });
 });
 
+describe('ollama runtime helpers', () => {
+  test('pickOllamaGemmaTag picks a vision-capable gemma3 tag', () => {
+    expect(pickOllamaGemmaTag(['llama3:8b', 'gemma3:4b'], {})).toBe('gemma3:4b');
+    expect(pickOllamaGemmaTag(['gemma3:latest'], {})).toBe('gemma3:latest');
+    expect(pickOllamaGemmaTag(['gemma3:12b'], {})).toBe('gemma3:12b');
+  });
+  test('pickOllamaGemmaTag excludes text-only tags', () => {
+    expect(pickOllamaGemmaTag(['gemma3:1b'], {})).toBe(null);
+    expect(pickOllamaGemmaTag(['gemma3n:e4b'], {})).toBe(null);
+    expect(pickOllamaGemmaTag(['llama3:8b'], {})).toBe(null);
+  });
+  test('$MAUDE_OLLAMA_MODEL wins verbatim', () => {
+    expect(pickOllamaGemmaTag(['gemma3:4b'], { MAUDE_OLLAMA_MODEL: 'gemma3:27b' })).toBe(
+      'gemma3:27b'
+    );
+  });
+  test('ollamaHost normalizes $OLLAMA_HOST and pins it to loopback', () => {
+    expect(ollamaHost({})).toBe('http://127.0.0.1:11434');
+    expect(ollamaHost({ OLLAMA_HOST: 'http://localhost:11434/' })).toBe('http://localhost:11434');
+    expect(ollamaHost({ OLLAMA_HOST: '127.0.0.1:11434' })).toBe('http://127.0.0.1:11434');
+    expect(ollamaHost({ OLLAMA_HOST: '[::1]:11434' })).toBe('http://[::1]:11434');
+    // non-loopback = refused (frames must never leave this machine — DDR-183)
+    expect(ollamaHost({ OLLAMA_HOST: '0.0.0.0:11434' })).toBe(null);
+    expect(ollamaHost({ OLLAMA_HOST: '192.168.1.20:11434' })).toBe(null);
+    expect(ollamaHost({ OLLAMA_HOST: 'http://ollama.internal:11434' })).toBe(null);
+    expect(ollamaHost({ OLLAMA_HOST: 'http://169.254.169.254' })).toBe(null);
+  });
+  test('parseBeats sanitizes model-authored labels (control chars stripped, capped)', () => {
+    const evil = `0:05 | a\x00b\x1bc ${'x'.repeat(300)}`;
+    const beats = parseBeats(evil, 10);
+    expect(beats).toHaveLength(1);
+    expect(beats[0].what.length).toBeLessThanOrEqual(120);
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting that control chars were stripped is the point.
+    expect(beats[0].what).not.toMatch(/[\x00-\x1f]/);
+  });
+  test('ollamaScoutPrompt maps frames to timestamps', () => {
+    const p = ollamaScoutPrompt(10, [0.05, 5, 9.95]);
+    expect(p).toContain('frame 1 = t=0.05s');
+    expect(p).toContain('frame 3 = t=9.95s');
+    expect(p).toContain('TIME=');
+  });
+});
+
 describe('clipCandidates', () => {
   test('tries raw, root-relative, and designRoot/assets locations', () => {
     const c = clipCandidates('assets/abc12345.mp4', '/repo', '.design');

package/apps/studio/bin/_transcribe.mjs

@@ -123,7 +123,7 @@ function parseArgs(argv) {
 }
 
 const CLOUD_PROVIDERS = new Set(['elevenlabs', 'groq']);
-const KNOWN_PROVIDERS = new Set(['whisper', 'elevenlabs', 'groq']);
+const KNOWN_PROVIDERS = new Set(['auto', 'whisper', 'elevenlabs', 'groq']);
 
 /**
  * Resolve the transcription engine as an EXPLICIT choice (Task 2.6): the
@@ -136,7 +136,7 @@ export function resolveProvider(flag, repo) {
   if (flag) {
     if (!KNOWN_PROVIDERS.has(flag)) {
       process.stderr.write(
-        `transcribe: unknown --provider '${flag}' (use whisper | elevenlabs | groq)\n`
+        `transcribe: unknown --provider '${flag}' (use auto | whisper | elevenlabs | groq)\n`
       );
       process.exit(2);
     }
@@ -148,6 +148,39 @@ export function resolveProvider(flag, repo) {
   return { provider: 'whisper', defaulted: true };
 }
 
+/**
+ * Settle an `auto` choice into a concrete engine. `auto` prefers a cloud engine
+ * whose key is set (ElevenLabs Scribe first), else local whisper — mirroring
+ * generation/whisper-models.ts `resolveAutoEngine`. Key presence lives
+ * server-side (the keychain), so this asks the local dev server; with no server
+ * reachable there is no key to use anyway, so it settles on local whisper.
+ *
+ * Still no SILENT cloud switch (DDR-164): `auto` is a chosen mode, and the
+ * caller prints which engine it resolved to before transcribing.
+ */
+export async function settleAutoProvider(provider, port) {
+  if (provider !== 'auto') return { provider, autoReason: null };
+  const base = `http://127.0.0.1:${port || process.env.MAUDE_PORT || 4399}`;
+  try {
+    const res = await fetch(`${base}/_api/generate/providers`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    if (res.ok) {
+      const body = await res.json();
+      const keyed = new Set(
+        (body.providers || []).filter((p) => p && p.configured).map((p) => p.id)
+      );
+      if (keyed.has('elevenlabs'))
+        return { provider: 'elevenlabs', autoReason: 'auto → ElevenLabs Scribe (key is set)' };
+      if (keyed.has('groq'))
+        return { provider: 'groq', autoReason: 'auto → Groq Whisper (key is set)' };
+    }
+  } catch {
+    /* no server / no keys — local whisper is the honest answer */
+  }
+  return { provider: 'whisper', autoReason: 'auto → local whisper.cpp (no cloud key set)' };
+}
+
 /** Read `.design/config.json` → generation.transcription.provider, or null. */
 function readConfigProvider(repo) {
   try {
@@ -303,7 +336,11 @@ async function main() {
   // Resolve the engine as an explicit choice (Task 2.6). A chosen cloud engine
   // routes through the dev server (key server-side); the local default stays
   // whisper. We NEVER auto-switch between them.
-  const { provider, defaulted } = resolveProvider(args.provider, repo);
+  const { provider: chosen, defaulted } = resolveProvider(args.provider, repo);
+  // `auto` settles into a concrete engine here, and we SAY which — the engine is
+  // never a mystery even when the user delegated the pick (DDR-164).
+  const { provider, autoReason } = await settleAutoProvider(chosen, args.port);
+  if (autoReason) process.stderr.write(`transcribe: ${autoReason}\n`);
   if (defaulted)
     process.stderr.write(
       'transcribe: no engine configured — using local whisper ' +

package/apps/studio/bin/smoke.sh

@@ -157,7 +157,13 @@ if [ "$CHANGED_ONLY" = "1" ]; then
         git -C "$REPO" ls-files --others --exclude-standard -- .design/ui .design/system 2>/dev/null
       } | sort -u
     )
-    if printf '%s\n' "$CHANGED" | grep -qE 'dev-server/|canvas-lib\.tsx|canvas[^/]*\.tsx\.template'; then
+    # `apps/studio/` is the dev server. The pattern used to say `dev-server/`,
+    # which is where it lived before the move — so from the rename until
+    # 2026-08-06 the escalation silently never fired, and a dev-server change
+    # got the narrow "only canvases that changed" sweep instead of the full one.
+    # Kept alongside the old path rather than replaced: a --changed-only run in
+    # an older checkout should still escalate.
+    if printf '%s\n' "$CHANGED" | grep -qE 'apps/studio/|dev-server/|canvas-lib\.tsx|canvas[^/]*\.tsx\.template'; then
       echo "→ --changed-only: dev-server / canvas-lib / template changed — escalating to FULL set" >&2
     else
       # Keep only canvases whose repo-relative path is in the changed set.

package/apps/studio/build.ts

@@ -24,7 +24,6 @@ import { browserslistToTargets, bundle as lcssBundle } from 'lightningcss';
 import { cloudStubPlugin } from './cloud-build.ts';
 
 const ROOT = dirname(fileURLToPath(import.meta.url));
-const DIST = join(ROOT, 'dist');
 
 const ARGS = new Set(process.argv.slice(2));
 const FLAG_TARGET = process.argv.find((a) => a.startsWith('--target='))?.slice('--target='.length);
@@ -33,6 +32,34 @@ const MODE: 'dev' | 'release' | 'dry' = ARGS.has('--dry-run')
   : ARGS.has('--release')
     ? 'release'
     : 'dev';
+
+// DEV-ONLY override, so a test can build somewhere disposable.
+//
+// `test/bundle-smoke.test.ts` shells out to this script to prove the bundle
+// still parses — and, until this existed, wrote its unminified DEV output
+// straight over the COMMITTED release artifacts (14 MB where 2 MB ships). What
+// is committed is what ships, so a suite run silently staged a broken release.
+// CLAUDE.md recorded this as "observed, root cause unconfirmed"; it is this.
+//
+// REFUSED OUTSIDE DEV, and that guard is the whole point of the variable being
+// safe. DIST is the write target for every artifact — client bundle, styles,
+// dist/runtime/*, and the compiled server binary. One environment variable
+// reaching a release runner would send all of them to a scratch directory, exit
+// 0 with normal-looking size lines, and leave packaging to ship the COMMITTED
+// artifacts instead. `check-runtime-bundles.sh` would validate those stale
+// files and pass; `check-client-boots.mjs` would boot them and pass. Every gate
+// green, nothing built actually shipped — a silent downgrade primitive with no
+// diff and no red CI. This repo's doctrine is "what is committed is what ships"
+// AND "verify the built artifact"; an unguarded override severs the two.
+if (process.env.MAUDE_DIST_DIR && MODE !== 'dev') {
+  console.error(
+    `[build] MAUDE_DIST_DIR is a dev/test-only override and must not be set for a --${MODE} build.\n` +
+      `        Refusing to build: a release that writes elsewhere ships the previously committed\n` +
+      `        artifacts while every packaging gate stays green.`
+  );
+  process.exit(2);
+}
+const DIST = process.env.MAUDE_DIST_DIR || join(ROOT, 'dist');
 const WATCH = ARGS.has('--watch');
 /** Cloud Phase 27 D1 — build the CELL's variant (secret-bearing surfaces
  *  removed from the binary, not merely un-routed). `--cloud` with `--release`. */