@volter/world 2.0.0

package/src/journeys/tutorial-runner.test.ts

@@ -0,0 +1,180 @@
+import { expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { downEverything, failures, parseTutorial, removeTutorialApp, runTutorial, tutorialApp } from './tutorial.ts';
+
+async function run(markdown: string, timeoutMs = 6000) {
+  const dir = mkdtempSync(join(tmpdir(), 'tutorial-observation-'));
+  try {
+    return await runTutorial(parseTutorial(markdown, 'observation.md'),
+      { dir, parent: dir, env: { ...process.env } as Record<string, string> }, { stepTimeoutMs: timeoutMs });
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+test('preserves output guaranteed to precede the background launch marker', async () => {
+  // The first printf runs synchronously before bash backgrounds sleep; its output must
+  // precede the runner's DONE marker regardless of process scheduling.
+  const result = await run("```bash\nprintf 'early readiness\\n'; sleep 0.1 &\ncd .\n```\n```text\nearly readiness\n```\n");
+  expect(failures(result)).toEqual([]);
+  expect(result.at(-1)!.output).toContain('early readiness');
+});
+
+test('waits for delayed readiness at the end of a fence, including after a foreground cd', async () => {
+  const result = await run("```bash\n(sleep 3; printf 'host ready\\nconsole ready\\n') &\ncd .\n```\n```text\nhost ready\nconsole ready\n```\n");
+  expect(failures(result)).toEqual([]);
+}, 15_000);
+
+test('missing background output remains a bounded failure with the observed diagnostics', async () => {
+  const result = await run("```bash\nprintf 'wrong output\\n' &\ncd .\n```\n```text\nrequired readiness\n```\n", 300);
+  expect(failures(result).join('\n')).toContain('required readiness');
+  expect(failures(result).join('\n')).toContain('wrong output');
+});
+
+test('foreground failures still fail and documented refusals still match their expected text', async () => {
+  const result = await run("```bash\nfalse\n```\n```bash\nprintf 'refused\\n'; false\n```\n```text\nrefused\n```\n");
+  expect(failures(result)).toHaveLength(1);
+  expect(failures(result)[0]).toContain('exited 1');
+});
+
+for (const delayedStep of [false, true]) test(`joins asynchronous job shutdown before returning (delayed step marker: ${delayedStep})`, async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tutorial-join-'));
+  const finished = join(dir, 'finished');
+  const pidFile = join(dir, 'job.pid');
+  const server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: () => new Response('shutdown permitted') });
+  writeFileSync(join(dir, 'job.mjs'), `
+import fs from 'node:fs';
+let stopping=false;
+process.on('SIGTERM',async()=>{
+  if(stopping)return; stopping=true;
+  await fetch('http://127.0.0.1:${server.port}');
+  fs.writeFileSync(${JSON.stringify(finished)},'joined');process.exit(0);
+});
+fs.writeFileSync(${JSON.stringify(pidFile)},String(process.pid));
+console.log('job ready');setInterval(()=>{},1000);
+`);
+  const markdown = '```bash\nbun job.mjs &\n```\n```text\njob ready\n```\n'
+    + (delayedStep ? '```bash\nsleep 0.3\n```\n' : '');
+  try {
+    const run = runTutorial(parseTutorial(markdown, 'join.md'), { dir, parent: dir, env: { ...process.env } as Record<string, string> }, { stepTimeoutMs: delayedStep ? 100 : 6000 });
+    if (delayedStep) await expect(run).rejects.toThrow('step timed out');
+    else expect(failures(await run)).toEqual([]);
+    expect(readFileSync(finished, 'utf8')).toBe('joined');
+  } finally {
+    // The fixture knows only this exact child; failed assertions must not leave it running.
+    if (existsSync(pidFile)) {
+      const pid = Number(readFileSync(pidFile, 'utf8'));
+      try { process.kill(pid, 'SIGTERM'); } catch { /* already reaped */ }
+      const alive = () => { try { process.kill(pid, 0); return true; } catch { return false; } };
+      const deadline = Date.now() + 5000;
+      while (alive() && Date.now() < deadline) await Bun.sleep(20);
+      expect(alive()).toBe(false);
+    }
+    server.stop(true);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}, 20_000);
+
+test('a background shutdown failure fails tutorial cleanup and retains its directory', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tutorial-stop-fail-'));
+  writeFileSync(join(dir, 'job.mjs'), "process.on('SIGTERM',()=>process.exit(7));console.log('job ready');setInterval(()=>{},1000);");
+  try {
+    await expect(runTutorial(parseTutorial('```bash\nbun job.mjs &\n```\n```text\njob ready\n```\n', 'stop-fail.md'),
+      { dir, parent: dir, env: { ...process.env } as Record<string, string> })).rejects.toThrow('failed during cleanup: 7');
+    expect(existsSync(dir)).toBe(true);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}, 20_000);
+
+
+test('npm and Bun keep the local scope in global installs and nested directories, with no public fallback', async () => {
+  const hits: string[] = [];
+  const registry = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch(request) {
+    hits.push(new URL(request.url).pathname);
+    return Response.json({ error: 'fixture package missing' }, { status: 404 });
+  } });
+  let publicRegistry: ReturnType<typeof Bun.serve> | undefined;
+  const publicHits: string[] = [];
+  let app: ReturnType<typeof tutorialApp> | undefined;
+  try {
+    app = tutorialApp('registry-scope', { env: { NPM_CONFIG_REGISTRY: `http://127.0.0.1:${registry.port}` } });
+    const nested = join(app.dir, 'nested');
+    mkdirSync(nested);
+    for (const global of [false, true]) {
+      const scope = Bun.spawn(['npm', 'view', '@volter/fixture-scope-missing', '--json', '--fetch-retries=0', ...(global ? ['--global'] : [])],
+        { cwd: nested, env: app.env, stdout: 'pipe', stderr: 'pipe' });
+      const [code, output, error] = await Promise.all([scope.exited, new Response(scope.stdout).text(), new Response(scope.stderr).text()]);
+      expect(code).not.toBe(0);
+      expect(output + error).toContain('fixture package missing');
+      expect(hits).toHaveLength(global ? 2 : 1);
+      const defaults = Bun.spawn(['npm', 'config', 'get', 'registry', ...(global ? ['--global'] : [])],
+        { cwd: nested, env: app.env, stdout: 'pipe', stderr: 'pipe' });
+      const [defaultCode, value] = await Promise.all([defaults.exited, new Response(defaults.stdout).text(), new Response(defaults.stderr).text()]);
+      expect(defaultCode).toBe(0);
+      expect(value.trim()).toBe('https://registry.npmjs.org/');
+    }
+    expect(app.env.BUN_CONFIG_REGISTRY).toBe('https://registry.npmjs.org/');
+    publicRegistry = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch(request) {
+      publicHits.push(new URL(request.url).pathname);
+      return Response.json({ error: 'default fixture missing' }, { status: 404 });
+    } });
+    const bunEnv = { ...app.env, BUN_CONFIG_REGISTRY: `http://127.0.0.1:${publicRegistry.port}` };
+    for (const global of [false, true]) {
+      const bun = Bun.spawn(['bun', 'add', '@volter/fixture-scope-missing', '--ignore-scripts', ...(global ? ['--global'] : [])],
+        { cwd: nested, env: bunEnv, stdout: 'pipe', stderr: 'pipe' });
+      const [bunCode, bunOutput, bunError] = await Promise.all([bun.exited, new Response(bun.stdout).text(), new Response(bun.stderr).text()]);
+      expect(bunCode).not.toBe(0);
+      expect(bunOutput + bunError).toContain('404');
+      expect(hits).toHaveLength(global ? 4 : 3);
+      expect(publicHits).toEqual([]);
+    }
+    const unscoped = Bun.spawn(['bun', 'add', 'fixture-public-missing', '--ignore-scripts'],
+      { cwd: nested, env: bunEnv, stdout: 'pipe', stderr: 'pipe' });
+    const [unscopedCode] = await Promise.all([unscoped.exited, new Response(unscoped.stdout).text(), new Response(unscoped.stderr).text()]);
+    expect(unscopedCode).not.toBe(0);
+    expect(publicHits).toEqual(['/fixture-public-missing']);
+    expect(hits).toHaveLength(4);
+    expect(hits.every(path => decodeURIComponent(path) === '/@volter/fixture-scope-missing')).toBe(true);
+  } finally { registry.stop(true); publicRegistry?.stop(true); if (app) rmSync(app.parent, { recursive: true, force: true }); }
+}, 30_000);
+
+
+test('cleanup ignores arbitrary pid files and symlinked World roots', async () => {
+  const parent = mkdtempSync(join(tmpdir(), 'tutorial-cleanup-'));
+  const outside = mkdtempSync(join(tmpdir(), 'tutorial-outside-'));
+  const child = Bun.spawn([process.execPath, '-e', 'setInterval(()=>{},1000)'], { stdout: 'ignore', stderr: 'ignore' });
+  try {
+    writeFileSync(join(parent, 'pids'), `${child.pid}\n`);
+    const instance = join(outside, '.volter', 'worlds', 'outside');
+    mkdirSync(instance, { recursive: true });
+    writeFileSync(join(instance, 'instance.json'), 'unreadable fixture');
+    symlinkSync(outside, join(parent, 'linked-app'));
+    const app = join(parent, 'app');
+    mkdirSync(join(app, '.volter'), { recursive: true });
+    symlinkSync(join(outside, '.volter', 'worlds'), join(app, '.volter', 'worlds'));
+    await downEverything(parent);
+    expect(process.kill(child.pid, 0)).toBe(true);
+    expect(readFileSync(join(instance, 'instance.json'), 'utf8')).toBe('unreadable fixture');
+  } finally {
+    child.kill('SIGTERM'); await child.exited;
+    rmSync(parent, { recursive: true, force: true });
+    rmSync(outside, { recursive: true, force: true });
+  }
+});
+
+test('failed World teardown prevents fixture removal and reports the retained path', async () => {
+  const parent = mkdtempSync(join(tmpdir(), 'tutorial-retain-'));
+  const instance = join(parent, '.volter', 'worlds', 'broken');
+  mkdirSync(instance, { recursive: true });
+  mkdirSync(join(parent, '.volter', 'worlds', '.locks'));
+  mkdirSync(join(parent, '.volter', 'worlds', '.resources'));
+  const metadata = join(instance, 'instance.json');
+  writeFileSync(metadata, 'unreadable fixture');
+  try {
+    await expect(removeTutorialApp(parent)).rejects.toThrow(`retained ${parent}`);
+    expect(readFileSync(metadata, 'utf8')).toBe('unreadable fixture');
+    // This fixture never launched processes: removing the corrupt test record makes teardown safe.
+    rmSync(metadata);
+    await removeTutorialApp(parent);
+    expect(existsSync(parent)).toBe(false);
+  } finally { rmSync(parent, { recursive: true, force: true }); }
+});

