@volter/world-runtime 2.0.1 → 2.0.2

package/dist/src/service-recorder.js

@@ -59,7 +59,7 @@ const record = (entry, then) => {
     process.stdout.write(`${logEnd().atLineStart ? '' : '\n'}${line}`, () => then?.());
 };
 const started = Date.now();
-const child = spawn(command, args, { stdio: 'inherit', env });
+const child = spawn(command, args, { windowsHide: true, stdio: 'inherit', env });
 if (child.pid !== undefined)
     record({ event: 'world.service.started', pid: child.pid, parentPid: process.pid });
 /** The log's last `bytes` (from a line start) as the rotation `<log>.1`: however far a runaway writer overshot the cap,

package/dist/src/storage-capacity.js

@@ -16,7 +16,7 @@ export function storagePoolResolver(onFailure) {
             let pool;
             if (process.platform === 'darwin') {
                 stage = 'volume lookup';
-                const df = execFileSync('/bin/df', ['-P', root], { encoding: 'utf8', timeout: 3000, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'] });
+                const df = execFileSync('/bin/df', ['-P', root], { windowsHide: true, encoding: 'utf8', timeout: 3000, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'] });
                 const disk = df.trim().split('\n').at(-1)?.trim().split(/\s+/)[0];
                 if (disk && /^\/dev\/disk\d+(?:s\d+)*$/.test(disk)) {
                     stage = 'volume metadata';
@@ -51,7 +51,7 @@ export function storagePoolResolver(onFailure) {
     };
 }
 function diskInfo(disk) {
-    return execFileSync('/usr/sbin/diskutil', ['info', '-plist', disk], {
+    return execFileSync('/usr/sbin/diskutil', ['info', '-plist', disk], { windowsHide: true,
         encoding: 'utf8', timeout: 3000, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'],
     });
 }

package/dist/src/up-task.js

@@ -8,7 +8,7 @@ import { siblingScript } from "./sibling.js";
  *  is not the caller's to keep, so the boot completes and its outcome is written to the lifecycle log. */
 export function superviseWorldUp(configId, options) {
     return new Promise((done, reject) => {
-        const child = spawn(process.execPath, [siblingScript(import.meta.url, 'up-task-worker')], {
+        const child = spawn(process.execPath, [siblingScript(import.meta.url, 'up-task-worker')], { windowsHide: true,
             cwd: process.cwd(), env: process.env, detached: process.platform !== 'win32',
             stdio: ['ignore', 'inherit', 'inherit', 'ipc'], serialization: 'json',
         });

package/dist/src/world-origins.d.ts

@@ -0,0 +1,13 @@
+export declare const LOCAL_ORIGIN_BASE = "localhost";
+/** The origin a browser reaches `served` at on a local host listening on `port`, or null when its
+ *  names make no label. */
+export declare function localWorldOrigin(served: string, port: number, base?: string): string | null;
+/** Which World a request's host names: undefined for a host that is not a World's origin (the host's
+ *  own, path-addressed), null for a World-origin-shaped host naming no World served here. */
+export declare function worldOfHost(hostname: string, served: Iterable<string>, base?: string): string | null | undefined;
+/** Whether a path under the console's base is a door of a World served here: a World whose org shares the console's
+ *  name (`console/<world>`) has its doors at `/-/console/<world>/…`, and they are the World's, never the console's. */
+export declare function worldDoorUnderConsole(path: string, served: (name: string) => boolean, consoleBase: string): boolean;
+/** Whether a path on a World's origin belongs to that World (its wire, its doors, its mirrors) or to
+ *  what every origin carries (`/-/ping`, the console): a World's origin serves no other World. */
+export declare function pathOfWorld(path: string, served: string, consoleBase: string): boolean;

package/dist/src/world-origins.js

@@ -0,0 +1,37 @@
+// WORLD ORIGINS for a local host (docs/contributing/architecture.md, "Viewing a World"): each World a
+// browser steps into is reached at an origin of its own, `http://<world>--<org>.localhost:<port>`, so no
+// World's page shares an origin with another World's session. Browsers and curl resolve `*.localhost`
+// to loopback. Callers that present a token keep path addressing on the host's own origin.
+import { worldOriginLabel } from "./served-world.js";
+export const LOCAL_ORIGIN_BASE = 'localhost';
+/** The origin a browser reaches `served` at on a local host listening on `port`, or null when its
+ *  names make no label. */
+export function localWorldOrigin(served, port, base = LOCAL_ORIGIN_BASE) {
+    const label = worldOriginLabel(served);
+    return label ? `http://${label}.${base}:${port}` : null;
+}
+/** Which World a request's host names: undefined for a host that is not a World's origin (the host's
+ *  own, path-addressed), null for a World-origin-shaped host naming no World served here. */
+export function worldOfHost(hostname, served, base = LOCAL_ORIGIN_BASE) {
+    const suffix = `.${base}`;
+    if (!hostname.endsWith(suffix))
+        return undefined;
+    const label = hostname.slice(0, -suffix.length);
+    for (const name of served)
+        if (worldOriginLabel(name) === label)
+            return name;
+    return null;
+}
+/** Whether a path under the console's base is a door of a World served here: a World whose org shares the console's
+ *  name (`console/<world>`) has its doors at `/-/console/<world>/…`, and they are the World's, never the console's. */
+export function worldDoorUnderConsole(path, served, consoleBase) {
+    if (path !== consoleBase && !path.startsWith(`${consoleBase}/`))
+        return false;
+    const m = /^\/-\/([^/]+)\/([^/]+)/.exec(path);
+    return Boolean(m && served(`${m[1]}/${m[2]}`));
+}
+/** Whether a path on a World's origin belongs to that World (its wire, its doors, its mirrors) or to
+ *  what every origin carries (`/-/ping`, the console): a World's origin serves no other World. */
+export function pathOfWorld(path, served, consoleBase) {
+    return path === '/-/ping' || path === consoleBase || path.startsWith(`${consoleBase}/`) || path.startsWith(`/${served}/`) || path.startsWith(`/-/${served}/`) || path === `/${served}` || path === `/-/${served}`;
+}

package/dist/src/world-view.d.ts

@@ -0,0 +1,25 @@
+/** A console as a host mounts it (`@volter/world-console`): answer a request under `base`, or null. */
+export type ViewConsole = {
+    handle: (request: Request, base: string, opts?: {
+        worldOrigin?: boolean;
+    }) => Promise<Response | null>;
+};
+export declare const VIEW_CONSOLE_BASE = "/-/console";
+export type WorldView = {
+    url: string;
+    base: string;
+    served: string;
+    token: string;
+    readToken: string;
+    console: string | null; /** the World's own browser origin, when it has one */
+    origin: string | null;
+    stop: () => Promise<void>;
+};
+export declare function serveWorldView(name: string, opts?: {
+    root?: string;
+    port?: number;
+    host?: string;
+    console?: ViewConsole;
+    announce?: (line: string) => void; /** each World a browser steps into at an origin of its own (on by default on loopback) */
+    origins?: boolean;
+}): Promise<WorldView>;

package/dist/src/world-view.js

@@ -0,0 +1,110 @@
+// THE LOCAL VIEW: one World served for a person to step into — its doors, its mirrors, its branches
+// ("as of" views) and the console, on one origin (docs/contributing/architecture.md, "Viewing a
+// World"). `volter world view` is this; the runtime's `up` gains no step. A host that serves many
+// Worlds (world-host) answers the same doors; this serves one, and the branches made of it.
+import { existsSync, readdirSync } from 'node:fs';
+import { loadWorldConfig } from "./configs.js";
+import { join, resolve } from 'node:path';
+import { serveHttp, stateDirName } from '@volter/world-core';
+import { LocalBranches } from "./local-branches.js";
+import { mountWorld } from "./served-world.js";
+import { localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
+export const VIEW_CONSOLE_BASE = '/-/console';
+/** The branch Worlds already under `dir` (`<dir>/<org>/<world>/.volter/world.json`). */
+function branchRoots(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const org of readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory())) {
+        for (const world of readdirSync(join(dir, org.name), { withFileTypes: true }).filter((e) => e.isDirectory())) {
+            const root = join(dir, org.name, world.name);
+            if (existsSync(join(root, stateDirName(), 'world.json')))
+                out.push(root);
+        }
+    }
+    return out.sort();
+}
+export async function serveWorldView(name, opts = {}) {
+    const root = resolve(opts.root ?? process.cwd());
+    const host = opts.host ?? '127.0.0.1';
+    const worlds = new Map();
+    let loopback = '';
+    let port = 0;
+    const loopbackBind = host === '127.0.0.1' || host === 'localhost' || host === '::1';
+    // each World's browser session on an origin of its own, where the view listens on loopback (*.localhost)
+    const origins = opts.origins ?? loopbackBind;
+    // bound to loopback with an origin per World, the view is for the person at this machine: its pages need no token
+    // (served-world.ts localSession). Without origins every World's pages share one, and none is handed a session.
+    const local = loopbackBind && origins;
+    // a non-loopback --host turns origins off by default: say so (the World and its branches then share one origin)
+    if (opts.origins === undefined && !origins)
+        opts.announce?.(`origins  off (bound to ${host}): the World and its branches share one origin, where a browser session is only path-scoped; bind loopback for an origin per World`);
+    const browserOrigin = origins ? (served) => (port ? localWorldOrigin(served, port) : null) : undefined;
+    const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
+    const branches = new LocalBranches({ dir: join(root, stateDirName(), 'branches'), origin: () => loopback, worlds, mount: mountAt, ...(opts.announce ? { announce: opts.announce } : {}) });
+    const world = await mountWorld(name, { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(local ? { localTrust: true } : {}) });
+    worlds.set(world.served, world);
+    const server = await serveHttp({
+        // a pushed blob (a release video) is one PUT: bodies up to 1 GiB, as `serve` takes them
+        hostname: host, port: opts.port ?? 0, maxRequestBodySize: 1024 * 1024 * 1024,
+        // this front serves a World and its branches; each World's own twins journal their requests
+        twinRequestJournal: false,
+        async fetch(request) {
+            const at = new URL(request.url);
+            const path = at.pathname;
+            // a World's own origin serves that World (and the ping and the console) and no other
+            const own = origins ? worldOfHost(at.hostname, worlds.keys()) : undefined;
+            if (own === null)
+                return Response.json({ error: `no world at ${at.host}` }, { status: 404 });
+            // the bare address, typed into a browser, is the World's page: at its own origin when it has one
+            if (opts.console && path === '/' && request.method === 'GET' && (request.headers.get('accept') ?? '').includes('text/html')) {
+                const served = own ?? world.served;
+                const page = `${VIEW_CONSOLE_BASE}/${served}`;
+                return Response.redirect(own ? `${at.origin}${page}` : `${browserOrigin?.(served) ?? at.origin}${page}`, 302);
+            }
+            if (own && !pathOfWorld(path, own, VIEW_CONSOLE_BASE))
+                return Response.json({ error: `this origin serves ${own} only` }, { status: 404 });
+            if (path === '/-/ping')
+                return Response.json({ ok: true, worlds: own ? [own] : [...worlds.keys()], ...(opts.console ? { console: `${VIEW_CONSOLE_BASE}/` } : {}) });
+            if (opts.console && (path === VIEW_CONSOLE_BASE || path.startsWith(`${VIEW_CONSOLE_BASE}/`)) && !worldDoorUnderConsole(path, (n) => worlds.has(n), VIEW_CONSOLE_BASE)) {
+                // on a World's own origin the console keeps no token script can read (its session is the credential)
+                const answered = await opts.console.handle(request, VIEW_CONSOLE_BASE, own ? { worldOrigin: true } : undefined);
+                if (answered)
+                    return answered;
+            }
+            const m = /^\/(?:-\/)?([^/]+)\/([^/]+)/.exec(path);
+            const target = m ? worlds.get(`${m[1]}/${m[2]}`) : undefined;
+            if (!target)
+                return Response.json({ error: `no world at ${path}: this view serves ${[...worlds.keys()].join(', ')}` }, { status: 404 });
+            return target.handle(request);
+        },
+    });
+    port = server.port ?? 0;
+    const url = `http://${host}:${server.port}`;
+    loopback = `http://${host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host}:${server.port}`;
+    // a branch outlives the view that made it until its time runs out: stopping stops its compute only
+    const stop = async () => {
+        branches.stop();
+        await server.stop(true);
+        for (const w of [...worlds.values()].reverse())
+            await w.stop();
+    };
+    try {
+        await world.boot(url);
+        // branches an earlier view made: mounted again (the sweep then removes those whose time ran out)
+        for (const at of branchRoots(join(root, stateDirName(), 'branches'))) {
+            const b = await mountAt(at);
+            await b.boot(url);
+            worlds.set(b.served, b);
+        }
+        await branches.resume();
+    }
+    catch (error) {
+        await stop().catch(() => undefined);
+        throw error;
+    }
+    // the console opens on the World's own origin, where its session lives
+    const consoleUrl = opts.console ? `${browserOrigin?.(world.served) ?? url}${VIEW_CONSOLE_BASE}/${world.served}` : null;
+    opts.announce?.(`viewing  ${world.served}  ${url}/${world.served}${consoleUrl ? `\nconsole  ${consoleUrl}` : ''}`);
+    return { url, base: `${url}/${world.served}`, served: world.served, get token() { return world.token; }, get readToken() { return world.readToken; }, console: consoleUrl, origin: browserOrigin?.(world.served) ?? null, stop };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -67,13 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.1",
-    "@volter/world-console": "2.0.1"
+    "@volter/world-core": "2.0.2",
+    "@volter/world-console": "2.0.2"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
-    "@volter/world-core": "2.0.1",
+    "@volter/world-access": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -83,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.1"
+    "@volter/twin-mongodb": "0.1.2"
   }
 }

package/src/app-url.ts

@@ -150,7 +150,7 @@ export function addAppHosts(name: string, hosts: string[], options: { root?: str
 
 /** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
 function listeningTcpPorts(pid: number): number[] {
-  const result = spawnSync('lsof', ['-a', '-p', String(pid), '-iTCP', '-sTCP:LISTEN', '-P', '-n', '-Fn'], { encoding: 'utf8' });
+  const result = spawnSync('lsof', ['-a', '-p', String(pid), '-iTCP', '-sTCP:LISTEN', '-P', '-n', '-Fn'], { windowsHide: true, encoding: 'utf8' });
   if (result.error) {
     throw new Error(`volter-world app-url: \`lsof\` is unavailable (${result.error.message}) — pass the port, or --set the URL directly`);
   }

package/src/catalog.ts

@@ -115,7 +115,7 @@ export function checkoutCatalog(root: string): Catalog {
     packDir: (vendor) => (isPackDir(join(packsDir, vendor)) ? join(packsDir, vendor) : undefined),
     version: (vendor) => packageVersion(join(packsDir, vendor)),
     sha: () => {
-      const proc = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+      const proc = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { windowsHide: true, encoding: 'utf8' });
       const sha = proc.status === 0 ? proc.stdout.trim() : '';
       return /^[0-9a-f]{40}$/.test(sha) ? sha : 'unknown';
     },

package/src/cli.ts

@@ -860,7 +860,7 @@ async function main(): Promise<void> {
       // VOLTER_WORLD names the World to the injector: a request addressed to its paths carries its key
       const commandEnv: Record<string, string | undefined> = { ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref };
       commandEnv.VOLTER_TWIN_INJECT_QUIET = head.includes('--verbose') ? '0' : commandEnv.VOLTER_TWIN_INJECT_QUIET ?? '1';
-      const child = spawn(command[0]!, command.slice(1), { env: commandEnv, stdio: 'inherit' });
+      const child = spawn(command[0]!, command.slice(1), { windowsHide: true, env: commandEnv, stdio: 'inherit' });
       const code = await new Promise<number>((resolveExit) => { child.on('exit', (status) => resolveExit(status ?? 1)); child.on('error', () => resolveExit(127)); });
       // a client that wrote and exited at once still has bytes on their way through a bridge
       await drainStreams();
@@ -884,7 +884,7 @@ async function main(): Promise<void> {
       const compose = splitDockerComposeArgs(command);
       if (compose) {
         // the consumer's own service names, from its own files, through its own docker
-        const listed = spawnSync(compose.head[0]!, [...compose.head.slice(1), ...compose.composeFlags, 'config', '--services'], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        const listed = spawnSync(compose.head[0]!, [...compose.head.slice(1), ...compose.composeFlags, 'config', '--services'], { windowsHide: true, env, stdio: ['ignore', 'pipe', 'pipe'] });
         if (listed.status !== 0) throw new Error(`volter-world attach --via reflect: docker compose config --services failed:\n${listed.stderr.toString().trim()}`);
         const services = listed.stdout.toString().split('\n').map((s) => s.trim()).filter(Boolean);
         const overridePath = join(instanceDir(attachRoot, resolved.ref), 'reflect-compose.override.yml');
@@ -892,7 +892,7 @@ async function main(): Promise<void> {
         toRun = dockerComposeWithOverride(command, overridePath);
         process.stderr.write(`volter-world attach --via reflect: ${services.length} service(s) attached — dns ${manifest.resolverIp}:53, front ${manifest.targetIp}:443, CA ${ATTACHED_CA_PATH}\n`);
       }
-      const result = spawnSync(toRun[0]!, toRun.slice(1), { env, stdio: 'inherit' });
+      const result = spawnSync(toRun[0]!, toRun.slice(1), { windowsHide: true, env, stdio: 'inherit' });
       process.exit(result.status ?? 1);
     }
     if (via !== 'env') {

package/src/console-apart.ts

@@ -8,7 +8,7 @@
 import { serveHttp, type HttpServer } from '@volter/world-core';
 
 /** What a console offers a host: its shell and assets under `base`, told where the Worlds are served. */
-export type ConsoleMount = { handle: (request: Request, base: string, opts?: { worlds?: string; names?: string[] }) => Promise<Response | null> };
+export type ConsoleMount = { handle: (request: Request, base: string, opts?: { worlds?: string; names?: string[]; worldOrigin?: boolean }) => Promise<Response | null> };
 export const CONSOLE_BASE = '/-/console';
 
 /** Serve `mount` on its own listener; doors under `/-/` go to `upstream` (the Worlds' origin). */
@@ -57,6 +57,9 @@ export async function serveConsoleFor(target: string, opts: { hostname?: string;
     throw error;
   }
   const hostname = opts.hostname ?? '127.0.0.1';
+  // the console's own origin, once it listens: a World that lets only its own origin frame its pages lets this
+  // console frame them too, as they are framed where it serves them itself
+  let consoleOrigin = '';
   const worldsServer = await serveHttp({
     hostname, port: opts.port !== undefined && opts.port !== 0 ? opts.port + 1 : 0, twinRequestJournal: false,
     async fetch(request) {
@@ -71,11 +74,14 @@ export async function serveConsoleFor(target: string, opts: { hostname?: string;
       // the host's own redirects (the session door's, a twin root's to its mirror) stay on this origin
       const location = out.get('location');
       if (location?.startsWith(origin)) out.set('location', `${url.origin}${location.slice(origin.length)}`);
+      const csp = out.get('content-security-policy');
+      if (csp && consoleOrigin) out.set('content-security-policy', csp.replace(/frame-ancestors ([^;]*)/, (_all, allowed: string) => (/'none'/.test(allowed) ? `frame-ancestors ${allowed}` : `frame-ancestors ${allowed} ${consoleOrigin}`)));
       return new Response(answer.body, { status: answer.status, headers: out });
     },
   });
   const worlds = `http://${hostname}:${worldsServer.port}`;
   const consoleServer = await serveConsoleApart(mount, { upstream: origin, worlds, names, hostname, ...(opts.port !== undefined ? { port: opts.port } : {}) });
+  consoleOrigin = new URL(consoleServer.url).origin;
   return { url: consoleServer.url, worlds, servers: [consoleServer.server, worldsServer] };
 }
 

package/src/covers.ts

@@ -602,8 +602,10 @@ function usesOf(signals: Map<string, string[]>): Map<string, Array<{ usage: Worl
 export function detectRepoVendors(repoPath: string): RepoVendorSignals {
   const repo = resolve(repoPath);
   // the platform's own packages — the twins an app installed, the command, the runtime — are
-  // never a vendor signal: an app that installed @volter/twin-slack did not gain a Slack dependency
-  const dependencies = projectDependencies(repo).filter((dep) => !dep.startsWith('@volter/') && !dep.startsWith('pypi:volter'));
+  // never a vendor signal: an app that installed @volter/twin-slack did not gain a Slack dependency.
+  // A Volter package a pack names as its vendor's SDK is one (`@volter/identity`, the Volter identity
+  // service's client, is the volteridentity twin's), as any vendor's SDK is.
+  const dependencies = projectDependencies(repo).filter((dep) => Object.hasOwn(SDK_TWINS, dep) || (!dep.startsWith('@volter/') && !dep.startsWith('pypi:volter')));
   const envNames = projectEnvNames(repo);
   const npmRegistries = projectNpmRegistries(repo);
 

package/src/host-worker.ts

@@ -4,13 +4,14 @@
 // red) without disturbing sibling twins. Posts {type:'ready'} once listening.
 import { parentPort, workerData } from 'node:worker_threads';
 import type { ColocatedTwinSpec } from './host.ts';
+import { importModule } from './import-module.ts';
 
 const spec = workerData as ColocatedTwinSpec;
 
 type TwinServer = { port: number; stop: () => void | Promise<void> };
 type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean }) => TwinServer | Promise<TwinServer>;
 
-const mod = (await import(spec.module)) as Record<string, unknown>;
+const mod = await importModule(spec.module);
 const factory = mod[spec.export] as TwinServerFactory | undefined;
 if (typeof factory !== 'function') {
   throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);

package/src/host.ts

@@ -21,6 +21,7 @@
 // world config that drives it) stays vendor-agnostic — exactly like `bin` spawning.
 import { Worker } from 'node:worker_threads';
 import { siblingScript } from './sibling.ts';
+import { importModule } from './import-module.ts';
 import { pathToFileURL } from 'node:url';
 
 /** One twin to mount in the host. `module`/`export` name a `({port,root,readOnly}) => {port,stop}`
@@ -57,7 +58,7 @@ type TwinServer = { port: number; stop: () => void | Promise<void> };
 type TwinServerFactory = (opts: { port?: number; root?: string; readOnly?: boolean; scenarioPath?: string }) => TwinServer | Promise<TwinServer>;
 
 async function loadFactory(spec: ColocatedTwinSpec): Promise<TwinServerFactory> {
-  const mod = (await import(spec.module)) as Record<string, unknown>;
+  const mod = await importModule(spec.module);
   const factory = mod[spec.export];
   if (typeof factory !== 'function') {
     throw new Error(`Twin "${spec.id}": ${spec.module} has no factory export "${spec.export}"`);

package/src/import-module.ts

@@ -0,0 +1,9 @@
+// import() of what a World names a module by: a package name, a file URL, or a file path. Node's ESM loader takes an
+// absolute path only as a file:// URL — on Windows `C:\…` reads as a URL with the scheme `c:` and is refused
+// (ERR_UNSUPPORTED_ESM_URL_SCHEME); Bun takes either. A path becomes its file URL here; anything else is passed on.
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export function importModule<T = Record<string, unknown>>(specifier: string): Promise<T> {
+  return import(isAbsolute(specifier) ? pathToFileURL(specifier).href : specifier) as Promise<T>;
+}

package/src/index.ts

@@ -163,8 +163,13 @@ export { branchWorld, checkoutWorld } from './branch.ts';
 export type { BranchOptions } from './branch.ts';
 export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.ts';
 export type { DeployTwinOutcome, MaterializedRoot } from './root.ts';
-export { landReceipts, mountWorld, readServeRecord, refreshSchedule, servedName, serveWorld, TOKEN_HEADER, WorldDoors } from './served-world.ts';
-export type { DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
+export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.ts';
+export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
+export { LocalBranches } from './local-branches.ts';
+export { serveWorldView, VIEW_CONSOLE_BASE } from './world-view.ts';
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
+export type { ViewConsole, WorldView } from './world-view.ts';
+export type { LocalBranchesOptions } from './local-branches.ts';
 export type { ServedWorld } from './served-world.ts';
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.ts';
 

package/src/infra-cli.ts

@@ -26,7 +26,7 @@ if (!existsSync(definition)) {
 }
 
 const base = ['compose', '-f', definition];
-const run = (args: string[]) => spawnSync('docker', [...base, ...args], {
+const run = (args: string[]) => spawnSync('docker', [...base, ...args], { windowsHide: true,
   encoding: 'utf8',
   env: { ...process.env, VOLTER_WORLD_DATA: worldData },
   timeout: 120_000,
@@ -60,7 +60,7 @@ function selectBacking(): 'docker' | 'pglite' {
     process.stderr.write(`managed infrastructure: VOLTER_WORLD_INFRA_BACKING must be docker or pglite (got ${JSON.stringify(forced)})\n`);
     process.exit(2);
   }
-  const probe = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { encoding: 'utf8', timeout: 10_000 });
+  const probe = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { windowsHide: true, encoding: 'utf8', timeout: 10_000 });
   if (probe.status === 0) return 'docker';
   // Absence of a container runtime (no binary, no daemon) is a capability
   // difference: swap backings. A PRESENT runtime failing on resources stays

package/src/init.ts

@@ -1164,6 +1164,9 @@ current
 *.env
 credentials/
 token
+token.read
+sessions.json
+keys.json
 `;
 
 export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}): void {

package/src/local-branches.ts

@@ -0,0 +1,173 @@
+// LOCAL BRANCHES: the branches a local host makes of the Worlds it serves (docs/contributing/architecture.md,
+// "Viewing a World"). A branch is another World: the parent's config under a new name, cloned from the
+// parent through its own doors (its history cut at an instant, when one is asked), its clock frozen at
+// that instant so no twin's catch-up walks it forward, and removed when its time runs out. world-host
+// and `volter world view` both make them with this; a hosted World's supervisor makes its own.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDirName, withStateRemoval } from '@volter/world-core';
+import { clockFile } from './runtime.ts';
+import { loadWorldConfig } from './configs.ts';
+import { TOKEN_HEADER, type BranchDoors, type BranchRow, type MountedWorld } from './served-world.ts';
+
+/** What a branch records beside itself: whose branch it is, as of when, and until when. */
+type BranchRecord = { from: string; at: { instant?: string; live?: boolean; label?: string } | null; createdAt: string; expiresAt: string | null };
+const RECORD = 'branch.json';
+const SWEEP_MS = 60_000;
+
+/** A World's manifest under another name, in the manifest's own format: format 2 names a World in
+ *  `metadata.id` and serves it bare at `serving.name`; format 1 in `id` and `bare.name`. */
+function renamed(config: Record<string, unknown>, id: string, name: string): Record<string, unknown> {
+  if (config.schemaVersion === 2) {
+    return { ...config, metadata: { ...(config.metadata as Record<string, unknown> | undefined), id }, serving: { ...(config.serving as Record<string, unknown> | undefined), mode: 'bare', name } };
+  }
+  return { ...config, id, bare: { ...(config.bare as Record<string, unknown> | undefined), name } };
+}
+
+export type LocalBranchesOptions = {
+  /** where branches live: `<dir>/<org>/<world>/` */
+  dir: string;
+  /** the URL a branch reaches its parent at (the host's own listener, on loopback) */
+  origin: () => string;
+  /** the Worlds the host serves, by served name; branches join it while they live */
+  worlds: Map<string, MountedWorld>;
+  /** mount a World at a root, with its branches doors wired */
+  mount: (root: string) => Promise<MountedWorld>;
+  announce?: (line: string) => void;
+};
+
+export class LocalBranches {
+  private sweeper: ReturnType<typeof setInterval> | null = null;
+  constructor(private readonly o: LocalBranchesOptions) {}
+
+  private record(world: MountedWorld): BranchRecord | null {
+    try { return JSON.parse(readFileSync(join(world.root, stateDirName(), RECORD), 'utf8')) as BranchRecord; } catch { return null; }
+  }
+
+  /** The branches of `parent` this host holds. */
+  list(parent: string): BranchRow[] {
+    const rows: BranchRow[] = [];
+    for (const [name, world] of this.o.worlds) {
+      const r = this.record(world);
+      if (r?.from === parent) rows.push({ name, from: r.from, at: r.at, createdAt: r.createdAt, expiresAt: r.expiresAt });
+    }
+    return rows.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  }
+
+  /** Branches being made, by parent: a parent is not removed mid-clone. */
+  private readonly making = new Map<string, number>();
+  hasBranches(parent: string): boolean { return (this.making.get(parent) ?? 0) > 0 || this.list(parent).length > 0; }
+
+  /** A World's branches doors, answered by this host. */
+  doorsFor(parent: string): BranchDoors {
+    return {
+      list: async () => this.list(parent),
+      create: (at, ttl, _origin, parentKey) => this.create(parent, at, ttl, parentKey),
+      remove: async (name) => { const w = this.o.worlds.get(name); if (!w || this.record(w)?.from !== parent) return false; await this.remove(name); return true; },
+    };
+  }
+
+  private async create(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
+    this.making.set(parent, (this.making.get(parent) ?? 0) + 1);
+    try { return await this.make(parent, at, ttlSeconds, parentKey); } finally {
+      const left = (this.making.get(parent) ?? 1) - 1;
+      if (left > 0) this.making.set(parent, left); else this.making.delete(parent);
+    }
+  }
+  private async make(parent: string, at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, parentKey?: string): Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }> {
+    const from = this.o.worlds.get(parent);
+    if (!from) throw new Error(`no world ${parent} here`);
+    const [org, world] = parent.split('/') as [string, string];
+    const stamp = at.instant ? at.instant.replace(/[-:]/g, '').replace(/\.\d+Z$|Z$/, '').toLowerCase().slice(0, 13) : 'now';
+    // a labelled branch (a pull request's preview) is named for its label; the random tail keeps a replacement distinct
+    // a name already taken (a 4-hex tail's rare clash) is passed over for a fresh tail, never made over
+    const free = (): { id: string; name: string; root: string } | null => {
+      for (let tries = 0; tries < 8; tries++) {
+        const suffix = `${at.label ? `-${at.label}` : `-at-${stamp}`}-${Buffer.from(crypto.getRandomValues(new Uint8Array(2))).toString('hex')}`;
+        const id = `${world.slice(0, 64 - suffix.length)}${suffix}`;
+        const name = `${org}/${id}`; const root = join(this.o.dir, org, id);
+        if (!this.o.worlds.has(name) && !existsSync(root)) return { id, name, root };
+      }
+      return null;
+    };
+    const picked = free();
+    if (!picked) throw new Error(`no free name for a branch of ${parent}`);
+    const { id, name, root } = picked;
+    // the parent's config under the branch's own name: the same twins, served at the branch's place
+    mkdirSync(join(root, stateDirName()), { recursive: true });
+    writeFileSync(join(root, stateDirName(), 'world.json'), `${JSON.stringify(renamed(JSON.parse(readFileSync(join(from.root, stateDirName(), 'world.json'), 'utf8')) as Record<string, unknown>, id, name), null, 2)}\n`);
+    let mounted: MountedWorld | undefined;
+    try {
+      mounted = await this.o.mount(root);
+      await mounted.boot(this.o.origin());
+      this.o.worlds.set(name, mounted);
+      const origin = this.o.origin();
+      // each twin's history cut at the instant, by the parent's own history door
+      let views: unknown;
+      if (at.instant) {
+        const cut = await from.handle(new Request(`${origin}/-/${parent}/history?at=${encodeURIComponent(at.instant)}`, { headers: { [TOKEN_HEADER]: from.token } }));
+        if (!cut.ok) throw new Error(`the history of ${parent} at ${at.instant}: ${await cut.text()}`);
+        views = ((await cut.json()) as { views: unknown }).views;
+      }
+      const cloned = await mounted.handle(new Request(`${origin}/-/${name}/origin`, { method: 'PUT', headers: { [TOKEN_HEADER]: mounted.token, 'content-type': 'application/json' }, body: JSON.stringify({ url: `${origin}/${parent}`, token: parentKey ?? from.token, ...(views ? { views } : {}) }) })); // the branch's own key to its parent (the parent's doors make it), never the parent's token
+      if (!cloned.ok) throw new Error(`cloning ${parent}: ${await cloned.text()}`);
+      // the branch's clock stands at its instant, else at the parent's: no twin's catch-up walks it on
+      // (a parent whose clock was never set: the branch's stands at now, frozen there, as http-api says);
+      // a live branch (a pull request's preview) keeps the parent's time: real time, or its simulated clock
+      const clock = at.instant ?? this.frozenClock(from) ?? (at.live ? null : new Date().toISOString());
+      if (clock) { const file = clockFile(root, id); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, `${clock}\n`); }
+      const createdAt = new Date().toISOString();
+      const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
+      writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: at.instant ? { instant: at.instant } : null, createdAt, expiresAt } satisfies BranchRecord, null, 2)}\n`);
+      this.o.announce?.(`branch   ${name}  of ${parent}${at.instant ? ` as of ${at.instant}` : ''}${expiresAt ? `, until ${expiresAt}` : ''}`);
+      return { name, token: mounted.token, readToken: mounted.readToken, expiresAt };
+    } catch (error) {
+      this.o.worlds.delete(name);
+      try { await mounted?.stop(); } catch { /* reported below */ }
+      withStateRemoval(root, () => rmSync(root, { recursive: true, force: true }));
+      throw error;
+    }
+  }
+
+  /** The parent's frozen clock, when it has one. */
+  private frozenClock(world: MountedWorld): string | null {
+    try {
+      const held = readFileSync(clockFile(world.root, loadWorldConfig(join(world.root, stateDirName(), 'world.json'), world.root).config.id), 'utf8').trim();
+      return Number.isNaN(Date.parse(held)) ? null : held;
+    } catch { return null; }
+  }
+
+  /** Stop a branch and remove its World (a branch's own branches first). */
+  async remove(name: string): Promise<void> {
+    const world = this.o.worlds.get(name);
+    if (!world) return;
+    for (const child of this.list(name)) await this.remove(child.name);
+    await world.stop();
+    withStateRemoval(world.root, () => rmSync(world.root, { recursive: true, force: true }));
+    this.o.worlds.delete(name);
+    this.o.announce?.(`removed  ${name}`);
+  }
+
+  /** Remove the branches whose time ran out, now and every minute while the host serves. */
+  async resume(): Promise<void> {
+    await this.sweep();
+    this.sweeper = setInterval(() => { void this.sweep(); }, SWEEP_MS);
+    this.sweeper.unref?.();
+  }
+  /** One sweep at a time: a slow one never overlaps the next. */
+  private sweeping = false;
+  private async sweep(): Promise<void> {
+    if (this.sweeping) return;
+    this.sweeping = true;
+    try {
+      const now = Date.now();
+      for (const [name, world] of [...this.o.worlds]) {
+        const r = this.record(world);
+        if (r?.expiresAt && Date.parse(r.expiresAt) <= now && this.o.worlds.has(name)) {
+          try { await this.remove(name); } catch (error) { this.o.announce?.(`branch   ${name}: removal failed: ${error instanceof Error ? error.message : String(error)}`); }
+        }
+      }
+    } finally { this.sweeping = false; }
+  }
+  stop(): void { if (this.sweeper) clearInterval(this.sweeper); this.sweeper = null; }
+}