@defrex/autobuild 0.8.0 → 0.9.0

package/packages/core/src/ports/forge/github-transport.ts

@@ -213,8 +213,14 @@ export function createGitHubFetchTransport(opts: {
       // a private repository is otherwise indistinguishable from a bad path,
       // and the operator's fix (export a token, or `gh auth login`) is the
       // point of the message.
+      // `in` rather than relying on the `token === undefined` discriminant:
+      // the plugin-sdk typecheck fixture compiles this chain without
+      // strictNullChecks, where `undefined` is assignable to `string` and
+      // the union stops discriminating (AUT-517).
       const anonymous =
-        credential.token === undefined ? ` (request was unauthenticated: ${credential.reason})` : ''
+        credential.token === undefined && 'reason' in credential
+          ? ` (request was unauthenticated: ${credential.reason})`
+          : ''
       throw new GitHubApiError(
         response.status,
         `${githubErrorMessage(response.status, json, text)}${anonymous}`,
@@ -335,9 +341,14 @@ export async function resolveGitHubToken(
   if (fromEnv !== undefined) return { token: fromEnv }
   const probe = await githubTokenFromGhCli(exec)
   if (probe.token !== undefined) return probe
+  // `in` rather than relying on the `token !== undefined` discriminant: the
+  // plugin-sdk typecheck fixture compiles this chain without
+  // strictNullChecks, where `undefined` is assignable to `string` and the
+  // union stops discriminating (AUT-517). A miss always carries its reason.
+  const missReason = 'reason' in probe ? probe.reason : 'no credential source succeeded'
   return {
     token: undefined,
-    reason: `GITHUB_TOKEN and GH_TOKEN are unset and ${probe.reason}`,
+    reason: `GITHUB_TOKEN and GH_TOKEN are unset and ${missReason}`,
   }
 }
 

package/packages/core/src/ports/forge/github.ts

@@ -470,6 +470,16 @@ function restMergeState(raw: string): MergeStateStatus {
 
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
 
+/** Bounded UNKNOWN re-query schedule: 7 re-queries, ~30 s of nondecreasing
+ * backoff capped at 6 s steps. Sized after AUT-392 — the prior
+ * two-re-query/2 s budget (`[500, 1500]`) was exhausted by a live occurrence
+ * (build `give-repo-scoped`, PR #352) while GitHub was still computing
+ * mergeability after required checks completed. Single-occurrence evidence,
+ * so this is a deliberate sizing bet, not a measured latency distribution;
+ * the unchanged pendingAutoMerge tick backstop remains behind it for waits a
+ * single tick cannot absorb. */
+export const MERGEABILITY_RETRY_DELAYS_MS = [1000, 2000, 4000, 5000, 6000, 6000, 6000]
+
 /** Hard cap on the janitor poll's per-PR ETag cache. One small entry per PR
  * ever polled in a dispatcher process lifetime makes hitting this in practice
  * implausible; the cap is hygiene, not a load-bearing bound. */
@@ -514,7 +524,8 @@ export class GitHubForge implements Forge {
       env?: Readonly<Record<string, string | undefined>>
       /** Bounded waits between mergeability re-queries when GitHub reports
        * `mergeable_state: 'unknown'` (mergeability still being computed).
-       * Two retries default; tests inject `[0, 0]` so no test sleeps. */
+       * Defaults to `MERGEABILITY_RETRY_DELAYS_MS` (7 re-queries, ~30 s);
+       * tests inject `[0, 0]` or all-zero schedules so no test sleeps. */
       mergeabilityRetryDelaysMs?: number[]
     } = {},
   ) {
@@ -535,7 +546,7 @@ export class GitHubForge implements Forge {
       this.explicitRepository = this.env.AB_REPOSITORY
     }
     this.repoRoot = opts.repoRoot
-    this.mergeabilityRetryDelaysMs = opts.mergeabilityRetryDelaysMs ?? [500, 1500]
+    this.mergeabilityRetryDelaysMs = opts.mergeabilityRetryDelaysMs ?? MERGEABILITY_RETRY_DELAYS_MS
     this.prAttachments = new GitHubPrAttachmentHosting({ transport: this.transport })
   }
 

package/packages/core/src/ports/forge/local-git.ts

@@ -40,9 +40,39 @@ function detail(error: unknown): string {
 export class LocalGitForge implements Forge {
   readonly name = 'local-git'
   private readonly exec: Exec
+  /** The repository the optional checkout-less read seam reads from. The
+   * factory passes the served checkout; without it the capability is absent
+   * and callers retain their checkout/git fallbacks. */
+  private readonly repoRoot?: string
 
-  constructor(opts: { exec?: Exec } = {}) {
+  constructor(opts: { exec?: Exec; repoRoot?: string } = {}) {
     this.exec = opts.exec ?? bunExec
+    this.repoRoot = opts.repoRoot
+  }
+
+  /** Current tip of a local branch in the served repository. Throws when the
+   * branch does not exist — the same not-found contract as remote adapters. */
+  async remoteBranchSha(branch: string): Promise<string> {
+    if (this.repoRoot === undefined) {
+      throw new Error('local-git forge has no repository root for remote branch reads')
+    }
+    const result = await this.command(
+      ['rev-parse', '--verify', `refs/heads/${branch}`],
+      this.repoRoot,
+      true,
+    )
+    if (result.exitCode !== 0) throw new Error(`local-git: unknown remote branch ${branch}`)
+    return result.stdout.trim()
+  }
+
+  /** File bytes from the served repository. Ref omitted → the checkout's HEAD.
+   * Throws when the path does not exist at that ref. */
+  async readFile(path: string, ref?: string): Promise<string> {
+    if (this.repoRoot === undefined) {
+      throw new Error('local-git forge has no repository root for file reads')
+    }
+    const result = await this.command(['show', `${ref ?? 'HEAD'}:${path}`], this.repoRoot)
+    return result.stdout
   }
 
   private async command(args: string[], cwd: string, allowFailure = false) {

package/packages/core/src/ports/runner/claude.ts

@@ -38,7 +38,7 @@ import {
   toolInputPart,
   toolOutputPart,
 } from './stream-parts'
-import { classifyProviderError, configurationFailure } from './provider-error'
+import { classifyProviderError, missingExecutableFailure } from './provider-error'
 import { sessionEnv } from './session-env'
 import type { OneShotCompletion, OneShotCompletionInput, OneShotCompletionResult } from './one-shot'
 import type { RuntimeUsabilityInput, RuntimeUsabilityResult } from './runtime'
@@ -652,7 +652,7 @@ function launchFailure(error: unknown): ClaudeTurn {
   return {
     text: '',
     usage: { inputTokens: 0, outputTokens: 0 },
-    failure: missing ? configurationFailure(message) : classifyProviderError(message),
+    failure: missing ? missingExecutableFailure(message) : classifyProviderError(message),
     cli: {
       stdout: '',
       stderr: errorText(error),

package/packages/core/src/ports/runner/codex.ts

@@ -17,7 +17,11 @@ import {
   type Transcript,
 } from '../types'
 import type { OneShotCompletion, OneShotCompletionInput, OneShotCompletionResult } from './one-shot'
-import { classifyProviderError, configurationFailure, credentialFailure } from './provider-error'
+import {
+  classifyProviderError,
+  credentialFailure,
+  missingExecutableFailure,
+} from './provider-error'
 import {
   abortPart,
   errorPart,
@@ -694,7 +698,7 @@ function launchFailure(error: unknown): CodexTurn {
   return {
     text: '',
     usage: { inputTokens: 0, outputTokens: 0 },
-    failure: missing ? configurationFailure(message) : classifyProviderError(message),
+    failure: missing ? missingExecutableFailure(message) : classifyProviderError(message),
     cli: { stdout: '', stderr: errorText(error), exitCode: -1 },
     events: [],
     malformedLines: [],

package/packages/core/src/ports/runner/fake.ts

@@ -49,12 +49,18 @@ export function failedTurnResult(
   permanent: boolean,
   text = '',
   cause?: AgentFailureCause,
+  missingExecutable?: true,
 ): AgentTurnResult {
   return {
     kind: 'failed',
     text,
     usage: { inputTokens: 0, outputTokens: 0, turns: 1 },
-    failure: { message, permanent, ...(cause !== undefined ? { cause } : {}) },
+    failure: {
+      message,
+      permanent,
+      ...(cause !== undefined ? { cause } : {}),
+      ...(missingExecutable === true ? { missingExecutable } : {}),
+    },
   }
 }
 

package/packages/core/src/ports/runner/pi.ts

@@ -13,7 +13,12 @@ import {
   type Transcript,
 } from '../types'
 import type { OneShotCompletion, OneShotCompletionInput, OneShotCompletionResult } from './one-shot'
-import { classifyProviderError, configurationFailure, credentialFailure } from './provider-error'
+import {
+  classifyProviderError,
+  configurationFailure,
+  credentialFailure,
+  missingExecutableFailure,
+} from './provider-error'
 import { createPiRpcSession, PI_MODEL_ARG, PI_RPC_MODE_ARG } from './pi-rpc'
 import {
   abortPart,
@@ -586,11 +591,8 @@ export class PiAgentRunner implements AgentRunner, OneShotCompletion {
 
 function localPiFailure(error: unknown): AgentTurnFailure {
   const message = errorText(error)
-  if (
-    /executable "pi" was not found|requires Pi .* or newer|could not parse detected Pi version/.test(
-      message,
-    )
-  ) {
+  if (/executable "pi" was not found/.test(message)) return missingExecutableFailure(message)
+  if (/requires Pi .* or newer|could not parse detected Pi version/.test(message)) {
     return configurationFailure(message)
   }
   if (/not ready|authentication|logged in|credentials/i.test(message))

package/packages/core/src/ports/runner/provider-error.ts

@@ -77,9 +77,12 @@ export function classifyProviderError(
 /** Whether another declared target may be tried inside this phase attempt.
  * Legacy plugins have no cause: preserve their old safe split. */
 export function isAlternateEligible(failure: AgentTurnFailure): boolean {
-  return failure.cause === undefined
-    ? !failure.permanent
-    : failure.cause === 'availability' || failure.cause === 'exhaustion'
+  if (failure.cause === undefined) return !failure.permanent
+  return (
+    failure.cause === 'availability' ||
+    failure.cause === 'exhaustion' ||
+    (failure.cause === 'configuration' && failure.missingExecutable === true)
+  )
 }
 
 /** Final-failure retry behavior remains governed by the compatibility bit. */
@@ -92,6 +95,13 @@ export function configurationFailure(message: string): AgentTurnFailure {
   return { message, permanent: true, cause: 'configuration' }
 }
 
+/** The runtime's CLI executable is not installed. Still a permanent
+ * `configuration` failure (never retried), but a later declared target whose
+ * CLI is installed may serve the phase. */
+export function missingExecutableFailure(message: string): AgentTurnFailure {
+  return { message, permanent: true, cause: 'configuration', missingExecutable: true }
+}
+
 /** Explicit credential failures bypass both alternates and phase retries. */
 export function credentialFailure(message: string): AgentTurnFailure {
   return { message, permanent: true, cause: 'credentials' }

package/packages/core/src/ports/tickets/{remote-index.ts → hosted-index.ts}

@@ -1,7 +1,8 @@
+// Client half of the hosted ticket source (SPEC §13): the TicketSource a
+// local CLI drives against a hosted deployment. The HTTP server half ships
+// in `@defrex/autobuild-hosted-store-service`.
 export { HostedTicketSource } from './remote'
 export type { HostedTicketFetch, HostedTicketSourceOptions } from './remote'
-export { createTicketServer } from './remote-server'
-export type { TicketServerOptions } from './remote-server'
 export {
   HOSTED_TICKET_OPERATIONS,
   hostedTicketContextSchema,

package/packages/core/src/ports/types.ts

@@ -177,8 +177,11 @@ export interface WorkspaceProvisionResult extends WorkspaceHandle {
 
 export interface WorkspacePublication {
   /** Observe whether the exact requested commit already reached the durable
-   * remote branch after an interrupted acknowledgement. */
-  isPublished?(input: { sha: string; branch: string }): Promise<boolean>
+   * remote branch after an interrupted acknowledgement. `ref` optionally
+   * names the workspace whose git database the probe runs against — used by
+   * the operator-sandbox publication path, whose provider probes from the
+   * sandbox checkout; the build-path callers omit it. */
+  isPublished?(input: { ref?: string; sha: string; branch: string }): Promise<boolean>
   /** Publish exactly one commit to exactly one branch; no arbitrary command
    * surface is exposed to the dispatcher or build child. */
   publish(input: { ref: string; sha: string; branch: string }): Promise<void>
@@ -221,6 +224,14 @@ export interface WorkspaceProvider {
   readonly orchestratorSandbox?: OperatorSandboxExecution
   /** Trusted dispatcher-only publication capability for remote workspaces. */
   readonly publication?: WorkspacePublication
+  /** Publication capability for the operator sandbox (PR-only publication):
+   * deliberately distinct from `publication`, which is the dispatcher's
+   * remote-workspace discriminator — its presence reclassifies every build
+   * workspace as remote and reroutes build publication. `sandboxPublication`
+   * is never consulted by the dispatcher; it is consumed only by the
+   * operator-sandbox publish service, and present only on providers that can
+   * host operator sandboxes. */
+  readonly sandboxPublication?: WorkspacePublication
   /** Optional only for remote/disposable providers. */
   readonly recovery?: WorkspaceRecovery
   provision(opts: {
@@ -424,6 +435,10 @@ export interface AgentTurnFailure {
   /** Additive structured routing cause. Legacy plugin runners may omit it;
    * their existing permanent bit then supplies the conservative behavior. */
   cause?: AgentFailureCause
+  /** Set with cause 'configuration' when the runtime's CLI executable is not
+   * installed. This is the one configuration failure a configured alternate
+   * may serve; every other configuration failure still stops the chain. */
+  missingExecutable?: true
 }
 
 /** A turn that reached a provider/runtime-declared failure while retaining an

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

@@ -0,0 +1,114 @@
+/**
+ * The full capability objects for the builtin workspace providers (AUT-516).
+ * The parse-time subset lives in `config/schema.ts`'s
+ * `BUILTIN_WORKSPACE_PROVIDER_CONFIG` because config validation must be
+ * statically reachable without the registry; this module assembles the FULL
+ * declarations — including the registry-seam behaviors — and is attached to
+ * the builtin registrations by `plugins/registry.ts`.
+ *
+ * Import graph discipline: this module imports `config/schema.ts`,
+ * `git-worktree.ts`, `vercel-sandbox.ts`, and the shared vercel capability
+ * module; nothing imports it from `schema.ts`, so no cycle exists. The
+ * `vercel-sandbox` entry's capabilities are the shared
+ * `VERCEL_SANDBOX_CAPABILITIES` object (AUT-517) — the plugin package
+ * references the same object, so the declarations cannot drift. The
+ * construction-site `configRefusal` for git-worktree is set EXPLICITLY here,
+ * not copied from the table's parse-site `configRefusalMessage` — the two
+ * strings differ by design (the parse-site message adds the remediation
+ * clause; the construction-site one does not).
+ *
+ * This `BUILTINS` record is the single source of truth for which builtins
+ * exist: `plugins/registry.ts` derives its builtin workspace-provider set
+ * from `builtinWorkspaceProviderNames()` (AUT-579), so adding an entry here
+ * (plus the config-table half that AUT-573's parity tests pin) completes
+ * the registration step — no registry edit is required.
+ */
+import { join, resolve } from 'node:path'
+import type { VercelSandboxConfig, WorkspaceConfig } from '../../config/schema'
+import type { WorkspaceProviderCapabilities } from './provider-capabilities'
+import type { CreateWorkspaceProviderOptions } from './create'
+import { GitWorktreeProvider } from './git-worktree'
+import { VercelSandboxProvider } from './vercel-sandbox'
+import { VERCEL_SANDBOX_CAPABILITIES } from './vercel-capabilities'
+import type { WorkspaceProvider } from '../types'
+
+/** The git-worktree construction-site refusal: no remediation clause, unlike
+ * the parse-site message in the config table. */
+const GIT_WORKTREE_CONSTRUCTION_REFUSAL =
+  '[workspace.config] is not supported by the builtin "git-worktree" provider'
+
+interface BuiltinWorkspaceProviderDeclaration {
+  capabilities: WorkspaceProviderCapabilities
+  builtinFactory: (
+    config: WorkspaceConfig,
+    opts: CreateWorkspaceProviderOptions,
+    parsed: unknown,
+  ) => WorkspaceProvider | Promise<WorkspaceProvider>
+}
+
+const BUILTINS: Record<string, BuiltinWorkspaceProviderDeclaration> = {
+  'git-worktree': {
+    capabilities: {
+      configRefusal: GIT_WORKTREE_CONSTRUCTION_REFUSAL,
+    },
+    builtinFactory(_config, opts) {
+      // Its provider config is always `{}`: the refusal (parse site and
+      // construction site alike) has already rejected anything else.
+      return new GitWorktreeProvider({
+        root: resolve(opts.worktreeRoot),
+        sandboxRoot:
+          opts.sandboxRoot ?? resolve(join(opts.worktreeRoot, '..', 'orchestrator-sandboxes')),
+        setupCommand: opts.sandboxSetupCommand,
+        sandboxEnvironmentVariables: opts.sandboxEnvironmentVariables,
+        envSource: opts.env,
+      })
+    },
+  },
+  'vercel-sandbox': {
+    capabilities: VERCEL_SANDBOX_CAPABILITIES,
+    builtinFactory(_config, opts, parsed) {
+      // storeRef/storeToken are guaranteed present: the pre-split
+      // storeRequirements check in createWorkspaceProvider ran before
+      // construction.
+      return new VercelSandboxProvider({
+        config: parsed as VercelSandboxConfig,
+        env: opts.env,
+        storeRef: opts.storeRef!,
+        storeToken: opts.storeToken!,
+        repo: resolve(opts.repoRoot),
+        runtimeReferences: opts.runtimeReferences ?? [],
+        setupCommand: opts.sandboxSetupCommand,
+        sandboxEnvironmentVariables: opts.sandboxEnvironmentVariables,
+        ...(opts.origin !== undefined ? { origin: opts.origin } : {}),
+        ...(opts.remoteBranchHead !== undefined ? { remoteBranchHead: opts.remoteBranchHead } : {}),
+      })
+    },
+  },
+}
+
+/** Every builtin provider name, for parity checks over the declaration
+ * tables (AUT-573): the parse-time table in `config/schema.ts` and the FULL
+ * declarations here must cover the same provider set. */
+export function builtinWorkspaceProviderNames(): readonly string[] {
+  return Object.keys(BUILTINS)
+}
+
+/** The FULL capability object of a builtin workspace provider, `undefined`
+ * for any other name. Used by pre-registry seams (guest probe, init
+ * preflight) that cannot consult the plugin registry. */
+export function builtinWorkspaceProviderCapabilities(
+  name: string,
+): WorkspaceProviderCapabilities | undefined {
+  return BUILTINS[name]?.capabilities
+}
+
+/** The builtin registration extras for `plugins/registry.ts`: the capability
+ * object plus the host-owned construction closure. */
+export function builtinWorkspaceProviderRegistration(
+  name: string,
+): BuiltinWorkspaceProviderDeclaration | undefined {
+  const builtin = BUILTINS[name]
+  return builtin === undefined
+    ? undefined
+    : { capabilities: builtin.capabilities, builtinFactory: builtin.builtinFactory }
+}

package/packages/core/src/ports/workspace/create.ts

@@ -1,11 +1,17 @@
-import { join, resolve } from 'node:path'
-import { vercelSandboxConfigSchema, type WorkspaceConfig } from '../../config/schema'
+import { resolve } from 'node:path'
+import { SANDBOX_FORBIDDEN_ENV } from './operator-sandbox'
+import type { WorkspaceConfig } from '../../config/schema'
 import type { PluginRegistry } from '../../plugins/registry'
 import type { WorkspaceProvider } from '../types'
 import type { BuildExecution } from './build-execution'
-import { GitWorktreeProvider } from './git-worktree'
+import {
+  currentRuntimeReferences,
+  runtimeProvisioningMap,
+  runtimeProvisioningMissingMessage,
+  sandboxForbiddenEnvMessage,
+} from './provider-capabilities'
 import { LocalBuildExecution } from './local-build-execution'
-import { type RuntimeReferencesSource, VercelSandboxProvider } from './vercel-sandbox'
+import type { RuntimeReferencesSource } from './vercel-sandbox'
 
 export interface CreateWorkspaceProviderOptions {
   registry: PluginRegistry
@@ -31,6 +37,11 @@ export interface CreateWorkspaceProviderOptions {
   sandboxSetupCommand?: string
   sandboxRoot?: string
   sandboxEnvironmentVariables?: readonly string[]
+  /** Whether `[orchestrator].enabled` is set at the call site. Gates the
+   * construction-site `sandboxForbiddenEnv` check so the parse-time rule is
+   * reproduced exactly (the config validation only runs when the orchestrator
+   * is enabled). */
+  orchestratorSandboxEnabled?: boolean
 }
 
 export interface WorkspaceRuntime {
@@ -53,44 +64,56 @@ export async function createWorkspaceProvider(
     )
   }
 
-  if (registration.owner.kind === 'builtin') {
-    if (config.provider === 'git-worktree') {
-      if (Object.keys(config.config).length > 0) {
-        throw new Error(
-          '[workspace.config] is not supported by the builtin "git-worktree" provider',
-        )
-      }
-      return new GitWorktreeProvider({
-        root: resolve(opts.worktreeRoot),
-        sandboxRoot:
-          opts.sandboxRoot ?? resolve(join(opts.worktreeRoot, '..', 'orchestrator-sandboxes')),
-        setupCommand: opts.sandboxSetupCommand,
-        sandboxEnvironmentVariables: opts.sandboxEnvironmentVariables,
-        envSource: opts.env,
-      })
+  // Uniform capability enforcement (AUT-516): every declaration that needs
+  // the registry is honoured here, before the builtin/plugin split, where
+  // `registration.capabilities`, `opts.storeRef`, and `opts.storeToken` are
+  // already in hand — a plugin declaring any of them is enforced too, never
+  // accepted by manifest parsing and silently ignored. Order preserves the
+  // builtin failure precedence.
+  const capabilities = registration.capabilities
+  const hasConfig = Object.keys(config.config).length > 0
+  if (capabilities?.configRefusal !== undefined && hasConfig) {
+    throw new Error(capabilities.configRefusal)
+  }
+  let parsed: { data: unknown } | undefined
+  if (capabilities?.configSchema !== undefined) {
+    const result = capabilities.configSchema.safeParse(config.config)
+    if (!result.success) {
+      throw new Error(`invalid ${config.provider} config: ${result.error.message}`)
     }
-    if (config.provider === 'vercel-sandbox') {
-      const parsed = vercelSandboxConfigSchema.safeParse(config.config)
-      if (!parsed.success) throw new Error(`invalid vercel-sandbox config: ${parsed.error.message}`)
-      if (opts.storeRef === undefined || opts.storeToken === undefined) {
-        throw new Error('vercel-sandbox requires an HTTPS BuildStore and scoped AB_TOKEN authority')
+    parsed = result as { data: unknown }
+  }
+  if (capabilities?.requireRuntimeProvisioning === true && opts.runtimeReferences !== undefined) {
+    // `mcp.ts` passes no `runtimeReferences` because it references no runtimes;
+    // dispatch and init validation always do.
+    const provisioning = runtimeProvisioningMap(parsed !== undefined ? parsed.data : config.config)
+    for (const group of currentRuntimeReferences(opts.runtimeReferences)) {
+      if (Object.hasOwn(provisioning, group.runtime)) continue
+      throw new Error(runtimeProvisioningMissingMessage(group))
+    }
+  }
+  if (opts.orchestratorSandboxEnabled === true && capabilities?.sandboxForbiddenEnv !== undefined) {
+    for (const name of opts.sandboxEnvironmentVariables ?? []) {
+      if (SANDBOX_FORBIDDEN_ENV.includes(name) || capabilities.sandboxForbiddenEnv.includes(name)) {
+        throw new Error(sandboxForbiddenEnvMessage(name))
       }
-      return new VercelSandboxProvider({
-        config: parsed.data,
-        env: opts.env,
-        storeRef: opts.storeRef,
-        storeToken: opts.storeToken,
-        repo: resolve(opts.repoRoot),
-        runtimeReferences: opts.runtimeReferences ?? [],
-        setupCommand: opts.sandboxSetupCommand,
-        sandboxEnvironmentVariables: opts.sandboxEnvironmentVariables,
-        ...(opts.origin !== undefined ? { origin: opts.origin } : {}),
-        ...(opts.remoteBranchHead !== undefined ? { remoteBranchHead: opts.remoteBranchHead } : {}),
-      })
     }
-    throw new Error(
-      `workspace provider "${config.provider}" is registered as a builtin but has no constructor`,
-    )
+  }
+  if (
+    capabilities?.storeRequirements !== undefined &&
+    (opts.storeRef === undefined || opts.storeToken === undefined)
+  ) {
+    throw new Error(capabilities.storeRequirements.constructionMessage)
+  }
+
+  if (registration.owner.kind === 'builtin') {
+    const builtinFactory = registration.builtinFactory
+    if (builtinFactory === undefined) {
+      throw new Error(
+        `workspace provider "${config.provider}" is registered as a builtin but has no constructor`,
+      )
+    }
+    return builtinFactory(config, opts, parsed !== undefined ? parsed.data : config.config)
   }
 
   const factory = registration.factory
@@ -101,10 +124,22 @@ export async function createWorkspaceProvider(
   }
 
   try {
+    // Conditional spreads keep the existing exactness guarantee: a call site
+    // that supplies no seams constructs exactly `{ config, env, repoRoot }`,
+    // so plugin factories see no `undefined`-valued additions. With seams,
+    // the context widens in place (AUT-560) — the seams the builtin factory
+    // receives through `opts` reach the plugin factory through the context.
     return await factory({
       config: config.config,
       env: opts.env,
       repoRoot: resolve(opts.repoRoot),
+      ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
+      ...(opts.storeToken !== undefined ? { storeToken: opts.storeToken } : {}),
+      ...(opts.runtimeReferences !== undefined
+        ? { runtimeReferences: opts.runtimeReferences }
+        : {}),
+      ...(opts.origin !== undefined ? { origin: opts.origin } : {}),
+      ...(opts.remoteBranchHead !== undefined ? { remoteBranchHead: opts.remoteBranchHead } : {}),
     })
   } catch (error) {
     throw new Error(