@rivet-dev/agentos-core 0.0.0-integrate-dylib-into-main.815fcda → 0.0.0-main.29b0797

package/dist/agent-os.js

@@ -1,32 +1,141 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, posix as posixPath, resolve as resolveHostPath, } from "node:path";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, posix as posixPath, resolve as resolveHostPath, } from "node:path";
 import { fileURLToPath } from "node:url";
-import { validateToolkits } from "./host-tools.js";
-import { zodToJsonSchema } from "./host-tools-zod.js";
+import { validateBindings } from "./bindings.js";
+import { zodToJsonSchema } from "./bindings-zod.js";
+import { parseAgentOsOptions } from "./options-schema.js";
 import { resolvePublishedSidecarBinary } from "./sidecar/binary.js";
 import { findCargoBinary, resolveCargoBinary } from "./sidecar/cargo.js";
-export { isAcpTimeoutErrorData } from "./json-rpc.js";
 const ACP_PROTOCOL_VERSION = 1;
 const ACP_EXTENSION_NAMESPACE = "dev.rivet.agent-os.acp";
 const SHELL_DISPOSE_TIMEOUT_MS = 5_000;
-/**
- * Reserved `env` key on `AcpResumeSessionRequest` carrying the resolved adapter
- * bin entrypoint. The resume wire request omits a dedicated `adapterEntrypoint`
- * field; the sidecar reads the entrypoint from this key and strips it before
- * launching the adapter. Must stay in sync with the sidecar constant of the same
- * name in `crates/agentos-sidecar/src/acp_extension.rs`.
- */
-const RESUME_ADAPTER_ENTRYPOINT_ENV = "AGENT_OS_RESUME_ADAPTER_ENTRYPOINT";
-function defaultAcpClientCapabilities() {
+function safeWireU64(value) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0) {
+        throw new RangeError(`wire integer ${value} exceeds JavaScript's safe range`);
+    }
+    return result;
+}
+function decodeDurableSessionInfo(value) {
     return {
-        fs: {
-            readTextFile: true,
-            writeTextFile: true,
-        },
-        terminal: true,
+        sessionId: value.sessionId,
+        agent: value.agent,
+        cwd: value.cwd,
+        additionalDirectories: JSON.parse(value.additionalDirectories),
+        state: JSON.parse(value.state),
+        latestSequence: safeWireU64(value.latestSequence),
+        title: value.title ?? undefined,
+        metadata: value.metadata === null ? undefined : JSON.parse(value.metadata),
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+    };
+}
+const PERMISSION_TERMINAL_REASONS = new Set([
+    "already_resolved",
+    "prompt_cancelled",
+    "adapter_exited",
+    "session_deleted",
+    "vm_shutdown",
+    "request_not_found",
+]);
+function permissionTerminalReason(value) {
+    if (value !== null &&
+        PERMISSION_TERMINAL_REASONS.has(value)) {
+        return value;
+    }
+    throw new Error(`invalid permission terminal reason: ${value ?? "missing"}`);
+}
+function decodeDurableSessionEvent(value) {
+    const envelope = {
+        durability: "durable",
+        sessionId: value.sessionId,
+        sequence: safeWireU64(value.sequence),
+        timestamp: value.timestamp,
+    };
+    switch (value.event.tag) {
+        case "AcpDurableSessionUpdate": {
+            const update = JSON.parse(value.event.val.update);
+            const { sessionUpdate: type, ...payload } = update;
+            return {
+                ...envelope,
+                type,
+                ...payload,
+            };
+        }
+        case "AcpDurablePermissionRequest": {
+            const request = JSON.parse(value.event.val.request);
+            const { sessionId: _sessionId, ...payload } = request;
+            return {
+                ...envelope,
+                type: "permission_request",
+                requestId: value.event.val.requestId,
+                ...payload,
+            };
+        }
+        case "AcpDurablePermissionResponse": {
+            const status = value.event.val.status;
+            if (status !== "accepted" && status !== "not_pending") {
+                throw new Error(`invalid permission response event status: ${status}`);
+            }
+            const response = JSON.parse(value.event.val.response);
+            return {
+                ...envelope,
+                type: "permission_response",
+                requestId: value.event.val.requestId,
+                ...response,
+                status,
+                ...(value.event.val.reason === null
+                    ? {}
+                    : { reason: permissionTerminalReason(value.event.val.reason) }),
+            };
+        }
+    }
+}
+function normalizeSessionCapabilities(value) {
+    const capabilities = toRecord(value);
+    const prompt = toRecord(capabilities.promptCapabilities);
+    const mcp = toRecord(capabilities.mcpCapabilities);
+    const session = toRecord(capabilities.sessionCapabilities);
+    const extensions = Object.fromEntries(Object.entries(capabilities).filter(([key]) => ![
+        "loadSession",
+        "promptCapabilities",
+        "mcpCapabilities",
+        "sessionCapabilities",
+    ].includes(key)));
+    return {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        loadSession: capabilities.loadSession === true,
+        ...(Object.keys(prompt).length > 0
+            ? {
+                prompt: {
+                    audio: prompt.audio === true || undefined,
+                    embeddedContext: prompt.embeddedContext === true || undefined,
+                    image: prompt.image === true || undefined,
+                },
+            }
+            : {}),
+        ...(Object.keys(mcp).length > 0
+            ? {
+                mcp: {
+                    http: mcp.http === true || undefined,
+                    sse: mcp.sse === true || undefined,
+                },
+            }
+            : {}),
+        ...(Object.keys(session).length > 0
+            ? {
+                session: {
+                    list: typeof session.list === "object" || undefined,
+                    resume: typeof session.resume === "object" || undefined,
+                    close: typeof session.close === "object" || undefined,
+                    delete: typeof session.delete === "object" || undefined,
+                    additionalDirectories: typeof session.additionalDirectories === "object" || undefined,
+                },
+            }
+            : {}),
+        ...(Object.keys(extensions).length > 0 ? { extensions } : {}),
     };
 }
 async function waitForTrackedExitPromises(promises, timeoutMs) {
@@ -40,21 +149,24 @@ async function waitForTrackedExitPromises(promises, timeoutMs) {
         }),
     ]);
 }
-import { AGENT_CONFIGS } from "./agents.js";
-import { getBaseEnvironment, getBaseFilesystemEntries, } from "./base-filesystem.js";
+import { OPT_AGENTOS_ROOT, } from "./agentos-package.js";
+import { getBaseEnvironment } from "./base-filesystem.js";
 import { CronManager } from "./cron/cron-manager.js";
 import { TimerScheduleDriver } from "./cron/timer-driver.js";
+import { resolveDefaultSoftware } from "./default-software.js";
 import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-snapshot.js";
-import { createHostDirBackend } from "./host-dir-mount.js";
 import { serializeMountConfigForSidecar, } from "./js-bridge.js";
 import { createSnapshotExport, } from "./layers.js";
-import { processSoftware, resolvePackageDir, } from "./packages.js";
 import { allowAll } from "./runtime-compat.js";
