@defrex/autobuild 0.8.0 → 0.9.0

package/docs/architecture.md

@@ -54,7 +54,15 @@ Git installation never requires a separately published core package.
 `packages/core` owns the CLI, kernel, adapters, shared types, dashboard
 projection, plugin SDK, and reusable contract suites. The optional
 `packages/hosted-store-service` workspace composes the public remote-server
-surface with `packages/postgres-store`; neither package enters an ordinary CLI
+surface with `packages/postgres-store`; the separate optional
+`packages/hosted-dispatcher` workspace owns the cron-driven hosted dispatcher
+(the `/api/dispatch` route driver, the deploy-time `pack-distribution` command,
+and the packed-distribution trace helper) and peers on both the core and the
+store service. The optional `packages/vercel-sandbox` workspace publishes the
+`@defrex/autobuild-vercel-sandbox` provider plugin (AUT-517): while the
+builtin hosts the implementation, its manifest re-registers the provider name
+over the shared capability object and the loader skips it with a notice.
+Neither optional package enters an ordinary CLI
 installation's runtime dependency closure. `tools/` is repository-only
 maintainer tooling. All workspace manifests share one version because the
 remote-store protocol requires matching client and server versions.
@@ -68,16 +76,19 @@ remote-store protocol requires matching client and server versions.
 | `packages/core/src/ontology.ts` | The shared nouns — findings, verdicts, phases, refs, the canonical verify outcome | §4 |
 | `packages/core/src/events/` | Separate build, repository, and operator-session envelopes/catalogs, frozen payload schemas, actor validation, the `via` attribution marker | §15 |
 | `packages/core/src/harvest/` | Structured occurrence, scan packet, proposal, and ledger schemas | §12 |
-| `packages/core/src/sessions/` | The operator-session reducer: status, open turn, pending approval, wake settings and cursors, and the turn list, reduced purely from the session event log | §7.1.1 |
+| `packages/core/src/store/session-reducer.ts` | The operator-session reducer: status, open turn, pending approval, wake settings and cursors, and the turn list, reduced purely from the session event log | §7.1.1 |
+| `packages/core/src/orchestrator/` | The embedded orchestrator's turn runner: the canonical-skill system prompt, durable conversation reconstruction, registry entries as AI SDK tools with the session's repository injected, gateway model resolution with the typed failure vocabulary, the approval-list configuration, and the CAS-guarded start/resume loop with budget suspension and step-boundary checkpoints | §7.1.2 |
 | `packages/core/src/store/` | BuildStore contract spanning builds, the repository journal, and operator sessions; interface-enforced build, operator-session, and local ambient-session scope wrappers; memory, SQLite/blob, and remote HTTP adapters | §7 |
 | `packages/core/src/store/streams/` | The stream primitive's shared core (§7.6): record/chunk types and the `ai-ui-message-stream/v1` constants, SDK-backed close-time `UIMessage[]` assembly, and the uniform bounded-wait read loop | §7.6 |
-| `packages/hosted-store-service/` | Environment-only hosted Fetch handler, lazy PostgreSQL/blob composition, offline token binary, tests, and deployment guide | §7.2, §18 |
-| `server.ts`, `vercel.json` | One host-neutral Bun listener used locally and by Vercel's Bun preset | §7.2 |
+| `packages/hosted-store-service/` | Environment-only hosted Fetch handler, lazy PostgreSQL/blob composition, offline token binary, the Next.js operator web app (`app/`, `server.ts`, `next.config.ts`, `vercel.json`), tests, and deployment guide | §7.2, §18 |
+| `packages/hosted-dispatcher/` | The optional cron-driven hosted dispatcher: endpoint driver, deploy-time `pack-distribution` binary, packed-distribution trace helper, tests, and operator guide | §7.2, §12, §18 |
+| `packages/vercel-sandbox/` | Published `@defrex/autobuild-vercel-sandbox` provider plugin: transitional manifest over the shared capability object with a guarded factory (implementation stays builtin-hosted until AUT-505) | §3.2.1 |
+| `packages/hosted-store-service/server.ts`, `packages/hosted-store-service/vercel.json` | One host-neutral Bun listener used locally and by Vercel's Bun preset | §7.2 |
 | `packages/core/src/kernel/` | Phase table, build reducer, engine; pure harvest, dispatcher-settings, dispatcher-status, and PR-attachment selectors; converge, stall detection, verify gating | §5, §7.5, §10, §12, §14, §15.4–15.5 |
 | `packages/core/src/ports/` | TicketSource / Workspace / Forge / AgentRunner / Telemetry interfaces, adapters, and fakes; registry-aware builtin/plugin construction; eager primary/alternate runtime routing and provider-failure classification under `ports/runner/` | §3.2, §9, §13 |
 | `packages/core/src/plugins/` | Strict versioned plugin manifests, dual-root repository/package Bun loading, owner-aware adapter registration, contract/credential metadata, and runtime-factory materialization | §3.2.1, §9 |
 | `packages/core/src/plugin-sdk/` | The sole supported `@defrex/autobuild/plugin-sdk` barrel: port/manifest types, contract suites, and reference fakes | §3.2.1 |
