@rivet-dev/agentos-core 0.0.0-abc-fixes-1.d8c4d95 → 0.0.0-agent-acp-codex-session-benchmark.62b1f46

package/dist/sidecar/rpc-client.js

@@ -1,20 +1,34 @@
 import { randomUUID } from "node:crypto";
 import { constants as osConstants } from "node:os";
 import { posix as posixPath } from "node:path";
-const SYNTHETIC_PID_BASE = 1_000_000;
-const MISSING_EXIT_EVENT_GRACE_MS = 500;
-const PROTECTED_READ_ONLY_GUEST_ROOTS = ["/etc/agentos"];
-const TRAILING_OUTPUT_DRAIN_INTERVAL_MS = 10;
-const TRAILING_OUTPUT_DRAIN_MAX_MS = 250;
-const TRAILING_OUTPUT_DRAIN_QUIET_TURNS = 2;
-async function drainTrailingProcessOutputTurn(delayMs = 0) {
-    // Native-sidecar `process_output` events can lag one macrotask behind the
-    // terminal `process_exited` notification for very short-lived processes, and
-    // under suite load the sidecar event pump can need a little extra time to
-    // flush delayed output through its listener callbacks.
-    await new Promise((resolve) => {
-        setTimeout(resolve, delayMs);
-    });
+function shouldLogStructuredSidecarEvent(name) {
+    const normalized = name.toLowerCase();
+    return (normalized === "limit_warning" ||
+        normalized.startsWith("security.") ||
+        normalized.includes("warning") ||
+        normalized.includes("failed") ||
+        normalized.includes("error"));
+}
+function decodeUtf8(data) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8");
+}
+function formatStructuredSidecarDetail(detail) {
+    const entries = Object.entries(detail);
+    if (entries.length === 0) {
+        return "";
+    }
+    return entries
+        .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+        .join(" ");
+}
+function logStructuredSidecarEvent(name, detail) {
+    if (!shouldLogStructuredSidecarEvent(name)) {
+        return;
+    }
+    const formatted = formatStructuredSidecarDetail(detail);
+    console.warn(formatted
+        ? `[agent-os] sidecar ${name}: ${formatted}`
+        : `[agent-os] sidecar ${name}`);
 }
 const PREFERRED_SIGNAL_NAMES = [
     "SIGHUP",
@@ -58,98 +72,6 @@ const NON_CANONICAL_SIGNAL_NAMES = new Set([
     "SIGUNUSED",
 ]);
 const SIGNAL_NAME_BY_NUMBER = buildSignalNameByNumber();
-const DOUBLE_QUOTE_ESCAPABLE_CHARACTERS = new Set(['"', "\\", "$", "`"]);
-function appendDoubleQuotedEscape(current, character) {
-    if (DOUBLE_QUOTE_ESCAPABLE_CHARACTERS.has(character)) {
-        return current + character;
-    }
-    if (character === "\n") {
-        return current;
-    }
-    return `${current}\\${character}`;
-}
-function parseSimpleExecCommand(command) {
-    const tokens = [];
-    let current = "";
-    let quote = null;
-    let escaped = false;
-    for (const character of command) {
-        if (quote === null) {
-            if (escaped) {
-                current += character;
-                escaped = false;
-                continue;
-            }
-            if (character === "\\") {
-                escaped = true;
-                continue;
-            }
-            if (character === "'" || character === '"') {
-                quote = character;
-                continue;
-            }
-            if (/\s/.test(character)) {
-                if (current) {
-                    tokens.push(current);
-                    current = "";
-                }
-                continue;
-            }
-            if ("|&;<>()$`*?[]{}~!".includes(character)) {
-                return null;
-            }
-            current += character;
-            continue;
-        }
-        if (quote === "'") {
-            if (character === "'") {
-                quote = null;
-                continue;
-            }
-            current += character;
-            continue;
-        }
-        if (escaped) {
-            current = appendDoubleQuotedEscape(current, character);
-            escaped = false;
-            continue;
-        }
-        if (character === "\\") {
-            escaped = true;
-            continue;
-        }
-        if (character === '"') {
-            quote = null;
-            continue;
-        }
-        if (character === "$" || character === "`") {
-            return null;
-        }
-        current += character;
-    }
-    if (quote !== null || escaped) {
-        return null;
-    }
-    if (current) {
-        tokens.push(current);
-    }
-    if (tokens.length === 0) {
-        return null;
-    }
-    if (tokens.some((token) => token.length === 0)) {
-        return null;
-    }
-    return tokens;
-}
-function canUseDirectExec(driver, commandName) {
-    return driver === "wasmvm" || (driver === "node" && commandName === "node");
-}
-function shellSingleQuote(value) {
-    if (value.length === 0) {
-        return "''";
-    }
-    return `'${value.replace(/'/g, `'"'"'`)}'`;
-}
 function buildSignalNameByNumber() {
     const signals = osConstants.signals;
     const names = new Map();
@@ -171,79 +93,110 @@ function buildSignalNameByNumber() {
 export function toSidecarSignalName(signal) {
     return SIGNAL_NAME_BY_NUMBER.get(signal) ?? String(signal);
 }
+function toSidecarTimeoutMs(timeout) {
+    if (timeout === undefined) {
+        return undefined;
+    }
+    if (!Number.isFinite(timeout) || timeout < 0) {
+        throw new RangeError("process timeout must be a finite non-negative number");
+    }
+    return Math.trunc(timeout);
+}
+const processCompletion = Symbol("agentos.processCompletion");
 export class NativeSidecarKernelProxy {
     env;
     cwd;
-    commands;
     vfs;
     processes = new Map();
-    defaultExecCwd;
     client;
     session;
     vm;
+    ownsClient;
     localMounts;
-    commandDrivers;
-    onWasmCommandResolved;
+    baseSidecarMounts;
     onDispose;
     trackedProcesses = new Map();
     trackedProcessesById = new Map();
-    listenerLookups = new Map();
-    boundUdpLookups = new Map();
-    signalStates = new Map();
-    signalRefreshes = new Map();
-    sidecarProcessSnapshot = [];
     processSnapshotRefresh = null;
-    observedProcessStartTimes = new Map();
     rootView;
-    zombieTimerCountValue = 0;
-    zombieTimerCountRefresh = null;
     disposed = false;
+    disposePromise = null;
     pumpError = null;
-    nextSyntheticPid = SYNTHETIC_PID_BASE;
+    mountReconfigurePromise = null;
     eventPumpAbortController = new AbortController();
     eventPump;
     constructor(options) {
         this.client = options.client;
         this.session = options.session;
         this.vm = options.vm;
+        this.ownsClient = options.ownsClient ?? true;
         this.env = { ...options.env };
         this.cwd = options.cwd;
-        this.defaultExecCwd = options.defaultExecCwd;
         this.localMounts = [...options.localMounts].sort((left, right) => right.path.length - left.path.length);
-        this.commandDrivers = buildCommandMap(options.commandGuestPaths);
-        this.onWasmCommandResolved = options.onWasmCommandResolved;
+        const localMountPaths = new Set(this.localMounts.map((mount) => mount.path));
+        this.baseSidecarMounts = options.sidecarMounts.filter((mount) => mount.plugin.id !== "js_bridge" ||
+            !localMountPaths.has(posixPath.normalize(mount.guestPath)));
         this.onDispose = options.onDispose;
-        this.commands = this.commandDrivers;
-        this.vfs = this.createFilesystemView(true);
-        this.rootView = this.createFilesystemView(false);
+        this.vfs = this.createFilesystemView();
+        this.rootView = this.vfs;
         this.eventPump = this.runEventPump();
-        void this.eventPump.catch(() => { });
+        void this.eventPump;
     }
     createRootView() {
         return this.rootView;
     }
-    get zombieTimerCount() {
-        if (!this.zombieTimerCountRefresh) {
-            this.zombieTimerCountRefresh = this.refreshZombieTimerCount();
-        }
-        return this.zombieTimerCountValue;
-    }
-    registerCommandGuestPaths(commandGuestPaths) {
-        for (const name of commandGuestPaths.keys()) {
-            this.commandDrivers.set(name, "wasmvm");
-        }
+    /** Resolve the host-only backing store for an exact js_bridge mount id. */
+    hostFilesystemForMount(mountId) {
+        const normalized = posixPath.normalize(mountId);
+        return this.localMounts.find((mount) => mount.path === normalized)?.fs;
     }
     async dispose() {
         if (this.disposed) {
             return;
         }
+        if (this.disposePromise) {
+            return this.disposePromise;
+        }
+        const attempt = this.disposeOnce();
+        this.disposePromise = attempt;
+        try {
+            await attempt;
+        }
+        finally {
+            if (this.disposePromise === attempt) {
+                this.disposePromise = null;
+            }
+        }
+    }
+    async disposeOnce() {
+        const errors = [];
+        try {
+            await this.mountReconfigurePromise;
+        }
+        catch (error) {
+            errors.push(toError(error));
+        }
+        const liveProcesses = [...this.trackedProcessesById.values()].filter((entry) => !entry.settled);
+        const signalResults = await Promise.allSettled(liveProcesses.map((entry) => this.signalProcess(entry, 15)));
+        for (const result of signalResults) {
+            if (result.status === "rejected") {
+                errors.push(toError(result.reason));
+            }
+        }
+        try {
+            await this.client.disposeVm(this.session, this.vm);
+        }
+        catch (error) {
+            errors.push(toError(error));
+            throw new AggregateError(errors, "failed to dispose sidecar VM");
+        }
+        // Remote disposal is authoritative. Only now make local teardown
+        // irreversible; a rejected/failed request leaves the route and lease live so
+        // the caller can retry without manufacturing local success.
         this.disposed = true;
         this.eventPumpAbortController.abort();
-        const liveProcesses = [...this.trackedProcesses.values()].filter((entry) => entry.exitCode === null);
-        await Promise.allSettled(liveProcesses.map((entry) => this.signalProcess(entry, 15)));
-        await this.client.disposeVm(this.session, this.vm).catch(() => { });
         for (const entry of liveProcesses) {
-            if (entry.exitCode === null) {
+            if (!entry.settled) {
                 // The sidecar dispose path already performs TERM/KILL escalation for any
                 // guest executions that are still live. Resolve local waiters eagerly so
                 // VM teardown does not hang on killed ACP adapter processes that never
@@ -251,191 +204,107 @@ export class NativeSidecarKernelProxy {
                 this.finishProcess(entry, 143);
             }
         }
-        await this.client.dispose().catch(() => { });
-        await this.eventPump.catch(() => { });
-        await this.onDispose?.().catch(() => { });
-    }
-    async exec(command, options) {
-        if (!this.commands.has("sh")) {
-            throw new Error(`native sidecar exec requires guest shell command 'sh': ${command}`);
-        }
-        const stdoutChunks = [];
-        const stderrChunks = [];
-        const effectiveCwd = options?.cwd ?? this.defaultExecCwd ?? this.cwd;
-        const parsedCommand = parseSimpleExecCommand(command);
-        const resolveExecPath = (targetPath) => targetPath.startsWith("/")
-            ? posixPath.normalize(targetPath)
-            : posixPath.normalize(posixPath.join(effectiveCwd, targetPath));
-        const runAndCapture = async (proc, stdinOverride, readExitCode) => {
-            if (stdinOverride !== undefined) {
-                proc.writeStdin(stdinOverride);
-            }
-            else if (options?.stdin !== undefined) {
-                proc.writeStdin(options.stdin);
+        // Only tear down the shared sidecar process when this proxy owns it. VMs
+        // leased from an `AgentOsSidecar` handle share one process, which is
+        // disposed when the handle is disposed.
+        if (this.ownsClient) {
+            try {
+                await this.client.dispose();
             }
-            // `kernel.exec()` is a non-interactive run-to-completion API: when the
-            // caller does not opt into a streaming stdin handle, the guest process
-            // should observe EOF after any provided input so commands like
-            // `node -e ...` do not linger behind an inherited open stdin pipe.
-            proc.closeStdin();
-            const waitPromise = proc.wait();
-            const shellExitCode = typeof options?.timeout === "number"
-                ? await new Promise((resolve) => {
-                    const timer = setTimeout(() => {
-                        proc.kill(9);
-                        void proc.wait().then(resolve);
-                    }, options.timeout);
-                    void waitPromise.then((code) => {
-                        clearTimeout(timer);
-                        resolve(code);
-                    });
-                })
-                : await waitPromise;
-            const exitCode = readExitCode
-                ? await readExitCode().catch(() => shellExitCode)
-                : shellExitCode;
-            await drainTrailingProcessOutputTurn();
-            return {
-                exitCode,
-                stdout: Buffer.concat(stdoutChunks.map((chunk) => Buffer.from(chunk))).toString("utf8"),
-                stderr: Buffer.concat(stderrChunks.map((chunk) => Buffer.from(chunk))).toString("utf8"),
-            };
-        };
-        if (parsedCommand &&
-            (parsedCommand[0] === "sh" || parsedCommand[0] === "/bin/sh") &&
-            parsedCommand[1] === "-c" &&
-            parsedCommand.length === 3) {
-            const shellScript = parsedCommand[2].trim();
-            const exitMatch = shellScript.match(/^exit(?:\s+(-?\d+))?$/);
-            if (exitMatch) {
-                return {
-                    exitCode: Number.parseInt(exitMatch[1] ?? "0", 10),
-                    stdout: "",
-                    stderr: "",
-                };
+            catch (error) {
+                errors.push(toError(error));
             }
-            return this.exec(parsedCommand[2], options);
         }
-        if (parsedCommand &&
-            parsedCommand[0] === "chmod" &&
-            parsedCommand.length >= 3 &&
-            /^[0-7]{3,4}$/.test(parsedCommand[1] ?? "")) {
-            const mode = Number.parseInt(parsedCommand[1], 8);
-            for (const target of parsedCommand.slice(2)) {
-                await this.client.chmod(this.session, this.vm, resolveExecPath(target), mode);
-            }
-            return { exitCode: 0, stdout: "", stderr: "" };
+        try {
+            await this.eventPump;
         }
-        if (parsedCommand &&
-            parsedCommand[0] === "stat" &&
-            parsedCommand.length === 4 &&
-            parsedCommand[1] === "-c" &&
-            parsedCommand[2] === "%a") {
-            const stat = await this.stat(resolveExecPath(parsedCommand[3]));
-            return {
-                exitCode: 0,
-                stdout: `${(stat.mode & 0o777).toString(8)}\n`,
-                stderr: "",
-            };
+        catch (error) {
+            errors.push(toError(error));
         }
-        const parsedCommandDriver = parsedCommand
-            ? this.commands.get(parsedCommand[0])
-            : undefined;
-        const requiresShellWrappedWasmCwd = parsedCommandDriver === "wasmvm" && parsedCommand?.[0] === "pwd";
-        if (parsedCommand &&
-            parsedCommandDriver &&
-            canUseDirectExec(parsedCommandDriver, parsedCommand[0]) &&
-            !requiresShellWrappedWasmCwd) {
-            if (parsedCommandDriver === "wasmvm") {
-                this.onWasmCommandResolved?.(parsedCommand[0]);
-            }
-            return runAndCapture(this.spawn(parsedCommand[0], parsedCommand.slice(1), {
-                ...options,
-                cwd: effectiveCwd,
-                onStdout: (chunk) => {
-                    stdoutChunks.push(chunk);
-                    options?.onStdout?.(chunk);
-                },
-                onStderr: (chunk) => {
-                    stderrChunks.push(chunk);
-                    options?.onStderr?.(chunk);
-                },
-            }));
+        try {
+            await this.onDispose?.();
+        }
+        catch (error) {
+            errors.push(toError(error));
+        }
+        // Drop all per-VM tracking state so a disposed proxy retains nothing.
+        for (const entry of this.trackedProcesses.values()) {
+            entry.onStdout.clear();
+            entry.onStderr.clear();
+        }
+        this.trackedProcesses.clear();
+        this.trackedProcessesById.clear();
+        this.localMounts.length = 0;
+        if (errors.length > 0) {
+            throw new AggregateError(errors, "failed to dispose sidecar VM");
         }
-        const proc = this.spawn("sh", ["-c", command], {
-            ...options,
-            cwd: effectiveCwd,
-            onStdout: (chunk) => {
-                stdoutChunks.push(chunk);
-                options?.onStdout?.(chunk);
-            },
-            onStderr: (chunk) => {
-                stderrChunks.push(chunk);
-                options?.onStderr?.(chunk);
-            },
-        });
-        return runAndCapture(proc);
+    }
+    /** Test-only snapshot of the per-VM tracking collection sizes. */
+    __trackingSizesForTest() {
+        return {
+            trackedProcesses: this.trackedProcesses.size,
+            trackedProcessesById: this.trackedProcessesById.size,
+            localMounts: this.localMounts.length,
+        };
+    }
+    /** Test-only handle to a tracked entry so its listener Sets can be inspected. */
+    __trackedEntryForTest(pid) {
+        return this.trackedProcesses.get(pid);
+    }
+    async exec(command, options) {
+        const captureOutput = options?.captureStdio !== false;
+        const proc = (await this.spawnTracked("sh", [], {
+            env: options?.env,
+            cwd: options?.cwd,
+            timeout: options?.timeout,
+            onStdout: options?.onStdout,
+            onStderr: options?.onStderr,
+            shellCommand: command,
+            captureOutput,
+        }));
+        if (options?.stdin !== undefined) {
+            await proc.writeStdin(options.stdin);
+        }
+        await proc.closeStdin();
+        const completion = await proc[processCompletion];
+        return {
+            exitCode: completion.exitCode,
+            stdout: decodeUtf8(completion.stdout),
+            stderr: decodeUtf8(completion.stderr),
+        };
     }
     async execArgv(command, args = [], options) {
-        const stdoutChunks = [];
-        const stderrChunks = [];
-        const effectiveCwd = options?.cwd ?? this.defaultExecCwd ?? this.cwd;
+        const captureOutput = options?.captureStdio !== false;
+        const requestedCwd = options?.cwd;
         const runAndCapture = async (proc) => {
             if (options?.stdin !== undefined) {
-                proc.writeStdin(options.stdin);
+                await proc.writeStdin(options.stdin);
             }
-            proc.closeStdin();
-            const waitPromise = proc.wait();
-            const exitCode = typeof options?.timeout === "number"
-                ? await new Promise((resolve) => {
-                    const timer = setTimeout(() => {
-                        proc.kill(9);
-                        void proc.wait().then(resolve);
-                    }, options.timeout);
-                    void waitPromise.then((code) => {
-                        clearTimeout(timer);
-                        resolve(code);
-                    });
-                })
-                : await waitPromise;
-            await drainTrailingProcessOutputTurn();
+            await proc.closeStdin();
+            const completion = await proc[processCompletion];
             return {
-                exitCode,
-                stdout: Buffer.concat(stdoutChunks.map((chunk) => Buffer.from(chunk))).toString("utf8"),
-                stderr: Buffer.concat(stderrChunks.map((chunk) => Buffer.from(chunk))).toString("utf8"),
+                exitCode: completion.exitCode,
+                stdout: decodeUtf8(completion.stdout),
+                stderr: decodeUtf8(completion.stderr),
             };
         };
-        if (this.commands.get(command) === "wasmvm") {
-            this.onWasmCommandResolved?.(command);
-        }
-        return runAndCapture(this.spawn(command, [...args], {
-            ...options,
-            cwd: effectiveCwd,
-            onStdout: (chunk) => {
-                stdoutChunks.push(chunk);
-                options?.onStdout?.(chunk);
-            },
-            onStderr: (chunk) => {
-                stderrChunks.push(chunk);
-                options?.onStderr?.(chunk);
-            },
+        const proc = (await this.spawnTracked(command, [...args], {
+            env: options?.env,
+            cwd: requestedCwd,
+            timeout: options?.timeout,
+            onStdout: options?.onStdout,
+            onStderr: options?.onStderr,
+            captureOutput,
         }));
+        return runAndCapture(proc);
     }
-    spawn(command, args, options) {
-        let spawnCommand = command;
-        let spawnArgs = [...args];
-        const shellOption = options?.shell;
-        if (shellOption === true || typeof shellOption === "string") {
-            // Node's shell mode hands the raw command line to the shell. Shell
-            // grammar belongs to the guest shell, so the bridge never parses it.
-            if (!this.commands.has("sh")) {
-                throw new Error(`native sidecar shell-mode spawn requires guest shell command 'sh': ${command}`);
-            }
-            spawnCommand = "sh";
-            spawnArgs = ["-c", [command, ...args].join(" ")];
-        }
-        const pid = this.nextSyntheticPid++;
-        const processId = `proc-${pid}`;
+    async spawn(command, args, options) {
+        return this.spawnTracked(command, args, options);
+    }
+    async spawnTracked(command, args, options) {
+        const spawnCommand = command;
+        const spawnArgs = [...args];
+        const shellCommand = options?.shellCommand;
         let resolveWait;
         let rejectWait;
         const waitPromise = new Promise((resolve, reject) => {
@@ -443,437 +312,85 @@ export class NativeSidecarKernelProxy {
             rejectWait = reject;
         });
         const entry = {
-            pid,
-            processId,
-            command: spawnCommand,
+            pid: null,
+            processId: null,
+            command: shellCommand === undefined ? spawnCommand : undefined,
+            shellCommand,
             args: spawnArgs,
-            driver: spawnCommand === "node" ? "node" : "wasmvm",
-            cwd: options?.cwd ?? this.cwd,
-            env: {
-                ...(options?.env ?? {}),
-                ...(options?.streamStdin ? { SECURE_EXEC_KEEP_STDIN_OPEN: "1" } : {}),
-            },
-            startTime: Date.now(),
-            exitTime: null,
-            hostPid: null,
+            requestedCwd: options?.cwd,
+            pty: options?.pty,
+            env: options?.env ? { ...options.env } : undefined,
+            keepStdinOpen: options?.streamStdin,
+            timeoutMs: toSidecarTimeoutMs(options?.timeout),
+            captureOutput: options?.captureOutput,
             exitCode: null,
-            started: false,
-            startPromise: Promise.resolve(),
             waitPromise,
             resolveWait,
             rejectWait,
+            settled: false,
             onStdout: new Set(options?.onStdout ? [options.onStdout] : []),
             onStderr: new Set(options?.onStderr ? [options.onStderr] : []),
-            pendingStdin: [],
-            stdinFlushPromise: null,
-            pendingCloseStdin: false,
-            pendingKillSignal: null,
-            waitWithFallbackPromise: null,
-            hostExitObservedAt: null,
-            outputGeneration: 0,
         };
-        this.trackedProcesses.set(pid, entry);
-        this.trackedProcessesById.set(processId, entry);
-        this.updateTrackedProcessSnapshot(entry);
+        await this.startTrackedProcess(entry);
+        if (entry.pid === null) {
+            throw new Error("sidecar did not return a kernel pid for the process");
+        }
+        const pid = entry.pid;
         const proc = {
+            [processCompletion]: waitPromise,
             pid,
-            writeStdin: (data) => {
+            writeStdin: async (data) => {
                 if (entry.exitCode !== null) {
                     return;
                 }
-                entry.pendingStdin.push(data);
-                void this.flushPendingStdin(entry).catch((error) => {
-                    this.handleBackgroundProcessError(entry, error);
-                });
+                await this.client.writeStdin(this.session, this.vm, this.processIdFor(entry), data);
             },
-            closeStdin: () => {
-                entry.pendingCloseStdin = true;
-                void this.closeTrackedStdin(entry).catch((error) => {
-                    this.handleBackgroundProcessError(entry, error);
-                });
-            },
-            kill: (signal = 15) => {
+            closeStdin: async () => {
                 if (entry.exitCode !== null) {
                     return;
                 }
-                entry.pendingKillSignal = signal;
-                void entry.startPromise.then(async () => {
-                    if (entry.exitCode !== null || entry.pendingKillSignal === null) {
-                        return;
-                    }
-                    const pendingSignal = entry.pendingKillSignal;
-                    entry.pendingKillSignal = null;
-                    await this.signalProcess(entry, pendingSignal);
-                });
-            },
-            wait: async () => {
-                const exitCode = await this.waitForTrackedProcess(entry);
-                await this.drainTrailingProcessOutput(entry);
-                return exitCode;
+                await this.client.closeStdin(this.session, this.vm, this.processIdFor(entry));
             },
+            kill: (signal = 15) => this.signalProcess(entry, signal),
+            wait: () => this.waitForTrackedProcess(entry),
             get exitCode() {
                 return entry.exitCode;
             },
         };
-        entry.startPromise = this.startTrackedProcess(entry).catch((error) => {
-            const normalized = error instanceof Error ? error : new Error(String(error));
-            const stderr = new TextEncoder().encode(`${normalized.message}\n`);
-            for (const handler of entry.onStderr) {
-                handler(stderr);
-            }
-            this.finishProcess(entry, 1);
-        });
         return proc;
     }
-    openShell(options) {
+    async openShell(options) {
         const stdoutHandlers = new Set();
         const stderrHandlers = new Set();
-        const command = options?.command ?? "sh";
-        const args = options?.args ??
-            (command === "sh" || command === "/bin/sh" ? ["-i"] : []);
-        const synthesizePrompt = !options?.command && !options?.args;
-        const autoCloseExplicitCommandStdin = Boolean(options?.command) && !["sh", "/bin/sh", "bash"].includes(command);
-        const promptText = "sh-0.4$ ";
-        const textEncoder = new TextEncoder();
-        const textDecoder = new TextDecoder();
-        const execCommand = this.exec.bind(this);
-        const spawnCommand = this.spawn.bind(this);
-        const sanitizeSyntheticShellText = (value) => value
-            .replace(/\u001b\[[0-9;]*m/g, "")
-            .replace(/^.*WARN could not retrieve pid for child process\n?/gm, "")
-            .replace(/^ProcessExitError:.*\n(?:\s+at .*\n)*/gm, "");
-        let bufferedInput = "";
-        let bufferedCommand = "";
-        let activeForegroundProcess = null;
-        let shellEnv = { ...(options?.env ?? {}) };
-        let shellCwd = options?.cwd ?? this.cwd;
-        let syntheticCommandQueue = Promise.resolve();
-        let promptTimer = null;
-        let closeStdinTimer = null;
-        let commandInFlight = false;
-        let syntheticCursorAtLineStart = true;
-        const syntheticPid = this.nextSyntheticPid++;
-        let syntheticExitCode = null;
-        let resolveSyntheticWait;
-        const syntheticWaitPromise = new Promise((resolve) => {
-            resolveSyntheticWait = resolve;
-        });
-        const clearPromptTimer = () => {
-            if (promptTimer !== null) {
-                clearTimeout(promptTimer);
-                promptTimer = null;
-            }
-        };
-        const clearCloseStdinTimer = () => {
-            if (closeStdinTimer !== null) {
-                clearTimeout(closeStdinTimer);
-                closeStdinTimer = null;
-            }
-        };
-        const normalizeSyntheticTerminalText = (text) => text.replace(/\r?\n/g, "\r\n");
-        const updateSyntheticCursor = (text) => {
-            if (!text) {
-                return;
-            }
-            syntheticCursorAtLineStart = /(?:\r\n)$/.test(text);
-        };
-        const emitSyntheticStdout = (text) => {
-            if (!text) {
-                return;
-            }
-            const normalized = normalizeSyntheticTerminalText(text);
-            updateSyntheticCursor(normalized);
-            const chunk = textEncoder.encode(normalized);
-            for (const handler of stdoutHandlers) {
-                handler(chunk);
-            }
-        };
-        const emitSyntheticTerminal = (text) => {
-            if (!text) {
-                return;
-            }
-            const normalized = normalizeSyntheticTerminalText(text);
-            updateSyntheticCursor(normalized);
-            const chunk = textEncoder.encode(normalized);
-            for (const handler of stdoutHandlers) {
-                handler(chunk);
-            }
-        };
-        const finishSyntheticShell = (exitCode) => {
-            if (syntheticExitCode !== null) {
-                return;
-            }
-            syntheticExitCode = exitCode;
-            clearPromptTimer();
-            resolveSyntheticWait(exitCode);
-        };
-        const commandNeedsContinuation = (source) => {
-            let singleQuoted = false;
-            let doubleQuoted = false;
-            let escaped = false;
-            for (const character of source) {
-                if (escaped) {
-                    escaped = false;
-                    continue;
-                }
-                if (character === "\\") {
-                    escaped = true;
-                    continue;
-                }
-                if (!doubleQuoted && character === "'") {
-                    singleQuoted = !singleQuoted;
-                    continue;
-                }
-                if (!singleQuoted && character === '"') {
-                    doubleQuoted = !doubleQuoted;
-                }
-            }
-            return singleQuoted || doubleQuoted || escaped;
-        };
-        const emitPrompt = () => {
-            if (!synthesizePrompt) {
-                return;
-            }
-            if (syntheticExitCode !== null) {
-                return;
-            }
-            commandInFlight = false;
-            const promptPrefix = syntheticCursorAtLineStart ? "" : "\r\n";
-            const promptChunk = textEncoder.encode(`${promptPrefix}${promptText}`);
-            for (const handler of stdoutHandlers) {
-                handler(promptChunk);
-            }
-            syntheticCursorAtLineStart = false;
-        };
-        const schedulePrompt = (delayMs) => {
-            if (!synthesizePrompt) {
-                return;
-            }
-            clearPromptTimer();
-            promptTimer = setTimeout(() => {
-                promptTimer = null;
-                emitPrompt();
-            }, delayMs);
-        };
-        const parseForegroundCommand = (source) => {
-            const parsed = parseSimpleExecCommand(source);
-            const driver = parsed ? this.commands.get(parsed[0]) : undefined;
-            if (!parsed ||
-                !canUseDirectExec(driver, parsed[0]) ||
-                (driver === "wasmvm" && parsed[0] === "pwd")) {
-                return null;
-            }
-            return parsed;
-        };
-        const writeForegroundInput = (proc, data) => {
-            if (typeof data === "string") {
-                for (const character of data) {
-                    proc.writeStdin(character);
-                }
-                return;
-            }
-            for (const byte of data) {
-                proc.writeStdin(new Uint8Array([byte]));
-            }
-        };
         let onData = null;
         stdoutHandlers.add((data) => onData?.(data));
         if (options?.onStderr) {
             stderrHandlers.add(options.onStderr);
         }
-        if (synthesizePrompt) {
-            schedulePrompt(0);
-            return {
-                pid: syntheticPid,
-                write(data) {
-                    if (syntheticExitCode !== null) {
-                        return;
-                    }
-                    if (activeForegroundProcess) {
-                        const rawText = typeof data === "string"
-                            ? data
-                            : Buffer.from(data).toString("utf8");
-                        if (rawText.includes("\u0003")) {
-                            const [beforeInterrupt] = rawText.split("\u0003");
-                            if (beforeInterrupt) {
-                                writeForegroundInput(activeForegroundProcess, beforeInterrupt);
-                            }
-                            emitSyntheticTerminal("^C\n");
-                            activeForegroundProcess.kill(2);
-                            return;
-                        }
-                        writeForegroundInput(activeForegroundProcess, data);
-                        return;
-                    }
-                    const rawText = typeof data === "string"
-                        ? data
-                        : Buffer.from(data).toString("utf8");
-                    let text = rawText;
-                    if (rawText.includes("\u0003")) {
-                        const segments = rawText.split("\u0003");
-                        bufferedInput = "";
-                        bufferedCommand = "";
-                        for (let index = 0; index < segments.length - 1; index += 1) {
-                            emitSyntheticTerminal("^C\n");
-                            emitPrompt();
-                        }
-                        text = segments[segments.length - 1] ?? "";
-                    }
-                    if (text.includes("\u0004") &&
-                        bufferedInput.length === 0 &&
-                        bufferedCommand.length === 0) {
-                        finishSyntheticShell(0);
-                        return;
-                    }
-                    bufferedInput += text.replace(/\u0004/g, "");
-                    while (true) {
-                        const newlineIndex = bufferedInput.indexOf("\n");
-                        if (newlineIndex < 0) {
-                            break;
-                        }
-                        const line = bufferedInput
-                            .slice(0, newlineIndex)
-                            .replace(/\r$/, "");
-                        bufferedInput = bufferedInput.slice(newlineIndex + 1);
-                        emitSyntheticStdout(`${line}\n`);
-                        const nextCommand = bufferedCommand
-                            ? `${bufferedCommand}\n${line}`
-                            : line;
-                        if (commandNeedsContinuation(nextCommand)) {
-                            bufferedCommand = nextCommand;
-                            continue;
-                        }
-                        bufferedCommand = "";
-                        syntheticCommandQueue = syntheticCommandQueue
-                            .then(async () => {
-                            const trimmed = nextCommand.trim();
-                            if (!trimmed) {
-                                emitPrompt();
-                                return;
-                            }
-                            const exitMatch = trimmed.match(/^exit(?:\s+(-?\d+))?$/);
-                            if (exitMatch) {
-                                finishSyntheticShell(Number.parseInt(exitMatch[1] ?? "0", 10));
-                                return;
-                            }
-                            const exportMatch = trimmed.match(/^export\s+([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
-                            if (exportMatch) {
-                                shellEnv = {
-                                    ...shellEnv,
-                                    [exportMatch[1]]: exportMatch[2],
-                                };
-                                emitPrompt();
-                                return;
-                            }
-                            const cdMatch = trimmed.match(/^cd(?:\s+(.*))?$/);
-                            if (cdMatch) {
-                                const target = cdMatch[1]?.trim() || "/";
-                                shellCwd = target.startsWith("/")
-                                    ? posixPath.normalize(target)
-                                    : posixPath.normalize(posixPath.join(shellCwd, target));
-                                emitPrompt();
-                                return;
-                            }
-                            const foregroundCommand = parseForegroundCommand(trimmed);
-                            if (foregroundCommand) {
-                                const proc = spawnCommand(foregroundCommand[0], foregroundCommand.slice(1), {
-                                    env: shellEnv,
-                                    cwd: shellCwd,
-                                    streamStdin: true,
-                                    onStdout: (chunk) => emitSyntheticTerminal(textDecoder.decode(chunk)),
-                                    onStderr: (chunk) => emitSyntheticTerminal(textDecoder.decode(chunk)),
-                                });
-                                activeForegroundProcess = proc;
-                                try {
-                                    await proc.wait();
-                                }
-                                finally {
-                                    if (activeForegroundProcess === proc) {
-                                        activeForegroundProcess = null;
-                                    }
-                                }
-                                emitPrompt();
-                                return;
-                            }
-                            const result = await execCommand(nextCommand, {
-                                env: shellEnv,
-                                cwd: shellCwd,
-                            });
-                            const sanitizedStdout = sanitizeSyntheticShellText(result.stdout);
-                            if (sanitizedStdout) {
-                                emitSyntheticStdout(sanitizedStdout);
-                            }
-                            const sanitizedStderr = sanitizeSyntheticShellText(result.stderr).replace(/^error: failed to execute command '([^']+)': .*$/gm, "error: command not found: $1");
-                            if (sanitizedStderr) {
-                                emitSyntheticTerminal(sanitizedStderr);
-                            }
-                            emitPrompt();
-                        })
-                            .catch((error) => {
-                            const message = error instanceof Error ? error.message : String(error);
-                            emitSyntheticTerminal(`${message}\n`);
-                            emitPrompt();
-                        });
-                    }
-                },
-                get onData() {
-                    return onData;
-                },
-                set onData(handler) {
-                    onData = handler;
-                },
-                resize() {
-                    // Synthetic shells are terminal-less.
-                },
-                kill(signal = 15) {
-                    finishSyntheticShell(128 + signal);
-                },
-                wait() {
-                    return syntheticWaitPromise;
-                },
-            };
-        }
-        const proc = this.spawn(command, args, {
+        const proc = await this.spawnTracked(options?.command, options?.args ?? [], {
             env: options?.env,
             cwd: options?.cwd,
-            streamStdin: true,
+            pty: { cols: options?.cols, rows: options?.rows },
             onStdout: (chunk) => {
                 for (const handler of stdoutHandlers) {
                     handler(chunk);
                 }
-                if (commandInFlight) {
-                    schedulePrompt(120);
-                }
             },
             onStderr: (chunk) => {
                 for (const handler of stderrHandlers) {
                     handler(chunk);
                 }
-                if (commandInFlight) {
-                    schedulePrompt(120);
-                }
             },
         });
+        const entry = this.trackedProcesses.get(proc.pid);
+        if (!entry) {
+            throw new Error(`sidecar shell process ${proc.pid} is not tracked`);
+        }
         return {
             pid: proc.pid,
+            processId: this.processIdFor(entry),
             write(data) {
-                if (synthesizePrompt) {
-                    return;
-                }
-                proc.writeStdin(data);
-                if (autoCloseExplicitCommandStdin) {
-                    clearCloseStdinTimer();
-                    closeStdinTimer = setTimeout(() => {
-                        closeStdinTimer = null;
-                        proc.closeStdin();
-                    }, 100);
-                }
-                if (synthesizePrompt &&
-                    typeof data === "string" &&
-                    (data.includes("\n") || data.includes("\r"))) {
-                    commandInFlight = true;
-                    schedulePrompt(120);
-                }
+                return proc.writeStdin(data);
             },
             get onData() {
                 return onData;
@@ -881,298 +398,177 @@ export class NativeSidecarKernelProxy {
             set onData(handler) {
                 onData = handler;
             },
-            resize() {
-                // The current stdio-native path is process-backed rather than PTY-backed.
-            },
-            kill(signal) {
-                clearCloseStdinTimer();
-                clearPromptTimer();
-                proc.kill(signal);
+            resize: (cols, rows) => {
+                const entry = this.trackedProcesses.get(proc.pid);
+                if (!entry || entry.exitCode !== null) {
+                    return;
+                }
+                return this.client.resizePty(this.session, this.vm, this.processIdFor(entry), Math.trunc(cols), Math.trunc(rows));
             },
+            kill: (signal) => proc.kill(signal),
             wait() {
-                clearPromptTimer();
                 return proc.wait();
             },
         };
     }
-    async connectTerminal(options) {
-        const stdin = process.stdin;
-        const stdout = process.stdout;
-        const { onData, ...shellOptions } = options ?? {};
-        const shell = this.openShell({
-            ...shellOptions,
-            onStderr: shellOptions.onStderr ??
-                ((data) => {
-                    process.stderr.write(data);
-                }),
-        });
-        const outputHandler = onData ??
-            ((data) => {
-                stdout.write(data);
-            });
-        const restoreRawMode = stdin.isTTY && typeof stdin.setRawMode === "function";
-        const onStdinData = (data) => {
-            shell.write(data);
-        };
-        const onResize = () => {
-            shell.resize(stdout.columns, stdout.rows);
-        };
-        let cleanedUp = false;
-        const cleanup = () => {
-            if (cleanedUp) {
-                return;
-            }
-            cleanedUp = true;
-            stdin.removeListener("data", onStdinData);
-            stdin.pause();
-            if (restoreRawMode) {
-                stdin.setRawMode(false);
-            }
-            if (stdout.isTTY) {
-                stdout.removeListener("resize", onResize);
-            }
-        };
-        try {
-            if (restoreRawMode) {
-                stdin.setRawMode(true);
-            }
-            stdin.on("data", onStdinData);
-            stdin.resume();
-            shell.onData = outputHandler;
-            if (stdout.isTTY) {
-                stdout.on("resize", onResize);
-                shell.resize(stdout.columns, stdout.rows);
-            }
-        }
-        catch (error) {
-            cleanup();
-            shell.kill();
-            throw error;
-        }
-        void shell.wait().finally(() => {
-            cleanup();
-        });
-        return shell.pid;
-    }
     readFile(path) {
-        return this.dispatchRead(path, (mount, relativePath) => mount.fs.readFile(relativePath));
+        return this.dispatchNativeRead(path);
     }
-    writeFile(path, content) {
-        return this.dispatchWrite(path, (mount, relativePath) => mount.fs.writeFile(relativePath, content), () => this.client.writeFile(this.session, this.vm, path, content));
+    async writeFile(path, content) {
+        await this.waitForMountReconfigure();
+        await this.client.writeFile(this.session, this.vm, path, content);
     }
-    async mkdir(path, recursive = true) {
-        return this.dispatchWrite(path, (mount, relativePath) => mount.fs.mkdir(relativePath, { recursive }), () => this.client.mkdir(this.session, this.vm, path, { recursive }));
+    async mkdir(path, options) {
+        await this.waitForMountReconfigure();
+        await this.client.mkdir(this.session, this.vm, path, options);
     }
     async exists(path) {
-        const local = this.resolveLocalMount(path);
-        if (local) {
-            return local.mount.fs.exists(local.relativePath);
-        }
         return this.client.exists(this.session, this.vm, path);
     }
     async stat(path) {
-        const local = this.resolveLocalMount(path);
-        if (local) {
-            return local.mount.fs.stat(local.relativePath);
-        }
         return toVirtualStat(await this.client.stat(this.session, this.vm, path));
     }
     async readdir(path) {
-        const local = this.resolveLocalMount(path);
-        if (local) {
-            return local.mount.fs.readDir(local.relativePath);
-        }
-        const entries = await this.client.readdir(this.session, this.vm, path);
-        return [...new Set([...entries, ...this.mountedChildNames(path)])].sort((a, b) => a.localeCompare(b));
+        return this.client.readdir(this.session, this.vm, path);
+    }
+    async readdirRecursive(path, options) {
+        return (await this.client.readdirRecursive(this.session, this.vm, path, options)).map((entry) => ({ ...entry, size: Number(entry.size) }));
     }
     async removeFile(path) {
-        return this.dispatchWrite(path, (mount, relativePath) => mount.fs.removeFile(relativePath), () => this.client.removeFile(this.session, this.vm, path));
+        await this.client.removeFile(this.session, this.vm, path);
     }
     async removeDir(path) {
-        return this.dispatchWrite(path, (mount, relativePath) => mount.fs.removeDir(relativePath), () => this.client.removeDir(this.session, this.vm, path));
+        await this.client.removeDir(this.session, this.vm, path);
+    }
+    async removePath(path, options) {
+        await this.client.removePath(this.session, this.vm, path, options);
+    }
+    async copyPath(fromPath, toPath, options) {
+        return this.client.copyPath(this.session, this.vm, fromPath, toPath, options);
     }
     async rename(oldPath, newPath) {
-        const from = this.resolveLocalMount(oldPath);
-        const to = this.resolveLocalMount(newPath);
-        if (!!from !== !!to) {
-            throw errnoError("EXDEV", "cross-device link not permitted");
-        }
-        if (from && to) {
-            if (from.mount.path !== to.mount.path) {
-                throw errnoError("EXDEV", "cross-device link not permitted");
-            }
-            this.assertLocalWritable(from.mount);
-            return from.mount.fs.rename(from.relativePath, to.relativePath);
-        }
         return this.client.rename(this.session, this.vm, oldPath, newPath);
     }
+    async movePath(oldPath, newPath) {
+        return this.client.movePath(this.session, this.vm, oldPath, newPath);
+    }
     mountFs(path, driver, options) {
         this.localMounts.unshift({
             path: posixPath.normalize(path),
             fs: driver,
-            readOnly: options?.readOnly ?? false,
+            readOnly: options?.readOnly,
+            sidecarMount: options?.sidecarMount,
         });
         this.localMounts.sort((left, right) => right.path.length - left.path.length);
+        return this.reconfigureSidecarMounts();
     }
     unmountFs(path) {
         const normalized = posixPath.normalize(path);
         const index = this.localMounts.findIndex((mount) => mount.path === normalized);
-        if (index >= 0) {
-            this.localMounts.splice(index, 1);
-        }
-    }
-    snapshotProcesses() {
-        return this.buildProcessSnapshot();
+        if (index < 0) {
+            return Promise.resolve();
+        }
+        this.localMounts.splice(index, 1);
+        return this.reconfigureSidecarMounts();
+    }
+    desiredSidecarMounts() {
+        return [
+            ...this.baseSidecarMounts,
+            ...this.localMounts.map((mount) => mount.sidecarMount ?? {
+                guestPath: mount.path,
+                readOnly: mount.readOnly,
+                plugin: {
+                    id: "js_bridge",
+                },
+            }),
+        ];
     }
-    findListener(request) {
-        const key = socketLookupKey("listener", request);
-        const cached = this.listenerLookups.get(key);
-        if (!cached?.pending) {
-            this.listenerLookups.set(key, {
-                value: cached?.value ?? null,
-                pending: this.refreshSocketLookup(this.listenerLookups, key, () => this.client.findListener(this.session, this.vm, request)),
-            });
-        }
-        return this.listenerLookups.get(key)?.value ?? null;
-    }
-    findBoundUdp(request) {
-        const key = socketLookupKey("udp", request);
-        const cached = this.boundUdpLookups.get(key);
-        if (!cached?.pending) {
-            this.boundUdpLookups.set(key, {
-                value: cached?.value ?? null,
-                pending: this.refreshSocketLookup(this.boundUdpLookups, key, () => this.client.findBoundUdp(this.session, this.vm, request)),
+    reconfigureSidecarMounts() {
+        const run = async () => {
+            if (this.disposed) {
+                return;
+            }
+            // Package projections are sidecar-owned and survive mount reconfiguration.
+            await this.client.configureVm(this.session, this.vm, {
+                mounts: this.desiredSidecarMounts(),
             });
-        }
-        return this.boundUdpLookups.get(key)?.value ?? null;
+        };
+        const previous = this.mountReconfigurePromise ?? Promise.resolve();
+        const next = previous.then(run, run);
+        const tracked = next.finally(() => {
+            if (this.mountReconfigurePromise === tracked) {
+                this.mountReconfigurePromise = null;
+            }
+        });
+        this.mountReconfigurePromise = tracked;
+        return tracked;
     }
-    getSignalState(pid) {
-        const entry = this.trackedProcesses.get(pid);
-        if (entry && !this.signalRefreshes.has(pid)) {
-            this.signalRefreshes.set(pid, this.refreshSignalState(entry));
+    async waitForMountReconfigure() {
+        if (this.mountReconfigurePromise) {
+            await this.mountReconfigurePromise;
         }
-        return this.signalStates.get(pid) ?? { handlers: new Map() };
     }
-    async refreshSocketLookup(cache, key, lookup) {
-        try {
-            const socket = await lookup();
-            cache.set(key, {
-                value: socket ? toKernelSocketSnapshot(socket) : null,
-                pending: null,
-            });
-        }
-        catch {
-            cache.set(key, {
-                value: cache.get(key)?.value ?? null,
-                pending: null,
-            });
-        }
+    async snapshotProcesses() {
+        return this.buildProcessSnapshot(await this.refreshProcessSnapshot());
     }
-    async refreshSignalState(entry) {
-        try {
-            const signalState = await this.client.getSignalState(this.session, this.vm, entry.processId);
-            this.signalStates.set(entry.pid, toKernelSignalState(signalState.handlers));
-        }
-        catch {
-            this.signalStates.set(entry.pid, this.signalStates.get(entry.pid) ?? { handlers: new Map() });
-        }
-        finally {
-            this.signalRefreshes.delete(entry.pid);
-        }
+    async processSnapshotById(processId) {
+        return (await this.refreshProcessSnapshot()).find((process) => process.processId === processId);
     }
     async refreshProcessSnapshot() {
         if (this.processSnapshotRefresh) {
-            await this.processSnapshotRefresh;
-            return;
+            return this.processSnapshotRefresh;
         }
         this.processSnapshotRefresh = (async () => {
             try {
-                this.sidecarProcessSnapshot = await this.client.getProcessSnapshot(this.session, this.vm);
+                return await this.client.getProcessSnapshot(this.session, this.vm);
             }
             finally {
                 this.processSnapshotRefresh = null;
             }
         })();
-        await this.processSnapshotRefresh;
-    }
-    async refreshZombieTimerCount() {
-        try {
-            const snapshot = await this.client.getZombieTimerCount(this.session, this.vm);
-            this.zombieTimerCountValue = snapshot.count;
-        }
-        catch {
-            // Keep the last known value if the sidecar query fails.
-        }
-        finally {
-            this.zombieTimerCountRefresh = null;
-        }
-    }
-    async drainTrailingProcessOutput(entry) {
-        if (entry.onStdout.size === 0 && entry.onStderr.size === 0) {
-            return;
-        }
-        let observedGeneration = entry.outputGeneration;
-        let quietTurns = 0;
-        let delayMs = 0;
-        const deadline = Date.now() + TRAILING_OUTPUT_DRAIN_MAX_MS;
-        while (quietTurns < TRAILING_OUTPUT_DRAIN_QUIET_TURNS) {
-            const remainingMs = deadline - Date.now();
-            if (remainingMs <= 0) {
-                return;
-            }
-            await drainTrailingProcessOutputTurn(Math.min(delayMs, remainingMs));
-            if (entry.outputGeneration === observedGeneration) {
-                quietTurns += 1;
-            }
-            else {
-                observedGeneration = entry.outputGeneration;
-                quietTurns = 0;
-            }
-            delayMs = TRAILING_OUTPUT_DRAIN_INTERVAL_MS;
-        }
+        return this.processSnapshotRefresh;
     }
     async startTrackedProcess(entry) {
+        await this.waitForMountReconfigure();
         const started = await this.client.execute(this.session, this.vm, {
-            processId: entry.processId,
-            command: entry.command,
+            ...(entry.shellCommand !== undefined
+                ? { shellCommand: entry.shellCommand }
+                : entry.command !== undefined
+                    ? { command: entry.command }
+                    : {}),
             args: entry.args,
-            env: entry.env,
-            cwd: entry.cwd,
-        });
-        entry.hostPid = started.pid;
-        entry.started = true;
-        this.updateTrackedProcessSnapshot(entry);
-        void this.refreshProcessSnapshot().catch(() => { });
-        await this.refreshSignalState(entry);
-        void this.flushPendingStdin(entry).catch((error) => {
-            this.handleBackgroundProcessError(entry, error);
-        });
-        void this.closeTrackedStdin(entry).catch((error) => {
-            this.handleBackgroundProcessError(entry, error);
+            ...(entry.env !== undefined ? { env: entry.env } : {}),
+            ...(entry.requestedCwd !== undefined ? { cwd: entry.requestedCwd } : {}),
+            ...(entry.pty ? { pty: entry.pty } : {}),
+            ...(entry.keepStdinOpen !== undefined
+                ? { keepStdinOpen: entry.keepStdinOpen }
+                : {}),
+            ...(entry.timeoutMs !== undefined ? { timeoutMs: entry.timeoutMs } : {}),
+            ...(entry.captureOutput !== undefined
+                ? { captureOutput: entry.captureOutput }
+                : {}),
         });
-        if (entry.pendingKillSignal !== null) {
-            const signal = entry.pendingKillSignal;
-            entry.pendingKillSignal = null;
-            await this.signalProcess(entry, signal);
+        if (started.pid === null) {
+            throw new Error("sidecar did not return a kernel pid for the process");
         }
+        entry.processId = started.processId;
+        entry.pid = started.pid;
+        this.trackedProcessesById.set(entry.processId, entry);
+        this.trackedProcesses.set(entry.pid, entry);
     }
     async runEventPump() {
+        // Scope the pump to THIS VM's ownership so multiple proxies can share one
+        // sidecar process: events for other VMs stay buffered for their own pumps
+        // rather than being consumed (and dropped) here.
+        const vmId = this.vm.vmId;
         while (!this.disposed) {
             try {
-                const event = await this.client.waitForEvent({ any: true }, undefined, {
-                    signal: this.eventPumpAbortController.signal,
-                });
+                const event = await this.client.waitForEvent((frame) => frame.ownership.scope === "vm" && frame.ownership.vm_id === vmId, undefined, { signal: this.eventPumpAbortController.signal });
                 if (event.payload.type === "process_output") {
                     const entry = this.trackedProcessesById.get(event.payload.process_id);
                     if (!entry) {
                         continue;
                     }
-                    entry.outputGeneration += 1;
-                    void this.refreshProcessSnapshot().catch(() => { });
-                    if (!this.signalRefreshes.has(entry.pid)) {
-                        this.signalRefreshes.set(entry.pid, this.refreshSignalState(entry));
-                        await this.signalRefreshes.get(entry.pid);
-                    }
                     const chunk = event.payload.chunk;
                     const listeners = event.payload.channel === "stdout"
                         ? entry.onStdout
@@ -1187,9 +583,17 @@ export class NativeSidecarKernelProxy {
                     if (!entry) {
                         continue;
                     }
-                    void this.refreshProcessSnapshot().catch(() => { });
-                    this.signalRefreshes.delete(entry.pid);
-                    this.finishProcess(entry, event.payload.exit_code);
+                    if (event.payload.error_code !== undefined) {
+                        const error = new Error(event.payload.error_message ?? event.payload.error_code);
+                        error.code = event.payload.error_code;
+                        this.failProcess(entry, error);
+                        continue;
+                    }
+                    this.finishProcess(entry, event.payload.exit_code, event.payload.stdout, event.payload.stderr);
+                    continue;
+                }
+                if (event.payload.type === "structured") {
+                    logStructuredSidecarEvent(event.payload.name, event.payload.detail);
                 }
             }
             catch (error) {
@@ -1206,362 +610,113 @@ export class NativeSidecarKernelProxy {
                     for (const listener of entry.onStderr) {
                         listener(stderr);
                     }
-                    this.finishProcess(entry, 1);
+                    this.failProcess(entry, this.pumpError);
                 }
                 return;
             }
         }
     }
-    finishProcess(entry, exitCode) {
-        if (entry.exitCode !== null) {
+    finishProcess(entry, exitCode, stdout = new Uint8Array(), stderr = new Uint8Array()) {
+        if (entry.settled) {
             return;
         }
+        entry.settled = true;
         entry.exitCode = exitCode;
-        entry.exitTime = Date.now();
-        this.updateTrackedProcessSnapshot(entry);
-        entry.resolveWait(exitCode);
-    }
-    waitForTrackedProcess(entry) {
-        if (entry.exitCode !== null) {
-            return Promise.resolve(entry.exitCode);
-        }
-        if (entry.waitWithFallbackPromise !== null) {
-            return entry.waitWithFallbackPromise;
+        entry.resolveWait({ exitCode, stdout, stderr });
+        // The sidecar guarantees that all process_output events precede the terminal
+        // process_exited event. Release client routing immediately after exit; the
+        // exited record lives on in `processes` for listing.
+        this.releaseProcessTracking(entry);
+    }
+    failProcess(entry, error) {
+        if (entry.settled) {
+            return;
         }
-        entry.waitWithFallbackPromise = (async () => {
-            await entry.startPromise.catch(() => { });
-            while (entry.exitCode === null && !this.disposed) {
-                const maybeExit = await Promise.race([
-                    entry.waitPromise.then((exitCode) => exitCode),
-                    new Promise((resolve) => setTimeout(() => resolve(null), 50)),
-                ]);
-                if (maybeExit !== null) {
-                    return maybeExit;
-                }
-                try {
-                    await this.refreshProcessSnapshot();
-                    const snapshot = this.sidecarProcessSnapshot.find((candidate) => candidate.processId === entry.processId);
-                    if (snapshot?.status === "exited") {
-                        this.finishProcess(entry, snapshot.exitCode ?? 0);
-                        break;
-                    }
-                    if (snapshot) {
-                        entry.hostExitObservedAt = null;
-                        continue;
-                    }
-                    // Fast guest processes can exit before the sidecar emits a
-                    // `process_exited` event. Once a started process disappears from the
-                    // authoritative VM snapshot for a full grace window, treat it as
-                    // reaped even if the `pid` returned at launch was only a kernel/shared
-                    // runtime identifier rather than a probeable host PID.
-                    if (!snapshot) {
-                        const now = Date.now();
-                        if (entry.hostExitObservedAt === null) {
-                            entry.hostExitObservedAt = now;
-                            continue;
-                        }
-                        if (now - entry.hostExitObservedAt >= MISSING_EXIT_EVENT_GRACE_MS) {
-                            this.finishProcess(entry, 0);
-                            break;
-                        }
-                    }
-                }
-                catch {
-                    // Fall back to the next wait interval if the sidecar snapshot query fails.
-                }
-            }
-            return entry.waitPromise;
-        })().finally(() => {
-            entry.waitWithFallbackPromise = null;
-        });
-        return entry.waitWithFallbackPromise;
+        entry.settled = true;
+        entry.rejectWait(error);
+        this.releaseProcessTracking(entry);
     }
-    async signalProcess(entry, signal) {
-        try {
-            await this.client.killProcess(this.session, this.vm, entry.processId, toSidecarSignalName(signal));
+    releaseProcessTracking(entry) {
+        if (entry.pid !== null) {
+            this.trackedProcesses.delete(entry.pid);
         }
-        catch (error) {
-            if (isNoSuchProcessError(error) || isUnknownVmError(error)) {
-                return;
-            }
-            throw error;
+        if (entry.processId !== null) {
+            this.trackedProcessesById.delete(entry.processId);
         }
+        entry.onStdout.clear();
+        entry.onStderr.clear();
     }
-    flushPendingStdin(entry) {
-        if (entry.stdinFlushPromise !== null) {
-            return entry.stdinFlushPromise;
-        }
-        entry.stdinFlushPromise = entry.startPromise
-            .then(async () => {
-            if (entry.exitCode !== null) {
-                return;
-            }
-            while (entry.pendingStdin.length > 0) {
-                const chunk = entry.pendingStdin.shift();
-                if (chunk === undefined) {
-                    break;
-                }
-                await this.client.writeStdin(this.session, this.vm, entry.processId, chunk);
-            }
-        })
-            .catch((error) => {
-            if (isNoSuchProcessError(error) || isUnknownVmError(error)) {
-                return;
-            }
-            throw error;
-        })
-            .finally(() => {
-            entry.stdinFlushPromise = null;
-            if (entry.pendingStdin.length > 0 && entry.exitCode === null) {
-                void this.flushPendingStdin(entry).catch((error) => {
-                    this.handleBackgroundProcessError(entry, error);
-                });
-            }
-        });
-        return entry.stdinFlushPromise;
+    waitForTrackedProcess(entry) {
+        return entry.waitPromise.then((completion) => completion.exitCode);
     }
-    async closeTrackedStdin(entry) {
-        await entry.startPromise;
-        await this.flushPendingStdin(entry);
-        if (entry.exitCode !== null || !entry.pendingCloseStdin) {
-            return;
-        }
-        entry.pendingCloseStdin = false;
-        try {
-            await this.client.closeStdin(this.session, this.vm, entry.processId);
-        }
-        catch (error) {
-            if (isNoSuchProcessError(error) || isUnknownVmError(error)) {
-                return;
-            }
-            throw error;
-        }
+    async signalProcess(entry, signal) {
+        await this.client.killProcess(this.session, this.vm, this.processIdFor(entry), toSidecarSignalName(signal));
     }
-    handleBackgroundProcessError(entry, error) {
-        if (this.disposed ||
-            isNoSuchProcessError(error) ||
-            isUnknownVmError(error)) {
-            return;
-        }
-        if (entry.exitCode !== null) {
-            this.recordCompletedProcessError(entry, error);
-            return;
-        }
-        this.emitBackgroundProcessError(entry, error);
-        this.finishProcess(entry, 1);
-    }
-    recordCompletedProcessError(entry, error) {
-        if (this.disposed ||
-            isNoSuchProcessError(error) ||
-            isUnknownVmError(error)) {
-            return entry.exitCode ?? 1;
-        }
-        this.emitBackgroundProcessError(entry, error);
-        entry.exitCode =
-            entry.exitCode === null || entry.exitCode === 0 ? 1 : entry.exitCode;
-        entry.exitTime ??= Date.now();
-        this.updateTrackedProcessSnapshot(entry);
-        return entry.exitCode;
-    }
-    emitBackgroundProcessError(entry, error) {
-        const normalized = error instanceof Error ? error : new Error(String(error));
-        const stderr = new TextEncoder().encode(`${normalized.message}\n`);
-        for (const handler of entry.onStderr) {
-            handler(stderr);
+    processIdFor(entry) {
+        if (entry.processId === null) {
+            throw new Error("sidecar process has not started");
         }
+        return entry.processId;
     }
-    createFilesystemView(includeLocalMounts) {
+    createFilesystemView() {
         return {
-            readFile: (path) => this.dispatchRead(path, (mount, relativePath) => mount.fs.readFile(relativePath), includeLocalMounts),
-            readTextFile: async (path) => new TextDecoder().decode(await this.dispatchRead(path, (mount, relativePath) => mount.fs.readFile(relativePath), includeLocalMounts)),
-            readDir: async (path) => {
-                const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-                if (local) {
-                    return local.mount.fs.readDir(local.relativePath);
-                }
-                const entries = await this.client.readdir(this.session, this.vm, path);
-                return includeLocalMounts
-                    ? [...new Set([...entries, ...this.mountedChildNames(path)])].sort((a, b) => a.localeCompare(b))
-                    : entries;
-            },
+            readFile: (path) => this.readFile(path),
+            readTextFile: async (path) => new TextDecoder().decode(await this.readFile(path)),
+            readDir: (path) => this.readdir(path),
             readDirWithTypes: async (path) => {
-                const entries = await this.createFilesystemView(includeLocalMounts).readDir(path);
+                const entries = await this.readdir(path);
                 return Promise.all(entries.map(async (name) => {
-                    const stat = await this.createFilesystemView(includeLocalMounts).lstat(posixPath.join(path, name));
+                    const stat = await this.client.lstat(this.session, this.vm, posixPath.join(path, name));
                     return {
                         name,
-                        isDirectory: stat.isDirectory,
-                        isSymbolicLink: stat.isSymbolicLink,
+                        isDirectory: stat.is_directory,
+                        isSymbolicLink: stat.is_symbolic_link,
                     };
                 }));
             },
-            writeFile: (path, content) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.writeFile(relativePath, content), () => this.client.writeFile(this.session, this.vm, path, content), includeLocalMounts),
-            createDir: (path) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.createDir(relativePath), async () => {
+            writeFile: (path, content) => this.writeFile(path, content),
+            createDir: async (path) => {
                 try {
-                    await this.client.mkdir(this.session, this.vm, path, {
-                        recursive: false,
-                    });
+                    await this.client.mkdir(this.session, this.vm, path);
                 }
                 catch (error) {
                     if (!isAlreadyExistsError(error)) {
                         throw error;
                     }
                 }
-            }, includeLocalMounts),
-            mkdir: (path, options) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.mkdir(relativePath, {
-                recursive: options?.recursive ?? true,
-            }), () => this.client.mkdir(this.session, this.vm, path, {
-                recursive: options?.recursive ?? true,
-            }), includeLocalMounts),
-            exists: async (path) => {
-                const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-                if (local) {
-                    return local.mount.fs.exists(local.relativePath);
-                }
-                return this.client.exists(this.session, this.vm, path);
-            },
-            stat: async (path) => {
-                const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-                if (local) {
-                    return local.mount.fs.stat(local.relativePath);
-                }
-                return toVirtualStat(await this.client.stat(this.session, this.vm, path));
-            },
-            removeFile: (path) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.removeFile(relativePath), () => this.client.removeFile(this.session, this.vm, path), includeLocalMounts),
-            removeDir: (path) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.removeDir(relativePath), () => this.client.removeDir(this.session, this.vm, path), includeLocalMounts),
-            rename: async (oldPath, newPath) => {
-                const from = includeLocalMounts
-                    ? this.resolveLocalMount(oldPath)
-                    : null;
-                const to = includeLocalMounts ? this.resolveLocalMount(newPath) : null;
-                if (!!from !== !!to) {
-                    throw errnoError("EXDEV", "cross-device link not permitted");
-                }
-                if (from && to) {
-                    if (from.mount.path !== to.mount.path) {
-                        throw errnoError("EXDEV", "cross-device link not permitted");
-                    }
-                    this.assertLocalWritable(from.mount);
-                    return from.mount.fs.rename(from.relativePath, to.relativePath);
-                }
-                return this.client.rename(this.session, this.vm, oldPath, newPath);
-            },
-            realpath: async (path) => {
-                const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-                if (local) {
-                    return local.mount.fs.realpath(local.relativePath);
-                }
-                return this.client.realpath(this.session, this.vm, path);
-            },
-            symlink: (target, linkPath) => this.dispatchWrite(linkPath, (mount, relativePath) => mount.fs.symlink(target, relativePath), () => this.client.symlink(this.session, this.vm, target, linkPath), includeLocalMounts),
-            readlink: async (path) => {
-                const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-                if (local) {
-                    return local.mount.fs.readlink(local.relativePath);
-                }
-                return this.client.readLink(this.session, this.vm, path);
-            },
-            lstat: async (path) => {
-                const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-                if (local) {
-                    return local.mount.fs.lstat(local.relativePath);
-                }
-                return toVirtualStat(await this.client.lstat(this.session, this.vm, path));
-            },
-            link: async (oldPath, newPath) => {
-                const from = includeLocalMounts
-                    ? this.resolveLocalMount(oldPath)
-                    : null;
-                const to = includeLocalMounts ? this.resolveLocalMount(newPath) : null;
-                if (!!from !== !!to) {
-                    throw errnoError("EXDEV", "cross-device link not permitted");
-                }
-                if (from && to) {
-                    if (from.mount.path !== to.mount.path) {
-                        throw errnoError("EXDEV", "cross-device link not permitted");
-                    }
-                    this.assertLocalWritable(from.mount);
-                    return from.mount.fs.link(from.relativePath, to.relativePath);
-                }
-                return this.client.link(this.session, this.vm, oldPath, newPath);
-            },
-            chmod: (path, mode) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.chmod(relativePath, mode), () => this.client.chmod(this.session, this.vm, path, mode), includeLocalMounts),
-            chown: (path, uid, gid) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.chown(relativePath, uid, gid), () => this.client.chown(this.session, this.vm, path, uid, gid), includeLocalMounts),
-            utimes: (path, atimeMs, mtimeMs) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.utimes(relativePath, atimeMs, mtimeMs), () => this.client.utimes(this.session, this.vm, path, atimeMs, mtimeMs), includeLocalMounts),
-            truncate: (path, length) => this.dispatchWrite(path, (mount, relativePath) => mount.fs.truncate(relativePath, length), () => this.client.truncate(this.session, this.vm, path, length), includeLocalMounts),
-            pread: async (path, offset, length) => {
-                const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-                if (local) {
-                    return local.mount.fs.pread(local.relativePath, offset, length);
-                }
-                return this.client.pread(this.session, this.vm, path, offset, length);
-            },
-            pwrite: async (path, offset, data) => {
-                const bytes = await this.createFilesystemView(includeLocalMounts).readFile(path);
-                const nextSize = Math.max(bytes.length, offset + data.length);
-                const updated = new Uint8Array(nextSize);
-                updated.set(bytes);
-                updated.set(data, offset);
-                await this.createFilesystemView(includeLocalMounts).writeFile(path, updated);
             },
+            mkdir: (path, options) => this.mkdir(path, options),
+            exists: (path) => this.exists(path),
+            stat: (path) => this.stat(path),
+            removeFile: (path) => this.removeFile(path),
+            removeDir: (path) => this.removeDir(path),
+            rename: (oldPath, newPath) => this.client.rename(this.session, this.vm, oldPath, newPath),
+            realpath: (path) => this.client.realpath(this.session, this.vm, path),
+            symlink: (target, linkPath) => this.client.symlink(this.session, this.vm, target, linkPath),
+            readlink: (path) => this.client.readLink(this.session, this.vm, path),
+            lstat: async (path) => toVirtualStat(await this.client.lstat(this.session, this.vm, path)),
+            link: (oldPath, newPath) => this.client.link(this.session, this.vm, oldPath, newPath),
+            chmod: (path, mode) => this.client.chmod(this.session, this.vm, path, mode),
+            chown: (path, uid, gid) => this.client.chown(this.session, this.vm, path, uid, gid),
+            utimes: (path, atimeMs, mtimeMs) => this.client.utimes(this.session, this.vm, path, atimeMs, mtimeMs),
+            truncate: (path, length) => this.client.truncate(this.session, this.vm, path, length),
+            pread: (path, offset, length) => this.client.pread(this.session, this.vm, path, offset, length),
+            pwrite: (path, offset, data) => this.client.pwrite(this.session, this.vm, path, offset, data),
         };
     }
-    buildProcessSnapshot() {
-        void this.refreshProcessSnapshot().catch(() => { });
+    buildProcessSnapshot(snapshot) {
         const processMap = new Map();
-        const displayPidByKernelPid = new Map();
-        for (const entry of this.sidecarProcessSnapshot) {
-            const tracked = this.trackedProcessesById.get(entry.processId);
-            if (tracked) {
-                displayPidByKernelPid.set(entry.pid, tracked.pid);
-            }
-        }
-        for (const entry of this.sidecarProcessSnapshot) {
-            const tracked = this.trackedProcessesById.get(entry.processId);
-            const displayPid = displayPidByKernelPid.get(entry.pid) ?? entry.pid;
-            const displayPpid = displayPidByKernelPid.get(entry.ppid) ?? entry.ppid;
-            const displayPgid = displayPidByKernelPid.get(entry.pgid) ?? entry.pgid;
-            const displaySid = displayPidByKernelPid.get(entry.sid) ?? entry.sid;
-            const processKey = `${entry.processId}:${entry.pid}`;
-            const startTime = tracked?.startTime ??
-                this.observedProcessStartTimes.get(processKey) ??
-                Date.now();
-            this.observedProcessStartTimes.set(processKey, startTime);
-            processMap.set(displayPid, {
-                pid: displayPid,
-                ppid: displayPpid,
-                pgid: displayPgid,
-                sid: displaySid,
-                driver: tracked?.driver ?? entry.driver,
-                command: tracked?.command ?? entry.command,
-                args: tracked?.args ?? entry.args,
-                cwd: tracked?.cwd ?? entry.cwd,
-                status: tracked?.exitCode !== null
-                    ? "exited"
-                    : tracked
-                        ? "running"
-                        : entry.status === "exited"
-                            ? "exited"
-                            : "running",
-                exitCode: tracked?.exitCode ?? entry.exitCode,
-                startTime,
-                exitTime: tracked?.exitTime ?? null,
-            });
-        }
-        for (const entry of this.trackedProcesses.values()) {
-            if (processMap.has(entry.pid)) {
-                continue;
-            }
+        for (const entry of snapshot) {
             processMap.set(entry.pid, {
                 pid: entry.pid,
-                ppid: 0,
-                pgid: entry.pid,
-                sid: entry.pid,
+                ppid: entry.ppid,
+                pgid: entry.pgid,
+                sid: entry.sid,
                 driver: entry.driver,
                 command: entry.command,
                 args: entry.args,
                 cwd: entry.cwd,
-                status: entry.exitCode === null ? "running" : "exited",
+                status: entry.status,
                 exitCode: entry.exitCode,
                 startTime: entry.startTime,
                 exitTime: entry.exitTime,
@@ -1573,119 +728,10 @@ export class NativeSidecarKernelProxy {
         }
         return [...processMap.values()].sort((left, right) => left.pid - right.pid);
     }
-    dispatchRead(path, handler, includeLocalMounts = true) {
-        const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-        if (local) {
-            return handler(local.mount, local.relativePath);
-        }
-        return this.dispatchNativeRead(path);
-    }
-    dispatchNativeRead(path) {
+    async dispatchNativeRead(path) {
+        await this.waitForMountReconfigure();
         return this.client.readFile(this.session, this.vm, path);
     }
-    async dispatchWrite(path, handler, nativeHandler, includeLocalMounts = true) {
-        this.assertGuestPathWritable(path);
-        const local = includeLocalMounts ? this.resolveLocalMount(path) : null;
-        if (local) {
-            this.assertLocalWritable(local.mount);
-            await handler(local.mount, local.relativePath);
-            return;
-        }
-        await nativeHandler();
-    }
-    resolveLocalMount(path) {
-        const normalizedPath = posixPath.normalize(path);
-        for (const mount of this.localMounts) {
-            if (normalizedPath !== mount.path &&
-                !normalizedPath.startsWith(`${mount.path}/`)) {
-                continue;
-            }
-            const relativePath = normalizedPath === mount.path
-                ? "/"
-                : `/${normalizedPath.slice(mount.path.length + 1)}`;
-            return {
-                mount,
-                relativePath,
-            };
-        }
-        return null;
-    }
-    assertGuestPathWritable(path) {
-        const normalizedPath = posixPath.normalize(path);
-        for (const root of PROTECTED_READ_ONLY_GUEST_ROOTS) {
-            if (normalizedPath === root || normalizedPath.startsWith(`${root}/`)) {
-                throw errnoError("EROFS", "read-only file system");
-            }
-        }
-    }
-    mountedChildNames(path) {
-        const normalizedPath = posixPath.normalize(path);
-        const names = new Set();
-        for (const mount of this.localMounts) {
-            if (mount.path === normalizedPath) {
-                continue;
-            }
-            if (!mount.path.startsWith(`${normalizedPath}/`) &&
-                normalizedPath !== "/") {
-                continue;
-            }
-            const relative = normalizedPath === "/"
-                ? mount.path.slice(1)
-                : mount.path.slice(normalizedPath.length + 1);
-            const name = relative.split("/").find(Boolean);
-            if (name) {
-                names.add(name);
-            }
-        }
-        return [...names];
-    }
-    assertLocalWritable(mount) {
-        if (mount.readOnly) {
-            throw errnoError("EROFS", "read-only file system");
-        }
-    }
-    updateTrackedProcessSnapshot(entry) {
-        this.processes.set(entry.pid, {
-            pid: entry.pid,
-            ppid: 0,
-            pgid: entry.pid,
-            sid: entry.pid,
-            driver: entry.driver,
-            command: entry.command,
-            args: entry.args,
-            cwd: entry.cwd,
-            status: entry.exitCode === null ? "running" : "exited",
-            exitCode: entry.exitCode,
-            startTime: entry.startTime,
-            exitTime: entry.exitTime,
-        });
-    }
-}
-function buildCommandMap(commandGuestPaths) {
-    const commands = new Map([
-        ["node", "node"],
-        ["npm", "node"],
-        ["npx", "node"],
-    ]);
-    for (const name of commandGuestPaths.keys()) {
-        commands.set(name, "wasmvm");
-    }
-    return commands;
-}
-function isNoSuchProcessError(error) {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    const message = error.message.toLowerCase();
-    return (error.message.includes("ESRCH") ||
-        message.includes("no such process") ||
-        message.includes("has no active process"));
-}
-function isUnknownVmError(error) {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    return error.message.toLowerCase().includes("unknown sidecar vm");
 }
 function isAlreadyExistsError(error) {
     if (!(error instanceof Error)) {
@@ -1694,63 +740,32 @@ function isAlreadyExistsError(error) {
     const message = error.message.toLowerCase();
     return error.message.includes("EEXIST") || message.includes("file exists");
 }
-function isMissingHostProcessError(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === "ESRCH");
-}
-function errnoError(code, message) {
-    return Object.assign(new Error(`${code}: ${message}`), { code });
-}
+// VirtualStat is a numeric, Node-default-shaped view: u64 fields above
+// Number.MAX_SAFE_INTEGER lose precision here, same as Node's non-bigint
+// fs.stat on the host.
 function toVirtualStat(stat) {
     return {
         mode: stat.mode,
-        size: stat.size,
-        blocks: stat.blocks,
-        dev: stat.dev,
-        rdev: stat.rdev,
+        size: Number(stat.size),
+        sizeExact: stat.size,
+        blocks: Number(stat.blocks),
+        dev: Number(stat.dev),
+        rdev: Number(stat.rdev),
         isDirectory: stat.is_directory,
         isSymbolicLink: stat.is_symbolic_link,
         atimeMs: stat.atime_ms,
         mtimeMs: stat.mtime_ms,
         ctimeMs: stat.ctime_ms,
         birthtimeMs: stat.birthtime_ms,
-        ino: stat.ino,
-        nlink: stat.nlink,
+        ino: Number(stat.ino),
+        inoExact: stat.ino,
+        nlink: Number(stat.nlink),
+        nlinkExact: stat.nlink,
         uid: stat.uid,
         gid: stat.gid,
     };
 }
-function toKernelSocketSnapshot(socket) {
-    return {
-        processId: socket.processId,
-        ...(socket.host !== undefined ? { host: socket.host } : {}),
-        ...(socket.port !== undefined ? { port: socket.port } : {}),
-        ...(socket.path !== undefined ? { path: socket.path } : {}),
-    };
-}
-function toKernelSignalState(handlers) {
-    return {
-        handlers: new Map([...handlers.entries()].map(([signal, registration]) => [
-            signal,
-            {
-                action: registration.action,
-                mask: new Set(registration.mask),
-                flags: registration.flags,
-            },
-        ])),
-    };
-}
-function socketLookupKey(kind, request) {
-    return JSON.stringify({
-        kind,
-        host: request.host ?? null,
-        port: request.port ?? null,
-        path: request.path ?? null,
-    });
-}
-export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./native-process-client.js";
+export { NativeSidecarProcessClient, SidecarEventBufferOverflow, SidecarProcess, SidecarProcessError, SidecarProcessExited, } from "./native-process-client.js";
 export class AgentOsSidecarVmHandle {
     client;
     sessionId;
@@ -1780,8 +795,8 @@ export class AgentOsSidecarSessionHandle {
     listVms() {
         return this.client.listVms(this.sessionId);
     }
-    async createVm(options) {
-        return this.client.createVm(this.sessionId, options);
+    async createVm() {
+        return this.client.createVm(this.sessionId);
     }
     async dispose() {
         await this.client.disposeSession(this.sessionId);
@@ -1802,13 +817,11 @@ export class AgentOsSidecarClient {
         this.assertActive();
         const sessionId = this.createId();
         const placement = clonePlacement(options.placement);
-        const metadata = cloneMetadata(options.metadata);
         const lifecycle = {
             sessionId,
             placement,
             state: "connecting",
             createdAt: this.now(),
-            metadata,
             vmIds: [],
         };
         const entry = {
@@ -1820,7 +833,6 @@ export class AgentOsSidecarClient {
             entry.transport = await this.createSessionTransport({
                 sessionId,
                 placement: clonePlacement(placement),
-                metadata: cloneMetadata(metadata),
                 signal: options.signal,
             });
             entry.lifecycle.state = "ready";
@@ -1848,21 +860,19 @@ export class AgentOsSidecarClient {
         const vmEntry = this.getVmEntry(sessionId, vmId);
         return cloneVmLifecycle(vmEntry.lifecycle);
     }
-    async createVm(sessionId, options = {}) {
+    async createVm(sessionId) {
         this.assertActive();
         const entry = this.getSessionEntry(sessionId);
         if (entry.lifecycle.state !== "ready" || !entry.transport) {
             throw new Error(`Cannot create VM for sidecar session ${sessionId} while it is ${entry.lifecycle.state}`);
         }
         const vmId = this.createId();
-        const metadata = cloneMetadata(options.metadata);
         const vmEntry = {
             lifecycle: {
                 vmId,
                 sessionId,
                 state: "creating",
                 createdAt: this.now(),
-                metadata,
             },
         };
         entry.vms.set(vmId, vmEntry);
@@ -1871,7 +881,6 @@ export class AgentOsSidecarClient {
             await entry.transport.createVm?.({
                 vmId,
                 sessionId,
-                metadata: cloneMetadata(metadata),
             });
             vmEntry.lifecycle.state = "ready";
             vmEntry.lifecycle.readyAt = this.now();
@@ -1933,10 +942,10 @@ export class AgentOsSidecarClient {
                 errors.push(toError(error));
             }
         }
-        this.disposed = true;
         if (errors.length > 0) {
             throw new Error(errors.map((error) => error.message).join("; "));
         }
+        this.disposed = true;
     }
     async disposeVmEntry(sessionEntry, vmEntry) {
         if (vmEntry.lifecycle.state === "disposed" ||
@@ -1983,32 +992,32 @@ export function serializeMountConfigForSidecar(mount) {
     if ("driver" in mount) {
         return {
             guestPath: mount.path,
-            readOnly: mount.readOnly ?? false,
+            ...(mount.readOnly === undefined ? {} : { readOnly: mount.readOnly }),
             plugin: {
                 id: "js_bridge",
-                config: {},
             },
         };
     }
     return {
         guestPath: mount.path,
-        readOnly: mount.readOnly ?? false,
+        ...(mount.readOnly === undefined ? {} : { readOnly: mount.readOnly }),
         plugin: {
             id: mount.plugin.id,
-            config: mount.plugin.config ?? {},
+            ...(mount.plugin.config === undefined
+                ? {}
+                : { config: mount.plugin.config }),
         },
     };
 }
-export function serializeRootFilesystemForSidecar(config, bootstrapLower) {
-    const lowerInputs = [
-        ...(config?.lowers ?? []),
-        ...(bootstrapLower ? [bootstrapLower] : []),
-    ];
+export function serializeRootFilesystemForSidecar(config) {
     return {
-        mode: config?.mode === "read-only" ? "read-only" : "ephemeral",
-        disableDefaultBaseLayer: config?.disableDefaultBaseLayer ?? false,
-        lowers: lowerInputs.map(serializeRootLowerForSidecar),
-        bootstrapEntries: [],
+        ...(config?.mode !== undefined ? { mode: config.mode } : {}),
+        ...(config?.disableDefaultBaseLayer !== undefined
+            ? { disableDefaultBaseLayer: config.disableDefaultBaseLayer }
+            : {}),
+        ...(config?.lowers !== undefined
+            ? { lowers: config.lowers.map(serializeRootLowerForSidecar) }
+            : {}),
     };
 }
 function clonePlacement(placement) {
@@ -2023,21 +1032,16 @@ function clonePlacement(placement) {
         sidecarId: placement.sidecarId,
     };
 }
-function cloneMetadata(metadata) {
-    return { ...(metadata ?? {}) };
-}
 function cloneSessionLifecycle(lifecycle) {
     return {
         ...lifecycle,
         placement: clonePlacement(lifecycle.placement),
-        metadata: cloneMetadata(lifecycle.metadata),
         vmIds: [...lifecycle.vmIds],
     };
 }
 function cloneVmLifecycle(lifecycle) {
     return {
         ...lifecycle,
-        metadata: cloneMetadata(lifecycle.metadata),
     };
 }
 function serializeRootLowerForSidecar(lower) {