@1agh/maude 0.55.0 → 0.56.0

package/apps/studio/generation/gemma-models.ts

@@ -21,6 +21,39 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { cachedProbe, hasCommandCached, type SetupOption } from './runtime-probe.ts';
+
+/** Maude-managed venv for the mlx-vlm runtime. Lives next to the identity cache
+ *  (`$XDG_CACHE_HOME/maude` else `~/.maude`) — re-creatable with one command, so
+ *  cache-tier is fine. The install stays USER-RUN in a terminal (DDR-183: the
+ *  runtime is a manual step), but pointing the command at a dedicated venv makes
+ *  it PEP 668-proof (a bare `pip install` is refused by Homebrew/system Pythons)
+ *  and gives the probe a well-known place to look, so the app picks the install
+ *  up automatically. */
+export function mlxVenvDir(): string {
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg && xdg.length > 0 ? join(xdg, 'maude') : join(homedir(), '.maude');
+  return join(base, 'mlx-venv');
+}
+
+/** POSIX single-quote a path for a command the USER will paste into a shell.
+ *  Double quotes would let `$(…)`, backticks and `"` inside $XDG_CACHE_HOME /
+ *  $HOME survive into a command run unread; single quotes disarm everything but
+ *  `'` itself, which is closed-escaped-reopened. */
+function shellQuote(s: string): string {
+  return `'${s.replaceAll("'", `'\\''`)}'`;
+}
+
+/** The copy/paste one-liner the Settings card shows. Computed from the SAME path
+ *  the probe checks, so the two can never drift. Returns null when the resolved
+ *  path holds a newline or control char — no quoting makes a multi-line paste
+ *  safe, so the card shows no command rather than a dangerous one. */
+export function mlxInstallCommand(): string | null {
+  const dir = mlxVenvDir();
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing control chars is the point.
+  if (/[\x00-\x1f\x7f]/.test(dir)) return null;
+  return `python3 -m venv ${shellQuote(dir)} && ${shellQuote(join(dir, 'bin', 'pip'))} install -U mlx-vlm`;
+}
 
 export interface GemmaModelDescriptor {
   /** Stable id used by the pref + route. */
@@ -103,11 +136,16 @@ export function listGemmaModels(): GemmaModelStatus[] {
   return GEMMA_MODELS.map((m) => ({ ...m, downloaded: gemmaModelDownloaded(m) }));
 }
 
-/** Resolve a Python that can `import mlx_vlm` (honors $MAUDE_MLX_PYTHON), or null. */
+/** Resolve a Python that can `import mlx_vlm`, or null. Order: explicit
+ *  $MAUDE_MLX_PYTHON → the Maude-managed venv → PATH pythons. */
 export function resolveMlxPython(): string | null {
-  const candidates = [process.env.MAUDE_MLX_PYTHON, 'python3', 'python'].filter(
-    Boolean
-  ) as string[];
+  const venvPy = join(mlxVenvDir(), 'bin', 'python3');
+  const candidates = [
+    process.env.MAUDE_MLX_PYTHON,
+    existsSync(venvPy) ? venvPy : null,
+    'python3',
+    'python',
+  ].filter(Boolean) as string[];
   for (const py of candidates) {
     const r = spawnSync(py, ['-c', 'import mlx_vlm'], { stdio: 'ignore' });
     if (r.status === 0) return py;
@@ -122,22 +160,282 @@ export function resolveMlxPython(): string | null {
 // Memoize with a short TTL: DoS-bounded to at most one probe per PROBE_TTL_MS
 // regardless of request rate, while still picking up a mid-session `pip install` /
 // PATH change within the TTL.
+// The TTL cache + PATH probe live in runtime-probe.ts — shared with the whisper
+// stack, which has the same "never print an impossible instruction" problem.
 const PROBE_TTL_MS = 30_000;
-const probeCache = new Map<string, { at: number; value: boolean }>();
-
-function cachedProbe(key: string, compute: () => boolean): boolean {
-  const now = Date.now();
-  const hit = probeCache.get(key);
-  if (hit && now - hit.at < PROBE_TTL_MS) return hit.value;
-  const value = compute();
-  probeCache.set(key, { at: now, value });
-  return value;
-}
 
 export function mlxVlmAvailable(): boolean {
   return cachedProbe('mlx', () => resolveMlxPython() !== null);
 }
 
+// ─── Ollama alternative runtime ──────────────────────────────────────────────
+// The scout can also run through a local Ollama server (gemma3 vision) — a far
+// simpler install story than mlx-vlm for most people: one app, `ollama pull`,
+// no Python. mlx stays preferred when both are present (it's the benchmarked
+// path, DDR-183); Ollama is the accessible alternative.
+
+/** The model the install/pull commands recommend (vision-capable, ~3.3 GB). */
+export const OLLAMA_RECOMMENDED_MODEL = 'gemma3:4b';
+
+/** Loopback-only literal hosts (mirrors the DDR-185 curl-local posture). No DNS
+ *  names besides `localhost` — a resolvable name could point anywhere. */
+export function isLoopbackHostname(hostname: string): boolean {
+  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 scout is egress-free by design (DDR-183): a remote/LAN
+ *  Ollama would silently upload the user's video frames, and on the server side
+ *  an unvalidated host would turn the probe route into an SSRF emitter. Returns
+ *  null when the value isn't loopback. */
+export function ollamaHost(): string | null {
+  const raw = (process.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;
+  }
+}
+
+export interface OllamaStatus {
+  /** The server answered /api/tags. */
+  available: boolean;
+  /** A usable vision-capable gemma tag ($MAUDE_OLLAMA_MODEL wins), or null. */
+  model: string | null;
+  /** Every tag the local server has (drives the per-model "downloaded" state). */
+  tags: string[];
+  /** The `ollama` binary is on PATH. Installed-but-not-running is a DIFFERENT
+   *  state from not-installed, and it needs the opposite advice ("start it",
+   *  not "install it") — the card would otherwise tell you to reinstall
+   *  software you already have. */
+  installed: boolean;
+}
+
+// Curated allowlist of Ollama scout models, mirroring GEMMA_MODELS for the mlx
+// runtime. The tag is the frozen pull target — NEVER user input, so the pull
+// can't be steered at an arbitrary repo. Ids are namespaced so one route can
+// serve both runtimes without ambiguity.
+export const OLLAMA_MODELS = [
+  {
+    id: 'ollama:gemma3:4b',
+    tag: 'gemma3:4b',
+    label: 'Gemma 3 4B (Ollama)',
+    sizeMB: 3300,
+    note: 'The recommended Ollama scout. ~3.3 GB. Pulled and managed by Ollama.',
+  },
+  {
+    id: 'ollama:gemma3:12b',
+    tag: 'gemma3:12b',
+    label: 'Gemma 3 12B (Ollama)',
+    sizeMB: 8100,
+    note: 'Sharper beats, needs more RAM. ~8.1 GB.',
+  },
+] as const;
+
+export function getOllamaModel(id: unknown): (typeof OLLAMA_MODELS)[number] | null {
+  return OLLAMA_MODELS.find((m) => m.id === id) ?? null;
+}
+
+/** The scout models offered for BOTH runtimes, each tagged with the runtime it
+ *  belongs to and whether it's already on disk — so one Settings list can show
+ *  "download" against whichever runtime the machine actually has. */
+export function listScoutModels(status: OllamaStatus) {
+  const mlx = listGemmaModels().map((m) => ({ ...m, runtime: 'mlx' as const }));
+  const ollama = OLLAMA_MODELS.map((m) => ({
+    ...m,
+    runtime: 'ollama' as const,
+    // An exact tag match; `gemma3:4b` and `gemma3:4b-it-q4_K_M` are different pulls.
+    downloaded: status.tags.includes(m.tag),
+  }));
+  // Ollama first when it's the runtime that can actually act on a click.
+  return status.available ? [...ollama, ...mlx] : [...mlx, ...ollama];
+}
+
+/**
+ * Pull a model through the local Ollama server (`POST /api/pull`, NDJSON
+ * progress stream). Same egress discipline as everything else here: the host is
+ * loopback-pinned, redirects are refused, and the tag comes from the frozen
+ * allowlist — never from the request body.
+ */
+export async function pullOllamaModel(
+  id: string,
+  onProgress: (received: number, total: number) => void,
+  signal?: AbortSignal
+): Promise<void> {
+  const m = getOllamaModel(id);
+  if (!m) throw new Error(`unknown ollama model: ${id}`);
+  const host = ollamaHost();
+  if (!host) throw new Error('OLLAMA_HOST is not a loopback address — refusing to pull');
+
+  const res = await fetch(`${host}/api/pull`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ model: m.tag, stream: true }),
+    redirect: 'manual',
+    signal,
+  });
+  if (!res.ok || !res.body) throw new Error(`ollama pull failed (HTTP ${res.status})`);
+
+  // NDJSON: {"status":"pulling …","total":N,"completed":M} … {"status":"success"}
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = '';
+  let ok = false;
+  let lastErr = '';
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.split('\n');
+    buf = lines.pop() ?? '';
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const ev = JSON.parse(line) as {
+          status?: string;
+          total?: number;
+          completed?: number;
+          error?: string;
+        };
+        if (ev.error) lastErr = ev.error;
+        if (typeof ev.total === 'number' && ev.total > 0)
+          onProgress(Math.min(ev.total, ev.completed ?? 0), ev.total);
+        if (ev.status === 'success') ok = true;
+      } catch {
+        /* a partial/garbage line — the next read completes it */
+      }
+    }
+  }
+  if (!ok) throw new Error(lastErr || 'ollama pull did not report success');
+}
+
+const OLLAMA_DOWNLOAD_URL = 'https://ollama.com/download';
+
+/**
+ * The install routes that actually work on THIS machine, best first.
+ *
+ * The point is to never show an impossible instruction: `brew install` is noise
+ * without Homebrew, and the venv one-liner is noise without python3. The
+ * universal fallback is Ollama's official install script, which handles macOS
+ * AND Linux (on macOS it fetches Ollama-darwin.zip into /Applications) and needs
+ * only curl — present on both by default, so it works where brew doesn't.
+ */
+export function ollamaSetupOptions(status: OllamaStatus): SetupOption[] {
+  const opts: SetupOption[] = [];
+  if (status.installed && !status.available) {
+    opts.push({
+      id: 'start',
+      kind: 'command',
+      label: 'Ollama is installed but not running — start it',
+      command: 'ollama serve',
+      note: 'Or just open the Ollama app; it runs in the menu bar.',
+    });
+    return opts;
+  }
+  if (status.available) {
+    opts.push({
+      id: 'pull',
+      kind: 'command',
+      label: 'Ollama is running — it just needs a vision model',
+      command: `ollama pull ${OLLAMA_RECOMMENDED_MODEL}`,
+    });
+    return opts;
+  }
+  const plat = process.platform;
+  if ((plat === 'darwin' || plat === 'linux') && hasCommandCached('curl'))
+    opts.push({
+      id: 'script',
+      kind: 'command',
+      label: 'Install Ollama (official script — no Homebrew needed)',
+      command: `curl -fsSL https://ollama.com/install.sh | sh && ollama pull ${OLLAMA_RECOMMENDED_MODEL}`,
+      note: 'Works on macOS and Linux; needs only curl.',
+    });
+  if (plat === 'darwin' && hasCommandCached('brew'))
+    opts.push({
+      id: 'brew',
+      kind: 'command',
+      label: 'Install with Homebrew',
+      command: `brew install ollama && brew services start ollama && ollama pull ${OLLAMA_RECOMMENDED_MODEL}`,
+    });
+  opts.push({
+    id: 'download',
+    kind: 'link',
+    label: 'Download the Ollama app',
+    url: OLLAMA_DOWNLOAD_URL,
+    note: `Then run \`ollama pull ${OLLAMA_RECOMMENDED_MODEL}\` in a terminal.`,
+  });
+  return opts;
+}
+
+/** The mlx-vlm half, which only exists on Apple Silicon and only when a python3
+ *  is around to build the venv with. Returns the reason when it can't run, so
+ *  the card can say why instead of showing a command that would fail. */
+export function mlxSetup(): { supported: boolean; reason?: string; command?: string } {
+  if (process.platform !== 'darwin')
+    return { supported: false, reason: 'mlx-vlm is Apple-Silicon only — use Ollama instead.' };
+  if (process.arch !== 'arm64')
+    return {
+      supported: false,
+      reason: 'mlx needs Apple Silicon (this Mac is Intel) — use Ollama instead.',
+    };
+  if (!hasCommandCached('python3'))
+    return {
+      supported: false,
+      reason: 'No python3 on PATH — install Python 3, or just use Ollama (no Python needed).',
+    };
+  const command = mlxInstallCommand();
+  if (!command)
+    return {
+      supported: false,
+      reason: 'Can’t build a safe install command for this machine’s cache path — use Ollama.',
+    };
+  return { supported: true, command };
+}
+
+/** 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. */
+export function pickOllamaGemmaTag(tags: string[]): string | null {
+  const explicit = process.env.MAUDE_OLLAMA_MODEL;
+  if (explicit && explicit.length > 0) return explicit;
+  return tags.find((t) => /^gemma3:(?!1b)/.test(t) || t === 'gemma3') ?? null;
+}
+
+const ollamaCache = { at: 0, value: null as OllamaStatus | null };
+
+export async function ollamaStatus(): Promise<OllamaStatus> {
+  const now = Date.now();
+  if (ollamaCache.value && now - ollamaCache.at < PROBE_TTL_MS) return ollamaCache.value;
+  let value: OllamaStatus = {
+    available: false,
+    model: null,
+    tags: [],
+    installed: hasCommandCached('ollama'),
+  };
+  const host = ollamaHost(); // null = $OLLAMA_HOST steered off loopback — refused
+  if (host) {
+    try {
+      // redirect: 'manual' — never follow a redirect off the pinned loopback host.
+      const res = await fetch(`${host}/api/tags`, {
+        signal: AbortSignal.timeout(1500),
+        redirect: 'manual',
+      });
+      if (res.ok && Number(res.headers.get('content-length') || 0) <= 1024 * 1024) {
+        const body = (await res.json()) as { models?: Array<{ name?: string }> };
+        const tags = (body.models ?? []).map((m) => m.name).filter(Boolean) as string[];
+        value = { ...value, available: true, tags, model: pickOllamaGemmaTag(tags) };
+      }
+    } catch {
+      /* not running / not installed */
+    }
+  }
+  ollamaCache.at = now;
+  ollamaCache.value = value;
+  return value;
+}
+
 export function ffmpegAvailable(): boolean {
   return cachedProbe('ffmpeg', () => {
     const finder = process.platform === 'win32' ? 'where' : 'which';

package/apps/studio/generation/prefs.ts

@@ -12,8 +12,13 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-/** The transcription engines the selector offers (mirrors the config schema enum). */
-export const TRANSCRIPTION_PROVIDERS = ['whisper', 'elevenlabs', 'groq'] as const;
+/** The transcription engines the selector offers (mirrors the config schema enum).
+ *  `auto` picks the best engine the machine is equipped for — a cloud engine
+ *  when its key is set, else local whisper — and the UI states what it resolved
+ *  to. It is a SELECTED mode, not a silent fallback: DDR-164's rule (Maude never
+ *  switches to a paid/off-machine engine behind your back) survives because
+ *  choosing `auto` is itself the explicit act, and the resolution is shown. */
+export const TRANSCRIPTION_PROVIDERS = ['auto', 'whisper', 'elevenlabs', 'groq'] as const;
 export type TranscriptionProvider = (typeof TRANSCRIPTION_PROVIDERS)[number];
 
 export function isTranscriptionProvider(v: unknown): v is TranscriptionProvider {

package/apps/studio/generation/runtime-probe.ts

@@ -0,0 +1,50 @@
+// generation/runtime-probe.ts — shared "what can this machine actually do"
+// probing for the optional local runtimes (the Gemma scout's mlx-vlm/Ollama, the
+// subtitle stack's whisper.cpp).
+//
+// Two jobs, both learned the hard way:
+//
+//   1. Probes SPAWN. They sit behind un-authenticated (same-origin + loopback)
+//      GETs, so an unthrottled probe is a way to stall the single-threaded Bun
+//      event loop. Everything here is TTL-cached: at most one spawn per key per
+//      PROBE_TTL_MS regardless of request rate, while still noticing a
+//      mid-session install within the TTL.
+//
+//   2. A card must never print an instruction this machine can't follow.
+//      `brew install …` is noise without Homebrew; a venv one-liner is noise
+//      without python3. Callers build their setup routes from these probes and
+//      return only the viable ones, best first.
+
+import { spawnSync } from 'node:child_process';
+
+const PROBE_TTL_MS = 30_000;
+const probeCache = new Map<string, { at: number; value: boolean }>();
+
+export function cachedProbe(key: string, compute: () => boolean): boolean {
+  const now = Date.now();
+  const hit = probeCache.get(key);
+  if (hit && now - hit.at < PROBE_TTL_MS) return hit.value;
+  const value = compute();
+  probeCache.set(key, { at: now, value });
+  return value;
+}
+
+/** Is a command on PATH? */
+export function hasCommandCached(cmd: string): boolean {
+  return cachedProbe(`has:${cmd}`, () => {
+    const finder = process.platform === 'win32' ? 'where' : 'which';
+    return spawnSync(finder, [cmd], { stdio: 'ignore' }).status === 0;
+  });
+}
+
+/** One way to get a runtime onto THIS machine. `command` is copy/paste; `link`
+ *  is a URL — the desktop shell has no general URL opener by design (DDR-054),
+ *  so the client renders a copyable link rather than a button that can't work. */
+export interface SetupOption {
+  id: string;
+  kind: 'command' | 'link';
+  label: string;
+  command?: string;
+  url?: string;
+  note?: string;
+}

package/apps/studio/generation/whisper-models.ts

@@ -13,10 +13,12 @@
 // The actual download (streamed, SSRF-hardened, progress-tracked) lives in the
 // http route so the egress discipline sits next to the other provider egress.
 
+import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { mkdir, rename, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { cachedProbe, hasCommandCached, type SetupOption } from './runtime-probe.ts';
 
 export interface WhisperModelDescriptor {
   /** Stable id used by the config + route (`base`, `base.en`, …). */
@@ -270,3 +272,125 @@ export async function removeWhisperModel(id: string): Promise<boolean> {
   await rm(p, { force: true });
   return true;
 }
+
+// ─── Runtime detection + setup routes ────────────────────────────────────────
+// The card used to print `brew install whisper-cpp` unconditionally and never
+// checked whether the binary was actually there — so a machine without Homebrew
+// got an instruction it couldn't follow, and nobody learned the engine was
+// missing until a transcription failed.
+//
+// Unlike Ollama there is NO universal one-liner here: whisper.cpp's releases
+// ship prebuilt binaries for Ubuntu and Windows but NOT macOS (the xcframework
+// is an Xcode library, not a CLI), so on a Mac without brew the honest routes
+// are a cloud engine (already supported, needs only a key) or a source build.
+
+/** Resolve the whisper.cpp CLI, or null.
+ *
+ *  MUST stay byte-identical to `bin/_transcribe.mjs` `resolveWhisper()` — the
+ *  card would otherwise claim an engine the transcriber can't find. That
+ *  includes the security rule it documents: the bare name `main` is
+ *  DELIBERATELY not probed (it's a common executable name and the probe
+ *  EXECUTES each candidate, so `.` on $PATH inside an untrusted repo could
+ *  auto-run a seeded `main`). */
+export function resolveWhisperCli(): string | null {
+  const candidates = [process.env.MAUDE_WHISPER_CLI, 'whisper-cli', 'whisper'].filter(
+    Boolean
+  ) as string[];
+  for (const c of candidates) {
+    const probe = spawnSync(c, ['--help'], { stdio: 'ignore' });
+    if (!probe.error) return c;
+  }
+  return null;
+}
+
+export function whisperCliAvailable(): boolean {
+  return cachedProbe('whisper-cli', () => resolveWhisperCli() !== null);
+}
+
+export interface WhisperSetup {
+  /** The binary resolves — local transcription can actually run. */
+  installed: boolean;
+  /** Routes to get it, best first. Empty when it's already installed. */
+  options: SetupOption[];
+}
+
+export function whisperSetup(): WhisperSetup {
+  if (whisperCliAvailable()) return { installed: true, options: [] };
+  const options: SetupOption[] = [];
+  if (hasCommandCached('brew'))
+    options.push({
+      id: 'brew',
+      kind: 'command',
+      label: 'Install whisper.cpp with Homebrew',
+      command: 'brew install whisper-cpp',
+    });
+  else
+    options.push({
+      id: 'cloud',
+      kind: 'link',
+      label: 'No Homebrew — a cloud engine needs no install at all',
+      url: 'https://elevenlabs.io/app/settings/api-keys',
+      note: 'Pick ElevenLabs Scribe or Groq above and paste a key. Audio is uploaded to that provider and billed to your account.',
+    });
+  options.push({
+    id: 'source',
+    kind: 'link',
+    label: 'Build from source',
+    url: 'https://github.com/ggml-org/whisper.cpp',
+    note: 'whisper.cpp ships prebuilt binaries for Linux and Windows, but not macOS — a Mac build needs cmake + Xcode command-line tools.',
+  });
+  return { installed: false, options };
+}
+
+// ─── Automatic engine choice ─────────────────────────────────────────────────
+// Task 2.6 / DDR-164 made the engine an EXPLICIT choice because a silent
+// fallback to a cloud engine has two consequences the user never asked for:
+// their audio leaves the machine, and their account is billed. That rule is
+// kept — what changes is that "auto" becomes a choice the user can MAKE, and
+// one that always SAYS what it currently resolves to (in this card and in the
+// transcriber's own output). Nothing switches behind your back; `auto` is a
+// selected mode, not a hidden default override.
+//
+// The bite worth knowing: one ElevenLabs key covers audio generation AND
+// Scribe, so a key added for music/TTS is enough to make `auto` route
+// transcription to the cloud. That's why the card states the resolution
+// out loud and pinning `whisper` stays one click away.
+
+export type TranscriptionEngine = 'auto' | 'whisper' | 'elevenlabs' | 'groq';
+
+export interface AutoEngineResolution {
+  /** What `auto` picks right now. */
+  engine: Exclude<TranscriptionEngine, 'auto'>;
+  /** Why — rendered verbatim so the choice is never a mystery. */
+  reason: string;
+  /** True when the resolved engine uploads audio and bills a provider. */
+  cloud: boolean;
+}
+
+/**
+ * Resolve `auto`: prefer the cloud engine whose key is present (ElevenLabs
+ * Scribe first — better accuracy than a local base model), else local
+ * whisper.cpp. `configured` is the set of providers holding a key, passed in so
+ * this stays a pure function (the keychain read is the caller's).
+ */
+export function resolveAutoEngine(
+  configured: Iterable<string>,
+  whisperInstalled: boolean
+): AutoEngineResolution {
+  const keys = new Set(configured);
+  if (keys.has('elevenlabs'))
+    return {
+      engine: 'elevenlabs',
+      reason: 'ElevenLabs key is set — Scribe is more accurate than a local base model.',
+      cloud: true,
+    };
+  if (keys.has('groq'))
+    return { engine: 'groq', reason: 'Groq key is set — fast cloud transcription.', cloud: true };
+  return {
+    engine: 'whisper',
+    reason: whisperInstalled
+      ? 'No cloud key set — using local whisper.cpp (free, offline, nothing leaves this machine).'
+      : 'No cloud key set — will use local whisper.cpp once its binary is installed.',
+    cloud: false,
+  };
+}

package/apps/studio/hmr-broadcast.ts

@@ -171,3 +171,70 @@ export function classifyChange(
   }
   return null;
 }
+
+// ---------------------------------------------------------------------------
+// Container write bridge — inspector-edits-live-render RCA.
+
+/**
+ * Delay before synthesising the `fs:any` a container's `fs.watch` failed to
+ * emit. The write is `await`ed inside the op before it returns, so a few hundred
+ * ms is ample; kept well under activity's 2.5 s `SUPPRESS_TTL_MS` so the
+ * user-write rim stays muted when the synthetic event lands.
+ */
+export const SYNTHETIC_FS_DELAY_MS = 250;
+
+/**
+ * In a CELL the recursive `fs.watch` (Linux inotify) does NOT fire for the
+ * atomic tmp+rename writes `canvas-edit.ts` makes into `designRoot` subdirs —
+ * verified live: after a `200` `edit-css` on a cell, a connected `canvas-hmr`
+ * socket received nothing. So `fs:any` never fires, the HMR broadcaster never
+ * runs, and a PEER's canvas iframe sits on the pre-edit module until a manual
+ * reload. (Annotations are spared: they cross via the collab room, not `fs:any`.)
+ *
+ * Every write path arms `activity:suppress(rel)` immediately before writing — a
+ * reliable, complete signal that a write to `rel` is imminent. Treat it as the
+ * `fs:any` the watcher owes us and synthesise one once the write has settled. A
+ * no-op or failed edit disarms via `activity:unsuppress`, which cancels the
+ * pending emit, so an equal-length or rejected edit never reloads peers.
+ *
+ * WORKSPACE-MODE ONLY (the caller gates it): locally `fs.watch` fires, and a
+ * second source would double-reload every canvas on every edit — the HMR
+ * broadcaster's 50 ms per-path debounce cannot coalesce two events ~250 ms apart.
+ */
+export function createContainerWriteBridge(ctx: Context): { stop(): void } {
+  const pending = new Map<string, ReturnType<typeof setTimeout>>();
+  const norm = (rel: string) => rel.replace(/\\/g, '/');
+
+  const offSuppress = ctx.bus.on('activity:suppress', (rel: string) => {
+    if (typeof rel !== 'string' || !rel) return;
+    const key = norm(rel);
+    const prev = pending.get(key);
+    if (prev) clearTimeout(prev);
+    pending.set(
+      key,
+      setTimeout(() => {
+        pending.delete(key);
+        ctx.bus.emit('fs:any', key);
+      }, SYNTHETIC_FS_DELAY_MS)
+    );
+  });
+
+  const cancel = (rel: string) => {
+    if (typeof rel !== 'string' || !rel) return;
+    const t = pending.get(norm(rel));
+    if (t) {
+      clearTimeout(t);
+      pending.delete(norm(rel));
+    }
+  };
+  const offUnsuppress = ctx.bus.on('activity:unsuppress', cancel);
+
+  return {
+    stop() {
+      offSuppress();
+      offUnsuppress();
+      for (const t of pending.values()) clearTimeout(t);
+      pending.clear();
+    },
+  };
+}