@volter/world-runtime 3.0.37 → 3.0.39

package/src/guest-control.mjs

@@ -0,0 +1,17 @@
+import { COMMAND_GRACE_MS } from './command-lifetime.mjs';
+// Runtime teardown contract: existing 5000 ms grace, not a new vendor default.
+export function guestControl(operation, label, signal, budget = COMMAND_GRACE_MS) {
+  const controller = new AbortController();
+  const abort = () => controller.abort(signal.reason);
+  if (signal?.aborted) abort(); else signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(() => controller.abort(new Error(`${label} exceeded ${budget} ms runtime control budget; ownership retained`)), budget);
+  let rejectAbort;
+  const failed = new Promise((_, reject) => { rejectAbort = reject; });
+  const cancelled = () => rejectAbort(controller.signal.reason);
+  controller.signal.addEventListener('abort', cancelled, { once: true });
+  if (controller.signal.aborted) cancelled();
+  return Promise.race([Promise.resolve().then(() => { controller.signal.throwIfAborted(); return operation(controller.signal); }), failed]).finally(() => {
+    clearTimeout(timer); signal?.removeEventListener('abort', abort);
+    controller.signal.removeEventListener('abort', cancelled);
+  });
+}

package/src/guest-entry.mjs

@@ -0,0 +1,146 @@
+// One pinned Substrate host; the interim adapter admits Node argv, never an OS shell.
+import childProcess from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { createNodeHost, serveAgent } from '@volter/browser-host-node';
+import { parseSimpleBrowserCommand } from '@volter/browser-runtime';
+import { signalOwnedProcess } from './process-signal.mjs';
+import { commandLifetime, COMMAND_GRACE_MS } from './command-lifetime.mjs';
+import { beginGuestProcess, retainGuestProcess, releaseGuestProcesses } from './guest-processes.mjs';
+import { admitGuestArgv, guestEnvironment } from './guest-command.mjs';
+import { guestControl } from './guest-control.mjs';
+
+const host = createNodeHost({ root: process.env.SUBSTRATE_ROOT });
+const routing = JSON.parse(process.env.SUBSTRATE_GUEST_ENV);
+const retained = new Map(), admissions = new Map();
+let closing = false, launching;
+const rawSpawn = childProcess.spawn;
+// The pinned lane creates/retains children synchronously in run(). Replace exactly its
+// launcher before spawning, and keep its own pipes, process tracking and socket discovery.
+// Scope is synchronous: inspectors and future unrelated spawns never acquire this admission.
+childProcess.spawn = (file, args, options) => {
+  if (file !== '/bin/sh') return rawSpawn(file, args, options);
+  if (!launching || args.length !== 2 || args[0] !== '-c' || args[1] !== 'world-owned-node') throw new Error('guest shell execution refused');
+  const launch = launching;
+  const admitted = admitGuestArgv(launch.argv, process.env.SUBSTRATE_GUEST_RUNTIME, host.root, options.cwd);
+  const receipt = beginGuestProcess(process.env.SUBSTRATE_RECEIPTS, process.env.SUBSTRATE_WORLD_INSTANCE, process.env.SUBSTRATE_GUEST_NAME, 'command');
+  const child = rawSpawn(process.execPath, admitted.argv.slice(1), { ...options, env: { ...guestEnvironment(options.env ?? {}), ...routing }, cwd: admitted.cwd, shell: false });
+  const lifetime = commandLifetime(child, launch.signal);
+  const held = { child, lifetime, receipt };
+  if (!child.pid) {
+    void lifetime.finish().then(() => releaseGuestProcesses([receipt])).catch(error => console.error('Unspawned guest receipt retained:', error));
+    throw new Error('guest Node process did not spawn');
+  }
+  retained.set(child.pid, held); // ownership before publication
+  retainGuestProcess(receipt, { pid: child.pid });
+  held.birth = lifetime.identity.then(birth => {
+    if (!birth?.start || child.exitCode !== null || child.signalCode !== null || retained.get(child.pid) !== held) {
+      throw new Error('guest spawn birth invalid: original child no longer held/live or birth unavailable; admission refused');
+    }
+    retainGuestProcess(receipt, birth); // readiness cannot precede this successful atomic publication
+    return birth;
+  });
+  held.birth.then(launch.resolve, launch.reject);
+  void lifetime.finish().then(() => {
+    retained.delete(child.pid);
+    releaseGuestProcesses([receipt]); // commandLifetime confirms close and whole-group absence
+  }).catch(error => console.error('Guest command retirement unconfirmed; receipt retained:', error));
+  launch.held = held;
+  return child;
+};
+syncBuiltinESMExports();
+const laneRun = host.lane.run.bind(host.lane);
+host.lane.run = () => Promise.reject(new Error('guest shell fallback refused; only admitted Node argv is supported'));
+host.lane.openPty = () => Promise.reject(new Error('guest PTY/shell execution is unsupported by Node argv admission'));
+const program = '__world_node_argv';
+host.runtime.registerProgram(program, async (argv, options) => {
+  const launch = argv.length === 2 ? admissions.get(argv[1]) : undefined;
+  if (closing || !launch || launch.consumed) throw new Error('guest command has no live argv admission');
+  launch.consumed = true;
+  if (options.terminal || options.stdinStream) throw new Error('guest PTY/streamed stdin is unsupported');
+  const cwd = host.filesystem.real(options.cwd ?? '/');
+  admitGuestArgv(launch.argv, process.env.SUBSTRATE_GUEST_RUNTIME, host.root, cwd);
+  launch.signal = options.signal;
+  let result;
+  try {
+    launching = launch;
+    // The pinned lane's raw abort callback signals a numeric PID; leave cancellation to
+    // our retained commandLifetime so every delivery uses the held child or verified birth.
+    result = laneRun('world-owned-node', { ...options, signal: undefined, env: { ...guestEnvironment(options.env ?? {}), ...routing } });
+  } catch (error) { launch.reject(error); throw error; }
+  finally { launching = undefined; }
+  if (!launch.held) { const error = new Error('Substrate did not retain the admitted Node child'); launch.reject(error); throw error; }
+  return (await Promise.all([result, launch.birth]))[0];
+});
+const runtimeStart = host.runtime.start.bind(host.runtime);
+host.runtime.start = (command, options) => {
+  let argv = parseSimpleBrowserCommand(command);
+  // RemoteRuntime's wire envelope is decoded as data; neither envelope nor payload runs in a shell.
+  if (argv.length === 3 && argv[0] === 'sh' && argv[1] === '-c') argv = parseSimpleBrowserCommand(argv[2]);
+  if (closing || argv.length !== 2 || argv[0] !== program || !admissions.has(argv[1])) throw new Error('guest command is not an admitted Node argv operation');
+  return runtimeStart(`${program} ${argv[1]}`, options);
+};
+async function signalCommands(signal) {
+  await Promise.all([...retained.values()].map(async held => {
+    const birth = await held.birth; // rejected/unheld captures can never authorize a numeric signal
+    await signalOwnedProcess(birth, signal, true);
+  }));
+}
+const agent = await guestControl(() => serveAgent({ host, token: process.env.SUBSTRATE_TOKEN, port: Number(process.env.SUBSTRATE_AGENT_PORT), bind: '127.0.0.1' }), 'guest agent startup');
+const streams = new Set();
+agent.server.on('request', (request, response) => {
+  if (!new URL(request.url, 'http://guest').pathname.endsWith('/events')) return;
+  streams.add(response); response.on('close', () => streams.delete(response));
+});
+async function close() {
+  if (closing) return;
+  closing = true;
+  const commands = [...retained.values()];
+  for (const held of commands) { held.lifetime.cancel('SIGCONT'); held.lifetime.cancel('SIGTERM'); }
+  // Every command retires through the same bounded grace/KILL/confirmation as World commands.
+  const results = await Promise.allSettled(commands.map(held => held.lifetime.finish()));
+  for (const result of results) if (result.status === 'rejected') throw result.reason;
+  await guestControl(async () => {
+    await host.close();
+    for (const response of streams) response.end();
+    await agent.close();
+  }, 'Substrate guest drain');
+  process.exit(0);
+}
+process.on('message', async ({ id, action, path }) => {
+  try {
+    let value;
+    if (action === 'prepare') {
+      if (closing) throw new Error('Substrate guest is retiring');
+      const argv = JSON.parse(path);
+      if (!Array.isArray(argv) || argv[0] !== 'node') throw new Error('admitted guest program is node');
+      const key = randomUUID();
+      let resolve, reject;
+      const birth = new Promise((yes, no) => { resolve = yes; reject = no; });
+      birth.catch(() => {});
+      admissions.set(key, { argv, birth, resolve, reject, consumed: false });
+      value = key;
+    } else if (action === 'admission') {
+      const launch = admissions.get(path);
+      if (!launch) throw new Error('guest launch admission missing');
+      try { value = await guestControl(() => launch.birth, 'guest birth admission'); }
+      finally { if (launch.consumed) admissions.delete(path); }
+    } else if (action === 'pause' || action === 'resume') {
+      await guestControl(() => signalCommands(action === 'pause' ? 'SIGSTOP' : 'SIGCONT'), `guest ${action}`);
+    } else if (action === 'stat') {
+      const s = host.filesystem.statSync(path);
+      value = { size: s.size, mode: s.mode, mtime: s.mtime.toISOString(), type: s.isDirectory() ? 'directory' : 'file' };
+    } else throw new Error(`unsupported guest control ${action}`);
+    if (process.connected) process.send?.({ id, value });
+  } catch (error) { if (process.connected) process.send?.({ id, error: error.message }); }
+});
+const retire = () => void close().catch(error => {
+  console.error('Substrate guest retirement refused; ownership retained:', error);
+  // No success or receipt deletion on uncertainty; exit closes control. World down owns retry.
+  process.exit(1);
+});
+process.on('disconnect', retire);
+if (!process.connected) retire();
+process.on('SIGTERM', retire);
+process.on('SIGINT', retire);
+process.send?.({ ready: true, port: agent.port, controlBudgetMs: COMMAND_GRACE_MS });

package/src/guest-processes.d.mts

@@ -0,0 +1,9 @@
+import type { SpawnIdentity } from './process-receipt.js';
+export interface GuestProcessRecord extends SpawnIdentity { instance: string; guest: string; kind: 'agent' | 'command' | 'pty'; launching: false }
+export interface GuestProcessReceipt { path: string; record: GuestProcessRecord }
+export interface GuestProcessLaunch { path: string; record: Omit<GuestProcessRecord, 'pid' | 'launching'> & { pid?: number; launching: boolean } }
+export function guestProcessDirectory(instanceDir: string): string;
+export function beginGuestProcess(directory: string, instance: string, guest: string, kind: GuestProcessRecord['kind']): GuestProcessLaunch;
+export function retainGuestProcess(receipt: GuestProcessLaunch, identity: SpawnIdentity): void;
+export function readGuestProcesses(instanceDir: string, expectedInstance?: string): GuestProcessReceipt[];
+export function releaseGuestProcesses(receipts: Array<{ path: string }>): void;

package/src/guest-processes.mjs

@@ -0,0 +1,47 @@
+// Guest metadata over the existing atomic process receipt; no independent lifecycle.
+import { randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { publishProcessReceipt, readProcessReceipt } from './process-receipt.mjs';
+
+export const guestProcessDirectory = instanceDir => join(instanceDir, 'guest-processes');
+export function beginGuestProcess(directory, instance, guest, kind) {
+  mkdirSync(directory, { recursive: true });
+  const path = join(directory, `${randomUUID()}.json`);
+  const record = { instance, guest, kind, launching: true };
+  publishProcessReceipt(path, JSON.stringify(record));
+  return { path, record };
+}
+export function retainGuestProcess(receipt, identity) {
+  receipt.record = { ...receipt.record, launching: false, ...identity };
+  publishProcessReceipt(receipt.path, JSON.stringify(receipt.record));
+}
+export function readGuestProcesses(instanceDir, expectedInstance) {
+  const directory = guestProcessDirectory(instanceDir);
+  if (!existsSync(directory)) return [];
+  if (lstatSync(directory).isSymbolicLink()) throw new Error('Guest receipt directory is a symbolic link; ownership retained');
+  const names = readdirSync(directory);
+  if (!names.length) return [];
+  if (!expectedInstance) {
+    try { expectedInstance = JSON.parse(readFileSync(join(instanceDir, 'instance.json'), 'utf8')).instance; }
+    catch { throw new Error('Guest instance identity unreadable; ownership retained'); }
+  }
+  return names.map(name => {
+    const path = join(directory, name);
+    if (!/^[0-9a-f-]+\.json$/.test(name) || !lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()) throw new Error('Unresolved guest receipt publication; ownership retained');
+    const receipt = readProcessReceipt(path, text => {
+      const r = JSON.parse(text);
+      if (r.instance !== expectedInstance || typeof r.guest !== 'string' || !['agent', 'command', 'pty'].includes(r.kind)
+        || r.launching || !Number.isInteger(r.pid) || r.pid < 1 || (r.start !== undefined && (typeof r.start !== 'string' || !r.start))) {
+        throw new Error('Guest launch or spawn identity unresolved');
+      }
+      return r;
+    });
+    if (receipt.error || !receipt.value) throw receipt.error ?? new Error('Guest receipt disappeared during inspection; ownership retained');
+    return { path, record: receipt.value };
+  });
+}
+// The caller must have confirmed each recorded group absent before releasing these receipts.
+export function releaseGuestProcesses(receipts) {
+  for (const { path } of receipts) rmSync(path);
+}

package/src/guest-runner.ts

@@ -0,0 +1,414 @@
+// Substrate-backed light guests; architecture, "Other wires: … machines". Imports start nothing.
+import { spawn, type ChildProcess } 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, type RemoteProcessHandle, type SandboxProvider } from '@volter/browser-sandboxes';
+import type { MachinePool, MachineSpec, MachineProcess, MachineStatus, GuestImage, LightPoolOptions } from '@volter/world-core/runtime';
+import { allocatePort } from './tcp-port.ts';
+import { ownedPath, assertOwnedRealPath } from './owned-path.ts';
+import { commandLifetime, commandProcessGroup } from './command-lifetime.ts';
+import { beginGuestProcess, retainGuestProcess, readGuestProcesses, releaseGuestProcesses } from './guest-processes.mjs';
+import { retireOwnedProcessGroups } from './runtime.ts';
+import { guestControl } from './guest-control.mjs';
+import { admitGuestArgv, guestCommandGap, guestEnvironment } from './guest-command.mjs';
+type Plan = { runtime: string; cwd: string; env: Record<string, string>; command: string[]; ports: number[]; copies: Array<{ sources: string[]; destination: string; cwd: string }> };
+type Guest = { name: string; dir: string; cwd: string; env: Record<string, string>; child: ChildProcess; lifetime: ReturnType<typeof commandLifetime>; runtime: RemoteRuntime; ports: Set<number>; status: MachineStatus; stopping?: boolean; launch?: RemoteProcessHandle; imageRuntime: string; agentPort: number; resetOnStop?: boolean };
+const delay = (ms: number): Promise<void> => 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<string, Map<string, Guest>>();
+const lifecycle = new Map<string, Map<string, MachineStatus>>();
+/** Word splitting for the supported Dockerfile instructions; no shell is executed while parsing. */
+function words(text: string): string[] {
+  const out: string[] = []; 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: string): string[] {
+  if (!text.trim().startsWith('[')) throw guestCommandGap('guest shell-form CMD/ENTRYPOINT is unsupported; use Node argv with an image entry file');
+  const value: unknown = 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: GuestImage): Plan {
+  const out: Plan = { runtime: image.runtime ?? '', cwd: '/', env: {}, command: [], ports: [], copies: [] };
+  let entry: string[] = [], cmd: string[] = [], 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: string): string => 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: string, path: string, cwd = '/'): string {
+  // 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: string, destination: string): void {
+  mkdirSync(dirname(destination), { recursive: true });
+  cpSync(source, destination, { recursive: true, dereference: true, filter: path => !['.git', '.volter'].includes(basename(path)) });
+}
+function prepare(dir: string, image: GuestImage, p: Plan): void {
+  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(): NodeJS.ProcessEnv {
+  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: NodeJS.ProcessEnv = { ...instance.env, ...current };
+  if (!env.VOLTER_WORLD || !env.NODE_OPTIONS) throw new Error('World guest injection environment is incomplete');
+  return env;
+}
+function injected(base: NodeJS.ProcessEnv, deploy: Record<string, string>, dir: string): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { 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: string | undefined;
+function trustedNodeExecutable(): string {
+  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: ChildProcess, action: string, path?: string, signal?: AbortSignal): Promise<any> {
+  return guestControl(control => new Promise((yes, no) => {
+    if (!child.connected) { no(new Error('Substrate guest control disconnected')); return; }
+    const id = ++messageId;
+    const cleanup = (): void => { child.off('message', reply); child.off('exit', ended); child.off('disconnect', ended); child.off('error', failed); control.removeEventListener('abort', aborted); };
+    const failed = (error: Error): void => { cleanup(); no(error); };
+    const aborted = (): void => failed(control.reason);
+    const ended = (): void => failed(new Error('Substrate guest exited during control request'));
+    const reply = (message: any): void => { 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: Guest, args: string[], options: Parameters<RemoteRuntime['start']>[1], signal?: AbortSignal): Promise<RemoteProcessHandle> {
+  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: LightPoolOptions & { world: string; root?: string }): MachinePool {
+  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: string): string => `${options.world}/${name}`;
+  const receipts = (name: string) => 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<string, Guest>();
+  const states = lifecycle.get(root) ?? new Map<string, MachineStatus>();
+  pools.set(root, guests); lifecycle.set(root, states);
+  const update = (g: Guest, status: MachineStatus): void => { g.status = status; states.set(g.name, status); };
+  const live = (name: string): Guest => {
+    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: string): Promise<void> => {
+    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: SandboxProvider = {
+    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: MachineSpec) {
+      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: Parameters<typeof fetch>[0], init?: RequestInit) => guestControl(async control => {
+            const signals = [control, init?.signal, ...(starting ? [spec.signal] : [])].filter(Boolean) as AbortSignal[];
+            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)) as typeof fetch,
+        });
+        const g: Guest = { lifetime, name: spec.name, dir, cwd: p.cwd, env: env as Record<string, string>, 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<void>((yes, no) => {
+          const cleanup = (): void => { child.off('message', ready); child.off('error', failed); child.off('exit', ended); spec.signal?.removeEventListener('abort', aborted); };
+          const failed = (error: Error): void => { cleanup(); no(error); };
+          const ended = (): void => failed(new Error(g.status.reason ?? 'Substrate agent exited during startup'));
+          const aborted = (): void => failed(spec.signal?.reason ?? new Error('Substrate guest startup cancelled'));
+          const ready = (message: any): void => { 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 } as Record<string, string>;
+          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' as const }))) {
+          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 as 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: Array<{ stdout?: string } | { stderr?: string } | { exit: number }> = []; let wake: (() => void) | undefined, done = false;
+      const push = (item: (typeof queue)[number]): void => { 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: MachineProcess['events'] = { async *[Symbol.asyncIterator]() { for (;;) { while (queue.length) yield queue.shift()!; if (done) return; await new Promise<void>(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' as const };
+      return g.runtime.request(port, url.pathname + url.search, init);
+    },
+    pause: name => provider.pause({ name, url: '' }) as Promise<void>,
+    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 }); },
+  };
+}