@evelandhq/sandbox-bwrap 0.1.3 → 0.2.0

package/README.md

@@ -71,20 +71,25 @@ which requires that nothing be left running afterwards, and `stop()`, which auth
 triggers mid-run through `ctx.getSandbox().stop()`. Backends with provider-side compute
 distinguish the two — a container to pause, a VM to snapshot; bwrap has no such resource,
 because the processes are the compute. Neither method touches the session's workspace
-directory — it is durable state, and remains available when the session reattaches or the
-next callback reopens it.
+directory — it is durable state. Cleanup closes that compute generation to new commands;
+the next backend `create()` opens a fresh generation over the same workspace. Repeated
+`create()` calls through one backend instance share the live generation, so one handle
+cannot race a new spawn past another handle's cleanup barrier.
 
 ### Options
 
-| Option             | Default                              | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `env`              | `{}`                                 | Environment variables set for every sandboxed command.                                                                                                                                                                                                                                                                                                                                                                                            |
-| `networkPolicy`    | `"allow-all"`                        | `"allow-all"` shares the host network; `"deny-all"` runs each command with no network (`--unshare-net`). `setNetworkPolicy` can switch between the two at run time; granular domain policies are rejected (use the Vercel backend for those).                                                                                                                                                                                                     |
-| `hidePaths`        | `[]`                                 | Extra host paths hidden from the sandbox (each covered by an empty tmpfs).                                                                                                                                                                                                                                                                                                                                                                        |
-| `bwrapPath`        | `"bwrap"`                            | bwrap executable to invoke.                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `cacheDir`         | `<appRoot>/.eve/sandbox-cache/bwrap` | Absolute directory holding templates and durable session workspaces. Pin this outside the release directory so a redeploy does not discard durable session state: since eve 0.22.0, eve keys session sandboxes per durable session, not per deployment, so an `appRoot`-derived default would silently destroy every session's `/workspace` on the next redeploy. The generated eveland module always sets this from `EVELAND_SANDBOX_CACHE_DIR`. |
-| `templateRevision` | `null`                               | Optional immutable release identity included in the template cache key but not the session path. Change it when seed files change so new Sessions use a fresh template without overwriting durable workspaces. Eveland sets it from its internal `EVELAND_SANDBOX_TEMPLATE_REVISION`.                                                                                                                                                             |
-| `runTimeoutMs`     | `600000`                             | Hard wall-clock limit for one `run()` command. Timeout aborts the command and kills its complete bwrap process group. Set `null` to disable it. The limit deliberately does not apply to `spawn()`, which is the API for long-running processes.                                                                                                                                                                                                  |
+| Option                   | Default                              | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`                    | `{}`                                 | Environment variables set for every sandboxed command.                                                                                                                                                                                                                                                                                                                                                                                            |
+| `networkPolicy`          | `"allow-all"`                        | `"allow-all"` shares the host network; `"deny-all"` runs each command with no network (`--unshare-net`). `setNetworkPolicy` can switch between the two at run time; granular domain policies are rejected (use the Vercel backend for those).                                                                                                                                                                                                     |
+| `hidePaths`              | `[]`                                 | Extra host paths hidden from the sandbox (each covered by an empty tmpfs).                                                                                                                                                                                                                                                                                                                                                                        |
+| `bwrapPath`              | `"bwrap"`                            | bwrap executable to invoke.                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `cacheDir`               | `<appRoot>/.eve/sandbox-cache/bwrap` | Absolute directory holding templates and durable session workspaces. Pin this outside the release directory so a redeploy does not discard durable session state: since eve 0.22.0, eve keys session sandboxes per durable session, not per deployment, so an `appRoot`-derived default would silently destroy every session's `/workspace` on the next redeploy. The generated eveland module always sets this from `EVELAND_SANDBOX_CACHE_DIR`. |
+| `templateRevision`       | `null`                               | Optional immutable release identity included in the template cache key but not the session path. Change it when seed files change so new Sessions use a fresh template without overwriting durable workspaces. Eveland sets it from its internal `EVELAND_SANDBOX_TEMPLATE_REVISION`.                                                                                                                                                             |
+| `runTimeoutMs`           | `600000`                             | Hard wall-clock limit for one `run()` command. Timeout aborts the command and kills its complete bwrap process group. Set `null` to disable it. The limit deliberately does not apply to `spawn()`, which is the API for long-running processes.                                                                                                                                                                                                  |
+| `maxConcurrentProcesses` | `64`                                 | Maximum live `run()`/`spawn()` commands admitted in one compute generation. A live `spawn()` counts until it actually exits, even when its caller never waits. Set `null` to disable.                                                                                                                                                                                                                                                             |
+| `maxOutputBytes`         | `16777216`                           | Maximum combined stdout and stderr retained by one `run()` call. Exceeding it aborts and reaps the complete process group. Set `null` to disable. Streaming `spawn()` output is not retained by this backend.                                                                                                                                                                                                                                     |
+| `onEvent`                | `undefined`                          | Best-effort structured lifecycle sink for generation, command, and cleanup events. Sink failures are ignored so telemetry cannot change command behavior.                                                                                                                                                                                                                                                                                         |
 
 Both lifecycle callbacks may call `use({ networkPolicy: "allow-all" | "deny-all" })`. The
 policy is applied before `use()` returns the template or live Session, so subsequent commands in
@@ -100,34 +105,72 @@ backend's configured policy.
   `<cacheDir>/templates/<hash>` (`<cacheDir>` defaults to
   `<appRoot>/.eve/sandbox-cache/bwrap` when the `cacheDir` option is not set). Idempotent
   per template key + options hash; `templateRevision` participates in that hash.
-- **create** (runtime): clones the template into `<cacheDir>/sessions/<hash>` on first
-  use. The directory IS the durable session state: it persists across reconnects and
-  process restarts.
+- **create** (runtime): atomically clones the template into
+  `<cacheDir>/sessions/<hash>` on first use. It first requests a filesystem reflink
+  (copy-on-write); filesystems without reflink support fall back to a normal recursive
+  copy. The selected strategy is recorded in cache metadata. The directory IS the durable
+  session state: it persists across reconnects and process restarts.
 - **run/spawn**: every command is one transient bwrap invocation —
   read-only host rootfs, the session directory bound read-write at `/workspace`,
   tmpfs `/tmp`, PID/IPC/UTS namespaces unshared, `--die-with-parent`.
-  `run()` also applies `runTimeoutMs` and kills the entire detached process group
-  when the deadline or caller AbortSignal fires; `spawn()` remains unbounded until
-  its holder calls `kill()`, the Session is stopped, or the backend shuts down.
+  `run()` also applies `runTimeoutMs` and `maxOutputBytes`, and kills the entire
+  detached process group when a boundary or caller AbortSignal fires. Both APIs count
+  against `maxConcurrentProcesses`; `spawn()` remains long-running until its holder
+  calls `kill()`, the compute generation is stopped, or the backend shuts down.
 - **File I/O** (`readTextFile`, `writeFile`, …): host-side operations on the session
   directory; no subprocess. Writes outside `/workspace` are refused.
 
 ## Disk usage and cache management
 
-Session and template directories persist indefinitely under
-`<cacheDir>/{sessions,templates}` across process restarts and reconnects, enabling fast
-reattach when a session resumes. Each session key gets a directory that is reused for
-the lifetime of the session; each template is cached per (template key, options hash), with
-an optional release revision in the options hash,
-and reused across sessions. This backend intentionally does not prune either — its
-`stop()` and `shutdown()` methods only kill the session's live processes and leave the
-workspace on disk, so reattach is instant and stateless from the agent's perspective. On a long-lived
-host, this means the cache will grow with the number of durable sessions and unique
-templates, consuming disk space indefinitely. On eveland deployments this cache lives at
-`EVELAND_SANDBOX_CACHE_DIR` (one subdirectory per project), outside every release
-directory, precisely so that redeploying a project does not touch it.
-
-Reclaiming space today requires manual intervention: identify which sessions are known dead and delete their corresponding directories under the cache root. Automatic cache pruning (e.g., based on age or LRU) is a known gap and a planned follow-up.
+Session and template directories persist under `<cacheDir>/{sessions,templates}` across
+process restarts and reconnects, enabling fast reattach. `stop()` and `shutdown()` never
+delete durable state, and this package never schedules automatic deletion. On Eveland,
+the cache lives at `EVELAND_SANDBOX_CACHE_DIR` outside every release directory, so a
+redeploy does not touch it.
+
+Operator metadata lives separately under `<cacheDir>/metadata`; sandboxed code cannot
+rewrite its own retention timestamps, tags, clone strategy, or active-generation leases.
+Use the explicit APIs to inspect and reclaim storage:
+
+```ts
+import { listBwrapCache, pruneBwrapCache } from "@evelandhq/sandbox-bwrap";
+
+const location = { appRoot: "/srv/my-agent", cacheDir: "/var/lib/eveland/sandbox/project" };
+const entries = await listBwrapCache(location);
+
+// Dry-run is the default. Age and LRU policies may be combined independently
+// for durable sessions and templates.
+const preview = await pruneBwrapCache({
+  ...location,
+  sessions: { maxAgeMs: 30 * 24 * 60 * 60 * 1000 },
+  templates: { maxEntries: 10 },
+});
+
+// Apply only after inspecting preview.candidates and preview.skippedActive.
+const applied = await pruneBwrapCache({
+  ...location,
+  sessions: { maxAgeMs: 30 * 24 * 60 * 60 * 1000 },
+  templates: { maxEntries: 10 },
+  dryRun: false,
+});
+```
+
+Active compute generations are skipped and rechecked immediately before deletion. The
+backend uses both process-local reference counts and lease files outside the writable
+workspace, so a separate pruning process can see active sessions. A process crash can
+leave a conservative stale lease; inspect `listBwrapCacheLeases(location)` and confirm
+the owning deployment is stopped before removing such a lease. Leases are not expired
+automatically because deleting a live durable workspace is worse than retaining a false
+positive.
+
+## Lifecycle observability
+
+`onEvent` receives discriminated `generation.started`, `command.started`,
+`command.finished`, `cleanup.started`, `cleanup.completed`, and `cleanup.failed` events.
+They include session/generation/command identities, tags, PID/process-group identity when
+available, duration, output byte counts, live-process counts, finish reason, and cleanup
+errors. Events deliberately omit command text and output. Do not put secrets in `tags`;
+the sink is operator-controlled telemetry, not part of the sandbox boundary.
 
 ## Security boundary
 
@@ -158,8 +201,9 @@ Reclaiming space today requires manual intervention: identify which sessions are
   container's filesystem, not the Docker host; no host root or Docker socket is mounted.
 - CPU, memory, and PID limits are inherited from whatever cgroup the agent runs in
   (on eveland, the deployment's Docker container or systemd unit covers sandbox
-  children too). The backend adds only the `run()` wall-clock deadline; it does not
-  create a per-command cgroup or impose resource quotas on `spawn()`.
+  children too). `maxConcurrentProcesses` is an admission bound, not a kernel PID or
+  thread quota; `runTimeoutMs` and `maxOutputBytes` bound one `run()`. The backend does
+  not create a per-command cgroup or impose CPU/memory quotas on `spawn()`.
 - Host-side write/remove calls (`writeFile`, `writeTextFile`, `writeBinaryFile`,
   `removePath`) verify containment with a realpath-aware check
   (`isWithinWorkspaceReal`): they resolve symlinks along the path and re-check that
@@ -184,8 +228,11 @@ Reclaiming space today requires manual intervention: identify which sessions are
 Eveland's generated local Docker image installs `bubblewrap` and `bash`, creates
 `/workspace`, and starts the outer Agent container with its default capability set
 dropped, `SYS_ADMIN` and `NET_ADMIN` added for bwrap namespaces, `no-new-privileges`,
-and `seccomp=unconfined`. This is a local-development boundary; the supported Linux
-production topology uses the unprivileged systemd path below.
+`seccomp=unconfined`, and Docker `--init`. The init process is required to reap orphaned
+bwrap descendants; without it they can accumulate as zombies until the container PID
+limit is exhausted. Containers created before enabling it must be recreated. This is a
+local-development boundary; the supported Linux production topology uses the
+unprivileged systemd path below, where host PID 1 already reaps orphans.
 
 - Linux with unprivileged user namespaces available to the calling process. Ubuntu's
   packaged bubblewrap (0.9.0-1ubuntu0.1 on 24.04) ships **no** AppArmor profile. Since
@@ -225,7 +272,9 @@ production topology uses the unprivileged systemd path below.
 - Works under systemd hardening (`NoNewPrivileges=yes`, `ProtectSystem=strict`):
   apt's `bwrap` is not setuid, so it needs no privilege escalation to run — but it
   still needs the AppArmor profile above to create a user namespace as an
-  unprivileged user.
+  unprivileged user. There is no Docker-style `--init` setting to add to a systemd
+  Deployment; systemd already provides the host init/subreaper and `TasksMax` cgroup
+  boundary.
 
 ## Testing
 
@@ -236,7 +285,8 @@ production topology uses the unprivileged systemd path below.
   It provisions a Lima VM (`brew install lima`), streams this worktree in, and runs the
   test as an unprivileged user under the systemd hardening a deployed eve agent actually
   gets — `NoNewPrivileges=yes`, `ProtectSystem=strict`, `PrivateTmp=yes`. Prints
-  `BWRAP SMOKE OK`. Run this before pushing anything that touches `src/args.ts` or
+  `BWRAP SMOKE OK`. The test also churns 500 short bwrap commands and checks that the
+  zombie count returns to baseline. Run this before pushing anything that touches `src/args.ts` or
   `src/process.ts`: CI's smoke job covers the unprivileged-user case but not the systemd
   constraints, and argv that looks right is not the same as a kernel that accepts it.
 - `pnpm tsx src/integration/bwrap-backend-smoke.ts` — the same test, run directly. Needs

package/dist/backend.d.ts

@@ -1,6 +1,7 @@
 import type { SandboxBackend } from "eve/sandbox";
 import type { BwrapSandboxCreateOptions, BwrapSandboxUseOptions } from "./options.js";
 import type { ProcessRunner } from "./process.js";
+import { type BwrapDirectoryCopier } from "./cache.js";
 /**
  * Stable backend name. Participates in eve's template/session cache-key
  * derivation and persisted reconnect state — never change it.
@@ -10,5 +11,7 @@ export interface CreateBwrapSandboxBackendInput {
     readonly createOptions?: BwrapSandboxCreateOptions;
     /** Injectable process launcher so backend logic is testable without bwrap. */
     readonly runner?: ProcessRunner;
+    /** Injectable clone primitive for filesystem-capability tests. */
+    readonly copyDirectory?: BwrapDirectoryCopier;
 }
 export declare function createBwrapSandboxBackend(input?: CreateBwrapSandboxBackendInput): SandboxBackend<BwrapSandboxUseOptions, BwrapSandboxUseOptions>;

package/dist/backend.js

@@ -1,37 +1,24 @@
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { cp, mkdir, rename, rm } from "node:fs/promises";
-import { dirname } from "node:path";
+import { mkdir, rename, rm } from "node:fs/promises";
+import { basename } from "node:path";
 import { SandboxTemplateNotProvisionedError } from "eve/sandbox";
 import { createBwrapOptionsHash, resolveBwrapSandboxOptions } from "./options.js";
-import { resolveSessionPath, resolveTemplatePath, WORKSPACE_ROOT } from "./paths.js";
+import { resolveBwrapCacheRoot, resolveSessionPath, resolveTemplatePath, WORKSPACE_ROOT, } from "./paths.js";
 import { createNodeProcessRunner, describeMissingPrereqs, isBwrapAvailable } from "./process.js";
 import { createBwrapSession } from "./session.js";
+import { cloneDirectoryAtomically, createBwrapCacheLease, registerActiveCachePath, touchCacheMetadata, } from "./cache.js";
 const EVE_MODEL_SKILL_ROOT = "$HOME/.agents/skills";
 /**
  * Stable backend name. Participates in eve's template/session cache-key
  * derivation and persisted reconnect state — never change it.
  */
 export const BWRAP_BACKEND_NAME = "bwrap";
-async function copyDirectoryAtomically(sourcePath, targetPath) {
-    const tmpPath = `${targetPath}.${randomUUID()}.tmp`;
-    await mkdir(dirname(targetPath), { recursive: true });
-    try {
-        await cp(sourcePath, tmpPath, { recursive: true });
-        await rename(tmpPath, targetPath);
-    }
-    catch (error) {
-        await rm(tmpPath, { force: true, recursive: true }).catch(() => { });
-        // A concurrent writer winning the rename race is success, not failure.
-        if (existsSync(targetPath))
-            return;
-        throw error;
-    }
-}
 export function createBwrapSandboxBackend(input = {}) {
     const options = resolveBwrapSandboxOptions(input.createOptions);
     const optionsHash = createBwrapOptionsHash(options);
     const runner = input.runner ?? createNodeProcessRunner();
+    const generations = new Map();
     // Probe only when running against the real bwrap; injected runners skip it.
     const shouldProbe = input.runner === undefined;
     let probed = false;
@@ -47,8 +34,42 @@ export function createBwrapSandboxBackend(input = {}) {
             throw new Error(missing);
         probed = true;
     }
-    function openSession(id, workspaceDir, appRoot) {
-        return createBwrapSession({ id, workspaceDir, appRoot, runner, options });
+    function openSession(id, workspaceDir, appRoot, tags, generationId, onStopped) {
+        return createBwrapSession({
+            id,
+            workspaceDir,
+            appRoot,
+            runner,
+            options,
+            tags,
+            generationId,
+            onStopped,
+        });
+    }
+    async function openRuntimeSession(id, workspaceDir, appRoot, tags) {
+        const current = generations.get(workspaceDir);
+        if (current && current.lifecycleState() !== "stopped")
+            return current;
+        const releaseActive = registerActiveCachePath(workspaceDir);
+        const cacheRoot = resolveBwrapCacheRoot(appRoot, options.cacheDir);
+        const activeLease = await createBwrapCacheLease({
+            cacheRoot,
+            sessionId: basename(workspaceDir),
+        });
+        let session;
+        try {
+            session = openSession(id, workspaceDir, appRoot, tags, activeLease.lease.generationId, async () => {
+                releaseActive();
+                await activeLease.release();
+            });
+        }
+        catch (error) {
+            releaseActive();
+            await activeLease.release();
+            throw error;
+        }
+        generations.set(workspaceDir, session);
+        return session;
     }
     function resolveSeedPath(seedPath) {
         if (seedPath === EVE_MODEL_SKILL_ROOT || seedPath.startsWith(`${EVE_MODEL_SKILL_ROOT}/`)) {
@@ -78,8 +99,16 @@ export function createBwrapSandboxBackend(input = {}) {
         async prewarm({ templateKey, bootstrap, seedFiles, log, runtimeContext }) {
             assertBwrapAvailable();
             const templatePath = resolveTemplatePath(runtimeContext.appRoot, templateKey, optionsHash, options.cacheDir);
-            if (existsSync(templatePath))
+            const touchTemplate = async () => await touchCacheMetadata({
+                cacheRoot: resolveBwrapCacheRoot(runtimeContext.appRoot, options.cacheDir),
+                kind: "template",
+                id: basename(templatePath),
+                templateRevision: options.templateRevision,
+            });
+            if (existsSync(templatePath)) {
+                await touchTemplate();
                 return { reused: true };
+            }
             log?.(`bwrap: capturing template for ${templateKey}`);
             const stagingPath = `${templatePath}.staging-${randomUUID()}`;
             await mkdir(stagingPath, { recursive: true });
@@ -94,18 +123,23 @@ export function createBwrapSandboxBackend(input = {}) {
             catch (error) {
                 await rm(stagingPath, { force: true, recursive: true }).catch(() => { });
                 // A concurrent prewarm winning the race is reuse, not failure.
-                if (existsSync(templatePath))
+                if (existsSync(templatePath)) {
+                    await touchTemplate();
                     return { reused: true };
+                }
                 throw error;
             }
+            await touchTemplate();
             return { reused: false };
         },
-        async create({ templateKey, sessionKey, runtimeContext }) {
+        async create({ templateKey, sessionKey, runtimeContext, tags }) {
             assertBwrapAvailable();
             const sessionPath = resolveSessionPath(runtimeContext.appRoot, sessionKey, options.cacheDir);
+            let cloneStrategy = "existing";
             if (!existsSync(sessionPath)) {
                 if (templateKey === null) {
                     await mkdir(sessionPath, { recursive: true });
+                    cloneStrategy = "empty";
                 }
                 else {
                     const templatePath = resolveTemplatePath(runtimeContext.appRoot, templateKey, optionsHash, options.cacheDir);
@@ -115,10 +149,21 @@ export function createBwrapSandboxBackend(input = {}) {
                             templateKey,
                         });
                     }
-                    await copyDirectoryAtomically(templatePath, sessionPath);
+                    cloneStrategy = await cloneDirectoryAtomically({
+                        sourcePath: templatePath,
+                        targetPath: sessionPath,
+                        copyDirectory: input.copyDirectory,
+                    });
                 }
             }
-            const session = openSession(sessionKey, sessionPath, runtimeContext.appRoot);
+            await touchCacheMetadata({
+                cacheRoot: resolveBwrapCacheRoot(runtimeContext.appRoot, options.cacheDir),
+                kind: "session",
+                id: basename(sessionPath),
+                tags,
+                cloneStrategy,
+            });
+            const session = await openRuntimeSession(sessionKey, sessionPath, runtimeContext.appRoot, tags);
             return {
                 session,
                 useSessionFn: async (useOptions) => await useSession(session, useOptions),

package/dist/cache.d.ts

@@ -0,0 +1,75 @@
+export type BwrapCacheEntryKind = "session" | "template";
+export type BwrapCloneStrategy = "empty" | "reflink" | "copy" | "existing";
+export interface BwrapCacheMetadata {
+    readonly schemaVersion: 1;
+    readonly kind: BwrapCacheEntryKind;
+    readonly id: string;
+    readonly createdAt: string;
+    readonly lastUsedAt: string;
+    readonly tags?: Readonly<Record<string, string>>;
+    readonly cloneStrategy?: BwrapCloneStrategy;
+    readonly templateRevision?: string;
+}
+export interface BwrapCacheEntry extends BwrapCacheMetadata {
+    readonly path: string;
+    readonly sizeBytes: number;
+    readonly active: boolean;
+    readonly metadataPresent: boolean;
+}
+export interface BwrapCacheLocation {
+    readonly appRoot: string;
+    readonly cacheDir?: string | null;
+}
+export interface BwrapCachePrunePolicy {
+    readonly maxAgeMs?: number;
+    readonly maxEntries?: number;
+}
+export interface BwrapCachePruneInput extends BwrapCacheLocation {
+    readonly dryRun?: boolean;
+    readonly sessions?: BwrapCachePrunePolicy;
+    readonly templates?: BwrapCachePrunePolicy;
+    readonly now?: Date;
+}
+export interface BwrapCachePruneResult {
+    readonly dryRun: boolean;
+    readonly candidates: readonly BwrapCacheEntry[];
+    readonly removed: readonly BwrapCacheEntry[];
+    readonly skippedActive: readonly BwrapCacheEntry[];
+    readonly retained: readonly BwrapCacheEntry[];
+}
+export interface BwrapCacheLease {
+    readonly sessionId: string;
+    readonly generationId: string;
+    readonly pid: number;
+    readonly createdAt: string;
+    readonly path: string;
+}
+export declare function registerActiveCachePath(path: string): () => void;
+export declare function createBwrapCacheLease(input: {
+    cacheRoot: string;
+    sessionId: string;
+}): Promise<{
+    lease: BwrapCacheLease;
+    release(): Promise<void>;
+}>;
+export declare function listBwrapCacheLeases(input: BwrapCacheLocation): Promise<BwrapCacheLease[]>;
+export declare function listBwrapCache(input: BwrapCacheLocation): Promise<BwrapCacheEntry[]>;
+export declare function pruneBwrapCache(input: BwrapCachePruneInput): Promise<BwrapCachePruneResult>;
+export type BwrapDirectoryCopier = (source: string, target: string, options: {
+    recursive: true;
+    mode?: number;
+}) => Promise<void>;
+export declare function cloneDirectoryAtomically(input: {
+    sourcePath: string;
+    targetPath: string;
+    copyDirectory?: BwrapDirectoryCopier;
+}): Promise<BwrapCloneStrategy>;
+export declare function touchCacheMetadata(input: {
+    cacheRoot: string;
+    kind: BwrapCacheEntryKind;
+    id: string;
+    tags?: Readonly<Record<string, string>>;
+    cloneStrategy?: BwrapCloneStrategy;
+    templateRevision?: string | null;
+    now?: Date;
+}): Promise<BwrapCacheMetadata>;

package/dist/cache.js

@@ -0,0 +1,283 @@
+import { randomUUID } from "node:crypto";
+import { constants, existsSync } from "node:fs";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+const activeCachePaths = new Map();
+export function registerActiveCachePath(path) {
+    const resolved = resolve(path);
+    activeCachePaths.set(resolved, (activeCachePaths.get(resolved) ?? 0) + 1);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const remaining = (activeCachePaths.get(resolved) ?? 1) - 1;
+        if (remaining <= 0)
+            activeCachePaths.delete(resolved);
+        else
+            activeCachePaths.set(resolved, remaining);
+    };
+}
+function resolveCacheRoot(input) {
+    return resolve(input.cacheDir ?? join(input.appRoot, ".eve", "sandbox-cache", "bwrap"));
+}
+function leaseDirectory(cacheRoot) {
+    return join(cacheRoot, "metadata", "active", "sessions");
+}
+export async function createBwrapCacheLease(input) {
+    const generationId = randomUUID();
+    const directory = leaseDirectory(input.cacheRoot);
+    const path = join(directory, `${input.sessionId}.${generationId}.json`);
+    const lease = {
+        sessionId: input.sessionId,
+        generationId,
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        path,
+    };
+    await mkdir(directory, { recursive: true });
+    await writeFile(path, `${JSON.stringify(lease, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    let released = false;
+    return {
+        lease,
+        async release() {
+            if (released)
+                return;
+            await rm(path, { force: true });
+            released = true;
+        },
+    };
+}
+export async function listBwrapCacheLeases(input) {
+    const cacheRoot = resolveCacheRoot(input);
+    const directory = leaseDirectory(cacheRoot);
+    const names = await readdir(directory).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const leases = await Promise.all(names
+        .filter((name) => name.endsWith(".json"))
+        .map(async (name) => {
+        const path = join(directory, name);
+        try {
+            const value = JSON.parse(await readFile(path, "utf8"));
+            if (typeof value.sessionId !== "string" ||
+                !validEntryId("session", value.sessionId) ||
+                typeof value.generationId !== "string" ||
+                typeof value.pid !== "number" ||
+                typeof value.createdAt !== "string") {
+                return null;
+            }
+            return { ...value, path };
+        }
+        catch {
+            return null;
+        }
+    }));
+    return leases
+        .filter((lease) => lease !== null)
+        .sort((a, b) => a.path.localeCompare(b.path));
+}
+function validEntryId(kind, id) {
+    return kind === "session" ? /^[0-9a-f]{32}$/.test(id) : /^[0-9a-f]{32}-[0-9a-f]{16}$/.test(id);
+}
+async function directorySize(path) {
+    const info = await lstat(path);
+    if (!info.isDirectory())
+        return info.size;
+    const children = await readdir(path);
+    const sizes = await Promise.all(children.map(async (child) => await directorySize(join(path, child))));
+    return sizes.reduce((total, size) => total + size, 0);
+}
+async function listKind(cacheRoot, kind, leasedSessionIds) {
+    const directory = join(cacheRoot, `${kind}s`);
+    const children = await readdir(directory, { withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const entries = await Promise.all(children
+        .filter((child) => child.isDirectory() && validEntryId(kind, child.name))
+        .map(async (child) => {
+        const entryPath = join(directory, child.name);
+        const info = await lstat(entryPath);
+        const stored = await readMetadata(metadataPath(cacheRoot, kind, child.name));
+        const metadata = stored?.kind === kind && stored.id === child.name
+            ? stored
+            : {
+                schemaVersion: 1,
+                kind,
+                id: child.name,
+                createdAt: info.birthtime.toISOString(),
+                lastUsedAt: info.mtime.toISOString(),
+            };
+        return {
+            ...metadata,
+            path: entryPath,
+            sizeBytes: await directorySize(entryPath),
+            active: activeCachePaths.has(entryPath) || leasedSessionIds.has(child.name),
+            metadataPresent: stored !== null && stored.kind === kind && stored.id === child.name,
+        };
+    }));
+    return entries.sort((a, b) => a.id.localeCompare(b.id));
+}
+export async function listBwrapCache(input) {
+    const cacheRoot = resolveCacheRoot(input);
+    const leases = await listBwrapCacheLeases(input);
+    const leasedSessionIds = new Set(leases.map((lease) => lease.sessionId));
+    const [sessions, templates] = await Promise.all([
+        listKind(cacheRoot, "session", leasedSessionIds),
+        listKind(cacheRoot, "template", leasedSessionIds),
+    ]);
+    return [...sessions, ...templates];
+}
+function validatePolicy(kind, policy) {
+    if (policy.maxAgeMs !== undefined &&
+        (!Number.isSafeInteger(policy.maxAgeMs) || policy.maxAgeMs < 0)) {
+        throw new Error(`bwrap sandbox: ${kind} maxAgeMs must be a non-negative safe integer`);
+    }
+    if (policy.maxEntries !== undefined &&
+        (!Number.isSafeInteger(policy.maxEntries) || policy.maxEntries < 0)) {
+        throw new Error(`bwrap sandbox: ${kind} maxEntries must be a non-negative safe integer`);
+    }
+    if (policy.maxAgeMs === undefined && policy.maxEntries === undefined) {
+        throw new Error(`bwrap sandbox: ${kind} prune policy must set maxAgeMs or maxEntries`);
+    }
+}
+function selectCandidates(entries, policy, nowMs) {
+    const selected = new Set();
+    if (policy.maxAgeMs !== undefined) {
+        for (const entry of entries) {
+            if (nowMs - Date.parse(entry.lastUsedAt) > policy.maxAgeMs)
+                selected.add(entry);
+        }
+    }
+    if (policy.maxEntries !== undefined && entries.length > policy.maxEntries) {
+        const oldestFirst = [...entries].sort((a, b) => Date.parse(a.lastUsedAt) - Date.parse(b.lastUsedAt) || a.id.localeCompare(b.id));
+        for (const entry of oldestFirst.slice(0, entries.length - policy.maxEntries)) {
+            selected.add(entry);
+        }
+    }
+    return selected;
+}
+export async function pruneBwrapCache(input) {
+    if (!input.sessions && !input.templates) {
+        throw new Error("bwrap sandbox: cache prune requires a sessions or templates policy");
+    }
+    if (input.sessions)
+        validatePolicy("session", input.sessions);
+    if (input.templates)
+        validatePolicy("template", input.templates);
+    const entries = await listBwrapCache(input);
+    const nowMs = (input.now ?? new Date()).getTime();
+    const selected = new Set();
+    for (const [kind, policy] of [
+        ["session", input.sessions],
+        ["template", input.templates],
+    ]) {
+        if (!policy)
+            continue;
+        const matches = entries.filter((entry) => entry.kind === kind);
+        for (const entry of selectCandidates(matches, policy, nowMs))
+            selected.add(entry);
+    }
+    const candidates = [...selected].sort((a, b) => a.path.localeCompare(b.path));
+    const skippedActive = candidates.filter((entry) => entry.active || activeCachePaths.has(entry.path));
+    const removable = candidates.filter((entry) => !skippedActive.includes(entry));
+    const removed = [];
+    if (input.dryRun === false) {
+        const cacheRoot = resolveCacheRoot(input);
+        for (const entry of removable) {
+            const leased = (await listBwrapCacheLeases(input)).some((lease) => lease.sessionId === entry.id);
+            if (activeCachePaths.has(entry.path) || leased) {
+                skippedActive.push(entry);
+                continue;
+            }
+            await rm(entry.path, { force: true, recursive: true });
+            await rm(metadataPath(cacheRoot, entry.kind, entry.id), { force: true });
+            removed.push(entry);
+        }
+    }
+    return {
+        dryRun: input.dryRun !== false,
+        candidates,
+        removed,
+        skippedActive,
+        retained: entries.filter((entry) => !removed.includes(entry) && (!selected.has(entry) || skippedActive.includes(entry))),
+    };
+}
+const reflinkFallbackCodes = new Set(["EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EXDEV"]);
+export async function cloneDirectoryAtomically(input) {
+    const copyDirectory = input.copyDirectory ?? (async (source, target, options) => await cp(source, target, options));
+    const temporary = `${input.targetPath}.${randomUUID()}.tmp`;
+    await mkdir(dirname(input.targetPath), { recursive: true });
+    try {
+        let strategy = "reflink";
+        try {
+            await copyDirectory(input.sourcePath, temporary, {
+                recursive: true,
+                mode: constants.COPYFILE_FICLONE_FORCE,
+            });
+        }
+        catch (error) {
+            if (!reflinkFallbackCodes.has(error.code ?? ""))
+                throw error;
+            strategy = "copy";
+            await rm(temporary, { force: true, recursive: true });
+            await copyDirectory(input.sourcePath, temporary, { recursive: true });
+        }
+        await rename(temporary, input.targetPath);
+        return strategy;
+    }
+    catch (error) {
+        await rm(temporary, { force: true, recursive: true }).catch(() => { });
+        if (existsSync(input.targetPath))
+            return "existing";
+        throw error;
+    }
+}
+function metadataPath(cacheRoot, kind, id) {
+    return join(cacheRoot, "metadata", `${kind}s`, `${id}.json`);
+}
+async function readMetadata(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        return value.schemaVersion === 1 ? value : null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function touchCacheMetadata(input) {
+    const target = metadataPath(input.cacheRoot, input.kind, input.id);
+    const existing = await readMetadata(target);
+    const now = (input.now ?? new Date()).toISOString();
+    const tags = input.tags ?? existing?.tags;
+    const cloneStrategy = input.cloneStrategy === "existing"
+        ? (existing?.cloneStrategy ?? "existing")
+        : (input.cloneStrategy ?? existing?.cloneStrategy);
+    const templateRevision = input.templateRevision ?? existing?.templateRevision;
+    const metadata = {
+        schemaVersion: 1,
+        kind: input.kind,
+        id: input.id,
+        createdAt: existing?.createdAt ?? now,
+        lastUsedAt: now,
+        ...(tags && Object.keys(tags).length > 0 ? { tags } : {}),
+        ...(cloneStrategy ? { cloneStrategy } : {}),
+        ...(templateRevision ? { templateRevision } : {}),
+    };
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    await mkdir(dirname(target), { recursive: true });
+    try {
+        await writeFile(temporary, `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+        await rename(temporary, target);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => { });
+    }
+    return metadata;
+}

package/dist/events.d.ts

@@ -0,0 +1,44 @@
+export type BwrapCommandFinishReason = "exit" | "abort" | "timeout" | "output-limit" | "killed" | "cleanup";
+interface BwrapEventBase {
+    readonly timestamp: string;
+    readonly sessionId: string;
+    readonly generationId: string;
+    readonly tags: Readonly<Record<string, string>>;
+}
+export type BwrapSandboxEvent = (BwrapEventBase & {
+    readonly type: "generation.started";
+}) | (BwrapEventBase & {
+    readonly type: "command.started";
+    readonly commandId: string;
+    readonly pid?: number;
+    readonly pgid?: number;
+    readonly liveProcesses: number;
+}) | (BwrapEventBase & {
+    readonly type: "command.finished";
+    readonly commandId: string;
+    readonly pid?: number;
+    readonly reason: BwrapCommandFinishReason;
+    readonly exitCode?: number;
+    readonly durationMs: number;
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+    readonly liveProcesses: number;
+    readonly error?: string;
+}) | (BwrapEventBase & {
+    readonly type: "cleanup.started";
+    readonly requestedProcesses: number;
+}) | (BwrapEventBase & {
+    readonly type: "cleanup.completed";
+    readonly requestedProcesses: number;
+    readonly remainingProcesses: number;
+    readonly durationMs: number;
+}) | (BwrapEventBase & {
+    readonly type: "cleanup.failed";
+    readonly requestedProcesses: number;
+    readonly remainingProcesses: number;
+    readonly durationMs: number;
+    readonly errors: readonly string[];
+});
+export type BwrapSandboxEventPayload = BwrapSandboxEvent extends infer Event ? Event extends BwrapSandboxEvent ? Omit<Event, "timestamp" | "sessionId" | "generationId" | "tags"> : never : never;
+export type BwrapSandboxEventSink = (event: BwrapSandboxEvent) => unknown;
+export {};

package/dist/events.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -2,7 +2,10 @@ import type { SandboxBackend } from "eve/sandbox";
 import type { BwrapSandboxCreateOptions, BwrapSandboxUseOptions } from "./options.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, type CreateBwrapSandboxBackendInput, } from "./backend.js";
 export type { BwrapNetworkPolicy, BwrapSandboxCreateOptions, BwrapSandboxUseOptions, } from "./options.js";
-export { DEFAULT_RUN_TIMEOUT_MS } from "./options.js";
+export type { BwrapCommandFinishReason, BwrapSandboxEvent, BwrapSandboxEventSink, } from "./events.js";
+export { listBwrapCache, listBwrapCacheLeases, pruneBwrapCache } from "./cache.js";
+export type { BwrapCacheEntry, BwrapCacheEntryKind, BwrapCacheLocation, BwrapCacheLease, BwrapCacheMetadata, BwrapCachePruneInput, BwrapCachePrunePolicy, BwrapCachePruneResult, BwrapCloneStrategy, } from "./cache.js";
+export { DEFAULT_MAX_CONCURRENT_PROCESSES, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_RUN_TIMEOUT_MS, } from "./options.js";
 export { isBwrapAvailable } from "./process.js";
 export type { ProcessRunner, SpawnedProcess } from "./process.js";
 /**

package/dist/index.js

@@ -1,6 +1,7 @@
 import { createBwrapSandboxBackend } from "./backend.js";
 export { BWRAP_BACKEND_NAME, createBwrapSandboxBackend, } from "./backend.js";
-export { DEFAULT_RUN_TIMEOUT_MS } from "./options.js";
+export { listBwrapCache, listBwrapCacheLeases, pruneBwrapCache } from "./cache.js";
+export { DEFAULT_MAX_CONCURRENT_PROCESSES, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_RUN_TIMEOUT_MS, } from "./options.js";
 export { isBwrapAvailable } from "./process.js";
 /**
  * Creates the bubblewrap sandbox backend for `defineSandbox({ backend })`.

package/dist/options.d.ts

@@ -1,3 +1,4 @@
+import type { BwrapSandboxEventSink } from "./events.js";
 /** Coarse egress control, matching what eve's Docker backend supports. */
 export type BwrapNetworkPolicy = "allow-all" | "deny-all";
 /** Options lifecycle hooks can apply when they open a template or live Session. */
@@ -7,6 +8,10 @@ export interface BwrapSandboxUseOptions {
 }
 /** Commands executed through `run()` are bounded by default; use `spawn()` for daemons. */
 export declare const DEFAULT_RUN_TIMEOUT_MS = 600000;
+/** Per-generation admission ceiling for transient bwrap commands. */
+export declare const DEFAULT_MAX_CONCURRENT_PROCESSES = 64;
+/** Combined stdout + stderr retained by one `run()` call. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
 /** Options accepted by `bwrap(opts)`. */
 export interface BwrapSandboxCreateOptions {
     /** Environment variables set for every command the backend runs. */
@@ -36,6 +41,12 @@ export interface BwrapSandboxCreateOptions {
      * long-running `spawn()` API.
      */
     readonly runTimeoutMs?: number | null;
+    /** Maximum live `run()`/`spawn()` processes in one compute generation. */
+    readonly maxConcurrentProcesses?: number | null;
+    /** Maximum combined stdout/stderr bytes retained by one `run()` call. */
+    readonly maxOutputBytes?: number | null;
+    /** Best-effort structured lifecycle events. Sink errors never affect commands. */
+    readonly onEvent?: BwrapSandboxEventSink;
 }
 /** Fully-defaulted options consumed by the backend implementation. */
 export interface ResolvedBwrapSandboxOptions {
@@ -46,6 +57,9 @@ export interface ResolvedBwrapSandboxOptions {
     readonly cacheDir: string | null;
     readonly templateRevision: string | null;
     readonly runTimeoutMs: number | null;
+    readonly maxConcurrentProcesses: number | null;
+    readonly maxOutputBytes: number | null;
+    readonly onEvent?: BwrapSandboxEventSink;
 }
 export declare function resolveBwrapSandboxOptions(options?: BwrapSandboxCreateOptions): ResolvedBwrapSandboxOptions;
 /**

package/dist/options.js

@@ -1,6 +1,10 @@
 import { createHash } from "node:crypto";
 /** Commands executed through `run()` are bounded by default; use `spawn()` for daemons. */
 export const DEFAULT_RUN_TIMEOUT_MS = 600_000;
+/** Per-generation admission ceiling for transient bwrap commands. */
+export const DEFAULT_MAX_CONCURRENT_PROCESSES = 64;
+/** Combined stdout + stderr retained by one `run()` call. */
+export const DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
 function resolveRunTimeoutMs(value) {
     if (value === null)
         return null;
@@ -10,6 +14,15 @@ function resolveRunTimeoutMs(value) {
     }
     return resolved;
 }
+function resolvePositiveLimit(name, value, fallback) {
+    if (value === null)
+        return null;
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new Error(`bwrap sandbox: ${name} must be a positive safe integer or null`);
+    }
+    return resolved;
+}
 export function resolveBwrapSandboxOptions(options = {}) {
     return {
         env: options.env ?? {},
@@ -19,6 +32,9 @@ export function resolveBwrapSandboxOptions(options = {}) {
         cacheDir: options.cacheDir ?? null,
         templateRevision: options.templateRevision ?? null,
         runTimeoutMs: resolveRunTimeoutMs(options.runTimeoutMs),
+        maxConcurrentProcesses: resolvePositiveLimit("maxConcurrentProcesses", options.maxConcurrentProcesses, DEFAULT_MAX_CONCURRENT_PROCESSES),
+        maxOutputBytes: resolvePositiveLimit("maxOutputBytes", options.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES),
+        ...(options.onEvent ? { onEvent: options.onEvent } : {}),
     };
 }
 /**
@@ -32,6 +48,8 @@ export function createBwrapOptionsHash(options) {
         cacheDir: options.cacheDir,
         env: Object.fromEntries(Object.entries(options.env).sort(([a], [b]) => (a < b ? -1 : 1))),
         hidePaths: [...options.hidePaths],
+        maxConcurrentProcesses: options.maxConcurrentProcesses,
+        maxOutputBytes: options.maxOutputBytes,
         networkPolicy: options.networkPolicy,
         runTimeoutMs: options.runTimeoutMs,
         templateRevision: options.templateRevision,

package/dist/process.js

@@ -39,44 +39,68 @@ export function createNodeProcessRunner() {
             });
             exit.catch(() => { });
             const killTree = () => {
+                if (child.exitCode !== null || child.signalCode !== null)
+                    return undefined;
                 if (child.pid !== undefined) {
                     try {
                         process.kill(-child.pid, "SIGKILL");
-                        return;
+                        return undefined;
                     }
-                    catch {
-                        // fall through: group already gone or not yet set up
+                    catch (error) {
+                        // ESRCH can mean the process group was not established yet; kill
+                        // the direct child. Other failures (notably EPERM) are cleanup
+                        // failures even if the direct-child fallback succeeds, because
+                        // descendants may have escaped the signal.
+                        child.kill("SIGKILL");
+                        if (error.code !== "ESRCH")
+                            return error;
+                        return undefined;
                     }
                 }
                 child.kill("SIGKILL");
+                return undefined;
             };
             let aborted = false;
             let abortReason;
+            let abortKillError;
             const signal = options?.abortSignal;
+            let onAbort;
             if (signal) {
-                const onAbort = () => {
+                onAbort = () => {
                     aborted = true;
                     abortReason = signal.reason;
-                    killTree();
+                    abortKillError = killTree();
                 };
                 if (signal.aborted)
                     onAbort();
                 else
                     signal.addEventListener("abort", onAbort, { once: true });
             }
+            const removeAbortListener = () => {
+                if (signal && onAbort)
+                    signal.removeEventListener("abort", onAbort);
+            };
+            void exit.then(removeAbortListener, removeAbortListener);
             return {
                 pid: child.pid,
                 stdout: Readable.toWeb(child.stdout),
                 stderr: Readable.toWeb(child.stderr),
                 async wait() {
                     const result = await exit;
+                    if (abortKillError !== undefined) {
+                        const cleanupMessage = abortKillError instanceof Error ? abortKillError.message : String(abortKillError);
+                        const abortMessage = abortReason instanceof Error ? abortReason.message : String(abortReason);
+                        throw new AggregateError([abortKillError, abortReason], `bwrap process abort cleanup failed: ${cleanupMessage}; abort reason: ${abortMessage}`);
+                    }
                     if (aborted)
                         throw abortReason;
                     return result;
                 },
                 async kill() {
-                    killTree();
+                    const killError = killTree();
                     await exit.catch(() => { });
+                    if (killError !== undefined)
+                        throw killError;
                 },
             };
         },

package/dist/session.d.ts

@@ -7,6 +7,9 @@ export interface CreateBwrapSessionInput {
     readonly appRoot: string;
     readonly runner: ProcessRunner;
     readonly options: ResolvedBwrapSandboxOptions;
+    readonly generationId?: string;
+    readonly tags?: Readonly<Record<string, string>>;
+    readonly onStopped?: () => void | Promise<void>;
 }
 /**
  * A sandbox session plus the lifecycle hook the backend handle needs.
@@ -16,5 +19,7 @@ export interface CreateBwrapSessionInput {
 export type BwrapSession = SandboxSession & {
     /** Kills every process this session spawned that has not yet exited. Idempotent. */
     killAll(): Promise<void>;
+    /** Internal compute-generation state used to coordinate repeated handles. */
+    lifecycleState(): "running" | "stopping" | "stopped";
 };
 export declare function createBwrapSession(input: CreateBwrapSessionInput): BwrapSession;

package/dist/session.js

@@ -1,4 +1,5 @@
 import { createReadStream, existsSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { Readable } from "node:stream";
@@ -11,14 +12,25 @@ function isMissingFileError(error) {
         error !== null &&
         error.code === "ENOENT");
 }
-async function collectStream(stream) {
+async function collectStream(stream, budget, abort) {
     const chunks = [];
     const reader = stream.getReader();
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        chunks.push(value);
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            budget.used += value.byteLength;
+            if (budget.limit !== null && budget.used > budget.limit) {
+                const error = new Error(`bwrap sandbox: run output exceeded ${budget.limit} bytes`);
+                abort(error);
+                throw error;
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
     }
     return Buffer.concat(chunks).toString("utf8");
 }
@@ -34,22 +46,46 @@ function sliceLines(text, startLine, endLine) {
     const lines = text.split("\n");
     return lines.slice((startLine ?? 1) - 1, endLine ?? lines.length).join("\n");
 }
-function createRunAbortSignal(callerSignal, timeoutMs) {
-    if (timeoutMs === null)
-        return { signal: callerSignal, clear() { } };
+function createRunAbortSignal(callerSignal, timeoutMs, outputSignal) {
+    const signals = [outputSignal, ...(callerSignal ? [callerSignal] : [])];
+    if (timeoutMs === null) {
+        return { signal: AbortSignal.any(signals), clear() { } };
+    }
     const timeout = new AbortController();
     const timer = setTimeout(() => {
         timeout.abort(new Error(`bwrap sandbox: run timed out after ${timeoutMs} ms`));
     }, timeoutMs);
     timer.unref?.();
     return {
-        signal: callerSignal ? AbortSignal.any([callerSignal, timeout.signal]) : timeout.signal,
+        signal: AbortSignal.any([...signals, timeout.signal]),
         clear: () => clearTimeout(timer),
     };
 }
 export function createBwrapSession(input) {
     const { id, workspaceDir, appRoot, runner, options } = input;
+    const generationId = input.generationId ?? randomUUID();
+    const tags = input.tags ?? {};
     let networkPolicy = options.networkPolicy;
+    function emit(event) {
+        try {
+            const receipt = options.onEvent?.({
+                ...event,
+                timestamp: new Date().toISOString(),
+                sessionId: id,
+                generationId,
+                tags,
+            });
+            if (receipt !== null &&
+                typeof receipt === "object" &&
+                "then" in receipt &&
+                typeof receipt.then === "function") {
+                void Promise.resolve(receipt).catch(() => { });
+            }
+        }
+        catch {
+            // Observability is best effort and must never change sandbox behavior.
+        }
+    }
     const host = (path) => toHostPath(path, workspaceDir);
     function writableHostPath(path, operation) {
         const hostPath = host(path);
@@ -59,40 +95,109 @@ export function createBwrapSession(input) {
         return hostPath;
     }
     const live = new Set();
-    // Wrap wait()/kill() rather than eagerly calling proc.wait() ourselves to
-    // watch for exit: a fire-and-forget wait() started at spawn time races
-    // ahead of the caller (its resolution is not tied to when anyone actually
-    // observes the process), so a process can be silently untracked before
-    // killAll() ever sees it. Tying removal to the caller's own wait()/kill()
-    // call keeps "still tracked" in sync with "still owned by the caller":
-    // run() untracks itself the moment its internal wait() settles, and a
-    // bare spawn() stays tracked (and killable) until its holder collects it.
+    let lifecycle = "running";
+    let cleanupPromise;
+    let stoppedNotified = false;
+    emit({ type: "generation.started" });
+    function countedStream(stream, onBytes) {
+        const reader = stream.getReader();
+        return new ReadableStream({
+            async pull(controller) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    controller.close();
+                    reader.releaseLock();
+                    return;
+                }
+                onBytes(value.byteLength);
+                controller.enqueue(value);
+            },
+            async cancel(reason) {
+                await reader.cancel(reason);
+                reader.releaseLock();
+            },
+        });
+    }
+    function finishReason(error, terminationReason) {
+        if (terminationReason)
+            return terminationReason;
+        const message = error instanceof Error ? error.message : String(error ?? "");
+        if (message.includes("timed out"))
+            return "timeout";
+        if (message.includes("output exceeded"))
+            return "output-limit";
+        return error === undefined ? "exit" : "abort";
+    }
     function track(proc) {
+        const commandId = randomUUID();
+        const startedAt = Date.now();
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let terminationReason;
+        const exit = proc.wait();
         const wrapped = {
             pid: proc.pid,
-            stdout: proc.stdout,
-            stderr: proc.stderr,
+            stdout: countedStream(proc.stdout, (count) => (stdoutBytes += count)),
+            stderr: countedStream(proc.stderr, (count) => (stderrBytes += count)),
             async wait() {
-                try {
-                    return await proc.wait();
-                }
-                finally {
-                    live.delete(wrapped);
-                }
+                return await exit;
             },
             async kill() {
-                try {
-                    await proc.kill();
-                }
-                finally {
-                    live.delete(wrapped);
-                }
+                await wrapped.terminate("killed");
+            },
+            async terminate(reason) {
+                terminationReason = reason;
+                await proc.kill();
+                live.delete(wrapped);
             },
         };
         live.add(wrapped);
+        emit({
+            type: "command.started",
+            commandId,
+            ...(proc.pid === undefined ? {} : { pid: proc.pid, pgid: proc.pid }),
+            liveProcesses: live.size,
+        });
+        // Process ownership ends when the process actually exits, independently
+        // of whether the caller ever collects the returned handle.
+        void exit
+            .then((result) => {
+            live.delete(wrapped);
+            emit({
+                type: "command.finished",
+                commandId,
+                ...(proc.pid === undefined ? {} : { pid: proc.pid }),
+                reason: finishReason(undefined, terminationReason),
+                exitCode: result.exitCode,
+                durationMs: Date.now() - startedAt,
+                stdoutBytes,
+                stderrBytes,
+                liveProcesses: live.size,
+            });
+        }, (error) => {
+            live.delete(wrapped);
+            emit({
+                type: "command.finished",
+                commandId,
+                ...(proc.pid === undefined ? {} : { pid: proc.pid }),
+                reason: finishReason(error, terminationReason),
+                durationMs: Date.now() - startedAt,
+                stdoutBytes,
+                stderrBytes,
+                liveProcesses: live.size,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .catch(() => { });
         return wrapped;
     }
     async function spawnProcess(spawnOptions) {
+        if (lifecycle !== "running") {
+            throw new Error(`bwrap sandbox: compute generation is ${lifecycle}; refusing to spawn`);
+        }
+        if (options.maxConcurrentProcesses !== null && live.size >= options.maxConcurrentProcesses) {
+            throw new Error(`bwrap sandbox: concurrent process limit of ${options.maxConcurrentProcesses} reached`);
+        }
         const env = {
             PATH: DEFAULT_SANDBOX_PATH,
             HOME: WORKSPACE_ROOT,
@@ -118,21 +223,77 @@ export function createBwrapSession(input) {
     return {
         id,
         resolvePath: resolveWorkspacePath,
+        lifecycleState() {
+            return lifecycle;
+        },
         async killAll() {
-            const pending = [...live];
-            live.clear();
-            await Promise.all(pending.map((proc) => proc.kill().catch(() => undefined)));
+            if (lifecycle === "stopped")
+                return;
+            if (cleanupPromise)
+                return await cleanupPromise;
+            lifecycle = "stopping";
+            cleanupPromise = (async () => {
+                const pending = [...live];
+                const startedAt = Date.now();
+                emit({ type: "cleanup.started", requestedProcesses: pending.length });
+                const results = await Promise.allSettled(pending.map(async (proc) => await proc.terminate("cleanup")));
+                const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+                if (failures.length > 0) {
+                    const errorMessages = failures.map((failure) => failure instanceof Error ? failure.message : String(failure));
+                    emit({
+                        type: "cleanup.failed",
+                        requestedProcesses: pending.length,
+                        remainingProcesses: live.size,
+                        durationMs: Date.now() - startedAt,
+                        errors: errorMessages,
+                    });
+                    throw new AggregateError(failures, `bwrap sandbox: failed to stop all live processes: ${errorMessages.join("; ")}`);
+                }
+                if (!stoppedNotified) {
+                    try {
+                        await input.onStopped?.();
+                        stoppedNotified = true;
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        emit({
+                            type: "cleanup.failed",
+                            requestedProcesses: pending.length,
+                            remainingProcesses: live.size,
+                            durationMs: Date.now() - startedAt,
+                            errors: [message],
+                        });
+                        throw error;
+                    }
+                }
+                lifecycle = "stopped";
+                emit({
+                    type: "cleanup.completed",
+                    requestedProcesses: pending.length,
+                    remainingProcesses: live.size,
+                    durationMs: Date.now() - startedAt,
+                });
+            })();
+            try {
+                await cleanupPromise;
+            }
+            catch (error) {
+                cleanupPromise = undefined;
+                throw error;
+            }
         },
         async spawn(spawnOptions) {
             return await spawnProcess(spawnOptions);
         },
         async run(runOptions) {
-            const runAbort = createRunAbortSignal(runOptions.abortSignal, options.runTimeoutMs);
+            const outputAbort = new AbortController();
+            const runAbort = createRunAbortSignal(runOptions.abortSignal, options.runTimeoutMs, outputAbort.signal);
+            const budget = { limit: options.maxOutputBytes, used: 0 };
             try {
                 const proc = await spawnProcess({ ...runOptions, abortSignal: runAbort.signal });
                 const [stdout, stderr, { exitCode }] = await Promise.all([
-                    collectStream(proc.stdout),
-                    collectStream(proc.stderr),
+                    collectStream(proc.stdout, budget, (reason) => outputAbort.abort(reason)),
+                    collectStream(proc.stderr, budget, (reason) => outputAbort.abort(reason)),
                     proc.wait(),
                 ]);
                 return { exitCode, stdout, stderr };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evelandhq/sandbox-bwrap",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "bubblewrap SandboxBackend for eve agents — real exec sandboxing without Docker or KVM",
   "keywords": [
     "agent",