@defrex/autobuild 0.8.0 → 0.9.0

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

@@ -0,0 +1,110 @@
+/**
+ * The single shared capability object for the `vercel-sandbox` workspace
+ * provider (AUT-517). During the transitional state in which the builtin
+ * hosts the provider implementation, both the builtin registration (in
+ * `builtin-capabilities.ts`) and the `@defrex/autobuild-vercel-sandbox`
+ * plugin reference THIS object, so the two declarations cannot drift: any
+ * future divergence is a compile-time split, not a silently duplicated
+ * closure.
+ *
+ * The parse-time subset comes from `BUILTIN_WORKSPACE_PROVIDER_CONFIG` in
+ * `config/schema.ts`; the registry-seam behaviors and the closures
+ * (`validateOrigin`, `guestEnvNames`, `describeEnvironment`,
+ * `validateReadiness`) are assembled here once.
+ *
+ * Import graph discipline: this module imports `config/schema.ts`,
+ * `github-origin.ts`, and `init-readiness-remote.ts`; nothing imports it
+ * from `schema.ts`, so no cycle exists.
+ */
+import { BUILTIN_WORKSPACE_PROVIDER_CONFIG, type VercelSandboxConfig } from '../../config/schema'
+import { validateRemoteReadiness } from '../../cli/init-readiness-remote'
+import type {
+  WorkspaceProviderCapabilities,
+  WorkspaceReadinessContext,
+} from './provider-capabilities'
+import { validateVercelGithubOrigin } from './github-origin'
+
+/** The parse-time declaration subset from the config table, without the
+ * parse-site refusal text (which never belongs on the capability). */
+function pickConfigDeclaration(name: string): WorkspaceProviderCapabilities {
+  const declaration = BUILTIN_WORKSPACE_PROVIDER_CONFIG.get(name)
+  if (declaration === undefined) return {}
+  return {
+    ...(declaration.configSchema !== undefined ? { configSchema: declaration.configSchema } : {}),
+    ...(declaration.requireRuntimeProvisioning === true
+      ? { requireRuntimeProvisioning: true }
+      : {}),
+    ...(declaration.sandboxForbiddenEnv !== undefined
+      ? { sandboxForbiddenEnv: declaration.sandboxForbiddenEnv }
+      : {}),
+  }
+}
+
+export const VERCEL_SANDBOX_CAPABILITIES: WorkspaceProviderCapabilities = {
+  // Parse-time subset comes from the config table; the capability carries
+  // no configRefusal because the provider accepts [workspace.config]
+  // through its schema.
+  ...pickConfigDeclaration('vercel-sandbox'),
+  supportedForges: ['github'],
+  forgeDispatchMessage: 'vercel-sandbox requires the builtin github forge',
+  forgeValidationMessage:
+    'vercel-sandbox supports forge = "github" only; configure GitHub publication before validating',
+  requiredEnv: [
+    {
+      alternatives: [['GITHUB_TOKEN'], ['GH_TOKEN']],
+      dispatchMessage:
+        'vercel-sandbox publication requires GITHUB_TOKEN or GH_TOKEN in the dispatcher environment',
+      validationMessage:
+        'vercel-sandbox publication requires push-capable GITHUB_TOKEN or GH_TOKEN',
+    },
+    {
+      alternatives: [
+        ['VERCEL_OIDC_TOKEN'],
+        ['VERCEL_TOKEN', 'VERCEL_TEAM_ID', 'VERCEL_PROJECT_ID'],
+      ],
+      validationMessage:
+        'Vercel authentication requires VERCEL_OIDC_TOKEN or the durable VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID set',
+    },
+  ],
+  processEnvOnly: [
+    {
+      name: 'VERCEL_OIDC_TOKEN',
+      message:
+        'VERCEL_OIDC_TOKEN loaded only from the target .env is unavailable to the Vercel SDK; export it in the launcher environment or configure VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID',
+    },
+  ],
+  storeRequirements: {
+    constructionMessage:
+      'vercel-sandbox requires an HTTPS BuildStore and scoped AB_TOKEN authority',
+    storeRefMessage: 'vercel-sandbox requires AB_STORE to be an HTTPS URL reachable from Vercel',
+    storeTokenMessage: 'vercel-sandbox requires nonempty AB_TOKEN for the hosted Store',
+  },
+  validateOrigin: validateVercelGithubOrigin,
+  originReadFailureMessage: 'vercel-sandbox requires a readable Git origin',
+  guestEnvNames: (raw) => {
+    const config = raw as VercelSandboxConfig
+    return [
+      ...config.environmentVariables,
+      ...(config.gitUsernameEnv === undefined ? [] : [config.gitUsernameEnv]),
+      ...(config.gitPasswordEnv === undefined ? [] : [config.gitPasswordEnv]),
+    ]
+  },
+  describeEnvironment: (raw, env) => {
+    const config = raw as VercelSandboxConfig
+    return [
+      `Vercel auth: ${env.VERCEL_OIDC_TOKEN ? 'OIDC' : 'access token'}; team=${env.VERCEL_TEAM_ID ?? '(linked)'}; project=${env.VERCEL_PROJECT_ID ?? '(linked)'}`,
+      `Private clone variables: ${
+        config.gitUsernameEnv === undefined
+          ? '(public repository)'
+          : `${config.gitUsernameEnv}, ${config.gitPasswordEnv}`
+      }`,
+      `Guest environment variable names: ${config.environmentVariables.join(', ') || '(none)'}`,
+      `Runtime provisioning names: ${
+        Object.keys(config.runtimeProvisioning ?? {})
+          .sort()
+          .join(', ') || '(none)'
+      }`,
+    ]
+  },
+  validateReadiness: (ctx: WorkspaceReadinessContext) => validateRemoteReadiness(ctx),
+}

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

