@fusionkit/session-vercel-sandbox 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import type { NetworkPolicy as WarrantNetworkPolicy } from "@fusionkit/protocol";
+import type { BackendExecutionKind, SessionBackend, SessionBackendResult, SessionExecution } from "@fusionkit/runner";
+import { Sandbox } from "@vercel/sandbox";
+import type { NetworkPolicy as VercelNetworkPolicy } from "@vercel/sandbox";
+export type VercelSandboxSource = {
+    type: "git";
+    url: string;
+    depth?: number;
+    revision?: string;
+} | {
+    type: "git";
+    url: string;
+    username: string;
+    password: string;
+    depth?: number;
+    revision?: string;
+} | {
+    type: "tarball";
+    url: string;
+} | {
+    type: "snapshot";
+    snapshotId: string;
+};
+export type VercelSandboxResources = {
+    vcpus: number;
+};
+type VercelSandboxCreateBase = {
+    token: string;
+    teamId?: string;
+    projectId?: string;
+    timeout: number;
+    networkPolicy: VercelNetworkPolicy;
+    persistent: boolean;
+    resources?: VercelSandboxResources;
+    tags?: Record<string, string>;
+};
+export type VercelSandboxCreateInput = (VercelSandboxCreateBase & {
+    runtime: string;
+    source?: Exclude<VercelSandboxSource, {
+        type: "snapshot";
+    }>;
+}) | (VercelSandboxCreateBase & {
+    source: Extract<VercelSandboxSource, {
+        type: "snapshot";
+    }>;
+});
+export type VercelSandboxInstance = Awaited<ReturnType<typeof Sandbox.create>>;
+export type VercelSandboxFactory = (input: VercelSandboxCreateInput) => Promise<VercelSandboxInstance>;
+export type VercelSandboxOptions = {
+    /** Sandbox runtime image. Defaults to node22. */
+    runtime?: string;
+    /** Working directory inside the VM. Defaults to /warrant/workspace. */
+    workdir?: string;
+    /** Credentials; falls back to the ambient Vercel environment. */
+    token?: string;
+    teamId?: string;
+    projectId?: string;
+    /** Initial sandbox source. Supports git, tarball, and snapshot sources. */
+    source?: VercelSandboxSource;
+    /** Convenience for `source: { type: "snapshot", snapshotId }`. */
+    sourceSnapshotId?: string;
+    /** Whether the sandbox should auto-snapshot on stop. Defaults to false. */
+    persistent?: boolean;
+    /** Sandbox tags passed to Vercel. */
+    tags?: Record<string, string>;
+    /** Resource allocation passed to Vercel. */
+    resources?: VercelSandboxResources;
+    /** Test/extension seam for creating sandboxes without live credentials. */
+    createSandbox?: VercelSandboxFactory;
+};
+/**
+ * Directory names never staged into a sandbox and never mirrored back:
+ * VCS metadata stays local (output is collected as a git diff on the
+ * runner side) and dependency trees are reinstalled inside the VM when
+ * the task needs them. Backends with runtime-specific state directories
+ * extend this set at the call site.
+ */
+export declare const SANDBOX_IGNORED_DIRS: ReadonlySet<string>;
+/**
+ * Quote a value for POSIX sh: single quotes, with embedded single quotes
+ * rendered as '\''. Unlike double quotes, nothing inside single quotes is
+ * expanded, so secret values containing $, backticks, or quotes are inert.
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * List a workspace's files as relative paths, skipping the shared ignored
+ * directories plus any backend-specific extras. The one walker used to
+ * stage workspaces into sandboxes.
+ */
+export declare function listWorkspaceFiles(root: string, extraIgnores?: Iterable<string>): string[];
+/**
+ * Write one mirrored-back sandbox file into the local checkout, with the
+ * path validated against escape before anything touches the filesystem.
+ * Shared by every sandbox-shaped backend so mirror-back path safety lives
+ * in exactly one place.
+ */
+export declare function writeMirroredFile(repoDir: string, rel: string, content: Uint8Array): void;
+/**
+ * Resolve Vercel credentials from explicit options or the ambient
+ * environment, failing closed (capability error) when no token exists.
+ */
+export declare function vercelCredentialsFromEnv(options?: {
+    token?: string;
+    teamId?: string;
+    projectId?: string;
+}): {
+    token: string;
+    teamId?: string;
+    projectId?: string;
+};
+/** Map a Warrant network policy to a Vercel Sandbox network policy. */
+export declare function toVercelNetwork(policy: WarrantNetworkPolicy): VercelNetworkPolicy;
+export declare class VercelSandboxBackend implements SessionBackend {
+    readonly isolation: "vercel-sandbox";
+    private readonly options;
+    constructor(options?: VercelSandboxOptions);
+    supports(_kind: BackendExecutionKind, contract: SessionExecution["contract"]): boolean;
+    execute(input: SessionExecution): Promise<SessionBackendResult>;
+}
+/** Create a Vercel Sandbox session backend for a Warrant runner. */
+export declare function vercelSandboxBackend(options?: VercelSandboxOptions): VercelSandboxBackend;
+export {};

