@defrex/autobuild 0.8.0

package/packages/core/src/ports/workspace/vercel-sandbox.ts

@@ -0,0 +1,2541 @@
+import { createHash } from 'node:crypto'
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { Sandbox, Snapshot, type NetworkPolicy, type SandboxRegion } from '@vercel/sandbox'
+import { displayName, tomlKey, type RuntimeReferenceGroup } from '../../config/roles'
+import {
+  type VercelProvisioningStep,
+  type VercelSandboxConfig,
+  vercelSandboxConfigSchema,
+} from '../../config/schema'
+import { distributionRoot } from '../../distribution'
+import { defaultDistributionArchive, readDistributionIdentity } from './distribution-archive'
+import type {
+  WorkspaceHandle,
+  WorkspaceProvider,
+  WorkspaceProvisionResult,
+  WorkspaceReapOutcome,
+} from '../types'
+import {
+  SandboxOperationError,
+  type OperatorSandboxExecution,
+  type SandboxCommandRequest,
+  type SandboxCommandResult,
+  type SandboxEnvironmentIdentity,
+  type SandboxWaitResult,
+} from './operator-sandbox'
+import type {
+  BuildExecution,
+  BuildExecutionExit,
+  BuildExecutionHandle,
+  BuildExecutionIdentity,
+  BuildExecutionStart,
+  ExecutionObservation,
+} from './build-execution'
+import {
+  HARVEST_RUNNER_OPTIONS_ENV,
+  type HarvestExecution,
+  type HarvestExecutionStart,
+  type HarvestRunnerLaunch,
+} from './harvest-execution'
+import { BUILD_RUNNER_OPTIONS_ENV } from './local-build-execution'
+import type { Exec } from './git-worktree'
+import { spawnExec } from './git-worktree'
+
+export const VERCEL_WORKSPACE_PATH = '/vercel/sandbox/workspace'
+export const VERCEL_AUTOBUILD_PATH = '/opt/autobuild'
+export const VERCEL_PROVISIONED_MARKER = `${VERCEL_AUTOBUILD_PATH}/.provisioned`
+/** Records the installed distribution's version. A reused sandbox whose marker
+ * disagrees with the version the current system would deliver is refreshed by
+ * reinstalling the archive, so an upgraded dispatcher retrofits its persistent
+ * guests (including legacy guests predating this marker) instead of resuming a
+ * stale distribution that the hosted store would reject. */
+export const VERCEL_DISTRIBUTION_VERSION_MARKER = `${VERCEL_AUTOBUILD_PATH}/.distribution-version`
+export const VERCEL_BUN_VERSION = '1.4.0'
+export const VERCEL_BUN_PREFIX = '/opt/autobuild-runtime'
+export const VERCEL_BUN_BIN_PATH = `${VERCEL_BUN_PREFIX}/node_modules/.bin`
+export const VERCEL_BUN_EXECUTABLE = `${VERCEL_BUN_BIN_PATH}/bun`
+
+export interface VercelCommand {
+  readonly exitCode: number | null
+  /** Provider-native command identity, recorded durably at launch so a later
+   * process can re-observe the execution. */
+  readonly cmdId: string
+  /** The optional signal lets a detaching supervisor release a pending
+   * long-poll without killing the remote command. */
+  wait(params?: { signal?: AbortSignal }): Promise<{ exitCode: number }>
+  kill(signal?: 'SIGTERM' | 'SIGKILL', opts?: { abortSignal?: AbortSignal }): Promise<void>
+  /** Completed-command output is read only for readiness/validation reporting
+   * and declared system-provisioning failure diagnostics, including failures
+   * during durable build provisioning. It is not a durable build-state channel;
+   * scoped Store facts/events remain authoritative. */
+  stdout?(): Promise<string>
+  stderr?(): Promise<string>
+}
+
+/**
+ * Bun's native fetch enforces its own request timeout on the SDK's `wait=true`
+ * long-poll and ignores the SDK's undici agent (`bodyTimeout: 0`). A guest
+ * execution routinely outlives that timeout, so an interrupted long-poll is
+ * re-issued until the command reports an exit code or the environment's own
+ * lifetime has passed. Any other failure still propagates: it may mean the
+ * environment is gone. The same classification reads the observation path's
+ * bounded wait: an interrupted or timed-out bounded wait leaves the execution
+ * provably unobserved, which reads as `running`.
+ */
+export function isInterruptedLongPoll(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  if (error.name === 'TimeoutError') return true
+  const message = error.message.toLowerCase()
+  return message.includes('timed out') || message.includes('socket connection was closed')
+}
+
+export async function waitForCommandExit(
+  command: Pick<VercelCommand, 'wait'>,
+  expired: () => boolean,
+  opts?: { signal?: AbortSignal },
+): Promise<{ exitCode: number }> {
+  for (;;) {
+    try {
+      return await command.wait(opts?.signal === undefined ? {} : { signal: opts.signal })
+    } catch (error) {
+      if (!isInterruptedLongPoll(error) || expired()) throw error
+    }
+  }
+}
+
+/** Narrow re-observation surface of one recorded detached command. The
+ * provider's plain lookup reports `exitCode: null` for a command that finished
+ * while no client was waiting on it, and keeps reporting none until some
+ * client issues `wait` — a caller may not conclude `running` from
+ * `exitCode: null` without first issuing a wait, whose resolution carries the
+ * populated exit code. The SDK's `Command` satisfies this structurally. */
+export interface VercelCommandLookup {
+  exitCode: number | null
+  wait(params?: { signal?: AbortSignal }): Promise<{ exitCode: number }>
+  /** Completed-command output, when the concrete handle exposes it (the SDK's
+   * `Command` does; narrow lookups may omit it). Read only after exit. */
+  stdout?(): Promise<string>
+  stderr?(): Promise<string>
+}
+
+export interface VercelSandboxHandle {
+  readonly name: string
+  /** The session's default working directory, where the server places a git
+   * source checkout. Managed images differ (`/vercel/sandbox` on the language
+   * images, `/vercel` on universal), so the checkout is located through it. */
+  readonly cwd?: string
+  currentSession?(): { sessionId: string }
+  /** Status of the session this handle observed, captured at `facade.get`
+   * time. Optional: facades without session metadata omit it. */
+  readonly sessionStatus?:
+    | 'failed'
+    | 'aborted'
+    | 'pending'
+    | 'running'
+    | 'stopping'
+    | 'stopped'
+    | 'snapshotting'
+  /** The provider-computed moment the running session times out (epoch ms;
+   * the SDK Sandbox's `expiresAt` getter, session start plus configured
+   * timeout). Optional: facades without session metadata omit it, and it is
+   * `undefined` while no session is running. Read live so a refreshed handle
+   * — including one carrying a resumed session's new expiry — reports fresh
+   * values on every observation. */
+  readonly sessionExpiresAt?: number
+  /** Narrowed re-observation of one recorded detached command. A missing
+   * command under a resumed session rejects; callers classify that as `lost`.
+   * The plain lookup reports no exit code for a command that finished while no
+   * client was waiting on it, and keeps reporting none until some client
+   * issues `wait` — a caller may not conclude `running` from `exitCode: null`
+   * without first issuing a wait. */
+  getCommand(cmdId: string, opts?: { signal?: AbortSignal }): Promise<VercelCommandLookup>
+  runCommand(params: {
+    cmd: string
+    args?: string[]
+    cwd?: string
+    env?: Record<string, string>
+    detached?: true
+    sudo?: boolean
+    signal?: AbortSignal
+  }): Promise<VercelCommand | { exitCode: number }>
+  writeFiles(
+    files: { path: string; content: Uint8Array }[],
+    opts?: { signal?: AbortSignal },
+  ): Promise<void>
+  stop(opts?: { signal?: AbortSignal }): Promise<unknown>
+  delete(opts?: { signal?: AbortSignal }): Promise<void>
+  update(
+    params: { networkPolicy: NetworkPolicy },
+    opts?: { signal?: AbortSignal },
+  ): Promise<unknown>
+}
+
+export type VercelSandboxCreateInput = {
+  name: string
+  source: {
+    type: 'git'
+    url: string
+    revision: string
+    depth?: number
+    username?: string
+    password?: string
+  }
+  image: string
+  resources: { vcpus: number }
+  timeout: number
+  persistent: true
+  region?: string
+  failoverRegions?: string[]
+  networkPolicy: NetworkPolicy
+  signal?: AbortSignal
+  /** Snapshot expiration in milliseconds for this environment's automatic
+   * snapshots (SDK `snapshotExpiration`); absent means the provider default. */
+  snapshotExpiration?: number
+  /** Retention bound for this environment's automatic snapshots. Snapshots
+   * are created whenever a session stops, and `Sandbox.delete()` never removes
+   * them; the bound keeps a live environment at exactly what resuming it
+   * needs. Release purges even this snapshot. */
+  keepLastSnapshots: { count: number; deleteEvicted: boolean }
+}
+
+/** Snapshots retained for a live environment: exactly the one resuming it
+ * needs. Each session stop supersedes the previous snapshot, so stops along
+ * the build never accumulate one snapshot per stop. */
+export const VERCEL_KEEP_LAST_SNAPSHOTS = 1
+
+/** The stop/snapshot margin added to the environment's configured lifetime by
+ * every VM-lifetime deadline: a command or observation may legitimately still
+ * resolve while the environment is being stopped or snapshotted, but past
+ * session expiry plus this margin it cannot still be running. Shared by the
+ * command path and the observation path so the two bounds cannot drift. */
+export const VERCEL_LIFETIME_MARGIN_MS = 5 * 60 * 1000
+
+/** The bound on the observation path's single wait on a recorded command
+ * whose plain lookup reports no exit code. A few seconds: long enough to
+ * observe an already-exited guest, far below the tick's operation timeout so
+ * one observation never approaches it. A genuinely running guest costs this
+ * much per observation; the next tick retries. */
+export const VERCEL_OBSERVE_WAIT_MS = 5_000
+
+/** The snapshot rows that hold billed storage. `deleted`/`failed` rows hold
+ * none and are never purge targets. */
+const LIVE_SNAPSHOT_STATUS = 'created'
+
+/** Bounded list→delete→re-list repetitions that absorb the provider's
+ * snapshot materialization lag between a session stop and its snapshot
+ * becoming listed. */
+const SNAPSHOT_PURGE_PASSES = 3
+
+export interface VercelSnapshotInfo {
+  id: string
+  sourceSessionId: string
+  status: 'created' | 'deleted' | 'failed'
+  sizeBytes?: number
+}
+
+/** Result of purging one environment's snapshots by exact name. `unknown`
+ * never silently claims confirmation. */
+export interface VercelSnapshotPurge {
+  outcome: 'confirmed' | 'unknown'
+  deleted: number
+  error?: string
+}
+
+export interface VercelSandboxFacade {
+  get(name: string, signal?: AbortSignal): Promise<VercelSandboxHandle | null>
+  /** Durable build workspaces retain the named get-or-create lifecycle. */
+  create(input: VercelSandboxCreateInput): Promise<VercelSandboxHandle>
+  /** Readiness always acquires a new unnamed disposable environment. */
+  createFresh?(
+    input: Omit<VercelSandboxCreateInput, 'name' | 'persistent'>,
+  ): Promise<VercelSandboxHandle>
+  /** Snapshots listed under the exact sandbox name — the deterministic
+   * per-environment purge key. */
+  listSnapshots(name: string, signal?: AbortSignal): Promise<VercelSnapshotInfo[]>
+  deleteSnapshot(snapshotId: string, signal?: AbortSignal): Promise<void>
+}
+
+/** The team and project a Vercel OIDC token was issued for, read from its
+ * unverified payload exactly as the Sandbox SDK does (`owner_id`,
+ * `project_id`). Null when the value is not a decodable JWT carrying both. */
+export function vercelOidcTokenScope(token: string): { teamId: string; projectId: string } | null {
+  const payload = token.split('.')[1]
+  if (payload === undefined || payload === '') return null
+  try {
+    const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as {
+      owner_id?: unknown
+      project_id?: unknown
+    }
+    if (typeof claims.owner_id !== 'string' || typeof claims.project_id !== 'string') return null
+    return { teamId: claims.owner_id, projectId: claims.project_id }
+  } catch {
+    return null
+  }
+}
+
+/** Credentials handed to every Sandbox SDK call. An OIDC token in the
+ * dispatcher environment is passed explicitly with the team and project from
+ * its claims — the SDK's own `VERCEL_OIDC_TOKEN` lookup reads the process
+ * environment, which is not where a hosted invocation carries its token (a
+ * Vercel Function receives it as a request header). A token whose claims
+ * cannot be read is left to the SDK's own resolution. */
+export function vercelSdkCredentials(
+  env: Record<string, string | undefined>,
+): Record<string, string> {
+  const oidcToken = env.VERCEL_OIDC_TOKEN
+  if (oidcToken) {
+    const scope = vercelOidcTokenScope(oidcToken)
+    return scope === null ? {} : { token: oidcToken, ...scope }
+  }
+  const token = env.VERCEL_TOKEN
+  const teamId = env.VERCEL_TEAM_ID
+  const projectId = env.VERCEL_PROJECT_ID
+  if (!token || !teamId || !projectId) {
+    throw new Error(
+      'vercel-sandbox requires VERCEL_OIDC_TOKEN or VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID',
+    )
+  }
+  return { token, teamId, projectId }
+}
+
+/** The SDK's session metadata is a live getter on the returned object, but the
+ * adapter's handle interface names it `sessionStatus`. Bridge it in place so
+ * every facade-returned handle carries fresh session state for observation. */
+function withSessionMetadata(sandbox: object): VercelSandboxHandle {
+  const status = () => (sandbox as { status?: VercelSandboxHandle['sessionStatus'] }).status
+  if (status() !== undefined && !Object.hasOwn(sandbox, 'sessionStatus')) {
+    Object.defineProperty(sandbox, 'sessionStatus', { get: status, configurable: true })
+  }
+  // The SDK computes `expiresAt` itself from the authoritative session fields
+  // (`(startedAt ?? createdAt) + timeout` while a session is running); bridge
+  // it as a live getter so observations never see a stale lifetime.
+  const expiresAt = () => (sandbox as { expiresAt?: Date | undefined }).expiresAt?.getTime()
+  if (expiresAt() !== undefined && !Object.hasOwn(sandbox, 'sessionExpiresAt')) {
+    Object.defineProperty(sandbox, 'sessionExpiresAt', { get: expiresAt, configurable: true })
+  }
+  return sandbox as VercelSandboxHandle
+}
+
+export function isMissingVercelSandbox(error: unknown): boolean {
+  if (error === null || typeof error !== 'object') return false
+  const candidate = error as {
+    response?: { status?: number }
+    json?: { error?: { code?: string } }
+  }
+  return (
+    candidate.response?.status === 404 ||
+    (candidate.response?.status === 410 && candidate.json?.error?.code === 'snapshot_not_found')
+  )
+}
+
+export function createVercelSdkFacade(
+  env: Record<string, string | undefined>,
+): VercelSandboxFacade {
+  const credentials = vercelSdkCredentials(env)
+  return {
+    async get(name, signal) {
+      try {
+        return withSessionMetadata(await Sandbox.get({ name, signal, ...credentials }))
+      } catch (error) {
+        if (isMissingVercelSandbox(error)) return null
+        throw error
+      }
+    },
+    async create(input) {
+      // get() returning null includes stale snapshots. getOrCreate performs the
+      // SDK's required stale-name deletion before recreating and also closes a
+      // concurrent provision race safely.
+      return withSessionMetadata(
+        await Sandbox.getOrCreate({
+          ...input,
+          region: input.region as SandboxRegion | undefined,
+          failoverRegions: input.failoverRegions as SandboxRegion[] | undefined,
+          ...credentials,
+        }),
+      )
+    },
+    async createFresh(input) {
+      return withSessionMetadata(
+        await Sandbox.create({
+          ...input,
+          region: input.region as SandboxRegion | undefined,
+          failoverRegions: input.failoverRegions as SandboxRegion[] | undefined,
+          ...credentials,
+        }),
+      )
+    },
+    async listSnapshots(name, signal) {
+      // The API rejects `limit` above 50; `toArray()` walks every page.
+      const page = await Snapshot.list({
+        name,
+        limit: 50,
+        ...(signal === undefined ? {} : { signal }),
+        ...credentials,
+      })
+      return (await page.toArray()).map((snapshot) => ({
+        id: snapshot.id,
+        sourceSessionId: snapshot.sourceSessionId,
+        status: snapshot.status,
+        ...(typeof snapshot.sizeBytes === 'number' && Number.isFinite(snapshot.sizeBytes)
+          ? { sizeBytes: snapshot.sizeBytes }
+          : {}),
+      }))
+    },
+    async deleteSnapshot(snapshotId, signal) {
+      const snapshot = await Snapshot.get({ snapshotId, ...credentials })
+      await snapshot.delete(signal === undefined ? {} : { signal })
+    },
+  }
+}
+
+export function requireVercelEnvironmentValue(
+  env: Record<string, string | undefined>,
+  name: string,
+): string {
+  const value = env[name]
+  if (value === undefined || value === '') {
+    throw new Error(`vercel-sandbox requires environment variable ${name}`)
+  }
+  return value
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Delete every `created` snapshot listed under the exact sandbox name, then
+ * re-list to prove absence, repeating a bounded number of times to absorb the
+ * provider's snapshot materialization lag. Any SDK failure — or a name that
+ * still lists live snapshots after the bounded passes — is reported as
+ * `unknown` so callers can retry rather than silently claim a purge.
+ */
+export async function purgeEnvironmentSnapshots(
+  facade: VercelSandboxFacade,
+  name: string,
+  signal?: AbortSignal,
+): Promise<VercelSnapshotPurge> {
+  let deleted = 0
+  for (let pass = 0; ; pass += 1) {
+    let listed: VercelSnapshotInfo[]
+    try {
+      listed = await facade.listSnapshots(name, signal)
+    } catch (error) {
+      return { outcome: 'unknown', deleted, error: describeError(error) }
+    }
+    const live = listed.filter((snapshot) => snapshot.status === LIVE_SNAPSHOT_STATUS)
+    if (live.length === 0) return { outcome: 'confirmed', deleted }
+    if (pass >= SNAPSHOT_PURGE_PASSES) {
+      return {
+        outcome: 'unknown',
+        deleted,
+        error:
+          `${live.length} snapshot(s) still listed under ${JSON.stringify(name)} ` +
+          `after ${SNAPSHOT_PURGE_PASSES} purge passes`,
+      }
+    }
+    for (const snapshot of live) {
+      try {
+        await facade.deleteSnapshot(snapshot.id, signal)
+        deleted += 1
+      } catch (error) {
+        return { outcome: 'unknown', deleted, error: describeError(error) }
+      }
+    }
+  }
+}
+
+export function validateVercelGithubOrigin(raw: string): {
+  url: string
+  host: string
+  path: string
+  directory: string
+} {
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    throw new Error('vercel-sandbox requires an HTTPS GitHub origin')
+  }
+  if (url.protocol !== 'https:' || url.hostname.toLowerCase() !== 'github.com') {
+    throw new Error('vercel-sandbox requires an HTTPS github.com origin')
+  }
+  url.username = ''
+  url.password = ''
+  url.search = ''
+  url.hash = ''
+  const path = url.pathname.replace(/\.git$/, '').replace(/^\//, '')
+  if (!/^[^/]+\/[^/]+$/.test(path)) throw new Error('GitHub origin must name owner/repository')
+  return {
+    url: `https://github.com/${path}.git`,
+    host: 'github.com',
+    path: `/${path}.git`,
+    directory: basename(path),
+  }
+}
+
+const cleanGithubOrigin = validateVercelGithubOrigin
+
+function sandboxName(origin: string, branch: string, generation = 0): string {
+  const readable = branch
+    .replace(/^ab\//, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .slice(0, 40)
+  const digest = createHash('sha256')
+    .update(`${origin}\0${branch}\0${generation}`)
+    .digest('hex')
+    .slice(0, 10)
+  return `autobuild-${readable || 'build'}-g${generation}-${digest}`.slice(0, 63)
+}
+
+/** Deterministic harvest environment name: one per repository origin, with
+ * the same digest slicing and charset discipline as `sandboxName`. The name
+ * is the get-or-create key and the exact snapshot purge key. */
+export function harvestSandboxName(origin: string): string {
+  const digest = createHash('sha256').update(origin).digest('hex').slice(0, 10)
+  return `autobuild-harvest-${digest}`.slice(0, 63)
+}
+
+/** Deterministic operator-sandbox environment name: one per (repository
+ * origin, operator) — the same digest over the two identities with the same
+ * slicing/charset/63-char rules as the build and harvest names. The name is
+ * the get-or-create key and the exact snapshot purge key. */
+export function sandboxEnvironmentName(origin: string, operator: string): string {
+  const digest = createHash('sha256').update(`${origin}\0${operator}`).digest('hex').slice(0, 10)
+  return `autobuild-sandbox-${digest}`.slice(0, 63)
+}
+
+/** Hard ceiling on one operator-sandbox command wait (`exec`'s
+ * `timeoutSeconds` and `wait`'s `waitSeconds`), in seconds. The service
+ * validates against the same bound. */
+export const SANDBOX_MAX_WAIT_SECONDS = 300
+
+async function execOrThrow(
+  exec: Exec,
+  cmd: string[],
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const result = await exec(cmd, { cwd, ...(signal === undefined ? {} : { signal }) })
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `${cmd.join(' ')} exited ${result.exitCode}: ${result.stderr.trim() || result.stdout.trim()}`,
+    )
+  }
+  return result.stdout.trim()
+}
+
+function oneSha(output: string, label: string): string | null {
+  const lines = output.trim() === '' ? [] : output.trim().split(/\r?\n/)
+  if (lines.length === 0) return null
+  if (lines.length !== 1) throw new Error(`${label} returned more than one ref`)
+  const sha = lines[0]!.split(/\s+/)[0]!
+  if (!/^[0-9a-f]{40,64}$/i.test(sha)) throw new Error(`${label} returned an invalid commit id`)
+  return sha
+}
+
+function uploadPackPolicy(
+  origin: ReturnType<typeof cleanGithubOrigin>,
+  auth?: string,
+): NetworkPolicy {
+  if (auth === undefined) return 'allow-all'
+  return {
+    allow: {
+      '*': [],
+      [origin.host]: [
+        {
+          match: {
+            method: ['GET'],
+            path: { exact: `${origin.path}/info/refs` },
+            queryString: [{ key: { exact: 'service' }, value: { exact: 'git-upload-pack' } }],
+          },
+          transform: [{ headers: { authorization: auth } }],
+        },
+        {
+          match: { method: ['POST'], path: { exact: `${origin.path}/git-upload-pack` } },
+          transform: [{ headers: { authorization: auth } }],
+        },
+      ],
+    },
+  }
+}
+
+/** Default checkout root when the handle does not report its session cwd. */
+const VERCEL_DEFAULT_CWD = '/vercel/sandbox'
+
+/** Where the server checked out the git source: the session cwd plus the
+ * repository directory name. Never assume the image's working directory. */
+export function sourceCheckoutPath(sandbox: VercelSandboxHandle, directory: string): string {
+  const root = (sandbox.cwd ?? '').trim().replace(/\/+$/, '') || VERCEL_DEFAULT_CWD
+  return `${root}/${directory}`
+}
+
+/**
+ * Move the server's checkout to the adapter-owned workspace path. The
+ * workspace parent is created first: the universal image has no
+ * `/vercel/sandbox` directory of its own.
+ */
+async function relocateCheckout(
+  sandbox: VercelSandboxHandle,
+  directory: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const sourcePath = sourceCheckoutPath(sandbox, directory)
+  try {
+    await commandOrThrow(sandbox, {
+      cmd: 'sh',
+      args: [
+        '-c',
+        'mkdir -p "$(dirname "$2")" && mv "$1" "$2"',
+        'relocate',
+        sourcePath,
+        VERCEL_WORKSPACE_PATH,
+      ],
+      ...(signal === undefined ? {} : { signal }),
+    })
+  } catch (error) {
+    throw new Error(
+      `vercel-sandbox could not move the checkout ${sourcePath} to ${VERCEL_WORKSPACE_PATH}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      { cause: error },
+    )
+  }
+}
+
+async function commandOrThrow(
+  sandbox: VercelSandboxHandle,
+  params: {
+    cmd: string
+    args?: string[]
+    cwd?: string
+    env?: Record<string, string>
+    sudo?: boolean
+    signal?: AbortSignal
+  },
+): Promise<void> {
+  const result = await sandbox.runCommand(params)
+  if (result.exitCode === null || result.exitCode === undefined) {
+    throw new Error(`sandbox command ${params.cmd} did not return an exit status`)
+  }
+  if (result.exitCode !== 0)
+    throw new Error(`sandbox command ${params.cmd} exited ${result.exitCode}`)
+}
+
+function bunProvisioningError(image: string, operation: string, error: unknown): Error {
+  return new Error(
+    `vercel-sandbox could not ${operation} Bun ${VERCEL_BUN_VERSION} on image ${JSON.stringify(image)}; Autobuild supports the universal managed image with working Node/npm, shell, filesystem, and package-registry access`,
+    { cause: error },
+  )
+}
+
+async function provisionBun(
+  sandbox: VercelSandboxHandle,
+  image: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  try {
+    await commandOrThrow(sandbox, {
+      cmd: 'npm',
+      args: ['install', '--prefix', VERCEL_BUN_PREFIX, '--no-save', `bun@${VERCEL_BUN_VERSION}`],
+      ...(signal === undefined ? {} : { signal }),
+    })
+  } catch (error) {
+    throw bunProvisioningError(image, 'provision', error)
+  }
+  try {
+    await commandOrThrow(sandbox, {
+      cmd: VERCEL_BUN_EXECUTABLE,
+      args: ['--version'],
+      ...(signal === undefined ? {} : { signal }),
+    })
+  } catch (error) {
+    throw bunProvisioningError(image, 'verify provisioned', error)
+  }
+}
+
+function runtimeEnvironment(
+  config: VercelSandboxConfig,
+  env: Record<string, string | undefined>,
+): Record<string, string> {
+  return Object.fromEntries(
+    config.environmentVariables.map((name) => [name, requireVercelEnvironmentValue(env, name)]),
+  )
+}
+
+function redactRuntimeError(error: unknown, env: Record<string, string>): string {
+  let detail = error instanceof Error ? error.message : String(error)
+  for (const value of Object.values(env).sort((a, b) => b.length - a.length)) {
+    if (value !== '') detail = detail.split(value).join('[REDACTED]')
+  }
+  return detail
+}
+
+/** Bootstrap the workspace runtime references with the build path's
+ * install/preflight chain. `env` is the already-resolved guest environment:
+ * callers decide which names a guest may see — the build and harvest paths
+ * forward `[workspace.config].environmentVariables`, while the operator
+ * sandbox passes its credential-free forwarded set only (build-workspace
+ * variables never enter a sandbox). */
+async function bootstrapRuntimes(
+  sandbox: VercelSandboxHandle,
+  config: VercelSandboxConfig,
+  env: Record<string, string>,
+  references: readonly RuntimeReferenceGroup[],
+  install: boolean,
+  signal?: AbortSignal,
+): Promise<void> {
+  for (const group of [...references].sort((left, right) =>
+    left.runtime < right.runtime ? -1 : left.runtime > right.runtime ? 1 : 0,
+  )) {
+    const provisioning = config.runtimeProvisioning?.[group.runtime]
+    if (provisioning === undefined) {
+      throw new Error(
+        `runtime ${displayName(group.runtime)} selected by ${group.references.join(', ')} has no provisioning; add [workspace.config.runtimeProvisioning.${tomlKey(group.runtime)}] with install and preflight commands`,
+      )
+    }
+    for (const stage of install ? (['install', 'preflight'] as const) : (['preflight'] as const)) {
+      try {
+        await readableCommand(sandbox, {
+          cmd: 'sh',
+          args: ['-c', provisioning[stage]],
+          cwd: VERCEL_WORKSPACE_PATH,
+          env,
+          ...(signal === undefined ? {} : { signal }),
+        })
+      } catch (error) {
+        throw new Error(
+          `runtime ${displayName(group.runtime)} ${stage} failed (selected by ${group.references.join(', ')}); fix workspace.config.runtimeProvisioning.${group.runtime}.${stage}: ${redactRuntimeError(error, env)}`,
+        )
+      }
+    }
+  }
+}
+
+async function runSystemProvisioning(
+  sandbox: VercelSandboxHandle,
+  steps: readonly VercelProvisioningStep[],
+  signal?: AbortSignal,
+): Promise<string[]> {
+  const completed: string[] = []
+  for (const step of steps) {
+    const result = (await sandbox.runCommand({
+      cmd: 'sh',
+      args: ['-c', step.command],
+      cwd: VERCEL_WORKSPACE_PATH,
+      sudo: true,
+      ...(signal === undefined ? {} : { signal }),
+    })) as VercelCommand
+    if (result.exitCode !== 0) {
+      const [stdout, stderr] = await Promise.all([
+        result.stdout?.() ?? Promise.resolve(''),
+        result.stderr?.() ?? Promise.resolve(''),
+      ])
+      throw new Error(
+        `system provisioning step ${JSON.stringify(step.name)} failed\n` +
+          `command: ${step.command}\n` +
+          `exit status: ${result.exitCode ?? '(missing)'}\n` +
+          `stdout:\n${stdout.trim() === '' ? '(empty)' : stdout}\n` +
+          `stderr:\n${stderr.trim() === '' ? '(empty)' : stderr}\n` +
+          'remediation: fix [workspace.config].provisioning and rerun ab init --validate',
+      )
+    }
+    completed.push(step.name)
+  }
+  return completed
+}
+
+async function preflightBun(sandbox: VercelSandboxHandle, image: string): Promise<void> {
+  try {
+    await commandOrThrow(sandbox, { cmd: VERCEL_BUN_EXECUTABLE, args: ['--version'] })
+  } catch (error) {
+    throw new Error(
+      `vercel-sandbox Bun ${VERCEL_BUN_VERSION} preflight failed on image ${JSON.stringify(image)}; release and reprovision this sandbox before retrying the build`,
+      { cause: error },
+    )
+  }
+}
+
+export async function packageAutobuildDistribution(): Promise<Uint8Array> {
+  const destination = await mkdtemp(join(tmpdir(), 'autobuild-pack-'))
+  try {
+    await execOrThrow(
+      spawnExec,
+      ['bun', 'pm', 'pack', '--ignore-scripts', '--destination', destination],
+      distributionRoot(),
+    )
+    const archives = (await readdir(destination)).filter((name) => name.endsWith('.tgz'))
+    if (archives.length !== 1)
+      throw new Error('Autobuild packaging did not produce exactly one archive')
+    return new Uint8Array(await readFile(join(destination, archives[0]!)))
+  } finally {
+    await rm(destination, { recursive: true, force: true })
+  }
+}
+
+export interface VercelReadinessOptions {
+  config: VercelSandboxConfig
+  env: Record<string, string | undefined>
+  storeRef: string
+  storeToken: string
+  repo: string
+  baseBranch: string
+  facade?: VercelSandboxFacade
+  exec?: Exec
+  packageArchive?: () => Promise<Uint8Array>
+  runtimeReferences?: readonly RuntimeReferenceGroup[]
+  signal?: AbortSignal
+  /** Called as soon as the fresh sandbox has an identity, before bootstrap. */
+  onSandbox?: (name: string) => void
+}
+
+export interface VercelReadinessResult {
+  sandbox: string
+  revision: string
+  origin: string
+  provisioning: string[]
+  output: string
+  /** Automatic snapshots deleted while releasing the disposable environment;
+   * zero proves the readiness check left no snapshot storage behind. */
+  snapshotsDeleted: number
+}
+
+async function readableCommand(
+  sandbox: VercelSandboxHandle,
+  params: {
+    cmd: string
+    args?: string[]
+    cwd?: string
+    env?: Record<string, string>
+    sudo?: boolean
+    signal?: AbortSignal
+  },
+): Promise<string> {
+  const result = (await sandbox.runCommand(params)) as VercelCommand
+  const stderr = result.stderr === undefined ? '' : await result.stderr()
+  const stdout = result.stdout === undefined ? '' : await result.stdout()
+  if (result.exitCode === null || result.exitCode === undefined) {
+    throw new Error(`sandbox command ${params.cmd} did not return an exit status`)
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `sandbox command ${params.cmd} exited ${result.exitCode}: ${stderr.trim() || stdout.trim() || '(no output)'}`,
+    )
+  }
+  return stdout
+}
+
+/** Create, inspect, and always delete one remote readiness environment. Unlike
+ * build provisioning this never uses a stable name, branch, or marker. */
+export async function validateVercelSandbox(
+  options: VercelReadinessOptions,
+): Promise<VercelReadinessResult> {
+  const config = vercelSandboxConfigSchema.parse(options.config)
+  if (!/^https:\/\//i.test(options.storeRef) || options.storeToken === '') {
+    throw new Error(
+      'remote validation requires an HTTPS AB_STORE and nonempty AB_TOKEN; configure a remotely reachable hosted Store',
+    )
+  }
+  if (options.signal?.aborted) throw options.signal.reason ?? new Error('validation cancelled')
+  const exec = options.exec ?? spawnExec
+  const rawOrigin = await execOrThrow(
+    exec,
+    ['git', 'remote', 'get-url', 'origin'],
+    options.repo,
+    options.signal,
+  )
+  const origin = cleanGithubOrigin(rawOrigin)
+  const revision = oneSha(
+    await execOrThrow(
+      exec,
+      ['git', 'ls-remote', '--heads', 'origin', `refs/heads/${options.baseBranch}`],
+      options.repo,
+      options.signal,
+    ),
+    `remote base ${options.baseBranch}`,
+  )
+  if (revision === null) {
+    throw new Error(
+      `remote base ${options.baseBranch} does not exist; commit and push the setup before validating`,
+    )
+  }
+  const username =
+    config.gitUsernameEnv === undefined
+      ? undefined
+      : requireVercelEnvironmentValue(options.env, config.gitUsernameEnv)
+  const password =
+    config.gitPasswordEnv === undefined
+      ? undefined
+      : requireVercelEnvironmentValue(options.env, config.gitPasswordEnv)
+  const facade = options.facade ?? createVercelSdkFacade(options.env)
+  if (facade.createFresh === undefined) {
+    throw new Error('the configured Vercel SDK facade does not support fresh validation sandboxes')
+  }
+  const sandbox = await facade.createFresh({
+    source: {
+      type: 'git',
+      url: origin.url,
+      revision,
+      ...(username !== undefined && password !== undefined ? { username, password } : {}),
+    },
+    image: config.image,
+    resources: { vcpus: config.vcpus },
+    timeout: config.timeoutSeconds * 1000,
+    ...(config.region !== undefined ? { region: config.region } : {}),
+    ...(config.failoverRegions.length > 0 ? { failoverRegions: config.failoverRegions } : {}),
+    ...(config.snapshotExpirationSeconds === undefined
+      ? {}
+      : { snapshotExpiration: config.snapshotExpirationSeconds * 1000 }),
+    networkPolicy: 'allow-all',
+    keepLastSnapshots: { count: VERCEL_KEEP_LAST_SNAPSHOTS, deleteEvicted: true },
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  })
+  const name = sandbox.name
+  const withSignal = <T extends { cmd: string }>(params: T): T & { signal?: AbortSignal } => ({
+    ...params,
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  })
+  const checkCancellation = (): void => {
+    if (options.signal?.aborted)
+      throw options.signal.reason ?? new Error(`validation cancelled; releasing sandbox ${name}`)
+  }
+  let failure: unknown
+  let readiness: VercelReadinessResult | undefined
+  try {
+    options.onSandbox?.(name)
+    checkCancellation()
+    await relocateCheckout(sandbox, origin.directory, options.signal)
+    await commandOrThrow(
+      sandbox,
+      withSignal({
+        cmd: 'git',
+        args: ['remote', 'set-url', 'origin', origin.url],
+        cwd: VERCEL_WORKSPACE_PATH,
+      }),
+    )
+    for (const key of ['credential.helper', 'http.extraheader', `http.${origin.url}.extraheader`]) {
+      const result = await sandbox.runCommand(
+        withSignal({
+          cmd: 'git',
+          args: ['config', '--local', '--unset-all', key],
+          cwd: VERCEL_WORKSPACE_PATH,
+        }),
+      )
+      if (result.exitCode !== 0 && result.exitCode !== 5) {
+        throw new Error(`failed to scrub git config ${key}`)
+      }
+    }
+    await provisionBun(sandbox, config.image, options.signal)
+    const provisioning = await runSystemProvisioning(sandbox, config.provisioning, options.signal)
+    const archive = await (options.packageArchive ?? defaultDistributionArchive)()
+    checkCancellation()
+    await sandbox.writeFiles([{ path: '/tmp/autobuild.tgz', content: archive }], {
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    })
+    checkCancellation()
+    await commandOrThrow(sandbox, withSignal({ cmd: 'mkdir', args: ['-p', VERCEL_AUTOBUILD_PATH] }))
+    await commandOrThrow(
+      sandbox,
+      withSignal({
+        cmd: 'tar',
+        args: ['-xzf', '/tmp/autobuild.tgz', '--strip-components=1', '-C', VERCEL_AUTOBUILD_PATH],
+      }),
+    )
+    await commandOrThrow(
+      sandbox,
+      withSignal({
+        cmd: VERCEL_BUN_EXECUTABLE,
+        args: ['install', '--production', '--ignore-scripts'],
+        cwd: VERCEL_AUTOBUILD_PATH,
+      }),
+    )
+    await commandOrThrow(
+      sandbox,
+      withSignal({
+        cmd: 'sh',
+        args: [
+          '-c',
+          `if [ -f bun.lock ] || [ -f bun.lockb ]; then ${VERCEL_BUN_EXECUTABLE} install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; elif [ -f pnpm-lock.yaml ]; then corepack pnpm install --frozen-lockfile; elif [ -f yarn.lock ]; then corepack yarn install --immutable; fi`,
+        ],
+        cwd: VERCEL_WORKSPACE_PATH,
+      }),
+    )
+    await bootstrapRuntimes(
+      sandbox,
+      config,
+      runtimeEnvironment(config, options.env),
+      options.runtimeReferences ?? [],
+      true,
+      options.signal,
+    )
+    const setup = await readableCommand(
+      sandbox,
+      withSignal({
+        cmd: 'sh',
+        args: [
+          '-c',
+          `PATH=${VERCEL_BUN_BIN_PATH}:$PATH exec ${VERCEL_BUN_EXECUTABLE} ${VERCEL_AUTOBUILD_PATH}/bin/ab-init-probe.ts`,
+        ],
+        cwd: VERCEL_WORKSPACE_PATH,
+        env: Object.fromEntries([
+          ['AB_STORE', options.storeRef],
+          ['AB_TOKEN', options.storeToken],
+          ...config.environmentVariables.map((name) => [
+            name,
+            requireVercelEnvironmentValue(options.env, name),
+          ]),
+        ]),
+      }),
+    )
+    readiness = {
+      sandbox: name,
+      revision,
+      origin: origin.url,
+      provisioning,
+      output: setup,
+      snapshotsDeleted: 0,
+    }
+  } catch (error) {
+    failure = error
+  }
+  // Release with zero snapshot storage left behind. Stop first: it ends the
+  // session deterministically, so no new snapshot can appear after the purge.
+  // Deleting a running sandbox instead stops its session and thereby creates
+  // exactly the orphan this sequence exists to prevent. A purge failure is a
+  // release failure and surfaces the same manual-remediation guidance.
+  const releaseErrors: unknown[] = []
+  let snapshotsDeleted = 0
+  try {
+    await sandbox.stop()
+  } catch (stopError) {
+    releaseErrors.push(stopError)
+  }
+  for (const pass of ['pre-delete', 'post-delete'] as const) {
+    const purged = await purgeEnvironmentSnapshots(facade, name)
+    if (purged.outcome === 'unknown') {
+      releaseErrors.push(
+        new Error(
+          `disposable sandbox ${name} ${pass} snapshot purge did not confirm: ${purged.error ?? 'unknown outcome'}`,
+        ),
+      )
+    }
+    snapshotsDeleted += purged.deleted
+    if (pass === 'pre-delete') {
+      try {
+        await sandbox.delete()
+      } catch (deleteError) {
+        releaseErrors.push(deleteError)
+      }
+    }
+  }
+  if (releaseErrors.length > 0) {
+    const guidance =
+      `disposable sandbox ${name} could not be fully released; ` +
+      `delete it manually in the Vercel dashboard or with: vercel sandbox rm ${name}, ` +
+      'and delete any snapshots remaining under its name (they keep incurring storage ' +
+      'until deleted or expired)'
+    if (failure !== undefined) throw new AggregateError([failure, ...releaseErrors], guidance)
+    if (releaseErrors.length === 1) {
+      throw new Error(guidance, { cause: releaseErrors[0] })
+    }
+    throw new AggregateError(releaseErrors, guidance)
+  }
+  if (failure !== undefined) {
+    throw new Error(
+      `disposable sandbox ${name} was deleted after validation failed: ${failure instanceof Error ? failure.message : String(failure)}`,
+      { cause: failure },
+    )
+  }
+  return { ...readiness!, snapshotsDeleted }
+}
+
+export type RuntimeReferencesSource =
+  | readonly RuntimeReferenceGroup[]
+  | (() => readonly RuntimeReferenceGroup[])
+
+function currentRuntimeReferences(
+  source: RuntimeReferencesSource | undefined,
+): readonly RuntimeReferenceGroup[] {
+  if (source === undefined) return []
+  return typeof source === 'function' ? source() : source
+}
+
+/** Install the distribution archive into `/opt/autobuild` and record its
+ * version marker. Shared by fresh provisioning and reuse-path refreshes; the
+ * readback comparison guards a silently failed write or extraction. */
+async function installDistribution(
+  sandbox: VercelSandboxHandle,
+  archive: Uint8Array,
+  version: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  await sandbox.writeFiles([{ path: '/tmp/autobuild.tgz', content: archive }], {
+    ...(signal === undefined ? {} : { signal }),
+  })
+  await commandOrThrow(sandbox, {
+    cmd: 'mkdir',
+    args: ['-p', VERCEL_AUTOBUILD_PATH],
+    ...(signal === undefined ? {} : { signal }),
+  })
+  await commandOrThrow(sandbox, {
+    cmd: 'tar',
+    args: ['-xzf', '/tmp/autobuild.tgz', '--strip-components=1', '-C', VERCEL_AUTOBUILD_PATH],
+    ...(signal === undefined ? {} : { signal }),
+  })
+  await commandOrThrow(sandbox, {
+    cmd: VERCEL_BUN_EXECUTABLE,
+    args: ['install', '--production', '--ignore-scripts'],
+    cwd: VERCEL_AUTOBUILD_PATH,
+    ...(signal === undefined ? {} : { signal }),
+  })
+  await writeDistributionVersionMarker(sandbox, version, signal)
+}
+
+async function writeDistributionVersionMarker(
+  sandbox: VercelSandboxHandle,
+  version: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  await commandOrThrow(sandbox, {
+    cmd: 'sh',
+    args: [
+      '-c',
+      'printf %s "$1" > "$2"',
+      'distribution-version',
+      version,
+      VERCEL_DISTRIBUTION_VERSION_MARKER,
+    ],
+    ...(signal === undefined ? {} : { signal }),
+  })
+  const readback = await readableCommand(sandbox, {
+    cmd: 'cat',
+    args: [VERCEL_DISTRIBUTION_VERSION_MARKER],
+    ...(signal === undefined ? {} : { signal }),
+  })
+  if (readback.trim() !== version) {
+    throw new Error(
+      `distribution version marker readback mismatch in ${VERCEL_DISTRIBUTION_VERSION_MARKER}: ` +
+        `wrote ${JSON.stringify(version)} but read ${JSON.stringify(readback.trim())}`,
+    )
+  }
+}
+
+/** The installed distribution's version, or `undefined` when the marker is
+ * unreadable — which includes every guest provisioned before the marker
+ * existed and is treated as a version mismatch by the reuse path. */
+async function readDistributionVersionMarker(
+  sandbox: VercelSandboxHandle,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  try {
+    const content = await readableCommand(sandbox, {
+      cmd: 'cat',
+      args: [VERCEL_DISTRIBUTION_VERSION_MARKER],
+      ...(signal === undefined ? {} : { signal }),
+    })
+    const trimmed = content.trim()
+    return trimmed === '' ? undefined : trimmed
+  } catch {
+    return undefined
+  }
+}
+
+export interface VercelSandboxProviderOptions {
+  config: VercelSandboxConfig
+  env: Record<string, string | undefined>
+  storeRef: string
+  storeToken: string
+  /** Dispatcher-local main checkout, used only for origin discovery and verification.
+   * With the injected `origin`/`remoteBranchHead` seams (checkout-less origin
+   * mode) it is never touched on the host. */
+  repo: string
+  facade?: VercelSandboxFacade
+  exec?: Exec
+  packageArchive?: () => Promise<Uint8Array>
+  runtimeReferences?: RuntimeReferencesSource
+  /** Checkout-less seam: the repository's HTTPS GitHub origin. Default reads
+   * `git remote get-url origin` from `repo` on the host. */
+  origin?: () => Promise<string>
+  /** Checkout-less seam: the remote branch's current head, `undefined` when
+   * the branch does not exist. Default runs `git ls-remote` from `repo` on
+   * the host. */
+  remoteBranchHead?: (branch: string) => Promise<string | undefined>
+  /** Test seam: the distribution version the current archive source delivers.
+   * Default reads the running distribution's package.json (origin mode keys
+   * the guest archive to that same version; source mode packs the same tree
+   * readDistributionIdentity reads), so the two agree by construction. */
+  distributionVersion?: () => Promise<string>
+  /** Test seam: the bound on the observation path's wait on a command whose
+   * lookup shows no exit. Defaults to `VERCEL_OBSERVE_WAIT_MS`. */
+  observeWaitMs?: number
+  /** The repository's raw `[commands].setup` shell string, run once at the end
+   * of a fresh operator-sandbox provision (never on resume). Set once at
+   * construction; never per call. */
+  setupCommand?: string
+  /** Names of non-secret host environment variables forwarded into operator
+   * sandbox commands (provisioning setup, exec, and start alike). The guest
+   * environment is otherwise always built from an empty record — never the
+   * process environment — so no credential can leak in. */
+  sandboxEnvironmentVariables?: readonly string[]
+}
+
+/** Vercel-backed working copy and executor. Completed SDK command output is
+ * read only for readiness/validation reporting and declared system-provisioning
+ * failure diagnostics, including failures during durable build provisioning. It
+ * is not a durable build-state channel; scoped Store facts/events remain the
+ * authoritative build-state channel. */
+export class VercelSandboxProvider implements WorkspaceProvider {
+  readonly name = 'vercel-sandbox'
+  readonly buildExecution: BuildExecution
+  readonly harvestExecution: HarvestExecution
+  readonly orchestratorSandbox: OperatorSandboxExecution
+  readonly publication
+  readonly recovery
+  private readonly facade: VercelSandboxFacade
+  private readonly exec: Exec
+  private readonly active = new Set<string>()
+  /** A failed stop leaves execution state unknown until a later stop/delete succeeds. */
+  private readonly uncertain = new Set<string>()
+  private readonly origins = new Map<string, ReturnType<typeof cleanGithubOrigin>>()
+  private readonly sessions = new Map<string, VercelSandboxHandle>()
+  private readonly observeWaitMs: number
+
+  constructor(private readonly options: VercelSandboxProviderOptions) {
+    if (!/^https:\/\//i.test(options.storeRef) || options.storeToken === '') {
+      throw new Error('vercel-sandbox requires an HTTPS BuildStore and scoped AB_TOKEN authority')
+    }
+    this.facade = options.facade ?? createVercelSdkFacade(options.env)
+    this.exec = options.exec ?? spawnExec
+    this.observeWaitMs = options.observeWaitMs ?? VERCEL_OBSERVE_WAIT_MS
+    this.buildExecution = {
+      start: (input) => this.start(input),
+      observe: (identity) => this.observeExecution(identity),
+    }
+    this.harvestExecution = {
+      start: (input) => this.startHarvestExecution(input),
+      observe: (identity) => this.observeExecution(identity),
+    }
+    this.orchestratorSandbox = {
+      describe: (input) => this.describeOperatorSandbox(input),
+      ensure: (input) => this.ensureOperatorSandbox(input),
+      exec: (handle, request) => this.sandboxExec(handle, request),
+      start: (handle, request) => this.sandboxStart(handle, request),
+      wait: (handle, input) => this.sandboxWait(handle, input),
+      readFile: (handle, path) => this.sandboxReadFile(handle, path),
+      writeFile: (handle, path, content) => this.sandboxWriteFile(handle, path, content),
+      stop: (input) => this.sandboxStop(input),
+      release: (input) => this.sandboxRelease(input),
+    }
+    this.recovery = {
+      reap: (handle: WorkspaceHandle) => {
+        if (handle.provider !== this.name) {
+          throw new Error(
+            `vercel-sandbox cannot reap a workspace owned by provider "${handle.provider}" (${handle.ref})`,
+          )
+        }
+        return this.reap(handle.ref)
+      },
+    }
+    this.publication = {
+      isPublished: (input: { sha: string; branch: string }) => this.isPublished(input),
+      publish: (input: { ref: string; sha: string; branch: string }) => this.publish(input),
+    }
+  }
+
+  async provision(opts: {
+    repo: string
+    baseBranch: string
+    branch: string
+    revision?: string
+    generation?: number
+  }): Promise<WorkspaceProvisionResult> {
+    const rawOrigin = await this.origin()
+    const origin = cleanGithubOrigin(rawOrigin)
+    const name = sandboxName(origin.url, opts.branch, opts.generation)
+    // Resolved once, before the create/reuse branch: the version the current
+    // archive source would deliver, against which both a fresh install's
+    // marker and a reused sandbox's marker are compared.
+    const distributionVersion = await (
+      this.options.distributionVersion ?? readDistributionIdentity
+    )()
+    let sandbox = await this.facade.get(name, this.operationSignal())
+    const existing = await this.remoteBranchHead(opts.branch, `remote branch ${opts.branch}`)
+    const base =
+      existing ??
+      opts.revision ??
+      (await this.remoteBranchHead(opts.baseBranch, `remote base ${opts.baseBranch}`))
+    if (base === null)
+      throw new Error(
+        `remote branch ${existing === null ? opts.baseBranch : opts.branch} does not exist`,
+      )
+
+    if (sandbox !== null) {
+      const marker = await sandbox.runCommand({
+        cmd: 'test',
+        args: ['-f', VERCEL_PROVISIONED_MARKER],
+      })
+      if (marker.exitCode === 0) {
+        const installed = await readDistributionVersionMarker(sandbox, this.operationSignal())
+        if (installed === distributionVersion) {
+          await sandbox.stop({ signal: this.operationSignal() })
+        } else {
+          // A completed sandbox whose installed distribution disagrees with
+          // what the current system would deliver — including legacy guests
+          // without a marker — is refreshed in place. Any refresh failure
+          // deletes the sandbox so the next pass rematerializes cleanly.
+          try {
+            const archive = await (this.options.packageArchive ?? defaultDistributionArchive)()
+            await installDistribution(sandbox, archive, distributionVersion, this.operationSignal())
+          } catch (error) {
+            try {
+              this.sessions.set(name, sandbox)
+              await this.reap(name)
+            } catch (deleteError) {
+              throw new AggregateError(
+                [error, deleteError],
+                `sandbox ${name} distribution refresh failed and its incomplete environment could not be confirmed deleted`,
+              )
+            }
+            throw error
+          }
+          await sandbox.stop({ signal: this.operationSignal() })
+        }
+      } else {
+        // A named VM without the marker is a crashed/legacy provisioning
+        // attempt. Never expose its potentially unscrubbed checkout to agents.
+        await sandbox.delete({ signal: this.operationSignal() })
+        sandbox = null
+      }
+    }
+
+    if (sandbox === null) {
+      const username =
+        this.options.config.gitUsernameEnv === undefined
+          ? undefined
+          : requireVercelEnvironmentValue(this.options.env, this.options.config.gitUsernameEnv)
+      const password =
+        this.options.config.gitPasswordEnv === undefined
+          ? undefined
+          : requireVercelEnvironmentValue(this.options.env, this.options.config.gitPasswordEnv)
+      const readAuth =
+        password === undefined
+          ? undefined
+          : `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`
+      sandbox = await this.facade.create({
+        name,
+        source: {
+          type: 'git',
+          url: origin.url,
+          revision: base,
+          ...(username !== undefined && password !== undefined ? { username, password } : {}),
+        },
+        image: this.options.config.image,
+        resources: { vcpus: this.options.config.vcpus },
+        timeout: this.options.config.timeoutSeconds * 1000,
+        persistent: true,
+        ...(this.options.config.region !== undefined ? { region: this.options.config.region } : {}),
+        ...(this.options.config.failoverRegions.length > 0
+          ? { failoverRegions: this.options.config.failoverRegions }
+          : {}),
+        ...(this.options.config.snapshotExpirationSeconds === undefined
+          ? {}
+          : { snapshotExpiration: this.options.config.snapshotExpirationSeconds * 1000 }),
+        networkPolicy: uploadPackPolicy(origin, readAuth),
+        keepLastSnapshots: { count: VERCEL_KEEP_LAST_SNAPSHOTS, deleteEvicted: true },
+        signal: this.operationSignal(),
+      })
+      try {
+        await relocateCheckout(sandbox, origin.directory)
+        await commandOrThrow(sandbox, {
+          cmd: 'git',
+          args: ['checkout', '-B', opts.branch, base],
+          cwd: VERCEL_WORKSPACE_PATH,
+        })
+        await commandOrThrow(sandbox, {
+          cmd: 'git',
+          args: ['remote', 'set-url', 'origin', origin.url],
+          cwd: VERCEL_WORKSPACE_PATH,
+        })
+        for (const key of [
+          'credential.helper',
+          'http.extraheader',
+          `http.${origin.url}.extraheader`,
+        ]) {
+          const result = await sandbox.runCommand({
+            cmd: 'git',
+            args: ['config', '--local', '--unset-all', key],
+            cwd: VERCEL_WORKSPACE_PATH,
+          })
+          if (result.exitCode !== 0 && result.exitCode !== 5)
+            throw new Error(`failed to scrub git config ${key}`)
+        }
+        await provisionBun(sandbox, this.options.config.image)
+        await runSystemProvisioning(sandbox, this.options.config.provisioning ?? [])
+        const archive = await (this.options.packageArchive ?? defaultDistributionArchive)()
+        await installDistribution(sandbox, archive, distributionVersion, this.operationSignal())
+        // Repository dependencies precede branch-owned package plugin loading.
+        // The fixed bootstrap supports the consuming repository's lockfile; its
+        // configured setup command still runs at every runner attachment.
+        await commandOrThrow(sandbox, {
+          cmd: 'sh',
+          args: [
+            '-c',
+            `if [ -f bun.lock ] || [ -f bun.lockb ]; then ${VERCEL_BUN_EXECUTABLE} install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; elif [ -f pnpm-lock.yaml ]; then corepack pnpm install --frozen-lockfile; elif [ -f yarn.lock ]; then corepack yarn install --immutable; fi`,
+          ],
+          cwd: VERCEL_WORKSPACE_PATH,
+        })
+        await bootstrapRuntimes(
+          sandbox,
+          this.options.config,
+          runtimeEnvironment(this.options.config, this.options.env),
+          currentRuntimeReferences(this.options.runtimeReferences),
+          true,
+        )
+        await commandOrThrow(sandbox, {
+          cmd: 'touch',
+          args: [VERCEL_PROVISIONED_MARKER],
+        })
+        await sandbox.stop({ signal: this.operationSignal() })
+      } catch (error) {
+        try {
+          this.sessions.set(name, sandbox)
+          await this.reap(name)
+        } catch (deleteError) {
+          throw new AggregateError(
+            [error, deleteError],
+            `sandbox ${name} setup failed and its incomplete environment could not be confirmed deleted`,
+          )
+        }
+        throw error
+      }
+    }
+    this.origins.set(name, origin)
+    this.sessions.set(name, sandbox)
+    return {
+      provider: this.name,
+      ref: name,
+      path: VERCEL_WORKSPACE_PATH,
+      branch: opts.branch,
+      base: { source: existing === null ? 'remote' : 'existing', sha: base },
+    }
+  }
+
+  async release(handle: WorkspaceHandle): Promise<void> {
+    if (this.active.has(handle.ref)) throw new Error(`cannot release active sandbox ${handle.ref}`)
+    await this.reap(handle.ref)
+  }
+
+  private operationSignal(): AbortSignal {
+    return AbortSignal.timeout(this.options.config.operationTimeoutMs ?? 30_000)
+  }
+
+  /** Stop/delete and then prove absence by exact deterministic name — for the
+   * sandbox and, because deleting a sandbox never removes the automatic
+   * snapshots its sessions created, for its snapshot storage too. */
+  private async reap(ref: string): Promise<WorkspaceReapOutcome> {
+    let sandbox = this.sessions.get(ref) ?? (await this.facade.get(ref, this.operationSignal()))
+    if (sandbox === null) {
+      // An environment can vanish without its snapshots; the purge still
+      // applies and only a confirmed empty list may forget the reference.
+      try {
+        const snapshots = await this.purgeOrRetryable(ref)
+        this.forget(ref)
+        return { outcome: 'absent', snapshots }
+      } catch (error) {
+        throw this.retryableCleanup(ref, error)
+      }
+    }
+    try {
+      try {
+        await sandbox.stop({ signal: this.operationSignal() })
+      } catch (error) {
+        // A persistent sandbox that was resumed once can wedge so that stop
+        // never returns while delete still succeeds within seconds. Absence
+        // is proven below either way, so a timed-out stop is not fatal.
+        if (!isInterruptedLongPoll(error)) throw error
+      }
+      // Purge between stop and delete: the sandbox still exists, so the exact
+      // name filter is unambiguous, and after the explicit stop no new
+      // snapshot can be created.
+      const purged = await this.purgeOrRetryable(ref)
+      await sandbox.delete({ signal: this.operationSignal() })
+      sandbox = await this.facade.get(ref, this.operationSignal())
+      if (sandbox !== null)
+        throw new Error(`sandbox ${ref} still exists after delete acknowledgement`)
+      // The post-delete pass catches anything the delete itself created;
+      // after the stop above it is normally empty.
+      const postDelete = await this.purgeOrRetryable(ref)
+      this.forget(ref)
+      return {
+        outcome: 'confirmed',
+        snapshots: {
+          outcome: 'confirmed',
+          deleted: purged.deleted + postDelete.deleted,
+        },
+      }
+    } catch (error) {
+      this.uncertain.add(ref)
+      this.sessions.delete(ref)
+      throw this.retryableCleanup(ref, error)
+    }
+  }
+
+  /** Purge one environment's snapshots, converting an unknown outcome into
+   * the retryable cleanup failure the dispatcher already retries. */
+  private async purgeOrRetryable(ref: string): Promise<VercelSnapshotPurge> {
+    const purged = await purgeEnvironmentSnapshots(this.facade, ref, this.operationSignal())
+    if (purged.outcome === 'unknown') {
+      throw new Error(
+        `snapshot purge for ${JSON.stringify(ref)} is unconfirmed: ${purged.error ?? 'unknown outcome'}`,
+      )
+    }
+    return purged
+  }
+
+  private retryableCleanup(ref: string, error: unknown): Error {
+    return new Error(
+      `sandbox ${ref} cleanup outcome is unknown and remains retryable: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    )
+  }
+
+  private forget(ref: string): void {
+    this.active.delete(ref)
+    this.uncertain.delete(ref)
+    this.sessions.delete(ref)
+    this.origins.delete(ref)
+  }
+
+  private async normalNetworkPolicy(ref: string): Promise<{
+    origin: ReturnType<typeof cleanGithubOrigin>
+    policy: NetworkPolicy
+  }> {
+    const origin = this.origins.get(ref) ?? cleanGithubOrigin(await this.origin())
+    this.origins.set(ref, origin)
+    return {
+      origin,
+      policy: uploadPackPolicy(
+        origin,
+        this.options.config.gitPasswordEnv === undefined
+          ? undefined
+          : `Basic ${Buffer.from(`${requireVercelEnvironmentValue(this.options.env, this.options.config.gitUsernameEnv!)}:${requireVercelEnvironmentValue(this.options.env, this.options.config.gitPasswordEnv)}`).toString('base64')}`,
+      ),
+    }
+  }
+
+  private async start(input: BuildExecutionStart): Promise<BuildExecutionHandle> {
+    const ref = input.workspaceRef
+    if (this.active.has(ref)) throw new Error(`sandbox ${ref} already has a live execution`)
+    const sandbox = this.sessions.get(ref) ?? (await this.facade.get(ref, this.operationSignal()))
+    if (sandbox === null) throw new Error(`sandbox ${ref} no longer exists`)
+    // A prior publication restore may have failed. Reassert the
+    // receive-pack-free policy before any guest command can run.
+    const { policy } = await this.normalNetworkPolicy(ref)
+    await sandbox.update({ networkPolicy: policy }, { signal: this.operationSignal() })
+    if (this.uncertain.has(ref)) {
+      // A prior wait/stop failure may have left agent code alive. Confirm a
+      // stop before starting another runner in the same environment.
+      await sandbox.stop({ signal: this.operationSignal() })
+      this.uncertain.delete(ref)
+    }
+    await preflightBun(sandbox, this.options.config.image)
+    await bootstrapRuntimes(
+      sandbox,
+      this.options.config,
+      runtimeEnvironment(this.options.config, this.options.env),
+      currentRuntimeReferences(this.options.runtimeReferences),
+      false,
+    )
+    this.sessions.set(ref, sandbox)
+    const env: Record<string, string> = {
+      AB_STORE: this.options.storeRef,
+      AB_TOKEN: this.options.storeToken,
+      [BUILD_RUNNER_OPTIONS_ENV]: JSON.stringify({
+        ...input,
+        supervision: { kind: 'environment' },
+      }),
+    }
+    for (const name of this.options.config.environmentVariables)
+      env[name] = requireVercelEnvironmentValue(this.options.env, name)
+    const command = (await sandbox.runCommand({
+      cmd: 'sh',
+      args: [
+        '-c',
+        `PATH=${VERCEL_BUN_BIN_PATH}:$PATH exec ${VERCEL_BUN_EXECUTABLE} ${VERCEL_AUTOBUILD_PATH}/bin/ab-build-runner.ts`,
+      ],
+      cwd: VERCEL_WORKSPACE_PATH,
+      env,
+      detached: true,
+      signal: this.operationSignal(),
+    })) as VercelCommand
+    return this.environmentSupervisedHandle(ref, sandbox, command)
+  }
+
+  /** Shared post-launch supervision of one detached guest command: command
+   * wait with lifetime-bounded long-poll retries, environment-owned teardown,
+   * and the durable identity a later process re-observes. Used by both the
+   * build path and the hosted harvest path. */
+  private environmentSupervisedHandle(
+    ref: string,
+    sandbox: VercelSandboxHandle,
+    command: VercelCommand,
+  ): BuildExecutionHandle {
+    this.active.add(ref)
+    let environmentStop: Promise<void> | undefined
+    const stopEnvironment = async (): Promise<void> => {
+      environmentStop ??= (async () => {
+        try {
+          await sandbox.stop({ signal: this.operationSignal() })
+        } catch (error) {
+          // Do not retain a potentially expired/stale SDK handle. A later
+          // execution must first re-resolve and confirm teardown.
+          this.uncertain.add(ref)
+          this.sessions.delete(ref)
+          throw error
+        } finally {
+          this.active.delete(ref)
+        }
+      })()
+      await environmentStop
+    }
+    let stopping: Promise<void> | undefined
+    const stop = async () => {
+      stopping ??= (async () => {
+        try {
+          await command.kill('SIGTERM', { abortSignal: this.operationSignal() })
+        } catch {
+          /* already exited */
+        }
+        await stopEnvironment()
+      })()
+      await stopping
+    }
+    // Retry interrupted long-polls only within the environment's own
+    // lifetime (plus a margin for stop/snapshot); past that the command
+    // cannot still be running and the failure is real.
+    const lifetimeDeadline =
+      Date.now() + this.options.config.timeoutSeconds * 1000 + VERCEL_LIFETIME_MARGIN_MS
+    // Detach (teardown of the LOCAL supervision only) aborts this wait so the
+    // process can exit while the guest keeps running and heartbeating its
+    // lease. A later invocation settles the execution from the Store plus
+    // provider liveness.
+    const localWait = new AbortController()
+    let detached = false
+    const completion = waitForCommandExit(command, () => Date.now() > lifetimeDeadline, {
+      signal: localWait.signal,
+    }).then(
+      async (result): Promise<BuildExecutionExit> => {
+        if (detached) return { exitCode: result.exitCode }
+        await stopEnvironment()
+        return { exitCode: result.exitCode }
+      },
+      async (error): Promise<BuildExecutionExit> => {
+        if (detached) return { exitCode: null }
+        await stopEnvironment()
+        throw error
+      },
+    )
+    const sessionId = sandbox.currentSession?.().sessionId
+    return {
+      identity: {
+        provider: this.name,
+        workspaceRef: ref,
+        environmentId: sandbox.name,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(command.cmdId !== undefined && command.cmdId !== ''
+          ? { commandId: command.cmdId }
+          : {}),
+      },
+      supervision: 'environment',
+      completion,
+      stop: async () => {
+        try {
+          await stop()
+          return { outcome: 'confirmed' }
+        } catch (error) {
+          return {
+            outcome: 'unknown',
+            error: error instanceof Error ? error.message : String(error),
+          }
+        }
+      },
+      detach: async () => {
+        detached = true
+        localWait.abort()
+      },
+    }
+  }
+
+  /** Hosted harvest (AUT-305): provision (or reuse) the repository's one
+   * disposable environment from the remote base head, launch the guest
+   * harvest runner as one detached command, and supervise it exactly like a
+   * build execution. Provisioning reuses the module-local build chain so a
+   * harvest guest is identical to a build guest; release is the provider's
+   * existing reap path (stop, snapshot purge, delete). */
+  private async startHarvestExecution(input: HarvestExecutionStart): Promise<BuildExecutionHandle> {
+    const origin = cleanGithubOrigin(await this.origin())
+    const name = harvestSandboxName(origin.url)
+    if (this.active.has(name)) throw new Error(`sandbox ${name} already has a live execution`)
+    // Resolved once, before the create/reuse branch: the version the current
+    // archive source would deliver, against which both a fresh install's
+    // marker and a reused environment's marker are compared.
+    const distributionVersion = await (
+      this.options.distributionVersion ?? readDistributionIdentity
+    )()
+    let sandbox = await this.facade.get(name, this.operationSignal())
+    if (sandbox !== null) {
+      const marker = await sandbox.runCommand({
+        cmd: 'test',
+        args: ['-f', VERCEL_PROVISIONED_MARKER],
+      })
+      if (marker.exitCode !== 0) {
+        // A named VM without the marker is a crashed/legacy provisioning
+        // attempt — e.g. a host that died mid-provision. Never expose its
+        // potentially unscrubbed checkout to agents.
+        await sandbox.delete({ signal: this.operationSignal() })
+        sandbox = null
+      } else {
+        // A completed environment left by an earlier (interrupted) run is
+        // stopped and reused. A reused guest whose installed distribution
+        // disagrees with what the current system would deliver is refreshed
+        // in place, mirroring the build reuse path.
+        const installed = await readDistributionVersionMarker(sandbox, this.operationSignal())
+        if (installed !== distributionVersion) {
+          try {
+            const archive = await (this.options.packageArchive ?? defaultDistributionArchive)()
+            await installDistribution(sandbox, archive, distributionVersion, this.operationSignal())
+          } catch (error) {
+            try {
+              this.sessions.set(name, sandbox)
+              await this.reap(name)
+            } catch (deleteError) {
+              throw new AggregateError(
+                [error, deleteError],
+                `harvest sandbox ${name} distribution refresh failed and its incomplete environment could not be confirmed deleted`,
+              )
+            }
+            throw error
+          }
+        }
+        await sandbox.stop({ signal: this.operationSignal() })
+      }
+    }
+    if (sandbox === null) {
+      const head = await this.remoteBranchHead(input.baseBranch, `remote base ${input.baseBranch}`)
+      if (head === null) {
+        throw new Error(`remote base ${input.baseBranch} does not exist`)
+      }
+      const username =
+        this.options.config.gitUsernameEnv === undefined
+          ? undefined
+          : requireVercelEnvironmentValue(this.options.env, this.options.config.gitUsernameEnv)
+      const password =
+        this.options.config.gitPasswordEnv === undefined
+          ? undefined
+          : requireVercelEnvironmentValue(this.options.env, this.options.config.gitPasswordEnv)
+      const readAuth =
+        password === undefined
+          ? undefined
+          : `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`
+      sandbox = await this.facade.create({
+        name,
+        source: {
+          type: 'git',
+          url: origin.url,
+          revision: head,
+          ...(username !== undefined && password !== undefined ? { username, password } : {}),
+        },
+        image: this.options.config.image,
+        resources: { vcpus: this.options.config.vcpus },
+        timeout: this.options.config.timeoutSeconds * 1000,
+        persistent: true,
+        ...(this.options.config.region !== undefined ? { region: this.options.config.region } : {}),
+        ...(this.options.config.failoverRegions.length > 0
+          ? { failoverRegions: this.options.config.failoverRegions }
+          : {}),
+        ...(this.options.config.snapshotExpirationSeconds === undefined
+          ? {}
+          : { snapshotExpiration: this.options.config.snapshotExpirationSeconds * 1000 }),
+        networkPolicy: uploadPackPolicy(origin, readAuth),
+        keepLastSnapshots: { count: VERCEL_KEEP_LAST_SNAPSHOTS, deleteEvicted: true },
+        signal: this.operationSignal(),
+      })
+      try {
+        await relocateCheckout(sandbox, origin.directory)
+        await commandOrThrow(sandbox, {
+          cmd: 'git',
+          args: ['remote', 'set-url', 'origin', origin.url],
+          cwd: VERCEL_WORKSPACE_PATH,
+        })
+        for (const key of [
+          'credential.helper',
+          'http.extraheader',
+          `http.${origin.url}.extraheader`,
+        ]) {
+          const result = await sandbox.runCommand({
+            cmd: 'git',
+            args: ['config', '--local', '--unset-all', key],
+            cwd: VERCEL_WORKSPACE_PATH,
+          })
+          if (result.exitCode !== 0 && result.exitCode !== 5)
+            throw new Error(`failed to scrub git config ${key}`)
+        }
+        await provisionBun(sandbox, this.options.config.image)
+        await runSystemProvisioning(sandbox, this.options.config.provisioning ?? [])
+        const archive = await (this.options.packageArchive ?? defaultDistributionArchive)()
+        await installDistribution(sandbox, archive, distributionVersion, this.operationSignal())
+        // Repository dependencies precede runtime preflight; the fixed
+        // bootstrap is the same one build provisioning runs.
+        await commandOrThrow(sandbox, {
+          cmd: 'sh',
+          args: [
+            '-c',
+            `if [ -f bun.lock ] || [ -f bun.lockb ]; then ${VERCEL_BUN_EXECUTABLE} install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; elif [ -f pnpm-lock.yaml ]; then corepack pnpm install --frozen-lockfile; elif [ -f yarn.lock ]; then corepack yarn install --immutable; fi`,
+          ],
+          cwd: VERCEL_WORKSPACE_PATH,
+        })
+        await bootstrapRuntimes(
+          sandbox,
+          this.options.config,
+          runtimeEnvironment(this.options.config, this.options.env),
+          currentRuntimeReferences(this.options.runtimeReferences),
+          true,
+        )
+        await commandOrThrow(sandbox, {
+          cmd: 'touch',
+          args: [VERCEL_PROVISIONED_MARKER],
+        })
+        await sandbox.stop({ signal: this.operationSignal() })
+      } catch (error) {
+        try {
+          this.sessions.set(name, sandbox)
+          await this.reap(name)
+        } catch (deleteError) {
+          throw new AggregateError(
+            [error, deleteError],
+            `harvest sandbox ${name} setup failed and its incomplete environment could not be confirmed deleted`,
+          )
+        }
+        throw error
+      }
+    }
+    this.origins.set(name, origin)
+    // Launch: reassert the normal network policy and preflight exactly as the
+    // build start path does, then one detached guest runner command.
+    const { policy } = await this.normalNetworkPolicy(name)
+    await sandbox.update({ networkPolicy: policy }, { signal: this.operationSignal() })
+    if (this.uncertain.has(name)) {
+      // A prior wait/stop failure may have left agent code alive. Confirm a
+      // stop before starting another runner in the same environment.
+      await sandbox.stop({ signal: this.operationSignal() })
+      this.uncertain.delete(name)
+    }
+    await preflightBun(sandbox, this.options.config.image)
+    await bootstrapRuntimes(
+      sandbox,
+      this.options.config,
+      runtimeEnvironment(this.options.config, this.options.env),
+      currentRuntimeReferences(this.options.runtimeReferences),
+      false,
+    )
+    this.sessions.set(name, sandbox)
+    const sessionId = sandbox.currentSession?.().sessionId
+    const envelope: HarvestRunnerLaunch = {
+      ...input,
+      supervision: { kind: 'environment' },
+      environment: {
+        provider: this.name,
+        environmentId: sandbox.name,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+      },
+    }
+    const env: Record<string, string> = {
+      AB_STORE: this.options.storeRef,
+      AB_TOKEN: this.options.storeToken,
+      [HARVEST_RUNNER_OPTIONS_ENV]: JSON.stringify(envelope),
+    }
+    for (const envName of this.options.config.environmentVariables)
+      env[envName] = requireVercelEnvironmentValue(this.options.env, envName)
+    const command = (await sandbox.runCommand({
+      cmd: 'sh',
+      args: [
+        '-c',
+        `PATH=${VERCEL_BUN_BIN_PATH}:$PATH exec ${VERCEL_BUN_EXECUTABLE} ${VERCEL_AUTOBUILD_PATH}/bin/ab-harvest-runner.ts`,
+      ],
+      cwd: VERCEL_WORKSPACE_PATH,
+      env,
+      detached: true,
+      signal: this.operationSignal(),
+    })) as VercelCommand
+    return this.environmentSupervisedHandle(name, sandbox, command)
+  }
+
+  /** Liveness of a previously recorded execution, from provider state alone:
+   * one bounded facade.get, one command lookup, and, when the lookup shows no
+   * exit, one bounded wait on that command. A missing sandbox, a session that
+   * is no longer running, or a command the current (resumed) session no
+   * longer knows is `lost`; a non-null exit code — from the lookup or from
+   * the bounded wait it triggered — is `ended`; an interrupted or timed-out
+   * wait leaves the execution `running`. The lifetime bound (session expiry
+   * plus the shared stop/snapshot margin) runs before the lookup and fails
+   * with the environment named instead of waiting. Unknown provider errors
+   * propagate — callers treat an unresolvable observation as running and
+   * never reap on it. */
+  private async observeExecution(identity: BuildExecutionIdentity): Promise<ExecutionObservation> {
+    if (identity.commandId === undefined) {
+      throw new Error(
+        `execution on ${identity.workspaceRef} has no recorded command id and cannot be re-observed`,
+      )
+    }
+    const sandbox = await this.facade.get(identity.workspaceRef, this.operationSignal())
+    if (sandbox === null) return { state: 'lost' }
+    if (sandbox.sessionStatus !== undefined && sandbox.sessionStatus !== 'running') {
+      return { state: 'lost' }
+    }
+    // Mirrors the command path's VM-lifetime bound: past the environment's
+    // session expiry (plus the shared stop/snapshot margin) the execution
+    // cannot still be running, so re-issuing the long-poll would only end in
+    // a generic transport failure. Fail with the environment named instead.
+    if (sandbox.sessionExpiresAt !== undefined) {
+      const deadline = sandbox.sessionExpiresAt + VERCEL_LIFETIME_MARGIN_MS
+      if (Date.now() > deadline) {
+        throw new Error(
+          `execution on sandbox ${identity.environmentId ?? identity.workspaceRef} cannot still be running: ` +
+            `the environment expired — its session expiry (${new Date(sandbox.sessionExpiresAt).toISOString()}) plus ` +
+            `the ${VERCEL_LIFETIME_MARGIN_MS} ms stop/snapshot margin passed at ${new Date(deadline).toISOString()}`,
+        )
+      }
+    }
+    try {
+      const command = await sandbox.getCommand(identity.commandId, {
+        signal: this.operationSignal(),
+      })
+      if (command.exitCode !== null) return { state: 'ended', exitCode: command.exitCode }
+      // The provider's plain lookup reports no exit code for a command that
+      // finished while no client was waiting on it, and keeps reporting none
+      // until some client waits — so "null" alone proves nothing. One bounded
+      // wait turns it into evidence: a resolved wait is a proved end, an
+      // interrupted or timed-out wait leaves the guest unobserved (`running`),
+      // and a missing sandbox is `lost`. Never re-issued here; the next tick
+      // retries. The bound composes the provider operation signal so one
+      // observation never approaches the tick's operation timeout.
+      try {
+        const finished = await command.wait({
+          signal: AbortSignal.any([
+            AbortSignal.timeout(this.observeWaitMs),
+            this.operationSignal(),
+          ]),
+        })
+        return { state: 'ended', exitCode: finished.exitCode }
+      } catch (error) {
+        if (isMissingVercelSandbox(error)) return { state: 'lost' }
+        if (isInterruptedLongPoll(error)) return { state: 'running' }
+        throw error
+      }
+    } catch (error) {
+      if (isMissingVercelSandbox(error)) return { state: 'lost' }
+      throw error
+    }
+  }
+
+  // ── Operator sandbox capability (AUT-340) ─────────────────────────
+  //
+  // One persistent, credential-free environment per operator × repository,
+  // provisioned with the build workspace's chain and exposed only through
+  // the registry's sandbox tools. The environment receives no store, forge,
+  // ticket-provider, or model credential: the guest environment below is
+  // built from an empty record plus forwarded names, and the git read
+  // credential enters only as a network-policy header transform.
+
+  /** The credential-free guest environment: one fresh record per call —
+   * never the process environment — holding exactly the forwarded
+   * `sandboxEnvironmentVariables`. A missing host value is a typed
+   * `environment` failure rather than a silent absence. The toolchain PATH is
+   * deliberately NOT part of the record: the SDK passes env values through
+   * verbatim, so a literal `$PATH` there would never be expanded — the PATH
+   * is prepended inside the guest shell instead (the same channel the build
+   * runner uses). Shared by the setup command and every tool `exec`/`start`. */
+  private sandboxEnv(): Record<string, string> {
+    const env: Record<string, string> = {}
+    for (const name of this.options.sandboxEnvironmentVariables ?? []) {
+      const value = this.options.env[name]
+      if (value === undefined || value === '') {
+        throw new SandboxOperationError(
+          'environment',
+          `operator sandbox environment variable ${name} is not set in the host environment`,
+        )
+      }
+      env[name] = value
+    }
+    return env
+  }
+
+  /** The toolchain PATH as a shell prefix: the guest shell expands `$PATH`
+   * from its own ambient environment, so guests get the autobuild toolchain
+   * ahead of the image's default PATH without the env record ever carrying an
+   * unexpanded literal. */
+  private sandboxPathPrefix(): string {
+    return `PATH=${VERCEL_BUN_BIN_PATH}:${VERCEL_AUTOBUILD_PATH}/bin:$PATH; export PATH; `
+  }
+
+  private async describeOperatorSandbox(input: {
+    operator: string
+  }): Promise<SandboxEnvironmentIdentity> {
+    const origin = cleanGithubOrigin(await this.origin())
+    return {
+      provider: this.name,
+      environmentId: sandboxEnvironmentName(origin.url, input.operator),
+      workspacePath: VERCEL_WORKSPACE_PATH,
+    }
+  }
+
+  /** Provision-or-resume. A persistent sandbox auto-resumes on the first SDK
+   * call that needs a running session, so the reuse path re-checks the
+   * distribution marker exactly as the build reuse path does and then leaves
+   * the session running for the tool call. A fresh provision runs the same
+   * chain as a build workspace and ends by running the repository's setup
+   * command; it leaves the environment running too (the tool call follows
+   * immediately; the idle settlement stops it later). */
+  private async ensureOperatorSandbox(input: {
+    repo: string
+    operator: string
+    baseBranch: string
+  }): Promise<SandboxEnvironmentIdentity> {
+    const origin = cleanGithubOrigin(await this.origin())
+    const name = sandboxEnvironmentName(origin.url, input.operator)
+    const distributionVersion = await (
+      this.options.distributionVersion ?? readDistributionIdentity
+    )()
+    let sandbox = await this.facade.get(name, this.operationSignal())
+    if (sandbox !== null) {
+      const marker = await sandbox.runCommand({
+        cmd: 'test',
+        args: ['-f', VERCEL_PROVISIONED_MARKER],
+      })
+      if (marker.exitCode !== 0) {
+        // A named VM without the marker is a crashed/legacy provisioning
+        // attempt. Never expose its potentially unscrubbed checkout.
+        await sandbox.delete({ signal: this.operationSignal() })
+        sandbox = null
+      } else {
+        const installed = await readDistributionVersionMarker(sandbox, this.operationSignal())
+        if (installed !== distributionVersion) {
+          // A reused environment whose installed distribution disagrees with
+          // what the current system would deliver is refreshed in place,
+          // exactly as build guests are. Refresh failure deletes the
+          // environment so the next call rematerializes it cleanly.
+          try {
+            const archive = await (this.options.packageArchive ?? defaultDistributionArchive)()
+            await installDistribution(sandbox, archive, distributionVersion, this.operationSignal())
+          } catch (error) {
+            try {
+              this.sessions.set(name, sandbox)
+              await this.reap(name)
+            } catch (deleteError) {
+              throw new AggregateError(
+                [error, deleteError],
+                `operator sandbox ${name} distribution refresh failed and its incomplete environment could not be confirmed deleted`,
+              )
+            }
+            throw error
+          }
+        }
+        const sessionId = sandbox.currentSession?.().sessionId
+        this.sessions.set(name, sandbox)
+        return {
+          provider: this.name,
+          environmentId: name,
+          ...(sessionId !== undefined ? { sessionId } : {}),
+          workspacePath: VERCEL_WORKSPACE_PATH,
+        }
+      }
+    }
+    const head = await this.remoteBranchHead(input.baseBranch, `remote base ${input.baseBranch}`)
+    if (head === null) {
+      throw new SandboxOperationError('provision', `remote base ${input.baseBranch} does not exist`)
+    }
+    const username =
+      this.options.config.gitUsernameEnv === undefined
+        ? undefined
+        : requireVercelEnvironmentValue(this.options.env, this.options.config.gitUsernameEnv)
+    const password =
+      this.options.config.gitPasswordEnv === undefined
+        ? undefined
+        : requireVercelEnvironmentValue(this.options.env, this.options.config.gitPasswordEnv)
+    const readAuth =
+      password === undefined
+        ? undefined
+        : `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`
+    sandbox = await this.facade.create({
+      name,
+      source: {
+        type: 'git',
+        url: origin.url,
+        revision: head,
+        ...(username !== undefined && password !== undefined ? { username, password } : {}),
+      },
+      image: this.options.config.image,
+      resources: { vcpus: this.options.config.vcpus },
+      timeout: this.options.config.timeoutSeconds * 1000,
+      persistent: true,
+      ...(this.options.config.region !== undefined ? { region: this.options.config.region } : {}),
+      ...(this.options.config.failoverRegions.length > 0
+        ? { failoverRegions: this.options.config.failoverRegions }
+        : {}),
+      ...(this.options.config.snapshotExpirationSeconds === undefined
+        ? {}
+        : { snapshotExpiration: this.options.config.snapshotExpirationSeconds * 1000 }),
+      networkPolicy: uploadPackPolicy(origin, readAuth),
+      keepLastSnapshots: { count: VERCEL_KEEP_LAST_SNAPSHOTS, deleteEvicted: true },
+      signal: this.operationSignal(),
+    })
+    try {
+      await relocateCheckout(sandbox, origin.directory)
+      await commandOrThrow(sandbox, {
+        cmd: 'git',
+        args: ['remote', 'set-url', 'origin', origin.url],
+        cwd: VERCEL_WORKSPACE_PATH,
+      })
+      for (const key of [
+        'credential.helper',
+        'http.extraheader',
+        `http.${origin.url}.extraheader`,
+      ]) {
+        const result = await sandbox.runCommand({
+          cmd: 'git',
+          args: ['config', '--local', '--unset-all', key],
+          cwd: VERCEL_WORKSPACE_PATH,
+        })
+        if (result.exitCode !== 0 && result.exitCode !== 5)
+          throw new Error(`failed to scrub git config ${key}`)
+      }
+      await provisionBun(sandbox, this.options.config.image)
+      await runSystemProvisioning(sandbox, this.options.config.provisioning ?? [])
+      const archive = await (this.options.packageArchive ?? defaultDistributionArchive)()
+      await installDistribution(sandbox, archive, distributionVersion, this.operationSignal())
+      // Repository dependencies precede the setup command; the fixed
+      // bootstrap is the same one build provisioning runs.
+      await commandOrThrow(sandbox, {
+        cmd: 'sh',
+        args: [
+          '-c',
+          `if [ -f bun.lock ] || [ -f bun.lockb ]; then ${VERCEL_BUN_EXECUTABLE} install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; elif [ -f pnpm-lock.yaml ]; then corepack pnpm install --frozen-lockfile; elif [ -f yarn.lock ]; then corepack yarn install --immutable; fi`,
+        ],
+        cwd: VERCEL_WORKSPACE_PATH,
+      })
+      // Runtime provisioning precedes the setup command, exactly as the build
+      // chain orders it. The guest env is the sandbox-forwarded set only: a
+      // runtime provisioning command that needs a build-workspace variable
+      // must have that name added to [orchestrator].sandbox.environmentVariables.
+      const runtimeReferences = currentRuntimeReferences(this.options.runtimeReferences)
+      if (runtimeReferences.length > 0) {
+        await bootstrapRuntimes(
+          sandbox,
+          this.options.config,
+          this.sandboxEnv(),
+          runtimeReferences,
+          true,
+          this.operationSignal(),
+        )
+      }
+      const setupCommand = this.options.setupCommand
+      if (setupCommand !== undefined && setupCommand.trim() !== '') {
+        await readableCommand(sandbox, {
+          cmd: 'sh',
+          args: ['-c', `${this.sandboxPathPrefix()}${setupCommand}`],
+          cwd: VERCEL_WORKSPACE_PATH,
+          env: this.sandboxEnv(),
+        })
+      }
+      await commandOrThrow(sandbox, {
+        cmd: 'touch',
+        args: [VERCEL_PROVISIONED_MARKER],
+      })
+    } catch (error) {
+      // Nothing unrecorded or half-built survives: reap the half-provisioned
+      // environment through the same sessions.set + reap pattern as builds.
+      try {
+        this.sessions.set(name, sandbox)
+        await this.reap(name)
+      } catch (deleteError) {
+        throw new AggregateError(
+          [error, deleteError],
+          `operator sandbox ${name} setup failed and its incomplete environment could not be confirmed deleted`,
+        )
+      }
+      throw error instanceof SandboxOperationError
+        ? error
+        : new SandboxOperationError(
+            'provision',
+            error instanceof Error ? error.message : String(error),
+            { cause: error },
+          )
+    }
+    this.origins.set(name, origin)
+    const sessionId = sandbox.currentSession?.().sessionId
+    this.sessions.set(name, sandbox)
+    return {
+      provider: this.name,
+      environmentId: name,
+      ...(sessionId !== undefined ? { sessionId } : {}),
+      workspacePath: VERCEL_WORKSPACE_PATH,
+    }
+  }
+
+  /** Resolve the live handle behind a journal-carried environment id. A
+   * missing environment is a typed `not-found`; the persistent sandbox
+   * auto-resumes on the first SDK call that needs a session. */
+  private async sandboxHandle(handle: SandboxEnvironmentIdentity): Promise<VercelSandboxHandle> {
+    const sandbox = await this.facade.get(handle.environmentId, this.operationSignal())
+    if (sandbox === null) {
+      throw new SandboxOperationError(
+        'not-found',
+        `operator sandbox ${handle.environmentId} no longer exists`,
+      )
+    }
+    this.sessions.set(handle.environmentId, sandbox)
+    return sandbox
+  }
+
+  /** One bounded-wait mechanism shared by `exec` and `wait` (the
+   * `waitForCommandExit` pattern with the caller's deadline): interrupted
+   * long-polls are re-issued until the explicit deadline; any other failure
+   * propagates immediately. `operationTimeoutMs` bounds only handle lookups
+   * and kill — never the wait itself, so a 300 s command is not cut off at
+   * the 30 s operation timeout. */
+  private async waitForSandboxExit(
+    command: Pick<VercelCommand, 'wait'>,
+    deadlineMs: number,
+  ): Promise<{ exitCode: number }> {
+    for (;;) {
+      try {
+        return await command.wait({})
+      } catch (error) {
+        if (!isInterruptedLongPoll(error) || Date.now() > deadlineMs) throw error
+      }
+    }
+  }
+
+  private async sandboxRootedPath(
+    handle: SandboxEnvironmentIdentity,
+    path: string,
+  ): Promise<string> {
+    if (path.includes('\\')) {
+      throw new SandboxOperationError(
+        'exec',
+        `sandbox path ${JSON.stringify(path)} must use "/" separators`,
+      )
+    }
+    return `${handle.workspacePath.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`
+  }
+
+  private async sandboxLaunch(
+    sandbox: VercelSandboxHandle,
+    request: SandboxCommandRequest,
+  ): Promise<VercelCommand> {
+    const command = (await sandbox.runCommand({
+      cmd: 'sh',
+      // The toolchain PATH is prepended inside the guest shell — the only
+      // channel where `$PATH` expands (the sandbox env doc comment explains
+      // why it cannot ride in the env record).
+      args: ['-c', `${this.sandboxPathPrefix()}${request.command}`],
+      ...(request.cwd !== undefined
+        ? { cwd: `${VERCEL_WORKSPACE_PATH}/${request.cwd.replace(/^\/+/, '')}` }
+        : { cwd: VERCEL_WORKSPACE_PATH }),
+      env: this.sandboxEnv(),
+      detached: true,
+      signal: this.operationSignal(),
+    })) as VercelCommand
+    return command
+  }
+
+  private async sandboxExec(
+    handle: SandboxEnvironmentIdentity,
+    request: SandboxCommandRequest,
+  ): Promise<SandboxCommandResult> {
+    const sandbox = await this.sandboxHandle(handle)
+    const timeoutSeconds = Math.min(
+      Math.max(request.timeoutSeconds ?? 120, 1),
+      SANDBOX_MAX_WAIT_SECONDS,
+    )
+    const command = await this.sandboxLaunch(sandbox, request)
+    const deadline = Date.now() + timeoutSeconds * 1000
+    let exit: { exitCode: number }
+    try {
+      exit = await this.waitForSandboxExit(command, deadline)
+    } catch (error) {
+      if (Date.now() >= deadline) {
+        try {
+          await command.kill('SIGTERM', { abortSignal: this.operationSignal() })
+        } catch {
+          /* already exited */
+        }
+        throw new SandboxOperationError(
+          'exec-timeout',
+          `sandbox command exceeded its ${timeoutSeconds}s bound and was killed`,
+          { cause: error },
+        )
+      }
+      throw new SandboxOperationError(
+        'exec',
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      )
+    }
+    const [stdout, stderr] = await Promise.all([
+      command.stdout?.() ?? Promise.resolve(''),
+      command.stderr?.() ?? Promise.resolve(''),
+    ])
+    return { exitCode: exit.exitCode, stdout, stderr }
+  }
+
+  private async sandboxStart(
+    handle: SandboxEnvironmentIdentity,
+    request: SandboxCommandRequest,
+  ): Promise<{ commandId: string }> {
+    const sandbox = await this.sandboxHandle(handle)
+    const command = await this.sandboxLaunch(sandbox, request)
+    return { commandId: command.cmdId }
+  }
+
+  private async sandboxWait(
+    handle: SandboxEnvironmentIdentity,
+    input: { commandId: string; waitSeconds: number },
+  ): Promise<SandboxWaitResult> {
+    const sandbox = await this.sandboxHandle(handle)
+    const waitSeconds = Math.min(Math.max(input.waitSeconds, 0), SANDBOX_MAX_WAIT_SECONDS)
+    const lookup = await sandbox.getCommand(input.commandId, { signal: this.operationSignal() })
+    if (lookup.exitCode !== null) {
+      const [stdout, stderr] = await Promise.all([
+        lookup.stdout?.() ?? Promise.resolve(''),
+        lookup.stderr?.() ?? Promise.resolve(''),
+      ])
+      return { state: 'exited', exitCode: lookup.exitCode, stdout, stderr }
+    }
+    if (waitSeconds === 0) return { state: 'running' }
+    const deadline = Date.now() + waitSeconds * 1000
+    try {
+      const exit = await this.waitForSandboxExit(lookup, deadline)
+      const [stdout, stderr] = await Promise.all([
+        lookup.stdout?.() ?? Promise.resolve(''),
+        lookup.stderr?.() ?? Promise.resolve(''),
+      ])
+      return { state: 'exited', exitCode: exit.exitCode, stdout, stderr }
+    } catch (error) {
+      if (isMissingVercelSandbox(error)) {
+        throw new SandboxOperationError(
+          'not-found',
+          `operator sandbox ${handle.environmentId} no longer exists`,
+          { cause: error },
+        )
+      }
+      // Interrupted-poll exhaustion at the deadline leaves the command
+      // provably unobserved: still running, no output (Vercel reports
+      // output only after exit). Any other failure is real.
+      if (Date.now() >= deadline || isInterruptedLongPoll(error)) return { state: 'running' }
+      throw new SandboxOperationError(
+        'exec',
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      )
+    }
+  }
+
+  private async sandboxReadFile(
+    handle: SandboxEnvironmentIdentity,
+    path: string,
+  ): Promise<Uint8Array> {
+    const rooted = await this.sandboxRootedPath(handle, path)
+    // Exec-mechanism read through a byte-preserving channel: `base64` on the
+    // rooted path (the path rides as its own argv element), decoded after
+    // exit. Reading the file through the string `stdout()` channel would
+    // mangle arbitrary binary before the registry's utf8-else-base64 branch
+    // could preserve it; base64 survives that channel exactly, and the
+    // decoder strips the wrapping whitespace GNU base64 inserts.
+    const sandbox = await this.sandboxHandle(handle)
+    const command = (await sandbox.runCommand({
+      cmd: 'base64',
+      args: [rooted],
+      cwd: VERCEL_WORKSPACE_PATH,
+      detached: true,
+      signal: this.operationSignal(),
+    })) as VercelCommand
+    const deadline = Date.now() + 120 * 1000
+    let exit: { exitCode: number }
+    try {
+      exit = await this.waitForSandboxExit(command, deadline)
+    } catch (error) {
+      throw new SandboxOperationError(
+        'exec',
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      )
+    }
+    if (exit.exitCode !== 0) {
+      const stderr = await command.stderr?.().catch(() => '')
+      throw new SandboxOperationError(
+        'not-found',
+        `could not read sandbox file ${JSON.stringify(path)}: exit ${exit.exitCode}${stderr ? `: ${stderr.trim()}` : ''}`,
+      )
+    }
+    const stdout = await command.stdout?.().catch(() => '')
+    return new Uint8Array(Buffer.from((stdout ?? '').replace(/\s+/g, ''), 'base64'))
+  }
+
+  private async sandboxWriteFile(
+    handle: SandboxEnvironmentIdentity,
+    path: string,
+    content: Uint8Array,
+  ): Promise<void> {
+    const sandbox = await this.sandboxHandle(handle)
+    const rooted = await this.sandboxRootedPath(handle, path)
+    try {
+      await sandbox.writeFiles([{ path: rooted, content }], {
+        signal: this.operationSignal(),
+      })
+    } catch (error) {
+      throw new SandboxOperationError(
+        'exec',
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      )
+    }
+  }
+
+  private async sandboxStop(input: {
+    operator: string
+    environmentId: string
+  }): Promise<{ outcome: 'stopped' | 'absent' | 'unsupported' }> {
+    const sandbox = await this.facade.get(input.environmentId, this.operationSignal())
+    if (sandbox === null) return { outcome: 'absent' }
+    try {
+      await sandbox.stop({ signal: this.operationSignal() })
+    } catch (error) {
+      // A stopped/expired session may reject a stop idempotently; absence is
+      // proven by re-resolution, and any other failure propagates as typed.
+      const stillThere = await this.facade.get(input.environmentId, this.operationSignal())
+      if (stillThere === null) return { outcome: 'absent' }
+      throw new SandboxOperationError(
+        'exec',
+        error instanceof Error ? error.message : String(error),
+        { cause: error },
+      )
+    }
+    return { outcome: 'stopped' }
+  }
+
+  private async sandboxRelease(input: {
+    repo: string
+    operator: string
+    environmentId: string
+  }): Promise<{
+    snapshots: { outcome: 'confirmed' | 'unknown'; deleted?: number; error?: string }
+  }> {
+    const reap = await this.reap(input.environmentId)
+    return {
+      snapshots: {
+        outcome: reap.snapshots.outcome === 'unknown' ? 'unknown' : 'confirmed',
+        ...(reap.snapshots.deleted !== undefined ? { deleted: reap.snapshots.deleted } : {}),
+        ...(reap.snapshots.error !== undefined ? { error: reap.snapshots.error } : {}),
+      },
+    }
+  }
+
+  /** Host-seam fallbacks: the injected origin/branch-head readers when given
+   * (checkout-less origin mode), otherwise host `git` executed from the
+   * dispatcher-local checkout. */
+  private async origin(): Promise<string> {
+    if (this.options.origin !== undefined) return this.options.origin()
+    return execOrThrow(this.exec, ['git', 'remote', 'get-url', 'origin'], this.options.repo)
+  }
+
+  private async remoteBranchHead(branch: string, label: string): Promise<string | null> {
+    if (this.options.remoteBranchHead !== undefined) {
+      return (await this.options.remoteBranchHead(branch)) ?? null
+    }
+    return oneSha(
+      await execOrThrow(
+        this.exec,
+        ['git', 'ls-remote', '--heads', 'origin', `refs/heads/${branch}`],
+        this.options.repo,
+      ),
+      label,
+    )
+  }
+
+  private async isPublished(input: { sha: string; branch: string }): Promise<boolean> {
+    const head = await this.remoteBranchHead(input.branch, `published branch ${input.branch}`)
+    return head === input.sha
+  }
+
+  private async publish(input: { ref: string; sha: string; branch: string }): Promise<void> {
+    if (this.active.has(input.ref) || this.uncertain.has(input.ref)) {
+      throw new Error('publication is forbidden until sandbox execution teardown is confirmed')
+    }
+    if (!/^[0-9a-f]{40,64}$/i.test(input.sha) || !/^ab\/[a-z0-9][a-z0-9-]*$/.test(input.branch)) {
+      throw new Error('publication requires an exact commit SHA and canonical build branch')
+    }
+    const token = this.options.env.GITHUB_TOKEN || this.options.env.GH_TOKEN
+    if (!token) {
+      throw new Error('vercel-sandbox publication requires GITHUB_TOKEN or GH_TOKEN')
+    }
+    const { origin, policy: normal } = await this.normalNetworkPolicy(input.ref)
+    const sandbox =
+      this.sessions.get(input.ref) ?? (await this.facade.get(input.ref, this.operationSignal()))
+    if (sandbox === null) throw new Error(`unknown sandbox ${input.ref}`)
+    this.sessions.set(input.ref, sandbox)
+    const publicationPolicy: NetworkPolicy = {
+      allow: {
+        [origin.host]: [
+          {
+            match: {
+              method: ['GET'],
+              path: { exact: `${origin.path}/info/refs` },
+              queryString: [{ key: { exact: 'service' }, value: { exact: 'git-receive-pack' } }],
+            },
+            transform: [
+              {
+                headers: {
+                  authorization: `Basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`,
+                },
+              },
+            ],
+          },
+          {
+            match: { method: ['POST'], path: { exact: `${origin.path}/git-receive-pack` } },
+            transform: [
+              {
+                headers: {
+                  authorization: `Basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`,
+                },
+              },
+            ],
+          },
+        ],
+      },
+    }
+    try {
+      await sandbox.update({ networkPolicy: publicationPolicy }, { signal: this.operationSignal() })
+      await commandOrThrow(sandbox, {
+        cmd: 'git',
+        args: ['push', '--no-verify', 'origin', `${input.sha}:refs/heads/${input.branch}`],
+        cwd: VERCEL_WORKSPACE_PATH,
+      })
+      await sandbox.stop({ signal: this.operationSignal() })
+      // Post-push verification without host git: the injected branch-head
+      // reader (origin mode) or the host ls-remote fallback answers.
+      const published = await this.remoteBranchHead(input.branch, 'published branch')
+      if (published !== input.sha)
+        throw new Error(`published head ${published ?? '(missing)'} did not match ${input.sha}`)
+    } finally {
+      try {
+        await sandbox.update({ networkPolicy: normal }, { signal: this.operationSignal() })
+      } finally {
+        await sandbox.stop({ signal: this.operationSignal() })
+      }
+    }
+  }
+}