@volter/world-runtime 2.0.1 → 2.0.3

package/dist/src/app-url.js

@@ -142,7 +142,7 @@ export function addAppHosts(name, hosts, options = {}) {
 }
 /** The listening TCP ports of a live pid, via lsof (macOS + Linux). */
 function listeningTcpPorts(pid) {
-    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/dist/src/catalog.js

@@ -110,7 +110,7 @@ export function checkoutCatalog(root) {
         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/dist/src/cli.js

@@ -981,7 +981,7 @@ async function main() {
             // VOLTER_WORLD names the World to the injector: a request addressed to its paths carries its key
             const commandEnv = { ...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((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();
@@ -1007,7 +1007,7 @@ async function main() {
             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);
@@ -1016,7 +1016,7 @@ async function main() {
                 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/dist/src/console-apart.d.ts

@@ -4,6 +4,7 @@ export type ConsoleMount = {
     handle: (request: Request, base: string, opts?: {
         worlds?: string;
         names?: string[];
+        worldOrigin?: boolean;
     }) => Promise<Response | null>;
 };
 export declare const CONSOLE_BASE = "/-/console";

package/dist/src/console-apart.js

@@ -67,6 +67,9 @@ export async function serveConsoleFor(target, opts = {}) {
         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) {
@@ -87,11 +90,15 @@ export async function serveConsoleFor(target, opts = {}) {
             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) => (/'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] };
 }
 /** The host's old console address (`/-/console/…`, a bookmark or a portal's link) sent on to the console's

package/dist/src/covers.js

@@ -450,8 +450,10 @@ function usesOf(signals) {
 export function detectRepoVendors(repoPath) {
     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);
     // vendor → detection sources

package/dist/src/host-worker.js

@@ -1,18 +1,11 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 // Worker entry for 'worker' isolation: one Worker thread per twin. It owns its event
 // loop + heap, so a CPU hog / leak / hard crash here is contained to this thread — the
 // host does NOT restart it: it gives up on the worker (fires a `gaveup` event → doctor
 // red) without disturbing sibling twins. Posts {type:'ready'} once listening.
 import { parentPort, workerData } from 'node:worker_threads';
+import { importModule } from "./import-module.js";
 const spec = workerData;
-const mod = (await import(__rewriteRelativeImportExtension(spec.module)));
+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/dist/src/host.js

@@ -1,11 +1,3 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 // Co-located twin host — run many twins in ONE process instead of one OS process
 // per twin. The twin core is a pure, transport-agnostic handler (see a pack's
 // `handle<Vendor>TwinRequest`), so nothing requires a process per twin; this host
@@ -29,9 +21,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // world config that drives it) stays vendor-agnostic — exactly like `bin` spawning.
 import { Worker } from 'node:worker_threads';
 import { siblingScript } from "./sibling.js";
+import { importModule } from "./import-module.js";
 import { pathToFileURL } from 'node:url';
 async function loadFactory(spec) {
-    const mod = (await import(__rewriteRelativeImportExtension(spec.module)));
+    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/dist/src/import-module.d.ts

@@ -0,0 +1 @@
+export declare function importModule<T = Record<string, unknown>>(specifier: string): Promise<T>;

package/dist/src/import-module.js

@@ -0,0 +1,16 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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(specifier) {
+    return import(__rewriteRelativeImportExtension(isAbsolute(specifier) ? pathToFileURL(specifier).href : specifier));
+}

package/dist/src/index.d.ts

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

package/dist/src/index.js

@@ -30,6 +30,9 @@ export { resetWorld, seedEntryFor, seedWorld } from "./placeholder.js";
 export { fetchFromOrigin, worldOrigin } from "./origin.js";
 export { branchWorld, checkoutWorld } from "./branch.js";
 export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
-export { landReceipts, mountWorld, readServeRecord, refreshSchedule, servedName, serveWorld, TOKEN_HEADER, WorldDoors } from "./served-world.js";
+export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from "./served-world.js";
+export { LocalBranches } from "./local-branches.js";
+export { serveWorldView, VIEW_CONSOLE_BASE } from "./world-view.js";
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
 export { assertWorldStateRemovable } from "./ancestry.js";

package/dist/src/infra-cli.js

@@ -23,7 +23,7 @@ if (!existsSync(definition)) {
     process.exit(2);
 }
 const base = ['compose', '-f', definition];
-const run = (args) => spawnSync('docker', [...base, ...args], {
+const run = (args) => spawnSync('docker', [...base, ...args], { windowsHide: true,
     encoding: 'utf8',
     env: { ...process.env, VOLTER_WORLD_DATA: worldData },
     timeout: 120_000,
@@ -57,7 +57,7 @@ function selectBacking() {
         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

package/dist/src/init.d.ts

@@ -214,7 +214,7 @@ export declare function renderEnvFile(plan: InitPlan): string;
 /** Write the plan's two artifacts. Byte-identical for the same repo + catalog: sorted keys, no
  * timestamps, no absolute paths inside the files. */
 /** What `.volter/.gitignore` says: the story is committed, the running state never is. */
-export declare const STATE_GITIGNORE = "# Volter: the world's running state and live env \u2014 never committed. world.json, handlers/ and seeds/ are the story.\nworlds/\ncurrent\n*.env\ncredentials/\ntoken\n";
+export declare const STATE_GITIGNORE = "# Volter: the world's running state and live env \u2014 never committed. world.json, handlers/ and seeds/ are the story.\nworlds/\ncurrent\n*.env\ncredentials/\ntoken\ntoken.read\nsessions.json\nkeys.json\n";
 export declare function writeWorldInit(plan: InitPlan, options?: {
     force?: boolean;
 }): void;

package/dist/src/init.js

@@ -632,6 +632,29 @@ export function planWorldInit(name, repoPath, options = {}) {
     const mintedEnv = [];
     const infraSignals = new Map();
     const infraEntries = [];
+    // 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 ?? []),
@@ -963,6 +986,9 @@ current
 *.env
 credentials/
 token
+token.read
+sessions.json
+keys.json
 `;
 export function writeWorldInit(plan, options = {}) {
     // A world already here is refused unless forced; a `.volter/` holding only running state

package/dist/src/local-branches.d.ts

@@ -0,0 +1,37 @@
+import { type BranchDoors, type BranchRow, type MountedWorld } from './served-world.js';
+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 declare class LocalBranches {
+    private readonly o;
+    private sweeper;
+    constructor(o: LocalBranchesOptions);
+    private record;
+    /** The branches of `parent` this host holds. */
+    list(parent: string): BranchRow[];
+    /** Branches being made, by parent: a parent is not removed mid-clone. */
+    private readonly making;
+    hasBranches(parent: string): boolean;
+    /** A World's branches doors, answered by this host. */
+    doorsFor(parent: string): BranchDoors;
+    private create;
+    private make;
+    /** The parent's frozen clock, when it has one. */
+    private frozenClock;
+    /** Stop a branch and remove its World (a branch's own branches first). */
+    remove(name: string): Promise<void>;
+    /** Remove the branches whose time ran out, now and every minute while the host serves. */
+    resume(): Promise<void>;
+    /** One sweep at a time: a slow one never overlaps the next. */
+    private sweeping;
+    private sweep;
+    stop(): void;
+}

package/dist/src/local-branches.js

@@ -0,0 +1,193 @@
+// 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.js";
+import { loadWorldConfig } from "./configs.js";
+import { TOKEN_HEADER } from "./served-world.js";
+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, id, name) {
+    if (config.schemaVersion === 2) {
+        return { ...config, metadata: { ...config.metadata, id }, serving: { ...config.serving, mode: 'bare', name } };
+    }
+    return { ...config, id, bare: { ...config.bare, name } };
+}
+export class LocalBranches {
+    o;
+    sweeper = null;
+    constructor(o) {
+        this.o = o;
+    }
+    record(world) {
+        try {
+            return JSON.parse(readFileSync(join(world.root, stateDirName(), RECORD), 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The branches of `parent` this host holds. */
+    list(parent) {
+        const rows = [];
+        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. */
+    making = new Map();
+    hasBranches(parent) { return (this.making.get(parent) ?? 0) > 0 || this.list(parent).length > 0; }
+    /** A World's branches doors, answered by this host. */
+    doorsFor(parent) {
+        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; },
+        };
+    }
+    async create(parent, at, ttlSeconds, parentKey) {
+        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);
+        }
+    }
+    async make(parent, at, ttlSeconds, parentKey) {
+        const from = this.o.worlds.get(parent);
+        if (!from)
+            throw new Error(`no world ${parent} here`);
+        const [org, world] = parent.split('/');
+        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 = () => {
+            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')), id, name), null, 2)}\n`);
+        let mounted;
+        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;
+            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()).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 }, 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. */
+    frozenClock(world) {
+        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) {
+        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() {
+        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. */
+    sweeping = false;
+    async sweep() {
+        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() { if (this.sweeper)
+        clearInterval(this.sweeper); this.sweeper = null; }
+}

package/dist/src/pglite-backing.js

@@ -68,8 +68,10 @@ export function infraConnections(services, env) {
 }
 // this module's directory under Node as under Bun: `volter-world-infra` is a node-shebang bin, where
 // `import.meta.dir` (Bun's) is undefined
-const HERE = fileURLToPath(new URL('.', import.meta.url));
-const HOST = join(HERE, 'pglite-host.mjs');
+// lazy: a module that builds a URL from import.meta.url when it loads fails to load in workerd, which bundles this
+// module into the hosted World (it never runs these services there)
+const here = () => fileURLToPath(new URL('.', import.meta.url));
+const hostScript = () => join(here(), 'pglite-host.mjs');
 const READY_TIMEOUT_MS = 60_000;
 const MONGODB_TWIN = '@volter/twin-mongodb';
 /** The kinds this backing serves, and the name its files carry under the data dir. */
@@ -79,7 +81,7 @@ function pidPath(dataDir, kind) {
 }
 /** The MongoDB twin's cli: the package installed above the World's config (an app repo), else the one
  *  this runtime was installed with (its dependency, or the checkout's workspace link). */
-export function mongodbTwinCli(worldConfig, froms = [...(worldConfig ? [dirname(worldConfig)] : []), HERE]) {
+export function mongodbTwinCli(worldConfig, froms = [...(worldConfig ? [dirname(worldConfig)] : []), here()]) {
     for (const from of froms) {
         const dir = findInstalledPackage(from, MONGODB_TWIN);
         const cli = dir === undefined ? undefined : packCli(dir);
@@ -92,7 +94,7 @@ export function mongodbTwinCli(worldConfig, froms = [...(worldConfig ? [dirname(
  *  process's own runtime; a checkout's is TypeScript whose kernel needs more than Node's type
  *  stripping, so it runs under Bun (this process's, or the one on PATH) — the repository's toolchain —
  *  and without Bun it is refused by name rather than started to fail. */
-export function twinRunner(cli, bunOnPath = () => spawnSync('bun', ['--version'], { stdio: 'ignore', timeout: 10_000 }).status === 0, underBun = typeof globalThis.Bun !== 'undefined') {
+export function twinRunner(cli, bunOnPath = () => spawnSync('bun', ['--version'], { stdio: 'ignore', timeout: 10_000, windowsHide: true }).status === 0, underBun = typeof globalThis.Bun !== 'undefined') {
     if (!cli.endsWith('.ts') || underBun)
         return process.execPath;
     if (bunOnPath())
@@ -105,7 +107,7 @@ function hostArgv(service, serviceData) {
         const cli = mongodbTwinCli(process.env.VOLTER_WORLD_CONFIG);
         return [twinRunner(cli), cli, 'serve', '--port', String(service.hostPort), '--root', serviceData];
     }
-    return ['node', HOST, '--port', String(service.hostPort), '--data', serviceData];
+    return ['node', hostScript(), '--port', String(service.hostPort), '--data', serviceData];
 }
 function alive(pid) {
     try {
@@ -169,6 +171,7 @@ export async function pgliteUp(services, dataDir) {
             // a real fd, not a pipe: the host must outlive this process untethered
             const logFd = openSync(log, 'a');
             const child = spawn(command, args, {
+                windowsHide: true,
                 detached: true,
                 stdio: ['ignore', logFd, logFd],
             });

package/dist/src/prerequisites.js

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
 const realRunner = (cmd, args) => {
-    const result = spawnSync(cmd, args, { encoding: 'utf8' });
+    const result = spawnSync(cmd, args, { windowsHide: true, encoding: 'utf8' });
     return {
         status: result.status,
         stdout: result.stdout || '',

package/dist/src/process-groups.js

@@ -22,7 +22,7 @@ export function survivingOwnedGroups(pids) {
     });
     if (!candidates.length || process.platform === 'win32')
         return candidates;
-    const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], {
+    const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], { windowsHide: true,
         encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024,
     });
     if (result.status !== 0 || result.error)

package/dist/src/redirect-proxy.js

@@ -199,11 +199,11 @@ export function opensslAvailable() {
     // this env var in real usage.
     if (process.env.VOLTER_TEST_NO_OPENSSL === '1')
         return false;
-    const r = spawnSync('openssl', ['version'], { stdio: 'ignore' });
+    const r = spawnSync('openssl', ['version'], { windowsHide: true, stdio: 'ignore' });
     return r.status === 0;
 }
 function runOpenssl(args) {
-    const r = spawnSync('openssl', args, { encoding: 'utf8' });
+    const r = spawnSync('openssl', args, { windowsHide: true, encoding: 'utf8' });
     if (r.status !== 0)
         throw new Error(`openssl ${args[0]} failed: ${(r.stderr || r.stdout || '').trim()}`);
     return r.stdout;

package/dist/src/root.d.ts

@@ -36,6 +36,29 @@ export declare function rootForControlRoot(controlRoot: string, service: string)
 /** The pack's mirror module (`src/<vendor>-mirror-ui.ts`: its shell, client and stylesheet), read as the
  *  hosted mirror build reads it (apps/cloud/scripts/mirrors.ts); a pack's index need not re-export them. */
 export declare function packMirrorExports(vendor: string, from: string): Promise<Record<string, unknown> | null>;
+/** A pack's mirror as the pack builds it (`<vendor>MirrorHtml`, `build<Vendor>MirrorClient`,
+ *  `<vendor>MirrorStyles`), found the way a World finds the pack; null when the pack has none. The
+ *  client builds at serve under Bun and is served prebuilt under Node, by the pack's own builder. */
+export type PackMirror = {
+    html: () => string;
+    client: () => Promise<string>;
+    styles?: () => Promise<string>; /** the account and a credential its screens sign in with (`<vendor>MirrorSignIn`): the account found in the twin's
+       *  state at `root`, the credential minted for it through the twin's own doors (`twin`), never a stored one read back */
+    signIn?: (as: string, ctx: MirrorSignInContext) => Promise<{
+        account: string;
+        token: string;
+    } | null> | {
+        account: string;
+        token: string;
+    } | null;
+};
+/** What a pack's `<vendor>MirrorSignIn` is given: the twin's state root (to find the account) and the twin's own doors
+ *  (to mint a credential for it, as the World's seed does through `/_twin/…`). */
+export type MirrorSignInContext = {
+    root: string;
+    twin: (path: string, init?: RequestInit) => Promise<Response>;
+};
+export declare function packMirror(vendor: string, from: string): Promise<PackMirror | null>;
 /** The real state system's adapters for a vendor: registered with the pack (protocol 2), else the
  *  pack's anchored exports (protocol 1: `perform<Name>Action`, `sync<Name>FromRemote`). */
 export type IngestAdapter = (request: Request, ctx: {