V48 Gate 3 (implementation-only): Vercel Sandbox v2 ephemeral deposit boxes

Force persistent:false for one-shot harness creates (v2 defaults to
persistent/Snapshot Storage), assign unique names, and stop+delete
ephemeral sandboxes after deposit synthesis.

Author: geraldarthurdavis

packages/pipeline-hosts/src/__tests__/vercel-sandbox-host.test.ts

@@ -1,5 +1,8 @@
 import { buildAssetPackSandboxHarness } from '../asset-pack-harness';
-import { VercelSandboxPipelineHost } from '../vercel-sandbox-host';
+import {
+  normalizeCreateOptions,
+  VercelSandboxPipelineHost,
+} from '../vercel-sandbox-host';
 import type {
   PipelineHarnessFile,
   PipelineHarnessHostEvent,
@@ -10,10 +13,12 @@ import type {
 
 class FakeSandbox {
   sandboxId = 'sbx_test';
+  name?: string;
   status = 'running';
   readonly writtenFiles: PipelineHarnessFile[] = [];
   readonly commands: { cmd: string; args: string[] }[] = [];
   stopped = false;
+  deleted = false;
 
   async writeFiles(files: PipelineHarnessFile[]): Promise<void> {
     this.writtenFiles.push(...files);
@@ -42,6 +47,11 @@ class FakeSandbox {
     this.stopped = true;
     this.status = 'stopped';
   }
+
+  async delete(): Promise<void> {
+    this.deleted = true;
+    this.status = 'deleted';
+  }
 }
 
 class DetachedFakeSandbox extends FakeSandbox {
@@ -191,8 +201,14 @@ describe('VercelSandboxPipelineHost', () => {
       'command-started',
       'command-completed',
       'artifacts-read',
+      // Ephemeral harnesses stop then delete (v2: avoid Snapshot Storage linger).
+      'sandbox-deleted',
       'sandbox-stopped',
     ]);
+    expect(events.find((e) => e.type === 'sandbox-created')).toMatchObject({
+      persistent: false,
+      name: expect.any(String),
+    });
     expect(events.find((event) => event.type === 'command-completed')).toMatchObject({
       stdoutLength: expect.any(Number),
       stderrLength: expect.any(Number),
@@ -300,7 +316,13 @@ describe('VercelSandboxPipelineHost', () => {
         token: 'test-token',
         teamId: 'team_test',
         projectId: 'prj_test',
+        // v2 default is persistent=true; Bitcode harnesses force false.
+        persistent: false,
       });
+      expect(typeof createOptions[0].name).toBe('string');
+      expect(createOptions[0].name!.length).toBeGreaterThan(8);
+      expect(fakeSandbox.stopped).toBe(true);
+      expect(fakeSandbox.deleted).toBe(true);
     } finally {
       restoreEnv('VERCEL_TOKEN', previous.VERCEL_TOKEN);
       restoreEnv('VERCEL_TEAM_ID', previous.VERCEL_TEAM_ID);
@@ -309,6 +331,36 @@ describe('VercelSandboxPipelineHost', () => {
     }
   });
 
+  it('normalizeCreateOptions forces ephemeral unless persistent is explicitly true', () => {
+    expect(normalizeCreateOptions({}).persistent).toBe(false);
+    expect(normalizeCreateOptions({ persistent: false }).persistent).toBe(false);
+    expect(normalizeCreateOptions({ persistent: true, name: 'keep-me' })).toMatchObject({
+      persistent: true,
+      name: 'keep-me',
+    });
+    const named = normalizeCreateOptions({ name: '  ' });
+    expect(named.persistent).toBe(false);
+    expect(named.name).toMatch(/^bitcode-harness-/);
+  });
+
+  it('deposit harness createOptions are non-persistent with a unique name', () => {
+    const plan = buildAssetPackSandboxHarness({
+      mode: 'asset_pack_pipeline',
+      synthesizeMode: 'deposit',
+      persistent: false,
+      read: { id: 'read-1', prompt: 'n/a' },
+      deposit: { id: 'deposit-demo' },
+      sourceRevision: {
+        repositoryFullName: 'engineeredsoftware/demo',
+        branch: 'main',
+        commit: 'abc',
+      },
+      source: { type: 'git', url: 'https://github.com/engineeredsoftware/demo.git', revision: 'abc' },
+    });
+    expect(plan.createOptions.persistent).toBe(false);
+    expect(plan.createOptions.name).toMatch(/^bitcode-deposit-/);
+  });
+
   it('bounds sandbox creation so auth/API hangs are observable', async () => {
     const factory: SandboxFactory = {
       create: async () => new Promise(() => undefined),

packages/pipeline-hosts/src/asset-pack-harness.ts

@@ -31,6 +31,23 @@ const SANDBOX_WORKING_DIRECTORY = '/vercel/sandbox' as const;
 const DEFAULT_LONG_TIMEOUT_MS = 45 * 60 * 1000;
 const SANDBOX_PNPM_VERSION = '10.33.0';
 
+/**
+ * Unique name per harness create (Vercel project-scoped). Even non-persistent
+ * sandboxes take a name for dashboard/log correlation; names are not reused.
+ */
+export function buildEphemeralSandboxName(
+  synthesizeMode: 'deposit' | 'read',
+  depositId?: string | null,
+): string {
+  const slug = String(depositId || 'harness')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  const stamp = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  return `bitcode-${synthesizeMode}-${slug || 'run'}-${stamp}`.slice(0, 96);
+}
+
 export interface BuildAssetPackSandboxHarnessOptions {
   mode?: PipelineHarnessMode;
   read: PipelineReadRequest;
@@ -54,10 +71,13 @@ export interface BuildAssetPackSandboxHarnessOptions {
     demandContext?: string[];
   };
   /**
-   * When false, create a non-persistent (ephemeral) sandbox — no snapshot on stop.
-   * Deposit one-shot synthesis defaults to false when synthesizeMode is deposit.
+   * Vercel Sandbox v2 defaults to persistent (auto-snapshot + Snapshot Storage
+   * billing). Bitcode harness runs are one-shot — default `false` unless a
+   * caller explicitly opts into a long-lived named workspace.
    */
   persistent?: boolean;
+  /** Optional stable name (unique per Vercel project). Auto-generated when omitted. */
+  sandboxName?: string;
 }
 
 export function buildAssetPackSandboxHarness(
@@ -111,20 +131,23 @@ export function buildAssetPackSandboxHarness(
     sourceOverlayPatch !== null
   );
 
+  // Vercel Sandbox v2: persistence is ON by default. Never leave `persistent`
+  // undefined for harness creates — that would silently bill Snapshot Storage
+  // for one-shot deposit/read synthesis. Opt-in only when the caller sets true.
+  const persistent = options.persistent === true;
+  const sandboxName =
+    (typeof options.sandboxName === 'string' && options.sandboxName.trim()) ||
+    buildEphemeralSandboxName(options.synthesizeMode ?? 'read', options.deposit?.id);
+
   return {
     capabilities: VERCEL_SANDBOX_HOST_CAPABILITIES,
     createOptions: {
       runtime: options.runtime ?? VERCEL_SANDBOX_HOST_CAPABILITIES.defaultRuntime,
       timeout: options.timeoutMs ?? DEFAULT_LONG_TIMEOUT_MS,
       networkPolicy: options.networkPolicy ?? 'allow-all',
       source: options.source,
-      // Deposit one-shots are ephemeral; read/QA harness may opt into persistence.
-      persistent:
-        typeof options.persistent === 'boolean'
-          ? options.persistent
-          : options.synthesizeMode === 'deposit'
-            ? false
-            : undefined,
+      persistent,
+      name: sandboxName,
     },
     manifest,
     files: [

packages/pipeline-hosts/src/types.ts

@@ -170,12 +170,32 @@ export interface SandboxCreateOptions {
   projectId?: string;
   token?: string;
   /**
-   * When false, the sandbox is ephemeral (no snapshot storage on stop).
-   * Deposit one-shot synthesis should prefer non-persistent boxes.
+   * Vercel Sandbox v2: persistence is DEFAULT (auto-snapshot on stop, billed
+   * Snapshot Storage). Bitcode pipeline harnesses are one-shot CI-style work —
+   * always pass `false` unless a caller explicitly opts into a long-lived
+   * named workspace. See Vercel docs: Persistent sandboxes / Opt out.
    */
   persistent?: boolean;
-  /** Optional stable name for Sandbox.get / resume (unique per project). */
+  /**
+   * Unique name within the Vercel project (v2 primary identity; v1 used
+   * sandboxId). Ephemeral deposit runs still set a unique name for logs/
+   * dashboard correlation even when `persistent: false`.
+   */
   name?: string;
+  /**
+   * Optional TTL for automatic snapshots when persistent (ms from last use).
+   * Only relevant when `persistent: true`.
+   */
+  snapshotExpiration?: number;
+  /**
+   * Retention for persistent sandboxes (keep N most recent snapshots).
+   * Only relevant when `persistent: true`.
+   */
+  keepLastSnapshots?: {
+    count: number;
+    expiration?: number;
+    deleteEvicted?: boolean;
+  };
 }
 
 export interface PipelineHarnessFile {
@@ -238,7 +258,10 @@ export interface SandboxRunCommandObject {
 }
 
 export interface SandboxSession {
+  /** v1 identity; still present on many SDK builds. */
   sandboxId?: string;
+  /** v2 primary identity (unique per project). */
+  name?: string;
   status?: string;
   writeFiles(files: PipelineHarnessFile[]): Promise<void>;
   runCommand(
@@ -248,19 +271,32 @@ export interface SandboxSession {
   ): Promise<SandboxCommandResult>;
   runCommand(params: SandboxRunCommandObject): Promise<SandboxCommandResult>;
   readFileToBuffer(file: { path: string; cwd?: string }): Promise<Buffer | null>;
+  /**
+   * End the current session. Persistent sandboxes auto-snapshot; non-persistent
+   * discard the filesystem. Does not permanently remove the sandbox entity.
+   */
   stop?(opts?: { blocking?: boolean }): Promise<unknown>;
+  /** Permanent remove (sandbox + snapshots + sessions). Prefer after ephemeral stop. */
+  delete?(): Promise<unknown>;
   snapshot?(opts?: { expiration?: number }): Promise<{ snapshotId: string }>;
+  update?(opts: Record<string, unknown>): Promise<unknown>;
 }
 
 export interface SandboxFactory {
   create(options: SandboxCreateOptions): Promise<SandboxSession>;
-  /** Optional: resume/stop an existing sandbox by id or name (SDK-dependent). */
+  /** Resume/retrieve by name (v2) or sandboxId (v1). */
   get?(options: {
     sandboxId?: string;
     name?: string;
     teamId?: string;
     projectId?: string;
     token?: string;
+    resume?: boolean;
+  }): Promise<SandboxSession>;
+  getOrCreate?(options: SandboxCreateOptions & {
+    onCreate?: (sandbox: SandboxSession) => void | Promise<void>;
+    onResume?: (sandbox: SandboxSession) => void | Promise<void>;
+    resume?: boolean;
   }): Promise<SandboxSession>;
 }
 
@@ -275,14 +311,24 @@ export type PipelineHarnessHostEvent =
       type: 'sandbox-created';
       timestamp: string;
       sandboxId?: string;
+      /** v2 name when available. */
+      name?: string;
+      persistent?: boolean;
       status?: string;
     }
   | {
       type: 'sandbox-cancelled';
       timestamp: string;
       sandboxId?: string;
+      name?: string;
       reason?: string;
     }
+  | {
+      type: 'sandbox-deleted';
+      timestamp: string;
+      sandboxId?: string;
+      name?: string;
+    }
   | {
       type: 'harness-files-written';
       timestamp: string;