@defrex/autobuild 0.8.0 → 0.10.0

package/skills/guide/references/plugin-authoring.md

@@ -38,6 +38,17 @@ the durable provider locator as `BuildExecutionStart.workspaceRef`; local PID
 supervision remains host-owned. A workspace plugin relying on these fields
 should declare an API range containing `^1.5.0`.
 
+Plugin API 1.7 extends the workspace-provider factory context with the
+host-derived seams a store-requiring remote provider needs. Workspace-provider
+factories additionally receive `storeRef` and `storeToken` (guaranteed present
+when the registration declares `capabilities.storeRequirements`),
+`runtimeReferences` (the host's effective runtime routes; absent at call sites
+that reference no runtimes), and the checkout-less `origin` and
+`remoteBranchHead` readers (absent means fall back to host `git` from
+`repoRoot`). All five are optional, and a factory that ignores them changes
+nothing. A plugin reading the new seams should declare an API range containing
+`^1.7.0`.
+
 `BuildStore` and `BlobStore` contract types are exported for remote-server
 authors, but BuildStore is **not** an in-process manifest map. Implement the
 colocated language-neutral
@@ -113,6 +124,12 @@ Every module must default-export one strict `AutobuildPluginManifest`:
   absolute consuming-repository root. Ticket sources receive the existing
   `[tickets]` fields, workspace providers receive `[workspace.config]`, and
   runtime and forge factories currently receive an empty `config` object.
+  Workspace providers additionally receive the host-derived seams (API 1.7):
+  `storeRef` and `storeToken` — guaranteed strings when the registration
+  declares `capabilities.storeRequirements` — plus `runtimeReferences`,
+  `origin`, and `remoteBranchHead`. Each seam is optional and absent when the
+  host call site supplies no such value; absent `origin`/`remoteBranchHead`
+  fall back to host `git` from `repoRoot`.
 
 Add the module specifier at the TOML root, before any table. Repository-path
 specifiers resolve from the config-bearing root, which is the immutable build

package/skills/guide/references/remote-store-protocol.md

@@ -20,7 +20,7 @@ document and the package's executable contracts together.
   `AB_STORE`; the shipped client appends the routes below.
 - Every `/builds`, `/repos`, and `/sessions` request sends
   `X-Autobuild-Version` with the exact client package version and
