@volter/twin-world 0.1.0

package/src/runtime.ts

@@ -0,0 +1,1888 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { createServer } from 'node:net';
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, writeFileSync, writeSync, existsSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { Socket } from 'node:net';
+import { withFileLock } from '@volter/twin';
+import { loadWorldConfig } from './configs.ts';
+import { activeVendorMap, ensureCa, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from './redirect-proxy.ts';
+import type { WorldConfig, WorldExternalReadyWhen, WorldInstance, WorldIsolation, WorldMode, WorldServiceConfig, WorldServiceInstance } from './schema.ts';
+
+const requireFromHere = createRequire(import.meta.url);
+
+export type UpWorldOptions = {
+  name?: string;
+  root?: string;
+  mode?: WorldMode;
+  /** Overrides the config's `isolation` for this boot (e.g. force 'process' for a share world). */
+  isolation?: WorldIsolation;
+  envFile?: string;
+  share?: Omit<ShareWorldOptions, 'root' | 'service' | 'verifyPath'> & { verifyPath?: string | false };
+};
+
+export type ShareWorldOptions = {
+  root?: string;
+  service?: string;
+  provider?: 'cloudflare-quick' | 'command';
+  command?: string;
+  args?: string[];
+  timeoutMs?: number;
+  verifyPath?: string | false;
+};
+
+export type ShareWorldServicesOptions = Omit<ShareWorldOptions, 'service' | 'verifyPath'> & {
+  service?: string;
+  verifyPath?: string | false;
+};
+
+export type WorldDoctorCheck = {
+  id: string;
+  ok: boolean;
+  message: string;
+};
+
+export type WorldDoctorReport = {
+  name: string;
+  ok: boolean;
+  checks: WorldDoctorCheck[];
+};
+
+export type RunWorldOptions = UpWorldOptions & {
+  keep?: boolean;
+};
+
+export type WorldUrlInfo = {
+  name: string;
+  mode: WorldMode;
+  services: Record<string, {
+    localUrl: string;
+    publicUrl?: string;
+    publicReady?: boolean;
+  }>;
+};
+
+function worldBaseDir(root: string): string {
+  return join(root, '.volter', 'worlds');
+}
+
+/** World names become a path segment (instanceDir/instanceLockFile) and must never let a
+ *  caller escape `worldBaseDir` (no `/`, and the leading-alnum requirement rules out a bare
+ *  `..`). Shared by upWorld's boot-time check and downWorld's `--purge` (the one path that
+ *  recursively `rmSync`s a name-derived directory, so it is the one that most needs this to
+ *  hold). */
+function assertSafeWorldName(name: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) throw new Error(`Invalid world name: ${name}`);
+}
+
+function instanceDir(root: string, name: string): string {
+  return join(worldBaseDir(root), name);
+}
+
+function instanceFile(root: string, name: string): string {
+  return join(instanceDir(root, name), 'instance.json');
+}
+
+/** Lockfile guarding the synchronous claim-of-the-instance-dir section of `upWorld` (TWIN-36).
+ * It must survive the claim's own `rmSync` of the instance dir, so it lives BESIDE the dirs in
+ * a dot-prefixed sibling: world names must start with an alphanumeric, so `.locks` can never
+ * collide with (or be wiped as) a world's instance dir. */
+function instanceLockFile(root: string, name: string): string {
+  return join(worldBaseDir(root), '.locks', `${name}.lock`);
+}
+
+/** Claim marker a winning `upWorld` writes into the freshly-wiped instance dir — under the
+ * instance lock, before releasing it — and removes once its boot attempt settles. It is what
+ * keeps later claimants out for the whole (async, possibly long) boot: mid-boot there are no
+ * recorded pids yet, so without it a second `upWorld` would see "nothing running" and rmSync
+ * the winner's dir out from under its freshly-spawned services. */
+function bootingFile(root: string, name: string): string {
+  return join(instanceDir(root, name), 'booting.json');
+}
+
+type BootingClaim = { pid: number; at: string };
+
+/** The live booting claim for a world, or null when there is none to honor. Only ever read
+ * under the instance lock, and the marker is written under that same lock — so a torn read is
+ * impossible; a malformed marker is a corrupt leftover and treated as stale. A claim whose
+ * recorded booter pid is dead is stale too (crashed mid-boot): the next claimant reclaims the
+ * dir, exactly like livePids() lets a fully-dead world be re-upped. */
+function liveBootingClaim(path: string): BootingClaim | null {
+  if (!existsSync(path)) return null;
+  let claim: BootingClaim;
+  try {
+    claim = JSON.parse(readFileSync(path, 'utf8')) as BootingClaim;
+  } catch {
+    return null;
+  }
+  if (!Number.isInteger(claim.pid) || claim.pid <= 0) return null;
+  return livePids([claim.pid]).length > 0 ? claim : null;
+}
+
+/** Where the session-scoped CA + on-the-fly leaf certs live for a world (under the instance dir, so
+ * `down`'s teardown removes them — the CA never outlives the world). */
+function tlsDir(root: string, name: string): string {
+  return join(instanceDir(root, name), 'tls');
+}
+
+/** State of a detached ambient-redirect proxy daemon (so `activate` can export its env and `down`
+ * can stop it). Written by the daemon, read by activate/down. */
+function proxyStateFile(root: string, name: string): string {
+  return join(instanceDir(root, name), 'proxy.json');
+}
+
+function proxyEnvFile(root: string, name: string): string {
+  return join(instanceDir(root, name), 'proxy-env.json');
+}
+
+type ProxyState = { pid: number; url: string; caCertPath: string };
+
+function readProxyState(root: string, name: string): ProxyState | null {
+  const file = proxyStateFile(root, name);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as ProxyState;
+  } catch {
+    return null;
+  }
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function envFileContents(env: Record<string, string>): string {
+  return `${Object.entries(env)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `export ${key}=${shellQuote(value)}`)
+    .join('\n')}\n`;
+}
+
+function injectPreloadSpecifier(): string {
+  return requireFromHere.resolve('@volter/twin/inject');
+}
+
+function writeProxyEnv(root: string, name: string, env: Record<string, string>): void {
+  writeFileSync(proxyEnvFile(root, name), `${JSON.stringify(env, null, 2)}\n`);
+}
+
+function readProxyEnv(path: string): Record<string, string> {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Record<string, string>;
+  } catch {
+    return {};
+  }
+}
+
+/** Resolve a service's cliRedirect map (env var → template), substituting the literal `${url}`
+ * with the service's resolved URL. These flow into the world env so the vendor's real CLI lands
+ * in the twin. See docs/WORLD_ACTIVATE.md. */
+function resolveCliRedirect(cliRedirect: Record<string, string> | undefined, url: string): Record<string, string> {
+  if (!cliRedirect) return {};
+  const out: Record<string, string> = {};
+  for (const [key, template] of Object.entries(cliRedirect)) out[key] = template.split('${url}').join(url);
+  return out;
+}
+
+function resolveServiceEnvTemplates(
+  templates: Record<string, string> | undefined,
+  service: { host: string; port: number; url: string },
+): Record<string, string> {
+  if (!templates) return {};
+  const out: Record<string, string> = {};
+  for (const [key, template] of Object.entries(templates)) {
+    out[key] = template
+      .split('${url}').join(service.url)
+      .split('${httpUrl}').join(service.url)
+      .split('${host}').join(service.host)
+      .split('${port}').join(String(service.port));
+  }
+  return out;
+}
+
+const CONTROL_PLANE_EGRESS_ENV = [
+  'NODE_OPTIONS',
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'ALL_PROXY',
+  'http_proxy',
+  'https_proxy',
+  'all_proxy',
+];
+
+function serviceProcessEnv(
+  config: WorldConfig,
+  service: WorldServiceConfig,
+  worldEnv: Record<string, string>,
+  port: number,
+): Record<string, string> {
+  const env: Record<string, string> = {
+    ...process.env,
+    ...(config.env ?? {}),
+    ...worldEnv,
+    PORT: String(port),
+  };
+  env.NO_PROXY = env.NO_PROXY ? `127.0.0.1,localhost,${env.NO_PROXY}` : '127.0.0.1,localhost';
+  env.no_proxy = env.no_proxy ? `127.0.0.1,localhost,${env.no_proxy}` : '127.0.0.1,localhost';
+  if (service.controlPlane) {
+    for (const key of CONTROL_PLANE_EGRESS_ENV) delete env[key];
+  }
+  return { ...env, ...(service.env ?? {}) };
+}
+
+async function allocatePort(): Promise<number> {
+  return await new Promise((resolvePort, reject) => {
+    const server = createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        server.close(() => reject(new Error('Could not allocate a TCP port')));
+        return;
+      }
+      const port = address.port;
+      server.close(() => resolvePort(port));
+    });
+    server.on('error', reject);
+  });
+}
+
+async function waitForTcp(port: number, timeoutMs = 15_000): Promise<void> {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const ok = await new Promise<boolean>((resolveOk) => {
+      const socket = new Socket();
+      socket.setTimeout(500);
+      socket.once('connect', () => {
+        socket.destroy();
+        resolveOk(true);
+      });
+      socket.once('timeout', () => {
+        socket.destroy();
+        resolveOk(false);
+      });
+      socket.once('error', () => resolveOk(false));
+      socket.connect(port, '127.0.0.1');
+    });
+    if (ok) return;
+    await new Promise((resolveWait) => setTimeout(resolveWait, 150));
+  }
+  throw new Error(`Service on port ${port} did not become reachable`);
+}
+
+function readPids(path: string): number[] {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => Number(line.trim()))
+    .filter((pid) => Number.isInteger(pid) && pid > 0);
+}
+
+function livePids(pids: number[]): number[] {
+  return pids.filter((pid) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function tunnelPids(instance: WorldInstance): number[] {
+  return Object.values(instance.services)
+    .map((service) => service.tunnel?.pid)
+    .filter((pid): pid is number => Boolean(pid));
+}
+
+function writePidsFromInstance(instance: WorldInstance): void {
+  // Deduped: co-located services share the single host child's pid.
+  const pids = [...new Set([
+    ...Object.values(instance.services).map((service) => service.pid),
+    ...tunnelPids(instance),
+  ].filter((pid) => Number.isInteger(pid) && pid > 0))];
+  writeFileSync(instance.pidsFile, `${pids.join('\n')}\n`);
+}
+
+function saveWorldInstance(instance: WorldInstance): void {
+  writeFileSync(instanceFile(instance.root, instance.name), `${JSON.stringify(instance, null, 2)}\n`);
+}
+
+/** The co-located host CHILD process cannot safely rewrite instance.json out from under the
+ *  parent (which may still be mid-boot, or rewrite it later via share/unshare) — so a worker
+ *  give-up (host.ts fires it on the first crash — never restarted) is recorded in a sidecar
+ *  file next to instance.json instead
+ *  (see host-cli.ts). Folding it in here means every reader (doctor, status, tests) sees the
+ *  record on `services[<id>].workerGaveUp` exactly as if it had been written into instance.json. */
+function mergeWorkerGaveUp(instance: WorldInstance, instancePath: string): void {
+  const sidecar = join(dirname(instancePath), 'host-gaveup.json');
+  if (!existsSync(sidecar)) return;
+  try {
+    const gaveUp = JSON.parse(readFileSync(sidecar, 'utf8')) as Record<string, { at: string; exits: number; detail: string }>;
+    for (const [id, record] of Object.entries(gaveUp)) {
+      const service = instance.services[id];
+      if (service) service.workerGaveUp = record;
+    }
+  } catch {
+    // Best-effort merge: a sidecar torn by a concurrent host-cli write must never break an
+    // instance.json read (the give-up record just fails to surface for this one read).
+  }
+}
+
+function readWorldInstance(name: string, root: string): WorldInstance {
+  const path = instanceFile(root, name);
+  if (!existsSync(path)) throw new Error(`World instance not found: ${name}`);
+  const instance = JSON.parse(readFileSync(path, 'utf8')) as WorldInstance;
+  mergeWorkerGaveUp(instance, path);
+  return instance;
+}
+
+function assertMode(mode: string): asserts mode is WorldMode {
+  if (mode !== 'local' && mode !== 'share' && mode !== 'sealed') throw new Error(`Invalid world mode: ${mode}`);
+}
+
+function getByJsonPath(value: unknown, jsonPath: string): unknown {
+  let current: unknown = value;
+  for (const rawSegment of jsonPath.split('.')) {
+    const segment = rawSegment.trim();
+    if (segment === '') continue;
+    if (current === null || current === undefined) return undefined;
+    if (Array.isArray(current)) {
+      const index = Number(segment);
+      if (!Number.isInteger(index)) return undefined;
+      current = current[index];
+    } else if (typeof current === 'object') {
+      current = (current as Record<string, unknown>)[segment];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+function runExternalCommand(
+  command: string[],
+  cwd: string,
+  serviceId: string,
+  phase: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { stdout: string; stderr: string } {
+  const [bin, ...args] = command;
+  if (!bin) throw new Error(`External service "${serviceId}": ${phase} command is empty`);
+  if (!commandExists(bin)) {
+    throw new Error(`External service "${serviceId}": \`${bin}\` not found on PATH (the ${phase} command's tool is not installed)`);
+  }
+  // 64MB ceiling (vs Node's 1MB default) so a chatty status/down doesn't ENOBUFS. The `up` phase
+  // uses runExternalUp (streamed, uncapped) since it's the one that restores DBs / boots stacks.
+  const result = spawnSync(bin, args, { cwd, encoding: 'utf8', env, maxBuffer: 64 * 1024 * 1024 });
+  if (result.error) {
+    throw new Error(`External service "${serviceId}": ${phase} command failed to run (${result.error.message})`);
+  }
+  if (result.status !== 0) {
+    const detail = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();
+    throw new Error(`External service "${serviceId}": ${phase} command exited ${result.status ?? 'null'}\n${detail}`);
+  }
+  return { stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+
+/** Run an external service's `up` command, STREAMING its stdout+stderr to the service log as it runs
+ * (instead of buffering through spawnSync's 1MB cap, which a large DB restore would overflow). Returns
+ * the combined output so `discover` can read it. Throws with a bounded tail on nonzero exit. */
+async function runExternalUp(
+  command: string[],
+  cwd: string,
+  serviceId: string,
+  env: NodeJS.ProcessEnv,
+  logPath: string,
+): Promise<string> {
+  const [bin, ...args] = command;
+  if (!bin) throw new Error(`External service "${serviceId}": up command is empty`);
+  if (!commandExists(bin)) {
+    throw new Error(`External service "${serviceId}": \`${bin}\` not found on PATH (the up command's tool is not installed)`);
+  }
+  writeFileSync(logPath, `$ ${command.join(' ')}\n`);
+  const out = openSync(logPath, 'a');
+  const chunks: string[] = [];
+  try {
+    const code = await new Promise<number | null>((resolveCode, reject) => {
+      const child = spawn(bin, args, { cwd, env });
+      child.on('error', reject);
+      const onData = (buf: Buffer) => {
+        const text = buf.toString('utf8');
+        chunks.push(text);
+        try { writeSync(out, text); } catch { /* best effort log */ }
+      };
+      child.stdout?.on('data', onData);
+      child.stderr?.on('data', onData);
+      child.on('close', (exitCode) => resolveCode(exitCode));
+    });
+    if (code !== 0) {
+      const detail = chunks.join('').trim().split('\n').slice(-40).join('\n');
+      throw new Error(`External service "${serviceId}": up command exited ${code ?? 'null'}\n${detail}`);
+    }
+  } finally {
+    closeSync(out);
+  }
+  return chunks.join('');
+}
+
+/** Resolve `${url}`/`${host}`/`${port}` in a readiness probe's httpUrl against an owned loopback
+ * service's allocated port (process/twin readiness — the port is auto-assigned, so it can't be a
+ * literal in the config). Other probe kinds (command/stdoutMatch) are returned unchanged. */
+function resolveReadyProbe(ready: WorldExternalReadyWhen, svc: { host: string; port: number; url: string }): WorldExternalReadyWhen {
+  if (ready.httpUrl === undefined) return ready;
+  const httpUrl = ready.httpUrl
+    .split('${url}').join(svc.url)
+    .split('${host}').join(svc.host)
+    .split('${port}').join(String(svc.port));
+  return { ...ready, httpUrl };
+}
+
+async function awaitReadiness(
+  ready: WorldExternalReadyWhen | undefined,
+  logPath: string,
+  cwd: string,
+  serviceId: string,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  if (!ready) return;
+  const timeoutMs = ready.timeoutMs ?? 60_000;
+  const intervalMs = ready.intervalMs ?? 500;
+  const started = Date.now();
+  let lastError = '';
+  while (Date.now() - started < timeoutMs) {
+    if (ready.command !== undefined) {
+      if (!commandExists(ready.command)) {
+        throw new Error(`Service "${serviceId}": readiness command \`${ready.command}\` not found on PATH`);
+      }
+      const result = spawnSync(ready.command, ready.args ?? [], { cwd, encoding: 'utf8', env, maxBuffer: 64 * 1024 * 1024 });
+      if (result.status === 0) return;
+      lastError = `command exited ${result.status ?? 'null'}: ${(result.stderr ?? '').trim()}`;
+    } else if (ready.httpUrl !== undefined) {
+      try {
+        const response = await fetch(ready.httpUrl);
+        if (response.status >= 200 && response.status < 400) return;
+        lastError = `HTTP ${response.status}`;
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+      }
+    } else if (ready.stdoutMatch !== undefined) {
+      const text = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
+      if (new RegExp(ready.stdoutMatch).test(text)) return;
+      lastError = `pattern /${ready.stdoutMatch}/ not yet in service log`;
+    }
+    await sleep(intervalMs);
+  }
+  throw new Error(`Service "${serviceId}": readiness probe timed out after ${timeoutMs}ms (${lastError || 'no probe matched'})`);
+}
+
+async function startExternalService(
+  service: WorldServiceConfig,
+  paths: { root: string; logs: string },
+  worldEnv: Record<string, string>,
+): Promise<WorldServiceInstance> {
+  const external = service.external;
+  if (!external) throw new Error(`External service "${service.id}" is missing its external config`);
+  const log = join(paths.logs, `${service.id}.log`);
+  // External commands see the accumulated world env (process.env + earlier services' discovered/
+  // injected vars), so a later external can consume an earlier service's connection info.
+  const env: NodeJS.ProcessEnv = { ...process.env, ...worldEnv };
+
+  // 1. up — start the self-managed stack, STREAMING its output to the service log (no 1MB cap).
+  const upOutput = await runExternalUp(external.up, paths.root, service.id, env, log);
+
+  // 2. readiness — Docker-backed externals take seconds to boot.
+  await awaitReadiness(external.readyWhen, log, paths.root, service.id, env);
+
+  // 3. status — discover connection info (optional; may reuse up output instead).
+  let statusOutput = '';
+  if (external.status) {
+    const statusResult = runExternalCommand(external.status, paths.root, service.id, 'status', env);
+    statusOutput = statusResult.stdout || statusResult.stderr;
+    appendFileSync(log, `\n$ ${external.status.join(' ')}\n${statusOutput}`);
+  }
+
+  // 4. discover — apply declarative mappings → injected env vars.
+  const injected: Record<string, string> = {};
+  const sources: Record<'status' | 'up', string> = {
+    status: statusOutput,
+    up: upOutput,
+  };
+  const jsonCache: Partial<Record<'status' | 'up', unknown>> = {};
+  for (const mapping of external.discover ?? []) {
+    const source = mapping.source ?? 'status';
+    const raw = sources[source];
+    let value: string | undefined;
+    if (mapping.jsonPath !== undefined) {
+      if (!(source in jsonCache)) {
+        try {
+          jsonCache[source] = JSON.parse(raw) as unknown;
+        } catch (error) {
+          throw new Error(`External service "${service.id}": discover "${mapping.as}" expected JSON from ${source} output but parse failed (${error instanceof Error ? error.message : String(error)})\nOutput: ${raw.slice(0, 500)}`);
+        }
+      }
+      const found = getByJsonPath(jsonCache[source], mapping.jsonPath);
+      value = found === undefined || found === null ? undefined : String(found);
+    } else if (mapping.pattern !== undefined) {
+      const match = new RegExp(mapping.pattern).exec(raw);
+      value = match?.groups?.value ?? match?.[1] ?? match?.[0];
+    }
+    if (value === undefined || value === '') {
+      throw new Error(`External service "${service.id}": discover "${mapping.as}" found ${value === '' ? 'an empty' : 'no'} value (jsonPath=${mapping.jsonPath ?? '-'} pattern=${mapping.pattern ?? '-'} source=${source})\nOutput: ${raw.slice(0, 500)}`);
+    }
+    injected[mapping.as] = value;
+  }
+
+  return {
+    id: service.id,
+    type: 'external',
+    command: [...external.up],
+    pid: 0,
+    log,
+    env: injected,
+    // Keep the discovered env on the instance so `down` can reference connection info it needs.
+    external: { down: [...external.down], cwd: paths.root, discoveredEnv: injected },
+  };
+}
+
+async function startService(
+  config: WorldConfig,
+  service: WorldServiceConfig,
+  worldEnv: Record<string, string>,
+  paths: { root: string; instance: string; logs: string; data: string },
+): Promise<WorldServiceInstance> {
+  if (service.type === 'external') return startExternalService(service, paths, worldEnv);
+  if (!service.command) throw new Error(`Service "${service.id}" must define command`);
+  const port = service.port === undefined || service.port === 'auto' ? await allocatePort() : service.port;
+  const serviceDataDir = join(paths.data, service.id);
+  mkdirSync(serviceDataDir, { recursive: true });
+
+  const args = [...(service.args ?? [])];
+  if (service.portArg !== false) args.push(service.portArg ?? '--port', String(port));
+  if (service.rootArg !== false) args.push(service.rootArg ?? '--root', serviceDataDir);
+
+  const log = join(paths.logs, `${service.id}.log`);
+  const out = openSync(log, 'a');
+  const env = serviceProcessEnv(config, service, worldEnv, port);
+  const cwd = service.cwd ? resolve(paths.root, service.cwd) : paths.root;
+
+  // Augment NODE_OPTIONS with declared extra preloads, so a service can add an app-local preload
+  // (e.g. a sandbox) WITHOUT replacing the world's injector. Paths resolve to absolute against the
+  // service cwd — Node's `--require` treats a bare relative specifier as a package name otherwise.
+  // (Setting service.env.NODE_OPTIONS directly still replaces the default — the explicit opt-out.)
+  if (service.preload?.length) {
+    const requires = service.preload.map((module) => `--require ${resolve(cwd, module)}`).join(' ');
+    env.NODE_OPTIONS = env.NODE_OPTIONS ? `${env.NODE_OPTIONS} ${requires}` : requires;
+  }
+  const child = spawn(service.command, args, {
+    cwd,
+    env,
+    detached: true,
+    stdio: ['ignore', out, out],
+  });
+  child.unref();
+
+  // Track an early exit. allocatePort() is TOCTOU (it closes its probe listener before the
+  // child binds), so if another/stale process already holds `port`, the child gets EADDRINUSE
+  // and dies — but waitForTcp would then see the OTHER process answering and the world would
+  // silently record this service's URL pointing at the WRONG twin (the multi-twin crossing
+  // bug). Detecting the child's own exit lets us fail LOUDLY instead.
+  // Object holder (not a bare `let`) so TS keeps the union type across the exit closure.
+  const exitState: { value: { code: number | null; signal: NodeJS.Signals | null } | null } = { value: null };
+  child.on('exit', (code, signal) => {
+    exitState.value = { code, signal };
+  });
+
+  await waitForTcp(port).catch((error) => {
+    try {
+      process.kill(-child.pid!, 'SIGTERM');
+    } catch {
+      // best effort cleanup
+    }
+    throw new Error(`Service "${service.id}" failed to start: ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+  });
+
+  if (exitState.value !== null) {
+    throw new Error(
+      `Service "${service.id}" exited during startup (code=${exitState.value.code}, signal=${exitState.value.signal}) even though port ${port} answers — `
+      + `the port is almost certainly held by another/stale process, so the twin never bound it. `
+      + `Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`,
+    );
+  }
+
+  const host = '127.0.0.1';
+  const url = `http://${host}:${port}`;
+
+  // Optional readiness probe beyond TCP (httpUrl/command/stdoutMatch): a process can bind its port
+  // before it is actually serving, so this makes `up` wait until the service truly responds.
+  if (service.ready && service.ready !== 'tcp') {
+    await awaitReadiness(resolveReadyProbe(service.ready, { host, port, url }), log, cwd, service.id, env).catch((error) => {
+      try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+      throw new Error(`Service "${service.id}" failed its readiness probe: ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+    });
+  }
+
+  return {
+    id: service.id,
+    type: service.type ?? 'twin',
+    command: [service.command, ...args],
+    port,
+    url,
+    pid: child.pid ?? 0,
+    log,
+    env: {
+      ...(service.injectEnv ? { [service.injectEnv]: url } : {}),
+      ...resolveServiceEnvTemplates(service.injectEnvTemplates, { host, port, url }),
+      ...resolveCliRedirect(service.cliRedirect, url),
+    },
+  };
+}
+
+/**
+ * Boot every `colocate`-declaring service inside ONE `volter-world-host` child (see src/host.ts —
+ * 'colocated' maps to the host's 'shared' mode, 'worker' to one Worker thread per twin). The
+ * recorded instances are shaped exactly like the spawn path's (port/url/injected env), except they
+ * all share the host child's pid — so pids/instance.json/downWorld need no special casing.
+ */
+async function startColocatedServices(
+  config: WorldConfig,
+  colocated: WorldServiceConfig[],
+  isolation: Exclude<WorldIsolation, 'process'>,
+  worldEnv: Record<string, string>,
+  paths: { root: string; instance: string; logs: string; data: string },
+): Promise<WorldServiceInstance[]> {
+  const hostCli = join(import.meta.dir, 'host-cli.ts');
+  const args: string[] = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
+  const allocated: Array<{ service: WorldServiceConfig; port: number }> = [];
+  for (const service of colocated) {
+    const port = service.port === undefined || service.port === 'auto' ? await allocatePort() : service.port;
+    const serviceDataDir = join(paths.data, service.id);
+    mkdirSync(serviceDataDir, { recursive: true });
+    // Relative module paths resolve from the world root (import() inside the host would
+    // otherwise resolve them against the runtime's own source directory).
+    const module = service.colocate!.module.startsWith('.') ? resolve(paths.root, service.colocate!.module) : service.colocate!.module;
+    args.push('--spec', [service.id, module, service.colocate!.export, String(port), serviceDataDir].join('|'));
+    allocated.push({ service, port });
+  }
+
+  const log = join(paths.logs, 'host.log');
+  const out = openSync(log, 'a');
+  // The host is world infrastructure, not an app process — same egress hygiene as controlPlane
+  // services (no injector preload, no ambient proxy): its twins SERVE, they don't call vendors.
+  const env: Record<string, string> = { ...process.env as Record<string, string>, ...(config.env ?? {}), ...worldEnv };
+  for (const key of CONTROL_PLANE_EGRESS_ENV) delete env[key];
+  const child = spawn(process.execPath, args, {
+    cwd: paths.root,
+    env,
+    detached: true,
+    stdio: ['ignore', out, out],
+  });
+  child.unref();
+
+  const exitState: { value: { code: number | null; signal: NodeJS.Signals | null } | null } = { value: null };
+  child.on('exit', (code, signal) => {
+    exitState.value = { code, signal };
+  });
+
+  const command = [process.execPath, ...args];
+  for (const { service, port } of allocated) {
+    await waitForTcp(port).catch((error) => {
+      try { process.kill(-child.pid!, 'SIGTERM'); } catch { /* best effort cleanup */ }
+      throw new Error(`Co-located twin "${service.id}" failed to start (host isolation=${isolation}): ${error instanceof Error ? error.message : String(error)}\nLog: ${log}`);
+    });
+  }
+  if (exitState.value !== null) {
+    throw new Error(
+      `The co-located host exited during startup (code=${exitState.value.code}, signal=${exitState.value.signal}) even though its ports answer — `
+      + `they are almost certainly held by other/stale processes. Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`,
+    );
+  }
+
+  const host = '127.0.0.1';
+  return allocated.map(({ service, port }) => {
+    const url = `http://${host}:${port}`;
+    return {
+      id: service.id,
+      type: service.type ?? 'twin',
+      command,
+      port,
+      url,
+      pid: child.pid ?? 0,
+      log,
+      env: {
+        ...(service.injectEnv ? { [service.injectEnv]: url } : {}),
+        ...resolveServiceEnvTemplates(service.injectEnvTemplates, { host, port, url }),
+        ...resolveCliRedirect(service.cliRedirect, url),
+      },
+    };
+  });
+}
+
+export async function upWorld(configId: string, options: UpWorldOptions = {}): Promise<WorldInstance> {
+  const root = resolve(options.root ?? process.cwd());
+  const loaded = loadWorldConfig(configId, root);
+  const name = options.name ?? loaded.config.id;
+  const mode = options.mode ?? 'local';
+  assertSafeWorldName(name);
+  assertMode(mode);
+  const isolation = options.isolation ?? loaded.config.isolation ?? 'process';
+  // TWIN-67: schema.ts's WorldIsolation contract says process isolation ("one OS process per
+  // service") is "the only choice for share/sealed/hosted worlds" — colocating twins in one host
+  // process (or worker threads, which still share that process) under `share`/`sealed` puts a
+  // semi-untrusted session on colocated twins sharing one host process, exactly what the
+  // contract forbids. Enforce it here instead of leaving it a comment nothing checks. Checked
+  // before the file-lock claim / any dir creation below, so a rejected combination leaves nothing
+  // to clean up.
+  if (mode !== 'local' && isolation !== 'process') {
+    throw new Error(
+      `world "${name}": mode "${mode}" requires isolation "process" (schema.ts: process isolation is the only choice for share/sealed/hosted worlds), got isolation "${isolation}". Use --isolation process (or omit --isolation) with --mode ${mode}.`,
+    );
+  }
+
+  const instance = instanceDir(root, name);
+  const logs = join(instance, 'logs');
+  const data = join(instance, 'data');
+  const pidsFile = join(instance, 'pids');
+  const envFile = resolve(root, options.envFile ?? join(instance, 'world.env'));
+  const instanceFile = join(instance, 'instance.json');
+
+  // Claim the instance dir under the kernel's cross-process file lock (TWIN-36). Without it,
+  // two concurrent `upWorld` calls on one name can both observe "no live pids", both rmSync the
+  // dir, and one clobbers the other's freshly-spawned services (orphaned processes + a corrupt
+  // instance dir). The lock guards only the SYNCHRONOUS claim below — check, wipe, re-create,
+  // write `booting.json` — so it is held for milliseconds and never spans the async service boot
+  // (which can exceed withFileLock's 10s contender timeout); the booting marker written inside
+  // the lock is what keeps contenders out for the boot's whole duration, and a contender that
+  // finds a live booter fails FAST with a clear error instead of waiting on an open-ended boot.
+  // The claim fn has no awaits, so two in-process callers cannot interleave inside it either;
+  // the lockfile adds the cross-process exclusion, and an in-process lock holder always releases
+  // before its first await, so withFileLock's synchronous contender wait can never deadlock the
+  // event loop against a holder in the same process.
+  withFileLock(instanceLockFile(root, name), () => {
+    const live = livePids(readPids(pidsFile));
+    if (live.length > 0) {
+      throw new Error(`World "${name}" is already running (${live.join(', ')}). Run: volter-world down ${name}`);
+    }
+    const booting = liveBootingClaim(bootingFile(root, name));
+    if (booting) {
+      throw new Error(
+        `World "${name}" is being booted by another process (pid ${booting.pid}, since ${booting.at}). Retry after it finishes (a dead booter's claim is reclaimed automatically).`,
+      );
+    }
+    rmSync(instance, { recursive: true, force: true });
+    mkdirSync(logs, { recursive: true });
+    mkdirSync(data, { recursive: true });
+    writeFileSync(bootingFile(root, name), `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() } satisfies BootingClaim)}\n`);
+  });
+
+  // From here on this call owns the claim; the finally below releases it however the boot
+  // settles. On success the recorded live pids (written before returning) take over as the
+  // "already running" guard; on failure the world never came up, so the next upWorld must be
+  // allowed to claim. Removing the marker is safe — only THIS call's marker can exist at this
+  // point (a foreign live claim made the claim section above throw before this try).
+  try {
+    const services: Record<string, WorldServiceInstance> = {};
+    const env: Record<string, string> = {
+      ...(loaded.config.env ?? {}),
+      VOLTER_WORLD_NAME: name,
+      VOLTER_WORLD_MODE: mode,
+      VOLTER_WORLD_CONFIG: loaded.path,
+      VOLTER_WORLD_INSTANCE: instanceFile,
+      // VOLTER_WORLD_SEALED is intent-only; VOLTER_TWIN_STRICT_EGRESS is what the ENFORCEMENT
+      // points actually gate on (redirect-proxy.ts's CONNECT/plain-proxy handlers and
+      // control-plane/inject.cjs's patched http/https/fetch) — both block any untwinned
+      // non-loopback host once this is set. Without it "sealed" only records intent and every
+      // untwinned host is blind-tunneled to the real internet (TWIN-60).
+      ...(mode === 'sealed' ? { VOLTER_WORLD_SEALED: '1', VOLTER_TWIN_STRICT_EGRESS: '1' } : {}),
+      NODE_OPTIONS: `--require ${injectPreloadSpecifier()}${process.env.NODE_OPTIONS ? ` ${process.env.NODE_OPTIONS}` : ''}`,
+    };
+    env.NO_PROXY = process.env.NO_PROXY ? `127.0.0.1,localhost,${process.env.NO_PROXY}` : '127.0.0.1,localhost';
+    env.no_proxy = process.env.no_proxy ? `127.0.0.1,localhost,${process.env.no_proxy}` : '127.0.0.1,localhost';
+    writeProxyEnv(root, name, env);
+
+    try {
+      // Non-'process' isolation: boot every colocate-declaring service inside ONE host child
+      // first; anything without `colocate` (and externals) still goes through the spawn path.
+      if (isolation !== 'process') {
+        const colocated = loaded.config.services.filter((service) => service.colocate && service.type !== 'external');
+        for (const started of await startColocatedServices(loaded.config, colocated, isolation, env, { root, instance, logs, data })) {
+          services[started.id] = started;
+          Object.assign(env, started.env);
+        }
+        writeProxyEnv(root, name, env);
+      }
+      let proxyForServices: ReturnType<typeof ensureWorldProxyFromEnv> | null = null;
+      // TWIN-64: attempt the ambient proxy once activeVendorMap(env) has at least one twin — tried
+      // again after each service in case ITS start is what makes the map non-empty. A sealed world
+      // must never come up silently unsealed: if openssl itself is unavailable (no proxy is even
+      // possible) or the proxy daemon fails/times out, refuse rather than let unmodified CLIs bypass
+      // the twins undetected.
+      const attemptProxy = (): void => {
+        if (proxyForServices || Object.keys(activeVendorMap(env)).length === 0) return;
+        if (!opensslAvailable()) {
+          if (mode === 'sealed') {
+            throw new Error(
+              `sealed world "${name}": openssl is unavailable — the ambient redirect proxy cannot start, so unmodified CLIs (curl, gh, stripe, …) could bypass the twins undetected; refusing to come up unsealed. Install openssl or use --mode local.`,
+            );
+          }
+          return;
+        }
+        proxyForServices = ensureWorldProxyFromEnv(name, root, env);
+        if (proxyForServices?.url) {
+          Object.assign(env, proxyForServices.env);
+        } else if (mode === 'sealed') {
+          // The ambient redirect proxy timed out (see the loud WARN already emitted by
+          // ensureWorldProxyFromEnv). Composes with the existing catch below: stops the proxy
+          // daemon, kills started services, rethrows.
+          throw new Error(`sealed world "${name}": ambient redirect proxy failed to start — refusing to come up unsealed`);
+        }
+      };
+      for (const service of loaded.config.services) {
+        if (services[service.id]) continue; // already up co-located
+        attemptProxy();
+        const started = await startService(loaded.config, service, env, { root, instance, logs, data });
+        services[started.id] = started;
+        Object.assign(env, started.env);
+        writeProxyEnv(root, name, env);
+      }
+      // Re-evaluate once more after the LAST service: a single/last-twin world's OWN vendor twin
+      // only lands in `env` once IT has started, so a check that only runs "before starting the
+      // next service" never fires when there is no next service (TWIN-64) — the single-twin sealed
+      // config test below exercises exactly this.
+      attemptProxy();
+    } catch (error) {
+      stopWorldProxy(root, name);
+      const pids = [...new Set(Object.values(services).map((service) => service.pid).filter(Boolean))];
+      signalPids(pids, 'SIGTERM');
+      // Stop any self-managed externals that DID come up, so a failed `up` never leaves a
+      // half-running external stack behind. Best-effort: the original error is what we throw —
+      // but a `down` that ITSELF fails must not be silent (the operator would have no hint that
+      // an external stack is still half-running), so those failures are appended to its message.
+      const rollbackErrors: string[] = [];
+      for (const service of Object.values(services)) {
+        if (service.type === 'external' && service.external) {
+          // Same env shape as up/status (startExternalService) and downWorld's teardown:
+          // process.env underneath so the tool is even findable on PATH — without it every
+          // rollback `down` died with "Executable not found" (silently, until surfaced below).
+          const downEnv = { ...process.env, ...env, ...(service.external.discoveredEnv ?? {}) };
+          try {
+            runExternalCommand(service.external.down, service.external.cwd, service.id, 'down', downEnv);
+          } catch (downError) {
+            rollbackErrors.push(downError instanceof Error ? downError.message : String(downError));
+          }
+        }
+      }
+      // Same SIGTERM→SIGKILL contract as downWorld: a service that ignores SIGTERM must not
+      // outlive a failed boot either. The poll exits as soon as everything is dead, so the
+      // common case (services honor SIGTERM) adds no delay to the failure path.
+      await killSurvivorsAfterGrace(pids, DOWN_GRACE_MS_DEFAULT);
+      if (rollbackErrors.length > 0) {
+        const suffix = `\n(rollback: external down failed — the stack may still be half-running: ${rollbackErrors.join('; ')})`;
+        // Mutate rather than re-wrap: callers match on the ORIGINAL message (which must keep
+        // leading) and the original stack/type stay intact.
+        if (error instanceof Error) error.message += suffix;
+        else throw new Error(`${String(error)}${suffix}`);
+      }
+      throw error;
+    }
+
+    const worldInstance: WorldInstance = {
+      name,
+      config: loaded.config.id,
+      configPath: loaded.path,
+      root,
+      createdAt: new Date().toISOString(),
+      mode,
+      dirs: { instance, logs, data },
+      services,
+      env,
+      envFile,
+      pidsFile,
+      ...(loaded.config.actors ? { actors: loaded.config.actors } : {}),
+      ...(loaded.config.fixtures ? { fixtures: loaded.config.fixtures } : {}),
+    };
+
+    mkdirSync(dirname(envFile), { recursive: true });
+    writeFileSync(envFile, envFileContents(env));
+    writePidsFromInstance(worldInstance);
+    saveWorldInstance(worldInstance);
+    if (mode === 'share') {
+      try {
+        return await shareWorldServices(name, { root, ...(options.share ?? {}) });
+      } catch (error) {
+        await downWorld(name, root);
+        throw error;
+      }
+    }
+    return worldInstance;
+  } finally {
+    rmSync(bootingFile(root, name), { force: true });
+  }
+}
+
+function teardownExternalServices(instance: WorldInstance): { stopped: string[]; errors: string[] } {
+  const stopped: string[] = [];
+  const errors: string[] = [];
+  for (const service of Object.values(instance.services)) {
+    if (service.type !== 'external' || !service.external) continue;
+    const downEnv = { ...process.env, ...(instance.env ?? {}), ...(service.external.discoveredEnv ?? {}) };
+    try {
+      runExternalCommand(service.external.down, service.external.cwd, service.id, 'down', downEnv);
+      stopped.push(service.id);
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return { stopped, errors };
+}
+
+/** SIGTERM contract (documented in WORLD.md § Teardown): services get SIGTERM to their process
+ * GROUP, then `downWorld` waits up to this grace for them to exit before SIGKILLing survivors.
+ * Overridable per call via `options.graceMs` (the CLI exposes `--grace-ms`). */
+const DOWN_GRACE_MS_DEFAULT = 5_000;
+
+/** Signal each pid's process GROUP (services are spawned `detached`, so each pid is a group
+ * leader), falling back to the single pid when the group signal fails. Returns the pids that
+ * accepted the signal. */
+function signalPids(pids: number[], signal: NodeJS.Signals): number[] {
+  const signalled: number[] = [];
+  for (const pid of pids) {
+    try {
+      process.kill(-pid, signal);
+      signalled.push(pid);
+    } catch {
+      try {
+        process.kill(pid, signal);
+        signalled.push(pid);
+      } catch {}
+    }
+  }
+  return signalled;
+}
+
+/** A zombie (exited but unreaped — e.g. its spawning `up` process is gone and this machine's
+ * PID 1 doesn't reap orphans, as in minimal containers) still answers `kill(pid, 0)` yet is dead
+ * for every practical purpose: it holds no ports and cannot receive SIGKILL. The escalation
+ * grace must not wait out a zombie — or worse, report "escalating" one. Linux: state field from
+ * /proc (the char right after the parenthesized comm). Elsewhere (macOS has no /proc): `ps`. */
+function zombiePid(pid: number): boolean {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    return stat.slice(stat.lastIndexOf(')') + 2).charAt(0) === 'Z';
+  } catch {
+    const result = spawnSync('ps', ['-o', 'state=', '-p', String(pid)], { encoding: 'utf8' });
+    return result.status === 0 && result.stdout.trim().startsWith('Z');
+  }
+}
+
+/** Pids from `pids` that are neither dead nor zombied — i.e. still need killing. Shared by both
+ * the async and sync flavors of the grace-then-SIGKILL poll below. */
+function undeadPids(pids: number[]): number[] {
+  return livePids(pids).filter((pid) => !zombiePid(pid));
+}
+
+/** Bounded extra wait (ms) for a pid to actually finish dying once SIGKILL has been sent. SIGKILL
+ * cannot be caught/blocked, but delivery + the kernel's exit transition is not instantaneous —
+ * callers that gate on "confirmed dead" (purge, unshareWorld) need this, not just the signal sent. */
+const KILL_CONFIRM_MS = 2_000;
+
+/** The SIGKILL half of SIGTERM→SIGKILL escalation: bounded poll on pid liveness (returns as soon
+ * as everything is dead — no fixed sleep), then SIGKILL whatever survived the grace, group-first
+ * exactly like the SIGTERM was delivered, then a short bounded confirm-wait so survivors are
+ * actually gone (not just signalled) by the time this returns. Returns the pids that needed
+ * escalation. */
+async function killSurvivorsAfterGrace(pids: number[], graceMs: number): Promise<number[]> {
+  const deadline = Date.now() + graceMs;
+  while (undeadPids(pids).length > 0 && Date.now() < deadline) {
+    await new Promise((resolveWait) => setTimeout(resolveWait, 50));
+  }
+  const survivors = undeadPids(pids);
+  signalPids(survivors, 'SIGKILL');
+  const confirmDeadline = Date.now() + KILL_CONFIRM_MS;
+  while (undeadPids(survivors).length > 0 && Date.now() < confirmDeadline) {
+    await new Promise((resolveWait) => setTimeout(resolveWait, 20));
+  }
+  return survivors;
+}
+
+/** Synchronous twin of `killSurvivorsAfterGrace` for callers (`unshareWorld`) that must stay
+ * synchronous — same "poll until dead or grace expires, then SIGKILL survivors, then confirm they
+ * are actually gone" contract, using an `Atomics.wait` backoff (already this file's pattern for
+ * synchronous polling — see `ensureWorldProxy`) instead of `setTimeout`, since a sync function has
+ * no event loop to yield to. */
+function killSurvivorsAfterGraceSync(pids: number[], graceMs: number): number[] {
+  const deadline = Date.now() + graceMs;
+  while (undeadPids(pids).length > 0 && Date.now() < deadline) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+  }
+  const survivors = undeadPids(pids);
+  signalPids(survivors, 'SIGKILL');
+  const confirmDeadline = Date.now() + KILL_CONFIRM_MS;
+  while (undeadPids(survivors).length > 0 && Date.now() < confirmDeadline) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+  }
+  return survivors;
+}
+
+/** Async solely for the SIGTERM→SIGKILL grace poll — everything else (proxy stop, SIGTERM,
+ * external teardown) still runs in the first synchronous slice, so a legacy caller that fires
+ * without awaiting gets exactly the old behavior plus the deferred escalation. A blocking
+ * sleep-loop would keep the sync signature but stall the caller's event loop for up to the whole
+ * grace; a detached watchdog child would escalate too but leak orphan processes — the await is
+ * the honest shape (upWorld/runWorld/the CLI are already async). */
+/**
+ * Delete a world's instance dir entirely — the `--purge` half of `down` (TWIN-45 dev/02b): no
+ * twin data (per-service `data/<id>`, logs, instance.json) survives past teardown. Plain `rm`,
+ * same honesty as `world scrub` on the control-plane side (see docs/DATA_AT_REST.md).
+ *
+ * Safety (never delete more than THIS world's own instance dir):
+ *  - `assertSafeWorldName` rejects any name containing `/` or starting with `.` — the only
+ *    names `instanceDir`/`instanceLockFile` can ever have produced — so `dir` cannot resolve
+ *    outside `worldBaseDir(root)` and cannot collide with a sibling instance's directory.
+ *  - `dir` is asserted to be an actual child of `worldBaseDir(root)` (defense in depth against
+ *    a future refactor of `instanceDir` weakening that guarantee) and can never equal
+ *    `worldBaseDir` itself (which would nuke every world) or its `.locks` sibling.
+ *  - The per-world claim lock (`instanceLockFile`) lives OUTSIDE the instance dir precisely so
+ *    `upWorld`'s claim survives an in-flight `rmSync` of the instance dir (see its own comment);
+ *    purge cleans up this world's own leftover lock file by exact name — never the `.locks` dir,
+ *    never another world's `.lock` file.
+ */
+function purgeInstanceDir(root: string, name: string): string {
+  assertSafeWorldName(name);
+  const base = worldBaseDir(root);
+  const dir = instanceDir(root, name);
+  const rel = relative(base, dir);
+  if (!rel || rel === '.' || rel.startsWith('..') || rel.split(sep)[0] !== name) {
+    throw new Error(`Refusing to purge: resolved instance dir "${dir}" is not a direct child of "${base}"`);
+  }
+  rmSync(dir, { recursive: true, force: true });
+  rmSync(instanceLockFile(root, name), { force: true }); // this world's own claim lock, if left over
+  return dir;
+}
+
+export async function downWorld(
+  name: string,
+  root = process.cwd(),
+  options: { graceMs?: number; purge?: boolean } = {},
+): Promise<{ name: string; stopped: number[]; escalated: number[]; externalStopped: string[]; externalErrors: string[]; purged?: string }> {
+  const resolvedRoot = resolve(root);
+  const dir = instanceDir(resolvedRoot, name);
+  const pidsFile = join(dir, 'pids');
+  // Tear down the ambient-redirect proxy + its session CA FIRST, so the trusted CA never outlives
+  // the world (it was only ever trusted via per-shell env, never system-wide).
+  stopWorldProxy(resolvedRoot, name);
+  const pids = readPids(pidsFile);
+  const stopped = signalPids(pids, 'SIGTERM');
+
+  // Stop self-managed externals via their declared `down` command. Tolerate a missing
+  // instance file (nothing to tear down), but surface external `down` failures to the caller.
+  let externalStopped: string[] = [];
+  let externalErrors: string[] = [];
+  try {
+    const instance = readWorldInstance(name, resolvedRoot);
+    const result = teardownExternalServices(instance);
+    externalStopped = result.stopped;
+    externalErrors = result.errors;
+  } catch {
+    // no instance.json (never fully came up) — only owned processes needed stopping.
+  }
+
+  // Escalate AFTER the (synchronous) external teardown so externals never wait on the grace, and
+  // poll the full pids list rather than `stopped`: a pid whose SIGTERM errored is almost always
+  // already dead, and livePids() re-checks anyway.
+  const escalated = await killSurvivorsAfterGrace(pids, options.graceMs ?? DOWN_GRACE_MS_DEFAULT);
+
+  rmSync(pidsFile, { force: true });
+
+  // Purge LAST, only after every process (including SIGKILL escalations) is confirmed dead —
+  // removing the instance dir out from under a still-running service would orphan it with no
+  // recorded pid to ever find it again.
+  if (!options.purge) return { name, stopped, escalated, externalStopped, externalErrors };
+  if (externalErrors.length > 0) {
+    // TWIN-61: instance.json is the ONLY record of a self-managed external's `down` command and
+    // discovered env (schema.ts's WorldServiceInstance.external). If its `down` just failed, the
+    // external stack is (probably) still running — deleting that record here would leave the
+    // operator with a live external and no way to ever find how to stop it again. Skip the rmSync
+    // and report the failure via `externalErrors` (already populated above); `purged` stays
+    // undefined so the caller can tell purge did NOT happen.
+    return { name, stopped, escalated, externalStopped, externalErrors };
+  }
+  const purged = purgeInstanceDir(resolvedRoot, name);
+  return { name, stopped, escalated, externalStopped, externalErrors, purged };
+}
+
+export function statusWorld(name: string, root = process.cwd()): WorldInstance & { running: boolean; livePids: number[] } {
+  const worldInstance = readWorldInstance(name, resolve(root));
+  const live = livePids(readPids(worldInstance.pidsFile));
+  return { ...worldInstance, running: live.length > 0, livePids: live };
+}
+
+function shareCommand(options: ShareWorldOptions, serviceUrl: string): { provider: 'cloudflare-quick' | 'command'; command: string; args: string[] } {
+  if (!options.command && options.provider === 'command') {
+    throw new Error(`share provider "command" requires a tunnel command (share.command / --command)`);
+  }
+  if (options.command) {
+    return {
+      provider: options.provider ?? 'command',
+      command: options.command,
+      args: (options.args ?? []).map((arg) => arg.replaceAll('{url}', serviceUrl)),
+    };
+  }
+  return {
+    provider: 'cloudflare-quick',
+    command: 'cloudflared',
+    args: ['tunnel', '--url', serviceUrl],
+  };
+}
+
+async function waitForPublicUrl(child: ReturnType<typeof spawn>, logPath: string, timeoutMs: number, requireTryCloudflare: boolean): Promise<string> {
+  const urlPattern = /https:\/\/[a-zA-Z0-9.-]+/g;
+  let exited = false;
+  let exitSummary = '';
+  child.once('exit', (code, signal) => {
+    exited = true;
+    exitSummary = `code=${code ?? 'null'} signal=${signal ?? 'null'}`;
+  });
+  child.once('error', (error) => {
+    exited = true;
+    exitSummary = error.message;
+  });
+
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const text = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
+    const matches = text.match(urlPattern);
+    const url = requireTryCloudflare
+        ? matches?.find((candidate) => candidate.includes('trycloudflare.com'))
+        : matches?.find((candidate) => candidate.includes('trycloudflare.com')) ?? matches?.[0];
+    if (url) return url;
+    if (exited) throw new Error(`Tunnel process exited before printing a public URL (${exitSummary}). Log: ${logPath}`);
+    await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+  }
+  throw new Error(`Tunnel did not print a public https URL within ${timeoutMs}ms. Log: ${logPath}`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolveWait) => setTimeout(resolveWait, ms));
+}
+
+function commandExists(command: string): boolean {
+  // Pass the live env so PATH reflects the current process (some runtimes snapshot env otherwise).
+  const result = spawnSync('which', [command], { stdio: 'ignore', env: process.env });
+  return result.status === 0;
+}
+
+function resolveWithPublicDns(hostname: string): string | undefined {
+  const result = spawnSync('dig', ['+short', '@1.1.1.1', hostname, 'A'], {
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) return undefined;
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => /^\d{1,3}(?:\.\d{1,3}){3}$/.test(line));
+}
+
+async function waitForPublicDns(hostname: string, timeoutMs: number): Promise<string | undefined> {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const ip = resolveWithPublicDns(hostname);
+    if (ip) return ip;
+    await sleep(1_000);
+  }
+  return undefined;
+}
+
+function publicHealthUrl(publicUrl: string, path: string): string {
+  const url = new URL(publicUrl);
+  url.pathname = path.startsWith('/') ? path : `/${path}`;
+  url.search = '';
+  url.hash = '';
+  return url.toString();
+}
+
+async function verifyPublicUrl(
+  publicUrl: string,
+  path: string,
+  timeoutMs: number,
+): Promise<NonNullable<WorldServiceInstance['publicVerification']>> {
+  if (!commandExists('dig')) throw new Error('Public URL verification requires dig');
+  if (!commandExists('curl')) throw new Error('Public URL verification requires curl');
+  const hostname = new URL(publicUrl).hostname;
+  const started = Date.now();
+  const resolvedIp = await waitForPublicDns(hostname, Math.min(timeoutMs, 60_000));
+  if (!resolvedIp) {
+    throw new Error(`Public URL did not resolve through @1.1.1.1 within ${Math.min(timeoutMs, 60_000)}ms: ${hostname}`);
+  }
+
+  const target = publicHealthUrl(publicUrl, path);
+  let lastError = '';
+  while (Date.now() - started < timeoutMs) {
+    const remainingMs = Math.max(timeoutMs - (Date.now() - started), 1);
+    const result = spawnSync(
+      'curl',
+      [
+        '-sS',
+        '-o',
+        '-',
+        '-w',
+        '\n%{http_code}',
+        '--max-time',
+        String(Math.min(10, Math.max(1, Math.ceil(remainingMs / 1000)))),
+        '--resolve',
+        `${hostname}:443:${resolvedIp}`,
+        target,
+      ],
+      { encoding: 'utf8' },
+    );
+    if (result.status === 0) {
+      const output = result.stdout;
+      const separator = output.lastIndexOf('\n');
+      const body = separator >= 0 ? output.slice(0, separator).trim() : output.trim();
+      const status = Number(separator >= 0 ? output.slice(separator + 1).trim() : '0');
+      if (status >= 200 && status < 400) {
+        return {
+          path,
+          checkedAt: new Date().toISOString(),
+          hostname,
+          resolvedIp,
+          status,
+          body: body.slice(0, 500),
+        };
+      }
+      lastError = `HTTP ${status}${body ? `: ${body.slice(0, 200)}` : ''}`;
+    } else {
+      lastError = result.stderr.trim() || `curl exited ${result.status}`;
+    }
+    await sleep(Math.min(2_000, Math.max(timeoutMs - (Date.now() - started), 0)));
+  }
+  throw new Error(`Public URL did not pass health verification at ${target}: ${lastError || 'timed out'}`);
+}
+
+export async function shareWorld(name: string, options: ShareWorldOptions = {}): Promise<WorldInstance> {
+  const root = resolve(options.root ?? process.cwd());
+  const serviceId = options.service ?? 'app';
+  const instance = readWorldInstance(name, root);
+  const service = instance.services[serviceId];
+  if (!service) throw new Error(`World "${name}" has no service "${serviceId}"`);
+  if (service.tunnel && livePids([service.tunnel.pid]).length > 0) {
+    throw new Error(`World "${name}" service "${serviceId}" is already shared at ${service.publicUrl}`);
+  }
+  if (!service.url) {
+    throw new Error(`World "${name}" service "${serviceId}" has no local URL to share (external/self-managed services are not assigned one)`);
+  }
+
+  const tunnel = shareCommand(options, service.url);
+  const log = join(instance.dirs.logs, `${serviceId}.tunnel.log`);
+  const out = openSync(log, 'a');
+  const child = spawn(tunnel.command, tunnel.args, {
+    cwd: root,
+    env: process.env,
+    detached: true,
+    stdio: ['ignore', out, out],
+  });
+  closeSync(out);
+
+  let publicUrl: string;
+  let publicVerification: WorldServiceInstance['publicVerification'];
+  try {
+    publicUrl = await waitForPublicUrl(child, log, options.timeoutMs ?? 20_000, tunnel.provider === 'cloudflare-quick');
+    if (options.verifyPath !== false) {
+      publicVerification = await verifyPublicUrl(publicUrl, options.verifyPath ?? '/health', options.timeoutMs ?? 90_000);
+    }
+  } catch (error) {
+    // TWIN-62: never-half-shared means the tunnel must actually be confirmed dead before we
+    // rethrow, not just best-effort SIGTERM'd — the same SIGTERM→grace→SIGKILL contract `downWorld`
+    // gives owned services (a cloudflared that ignores SIGTERM must not keep serving after a
+    // failed/rejected `share`).
+    if (child.pid) {
+      signalPids([child.pid], 'SIGTERM');
+      await killSurvivorsAfterGrace([child.pid], DOWN_GRACE_MS_DEFAULT);
+    }
+    throw error;
+  }
+  child.unref();
+
+  service.publicUrl = publicUrl;
+  service.publicUrlEphemeral = tunnel.provider === 'cloudflare-quick';
+  service.publicReady = options.verifyPath !== false;
+  if (publicVerification) service.publicVerification = publicVerification;
+  else delete service.publicVerification;
+  service.tunnel = {
+    provider: tunnel.provider,
+    pid: child.pid ?? 0,
+    log,
+    command: [tunnel.command, ...tunnel.args],
+    startedAt: new Date().toISOString(),
+  };
+  writePidsFromInstance(instance);
+  saveWorldInstance(instance);
+  return instance;
+}
+
+function configuredShareTargets(
+  instance: WorldInstance,
+  requestedService?: string,
+  verifyPath?: string | false,
+): Array<{ id: string; verifyPath?: string | false }> {
+  if (requestedService) return [{ id: requestedService, verifyPath }];
+  const config = loadWorldConfig(instance.configPath, instance.root).config;
+  if (config.share?.services.length) {
+    return config.share.services.map((service) => ({
+      id: service.id,
+      verifyPath: verifyPath ?? service.verifyPath,
+    }));
+  }
+  return [{ id: 'app', verifyPath }];
+}
+
+export async function shareWorldServices(name: string, options: ShareWorldServicesOptions = {}): Promise<WorldInstance> {
+  const root = resolve(options.root ?? process.cwd());
+  let instance = readWorldInstance(name, root);
+  const config = loadWorldConfig(instance.configPath, instance.root).config;
+  const targets = configuredShareTargets(instance, options.service, options.verifyPath);
+  for (const target of targets) {
+    instance = await shareWorld(name, {
+      ...options,
+      root,
+      provider: options.provider ?? config.share?.provider,
+      command: options.command ?? config.share?.command,
+      args: options.args ?? config.share?.args,
+      service: target.id,
+      verifyPath: target.verifyPath,
+    });
+  }
+  return instance;
+}
+
+/** TWIN-62: `unshare` must give tunnels the same contract plain `downWorld` already gives owned
+ * services — SIGTERM, confirm dead (escalating to SIGKILL past the grace), and only THEN erase the
+ * tunnel facts/pids. A best-effort SIGTERM with no confirmation can leave a `cloudflared` that
+ * ignores SIGTERM serving the public URL forever while instance.json (and the pids file) say
+ * nothing is shared — the exact "half-shared" state WORLD.md promises cannot exist. Stays
+ * synchronous (via `killSurvivorsAfterGraceSync`) to match the existing signature/call sites
+ * (the CLI does not await it). Returns the instance plus the tunnel pids that needed escalating,
+ * for callers that want to report it. */
+export function unshareWorld(name: string, options: { root?: string; service?: string; graceMs?: number } = {}): WorldInstance & { escalated: number[] } {
+  const root = resolve(options.root ?? process.cwd());
+  const instance = readWorldInstance(name, root);
+  const serviceIds = options.service ? [options.service] : Object.keys(instance.services);
+  const escalated: number[] = [];
+  const stillLive: string[] = [];
+  for (const serviceId of serviceIds) {
+    const service = instance.services[serviceId];
+    if (!service) throw new Error(`World "${name}" has no service "${serviceId}"`);
+    if (service.tunnel?.pid) {
+      const pid = service.tunnel.pid;
+      signalPids([pid], 'SIGTERM');
+      const survivors = killSurvivorsAfterGraceSync([pid], options.graceMs ?? DOWN_GRACE_MS_DEFAULT);
+      if (survivors.length > 0) escalated.push(...survivors);
+      // `undeadPids` (not the raw `livePids`) is the right "confirmed dead" test here: a zombie
+      // (exited but unreaped — likely since we just polled it synchronously via `Atomics.wait`,
+      // which blocks the event loop that would otherwise let this process auto-reap its child) still
+      // answers `kill(pid, 0)` yet is dead for every practical purpose — see `zombiePid`'s own
+      // comment. Using plain `livePids` here would treat every zombie as "still shared".
+      if (undeadPids([pid]).length > 0) {
+        // Even SIGKILL didn't confirm it dead (e.g. no permission to signal it) — refuse to erase
+        // the only record of this tunnel rather than orphan it with instance.json saying "unshared".
+        stillLive.push(serviceId);
+        continue;
+      }
+    }
+    delete service.publicUrl;
+    delete service.publicUrlEphemeral;
+    delete service.publicReady;
+    delete service.publicVerification;
+    delete service.tunnel;
+  }
+  writePidsFromInstance(instance);
+  saveWorldInstance(instance);
+  if (stillLive.length > 0) {
+    throw new Error(`World "${name}": tunnel process(es) for ${stillLive.join(', ')} could not be confirmed dead (even after SIGKILL) — refusing to erase their records`);
+  }
+  return Object.assign(instance, { escalated });
+}
+
+/** Short, hardcoded timeout for `doctorWorld`'s external re-probe (TWIN-68) — this is a health
+ * CHECK, not a boot wait, so it must never make `doctor` hang: a dead external should fail FAST. */
+const DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS = 3_000;
+
+/** Run an external service's declared readiness probe exactly ONCE (unlike `awaitReadiness`, which
+ * polls until it passes or times out — appropriate at boot, wrong for a doctor health check, which
+ * must report the CURRENT state, not wait for it to become healthy). Reuses the same probe shapes
+ * (`command`/`httpUrl`/`stdoutMatch`) declared in config for the boot-time `readyWhen`. */
+async function probeExternalOnce(
+  ready: WorldExternalReadyWhen,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  logPath: string,
+): Promise<{ ok: boolean; message: string }> {
+  if (ready.command !== undefined) {
+    if (!commandExists(ready.command)) {
+      return { ok: false, message: `readiness command \`${ready.command}\` not found on PATH` };
+    }
+    const result = spawnSync(ready.command, ready.args ?? [], {
+      cwd, encoding: 'utf8', env, timeout: DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.status === 0) return { ok: true, message: 'probe ok (command)' };
+    const timedOut = result.signal !== null && result.status === null;
+    return { ok: false, message: timedOut ? `probe command timed out after ${DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS}ms` : `probe command exited ${result.status ?? 'null'}: ${(result.stderr ?? '').trim().slice(0, 300)}` };
+  }
+  if (ready.httpUrl !== undefined) {
+    try {
+      const response = await fetch(ready.httpUrl, { signal: AbortSignal.timeout(DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS) });
+      if (response.status >= 200 && response.status < 400) return { ok: true, message: `probe ok (HTTP ${response.status})` };
+      return { ok: false, message: `probe returned HTTP ${response.status}` };
+    } catch (error) {
+      return { ok: false, message: `probe failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+  }
+  if (ready.stdoutMatch !== undefined) {
+    const text = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
+    if (new RegExp(ready.stdoutMatch).test(text)) return { ok: true, message: 'probe ok (stdoutMatch)' };
+    return { ok: false, message: `probe pattern /${ready.stdoutMatch}/ not found in log` };
+  }
+  return { ok: false, message: 'malformed readiness probe (no command/httpUrl/stdoutMatch)' };
+}
+
+export async function doctorWorld(name: string, options: { root?: string; verifyPublic?: boolean; timeoutMs?: number } = {}): Promise<WorldDoctorReport> {
+  const root = resolve(options.root ?? process.cwd());
+  const checks: WorldDoctorCheck[] = [];
+  let instance: WorldInstance;
+  try {
+    instance = readWorldInstance(name, root);
+    checks.push({ id: 'instance', ok: true, message: `instance=${instanceFile(root, name)}` });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { name, ok: false, checks: [{ id: 'instance', ok: false, message }] };
+  }
+
+  checks.push({ id: 'env-file', ok: existsSync(instance.envFile), message: instance.envFile });
+
+  const live = livePids(readPids(instance.pidsFile));
+  checks.push({
+    id: 'pids',
+    ok: live.length > 0,
+    message: live.length > 0 ? `live=${live.join(', ')}` : 'no live world processes',
+  });
+
+  // Loaded once, best-effort: only used to find each external service's declared readyWhen/status
+  // probe (TWIN-68) — if the config can't be reloaded (moved/deleted since `up`), externals just
+  // fall back to the "no probe declared" informational check rather than failing doctor entirely.
+  // (Named distinctly from the `config` reloaded further below for the share-mode checks, which
+  // intentionally keeps its own separate, non-best-effort load.)
+  let externalProbeConfig: WorldConfig | undefined;
+  try {
+    externalProbeConfig = loadWorldConfig(instance.configPath, instance.root).config;
+  } catch {
+    externalProbeConfig = undefined;
+  }
+
+  for (const service of Object.values(instance.services)) {
+    if (service.type === 'external') {
+      // We don't own the external tool's process or its port — report what it discovered, plus
+      // (TWIN-68) re-run its declared probe once so a stack that died mid-session goes red instead
+      // of reporting an unconditional ok:true forever.
+      const discovered = Object.keys(service.env ?? {});
+      const discoveredMessage = discovered.length > 0 ? `discovered ${discovered.join(', ')}` : 'self-managed (no discovered env)';
+      const configuredExternal = externalProbeConfig?.services.find((candidate) => candidate.id === service.id)?.external;
+      const probeCwd = service.external?.cwd ?? root;
+      const probeEnv = { ...process.env, ...(instance.env ?? {}), ...(service.external?.discoveredEnv ?? {}) };
+      if (configuredExternal?.readyWhen) {
+        const probe = await probeExternalOnce(configuredExternal.readyWhen, probeCwd, probeEnv, service.log);
+        checks.push({ id: `service:${service.id}:external`, ok: probe.ok, message: `${discoveredMessage}; ${probe.message}` });
+      } else if (configuredExternal?.status) {
+        try {
+          runExternalCommand(configuredExternal.status, probeCwd, service.id, 'doctor-probe', probeEnv);
+          checks.push({ id: `service:${service.id}:external`, ok: true, message: `${discoveredMessage}; probe ok (status)` });
+        } catch (error) {
+          checks.push({ id: `service:${service.id}:external`, ok: false, message: `${discoveredMessage}; probe failed: ${error instanceof Error ? error.message : String(error)}` });
+        }
+      } else {
+        checks.push({ id: `service:${service.id}:external`, ok: true, message: `${discoveredMessage}; no probe declared — health unknown` });
+      }
+      continue;
+    }
+    const pidLive = livePids([service.pid]).length > 0;
+    checks.push({
+      id: `service:${service.id}:pid`,
+      ok: pidLive,
+      message: pidLive ? `pid=${service.pid}` : `pid ${service.pid} is not live`,
+    });
+    if (service.workerGaveUp) {
+      // A worker-isolated twin whose Worker thread crashed: the host process (and its pid) is
+      // still alive, but this twin's own worker was given up on (never restarted) — surface it
+      // explicitly rather than let it hide behind an otherwise-generic tcp-refused check below.
+      checks.push({
+        id: `service:${service.id}:worker`,
+        ok: false,
+        message: `worker exited and was not restarted (${service.workerGaveUp.detail}), at ${service.workerGaveUp.at}`,
+      });
+    }
+    try {
+      await waitForTcp(service.port!, 1_000);
+      checks.push({ id: `service:${service.id}:tcp`, ok: true, message: service.url! });
+    } catch (error) {
+      checks.push({
+        id: `service:${service.id}:tcp`,
+        ok: false,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+    if (service.tunnel || service.publicUrl) {
+      const tunnelLive = service.tunnel ? livePids([service.tunnel.pid]).length > 0 : false;
+      checks.push({
+        id: `service:${service.id}:tunnel`,
+        ok: tunnelLive,
+        message: service.tunnel ? `pid=${service.tunnel.pid}` : 'missing tunnel process',
+      });
+      checks.push({
+        id: `service:${service.id}:public-ready`,
+        ok: service.publicReady === true,
+        message: service.publicUrl ?? 'missing public URL',
+      });
+      if (options.verifyPublic && service.publicUrl && service.publicVerification?.path) {
+        try {
+          const verification = await verifyPublicUrl(service.publicUrl, service.publicVerification.path, options.timeoutMs ?? 10_000);
+          checks.push({
+            id: `service:${service.id}:public-health`,
+            ok: true,
+            message: `${verification.status} ${service.publicUrl}${service.publicVerification.path}`,
+          });
+        } catch (error) {
+          checks.push({
+            id: `service:${service.id}:public-health`,
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    }
+  }
+
+  if (instance.mode === 'share') {
+    const config = loadWorldConfig(instance.configPath, instance.root).config;
+    const expected = config.share?.services.length ? config.share.services : [{ id: 'app' }];
+    for (const target of expected) {
+      const service = instance.services[target.id];
+      checks.push({
+        id: `share:${target.id}`,
+        ok: service?.publicReady === true && Boolean(service.publicUrl),
+        message: service?.publicUrl ?? 'not shared',
+      });
+    }
+  }
+
+  return { name: instance.name, ok: checks.every((check) => check.ok), checks };
+}
+
+export function urlsWorld(name: string, root = process.cwd()): WorldUrlInfo {
+  const instance = readWorldInstance(name, resolve(root));
+  return {
+    name: instance.name,
+    mode: instance.mode,
+    services: Object.fromEntries(Object.values(instance.services).map((service) => [
+      service.id,
+      {
+        localUrl: service.url ?? '',
+        ...(service.publicUrl ? { publicUrl: service.publicUrl } : {}),
+        ...(service.publicReady !== undefined ? { publicReady: service.publicReady } : {}),
+      },
+    ])),
+  };
+}
+
+export async function runWorld(configId: string, command: string[], options: RunWorldOptions = {}): Promise<{ instance: WorldInstance; exitCode: number }> {
+  if (command.length === 0) throw new Error('Missing command after --');
+  const instance = await upWorld(configId, options);
+  let exitCode = 1;
+  try {
+    exitCode = runWithWorldEnv(instance.name, command, instance.root);
+    return { instance, exitCode };
+  } finally {
+    if (!options.keep) await downWorld(instance.name, instance.root);
+  }
+}
+
+export function listWorlds(root = process.cwd()): Array<{ name: string; running: boolean; config?: string }> {
+  const base = worldBaseDir(resolve(root));
+  if (!existsSync(base)) return [];
+  return readdirSync(base, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      try {
+        const status = statusWorld(entry.name, root);
+        return { name: entry.name, running: status.running, config: status.config };
+      } catch {
+        return { name: entry.name, running: false };
+      }
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function runWithWorldEnv(name: string, command: string[], root = process.cwd()): number {
+  if (command.length === 0) throw new Error('Missing command after --');
+  const status = statusWorld(name, root);
+  const sealed = status.env.VOLTER_WORLD_MODE === 'sealed';
+  let proxyEnv: Record<string, string> = {};
+  try {
+    const proxy = ensureWorldProxy(name, root);
+    if (proxy?.url) {
+      proxyEnv = proxy.env;
+    } else if (sealed && proxy === null) {
+      // TWIN-64: ensureWorldProxy() returns bare `null` when openssl is unavailable — silently, by
+      // design, for the non-sealed env-only fallback. A SEALED world running a command without the
+      // ambient proxy is a different story: the Node injector (loaded via NODE_OPTIONS, still in
+      // `status.env`) keeps blocking Node http/https/fetch calls, but unmodified non-Node CLIs
+      // (curl, gh, stripe, …) have no HTTPS_PROXY to redirect them and can bypass the twins
+      // entirely. Never let that be silent — the daemon-timeout case is already loud (see the WARN
+      // `ensureWorldProxy` itself emits), this covers the "no openssl at all" gap.
+      process.stderr.write(
+        `!! WARN: world "${name}" is sealed but openssl is unavailable — NOT proxy-sealed for this command; unmodified CLIs (curl, gh, stripe, …) can bypass the twins here (Node http/https/fetch calls are still blocked via the injector).\n`,
+      );
+    }
+  } catch (error) {
+    if (sealed) {
+      // Never swallow a sealed world's proxy failure silently (TWIN-64): the command is about to
+      // run NOT proxy-sealed for unmodified CLIs even though Node calls stay guarded by the
+      // injector.
+      process.stderr.write(
+        `!! WARN: world "${name}" is sealed but the ambient redirect proxy failed to start (${error instanceof Error ? error.message : String(error)}) — NOT proxy-sealed for this command; unmodified CLIs (curl, gh, stripe, …) can bypass the twins here.\n`,
+      );
+    }
+    // Keep env-only redirect if the ambient proxy cannot start.
+  }
+  const result = spawnSync(command[0]!, command.slice(1), {
+    cwd: resolve(root),
+    env: { ...process.env, ...status.env, ...proxyEnv },
+    stdio: 'inherit',
+  });
+  return result.status ?? 1;
+}
+
+/** The shell + env + cwd a `volter-world shell` subshell launches with (extracted for testability):
+ * the world env (twin `*_URL`s + fake keys + the Node injector + cliRedirect endpoint vars) on top
+ * of the caller's env, plus `VOLTER_WORLD` so a prompt can show which world is active. The ambient
+ * TLS-proxy env (HTTPS_PROXY + the CA-trust vars) is layered in by `shellWorld` once the proxy is up,
+ * since starting a server is async; this pure helper stays synchronous + side-effect-free for tests. */
+export function worldShellEnv(name: string, root = process.cwd()): { shell: string; cwd: string; env: Record<string, string> } {
+  const status = statusWorld(name, root);
+  if (!status.running) throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-file <path> --name ${name}`);
+  return {
+    shell: process.env.SHELL || '/bin/bash',
+    cwd: resolve(root),
+    env: { ...process.env, ...status.env, VOLTER_WORLD: name } as Record<string, string>,
+  };
+}
+
+/** Drop into an interactive subshell with the world active — the contained sibling of `activate`
+ * (which wires your CURRENT shell + sets the `(world:<name>)` prompt marker). The subshell gets the
+ * world env AND, when openssl is available, an in-process ambient TLS redirect proxy: unmodified
+ * `gh`/`stripe`/`curl`/app in the subshell transparently hit the twins. Vendor calls in this subshell
+ * land in the twins; `exit` restores normal (the proxy + its session CA are torn down). The CA is
+ * trusted ONLY via this subshell's env — never installed system-wide. See docs/WORLD_ACTIVATE.md. */
+export async function shellWorld(name: string, root = process.cwd()): Promise<number> {
+  const { shell, cwd, env } = worldShellEnv(name, root);
+  const resolvedRoot = resolve(root);
+  let proxy: Awaited<ReturnType<typeof startRedirectProxy>> | null = null;
+  if (opensslAvailable()) {
+    try {
+      proxy = await startRedirectProxy({ env, tlsDir: tlsDir(resolvedRoot, name) });
+      Object.assign(env, proxy.proxyEnv());
+      process.stderr.write(`world '${name}' active in a subshell — vendor calls hit the twins (ambient proxy ${proxy.url}). type 'exit' to leave.\n`);
+    } catch (error) {
+      process.stderr.write(`world '${name}': ambient TLS proxy unavailable (${error instanceof Error ? error.message : String(error)}); falling back to env-only redirect.\n`);
+    }
+  } else {
+    process.stderr.write(`world '${name}' active in a subshell — vendor calls hit the twins (env-only; install openssl for ambient https redirect). type 'exit' to leave.\n`);
+  }
+  try {
+    const result = spawnSync(shell, ['-i'], { cwd, env, stdio: 'inherit' });
+    return result.status ?? 0;
+  } finally {
+    if (proxy) {
+      await proxy.close();
+      tearDownCa(tlsDir(resolvedRoot, name));
+    }
+  }
+}
+
+/** The daemon-poll deadline (ms) used by `ensureWorldProxy`/`ensureWorldProxyFromEnv` below. Hardcoded
+ * to 5000ms in production; `VOLTER_PROXY_DEADLINE_MS` is a TEST-ONLY seam so tests can force a
+ * deterministic timeout without an actual multi-second wait. Never set this env var in real usage. */
+function proxyDaemonDeadlineMs(): number {
+  const raw = process.env.VOLTER_PROXY_DEADLINE_MS;
+  if (raw === undefined) return 5000;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 5000;
+}
+
+/** Ensure a DETACHED ambient-redirect proxy daemon is running for this world (used by `activate`,
+ * which only emits a script and can't host an in-process server for the life of the shell). Idempotent:
+ * reuses a live daemon. Returns its proxy env, or null if openssl is missing (env-only fallback). The
+ * daemon is recorded in `proxy.json` and stopped by `down`. */
+export function ensureWorldProxy(name: string, root = process.cwd()): { url: string; caCertPath: string; env: Record<string, string> } | null {
+  const resolvedRoot = resolve(root);
+  if (!opensslAvailable()) return null;
+  const existing = readProxyState(resolvedRoot, name);
+  if (existing && isAlive(existing.pid)) {
+    return { url: existing.url, caCertPath: existing.caCertPath, env: proxyEnvFor(existing.url, existing.caCertPath) };
+  }
+  // Pre-create the CA synchronously so we can return its path immediately; the daemon reuses it.
+  const ca = ensureCa(tlsDir(resolvedRoot, name));
+  const child = spawn(process.execPath, [proxyDaemonEntry(), name, '--root', resolvedRoot], {
+    cwd: resolvedRoot,
+    env: process.env,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  // Wait briefly for the daemon to write its state (port).
+  const deadlineMs = proxyDaemonDeadlineMs();
+  const deadline = Date.now() + deadlineMs;
+  while (Date.now() < deadline) {
+    const state = readProxyState(resolvedRoot, name);
+    if (state && state.pid === child.pid) {
+      return { url: state.url, caCertPath: state.caCertPath, env: proxyEnvFor(state.url, state.caCertPath) };
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50); // 50ms synchronous backoff
+  }
+  // Daemon didn't report in time — fall back to env-only redirect rather than fabricate success.
+  // LOUD, never silent: a world that appears sealed but isn't is a purpose-1 integrity hole.
+  process.stderr.write(`!! WARN: ambient proxy daemon for world "${name}" did not report within ${deadlineMs}ms — world is NOT proxy-sealed; unmodified CLIs will bypass the twins (env-only redirect still active).\n`);
+  return { url: '', caCertPath: ca.caCert, env: {} };
+}
+
+function ensureWorldProxyFromEnv(name: string, root: string, env: Record<string, string>): { url: string; caCertPath: string; env: Record<string, string> } | null {
+  const resolvedRoot = resolve(root);
+  if (!opensslAvailable()) return null;
+  writeProxyEnv(resolvedRoot, name, env);
+  const existing = readProxyState(resolvedRoot, name);
+  if (existing && isAlive(existing.pid)) {
+    return { url: existing.url, caCertPath: existing.caCertPath, env: proxyEnvFor(existing.url, existing.caCertPath) };
+  }
+  const ca = ensureCa(tlsDir(resolvedRoot, name));
+  const child = spawn(process.execPath, [proxyDaemonEntry(), name, '--root', resolvedRoot, '--env-file', proxyEnvFile(resolvedRoot, name)], {
+    cwd: resolvedRoot,
+    env: process.env,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  const deadlineMs = proxyDaemonDeadlineMs();
+  const deadline = Date.now() + deadlineMs;
+  while (Date.now() < deadline) {
+    const state = readProxyState(resolvedRoot, name);
+    if (state && state.pid === child.pid) {
+      return { url: state.url, caCertPath: state.caCertPath, env: proxyEnvFor(state.url, state.caCertPath) };
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+  }
+  // Daemon didn't report in time — fall back to env-only redirect rather than fabricate success.
+  // LOUD, never silent: `upWorld` (sealed mode) turns this into a hard failure; other callers just
+  // see the empty url and keep the env-only redirect, but the operator must be told either way.
+  process.stderr.write(`!! WARN: ambient proxy daemon for world "${name}" did not report within ${deadlineMs}ms — world is NOT proxy-sealed; unmodified CLIs will bypass the twins (env-only redirect still active).\n`);
+  return { url: '', caCertPath: ca.caCert, env: {} };
+}
+
+function isAlive(pid: number): boolean {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function proxyDaemonEntry(): string {
+  return new URL('./proxy-daemon.ts', import.meta.url).pathname;
+}
+
+/** The detached proxy daemon's body (invoked as its own process by `ensureWorldProxy`). Starts the
+ * redirect proxy bound to an ephemeral port, records its pid/url/CA in `proxy.json`, and stays up
+ * until killed by `down`. Exported so the daemon entry file can delegate to it. */
+export async function runProxyDaemon(name: string, root = process.cwd(), envFile?: string): Promise<void> {
+  const resolvedRoot = resolve(root);
+  const envLoader = envFile
+    ? () => ({ ...process.env, ...readProxyEnv(envFile) } as Record<string, string>)
+    : undefined;
+  let env: Record<string, string> | undefined;
+  if (!envLoader) {
+    const status = statusWorld(name, resolvedRoot);
+    if (!status.running) throw new Error(`World "${name}" is not running`);
+    env = { ...process.env, ...status.env } as Record<string, string>;
+  }
+  const proxy = await startRedirectProxy({ env, envLoader, tlsDir: tlsDir(resolvedRoot, name) });
+  const state: ProxyState = { pid: process.pid, url: proxy.url, caCertPath: proxy.caCertPath };
+  writeFileSync(proxyStateFile(resolvedRoot, name), JSON.stringify(state));
+  const stop = async () => {
+    try { await proxy.close(); } catch { /* ignore */ }
+    try { rmSync(proxyStateFile(resolvedRoot, name), { force: true }); } catch { /* ignore */ }
+    process.exit(0);
+  };
+  process.on('SIGTERM', stop);
+  process.on('SIGINT', stop);
+}
+
+/** Stop a world's ambient-redirect proxy daemon (if any) and drop its session CA. Best-effort —
+ * called from `downWorld` so the trusted CA never outlives the world. */
+function stopWorldProxy(root: string, name: string): void {
+  const state = readProxyState(root, name);
+  if (state && isAlive(state.pid)) {
+    try { process.kill(state.pid, 'SIGTERM'); } catch { /* ignore */ }
+  }
+  try { rmSync(proxyStateFile(root, name), { force: true }); } catch { /* ignore */ }
+  try { rmSync(proxyEnvFile(root, name), { force: true }); } catch { /* ignore */ }
+  tearDownCa(tlsDir(root, name));
+}
+
+/**
+ * Emit a POSIX (bash/zsh) script to `eval` that ACTIVATES the world in the current shell — a
+ * virtualenv for vendor APIs. It exports the world env (twin `*_URL`s + fake keys + the Node
+ * injector + any `cliRedirect` endpoint vars), prepends `(world:<name>)` to the prompt so you can
+ * always see you're pointed at twins (a safety signal, not cosmetic), and defines a `deactivate`
+ * function that restores the prompt and unsets the vars. Usage: `eval "$(volter-world activate dev)"`.
+ *
+ * It ALSO starts (idempotently) the ambient TLS redirect proxy daemon for this world and exports
+ * `HTTPS_PROXY`/`HTTP_PROXY` + the CA-trust vars (`NODE_EXTRA_CA_CERTS`, `CURL_CA_BUNDLE`, …) so an
+ * UNMODIFIED `gh`/`stripe`/`curl`/app in the shell transparently hits the twins with zero per-tool
+ * config (WORLD_ACTIVATE.md tier 1). The session CA is trusted ONLY via these per-shell exports,
+ * never system-wide; `down` stops the daemon and drops the CA. If openssl is unavailable the script
+ * still emits the env-only redirect (Phase-1 behavior) — it just skips the proxy exports.
+ * See docs/WORLD_ACTIVATE.md.
+ */
+export function activateScript(name: string, root = process.cwd()): string {
+  const status = statusWorld(name, root);
+  if (!status.running) throw new Error(`World "${name}" is not running — run: volter-world up <config> --env-file <path> --name ${name}`);
+  const baseEnv = status.env ?? {};
+  // Bring up the ambient redirect proxy (best-effort) and fold its env in so the activated shell
+  // routes https through the twins too — not just the Node injector / cliRedirect endpoint vars.
+  let proxyNote = '';
+  let env: Record<string, string> = { ...baseEnv };
+  try {
+    const proxy = ensureWorldProxy(name, root);
+    if (proxy && proxy.url) {
+      env = { ...baseEnv, ...proxy.env };
+      proxyNote = ` (ambient proxy ${proxy.url})`;
+    }
+  } catch {
+    // openssl missing or daemon failed — keep env-only redirect; never fabricate proxy success.
+  }
+  const keys = Object.keys(env).sort();
+  const lines: string[] = [
+    `# volter-world activate ${name} — run:  eval "$(volter-world activate ${name})"`,
+    `if [ -n "\${_VOLTER_WORLD:-}" ]; then deactivate 2>/dev/null || true; fi`,
+    `_VOLTER_WORLD=${shellQuote(name)}`,
+    `_VOLTER_WORLD_OLD_PS1="\${PS1:-}"`,
+    `deactivate () {`,
+    ...keys.map((k) => `  unset ${k}`),
+    `  PS1="\${_VOLTER_WORLD_OLD_PS1:-}"; export PS1`,
+    `  unset _VOLTER_WORLD _VOLTER_WORLD_OLD_PS1`,
+    `  unset -f deactivate`,
+    `}`,
+    ...keys.map((k) => `export ${k}=${shellQuote(env[k]!)}`),
+    `PS1="(world:${name}) \${PS1:-}"; export PS1`,
+    `printf '%s\\n' "world '${name}' active — vendor calls now hit the twins${proxyNote}. run: deactivate" >&2`,
+  ];
+  return `${lines.join('\n')}\n`;
+}