-import { AcpRuntimeKind, decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agentos-protocol.js";
+import { decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agentos-protocol.js";
 import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
-import { createAgentOsSidecarClient, NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSidecarKernelProxy, SidecarProcess, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
-const LEGACY_PERMISSION_METHOD = "request/permission";
-const ACP_PERMISSION_METHOD = "session/request_permission";
+import { createAgentOsSidecarClient, NativeSidecarKernelProxy, SidecarProcess, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
+function defaultAgentStderrHandler(event) {
+    process.stderr.write(event.chunk);
+}
+function defaultAgentExitHandler(event) {
+    process.stderr.write(`[agentos] agent adapter exited unexpectedly: session=${event.sessionId} agent=${event.agentType} exitCode=${event.exitCode ?? "unknown"}; restore explicitly before retrying\n`);
+}
 class AcpDispatchError extends Error {
     code;
     data;
@@ -105,51 +217,28 @@ function toRecord(value) {
         ? value
         : {};
 }
-function parseAcpJson(value, context) {
-    if (value === null) {
-        return undefined;
+function normalizePackageRef(value) {
+    // The single package reference is `packagePath`: the packed `.aospkg` file
+    // (registry-built packages export `{ packagePath }`), or a package dir for
+    // local transition fixtures. A raw string is shorthand for the same path.
+    if (typeof value === "string") {
+        return { path: value };
     }
-    try {
-        return JSON.parse(value);
+    const record = toRecord(value);
+    if (typeof record.packagePath === "string") {
+        return { path: record.packagePath };
     }
-    catch (error) {
-        throw new Error(`invalid ACP ${context} JSON: ${error instanceof Error ? error.message : String(error)}`);
+    // Recognizably-legacy shapes fail loudly: silently dropping a software
+    // entry boots a VM with missing packages and no diagnostic.
+    for (const legacy of ["packageTar", "packageDir", "dir"]) {
+        if (typeof record[legacy] === "string") {
+            throw new Error(`agentOS package ref uses removed field "${legacy}" (value: ${JSON.stringify(record[legacy])}); ` +
+                "packages are referenced by a single `packagePath` — update the package " +
+                "(rebuild @agentos-software/* dependencies) or pass { packagePath }");
+        }
     }
+    return undefined;
 }
-function parseAcpJsonList(values, context) {
-    return values.map((value, index) => parseAcpJson(value, `${context}[${index}]`));
-}
-function sidecarSessionCreatedFromAcp(response) {
-    return {
-        sessionId: response.sessionId,
-        ...(response.pid !== null ? { pid: response.pid } : {}),
-        modes: parseAcpJson(response.modes, "modes"),
-        configOptions: parseAcpJsonList(response.configOptions, "configOptions"),
-        agentCapabilities: parseAcpJson(response.agentCapabilities, "agentCapabilities"),
-        agentInfo: parseAcpJson(response.agentInfo, "agentInfo"),
-    };
-}
-function sidecarSessionStateFromAcp(response) {
-    return {
-        sessionId: response.sessionId,
-        agentType: response.agentType,
-        processId: response.processId,
-        ...(response.pid !== null ? { pid: response.pid } : {}),
-        closed: response.closed,
-        modes: parseAcpJson(response.modes, "modes"),
-        configOptions: parseAcpJsonList(response.configOptions, "configOptions"),
-        agentCapabilities: parseAcpJson(response.agentCapabilities, "agentCapabilities"),
-        agentInfo: parseAcpJson(response.agentInfo, "agentInfo"),
-    };
-}
-function isLocalCancelledPromptResponse(method, response) {
-    const result = toRecord(response.result);
-    return (method === "session/prompt" &&
-        response.id === null &&
-        response.error === undefined &&
-        result.stopReason === "cancelled");
-}
-const CLOSED_SESSION_ID_RETENTION_LIMIT = 2048;
 const CLOSED_SHELL_ID_RETENTION_LIMIT = 2048;
 class BoundedSet {
     limit;
@@ -160,11 +249,11 @@ class BoundedSet {
         }
         this.limit = limit;
     }
-    add(value) {
+    add(value, associated) {
         if (this.#entries.has(value)) {
             this.#entries.delete(value);
         }
-        this.#entries.set(value, undefined);
+        this.#entries.set(value, associated);
         if (this.#entries.size <= this.limit) {
             return;
         }
@@ -176,6 +265,9 @@ class BoundedSet {
     has(value) {
         return this.#entries.has(value);
     }
+    get(value) {
+        return this.#entries.get(value);
+    }
     delete(value) {
         return this.#entries.delete(value);
     }
@@ -183,50 +275,6 @@ class BoundedSet {
         return this.#entries.size;
     }
 }
-function shouldDispatchToSessionEventHandlers(notification) {
-    return notification.method === "session/update";
-}
-function toSessionModes(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return null;
-    }
-    return value;
-}
-function toSessionConfigOptions(value) {
-    return Array.isArray(value) ? value : [];
-}
-function toAgentCapabilities(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return {};
-    }
-    return value;
-}
-function toAgentInfo(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return null;
-    }
-    if (typeof value.name !== "string") {
-        return null;
-    }
-    return value;
-}
-function sessionEntryFromInit(sessionId, agentType, initData) {
-    return {
-        sessionId,
-        agentType,
-        processId: "",
-        pid: null,
-        closed: false,
-        modes: initData.modes ?? null,
-        configOptions: initData.configOptions ?? [],
-        capabilities: initData.capabilities ?? {},
-        agentInfo: initData.agentInfo ?? null,
-        eventHandlers: new Set(),
-        permissionHandlers: new Set(),
-        configOverrides: new Map(),
-        pendingPermissionReplies: new Map(),
-    };
-}
 function isOverlayMountConfig(config) {
     return "filesystem" in config;
 }
@@ -366,7 +414,8 @@ const KERNEL_POSIX_BOOTSTRAP_DIRS = [
     "/mnt",
     "/media",
     "/home",
-    "/home/user",
+    "/home/agentos",
+    "/workspace",
     "/usr",
     "/usr/bin",
     "/usr/games",
@@ -390,130 +439,59 @@ const KERNEL_POSIX_BOOTSTRAP_DIRS = [
     "/var/tmp",
     "/etc/agentos",
 ];
-const NODE_RUNTIME_BOOTSTRAP_COMMANDS = ["node", "npm", "npx"];
-const KERNEL_COMMAND_STUB = "#!/bin/sh\n# kernel command stub\n";
+// Standard POSIX metadata for the bootstrap dirs whose mode/owner is NOT the
+// default (`755`, root:root). Replicated as a constant so building the no-base
+// bootstrap layer needs no `base-filesystem.json` read — when a base IS present
+// the sidecar's embedded base layer is authoritative and these are never emitted.
+const KERNEL_POSIX_BOOTSTRAP_DIR_METADATA = {
+    "/tmp": { mode: "1777", uid: 0, gid: 0 },
+    "/root": { mode: "700", uid: 0, gid: 0 },
+    "/sys": { mode: "555", uid: 0, gid: 0 },
+    "/home/agentos": { mode: "2755", uid: 1000, gid: 1000 },
+    "/workspace": { mode: "755", uid: 1000, gid: 1000 },
+    "/var/empty": { mode: "555", uid: 0, gid: 0 },
+    "/var/lock": { mode: "777", uid: 0, gid: 0 },
+    "/var/run": { mode: "777", uid: 0, gid: 0 },
+    "/var/tmp": { mode: "1777", uid: 0, gid: 0 },
+};
+// Runtime commands that get a `/bin/<cmd>` stub at bootstrap so the guest shell
+// resolves them on PATH (e.g. `sh -c "python ..."`, pipelines). The sidecar
+// intercepts these by name and routes them to the embedded V8 / Pyodide runtime.
+const RUNTIME_BOOTSTRAP_COMMANDS = [
+    "node",
+    "npm",
+    "npx",
+    "python",
+    "python3",
+];
 const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
 const SIDECAR_BINARY = join(REPO_ROOT, "target/debug/agentos-sidecar");
 const SIDECAR_BUILD_INPUTS = [
     join(REPO_ROOT, "Cargo.toml"),
     join(REPO_ROOT, "Cargo.lock"),
     join(REPO_ROOT, "crates/bridge"),
+    join(REPO_ROOT, "crates/build-support"),
     join(REPO_ROOT, "crates/execution"),
     join(REPO_ROOT, "crates/kernel"),
-    join(REPO_ROOT, "crates/sidecar"),
+    join(REPO_ROOT, "crates/agentos-protocol"),
+    join(REPO_ROOT, "crates/agentos-sidecar"),
+    join(REPO_ROOT, "crates/native-sidecar"),
+    join(REPO_ROOT, "crates/native-sidecar-core"),
+    join(REPO_ROOT, "crates/sidecar-protocol"),
+    join(REPO_ROOT, "crates/v8-runtime"),
+    join(REPO_ROOT, "crates/vfs"),
+    join(REPO_ROOT, "crates/vm-config"),
+    join(REPO_ROOT, "packages/build-tools/bridge-src"),
+    join(REPO_ROOT, "packages/build-tools/package.json"),
+    join(REPO_ROOT, "packages/build-tools/scripts/build-v8-bridge.mjs"),
+    join(REPO_ROOT, "packages/core/fixtures/base-filesystem.json"),
+    join(REPO_ROOT, "packages/runtime-core/fixtures/base-filesystem.json"),
+    join(REPO_ROOT, "pnpm-lock.yaml"),
 ];
 let ensuredSidecarBinary = null;
-function isWasmBinaryFile(path) {
-    try {
-        const header = readFileSync(path);
-        return (header.length >= 4 &&
-            header[0] === 0x00 &&
-            header[1] === 0x61 &&
-            header[2] === 0x73 &&
-            header[3] === 0x6d);
-    }
-    catch {
-        return false;
-    }
-}
-function collectBootstrapWasmCommands(commandDirs) {
-    const commands = [];
-    const seen = new Set();
-    for (const dir of commandDirs) {
-        let entries;
-        try {
-            entries = readdirSync(dir).sort((a, b) => a.localeCompare(b));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (entry.startsWith(".")) {
-                continue;
-            }
-            const fullPath = join(dir, entry);
-            try {
-                if (statSync(fullPath).isDirectory()) {
-                    continue;
-                }
-            }
-            catch {
-                continue;
-            }
-            if (!isWasmBinaryFile(fullPath) || seen.has(entry)) {
-                continue;
-            }
-            seen.add(entry);
-            commands.push(entry);
-        }
-    }
-    return commands;
-}
-function resolveDeclaredCommandSource(commandDir, commandName, aliases) {
-    let current = commandName;
-    const visited = new Set();
-    while (!visited.has(current)) {
-        visited.add(current);
-        const candidatePath = join(commandDir, current);
-        if (isWasmBinaryFile(candidatePath)) {
-            return candidatePath;
-        }
-        const next = aliases[current];
-        if (!next) {
-            return null;
-        }
-        current = next;
-    }
-    return null;
-}
-function prepareCommandDirs(commandPackages) {
-    const commandDirs = [];
-    const tempDirs = [];
-    try {
-        for (const commandPackage of commandPackages) {
-            commandDirs.push(commandPackage.commandDir);
-            const aliasEntries = Object.entries(commandPackage.aliases)
-                .sort(([leftAlias], [rightAlias]) => leftAlias.localeCompare(rightAlias))
-                .flatMap(([aliasName]) => {
-                const aliasPath = join(commandPackage.commandDir, aliasName);
-                if (isWasmBinaryFile(aliasPath)) {
-                    return [];
-                }
-                const sourcePath = resolveDeclaredCommandSource(commandPackage.commandDir, aliasName, commandPackage.aliases);
-                if (!sourcePath) {
-                    return [];
-                }
-                return [[aliasName, sourcePath]];
-            });
-            if (aliasEntries.length === 0) {
-                continue;
-            }
-            const aliasDir = mkdtempSync(join(tmpdir(), "agentos-command-aliases-"));
-            for (const [aliasName, sourcePath] of aliasEntries) {
-                writeFileSync(join(aliasDir, aliasName), readFileSync(sourcePath));
-            }
-            tempDirs.push(aliasDir);
-            commandDirs.push(aliasDir);
-        }
-    }
-    catch (error) {
-        for (const tempDir of tempDirs) {
-            rmSync(tempDir, { recursive: true, force: true });
-        }
-        throw error;
-    }
-    return {
-        commandDirs,
-        dispose() {
-            for (const tempDir of tempDirs) {
-                rmSync(tempDir, { recursive: true, force: true });
-            }
-        },
-    };
-}
 function collectConfiguredLowerPaths(config) {
     const paths = new Set();
-    for (const lower of config?.lowers ?? []) {
+    for (const lower of config?.type === "native" ? [] : (config?.lowers ?? [])) {
         if (lower.kind !== "snapshot-export") {
             continue;
         }
@@ -524,7 +502,7 @@ function collectConfiguredLowerPaths(config) {
     return paths;
 }
 function findBootstrapSeedEntry(config, path) {
-    for (const lower of config?.lowers ?? []) {
+    for (const lower of config?.type === "native" ? [] : (config?.lowers ?? [])) {
         if (lower.kind !== "snapshot-export") {
             continue;
         }
@@ -533,16 +511,18 @@ function findBootstrapSeedEntry(config, path) {
             return entry;
         }
     }
-    return getBaseFilesystemEntries().find((entry) => entry.path === path);
+    // No base-filesystem JSON read: standard non-default dir metadata comes from
+    // the constant table. When a base layer IS present these dirs are never
+    // emitted (see createKernelBootstrapLower), so this only seeds the no-base case.
+    const meta = KERNEL_POSIX_BOOTSTRAP_DIR_METADATA[path];
+    return meta ? { path, type: "directory", ...meta } : undefined;
 }
-function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
+function createKernelBootstrapLower(config, extraEntries = []) {
+    if (config?.type === "native") {
+        return null;
+    }
     const includesBundledBaseLayer = !(config?.disableDefaultBaseLayer ?? false);
     const existingPaths = collectConfiguredLowerPaths(config);
-    if (includesBundledBaseLayer) {
-        for (const entry of getBaseFilesystemEntries()) {
-            existingPaths.add(entry.path);
-        }
-    }
     const entries = [
         {
             path: "/",
@@ -552,18 +532,24 @@ function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
             gid: 0,
         },
     ];
-    for (const dir of KERNEL_POSIX_BOOTSTRAP_DIRS) {
-        if (existingPaths.has(dir)) {
-            continue;
+    // Only run the FS bootstrap (creating the POSIX dir tree) when there is NO
+    // base layer. When the bundled base IS present, the sidecar's embedded base
+    // layer already provides every POSIX dir with the correct mode/owner, so we
+    // emit nothing here and never read its filesystem table.
+    if (!includesBundledBaseLayer) {
+        for (const dir of KERNEL_POSIX_BOOTSTRAP_DIRS) {
+            if (existingPaths.has(dir)) {
+                continue;
+            }
+            const seed = findBootstrapSeedEntry(config, dir);
+            entries.push({
+                path: dir,
+                type: "directory",
+                mode: seed?.type === "directory" ? seed.mode : "755",
+                uid: seed?.uid ?? 0,
+                gid: seed?.gid ?? 0,
+            });
         }
-        const seed = findBootstrapSeedEntry(config, dir);
-        entries.push({
-            path: dir,
-            type: "directory",
-            mode: seed?.type === "directory" ? seed.mode : "755",
-            uid: seed?.uid ?? 0,
-            gid: seed?.gid ?? 0,
-        });
     }
     if (!includesBundledBaseLayer && !existingPaths.has("/usr/bin/env")) {
         entries.push({
@@ -576,22 +562,6 @@ function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
             encoding: "base64",
         });
     }
-    const uniqueCommands = [...new Set(commandNames)].sort((a, b) => a.localeCompare(b));
-    for (const command of uniqueCommands) {
-        const stubPath = `/bin/${command}`;
-        if (existingPaths.has(stubPath)) {
-            continue;
-        }
-        entries.push({
-            path: stubPath,
-            type: "file",
-            mode: "755",
-            uid: 0,
-            gid: 0,
-            content: KERNEL_COMMAND_STUB,
-            encoding: "utf8",
-        });
-    }
     for (const entry of sortFilesystemEntries(extraEntries)) {
         if (existingPaths.has(entry.path)) {
             continue;
@@ -619,7 +589,7 @@ function buildLiveBootstrapDirectoryEntries(existingPaths, config) {
     return entries;
 }
 async function bootstrapLiveBootstrapDirectories(client, session, vm, config) {
-    const existingPaths = new Set((await client.snapshotRootFilesystem(session, vm)).map((entry) => entry.path));
+    const existingPaths = new Set((await client.snapshotRootFilesystem(session, vm, Number.MAX_SAFE_INTEGER)).map((entry) => entry.path));
     const entries = buildLiveBootstrapDirectoryEntries(existingPaths, config);
     if (entries.length === 0) {
         return;
@@ -706,28 +676,6 @@ function latestMtimeMs(path) {
     }
     return latest;
 }
-function collectGuestCommandPaths(commandDirs) {
-    const guestPaths = new Map();
-    for (const [index, commandDir] of commandDirs.entries()) {
-        let entries;
-        try {
-            entries = readdirSync(commandDir).sort((left, right) => left.localeCompare(right));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (entry.startsWith(".")) {
-                continue;
-            }
-            if (!isWasmBinaryFile(join(commandDir, entry)) || guestPaths.has(entry)) {
-                continue;
-            }
-            guestPaths.set(entry, `/__secure_exec/commands/${index}/${entry}`);
-        }
-    }
-    return guestPaths;
-}
 async function resolveCompatLocalMounts(mounts) {
     if (!mounts) {
         return [];
@@ -796,57 +744,32 @@ function collectSidecarMountPlan(options) {
     }
     for (const mount of options.mounts ?? []) {
         if (!isNativeMountConfig(mount)) {
+            sidecarMounts.push({
+                guestPath: mount.path,
+                readOnly: isOverlayMountConfig(mount)
+                    ? (mount.filesystem.mode ?? "ephemeral") === "read-only"
+                    : (mount.readOnly ?? false),
+                plugin: {
+                    id: "js_bridge",
+                    config: {},
+                },
+            });
             continue;
         }
         pushMount(mount);
     }
-    for (const root of options.softwareRoots) {
-        pushMount({
-            path: root.vmPath,
-            plugin: createHostDirBackend({
-                hostPath: root.hostPath,
-                readOnly: true,
-            }),
-            readOnly: true,
-        });
-    }
-    for (const [index, commandDir] of options.commandDirs.entries()) {
-        pushMount({
-            path: `/__secure_exec/commands/${index}`,
-            plugin: createHostDirBackend({
-                hostPath: commandDir,
-                readOnly: true,
-            }),
-            readOnly: true,
-        });
-    }
-    if (options.shimDir) {
-        pushMount({
-            path: "/usr/local/bin",
-            plugin: createHostDirBackend({
-                hostPath: options.shimDir,
-                readOnly: true,
-            }),
-            readOnly: true,
-        });
-    }
     hostMounts.sort((left, right) => right.vmPath.length - left.vmPath.length);
     hostPathMappings.sort((left, right) => right.vmPath.length - left.vmPath.length);
     return { sidecarMounts, hostMounts, hostPathMappings };
 }
-function materializeToolShimDir(toolKits) {
-    const shimDir = mkdtempSync(join(tmpdir(), "agentos-host-tools-shims-"));
-    writeFileSync(join(shimDir, "agentos"), KERNEL_COMMAND_STUB, { mode: 0o755 });
-    for (const toolKit of toolKits) {
-        writeFileSync(join(shimDir, `agentos-${toolKit.name}`), KERNEL_COMMAND_STUB, { mode: 0o755 });
-    }
-    return shimDir;
-}
-function collectToolkitBootstrapCommands(toolKits) {
-    if (toolKits.length === 0) {
+function collectBindingBootstrapCommands(bindings) {
+    if (bindings.length === 0) {
         return [];
     }
-    return ["agentos", ...toolKits.map((toolKit) => `agentos-${toolKit.name}`)];
+    return [
+        "agentos",
+        ...bindings.map((bindingCollection) => `agentos-${bindingCollection.name}`),
+    ];
 }
 function validationMessage(error) {
     if (typeof error === "object" &&
@@ -864,14 +787,16 @@ function validationMessage(error) {
     }
     return error instanceof Error ? error.message : String(error);
 }
-function toolToSidecarDefinition(tool) {
+function bindingToSidecarDefinition(definition) {
     return {
-        description: tool.description,
-        inputSchema: zodToJsonSchema(tool.inputSchema),
-        ...(tool.timeout !== undefined ? { timeoutMs: tool.timeout } : {}),
-        ...(tool.examples && tool.examples.length > 0
+        description: definition.description,
+        inputSchema: zodToJsonSchema(definition.inputSchema),
+        ...(definition.timeout !== undefined
+            ? { timeoutMs: definition.timeout }
+            : {}),
+        ...(definition.examples && definition.examples.length > 0
             ? {
-                examples: tool.examples.map((example) => ({
+                examples: definition.examples.map((example) => ({
                     description: example.description,
                     input: example.input,
                 })),
@@ -879,8 +804,8 @@ function toolToSidecarDefinition(tool) {
             : {}),
     };
 }
-function combineInstructions(additionalInstructions, toolReference) {
-    const parts = [additionalInstructions, toolReference]
+function combineInstructions(additionalInstructions, bindingReference) {
+    const parts = [additionalInstructions, bindingReference]
         .map((part) => part?.trim())
         .filter((part) => Boolean(part));
     if (parts.length === 0) {
@@ -888,48 +813,48 @@ function combineInstructions(additionalInstructions, toolReference) {
     }
     return parts.join("\n\n");
 }
-function buildHostToolReference(toolKits) {
-    if (toolKits.length === 0) {
+function buildBindingReference(bindings) {
+    if (bindings.length === 0) {
         return "";
     }
     const lines = [
-        "## Available Host Tools",
+        "## Available Host Bindings",
         "",
-        "Run `agentos list-tools` to see all available tools.",
+        "Run `agentos list-bindings` to see all available bindings.",
         "",
     ];
-    for (const toolKit of toolKits) {
-        lines.push(`### ${toolKit.name}`);
+    for (const bindingCollection of bindings) {
+        lines.push(`### ${bindingCollection.name}`);
         lines.push("");
-        lines.push(toolKit.description);
+        lines.push(bindingCollection.description);
         lines.push("");
-        for (const [toolName, tool] of Object.entries(toolKit.tools)) {
-            const sidecarTool = toolToSidecarDefinition(tool);
-            const signature = buildToolFlagSignature(sidecarTool.inputSchema);
+        for (const [bindingName, definition] of Object.entries(bindingCollection.bindings)) {
+            const sidecarBinding = bindingToSidecarDefinition(definition);
+            const signature = buildBindingFlagSignature(sidecarBinding.inputSchema);
             const suffix = signature.length > 0 ? ` ${signature}` : "";
-            lines.push(`- \`agentos-${toolKit.name} ${toolName}${suffix}\` — ${tool.description}`);
+            lines.push(`- \`agentos-${bindingCollection.name} ${bindingName}${suffix}\` — ${definition.description}`);
         }
         lines.push("");
-        const toolsWithExamples = Object.entries(toolKit.tools).filter(([, tool]) => tool.examples && tool.examples.length > 0);
-        if (toolsWithExamples.length > 0) {
+        const bindingsWithExamples = Object.entries(bindingCollection.bindings).filter(([, definition]) => definition.examples && definition.examples.length > 0);
+        if (bindingsWithExamples.length > 0) {
             lines.push("**Examples:**");
             lines.push("");
-            for (const [toolName, tool] of toolsWithExamples) {
-                for (const example of tool.examples ?? []) {
-                    const args = inputToToolFlags(example.input);
+            for (const [bindingName, definition] of bindingsWithExamples) {
+                for (const example of definition.examples ?? []) {
+                    const args = inputToBindingFlags(example.input);
                     const suffix = args.length > 0 ? ` ${args}` : "";
-                    lines.push(`- ${example.description}: \`agentos-${toolKit.name} ${toolName}${suffix}\``);
+                    lines.push(`- ${example.description}: \`agentos-${bindingCollection.name} ${bindingName}${suffix}\``);
                 }
             }
             lines.push("");
         }
-        lines.push(`Run \`agentos-${toolKit.name} <tool> --help\` for details.`);
+        lines.push(`Run \`agentos-${bindingCollection.name} <binding> --help\` for details.`);
         lines.push("");
     }
     return lines.join("\n");
 }
-function buildToolFlagSignature(schema) {
-    return describeToolFlags(schema)
+function buildBindingFlagSignature(schema) {
+    return describeBindingFlags(schema)
         .map((flag) => {
         if (flag.required) {
             return `${flag.name} <${flag.type}>`;
@@ -938,7 +863,7 @@ function buildToolFlagSignature(schema) {
     })
         .join(" ");
 }
-function describeToolFlags(schema) {
+function describeBindingFlags(schema) {
     const schemaObject = asRecord(schema);
     const properties = asRecord(schemaObject.properties);
     const required = Array.isArray(schemaObject.required)
@@ -946,11 +871,11 @@ function describeToolFlags(schema) {
         : new Set();
     return Object.entries(properties).map(([fieldName, fieldSchema]) => ({
         name: `--${camelToKebab(fieldName)}`,
-        type: describeToolFlagType(fieldSchema),
+        type: describeBindingFlagType(fieldSchema),
         required: required.has(fieldName),
     }));
 }
-function describeToolFlagType(schema) {
+function describeBindingFlagType(schema) {
     const schemaObject = asRecord(schema);
     const type = typeof schemaObject.type === "string" ? schemaObject.type : undefined;
     if (type === "array") {
@@ -969,7 +894,7 @@ function describeJsonSchemaScalarType(schema) {
     const schemaObject = asRecord(schema);
     return typeof schemaObject.type === "string" ? schemaObject.type : "string";
 }
-function inputToToolFlags(input) {
+function inputToBindingFlags(input) {
     const inputObject = asRecord(input);
     return Object.entries(inputObject)
         .flatMap(([key, value]) => {
@@ -981,13 +906,13 @@ function inputToToolFlags(input) {
             return [`--no-${camelToKebab(key)}`];
         }
         if (Array.isArray(value)) {
-            return value.map((item) => `${flag} ${toolCliString(item)}`);
+            return value.map((item) => `${flag} ${bindingCliString(item)}`);
         }
-        return [`${flag} ${toolCliString(value)}`];
+        return [`${flag} ${bindingCliString(value)}`];
     })
         .join(" ");
 }
-function toolCliString(value) {
+function bindingCliString(value) {
     return typeof value === "string" ? value : (JSON.stringify(value) ?? "null");
 }
 function camelToKebab(value) {
@@ -1025,23 +950,23 @@ async function handleHostCallback(request, context) {
             };
         }
     }
-    const tool = context.toolMap.get(payload.callback_key);
-    if (!tool) {
+    const definition = context.bindingMap.get(payload.callback_key);
+    if (!definition) {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            error: `Unknown tool "${payload.callback_key}"`,
+            error: `Unknown binding "${payload.callback_key}"`,
         };
     }
-    const permissionMode = toolPermissionMode(context.permissions, payload.callback_key);
+    const permissionMode = bindingPermissionMode(context.permissions, payload.callback_key);
     if (permissionMode !== "allow") {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            error: `EACCES: blocked by tool.invoke policy for ${payload.callback_key}`,
+            error: `EACCES: blocked by binding.invoke policy for ${payload.callback_key}`,
         };
     }
-    const parsed = tool.inputSchema.safeParse(payload.input);
+    const parsed = definition.inputSchema.safeParse(payload.input);
     if (!parsed.success) {
         return {
             type: "host_callback_result",
@@ -1053,7 +978,7 @@ async function handleHostCallback(request, context) {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            result: await executeHostTool(tool, payload.callback_key, parsed.data),
+            result: await executeBinding(definition, payload.callback_key, parsed.data),
         };
     }
     catch (error) {
@@ -1064,14 +989,142 @@ async function handleHostCallback(request, context) {
         };
     }
 }
-function buildToolMap(toolKits) {
-    const toolMap = new Map();
-    for (const toolKit of toolKits) {
-        for (const [toolName, tool] of Object.entries(toolKit.tools)) {
-            toolMap.set(`${toolKit.name}:${toolName}`, tool);
+function buildBindingMap(bindings) {
+    const bindingMap = new Map();
+    for (const bindingCollection of bindings) {
+        for (const [bindingName, definition] of Object.entries(bindingCollection.bindings)) {
+            bindingMap.set(`${bindingCollection.name}:${bindingName}`, definition);
+        }
+    }
+    return bindingMap;
+}
+function bridgeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function toBridgeArgs(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("js_bridge args must be an object");
+    }
+    return value;
+}
+function bridgePath(mountId, value) {
+    if (!mountId.startsWith("/")) {
+        throw new Error(`Unsupported js_bridge mount id: ${mountId}`);
+    }
+    if (typeof value !== "string") {
+        throw new Error("js_bridge path argument must be a string");
+    }
+    return posixPath.normalize(posixPath.join(mountId, value));
+}
+function requireBridgeNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`js_bridge args.${field} must be a number`);
+    }
+    return value;
+}
+function decodeBridgeBytes(value, field) {
+    if (typeof value === "string") {
+        return new Uint8Array(Buffer.from(value, "base64"));
+    }
+    if (Array.isArray(value) &&
+        value.every((entry) => Number.isInteger(entry) && entry >= 0 && entry <= 255)) {
+        return new Uint8Array(value);
+    }
+    throw new Error(`js_bridge args.${field} must be base64 bytes`);
+}
+async function handleJsBridgeCall(request, context) {
+    try {
+        const args = toBridgeArgs(request.args);
+        const fs = context.filesystem;
+        const path = () => bridgePath(request.mount_id, args.path);
+        let result;
+        switch (request.operation) {
+            case "readFile":
+                result = Buffer.from(await fs.readFile(path())).toString("base64");
+                break;
+            case "readDir":
+                result = await fs.readDir(path());
+                break;
+            case "readDirWithTypes":
+                result = await fs.readDirWithTypes(path());
+                break;
+            case "writeFile":
+                await fs.writeFile(path(), decodeBridgeBytes(args.content, "content"));
+                break;
+            case "createDir":
+                await fs.createDir(path());
+                break;
+            case "mkdir":
+                await fs.mkdir(path(), { recursive: args.recursive !== false });
+                break;
+            case "exists":
+                result = await fs.exists(path());
+                break;
+            case "stat":
+                result = await fs.stat(path());
+                break;
+            case "removeFile":
+                await fs.removeFile(path());
+                break;
+            case "removeDir":
+                await fs.removeDir(path());
+                break;
+            case "rename":
+                await fs.rename(bridgePath(request.mount_id, args.oldPath), bridgePath(request.mount_id, args.newPath));
+                break;
+            case "realpath":
+                result = await fs.realpath(path());
+                break;
+            case "symlink": {
+                if (typeof args.target !== "string") {
+                    throw new Error("js_bridge args.target must be a string");
+                }
+                await fs.symlink(args.target, bridgePath(request.mount_id, args.linkPath));
+                break;
+            }
+            case "readlink":
+                result = await fs.readlink(path());
+                break;
+            case "lstat":
+                result = await fs.lstat(path());
+                break;
+            case "link":
+                await fs.link(bridgePath(request.mount_id, args.oldPath), bridgePath(request.mount_id, args.newPath));
+                break;
+            case "chmod":
+                await fs.chmod(path(), requireBridgeNumber(args.mode, "mode"));
+                break;
+            case "chown":
+                await fs.chown(path(), requireBridgeNumber(args.uid, "uid"), requireBridgeNumber(args.gid, "gid"), { followSymlinks: args.followSymlinks !== false });
+                break;
+            case "utimes":
+                await fs.utimes(path(), requireBridgeNumber(args.atimeMs, "atimeMs"), requireBridgeNumber(args.mtimeMs, "mtimeMs"));
+                break;
+            case "truncate":
+                await fs.truncate(path(), requireBridgeNumber(args.length, "length"));
+                break;
+            case "pread":
+                result = Buffer.from(await fs.pread(path(), requireBridgeNumber(args.offset, "offset"), requireBridgeNumber(args.length, "length"))).toString("base64");
+                break;
+            case "pwrite":
+                await fs.pwrite(path(), requireBridgeNumber(args.offset, "offset"), decodeBridgeBytes(args.content, "content"));
+                break;
+            default:
+                throw new Error(`Unsupported js_bridge operation: ${request.operation}`);
         }
+        return {
+            type: "js_bridge_result",
+            call_id: request.call_id,
+            ...(result === undefined ? {} : { result }),
+        };
+    }
+    catch (error) {
+        return {
+            type: "js_bridge_result",
+            call_id: request.call_id,
+            error: bridgeErrorMessage(error),
+        };
     }
-    return toolMap;
 }
 function parseHostCommandCallbackInput(input) {
     const value = asRecord(input);
@@ -1090,90 +1143,90 @@ function parseHostCommandCallbackInput(input) {
     };
 }
 async function handleHostCommandCallback(command, context) {
-    const directToolKit = context.toolKits.find((toolKit) => `agentos-${toolKit.name}` === command.command);
+    const directBindings = context.bindings.find((bindingCollection) => `agentos-${bindingCollection.name}` === command.command);
     if (command.command === "agentos") {
         return handleAgentOsRegistryCommand(command, context);
     }
-    if (directToolKit) {
-        return handleAgentOsToolkitCommand(command, context, directToolKit);
+    if (directBindings) {
+        return handleAgentOsBindingCommand(command, context, directBindings);
     }
     throw new Error(`Unknown host callback command "${command.command}"`);
 }
 async function handleAgentOsRegistryCommand(command, context) {
-    const [subcommand, toolkitName, toolName, ...toolArgs] = command.args;
+    const [subcommand, collectionName, bindingName, ...bindingArgs] = command.args;
     if (!subcommand || isHelpFlag(subcommand)) {
         return {
-            usage: "agentos <command>: list-tools [toolkit], <toolkit> --help, or <toolkit> <tool> ...",
+            usage: "agentos <command>: list-bindings [collection], <collection> --help, or <collection> <binding> ...",
         };
     }
-    if (subcommand === "list-tools") {
-        return toolkitName
-            ? describeToolkitPayload(context.toolKits, toolkitName)
-            : listToolkitsPayload(context.toolKits);
+    if (subcommand === "list-bindings") {
+        return collectionName
+            ? describeBindingsPayload(context.bindings, collectionName)
+            : listBindingsPayload(context.bindings);
     }
-    const toolKit = context.toolKits.find((kit) => kit.name === subcommand);
-    if (!toolKit) {
-        throw new Error(`No toolkit "${subcommand}". Available: ${toolkitNames(context.toolKits)}`);
+    const bindingCollection = context.bindings.find((collection) => collection.name === subcommand);
+    if (!bindingCollection) {
+        throw new Error(`No binding collection "${subcommand}". Available: ${bindingsNames(context.bindings)}`);
     }
-    if (!toolkitName || isHelpFlag(toolkitName)) {
-        return describeToolkitPayload(context.toolKits, subcommand);
+    if (!collectionName || isHelpFlag(collectionName)) {
+        return describeBindingsPayload(context.bindings, subcommand);
     }
-    if (toolName && isHelpFlag(toolName)) {
-        return describeToolPayload(toolKit, toolkitName);
+    if (bindingName && isHelpFlag(bindingName)) {
+        return describeBindingPayload(bindingCollection, collectionName);
     }
-    return invokeHostTool({
-        toolKit,
-        toolName: toolkitName,
-        args: [toolName, ...toolArgs].filter((value) => typeof value === "string"),
+    return invokeBinding({
+        bindingCollection,
+        bindingName: collectionName,
+        args: [bindingName, ...bindingArgs].filter((value) => typeof value === "string"),
         cwd: command.cwd,
         context,
     });
 }
-async function handleAgentOsToolkitCommand(command, context, toolKit) {
-    const [toolName, helpOrFirstArg, ...rest] = command.args;
-    if (!toolName || isHelpFlag(toolName)) {
-        return describeToolkitPayload(context.toolKits, toolKit.name);
+async function handleAgentOsBindingCommand(command, context, bindingCollection) {
+    const [bindingName, helpOrFirstArg, ...rest] = command.args;
+    if (!bindingName || isHelpFlag(bindingName)) {
+        return describeBindingsPayload(context.bindings, bindingCollection.name);
     }
     if (helpOrFirstArg && isHelpFlag(helpOrFirstArg)) {
-        return describeToolPayload(toolKit, toolName);
+        return describeBindingPayload(bindingCollection, bindingName);
     }
-    return invokeHostTool({
-        toolKit,
-        toolName,
+    return invokeBinding({
+        bindingCollection,
+        bindingName,
         args: [helpOrFirstArg, ...rest].filter((value) => typeof value === "string"),
         cwd: command.cwd,
         context,
     });
 }
-async function invokeHostTool({ toolKit, toolName, args, cwd, context, }) {
-    const tool = toolKit.tools[toolName];
-    if (!tool) {
-        throw new Error(`No tool "${toolName}" in toolkit "${toolKit.name}". Available: ${toolNames(toolKit)}`);
+async function invokeBinding({ bindingCollection, bindingName, args, cwd, context, }) {
+    const definition = bindingCollection.bindings[bindingName];
+    if (!definition) {
+        throw new Error(`No binding "${bindingName}" in collection "${bindingCollection.name}". Available: ${bindingNames(bindingCollection)}`);
     }
-    const callbackKey = `${toolKit.name}:${toolName}`;
-    const permissionMode = toolPermissionMode(context.permissions, callbackKey);
+    const callbackKey = `${bindingCollection.name}:${bindingName}`;
+    const permissionMode = bindingPermissionMode(context.permissions, callbackKey);
     if (permissionMode !== "allow") {
-        throw new Error(`EACCES: blocked by tool.invoke policy for ${callbackKey}`);
+        throw new Error(`EACCES: blocked by binding.invoke policy for ${callbackKey}`);
     }
-    const input = await parseHostToolInput(tool, args, cwd, context.readFile);
-    return executeHostTool(tool, callbackKey, input);
+    const input = await parseBindingInput(definition, args, cwd, context.readFile);
+    return executeBinding(definition, callbackKey, input);
 }
-async function executeHostTool(tool, callbackKey, input) {
-    const parsed = tool.inputSchema.safeParse(input);
+async function executeBinding(definition, callbackKey, input) {
+    const parsed = definition.inputSchema.safeParse(input);
     if (!parsed.success) {
         throw new Error(validationMessage(parsed.error));
     }
     return Promise.race([
-        Promise.resolve(tool.execute(parsed.data)),
+        Promise.resolve(definition.execute(parsed.data)),
         new Promise((_, reject) => {
-            if (tool.timeout === undefined) {
+            if (definition.timeout === undefined) {
                 return;
             }
-            setTimeout(() => reject(new Error(`Tool "${callbackKey}" timed out after ${tool.timeout}ms`)), tool.timeout);
+            setTimeout(() => reject(new Error(`Binding "${callbackKey}" timed out after ${definition.timeout}ms`)), definition.timeout);
         }),
     ]);
 }
-async function parseHostToolInput(tool, args, cwd, readFile) {
+async function parseBindingInput(definition, args, cwd, readFile) {
     if (args[0] === "--json") {
         const value = args[1];
         if (value === undefined) {
@@ -1192,9 +1245,9 @@ async function parseHostToolInput(tool, args, cwd, readFile) {
         const text = new TextDecoder().decode(await readFile(guestPath));
         return JSON.parse(text);
     }
-    return parseToolArgv(toolToSidecarDefinition(tool).inputSchema, args);
+    return parseBindingArgv(bindingToSidecarDefinition(definition).inputSchema, args);
 }
-function parseToolArgv(schema, argv) {
+function parseBindingArgv(schema, argv) {
     const schemaObject = asRecord(schema);
     const properties = asRecord(schemaObject.properties);
     const required = Array.isArray(schemaObject.required)
@@ -1266,50 +1319,50 @@ function parseToolArgv(schema, argv) {
     }
     return input;
 }
-function listToolkitsPayload(toolKits) {
+function listBindingsPayload(bindings) {
     return {
-        toolkits: toolKits.map((toolKit) => ({
-            name: toolKit.name,
-            description: toolKit.description,
-            tools: Object.keys(toolKit.tools),
+        bindings: bindings.map((bindingCollection) => ({
+            name: bindingCollection.name,
+            description: bindingCollection.description,
+            bindings: Object.keys(bindingCollection.bindings),
         })),
     };
 }
-function describeToolkitPayload(toolKits, toolkitName) {
-    const toolKit = toolKits.find((kit) => kit.name === toolkitName);
-    if (!toolKit) {
-        throw new Error(`No toolkit "${toolkitName}". Available: ${toolkitNames(toolKits)}`);
+function describeBindingsPayload(bindings, collectionName) {
+    const bindingCollection = bindings.find((collection) => collection.name === collectionName);
+    if (!bindingCollection) {
+        throw new Error(`No binding collection "${collectionName}". Available: ${bindingsNames(bindings)}`);
     }
     return {
-        name: toolKit.name,
-        description: toolKit.description,
-        tools: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
-            toolName,
+        name: bindingCollection.name,
+        description: bindingCollection.description,
+        bindings: Object.fromEntries(Object.entries(bindingCollection.bindings).map(([bindingName, definition]) => [
+            bindingName,
             {
-                description: tool.description,
-                flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
+                description: definition.description,
+                flags: describeBindingFlags(bindingToSidecarDefinition(definition).inputSchema),
             },
         ])),
     };
 }
-function describeToolPayload(toolKit, toolName) {
-    const tool = toolKit.tools[toolName];
-    if (!tool) {
-        throw new Error(`No tool "${toolName}" in toolkit "${toolKit.name}". Available: ${toolNames(toolKit)}`);
+function describeBindingPayload(bindingCollection, bindingName) {
+    const definition = bindingCollection.bindings[bindingName];
+    if (!definition) {
+        throw new Error(`No binding "${bindingName}" in collection "${bindingCollection.name}". Available: ${bindingNames(bindingCollection)}`);
     }
     return {
-        toolkit: toolKit.name,
-        tool: toolName,
-        description: tool.description,
-        flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
-        examples: tool.examples?.map((example) => ({
+        collection: bindingCollection.name,
+        binding: bindingName,
+        description: definition.description,
+        flags: describeBindingFlags(bindingToSidecarDefinition(definition).inputSchema),
+        examples: definition.examples?.map((example) => ({
             description: example.description,
             input: example.input,
         })) ?? [],
     };
 }
-function toolPermissionMode(permissions, callbackKey) {
-    const scope = permissions.tool;
+function bindingPermissionMode(permissions, callbackKey) {
+    const scope = permissions.binding;
     if (!scope) {
         return "deny";
     }
@@ -1343,11 +1396,11 @@ function permissionPatternMatches(pattern, value) {
         .join("");
     return new RegExp(`^${source}$`).test(value);
 }
-function toolkitNames(toolKits) {
-    return toolKits.map((toolKit) => toolKit.name).join(", ");
+function bindingsNames(bindings) {
+    return bindings.map((bindingCollection) => bindingCollection.name).join(", ");
 }
-function toolNames(toolKit) {
-    return Object.keys(toolKit.tools).join(", ");
+function bindingNames(bindingCollection) {
+    return Object.keys(bindingCollection.bindings).join(", ");
 }
 function isHelpFlag(value) {
     return value === "--help" || value === "-h";
@@ -1356,43 +1409,42 @@ function jsonSchemaType(schema) {
     const schemaObject = asRecord(schema);
     return typeof schemaObject.type === "string" ? schemaObject.type : undefined;
 }
-async function registerToolkitsOnSidecar(client, session, vm, toolKits) {
-    if (toolKits.length === 0) {
+async function registerBindingsOnSidecar(client, session, vm, bindings) {
+    if (bindings.length === 0) {
         return "";
     }
-    for (const toolKit of toolKits) {
+    for (const bindingCollection of bindings) {
         await client.registerHostCallbacks(session, vm, {
-            name: toolKit.name,
-            description: toolKit.description,
-            commandAliases: [`agentos-${toolKit.name}`],
+            name: bindingCollection.name,
+            description: bindingCollection.description,
+            commandAliases: [`agentos-${bindingCollection.name}`],
             registryCommandAliases: ["agentos"],
-            callbacks: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
-                toolName,
-                toolToSidecarDefinition(tool),
+            callbacks: Object.fromEntries(Object.entries(bindingCollection.bindings).map(([bindingName, definition]) => [
+                bindingName,
+                bindingToSidecarDefinition(definition),
             ])),
         });
     }
-    return buildHostToolReference(toolKits);
+    return buildBindingReference(bindings);
 }
 export class AgentOs {
     #kernel;
     sidecar;
-    _sessions = new Map();
-    _closedSessionIds = new BoundedSet(CLOSED_SESSION_ID_RETENTION_LIMIT);
-    _sessionClosePromises = new Map();
-    _pendingSessionRequestResolvers = new Map();
+    _durableSessionEventHandlers = new Map();
+    _agentExitHandlers = new Map();
     _processes = new Map();
     _shells = new Map();
+    // Value is the recorded exit code (undefined until/unless the exit
+    // resolves) so waitShell can still report it after the entry is dropped.
     _closedShellIds = new BoundedSet(CLOSED_SHELL_ID_RETENTION_LIMIT);
     _pendingShellExitPromises = new Set();
     _shellCounter = 0;
     _acpTerminals = new Map();
     _acpTerminalCounter = 0;
     _softwareRoots;
-    _softwareAgentConfigs;
     _cronManager;
-    _toolKits = [];
-    _toolReference = "";
+    _bindings = [];
+    _bindingReference = "";
     _permissions = allowAll;
     _hostMounts;
     _env;
@@ -1402,17 +1454,22 @@ export class AgentOs {
     _sidecarSession;
     _sidecarVm;
     _disposeSidecarEventListener;
-    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm) {
+    _agentStderrHandler;
+    _agentExitHandler;
+    _limitWarningHandler;
+    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, agentStderrHandler, agentExitHandler, limitWarningHandler) {
         this.#kernel = kernel;
         this.sidecar = sidecar;
         this._softwareRoots = softwareRoots;
-        this._softwareAgentConfigs = softwareAgentConfigs;
         this._hostMounts = hostMounts;
         this._env = env;
         this._rootFilesystem = rootFilesystem;
         this._sidecarClient = sidecarClient;
         this._sidecarSession = sidecarSession;
         this._sidecarVm = sidecarVm;
+        this._agentStderrHandler = agentStderrHandler;
+        this._agentExitHandler = agentExitHandler;
+        this._limitWarningHandler = limitWarningHandler;
         this._disposeSidecarEventListener = this._sidecarClient.onEvent((event) => {
             this._handleSidecarEvent(event);
         });
@@ -1430,92 +1487,130 @@ export class AgentOs {
         return getSharedAgentOsSidecarInternal(options);
     }
     static async create(options) {
-        const processed = processSoftware(options?.software ?? []);
+        options = parseAgentOsOptions(options);
+        // Default software is FULLY DYNAMIC: this package's own NON-agent
+        // @agentos-software/* dependencies (e.g. common), each default-exporting
+        // its registry-built descriptor. Agent packages are NOT projected here —
+        // openSession({ agent: id }) links the matching agent dependency into the running
+        // VM on first use, so agent closures (and pi's V8 snapshot bundle) only
+        // enter VMs that run them. Unbuilt packages throw with build
+        // instructions; opt out via defaultSoftware: false.
+        const defaultSoftware = options?.defaultSoftware === false ? [] : resolveDefaultSoftware();
+        const software = options?.defaultSoftware === false
+            ? (options.software ?? [])
+            : [...defaultSoftware, ...(options?.software ?? [])];
+        // Packages are projected by the SIDECAR: the client forwards only the
+        // package `path` over `configureVm` and the sidecar reads metadata from
+        // the packed vbare manifest (chunk1 of the `.aospkg`).
+        const flatSoftware = software.flat();
+        // Honor the AgentOsOptions.defaultSoftware contract ("entries already present
+        // in `software` are not duplicated"): the default bundle and an explicitly
+        // passed one resolve to the same package paths, so dedup by path. Without
+        // this the sidecar rejects the second projection with a duplicate-command
+        // error (e.g. coreutils' `[`).
+        const seenPackagePaths = new Set();
+        const sidecarPackages = flatSoftware.flatMap((entry) => {
+            const ref = normalizePackageRef(entry);
+            if (!ref || seenPackagePaths.has(ref.path)) {
+                return [];
+            }
+            seenPackagePaths.add(ref.path);
+            return [{ path: ref.path }];
+        });
+        // All package software is projected into `/opt/agentos` by the sidecar. The
+        // client stages nothing host-side and parses NO package manifests: the
+        // sidecar owns agent resolution, agent enumeration, and agent snapshot
+        // bundle loading from the projected package dirs.
         const localMounts = await resolveCompatLocalMounts(options?.mounts);
-        const toolKits = options?.toolKits;
-        if (toolKits && toolKits.length > 0) {
-            validateToolkits(toolKits);
+        const bindings = options?.bindings;
+        if (bindings && bindings.length > 0) {
+            validateBindings(bindings);
         }
+        // Resolve the sidecar handle up front so every VM created here leases the
+        // one shared native sidecar process owned by that handle.
+        const sidecar = resolveAgentOsSidecar(options?.sidecar);
         const createVmAdmin = async () => {
-            const preparedCommandDirs = prepareCommandDirs(processed.commandPackages);
-            const toolBootstrapCommands = collectToolkitBootstrapCommands(toolKits ?? []);
-            const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem, [
-                ...collectBootstrapWasmCommands(preparedCommandDirs.commandDirs),
-                ...NODE_RUNTIME_BOOTSTRAP_COMMANDS,
-                ...toolBootstrapCommands,
-            ]);
-            let toolReference = "";
+            // The `/opt/agentos` projection is built by the sidecar from the
+            // forwarded `packages` (it owns the staging dir + read-only mount, and
+            // runtime `linkSoftware` appends to that live dir). The client no longer
+            // stages packages host-side.
+            const bindingBootstrapCommands = collectBindingBootstrapCommands(bindings ?? []);
+            const bootstrapCommands = [
+                ...RUNTIME_BOOTSTRAP_COMMANDS,
+                ...bindingBootstrapCommands,
+            ];
+            const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem);
+            let bindingReference = "";
             let rootBridge = null;
             let kernel = null;
             let client = null;
-            let toolShimDir = null;
+            let createdNativeVm = null;
+            let nativeSession = null;
             let cleanedUp = false;
             const cleanup = async () => {
                 if (cleanedUp) {
                     return;
                 }
                 cleanedUp = true;
-                if (toolShimDir) {
-                    rmSync(toolShimDir, { recursive: true, force: true });
-                    toolShimDir = null;
-                }
-                preparedCommandDirs.dispose();
             };
             try {
                 const env = getBaseEnvironment();
-                if (toolKits && toolKits.length > 0) {
-                    toolShimDir = materializeToolShimDir(toolKits);
-                }
-                const commandGuestPaths = collectGuestCommandPaths(preparedCommandDirs.commandDirs);
-                const requestedMounts = options?.moduleAccessCwd
-                    ? [
-                        ...(options.mounts ?? []),
-                        {
-                            path: "/root/node_modules",
-                            plugin: createHostDirBackend({
-                                hostPath: join(options.moduleAccessCwd, "node_modules"),
-                                readOnly: true,
-                            }),
-                            readOnly: true,
-                        },
-                    ]
-                    : options?.mounts;
+                // Guest command paths. The sidecar owns the `/opt/agentos` projection and
+                // reports the exact projected package commands after `configureVm`.
+                // Binding-shim commands are added below.
+                const commandGuestPaths = new Map();
                 const { sidecarMounts, hostMounts, hostPathMappings } = collectSidecarMountPlan({
-                    mounts: requestedMounts,
-                    softwareRoots: processed.softwareRoots,
-                    commandDirs: preparedCommandDirs.commandDirs,
-                    shimDir: toolShimDir,
-                });
-                client = SidecarProcess.spawn({
-                    cwd: REPO_ROOT,
-                    command: ensureNativeSidecarBinary(),
-                    args: [],
-                    frameTimeoutMs: NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
+                    mounts: options?.mounts,
                 });
-                const session = await client.authenticateAndOpenSession();
+                // Reuse the sidecar handle's single shared native process; this VM
+                // becomes another tenant of it rather than spawning its own process.
+                const shared = await ensureSharedSidecarNativeProcess(sidecar);
+                client = shared.client;
+                const session = shared.session;
+                nativeSession = session;
                 const hostPermissions = options?.permissions ?? {
                     ...allowAll,
-                    tool: "allow",
+                    binding: "allow",
                 };
                 const sidecarPermissions = serializePermissionsForSidecar(hostPermissions);
                 const createVmConfig = {
                     env,
+                    database: options?.database,
+                    ...(options?.user ? { user: options.user } : {}),
                     rootFilesystem: serializeRootFilesystemForSidecar(options?.rootFilesystem, bootstrapLower),
                     permissions: sidecarPermissions,
                     limits: options?.limits,
                     loopbackExemptPorts: options?.loopbackExemptPorts ?? [],
+                    bootstrapCommands,
+                    ...(options?.rootFilesystem?.type === "native"
+                        ? {
+                            nativeRoot: {
+                                plugin: {
+                                    id: options.rootFilesystem.plugin.id,
+                                    config: options.rootFilesystem.plugin.config ?? {},
+                                },
+                                readOnly: options.rootFilesystem.readOnly ?? false,
+                            },
+                        }
+                        : {}),
                     // 0.3: the Node builtin allow-list moved from configureVm to
                     // VM creation. `undefined` => engine default allow-list;
                     // `[]` => deny all; `[..]` => exactly those. Platform and
                     // module resolution keep their engine defaults (full Node
                     // emulation), matching the prior behavior where Agent OS only
                     // constrained the builtin allow-list.
-                    ...(options?.allowedNodeBuiltins !== undefined
+                    ...(options?.allowedNodeBuiltins !== undefined ||
+                        options?.highResolutionTime !== undefined
                         ? {
                             jsRuntime: {
                                 platform: "node",
                                 moduleResolution: "node",
-                                allowedBuiltins: options.allowedNodeBuiltins,
+                                ...(options?.allowedNodeBuiltins !== undefined
+                                    ? { allowedBuiltins: options.allowedNodeBuiltins }
+                                    : {}),
+                                ...(options?.highResolutionTime !== undefined
+                                    ? { highResolutionTime: options.highResolutionTime }
+                                    : {}),
                             },
                         }
                         : {}),
@@ -1524,19 +1619,30 @@ export class AgentOs {
                     runtime: "java_script",
                     config: createVmConfig,
                 });
+                createdNativeVm = nativeVm;
+                // Scope the readiness wait to THIS VM's ownership; on a shared process
+                // other VMs are emitting their own lifecycle events concurrently.
                 await client.waitForEvent((event) => event.payload.type === "vm_lifecycle" &&
-                    event.payload.state === "ready", 10_000);
-                await client.configureVm(session, nativeVm, {
+                    event.payload.state === "ready" &&
+                    event.ownership.scope === "vm" &&
+                    event.ownership.vm_id === nativeVm.vmId, 10_000);
+                const configuredVm = await client.configureVm(session, nativeVm, {
                     mounts: sidecarMounts,
                     permissions: sidecarPermissions,
-                    commandPermissions: processed.commandPermissions,
+                    commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
+                    packages: sidecarPackages,
+                    packagesMountAt: OPT_AGENTOS_ROOT,
+                    bindingShimCommands: bindingBootstrapCommands,
                 });
-                if (toolKits && toolKits.length > 0) {
-                    toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, toolKits);
+                for (const command of configuredVm.projectedCommands) {
+                    commandGuestPaths.set(command.name, command.guestPath);
+                }
+                if (bindings && bindings.length > 0) {
+                    bindingReference = await registerBindingsOnSidecar(client, session, nativeVm, bindings);
                     commandGuestPaths.set("agentos", "/bin/agentos");
-                    for (const toolKit of toolKits) {
-                        commandGuestPaths.set(`agentos-${toolKit.name}`, `/bin/agentos-${toolKit.name}`);
+                    for (const bindingCollection of bindings) {
+                        commandGuestPaths.set(`agentos-${bindingCollection.name}`, `/bin/agentos-${bindingCollection.name}`);
                     }
                 }
                 rootBridge = new NativeSidecarKernelProxy({
@@ -1544,12 +1650,27 @@ export class AgentOs {
                     session,
                     vm: nativeVm,
                     env,
-                    cwd: "/home/user",
+                    cwd: "/workspace",
                     localMounts,
+                    sidecarMounts,
+                    permissions: sidecarPermissions,
+                    commandPermissions: {},
+                    loopbackExemptPorts: options?.loopbackExemptPorts,
+                    // Retained for runtime mount reconfigures: `configure_vm` is
+                    // replace-on-write for the whole payload, so post-boot mountFs
+                    // must resend the boot packages and binding shims.
+                    packages: sidecarPackages,
+                    packagesMountAt: OPT_AGENTOS_ROOT,
+                    bindingShimCommands: bindingBootstrapCommands,
                     commandGuestPaths,
                     onDispose: cleanup,
+                    // The native process is owned by the AgentOsSidecar handle and
+                    // shared across VMs; disposing this VM must not kill the process.
+                    ownsClient: false,
                 });
-                await bootstrapLiveBootstrapDirectories(client, session, nativeVm, options?.rootFilesystem);
+                if (options?.rootFilesystem?.type !== "native") {
+                    await bootstrapLiveBootstrapDirectories(client, session, nativeVm, options?.rootFilesystem);
+                }
                 kernel = rootBridge;
                 const snapshotClient = client;
                 return {
@@ -1557,13 +1678,17 @@ export class AgentOs {
                     hostMounts,
                     kernel,
                     rootView: rootBridge.createRootView(),
+                    sidecarMounts,
+                    sidecarPermissions,
+                    commandPermissions: {},
+                    loopbackExemptPorts: options?.loopbackExemptPorts,
                     sidecarClient: client,
                     sidecarSession: session,
                     sidecarVm: nativeVm,
                     permissions: hostPermissions,
-                    snapshotRootFilesystem: async () => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm))),
-                    toolKits: toolKits ?? [],
-                    toolReference,
+                    snapshotRootFilesystem: async (maxBytes) => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm, maxBytes))),
+                    bindings: bindings ?? [],
+                    bindingReference,
                     async dispose() {
                         if (kernel) {
                             const currentKernel = kernel;
@@ -1581,6 +1706,8 @@ export class AgentOs {
                 };
             }
             catch (error) {
+                // The native process is shared and owned by the sidecar handle, so
+                // never dispose the client here — only tear down this VM's resources.
                 if (kernel) {
                     await kernel.dispose().catch(() => { });
                 }
@@ -1588,23 +1715,26 @@ export class AgentOs {
                     await rootBridge.dispose().catch(() => { });
                 }
                 else {
-                    await client?.dispose().catch(() => { });
+                    if (createdNativeVm && nativeSession && client) {
+                        await client
+                            .disposeVm(nativeSession, createdNativeVm)
+                            .catch(() => { });
+                    }
                     await cleanup();
                 }
                 throw error;
             }
         };
-        const sidecar = resolveAgentOsSidecar(options?.sidecar);
         let sidecarLease = null;
         try {
             sidecarLease = await leaseAgentOsSidecarVm(sidecar, {
                 createVm: async () => createVmAdmin(),
             });
             const vmAdmin = sidecarLease.admin;
-            const vm = new AgentOs(vmAdmin.kernel, sidecar, processed.softwareRoots, processed.agentConfigs, vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm);
+            const vm = new AgentOs(vmAdmin.kernel, sidecar, [], vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.onAgentStderr ?? defaultAgentStderrHandler, options?.onAgentExit ?? defaultAgentExitHandler, options?.onLimitWarning);
             vm._sidecarLease = sidecarLease;
-            vm._toolKits = vmAdmin.toolKits;
-            vm._toolReference = vmAdmin.toolReference;
+            vm._bindings = vmAdmin.bindings;
+            vm._bindingReference = vmAdmin.bindingReference;
             vm._permissions = vmAdmin.permissions;
             vm._installSidecarRequestHandler();
             vm._cronManager = new CronManager(vm, options?.scheduleDriver ?? new TimerScheduleDriver());
@@ -1622,76 +1752,66 @@ export class AgentOs {
         const kernel = this.#kernel;
         return kernel.execArgv(command, args, options);
     }
-    _trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers) {
+    _trackProcess(proc, command, args, outputHandlers, exitHandlers) {
         const entry = {
             proc,
             command,
             args,
-            stdoutHandlers,
-            stderrHandlers,
+            outputHandlers,
             exitHandlers,
         };
         this._processes.set(proc.pid, entry);
+        // NOTE: do NOT delete from `_processes` on exit — the public API contract
+        // (getProcess/listProcesses/stopProcess, see process-management.test.ts)
+        // requires exited processes to stay queryable (running:false, exitCode set).
+        // `_processes` is a process table for this VM's lifetime; it is freed wholesale
+        // in dispose(). (H5: the leak was that dispose() never cleared it.)
         void proc.wait().then((code) => {
             for (const h of exitHandlers)
-                h(code);
+                h({ pid: proc.pid, exitCode: code });
         });
         return { pid: proc.pid };
     }
     spawn(command, args, options) {
-        const stdoutHandlers = new Set();
-        const stderrHandlers = new Set();
+        const outputHandlers = new Set();
         const exitHandlers = new Set();
-        // Include caller-provided callbacks in the initial handler sets.
-        if (options?.onStdout)
-            stdoutHandlers.add(options.onStdout);
-        if (options?.onStderr)
-            stderrHandlers.add(options.onStderr);
         const proc = this.#kernel.spawn(command, args, {
             ...options,
             onStdout: (data) => {
-                for (const h of stdoutHandlers)
-                    h(data);
+                for (const h of outputHandlers) {
+                    h({ pid: proc.pid, stream: "stdout", data });
+                }
             },
             onStderr: (data) => {
-                for (const h of stderrHandlers)
-                    h(data);
+                for (const h of outputHandlers) {
+                    h({ pid: proc.pid, stream: "stderr", data });
+                }
             },
         });
-        return this._trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers);
+        return this._trackProcess(proc, command, args, outputHandlers, exitHandlers);
     }
     /** Write data to a process's stdin. */
     writeProcessStdin(pid, data) {
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        entry.proc.writeStdin(data);
+        return entry.proc.writeStdin(data);
     }
     /** Close a process's stdin stream. */
     closeProcessStdin(pid) {
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        entry.proc.closeStdin();
-    }
-    /** Subscribe to stdout data from a process. Returns an unsubscribe function. */
-    onProcessStdout(pid, handler) {
-        const entry = this._processes.get(pid);
-        if (!entry)
-            throw new Error(`Process not found: ${pid}`);
-        entry.stdoutHandlers.add(handler);
-        return () => {
-            entry.stdoutHandlers.delete(handler);
-        };
+        return entry.proc.closeStdin();
     }
-    /** Subscribe to stderr data from a process. Returns an unsubscribe function. */
-    onProcessStderr(pid, handler) {
+    /** Subscribe to stdout and stderr from a process. */
+    onProcessOutput(pid, handler) {
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        entry.stderrHandlers.add(handler);
+        entry.outputHandlers.add(handler);
         return () => {
-            entry.stderrHandlers.delete(handler);
+            entry.outputHandlers.delete(handler);
         };
     }
     /** Subscribe to process exit. Returns an unsubscribe function. */
@@ -1701,7 +1821,7 @@ export class AgentOs {
             throw new Error(`Process not found: ${pid}`);
         // If already exited, call immediately.
         if (entry.proc.exitCode !== null) {
-            handler(entry.proc.exitCode);
+            handler({ pid, exitCode: entry.proc.exitCode });
             return () => { };
         }
         entry.exitHandlers.add(handler);
@@ -1733,35 +1853,6 @@ export class AgentOs {
     _vfs() {
         return this.#kernel.vfs;
     }
-    async _copyPath(from, to) {
-        const stat = await this._vfs().lstat(from);
-        if (stat.isSymbolicLink) {
-            const target = await this._vfs().readlink(from);
-            await this._vfs().symlink(target, to);
-            return;
-        }
-        if (stat.isDirectory) {
-            await this._mkdirp(posixPath.dirname(to));
-            if (!(await this.#kernel.exists(to))) {
-                await this.#kernel.mkdir(to);
-            }
-            await this._vfs().chmod(to, stat.mode);
-            await this._vfs().chown(to, stat.uid, stat.gid);
-            const entries = await this.#kernel.readdir(from);
-            for (const entry of entries) {
-                if (entry === "." || entry === "..")
-                    continue;
-                const fromPath = from === "/" ? `/${entry}` : `${from}/${entry}`;
-                const toPath = to === "/" ? `/${entry}` : `${to}/${entry}`;
-                await this._copyPath(fromPath, toPath);
-            }
-            return;
-        }
-        const content = await this.#kernel.readFile(from);
-        await this.writeFile(to, content);
-        await this._vfs().chmod(to, stat.mode);
-        await this._vfs().chown(to, stat.uid, stat.gid);
-    }
     async readFile(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readFile(path);
@@ -1814,14 +1905,13 @@ export class AgentOs {
     /** Recursively create directories (mkdir -p). */
     async _mkdirp(path) {
         this._assertWritableAbsolutePath(path);
-        const parts = path.split("/").filter(Boolean);
-        let current = "";
-        for (const part of parts) {
-            current += `/${part}`;
-            if (!(await this.#kernel.exists(current))) {
-                await this.#kernel.mkdir(current);
-            }
-        }
+        // `kernel.mkdir` is already recursive (it defaults to recursive=true on both
+        // the native sidecar and compat kernels) and creating an existing directory is
+        // a no-op, so a single call is sufficient. Do NOT probe each ancestor with
+        // `exists()` first: on the native sidecar every read-side op
+        // (exists/stat/readFile) triggers a full shadow-tree walk, so a per-component
+        // exists() loop makes `mkdir -p` cost O(components * tree).
+        await this.#kernel.mkdir(path);
     }
     async mkdir(path, options) {
         if (options?.recursive) {
@@ -1834,51 +1924,42 @@ export class AgentOs {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readdir(path);
     }
+    async readdirEntries(path) {
+        this._assertSafeAbsolutePath(path);
+        const entries = await this.#kernel.readdirRecursive(path, { maxDepth: 0 });
+        return entries.map((entry) => ({
+            name: entry.name,
+            isDirectory: entry.isDirectory,
+            isSymbolicLink: entry.isSymbolicLink,
+        }));
+    }
     async readdirRecursive(path, options) {
         this._assertSafeAbsolutePath(path);
-        const maxDepth = options?.maxDepth;
         const exclude = options?.exclude ? new Set(options.exclude) : undefined;
+        const entries = await this.#kernel.readdirRecursive(path, {
+            maxDepth: options?.maxDepth,
+        });
+        const excludedPrefixes = [];
         const results = [];
-        // BFS queue: [dirPath, currentDepth]
-        const queue = [[path, 0]];
-        while (queue.length > 0) {
-            const item = queue.shift();
-            if (!item)
-                break;
-            const [dirPath, depth] = item;
-            const entries = await this.#kernel.readdir(dirPath);
-            for (const name of entries) {
-                if (name === "." || name === "..")
-                    continue;
-                if (exclude?.has(name))
-                    continue;
-                const fullPath = dirPath === "/" ? `/${name}` : `${dirPath}/${name}`;
-                const s = await this.#kernel.stat(fullPath);
-                if (s.isSymbolicLink) {
-                    results.push({
-                        path: fullPath,
-                        type: "symlink",
-                        size: s.size,
-                    });
-                }
-                else if (s.isDirectory) {
-                    results.push({
-                        path: fullPath,
-                        type: "directory",
-                        size: s.size,
-                    });
-                    if (maxDepth === undefined || depth < maxDepth) {
-                        queue.push([fullPath, depth + 1]);
-                    }
-                }
-                else {
-                    results.push({
-                        path: fullPath,
-                        type: "file",
-                        size: s.size,
-                    });
+        for (const entry of entries) {
+            if (excludedPrefixes.some((prefix) => entry.path === prefix || entry.path.startsWith(`${prefix}/`))) {
+                continue;
+            }
+            if (exclude?.has(entry.name)) {
+                if (entry.isDirectory && !entry.isSymbolicLink) {
+                    excludedPrefixes.push(entry.path);
                 }
+                continue;
             }
+            results.push({
+                path: entry.path,
+                type: entry.isSymbolicLink
+                    ? "symlink"
+                    : entry.isDirectory
+                        ? "directory"
+                        : "file",
+                size: entry.size,
+            });
         }
         return results;
     }
@@ -1890,89 +1971,133 @@ export class AgentOs {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.exists(path);
     }
-    async snapshotRootFilesystem() {
+    async exportRootFilesystem(options) {
+        if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0) {
+            throw new RangeError("maxBytes must be a positive safe integer");
+        }
         const nativeSnapshot = this._sidecarLease?.admin.snapshotRootFilesystem;
-        if (nativeSnapshot) {
-            return nativeSnapshot();
+        const snapshot = nativeSnapshot
+            ? await nativeSnapshot(options.maxBytes)
+            : createSnapshotExport(await snapshotVirtualFilesystem(this._rootFilesystem));
+        const size = Buffer.byteLength(JSON.stringify(snapshot));
+        if (size > options.maxBytes) {
+            throw new RangeError(`root filesystem export is ${size} bytes, limit is ${options.maxBytes}; raise maxBytes to export this filesystem`);
         }
-        return createSnapshotExport(await snapshotVirtualFilesystem(this._rootFilesystem));
+        return snapshot;
     }
-    mountFs(path, driver, options) {
-        this._assertSafeAbsolutePath(path);
-        this.#kernel.mountFs(path, driver, { readOnly: options?.readOnly });
+    /**
+     * Mount a filesystem into the running VM. Resolves once the mount has been
+     * delivered to the native sidecar, so guest code can use it immediately
+     * after the returned promise settles; a delivery failure rejects instead of
+     * leaving the mount silently host-only.
+     */
+    async mountFs(descriptor) {
+        this._assertSafeAbsolutePath(descriptor.path);
+        if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
+            throw new Error("portable dynamic mounts require the native sidecar");
+        }
+        await this.#kernel.mountDescriptor({
+            guestPath: descriptor.path,
+            readOnly: descriptor.readOnly ?? false,
+            plugin: {
+                id: descriptor.plugin.id,
+                config: descriptor.plugin.config ?? {},
+            },
+        });
     }
-    unmountFs(path) {
+    async unmountFs(path) {
         this._assertSafeAbsolutePath(path);
-        this.#kernel.unmountFs(path);
+        if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
+            throw new Error("portable dynamic mounts require the native sidecar");
+        }
+        await this.#kernel.unmountDescriptor(path);
+    }
+    async listMounts() {
+        if (!(this.#kernel instanceof NativeSidecarKernelProxy))
+            return [];
+        return this.#kernel.listMounts();
     }
     async move(from, to) {
-        this._assertSafeAbsolutePath(from);
-        this._assertSafeAbsolutePath(to);
-        const sourceStat = await this._vfs().lstat(from);
-        if (!sourceStat.isDirectory || sourceStat.isSymbolicLink) {
-            return this.#kernel.rename(from, to);
-        }
-        await this._copyPath(from, to);
-        await this.delete(from, { recursive: true });
+        this._assertWritableAbsolutePath(from);
+        this._assertWritableAbsolutePath(to);
+        await this.#kernel.movePath(from, to);
     }
-    async delete(path, options) {
-        this._assertSafeAbsolutePath(path);
-        const s = await this.#kernel.stat(path);
-        if (s.isDirectory) {
-            if (options?.recursive) {
-                const entries = await this.#kernel.readdir(path);
-                for (const entry of entries) {
-                    if (entry === "." || entry === "..")
-                        continue;
-                    await this.delete(`${path}/${entry}`, { recursive: true });
-                }
-            }
-            return this.#kernel.removeDir(path);
-        }
-        return this.#kernel.removeFile(path);
+    async remove(path, options) {
+        this._assertWritableAbsolutePath(path);
+        await this.#kernel.removePath(path, {
+            recursive: options?.recursive ?? false,
+        });
     }
-    async fetch(port, request) {
-        const url = new URL(request.url);
+    async httpRequest(request) {
+        this._assertSafeAbsolutePath(request.path.split("?")[0] || "/");
+        const method = request.method?.toUpperCase() ?? "GET";
+        const body = typeof request.body === "string"
+            ? request.body
+            : request.body === undefined
+                ? undefined
+                : new TextDecoder().decode(request.body);
         const responsePayload = JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
-            port,
-            method: request.method,
-            path: `${url.pathname}${url.search}`,
-            headersJson: JSON.stringify(Object.fromEntries(request.headers.entries())),
-            ...(request.method !== "GET" && request.method !== "HEAD"
-                ? { body: await request.text() }
+            port: request.port,
+            method,
+            path: request.path,
+            headersJson: JSON.stringify(request.headers ?? {}),
+            ...(method !== "GET" && method !== "HEAD" && body !== undefined
+                ? { body }
                 : {}),
         }));
-        const headers = new Headers();
+        const headers = {};
         for (const [key, value] of responsePayload.headers ?? []) {
-            headers.append(key, value);
+            headers[key] = value;
         }
-        return new Response(Buffer.from(responsePayload.body ?? "", "base64"), {
+        return {
             status: responsePayload.status,
-            statusText: responsePayload.statusText,
+            statusText: responsePayload.statusText ?? "",
             headers,
-        });
+            body: new Uint8Array(Buffer.from(responsePayload.body ?? "", "base64")),
+        };
     }
     openShell(options) {
         const shellId = `shell-${++this._shellCounter}`;
         this._closedShellIds.delete(shellId);
         const dataHandlers = new Set();
-        const handle = this.#kernel.openShell(options);
+        const stderrHandlers = new Set();
+        const exitHandlers = new Set();
+        const handle = this.#kernel.openShell({
+            ...options,
+            onStderr: (data) => {
+                for (const handler of stderrHandlers)
+                    handler({ shellId, data });
+            },
+        });
         handle.onData = (data) => {
-            for (const h of dataHandlers)
-                h(data);
+            for (const handler of dataHandlers)
+                handler({ shellId, data });
         };
         const entry = {
             handle,
             dataHandlers,
-            exitPromise: Promise.resolve(),
+            stderrHandlers,
+            exitHandlers,
+            exitPromise: Promise.resolve(0),
         };
-        const exitPromise = handle.wait().then(() => undefined, () => undefined);
-        entry.exitPromise = exitPromise.finally(() => {
+        const exitPromise = handle.wait();
+        const finalize = (exitCode) => {
             this._pendingShellExitPromises.delete(entry.exitPromise);
             if (this._shells.get(shellId) === entry) {
                 this._shells.delete(shellId);
-                this._closedShellIds.add(shellId);
             }
+            // Record the exit code even when closeShell already dropped the
+            // entry, so a waitShell issued after exit still resolves with it.
+            this._closedShellIds.add(shellId, exitCode);
+        };
+        entry.exitPromise = exitPromise.then((exitCode) => {
+            finalize(exitCode);
+            for (const handler of exitHandlers)
+                handler({ shellId, exitCode });
+            return exitCode;
+        }, (error) => {
+            finalize();
+            throw error;
         });
         this._pendingShellExitPromises.add(entry.exitPromise);
         this._shells.set(shellId, entry);
@@ -1986,9 +2111,13 @@ export class AgentOs {
         const entry = this._shells.get(shellId);
         if (!entry)
             throw new Error(`Shell not found: ${shellId}`);
-        entry.handle.write(data);
+        return entry.handle.write(data);
     }
-    /** Subscribe to data output from a shell. Returns an unsubscribe function. */
+    /**
+     * Subscribe to ordered PTY output (stdout and stderr). Returns an unsubscribe
+     * function. `OpenShellOptions.onStderr` is a diagnostic tap for callers that
+     * need channel identity; do not render both surfaces.
+     */
     onShellData(shellId, handler) {
         const entry = this._shells.get(shellId);
         if (!entry)
@@ -1998,6 +2127,28 @@ export class AgentOs {
             entry.dataHandlers.delete(handler);
         };
     }
+    /** Subscribe to the stderr-only diagnostic stream for a shell. */
+    onShellStderr(shellId, handler) {
+        const entry = this._shells.get(shellId);
+        if (!entry)
+            throw new Error(`Shell not found: ${shellId}`);
+        entry.stderrHandlers.add(handler);
+        return () => entry.stderrHandlers.delete(handler);
+    }
+    /** Subscribe to shell exit. */
+    onShellExit(shellId, handler) {
+        const entry = this._shells.get(shellId);
+        if (!entry) {
+            const exitCode = this._closedShellIds.get(shellId);
+            if (exitCode !== undefined) {
+                handler({ shellId, exitCode });
+                return () => { };
+            }
+            throw new Error(`Shell not found: ${shellId}`);
+        }
+        entry.exitHandlers.add(handler);
+        return () => entry.exitHandlers.delete(handler);
+    }
     /** Notify a shell of terminal resize. */
     resizeShell(shellId, cols, rows) {
         const entry = this._shells.get(shellId);
@@ -2005,6 +2156,21 @@ export class AgentOs {
             throw new Error(`Shell not found: ${shellId}`);
         entry.handle.resize(cols, rows);
     }
+    /**
+     * Wait for a shell to exit and return its process exit code. Resolves
+     * immediately for a shell that has already exited (within the closed-shell
+     * retention window).
+     */
+    waitShell(shellId) {
+        const entry = this._shells.get(shellId);
+        if (!entry) {
+            const exitCode = this._closedShellIds.get(shellId);
+            if (exitCode !== undefined)
+                return Promise.resolve(exitCode);
+            throw new Error(`Shell not found: ${shellId}`);
+        }
+        return entry.exitPromise;
+    }
     /** Kill a shell process and remove it from tracking. */
     closeShell(shellId) {
         const entry = this._shells.get(shellId);
@@ -2104,609 +2270,406 @@ export class AgentOs {
             return;
         entry.proc.kill(9);
     }
-    /** Returns all active sessions with their IDs and agent types. */
-    listSessions() {
-        return [...this._sessions.values()].map((s) => ({
-            sessionId: s.sessionId,
-            agentType: s.agentType,
-        }));
-    }
-    /** Internal helper: retrieve a session or throw. */
-    _requireSession(sessionId) {
-        const session = this._sessions.get(sessionId);
-        if (!session) {
-            throw new Error(`Session not found: ${sessionId}`);
-        }
-        return session;
-    }
-    /** Returns all registered agents with their installation status. */
-    listAgents() {
-        // Collect all agent IDs from both package configs and hardcoded configs.
-        const allIds = new Set([
-            ...this._softwareAgentConfigs.keys(),
-            ...Object.keys(AGENT_CONFIGS),
-        ]);
-        return [...allIds]
-            .map((id) => {
-            const config = this._resolveAgentConfig(id);
-            if (!config)
-                return null;
-            let installed = false;
-            try {
-                // Check software roots first, then the host dir behind the
-                // `/root/node_modules` mount.
-                const vmPrefix = `/root/node_modules/${config.acpAdapter}`;
-                let hostPkgJsonPath = null;
-                for (const root of this._softwareRoots) {
-                    if (root.vmPath === vmPrefix) {
-                        hostPkgJsonPath = join(root.hostPath, "package.json");
-                        break;
-                    }
-                }
-                if (!hostPkgJsonPath) {
-                    const nodeModulesRoot = this._nodeModulesHostRoot();
-                    if (nodeModulesRoot) {
-                        hostPkgJsonPath = join(resolvePackageDir(nodeModulesRoot, config.acpAdapter), "package.json");
-                    }
-                }
-                if (!hostPkgJsonPath) {
-                    throw new Error("no package source");
-                }
-                readFileSync(hostPkgJsonPath);
-                installed = true;
-            }
-            catch {
-                // Package not installed
-            }
-            return {
-                id,
-                acpAdapter: config.acpAdapter,
-                agentPackage: config.agentPackage,
-                installed,
-            };
-        })
-            .filter((entry) => entry !== null);
-    }
-    _syncSessionState(session, state) {
-        session.processId = state.processId;
-        session.pid = state.pid ?? null;
-        session.closed = state.closed;
-        session.modes = toSessionModes(state.modes);
-        session.configOptions = toSessionConfigOptions(state.configOptions);
-        this._applySyntheticConfigOverrides(session);
-        session.capabilities = toAgentCapabilities(state.agentCapabilities);
-        session.agentInfo = toAgentInfo(state.agentInfo);
-    }
-    _applySessionUpdate(session, notification) {
-        if (notification.method !== "session/update") {
-            return;
-        }
-        const params = toRecord(notification.params);
-        const update = toRecord(params.update ?? params);
-        const sessionUpdate = update.sessionUpdate;
-        if (sessionUpdate === "current_mode_update" &&
-            typeof update.currentModeId === "string" &&
-            session.modes) {
-            session.modes = {
-                ...session.modes,
-                currentModeId: update.currentModeId,
-            };
-        }
-        if ((sessionUpdate === "config_option_update" ||
-            sessionUpdate === "config_options_update") &&
-            Array.isArray(update.configOptions)) {
-            session.configOptions = update.configOptions;
-        }
-    }
-    _recordSessionNotification(session, notification) {
-        this._applySessionUpdate(session, notification);
-        if (shouldDispatchToSessionEventHandlers(notification)) {
-            this._dispatchSessionEvent(session, notification);
-        }
-        if (notification.method === LEGACY_PERMISSION_METHOD ||
-            notification.method === ACP_PERMISSION_METHOD) {
-            const params = toRecord(notification.params);
-            const permissionId = params.permissionId;
-            if (typeof permissionId === "string" ||
-                typeof permissionId === "number") {
-                const request = {
-                    permissionId: String(permissionId),
-                    description: typeof params.description === "string"
-                        ? params.description
-                        : undefined,
-                    params,
-                };
-                for (const handler of session.permissionHandlers) {
-                    handler(request);
-                }
-            }
+    async openSession(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpOpenSessionRequest",
+            val: {
+                sessionId: input.sessionId ?? null,
+                agent: input.agent,
+                cwd: input.cwd ?? null,
+                additionalDirectories: input.additionalDirectories === undefined
+                    ? null
+                    : JSON.stringify(input.additionalDirectories),
+                env: input.env === undefined ? null : JSON.stringify(input.env),
+                mcpServers: input.mcpServers === undefined
+                    ? null
+                    : JSON.stringify(input.mcpServers),
+                permissionPolicy: input.permissionPolicy ?? null,
+                skipOsInstructions: input.skipOsInstructions ?? null,
+                additionalInstructions: combineInstructions(input.additionalInstructions, this._bindingReference) ?? null,
+            },
+        });
+        if (response.tag !== "AcpOpenSessionResponse") {
+            throw new Error(`unexpected openSession response: ${response.tag}`);
         }
     }
-    _dispatchSessionEvent(session, notification) {
-        if (session.eventHandlers.size === 0) {
-            return;
-        }
-        for (const subscriber of [...session.eventHandlers]) {
-            try {
-                subscriber.handler(notification);
-            }
-            catch {
-                // Ignore subscriber callback failures and keep event delivery moving.
-            }
+    async getSession(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetDurableSessionRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpGetDurableSessionResponse") {
+            throw new Error(`unexpected getSession response: ${response.tag}`);
         }
+        return decodeDurableSessionInfo(response.val.session);
     }
-    _subscribeSessionEvents(session, handler) {
-        const subscriber = {
-            handler,
-        };
-        session.eventHandlers.add(subscriber);
-        return () => {
-            session.eventHandlers.delete(subscriber);
+    async listSessions(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpListDurableSessionsRequest",
+            val: { cursor: input?.cursor ?? null, limit: input?.limit ?? null },
+        });
+        if (response.tag !== "AcpListDurableSessionsResponse") {
+            throw new Error(`unexpected listSessions response: ${response.tag}`);
+        }
+        return {
+            sessions: response.val.sessions.map(decodeDurableSessionInfo),
+            nextCursor: response.val.nextCursor,
         };
     }
-    _applySyntheticConfigOverrides(session) {
-        if (session.configOverrides.size === 0) {
-            return;
-        }
-        session.configOptions = session.configOptions.map((option) => {
-            const override = session.configOverrides.get(option.id) ??
-                (typeof option.category === "string"
-                    ? session.configOverrides.get(option.category)
-                    : undefined);
-            return override === undefined
-                ? option
-                : { ...option, currentValue: override };
+    async deleteSession(input = {}) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpDeleteSessionRequest",
+            val: { sessionId: input.sessionId ?? null },
         });
-    }
-    _handleSidecarEvent(event) {
-        if (event.payload.type === "ext") {
-            this._handleAcpExtEvent(event.payload.envelope);
-            return;
-        }
-        if (event.payload.type !== "structured") {
-            return;
-        }
-        if (event.payload.name !== "acp.session_event") {
-            return;
+        if (response.tag !== "AcpDeleteSessionResponse") {
+            throw new Error(`unexpected deleteSession response: ${response.tag}`);
         }
-        const sessionId = event.payload.detail.session_id;
-        const session = sessionId ? this._sessions.get(sessionId) : undefined;
-        if (!session) {
-            return;
+    }
+    async unloadSession(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpUnloadSessionRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpUnloadSessionResponse") {
+            throw new Error(`unexpected unloadSession response: ${response.tag}`);
         }
-        const notificationText = event.payload.detail.notification;
-        if (typeof notificationText !== "string") {
-            return;
+    }
+    async prompt(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpPromptRequest",
+            val: {
+                sessionId: input.sessionId ?? null,
+                idempotencyKey: input.idempotencyKey ?? null,
+                content: JSON.stringify(input.content),
+            },
+        });
+        if (response.tag !== "AcpPromptResponse") {
+            throw new Error(`unexpected prompt response: ${response.tag}`);
         }
-        try {
-            this._recordSessionNotification(session, toJsonRpcNotification(JSON.parse(notificationText)));
+        return {
+            sessionId: response.val.sessionId,
+            message: response.val.message === null ? null : JSON.parse(response.val.message),
+            stopReason: response.val.stopReason,
+        };
+    }
+    async cancelPrompt(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpCancelPromptRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpCancelPromptResponse") {
+            throw new Error(`unexpected cancelPrompt response: ${response.tag}`);
         }
-        catch {
-            // Ignore malformed event payloads from the sidecar.
+        if (response.val.status !== "cancelled" &&
+            response.val.status !== "no_active_prompt") {
+            throw new Error(`invalid cancelPrompt status: ${response.val.status}`);
         }
+        return { status: response.val.status };
     }
-    _handleAcpExtEvent(envelope) {
-        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
-            return;
+    async respondPermission(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpRespondPermissionRequest",
+            val: {
+                sessionId: input.sessionId,
+                requestId: input.requestId,
+                optionId: input.optionId,
+            },
+        });
+        if (response.tag !== "AcpRespondPermissionResponse") {
+            throw new Error(`unexpected respondPermission response: ${response.tag}`);
         }
-        try {
-            const event = decodeAcpEvent(envelope.payload);
-            switch (event.tag) {
-                case "AcpSessionEvent": {
-                    const session = this._sessions.get(event.val.sessionId);
-                    if (!session) {
-                        return;
-                    }
-                    this._recordSessionNotification(session, toJsonRpcNotification(JSON.parse(event.val.notification)));
-                    return;
-                }
-            }
+        if (response.val.status !== "accepted" &&
+            response.val.status !== "not_pending") {
+            throw new Error(`invalid respondPermission status: ${response.val.status}`);
         }
-        catch {
-            // Ignore malformed event payloads from the sidecar.
+        if (response.val.status === "accepted") {
+            if (response.val.reason !== null) {
+                throw new Error("accepted permission response must not include a reason");
+            }
+            return { status: "accepted" };
         }
-    }
-    _unsupportedConfigResponse(agentType, category) {
-        const message = agentType === "opencode" && category === "model"
-            ? "OpenCode reports available models, but model switching must be configured before createSession() because ACP session/set_config_option is not implemented."
-            : `The ${category} config option is read-only for ${agentType} sessions.`;
         return {
-            jsonrpc: "2.0",
-            id: null,
-            error: {
-                code: -32601,
-                message,
-            },
+            status: "not_pending",
+            reason: permissionTerminalReason(response.val.reason),
         };
     }
-    async _sendAcpRequest(request) {
-        const envelope = await this._sidecarClient.extensionRequest(this._sidecarSession, this._sidecarVm, {
-            namespace: ACP_EXTENSION_NAMESPACE,
-            payload: encodeAcpRequest(request),
+    async readHistory(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpReadHistoryRequest",
+            val: {
+                sessionId: input?.sessionId ?? null,
+                before: input?.before === undefined ? null : BigInt(input.before),
+                after: input?.after === undefined ? null : BigInt(input.after),
+                limit: input?.limit ?? null,
+            },
         });
-        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
-            throw new Error(`unexpected ACP Ext namespace: ${envelope.namespace}`);
+        if (response.tag !== "AcpHistoryPageResponse") {
+            throw new Error(`unexpected readHistory response: ${response.tag}`);
         }
-        const response = decodeAcpResponse(envelope.payload);
-        if (response.tag === "AcpErrorResponse") {
-            const error = new Error(response.val.message);
-            error.code = response.val.code;
-            throw error;
+        return {
+            events: response.val.events.map(decodeDurableSessionEvent),
+            hasMoreBefore: response.val.hasMoreBefore,
+            hasMoreAfter: response.val.hasMoreAfter,
+        };
+    }
+    async getSessionConfig(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetSessionConfigRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpSessionConfigResponse") {
+            throw new Error(`unexpected getSessionConfig response: ${response.tag}`);
         }
-        return response;
+        return {
+            revision: safeWireU64(response.val.revision),
+            options: JSON.parse(response.val.options),
+        };
     }
-    async _sendSessionRequest(sessionId, method, params) {
-        const session = this._requireSession(sessionId);
-        const response = await new Promise((resolve, reject) => {
-            const resolvers = this._pendingSessionRequestResolvers.get(sessionId) ?? new Set();
-            const resolver = {
-                method,
-                resolve: (response) => {
-                    resolve(response);
-                },
-            };
-            resolvers.add(resolver);
-            this._pendingSessionRequestResolvers.set(sessionId, resolvers);
-            void this._sendAcpRequest({
-                tag: "AcpSessionRequest",
-                val: {
-                    sessionId,
-                    method,
-                    params: params === undefined ? null : JSON.stringify(params),
-                },
-            })
-                .then((response) => {
-                if (response.tag !== "AcpSessionRpcResponse") {
-                    throw new Error(`unexpected response to AcpSessionRequest: ${response.tag}`);
-                }
-                return toJsonRpcResponse(JSON.parse(response.val.response));
-            })
-                .then(resolve, reject)
-                .finally(() => {
-                const nextResolvers = this._pendingSessionRequestResolvers.get(sessionId);
-                if (!nextResolvers) {
-                    return;
-                }
-                nextResolvers.delete(resolver);
-                if (nextResolvers.size === 0) {
-                    this._pendingSessionRequestResolvers.delete(sessionId);
-                }
-            });
+    async setSessionConfigOption(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpSetSessionConfigOptionRequest",
+            val: {
+                sessionId: input.sessionId ?? null,
+                configId: input.configId,
+                value: JSON.stringify(input.value),
+            },
         });
-        const liveSession = this._sessions.get(sessionId);
-        if (liveSession && !isLocalCancelledPromptResponse(method, response)) {
-            await this._hydrateSessionState(liveSession).catch(() => { });
-        }
-        if (!response.error) {
-            if (method === "session/set_mode" &&
-                typeof params?.modeId === "string" &&
-                session.modes) {
-                session.modes = {
-                    ...session.modes,
-                    currentModeId: params.modeId,
-                };
-            }
-            if (method === "session/set_config_option" &&
-                typeof params?.configId === "string" &&
-                typeof params?.value === "string") {
-                const nextValue = params.value;
-                const updatedOption = session.configOptions.find((option) => option.id === params.configId);
-                session.configOverrides.set(params.configId, nextValue);
-                if (typeof updatedOption?.category === "string") {
-                    session.configOverrides.set(updatedOption.category, nextValue);
-                }
-                session.configOptions = session.configOptions.map((option) => option.id === params.configId
-                    ? { ...option, currentValue: nextValue }
-                    : option);
-            }
+        if (response.tag !== "AcpSessionConfigResponse") {
+            throw new Error(`unexpected setSessionConfigOption response: ${response.tag}`);
         }
-        return response;
+        return {
+            revision: safeWireU64(response.val.revision),
+            options: JSON.parse(response.val.options),
+        };
     }
-    async _setSessionConfigByCategory(sessionId, category, value) {
-        const session = this._requireSession(sessionId);
-        const option = session.configOptions.find((entry) => entry.category === category);
-        if (option?.readOnly) {
-            return this._unsupportedConfigResponse(session.agentType, category);
+    async getSessionCapabilities(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetSessionCapabilitiesRequest",
+            val: { sessionId: input?.sessionId ?? null },
+        });
+        if (response.tag !== "AcpSessionCapabilitiesResponse") {
+            throw new Error(`unexpected getSessionCapabilities response: ${response.tag}`);
         }
-        const response = await this._sendSessionRequest(sessionId, "session/set_config_option", {
-            configId: option?.id ?? category,
-            value,
+        return response.val.capabilities === null
+            ? null
+            : normalizeSessionCapabilities(JSON.parse(response.val.capabilities));
+    }
+    async getSessionAgentInfo(input) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetSessionAgentInfoRequest",
+            val: { sessionId: input?.sessionId ?? null },
         });
-        return response;
+        if (response.tag !== "AcpSessionAgentInfoResponse") {
+            throw new Error(`unexpected getSessionAgentInfo response: ${response.tag}`);
+        }
+        return response.val.agentInfo === null
+            ? null
+            : JSON.parse(response.val.agentInfo);
+    }
+    /**
+     * Dynamically link a software package into the RUNNING VM. The package's
+     * `bin/` commands appear under `/opt/agentos/bin` (on `$PATH`) and its `share/man`
+     * pages under MANPATH immediately — the `/opt/agentos` mount is host-backed, so
+     * writing into its staging dir is reflected live with no reboot. An `agent`
+     * block registers the package for `openSession({ agent: name })`. Persists for the VM's
+     * lifetime (and across a snapshot iff the volume persists).
+     */
+    async linkSoftware(descriptor) {
+        // Forward to the sidecar, which owns the `/opt/agentos` projection and
+        // appends the package to its live host-backed staging dir; the commands
+        // appear under `/opt/agentos/bin` immediately. The sidecar rejects a
+        // duplicate command, surfaced here as a thrown error.
+        const commands = await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, descriptor);
+        if (this.#kernel instanceof NativeSidecarKernelProxy) {
+            this.#kernel.registerCommandGuestPaths(new Map(commands.projectedCommands.map((command) => [
+                command.name,
+                command.guestPath,
+            ])));
+            // Retain the linked package for runtime mount reconfigures:
+            // `configure_vm` is replace-on-write, so a later `mountFs` that
+            // resent only the boot packages would unproject this one.
+            this.#kernel.registerLinkedPackage(descriptor);
+        }
+        // The client parses no manifests: an `agent` block in the linked package is
+        // picked up by the sidecar (it owns the projected `/opt/agentos` and answers
+        // openSession/listAgents from it). Nothing to record client-side.
+    }
+    async listSoftware() {
+        return this._sidecarClient.providedCommands(this._sidecarSession, this._sidecarVm);
     }
-    _removeSession(sessionId) {
-        this._sessions.delete(sessionId);
+    /**
+     * Returns all registered agents with their installation status. Thin forwarder:
+     * sends `AcpListAgentsRequest` and maps the response. The sidecar enumerates the
+     * projected `/opt/agentos` packages (the client parses no manifests). Every such
+     * agent is a package materialized into the VM, so `installed` is always `true`.
+     */
+    async listAgents() {
+        const response = await this._sendAcpRequest({
+            tag: "AcpListAgentsRequest",
+            val: { reserved: false },
+        });
+        if (response.tag !== "AcpListAgentsResponse") {
+            throw new Error(`unexpected list_agents response: ${response.tag}`);
+        }
+        return response.val.agents.map((agent) => ({
+            id: agent.id,
+            installed: agent.installed,
+        }));
     }
-    _abortPendingSessionRequests(sessionId) {
-        const resolvers = this._pendingSessionRequestResolvers.get(sessionId);
-        if (!resolvers) {
+    _recordAgentStderr(event) {
+        if (!event.sessionId) {
             return;
         }
-        this._pendingSessionRequestResolvers.delete(sessionId);
-        const response = {
-            jsonrpc: "2.0",
-            id: null,
-            error: {
-                code: -32_000,
-                message: `Session closed: ${sessionId}`,
-            },
-        };
-        for (const resolver of resolvers) {
-            resolver.resolve(response);
+        const handler = this._agentStderrHandler;
+        if (!handler) {
+            return;
         }
-    }
-    _cancelPendingPromptRequests(sessionId) {
-        const resolvers = this._pendingSessionRequestResolvers.get(sessionId);
-        if (!resolvers) {
-            return false;
+        try {
+            handler({
+                sessionId: event.sessionId,
+                agentType: event.agentType,
+                processId: event.processId,
+                pid: null,
+                chunk: new Uint8Array(event.chunk),
+            });
         }
-        const response = {
-            jsonrpc: "2.0",
-            id: null,
-            result: {
-                stopReason: "cancelled",
-            },
+        catch (error) {
+            console.error("AgentOS stderr handler failed", error);
+        }
+    }
+    _recordAgentExit(event) {
+        const publicEvent = {
+            sessionId: event.sessionId,
+            agentType: event.agentType,
+            processId: event.processId,
+            pid: event.pid,
+            exitCode: event.exitCode,
+            restart: event.restart,
+            restartCount: event.restartCount,
+            maxRestarts: event.maxRestarts,
         };
-        let cancelledPrompt = false;
-        for (const resolver of [...resolvers]) {
-            if (resolver.method !== "session/prompt") {
-                continue;
+        const handler = this._agentExitHandler;
+        if (handler) {
+            try {
+                handler(publicEvent);
+            }
+            catch (error) {
+                console.error("AgentOS agent-exit handler failed", error);
             }
-            resolvers.delete(resolver);
-            resolver.resolve(response);
-            cancelledPrompt = true;
         }
-        if (resolvers.size === 0) {
-            this._pendingSessionRequestResolvers.delete(sessionId);
+        for (const key of ["*", event.sessionId]) {
+            for (const subscription of this._agentExitHandlers.get(key) ?? []) {
+                try {
+                    subscription(publicEvent);
+                }
+                catch (error) {
+                    console.error("AgentOS agent-exit subscription failed", error);
+                }
+            }
         }
-        return cancelledPrompt;
     }
-    _rejectPendingPermissionReplies(sessionId) {
-        const session = this._sessions.get(sessionId);
-        if (!session) {
+    _handleSidecarEvent(event) {
+        if (event.payload.type === "ext") {
+            this._handleAcpExtEvent(event.payload.envelope);
             return;
         }
-        this._rejectPendingPermissionRepliesFromSession(session);
-    }
-    _rejectPendingPermissionRepliesFromSession(session) {
-        for (const [permissionId, pendingReply,] of session.pendingPermissionReplies) {
-            clearTimeout(pendingReply.timer);
-            pendingReply.reject(new Error(`Session closed before permission reply: ${permissionId}`));
-        }
-        session.pendingPermissionReplies.clear();
-    }
-    async _closeSessionInternal(sessionId) {
-        const closing = this._sessionClosePromises.get(sessionId);
-        if (closing) {
-            return closing;
-        }
-        if (this._closedSessionIds.has(sessionId)) {
+        if (event.payload.type !== "structured") {
             return;
         }
-        this._abortPendingSessionRequests(sessionId);
-        this._rejectPendingPermissionReplies(sessionId);
-        this._requireSession(sessionId);
-        this._removeSession(sessionId);
-        this._closedSessionIds.add(sessionId);
-        const closePromise = this._sendAcpRequest({
-            tag: "AcpCloseSessionRequest",
-            val: { sessionId },
-        })
-            .then((response) => {
-            if (response.tag !== "AcpSessionClosedResponse") {
-                throw new Error(`unexpected response to AcpCloseSessionRequest: ${response.tag}`);
-            }
-        })
-            .finally(() => {
-            this._sessionClosePromises.delete(sessionId);
-        });
-        this._sessionClosePromises.set(sessionId, closePromise);
-        await closePromise;
+        if (event.payload.name === "limit_warning") {
+            this._handleLimitWarning(event.payload.detail);
+        }
     }
-    async _hydrateSessionState(session) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpGetSessionStateRequest",
-            val: { sessionId: session.sessionId },
-        });
-        if (response.tag !== "AcpSessionStateResponse") {
-            throw new Error(`unexpected response to AcpGetSessionStateRequest: ${response.tag}`);
-        }
-        const state = sidecarSessionStateFromAcp(response.val);
-        this._syncSessionState(session, state);
-    }
-    async createSession(agentType, options) {
-        const config = this._resolveAgentConfig(agentType);
-        if (!config) {
-            throw new Error(`Unknown agent type: ${agentType}`);
-        }
-        // System-prompt assembly and injection (launch args / OPENCODE_CONTEXTPATHS) are owned by
-        // the sidecar at AcpCreateSessionRequest. The host only forwards additionalInstructions /
-        // skipOsInstructions plus the agent's static launch args and env.
-        const launchArgs = [...(config.launchArgs ?? [])];
-        let launchEnv = { ...config.defaultEnv, ...options?.env };
-        const sessionCwd = options?.cwd ?? "/home/user";
-        const adapterEntrypoint = this._resolveAdapterBin(config.acpAdapter);
-        if ((agentType === "pi" || agentType === "pi-cli") &&
-            !launchEnv.PI_ACP_PI_COMMAND) {
-            launchEnv = {
-                ...launchEnv,
-                PI_ACP_PI_COMMAND: this._resolvePackageBin(config.agentPackage, "pi"),
-            };
+    _handleLimitWarning(detail) {
+        if (!this._limitWarningHandler) {
+            return;
         }
-        const response = await this._sendAcpRequest({
-            tag: "AcpCreateSessionRequest",
-            val: {
-                agentType: String(agentType),
-                runtime: AcpRuntimeKind.JavaScript,
-                adapterEntrypoint,
-                args: launchArgs,
-                env: new Map(Object.entries(launchEnv)),
-                cwd: sessionCwd,
-                mcpServers: JSON.stringify(options?.mcpServers ?? []),
-                protocolVersion: ACP_PROTOCOL_VERSION,
-                clientCapabilities: JSON.stringify(defaultAcpClientCapabilities()),
-                additionalInstructions: combineInstructions(options?.additionalInstructions, this._toolReference),
-                skipOsInstructions: options?.skipOsInstructions ?? false,
-            },
-        });
-        if (response.tag !== "AcpSessionCreatedResponse") {
-            throw new Error(`unexpected create_session response: ${response.tag}`);
-        }
-        const created = sidecarSessionCreatedFromAcp(response.val);
-        // The sessionId is chosen by the (untrusted/buggy) ACP adapter or sidecar. If it collides
-        // with a live session already in `_sessions`, blindly overwriting the entry would orphan the
-        // first session's event/permission handlers and pending permission replies. Fail closed:
-        // reject the colliding create and leave the original session intact. (A previously-closed,
-        // evicted id may still be re-used; only a live, non-closed entry is a collision.)
-        const existing = this._sessions.get(created.sessionId);
-        if (existing !== undefined && !existing.closed) {
-            throw new Error(`session id collision: ${created.sessionId}`);
-        }
-        const initData = {
-            modes: toSessionModes(created.modes) ?? undefined,
-            configOptions: toSessionConfigOptions(created.configOptions),
-            capabilities: toAgentCapabilities(created.agentCapabilities),
-            agentInfo: toAgentInfo(created.agentInfo) ?? undefined,
+        const toNumber = (value) => {
+            const parsed = Number(value);
+            return Number.isFinite(parsed) ? parsed : 0;
         };
-        const session = sessionEntryFromInit(created.sessionId, String(agentType), initData);
-        this._closedSessionIds.delete(created.sessionId);
-        this._sessions.set(created.sessionId, session);
         try {
-            await this._hydrateSessionState(session);
+            this._limitWarningHandler({
+                limit: detail.limit ?? "",
+                category: detail.category ?? "",
+                observed: toNumber(detail.observed),
+                capacity: toNumber(detail.capacity),
+                fillPercent: toNumber(detail.fillPercent),
+            });
         }
         catch (error) {
-            this._removeSession(created.sessionId);
-            throw error;
+            console.error("AgentOS limit-warning handler failed", error);
         }
-        return { sessionId: created.sessionId };
     }
-    /**
-     * Resume a session that exists in durable storage but is not live in this VM
-     * (e.g. after a Rivet actor slept and woke with a fresh VM). Thin forwarder:
-     * resolves the agent config + adapter entrypoint exactly as {@link createSession}
-     * does, then forwards a single `AcpResumeSessionRequest` to the sidecar, which
-     * owns the resume state machine (native `session/load` when the agent supports
-     * it, else `session/new` + a transcript-continuation preamble). The returned
-     * `sessionId` is the live id in this VM (equal to the requested id for native
-     * loads, freshly assigned for the fallback); the caller remaps `external -> live`.
-     * The new live session is registered + hydrated locally so subsequent prompts
-     * route to it.
-     *
-     * Resume depends on a durable root; on a non-durable (default in-memory) root
-     * there is no surviving store and the fallback tier always runs.
-     */
-    async resumeSession(sessionId, agentType, options) {
-        const config = this._resolveAgentConfig(agentType);
-        if (!config) {
-            throw new Error(`Unknown agent type: ${agentType}`);
-        }
-        const adapterEntrypoint = this._resolveAdapterBin(config.acpAdapter);
-        let launchEnv = { ...config.defaultEnv, ...options?.env };
-        const sessionCwd = options?.cwd ?? "/home/user";
-        if ((agentType === "pi" || agentType === "pi-cli") &&
-            !launchEnv.PI_ACP_PI_COMMAND) {
-            launchEnv = {
-                ...launchEnv,
-                PI_ACP_PI_COMMAND: this._resolvePackageBin(config.agentPackage, "pi"),
-            };
+    _handleAcpExtEvent(envelope) {
+        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
+            return;
         }
-        // The resume wire request has no dedicated `adapterEntrypoint` field; carry
-        // the resolved entrypoint through env under the sidecar's reserved key. The
-        // sidecar reads it and strips it before launching the adapter.
-        launchEnv = {
-            ...launchEnv,
-            [RESUME_ADAPTER_ENTRYPOINT_ENV]: adapterEntrypoint,
-        };
-        const response = await this._sendAcpRequest({
-            tag: "AcpResumeSessionRequest",
-            val: {
-                sessionId,
-                agentType: String(agentType),
-                transcriptPath: options?.transcriptPath ?? null,
-                cwd: sessionCwd,
-                env: new Map(Object.entries(launchEnv)),
-            },
-        });
-        if (response.tag !== "AcpSessionResumedResponse") {
-            throw new Error(`unexpected resume_session response: ${response.tag}`);
-        }
-        const { sessionId: liveSessionId, mode } = response.val;
-        // Register + hydrate the live session so subsequent prompts route to it.
-        const session = sessionEntryFromInit(liveSessionId, String(agentType), {});
-        this._closedSessionIds.delete(liveSessionId);
-        this._sessions.set(liveSessionId, session);
         try {
-            await this._hydrateSessionState(session);
+            const event = decodeAcpEvent(envelope.payload);
+            switch (event.tag) {
+                case "AcpDurableSessionEvent": {
+                    this._emitDurableSessionEvent(decodeDurableSessionEvent(event.val));
+                    return;
+                }
+                case "AcpEphemeralSessionUpdateEvent": {
+                    const update = JSON.parse(event.val.update);
+                    const { sessionUpdate: type, ...payload } = update;
+                    this._emitDurableSessionEvent({
+                        durability: "ephemeral",
+                        type,
+                        sessionId: event.val.sessionId,
+                        afterSequence: safeWireU64(event.val.afterSequence),
+                        ...payload,
+                    });
+                    return;
+                }
+                case "AcpSessionEvent":
+                    return;
+                case "AcpAgentStderrEvent": {
+                    this._recordAgentStderr(event.val);
+                    return;
+                }
+                case "AcpAgentExitedEvent": {
+                    this._recordAgentExit(event.val);
+                    return;
+                }
+            }
         }
         catch (error) {
-            this._removeSession(liveSessionId);
-            throw error;
+            console.error("AgentOS failed to decode an ACP sidecar event", error);
         }
-        return { sessionId: liveSessionId, mode };
     }
-    /**
-     * Resolve the VM bin entry point of an ACP adapter package.
-     * Reads from the host filesystem since kernel.readFile() resolves through
-     * mounts; adapter package.json is read directly off the host dir backing
-     * the relevant mount.
-     */
-    _resolveAdapterBin(adapterPackage) {
-        return this._resolvePackageBin(adapterPackage);
-    }
-    /**
-     * Parent of the host directory backing the `/root/node_modules` mount, if
-     * the caller supplied one (e.g. via `nodeModulesMount(...)`). Used as the
-     * `resolvePackageDir` start dir for adapter/agent package resolution when no
-     * software root matches. `nodeModulesMount` mounts `<dir>/node_modules`, so
-     * the start dir is `<dir>` (one level above the node_modules tree).
-     */
-    _nodeModulesHostRoot() {
-        for (const mount of this._hostMounts) {
-            if (mount.vmPath === "/root/node_modules") {
-                return dirname(mount.hostPath);
-            }
-        }
-        return null;
-    }
-    _resolvePackageBin(packageName, binName) {
-        const vmPrefix = `/root/node_modules/${packageName}`;
-        let hostPkgJsonPath = null;
-        for (const root of this._softwareRoots) {
-            if (root.vmPath === vmPrefix) {
-                hostPkgJsonPath = join(root.hostPath, "package.json");
-                break;
+    _emitDurableSessionEvent(entry) {
+        for (const handler of this._durableSessionEventHandlers.get(entry.sessionId) ?? []) {
+            try {
+                handler(entry);
             }
-        }
-        // Fall back to the host dir behind the `/root/node_modules` mount.
-        if (!hostPkgJsonPath) {
-            const nodeModulesRoot = this._nodeModulesHostRoot();
-            if (!nodeModulesRoot) {
-                throw new Error(`Cannot resolve package "${packageName}": no software root provides it and ` +
-                    `no /root/node_modules mount was supplied. Pass ` +
-                    `mounts: [nodeModulesMount("<host>/node_modules")] to AgentOs.create().`);
+            catch (error) {
+                console.error("AgentOS session event handler failed", error);
             }
-            hostPkgJsonPath = join(resolvePackageDir(nodeModulesRoot, packageName), "package.json");
-        }
-        const pkg = JSON.parse(readFileSync(hostPkgJsonPath, "utf-8"));
-        let binEntry;
-        if (typeof pkg.bin === "string") {
-            binEntry = pkg.bin;
         }
-        else if (typeof pkg.bin === "object" && pkg.bin !== null) {
-            binEntry =
-                (binName ? pkg.bin[binName] : undefined) ??
-                    pkg.bin[packageName] ??
-                    Object.values(pkg.bin)[0];
+    }
+    async _sendAcpRequest(request) {
+        const envelope = await this._sidecarClient.extensionRequest(this._sidecarSession, this._sidecarVm, {
+            namespace: ACP_EXTENSION_NAMESPACE,
+            payload: encodeAcpRequest(request),
+        });
+        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
+            throw new Error(`unexpected ACP Ext namespace: ${envelope.namespace}`);
         }
-        if (!binEntry) {
-            throw new Error(`No bin entry found in ${packageName}/package.json`);
+        const response = decodeAcpResponse(envelope.payload);
+        if (response.tag === "AcpErrorResponse") {
+            const error = new Error(response.val.message);
+            error.code = response.val.code;
+            throw error;
         }
-        return `${vmPrefix}/${binEntry}`;
+        return response;
     }
     _installSidecarRequestHandler() {
         const context = {
-            toolKits: this._toolKits,
-            toolMap: buildToolMap(this._toolKits),
+            bindings: this._bindings,
+            bindingMap: buildBindingMap(this._bindings),
             permissions: this._permissions,
             readFile: (path) => this.readFile(path),
         };
@@ -2715,10 +2678,8 @@ export class AgentOs {
                 case "host_callback":
                     return handleHostCallback(request, context);
                 case "js_bridge_call":
-                    return Promise.resolve({
-                        type: "js_bridge_result",
-                        call_id: request.payload.call_id,
-                        error: `unsupported sidecar request type: ${request.payload.type}`,
+                    return handleJsBridgeCall(request.payload, {
+                        filesystem: this.#kernel.vfs,
                     });
                 case "ext":
                     return this._handleAcpExtSidecarRequest(request.payload.envelope);
@@ -2737,25 +2698,6 @@ export class AgentOs {
         }
         const callback = decodeAcpCallback(envelope.payload);
         switch (callback.tag) {
-            case "AcpPermissionCallback": {
-                const reply = await this._handleAcpPermissionCallback(callback.val.sessionId, callback.val.permissionId, {
-                    ...toRecord(JSON.parse(callback.val.params)),
-                    _acpMethod: ACP_PERMISSION_METHOD,
-                });
-                return {
-                    type: "ext_result",
-                    envelope: {
-                        namespace: ACP_EXTENSION_NAMESPACE,
-                        payload: encodeAcpCallbackResponse({
-                            tag: "AcpPermissionCallbackResponse",
-                            val: {
-                                permissionId: callback.val.permissionId,
-                                reply,
-                            },
-                        }),
-                    },
-                };
-            }
             case "AcpHostRequestCallback": {
                 const response = await this._dispatchAcpSidecarRequest(toJsonRpcRequest(JSON.parse(callback.val.request)));
                 return {
@@ -2807,8 +2749,6 @@ export class AgentOs {
     async _handleSupportedAcpSidecarRequest(request) {
         const params = this._acpParams(request);
         switch (request.method) {
-            case ACP_PERMISSION_METHOD:
-                return this._handleAcpPermissionRequest(request, params);
             case "fs/read":
             case "fs/read_text_file":
                 return this._handleAcpReadFile(params);
@@ -2841,95 +2781,6 @@ export class AgentOs {
                 });
         }
     }
-    _normalizeAcpPermissionOptionId(options, reply) {
-        const optionTargets = reply === "always"
-            ? {
-                optionIds: new Set(["always", "allow_always"]),
-                kinds: new Set(["allow_always"]),
-            }
-            : reply === "once"
-                ? {
-                    optionIds: new Set(["once", "allow_once"]),
-                    kinds: new Set(["allow_once"]),
-                }
-                : {
-                    optionIds: new Set(["reject", "reject_once"]),
-                    kinds: new Set(["reject_once"]),
-                };
-        const matched = options?.find((option) => {
-            const optionId = typeof option.optionId === "string" ? option.optionId : undefined;
-            const kind = typeof option.kind === "string" ? option.kind : undefined;
-            return ((optionId !== undefined && optionTargets.optionIds.has(optionId)) ||
-                (kind !== undefined && optionTargets.kinds.has(kind)));
-        });
-        if (matched && typeof matched.optionId === "string") {
-            return matched.optionId;
-        }
-        if (reply === "always") {
-            return "allow_always";
-        }
-        if (reply === "once") {
-            return "allow_once";
-        }
-        return "reject_once";
-    }
-    _buildAcpPermissionResult(reply, params) {
-        const options = Array.isArray(params.options)
-            ? params.options.filter((option) => typeof option === "object" && option !== null)
-            : undefined;
-        const optionId = this._normalizeAcpPermissionOptionId(options, reply);
-        return {
-            outcome: optionId
-                ? {
-                    outcome: "selected",
-                    optionId,
-                }
-                : {
-                    outcome: "cancelled",
-                },
-        };
-    }
-    async _handleAcpPermissionRequest(request, params) {
-        const sessionId = typeof params.sessionId === "string" ? params.sessionId : undefined;
-        if (!sessionId) {
-            throw new AcpDispatchError(-32602, `${ACP_PERMISSION_METHOD} requires a sessionId`);
-        }
-        const session = this._sessions.get(sessionId);
-        if (!session) {
-            throw new AcpDispatchError(-32602, `Session not found: ${sessionId}`);
-        }
-        const permissionId = String(request.id);
-        const permissionParams = {
-            ...params,
-            permissionId,
-            _acpMethod: request.method,
-        };
-        if (session.permissionHandlers.size === 0) {
-            return this._buildAcpPermissionResult("reject", permissionParams);
-        }
-        const reply = await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                session.pendingPermissionReplies.delete(permissionId);
-                reject(new Error(`Timed out waiting for permission reply: ${permissionId}`));
-            }, 120_000);
-            session.pendingPermissionReplies.set(permissionId, {
-                resolve,
-                reject,
-                timer,
-            });
-            const permissionRequest = {
-                permissionId,
-                description: typeof permissionParams["description"] === "string"
-                    ? permissionParams["description"]
-                    : undefined,
-                params: permissionParams,
-            };
-            for (const handler of session.permissionHandlers) {
-                handler(permissionRequest);
-            }
-        });
-        return this._buildAcpPermissionResult(reply, permissionParams);
-    }
     _acpParams(request) {
         if (!request.params) {
             return {};
@@ -3102,9 +2953,6 @@ export class AgentOs {
                 ...(cwd ? { cwd } : {}),
                 ...(cols !== undefined ? { cols: Math.trunc(cols) } : {}),
                 ...(rows !== undefined ? { rows: Math.trunc(rows) } : {}),
-                onStderr: (data) => {
-                    this._appendAcpTerminalOutput(terminal, data);
-                },
             }),
             output: "",
             truncated: false,
@@ -3181,197 +3029,38 @@ export class AgentOs {
         terminal.handle.resize(Math.trunc(cols), Math.trunc(rows));
         return null;
     }
-    async _handleAcpPermissionCallback(sessionId, permissionId, params) {
-        const session = this._sessions.get(sessionId);
-        if (!session) {
-            return "reject";
-        }
-        if (session.permissionHandlers.size === 0) {
-            return "reject";
-        }
-        try {
-            return await new Promise((resolve, reject) => {
-                const timer = setTimeout(() => {
-                    session.pendingPermissionReplies.delete(permissionId);
-                    reject(new Error(`Timed out waiting for permission reply: ${permissionId}`));
-                }, 120_000);
-                session.pendingPermissionReplies.set(permissionId, {
-                    resolve,
-                    reject,
-                    timer,
-                });
-                const permissionRequest = {
-                    permissionId,
-                    description: typeof params.description === "string"
-                        ? params.description
-                        : undefined,
-                    params,
-                };
-                for (const handler of session.permissionHandlers) {
-                    handler(permissionRequest);
-                }
-            });
-        }
-        catch {
-            return "reject";
-        }
-    }
-    /**
-     * Resolve an agent config by ID. Package-provided configs take
-     * precedence over the hardcoded AGENT_CONFIGS.
-     */
-    _resolveAgentConfig(agentType) {
-        return (this._softwareAgentConfigs.get(agentType) ??
-            AGENT_CONFIGS[agentType]);
-    }
-    /**
-     * Gracefully destroy a session: cancel any pending work, close the client,
-     * and remove from tracking. Unlike close() which is abrupt, this attempts
-     * a graceful shutdown sequence.
-     */
-    async destroySession(sessionId) {
-        this._requireSession(sessionId);
-        try {
-            await this.cancelSession(sessionId);
-        }
-        catch {
-            // Ignore cancellation failures during teardown.
-        }
-        await this._closeSessionInternal(sessionId);
-    }
-    // ── Flat session API (ID-based) ───────────────────────────────
-    async prompt(sessionId, text) {
-        const session = this._requireSession(sessionId);
-        let agentText = "";
-        const handler = (event) => {
-            const params = toRecord(event.params);
-            const update = toRecord(params.update);
-            if (update?.sessionUpdate === "agent_message_chunk") {
-                const content = toRecord(update.content);
-                if (typeof content.text === "string") {
-                    agentText += content.text;
-                }
+    onSessionEvent(sessionIdOrHandler, maybeHandler) {
+        const sessionId = typeof sessionIdOrHandler === "string" ? sessionIdOrHandler : "main";
+        const handler = typeof sessionIdOrHandler === "function"
+            ? sessionIdOrHandler
+            : maybeHandler;
+        if (!handler) {
+            throw new TypeError("onSessionEvent requires a handler");
+        }
+        const handlers = this._durableSessionEventHandlers.get(sessionId) ?? new Set();
+        handlers.add(handler);
+        this._durableSessionEventHandlers.set(sessionId, handlers);
+        return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this._durableSessionEventHandlers.delete(sessionId);
             }
         };
-        const unsubscribe = this._subscribeSessionEvents(session, handler);
-        try {
-            const response = await this._sendSessionRequest(sessionId, "session/prompt", {
-                prompt: [{ type: "text", text }],
-            });
-            return { response, text: agentText };
-        }
-        finally {
-            unsubscribe();
-        }
-    }
-    /** Cancel ongoing agent work for a session. */
-    async cancelSession(sessionId) {
-        this._requireSession(sessionId);
-        const cancelledPendingPrompt = this._cancelPendingPromptRequests(sessionId);
-        if (cancelledPendingPrompt) {
-            // Session control requests share the same framed sidecar transport as an
-            // in-flight prompt request. If the adapter is blocked in prompt I/O, a
-            // synchronous cancel RPC can wedge behind that prompt until the transport
-            // timeout fires. Resolve the local prompt immediately, then let the sidecar
-            // cancellation continue in the background as best effort.
-            void this._sendSessionRequest(sessionId, "session/cancel").catch(() => { });
-            return {
-                jsonrpc: "2.0",
-                id: null,
-                result: {
-                    cancelled: true,
-                    requested: true,
-                    via: "prompt-fallback",
-                },
-            };
-        }
-        const response = await this._sendSessionRequest(sessionId, "session/cancel");
-        if (response.error?.code === -32601) {
-            return {
-                jsonrpc: "2.0",
-                id: null,
-                result: {
-                    cancelled: false,
-                    requested: true,
-                    via: "unsupported",
-                },
-            };
-        }
-        return response;
-    }
-    closeSession(sessionId) {
-        if (!this._sessions.has(sessionId) &&
-            !this._closedSessionIds.has(sessionId) &&
-            !this._sessionClosePromises.has(sessionId)) {
-            throw new Error(`Session not found: ${sessionId}`);
-        }
-        const closePromise = this._closeSessionInternal(sessionId);
-        // `closeSession()` is intentionally fire-and-forget; suppress unhandled
-        // rejections here and let tracked close promises surface errors to any
-        // internal/test callers awaiting `_sessionClosePromises`.
-        void closePromise.catch(() => { });
-    }
-    async respondPermission(sessionId, permissionId, reply) {
-        const session = this._requireSession(sessionId);
-        const pendingReply = session.pendingPermissionReplies.get(permissionId);
-        if (pendingReply) {
-            session.pendingPermissionReplies.delete(permissionId);
-            clearTimeout(pendingReply.timer);
-            pendingReply.resolve(reply);
-            return {
-                jsonrpc: "2.0",
-                id: null,
-                result: {
-                    permissionId,
-                    reply,
-                    via: "sidecar-request",
-                },
-            };
-        }
-        return this._sendSessionRequest(sessionId, LEGACY_PERMISSION_METHOD, {
-            permissionId,
-            reply,
-        });
-    }
-    async setSessionMode(sessionId, modeId) {
-        return this._sendSessionRequest(sessionId, "session/set_mode", {
-            modeId,
-        });
-    }
-    getSessionModes(sessionId) {
-        return this._requireSession(sessionId).modes;
-    }
-    async setSessionModel(sessionId, model) {
-        return this._setSessionConfigByCategory(sessionId, "model", model);
-    }
-    async setSessionThoughtLevel(sessionId, level) {
-        return this._setSessionConfigByCategory(sessionId, "thought_level", level);
-    }
-    getSessionConfigOptions(sessionId) {
-        return [...this._requireSession(sessionId).configOptions];
-    }
-    getSessionCapabilities(sessionId) {
-        const caps = this._requireSession(sessionId).capabilities;
-        return Object.keys(caps).length > 0 ? caps : null;
-    }
-    getSessionAgentInfo(sessionId) {
-        return this._requireSession(sessionId).agentInfo;
     }
-    async rawSessionSend(sessionId, method, params) {
-        return this._sendSessionRequest(sessionId, method, params);
-    }
-    async rawSend(sessionId, method, params) {
-        return this.rawSessionSend(sessionId, method, params);
-    }
-    onSessionEvent(sessionId, handler) {
-        const session = this._requireSession(sessionId);
-        return this._subscribeSessionEvents(session, handler);
-    }
-    onPermissionRequest(sessionId, handler) {
-        const session = this._requireSession(sessionId);
-        session.permissionHandlers.add(handler);
+    onAgentExit(sessionIdOrHandler, maybeHandler) {
+        const sessionId = typeof sessionIdOrHandler === "string" ? sessionIdOrHandler : "*";
+        const handler = typeof sessionIdOrHandler === "function"
+            ? sessionIdOrHandler
+            : maybeHandler;
+        if (!handler)
+            throw new TypeError("onAgentExit requires a handler");
+        const handlers = this._agentExitHandlers.get(sessionId) ?? new Set();
+        handlers.add(handler);
+        this._agentExitHandlers.set(sessionId, handlers);
         return () => {
-            session.permissionHandlers.delete(handler);
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this._agentExitHandlers.delete(sessionId);
         };
     }
     // ── Cron ────────────────────────────────────────────────────
@@ -3393,9 +3082,6 @@ export class AgentOs {
     }
     async dispose() {
         this._cronManager.dispose();
-        for (const sessionId of [...this._sessions.keys()]) {
-            await this._closeSessionInternal(sessionId).catch(() => { });
-        }
         for (const [id, entry] of this._shells) {
             entry.handle.kill();
         }
@@ -3407,6 +3093,7 @@ export class AgentOs {
             terminalExitPromises.push(terminal.waitPromise.then(() => undefined, () => undefined));
         }
         this._acpTerminals.clear();
+        this._processes.clear();
         await waitForTrackedExitPromises([...shellExitPromises, ...terminalExitPromises], SHELL_DISPOSE_TIMEOUT_MS);
         this._disposeSidecarEventListener();
         const sidecarLease = this._sidecarLease;
@@ -3436,6 +3123,173 @@ function resolveAgentOsSidecar(config) {
 }
 const sidecarStates = new WeakMap();
 const sharedSidecars = new Map();
+let sidecarProcessExitHookInstalled = false;
+/**
+ * Install a one-time, synchronous `process.on("exit")` hook that SIGKILLs any
+ * pooled shared sidecar child. Once a one-shot host process is allowed to exit
+ * (its sidecar handles are unref'd at 0 leases), this reaps the sidecar
+ * immediately instead of waiting for its stdin-EOF grace window — no orphan, no
+ * delay. We deliberately do NOT install SIGINT/SIGTERM handlers: a library
+ * should not hijack the host's signal handling. SIGINT still reaches the sidecar
+ * via the process group, and SIGTERM-driven exit still closes its stdin.
+ */
+function ensureSidecarProcessExitCleanup() {
+    if (sidecarProcessExitHookInstalled)
+        return;
+    sidecarProcessExitHookInstalled = true;
+    process.on("exit", () => {
+        for (const sidecar of sharedSidecars.values()) {
+            try {
+                sidecarStates.get(sidecar)?.sharedChild?.kill?.("SIGKILL");
+            }
+            catch {
+                // best-effort reap; the process is exiting regardless
+            }
+        }
+    });
+}
+function sidecarChildHandle(client) {
+    // SidecarProcess -> StdioSidecarProtocolClient.child (the spawned ChildProcess).
+    const protocolClient = client?.protocolClient;
+    return protocolClient?.child ?? undefined;
+}
+/**
+ * Apply the current hold state to the shared sidecar's child + stdio: ref them
+ * while ≥1 hold is live so in-flight VM work keeps the host process alive; unref
+ * them at 0 so a one-shot script exits on its own after `dispose()`. The sidecar
+ * process itself stays running (reusable) and self-exits on stdin EOF when the
+ * host finally goes away. Best-effort: never let ref/unref break VM lifecycle.
+ */
+function applySharedSidecarHold(state) {
+    const child = state.sharedChild;
+    if (!child)
+        return;
+    const hold = (state.eventLoopHolds ?? 0) > 0;
+    // Include the complete stdio array, not just the named fd0-fd2 aliases.
+    // Protocol v8 carries responses over fd3; leaving that control socket
+    // referenced pins Node's event loop after the final VM lease is disposed.
+    const handles = new Set([
+        child,
+        child.stdin,
+        child.stdout,
+        child.stderr,
+        ...(child.stdio ?? []),
+    ]);
+    for (const handle of handles) {
+        if (!handle)
+            continue;
+        try {
+            if (hold)
+                handle.ref?.();
+            else
+                handle.unref?.();
+        }
+        catch {
+            // ref/unref is an optimization, not correctness-critical
+        }
+    }
+}
+/**
+ * Take a hold for the entire create→use→dispose lifetime of one VM lease. Taken
+ * BEFORE VM creation starts (not when the lease lands in `activeLeases`) so a VM
+ * that is still mid-creation keeps the sidecar ref'd and a concurrent dispose
+ * cannot unref it out from under the in-flight create.
+ */
+function acquireSharedSidecarHold(state) {
+    state.eventLoopHolds = (state.eventLoopHolds ?? 0) + 1;
+    if (state.eventLoopHolds === 1)
+        applySharedSidecarHold(state);
+}
+/** Release a hold taken by {@link acquireSharedSidecarHold}; unref at 0. */
+function releaseSharedSidecarHold(state) {
+    const current = state.eventLoopHolds ?? 0;
+    if (current <= 0) {
+        // The `holdReleased` guard makes each lease release exactly once, so this
+        // should be unreachable. Warn rather than silently floor, per the repo's
+        // no-silent-masking rule, so an accounting bug surfaces instead of hiding.
+        state.eventLoopHolds = 0;
+        console.warn("[agentos] shared sidecar event-loop hold released more than acquired");
+        return;
+    }
+    state.eventLoopHolds = current - 1;
+    if (state.eventLoopHolds === 0)
+        applySharedSidecarHold(state);
+}
+/**
+ * Spawn-once accessor for a sidecar handle's shared native process. Concurrent
+ * callers await the same promise, so one `AgentOsSidecar` maps to exactly one
+ * `agent-os-sidecar` OS process for its whole lifetime.
+ */
+function ensureSharedSidecarNativeProcess(sidecar) {
+    const state = getSidecarState(sidecar);
+    if (!state.nativeProcess) {
+        ensureSidecarProcessExitCleanup();
+        state.nativeProcess = (async () => {
+            const client = SidecarProcess.spawn({
+                cwd: REPO_ROOT,
+                command: ensureNativeSidecarBinary(),
+                args: [],
+            });
+            // Track the child immediately — BEFORE the handshake await — so a
+            // failed `authenticateAndOpenSession()` can still reap it (otherwise
+            // the spawned child is untracked, unreapable, and pins the loop).
+            state.sharedChild = sidecarChildHandle(client);
+            if (!state.sharedChild) {
+                // We reached into @rivet-dev/agentos-runtime-core internals to get the child for
+                // idle-unref. If that shape ever changes this returns undefined and
+                // the optimization silently stops working (one-shot scripts would
+                // hang again). Make it loud rather than a silent regression.
+                console.warn("[agentos] could not resolve the shared sidecar child handle; " +
+                    "standalone scripts may not exit cleanly after dispose(). " +
+                    "This usually means @rivet-dev/agentos-runtime-core internals changed.");
+            }
+            // Apply the current hold state to the just-spawned child.
+            applySharedSidecarHold(state);
+            try {
+                const session = await client.authenticateAndOpenSession();
+                return { client, session };
+            }
+            catch (error) {
+                // Spawn/handshake failed: reap the child, drop the cached handle,
+                // and CLEAR the rejected promise so the next create() retries
+                // instead of permanently wedging on a rejected `nativeProcess`.
+                try {
+                    state.sharedChild?.kill?.("SIGKILL");
+                }
+                catch {
+                    // already gone
+                }
+                state.sharedChild = undefined;
+                state.nativeProcess = undefined;
+                throw error;
+            }
+        })();
+    }
+    return state.nativeProcess;
+}
+/** Dispose a sidecar handle's shared native process, if one was spawned. */
+async function disposeSharedSidecarNativeProcess(state) {
+    const pending = state.nativeProcess;
+    if (!pending) {
+        return;
+    }
+    state.nativeProcess = undefined;
+    // The cached child is now dead; drop it (symmetric with the assignment in
+    // ensureSharedSidecarNativeProcess). We deliberately do NOT zero
+    // `eventLoopHolds` here: this runs only from `AgentOsSidecar.dispose()`, which
+    // has already set the handle to `disposing` (so no new lease can acquire) and
+    // drained `activeLeases`; the disposed handle's state is then abandoned. Force-
+    // zeroing a shared counter could clobber a hold on a freshly re-acquired
+    // process generation, so it is left to the balanced acquire/release pairs.
+    state.sharedChild = undefined;
+    try {
+        const { client } = await pending;
+        await client.dispose();
+    }
+    catch {
+        // Process may have already exited; nothing to reclaim.
+    }
+}
 export class AgentOsSidecar {
     constructor(sidecarId, placement, sharedPool) {
         sidecarStates.set(this, {
@@ -3470,6 +3324,8 @@ export class AgentOsSidecar {
         }
         state.activeLeases.clear();
         state.description.activeVmCount = 0;
+        // Tear down the shared native process after all leased VMs are gone.
+        await disposeSharedSidecarNativeProcess(state);
         state.description.state = "disposed";
         if (state.sharedPool && sharedSidecars.get(state.sharedPool) === this) {
             sharedSidecars.delete(state.sharedPool);
@@ -3526,15 +3382,27 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
     }
     let transport;
     const client = createAgentOsSidecarClient({
-        async createSessionTransport(sessionBootstrap) {
+        async createOwnershipTransport(sessionBootstrap) {
             transport = await createInProcessSidecarTransport(sessionBootstrap, options);
             return transport;
         },
     });
+    // Hold the shared sidecar's event-loop ref for this lease's WHOLE lifetime —
+    // taken now, before VM creation, so a concurrent dispose cannot unref the
+    // sidecar while this create is still in flight. Released exactly once on
+    // dispose or on a failed create.
+    acquireSharedSidecarHold(state);
+    let holdReleased = false;
+    const releaseHold = () => {
+        if (holdReleased)
+            return;
+        holdReleased = true;
+        releaseSharedSidecarHold(state);
+    };
     let disposed = false;
     let leaseRecord;
     try {
-        const session = await client.createSession({
+        const session = await client.createOwnershipSession({
             placement: cloneSidecarPlacement(state.description.placement),
         });
         const vm = await session.createVm();
@@ -3555,6 +3423,10 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
                 state.activeLeases.delete(leaseRecord);
                 state.description.activeVmCount = state.activeLeases.size;
                 await client.dispose();
+                // Release this lease's hold; the shared sidecar is unref'd only
+                // once the last hold (across all in-flight + active leases) drops,
+                // so a one-shot host process can then exit on its own.
+                releaseHold();
             },
         };
         leaseRecord = {
@@ -3566,6 +3438,7 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
     }
     catch (error) {
         await client.dispose().catch(() => { });
+        releaseHold();
         throw error;
     }
 }