@volter/world-runtime 2.0.0

package/dist/src/runtime.js

@@ -0,0 +1,3502 @@
+import { offSignal } from "./signals.js";
+import { assertWorldStateRemovable, removeWorldState } from "./ancestry.js";
+import { packCli, packEntry } from "./catalog.js";
+import { spawn, spawnSync } from 'node:child_process';
+import { get as httpGet } from 'node:http';
+import { siblingScript } from "./sibling.js";
+import { commandLifetime, commandProcessGroup, CommandRetirementError } from "./command-lifetime.js";
+import { superviseWorldRun } from "./run-task.js";
+import { survivingOwnedGroups } from "./process-groups.js";
+import { randomUUID, createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { isIP } from 'node:net';
+import { allocatePort } from "./tcp-port.js";
+import { constants as osConstants, hostname as osHostname } from 'node:os';
+import { appendFileSync, chmodSync, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync, writeSync, existsSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { packFacts } from "./pack-facts.js";
+import { describeServiceEnd, readServiceEnd, serviceOutput } from "./service-exit.js";
+import { Socket } from 'node:net';
+import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
+import { loadWorldConfig } from "./configs.js";
+import { createWorldNetworkPolicy, WORLD_NETWORK_POLICY_ENV } from '@volter/world-core/network-policy';
+import { resolveServicePackage } from "./catalog.js";
+import { fakeEnvValue } from "./fixture-env.js";
+import { MINT_ENV } from "./schema.js";
+import { inertInjectEnvWarnings } from "./inject-map.js";
+import { activeVendorMap, ensureCa, opensslAvailable, proxyEnvFor, startRedirectProxy, tearDownCa } from "./redirect-proxy.js";
+import { CaTrustError, sessionTrustEnv } from "./ca-trust.js";
+import { checkedOwner, CONSUMER_HEARTBEAT_MS, createConsumer, refreshConsumer, releaseConsumer, removeConsumerRecord, worldConsumers } from "./consumers.js";
+import { assertLifecycleStartable, beginWorldLifecycle, handoffWorldLifecycle, recordWorldLifecycleEvent, releaseWorldLifecycle, retainWorldLifecycleForCleanup, hasWorldLifecycle, isWorldLifecycleRunning, lifecycleLogPath, releaseAbandonedWorldLifecycle } from "./lifecycle-record.js";
+/** The latest `limit` bytes of a service log, reaching into its one rotation (`<log>.1`) when the current file is
+ *  shorter: a readiness line printed just before a rotation is still found, and a poll never reads 64 MiB files. */
+function readServiceText(log, limit = 4 * 1024 * 1024) {
+    const tailOfFile = (path, bytes) => {
+        if (bytes <= 0 || !existsSync(path))
+            return '';
+        const fd = openSync(path, 'r');
+        try {
+            const size = fstatSync(fd).size, start = Math.max(0, size - bytes), buffer = Buffer.alloc(size - start);
+            readSync(fd, buffer, 0, buffer.length, start);
+            return buffer.toString('utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    const current = tailOfFile(log, limit);
+    return `${tailOfFile(`${log}.1`, limit - Buffer.byteLength(current))}${current}`;
+}
+/** The World's events file: every service's start and end, and the World's own stops, one JSON line each. */
+export function worldEventsPath(logs) {
+    return join(logs, 'events.jsonl');
+}
+/** Start `command args` under the service recorder (./service-recorder.ts) as its own process group: the service writes
+ *  its output straight to `log` (capped, time-marked), its start and end are recorded there and in the World's events
+ *  file, and it is handed a directory of its own for the log files it writes itself (VOLTER_WORLD_SERVICE_LOG_DIR).
+ *  `ended` settles when the recorder exits, right after the service ends and its exit record is written. */
+function spawnRecorded(serviceId, command, args, cwd, env, log) {
+    const logDir = `${log.replace(/\.log$/, '')}.d`;
+    mkdirSync(logDir, { recursive: true, mode: 0o700 });
+    const out = openPrivateLog(log, 'a'); // the service's output and the recorder's records, appended
+    const recorderEnv = { ...env, VOLTER_WORLD_SERVICE_ID: serviceId, VOLTER_WORLD_SERVICE_LOG: log,
+        VOLTER_WORLD_SERVICE_LOG_DIR: logDir, VOLTER_WORLD_EVENTS: worldEventsPath(dirname(log)) };
+    if (recorderEnv.NODE_OPTIONS !== undefined) {
+        recorderEnv.VOLTER_WORLD_SERVICE_NODE_OPTIONS = recorderEnv.NODE_OPTIONS;
+        delete recorderEnv.NODE_OPTIONS;
+    }
+    const child = spawn(process.execPath, [siblingScript(import.meta.url, 'service-recorder'), command, ...args], {
+        cwd,
+        env: recorderEnv,
+        detached: true,
+        stdio: ['ignore', out, out],
+    });
+    closeSync(out);
+    const ended = new Promise((resolveEnded) => { child.once('exit', () => resolveEnded()); child.once('error', () => resolveEnded()); });
+    return { child, ended };
+}
+/** A startup wait that fails as soon as the service ends, with the service's own account of its end (exit code or
+ *  signal, last output) instead of a timeout that names neither. */
+async function untilReadyOrEnded(wait, ended, boot, what, log) {
+    const local = new AbortController();
+    const abort = AbortSignal.any([boot.signal, local.signal]);
+    return new Promise((resolveReady, rejectReady) => {
+        let settled = false;
+        wait(abort).then((value) => { if (!settled) {
+            settled = true;
+            local.abort();
+            resolveReady(value);
+        } }, (error) => { if (!settled) {
+            settled = true;
+            local.abort();
+            rejectReady(error);
+        } });
+        void ended.then(() => {
+            if (settled)
+                return;
+            settled = true;
+            local.abort();
+            rejectReady(new Error(`${what} ${endedAccount(log)}`));
+        });
+    });
+}
+/** That the process answering a service's port is the service. allocatePort closes its probe before the service
+ *  binds, so another process can take the port and answer the first connect; the service then fails to bind and ends
+ *  at once, which a short settle catches for any program. A World twin also answers WORLD_BOOT_PATH with the boot it
+ *  belongs to, so a leftover World's twin on the port is named exactly; a server that does not answer the path (a
+ *  twin from before it, a program that is not a twin) is accepted on the settle alone. When the settle guards this
+ *  port alone (`early`), a twin's answer with this boot's id ends it early: a server of this boot holds the port, and
+ *  every port this boot assigns is kept apart from its siblings', so short of the kernel handing the just-probed port
+ *  to another of this boot's port-0 listeners, that server is the service just started. A settle standing for several
+ *  ports (a co-located host's)
+ *  always runs in full: one port's answer says nothing of the others'. Programs that are not twins are never asked. */
+async function confirmOwnPort(port, boot, ended, twin, what, log, early = false) {
+    // A twin is asked at once, raced with the settle: a server slow to answer costs no more than the settle did.
+    const answer = twin ? worldBootOf(port) : Promise.resolve(null);
+    const own = early && twin ? answer.then((a) => (a && a.boot === boot.bootId ? 'own' : new Promise(() => undefined))) : new Promise(() => undefined);
+    // `ended` absent: the process was already settled (a co-located host settles once for all its twins).
+    if (ended) {
+        const settled = await Promise.race([own, ended.then(() => 'ended'), new Promise((resolveAlive) => setTimeout(() => resolveAlive('alive'), 300))]);
+        if (settled === 'own')
+            return;
+        if (settled === 'ended')
+            throw new Error(`${what} ended right after its port first answered, so another process probably holds the port: the service ${endedAccount(log)}\nLog: ${log}`);
+    }
+    if (!twin)
+        return;
+    const answered = await answer;
+    if (answered && typeof answered.boot === 'string' && answered.boot !== boot.bootId) {
+        throw new Error(`${what}: its port is answered by a twin of another World boot (${answered.boot}), not this one; a leftover World holds the port. Stop it (\`volter-world list\`, then \`down\`) and retry.\nLog: ${log}`);
+    }
+}
+/** What the server on a loopback port says its World boot is (WORLD_BOOT_PATH), or null. A direct loopback request:
+ *  never through a proxy an activated shell's environment names. */
+function worldBootOf(port) {
+    return new Promise((resolveBoot) => {
+        const request = httpGet({ host: '127.0.0.1', port, path: WORLD_BOOT_PATH, timeout: 1000, agent: false }, (response) => {
+            let body = '';
+            response.setEncoding('utf8');
+            response.on('data', (chunk) => { body += chunk; if (body.length > 4096)
+                request.destroy(); });
+            response.on('end', () => { try {
+                resolveBoot(response.statusCode === 200 ? JSON.parse(body) : null);
+            }
+            catch {
+                resolveBoot(null);
+            } });
+        });
+        request.on('timeout', () => request.destroy());
+        request.on('error', () => resolveBoot(null));
+    });
+}
+/** A stopped service's own account from its log: how it ended and the last lines it wrote. */
+function endedAccount(log) {
+    const end = readServiceEnd(log);
+    if (!end)
+        return 'ended and left no record of its end';
+    const said = end.lastOutput.length ? `\nLast output:\n${end.lastOutput.map((line) => `  ${line}`).join('\n')}` : '';
+    return `${describeServiceEnd(end)}${said}`;
+}
+/** The World's own stop of a service, written into the service's log beside the service's records, so its end reads as
+ *  the World's act (and a SIGKILL after the grace as the World's, not the OOM killer's). */
+function recordWorldStop(logs, event, by, signal) {
+    for (const log of new Set(logs)) {
+        try {
+            if (!existsSync(log))
+                continue;
+            const fd = openSync(log, 'r');
+            let fresh = '';
+            try {
+                const { size } = lstatSync(log);
+                const last = Buffer.alloc(1);
+                if (size && readSync(fd, last, 0, 1, size - 1) && last[0] !== 10)
+                    fresh = '\n';
+            }
+            finally {
+                closeSync(fd);
+            }
+            const line = `${JSON.stringify({ event, by, signal, service: basename(log).replace(/\.log$/, ''), at: new Date().toISOString() })}\n`;
+            appendFileSync(log, `${fresh}${line}`);
+            try {
+                appendFileSync(worldEventsPath(dirname(log)), line, { mode: 0o600 });
+            }
+            catch { /* the service log has it */ }
+        }
+        catch { /* the stop proceeds without its record */ }
+    }
+}
+function worldBaseDir(root) {
+    // `stateDirName()`, not a literal: VOLTER_STATE_DIR is the documented way to point a process at
+    // a different state directory, and control-plane honours it everywhere. This package did not,
+    // so a caller that set it got worlds written under `.volter/` while the kernel read from the
+    // requested directory — two halves of the same world in two places.
+    return join(root, stateDirName(), '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) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
+        throw new Error(`Invalid world name: ${name}`);
+}
+/** Exported for the reflect attachment (reflect.ts), whose routes file lives in
+ * the instance dir — one layout owner, no duplicated path knowledge. */
+/** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
+ *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
+ *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+export function clockFile(root, name) {
+    return join(instanceDir(root, name), 'clock');
+}
+export function instanceDir(root, name) {
+    return join(worldBaseDir(root), name);
+}
+function instanceFile(root, name) {
+    return join(instanceDir(root, name), 'instance.json');
+}
+function foregroundRunFile(root, name) {
+    return join(instanceDir(root, name), 'foreground-run.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, name) {
+    return join(worldBaseDir(root), '.locks', `${name}.lock`);
+}
+function stoppingFile(root, name) {
+    return join(worldBaseDir(root), '.locks', `${name}.stop.json`);
+}
+const SHARE_CLAIM_STALE_MS = 60_000;
+const SHARE_CLAIM_HEARTBEAT_MS = 5_000;
+// Liveness is decided by the claim ITSELF (docs/contributing/architecture.md#world-resource-and-diagnostics-boundary,
+// landed 2026-09-04): ownership is the token the claimant minted and holds in memory — no other
+// process ever has it, so a reused pid can never look like the owner — and life is the claim's
+// heartbeat, a REAL instant refreshed by the holder (a world's frozen clock cannot measure
+// liveness; this is host physics, not world time). Nothing here reads a process table.
+function sharingClaimFile(root, name) {
+    return join(worldBaseDir(root), '.locks', `${name}.share.json`);
+}
+function readSharingClaim(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const claim = JSON.parse(readFileSync(path, 'utf8'));
+        if (!claim || typeof claim !== 'object' || typeof claim.token !== 'string'
+            || !Number.isInteger(claim.pid) || claim.pid <= 0 || typeof claim.hostname !== 'string'
+            || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string'
+            || (claim.serviceId !== undefined && typeof claim.serviceId !== 'string'))
+            return undefined;
+        return claim;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Exported for direct drive: the liveness rule, pure over a claim. */
+export function sharingClaimAlive(claim) {
+    const heartbeatAt = Date.parse(claim.heartbeatAt);
+    const heartbeatAge = Date.now() - heartbeatAt;
+    const fresh = Number.isFinite(heartbeatAt)
+        && heartbeatAge >= -SHARE_CLAIM_STALE_MS && heartbeatAge <= SHARE_CLAIM_STALE_MS;
+    if (claim.hostname !== osHostname())
+        return fresh;
+    // Same host: a dead pid is a dead claim at once; a live pid is alive only while its holder
+    // keeps the heartbeat fresh — pid reuse cannot wedge sharing, because a reused pid never
+    // holds the token and never refreshes the heartbeat, so the claim ages out on the bound.
+    if (livePids([claim.pid]).length === 0)
+        return false;
+    return fresh;
+}
+async function reserveSharingClaim(root, name, serviceId) {
+    const path = sharingClaimFile(root, name);
+    mkdirSync(dirname(path), { recursive: true });
+    while (true) {
+        const claim = withFileLock(`${path}.lock`, () => {
+            if (liveBootingClaim(stoppingFile(root, name)))
+                throw new Error(`World "${name}" is being stopped`);
+            const existing = readSharingClaim(path);
+            if (existing && sharingClaimAlive(existing)) {
+                if (existing.serviceId === serviceId) {
+                    throw new Error(`World "${name}" service "${serviceId}" is already being shared by pid ${existing.pid}`);
+                }
+                return undefined;
+            }
+            const now = new Date().toISOString();
+            const reserved = {
+                token: randomUUID(), pid: process.pid, hostname: osHostname(), serviceId,
+                claimedAt: now, heartbeatAt: now,
+            };
+            writeTextAtomic(path, `${JSON.stringify(reserved)}\n`);
+            return reserved;
+        });
+        if (claim)
+            return claim;
+        // A different service is mutating the same instance/pids projection. Wait for its bounded,
+        // heartbeated claim to settle, then reload the committed instance before starting this child.
+        await sleep(50);
+    }
+}
+function refreshSharingClaim(root, name, token) {
+    const path = sharingClaimFile(root, name);
+    withFileLock(`${path}.lock`, () => {
+        const claim = readSharingClaim(path);
+        if (claim?.token === token)
+            writeTextAtomic(path, `${JSON.stringify({ ...claim, heartbeatAt: new Date().toISOString() })}\n`);
+    });
+}
+function releaseSharingClaim(root, name, token) {
+    const path = sharingClaimFile(root, name);
+    withFileLock(`${path}.lock`, () => {
+        if (readSharingClaim(path)?.token === token)
+            rmSync(path, { force: true });
+    });
+}
+/** 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, name) {
+    return join(instanceDir(root, name), 'booting.json');
+}
+/** 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) {
+    if (!existsSync(path))
+        return null;
+    let claim;
+    try {
+        claim = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!Number.isInteger(claim.pid) || claim.pid <= 0)
+        return null;
+    return livePids([claim.pid]).length > 0 ? claim : null;
+}
+/** Explicit down can finish a crashed boot, but only ESRCH proves its writer is absent.
+ * Called under the instance lock, before claiming teardown or signalling any resources. */
+function prepareBootForDown(root, name) {
+    const path = bootingFile(root, name);
+    if (!existsSync(path))
+        return;
+    let claim;
+    try {
+        claim = JSON.parse(readFileSync(path, 'utf8'));
+        if (!claim || !Number.isInteger(claim.pid) || claim.pid <= 0 || typeof claim.at !== 'string'
+            || !Number.isFinite(Date.parse(claim.at)))
+            throw new Error('invalid boot claim');
+    }
+    catch {
+        throw new Error(`World "${name}" has unreadable boot ownership; instance and lifecycle retained`);
+    }
+    try {
+        process.kill(claim.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== 'ESRCH') {
+            throw new Error(`World "${name}" boot owner is uninspectable; instance and lifecycle retained`);
+        }
+        rmSync(path); // the recorded booter cannot publish anything after this point
+        return;
+    }
+    if (claim.pid !== process.pid)
+        throw new Error(`World "${name}" is being booted; retry after boot finishes`);
+    // An in-process boot rollback still owns this marker until its own finally runs.
+}
+/** 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, name) {
+    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. */
+/** The redirect proxy daemon's log, beside the World's service logs. */
+function proxyLogPath(root, name) {
+    return join(instanceDir(root, name), 'logs', 'proxy.log');
+}
+function proxyStateFile(root, name) {
+    return join(instanceDir(root, name), 'proxy.json');
+}
+function proxyStartingFile(root, name) {
+    return join(instanceDir(root, name), 'proxy-starting.json');
+}
+function assertProxyOwnershipResolved(root, name) {
+    if (existsSync(proxyStartingFile(root, name))) {
+        throw new Error(`World "${name}" has unresolved proxy startup ownership; lifecycle and instance retained. Inspect: ${proxyStartingFile(root, name)}`);
+    }
+}
+function proxyEnvFile(root, name) {
+    return join(instanceDir(root, name), 'proxy-env.json');
+}
+function readProxyState(root, name) {
+    const file = proxyStateFile(root, name);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function envFileContents(env) {
+    return `${Object.entries(env)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `export ${key}=${shellQuote(value)}`)
+        .join('\n')}\n`;
+}
+function injectPreloadSpecifier() {
+    // resolved on use: importing the runtime has no side effects in a host without module resolution
+    return createRequire(import.meta.url).resolve('@volter/world-core/inject');
+}
+function writeProxyEnv(root, name, env) {
+    writeTextAtomic(proxyEnvFile(root, name), `${JSON.stringify(env, null, 2)}\n`);
+}
+function readProxyEnv(path) {
+    const env = JSON.parse(readFileSync(path, 'utf8'));
+    if (!env || typeof env !== 'object' || Array.isArray(env) || Object.values(env).some(value => typeof value !== 'string')) {
+        throw new Error('World proxy environment is unreadable; refusing network access');
+    }
+    return env;
+}
+/** 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/guides/route-a-cli-through-the-world.md. */
+function resolveCliRedirect(cliRedirect, url) {
+    if (!cliRedirect)
+        return {};
+    const out = {};
+    for (const [key, template] of Object.entries(cliRedirect))
+        out[key] = template.split('${url}').join(url);
+    return out;
+}
+function resolveServiceEnvTemplates(templates, service) {
+    if (!templates)
+        return {};
+    const out = {};
+    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',
+];
+/** The process's environment as the world admits it: what `stripEnv` names stays outside. */
+export function admittedEnv(strip, env = process.env) {
+    const out = {};
+    const rules = (strip ?? []).map((s) => (s.endsWith('*') ? { prefix: s.slice(0, -1) } : { name: s }));
+    for (const [k, v] of Object.entries(env)) {
+        if (v === undefined)
+            continue;
+        // Permission is published by the attached instance, never inherited from
+        // whichever World happened to launch this operator process.
+        if (k === WORLD_NETWORK_POLICY_ENV)
+            continue;
+        if (rules.some((r) => ('prefix' in r ? k.startsWith(r.prefix) : k === r.name)))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+// The strip list of a running world, for `env`/`attach`: its config is the one the instance recorded.
+function stripEnvOf(instanceEnv) {
+    // Freeze the admission policy for the instance; editing/removing its source cannot widen it.
+    const saved = instanceEnv.VOLTER_WORLD_STRIP_ENV;
+    if (saved !== undefined) {
+        try {
+            const rules = JSON.parse(saved);
+            return Array.isArray(rules) && rules.every(rule => typeof rule === 'string') ? rules : ['*'];
+        }
+        catch {
+            return ['*'];
+        }
+    }
+    // Compatibility for instances created before policy persistence. An unreadable source fails closed.
+    const path = instanceEnv.VOLTER_WORLD_CONFIG;
+    if (!path)
+        return undefined;
+    try {
+        return loadWorldConfig(path).config.stripEnv;
+    }
+    catch {
+        return ['*'];
+    }
+}
+function serviceProcessEnv(config, service, worldEnv, port) {
+    const env = {
+        ...admittedEnv(config.stripEnv),
+        ...(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 waitForTcp(port, timeoutMs = 15_000, abort) {
+    const started = Date.now();
+    while (Date.now() - started < timeoutMs) {
+        abort?.throwIfAborted();
+        const ok = await new Promise((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, 25));
+    }
+    throw new Error(`Service on port ${port} did not become reachable`);
+}
+function readPids(path) {
+    const held = getActiveWorldStore().read(path);
+    if (held === null)
+        return [];
+    return held
+        .split(/\r?\n/)
+        .map((line) => Number(line.trim()))
+        .filter((pid) => Number.isInteger(pid) && pid > 0);
+}
+function livePids(pids) {
+    return pids.filter((pid) => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code !== 'ESRCH';
+        }
+    });
+}
+function tunnelPids(instance) {
+    return Object.values(instance.services)
+        .map((service) => service.tunnel?.pid)
+        .filter((pid) => Boolean(pid));
+}
+function writeTextAtomic(path, value) {
+    // through the World store: the filesystem locally (temp, rename, 0600), a hosted World's SQLite
+    getActiveWorldStore().writeAtomic(path, value, { secret: true });
+}
+function openPrivateLog(path, flags) {
+    const descriptor = openSync(path, flags, 0o600);
+    chmodSync(path, 0o600);
+    return descriptor;
+}
+/** PID ownership survives projection rewrites. This lock is always inside lifecycle locks,
+ * never held while acquiring one; a proxy append cannot race a share/unshare rebuild. */
+/** Record `pids` as the World's. `fresh` are the processes this very call has spawned: only their start times are
+ *  measured anew; every other pid keeps the start time recorded when it was spawned (re-measuring it would bless
+ *  whatever process holds that number now). */
+function writeOwnedPids(root, name, pids, fresh = []) {
+    const path = join(instanceDir(root, name), 'pids');
+    withFileLock(`${instanceLockFile(root, name)}.pids`, () => {
+        const retained = undeadPids(readPids(path));
+        const merged = [...new Set([...retained, ...pids].filter(pid => Number.isInteger(pid) && pid > 0))];
+        writeTextAtomic(path, `${merged.join('\n')}\n`);
+        recordIdentities(root, name, merged, fresh);
+    });
+}
+// ---- which process a recorded pid names -------------------------------------------------------------------------
+// A pid outlives its process: once the World's process has exited the kernel may hand the number to anyone. Each owned
+// pid's start time is recorded beside the pids file, and a pid whose running process started at another time is no
+// longer the World's: it is never signalled and never keeps the World running.
+function identityPath(root, name) {
+    return join(instanceDir(root, name), 'pids.identity');
+}
+/** Each running pid's start time (one call); a pid with no process is absent. Printed in one fixed zone and locale, so
+ *  the same process reads the same whoever asks (`lstart` otherwise follows the caller's TZ and language). */
+function processStarts(pids) {
+    const starts = new Map();
+    if (!pids.length || process.platform === 'win32')
+        return starts;
+    if (process.platform === 'linux' && existsSync('/proc/self/stat')) {
+        // Linux: the start tick since boot (field 22), which a wall-clock step does not move (lstart would).
+        for (const pid of pids) {
+            try {
+                const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+                starts.set(pid, `tick ${stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]}`);
+            }
+            catch { /* no process */ }
+        }
+        return starts;
+    }
+    const result = spawnSync('ps', ['-o', 'pid=,lstart=', '-p', pids.join(',')], { encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } });
+    for (const line of (result.stdout ?? '').split('\n')) {
+        const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+        if (match)
+            starts.set(Number(match[1]), match[2]);
+    }
+    return starts;
+}
+function readIdentities(root, name) {
+    try {
+        return JSON.parse(getActiveWorldStore().read(identityPath(root, name)) ?? '{}');
+    }
+    catch {
+        return {};
+    }
+}
+function recordIdentities(root, name, pids, fresh = []) {
+    try {
+        // A pid the World has just spawned is measured anew, whatever an older record says of that number.
+        const known = readIdentities(root, name), starts = processStarts(pids.filter((pid) => known[pid] === undefined || fresh.includes(pid)));
+        for (const pid of fresh)
+            if (starts.has(pid))
+                delete known[pid];
+        const kept = Object.fromEntries(pids.flatMap((pid) => { const start = known[pid] ?? starts.get(pid); return start ? [[String(pid), start]] : []; }));
+        writeTextAtomic(identityPath(root, name), JSON.stringify(kept));
+    }
+    catch { /* without a record a pid is trusted as before */ }
+}
+/** Recorded pids whose running process started at another time than recorded: the number now names another
+ *  program. An unrecorded pid, and a pid with no process, are never in this list. */
+function foreignPids(root, name, pids) {
+    const known = readIdentities(root, name);
+    const recorded = pids.filter((pid) => known[pid] !== undefined);
+    if (!recorded.length)
+        return [];
+    const starts = processStarts(recorded);
+    return recorded.flatMap((pid) => { const now = starts.get(pid); return now !== undefined && now !== known[pid] ? [{ pid, recorded: known[pid], now }] : []; });
+}
+/** The pids still naming the processes the World started (see foreignPids). */
+function ownedPids(root, name, pids) {
+    const foreign = new Set(foreignPids(root, name, pids).map((entry) => entry.pid));
+    return foreign.size ? pids.filter((pid) => !foreign.has(pid)) : pids;
+}
+function writePidsFromInstance(instance, fresh = []) {
+    // 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),
+            ...((instance.lifecycle?.holderPid ?? instance.resources?.holderPid) ? [instance.lifecycle?.holderPid ?? instance.resources.holderPid] : []),
+        ].filter((pid) => Number.isInteger(pid) && pid > 0))];
+    writeOwnedPids(instance.root, instance.name, pids, fresh);
+}
+export function saveWorldInstance(instance) {
+    writeTextAtomic(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, instancePath) {
+    const held = getActiveWorldStore().read(join(dirname(instancePath), 'host-gaveup.json'));
+    if (held === null)
+        return;
+    try {
+        const gaveUp = JSON.parse(held);
+        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).
+    }
+}
+/** `world run` persists this sidecar before the foreground consumer starts. If the runner itself
+ * is hard-killed, it cannot record its own signal or execute `finally`; the next World read turns
+ * that orphaned running marker into an explicit, durable abrupt-termination diagnosis. */
+function mergeForegroundRun(instance, persist = true) {
+    const path = foregroundRunFile(instance.root, instance.name);
+    const held = getActiveWorldStore().read(path);
+    if (held === null)
+        return;
+    try {
+        let record = JSON.parse(held);
+        if (record.state === 'running' && !isAlive(record.runnerPid)) {
+            record = {
+                state: 'abrupt',
+                runnerPid: record.runnerPid,
+                ...(record.consumerPid ? { consumerPid: record.consumerPid } : {}),
+                startedAt: record.startedAt,
+                observedAt: new Date().toISOString(),
+                log: record.log,
+                error: 'World runner disappeared without an exit record; it was hard-killed or its host/session terminated abruptly',
+            };
+            if (persist)
+                writeTextAtomic(path, `${JSON.stringify(record, null, 2)}\n`);
+        }
+        instance.lastRun = record;
+    }
+    catch {
+        // Preserve instance readability if a process vanished between the sidecar's atomic writes.
+    }
+}
+function readWorldInstance(name, root, readOnly = false) {
+    const path = instanceFile(root, name);
+    const text = getActiveWorldStore().read(path);
+    if (text === null)
+        throw new Error(`World instance not found: ${name}`);
+    const instance = JSON.parse(text);
+    mergeWorkerGaveUp(instance, path);
+    // A read-only inspector never follows unvalidated metadata to a different World's sidecar.
+    if (!readOnly || (instance.name === name && typeof instance.root === 'string' && resolve(instance.root) === resolve(root))) {
+        mergeForegroundRun(instance, !readOnly);
+    }
+    return instance;
+}
+function assertMode(mode) {
+    if (mode !== 'local' && mode !== 'share' && mode !== 'sealed')
+        throw new Error(`Invalid world mode: ${mode}`);
+}
+function getByJsonPath(value, jsonPath) {
+    let current = 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[segment];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+async function runExternalCommand(command, cwd, serviceId, phase, env = process.env, abort, timeoutMs = 60_000) {
+    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)`);
+    abort?.throwIfAborted();
+    const child = spawn(bin, args, { cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
+    const lifetime = commandLifetime(child, abort, true);
+    let stdout = '';
+    let stderr = '';
+    let failure;
+    const collect = (chunk, out) => {
+        if (out)
+            stdout += chunk.toString();
+        else
+            stderr += chunk.toString();
+        if (stdout.length + stderr.length > 64 * 1024 * 1024) {
+            failure = new Error('command output exceeds 64 MiB');
+            lifetime.cancel('SIGTERM');
+        }
+    };
+    child.stdout.on('data', chunk => collect(chunk, true));
+    child.stderr.on('data', chunk => collect(chunk, false));
+    child.on('error', error => { failure = error; });
+    const timer = setTimeout(() => { failure = new Error(`command timed out after ${timeoutMs}ms`); lifetime.cancel('SIGTERM'); }, timeoutMs);
+    try {
+        const result = await lifetime.finish();
+        if (failure)
+            throw new Error(`External service "${serviceId}": ${phase} command failed to run (${failure.message})`);
+        if (result.code !== 0 || lifetime.forwarded)
+            throw new Error(`External service "${serviceId}": ${phase} command exited ${result.code ?? 'null'}\n${stdout}${stderr}`);
+        return { stdout, stderr };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** 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, cwd, serviceId, env, logPath, abort) {
+    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`, { mode: 0o600 });
+    chmodSync(logPath, 0o600);
+    const out = openPrivateLog(logPath, 'a');
+    const chunks = [];
+    try {
+        abort?.throwIfAborted();
+        const child = spawn(bin, args, { cwd, env, detached: commandProcessGroup, stdio: ['ignore', 'pipe', 'pipe'] });
+        const lifetime = commandLifetime(child, abort, true);
+        let failure;
+        child.on('error', error => { failure = error; });
+        const onData = (buf) => {
+            const text = buf.toString('utf8');
+            chunks.push(text);
+            try {
+                writeSync(out, text);
+            }
+            catch (error) {
+                failure = error;
+                lifetime.cancel('SIGTERM');
+            }
+        };
+        child.stdout.on('data', onData);
+        child.stderr.on('data', onData);
+        const { code } = await lifetime.finish();
+        if (failure)
+            throw failure;
+        abort?.throwIfAborted();
+        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, svc) {
+    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, logPath, cwd, serviceId, env = process.env, abort) {
+    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) {
+        abort?.throwIfAborted();
+        if (ready.command !== undefined) {
+            if (!commandExists(ready.command)) {
+                throw new Error(`Service "${serviceId}": readiness command \`${ready.command}\` not found on PATH`);
+            }
+            try {
+                await runExternalCommand([ready.command, ...(ready.args ?? [])], cwd, serviceId, 'readiness', env, abort, Math.max(1, timeoutMs - (Date.now() - started)));
+                return;
+            }
+            catch (error) {
+                if (error instanceof CommandRetirementError)
+                    throw error;
+                lastError = String(error);
+            }
+        }
+        else if (ready.httpUrl !== undefined) {
+            try {
+                const response = await fetch(ready.httpUrl, { signal: AbortSignal.any([AbortSignal.timeout(Math.max(1, timeoutMs - (Date.now() - started))), ...(abort ? [abort] : [])]) });
+                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 = serviceOutput(readServiceText(logPath));
+            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, paths, worldEnv, stripEnv, boot) {
+    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`);
+    const cwd = service.cwd ? resolve(paths.root, service.cwd) : paths.root;
+    // 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 = {
+        ...admittedEnv(stripEnv),
+        ...worldEnv,
+        ...(service.env ?? {}),
+        VOLTER_WORLD_SERVICE_ID: service.id,
+        VOLTER_WORLD_SERVICE_LOG: log,
+    };
+    if (service.controlPlane)
+        for (const key of CONTROL_PLANE_EGRESS_ENV)
+            delete env[key];
+    // 1. up — start the self-managed stack, STREAMING its output to the service log (no 1MB cap).
+    if (!external.up[0] || !commandExists(external.up[0])) {
+        throw new Error(`External service "${service.id}": \`${external.up[0] ?? ''}\` not found on PATH (the up command's tool is not installed)`);
+    }
+    // Publish the declared teardown before an external command can create state.
+    boot?.external({ id: service.id, type: 'external', command: [...external.up], pid: 0, log, env: {},
+        external: { down: [...external.down], cwd, discoveredEnv: { ...(service.env ?? {}) } } });
+    const upOutput = await runExternalUp(external.up, cwd, service.id, env, log, boot?.signal);
+    // 2. readiness — Docker-backed externals take seconds to boot.
+    await awaitReadiness(external.readyWhen, log, cwd, service.id, env, boot?.signal);
+    // 3. status — discover connection info (optional; may reuse up output instead).
+    let statusOutput = '';
+    if (external.status) {
+        const statusResult = await runExternalCommand(external.status, cwd, service.id, 'status', env, boot?.signal);
+        statusOutput = statusResult.stdout || statusResult.stderr;
+        appendFileSync(log, `\n$ ${external.status.join(' ')}\n${statusOutput}`);
+    }
+    // 4. discover — apply declarative mappings → injected env vars.
+    const injected = {};
+    const sources = {
+        status: statusOutput,
+        up: upOutput,
+    };
+    const jsonCache = {};
+    for (const mapping of external.discover ?? []) {
+        const source = mapping.source ?? 'status';
+        const raw = sources[source];
+        let value;
+        if (mapping.jsonPath !== undefined) {
+            if (!(source in jsonCache)) {
+                try {
+                    jsonCache[source] = JSON.parse(raw);
+                }
+                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, discoveredEnv: injected },
+    };
+}
+function trackBootingChild(child, boot) {
+    if (!child.pid)
+        return;
+    boot.pids.add(child.pid);
+    boot.recordPids();
+}
+async function startService(config, service, worldEnv, paths, allocatedPorts, boot) {
+    if (service.type === 'external')
+        return startExternalService(service, paths, worldEnv, config.stripEnv, boot);
+    if (!service.command)
+        throw new Error(`Service "${service.id}" must define command`);
+    const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : service.port;
+    const serviceDataDir = join(paths.data, service.id);
+    mkdirSync(serviceDataDir, { recursive: true });
+    // R17 — the lockfile holds on the spawn path too: a twin that runs `packages/twin/<vendor>/src/cli.ts`
+    // is checked against its pin and its protocol standing before it is spawned.
+    const spawnedModule = (service.type ?? 'twin') === 'twin' ? spawnedTwinModule(service, paths.root) : undefined;
+    const mounted = spawnedModule !== undefined ? lockfileCheck(service, spawnedModule) : {};
+    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 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;
+    }
+    // The service runs under the service recorder, which outlives it to write its end into its own log: `up`
+    // returns once the World is ready, so nothing else is left to see a service stop.
+    env.VOLTER_WORLD_BOOT_ID = boot.bootId;
+    const { child, ended } = spawnRecorded(service.id, service.command, args, cwd, env, log);
+    child.once('error', error => boot.fail(error));
+    child.unref();
+    trackBootingChild(child, boot);
+    // 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: null };
+    child.on('exit', (code, signal) => {
+        exitState.value = { code, signal };
+    });
+    // A service that declares a readiness budget gets it for its bind too: under load (a box
+    // swapping, a docker build beside the boot) a heavy service takes longer than the 15s default
+    // to answer on its port, and failing it there wastes the whole boot.
+    const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
+    await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the service', log).catch((error) => {
+        if (undeadPids([child.pid]).length)
+            recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
+        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}`);
+    });
+    await confirmOwnPort(port, boot, ended, (service.type ?? 'twin') === 'twin', `Service "${service.id}"`, log, true).catch((error) => {
+        if (undeadPids([child.pid]).length)
+            recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+        try {
+            process.kill(-child.pid, 'SIGTERM');
+        }
+        catch { /* best effort cleanup */ }
+        throw error;
+    });
+    if (exitState.value !== null) {
+        throw new Error(`Service "${service.id}" ended during startup even though port ${port} answers, so another/stale process probably holds the port: the service ${endedAccount(log)}\n`
+            + `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 untilReadyOrEnded((abort) => awaitReadiness(resolveReadyProbe(service.ready, { host, port, url }), log, cwd, service.id, env, abort), ended, boot, 'the service', log).catch((error) => {
+            if (undeadPids([child.pid]).length)
+                recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
+            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,
+        ...(mounted.version !== undefined ? { resolvedVersion: mounted.version } : {}),
+        ...(mounted.protocol !== undefined ? { protocol: mounted.protocol } : {}),
+        pid: child.pid ?? 0,
+        log,
+        env: {
+            ...(service.injectEnv ? { [service.injectEnv]: url } : {}),
+            ...resolveServiceEnvTemplates(service.injectEnvTemplates, { host, port, url }),
+            ...resolveCliRedirect(service.cliRedirect, url),
+        },
+    };
+}
+/** What the host is about to mount, read WITHOUT importing the pack (the kernel never imports
+ *  packs): the nearest package.json above the module for the version, pack-facts for the
+ *  protocol standing the catalog recorded — keyed by the vendor dir the module sits in, else
+ *  the service id. */
+function mountedPackage(modulePath, serviceId) {
+    const out = {};
+    let dir = dirname(modulePath);
+    for (let i = 0; i < 6; i++) {
+        const p = join(dir, 'package.json');
+        if (existsSync(p)) {
+            try {
+                const v = JSON.parse(readFileSync(p, 'utf8')).version;
+                if (typeof v === 'string') {
+                    out.version = v;
+                    out.packagePath = p;
+                }
+            }
+            catch { /* unreadable: no version to hold a pin against */ }
+            break;
+        }
+        const up = dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    const m = /\/packages\/twin\/([^/]+)\//.exec(modulePath) ?? /@volter\/twin-([^/]+)\//.exec(modulePath);
+    const vendor = m?.[1] ?? serviceId;
+    try {
+        const facts = packFacts()[vendor];
+        if (facts?.protocol)
+            out.protocol = facts.protocol;
+    }
+    catch { /* no artifact: the standing is unknown, not refused */ }
+    return out;
+}
+/** R17 + R16 at boot, on BOTH paths (the colocated host and the spawned process): the mounted
+ *  package must satisfy the pin, its protocol standing must not be refused, and a deprecated one
+ *  is said aloud. Returns what to stamp on the instance record. */
+function lockfileCheck(service, modulePath) {
+    const mounted = mountedPackage(modulePath, service.id);
+    if (service.version !== undefined) {
+        if (mounted.version === undefined)
+            throw new Error(`Twin "${service.id}" pins version ${service.version} but no package.json was found above ${modulePath} — nothing to hold the pin against`);
+        if (!versionSatisfies(mounted.version, service.version))
+            throw new Error(`Twin "${service.id}" pins version ${service.version} and the mounted package is ${mounted.version} (${mounted.packagePath}) — re-pin the world config, or mount the version it names (volter-world outdated lists both)`);
+    }
+    if (mounted.protocol?.standing === 'refused')
+        throw new Error(`Twin "${service.id}" targets protocol major ${mounted.protocol.major}; this platform serves ${PROTOCOL_VERSION} and the previous major only (runtime contract R16)`);
+    if (mounted.protocol?.standing === 'deprecated')
+        process.stderr.write(`volter-world: twin "${service.id}" targets protocol major ${mounted.protocol.major}, one behind this platform's ${PROTOCOL_VERSION} — served for this cycle under deprecation (R16)\n`);
+    return mounted;
+}
+/** The module a spawned twin runs from: its first arg under packages/twin/<vendor>/ or an installed
+ *  @volter/twin-<vendor>/ package, resolved. */
+function spawnedTwinModule(service, root) {
+    const first = (service.args ?? []).find((a) => /packages\/twin\/[^/]+\//.test(a) || /@volter\/twin-[^/]+\//.test(a));
+    return first === undefined ? undefined : (first.startsWith('/') ? first : resolve(root, first));
+}
+/**
+ * The config as the runtime boots it (docs/concepts/worlds.md#the-config-and-the-running-world): a service
+ * naming a `package` gets its entry and colocate module resolved from the world root NOW, by
+ * node's own walk, and a `$mint` env value becomes a freshly minted throwaway credential for this
+ * boot. Everything downstream sees ordinary command/args/module/env.
+ */
+function materializeConfig(config, root) {
+    const services = config.services.map((service) => {
+        if (service.package === undefined)
+            return service;
+        const dir = resolveServicePackage(root, service.package);
+        // the pack's entry and cli come from ITS MANIFEST (src/*.ts in the checkout, dist/src/*.js once
+        // published) and the twin's process is the runtime's own — a world runs under Node as under Bun
+        const colocate = service.colocate === undefined ? undefined : { ...service.colocate, module: service.colocate.module ?? packEntry(dir) };
+        const cli = packCli(dir);
+        if (service.command === undefined && cli === undefined)
+            throw new Error(`${service.package} names no cli in its manifest (bin) and has no src/cli.ts`);
+        return {
+            ...service,
+            command: service.command ?? process.execPath,
+            args: service.command === undefined ? [cli, 'serve', ...(service.args ?? [])] : service.args,
+            ...(colocate === undefined ? {} : { colocate }),
+        };
+    });
+    // an empty value (a repository's .env.example key with none, in a World initialized before init left them out) is left
+    // unset, as world-machine leaves it: set, even to nothing, it would win over the app's own env files
+    const env = config.env === undefined ? undefined
+        : Object.fromEntries(Object.entries(config.env).filter(([, value]) => value !== '').map(([name, value]) => [name, value === MINT_ENV ? fakeEnvValue(name) : value]));
+    return { ...config, services, ...(env === undefined ? {} : { env }) };
+}
+/** `^a.b` admits the same major at minor ≥ b; anything else is an exact pin. */
+function versionSatisfies(actual, pin) {
+    const parse = (v) => v.replace(/^\^/, '').split('.').map((x) => Number(x));
+    const [am, an] = parse(actual);
+    const [pm, pn] = parse(pin);
+    if (pin.startsWith('^'))
+        return am === pm && (an ?? 0) >= (pn ?? 0);
+    return actual === pin;
+}
+/**
+ * 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, colocated, isolation, worldEnv, paths, allocatedPorts, boot) {
+    const hostCli = siblingScript(import.meta.url, 'host-cli');
+    const args = [hostCli, '--isolation', isolation === 'colocated' ? 'shared' : 'worker'];
+    const allocated = [];
+    for (const service of colocated) {
+        const port = service.port === undefined || service.port === 'auto' ? await allocatePort(allocatedPorts) : 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 declared = service.colocate.module;
+        const module = declared.startsWith('.') ? resolve(paths.root, declared) : declared;
+        // R17 — the lockfile check, BEFORE the host boots: what this module's own package.json says
+        // it is, against the pin the world config carries; and R16 — the protocol standing the
+        // catalog recorded for the package (pack-facts), refused two majors back, warned one back.
+        const mounted = lockfileCheck(service, module);
+        const scenario = service.colocate.scenarioPath;
+        args.push('--spec', [service.id, module, service.colocate.export, String(port), serviceDataDir, ...(scenario ? [`scenario=${scenario.startsWith('/') ? scenario : resolve(paths.root, scenario)}`] : [])].join('|'));
+        allocated.push({ service, port, mounted });
+    }
+    const log = join(paths.logs, 'host.log');
+    // 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 = { ...admittedEnv(config.stripEnv), ...(config.env ?? {}), ...worldEnv };
+    for (const key of CONTROL_PLANE_EGRESS_ENV)
+        delete env[key];
+    env.VOLTER_WORLD_BOOT_ID = boot.bootId;
+    // Under the same exit recorder as a process service, so the host's end (and every twin it holds) is in host.log.
+    const { child, ended } = spawnRecorded('host', process.execPath, args, paths.root, env, log);
+    child.once('error', error => boot.fail(error));
+    child.unref();
+    trackBootingChild(child, boot);
+    const exitState = { value: null };
+    child.on('exit', (code, signal) => {
+        exitState.value = { code, signal };
+    });
+    const command = [process.execPath, ...args];
+    for (const { service, port } of allocated) {
+        const bindTimeoutMs = typeof service.ready === 'object' && service.ready.timeoutMs !== undefined ? Math.max(service.ready.timeoutMs, 15_000) : 15_000;
+        await untilReadyOrEnded((abort) => waitForTcp(port, bindTimeoutMs, abort), ended, boot, 'the co-located host', log).catch((error) => {
+            if (undeadPids([child.pid]).length)
+                recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
+            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}`);
+        });
+    }
+    for (const [index, { service, port }] of allocated.entries()) {
+        // A host holding one twin settles for that one port, so its twin may be confirmed early like a lone service's.
+        await confirmOwnPort(port, boot, index === 0 ? ended : undefined, true, `Co-located twin "${service.id}"`, log, allocated.length === 1).catch((error) => {
+            if (undeadPids([child.pid]).length)
+                recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
+            try {
+                process.kill(-child.pid, 'SIGTERM');
+            }
+            catch { /* best effort cleanup */ }
+            throw error;
+        });
+    }
+    if (exitState.value !== null) {
+        throw new Error(`The co-located host ended during startup even though its ports answer, so other/stale processes probably hold them: the host ${endedAccount(log)}\n`
+            + `Stop leftover services (e.g. \`volter-world down\`) and retry.\nLog: ${log}`);
+    }
+    const host = '127.0.0.1';
+    return allocated.map(({ service, port, mounted }) => {
+        const url = `http://${host}:${port}`;
+        return {
+            id: service.id,
+            type: service.type ?? 'twin',
+            command,
+            port,
+            url,
+            ...(mounted.version !== undefined ? { resolvedVersion: mounted.version } : {}),
+            ...(mounted.protocol !== undefined ? { protocol: mounted.protocol } : {}),
+            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, options = {}, abort) {
+    abort?.throwIfAborted();
+    const root = resolve(options.root ?? process.cwd());
+    const found = loadWorldConfig(configId, root);
+    const loaded = { path: found.path, config: materializeConfig(found.config, root) };
+    const name = options.name ?? loaded.config.id;
+    const mode = options.mode ?? 'local';
+    assertSafeWorldName(name);
+    // R18 — the birth stamp: this platform reads its own protocol major's state and the previous
+    // one's by construction, and nothing else. A world two majors back, or born under a newer
+    // platform, is refused by name; its state travels through the snapshot doors, never an
+    // in-place rewrite. An unstamped world (born before the stamp existed) is read as current.
+    {
+        const born = loaded.config.catalog?.protocol;
+        if (born !== undefined) {
+            const major = Number(born);
+            if (major > PROTOCOL_MAJOR)
+                throw new Error(`World "${name}" was born under platform protocol major ${major}; this platform is ${PROTOCOL_VERSION} and cannot read a newer world's state (runtime contract R18) — run it on the platform it was born on, or export it there and re-init here`);
+            if (major < PROTOCOL_MAJOR - 1)
+                throw new Error(`World "${name}" was born under platform protocol major ${major}; this platform (${PROTOCOL_VERSION}) reads one major back and no further (runtime contract R18) — export its state through the snapshot door, re-init, import`);
+            if (major === PROTOCOL_MAJOR - 1)
+                process.stderr.write(`volter-world: world "${name}" was born under protocol major ${major}, one behind this platform's ${PROTOCOL_VERSION}; read by construction this cycle — re-init to re-stamp it (R18)\n`);
+        }
+    }
+    assertMode(mode);
+    let 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. A CONFIG-sourced isolation is a local-mode preference (init emits
+    // `isolation: 'colocated'` so a local world costs one twin process — R2a), so share/sealed
+    // quietly boot it per-process, their contractual shape; only an EXPLICIT --isolation flag
+    // contradicting the mode is an error, because the caller asked for two things at once.
+    if (mode !== 'local' && isolation !== 'process') {
+        if (options.isolation === undefined) {
+            isolation = 'process';
+        }
+        else {
+            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');
+    if (loaded.config.resources)
+        process.stderr.write(`World "${name}": config resources is deprecated; declarations are not reservations or enforced limits. Configure limits in the execution backend.\n`);
+    checkedOwner(options.owner);
+    let resourcesClaimed = false;
+    let cleanupUncertain = false;
+    const createdAt = new Date().toISOString();
+    // 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.
+    try {
+        withFileLock(instanceLockFile(root, name), () => {
+            assertProxyOwnershipResolved(root, name);
+            if (liveBootingClaim(stoppingFile(root, name)))
+                throw new Error(`World "${name}" is being stopped; retry after teardown finishes`);
+            const attached = worldConsumers(root, name);
+            if (attached.warnings.length || attached.consumers.some((c) => c.state !== 'exited')) {
+                throw new Error(`World "${name}" has active or uncertain attached consumers; cannot replace its instance`);
+            }
+            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).`);
+            }
+            if (!options.keepState)
+                assertWorldStateRemovable(root, instance);
+            // A legacy record can have been removed by an older reader while its external effects
+            // remain. Require a receipt for the exact prior instance, not merely absent claims/PIDs.
+            if (existsSync(instanceFile)) {
+                const priorRaw = readFileSync(instanceFile, 'utf8');
+                const prior = JSON.parse(priorRaw);
+                const receiptPath = join(instance, 'stopped.json');
+                const receipt = existsSync(receiptPath) ? JSON.parse(readFileSync(receiptPath, 'utf8')) : undefined;
+                if (prior.name !== name || resolve(prior.root) !== root || !receipt
+                    || receipt.instanceHash !== createHash('sha256').update(priorRaw).digest('hex')
+                    || !Number.isFinite(Date.parse(receipt.stoppedAt))) {
+                    throw new Error(`World "${name}" has no verified teardown receipt for its prior instance; use its owning runtime to complete cleanup before replacement`);
+                }
+            }
+            assertLifecycleStartable(root, name);
+            beginWorldLifecycle(root, name, createdAt, options.owner);
+            resourcesClaimed = true;
+            retainWorldLifecycleForCleanup(root, name);
+            // The last run's logs survive this boot as logs/previous (one generation): the record of a crash must outlive the
+            // restart that usually follows it. Moved aside before the wipe and back in after it.
+            const previousLogs = join(dirname(instance), `.${name}.previous-logs`); // dot-prefixed: bookkeeping, never listed as a World
+            if (existsSync(previousLogs) && !existsSync(logs)) {
+                mkdirSync(instance, { recursive: true });
+                renameSync(previousLogs, logs);
+            } // an earlier failed claim's, back first
+            rmSync(previousLogs, { recursive: true, force: true });
+            if (existsSync(logs)) {
+                rmSync(join(logs, 'previous'), { recursive: true, force: true });
+                renameSync(logs, previousLogs);
+            }
+            try {
+                if (options.keepState) {
+                    const KEEP = ['data', 'marks', 'changesets', 'episodes'];
+                    for (const entry of existsSync(instance) ? readdirSync(instance) : [])
+                        if (!KEEP.includes(entry))
+                            rmSync(join(instance, entry), { recursive: true, force: true });
+                }
+                else
+                    removeWorldState(root, instance, () => rmSync(instance, { recursive: true, force: true }));
+            }
+            catch (error) {
+                // The claim failed; the logs go back where they were rather than wait aside for the next boot to discard.
+                try {
+                    if (existsSync(previousLogs) && !existsSync(logs)) {
+                        mkdirSync(instance, { recursive: true });
+                        renameSync(previousLogs, logs);
+                    }
+                }
+                catch { /* left aside; restored by the next claim */ }
+                throw error;
+            }
+            mkdirSync(logs, { mode: 0o700, recursive: true });
+            if (existsSync(previousLogs))
+                renameSync(previousLogs, join(logs, 'previous'));
+            mkdirSync(data, { mode: 0o700, recursive: true });
+            chmodSync(instance, 0o700);
+            chmodSync(logs, 0o700);
+            chmodSync(data, 0o700);
+            writeFileSync(bootingFile(root, name), `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`, { mode: 0o600 });
+        });
+    }
+    catch (error) {
+        if (resourcesClaimed)
+            releaseWorldLifecycle(root, name);
+        throw error;
+    }
+    // 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 = {};
+        const inheritedEnv = admittedEnv(loaded.config.stripEnv);
+        const env = {
+            ...(loaded.config.env ?? {}),
+            VOLTER_WORLD_STRIP_ENV: JSON.stringify(loaded.config.stripEnv ?? []),
+            // the names this World sets itself, apart from what the caller's shell passes through (world-core's worldEnvValue)
+            [WORLD_ENV_NAMES_ENV]: JSON.stringify(Object.keys(loaded.config.env ?? {}).sort()),
+            VOLTER_WORLD_NAME: name,
+            // the world ref the dormant attach entry (`import '@volter/world-core/attach'`) arms the injector
+            // on — what a Bun process, which ignores NODE_OPTIONS, reads to reach the twins inside `run`
+            VOLTER_WORLD: name,
+            ...(loaded.config.network ? { [WORLD_NETWORK_POLICY_ENV]: JSON.stringify(createWorldNetworkPolicy(name, mode === 'sealed' ? { egress: [] } : loaded.config.network)) } : {}),
+            VOLTER_WORLD_MODE: mode,
+            VOLTER_WORLD_CONFIG: loaded.path,
+            VOLTER_WORLD_INSTANCE: instanceFile,
+            VOLTER_WORLD_DATA: data,
+            // the live env file this `up` writes: what a service that runs apps elsewhere (world-machine's guest) carries there
+            VOLTER_WORLD_ENV_FILE: envFile,
+            // THE WORLD CLOCK: every service stamps from this file via the kernel's worldNow();
+            // absent until `volter-world clock <name> set/advance` writes it (→ real time).
+            TWIN_WORLD_CLOCK_FILE: clockFile(root, name),
+            // 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()}${inheritedEnv.NODE_OPTIONS ? ` ${inheritedEnv.NODE_OPTIONS}` : ''}`,
+        };
+        env.NO_PROXY = `127.0.0.1,localhost${env.NO_PROXY || inheritedEnv.NO_PROXY ? `,${env.NO_PROXY ?? inheritedEnv.NO_PROXY}` : ''}`;
+        env.no_proxy = `127.0.0.1,localhost${env.no_proxy || inheritedEnv.no_proxy ? `,${env.no_proxy ?? inheritedEnv.no_proxy}` : ''}`;
+        writeProxyEnv(root, name, env);
+        const worldInstance = {
+            name, config: loaded.config.id, configPath: loaded.path, root, createdAt, mode,
+            dirs: { instance, logs, data }, services, env, envFile, pidsFile,
+            ...(loaded.config.selection ? { selection: loaded.config.selection } : {}),
+            ...(loaded.config.actors ? { actors: loaded.config.actors } : {}),
+            ...(loaded.config.fixtures ? { fixtures: loaded.config.fixtures } : {}),
+            lifecycle: { owner: options.owner, log: lifecycleLogPath(root, name) },
+        };
+        saveWorldInstance(worldInstance);
+        const cancelled = new AbortController();
+        const onBootSignal = (signal) => cancelled.abort(new Error(`World "${name}": boot interrupted by ${signal}`));
+        const onOwnerEnd = () => cancelled.abort(new Error(typeof abort?.reason === 'string' && abort.reason.startsWith('SIG')
+            ? `World "${name}": boot interrupted by ${abort.reason}` : `World "${name}": caller ended during boot`));
+        process.on('SIGTERM', onBootSignal);
+        process.on('SIGINT', onBootSignal);
+        abort?.addEventListener('abort', onOwnerEnd, { once: true });
+        if (abort?.aborted)
+            onOwnerEnd();
+        const detachBootSignals = () => {
+            offSignal('SIGTERM', onBootSignal);
+            offSignal('SIGINT', onBootSignal);
+            abort?.removeEventListener('abort', onOwnerEnd);
+        };
+        const boot = {
+            bootId: randomUUID(), signal: cancelled.signal, fail: error => cancelled.abort(error), pids: new Set(),
+            external: service => { services[service.id] = service; saveWorldInstance(worldInstance); },
+            recordPids: () => writeOwnedPids(root, name, [...boot.pids], [...boot.pids]),
+        };
+        const recordPidsSoFar = boot.recordPids;
+        try {
+            // Ownership survives caller/process loss without an inert capacity-holder process.
+            retainWorldLifecycleForCleanup(root, name);
+            // Protect later explicit ports before selecting any automatic port, across both paths.
+            const allocatedPorts = new Set(loaded.config.services.flatMap((service) => typeof service.port === 'number' ? [service.port] : []));
+            // 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 }, allocatedPorts, boot)) {
+                    services[started.id] = started;
+                    Object.assign(env, started.env);
+                }
+                recordPidsSoFar();
+                writeProxyEnv(root, name, env);
+            }
+            let proxyForServices = 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 = () => {
+                if (proxyForServices || (Object.keys(activeVendorMap(env)).length === 0 && env[WORLD_NETWORK_POLICY_ENV] === undefined))
+                    return;
+                if (!opensslAvailable()) {
+                    if (mode === 'sealed' || loaded.config.network !== undefined) {
+                        throw new Error(`world "${name}" requires its network policy proxy, but openssl is unavailable; refusing to start. Install openssl.`);
+                    }
+                    return;
+                }
+                proxyForServices = ensureWorldProxyFromEnv(name, root, env, boot);
+                if (proxyForServices?.url) {
+                    Object.assign(env, proxyForServices.env);
+                }
+                else if (mode === 'sealed' || loaded.config.network !== undefined) {
+                    // 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(`world "${name}" requires its network policy proxy, but it failed to start; refusing to start`);
+                }
+            };
+            for (const service of loaded.config.services) {
+                if (services[service.id])
+                    continue; // already up co-located
+                attemptProxy();
+                boot.signal.throwIfAborted();
+                const started = await startService(loaded.config, service, env, { root, instance, logs, data }, allocatedPorts, boot);
+                services[started.id] = started;
+                recordPidsSoFar();
+                Object.assign(env, started.env);
+                writeProxyEnv(root, name, env);
+            }
+            detachBootSignals();
+            // 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();
+            // Inert-injectEnv check (LibreChat blind-adoption finding): an injectEnv like AWS_TWIN_URL
+            // lands in the world env, LOOKS wired, and does nothing — the injector reads no such vendor.
+            // Warn loudly at `up`, when the operator is watching, instead of letting the disagreement
+            // surface later as silently-real vendor traffic.
+            for (const warning of inertInjectEnvWarnings(loaded.config.services)) {
+                process.stderr.write(`${warning}\n`);
+            }
+            mkdirSync(dirname(envFile), { recursive: true });
+            // Config env and discovered credentials: a file this writes is owner-only; a file the caller already made keeps
+            // the mode the caller chose (a shared env file may be read under another uid).
+            writeFileSync(envFile, envFileContents(env), { mode: 0o600 });
+            writePidsFromInstance(worldInstance, Object.values(worldInstance.services).map((service) => service.pid).filter((pid) => pid > 0));
+            saveWorldInstance(worldInstance);
+            const servicePids = [...new Set(Object.values(services).map((service) => service.pid).filter((pid) => pid > 0))];
+            handoffWorldLifecycle(root, name, servicePids);
+            if (mode === 'share') {
+                try {
+                    return await shareWorldServices(name, { root, ...(options.share ?? {}) });
+                }
+                catch (error) {
+                    await downWorld(name, root);
+                    throw error;
+                }
+            }
+            return worldInstance;
+        }
+        catch (error) {
+            cleanupUncertain = true;
+            detachBootSignals();
+            // Rollback never lets its own failure replace the boot's: each step's error is added to the original.
+            const rollbackErrors = [];
+            try {
+                stopWorldProxy(root, name);
+            }
+            catch (proxyError) {
+                rollbackErrors.push(`proxy stop failed: ${proxyError instanceof Error ? proxyError.message : String(proxyError)}`);
+            }
+            const pids = [...new Set([...Object.values(services).map((service) => service.pid).filter(Boolean), ...boot.pids])];
+            const rollbackAlive = undeadPids(Object.values(services).map((service) => service.pid).filter(Boolean));
+            const rollbackLogs = Object.values(services).filter((service) => service.type !== 'external' && service.log && rollbackAlive.includes(service.pid)).map((service) => service.log);
+            recordWorldStop(rollbackLogs, 'world.service.stop', 'boot rollback', 'SIGTERM');
+            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.
+            for (const service of Object.values(services)) {
+                if (service.type === 'external' && service.external) {
+                    // Same env shape as up/status (startExternalService) and downWorld's teardown:
+                    // Admitted caller variables keep allowed tools findable without reintroducing
+                    // credentials that were excluded when this World started.
+                    const downEnv = { ...admittedEnv(loaded.config.stripEnv), ...env, ...(service.external.discoveredEnv ?? {}) };
+                    try {
+                        await 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.
+            const rollbackKilled = await killSurvivorsAfterGrace(pids, DOWN_GRACE_MS_DEFAULT);
+            recordWorldStop(Object.values(services).filter((service) => rollbackKilled.includes(service.pid) && service.log).map((service) => service.log), 'world.service.killed', 'boot rollback', 'SIGKILL');
+            const surviving = undeadPids(pids);
+            if (surviving.length)
+                rollbackErrors.push('owned processes remain alive or uncertain');
+            if (error instanceof CommandRetirementError)
+                rollbackErrors.push(error.message);
+            if (rollbackErrors.length > 0) {
+                cleanupUncertain = true;
+                try {
+                    retainWorldLifecycleForCleanup(root, name);
+                    saveWorldInstance(worldInstance);
+                }
+                catch (bookkeepingError) {
+                    rollbackErrors.push(`rollback bookkeeping failed: ${bookkeepingError instanceof Error ? bookkeepingError.message : String(bookkeepingError)}`);
+                }
+                const suffix = `\n(rollback incomplete — processes or an external stack may still be 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}`);
+            }
+            if (rollbackErrors.length === 0) {
+                // Publication failure must retain ownership. Prune requires both a receipt and release.
+                cleanupUncertain = true;
+                try {
+                    rmSync(pidsFile, { force: true });
+                    const raw = readFileSync(instanceFile, 'utf8');
+                    writeTextAtomic(join(instance, 'stopped.json'), JSON.stringify({ instanceHash: createHash('sha256').update(raw).digest('hex'), stoppedAt: new Date().toISOString() }));
+                    releaseWorldLifecycle(root, name);
+                    cleanupUncertain = false;
+                }
+                catch (receiptError) {
+                    const note = `\n(rollback stopped every process but could not publish its teardown receipt: ${receiptError instanceof Error ? receiptError.message : String(receiptError)}; lifecycle retained)`;
+                    if (error instanceof Error)
+                        error.message += note;
+                    else
+                        throw new Error(`${String(error)}${note}`);
+                }
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        if (resourcesClaimed) {
+            try {
+                recordWorldLifecycleEvent(root, name, `boot failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            catch (diagnosticError) {
+                process.stderr.write(`World "${name}": could not save boot failure: ${String(diagnosticError)}; original failure: ${String(error)}\n`);
+            }
+            if (!cleanupUncertain)
+                releaseWorldLifecycle(root, name);
+        }
+        throw error;
+    }
+    finally {
+        rmSync(bootingFile(root, name), { force: true });
+    }
+}
+async function teardownExternalServices(instance) {
+    const stopped = [];
+    const errors = [];
+    for (const service of Object.values(instance.services)) {
+        if (service.type !== 'external')
+            continue;
+        if (!service.external || !Array.isArray(service.external.down) || !service.external.down.length
+            || service.external.down.some((arg) => typeof arg !== 'string') || typeof service.external.cwd !== 'string') {
+            errors.push(`External service "${service.id}": missing or invalid teardown metadata; lifecycle retained`);
+            continue;
+        }
+        const downEnv = { ...admittedEnv(stripEnvOf(instance.env ?? {})), ...(instance.env ?? {}), ...(service.external.discoveredEnv ?? {}) };
+        try {
+            await 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 docs/concepts/worlds.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, signal) {
+    const signalled = [];
+    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;
+}
+/** 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) {
+    return survivingOwnedGroups(pids);
+}
+/** 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, graceMs) {
+    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, graceMs) {
+    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/concepts/data-and-keys.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 leaves that lock alone; its owner's finally releases it, so waiting claimants never
+ *    enter through a replacement lock while the original is still held.
+ */
+function purgeInstanceDir(root, name) {
+    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}"`);
+    }
+    removeWorldState(root, dir, () => rmSync(dir, { recursive: true, force: true }));
+    // The caller holds this lock. Never unlink it while another up may be waiting on it.
+    return dir;
+}
+class WorldConsumersActiveError extends Error {
+}
+export async function downWorld(name, root = process.cwd(), options = {}) {
+    assertSafeWorldName(name);
+    const resolvedRoot = resolve(root);
+    const token = randomUUID();
+    // Like boot's claim: a short synchronous lock protects an async lifecycle transition.
+    // Do not hold a filesystem lock while external shutdown or the grace period waits.
+    withFileLock(instanceLockFile(resolvedRoot, name), () => withFileLock(`${sharingClaimFile(resolvedRoot, name)}.lock`, () => {
+        assertProxyOwnershipResolved(resolvedRoot, name);
+        const prior = existsSync(instanceFile(resolvedRoot, name)) ? readWorldInstance(name, resolvedRoot, true) : undefined;
+        if (prior?.resources && !prior.lifecycle)
+            throw new Error(`World "${name}" belongs to a legacy runtime; use its pinned runtime for teardown before migration`);
+        if (options.expectedCreatedAt !== undefined && readWorldInstance(name, resolvedRoot, true).createdAt !== options.expectedCreatedAt) {
+            throw new Error(`World "${name}" generation changed; teardown refused`);
+        }
+        if (options.purge)
+            assertWorldStateRemovable(resolvedRoot, instanceDir(resolvedRoot, name));
+        prepareBootForDown(resolvedRoot, name);
+        if (liveBootingClaim(stoppingFile(resolvedRoot, name)))
+            throw new Error(`World "${name}" is already being stopped`);
+        const consumers = worldConsumers(resolvedRoot, name);
+        if (consumers.warnings.length || consumers.consumers.some((c) => c.state !== 'exited')) {
+            throw new WorldConsumersActiveError(`World "${name}" has active or uncertain attached consumers; finish the attached commands before down. Inspect: volter-world resources --root ${shellQuote(resolvedRoot)}`);
+        }
+        const sharePath = sharingClaimFile(resolvedRoot, name);
+        if (existsSync(sharePath)) {
+            const sharing = readSharingClaim(sharePath);
+            if (!sharing || sharingClaimAlive(sharing))
+                throw new Error(`World "${name}" is being shared or has an unreadable sharing claim; retry after sharing finishes`);
+            rmSync(sharePath); // explicit down may reclaim a provably stale sharing claim
+        }
+        retainWorldLifecycleForCleanup(resolvedRoot, name);
+        writeTextAtomic(stoppingFile(resolvedRoot, name), JSON.stringify({ pid: process.pid, at: new Date().toISOString(), token }));
+    }));
+    try {
+        return await downWorldClaimed(name, resolvedRoot, options);
+    }
+    finally {
+        withFileLock(instanceLockFile(resolvedRoot, name), () => {
+            const path = stoppingFile(resolvedRoot, name);
+            if (existsSync(path) && JSON.parse(readFileSync(path, 'utf8')).token === token)
+                rmSync(path);
+        });
+    }
+}
+async function downWorldClaimed(name, root, options) {
+    assertSafeWorldName(name);
+    const resolvedRoot = resolve(root);
+    const dir = instanceDir(resolvedRoot, name);
+    const pidsFile = join(dir, 'pids');
+    const before = existsSync(instanceFile(resolvedRoot, name)) ? readFileSync(instanceFile(resolvedRoot, name), 'utf8') : undefined;
+    // A retry must not retain an earlier success receipt while teardown is in progress.
+    rmSync(join(dir, 'stopped.json'), { force: true });
+    // 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).
+    let instance;
+    try {
+        instance = readWorldInstance(name, resolvedRoot);
+        if (instance.name !== name || typeof instance.root !== 'string' || resolve(instance.root) !== resolvedRoot || !instance.services)
+            throw new Error('invalid identity');
+    }
+    catch {
+        instance = undefined;
+    }
+    // Nothing to tear down when the metadata is gone and every process the lifecycle recorded has exited.
+    if (!instance && before === undefined && releaseAbandonedWorldLifecycle(resolvedRoot, name)) {
+        return { name, stopped: [], escalated: [], externalStopped: [], externalErrors: [] };
+    }
+    if (!instance && (before !== undefined || hasWorldLifecycle(resolvedRoot, name))) {
+        return { name, stopped: [], escalated: [], externalStopped: [],
+            externalErrors: ['World instance or external teardown metadata missing or unreadable; cleanup refused; lifecycle evidence retained'] };
+    }
+    const proxyPid = readProxyState(resolvedRoot, name)?.pid;
+    stopWorldProxy(resolvedRoot, name);
+    const foregroundPid = instance?.lastRun?.state !== 'completed' ? instance?.lastRun?.consumerPid : undefined;
+    const holderPid = instance?.lifecycle?.holderPid ?? instance?.resources?.holderPid;
+    const recordedPids = [...new Set([...readPids(pidsFile), ...(foregroundPid ? [foregroundPid] : []), ...(proxyPid ? [proxyPid] : [])])].filter(pid => pid !== holderPid);
+    const foreign = foreignPids(resolvedRoot, name, recordedPids);
+    const pids = recordedPids.filter((pid) => !foreign.some((entry) => entry.pid === pid));
+    const processServices = Object.values(instance?.services ?? {}).filter((service) => service.type !== 'external' && service.log);
+    // Only a service still alive is stopped by this `down`; a dead one's end was not the World's.
+    const stillAlive = undeadPids(processServices.map((service) => service.pid).filter((pid) => pids.includes(pid)));
+    recordWorldStop(processServices.filter((service) => stillAlive.includes(service.pid)).map((service) => service.log), 'world.service.stop', 'down', 'SIGTERM');
+    const stopped = signalPids(pids, 'SIGTERM');
+    // Stop self-managed externals via their declared `down` command. A missing instance is
+    // safe only without retained lifecycle ownership, checked before any signals above.
+    let externalStopped = [];
+    let externalErrors = [];
+    try {
+        if (!instance)
+            throw new Error('World instance unavailable');
+        const result = await teardownExternalServices(instance);
+        externalStopped = result.stopped;
+        externalErrors = result.errors;
+    }
+    catch {
+        // no instance.json (never fully came up) — only owned processes needed stopping.
+        if (before !== undefined)
+            externalErrors.push('World instance or external teardown metadata unreadable; cleanup refused');
+    }
+    // Escalate AFTER the 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);
+    recordWorldStop(processServices.filter((service) => escalated.includes(service.pid)).map((service) => service.log), 'world.service.killed', 'down', 'SIGKILL');
+    if (holderPid && !externalErrors.length && !undeadPids(pids).length) {
+        pids.push(holderPid);
+        stopped.push(...signalPids([holderPid], 'SIGTERM'));
+        escalated.push(...await killSurvivorsAfterGrace([holderPid], options.graceMs ?? DOWN_GRACE_MS_DEFAULT));
+    }
+    // Finalization belongs to this exact generation, not just the reusable name. A new up may
+    // win once the old PIDs exit; never erase its PID file, lifecycle or instance directory.
+    return withFileLock(instanceLockFile(resolvedRoot, name), () => withFileLock(`${sharingClaimFile(resolvedRoot, name)}.lock`, () => {
+        const notSignalled = foreign.map((entry) => `pid ${entry.pid} now names another process (started ${entry.now}; the World's started ${entry.recorded}); not signalled`);
+        const result = { name, stopped, escalated, externalStopped, externalErrors, ...(notSignalled.length ? { notSignalled } : {}) };
+        const path = instanceFile(resolvedRoot, name);
+        const current = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+        if (current !== before || existsSync(bootingFile(resolvedRoot, name))) {
+            externalErrors.push('World generation changed or is booting; finalization refused');
+            return result;
+        }
+        if (existsSync(proxyStateFile(resolvedRoot, name)) || existsSync(sharingClaimFile(resolvedRoot, name))) {
+            externalErrors.push('Proxy or sharing lifecycle changed during teardown; cleanup refused');
+            return result;
+        }
+        const surviving = undeadPids(pids);
+        if (surviving.length)
+            externalErrors.push(`World processes still alive or uninspectable after teardown: ${surviving.join(', ')}; cleanup refused`);
+        if (externalErrors.length)
+            return result;
+        rmSync(pidsFile, { force: true });
+        if (before) {
+            writeTextAtomic(join(dir, 'stopped.json'), `${JSON.stringify({
+                instanceHash: createHash('sha256').update(before).digest('hex'), stoppedAt: new Date().toISOString(),
+            })}\n`);
+        }
+        releaseWorldLifecycle(resolvedRoot, name);
+        return options.purge ? { ...result, purged: purgeInstanceDir(resolvedRoot, name) } : result;
+    }));
+}
+export function statusWorld(name, root = process.cwd(), options = {}) {
+    const worldInstance = readWorldInstance(name, resolve(root), options.readOnly);
+    const live = ownedPids(resolve(root), name, livePids(readPids(worldInstance.pidsFile)));
+    const externalOnly = Object.values(worldInstance.services).every(service => service.type === 'external');
+    const recorded = externalOnly && !existsSync(stoppingFile(root, name)) && !existsSync(join(instanceDir(root, name), 'stopped.json'))
+        && isWorldLifecycleRunning(root, name, worldInstance.createdAt);
+    // `running` is ownership (any owned process lives: a service, the proxy daemon, a tunnel), which the lifecycle guards
+    // read; a service's own state is judged by its process group, so a dead service reads as dead beside a live daemon.
+    const owned = Object.values(worldInstance.services).filter((service) => service.type !== 'external' && service.pid);
+    const ownPids = ownedPids(resolve(root), name, owned.map((service) => service.pid));
+    const leaders = livePids(ownPids);
+    // `light` (a listing of every World) skips the process-table scan: a lingering group then reads as stopped.
+    const groups = ownPids.length && !options.light ? survivingOwnedGroups(ownPids) : [];
+    const serviceStates = {};
+    for (const service of Object.values(worldInstance.services)) {
+        serviceStates[service.id] = service.type === 'external' ? 'external'
+            : service.workerGaveUp ? 'gave-up'
+                : leaders.includes(service.pid) ? 'running' : groups.includes(service.pid) ? 'lingering' : 'stopped';
+    }
+    const running = live.length > 0 || recorded;
+    const degraded = running && Object.values(serviceStates).some((state) => state !== 'running' && state !== 'external');
+    return { ...worldInstance, running, livePids: live, serviceStates, degraded };
+}
+function logicalTreeBytes(path) {
+    const stat = lstatSync(path);
+    if (!stat.isDirectory())
+        return stat.size; // never follow symlinks
+    return readdirSync(path).reduce((sum, child) => sum + logicalTreeBytes(join(path, child)), 0);
+}
+/** Fail closed. Neither dead service PIDs nor an absent lifecycle record prove external teardown.
+ * Only down's receipt for this exact instance makes its disposable data eligible. */
+function worldCleanupEntry(name, root) {
+    assertSafeWorldName(name);
+    const path = instanceDir(root, name);
+    const entry = { name, path, eligible: false, reason: '' };
+    try {
+        if ([join(root, stateDirName()), worldBaseDir(root), join(worldBaseDir(root), '.locks'), path]
+            .some((dir) => existsSync(dir) && lstatSync(dir).isSymbolicLink())) {
+            return { ...entry, reason: 'symbolic-link state directory; retained' };
+        }
+        if (!lstatSync(path).isDirectory())
+            return { ...entry, reason: 'not an instance directory' };
+        if (existsSync(proxyStartingFile(root, name)))
+            return { ...entry, reason: 'unresolved proxy startup ownership; retained' };
+        if (existsSync(stoppingFile(root, name)))
+            return { ...entry, reason: 'teardown marker present; retained' };
+        if (existsSync(bootingFile(root, name)))
+            return { ...entry, reason: 'boot marker present; retained' };
+        if (existsSync(proxyStateFile(root, name)))
+            return { ...entry, reason: 'proxy lifecycle record present; retained' };
+        if (existsSync(sharingClaimFile(root, name)))
+            return { ...entry, reason: 'sharing lifecycle claim present; retained' };
+        const raw = readFileSync(instanceFile(root, name), 'utf8');
+        const snapshot = JSON.parse(raw);
+        if (snapshot.name !== name || typeof snapshot.root !== 'string' || resolve(snapshot.root) !== root) {
+            return { ...entry, reason: 'inconsistent instance identity' };
+        }
+        const instance = statusWorld(name, root, { readOnly: true });
+        if (instance.name !== name || typeof instance.createdAt !== 'string' || !instance.services
+            || typeof instance.configPath !== 'string' || resolve(instance.dirs.instance) !== path
+            || resolve(instance.pidsFile) !== join(path, 'pids'))
+            return { ...entry, reason: 'inconsistent instance metadata' };
+        const configRelative = relative(path, resolve(instance.configPath));
+        if (!configRelative || (!configRelative.startsWith(`..${sep}`) && configRelative !== '..')) {
+            return { ...entry, reason: 'source config inside instance; retained' };
+        }
+        const servicePids = Object.values(instance.services).map((service) => service.pid);
+        const knownPids = [...instance.livePids, ...servicePids, instance.lifecycle?.holderPid ?? instance.resources?.holderPid ?? 0];
+        if (undeadPids(knownPids.filter((pid) => Number.isInteger(pid) && pid > 0)).length) {
+            return { ...entry, reason: 'running World; stopping requires explicit down' };
+        }
+        const attached = worldConsumers(root, name, instance.createdAt);
+        if (attached.warnings.length || attached.consumers.some((c) => c.state !== 'exited')) {
+            return { ...entry, reason: 'active or uncertain attached consumer; retained' };
+        }
+        const lastRun = instance.lastRun;
+        if (existsSync(foregroundRunFile(root, name))) {
+            const record = JSON.parse(readFileSync(foregroundRunFile(root, name), 'utf8'));
+            if (!record || !['running', 'abrupt', 'completed'].includes(record.state)
+                || !Number.isInteger(record.runnerPid) || record.runnerPid <= 0)
+                return { ...entry, reason: 'invalid foreground consumer metadata' };
+        }
+        if (lastRun && lastRun.state !== 'completed'
+            && livePids([lastRun.runnerPid, lastRun.consumerPid ?? 0].filter((pid) => pid > 0)).length) {
+            return { ...entry, reason: 'foreground consumer still active' };
+        }
+        if (hasWorldLifecycle(root, name)) {
+            return { ...entry, reason: 'lifecycle ownership remains; verified teardown required' };
+        }
+        const receiptPath = join(path, 'stopped.json');
+        if (!existsSync(receiptPath))
+            return { ...entry, reason: 'no successful teardown receipt (legacy/unknown); review before explicit down' };
+        const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+        if (receipt.instanceHash !== createHash('sha256').update(raw).digest('hex') || !Number.isFinite(Date.parse(receipt.stoppedAt))) {
+            return { ...entry, reason: 'invalid or outdated teardown receipt' };
+        }
+        try {
+            assertWorldStateRemovable(root, path);
+        }
+        catch (error) {
+            return { ...entry, reason: error instanceof Error ? error.message : 'Branch ancestry unreadable; retained' };
+        }
+        return { ...entry, eligible: true, reason: 'successfully stopped; disposable instance data only', stoppedAt: receipt.stoppedAt, logicalBytes: logicalTreeBytes(path) };
+    }
+    catch (error) {
+        // Do not print malformed metadata: it can contain env secrets.
+        return { ...entry, reason: `unreadable or incomplete lifecycle metadata; retained (${error.code ?? 'invalid'})` };
+    }
+}
+/** Preview by default. Apply holds up's lock across fresh eligibility checking and deletion.
+ * Never call down here: that would turn a stale preview into permission to kill a new World. */
+export function pruneWorlds(options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    if (options.name !== undefined)
+        assertSafeWorldName(options.name);
+    const base = worldBaseDir(root);
+    const names = options.name ? [options.name] : existsSync(base)
+        ? readdirSync(base).filter((name) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)).sort() : [];
+    const entries = names.map((name) => {
+        if (!options.apply)
+            return worldCleanupEntry(name, root);
+        // Refuse symlink/incomplete state before even creating a lock through its parent path.
+        const preview = worldCleanupEntry(name, root);
+        if (!preview.eligible)
+            return preview;
+        return withFileLock(instanceLockFile(root, name), () => withFileLock(`${sharingClaimFile(root, name)}.lock`, () => {
+            const entry = worldCleanupEntry(name, root);
+            if (entry.eligible) {
+                removeWorldState(root, entry.path, () => rmSync(entry.path, { recursive: true }));
+                // Keep the sibling lock alone: unlinking it here can break concurrent up's exclusion.
+                return { ...entry, removed: true };
+            }
+            return entry;
+        }));
+    });
+    return { root, apply: options.apply === true, entries };
+}
+function worldServiceControlRoot(name, service, root = process.cwd()) {
+    const instance = readWorldInstance(name, resolve(root));
+    if (!instance.services[service])
+        throw new Error(`World ${name} has no service "${service}"`);
+    return join(instance.dirs.data, service);
+}
+function worldServiceStateService(controlRoot, requestedService) {
+    const stateRoot = join(controlRoot, stateDirName(), 'world');
+    if (!existsSync(stateRoot))
+        return requestedService;
+    const actionServices = readdirSync(stateRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && ['actions.jsonl', 'events.jsonl', 'branch.json'].some((f) => existsSync(join(stateRoot, entry.name, f))))
+        .map((entry) => entry.name);
+    if (actionServices.includes(requestedService))
+        return requestedService;
+    if (actionServices.length === 1)
+        return actionServices[0];
+    if (actionServices.length > 1) {
+        throw new Error(`World service "${requestedService}" records actions under multiple state services (${actionServices.join(', ')}); use volter-twin plan with the explicit service data root`);
+    }
+    return requestedService;
+}
+function shareCommand(options, serviceUrl) {
+    if (options.provider === 'cloudflare-quick' && options.command) {
+        throw new Error('share provider "cloudflare-quick" uses the built-in cloudflared command and cannot be combined with a custom command');
+    }
+    if (!options.command && options.provider === 'command') {
+        throw new Error(`share provider "command" requires a tunnel command (share.command / --command)`);
+    }
+    if (options.command) {
+        return {
+            provider: 'command',
+            command: options.command,
+            args: (options.args ?? []).map((arg) => arg.replaceAll('{url}', serviceUrl)),
+        };
+    }
+    return {
+        provider: 'cloudflare-quick',
+        command: 'cloudflared',
+        args: ['tunnel', '--url', serviceUrl],
+    };
+}
+export function parseCloudflareQuickPublicUrl(candidate) {
+    // Validate the provider's RAW stdout token before WHATWG normalization. Otherwise `%2e` in the
+    // authority, an explicit default `:443`, or `/.` / `/%2e%2e` paths normalize into an apparently
+    // valid origin and bypass the strict cloudflared-output boundary.
+    if (!/^https:\/\/[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.trycloudflare\.com\/?$/.test(candidate))
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(candidate);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.port
+        || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.trycloudflare\.com$/.test(parsed.hostname)
+        || parsed.pathname !== '/' || parsed.search || parsed.hash)
+        return undefined;
+    return parsed.origin;
+}
+function canonicalDottedIpv4(host) {
+    const parts = host.split('.');
+    return parts.length === 4 && parts.every((part) => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255);
+}
+function parseCustomShareOrigin(handshake) {
+    const raw = /^https?:\/\/(\[[0-9a-f:.]+\]|[a-z0-9.-]+)(?::([0-9]{1,5}))?\/?$/i.exec(handshake);
+    if (!raw) {
+        throw new Error(`Custom tunnel VOLTER_SHARE_URL must be a strict http(s) origin without path, query, fragment, or backslashes: ${handshake}`);
+    }
+    const rawHost = raw[1];
+    const rawPort = raw[2];
+    let parsed;
+    try {
+        parsed = new URL(handshake);
+    }
+    catch {
+        throw new Error(`Custom tunnel emitted an invalid VOLTER_SHARE_URL handshake: ${handshake}`);
+    }
+    const normalizedHostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (!rawHost.startsWith('[') && isIP(normalizedHostname) === 4
+        && (!canonicalDottedIpv4(rawHost) || rawHost !== normalizedHostname)) {
+        throw new Error(`Custom tunnel VOLTER_SHARE_URL must use canonical dotted-decimal IPv4 syntax: ${handshake}`);
+    }
+    if (rawPort && rawPort.length > 1 && rawPort.startsWith('0')) {
+        throw new Error(`Custom tunnel VOLTER_SHARE_URL must use canonical decimal port syntax: ${handshake}`);
+    }
+    if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || parsed.username || parsed.password
+        || parsed.pathname !== '/' || parsed.search || parsed.hash) {
+        throw new Error(`Custom tunnel VOLTER_SHARE_URL must be a credential-free http(s) origin: ${handshake}`);
+    }
+    return parsed.origin;
+}
+async function waitForPublicUrl(child, logPath, timeoutMs, requireTryCloudflare) {
+    const urlPattern = /https?:\/\/[^\s"'<>]+/gi;
+    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') : '';
+        if (requireTryCloudflare) {
+            for (const candidate of text.match(urlPattern) ?? []) {
+                const parsed = parseCloudflareQuickPublicUrl(candidate);
+                if (parsed)
+                    return parsed;
+            }
+        }
+        else {
+            const handshake = /^VOLTER_SHARE_URL=(\S+)\s*$/m.exec(text)?.[1];
+            if (handshake)
+                return parseCustomShareOrigin(handshake);
+        }
+        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(requireTryCloudflare
+        ? `Cloudflare tunnel did not print a trycloudflare.com https URL within ${timeoutMs}ms. Log: ${logPath}`
+        : `Custom tunnel did not print VOLTER_SHARE_URL=<http(s)-url> within ${timeoutMs}ms. Log: ${logPath}`);
+}
+function sleep(ms) {
+    return new Promise((resolveWait) => setTimeout(resolveWait, ms));
+}
+function commandExists(command) {
+    // 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) {
+    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, timeoutMs) {
+    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, path) {
+    const url = new URL(publicUrl);
+    url.pathname = path.startsWith('/') ? path : `/${path}`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+async function verifyPublicUrl(publicUrl, path, timeoutMs) {
+    if (!commandExists('curl'))
+        throw new Error('Public URL verification requires curl');
+    const hostname = new URL(publicUrl).hostname;
+    const normalizedHostname = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    const local = normalizedHostname === 'localhost' || normalizedHostname === '::1'
+        || (isIP(normalizedHostname) === 4 && normalizedHostname.split('.')[0] === '127');
+    if (local) {
+        const target = publicHealthUrl(publicUrl, path);
+        const result = spawnSync('curl', ['--noproxy', '*', '-sS', '-o', '-', '-w', '\n%{http_code}', '--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))), target], { encoding: 'utf8' });
+        const separator = result.stdout.lastIndexOf('\n');
+        const body = separator >= 0 ? result.stdout.slice(0, separator).trim() : result.stdout.trim();
+        const status = Number(separator >= 0 ? result.stdout.slice(separator + 1).trim() : '0');
+        if (result.status !== 0 || status < 200 || status >= 400) {
+            throw new Error(`Local shared URL did not pass health verification at ${target}: ${result.stderr.trim() || `HTTP ${status}`}`);
+        }
+        return { path, checkedAt: new Date().toISOString(), hostname, resolvedIp: normalizedHostname === 'localhost' ? '127.0.0.1' : normalizedHostname, status, body: body.slice(0, 500) };
+    }
+    if (!commandExists('dig'))
+        throw new Error('Public URL verification requires dig');
+    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, options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    const serviceId = options.service ?? 'app';
+    assertSafeWorldName(name);
+    const claim = await reserveSharingClaim(root, name, serviceId);
+    const heartbeat = setInterval(() => {
+        try {
+            refreshSharingClaim(root, name, claim.token);
+        }
+        catch { /* retry next tick; same-host process identity still protects the live owner */ }
+    }, SHARE_CLAIM_HEARTBEAT_MS);
+    heartbeat.unref();
+    try {
+        return await shareWorldReserved(name, { ...options, root, service: serviceId });
+    }
+    finally {
+        clearInterval(heartbeat);
+        releaseSharingClaim(root, name, claim.token);
+    }
+}
+async function shareWorldReserved(name, options) {
+    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`);
+    // Each spawned tunnel owns one log generation. Truncating before spawn prevents a repeated
+    // share from accepting the previous process's URL handshake as the new process's endpoint.
+    const out = openPrivateLog(log, 'w');
+    const child = spawn(tunnel.command, tunnel.args, {
+        cwd: root,
+        env: process.env,
+        detached: true,
+        stdio: ['ignore', out, out],
+    });
+    closeSync(out);
+    let publicUrl;
+    let publicVerification;
+    let pidsWritten = false;
+    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);
+        }
+        // Build the prospective instance off to the side. Until BOTH persistence files are written,
+        // callers and the previously loaded instance retain the exact unshared object.
+        const nextInstance = structuredClone(instance);
+        const nextService = nextInstance.services[serviceId];
+        nextService.publicUrl = publicUrl;
+        nextService.publicUrlEphemeral = tunnel.provider === 'cloudflare-quick' || options.ephemeral === true;
+        nextService.publicReady = options.verifyPath !== false;
+        if (publicVerification)
+            nextService.publicVerification = publicVerification;
+        else
+            delete nextService.publicVerification;
+        nextService.tunnel = {
+            provider: tunnel.provider,
+            pid: child.pid ?? 0,
+            log,
+            command: [tunnel.command, ...tunnel.args],
+            startedAt: new Date().toISOString(),
+        };
+        writePidsFromInstance(nextInstance, child.pid ? [child.pid] : []);
+        pidsWritten = true;
+        saveWorldInstance(nextInstance);
+        child.unref();
+        return nextInstance;
+    }
+    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);
+        }
+        const cleanupProblems = [];
+        if (child.pid && undeadPids([child.pid]).length > 0)
+            cleanupProblems.push(`tunnel pid ${child.pid} survived cleanup`);
+        // If the pids write landed but instance.json did not, restore the previous pids projection only
+        // after the child is confirmed dead. Atomic writes ensure a failed write itself leaves the old
+        // file intact; this compensates the one successful write in a two-file persistence attempt.
+        if (pidsWritten) {
+            try {
+                writePidsFromInstance(instance);
+            }
+            catch (restoreError) {
+                cleanupProblems.push(`could not restore pids file: ${restoreError instanceof Error ? restoreError.message : String(restoreError)}`);
+            }
+        }
+        if (cleanupProblems.length > 0) {
+            throw new Error(`${error instanceof Error ? error.message : String(error)}; share cleanup incomplete: ${cleanupProblems.join('; ')}`, { cause: error });
+        }
+        throw error;
+    }
+}
+function configuredShareTargets(instance, requestedService, verifyPath) {
+    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, options = {}) {
+    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) {
+        const provider = options.provider ?? (options.command ? 'command' : config.share?.provider);
+        if (provider === 'cloudflare-quick' && options.command) {
+            throw new Error('share provider "cloudflare-quick" uses the built-in cloudflared command and cannot be combined with a custom command');
+        }
+        // An explicit provider override is authoritative. In particular, selecting the real
+        // Cloudflare provider must clear a config-declared local rehearsal command instead of
+        // launching that command while parsing its output as cloudflared.
+        const command = provider === 'cloudflare-quick' ? undefined : options.command ?? config.share?.command;
+        const args = provider === 'cloudflare-quick' ? undefined : options.args ?? config.share?.args;
+        instance = await shareWorld(name, {
+            ...options,
+            root,
+            provider,
+            command,
+            args,
+            ephemeral: options.ephemeral ?? config.share?.ephemeral,
+            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 docs/concepts/worlds.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, options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    const instance = readWorldInstance(name, root);
+    const serviceIds = options.service ? [options.service] : Object.keys(instance.services);
+    const escalated = [];
+    const stillLive = [];
+    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 `survivingOwnedGroups`' 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, cwd, env, logPath) {
+    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 = serviceOutput(readServiceText(logPath));
+        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)' };
+}
+/** A stopped service's own account for doctor: how it ended, its last output, and where its whole log is. */
+function stoppedServiceReport(pid, log) {
+    const end = readServiceEnd(log);
+    if (!end)
+        return `pid ${pid} is not live\n      log: ${log}`;
+    const said = end.lastOutput.length ? `\n      last output:\n${end.lastOutput.map((line) => `        ${line}`).join('\n')}` : '\n      (no output in its last run)';
+    return `pid ${pid} is not live: it ${describeServiceEnd(end)}${said}\n      log: ${log}`;
+}
+export async function doctorWorld(name, options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    const checks = [];
+    let instance;
+    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 });
+    if (instance.lifecycle) {
+        checks.push({ id: 'lifecycle', ok: hasWorldLifecycle(root, name) && existsSync(instance.lifecycle.log),
+            message: `lifecycle ownership recorded; no capacity reserved; log=${instance.lifecycle.log}` });
+    }
+    const live = livePids(readPids(instance.pidsFile));
+    checks.push({
+        id: 'pids',
+        ok: live.length > 0 || Object.values(instance.services).every(service => service.type === 'external'),
+        message: live.length > 0 ? `live=${live.join(', ')}` : 'no process-backed services are running; external services are checked below',
+    });
+    // The redirect proxy every attached command's HTTPS goes through: a dead one refuses all of their egress.
+    const proxy = readProxyState(root, name);
+    if (proxy) {
+        const proxyLive = livePids([proxy.pid]).length > 0;
+        const proxyLog = proxyLogPath(root, name);
+        checks.push({ id: 'proxy', ok: proxyLive, message: proxyLive ? `pid=${proxy.pid} log=${proxyLog}`
+                : `proxy daemon pid ${proxy.pid} is not live: commands attached with its HTTPS_PROXY lose all HTTPS egress\n      log: ${proxyLog}` });
+    }
+    // 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;
+    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 = { ...admittedEnv(stripEnvOf(instance.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 {
+                    await 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}` : stoppedServiceReport(service.pid, service.log),
+        });
+        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 });
+            // A port that accepts is not a service that answers (a stuck event loop still completes the handshake): the
+            // readiness probe the service declared is run again, as it was at boot.
+            // A log pattern matched at boot matches forever, so it cannot tell a hung service: only a probe that asks is re-run,
+            // in the service's own cwd and with its PORT, as at boot.
+            const configured = externalProbeConfig?.services.find((candidate) => candidate.id === service.id);
+            const declared = configured?.ready;
+            if (pidLive && declared && declared !== 'tcp' && declared.stdoutMatch === undefined) {
+                const probe = await probeExternalOnce(resolveReadyProbe(declared, { host: '127.0.0.1', port: service.port, url: service.url }), configured?.cwd ? resolve(root, configured.cwd) : root, { ...admittedEnv(stripEnvOf(instance.env ?? {})), ...(instance.env ?? {}), ...(configured?.env ?? {}), PORT: String(service.port) }, service.log);
+                checks.push({ id: `service:${service.id}:ready`, ok: probe.ok,
+                    message: probe.ok ? probe.message : `its port accepts but its declared readiness probe fails (${probe.message}): the service is up but not answering\n      log: ${service.log}` });
+            }
+        }
+        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 ? 'missing tunnel process'
+                    : tunnelLive ? `pid=${service.tunnel.pid}`
+                        : `tunnel pid ${service.tunnel.pid} is not live; its public URL no longer reaches the service${service.tunnel.log ? `\n      log: ${service.tunnel.log}` : ''}`,
+            });
+            checks.push({
+                id: `service:${service.id}:public-ready`,
+                ok: service.publicReady === true && (!service.tunnel || tunnelLive),
+                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, root = process.cwd()) {
+    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 } : {}),
+            },
+        ])),
+    };
+}
+/**
+ * The clean (unquoted) base URL(s) of a RUNNING world's services — the `volter-world url`
+ * surface. Resolved from the generated instance, so callers never shell-parse `world.env`
+ * (its values are single-quoted). One `{ id, url }` when `service` is named; every
+ * URL-bearing service otherwise ('external' services have no assigned URL — their endpoints
+ * are discovered env vars, so they are omitted from the list and refused by name).
+ */
+export function urlWorld(name, options = {}) {
+    const status = statusWorld(name, options.root ?? process.cwd());
+    if (!status.running) {
+        throw new Error(`World ${name} is not running; start it with: volter-world up ${status.config} --env-file <path> --name ${name}`);
+    }
+    if (options.service === undefined) {
+        return Object.values(status.services)
+            .filter((service) => service.url)
+            .map((service) => ({ id: service.id, url: service.url }));
+    }
+    const service = status.services[options.service];
+    if (!service) {
+        throw new Error(`World ${name} has no service "${options.service}"; it has: ${Object.keys(status.services).join(', ')}`);
+    }
+    if (!service.url) {
+        throw new Error(`Service "${options.service}" has no assigned URL (type '${service.type}' endpoints are discovered env vars) — read them with: volter-world env ${name} -- env`);
+    }
+    return [{ id: service.id, url: service.url }];
+}
+export async function runWorld(configId, command, options = {}) {
+    if (command.length === 0)
+        throw new Error('Missing command after --');
+    if (!options.keep)
+        return superviseWorldRun(configId, command, options);
+    return runWorldOwned(configId, command, options);
+}
+/** Internal task entry. The lifetime owner exists before admission/startup. Cancellation during
+ * boot is latched and handled after startup settles, so no abandoned startup can create a late
+ * service after teardown. Persistent --keep runs use the caller directly. */
+export async function runWorldOwned(configId, command, options, abort) {
+    if (abort?.aborted)
+        throw new Error('World run cancelled before admission');
+    const instance = await upWorld(configId, options, abort);
+    let outcome;
+    let failure;
+    let failed = false;
+    let retired = true;
+    try {
+        outcome = await runWithWorldEnvLogged(instance.name, command, instance.root, { abort, verbose: options.verbose });
+        instance.lastRun = outcome;
+        saveWorldInstance(instance);
+    }
+    catch (error) {
+        failure = error;
+        failed = true;
+        if (error instanceof CommandRetirementError) {
+            retired = false;
+            try {
+                retainWorldLifecycleForCleanup(instance.root, instance.name);
+            }
+            catch { /* the live holder and unfinished foreground record remain authoritative */ }
+        }
+    }
+    if (!options.keep && retired) {
+        try {
+            await finishTaskWorld(instance);
+        }
+        catch (error) {
+            if (failed)
+                throw new AggregateError([failure, error], `World execution and cleanup failed: ${String(failure)}; ${String(error)}`);
+            throw error;
+        }
+    }
+    if (failed)
+        throw failure;
+    return { instance, exitCode: outcome.exitCode, outcome: outcome };
+}
+async function finishTaskWorld(instance) {
+    let waiting = false;
+    let uncertainSince;
+    for (;;) {
+        try {
+            const result = await downWorld(instance.name, instance.root, { expectedCreatedAt: instance.createdAt });
+            if (result.externalErrors.length) {
+                const message = `World "${instance.name}" cleanup incomplete: ${result.externalErrors.join('; ')}. Reservation and diagnostics retained.`;
+                // The caller that would have read this on stderr may be gone; the lifecycle log keeps it.
+                try {
+                    recordWorldLifecycleEvent(instance.root, instance.name, message);
+                }
+                catch { /* the error still propagates */ }
+                throw new Error(message);
+            }
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof WorldConsumersActiveError))
+                throw error;
+            // Wait for attachments that are running; one that is only uncertain (a runner gone, another host) never
+            // resolves by waiting, so the task ends and names what `consumers retire` must settle.
+            const blocking = worldConsumers(instance.root, instance.name).consumers.filter((consumer) => consumer.state !== 'exited');
+            const onlyUncertain = blocking.length > 0 && !blocking.some((consumer) => consumer.state === 'active');
+            uncertainSince = onlyUncertain ? (uncertainSince ?? Date.now()) : undefined;
+            // Two minutes, not one look: an attachment whose heartbeat lapsed while the machine slept reads uncertain until
+            // its next beat.
+            if (uncertainSince !== undefined && Date.now() - uncertainSince >= 120_000) {
+                const message = `World "${instance.name}" cleanup waits on uncertain attachments (${blocking.map((consumer) => consumer.id).join(', ')}); settle them with \`volter-world consumers retire\`, then \`down\``;
+                try {
+                    recordWorldLifecycleEvent(instance.root, instance.name, message);
+                }
+                catch { /* the error still propagates */ }
+                throw new Error(message);
+            }
+            if (!waiting) {
+                recordWorldLifecycleEvent(instance.root, instance.name, 'task ended; cleanup waiting for registered attachments');
+                waiting = true;
+            }
+            await new Promise(resolve => setTimeout(resolve, CONSUMER_HEARTBEAT_MS));
+        }
+    }
+}
+export function listWorlds(root = process.cwd()) {
+    const base = worldBaseDir(resolve(root));
+    if (!existsSync(base))
+        return [];
+    return readdirSync(base, { withFileTypes: true })
+        // World names must start with an alphanumeric (assertSafeWorldName), which is exactly why
+        // the lock dir is dot-prefixed — so anything not world-NAMED is bookkeeping (`.locks`),
+        // never a world, and must not be listed as one.
+        .filter((entry) => entry.isDirectory() && /^[A-Za-z0-9]/.test(entry.name))
+        .map((entry) => {
+        try {
+            const status = statusWorld(entry.name, root, { light: true });
+            return { name: entry.name, running: status.running, degraded: status.degraded, config: status.config };
+        }
+        catch {
+            return { name: entry.name, running: false };
+        }
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function worldAttachedCommandEnv(name, root, verbose = false) {
+    const status = statusWorld(name, root);
+    const sealed = status.env.VOLTER_WORLD_MODE === 'sealed' || status.env[WORLD_NETWORK_POLICY_ENV] !== undefined;
+    const baseEnv = { ...admittedEnv(stripEnvOf(status.env)), ...status.env };
+    let proxyEnv = {};
+    try {
+        const proxy = ensureWorldProxy(name, root, [admittedEnv(stripEnvOf(status.env)), status.env]);
+        if (proxy?.url) {
+            proxyEnv = proxy.env;
+        }
+        else if (sealed)
+            throw new Error(`world "${name}" requires its network policy proxy: attachment proxy is unavailable; refusing to run the command`);
+    }
+    catch (error) {
+        if (error instanceof CaTrustError)
+            throw error;
+        if (sealed)
+            throw new Error(`world "${name}" requires its network policy proxy: attachment proxy failed; refusing to run the command (${error instanceof Error ? error.message : String(error)})`);
+        // Keep env-only redirect if the ambient proxy cannot start.
+    }
+    return { instance: status, env: { ...baseEnv, ...proxyEnv, VOLTER_WORLD: name,
+            VOLTER_TWIN_INJECT_QUIET: verbose ? '0' : baseEnv.VOLTER_TWIN_INJECT_QUIET ?? '1' } };
+}
+/** Runs the command in the world's env in the foreground and resolves to its exit code. The child is
+ *  awaited, not blocked on: a runtime that runs no synchronous child (the browser engine) still runs
+ *  this one, and the caller sees no difference — stdio is inherited either way. */
+export function runWithWorldEnv(name, command, root = process.cwd(), options = {}) {
+    if (command.length === 0)
+        throw new Error('Missing command after --');
+    const attached = worldAttachedCommandEnv(name, root, options.verbose);
+    return new Promise((resolveExit) => {
+        const child = spawn(command[0], command.slice(1), {
+            cwd: resolve(options.cwd ?? root),
+            env: attached.env,
+            stdio: 'inherit',
+        });
+        const forward = (signal) => { if (child.exitCode === null && child.signalCode === null)
+            child.kill(signal); };
+        process.on('SIGINT', forward);
+        process.on('SIGTERM', forward);
+        child.once('error', () => { offSignal('SIGINT', forward); offSignal('SIGTERM', forward); resolveExit(1); });
+        child.once('exit', (code, signal) => { offSignal('SIGINT', forward); offSignal('SIGTERM', forward); resolveExit(code ?? (signal ? 1 : 0)); });
+    });
+}
+/**
+ * The owner's explicit resolution of uncertain attachments (never automatic, never implied by age).
+ * A record is retired only when it belongs to this host and the running instance, its runner and
+ * its command are both gone (ESRCH), and no live process remains in the command's process group
+ * (`survivingOwnedGroups`, the lifecycle's own retirement evidence); anything else is kept with the
+ * reason, surviving members named by their group. Active consumers are never touched.
+ */
+export function retireWorldConsumers(name, root = process.cwd(), options = {}) {
+    assertSafeWorldName(name);
+    const resolvedRoot = resolve(root);
+    return withFileLock(instanceLockFile(resolvedRoot, name), () => {
+        const current = statusWorld(name, resolvedRoot);
+        const { consumers } = worldConsumers(resolvedRoot, name, current.createdAt);
+        const chosen = consumers.filter(c => c.state === 'uncertain' && (options.consumer === undefined || c.id === options.consumer));
+        if (options.consumer !== undefined && chosen.length === 0)
+            throw new Error(`World "${name}" has no uncertain consumer ${options.consumer}`);
+        const gone = (pid) => { try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (error) {
+            return error.code === 'ESRCH';
+        } };
+        return chosen.map((c) => {
+            const keep = (reason) => ({ id: c.id, owner: c.owner, retired: false, reason });
+            if (c.hostname !== osHostname())
+                return keep(`recorded on host ${c.hostname}; retire it there`);
+            if (c.instanceCreatedAt !== current.createdAt)
+                return keep('belongs to another instance of this World');
+            if (!gone(c.runnerPid))
+                return keep(`runner ${c.runnerPid} is still alive`);
+            if (c.consumerPid === undefined)
+                return keep('its command was never recorded as started, so its processes cannot be proven gone');
+            if (!gone(c.consumerPid))
+                return keep(`command ${c.consumerPid} is still alive`);
+            const surviving = survivingOwnedGroups([c.consumerPid]);
+            if (surviving.length)
+                return keep(`process group ${c.consumerPid} still has live members`);
+            removeConsumerRecord(resolvedRoot, name, c.id);
+            return { id: c.id, owner: c.owner, retired: true, reason: `runner ${c.runnerPid}, command ${c.consumerPid} and its process group are gone` };
+        });
+    });
+}
+export async function attachWorld(name, command, root = process.cwd(), options = {}) {
+    if (command.length === 0)
+        throw new Error('Missing command after --');
+    assertSafeWorldName(name);
+    const resolvedRoot = resolve(root);
+    checkedOwner(options.owner);
+    const attached = worldAttachedCommandEnv(name, resolvedRoot, options.verbose);
+    const record = withFileLock(instanceLockFile(resolvedRoot, name), () => {
+        if (existsSync(stoppingFile(resolvedRoot, name)) || existsSync(bootingFile(resolvedRoot, name))) {
+            throw new Error(`World "${name}" is changing lifecycle; retry after it finishes`);
+        }
+        const current = statusWorld(name, resolvedRoot);
+        if (!current.running || current.createdAt !== attached.instance.createdAt)
+            throw new Error(`World "${name}" is stopped or changed while attaching`);
+        // Attaching to a World whose services died is allowed (a command may not need them), but never silent.
+        for (const [id, state] of Object.entries(current.serviceStates)) {
+            if (state === 'running' || state === 'external')
+                continue;
+            const service = current.services[id];
+            const end = service?.log ? readServiceEnd(service.log) : undefined;
+            process.stderr.write(`World "${name}": service ${id} is not running${end ? `: it ${describeServiceEnd(end)}` : ''}${service?.log ? `\n  log: ${service.log}` : ''}\n`);
+        }
+        return createConsumer(resolvedRoot, name, current.createdAt, 'attach', options.owner ?? current.lifecycle?.owner ?? current.resources?.owner, { completionRequired: true });
+    });
+    let timer;
+    let retired = true;
+    try {
+        return await new Promise((done, reject) => {
+            const child = spawn(command[0], command.slice(1), { cwd: resolve(options.cwd ?? root), env: attached.env, stdio: 'inherit', detached: commandProcessGroup });
+            const lifetime = commandLifetime(child);
+            let failure;
+            record.consumerPid = child.pid;
+            try {
+                refreshConsumer(resolvedRoot, name, record);
+            }
+            catch (error) {
+                failure = error;
+                lifetime.cancel('SIGTERM');
+            }
+            timer = setInterval(() => {
+                try {
+                    refreshConsumer(resolvedRoot, name, record);
+                }
+                catch { /* the stale heartbeat reports uncertain; never implies permission to clean up */ }
+            }, CONSUMER_HEARTBEAT_MS);
+            timer.unref();
+            child.once('error', (error) => { failure = error; });
+            void lifetime.finish().then(({ code, signal }) => {
+                if (failure)
+                    reject(failure);
+                else
+                    done(signal || lifetime.forwarded ? signalExitCode(signal ?? lifetime.forwarded) : code ?? 1);
+            }, error => {
+                retired = false;
+                record.retirementUncertain = true;
+                try {
+                    refreshConsumer(resolvedRoot, name, record);
+                }
+                catch { /* pre-spawn completion requirement already retains uncertainty */ }
+                reject(error);
+            });
+        });
+    }
+    finally {
+        if (timer)
+            clearInterval(timer);
+        if (retired)
+            releaseConsumer(resolvedRoot, name, record);
+    }
+}
+function signalExitCode(signal) {
+    if (signal === null)
+        return 1;
+    return 128 + (osConstants.signals[signal] ?? 0);
+}
+/** `world run`'s foreground consumer: stream output to the terminal while retaining one current
+ * World-visible log, then return a structured outcome even when spawning fails or a signal kills
+ * the consumer. The record intentionally contains neither argv nor environment values. */
+async function runWithWorldEnvLogged(name, command, root, options = {}) {
+    const startedAt = new Date().toISOString();
+    const instance = statusWorld(name, root);
+    const log = join(instance.dirs.logs, 'foreground.log');
+    const running = { state: 'running', runnerPid: process.pid, startedAt, log };
+    writeTextAtomic(foregroundRunFile(instance.root, instance.name), `${JSON.stringify(running, null, 2)}\n`);
+    const logFd = openPrivateLog(log, 'w');
+    try {
+        writeSync(logFd, `World ${name}: foreground consumer started at ${startedAt}\n`);
+    }
+    catch (error) {
+        closeSync(logFd);
+        throw error;
+    }
+    const finish = (exitCode, signal, error) => {
+        const finishedAt = new Date().toISOString();
+        const detail = error ? `spawn error: ${error}` : signal ? `terminated by ${signal}` : `exited ${exitCode}`;
+        try {
+            writeSync(logFd, `\nWorld ${name}: foreground consumer ${detail} at ${finishedAt}\n`);
+        }
+        finally {
+            closeSync(logFd);
+        }
+        const outcome = {
+            state: 'completed',
+            runnerPid: process.pid,
+            startedAt,
+            finishedAt,
+            exitCode,
+            log,
+            ...(signal ? { signal } : {}),
+            ...(error ? { error } : {}),
+        };
+        writeTextAtomic(foregroundRunFile(instance.root, instance.name), `${JSON.stringify(outcome, null, 2)}\n`);
+        return outcome;
+    };
+    if (options.abort?.aborted) {
+        const signal = options.abort.reason === 'SIGINT' ? 'SIGINT' : 'SIGTERM';
+        return finish(signalExitCode(signal), signal);
+    }
+    let attached;
+    try {
+        attached = worldAttachedCommandEnv(name, root, options.verbose);
+    }
+    catch (cause) {
+        return finish(1, undefined, cause instanceof Error ? cause.message : String(cause));
+    }
+    return await new Promise((resolveOutcome, rejectOutcome) => {
+        let spawnError;
+        let child;
+        try {
+            child = spawn(command[0], command.slice(1), {
+                cwd: resolve(options.cwd ?? root),
+                env: attached.env,
+                stdio: ['inherit', 'pipe', 'pipe'],
+                detached: commandProcessGroup,
+            });
+        }
+        catch (cause) {
+            resolveOutcome(finish(1, undefined, cause instanceof Error ? cause.message : String(cause)));
+            return;
+        }
+        const lifetime = commandLifetime(child, options.abort);
+        child.stdout.on('data', (chunk) => {
+            try {
+                process.stdout.write(chunk);
+                writeSync(logFd, chunk);
+            }
+            catch (error) {
+                spawnError = String(error);
+                lifetime.cancel('SIGTERM');
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            try {
+                process.stderr.write(chunk);
+                writeSync(logFd, chunk);
+            }
+            catch (error) {
+                spawnError = String(error);
+                lifetime.cancel('SIGTERM');
+            }
+        });
+        child.once('error', (cause) => {
+            spawnError = cause.message;
+        });
+        const activeRecord = {
+            state: 'running',
+            runnerPid: process.pid,
+            ...(child.pid ? { consumerPid: child.pid } : {}),
+            startedAt,
+            log,
+        };
+        try {
+            writeTextAtomic(foregroundRunFile(instance.root, instance.name), `${JSON.stringify(activeRecord, null, 2)}\n`);
+        }
+        catch (error) {
+            spawnError = String(error);
+            lifetime.cancel('SIGTERM');
+        }
+        void lifetime.finish().then(({ code, signal }) => {
+            const effectiveSignal = signal ?? lifetime.forwarded;
+            const exitCode = effectiveSignal ? signalExitCode(effectiveSignal) : (code ?? 1);
+            try {
+                resolveOutcome(finish(spawnError ? 1 : exitCode, effectiveSignal, spawnError));
+            }
+            catch (error) {
+                rejectOutcome(error);
+            }
+        }, error => { closeSync(logFd); rejectOutcome(error); });
+    });
+}
+/** 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, root = process.cwd()) {
+    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: status.env.SHELL || admittedEnv(stripEnvOf(status.env)).SHELL || '/bin/bash',
+        cwd: resolve(root),
+        env: { ...admittedEnv(stripEnvOf(status.env)), ...status.env, VOLTER_WORLD: name },
+    };
+}
+/** 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/guides/route-a-cli-through-the-world.md. */
+export async function shellWorld(name, root = process.cwd()) {
+    const { shell, cwd, env } = worldShellEnv(name, root);
+    const resolvedRoot = resolve(root);
+    let proxy = null;
+    const sealed = env.VOLTER_WORLD_MODE === 'sealed' || env[WORLD_NETWORK_POLICY_ENV] !== undefined;
+    if (opensslAvailable()) {
+        try {
+            proxy = await startRedirectProxy({ env, trustEnv: [admittedEnv(stripEnvOf(env)), 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) {
+            if (error instanceof CaTrustError)
+                throw error;
+            if (sealed)
+                throw new Error(`world "${name}" requires its network policy proxy: attachment proxy failed; refusing to open a shell (${error instanceof Error ? error.message : String(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 {
+        if (sealed)
+            throw new Error(`world "${name}" requires its network policy proxy: openssl is unavailable; refusing to open a shell`);
+        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() {
+    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, root = process.cwd(), caller = process.env) {
+    assertSafeWorldName(name);
+    const resolvedRoot = resolve(root);
+    return withFileLock(instanceLockFile(resolvedRoot, name), () => {
+        assertProxyOwnershipResolved(resolvedRoot, name);
+        if (liveBootingClaim(stoppingFile(resolvedRoot, name)))
+            throw new Error(`World "${name}" is being stopped`);
+        if (liveBootingClaim(bootingFile(resolvedRoot, name)))
+            throw new Error(`World "${name}" is being booted`);
+        if (!statusWorld(name, resolvedRoot, { readOnly: true }).running)
+            throw new Error(`World "${name}" is not running`);
+        return ensureWorldProxyUnlocked(name, resolvedRoot, caller);
+    });
+}
+/** The World's live proxy daemon, or null. One from before its guests' listener (its state names none) keeps a World
+ *  Machine on its host's network, so it is stopped (its CA kept, which the next daemon reuses) and a new one started. */
+function currentProxyState(root, name) {
+    const existing = readProxyState(root, name);
+    if (!existing || !isAlive(existing.pid))
+        return null;
+    if (existing.guestUrl)
+        return existing;
+    try {
+        process.kill(existing.pid, 'SIGTERM');
+    }
+    catch { /* gone already */ }
+    for (let i = 0; i < 50 && isAlive(existing.pid); i += 1)
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    try {
+        rmSync(proxyStateFile(root, name), { force: true });
+    }
+    catch { /* ignore */ }
+    return null;
+}
+function ensureWorldProxyUnlocked(name, root, caller) {
+    const resolvedRoot = resolve(root);
+    if (!opensslAvailable())
+        return null;
+    const existing = currentProxyState(resolvedRoot, name);
+    if (existing && isAlive(existing.pid)) {
+        return { url: existing.url, caCertPath: existing.caCertPath, env: proxyEnvFor(existing.url, existing.caCertPath, caller, existing.guestUrl) };
+    }
+    // Pre-create the CA synchronously so we can return its path immediately; the daemon reuses it.
+    const ca = ensureCa(tlsDir(resolvedRoot, name));
+    return startProxyDaemonOwned(name, resolvedRoot, ca.caCert, undefined, undefined, caller);
+}
+function ensureWorldProxyFromEnv(name, root, env, boot) {
+    const resolvedRoot = resolve(root);
+    if (!opensslAvailable())
+        return null;
+    writeProxyEnv(resolvedRoot, name, env);
+    const existing = currentProxyState(resolvedRoot, name);
+    if (existing && isAlive(existing.pid)) {
+        return { url: existing.url, caCertPath: existing.caCertPath, env: proxyEnvFor(existing.url, existing.caCertPath, [admittedEnv(stripEnvOf(env)), env], existing.guestUrl) };
+    }
+    const ca = ensureCa(tlsDir(resolvedRoot, name));
+    return startProxyDaemonOwned(name, resolvedRoot, ca.caCert, proxyEnvFile(resolvedRoot, name), boot, [admittedEnv(stripEnvOf(env)), env]);
+}
+function startProxyDaemonOwned(name, root, caCertPath, envFile, boot, caller = process.env) {
+    sessionTrustEnv(caCertPath, caller); // Fail in the parent before an invalid trust input can become a daemon timeout.
+    const marker = proxyStartingFile(root, name);
+    // Write ahead of spawn: even permanently failed PID publication must leave durable evidence.
+    // The instance lock (activate) or boot claim excludes a competing startup or teardown.
+    const createdAt = readWorldInstance(name, root, true).createdAt;
+    const markerFd = openSync(marker, 'wx', 0o600); // EEXIST must never remove another intent
+    try {
+        try {
+            writeFileSync(markerFd, JSON.stringify({ token: randomUUID(), ownerPid: process.pid, createdAt }));
+        }
+        finally {
+            closeSync(markerFd);
+        }
+    }
+    catch (error) {
+        rmSync(marker, { force: true }); // partial pre-spawn writes own no child
+        throw error;
+    }
+    let child;
+    try {
+        retainWorldLifecycleForCleanup(root, name);
+        // Its own log (a startup error, a crash, the refusals it answers): with no output the daemon's failures left nothing.
+        mkdirSync(dirname(proxyLogPath(root, name)), { recursive: true, mode: 0o700 });
+        const proxyOut = openPrivateLog(proxyLogPath(root, name), 'a');
+        try {
+            child = spawn(process.execPath, [proxyDaemonEntry(), name, '--root', root, ...(envFile ? [`--env-file=${envFile}`] : [])], {
+                cwd: root, env: process.env, detached: true, stdio: ['ignore', proxyOut, proxyOut],
+            });
+        }
+        finally {
+            closeSync(proxyOut);
+        }
+    }
+    catch (error) {
+        rmSync(marker, { force: true }); // no child was returned by spawn
+        throw error;
+    }
+    child.on('error', () => { }); // a failed spawn can emit after this synchronous operation throws
+    const pid = child.pid;
+    if (!pid || !Number.isInteger(pid) || pid <= 0) {
+        rmSync(marker, { force: true });
+        throw new Error(`World "${name}": ambient proxy process did not start`);
+    }
+    boot?.pids.add(pid); // before any fallible filesystem operation
+    child.unref();
+    let retirementAttempted = false;
+    const retire = () => {
+        retirementAttempted = true;
+        signalPids([pid], 'SIGTERM');
+        killSurvivorsAfterGraceSync([pid], DOWN_GRACE_MS_DEFAULT);
+        if (undeadPids([pid]).length) {
+            const error = new CommandRetirementError(`World "${name}": proxy process ${pid} retirement is unconfirmed; ownership retained`);
+            try {
+                retainWorldLifecycleForCleanup(root, name);
+            }
+            catch (cause) {
+                error.message += `; claim update failed: ${String(cause)}`;
+            }
+            throw error;
+        }
+        // Publication can happen during the grace period. Erase only this retired child's state.
+        if (readProxyState(root, name)?.pid === pid)
+            rmSync(proxyStateFile(root, name), { force: true });
+        rmSync(marker, { force: true });
+    };
+    try {
+        if (boot)
+            boot.recordPids();
+        else
+            writeOwnedPids(root, name, [pid], [pid]);
+        rmSync(marker, { force: true }); // canonical ownership is now durable
+        const deadlineMs = proxyDaemonDeadlineMs();
+        const deadline = Date.now() + deadlineMs;
+        while (Date.now() < deadline) {
+            const state = readProxyState(root, name);
+            if (state?.pid === pid) {
+                if (!boot)
+                    handoffWorldLifecycle(root, name, readPids(join(instanceDir(root, name), 'pids')));
+                return { url: state.url, caCertPath: state.caCertPath, env: proxyEnvFor(state.url, state.caCertPath, caller, state.guestUrl) };
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+        }
+        retire();
+        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, env: {} };
+    }
+    catch (error) {
+        if (!retirementAttempted)
+            retire();
+        throw error;
+    }
+}
+function isAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function proxyDaemonEntry() {
+    return siblingScript(import.meta.url, 'proxy-daemon');
+}
+/** 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, root = process.cwd(), envFile) {
+    const resolvedRoot = resolve(root);
+    const envLoader = envFile
+        ? () => { const saved = readProxyEnv(envFile); return { ...admittedEnv(stripEnvOf(saved)), ...saved }; }
+        : undefined;
+    let env;
+    if (!envLoader) {
+        const status = statusWorld(name, resolvedRoot);
+        if (!status.running)
+            throw new Error(`World "${name}" is not running`);
+        env = { ...admittedEnv(stripEnvOf(status.env)), ...status.env };
+    }
+    const proxy = await startRedirectProxy({ env, envLoader, tlsDir: tlsDir(resolvedRoot, name), note: (line) => process.stderr.write(`${line}\n`) });
+    const state = { pid: process.pid, url: proxy.url, caCertPath: proxy.caCertPath, guestUrl: proxy.guestUrl };
+    writeFileSync(proxyStateFile(resolvedRoot, name), JSON.stringify(state));
+    // Not a recorded service, so it records its own start and end in the World's events (a crash included; a SIGKILL
+    // leaves none, which doctor's proxy check then names).
+    const events = worldEventsPath(join(instanceDir(resolvedRoot, name), 'logs'));
+    const event = (entry) => { try {
+        appendFileSync(events, `${JSON.stringify({ ...entry, service: 'proxy', pid: process.pid, at: new Date().toISOString() })}\n`, { mode: 0o600 });
+    }
+    catch { /* no events file to write */ } };
+    event({ event: 'world.service.started' });
+    const proxyStarted = Date.now();
+    process.on('uncaughtException', (error) => { process.stderr.write(`${new Date().toISOString()} proxy daemon crashed: ${error.stack ?? error}\n`); process.exitCode = 1; process.exit(1); });
+    process.on('exit', (code) => event({ event: 'world.service.exited', status: code, code, signal: null, uptimeMs: Date.now() - proxyStarted }));
+    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, name) {
+    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/guides/route-a-cli-through-the-world.md.
+ */
+export function activateScript(name, root = process.cwd()) {
+    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 = { ...baseEnv };
+    const sealed = baseEnv.VOLTER_WORLD_MODE === 'sealed' || baseEnv[WORLD_NETWORK_POLICY_ENV] !== undefined;
+    try {
+        const proxy = ensureWorldProxy(name, root, [admittedEnv(stripEnvOf(baseEnv)), baseEnv]);
+        if (proxy && proxy.url) {
+            env = { ...baseEnv, ...proxy.env };
+            proxyNote = ` (ambient proxy ${proxy.url})`;
+        }
+        else if (sealed)
+            throw new Error('attachment proxy is unavailable');
+    }
+    catch (error) {
+        if (error instanceof CaTrustError)
+            throw error;
+        if (sealed)
+            throw new Error(`world "${name}" requires its network policy proxy: attachment proxy failed; refusing activation (${error instanceof Error ? error.message : String(error)})`);
+        // openssl missing or daemon failed — keep env-only redirect; never fabricate proxy success.
+    }
+    const keys = Object.keys(env).sort();
+    const lines = [
+        `# 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`;
+}