@defrex/autobuild 0.8.0 → 0.9.0

package/skills/guide/SKILL.md

@@ -65,6 +65,13 @@ spec → plan ⇄ plan-review → implement ⇄ code-review → verify:* → fin
   claims tickets that pass the `[tickets]` ready
   gate, chooses a short immutable slug from the final conforming spec, and
   starts builds up to the top-level `capacity` bound.
+- **Ticket assets** — files or folders attached to a ticket (see
+  [Ticket assets](#ticket-assets)) are frozen into the build at claim and
+  appear under `.ab/assets/` in every phase, as inputs alongside the spec.
+  A `design` asset is part of the contract: `plan`, `plan-review`, `implement`,
+  `code-review`, and agent verify steps judge against it, as a contract on
+  observable visual and reference outcomes, not on implementation. Other kinds
+  are reference material.
 - **`spec`** — the ticket's spec becomes the build's contract. The `ab-spec`
   skill is the human-interactive surface for producing it, and it runs *before*
   a build exists.
@@ -337,7 +344,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"
 ```
 
 `timeoutSeconds` is required (60–86400; Hobby currently caps at 2700), `vcpus`
@@ -413,6 +420,12 @@ Names must already exist in `[verify].steps` with matching tables; duplicates,
 blanks, unknown names, malformed metadata, and omission of an `always = true`
 step make the planner's `ab done` fail before `plan.completed` is appended.
 
+An agent verify step is handed the build's pinned ticket assets under
+`.ab/assets/` (listed in `.ab/context.json`) as well as the spec. A verify skill
+should treat a `design` asset as part of the contract, a contract on observable
+visual and reference outcomes, not on implementation, and judge the result
+against it.
+
 An agent verify step selects `[roles.<step>]` by its **logical step name** —
 the name in `[verify].steps`, not the skill it runs. An agent finalize
 post-step follows the same rule.
@@ -782,15 +795,21 @@ environment variable instead and say why.
 
 ### `[orchestrator]`
 
-Gates the operator-sandbox feature (AUT-340): a persistent, **credential-free**
-environment per operator × repository that an operator agent drives through the
-`sandbox.*` registry tools (`ab mcp`, and every later binding). The whole table
-is **closed to unknown keys** and restart-classified: changing it requires a
-dispatcher restart.
+Gates the operator-agent feature (AUT-340, AUT-342): the persistent,
+**credential-free** sandbox environment per operator × repository that an
+operator agent drives through the `sandbox.*` registry tools (`ab mcp`, and
+every later binding), and — when the embedded orchestrator is enabled — the
+turn runner that answers operator sessions and wakes on build attention
+events. The whole table is **closed to unknown keys** and restart-classified:
+changing it requires a dispatcher restart.
 
 | Field | Default | Allowed / constraints | Effect |
 |---|---|---|---|
-| `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` | — (required when `enabled = true`) | nonblank provider-qualified string, same vocabulary as `[roles]` | The turn runner's model, resolved through the deployment's gateway credential; a leading `vercel-ai-gateway/` prefix is accepted and stripped. |
+| `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. |
+| `approvals` | `["builds.control:abort", "builds.control:discard", "builds.answer:revise-spec", "sandbox.publish", "tickets.move:ready"]` | array of `tool` or `tool:qualifier` strings | Registry tool calls that suspend a turn until the operator answers. Empty (`[]`) means none — autonomous operation. An entry naming an absent or unknown tool is **inert by design**, never an error. A qualified entry applies to one discriminator value only (`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. Absent inherits the default attention set (the events `ab watch` filters on by default); an explicit `[]` means never wake — message-only. Each glob must match at least one build event type. Existing sessions never retroactively inherit; an explicit wake update always wins. |
 | `sandbox` | — | strict subtable | The sandbox behavior knobs; absence reads as the defaults below. |
 
 `[orchestrator.sandbox]` fields:
@@ -814,6 +833,20 @@ and archiving an operator's last session are **destructive** (reset re-provision
 from the current base head); there is at most **one** environment per operator
 and repository.
 
+Publication: `sandbox.publish` takes a title (1–200 characters), an optional
+body (≤65,536 characters), and an optional explicit commit, and takes your
+sandbox's current head commit to a pull request. It refuses when the checkout
+has uncommitted changes — tracked or untracked (the sandbox's own provisioning
+marker is excluded) — and when the commit is not a descendant of the base head
+recorded when the sandbox was provisioned or last reset — a pre-existing environment without a recorded
+base head asks you to run `sandbox.reset` first. The rule is PR only, never the
+base branch: the sandbox itself never pushes and holds no credential — the push
+and the PR creation are kernel plumbing through the workspace provider's
+publication capability, to one deterministic operator branch per operator and
+repository, so a later publish updates the same PR's head. A publication is a
+repository-journal fact naming the operator, the session, the branch, the
+commit, and the PR; a refused or failed attempt is journaled too.
+
 ## Setup and upgrades
 
 **`ab init <target> [--force]`** runs *outside* build sessions — it takes a
@@ -827,7 +860,7 @@ repo path, needs no `AB_*` environment, and is safe to re-run. It:
   `[commands]`, no verify or finalize steps, a valid local ticket gate, and one
   explicit runtime solely as a schema placeholder. It reads no package or
   language manifest and invents no command.
-- Vendors 11 skills before handoff, including the locally editable
+- Vendors 12 skills before handoff, including the locally editable
   [repository setup reference](references/setup.md) in the installed `ab-guide`
   tree. On an interactive terminal it starts the selected coding-agent CLI in
   the target repository with a short prompt to read that reference and
@@ -1070,6 +1103,37 @@ subcommand accepts `--json`, which emits one bare JSON value and no prose: a
 `Ticket[]` for `list`, and the complete resulting `Ticket` for `create`,
 `update`, `block`, `unblock`, `show`, or `move`.
 
+### Ticket assets
+
+A ticket asset is a file or folder attached to a ticket and stored in the
+BuildStore, never in the ticket source: a design export, reference screenshots,
+a sample payload. Each has a kind and a name.
+
+- `ab ticket attach <id> <kind> <path> [--name <name>] [--json]` stores `<path>`
+  (default name: its basename). Attaching the same kind and name again makes a
+  new revision; earlier ones stay retrievable. Over the store's size limit
+  (25 MiB by default, lower on a hosted deployment) it is refused. Attach and
+  remove leave a note on the ticket naming the asset.
+- `ab ticket show <id>` lists the current assets; with `--json` the ticket
+  gains an `assets` array.
+- `ab ticket asset get <id> <kind> <name> <dest> [--rev <n>]` downloads the
+  exact bytes of the latest (or given) revision; `ab ticket asset rm <id> <kind>
+  <name>` drops it from the current assets.
+- **Frozen at claim.** A claim pins the current revisions into the build. A
+  later attach or remove leaves a running build alone; a human answer with
+  `--revise-spec-from-ticket` pins again. `ab build asset get <slug> <kind>
+  <name> <dest> [--rev <n>]` downloads what the build froze, also after it ends.
+- **Where phases find them.** `ab context` writes each pinned asset to
+  `.ab/assets/<kind>/<name>/` (a file asset is the single file inside that
+  directory) and lists them under `assets` in `.ab/context.json` with kind,
+  name, revision, layout, size, and path. The key is absent when the build has
+  none.
+
+By convention the `design` kind is a visual or reference contract, exported to
+static files when the ticket is groomed, so no build converts a link. The spec
+cites it by kind and name. See [the lifecycle](#the-lifecycle) for how phases
+judge against it.
+
 ## Retrieving build artifacts
 
 `ab artifact download <build> <kind>[@rev] --output <file> [--store <ref>]`
@@ -1081,6 +1145,17 @@ Inside a phase, a complete ambient tuple permits only the ambient build; a
 foreign build or malformed/partial identity is rejected. Use the exact pinned
 `@rev` from a PR attachment command.
 
+Repository-scoped streams have their own form:
+`ab artifact download stream:<id>[@rev] --output <file> [--store <ref>]`. A
+stream id is store-assigned and globally unique, so no build argument is
+needed; the command resolves the stream, requires it to be repository-scoped
+and owned by this repository, and retrieves the artifact its close finalized
+(§7.6) — an open stream has no artifact yet. This form is strictly an operator
+read: under any complete ambient build or Harvest identity it fails closed
+(§8.2), since repository-scoped targets are never reachable by ambient
+own-build or own-harvest authority. Find stream ids in the session rows of
+`ab harvest status`.
+
 In a build session, `ab artifact put <kind> <file> --attach` atomically deposits
 the exact bytes and designates that revision for the PR. A later designation of
 the same kind replaces it; distinct kinds remain distinct attachments. The
@@ -1214,16 +1289,19 @@ on its first paint; clearing the hold removes both on the next poll. The hold
 survives a restart and is not defeated by re-running `ab dispatch`.
 
 `--auto-merge` and `--no-auto-merge` similarly set the durable repository
-claim-time default; omission reuses stored state, falling back to OFF only when
+auto-merge default; omission reuses stored state, falling back to OFF only when
 no fact exists. The forms are mutually exclusive independently of the intake
 pair. Global-row `m` re-reads current state, appends the opposite value, and
 posts a dispatcher notice. When on, each fresh dispatcher claim records the
 existing human-authored `build.auto-merge-requested` fact immediately after
 `build.created` and before runner launch. The first visible build frame therefore
-carries `auto merge`. This is a creation-time seed, not policy: changes never
-touch existing builds, resumed/adopted logs or other creation paths never sample
-it, and build-row `m` remains independent (a seeded build can be cancelled while
-the global default stays on). Both repository settings are independently
+carries `auto merge`. The default is also a bulk action over current builds:
+on each change the dispatcher reconciles every non-terminal build against the
+newest fact, requesting consent when it turns on and withdrawing it when it
+turns off, attributed to the toggling operator exactly as a row keypress would
+be. A per-build toggle overrides its build's state until the global row is
+toggled again, so a seeded or fanned build can still be cancelled while the
+global default stays on. Both repository settings are independently
 last-write-wins by event sequence. They are stored in the BuildStore, not in
 `autobuild.toml`; propagation uses polling, not a push channel.
 
@@ -1249,10 +1327,13 @@ settles every exhaustion barrier. Exhaustion and escalation remain terminal.
 Escalation's row is dismissed only by a post-terminal human resume request
 followed by its later kernel acknowledgement, never by the request alone.
 
-A build with auto-merge off has no auto-merge token. Requested, enabled, and
-cancelling states all read `auto merge`: cyan means requested locally but not
-yet applied on GitHub, green means native auto-merge is enabled, and yellow
-means cancellation is in flight. The token disappears when cancellation lands.
+Every build row renders an explicit `auto merge <state>` token, including off:
+cyan means requested locally but not yet applied on GitHub, green means native
+auto-merge is enabled, yellow means cancellation is in flight, and dim means
+off — turning red while the repository default reads ON, so the
+consent mismatch is visible without opening the detail view. A build parked on
+an open PR with no consent carries the reason on its merge step, naming the
+per-build control that requests it.
 Merge conflicts recover automatically: the gate defers, the pipeline re-enters
 reconcile, and verify re-runs before consent is re-examined — the reconcile
 step on the build row is the only indication, and uncomputed mergeability
@@ -1509,10 +1590,12 @@ stream:<id>` retrieves the closed session's finalized document.
 Harvest sessions stream the same protocol into *repository-scoped* streams:
 the harvest runner's synthesize and review brackets each get one stream
 (`phase` spelled `harvest:<step>`), with `harvest.session.started` carrying
-the stream id. Find them via that `stream` field or the harvest journal
-(`ab watch --repository`); a closed stream finalizes to a repository-scope
-`stream:<id>` artifact. The harvest run id is not on the stream — recover it
-from the journal event that names the stream.
+the stream id. `ab harvest status` shows each run's sessions the way build
+status does — one row per session with its stream id and open/closed status
+(`session hs_… (harvest, synthesize@1) stream st_… (open)`). Once a stream
+closes, its finalized document is a repository-scoped `stream:<id>` artifact,
+and `ab artifact download stream:<id>` retrieves it; the stream form is an
+operator-only read (ambient phase identity fails closed).
 
 **`ab watch [<slug>...] [--repository] [--event <glob>]... [--since <cursor>]
 [--timeout <dur>] [--interval <dur>] [--count <n>] [--json] [--store <ref>]`**
@@ -1553,7 +1636,10 @@ The watch ends with exit 0 when `--timeout` elapses (30 minutes by default;
 gone terminal; with no slugs named, an empty set of active builds does not end
 it. Usage errors, scope violations, unknown slugs, and cursor rejection exit 1
 before any record. A store read that fails after the watch has started is
-reported once on stderr and retried without duplicating or skipping any event.
+reported on stderr once per failing read source — locally the poll cycle is
+one source, while against an `http(s)` store each tracked stream and the
+discovery pass carries its own failure streak — and retried without
+duplicating or skipping any event.
 Against a local store the default cadence polls every 1 second. Against an
 `http(s)` store each tracked stream long-polls instead — one held request per
 stream waits up to 25 seconds for the next event, requests run concurrently,
@@ -1635,8 +1721,11 @@ condition (one record with `condition` null, showing how the build ended); 3 —
 stdout is a bare `{"cursor": …}` object for the final position, plus one line
 on stderr); 4 — interrupted by SIGINT before any condition was satisfied (same
 cursor behavior as 3). The default poll interval and `--interval` match
-`ab watch`. A store read that fails while waiting is reported once on stderr
-and retried without missing or duplicating a condition. The command is
+`ab watch`. A store read that fails while waiting is reported on stderr once
+per failing read source — locally the poll cycle is one source, while
+against an `http(s)` store each tracked build and the discovery pass carries
+its own failure streak — and retried without missing or duplicating a
+condition. The command is
 read-only — it appends no event, takes no lease, and creates no record — and
 deciding what to do about a match stays with the caller's skill.
 
@@ -1770,12 +1859,16 @@ default, when you need to know what this repo's version says).
 | `ab-code-review` | `code-review` phase | Fresh skeptic: review the implementation diff against spec and plan, same verdict vocabulary. |
 | `ab-reconcile` | `reconcile` phase (epilogue) | Resolve a conflicted PR with one merge commit, base merged *into* the build branch. Never rebases. |
 | `ab-finalize` | `finalize` phase | Write the PR description for a green build; the kernel opens the PR. |
-
-Autobuild installs 11 skills. Everything except `ab-spec`, `ab-tickets`, and
-`ab-guide` is **runner-invoked** by the kernel and carries
-`disable-model-invocation: true` — do not invoke a phase skill yourself, and do
-not remove that key to make one convenient to call. A model starting a pipeline
-phase by pattern-matching a description is exactly what the flag prevents. The
-three exceptions drive no phase, which is the criterion for membership (§16.3):
-`ab-spec` and `ab-tickets` are human/agent-facing pre-build surfaces, and
-`ab-guide` is read-only reference including the setup handoff guidance.
+| `ab-operate` | hosted only | The embedded orchestrator's own operating manual: its role, the registry tool surface with the approval semantics, the attention set, wake-trigger input, budget/approval suspension, and when to escalate to the operator rather than act. Invoked by the embedded orchestrator, never vendored into a build session. |
+
+Autobuild installs 12 skills. Everything except `ab-spec`, `ab-tickets`, and
+`ab-guide` carries `disable-model-invocation: true` — do not invoke a phase
+skill yourself, and do not remove that key to make one convenient to call. A
+model starting a pipeline phase by pattern-matching a description is exactly
+what the flag prevents. Those three exceptions drive no build phase, which is
+the criterion for membership (§16.3): `ab-spec` and `ab-tickets` are
+human/agent-facing pre-build surfaces, and `ab-guide` is read-only reference
+including the setup handoff guidance. The fourth skill outside the
+model-invocable set, `ab-operate`, is not a build-phase skill either: it is the
+embedded orchestrator's own operating manual, read by the hosted turn runner as
+its system prompt and never invoked by a model in a build session.

package/skills/guide/references/operator-api.md

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

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,7 +290,7 @@ 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 |
@@ -357,7 +357,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 +369,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 +381,12 @@ 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` |
 | `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 +396,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 +580,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 +750,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 +827,12 @@ 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 |
 
 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 +945,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 +1068,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: