@defrex/autobuild 0.9.0 → 0.10.1

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

@@ -0,0 +1,88 @@
+/**
+ * Reducer snapshots: a cache beside the event log, never an authority.
+ *
+ * For one scope (a build log or a repository journal) and one registered
+ * reducer, the store may keep that reducer's serialized accumulator as of a
+ * cursor, so a process with no hot memory loads it, reads only the events
+ * newer than the cursor, and advances — instead of replaying the whole log.
+ *
+ * The log always regenerates a snapshot. Every consumer treats a missing,
+ * version-mismatched, ahead-of-log, malformed or unreadable snapshot as a miss
+ * and replays; deleting every snapshot changes no observable output.
+ */
+import { z } from 'zod'
+import type { IncrementalReducer } from '../kernel/incremental'
+import type { BuildStore } from './types'
+
+export type SnapshotScope = { kind: 'build'; slug: string } | { kind: 'repo'; repo: string }
+
+export interface ReducerSnapshot {
+  /** The reducer version that wrote `state`; a reader on another version
+   * ignores the snapshot. */
+  version: number
+  /** The greatest event seq folded into `state`. */
+  cursor: number
+  /** The reducer's JSON accumulator as of `cursor`. */
+  state: unknown
+}
+
+export const reducerSnapshotWireSchema = z.object({
+  version: z.number().int().min(1),
+  cursor: z.number().int().min(0),
+  state: z.unknown(),
+})
+
+/** The registry name a snapshot is keyed by: a short identifier, safe in a URL
+ * path segment and a SQL key. */
+export const SNAPSHOT_REDUCER_NAME = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/
+
+export function snapshotScopeKey(scope: SnapshotScope): string {
+  return scope.kind === 'build' ? `build:${scope.slug}` : `repo:${scope.repo}`
+}
+
+/** Whether a put replaces the stored row. The stored cursor never decreases:
+ * a higher cursor wins whatever the versions, and an upgraded reducer replaces
+ * an older shape at an unchanged cursor. */
+export function snapshotSupersedes(
+  next: Pick<ReducerSnapshot, 'version' | 'cursor'>,
+  stored: Pick<ReducerSnapshot, 'version' | 'cursor'> | undefined,
+): boolean {
+  if (stored === undefined) return true
+  if (next.cursor !== stored.cursor) return next.cursor > stored.cursor
+  return next.version > stored.version
+}
+
+type SnapshotStore = Pick<BuildStore, 'getReducerSnapshot' | 'putReducerSnapshot'>
+
+/** Read a snapshot, degrading every failure to a miss. */
+export async function loadReducerSnapshot(
+  store: Partial<SnapshotStore>,
+  scope: SnapshotScope,
+  name: string,
+  reducer: Pick<IncrementalReducer<unknown, unknown, unknown>, 'version'>,
+): Promise<ReducerSnapshot | null> {
+  if (store.getReducerSnapshot === undefined) return null
+  try {
+    const found = await store.getReducerSnapshot(scope, name, reducer.version)
+    if (found === null || found.version !== reducer.version) return null
+    if (!Number.isInteger(found.cursor) || found.cursor < 0) return null
+    return found
+  } catch {
+    return null
+  }
+}
+
+/** Write a snapshot best-effort; a failing store never reaches the caller. */
+export async function persistReducerSnapshot(
+  store: Partial<SnapshotStore>,
+  scope: SnapshotScope,
+  name: string,
+  snapshot: ReducerSnapshot,
+): Promise<boolean> {
+  if (store.putReducerSnapshot === undefined) return false
+  try {
+    return await store.putReducerSnapshot(scope, name, snapshot)
+  } catch {
+    return false
+  }
+}

package/packages/core/src/store/ticket-assets.ts

@@ -10,6 +10,7 @@
 
 import type { AbEvent } from '../events/catalog'
 import type { PinnedAsset } from '../events/payloads'
+import { defineReducer } from '../kernel/incremental'
 import { contentHash, type BlobStore, type BuildStore } from './types'
 
 export type { PinnedAsset }
@@ -379,19 +380,40 @@ export async function samplePinnedAssets(
   return (await store.listTicketAssets(repo, ticketId)).map(pinnedAssetOf)
 }
 
