@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/store/types.ts

@@ -24,7 +24,17 @@ import type {
   SessionEventType,
   SessionEventWrite,
 } from '../events/sessions'
+export type { SessionEventEnvelope }
 import type { TicketRef } from '../ontology'
+import type { ReducerSnapshot, SnapshotScope } from './snapshots'
+export type { ReducerSnapshot, SnapshotScope }
+import type {
+  TicketAsset,
+  TicketAssetInput,
+  TicketAssetLimits,
+  TicketAssetMeta,
+  TicketAssetSummary,
+} from './ticket-assets'
 import type {
   StreamChunk,
   StreamOutcome,
@@ -64,6 +74,12 @@ export interface NewBuildInput {
   repoOrigin?: string
   ticket?: TicketRef
   branch?: string
+  /** The build's `build.created` fact, appended as seq 1 in the same atomic
+   * step as the record: both exist or neither does, so the claim-time facts it
+   * freezes (ticket assets, SPEC §6.3) can never be lost to a crash between
+   * the two writes. An invalid payload, or any other event type, rejects and
+   * creates nothing. */
+  created?: EventWrite<'build.created'>
 }
 
 export interface ArtifactMeta {
@@ -77,6 +93,38 @@ export interface ArtifactMeta {
   createdAt: string
 }
 
+/** The projection of one build's event log onto exactly the two facts an
+ * operator dashboard needs from every build (AUT-487): the latest terminal
+ * fact's kind — `done` for `build.completed`, `aborted` for `build.aborted`,
+ * in-order overwrite, exactly `reduceBuild`'s terminal rule — and the seqs of
+ * the log's `observation.recorded` occurrences. `terminal` is absent while
+ * the log carries neither terminal fact (a queued, running, paused, blocked,
+ * or mid-cleanup build). Everything else a dashboard shows comes from the
+ * journal, the build records, and the full histories of just the builds that
+ * render rows. Nothing is persisted: every adapter derives the digest from
+ * the event log on each call, so the log stays the sole authority and the
+ * digest can always be discarded and rebuilt. */
+export interface BuildDigest {
+  slug: string
+  terminal?: 'done' | 'aborted'
+  /** Ascending-seq `{seq, ts}` pairs for every `observation.recorded` in the
+   * build's log; `ts` is the event envelope timestamp (AUT-521: the harvest
+   * pressure gate measures drift from the oldest unclaimed occurrence's ts,
+   * so per-occurrence timestamps travel with the digest). */
+  observations: { seq: number; ts: string }[]
+  /** Envelope ts of the log's latest `pr.merged` event, absent when the log
+   * has none (AUT-521: latest-wins suffices for drift, which counts a build
+   * when any of its merges is strictly after the oldest unclaimed
+   * observation). */
+  merged?: string
+  /** A `pr-attachment.hosted` has no later matching `pr-attachment.reclaimed`
+   * (the `pendingPrAttachmentReclaims` rule). Absent otherwise. */
+  reclaimPending?: true
+  /** The latest `execution.started` has no later `execution.ended` with the
+   * same `instance` (the `openExecution` rule). Absent otherwise. */
+  executionOpen?: true
+}
+
 export interface RepositoryRecord {
   repo: string
   createdAt: string
@@ -103,7 +151,8 @@ export interface RepositoryArtifact {
 /** An operator session: hosted-only durable orchestrator-conversation state
  * (SPEC §7.1.1). The record carries only identity and timestamps; everything
  * else — status, open turn, pending approval, wake settings — is a reduction
- * of the session's own event log (sessions/reducer.ts), never a column. */
+ * of the session's own event log (the hosted package's session-reducer.ts),
+ * never a column. */
 export interface SessionRecord {
   /** Store-assigned (`os_<uuid>`). */
   id: string
@@ -257,6 +306,18 @@ export interface BuildStore {
     opts?: { waitSeconds?: number; signal?: AbortSignal },
   ): Promise<AbEvent[]>
 
+  /** One entry for EVERY build whose record's repo is `repo` (completeness is
+   * contractual: a freshly created build whose log holds none of the
+   * digest-relevant event types still gets its entry, with empty
+   * `observations` and no `terminal`), keyed by slug. A read-only, repo-scoped
+   * batch query shaped like `listBuilds`: it performs no `ensureRepo`, never
+   * writes, and an unknown or build-less repo answers an empty map rather
+   * than rejecting. Derived from the event log on every call — the log is the
+   * sole authority, so there is nothing to refresh or invalidate. The
+   * derivation is the shared `reduceBuildDigest` (store/digest.ts), so every
+   * adapter answers identical results for identical logs. */
+  getRepoBuildDigests(repo: string): Promise<Map<string, BuildDigest>>
+
   putArtifact(slug: string, artifact: ArtifactInput): Promise<ArtifactMeta>
   /** Latest revision when `rev` is omitted; null if kind (or rev) absent. */
   getArtifact(slug: string, kind: string, rev?: number): Promise<Artifact | null>
@@ -305,9 +366,92 @@ export interface BuildStore {
     sinceSeq?: number,
     opts?: { waitSeconds?: number; signal?: AbortSignal },
   ): Promise<RepositoryEvent[]>
+  /** Bounded repository-journal read for stateless full-state readers
+   * (AUT-489): every durable fact (REPOSITORY_STATE_EVENT_TYPES) plus — when
+   * the journal has one — the tail from the latest `dispatcher.run-started`.
+   * Reducing this subset with the state readers yields exactly what a full
+   * replay yields (`projectRepositoryStateEvents` is the normative oracle).
+   * Unknown repo rejects like `getRepoEvents`. */
+  getRepoStateEvents(repo: string): Promise<RepositoryEvent[]>
+  /** The journal's true high-water mark: the greatest assigned seq of any
+   * event type, 0 for an empty journal. Returns no event rows — the cursor a
+   * long-lived reader (the dispatcher's repository view) needs to resume with
+   * `getRepoEvents(repo, cursor)` even when the bounded subset excludes the
+   * journal's trailing events. Unknown repo rejects like `getRepoEvents`;
+   * never an `ensureRepo` side effect. */
+  getRepoHighWater(repo: string): Promise<number>
+  /** The stored reducer snapshot for a scope (a build log or a repository
+   * journal), a cache beside the log and never an authority. `null` when
+   * absent, when the stored version differs from `version`, when the stored
+   * cursor is ahead of the scope's log tail, or when the scope is unknown (no
+   * `ensureRepo` side effect, no rejection). A store without snapshot storage
+   * answers `null`. */
+  getReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    version: number,
+  ): Promise<ReducerSnapshot | null>
+  /** Upsert a reducer snapshot; the stored cursor never decreases. Writes only
+   * when no row exists, when `cursor` is above the stored one (whatever the
+   * versions — a mismatched row is replaced as soon as any writer advances
+   * past it), or when the cursor is equal and `version` is higher. Everything
+   * else, and any cursor beyond the log tail, is a no-op. Atomic, so
+   * concurrent writers cannot undo each other's progress. Resolves `true`
+   * when the row was written. */
+  putReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    snapshot: ReducerSnapshot,
+  ): Promise<boolean>
   putRepoArtifact(repo: string, artifact: ArtifactInput): Promise<RepositoryArtifactMeta>
   getRepoArtifact(repo: string, kind: string, rev?: number): Promise<RepositoryArtifact | null>
   listRepoArtifacts(repo: string, kind?: string): Promise<RepositoryArtifactMeta[]>
+  // ── Ticket assets (SPEC §7.1 — files attached to a ticket) ─────────────
+  // Keyed by (repo, ticketId, kind, name); revisions are 0-based. The store
+  // owns the bytes, the ticket source only ever gets a note (SPEC §13).
+  /** The effective ceilings this store accepts for `repo` (a remote
+   * deployment may advertise lower ones than the defaults). */
+  ticketAssetLimits(repo: string): Promise<TicketAssetLimits>
+  /** Validate, then store a new revision. Over-limit or invalid input rejects
+   * with `TicketAssetValidationError` and stores nothing. */
+  putTicketAsset(repo: string, ticketId: string, asset: TicketAssetInput): Promise<TicketAssetMeta>
+  /** Latest live revision when `rev` is omitted; null when the asset is
+   * absent, removed (latest row is a tombstone), or `rev` is not a real
+   * revision. An explicit `rev` of an earlier revision keeps working after a
+   * removal, so a build that pinned it still retrieves it. */
+  getTicketAsset(
+    repo: string,
+    ticketId: string,
+    kind: string,
+    name: string,
+    rev?: number,
+  ): Promise<TicketAsset | null>
+  /** The ticket asset `kind/name` exactly as build `slug` froze it (SPEC
+   * §6.3): the latest pinned revision, or with `rev` any revision the build
+   * ever pinned. Reads the build's own events, never the ticket's current
+   * state, so it is stable after a replace or removal and works for finished
+   * builds. Null when the build never pinned it. Rejects an unknown build. */
+  getPinnedTicketAsset(
+    slug: string,
+    kind: string,
+    name: string,
+    rev?: number,
+  ): Promise<TicketAsset | null>
+  /** Default: the latest live revision per (kind, name). `revisions: true`:
+   * every real revision (no tombstones). Summaries carry no manifest. */
+  listTicketAssets(
+    repo: string,
+    ticketId: string,
+    opts?: { revisions?: boolean },
+  ): Promise<TicketAssetSummary[]>
+  /** Tombstone the asset (the next revision number, empty manifest). Returns
+   * the removed revision's meta, or null when no live asset exists. */
+  removeTicketAsset(
+    repo: string,
+    ticketId: string,
+    kind: string,
+    name: string,
+  ): Promise<TicketAssetMeta | null>
   claimRepoLease(repo: string, holder: string, ttlMs: number): Promise<boolean>
   heartbeatRepo(repo: string, holder: string): Promise<boolean>
   releaseRepoLease(repo: string, holder: string): Promise<void>
@@ -339,6 +483,21 @@ export interface BuildStore {
     id: string,
     event: SessionEventWrite<T>,
   ): Promise<SessionEventEnvelope<T>>
+  /** Atomically append one validated session event only when the session's
+   * current sequence equals `expectedSeq` (0 would only match a session with
+   * no facts — impossible, since `session.created` is always seq 1). Returns
+   * null when the session has advanced; a comparison miss must not mutate the
+   * log or the record's `updatedAt`. The three turn-start sites (message
+   * route, answer route, dispatcher tick) race on the same idle session, and
+   * two concurrent `turn.started` facts would break the single-open-turn
+   * invariant — this is the sessions mirror of the build log's
+   * `appendIfCurrent`. Invalid events and unknown sessions reject just as
+   * they do for `appendSessionEvent`. */
+  appendSessionEventIfCurrent<T extends SessionEventType>(
+    id: string,
+    expectedSeq: number,
+    event: SessionEventWrite<T>,
+  ): Promise<SessionEventEnvelope<T> | null>
   /** Events with seq strictly greater than `sinceSeq` (default 0), in order.
    * When nothing newer exists, an adapter honors `waitSeconds` with the
    * same clamp/early-return rules as stream reads (§7.6): whole seconds,

package/packages/core/src/testing/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Public testing entry point: the deterministic doubles, CLI entry points,
+ * and the end-to-end harness that out-of-tree packages' tests build against
+ * (the hosted store-service suite is the in-repo consumer). Production code
+ * never imports from here — it is test-facing surface, like plugin-sdk's
+ * fakes, just CLI-shaped.
+ */
+// The plugin-sdk's contract suites, fakes, and memory stores are the shared
+// testing vocabulary; re-export so `@defrex/autobuild/testing` is one import.
+export * from '../plugin-sdk'
+export { manualClock, steppingClock } from './fixed'
+export { agentActor, DISPATCHER, KERNEL, humanActor, type Via } from '../events/envelope'
+export { EventValidationError } from '../events/catalog'
+export type { EscalationSource } from '../ontology'
+export { abDispatch, type DispatchOpts } from '../cli/dispatch'
+// CLI entry points for the hosted-dispatcher integration test: programmatic
+// `ab` invocation and its environment resolution.
+export { resolveCliEnv } from '../cli/env'
+export { runCli } from '../cli/main'
+// Deterministic id doubles for the hosted-dispatcher integration test.
+export { randomUuids, sequentialIds, type IdSource } from '../ids'
+export { abWatch } from '../cli/watch'
+export { abTicket, type TicketSourceFactory } from '../cli/ticket'
+export { createTerminalModeController } from '../cli/terminal-restore'
+export { abBuildControl, type BuildControlAction } from '../cli/build-control'
+export { abBulkControl } from '../cli/bulk-control'
+export { createTicketSource } from '../ports/tickets/create'
+export { createOperatorSandboxService } from '../operator/sandbox'
+export { parseConfig } from '../config/load'
+export { spawnExec, type Exec } from '../ports/workspace/git-worktree'
+// Durable guest-launch state readers + the in-process guest runner for the
+// hosted-dispatcher integration test's GuestExecution double, which supervises
+// a real BuildRunner exactly as a real sandbox execution would.
+export {
+  BUILD_EFFECTIVE_CONFIG_ARTIFACT,
+  diagnosticArtifact,
+  parseEffectiveBuildConfig,
+  selectOpenWorkspace,
+} from '../processes/build-execution-state'
+export {
+  BuildRunner,
+  LeaseHeldError,
+  SetupFailureError,
+} from '../processes/build-runner'
+export { readEventsWithWait } from '../store/streams/wait'
+export { textContent } from '../store/types'
+export {
+  CONFIG_TOML,
+  GIT_ID,
+  git,
+  happyHandlers,
+  makeHarness,
+  readyTicket,
+  typesOf,
+  writeFileIn,
+  type Cli,
+  type E2eHarness,
+  type SkillHandlers,
+} from '../integration/harness'

package/skills/code-review/SKILL.md

@@ -27,7 +27,11 @@ goes nowhere.
      fake or mock are not contract evidence because they can repeat the
      author's assumption.
    - **Spec conformance** — every acceptance criterion met; nothing beyond
-     the spec's scope smuggled in.
+     the spec's scope smuggled in. 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: judge the rendered output against it wherever the code lets you
+     check, and treat a divergence as a finding. A gap in the asset is not a
+     reason to invent requirements.
    - **Tests** — do the new tests exercise the seams this change created or
      moved? Would they fail if the change were wrong?
    - **Fit** — matches the codebase's idioms; no needless indirection.

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.
@@ -719,7 +732,8 @@ state eligible.
 |---|---|---|---|
 | `source` | — | **required**, nonblank builtin or plugin registration name | Which provider backs all ticket operations. Unknown names report every available builtin and plugin source. |
 | `readyLabels` | — (source-aware) | optional; array of nonempty strings | A ticket must carry **every** listed label to be dispatchable. `[]` = **no label gate**. Absent uses the source default below. |
-| `readyState` | — | **required**, non-blank string | The one workflow state a ticket must sit in to be dispatchable. Linear matches exactly and case-sensitively; file canonicalizes it to a state directory (`ready` → `ready/`). There is no any-state mode. |
+| `readyState` | — | **required**, non-blank string | The one workflow state a ticket must sit in to be dispatchable. Linear matches exactly and case-sensitively; file matches it case-insensitively to a state directory (`ready` → `ready/`). There is no any-state mode. |
+| `readyAssignee` | — | optional; `"me"` or an email; `linear` only | Also require the ticket to be assigned to that Linear user (`me` = owner of `LINEAR_API_KEY`); unassigned tickets are never ready. |
 | `teamKey` | — | required by `linear`, forbidden by `file`, allowed for plugins | The Linear team key (e.g. `"ENG"`) or an existing plugin configuration field. |
 | `claimedState` | — | optional nonempty string; forbidden by `file`, allowed for plugins | Workflow state `claim()` moves a ticket to when a build starts. |
 | `createState` | — | optional, nonempty string | Default state for new tickets when a create does not name one. Absent = the provider's default (Linear: the team's default, e.g. Backlog; file: Triage). |
@@ -759,11 +773,16 @@ Cross-field rules, each an **error**:
   janitor completion. Every source-agnostic `ab ticket` command loads and uses
   the same configured registration.
 
-The file tracker is **directory-per-state**: `<dir>/<state>/<id>.md` over
-`triage/ ready/ doing/ done/`. The directory *is* the state, so a transition or
+The file tracker is **directory-per-state**: `<dir>/<state>/<id>.md`, where
+every directory directly under the root is a state: the four lifecycle
+directories `triage/ ready/ doing/ done/` (always present, created on first use)
+plus any others the repository adds, such as `icebox/`. A state exists when its
+directory exists; state names match directories case-insensitively, and a name
+with no directory is an error listing those that exist. The directory *is* the
+state, so a transition or
 claim is a rename — frontmatter carries no `state`/`claimedBy`, and a ticket
 body survives byte-exactly because a move never rewrites the file. A malformed
-record in any lifecycle directory is diagnosed with its path and validation
+record in any state directory is diagnosed with its path and validation
 problem, left untouched, and excluded from listing/claim so unrelated valid
 ready work can continue. `ab ticket list` sends those diagnostics to stderr and
 keeps JSON stdout as one bare valid-ticket array. Tracker-wide safety checks
@@ -771,8 +790,8 @@ remain fatal: the same id in two state dirs is a loud error naming both paths,
 as are root-level ticket files with no state and filesystem failures. When
 `dir` is defaulted, the backlog writes its own `.gitignore` of `*`, so git never sees it; an
 explicit `dir` is the user's and is left alone. Agents and operators drive it
-through the source-agnostic `ab ticket` commands rather than running `mv` by
-hand.
+through the source-agnostic `ab ticket` commands rather than running `mv` or
+`mkdir` by hand; `ab ticket state create` makes a new state.
 
 **Secrets never live in this file.** `LINEAR_API_KEY` and plugin-declared
 `requiredEnv` credentials are environment variables (a local `.env` works).
@@ -782,15 +801,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 +839,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 +866,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
@@ -1030,6 +1069,19 @@ with Linear and the file tracker, without provider-specific API/MCP calls:
   labeled metadata and the body verbatim, so it can read a stored spec back.
 - `ab ticket move <id> <state> [--json]` transitions one ticket and reports its
   post-transition value.
+- `ab ticket states [--json]` lists every state of the configured source:
+  lifecycle states first (triage, ready, doing, done), then custom states
+  alphabetically. Each row has the state name, the roles it plays under the
+  current config (create, ready, claimed, triage, proposal, done, or none), its
+  ticket count, and its purpose when set. `--json` emits one bare array of
+  `{name, roles, tickets, about?}`.
+- `ab ticket state create <name> [--about <text>] [--json]` makes a state, for
+  example `icebox`. It is idempotent: an existing state is reported as already
+  existing, and `--about` (one line) records or replaces its purpose. A name is
+  one to forty lowercase letters, digits, and hyphens starting with a letter,
+  and may not match an existing state case-insensitively. There is no rename or
+  delete. Only the file source supports `states` and `state create`; other
+  sources exit nonzero naming the source and the unsupported operation.
 
 State names and ids are source-local. For block and unblock, the first id is the
 ticket being changed and the comma-separated second operand names its blockers.
@@ -1070,6 +1122,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 +1164,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 +1308,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 +1346,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 +1609,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 +1655,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 +1740,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.
 
@@ -1760,7 +1868,7 @@ default, when you need to know what this repo's version says).
 | Skill | Place in the lifecycle | Purpose |
 |---|---|---|
 | `ab-spec` | Before a build exists | Design a feature spec-first through conversation, or flesh out a ticket to the spec standard. The human-interactive surface; takes a ticket, not a build slug. **Model-invocable.** |
-| `ab-tickets` | Before a build exists | Drive this repo's local file tracker: create a ticket, report the backlog, groom or move one between `triage/ ready/ doing/ done/`. The agent-facing surface on the tracker — use it instead of `mv`. **Model-invocable.** |
+| `ab-tickets` | Before a build exists | Drive this repo's local file tracker: create a ticket, report the backlog, groom or move one between the lifecycle directories (`triage/ ready/ doing/ done/`) and any repository-defined states, including the icebox. The agent-facing surface on the tracker — use it instead of `mv`. **Model-invocable.** |
 | `ab-guide` | Outside the pipeline | This skill: reference for the lifecycle, config surface, setup/upgrade behavior, and the installed skills. Its editable `references/setup.md` guides the init handoff. **Model-invocable.** |
 | `ab-harvest` | harvest `synthesize` step | Continue the producer across review rounds: cluster the claimed structured observations and author typed spec-standard create/join/suppress proposals. Runner-only. |
 | `ab-harvest-review` | harvest `review` step | Fresh adversarial reviewer for proposal coverage, semantic dedup, spec quality, and evidence; returns `approve`/`revise`/`escalate`. Runner-only. |
@@ -1770,12 +1878,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: