@volter/world-runtime 2.0.1 → 2.0.3

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.3",
   "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.3"
   },
   "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.1",
+    "@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

@@ -831,6 +831,25 @@ export function planWorldInit(name: string, repoPath: string, options: InitOptio
   const mintedEnv: string[] = [];
   const infraSignals = new Map<string, string[]>();
   const infraEntries: Array<{ name: string; source: string; kind: string }> = [];
+  // SMTP's host and port under the names this app declares: apps name them their own way (twenty's EMAIL_SMTP_HOST/
+  // EMAIL_SMTP_PORT beside nodemailer's SMTP_HOST), and a raw-TCP twin is reached only through the env the app reads,
+  // so every declared `…SMTP_HOST` / `…SMTP_PORT` points at the smtp twin (twenty lane: its mail went to the log). A World
+  // regenerated with --force keeps its saved smtp service as it was: remove it from the config to pick these names up
+  const smtp = services.find((service) => service.id === 'smtp' && service.type === 'twin');
+  if (smtp) {
+    const templates = { ...(smtp.injectEnvTemplates ?? {}) };
+    // not the app's outbound mail: a server it listens on (INBOUND_) or a local catcher it runs (MAILHOG_, MAILPIT_)
+    const notOutbound = /^(?:INBOUND|INCOMING|MAILHOG|MAILPIT|MAILCATCHER|MAILDEV)_/;
+    for (const { name } of repoEnvEntries(repo)) {
+      if (name in templates || notOutbound.test(name)) continue;
+      if (/^(?:[A-Z0-9]+_)*SMTP_HOST$/.test(name)) templates[name] = '${host}';
+      else if (/^(?:[A-Z0-9]+_)*SMTP_PORT$/.test(name)) templates[name] = '${port}';
+      // the twin speaks plain SMTP on its port: a secure/TLS flag beside an injected host would make the app open
+      // implicit TLS to it and fail, so the flag says plain
+      else if (/^(?:[A-Z0-9]+_)*SMTP_(?:SECURE|TLS|SSL)$/.test(name)) templates[name] = 'false';
+    }
+    smtp.injectEnvTemplates = templates;
+  }
   // Every name a twin service above injects at boot (its endpoint env and templates).
   const worldInjected = new Set([
     ...(existing?.services ?? []),
@@ -1164,6 +1183,9 @@ current
 *.env
 credentials/
 token
+token.read
+sessions.json
+keys.json
 `;
 
 export function writeWorldInit(plan: InitPlan, options: { force?: boolean } = {}): void {