@1agh/maude 0.55.0 → 0.56.0

package/apps/studio/sync/supervisor.ts

@@ -0,0 +1,178 @@
+// Sync supervisor — one owner of the live sync runtime, so linking a project
+// can START SYNCING instead of asking a person to restart the app.
+//
+// Why this exists: `createSyncRuntime` captures `cfg.linkedHub` once, and
+// `reloadConfig` deliberately refuses to hot-swap it (a config.json is
+// committed and travels with the repo — a poisoned one must never re-point the
+// sync socket, DDR-149). That rule is about the FILE WATCHER, and it was being
+// paid for by the person: after pressing Connect in the cloud panel the whole
+// product did nothing visible and the UI said "restart the studio server to
+// start syncing" — a sentence with no button behind it, and no meaning at all
+// inside the desktop app, where there is no server the person can see.
+//
+// The supervisor separates the two paths that were conflated:
+//
+//   • a linkedHub arriving from DISK        → still boot-pinned, still refused;
+//   • a linkedHub the person JUST AUTHORIZED in trusted app chrome, whose hub
+//     credential this process itself stored one line earlier → adopted in
+//     memory and applied by a real stop() + start() cycle.
+//
+// The second path never reads the value back off disk: `restart()` takes the
+// LinkedHub object the attach lane just wrote, so nothing that happens to
+// `.design/config.json` in between can steer the socket.
+
+import { adoptLinkedHub, type Context, type LinkedHub } from '../context.ts';
+import { resolveCellPairing } from './cell-pairing.ts';
+import { getHubToken } from './hubs-config.ts';
+import {
+  type CreateSyncRuntimeOptions,
+  checkUrlScheme,
+  createSyncRuntime,
+  type SyncRuntime,
+} from './index.ts';
+
+/**
+ * What happened when the runtime was (re)started — the honest answer the cloud
+ * panel repeats back to the person. `syncing:false` is never silent: `reason`
+ * is what to say, and the caller renders it verbatim rather than guessing.
+ */
+export interface SyncStartOutcome {
+  syncing: boolean;
+  /** Canvases the runtime actually took ownership of. */
+  canvases: number;
+  /** Machine-readable cause when `syncing` is false. */
+  reason?: 'unlinked' | 'no-credential' | 'insecure-url' | 'refused' | 'nothing-syncable' | 'error';
+  /** One sentence a person can act on. Present whenever `syncing` is false. */
+  detail?: string;
+}
+
+export interface SyncSupervisor {
+  /** Boot the runtime from the config as loaded. Safe when unlinked. */
+  start(): Promise<SyncStartOutcome>;
+  /**
+   * Adopt a just-authorized link and cycle the runtime. `linkedHub` is passed
+   * BY VALUE from the attach lane on purpose — never re-read from disk.
+   */
+  restart(linkedHub?: LinkedHub): Promise<SyncStartOutcome>;
+  stop(): Promise<void>;
+  /** The live runtime, or null in solo mode. Test/inspection surface. */
+  current(): SyncRuntime | null;
+}
+
+/**
+ * Why did `createSyncRuntime` decline? It logs its refusals and returns null,
+ * which is right for a boot path and useless for a dialog. Re-derive the cause
+ * from the same inputs so the panel can say something true. Kept in this order
+ * deliberately — it mirrors the guard order in createSyncRuntime.
+ */
+function diagnose(ctx: Context): { reason: SyncStartOutcome['reason']; detail: string } {
+  // Cell pairing supplies its own hub URL + credential from the environment, so
+  // "no linkedHub on disk" is not the diagnosis there — reporting "not linked to
+  // a workspace" for a cell that IS paired would send an operator looking for a
+  // config field that has nothing to do with it. Both pairing outcomes (refused
+  // to resolve, or resolved but the runtime still declined) return here — a
+  // successfully-resolved pairing always carries a non-empty `url`
+  // (`resolveCellPairing` refuses an empty one), so there is no "unlinked"
+  // state to fall through to on this path, unlike the plain linkedHub case below.
+  const { pairing, detail: pairingRefusal } = resolveCellPairing();
+  if (pairingRefusal) {
+    return { reason: 'refused', detail: pairingRefusal };
+  }
+  if (pairing) {
+    return {
+      reason: 'refused',
+      detail: 'Cell pairing is on but syncing did not start — see the server log for why.',
+    };
+  }
+  const linked = ctx.cfg.linkedHub;
+  if (!linked) {
+    return { reason: 'unlinked', detail: 'This project is not linked to a workspace.' };
+  }
+  const scheme = checkUrlScheme(linked.url);
+  if (scheme) {
+    return { reason: 'insecure-url', detail: scheme };
+  }
+  if (!getHubToken(linked.url)) {
+    return {
+      reason: 'no-credential',
+      detail: 'No sign-in for this workspace is stored on this machine yet.',
+    };
+  }
+  return {
+    reason: 'refused',
+    detail: 'Syncing is switched off in this environment — see the server log for why.',
+  };
+}
+
+export function createSyncSupervisor(
+  ctx: Context,
+  opts: CreateSyncRuntimeOptions = {},
+  factory: (c: Context, o: CreateSyncRuntimeOptions) => SyncRuntime | null = createSyncRuntime
+): SyncSupervisor {
+  let runtime: SyncRuntime | null = null;
+  // Two Connects pressed in quick succession must not interleave a stop() with
+  // another cycle's start() — the second would attach providers the first is
+  // still tearing down. One chain, in order.
+  let chain: Promise<unknown> = Promise.resolve();
+
+  async function boot(): Promise<SyncStartOutcome> {
+    runtime = factory(ctx, opts);
+    if (!runtime) return { syncing: false, canvases: 0, ...diagnose(ctx) };
+    try {
+      await runtime.start();
+    } catch (err) {
+      // Same posture as the boot path: a failed sync start never takes the
+      // server (or the attach response) down with it — solo mode continues.
+      console.error('[sync] start failed — continuing in solo mode:', err);
+      return {
+        syncing: false,
+        canvases: 0,
+        reason: 'error',
+        detail: `Syncing could not start: ${(err as Error).message}`,
+      };
+    }
+    const canvases = runtime.size();
+    if (canvases === 0) {
+      // Linked and authenticated, but nothing on disk qualifies. The runtime
+      // already wrote the full reason into `_sync.json` (9.1-D); reuse it
+      // rather than inventing a second explanation that can drift from it.
+      const status = runtime.status() as { reason?: string } | null;
+      return {
+        syncing: false,
+        canvases: 0,
+        reason: 'nothing-syncable',
+        detail: status?.reason ?? 'No canvases in this project are syncable yet.',
+      };
+    }
+    return { syncing: true, canvases };
+  }
+
+  function serialize<T>(work: () => Promise<T>): Promise<T> {
+    const next = chain.then(work, work);
+    // Keep the chain alive even when a link fails — the NEXT attach must still
+    // be able to run. (A rejected chain would poison every later restart.)
+    chain = next.catch(() => {});
+    return next;
+  }
+
+  return {
+    start: () => serialize(boot),
+    restart: (linkedHub) =>
+      serialize(async () => {
+        try {
+          await runtime?.stop();
+        } catch (err) {
+          console.error('[sync] stop before restart failed:', err);
+        }
+        runtime = null;
+        if (linkedHub) adoptLinkedHub(ctx, linkedHub);
+        return boot();
+      }),
+    stop: () =>
+      serialize(async () => {
+        await runtime?.stop();
+        runtime = null;
+      }),
+    current: () => runtime,
+  };
+}

