@volter/world-runtime 2.0.15 → 2.0.17

package/dist/src/served-world.js

@@ -156,7 +156,8 @@ export async function mountWorld(name, opts = {}) {
     const world = new WorldDoors(name, worldRoot, configRef, served, host, held('token') ?? mintToken('tok_'), held('token.read') ?? mintToken('tok_r_'));
     const keep = () => { writeSecret(join(worldRoot, stateDirName(), 'token'), world.token); writeSecret(join(worldRoot, stateDirName(), 'token.read'), world.readToken); };
     let timers = [];
-    return {
+    let stopping = null;
+    const mounted = {
         name, served, root: worldRoot,
         get token() { return world.token; }, get readToken() { return world.readToken; },
         twins: () => world.twins(),
@@ -193,18 +194,40 @@ export async function mountWorld(name, opts = {}) {
                 throw error;
             }
         },
-        async stop() {
-            for (const t of timers)
-                clearInterval(t);
-            try {
-                rmSync(record, { force: true });
-            }
-            catch { /* already gone */ }
-            const result = await downWorld(name, worldRoot);
-            if (result.externalErrors.length)
-                throw new Error(`World "${name}" shutdown incomplete; instance and reservation retained: ${result.externalErrors.join('; ')}`);
+        stop() {
+            // one stop at a time: a second caller (the view shutting down while a switch stops this World) shares the first's
+            stopping ??= stopOnce().finally(() => { stopping = null; });
+            return stopping;
         },
     };
+    async function stopOnce() {
+        // refreshes stop first, so none writes into the World while its twins stop; the serve record goes only once they are
+        // down. A stop that fails keeps the record (a checkout under the serve still refuses) and re-arms the refreshes:
+        // refused before anything stopped, the World is served as it was; failed part way, its record names what remains
+        for (const t of timers)
+            clearInterval(t);
+        timers = [];
+        let result;
+        try {
+            result = await downWorld(name, worldRoot);
+            if (result.externalErrors.length)
+                throw new Error(`World "${name}" shutdown incomplete; instance and reservation retained: ${result.externalErrors.join('; ')}`);
+        }
+        catch (error) {
+            if (instance) {
+                try {
+                    timers = await scheduleRefreshes(name, worldRoot, instance);
+                }
+                catch { /* the stop's error is the one reported */ }
+            }
+            throw error;
+        }
+        try {
+            rmSync(record, { force: true });
+        }
+        catch { /* already gone */ }
+    }
+    return mounted;
 }
 /** A local World's mirrors: each pack's builders, found once per process, and each client built once. */
 const localMirrors = new Map();
@@ -1564,8 +1587,10 @@ export class WorldDoors {
             const state = this.stateOf(vendor);
             const controlRoot = this.controlRoot(vendor);
             const counts = new Map();
+            // what the World holds as the vendor's own resources: the twin's bookkeeping (a `_` type, as a screens sign-in's token)
+            // is never a resource a person reads, as it is in no log or diff
             for (const r of readTree(state, controlRoot))
-                if (r.deleted !== true)
+                if (r.deleted !== true && !r.type.startsWith('_'))
                     counts.set(r.type, (counts.get(r.type) ?? 0) + 1);
             twins.push({
                 twin: vendor, position: wholeLog(state, controlRoot).length,

package/dist/src/world-view.js

@@ -55,17 +55,8 @@ export async function serveWorldView(name, opts = {}) {
         switching = true;
         const from = world.name;
         try {
-            // a stop that fails part way brings this branch back as it was before the error is reported
-            try {
-                await world.stop();
-            }
-            catch (error) {
-                try {
-                    await world.boot(url);
-                }
-                catch { /* the stop's own error is the one reported */ }
-                throw error;
-            }
+            // a stop that is refused or fails leaves this branch served as it was (served-world.ts stop): the switch just fails
+            await world.stop();
             let next;
             try {
                 next = await mountWorld(branch, mountOpts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.15",
+  "version": "2.0.17",
   "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,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.9",
+    "@volter/world-core": "2.0.10",
     "@volter/world-console": "2.0.9"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.1",
-    "@volter/world-core": "2.0.9",
+    "@volter/world-core": "2.0.10",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.9"
+    "@volter/twin-mongodb": "0.1.10"
   }
 }

package/src/infra-cli.ts

@@ -1,177 +1,10 @@
 #!/usr/bin/env node
-// Private implementation for infrastructure emitted by `volter-world init`. World configs invoke
-// this declared service; application agents never operate or diagnose its backing mechanism.
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { infraConnections, parseInfraDefinition } from './pglite-backing.ts';
+// `volter-world-infra up|status|down`: the World-managed infrastructure's declared lifecycle commands (infra.ts), as
+// a process. World configs invoke this declared service; application agents never operate or diagnose its backing.
+import { runInfrastructure } from './infra.ts';
 
-const phase = process.argv[2];
-if (phase !== 'up' && phase !== 'status' && phase !== 'down') {
-  process.stderr.write('managed infrastructure: expected up, status, or down\n');
-  process.exit(2);
-}
-
-const worldConfig = process.env.VOLTER_WORLD_CONFIG;
-const worldData = process.env.VOLTER_WORLD_DATA;
-if (!worldConfig || !worldData) {
-  process.stderr.write('managed infrastructure: missing World lifecycle context\n');
-  process.exit(2);
-}
-const definition = join(dirname(worldConfig), 'world.infrastructure.yml');
-if (!existsSync(definition)) {
-  process.stderr.write('managed infrastructure: declared definition is missing\n');
-  process.exit(2);
-}
-
-const base = ['compose', '-f', definition];
-const run = (args: string[]) => spawnSync('docker', [...base, ...args], { windowsHide: true,
-  encoding: 'utf8',
-  env: { ...process.env, VOLTER_WORLD_DATA: worldData },
-  timeout: 120_000,
+const code = await runInfrastructure(process.argv[2] ?? '', process.env, {
+  out: (text) => { process.stdout.write(text); },
+  err: (text) => { process.stderr.write(text); },
 });
-const classify = (raw: string): string => /no space left on device|enospc/iu.test(raw)
-  ? 'insufficient writable storage'
-  : /out of memory|cannot allocate memory|killed/iu.test(raw)
-    ? 'insufficient memory'
-    : /cannot connect|not running|daemon/iu.test(raw)
-      ? 'local execution capacity is unavailable'
-      : 'managed infrastructure operation failed';
-const fail = (result: ReturnType<typeof run>): never => {
-  const raw = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
-  process.stderr.write(`managed infrastructure ${phase} failed: ${classify(raw)}\n`);
-  process.exit(result.status && result.status > 0 ? result.status : 1);
-};
-
-// ---- backing selection ------------------------------------------------------
-// The declared service contract (up/status/down) is the boundary; WHICH
-// runtime answers it is private and chosen here, per machine, at each phase:
-//   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite — explicit, for tests/operators;
-//   2. a working container runtime — the compose path, byte-identical to before;
-//   3. no container runtime + a definition of postgres and/or mongodb services —
-//      the containerless backing (pglite-backing.ts: PGlite for postgres, the
-//      MongoDB twin for mongodb), announced loudly;
-//   4. otherwise the honest refusal naming what this machine cannot serve.
-function selectBacking(): 'docker' | 'pglite' {
-  const forced = process.env.VOLTER_WORLD_INFRA_BACKING;
-  if (forced === 'docker' || forced === 'pglite') return forced;
-  if (forced !== undefined) {
-    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}}'], { 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
-  // on the docker path so the real capacity problem is classified and
-  // surfaced — a full disk starves every backing equally.
-  if (probe.error !== undefined) return 'pglite';
-  const reason = classify(`${probe.stdout ?? ''}\n${probe.stderr ?? ''}`);
-  return reason === 'local execution capacity is unavailable' ? 'pglite' : 'docker';
-}
-
-async function runPglite(): Promise<never> {
-  const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
-  const services = parseInfraDefinition(readFileSync(definition, 'utf8')).filter((s) => composed === null || composed.includes(s.kind));
-  if (services.length === 0) {
-    process.stderr.write('managed infrastructure: the declared definition names no services\n');
-    process.exit(1);
-  }
-  const unsupported = unsupportedKinds(services);
-  if (unsupported.length > 0) {
-    process.stderr.write(`managed infrastructure ${phase} failed: local execution capacity is unavailable (no container runtime, and the containerless backing cannot serve: ${unsupported.join(', ')})\n`);
-    process.exit(1);
-  }
-  if (phase === 'up') {
-    process.stdout.write('managed infrastructure backing: containerless (no container runtime)\n');
-    try {
-      await pgliteUp(services, worldData!);
-    } catch (error) {
-      process.stderr.write(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
-      process.exit(1);
-    }
-    process.stdout.write('managed infrastructure ready\n');
-    process.exit(0);
-  }
-  if (phase === 'status') {
-    const status = await pgliteStatus(services, worldData!);
-    if (!status.ok) {
-      process.stderr.write(`managed infrastructure status failed: ${status.ready}/${services.length} declared services are ready\n`);
-      process.exit(1);
-    }
-    process.stdout.write(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, process.env) })}\n`);
-    process.exit(0);
-  }
-  await pgliteDown(services, worldData!);
-  process.stdout.write('managed infrastructure stopped\n');
-  process.exit(0);
-}
-
-// ---- redis: the twin, containerless ----------------------------------------
-// A redis service is served by the redis twin (redis-backing.ts) on every machine, container runtime or not,
-// unless the operator forces the container backing; the other services take the backing chosen above. Where the
-// twin is not installed (@volter/twin-redis is not this runtime's dependency), redis goes to that backing too:
-// the container where there is one, else the backing's refusal naming redis.
-const declared = parseInfraDefinition(readFileSync(definition, 'utf8'));
-const { redisTwinCli } = await import('./redis-backing.ts');
-const twinCli = redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(worldConfig)]);
-const twinned = process.env.VOLTER_WORLD_INFRA_BACKING === 'docker' || twinCli === undefined ? [] : declared.filter((s) => s.kind === 'redis');
-/** The services the backing below answers for: every one, or those the twin does not serve (by compose service name). */
-const composed = twinned.length === 0 ? null : declared.filter((s) => s.kind !== 'redis').map((s) => s.kind);
-if (twinned.length > 0) await runRedisTwin();
-
-async function runRedisTwin(): Promise<void> {
-  const { redisTwinDown, redisTwinStatus, redisTwinUp } = await import('./redis-backing.ts');
-  const cli = twinCli!;
-  if (phase === 'up') {
-    process.stdout.write('managed infrastructure backing: redis twin (containerless)\n');
-    try {
-      await redisTwinUp(twinned, worldData!, cli);
-    } catch (error) {
-      process.stderr.write(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
-      process.exit(1);
-    }
-  } else if (phase === 'status') {
-    const ready = await redisTwinStatus(twinned, worldData!);
-    if (ready !== twinned.length) {
-      process.stderr.write(`managed infrastructure status failed: ${ready}/${declared.length} declared services are ready\n`);
-      process.exit(1);
-    }
-  } else {
-    await redisTwinDown(twinned, worldData!);
-  }
-  if (composed!.length === 0) {
-    if (phase === 'up') process.stdout.write('managed infrastructure ready\n');
-    else if (phase === 'status') process.stdout.write(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, process.env) })}\n`);
-    else process.stdout.write('managed infrastructure stopped\n');
-    process.exit(0);
-  }
-}
-
-if (selectBacking() === 'pglite') {
-  await runPglite();
-}
-
-const only = composed ?? [];
-if (phase === 'up') {
-  const result = run(['up', '-d', '--wait', ...only]);
-  if (result.status !== 0) fail(result);
-  process.stdout.write('managed infrastructure ready\n');
-} else if (phase === 'status') {
-  const expected = run(['config', '--services']);
-  if (expected.status !== 0) fail(expected);
-  const running = run(['ps', '--status', 'running', '--services']);
-  if (running.status !== 0) fail(running);
-  const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
-  const runningNames = running.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
-  if (expectedNames.length === 0 || expectedNames.join('\0') !== runningNames.join('\0')) {
-    process.stderr.write(`managed infrastructure status failed: ${runningNames.length + twinned.length}/${expectedNames.length + twinned.length} declared services are ready\n`);
-    process.exit(1);
-  }
-  process.stdout.write(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length, connections: infraConnections(declared, process.env) })}\n`);
-} else {
-  const result = run(['down', '--remove-orphans']);
-  if (result.status !== 0) fail(result);
-  process.stdout.write('managed infrastructure stopped\n');
-}
+process.exit(code);

package/src/infra.ts

@@ -0,0 +1,225 @@
+// Private implementation for infrastructure emitted by `volter-world init`. World configs invoke
+// this declared service; application agents never operate or diagnose its backing mechanism.
+//
+// One phase (up, status, down) per call, answering its exit code, with its output written through `io`. The
+// `volter-world-infra` bin (infra-cli.ts) runs it as a process; the World's own `up` runs the up phase in its own
+// process (runtime.ts, `ownInfrastructureUp`), so the containerless services it starts are children of the process
+// that owns the World's lifetime, as every other service's recorder is, and not of a tool that exits once they
+// serve. A process layer where a child does not outlive its parent (a browser tab's) otherwise ended the PGlite host
+// the moment `volter-world-infra up` returned, and the World's readiness probe never saw it.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { infraConnections, parseInfraDefinition } from './pglite-backing.ts';
+
+export interface InfrastructureIo { out: (text: string) => void; err: (text: string) => void }
+
+interface Ran { status: number | null; stdout: string; stderr: string; error?: Error }
+
+/** A command run to its end without blocking this process: in the World's own `up` the phase shares the event loop
+ *  with the boot's signal handling, where the tool's spawnSync blocked only the tool. Ended by `timeout` (SIGTERM,
+ *  as spawnSync's timeout) or by the boot's abort. */
+function runCommand(command: string, args: string[], options: { env: NodeJS.ProcessEnv; timeout: number; signal?: AbortSignal }): Promise<Ran> {
+  return new Promise((resolveRan) => {
+    let stdout = ''; let stderr = ''; let settled = false;
+    let grace: ReturnType<typeof setTimeout> | undefined;
+    const child = spawn(command, args, { windowsHide: true, env: options.env, stdio: ['ignore', 'pipe', 'pipe'], ...(options.signal ? { signal: options.signal } : {}) });
+    const settle = (ran: Ran) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); if (grace) clearTimeout(grace);
+      // a grandchild that still holds the pipes does not hold this answer
+      child.stdout?.destroy(); child.stderr?.destroy();
+      resolveRan(ran);
+    };
+    // the timeout is a hard limit and answers as spawnSync's did: the command is killed and the result carries an
+    // ETIMEDOUT error (a hung `docker info`, a daemon that never answers, is then no container runtime, as before)
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      settle({ status: null, stdout, stderr, error: Object.assign(new Error(`spawn ${command} ETIMEDOUT`), { code: 'ETIMEDOUT' }) });
+    }, options.timeout);
+    child.stdout?.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8'); });
+    child.stderr?.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8'); });
+    // a spawn that fails (no such binary, an abort) answers as spawnSync did: no status, the error
+    child.on('error', (error) => settle({ status: null, stdout, stderr, error }));
+    // the output is whole at `close`; once the command has exited, a descendant holding its pipes open delays the
+    // answer by at most a moment, never to the timeout
+    child.on('exit', (code) => { grace = setTimeout(() => settle({ status: code, stdout, stderr }), 500); });
+    child.on('close', (code) => settle({ status: code, stdout, stderr }));
+  });
+}
+
+/** One phase of the World-managed infrastructure. `env` is the infrastructure service's environment, which the
+ *  services this starts run in; `signal` is the boot's abort (the World's own up passes it; the tool has none). */
+export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, io: InfrastructureIo, signal?: AbortSignal): Promise<number> {
+  if (phase !== 'up' && phase !== 'status' && phase !== 'down') {
+    io.err('managed infrastructure: expected up, status, or down\n');
+    return 2;
+  }
+
+  const worldConfig = env.VOLTER_WORLD_CONFIG;
+  const worldData = env.VOLTER_WORLD_DATA;
+  if (!worldConfig || !worldData) {
+    io.err('managed infrastructure: missing World lifecycle context\n');
+    return 2;
+  }
+  const definition = join(dirname(worldConfig), 'world.infrastructure.yml');
+  if (!existsSync(definition)) {
+    io.err('managed infrastructure: declared definition is missing\n');
+    return 2;
+  }
+
+  const base = ['compose', '-f', definition];
+  const run = async (args: string[]): Promise<Ran> => {
+    const ran = await runCommand('docker', [...base, ...args], { env: { ...env, VOLTER_WORLD_DATA: worldData }, timeout: 120_000, ...(signal ? { signal } : {}) });
+    signal?.throwIfAborted();
+    return ran;
+  };
+  const launch = { env, ...(signal ? { signal } : {}) };
+  const classify = (raw: string): string => /no space left on device|enospc/iu.test(raw)
+    ? 'insufficient writable storage'
+    : /out of memory|cannot allocate memory|killed/iu.test(raw)
+      ? 'insufficient memory'
+      : /cannot connect|not running|daemon/iu.test(raw)
+        ? 'local execution capacity is unavailable'
+        : 'managed infrastructure operation failed';
+  const fail = (result: Ran): number => {
+    const raw = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+    io.err(`managed infrastructure ${phase} failed: ${classify(raw)}\n`);
+    return result.status && result.status > 0 ? result.status : 1;
+  };
+
+  // ---- backing selection ------------------------------------------------------
+  // The declared service contract (up/status/down) is the boundary; WHICH
+  // runtime answers it is private and chosen here, per machine, at each phase:
+  //   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite — explicit, for tests/operators;
+  //   2. a working container runtime — the compose path, byte-identical to before;
+  //   3. no container runtime + a definition of postgres and/or mongodb services —
+  //      the containerless backing (pglite-backing.ts: PGlite for postgres, the
+  //      MongoDB twin for mongodb), announced loudly;
+  //   4. otherwise the honest refusal naming what this machine cannot serve.
+  async function selectBacking(): Promise<'docker' | 'pglite' | number> {
+    const forced = env.VOLTER_WORLD_INFRA_BACKING;
+    if (forced === 'docker' || forced === 'pglite') return forced;
+    if (forced !== undefined) {
+      io.err(`managed infrastructure: VOLTER_WORLD_INFRA_BACKING must be docker or pglite (got ${JSON.stringify(forced)})\n`);
+      return 2;
+    }
+    const probe = await runCommand('docker', ['info', '--format', '{{.ServerVersion}}'], { env, timeout: 10_000, ...(signal ? { signal } : {}) });
+    signal?.throwIfAborted();
+    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
+    // on the docker path so the real capacity problem is classified and
+    // surfaced — a full disk starves every backing equally.
+    // A shell's "command not found" (127) is the same absence: a process layer that runs commands by name answers
+    // an unknown one so, where spawnSync answered ENOSYS (a browser tab's).
+    if (probe.error !== undefined || probe.status === 127) return 'pglite';
+    const reason = classify(`${probe.stdout ?? ''}\n${probe.stderr ?? ''}`);
+    return reason === 'local execution capacity is unavailable' ? 'pglite' : 'docker';
+  }
+
+  async function runPglite(): Promise<number> {
+    const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
+    const services = parseInfraDefinition(readFileSync(definition, 'utf8')).filter((s) => composed === null || composed.includes(s.kind));
+    if (services.length === 0) {
+      io.err('managed infrastructure: the declared definition names no services\n');
+      return 1;
+    }
+    const unsupported = unsupportedKinds(services);
+    if (unsupported.length > 0) {
+      io.err(`managed infrastructure ${phase} failed: local execution capacity is unavailable (no container runtime, and the containerless backing cannot serve: ${unsupported.join(', ')})\n`);
+      return 1;
+    }
+    if (phase === 'up') {
+      io.out('managed infrastructure backing: containerless (no container runtime)\n');
+      try {
+        await pgliteUp(services, worldData!, launch);
+      } catch (error) {
+        io.err(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
+        return 1;
+      }
+      io.out('managed infrastructure ready\n');
+      return 0;
+    }
+    if (phase === 'status') {
+      const status = await pgliteStatus(services, worldData!);
+      if (!status.ok) {
+        io.err(`managed infrastructure status failed: ${status.ready}/${services.length} declared services are ready\n`);
+        return 1;
+      }
+      io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env) })}\n`);
+      return 0;
+    }
+    await pgliteDown(services, worldData!);
+    io.out('managed infrastructure stopped\n');
+    return 0;
+  }
+
+  // ---- redis: the twin, containerless ----------------------------------------
+  // A redis service is served by the redis twin (redis-backing.ts) on every machine, container runtime or not,
+  // unless the operator forces the container backing; the other services take the backing chosen above. Where the
+  // twin is not installed (@volter/twin-redis is not this runtime's dependency), redis goes to that backing too:
+  // the container where there is one, else the backing's refusal naming redis.
+  const declared = parseInfraDefinition(readFileSync(definition, 'utf8'));
+  const { redisTwinCli } = await import('./redis-backing.ts');
+  const twinCli = redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(worldConfig)]);
+  const twinned = env.VOLTER_WORLD_INFRA_BACKING === 'docker' || twinCli === undefined ? [] : declared.filter((s) => s.kind === 'redis');
+  /** The services the backing below answers for: every one, or those the twin does not serve (by compose service name). */
+  const composed = twinned.length === 0 ? null : declared.filter((s) => s.kind !== 'redis').map((s) => s.kind);
+  if (twinned.length > 0) {
+    const { redisTwinDown, redisTwinStatus, redisTwinUp } = await import('./redis-backing.ts');
+    const cli = twinCli!;
+    if (phase === 'up') {
+      io.out('managed infrastructure backing: redis twin (containerless)\n');
+      try {
+        await redisTwinUp(twinned, worldData!, cli, launch);
+      } catch (error) {
+        io.err(`managed infrastructure up failed: ${String((error as Error).message ?? error)}\n`);
+        return 1;
+      }
+    } else if (phase === 'status') {
+      const ready = await redisTwinStatus(twinned, worldData!);
+      if (ready !== twinned.length) {
+        io.err(`managed infrastructure status failed: ${ready}/${declared.length} declared services are ready\n`);
+        return 1;
+      }
+    } else {
+      await redisTwinDown(twinned, worldData!);
+    }
+    if (composed!.length === 0) {
+      if (phase === 'up') io.out('managed infrastructure ready\n');
+      else if (phase === 'status') io.out(`${JSON.stringify({ ok: true, services: declared.length, connections: infraConnections(declared, env) })}\n`);
+      else io.out('managed infrastructure stopped\n');
+      return 0;
+    }
+  }
+
+  const backing = await selectBacking();
+  if (typeof backing === 'number') return backing;
+  if (backing === 'pglite') return runPglite();
+
+  const only = composed ?? [];
+  if (phase === 'up') {
+    const result = await run(['up', '-d', '--wait', ...only]);
+    if (result.status !== 0) return fail(result);
+    io.out('managed infrastructure ready\n');
+  } else if (phase === 'status') {
+    const expected = await run(['config', '--services']);
+    if (expected.status !== 0) return fail(expected);
+    const running = await run(['ps', '--status', 'running', '--services']);
+    if (running.status !== 0) return fail(running);
+    const expectedNames = expected.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
+    const runningNames = running.stdout.split(/\s+/u).filter(Boolean).filter((n) => composed === null || composed.includes(n)).sort();
+    if (expectedNames.length === 0 || expectedNames.join('\0') !== runningNames.join('\0')) {
+      io.err(`managed infrastructure status failed: ${runningNames.length + twinned.length}/${expectedNames.length + twinned.length} declared services are ready\n`);
+      return 1;
+    }
+    io.out(`${JSON.stringify({ ok: true, services: expectedNames.length + twinned.length, connections: infraConnections(declared, env) })}\n`);
+  } else {
+    const result = await run(['down', '--remove-orphans']);
+    if (result.status !== 0) return fail(result);
+    io.out('managed infrastructure stopped\n');
+  }
+  return 0;
+}

