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

package/dist/agent-os.js

@@ -1,35 +1,11 @@
-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 { fileURLToPath } from "node:url";
-import commonSoftware from "@agentos-software/common";
-import { validateToolkits } from "./host-tools.js";
+import { posix as posixPath } from "node:path";
 import { zodToJsonSchema } from "./host-tools-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() {
-    return {
-        fs: {
-            readTextFile: true,
-            writeTextFile: true,
-        },
-        terminal: true,
-    };
-}
 async function waitForTrackedExitPromises(promises, timeoutMs) {
     if (promises.length === 0) {
         return;
@@ -41,31 +17,21 @@ async function waitForTrackedExitPromises(promises, timeoutMs) {
         }),
     ]);
 }
-import { AGENT_CONFIGS } from "./agents.js";
-import { getBaseEnvironment, getBaseFilesystemEntries, } from "./base-filesystem.js";
 import { CronManager } from "./cron/cron-manager.js";
-import { TimerScheduleDriver } from "./cron/timer-driver.js";
-import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-snapshot.js";
-import { createHostDirBackend } from "./host-dir-mount.js";
+import { resolveDefaultSoftware } from "./default-software.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";
+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"} restart=${event.restart} (${event.restartCount}/${event.maxRestarts})\n`);
+}
 const LEGACY_PERMISSION_METHOD = "request/permission";
 const ACP_PERMISSION_METHOD = "session/request_permission";
-class AcpDispatchError extends Error {
-    code;
-    data;
-    constructor(code, message, data) {
-        super(message);
-        this.name = "AcpDispatchError";
-        this.code = code;
-        this.data = data;
-    }
-}
 function toJsonRpcNotification(value) {
     if (!value ||
         typeof value !== "object" ||
@@ -88,24 +54,24 @@ function toJsonRpcResponse(value) {
     }
     return value;
 }
-function toJsonRpcRequest(value) {
-    if (!value ||
-        typeof value !== "object" ||
-        Array.isArray(value) ||
-        value.jsonrpc !== "2.0" ||
-        !(typeof value.id === "number" ||
-            typeof value.id === "string" ||
-            value.id === null) ||
-        typeof value.method !== "string") {
-        throw new Error("Invalid JSON-RPC request from ACP callback");
-    }
-    return value;
-}
 function toRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
         : {};
 }
+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 };
+    }
+    const record = toRecord(value);
+    if (typeof record.packagePath === "string") {
+        return { path: record.packagePath };
+    }
+    throw new TypeError("Invalid software package reference: expected a path string or { packagePath: string }");
+}
 function parseAcpJson(value, context) {
     if (value === null) {
         return undefined;
@@ -120,16 +86,6 @@ function parseAcpJson(value, context) {
 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,
@@ -143,47 +99,6 @@ function sidecarSessionStateFromAcp(response) {
         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;
-    #entries = new Map();
-    constructor(limit) {
-        if (!Number.isInteger(limit) || limit <= 0) {
-            throw new Error(`BoundedSet limit must be a positive integer: ${limit}`);
-        }
-        this.limit = limit;
-    }
-    add(value) {
-        if (this.#entries.has(value)) {
-            this.#entries.delete(value);
-        }
-        this.#entries.set(value, undefined);
-        if (this.#entries.size <= this.limit) {
-            return;
-        }
-        const oldest = this.#entries.keys().next();
-        if (!oldest.done) {
-            this.#entries.delete(oldest.value);
-        }
-    }
-    has(value) {
-        return this.#entries.has(value);
-    }
-    delete(value) {
-        return this.#entries.delete(value);
-    }
-    get size() {
-        return this.#entries.size;
-    }
-}
 function shouldDispatchToSessionEventHandlers(notification) {
     return notification.method === "session/update";
 }
@@ -211,20 +126,15 @@ function toAgentInfo(value) {
     }
     return value;
 }
-function sessionEntryFromInit(sessionId, agentType, initData) {
+function sessionEntryFromRoute(response) {
     return {
-        sessionId,
-        agentType,
-        processId: "",
-        pid: null,
-        closed: false,
-        modes: initData.modes ?? null,
-        configOptions: initData.configOptions ?? [],
-        capabilities: initData.capabilities ?? {},
-        agentInfo: initData.agentInfo ?? null,
+        sessionId: response.sessionId,
+        agentType: response.agentType,
+        processId: response.processId,
+        pid: response.pid,
         eventHandlers: new Set(),
         permissionHandlers: new Set(),
-        configOverrides: new Map(),
+        warnedNoPermissionHandler: false,
         pendingPermissionReplies: new Map(),
     };
 }
@@ -234,502 +144,41 @@ function isOverlayMountConfig(config) {
 function isNativeMountConfig(config) {
     return "plugin" in config;
 }
-function asMountConfigJsonObject(value) {
-    if (value && typeof value === "object" && !Array.isArray(value)) {
-        return value;
-    }
-    return {};
-}
-function getHostDirMountPluginConfig(config) {
-    const object = asMountConfigJsonObject(config);
-    if (typeof object.hostPath !== "string") {
-        return null;
-    }
-    const hostPathConfig = {
-        hostPath: object.hostPath,
-    };
-    if (typeof object.readOnly === "boolean") {
-        hostPathConfig.readOnly = object.readOnly;
-    }
-    return hostPathConfig;
-}
-function getSandboxAgentMountPluginConfig(config) {
-    const object = asMountConfigJsonObject(config);
-    if (typeof object.baseUrl !== "string") {
-        return null;
-    }
-    const sandboxConfig = {
-        baseUrl: object.baseUrl,
-    };
-    if (typeof object.token === "string") {
-        sandboxConfig.token = object.token;
-    }
-    if (typeof object.basePath === "string") {
-        sandboxConfig.basePath = object.basePath;
-    }
-    if (typeof object.timeoutMs === "number") {
-        sandboxConfig.timeoutMs = object.timeoutMs;
-    }
-    if (typeof object.maxFullReadBytes === "number") {
-        sandboxConfig.maxFullReadBytes = object.maxFullReadBytes;
-    }
-    if (object.headers &&
-        typeof object.headers === "object" &&
-        !Array.isArray(object.headers)) {
-        const headers = Object.entries(object.headers)
-            .filter(([, value]) => typeof value === "string")
-            .map(([name, value]) => [name, value]);
-        if (headers.length > 0) {
-            sandboxConfig.headers = Object.fromEntries(headers);
-        }
-    }
-    return sandboxConfig;
-}
-function getS3MountPluginConfig(config) {
-    const object = asMountConfigJsonObject(config);
-    if (typeof object.bucket !== "string") {
-        return null;
-    }
-    const s3Config = {
-        bucket: object.bucket,
-    };
-    if (typeof object.prefix === "string") {
-        s3Config.prefix = object.prefix;
-    }
-    if (typeof object.region === "string") {
-        s3Config.region = object.region;
-    }
-    if (typeof object.endpoint === "string") {
-        s3Config.endpoint = object.endpoint;
-    }
-    if (typeof object.chunkSize === "number") {
-        s3Config.chunkSize = object.chunkSize;
-    }
-    if (typeof object.inlineThreshold === "number") {
-        s3Config.inlineThreshold = object.inlineThreshold;
-    }
-    if (object.credentials &&
-        typeof object.credentials === "object" &&
-        !Array.isArray(object.credentials) &&
-        typeof object.credentials.accessKeyId === "string" &&
-        typeof object.credentials.secretAccessKey === "string") {
-        s3Config.credentials = {
-            accessKeyId: object.credentials.accessKeyId,
-            secretAccessKey: object.credentials.secretAccessKey,
-        };
-    }
-    return s3Config;
-}
-function getGoogleDriveMountPluginConfig(config) {
-    const object = asMountConfigJsonObject(config);
-    if (typeof object.folderId !== "string") {
-        return null;
-    }
-    if (!object.credentials ||
-        typeof object.credentials !== "object" ||
-        Array.isArray(object.credentials) ||
-        typeof object.credentials.clientEmail !== "string" ||
-        typeof object.credentials.privateKey !== "string") {
-        return null;
-    }
-    const googleDriveConfig = {
-        credentials: {
-            clientEmail: object.credentials.clientEmail,
-            privateKey: object.credentials.privateKey,
-        },
-        folderId: object.folderId,
-    };
-    if (typeof object.keyPrefix === "string") {
-        googleDriveConfig.keyPrefix = object.keyPrefix;
-    }
-    if (typeof object.chunkSize === "number") {
-        googleDriveConfig.chunkSize = object.chunkSize;
-    }
-    if (typeof object.inlineThreshold === "number") {
-        googleDriveConfig.inlineThreshold = object.inlineThreshold;
-    }
-    return googleDriveConfig;
-}
-const KERNEL_POSIX_BOOTSTRAP_DIRS = [
-    "/dev",
-    "/proc",
-    "/tmp",
-    "/bin",
-    "/lib",
-    "/sbin",
-    "/boot",
-    "/etc",
-    "/root",
-    "/run",
-    "/srv",
-    "/sys",
-    "/opt",
-    "/mnt",
-    "/media",
-    "/home",
-    "/home/agentos",
-    "/workspace",
-    "/usr",
-    "/usr/bin",
-    "/usr/games",
-    "/usr/include",
-    "/usr/lib",
-    "/usr/libexec",
-    "/usr/man",
-    "/usr/local",
-    "/usr/local/bin",
-    "/usr/sbin",
-    "/usr/share",
-    "/usr/share/man",
-    "/var",
-    "/var/cache",
-    "/var/empty",
-    "/var/lib",
-    "/var/lock",
-    "/var/log",
-    "/var/run",
-    "/var/spool",
-    "/var/tmp",
-    "/etc/agentos",
-];
-const NODE_RUNTIME_BOOTSTRAP_COMMANDS = ["node", "npm", "npx"];
-const KERNEL_COMMAND_STUB = "#!/bin/sh\n# kernel command stub\n";
-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/execution"),
-    join(REPO_ROOT, "crates/kernel"),
-    join(REPO_ROOT, "crates/sidecar"),
-];
-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 ?? []) {
-        if (lower.kind !== "snapshot-export") {
-            continue;
-        }
-        for (const entry of lower.source.filesystem.entries) {
-            paths.add(entry.path);
-        }
-    }
-    return paths;
-}
-function findBootstrapSeedEntry(config, path) {
-    for (const lower of config?.lowers ?? []) {
-        if (lower.kind !== "snapshot-export") {
-            continue;
-        }
-        const entry = lower.source.filesystem.entries.find((candidate) => candidate.path === path);
-        if (entry) {
-            return entry;
-        }
-    }
-    return getBaseFilesystemEntries().find((entry) => entry.path === path);
-}
-function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
-    const includesBundledBaseLayer = !(config?.disableDefaultBaseLayer ?? false);
-    const existingPaths = collectConfiguredLowerPaths(config);
-    if (includesBundledBaseLayer) {
-        for (const entry of getBaseFilesystemEntries()) {
-            existingPaths.add(entry.path);
-        }
-    }
-    const entries = [
-        {
-            path: "/",
-            type: "directory",
-            mode: "755",
-            uid: 0,
-            gid: 0,
-        },
-    ];
-    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,
-        });
-    }
-    if (!includesBundledBaseLayer && !existingPaths.has("/usr/bin/env")) {
-        entries.push({
-            path: "/usr/bin/env",
-            type: "file",
-            mode: "644",
-            uid: 0,
-            gid: 0,
-            content: "AA==",
-            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;
-        }
-        entries.push(entry);
-    }
-    return entries.length > 1 ? createSnapshotExport(entries) : null;
-}
-function buildLiveBootstrapDirectoryEntries(existingPaths, config) {
-    const entries = [];
-    for (const dir of KERNEL_POSIX_BOOTSTRAP_DIRS) {
-        if (existingPaths.has(dir)) {
-            continue;
-        }
-        const seed = findBootstrapSeedEntry(config, dir);
-        entries.push({
-            path: dir,
-            kind: "directory",
-            mode: Number.parseInt(seed?.type === "directory" ? seed.mode : "755", 8),
-            uid: seed?.uid ?? 0,
-            gid: seed?.gid ?? 0,
-            executable: true,
-        });
-    }
-    return entries;
-}
-async function bootstrapLiveBootstrapDirectories(client, session, vm, config) {
-    const existingPaths = new Set((await client.snapshotRootFilesystem(session, vm)).map((entry) => entry.path));
-    const entries = buildLiveBootstrapDirectoryEntries(existingPaths, config);
-    if (entries.length === 0) {
-        return;
+function requireSnapshotField(entry, field) {
+    const value = entry[field];
+    if (value === undefined || value === null) {
+        throw new Error(`sidecar root snapshot for ${entry.path} is missing ${String(field)}`);
     }
-    await client.bootstrapRootFilesystem(session, vm, entries);
+    return value;
 }
-function toSnapshotModeString(mode, kind) {
-    const fallback = kind === "directory" ? 0o755 : kind === "symlink" ? 0o777 : 0o644;
-    return `0${((mode ?? fallback) & 0o7777).toString(8)}`;
+function toSnapshotModeString(mode) {
+    return `0${(mode & 0o7777).toString(8)}`;
 }
 function convertSidecarRootSnapshotEntries(entries) {
     return entries.map((entry) => {
         const baseEntry = {
             path: entry.path,
             type: entry.kind,
-            mode: toSnapshotModeString(entry.mode, entry.kind),
-            uid: entry.uid ?? 0,
-            gid: entry.gid ?? 0,
+            mode: toSnapshotModeString(requireSnapshotField(entry, "mode")),
+            uid: requireSnapshotField(entry, "uid"),
+            gid: requireSnapshotField(entry, "gid"),
         };
         if (entry.kind === "file") {
             return {
                 ...baseEntry,
-                content: entry.content ?? "",
-                encoding: entry.encoding ?? "utf8",
+                content: requireSnapshotField(entry, "content"),
+                encoding: requireSnapshotField(entry, "encoding"),
             };
         }
         if (entry.kind === "symlink") {
-            if (entry.target === undefined) {
-                throw new Error(`sidecar root snapshot for ${entry.path} is missing a symlink target`);
-            }
             return {
                 ...baseEntry,
-                target: entry.target,
+                target: requireSnapshotField(entry, "target"),
             };
         }
         return baseEntry;
     });
 }
-function ensureNativeSidecarBinary() {
-    // A published install has no in-repo Cargo workspace to build from: resolve
-    // the prebuilt platform binary (or the AGENTOS_SIDECAR_BIN override).
-    if (process.env.AGENTOS_SIDECAR_BIN ||
-        !existsSync(join(REPO_ROOT, "Cargo.toml"))) {
-        return resolvePublishedSidecarBinary();
-    }
-    if (ensuredSidecarBinary &&
-        existsSync(ensuredSidecarBinary) &&
-        !sidecarBinaryNeedsBuild()) {
-        return ensuredSidecarBinary;
-    }
-    if (sidecarBinaryNeedsBuild()) {
-        const cargoBinary = findCargoBinary();
-        if (cargoBinary) {
-            execFileSync(cargoBinary, ["build", "-q", "-p", "agentos-sidecar"], {
-                cwd: REPO_ROOT,
-                stdio: "pipe",
-            });
-        }
-        else if (!existsSync(SIDECAR_BINARY)) {
-            execFileSync(resolveCargoBinary(), ["build", "-q", "-p", "agentos-sidecar"], {
-                cwd: REPO_ROOT,
-                stdio: "pipe",
-            });
-        }
-    }
-    ensuredSidecarBinary = SIDECAR_BINARY;
-    return ensuredSidecarBinary;
-}
-function sidecarBinaryNeedsBuild() {
-    if (!existsSync(SIDECAR_BINARY)) {
-        return true;
-    }
-    const binaryMtimeMs = statSync(SIDECAR_BINARY).mtimeMs;
-    return SIDECAR_BUILD_INPUTS.some((path) => existsSync(path) && latestMtimeMs(path) > binaryMtimeMs);
-}
-function latestMtimeMs(path) {
-    const stats = statSync(path);
-    if (!stats.isDirectory()) {
-        return stats.mtimeMs;
-    }
-    let latest = stats.mtimeMs;
-    for (const entry of readdirSync(path)) {
-        latest = Math.max(latest, latestMtimeMs(join(path, entry)));
-    }
-    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 [];
@@ -743,7 +192,7 @@ async function resolveCompatLocalMounts(mounts) {
             resolved.push({
                 path: posixPath.normalize(mount.path),
                 fs: mount.driver,
-                readOnly: mount.readOnly ?? false,
+                readOnly: mount.readOnly,
             });
             continue;
         }
@@ -760,15 +209,13 @@ async function resolveCompatLocalMounts(mounts) {
         resolved.push({
             path: posixPath.normalize(mount.path),
             fs,
-            readOnly: mode === "read-only",
+            readOnly: mount.filesystem.mode === undefined ? undefined : mode === "read-only",
         });
     }
     return resolved;
 }
 function collectSidecarMountPlan(options) {
     const sidecarMounts = [];
-    const hostMounts = [];
-    const hostPathMappings = [];
     const seenMounts = new Set();
     function pushMount(mount) {
         const serialized = serializeMountConfigForSidecar(mount);
@@ -778,77 +225,26 @@ function collectSidecarMountPlan(options) {
         }
         seenMounts.add(key);
         sidecarMounts.push(serialized);
-        if (mount.plugin.id === "host_dir") {
-            const config = getHostDirMountPluginConfig(mount.plugin.config);
-            if (config) {
-                hostPathMappings.push({
-                    vmPath: posixPath.normalize(mount.path),
-                    hostPath: resolveHostPath(config.hostPath),
-                    readOnly: mount.readOnly ?? config.readOnly ?? true,
-                });
-            }
-            if (config && options.mounts?.some((candidate) => candidate === mount)) {
-                hostMounts.push({
-                    vmPath: posixPath.normalize(mount.path),
-                    hostPath: resolveHostPath(config.hostPath),
-                    readOnly: mount.readOnly ?? config.readOnly ?? true,
-                });
-            }
-        }
     }
     for (const mount of options.mounts ?? []) {
         if (!isNativeMountConfig(mount)) {
+            const readOnly = isOverlayMountConfig(mount)
+                ? mount.filesystem.mode === undefined
+                    ? undefined
+                    : mount.filesystem.mode === "read-only"
+                : mount.readOnly;
+            sidecarMounts.push({
+                guestPath: mount.path,
+                ...(readOnly === undefined ? {} : { readOnly }),
+                plugin: {
+                    id: "js_bridge",
+                },
+            });
             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) {
-        return [];
-    }
-    return ["agentos", ...toolKits.map((toolKit) => `agentos-${toolKit.name}`)];
+    return { sidecarMounts };
 }
 function validationMessage(error) {
     if (typeof error === "object" &&
@@ -866,6 +262,29 @@ function validationMessage(error) {
     }
     return error instanceof Error ? error.message : String(error);
 }
+function requireVmFetchResponsePayload(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("sidecar vm.fetch response must be an object");
+    }
+    const payload = value;
+    if (!Number.isInteger(payload.status)) {
+        throw new Error("sidecar vm.fetch response is missing numeric status");
+    }
+    if (typeof payload.statusText !== "string") {
+        throw new Error("sidecar vm.fetch response is missing statusText");
+    }
+    if (!Array.isArray(payload.headers) ||
+        payload.headers.some((entry) => !Array.isArray(entry) ||
+            entry.length !== 2 ||
+            typeof entry[0] !== "string" ||
+            typeof entry[1] !== "string")) {
+        throw new Error("sidecar vm.fetch response is missing valid headers");
+    }
+    if (typeof payload.body !== "string") {
+        throw new Error("sidecar vm.fetch response is missing base64 body");
+    }
+    return payload;
+}
 function toolToSidecarDefinition(tool) {
     return {
         description: tool.description,
@@ -881,126 +300,6 @@ function toolToSidecarDefinition(tool) {
             : {}),
     };
 }
-function combineInstructions(additionalInstructions, toolReference) {
-    const parts = [additionalInstructions, toolReference]
-        .map((part) => part?.trim())
-        .filter((part) => Boolean(part));
-    if (parts.length === 0) {
-        return null;
-    }
-    return parts.join("\n\n");
-}
-function buildHostToolReference(toolKits) {
-    if (toolKits.length === 0) {
-        return "";
-    }
-    const lines = [
-        "## Available Host Tools",
-        "",
-        "Run `agentos list-tools` to see all available tools.",
-        "",
-    ];
-    for (const toolKit of toolKits) {
-        lines.push(`### ${toolKit.name}`);
-        lines.push("");
-        lines.push(toolKit.description);
-        lines.push("");
-        for (const [toolName, tool] of Object.entries(toolKit.tools)) {
-            const sidecarTool = toolToSidecarDefinition(tool);
-            const signature = buildToolFlagSignature(sidecarTool.inputSchema);
-            const suffix = signature.length > 0 ? ` ${signature}` : "";
-            lines.push(`- \`agentos-${toolKit.name} ${toolName}${suffix}\` — ${tool.description}`);
-        }
-        lines.push("");
-        const toolsWithExamples = Object.entries(toolKit.tools).filter(([, tool]) => tool.examples && tool.examples.length > 0);
-        if (toolsWithExamples.length > 0) {
-            lines.push("**Examples:**");
-            lines.push("");
-            for (const [toolName, tool] of toolsWithExamples) {
-                for (const example of tool.examples ?? []) {
-                    const args = inputToToolFlags(example.input);
-                    const suffix = args.length > 0 ? ` ${args}` : "";
-                    lines.push(`- ${example.description}: \`agentos-${toolKit.name} ${toolName}${suffix}\``);
-                }
-            }
-            lines.push("");
-        }
-        lines.push(`Run \`agentos-${toolKit.name} <tool> --help\` for details.`);
-        lines.push("");
-    }
-    return lines.join("\n");
-}
-function buildToolFlagSignature(schema) {
-    return describeToolFlags(schema)
-        .map((flag) => {
-        if (flag.required) {
-            return `${flag.name} <${flag.type}>`;
-        }
-        return `[${flag.name} <${flag.type}>]`;
-    })
-        .join(" ");
-}
-function describeToolFlags(schema) {
-    const schemaObject = asRecord(schema);
-    const properties = asRecord(schemaObject.properties);
-    const required = Array.isArray(schemaObject.required)
-        ? new Set(schemaObject.required.filter((item) => typeof item === "string"))
-        : new Set();
-    return Object.entries(properties).map(([fieldName, fieldSchema]) => ({
-        name: `--${camelToKebab(fieldName)}`,
-        type: describeToolFlagType(fieldSchema),
-        required: required.has(fieldName),
-    }));
-}
-function describeToolFlagType(schema) {
-    const schemaObject = asRecord(schema);
-    const type = typeof schemaObject.type === "string" ? schemaObject.type : undefined;
-    if (type === "array") {
-        const itemType = describeJsonSchemaScalarType(schemaObject.items);
-        return `${itemType}[]`;
-    }
-    if (type === "string") {
-        const enumValues = Array.isArray(schemaObject.enum)
-            ? schemaObject.enum.filter((item) => typeof item === "string")
-            : [];
-        return enumValues.length > 0 ? enumValues.join("|") : "string";
-    }
-    return type ?? "string";
-}
-function describeJsonSchemaScalarType(schema) {
-    const schemaObject = asRecord(schema);
-    return typeof schemaObject.type === "string" ? schemaObject.type : "string";
-}
-function inputToToolFlags(input) {
-    const inputObject = asRecord(input);
-    return Object.entries(inputObject)
-        .flatMap(([key, value]) => {
-        const flag = `--${camelToKebab(key)}`;
-        if (value === true) {
-            return [flag];
-        }
-        if (value === false) {
-            return [`--no-${camelToKebab(key)}`];
-        }
-        if (Array.isArray(value)) {
-            return value.map((item) => `${flag} ${toolCliString(item)}`);
-        }
-        return [`${flag} ${toolCliString(value)}`];
-    })
-        .join(" ");
-}
-function toolCliString(value) {
-    return typeof value === "string" ? value : (JSON.stringify(value) ?? "null");
-}
-function camelToKebab(value) {
-    return value.replace(/[A-Z]/g, (ch, index) => `${index > 0 ? "-" : ""}${ch.toLowerCase()}`);
-}
-function asRecord(value) {
-    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-        return value;
-    }
-    return {};
-}
 async function handleHostCallback(request, context) {
     const payload = request.payload;
     if (payload.type !== "host_callback") {
@@ -1010,23 +309,6 @@ async function handleHostCallback(request, context) {
             error: `unsupported sidecar request type: ${payload.type}`,
         };
     }
-    const command = parseHostCommandCallbackInput(payload.input);
-    if (command) {
-        try {
-            return {
-                type: "host_callback_result",
-                invocation_id: payload.invocation_id,
-                result: await handleHostCommandCallback(command, context),
-            };
-        }
-        catch (error) {
-            return {
-                type: "host_callback_result",
-                invocation_id: payload.invocation_id,
-                error: validationMessage(error),
-            };
-        }
-    }
     const tool = context.toolMap.get(payload.callback_key);
     if (!tool) {
         return {
@@ -1035,14 +317,6 @@ async function handleHostCallback(request, context) {
             error: `Unknown tool "${payload.callback_key}"`,
         };
     }
-    const permissionMode = toolPermissionMode(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}`,
-        };
-    }
     const parsed = tool.inputSchema.safeParse(payload.input);
     if (!parsed.success) {
         return {
@@ -1055,7 +329,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 tool.execute(parsed.data),
         };
     }
     catch (error) {
@@ -1075,348 +349,186 @@ function buildToolMap(toolKits) {
     }
     return toolMap;
 }
-function parseHostCommandCallbackInput(input) {
-    const value = asRecord(input);
-    if (value.type !== "command" ||
-        typeof value.command !== "string" ||
-        typeof value.cwd !== "string" ||
-        !Array.isArray(value.args) ||
-        !value.args.every((arg) => typeof arg === "string")) {
-        return null;
-    }
-    return {
-        type: "command",
-        command: value.command,
-        args: value.args,
-        cwd: value.cwd,
-    };
+function bridgeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-async function handleHostCommandCallback(command, context) {
-    const directToolKit = context.toolKits.find((toolKit) => `agentos-${toolKit.name}` === command.command);
-    if (command.command === "agentos") {
-        return handleAgentOsRegistryCommand(command, context);
-    }
-    if (directToolKit) {
-        return handleAgentOsToolkitCommand(command, context, directToolKit);
+function toBridgeArgs(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("js_bridge args must be an object");
     }
-    throw new Error(`Unknown host callback command "${command.command}"`);
+    return value;
 }
-async function handleAgentOsRegistryCommand(command, context) {
-    const [subcommand, toolkitName, toolName, ...toolArgs] = command.args;
-    if (!subcommand || isHelpFlag(subcommand)) {
-        return {
-            usage: "agentos <command>: list-tools [toolkit], <toolkit> --help, or <toolkit> <tool> ...",
-        };
-    }
-    if (subcommand === "list-tools") {
-        return toolkitName
-            ? describeToolkitPayload(context.toolKits, toolkitName)
-            : listToolkitsPayload(context.toolKits);
+function bridgePath(mountId, value) {
+    if (!mountId.startsWith("/")) {
+        throw new Error(`Unsupported js_bridge mount id: ${mountId}`);
     }
-    const toolKit = context.toolKits.find((kit) => kit.name === subcommand);
-    if (!toolKit) {
-        throw new Error(`No toolkit "${subcommand}". Available: ${toolkitNames(context.toolKits)}`);
+    if (typeof value !== "string") {
+        throw new Error("js_bridge path argument must be a string");
     }
-    if (!toolkitName || isHelpFlag(toolkitName)) {
-        return describeToolkitPayload(context.toolKits, subcommand);
-    }
-    if (toolName && isHelpFlag(toolName)) {
-        return describeToolPayload(toolKit, toolkitName);
-    }
-    return invokeHostTool({
-        toolKit,
-        toolName: toolkitName,
-        args: [toolName, ...toolArgs].filter((value) => typeof value === "string"),
-        cwd: command.cwd,
-        context,
-    });
+    return posixPath.normalize(posixPath.join(mountId, value));
 }
-async function handleAgentOsToolkitCommand(command, context, toolKit) {
-    const [toolName, helpOrFirstArg, ...rest] = command.args;
-    if (!toolName || isHelpFlag(toolName)) {
-        return describeToolkitPayload(context.toolKits, toolKit.name);
-    }
-    if (helpOrFirstArg && isHelpFlag(helpOrFirstArg)) {
-        return describeToolPayload(toolKit, toolName);
-    }
-    return invokeHostTool({
-        toolKit,
-        toolName,
-        args: [helpOrFirstArg, ...rest].filter((value) => typeof value === "string"),
-        cwd: command.cwd,
-        context,
-    });
+function requireBridgeNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`js_bridge args.${field} must be a number`);
+    }
+    return value;
 }
-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)}`);
+function decodeBridgeBytes(value, field) {
+    if (typeof value === "string") {
+        return new Uint8Array(Buffer.from(value, "base64"));
     }
-    const callbackKey = `${toolKit.name}:${toolName}`;
-    const permissionMode = toolPermissionMode(context.permissions, callbackKey);
-    if (permissionMode !== "allow") {
-        throw new Error(`EACCES: blocked by tool.invoke policy for ${callbackKey}`);
+    if (Array.isArray(value) &&
+        value.every((entry) => Number.isInteger(entry) && entry >= 0 && entry <= 255)) {
+        return new Uint8Array(value);
     }
-    const input = await parseHostToolInput(tool, args, cwd, context.readFile);
-    return executeHostTool(tool, callbackKey, input);
+    throw new Error(`js_bridge args.${field} must be base64 bytes`);
 }
-async function executeHostTool(tool, callbackKey, input) {
-    const parsed = tool.inputSchema.safeParse(input);
-    if (!parsed.success) {
-        throw new Error(validationMessage(parsed.error));
-    }
-    return Promise.race([
-        Promise.resolve(tool.execute(parsed.data)),
-        new Promise((_, reject) => {
-            if (tool.timeout === undefined) {
-                return;
-            }
-            setTimeout(() => reject(new Error(`Tool "${callbackKey}" timed out after ${tool.timeout}ms`)), tool.timeout);
-        }),
-    ]);
-}
-async function parseHostToolInput(tool, args, cwd, readFile) {
-    if (args[0] === "--json") {
-        const value = args[1];
-        if (value === undefined) {
-            throw new Error("Flag --json requires a value");
-        }
-        return JSON.parse(value);
-    }
-    if (args[0] === "--json-file") {
-        const value = args[1];
-        if (value === undefined) {
-            throw new Error("Flag --json-file requires a value");
-        }
-        const guestPath = value.startsWith("/")
-            ? posixPath.normalize(value)
-            : posixPath.normalize(`${cwd}/${value}`);
-        const text = new TextDecoder().decode(await readFile(guestPath));
-        return JSON.parse(text);
-    }
-    return parseToolArgv(toolToSidecarDefinition(tool).inputSchema, args);
-}
-function parseToolArgv(schema, argv) {
-    const schemaObject = asRecord(schema);
-    const properties = asRecord(schemaObject.properties);
-    const required = Array.isArray(schemaObject.required)
-        ? new Set(schemaObject.required.filter((value) => typeof value === "string"))
-        : new Set();
-    const flagToField = new Map();
-    for (const [fieldName, fieldSchema] of Object.entries(properties)) {
-        flagToField.set(camelToKebab(fieldName), [fieldName, fieldSchema]);
-    }
-    const input = {};
-    for (let index = 0; index < argv.length;) {
-        const arg = argv[index];
-        if (!arg?.startsWith("--")) {
-            throw new Error(`Unexpected positional argument: "${arg}"`);
-        }
-        const rawFlag = arg.slice(2);
-        const negated = rawFlag.startsWith("no-");
-        const flagName = negated ? rawFlag.slice(3) : rawFlag;
-        const entry = flagToField.get(flagName);
-        if (!entry) {
-            throw new Error(`Unknown flag: --${rawFlag}`);
-        }
-        const [fieldName, fieldSchema] = entry;
-        const fieldType = jsonSchemaType(fieldSchema);
-        if (negated) {
-            if (fieldType !== "boolean") {
-                throw new Error(`Unknown flag: --${rawFlag}`);
-            }
-            input[fieldName] = false;
-            index += 1;
-            continue;
-        }
-        if (fieldType === "boolean") {
-            input[fieldName] = true;
-            index += 1;
-            continue;
-        }
-        const value = argv[index + 1];
-        if (value === undefined) {
-            throw new Error(`Flag --${rawFlag} requires a value`);
-        }
-        if (fieldType === "number" || fieldType === "integer") {
-            const number = Number(value);
-            if (!Number.isFinite(number)) {
-                throw new Error(`Flag --${rawFlag} expects a number, got "${value}"`);
+async function handleJsBridgeCall(request, context) {
+    try {
+        const args = toBridgeArgs(request.args);
+        const target = context.resolveTarget(request.mount_id);
+        if (!target) {
+            throw new Error(`Unknown js_bridge mount id: ${request.mount_id}`);
+        }
+        const fs = target.filesystem;
+        const path = () => bridgePath(target.rootPath, 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(target.rootPath, args.oldPath), bridgePath(target.rootPath, 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(target.rootPath, args.linkPath));
+                break;
             }
-            input[fieldName] = number;
-            index += 2;
-            continue;
-        }
-        if (fieldType === "array") {
-            const current = Array.isArray(input[fieldName])
-                ? input[fieldName]
-                : [];
-            const itemSchema = asRecord(fieldSchema).items;
-            const itemType = jsonSchemaType(itemSchema);
-            current.push(itemType === "number" || itemType === "integer" ? Number(value) : value);
-            input[fieldName] = current;
-            index += 2;
-            continue;
-        }
-        input[fieldName] = value;
-        index += 2;
-    }
-    for (const fieldName of required) {
-        if (!(fieldName in input)) {
-            throw new Error(`Missing required flag: --${camelToKebab(fieldName)}`);
+            case "readlink":
+                result = await fs.readlink(path());
+                break;
+            case "lstat":
+                result = await fs.lstat(path());
+                break;
+            case "link":
+                await fs.link(bridgePath(target.rootPath, args.oldPath), bridgePath(target.rootPath, 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"));
+                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 }),
+        };
     }
-    return input;
-}
-function listToolkitsPayload(toolKits) {
-    return {
-        toolkits: toolKits.map((toolKit) => ({
-            name: toolKit.name,
-            description: toolKit.description,
-            tools: Object.keys(toolKit.tools),
-        })),
-    };
-}
-function describeToolkitPayload(toolKits, toolkitName) {
-    const toolKit = toolKits.find((kit) => kit.name === toolkitName);
-    if (!toolKit) {
-        throw new Error(`No toolkit "${toolkitName}". Available: ${toolkitNames(toolKits)}`);
-    }
-    return {
-        name: toolKit.name,
-        description: toolKit.description,
-        tools: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
-            toolName,
-            {
-                description: tool.description,
-                flags: describeToolFlags(toolToSidecarDefinition(tool).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)}`);
-    }
-    return {
-        toolkit: toolKit.name,
-        tool: toolName,
-        description: tool.description,
-        flags: describeToolFlags(toolToSidecarDefinition(tool).inputSchema),
-        examples: tool.examples?.map((example) => ({
-            description: example.description,
-            input: example.input,
-        })) ?? [],
-    };
-}
-function toolPermissionMode(permissions, callbackKey) {
-    const scope = permissions.tool;
-    if (!scope) {
-        return "deny";
-    }
-    if (typeof scope === "string") {
-        return scope;
-    }
-    let mode = scope.default ?? "deny";
-    for (const rule of scope.rules) {
-        const operations = rule.operations ?? ["*"];
-        const patterns = rule.patterns ?? ["**"];
-        if (operations.some((operation) => operation === "*" || operation === "invoke") &&
-            patterns.some((pattern) => permissionPatternMatches(pattern, callbackKey))) {
-            mode = rule.mode;
-        }
+    catch (error) {
+        return {
+            type: "js_bridge_result",
+            call_id: request.call_id,
+            error: bridgeErrorMessage(error),
+        };
     }
-    return mode;
-}
-function permissionPatternMatches(pattern, value) {
-    if (pattern === "*" || pattern === "**" || pattern === value) {
-        return true;
-    }
-    const parts = pattern.split(/(\*\*|\*)/u);
-    const source = parts
-        .map((part) => {
-        if (part === "**")
-            return ".*";
-        if (part === "*")
-            return "[^:]*";
-        return part.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-    })
-        .join("");
-    return new RegExp(`^${source}$`).test(value);
 }
-function toolkitNames(toolKits) {
-    return toolKits.map((toolKit) => toolKit.name).join(", ");
-}
-function toolNames(toolKit) {
-    return Object.keys(toolKit.tools).join(", ");
-}
-function isHelpFlag(value) {
-    return value === "--help" || value === "-h";
-}
-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) {
-        return "";
-    }
-    for (const toolKit of toolKits) {
-        await client.registerHostCallbacks(session, vm, {
+function serializeToolkitsForSidecar(toolKits) {
+    return toolKits.map((toolKit) => {
+        return {
             name: toolKit.name,
             description: toolKit.description,
-            commandAliases: [`agentos-${toolKit.name}`],
-            registryCommandAliases: ["agentos"],
             callbacks: Object.fromEntries(Object.entries(toolKit.tools).map(([toolName, tool]) => [
                 toolName,
                 toolToSidecarDefinition(tool),
             ])),
-        });
-    }
-    return buildHostToolReference(toolKits);
+        };
+    });
 }
 export class AgentOs {
     #kernel;
     sidecar;
     _sessions = new Map();
-    _closedSessionIds = new BoundedSet(CLOSED_SESSION_ID_RETENTION_LIMIT);
-    _sessionClosePromises = new Map();
-    _pendingSessionRequestResolvers = new Map();
     _processes = new Map();
     _shells = new Map();
-    _closedShellIds = new BoundedSet(CLOSED_SHELL_ID_RETENTION_LIMIT);
-    _pendingShellExitPromises = new Set();
-    _shellCounter = 0;
-    _acpTerminals = new Map();
-    _acpTerminalCounter = 0;
-    _softwareRoots;
-    _softwareAgentConfigs;
+    _pendingShellExitPromises = new Map();
+    _disposed = false;
+    _disposePromise = null;
     _cronManager;
     _toolKits = [];
-    _toolReference = "";
-    _permissions = allowAll;
-    _hostMounts;
-    _env;
-    _rootFilesystem;
     _sidecarLease = null;
     _sidecarClient;
     _sidecarSession;
     _sidecarVm;
     _disposeSidecarEventListener;
-    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm) {
+    _disposeSidecarRequestHandler = null;
+    _agentStderrHandler;
+    _agentExitHandler;
+    _limitWarningHandler;
+    constructor(kernel, sidecar, 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);
+        }, {
+            scope: "vm",
+            connection_id: sidecarSession.connectionId,
+            session_id: sidecarSession.sessionId,
+            vm_id: sidecarVm.vmId,
         });
         agentOsRuntimeAdmins.set(this, {
             kernel,
@@ -1432,143 +544,145 @@ export class AgentOs {
         return getSharedAgentOsSidecarInternal(options);
     }
     static async create(options) {
+        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;
+        // callers or an upper package-manager layer must pass those packages in
+        // `software` before createSession(id). Unbuilt packages throw with build
+        // instructions; opt out via defaultSoftware: false.
+        const defaultSoftware = options?.defaultSoftware === false ? [] : resolveDefaultSoftware();
         const software = options?.defaultSoftware === false
             ? (options.software ?? [])
-            : [commonSoftware, ...(options?.software ?? [])];
-        const processed = processSoftware(software);
+            : [...defaultSoftware, ...(options?.software ?? [])];
+        // Packages are projected by the SIDECAR: the client forwards only the
+        // package `path` over `initializeVm` 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 (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);
-        }
+        // 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.
             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;
-                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,
+                let env = {};
+                const { sidecarMounts } = collectSidecarMountPlan({
+                    mounts: options?.mounts,
                 });
-                const session = await client.authenticateAndOpenSession();
-                const hostPermissions = options?.permissions ?? {
-                    ...allowAll,
-                    tool: "allow",
-                };
-                const sidecarPermissions = serializePermissionsForSidecar(hostPermissions);
+                // 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 sidecarPermissions = options?.permissions
+                    ? serializePermissionsForSidecar(options.permissions)
+                    : undefined;
                 const createVmConfig = {
-                    env,
-                    rootFilesystem: serializeRootFilesystemForSidecar(options?.rootFilesystem, bootstrapLower),
+                    ...(options?.rootFilesystem !== undefined
+                        ? {
+                            rootFilesystem: serializeRootFilesystemForSidecar(options.rootFilesystem),
+                        }
+                        : {}),
                     permissions: sidecarPermissions,
                     limits: options?.limits,
-                    loopbackExemptPorts: options?.loopbackExemptPorts ?? [],
+                    ...(options?.loopbackExemptPorts !== undefined
+                        ? { loopbackExemptPorts: options.loopbackExemptPorts }
+                        : {}),
                     // 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 }
+                                    : {}),
                             },
                         }
                         : {}),
+                    ...(options?.additionalInstructions === undefined
+                        ? {}
+                        : {
+                            agentAdditionalInstructions: options.additionalInstructions,
+                        }),
                 };
-                const nativeVm = await client.createVm(session, {
+                const nativeVm = await client.initializeVm(session, {
                     runtime: "java_script",
                     config: createVmConfig,
+                    ...(sidecarMounts.length > 0 ? { mounts: sidecarMounts } : {}),
+                    ...(sidecarPackages.length > 0 ? { packages: sidecarPackages } : {}),
+                    ...(toolKits === undefined || toolKits.length === 0
+                        ? {}
+                        : { hostCallbacks: serializeToolkitsForSidecar(toolKits) }),
                 });
-                await client.waitForEvent((event) => event.payload.type === "vm_lifecycle" &&
-                    event.payload.state === "ready", 10_000);
-                await client.configureVm(session, nativeVm, {
-                    mounts: sidecarMounts,
-                    permissions: sidecarPermissions,
-                    commandPermissions: processed.commandPermissions,
-                    loopbackExemptPorts: options?.loopbackExemptPorts,
-                });
-                if (toolKits && toolKits.length > 0) {
-                    toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, toolKits);
-                    commandGuestPaths.set("agentos", "/bin/agentos");
-                    for (const toolKit of toolKits) {
-                        commandGuestPaths.set(`agentos-${toolKit.name}`, `/bin/agentos-${toolKit.name}`);
-                    }
-                }
+                env = { ...nativeVm.guestEnv };
+                createdNativeVm = nativeVm;
                 rootBridge = new NativeSidecarKernelProxy({
                     client,
                     session,
                     vm: nativeVm,
-                    env,
-                    cwd: "/workspace",
+                    env: nativeVm.guestEnv,
+                    cwd: nativeVm.guestCwd,
                     localMounts,
-                    commandGuestPaths,
+                    sidecarMounts,
                     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);
                 kernel = rootBridge;
-                const snapshotClient = client;
                 return {
                     env,
-                    hostMounts,
                     kernel,
                     rootView: rootBridge.createRootView(),
+                    sidecarMounts,
                     sidecarClient: client,
                     sidecarSession: session,
                     sidecarVm: nativeVm,
-                    permissions: hostPermissions,
-                    snapshotRootFilesystem: async () => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm))),
                     toolKits: toolKits ?? [],
-                    toolReference,
                     async dispose() {
                         if (kernel) {
                             const currentKernel = kernel;
@@ -1586,37 +700,48 @@ 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(() => { });
+                    await kernel.dispose().catch((cleanupError) => {
+                        console.warn("failed to dispose kernel after VM startup failure", cleanupError);
+                    });
                 }
                 if (rootBridge) {
-                    await rootBridge.dispose().catch(() => { });
+                    await rootBridge.dispose().catch((cleanupError) => {
+                        console.warn("failed to dispose root bridge after VM startup failure", cleanupError);
+                    });
                 }
                 else {
-                    await client?.dispose().catch(() => { });
+                    if (createdNativeVm && nativeSession && client) {
+                        await client
+                            .disposeVm(nativeSession, createdNativeVm)
+                            .catch((cleanupError) => {
+                            console.warn("failed to dispose sidecar VM after startup failure", cleanupError);
+                        });
+                    }
                     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.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._permissions = vmAdmin.permissions;
             vm._installSidecarRequestHandler();
-            vm._cronManager = new CronManager(vm, options?.scheduleDriver ?? new TimerScheduleDriver());
+            vm._cronManager = new CronManager(vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm);
             return vm;
         }
         catch (error) {
-            await sidecarLease?.dispose().catch(() => { });
+            await sidecarLease?.dispose().catch((cleanupError) => {
+                console.warn("failed to dispose sidecar lease after AgentOs.create failure", cleanupError);
+            });
             throw error;
         }
     }
@@ -1627,23 +752,76 @@ export class AgentOs {
         const kernel = this.#kernel;
         return kernel.execArgv(command, args, options);
     }
-    _trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers) {
+    _pruneCompletedProcessRoutes() {
+        let completedRoutes = 0;
+        for (const entry of this._processes.values()) {
+            if (entry.state !== "running")
+                completedRoutes++;
+        }
+        let removeCount = Math.max(0, completedRoutes - this._sidecarVm.processRouteRetention);
+        for (const [pid, entry] of this._processes) {
+            if (removeCount === 0)
+                break;
+            if (entry.state !== "running") {
+                this._processes.delete(pid);
+                removeCount--;
+            }
+        }
+    }
+    async _trackProcess(proc, stdoutHandlers, stderrHandlers, exitHandlers) {
+        const existing = this._processes.get(proc.pid);
+        if (existing?.state === "running") {
+            const duplicateError = new Error(`Sidecar returned an already-active kernel pid: ${proc.pid}`);
+            try {
+                await proc.kill(9);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([duplicateError, cleanupError], "Sidecar returned a duplicate active pid and cleanup failed");
+            }
+            throw duplicateError;
+        }
+        this._processes.delete(proc.pid);
         const entry = {
+            state: "running",
             proc,
-            command,
-            args,
             stdoutHandlers,
             stderrHandlers,
             exitHandlers,
         };
         this._processes.set(proc.pid, entry);
-        void proc.wait().then((code) => {
-            for (const h of exitHandlers)
-                h(code);
+        void proc
+            .wait()
+            .then((code) => {
+            if (this._processes.get(proc.pid) !== entry)
+                return;
+            const handlers = [...exitHandlers];
+            stdoutHandlers.clear();
+            stderrHandlers.clear();
+            exitHandlers.clear();
+            this._processes.delete(proc.pid);
+            this._processes.set(proc.pid, { state: "exited", exitCode: code });
+            this._pruneCompletedProcessRoutes();
+            for (const handler of handlers)
+                handler(code);
+        })
+            .catch((error) => {
+            if (this._processes.get(proc.pid) === entry) {
+                const routeError = error instanceof Error ? error : new Error(String(error));
+                stdoutHandlers.clear();
+                stderrHandlers.clear();
+                exitHandlers.clear();
+                this._processes.delete(proc.pid);
+                this._processes.set(proc.pid, {
+                    state: "failed",
+                    error: routeError,
+                });
+                this._pruneCompletedProcessRoutes();
+            }
+            console.error(`[agent-os] process ${proc.pid} wait failed`, error);
         });
         return { pid: proc.pid };
     }
-    spawn(command, args, options) {
+    async spawn(command, args, options) {
         const stdoutHandlers = new Set();
         const stderrHandlers = new Set();
         const exitHandlers = new Set();
@@ -1652,7 +830,7 @@ export class AgentOs {
             stdoutHandlers.add(options.onStdout);
         if (options?.onStderr)
             stderrHandlers.add(options.onStderr);
-        const proc = this.#kernel.spawn(command, args, {
+        const proc = await this.#kernel.spawn(command, args, {
             ...options,
             onStdout: (data) => {
                 for (const h of stdoutHandlers)
@@ -1663,27 +841,39 @@ export class AgentOs {
                     h(data);
             },
         });
-        return this._trackProcess(proc, command, args, stdoutHandlers, stderrHandlers, exitHandlers);
+        return await this._trackProcess(proc, stdoutHandlers, stderrHandlers, 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);
+        if (entry.state === "exited")
+            return Promise.resolve();
+        if (entry.state === "failed")
+            return Promise.reject(entry.error);
+        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();
+        if (entry.state === "exited")
+            return Promise.resolve();
+        if (entry.state === "failed")
+            return Promise.reject(entry.error);
+        return 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}`);
+        if (entry.state === "exited")
+            return () => { };
+        if (entry.state === "failed")
+            throw entry.error;
         entry.stdoutHandlers.add(handler);
         return () => {
             entry.stdoutHandlers.delete(handler);
@@ -1694,6 +884,10 @@ export class AgentOs {
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
+        if (entry.state === "exited")
+            return () => { };
+        if (entry.state === "failed")
+            throw entry.error;
         entry.stderrHandlers.add(handler);
         return () => {
             entry.stderrHandlers.delete(handler);
@@ -1705,10 +899,12 @@ export class AgentOs {
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
         // If already exited, call immediately.
-        if (entry.proc.exitCode !== null) {
-            handler(entry.proc.exitCode);
+        if (entry.state === "exited") {
+            handler(entry.exitCode);
             return () => { };
         }
+        if (entry.state === "failed")
+            throw entry.error;
         entry.exitHandlers.add(handler);
         return () => {
             entry.exitHandlers.delete(handler);
@@ -1719,226 +915,68 @@ export class AgentOs {
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
+        if (entry.state === "exited")
+            return Promise.resolve(entry.exitCode);
+        if (entry.state === "failed")
+            return Promise.reject(entry.error);
         return entry.proc.wait();
     }
-    _assertSafeAbsolutePath(path) {
-        if (!path.startsWith("/")) {
-            throw new Error(`Path must be absolute: ${path}`);
-        }
-        if (posixPath.normalize(path) !== path) {
-            throw new Error(`Path must be normalized: ${path}`);
-        }
-    }
-    _assertWritableAbsolutePath(path) {
-        this._assertSafeAbsolutePath(path);
-        if (path === "/proc" || path.startsWith("/proc/")) {
-            throw new Error(`Path is read-only: ${path}`);
-        }
-    }
-    _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);
     }
     async writeFile(path, content) {
-        this._assertWritableAbsolutePath(path);
         return this.#kernel.writeFile(path, content);
     }
-    async writeFiles(entries) {
-        const results = [];
-        for (const entry of entries) {
-            try {
-                this._assertWritableAbsolutePath(entry.path);
-                // Create parent directories as needed
-                const parentDir = entry.path.substring(0, entry.path.lastIndexOf("/"));
-                if (parentDir) {
-                    await this._mkdirp(parentDir);
-                }
-                await this.#kernel.writeFile(entry.path, entry.content);
-                results.push({ path: entry.path, success: true });
-            }
-            catch (err) {
-                results.push({
-                    path: entry.path,
-                    success: false,
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            }
-        }
-        return results;
-    }
-    async readFiles(paths) {
-        const results = [];
-        for (const path of paths) {
-            try {
-                this._assertSafeAbsolutePath(path);
-                const content = await this.#kernel.readFile(path);
-                results.push({ path, content });
-            }
-            catch (err) {
-                results.push({
-                    path,
-                    content: null,
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            }
-        }
-        return results;
-    }
-    /** 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);
-            }
-        }
-    }
     async mkdir(path, options) {
-        if (options?.recursive) {
-            return this._mkdirp(path);
-        }
-        this._assertSafeAbsolutePath(path);
-        return this.#kernel.mkdir(path);
+        return this.#kernel.mkdir(path, options);
     }
     async readdir(path) {
-        this._assertSafeAbsolutePath(path);
         return this.#kernel.readdir(path);
     }
     async readdirRecursive(path, options) {
-        this._assertSafeAbsolutePath(path);
-        const maxDepth = options?.maxDepth;
-        const exclude = options?.exclude ? new Set(options.exclude) : undefined;
-        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,
-                    });
-                }
-            }
-        }
-        return results;
+        const entries = await this.#kernel.readdirRecursive(path, {
+            maxDepth: options?.maxDepth,
+        });
+        return entries.map((entry) => ({
+            path: entry.path,
+            type: entry.isSymbolicLink
+                ? "symlink"
+                : entry.isDirectory
+                    ? "directory"
+                    : "file",
+            size: entry.size,
+        }));
     }
     async stat(path) {
-        this._assertSafeAbsolutePath(path);
         return this.#kernel.stat(path);
     }
     async exists(path) {
-        this._assertSafeAbsolutePath(path);
         return this.#kernel.exists(path);
     }
     async snapshotRootFilesystem() {
-        const nativeSnapshot = this._sidecarLease?.admin.snapshotRootFilesystem;
-        if (nativeSnapshot) {
-            return nativeSnapshot();
-        }
-        return createSnapshotExport(await snapshotVirtualFilesystem(this._rootFilesystem));
+        return createSnapshotExport(convertSidecarRootSnapshotEntries(await this._sidecarClient.snapshotRootFilesystem(this._sidecarSession, this._sidecarVm)));
     }
-    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(path, driver, options) {
+        await this.#kernel.mountFs(path, driver, { readOnly: options?.readOnly });
     }
-    unmountFs(path) {
-        this._assertSafeAbsolutePath(path);
-        this.#kernel.unmountFs(path);
+    async unmountFs(path) {
+        await this.#kernel.unmountFs(path);
     }
     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 });
+        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);
+        await this.#kernel.removePath(path, options);
     }
     async fetch(port, request) {
         const url = new URL(request.url);
-        const responsePayload = JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
+        const responsePayload = requireVmFetchResponsePayload(JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
             port,
             method: request.method,
             path: `${url.pathname}${url.search}`,
@@ -1946,22 +984,21 @@ export class AgentOs {
             ...(request.method !== "GET" && request.method !== "HEAD"
                 ? { body: await request.text() }
                 : {}),
-        }));
+        })));
         const headers = new Headers();
-        for (const [key, value] of responsePayload.headers ?? []) {
+        for (const [key, value] of responsePayload.headers) {
             headers.append(key, value);
         }
-        return new Response(Buffer.from(responsePayload.body ?? "", "base64"), {
+        return new Response(Buffer.from(responsePayload.body, "base64"), {
             status: responsePayload.status,
             statusText: responsePayload.statusText,
             headers,
         });
     }
-    openShell(options) {
-        const shellId = `shell-${++this._shellCounter}`;
-        this._closedShellIds.delete(shellId);
+    async openShell(options) {
         const dataHandlers = new Set();
-        const handle = this.#kernel.openShell(options);
+        const handle = await this.#kernel.openShell(options);
+        const shellId = handle.processId;
         handle.onData = (data) => {
             for (const h of dataHandlers)
                 h(data);
@@ -1969,152 +1006,165 @@ export class AgentOs {
         const entry = {
             handle,
             dataHandlers,
-            exitPromise: Promise.resolve(),
+            exitPromise: Promise.resolve(0),
+            closing: false,
         };
-        const exitPromise = handle.wait().then(() => undefined, () => undefined);
-        entry.exitPromise = exitPromise.finally(() => {
-            this._pendingShellExitPromises.delete(entry.exitPromise);
+        const exitPromise = handle.wait();
+        const finalize = () => {
+            this._pendingShellExitPromises.delete(shellId);
             if (this._shells.get(shellId) === entry) {
                 this._shells.delete(shellId);
-                this._closedShellIds.add(shellId);
             }
+        };
+        entry.exitPromise = exitPromise.then((exitCode) => {
+            finalize();
+            return exitCode;
+        }, (error) => {
+            finalize();
+            throw error;
         });
-        this._pendingShellExitPromises.add(entry.exitPromise);
+        this._pendingShellExitPromises.set(shellId, entry.exitPromise);
         this._shells.set(shellId, entry);
         return { shellId };
     }
-    async connectTerminal(options) {
-        return this.#kernel.connectTerminal(options);
-    }
     /** Write data to a shell's PTY input. */
     writeShell(shellId, data) {
         const entry = this._shells.get(shellId);
-        if (!entry)
+        if (!entry || entry.closing)
             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. */
     onShellData(shellId, handler) {
         const entry = this._shells.get(shellId);
-        if (!entry)
+        if (!entry || entry.closing)
             throw new Error(`Shell not found: ${shellId}`);
         entry.dataHandlers.add(handler);
         return () => {
             entry.dataHandlers.delete(handler);
         };
     }
-    /** Notify a shell of terminal resize. */
-    resizeShell(shellId, cols, rows) {
+    /** Notify a shell of terminal resize and await the sidecar response. */
+    async resizeShell(shellId, cols, rows) {
         const entry = this._shells.get(shellId);
-        if (!entry)
+        if (!entry || entry.closing)
             throw new Error(`Shell not found: ${shellId}`);
-        entry.handle.resize(cols, rows);
+        await entry.handle.resize(cols, rows);
     }
-    /** Kill a shell process and remove it from tracking. */
-    closeShell(shellId) {
+    /**
+     * Wait for a shell to exit and return its sidecar-authoritative exit code.
+     * A late wait reads the retained sidecar process snapshot.
+     */
+    async waitShell(shellId) {
         const entry = this._shells.get(shellId);
-        if (!entry) {
-            if (this._closedShellIds.has(shellId)) {
-                return;
+        if (entry) {
+            return entry.exitPromise;
+        }
+        const pending = this._pendingShellExitPromises.get(shellId);
+        if (pending) {
+            return pending;
+        }
+        if (this.#kernel instanceof NativeSidecarKernelProxy) {
+            const process = await this.#kernel.processSnapshotById(shellId);
+            if (process?.status === "exited" && process.exitCode !== null) {
+                return process.exitCode;
             }
-            throw new Error(`Shell not found: ${shellId}`);
         }
-        entry.handle.kill();
-        this._shells.delete(shellId);
-        this._closedShellIds.add(shellId);
-    }
-    _resolveVmPathToHostPath(vmPath) {
-        const normalizedVmPath = posixPath.normalize(vmPath);
-        for (const mount of this._hostMounts) {
-            if (normalizedVmPath === mount.vmPath ||
-                normalizedVmPath.startsWith(`${mount.vmPath}/`)) {
-                const relativePath = posixPath.relative(mount.vmPath, normalizedVmPath);
-                if (!relativePath) {
-                    return mount.hostPath;
+        throw new Error(`Shell not found: ${shellId}`);
+    }
+    /** Kill a shell process, await the sidecar response, and remove it from tracking. */
+    async closeShell(shellId) {
+        const entry = this._shells.get(shellId);
+        if (!entry) {
+            if (this.#kernel instanceof NativeSidecarKernelProxy) {
+                const process = await this.#kernel.processSnapshotById(shellId);
+                if (process?.status === "exited") {
+                    return;
                 }
-                return join(mount.hostPath, ...relativePath.split("/").filter(Boolean));
             }
+            throw new Error(`Shell not found: ${shellId}`);
         }
-        return null;
+        if (entry.closing) {
+            return;
+        }
+        await entry.handle.kill();
+        entry.closing = true;
     }
-    /** Returns info about all processes spawned via spawn(). */
-    listProcesses() {
-        return [...this._processes.values()].map(({ proc, command, args }) => ({
-            pid: proc.pid,
-            command,
-            args,
-            running: proc.exitCode === null,
-            exitCode: proc.exitCode,
-        }));
+    /** Returns sidecar-authoritative info for processes spawned via spawn(). */
+    async listProcesses() {
+        const processByPid = new Map((await this.allProcesses()).map((process) => [process.pid, process]));
+        return [...this._processes.keys()].map((pid) => {
+            const process = processByPid.get(pid);
+            if (!process) {
+                throw new Error(`Sidecar process snapshot is missing tracked process: ${pid}`);
+            }
+            return {
+                pid: process.pid,
+                command: process.command,
+                args: process.args.slice(1),
+                running: process.status !== "exited",
+                exitCode: process.exitCode,
+            };
+        });
     }
     /** Returns all kernel processes across all active runtimes (WASM and Node). */
-    allProcesses() {
+    async allProcesses() {
         if (this.#kernel instanceof NativeSidecarKernelProxy) {
-            return this.#kernel.snapshotProcesses();
+            return await this.#kernel.snapshotProcesses();
         }
         return [...this.#kernel.processes.values()];
     }
-    /** Returns processes organized as a tree using ppid relationships. */
-    processTree() {
-        const all = this.allProcesses();
-        const nodeMap = new Map();
-        // Index: create a tree node for each process
-        for (const proc of all) {
-            nodeMap.set(proc.pid, { ...proc, children: [] });
-        }
-        // Wire: attach each node to its parent
-        const roots = [];
-        for (const node of nodeMap.values()) {
-            const parent = nodeMap.get(node.ppid);
-            if (parent) {
-                parent.children.push(node);
-            }
-            else {
-                roots.push(node);
-            }
-        }
-        return roots;
-    }
     /** Returns info about a specific process by PID. Throws if not found. */
-    getProcess(pid) {
-        const entry = this._processes.get(pid);
-        if (!entry) {
+    async getProcess(pid) {
+        if (!this._processes.has(pid)) {
             throw new Error(`Process not found: ${pid}`);
         }
+        const process = (await this.allProcesses()).find((candidate) => candidate.pid === pid);
+        if (!process) {
+            throw new Error(`Sidecar process snapshot is missing tracked process: ${pid}`);
+        }
         return {
-            pid: entry.proc.pid,
-            command: entry.command,
-            args: entry.args,
-            running: entry.proc.exitCode === null,
-            exitCode: entry.proc.exitCode,
+            pid: process.pid,
+            command: process.command,
+            args: process.args.slice(1),
+            running: process.status !== "exited",
+            exitCode: process.exitCode,
         };
     }
     /** Send SIGTERM to gracefully stop a process. No-op if already exited. */
-    stopProcess(pid) {
+    async stopProcess(pid) {
         const entry = this._processes.get(pid);
         if (!entry) {
             throw new Error(`Process not found: ${pid}`);
         }
-        if (entry.proc.exitCode !== null)
+        if (entry.state === "exited")
             return;
-        entry.proc.kill();
+        if (entry.state === "failed")
+            throw entry.error;
+        await entry.proc.kill();
     }
     /** Send SIGKILL to force-kill a process. No-op if already exited. */
-    killProcess(pid) {
+    async killProcess(pid) {
         const entry = this._processes.get(pid);
         if (!entry) {
             throw new Error(`Process not found: ${pid}`);
         }
-        if (entry.proc.exitCode !== null)
+        if (entry.state === "exited")
             return;
-        entry.proc.kill(9);
+        if (entry.state === "failed")
+            throw entry.error;
+        await 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,
-        }));
+    /** Returns the sidecar's authoritative active-session list. */
+    async listSessions() {
+        const response = await this._sendAcpRequest({
+            tag: "AcpListSessionsRequest",
+            val: { reserved: false },
+        });
+        if (response.tag !== "AcpListSessionsResponse") {
+            throw new Error(`unexpected response to AcpListSessionsRequest: ${response.tag}`);
+        }
+        return response.val.sessions.map((session) => ({ ...session }));
     }
     /** Internal helper: retrieve a session or throw. */
     _requireSession(sessionId) {
@@ -2124,87 +1174,49 @@ export class AgentOs {
         }
         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;
+    /**
+     * 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 `createSession(name)`. Persists for the VM's
+     * lifetime (and across a snapshot iff the volume persists).
+     */
+    async linkSoftware(descriptor) {
+        const ref = normalizePackageRef(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.
+        await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, { path: ref.path });
+        // 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
+        // createSession/listAgents from it). Nothing to record client-side.
+    }
+    async providedCommands() {
+        return this._sidecarClient.providedCommands(this._sidecarSession, this._sidecarVm);
+    }
+    /**
+     * 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,
+            adapterEntrypoint: agent.adapterEntrypoint,
+        }));
     }
     _recordSessionNotification(session, notification) {
-        this._applySessionUpdate(session, notification);
         if (shouldDispatchToSessionEventHandlers(notification)) {
             this._dispatchSessionEvent(session, notification);
         }
@@ -2235,8 +1247,8 @@ export class AgentOs {
             try {
                 subscriber.handler(notification);
             }
-            catch {
-                // Ignore subscriber callback failures and keep event delivery moving.
+            catch (error) {
+                console.warn(`ACP session event subscriber failed for ${session.sessionId}`, error);
             }
         }
     }
@@ -2249,961 +1261,492 @@ export class AgentOs {
             session.eventHandlers.delete(subscriber);
         };
     }
-    _applySyntheticConfigOverrides(session) {
-        if (session.configOverrides.size === 0) {
+    /**
+     * Warn once per session (host-visible) that a tool-permission request was
+     * auto-denied because no `onPermissionRequest` handler is registered. Shared
+     * by both the bare-callback and JSON-RPC permission paths so the message and
+     * the once-per-session guard cannot drift between them.
+     */
+    _warnNoPermissionHandlerOnce(session, params) {
+        if (session.warnedNoPermissionHandler) {
             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 };
-        });
+        session.warnedNoPermissionHandler = true;
+        this._emitSessionWarning(session, `agentos: a tool-permission request (${this._permissionToolLabel(params)}) was ` +
+            `auto-denied because no onPermissionRequest handler is registered for session ` +
+            `${session.sessionId}. Register one with vm.onPermissionRequest(sessionId, ...) and ` +
+            `reply via vm.respondPermission(...) to let the agent use tools.`);
     }
-    _handleSidecarEvent(event) {
-        if (event.payload.type === "ext") {
-            this._handleAcpExtEvent(event.payload.envelope);
-            return;
+    /** Best-effort human label for the tool named in a permission request. */
+    _permissionToolLabel(params) {
+        if (typeof params.toolName === "string") {
+            return params.toolName;
         }
-        if (event.payload.type !== "structured") {
-            return;
+        const toolCall = params.toolCall;
+        if (toolCall &&
+            typeof toolCall === "object" &&
+            typeof toolCall.title === "string") {
+            return toolCall.title;
         }
-        if (event.payload.name !== "acp.session_event") {
-            return;
-        }
-        const sessionId = event.payload.detail.session_id;
-        const session = sessionId ? this._sessions.get(sessionId) : undefined;
-        if (!session) {
-            return;
-        }
-        const notificationText = event.payload.detail.notification;
-        if (typeof notificationText !== "string") {
+        return "a tool";
+    }
+    /**
+     * Emit a host-visible warning for a session through the same agent-process log
+     * channel that surfaces adapter stderr (`onAgentStderr`, default: process
+     * stderr). Used for agent-os-owned diagnostics — e.g. a permission request
+     * that was auto-denied because no host hook is registered — so they never fire
+     * silently inside the sidecar.
+     */
+    _emitSessionWarning(session, message) {
+        const handler = this._agentStderrHandler;
+        if (!handler) {
             return;
         }
         try {
-            this._recordSessionNotification(session, toJsonRpcNotification(JSON.parse(notificationText)));
+            handler({
+                sessionId: session.sessionId,
+                agentType: session.agentType,
+                processId: session.processId,
+                pid: session.pid,
+                chunk: new TextEncoder().encode(`${message}\n`),
+            });
         }
-        catch {
-            // Ignore malformed event payloads from the sidecar.
+        catch (error) {
+            console.warn(`ACP warning handler failed for ${session.sessionId}`, error);
         }
     }
-    _handleAcpExtEvent(envelope) {
-        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
+    _recordAgentStderr(event) {
+        const session = this._sessions.get(event.sessionId);
+        const handler = this._agentStderrHandler;
+        if (!handler) {
             return;
         }
         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;
-                }
-            }
+            handler({
+                sessionId: event.sessionId,
+                agentType: event.agentType,
+                processId: event.processId,
+                pid: session?.pid ?? null,
+                chunk: new Uint8Array(event.chunk),
+            });
         }
-        catch {
-            // Ignore malformed event payloads from the sidecar.
+        catch (error) {
+            console.warn(`ACP stderr handler failed for ${event.sessionId}`, error);
         }
     }
-    _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,
-            },
-        };
-    }
-    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}`);
-        }
-        const response = decodeAcpResponse(envelope.payload);
-        if (response.tag === "AcpErrorResponse") {
-            const error = new Error(response.val.message);
-            error.code = response.val.code;
-            throw error;
+    _recordAgentExit(event) {
+        const session = this._sessions.get(event.sessionId);
+        const handler = this._agentExitHandler;
+        if (!handler) {
+            return;
         }
-        return response;
-    }
-    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);
-                }
+        try {
+            handler({
+                sessionId: event.sessionId,
+                agentType: event.agentType,
+                processId: event.processId,
+                pid: session?.pid ?? null,
+                exitCode: event.exitCode,
+                restart: event.restart,
+                restartCount: event.restartCount,
+                maxRestarts: event.maxRestarts,
             });
-        });
-        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);
-            }
         }
-        return response;
-    }
-    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);
+        catch (error) {
+            console.warn(`ACP exit handler failed for ${event.sessionId}`, error);
         }
-        const response = await this._sendSessionRequest(sessionId, "session/set_config_option", {
-            configId: option?.id ?? category,
-            value,
-        });
-        return response;
     }
-    _removeSession(sessionId) {
-        this._sessions.delete(sessionId);
-    }
-    _abortPendingSessionRequests(sessionId) {
-        const resolvers = this._pendingSessionRequestResolvers.get(sessionId);
-        if (!resolvers) {
+    _handleSidecarEvent(event) {
+        if (event.payload.type === "ext") {
+            this._handleAcpExtEvent(event.payload.envelope);
             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);
+        if (event.payload.type === "cron_dispatch") {
+            const dispatch = event.payload.dispatch;
+            this._cronManager.consumeDispatch({
+                alarm: {
+                    generation: dispatch.alarm.generation,
+                    ...(dispatch.alarm.next_alarm_ms === undefined
+                        ? {}
+                        : { nextAlarmMs: dispatch.alarm.next_alarm_ms }),
+                },
+                runs: dispatch.runs.map((run) => ({
+                    runId: run.run_id,
+                    jobId: run.job_id,
+                    action: run.action,
+                })),
+                events: dispatch.events.map((record) => ({
+                    kind: record.kind,
+                    jobId: record.job_id,
+                    timeMs: record.time_ms,
+                    ...(record.duration_ms === undefined
+                        ? {}
+                        : { durationMs: record.duration_ms }),
+                    ...(record.error === undefined ? {} : { error: record.error }),
+                })),
+            });
+            return;
         }
-    }
-    _cancelPendingPromptRequests(sessionId) {
-        const resolvers = this._pendingSessionRequestResolvers.get(sessionId);
-        if (!resolvers) {
-            return false;
+        if (event.payload.type !== "structured") {
+            return;
         }
-        const response = {
-            jsonrpc: "2.0",
-            id: null,
-            result: {
-                stopReason: "cancelled",
-            },
-        };
-        let cancelledPrompt = false;
-        for (const resolver of [...resolvers]) {
-            if (resolver.method !== "session/prompt") {
-                continue;
-            }
-            resolvers.delete(resolver);
-            resolver.resolve(response);
-            cancelledPrompt = true;
+        if (event.payload.name === "limit_warning") {
+            this._handleLimitWarning(event.payload.detail);
+            return;
         }
-        if (resolvers.size === 0) {
-            this._pendingSessionRequestResolvers.delete(sessionId);
+        if (event.payload.name !== "acp.session_event") {
+            return;
         }
-        return cancelledPrompt;
-    }
-    _rejectPendingPermissionReplies(sessionId) {
-        const session = this._sessions.get(sessionId);
+        const sessionId = event.payload.detail.session_id;
+        const session = sessionId ? this._sessions.get(sessionId) : undefined;
         if (!session) {
             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)) {
+        const notificationText = event.payload.detail.notification;
+        if (typeof notificationText !== "string") {
             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;
-    }
-    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 ?? "/workspace";
-        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"),
-            };
-        }
-        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 session = sessionEntryFromInit(created.sessionId, String(agentType), initData);
-        this._closedSessionIds.delete(created.sessionId);
-        this._sessions.set(created.sessionId, session);
         try {
-            await this._hydrateSessionState(session);
+            this._recordSessionNotification(session, toJsonRpcNotification(JSON.parse(notificationText)));
         }
         catch (error) {
-            this._removeSession(created.sessionId);
-            throw error;
+            console.warn("invalid ACP session event from sidecar", 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 ?? "/workspace";
-        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;
+        }
+        let warning;
+        try {
+            const requireString = (name) => {
+                const value = detail[name];
+                if (value === undefined) {
+                    throw new Error(`missing ${name}`);
+                }
+                return value;
+            };
+            const requireNumber = (name) => {
+                const value = Number(requireString(name));
+                if (!Number.isFinite(value)) {
+                    throw new Error(`invalid ${name}`);
+                }
+                return value;
+            };
+            warning = {
+                limit: requireString("limit"),
+                category: requireString("category"),
+                observed: requireNumber("observed"),
+                capacity: requireNumber("capacity"),
+                fillPercent: requireNumber("fillPercent"),
             };
         }
-        // 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}`);
+        catch (error) {
+            console.warn("invalid limit warning from sidecar", error);
+            return;
         }
-        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);
+            this._limitWarningHandler(warning);
         }
         catch (error) {
-            this._removeSession(liveSessionId);
-            throw error;
+            console.warn("limit warning handler failed", 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;
-            }
+    _handleAcpExtEvent(envelope) {
+        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
+            return;
         }
-        // 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().`);
+        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;
+                }
+                case "AcpAgentStderrEvent": {
+                    this._recordAgentStderr(event.val);
+                    return;
+                }
+                case "AcpAgentExitedEvent": {
+                    this._recordAgentExit(event.val);
+                    return;
+                }
             }
-            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];
-        }
-        if (!binEntry) {
-            throw new Error(`No bin entry found in ${packageName}/package.json`);
+        catch (error) {
+            console.warn("invalid ACP extension event from sidecar", error);
         }
-        return `${vmPrefix}/${binEntry}`;
     }
-    _installSidecarRequestHandler() {
-        const context = {
-            toolKits: this._toolKits,
-            toolMap: buildToolMap(this._toolKits),
-            permissions: this._permissions,
-            readFile: (path) => this.readFile(path),
-        };
-        this._sidecarClient.setSidecarRequestHandler((request) => {
-            switch (request.payload.type) {
-                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}`,
-                    });
-                case "ext":
-                    return this._handleAcpExtSidecarRequest(request.payload.envelope);
-            }
-        });
-    }
-    async _handleAcpExtSidecarRequest(envelope) {
+    _decodeAcpResponseEnvelope(envelope) {
         if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
-            return {
-                type: "ext_result",
-                envelope: {
-                    namespace: envelope.namespace,
-                    payload: Buffer.from("unknown extension namespace", "utf8"),
-                },
-            };
+            throw new Error(`unexpected ACP Ext namespace: ${envelope.namespace}`);
         }
-        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 {
-                    type: "ext_result",
-                    envelope: {
-                        namespace: ACP_EXTENSION_NAMESPACE,
-                        payload: encodeAcpCallbackResponse({
-                            tag: "AcpHostRequestCallbackResponse",
-                            val: {
-                                response: JSON.stringify(response),
-                            },
-                        }),
-                    },
-                };
-            }
+        const response = decodeAcpResponse(envelope.payload);
+        if (response.tag === "AcpErrorResponse") {
+            const error = new Error(response.val.message);
+            error.code = response.val.code;
+            throw error;
         }
+        return response;
     }
-    async _dispatchAcpSidecarRequest(request) {
-        try {
-            const result = await this._handleSupportedAcpSidecarRequest(request);
-            return {
-                jsonrpc: "2.0",
-                id: request.id,
-                result,
-            };
-        }
-        catch (error) {
-            if (error instanceof AcpDispatchError) {
-                return {
-                    jsonrpc: "2.0",
-                    id: request.id,
-                    error: {
-                        code: error.code,
-                        message: error.message,
-                        ...(error.data ? { data: error.data } : {}),
-                    },
-                };
-            }
-            return {
-                jsonrpc: "2.0",
-                id: request.id,
-                error: {
-                    code: -32603,
-                    message: error instanceof Error ? error.message : String(error),
+    async _sendAcpRequest(request, onResponse) {
+        let hookResponse;
+        const envelope = await this._sidecarClient.extensionRequest(this._sidecarSession, this._sidecarVm, {
+            namespace: ACP_EXTENSION_NAMESPACE,
+            payload: encodeAcpRequest(request),
+        }, onResponse
+            ? {
+                onResponse: (responseEnvelope) => {
+                    hookResponse =
+                        this._decodeAcpResponseEnvelope(responseEnvelope);
+                    onResponse(hookResponse);
                 },
-            };
+            }
+            : undefined);
+        if (hookResponse) {
+            return hookResponse;
         }
+        const response = this._decodeAcpResponseEnvelope(envelope);
+        onResponse?.(response);
+        return response;
     }
-    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);
-            case "fs/write":
-            case "fs/write_text_file":
-                return this._handleAcpWriteFile(params);
-            case "fs/readDir":
-            case "fs/read_dir":
-                return this._handleAcpReadDir(params);
-            case "terminal/create":
-                return this._handleAcpCreateTerminal(params);
-            case "terminal/write":
-                return this._handleAcpWriteTerminal(params);
-            case "terminal/output":
-            case "terminal/read":
-                return this._handleAcpReadTerminal(params);
-            case "terminal/wait_for_exit":
-            case "terminal/waitForExit":
-                return this._handleAcpWaitForTerminalExit(params);
-            case "terminal/kill":
-                return this._handleAcpKillTerminal(params);
-            case "terminal/release":
-            case "terminal/close":
-                return this._handleAcpReleaseTerminal(params);
-            case "terminal/resize":
-                return this._handleAcpResizeTerminal(params);
-            default:
-                throw new AcpDispatchError(-32601, `Method not found: ${request.method}`, {
-                    method: request.method,
-                });
-        }
+    async _sendSessionRequest(sessionId, method, params) {
+        return (await this._sendSessionRequestWithText(sessionId, method, params))
+            .response;
     }
-    _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)));
+    async _sendSessionRequestWithText(sessionId, method, params) {
+        const acpResponse = await this._sendAcpRequest({
+            tag: "AcpSessionRequest",
+            val: {
+                sessionId,
+                method,
+                params: params === undefined ? null : JSON.stringify(params),
+            },
         });
-        if (matched && typeof matched.optionId === "string") {
-            return matched.optionId;
-        }
-        if (reply === "always") {
-            return "allow_always";
-        }
-        if (reply === "once") {
-            return "allow_once";
+        if (acpResponse.tag !== "AcpSessionRpcResponse") {
+            throw new Error(`unexpected response to AcpSessionRequest: ${acpResponse.tag}`);
         }
-        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",
-                },
+            response: toJsonRpcResponse(JSON.parse(acpResponse.val.response)),
+            text: acpResponse.val.text,
         };
     }
-    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);
-            }
+    async _setSessionConfigByCategory(sessionId, category, value) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpSetSessionConfigRequest",
+            val: { sessionId, category, value },
         });
-        return this._buildAcpPermissionResult(reply, permissionParams);
-    }
-    _acpParams(request) {
-        if (!request.params) {
-            return {};
-        }
-        if (typeof request.params !== "object" ||
-            request.params === null ||
-            Array.isArray(request.params)) {
-            throw new AcpDispatchError(-32602, `${request.method} requires object params`);
+        if (response.tag !== "AcpSessionRpcResponse") {
+            throw new Error(`unexpected response to AcpSetSessionConfigRequest: ${response.tag}`);
         }
-        return request.params;
+        return toJsonRpcResponse(JSON.parse(response.val.response));
     }
-    _requireAcpStringParam(params, name, method) {
-        const value = params[name];
-        if (typeof value !== "string") {
-            throw new AcpDispatchError(-32602, `${method} requires a string ${name}`);
-        }
-        return value;
+    _removeSession(sessionId) {
+        this._sessions.delete(sessionId);
     }
-    _optionalAcpStringParam(params, name, method) {
-        const value = params[name];
-        if (value === undefined || value === null) {
-            return undefined;
-        }
-        if (typeof value !== "string") {
-            throw new AcpDispatchError(-32602, `${method} requires ${name} to be a string when provided`);
+    _rejectPendingPermissionReplies(sessionId) {
+        const session = this._sessions.get(sessionId);
+        if (!session) {
+            return;
         }
-        return value;
+        this._rejectPendingPermissionRepliesFromSession(session);
     }
-    _optionalAcpNumberParam(params, name, method) {
-        const value = params[name];
-        if (value === undefined || value === null) {
-            return undefined;
-        }
-        if (typeof value !== "number" || !Number.isFinite(value)) {
-            throw new AcpDispatchError(-32602, `${method} requires ${name} to be a number when provided`);
+    _rejectPendingPermissionRepliesFromSession(session) {
+        for (const [permissionId, pendingReply,] of session.pendingPermissionReplies) {
+            clearTimeout(pendingReply.cleanupTimer);
+            pendingReply.reject(new Error(`Session closed before permission reply: ${permissionId}`));
         }
-        return value;
+        session.pendingPermissionReplies.clear();
     }
-    _optionalAcpStringArrayParam(params, name, method) {
-        const value = params[name];
-        if (value === undefined || value === null) {
-            return undefined;
+    async _closeSessionInternal(sessionId) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpCloseSessionRequest",
+            val: { sessionId },
+        });
+        if (response.tag !== "AcpSessionClosedResponse") {
+            throw new Error(`unexpected response to AcpCloseSessionRequest: ${response.tag}`);
         }
-        if (!Array.isArray(value) ||
-            value.some((entry) => typeof entry !== "string")) {
-            throw new AcpDispatchError(-32602, `${method} requires ${name} to be an array of strings when provided`);
+        if (response.val.sessionId !== sessionId) {
+            throw new Error(`unexpected session id in AcpSessionClosedResponse: expected ${sessionId}, received ${response.val.sessionId}`);
         }
-        return [...value];
+        this._rejectPendingPermissionReplies(sessionId);
+        this._removeSession(sessionId);
     }
-    _optionalAcpEnvParam(params, name, method) {
-        const value = params[name];
-        if (value === undefined || value === null) {
-            return undefined;
-        }
-        if (Array.isArray(value)) {
-            const env = {};
-            for (const entry of value) {
-                if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-                    throw new AcpDispatchError(-32602, `${method} requires ${name} entries to be { name, value } objects`);
-                }
-                const record = entry;
-                if (typeof record.name !== "string" ||
-                    typeof record.value !== "string") {
-                    throw new AcpDispatchError(-32602, `${method} requires ${name} entries to be { name, value } objects`);
-                }
-                env[record.name] = record.value;
-            }
-            return env;
-        }
-        if (typeof value !== "object") {
-            throw new AcpDispatchError(-32602, `${method} requires ${name} to be an object or name/value array`);
-        }
-        const env = {};
-        for (const [key, entryValue] of Object.entries(value)) {
-            if (typeof entryValue !== "string") {
-                throw new AcpDispatchError(-32602, `${method} requires ${name} values to be strings`);
-            }
-            env[key] = entryValue;
+    async _getSessionState(sessionId) {
+        const response = await this._sendAcpRequest({
+            tag: "AcpGetSessionStateRequest",
+            val: { sessionId },
+        });
+        if (response.tag !== "AcpSessionStateResponse") {
+            throw new Error(`unexpected response to AcpGetSessionStateRequest: ${response.tag}`);
         }
-        return env;
+        return sidecarSessionStateFromAcp(response.val);
     }
-    _requireAcpTerminal(params, method) {
-        const terminalId = this._requireAcpStringParam(params, "terminalId", method);
-        const terminal = this._acpTerminals.get(terminalId);
-        if (!terminal) {
-            throw new AcpDispatchError(-32602, `ACP terminal not found: ${terminalId}`);
+    async createSession(agentType, options) {
+        // The client is npm-agnostic: it sends only the agent NAME. The sidecar
+        // resolves the name -> package -> entrypoint/env/launchArgs from the
+        // projected `/opt/agentos/<name>/current/agentos-package.json` and spawns
+        // (including the agent's static launch args and manifest env defaults).
+        // System-prompt assembly/injection (launch args / OPENCODE_CONTEXTPATHS) is
+        // owned by the sidecar; the host only forwards additionalInstructions /
+        // skipOsInstructions plus the caller's env.
+        const response = await this._sendAcpRequest({
+            tag: "AcpCreateSessionRequest",
+            val: {
+                agentType: String(agentType),
+                runtime: null,
+                args: null,
+                env: options?.env ? new Map(Object.entries(options.env)) : null,
+                cwd: options?.cwd ?? null,
+                mcpServers: options?.mcpServers
+                    ? JSON.stringify(options.mcpServers)
+                    : null,
+                protocolVersion: null,
+                clientCapabilities: null,
+                additionalInstructions: options?.additionalInstructions ?? null,
+                skipOsInstructions: options?.skipOsInstructions === true ? true : null,
+            },
+        }, (created) => {
+            if (created.tag !== "AcpSessionCreatedResponse") {
+                throw new Error(`unexpected create_session response: ${created.tag}`);
+            }
+            this._sessions.set(created.val.sessionId, sessionEntryFromRoute(created.val));
+        });
+        if (response.tag !== "AcpSessionCreatedResponse") {
+            throw new Error(`unexpected create_session response: ${response.tag}`);
         }
-        return terminal;
+        return { sessionId: response.val.sessionId };
     }
-    _appendAcpTerminalOutput(terminal, data) {
-        const chunk = Buffer.from(data).toString("utf8");
-        if (!chunk) {
-            return;
+    /**
+     * 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 locally only for host callbacks/events;
+     * authoritative state remains in the sidecar.
+     *
+     * 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) {
+        // The client is npm-agnostic: it sends only the agent NAME. The sidecar
+        // resolves the name -> package -> entrypoint/env/launchArgs from the
+        // projected manifest, exactly as createSession does.
+        const response = await this._sendAcpRequest({
+            tag: "AcpResumeSessionRequest",
+            val: {
+                sessionId,
+                agentType: String(agentType),
+                transcriptPath: options?.transcriptPath ?? null,
+                cwd: options?.cwd ?? null,
+                env: options?.env ? new Map(Object.entries(options.env)) : null,
+            },
+        }, (resumed) => {
+            if (resumed.tag !== "AcpSessionResumedResponse") {
+                throw new Error(`unexpected resume_session response: ${resumed.tag}`);
+            }
+            this._sessions.set(resumed.val.sessionId, sessionEntryFromRoute(resumed.val));
+        });
+        if (response.tag !== "AcpSessionResumedResponse") {
+            throw new Error(`unexpected resume_session response: ${response.tag}`);
         }
-        terminal.output += chunk;
-        if (Number.isFinite(terminal.outputByteLimit) &&
-            terminal.outputByteLimit >= 0 &&
-            terminal.output.length > terminal.outputByteLimit) {
-            terminal.output = terminal.output.slice(terminal.output.length - terminal.outputByteLimit);
-            terminal.truncated = true;
-        }
-    }
-    async _handleAcpReadFile(params) {
-        const method = "fs/read";
-        const path = this._requireAcpStringParam(params, "path", method);
-        const line = this._optionalAcpNumberParam(params, "line", method);
-        const limit = this._optionalAcpNumberParam(params, "limit", method);
-        const encoding = this._optionalAcpStringParam(params, "encoding", method);
-        const bytes = await this.readFile(path);
-        if (encoding === "base64") {
-            return { content: Buffer.from(bytes).toString("base64") };
-        }
-        const text = new TextDecoder().decode(bytes);
-        if (line === undefined && limit === undefined) {
-            return { content: text };
-        }
-        const startLine = Math.max(1, Math.trunc(line ?? 1));
-        const lineLimit = limit === undefined
-            ? Number.POSITIVE_INFINITY
-            : Math.max(0, Math.trunc(limit));
-        return {
-            content: text
-                .split("\n")
-                .slice(startLine - 1, startLine - 1 + lineLimit)
-                .join("\n"),
-        };
-    }
-    async _handleAcpWriteFile(params) {
-        const method = "fs/write";
-        const path = this._requireAcpStringParam(params, "path", method);
-        const content = this._requireAcpStringParam(params, "content", method);
-        const encoding = this._optionalAcpStringParam(params, "encoding", method);
-        await this.writeFile(path, encoding === "base64" ? Buffer.from(content, "base64") : content);
-        return null;
+        const { sessionId: liveSessionId, mode } = response.val;
+        return { sessionId: liveSessionId, mode };
     }
-    async _handleAcpReadDir(params) {
-        const method = "fs/readDir";
-        const path = this._requireAcpStringParam(params, "path", method);
-        const entries = await this._vfs().readDirWithTypes(path);
-        return {
-            entries: entries
-                .filter((entry) => entry.name !== "." && entry.name !== "..")
-                .map((entry) => ({
-                name: entry.name,
-                path: path === "/" ? `/${entry.name}` : `${path}/${entry.name}`,
-                type: entry.isSymbolicLink
-                    ? "symlink"
-                    : entry.isDirectory
-                        ? "directory"
-                        : "file",
-            })),
+    _installSidecarRequestHandler() {
+        const context = {
+            toolMap: buildToolMap(this._toolKits),
         };
+        this._disposeSidecarRequestHandler?.();
+        this._disposeSidecarRequestHandler =
+            this._sidecarClient.registerSidecarRequestHandler({
+                scope: "vm",
+                connection_id: this._sidecarSession.connectionId,
+                session_id: this._sidecarSession.sessionId,
+                vm_id: this._sidecarVm.vmId,
+            }, (request) => {
+                switch (request.payload.type) {
+                    case "host_callback":
+                        return handleHostCallback(request, context);
+                    case "js_bridge_call":
+                        return handleJsBridgeCall(request.payload, {
+                            resolveTarget: (mountId) => {
+                                const hostMountResolver = this.#kernel.hostFilesystemForMount;
+                                if (hostMountResolver) {
+                                    const filesystem = hostMountResolver.call(this.#kernel, mountId);
+                                    return filesystem
+                                        ? { filesystem, rootPath: "/" }
+                                        : undefined;
+                                }
+                                return { filesystem: this.#kernel.vfs, rootPath: mountId };
+                            },
+                        });
+                    case "ext":
+                        return this._handleAcpExtSidecarRequest(request.payload.envelope);
+                }
+            });
     }
-    _handleAcpCreateTerminal(params) {
-        const method = "terminal/create";
-        const command = this._requireAcpStringParam(params, "command", method);
-        const args = this._optionalAcpStringArrayParam(params, "args", method);
-        const env = this._optionalAcpEnvParam(params, "env", method);
-        const cwd = this._optionalAcpStringParam(params, "cwd", method);
-        const cols = this._optionalAcpNumberParam(params, "cols", method);
-        const rows = this._optionalAcpNumberParam(params, "rows", method);
-        const outputByteLimit = Math.max(0, Math.trunc(this._optionalAcpNumberParam(params, "outputByteLimit", method) ??
-            1_048_576));
-        const terminalId = `acp-terminal-${++this._acpTerminalCounter}`;
-        const terminal = {
-            handle: this.#kernel.openShell({
-                command,
-                ...(args ? { args } : {}),
-                ...(env ? { env } : {}),
-                ...(cwd ? { cwd } : {}),
-                ...(cols !== undefined ? { cols: Math.trunc(cols) } : {}),
-                ...(rows !== undefined ? { rows: Math.trunc(rows) } : {}),
-                onStderr: (data) => {
-                    this._appendAcpTerminalOutput(terminal, data);
+    async _handleAcpExtSidecarRequest(envelope) {
+        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
+            return {
+                type: "ext_result",
+                envelope: {
+                    namespace: envelope.namespace,
+                    payload: Buffer.from("unknown extension namespace", "utf8"),
                 },
-            }),
-            output: "",
-            truncated: false,
-            outputByteLimit,
-            exitCode: null,
-            waitPromise: Promise.resolve(0),
-        };
-        terminal.handle.onData = (data) => {
-            this._appendAcpTerminalOutput(terminal, data);
-        };
-        terminal.waitPromise = terminal.handle.wait().then((exitCode) => {
-            terminal.exitCode = exitCode;
-            return exitCode;
-        });
-        this._acpTerminals.set(terminalId, terminal);
-        return { terminalId };
-    }
-    _handleAcpWriteTerminal(params) {
-        const method = "terminal/write";
-        const terminal = this._requireAcpTerminal(params, method);
-        const data = this._requireAcpStringParam(params, "data", method);
-        const encoding = this._optionalAcpStringParam(params, "encoding", method);
-        terminal.handle.write(encoding === "base64" ? Buffer.from(data, "base64") : data);
-        return null;
-    }
-    _handleAcpReadTerminal(params) {
-        const terminal = this._requireAcpTerminal(params, "terminal/output");
+            };
+        }
+        const callback = decodeAcpCallback(envelope.payload);
+        if (callback.val.cleanupAfterMs > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new Error("ACP permission callback cleanup deadline exceeds JS range");
+        }
+        const reply = await this._handleAcpPermissionCallback(callback.val.sessionId, callback.val.permissionId, {
+            ...toRecord(JSON.parse(callback.val.params)),
+            _acpMethod: ACP_PERMISSION_METHOD,
+        }, Number(callback.val.cleanupAfterMs));
         return {
-            output: terminal.output,
-            truncated: terminal.truncated,
-            ...(terminal.exitCode !== null
-                ? {
-                    exitStatus: {
-                        exitCode: terminal.exitCode,
-                        signal: null,
+            type: "ext_result",
+            envelope: {
+                namespace: ACP_EXTENSION_NAMESPACE,
+                payload: encodeAcpCallbackResponse({
+                    tag: "AcpPermissionCallbackResponse",
+                    val: {
+                        permissionId: callback.val.permissionId,
+                        reply: reply ?? null,
                     },
-                }
-                : {}),
+                }),
+            },
         };
     }
-    async _handleAcpWaitForTerminalExit(params) {
-        const terminal = this._requireAcpTerminal(params, "terminal/wait_for_exit");
-        const exitCode = await terminal.waitPromise;
-        return { exitCode, signal: null };
-    }
-    _handleAcpKillTerminal(params) {
-        const method = "terminal/kill";
-        const terminal = this._requireAcpTerminal(params, method);
-        const signal = this._optionalAcpNumberParam(params, "signal", method) ?? 15;
-        terminal.handle.kill(Math.trunc(signal));
-        return null;
-    }
-    _handleAcpReleaseTerminal(params) {
-        const method = "terminal/release";
-        const terminalId = this._requireAcpStringParam(params, "terminalId", method);
-        const terminal = this._acpTerminals.get(terminalId);
-        if (!terminal) {
-            throw new AcpDispatchError(-32602, `ACP terminal not found: ${terminalId}`);
-        }
-        if (terminal.exitCode === null) {
-            terminal.handle.kill();
-        }
-        this._acpTerminals.delete(terminalId);
-        return null;
-    }
-    _handleAcpResizeTerminal(params) {
-        const method = "terminal/resize";
-        const terminal = this._requireAcpTerminal(params, method);
-        const cols = this._optionalAcpNumberParam(params, "cols", method);
-        const rows = this._optionalAcpNumberParam(params, "rows", method);
-        if (cols === undefined || rows === undefined) {
-            throw new AcpDispatchError(-32602, `${method} requires numeric cols and rows`);
-        }
-        terminal.handle.resize(Math.trunc(cols), Math.trunc(rows));
-        return null;
-    }
-    async _handleAcpPermissionCallback(sessionId, permissionId, params) {
+    async _handleAcpPermissionCallback(sessionId, permissionId, params, cleanupAfterMs) {
         const session = this._sessions.get(sessionId);
         if (!session) {
-            return "reject";
+            return undefined;
         }
         if (session.permissionHandlers.size === 0) {
-            return "reject";
+            // Surface the absent host route, then let the sidecar apply its ACP
+            // permission default. The client does not manufacture a policy answer.
+            this._warnNoPermissionHandlerOnce(session, params);
+            return undefined;
         }
         try {
             return await new Promise((resolve, reject) => {
-                const timer = setTimeout(() => {
+                const cleanupTimer = setTimeout(() => {
                     session.pendingPermissionReplies.delete(permissionId);
-                    reject(new Error(`Timed out waiting for permission reply: ${permissionId}`));
-                }, 120_000);
+                    reject(new Error(`Permission reply route expired after the sidecar deadline: ${permissionId}`));
+                }, cleanupAfterMs);
                 session.pendingPermissionReplies.set(permissionId, {
                     resolve,
                     reject,
-                    timer,
+                    cleanupTimer,
                 });
                 const permissionRequest = {
                     permissionId,
@@ -3217,111 +1760,42 @@ export class AgentOs {
                 }
             });
         }
-        catch {
-            return "reject";
+        catch (error) {
+            console.warn(`ACP permission callback route closed for ${sessionId}/${permissionId}; the sidecar owns the outcome`, error);
+            return undefined;
         }
     }
-    /**
-     * 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;
-                }
-            }
-        };
-        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();
+        const result = await this._sendSessionRequestWithText(sessionId, "session/prompt", {
+            prompt: [{ type: "text", text }],
+        });
+        if (result.text === null) {
+            throw new Error("sidecar prompt response is missing accumulated text");
         }
+        return { response: result.response, text: result.text };
     }
     /** 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;
+        return this._sendSessionRequest(sessionId, "session/cancel");
     }
-    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 closeSession(sessionId) {
+        await this._closeSessionInternal(sessionId);
     }
     async respondPermission(sessionId, permissionId, reply) {
-        const session = this._requireSession(sessionId);
-        const pendingReply = session.pendingPermissionReplies.get(permissionId);
+        const session = this._sessions.get(sessionId);
+        const pendingReply = session?.pendingPermissionReplies.get(permissionId);
         if (pendingReply) {
-            session.pendingPermissionReplies.delete(permissionId);
-            clearTimeout(pendingReply.timer);
+            session?.pendingPermissionReplies.delete(permissionId);
+            clearTimeout(pendingReply.cleanupTimer);
             pendingReply.resolve(reply);
             return {
                 jsonrpc: "2.0",
@@ -3333,18 +1807,15 @@ export class AgentOs {
                 },
             };
         }
-        return this._sendSessionRequest(sessionId, LEGACY_PERMISSION_METHOD, {
-            permissionId,
-            reply,
-        });
+        throw new Error(`Permission request is not pending: ${permissionId}`);
     }
     async setSessionMode(sessionId, modeId) {
         return this._sendSessionRequest(sessionId, "session/set_mode", {
             modeId,
         });
     }
-    getSessionModes(sessionId) {
-        return this._requireSession(sessionId).modes;
+    async getSessionModes(sessionId) {
+        return toSessionModes((await this._getSessionState(sessionId)).modes);
     }
     async setSessionModel(sessionId, model) {
         return this._setSessionConfigByCategory(sessionId, "model", model);
@@ -3352,15 +1823,15 @@ export class AgentOs {
     async setSessionThoughtLevel(sessionId, level) {
         return this._setSessionConfigByCategory(sessionId, "thought_level", level);
     }
-    getSessionConfigOptions(sessionId) {
-        return [...this._requireSession(sessionId).configOptions];
+    async getSessionConfigOptions(sessionId) {
+        return toSessionConfigOptions((await this._getSessionState(sessionId)).configOptions);
     }
-    getSessionCapabilities(sessionId) {
-        const caps = this._requireSession(sessionId).capabilities;
+    async getSessionCapabilities(sessionId) {
+        const caps = toAgentCapabilities((await this._getSessionState(sessionId)).agentCapabilities);
         return Object.keys(caps).length > 0 ? caps : null;
     }
-    getSessionAgentInfo(sessionId) {
-        return this._requireSession(sessionId).agentInfo;
+    async getSessionAgentInfo(sessionId) {
+        return toAgentInfo((await this._getSessionState(sessionId)).agentInfo);
     }
     async rawSessionSend(sessionId, method, params) {
         return this._sendSessionRequest(sessionId, method, params);
@@ -3381,45 +1852,79 @@ export class AgentOs {
     }
     // ── Cron ────────────────────────────────────────────────────
     /** Schedule a cron job. Returns a handle with the job ID and a cancel method. */
-    scheduleCron(options) {
+    async scheduleCron(options) {
         return this._cronManager.schedule(options);
     }
     /** List all registered cron jobs. */
-    listCronJobs() {
+    async listCronJobs() {
         return this._cronManager.list();
     }
     /** Cancel a cron job by ID. */
-    cancelCronJob(id) {
-        this._cronManager.cancel(id);
+    async cancelCronJob(id) {
+        await this._cronManager.cancel(id);
     }
     /** Subscribe to cron lifecycle events (fire, complete, error). */
     onCronEvent(handler) {
         this._cronManager.onEvent(handler);
     }
     async dispose() {
-        this._cronManager.dispose();
-        for (const sessionId of [...this._sessions.keys()]) {
-            await this._closeSessionInternal(sessionId).catch(() => { });
+        if (this._disposed) {
+            return;
         }
-        for (const [id, entry] of this._shells) {
-            entry.handle.kill();
+        if (this._disposePromise) {
+            return this._disposePromise;
         }
-        const shellExitPromises = [...this._pendingShellExitPromises];
-        this._shells.clear();
-        const terminalExitPromises = [];
-        for (const terminal of this._acpTerminals.values()) {
-            terminal.handle.kill();
-            terminalExitPromises.push(terminal.waitPromise.then(() => undefined, () => undefined));
+        const attempt = this._disposeOnce();
+        this._disposePromise = attempt;
+        try {
+            await attempt;
         }
-        this._acpTerminals.clear();
-        await waitForTrackedExitPromises([...shellExitPromises, ...terminalExitPromises], SHELL_DISPOSE_TIMEOUT_MS);
-        this._disposeSidecarEventListener();
+        finally {
+            if (this._disposePromise === attempt) {
+                this._disposePromise = null;
+            }
+        }
+    }
+    async _disposeOnce() {
+        for (const sessionId of [...this._sessions.keys()]) {
+            try {
+                await this._closeSessionInternal(sessionId);
+            }
+            catch (error) {
+                console.warn(`failed to close ACP session ${sessionId} during dispose`, error);
+            }
+        }
+        const shellKillResults = await Promise.allSettled([...this._shells.values()].map((entry) => entry.handle.kill()));
+        for (const result of shellKillResults) {
+            if (result.status === "rejected") {
+                console.warn("failed to close shell during dispose", result.reason);
+            }
+        }
+        const shellExitPromises = [...this._pendingShellExitPromises.values()];
+        await waitForTrackedExitPromises(shellExitPromises, SHELL_DISPOSE_TIMEOUT_MS);
         const sidecarLease = this._sidecarLease;
-        this._sidecarLease = null;
         if (sidecarLease) {
-            return sidecarLease.dispose();
+            await sidecarLease.dispose();
         }
-        return this.#kernel.dispose();
+        else {
+            await this.#kernel.dispose();
+        }
+        // Only release local correlation after authoritative remote teardown. A
+        // failed close leaves these routes and the lease intact for a safe retry.
+        for (const session of this._sessions.values()) {
+            this._rejectPendingPermissionRepliesFromSession(session);
+        }
+        this._sessions.clear();
+        this._cronManager.dispose();
+        this._shells.clear();
+        this._processes.clear();
+        this._disposeSidecarEventListener();
+        this._disposeSidecarRequestHandler?.();
+        this._disposeSidecarRequestHandler = null;
+        if (this._sidecarLease === sidecarLease) {
+            this._sidecarLease = null;
+        }
+        this._disposed = true;
     }
 }
 const agentOsRuntimeAdmins = new WeakMap();
@@ -3441,6 +1946,162 @@ 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;
+    for (const handle of [child, child.stdin, child.stdout, child.stderr]) {
+        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({
+                command: resolvePublishedSidecarBinary(),
+                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;
+    }
+    const { client, session } = await pending;
+    // The TS handle shares one real wire session across all leased VMs. Close it
+    // only after every VM lease has confirmed disposal, then terminate transport.
+    // A rejected close retains the live process/session handle so the caller can
+    // retry the idempotent sidecar operation.
+    await client.closeSession(session);
+    await client.dispose();
+    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;
+}
 export class AgentOsSidecar {
     constructor(sidecarId, placement, sharedPool) {
         sidecarStates.set(this, {
@@ -3463,6 +2124,21 @@ export class AgentOsSidecar {
         if (state.description.state === "disposed") {
             return;
         }
+        if (state.disposePromise) {
+            return state.disposePromise;
+        }
+        const attempt = this.disposeOnce(state);
+        state.disposePromise = attempt;
+        try {
+            await attempt;
+        }
+        finally {
+            if (state.disposePromise === attempt) {
+                state.disposePromise = undefined;
+            }
+        }
+    }
+    async disposeOnce(state) {
         state.description.state = "disposing";
         const errors = [];
         for (const lease of [...state.activeLeases]) {
@@ -3473,15 +2149,15 @@ export class AgentOsSidecar {
                 errors.push(error instanceof Error ? error : new Error(String(error)));
             }
         }
-        state.activeLeases.clear();
-        state.description.activeVmCount = 0;
+        if (errors.length > 0) {
+            throw new AggregateError(errors, `failed to dispose sidecar ${state.description.sidecarId}`);
+        }
+        // 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);
         }
-        if (errors.length > 0) {
-            throw new Error(errors.map((error) => error.message).join("; "));
-        }
     }
 }
 function createAgentOsSidecarInternal(options = {}) {
@@ -3536,7 +2212,20 @@ async function leaseAgentOsSidecarVm(sidecar, 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 disposePromise = null;
     let leaseRecord;
     try {
         const session = await client.createSession({
@@ -3556,10 +2245,27 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
                 if (disposed) {
                     return;
                 }
-                disposed = true;
-                state.activeLeases.delete(leaseRecord);
-                state.description.activeVmCount = state.activeLeases.size;
-                await client.dispose();
+                if (!disposePromise) {
+                    disposePromise = (async () => {
+                        await client.dispose();
+                        disposed = true;
+                        state.activeLeases.delete(leaseRecord);
+                        state.description.activeVmCount = state.activeLeases.size;
+                        // 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();
+                    })();
+                }
+                const attempt = disposePromise;
+                try {
+                    await attempt;
+                }
+                finally {
+                    if (disposePromise === attempt) {
+                        disposePromise = null;
+                    }
+                }
             },
         };
         leaseRecord = {
@@ -3570,20 +2276,39 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
         return lease;
     }
     catch (error) {
-        await client.dispose().catch(() => { });
+        await client.dispose().catch((cleanupError) => {
+            console.warn("failed to dispose sidecar client after lease creation failure", cleanupError);
+        });
+        releaseHold();
         throw error;
     }
 }
 async function createInProcessSidecarTransport(sessionBootstrap, options) {
     const vmAdmins = new Map();
     let disposed = false;
+    let disposePromise = null;
     async function disposeVmAdmin(vmId) {
         const admin = vmAdmins.get(vmId);
         if (!admin) {
             return;
         }
-        vmAdmins.delete(vmId);
         await admin.dispose();
+        vmAdmins.delete(vmId);
+    }
+    async function disposeTransport() {
+        const errors = [];
+        for (const vmId of [...vmAdmins.keys()]) {
+            try {
+                await disposeVmAdmin(vmId);
+            }
+            catch (error) {
+                errors.push(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, "failed to dispose sidecar session");
+        }
+        disposed = true;
     }
     return {
         async createVm(vmBootstrap) {
@@ -3600,18 +2325,17 @@ async function createInProcessSidecarTransport(sessionBootstrap, options) {
             if (disposed) {
                 return;
             }
-            disposed = true;
-            const errors = [];
-            for (const vmId of [...vmAdmins.keys()]) {
-                try {
-                    await disposeVmAdmin(vmId);
-                }
-                catch (error) {
-                    errors.push(error instanceof Error ? error : new Error(String(error)));
-                }
+            if (!disposePromise) {
+                disposePromise = disposeTransport();
+            }
+            const attempt = disposePromise;
+            try {
+                await attempt;
             }
-            if (errors.length > 0) {
-                throw new Error(errors.map((error) => error.message).join("; "));
+            finally {
+                if (disposePromise === attempt) {
+                    disposePromise = null;
+                }
             }
         },
         getVmAdmin(vmId) {