-/** Latest-pinned revision of `kind/name` as the build's events record it, or
- * (with `rev`) the revision when any pin in the log named it. */
-export function findPinnedRevision(
-  events: AbEvent[],
+export const PINNED_ASSETS_REDUCER_VERSION = 1
+
+/** The asset sets recorded by every `build.created`/`spec.revised` pin event
+ * that carries one, in array order. Each pin event replaces the set, so the
+ * newest decides the live pin; all of them answer "was this revision ever
+ * named". `pinnedRevision` is the query over the finished state. */
+export const pinnedAssetsReducer = defineReducer<
+  { pins: PinnedAsset[][] },
+  AbEvent,
+  { pins: PinnedAsset[][] }
+>({
+  version: PINNED_ASSETS_REDUCER_VERSION,
+  initial: () => ({ pins: [] }),
+  fold(acc, events) {
+    for (const event of events) {
+      if (event.type !== 'build.created' && event.type !== 'spec.revised') continue
+      const assets = event.payload.assets
+      if (assets === undefined) continue
+      acc.pins.push(assets)
+    }
+  },
+  finish: (acc) => ({ pins: acc.pins.slice() }),
+})
+
+/** Latest-pinned revision of `kind/name` over a reduced pin state, or (with
+ * `rev`) the revision when any pin named it. */
+export function pinnedRevision(
+  state: { pins: readonly (readonly PinnedAsset[])[] },
   kind: string,
   name: string,
   rev?: number,
 ): number | undefined {
   let latest: number | undefined
-  for (const event of events) {
-    if (event.type !== 'build.created' && event.type !== 'spec.revised') continue
-    const assets = event.payload.assets
-    if (assets === undefined) continue
+  for (const assets of state.pins) {
     if (rev !== undefined) {
       if (assets.some((a) => a.kind === kind && a.name === name && a.revision === rev)) return rev
       continue
@@ -403,6 +425,17 @@ export function findPinnedRevision(
   return latest
 }
 
+/** Latest-pinned revision of `kind/name` as the build's events record it, or
+ * (with `rev`) the revision when any pin in the log named it. */
+export function findPinnedRevision(
+  events: AbEvent[],
+  kind: string,
+  name: string,
+  rev?: number,
+): number | undefined {
+  return pinnedRevision(pinnedAssetsReducer.reduce(events), kind, name, rev)
+}
+
 /** `BuildStore.getPinnedTicketAsset` for any adapter: read the build's own
  * events to find the pinned revision, then fetch exactly that revision from the
  * ticket's assets. Earlier revisions stay retrievable after a replace or a

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

@@ -26,6 +26,8 @@ import type {
 } 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,
@@ -115,6 +117,12 @@ export interface BuildDigest {
    * 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 {
@@ -365,6 +373,36 @@ export interface BuildStore {
    * 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[]>

package/skills/guide/SKILL.md

@@ -732,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). |
@@ -772,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
@@ -784,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).
@@ -893,7 +899,7 @@ repo path, needs no `AB_*` environment, and is safe to re-run. It:
   base for `ab upgrade`'s three-way merges.
 - Rewrites frontmatter on install: `name` → `ab-<name>`, and
   `disable-model-invocation: true` on every skill outside the model-invocable
-  set (`ab-spec`, `ab-tickets`, `ab-guide`).
+  set (`ab-spec`, `ab-tickets`, `ab-guide`, `ab-operate`).
 
 The final report states `autobuild.toml: written|skipped`, aggregates all skill
 counts, names only attention-worthy `kept` and `overwritten` skills, and reports
@@ -1063,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.
@@ -1849,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. |
@@ -1859,16 +1878,14 @@ 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. |
-| `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.
+| `ab-operate` | outside the pipeline; model-invocable | The orchestrator role's operating manual, for any agent: file and groom tickets, watch builds with a resumable `ab watch` / `ab wait` loop, answer escalations, pause, resume, abort, control auto-merge, and keep going until every shepherded build is merged, closed, or aborted. Also read by the hosted turn runner as its system prompt (registry tools, approval and budget suspension, wake turns). |
+
+Autobuild installs 12 skills. Everything except `ab-spec`, `ab-tickets`,
+`ab-guide`, and `ab-operate` 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 four 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, `ab-guide` is
+read-only reference including the setup handoff guidance, and `ab-operate` is
+the manual for the orchestrator role, which any agent may take on.

package/skills/guide/references/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/skills/operate/SKILL.md

@@ -1,17 +1,140 @@
 ---
 name: operate
-description: You are the embedded orchestrator for one repository - the agent that answers its operator sessions, watches its builds, unblocks them, and discusses direction. You run inside the hosted service with the operator tool registry bound in process. Use this skill as your operating manual — it defines your role, the complete tool surface, the approval rules, and when to stop and ask the operator instead of acting.
+description: Orchestrate a repository's builds - file and groom tickets, watch builds, answer escalations, pause, resume, or abort builds, control auto-merge, and drive work to merge. Use when asked to watch, shepherd, or orchestrate builds, whether from a coding-agent session at the repository root using the ab CLI or inside the hosted service with the operator tool registry.
 ---
 
 # Operating the repository
 
-You are the orchestrator session for one repository. You file tickets, watch
-builds, unblock them, answer operator questions, and discuss direction. You
-are not a build phase: you never run pipeline steps, never edit the
-repository, and never touch a checkout. Your entire reach is the operator
-tool registry bound into your turn.
-
-## How you run
+The orchestrator is a role, not a deployment. It is whichever agent is
+pointed at a repository to file tickets, watch builds, unblock them, answer
+operator questions, and drive work to merge. Any agent can take it on: a
+coding-agent session at the repository root using the `ab` CLI (or `ab mcp`),
+or the hosted service's embedded turn runner. There is no initialization
+step — deciding to orchestrate is enough.
+
+The orchestrator is not a build phase: it never runs pipeline steps, never
+edits the repository, and never touches a build's checkout. Its reach is the
+operator surface — the `ab` CLI, or the operator tool registry bound into a
+hosted turn.
+
+Find your setting and read that section: **Running locally with the `ab`
+CLI** if you are a session with a shell, **Running in the hosted service** if
+your tools are the registry's `builds.*` / `tickets.*` family. The sections
+after them apply to both.
+
+## Running locally with the `ab` CLI
+
+Run the commands below from the repository root. Each acts with the operator's
+authority, so say what you are doing before you do anything destructive.
+
+### Watch for attention events
+
+`ab watch --json` streams the attention set (escalations, failures, finalize,
+PR conflicted/merged/closed, build completed/aborted) as newline-delimited
+records. Every record carries a `cursor`; a bounded watch ends with a trailing
+`{"cursor": …}` line. Resume with `--since <cursor>` and every event after it
+is delivered exactly once, including events that landed while nothing was
+watching. Name slugs to watch only those builds; with none, every active build
+(including ones created later) is watched. `--event <glob>` replaces the
+default filter, `--timeout <dur>` bounds it (default 30 minutes, `0` is
+unbounded), `--count <n>` ends it after n records.
+
+`ab wait [<slug>...] (--for <condition> | --event <glob>) [--since <cursor>] [--json]`
+blocks until a condition holds and prints one record. `--for` state conditions
+are also satisfied immediately by a build already in that state; `--event` is
+satisfied only by new events. Conditions include `attention`,
+`blocked`, `paused`, `running`, `done`, `aborted`, `terminal`, `pr=merged`,
+`pr=closed`, `pr=conflicted`, and `phase=<phase>`. Exit codes: 0 satisfied,
+1 usage or store error, 2 every named build is terminal without satisfying a
+condition, 3 timeout, 4 interrupted. On 3 and 4 with `--json`, the output is a
+bare `{"cursor": …}` to resume from.
+
+Run long watches and waits in whatever background or monitor facility your
+harness provides, so the session stays responsive and you are woken when they
+emit. Never block a foreground command for their whole duration.
+
+### Keep watching until the work is done
+
+Checking once is not shepherding. When you take responsibility for builds:
+
+1. Record the set you are shepherding (`ab builds --all --json`, or the slugs
+   you were given).
+2. Arm an event-only watch and keep its cursor:
+   `ab watch <slugs…> --json --since <cursor>` (omit `--since` the first
+   time). Events are delivered exactly once, so a build that already finished
+   is never replayed. Do not loop on `ab wait --for terminal|attention|…`:
+   state conditions are satisfied at once by any build already in that state,
+   even with `--since`, so a finished build would be returned again and the
+   loop would spin on it. If you use `ab wait`, use only `--event <glob>`
+   conditions (satisfied by new events only), never `--for`.
+3. Reconcile current state right after the first watch is armed, and again
+   whenever a watch ends without records: a watch baselines each build at its
+   current position and does not emit what already happened, so a build that
+   merged, or an escalation already open, before registration would otherwise
+   never reach you. Run `ab build status <slug> --json` for every slug in the
+   set. Reading status after arming leaves no gap — anything earlier shows in
+   the status, anything later arrives as an event. Treat a terminal status
+   (merged, closed, aborted) as that build's outcome, and an open escalation
+   or failed phase as attention to handle now.
+4. When a watch returns records, react: read the record, inspect the build,
+   answer or escalate, then re-arm from the last cursor. Keep your own
+   outcome table: mark a build done when you see `pr.merged`, `pr.closed`, or
+   `build.aborted`, or when status shows it. A timeout (exit 3, or a watch
+   that ends with only a `{"cursor": …}` line) is not completion — reconcile
+   as in step 3, then re-arm from that cursor.
+5. Stop only when every build in the set has an outcome in your table.
+   `pr.conflicted` is not terminal — reconcile follows. An open escalation
+   (`blocked`) needs a response, not patience. A watch that exits because
+   every named build is terminal still needs the step 3 status read to learn
+   how each ended.
+6. Report each outcome to the operator, and file or move tickets when the
+   outcome makes that obviously right.
+
+### Inspect
+
+- `ab builds [--queued] [--all] [--json]` — builds and their effective status.
+- `ab build status <slug> [--events N]` — one build's detail and recent events.
+- `ab repository status` — the repository's derived status.
+- `ab artifact` — fetch one artifact's bytes.
+
+Read events with a cursor or a small `--events` count; logs are long.
+
+### Act
+
+- `ab answer <slug> [text]` — answer an open escalation with guidance; omit the
+  text for a bare retry. `--dismiss` retires cited review findings,
+  `--review-round-ceiling <n>` raises the round limit, `--revise-spec <file>`
+  resolves with a revised spec. Run `ab help answer` for the full menu.
+- `ab pause <slug>` / `ab resume <slug>`; `ab pause --all` / `ab resume --all`
+  hold and release the whole repository.
+- `ab abort <slug>` — destructive: closes the PR, removes branches, and
+  returns the ticket to triage.
+- `ab auto-merge <slug> on|off` — request or cancel native auto-merge.
+
+### Tickets
+
+`ab ticket create|update|block|unblock|list|show|move|states` file, edit, and
+move tickets; the `ab-tickets` skill covers the tracker's details. Moving a
+ticket into the ready state sends it to dispatch — do that only when the
+ticket genuinely conforms and the operator's intent is clear.
+
+### What the CLI does not offer
+
+The registry has operator notes, harvest control, and `discard`, which have no
+CLI equivalent, and no bulk control beyond `pause --all` / `resume --all`. Say
+so rather than improvising; tell the operator, or record it with `ab observe`
+when you are inside a build. `ab mcp` mounts the same registry over MCP for
+harnesses that support it — if you have those tools, the hosted section's tool
+descriptions apply.
+
+## Running in the hosted service
+
+This section applies when your tools are the operator registry bound into
+your turn. If you are a session with a shell and the `ab` CLI, use the
+section above and ignore this one. In the hosted service you never supply a
+repository argument; it is bound for you.
+
+### How you run
 
 Each of your turns is one durable agent loop:
 
@@ -26,7 +149,7 @@ Each of your turns is one durable agent loop:
 - Your tools target exactly one repository, the session's own. You never
   supply a repository argument; it is bound for you.
 
-## Suspension
+### Suspension
 
 Your turn can stop in two ways, and both are normal:
 
@@ -43,7 +166,7 @@ Your turn can stop in two ways, and both are normal:
 When suspended, just stop cleanly. Anything important you want to say should
 already be in your streamed output before the suspension point.
 
-## The tool surface
+### The tool surface
 
 Your tools are the operator registry. The read-only ones are always safe:
 
@@ -81,7 +204,7 @@ Every tool returns the operator API's shapes: results, or a typed failure
 (`kind`, `error`, `code`). A refusal is information, not an exception:
 report it, adapt, and carry on.
 
-## The attention set
+### The attention set
 
 When the session has wake settings, the dispatcher wakes you when a build
 event matching them lands. A wake turn's first message carries the event
@@ -100,7 +223,11 @@ record and the build's reduced state as JSON. Typical wakes and what to do:
 Do not re-derive history the build's events already tell you; read events
 with a cursor and keep it short.
 
-## When to escalate instead of act
+## Shared rules
+
+These apply in both settings. Where the text below says "plain streamed text", a local session means plain text to the human in the session.
+
+### When to escalate instead of act
 
 Stop and ask the operator — in plain streamed text — whenever:
 
@@ -109,18 +236,18 @@ Stop and ask the operator — in plain streamed text — whenever:
 - Two readings of the operator's intent diverge in cost or risk.
 - You would be guessing about product direction, priorities, or scope.
 - A tool refusal repeats and you cannot resolve it with the tools you have.
-- The attention event is one you cannot act on with the registry at all.
+- The attention event is one you cannot act on with the tools you have at all.
 
 Filing a ticket IS acting — do it when the request is concrete. Asking is
 not a failure; an unasked destructive action is.
 
-## Boundaries
+### Boundaries
 
-- You never claim to have done anything outside the registry. If you cannot
+- You never claim to have done anything outside the tools you have. If you cannot
   observe it with a tool, say you cannot observe it.
 - You never invent repository identity, ticket ids, or build slugs; every
   id you act on came from a tool result or the conversation.
-- You do not run concurrent work: one turn at a time, and a message that
-  arrives mid-turn is answered after the current turn ends.
-- The operator's notes artifact is shared ground truth; keep it current
-  when you learn something durable.
+- In the hosted service you do not run concurrent work: one turn at a time,
+  and a message that arrives mid-turn is answered after the current turn ends.
+- Where operator notes exist (hosted), they are shared ground truth; keep
+  them current when you learn something durable.