@volter/world 2.0.1 → 2.0.2

package/src/credentials.ts

@@ -36,12 +36,23 @@ export function storeToken(origin: string, token: string, path: string = credent
   chmodSync(path, 0o600);
 }
 
+/** Forget the token stored for an origin; whether one was stored. */
+export function forgetToken(origin: string, path: string = credentialsPath()): boolean {
+  const store = readStore(path); const key = normalizeOrigin(origin);
+  if (!(key in store)) return false;
+  delete store[key];
+  writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  return true;
+}
+
 /** `volter login`: the hosted platform a person signed the CLI into — its origin, beside the credentials. */
 export function platformPath(): string { return join(dirname(credentialsPath()), 'platform.json'); }
 export function storePlatform(origin: string, path: string = platformPath()): void {
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   writeFileSync(path, `${JSON.stringify({ url: normalizeOrigin(origin), savedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
 }
+/** Forget which platform the CLI is signed into. */
+export function forgetPlatform(path: string = platformPath()): void { if (existsSync(path)) writeFileSync(path, '{}\n', { mode: 0o600 }); }
 export function platformOrigin(path: string = platformPath()): string | undefined {
   if (!existsSync(path)) return undefined;
   try { return (JSON.parse(readFileSync(path, 'utf8')) as { url?: string }).url; } catch { return undefined; }

package/src/journeys/tutorial.ts

@@ -20,7 +20,7 @@
 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 { basename, delimiter, 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;
@@ -98,6 +98,10 @@ export function mask(text: string): string {
 
 export type StepResult = { step: Step; output: string; missing: string[]; exit: number | null };
 
+/** The PATH with the scratch app's global install dir first. bun and npm on POSIX link global bins into `<prefix>/bin`;
+ *  npm on Windows puts its `.cmd` shims in the prefix itself, and PATH is `;`-separated there. */
+const globalPath = (global: string): string => [...(process.platform === 'win32' ? [global] : []), join(global, 'bin'), process.env.PATH ?? ''].join(delimiter);
+
 /**
  * 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
@@ -109,7 +113,7 @@ export function tutorialApp(name: string, registry: { env: Record<string, string
   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 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: globalPath(global), 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.
@@ -133,7 +137,22 @@ const DONE = '__VOLTER_STEP_DONE__';
  * 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 shell = Bun.spawn({ cmd: ['bash', '--noprofile', '--norc'], cwd: app.dir, env: app.env, stdin: 'pipe', stdout: 'pipe', stderr: 'pipe', windowsHide: true });
+  // Windows keeps no parent for a process whose parent died, and an msys process that execs (npx's sh script) leaves
+  // its Windows children parentless within a second, so what the page started is found through both trees: the msys
+  // processes under the shell (Git's `ps`, which keeps their parentage across exec), then the Windows processes under
+  // each of those; recorded after every step, by pid and start time, so a reused pid is never mistaken
+  const started = new Map<string, WinProcess>();
+  const recordDescendants = (): void => {
+    if (process.platform !== 'win32' || !shell.pid) return;
+    const procs = windowsProcesses();
+    const roots = [shell.pid, ...msysDescendantWinpids(shell.pid)];
+    const byPid = new Map(procs.map((p) => [p.pid, p]));
+    for (const root of roots) {
+      const self = byPid.get(root); if (self && root !== shell.pid) started.set(`${self.pid}@${self.created}`, self);
+      for (const p of descendantsOf(root, procs)) started.set(`${p.pid}@${p.created}`, p);
+    }
+  };
   const results: StepResult[] = [];
   const reader = shell.stdout.getReader();
   const errReader = shell.stderr.getReader();
@@ -172,6 +191,8 @@ export async function runTutorial(tutorial: Tutorial, app: { dir: string; parent
   };
   const send = (text: string) => { shell.stdin.write(text); shell.stdin.flush(); };
   send('__volter_tutorial_jobs=()\n');
+  // processes the page started that outlived its own stop and the harness's kill of its jobs (Windows)
+  let leftovers: WinProcess[] = [];
   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.
@@ -181,12 +202,23 @@ export async function runTutorial(tutorial: Tutorial, app: { dir: string; parent
       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);
+      if (process.platform === 'win32') recordDescendants();
       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); }),
-      ]);
+      stdoutDrain.catch(() => {});
+      const bounded = <T>(p: Promise<T>): Promise<T> => Promise.race([p, new Promise<never>((_, reject) => { exitTimer = setTimeout(() => reject(new Error('tutorial shell did not exit and close its output')), 5000); })]);
+      if (process.platform !== 'win32') await bounded(Promise.all([shell.exited, stdoutDrain, stderrDrain]));
+      else {
+        // Windows: a job killed by the page (or above) can leave a server running under it (`kill %1` ends npx, not
+        // the node it started); such a server holds the shell's output open. So the shell's own exit is waited for,
+        // then what it started and is still running (its console host went with it) is a leftover, ended only once
+        // the page's Worlds are down (runTutorial's finally); with none, its output closes as on any platform
+        await bounded(shell.exited);
+        const alive = new Set(windowsProcesses().map((p) => `${p.pid}@${p.created}`));
+        leftovers = [...started.entries()].filter(([k, p]) => alive.has(k) && p.pid !== shell.pid).map(([, p]) => p);
+        if (exitTimer) clearTimeout(exitTimer);
+        if (!leftovers.length) await bounded(Promise.all([stdoutDrain, stderrDrain]));
+      }
     } catch (error) {
       if (shell.pid) killTree(shell.pid); // bounded fallback; no claim that its children joined
       await Promise.allSettled([reader.cancel(), errReader.cancel()]);
@@ -238,11 +270,20 @@ export async function runTutorial(tutorial: Tutorial, app: { dir: string; parent
       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 };
+      recordDescendants();
       results.push(r); opts.onStep?.(r);
     }
   } finally {
     await cleanupShell();
     await downEverything(app.parent);
+    if (leftovers.length) {
+      // the page's Worlds are down: what is still running is the page's leak, ended now (only these pids, each checked
+      // against its start time) and reported, never hidden
+      const alive = new Set(windowsProcesses().map((p) => `${p.pid}@${p.created}`));
+      for (const p of leftovers) if (alive.has(`${p.pid}@${p.created}`)) Bun.spawnSync({ cmd: ['taskkill', '/PID', String(p.pid), '/T', '/F'], windowsHide: true, stdout: 'ignore', stderr: 'ignore' });
+      await Promise.allSettled([reader.cancel(), errReader.cancel()]);
+      throw new Error(`the page left ${leftovers.length} process(es) running after its own stop and the harness's kill of its jobs (ended now):\n${leftovers.map((p) => `  pid ${p.pid}: ${p.command}`).join('\n')}`);
+    }
   }
   return results;
 }