-| `packages/core/src/processes/` | build-runner and standalone child composition, durable execution config/diagnostics, dispatcher (+ janitor duty and harvest trigger), harvest deterministic core + runner | §3.3, §12, §15.7 |
+| `packages/core/src/processes/` | build-runner and standalone child composition, durable execution config/diagnostics, dispatcher (+ janitor duty, harvest trigger, and the last-step orchestrator resume/reap/wake pass, origin-mode-gated), orchestrator tick step, harvest deterministic core + runner | §3.3, §7.1.2, §12, §15.7 |
 | `packages/core/src/cli/` and `bin/` | The `ab` CLI — the only agent↔store channel — plus the shared presentation-only durable-progress projection, init/upgrade, the Store-only dispatch frontend, its private supervised kernel entry, and `bin/ab-build-runner.ts` (one child per build) | §8, §14, §16.3 |
 | `packages/core/src/cli/dashboard/` | `ab dispatch`'s fixed live frame: pure projection, renderer, poll cache, and deterministic image renderer | §14 |
 | `bin/agent/ab` | Private launcher placed first on agent-session `PATH`; delegates to the canonical `bin/ab.ts` | §8.1 |
@@ -92,10 +103,15 @@ remote-store protocol requires matching client and server versions.
 ## Key boundaries
 
 **Hosted store service.** `@defrex/autobuild/remote-store` is the supported protocol
-server/client/token export. The hosted workspace validates its environment,
+export for the remote store's client half, wire schemas, and token minting; the
+protocol servers (the remote BuildStore HTTP server, the operator API server,
+and the hosted ticket-source server) ship in
+`@defrex/autobuild-hosted-store-service`, which builds against core's
+`remote-store`, `operator`, and `hosted-tickets` subpaths only. The hosted
+workspace validates its environment,
 serves health without touching persistence, and lazily retains one
 `openPostgresBuildStoreFromEnv` promise per warm process. Its Fetch handler has
-no Vercel branch; root `server.ts` is the sole `Bun.serve()` composition point.
+no Vercel branch; the package's `server.ts` is the sole `Bun.serve()` composition point.
 The fixed 1 MiB decoded artifact policy is enforced before backing mutation.
 The `ab-hosted-store` binary signs admin or build/session tokens offline from
 `AB_STORE_SECRET`; the running service exposes no mint endpoint. Machine routes
@@ -110,7 +126,7 @@ and `packages/core/src/events/sessions.ts`
 are the frozen catalogs; every write passes `validateEventWrite` /
 `validateRepositoryEventWrite` / `validateSessionEventWrite`. `packages/core/src/kernel/reducer.ts` derives all build
 status; `packages/core/src/kernel/harvest.ts` and `packages/core/src/kernel/dispatch-settings.ts` reduce
-the repository journal independently of each other; `packages/core/src/sessions/reducer.ts` reduces an operator
+the repository journal independently of each other; `packages/core/src/store/session-reducer.ts` reduces an operator
 session's status, open turn, pending approval, and wake cursors from its own
 closed catalog. No decision anywhere
 consults a snapshot in place of the append-only log.
@@ -503,9 +519,16 @@ It follows one dispatch run's repository facts incrementally through
 `packages/core/src/kernel/dispatch-status.ts`, retaining only low-volume settings/Harvest
 facts for their replay reducers, validates/caches its effective-config artifact,
 and polls build streams independently while elapsed paints continue from cached
-intervals. The same polling path calls the canonical
-`scanUnclaimedObservations` BuildStore reduction for the header's current count
-and pairs it with the effective config's `policy.harvestThreshold`. That sample
+intervals. The same polling path samples the header's current count from build
+digests plus the repository journal — one journal read plus one repo-scoped
+digest read, plus a journal-record probe — paired with the effective config's
+`policy.harvestThreshold`. A journal record that does not yet exist reads as an
+empty journal: the sample, the operator query, the dispatcher's
+repository-wide journal reads (controls, settlement stages, and ready
+scans), and the operator sandbox service's journal reads all go through
+the same shared missing-record journal read (the AUT-524 helper in
+`packages/core/src/processes/harvest.ts`), which writes nothing (no
+`ensureRepo` from a display path). That sample
 is process-local presentation state: a failed refresh preserves the last
 successful value and adds a local diagnostic, while an initial failure delays
 the complete frame rather than inventing zero. No repository fact transports
@@ -579,8 +602,8 @@ bun typecheck     # tsc --noEmit
 For dashboard presentation work, run the repository-only hot CLI:
 
 ```sh
-bun run dev -- dispatch
-# Generic form: bun run dev -- <ab arguments>
+bun run dev:cli -- dispatch
+# Generic form: bun run dev:cli -- <ab arguments>
 ```
 
 Bun keeps the original CLI promise and its `DispatchLoop` alive while hot
@@ -596,7 +619,7 @@ installed `ab` binary remains the non-watching production entry.
 The seams are the contract. Five reusable contract families run the same
 behavioral assertions against every implementation:
 
-- `packages/core/src/store/contract.ts` — `BuildStore` and `BlobStore`, including the streams block (§7.6) every adapter runs;
+- `packages/core/src/store/contract.ts` — `BuildStore` and `BlobStore`, including the streams block (§7.6) and the ticket-asset block (§7.1.3) every adapter runs;
 - `packages/core/src/ports/tickets/contract.ts` — `TicketSource`;
 - `packages/core/src/ports/workspace/contract.ts` — `WorkspaceProvider`;
 - `packages/core/src/ports/forge/contract.ts` — `Forge`, including idempotent PR close and
@@ -618,6 +641,19 @@ A normal `bun test` runs the memory/fake/local registrations, including a fake
 selected through the plugin ticket-source registry, the real filesystem and
 local-git adapters, the injected Claude and Codex CLI subprocess contracts,
 and the injected Pi CLI/RPC contract.