package/src/pglite-backing.ts

@@ -97,11 +97,19 @@ export function twinRunner(cli: string, bunOnPath: () => boolean = () => spawnSy
   throw new Error(`a checkout's MongoDB twin runs under bun, which is not on PATH (${cli} is TypeScript that Node cannot run)`);
 }
 
+/** How a backing starts its hosts: the environment they run in (the World's service environment, which
+ *  the runtime computes for the infrastructure service: admitted host env, the World's env, the service's own, less
+ *  the control plane's NODE_OPTIONS and proxies), and the boot's abort. The `volter-world-infra` process passes
+ *  nothing and its hosts inherit its own environment, which is that same service environment. The World's `up`,
+ *  running the up phase in its own process, passes it: its own process.env is the operator's, not the service's. */
+export interface HostLaunch { env?: NodeJS.ProcessEnv; signal?: AbortSignal }
+
 /** The argv that serves one service on its declared loopback port, with its bytes in `serviceData`. */
-function hostArgv(service: InfraService, serviceData: string): string[] {
+function hostArgv(service: InfraService, serviceData: string, env: NodeJS.ProcessEnv): string[] {
   if (service.kind === 'mongodb') {
-    const cli = mongodbTwinCli(process.env.VOLTER_WORLD_CONFIG);
-    return [twinRunner(cli), cli, 'serve', '--port', String(service.hostPort), '--root', serviceData];
+    const cli = mongodbTwinCli(env.VOLTER_WORLD_CONFIG);
+    // blocking (spawnSync), as it was in the tool: reached only for a checkout's TypeScript cli under Node
+    return [twinRunner(cli, () => spawnSync('bun', ['--version'], { stdio: 'ignore', timeout: 10_000, windowsHide: true, env }).status === 0), cli, 'serve', '--port', String(service.hostPort), '--root', serviceData];
   }
   return ['node', hostScript(), '--port', String(service.hostPort), '--data', serviceData];
 }
@@ -138,7 +146,8 @@ function logSince(log: string, offset: number): string {
   try { return readFileSync(log).subarray(offset).toString('utf8'); } catch { return ''; }
 }
 
-export async function pgliteUp(services: InfraService[], dataDir: string): Promise<void> {
+export async function pgliteUp(services: InfraService[], dataDir: string, launch: HostLaunch = {}): Promise<void> {
+  const env = launch.env ?? process.env;
   // Every check before any start: a refused up starts nothing, so it never leaves the World half-booted.
   const plan: Array<{ service: InfraService; name: string; serviceData: string; log: string; pidFile: string; argv: string[] }> = [];
   for (const service of services) {
@@ -150,7 +159,7 @@ export async function pgliteUp(services: InfraService[], dataDir: string): Promi
     if (await listening(service.hostPort)) {
       throw new Error(`${name} cannot serve port ${service.hostPort}: another process is already listening on it`);
     }
-    plan.push({ service, name, serviceData, log, pidFile, argv: hostArgv(service, serviceData) });
+    plan.push({ service, name, serviceData, log, pidFile, argv: hostArgv(service, serviceData, env) });
   }
   const started: Array<{ pid: number; pidFile: string }> = [];
   try {
@@ -163,6 +172,7 @@ export async function pgliteUp(services: InfraService[], dataDir: string): Promi
       const logFd = openSync(log, 'a');
       const child = spawn(command!, args, {
         windowsHide: true,
+        env,
         detached: true,
         stdio: ['ignore', logFd, logFd],
       });
@@ -177,6 +187,8 @@ export async function pgliteUp(services: InfraService[], dataDir: string): Promi
       while (!(alive(child.pid!) && logSince(log, offset).includes(line) && await listening(service.hostPort))) {
         if (!alive(child.pid!)) throw new Error(`${name} exited before serving — see ${log}`);
         if (Date.now() > deadline) throw new Error(`${name} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+        // an aborted boot (Ctrl-C during up) stops waiting; the catch below ends what this up started
+        launch.signal?.throwIfAborted();
         await sleep(200);
       }
     }

package/src/redis-backing.ts

@@ -13,7 +13,7 @@ import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { findInstalledPackage, packCli } from './catalog.ts';
-import type { InfraService } from './pglite-backing.ts';
+import type { HostLaunch, InfraService } from './pglite-backing.ts';
 
 const PACKAGE = '@volter/twin-redis';
 const READY_TIMEOUT_MS = 60_000;
@@ -49,7 +49,7 @@ function listening(port: number): Promise<boolean> {
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-export async function redisTwinUp(services: InfraService[], dataDir: string, cli: string): Promise<void> {
+export async function redisTwinUp(services: InfraService[], dataDir: string, cli: string, launch: HostLaunch = {}): Promise<void> {
   for (const service of services) {
     const pidFile = pidPath(dataDir, service);
     if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort)) continue;
@@ -66,6 +66,7 @@ export async function redisTwinUp(services: InfraService[], dataDir: string, cli
     // type transformation, not only stripping (the kernel declares constructor parameter properties)
     const runtime = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
     const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
+      env: launch.env ?? process.env,
       detached: true,
       stdio: ['ignore', logFd, logFd],
     });
@@ -75,6 +76,7 @@ export async function redisTwinUp(services: InfraService[], dataDir: string, cli
     const deadline = Date.now() + READY_TIMEOUT_MS;
     while (!(await listening(service.hostPort)) || !alive(child.pid!)) {
       if (!alive(child.pid!)) throw new Error(`redis exited before serving — see ${log}`);
+      launch.signal?.throwIfAborted();
       if (Date.now() > deadline) throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
       await sleep(200);
     }