@evelandhq/sandbox-bwrap 0.1.3 → 0.3.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, removeCacheMetadata, 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),
@@ -141,6 +186,23 @@ export function createBwrapSandboxBackend(input = {}) {
                 async shutdown() {
                     await session.killAll();
                 },
+                // eve (>=0.47) calls this when authored code runs
+                // `ctx.getSandbox().delete()`: the sandbox and its disposable state are
+                // gone for good, and the next access reprovisions from the template.
+                // For bwrap the disposable state is the session workspace directory and
+                // its metadata sidecar; the template it was cloned from is shared and
+                // must survive.
+                async delete(deleteOptions) {
+                    deleteOptions?.abortSignal?.throwIfAborted();
+                    await session.killAll();
+                    generations.delete(sessionPath);
+                    await rm(sessionPath, { force: true, recursive: true });
+                    await removeCacheMetadata({
+                        cacheRoot: resolveBwrapCacheRoot(runtimeContext.appRoot, options.cacheDir),
+                        kind: "session",
+                        id: basename(sessionPath),
+                    });
+                },
             };
         },
     };

package/dist/cache.d.ts

@@ -0,0 +1,85 @@
+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>;
+/**
+ * Removes one cache entry's metadata sidecar. Deleting a session removes its
+ * workspace directory too, and a metadata file without a directory would read
+ * as an orphan to `pruneBwrapCache` — remove both together.
+ */
+export declare function removeCacheMetadata(input: {
+    cacheRoot: string;
+    kind: BwrapCacheEntryKind;
+    id: string;
+}): Promise<void>;