@volter/browser-wali 0.1.4 → 0.1.6

package/dist/worker-program.js

@@ -1,16 +1,34 @@
+import { normalizeProcessFilesystemPolicy, intersectProcessFilesystemPolicies, requireProcessFilesystemPolicySupport } from "@volter/browser-runtime/browser-process-filesystem-policy.js";
+import { localBrowserFileSystemStore, readBrowserFileSystemSnapshot, readBrowserFileSystemEntry } from "@volter/browser-runtime/browser-filesystem.js";
+import { BROWSER_PACK_RETENTION_ROOT, NODE_ENGINE_ROOT, PROJECT_ROOTS } from "@volter/browser-runtime/browser-pack-store.js";
+import { browserProcessLineage } from "@volter/browser-runtime/browser-process.js";
 import { SharedWaliStdinWriter } from "./stdin.js";
-import { applyProcessFilesystemPatch, closeSharedPipe, createProcessFilesystemPatch, encodeProcessSnapshot, readSharedPipe, writeSharedPipe, } from "./process-bridge.js";
+import { createWaliSignalState, defaultTerminates, WaliSignals } from "./signals.js";
+import { waliSharedPipeDescribesFd } from "./shared-pipes.js";
+import { applyProcessFilesystemPatch, closeSharedPipe, createProcessFilesystemPatch, encodeProcessPatch, readSharedPipe, writeSharedPipe, } from "./process-bridge.js";
 import { createBrowserFileLockChannel, sharedBrowserFileLockCoordinator, } from "@volter/browser-runtime/browser-file-locks.js";
 import { createBrowserFileCoherenceChannel, sharedBrowserFileCoherenceCoordinator, } from "@volter/browser-runtime/browser-file-coherence.js";
+import { currentEntry, patchedSnapshot } from "@volter/browser-runtime/browser-process-filesystem.js";
+import { pageWorker } from "@volter/browser-runtime/page-workers.js";
 /** Runs one unchanged WALI executable off the UI thread while retaining its compiled module. */
