@defrex/autobuild 0.8.0 → 0.10.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,11 +126,120 @@ 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.
 
+**Incremental reducers.** Every pure projection of an event array is a fold plus
+a final derivation, defined once with `defineReducer` in
+`packages/core/src/kernel/incremental.ts`: `initial()` builds an empty
+accumulator, `advance(acc, events)` folds in only the events newer than the
+accumulator, and `finish(acc)` derives the public state. The whole-array
+functions (`reduceBuild`, `reduceHarvest`, `reduceSession`, and the rest) are
+wrappers over the same fold, so results cannot diverge, and a property test
+checks every split point of fixture and generated logs. The accumulator is plain
+JSON, so it survives a serialize-and-parse round trip. `advance` never mutates
+its input: it clones, then folds, so a state derived earlier is never disturbed
+by a later advance. Each reducer publishes a `version`; bump it whenever the
+accumulator shape or the fold semantics change, because a cached accumulator is
+only valid for the version that wrote it. `kernel/reducer-registry.ts` lists
+every reducer with its version, and its snapshot test fails when an accumulator
+shape changes without a bump. Most callers still read whole logs (the terminal
+dashboard poll advances a carried build accumulator by per-build deltas; the
+dispatcher view below restores from stored accumulators).
+
+**Reducer snapshots.** The `BuildStore` port can keep, per scope (one build log
+or the repository journal) and registered reducer, that reducer's accumulator as
+of a cursor: `getReducerSnapshot(scope, reducer, version)` and
+`putReducerSnapshot(scope, reducer, {version, cursor, state})`
+(`packages/core/src/store/snapshots.ts`). The log stays the only authority. The
+store enforces the invariants: the stored cursor never decreases (a write whose
+cursor does not advance is a no-op, so concurrent writers cannot undo each
+other), a row of another reducer version reads as absent and is replaced once a
+writer advances past it, and a cursor beyond the log's tail is refused and never
+returned. Every consumer treats a missing, mismatched, ahead-of-log, malformed
+or unreadable snapshot as a miss and replays the log, with identical results;
+deleting all snapshots changes no observable output (the integration harness
+audits this for every scenario at cleanup). Memory, SQLite, Postgres and the
+remote client implement it, and the hosted store service serves it on
+`GET|PUT /builds|repos/{id}/snapshots/{reducer}`
+(`docs/remote-store-protocol.md`). SQLite creates the `reducer_snapshots` table
+at open. Postgres keeps it outside the versioned schema: `reducer_snapshots` is
+created by the idempotent `SNAPSHOT_SCHEMA_DDL` in `migratePostgres`, with no
+marker, version or checksum change, so a deployment at the current schema keeps
+serving across the upgrade, a new client against a database that lacks the table
+reads every snapshot as missing and replays (SQLSTATE `42P01` is never an
+error), and an older client never asks. Run `bun run postgres:migrate` once to
+gain the table; until then the dispatcher and every other reader replay in full.
+
+**Dispatcher repository view.** A dispatcher process builds its view of the
+repository once and refreshes it by deltas
+(`packages/core/src/processes/repo-view.ts`). `RepoViewStore` decorates the
+`BuildStore` port: the first `refresh()` reads the journal's high-water mark
+(`getRepoHighWater`), the bounded journal subset, the build listing and digests,
+and the full log of every build that still has work (the same predicate the tick
+loops use); every later `refresh()` reads only events newer than its cursors —
+one journal delta, one delta per held build, plus the listing and digest reads
+that discover new builds. Every tick stage reads and writes through the view, so
+an event a stage appends is folded in at once and later stages in the same tick
+see it with no re-read; a foreign append interleaved with ours leaves a seq gap
+that marks the log dirty, a lost compare-and-set does the same, and any delta
+that is not contiguous from its cursor discards the log and re-reads it in full,
+so no event is skipped. Every state transition of one source (a build, the
+journal) runs on that source's single promise chain — snapshot and delta reads,
+window opening and widening, the fold after an own append, a lost
+compare-and-set's invalidation — and readers queue on it too, so overlapping
+readers join the repair in flight instead of observing half-applied state.
+Decisions that deliberately re-read at the last moment
+(`refreshBuild`) take an explicit delta. Cursor-bearing readers such as the
+orchestrator wake pass get per-source windows that hold only events above the
+lowest session cursor. A `--once` invocation builds the view cold and reads each
+log once; a long-running dispatcher pays that replay at its first tick and not
+again.
+
+The view restores from reducer snapshots on cold start. The journal comes from
+the `journalView` reducer (the journal pruned on arrival: durable types plus the
+tail from the latest `dispatcher.run-started`); each work build comes from one
+`work` snapshot row — the `build`, `logIndex`, `openExecution`,
+`openBuildWorkspace`, `publicationState`, `lastExecutionOutcome`, `buildDigest`,
+`dashboardFacts` and `currentDeferralObservation` accumulators at a single
+cursor. One row is one atomic write on every adapter, so a reader in another
+process sees the old bundle or the new, never a mix; the bundle version is
+derived from the component reducer versions, so a stale bundle misses and the
+build is replayed once. The view
+reads only the events newer than that cursor and holds, for a snapshot-backed
+build, just that delta plus the reduced state of everything before it, so a tick
+with no new events reads zero event rows (apart from the discovery listing and
+digests) and one with M new events reads exactly M. Tick stages that run for every
+build each tick take `buildFacts(slug)` (state, log index, open execution, open
+workspace, publication view) instead of the event array, and read raw history
+only on the branches that act on it. `persistSnapshots()` writes the advanced
+state back at the end of each tick and on shutdown — best effort, throttled in a
+resident dispatcher, always run by a cold single-tick process — and never writes
+a cursor that was not read from the log.
+
+**Operator reads.** The web dashboard, the repository and Harvest status
+routes, the operator build listings, and the `ab watch`/`ab wait` discovery
+passes derive from that same view instead of replaying the log
+(`packages/core/src/operator/read-view.ts`). A dashboard row renders from the
+`BuildState` plus the `dashboardFacts` reducer
+(`packages/core/src/cli/dashboard/facts.ts`: queued-row dispatch text, session
+brackets, phase intervals, pause time, and the per-round loop-output seqs) and
+the auto-merge deferral ledger; `projectBuild(…, events)` is the same projection
+over the whole-array reduction, so the snapshot and replay paths cannot differ.
+Within one serving process, passes are single-flight per repository: requests
+arriving while a pass runs join the one trailing pass, which restores from the
+snapshot the previous pass persisted. A poll at idle therefore reads no event
+rows beyond snapshot lookups and build discovery, and a poll after M new events
+reads those M rows once, however many tabs or watchers the process serves.
+Serving processes do not coordinate: with P of them, each may read the same M
+rows once, so duplicate reads are bounded by P and never by history, tabs, or
+watchers. A settled build listed under `--all` is restored from the snapshot the
+dispatcher left at settlement, or read once and then persisted. The first
+operator poll after upgrading replays each work build once, because the stored
+bundle layout changed.
+
 **Session Store authority.** `packages/core/src/cli/binary.ts` validates a complete build or
 Harvest ambient tuple before opening its phase Store through
 `packages/core/src/cli/store-opening.ts`. `packages/core/src/cli/env.ts` also classifies optional ambient
