@rivet-dev/agentos-core 0.2.4 → 0.2.5-rc.1

package/dist/agent-os.js

@@ -2,9 +2,8 @@ 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 { 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 { zodToJsonSchema } from "./host-tools-zod.js";
 import { parseAgentOsOptions } from "./options-schema.js";
@@ -42,15 +41,16 @@ 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, resolveAgentSnapshotBundle, resolvePackageDir, } from "./packages.js";
+import { resolveAgentSnapshotBundle, } from "./packages.js";
+import { OPT_AGENTOS_BIN, OPT_AGENTOS_ROOT, tryReadAgentosPackageManifest, } from "./agentos-package.js";
+import { resolveDefaultSoftware, resolveDependencyAgents, } 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";
@@ -58,6 +58,9 @@ import { createAgentOsSidecarClient, NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSide
 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 {
@@ -110,6 +113,53 @@ function toRecord(value) {
         ? value
         : {};
 }
+function normalizePackageRef(value) {
+    if (typeof value === "string") {
+        return { dir: value };
+    }
+    const record = toRecord(value);
+    if (typeof record.packageDir === "string") {
+        return {
+            dir: record.packageDir,
+            legacyManifest: legacyPackageManifest(record),
+        };
+    }
+    if (typeof record.dir === "string") {
+        return {
+            dir: record.dir,
+            legacyManifest: legacyPackageManifest(record),
+        };
+    }
+    return undefined;
+}
+function legacyPackageManifest(record) {
+    if (typeof record.name !== "string") {
+        return undefined;
+    }
+    const manifest = { name: record.name };
+    const agent = toRecord(record.agent);
+    if (typeof agent.acpEntrypoint === "string") {
+        manifest.agent = {
+            acpEntrypoint: agent.acpEntrypoint,
+            ...(isStringRecord(agent.env) ? { env: agent.env } : {}),
+            ...(Array.isArray(agent.launchArgs) &&
+                agent.launchArgs.every((arg) => typeof arg === "string")
+                ? { launchArgs: agent.launchArgs }
+                : {}),
+            ...(typeof agent.snapshot === "boolean" ? { snapshot: agent.snapshot } : {}),
+        };
+    }
+    return manifest;
+}
+function readPackageManifestForClient(ref) {
+    return tryReadAgentosPackageManifest(ref.dir) ?? ref.legacyManifest;
+}
+function isStringRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
 function parseAcpJson(value, context) {
     if (value === null) {
         return undefined;
@@ -165,11 +215,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;
         }
@@ -181,6 +231,9 @@ class BoundedSet {
     has(value) {
         return this.#entries.has(value);
     }
+    get(value) {
+        return this.#entries.get(value);
+    }
     delete(value) {
         return this.#entries.delete(value);
     }
@@ -228,6 +281,7 @@ function sessionEntryFromInit(sessionId, agentType, initData) {
         agentInfo: initData.agentInfo ?? null,
         eventHandlers: new Set(),
         permissionHandlers: new Set(),
+        warnedNoPermissionHandler: false,
         configOverrides: new Map(),
         pendingPermissionReplies: new Map(),
     };
@@ -396,7 +450,31 @@ const KERNEL_POSIX_BOOTSTRAP_DIRS = [
     "/var/tmp",
     "/etc/agentos",
 ];
-const NODE_RUNTIME_BOOTSTRAP_COMMANDS = ["node", "npm", "npx"];
+// 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 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");
@@ -409,114 +487,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 ?? []) {
@@ -539,16 +509,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 = []) {
     const includesBundledBaseLayer = !(config?.disableDefaultBaseLayer ?? false);
     const existingPaths = collectConfiguredLowerPaths(config);
-    if (includesBundledBaseLayer) {
-        for (const entry of getBaseFilesystemEntries()) {
-            existingPaths.add(entry.path);
-        }
-    }
     const entries = [
         {
             path: "/",
@@ -558,18 +527,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({
@@ -712,28 +687,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 [];
@@ -816,26 +769,6 @@ function collectSidecarMountPlan(options) {
         }
         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",
@@ -1527,9 +1460,13 @@ 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;
+    /** Command names linked into `/opt/agentos/bin` at runtime (via the sidecar). */
+    _linkedCommands = new Set();
     _acpTerminals = new Map();
     _acpTerminalCounter = 0;
     _softwareRoots;
@@ -1548,8 +1485,9 @@ export class AgentOs {
     _sidecarVm;
     _disposeSidecarEventListener;
     _agentStderrHandler;
+    _agentExitHandler;
     _limitWarningHandler;
-    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, additionalInstructions, agentStderrHandler, limitWarningHandler) {
+    constructor(kernel, sidecar, softwareRoots, softwareAgentConfigs, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, additionalInstructions, agentStderrHandler, agentExitHandler, limitWarningHandler) {
         this.#kernel = kernel;
         this.sidecar = sidecar;
         this._softwareRoots = softwareRoots;
@@ -1562,6 +1500,7 @@ export class AgentOs {
         this._sidecarVm = sidecarVm;
         this._additionalInstructions = additionalInstructions;
         this._agentStderrHandler = agentStderrHandler;
+        this._agentExitHandler = agentExitHandler;
         this._limitWarningHandler = limitWarningHandler;
         this._disposeSidecarEventListener = this._sidecarClient.onEvent((event) => {
             this._handleSidecarEvent(event);
@@ -1581,13 +1520,45 @@ export class AgentOs {
     }
     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 —
+        // 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 ? [] : await resolveDefaultSoftware();
         const software = options?.defaultSoftware === false
             ? (options.software ?? [])
-            : [commonSoftware, ...(options?.software ?? [])];
-        const processed = processSoftware(software);
+            : [...defaultSoftware, ...(options?.software ?? [])];
+        // Package dirs are projected by the SIDECAR: the client forwards only
+        // `{dir}` over `configureVm` and the sidecar reads package metadata from
+        // `<dir>/agentos-package.json`.
+        const flatSoftware = software.flat();
+        const packageRefs = flatSoftware.flatMap((entry) => {
+            const ref = normalizePackageRef(entry);
+            return ref ? [ref] : [];
+        });
+        const sidecarPackages = packageRefs.map((ref) => ({ dir: ref.dir }));
+        // All package software is projected into `/opt/agentos` by the sidecar. The
+        // client stages nothing host-side; it only derives the agent configs.
+        const agentConfigs = new Map();
+        // Register `/opt/agentos` agent packages so `createSession(<name>)`
+        // launches via `/opt/agentos/bin/<acpEntrypoint>`. The wire no longer
+        // carries agent metadata; read it from the package manifest.
+        for (const ref of packageRefs) {
+            const manifest = readPackageManifestForClient(ref);
+            if (!manifest?.agent)
+                continue;
+            agentConfigs.set(manifest.name, {
+                adapterEntrypoint: `${OPT_AGENTOS_BIN}/${manifest.agent.acpEntrypoint}`,
+                launchArgs: manifest.agent.launchArgs,
+                defaultEnv: manifest.agent.env,
+            });
+        }
         // Agent-SDK snapshot bundle (loaded once per sidecar into the V8 startup
         // snapshot, reused across sessions) for any snapshot-enabled agent.
-        const snapshotUserlandCode = resolveAgentSnapshotBundle(software);
+        const snapshotUserlandCode = resolveAgentSnapshotBundle(packageRefs.map((ref) => ({ packageDir: ref.dir })));
         const localMounts = await resolveCompatLocalMounts(options?.mounts);
         const toolKits = options?.toolKits;
         if (toolKits && toolKits.length > 0) {
@@ -1597,13 +1568,12 @@ export class AgentOs {
         // 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,
-                ...toolBootstrapCommands,
-            ]);
+            const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem, [...RUNTIME_BOOTSTRAP_COMMANDS, ...toolBootstrapCommands]);
             let toolReference = "";
             let rootBridge = null;
             let kernel = null;
@@ -1621,14 +1591,47 @@ export class AgentOs {
                     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);
+                // Guest command paths. The sidecar owns the `/opt/agentos` projection,
+                // but the client's command map (rpc-client) still needs to KNOW the
+                // projected command names so its shell-exec guard (`this.commands.has("sh")`)
+                // and wasmvm routing work. Seed each projected package's commands from its
+                // `bin` map (mirroring the sidecar projection's command derivation), mapped
+                // to their projected `/opt/agentos/bin/<cmd>` path. Tool-shim commands are
+                // added below.
+                const commandGuestPaths = new Map();
+                const deriveProjectedCommandNames = (dir) => {
+                    try {
+                        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+                        if (pkg.bin && typeof pkg.bin === "object") {
+                            return Object.keys(pkg.bin);
+                        }
+                        if (typeof pkg.bin === "string") {
+                            const base = pkg.name?.split("/").pop();
+                            if (base)
+                                return [base];
+                        }
+                    }
+                    catch {
+                        // no/invalid package.json — fall through to the bin/ scan
+                    }
+                    try {
+                        return readdirSync(join(dir, "bin"));
+                    }
+                    catch {
+                        return [];
+                    }
+                };
+                for (const ref of packageRefs) {
+                    for (const cmd of deriveProjectedCommandNames(ref.dir)) {
+                        commandGuestPaths.set(cmd, `/opt/agentos/bin/${cmd}`);
+                    }
+                }
                 const requestedMounts = options?.moduleAccessCwd
                     ? [
                         ...(options.mounts ?? []),
@@ -1644,8 +1647,6 @@ export class AgentOs {
                     : options?.mounts;
                 const { sidecarMounts, hostMounts, hostPathMappings } = collectSidecarMountPlan({
                     mounts: requestedMounts,
-                    softwareRoots: processed.softwareRoots,
-                    commandDirs: preparedCommandDirs.commandDirs,
                     shimDir: toolShimDir,
                 });
                 // Reuse the sidecar handle's single shared native process; this VM
@@ -1672,6 +1673,7 @@ export class AgentOs {
                     // emulation), matching the prior behavior where Agent OS only
                     // constrained the builtin allow-list.
                     ...(options?.allowedNodeBuiltins !== undefined ||
+                        options?.highResolutionTime !== undefined ||
                         snapshotUserlandCode !== undefined
                         ? {
                             jsRuntime: {
@@ -1680,6 +1682,9 @@ export class AgentOs {
                                 ...(options?.allowedNodeBuiltins !== undefined
                                     ? { allowedBuiltins: options.allowedNodeBuiltins }
                                     : {}),
+                                ...(options?.highResolutionTime !== undefined
+                                    ? { highResolutionTime: options.highResolutionTime }
+                                    : {}),
                                 ...(snapshotUserlandCode !== undefined
                                     ? { snapshotUserlandCode }
                                     : {}),
@@ -1701,8 +1706,10 @@ export class AgentOs {
                 await client.configureVm(session, nativeVm, {
                     mounts: sidecarMounts,
                     permissions: sidecarPermissions,
-                    commandPermissions: processed.commandPermissions,
+                    commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
+                    packages: sidecarPackages,
+                    packagesMountAt: OPT_AGENTOS_ROOT,
                 });
                 if (toolKits && toolKits.length > 0) {
                     toolReference = await registerToolkitsOnSidecar(client, session, nativeVm, toolKits);
@@ -1720,7 +1727,7 @@ export class AgentOs {
                     localMounts,
                     sidecarMounts,
                     permissions: sidecarPermissions,
-                    commandPermissions: processed.commandPermissions,
+                    commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     commandGuestPaths,
                     onDispose: cleanup,
@@ -1738,7 +1745,7 @@ export class AgentOs {
                     rootView: rootBridge.createRootView(),
                     sidecarMounts,
                     sidecarPermissions,
-                    commandPermissions: processed.commandPermissions,
+                    commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     sidecarClient: client,
                     sidecarSession: session,
@@ -1789,7 +1796,7 @@ export class AgentOs {
                 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, options?.additionalInstructions, options?.onAgentStderr ?? defaultAgentStderrHandler, options?.onLimitWarning);
+            const vm = new AgentOs(vmAdmin.kernel, sidecar, [], agentConfigs, 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;
@@ -1858,14 +1865,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) {
@@ -2156,15 +2163,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);
@@ -2178,7 +2194,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) {
@@ -2197,6 +2213,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);
@@ -2311,22 +2342,70 @@ export class AgentOs {
         }
         return session;
     }
+    /**
+     * 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, { dir: ref.dir });
+        for (const command of commands) {
+            this._linkedCommands.add(command);
+        }
+        const manifest = readPackageManifestForClient(ref);
+        if (manifest?.agent) {
+            this._softwareAgentConfigs.set(manifest.name, {
+                adapterEntrypoint: `${OPT_AGENTOS_BIN}/${manifest.agent.acpEntrypoint}`,
+                launchArgs: manifest.agent.launchArgs,
+                defaultEnv: manifest.agent.env,
+            });
+        }
+    }
     /** Returns all registered agents with their installation status. */
     listAgents() {
-        // Collect all agent IDs from both package configs and hardcoded configs.
+        // Collect agent IDs from package configs, the hardcoded configs, and the
+        // @agentos-software/* agent dependencies (linked lazily on first
+        // createSession — see createSession).
+        const dependencyAgents = resolveDependencyAgents();
         const allIds = new Set([
             ...this._softwareAgentConfigs.keys(),
-            ...Object.keys(AGENT_CONFIGS),
+            ...dependencyAgents.keys(),
         ]);
         return [...allIds]
             .map((id) => {
-            const config = this._resolveAgentConfig(id);
-            if (!config)
-                return null;
+            let config = this._resolveAgentConfig(id);
+            if (!config) {
+                // Dependency agent not linked yet — report it from its manifest.
+                const dependencyAgent = dependencyAgents.get(id);
+                if (!dependencyAgent)
+                    return null;
+                config = {
+                    adapterEntrypoint: `${OPT_AGENTOS_BIN}/${dependencyAgent.acpEntrypoint}`,
+                };
+            }
+            // An `/opt/agentos` agent package is materialized into the VM at
+            // boot, so it is always "installed" — its adapter is a real command.
+            if (config.adapterEntrypoint || !config.acpAdapter) {
+                return {
+                    id,
+                    adapterEntrypoint: config.adapterEntrypoint,
+                    installed: true,
+                };
+            }
             let installed = false;
             try {
-                // Check software roots first, then the host dir behind the
-                // `/root/node_modules` mount.
+                // Check the software roots that provide this adapter package.
                 const vmPrefix = `/root/node_modules/${config.acpAdapter}`;
                 let hostPkgJsonPath = null;
                 for (const root of this._softwareRoots) {
@@ -2335,12 +2414,6 @@ export class AgentOs {
                         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");
                 }
@@ -2436,6 +2509,60 @@ 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);
@@ -2460,6 +2587,28 @@ export class AgentOs {
             // 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;
@@ -2545,6 +2694,10 @@ export class AgentOs {
                     this._recordAgentStderr(event.val);
                     return;
                 }
+                case "AcpAgentExitedEvent": {
+                    this._recordAgentExit(event.val);
+                    return;
+                }
             }
         }
         catch {
@@ -2760,7 +2913,19 @@ export class AgentOs {
         this._syncSessionState(session, state);
     }
     async createSession(agentType, options) {
-        const config = this._resolveAgentConfig(agentType);
+        let config = this._resolveAgentConfig(agentType);
+        if (!config) {
+            // Lazily link an agent dependency on first use: agent packages are not
+            // projected by default (each carries a full node closure), so resolve
+            // the @agentos-software/* dep whose packed manifest name matches and
+            // link it into the running VM now. linkSoftware registers its
+            // entrypoint/env from the package's own agentos-package.json.
+            const dependencyAgent = resolveDependencyAgents().get(String(agentType));
+            if (dependencyAgent) {
+                await this.linkSoftware({ packageDir: dependencyAgent.packageDir });
+                config = this._resolveAgentConfig(agentType);
+            }
+        }
         if (!config) {
             throw new Error(`Unknown agent type: ${agentType}`);
         }
@@ -2768,15 +2933,14 @@ export class AgentOs {
         // 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 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"),
-            };
+        // Every agent is an `/opt/agentos` package now: the config carries a
+        // pre-resolved guest command path (`adapterEntrypoint`) that the sidecar
+        // spawns directly. There is no npm adapter resolution.
+        const adapterEntrypoint = config.adapterEntrypoint;
+        if (!adapterEntrypoint) {
+            throw new Error(`agent "${String(agentType)}" config has no adapterEntrypoint`);
         }
         const response = await this._sendAcpRequest({
             tag: "AcpCreateSessionRequest",
@@ -2848,21 +3012,20 @@ export class AgentOs {
         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"),
-            };
+        // Every agent is an `/opt/agentos` package now: the config carries a
+        // pre-resolved guest command path (`adapterEntrypoint`). There is no npm
+        // adapter resolution.
+        const adapterEntrypoint = config.adapterEntrypoint;
+        if (!adapterEntrypoint) {
+            throw new Error(`agent "${String(agentType)}" config has no adapterEntrypoint`);
         }
+        const sessionCwd = options?.cwd ?? "/workspace";
         // 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,
+        const launchEnv = {
+            ...config.defaultEnv,
+            ...options?.env,
             [RESUME_ADAPTER_ENTRYPOINT_ENV]: adapterEntrypoint,
         };
         const response = await this._sendAcpRequest({
@@ -2896,65 +3059,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,
@@ -3155,6 +3259,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) => {
@@ -3437,6 +3545,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 {
@@ -3467,12 +3579,12 @@ export class AgentOs {
         }
     }
     /**
-     * Resolve an agent config by ID. Package-provided configs take
-     * precedence over the hardcoded AGENT_CONFIGS.
+     * Resolve an agent config by ID. Agents are /opt/agentos packages
+     * registered from their manifests (explicit software at create, or lazily
+     * linked dependency agents) — there is no hardcoded fallback config.
      */
     _resolveAgentConfig(agentType) {
-        return (this._softwareAgentConfigs.get(agentType) ??
-            AGENT_CONFIGS[agentType]);
+        return this._softwareAgentConfigs.get(agentType);
     }
     /**
      * Gracefully destroy a session: cancel any pending work, close the client,
@@ -3687,6 +3799,88 @@ 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
@@ -3695,6 +3889,7 @@ const sharedSidecars = new Map();
 function ensureSharedSidecarNativeProcess(sidecar) {
     const state = getSidecarState(sidecar);
     if (!state.nativeProcess) {
+        ensureSidecarProcessExitCleanup();
         state.nativeProcess = (async () => {
             const client = SidecarProcess.spawn({
                 cwd: REPO_ROOT,
@@ -3702,8 +3897,39 @@ function ensureSharedSidecarNativeProcess(sidecar) {
                 args: [],
                 frameTimeoutMs: NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
             });
-            const session = await client.authenticateAndOpenSession();
-            return { client, session };
+            // 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 @secure-exec/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 @secure-exec/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;
@@ -3715,6 +3941,14 @@ async function disposeSharedSidecarNativeProcess(state) {
         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();
@@ -3820,6 +4054,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 {
@@ -3844,6 +4090,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 = {
@@ -3855,6 +4105,7 @@ async function leaseAgentOsSidecarVm(sidecar, options) {
     }
     catch (error) {
         await client.dispose().catch(() => { });
+        releaseHold();
         throw error;
     }
 }