@rivet-dev/agentos-core 0.2.22 → 0.4.0

package/dist/agent-os.js

@@ -8,140 +8,12 @@ import { SidecarRejectedError } from "@rivet-dev/agentos-runtime-core/sidecar-er
 import { hostFunctionDescription, resolveHostFunctions, } from "@rivet-dev/agentos-runtime-core/host-functions";
 import { zodToJsonSchema } from "@rivet-dev/agentos-runtime-core/host-functions-zod";
 import { parseAgentOsOptions } from "./options-schema.js";
+import { buildProcessForest } from "./process-forest.js";
 import { getSandboxDisposeHooks, resolveSandboxOptions, } from "./sandbox.js";
 import { resolvePublishedSidecarBinary } from "./sidecar/binary.js";
+import { replayPage, replayPageLimits, replayWirePageLimits, } from "./output-replay.js";
 import { findCargoBinary, resolveCargoBinary } from "./sidecar/cargo.js";
-const ACP_PROTOCOL_VERSION = 1;
-const ACP_EXTENSION_NAMESPACE = "dev.rivet.agent-os.acp";
-const SHELL_DISPOSE_TIMEOUT_MS = 5_000;
-const PROCESS_OUTPUT_EVENT_LIMIT = 1_024;
-function safeWireU64(value) {
-    const result = Number(value);
-    if (!Number.isSafeInteger(result) || result < 0) {
-        throw new RangeError(`wire integer ${value} exceeds JavaScript's safe range`);
-    }
-    return result;
-}
-function decodeDurableSessionInfo(value) {
-    return {
-        sessionId: value.sessionId,
-        agent: value.agent,
-        cwd: value.cwd,
-        additionalDirectories: JSON.parse(value.additionalDirectories),
-        state: JSON.parse(value.state),
-        latestSequence: safeWireU64(value.latestSequence),
-        title: value.title ?? undefined,
-        metadata: value.metadata === null ? undefined : JSON.parse(value.metadata),
-        createdAt: value.createdAt,
-        updatedAt: value.updatedAt,
-    };
-}
-const PERMISSION_TERMINAL_REASONS = new Set([
-    "already_resolved",
-    "prompt_cancelled",
-    "adapter_exited",
-    "session_deleted",
-    "vm_shutdown",
-    "request_not_found",
-]);
-function permissionTerminalReason(value) {
-    if (value !== null &&
-        PERMISSION_TERMINAL_REASONS.has(value)) {
-        return value;
-    }
-    throw new Error(`invalid permission terminal reason: ${value ?? "missing"}`);
-}
-function decodeDurableSessionEvent(value) {
-    const envelope = {
-        durability: "durable",
-        sessionId: value.sessionId,
-        sequence: safeWireU64(value.sequence),
-        timestamp: value.timestamp,
-    };
-    switch (value.event.tag) {
-        case "AcpDurableSessionUpdate": {
-            const update = JSON.parse(value.event.val.update);
-            const { sessionUpdate: type, ...payload } = update;
-            return {
-                ...envelope,
-                type,
-                ...payload,
-            };
-        }
-        case "AcpDurablePermissionRequest": {
-            const request = JSON.parse(value.event.val.request);
-            const { sessionId: _sessionId, ...payload } = request;
-            return {
-                ...envelope,
-                type: "permission_request",
-                requestId: value.event.val.requestId,
-                ...payload,
-            };
-        }
-        case "AcpDurablePermissionResponse": {
-            const status = value.event.val.status;
-            if (status !== "accepted" && status !== "not_pending") {
-                throw new Error(`invalid permission response event status: ${status}`);
-            }
-            const response = JSON.parse(value.event.val.response);
-            return {
-                ...envelope,
-                type: "permission_response",
-                requestId: value.event.val.requestId,
-                ...response,
-                status,
-                ...(value.event.val.reason === null
-                    ? {}
-                    : { reason: permissionTerminalReason(value.event.val.reason) }),
-            };
-        }
-    }
-}
-function normalizeSessionCapabilities(value) {
-    const capabilities = toRecord(value);
-    const prompt = toRecord(capabilities.promptCapabilities);
-    const mcp = toRecord(capabilities.mcpCapabilities);
-    const session = toRecord(capabilities.sessionCapabilities);
-    const extensions = Object.fromEntries(Object.entries(capabilities).filter(([key]) => ![
-        "loadSession",
-        "promptCapabilities",
-        "mcpCapabilities",
-        "sessionCapabilities",
-    ].includes(key)));
-    return {
-        protocolVersion: ACP_PROTOCOL_VERSION,
-        loadSession: capabilities.loadSession === true,
-        ...(Object.keys(prompt).length > 0
-            ? {
-                prompt: {
-                    audio: prompt.audio === true || undefined,
-                    embeddedContext: prompt.embeddedContext === true || undefined,
-                    image: prompt.image === true || undefined,
-                },
-            }
-            : {}),
-        ...(Object.keys(mcp).length > 0
-            ? {
-                mcp: {
-                    http: mcp.http === true || undefined,
-                    sse: mcp.sse === true || undefined,
-                },
-            }
-            : {}),
-        ...(Object.keys(session).length > 0
-            ? {
-                session: {
-                    list: typeof session.list === "object" || undefined,
-                    resume: typeof session.resume === "object" || undefined,
-                    close: typeof session.close === "object" || undefined,
-                    delete: typeof session.delete === "object" || undefined,
-                    additionalDirectories: typeof session.additionalDirectories === "object" || undefined,
-                },
-            }
-            : {}),
-        ...(Object.keys(extensions).length > 0 ? { extensions } : {}),
-    };
-}
+const VM_DISPOSE_DRAIN_TIMEOUT_MS = 5_000;
 async function waitForTrackedExitPromises(promises, timeoutMs) {
     if (promises.length === 0) {
         return;
@@ -168,60 +40,9 @@ import { resolveDefaultSoftware } from "./default-software.js";
 import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-snapshot.js";
 import { serializeMountConfigForSidecar, } from "./js-bridge.js";
 import { createSnapshotExport, } from "./layers.js";
-import { decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agentos-protocol.js";
+import { allowAll } from "./runtime-compat.js";
 import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
 import { createAgentOsSidecarClient, NativeSidecarKernelProxy, SidecarProcess, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
-function defaultAgentStderrHandler(event) {
-    process.stderr.write(event.chunk);
-}
-function defaultAgentExitHandler(event) {
-    process.stderr.write(`[agentos] agent adapter exited unexpectedly: session=${event.sessionId} agent=${event.agentType} exitCode=${event.exitCode ?? "unknown"}; restore explicitly before retrying\n`);
-}
-class AcpDispatchError extends Error {
-    code;
-    data;
-    constructor(code, message, data) {
-        super(message);
-        this.name = "AcpDispatchError";
-        this.code = code;
-        this.data = data;
-    }
-}
-function toJsonRpcNotification(value) {
-    if (!value ||
-        typeof value !== "object" ||
-        Array.isArray(value) ||
-        value.jsonrpc !== "2.0" ||
-        typeof value.method !== "string") {
-        throw new Error("Invalid JSON-RPC notification from sidecar");
-    }
-    return value;
-}
-function toJsonRpcResponse(value) {
-    if (!value ||
-        typeof value !== "object" ||
-        Array.isArray(value) ||
-        value.jsonrpc !== "2.0" ||
-        !(typeof value.id === "number" ||
-            typeof value.id === "string" ||
-            value.id === null)) {
-        throw new Error("Invalid JSON-RPC response from sidecar");
-    }
-    return value;
-}
-function toJsonRpcRequest(value) {
-    if (!value ||
-        typeof value !== "object" ||
-        Array.isArray(value) ||
-        value.jsonrpc !== "2.0" ||
-        !(typeof value.id === "number" ||
-            typeof value.id === "string" ||
-            value.id === null) ||
-        typeof value.method !== "string") {
-        throw new Error("Invalid JSON-RPC request from ACP callback");
-    }
-    return value;
-}
 function toRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -250,6 +71,8 @@ function normalizePackageRef(value) {
     return undefined;
 }
 const CLOSED_SHELL_ID_RETENTION_LIMIT = 2048;
+const TERMINAL_LIMIT = 1024;
+const PROCESS_REGISTRY_LIMIT = 1024;
 class BoundedSet {
     limit;
     #entries = new Map();
@@ -464,18 +287,8 @@ const KERNEL_POSIX_BOOTSTRAP_DIR_METADATA = {
     "/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_BINARY = join(REPO_ROOT, "target/debug/agentos-native-sidecar");
 const SIDECAR_BUILD_INPUTS = [
     join(REPO_ROOT, "Cargo.toml"),
     join(REPO_ROOT, "Cargo.lock"),
@@ -483,8 +296,6 @@ const SIDECAR_BUILD_INPUTS = [
     join(REPO_ROOT, "crates/build-support"),
     join(REPO_ROOT, "crates/execution"),
     join(REPO_ROOT, "crates/kernel"),
-    join(REPO_ROOT, "crates/agentos-protocol"),
-    join(REPO_ROOT, "crates/agentos-sidecar"),
     join(REPO_ROOT, "crates/native-sidecar"),
     join(REPO_ROOT, "crates/native-sidecar-core"),
     join(REPO_ROOT, "crates/sidecar-protocol"),
@@ -653,13 +464,13 @@ function ensureNativeSidecarBinary() {
     if (sidecarBinaryNeedsBuild()) {
         const cargoBinary = findCargoBinary();
         if (cargoBinary) {
-            execFileSync(cargoBinary, ["build", "-q", "-p", "agentos-sidecar"], {
+            execFileSync(cargoBinary, ["build", "-q", "-p", "agentos-native-sidecar"], {
                 cwd: REPO_ROOT,
                 stdio: "pipe",
             });
         }
         else if (!existsSync(SIDECAR_BINARY)) {
-            execFileSync(resolveCargoBinary(), ["build", "-q", "-p", "agentos-sidecar"], {
+            execFileSync(resolveCargoBinary(), ["build", "-q", "-p", "agentos-native-sidecar"], {
                 cwd: REPO_ROOT,
                 stdio: "pipe",
             });
@@ -944,8 +755,15 @@ async function handleHostCallback(request, context) {
             error: `unsupported sidecar request type: ${payload.type}`,
         };
     }
-    const command = parseHostCommandCallbackInput(payload.input);
-    if (command) {
+    if (payload.callback_key === "agentos") {
+        const command = parseHostCommandCallbackInput(payload.input);
+        if (!command || command.command !== payload.callback_key) {
+            return {
+                type: "host_callback_result",
+                invocation_id: payload.invocation_id,
+                error: `Invalid registry callback for "${payload.callback_key}"`,
+            };
+        }
         try {
             return {
                 type: "host_callback_result",
@@ -969,8 +787,9 @@ async function handleHostCallback(request, context) {
             error: `Unknown host function "${payload.callback_key}"`,
         };
     }
-    // The sidecar checks the `hostFunction` permission scope before it forwards a
-    // host function call, so a call that reaches the host is already permitted.
+    // The sidecar authorizes this exact callback key before forwarding it. Never
+    // reinterpret direct callback input as a registry command: a valid function
+    // schema may itself accept command-shaped data.
     const parsed = definition.inputSchema.safeParse(payload.input);
     if (!parsed.success) {
         return {
@@ -1594,22 +1413,25 @@ function mapExecutionCompletedEvent(event) {
 export class AgentOs {
     #kernel;
     sidecar;
-    _durableSessionEventHandlers = new Map();
-    _agentExitHandlers = new Map();
     _processes = new Map();
     _languageProcesses = new Map();
     _languageProcessIds = new Map();
+    _pendingProcessRegistrations = 0;
     _executionOutputHandlers = new Map();
     _executionCompletedHandlers = new Map();
+    // No completion event can arrive after the sidecar exits, so its close
+    // rejects every execution still waiting for one.
+    _pendingCompletionRejects = new Set();
     _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);
+    _closedShellErrors = new BoundedSet(CLOSED_SHELL_ID_RETENTION_LIMIT);
     _pendingShellExitPromises = new Set();
     _shellCounter = 0;
-    _acpTerminals = new Map();
-    _acpTerminalCounter = 0;
     _softwareRoots;
+    _installedSoftware = new Map();
+    _vmMutationActive = false;
     _cronManager;
     _hostFunctions = [];
     _hostFunctionReference = "";
@@ -1621,8 +1443,7 @@ export class AgentOs {
     _sidecarSession;
     _sidecarVm;
     _disposeSidecarEventListener;
-    _agentStderrHandler;
-    _agentExitHandler;
+    _disposeSidecarCloseListener;
     _limitWarningHandler;
     _disposeHooks = [];
     /**
@@ -1714,31 +1535,16 @@ export class AgentOs {
     software = {
         list: this._listSoftware.bind(this),
         link: this._linkSoftware.bind(this),
-    };
-    agents = {
-        list: this._listAgents.bind(this),
-    };
-    sessions = {
-        open: this._openSession.bind(this),
-        get: this._getSession.bind(this),
-        list: this._listSessions.bind(this),
-        delete: this._deleteSession.bind(this),
-        unload: this._unloadSession.bind(this),
-        prompt: this._prompt.bind(this),
-        cancelPrompt: this._cancelPrompt.bind(this),
-        respondPermission: this._respondPermission.bind(this),
-        readHistory: this._readHistory.bind(this),
-        getConfig: this._getSessionConfig.bind(this),
-        setConfigOption: this._setSessionConfigOption.bind(this),
-        getCapabilities: this._getSessionCapabilities.bind(this),
-        getAgentInfo: this._getSessionAgentInfo.bind(this),
+        install: this._installSoftware.bind(this),
+        uninstall: this._uninstallSoftware.bind(this),
+        installed: this._installedSoftwareList.bind(this),
     };
     cron = {
         schedule: this._scheduleCron.bind(this),
         list: this._listCronJobs.bind(this),
         cancel: this._cancelCronJob.bind(this),
     };
-    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, agentStderrHandler, agentExitHandler, limitWarningHandler) {
+    constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, limitWarningHandler) {
         this.#kernel = kernel;
         this.sidecar = sidecar;
         this._softwareRoots = softwareRoots;
@@ -1748,12 +1554,14 @@ export class AgentOs {
         this._sidecarClient = sidecarClient;
         this._sidecarSession = sidecarSession;
         this._sidecarVm = sidecarVm;
-        this._agentStderrHandler = agentStderrHandler;
-        this._agentExitHandler = agentExitHandler;
         this._limitWarningHandler = limitWarningHandler;
         this._disposeSidecarEventListener = this._sidecarClient.onEvent((event) => {
             this._handleSidecarEvent(event);
         });
+        this._disposeSidecarCloseListener = this._sidecarClient.onClose((error) => {
+            for (const reject of this._pendingCompletionRejects)
+                reject(error);
+        });
         agentOsRuntimeAdmins.set(this, {
             kernel,
             rootView: rootFilesystem,
@@ -1767,18 +1575,12 @@ export class AgentOs {
     static async getSharedSidecar(options = {}) {
         return getSharedAgentOsSidecarInternal(options);
     }
-    static async create(callerOptions) {
-        // The generic exists only so each `execute` infers its input from its own
-        // `inputSchema`. Past this point the concrete schemas carry no meaning, so
-        // the rest of `create()` works with the plain option type.
-        let options = parseAgentOsOptions(callerOptions);
-        // Default software is FULLY DYNAMIC: this package's own NON-agent
-        // @agentos-software/* dependencies (e.g. common), each default-exporting
-        // its registry-built descriptor. Agent packages are NOT projected here —
-        // openSession({ agent: id }) links the matching agent dependency into the running
-        // VM on first use, so agent closures (and pi's V8 snapshot bundle) only
-        // enter VMs that run them. Unbuilt packages throw with build
-        // instructions; opt out via defaultSoftware: false.
+    static async create(options, 
+    /** @internal Product wrappers select a sidecar-owned default profile here. */
+    defaultsProfile = "agent_os") {
+        options = parseAgentOsOptions(options);
+        // Default software is resolved from immutable `.aospkg` files vendored in
+        // this package. Runtime package resolution never consults npm.
         const defaultSoftware = options?.defaultSoftware === false ? [] : resolveDefaultSoftware();
         const software = options?.defaultSoftware === false
             ? (options.software ?? [])
@@ -1802,9 +1604,7 @@ export class AgentOs {
             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.
+        // client stages nothing host-side and parses no package manifests.
         const localMounts = await resolveCompatLocalMounts(options?.mounts);
         // Keys become command names, so resolve and check them before anything
         // else in `create()` allocates a sidecar or a sandbox.
@@ -1823,10 +1623,6 @@ export class AgentOs {
             // runtime `linkSoftware` appends to that live dir). The client no longer
             // stages packages host-side.
             const hostFunctionBootstrapCommands = collectHostFunctionBootstrapCommands(hostFunctions);
-            const bootstrapCommands = [
-                ...RUNTIME_BOOTSTRAP_COMMANDS,
-                ...hostFunctionBootstrapCommands,
-            ];
             const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem);
             let hostFunctionReference = "";
             let rootBridge = null;
@@ -1842,7 +1638,9 @@ export class AgentOs {
                 cleanedUp = true;
             };
             try {
-                const env = getBaseEnvironment();
+                const env = options?.environment !== undefined
+                    ? { ...options.environment }
+                    : getBaseEnvironment();
                 // Guest command paths. The sidecar owns the `/opt/agentos` projection and
                 // reports the exact projected package commands after `configureVm`.
                 // HostFunction-shim commands are added below.
@@ -1856,16 +1654,27 @@ export class AgentOs {
                 client = shared.client;
                 const session = shared.session;
                 nativeSession = session;
-                const sidecarPermissions = serializePermissionsForSidecar(options?.permissions);
+                const hostPermissions = options?.permissions ?? {
+                    ...allowAll,
+                    binding: "allow",
+                };
+                const sidecarPermissions = options?.permissions
+                    ? serializePermissionsForSidecar(options.permissions)
+                    : undefined;
                 const createVmConfig = {
-                    env,
+                    defaultsProfile,
+                    ...(options?.environment !== undefined
+                        ? { env: { ...options.environment } }
+                        : {}),
                     database: options?.database,
                     ...(options?.user ? { user: options.user } : {}),
                     rootFilesystem: serializeRootFilesystemForSidecar(options?.rootFilesystem, bootstrapLower),
-                    permissions: sidecarPermissions,
+                    ...(sidecarPermissions ? { permissions: sidecarPermissions } : {}),
                     limits: options?.limits,
                     loopbackExemptPorts: options?.loopbackExemptPorts ?? [],
-                    bootstrapCommands,
+                    ...(hostFunctionBootstrapCommands.length > 0
+                        ? { bootstrapCommands: hostFunctionBootstrapCommands }
+                        : {}),
                     ...(options?.rootFilesystem?.type === "native"
                         ? {
                             nativeRoot: {
@@ -1912,7 +1721,7 @@ export class AgentOs {
                     event.ownership.vm_id === nativeVm.vmId, 10_000);
                 const configuredVm = await client.configureVm(session, nativeVm, {
                     mounts: sidecarMounts,
-                    permissions: sidecarPermissions,
+                    permissions: undefined,
                     commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     packages: sidecarPackages,
@@ -1937,7 +1746,7 @@ export class AgentOs {
                     cwd: "/workspace",
                     localMounts,
                     sidecarMounts,
-                    permissions: sidecarPermissions,
+                    permissions: undefined,
                     commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     // Retained for runtime mount reconfigures: `configure_vm` is
@@ -1963,7 +1772,7 @@ export class AgentOs {
                     kernel,
                     rootView: rootBridge.createRootView(),
                     sidecarMounts,
-                    sidecarPermissions,
+                    sidecarPermissions: undefined,
                     commandPermissions: {},
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     sidecarClient: client,
@@ -2014,7 +1823,7 @@ export class AgentOs {
                 createVm: async () => createVmAdmin(),
             });
             const vmAdmin = sidecarLease.admin;
-            const vm = new AgentOs(vmAdmin.kernel, sidecar, [], vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.onAgentStderr ?? defaultAgentStderrHandler, options?.onAgentExit ?? defaultAgentExitHandler, options?.onLimitWarning);
+            const vm = new AgentOs(vmAdmin.kernel, sidecar, [], vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.onLimitWarning);
             vm._sidecarLease = sidecarLease;
             vm._hostFunctions = vmAdmin.hostFunctions;
             vm._hostFunctionReference = vmAdmin.hostFunctionReference;
@@ -2052,10 +1861,7 @@ export class AgentOs {
         let executionId;
         const earlyOutput = [];
         const completedBeforeAdmission = new Set();
-        let resolveCompletion;
-        const completion = new Promise((resolve) => {
-            resolveCompletion = resolve;
-        });
+        const { completion, resolve: resolveCompletion, release: releaseCompletion, } = this._pendingCompletion();
         let warnedAboutEarlyEvents = false;
         const warnAboutEarlyEvents = () => {
             if (warnedAboutEarlyEvents)
@@ -2092,7 +1898,7 @@ export class AgentOs {
             }
             if (event.executionId === executionId) {
                 completed = true;
-                resolveCompletion?.();
+                resolveCompletion();
             }
         });
         let response;
@@ -2102,11 +1908,13 @@ export class AgentOs {
         catch (error) {
             unsubscribeOutput();
             unsubscribeCompleted();
+            releaseCompletion();
             throw error;
         }
         if (response.type !== "execution_accepted") {
             unsubscribeOutput();
             unsubscribeCompleted();
+            releaseCompletion();
             throw new Error(`unexpected execution response: ${response.type}`);
         }
         const descriptor = response.response.execution;
@@ -2117,7 +1925,7 @@ export class AgentOs {
         }
         completed = completedBeforeAdmission.has(executionId);
         if (completed)
-            resolveCompletion?.();
+            resolveCompletion();
         const abort = () => {
             // Admitted executions report cancellation through their structured result.
             void this._cancelExecution(response.response.operationId).catch((error) => {
@@ -2130,6 +1938,7 @@ export class AgentOs {
         const cleanup = () => {
             unsubscribeOutput();
             unsubscribeCompleted();
+            releaseCompletion();
             options.signal?.removeEventListener("abort", abort);
         };
         if (background) {
@@ -2165,44 +1974,45 @@ export class AgentOs {
         if ("contextId" in options) {
             throw new Error("contextId is not supported for spawned processes; contexts are for attached operations");
         }
+        const releaseRegistrySlot = this._reserveProcessRegistrySlot();
         const executionId = `process-${randomUUID()}`;
         const internalOptions = {
             ...options,
             output: options.output,
         };
-        const admitted = (await this._executionOperation(buildPayload(internalOptions, executionId), internalOptions, true));
-        const descriptor = {
-            pid: admitted.pid,
-            state: "running",
-            language,
-            startedAtMs: admitted.createdAtMs,
-        };
-        this._languageProcesses.set(admitted.pid, {
-            executionId: admitted.executionId,
-            descriptor,
-            outputHandlers: new Set(),
-            exitHandlers: new Set(),
-        });
-        this._languageProcessIds.set(admitted.executionId, admitted.pid);
-        const reconcileCompletion = async () => {
-            if (!this._languageProcesses.get(admitted.pid)?.exit) {
-                await this._waitProcess(admitted.pid);
-            }
-        };
-        if (admitted.completed)
-            await reconcileCompletion();
-        else {
-            void admitted.completion
-                .then(reconcileCompletion)
-                .catch((error) => console.error("[agentos] failed to reconcile spawned process completion", error));
-        }
-        if (options.signal) {
-            const abort = () => {
-                void this._killProcess(admitted.pid);
+        try {
+            const admitted = (await this._executionOperation(buildPayload(internalOptions, executionId), internalOptions, true));
+            const descriptor = {
+                pid: admitted.pid,
+                state: "running",
+                language,
+                startedAtMs: admitted.createdAtMs,
             };
-            options.signal.addEventListener("abort", abort, { once: true });
+            this._languageProcesses.set(admitted.pid, {
+                executionId: admitted.executionId,
+                descriptor,
+                outputHandlers: new Set(),
+                exitHandlers: new Set(),
+            });
+            this._languageProcessIds.set(admitted.executionId, admitted.pid);
+            releaseRegistrySlot();
+            const reconcileCompletion = async () => {
+                if (!this._languageProcesses.get(admitted.pid)?.exit) {
+                    await this._waitProcess(admitted.pid);
+                }
+            };
+            if (admitted.completed)
+                await reconcileCompletion();
+            else {
+                void admitted.completion
+                    .then(reconcileCompletion)
+                    .catch((error) => console.error("[agentos] failed to reconcile spawned process completion", error));
+            }
+            return (this._languageProcesses.get(admitted.pid)?.descriptor ?? descriptor);
+        }
+        finally {
+            releaseRegistrySlot();
         }
-        return this._languageProcesses.get(admitted.pid)?.descriptor ?? descriptor;
     }
     async _exec(command, options = {}) {
         return (await this._executionOperation({
@@ -2564,12 +2374,9 @@ export class AgentOs {
         return response.response.executions.map(mapExecutionDescriptor);
     }
     async _waitExecutionResult(executionId) {
-        let resolveCompletion;
-        const completion = new Promise((resolve) => {
-            resolveCompletion = resolve;
-        });
+        const { completion, resolve: resolveCompletion, release: releaseCompletion, } = this._pendingCompletion();
         const unsubscribe = this._onExecutionCompleted(executionId, () => {
-            resolveCompletion?.();
+            resolveCompletion();
         });
         let response;
         try {
@@ -2587,6 +2394,7 @@ export class AgentOs {
         }
         finally {
             unsubscribe();
+            releaseCompletion();
         }
         if (response.type !== "execution_completed") {
             throw new Error(`unexpected waitExecution response: ${response.type}`);
@@ -2679,6 +2487,24 @@ export class AgentOs {
                 this._executionOutputHandlers.delete(executionId);
         };
     }
+    /** A completion signal that rejects if the sidecar exits before it resolves. */
+    _pendingCompletion() {
+        let resolve;
+        let reject;
+        const completion = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        // Callers await the signal only on some paths; an unawaited rejection
+        // must not surface as an unhandled rejection.
+        completion.catch(() => { });
+        this._pendingCompletionRejects.add(reject);
+        return {
+            completion,
+            resolve,
+            release: () => this._pendingCompletionRejects.delete(reject),
+        };
+    }
     _onExecutionCompleted(executionId, handler) {
         const handlers = this._executionCompletedHandlers.get(executionId) ?? new Set();
         handlers.add(handler);
@@ -2696,8 +2522,7 @@ export class AgentOs {
             args,
             startedAtMs: Date.now(),
             retainEvents,
-            events: [],
-            nextSequence: 0,
+            processId: proc.processId,
             signal: undefined,
             exit: undefined,
             outputHandlers,
@@ -2709,16 +2534,15 @@ export class AgentOs {
         // 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) => {
-            const exit = {
-                pid: proc.pid,
-                outcome: entry.signal ? "signalled" : "exited",
-                exitCode: code,
-                ...(entry.signal ? { signal: entry.signal } : {}),
-            };
-            entry.exit = exit;
-            for (const h of exitHandlers)
-                h(exit);
+        void proc
+            .wait()
+            .then((code) => {
+            this._recordProcessExit(proc.pid, code);
+        })
+            .catch((error) => {
+            // A failed wait is not an exit event. Explicit process.wait calls retain
+            // the error, and callers may still signal an unconfirmed live process.
+            console.error(`[agentOS] process ${proc.pid} exit observation failed`, error);
         });
         return {
             pid: proc.pid,
@@ -2727,46 +2551,123 @@ export class AgentOs {
             startedAtMs: entry.startedAtMs,
         };
     }
+    _recordProcessExit(pid, exitCode) {
+        const entry = this._processes.get(pid);
+        if (!entry || entry.exit)
+            return;
+        const exit = {
+            pid,
+            exitCode,
+            outcome: entry.signal ? "signalled" : "exited",
+            ...(entry.signal ? { signal: entry.signal } : {}),
+        };
+        entry.exit = exit;
+        for (const handler of entry.exitHandlers) {
+            try {
+                handler(exit);
+            }
+            catch (error) {
+                console.error("[agentOS] process exit handler failed", error);
+            }
+        }
+    }
+    _reserveProcessRegistrySlot() {
+        this._pruneExitedProcesses(this._pendingProcessRegistrations + 1);
+        const retained = this._processes.size + this._languageProcesses.size;
+        const admitted = retained + this._pendingProcessRegistrations + 1;
+        if (admitted > PROCESS_REGISTRY_LIMIT) {
+            throw Object.assign(new Error(`process registry limit ${PROCESS_REGISTRY_LIMIT} reached; wait for an exited process to be evicted or raise PROCESS_REGISTRY_LIMIT`), {
+                code: "ERR_AGENTOS_RESOURCE_LIMIT",
+                limitName: "process_registry_entries",
+                configuredLimit: PROCESS_REGISTRY_LIMIT,
+                requested: admitted,
+                configurationPath: "PROCESS_REGISTRY_LIMIT",
+                unit: "processes",
+                scope: "vm",
+                operation: "process.spawn",
+                retryable: true,
+            });
+        }
+        this._pendingProcessRegistrations += 1;
+        if (admitted >= PROCESS_REGISTRY_LIMIT * 0.8) {
+            console.warn("[agentos] process registry admission approaches PROCESS_REGISTRY_LIMIT", { admitted, limit: PROCESS_REGISTRY_LIMIT });
+        }
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            this._pendingProcessRegistrations -= 1;
+        };
+    }
+    _pruneExitedProcesses(reserveSlots) {
+        const retained = this._processes.size + this._languageProcesses.size;
+        const target = Math.max(0, PROCESS_REGISTRY_LIMIT - reserveSlots);
+        let removeCount = retained - target;
+        if (removeCount <= 0)
+            return;
+        const exited = [
+            ...[...this._processes.entries()]
+                .filter(([, entry]) => entry.exit !== undefined)
+                .map(([pid, entry]) => ({
+                kind: "process",
+                pid,
+                startedAtMs: entry.startedAtMs,
+            })),
+            ...[...this._languageProcesses.entries()]
+                .filter(([, entry]) => entry.exit !== undefined)
+                .map(([pid, entry]) => ({
+                kind: "language",
+                pid,
+                startedAtMs: entry.descriptor.startedAtMs,
+            })),
+        ].sort((left, right) => left.startedAtMs - right.startedAtMs || left.pid - right.pid);
+        for (const entry of exited) {
+            if (removeCount <= 0)
+                break;
+            if (entry.kind === "process") {
+                this._processes.delete(entry.pid);
+            }
+            else {
+                const language = this._languageProcesses.get(entry.pid);
+                if (language)
+                    this._languageProcessIds.delete(language.executionId);
+                this._languageProcesses.delete(entry.pid);
+            }
+            removeCount -= 1;
+        }
+    }
     async _spawnProcess(command, args = [], options = {}) {
+        const releaseRegistrySlot = this._reserveProcessRegistrySlot();
         const outputHandlers = new Set();
         const exitHandlers = new Set();
-        const recordOutput = (channel, data) => {
-            const entry = this._processes.get(proc.pid);
-            if (!entry?.retainEvents)
-                return;
-            if (entry.events.length >= PROCESS_OUTPUT_EVENT_LIMIT) {
-                entry.events.shift();
-            }
-            entry.events.push({
-                pid: proc.pid,
-                sequence: entry.nextSequence++,
-                channel,
-                chunk: data,
-                timestampMs: Date.now(),
+        let proc;
+        try {
+            proc = this.#kernel.spawn(command, args, {
+                cwd: options.cwd,
+                env: options.env,
+                stdin: options.stdin,
+                timeout: options.timeoutMs,
+                streamStdin: true,
+                retainOutput: options.output?.retainEvents ?? false,
+                onStdout: (data, metadata) => {
+                    options?.onStdout?.(data);
+                    for (const h of outputHandlers) {
+                        h({ pid: proc.pid, stream: "stdout", data, ...metadata });
+                    }
+                },
+                onStderr: (data, metadata) => {
+                    options?.onStderr?.(data);
+                    for (const h of outputHandlers) {
+                        h({ pid: proc.pid, stream: "stderr", data, ...metadata });
+                    }
+                },
             });
-        };
-        const proc = this.#kernel.spawn(command, args, {
-            cwd: options.cwd,
-            env: options.env,
-            stdin: options.stdin,
-            timeout: options.timeoutMs,
-            streamStdin: true,
-            onStdout: (data) => {
-                recordOutput("stdout", data);
-                options?.onStdout?.(data);
-                for (const h of outputHandlers) {
-                    h({ pid: proc.pid, stream: "stdout", data });
-                }
-            },
-            onStderr: (data) => {
-                recordOutput("stderr", data);
-                options?.onStderr?.(data);
-                for (const h of outputHandlers) {
-                    h({ pid: proc.pid, stream: "stderr", data });
-                }
-            },
-        });
-        return this._trackProcess(proc, command, args, options.output?.retainEvents ?? false, outputHandlers, exitHandlers);
+            return this._trackProcess(proc, command, args, options.output?.retainEvents ?? false, outputHandlers, exitHandlers);
+        }
+        finally {
+            releaseRegistrySlot();
+        }
     }
     spawn(command, args = [], options) {
         return this.process.spawn(command, args, options);
@@ -2825,6 +2726,8 @@ export class AgentOs {
             if (language.exit)
                 return language.exit;
             const result = await this._waitExecutionResult(language.executionId);
+            if (language.exit)
+                return language.exit;
             const exit = {
                 pid,
                 outcome: result.outcome === "timed_out"
@@ -3009,25 +2912,29 @@ export class AgentOs {
      * leaving the mount silently host-only.
      */
     async _mountFs(descriptor) {
-        this._assertSafeAbsolutePath(descriptor.path);
-        if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
-            throw new Error("portable dynamic mounts require the native sidecar");
-        }
-        await this.#kernel.mountDescriptor({
-            guestPath: descriptor.path,
-            readOnly: descriptor.readOnly ?? false,
-            plugin: {
-                id: descriptor.plugin.id,
-                config: descriptor.plugin.config ?? {},
-            },
+        return this._withVmMutation(async () => {
+            this._assertSafeAbsolutePath(descriptor.path);
+            if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
+                throw new Error("portable dynamic mounts require the native sidecar");
+            }
+            await this.#kernel.mountDescriptor({
+                guestPath: descriptor.path,
+                readOnly: descriptor.readOnly ?? false,
+                plugin: {
+                    id: descriptor.plugin.id,
+                    config: descriptor.plugin.config ?? {},
+                },
+            });
         });
     }
     async _unmountFs(path) {
-        this._assertSafeAbsolutePath(path);
-        if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
-            throw new Error("portable dynamic mounts require the native sidecar");
-        }
-        await this.#kernel.unmountDescriptor(path);
+        return this._withVmMutation(async () => {
+            this._assertSafeAbsolutePath(path);
+            if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
+                throw new Error("portable dynamic mounts require the native sidecar");
+            }
+            await this.#kernel.unmountDescriptor(path);
+        });
     }
     async _listMounts() {
         if (!(this.#kernel instanceof NativeSidecarKernelProxy))
@@ -3143,8 +3050,8 @@ export class AgentOs {
     }
     /**
      * Fetch an HTTP endpoint inside the VM while preserving duplicate response
-     * headers and arbitrary binary bodies. agentOS Apps uses this compatibility
-     * surface for its direct actor API.
+     * headers and arbitrary binary bodies. This compatibility surface supports
+     * fetch-like callers that proxy requests into a guest VM.
      */
     async fetch(port, request) {
         const url = new URL(request.url);
@@ -3210,6 +3117,25 @@ export class AgentOs {
         });
     }
     _openTerminal(options) {
+        // Include closed-but-not-yet-exited terminals: close is not proof of exit.
+        if (this._pendingShellExitPromises.size >= TERMINAL_LIMIT) {
+            throw Object.assign(new Error(`terminal limit ${TERMINAL_LIMIT} reached; wait for existing terminals to exit or raise TERMINAL_LIMIT`), {
+                code: "ERR_AGENTOS_RESOURCE_LIMIT",
+                limitName: "active_terminals",
+                configuredLimit: TERMINAL_LIMIT,
+                requested: TERMINAL_LIMIT + 1,
+                configurationPath: "TERMINAL_LIMIT",
+                unit: "terminals",
+                scope: "vm",
+                retryable: true,
+            });
+        }
+        if (this._pendingShellExitPromises.size + 1 >= TERMINAL_LIMIT * 0.8) {
+            console.warn("[agentos] terminal admission approaches TERMINAL_LIMIT; close unused terminals", {
+                active: this._pendingShellExitPromises.size + 1,
+                limit: TERMINAL_LIMIT,
+            });
+        }
         const shellId = `shell-${++this._shellCounter}`;
         this._closedShellIds.delete(shellId);
         const dataHandlers = new Set();
@@ -3249,9 +3175,17 @@ export class AgentOs {
                 handler({ shellId, exitCode });
             return exitCode;
         }, (error) => {
+            this._closedShellErrors.add(shellId, error);
             finalize();
             throw error;
         });
+        // Preserve rejection for wait() without leaving an unobserved promise.
+        void entry.exitPromise.catch((error) => {
+            console.error("[agentos] terminal ended without a confirmed exit", {
+                shellId,
+                error,
+            });
+        });
         this._pendingShellExitPromises.add(entry.exitPromise);
         this._shells.set(shellId, entry);
         return { shellId };
@@ -3317,6 +3251,9 @@ export class AgentOs {
     _waitTerminal(shellId) {
         const entry = this._shells.get(shellId);
         if (!entry) {
+            if (this._closedShellErrors.has(shellId)) {
+                return Promise.reject(this._closedShellErrors.get(shellId));
+            }
             const exitCode = this._closedShellIds.get(shellId);
             if (exitCode !== undefined)
                 return Promise.resolve(exitCode);
@@ -3374,10 +3311,10 @@ export class AgentOs {
     /** Returns info about all processes spawned via spawn(). */
     async _listProcesses() {
         return [
-            ...[...this._processes.values()].map(({ proc, command, startedAtMs }) => ({
+            ...[...this._processes.values()].map(({ proc, command, startedAtMs, exit }) => ({
                 pid: proc.pid,
                 command,
-                state: proc.exitCode === null ? "running" : "exited",
+                state: exit || proc.exitCode !== null ? "exited" : "running",
                 startedAtMs,
             })),
             ...[...this._languageProcesses.values()].map((entry) => entry.descriptor),
@@ -3392,38 +3329,32 @@ export class AgentOs {
     }
     /** Returns processes organized as a tree using ppid relationships. */
     async _processTree() {
-        const all = this._listAllProcesses();
-        const nodeMap = new Map();
-        // Index: create a tree node for each process
-        for (const proc of all) {
-            nodeMap.set(proc.pid, {
-                pid: proc.pid,
-                ppid: proc.ppid,
-                command: proc.command,
-                state: proc.status,
-                startedAtMs: proc.startTime,
-                children: [],
-            });
-        }
+        const records = this.#kernel instanceof NativeSidecarKernelProxy
+            ? this.#kernel.snapshotProcessTopology()
+            : this._listAllProcesses().map((info) => ({
+                info,
+                key: `kernel:${info.pid}`,
+                parentKey: `kernel:${info.ppid}`,
+            }));
+        const roots = buildProcessForest(records, (proc, children) => ({
+            pid: proc.pid,
+            ppid: proc.ppid,
+            command: proc.command,
+            state: proc.status,
+            startedAtMs: proc.startTime,
+            children,
+        }));
+        const kernelKeys = new Set(records.map((record) => record.key));
         for (const process of this._languageProcesses.values()) {
-            if (!nodeMap.has(process.descriptor.pid)) {
-                nodeMap.set(process.descriptor.pid, {
+            // Language admission returns a raw kernel PID and bypasses the proxy's
+            // synthetic spawn registry. A matching display PID is not identity.
+            if (!kernelKeys.has(`kernel:${process.descriptor.pid}`)) {
+                roots.push({
                     ...process.descriptor,
                     children: [],
                 });
             }
         }
-        // Wire: attach each node to its parent
-        const roots = [];
-        for (const node of nodeMap.values()) {
-            const parent = node.ppid === undefined ? undefined : nodeMap.get(node.ppid);
-            if (parent) {
-                parent.children.push(node);
-            }
-            else {
-                roots.push(node);
-            }
-        }
         return roots;
     }
     /** Returns info about a specific process by PID. Throws if not found. */
@@ -3438,15 +3369,29 @@ export class AgentOs {
         return {
             pid: entry.proc.pid,
             command: entry.command,
-            state: entry.proc.exitCode === null ? "running" : "exited",
+            state: entry.exit || entry.proc.exitCode !== null ? "exited" : "running",
             startedAtMs: entry.startedAtMs,
         };
     }
     async _signalProcess(pid, signal) {
         const language = this._languageProcesses.get(pid);
         if (language) {
+            if (language.exit)
+                return;
             language.signal = signal;
-            await this._signalExecution(language.executionId, signal);
+            try {
+                await this._signalExecution(language.executionId, signal);
+            }
+            catch (error) {
+                if (!(error instanceof SidecarRejectedError) ||
+                    error.detail.code !== "execution_not_running") {
+                    throw error;
+                }
+                // The execution can finish between the local state check and the
+                // signal request. Reconcile its final state and preserve kill/signal's
+                // documented already-exited no-op behavior.
+                await this._waitProcess(pid);
+            }
             return;
         }
         const entry = this._processes.get(pid);
@@ -3471,24 +3416,21 @@ export class AgentOs {
         await this._resizeExecutionPty(language.executionId, size);
     }
     async _readProcessOutput(pid, options = {}) {
+        const { maxEvents } = replayPageLimits(options);
         const language = this._languageProcesses.get(pid);
         if (language) {
             const page = await this._readExecutionOutput(language.executionId, {
+                limit: maxEvents,
                 cursor: options.after === undefined ? undefined : `1:${options.after + 1}`,
             });
-            return {
+            const replay = replayPage(pid, page.events.map((event) => ({
                 pid,
-                events: page.events.map((event) => ({
-                    pid,
-                    sequence: event.sequence,
-                    channel: event.channel,
-                    chunk: event.chunk,
-                    timestampMs: event.timestampMs,
-                })),
-                nextCursor: page.nextCursor,
-                hasMore: page.hasMore,
-                truncated: page.truncated,
-            };
+                sequence: event.sequence,
+                channel: event.channel,
+                chunk: event.chunk,
+                timestampMs: event.timestampMs,
+            })), options, page.truncated ? (options.after ?? -1) + 1 : undefined, page.hasMore);
+            return { ...replay, exitCode: language.exit?.exitCode ?? null };
         }
         const entry = this._processes.get(pid);
         if (!entry)
@@ -3496,315 +3438,125 @@ export class AgentOs {
         if (!entry.retainEvents) {
             throw new Error(`Process ${pid} was not spawned with output.retainEvents enabled`);
         }
-        const after = options.after ?? -1;
-        const events = entry.events.filter((event) => event.sequence > after);
-        return {
-            pid,
-            events,
-            nextCursor: String(events.at(-1)?.sequence ?? after),
-            hasMore: false,
-            truncated: entry.events.length === PROCESS_OUTPUT_EVENT_LIMIT &&
-                after < (entry.events[0]?.sequence ?? 0) - 1,
-        };
-    }
-    async _openSession(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpOpenSessionRequest",
-            val: {
-                sessionId: input.sessionId ?? null,
-                agent: input.agent,
-                cwd: input.cwd ?? null,
-                additionalDirectories: input.additionalDirectories === undefined
-                    ? null
-                    : JSON.stringify(input.additionalDirectories),
-                env: input.env === undefined ? null : JSON.stringify(input.env),
-                mcpServers: input.mcpServers === undefined
-                    ? null
-                    : JSON.stringify(input.mcpServers),
-                permissionPolicy: input.permissionPolicy ?? null,
-                skipOsInstructions: input.skipOsInstructions ?? null,
-                additionalInstructions: combineInstructions(input.additionalInstructions, this._hostFunctionReference) ?? null,
-            },
-        });
-        if (response.tag !== "AcpOpenSessionResponse") {
-            throw new Error(`unexpected openSession response: ${response.tag}`);
+        if (!entry.processId) {
+            throw new Error(`Process ${pid} does not expose a sidecar replay identity`);
         }
-    }
-    async _getSession(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpGetDurableSessionRequest",
-            val: { sessionId: input?.sessionId ?? null },
+        const wireLimits = replayWirePageLimits(options);
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, {
+            type: "read_process_output",
+            process_id: entry.processId,
+            ...(options.after === undefined ? {} : { after: options.after }),
+            max_events: wireLimits.maxEvents,
+            max_bytes: wireLimits.maxBytes,
         });
-        if (response.tag !== "AcpGetDurableSessionResponse") {
-            throw new Error(`unexpected getSession response: ${response.tag}`);
+        if (response.type !== "process_output_page") {
+            throw new Error(`unexpected readProcessOutput response: ${response.type}`);
         }
-        return decodeDurableSessionInfo(response.val.session);
-    }
-    async _listSessions(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpListDurableSessionsRequest",
-            val: { cursor: input?.cursor ?? null, limit: input?.limit ?? null },
-        });
-        if (response.tag !== "AcpListDurableSessionsResponse") {
-            throw new Error(`unexpected listSessions response: ${response.tag}`);
+        const exitCode = response.response.exitCode;
+        if (exitCode !== null && this._processes.get(pid) === entry) {
+            if (this.#kernel instanceof NativeSidecarKernelProxy) {
+                this.#kernel.reconcileReplayExit(entry.processId, exitCode);
+            }
+            this._recordProcessExit(pid, exitCode);
         }
         return {
-            sessions: response.val.sessions.map(decodeDurableSessionInfo),
-            nextCursor: response.val.nextCursor,
+            pid,
+            exitCode,
+            events: response.response.events.map((event) => ({
+                pid,
+                sequence: safeProtocolNumber(event.sequence, "process output sequence"),
+                channel: event.channel.toLowerCase(),
+                chunk: new Uint8Array(event.chunk),
+                timestampMs: safeProtocolNumber(event.timestampMs, "process output timestamp"),
+            })),
+            nextCursor: response.response.nextCursor === null
+                ? null
+                : safeProtocolNumber(response.response.nextCursor, "process output cursor"),
+            hasMore: response.response.hasMore,
+            truncated: response.response.truncated,
         };
     }
-    async _deleteSession(input = {}) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpDeleteSessionRequest",
-            val: { sessionId: input.sessionId ?? null },
-        });
-        if (response.tag !== "AcpDeleteSessionResponse") {
-            throw new Error(`unexpected deleteSession response: ${response.tag}`);
+    async _withVmMutation(operation) {
+        if (this._vmMutationActive) {
+            throw new Error("invalid_state: another VM mount or software mutation is already in progress; wait for it to finish before retrying");
         }
-    }
-    async _unloadSession(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpUnloadSessionRequest",
-            val: { sessionId: input?.sessionId ?? null },
-        });
-        if (response.tag !== "AcpUnloadSessionResponse") {
-            throw new Error(`unexpected unloadSession response: ${response.tag}`);
+        this._vmMutationActive = true;
+        try {
+            return await operation();
         }
-    }
-    async _prompt(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpPromptRequest",
-            val: {
-                sessionId: input.sessionId ?? null,
-                idempotencyKey: input.idempotencyKey ?? null,
-                content: JSON.stringify(input.content),
-            },
-        });
-        if (response.tag !== "AcpPromptResponse") {
-            throw new Error(`unexpected prompt response: ${response.tag}`);
+        finally {
+            this._vmMutationActive = false;
         }
-        return {
-            sessionId: response.val.sessionId,
-            message: response.val.message === null ? null : JSON.parse(response.val.message),
-            stopReason: response.val.stopReason,
-        };
     }
-    async _cancelPrompt(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpCancelPromptRequest",
-            val: { sessionId: input?.sessionId ?? null },
-        });
-        if (response.tag !== "AcpCancelPromptResponse") {
-            throw new Error(`unexpected cancelPrompt response: ${response.tag}`);
-        }
-        if (response.val.status !== "cancelled" &&
-            response.val.status !== "no_active_prompt") {
-            throw new Error(`invalid cancelPrompt status: ${response.val.status}`);
-        }
-        return { status: response.val.status };
-    }
-    async _respondPermission(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpRespondPermissionRequest",
-            val: {
-                sessionId: input.sessionId,
-                requestId: input.requestId,
-                optionId: input.optionId,
-            },
-        });
-        if (response.tag !== "AcpRespondPermissionResponse") {
-            throw new Error(`unexpected respondPermission response: ${response.tag}`);
-        }
-        if (response.val.status !== "accepted" &&
-            response.val.status !== "not_pending") {
-            throw new Error(`invalid respondPermission status: ${response.val.status}`);
-        }
-        if (response.val.status === "accepted") {
-            if (response.val.reason !== null) {
-                throw new Error("accepted permission response must not include a reason");
+    async _linkSoftware(descriptor) {
+        return this._withVmMutation(async () => {
+            // Forward to the sidecar, which owns the `/opt/agentos` projection and
+            // appends the package to its live host-backed staging dir; the commands
+            // appear under `/opt/agentos/bin` immediately. The sidecar rejects a
+            // duplicate command, surfaced here as a thrown error.
+            const commands = await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, descriptor);
+            if (this.#kernel instanceof NativeSidecarKernelProxy) {
+                this.#kernel.registerCommandGuestPaths(new Map(commands.projectedCommands.map((command) => [
+                    command.name,
+                    command.guestPath,
+                ])));
             }
-            return { status: "accepted" };
-        }
-        return {
-            status: "not_pending",
-            reason: permissionTerminalReason(response.val.reason),
-        };
-    }
-    async _readHistory(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpReadHistoryRequest",
-            val: {
-                sessionId: input?.sessionId ?? null,
-                before: input?.before === undefined ? null : BigInt(input.before),
-                after: input?.after === undefined ? null : BigInt(input.after),
-                limit: input?.limit ?? null,
-            },
         });
-        if (response.tag !== "AcpHistoryPageResponse") {
-            throw new Error(`unexpected readHistory response: ${response.tag}`);
-        }
-        return {
-            events: response.val.events.map(decodeDurableSessionEvent),
-            hasMoreBefore: response.val.hasMoreBefore,
-            hasMoreAfter: response.val.hasMoreAfter,
-        };
-    }
-    async _getSessionConfig(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpGetSessionConfigRequest",
-            val: { sessionId: input?.sessionId ?? null },
-        });
-        if (response.tag !== "AcpSessionConfigResponse") {
-            throw new Error(`unexpected getSessionConfig response: ${response.tag}`);
-        }
-        return {
-            revision: safeWireU64(response.val.revision),
-            options: JSON.parse(response.val.options),
-        };
-    }
-    async _setSessionConfigOption(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpSetSessionConfigOptionRequest",
-            val: {
-                sessionId: input.sessionId ?? null,
-                configId: input.configId,
-                value: JSON.stringify(input.value),
-            },
-        });
-        if (response.tag !== "AcpSessionConfigResponse") {
-            throw new Error(`unexpected setSessionConfigOption response: ${response.tag}`);
-        }
-        return {
-            revision: safeWireU64(response.val.revision),
-            options: JSON.parse(response.val.options),
-        };
     }
-    async _getSessionCapabilities(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpGetSessionCapabilitiesRequest",
-            val: { sessionId: input?.sessionId ?? null },
+    async _installSoftware(source) {
+        return this._withVmMutation(async () => {
+            const wireSource = source.type === "url"
+                ? {
+                    type: "url",
+                    url: source.url,
+                    expected_digest: source.expectedDigest,
+                }
+                : {
+                    type: "path",
+                    path: source.path,
+                    expected_digest: source.expectedDigest,
+                };
+            const result = await this._sidecarClient.installPackage(this._sidecarSession, this._sidecarVm, { source: wireSource });
+            const packageInfo = result.package;
+            const installed = {
+                packageId: packageInfo.package_id,
+                digest: packageInfo.digest,
+                sizeBytes: packageInfo.size,
+                packageName: packageInfo.package_name,
+                version: packageInfo.version,
+                commands: [...packageInfo.commands],
+            };
+            this._installedSoftware.set(installed.packageId, installed);
+            if (this.#kernel instanceof NativeSidecarKernelProxy) {
+                this.#kernel.registerCommandGuestPaths(new Map(result.projected_commands.map((command) => [
+                    command.name,
+                    command.guest_path,
+                ])));
+            }
+            return { ...installed, commands: [...installed.commands] };
         });
-        if (response.tag !== "AcpSessionCapabilitiesResponse") {
-            throw new Error(`unexpected getSessionCapabilities response: ${response.tag}`);
-        }
-        return response.val.capabilities === null
-            ? null
-            : normalizeSessionCapabilities(JSON.parse(response.val.capabilities));
     }
-    async _getSessionAgentInfo(input) {
-        const response = await this._sendAcpRequest({
-            tag: "AcpGetSessionAgentInfoRequest",
-            val: { sessionId: input?.sessionId ?? null },
+    async _uninstallSoftware(packageId) {
+        return this._withVmMutation(async () => {
+            const installed = this._installedSoftware.get(packageId);
+            if (!installed)
+                throw new Error(`Software not found: ${packageId}`);
+            const removedCommands = await this._sidecarClient.unlinkPackage(this._sidecarSession, this._sidecarVm, packageId);
+            this._installedSoftware.delete(packageId);
+            if (this.#kernel instanceof NativeSidecarKernelProxy) {
+                this.#kernel.unregisterCommandGuestPaths(removedCommands);
+            }
+            return { ...installed, commands: [...installed.commands] };
         });
-        if (response.tag !== "AcpSessionAgentInfoResponse") {
-            throw new Error(`unexpected getSessionAgentInfo response: ${response.tag}`);
-        }
-        return response.val.agentInfo === null
-            ? null
-            : JSON.parse(response.val.agentInfo);
-    }
-    /** @deprecated Use `sessions.open()`. */
-    openSession(input) {
-        return this.sessions.open(input);
-    }
-    /** @deprecated Use `sessions.get()`. */
-    getSession(input) {
-        return this.sessions.get(input);
-    }
-    /** @deprecated Use `sessions.list()`. */
-    listSessions(input) {
-        return this.sessions.list(input);
-    }
-    /** @deprecated Use `sessions.delete()`. */
-    deleteSession(input = {}) {
-        return this.sessions.delete(input);
-    }
-    /** @deprecated Use `sessions.unload()`. */
-    unloadSession(input) {
-        return this.sessions.unload(input);
-    }
-    /** @deprecated Use `sessions.prompt()`. */
-    prompt(input) {
-        return this.sessions.prompt(input);
     }
-    /** @deprecated Use `sessions.cancelPrompt()`. */
-    cancelPrompt(input) {
-        return this.sessions.cancelPrompt(input);
-    }
-    /** @deprecated Use `sessions.respondPermission()`. */
-    respondPermission(input) {
-        return this.sessions.respondPermission(input);
-    }
-    /** @deprecated Use `sessions.readHistory()`. */
-    readHistory(input) {
-        return this.sessions.readHistory(input);
-    }
-    /** @deprecated Use `sessions.getConfig()`. */
-    getSessionConfig(input) {
-        return this.sessions.getConfig(input);
-    }
-    /** @deprecated Use `sessions.setConfigOption()`. */
-    setSessionConfigOption(input) {
-        return this.sessions.setConfigOption(input);
-    }
-    /** @deprecated Use `sessions.getCapabilities()`. */
-    getSessionCapabilities(input) {
-        return this.sessions.getCapabilities(input);
-    }
-    /** @deprecated Use `sessions.getAgentInfo()`. */
-    getSessionAgentInfo(input) {
-        return this.sessions.getAgentInfo(input);
-    }
-    /**
-     * Dynamically link a software package into the RUNNING VM. The package's
-     * `bin/` commands appear under `/opt/agentos/bin` (on `$PATH`) and its `share/man`
-     * pages under MANPATH immediately — the `/opt/agentos` mount is host-backed, so
-     * writing into its staging dir is reflected live with no reboot. An `agent`
-     * block registers the package for `openSession({ agent: name })`. Persists for the VM's
-     * lifetime (and across a snapshot iff the volume persists).
-     */
-    async _linkSoftware(descriptor) {
-        // Forward to the sidecar, which owns the `/opt/agentos` projection and
-        // appends the package to its live host-backed staging dir; the commands
-        // appear under `/opt/agentos/bin` immediately. The sidecar rejects a
-        // duplicate command, surfaced here as a thrown error.
-        const commands = await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, descriptor);
-        if (this.#kernel instanceof NativeSidecarKernelProxy) {
-            this.#kernel.registerCommandGuestPaths(new Map(commands.projectedCommands.map((command) => [
-                command.name,
-                command.guestPath,
-            ])));
-            // Retain the linked package for runtime mount reconfigures:
-            // `configure_vm` is replace-on-write, so a later `mountFs` that
-            // resent only the boot packages would unproject this one.
-            this.#kernel.registerLinkedPackage(descriptor);
-        }
-        // The client parses no manifests: an `agent` block in the linked package is
-        // picked up by the sidecar (it owns the projected `/opt/agentos` and answers
-        // openSession/listAgents from it). Nothing to record client-side.
+    _installedSoftwareList() {
+        return [...this._installedSoftware.values()]
+            .sort((left, right) => left.packageId.localeCompare(right.packageId))
+            .map((software) => ({ ...software, commands: [...software.commands] }));
     }
     async _listSoftware() {
         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,
-        }));
-    }
     /** @deprecated Use `software.link()`. */
     linkSoftware(descriptor) {
         return this.software.link(descriptor);
@@ -3813,63 +3565,14 @@ export class AgentOs {
     listSoftware() {
         return this.software.list();
     }
-    /** @deprecated Use `agents.list()`. */
-    listAgents() {
-        return this.agents.list();
-    }
-    _recordAgentStderr(event) {
-        if (!event.sessionId) {
-            return;
-        }
-        const handler = this._agentStderrHandler;
-        if (!handler) {
-            return;
-        }
-        try {
-            handler({
-                sessionId: event.sessionId,
-                agentType: event.agentType,
-                processId: event.processId,
-                pid: null,
-                chunk: new Uint8Array(event.chunk),
-            });
-        }
-        catch (error) {
-            console.error("AgentOS stderr handler failed", error);
-        }
-    }
-    _recordAgentExit(event) {
-        const publicEvent = {
-            sessionId: event.sessionId,
-            agentType: event.agentType,
-            processId: event.processId,
-            pid: event.pid,
-            exitCode: event.exitCode,
-            restart: event.restart,
-            restartCount: event.restartCount,
-            maxRestarts: event.maxRestarts,
-        };
-        const handler = this._agentExitHandler;
-        if (handler) {
-            try {
-                handler(publicEvent);
-            }
-            catch (error) {
-                console.error("AgentOS agent-exit handler failed", error);
-            }
-        }
-        for (const key of ["*", event.sessionId]) {
-            for (const subscription of this._agentExitHandlers.get(key) ?? []) {
-                try {
-                    subscription(publicEvent);
-                }
-                catch (error) {
-                    console.error("AgentOS agent-exit subscription failed", error);
-                }
-            }
-        }
-    }
     _handleSidecarEvent(event) {
+        // onEvent is process-wide: execution IDs are only unique inside one VM.
+        // Keep sibling VMs' output/completion and warnings on their own handles.
+        if (event.ownership.scope === "vm" &&
+            (event.ownership.connection_id !== this._sidecarSession.connectionId ||
+                event.ownership.session_id !== this._sidecarSession.sessionId ||
+                event.ownership.vm_id !== this._sidecarVm.vmId))
+            return;
         if (event.payload.type === "execution_output") {
             const output = mapExecutionOutputEvent(event.payload.event);
             const pid = this._languageProcessIds.get(output.executionId);
@@ -3880,6 +3583,8 @@ export class AgentOs {
                         pid,
                         stream: output.channel === "stderr" ? "stderr" : "stdout",
                         data: output.chunk,
+                        sequence: output.sequence,
+                        timestampMs: output.timestampMs,
                     };
                     for (const handler of process.outputHandlers) {
                         try {
@@ -3945,10 +3650,6 @@ export class AgentOs {
             }
             return;
         }
-        if (event.payload.type === "ext") {
-            this._handleAcpExtEvent(event.payload.envelope);
-            return;
-        }
         if (event.payload.type !== "structured") {
             return;
         }
@@ -3977,71 +3678,6 @@ export class AgentOs {
             console.error("AgentOS limit-warning handler failed", error);
         }
     }
-    _handleAcpExtEvent(envelope) {
-        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
-            return;
-        }
-        try {
-            const event = decodeAcpEvent(envelope.payload);
-            switch (event.tag) {
-                case "AcpDurableSessionEvent": {
-                    this._emitDurableSessionEvent(decodeDurableSessionEvent(event.val));
-                    return;
-                }
-                case "AcpEphemeralSessionUpdateEvent": {
-                    const update = JSON.parse(event.val.update);
-                    const { sessionUpdate: type, ...payload } = update;
-                    this._emitDurableSessionEvent({
-                        durability: "ephemeral",
-                        type,
-                        sessionId: event.val.sessionId,
-                        afterSequence: safeWireU64(event.val.afterSequence),
-                        ...payload,
-                    });
-                    return;
-                }
-                case "AcpSessionEvent":
-                    return;
-                case "AcpAgentStderrEvent": {
-                    this._recordAgentStderr(event.val);
-                    return;
-                }
-                case "AcpAgentExitedEvent": {
-                    this._recordAgentExit(event.val);
-                    return;
-                }
-            }
-        }
-        catch (error) {
-            console.error("AgentOS failed to decode an ACP sidecar event", error);
-        }
-    }
-    _emitDurableSessionEvent(entry) {
-        for (const handler of this._durableSessionEventHandlers.get(entry.sessionId) ?? []) {
-            try {
-                handler(entry);
-            }
-            catch (error) {
-                console.error("AgentOS session event handler failed", error);
-            }
-        }
-    }
-    async _sendAcpRequest(request) {
-        const envelope = await this._sidecarClient.extensionRequest(this._sidecarSession, this._sidecarVm, {
-            namespace: ACP_EXTENSION_NAMESPACE,
-            payload: encodeAcpRequest(request),
-        });
-        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
-            throw new Error(`unexpected ACP Ext namespace: ${envelope.namespace}`);
-        }
-        const response = decodeAcpResponse(envelope.payload);
-        if (response.tag === "AcpErrorResponse") {
-            const error = new Error(response.val.message);
-            error.code = response.val.code;
-            throw error;
-        }
-        return response;
-    }
     _installSidecarRequestHandler() {
         const context = {
             hostFunctions: this._hostFunctions,
@@ -4057,386 +3693,15 @@ export class AgentOs {
                         filesystem: this.#kernel.vfs,
                     });
                 case "ext":
-                    return this._handleAcpExtSidecarRequest(request.payload.envelope);
-            }
-        });
-    }
-    async _handleAcpExtSidecarRequest(envelope) {
-        if (envelope.namespace !== ACP_EXTENSION_NAMESPACE) {
-            return {
-                type: "ext_result",
-                envelope: {
-                    namespace: envelope.namespace,
-                    payload: Buffer.from("unknown extension namespace", "utf8"),
-                },
-            };
-        }
-        const callback = decodeAcpCallback(envelope.payload);
-        switch (callback.tag) {
-            case "AcpHostRequestCallback": {
-                const response = await this._dispatchAcpSidecarRequest(toJsonRpcRequest(JSON.parse(callback.val.request)));
-                return {
-                    type: "ext_result",
-                    envelope: {
-                        namespace: ACP_EXTENSION_NAMESPACE,
-                        payload: encodeAcpCallbackResponse({
-                            tag: "AcpHostRequestCallbackResponse",
-                            val: {
-                                response: JSON.stringify(response),
-                            },
-                        }),
-                    },
-                };
-            }
-        }
-    }
-    async _dispatchAcpSidecarRequest(request) {
-        try {
-            const result = await this._handleSupportedAcpSidecarRequest(request);
-            return {
-                jsonrpc: "2.0",
-                id: request.id,
-                result,
-            };
-        }
-        catch (error) {
-            if (error instanceof AcpDispatchError) {
-                return {
-                    jsonrpc: "2.0",
-                    id: request.id,
-                    error: {
-                        code: error.code,
-                        message: error.message,
-                        ...(error.data ? { data: error.data } : {}),
-                    },
-                };
-            }
-            return {
-                jsonrpc: "2.0",
-                id: request.id,
-                error: {
-                    code: -32603,
-                    message: error instanceof Error ? error.message : String(error),
-                },
-            };
-        }
-    }
-    async _handleSupportedAcpSidecarRequest(request) {
-        const params = this._acpParams(request);
-        switch (request.method) {
-            case "fs/read":
-            case "fs/read_text_file":
-                return this._handleAcpReadFile(params);
-            case "fs/write":
-            case "fs/write_text_file":
-                return this._handleAcpWriteFile(params);
-            case "fs/readDir":
-            case "fs/read_dir":
-                return this._handleAcpReadDir(params);
-            case "terminal/create":
-                return this._handleAcpCreateTerminal(params);
-            case "terminal/write":
-                return this._handleAcpWriteTerminal(params);
-            case "terminal/output":
-            case "terminal/read":
-                return this._handleAcpReadTerminal(params);
-            case "terminal/wait_for_exit":
-            case "terminal/waitForExit":
-                return this._handleAcpWaitForTerminalExit(params);
-            case "terminal/kill":
-                return this._handleAcpKillTerminal(params);
-            case "terminal/release":
-            case "terminal/close":
-                return this._handleAcpReleaseTerminal(params);
-            case "terminal/resize":
-                return this._handleAcpResizeTerminal(params);
-            default:
-                throw new AcpDispatchError(-32601, `Method not found: ${request.method}`, {
-                    method: request.method,
-                });
-        }
-    }
-    _acpParams(request) {
-        if (!request.params) {
-            return {};
-        }
-        if (typeof request.params !== "object" ||
-            request.params === null ||
-            Array.isArray(request.params)) {
-            throw new AcpDispatchError(-32602, `${request.method} requires object params`);
-        }
-        return request.params;
-    }
-    _requireAcpStringParam(params, name, method) {
-        const value = params[name];
-        if (typeof value !== "string") {
-            throw new AcpDispatchError(-32602, `${method} requires a string ${name}`);
-        }
-        return value;
-    }
-    _optionalAcpStringParam(params, name, method) {
-        const value = params[name];
-        if (value === undefined || value === null) {
-            return undefined;
-        }
-        if (typeof value !== "string") {
-            throw new AcpDispatchError(-32602, `${method} requires ${name} to be a string when provided`);
-        }
-        return value;
-    }
-    _optionalAcpNumberParam(params, name, method) {
-        const value = params[name];
-        if (value === undefined || value === null) {
-            return undefined;
-        }
-        if (typeof value !== "number" || !Number.isFinite(value)) {
-            throw new AcpDispatchError(-32602, `${method} requires ${name} to be a number when provided`);
-        }
-        return value;
-    }
-    _optionalAcpStringArrayParam(params, name, method) {
-        const value = params[name];
-        if (value === undefined || value === null) {
-            return undefined;
-        }
-        if (!Array.isArray(value) ||
-            value.some((entry) => typeof entry !== "string")) {
-            throw new AcpDispatchError(-32602, `${method} requires ${name} to be an array of strings when provided`);
-        }
-        return [...value];
-    }
-    _optionalAcpEnvParam(params, name, method) {
-        const value = params[name];
-        if (value === undefined || value === null) {
-            return undefined;
-        }
-        if (Array.isArray(value)) {
-            const env = {};
-            for (const entry of value) {
-                if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-                    throw new AcpDispatchError(-32602, `${method} requires ${name} entries to be { name, value } objects`);
-                }
-                const record = entry;
-                if (typeof record.name !== "string" ||
-                    typeof record.value !== "string") {
-                    throw new AcpDispatchError(-32602, `${method} requires ${name} entries to be { name, value } objects`);
-                }
-                env[record.name] = record.value;
-            }
-            return env;
-        }
-        if (typeof value !== "object") {
-            throw new AcpDispatchError(-32602, `${method} requires ${name} to be an object or name/value array`);
-        }
-        const env = {};
-        for (const [key, entryValue] of Object.entries(value)) {
-            if (typeof entryValue !== "string") {
-                throw new AcpDispatchError(-32602, `${method} requires ${name} values to be strings`);
+                    return {
+                        type: "ext_result",
+                        envelope: {
+                            namespace: request.payload.envelope.namespace,
+                            payload: Buffer.from("extension handlers are not configured", "utf8"),
+                        },
+                    };
             }
-            env[key] = entryValue;
-        }
-        return env;
-    }
-    _requireAcpTerminal(params, method) {
-        const terminalId = this._requireAcpStringParam(params, "terminalId", method);
-        const terminal = this._acpTerminals.get(terminalId);
-        if (!terminal) {
-            throw new AcpDispatchError(-32602, `ACP terminal not found: ${terminalId}`);
-        }
-        return terminal;
-    }
-    _appendAcpTerminalOutput(terminal, data) {
-        const chunk = Buffer.from(data).toString("utf8");
-        if (!chunk) {
-            return;
-        }
-        terminal.output += chunk;
-        if (Number.isFinite(terminal.outputByteLimit) &&
-            terminal.outputByteLimit >= 0 &&
-            terminal.output.length > terminal.outputByteLimit) {
-            terminal.output = terminal.output.slice(terminal.output.length - terminal.outputByteLimit);
-            terminal.truncated = true;
-        }
-    }
-    async _handleAcpReadFile(params) {
-        const method = "fs/read";
-        const path = this._requireAcpStringParam(params, "path", method);
-        const line = this._optionalAcpNumberParam(params, "line", method);
-        const limit = this._optionalAcpNumberParam(params, "limit", method);
-        const encoding = this._optionalAcpStringParam(params, "encoding", method);
-        const bytes = await this.readFile(path);
-        if (encoding === "base64") {
-            return { content: Buffer.from(bytes).toString("base64") };
-        }
-        const text = new TextDecoder().decode(bytes);
-        if (line === undefined && limit === undefined) {
-            return { content: text };
-        }
-        const startLine = Math.max(1, Math.trunc(line ?? 1));
-        const lineLimit = limit === undefined
-            ? Number.POSITIVE_INFINITY
-            : Math.max(0, Math.trunc(limit));
-        return {
-            content: text
-                .split("\n")
-                .slice(startLine - 1, startLine - 1 + lineLimit)
-                .join("\n"),
-        };
-    }
-    async _handleAcpWriteFile(params) {
-        const method = "fs/write";
-        const path = this._requireAcpStringParam(params, "path", method);
-        const content = this._requireAcpStringParam(params, "content", method);
-        const encoding = this._optionalAcpStringParam(params, "encoding", method);
-        await this.writeFile(path, encoding === "base64" ? Buffer.from(content, "base64") : content);
-        return null;
-    }
-    async _handleAcpReadDir(params) {
-        const method = "fs/readDir";
-        const path = this._requireAcpStringParam(params, "path", method);
-        const entries = await this._vfs().readDirWithTypes(path);
-        return {
-            entries: entries
-                .filter((entry) => entry.name !== "." && entry.name !== "..")
-                .map((entry) => ({
-                name: entry.name,
-                path: path === "/" ? `/${entry.name}` : `${path}/${entry.name}`,
-                type: entry.isSymbolicLink
-                    ? "symlink"
-                    : entry.isDirectory
-                        ? "directory"
-                        : "file",
-            })),
-        };
-    }
-    _handleAcpCreateTerminal(params) {
-        const method = "terminal/create";
-        const command = this._requireAcpStringParam(params, "command", method);
-        const args = this._optionalAcpStringArrayParam(params, "args", method);
-        const env = this._optionalAcpEnvParam(params, "env", method);
-        const cwd = this._optionalAcpStringParam(params, "cwd", method);
-        const cols = this._optionalAcpNumberParam(params, "cols", method);
-        const rows = this._optionalAcpNumberParam(params, "rows", method);
-        const outputByteLimit = Math.max(0, Math.trunc(this._optionalAcpNumberParam(params, "outputByteLimit", method) ??
-            1_048_576));
-        const terminalId = `acp-terminal-${++this._acpTerminalCounter}`;
-        const terminal = {
-            handle: this.#kernel.openShell({
-                command,
-                ...(args ? { args } : {}),
-                ...(env ? { env } : {}),
-                ...(cwd ? { cwd } : {}),
-                ...(cols !== undefined ? { cols: Math.trunc(cols) } : {}),
-                ...(rows !== undefined ? { rows: Math.trunc(rows) } : {}),
-            }),
-            output: "",
-            truncated: false,
-            outputByteLimit,
-            exitCode: null,
-            waitPromise: Promise.resolve(0),
-        };
-        terminal.handle.onData = (data) => {
-            this._appendAcpTerminalOutput(terminal, data);
-        };
-        terminal.waitPromise = terminal.handle.wait().then((exitCode) => {
-            terminal.exitCode = exitCode;
-            return exitCode;
         });
-        this._acpTerminals.set(terminalId, terminal);
-        return { terminalId };
-    }
-    async _handleAcpWriteTerminal(params) {
-        const method = "terminal/write";
-        const terminal = this._requireAcpTerminal(params, method);
-        const data = this._requireAcpStringParam(params, "data", method);
-        const encoding = this._optionalAcpStringParam(params, "encoding", method);
-        await terminal.handle.write(encoding === "base64" ? Buffer.from(data, "base64") : data);
-        return null;
-    }
-    _handleAcpReadTerminal(params) {
-        const terminal = this._requireAcpTerminal(params, "terminal/output");
-        return {
-            output: terminal.output,
-            truncated: terminal.truncated,
-            ...(terminal.exitCode !== null
-                ? {
-                    exitStatus: {
-                        exitCode: terminal.exitCode,
-                        signal: null,
-                    },
-                }
-                : {}),
-        };
-    }
-    async _handleAcpWaitForTerminalExit(params) {
-        const terminal = this._requireAcpTerminal(params, "terminal/wait_for_exit");
-        const exitCode = await terminal.waitPromise;
-        return { exitCode, signal: null };
-    }
-    _handleAcpKillTerminal(params) {
-        const method = "terminal/kill";
-        const terminal = this._requireAcpTerminal(params, method);
-        const signal = this._optionalAcpNumberParam(params, "signal", method) ?? 15;
-        terminal.handle.kill(Math.trunc(signal));
-        return null;
-    }
-    _handleAcpReleaseTerminal(params) {
-        const method = "terminal/release";
-        const terminalId = this._requireAcpStringParam(params, "terminalId", method);
-        const terminal = this._acpTerminals.get(terminalId);
-        if (!terminal) {
-            throw new AcpDispatchError(-32602, `ACP terminal not found: ${terminalId}`);
-        }
-        if (terminal.exitCode === null) {
-            terminal.handle.kill();
-        }
-        this._acpTerminals.delete(terminalId);
-        return null;
-    }
-    _handleAcpResizeTerminal(params) {
-        const method = "terminal/resize";
-        const terminal = this._requireAcpTerminal(params, method);
-        const cols = this._optionalAcpNumberParam(params, "cols", method);
-        const rows = this._optionalAcpNumberParam(params, "rows", method);
-        if (cols === undefined || rows === undefined) {
-            throw new AcpDispatchError(-32602, `${method} requires numeric cols and rows`);
-        }
-        terminal.handle.resize(Math.trunc(cols), Math.trunc(rows));
-        return null;
-    }
-    onSessionEvent(sessionIdOrHandler, maybeHandler) {
-        const sessionId = typeof sessionIdOrHandler === "string" ? sessionIdOrHandler : "main";
-        const handler = typeof sessionIdOrHandler === "function"
-            ? sessionIdOrHandler
-            : maybeHandler;
-        if (!handler) {
-            throw new TypeError("onSessionEvent requires a handler");
-        }
-        const handlers = this._durableSessionEventHandlers.get(sessionId) ?? new Set();
-        handlers.add(handler);
-        this._durableSessionEventHandlers.set(sessionId, handlers);
-        return () => {
-            handlers.delete(handler);
-            if (handlers.size === 0) {
-                this._durableSessionEventHandlers.delete(sessionId);
-            }
-        };
-    }
-    onAgentExit(sessionIdOrHandler, maybeHandler) {
-        const sessionId = typeof sessionIdOrHandler === "string" ? sessionIdOrHandler : "*";
-        const handler = typeof sessionIdOrHandler === "function"
-            ? sessionIdOrHandler
-            : maybeHandler;
-        if (!handler)
-            throw new TypeError("onAgentExit requires a handler");
-        const handlers = this._agentExitHandlers.get(sessionId) ?? new Set();
-        handlers.add(handler);
-        this._agentExitHandlers.set(sessionId, handlers);
-        return () => {
-            handlers.delete(handler);
-            if (handlers.size === 0)
-                this._agentExitHandlers.delete(sessionId);
-        };
     }
     // ── Cron ────────────────────────────────────────────────────
     /** Schedule a cron job. Returns a handle with the job ID and a cancel method. */
@@ -4469,29 +3734,38 @@ export class AgentOs {
     }
     async dispose() {
         this._cronManager.dispose();
-        for (const [id, entry] of this._shells) {
+        const errors = [];
+        for (const entry of this._shells.values()) {
             entry.handle.kill();
         }
         const shellExitPromises = [...this._pendingShellExitPromises];
+        const runningLanguageProcesses = [
+            ...this._languageProcesses.entries(),
+        ].filter(([, process]) => !process.exit);
+        const languageExitPromises = runningLanguageProcesses.map(([, process]) => new Promise((resolve) => {
+            const handleExit = () => {
+                process.exitHandlers.delete(handleExit);
+                resolve();
+            };
+            process.exitHandlers.add(handleExit);
+        }));
+        const languageKillResults = await Promise.allSettled(runningLanguageProcesses.map(([pid]) => this._killProcess(pid)));
+        errors.push(...languageKillResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []));
+        await waitForTrackedExitPromises([...shellExitPromises, ...languageExitPromises], VM_DISPOSE_DRAIN_TIMEOUT_MS);
         this._shells.clear();
-        const terminalExitPromises = [];
-        for (const terminal of this._acpTerminals.values()) {
-            terminal.handle.kill();
-            terminalExitPromises.push(terminal.waitPromise.then(() => undefined, () => undefined));
-        }
-        this._acpTerminals.clear();
         this._processes.clear();
+        this._languageProcesses.clear();
+        this._languageProcessIds.clear();
         this._executionOutputHandlers.clear();
         this._executionCompletedHandlers.clear();
-        await waitForTrackedExitPromises([...shellExitPromises, ...terminalExitPromises], SHELL_DISPOSE_TIMEOUT_MS);
         this._disposeSidecarEventListener();
+        this._disposeSidecarCloseListener();
         const sidecarLease = this._sidecarLease;
         this._sidecarLease = null;
         const disposeVm = sidecarLease
             ? sidecarLease.dispose()
             : this.#kernel.dispose();
         const hooks = this._disposeHooks.splice(0);
-        const errors = [];
         try {
             await disposeVm;
         }