package/dist/index.js

@@ -0,0 +1,261 @@
+/**
+ * @fusionkit/session-vercel-sandbox — a session backend that runs each
+ * governed session inside a Vercel Sandbox (a Firecracker microVM).
+ *
+ * This is the strongest isolation tier in the repo: VM-level separation
+ * on the same infrastructure that powers Vercel's build system, with
+ * domain-based egress policy applied at the VM boundary rather than via
+ * environment variables a binary could ignore.
+ *
+ * Status: experimental and integration-gated. It compiles against the
+ * real @vercel/sandbox types, but running it requires Vercel credentials
+ * (VERCEL_TOKEN / VERCEL_TEAM_ID / VERCEL_PROJECT_ID, or an OIDC token in
+ * a Vercel environment). Without them, `vercelSandboxBackend()` still
+ * constructs; `execute` throws a clear capability error. The kernel and
+ * the other backends do not depend on it.
+ *
+ * This module also owns the sandbox-shaped helpers (file listing, shell
+ * quoting, mirror-back writes, credential resolution) shared with
+ * `@fusionkit/session-harness`, which drives the same microVM tier through
+ * the AI SDK harness bridge.
+ */
+import { readFileSync, readdirSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { CapabilityMismatchError, executionHash, resolveSessionEnv } from "@fusionkit/runner";
+import { parseWorkspaceRelativePath, resolveInsideWorkspace } from "@fusionkit/workspace";
+import { Sandbox } from "@vercel/sandbox";
+/**
+ * Directory names never staged into a sandbox and never mirrored back:
+ * VCS metadata stays local (output is collected as a git diff on the
+ * runner side) and dependency trees are reinstalled inside the VM when
+ * the task needs them. Backends with runtime-specific state directories
+ * extend this set at the call site.
+ */
+export const SANDBOX_IGNORED_DIRS = new Set([
+    ".git",
+    "node_modules",
+    ".warrant"
+]);
+/** Defaults for the microVM; both are overridable via VercelSandboxOptions. */
+const DEFAULT_WORKDIR = "/warrant/workspace";
+const DEFAULT_RUNTIME = "node22";
+function defaultCreateSandbox(input) {
+    return Sandbox.create(input);
+}
+function normalizeSandboxWorkdir(workdir) {
+    if (!workdir.startsWith("/") || workdir.includes("\0")) {
+        throw new CapabilityMismatchError(`vercel sandbox workdir must be an absolute VM path: ${workdir}`);
+    }
+    if (workdir.split("/").includes("..")) {
+        throw new CapabilityMismatchError(`vercel sandbox workdir must not contain '..': ${workdir}`);
+    }
+    return workdir.replace(/\/+$/, "") || "/";
+}
+function posixJoin(base, rel) {
+    const normalizedRel = rel.split("\\").join("/");
+    if (base === "/")
+        return `/${normalizedRel}`;
+    return `${base}/${normalizedRel}`;
+}
+function sandboxCwd(workdir, cwd) {
+    if (cwd === "." || cwd === "./")
+        return workdir;
+    const safeRel = parseWorkspaceRelativePath(cwd);
+    return posixJoin(workdir, safeRel);
+}
+function sandboxSource(options) {
+    if (options.source !== undefined && options.sourceSnapshotId !== undefined) {
+        throw new CapabilityMismatchError("vercel sandbox options must not set both source and sourceSnapshotId");
+    }
+    if (options.source !== undefined)
+        return options.source;
+    if (options.sourceSnapshotId !== undefined) {
+        return { type: "snapshot", snapshotId: options.sourceSnapshotId };
+    }
+    return undefined;
+}
+function sandboxCreateInput(input) {
+    const { credentials, runtime, timeoutMs, networkPolicy, options } = input;
+    const base = {
+        ...credentials,
+        timeout: timeoutMs,
+        networkPolicy,
+        persistent: options.persistent ?? false,
+        ...(options.resources !== undefined ? { resources: options.resources } : {}),
+        ...(options.tags !== undefined ? { tags: options.tags } : {})
+    };
+    const source = sandboxSource(options);
+    if (source?.type === "snapshot") {
+        // @vercel/sandbox@2.2.0 snapshot sources inherit their runtime from the
+        // snapshot and reject `runtime` on the same create call.
+        return { ...base, source };
+    }
+    return {
+        ...base,
+        runtime,
+        ...(source !== undefined ? { source } : {})
+    };
+}
+/**
+ * Quote a value for POSIX sh: single quotes, with embedded single quotes
+ * rendered as '\''. Unlike double quotes, nothing inside single quotes is
+ * expanded, so secret values containing $, backticks, or quotes are inert.
+ */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", String.raw `'\''`)}'`;
+}
+/**
+ * List a workspace's files as relative paths, skipping the shared ignored
+ * directories plus any backend-specific extras. The one walker used to
+ * stage workspaces into sandboxes.
+ */
+export function listWorkspaceFiles(root, extraIgnores = []) {
+    const ignored = new Set([...SANDBOX_IGNORED_DIRS, ...extraIgnores]);
+    const out = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (ignored.has(entry.name))
+                continue;
+            if (entry.isDirectory()) {
+                walk(join(dir, entry.name));
+            }
+            else if (entry.isFile()) {
+                out.push(relative(root, join(dir, entry.name)));
+            }
+        }
+    };
+    walk(root);
+    return out;
+}
+/**
+ * Write one mirrored-back sandbox file into the local checkout, with the
+ * path validated against escape before anything touches the filesystem.
+ * Shared by every sandbox-shaped backend so mirror-back path safety lives
+ * in exactly one place.
+ */
+export function writeMirroredFile(repoDir, rel, content) {
+    const safeRel = parseWorkspaceRelativePath(rel);
+    const target = resolveInsideWorkspace(repoDir, safeRel);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content);
+}
+/**
+ * Resolve Vercel credentials from explicit options or the ambient
+ * environment, failing closed (capability error) when no token exists.
+ */
+export function vercelCredentialsFromEnv(options = {}) {
+    const token = options.token ?? process.env.VERCEL_TOKEN;
+    if (!token) {
+        throw new CapabilityMismatchError("vercel sandbox requires VERCEL_TOKEN (or an explicit token)");
+    }
+    const teamId = options.teamId ?? process.env.VERCEL_TEAM_ID;
+    const projectId = options.projectId ?? process.env.VERCEL_PROJECT_ID;
+    return {
+        token,
+        ...(teamId !== undefined ? { teamId } : {}),
+        ...(projectId !== undefined ? { projectId } : {})
+    };
+}
+/** Map a Warrant network policy to a Vercel Sandbox network policy. */
+export function toVercelNetwork(policy) {
+    if (!policy.defaultDeny)
+        return "allow-all";
+    if (policy.allowHosts.length === 0)
+        return "deny-all";
+    // Domain allowlist; everything else is denied by default.
+    return { allow: policy.allowHosts };
+}
+export class VercelSandboxBackend {
+    isolation = "vercel-sandbox";
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    supports(_kind, contract) {
+        // The microVM has a real OS, so it can host real vendor CLIs and the
+        // command harness. (The node-based mock is for the in-process tests.)
+        return contract.agent.kind !== "mock";
+    }
+    async execute(input) {
+        const { contract, repoDir, secrets, execution, emit } = input;
+        const creds = vercelCredentialsFromEnv(this.options);
+        const workdir = normalizeSandboxWorkdir(this.options.workdir ?? DEFAULT_WORKDIR);
+        const cwd = sandboxCwd(workdir, execution.cwd);
+        const runtime = this.options.runtime ?? DEFAULT_RUNTIME;
+        const createSandbox = this.options.createSandbox ?? defaultCreateSandbox;
+        const sandbox = await createSandbox(sandboxCreateInput({
+            credentials: creds,
+            runtime,
+            timeoutMs: execution.timeoutMs,
+            networkPolicy: toVercelNetwork(contract.network),
+            options: this.options
+        }));
+        try {
+            await sandbox.fs.mkdir(workdir, { recursive: true });
+            const inputFiles = listWorkspaceFiles(repoDir);
+            if (inputFiles.length > 0) {
+                await sandbox.writeFiles(inputFiles.map((rel) => ({
+                    path: posixJoin(workdir, rel),
+                    content: readFileSync(join(repoDir, rel))
+                })));
+            }
+            // Secrets are injected as single-quoted exports: shellQuote renders
+            // values inert to expansion, so $, backticks, and quotes pass through.
+            const env = resolveSessionEnv(execution.env, secrets);
+            const envPrefix = Object.entries(env)
+                .map(([name, value]) => `export ${name}=${shellQuote(value)}; `)
+                .join("");
+            const script = execution.kind === "shell"
+                ? execution.script
+                : `${shellQuote(execution.cmd)} ${execution.args.map(shellQuote).join(" ")}`;
+            const result = await sandbox.runCommand("sh", [
+                "-c",
+                `cd ${shellQuote(cwd)} && ${envPrefix}${script}`
+            ]);
+            emit({
+                type: "command.executed",
+                argvHash: executionHash(execution),
+                exitCode: result.exitCode
+            });
+            await mirrorBack(sandbox, workdir, repoDir);
+            const [stdout, stderr] = await Promise.all([
+                result.stdout(),
+                result.stderr()
+            ]);
+            const log = Buffer.from(stdout + stderr, "utf8");
+            return { exitCode: result.exitCode, log };
+        }
+        finally {
+            await sandbox.stop().catch(() => undefined);
+        }
+    }
+}
+/**
+ * Mirror the sandbox workdir back onto the local checkout so the runner's
+ * standard git-based output collection sees the changes. A per-file walk is
+ * the operation the sandbox FS API supports (there is no bulk download),
+ * and the file count is bounded by the workspace that was staged in.
+ */
+async function mirrorBack(sandbox, workdir, repoDir) {
+    const walk = async (dir) => {
+        const names = await sandbox.fs.readdir(dir);
+        for (const name of names) {
+            if (SANDBOX_IGNORED_DIRS.has(name))
+                continue;
+            const remote = `${dir}/${name}`;
+            const info = await sandbox.fs.stat(remote);
+            if (info.isDirectory()) {
+                await walk(remote);
+                continue;
+            }
+            const rel = remote.slice(workdir.length + 1);
+            const buffer = await sandbox.fs.readFile(remote);
+            writeMirroredFile(repoDir, rel, buffer);
+        }
+    };
+    await walk(workdir);
+}
+/** Create a Vercel Sandbox session backend for a Warrant runner. */
+export function vercelSandboxBackend(options = {}) {
+    return new VercelSandboxBackend(options);
+}

