@defrex/autobuild 0.8.0

package/packages/core/src/cli/mcp.ts

@@ -0,0 +1,279 @@
+/**
+ * `ab mcp` — the first binding of the agent tool registry (AUT-338): the
+ * registry served as an MCP server over stdio, using the official MCP
+ * TypeScript SDK's current major.
+ *
+ * The CLI remains the primary local interface for agents that have a shell.
+ * The stdio binding exists so the registry can be exercised end to end from a
+ * local install, for dogfooding, and for local agents that cannot run
+ * commands. Every tool is registered from the registry's closed table — name,
+ * description, JSON-schema input, annotations, handler — so this surface can
+ * never drift from the in-process registry the contract suite proves.
+ *
+ * Identity: the sessionless operator identity the other operator commands use
+ * (`buildControlUser` — USER/USERNAME, else "dashboard"), with a via marker
+ * naming the connected MCP client (learned lazily at the initialize handshake).
+ * The server fails closed inside a phase: repository-wide operator authority
+ * cannot be narrowed to the ambient build (the §8.2 rule that makes
+ * repository-wide `ab builds` fail inside a phase, moved to process start
+ * because a server cannot scope per request).
+ */
+import { join } from 'node:path'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { loadConfig } from '../config/load'
+import type { Config } from '../config/schema'
+import type { Via } from '../events/envelope'
+import { defaultTriageState } from '../processes/dispatcher'
+import { createWorkspaceProvider } from '../ports/workspace/create'
+import { createTicketSource } from '../ports/tickets/create'
+import { loadPlugins } from '../plugins/load'
+import { AUTOBUILD_VERSION } from '../store/remote/version'
+import type { Clock } from '../store/types'
+import { buildControlUser } from './build-control'
+import type { Exec } from '../ports/workspace/git-worktree'
+import { openSessionlessStore, type StoreOpener } from './store-opening'
+import { InvalidAmbientContextError, resolveAmbientReadSession } from './env'
+import { buildRegistry, RegistryError, type OperatorToolRegistry } from '../operator/registry'
+import { createOperatorSandboxService, type OperatorSandboxService } from '../operator/sandbox'
+import type { OperatorTicketBackend } from '../operator/tickets'
+
+export const AB_MCP_USAGE = 'usage: ab mcp [--store <ref>] [--repo <id>] (§8.2)'
+
+export const AB_MCP_PHASE_REFUSAL =
+  'ab mcp serves repository-wide operator authority and cannot run inside a phase session (§8.2)'
+
+const SERVER_INSTRUCTIONS = [
+  'Autobuild operator tools for one repository: builds, repository and harvest controls, tickets, and operator notes.',
+  'The `ab` CLI is the primary local interface for agents that have a shell; these tools mirror its operator commands',
+  'and the operator API routes — every result equals the corresponding route. Prefer the CLI when a command exists;',
+  'use these tools when no shell is available, for dogfooding, and for parity testing of the tool registry.',
+  'Every tool names its repository explicitly via `repo`; mutating tools append durable, human-attributed events.',
+].join(' ')
+
+export interface AbMcpOpts {
+  targetRepo: string
+  env: Record<string, string | undefined>
+  exec: Exec
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  /** Explicit --store; selection remains --store > AB_STORE > repo-local. */
+  storeRef?: string
+  /** Explicit --repo: refuse calls targeting any other repository. */
+  repo?: string
+  /** Injectable adapter seam for tests; production composes the real adapter. */
+  openStore?: StoreOpener
+  /** Injectable ticket-source factory for tests. */
+  ticketSourceFactory?: typeof createTicketSource
+  clock?: Clock
+}
+
+/**
+ * The operator ticket backend for the stdio binding: one TicketSource built
+ * once from the checkout's own `[tickets]` config. `statesFor` returns the
+ * configured lifecycle names; `sourceFor` cross-checks the effective
+ * config's teamKey against this startup config and refuses on drift.
+ */
+export async function buildMcpTicketBackend(
+  opts: AbMcpOpts & { checkout: string; localStateRoot: string },
+): Promise<OperatorTicketBackend> {
+  const configPath = join(opts.checkout, 'autobuild.toml')
+  let config: Config
+  try {
+    config = await loadConfig(configPath)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(
+        `${configPath}: not found — 'ab mcp' reads autobuild.toml from the resolved Git main checkout (SPEC §8.8)`,
+      )
+    }
+    throw error
+  }
+  const plugins = await loadPlugins(config.plugins, opts.checkout)
+  const factory = opts.ticketSourceFactory ?? createTicketSource
+  const source = await factory(
+    config.tickets,
+    opts.env,
+    opts.checkout,
+    opts.localStateRoot,
+    plugins,
+  )
+  const states = [
+    ...new Set(
+      [
+        defaultTriageState(config),
+        config.tickets.readyState,
+        config.tickets.claimedState,
+        config.tickets.createState,
+      ].filter((state): state is string => state !== undefined),
+    ),
+  ]
+  return {
+    sourceFor: async (context) => {
+      if (config.tickets.teamKey !== context.teamKey) {
+        throw new Error(
+          `the repository's effective ticket config names team "${context.teamKey}", but this checkout's autobuild.toml names team "${String(config.tickets.teamKey)}"; refusing to serve tickets across that drift — run ab mcp from the checkout dispatch uses`,
+        )
+      }
+      return source
+    },
+    statesFor: async () => states,
+  }
+}
+
+/**
+ * Map every registry entry onto the MCP server: name, description (with the
+ * output description appended), input schema, annotations, and a handler that
+ * routes through registry.call so validation, identity enforcement, and
+ * failure-body mapping stay identical across bindings. Successes and failures
+ * both surface as JSON text content; failures additionally carry isError.
+ */
+export function serveRegistry(
+  registry: OperatorToolRegistry,
+  server: McpServer,
+  ctx: { identity?: string; via?: Via | (() => Via | undefined) },
+): void {
+  for (const entry of registry.entries) {
+    server.registerTool(
+      entry.name,
+      {
+        description: `${entry.description}\n\nReturns: ${entry.outputDescription}`,
+        inputSchema: entry.inputSchema,
+        annotations: entry.annotations,
+      },
+      // The SDK validates args against the entry's schema before this runs;
+      // registry.call re-validates so every binding shares one enforcement
+      // path.
+      async (args: unknown) => {
+        try {
+          // A lazy via resolves per call — the stdio server is long-lived and
+          // only learns the client's identity at the initialize handshake.
+          const via = typeof ctx.via === 'function' ? ctx.via() : ctx.via
+          const value = await registry.call(entry.name, args, {
+            identity: ctx.identity,
+            ...(via !== undefined ? { via } : {}),
+          })
+          return { content: [{ type: 'text' as const, text: JSON.stringify(value) }] }
+        } catch (error) {
+          const body =
+            error instanceof RegistryError
+              ? error.body
+              : { kind: 'internal' as const, error: 'operator tool is unavailable' }
+          return {
+            content: [{ type: 'text' as const, text: JSON.stringify(body) }],
+            isError: true,
+          }
+        }
+      },
+    )
+  }
+}
+
+/** The `ab mcp` command core. Returns the process exit code. */
+export async function abMcp(opts: AbMcpOpts): Promise<number> {
+  // Fail closed before any store open: a complete ambient tuple (or a
+  // malformed one) must not start a repository-wide server.
+  let ambient: unknown
+  try {
+    ambient = resolveAmbientReadSession(opts.env)
+  } catch (error) {
+    if (error instanceof InvalidAmbientContextError) {
+      opts.stderr(`${AB_MCP_PHASE_REFUSAL} ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+  if (ambient !== undefined) {
+    opts.stderr(AB_MCP_PHASE_REFUSAL)
+    return 1
+  }
+
+  const context = await openSessionlessStore({
+    targetRepo: opts.targetRepo,
+    env: opts.env,
+    exec: opts.exec,
+    ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
+    ...(opts.openStore !== undefined ? { openStore: opts.openStore } : {}),
+  })
+  try {
+    const backend = await buildMcpTicketBackend({
+      ...opts,
+      checkout: context.checkout,
+      localStateRoot: context.localStateRoot,
+    })
+    // The operator-sandbox backend (AUT-340) is built only when the
+    // repository enables it. A construction failure is contained: the
+    // server still serves every other tool, one diagnostic names the
+    // failure, and the sandbox tools are absent from advertisement AND
+    // dispatch (never broken).
+    let sandbox: OperatorSandboxService | undefined
+    try {
+      const configPath = join(context.checkout, 'autobuild.toml')
+      let mcpConfig: Config
+      try {
+        mcpConfig = await loadConfig(configPath)
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+          throw new Error(
+            `${configPath}: not found — 'ab mcp' reads autobuild.toml from the resolved Git main checkout (SPEC §8.8)`,
+          )
+        }
+        throw error
+      }
+      if (mcpConfig.orchestrator.enabled) {
+        const provider = await createWorkspaceProvider(mcpConfig.workspace, {
+          registry: await loadPlugins(mcpConfig.plugins, context.checkout),
+          worktreeRoot: context.worktreeRoot,
+          repoRoot: context.checkout,
+          env: opts.env,
+          storeRef: context.storeRef,
+          ...(context.token !== undefined ? { storeToken: context.token } : {}),
+          sandboxSetupCommand: mcpConfig.commands.setup,
+          sandboxRoot: join(context.localStateRoot, 'orchestrator-sandboxes'),
+          sandboxEnvironmentVariables: mcpConfig.orchestrator.sandbox.environmentVariables,
+        })
+        sandbox = await createOperatorSandboxService({
+          store: context.store,
+          repo: context.repo,
+          provider,
+          sandbox: mcpConfig.orchestrator.sandbox,
+          baseBranch: mcpConfig.baseBranch,
+          ...(opts.clock !== undefined ? { clock: opts.clock } : {}),
+        })
+      }
+    } catch (error) {
+      opts.stderr(
+        `ab mcp: operator sandbox backend unavailable, sandbox tools omitted: ${error instanceof Error ? error.message : String(error)}`,
+      )
+      sandbox = undefined
+    }
+    const registry = buildRegistry({
+      store: context.store,
+      tickets: backend,
+      ...(sandbox !== undefined ? { sandbox } : {}),
+      clock: opts.clock,
+      ...(opts.repo !== undefined ? { allowedRepo: opts.repo } : {}),
+    })
+
+    const server = new McpServer(
+      { name: 'autobuild', version: AUTOBUILD_VERSION },
+      { instructions: SERVER_INSTRUCTIONS },
+    )
+    serveRegistry(registry, server, {
+      identity: buildControlUser(opts.env),
+      // Unlike the hosted stateless server, the stdio server is long-lived:
+      // the initialize handshake populates the client version before any tool
+      // call, so the via marker names the connected client.
+      via: () => ({ kind: 'mcp', client: server.server.getClientVersion()?.name ?? 'stdio' }),
+    })
+
+    const done = new Promise<void>((resolve) => {
+      server.server.onclose = () => resolve()
+    })
+    await server.connect(new StdioServerTransport())
+    await done
+    return 0
+  } finally {
+    await context.store.close()
+  }
+}

package/packages/core/src/cli/models.ts

@@ -0,0 +1,65 @@
+/** `ab models` lists the catalog resolved by the operator's local Pi CLI. */
+import { checkLocalPi } from '../ports/runner/pi'
+import { readLocalPiCatalog } from '../ports/runner/pi-rpc'
+
+/** One catalog entry — a provider-qualified id, split for display. */
+export interface PiCatalogEntry {
+  provider: string
+  id: string
+}
+
+/**
+ * Fetch Pi's model catalog. `availableOnly` narrows to models whose provider
+ * credentials are configured (a network/credential check); otherwise the full
+ * offline catalog is returned.
+ */
+export type PiModelCatalogFn = (opts: { availableOnly: boolean }) => Promise<PiCatalogEntry[]>
+
+const defaultCatalog: PiModelCatalogFn = async ({ availableOnly }) => {
+  const env = Object.fromEntries(
+    Object.entries(process.env).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  )
+  await checkLocalPi(process.cwd(), env)
+  return readLocalPiCatalog({ cwd: process.cwd(), env, availableOnly })
+}
+
+export interface AbModelsOptions {
+  /** Case-insensitive substring over `provider/id`; absent ⇒ list everything. */
+  query?: string
+  /** Restrict to models with configured credentials. */
+  availableOnly: boolean
+  stdout: (line: string) => void
+  /** Injectable for tests; defaults to the local Pi CLI catalog. */
+  catalog?: PiModelCatalogFn
+}
+
+export async function abModels(opts: AbModelsOptions): Promise<void> {
+  const catalog = opts.catalog ?? defaultCatalog
+  const entries = await catalog({ availableOnly: opts.availableOnly })
+
+  const needle = opts.query?.toLowerCase()
+  const matched = (
+    needle === undefined
+      ? entries
+      : entries.filter((e) => `${e.provider}/${e.id}`.toLowerCase().includes(needle))
+  ).sort((a, b) => `${a.provider}/${a.id}`.localeCompare(`${b.provider}/${b.id}`))
+
+  if (matched.length === 0) {
+    opts.stdout(
+      opts.query !== undefined
+        ? `no Pi models match "${opts.query}"${opts.availableOnly ? ' with configured credentials' : ''}`
+        : 'no Pi models found',
+    )
+    return
+  }
+
+  for (const e of matched) {
+    opts.stdout(`${e.provider}/${e.id}`)
+  }
+  opts.stdout('')
+  opts.stdout(
+    `${matched.length} model(s) — paste a provider-qualified id into autobuild.toml [roles.default] or a concrete [roles.<name>] entry.`,
+  )
+}

package/packages/core/src/cli/observe.ts

@@ -0,0 +1,55 @@
+/**
+ * `ab observe` (SPEC §8.2, §12): structured observations at the point of
+ * capture — followup | refactor | latent-bug, with file/ticket refs — so
+ * `harvest` clusters records, not prose mined from a markdown file.
+ *
+ * NOT a terminal: usable in any phase, at any time, any number of times.
+ * The id is kernel-assigned at deposit, like all ids (§15.4).
+ */
+import type { EventEnvelope } from '../events/catalog'
+import { agentActor } from '../events/envelope'
+import type { IdSource } from '../ids'
+import { observationKindSchema } from '../ontology'
+import type { BuildStore } from '../store/types'
+import type { CliEnv } from './env'
+
+export interface ObserveDeps {
+  store: BuildStore
+  env: CliEnv
+  ids: IdSource
+}
+
+export interface ObserveOpts {
+  kind: string
+  summary: string
+  files?: string[]
+  refs?: string[]
+}
+
+export async function observe(
+  deps: ObserveDeps,
+  opts: ObserveOpts,
+): Promise<EventEnvelope<'observation.recorded'>> {
+  const kind = observationKindSchema.safeParse(opts.kind)
+  if (!kind.success) {
+    throw new Error(
+      `--kind "${opts.kind}" is not an observation kind — expected ` +
+        'followup | refactor | latent-bug (§8.2)',
+    )
+  }
+  if (opts.summary.trim() === '') {
+    throw new Error("'ab observe' requires a non-empty <summary> (§8.2)")
+  }
+  const { env } = deps
+  return deps.store.append(env.build, {
+    actor: agentActor(env.phase, env.session),
+    type: 'observation.recorded',
+    payload: {
+      id: deps.ids('obs'),
+      kind: kind.data,
+      summary: opts.summary,
+      ...(opts.files !== undefined && opts.files.length > 0 ? { files: opts.files } : {}),
+      ...(opts.refs !== undefined && opts.refs.length > 0 ? { refs: opts.refs } : {}),
+    },
+  })
+}

package/packages/core/src/cli/plugin.ts

@@ -0,0 +1,227 @@
+import { join } from 'node:path'
+import { loadConfig } from '../config/load'
+import { CONTRACT_ADAPTER_ENV, CONTRACT_PORT_ENV, CONTRACT_REPO_ENV } from '../plugins/contract-env'
+import { diagnosePlugins, type PluginDiagnosis } from '../plugins/load'
+import {
+  PLUGIN_PORTS,
+  pluginPortLabel,
+  type AdapterProjection,
+  type PluginPort,
+} from '../plugins/registry'
+import type { Exec } from '../ports/workspace/git-worktree'
+import { resolveMainRepo } from './repo-state'
+
+export interface PluginContractProcessInput {
+  repoRoot: string
+  port: PluginPort
+  adapter: string
+  env: Record<string, string | undefined>
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+}
+
+export type PluginContractSubprocess = (input: PluginContractProcessInput) => Promise<number>
+
+export interface PluginCliOpts {
+  targetRepo: string
+  env: Record<string, string | undefined>
+  exec: Exec
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  subprocess?: PluginContractSubprocess
+}
+
+function definedEnv(env: Record<string, string | undefined>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  )
+}
+
+function forwardText(text: string, sink: (line: string) => void): void {
+  const normalized = text.endsWith('\n') ? text.slice(0, -1) : text
+  if (normalized === '') return
+  for (const line of normalized.split('\n')) sink(line)
+}
+
+export const spawnPluginContract: PluginContractSubprocess = async (input) => {
+  const entry = join(import.meta.dir, '..', 'plugins', 'contract-entry.ts')
+  // Use the current Bun executable by absolute path: the plugin's declared
+  // environment may intentionally omit PATH, but contract execution must not
+  // depend on executable lookup inside that replacement environment.
+  const child = Bun.spawn([process.execPath, 'test', entry], {
+    cwd: input.repoRoot,
+    env: {
+      ...definedEnv(input.env),
+      [CONTRACT_REPO_ENV]: input.repoRoot,
+      [CONTRACT_PORT_ENV]: input.port,
+      [CONTRACT_ADAPTER_ENV]: input.adapter,
+    },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [stdout, stderr, status] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  forwardText(stdout, input.stdout)
+  forwardText(stderr, input.stderr)
+  return status
+}
+
+function renderModuleReport(report: PluginDiagnosis['reports'][number]): string {
+  const location = report.resolved === undefined ? '' : ` resolved=${report.resolved}`
+  const source = report.resolvedFrom === undefined ? '' : ` from=${report.resolvedFrom}`
+  const plugin = report.pluginName === undefined ? '' : ` plugin=${report.pluginName}`
+  const api =
+    report.api === undefined
+      ? ''
+      : ` api=${report.api.declaredRange} host=${report.api.hostVersion} ${report.api.status}`
+  return report.status === 'loaded'
+    ? `OK ${report.module} kind=${report.resolutionKind}${location}${source}${plugin}${api}`
+    : `FAIL ${report.module} kind=${report.resolutionKind} stage=${report.stage}${location}${source}${plugin}${api}: ${report.error}`
+}
+
+function renderAdapter(adapter: AdapterProjection): string {
+  const contract = adapter.hasContract
+    ? adapter.live
+      ? 'contract=live'
+      : 'contract=available'
+    : 'contract=missing'
+  if (adapter.source.kind === 'builtin') {
+    return `  ${adapter.name} owner=builtin module=(builtin) resolution=builtin api=host-compatible ${contract}`
+  }
+  const { source } = adapter
+  return (
+    `  ${adapter.name} owner=plugin:${source.pluginName} module=${source.module} ` +
+    `resolution=${source.resolutionKind} resolved=${source.resolved} ` +
+    `api=${source.api.declaredRange} host=${source.api.hostVersion} ${source.api.status} ${contract}`
+  )
+}
+
+function contractField(port: PluginPort, adapter: string): string {
+  const map: Record<PluginPort, string> = {
+    'ticket-source': 'ticketSources',
+    'agent-runtime': 'agentRuntimes',
+    'workspace-provider': 'workspaceProviders',
+    forge: 'forges',
+  }
+  return `${map[port]}.${adapter}.contract.factory`
+}
+
+async function loadDiagnosis(opts: PluginCliOpts): Promise<{
+  repoRoot: string
+  diagnosis: PluginDiagnosis
+}> {
+  const repoRoot = await resolveMainRepo(opts.targetRepo, opts.exec)
+  const configPath = join(repoRoot, 'autobuild.toml')
+  let config: Awaited<ReturnType<typeof loadConfig>>
+  try {
+    config = await loadConfig(configPath)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(
+        `${configPath}: not found — 'ab plugin' reads autobuild.toml from the resolved Git main checkout`,
+      )
+    }
+    throw error
+  }
+  return {
+    repoRoot,
+    diagnosis: await diagnosePlugins(config.plugins, repoRoot),
+  }
+}
+
+function parsePort(value: string): PluginPort {
+  if (!PLUGIN_PORTS.includes(value as PluginPort)) {
+    throw new Error(`unknown plugin port "${value}" — expected one of: ${PLUGIN_PORTS.join(', ')}`)
+  }
+  return value as PluginPort
+}
+
+/** Sessionless `ab plugin` operator/authoring namespace. */
+export async function abPlugin(argv: readonly string[], opts: PluginCliOpts): Promise<number> {
+  const [command, ...rest] = argv
+  if (command === 'list') {
+    if (rest.length !== 0) throw new Error('usage: ab plugin list')
+    const { diagnosis } = await loadDiagnosis(opts)
+    opts.stdout('configured modules:')
+    if (diagnosis.reports.length === 0) opts.stdout('  (none)')
+    for (const report of diagnosis.reports) {
+      const line = `  ${renderModuleReport(report)}`
+      if (report.status === 'loaded') opts.stdout(line)
+      else opts.stderr(line)
+    }
+    opts.stdout('adapters:')
+    for (const port of PLUGIN_PORTS) {
+      opts.stdout(`${port}:`)
+      for (const adapter of diagnosis.registry.adapters(port)) {
+        opts.stdout(renderAdapter(adapter))
+      }
+    }
+    return diagnosis.healthy ? 0 : 1
+  }
+
+  if (command === 'doctor') {
+    if (rest.length !== 0) throw new Error('usage: ab plugin doctor')
+    const { diagnosis } = await loadDiagnosis(opts)
+    if (diagnosis.reports.length === 0) {
+      opts.stdout('No configured plugin modules.')
+    }
+    for (const report of diagnosis.reports) {
+      const line = renderModuleReport(report)
+      if (report.status === 'loaded') opts.stdout(line)
+      else opts.stderr(line)
+    }
+    return diagnosis.healthy ? 0 : 1
+  }
+
+  if (command === 'test') {
+    if (rest.length !== 2) {
+      throw new Error(
+        'usage: ab plugin test <ticket-source|agent-runtime|workspace-provider|forge> <adapter>',
+      )
+    }
+    const port = parsePort(rest[0]!)
+    const adapter = rest[1]!
+    const { repoRoot, diagnosis } = await loadDiagnosis(opts)
+    if (!diagnosis.healthy) {
+      for (const report of diagnosis.reports) {
+        if (report.status === 'failed') opts.stderr(renderModuleReport(report))
+      }
+      return 1
+    }
+    const registration = diagnosis.registry.registration(port, adapter)
+    if (registration === undefined) {
+      const names = diagnosis.registry.adapters(port).map((entry) => entry.name)
+      throw new Error(
+        `unknown ${pluginPortLabel(port)} adapter "${adapter}" — configured adapters: ${names.join(', ') || '(none)'}`,
+      )
+    }
+    if (registration.contract === undefined) {
+      throw new Error(
+        `${pluginPortLabel(port)} adapter "${adapter}" cannot be contract-tested: ` +
+          `its manifest does not provide ${contractField(port, adapter)}. ` +
+          'Register the adapter as { factory, contract: { factory } } where the contract factory returns the shared suite harness factory.',
+      )
+    }
+    if (registration.contract.live === true && opts.env.AB_RUN_LIVE_PORT_CONTRACTS !== '1') {
+      throw new Error(
+        `${pluginPortLabel(port)} adapter "${adapter}" declares a live contract; ` +
+          'set AB_RUN_LIVE_PORT_CONTRACTS=1 to explicitly allow external side effects',
+      )
+    }
+    return await (opts.subprocess ?? spawnPluginContract)({
+      repoRoot,
+      port,
+      adapter,
+      env: opts.env,
+      stdout: opts.stdout,
+      stderr: opts.stderr,
+    })
+  }
+
+  throw new Error(
+    'usage: ab plugin <list|doctor|test> — test requires <ticket-source|agent-runtime|workspace-provider|forge> <adapter>',
+  )
+}