@1agh/maude 0.55.0 → 0.56.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/client/app.jsx

@@ -156,7 +156,7 @@ const LAYERS_MODE_STORE = 'mdcc-layers-mode';
 // resizable width + a tab strip over the panels assigned to the slot; renders
 // the active panel (passed as children). Collapses to 0 width when nothing is
 // visibly open (it may still host an always-mounted hidden ChatPanel).
-function DockSlot({ side, width, open, ids, activeId, onPick, children }) {
+function DockSlot({ side, width, open, ids, activeId, onPick, children, labels = null }) {
   return (
     <div
       className={'st-dockslot st-dockslot--' + side + (open ? '' : ' is-collapsed')}
@@ -173,7 +173,7 @@ function DockSlot({ side, width, open, ids, activeId, onPick, children }) {
               className={'st-docktab' + (activeId === id ? ' is-active' : '')}
               onClick={() => onPick(id)}
             >
-              {(DOCK_PANELS.find((p) => p.id === id) || {}).label || id}
+              {labels?.[id] || (DOCK_PANELS.find((p) => p.id === id) || {}).label || id}
             </button>
           ))}
         </div>
@@ -3733,7 +3733,14 @@ function Menubar({
     { id: 'tree', label: 'Project Tree', shortcut: 'T', checked: sidebarOpen, disabled: false },
     {
       id: 'changes',
-      label: changesCount > 0 ? `Changes · ${changesCount} unsaved` : 'Changes',
+      // In a cell this panel is History (the hub already committed the work),
+      // so the menu names what it opens rather than an unsaved count there is
+      // no way — and no reason — to act on.
+      label: cloud
+        ? 'History'
+        : changesCount > 0
+          ? `Changes · ${changesCount} unsaved`
+          : 'Changes',
       shortcut: '⌘ ⇧ G',
       checked: changesOpen,
       disabled: false,
@@ -14019,6 +14026,11 @@ function App() {
     changes: changesOpen,
     assistant: assistantOpen,
   };
+  // Per-shell overrides for the dock tab strip. In a cell the `changes` panel
+  // IS the history (the hub commits server-side), so its tab must say so —
+  // otherwise the one visible word still promises a working-tree surface that
+  // panel no longer has.
+  const dockLabels = cfg.cloud ? { changes: 'History' } : null;
   const leftIds = idsForSide('left');
   const rightIds = idsForSide('right');
   const leftActive = leftIds.find((id) => panelIsOpen[id]) || null;
@@ -14083,6 +14095,20 @@ function App() {
           status={gitStatus && remoteSync ? { ...gitStatus, ...remoteSync } : gitStatus}
           project={project}
           readOnly={!isNativeApp() || viewerMode}
+          // A cloud cell commits every edit server-side as it lands, so the
+          // working-tree half of this panel describes work that is already
+          // saved. `cfg.cloud` is present exactly when the hub runs the
+          // workspace agent that owns this project's history, which is the
+          // same condition.
+          //
+          // PRESENTATION, NOT A CONTROL — nothing may come to depend on this.
+          // `/_api/git/commit` and `/_api/git/discard` are classified `edit` in
+          // the cell's route manifest and stay reachable by any member with a
+          // session; withdrawing the buttons removes an offer that would
+          // mislead, it does not remove a capability. The real gates are
+          // server-side (`projectReadOnly`, the manifest's role matrix), and
+          // they are unchanged by this flag.
+          historyOnly={!!cfg.cloud}
           resizing={resizingFor('changes')}
           onClose={() => setChangesOpen(false)}
           onCommit={gitCommit}
@@ -14330,6 +14356,7 @@ function App() {
               ids={leftIds}
               activeId={leftActive}
               onPick={togglePanel}
+              labels={dockLabels}
             >
               {leftHostsAssistant && (
                 <ChatPanel
@@ -14402,6 +14429,7 @@ function App() {
               ids={rightIds}
               activeId={rightActive}
               onPick={togglePanel}
+              labels={dockLabels}
             >
               {rightHostsAssistant && (
                 <ChatPanel

package/apps/studio/client/panels/CloudBar.jsx

@@ -247,6 +247,41 @@ export function localIdentityHint({
   return related ? 'similar' : 'mismatch';
 }
 
+/**
+ * What to say after a successful Connect.
+ *
+ * The old copy said "Linked to <X> — restart the studio server to start
+ * syncing", which was three problems in one line: it named a thing the person
+ * cannot see (there is no visible server in the desktop app), gave them a task
+ * instead of a result, and never explained what connecting had achieved. The
+ * server now cycles the sync runtime itself, so this reports an OUTCOME —
+ * and on the paths where syncing genuinely didn't start, it says which one and
+ * what to do, rather than prescribing a restart for every cause.
+ *
+ * Returns `{ text, title }` — `text` is the rail's one line, `title` the full
+ * sentence on hover (the rail truncates).
+ */
+export function connectOutcomeNote(project, sync) {
+  const name = project || 'the workspace';
+  if (sync?.syncing) {
+    const n = sync.canvases ?? 0;
+    return {
+      text: `Syncing with ${name} — ${n} canvas${n === 1 ? '' : 'es'}.`,
+      title: `This project’s canvases now sync with the ${name} workspace. Live status is in the “hub sync” slot in the status bar.`,
+    };
+  }
+  if (sync?.reason === 'nothing-syncable') {
+    return {
+      text: `Connected to ${name} — nothing to sync yet.`,
+      title: sync.detail || 'No canvases in this project are syncable yet.',
+    };
+  }
+  return {
+    text: `Connected to ${name} — ${sync?.detail ?? 'restart Maude to start syncing.'}`,
+    title: sync?.detail || 'Restart Maude to start syncing.',
+  };
+}
+
 function Spark({ size = 15 }) {
   return (
     <svg width={size} height={size} viewBox="0 0 32 32" fill="currentColor" aria-hidden="true">
@@ -308,7 +343,7 @@ export default function CloudBar() {
   const [device, setDevice] = useState(null); // { userCode, verificationUrl, deviceCode }
   const [projects, setProjects] = useState(null);
   const [busy, setBusy] = useState('');
-  const [note, setNote] = useState('');
+  const [note, setNote] = useState(null); // { text, title } — connectOutcomeNote
   const [error, setError] = useState('');
   const [copied, setCopied] = useState(false);
   const [copiedLink, setCopiedLink] = useState(false);
@@ -391,7 +426,7 @@ export default function CloudBar() {
     setBusy('');
     setPending(null);
     if (r.ok && r.json?.ok) {
-      setNote(`Linked to ${r.json.project ?? pending.project} — restart the studio server to start syncing.`);
+      setNote(connectOutcomeNote(r.json.project ?? pending.project, r.json.sync));
     } else {
       setError(r.json?.error || 'The workspace could not be connected.');
     }
@@ -468,7 +503,7 @@ export default function CloudBar() {
 
   async function connect(projectId) {
     setBusy(projectId);
-    setNote('');
+    setNote(null);
     setError('');
     const r = await api('/_api/cloud/attach', {
       method: 'POST',
@@ -477,7 +512,7 @@ export default function CloudBar() {
     });
     setBusy('');
     if (r.ok && r.json?.ok) {
-      setNote(`Linked to ${projectId} — restart the studio server to start syncing.`);
+      setNote(connectOutcomeNote(r.json.project ?? projectId, r.json.sync));
     } else {
       setError(r.json?.error || 'The workspace could not be connected.');
     }
@@ -670,7 +705,11 @@ export default function CloudBar() {
             <span className="gi-rail-login">{email ?? 'Maude Cloud'}</span>
             <span className="gi-rail-caret"><Icon name="chevron-up" size={13} /></span>
           </button>
-          {note && <span className="gi-rail-hint" title={note}>{note}</span>}
+          {note && (
+            <span className="gi-rail-hint" title={note.title} data-testid="cloud-connect-note">
+              {note.text}
+            </span>
+          )}
           {error && <span className="gi-rail-err" title={error}>{error}</span>}
           {menuOpen && (
             <div className="gi-menu" role="menu" aria-label="Maude Cloud">