@defrex/autobuild 0.8.0 → 0.9.0

package/packages/core/src/ports/workspace/git-worktree.ts

@@ -19,7 +19,12 @@ import {
   type SandboxEnvironmentIdentity,
   type SandboxWaitResult,
 } from './operator-sandbox'
-import type { WorkspaceHandle, WorkspaceProvider, WorkspaceProvisionResult } from '../types'
+import type {
+  WorkspaceHandle,
+  WorkspaceProvider,
+  WorkspaceProvisionResult,
+  WorkspacePublication,
+} from '../types'
 
 export interface ExecResult {
   stdout: string
@@ -107,6 +112,7 @@ function parseWorktreeList(porcelain: string): WorktreeEntry[] {
 export class GitWorktreeProvider implements WorkspaceProvider {
   readonly name = 'git-worktree'
   readonly orchestratorSandbox: OperatorSandboxExecution
+  readonly sandboxPublication: WorkspacePublication
   private readonly root: string
   private readonly sandboxRoot: string
   private readonly setupCommand: string | undefined
@@ -124,6 +130,10 @@ export class GitWorktreeProvider implements WorkspaceProvider {
   constructor(opts: {
     root: string
     exec?: Exec
+    /** Test-only override of the exit-stamp drain grace
+     * (`DEFAULT_SANDBOX_EXIT_DRAIN_GRACE_MS`); production behavior is
+     * unchanged. */
+    exitDrainGraceMs?: number
     /** Operator-sandbox worktree root; defaults to a sibling of the build
      * worktree root inside the local state tree. */
     sandboxRoot?: string
@@ -141,6 +151,8 @@ export class GitWorktreeProvider implements WorkspaceProvider {
     this.setupCommand = opts.setupCommand
     this.sandboxEnvironmentVariables = opts.sandboxEnvironmentVariables ?? []
     this.sandboxEnvSource = opts.envSource ?? {}
+    this.exitDrainGraceMs =
+      opts.exitDrainGraceMs ?? GitWorktreeProvider.DEFAULT_SANDBOX_EXIT_DRAIN_GRACE_MS
     this.exec = opts.exec ?? spawnExec
     this.orchestratorSandbox = {
       describe: (input) => Promise.resolve(this.sandboxIdentity(input.repo, input.operator)),
@@ -153,6 +165,10 @@ export class GitWorktreeProvider implements WorkspaceProvider {
       stop: () => Promise.resolve({ outcome: 'unsupported' as const }),
       release: (input) => this.sandboxRelease(input),
     }
+    this.sandboxPublication = {
+      isPublished: (input) => this.sandboxIsPublished(input),
+      publish: (input) => this.publishSandbox(input),
+    }
   }
 
   private async realRoot(): Promise<string> {
@@ -477,10 +493,25 @@ export class GitWorktreeProvider implements WorkspaceProvider {
 
   /** Main-repo directory owning the worktree at `path`, or null if the path
    * is gone or not a worktree — the release-is-a-no-op cases. Needed when a
-   * restarted process releases a worktree it did not provision (§7.4). */
+   * restarted process releases a worktree it did not provision (§7.4).
+   * A successful `rev-parse --git-common-dir` with empty stdout is a
+   * degenerate input — feeding it to `resolve` would target the worktree
+   * directory itself and misdirect the subsequent `worktree remove` — so it
+   * fails loudly with a `GitError` (same posture as `shaFrom`'s empty-SHA
+   * guard) rather than masquerading as a release-is-a-no-op case. The error
+   * type diverges deliberately from `excludeProvisioningMarker`'s
+   * `SandboxOperationError`: this is provider-level discovery shared by
+   * `release` and `sandboxRelease`, not a sandbox operation. */
   private async discoverRepo(path: string): Promise<string | null> {
     const result = await this.git(path, ['rev-parse', '--git-common-dir'])
     if (result.exitCode !== 0) return null
+    if (result.stdout.trim() === '') {
+      throw new GitError(['-C', path, 'rev-parse', '--git-common-dir'], {
+        ...result,
+        exitCode: 1,
+        stderr: 'git returned no common directory',
+      })
+    }
     const commonDir = resolve(path, result.stdout.trim())
     // The common dir is the main repo's `.git`; worktree commands need the
     // repo directory itself (a bare common dir already is one).
@@ -536,7 +567,15 @@ export class GitWorktreeProvider implements WorkspaceProvider {
     baseBranch: string
   }): Promise<SandboxEnvironmentIdentity> {
     const identity = this.sandboxIdentity(input.repo, input.operator)
-    if (await this.isRegisteredWorktree(identity.environmentId, input.repo)) return identity
+    if (await this.isRegisteredWorktree(identity.environmentId, input.repo)) {
+      // Pre-existing sandboxes provisioned before the info/exclude write
+      // landed (AUT-580) keep an unexcluded marker; write the exclusion on
+      // every ensure so the publish service's untracked-inclusive dirty
+      // check never counts the marker as dirt and the correct baseSha /
+      // reset-required diagnostic surfaces.
+      await this.excludeProvisioningMarker(identity.workspacePath)
+      return identity
+    }
     await mkdir(this.sandboxRoot, { recursive: true })
     const baseHead = await this.resolveCommit(input.repo, `refs/heads/${input.baseBranch}`)
     await this.gitOrThrow(input.repo, [
@@ -547,6 +586,7 @@ export class GitWorktreeProvider implements WorkspaceProvider {
       baseHead,
     ])
     try {
+      await this.excludeProvisioningMarker(identity.workspacePath)
       const marker = join(identity.workspacePath, '.autobuild-sandbox-provisioned')
       const provisioned = await stat(marker).then(
         () => true,
@@ -572,7 +612,45 @@ export class GitWorktreeProvider implements WorkspaceProvider {
       await this.git(input.repo, ['worktree', 'prune'])
       throw error
     }
-    return identity
+    return { ...identity, baseSha: baseHead }
+  }
+
+  /** Idempotently exclude the provisioning marker in the worktree's
+   * info/exclude so it never counts as dirt for the publish service's
+   * untracked-inclusive dirty check (f_c748dc6a). Runs on both ensure
+   * paths — fresh provisioning and the registered-worktree early return —
+   * so sandboxes provisioned before the write landed are healed the next
+   * time they are ensured. Errors propagate: a failed exclusion write
+   * aborts provisioning, mirroring fail-closed behavior. A successful
+   * `rev-parse --git-path` with empty stdout is a degenerate input — feeding
+   * it to `resolve` would target the workspace directory itself — so it fails
+   * loudly with the same `SandboxOperationError` — and the identical
+   * failure string — the fake workspace uses for the same case, keeping
+   * the two workspace-port implementations aligned. */
+  private async excludeProvisioningMarker(workspacePath: string): Promise<void> {
+    const markerName = '.autobuild-sandbox-provisioned'
+    const exclude = await this.gitOrThrow(workspacePath, [
+      'rev-parse',
+      '--git-path',
+      'info/exclude',
+    ])
+    if (exclude.stdout.trim() === '') {
+      throw new SandboxOperationError(
+        'provision',
+        `operator sandbox could not resolve info/exclude: ${exclude.stderr.trim() || `exit ${exclude.exitCode}`}`,
+      )
+    }
+    const excludePath = resolve(workspacePath, exclude.stdout.trim())
+    await mkdir(excludePath.slice(0, excludePath.lastIndexOf(sep)), { recursive: true })
+    const existing = await fsReadFile(excludePath, 'utf8').then(
+      (content) => content,
+      () => '',
+    )
+    const lines = existing.split('\n')
+    if (!lines.includes(markerName)) {
+      const prefix = existing === '' || existing.endsWith('\n') ? existing : `${existing}\n`
+      await fsWriteFile(excludePath, `${prefix}${markerName}\n`)
+    }
   }
 
   /** One `sh -c` command inside the sandbox worktree with the credential-free
@@ -650,9 +728,25 @@ export class GitWorktreeProvider implements WorkspaceProvider {
    * this cap covers the fire-and-forget case — commands that finish but are
    * never waited on — so the map (and its retained stdout/stderr strings)
    * stays bounded at ~cap entries' worth of output regardless of how many
-   * commands the process ever runs. Running entries are never evicted. */
+   * commands the process ever runs. Running entries are never evicted, and
+   * cap-evicted commands fail `wait` typed `not-found`: the legitimate
+   * not-found population under the cap is entries trimmed as the oldest
+   * finished, entries already consumed by a terminal wait, and ids from a
+   * restarted host. */
   private static readonly MAX_RETAINED_SANDBOX_COMMANDS = 50
 
+  /** Bound on how long the exit stamp waits for the stdout/stderr pipe
+   * readers to drain after the process exits. A normal child closes its
+   * pipes on exit and drains immediately; a grandchild that inherited the
+   * write end (e.g. `sleep 30 &`) keeps the pipe open long past the
+   * child's exit, so the grace bounds the stamp instead of stalling the
+   * delivered `exited` result until the grandchild dies. Because the race
+   * outcome varies (reader drain vs. grace), stamp landing times are also
+   * variable — which is why `evictFinishedBeyondCap` stops at
+   * exited-but-unstamped entries instead of treating them as running. */
+  private static readonly DEFAULT_SANDBOX_EXIT_DRAIN_GRACE_MS = 250
+  private readonly exitDrainGraceMs: number
+
   /** Detached children tracked in-process only; a restarted host reports a
    * recorded command as gone (`wait` fails typed `not-found`). Eviction uses
    * the same semantics: the first `wait` that observes `exited` consumes the
@@ -680,38 +774,75 @@ export class GitWorktreeProvider implements WorkspaceProvider {
 
   /** While the map exceeds the retention cap, delete the oldest finished
    * entries in insertion order (`Map` iterates in insertion order). Running
-   * entries are never evicted — the live procs themselves are the resource. */
+   * entries are never evicted — the live procs themselves are the resource.
+   * A pass also stops at the first tracked command that has exited but whose
+   * drain-gated exit stamp has not yet landed: such an entry is finished,
+   * not running, so the stamped entries older than it are unambiguously
+   * safe to evict (and are deleted by the walk reaching it), but nothing
+   * newer may be selected ahead of it — deleting a newer finished entry
+   * while an older one's stamp is still pending would make the victim
+   * choice depend on when stamps happen to land. When the pending entry is
+   * itself the oldest evictable entry, the pass deletes nothing and defers
+   * to its stamp. The stop always resolves — every exited entry is stamped
+   * within the drain grace, and every stamp runs this pass again — so the
+   * map settles to the cap with victims chosen as the oldest finished
+   * entries in insertion order, independent of stamp timing; while a stamp
+   * is pending the map may transiently hold the cap plus the entries that
+   * finished after that pending entry. */
   private evictFinishedBeyondCap(): void {
     if (this.sandboxChildren.size <= GitWorktreeProvider.MAX_RETAINED_SANDBOX_COMMANDS) return
     for (const [id, tracked] of this.sandboxChildren) {
-      if (this.sandboxChildren.size <= GitWorktreeProvider.MAX_RETAINED_SANDBOX_COMMANDS) break
+      if (this.sandboxChildren.size <= GitWorktreeProvider.MAX_RETAINED_SANDBOX_COMMANDS) return
+      // An exited-but-unstamped entry is finished, not running: stop here so
+      // no entry newer than it is evicted ahead of it.
+      if (tracked.exitCode === null && this.hasExitedProcess(tracked)) return
       if (tracked.exitCode !== null) this.sandboxChildren.delete(id)
     }
   }
 
+  /** Synchronous exit probe for a tracked child: `exitCode` covers a normal
+   * exit, `signalCode` a signal kill (where `exitCode` stays null). Both are
+   * synchronous on `Bun.Subprocess`, so an eviction pass reads real state at
+   * pass time rather than the drain-delayed stamp. */
+  private hasExitedProcess(tracked: { proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'> }): boolean {
+    return tracked.proc.exitCode !== null || tracked.proc.signalCode !== null
+  }
+
   private trackChildStreams(
     commandId: string,
     child: { proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'> },
   ): void {
-    void (async () => {
-      const reader = child.proc.stdout.getReader()
-      const decoder = new TextDecoder()
-      for (;;) {
-        const { done, value } = await reader.read()
-        if (done) break
-        this.appendChildStream(commandId, 'stdout', decoder.decode(value, { stream: true }))
-      }
-    })()
-    void (async () => {
-      const reader = child.proc.stderr.getReader()
-      const decoder = new TextDecoder()
-      for (;;) {
-        const { done, value } = await reader.read()
-        if (done) break
-        this.appendChildStream(commandId, 'stderr', decoder.decode(value, { stream: true }))
-      }
-    })()
-    void child.proc.exited.then((code) => {
+    const drained = Promise.all([
+      (async () => {
+        const reader = child.proc.stdout.getReader()
+        const decoder = new TextDecoder()
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          this.appendChildStream(commandId, 'stdout', decoder.decode(value, { stream: true }))
+        }
+      })(),
+      (async () => {
+        const reader = child.proc.stderr.getReader()
+        const decoder = new TextDecoder()
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          this.appendChildStream(commandId, 'stderr', decoder.decode(value, { stream: true }))
+        }
+      })(),
+    ]).catch(() => {})
+    void child.proc.exited.then(async (code) => {
+      // Stamp `exited` only once the pipe readers have drained what the
+      // child wrote, so a terminal `wait` never snapshots truncated output —
+      // under load the exit can otherwise be observed before the readers
+      // finish appending (seen as a flaky empty `stdout` in the retention
+      // test's full-suite run). The grace bounds the stamp when a grandchild
+      // keeps the write end open past the child's own exit.
+      await Promise.race([
+        drained,
+        new Promise((resolve) => setTimeout(resolve, this.exitDrainGraceMs)),
+      ])
       const tracked = this.sandboxChildren.get(commandId)
       if (tracked === undefined) return
       tracked.exitCode = code ?? -1
@@ -845,4 +976,93 @@ export class GitWorktreeProvider implements WorkspaceProvider {
     // A local worktree has no snapshot concept; release is always complete.
     return { snapshots: { outcome: 'confirmed' } }
   }
+
+  // ── Operator-sandbox publication (PR-only) ──────────────────
+  //
+  // The push and its probe run host-side in the sandbox worktree with the
+  // host's own forge configuration — exactly the transport a local build's
+  // finalize push uses (GitHubForge.pushBranch runs `git push` in the
+  // worktree); the only difference is an exact sha rather than HEAD, because
+  // publish accepts an explicit commit. No credential is ever handed to the
+  // sandbox itself: the sandbox performs no push, the provider does.
+
+  /** Same shape validation as the vercel publication adapter: an exact
+   * commit SHA and a canonical publication branch. */
+  private static assertPublicationInput(input: { sha: string; branch: string }): void {
+    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')
+    }
+  }
+
+  /** Linked worktrees share the origin remote configuration with the main
+   * repository, so the probe runs from the worktree path itself. */
+  private async hasOriginRemote(cwd: string): Promise<boolean> {
+    const result = await this.git(cwd, ['remote'])
+    if (result.exitCode !== 0) return false
+    return result.stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .includes('origin')
+  }
+
+  private async sandboxIsPublished(input: {
+    ref?: string
+    sha: string
+    branch: string
+  }): Promise<boolean> {
+    GitWorktreeProvider.assertPublicationInput(input)
+    if (input.ref === undefined || input.ref === '') {
+      throw new Error('the git-worktree publication probe requires the workspace ref')
+    }
+    const ref = resolve(input.ref)
+    if (await this.hasOriginRemote(ref)) {
+      const result = await this.git(ref, ['ls-remote', 'origin', `refs/heads/${input.branch}`])
+      if (result.exitCode !== 0) {
+        throw new GitError(['-C', ref, 'ls-remote', 'origin', `refs/heads/${input.branch}`], result)
+      }
+      return result.stdout
+        .split('\n')
+        .some((line) => line.trim() === `${input.sha}\trefs/heads/${input.branch}`)
+    }
+    // No origin remote (local-git-forge deployments, where a local finalize
+    // performs no network push): compare the branch locally. Linked
+    // worktrees share all refs with the main repository, so no bookkeeping
+    // beyond the worktree path is needed.
+    const head = await this.resolveOptionalCommit(ref, `refs/heads/${input.branch}`)
+    return head === input.sha
+  }
+
+  private async publishSandbox(input: { ref: string; sha: string; branch: string }): Promise<void> {
+    GitWorktreeProvider.assertPublicationInput(input)
+    const ref = resolve(input.ref)
+    if (await this.hasOriginRemote(ref)) {
+      const args = [
+        '-C',
+        ref,
+        'push',
+        '--no-verify',
+        'origin',
+        `${input.sha}:refs/heads/${input.branch}`,
+      ]
+      const result = await this.exec(['git', ...args], {})
+      if (result.exitCode !== 0) throw new GitError(args, result)
+      return
+    }
+    // Local equivalent of the finalize push for deployments without an
+    // origin remote: a ref move guarded so it can never be a
+    // non-fast-forward. The service refuses the base branch before this
+    // seam is reached.
+    const existing = await this.resolveOptionalCommit(ref, `refs/heads/${input.branch}`)
+    if (existing !== null && existing !== input.sha) {
+      if (!(await this.isAncestor(ref, existing, input.sha))) {
+        throw new Error(
+          `refusing to move refs/heads/${input.branch}: its current tip ${existing} ` +
+            `is not an ancestor of ${input.sha}`,
+        )
+      }
+    }
+    const args = ['-C', ref, 'update-ref', `refs/heads/${input.branch}`, input.sha]
+    const result = await this.git(ref, ['update-ref', `refs/heads/${input.branch}`, input.sha])
+    if (result.exitCode !== 0) throw new GitError(args, result)
+  }
 }

package/packages/core/src/ports/workspace/github-origin.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure GitHub origin validation for the remote workspace provider. String
+ * logic only — no SDK, no git, no provider module — so capability declarations
+ * can reference it without pulling the provider implementation into import
+ * graphs that must stay light.
+ */
+import { basename } from 'node:path'
+
+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),
+  }
+}

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

@@ -49,6 +49,11 @@ export interface SandboxEnvironmentIdentity {
   sessionId?: string
   /** Checkout root inside the environment; tool file paths are rooted here. */
   workspacePath: string
+  /** The base branch head the fresh provision selected, present only on the
+   * fresh-provision path (absent on reuse/resume, which never re-resolves
+   * it). The publication preconditions compare against it: a publish must
+   * be a descendant of the base head at provision or reset time. */
+  baseSha?: string
 }
 
 export interface SandboxCommandRequest {
@@ -87,7 +92,8 @@ export class SandboxOperationError extends Error {
       | 'not-found'
       | 'environment'
       | 'reset'
-      | 'release',
+      | 'release'
+      | 'publish',
     message: string,
     options?: { cause?: unknown },
   ) {

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

@@ -0,0 +1,171 @@
+/**
+ * Declarative capabilities a workspace-provider registration can supply, plus
+ * the readiness contract those capabilities speak. Core honours these
+ * declarations at registry-aware seams without naming any provider, which is
+ * what lets a third-party remote provider receive the same treatment as the
+ * builtin `vercel-sandbox` registration (AUT-516).
+ *
+ * This module is a leaf: runtime imports are limited to `config/roles`
+ * helpers, everything else is types. `config/schema.ts` imports the message
+ * builders below, and `builtin-capabilities.ts` imports `config/schema.ts` —
+ * so nothing here may import either, or module evaluation would cycle.
+ */
+import type { z } from 'zod'
+import { displayName, tomlKey, type RuntimeReferenceGroup } from '../../config/roles'
+import type { Config } from '../../config/schema'
+import type { Exec } from './git-worktree'
+
+/** Host-derived effective routes; consumed only by remote providers. */
+export type RuntimeReferencesSource =
+  | readonly RuntimeReferenceGroup[]
+  | (() => readonly RuntimeReferenceGroup[])
+
+export function currentRuntimeReferences(
+  source: RuntimeReferencesSource | undefined,
+): readonly RuntimeReferenceGroup[] {
+  if (source === undefined) return []
+  return typeof source === 'function' ? source() : source
+}
+
+/** The `[workspace.config.runtimeProvisioning]` map of a parsed provider
+ * config, `{}` when the provider declares no such table. */
+export function runtimeProvisioningMap(parsedConfig: unknown): Record<string, unknown> {
+  if (parsedConfig === null || typeof parsedConfig !== 'object') return {}
+  const table = (parsedConfig as { runtimeProvisioning?: unknown }).runtimeProvisioning
+  return table !== null && typeof table === 'object' ? (table as Record<string, unknown>) : {}
+}
+
+/** Verbatim `configSchema` diagnostic for a referenced runtime with no
+ * provisioning entry. Shared by the config parse and the construction seam so
+ * the two cannot drift. */
+export function runtimeProvisioningMissingMessage(group: RuntimeReferenceGroup): string {
+  return (
+    `runtime ${displayName(group.runtime)} is selected by ${group.references.join(', ')} but has no sandbox provisioning; add ` +
+    `[workspace.config.runtimeProvisioning.${tomlKey(group.runtime)}] with nonblank install and preflight commands`
+  )
+}
+
+/** Verbatim credential-free operator-sandbox diagnostic (AUT-340). Shared by
+ * the config parse and the construction seam so the two cannot drift. */
+export function sandboxForbiddenEnvMessage(name: string): string {
+  return `environment variable ${JSON.stringify(name)} is a store, forge, ticket-provider, model, or Vercel credential and may never be forwarded into an operator sandbox`
+}
+
+// ── Readiness contract ───────────────────────────────────────────────────────
+
+export interface ReadinessCheck {
+  name: string
+  status: 'pass' | 'fail' | 'absent'
+  detail: string
+}
+
+export interface InitValidationReport {
+  provider: string
+  context: 'local worktree' | 'Vercel Sandbox'
+  workspace?: string
+  revision?: string
+  checks: ReadinessCheck[]
+  exitCode: number
+  /** Vercel only: automatic snapshots deleted while releasing the disposable
+   * environment; zero proves no snapshot storage was left behind. */
+  snapshotsDeleted?: number
+}
+
+export interface GuestProbeReport {
+  checks: ReadinessCheck[]
+}
+
+// ── Capability declarations ──────────────────────────────────────────────────
+
+/** One required-environment group: alternatives are tried in order, and one
+ * is satisfied when EVERY named variable in it is set nonempty. The group must
+ * carry at least one message — a group with neither `dispatchMessage` nor
+ * `validationMessage` is rejected at manifest parse (AUT-554), because both
+ * enforcement sites skip it and the declaration would never be enforced. */
+export interface WorkspaceProviderEnvRequirement {
+  alternatives: readonly (readonly string[])[]
+  /** Verbatim dispatch-preflight text (`cli/dispatch.ts`). */
+  dispatchMessage?: string
+  /** Verbatim init-preflight text (`validateInitReadiness`'s hostPreflight). */
+  validationMessage?: string
+}
+
+/**
+ * Everything a workspace-provider registration can declare about its own
+ * behavior, so core can enforce it without naming the provider. Field texts
+ * are verbatim today's messages; a capability absent means "no check".
+ */
+export interface WorkspaceProviderCapabilities {
+  /** Strict schema applied to `[workspace.config]`. Mutually exclusive with
+   * `configRefusal`. */
+  configSchema?: z.ZodType
+  /** Construction-site refusal (`createWorkspaceProvider`) for a provider
+   * that rejects `[workspace.config]` outright. Distinct from the parse-site
+   * refusal text, which lives on the builtin config table in
+   * `config/schema.ts` — the two strings differ by design. */
+  configRefusal?: string
+  /** Referenced runtimes must have `[workspace.config.runtimeProvisioning]`
+   * entries. */
+  requireRuntimeProvisioning?: boolean
+  /** Names added to the operator-sandbox forbidden-forwarding set beyond
+   * `SANDBOX_FORBIDDEN_ENV`. Enforced at the two registry-aware seams —
+   * `createWorkspaceProvider` construction and the registry-aware
+   * `validateInitReadiness` check — not at config parse: plugins are not
+   * loaded when config is parsed, and no site loads plugins earlier to widen
+   * parse-time coverage. The shared `SANDBOX_FORBIDDEN_ENV` names are
+   * rejected at parse time for every provider (AUT-536). */
+  sandboxForbiddenEnv?: readonly string[]
+  supportedForges?: readonly string[]
+  /** Verbatim texts; dispatch and init validation emit different sentences. */
+  forgeDispatchMessage?: string
+  forgeValidationMessage?: string
+  requiredEnv?: readonly WorkspaceProviderEnvRequirement[]
+  /** Variables that must exist in the launcher process environment, never
+   * only in a loaded `.env`. */
+  processEnvOnly?: readonly { name: string; message: string }[]
+  /** Store requirements for checkout-less providers, with each site's
+   * verbatim text. */
+  storeRequirements?: {
+    constructionMessage: string
+    storeRefMessage: string
+    storeTokenMessage: string
+  }
+  /** Validates the git origin URL before dispatch (throws the provider's own
+   * message) and returns the normalized origin coordinates. */
+  validateOrigin?: (raw: string) => { url: string; host: string; path: string; directory: string }
+  originReadFailureMessage?: string
+  /** Env names the provider forwards into the guest (readiness redaction). */
+  guestEnvNames?: (config: unknown) => readonly string[]
+  /** Readiness summary stdout lines printed after the report. The config
+   * argument is the `[workspace.config]` parsed with the declared
+   * `configSchema`, or the raw `[workspace.config]` table when no schema is
+   * declared — mirroring `guestEnvNames`. */
+  describeEnvironment?: (
+    config: unknown,
+    env: Record<string, string | undefined>,
+  ) => readonly string[]
+  /** Remote readiness validation for `ab init --validate`. */
+  validateReadiness?: (ctx: WorkspaceReadinessContext) => Promise<InitValidationReport>
+}
+
+/** Everything a readiness implementation reads. `facade` and `packageArchive`
+ * are the host's test seams, passed opaquely — the vercel implementation
+ * narrows them. */
+export interface WorkspaceReadinessContext {
+  config: Config
+  /** The `[workspace.config]` parsed with the declared `configSchema`. */
+  providerConfig: unknown
+  env: Record<string, string | undefined>
+  storeRef: string
+  storeToken: string
+  repo: string
+  baseBranch: string
+  configBytes: string
+  exec: Exec
+  redact: (value: unknown) => string
+  runtimeReferences: readonly RuntimeReferenceGroup[]
+  stdout: (line: string) => void
+  signal?: AbortSignal
+  facade?: unknown
+  packageArchive?: () => Promise<Uint8Array>
+}