package/apps/studio/test/cloud-endpoints.test.ts

@@ -10,6 +10,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import {
+  connectOutcomeNote,
   isDisplayableUrl,
   localIdentityHint,
   parseDeepLink,
@@ -322,6 +323,41 @@ describe('localIdentityHint — only an exact, corroborated agreement is silent'
   });
 });
 
+describe('connectOutcomeNote — what the rail says after Connect', () => {
+  test('syncing: a result, and where to watch it', () => {
+    const n = connectOutcomeNote('alligators', { syncing: true, canvases: 12 });
+    expect(n.text).toBe('Syncing with alligators — 12 canvases.');
+    expect(n.title).toContain('hub sync');
+    expect(connectOutcomeNote('alligators', { syncing: true, canvases: 1 }).text).toContain(
+      '1 canvas.'
+    );
+  });
+
+  test('linked but nothing syncable says so — and never claims a restart would help', () => {
+    const n = connectOutcomeNote('alligators', {
+      syncing: false,
+      canvases: 0,
+      reason: 'nothing-syncable',
+      detail: 'no canvases found under .design.',
+    });
+    expect(n.text).toBe('Connected to alligators — nothing to sync yet.');
+    expect(n.title).toContain('no canvases found');
+    expect(n.text).not.toMatch(/restart/i);
+  });
+
+  test('any other refusal repeats the server’s own reason', () => {
+    const n = connectOutcomeNote('alligators', {
+      syncing: false,
+      canvases: 0,
+      reason: 'no-credential',
+      detail: 'No sign-in for this workspace is stored on this machine yet.',
+    });
+    expect(n.text).toContain('No sign-in for this workspace');
+    // Never the old sentence: there is no studio server a person can see.
+    expect(n.text).not.toContain('studio server');
+  });
+});
+
 describe('attachCode — the maude:// lane end to end (stubbed)', () => {
   test('a valid code links: hub credential stored, linkedHub written token-free', async () => {
     const { createCloudEndpoints } = await import('../cloud/endpoints.ts');
@@ -375,6 +411,65 @@ describe('attachCode — the maude:// lane end to end (stubbed)', () => {
     expect(r.status).toBe(200);
   });
 
+  test('linking STARTS syncing — the outcome is reported, not homework', async () => {
+    // The bug this closes: the panel used to answer a successful Connect with
+    // "restart the studio server to start syncing" — a task, naming a thing
+    // the desktop user cannot see. The attach lane now cycles the runtime and
+    // reports what happened.
+    const { createCloudEndpoints } = await import('../cloud/endpoints.ts');
+    const designRoot = join(scratch, '.design-sync');
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(designRoot, { recursive: true });
+    writeFileSync(join(designRoot, 'config.json'), '{}\n');
+
+    const handed: unknown[] = [];
+    const apiEndpoints = createCloudEndpoints({
+      paths: { repoRoot: scratch, designRoot },
+      syncControl: {
+        restart: async (linkedHub) => {
+          handed.push(linkedHub);
+          return { syncing: true, canvases: 4 };
+        },
+      },
+    });
+    const r = await apiEndpoints.attachCode(`mhc_${'a'.repeat(64)}`);
+    expect(r.status).toBe(200);
+    expect((r.json as any).sync).toEqual({ syncing: true, canvases: 4 });
+    expect((r.json as any).note).toBe('Linked — syncing 4 canvases.');
+
+    // The supervisor is handed the value BY VALUE — the same object written to
+    // config.json — so nothing that touches that committed file in between can
+    // steer the socket.
+    const cfg = JSON.parse(readFileSync(join(designRoot, 'config.json'), 'utf8'));
+    expect(handed).toEqual([cfg.linkedHub]);
+  });
+
+  test('a TSX opt-out survives a re-link — only the restrictive direction carries', async () => {
+    // `syncTsx: false` means "do not upload canvas bodies to this hub"
+    // (DDR-072/DDR-079). Re-linking used to overwrite linkedHub wholesale,
+    // which silently re-enabled it — harmless while nothing synced until a
+    // restart, a real disclosure now that Connect starts syncing immediately.
+    const { createCloudEndpoints } = await import('../cloud/endpoints.ts');
+    const designRoot = join(scratch, '.design-opt-out');
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(designRoot, { recursive: true });
+    writeFileSync(
+      join(designRoot, 'config.json'),
+      JSON.stringify({ linkedHub: { url: 'https://old.example', linkedAt: 1, syncTsx: false } })
+    );
+
+    const apiEndpoints = createCloudEndpoints({ paths: { repoRoot: scratch, designRoot } });
+    const r = await apiEndpoints.attachCode(`mhc_${'a'.repeat(64)}`);
+    expect(r.status).toBe(200);
+    const cfg = JSON.parse(readFileSync(join(designRoot, 'config.json'), 'utf8'));
+    expect(cfg.linkedHub.syncTsx).toBe(false);
+    expect(cfg.linkedHub.url).toContain('127.0.0.1');
+    // No supervisor wired (a plain embedder): still linked, and the note says
+    // what is left to do instead of claiming success.
+    expect((r.json as any).sync.syncing).toBe(false);
+    expect((r.json as any).note).toMatch(/Restart Maude/);
+  });
+
   test('a malformed or dead code never reaches the network', async () => {
     const { createCloudEndpoints } = await import('../cloud/endpoints.ts');
     const apiEndpoints = createCloudEndpoints({

package/apps/studio/test/csrf-write-guard.test.ts

@@ -36,14 +36,31 @@ describe('CSRF Origin guard — sameOriginWrite (DDR-105)', () => {
     expect(sameOriginWrite(post('http://localhost:4399.evil.example'))).toBe(false);
     // Right host, wrong port is still cross-origin.
     expect(sameOriginWrite(post('http://localhost:4400'))).toBe(false);
-    // Right host:port, wrong scheme is still cross-origin.
-    expect(sameOriginWrite(post('https://localhost:4399'))).toBe(false);
   });
 
   test('allows the legit same-origin shell Origin', () => {
     expect(sameOriginWrite(post(SELF))).toBe(true);
   });
 
+  test('a matching host on a different SCHEME is same-origin — TLS terminates at the cell proxy', () => {
+    // The second half of the inspector-edits RCA. In a cell the browser sends
+    // `https://<host>` but the studio serves plaintext and computes `req.url` as
+    // `http://<host>`, so a scheme-strict compare 403'd every legitimate shell
+    // write. Host+port still pins it; a cross-site page has a different host.
+    const cell = 'https://alligators.cloud.maude.sh';
+    const cellReq = (origin?: string) =>
+      new Request('http://alligators.cloud.maude.sh/_api/edit-css', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...(origin ? { origin } : {}) },
+        body: '{}',
+      });
+    expect(sameOriginWrite(cellReq(cell))).toBe(true); // https Origin ↔ http req.url, same host
+    // But a genuinely different host is still rejected, scheme notwithstanding.
+    expect(sameOriginWrite(cellReq('https://evil.cloud.maude.sh'))).toBe(false);
+    // And the port still discriminates when present.
+    expect(sameOriginWrite(post('https://localhost:4400'))).toBe(false);
+  });
+
   test('allows a request with no Origin header (curl / programmatic / bun:test)', () => {
     expect(sameOriginWrite(post())).toBe(true);
   });

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

@@ -0,0 +1,245 @@
+// gemma-models.test.ts — the pure helpers behind the Gemma scout's two runtimes
+// (feature-scene-aware-keyframes / DDR-183). The download spawn + the live probes
+// are soft-dep gates covered by manual runs; this covers what a security review
+// found load-bearing: the copy/paste install command the user pastes UNREAD, and
+// the loopback pin that keeps the scout egress-free.
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import {
+  getOllamaModel,
+  isLoopbackHostname,
+  listScoutModels,
+  mlxInstallCommand,
+  mlxSetup,
+  mlxVenvDir,
+  ollamaHost,
+  ollamaSetupOptions,
+  pickOllamaGemmaTag,
+} from '../generation/gemma-models.ts';
+
+const ENV_KEYS = ['XDG_CACHE_HOME', 'OLLAMA_HOST', 'MAUDE_OLLAMA_MODEL'] as const;
+const saved = new Map<string, string | undefined>();
+function setEnv(key: (typeof ENV_KEYS)[number], value: string | undefined) {
+  if (!saved.has(key)) saved.set(key, process.env[key]);
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+}
+afterEach(() => {
+  for (const [k, v] of saved) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  saved.clear();
+});
+
+describe('mlxVenvDir / mlxInstallCommand', () => {
+  test('honors XDG_CACHE_HOME, else ~/.maude', () => {
+    setEnv('XDG_CACHE_HOME', '/tmp/xdg');
+    expect(mlxVenvDir()).toBe('/tmp/xdg/maude/mlx-venv');
+    setEnv('XDG_CACHE_HOME', undefined);
+    expect(mlxVenvDir()).toMatch(/\/\.maude\/mlx-venv$/);
+  });
+
+  test('the shown command targets the SAME path the probe checks', () => {
+    setEnv('XDG_CACHE_HOME', '/tmp/xdg');
+    const cmd = mlxInstallCommand();
+    expect(cmd).toContain(mlxVenvDir());
+    expect(cmd).toContain('python3 -m venv');
+    expect(cmd).toContain('install -U mlx-vlm');
+  });
+
+  test('single-quotes the path so shell metacharacters cannot execute', () => {
+    setEnv('XDG_CACHE_HOME', '/tmp/$(touch /tmp/pwned)/`id`/"x"');
+    const cmd = mlxInstallCommand() ?? '';
+    // The dangerous characters are present only INSIDE single quotes — the shell
+    // expands nothing there.
+    expect(cmd).toContain('\'/tmp/$(touch /tmp/pwned)/`id`/"x"/maude/mlx-venv\'');
+    expect(cmd).not.toMatch(/"\/tmp\/\$\(/); // never inside double quotes
+  });
+
+  test('escapes an embedded single quote by closing, escaping, reopening', () => {
+    setEnv('XDG_CACHE_HOME', "/tmp/it's");
+    const cmd = mlxInstallCommand() ?? '';
+    expect(cmd).toContain(`'/tmp/it'\\''s/maude/mlx-venv'`);
+  });
+
+  test('refuses to build a command when the path holds a control char', () => {
+    setEnv('XDG_CACHE_HOME', '/tmp/a\nrm -rf ~');
+    expect(mlxInstallCommand()).toBe(null);
+  });
+});
+
+describe('ollamaHost — loopback pin (DDR-183 egress-free)', () => {
+  test('defaults to loopback and accepts loopback forms', () => {
+    setEnv('OLLAMA_HOST', undefined);
+    expect(ollamaHost()).toBe('http://127.0.0.1:11434');
+    setEnv('OLLAMA_HOST', '127.0.0.1:11434');
+    expect(ollamaHost()).toBe('http://127.0.0.1:11434');
+    setEnv('OLLAMA_HOST', 'http://localhost:11434/');
+    expect(ollamaHost()).toBe('http://localhost:11434');
+  });
+
+  test('refuses every non-loopback host rather than uploading frames to it', () => {
+    for (const host of [
+      '0.0.0.0:11434',
+      '192.168.1.20:11434',
+      'http://169.254.169.254',
+      'http://ollama.example.com',
+      'not a url',
+    ]) {
+      setEnv('OLLAMA_HOST', host);
+      expect(ollamaHost()).toBe(null);
+    }
+  });
+
+  test('isLoopbackHostname accepts only literal loopback', () => {
+    expect(isLoopbackHostname('127.0.0.1')).toBe(true);
+    expect(isLoopbackHostname('127.1.2.3')).toBe(true);
+    expect(isLoopbackHostname('::1')).toBe(true);
+    expect(isLoopbackHostname('localhost')).toBe(true);
+    expect(isLoopbackHostname('127.0.0.1.evil.com')).toBe(false);
+    expect(isLoopbackHostname('10.0.0.1')).toBe(false);
+  });
+});
+
+// The card must never show an instruction this machine can't follow — the whole
+// point of probing brew/python3/curl rather than hardcoding an install line.
+describe('ollamaSetupOptions', () => {
+  const notInstalled = { available: false, model: null, tags: [], installed: false };
+
+  test('installed but not running → start it, never "install it" again', () => {
+    const opts = ollamaSetupOptions({ ...notInstalled, installed: true });
+    expect(opts.map((o) => o.id)).toEqual(['start']);
+    expect(opts[0].command).toBe('ollama serve');
+  });
+
+  test('running → the only thing missing is a model', () => {
+    const opts = ollamaSetupOptions({ available: true, model: null, tags: [], installed: true });
+    expect(opts.map((o) => o.id)).toEqual(['pull']);
+    expect(opts[0].command).toContain('ollama pull');
+  });
+
+  test('not installed → always offers a route, and a download link as the floor', () => {
+    const opts = ollamaSetupOptions(notInstalled);
+    expect(opts.length).toBeGreaterThan(0);
+    const download = opts.find((o) => o.id === 'download');
+    expect(download?.kind).toBe('link');
+    expect(download?.url).toBe('https://ollama.com/download');
+    // Whatever routes are offered, each is actionable as-is.
+    for (const o of opts) expect(o.kind === 'command' ? o.command : o.url).toBeTruthy();
+  });
+
+  test('on macOS/Linux the brew-free script route comes before brew', () => {
+    if (process.platform !== 'darwin' && process.platform !== 'linux') return;
+    const ids = ollamaSetupOptions(notInstalled).map((o) => o.id);
+    if (ids.includes('script') && ids.includes('brew'))
+      expect(ids.indexOf('script')).toBeLessThan(ids.indexOf('brew'));
+  });
+});
+
+// The model list has to be actionable on whatever runtime the machine has —
+// a dead "Needs mlx-vlm" on an Ollama box was the bug this replaced.
+describe('listScoutModels', () => {
+  const offline = { available: false, model: null, tags: [], installed: false };
+  const running = {
+    available: true,
+    model: 'gemma3:4b',
+    tags: ['gemma3:4b', 'llama3:8b'],
+    installed: true,
+  };
+
+  test('every model declares the runtime that can download it', () => {
+    for (const m of listScoutModels(offline)) expect(['mlx', 'ollama']).toContain(m.runtime);
+  });
+
+  test('Ollama models sort first when Ollama is the runtime that can act', () => {
+    expect(listScoutModels(running)[0].runtime).toBe('ollama');
+    expect(listScoutModels(offline)[0].runtime).toBe('mlx');
+  });
+
+  test('an Ollama model counts as downloaded only on an EXACT tag match', () => {
+    const rows = listScoutModels(running).filter((m) => m.runtime === 'ollama');
+    expect(rows.find((m) => m.id === 'ollama:gemma3:4b')?.downloaded).toBe(true);
+    expect(rows.find((m) => m.id === 'ollama:gemma3:12b')?.downloaded).toBe(false);
+    // A near-miss tag is a different pull, not the same model.
+    const nearMiss = listScoutModels({ ...running, tags: ['gemma3:4b-it-q4_K_M'] });
+    expect(nearMiss.find((m) => m.id === 'ollama:gemma3:4b')?.downloaded).toBe(false);
+  });
+
+  test('getOllamaModel only resolves allowlisted ids (the pull target is frozen)', () => {
+    expect(getOllamaModel('ollama:gemma3:4b')?.tag).toBe('gemma3:4b');
+    expect(getOllamaModel('gemma-4-e4b-it-4bit')).toBe(null);
+    expect(getOllamaModel('ollama:../../evil')).toBe(null);
+    expect(getOllamaModel('ollama:llama3:8b')).toBe(null);
+  });
+});
+
+describe('mlxSetup', () => {
+  test('either a usable command or a stated reason — never a silent dead end', () => {
+    const s = mlxSetup();
+    if (s.supported) {
+      expect(s.command).toContain('mlx-vlm');
+      expect(s.reason).toBeUndefined();
+    } else {
+      expect(s.reason).toBeTruthy();
+      expect(s.command).toBeUndefined();
+    }
+  });
+});
+
+// The CLI (bin/_smart-frames.mjs, pure JS — no .ts imports) deliberately carries
+// its OWN copy of these helpers. That duplication is an accepted constraint, so
+// the drift it invites needs a guard: a review already caught the two copies
+// disagreeing about the bare `gemma3` tag.
+describe('CLI ↔ server helper parity', () => {
+  test('pickOllamaGemmaTag agrees on every tag shape', async () => {
+    const cli = await import('../bin/_smart-frames.mjs');
+    setEnv('MAUDE_OLLAMA_MODEL', undefined);
+    for (const tags of [
+      ['gemma3:4b'],
+      ['gemma3'],
+      ['gemma3:1b'],
+      ['gemma3n:e4b'],
+      ['llama3:8b', 'gemma3:12b'],
+      [],
+    ]) {
+      expect(cli.pickOllamaGemmaTag(tags, {})).toBe(pickOllamaGemmaTag(tags));
+    }
+  });
+
+  test('ollamaHost agrees on loopback acceptance and refusal', async () => {
+    const cli = await import('../bin/_smart-frames.mjs');
+    for (const host of [
+      '127.0.0.1:11434',
+      'http://localhost:11434/',
+      '[::1]:11434',
+      '0.0.0.0:11434',
+      '192.168.1.20:11434',
+      'http://ollama.example.com',
+    ]) {
+      setEnv('OLLAMA_HOST', host);
+      expect(cli.ollamaHost({ OLLAMA_HOST: host })).toBe(ollamaHost());
+    }
+  });
+
+  test('the venv path the CLI probes is the one the server installs into', async () => {
+    const cli = await import('../bin/_smart-frames.mjs');
+    setEnv('XDG_CACHE_HOME', '/tmp/xdg');
+    expect(cli.mlxVenvPython({ XDG_CACHE_HOME: '/tmp/xdg' })).toBe(`${mlxVenvDir()}/bin/python3`);
+  });
+});
+
+describe('pickOllamaGemmaTag', () => {
+  test('picks a vision-capable gemma3 tag, skips text-only ones', () => {
+    setEnv('MAUDE_OLLAMA_MODEL', undefined);
+    expect(pickOllamaGemmaTag(['llama3:8b', 'gemma3:4b'])).toBe('gemma3:4b');
+    expect(pickOllamaGemmaTag(['gemma3'])).toBe('gemma3');
+    expect(pickOllamaGemmaTag(['gemma3:1b'])).toBe(null);
+    expect(pickOllamaGemmaTag(['gemma3n:e4b'])).toBe(null);
+  });
+
+  test('$MAUDE_OLLAMA_MODEL wins verbatim', () => {
+    setEnv('MAUDE_OLLAMA_MODEL', 'gemma3:27b');
+    expect(pickOllamaGemmaTag(['gemma3:4b'])).toBe('gemma3:27b');
+  });
+});

package/apps/studio/test/hmr-broadcast.test.ts

@@ -3,7 +3,13 @@
 import { describe, expect, test } from 'bun:test';
 
 import { type Context, createBus } from '../context.ts';
-import { createHmrBroadcaster, HMR_DEBOUNCE_MS, type HmrMessage } from '../hmr-broadcast.ts';
+import {
+  createContainerWriteBridge,
+  createHmrBroadcaster,
+  HMR_DEBOUNCE_MS,
+  type HmrMessage,
+  SYNTHETIC_FS_DELAY_MS,
+} from '../hmr-broadcast.ts';
 
 function mkCtx(): Context {
   const bus = createBus();
@@ -150,3 +156,53 @@ describe('hmr-broadcast / stop', () => {
     expect(got).toHaveLength(0);
   });
 });
+
+describe('container write bridge — synthesises fs:any the container fs.watch misses', () => {
+  const collect = (ctx: Context) => {
+    const got: string[] = [];
+    ctx.bus.on('fs:any', (rel: string) => got.push(rel));
+    return got;
+  };
+
+  test('activity:suppress → a synthetic fs:any lands after the delay', async () => {
+    const ctx = mkCtx();
+    const got = collect(ctx);
+    const bridge = createContainerWriteBridge(ctx);
+    ctx.bus.emit('activity:suppress', 'ui/Home.tsx');
+    expect(got).toHaveLength(0); // not immediate — the write must settle first
+    await new Promise((r) => setTimeout(r, SYNTHETIC_FS_DELAY_MS + 30));
+    expect(got).toEqual(['ui/Home.tsx']);
+    bridge.stop();
+  });
+
+  test('a no-op / failed edit disarms via activity:unsuppress — no reload for peers', async () => {
+    const ctx = mkCtx();
+    const got = collect(ctx);
+    const bridge = createContainerWriteBridge(ctx);
+    ctx.bus.emit('activity:suppress', 'ui/Home.tsx');
+    ctx.bus.emit('activity:unsuppress', 'ui/Home.tsx'); // delta 0 / threw
+    await new Promise((r) => setTimeout(r, SYNTHETIC_FS_DELAY_MS + 30));
+    expect(got).toHaveLength(0);
+    bridge.stop();
+  });
+
+  test('backslash paths are normalised so they match the watcher/classifier shape', async () => {
+    const ctx = mkCtx();
+    const got = collect(ctx);
+    const bridge = createContainerWriteBridge(ctx);
+    ctx.bus.emit('activity:suppress', 'ui\\Home.tsx');
+    await new Promise((r) => setTimeout(r, SYNTHETIC_FS_DELAY_MS + 30));
+    expect(got).toEqual(['ui/Home.tsx']);
+    bridge.stop();
+  });
+
+  test('stop() cancels a pending emit', async () => {
+    const ctx = mkCtx();
+    const got = collect(ctx);
+    const bridge = createContainerWriteBridge(ctx);
+    ctx.bus.emit('activity:suppress', 'ui/Home.tsx');
+    bridge.stop();
+    await new Promise((r) => setTimeout(r, SYNTHETIC_FS_DELAY_MS + 30));
+    expect(got).toHaveLength(0);
+  });
+});