package/dist/test/vercel-sandbox.test.d.ts

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

package/dist/test/vercel-sandbox.test.js

@@ -0,0 +1,254 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { CapabilityMismatchError, prepareExecution } from "@fusionkit/runner";
+import { listWorkspaceFiles, SANDBOX_IGNORED_DIRS, toVercelNetwork, VercelSandboxBackend } from "../index.js";
+function contractFixture(overrides = {}) {
+    return {
+        version: "warrant.contract.v1",
+        runId: "run_vercel_sandbox_test",
+        issuedAt: "2026-06-11T00:00:00.000Z",
+        issuer: { keyId: "ed25519:0000000000000000", role: "plane" },
+        requestedBy: { kind: "human", id: "alice" },
+        agent: { kind: "command" },
+        task: { prompt: "echo hi" },
+        runner: { pool: "default" },
+        workspace: {
+            version: "warrant.manifest.v1",
+            baseRef: "abc",
+            bundleHash: "1".repeat(64),
+            untrackedFiles: [],
+            deniedPatterns: [],
+            deniedPaths: []
+        },
+        policyHash: "2".repeat(64),
+        secrets: [],
+        network: { defaultDeny: true, allowHosts: [] },
+        budget: {},
+        disclosure: "minimal-context",
+        expiresAt: "2026-06-11T01:00:00.000Z",
+        signatures: [],
+        ...overrides
+    };
+}
+function sessionInput(input) {
+    const contract = input.contract ?? contractFixture();
+    return {
+        contract,
+        repoDir: input.repoDir,
+        secrets: input.secrets ?? [],
+        execution: prepareExecution({ contract, mockScriptPath: "/tmp/mock-agent.js" }),
+        emit: input.emit ?? (() => undefined)
+    };
+}
+function makeRepo(files) {
+    const repoDir = mkdtempSync(join(tmpdir(), "vercel-sandbox-test-"));
+    for (const [path, content] of Object.entries(files)) {
+        const target = join(repoDir, path);
+        mkdirSync(join(target, ".."), { recursive: true });
+        writeFileSync(target, content);
+    }
+    return repoDir;
+}
+function makeFakeSandbox(input = {}) {
+    const fake = {
+        sandbox: undefined,
+        mkdirCalls: [],
+        runCalls: [],
+        stopCalled: false,
+        writtenFiles: []
+    };
+    fake.sandbox = {
+        fs: {
+            mkdir: async (path, options) => {
+                fake.mkdirCalls.push({ path, recursive: options?.recursive });
+            },
+            readdir: async (path) => input.readdir?.(path) ?? [],
+            stat: async (path) => ({
+                isDirectory: () => input.directories?.has(path) ?? false
+            }),
+            readFile: async (path) => Buffer.from(input.files?.get(path) ?? new Uint8Array())
+        },
+        writeFiles: async (files) => {
+            fake.writtenFiles.push(...files);
+        },
+        runCommand: async (command, args) => {
+            fake.runCalls.push({ command, args });
+            if (input.runError)
+                throw input.runError;
+            return {
+                exitCode: 0,
+                stdout: async () => input.stdout ?? "",
+                stderr: async () => input.stderr ?? ""
+            };
+        },
+        stop: async () => {
+            fake.stopCalled = true;
+            if (input.stopError)
+                throw input.stopError;
+            return {};
+        }
+    };
+    return fake;
+}
+test("network policy maps to Vercel Sandbox egress policy", () => {
+    assert.equal(toVercelNetwork({ defaultDeny: false, allowHosts: [] }), "allow-all");
+    assert.equal(toVercelNetwork({ defaultDeny: true, allowHosts: [] }), "deny-all");
+    assert.deepEqual(toVercelNetwork({
+        defaultDeny: true,
+        allowHosts: ["api.example.com", "registry.npmjs.org"]
+    }), { allow: ["api.example.com", "registry.npmjs.org"] });
+});
+test("workspace staging ignores VCS, dependencies, and Warrant state", () => {
+    assert.ok(SANDBOX_IGNORED_DIRS.has(".warrant"));
+    const repoDir = makeRepo({
+        "README.md": "keep\n",
+        ".git/config": "local git metadata\n",
+        "node_modules/pkg/index.js": "dependency\n",
+        ".warrant/cache.json": "local warrant state\n",
+        "src/index.ts": "export {}\n",
+        "src/.warrant/trace.json": "nested warrant state\n"
+    });
+    try {
+        assert.deepEqual(listWorkspaceFiles(repoDir).sort(), [
+            "README.md",
+            "src/index.ts"
+        ]);
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});
+test("backend passes hardened create options and honors execution cwd", async () => {
+    const repoDir = makeRepo({
+        "README.md": "root\n",
+        "packages/app/package.json": "{}\n"
+    });
+    const fake = makeFakeSandbox({ stdout: "ok\n" });
+    let createInput;
+    const backend = new VercelSandboxBackend({
+        token: "fake-token",
+        runtime: "node24",
+        sourceSnapshotId: "snap_123",
+        tags: { run: "test", lane: "vercel-backend" },
+        resources: { vcpus: 4 },
+        createSandbox: async (input) => {
+            createInput = input;
+            return fake.sandbox;
+        }
+    });
+    const contract = contractFixture({
+        network: { defaultDeny: true, allowHosts: ["api.example.com"] },
+        execution: {
+            kind: "shell",
+            script: "pwd",
+            cwd: "packages/app",
+            timeoutMs: 12_345
+        }
+    });
+    try {
+        const result = await backend.execute(sessionInput({ repoDir, contract }));
+        assert.equal(result.exitCode, 0);
+        assert.equal(result.log.toString("utf8"), "ok\n");
+        assert.deepEqual(createInput, {
+            token: "fake-token",
+            timeout: 12_345,
+            networkPolicy: { allow: ["api.example.com"] },
+            persistent: false,
+            resources: { vcpus: 4 },
+            tags: { run: "test", lane: "vercel-backend" },
+            source: { type: "snapshot", snapshotId: "snap_123" }
+        });
+        assert.ok(createInput && !("runtime" in createInput));
+        assert.deepEqual(fake.mkdirCalls, [
+            { path: "/warrant/workspace", recursive: true }
+        ]);
+        assert.deepEqual(fake.writtenFiles.map((file) => file.path).sort(), [
+            "/warrant/workspace/README.md",
+            "/warrant/workspace/packages/app/package.json"
+        ]);
+        assert.equal(fake.runCalls.length, 1);
+        assert.equal(fake.runCalls[0]?.command, "sh");
+        assert.equal(fake.runCalls[0]?.args[1], "cd '/warrant/workspace/packages/app' && pwd");
+        assert.equal(fake.stopCalled, true);
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});
+test("backend fails closed without Vercel credentials", async () => {
+    const repoDir = makeRepo({ "README.md": "root\n" });
+    const previous = {
+        VERCEL_TOKEN: process.env.VERCEL_TOKEN,
+        VERCEL_TEAM_ID: process.env.VERCEL_TEAM_ID,
+        VERCEL_PROJECT_ID: process.env.VERCEL_PROJECT_ID
+    };
+    delete process.env.VERCEL_TOKEN;
+    delete process.env.VERCEL_TEAM_ID;
+    delete process.env.VERCEL_PROJECT_ID;
+    let created = false;
+    const backend = new VercelSandboxBackend({
+        createSandbox: async () => {
+            created = true;
+            return makeFakeSandbox().sandbox;
+        }
+    });
+    try {
+        await assert.rejects(backend.execute(sessionInput({ repoDir })), CapabilityMismatchError);
+        assert.equal(created, false);
+    }
+    finally {
+        if (previous.VERCEL_TOKEN === undefined)
+            delete process.env.VERCEL_TOKEN;
+        else
+            process.env.VERCEL_TOKEN = previous.VERCEL_TOKEN;
+        if (previous.VERCEL_TEAM_ID === undefined)
+            delete process.env.VERCEL_TEAM_ID;
+        else
+            process.env.VERCEL_TEAM_ID = previous.VERCEL_TEAM_ID;
+        if (previous.VERCEL_PROJECT_ID === undefined) {
+            delete process.env.VERCEL_PROJECT_ID;
+        }
+        else {
+            process.env.VERCEL_PROJECT_ID = previous.VERCEL_PROJECT_ID;
+        }
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});
+test("backend stops sandbox after execution failure", async () => {
+    const repoDir = makeRepo({ "README.md": "root\n" });
+    const fake = makeFakeSandbox({ runError: new Error("boom") });
+    const backend = new VercelSandboxBackend({
+        token: "fake-token",
+        createSandbox: async () => fake.sandbox
+    });
+    try {
+        await assert.rejects(backend.execute(sessionInput({ repoDir })), /boom/);
+        assert.equal(fake.stopCalled, true);
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});
+test("backend swallows sandbox stop failures after successful execution", async () => {
+    const repoDir = makeRepo({ "README.md": "root\n" });
+    const fake = makeFakeSandbox({
+        stdout: "done\n",
+        stopError: new Error("stop failed")
+    });
+    const backend = new VercelSandboxBackend({
+        token: "fake-token",
+        createSandbox: async () => fake.sandbox
+    });
+    try {
+        const result = await backend.execute(sessionInput({ repoDir }));
+        assert.equal(result.exitCode, 0);
+        assert.equal(result.log.toString("utf8"), "done\n");
+        assert.equal(fake.stopCalled, true);
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@fusionkit/session-vercel-sandbox",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/session-vercel-sandbox"
+  },
+  "description": "Vercel Sandbox session backend for Warrant runners: each governed session runs in a Firecracker microVM with VM-level isolation and domain-based egress policy.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@vercel/sandbox": "2.2.0",
+    "ms": "2.1.3",
+    "@fusionkit/protocol": "0.1.0",
+    "@fusionkit/runner": "0.1.0",
+    "@fusionkit/workspace": "0.1.0"
+  }
+}