@evelandhq/sandbox-bwrap 0.1.2 → 0.2.0

package/README.md

@@ -21,11 +21,12 @@ the sandbox module into the release directory at build time — `agent/sandbox.j
 agent, or `agent/sandbox/sandbox.js` when a sandbox folder exists, recursively for every
 subagent — and vendors this package's built output beside it, so agent projects never declare
 a deployment backend themselves. If a project shipped its own sandbox module, the build
-replaces that definition and reports it in the build log; authored `bootstrap()` and
-`onSession()` behavior is not used. The sibling `agent/sandbox/workspace/**` tree is preserved,
-so Eve still seeds those files into each Session's `/workspace`. Each Eveland Release supplies a
-distinct template revision, so Sessions created against a new Deployment see its updated seeds
-while existing durable Session workspaces remain untouched. The systemd runtime invokes
+wraps that definition and reports it in the build log: Eveland overrides only `backend`, while
+authored `bootstrap()`, `onSession()`, `description`, and `revalidationKey` remain active. The
+sibling `agent/sandbox/workspace/**` tree is preserved, so Eve still seeds those files into each
+Session's `/workspace`. Each Eveland Release supplies a distinct template revision, so Sessions
+created against a new Deployment see its updated seeds while existing durable Session workspaces
+remain untouched. The systemd runtime invokes
 bwrap as its unprivileged deployment user. The local Docker runtime installs bwrap inside the Agent
 image and grants the outer container only the capabilities nested bwrap requires; the
 Agent container still receives no Docker socket. Local `eve dev` is untouched — it never runs
@@ -70,57 +71,106 @@ 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
+that callback use the requested network boundary. Calling `use()` without options keeps the
+backend's configured policy.
 
 ## How it works
 
-- **prewarm** (build time): runs the authored `bootstrap` inside bwrap against a
-  staging directory, resolves Eve's `$HOME/.agents/skills/**` seed paths to
-  `/workspace/.agents/skills/**`, writes seed files, then atomically renames it into
+- **prewarm** (build time): resolves Eve's `$HOME/.agents/skills/**` seed paths to
+  `/workspace/.agents/skills/**`, writes every seed into a staging directory, then runs the
+  authored `bootstrap` inside bwrap so it can consume those canonical inputs, before atomically
+  renaming the result into
   `<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
 
@@ -151,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
@@ -177,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
@@ -218,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
 
@@ -229,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 } from "./options.js";
+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;
+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}/`)) {
@@ -67,38 +88,58 @@ export function createBwrapSandboxBackend(input = {}) {
             }
         }
     }
+    async function useSession(session, useOptions) {
+        if (useOptions?.networkPolicy !== undefined) {
+            await session.setNetworkPolicy(useOptions.networkPolicy);
+        }
+        return session;
+    }
     return {
         name: BWRAP_BACKEND_NAME,
         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 });
             try {
                 const session = openSession(templateKey, stagingPath, runtimeContext.appRoot);
-                if (bootstrap)
-                    await bootstrap({ use: async () => session });
                 await writeSeedFiles(session, seedFiles);
+                if (bootstrap) {
+                    await bootstrap({ use: async (useOptions) => await useSession(session, useOptions) });
+                }
                 await rename(stagingPath, templatePath);
             }
             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);
@@ -108,13 +149,24 @@ 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 () => session,
+                useSessionFn: async (useOptions) => await useSession(session, useOptions),
                 async captureState() {
                     return { backendName: BWRAP_BACKEND_NAME, metadata: {}, sessionKey };
                 },

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>;