@volter/browser-wali 0.1.5 → 0.1.7

package/dist/runtime.js

@@ -1,24 +1,31 @@
+import { createWaliSignalState, defaultTerminates, WaliSignals, WaliSignalHost } from "./signals.js";
+import { createConfinedWaliSpawnImport } from "./spawn-policy.js";
+import { normalizeProcessFilesystemPolicy, intersectProcessFilesystemPolicies } from "@volter/browser-runtime/browser-process-filesystem-policy.js";
 import { assertWaliModule, compileWaliModule, inspectWaliModule } from "./inspect.js";
+import { WALI_ENOSYS, waliUnimplementedTraps } from "./capabilities.js";
+import { WaliDescriptionRegistry, WaliProcessDescriptorTable } from "./descriptors.js";
 import { createStdioAliasRegistry, WaliFileDescriptorTable } from "./filesystem.js";
 import { createWaliAllocatorControl, createWaliSharedMmapRegistry, WaliMemoryManager } from "./memory.js";
 import { WaliPthreadProcessExit, WaliSystemHost } from "./system.js";
 import { WaliEventHost } from "./events.js";
-import { createImportedMemory } from "./module-layout.js";
+import { createImportedMemory, findImportedMemory } from "./module-layout.js";
 import { WaliThreadPool } from "./threads.js";
 import { WaliLocalSocketHost } from "./local-sockets.js";
 import { WaliNetworkCoordinator, WaliNetworkHost } from "./network.js";
 import { BufferedWaliStdin, SharedWaliStdinReader } from "./stdin.js";
-import { WaliFilesystemCoordinator, WaliSharedFileDescriptorHost } from "./filesystem-remote.js";
+import { WaliFilesystemClient, WaliFilesystemCoordinator, WaliSharedFileDescriptorHost } from "./filesystem-remote.js";
 import { createWaliSharedPipeState, WaliSharedPipeHost } from "./shared-pipes.js";
+import { createWaliCodecImports, WaliCodecClient, WaliCodecCoordinator } from "./codec-remote.js";
+import { createSelectImport, SELECT_SCRATCH_BYTES } from "./select.js";
 import { applyProcessFilesystemPatch, BROWSER_PROCESS_RESPONSE_BYTES, closeSharedPipe, decodeProcessSnapshot, retainSharedPipe, } from "./process-bridge.js";
 import { BrowserFileLockClient } from "@volter/browser-runtime/browser-file-locks.js";
 import { BrowserFileCoherenceClient } from "@volter/browser-runtime/browser-file-coherence.js";
 import { WaliCoherentFileLockClient } from "./coherent-file-locks.js";