+Ticket assets (SPEC §7.1.3) are files attached to a ticket and kept in the
+BuildStore, never in the ticket source. `packages/core/src/store/ticket-assets.ts`
+holds the types, the limits, and the one validator every adapter calls;
+`packages/core/src/cli/ticket-assets.ts` holds the filesystem walk, the download
+writer, and the note builder; `ab ticket attach`, `asset get`, and `asset rm`
+live in `packages/core/src/cli/ticket.ts`. The only thing a ticket source sees is
+a note through `comment()`, so no source or plugin protocol changed.
+A claim freezes the ticket's current assets into the build (SPEC §6.3):
+`build.created.assets` (and, when a spec is revised from the ticket,
+`spec.revised.assets`) record the pinned revisions, `state.pinnedAssets` in the
+reducer projects them, `getPinnedTicketAsset` reads them back by pinned revision,
+and `ab context` writes them under `.ab/assets/`.
+
 Both `ab dispatch` and sessionless `ab ticket` load the repository's plugins
 before selecting their TicketSource; dispatch passes that one adapter instance
 through readiness, dependency, harvest, and completion paths. The Linear,
@@ -626,6 +662,13 @@ but reported as skipped: live provider access requires credentials/resources
 and an explicit opt-in. When
 adding an adapter, start from its contract suite, not only the interface.
 
+The two remote clients get client-only unit coverage in core itself:
+`RemoteBuildStore` (`store/remote/client.test.ts`, which also pins scoped-token
+minting/verification) and `HostedTicketSource` (`ports/tickets/remote.test.ts`)
+run against an injected `fetchFn` with responses built from the protocol's wire
+schemas. The full over-the-wire seam suites (client → HTTP → server) run in
+`packages/hosted-store-service` in the same `bun test`.
+
 To run the Linear contract manually against a destructive scratch target:
 
 ```sh

package/docs/configuration.md

@@ -23,7 +23,11 @@ environment. They are published to npm as separate packages alongside the
 PostgreSQL, or blob-provider dependencies; a project that embeds the adapter
 or the service adds the package it needs (`bun add
 @defrex/autobuild-postgres-store` or `bun add
