@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/plugins/load.ts

@@ -1,4 +1,5 @@
-import { isAbsolute } from 'node:path'
+import { existsSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { ZodError } from 'zod'
 import { distributionRoot } from '../distribution'
@@ -7,6 +8,7 @@ import {
   parsePluginManifest,
   pluginApiCompatibility,
   PluginApiCompatibilityError,
+  type AutobuildPluginManifest,
   type PluginApiCompatibility,
 } from './manifest'
 import { createPluginRegistry, type PluginRegistry, type PluginResolutionKind } from './registry'
@@ -15,6 +17,49 @@ function reason(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+/** The package directory a bare specifier names: `@scope/name/sub` names
+ * `@scope/name`, `name/sub` names `name`. Subpath exports resolve inside the
+ * package, so the on-disk gate below must check the package, not the
+ * subpath. */
+function packageNameOf(specifier: string): string {
+  const segments = specifier.split('/')
+  return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : (segments[0] ?? specifier)
+}
+
+/** First directory of `root`'s ancestor chain (inclusive) under which
+ * `node_modules/<specifier>` exists on disk, or undefined. Pure filesystem
+ * syscalls — deliberately no Bun APIs: `Bun.resolveSync` on a bare specifier
+ * that no `node_modules` lookup satisfies hands the specifier to Bun's
+ * runtime auto-installer, which fetches from the network and writes a cache;
+ * on a read-only filesystem (the hosted dispatcher function) that is a
+ * fatal, uncatchable process exit (AUT-587). Gating on a disk hit keeps the
+ * installer unreachable: per the planner-verified Bun 1.4 behavior, a
+ * resolver call whose base chain holds the package on disk resolves from
+ * disk and never touches the installer.
+ *
+ * Termination (AUT-597): `root` is resolved to an absolute path before the
+ * walk begins, so a relative candidate root cannot make `dirname` a fixed
+ * point and spin the loop forever. The `parent === current` guard backstops
+ * the fixed point (`dirname('/') === '/'`) should the loop's start point
+ * ever change.
+ *
+ * Candidate-root provenance (AUT-604): production callers never supply a
+ * non-filesystem token here. Origin mode does not pass
+ * `'<hosted-dispatcher>'` — `abDispatch` normalizes `targetRepo` to the
+ * per-origin scratch root before `loadPlugins` runs — so candidate roots
+ * are always real filesystem roots; a relative one reaching this walk is a
+ * caller bug with a fail-closed outcome, not a supported input. */
+function diskNodeModulesDirectory(specifier: string, root: string): string | undefined {
+  const pkg = packageNameOf(specifier)
+  let current = resolve(root)
+  while (true) {
+    if (existsSync(join(current, 'node_modules', pkg))) return current
+    const parent = dirname(current)
+    if (parent === current) return undefined
+    current = parent
+  }
+}
+
 function importUrl(resolved: string): string {
   return resolved.startsWith('file:') ? resolved : pathToFileURL(resolved).href
 }
@@ -30,12 +75,15 @@ export interface PluginModuleReport {
   resolutionKind: PluginResolutionKind
   resolved?: string
   resolvedFrom?: PluginResolutionSource
-  status: 'loaded' | 'failed'
+  status: 'loaded' | 'failed' | 'skipped'
   stage: PluginLoadStage | 'loaded'
   pluginName?: string
   api?: PluginApiCompatibility
   error?: string
   cause?: unknown
+  /** One-line explanation for a `skipped` report, emitted through the
+   * loader's notice channel. Undefined for `loaded` and `failed`. */
+  notice?: string
 }
 
 export interface PluginDiagnosis {
@@ -52,6 +100,14 @@ export interface PluginLoadOptions {
    * loads without being added to the repository. Defaults to the running
    * distribution's root. */
   installationRoot?: string
+  /** Guest context (AUT-517): a package-kind specifier that cannot be
+   * resolved from either candidate is skipped with a notice instead of
+   * failing the process, because guests never construct workspace providers
+   * and may legitimately be handed a provider plugin they need not load.
+   * Repo-path specifiers and every post-resolution failure stay fail-closed. */
+  guest?: boolean
+  /** Notice channel for skipped loads. Defaults to one line on stderr. */
+  onNotice?: (line: string) => void
 }
 
 export function pluginResolutionKind(moduleSpecifier: string): PluginResolutionKind {
@@ -79,6 +135,14 @@ function failed(
   }
 }
 
+/** True when the manifest declares no registrations outside the
+ * workspace-provider map. */
+function declaresOnlyWorkspaceProviderRegistrations(manifest: AutobuildPluginManifest): boolean {
+  const empty = (registrations: Record<string, unknown> | undefined): boolean =>
+    registrations === undefined || Object.keys(registrations).length === 0
+  return empty(manifest.ticketSources) && empty(manifest.agentRuntimes) && empty(manifest.forges)
+}
+
 function manifestIdentity(value: unknown): {
   pluginName?: string
   api?: PluginApiCompatibility
@@ -130,8 +194,17 @@ export async function attemptPlugin(
     let found: { path: string; source: PluginResolutionSource } | undefined
     let lastError: unknown
     for (const candidate of candidates) {
+      // Disk-first gate (AUT-587): only a candidate whose `node_modules`
+      // chain holds the package on disk reaches the resolver. Bun's runtime
+      // auto-installer fires exactly when disk resolution fails, so a miss
+      // here must be recorded without calling `Bun.resolveSync` at all.
+      const diskRoot = diskNodeModulesDirectory(moduleSpecifier, candidate.root)
+      if (diskRoot === undefined) {
+        failures.push(`${candidate.source} "${candidate.root}"`)
+        continue
+      }
       try {
-        found = { path: Bun.resolveSync(moduleSpecifier, candidate.root), source: candidate.source }
+        found = { path: Bun.resolveSync(moduleSpecifier, diskRoot), source: candidate.source }
         break
       } catch (error) {
         lastError = error
@@ -139,10 +212,26 @@ export async function attemptPlugin(
       }
     }
     if (found === undefined) {
+      if (options.guest === true) {
+        return {
+          ...initial,
+          status: 'skipped',
+          stage: 'resolution',
+          notice:
+            `plugin module "${moduleSpecifier}" could not be resolved from ${failures.join(' or ')}; ` +
+            'guests never construct workspace providers, so the provider plugin is skipped here',
+        }
+      }
+      // A disk miss never reached the resolver, so there is no Bun error to
+      // quote — say directly what the gate established instead.
+      const detail =
+        lastError !== undefined
+          ? reason(lastError)
+          : `no "node_modules/${packageNameOf(moduleSpecifier)}" entry exists on disk under any candidate root`
       return failed(
         initial,
         'resolution',
-        `plugin module "${moduleSpecifier}" could not be resolved from ${failures.join(' or ')}: ${reason(lastError)}`,
+        `plugin module "${moduleSpecifier}" could not be resolved from ${failures.join(' or ')}: ${detail}`,
         lastError,
       )
     }
@@ -201,6 +290,33 @@ export async function attemptPlugin(
     pluginName: manifest.name,
     api,
   }
+  // Transitional duplicate-skip (AUT-517): while the builtin hosts the
+  // vercel-sandbox implementation, a configured plugin that re-registers the
+  // same workspace-provider name must be accepted and skipped, not thrown
+  // out of startup. Skip the whole module IFF it declares at least one
+  // registration, only workspace-provider registrations, and EVERY declared
+  // name collides with a builtin workspace-provider registration. Any other
+  // collision (other ports, plugin-vs-plugin, mixed fresh/colliding) throws
+  // exactly as before via registry.register below. Keyed on builtin
+  // ownership, so the rule retires itself when the builtin is removed.
+  const collisions = registry.builtinWorkspaceProviderCollisions(manifest)
+  if (
+    collisions.length > 0 &&
+    declaresOnlyWorkspaceProviderRegistrations(manifest) &&
+    collisions.length === Object.keys(manifest.workspaceProviders ?? {}).length
+  ) {
+    const names = Object.keys(manifest.workspaceProviders ?? {})
+      .map((name) => JSON.stringify(name))
+      .join(', ')
+    return {
+      ...identified,
+      status: 'skipped',
+      stage: 'registration',
+      notice:
+        `plugin "${manifest.name}" declares only builtin workspace-provider registration(s) ${names}; ` +
+        'skipping it — the builtin keeps serving the provider',
+    }
+  }
   try {
     registry.register(manifest, {
       module: moduleSpecifier,
@@ -224,7 +340,9 @@ export async function attemptPlugin(
 }
 
 /** Exhaustively attempt configured modules in declaration order. Failed
- * modules leave no registrations; later healthy modules still load. */
+ * modules leave no registrations; later healthy modules still load. Skipped
+ * modules (builtin duplicate-skip, guest tolerance) register nothing and
+ * count as healthy. */
 export async function diagnosePlugins(
   modules: readonly string[],
   repoRoot: string,
@@ -238,22 +356,32 @@ export async function diagnosePlugins(
   return {
     registry,
     reports,
-    healthy: reports.every((report) => report.status === 'loaded'),
+    healthy: reports.every((report) => report.status !== 'failed'),
   }
 }
 
-/** Dispatch compatibility wrapper: preserve first-failure, fail-closed startup. */
+function defaultPluginNotice(line: string): void {
+  console.error(line)
+}
+
+/** Dispatch compatibility wrapper: preserve first-failure, fail-closed startup.
+ * Skipped modules are announced through the notice channel and load
+ * continues. */
 export async function loadPlugins(
   modules: readonly string[],
   repoRoot: string,
   options: PluginLoadOptions = {},
   registry: PluginRegistry = createPluginRegistry(),
 ): Promise<PluginRegistry> {
+  const onNotice = options.onNotice ?? defaultPluginNotice
   for (const moduleSpecifier of modules) {
     const report = await attemptPlugin(moduleSpecifier, repoRoot, registry, options)
     if (report.status === 'failed') {
       throw new Error(report.error, { cause: report.cause })
     }
+    if (report.status === 'skipped' && report.notice !== undefined) {
+      onNotice(report.notice)
+    }
   }
   return registry
 }

package/packages/core/src/plugins/manifest.ts

@@ -8,9 +8,13 @@ import type { RuntimeRegistration } from '../ports/runner/runtime'
 import type { TicketSourceContractFactory } from '../ports/tickets/contract'
 import type { ForgeContractFactory } from '../ports/forge/contract'
 import type { WorkspaceProviderContractFactory } from '../ports/workspace/contract'
+import type {
+  RuntimeReferencesSource,
+  WorkspaceProviderCapabilities,
+} from '../ports/workspace/provider-capabilities'
 
 /** Version of the in-process plugin contract exposed by `@defrex/autobuild/plugin-sdk`. */
-export const PLUGIN_API_VERSION = '1.5.0' as const
+export const PLUGIN_API_VERSION = '1.7.0' as const
 
 /** Context supplied when a registered adapter or contract fixture is selected. */
 export interface PluginFactoryContext<Config = Record<string, unknown>> {
@@ -22,12 +26,48 @@ export interface PluginFactoryContext<Config = Record<string, unknown>> {
   repoRoot: string
 }
 
-export type PluginFactory<Adapter, Config = Record<string, unknown>> = {
+export type PluginFactory<
+  Adapter,
+  Config = Record<string, unknown>,
+  Context = PluginFactoryContext<Config>,
+> = {
   /** The method-index form intentionally makes this callback bivariant, so a
-   * plugin can retain its concrete config type across the erased manifest. */
-  invoke(context: PluginFactoryContext<Config>): Adapter | Promise<Adapter>
+   * plugin can retain its concrete config type across the erased manifest —
+   * and a port that widens the context (workspace providers receive the
+   * host-derived seams, AUT-560) keeps every base-context factory assignable. */
+  invoke(context: Context): Adapter | Promise<Adapter>
 }['invoke']
 
+/** Context supplied to a workspace-provider factory: the shared
+ * `{ config, env, repoRoot }` context plus the host-derived seams a
+ * store-requiring remote provider needs (AUT-560). Every added field is
+ * optional — the shared call sites that carry no seam construct the plain
+ * shared context, and a factory that ignores the new fields changes nothing.
+ * Plugin API 1.7.0. */
+export interface WorkspaceProviderPluginFactoryContext<Config = Record<string, unknown>>
+  extends PluginFactoryContext<Config> {
+  /** Git store URL the dispatcher selected (`AB_STORE`). Guaranteed present
+   * when the registration declares `capabilities.storeRequirements`:
+   * `createWorkspaceProvider` refuses construction before the factory runs
+   * when either store seam is missing. */
+  storeRef?: string
+  /** Scoped store token (`AB_TOKEN`). Guaranteed present under
+   * `capabilities.storeRequirements` for the same reason. */
+  storeToken?: string
+  /** Host-derived effective runtime routes (the referenced runtimes and their
+   * selection provenance). Absent at call sites that reference no runtimes
+   * (for example the MCP server), which never construct a workspace. */
+  runtimeReferences?: RuntimeReferencesSource
+  /** Checkout-less seam: the repository's HTTPS origin. When absent the
+   * provider falls back to host `git` from `repoRoot` — the same default the
+   * builtin `VercelSandboxProvider` applies. */
+  origin?: () => Promise<string>
+  /** Checkout-less seam: the remote branch's current head, `undefined` when
+   * the branch does not exist. When absent the provider falls back to host
+   * `git` from `repoRoot`. */
+  remoteBranchHead?: (branch: string) => Promise<string | undefined>
+}
+
 export type TicketSourcePluginFactory<Config = Record<string, unknown>> = PluginFactory<
   TicketSource,
   Config
@@ -53,10 +93,29 @@ export type AgentRuntimePluginFactory<Config = Record<string, unknown>> = Plugin
 >
 export type WorkspaceProviderPluginFactory<Config = Record<string, unknown>> = PluginFactory<
   WorkspaceProvider,
-  Config
+  Config,
+  WorkspaceProviderPluginFactoryContext<Config>
 >
 export type ForgePluginFactory<Config = Record<string, unknown>> = PluginFactory<Forge, Config>
 
+/** Optional host-enforced metadata for a workspace provider. Bare factories
+ * remain valid for plugin API 1.0 compatibility. Required environment lives
+ * on `capabilities.requiredEnv` — a descriptor-level `requiredEnv` is
+ * rejected at manifest parse (see `workspaceProviderRegistrationSchema`). */
+export interface WorkspaceProviderPluginDescriptor<Config = Record<string, unknown>> {
+  factory: WorkspaceProviderPluginFactory<Config>
+  /** Optional shared-suite certification fixture. */
+  contract?: PluginContractDescriptor<WorkspaceProviderContractFactory>
+  /** Behavior declarations the host enforces without naming the provider
+   * (AUT-516): config schema, forges, environment groups, store requirements,
+   * origin validation, and remote readiness. */
+  capabilities?: WorkspaceProviderCapabilities
+}
+
+export type WorkspaceProviderPluginRegistration<Config = Record<string, unknown>> =
+  | WorkspaceProviderPluginFactory<Config>
+  | WorkspaceProviderPluginDescriptor<Config>
+
 export interface PluginContractDescriptor<ContractFactory, Config = Record<string, unknown>> {
   /** Creates the unchanged shared-suite harness factory when the test verb runs. */
   factory: PluginFactory<ContractFactory, Config>
@@ -75,10 +134,6 @@ export type AgentRuntimePluginRegistration = PluginAdapterRegistration<
   AgentRuntimePluginFactory,
   AgentRunnerContractFactory
 >
-export type WorkspaceProviderPluginRegistration = PluginAdapterRegistration<
-  WorkspaceProviderPluginFactory,
-  WorkspaceProviderContractFactory
->
 export type ForgePluginRegistration = PluginAdapterRegistration<
   ForgePluginFactory,
   ForgeContractFactory
@@ -212,6 +267,120 @@ const ticketSourceRegistrationSchema = z.unknown().transform((value, ctx) => {
   return z.NEVER
 })
 
+/** Function-valued capability fields (origin validation, redaction, summary
+ * lines, remote readiness). */
+const capabilityFunctionSchema = z.custom<(...args: never[]) => unknown>(
+  (value) => typeof value === 'function',
+  'must be a function',
+)
+
+const workspaceProviderCapabilitiesSchema = z.strictObject({
+  // A Zod schema carries both `parse` and `safeParse`; the consumers use each
+  // (`create.ts` parses with `safeParse`, `init-validation.ts` with `parse`),
+  // so requiring only one would let a half-shaped object past manifest parsing
+  // and crash the other seam with a TypeError instead of the config
+  // diagnostic (f_69fc887c).
+  configSchema: z
+    .custom<z.ZodType>((value) => {
+      if (value === null || typeof value !== 'object') return false
+      const shape = value as { parse?: unknown; safeParse?: unknown }
+      return typeof shape.parse === 'function' && typeof shape.safeParse === 'function'
+    }, 'must be a Zod schema')
+    .optional(),
+  configRefusal: z.string().optional(),
+  requireRuntimeProvisioning: z.boolean().optional(),
+  sandboxForbiddenEnv: z.array(z.string()).optional(),
+  supportedForges: z.array(z.string()).optional(),
+  forgeDispatchMessage: z.string().optional(),
+  forgeValidationMessage: z.string().optional(),
+  requiredEnv: z
+    .array(
+      z.strictObject({
+        alternatives: z.array(z.array(z.string().min(1)).min(1)).min(1),
+        dispatchMessage: z.string().optional(),
+        validationMessage: z.string().optional(),
+      }),
+    )
+    // AUT-554: a group carrying neither message is skipped at both
+    // enforcement sites (dispatch.ts omits an undefined dispatchMessage;
+    // init-validation.ts's declaredForgeEnvChecks omits an undefined
+    // validationMessage), so accepting it here would license a declaration
+    // the host never enforces. The issue anchors at the group's index so the
+    // rendered path names it by location and the message names it by its
+    // alternatives. The shape guard keeps the check quiet when the group's
+    // structural diagnostics already speak: zod v4 runs refinements even
+    // after a check-stage failure inside the group (an empty alternatives
+    // array still parses through), and a malformed group must not grow a
+    // second, degraded copy of this issue.
+    .superRefine((groups, ctx) => {
+      groups.forEach((group, index) => {
+        if (group.dispatchMessage !== undefined || group.validationMessage !== undefined) return
+        // Skip a structurally malformed group: its own diagnostics speak.
+        if (
+          group.alternatives.length === 0 ||
+          group.alternatives.some((names) => names.length === 0)
+        )
+          return
+        const alternatives = group.alternatives.map((names) => names.join(', ')).join(' | ')
+        ctx.addIssue({
+          code: 'custom',
+          path: [index],
+          message: `requiredEnv group (alternatives: ${alternatives}) declares neither dispatchMessage nor validationMessage; declare at least one so the host enforces this group — a group with neither is silently skipped at dispatch and init validation`,
+        })
+      })
+    })
+    .optional(),
+  processEnvOnly: z
+    .array(z.strictObject({ name: z.string().min(1), message: z.string() }))
+    .optional(),
+  storeRequirements: z
+    .strictObject({
+      constructionMessage: z.string(),
+      storeRefMessage: z.string(),
+      storeTokenMessage: z.string(),
+    })
+    .optional(),
+  validateOrigin: capabilityFunctionSchema.optional(),
+  originReadFailureMessage: z.string().optional(),
+  guestEnvNames: capabilityFunctionSchema.optional(),
+  describeEnvironment: capabilityFunctionSchema.optional(),
+  validateReadiness: capabilityFunctionSchema.optional(),
+})
+
+const workspaceProviderDescriptorSchema = z.strictObject({
+  factory: factorySchema,
+  contract: contractSchema.optional(),
+  capabilities: workspaceProviderCapabilitiesSchema.optional(),
+})
+
+/**
+ * The workspace-provider counterpart of `ticketSourceRegistrationSchema`, with
+ * one deliberate tightening (AUT-516): a top-level `requiredEnv` key is
+ * rejected with a bespoke remediation message instead of the generic
+ * unrecognized-key complaint. The generic registration schema accepts the key
+ * today, but its only consumer is ticket-source construction — routing
+ * workspace-provider env requirements there would leave the declaration
+ * parsed and never checked, exactly the ignored-declaration failure mode this
+ * port's capabilities exist to eliminate. Required environment belongs on
+ * `capabilities.requiredEnv`, which carries the per-site messages a bare name
+ * list cannot.
+ */
+const workspaceProviderRegistrationSchema = z.unknown().transform((value, ctx) => {
+  if (typeof value === 'function') return value
+  if (value !== null && typeof value === 'object' && 'requiredEnv' in value) {
+    ctx.addIssue({
+      code: 'custom',
+      message:
+        'workspaceProviders.<name>.requiredEnv is not supported; declare required environment as workspaceProviders.<name>.capabilities.requiredEnv',
+    })
+    return z.NEVER
+  }
+  const parsed = workspaceProviderDescriptorSchema.safeParse(value)
+  if (parsed.success) return parsed.data
+  forwardIssues(parsed.error.issues, ctx)
+  return z.NEVER
+})
+
 /** Strict runtime contract for a plugin module's default export.
  *
  * `.optional()` stays outermost, so an undeclared port remains `undefined`
@@ -221,7 +390,11 @@ export const pluginManifestSchema = z.strictObject({
   apiVersion: nonblank,
   ticketSources: openMap('ticketSources', ticketSourceRegistrationSchema, ADAPTER_MAP).optional(),
   agentRuntimes: registrationMap('agentRuntimes').optional(),
-  workspaceProviders: registrationMap('workspaceProviders').optional(),
+  workspaceProviders: openMap(
+    'workspaceProviders',
+    workspaceProviderRegistrationSchema,
+    ADAPTER_MAP,
+  ).optional(),
   forges: registrationMap('forges').optional(),
 })
 

package/packages/core/src/plugins/registry.ts

@@ -12,6 +12,23 @@ import type { AgentRunnerContractFactory } from '../ports/runner/contract'
 import type { TicketSourceContractFactory } from '../ports/tickets/contract'
 import type { WorkspaceProviderContractFactory } from '../ports/workspace/contract'
 import type { ForgeContractFactory } from '../ports/forge/contract'
+import type { WorkspaceConfig } from '../config/schema'
+import type { CreateWorkspaceProviderOptions } from '../ports/workspace/create'
+import type { WorkspaceProviderCapabilities } from '../ports/workspace/provider-capabilities'
+import type { WorkspaceProvider } from '../ports/types'
+import {
+  builtinWorkspaceProviderNames,
+  builtinWorkspaceProviderRegistration,
+} from '../ports/workspace/builtin-capabilities'
+
+/** Host-owned construction closure for a builtin workspace provider. `parsed`
+ * is the declared `configSchema`'s parse output, or the raw
+ * `[workspace.config]` when no schema is declared. */
+export type BuiltinWorkspaceProviderFactory = (
+  config: WorkspaceConfig,
+  opts: CreateWorkspaceProviderOptions,
+  parsed: unknown,
+) => WorkspaceProvider | Promise<WorkspaceProvider>
 
 export type PluginPort = 'ticket-source' | 'agent-runtime' | 'workspace-provider' | 'forge'
 
@@ -49,6 +66,14 @@ export interface AdapterRegistration<Factory, ContractFactory = unknown> {
    * builtins and every other plugin port. */
   requiredEnv?: readonly string[]
   contract?: PluginContractDescriptor<ContractFactory>
+  /** Workspace-provider capability declarations (AUT-516). Attached to the
+   * builtin registrations and normalized from plugin descriptors; every other
+   * port leaves it undefined. */
+  capabilities?: WorkspaceProviderCapabilities
+  /** Builtin workspace providers construct their host-owned adapters through
+   * this closure (`createWorkspaceProvider` calls it after the uniform
+   * capability checks); plugins keep `factory`. */
+  builtinFactory?: BuiltinWorkspaceProviderFactory
   source: RegistrationSource
 }
 
@@ -92,6 +117,7 @@ interface PendingRegistration {
   factory: unknown
   requiredEnv?: readonly string[]
   contract?: PluginContractDescriptor<unknown>
+  capabilities?: WorkspaceProviderCapabilities
   target: Map<string, AdapterRegistration<unknown, unknown>>
 }
 
@@ -101,6 +127,7 @@ type InternalRegistration<AdapterFactory, ContractFactory> =
       factory: AdapterFactory
       requiredEnv?: readonly string[]
       contract?: PluginContractDescriptor<ContractFactory>
+      capabilities?: WorkspaceProviderCapabilities
     }
 
 function normalize<AdapterFactory, ContractFactory>(
@@ -109,6 +136,7 @@ function normalize<AdapterFactory, ContractFactory>(
   factory: AdapterFactory
   requiredEnv?: readonly string[]
   contract?: PluginContractDescriptor<ContractFactory>
+  capabilities?: WorkspaceProviderCapabilities
 } {
   if (typeof registration === 'function') {
     return { factory: registration as AdapterFactory }
@@ -117,11 +145,13 @@ function normalize<AdapterFactory, ContractFactory>(
     factory: AdapterFactory
     requiredEnv?: readonly string[]
     contract?: PluginContractDescriptor<ContractFactory>
+    capabilities?: WorkspaceProviderCapabilities
   }
   return {
     factory: object.factory,
     ...(object.requiredEnv !== undefined ? { requiredEnv: [...object.requiredEnv] } : {}),
     ...(object.contract !== undefined ? { contract: object.contract } : {}),
+    ...(object.capabilities !== undefined ? { capabilities: object.capabilities } : {}),
   }
 }
 
@@ -141,10 +171,29 @@ export class PluginRegistry {
     // profile value, so a runtime with the same name could never be selected.
     'split',
   ])
-  readonly workspaceProviders = reserved<
-    WorkspaceProviderPluginFactory,
-    WorkspaceProviderContractFactory
-  >(['git-worktree', 'vercel-sandbox'])
+  // Builtin workspace-provider names are derived from the canonical builtin
+  // list in builtin-capabilities.ts (AUT-579), so a builtin added there
+  // registers here automatically — no registry edit is needed.
+  readonly workspaceProviders = new Map<
+    string,
+    AdapterRegistration<WorkspaceProviderPluginFactory, WorkspaceProviderContractFactory>
+  >(
+    builtinWorkspaceProviderNames().map((name) => {
+      const builtin = builtinWorkspaceProviderRegistration(name)
+      if (builtin === undefined) {
+        throw new Error(`builtin workspace provider "${name}" has no capability declaration`)
+      }
+      return [
+        name,
+        {
+          owner: BUILTIN,
+          source: { kind: 'builtin' } as const,
+          capabilities: builtin.capabilities,
+          builtinFactory: builtin.builtinFactory,
+        },
+      ]
+    }),
+  )
   readonly forges = reserved<ForgePluginFactory, ForgeContractFactory>(['github', 'local-git'])
 
   register(
@@ -184,6 +233,9 @@ export class PluginRegistry {
           ...(normalized.contract !== undefined
             ? { contract: normalized.contract as PluginContractDescriptor<unknown> }
             : {}),
+          ...(normalized.capabilities !== undefined
+            ? { capabilities: normalized.capabilities }
+            : {}),
           target: target as Map<string, AdapterRegistration<unknown, unknown>>,
         })
       }
@@ -223,6 +275,9 @@ export class PluginRegistry {
           ? { requiredEnv: registration.requiredEnv }
           : {}),
         ...(registration.contract !== undefined ? { contract: registration.contract } : {}),
+        ...(registration.capabilities !== undefined
+          ? { capabilities: registration.capabilities }
+          : {}),
         source,
       })
     }
@@ -267,6 +322,20 @@ export class PluginRegistry {
         return this.forges.get(name)
     }
   }
+
+  /** Workspace-provider names a manifest declares that currently belong to a
+   * BUILTIN registration (AUT-517). Names owned by another plugin are not
+   * reported — those collisions throw as always. The loader uses this for
+   * the transitional duplicate-skip: while the builtin hosts the
+   * vercel-sandbox implementation, a configured plugin re-registering the
+   * name is skipped instead of failing startup. Keyed on builtin ownership,
+   * so the rule retires itself when the builtin is removed (AUT-505). */
+  builtinWorkspaceProviderCollisions(manifest: AutobuildPluginManifest): string[] {
+    return Object.keys(manifest.workspaceProviders ?? {}).filter((name) => {
+      const existing = this.workspaceProviders.get(name)
+      return existing !== undefined && existing.owner.kind === 'builtin'
+    })
+  }
 }
 
 export function createPluginRegistry(): PluginRegistry {

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

@@ -47,7 +47,7 @@ export async function createForge(opts: {
         ...(opts.repository !== undefined ? { repository: opts.repository } : {}),
       })
     }
-    if (opts.name === 'local-git') return new LocalGitForge()
+    if (opts.name === 'local-git') return new LocalGitForge({ repoRoot: opts.repoRoot })
     throw new Error(`builtin forge adapter ${JSON.stringify(opts.name)} has no constructor`)
   }
 

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

@@ -83,6 +83,13 @@ export class FakeForge implements Forge {
   readonly name = 'fake'
   readonly prAttachments?: PrAttachmentHosting
 
+  /** Optional checkout-less read seam (SPEC §16.1 pipeline pinning): seeded
+   * remote branches (`branch` → sha) and file contents keyed `ref\0path`.
+   * `remoteBranchSha` throws when the branch was never seeded — the same
+   * not-found contract as the production adapters. */
+  readonly remoteBranches = new Map<string, string>()
+  readonly files = new Map<string, string>()
+
   /** Journals — public so tests assert directly on call order and args. */
   readonly pushes: PushRecord[] = []
   readonly opened: OpenPrRecord[] = []
@@ -330,6 +337,30 @@ export class FakeForge implements Forge {
     return this.autoMerge.get(number) ?? false
   }
 
+  /** Seed a remote branch head for the optional checkout-less read seam. */
+  seedBranch(branch: string, sha: string): void {
+    this.remoteBranches.set(branch, sha)
+  }
+
+  /** Seed file content readable at a given ref (sha or branch name). */
+  seedFile(ref: string, path: string, content: string): void {
+    this.files.set(`${ref}\0${path}`, content)
+  }
+
+  async remoteBranchSha(branch: string): Promise<string> {
+    const sha = this.remoteBranches.get(branch)
+    if (sha === undefined) throw new Error(`FakeForge: unknown remote branch ${branch}`)
+    return sha
+  }
+
+  async readFile(path: string, ref?: string): Promise<string> {
+    const key = `${ref ?? 'default'}\0${path}`
+    const content = this.files.get(key)
+    if (content === undefined)
+      throw new Error(`FakeForge: no file ${path} at ref ${ref ?? 'default'}`)
+    return content
+  }
+
   async pushBranch(workspacePath: string, branch: string): Promise<void> {
     this.pushes.push({ workspacePath, branch })
     this.publishedBranches.add(branch)