+/**
+ * Each program's module, compiled by the first worker that ran it, for every
+ * worker after: a module is compiled once per page, not once per worker. Only
+ * a pinned artifact is kept; a `blob:` module is a URL of its own each run.
+ */
+const compiledModules = new Map();
+const compiledKey = (url, integrity) => integrity ? `${url}\n${integrity}` : undefined;
 export class BrowserWaliWorkerProgram {
     filesystem;
     program;
+    capabilities = Object.freeze({ filesystemPolicy: true });
+    /** Started by the first run, so a program the page offers and never runs costs no worker. */
     worker;
     pending;
     stdin;
     terminalSize = { columns: 80, rows: 24 };
     nextId = 1;
+    forkWorkers = new Map();
     childControllers = new Map();
     openUrlHandler;
     urlScanTail = "";
@@ -18,22 +36,55 @@ export class BrowserWaliWorkerProgram {
     processPorts = [];
     threadOutputPorts = [];
     filesystemUpdatePort;
+    traceId = crypto.randomUUID();
     preparing = false;
+    applyingFilesystem = false;
     constructor(filesystem, program) {
         this.filesystem = filesystem;
         this.program = program;
-        this.worker = this.createWorker();
     }
     async run(argv, options = {}) {
+        if (options.filesystemPolicy !== undefined)
+            options = { ...options, filesystemPolicy: normalizeProcessFilesystemPolicy(options.filesystemPolicy) };
         if (this.pending || this.preparing)
             throw new Error("The browser WALI program is already running.");
         if (options.signal?.aborted)
             throw options.signal.reason;
+        // Started here so its boot overlaps the run's preparation.
+        this.worker ??= this.createWorker();
         this.preparing = true;
+        console.log("[wali-boot]", JSON.stringify({ stage: "prepare", run: this.traceId, argv, at: Date.now() }));
         try {
-            const filesystem = this.program.prepareFilesystem
-                ? await this.program.prepareFilesystem(this.filesystem.toSnapshot())
-                : this.filesystem.toSnapshot();
+            // A page over a worker's store sends the worker to the store, not the
+            // tree: what the page has written must be in the store first, and the
+            // snapshot is the index, which the worker reads the bytes behind.
+            const store = localBrowserFileSystemStore(this.filesystem);
+            if (store)
+                await this.filesystem.flush?.();
+            // The worker reads every store root's bytes from the store itself, so
+            // those roots travel as metadata. The trees the program says it never
+            // reads travel the same way: their directories are there (a process may
+            // be started with one as its cwd: VS Code's extension host runs from the
+            // server's install tree and spawns git from it), their files are not.
+            console.log("[wali-boot]", JSON.stringify({ stage: "flushed", run: this.traceId, at: Date.now() }));
+            // A live pack's retention links are the shared store's references, not
+            // files a program reads; carried as content, one installed model is
+            // gigabytes in every run's image. The Node engine's prepared module
+            // bodies are its own: carried as content, an editor's 296 MB of them went
+            // into every `git` run's image, and two runs at once ended the page on
+            // its heap (measured 2026-09-24 in examples/volter-editor).
+            const unread = [BROWSER_PACK_RETENTION_ROOT, NODE_ENGINE_ROOT, ...this.program.excludedImagePaths?.() ?? []];
+            const metadataRoots = [...(store ? PROJECT_ROOTS : []), ...unread];
+            const image = await readBrowserFileSystemSnapshot(this.filesystem, "/", metadataRoots.length > 0 ? { metadataRoots } : {});
+            // The base every patch is diffed against is the image as the worker
+            // holds it: the unread trees' files are not in it (their directories
+            // are). Diffed against the page's own listing, the worker's final tree
+            // reported every one of those files removed, and the page deleted them
+            // (measured 2026-09-21: one git run's exit took 3,318 files of the
+            // GitLens and server trees).
+            const unreadFile = (path) => unread.some((root) => path === root || path.startsWith(`${root}/`));
+            const base = { files: image.files.filter((entry) => entry.type === "directory" || !unreadFile(entry.path)) };
+            const filesystem = this.program.prepareFilesystem ? await this.program.prepareFilesystem(image) : image;
             if (options.signal?.aborted)
                 throw options.signal.reason;
             const id = this.nextId++;
@@ -41,25 +92,70 @@ export class BrowserWaliWorkerProgram {
             const lockChannel = createBrowserFileLockChannel();
             const releaseFileLocks = sharedBrowserFileLockCoordinator.attach(lockChannel.server, lockOwner);
             const coherenceChannel = createBrowserFileCoherenceChannel();
-            const releaseFileCoherence = sharedBrowserFileCoherenceCoordinator.attach(coherenceChannel.server, this.program.coherenceFilesystem ?? this.filesystem, () => this.program.onFilesystemCommit?.(this.filesystem));
+            const coherenceFilesystem = this.program.coherenceFilesystem ?? this.filesystem;
+            const releaseFileCoherence = sharedBrowserFileCoherenceCoordinator.attach(coherenceChannel.server, coherenceFilesystem, () => this.program.onFilesystemCommit?.(this.filesystem), 
+            // What coherence wrote is what the tree holds; the base records it so a
+            // later live patch on the same path is judged against the truth.
+            (path) => {
+                const pending = this.pending;
+                if (!pending || pending.id !== id)
+                    return;
+                const entry = currentEntry(coherenceFilesystem, path);
+                pending.filesystemBase = patchedSnapshot(pending.filesystemBase, entry ? { files: [entry], removed: [] } : { files: [], removed: [path] });
+            });
             this.urlScanTail = "";
             this.openedUrls.clear();
             const stdin = new SharedWaliStdinWriter();
-            stdin.resize(this.terminalSize.columns, this.terminalSize.rows);
+            const size = options.terminal ?? this.terminalSize;
+            stdin.resize(size.columns, size.rows);
             this.stdin = stdin;
+            const signalState = createWaliSignalState();
             return await new Promise((resolve, reject) => {
-                const abort = () => {
+                // What `kill` sent (the abort reason's `signal`; an abort that names
+                // none ends the process, as SIGKILL). A handler the program installed
+                // runs, and the program ends as it chooses: git removes its lockfiles
+                // and raises the signal again, which then ends it. An AbortSignal fires
+                // once, so a signal the program survived leaves `redeliver` on the
+                // reason: the next `kill` (a SIGKILL after an ignored SIGTERM) still
+                // reaches it, and `handled` says whether the program ended by itself.
+                const reason = () => options.signal?.reason ?? new DOMException("The WALI process was interrupted.", "AbortError");
+                const end = () => {
+                    const current = options.signal?.reason;
+                    if (current && typeof current === "object")
+                        current.handled = false;
                     this.resetWorker();
                     this.finishPending();
-                    reject(options.signal?.reason ?? new DOMException("The WALI process was interrupted.", "AbortError"));
+                    reject(reason());
+                };
+                const survives = (signal) => {
+                    if (signal === 9)
+                        return false;
+                    const disposition = new WaliSignals(signalState).raise(signal);
+                    return disposition !== "default" || !defaultTerminates(signal);
+                };
+                const abort = () => {
+                    const current = options.signal?.reason;
+                    if (!survives(abortSignalNumber(current))) {
+                        end();
+                        return;
+                    }
+                    if (current && typeof current === "object") {
+                        current.handled = true;
+                        current.redeliver = (signal) => { if (this.pending && !survives(signal))
+                            end(); };
+                    }
                 };
                 options.signal?.addEventListener("abort", abort, { once: true });
                 let releaseLoopback = () => { };
                 const loopbackChannel = this.program.loopback ? new MessageChannel() : undefined;
                 if (loopbackChannel)
                     releaseLoopback = this.program.loopback.attach(loopbackChannel.port1);
+                let resolveFilesystemFinalization;
+                const filesystemFinalization = new Promise((resolve) => { resolveFilesystemFinalization = resolve; });
                 this.pending = {
                     id,
+                    filesystemBase: base,
+                    filesystemQueue: Promise.resolve(),
                     resolve,
                     reject,
                     options,
@@ -69,17 +165,41 @@ export class BrowserWaliWorkerProgram {
                     releaseLoopback,
                     releaseFileLocks,
                     releaseFileCoherence,
+                    releaseFilesystemChanges: () => { },
+                    changedPaths: new Set(),
+                    importingFilesystem: false,
+                    filesystemFinalized: false,
+                    filesystemFinalization,
+                    resolveFilesystemFinalization,
                 };
                 const request = {
                     type: "run",
+                    // A program the lane exec'd into an existing process runs AS that
+                    // process: it takes its pid, the parent it kept, and the counter its
+                    // own children are numbered from. A run that is not an exec carries
+                    // no lineage and is the runtime's first process, as before.
+                    ...(options[browserProcessLineage] ? {
+                        pid: options[browserProcessLineage].pid,
+                        parentPid: options[browserProcessLineage].parentPid,
+                        childPidAllocator: options[browserProcessLineage].childPidAllocator,
+                    } : {}),
                     id,
+                    ...(options.descriptorTable ? { descriptorTable: options.descriptorTable } : {}),
                     url: this.program.url,
                     ...(this.program.integrity ? { integrity: this.program.integrity } : {}),
+                    ...(() => {
+                        const key = compiledKey(this.program.url, this.program.integrity);
+                        const compiled = key ? compiledModules.get(key) : undefined;
+                        return compiled ? { compiled } : {};
+                    })(),
                     ...(options.executablePath ? { executablePath: options.executablePath } : {}),
                     argv: [...argv],
                     cwd: options.cwd ?? this.program.cwd ?? "/",
-                    env: { ...this.program.env },
+                    env: { ...options.env, ...this.program.env },
                     threadPoolSize: this.program.threadPoolSize ?? 18,
+                    ...(this.program.codec ? { codec: this.program.codec } : {}),
+                    ...(options.filesystemPolicy ? { filesystemPolicy: options.filesystemPolicy } : {}),
+                    ...(this.program.spawn?.capabilities?.filesystemPolicy === true ? { childFilesystemPolicyVersion: 1 } : {}),
                     ...(this.program.network.allowedHosts.length > 0 || loopbackChannel ? { network: {
                             ...(this.program.network.relayUrl ? { relayUrl: this.program.network.relayUrl } : {}),
                             allowedHosts: [...this.program.network.allowedHosts],
@@ -88,9 +208,12 @@ export class BrowserWaliWorkerProgram {
                         } } : {}),
                     ...(loopbackChannel ? { loopbackPort: loopbackChannel.port2 } : {}),
                     stdin: stdin.buffer,
+                    terminal: options.terminal !== undefined,
                     filesystem,
+                    ...(store ? { store: { projectId: store } } : {}),
                     fileLocks: { channel: lockChannel.client, owner: lockOwner },
                     fileCoherence: coherenceChannel.client,
+                    signalState,
                 };
                 const channels = Array.from({ length: request.threadPoolSize }, () => new MessageChannel());
                 this.processPorts = channels.map((channel) => channel.port1);
@@ -121,14 +244,17 @@ export class BrowserWaliWorkerProgram {
                                 this.emitStderr(active, `\nWALI pthread ${event.data.tid ?? "unknown"} error: ${event.data.message}\n`);
                                 return;
                             }
-                            const chunk = new TextDecoder().decode(event.data.bytes);
+                            if (event.data.type === "diagnostic") {
+                                active.options.onDiagnostic?.(event.data.message);
+                                return;
+                            }
                             if (event.data.type === "stdout")
-                                this.emitStdout(active, chunk);
+                                this.emitStdout(active, event.data.bytes);
                             else
-                                this.emitStderr(active, chunk);
+                                this.emitStderr(active, new TextDecoder().decode(event.data.bytes));
                         }
                         finally {
-                            if (event.data.type !== "error" && event.data.ack) {
+                            if (event.data.type !== "error" && event.data.type !== "diagnostic" && event.data.ack) {
                                 const ack = new Int32Array(event.data.ack);
                                 Atomics.store(ack, 0, 1);
                                 Atomics.notify(ack, 0);
@@ -141,11 +267,28 @@ export class BrowserWaliWorkerProgram {
                 const filesystemUpdates = new MessageChannel();
                 this.filesystemUpdatePort = filesystemUpdates.port1;
                 this.filesystemUpdatePort.onmessage = (event) => {
-                    void this.applyLiveFilesystemPatch(id, event.data);
+                    const active = this.pending;
+                    if (active?.id === id)
+                        active.filesystemQueue = active.filesystemQueue.then(() => this.applyLiveFilesystemPatch(id, event.data));
                 };
                 this.filesystemUpdatePort.start();
+                const changed = (path) => {
+                    const active = this.pending;
+                    if (!active || active.id !== id || this.applyingFilesystem)
+                        return;
+                    active.changedPaths.add(path);
+                    this.scheduleFilesystemImport(active);
+                };
+                this.filesystem.on("change", changed);
+                this.filesystem.on("delete", changed);
+                this.pending.releaseFilesystemChanges = () => {
+                    this.filesystem.off("change", changed);
+                    this.filesystem.off("delete", changed);
+                };
                 request.filesystemUpdatePort = filesystemUpdates.port2;
+                console.log("[wali-boot]", JSON.stringify({ stage: "dispatch", run: this.traceId, at: Date.now() }));
                 this.worker.postMessage(request, [
+                    ...(request.descriptorTable ? [request.descriptorTable.port] : []),
                     ...request.browserProcessPorts,
                     ...request.threadOutputPorts,
                     request.filesystemUpdatePort,
@@ -153,14 +296,21 @@ export class BrowserWaliWorkerProgram {
                     request.fileCoherence.port,
                     ...(request.loopbackPort ? [request.loopbackPort] : []),
                 ]);
-                if (options.stdin !== undefined) {
-                    if (!stdin.write(options.stdin)) {
-                        this.resetWorker();
-                        this.finishPending();
-                        reject(new Error("Browser process stdin exceeds the WALI input buffer."));
-                        return;
-                    }
-                    stdin.close();
+                // THE INHERITED TABLE OWNS fd 0. When a run inherits a descriptor table
+                // whose fd 0 is an open pipe description, that pipe IS the run's stdin
+                // and the guest reads it itself. Pumping the host's own reader on the
+                // same description into this run's private stdin buffer puts two readers
+                // on one pipe, and the pump -- polling from launch, while the guest is
+                // still instantiating -- takes the bytes and drops them where nothing
+                // reads. Measured: git's remote helper never saw its `capabilities` line.
+                const inheritedPipes = inheritedSharedPipes(options.descriptorTable);
+                const inheritedStdin = inheritedPipes !== undefined && waliSharedPipeDescribesFd(inheritedPipes, 0);
+                if (inheritedStdin) {
+                    // Nothing to pump: fd 0 is the description, not this run's stdin.
+                }
+                else if (options.stdin !== undefined) {
+                    const value = options.stdin;
+                    void this.forwardStdin(id, stdin, (async function* () { yield value; })());
                 }
                 else if (options.stdinStream) {
                     void this.forwardStdin(id, stdin, options.stdinStream);
@@ -172,10 +322,21 @@ export class BrowserWaliWorkerProgram {
         }
     }
     async forwardStdin(id, stdin, stream) {
+        const encoder = new TextEncoder();
         try {
             for await (const chunk of stream) {
-                while (this.pending?.id === id && !stdin.write(chunk)) {
-                    await new Promise((resolve) => setTimeout(resolve, 1));
+                const bytes = typeof chunk === "string" ? encoder.encode(chunk) : chunk;
+                let offset = 0;
+                while (this.pending?.id === id && offset < bytes.byteLength) {
+                    const free = stdin.free();
+                    if (free > 0) {
+                        const length = Math.min(free, bytes.byteLength - offset);
+                        stdin.write(bytes.subarray(offset, offset + length));
+                        offset += length;
+                    }
+                    else {
+                        await new Promise((resolve) => setTimeout(resolve, 1));
+                    }
                 }
                 if (this.pending?.id !== id)
                     return;
@@ -207,14 +368,22 @@ export class BrowserWaliWorkerProgram {
     terminate() {
         this.pending?.reject(new DOMException("The WALI program was terminated.", "AbortError"));
         this.finishPending();
-        this.worker.terminate();
+        this.worker?.terminate();
     }
     createWorker() {
-        const worker = new Worker(new URL("./worker-program-worker.js", import.meta.url), {
+        const worker = pageWorker(new Worker(new URL("./worker-program-worker.js", import.meta.url), {
             type: "module",
             name: "browser-wali-program",
+        }));
+        worker.addEventListener("message", (event) => {
+            void this.handleMessage(event.data).catch((cause) => {
+                if (this.pending?.id !== event.data.id)
+                    return;
+                this.pending.reject(cause);
+                this.finishPending();
+                this.resetWorker();
+            });
         });
-        worker.addEventListener("message", (event) => void this.handleMessage(event.data));
         worker.addEventListener("error", (event) => {
             this.pending?.reject(event.error ?? new Error(event.message));
             this.finishPending();
@@ -223,6 +392,12 @@ export class BrowserWaliWorkerProgram {
         return worker;
     }
     async handleMessage(message) {
+        if (message.type === "compiled") {
+            const key = compiledKey(this.program.url, this.program.integrity);
+            if (key)
+                compiledModules.set(key, message.compiled);
+            return;
+        }
         const pending = this.pending;
         if (!pending || message.id !== pending.id)
             return;
@@ -234,18 +409,46 @@ export class BrowserWaliWorkerProgram {
             this.emitStderr(pending, message.chunk);
             return;
         }
+        if (message.type === "diagnostic") {
+            pending.options.onDiagnostic?.(message.message);
+            return;
+        }
+        if (message.type === "fork") {
+            this.forkChild(message);
+            return;
+        }
         if (message.type === "spawn") {
             void this.spawnChild(message, pending);
             return;
         }
         if (message.type === "kill") {
-            this.childControllers.get(message.pid)?.abort(new DOMException(`Signal ${message.signal}`, "AbortError"));
+            const controller = this.childControllers.get(message.pid);
+            if (!controller)
+                return;
+            // a child that survived an earlier signal takes the next through its reason
+            if (controller.signal.aborted)
+                controller.signal.reason?.redeliver?.(message.signal);
+            else
+                controller.abort(signalAbortReason(message.signal, `Signal ${message.signal}`));
             return;
         }
+        console.log("[wali-boot]", JSON.stringify({ stage: "result-received", run: this.traceId, at: Date.now() }));
         const safeFilesystem = this.program.sanitizeFilesystem
             ? await this.program.sanitizeFilesystem(message.filesystem)
             : message.filesystem;
-        const patch = synchronizeFilesystem(this.filesystem, safeFilesystem);
+        if (message.filesystemFinalized)
+            await pending.filesystemFinalization;
+        await pending.filesystemQueue;
+        console.log("[wali-boot]", JSON.stringify({ stage: "filesystem-settled", run: this.traceId, at: Date.now() }));
+        if (this.pending !== pending)
+            return;
+        // A threaded process commits its final delta on the ordered update port.
+        // Its full snapshot may predate a peer import acknowledged on that port;
+        // diffing it against the advanced base would manufacture a deletion.
+        const patch = message.filesystemFinalized ? { files: [], removed: [] }
+            : createProcessFilesystemPatch(pending.filesystemBase, safeFilesystem);
+        if (!message.filesystemFinalized)
+            applyProcessFilesystemPatch(this.filesystem, patch, pending.filesystemBase);
         try {
             await this.program.onFilesystemCommit?.(this.filesystem, patch);
         }
@@ -255,6 +458,7 @@ export class BrowserWaliWorkerProgram {
             return;
         }
         this.finishPending();
+        console.log("[wali-boot]", JSON.stringify({ stage: "done", run: this.traceId, at: Date.now() }));
         if (message.result)
             pending.resolve({ ...message.result, stdout: pending.stdout, stderr: pending.stderr });
         else {
@@ -263,15 +467,76 @@ export class BrowserWaliWorkerProgram {
             pending.reject(new Error(streamedStderr ? `${streamedStderr}\n${detail}` : detail));
         }
     }
+    forkChild(message) {
+        const worker = pageWorker(new Worker(new URL("./fork-worker.js", import.meta.url), { type: "module", name: `wali-fork-${message.pid}` }));
+        this.forkWorkers.set(message.pid, worker);
+        const finish = () => { worker.terminate(); this.forkWorkers.delete(message.pid); };
+        worker.addEventListener("message", (event) => {
+            if (event.data.type === "fork-done") {
+                finish();
+                return;
+            }
+            void this.handleMessage(event.data).catch(error => {
+                this.pending?.reject(error);
+                this.finishPending();
+                this.resetWorker();
+            });
+        });
+        worker.addEventListener("error", event => {
+            this.pending?.reject(event.error ?? new Error(event.message));
+            this.finishPending();
+            this.resetWorker();
+        });
+        worker.postMessage(message, [message.descriptorTable.port,
+            ...(message.descriptorTable.releasePort ? [message.descriptorTable.releasePort] : []), message.forkState.memory]);
+    }
     async spawnChild(message, pending) {
         const backend = this.program.spawn;
         const controller = new AbortController();
         this.childControllers.set(message.pid, controller);
+        const trace = (stage) => console.log("[wali-boot]", JSON.stringify({ stage, run: this.traceId, child: message.pid, at: Date.now() }));
+        trace("spawn-received");
+        const releasePort = message.descriptorTable?.releasePort;
+        const descriptorTable = message.descriptorTable && {
+            port: message.descriptorTable.port, control: message.descriptorTable.control,
+            payload: message.descriptorTable.payload,
+            ...(message.descriptorTable.sharedPipes ? { sharedPipes: message.descriptorTable.sharedPipes } : {}),
+        };
+        let released;
+        const releaseDescriptors = () => released ??= releasePort ? new Promise((resolve) => {
+            releasePort.onmessage = () => { releasePort.close(); resolve(); };
+            releasePort.postMessage(true);
+        }) : Promise.resolve();
         let stdoutWrites = Promise.resolve();
         let stderrWrites = Promise.resolve();
         let stdoutStreamed = false;
         let stderrStreamed = false;
-        let childFilesystem = this.filesystem.toSnapshot();
+        // The child's patch is a diff of the tree before and after it ran; the
+        // diff needs sizes and times, and only the entries it names need bytes.
+        const metadataSnapshot = () => readBrowserFileSystemSnapshot(this.filesystem, "/", { metadataRoots: ["/"] });
+        const patchAgainst = async (before) => {
+            const patch = createProcessFilesystemPatch(before, await metadataSnapshot());
+            const previous = new Map(before.files.map((entry) => [entry.path, entry]));
+            const files = [];
+            const removed = new Set(patch.removed);
+            for (const entry of patch.files) {
+                const current = previous.get(entry.path);
+                const bytesMoved = entry.type === "file" && (!current || current.type !== "file"
+                    || current.size !== entry.size || current.mtimeMs !== entry.mtimeMs);
+                if (!bytesMoved) {
+                    files.push(entry);
+                    continue;
+                }
+                const captured = await readBrowserFileSystemEntry(this.filesystem, entry.path);
+                if (captured)
+                    files.push(captured);
+                else if (current)
+                    removed.add(entry.path);
+            }
+            return { files, removed: [...removed] };
+        };
+        let childFilesystem = await metadataSnapshot();
+        trace("spawn-snapshot");
         const stdout = (chunk) => {
             stdoutStreamed = true;
             if (message.stdout)
@@ -279,6 +544,10 @@ export class BrowserWaliWorkerProgram {
             else
                 this.emitStdout(pending, chunk);
         };
+        const stdoutBytes = (bytes) => {
+            stdoutStreamed = true;
+            stdoutWrites = stdoutWrites.then(() => writeSharedPipe(message.stdout, bytes));
+        };
         const stderr = (chunk) => {
             stderrStreamed = true;
             if (message.stderr)
@@ -289,35 +558,50 @@ export class BrowserWaliWorkerProgram {
         try {
             if (!backend)
                 throw new Error("No browser child-process backend is configured.");
+            const filesystemPolicy = pending.options.filesystemPolicy
+                ? intersectProcessFilesystemPolicies(pending.options.filesystemPolicy, message.filesystemPolicy)
+                : message.filesystemPolicy === undefined ? undefined : normalizeProcessFilesystemPolicy(message.filesystemPolicy);
+            requireProcessFilesystemPolicySupport(filesystemPolicy, backend.capabilities);
             const safePatch = this.program.sanitizeFilesystemPatch
                 ? await this.program.sanitizeFilesystemPatch(message.filesystemPatch)
                 : message.filesystemPatch;
-            applyProcessFilesystemPatch(this.filesystem, safePatch);
-            childFilesystem = this.filesystem.toSnapshot();
+            applyProcessFilesystemPatch(this.filesystem, safePatch, pending.filesystemBase);
+            pending.filesystemBase = patchedSnapshot(pending.filesystemBase, safePatch);
+            childFilesystem = await metadataSnapshot();
+            trace("spawn-patched");
             const stdinStream = message.stdin ? streamBrowserPipe(message.stdin, controller.signal) : undefined;
-            const result = await backend.run(browserCommand(message), {
+            const spawned = browserCommand(message);
+            const result = await backend.run(spawned.command, {
+                [browserProcessLineage]: { pid: message.pid, parentPid: message.parentPid, childPidAllocator: message.childPidAllocator },
+                ...(filesystemPolicy ? { filesystemPolicy } : {}),
+                ...(descriptorTable ? { descriptorTable } : {}),
                 cwd: message.cwd,
-                executablePath: message.executablePath,
-                env: message.env,
+                ...(spawned.executablePath ? { executablePath: spawned.executablePath } : {}),
+                env: message.inheritEnvironment ? { ...pending.options.env, ...this.program.env } : message.env,
                 ...(stdinStream ? { stdinStream } : {}),
                 signal: controller.signal,
+                ...(message.stdout ? { onStdoutBytes: stdoutBytes } : {}),
                 onStdout: stdout,
                 onStderr: stderr,
             });
-            // AlmostNode streams long-running commands, but may only return buffered
+            // Tabnode streams long-running commands, but may only return buffered
             // output for short commands. Deliver exactly one form to the child pipe.
             if (result.stdout && !stdoutStreamed)
                 stdout(result.stdout);
             if (result.stderr && !stderrStreamed)
                 stderr(result.stderr);
+            trace("spawn-ran");
             await Promise.all([stdoutWrites, stderrWrites]);
-            encodeProcessSnapshot(message, childFilesystem, this.filesystem.toSnapshot(), result.exitCode);
+            await releaseDescriptors();
+            encodeProcessPatch(message, await patchAgainst(childFilesystem), result.exitCode);
+            trace("spawn-returned");
         }
         catch (error) {
             const text = `${error instanceof Error ? error.message : String(error)}\n`;
             stderr(text);
             await stderrWrites;
-            encodeProcessSnapshot(message, childFilesystem, this.filesystem.toSnapshot(), controller.signal.aborted ? 130 : 127);
+            await releaseDescriptors();
+            encodeProcessPatch(message, await patchAgainst(childFilesystem), controller.signal.aborted ? 130 : 127);
         }
         finally {
             controller.abort(new DOMException("Browser child process completed.", "AbortError"));
@@ -329,14 +613,77 @@ export class BrowserWaliWorkerProgram {
     }
     async applyLiveFilesystemPatch(id, message) {
         const pending = this.pending;
-        if (!pending || pending.id !== id || message.type !== "filesystem")
+        if (!pending || pending.id !== id)
+            return;
+        if (message.type === "finalized") {
+            pending.filesystemFinalized = true;
+            pending.changedPaths.clear();
+            pending.releaseFilesystemChanges();
+            pending.resolveFilesystemFinalization();
+            return;
+        }
+        if (message.type === "checkpoint") {
+            // This method runs on the ordered filesystem queue, after prior writes
+            // and their durability callbacks have completed.
+            const control = new Int32Array(message.control);
+            Atomics.store(control, 0, 1);
+            Atomics.notify(control, 0);
+            return;
+        }
+        if (message.type === "imported") {
+            pending.filesystemBase = patchedSnapshot(pending.filesystemBase, message.patch);
+            pending.importingFilesystem = false;
+            this.scheduleFilesystemImport(pending);
+            return;
+        }
+        try {
+            if (message.type === "import-error")
+                throw new Error(message.message);
+            const safePatch = this.program.sanitizeFilesystemPatch
+                ? await this.program.sanitizeFilesystemPatch(message.patch)
+                : message.patch;
+            this.applyingFilesystem = true;
+            try {
+                applyProcessFilesystemPatch(this.filesystem, safePatch, pending.filesystemBase);
+            }
+            finally {
+                this.applyingFilesystem = false;
+            }
+            pending.filesystemBase = patchedSnapshot(pending.filesystemBase, safePatch);
+        }
+        catch (error) {
+            // THIS IS WHERE A LIVE PROGRAM BECOMES A DEAD ONE, and it is not an
+            // exit. `resetWorker()` terminates the worker from the HOST, so no
+            // guest exit path runs: instruments on `SYS_exit`, `SYS_exit_group` and
+            // musl's last-thread path are all silent through this, and the caller
+            // is told only that the program is gone.
+            //
+            // MEASURED 2026-09-19, the editor's Blender session on the WALI skew,
+            // the "one-session death" that had been attributed to a guest exit(0):
+            // it dies HERE, on `assertPatchBase`, at "write conflict at
+            // /work/.vgai-session/out/<n>.done". The directory channel's poll loop
+            // unlinks four files on the page after every answer, so a guest patch
+            // naming one of those paths crosses the page's own edit and the base
+            // the guest computed against no longer matches. Reproduced at session
+            // call 37 of a render loop (`base`: a file, `current`: null) and again
+            // at call 14 (`current`: the same file at a different mtime) -- the
+            // disagreement has more than one shape, which is why a targeted "drop
+            // the crossed paths" filter narrowed it without closing it (tried at
+            // both ends, reverted; it is not a one-line fix).
+            //
+            // The mechanism is a protocol one: TWO WRITERS SHARE ONE DIRECTORY with
+            // no ownership rule. The channel would not have this class of failure
+            // if the session owned its own files and the page only read them.
+            if (this.pending?.id !== id)
+                return;
+            this.finishPending();
+            this.resetWorker();
+            pending.reject(new Error(`WALI filesystem update could not be applied: ${error instanceof Error ? error.message : String(error)}`));
             return;
-        const safePatch = this.program.sanitizeFilesystemPatch
-            ? await this.program.sanitizeFilesystemPatch(message.patch)
-            : message.patch;
-        applyProcessFilesystemPatch(this.filesystem, safePatch);
+        }
         try {
-            await this.program.onFilesystemCommit?.(this.filesystem, message.patch);
+            if (message.type === "filesystem")
+                await this.program.onFilesystemCommit?.(this.filesystem, message.patch);
         }
         catch (error) {
             if (this.pending?.id !== id)
@@ -346,11 +693,52 @@ export class BrowserWaliWorkerProgram {
             pending.reject(new Error(`WALI filesystem durability barrier failed: ${error instanceof Error ? error.message : String(error)}`));
         }
     }
+    scheduleFilesystemImport(pending) {
+        if (pending.filesystemFinalized || pending.importingFilesystem || pending.changedPaths.size === 0 || this.pending !== pending)
+            return;
+        pending.importingFilesystem = true;
+        pending.filesystemQueue = pending.filesystemQueue.then(async () => {
+            if (this.pending !== pending)
+                return;
+            const paths = new Set(pending.changedPaths);
+            pending.changedPaths.clear();
+            const before = { files: pending.filesystemBase.files.filter((entry) => paths.has(entry.path)) };
+            const after = { files: [] };
+            // THE CHANGED PATHS, ONE AT A TIME, never the whole tree. This read a
+            // full `toSnapshot()` to pick two entries out of it, and a page-side
+            // snapshot carries every file's bytes as base64: measured 2026-09-19
+            // with Blender's 78 MB runtime tree in the page's filesystem, that is
+            // ~100 MB of string built and thrown away PER PAGE WRITE, and a
+            // directory-channel session writes twice per request.
+            for (const path of paths) {
+                const entry = await readBrowserFileSystemEntry(this.filesystem, path);
+                if (entry)
+                    after.files.push(entry);
+            }
+            if (this.pending !== pending)
+                return;
+            const patch = createProcessFilesystemPatch(before, after);
+            if (patch.files.length === 0 && patch.removed.length === 0) {
+                pending.importingFilesystem = false;
+                this.scheduleFilesystemImport(pending);
+                return;
+            }
+            this.filesystemUpdatePort?.postMessage({ type: "import", patch, base: before });
+        }).catch((error) => {
+            if (this.pending !== pending)
+                return;
+            this.finishPending();
+            this.resetWorker();
+            pending.reject(error);
+        });
+    }
     finishPending() {
+        this.pending?.resolveFilesystemFinalization();
         this.pending?.removeAbortListener();
         this.pending?.releaseLoopback();
         this.pending?.releaseFileLocks();
         this.pending?.releaseFileCoherence();
+        this.pending?.releaseFilesystemChanges();
         this.pending = undefined;
         this.stdin?.close();
         this.stdin = undefined;
@@ -364,9 +752,13 @@ export class BrowserWaliWorkerProgram {
         this.filesystemUpdatePort = undefined;
     }
     emitStdout(pending, chunk) {
-        pending.stdout += chunk;
-        this.scanOpenUrls(chunk);
-        pending.options.onStdout?.(chunk);
+        const text = typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+        pending.stdout += text;
+        this.scanOpenUrls(text);
+        if (typeof chunk !== "string" && pending.options.onStdoutBytes)
+            pending.options.onStdoutBytes(chunk);
+        else
+            pending.options.onStdout?.(text);
     }
     emitStderr(pending, chunk) {
         pending.stderr += chunk;
@@ -387,13 +779,33 @@ export class BrowserWaliWorkerProgram {
         this.urlScanTail = text.slice(-2048);
     }
     resetWorker() {
+        for (const worker of this.forkWorkers.values())
+            worker.terminate();
+        this.forkWorkers.clear();
         for (const controller of this.childControllers.values())
             controller.abort();
         this.childControllers.clear();
-        this.worker.terminate();
+        this.worker?.terminate();
         this.worker = this.createWorker();
     }
 }
+/**
+ * An abort that is a signal: the reason carries its number as `signal`, which
+ * the shell's `kill` and a process's own kill of a child set.
+ */
+export function signalAbortReason(signal, message) {
+    return Object.assign(new DOMException(message, "AbortError"), { signal });
+}
+function abortSignalNumber(reason) {
+    const signal = reason?.signal;
+    return typeof signal === "number" && Number.isInteger(signal) && signal > 0 && signal <= 64 ? signal : 9;
+}
+/**
+ * The process host's command for a spawn. A shell is handed over whole, as
+ * its argv, so the host reads its line and the `$0` and positional arguments
+ * after it (`sh -c '"$@"' editor file`); the path it was exec'd at named the
+ * shell, not what the line runs, so it does not go with it.
+ */
 function browserCommand(message) {
     const [program = "", ...args] = message.argv;
     const executable = message.executablePath || program;
@@ -404,22 +816,24 @@ function browserCommand(message) {
         if (script?.includes("__grok_user_cmd")) {
             const separator = args.indexOf("--", commandIndex + 2);
             if (separator >= 0 && args[separator + 1])
-                return args[separator + 1];
+                return { command: args[separator + 1] };
         }
-        if (script !== undefined)
-            return script;
         // The browser shell is a registered process-host executable, not a file
-        // at the native harness's host-specific absolute path. Preserve argv but
-        // route probes such as `/bin/bash --version` through that executable.
-        return [basename, ...args].map(shellQuote).join(" ");
+        // at the native harness's host-specific absolute path, so the shell goes
+        // by its name: `/bin/bash --version` is `bash --version`.
+        return { command: [basename, ...args].map(shellQuote).join(" ") };
     }
-    return message.argv.map(shellQuote).join(" ");
+    return { command: message.argv.map(shellQuote).join(" "), ...(message.executablePath ? { executablePath: message.executablePath } : {}) };
 }
 function shellQuote(value) {
     if (/^[A-Za-z0-9_./:+,@%=-]+$/u.test(value))
         return value;
     return `'${value.replaceAll("'", `'\\''`)}'`;
 }
+/** The WALI lane's own field on a run option's descriptor channel. */
+function inheritedSharedPipes(channel) {
+    return channel?.sharedPipes;
+}
 function closeExternalPipe(handle) {
     if (handle)
         closeSharedPipe(handle);
@@ -440,9 +854,4 @@ async function* streamBrowserPipe(handle, signal) {
     if (signal.aborted)
         throw signal.reason;
 }
-function synchronizeFilesystem(target, snapshot) {
-    const patch = createProcessFilesystemPatch(target.toSnapshot(), snapshot);
-    applyProcessFilesystemPatch(target, patch);
-    return patch;
-}
 //# sourceMappingURL=worker-program.js.map