-@defrex/autobuild-hosted-store-service`). The deployable web application still
+@defrex/autobuild-hosted-store-service`). The cron-driven hosted dispatcher is
+separately published as `@defrex/autobuild-hosted-dispatcher`; a deployment
+opts into building by installing that package, and its `AB_DISPATCHER_*`
+variables are documented in the [hosted-dispatcher runbook](hosted-dispatcher.md),
+not here. The deployable web application still
 runs from a release checkout: choose the compatible tag shown in
 [GitHub Releases](https://github.com/defrex/autobuild/releases), clone that exact
 revision into a dedicated checkout, and run the idempotent migration there:
@@ -37,7 +41,9 @@ DATABASE_URL=postgres://… bun run postgres:migrate
 
 Replace `v0.6.0` with the selected release tag. Schema diagnostics' root
 `postgres:migrate` script is relative to that pinned checkout. A hosted build
-can run the same step itself: `bun run deploy:build` migrates against the
+can run the same step itself: `bun run deploy:build` — run from the hosted
+store service package directory (`packages/hosted-store-service`), the Next.js
+project directory — migrates against the
 deployment's database URL, logs the host it prepared, and then builds the web
 application, failing the build when no database URL is configured or the
 schema is incompatible. The database
@@ -146,6 +152,33 @@ snapshot. Raising capacity can fill the new slots immediately; lowering it
 prevents new claims without terminating builds already above the limit. `ab
 dispatch --once` performs one pass and does not watch or reload.
 
+The sections `autobuild.toml` delivers to a build fall into three ownership
+classes. **Build-owned** sections define the pipeline a build runs — `[verify]`
+with `[verify.<step>]`, `[finalize]` with `[finalize.<step>]`, `[commands]`,
+and `[workspace]` (provider and config, including `provisioning` and
+`runtimeProvisioning`). They are pinned to the build's own branch: the
+dispatcher reads them at the build's recorded base commit, or at its branch
+head once the build has published commits, and records the exact commit in the
+effective-config artifact metadata. In checkout mode the worktree read is the
+exception: when it cannot be attributed to the branch-head commit — because
+the worktree file has uncommitted edits, because the clean/dirty comparison
+could not be performed (non-git workspace or a transient git error), or because
+the branch head never carried the file — the deposit records the source
+`worktree-dirty` with no commit. The build still runs the worktree bytes, but
+provenance declines to attribute them to any commit. **Deployment-owned** sections — `[roles]`
+(runtime, model, args, alternates, per-role `sessionBudgetSeconds`) and
+`[policy]` — keep flowing live. **Dispatcher-owned** sections (`baseBranch`,
+`capacity`, `forge`, `plugins`, `pr`, `tickets`, `orchestrator`) configure the
+dispatcher itself and are never interpreted by the build runner.
+
+Consequently, an accepted base-branch reload re-deposits only the
+deployment-owned sections to active builds; it does not retarget an in-flight
+build's verify universe, finalize steps, commands, or provisioning. A build
+that publishes a pipeline change to its own branch picks it up at its next
+launch, so config changes still flow through the pipeline for the build that
+carries them. In-flight environments are never re-provisioned: a fresh build
+from the new base is the path for a changed provisioning definition.
+
 Every accepted revision is deposited verbatim as a `dispatcher-config`
 repository artifact and referenced by a `dispatcher.config-reloaded` repository
 event. The dashboard reports the reload and reprojects values such as capacity;
@@ -164,10 +197,11 @@ These fields hot-reload:
 | `baseBranch` | Next dispatch or base fallback decision; existing `build.created` facts remain immutable. |
 | `capacity` | Next dispatcher tick. |
 | `[pr]` | Next build creation. |
-| `[commands]` | Next setup, verify check, or finalize check selected. |
-| `[verify]` and `[finalize]` | Next engine step selection. An approved plan's stored verify selection remains authoritative. |
-| `[roles]` | Next agent invocation for that role. Runtime, model, args, alternates, and the session budget are captured together. |
-| `[policy]` | Next policy, convergence, or agent-session boundary. A running session keeps its captured budget. |
+| `[commands]` | Next setup, verify check, or finalize check selected for a build whose OWN branch carries it. A base-branch reload does not retarget an in-flight build. |
+| `[verify]` and `[finalize]` | Next engine step selection for a build whose OWN branch carries it. An approved plan's stored verify selection remains authoritative, and a base-branch reload does not retarget an in-flight build. |
+| `[workspace]` provider and config (including `provisioning`) | Next launch of a build whose OWN branch carries it. A base-branch reload never re-provisions an in-flight build. |
+| `[roles]` | Next agent invocation for that role. Runtime, model, args, alternates, and the session budget are captured together and delivered live. |
+| `[policy]` | Next policy, convergence, or agent-session boundary, delivered live. A running session keeps its captured budget. |
 | `tickets.readyLabels`, `tickets.readyState` | Next ready-ticket scan. |
 | `tickets.triageState`, `tickets.proposalState` | Next dispatcher handback or harvest filing boundary. |
 
@@ -239,6 +273,40 @@ earlier configured plugins are reserved, and declaration order never permits
 shadowing. A collision between distinct plugin declarations continues to name
 the conflicting adapter and both owners.
 
+Two transitional downgrade paths announce themselves instead of failing
+startup (AUT-517). First, while the builtin hosts the `vercel-sandbox`
+implementation, a configured plugin that re-registers that workspace-provider
+name — `@defrex/autobuild-vercel-sandbox` is exactly such a plugin — is
+skipped with a one-line notice and the builtin keeps serving the provider:
+
+```text
+plugin "autobuild-vercel-sandbox" declares only builtin workspace-provider registration(s) "vercel-sandbox"; skipping it — the builtin keeps serving the provider
+```
+
+The skip applies only when the manifest declares at least one registration,
+only workspace-provider registrations, and every declared name collides with
+a builtin registration; any other collision still throws. The rule keys on
+builtin ownership, so it retires itself when the builtin is removed and a
+second plugin registering the name collides and fails startup as always.
+`ab plugin list` and `ab plugin doctor` show skipped modules as `SKIP` lines
+and exit 0. Second, guest processes (build and harvest children,
+`ab init`'s guest readiness probe, and scoped phase CLI commands) tolerate a
+configured bare package specifier they cannot resolve — guests never
+construct workspace providers, so a provider plugin they need not load is
+skipped with a notice instead of failing the process:
+
+```text
+plugin module "@defrex/autobuild-vercel-sandbox" could not be resolved from repository "…" or installation "…"; guests never construct workspace providers, so the provider plugin is skipped here
+```
+
+Repository-path specifiers and every post-resolution failure (evaluation,
+manifest, collision) stay fail-closed everywhere, including guests. The guest
+readiness probe surfaces a resolution-stage skip in its `configuration and
+plugins` check detail: the detail names the missing module (the skip notice
+quoted above) and the remediation — add the package to the repository's
+dependencies so it resolves from the repository install during
+`commands.setup`.
+
 Plugin authors import the stable surface from `@defrex/autobuild/plugin-sdk`, normally
 with `import type`, and can develop against Autobuild as a dev/peer dependency
 without adding a runtime Autobuild dependency to the plugin. That entry point
@@ -255,6 +323,24 @@ require `^1.3.0`. API 1.4 adds the optional `Ticket.creationKey` projection: a
 ticket-source plugin should return its stable external create/adoption key from
 create, get, and ready listings so dispatch can correlate Autobuild's durable
 in-flight creations. Legacy tickets may omit it and remain dispatchable.
+API 1.6 adds workspace-provider capability declarations: a
+`workspaceProviders` registration may carry a `capabilities` object declaring
+its `[workspace.config]` schema (or an outright refusal), required runtime
+provisioning, supported forges, required environment groups (with per-site
+messages), variables that must exist in the launcher process environment,
+additional operator-sandbox forbidden variable names, HTTPS/token store
+requirements, an origin validator, and a remote readiness validation for
+`ab init --validate`. The host enforces every declared capability at its seam
+without naming the provider; required environment belongs on
+`capabilities.requiredEnv` (a descriptor-level `requiredEnv` is rejected at
+manifest parse), and each `capabilities.requiredEnv` group must declare at
+least one of `dispatchMessage` / `validationMessage` — a group with neither is
+rejected at manifest parse, because the host would silently skip it at both
+enforcement sites. API 1.7 extends the workspace-provider factory context with
+the host-derived seams: `storeRef` and `storeToken` (guaranteed present under
+`capabilities.storeRequirements`), `runtimeReferences`, and the checkout-less
+`origin` and `remoteBranchHead` readers, all optional and ignored by factories
+that do not read them. A plugin reading the new seams should require `^1.7.0`.
 
 ```ts
 import type { AutobuildPluginManifest } from '@defrex/autobuild/plugin-sdk'
@@ -438,7 +524,7 @@ gitPasswordEnv = "AB_GIT_READ_TOKEN"
 
 [workspace.config.runtimeProvisioning.pi]
 install = "npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.84.4"
-preflight = "test \"$(pi --version)\" = \"0.84.4\""
+preflight = "test \"$(pi --version)\" = \"0.84.4\" && pi update --models"
 ```
 
 | Vercel field | Default | Constraints |
@@ -518,13 +604,14 @@ checkout-only hooks such as Husky are not provisioning dependencies. A Bun
 install or verification failure identifies the configured image and expected
 universal-image capabilities, deletes the partial environment, and leaves no
 readiness marker. A retry also deletes any named sandbox without that marker
-instead of adopting partial setup. The installed distribution's version is
-recorded in the guest's `/opt/autobuild/.distribution-version` marker; a
-reused sandbox whose marker no longer matches the version the current system
-would deliver is refreshed by reinstalling the archive before reuse, so an
-upgraded dispatcher retrofits its persistent guests (see "Guest distribution
-version selection and delivery" in docs/setup.md for the release-and-upgrade
-delivery path and the hosted store's version-lockstep gate). Immediately
+instead of adopting partial setup. The installed distribution's identity — package version and remote-store
+protocol version — is recorded in the guest's
+`/opt/autobuild/.distribution-version` marker; a reused sandbox whose marker
+no longer matches the identity the current system would deliver is refreshed
+by reinstalling the archive before reuse, so an upgraded dispatcher retrofits
+its persistent guests (see "Guest distribution version selection and delivery"
+in docs/setup.md for the release-and-upgrade delivery path and the hosted
+store's version-lockstep gate). Immediately
 before every build-child launch, the adapter verifies the
 provisioned absolute Bun executable and every referenced runtime again. A
 failure names the runtime, selecting role/alternate, stage, and provisioning
@@ -884,7 +971,7 @@ session starts, with a copyable table and all registered runtime names.
 | `args` | inherited; otherwise `[]` | optional array of nonempty strings; `[]` allowed | Ordered extra CLI argv tokens applied to every phase and tool-free one-shot invocation. A supplied list replaces, rather than unions with, the inherited list. |
 | `extensions` | no effect | deprecated optional array of nonempty strings | Compatibility-only field. Dispatch warns for each declaring role; migrate explicit runtime options to `args`. |
 | `sessionBudgetSeconds` | inherited; otherwise `[policy].sessionBudgetSeconds` | optional positive integer | Wall-clock budget for each build phase session routed through this logical role. One budget covers the primary and every alternate target. |
-| `alternates` | inherited; otherwise `[]` | optional ordered array of strict `{ runtime?, model?, args?, extensions? }` entries; `[]` allowed | Failure-triggered execution targets. A role's list replaces the inherited list wholesale; each entry overlays that role's effective primary axes. `extensions` is accepted there only as the same deprecated no-op. |
+| `alternates` | inherited; otherwise `[]` | optional ordered array of strict `{ runtime?, model?, args?, extensions? }` entries; `[]` allowed | Failure-triggered execution targets (provider failures and a runtime whose CLI is not installed). A role's list replaces the inherited list wholesale; each entry overlays that role's effective primary axes. `extensions` is accepted there only as the same deprecated no-op. |
 
 <!-- config-fragment:roles -->
 ```toml
@@ -984,7 +1071,7 @@ useful; mixed models are not a configuration inconsistency.
 Each session attempt starts with its role's primary. Overload, rate limits, 5xx,
 timeout, transport, unknown provider failures, and quota/usage/billing
 exhaustion try alternates in declaration order inside that same phase attempt.
-Authentication, permission, and local runtime-configuration failures do not.
+Authentication, permission, and local runtime-configuration failures do not, with one exception: a runtime whose CLI executable is not installed is skipped like any other eligible failure, so the phase runs on the first declared target whose CLI is present. An unsupported installed version is still a stopping configuration failure. If no target's CLI is installed, the chain ends in one non-retried `configuration` failure carrying the last target's missing-CLI message. The remote provisioning preflight stays fail-closed: a missing runtime there is a provisioning defect.
 Each target gets a separate session and transcript; a continuation that moves
 to another target starts fresh from durable context and cannot inherit the
 failed provider's conversation. Selection is not sticky: the next phase, next
@@ -1203,14 +1290,19 @@ Set `COMPANY_TICKET_TOKEN` in the environment, never in this table.
 
 ## `[orchestrator]`
 
-Gates the operator-sandbox feature: a persistent, **credential-free**
-environment per operator × repository that an operator agent drives through the
-`sandbox.*` registry tools (served by `ab mcp` and every later binding). The
-table is closed to unknown keys and restart-classified as a whole.
+Gates the operator-agent feature (AUT-340, AUT-342): the per-operator sandbox
+environments the `sandbox.*` registry tools drive, and — when the embedded
+orchestrator is enabled — the turn runner that answers operator sessions and
+wakes on build events. The table is closed to unknown keys and
+restart-classified as a whole.
 
 | Field | Default | Constraints | Purpose |
 |---|---:|---|---|
-| `enabled` | `false` | boolean | Master gate. With the table absent or `enabled = false`, the sandbox tools are absent from every binding and no environment is ever provisioned. |
+| `enabled` | `false` | boolean | Master gate. With the table absent or `enabled = false`, the sandbox tools are absent from every binding, no environment is ever provisioned, and no dispatcher tick or message post ever runs orchestrator code — a local dispatcher is inert even when enabled, because the turn runner exists only in the hosted deployment. |
+| `model` | — | nonblank string, required when `enabled = true` | Provider-qualified model string for the turn runner, in the same vocabulary as `[roles]` model strings (a leading `vercel-ai-gateway/` prefix is accepted and stripped). Resolved through the deployment's gateway credential. |
+| `invocationBudgetSeconds` | `240` | positive integer, clamped to 300 | Wall-clock budget for one turn invocation. A larger value is clamped — not rejected — to the 300-second hosted function limit the runner executes under (`ORCHESTRATOR_ROUTE_LIMIT_SECONDS`, the same number the operator route pins as `maxDuration`). |
+| `approvals` | see below | array of `tool` or `tool:qualifier` strings | Registry tool names whose calls suspend a turn until the operator answers. Default: `["builds.control:abort", "builds.control:discard", "builds.answer:revise-spec", "sandbox.publish", "tickets.move:ready"]`. Empty (`[]`) means none — autonomous operation. An entry naming an absent or unknown tool is **inert by design**, never a config error: the list stays stable while the registry grows, and a tool's removal cannot break parsing. A `tool:qualifier` entry applies to the named discriminator value only (for example `tickets.move:ready` approves moving a ticket to `ready`); for a tool without a discriminator, only the bare form matches. |
+| `wake` | inherits the default | array of event-type globs | The attention events a **new** session wakes for. Kept schema-optional so absent (inherit the default attention set — the build events `ab watch` filters on by default plus the repository-journal events `ab watch --repository` follows) and `[]` (never wake; message-only) stay distinct. Each glob must match at least one build or repository-journal event type, validated with the same compiler `ab watch` uses. Existing sessions never retroactively inherit; an explicit `PUT .../wake` always wins. |
 | `sandbox` | — | strict subtable; absence reads as the defaults | Sandbox behavior knobs. |
 
 `[orchestrator.sandbox]` fields:
@@ -1225,7 +1317,16 @@ forge, ticket-provider, or model credential, and naming any of `AB_STORE`,
 `AB_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, `LINEAR_API_KEY`, `VERCEL_OIDC_TOKEN`,
 `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, or `AI_GATEWAY_API_KEY`
 in `environmentVariables` is a config error. The typed operator tools remain
-the only route to build state from inside the sandbox. Tool bounds:
+the only route to build state from inside the sandbox. A workspace-provider
+plugin can declare additional forbidden names via its registration's
+`capabilities.sandboxForbiddenEnv`; those are enforced at the post-load seams
+(provider construction and `ab init --validate`) rather than at config parse,
+because plugins are not loaded when configuration is parsed — a deliberate
+deferral, not an oversight. Concretely, the shared names above are rejected
+when the config is parsed, plugin-declared extras are rejected when the
+provider is constructed (dispatch and `ab mcp`), and `ab init --validate`
+re-checks both sets after plugins load, before any infrastructure is
+provisioned. Tool bounds:
 `sandbox.exec` waits at most 300 seconds; stdout and stderr are each truncated
 at 65,536 bytes with a `[truncated by autobuild: output exceeded 65536 bytes]`
 marker; `sandbox.reset` and archiving an operator's last session are
@@ -1236,6 +1337,10 @@ one environment per operator and repository.
 ```toml
 [orchestrator]
 enabled = true
+model = "anthropic/claude-sonnet-4"
+invocationBudgetSeconds = 240
+approvals = ["builds.control:abort", "sandbox.publish", "tickets.move:ready"]
+# wake omitted: new sessions inherit the default attention set
 
 [orchestrator.sandbox]
 idleMinutes = 30
@@ -1245,6 +1350,25 @@ environmentVariables = ["MY_TOOL_CONFIG"]
 Set `MY_TOOL_CONFIG` in the host environment of the `ab mcp` process; a missing
 value fails the tool call that needs it, named as a typed `environment` error.
 
+In the hosted deployment the `sandbox.*` tools are served to orchestrator
+turns from two bindings, both composing the backend from the repository's
+deposited effective config: the store service's message-turn runner (and its
+same-invocation approval resumes), and the origin-mode dispatcher tick's wake
+and resume runner, which reuses the dispatcher's wired workspace provider and
+forge. Both use the builtin workspace provider and the builtin `github` forge
+from that config — a plugin-provider or forgeless config degrades that
+binding's sandbox tools only, with a reported diagnostic. The store-service
+path authenticates the Sandbox SDK with the request's `x-vercel-oidc-token`
+header (or an explicit `VERCEL_OIDC_TOKEN`, which takes precedence, or the
+durable `VERCEL_TOKEN`/`VERCEL_TEAM_ID`/`VERCEL_PROJECT_ID` triple, which
+needs no header); the tick path inherits the dispatcher's already-forwarded
+token. Every serving path derives the same deterministic environment name per
+(repository origin, operator), so an operator's environment is one
+environment per repository no matter which binding drove it, and the guest
+still receives no credential. Serving stays gated exactly as locally: the
+effective `[orchestrator].enabled`, the registry's closed-table filtering,
+and the `approvals` suspension list in the turn loop.
+
 ## Complete example
 
 The following deliberately exercises every fixed table and both verify/finalize
@@ -1427,8 +1551,10 @@ pre-attempt index and reports the original Git failure; merged worktree files
 remain in place and the merge's exit status is unchanged. Upgrade never pushes
 or rewrites history.
 
-Autobuild now installs 11 skills; only `ab-spec`, `ab-tickets`, and `ab-guide`
-are model-invocable. The setup reference is an ordinary support file in the
+Autobuild now installs 12 skills; only `ab-spec`, `ab-tickets`, and `ab-guide`
+are model-invocable. (`ab-operate` — the embedded orchestrator's operating
+manual — also carries `disable-model-invocation: true`; it is read by the
+hosted turn runner, never invoked by a model in a build session.) The setup reference is an ordinary support file in the
 editable/pristine `ab-guide` tree and participates in the same three-way
 upgrade merge as every other vendored file.
 
@@ -1459,7 +1585,7 @@ poll. Editing TOML cannot change them.
 |---|---:|---|---|
 | Ticket intake | on | `ab dispatch --intake` / `--no-intake`; `i` on the dashboard's global row, and `p` (pause all) / `r` (resume all) on that row or their sessionless equivalents `ab pause --all` / `ab resume --all`, which turn intake off and on as part of quiescing the repository | When off, skip only new ticket list/claim/dispatch work. Janitor work, lease recovery, in-flight builds, and harvesting continue. Turning intake off does not hold builds the repository has already accepted — that is the repository pause below. |
 | Repository pause | off | `p` (pause all) / `r` (resume all) on the dashboard's global row, or `ab pause --all` / `ab resume --all` | While on, the dashboard controls line shows `repository PAUSED`, and each held queued row shows `(held)` while retaining its literal `QUEUED` status. No dispatcher tick attaches a runner to such a build — recovery, startup resume, and the lease sweep all skip them. Running builds are parked by the per-build pauses the same command writes; the janitor still settles aborts and discards. |
-| Claim-time auto-merge default | off | `ab dispatch --auto-merge` / `--no-auto-merge`; `m` on the global row | Seeds durable auto-merge intent only on builds claimed after the setting is enabled. Existing builds never change with the default. |
+| Repository auto-merge default | off | `ab dispatch --auto-merge` / `--no-auto-merge`; `m` on the global row | Seeds durable auto-merge intent on builds claimed while the setting is enabled, and — on each change — also applies as a bulk action to every current non-terminal build: turning it on requests consent for each build (turning it off withdraws it), attributed to the operator who toggled it exactly as if they had pressed `m` on every row. A per-build toggle overrides its build's state until the global row is toggled again. |
 | Harvest gate | on | `h` on the dashboard's global row | Pauses or resumes repository observation harvesting. The header shows the kernel-acknowledged gate, not merely a pending keypress. |
 
 The opposite flag forms for each dispatch setting are mutually exclusive.

package/docs/hosted-dispatcher.md

@@ -1,19 +1,24 @@
 # The hosted dispatcher
 
-The optional [hosted service](../packages/hosted-store-service/README.md) can
-own the dispatch kernel. One authenticated HTTP endpoint — `GET /api/dispatch`
-— runs, for each configured repository, one bounded origin-mode dispatcher
+The optional [`@defrex/autobuild-hosted-dispatcher`](../packages/hosted-dispatcher/README.md)
+package lets a deployment own the dispatch kernel. Installing it and mounting
+its route — `GET /api/dispatch`, backed by the package's
+`dispatcherEndpoint()` singleton — makes the hosted deployment the kernel
+owner. One authenticated HTTP invocation runs, for each configured
+repository, one bounded origin-mode dispatcher
 tick: the kernel claims ready tickets, provisions and launches sandboxes,
 observes running builds, settles publications, opens and merges PRs, and runs
 the janitor, exactly as a local `ab dispatch --once --repository <origin>`
 pass does. The schedule is what you attach to that endpoint (Vercel Cron calls
 it once a minute by default), so builds no longer depend on a maintainer's
-machine.
+machine. A deployment that does not install the package serves the hosted
+store, ticket, operator, and web endpoints and never attempts a dispatch tick.
 
 ## Enabling the schedule
 
-1. Deploy the hosted service with the dispatcher variables from
-   [its README](../packages/hosted-store-service/README.md#hosted-dispatcher)
+1. Deploy the hosted service with the dispatcher package installed and the
+   dispatcher variables from
+   [its README](../packages/hosted-dispatcher/README.md)
    — `AB_DISPATCHER_ORIGIN`, the repository set, `CRON_SECRET`, and the forge
    credentials the kernel needs (`GITHUB_TOKEN` or `GH_TOKEN`, plus any
    guest-forwarded variables such as `AI_GATEWAY_API_KEY`). A deployment
@@ -44,26 +49,77 @@ Every sandbox installs the Autobuild distribution the launching dispatcher
 runs. A local dispatcher packs it from its source checkout with `bun pm pack`;
 a bundled deployment has neither `bun` nor a source tree at runtime, so it
 must pack the archive while both exist — in its build step — and carry it into
-the function bundle:
+the function bundle. The script lives in the hosted store service package
+(`packages/hosted-store-service/package.json`), whose directory is the Next.js
+project directory and the deployment build's working directory:
 
 ```json
-{ "scripts": { "deploy:build": "bun packages/hosted-store-service/src/bin.ts pack-distribution && bun run postgres:migrate && bun run build && bun tools/ship-packed-distribution.ts" } }
+{ "scripts": { "deploy:build": "bun ../../packages/hosted-dispatcher/src/bin.ts pack-distribution --root . && bun ../../packages/postgres-store/src/bin.ts migrate && bun run build && bun ../../packages/hosted-dispatcher/src/ship-packed-distribution.ts && bun ../../packages/hosted-dispatcher/src/ship-provider-plugin.ts" } }
 ```
 
-`pack-distribution` writes `.autobuild-dist/autobuild-<version>.tgz` under the
-distribution root (`--root DIR` overrides). The Next.js config's
+`pack-distribution` (the `ab-hosted-dispatcher` bin) writes
+`.autobuild-dist/autobuild-<version>.tgz` under the
+distribution root (`--root DIR` overrides) — this deployment passes
+`--root .`, because the packer's default root is the repository's distribution
+root while the trace step below and the Next config's
 `outputFileTracingIncludes: { '/api/dispatch': ['./.autobuild-dist/**'] }`
-records the intent to include that directory in the cron route's bundle, but
+resolve against the deployment build's working directory, where the archive
+must land beside the built output. The Next.js config's
+`outputFileTracingIncludes` records the intent to include that directory in the cron route's bundle, but
 Next 16's default Turbopack builds never apply `outputFileTracingIncludes`
 (only webpack builds do), so a deployment cannot rely on the config alone. The
 autobuild-api pipeline therefore ends `deploy:build` with a post-build trace
-step (`bun tools/ship-packed-distribution.ts`) that appends the archive to the
+step (`bun ../../packages/hosted-dispatcher/src/ship-packed-distribution.ts`) that appends the archive to the
 dispatch route's `route.js.nft.json` — the trace file Vercel's Next builder
 consumes when assembling the function bundle — and fails the deploy loudly if
-nothing was packed or the trace file is missing. A deployment using this
+nothing was packed or the trace file is missing. The same step appends the
+distribution root's `package.json`, which provisioning reads for the running
+version and which no import traces once the Next.js project directory sits
+below the repository root. A deployment using this
 pipeline cannot ship without the archive; deployments that skip both packing
 and the trace step still fail at runtime.
 
+A second post-build trace step ships the provider plugin package (AUT-517):
+`bun ../../packages/hosted-dispatcher/src/ship-provider-plugin.ts` locates the
+plugin's source through the repository root's `workspaces` tree (never through
+`node_modules`, so a previous run's staged directory cannot shadow the source),
+bundles its entrypoint with `bun build --target=bun --format=esm` into a
+single self-contained module (the plugin-sdk closure inlines — the
+deployment's repository-root `node_modules` carries no `@defrex/autobuild`
+either — while node builtins stay external), stages it into
+`<repoRoot>/node_modules/@defrex/autobuild-vercel-sandbox/` (replacing the
+workspace symlink a local `bun install` leaves there — or a previous run's
+staged directory, which `bun install` does not relink; the deployment never
+runs `bun install` again), and appends the staged files to the dispatch
+route's trace at the same repository-root depth as the existing
+`node_modules/.bun/**` entries. A bare plugin specifier resolves only
+through a `node_modules/` path, and the compiled dispatcher's
+`distributionRoot()` is the repository root, so only this staging makes
+`plugins = ["@defrex/autobuild-vercel-sandbox"]` loadable inside the
+deployed function. The step is idempotent across runs — including in a
+fresh process after an earlier run consumed the workspace link — and fails
+the deploy loudly when the package, its entrypoint, or the trace file is
+missing. The npm published package remains the real `src` — only the
+deployment stages the bundle.
+
+What the staged directory does afterwards depends on the build environment.
+Inside a Vercel deployment build (which always sets `VERCEL`, including a
+local `vercel build` run) the staged directory stays: the deployment never
+runs `bun install` again and the function bundle's runtime resolution needs
+it — a deployment building outside Vercel must set `VERCEL=1` in its build
+environment to keep the staged bundle. A plain local `bun run deploy:build`
+(no `VERCEL` environment) removes the staged directory afterwards and
+restores the workspace symlink, so a local run leaves the checkout exactly
+as `bun install` had it and local test runs keep resolving the workspace
+source (the capability parity test's reference equality holds). On checkouts
+of older versions the staged directory stayed behind and survived `bun
+install` — it reports "no changes" because the staged package satisfies the
+manifest — so later local runs resolved the plugin to the self-contained
+bundle and the parity test failed on its reference-equality assertion; the
+recovery is `rm -rf node_modules/@defrex/autobuild-vercel-sandbox && bun
+install`, or simply re-run `deploy:build` locally on a version with this
+fix, which restores the symlink itself.
+
 At runtime the kernel takes, in order: `AB_DISTRIBUTION_ARCHIVE` (an explicit
 archive path), the single archive under `.autobuild-dist/` of the
 distribution root or working directory, a source checkout packed on the spot,

package/docs/operator-api.md

@@ -1,9 +1,9 @@
 # Operator API v1
 
 The hosted service exposes the polling-oriented operator surface at
-`/operator/v1/repos/{repo}`. It is versioned with remote store protocol **2**.
+`/operator/v1/repos/{repo}`. It is versioned with remote store protocol **3**.
 Every request must send `X-Autobuild-Version`,
-`X-Autobuild-Protocol-Version: 2`, and `Authorization: Bearer …`. Identity is
+`X-Autobuild-Protocol-Version: 3`, and `Authorization: Bearer …`. Identity is
 checked before authentication or resource lookup.
 
 Mint a token offline; the signed user is used as the human actor on every write: