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

package/dist/agent-os.js

@@ -1,25 +1,17 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, posix as posixPath, resolve as resolveHostPath, } from "node:path";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, posix as posixPath, resolve as resolveHostPath, } from "node:path";
 import { fileURLToPath } from "node:url";
 import { validateToolkits } from "./host-tools.js";
 import { zodToJsonSchema } from "./host-tools-zod.js";
+import { 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: {
@@ -40,19 +32,24 @@ async function waitForTrackedExitPromises(promises, timeoutMs) {
         }),
     ]);
 }
-import { AGENT_CONFIGS } from "./agents.js";
-import { getBaseEnvironment, getBaseFilesystemEntries, } from "./base-filesystem.js";
+import { getBaseEnvironment } 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 { serializeMountConfigForSidecar, } from "./js-bridge.js";
 import { createSnapshotExport, } from "./layers.js";
-import { processSoftware, resolvePackageDir, } from "./packages.js";
+import { OPT_AGENTOS_ROOT, } from "./agentos-package.js";
+import { resolveDefaultSoftware } from "./default-software.js";
 import { allowAll } from "./runtime-compat.js";
 import { AcpRuntimeKind, 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";
+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 {
@@ -105,6 +102,28 @@ function toRecord(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 };
+    }
+    // Recognizably-legacy shapes fail loudly: silently dropping a software
+    // entry boots a VM with missing packages and no diagnostic.
+    for (const legacy of ["packageTar", "packageDir", "dir"]) {
+        if (typeof record[legacy] === "string") {
+            throw new Error(`agentOS package ref uses removed field "${legacy}" (value: ${JSON.stringify(record[legacy])}); ` +
+                "packages are referenced by a single `packagePath` — update the package " +
+                "(rebuild @agentos-software/* dependencies) or pass { packagePath }");
+        }
+    }
+    return undefined;
+}
 function parseAcpJson(value, context) {
     if (value === null) {
         return undefined;
@@ -160,11 +179,11 @@ class BoundedSet {
         }
         this.limit = limit;
     }
-    add(value) {
+    add(value, associated) {
         if (this.#entries.has(value)) {
             this.#entries.delete(value);
         }
-        this.#entries.set(value, undefined);
+        this.#entries.set(value, associated);
         if (this.#entries.size <= this.limit) {
             return;
         }
@@ -176,6 +195,9 @@ class BoundedSet {
     has(value) {
         return this.#entries.has(value);
     }
+    get(value) {
+        return this.#entries.get(value);
+    }
     delete(value) {
         return this.#entries.delete(value);
     }
@@ -223,6 +245,7 @@ function sessionEntryFromInit(sessionId, agentType, initData) {
         agentInfo: initData.agentInfo ?? null,
         eventHandlers: new Set(),
         permissionHandlers: new Set(),
+        warnedNoPermissionHandler: false,
         configOverrides: new Map(),
         pendingPermissionReplies: new Map(),
     };
@@ -366,7 +389,8 @@ const KERNEL_POSIX_BOOTSTRAP_DIRS = [
     "/mnt",
     "/media",
     "/home",
-    "/home/user",
+    "/home/agentos",
+    "/workspace",
     "/usr",
     "/usr/bin",
     "/usr/games",
@@ -390,8 +414,31 @@ const KERNEL_POSIX_BOOTSTRAP_DIRS = [
     "/var/tmp",
     "/etc/agentos",
 ];
-const NODE_RUNTIME_BOOTSTRAP_COMMANDS = ["node", "npm", "npx"];
-const KERNEL_COMMAND_STUB = "#!/bin/sh\n# kernel command stub\n";
+// Standard POSIX metadata for the bootstrap dirs whose mode/owner is NOT the
+// default (`755`, root:root). Replicated as a constant so building the no-base
+// bootstrap layer needs no `base-filesystem.json` read — when a base IS present
+// the sidecar's embedded base layer is authoritative and these are never emitted.
+const KERNEL_POSIX_BOOTSTRAP_DIR_METADATA = {
+    "/tmp": { mode: "1777", uid: 0, gid: 0 },
+    "/root": { mode: "700", uid: 0, gid: 0 },
+    "/sys": { mode: "555", uid: 0, gid: 0 },
+    "/home/agentos": { mode: "2755", uid: 1000, gid: 1000 },
+    "/workspace": { mode: "755", uid: 1000, gid: 1000 },
+    "/var/empty": { mode: "555", uid: 0, gid: 0 },
+    "/var/lock": { mode: "777", uid: 0, gid: 0 },
+    "/var/run": { mode: "777", uid: 0, gid: 0 },
+    "/var/tmp": { mode: "1777", uid: 0, gid: 0 },
+};
+// Runtime commands that get a `/bin/<cmd>` stub at bootstrap so the guest shell
+// resolves them on PATH (e.g. `sh -c "python ..."`, pipelines). The sidecar
+// intercepts these by name and routes them to the embedded V8 / Pyodide runtime.
+const RUNTIME_BOOTSTRAP_COMMANDS = [
+    "node",
+    "npm",
+    "npx",
+    "python",
+    "python3",
+];
 const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
 const SIDECAR_BINARY = join(REPO_ROOT, "target/debug/agentos-sidecar");
 const SIDECAR_BUILD_INPUTS = [
@@ -403,114 +450,6 @@ const SIDECAR_BUILD_INPUTS = [
     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 ?? []) {
@@ -533,16 +472,15 @@ function findBootstrapSeedEntry(config, path) {
             return entry;
         }
     }
-    return getBaseFilesystemEntries().find((entry) => entry.path === path);
+    // No base-filesystem JSON read: standard non-default dir metadata comes from
+    // the constant table. When a base layer IS present these dirs are never
+    // emitted (see createKernelBootstrapLower), so this only seeds the no-base case.
+    const meta = KERNEL_POSIX_BOOTSTRAP_DIR_METADATA[path];
+    return meta ? { path, type: "directory", ...meta } : undefined;
 }
-function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
+function createKernelBootstrapLower(config, extraEntries = []) {
     const includesBundledBaseLayer = !(config?.disableDefaultBaseLayer ?? false);
     const existingPaths = collectConfiguredLowerPaths(config);
-    if (includesBundledBaseLayer) {
-        for (const entry of getBaseFilesystemEntries()) {
-            existingPaths.add(entry.path);
-        }
-    }
     const entries = [
         {
             path: "/",
@@ -552,18 +490,24 @@ function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
             gid: 0,
         },
     ];
-    for (const dir of KERNEL_POSIX_BOOTSTRAP_DIRS) {
-        if (existingPaths.has(dir)) {
-            continue;
+    // Only run the FS bootstrap (creating the POSIX dir tree) when there is NO
+    // base layer. When the bundled base IS present, the sidecar's embedded base
+    // layer already provides every POSIX dir with the correct mode/owner, so we
+    // emit nothing here and never read its filesystem table.
+    if (!includesBundledBaseLayer) {
+        for (const dir of KERNEL_POSIX_BOOTSTRAP_DIRS) {
+            if (existingPaths.has(dir)) {
+                continue;
+            }
+            const seed = findBootstrapSeedEntry(config, dir);
+            entries.push({
+                path: dir,
+                type: "directory",
+                mode: seed?.type === "directory" ? seed.mode : "755",
+                uid: seed?.uid ?? 0,
+                gid: seed?.gid ?? 0,
+            });
         }
-        const seed = findBootstrapSeedEntry(config, dir);
-        entries.push({
-            path: dir,
-            type: "directory",
-            mode: seed?.type === "directory" ? seed.mode : "755",
-            uid: seed?.uid ?? 0,
-            gid: seed?.gid ?? 0,
-        });
     }
     if (!includesBundledBaseLayer && !existingPaths.has("/usr/bin/env")) {
         entries.push({
@@ -576,22 +520,6 @@ function createKernelBootstrapLower(config, commandNames, extraEntries = []) {
             encoding: "base64",
         });
     }
-    const uniqueCommands = [...new Set(commandNames)].sort((a, b) => a.localeCompare(b));
-    for (const command of uniqueCommands) {
-        const stubPath = `/bin/${command}`;
-        if (existingPaths.has(stubPath)) {
-            continue;
-        }
-        entries.push({
-            path: stubPath,
-            type: "file",
-            mode: "755",
-            uid: 0,
-            gid: 0,
-            content: KERNEL_COMMAND_STUB,
-            encoding: "utf8",
-        });
-    }
     for (const entry of sortFilesystemEntries(extraEntries)) {
         if (existingPaths.has(entry.path)) {
             continue;
@@ -706,28 +634,6 @@ function latestMtimeMs(path) {
     }
     return latest;
 }
-function collectGuestCommandPaths(commandDirs) {
-    const guestPaths = new Map();
-    for (const [index, commandDir] of commandDirs.entries()) {
-        let entries;
-        try {
-            entries = readdirSync(commandDir).sort((left, right) => left.localeCompare(right));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (entry.startsWith(".")) {
-                continue;
-            }
-            if (!isWasmBinaryFile(join(commandDir, entry)) || guestPaths.has(entry)) {
-                continue;
-            }
-            guestPaths.set(entry, `/__secure_exec/commands/${index}/${entry}`);
-        }
-    }
-    return guestPaths;
-}
 async function resolveCompatLocalMounts(mounts) {
     if (!mounts) {
         return [];
@@ -796,52 +702,24 @@ function collectSidecarMountPlan(options) {
     }
     for (const mount of options.mounts ?? []) {
         if (!isNativeMountConfig(mount)) {
+            sidecarMounts.push({
+                guestPath: mount.path,
+                readOnly: isOverlayMountConfig(mount)
+                    ? (mount.filesystem.mode ?? "ephemeral") === "read-only"
+                    : (mount.readOnly ?? false),
+                plugin: {
+                    id: "js_bridge",
+                    config: {},
+                },
+            });
             continue;
         }
         pushMount(mount);
     }
-    for (const root of options.softwareRoots) {
-        pushMount({
-            path: root.vmPath,
-            plugin: createHostDirBackend({
-                hostPath: root.hostPath,
-                readOnly: true,
-            }),
-            readOnly: true,
-        });
-    }
-    for (const [index, commandDir] of options.commandDirs.entries()) {
-        pushMount({
-            path: `/__secure_exec/commands/${index}`,
-            plugin: createHostDirBackend({
-                hostPath: commandDir,
-                readOnly: true,
-            }),
-            readOnly: true,
-        });
-    }
-    if (options.shimDir) {
-        pushMount({
-            path: "/usr/local/bin",
-            plugin: createHostDirBackend({
-                hostPath: options.shimDir,
-                readOnly: true,
-            }),
-            readOnly: true,
-        });
-    }
     hostMounts.sort((left, right) => right.vmPath.length - left.vmPath.length);
     hostPathMappings.sort((left, right) => right.vmPath.length - left.vmPath.length);
     return { sidecarMounts, hostMounts, hostPathMappings };
 }
-function materializeToolShimDir(toolKits) {
-    const shimDir = mkdtempSync(join(tmpdir(), "agentos-host-tools-shims-"));
-    writeFileSync(join(shimDir, "agentos"), KERNEL_COMMAND_STUB, { mode: 0o755 });
-    for (const toolKit of toolKits) {
-        writeFileSync(join(shimDir, `agentos-${toolKit.name}`), KERNEL_COMMAND_STUB, { mode: 0o755 });
-    }
-    return shimDir;
-}
 function collectToolkitBootstrapCommands(toolKits) {
     if (toolKits.length === 0) {
         return [];
@@ -1038,7 +916,7 @@ async function handleHostCallback(request, context) {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            error: `EACCES: blocked by tool.invoke policy for ${payload.callback_key}`,
+            error: `EACCES: blocked by binding.invoke policy for ${payload.callback_key}`,
         };
     }
     const parsed = tool.inputSchema.safeParse(payload.input);
@@ -1073,6 +951,134 @@ function buildToolMap(toolKits) {
     }
     return toolMap;
 }
+function bridgeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function toBridgeArgs(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("js_bridge args must be an object");
+    }
+    return value;
+}
+function bridgePath(mountId, value) {
+    if (!mountId.startsWith("/")) {
+        throw new Error(`Unsupported js_bridge mount id: ${mountId}`);
+    }
+    if (typeof value !== "string") {
+        throw new Error("js_bridge path argument must be a string");
+    }
+    return posixPath.normalize(posixPath.join(mountId, value));
+}
+function requireBridgeNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`js_bridge args.${field} must be a number`);
+    }
+    return value;
+}
+function decodeBridgeBytes(value, field) {
+    if (typeof value === "string") {
+        return new Uint8Array(Buffer.from(value, "base64"));
+    }
+    if (Array.isArray(value) &&
+        value.every((entry) => Number.isInteger(entry) && entry >= 0 && entry <= 255)) {
+        return new Uint8Array(value);
+    }
+    throw new Error(`js_bridge args.${field} must be base64 bytes`);
+}
+async function handleJsBridgeCall(request, context) {
+    try {
+        const args = toBridgeArgs(request.args);
+        const fs = context.filesystem;
+        const path = () => bridgePath(request.mount_id, args.path);
+        let result;
+        switch (request.operation) {
+            case "readFile":
+                result = Buffer.from(await fs.readFile(path())).toString("base64");
+                break;
+            case "readDir":
+                result = await fs.readDir(path());
+                break;
+            case "readDirWithTypes":
+                result = await fs.readDirWithTypes(path());
+                break;
+            case "writeFile":
+                await fs.writeFile(path(), decodeBridgeBytes(args.content, "content"));
+                break;
+            case "createDir":
+                await fs.createDir(path());
+                break;
+            case "mkdir":
+                await fs.mkdir(path(), { recursive: args.recursive !== false });
+                break;
+            case "exists":
+                result = await fs.exists(path());
+                break;
+            case "stat":
+                result = await fs.stat(path());
+                break;
+            case "removeFile":
+                await fs.removeFile(path());
+                break;
+            case "removeDir":
+                await fs.removeDir(path());
+                break;
+            case "rename":
+                await fs.rename(bridgePath(request.mount_id, args.oldPath), bridgePath(request.mount_id, args.newPath));
+                break;
+            case "realpath":
+                result = await fs.realpath(path());
+                break;
+            case "symlink": {
+                if (typeof args.target !== "string") {
+                    throw new Error("js_bridge args.target must be a string");
+                }
+                await fs.symlink(args.target, bridgePath(request.mount_id, args.linkPath));
+                break;
+            }
+            case "readlink":
+                result = await fs.readlink(path());
+                break;
+            case "lstat":
+                result = await fs.lstat(path());
+                break;
+            case "link":
+                await fs.link(bridgePath(request.mount_id, args.oldPath), bridgePath(request.mount_id, args.newPath));
+                break;
+            case "chmod":
+                await fs.chmod(path(), requireBridgeNumber(args.mode, "mode"));
+                break;
+            case "chown":
+                await fs.chown(path(), requireBridgeNumber(args.uid, "uid"), requireBridgeNumber(args.gid, "gid"));
+                break;
+            case "utimes":
+                await fs.utimes(path(), requireBridgeNumber(args.atimeMs, "atimeMs"), requireBridgeNumber(args.mtimeMs, "mtimeMs"));
+                break;
+            case "truncate":
+                await fs.truncate(path(), requireBridgeNumber(args.length, "length"));
+                break;
+            case "pread":
+                result = Buffer.from(await fs.pread(path(), requireBridgeNumber(args.offset, "offset"), requireBridgeNumber(args.length, "length"))).toString("base64");
+                break;
+            case "pwrite":
+                await fs.pwrite(path(), requireBridgeNumber(args.offset, "offset"), decodeBridgeBytes(args.content, "content"));
+                break;
+            default:
+                throw new Error(`Unsupported js_bridge operation: ${request.operation}`);
+        }
+        return {
+            type: "js_bridge_result",
+            call_id: request.call_id,
+            ...(result === undefined ? {} : { result }),
+        };
+    }
+    catch (error) {
+        return {
+            type: "js_bridge_result",
+            call_id: request.call_id,
+            error: bridgeErrorMessage(error),
+        };
+    }
+}
 function parseHostCommandCallbackInput(input) {
     const value = asRecord(input);
     if (value.type !== "command" ||
@@ -1153,7 +1159,7 @@ async function invokeHostTool({ toolKit, toolName, args, cwd, context, }) {
     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}`);
+        throw new Error(`EACCES: blocked by binding.invoke policy for ${callbackKey}`);
     }
     const input = await parseHostToolInput(tool, args, cwd, context.readFile);
     return executeHostTool(tool, callbackKey, input);
@@ -1309,7 +1315,7 @@ function describeToolPayload(toolKit, toolName) {
     };
 }
 function toolPermissionMode(permissions, callbackKey) {
-    const scope = permissions.tool;
+    const scope = permissions.binding;
     if (!scope) {
         return "deny";
     }
@@ -1383,13 +1389,14 @@ export class AgentOs {
     _pendingSessionRequestResolvers = new Map();
     _processes = new Map();
     _shells = new Map();
+    // Value is the recorded exit code (undefined until/unless the exit
+    // resolves) so waitShell can still report it after the entry is dropped.
     _closedShellIds = new BoundedSet(CLOSED_SHELL_ID_RETENTION_LIMIT);
     _pendingShellExitPromises = new Set();
     _shellCounter = 0;
     _acpTerminals = new Map();
     _acpTerminalCounter = 0;
     _softwareRoots;
-    _softwareAgentConfigs;
     _cronManager;
     _toolKits = [];
     _toolReference = "";
@@ -1397,22 +1404,29 @@ export class AgentOs {
     _hostMounts;
     _env;
     _rootFilesystem;
+    _additionalInstructions;
     _sidecarLease = null;
     _sidecarClient;
     _sidecarSession;
     _sidecarVm;
     _disposeSidecarEventListener;
-    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm) {
+    _agentStderrHandler;
+    _agentExitHandler;
+    _limitWarningHandler;
+    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, additionalInstructions, 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._additionalInstructions = additionalInstructions;
+        this._agentStderrHandler = agentStderrHandler;
+        this._agentExitHandler = agentExitHandler;
+        this._limitWarningHandler = limitWarningHandler;
         this._disposeSidecarEventListener = this._sidecarClient.onEvent((event) => {
             this._handleSidecarEvent(event);
         });
@@ -1430,72 +1444,90 @@ export class AgentOs {
         return getSharedAgentOsSidecarInternal(options);
     }
     static async create(options) {
-        const processed = processSoftware(options?.software ?? []);
+        options = parseAgentOsOptions(options);
+        // Default software is FULLY DYNAMIC: this package's own NON-agent
+        // @agentos-software/* dependencies (e.g. common), each default-exporting
+        // its registry-built descriptor. Agent packages are NOT projected here —
+        // createSession(id) links the matching agent dependency into the running
+        // VM on first use, so agent closures (and pi's V8 snapshot bundle) only
+        // enter VMs that run them. Unbuilt packages throw with build
+        // instructions; opt out via defaultSoftware: false.
+        const defaultSoftware = options?.defaultSoftware === false ? [] : resolveDefaultSoftware();
+        const software = options?.defaultSoftware === false
+            ? (options.software ?? [])
+            : [...defaultSoftware, ...(options?.software ?? [])];
+        // Packages are projected by the SIDECAR: the client forwards only the
+        // package `path` over `configureVm` and the sidecar reads metadata from
+        // the packed vbare manifest (chunk1 of the `.aospkg`).
+        const flatSoftware = software.flat();
+        // Honor the AgentOsOptions.defaultSoftware contract ("entries already present
+        // in `software` are not duplicated"): the default bundle and an explicitly
+        // passed one resolve to the same package paths, so dedup by path. Without
+        // this the sidecar rejects the second projection with a duplicate-command
+        // error (e.g. coreutils' `[`).
+        const seenPackagePaths = new Set();
+        const sidecarPackages = flatSoftware.flatMap((entry) => {
+            const ref = normalizePackageRef(entry);
+            if (!ref || seenPackagePaths.has(ref.path)) {
+                return [];
+            }
+            seenPackagePaths.add(ref.path);
+            return [{ path: ref.path }];
+        });
+        // All package software is projected into `/opt/agentos` by the sidecar. The
+        // client stages nothing host-side and parses NO package manifests: the
+        // sidecar owns agent resolution, agent enumeration, and agent snapshot
+        // bundle loading from the projected package dirs.
         const localMounts = await resolveCompatLocalMounts(options?.mounts);
         const toolKits = options?.toolKits;
         if (toolKits && toolKits.length > 0) {
             validateToolkits(toolKits);
         }
+        // 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);
+            // The `/opt/agentos` projection is built by the sidecar from the
+            // forwarded `packages` (it owns the staging dir + read-only mount, and
+            // runtime `linkSoftware` appends to that live dir). The client no longer
+            // stages packages host-side.
             const toolBootstrapCommands = collectToolkitBootstrapCommands(toolKits ?? []);
-            const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem, [
-                ...collectBootstrapWasmCommands(preparedCommandDirs.commandDirs),
-                ...NODE_RUNTIME_BOOTSTRAP_COMMANDS,
+            const bootstrapCommands = [
+                ...RUNTIME_BOOTSTRAP_COMMANDS,
                 ...toolBootstrapCommands,
-            ]);
+            ];
+            const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem);
             let toolReference = "";
             let rootBridge = null;
             let kernel = null;
             let client = null;
-            let toolShimDir = null;
+            let createdNativeVm = null;
+            let nativeSession = null;
             let cleanedUp = false;
             const cleanup = async () => {
                 if (cleanedUp) {
                     return;
                 }
                 cleanedUp = true;
-                if (toolShimDir) {
-                    rmSync(toolShimDir, { recursive: true, force: true });
-                    toolShimDir = null;
-                }
-                preparedCommandDirs.dispose();
             };
             try {
                 const env = getBaseEnvironment();
-                if (toolKits && toolKits.length > 0) {
-                    toolShimDir = materializeToolShimDir(toolKits);
-                }
-                const commandGuestPaths = collectGuestCommandPaths(preparedCommandDirs.commandDirs);
-                const requestedMounts = options?.moduleAccessCwd
-                    ? [
-                        ...(options.mounts ?? []),
-                        {
-                            path: "/root/node_modules",
-                            plugin: createHostDirBackend({
-                                hostPath: join(options.moduleAccessCwd, "node_modules"),
-                                readOnly: true,
-                            }),
-                            readOnly: true,
-                        },
-                    ]
-                    : options?.mounts;
+                // Guest command paths. The sidecar owns the `/opt/agentos` projection and
+                // reports the exact projected package commands after `configureVm`.
+                // Tool-shim commands are added below.
+                const commandGuestPaths = new Map();
                 const { sidecarMounts, hostMounts, hostPathMappings } = collectSidecarMountPlan({
-                    mounts: requestedMounts,
-                    softwareRoots: processed.softwareRoots,
-                    commandDirs: preparedCommandDirs.commandDirs,
-                    shimDir: toolShimDir,
-                });
-                client = SidecarProcess.spawn({
-                    cwd: REPO_ROOT,
-                    command: ensureNativeSidecarBinary(),
-                    args: [],
-                    frameTimeoutMs: NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
+                    mounts: options?.mounts,
                 });
-                const session = await client.authenticateAndOpenSession();
+                // Reuse the sidecar handle's single shared native process; this VM
+                // becomes another tenant of it rather than spawning its own process.
+                const shared = await ensureSharedSidecarNativeProcess(sidecar);
+                client = shared.client;
+                const session = shared.session;
+                nativeSession = session;
                 const hostPermissions = options?.permissions ?? {
                     ...allowAll,
-                    tool: "allow",
+                    binding: "allow",
                 };
                 const sidecarPermissions = serializePermissionsForSidecar(hostPermissions);
                 const createVmConfig = {
@@ -1504,18 +1536,25 @@ export class AgentOs {
                     permissions: sidecarPermissions,
                     limits: options?.limits,
                     loopbackExemptPorts: options?.loopbackExemptPorts ?? [],
+                    bootstrapCommands,
                     // 0.3: the Node builtin allow-list moved from configureVm to
                     // VM creation. `undefined` => engine default allow-list;
                     // `[]` => deny all; `[..]` => exactly those. Platform and
                     // module resolution keep their engine defaults (full Node
                     // emulation), matching the prior behavior where Agent OS only
                     // constrained the builtin allow-list.
-                    ...(options?.allowedNodeBuiltins !== undefined
+                    ...(options?.allowedNodeBuiltins !== undefined ||
+                        options?.highResolutionTime !== undefined
                         ? {
                             jsRuntime: {
                                 platform: "node",
                                 moduleResolution: "node",
-                                allowedBuiltins: options.allowedNodeBuiltins,
+                                ...(options?.allowedNodeBuiltins !== undefined
+                                    ? { allowedBuiltins: options.allowedNodeBuiltins }
+                                    : {}),
+                                ...(options?.highResolutionTime !== undefined
+                                    ? { highResolutionTime: options.highResolutionTime }
+                                    : {}),
                             },
                         }
                         : {}),
@@ -1524,14 +1563,25 @@ export class AgentOs {
                     runtime: "java_script",
                     config: createVmConfig,
                 });
+                createdNativeVm = nativeVm;
+                // Scope the readiness wait to THIS VM's ownership; on a shared process
+                // other VMs are emitting their own lifecycle events concurrently.
                 await client.waitForEvent((event) => event.payload.type === "vm_lifecycle" &&
-                    event.payload.state === "ready", 10_000);
-                await client.configureVm(session, nativeVm, {
+                    event.payload.state === "ready" &&
+                    event.ownership.scope === "vm" &&
+                    event.ownership.vm_id === nativeVm.vmId, 10_000);
+                const configuredVm = await client.configureVm(session, nativeVm, {
                     mounts: sidecarMounts,
                     permissions: sidecarPermissions,
-                    commandPermissions: processed.commandPermissions,
+                    commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
+                    packages: sidecarPackages,
+                    packagesMountAt: OPT_AGENTOS_ROOT,
+                    toolShimCommands: toolBootstrapCommands,
                 });
+                for (const command of configuredVm.projectedCommands) {
+                    commandGuestPaths.set(command.name, command.guestPath);
+                }
                 if (toolKits && toolKits.length > 0) {
                     toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, toolKits);
                     commandGuestPaths.set("agentos", "/bin/agentos");
@@ -1544,10 +1594,17 @@ export class AgentOs {
                     session,
                     vm: nativeVm,
                     env,
-                    cwd: "/home/user",
+                    cwd: "/workspace",
                     localMounts,
+                    sidecarMounts,
+                    permissions: sidecarPermissions,
+                    commandPermissions: {},
+                    loopbackExemptPorts: options?.loopbackExemptPorts,
                     commandGuestPaths,
                     onDispose: cleanup,
+                    // The native process is owned by the AgentOsSidecar handle and
+                    // shared across VMs; disposing this VM must not kill the process.
+                    ownsClient: false,
                 });
                 await bootstrapLiveBootstrapDirectories(client, session, nativeVm, options?.rootFilesystem);
                 kernel = rootBridge;
@@ -1557,6 +1614,10 @@ export class AgentOs {
                     hostMounts,
                     kernel,
                     rootView: rootBridge.createRootView(),
+                    sidecarMounts,
+                    sidecarPermissions,
+                    commandPermissions: {},
+                    loopbackExemptPorts: options?.loopbackExemptPorts,
                     sidecarClient: client,
                     sidecarSession: session,
                     sidecarVm: nativeVm,
@@ -1581,6 +1642,8 @@ export class AgentOs {
                 };
             }
             catch (error) {
+                // The native process is shared and owned by the sidecar handle, so
+                // never dispose the client here — only tear down this VM's resources.
                 if (kernel) {
                     await kernel.dispose().catch(() => { });
                 }
@@ -1588,20 +1651,23 @@ export class AgentOs {
                     await rootBridge.dispose().catch(() => { });
                 }
                 else {
-                    await client?.dispose().catch(() => { });
+                    if (createdNativeVm && nativeSession && client) {
+                        await client
+                            .disposeVm(nativeSession, createdNativeVm)
+                            .catch(() => { });
+                    }
                     await cleanup();
                 }
                 throw error;
             }
         };
-        const sidecar = resolveAgentOsSidecar(options?.sidecar);
         let sidecarLease = null;
         try {
             sidecarLease = await leaseAgentOsSidecarVm(sidecar, {
                 createVm: async () => createVmAdmin(),
             });
             const vmAdmin = sidecarLease.admin;
-            const vm = new AgentOs(vmAdmin.kernel, sidecar, processed.softwareRoots, processed.agentConfigs, vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm);
+            const vm = new AgentOs(vmAdmin.kernel, sidecar, [], vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.additionalInstructions, options?.onAgentStderr ?? defaultAgentStderrHandler, options?.onAgentExit ?? defaultAgentExitHandler, options?.onLimitWarning);
             vm._sidecarLease = sidecarLease;
             vm._toolKits = vmAdmin.toolKits;
             vm._toolReference = vmAdmin.toolReference;
@@ -1632,6 +1698,11 @@ export class AgentOs {
             exitHandlers,
         };
         this._processes.set(proc.pid, entry);
+        // NOTE: do NOT delete from `_processes` on exit — the public API contract
+        // (getProcess/listProcesses/stopProcess, see process-management.test.ts)
+        // requires exited processes to stay queryable (running:false, exitCode set).
+        // `_processes` is a process table for this VM's lifetime; it is freed wholesale
+        // in dispose(). (H5: the leak was that dispose() never cleared it.)
         void proc.wait().then((code) => {
             for (const h of exitHandlers)
                 h(code);
@@ -1665,14 +1736,14 @@ export class AgentOs {
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        entry.proc.writeStdin(data);
+        return entry.proc.writeStdin(data);
     }
     /** Close a process's stdin stream. */
     closeProcessStdin(pid) {
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        entry.proc.closeStdin();
+        return entry.proc.closeStdin();
     }
     /** Subscribe to stdout data from a process. Returns an unsubscribe function. */
     onProcessStdout(pid, handler) {
@@ -1733,35 +1804,6 @@ export class AgentOs {
     _vfs() {
         return this.#kernel.vfs;
     }
-    async _copyPath(from, to) {
-        const stat = await this._vfs().lstat(from);
-        if (stat.isSymbolicLink) {
-            const target = await this._vfs().readlink(from);
-            await this._vfs().symlink(target, to);
-            return;
-        }
-        if (stat.isDirectory) {
-            await this._mkdirp(posixPath.dirname(to));
-            if (!(await this.#kernel.exists(to))) {
-                await this.#kernel.mkdir(to);
-            }
-            await this._vfs().chmod(to, stat.mode);
-            await this._vfs().chown(to, stat.uid, stat.gid);
-            const entries = await this.#kernel.readdir(from);
-            for (const entry of entries) {
-                if (entry === "." || entry === "..")
-                    continue;
-                const fromPath = from === "/" ? `/${entry}` : `${from}/${entry}`;
-                const toPath = to === "/" ? `/${entry}` : `${to}/${entry}`;
-                await this._copyPath(fromPath, toPath);
-            }
-            return;
-        }
-        const content = await this.#kernel.readFile(from);
-        await this.writeFile(to, content);
-        await this._vfs().chmod(to, stat.mode);
-        await this._vfs().chown(to, stat.uid, stat.gid);
-    }
     async readFile(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readFile(path);
@@ -1814,14 +1856,13 @@ export class AgentOs {
     /** Recursively create directories (mkdir -p). */
     async _mkdirp(path) {
         this._assertWritableAbsolutePath(path);
-        const parts = path.split("/").filter(Boolean);
-        let current = "";
-        for (const part of parts) {
-            current += `/${part}`;
-            if (!(await this.#kernel.exists(current))) {
-                await this.#kernel.mkdir(current);
-            }
-        }
+        // `kernel.mkdir` is already recursive (it defaults to recursive=true on both
+        // the native sidecar and compat kernels) and creating an existing directory is
+        // a no-op, so a single call is sufficient. Do NOT probe each ancestor with
+        // `exists()` first: on the native sidecar every read-side op
+        // (exists/stat/readFile) triggers a full shadow-tree walk, so a per-component
+        // exists() loop makes `mkdir -p` cost O(components * tree).
+        await this.#kernel.mkdir(path);
     }
     async mkdir(path, options) {
         if (options?.recursive) {
@@ -1836,49 +1877,31 @@ export class AgentOs {
     }
     async readdirRecursive(path, options) {
         this._assertSafeAbsolutePath(path);
-        const maxDepth = options?.maxDepth;
         const exclude = options?.exclude ? new Set(options.exclude) : undefined;
+        const entries = await this.#kernel.readdirRecursive(path, {
+            maxDepth: options?.maxDepth,
+        });
+        const excludedPrefixes = [];
         const results = [];
-        // BFS queue: [dirPath, currentDepth]
-        const queue = [[path, 0]];
-        while (queue.length > 0) {
-            const item = queue.shift();
-            if (!item)
-                break;
-            const [dirPath, depth] = item;
-            const entries = await this.#kernel.readdir(dirPath);
-            for (const name of entries) {
-                if (name === "." || name === "..")
-                    continue;
-                if (exclude?.has(name))
-                    continue;
-                const fullPath = dirPath === "/" ? `/${name}` : `${dirPath}/${name}`;
-                const s = await this.#kernel.stat(fullPath);
-                if (s.isSymbolicLink) {
-                    results.push({
-                        path: fullPath,
-                        type: "symlink",
-                        size: s.size,
-                    });
-                }
-                else if (s.isDirectory) {
-                    results.push({
-                        path: fullPath,
-                        type: "directory",
-                        size: s.size,
-                    });
-                    if (maxDepth === undefined || depth < maxDepth) {
-                        queue.push([fullPath, depth + 1]);
-                    }
-                }
-                else {
-                    results.push({
-                        path: fullPath,
-                        type: "file",
-                        size: s.size,
-                    });
+        for (const entry of entries) {
+            if (excludedPrefixes.some((prefix) => entry.path === prefix || entry.path.startsWith(`${prefix}/`))) {
+                continue;
+            }
+            if (exclude?.has(entry.name)) {
+                if (entry.isDirectory && !entry.isSymbolicLink) {
+                    excludedPrefixes.push(entry.path);
                 }
+                continue;
             }
+            results.push({
+                path: entry.path,
+                type: entry.isSymbolicLink
+                    ? "symlink"
+                    : entry.isDirectory
+                        ? "directory"
+                        : "file",
+                size: entry.size,
+            });
         }
         return results;
     }
@@ -1906,30 +1929,15 @@ export class AgentOs {
         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 });
+        this._assertWritableAbsolutePath(from);
+        this._assertWritableAbsolutePath(to);
+        await this.#kernel.movePath(from, to);
     }
     async delete(path, options) {
-        this._assertSafeAbsolutePath(path);
-        const s = await this.#kernel.stat(path);
-        if (s.isDirectory) {
-            if (options?.recursive) {
-                const entries = await this.#kernel.readdir(path);
-                for (const entry of entries) {
-                    if (entry === "." || entry === "..")
-                        continue;
-                    await this.delete(`${path}/${entry}`, { recursive: true });
-                }
-            }
-            return this.#kernel.removeDir(path);
-        }
-        return this.#kernel.removeFile(path);
+        this._assertWritableAbsolutePath(path);
+        await this.#kernel.removePath(path, {
+            recursive: options?.recursive ?? false,
+        });
     }
     async fetch(port, request) {
         const url = new URL(request.url);
@@ -1964,15 +1972,24 @@ export class AgentOs {
         const entry = {
             handle,
             dataHandlers,
-            exitPromise: Promise.resolve(),
+            exitPromise: Promise.resolve(0),
         };
-        const exitPromise = handle.wait().then(() => undefined, () => undefined);
-        entry.exitPromise = exitPromise.finally(() => {
+        const exitPromise = handle.wait();
+        const finalize = (exitCode) => {
             this._pendingShellExitPromises.delete(entry.exitPromise);
             if (this._shells.get(shellId) === entry) {
                 this._shells.delete(shellId);
-                this._closedShellIds.add(shellId);
             }
+            // Record the exit code even when closeShell already dropped the
+            // entry, so a waitShell issued after exit still resolves with it.
+            this._closedShellIds.add(shellId, exitCode);
+        };
+        entry.exitPromise = exitPromise.then((exitCode) => {
+            finalize(exitCode);
+            return exitCode;
+        }, (error) => {
+            finalize();
+            throw error;
         });
         this._pendingShellExitPromises.add(entry.exitPromise);
         this._shells.set(shellId, entry);
@@ -1986,7 +2003,7 @@ export class AgentOs {
         const entry = this._shells.get(shellId);
         if (!entry)
             throw new Error(`Shell not found: ${shellId}`);
-        entry.handle.write(data);
+        return entry.handle.write(data);
     }
     /** Subscribe to data output from a shell. Returns an unsubscribe function. */
     onShellData(shellId, handler) {
@@ -2005,6 +2022,21 @@ export class AgentOs {
             throw new Error(`Shell not found: ${shellId}`);
         entry.handle.resize(cols, rows);
     }
+    /**
+     * Wait for a shell to exit and return its process exit code. Resolves
+     * immediately for a shell that has already exited (within the closed-shell
+     * retention window).
+     */
+    waitShell(shellId) {
+        const entry = this._shells.get(shellId);
+        if (!entry) {
+            const exitCode = this._closedShellIds.get(shellId);
+            if (exitCode !== undefined)
+                return Promise.resolve(exitCode);
+            throw new Error(`Shell not found: ${shellId}`);
+        }
+        return entry.exitPromise;
+    }
     /** Kill a shell process and remove it from tracking. */
     closeShell(shellId) {
         const entry = this._shells.get(shellId);
@@ -2119,53 +2151,56 @@ 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);
+    /**
+     * 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);
+        if (!ref) {
+            throw new Error("Invalid agentOS package reference");
+        }
+        // Forward to the sidecar, which owns the `/opt/agentos` projection and
+        // appends the package to its live host-backed staging dir; the commands
+        // appear under `/opt/agentos/bin` immediately. The sidecar rejects a
+        // duplicate command, surfaced here as a thrown error.
+        const commands = await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, { path: ref.path });
+        if (this.#kernel instanceof NativeSidecarKernelProxy) {
+            this.#kernel.registerCommandGuestPaths(new Map(commands.projectedCommands.map((command) => [
+                command.name,
+                command.guestPath,
+            ])));
+        }
+        // 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,
+        }));
     }
     _syncSessionState(session, state) {
         session.processId = state.processId;
@@ -2244,6 +2279,106 @@ export class AgentOs {
             session.eventHandlers.delete(subscriber);
         };
     }
+    /**
+     * 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.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.`);
+    }
+    /** Best-effort human label for the tool named in a permission request. */
+    _permissionToolLabel(params) {
+        if (typeof params.toolName === "string") {
+            return params.toolName;
+        }
+        const toolCall = params.toolCall;
+        if (toolCall &&
+            typeof toolCall === "object" &&
+            typeof toolCall.title === "string") {
+            return toolCall.title;
+        }
+        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 {
+            handler({
+                sessionId: session.sessionId,
+                agentType: session.agentType,
+                processId: session.processId,
+                pid: session.pid,
+                chunk: new TextEncoder().encode(`${message}\n`),
+            });
+        }
+        catch {
+            // A warning sink failure must never affect permission handling.
+        }
+    }
+    _recordAgentStderr(event) {
+        const session = (event.sessionId ? this._sessions.get(event.sessionId) : undefined) ??
+            [...this._sessions.values()].find((candidate) => candidate.processId === event.processId);
+        const sessionId = event.sessionId || session?.sessionId;
+        if (!sessionId) {
+            return;
+        }
+        const handler = this._agentStderrHandler;
+        if (!handler) {
+            return;
+        }
+        try {
+            handler({
+                sessionId,
+                agentType: event.agentType || session?.agentType || "",
+                processId: event.processId,
+                pid: session?.pid ?? null,
+                chunk: new Uint8Array(event.chunk),
+            });
+        }
+        catch {
+            // Ignore subscriber callback failures and keep event delivery moving.
+        }
+    }
+    _recordAgentExit(event) {
+        const session = this._sessions.get(event.sessionId);
+        const handler = this._agentExitHandler;
+        if (!handler) {
+            return;
+        }
+        try {
+            handler({
+                sessionId: event.sessionId,
+                agentType: event.agentType || session?.agentType || "",
+                processId: event.processId,
+                pid: session?.pid ?? null,
+                exitCode: event.exitCode,
+                restart: event.restart,
+                restartCount: event.restartCount,
+                maxRestarts: event.maxRestarts,
+            });
+        }
+        catch {
+            // Ignore subscriber callback failures and keep event delivery moving.
+        }
+    }
     _applySyntheticConfigOverrides(session) {
         if (session.configOverrides.size === 0) {
             return;
@@ -2266,6 +2401,10 @@ export class AgentOs {
         if (event.payload.type !== "structured") {
             return;
         }
+        if (event.payload.name === "limit_warning") {
+            this._handleLimitWarning(event.payload.detail);
+            return;
+        }
         if (event.payload.name !== "acp.session_event") {
             return;
         }
@@ -2285,6 +2424,27 @@ export class AgentOs {
             // Ignore malformed event payloads from the sidecar.
         }
     }
+    _handleLimitWarning(detail) {
+        if (!this._limitWarningHandler) {
+            return;
+        }
+        const toNumber = (value) => {
+            const parsed = Number(value);
+            return Number.isFinite(parsed) ? parsed : 0;
+        };
+        try {
+            this._limitWarningHandler({
+                limit: detail.limit ?? "",
+                category: detail.category ?? "",
+                observed: toNumber(detail.observed),
+                capacity: toNumber(detail.capacity),
+                fillPercent: toNumber(detail.fillPercent),
+            });
+        }
+        catch {
+            // A throwing handler must never break the sidecar event loop.
+        }
+    }
     _handleAcpExtEvent(envelope) {
         if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
             return;
@@ -2300,6 +2460,14 @@ export class AgentOs {
                     this._recordSessionNotification(session, toJsonRpcNotification(JSON.parse(event.val.notification)));
                     return;
                 }
+                case "AcpAgentStderrEvent": {
+                    this._recordAgentStderr(event.val);
+                    return;
+                }
+                case "AcpAgentExitedEvent": {
+                    this._recordAgentExit(event.val);
+                    return;
+                }
             }
         }
         catch {
@@ -2515,37 +2683,30 @@ export class AgentOs {
         this._syncSessionState(session, state);
     }
     async createSession(agentType, options) {
-        const config = this._resolveAgentConfig(agentType);
-        if (!config) {
-            throw new Error(`Unknown agent type: ${agentType}`);
-        }
-        // System-prompt assembly and injection (launch args / OPENCODE_CONTEXTPATHS) are owned by
-        // the sidecar at AcpCreateSessionRequest. The host only forwards additionalInstructions /
-        // skipOsInstructions plus the agent's static launch args and env.
-        const launchArgs = [...(config.launchArgs ?? [])];
-        let launchEnv = { ...config.defaultEnv, ...options?.env };
-        const sessionCwd = options?.cwd ?? "/home/user";
-        const adapterEntrypoint = this._resolveAdapterBin(config.acpAdapter);
-        if ((agentType === "pi" || agentType === "pi-cli") &&
-            !launchEnv.PI_ACP_PI_COMMAND) {
-            launchEnv = {
-                ...launchEnv,
-                PI_ACP_PI_COMMAND: this._resolvePackageBin(config.agentPackage, "pi"),
-            };
-        }
+        // 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 launchEnv = { ...options?.env };
+        const sessionCwd = options?.cwd ?? "/workspace";
         const response = await this._sendAcpRequest({
             tag: "AcpCreateSessionRequest",
             val: {
                 agentType: String(agentType),
                 runtime: AcpRuntimeKind.JavaScript,
-                adapterEntrypoint,
-                args: launchArgs,
+                args: [],
                 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),
+                additionalInstructions: combineInstructions([this._additionalInstructions, options?.additionalInstructions]
+                    .map((part) => part?.trim())
+                    .filter((part) => Boolean(part))
+                    .join("\n\n") || undefined, this._toolReference),
                 skipOsInstructions: options?.skipOsInstructions ?? false,
             },
         });
@@ -2596,27 +2757,11 @@ export class AgentOs {
      * there is no surviving store and the fallback tier always runs.
      */
     async resumeSession(sessionId, agentType, options) {
-        const config = this._resolveAgentConfig(agentType);
-        if (!config) {
-            throw new Error(`Unknown agent type: ${agentType}`);
-        }
-        const adapterEntrypoint = this._resolveAdapterBin(config.acpAdapter);
-        let launchEnv = { ...config.defaultEnv, ...options?.env };
-        const sessionCwd = options?.cwd ?? "/home/user";
-        if ((agentType === "pi" || agentType === "pi-cli") &&
-            !launchEnv.PI_ACP_PI_COMMAND) {
-            launchEnv = {
-                ...launchEnv,
-                PI_ACP_PI_COMMAND: this._resolvePackageBin(config.agentPackage, "pi"),
-            };
-        }
-        // 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,
-        };
+        // 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 sessionCwd = options?.cwd ?? "/workspace";
+        const launchEnv = { ...options?.env };
         const response = await this._sendAcpRequest({
             tag: "AcpResumeSessionRequest",
             val: {
@@ -2632,6 +2777,10 @@ export class AgentOs {
         }
         const { sessionId: liveSessionId, mode } = response.val;
         // Register + hydrate the live session so subsequent prompts route to it.
+        const existing = this._sessions.get(liveSessionId);
+        if (existing !== undefined && !existing.closed) {
+            throw new Error(`session id collision: ${liveSessionId}`);
+        }
         const session = sessionEntryFromInit(liveSessionId, String(agentType), {});
         this._closedSessionIds.delete(liveSessionId);
         this._sessions.set(liveSessionId, session);
@@ -2644,65 +2793,6 @@ export class AgentOs {
         }
         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;
-            }
-        }
-        // 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().`);
-            }
-            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`);
-        }
-        return `${vmPrefix}/${binEntry}`;
-    }
     _installSidecarRequestHandler() {
         const context = {
             toolKits: this._toolKits,
@@ -2715,10 +2805,8 @@ export class AgentOs {
                 case "host_callback":
                     return handleHostCallback(request, context);
                 case "js_bridge_call":
-                    return Promise.resolve({
-                        type: "js_bridge_result",
-                        call_id: request.payload.call_id,
-                        error: `unsupported sidecar request type: ${request.payload.type}`,
+                    return handleJsBridgeCall(request.payload, {
+                        filesystem: this.#kernel.vfs,
                     });
                 case "ext":
                     return this._handleAcpExtSidecarRequest(request.payload.envelope);
@@ -2905,6 +2993,10 @@ export class AgentOs {
             _acpMethod: request.method,
         };
         if (session.permissionHandlers.size === 0) {
+            // Default-closed deny; warn once (host-visible) so a forgotten
+            // onPermissionRequest handler is an observable cause rather than a
+            // silent denial. See _warnNoPermissionHandlerOnce.
+            this._warnNoPermissionHandlerOnce(session, permissionParams);
             return this._buildAcpPermissionResult("reject", permissionParams);
         }
         const reply = await new Promise((resolve, reject) => {
@@ -3187,6 +3279,10 @@ export class AgentOs {
             return "reject";
         }
         if (session.permissionHandlers.size === 0) {
+            // Default-closed: deny when no host hook is listening, and warn once
+            // (host-visible) so a forgotten onPermissionRequest handler is not an
+            // invisible cause of an agent that cannot use any tool.
+            this._warnNoPermissionHandlerOnce(session, params);
             return "reject";
         }
         try {
@@ -3216,14 +3312,6 @@ export class AgentOs {
             return "reject";
         }
     }
-    /**
-     * Resolve an agent config by ID. Package-provided configs take
-     * precedence over the hardcoded AGENT_CONFIGS.
-     */
-    _resolveAgentConfig(agentType) {
-        return (this._softwareAgentConfigs.get(agentType) ??
-            AGENT_CONFIGS[agentType]);
-    }
     /**
      * Gracefully destroy a session: cancel any pending work, close the client,
      * and remove from tracking. Unlike close() which is abrupt, this attempts
@@ -3407,6 +3495,7 @@ export class AgentOs {
             terminalExitPromises.push(terminal.waitPromise.then(() => undefined, () => undefined));
         }
         this._acpTerminals.clear();
+        this._processes.clear();
         await waitForTrackedExitPromises([...shellExitPromises, ...terminalExitPromises], SHELL_DISPOSE_TIMEOUT_MS);
         this._disposeSidecarEventListener();
         const sidecarLease = this._sidecarLease;
@@ -3436,6 +3525,164 @@ 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({
+                cwd: REPO_ROOT,
+                command: ensureNativeSidecarBinary(),
+                args: [],
+                frameTimeoutMs: NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
+            });
+            // Track the child immediately — BEFORE the handshake await — so a
+            // failed `authenticateAndOpenSession()` can still reap it (otherwise
+            // the spawned child is untracked, unreapable, and pins the loop).
+            state.sharedChild = sidecarChildHandle(client);
+            if (!state.sharedChild) {
+                // We reached into @rivet-dev/agentos-runtime-core internals to get the child for
+                // idle-unref. If that shape ever changes this returns undefined and
+                // the optimization silently stops working (one-shot scripts would
+                // hang again). Make it loud rather than a silent regression.
+                console.warn("[agentos] could not resolve the shared sidecar child handle; " +
+                    "standalone scripts may not exit cleanly after dispose(). " +
+                    "This usually means @rivet-dev/agentos-runtime-core internals changed.");
+            }
+            // Apply the current hold state to the just-spawned child.
+            applySharedSidecarHold(state);
+            try {
+                const session = await client.authenticateAndOpenSession();
+                return { client, session };
+            }
+            catch (error) {
+                // Spawn/handshake failed: reap the child, drop the cached handle,
+                // and CLEAR the rejected promise so the next create() retries
+                // instead of permanently wedging on a rejected `nativeProcess`.
+                try {
+                    state.sharedChild?.kill?.("SIGKILL");
+                }
+                catch {
+                    // already gone
+                }
+                state.sharedChild = undefined;
+                state.nativeProcess = undefined;
+                throw error;
+            }
+        })();
+    }
+    return state.nativeProcess;
+}
+/** Dispose a sidecar handle's shared native process, if one was spawned. */
+async function disposeSharedSidecarNativeProcess(state) {
+    const pending = state.nativeProcess;
+    if (!pending) {
+        return;
+    }
+    state.nativeProcess = undefined;
+    // The cached child is now dead; drop it (symmetric with the assignment in
+    // ensureSharedSidecarNativeProcess). We deliberately do NOT zero
+    // `eventLoopHolds` here: this runs only from `AgentOsSidecar.dispose()`, which
+    // has already set the handle to `disposing` (so no new lease can acquire) and
+    // drained `activeLeases`; the disposed handle's state is then abandoned. Force-
+    // zeroing a shared counter could clobber a hold on a freshly re-acquired
+    // process generation, so it is left to the balanced acquire/release pairs.
+    state.sharedChild = undefined;
+    try {
+        const { client } = await pending;
+        await client.dispose();
+    }
+    catch {
+        // Process may have already exited; nothing to reclaim.
+    }
+}
 export class AgentOsSidecar {
     constructor(sidecarId, placement, sharedPool) {
         sidecarStates.set(this, {
@@ -3470,6 +3717,8 @@ export class AgentOsSidecar {
         }
         state.activeLeases.clear();
         state.description.activeVmCount = 0;
+        // Tear down the shared native process after all leased VMs are gone.
+        await disposeSharedSidecarNativeProcess(state);
         state.description.state = "disposed";
         if (state.sharedPool && sharedSidecars.get(state.sharedPool) === this) {
             sharedSidecars.delete(state.sharedPool);
@@ -3531,6 +3780,18 @@ 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 leaseRecord;
     try {
@@ -3555,6 +3816,10 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
                 state.activeLeases.delete(leaseRecord);
                 state.description.activeVmCount = state.activeLeases.size;
                 await client.dispose();
+                // Release this lease's hold; the shared sidecar is unref'd only
+                // once the last hold (across all in-flight + active leases) drops,
+                // so a one-shot host process can then exit on its own.
+                releaseHold();
             },
         };
         leaseRecord = {
@@ -3566,6 +3831,7 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
     }
     catch (error) {
         await client.dispose().catch(() => { });
+        releaseHold();
         throw error;
     }
 }