@@ -288,9 +329,46 @@ export async function removeTutorialApp(parent: string): Promise<void> {
   rmSync(parent, { recursive: true, force: true });
 }
 
+/** A Windows process as the harness records it: identity is the pid with its start time (pids are reused). */
+export type WinProcess = { pid: number; parent: number; created: string; command: string };
+
+/** Every process on this Windows machine, with its parent, start time and command line. */
+export function windowsProcesses(): WinProcess[] {
+  const query = 'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId)`t$($_.ParentProcessId)`t$($_.CreationDate.ToFileTimeUtc())`t$($_.CommandLine)" }';
+  const out = Bun.spawnSync({ cmd: ['powershell', '-NoProfile', '-Command', query], windowsHide: true, stdout: 'pipe', stderr: 'ignore' }).stdout.toString();
+  return out.split(/\r?\n/).filter(Boolean).map((line) => { const [pid, parent, created, ...command] = line.split('\t'); return { pid: Number(pid), parent: Number(parent), created: created ?? '', command: command.join('\t') }; }).filter((p) => p.pid > 0);
+}
+
+/** The Windows pids of the msys processes descended from the msys process whose Windows pid is `winpid`, from Git's
+ *  `ps -l` (columns PID PPID PGID WINPID …); none where there is no `ps`. */
+export function msysDescendantWinpids(winpid: number): number[] {
+  const ps = Bun.which('ps'); if (!ps) return [];
+  const rows = Bun.spawnSync({ cmd: [ps, '-l'], windowsHide: true, stdout: 'pipe', stderr: 'ignore' }).stdout.toString().split(/\r?\n/)
+    .map((line) => /^[^\d]*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s/.exec(line)).filter((m): m is RegExpExecArray => m !== null)
+    .map((m) => ({ pid: Number(m[1]), ppid: Number(m[2]), winpid: Number(m[4]) }));
+  const top = rows.find((r) => r.winpid === winpid); if (!top) return [];
+  const out: number[] = []; const frontier = [top.pid]; const seen = new Set([top.pid]);
+  while (frontier.length) { const parent = frontier.pop()!; for (const r of rows) if (r.ppid === parent && !seen.has(r.pid)) { seen.add(r.pid); out.push(r.winpid); frontier.push(r.pid); } }
+  return out;
+}
+
+/** The processes descended from `root` in a snapshot: a child must have started after its parent (Windows reuses the
+ *  pid of a dead parent, and a newer process under that pid is no ancestor). */
+export function descendantsOf(root: number, procs: WinProcess[]): WinProcess[] {
+  const byPid = new Map(procs.map((p) => [p.pid, p]));
+  const out: WinProcess[] = []; const frontier = [root]; const seen = new Set<number>([root]);
+  while (frontier.length) {
+    const parent = frontier.pop()!; const at = byPid.get(parent)?.created ?? '0';
+    for (const p of procs) if (p.parent === parent && !seen.has(p.pid) && BigInt(p.created || '0') >= BigInt(at || '0')) { seen.add(p.pid); out.push(p); frontier.push(p.pid); }
+  }
+  return out;
+}
+
 /** 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);
+  // Windows has no pgrep and no signal a process can catch: taskkill ends the pid and its whole tree
+  if (process.platform === 'win32') { Bun.spawnSync({ cmd: ['taskkill', '/PID', String(pid), '/T', '/F'], windowsHide: true, stdout: 'ignore', stderr: 'ignore' }); return; }
+  const children = Bun.spawnSync({ cmd: ['pgrep', '-P', String(pid)], windowsHide: true }).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 */ }
 }