@@ -503,9 +628,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 +711,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 +728,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 +750,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 +771,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,11 +197,12 @@ 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. |
-| `tickets.readyLabels`, `tickets.readyState` | Next ready-ticket scan. |
+| `[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`, `tickets.readyAssignee` | Next ready-ticket scan. |
 | `tickets.triageState`, `tickets.proposalState` | Next dispatcher handback or harvest filing boundary. |
 
 Adapter selectors and factory inputs are constructed once and require a
@@ -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
@@ -1080,6 +1167,7 @@ state. Within a present table, `source` and `readyState` are required.
 | `source` | — | required nonblank builtin or plugin registration name | Select the ticket adapter after configured plugins load. |
 | `readyLabels` | source-aware | optional array of nonempty strings; `[]` allowed | Require every listed label in addition to the state gate. |
 | `readyState` | — | required nonblank string | The one workflow state eligible for dispatch. |
+| `readyAssignee` | — | optional; `"me"` or an email address; Linear only (rejected for file, hosted, and plugin sources) | Require the ticket to be assigned to one Linear user, in addition to the state and label gates. |
 | `teamKey` | — | required for Linear and hosted; forbidden for file; optional for plugins | Backend team key such as `"ENG"`, or an existing plugin config field. |
 | `claimedState` | `"In Progress"` for direct Linear; hosted backend default otherwise | optional nonempty string; forbidden for file; allowed for plugins | Workflow state entered when a ticket is claimed. |
 | `createState` | provider default | optional nonempty string | Default state for newly created tickets when `ab ticket create` omits `--state`. |
@@ -1087,13 +1175,33 @@ state. Within a present table, `source` and `readyState` are required.
 | `proposalState` | the resolved `triageState` | optional nonempty string | State harvest files its synthesized proposals into. Setting it to `readyState` waives the human grooming gate, not dependency eligibility. |
 | `dir` | file: selected local state root's `tickets/`; plugin: omitted | optional nonempty path; forbidden for Linear; allowed for plugins | Root containing file-source state directories, or an existing plugin config field. Relative file paths resolve from the repository. |
 
+`readyAssignee = "me"` resolves to the Linear user who owns `LINEAR_API_KEY`,
+so one committed value makes each person's local dispatcher take only the work
+assigned to them; an email names a specific user, for a shared or bot key. The
+gate is conjunctive with `readyState` and `readyLabels`, and a ticket with no
+assignee is never ready while it is set. It applies to every ready surface
+(dispatch, the queued count, and `ab ticket list` without filters); blockers
+still prevent claim. It is empty or blank, or neither `"me"` nor an email,
+fails validation. `ab init --validate` prints the user the gate resolves to and
+fails when an email matches no workspace user. The field reloads without a
+restart.
+
 When `readyLabels` is absent, direct Linear uses `["autobuild"]`; hosted, file,
 and plugin sources use `[]`, meaning no host-imposed label gate. An explicit value always
 wins. A nonempty list is
 conjunctive: every configured label must be present. `readyState` remains
 mandatory regardless of labels. Linear compares state and label names exactly
-and case-sensitively. The file source accepts state names case-insensitively and
-canonicalizes them to `triage/`, `ready/`, `doing/`, or `done/`.
+and case-sensitively. The file source matches state names case-insensitively against the directories
+under the tracker root: the four lifecycle directories (`triage/`, `ready/`,
+`doing/`, `done/`, always present) plus any directory the repository adds, such
+as `icebox/`. A name matching no directory is an error listing those that
+exist, so creating a state stays an explicit act: `ab ticket state create <name>
+[--about <text>]` makes one, and `ab ticket states` lists every state with its
+roles, ticket count, and purpose. A purpose is stored as a one-line `.about` file
+inside the state directory, so it travels with a git-tracked `dir` and is never
+read as a ticket. `createState`, `readyState`,
+`triageState`, and `proposalState` may each name any existing directory;
+`ab ticket list` with no filter still lists only `readyState`.
 
 Source-specific validation is strict:
 
@@ -1203,14 +1311,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 +1338,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 +1358,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 +1371,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 +1572,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 +1606,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.