@@ -1,7 +1,4 @@
 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 {
@@ -9,12 +6,12 @@ import {
   type VercelSandboxConfig,
   vercelSandboxConfigSchema,
 } from '../../config/schema'
-import { distributionRoot } from '../../distribution'
-import { defaultDistributionArchive, readDistributionIdentity } from './distribution-archive'
+import { distributionStampFor, resolveDistributionArchive } from './distribution-archive'
 import type {
   WorkspaceHandle,
   WorkspaceProvider,
   WorkspaceProvisionResult,
+  WorkspacePublication,
   WorkspaceReapOutcome,
 } from '../types'
 import {
@@ -42,15 +39,23 @@ import {
 import { BUILD_RUNNER_OPTIONS_ENV } from './local-build-execution'
 import type { Exec } from './git-worktree'
 import { spawnExec } from './git-worktree'
+import { validateVercelGithubOrigin } from './github-origin'
+import { currentRuntimeReferences, type RuntimeReferencesSource } from './provider-capabilities'
+
+export { validateVercelGithubOrigin }
 
 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. */
+/** Records the installed distribution's identity stamp — everything the
+ * hosted store's skew check compares (package version and remote-store
+ * protocol version) plus the sha256 digest of the exact packed archive the
+ * dispatcher installs (see `readDistributionIdentityStamp`). A reused sandbox
+ * whose marker disagrees with the stamp 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'
@@ -447,35 +452,6 @@ export async function purgeEnvironmentSnapshots(
   }
 }
 
-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 {
@@ -759,23 +735,6 @@ async function preflightBun(sandbox: VercelSandboxHandle, image: string): Promis
   }
 }
 
-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>
@@ -930,7 +889,7 @@ export async function validateVercelSandbox(
     }
     await provisionBun(sandbox, config.image, options.signal)
     const provisioning = await runSystemProvisioning(sandbox, config.provisioning, options.signal)
-    const archive = await (options.packageArchive ?? defaultDistributionArchive)()
+    const archive = await effectiveArchive(options.packageArchive)
     checkCancellation()
     await sandbox.writeFiles([{ path: '/tmp/autobuild.tgz', content: archive }], {
       ...(options.signal === undefined ? {} : { signal: options.signal }),
@@ -1052,24 +1011,16 @@ export async function validateVercelSandbox(
   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
-}
+export type { RuntimeReferencesSource } from './provider-capabilities'
 
 /** 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. */
+ * identity marker. Shared by fresh provisioning, reuse-path refreshes, and
+ * the restart path; the readback comparison guards a silently failed write or
+ * extraction. */
 async function installDistribution(
   sandbox: VercelSandboxHandle,
   archive: Uint8Array,
-  version: string,
+  identity: string,
   signal?: AbortSignal,
 ): Promise<void> {
   await sandbox.writeFiles([{ path: '/tmp/autobuild.tgz', content: archive }], {
@@ -1091,12 +1042,12 @@ async function installDistribution(
     cwd: VERCEL_AUTOBUILD_PATH,
     ...(signal === undefined ? {} : { signal }),
   })
-  await writeDistributionVersionMarker(sandbox, version, signal)
+  await writeDistributionVersionMarker(sandbox, identity, signal)
 }
 
 async function writeDistributionVersionMarker(
   sandbox: VercelSandboxHandle,
-  version: string,
+  identity: string,
   signal?: AbortSignal,
 ): Promise<void> {
   await commandOrThrow(sandbox, {
@@ -1105,7 +1056,7 @@ async function writeDistributionVersionMarker(
       '-c',
       'printf %s "$1" > "$2"',
       'distribution-version',
-      version,
+      identity,
       VERCEL_DISTRIBUTION_VERSION_MARKER,
     ],
     ...(signal === undefined ? {} : { signal }),
@@ -1115,17 +1066,17 @@ async function writeDistributionVersionMarker(
     args: [VERCEL_DISTRIBUTION_VERSION_MARKER],
     ...(signal === undefined ? {} : { signal }),
   })
-  if (readback.trim() !== version) {
+  if (readback.trim() !== identity) {
     throw new Error(
-      `distribution version marker readback mismatch in ${VERCEL_DISTRIBUTION_VERSION_MARKER}: ` +
-        `wrote ${JSON.stringify(version)} but read ${JSON.stringify(readback.trim())}`,
+      `distribution identity marker readback mismatch in ${VERCEL_DISTRIBUTION_VERSION_MARKER}: ` +
+        `wrote ${JSON.stringify(identity)} 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. */
+/** The installed distribution's identity stamp, or `undefined` when the marker
+ * is unreadable — which includes every guest provisioned before the marker
+ * existed and is treated as a mismatch by the reuse and restart paths. */
 async function readDistributionVersionMarker(
   sandbox: VercelSandboxHandle,
   signal?: AbortSignal,
@@ -1143,6 +1094,17 @@ async function readDistributionVersionMarker(
   }
 }
 
+/** The archive bytes a provider installs: the injected test archive when
+ * present, else the per-process memoized running distribution archive
+ * (`resolveDistributionArchive`), so a deployment without an injected archive
+ * packs or fetches once per process rather than once per install site. */
+async function effectiveArchive(
+  packageArchive: (() => Promise<Uint8Array>) | undefined,
+): Promise<Uint8Array> {
+  if (packageArchive) return packageArchive()
+  return (await resolveDistributionArchive()).archive
+}
+
 export interface VercelSandboxProviderOptions {
   config: VercelSandboxConfig
   env: Record<string, string | undefined>
@@ -1163,11 +1125,14 @@ export interface VercelSandboxProviderOptions {
    * 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 distribution identity stamp the current archive source
+   * delivers (package version plus remote-store protocol version plus the
+   * sha256 digest of the archive bytes, see `readDistributionIdentityStamp`).
+   * Default computes the stamp over the effective archive source (origin mode
+   * keys the guest archive to the running version; source mode packs the same
+   * tree `readDistributionIdentity` reads), so the stamp and the installed
+   * bytes agree by construction. */
+  distributionIdentity?: () => 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
@@ -1193,6 +1158,7 @@ export class VercelSandboxProvider implements WorkspaceProvider {
   readonly harvestExecution: HarvestExecution
   readonly orchestratorSandbox: OperatorSandboxExecution
   readonly publication
+  readonly sandboxPublication: WorkspacePublication
   readonly recovery
   private readonly facade: VercelSandboxFacade
   private readonly exec: Exec
@@ -1203,6 +1169,24 @@ export class VercelSandboxProvider implements WorkspaceProvider {
   private readonly sessions = new Map<string, VercelSandboxHandle>()
   private readonly observeWaitMs: number
 
+  /** The archive bytes this provider installs: the injected `packageArchive`
+   * seam when set, else the per-process memoized running distribution
+   * archive. Every install site routes through here, so the marker digest
+   * always describes the bytes actually installed. */
+  private archiveBytes(): Promise<Uint8Array> {
+    return effectiveArchive(this.options.packageArchive)
+  }
+
+  /** The distribution identity stamp to write and compare: the injected
+   * `distributionIdentity` seam when set (which pins the stamp independent of
+   * the archive), else the default stamp computed over `archiveBytes()` — so
+   * a provider that injects only `packageArchive` stamps the bytes it
+   * actually installs and the seam divergence class is unrepresentable. */
+  private async identityStamp(): Promise<string> {
+    if (this.options.distributionIdentity) return this.options.distributionIdentity()
+    return distributionStampFor(await this.archiveBytes())
+  }
+
   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')
@@ -1243,6 +1227,14 @@ export class VercelSandboxProvider implements WorkspaceProvider {
       isPublished: (input: { sha: string; branch: string }) => this.isPublished(input),
       publish: (input: { ref: string; sha: string; branch: string }) => this.publish(input),
     }
+    // The operator-sandbox publication path reuses the SAME capability: its
+    // publish pushes an exact sha from any sandbox ref, including an operator
+    // environment, and its isPublished ignores the optional `ref` field.
+    // Constructor-body assignment, never a field initializer — the class
+    // assigns `publication` in the constructor too, and under the repo's
+    // `useDefineForClassFields` semantics a field initializer would run
+    // before that assignment and capture `undefined`.
+    this.sandboxPublication = this.publication
   }
 
   async provision(opts: {
@@ -1255,12 +1247,10 @@ export class VercelSandboxProvider implements WorkspaceProvider {
     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
-    )()
+    // Resolved once, before the create/reuse branch: the identity stamp the
+    // current archive source would deliver, against which both a fresh
+    // install's marker and a reused sandbox's marker are compared.
+    const distributionIdentity = await this.identityStamp()
     let sandbox = await this.facade.get(name, this.operationSignal())
     const existing = await this.remoteBranchHead(opts.branch, `remote branch ${opts.branch}`)
     const base =
@@ -1279,7 +1269,7 @@ export class VercelSandboxProvider implements WorkspaceProvider {
       })
       if (marker.exitCode === 0) {
         const installed = await readDistributionVersionMarker(sandbox, this.operationSignal())
-        if (installed === distributionVersion) {
+        if (installed === distributionIdentity) {
           await sandbox.stop({ signal: this.operationSignal() })
         } else {
           // A completed sandbox whose installed distribution disagrees with
@@ -1287,8 +1277,13 @@ export class VercelSandboxProvider implements WorkspaceProvider {
           // 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())
+            const archive = await this.archiveBytes()
+            await installDistribution(
+              sandbox,
+              archive,
+              distributionIdentity,
+              this.operationSignal(),
+            )
           } catch (error) {
             try {
               this.sessions.set(name, sandbox)
@@ -1374,8 +1369,8 @@ export class VercelSandboxProvider implements WorkspaceProvider {
         }
         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())
+        const archive = await this.archiveBytes()
+        await installDistribution(sandbox, archive, distributionIdentity, 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.
@@ -1541,6 +1536,32 @@ export class VercelSandboxProvider implements WorkspaceProvider {
       await sandbox.stop({ signal: this.operationSignal() })
       this.uncertain.delete(ref)
     }
+    // Restart (the lease sweep's re-attach) launches guest code in an existing
+    // sandbox, so it must compare the distribution identity exactly as the
+    // reuse paths do: a guest installed by an older dispatcher — including one
+    // stranded by a protocol-only bump or a missing/unreadable marker — is
+    // refreshed before the runner starts, or the hosted store would 409 its
+    // heartbeat and the build would strand. Refresh failure deletes the
+    // sandbox so the next pass rematerializes it cleanly.
+    const distributionIdentity = await this.identityStamp()
+    const installed = await readDistributionVersionMarker(sandbox, this.operationSignal())
+    if (installed !== distributionIdentity) {
+      try {
+        const archive = await this.archiveBytes()
+        await installDistribution(sandbox, archive, distributionIdentity, this.operationSignal())
+      } catch (error) {
+        try {
+          this.sessions.set(ref, sandbox)
+          await this.reap(ref)
+        } catch (deleteError) {
+          throw new AggregateError(
+            [error, deleteError],
+            `sandbox ${ref} distribution refresh failed and its incomplete environment could not be confirmed deleted`,
+          )
+        }
+        throw error
+      }
+    }
     await preflightBun(sandbox, this.options.config.image)
     await bootstrapRuntimes(
       sandbox,
@@ -1679,12 +1700,10 @@ export class VercelSandboxProvider implements WorkspaceProvider {
     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
-    )()
+    // Resolved once, before the create/reuse branch: the identity stamp the
+    // current archive source would deliver, against which both a fresh
+    // install's marker and a reused environment's marker are compared.
+    const distributionIdentity = await this.identityStamp()
     let sandbox = await this.facade.get(name, this.operationSignal())
     if (sandbox !== null) {
       const marker = await sandbox.runCommand({
@@ -1703,10 +1722,15 @@ export class VercelSandboxProvider implements WorkspaceProvider {
         // 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) {
+        if (installed !== distributionIdentity) {
           try {
-            const archive = await (this.options.packageArchive ?? defaultDistributionArchive)()
-            await installDistribution(sandbox, archive, distributionVersion, this.operationSignal())
+            const archive = await this.archiveBytes()
+            await installDistribution(
+              sandbox,
+              archive,
+              distributionIdentity,
+              this.operationSignal(),
+            )
           } catch (error) {
             try {
               this.sessions.set(name, sandbox)
@@ -1785,8 +1809,8 @@ export class VercelSandboxProvider implements WorkspaceProvider {
         }
         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())
+        const archive = await this.archiveBytes()
+        await installDistribution(sandbox, archive, distributionIdentity, this.operationSignal())
         // Repository dependencies precede runtime preflight; the fixed
         // bootstrap is the same one build provisioning runs.
         await commandOrThrow(sandbox, {
@@ -2006,9 +2030,7 @@ export class VercelSandboxProvider implements WorkspaceProvider {
   }): Promise<SandboxEnvironmentIdentity> {
     const origin = cleanGithubOrigin(await this.origin())
     const name = sandboxEnvironmentName(origin.url, input.operator)
-    const distributionVersion = await (
-      this.options.distributionVersion ?? readDistributionIdentity
-    )()
+    const distributionIdentity = await this.identityStamp()
     let sandbox = await this.facade.get(name, this.operationSignal())
     if (sandbox !== null) {
       const marker = await sandbox.runCommand({
@@ -2022,14 +2044,19 @@ export class VercelSandboxProvider implements WorkspaceProvider {
         sandbox = null
       } else {
         const installed = await readDistributionVersionMarker(sandbox, this.operationSignal())
-        if (installed !== distributionVersion) {
+        if (installed !== distributionIdentity) {
           // 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())
+            const archive = await this.archiveBytes()
+            await installDistribution(
+              sandbox,
+              archive,
+              distributionIdentity,
+              this.operationSignal(),
+            )
           } catch (error) {
             try {
               this.sessions.set(name, sandbox)
@@ -2114,8 +2141,8 @@ export class VercelSandboxProvider implements WorkspaceProvider {
       }
       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())
+      const archive = await this.archiveBytes()
+      await installDistribution(sandbox, archive, distributionIdentity, this.operationSignal())
       // Repository dependencies precede the setup command; the fixed
       // bootstrap is the same one build provisioning runs.
       await commandOrThrow(sandbox, {
@@ -2182,6 +2209,7 @@ export class VercelSandboxProvider implements WorkspaceProvider {
       environmentId: name,
       ...(sessionId !== undefined ? { sessionId } : {}),
       workspacePath: VERCEL_WORKSPACE_PATH,
+      baseSha: head,
     }
   }
 

package/packages/core/src/processes/build-child.ts

@@ -10,6 +10,7 @@ import { openProductionStore } from '../cli/store-opening'
 import { BuildRunner, LeaseHeldError, SetupFailureError } from './build-runner'
 import {
   BUILD_EFFECTIVE_CONFIG_ARTIFACT,
+  buildOwnedSectionsDiffer,
   diagnosticArtifact,
   parseEffectiveBuildConfig,
   selectOpenWorkspace,
@@ -22,11 +23,17 @@ function message(error: unknown): string {
 }
 
 /** Child-side composition. The launch envelope supplies identity only; all
- * execution location/configuration is discovered through the scoped Store. */
+ * execution location/configuration is discovered through the scoped Store.
+ * `opts.guest` marks a structurally guest process (environment-supervised
+ * launch): plugin loading then tolerates a configured package specifier the
+ * guest cannot resolve — guests never construct workspace providers, so a
+ * provider plugin configured in autobuild.toml is skipped with a notice
+ * instead of failing the build (AUT-517). */
 export async function runBuildChild(
   input: BuildExecutionStart,
   env: Record<string, string | undefined> = process.env,
   openStore: (ref: string, token?: string) => BuildStore = openProductionStore,
+  opts: { guest?: boolean } = {},
 ): Promise<void> {
   const fullStore = openStore(input.storeRef, env.AB_TOKEN)
   const store = fullStore.scopeBuild(input.slug)
@@ -50,6 +57,7 @@ export async function runBuildChild(
     let currentConfig = parseEffectiveBuildConfig(configArtifact)
     const plugins = await loadPlugins(currentConfig.plugins, workspace.path, {
       packageRoot: record.repo,
+      ...(opts.guest === true ? { guest: true } : {}),
     })
     const { runtimes: builtins } = createProductionRuntimes()
     const runtimes = await materializePluginRuntimes(builtins, plugins, {
@@ -66,7 +74,14 @@ export async function runBuildChild(
       const latest = await store.getArtifact(input.slug, BUILD_EFFECTIVE_CONFIG_ARTIFACT)
       if (latest === null) return currentConfig
       try {
-        currentConfig = parseEffectiveBuildConfig(latest)
+        const parsed = parseEffectiveBuildConfig(latest)
+        // Defensive guard (SPEC §16.1): after pinning, a boundary deposit may
+        // move deployment-owned sections only. If build-owned sections change
+        // without the build's own branch advancing, the artifact was written
+        // by something other than a launch — keep the last valid boundary.
+        if (!buildOwnedSectionsDiffer(currentConfig, parsed)) {
+          currentConfig = parsed
+        }
       } catch {
         // The dispatcher publishes only validated snapshots. If storage is
         // externally corrupted, preserve the child's last valid boundary.