package/src/journeys/tutorials.test.ts

@@ -24,14 +24,27 @@ for (const file of pages) {
     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);
+      const { needsIssuer, startIssuer } = await import('../../../../scripts/issuer-stack.ts');
+      let hosted: Awaited<ReturnType<typeof startHostedStack>> | null = null;
+      let issuer: Awaited<ReturnType<typeof startIssuer>> | null = null;
       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
+      // TUTORIAL_TRACE=1 prints each step as it finishes: what a failed shell cleanup would otherwise take with it
+      const trace = process.env.TUTORIAL_TRACE ? (r: { step: { kind: string; line: number; command?: string; path?: string }; output: string; missing: string[]; exit: number | null }) => console.error(`── line ${r.step.line} ${r.step.command ?? r.step.path} → exit ${r.exit}${r.missing.length ? `, missing: ${r.missing.join(' | ')}` : ''}\n${r.output.trim().slice(-1500)}`) : undefined;
+      try {
+        // a page about the hosted product runs against the hosted stack — the rehearsal's, stood up for the page (scripts/hosted-stack.ts)
+        if (needsHosted(readFileSync(file, 'utf8'))) { hosted = await startHostedStack(); Object.assign(app.env, hosted.env); }
+        // a page about self-hosting the platform brings its own identity provider: the values its provider gives back (scripts/issuer-stack.ts)
+        const platformOrigin = needsIssuer(readFileSync(file, 'utf8'));
+        if (platformOrigin) { issuer = await startIssuer(platformOrigin); Object.assign(app.env, issuer.env); }
+        results = await runTutorial(tutorial, app, { stepTimeoutMs: 180_000, ...(trace ? { onStep: trace } : {}) }); completed = true;
+      } finally {
+        // each stack is stopped whatever the other or the page did; a stop's failure is said, never in place of the page's own
+        const stopped = await Promise.allSettled([hosted?.stop(), issuer?.stop()]);
+        for (const s of stopped) if (s.status === 'rejected') { completed = false; console.error(`a stack did not stop: ${String(s.reason)}`); }
+        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/mcp.ts

@@ -0,0 +1,181 @@
+// `volter mcp` (docs/contributing/architecture.md, "The way in is the app's folder"): an MCP server over stdio whose tools
+// are the `volter` command's own verbs. A tool that reads (status, log, diff, branches) asks the SDK; a tool that acts runs
+// the command itself, as a child, so there is one implementation of each verb and an agent gets what a person would.
+// Locally a World is reached with its own token (the command finds it); the platform with the person's token from
+// `volter login`, which only the person can approve, in their browser.
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { World } from './world.ts';
+import { agentPrompt } from './agent-prompt.ts';
+
+/** This command's own entry, beside this module (src/cli.ts in a checkout, dist/src/cli.js when published). */
+const CLI = fileURLToPath(new URL(`./cli${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
+const MAX_OUTPUT = 20_000;
+
+type Ran = { code: number; output: string };
+/** Run `volter <args>` in `dir` to its end (or its timeout), its stdout and stderr together, the tail kept. */
+function volter(args: string[], dir: string, timeoutSeconds = 600): Promise<Ran> {
+  return new Promise((done) => {
+    const child = spawn(process.execPath, [CLI, ...args], { cwd: dir, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    let output = '';
+    const take = (d: Buffer): void => { output += d.toString(); if (output.length > MAX_OUTPUT * 2) output = output.slice(-MAX_OUTPUT); };
+    child.stdout.on('data', take); child.stderr.on('data', take);
+    const timer = setTimeout(() => { output += `\n(stopped after ${timeoutSeconds}s)`; child.kill(); }, timeoutSeconds * 1000);
+    child.on('error', (e) => { clearTimeout(timer); done({ code: 1, output: `${output}${e.message}` }); });
+    child.on('close', (code) => { clearTimeout(timer); done({ code: code ?? 1, output: output.length > MAX_OUTPUT ? `…${output.slice(-MAX_OUTPUT)}` : output }); });
+  });
+}
+
+/** A command that keeps running (the World's view, a sign-in waiting for approval): started once, answered as soon as
+ *  its first lines say what the agent needs, left running for as long as this server runs. */
+const background = new Map<string, ChildProcess>();
+function startBackground(key: string, args: string[], dir: string, ready: RegExp, seconds = 60): Promise<Ran> {
+  background.get(key)?.kill(); background.delete(key);
+  return new Promise((done) => {
+    const child = spawn(process.execPath, [CLI, ...args], { cwd: dir, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    background.set(key, child);
+    let output = ''; let answered = false;
+    const answer = (code: number): void => { if (!answered) { answered = true; clearTimeout(timer); done({ code, output }); } };
+    const take = (d: Buffer): void => { output += d.toString(); if (ready.test(output)) answer(0); };
+    child.stdout!.on('data', take); child.stderr!.on('data', take);
+    child.on('error', (e) => { output += e.message; answer(1); });
+    child.on('close', (code) => { background.delete(key); answer(code ?? 1); });
+    const timer = setTimeout(() => answer(0), seconds * 1000);
+  });
+}
+/** Everything this server left running, ended: a World under a dashboard is brought down through its own command first
+ *  (its state kept, its teardown recorded), then the command itself. */
+function stopAll(): void {
+  for (const [key, child] of background) {
+    if (key.startsWith('view:')) spawnSync(process.execPath, [CLI, 'world', 'down'], { cwd: key.slice('view:'.length), windowsHide: true, stdio: 'ignore', timeout: 60_000 });
+    child.kill();
+  }
+  background.clear();
+}
+for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => { stopAll(); process.exit(0); });
+process.on('exit', stopAll);
+
+const text = (s: string, isError = false) => ({ content: [{ type: 'text' as const, text: s.trim() || '(no output)' }], ...(isError ? { isError: true } : {}) });
+const ran = (r: Ran) => text(r.output, r.code !== 0);
+const asJson = (v: unknown) => text(JSON.stringify(v, null, 2));
+const fail = (e: unknown) => text(e instanceof Error ? e.message : String(e), true);
+
+const INSTRUCTIONS = `Volter World runs an app against twins of the SaaS APIs it calls (Stripe, Slack, GitHub, OpenAI and about a hundred more): the app keeps its real SDKs and code, and every write lands in a World that can be branched, reset and looked at on each vendor's own screens.
+
+Work in the app's folder (each tool takes "dir", defaulting to where this server was started).
+- Set up: world_init detects the vendors from the app's manifests and env names; show the person the list before keeping it. Then world_up.
+- Run the app or its tests inside the World with world_run (never bare against the real vendors).
+- Look: world_log and world_diff say what the app changed at each vendor; world_view starts the dashboard and returns its link for the person.
+- Branch and reset like a database: world_branch, world_checkout, world_reset.
+- Share with a team: platform_login returns a link and a code the PERSON must approve in their browser (you cannot approve it); after they do, remote_link links this World to <org>/<world> on the platform (create: true makes it there from this World's vendors); world_changeset cuts the changes with a message, and world_push sends them.
+The guide: https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md`;
+
+export async function serveMcp(version: string): Promise<void> {
+  const server = new McpServer({ name: 'volter', title: 'Volter World', version }, { instructions: INSTRUCTIONS });
+  const here = (dir?: string): string => resolve(dir ?? process.cwd());
+  const dirArg = { dir: z.string().optional().describe("The app's folder (the World's root). Defaults to where this server was started.") };
+
+  server.registerTool('world_status', {
+    title: 'World status', description: 'The World of the app folder: its branch, whether it is running, each twin\'s URL, its origin (the remote it pushes to) and unpushed changes.',
+    inputSchema: dirArg, annotations: { readOnlyHint: true },
+  }, async ({ dir }) => { try { return asJson(World.open({ root: here(dir) }).status()); } catch (e) { return fail(e); } });
+
+  server.registerTool('world_init', {
+    title: 'Set up a World for the app', description: "Detect the vendors the app calls (from its package manifests and env var names), install their twins when none are installed yet, and write .volter/world.json beside the code. Show the person the detected vendors; pass allowUnknown to keep going when some have no twin yet.",
+    inputSchema: { ...dirArg, name: z.string().optional().describe('The World\'s name (defaults to the folder\'s).'), allowUnknown: z.boolean().optional(), force: z.boolean().optional().describe('Overwrite an existing .volter/world.json.') },
+  }, async ({ dir, name, allowUnknown, force }) => ran(await volter(['world', 'init', '--install', ...(name ? ['--name', name] : []), ...(allowUnknown ? ['--allow-unknown'] : []), ...(force ? ['--force'] : [])], here(dir))));
+
+  server.registerTool('world_up', {
+    title: 'Start the World', description: 'Start the twins on the current branch. A fresh branch loads its default data (the story); a stopped one resumes where it was.',
+    inputSchema: { ...dirArg, seed: z.boolean().optional().describe('Load the default data on a fresh branch (default true).') },
+  }, async ({ dir, seed }) => ran(await volter(['world', 'up', ...(seed === false ? ['--no-seed'] : [])], here(dir))));
+
+  server.registerTool('world_run', {
+    title: 'Run a command in the World', description: "Run the app or its tests inside the World: the vendors' hosts go to their twins, so the real SDKs work unchanged. Returns the command's exit code and the tail of its output.",
+    inputSchema: { ...dirArg, command: z.array(z.string()).min(1).describe('The command and its arguments, e.g. ["npm", "test"].'), timeoutSeconds: z.number().int().positive().max(3600).optional() },
+  }, async ({ dir, command, timeoutSeconds }) => { const r = await volter(['world', 'run', '--', ...command], here(dir), timeoutSeconds ?? 600); return text(`exit ${r.code}\n${r.output}`, r.code !== 0); });
+
+  server.registerTool('world_down', {
+    title: 'Stop the World', description: 'Stop the twins. Their state is kept for the next world_up unless purge is true.',
+    inputSchema: { ...dirArg, purge: z.boolean().optional() }, annotations: { destructiveHint: true },
+  }, async ({ dir, purge }) => ran(await volter(['world', 'down', ...(purge ? ['--purge'] : [])], here(dir))));
+
+  server.registerTool('world_view', {
+    title: 'Open the dashboard', description: "Run the World with its dashboard on this machine (each vendor's own screens, the calls, the changes, the branches) and return its link for the person. The dashboard runs the World itself: a World already started with world_up is stopped first (its state is kept) and comes back under the dashboard. It keeps running while this server does; world_run works against it meanwhile.",
+    inputSchema: dirArg,
+  }, async ({ dir }) => {
+    const root = here(dir);
+    let before = '';
+    try { const s = World.open({ root }).status(); if (s.running && !s.served) { const down = await volter(['world', 'down'], root); if (down.code !== 0) return ran(down); before = `${down.output.trim()} (state kept; the dashboard runs it now)\n`; } } catch (e) { return fail(e); }
+    const r = await startBackground(`view:${root}`, ['world', 'view', '--no-open'], root, /console\s+\S+/);
+    return text(`${before}${r.output}`, r.code !== 0);
+  });
+
+  server.registerTool('world_log', {
+    title: 'What the app changed', description: 'Every write the app made in this World, newest last: vendor, operation and subject.',
+    inputSchema: { ...dirArg, limit: z.number().int().positive().max(1000).optional().describe('The newest this many (default 50).') }, annotations: { readOnlyHint: true },
+  }, async ({ dir, limit }) => { try { const rows = World.open({ root: here(dir) }).log(); return asJson(rows.slice(-(limit ?? 50)).map((r) => ({ vendor: r.service, operation: r.operation ?? r.op, subject: r.subject, ...(r.receipt ? { receipt: r.receipt } : {}) }))); } catch (e) { return fail(e); } });
+
+  server.registerTool('world_diff', {
+    title: 'Changes since the default data', description: 'How many changes each vendor has since the default data (or the last mark).',
+    inputSchema: dirArg, annotations: { readOnlyHint: true },
+  }, async ({ dir }) => { try { const d = World.open({ root: here(dir) }).diff(); return asJson({ base: d.base, vendors: d.vendors }); } catch (e) { return fail(e); } });
+
+  server.registerTool('world_branch', {
+    title: 'List or make branches', description: 'Without a name, the branches (the checked-out one first). With a name, make a branch from here and check it out, like a database branch: try something, then check out the old one or reset.',
+    inputSchema: { ...dirArg, name: z.string().optional() },
+  }, async ({ dir, name }) => {
+    if (name) return ran(await volter(['world', 'branch', name], here(dir)));
+    try { const w = World.open({ root: here(dir) }); return asJson({ current: w.name, branches: w.branches() }); } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('world_checkout', {
+    title: 'Switch branch', description: 'Check out another branch of the World.',
+    inputSchema: { ...dirArg, name: z.string() },
+  }, async ({ dir, name }) => ran(await volter(['world', 'checkout', name], here(dir))));
+
+  server.registerTool('world_reset', {
+    title: 'Back to the default data', description: "Discard the current branch's changes and load its default data again.",
+    inputSchema: dirArg, annotations: { destructiveHint: true },
+  }, async ({ dir }) => ran(await volter(['world', 'reset'], here(dir))));
+
+  server.registerTool('platform_login', {
+    title: 'Sign in to a platform', description: 'Start signing this machine\'s `volter` command in to a Volter World platform. Returns a link and a code: give both to the PERSON, who approves it in their browser (you cannot). The sign-in completes by itself once they do; check with platform_whoami.',
+    inputSchema: { url: z.string().url().describe("The platform's address (https://…), as the person gave it") },
+  }, async ({ url }) => ran(await startBackground('login', ['login', url, '--no-open'], process.cwd(), /code\s+[A-Z]{4}-[A-Z]{4}/, 30)));
+
+  server.registerTool('platform_whoami', {
+    title: 'Who the command is signed in as', description: 'The platform this machine\'s `volter` command is signed in to, as whom, and their orgs.',
+    inputSchema: {}, annotations: { readOnlyHint: true },
+  }, async () => ran(await volter(['whoami'], process.cwd())));
+
+  server.registerTool('remote_link', {
+    title: 'Link the World to the platform', description: "Link this World to <org>/<world> on the platform the command is signed in to, as the remote it pushes to. create: true makes that World on the platform from this World's vendors when it does not exist.",
+    inputSchema: { ...dirArg, target: z.string().regex(/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/).describe('<org>/<world>'), name: z.string().optional().describe('The remote\'s name (default origin).'), create: z.boolean().optional() },
+  }, async ({ dir, target, name, create }) => ran(await volter(['remote', 'add', name ?? 'origin', target, ...(create ? ['--create'] : [])], here(dir))));
+
+  server.registerTool('world_changeset', {
+    title: 'Cut a changeset', description: "Cut the World's unpushed changes into a reviewable changeset, with a message saying what and why; world_push sends it.",
+    inputSchema: { ...dirArg, message: z.string().min(1).describe('What the changes are and why.'), name: z.string().optional() },
+  }, async ({ dir, message, name }) => ran(await volter(['world', 'changeset', ...(name ? [name] : []), '-m', message], here(dir))));
+
+  server.registerTool('world_push', {
+    title: 'Push to the remote', description: "Send this World's unpushed changes to its remote (the platform's World after remote_link); the remote answers with a receipt for each change.",
+    inputSchema: { ...dirArg, changeset: z.string().optional().describe('Push one changeset by name; default all unpushed.') },
+  }, async ({ dir, changeset }) => ran(await volter(['world', 'push', ...(changeset ? [changeset] : [])], here(dir))));
+
+  server.registerPrompt('get-started', {
+    title: 'Set up Volter World for this app', description: 'Walks through setting up a World for the app in this folder, running its tests in it, and optionally sharing it on a platform.',
+    argsSchema: { platform: z.string().optional().describe("A platform to share the World on: its address"), world: z.string().optional().describe('<org>/<world> on that platform') },
+  }, ({ platform, world }) => ({ messages: [{ role: 'user', content: { type: 'text', text: agentPrompt({ ...(platform ? { platform } : {}), ...(world ? { world } : {}), tools: true }) } }] }));
+
+  // the client closing the connection (its stdin ends) ends this server, and the commands it left running with it
+  const stop = (): void => { stopAll(); process.exit(0); };
+  server.server.onclose = stop;
+  process.stdin.on('end', stop);
+  await server.connect(new StdioServerTransport());
+}

package/src/update-notice.ts

@@ -0,0 +1,44 @@
+// The update notice (docs/contributing/architecture.md, "The way in is the app's folder"): at most once a day the command
+// asks the npm registry for @volter/world's latest version, while it does its own work, and says in one line on stderr
+// when a newer one exists. Never in CI, never for --json, never when the person opted out (VOLTER_NO_UPDATE_NOTIFIER=1):
+// then nothing is asked at all. The answer is kept beside the credentials, so a day's commands ask once.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { credentialsPath } from './credentials.ts';
+
+const DAY = 86_400_000;
+const REGISTRY = 'https://registry.npmjs.org/@volter/world/latest';
+
+type Checked = { checkedAt: string; latest: string | null };
+
+/** This package's version, read from its own package.json. */
+export function currentVersion(): string {
+  try { return (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version?: string }).version ?? '0.0.0'; } catch { return '0.0.0'; }
+}
+
+/** Whether `a` is a newer release than `b` (major.minor.patch; a prerelease is not offered). */
+export function newer(a: string, b: string): boolean {
+  const parse = (v: string): number[] | null => (/^\d+\.\d+\.\d+$/.test(v) ? v.split('.').map(Number) : null);
+  const x = parse(a); const y = parse(b); if (!x || !y) return false;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i]! > y[i]!;
+  return false;
+}
+
+/** Start the day's check if one is due, while the command runs; the returned function, called when the command is
+ *  done, waits a moment at most for it and prints the notice when there is one. Off, it does nothing and asks nothing. */
+export function startUpdateCheck(args: string[], env: NodeJS.ProcessEnv = process.env): () => Promise<void> {
+  if (env.VOLTER_NO_UPDATE_NOTIFIER || env.CI || args.includes('--json') || !process.stderr.isTTY) return async () => undefined;
+  const path = join(dirname(credentialsPath()), 'update-check.json');
+  let kept: Checked | null = null;
+  try { if (existsSync(path)) kept = JSON.parse(readFileSync(path, 'utf8')) as Checked; } catch { kept = null; }
+  const due = !kept || Date.now() - Date.parse(kept.checkedAt) > DAY;
+  const check: Promise<string | null> = due
+    ? fetch(REGISTRY, { signal: AbortSignal.timeout(1500) }).then(async (r) => (r.ok ? ((await r.json()) as { version?: string }).version ?? null : null)).catch(() => null)
+        .then((latest) => { try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify({ checkedAt: new Date().toISOString(), latest } satisfies Checked)}\n`); } catch { /* a read-only home only loses the cache */ } return latest; })
+    : Promise.resolve(kept?.latest ?? null);
+  return async () => {
+    const latest = await Promise.race([check, new Promise<null>((r) => setTimeout(() => r(null), 800))]);
+    const here = currentVersion();
+    if (latest && newer(latest, here)) process.stderr.write(`\nvolter ${latest} is out (you have ${here}): npm install -g @volter/world\n`);
+  };
+}

