@volter/world-runtime 3.0.38 → 3.0.39

package/dist/src/guest-runner.js

@@ -0,0 +1,567 @@
+// Substrate-backed light guests; architecture, "Other wires: … machines". Imports start nothing.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { accessSync, constants, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync } from 'node:fs';
+import { dirname, basename, join, resolve, posix, delimiter } from 'node:path';
+import { RemoteRuntime } from '@volter/browser-sandboxes';
+import { allocatePort } from "./tcp-port.js";
+import { ownedPath, assertOwnedRealPath } from "./owned-path.js";
+import { commandLifetime, commandProcessGroup } from "./command-lifetime.js";
+import { beginGuestProcess, retainGuestProcess, readGuestProcesses, releaseGuestProcesses } from './guest-processes.mjs';
+import { retireOwnedProcessGroups } from "./runtime.js";
+import { guestControl } from './guest-control.mjs';
+import { admitGuestArgv, guestCommandGap, guestEnvironment } from './guest-command.mjs';
+const delay = (ms) => new Promise(r => setTimeout(r, ms));
+// Re-enrolling image metadata must not lose ownership of guests already running in this World.
+const pools = new Map();
+const lifecycle = new Map();
+/** Word splitting for the supported Dockerfile instructions; no shell is executed while parsing. */
+function words(text) {
+    const out = [];
+    let word = '', quote = '', active = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '\\' && quote !== "'") {
+            word += text[++i] ?? '';
+            active = true;
+        }
+        else if (quote) {
+            if (ch === quote)
+                quote = '';
+            else
+                word += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            active = true;
+        }
+        else if (/\s/.test(ch)) {
+            if (active) {
+                out.push(word);
+                word = '';
+                active = false;
+            }
+        }
+        else {
+            word += ch;
+            active = true;
+        }
+    }
+    if (quote)
+        throw new Error('unsupported unterminated Dockerfile quote');
+    if (active)
+        out.push(word);
+    return out;
+}
+function command(text) {
+    if (!text.trim().startsWith('['))
+        throw guestCommandGap('guest shell-form CMD/ENTRYPOINT is unsupported; use Node argv with an image entry file');
+    const value = JSON.parse(text);
+    if (!Array.isArray(value) || !value.every(v => typeof v === 'string'))
+        throw new Error('invalid Dockerfile exec form');
+    return value;
+}
+function plan(image) {
+    const out = { runtime: image.runtime ?? '', cwd: '/', env: {}, command: [], ports: [], copies: [] };
+    let entry = [], cmd = [], stages = 0;
+    const path = resolve(image.context, image.dockerfile ?? 'Dockerfile');
+    if (image.dockerfile || existsSync(path)) {
+        for (const line of readFileSync(path, 'utf8').replace(/\\\r?\n/g, ' ').split(/\r?\n/)) {
+            if (!line.trim() || line.trimStart().startsWith('#'))
+                continue;
+            const hit = /^\s*(\w+)\s+(.+)$/.exec(line);
+            if (!hit)
+                throw new Error(`unsupported Dockerfile line: ${line}`);
+            const op = hit[1].toUpperCase(), body = hit[2];
+            const expand = (s) => s.replace(/\$\{(\w+)\}|\$(\w+)/g, (_, a, b) => out.env[a ?? b] ?? '');
+            switch (op) {
+                case 'FROM': {
+                    if (++stages > 1)
+                        throw new Error('light guests cannot build multi-stage images; enroll a prepared context and command');
+                    const base = words(body)[0] ?? '';
+                    const inferred = /(?:^|\/)(node|bun|python|deno)(?=[:@/]|$)/.exec(base)?.[1];
+                    out.runtime ||= inferred ?? '';
+                    if (!out.runtime)
+                        throw guestCommandGap(`unsupported guest runtime in base image ${base}`);
+                    break;
+                }
+                case 'WORKDIR':
+                    out.cwd = posix.resolve(out.cwd, expand(body));
+                    break;
+                case 'ENV': {
+                    const values = words(body);
+                    if (!values[0]?.includes('='))
+                        out.env[values.shift() ?? ''] = expand(values.join(' '));
+                    else
+                        for (const value of values) {
+                            const n = value.indexOf('=');
+                            if (n < 1)
+                                throw new Error('invalid ENV');
+                            out.env[value.slice(0, n)] = expand(value.slice(n + 1));
+                        }
+                    break;
+                }
+                case 'EXPOSE':
+                    for (const value of words(body)) {
+                        if (value.endsWith('/udp'))
+                            throw new Error('light guests support TCP only');
+                        out.ports.push(Number(value.split('/')[0]));
+                    }
+                    break;
+                case 'CMD':
+                    cmd = command(body);
+                    break;
+                case 'ENTRYPOINT':
+                    entry = command(body);
+                    break;
+                case 'COPY': {
+                    const values = body.trim().startsWith('[') ? command(body) : words(body);
+                    if (values.some(v => v.startsWith('--') || /[*?]/.test(v)))
+                        throw new Error('unsupported COPY flag, stage or glob');
+                    const destination = expand(values.pop() ?? '');
+                    if (!values.length || !destination)
+                        throw new Error('invalid COPY');
+                    out.copies.push({ sources: values.map(expand), destination, cwd: out.cwd });
+                    break;
+                }
+                case 'RUN':
+                    if (/\b(apt|apt-get|apk|yum|dnf|pacman|brew|curl|wget)\b/.test(body) || !/^(npm|pnpm|yarn|bun|pip|pip3|python|python3)\b/.test(body.trim()))
+                        throw new Error(`unsupported OS/build step: RUN ${body}`);
+                    if (!image.prepared)
+                        throw new Error(`RUN needs a prepared context: ${body}`);
+                    break;
+                case 'LABEL': break;
+                default: throw new Error(`unsupported Dockerfile instruction ${op}`);
+            }
+        }
+    }
+    out.runtime = image.runtime ?? out.runtime;
+    if (out.runtime !== 'node')
+        throw guestCommandGap(`unsupported guest runtime ${out.runtime || '(unknown)'}`);
+    out.command = image.command ?? [...entry, ...cmd];
+    out.cwd = image.cwd ?? out.cwd;
+    out.env = { ...out.env, ...image.env };
+    return out;
+}
+function guestPath(dir, path, cwd = '/') {
+    // Reject traversal rather than let a normalization hide it. This is path hygiene, not isolation.
+    if (path.split('/').includes('..'))
+        throw new Error('guest path traversal is unsupported');
+    const target = join(dir, posix.resolve(cwd, path));
+    let existing = target;
+    while (!existsSync(existing) && existing !== dir)
+        existing = dirname(existing);
+    assertOwnedRealPath(realpathSync(dir), existing);
+    return target;
+}
+function copy(source, destination) {
+    mkdirSync(dirname(destination), { recursive: true });
+    cpSync(source, destination, { recursive: true, dereference: true, filter: path => !['.git', '.volter'].includes(basename(path)) });
+}
+function prepare(dir, image, p) {
+    mkdirSync(dir, { recursive: true });
+    const context = realpathSync(image.context);
+    if (p.copies.length)
+        for (const item of p.copies) {
+            mkdirSync(guestPath(dir, item.cwd), { recursive: true });
+            const destination = guestPath(dir, item.destination, item.cwd);
+            const directory = item.sources.length > 1 || item.destination.endsWith('/') || (existsSync(destination) && statSync(destination).isDirectory());
+            if (directory)
+                mkdirSync(destination, { recursive: true });
+            for (const source of item.sources) {
+                const from = realpathSync(resolve(context, source));
+                assertOwnedRealPath(context, from);
+                copy(from, directory && !statSync(from).isDirectory() ? join(destination, basename(source)) : destination);
+            }
+        }
+    else {
+        const target = guestPath(dir, p.cwd);
+        mkdirSync(target, { recursive: true });
+        for (const entry of readdirSync(context)) {
+            if (['.git', '.volter', 'node_modules'].includes(entry))
+                continue;
+            copy(join(context, entry), join(target, entry));
+        }
+        if (existsSync(join(context, 'node_modules')) && !existsSync(join(target, 'node_modules')))
+            symlinkSync(join(context, 'node_modules'), join(target, 'node_modules'));
+    }
+    mkdirSync(guestPath(dir, p.cwd), { recursive: true });
+}
+function worldEnv() {
+    const instancePath = process.env.VOLTER_WORLD_INSTANCE;
+    if (!instancePath)
+        throw new Error('guest execution requires a World instance');
+    const instance = JSON.parse(readFileSync(instancePath, 'utf8'));
+    // proxy-env has the completed vendor map; the early twin process env may not.
+    const current = JSON.parse(readFileSync(join(dirname(instancePath), 'proxy-env.json'), 'utf8'));
+    const env = { ...instance.env, ...current };
+    if (!env.VOLTER_WORLD || !env.NODE_OPTIONS)
+        throw new Error('World guest injection environment is incomplete');
+    return env;
+}
+function injected(base, deploy, dir) {
+    const env = { PATH: process.env.PATH, ...guestEnvironment(deploy) };
+    // Admission already happened at World boot; never inherit the twin process's ambient secrets.
+    for (const [key, value] of Object.entries(base)) {
+        if (/^(VOLTER_|TWIN_|NODE_OPTIONS$|NODE_EXTRA_CA_CERTS$|.*_TWIN_URL$|HTTPS?_PROXY$|https?_proxy$|NO_PROXY$|no_proxy$|SSL_CERT_FILE$|REQUESTS_CA_BUNDLE$)/.test(key))
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(env)) {
+        if (value?.startsWith('/') && !/^(PATH|NODE_|VOLTER_|TWIN_|SSL_|REQUESTS_)/.test(key))
+            env[key] = join(dir, value);
+    }
+    if (!base.VOLTER_WORLD_GUEST_PROXY)
+        throw new Error('World guest proxy is missing');
+    for (const key of ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy', 'VOLTER_WORLD_PROXY'])
+        env[key] = base.VOLTER_WORLD_GUEST_PROXY;
+    env.NO_PROXY = env.no_proxy = '';
+    env.HOME = join(dir, 'home/user');
+    mkdirSync(env.HOME, { recursive: true });
+    return env;
+}
+// Resolve only the runtime's operator PATH, once; deployment/exec PATH is never consulted.
+let nodeExecutable;
+function trustedNodeExecutable() {
+    if (nodeExecutable)
+        return nodeExecutable;
+    if (!process.versions.bun)
+        return nodeExecutable = realpathSync(process.execPath);
+    for (const folder of (process.env.PATH ?? '').split(delimiter)) {
+        if (!folder.startsWith('/'))
+            continue;
+        const candidate = resolve(folder, process.platform === 'win32' ? 'node.exe' : 'node');
+        try {
+            accessSync(candidate, constants.X_OK);
+            if (statSync(candidate).isFile())
+                return nodeExecutable = realpathSync(candidate);
+        }
+        catch { /* next operator PATH entry */ }
+    }
+    throw new Error('trusted Node executable unavailable in runtime operator PATH');
+}
+let messageId = 0;
+function ask(child, action, path, signal) {
+    return guestControl(control => new Promise((yes, no) => {
+        if (!child.connected) {
+            no(new Error('Substrate guest control disconnected'));
+            return;
+        }
+        const id = ++messageId;
+        const cleanup = () => { child.off('message', reply); child.off('exit', ended); child.off('disconnect', ended); child.off('error', failed); control.removeEventListener('abort', aborted); };
+        const failed = (error) => { cleanup(); no(error); };
+        const aborted = () => failed(control.reason);
+        const ended = () => failed(new Error('Substrate guest exited during control request'));
+        const reply = (message) => { if (message.id !== id)
+            return; cleanup(); message.error ? no(new Error(message.error)) : yes(message.value); };
+        child.on('message', reply);
+        child.once('exit', ended);
+        child.once('disconnect', ended);
+        child.once('error', failed);
+        control.addEventListener('abort', aborted, { once: true });
+        child.send({ id, action, path }, error => { if (error)
+            failed(error); });
+    }), `guest ${action}`, signal);
+}
+async function startAdmitted(g, args, options, signal) {
+    const cwd = options?.cwd ?? g.cwd;
+    const mapped = [...args];
+    if (mapped[1]?.startsWith('/'))
+        mapped[1] = guestPath(g.dir, mapped[1]);
+    const admitted = admitGuestArgv(mapped, g.imageRuntime, g.dir, guestPath(g.dir, cwd));
+    const key = await ask(g.child, 'prepare', JSON.stringify(admitted.argv), signal);
+    const handle = await guestControl(() => g.runtime.start(`__world_node_argv ${key}`, options), 'guest start transport', signal);
+    void handle.result.catch(() => { }); // observe a failure even if admission refuses first
+    try {
+        await ask(g.child, 'admission', key, signal);
+    } // valid held birth has been durably published
+    catch (error) {
+        handle.kill();
+        throw error;
+    }
+    return handle;
+}
+/** Local provider for Substrate's sandbox contract; all guest operations are vendor-neutral. */
+export function createLightGuestPool(options) {
+    const instancePath = process.env.VOLTER_WORLD_INSTANCE;
+    if (!instancePath)
+        throw new Error('guest pool requires a World instance');
+    const instanceDir = dirname(instancePath), instance = JSON.parse(readFileSync(instancePath, 'utf8'));
+    const receiptsDir = ownedPath(instanceDir, 'guest-processes');
+    const receiptGuest = (name) => `${options.world}/${name}`;
+    const receipts = (name) => readGuestProcesses(instanceDir, instance.instance).filter(r => r.record.guest === receiptGuest(name));
+    const data = options.root ?? join(dirname(process.env.VOLTER_WORLD_INSTANCE ?? ''), 'data');
+    const root = ownedPath(data, `guests/${options.world}`);
+    const guests = pools.get(root) ?? new Map();
+    const states = lifecycle.get(root) ?? new Map();
+    pools.set(root, guests);
+    lifecycle.set(root, states);
+    const update = (g, status) => { g.status = status; states.set(g.name, status); };
+    const live = (name) => {
+        const g = guests.get(name);
+        if (!g || g.status.state !== 'started' || g.child.exitCode !== null || g.child.signalCode !== null)
+            throw new Error(g?.status.reason ?? `Substrate guest is ${g?.status.state ?? 'missing'}`);
+        return g;
+    };
+    const stop = async (name) => {
+        const g = guests.get(name);
+        if (!g)
+            return;
+        const terminal = g.status.state === 'exited' || g.status.state === 'failed' ? g.status : undefined;
+        g.stopping = true;
+        g.runtime.close();
+        // cancel resumes the agent's private group. Its retained Substrate handles retire commands;
+        // durable command groups use the same World grace/KILL/confirmation, even after agent loss.
+        g.lifetime.cancel('SIGCONT');
+        g.lifetime.cancel('SIGTERM');
+        try {
+            const outcomes = await Promise.allSettled([
+                g.lifetime.finish(),
+                retireOwnedProcessGroups(receipts(name).filter(r => r.record.kind !== 'agent').map(r => r.record)),
+            ]);
+            for (const outcome of outcomes)
+                if (outcome.status === 'rejected')
+                    throw outcome.reason;
+            const remaining = receipts(name);
+            await retireOwnedProcessGroups(remaining.map(r => r.record));
+            releaseGuestProcesses(remaining);
+        }
+        catch (error) {
+            update(g, { state: 'failed', reason: `guest retirement unconfirmed; ownership retained: ${error}` });
+            throw error;
+        }
+        update(g, terminal ?? { state: 'stopped' });
+        guests.delete(name);
+        if (g.resetOnStop)
+            rmSync(ownedPath(data, `guests/${options.world}/${name}`), { recursive: true, force: true });
+    };
+    const provider = {
+        pauseMode: 'freeze-processes',
+        async start({ id }) { const g = guests.get(id); if (!g)
+            throw new Error('Substrate guest launch was not prepared'); return { name: id, url: `http://127.0.0.1:${g.agentPort}` }; },
+        async pause({ name }) { const g = live(name); await ask(g.child, 'pause'); update(g, { state: 'paused' }); },
+        async resume({ name }) { const g = guests.get(name); if (!g || g.status.state !== 'paused')
+            throw new Error('Substrate guest cannot resume'); await ask(g.child, 'resume'); update(g, { state: 'started' }); },
+        async stop({ name }) { await stop(name); },
+        running() { return new Set([...guests].filter(([, g]) => g.status.state === 'started').map(([name]) => name)); },
+    };
+    return {
+        kind: 'light',
+        async admitRun(spec) {
+            if (!/^[a-zA-Z0-9_-]+$/.test(spec.name))
+                throw new Error('invalid guest name');
+            const image = options.images?.[spec.image];
+            if (!image)
+                throw new Error(`image ${spec.image} has no light guest context`);
+            const p = plan(image), dir = ownedPath(data, `guests/${options.world}/${spec.name}`);
+            prepare(dir, image, p);
+            const args = [...(spec.command ?? p.command)];
+            if (args[1]?.startsWith('/'))
+                args[1] = guestPath(dir, args[1]);
+            if (args.length)
+                admitGuestArgv(args, p.runtime, dir, guestPath(dir, p.cwd));
+        },
+        async status(name) {
+            const g = guests.get(name);
+            if (g?.status.state === 'started' && g.launch && g.launch.state !== 'running')
+                await g.launch.result.catch(() => { });
+            return states.get(name) ?? { state: 'failed', reason: 'Substrate guest is missing' };
+        },
+        async ports(name) { return live(name).runtime.ports(); },
+        async files(name) {
+            const g = live(name);
+            return {
+                read: path => { live(name); return g.runtime.files.read(path); },
+                write: (path, bytes) => { live(name); return g.runtime.files.write(path, bytes); },
+                list: path => { live(name); return g.runtime.files.list(path); },
+                mkdir: path => { live(name); return g.runtime.files.mkdir(path); },
+                remove: path => { live(name); return g.runtime.files.remove(path); },
+                stat: path => { live(name); return ask(g.child, 'stat', path); },
+            };
+        },
+        async run(spec) {
+            if (!/^[a-zA-Z0-9_-]+$/.test(spec.name))
+                throw new Error('invalid guest name');
+            if (guests.has(spec.name))
+                throw new Error('guest already exists; stop before starting again');
+            let starting = true;
+            if (!Number.isSafeInteger(spec.startTimeoutMs) || spec.startTimeoutMs <= 0)
+                throw new Error('light guest requires a vendor startup observation budget');
+            const startup = new AbortController();
+            const timeoutReason = new Error(`guest startup exceeded ${spec.startTimeoutMs} ms before declared readiness`);
+            const deadline = setTimeout(() => startup.abort(timeoutReason), spec.startTimeoutMs);
+            spec = { ...spec, signal: spec.signal ? AbortSignal.any([spec.signal, startup.signal]) : startup.signal };
+            try {
+                spec.signal?.throwIfAborted();
+                const image = options.images?.[spec.image];
+                if (!image)
+                    throw new Error(`image ${spec.image} has no light guest context`);
+                const p = plan(image), dir = ownedPath(data, `guests/${options.world}/${spec.name}`);
+                const base = worldEnv(), deploy = { ...p.env, ...spec.env }, env = injected(base, deploy, dir);
+                const args = spec.command ?? p.command;
+                prepare(dir, image, p);
+                if (args.length) {
+                    const mapped = [...args];
+                    if (mapped[1]?.startsWith('/'))
+                        mapped[1] = guestPath(dir, mapped[1]);
+                    admitGuestArgv(mapped, p.runtime, dir, guestPath(dir, p.cwd));
+                }
+                for (const mount of spec.mounts ?? []) {
+                    if (!/^[a-zA-Z0-9_-]+$/.test(mount.name) || mount.path === '/')
+                        throw new Error('unsupported guest mount');
+                    const volume = ownedPath(data, `guests/${options.world}-volumes/${mount.name}`);
+                    const target = guestPath(dir, mount.path);
+                    mkdirSync(volume, { recursive: true });
+                    rmSync(target, { recursive: true, force: true });
+                    mkdirSync(dirname(target), { recursive: true });
+                    symlinkSync(volume, target);
+                }
+                if (!existsSync(join(dir, 'workspace')))
+                    mkdirSync(join(dir, 'workspace'), { recursive: true });
+                const ports = new Set([...(spec.ports ?? []), ...p.ports]);
+                for (const internal of ports)
+                    if (!Number.isInteger(internal) || internal < 1 || internal > 65535)
+                        throw new Error('invalid guest port');
+                if (ports.size && !args.length)
+                    throw new Error('image has a listening port but no start command');
+                const agentPort = await allocatePort(new Set(ports)), token = deploy.SUBSTRATE_TOKEN ?? randomBytes(24).toString('hex');
+                // Substrate's macOS socket discovery uses lsof, installed in /usr/sbin. This agent's
+                // infrastructure PATH is separate from the declared environment passed to the product.
+                const agentPath = process.platform === 'darwin' ? `${process.env.PATH ?? ''}:/usr/sbin` : process.env.PATH;
+                const receipt = beginGuestProcess(receiptsDir, instance.instance, receiptGuest(spec.name), 'agent');
+                // The agent's own control transport remains host-side; only product commands use guest policy.
+                const guestRouting = Object.fromEntries(Object.entries(env).filter(([key]) => /^(VOLTER_|TWIN_|NODE_OPTIONS$|NODE_EXTRA_CA_CERTS$|.*_TWIN_URL$|HTTPS?_PROXY$|https?_proxy$|NO_PROXY$|no_proxy$)/.test(key)));
+                const control = Object.fromEntries(Object.entries(base).filter(([key]) => /^(VOLTER_WORLD_PROXY$|HTTPS?_PROXY$|https?_proxy$|NO_PROXY$|no_proxy$)/.test(key)));
+                const child = spawn(trustedNodeExecutable(), [new URL('./guest-entry.mjs', import.meta.url).pathname], { detached: commandProcessGroup, env: { ...env, ...control, PATH: agentPath, SUBSTRATE_ROOT: dir, SUBSTRATE_GUEST_RUNTIME: p.runtime, SUBSTRATE_TOKEN: token, SUBSTRATE_AGENT_PORT: String(agentPort), SUBSTRATE_GUEST_ENV: JSON.stringify(guestRouting), SUBSTRATE_RECEIPTS: receiptsDir, SUBSTRATE_WORLD_INSTANCE: instance.instance, SUBSTRATE_GUEST_NAME: receiptGuest(spec.name) }, cwd: dir, stdio: ['ignore', 'ignore', 'pipe', 'ipc'], windowsHide: true });
+                const lifetime = commandLifetime(child);
+                const runtime = new RemoteRuntime(`http://127.0.0.1:${agentPort}`, token, {
+                    fetch: ((input, init) => guestControl(async (control) => {
+                        const signals = [control, init?.signal, ...(starting ? [spec.signal] : [])].filter(Boolean);
+                        const response = await fetch(input, { ...init, signal: AbortSignal.any(signals) });
+                        // JSON control replies must complete inside the budget; event/product streams retain their own lifetime.
+                        if (response.headers.get('content-type')?.includes('application/json')) {
+                            const bytes = await response.arrayBuffer();
+                            return new Response(bytes, { status: response.status, statusText: response.statusText, headers: response.headers });
+                        }
+                        return response;
+                    }, 'guest control transport', starting ? spec.signal : undefined)),
+                });
+                const g = { lifetime, name: spec.name, dir, cwd: p.cwd, env: env, child, runtime, ports, status: { state: 'started' }, imageRuntime: p.runtime, agentPort, resetOnStop: spec.resetOnStop };
+                guests.set(spec.name, g);
+                update(g, g.status);
+                if (!child.pid) {
+                    await lifetime.finish();
+                    releaseGuestProcesses([receipt]);
+                    throw new Error('Substrate guest process did not spawn');
+                }
+                retainGuestProcess(receipt, { pid: child.pid });
+                let diagnostic = '';
+                child.stderr?.on('data', bytes => { diagnostic = (diagnostic + String(bytes)).slice(-8192); });
+                child.on('error', error => { if (!g.stopping)
+                    update(g, { state: 'failed', reason: error.message }); });
+                child.once('exit', (code, signal) => { if (!g.stopping)
+                    update(g, { state: 'failed', ...(code !== null ? { exitCode: code } : {}), reason: `Substrate agent exited (${code ?? signal}): ${diagnostic.trim()}` }); });
+                await new Promise((yes, no) => {
+                    const cleanup = () => { child.off('message', ready); child.off('error', failed); child.off('exit', ended); spec.signal?.removeEventListener('abort', aborted); };
+                    const failed = (error) => { cleanup(); no(error); };
+                    const ended = () => failed(new Error(g.status.reason ?? 'Substrate agent exited during startup'));
+                    const aborted = () => failed(spec.signal?.reason ?? new Error('Substrate guest startup cancelled'));
+                    const ready = (message) => { if (message.ready !== true)
+                        return; cleanup(); yes(); };
+                    child.on('message', ready);
+                    child.once('error', failed);
+                    child.once('exit', ended);
+                    spec.signal?.addEventListener('abort', aborted, { once: true });
+                    if (spec.signal?.aborted)
+                        aborted();
+                });
+                const birth = await lifetime.identity;
+                if (!birth?.start || child.exitCode !== null || child.signalCode !== null)
+                    throw new Error('Substrate agent birth identity unavailable; ownership retained');
+                retainGuestProcess(receipt, birth);
+                await provider.start({ id: spec.name, token });
+                await runtime.connect();
+                if (args.length) {
+                    const commandEnv = { ...deploy, ...env };
+                    delete commandEnv.SUBSTRATE_TOKEN;
+                    delete commandEnv.SUBSTRATE_ROOT;
+                    g.launch = await startAdmitted(g, args, { cwd: p.cwd, env: commandEnv }, spec.signal);
+                    void g.launch.result.then(r => { if (!g.stopping)
+                        update(g, { state: 'exited', exitCode: r.exitCode, ...(r.exitCode !== 0 ? { reason: r.stderr || `image command exited ${r.exitCode}` } : {}) }); }, error => { if (!g.stopping)
+                        update(g, { state: 'failed', reason: String(error) }); });
+                }
+                for (const check of spec.checks?.length ? spec.checks : [...ports].map(port => ({ port, type: 'tcp' }))) {
+                    if (!ports.has(check.port))
+                        throw new Error('health port is not declared');
+                    {
+                        // Substrate discovery polls owned command groups every 200 ms (published linux-lane.js).
+                        while (!(await runtime.ports()).includes(check.port)) {
+                            spec.signal?.throwIfAborted();
+                            live(spec.name);
+                            if (g.launch && g.launch.state !== 'running')
+                                throw new Error(g.status.reason ?? 'image command exited before listening');
+                            await delay(200);
+                        }
+                    }
+                    if (check.type === 'http') {
+                        const response = await runtime.request(check.port, check.path ?? '/', { signal: spec.signal });
+                        await response.body?.cancel();
+                        if (!response.ok)
+                            throw new Error(`HTTP health ${response.status}`);
+                    }
+                }
+                spec.signal?.throwIfAborted();
+                return { ports: [...ports].map(internal => ({ internal, host: agentPort, url: runtime.portUrl(internal) })) };
+            }
+            catch (error) {
+                states.set(spec.name, { state: 'failed', reason: String(error.message ?? error) });
+                const g = guests.get(spec.name);
+                if (g) {
+                    update(g, states.get(spec.name));
+                    await provider.stop({ name: spec.name, url: '' });
+                }
+                throw error;
+            }
+            finally {
+                starting = false;
+                clearTimeout(deadline);
+            }
+        },
+        async exec(name, spec) {
+            const g = live(name);
+            const queue = [];
+            let wake, done = false;
+            const push = (item) => { queue.push(item); wake?.(); };
+            const env = guestEnvironment(spec.env ?? {});
+            for (const [key, value] of Object.entries(g.env))
+                if (/^(VOLTER_|TWIN_|NODE_OPTIONS$|NODE_EXTRA_CA_CERTS$|.*_TWIN_URL$|HTTPS?_PROXY$|https?_proxy$|NO_PROXY$|no_proxy$)/.test(key))
+                    env[key] = value;
+            const handle = await startAdmitted(g, spec.args, { cwd: spec.cwd ?? g.cwd, env, onStdout: stdout => push({ stdout }), onStderr: stderr => push({ stderr }) });
+            void handle.result.then(result => { push({ exit: result.exitCode }); done = true; wake?.(); }, error => { push({ stderr: String(error) }); push({ exit: 1 }); done = true; wake?.(); });
+            const processes = await g.runtime.processes();
+            const pid = processes.filter(p => p.command === handle.command).at(-1)?.pid ?? handle.pid;
+            const events = { async *[Symbol.asyncIterator]() { for (;;) {
+                    while (queue.length)
+                        yield queue.shift();
+                    if (done)
+                        return;
+                    await new Promise(r => { wake = r; });
+                } } };
+            return { pid, events };
+        },
+        async request(name, port, request) {
+            const g = live(name);
+            if (!g.ports.has(port))
+                throw new Error('guest port is not declared');
+            const url = new URL(request.url), headers = new Headers(request.headers);
+            for (const key of ['host', 'connection', 'content-length', 'transfer-encoding'])
+                headers.delete(key);
+            const init = { method: request.method, headers, body: ['GET', 'HEAD'].includes(request.method) ? undefined : await request.arrayBuffer(), signal: request.signal, redirect: 'manual' };
+            return g.runtime.request(port, url.pathname + url.search, init);
+        },
+        pause: name => provider.pause({ name, url: '' }),
+        resume: async (name) => { await provider.resume({ name, url: '' }); },
+        stop,
+        async remove(name) { await stop(name); if (!/^[a-zA-Z0-9_-]+$/.test(name))
+            throw new Error('invalid guest name'); states.delete(name); rmSync(ownedPath(data, `guests/${options.world}/${name}`), { recursive: true, force: true }); },
+    };
+}

package/dist/src/host.js

@@ -1,3 +1,4 @@
+import { errorMessage } from "./error-message.js";
 import { getPack, registerPack } from '@volter/world-core/runtime';
 // Co-located twin host — run many twins in ONE process instead of one OS process
 // per twin. The twin core is a pure, transport-agnostic handler (see a pack's
@@ -61,8 +62,8 @@ export async function startColocatedHost(specs, options = {}) {
         // the shared process. (A thrown *request* handler is already contained by Bun.serve → 500.)
         // We log and attribute rather than exit — state stays consistent because every kernel write
         // is atomic (temp→rename) and root-keyed, so a swallowed error can't corrupt a sibling.
-        const onRejection = (reason) => onEvent({ twin: '(host)', kind: 'unhandledRejection', detail: String(reason) });
-        const onUncaught = (err) => onEvent({ twin: '(host)', kind: 'uncaughtException', detail: String(err) });
+        const onRejection = (reason) => onEvent({ twin: '(host)', kind: 'unhandledRejection', detail: errorMessage(reason) });
+        const onUncaught = (err) => onEvent({ twin: '(host)', kind: 'uncaughtException', detail: errorMessage(err) });
         process.on('unhandledRejection', onRejection);
         process.on('uncaughtException', onUncaught);
         const servers = [];
@@ -112,7 +113,7 @@ export async function startColocatedHost(specs, options = {}) {
                 // Every stop runs, even when a sibling hangs or throws. Host shutdown
                 // still resolves within its budget so the owning runtime can retire it.
                 for (const error of await stop())
-                    onEvent({ twin: '(host)', kind: 'stop-failed', detail: String(error) });
+                    onEvent({ twin: '(host)', kind: 'stop-failed', detail: errorMessage(error) });
             },
         };
     }