package/src/journeys/tutorial.ts

@@ -0,0 +1,345 @@
+// The tutorial runner — a tutorial page IS its journey (owner, 2026-09-05: "the journeys should
+// ONLY be what happens in the tutorials — that way to keep the tutorials up to date and proven").
+//
+// A page is read for its fences, in order:
+//   ```bash            every non-comment line is one command the reader types, run in ONE bash
+//                      session that persists across the page (env, cwd, background jobs), the
+//                      way a terminal does; a trailing `&` runs a server in the background
+//   ```text            right after a bash fence: what the reader sees — every line must appear
+//                      in that command's output, after ports, ids, hashes and times are masked
+//   ```<lang> file=p   a file the reader writes at path p (relative to the app) before going on
+// Everything else (a ```json config excerpt, a ```ts snippet with no file=) is illustration.
+//
+// Every command runs literally, `bun add` included: the app installs from the registry the
+// caller names (scripts/registry.ts — this checkout's packages, published to a registry on this
+// machine), with a global install dir and an install cache of its own, so `bun add -g
+// @volter/world` puts `volter` on the PATH the way it does for a reader.
+//
+// The same steps make the recording: `tapeFor(page)` renders a vhs tape that types each command,
+// waits, and screenshots after each one, so docs/media/<page>/ is the page's own playback.
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { downWorld } from '@volter/world-runtime';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { CLI, OPERATOR_CLI, PACKS, SDK } from './kit.ts';
+void CLI; void OPERATOR_CLI; void PACKS; void SDK;
+
+export type Step =
+  | { kind: 'file'; path: string; content: string; line: number }
+  | { kind: 'run'; command: string; background: boolean; expect: string[]; line: number; /** the bash fence this command came from: a text fence is what the reader sees after the WHOLE fence */ fence: number };
+
+export type Tutorial = { name: string; file: string; steps: Step[] };
+
+const FENCE = /^```([^\n]*)\n([\s\S]*?)^```[ \t]*$/gm;
+
+/** The steps of a tutorial page, in the order the reader meets them. */
+export function parseTutorial(markdown: string, file: string): Tutorial {
+  const steps: Step[] = [];
+  let lastRun: Extract<Step, { kind: 'run' }> | null = null;
+  let fence = 0;
+  for (const m of markdown.matchAll(FENCE)) {
+    const info = m[1]!.trim();
+    const body = m[2]!;
+    const line = markdown.slice(0, m.index).split('\n').length;
+    const [lang, ...attrs] = info.split(/\s+/);
+    const fileAttr = attrs.find((a) => a.startsWith('file='))?.slice(5);
+    if (fileAttr) { steps.push({ kind: 'file', path: fileAttr, content: body, line }); lastRun = null; continue; }
+    if (lang === 'bash' || lang === 'sh' || lang === 'shell') {
+      lastRun = null; fence += 1;
+      for (const command of commandsOf(body)) {
+        const background = /\s&\s*$/.test(command);
+        const step: Extract<Step, { kind: 'run' }> = { kind: 'run', command: command.replace(/\s&\s*$/, '').trim(), background, expect: [], line, fence };
+        steps.push(step); lastRun = step;
+      }
+      continue;
+    }
+    if (lang === 'text' && lastRun) {
+      lastRun.expect = body.split('\n').map((l) => l.trimEnd()).filter((l) => l.trim() !== '');
+      lastRun = null;
+      continue;
+    }
+    lastRun = null;
+  }
+  // a cookbook recipe's page is its README: the recipe's directory is its name
+  const base = basename(file).replace(/\.md$/, '');
+  return { name: base === 'README' ? basename(dirname(file)) : base, file, steps };
+}
+
+/** Lines of a bash fence as commands: comments and blanks dropped, `\` continuations joined. */
+function commandsOf(body: string): string[] {
+  const out: string[] = [];
+  let pending = '';
+  for (const raw of body.split('\n')) {
+    const line = raw.replace(/\s+#.*$/, '').trimEnd();
+    if (line.trim() === '' || line.trim().startsWith('#')) continue;
+    if (line.endsWith('\\')) { pending += `${line.slice(0, -1)} `; continue; }
+    out.push((pending + line).trim()); pending = '';
+  }
+  if (pending.trim()) out.push(pending.trim());
+  return out;
+}
+
+/** What varies between runs and machines, masked before an expected line is looked for. */
+export function mask(text: string): string {
+  text = text.replace(/[ \t]{2,}/g, ' '); // columns are alignment, not content
+  return text
+    .replace(/127\.0\.0\.1:\d+/g, '127.0.0.1:PORT')
+    .replace(/\b\d\d:\d\d:\d\d\.\d{3}\b/g, 'TIME')
+    .replace(/\b\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?Z\b/g, 'ISO')
+    .replace(/\b(cus|evt|sub|price|prod|ch|pi|in|cs|act|chg|ghp|xoxb|xoxp)_[A-Za-z0-9_]+/g, '$1_ID')
+    .replace(/\(([0-9a-f]{12})\)/g, '(HASH)')
+    .replace(/\b[0-9a-f]{32,64}\b/g, 'HEX')
+    .replace(/Stopped (\S+): [\d, ]+/g, 'Stopped $1: PIDS')
+    .replace(/\/(?:private\/)?(?:var|tmp)\/[^\s'"]+/g, '/TMP')
+    .replace(/[ \t]+/g, ' ')
+    .trim();
+}
+
+export type StepResult = { step: Step; output: string; missing: string[]; exit: number | null };
+
+/**
+ * A scratch app for a tutorial: an empty directory, a config dir of its own, a global install dir
+ * of its own on the PATH, and the registry to install from. The page makes everything else — its
+ * package.json, its env example, its files — and installs what it names.
+ */
+export function tutorialApp(name: string, registry: { env: Record<string, string> }): { dir: string; parent: string; env: Record<string, string> } {
+  const parent = mkdtempSync(join(tmpdir(), `tutorial-${name}-`));
+  const dir = join(parent, 'acme-web');
+  mkdirSync(dir);
+  const global = join(parent, 'bun-global');
+  mkdirSync(join(global, 'bin'), { recursive: true });
+  const env = { ...process.env as Record<string, string>, ...registry.env, BUN_INSTALL: global, npm_config_prefix: global, npm_config_cache: join(parent, 'npm-cache'), npm_config_update_notifier: 'false', PATH: `${join(global, 'bin')}:${process.env.PATH ?? ''}`, XDG_CONFIG_HOME: join(parent, 'config'), PS1: '$ ' };
+  const localRegistry = registry.env.NPM_CONFIG_REGISTRY;
+  if (localRegistry) {
+    // Both clients read this private scope config, including global installs and nested dirs.
+    // Public SDK tarballs use the default registry without an extra Verdaccio relay.
+    mkdirSync(env.XDG_CONFIG_HOME, { recursive: true });
+    const npmrc = join(env.XDG_CONFIG_HOME, '.npmrc');
+    writeFileSync(npmrc, `@volter:registry=${localRegistry}\n`);
+    Object.assign(env, {
+      NPM_CONFIG_USERCONFIG: npmrc, npm_config_userconfig: npmrc,
+      NPM_CONFIG_REGISTRY: 'https://registry.npmjs.org/', npm_config_registry: 'https://registry.npmjs.org/',
+      BUN_CONFIG_REGISTRY: 'https://registry.npmjs.org/',
+    });
+  }
+  return { dir, parent, env };
+}
+
+const DONE = '__VOLTER_STEP_DONE__';
+
+/**
+ * Run a tutorial's steps in one bash session in the app, checking each expected line. Returns
+ * every step's result; `failures()` says which steps the page got wrong.
+ */
+export async function runTutorial(tutorial: Tutorial, app: { dir: string; parent: string; env: Record<string, string> }, opts: { stepTimeoutMs?: number; onStep?: (r: StepResult) => void } = {}): Promise<StepResult[]> {
+  const shell = Bun.spawn({ cmd: ['bash', '--noprofile', '--norc'], cwd: app.dir, env: app.env, stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
+  const results: StepResult[] = [];
+  const reader = shell.stdout.getReader();
+  const errReader = shell.stderr.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let errBuffer = '';
+  // one read in flight at a time: a read abandoned by a timeout race would swallow its chunk
+  let pending: ReturnType<typeof reader.read> | null = null;
+  const nextChunk = (): ReturnType<typeof reader.read> => {
+    if (pending === null) pending = reader.read().then((r) => { pending = null; return r; });
+    return pending;
+  };
+  // stderr is drained continuously (a background server's chatter must never block the shell)
+  const stderrDrain = (async () => { for (;;) { const { value, done } = await errReader.read(); if (done) break; errBuffer += decoder.decode(value); } })();
+  stderrDrain.catch(() => {}); // awaited at shutdown, including a failed reader
+  let current: Extract<Step, { kind: 'run' }> | null = null; // the step under way, for the timeout's message
+  const readUntilDone = async (timeoutMs: number, marker = DONE): Promise<{ output: string; exit: number | null }> => {
+    const started = Date.now();
+    for (;;) {
+      const i = buffer.indexOf(marker);
+      if (i >= 0) {
+        const tail = buffer.slice(i + marker.length);
+        const nl = tail.indexOf('\n');
+        if (nl >= 0) {
+          const exit = Number(tail.slice(0, nl));
+          const output = buffer.slice(0, i);
+          buffer = tail.slice(nl + 1);
+          return { output, exit: Number.isFinite(exit) ? exit : null };
+        }
+      }
+      if (Date.now() - started > timeoutMs) throw new Error(`step timed out after ${timeoutMs}ms${current ? ` at line ${current.line}: \`${current.command}\`` : ''}; output so far:\n${buffer}\n${errBuffer}`);
+      const chunk = await Promise.race([nextChunk(), new Promise<{ value: undefined; done: false }>((r) => setTimeout(() => r({ value: undefined, done: false }), 250))]);
+      if (chunk.done) throw new Error(`the shell exited; output so far:\n${buffer}\n${errBuffer}`);
+      if (chunk.value) buffer += decoder.decode(chunk.value);
+    }
+  };
+  const send = (text: string) => { shell.stdin.write(text); shell.stdin.flush(); };
+  send('__volter_tutorial_jobs=()\n');
+  const cleanupShell = async (): Promise<void> => {
+    // Signals begin asynchronous World teardown. Bash must reap its own jobs before we down
+    // their Worlds. A delayed step-DONE is not proof this cleanup protocol has even started.
+    const marker = `__VOLTER_CLEANUP_${randomUUID()}__`;
+    let exitTimer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      send(`for j in $(jobs -pr); do kill "$j" 2>/dev/null || true; done\n__volter_tutorial_cleanup=0\nfor j in "\${__volter_tutorial_jobs[@]}"; do wait "$j"; s=$?; case "$s" in 0|129|130|143) ;; *) echo "background job $j failed during cleanup: $s"; __volter_tutorial_cleanup=1 ;; esac; done\necho ${marker}$__volter_tutorial_cleanup\n`);
+      const joined = await readUntilDone(10_000, marker);
+      if (joined.exit !== 0) throw new Error(joined.output);
+      send('exit\n');
+      const stdoutDrain = (async () => { while (!(await nextChunk()).done) { /* drain to EOF */ } })();
+      await Promise.race([
+        Promise.all([shell.exited, stdoutDrain, stderrDrain]),
+        new Promise<never>((_, reject) => { exitTimer = setTimeout(() => reject(new Error('tutorial shell did not exit and close its output')), 5000); }),
+      ]);
+    } catch (error) {
+      if (shell.pid) killTree(shell.pid); // bounded fallback; no claim that its children joined
+      await Promise.allSettled([reader.cancel(), errReader.cancel()]);
+      throw new Error(`Tutorial shell cleanup unconfirmed; retained ${app.parent}: ${String(error)}`);
+    } finally { if (exitTimer) clearTimeout(exitTimer); }
+  };
+  const fenceOutput = new Map<number, string>(); // what the reader saw after each bash fence, all its commands
+  const backgroundFences = new Set<number>();
+  try {
+    for (const step of tutorial.steps) {
+      if (step.kind === 'file') {
+        const path = join(app.dir, step.path);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, step.content);
+        const r: StepResult = { step, output: '', missing: [], exit: 0 };
+        results.push(r); opts.onStep?.(r);
+        continue;
+      }
+      let output = '';
+      let exit: number | null = 0;
+      current = step;
+      const deadline = Date.now() + (opts.stepTimeoutMs ?? 120_000);
+      if (step.background) {
+        backgroundFences.add(step.fence);
+        send(`${step.command} 2>&1 &\n__volter_tutorial_jobs+=("$!")\necho ${DONE}0\n`);
+        ({ output, exit } = await readUntilDone(opts.stepTimeoutMs ?? 120_000));
+        // Keep the existing settling period for subsequent commands in this fence;
+        // required output is additionally awaited at the fence boundary below.
+        await new Promise((r) => setTimeout(r, 2500));
+        send(`echo ${DONE}0\n`);
+        output += (await readUntilDone(opts.stepTimeoutMs ?? 120_000)).output;
+      } else {
+        send(`${step.command} 2>&1\necho ${DONE}$?\n`);
+        ({ output, exit } = await readUntilDone(opts.stepTimeoutMs ?? 120_000));
+      }
+      fenceOutput.set(step.fence, `${fenceOutput.get(step.fence) ?? ''}${output}`);
+      if (step.expect.length && backgroundFences.has(step.fence)) {
+        // Expectations describe the WHOLE fence, even when its final command is cd.
+        // No extra app command is injected, and noisy output never extends the deadline.
+        for (;;) {
+          if (buffer) { fenceOutput.set(step.fence, `${fenceOutput.get(step.fence) ?? ''}${buffer}`); buffer = ''; }
+          const observed = mask(fenceOutput.get(step.fence) ?? '');
+          if (step.expect.every(line => observed.includes(mask(line))) || Date.now() >= deadline) break;
+          const chunk = await Promise.race([nextChunk(), new Promise<{ value: undefined; done: false }>((r) => setTimeout(() => r({ value: undefined, done: false }), Math.min(250, Math.max(1, deadline - Date.now()))))]);
+          if (chunk.done) break;
+          if (chunk.value) buffer += decoder.decode(chunk.value);
+        }
+      }
+      const masked = mask(fenceOutput.get(step.fence) ?? output);
+      const missing = step.expect.filter((line) => !masked.includes(mask(line)));
+      const r: StepResult = { step, output: step.expect.length ? (fenceOutput.get(step.fence) ?? output) : output, missing, exit };
+      results.push(r); opts.onStep?.(r);
+    }
+  } finally {
+    await cleanupShell();
+    await downEverything(app.parent);
+  }
+  return results;
+}
+
+/** Stop only Worlds discovered within this fixture, through the runtime's ownership checks. */
+export async function downEverything(parent: string): Promise<void> {
+  const worlds: Array<{ name: string; root: string }> = [];
+  const directory = (path: string): boolean => lstatSync(path).isDirectory();
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === 'node_modules') continue; // never follow symlinks
+      const full = join(dir, entry.name);
+      if (entry.name === '.volter') {
+        const instances = join(full, 'worlds');
+        if (existsSync(instances) && directory(instances)) {
+          for (const world of readdirSync(instances, { withFileTypes: true })) {
+            // Runtime metadata (.locks/.resources) is not a World; use the World-name grammar.
+            if (world.isDirectory() && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(world.name)) worlds.push({ name: world.name, root: dir });
+          }
+        }
+        continue; // instance data is not another app's World root
+      }
+      walk(full);
+    }
+  };
+  if (!directory(parent)) throw new Error(`Tutorial cleanup requires a real scratch directory: ${parent}`);
+  walk(parent);
+  const errors: Error[] = [];
+  for (const w of worlds) {
+    try {
+      const result = await downWorld(w.name, w.root);
+      if (result.externalErrors.length) throw new Error(result.externalErrors.join('; '));
+    } catch (error) {
+      errors.push(new Error(`${w.name} at ${w.root}: ${String(error)}`));
+    }
+  }
+  if (errors.length) throw new AggregateError(errors, `Tutorial cleanup incomplete; retained ${parent}: ${errors.map(error => error.message).join('; ')}`);
+}
+
+/** Removal is conditional on successful World teardown, including after a failed page. */
+export async function removeTutorialApp(parent: string): Promise<void> {
+  await downEverything(parent);
+  rmSync(parent, { recursive: true, force: true });
+}
+
+/** Kill a process and its descendants, children first, each by its exact pid. */
+export function killTree(pid: number): void {
+  const children = Bun.spawnSync({ cmd: ['pgrep', '-P', String(pid)] }).stdout.toString().split('\n').map((s) => Number(s.trim())).filter((n) => Number.isFinite(n) && n > 0);
+  for (const child of children) killTree(child);
+  try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+}
+
+export function failures(results: StepResult[]): string[] {
+  const out: string[] = [];
+  for (const r of results) {
+    if (r.step.kind !== 'run') continue;
+    if (r.missing.length) out.push(`line ${r.step.line}: \`${r.step.command}\` — expected line(s) not in output:\n    ${r.missing.join('\n    ')}\n  output:\n    ${r.output.trim().split('\n').join('\n    ')}`);
+    // a command with no expected output must succeed; one with expected output is judged by it (a page may show a refusal)
+    if (r.exit !== 0 && r.exit !== null && !r.step.background && r.step.expect.length === 0) out.push(`line ${r.step.line}: \`${r.step.command}\` exited ${r.exit}:\n    ${r.output.trim().split('\n').join('\n    ')}`);
+  }
+  return out;
+}
+
+/** The vhs tape for a page: type each command, wait, screenshot; files are named, not typed. */
+export function tapeFor(tutorial: Tutorial, opts: { gif: string; shotsDir: string }): string {
+  const lines = [
+    `# ${tutorial.file}, recorded — generated from the page by scripts/docs-media.ts; do not edit.`,
+    `Output ${opts.gif}`,
+    'Set Shell "bash"', 'Set FontSize 15', 'Set Width 1100', 'Set Height 640', 'Set Padding 24', 'Set Theme "Catppuccin Mocha"', 'Set TypingSpeed 35ms', '',
+  ];
+  let n = 0;
+  for (const step of tutorial.steps) {
+    if (step.kind === 'file') { lines.push(`Type "# wrote ${step.path}"`, 'Enter', 'Sleep 800ms', ''); continue; }
+    n += 1;
+    const wait = /^volter world (up|reset|init|clone|push)\b/.test(step.command) ? '6s' : /^volter world run\b|^bun add\b/.test(step.command) ? '4s' : '2500ms';
+    lines.push(`Type "${step.command.replace(/"/g, '\\"')}${step.background ? ' &' : ''}"`, 'Enter', `Sleep ${wait}`, `Screenshot ${opts.shotsDir}/step-${String(n).padStart(2, '0')}.png`, '');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/** Every @volter package the pages install, for the registry to publish. */
+export function packagesNamedIn(files: string[]): string[] {
+  const { readFileSync } = require('node:fs') as typeof import('node:fs');
+  const names = new Set<string>(['@volter/world']);
+  // every install line a page types — `bun add …`, `npm install …`, `npm i …` — names the packages the registry must hold
+  for (const f of files) for (const m of readFileSync(f, 'utf8').matchAll(/\b(?:bun add|npm (?:install|i|add))\b[^\n]*/g)) for (const t of m[0].split(/\s+/)) if (t.startsWith('@volter/')) names.add(t.replace(/@[^@/]*$/, ''));
+  return [...names];
+}
+
+export const TUTORIALS_DIR = resolve(import.meta.dir, '..', '..', '..', '..', 'docs');
+/** Every tutorial page: getting-started, then the guides. */
+export function tutorialFiles(): string[] {
+  const { readdirSync } = require('node:fs') as typeof import('node:fs');
+  const guides = readdirSync(join(TUTORIALS_DIR, 'guides')).filter((f) => f.endsWith('.md')).sort().map((f) => join(TUTORIALS_DIR, 'guides', f));
+  // a cookbook page is a journey too when it says so (`<!-- journey -->`): the same runner, the same proof
+  const { readFileSync } = require('node:fs') as typeof import('node:fs');
+  const cookbook = join(TUTORIALS_DIR, '..', 'cookbook');
+  const recipes = readdirSync(cookbook, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => join(cookbook, e.name, 'README.md')).filter((f) => { try { return readFileSync(f, 'utf8').includes('<!-- journey -->'); } catch { return false; } }).sort();
+  return [join(TUTORIALS_DIR, 'getting-started.md'), ...guides, ...recipes];
+}

package/src/journeys/tutorials.test.ts

@@ -0,0 +1,39 @@
+// Every tutorial page, executed as written (tutorial.ts): the page's bash fences are typed into
+// one shell in a scratch app, each ```text fence must appear in its command's output, each
+// `file=` fence is written where the page says. Nothing runs that the page does not show — a
+// page that drifts from the product fails here, by line number.
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { failures, packagesNamedIn, parseTutorial, removeTutorialApp, runTutorial, tutorialApp, tutorialFiles, TUTORIALS_DIR } from './tutorial.ts';
+import { startRegistry, type Registry } from '../../../../scripts/registry.ts';
+
+const only = process.env.TUTORIAL;
+const pages = tutorialFiles().filter((f) => !only || f.endsWith(`${only}.md`));
+
+// one registry for the whole file: this checkout's packages, published to a registry on this
+// machine, so every page's `bun add` is a real install
+let registry: Registry | null = null;
+beforeAll(async () => { registry = await startRegistry({ only: packagesNamedIn(pages) }); }, 300_000);
+afterAll(() => { registry?.stop(); });
+
+for (const file of pages) {
+  const tutorial = parseTutorial(readFileSync(file, 'utf8'), file);
+  const label = relative(TUTORIALS_DIR, file);
+  describe(label, () => {
+    test('has steps a reader runs', () => { expect(tutorial.steps.filter((s) => s.kind === 'run').length).toBeGreaterThan(2); });
+    test('runs as written', async () => {
+      const app = tutorialApp(tutorial.name, registry!);
+      // a page about the hosted product runs against the hosted stack — the rehearsal's, stood up for the page (scripts/hosted-stack.ts)
+      const { needsHosted, startHostedStack } = await import('../../../../scripts/hosted-stack.ts');
+      const hosted = needsHosted(readFileSync(file, 'utf8')) ? await startHostedStack() : null;
+      if (hosted) Object.assign(app.env, hosted.env);
+      let results;
+      let completed = false;
+      try { results = await runTutorial(tutorial, app, { stepTimeoutMs: 180_000 }); completed = true; }
+      finally { await hosted?.stop(); if (process.env.TUTORIAL_KEEP || !completed) console.error(`kept ${app.parent}`); else await removeTutorialApp(app.parent); } // failed shell/World cleanup retains its evidence; TUTORIAL_KEEP=1 also keeps a successful page
+      const wrong = failures(results);
+      expect(wrong, wrong.join('\n\n')).toEqual([]);
+    }, 900_000);
+  });
+}

package/src/locate.ts

@@ -0,0 +1,61 @@
+// Where the world is (docs/concepts/worlds.md#the-config-and-the-running-world): the nearest `.volter/world.json`
+// above the cwd names the world root — the app repo — and `.volter/current` names the branch that
+// is checked out (absent: the main branch, the config's `id`). Every `volter` verb and
+// `World.open()` start here, the way `git` starts from the nearest `.git`.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { stateDirName } from '@volter/world-core';
+import { loadWorldConfig } from '@volter/world-runtime';
+
+export const WORLD_FILE = 'world.json';
+
+/** `<root>/.volter` */
+export function stateDir(root: string): string { return join(root, stateDirName()); }
+/** `<root>/.volter/world.json` — the config, relative to the root as `up` takes it. */
+export function worldConfigRelative(): string { return join(stateDirName(), WORLD_FILE); }
+export function worldConfigPath(root: string): string { return join(stateDir(root), WORLD_FILE); }
+/** `<root>/.volter/world.env` — where `up` writes the live env (gitignored by init). */
+export function worldEnvPath(root: string): string { return join(stateDir(root), 'world.env'); }
+/** `<root>/.volter/seed.ts` — the default data, when the world has any. */
+export function worldSeedPath(root: string): string { return join(stateDir(root), 'seed.ts'); }
+
+/** The world root above `from`, or null: the nearest directory holding `.volter/world.json`. */
+export function findWorldRoot(from: string = process.cwd()): string | null {
+  let dir = resolve(from);
+  for (;;) {
+    if (existsSync(worldConfigPath(dir))) return dir;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+export function requireWorldRoot(from: string = process.cwd()): string {
+  const root = findWorldRoot(from);
+  if (root === null) {
+    throw new Error(`Not in a world: no ${worldConfigRelative()} here or above ${resolve(from)}. Run \`volter world init\` in your app, or pass --world <dir>.`);
+  }
+  return root;
+}
+
+/** The main branch: the config's `id`. */
+export function mainBranch(root: string): string {
+  return loadWorldConfig(worldConfigPath(root), root).config.id;
+}
+
+const CURRENT = 'current';
+
+/** The checked-out branch: `.volter/current`, else main. */
+export function currentBranch(root: string): string {
+  const file = join(stateDir(root), CURRENT);
+  if (!existsSync(file)) return mainBranch(root);
+  const name = readFileSync(file, 'utf8').trim();
+  return name === '' ? mainBranch(root) : name;
+}
+
+export function setCurrentBranch(root: string, name: string): void {
+  mkdirSync(stateDir(root), { recursive: true });
+  const file = join(stateDir(root), CURRENT);
+  if (name === mainBranch(root)) { if (existsSync(file)) rmSync(file); return; }
+  writeFileSync(file, `${name}\n`);
+}