package/src/world.ts

@@ -8,7 +8,7 @@ import clockForm from '@volter/world-core/world-clock';
 import {
   activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld,
   statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin,
-  deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, findInstalledPackage, type ServedWorld, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom,
+  deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, type ServedWorld, type ViewConsole, type WorldView, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom,
   type DeployTwinOutcome, type MaterializedRoot,
   type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance, materializeRoots } from '@volter/world-runtime';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -108,7 +108,7 @@ export class World {
     if (opts.install !== false && !twins.every((t) => findInstalledPackage(dir, `@volter/twin-${t}`))) {
       // the runtime's own installer: bun under Bun, npm under Node — never assumed
       const cmd = typeof Bun !== 'undefined' ? ['bun', 'add', '-d'] : ['npm', 'install', '--save-dev'];
-      const r = spawnSync(cmd[0]!, [...cmd.slice(1), ...twins.map((t) => `@volter/twin-${t}`)], { cwd: dir, stdio: 'inherit' });
+      const r = spawnSync(cmd[0]!, [...cmd.slice(1), ...twins.map((t) => `@volter/twin-${t}`)], { windowsHide: true, cwd: dir, stdio: 'inherit' });
       if (r.status !== 0) throw new Error(`installing the twins failed (${cmd.join(' ')} exited ${r.status})`);
     }
     const name = served.split('/')[1]!;
@@ -329,8 +329,15 @@ export class World {
   // ── serving ─────────────────────────────────────────────────────────────────────────────
   /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
   serve(opts: { port?: number; host?: string; consolePort?: number; announce?: (info: { name: string; base: string; token: string; readToken: string; console: string | null }) => void } = {}): Promise<ServedWorld> { return serveWorld(this.name, { root: this.root, ...opts }); }
+  /** `volter world view`: this World, its mirrors, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
+  view(opts: { port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; origins?: boolean } = {}): Promise<WorldView> { return serveWorldView(this.name, { root: this.root, ...opts }); }
 
   // ── remotes ─────────────────────────────────────────────────────────────────────────────
+  /** The vendors this world has a twin of, as world.json names them (a twin service's package, else its id). */
+  vendors(): string[] {
+    const { config } = loadWorldConfig(this.configRef(), this.root);
+    return [...new Set(config.services.filter((s) => (s.type ?? 'twin') === 'twin').map((s) => /^@volter\/twin-(.+)$/.exec(s.package ?? '')?.[1] ?? s.id))].sort();
+  }
   /** The remotes named in world.json (`volter remote add`), name → url or path. */
   remotes(): Record<string, string> { return { ...(loadWorldConfig(this.configRef(), this.root).config.remotes ?? {}) }; }
   /** Name a remote; `origin` is the one fetch and push use by default. A token given is remembered for it. */