@@ -139,7 +140,7 @@ export async function startColocatedHost(specs, options = {}) {
             }
         });
         worker.on('error', (err) => {
-            onEvent({ twin: spec.id, kind: 'error', detail: String(err) });
+            onEvent({ twin: spec.id, kind: 'error', detail: errorMessage(err) });
             if (!ready)
                 rejectReady(err);
         });

package/dist/src/index.d.ts

@@ -53,4 +53,5 @@ export type { ServedWorld } from './served-world.js';
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.js';
 export { assertWorldStateRemovable } from './ancestry.js';
 export { withoutVaultSignIn } from './runtime.js';
+export { errorMessage } from './error-message.js';
 export { materializeBrowserFiles, browsersDir, worldBrowser, worldBrowsers, putWorldBrowser, deleteWorldBrowser, inheritWorldBrowsers, type WorldBrowser } from './browsers.js';

package/dist/src/index.js

@@ -37,4 +37,5 @@ export { LOCAL_ORIGIN_BASE, localWorldOrigin, pagesOfHost, pagesOriginOf, pathOf
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
 export { assertWorldStateRemovable } from "./ancestry.js";
 export { withoutVaultSignIn } from "./runtime.js";
+export { errorMessage } from "./error-message.js";
 export { materializeBrowserFiles, browsersDir, worldBrowser, worldBrowsers, putWorldBrowser, deleteWorldBrowser, inheritWorldBrowsers } from "./browsers.js";

package/dist/src/infra-cli.js

@@ -2,8 +2,12 @@
 // `volter-world-infra up|status|down`: the World-managed infrastructure's declared lifecycle commands (infra.ts), as
 // a process. World configs invoke this declared service; application agents never operate or diagnose its backing.
 import { runInfrastructure } from "./infra.js";
+import { errorMessage } from "./error-message.js";
 const code = await runInfrastructure(process.argv[2] ?? '', process.env, {
     out: (text) => { process.stdout.write(text); },
     err: (text) => { process.stderr.write(text); },
+}).catch(error => {
+    process.stderr.write(`managed infrastructure ${process.argv[2] ?? ''} failed: ${errorMessage(error)}\n`);
+    return 1;
 });
 process.exit(code);