+import { monotonicMilliseconds } from "./monotonic-clock.js";
 const EBADF = 9n;
 const EINVAL = 22n;
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
-const WNOHANG = 1;
 export class UnsupportedWaliImportError extends Error {
     imports;
     constructor(imports) {
@@ -27,6 +34,45 @@ export class UnsupportedWaliImportError extends Error {
         this.name = "UnsupportedWaliImportError";
     }
 }
+/**
+ * The handler for an import this runtime does not implement.
+ *
+ * `capabilities.ts` holds the rule and the evidence: a `SYS_*` name answers
+ * `-ENOSYS` the way a kernel does, and the four names in
+ * `WALI_TRAPPING_IMPORTS` still take the process down because an errno there
+ * cannot reach a caller that can act on it. `thread-worker.ts` does the
+ * identical thing for every pthread.
+ *
+ * WHERE THE ONE-SHOT NOTICE LANDS. This runtime runs inside
+ * `worker-program-worker.ts`, a nested worker, so `console.error` alone reaches
+ * that worker's devtools console and NOTHING ELSE -- measured 2026-09-19
+ * through the vgai editor, where an `os.fork()` answered -ENOSYS left
+ * `vgai console`, the product's own unresolved-console door, silent, because
+ * the editor's collector reports only what THE PAGE sees. A trap reached that
+ * door through the worker's `{type:"result", error}` message; an answered
+ * syscall had nothing to travel on. `onDiagnostic` is that something: the
+ * runtime's own word to its host, carried by `{type:"diagnostic"}` on
+ * `WaliWorkerResponse` and by the pthread output ports, landing on
+ * `BrowserProcessRunOptions.onDiagnostic`. It is deliberately NOT stdout: a
+ * kernel does not write to your streams, and a host that parses the program's
+ * output would have to un-parse this line again.
+ */
+function unimplementedImport(name, report) {
+    if (waliUnimplementedTraps(name))
+        return () => { throw new UnsupportedWaliImportError([name]); };
+    let reported = false;
+    return () => {
+        if (!reported) {
+            reported = true;
+            const notice = `[WALI] ${name} is not implemented; answering -ENOSYS (38) as a kernel would.`;
+            console.error(notice);
+            report?.(notice);
+        }
+        return WALI_ENOSYS;
+    };
+}
+class WaliProcessReplaced extends Error {
+}
 class WaliProcessExit extends Error {
     code;
     constructor(code) {
@@ -36,6 +82,9 @@ class WaliProcessExit extends Error {
 }
 export class BrowserWaliRuntime {
     async run(source, options = {}) {
+        const inheritedFilesystemPolicy = options.filesystemPolicy === undefined ? undefined
+            : normalizeProcessFilesystemPolicy(options.filesystemPolicy);
+        const filesystemPolicy = inheritedFilesystemPolicy;
         const module = await compileWaliModule(source);
         const descriptors = inspectWaliModule(module);
         assertWaliModule(descriptors);
@@ -48,10 +97,17 @@ export class BrowserWaliRuntime {
         const argv = options.argv?.length ? [...options.argv] : ["wali-program"];
         const argvBytes = argv.map((argument) => encoder.encode(`${argument}\0`));
         const pid = normalizePid(options.pid);
-        const signalActions = new Map();
+        // Where a run's time goes: setup, then the guest, and within it each
+        // syscall by name. A run longer than PROFILE_AFTER_MS prints it once.
+        const runStartedAt = performance.now();
+        let startEnteredAt = runStartedAt;
+        const syscallTime = new Map();
+        const signalState = options.signalState ?? createWaliSignalState();
         let instance;
         let threadPool;
         let networkCoordinator;
+        let codecCoordinator;
+        let codecClient;
         let filesystemCoordinator;
         const importedMemory = createImportedMemory(source, options.memory);
         const stdioAliasRegistry = createStdioAliasRegistry();
@@ -61,7 +117,8 @@ export class BrowserWaliRuntime {
         // Word 1: first failing worker slot. Word 2: process exit code.
         const pthreadFatal = new Int32Array(new SharedArrayBuffer(3 * Int32Array.BYTES_PER_ELEMENT));
         Atomics.store(pthreadFatal, 1, -1);
-        const sharedPipeState = createWaliSharedPipeState();
+        const localDescriptors = new WaliProcessDescriptorTable(new WaliDescriptionRegistry());
+        const sharedPipeState = options.descriptorTable?.sharedPipes ?? createWaliSharedPipeState(localDescriptors);
         const memory = () => {
             if (importedMemory)
                 return importedMemory;
@@ -94,18 +151,70 @@ export class BrowserWaliRuntime {
             }
             return BigInt(value.byteLength);
         };
-        const exit = (status) => { throw new WaliProcessExit(status & 0xff); };
+        /**
+         * THE MAIN THREAD ENDING THE PROCESS SAYS SO, the same way a pthread does.
+         *
+         * `thread-worker.ts`'s `SYS_exit_group` already names the WORKER that ends
+         * a process, because a bare "exited 0" reads as an orderly shutdown and is
+         * the most misleading answer this runtime can give. This is the other half:
+         * without it, the ABSENCE of the worker's notice is the only evidence that
+         * the main thread was the one that exited, which is reasoning from silence.
+         *
+         * MEASURED 2026-09-19 (WS-W): headless Blender ended mid-call on the WALI
+         * skew and the worker notice did NOT fire, so the exit came through here --
+         * a fact that took a second run to establish and that this line states
+         * directly. Which syscall and which status are both part of the answer:
+         * `SYS_exit` from the main thread and `SYS_exit_group` mean different
+         * things about who decided.
+         */
+        const exit = (status, name = "SYS_exit_group") => {
+            const notice = `[WALI] ${name}(${status & 0xff}) on the MAIN thread -- the process is ending here,`
+                + ` not in a pthread. If the program did not ask to exit, this is the caller to find.`;
+            console.error(notice);
+            options.onDiagnostic?.(notice);
+            throw new WaliProcessExit(status & 0xff);
+        };
+        const signalSelf = (signal) => {
+            if (signal < 0 || signal > 64)
+                return -22n;
+            if (signal === 0)
+                return 0n;
+            // blocked, it stays pending until the mask admits it (raise queues only for a handler)
+            if (signal !== 9 && (signalHost.mask & (1n << BigInt(signal - 1))) !== 0n) {
+                new WaliSignals(signalState).raise(signal);
+                return 0n;
+            }
+            const disposition = signal === 9 || signal === 19 ? "default" : new WaliSignals(signalState).raise(signal);
+            if (disposition === "default" && defaultTerminates(signal))
+                exit(128 + signal, `signal ${signal}`);
+            return 0n;
+        };
         const executablePath = options.executablePath
             ?? (argv[0].startsWith("/") ? argv[0] : `/usr/bin/${argv[0]}`);
         const threaded = waliDescriptors.some((descriptor) => descriptor.name === "__wasm_thread_spawn");
-        const mmapCursor = createWaliAllocatorControl();
+        // A module that imports none of the calls that make a child never has
+        // one: it needs neither the filesystem worker that shares descriptors
+        // with children nor the network worker that carries their pipes, and
+        // starting those was most of a small program's setup (ADR-0042).
+        const makesChildren = waliDescriptors.some((descriptor) => CHILD_PROCESS_SYSCALLS.has(descriptor.name));
+        const childDoor = makesChildren ? options.browserProcess : undefined;
+        const mmapCursor = options.forkState?.allocator ?? createWaliAllocatorControl();
         const sharedMmapRegistry = createWaliSharedMmapRegistry();
-        if (threaded && options.filesystem?.toSnapshot && options.filesystem.replaceSnapshot) {
+        const inheritedDescriptors = options.descriptorTable ? new WaliFilesystemClient(options.descriptorTable) : undefined;
+        if (inheritedDescriptors && importedMemory)
+            inheritedDescriptors.attachMemory(importedMemory);
+        if (!inheritedDescriptors && (threaded || childDoor) && options.filesystem?.toSnapshot && options.filesystem.replaceSnapshot) {
             if (!importedMemory) {
                 throw new Error("A threaded WALI module must import its shared process memory.");
             }
-            filesystemCoordinator = await WaliFilesystemCoordinator.create(options.filesystem.toSnapshot(), {
+            // A filesystem worker over the same store is handed only what differs
+            // from it, not the store's whole index again (ADR-0042).
+            const overlay = options.store ? options.filesystem.toStoreOverlaySnapshot?.() : undefined;
+            filesystemCoordinator = await WaliFilesystemCoordinator.create(overlay ?? options.filesystem.toSnapshot(), {
+                ...(options.store ? { store: options.store } : {}),
                 memory: importedMemory,
+                sharedPipes: sharedPipeState,
+                ...(filesystemPolicy ? { filesystemPolicy } : {}),
                 cwd: options.cwd ?? "/",
                 executablePath,
                 pid,
@@ -114,13 +223,18 @@ export class BrowserWaliRuntime {
                 ...(options.fileCoherence ? { fileCoherence: options.fileCoherence } : {}),
             });
         }
-        const runtimeFilesystem = filesystemCoordinator?.filesystem() ?? options.filesystem;
+        if (filesystemPolicy && threaded && !filesystemCoordinator && !inheritedDescriptors)
+            throw new Error("Confined WALI threads require the shared filesystem owner.");
+        const runtimeFilesystem = inheritedDescriptors ?? filesystemCoordinator?.filesystem() ?? options.filesystem;
         const syncFilesystem = () => {
             if (filesystemCoordinator && options.filesystem?.replaceSnapshot) {
                 options.filesystem.replaceSnapshot(filesystemCoordinator.snapshot());
             }
         };
         const fileDescriptors = new WaliFileDescriptorTable({
+            ...((inheritedDescriptors || filesystemCoordinator) ? { descriptorState: sharedPipeState }
+                : { descriptors: localDescriptors }),
+            ...(filesystemPolicy ? { filesystemPolicy } : {}),
             ...(runtimeFilesystem ? { filesystem: runtimeFilesystem } : {}),
             cwd: options.cwd ?? "/",
             stdin,
@@ -138,17 +252,25 @@ export class BrowserWaliRuntime {
             ...(filesystemCoordinator ? { specialDescriptorMinimum: 10_000, descriptorMaximum: 19_999 } : {}),
         });
         const environmentFile = fileDescriptors.writeEnvironmentFile(options.env ?? {}, pid);
-        const sharedFileHost = filesystemCoordinator
-            ? new WaliSharedFileDescriptorHost(filesystemCoordinator.filesystem(), stdioAliasRegistry) : undefined;
+        const sharedFileClient = inheritedDescriptors ?? filesystemCoordinator?.filesystem();
+        const sharedFileHost = sharedFileClient
+            ? new WaliSharedFileDescriptorHost(sharedFileClient, stdioAliasRegistry, sharedPipeState) : undefined;
         const memoryManager = new WaliMemoryManager(memory, (fd, offset, length) => sharedFileHost?.readForMapping(fd, offset, length)
             ?? fileDescriptors.readForMapping(fd, offset, length), mmapCursor, (fd) => sharedFileHost?.mappingPath(fd) ?? fileDescriptors.mappingPath(fd), (path, offset, value) => sharedFileHost?.writeForMapping(path, offset, value)
-            ?? fileDescriptors.writeForMapping(path, offset, value), sharedMmapRegistry);
-        const systemHost = new WaliSystemHost(memory, pid, stdin, pthreadFatal);
-        if (options.network) {
-            networkCoordinator = await WaliNetworkCoordinator.create(options.network, sharedPipeState, stdin instanceof SharedWaliStdinReader ? stdin.buffer : undefined, stdioAliasRegistry.buffer);
+            ?? fileDescriptors.writeForMapping(path, offset, value), sharedMmapRegistry, options.onDiagnostic);
+        const signalHost = new WaliSignalHost(new WaliSignals(signalState), memory, () => instance?.exports.__indirect_function_table, () => Number(memoryManager.imports().SYS_mmap(0, 4096, 3, 0x22, -1, 0)));
+        // The same number the thread pool is built with below, so the CPU count
+        // the guest is told about can never exceed the workers that exist.
+        const threadPoolSize = options.threadPoolSize ?? 18;
+        const systemHost = new WaliSystemHost(memory, pid, stdin, pthreadFatal, options.terminal, threadPoolSize);
+        // One shot: a program that exhausts the pool usually keeps asking, and the
+        // hundredth copy of the notice buries the first.
+        let threadPoolExhaustionReported = false;
+        if (options.network || childDoor) {
+            networkCoordinator = await WaliNetworkCoordinator.create(options.network, sharedPipeState, stdin instanceof SharedWaliStdinReader ? stdin.buffer : undefined, stdioAliasRegistry.buffer, signalState);
         }
-        const networkHost = networkCoordinator ? new WaliNetworkHost(memory, networkCoordinator.createChannel()) : undefined;
-        const sharedPipeHost = new WaliSharedPipeHost(memory, sharedPipeState);
+        const networkHost = networkCoordinator ? new WaliNetworkHost(memory, networkCoordinator.createChannel(), signalHost) : undefined;
+        const sharedPipeHost = new WaliSharedPipeHost(memory, sharedPipeState, sharedFileClient ? undefined : localDescriptors, sharedFileClient);
         const eventHost = new WaliEventHost(memory, fileDescriptors, (fd, events) => sharedPipeHost.pollDescriptor(fd, events) ?? (networkHost?.isNetworkFd(fd)
             ? networkHost.pollFd(fd, events) : undefined));
         const localSocketHost = new WaliLocalSocketHost(memory, fileDescriptors);
@@ -157,9 +279,13 @@ export class BrowserWaliRuntime {
         const pipeImports = sharedPipeHost.imports({ ...localSocketHost.imports(), ...fileImports });
         const eventImports = eventHost.imports();
         const systemImports = systemHost.imports();
-        const childProcesses = new Map();
-        const nextChildPid = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
-        Atomics.store(nextChildPid, 0, Math.max(pid + 1, 10_000));
+        // A forked runtime learns its parent from the fork state; one the spawn
+        // door exec'd into an existing process is told; a first process's parent
+        // is init.
+        const parentProcessId = options.forkState?.parentPid ?? options.parentPid ?? 1;
+        const nextChildPid = new Int32Array(options.childPidAllocator ?? new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+        if (!options.childPidAllocator)
+            Atomics.store(nextChildPid, 0, Math.max(pid + 1, 10_000));
         const readCString = (pointer) => {
             if (!Number.isSafeInteger(pointer) || pointer <= 0 || pointer >= bytes().byteLength) {
                 throw new WebAssembly.RuntimeError("WALI process string pointer is out of bounds.");
@@ -188,51 +314,164 @@ export class BrowserWaliRuntime {
                 return;
             return retainSharedPipe(handle);
         };
-        const applyChildSnapshot = (process) => {
-            if (process.snapshotApplied)
-                return;
-            process.snapshotApplied = true;
+        const waitForChild = (requestedPid, statusPointer, optionsValue) => {
+            if (!networkHost)
+                return -10n;
+            if (statusPointer !== 0 && (statusPointer < 0 || statusPointer + 4 > bytes().byteLength))
+                return -14n;
+            const { result, process } = networkHost.waitChild(requestedPid, optionsValue, signalHost.mask);
+            if (result <= 0)
+                return BigInt(result);
             const patch = decodeProcessSnapshot(process);
             if (patch) {
                 if (filesystemCoordinator)
-                    applyProcessFilesystemPatch(filesystemCoordinator.filesystem(), patch);
+                    filesystemCoordinator.filesystem().importPeerPatch(patch);
                 if (options.filesystem)
                     applyProcessFilesystemPatch(options.filesystem, patch);
                 const snapshot = options.filesystem?.toSnapshot?.();
                 if (snapshot)
                     options.browserProcess?.restore?.(snapshot);
             }
+            if (statusPointer !== 0)
+                view().setInt32(statusPointer, (Atomics.load(new Int32Array(process.control), 1) & 0xff) << 8, true);
+            return BigInt(result);
         };
-        const waitForChild = (requestedPid, statusPointer, optionsValue) => {
-            let childPid;
-            let process;
-            if (requestedPid === -1) {
-                const entry = childProcesses.entries().next().value;
-                if (!entry)
-                    return -10n;
-                [childPid, process] = entry;
+        const spawnBrowserProcess = (args, filesystemPolicy) => {
+            const [pathname, argvPointer, envPointer, cwdPointer, stdinFd, stdoutFd, stderrFd] = args;
+            if (!options.browserProcess)
+                return -38;
+            if (filesystemPolicy)
+                filesystemPolicy = normalizeProcessFilesystemPolicy(filesystemPolicy);
+            const inheritedPolicy = inheritedFilesystemPolicy;
+            if (inheritedPolicy) {
+                if (options.browserProcess.filesystemPolicyVersion !== 1)
+                    return -95;
+                filesystemPolicy = intersectProcessFilesystemPolicies(inheritedPolicy, filesystemPolicy);
             }
-            else {
-                const exact = childProcesses.get(requestedPid);
-                if (!exact)
-                    return -10n;
-                childPid = requestedPid;
-                process = exact;
+            const executablePath = readCString(Number(pathname));
+            const argvValue = readCStringArray(Number(argvPointer));
+            if (argvValue.length === 0)
+                argvValue.push(executablePath);
+            const envValue = {};
+            for (const entry of readCStringArray(Number(envPointer))) {
+                const separator = entry.indexOf("=");
+                if (separator > 0)
+                    envValue[entry.slice(0, separator)] = entry.slice(separator + 1);
+            }
+            const childPid = Atomics.add(nextChildPid, 0, 1);
+            const process = {
+                control: new SharedArrayBuffer(8 * Int32Array.BYTES_PER_ELEMENT),
+                response: new SharedArrayBuffer(BROWSER_PROCESS_RESPONSE_BYTES),
+                snapshotApplied: false,
+            };
+            const stdin = exportPipe(Number(stdinFd), "reader");
+            const stdout = exportPipe(Number(stdoutFd), "writer");
+            const stderr = exportPipe(Number(stderrFd), "writer");
+            let childTable;
+            try {
+                const registered = networkHost.registerChild(childPid, process);
+                if (registered < 0)
+                    throw new Error(`Child registration failed: ${registered}`);
+                sharedFileClient?.prepareSpawn();
+                syncFilesystem();
+                childTable = sharedFileClient?.copyForExecChannel([Number(stdinFd), Number(stdoutFd), Number(stderrFd)]);
+                options.browserProcess.spawn({
+                    // A NEW process here, not an exec in place: its parent is this one,
+                    // and it and its own children come from the container's counter.
+                    pid: childPid,
+                    parentPid: pid,
+                    childPidAllocator: nextChildPid.buffer,
+                    ...(childTable ? { descriptorTable: childTable } : {}),
+                    ...(filesystemPolicy ? { filesystemPolicy } : {}),
+                    executablePath,
+                    argv: argvValue,
+                    env: envValue,
+                    ...(Number(envPointer) === 0 ? { inheritEnvironment: true } : {}),
+                    cwd: Number(cwdPointer) === 0 ? fileDescriptors.currentWorkingDirectory() : readCString(Number(cwdPointer)),
+                    control: process.control,
+                    response: process.response,
+                    ...(stdin ? { stdin } : {}),
+                    ...(stdout ? { stdout } : {}),
+                    ...(stderr ? { stderr } : {}),
+                });
+                return childPid;
+            }
+            catch {
+                childTable?.releasePort?.postMessage(true);
+                networkHost.forgetChild(childPid);
+                if (stdin)
+                    closeSharedPipe(stdin);
+                if (stdout)
+                    closeSharedPipe(stdout);
+                if (stderr)
+                    closeSharedPipe(stderr);
+                return -5;
+            }
+        };
+        let asyncifyData = options.forkState?.asyncifyData ?? 0;
+        let unwinding = false;
+        let rewinding = Boolean(options.forkState);
+        let forkResult = 0;
+        let forkNotice = false;
+        const asyncify = (name, ...args) => {
+            const fn = instance?.exports[name];
+            if (typeof fn !== "function")
+                throw new Error(`Missing ${name}; build the module with the Binaryen Asyncify stage.`);
+            fn(...args);
+        };
+        const currentCwd = () => sharedFileClient?.currentWorkingDirectory() ?? fileDescriptors.currentWorkingDirectory();
+        const fork = () => {
+            if (typeof instance?.exports.asyncify_start_unwind !== "function") {
+                if (!forkNotice)
+                    options.onDiagnostic?.("[WALI] SYS_fork answers -ENOSYS: module lacks the Binaryen Asyncify build stage (--asyncify --pass-arg=asyncify-imports@wali.SYS_fork).");
+                forkNotice = true;
+                return -38n;
             }
-            const control = new Int32Array(process.control);
-            if (Atomics.load(control, 0) === 0) {
-                if ((optionsValue & WNOHANG) !== 0)
-                    return 0n;
-                while (Atomics.load(control, 0) === 0)
-                    Atomics.wait(control, 0, 0, 1000);
+            if (rewinding) {
+                asyncify("asyncify_stop_rewind");
+                rewinding = false;
+                return BigInt(forkResult);
             }
-            applyChildSnapshot(process);
-            if (statusPointer !== 0) {
-                assertMemoryRange(memory(), statusPointer, 4);
-                view().setInt32(statusPointer, (Atomics.load(control, 1) & 0xff) << 8, true);
+            if (!options.browserProcess?.fork || !sharedFileClient || !networkHost)
+                return -38n;
+            unwinding = true;
+            view().setUint32(asyncifyData, asyncifyData + 8, true);
+            asyncify("asyncify_start_unwind", asyncifyData);
+            return 0n;
+        };
+        const execve = (pathname, argvPointer, envPointer) => {
+            if (!options.forkState || !options.browserProcess || !sharedFileClient)
+                return -38n;
+            const path = readCString(pathname);
+            const executable = path.startsWith("/") ? path : `${currentCwd()}/${path}`;
+            if (!runtimeFilesystem?.existsSync(executable))
+                return -2n;
+            if (!runtimeFilesystem.statSync(executable).isFile())
+                return -13n;
+            // A NULL envp is the process's own environment (see inheritEnvironment).
+            const env = envPointer === 0 ? { ...options.env } : {};
+            for (const entry of readCStringArray(envPointer)) {
+                const separator = entry.indexOf("=");
+                if (separator > 0)
+                    env[entry.slice(0, separator)] = entry.slice(separator + 1);
             }
-            childProcesses.delete(childPid);
-            return BigInt(childPid);
+            sharedFileClient.prepareSpawn();
+            const table = sharedFileClient.copyForExecChannel([0, 1, 2]);
+            const stdin = exportPipe(0, "reader");
+            const stdout = exportPipe(1, "writer");
+            const stderr = exportPipe(2, "writer");
+            options.browserProcess.spawn({
+                // The kernel's exec: the image changes, the process does not. The pid
+                // and the parent go across, and the child numbers ITS children from
+                // the container's one allocator -- two runtimes each starting their
+                // own at 10000 hand out the same pid twice.
+                pid, parentPid: parentProcessId, childPidAllocator: nextChildPid.buffer,
+                executablePath: executable, argv: readCStringArray(argvPointer), env, cwd: currentCwd(),
+                descriptorTable: table, control: options.forkState.control, response: options.forkState.response,
+                ...(filesystemPolicy ? { filesystemPolicy } : {}),
+                ...(stdin ? { stdin } : {}), ...(stdout ? { stdout } : {}), ...(stderr ? { stderr } : {}),
+            });
+            throw new WaliProcessReplaced();
         };
         const builtins = {
             __init: () => 0,
@@ -264,10 +503,10 @@ export class BrowserWaliRuntime {
                 }
                 return written;
             },
-            SYS_exit: (status) => exit(Number(status)),
-            SYS_exit_group: (status) => exit(Number(status)),
+            SYS_exit: (status) => exit(Number(status), "SYS_exit"),
+            SYS_exit_group: (status) => exit(Number(status), "SYS_exit_group"),
             SYS_getpid: () => BigInt(pid),
-            SYS_getppid: () => 1n,
+            SYS_getppid: () => BigInt(parentProcessId),
             SYS_gettid: () => BigInt(pid),
             SYS_getuid: () => 1000n,
             SYS_geteuid: () => 1000n,
@@ -280,83 +519,71 @@ export class BrowserWaliRuntime {
             // advertises it; a program calling it on its main thread was the one
             // path that still failed closed.
             SYS_prctl: () => 0n,
-            SYS_tkill: () => 0n,
-            SYS_browser_spawn: (pathname, argvPointer, envPointer, cwdPointer, stdinFd, stdoutFd, stderrFd) => {
-                if (!options.browserProcess)
-                    return -38;
-                const executablePath = readCString(Number(pathname));
-                const argvValue = readCStringArray(Number(argvPointer));
-                if (argvValue.length === 0)
-                    argvValue.push(executablePath);
-                const envValue = {};
-                for (const entry of readCStringArray(Number(envPointer))) {
-                    const separator = entry.indexOf("=");
-                    if (separator > 0)
-                        envValue[entry.slice(0, separator)] = entry.slice(separator + 1);
-                }
-                const childPid = Atomics.add(nextChildPid, 0, 1);
-                const process = {
-                    control: new SharedArrayBuffer(8 * Int32Array.BYTES_PER_ELEMENT),
-                    response: new SharedArrayBuffer(BROWSER_PROCESS_RESPONSE_BYTES),
-                    snapshotApplied: false,
-                };
-                const stdin = exportPipe(Number(stdinFd), "reader");
-                const stdout = exportPipe(Number(stdoutFd), "writer");
-                const stderr = exportPipe(Number(stderrFd), "writer");
-                childProcesses.set(childPid, process);
-                try {
-                    syncFilesystem();
-                    options.browserProcess.spawn({
-                        pid: childPid,
-                        executablePath,
-                        argv: argvValue,
-                        env: envValue,
-                        cwd: Number(cwdPointer) === 0 ? fileDescriptors.currentWorkingDirectory() : readCString(Number(cwdPointer)),
-                        control: process.control,
-                        response: process.response,
-                        ...(stdin ? { stdin } : {}),
-                        ...(stdout ? { stdout } : {}),
-                        ...(stderr ? { stderr } : {}),
-                    });
-                    return childPid;
-                }
-                catch {
-                    childProcesses.delete(childPid);
-                    if (stdin)
-                        closeSharedPipe(stdin);
-                    if (stdout)
-                        closeSharedPipe(stdout);
-                    if (stderr)
-                        closeSharedPipe(stderr);
-                    return -5;
+            // A signal the process sends itself (musl's raise is tkill on its own
+            // tid): a handler runs when the call returns, SIG_DFL ends the process
+            // for the signals whose default is to end it, as with 128 + the signal.
+            SYS_tkill: (_tid, signal) => signalSelf(Number(signal)),
+            // The codec bridge is negotiated by the manifest's `media.webcodecs`;
+            // without it every one of the six answers -95 before an argument is read.
+            ...createWaliCodecImports(memory, () => options.codec?.version === 1, () => codecClient),
+            SYS_browser_spawn: (...args) => spawnBrowserProcess(args),
+            SYS_browser_spawn_confined_v1: createConfinedWaliSpawnImport(memory, () => options.browserProcess?.filesystemPolicyVersion === 1, spawnBrowserProcess),
+            SYS_fork: fork,
+            SYS_execve: (path, argv, env) => execve(Number(path), Number(argv), Number(env)),
+            // interrupted by a signal: its handler runs here, and a handler that
+            // asked for SA_RESTART (musl's signal() does) has the wait made again
+            SYS_wait4: (childPid, status, optionsValue) => {
+                for (;;) {
+                    const result = waitForChild(Number(childPid), Number(status), Number(optionsValue));
+                    if (result !== -4n || !signalHost.deliver())
+                        return result;
                 }
             },
-            SYS_wait4: (childPid, status, optionsValue) => waitForChild(Number(childPid), Number(status), Number(optionsValue)),
+            SYS_pidfd_open: () => -38n,
             SYS_kill: (childPid, signal) => {
+                if (Number(childPid) === pid || Number(childPid) === 0)
+                    return signalSelf(Number(signal));
                 const normalized = Math.abs(Number(childPid));
-                const process = childProcesses.get(normalized);
-                if (!process)
+                if (!networkHost?.hasChild(normalized))
                     return -3n;
-                Atomics.store(new Int32Array(process.control), 3, Number(signal));
                 options.browserProcess?.kill?.(normalized, Number(signal));
                 return 0n;
             },
             SYS_setpgid: () => 0n,
             SYS_getpgid: (childPid) => BigInt(Number(childPid) === 0 ? pid : Math.abs(Number(childPid))),
-            __wasm_thread_spawn: (functionPointer, argumentPointer) => threadPool?.spawn(Number(functionPointer), Number(argumentPointer)) ?? -11,
-            SYS_rt_sigaction: (signal, action, previous, setSize) => {
-                const signalNumber = Number(signal);
-                const actionPointer = Number(action);
-                const previousPointer = Number(previous);
-                if (signalNumber < 1 || signalNumber > 64 || Number(setSize) !== 8)
-                    return -EINVAL;
-                if (actionPointer !== 0 && (signalNumber === 9 || signalNumber === 19))
-                    return -EINVAL;
-                if (previousPointer !== 0)
-                    copyIn(previousPointer, signalActions.get(signalNumber) ?? new Uint8Array(20));
-                if (actionPointer !== 0)
-                    signalActions.set(signalNumber, copyOut(actionPointer, 20));
-                return 0n;
+            /**
+             * POOL EXHAUSTION SAYS SO, ONCE, because -EAGAIN is invisible from here up.
+             *
+             * The pool is instantiated before `_start` and never grows, so it is the
+             * process's whole THREAD budget; `WaliThreadPool.spawn` answers -EAGAIN
+             * (-11) when no slot is free, exactly as a kernel out of task structs
+             * would. What the guest does with that is the problem: libc++ turns it
+             * into `std::system_error: thread constructor failed: Resource
+             * temporarily unavailable`, and an uncaught one leaves the module as the
+             * host string `[object WebAssembly.Exception]` with nothing naming a
+             * thread, a pool or a number.
+             *
+             * MEASURED 2026-09-19 (WS-Y): that string was the entire failure report
+             * of the OpenImageIO deps gate for two days, and the cause was arithmetic
+             * -- an unconfigured OpenImageIO opens its own pool of `cpus - 1` AND
+             * OpenEXR's global pool of `cpus`, so it wants `2 * cpus - 1` threads out
+             * of a budget of `cpus`. One line here names that class of death at the
+             * moment it happens. Same door as the exit notices above: console.error
+             * plus onDiagnostic, never stdout.
+             */
+            __wasm_thread_spawn: (functionPointer, argumentPointer) => {
+                const tid = threadPool?.spawn(Number(functionPointer), Number(argumentPointer), signalHost.mask) ?? -11;
+                if (tid === -11 && !threadPoolExhaustionReported) {
+                    threadPoolExhaustionReported = true;
+                    const notice = `[WALI] pthread_create answered -EAGAIN: all ${threadPoolSize} worker slots are in use.`
+                        + ` The pool is the process's whole thread budget and does not grow, so this is a QUOTA, not a cpu count --`
+                        + ` sysconf(_SC_NPROCESSORS_ONLN) answers ${systemHost.reportedCpuCount()} here and a`
+                        + ` library that opens more than one pool from that number wants a multiple of it. Raise the program's`
+                        + ` requirements.workers, or state the library's concurrency.`;
+                    console.error(notice);
+                    options.onDiagnostic?.(notice);
+                }
+                return tid;
             },
             SYS_clock_gettime: (clockId, pointer) => {
                 const nowNanoseconds = clockNanoseconds(Number(clockId));
@@ -382,6 +609,7 @@ export class BrowserWaliRuntime {
             },
             ...memoryManager.imports(),
             ...systemImports,
+            ...signalHost.imports(),
             ...pipeImports,
             // The relay event worker is also the process-wide descriptor table for
             // epoll, eventfd, and timerfd. Root and pthread instances must share it:
@@ -392,15 +620,28 @@ export class BrowserWaliRuntime {
                 ?? systemImports.SYS_ioctl(fd, request, argument),
         };
         const handlers = { ...builtins, ...options.imports };
+        // select(2) is the process's poll over a scratch mapping, whichever host
+        // composed that poll above.
+        let selectScratch = 0;
+        handlers.SYS_select ??= createSelectImport(memory, (pointer, count, timeout) => handlers.SYS_poll(pointer, count, timeout), () => (selectScratch ||= Number(memoryManager.imports().SYS_mmap(0, SELECT_SCRATCH_BYTES, 3, 0x22, -1, 0))));
         const wali = {};
         for (const descriptor of waliDescriptors) {
-            const handler = handlers[descriptor.name]
-                ?? (() => { throw new UnsupportedWaliImportError([descriptor.name]); });
+            const handler = handlers[descriptor.name] ?? unimplementedImport(descriptor.name, options.onDiagnostic);
+            const spent = { calls: 0, ms: 0 };
+            syscallTime.set(descriptor.name, spent);
             wali[descriptor.name] = (...args) => {
                 options.onSyscall?.(descriptor.name, args);
-                const result = handler(...args);
-                options.onSyscallResult?.(descriptor.name, result);
-                return result;
+                const began = performance.now();
+                try {
+                    const result = handler(...args);
+                    options.onSyscallResult?.(descriptor.name, result);
+                    signalHost.deliver();
+                    return result;
+                }
+                finally {
+                    spent.calls += 1;
+                    spent.ms += performance.now() - began;
+                }
             };
         }
         const env = {
@@ -413,6 +654,44 @@ export class BrowserWaliRuntime {
             wali,
             env,
         });
+        if (options.forkState) {
+            bytes().set(new Uint8Array(options.forkState.memory));
+            for (const [name, value] of Object.entries(options.forkState.globals)) {
+                const global = instance.exports[name];
+                if (!(global instanceof WebAssembly.Global))
+                    throw new Error(`Fork snapshot global ${name} is not exported.`);
+                global.value = value;
+            }
+            memoryManager.restoreFork(options.forkState.mappings);
+            systemImports.SYS_umask(options.forkState.umask);
+        }
+        else if (typeof instance.exports.asyncify_start_unwind === "function") {
+            const stack = instance.exports.__stack_pointer;
+            if (!(stack instanceof WebAssembly.Global))
+                throw new Error("Asyncify fork requires --export=__stack_pointer at link.");
+            // Reserve the module's declared stack capacity outside its initial image,
+            // before brk is initialized. The guest heap begins after this reservation.
+            const capacity = Number(stack.value);
+            if (capacity <= 0)
+                throw new Error("Asyncify fork requires a nonempty module stack.");
+            asyncifyData = memory().buffer.byteLength;
+            memory().grow(Math.ceil((capacity + 8) / 65_536));
+            view().setUint32(asyncifyData + 4, asyncifyData + 8 + capacity, true);
+        }
+        if (options.codec?.version === 1) {
+            try {
+                codecCoordinator = await WaliCodecCoordinator.create(memory());
+                codecClient = new WaliCodecClient(codecCoordinator.createChannel());
+            }
+            catch (error) {
+                // A host without WebCodecs (or without workers) answers the six
+                // imports -95, the ABI's answer for a codec the browser cannot do.
+                // It never takes the program down.
+                console.warn("[WALI] the codec bridge is unavailable:", error);
+                codecCoordinator = undefined;
+                codecClient = undefined;
+            }
+        }
         if (threaded) {
             if (!importedMemory) {
                 throw new Error("A threaded WALI module must be linked with --import-memory so browser workers can share its process memory.");
@@ -424,34 +703,86 @@ export class BrowserWaliRuntime {
                 sharedMmapRegistry,
                 fatalState: pthreadFatal.buffer,
                 imports: descriptors,
-                size: options.threadPoolSize ?? 18,
+                size: threadPoolSize,
                 pid,
                 executablePath,
                 argv,
                 cwd: fileDescriptors.currentWorkingDirectory(),
                 stdioAliasRegistry: stdioAliasRegistry.buffer,
                 sharedPipes: sharedPipeState,
+                signals: signalState,
                 childPidAllocator: nextChildPid.buffer,
+                ...(inheritedFilesystemPolicy ? { inheritedFilesystemPolicy } : {}),
                 ...(options.browserProcessPorts ? { browserProcessPorts: options.browserProcessPorts } : {}),
+                ...(options.browserProcess?.filesystemPolicyVersion === 1 ? { childFilesystemPolicyVersion: 1 } : {}),
                 ...(options.threadOutputPorts ? { outputPorts: options.threadOutputPorts } : {}),
                 ...(stdin instanceof SharedWaliStdinReader ? { stdin: stdin.buffer } : {}),
+                terminal: options.terminal === true,
                 onStdout: (chunk) => { emit(1, chunk); },
                 onStderr: (chunk) => { emit(2, chunk); },
                 ...(networkCoordinator ? { network: networkCoordinator } : {}),
-                ...(filesystemCoordinator ? { filesystem: filesystemCoordinator } : {}),
+                ...(sharedFileClient ? { filesystem: sharedFileClient } : {}),
+                ...(codecCoordinator ? { codec: codecCoordinator } : {}),
             });
             await threadPool.initialize();
         }
         const start = instance.exports._start;
         if (typeof start !== "function")
             throw new Error("WALI module does not export _start.");
+        startEnteredAt = performance.now();
         let exitCode = 0;
+        let replaced = false;
         try {
             try {
-                start();
+                if (rewinding)
+                    asyncify("asyncify_start_rewind", asyncifyData);
+                for (;;) {
+                    start();
+                    if (!unwinding)
+                        break;
+                    asyncify("asyncify_stop_unwind");
+                    unwinding = false;
+                    const layout = options.memoryLayout ?? (!(source instanceof WebAssembly.Module)
+                        ? findImportedMemory(source instanceof Uint8Array ? source : new Uint8Array(source)) : undefined);
+                    if (!layout)
+                        throw new Error("Fork requires the module's imported memory layout.");
+                    const globals = {};
+                    for (const [name, value] of Object.entries(instance.exports)) {
+                        if (!(value instanceof WebAssembly.Global))
+                            continue;
+                        try {
+                            value.value = value.value;
+                            globals[name] = value.value;
+                        }
+                        catch { /* Immutable globals are reconstructed by instantiation. */ }
+                    }
+                    const control = new SharedArrayBuffer(8 * Int32Array.BYTES_PER_ELEMENT);
+                    const response = new SharedArrayBuffer(BROWSER_PROCESS_RESPONSE_BYTES);
+                    forkResult = Atomics.add(nextChildPid, 0, 1);
+                    const registered = networkHost.registerChild(forkResult, { control, response });
+                    if (registered < 0)
+                        throw new Error(`Fork child registration failed: ${registered}`);
+                    const mask = Number(systemImports.SYS_umask(0));
+                    systemImports.SYS_umask(mask);
+                    options.onDiagnostic?.(`[WALI] fork snapshot: ${memory().buffer.byteLength} bytes, Asyncify stack ${view().getUint32(asyncifyData, true) - asyncifyData - 8} bytes.`);
+                    options.browserProcess.fork({
+                        module, memoryLayout: layout, pid: forkResult, control, response,
+                        descriptorTable: sharedFileClient.copyForForkChannel(),
+                        childPidAllocator: nextChildPid.buffer,
+                        argv, env: { ...options.env }, cwd: currentCwd(), executablePath,
+                        ...(filesystemPolicy ? { filesystemPolicy } : {}),
+                        forkState: { control, response, memory: bytes().slice().buffer, globals,
+                            allocator: memoryManager.allocatorControl().slice(0), mappings: memoryManager.forkSnapshot(),
+                            asyncifyData, umask: mask, parentPid: pid },
+                    });
+                    rewinding = true;
+                    asyncify("asyncify_start_rewind", asyncifyData);
+                }
             }
             catch (error) {
-                if (error instanceof WaliProcessExit || error instanceof WaliPthreadProcessExit)
+                if (error instanceof WaliProcessReplaced)
+                    replaced = true;
+                else if (error instanceof WaliProcessExit || error instanceof WaliPthreadProcessExit)
                     exitCode = error.code;
                 else if (error instanceof UnsupportedWaliImportError)
                     throw error;
@@ -467,17 +798,44 @@ export class BrowserWaliRuntime {
         finally {
             threadPool?.terminate();
             networkCoordinator?.terminate();
-            syncFilesystem();
+            codecCoordinator?.terminate();
+            if (environmentFile && runtimeFilesystem?.existsSync(environmentFile))
+                runtimeFilesystem.unlinkSync(environmentFile);
+            if (filesystemCoordinator && options.filesystemUpdatePort && options.filesystem?.replaceSnapshot) {
+                options.filesystem.replaceSnapshot(filesystemCoordinator.finalSnapshot());
+                options.onFilesystemFinalized?.();
+            }
+            else
+                syncFilesystem();
+            sharedFileClient?.closeProcess();
+            if (!sharedFileClient)
+                fileDescriptors.descriptors.exit();
             filesystemCoordinator?.terminate();
         }
+        const wallMs = performance.now() - runStartedAt;
+        if (wallMs > PROFILE_AFTER_MS) {
+            const calls = [...syscallTime].filter(([, spent]) => spent.calls > 0);
+            const inSyscalls = calls.reduce((sum, [, spent]) => sum + spent.ms, 0);
+            const top = calls.sort((a, b) => b[1].ms - a[1].ms).slice(0, 8)
+                .map(([name, spent]) => `${name.replace(/^SYS_/u, "")} ${spent.calls}x ${Math.round(spent.ms)}ms`);
+            console.log("[wali-profile]", JSON.stringify({
+                argv: argv.slice(0, 3), wallMs: Math.round(wallMs), setupMs: Math.round(startEnteredAt - runStartedAt),
+                guestMs: Math.round(performance.now() - startEnteredAt), syscallMs: Math.round(inSyscalls), top,
+            }));
+        }
         return {
             exitCode,
+            ...(replaced ? { replaced } : {}),
             stdout: decoder.decode(concatenate(stdout)),
             stderr: decoder.decode(concatenate(stderr)),
             imports: descriptors,
         };
     }
 }
+/** The calls through which a process makes a child: fork, exec, the browser's spawn door, and the wait for one. */
+const CHILD_PROCESS_SYSCALLS = new Set(["SYS_fork", "SYS_execve", "SYS_browser_spawn", "SYS_browser_spawn_confined_v1", "SYS_wait4"]);
+/** A run longer than this prints where its time went (`[wali-profile]`). */
+const PROFILE_AFTER_MS = 2000;
 function normalizePid(pid) {
     if (pid === undefined)
         return 2;
@@ -507,8 +865,7 @@ function clockNanoseconds(clockId) {
         return BigInt(Math.floor(milliseconds * 1_000_000));
     }
     if (clockId === 1 || clockId === 4) {
-        const milliseconds = typeof performance === "undefined" ? Date.now() : performance.now();
-        return BigInt(Math.floor(milliseconds * 1_000_000));
+        return BigInt(Math.floor(monotonicMilliseconds() * 1_000_000));
     }
     return undefined;
 }