-  `X-Autobuild-Protocol-Version` with the remote protocol version (`2` in this
+  `X-Autobuild-Protocol-Version` with the remote protocol version (`3` in this
   distribution). Before authentication,
   body parsing, or resource lookup, the server compares both exact strings.
   Missing or different values receive `409 {"kind":"conflict","error":"…"}`;
@@ -290,13 +290,15 @@ it to exist. An unknown build returns `404 not-found`.
 
 | BuildStore operation | HTTP route | Request | Success |
 |---|---|---|---|
-| `createBuild` | `POST /builds` | `{slug: string, repo: string, repoOrigin?: string, ticket?: TicketRef, branch?: string}`; `slug`, `repo`, and a supplied `branch` are nonempty | `201` + `BuildRecord`; duplicate slug is `409 conflict` |
+| `createBuild` | `POST /builds` | `{slug: string, repo: string, repoOrigin?: string, ticket?: TicketRef, branch?: string, created?: event write}`; `slug`, `repo`, and a supplied `branch` are nonempty. `created`, when present, must be a valid `build.created` write; the server appends it as seq 1 atomically with the record (both exist or neither), and an invalid one is `422` with nothing created | `201` + `BuildRecord`; duplicate slug is `409 conflict` |
 | `listBuilds` | `GET /builds` | none | `200` + `BuildRecord[]`; list order is unspecified |
 | `getBuild` | `GET /builds/{slug}` | none | `200` + `BuildRecord`; absent is `404` (the shipped client maps this to `null`) |
 | `append` | `POST /builds/{slug}/events` | event write | `201` + build event envelope |
 | `appendIfCurrent` | `POST /builds/{slug}/events/conditional` | `{"expectedSeq": nonnegative integer, "event": event write}` | appended: `201` + build event envelope; stream advanced: `200 null` |
 | `getEvents` | `GET /builds/{slug}/events?since={n}&wait={s}` | optional `since` query value, parsed below; absence defaults to `0`. Optional `wait` in whole seconds, parsed per the event-wait rules below | `200` + envelopes whose `seq` is strictly greater than parsed `since`, in increasing sequence order |
 | `appendWithArtifacts` | `POST /builds/{slug}/deposits` | atomic deposit request | `201` + `{event, artifacts}` |
+| `getReducerSnapshot` | `GET /builds/{slug}/snapshots/{reducer}?version={n}` | required `version` query value, a positive integer; `reducer` is a registry name (`^[A-Za-z][A-Za-z0-9._-]{0,63}$`) | `200` + `{"version", "cursor", "state"}` or `200 null` when absent, written by another reducer version, or ahead of the build log's tail; an unknown build is `404`, which the shipped client also maps to `null` |
+| `putReducerSnapshot` | `PUT /builds/{slug}/snapshots/{reducer}` | `{"version": int >= 1, "cursor": int >= 0, "state": JSON}`, at most 16 MiB (`413` above) | `200 {"written": boolean}`; the stored cursor never decreases, so a write at an equal or lower cursor (or an equal cursor at an equal or lower version) and one past the log's tail answer `written: false` |
 | `putArtifact` | `POST /builds/{slug}/artifacts` | artifact input | `201` + build artifact metadata |
 | `getArtifact` | `GET /builds/{slug}/artifacts?kind={kind}&rev={n}` | `kind` is required and nonempty; optional `rev` is parsed below | `200` + artifact read; an absent `rev` parameter selects the latest revision; a missing kind/revision is `200 null` |
 | `listArtifacts` | `GET /builds/{slug}/artifact-list?kind={kind}` | optional `kind`; absence means all kinds | `200` + metadata ordered by kind and then increasing revision |
@@ -336,6 +338,32 @@ part of this protocol. Retention is enforced server-side inside the store at
 deposit time (bounded pruning of dispatcher run/config artifact revisions),
 not through any endpoint.
 
+### Reducer snapshots
+
+A reducer snapshot is one registered reducer's serialized state as of a log
+cursor, kept per scope (one build log or one repository journal) and reducer
+name. It is a cache the log regenerates, never an authority: a process with no
+hot memory loads it, reads only the events newer than its cursor, advances the
+reducer, and writes the advanced state back, and deleting every snapshot changes
+no observable output. The routes above and in section 4 are additive and carry
+no protocol-version bump. The store, not the client, enforces the invariants:
+
+- the stored cursor never decreases, whatever the versions of the competing
+  writers; a write succeeds only when no row exists, when its cursor is above the
+  stored one, or when its cursor equals the stored one and its version is higher
+  (an upgraded reducer replacing the old shape at an unchanged tail);
+- a read answers `null` for a row whose version differs from the requested one,
+  and for one whose cursor is beyond the scope's log tail; a write beyond the
+  tail is refused;
+- an unknown build or repository answers `null` (read) or `written: false`
+  (write) and never creates the scope.
+
+A client treats `404` and `405` from either route as "no snapshot", so a client
+newer than its store replays the log with no error, and a client older than its
+store never calls the routes. Authentication and transport failures still
+surface normally. A build token may touch only its own build's snapshots and a
+repository token only its own repository's, exactly as for events.
+
 ### The event-read bounded wait
 
 Both event reads (`getEvents` and, symmetrically, the `getRepoEvents` read of
@@ -357,7 +385,8 @@ requires. A held request's authentication, token scope, and version-skew rules
 are identical to the immediate form: a `401`, `403`, or `409` identity failure
 is answered immediately, never held.
 
-The parameter is purely additive, so the protocol version stays `2`: a server
+The parameter is purely additive in the version it landed in (protocol `2`,
+where the event-wait rules were introduced): a server
 that ignores `wait` remains conforming — its immediate empty answers only raise
 the client's request rate — and a client that sends `wait` to such a server
 observes no other difference. This is the same reasoning the stream and session
@@ -368,7 +397,11 @@ waits apply. There is no push transport; a held request is the whole mechanism.
 Repository journals are separate resources with independent event sequences,
 artifacts, and leases. `{repo}` is one percent-encoded repository id; encode
 embedded `/` characters. All resource routes authorize and require the
-repository to exist. An unknown repository returns `404 not-found`.
+repository to exist. An unknown repository returns `404 not-found` — with one
+carve-out: the build-digest batch read of this section is keyed to build
+records, not the repository journal record, so it authorizes the repo token
+but answers `200` (possibly empty) even for an unknown repository, a repository
+without a journal record, or a repository without builds.
 
 | BuildStore operation | HTTP route | Request | Success |
 |---|---|---|---|
@@ -376,10 +409,14 @@ repository to exist. An unknown repository returns `404 not-found`.
 | `getRepo` | `GET /repos/{repo}` | none | `200` + `RepositoryRecord`; absent is `404` (the shipped client maps this to `null`) |
 | `appendRepo` | `POST /repos/{repo}/events` | event write | `201` + repository event envelope |
 | `getRepoEvents` | `GET /repos/{repo}/events?since={n}&wait={s}` | optional `since` query value, parsed as in section 3; absence defaults to `0`. Optional `wait` in whole seconds, per the event-wait rules of section 3 | `200` + envelopes with `seq >` parsed `since`, in increasing sequence order |
+| `getRepoStateEvents` | `GET /repos/{repo}/state-events` | none | `200` + the bounded repository-journal subset (AUT-489): every durable event type (`harvest.*`, `orchestrator.sandbox.*`, the three dispatcher setting types) plus, when the journal has one, the tail from the latest `dispatcher.run-started`, in increasing sequence order; served inside the repository-existence gate like `GET events`, so an unknown repository is `404` |
+| `getReducerSnapshot` (repo scope) | `GET /repos/{repo}/snapshots/{reducer}?version={n}` | required `version` query value, a positive integer; `reducer` is a registry name (`^[A-Za-z][A-Za-z0-9._-]{0,63}$`) | `200` + `{"version", "cursor", "state"}` or `200 null` when absent, written by another reducer version, ahead of the journal's tail, or the repository has no journal record; an unknown repository is `404`, which the shipped client also maps to `null` |
+| `putReducerSnapshot` (repo scope) | `PUT /repos/{repo}/snapshots/{reducer}` | `{"version": int >= 1, "cursor": int >= 0, "state": JSON}`, at most 16 MiB (`413` above) | `200 {"written": boolean}`; the stored cursor never decreases, so a write at an equal or lower cursor (or an equal cursor at an equal or lower version) and one past the journal's tail answer `written: false` |
 | `appendRepoWithArtifacts` | `POST /repos/{repo}/deposits` | atomic deposit request | `201` + `{event, artifacts}` using repository shapes |
 | `putRepoArtifact` | `POST /repos/{repo}/artifacts` | artifact input | `201` + repository artifact metadata |
 | `getRepoArtifact` | `GET /repos/{repo}/artifacts?kind={kind}&rev={n}` | required nonempty `kind`; optional `rev` is parsed as in section 3 | `200` + artifact read; latest only when the `rev` parameter is absent; missing kind/revision is `200 null` |
 | `listRepoArtifacts` | `GET /repos/{repo}/artifact-list?kind={kind}` | optional `kind`; absence means all kinds | `200` + metadata ordered by kind and then increasing revision |
+| `getRepoBuildDigests` | `GET /repos/{repo}/build-digests` | none | `200` + `BuildDigest[]`, one entry per build record of the repository (possibly empty), ordered by slug; handled before the repository-existence gate, so an unknown or journal-less repository answers `200 []` |
 | `claimRepoLease` | `POST /repos/{repo}/lease/claim` | claim request | `200 {"ok": boolean}` |
 | `heartbeatRepo` | `POST /repos/{repo}/lease/heartbeat` | holder request | `200 {"ok": boolean}` |
 | `releaseRepoLease` | `POST /repos/{repo}/lease/release` | holder request | `200 {"ok": true}`; a wrong holder is a successful no-op |
@@ -389,10 +426,153 @@ creation operation and must not reset timestamps, events, artifacts, or lease
 state when the repository already exists. Event sequence numbering starts at 1
 for each repository independently of every build and other repository.
 
+A `BuildDigest` is the projection of one build's log onto its terminal fact
+and its `observation.recorded` occurrences:
+
+```jsonc
+// BuildDigest
+{
+  "slug": "ab-fix-login-3",
+  "terminal": "done",               // optional: "done" | "aborted", omitted while the log has neither
+  "observations": [                 // ascending-seq pairs for the log's observation.recorded events
+    { "seq": 1, "ts": "2026-07-15T12:00:01.000Z" },
+    { "seq": 4, "ts": "2026-07-15T12:00:04.000Z" }
+  ],
+  "merged": "2026-07-15T12:00:06.000Z" // optional: ts of the log's latest pr.merged, omitted when none
+}
+```
+
+The digest is derived from the event log on every call — the server persists
+nothing and there is no refresh step. Protocol version `3` reshaped the
+digest's `observations` from bare sequence numbers to `{seq, ts}` pairs and
+added the optional `merged` fact, so the harvest pressure gate can evaluate
+launch decisions from digests and the repository journal alone instead of
+reading every build's full history per evaluation. That is a breaking wire
+change, not an additive one: a server that predates it returns the old shape
+and would fail the client's schema parse mid-request, which is why the version
+moved — a stale peer is now rejected at the handshake (`409 conflict`) instead.
+This is the same discipline the transport's exact-match version rules promise:
+wire shapes that independently implemented servers must reproduce update this
+document and the protocol version together.
+
 The build-stream query, artifact, ordering, timestamp, and validation rules
 apply symmetrically to repository journals, including the event-read bounded
 wait of section 3.
 
+### Ticket assets
+
+A ticket asset is a named, versioned bundle of files attached to
+a ticket, keyed by `(repo, ticketId, kind, name)`. These routes live under the
+repository but, unlike the journal routes, **do not require a repository
+record**: assets can precede any journal row, so the repository-existence gate
+does not apply. `{repo}` and `{id}` are percent-encoded path segments. Token
+authorization follows the one-matching-repo column of the matrix (a repo token
+for its own repository, or admin); build and session tokens receive `403 auth`.
+The family is additive, so `REMOTE_STORE_PROTOCOL_VERSION` did not change.
+
+A build also reads the assets it froze at its claim through its own build-scoped
+routes, which a build token may use (no ticket-asset authority needed). The
+server reduces the build's events to find the pinned revision, then returns that
+exact revision, so a later replace or removal never changes the answer and a
+finished build still answers:
+
+| BuildStore operation | HTTP route | Request | Success |
+|---|---|---|---|
+| `getPinnedTicketAsset` (manifest) | `GET /builds/{slug}/ticket-assets?kind=&name=[&rev=]` | required `kind` and `name`; optional `rev` | `200` + `TicketAssetMeta` for the latest pinned revision (or the named pinned `rev`), or `200 null` when the build never pinned it |
+| `getPinnedTicketAsset` (one file) | `GET /builds/{slug}/ticket-assets/file?kind=&name=&rev=&path=` | required `kind`, `name`, `path`; optional `rev` | `200` + `{"contentBase64": string}`, or `200 null` when not pinned; `404` when the revision has no such file |
+
+| BuildStore operation | HTTP route | Request | Success |
+|---|---|---|---|
+| `ticketAssetLimits` | `GET /repos/{repo}/ticket-asset-limits` | none | `200` + `{maxBytes, maxEntries, maxRequestBytes?}` — the effective per-revision ceilings and, when the deployment has one, the largest request or response body it can carry. A server without this route answers `404`; clients treat that as the defaults |
+| `putTicketAsset` | `POST /repos/{repo}/tickets/{id}/assets` | `{kind, name, layout, entries}` | `201` + `TicketAssetMeta` (with its manifest) |
+| `getTicketAsset` (manifest) | `GET /repos/{repo}/tickets/{id}/assets?kind=&name=[&rev=]` | required `kind` and `name`; optional `rev` | `200` + `TicketAssetMeta` — **the manifest only, no bytes** — or `200 null` when the asset is absent or removed (latest) or the revision does not exist |
+| `getTicketAsset` (one file) | `GET /repos/{repo}/tickets/{id}/assets/file?kind=&name=&rev=&path=` | required `kind`, `name`, `path`; optional `rev` | `200` + `{"contentBase64": string}`, or `200 null` when the asset is absent; `404` when the revision has no such file |
+| `listTicketAssets` | `GET /repos/{repo}/tickets/{id}/assets/list[?revisions=1]` | optional `revisions=1` | `200` + `TicketAssetSummary[]` ordered by kind, name, revision: the latest live revision per kind and name, or with `revisions=1` every real revision (no tombstones). Summaries carry no manifest |
+| `removeTicketAsset` | `POST /repos/{repo}/tickets/{id}/assets/remove` | `{kind, name}` | `200` + the removed `TicketAssetMeta`, or `200 null` when no live asset exists |
+
+Wire types:
+
+```jsonc
+// put request: entries are files (content as base64) or explicit directories
+{ "kind": "design", "name": "home", "layout": "tree",   // layout: "file" | "tree"
+  "entries": [
+    { "type": "file", "path": "index.html", "contentBase64": "PGgxPg==" },
+    { "type": "dir",  "path": "img/empty" }
+  ] }
+
+// TicketAssetMeta: dir entries carry no size or blobRef
+{ "repo": "…", "ticketId": "AUT-1", "kind": "design", "name": "home",
+  "revision": 0, "layout": "tree", "size": 1234,         // size = total file bytes
+  "entries": [
+    { "type": "file", "path": "index.html", "size": 1234, "blobRef": "<sha256 hex>" },
+    { "type": "dir",  "path": "img/empty" }
+  ],
+  "createdAt": "2026-10-01T12:00:00.000Z" }
+
+// TicketAssetSummary (list): the same without entries
+{ "repo": "…", "ticketId": "AUT-1", "kind": "design", "name": "home",
+  "revision": 0, "layout": "tree", "size": 1234,
+  "fileCount": 1, "dirCount": 1, "createdAt": "…" }
+```
+
+Semantics every server must reproduce:
+
+- **Revisions** are 0-based per `(repo, ticketId, kind, name)`. Putting the same
+  kind and name again creates the next revision; earlier revisions stay readable
+  by explicit `rev`.
+- **Removal is a tombstone** that takes the next revision number with an empty
+  manifest. The latest row decides liveness: a read without `rev` and the
+  default list skip a removed asset, while an explicit earlier `rev` keeps
+  working (a build that pinned that revision still retrieves it). Re-attaching
+  takes the next revision, so numbers may skip the tombstone. `revisions=1`
+  lists real revisions only.
+- **Validation** (`422 validation`, nothing stored). `kind` and `name` match
+  `[A-Za-z0-9._-]+`, at most 64 characters. Paths are relative and
+  `/`-separated, with no empty, `.`, or `..` segment and no NUL, at most 256
+  UTF-8 bytes (128 per segment); paths are unique across files and directories
+  and no file is the ancestor of another entry. `layout: "file"` has exactly one
+  top-level `file` entry and no directory; `layout: "tree"` may hold any number
+  of entries, including zero (an empty folder; its root is implicit). A revision
+  holds at most 1000 entries (files plus directories) and **26214400 bytes (25
+  MiB)** of file bytes; the error names the limit, for example `ticket asset
+  exceeds the 26214400-byte (25 MiB) limit`.
+- File bytes are content-addressed (`blobRef` is the sha256 hex) in the same
+  blob store as artifacts; the database holds only the manifest.
+
+**Deployment ceilings.** A platform may reject oversized request or response
+bodies before any application code runs (Vercel's functions cap them at 4.5
+MB), so validating on the server alone cannot enforce a limit. A server that
+has such a ceiling advertises it as `maxRequestBytes` on the limits route
+together with the effective `maxBytes`, computed from it as follows. Paths and
+entry counts are bounded, so the worst-case wire overhead is a constant:
+`overhead = 1024 + 1000 × 320 = 321024` bytes, and
+`maxBytes = min(26214400, max(0, floor((maxRequestBytes − overhead) × 3 / 4)))`
+(base64 inflates content by 4/3); `maxEntries` stays 1000. The hosted service
+sets `maxRequestBytes` to 4 MiB, giving an effective per-asset limit of 2904960
+bytes (about 2.8 MiB). The formula is a safe lower bound, not the final
+authority:
+
+- The shipped **client** reads the limits once per store handle and, before any
+  upload, validates against `maxBytes` and `maxEntries` and then compares the
+  exact UTF-8 length of the serialized request with `maxRequestBytes`. A bundle
+  that does not fit is refused locally with `ticket asset exceeds this store's
+  N-byte limit (deployment request ceiling M bytes)` and **no upload request is
+  made**.
+- The **server** re-validates every put against its effective limits and checks
+  every ticket-asset body against `maxRequestBytes` itself, answering `413` (a
+  request) or `422` with a limit-naming message where the platform lets the
+  request through.
+- **Downloads never need a bundle-sized response**: the client reads the
+  manifest and then each file by its own request. The manifest, file, and list
+  routes check the exact serialized length of their response against
+  `maxRequestBytes` and fail with a `413 validation` error naming the asset (or
+  the file, its size, and the ceiling) rather than letting the platform reject
+  it. This matters for a revision stored under an older or higher ceiling:
+  its manifest and smaller files remain retrievable; a file that cannot fit can
+  only be fetched from a store with a higher ceiling. Chunked or ranged transfer
+  is not part of the protocol, so a deployment's effective per-asset limit is
+  its advertised `maxBytes`.
+
 ## 5. Operator-session operations
 
 Operator sessions are a third resource kind: durable orchestrator-conversation
@@ -430,6 +610,7 @@ identity is already the actor.
 | `listSessions` | `GET /repos/{repo}/sessions` | none | `200` + `SessionRecord[]`, creation order (`createdAt`, then the store's creation counter for same-millisecond ties) |
 | `getSession` | `GET /sessions/{id}` | none | `200` + `SessionRecord`; absent is `404` (the shipped client maps this to `null`) |
 | `appendSessionEvent` | `POST /sessions/{id}/events` | event write | `201` + session event envelope (same envelope shape with `"session"` in place of `"build"`) |
+| `appendSessionEventIfCurrent` | `POST /sessions/{id}/events/conditional` | `{"expectedSeq": nonnegative integer, "event": event write}` | appended: `201` + session event envelope; session advanced: `200 null` (mirroring section 3's build compare-and-append) |
 | `getSessionEvents` | `GET /sessions/{id}/events?since={n}&wait={s}` | optional `since` query value, parsed as in section 3; absence defaults to `0`. Optional `wait` in whole seconds, per the event-wait rules of section 3 | `200` + session event envelopes with `seq >` parsed `since`, in increasing sequence order |
 | `appendSessionWithArtifacts` | `POST /sessions/{id}/deposits` | atomic deposit request | `201` + `{event, artifacts}` using session shapes; the substitution algorithm of section 8 applies unchanged |
 | `putSessionArtifact` | `POST /sessions/{id}/artifacts` | artifact input | `201` + session artifact metadata |
@@ -599,7 +780,8 @@ by this rule (their retention belongs to the open archival thread), and open
 streams are never pruned. A read of a stream whose chunks were pruned returns
 no chunks, `status: "closed"`, and the artifact reference.
 
-These additions are purely additive: the protocol version stays `2`, and a
+These additions were purely additive in the version they landed in (protocol
+`2`, where the stream routes were introduced), and a
 conforming server implements the stream routes together with this document's
 rules exactly as it does for the event and artifact routes.
 
@@ -675,12 +857,17 @@ resource access; an explicit resource whose id is `"*"` is not admin.
 
 ### Resource authorization matrix
 
-| Token resource | `/builds` create/list | one matching build | `/repos` ensure | one matching repo | `/repos/{repo}/sessions` create/list | one matching session |
-|---|---:|---:|---:|---:|---:|---:|
-| admin (`build: "*"`) | yes | any | yes | any | yes | any |
-| build | no | exact id only | no | no | no | no |
-| repo | no | no | no | exact id only | yes | no |
-| session | no | no | no | no | no | exact id only |
+| Token resource | `/builds` create/list | one matching build | `/repos` ensure | one matching repo | `/repos/{repo}/sessions` create/list | `/repos/{repo}/build-digests` | `/repos/{repo}/state-events` | `/repos/{repo}/tickets/{id}/assets` and `/repos/{repo}/ticket-asset-limits` | one matching session |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| admin (`build: "*"`) | yes | any | yes | any | yes | any | any | any | any |
+| build | no | exact id only | no | no | no | no | no | no | no |
+| repo | no | no | no | exact id only | yes | exact id only | exact id only | exact repo only | no |
+| session | no | no | no | no | no | no | no | no | exact id only |
+
+The snapshot routes (`/builds/{slug}/snapshots/{reducer}` and
+`/repos/{repo}/snapshots/{reducer}`) follow the one-matching-build and
+one-matching-repo columns: a build token reads and writes only its own build's
+snapshots, a repo token only its own repository's.
 
 A valid token used for the wrong resource receives `403 auth`. Resource scope
 gates all operations, including reads, artifact operations, and leases. A
@@ -793,8 +980,8 @@ The shipped server maps failures as follows:
 | `403` | `auth` | Valid token with the wrong resource scope or event-session attribution |
 | `404` | `not-found` | Unknown route, unsupported method, unknown build, unknown repository, unknown session, or an unknown or foreign-scoped stream |
 | `409` | `conflict` | Missing/mismatched package or protocol identity, duplicate build creation, appending to a closed stream (`stream "…" is closed`), or a backing conflict reported as already existing |
-| `413` | `validation` | Decoded artifact or serialized stream batch exceeds the configured ceiling; the message names the ceiling |
-| `422` | `validation` | `EventValidationError` from build, repository, or session catalog validation; its message is preserved verbatim |
+| `413` | `validation` | Decoded artifact or serialized stream batch exceeds the configured ceiling; a ticket-asset request or response exceeds the deployment's request ceiling; the message names the ceiling |
+| `422` | `validation` | `EventValidationError` from build, repository, or session catalog validation, or a ticket-asset validation failure (including the 25 MiB limit); its message is preserved verbatim |
 | `500` | `internal` | Any other unexpected backing or server failure; the thrown error message is returned |
 
 Authentication runs before resource lookup, and session authorization runs
@@ -916,11 +1103,12 @@ Four shipped behaviors do not add `BuildStore` routes:
   store lifecycle; there is no close endpoint.
 - `GET /health` is outside the `BuildStore` interface. It is always open and
   returns exactly `200 {"ok":true,"autobuildVersion":"<package>",
-  "protocolVersion":"2"}`. It reports HTTP-process availability and identity,
+  "protocolVersion":"3"}`. It reports HTTP-process availability and identity,
   not a deeper backing-store transaction or migration check.
 
-There is no push/WebSocket subscription protocol, batch-read route,
-repository listing, artifact deletion, or server deployment API.
+There is no push/WebSocket subscription protocol, repository listing, artifact
+deletion, or server deployment API. The one repo-scoped batch read is the
+build-digest route of section 4; no other batch-read route exists.
 
 ## 12. Conformance
 

package/skills/guide/references/remote-ticket-protocol.md

@@ -3,7 +3,7 @@
 The hosted ticket protocol exposes the complete `TicketSource` port without
 exposing backend credentials. It shares the Autobuild and remote protocol
 version headers with the remote BuildStore. Both must exactly match the service;
-this release uses remote protocol version `2`.
+this release uses remote protocol version `3`.
 
 ## Authentication and context
 

package/skills/guide/references/setup.md

@@ -59,7 +59,7 @@ DEBIAN_FRONTEND=noninteractive apt-get install -y chromium""" },
 
 [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"
 ```
 
 Use a `vercel-ai-gateway/...` Pi model with `AI_GATEWAY_API_KEY` in the
@@ -220,14 +220,17 @@ same lockstep window. If the release is cut but the store upgrade lags, guests
 carrying the new distribution fail loudly against the old store (409) rather
 than running silently stale.
 
-Provisioning records the installed distribution's version in the guest's
-`/opt/autobuild/.distribution-version` marker. A reused persistent sandbox
-whose marker disagrees with the version the current system would deliver —
-which includes every guest provisioned before the marker existed — is
-refreshed in place (archive re-fetched, extracted, and production-installed)
-before being reused, so an upgraded dispatcher retrofits its existing guests
-instead of resuming a stale distribution. A refresh failure deletes the
-sandbox so the next provisioning pass rematerializes it from scratch.
+Provisioning records the installed distribution's identity — package version
+and remote-store protocol version — in the guest's
+`/opt/autobuild/.distribution-version` marker. Every path that launches guest
+code in an existing sandbox — provisioning reuse, harvest reuse, the operator
+sandbox, and build execution restart after a lease sweep — compares the marker
+against the identity the current system would deliver and, when they disagree
+(which includes every guest provisioned before the marker existed), refreshes
+it in place (archive re-fetched, extracted, and production-installed) first,
+so an upgraded dispatcher retrofits its existing guests instead of resuming a
+stale distribution the hosted store would reject. A refresh failure deletes
+the sandbox so the next provisioning pass rematerializes it from scratch.
 
 After a lockstep upgrade, confirm a fix-bearing guest from the guest
 perspective:

package/skills/implement/SKILL.md

@@ -21,6 +21,9 @@ You never push — the push is plumbing that happens when you finish.
    operator's answer to the escalation that blocked this build). The manifest's
    `feedback` field names which one this round is, and is absent when the round
    carries none.
+   When the manifest lists `assets`, they are the build's pinned ticket assets
+   under `.ab/assets/<kind>/<name>/`; read them with the spec. A `design` asset
+   is a contract on observable visual and reference outcomes, not on implementation — what you build must satisfy it, while how stays yours.
 2. Execute the plan. Commit in coherent increments with real messages —
    the commit history is part of the paper trail.
 3. Run the repo's checks yourself before finishing (the config's typecheck /

package/skills/operate/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: operate
+description: You are the embedded orchestrator for one repository - the agent that answers its operator sessions, watches its builds, unblocks them, and discusses direction. You run inside the hosted service with the operator tool registry bound in process. Use this skill as your operating manual — it defines your role, the complete tool surface, the approval rules, and when to stop and ask the operator instead of acting.
+---
+
+# Operating the repository
+
+You are the orchestrator session for one repository. You file tickets, watch
+builds, unblock them, answer operator questions, and discuss direction. You
+are not a build phase: you never run pipeline steps, never edit the
+repository, and never touch a checkout. Your entire reach is the operator
+tool registry bound into your turn.
+
+## How you run
+
+Each of your turns is one durable agent loop:
+
+- The conversation is reconstructed from durable state on every invocation.
+  Nothing is held in memory between invocations; if your turn suspends and
+  resumes in a fresh invocation, the model input is identical.
+- Your output streams as protocol parts onto the turn's stream. The operator
+  sees it live in the session.
+- Every tool call is attributed to the session's operator — the human actor
+  named on every write is that operator, with your session as the delegate.
+  Act accordingly: you are spending their authority.
+- Your tools target exactly one repository, the session's own. You never
+  supply a repository argument; it is bound for you.
+
+## Suspension
+
+Your turn can stop in two ways, and both are normal:
+
+- **Budget.** Each invocation has a wall-clock budget. When it runs out, the
+  turn suspends (`cause: budget`) and resumes in a fresh invocation — a new
+  provider call — with the identical conversation. Never assume a turn
+  died; never repeat work a checkpoint already covers.
+- **Approval.** Some tools are on the repository's approval list. Calling
+  one suspends your turn (`cause: approval`) until the operator answers.
+  An `approve` answer executes the call; a `deny` answer hands you a denied
+  tool output — treat it as a firm no, say so briefly, and move on. Tools
+  not on the list run without pause.
+
+When suspended, just stop cleanly. Anything important you want to say should
+already be in your streamed output before the suspension point.
+
+## The tool surface
+
+Your tools are the operator registry. The read-only ones are always safe:
+
+- `builds.list` — active, queued, or all builds, with effective status.
+- `builds.get` — one build's detail.
+- `builds.events` — one build's event log from a cursor (use a cursor; logs
+  are long).
+- `builds.artifact` — one artifact's bytes, base64-encoded.
+- `repository.status` — the repository's derived status.
+- `harvest.status` — the observation workflow's current state.
+
+The mutating ones carry the operator's authority — prefer the narrowest
+that does the job, and say what you are doing before you do it:
+
+- `builds.control` — pause, resume, abort, or discard a build. `abort` and
+  `discard` are destructive to in-flight work.
+- `builds.answer` — answer an open escalation: guidance text, a retry, a
+  review-round ceiling, or a revise-spec resolution.
+- `tickets.list`, `tickets.get` — read the ticket queue and one ticket.
+- `tickets.create` — file a new ticket from a conversation.
+- `tickets.update`, `tickets.block`, `tickets.unblock` — edit fields and
+  blocker relations.
+- `tickets.move` — move a ticket between workflow states. Moving a ticket
+  into the ready state sends it to dispatch — do that only when the ticket
+  genuinely conforms and the operator's intent is clear.
+- `notes.read`, `notes.write` — the operator-notes artifact: durable,
+  human-readable notes about this repository's operation. Write what the
+  next turn (or the next human) will need; read it before acting on
+  anything you'd otherwise guess.
+- `repository.settings` and `repository.bulk_control` — repository-wide
+  switches; use sparingly and only on clear instruction.
+- `harvest.control` — start or control an observation run.
+
+Every tool returns the operator API's shapes: results, or a typed failure
+(`kind`, `error`, `code`). A refusal is information, not an exception:
+report it, adapt, and carry on.
+
+## The attention set
+
+When the session has wake settings, the dispatcher wakes you when a build
+event matching them lands. A wake turn's first message carries the event
+record and the build's reduced state as JSON. Typical wakes and what to do:
+
+- `escalation.raised` / `phase.failed` / `infrastructure.failed` — read the
+  escalation and the build's recent events; if the operator notes or the
+  conversation already answer it, say so; otherwise summarize and decide
+  whether it needs the operator.
+- `finalize.completed` / `build.completed` / `pr.merged` / `pr.closed` /
+  `pr.conflicted` / `build.aborted` — acknowledge outcome changes that the
+  operator should know about, and file or move tickets when the outcome
+  makes that obviously right.
+- Anything else matching the wake settings — read the event, then decide.
+
+Do not re-derive history the build's events already tell you; read events
+with a cursor and keep it short.
+
+## When to escalate instead of act
+
+Stop and ask the operator — in plain streamed text — whenever:
+
+- The action is destructive and not clearly instructed (`abort`, `discard`,
+  a bulk control, a repository-wide setting).
+- Two readings of the operator's intent diverge in cost or risk.
+- You would be guessing about product direction, priorities, or scope.
+- A tool refusal repeats and you cannot resolve it with the tools you have.
+- The attention event is one you cannot act on with the registry at all.
+
+Filing a ticket IS acting — do it when the request is concrete. Asking is
+not a failure; an unasked destructive action is.
+
+## Boundaries
+
+- You never claim to have done anything outside the registry. If you cannot
+  observe it with a tool, say you cannot observe it.
+- You never invent repository identity, ticket ids, or build slugs; every
+  id you act on came from a tool result or the conversation.
+- You do not run concurrent work: one turn at a time, and a message that
+  arrives mid-turn is answered after the current turn ends.
+- The operator's notes artifact is shared ground truth; keep it current
+  when you learn something durable.

package/skills/plan/SKILL.md

@@ -19,6 +19,10 @@ write product code in this phase.
    reviewer's findings) or `.ab/guidance.json` (a human operator's answer to
    the escalation that blocked this build). A round never carries both, and a
    round may carry neither.
+   When the manifest lists `assets`, they are the build's pinned ticket assets
+   under `.ab/assets/<kind>/<name>/`; read them with the spec. A `design` asset
+   is a contract on observable visual and reference outcomes, not on implementation — the plan must satisfy it, while how stays yours. The spec cites
+   assets by kind and name.
 2. Read the spec, then the codebase. The spec says what and why; you decide
    how. Explore enough of the code to name real files and real seams. When an
    approach touches a third-party service, ground it in the provider's own

package/skills/plan-review/SKILL.md

@@ -17,7 +17,11 @@ verdict travels the typed channel; nothing you print matters to the pipeline.
    lists finding ids a human explicitly dismissed.
 2. Judge the plan on exactly these axes:
    - **Spec conformance** — does executing this plan satisfy every
-     acceptance criterion? Does anything in it exceed the spec's scope?
+     acceptance criterion? Does anything in it exceed the spec's scope? A
+     pinned `design` asset (listed under `assets` in `.ab/context.json`, files
+     under `.ab/assets/<kind>/<name>/`) is a contract on observable visual and reference outcomes, not on implementation: open it and flag a plan that
+     contradicts or ignores it, as you would an unmet criterion. A gap in the
+     asset is not a reason to invent requirements.
    - **Groundedness** — do the files and seams it names actually exist and
      work the way the plan assumes? Spot-check the code; a plan built on a
      wrong assumption fails in `implement` at ten times the cost. For every

package/skills/spec/SKILL.md

@@ -37,7 +37,9 @@ in order, but as a conversation, not a form:
 3. **Out of scope.** Ask what adjacent work is explicitly excluded. Propose
    candidates — the tempting expansions you noticed while reading the code.
 4. **Evidence.** Link what exists: the error rates, the user reports, the
-   prior discussion.
+   prior discussion. Designs and other reference material are attached as
+   ticket assets and cited by kind and name — see
+   [Designs and reference material](#designs-and-reference-material).
 
 Draft the spec in full, show it, iterate until the user accepts. Then create
 the ticket with the spec as its body using `ab ticket create`. Honor a
@@ -102,6 +104,9 @@ spec to a file, then sync only the body:
 ab ticket update <ticket> --body spec.md
 ```
 
+If the human points at a design or other reference material while fleshing out,
+follow [Designs and reference material](#designs-and-reference-material).
+
 Omitted metadata is preserved, including title, labels, assignee, state, and
 provider-specific fields. If grooming changes dependencies, use the same
 configured-source surface rather than a provider API or MCP call:
@@ -114,10 +119,48 @@ ab ticket unblock <ticket> <blocker-id>
 The first id is the ticket being amended. Both relationship operations are
 idempotent; adding validates the blocker exists and rejects a self-block.
 
+## Designs and reference material
+
+When the user points at a design, mock, prototype, screenshot set, sample
+payload, or other reference material, export it during this conversation, so
+no build worker ever has to convert a link. Use whatever tools this session
+has (a browser, a connector, a screenshot tool, fetch, a CLI) and do not tie
+the result to any one design tool. Produce portable static files in one
+folder: a static reference page (`index.html`, with its assets inline or
+alongside) plus screenshots of the key states and widths.
+
+Attach the folder (or a single file) to the ticket as a `design` asset:
+
+```
+ab ticket attach <id> design <path> [--name <name>]
+```
+
+The ticket must exist first. For a new ticket, create it in a non-ready
+staging state, attach, and check with `ab ticket show <id>`. Then place it
+where the human asked: if the intended destination is ready, move it there
+last, so a build cannot claim it before its assets exist; otherwise leave it
+in its destination (or the configured create state) and do not promote it. Attaching the same
+kind and name again makes a new revision. Assets are frozen into a build when
+it claims the ticket; attaching afterward does not reach a build already
+running.
+
+Cite the asset in the spec's Evidence by kind and name (``design `home-page` ``),
+never by external link. The spec still states the underlying need; the asset is
+the visual contract.
+
+If this session cannot export the design (no tool for it, an auth wall, or
+files over the store's size limit), keep the external link in Evidence and say
+plainly, in the spec and to the human, that builds cannot read it, so the
+planner does not treat it as a contract.
+
 ## Rules
 
-- The spec says **what and why, never how** — if the user hands you a
-  design, capture the underlying need and park the design in evidence as
+- The spec says **what and why, never how.** An exported, attached `design`
+  asset is a contract on observable visual and reference outcomes — layout,
+  content, states, copy, look — that plan, review, and verify judge against;
+  it is not a contract on implementation, and component structure, libraries,
+  and file layout stay the planner's. A technical design or proposed approach
+  the user hands you, and any link you could not export, goes in Evidence as
   "proposed approach", clearly non-binding on the planner.
 - Don't gold-plate: a spec is buildable when a planner could start, not when
   every question is answered. Thin-but-groomed is a valid state — dispatch