@daugasauron/dolly 0.0.0-stage → 0.1.4-rc.0

package/src/process-supervisor.mjs

@@ -0,0 +1,1002 @@
+import { DOLLY_PROCESS_ABI_DIGEST } from "../dist/dolly-process-abi.mjs";
+import { DOLLY_ERRNO } from "./process-constants.mjs";
+import { parseWasmInterface } from "./wasm-interface.mjs";
+import { validateProcessInterface } from "./process-abi.mjs";
+import { validateThreadProfile } from "../host/threads/threads.mjs";
+import { DOLLY_THREAD_SPAWN } from "../host/threads/abi.mjs";
+import { executableHostRequirements, checkHostAbi } from "../host/requirements.mjs";
+import {
+  DOLLY_PROCESS_EXEC, DOLLY_PROCESS_EXIT, DOLLY_PROCESS_PACKET_LIMIT as packetLimit, DOLLY_PROCESS_SIGALRM, DOLLY_PROCESS_SIGINT,
+  DOLLY_PROCESS_SIGKILL, DOLLY_PROCESS_SIGNAL, DOLLY_PROCESS_SIGNAL_ACKNOWLEDGE,
+  DOLLY_PROCESS_SIGWINCH, DOLLY_PROCESS_SIZEOF, DOLLY_PROCESS_SPAWN,
+  DOLLY_PROCESS_SPAWN_FOREGROUND, DOLLY_PROCESS_SPAWN_INHERIT_ENVIRONMENT,
+  DOLLY_PROCESS_SPAWN_INTERACTIVE,
+} from "./process-constants.mjs";
+import { hex } from "./static-asset.mjs";
+
+const encoder = new TextEncoder();
+const spawnHeaderSize = DOLLY_PROCESS_SIZEOF.dolly_process_spawn_request;
+// The kernel's deferred-call result; processes never observe it.
+const deferredResult = -(1n << 63n);
+const interruptedSystemCall = -BigInt(DOLLY_ERRNO.EINTR);
+// Trusted bounds on concurrent process Workers, independent of kernel
+// records: a spawn is admitted while the processes' committed Wasm memory is
+// under the budget or the spawning process has no live child, and the count,
+// the kernel's table, is the backstop. It stays below what Chromium reserves:
+// the memory of a 61st process of 8 GiB was refused.
+const processWorkerLimit = 56;
+const processMemoryBudgetBytes = 4 * 1024 * 1024 * 1024;
+// Chromium releases the address space of a terminated Worker's memory some
+// time after terminate(): a memory it cannot reserve is asked for again for
+// a while before the process is refused. A spawn the count refuses waits as
+// long, like any blocking call, asked again whenever a process ends and at
+// each service tick; then it fails EAGAIN, a full process table's answer. A
+// spawn the budget refuses waits until a process ends, however long: make and
+// Cargo end a build at a spawn's EAGAIN. So a pipeline started over the
+// budget waits forever if its first stage fills the pipe before the next
+// stage is admitted; a signal (Ctrl+C) ends the wait.
+const reservationRetryMilliseconds = 50;
+const reservationPatienceMilliseconds = 5000;
+const interruptGraceMilliseconds = 500;
+const compiledModuleCacheEntries = 64;
+const compiledModuleCacheBytes = 256 * 1024 * 1024;
+// File versions known to hold a cached module's bytes (dolly_process_image_version).
+const compiledVersionEntries = 1024;
+const compilationNoticeMilliseconds = 250;
+const largeInteractiveProcessBytes = 128 * 1024 * 1024;
+const workerReclamationMilliseconds = 500;
+
+// How many calls a recursion nests before this thread's stack ends, entered
+// with enter. Each call counts itself in memory and holds sixteen values it
+// loaded there across the next call, so its frame is as large in a baseline
+// compiler as in an optimizing one: a one-local recursion read anything from
+// 0.4 to 2.4 times in Firefox as its tiers changed.
+// (func $dive (result i64) (local i64 x 16) count++; load them; dive() + their sum)
+const diver = "AGFzbQEAAAABBQFgAAF+AwIBAAUDAQABBxECBm1lbW9yeQIABGRpdmUAAAq/AQG8AQEQfkEAQQAoAgBBAWo2AgBBCCkDACEAQRAp" +
+  "AwAhAUEYKQMAIQJBICkDACEDQSgpAwAhBEEwKQMAIQVBOCkDACEGQcAAKQMAIQdByAApAwAhCEHQACkDACEJQdgAKQMAIQpB4AAp" +
+  "AwAhC0HoACkDACEMQfAAKQMAIQ1B+AApAwAhDkGAASkDACEPEAAgAHwgAXwgAnwgA3wgBHwgBXwgBnwgB3wgCHwgCXwgCnwgC3wg" +
+  "DHwgDXwgDnwgD3wL";
+async function stackDepth(enter) {
+  const { memory, dive } = new WebAssembly.Instance(new WebAssembly.Module(
+    Uint8Array.from(atob(diver), character => character.charCodeAt(0)))).exports;
+  try { await enter(dive)(); } catch { /* The stack ended: that is the measurement. */ }
+  return new Uint32Array(memory.buffer, 0, 1)[0];
+}
+
+export function terminalFailureReason(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const firstLine = message.split(/[\r\n]/, 1)[0]
+    .replace(/[^\x20-\x7e]/g, "?")
+    .slice(0, 512);
+  return firstLine || "unknown Worker failure";
+}
+
+function encodeStrings(strings, label) {
+  if (!Array.isArray(strings)) throw new TypeError(`${label} must be an array`);
+  const encoded = [];
+  let size = 0;
+  for (const value of strings) {
+    if (typeof value !== "string" || value.includes("\0")) {
+      throw new TypeError(`${label} contains an invalid string`);
+    }
+    const bytes = encoder.encode(value);
+    if (bytes.length + 1 > packetLimit - size) throw new RangeError(`${label} is too large`);
+    encoded.push(bytes);
+    size += bytes.length + 1;
+  }
+  const output = new Uint8Array(size);
+  let offset = 0;
+  for (const bytes of encoded) {
+    output.set(bytes, offset);
+    offset += bytes.length + 1;
+  }
+  return output;
+}
+
+// Root processes run argv[0], inherit the kernel environment and map
+// descriptors 0-2 onto themselves.
+function encodeSpawn(arguments_, flags) {
+  if (!Array.isArray(arguments_) || arguments_.length === 0) {
+    throw new TypeError("a process needs argv[0]");
+  }
+  const [path] = arguments_;
+  if (typeof path !== "string" || !path.startsWith("/") || path.includes("\0")) {
+    throw new TypeError("a process path must be absolute");
+  }
+  const pathBytes = encoder.encode(path);
+  const argumentBytes = encodeStrings(arguments_, "process arguments");
+  const size = spawnHeaderSize + pathBytes.length + argumentBytes.length + 3 * 8;
+  if (pathBytes.length > 4096 || size > packetLimit) {
+    throw new RangeError("process spawn packet is too large");
+  }
+  const packet = new Uint8Array(size);
+  const view = new DataView(packet.buffer);
+  view.setUint32(0, flags | DOLLY_PROCESS_SPAWN_INHERIT_ENVIRONMENT, true);
+  view.setUint32(4, arguments_.length, true);
+  view.setUint32(16, 3, true);
+  view.setUint32(28, pathBytes.length, true);
+  view.setBigUint64(32, BigInt(argumentBytes.length), true);
+  view.setBigUint64(48, 0xffffffffffffffffn, true);
+  packet.set(pathBytes, spawnHeaderSize);
+  packet.set(argumentBytes, spawnHeaderSize + pathBytes.length);
+  for (let descriptor = 0; descriptor < 3; ++descriptor) {
+    view.setUint32(size - 24 + descriptor * 8, descriptor, true);
+    view.setUint32(size - 20 + descriptor * 8, descriptor, true);
+  }
+  return packet;
+}
+
+function createProcessMemory({ initial, maximum }) {
+  return new WebAssembly.Memory({
+    initial,
+    maximum,
+    shared: true,
+    address: "i64",
+  });
+}
+
+export class DollyProcessSupervisor {
+  constructor(kernel, kernelMemory, gateModule, workerUrl, processContract, hostAbi, serviceHost, threadContract, threadHost, processModules) {
+    if (!(kernelMemory instanceof WebAssembly.Memory) ||
+        !(gateModule instanceof WebAssembly.Module) || !(workerUrl instanceof URL)) {
+      throw new TypeError("invalid Dolly process supervisor configuration");
+    }
+    this.kernel = kernel;
+    this.kernelMemory = kernelMemory;
+    this.gateModule = gateModule;
+    this.workerUrl = workerUrl;
+    this.processContract = processContract;
+    this.hostAbi = hostAbi;
+    this.serviceHost = serviceHost;
+    this.threadContract = threadContract;
+    this.threadHost = threadHost;
+    this.processModules = processModules;
+    this.processes = new Map();
+    this.deferred = new Map();
+    this.compiledModules = new Map();
+    this.compiledModuleBytes = 0;
+    this.compiledVersions = new Map();
+    this.launchChain = Promise.resolve();
+    this.mailboxAddress = Number(kernel.dolly_process_mailbox_address());
+    this.mailboxCapacity = packetLimit;
+    if (!Number.isSafeInteger(this.mailboxAddress) || this.mailboxAddress <= 0 ||
+        this.mailboxAddress > kernelMemory.buffer.byteLength - this.mailboxCapacity) {
+      throw new Error("Dolly kernel supplied an invalid process mailbox");
+    }
+    this.serviceTimer = setInterval(() => this.#serviceTick(), 16);
+  }
+
+  static async create(kernel, kernelMemory, runtimeBase, hostAbi, serviceHost, threadHost, processModules) {
+    const [gateBytes, contractBytes, threadBytes, workerBytes] = await Promise.all([
+      "dolly-process-gate-0.wasm", "dolly-process-0.wasm", "dolly-threads-0.wasm",
+      "dolly-process-worker.mjs",
+    ].map(async name => {
+      const response = await fetch(new URL(`dist/${name}`, runtimeBase), {
+        cache: "no-store", credentials: "same-origin", redirect: "error",
+      });
+      if (!response.ok) throw new Error(`Dolly ${name} returned HTTP ${response.status}`);
+      return response.arrayBuffer();
+    }));
+    const gateModule = await WebAssembly.compile(gateBytes);
+    // Fresh Workers share trusted code bytes, never process memory or JS state.
+    const workerUrl = new URL(URL.createObjectURL(new Blob([workerBytes], { type: "text/javascript" })));
+    try {
+      const supervisor = new DollyProcessSupervisor(
+        kernel, kernelMemory, gateModule, workerUrl,
+        parseWasmInterface(contractBytes, "dolly-process-0"),
+        hostAbi, serviceHost, parseWasmInterface(threadBytes, "dolly-threads-0"), threadHost, processModules,
+      );
+      supervisor.releaseWorkerSource = () => URL.revokeObjectURL(workerUrl.href);
+      // Entered through JSPI (WebAssembly.promising), a process runs on a
+      // stack of its own. Chrome's holds about 950 KB where a Worker's holds
+      // 500 KB, which Clang needs: an executable asks for it with a
+      // dolly.process.stack section, and only the compiler carries one
+      // (src/process/compiler-main.c). Every other program is entered
+      // directly: a Codex build crashed Chrome's tab twice on that stack
+      // (tasks/20260930-232236-llvm-in-dolly), and Firefox 155 reports every
+      // Worker terminated inside such a call as an uncaught exception that no
+      // listener receives. Firefox's holds no more, so the entry is also taken
+      // only where it is measured half again as deep (Chrome 151: 1.90
+      // times, Firefox 155: 1.01, each in 48 measurements of 48). stack@0
+      // sizes the room of each stack by the same measurements.
+      supervisor.stackDepths = { direct: await stackDepth(entry => entry),
+        promising: WebAssembly.promising ? await stackDepth(WebAssembly.promising) : 0 };
+      supervisor.promisingEntry = supervisor.stackDepths.promising > 1.5 * supervisor.stackDepths.direct;
+      return supervisor;
+    } catch (error) {
+      URL.revokeObjectURL(workerUrl.href);
+      throw error;
+    }
+  }
+
+  // threads@0 was disabled and its Workers are terminated: the programs that
+  // ran on them end here, each told why on its own stderr.
+  withdrawThreads() {
+    this.threadHost = undefined;
+    for (const process of [...this.processes.values()]) {
+      if (process.threaded) this.#fail(process, new Error("threads@0 was disabled"));
+    }
+  }
+
+  // What a spawn waits for, "count" or "budget", or null when it is admitted.
+  // The budget bounds fan-out (make -j, xargs -P), not a chain: refusing the
+  // one child a process waits for (zig build-exe's cc, cc's wasm-opt) would
+  // stop a build the machine can hold, so a parent with no live child is
+  // admitted under the count alone. The page's own spawns have parent 0.
+  #spawnWait(parent) {
+    if (this.processes.size >= processWorkerLimit) return "count";
+    let committed = 0, fanning = false;
+    for (const process of this.processes.values()) {
+      committed += process.memory?.buffer.byteLength ?? 0;
+      fanning ||= process.parent === parent && !process.retiring;
+    }
+    return committed < processMemoryBudgetBytes || !fanning ? null : "budget";
+  }
+
+  spawn(arguments_, { foreground = false } = {}) {
+    if (this.#spawnWait(0)) throw new Error("Dolly process limit reached");
+    const packet = encodeSpawn(arguments_, foreground ? DOLLY_PROCESS_SPAWN_FOREGROUND : 0);
+    new Uint8Array(
+      this.kernelMemory.buffer,
+      this.mailboxAddress,
+      packet.length,
+    ).set(packet);
+    const pid = this.kernel.dolly_process_spawn_serialized(BigInt(packet.length));
+    if (pid < 0) {
+      const errno = Object.keys(DOLLY_ERRNO).find(name => DOLLY_ERRNO[name] === -pid) ?? `errno ${-pid}`;
+      throw new Error(`cannot start ${arguments_[0]}: ${errno}`);
+    }
+    const completion = new Promise((resolve, reject) => {
+      this.#registerProcess(pid, 0, resolve, reject);
+    });
+    this.#scheduleLaunches();
+    return completion;
+  }
+
+  #registerProcess(pid, parent, resolve = null, reject = null) {
+    const flags = this.kernel.dolly_process_spawn_flags(pid);
+    if (pid <= 0 || this.processes.has(pid) || flags < 0 ||
+        this.kernel.dolly_process_parent(pid) !== parent) {
+      throw new Error(`kernel supplied invalid process ${pid}`);
+    }
+    const process = {
+      pid, parent, resolve, reject, worker: null, gate: null, control: null,
+      memory: null, messageHandler: null, errorHandler: null,
+      messageErrorHandler: null, started: false,
+      failure: null, interactive: (flags & DOLLY_PROCESS_SPAWN_INTERACTIVE) !== 0, retiring: false,
+      interruptTimer: null, deadlineTimer: null, retirementTimer: null, lastSignal: 0,
+      reclamationDeadline: 0, tid: 0, threads: new Map(), threaded: false,
+      execution: null, signalAtStart: 0,
+    };
+    this.processes.set(pid, process);
+    this.#armDeadline(process);
+  }
+
+  #descendantDepth(process, ancestorPid) {
+    let candidate = process;
+    for (let depth = 0; depth < this.processes.size; ++depth) {
+      if (candidate.parent === ancestorPid) return depth + 1;
+      if (candidate.parent === 0) return 0;
+      candidate = this.processes.get(candidate.parent);
+      if (!candidate) return 0;
+    }
+    return 0;
+  }
+
+  #serviceTick() {
+    this.serviceHost();
+    const interrupted = this.kernel.dolly_process_take_interrupt();
+    if (interrupted > 0) this.#interruptForeground(interrupted);
+    for (let pid; (pid = this.kernel.dolly_process_take_alarm()) > 0;) {
+      this.#deliverSignal(this.processes.get(pid), DOLLY_PROCESS_SIGALRM);
+    }
+    this.#deliverRaised();
+    this.serviceDeferred();
+  }
+
+  // What a pseudo-terminal raised for the programs on its slave
+  // (host/pty/dolly-pty-supervisor-0.wat): its interrupt key, resize or hang-up.
+  #deliverRaised() {
+    for (let pid; (pid = this.kernel.dolly_pty_take_signal()) > 0;) {
+      this.#deliverSignal(this.processes.get(pid), this.kernel.dolly_pty_taken_signal());
+    }
+  }
+
+  #interruptForeground(pid) {
+    const process = this.processes.get(pid);
+    if (!process || process.retiring) return;
+    const descendants = [...this.processes.values()].filter(
+      (candidate) => !candidate.retiring && candidate.pid !== pid &&
+        this.#descendantDepth(candidate, pid) !== 0,
+    );
+    // Like a job-control shell, an interactive owner's running commands take
+    // SIGINT in its place; without any it takes SIGINT itself.
+    for (const target of process.interactive && descendants.length ? descendants : [process, ...descendants]) {
+      this.#deliverSignal(target);
+    }
+  }
+
+  #deliverSignal(process, signalNumber = DOLLY_PROCESS_SIGINT) {
+    if (!process || process.retiring || this.processes.get(process.pid) !== process) return false;
+    const result = this.kernel.dolly_process_signal(process.pid, signalNumber);
+    process.lastSignal = signalNumber;
+    // Resize notification is not an interrupt request and must never acquire
+    // a forced-termination deadline, including before program entry.
+    if (signalNumber === DOLLY_PROCESS_SIGWINCH && (result !== 0 || !process.started)) return result === 0;
+    if (signalNumber === DOLLY_PROCESS_SIGKILL || result !== 0 || !process.started) {
+      return this.#forceExit(process.pid, 128 + signalNumber, signalNumber);
+    }
+    const receiver = process.threaded
+      ? [...process.threads.values()].sort((a, b) => a.tid - b.tid)[0] : process;
+    const deferred = this.deferred.get(receiver);
+    if (deferred) {
+      this.#clearDeferred(receiver);
+      this.#signal(receiver, deferred.message.sequence, interruptedSystemCall);
+    }
+    // The old program takes the signal and calls EXEC again, as after any
+    // interrupted call; a resize waits for the new program.
+    if (process.execution?.thread === receiver && signalNumber !== DOLLY_PROCESS_SIGWINCH) {
+      const { message } = process.execution;
+      process.execution = null;
+      this.kernel.dolly_process_exec_refused(process.pid, 0n);
+      this.#signal(receiver, message.sequence, interruptedSystemCall);
+    }
+    if (signalNumber !== DOLLY_PROCESS_SIGWINCH) this.#armInterrupt(process, signalNumber);
+    return true;
+  }
+
+  // A program that does not finish a delivered signal in time is ended by it.
+  #armInterrupt(process, signalNumber) {
+    if (process.interruptTimer !== null) return;
+    process.interruptTimer = setTimeout(() => {
+      process.interruptTimer = null;
+      this.#forceExit(process.pid, 128 + signalNumber, signalNumber);
+    }, interruptGraceMilliseconds);
+  }
+
+  #scheduleLaunches() {
+    this.launchChain = this.launchChain
+      .then(() => this.#launchPending())
+      .catch((error) => {
+        // Only a kernel that cannot name its next launch reaches this point.
+        for (const process of [...this.processes.values()]) this.#fail(process, error);
+      });
+  }
+
+  // The module for the executable the kernel opened for a process: the one
+  // compiled from the same version of its file's bytes, which takes no read,
+  // or one compiled from the bytes, found by their SHA-256 or compiled now.
+  async #compiledImage(pid) {
+    const version = BigInt(this.kernel.dolly_process_image_version(pid));
+    const key = this.compiledVersions.get(version);
+    if (version !== 0n && this.compiledModules.has(key)) {
+      if (this.kernel.dolly_process_image_consumed(pid) !== 0) {
+        throw new Error(`kernel did not release executable ${pid}`);
+      }
+      return this.#cachedModule(key);
+    }
+    const compiled = await this.#compileProcess(this.#takeImage(pid));
+    if (version !== 0n) {
+      this.compiledVersions.delete(version);
+      this.compiledVersions.set(version, compiled.key);
+      if (this.compiledVersions.size > compiledVersionEntries) {
+        this.compiledVersions.delete(this.compiledVersions.keys().next().value);
+      }
+    }
+    return compiled;
+  }
+
+  // A cached module, made the most recently used.
+  #cachedModule(key) {
+    const cached = this.compiledModules.get(key);
+    this.compiledModules.delete(key);
+    this.compiledModules.set(key, cached);
+    return cached;
+  }
+
+  async #compileProcess(bytes) {
+    const digest = hex(await crypto.subtle.digest("SHA-256", bytes));
+    const key = `${bytes.byteLength}:${digest}`;
+    if (this.compiledModules.has(key)) return this.#cachedModule(key);
+
+    const started = performance.now();
+    let noticeShown = false;
+    const notice = setTimeout(() => {
+      noticeShown = true;
+      const mebibytes = (bytes.byteLength / (1024 * 1024)).toFixed(1);
+      this.#writeTerminal(
+        `\r\ndolly: preparing ${mebibytes} MiB WebAssembly executable for this session...\r\n`,
+      );
+    }, compilationNoticeMilliseconds);
+    let module;
+    let memoryRequirements;
+    let processInterface;
+    let threaded;
+    let largeStack;
+    let requirements;
+    let prepared = false;
+    try {
+      const parsed = parseWasmInterface(bytes);
+      memoryRequirements = validateProcessInterface(this.processContract, parsed, DOLLY_PROCESS_ABI_DIGEST);
+      requirements = executableHostRequirements(parsed);
+      checkHostAbi(requirements, this.hostAbi);
+      threaded = validateThreadProfile(parsed, requirements, this.threadContract);
+      largeStack = parsed.customSections.includes("dolly.process.stack");
+      module = await WebAssembly.compile(bytes);
+      processInterface = { imports: parsed.imports, exports: parsed.exports,
+        castEmulationParameters: parsed.castEmulationParameters };
+      prepared = true;
+    } finally {
+      clearTimeout(notice);
+      if (noticeShown) {
+        this.#writeTerminal(
+          prepared
+            ? `dolly: executable ready in ${((performance.now() - started) / 1000).toFixed(1)}s\r\n`
+            : "dolly: executable preparation failed\r\n",
+        );
+      }
+    }
+    const compiled = { key, module, memoryRequirements, processInterface, threaded, largeStack, requirements, byteLength: bytes.byteLength };
+    if (bytes.byteLength <= compiledModuleCacheBytes) {
+      this.compiledModules.set(key, compiled);
+      this.compiledModuleBytes += bytes.byteLength;
+      while (this.compiledModules.size > compiledModuleCacheEntries ||
+             this.compiledModuleBytes > compiledModuleCacheBytes) {
+        const oldestKey = this.compiledModules.keys().next().value;
+        const oldest = this.compiledModules.get(oldestKey);
+        this.compiledModules.delete(oldestKey);
+        this.compiledModuleBytes -= oldest.byteLength;
+      }
+    }
+    return compiled;
+  }
+
+  #writeTerminal(text) {
+    const bytes = encoder.encode(text);
+    const address = this.kernel.malloc(BigInt(Math.max(1, bytes.byteLength)));
+    if (address === 0 || address === 0n) return;
+    try {
+      new Uint8Array(
+        this.kernelMemory.buffer, Number(address), bytes.byteLength,
+      ).set(bytes);
+      this.kernel.dolly_terminal_write_bytes(
+        BigInt(address), BigInt(bytes.byteLength),
+      );
+    } finally {
+      this.kernel.free(BigInt(address));
+    }
+  }
+
+  async #launchPending() {
+    for (let pid; (pid = this.kernel.dolly_process_next_launch()) !== 0;) {
+      const process = this.processes.get(pid);
+      try {
+        if (!process) throw new Error(`kernel supplied unregistered process ${pid}`);
+        const compiled = await this.#compiledImage(pid);
+        if (!this.#canLaunch(process)) continue;
+        const local = this.#admit(compiled);
+        for (let waited = 0; ; waited += reservationRetryMilliseconds) {
+          try {
+            this.#start(process, compiled, local);
+            break;
+          } catch (error) {
+            if (!(error instanceof RangeError) || process.memory || waited >= reservationPatienceMilliseconds) throw error;
+          }
+          await new Promise(resolve => setTimeout(resolve, reservationRetryMilliseconds));
+          if (!this.#canLaunch(process)) break;
+        }
+      } catch (error) {
+        // A failed launch ends only its own process; exiting it in the kernel
+        // also stops next_launch from naming it again.
+        if (process) this.#fail(process, error);
+        else this.kernel.dolly_process_worker_exited(pid, 126, 0);
+      }
+    }
+  }
+
+  // The bytes of the executable the kernel opened for a process, which it then closes.
+  #takeImage(pid) {
+    const read = this.kernel.dolly_process_image_read(pid);
+    if (read !== 0) throw new Error(`cannot read the executable of process ${pid}: ${read}`);
+    const address = Number(this.kernel.dolly_process_image_address(pid));
+    const size = Number(this.kernel.dolly_process_image_size(pid));
+    if (!Number.isSafeInteger(address) || !Number.isSafeInteger(size) ||
+        address <= 0 || size < 8 || address > this.kernelMemory.buffer.byteLength - size) {
+      throw new Error(`kernel supplied an invalid executable for process ${pid}`);
+    }
+    const bytes = new Uint8Array(size);
+    bytes.set(new Uint8Array(this.kernelMemory.buffer, address, size));
+    if (this.kernel.dolly_process_image_consumed(pid) !== 0) {
+      throw new Error(`kernel did not release executable ${pid}`);
+    }
+    return bytes;
+  }
+
+  // Checked at every launch, not only when compiled: nena@0 may have disabled
+  // a module since. The modules served in this executable's own Worker each
+  // hold one Worker's state, such as its function table: one goes with threads
+  // only where it serves every thread. Returns those modules.
+  #admit({ requirements, threaded }) {
+    checkHostAbi(requirements, this.hostAbi);
+    const local = [...requirements.keys()].filter(requirement => this.processModules.has(requirement));
+    const unthreaded = local.filter(requirement => !this.processModules.get(requirement).threads);
+    if (threaded && unthreaded.length) throw new TypeError(`a program using threads@0 cannot use ${unthreaded.join(", ")}`);
+    if (threaded && !this.threadHost) throw new Error("threads@0 is unavailable");
+    return local;
+  }
+
+  #start(process, { module, memoryRequirements, processInterface, threaded, largeStack }, local) {
+    const memory = createProcessMemory(memoryRequirements);
+    process.memory = memory;
+    const gate = new WebAssembly.Instance(this.gateModule, {
+      process: { memory },
+      kernel: { memory: this.kernelMemory },
+    });
+    Object.assign(process, { gate, module, processInterface, threaded, largeStack, local });
+    if (threaded) {
+      const tid = this.kernel.dolly_threads_attach(process.pid);
+      if (tid <= 0) throw new Error(`kernel could not reserve main thread: ${tid}`);
+      process.tid = tid;
+      process.threads.set(tid, process);
+    }
+    this.#launchWorker(process, process);
+  }
+
+  // EXEC: the kernel has read the new program and the old one waits in the
+  // call while it is compiled and admitted. A refusal returns to the old
+  // program with ENOEXEC, after one line on its stderr; past the commit the
+  // old program's Workers go and the process starts again, its pid and
+  // record kept.
+  async #exec(process, thread, message) {
+    const execution = { thread, message };
+    process.execution = execution;
+    let compiled, local;
+    try {
+      compiled = await this.#compiledImage(process.pid);
+      if (process.execution === execution) local = this.#admit(compiled);
+    } catch (error) {
+      if (process.execution !== execution) return;
+      process.execution = null;
+      const line = encoder.encode(`dolly: process ${process.pid} cannot run its new program: ` +
+        `${terminalFailureReason(error)}\n`);
+      new Uint8Array(this.kernelMemory.buffer, this.mailboxAddress, line.length).set(line);
+      this.kernel.dolly_process_exec_refused(process.pid, BigInt(line.length));
+      this.#signal(thread, message.sequence, -BigInt(DOLLY_ERRNO.ENOEXEC));
+      return;
+    }
+    if (process.execution !== execution) return;
+    process.execution = null;
+    const signalAtStart = this.kernel.dolly_process_exec_commit(process.pid);
+    if (signalAtStart < 0) {
+      this.#fail(process, new Error(`kernel rejected process ${process.pid} exec: ${signalAtStart}`));
+      return;
+    }
+    // The old program's memory goes with its Workers. Termination has no
+    // completion event: a large interactive one gets the time it gets before
+    // a parent may start its replacement (#reclamationDeadline).
+    const delay = this.#reclamationDeadline(process) - performance.now();
+    if (process.interruptTimer !== null) clearTimeout(process.interruptTimer);
+    process.interruptTimer = null;
+    this.#disposeWorker(process);
+    Object.assign(process, { started: false, threaded: false, tid: 0, threads: new Map(), signalAtStart });
+    // Its descriptors with CLOEXEC are closed: a reader of their pipes goes on now.
+    this.#deliverRaised();
+    if (this.kernel.dolly_process_take_wakeup()) this.serviceDeferred();
+    const start = () => {
+      if (!this.#canLaunch(process)) return;
+      try { this.#start(process, compiled, local); } catch (error) { this.#fail(process, error); }
+    };
+    if (delay > 0) setTimeout(start, delay);
+    else start();
+  }
+
+  #launchWorker(process, thread, argument = undefined) {
+    const { pid, module, memory, processInterface, threaded, local } = process;
+    const control = new SharedArrayBuffer(16);
+    const name = `dolly-process-${pid}-thread-${thread.tid}`;
+    const worker = threaded ? this.threadHost.create(pid, this.workerUrl, name)
+      : new Worker(this.workerUrl, { type: "module", name });
+    if (!worker) throw new Error("thread Worker capacity exhausted");
+    thread.worker = worker;
+    thread.control = new Int32Array(control);
+    thread.messageHandler = event => this.#message(process, event.data, thread);
+    thread.errorHandler = event => this.#fail(process, new Error(event.message || `${name} failed`));
+    thread.messageErrorHandler = () => this.#fail(process, new Error(`${name} message could not be decoded`));
+    worker.addEventListener("message", thread.messageHandler);
+    worker.addEventListener("error", thread.errorHandler, { once: true });
+    worker.addEventListener("messageerror", thread.messageErrorHandler, { once: true });
+    // local: the modules this executable records that are served in its own
+    // Worker (host/dso), each as the bundle it imports and its configuration.
+    worker.postMessage({ type: "configure", pid, tid: thread.tid, argument, threaded, module, memory, control,
+      promisingEntry: this.promisingEntry && process.largeStack, stackDepths: this.stackDepths,
+      clockOrigin: performance.timeOrigin, processInterface, local: local.map(requirement => this.processModules.get(requirement)) });
+  }
+
+  #canLaunch(process) {
+    if (this.processes.get(process.pid) !== process || process.retiring) return false;
+    // An ancestor's EXIT can reach the kernel before its Worker posts finished.
+    if (this.kernel.dolly_process_exited(process.pid) !== 0) {
+      this.#retire(process);
+      return false;
+    }
+    return true;
+  }
+
+  #signal(process, sequence, result) {
+    const encoded = BigInt.asUintN(64, result);
+    Atomics.store(process.control, 2, Number(encoded & 0xffffffffn));
+    Atomics.store(process.control, 3, Number((encoded >> 32n) & 0xffffffffn));
+    Atomics.store(process.control, 1, sequence);
+    Atomics.notify(process.control, 1);
+  }
+
+  #armDeadline(process) {
+    const remaining = this.kernel.dolly_process_deadline_remaining(process.pid);
+    if (remaining >= 0) {
+      process.deadlineTimer = setTimeout(() => this.#endTree(process.pid, 124), Math.ceil(remaining));
+    }
+  }
+
+  #clearTimers(process) {
+    if (process.interruptTimer !== null) clearTimeout(process.interruptTimer);
+    if (process.deadlineTimer !== null) clearTimeout(process.deadlineTimer);
+    if (process.retirementTimer !== null) clearTimeout(process.retirementTimer);
+    process.interruptTimer = null;
+    process.deadlineTimer = null;
+    process.retirementTimer = null;
+  }
+
+  #clearDeferred(thread) {
+    const pending = this.deferred.get(thread);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.deferred.delete(thread);
+  }
+
+  #syscall(process, message, retry = false, thread = process) {
+    const refusedSince = this.deferred.get(thread)?.refusedSince;
+    this.#clearDeferred(thread);
+    const values = [
+      message.sequence,
+      message.operation,
+      message.requestAddress,
+      message.requestSize,
+      message.responseAddress,
+      message.responseCapacity,
+    ];
+    if (message.pid !== process.pid || message.tid !== thread.tid ||
+        values.some((value) => !Number.isSafeInteger(value) || value < 0) ||
+        message.requestSize > packetLimit || message.responseCapacity > packetLimit ||
+        Atomics.load(thread.control, 0) !== message.sequence ||
+        Atomics.load(thread.control, 1) === message.sequence) {
+      this.#fail(process, new Error(`process ${process.pid} sent an invalid syscall`));
+      return;
+    }
+    let result;
+    let signalDelivery;
+    let threadArgument;
+    try {
+      process.gate.exports.request(
+        BigInt(message.requestAddress),
+        BigInt(this.mailboxAddress),
+        BigInt(message.requestSize),
+      );
+      if (message.operation === DOLLY_THREAD_SPAWN && message.requestSize === 8)
+        threadArgument = new DataView(this.kernelMemory.buffer, this.mailboxAddress, 8).getBigUint64(0, true);
+      const args = [process.pid, message.operation, BigInt(message.requestSize), BigInt(message.responseCapacity)];
+      if (process.threaded) args.splice(1, 0, thread.tid);
+      const waiting = message.operation === DOLLY_PROCESS_SPAWN ? this.#spawnWait(process.pid) : null;
+      const now = performance.now(), since = waiting === "count" ? refusedSince ?? now : undefined;
+      if (waiting === "budget" || waiting === "count" && now - since < reservationPatienceMilliseconds) {
+        this.deferred.set(thread, { process, thread, message, timer: null, refusedSince: since });
+        return;
+      }
+      const exhausted = waiting === "count" ||
+        process.threaded && message.operation === DOLLY_THREAD_SPAWN && !this.threadHost?.available(process.pid);
+      // Firefox can enter a direct Wasm call twice. Use the generic call path
+      // so a completed syscall is never replayed against its response packet.
+      result = exhausted ? -BigInt(DOLLY_ERRNO.EAGAIN)
+        : Reflect.apply(process.threaded ? this.kernel.dolly_threads_dispatch : this.kernel.dolly_process_dispatch,
+          this.kernel, args);
+      if (result === deferredResult) {
+        const deferred = { process, thread, message, timer: null };
+        this.deferred.set(thread, deferred);
+        const remaining = this.kernel.dolly_process_deferred_milliseconds();
+        if (remaining >= 0 && remaining <= 16) {
+          deferred.timer = setTimeout(() => {
+            if (this.deferred.get(thread) === deferred) this.#syscall(process, message, true, thread);
+          }, Math.ceil(remaining));
+        }
+        return;
+      }
+      if (message.operation === DOLLY_PROCESS_EXEC && message.requestSize !== 0 && result === 0n) {
+        this.#exec(process, thread, message).catch(error => this.#fail(process, error));
+        return;
+      }
+      if (message.operation === DOLLY_PROCESS_EXIT && result === 0n) {
+        // The kernel reclaimed every thread. Stop the others now; the caller
+        // unwinds and reports "finished" like a single-threaded process.
+        for (const other of [...process.threads.values()]) {
+          if (other !== thread) this.#disposeThread(process, other);
+        }
+      } else if (result >= 0n) {
+        if (result > BigInt(message.responseCapacity)) {
+          throw new Error(`kernel overfilled process ${process.pid} response`);
+        }
+        process.gate.exports.response(
+          BigInt(this.mailboxAddress),
+          BigInt(message.responseAddress),
+          result,
+        );
+        if (message.operation === DOLLY_THREAD_SPAWN) {
+          if (result !== 8n || threadArgument === undefined) throw new Error("invalid kernel thread response");
+          const response = new DataView(this.kernelMemory.buffer, this.mailboxAddress, 8);
+          const tid = response.getUint32(0, true);
+          if (!tid || tid > 0x7fffffff || response.getUint32(4, true) || process.threads.has(tid))
+            throw new Error("invalid kernel thread identity");
+          const child = { tid, worker: null, control: null };
+          process.threads.set(tid, child);
+          try { this.#launchWorker(process, child, threadArgument); }
+          catch (error) {
+            this.#disposeThread(process, child);
+            this.kernel.dolly_threads_unstarted(process.pid, tid);
+            result = -BigInt(DOLLY_ERRNO.EAGAIN);
+          }
+        }
+        if (message.operation === DOLLY_PROCESS_SPAWN) {
+          if (result !== 8n) throw new Error("invalid kernel spawn response");
+          const response = new DataView(this.kernelMemory.buffer, this.mailboxAddress, 8);
+          const pid = response.getUint32(0, true);
+          if (pid === 0 || pid > 0x7fffffff || response.getUint32(4, true) !== 0) {
+            throw new Error("invalid kernel spawn identity");
+          }
+          this.#registerProcess(pid, process.pid);
+        }
+        if (message.operation === DOLLY_PROCESS_SIGNAL) {
+          if (result !== 8n) throw new Error("invalid kernel signal response");
+          const response = new DataView(this.kernelMemory.buffer, this.mailboxAddress, 8);
+          signalDelivery = { pid: response.getUint32(0, true), signal: response.getUint32(4, true) };
+          if (signalDelivery.pid === 0 || signalDelivery.pid > 0x7fffffff) {
+            throw new Error("invalid kernel signal target");
+          }
+        }
+      }
+    } catch (error) {
+      this.#fail(process, error);
+      return;
+    }
+    this.#signal(thread, message.sequence, result);
+    if (message.operation === DOLLY_PROCESS_SIGNAL_ACKNOWLEDGE && result === 4n &&
+        new DataView(this.kernelMemory.buffer, this.mailboxAddress, 4).getInt32(0, true) === 0 &&
+        process.interruptTimer !== null) {
+      clearTimeout(process.interruptTimer);
+      process.interruptTimer = null;
+    }
+    if (signalDelivery?.signal) {
+      this.#deliverSignal(this.processes.get(signalDelivery.pid), signalDelivery.signal);
+    }
+    this.#deliverRaised();
+    // A spawn that waited for admission is launched like any other.
+    if (!retry || message.operation === DOLLY_PROCESS_SPAWN) this.#scheduleLaunches();
+    if (retry) return;
+    // A pipe write or close can complete another thread's blocked read or poll,
+    // such as an async runtime's waker: retry now, not at the next tick.
+    if (this.kernel.dolly_process_take_wakeup()) this.serviceDeferred();
+  }
+
+  #message(process, message, thread = process) {
+    if (this.processes.get(process.pid) !== process || process.retiring ||
+        (process.threaded && process.threads.get(thread.tid) !== thread)) return;
+    if (message?.pid !== process.pid || message?.tid !== thread.tid) {
+      this.#fail(process, new Error(`process ${process.pid} sent a mismatched identity`));
+    } else if (message.type === "started") {
+      if (thread !== process) return;
+      if (this.kernel.dolly_process_worker_started(process.pid) !== 0) {
+        this.#fail(process, new Error(`kernel rejected process ${process.pid} start`));
+      } else {
+        process.started = true;
+        // A signal pending across EXEC is the new program's to answer.
+        if (process.signalAtStart) this.#armInterrupt(process, process.signalAtStart);
+        process.signalAtStart = 0;
+      }
+    } else if (message.type === "syscall") {
+      this.#syscall(process, message, false, thread);
+    } else if (message.type === "thread-finished") {
+      if (!process.threaded || typeof message.result !== "bigint") {
+        this.#fail(process, new Error("invalid thread completion")); return;
+      }
+      // The trusted Worker wrapper has unwound Wasm and will never re-enter it.
+      // Remove its event handlers/resources before making its stack joinable.
+      this.#disposeThread(process, thread);
+      const last = this.kernel.dolly_threads_retired(process.pid, thread.tid, message.result);
+      if (last < 0) this.#fail(process, new Error("kernel rejected thread retirement"));
+      else if (last) this.#forceExit(process.pid, 0);
+      else this.serviceDeferred();
+    } else if (message.type === "finished") {
+      // _start returned (status zero), or EXIT has already recorded the status.
+      this.kernel.dolly_process_worker_exited(process.pid, 0, 0);
+      this.#retire(process);
+    } else if (message.type === "failed") {
+      const detail = message.stack ? `${message.message}\n${message.stack}` : message.message;
+      this.#fail(process, new Error(detail || `process ${process.pid} failed`));
+    } else {
+      this.#fail(process, new Error(`process ${process.pid} sent an unknown message`));
+    }
+  }
+
+  #reclamationDeadline(process) {
+    return Math.max(process.reclamationDeadline,
+      process.interactive && (process.memory?.buffer.byteLength ?? 0) >= largeInteractiveProcessBytes
+        ? performance.now() + workerReclamationMilliseconds : 0);
+  }
+
+  #retire(process) {
+    process.retiring = true;
+    // A process a signal ends passes it to its descendants, as a signal to its
+    // process group would: Dolly has no groups, so the command of slop -c is
+    // the shell's child unless it is exec'd. Each answers it as it handles it.
+    // A descendant that has it already, as Ctrl-C gives it to the whole
+    // foreground tree, is not given it twice.
+    const signal = this.kernel.dolly_process_exit_signal(process.pid);
+    if (signal !== 0) {
+      for (const descendant of [...this.processes.values()]) {
+        if (descendant.lastSignal !== signal && this.#descendantDepth(descendant, process.pid) !== 0) {
+          this.#deliverSignal(descendant, signal);
+        }
+      }
+    }
+    // Its children live on: the kernel has given them parent 0.
+    for (const child of this.processes.values()) if (child.parent === process.pid) child.parent = 0;
+    process.reclamationDeadline = this.#reclamationDeadline(process);
+    this.#stop(process);
+    // The kernel has closed the process's descriptors: a reader of its pipe or
+    // a waiter for its lock proceeds now, not at the next tick.
+    this.#deliverRaised();
+    if (this.kernel.dolly_process_take_wakeup()) this.serviceDeferred();
+    const retired = () => {
+      process.retirementTimer = null;
+      if (this.processes.get(process.pid) !== process) return;
+      this.#acknowledgeRetirement(process);
+      if (process.resolve) this.#finish(process);
+      else {
+        // An orphan, whose parent may have ended after this one did: nobody
+        // waits for it, so it is reaped, as init would.
+        if (this.kernel.dolly_process_parent(process.pid) === 0) this.kernel.dolly_process_collect(process.pid);
+        this.serviceDeferred();
+      }
+    };
+    // Worker.terminate() has no completion event. Drop all references, then allow
+    // one bounded reclamation window for large interactive memories before WAIT
+    // can let a surviving parent launch their replacement.
+    const delay = process.reclamationDeadline - performance.now();
+    if (delay > 0) process.retirementTimer = setTimeout(retired, delay);
+    else retired();
+  }
+
+  #acknowledgeRetirement(process) {
+    const result = this.kernel.dolly_process_worker_retired(process.pid);
+    if (result !== 0) {
+      throw new Error(`kernel rejected process ${process.pid} retirement: ${result}`);
+    }
+    this.processes.delete(process.pid);
+  }
+
+  // Resolves how a root process ended, as the kernel recorded it: whoever ended
+  // it (the program, the supervisor or the kernel itself), the wait record and
+  // this are one fact.
+  #finish(process) {
+    const ending = this.kernel.dolly_process_collect(process.pid);
+    const status = ending < 0 ? ending : ending & 255;
+    // The modules see what the process left, such as its last terminal
+    // output, before anyone learns that it ended.
+    this.serviceHost();
+    if (process.failure) {
+      process.failure.status = status;
+      process.reject(process.failure);
+    } else if (!Number.isInteger(ending) || ending < 0) {
+      process.reject(new Error(`kernel returned invalid status for process ${process.pid}`));
+    } else {
+      process.resolve({ status, signal: ending >> 8 });
+    }
+  }
+
+  // A refusal or failure is reported to the program that asked: one line on
+  // the process's own stderr, then status 126.
+  #fail(process, error) {
+    if (process.retiring || this.processes.get(process.pid) !== process) return;
+    const detail = error instanceof Error ? error : new Error(String(error));
+    const reason = terminalFailureReason(detail);
+    const line = encoder.encode(`dolly: process ${process.pid} ` +
+      `${process.started ? "failed" : "was refused"}: ${reason}\n`);
+    new Uint8Array(this.kernelMemory.buffer, this.mailboxAddress, line.length).set(line);
+    this.kernel.dolly_process_worker_failed(process.pid, BigInt(line.length));
+    detail.message = `Dolly process ${process.pid} failed: ${detail.message}`;
+    process.failure = Object.assign(detail, { reason });
+    if (!process.reject) console.error(detail.stack ?? detail.message);
+    this.#retire(process);
+  }
+
+  #forceExit(pid, status, signalNumber = 0) {
+    const process = this.processes.get(pid);
+    if (!process) return false;
+    if (process.retiring) return true;
+    this.kernel.dolly_process_worker_exited(pid, status, signalNumber);
+    this.#retire(process);
+    return true;
+  }
+
+  // A timed command's deadline ends its tree, deepest first, as timeout(1)
+  // signals the command's process group.
+  #endTree(pid, status) {
+    const descendants = [...this.processes.values()]
+      .map((process) => ({ process, depth: this.#descendantDepth(process, pid) }))
+      .filter(({ depth }) => depth !== 0)
+      .sort((left, right) => right.depth - left.depth)
+      .map(({ process }) => process);
+    for (const descendant of descendants) {
+      this.#forceExit(descendant.pid, 128 + DOLLY_PROCESS_SIGKILL, DOLLY_PROCESS_SIGKILL);
+    }
+    this.#forceExit(pid, status);
+  }
+
+  #disposeThread(process, thread) {
+    this.#clearDeferred(thread);
+    if (thread.worker) {
+      thread.worker.removeEventListener("message", thread.messageHandler);
+      thread.worker.removeEventListener("error", thread.errorHandler);
+      thread.worker.removeEventListener("messageerror", thread.messageErrorHandler);
+      // Chrome keeps a Worker terminated inside Atomics.wait, and its memory,
+      // for two seconds. Answered with the deferred result, which no program
+      // is handed, a waiting Worker leaves Wasm and closes itself.
+      if (thread.control) this.#signal(thread, Atomics.load(thread.control, 0), deferredResult);
+      // threads@0 disabled since has already terminated its Workers.
+      if (process.threaded && this.threadHost) this.threadHost.release(thread.worker);
+      else thread.worker.terminate();
+    }
+    thread.worker = null;
+    thread.control = null;
+    thread.messageHandler = thread.errorHandler = thread.messageErrorHandler = null;
+    process.threads.delete(thread.tid);
+  }
+
+  // Ends a process's Workers and timers; the kernel keeps its record until collected.
+  #stop(process) {
+    process.retiring = true;
+    process.execution = null;
+    this.#clearTimers(process);
+    this.#disposeWorker(process);
+  }
+
+  #disposeWorker(process) {
+    for (const thread of [...process.threads.values()]) this.#disposeThread(process, thread);
+    this.#disposeThread(process, process);
+    process.gate = process.memory = process.module = process.processInterface = null;
+  }
+
+  serviceDeferred() {
+    for (const deferred of [...this.deferred.values()]) {
+      const { process, thread, message } = deferred;
+      // An earlier retry in this pass may have ended this thread: a completed
+      // EXIT stops the other threads of its process.
+      if (this.deferred.get(thread) !== deferred) continue;
+      if (this.processes.get(process.pid) === process && !process.retiring) {
+        this.#syscall(process, message, true, thread);
+      } else this.#clearDeferred(thread);
+    }
+  }
+
+  dispose() {
+    clearInterval(this.serviceTimer);
+    for (const process of this.processes.values()) {
+      this.#stop(process);
+      process.reject?.(new Error("Dolly runtime closed"));
+    }
+    this.processes.clear();
+    this.deferred.clear();
+    this.compiledModules.clear();
+    this.compiledModuleBytes = 0;
+    this.compiledVersions.clear();
+    this.releaseWorkerSource?.();
+    this.releaseWorkerSource = undefined;
+  }
+}