@defrex/autobuild 0.9.0 → 0.10.1

package/README.md

@@ -2,72 +2,29 @@
 
 # Autobuild
 
-**Tickets in, PRs out. No babysitting required.**
+**Tickets in, Product out.**
 
 </div>
 
-Every build runs headless, so ten tickets in flight cost the same 
-attention as one. You groom tickets in, you review pull requests out. 
-Agents do the work, and deterministic code keeps them honest.
+Autobuild runs coding agents through a fixed pipeline that plans, implements,
+reviews, and verifies every ticket before it merges. You groom tickets in and
+review pull requests out; agents do the work, and deterministic code keeps
+them honest.
 
 ![The autobuild dispatch dashboard with four builds in flight, each partway
 through the pipeline](docs/assets/headline-wide.png)
 
-## Groomed ticket in, reviewed PR out
-
-Running several coding agents by hand doesn't scale well. Every session wants
-prompts, permissions, and attention, and your focus becomes the ceiling.
-With Autobuild, each build runs the whole loop headlessly and escalates only
-when it is truly blocked. With attention off the critical path, throughput
-is only limited by how fast you can write good tickets.
-
-Headless is safe because the pipeline is deterministic code, not model
-judgment. State lives in a typed, append-only event log, phase transitions
-are owned by tested code, and every build leaves a queryable paper trail. Your
-merge gates are never bypassed: a PR lands when your required checks and your
-consent say it lands.
-
-The loop also feeds itself. While building, agents record observations —
-latent bugs, worthwhile refactors, follow-ups they noticed but rightly left
-alone. A harvester distills them into proposed tickets and files them for
-triage; approve one and it runs the same loop.
-
-Every seam is an adapter: ticket sources (the hosted service with database or
-Linear backend, direct Linear, local files, or a configured plugin), agent runtimes (Claude, Codex, Pi, or a configured plugin), the forge
-(GitHub via `gh`, credential-free local Git, or a configured plugin), workspaces,
-and the build store all sit behind
-narrow interfaces. Trusted Bun plugins declared in `autobuild.toml` can register
-third-party ticket, runtime, workspace, and forge adapters against the versioned
-`@defrex/autobuild/plugin-sdk` surface. Repositories may also opt into the shipped
-`vercel-sandbox` workspace provider: the complete build runs in an isolated
-Vercel VM while the local supervisor retains credentialed branch/PR publication.
-The default remains a local Git worktree. See the [workspace configuration and
-security contract](docs/configuration.md#vercel-sandbox).
-Teams that need one durable store across hosts
-can deploy the optional [hosted service](packages/hosted-store-service/README.md),
-which also serves a GitHub-authenticated browser dashboard, can own ticket
-persistence and external tracker credentials, and can run the dispatcher itself on a schedule (see [the hosted dispatcher](docs/hosted-dispatcher.md)). Repository identity across the
-Store, dispatcher, query commands, and that dashboard is the repository's
-normalized origin URL (e.g. `https://github.com/defrex/autobuild`), never a
-checkout path; pre-origin records are not migrated. The web UI uses a server-managed
-session; automation clients can use the versioned [operator API](docs/operator-api.md)
-for the same controls and projections without exposing service credentials, and
-external MCP agents connect through the [hosted MCP server](docs/mcp.md).
-
 ## Quickstart
 
 You need [Bun](https://bun.sh), `git`, and the local prerequisites for the
-agent runtime you select: Claude Code, Codex CLI, or Pi. Choosing the GitHub
-forge also requires an authenticated [`gh` CLI](https://cli.github.com)
-(`gh auth login`) or an exported `GITHUB_TOKEN`/`GH_TOKEN`; the local-git forge needs no
-account or remote.
-Init suggests only runtimes whose executable and/or provider authentication is
-usable on your machine.
+agent runtime you select: Claude Code, Codex CLI, or Pi. The GitHub forge also
+needs an authenticated [`gh` CLI](https://cli.github.com) or an exported
+`GITHUB_TOKEN`/`GH_TOKEN`; the local-git forge needs no account or remote.
 
 <!-- release-install:start -->
 
 ```sh
-bun add -g @defrex/autobuild@0.9.0
+bun add -g @defrex/autobuild@0.10.1
 ```
 
 <!-- release-install:end -->
@@ -78,44 +35,36 @@ Then, from the repository you want built:
 ab init
 ```
 
-Vendors the editable `ab-*` skills, writes a stack-neutral config, and hands
-repository-aware setup to a coding agent. Follow the canonical
-[installation and setup procedure](docs/setup.md) to keep local worktrees or
-explicitly configure Vercel, then commit the setup and check its real execution
-environment without creating build history:
-
-```sh
-ab init --validate
-```
-
-See the [configuration reference](docs/configuration.md) for every field. Only
-a clean readiness result should be followed by:
+This vendors the editable `ab-*` skills, writes a stack-neutral config, and
+hands repository-aware setup to a coding agent. The
+[configuration reference](docs/configuration.md) covers every field. Then
+start the dispatcher and its live dashboard:
 
 ```sh
 ab dispatch
 ```
 
-Starts the dispatcher, with the live dashboard on a TTY.
-
-In your selected coding agent, invoke the ticket-grooming skill:
+Then groom your first ticket in your coding agent:
 
 ```text
-/ab-spec I want to build a feature!
+/ab-spec add a retry budget
 ```
 
-The agent asks the questions needed to produce a quality ticket and adds it
-directly to your ticketing system. Using the skill to create tickets then
-largely becomes your input workflow.
+The agent asks the questions needed to produce a buildable ticket and files it
+in your tracker. From then on, that skill is how work goes in.
 
 ## How it works
 
-Every build moves through the same fixed pipeline:
+### Every ticket runs the pipeline
 
 ```text
 spec → plan ⇄ plan-review → implement ⇄ code-review → verify:* → finalize
       epilogue: (pr.conflicted → reconcile → verify:*)* → merged or closed
 ```
 
+Each ticket moves through deterministic phases inside its own build-runner.
+Every phase is a fresh agent session, with artifacts knitting them together.
+
 1. **spec** — the dispatcher claims a ready ticket, establishes the final
    spec, and cuts a branch. The spec is the contract for everything after.
 2. **plan ⇄ plan-review** — a planner writes an implementation plan; an
@@ -125,54 +74,88 @@ spec → plan ⇄ plan-review → implement ⇄ code-review → verify:* → fin
    you instead of looping forever.
 4. **verify:\*** — your verification steps, in the order you declare them:
    shell commands judged by exit code, or agent verifiers that return a
-   verdict.
-5. **finalize** — the PR opens with an agent-written description and a summary
-   of explicitly attached evidence, then any post-PR steps you've configured
-   (changelogs, release notes) run failure-tolerant. A content-producing step
-   commits selected files locally; the runner extends the open PR branch with
-   a regular push. A no-op adds no commit, and a publication failure becomes a
-   follow-up observation rather than failing the green build. Agent verifiers
-   attach an exact screenshot, trace, or other artifact with
-   `ab artifact put <kind> <file> --attach`; the PR always gets a pinned
-   retrieval command, and configured public image hosting can also render
-   images inline.
+   verdict and can attach evidence such as screenshots.
+5. **finalize** — the PR opens with an agent-written description and the
+   attached evidence, then any post-PR steps you've configured (changelogs,
+   release notes) run.
 6. **epilogue** — the dispatcher watches the open PR. Conflicts route back
    through reconcile and re-verify; the build ends `merged` or `closed`.
 
-Each phase is an agent session, but the pipeline itself is not agentic:
-agents never decide what phase comes next, and outcomes are never inferred
-from what a model printed. Every phase reports through a typed CLI into an
-append-only event log, and tested code decides the transition. That log is
-the build — kill the process at any point and the dispatcher resumes from
-durable state, and every decision along the way stays queryable after the
-fact.
+### A dispatcher spawns builds
+
+The dispatcher claims ready tickets and starts a build-runner for each.
+Runners are isolated, and all state is logged. Agents never decide what phase
+comes next, and outcomes are never inferred from what a model printed: every
+phase reports through a typed CLI into the event log, and tested code decides
+the transition. That log is the build. Kill the process at any point and the
+dispatcher resumes from durable state.
 
 The pipeline grammar is fixed on purpose; `verify:*` and `finalize:*` are the
-extension points, declared per-repo in `autobuild.toml`. Post-step agents may
-commit locally but never push or call the forge; publication stays
-kernel-owned. For the seams and the reasoning behind them, see
-[`docs/architecture.md`](docs/architecture.md) and [`SPEC.md`](SPEC.md).
-
-### Observation harvesting
-
-Builds notice things they shouldn't fix. An implementer that spots a latent
-bug, a worthwhile refactor, or a missing follow-up outside its spec records a
-structured observation (`ab observe`) and moves on — the insight is kept, and
-scope creep stays out of the PR.
-
-Observations accumulate per repository, and once enough pile up the
-dispatcher runs a separate outer workflow — scan → synthesize ⇄ review →
-file — that distills them into proposed tickets, deduplicated against work
-already filed. By default, proposals land in triage with the reserved
-`autobuild:proposal` label and never dispatch themselves: the label means
-observation harvest created the ticket for human triage, not that Autobuild has
-groomed or claimed it. Autobuild does not use this label as a readiness gate or
-remove it; it is distinct from any configured or historical `autobuild` ready
-label. You groom and ready proposals like any ticket you wrote yourself. Agents
-propose; humans dispatch.
+extension points, declared per repository in `autobuild.toml`. For the seams
+and the reasoning behind them, see [`docs/architecture.md`](docs/architecture.md)
+and [`SPEC.md`](SPEC.md).
+
+## All local, all remote, or anywhere between
+
+Every seam is an adapter you can customize for your project. The build
+pipeline stays the same.
+
+| Seam       | Decides               | Adapters                                   |
+| ---------- | --------------------- | ------------------------------------------ |
+| tickets    | where work comes from | local files, Linear, hosted, plugin        |
+| dispatcher | what starts builds    | local process, scheduled (hosted)          |
+| workspace  | where a build runs    | git worktree, Vercel Sandbox, plugin       |
+| runtime    | who does the thinking | Claude Code, Codex, Pi, plugin             |
+| forge      | where code lands      | local git, GitHub, plugin                  |
+| store      | where state lives     | SQLite, Postgres, any HTTP store           |
+| operators  | how you watch         | terminal, web UI, MCP                      |
+
+Plugins are trusted Bun modules declared in `autobuild.toml` against the
+versioned `@defrex/autobuild/plugin-sdk`. Teams that want one durable store
+across hosts can deploy the optional
+[hosted service](packages/hosted-store-service/README.md), which adds a
+browser dashboard, a [scheduled dispatcher](docs/hosted-dispatcher.md), an
+[operator API](docs/operator-api.md), and an [MCP server](docs/mcp.md).
+
+
+## Built for throughput, not latency
+
+One build may take longer than a chat with an agent. The trade is far more
+changes landing every day, with much greater reliability.
+
+- **File it and walk away.** Nothing in the pipeline waits on you. You don't
+  approve tool calls, paste errors back, or watch a terminal. A build
+  escalates to you only when it is truly blocked.
+- **As many builds as you can groom.** Builds run side by side, each in its
+  own workspace, up to the limit you set. Your attention stops being the
+  ceiling; how fast you can write good tickets becomes the limit.
+
+Headless is safe because the pipeline is deterministic code, not model
+judgment. State lives in a typed, append-only event log, phase transitions
+are owned by tested code, and every build leaves a queryable paper trail. Your
+merge gates are never bypassed: a PR lands when your required checks and your
+consent say it lands.
+
+## Let the queue fill itself
+
+Once tickets are the interface, anything that can write a ticket can put work
+in front of you.
+
+Builds feed the queue themselves. An implementer that spots a latent bug, a
+worthwhile refactor, or a missing follow-up outside its spec records an
+observation (`ab observe`) and moves on: the insight is kept, and scope creep
+stays out of the PR. Once enough pile up, the dispatcher distills them into
+proposed tickets, deduplicated against work already filed, and by default
+files them into triage. You groom them like any ticket you wrote yourself.
+Agents propose; humans dispatch.
+
+Support threads, meeting notes, and error telemetry can feed it the same way.
+An agent with the `ab` CLI or the MCP server can file tickets and answer
+routine escalations, leaving you only the real product calls.
 
 ## Learn more
 
+- [autobuild.run](https://www.autobuild.run) — the project site.
 - [`docs/spec-standard.md`](docs/spec-standard.md) — what makes a ticket
   buildable: the standard every dispatched spec must meet.
 - [`docs/configuration.md`](docs/configuration.md) — the complete strict
@@ -181,7 +164,8 @@ propose; humans dispatch.
   configuration, as a worked example of the config surface.
 - [`docs/architecture.md`](docs/architecture.md) — how the design maps to the
   codebase: kernel, ports, processes, and stores.
-- [`packages/postgres-store/README.md`](packages/postgres-store/README.md) — serverless PostgreSQL persistence with S3-compatible or Vercel Blob storage.
+- [`packages/postgres-store/README.md`](packages/postgres-store/README.md) —
+  serverless PostgreSQL persistence with S3-compatible or Vercel Blob storage.
 - [`docs/remote-store-protocol.md`](docs/remote-store-protocol.md) — the
   complete HTTP server contract and BuildStore conformance instructions.
 - [`SPEC.md`](SPEC.md) — the source of truth for the design and its

package/SPEC.md

@@ -241,6 +241,16 @@ same BuildStore. Consequences, by design:
 
 - **State is a reduction of events.** Any state snapshot is a cache, never
   the source of truth. Resumability falls out.
+- **Reducer snapshots are a cache the log regenerates, never an authority.**
+  The store may keep, per scope (one build log or the repository journal) and
+  reducer, that reducer's serialized state as of a cursor, keyed by scope,
+  reducer, reducer version, and cursor, so a process with no hot memory loads
+  it, reads only the newer events, and advances. A missing snapshot, one
+  written by a different reducer version, or one ahead of the log is ignored
+  and the state is rebuilt by full replay with identical results; stored
+  cursors never decrease; deleting every snapshot changes no observable
+  output. A store without snapshot storage behaves as if every snapshot were
+  missing.
 - **The UI layer is a subscriber** plus a command channel back. TUI, web —
   same adapter pattern. The shipped interactive terminal owns a supervised
   kernel child, and the BuildStore is their only changing-state boundary.
@@ -491,8 +501,11 @@ stream read's ([docs/remote-store-protocol.md](docs/remote-store-protocol.md),
 
 #### 7.1.2 The embedded orchestrator (turns)
 
-The orchestrator is the agent that files tickets, watches builds, unblocks
-them, and discusses direction — played in the hosted service by a stateless
+The orchestrator is a role, not a deployment: the agent that files tickets,
+watches builds, unblocks them, and discusses direction. Any agent can take it
+on — a coding-agent session at the repository root using the `ab` CLI or
+`ab mcp` needs no initialization — and the canonical `ab-operate` skill is its
+manual in either setting. In the hosted service it is played by a stateless
 turn runner over the operator tool registry, not by an agent living in a
 sandbox (parity with MCP; no credential plumbing) and not by an external
 workflow engine (durability comes from the store; the tick pattern already
@@ -2413,8 +2426,8 @@ installs into a repo:
   non-agent-invocable: they are invoked explicitly by the runner or a human,
   never auto-triggered by a model pattern-matching a description — a model
   must not start a pipeline phase by accident. The model-invocable exceptions
-  (`ab-spec`, `ab-tickets`, `ab-guide`) are exactly the three skills that
-  **drive no phase**; membership is decided by that criterion, not taste.
+  (`ab-spec`, `ab-tickets`, `ab-guide`, `ab-operate`) are exactly the four
+  skills that **drive no phase**; membership is decided by that criterion, not taste.
 
 When `.agents/skills` and `.claude/skills` resolve to the same filesystem
 entry, that repository-level alias already satisfies harness discovery. Init

package/docs/architecture.md

@@ -131,6 +131,115 @@ 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

package/docs/configuration.md

@@ -202,7 +202,7 @@ These fields hot-reload:
 | `[workspace]` provider and config (including `provisioning`) | Next launch of a build whose OWN branch carries it. A base-branch reload never re-provisions an in-flight build. |
 | `[roles]` | Next agent invocation for that role. Runtime, model, args, alternates, and the session budget are captured together and delivered live. |
 | `[policy]` | Next policy, convergence, or agent-session boundary, delivered live. A running session keeps its captured budget. |
-| `tickets.readyLabels`, `tickets.readyState` | Next ready-ticket scan. |
+| `tickets.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
@@ -1167,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`. |
@@ -1174,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:
 
@@ -1551,10 +1572,8 @@ 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 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
+Autobuild now installs 12 skills; only `ab-spec`, `ab-tickets`, `ab-guide`,
+and `ab-operate` are model-invocable. 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.
 

package/docs/remote-store-protocol.md

@@ -297,6 +297,8 @@ it to exist. An unknown build returns `404 not-found`.
 | `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
@@ -382,6 +410,8 @@ without a journal record, or a repository without builds.
 | `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` |
@@ -834,6 +864,11 @@ resource access; an explicit resource whose id is `"*"` is not admin.
 | 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
 session resource token's authority is exactly its one session — it cannot

package/docs/website.md

@@ -5,6 +5,10 @@ The marketing site is one static page in `packages/website`, reproduced from the
 - `bun run website:dev` serves it on port 3300 (`PORT` overrides), rebuilding on every request.
 - `bun run website:build` writes `packages/website/dist/` (`index.html`, `site.css`, `site.js`).
 
+The hero is the real `ab dispatch` dashboard: `packages/website/src/hero-frame.txt` holds the exact colored lines the terminal dashboard painted for the scripted `website-hero` capture, and the page renders them as preformatted HTML with each terminal color mapped to its design token. `bun run capture:website-hero` regenerates the file from the capture, and `bun run check` fails when it is stale.
+
+Shared links preview through Open Graph and Twitter card tags in the page head, pointing at `og.png`, a 1200×630 card drawn from the same frame in the site's own styles. `bun run capture:website-og` screenshots it with a local Chromium into `packages/website/src/og.png`; rerun it after changing the headline, the hero frame, or the styles, and look at the result, since font rasterization differs between machines and nothing checks the bytes. The canonical origin every absolute URL is built from is `SITE_URL` in `packages/website/src/constants.ts`.
+
 `dist/` is plain static files: any static host can serve it with no server runtime, credentials, or environment variables. On Vercel, set the root directory to `packages/website`, the build command to `bun run build`, and the output directory to `dist`.
 
 The page loads one webfont from Google Fonts and makes no other third-party requests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defrex/autobuild",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Agent-driven software delivery from groomed ticket to merged PR",
   "repository": {
     "type": "git",
@@ -117,9 +117,11 @@
     "website:dev": "bun packages/website/src/dev.ts",
     "website:build": "bun packages/website/src/build.ts",
     "capture:readme-headline": "bun tools/readme-headline.ts",
+    "capture:website-hero": "bun tools/website-hero.ts",
+    "capture:website-og": "bun tools/website-og.ts",
     "release": "bun tools/release.ts",
     "postgres:migrate": "bun packages/postgres-store/src/bin.ts migrate",
-    "check": "bun tools/biome-check.ts && bun tools/product-name-check.ts && bun tools/docs-asset-check.ts && bun tools/skill-docs-asset-check.ts && bun tools/readme-headline.ts --check && bun tools/workspace-manifest-check.ts && bun tools/package-boundary-check.ts && bun tools/bin-mode-check.ts && bun tools/publish-contents-check.ts && bun tools/publish-imports-check.ts",
+    "check": "bun tools/biome-check.ts && bun tools/product-name-check.ts && bun tools/docs-asset-check.ts && bun tools/skill-docs-asset-check.ts && bun tools/readme-headline.ts --check && bun tools/website-hero.ts --check && bun tools/workspace-manifest-check.ts && bun tools/package-boundary-check.ts && bun tools/bin-mode-check.ts && bun tools/publish-contents-check.ts && bun tools/publish-imports-check.ts",
     "format:staged": "git-format-staged --formatter './node_modules/.bin/biome format --stdin-file-path {}' '*.js' '*.jsx' '*.ts' '*.tsx' '*.json' '*.jsonc' '*.css' '*.graphql' '*.gql'",
     "prepare": "husky",
     "test": "bun test packages/*/src tools bin packages/hosted-store-service/app",
@@ -137,8 +139,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
-    "@defrex/autobuild-postgres-store": "0.8.0",
-    "@defrex/autobuild-vercel-sandbox": "0.8.0",
+    "@defrex/autobuild-postgres-store": "0.9.0",
+    "@defrex/autobuild-vercel-sandbox": "0.9.0",
     "@resvg/resvg-js": "2.6.2",
     "@types/bun": "^1.3.14",
     "@types/node": "^24.0.0",