@volter/world-runtime 2.0.0 → 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/known-external-services.json

@@ -373,10 +373,6 @@
       "disposition": "demanded",
       "reason": "vendor google-play (Play Developer API), ×1 — ladder classification 2026-09-02"
     },
-    "@googleapis/calendar": {
-      "disposition": "demanded",
-      "reason": "vendor google-calendar, ×1 (plus the GOOGLE_CALENDAR_API_KEY stem, ×1) — ladder classification 2026-09-02"
-    },
     "@googleapis/sheets": {
       "disposition": "demanded",
       "reason": "vendor google-sheets, ×1 — ladder classification 2026-09-02"
@@ -863,10 +859,6 @@
       "disposition": "demanded",
       "reason": "vendor ghost (VITE_PUBLIC_GHOST_CONTENT_API_KEY — the browser-side Content API key), ×1 — ladder classification 2026-09-02"
     },
-    "googlecalendar": {
-      "disposition": "demanded",
-      "reason": "vendor google-calendar (GOOGLE_CALENDAR_API_KEY; the @googleapis/calendar client is the same demand), ×1 — ladder classification 2026-09-02"
-    },
     "googlecloud": {
       "disposition": "demanded",
       "reason": "vendor googlecloud (GOOGLE_CLOUD_API_KEY; the roster's one consumer spends it on the Web Fonts Developer API at www.googleapis.com/webfonts/v1, so the stem is a Google Cloud API key rather than a googleoauth credential), ×1 — ladder classification 2026-09-02"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.0",
+  "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",
@@ -59,6 +59,7 @@
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
+    "mongodb": "~6.20.0",
     "pg": "8.16.3",
     "typescript": "^5.9.0"
   },
@@ -66,12 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0",
-    "@volter/world-console": "2.0.0"
+    "@volter/world-core": "2.0.2",
+    "@volter/world-console": "2.0.2"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
-    "@volter/world-core": "2.0.0",
+    "@electric-sql/pglite-pgvector": "0.0.9",
+    "@volter/world-access": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -79,5 +82,8 @@
     "@volter/world-console": {
       "optional": true
     }
+  },
+  "optionalDependencies": {
+    "@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/branch.ts

@@ -2,13 +2,18 @@
 // log of changes, and a world is a branch with compute attached (docs/concepts/the-model.md).
 // `branch <world> <name>` boots a new world from the base's config and forks every twin's mirror
 // into it (core's `forkTwin`: a POINTER to the base at its current position — the base's whole
-// history, its own entries included, is the branch's parent; nothing is copied). `checkout <name>`
+// history, its own entries included, is the branch's parent; nothing is copied). A managed database (containerless
+// Postgres) keeps no history, so it is the one thing copied: the stopped base's data, as of now. Two branches of one
+// base running at once share the database port its definition names; run one at a time (the SDK does). `checkout <name>`
 // brings a stopped world back up from its own instance record, state intact.
-import { existsSync, readdirSync } from 'node:fs';
+import { cpSync, existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { captureHistory, historyAtInstant, forkTwin, stateGeneration, withAncestryLock, worldPaths, worldStateRoot } from '@volter/world-core';
 import { downWorld, saveWorldInstance, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
+import { parseInfraDefinition, pgliteDown, pgliteUp } from './pglite-backing.ts';
+import { redisTwinCli, redisTwinDown, redisTwinUp } from './redis-backing.ts';
 
 export type BranchOptions = { root?: string; envFile?: string; now?: Date; /** branch from a point in the base's history: an instant, or a position per twin (contract "Just like Neon", 3) */ at?: { instant?: string; positions?: Record<string, number>; views?: Record<string, string> } };
 
@@ -37,6 +42,12 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
       return { state, view, position, generation: stateGeneration(worldPaths(state, fromRoot).dir) };
     }) };
   }));
+  // the base's managed databases (checked before the branch boots: its database would share the base's port)
+  const databases = managedDatabases(from);
+  if (databases.length && (options.at?.instant || options.at?.positions || options.at?.views)) {
+    throw new Error(`volter-world branch: ${base} has a managed database, which keeps no history to branch from at an instant or position; branch from its current state`);
+  }
+  refuseLiveDatabases(from, databases);
   const instance = await upWorld(existsSync(from.configPath) ? from.configPath : from.config, { name, root, mode: from.mode, envFile });
   const forked: Record<string, string[]> = {};
   try {
@@ -48,6 +59,7 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
       }
       if (states.length) forked[service] = states.map(s => s.state);
     }
+    await branchManagedDatabases(from, instance, databases);
   } catch (error) {
     await downWorld(name, root, { purge: true, expectedCreatedAt: instance.createdAt });
     throw error;
@@ -55,6 +67,58 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
   return { instance, forked };
 }
 
+/** The base's containerless managed databases: each PGlite `pglite-<kind>-data` and the MongoDB twin's
+ *  `twin-mongodb-data` (pglite-backing.ts), and the redis twin's `redis-twin` tree (redis-backing.ts). A stopped World's
+ *  hosts leave no pid file; a docker-backed World keeps its data under the container's volume, which a branch does not
+ *  carry. */
+function managedDatabases(from: WorldInstance): string[] {
+  const data = from.dirs.data;
+  if (!existsSync(data)) return [];
+  return readdirSync(data).filter((n) => /^pglite-[a-z0-9_-]+-data$/.test(n) || n === 'twin-mongodb-data' || n === 'redis-twin');
+}
+
+/** The pid files of the hosts serving one managed database directory. */
+function hostPidFiles(data: string, db: string): string[] {
+  if (db === 'redis-twin') return readdirSync(data).filter((n) => /^redis-twin-\d+\.pid$/.test(n)).map((n) => join(data, n));
+  return [join(data, `${db.slice(0, -'-data'.length)}.pid`)];
+}
+
+/** A copy of a live database directory is not a consistent one, and the branch's database would answer on the base's
+ *  port: the base must be stopped first (`volter world branch` stops it, as a branch replaces its base). */
+function refuseLiveDatabases(from: WorldInstance, dbs: string[]): void {
+  for (const db of dbs) {
+    for (const pidFile of hostPidFiles(from.dirs.data, db)) {
+      const pid = existsSync(pidFile) ? Number(readFileSync(pidFile, 'utf8').trim()) : NaN;
+      let live = false;
+      if (Number.isInteger(pid) && pid > 0) { try { process.kill(pid, 0); live = true; } catch { live = false; } }
+      if (live) throw new Error(`volter-world branch: ${from.name}'s managed ${db} is running (pid ${pid}); stop ${from.name} first so its database can be copied into the branch consistently`);
+    }
+  }
+}
+
+/** The branch's managed databases as the base holds them: the branch's own, just booted empty by `up`, are stopped,
+ *  replaced by a copy of the base's data, and started again, so a branch of a migrated and seeded World serves that
+ *  data, as its twins serve the base's history. */
+async function branchManagedDatabases(from: WorldInstance, instance: WorldInstance, dbs: string[]): Promise<void> {
+  if (!dbs.length) return;
+  const definition = join(dirname(instance.configPath), 'world.infrastructure.yml');
+  if (!existsSync(definition)) return;
+  const services = parseInfraDefinition(readFileSync(definition, 'utf8'));
+  const redis = services.filter((s) => s.kind === 'redis');
+  const hosted = services.filter((s) => s.kind !== 'redis');
+  const redisCli = dbs.includes('redis-twin') && redis.length ? redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(instance.configPath)]) : undefined;
+  await pgliteDown(hosted, instance.dirs.data);
+  if (redisCli) await redisTwinDown(redis, instance.dirs.data);
+  for (const db of dbs) {
+    if (db === 'redis-twin' && !redisCli) continue;
+    const to = join(instance.dirs.data, db);
+    rmSync(to, { recursive: true, force: true });
+    cpSync(join(from.dirs.data, db), to, { recursive: true });
+  }
+  if (dbs.some((db) => db !== 'redis-twin')) await pgliteUp(hosted, instance.dirs.data);
+  if (redisCli) await redisTwinUp(redis, instance.dirs.data, redisCli);
+}
+
 /** A stopped world back up, from its own record. */
 export async function checkoutWorld(name: string, options: { root?: string } = {}): Promise<WorldInstance> {
   const root = resolve(options.root ?? process.cwd());

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

@@ -2,7 +2,7 @@
 import { sessionTrustEnv } from './ca-trust.ts';
 import { spawn, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve, resolve as resolvePath } from 'node:path';
 import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
@@ -518,39 +518,61 @@ async function main(): Promise<void> {
   }
 
   if (cmd === 'clock') {
-    // THE operator door for world time (physics): show / set <iso> / advance <duration>.
-    // The clock is a frozen instant every twin reads per request (kernel worldNow()); setting
-    // or advancing takes effect live, no restarts. `advance` requires a set clock (advancing
-    // wall-clock would silently freeze time as a side effect).
+    // THE operator door for world time (physics): show / set <iso> / advance <duration> / shift <duration> / clear.
+    // The clock every twin reads per request (kernel worldNow()), and every application process through the injector
+    // (inject.cjs, WORLD TIME); a change takes effect live, no restarts. Its two forms (world-clock.cjs): `set` freezes
+    // time at an instant (scripted time: a life, a seed); `shift` moves a World forward while its time keeps running (a
+    // World serving an application, whose time a frozen instant would stop); `advance` moves either form; `clear`
+    // returns the World to the machine's time. `advance` refuses a World on the machine's time, which it would freeze.
     // argv shape here: cmd='clock', subject=<world>, rest=[action, value?, flags...]
+    const clockForm = createRequire(import.meta.url)('@volter/world-core/world-clock') as typeof import('@volter/world-core/world-clock');
     const name = subject;
     const [action, value] = rest;
-    if (!name || !action || (action !== 'show' && action !== 'set' && action !== 'advance')) {
-      console.error('usage: volter-world clock <world> show | set <iso-8601> | advance <N s|m|h|d> [--root <repo>]');
+    if (!name || !action || !['show', 'set', 'advance', 'shift', 'clear'].includes(action)) {
+      console.error('usage: volter-world clock <world> show | set <iso-8601> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear [--root <repo>]');
       process.exit(2);
     }
     const rootDir = resolve(optionValue(rest, '--root') ?? process.cwd());
     const file = clockFile(rootDir, name);
+    const current = existsSync(file) ? clockForm.parseClock(readFileSync(file, 'utf8')) : null;
+    const write = (clock: Parameters<typeof clockForm.formatClock>[0]) => {
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, `${clockForm.formatClock(clock)}\n`);
+      // the World's time now, bare, as scripts read it (`show` says which form)
+      console.log(new Date(clockForm.clockNowMs(clock, Date.now())).toISOString());
+    };
     if (action === 'show') {
-      console.log(existsSync(file) ? `${readFileSync(file, 'utf8').trim()} (frozen)` : `${new Date().toISOString()} (wall clock — no world clock set)`);
+      if (!current) console.log(`${new Date().toISOString()} (wall clock — no world clock set)`);
+      else if (current.kind === 'frozen') console.log(`${new Date(current.at).toISOString()} (frozen)`);
+      else {
+        const ahead = current.at - current.since;
+        console.log(`${new Date(clockForm.clockNowMs(current, Date.now())).toISOString()} (running, ${ahead >= 0 ? '+' : '-'}${Math.abs(ahead) / 1000}s from the machine's time)`);
+      }
+      return;
+    }
+    if (action === 'clear') {
+      if (existsSync(file)) rmSync(file);
+      console.log(`${new Date().toISOString()} (wall clock — no world clock set)`);
       return;
     }
     if (action === 'set') {
       const parsed = Date.parse(value ?? '');
       if (Number.isNaN(parsed)) { console.error(`clock set: ${JSON.stringify(value)} is not an ISO-8601 instant`); process.exit(2); }
-      mkdirSync(dirname(file), { recursive: true });
-      writeFileSync(file, `${new Date(parsed).toISOString()}\n`);
-      console.log(new Date(parsed).toISOString());
+      write({ kind: 'frozen', at: parsed });
       return;
     }
     const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec((value ?? '').trim());
-    if (!m) { console.error(`clock advance: ${JSON.stringify(value)} is not <N>(s|m|h|d)`); process.exit(2); }
-    if (!existsSync(file)) { console.error('clock advance: no world clock is set (advance from wall-clock would freeze time as a side effect) — `clock set <iso>` first'); process.exit(2); }
-    const base = Date.parse(readFileSync(file, 'utf8').trim());
-    const unit = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as 's' | 'm' | 'h' | 'd'];
-    const next = new Date(base + Number(m[1]) * unit).toISOString();
-    writeFileSync(file, `${next}\n`);
-    console.log(next);
+    if (!m) { console.error(`clock ${action}: ${JSON.stringify(value)} is not <N>(s|m|h|d)`); process.exit(2); }
+    const by = Number(m[1]) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as 's' | 'm' | 'h' | 'd'];
+    if (action === 'advance') {
+      if (!current) { console.error('clock advance: no world clock is set (advance from wall-clock would freeze time as a side effect) — `clock set <iso>` first, or `clock shift` to move a running World'); process.exit(2); }
+      write({ ...current, at: current.at + by });
+      return;
+    }
+    // shift: a World on the machine's time, or already running, moves forward and keeps running
+    if (current?.kind === 'frozen') { console.error('clock shift: this World\'s clock is frozen — `clock advance` moves it, or `clock clear` first'); process.exit(2); }
+    const wall = Date.now();
+    write(current ? { ...current, at: current.at + by } : { kind: 'running', at: wall + by, since: wall });
     return;
   }
 
@@ -838,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();
@@ -862,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');
@@ -870,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);