@defrex/autobuild 0.10.0 → 0.11.0

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

@@ -45,6 +45,7 @@ export type DigestEvent = DigestEventRow
 
 /** The carried accumulator for `reduceBuildDigest`. */
 export interface DigestAcc {
+  readinessChangeSeq?: number
   terminal?: BuildDigest['terminal']
   merged?: string
   observations: { seq: number; ts: string }[]
@@ -57,7 +58,7 @@ export interface DigestAcc {
 }
 
 /** Bump when `DigestAcc`'s shape or fold semantics change. */
-export const BUILD_DIGEST_REDUCER_VERSION = 2
+export const BUILD_DIGEST_REDUCER_VERSION = 3
 
 export const buildDigestReducer: IncrementalReducer<
   DigestAcc,
@@ -68,6 +69,8 @@ export const buildDigestReducer: IncrementalReducer<
   initial: (): DigestAcc => ({ observations: [], hosted: [], reclaimed: [], openInstance: null }),
   fold(acc, events) {
     for (const event of events) {
+      if (['pr.merged', 'build.completed', 'build.aborted'].includes(event.type))
+        acc.readinessChangeSeq = event.seq
       if (event.type === 'build.completed') acc.terminal = 'done'
       else if (event.type === 'build.aborted') acc.terminal = 'aborted'
       else if (event.type === 'pr.merged') acc.merged = event.ts
@@ -84,11 +87,20 @@ export const buildDigestReducer: IncrementalReducer<
       }
     }
   },
-  finish: ({ terminal, merged, observations, hosted, reclaimed, openInstance }) => {
+  finish: ({
+    readinessChangeSeq,
+    terminal,
+    merged,
+    observations,
+    hosted,
+    reclaimed,
+    openInstance,
+  }) => {
     const reclaimedSet = new Set(reclaimed)
     const reclaimPending = hosted.some((seq) => !reclaimedSet.has(seq))
     return {
       observations: [...observations],
+      ...(readinessChangeSeq !== undefined ? { readinessChangeSeq } : {}),
       ...(merged !== undefined ? { merged } : {}),
       ...(terminal !== undefined ? { terminal } : {}),
       ...(reclaimPending ? { reclaimPending: true as const } : {}),

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

@@ -46,6 +46,7 @@ import { createSessionScopedStore } from '../session-handle'
 import { DIGEST_EVENT_TYPES, type DigestEventRow, reduceBuildDigest } from '../digest'
 import {
   REPOSITORY_STATE_EVENT_TYPES,
+  REPOSITORY_LATEST_EVENT_TYPES,
   readRepoStateEventsWithAnchorRecheck,
 } from '../repo-state-events'
 import {
@@ -1188,14 +1189,26 @@ export class SqliteBuildStore implements BuildStore {
       },
       async (anchor) => {
         const durable = inArray(repoEvents.type, [...REPOSITORY_STATE_EVENT_TYPES])
+        const latest = REPOSITORY_LATEST_EVENT_TYPES.map((type) =>
+          and(
+            eq(repoEvents.type, type),
+            sql`${repoEvents.seq} = (SELECT seq FROM repo_events WHERE repo = ${repo} AND type = ${type} ORDER BY seq DESC LIMIT 1)`,
+          ),
+        )
+        const tail =
+          anchor === undefined
+            ? undefined
+            : and(
+                gte(repoEvents.seq, anchor),
+                sql`${repoEvents.type} NOT IN (${sql.join(
+                  REPOSITORY_LATEST_EVENT_TYPES.map((type) => sql`${type}`),
+                  sql`, `,
+                )})`,
+              )
         const rows = this.db
           .select()
           .from(repoEvents)
-          .where(
-            anchor === undefined
-              ? and(eq(repoEvents.repo, repo), durable)
-              : and(eq(repoEvents.repo, repo), or(gte(repoEvents.seq, anchor), durable)),
-          )
+          .where(and(eq(repoEvents.repo, repo), or(durable, tail, ...latest)))
           .orderBy(asc(repoEvents.seq))
           .all()
         return rows.map(

package/packages/core/src/store/remote/protocol.ts

@@ -285,6 +285,7 @@ export const buildDigestWireSchema = z.object({
     }),
   ),
   merged: z.string().min(1).optional(),
+  readinessChangeSeq: z.number().int().positive().optional(),
   reclaimPending: z.literal(true).optional(),
   executionOpen: z.literal(true).optional(),
 })

package/packages/core/src/store/repo-state-events.ts

@@ -1,54 +1,12 @@
-/**
- * The bounded repository-journal read (AUT-489): a pure subset derivation
- * that stateless full-state readers can fetch instead of the whole journal
- * without changing what their reducers report.
- *
- * The hosted dispatcher appends ~4 journal events per invocation (run-started,
- * tick-started, tick-completed/tick-yielded, run-stopped) whether or not it
- * did anything, so the journal grows forever with wall-clock time while the
- * durable signal stays small. Every repository-state consumer reduces the
- * journal through one of four pure reducers whose event-type dependencies
- * partition the catalog:
- *
- * - `reduceDispatchSettings` — only the three dispatcher setting types
- *   (latest-wins by seq).
- * - `reduceDispatchStatus(events, latestRun)` — only run-correlated
- *   dispatcher facts, and it skips every event whose `payload.run` is not the
- *   latest run. A run's facts are appended under its own run id, which is
- *   minted at `dispatcher.run-started`, so all facts the reducer keeps live at
- *   or after the latest run-started.
- * - `reduceHarvest` (and everything built on it) — only `harvest.*` events
- *   plus the three setting types, which it explicitly ignores.
- * - `sandboxStates` — only `orchestrator.sandbox.*` events.
- *
- * So the bounded subset is: **every event of a durable (slow-growing) type —
- * all `harvest.*`, all `orchestrator.sandbox.*`, and the three dispatcher
- * setting types — plus, when the journal contains at least one
- * `dispatcher.run-started`, the tail from that latest run-started to the end
- * of the journal.** For a hosted repository with N no-op invocations this
- * subset's size is a constant (one invocation's ~4 facts plus the durable
- * signal), independent of N.
- *
- * INVARIANT FOR AUTHORS OF NEW REPOSITORY EVENT TYPES: a new type must either
- * (a) join `REPOSITORY_STATE_EVENT_TYPES` — it is durable, slow-growing state
- * some reducer depends on at full replay depth — or (b) join
- * `REPOSITORY_RUN_SCOPED_EVENT_TYPES` — it is run-correlated and its only
- * consumers reduce it for the latest run, so the tail from the latest
- * `dispatcher.run-started` covers it. `tests/store/repo-state-events.test.ts`
- * asserts the two sets exactly partition `REPOSITORY_EVENT_TYPES`; adding a
- * type to neither fails the build until the author makes the call. A type in
- * neither set would be silently dropped from bounded reads.
- *
- * Reducing this subset with the state readers yields exactly what a full
- * replay yields: `reduceDispatchSettings`, `reduceHarvest`, `sandboxStates`
- * see identical event lists, and `reduceDispatchStatus` sees every event it
- * keeps (the rest are skipped by the `payload.run !== latestRun` guard). The
- * journal itself stays append-only; no event is deleted, rewritten, or
- * re-ordered, and a replay from the start is untouched.
+/** Bounded journal state has three disjoint, exhaustive categories:
+ * durable facts retain all history; run-scoped facts retain the latest run
+ * tail; latest-only facts retain exactly the greatest sequence per type,
+ * including before any run anchor. The full journal remains append-only.
  */
 import type { RepositoryEvent, RepositoryEventType } from '../events/repository'
 import { defineReducer, type IncrementalReducer } from '../kernel/incremental'
 import {
+  ticketSourceHealthEventPayloadSchemas,
   dispatcherSettingEventPayloadSchemas,
   dispatcherStatusEventPayloadSchemas,
   harvestEventPayloadSchemas,
@@ -64,6 +22,7 @@ const RUN_STARTED = 'dispatcher.run-started'
  * setting types are enumerated because they share one schema group with the
  * run-correlated `dispatcher.config-reloaded`. */
 export const REPOSITORY_STATE_EVENT_TYPES: readonly RepositoryEventType[] = [
+  ...Object.keys(ticketSourceHealthEventPayloadSchemas),
   ...Object.keys(harvestEventPayloadSchemas),
   ...Object.keys(orchestratorSandboxEventPayloadSchemas),
   ...Object.keys(dispatcherSettingEventPayloadSchemas).filter(
@@ -71,11 +30,19 @@ export const REPOSITORY_STATE_EVENT_TYPES: readonly RepositoryEventType[] = [
   ),
 ] as RepositoryEventType[]
 
+/** Latest-only measurements survive run turnover without retaining scan history. */
+export const REPOSITORY_LATEST_EVENT_TYPES: readonly RepositoryEventType[] = [
+  'dispatcher.ticket-scan-completed',
+]
+const LATEST_TYPES = new Set<string>(REPOSITORY_LATEST_EVENT_TYPES)
+
 /** Run-correlated repository event types: facts whose only state consumers
  * reduce them for the latest dispatcher run, so the tail from the latest
  * `dispatcher.run-started` contains everything those consumers keep. */
 export const REPOSITORY_RUN_SCOPED_EVENT_TYPES: readonly RepositoryEventType[] = [
-  ...Object.keys(dispatcherStatusEventPayloadSchemas),
+  ...Object.keys(dispatcherStatusEventPayloadSchemas).filter(
+    (type) => !REPOSITORY_LATEST_EVENT_TYPES.includes(type as RepositoryEventType),
+  ),
   'dispatcher.config-reloaded',
 ] as RepositoryEventType[]
 
@@ -122,8 +89,8 @@ export async function readRepoStateEventsWithAnchorRecheck(
 }
 
 /** Carried state for the bounded read: the latest run-started seq (the last
- * in array order, as the whole-array pass overwrites it) and every event seen,
- * in array order. Nothing is pruned: a later run-started may carry a lower seq
+ * in array order, as the whole-array pass overwrites it) and every ordinary event seen,
+ * in array order, plus one latest-only fact per type. Ordinary history is retained: a later run-started may carry a lower seq
  * than an earlier one and restore events below the earlier anchor, so only
  * `finish` can apply the filter exactly. Pruning below a monotone anchor is
  * valid only for seq-ordered input and belongs with the cached-state
@@ -134,10 +101,11 @@ export interface RepositoryStateEventsAcc {
 }
 
 /** Bump when `RepositoryStateEventsAcc` or its fold changes. */
-export const REPOSITORY_STATE_EVENTS_REDUCER_VERSION = 1
+export const REPOSITORY_STATE_EVENTS_REDUCER_VERSION = 4
 
 const keeps = (event: RepositoryEvent, anchor: number | undefined): boolean =>
-  STATE_TYPES.has(event.type) || (anchor !== undefined && event.seq >= anchor)
+  STATE_TYPES.has(event.type) ||
+  (!LATEST_TYPES.has(event.type) && anchor !== undefined && event.seq >= anchor)
 
 export const repositoryStateEventsReducer: IncrementalReducer<
   RepositoryStateEventsAcc,
@@ -149,10 +117,24 @@ export const repositoryStateEventsReducer: IncrementalReducer<
   fold(acc, events) {
     for (const event of events) {
       if (event.type === RUN_STARTED) acc.anchor = event.seq
+      if (LATEST_TYPES.has(event.type)) {
+        const held = acc.retained.find((held) => held.type === event.type)
+        if (held !== undefined && held.seq >= event.seq) continue
+        acc.retained = acc.retained.filter((held) => held.type !== event.type)
+      }
       acc.retained.push(event)
     }
   },
-  finish: (acc) => acc.retained.filter((event) => keeps(event, acc.anchor)),
+  finish: (acc) => {
+    const latest = new Map<string, RepositoryEvent>()
+    for (const event of acc.retained) {
+      if (LATEST_TYPES.has(event.type) && event.seq > (latest.get(event.type)?.seq ?? -1))
+        latest.set(event.type, event)
+    }
+    return [...acc.retained.filter((event) => keeps(event, acc.anchor)), ...latest.values()].sort(
+      (a, b) => a.seq - b.seq,
+    )
+  },
 })
 
 /** Carried state for the pruned journal view: the latest run-started seq and
@@ -167,16 +149,23 @@ export interface JournalViewAcc {
 }
 
 /** Bump when `JournalViewAcc` or its fold changes. */
-export const JOURNAL_VIEW_REDUCER_VERSION = 1
+export const JOURNAL_VIEW_REDUCER_VERSION = 4
 
 /** Fold seq-ordered events into a journal view in place. */
 export function foldJournalView(acc: JournalViewAcc, events: readonly RepositoryEvent[]): void {
   for (const event of events) {
     if (event.type === RUN_STARTED) {
       acc.anchor = event.seq
-      acc.retained = acc.retained.filter((held) => STATE_TYPES.has(held.type))
+      acc.retained = acc.retained.filter(
+        (held) => STATE_TYPES.has(held.type) || LATEST_TYPES.has(held.type),
+      )
     }
-    if (STATE_TYPES.has(event.type) || acc.anchor !== undefined) acc.retained.push(event)
+    if (LATEST_TYPES.has(event.type)) {
+      const held = acc.retained.find((held) => held.type === event.type)
+      if (held !== undefined && held.seq >= event.seq) continue
+      acc.retained = acc.retained.filter((held) => held.type !== event.type)
+      acc.retained.push(event)
+    } else if (STATE_TYPES.has(event.type) || acc.anchor !== undefined) acc.retained.push(event)
   }
 }
 
@@ -193,9 +182,10 @@ export const journalViewReducer: IncrementalReducer<
 
 /** The normative subset derivation every adapter implements and the contract
  * tests use as the oracle: durable types across the whole journal, plus —
- * only when the journal has one — every event from the latest
- * `dispatcher.run-started` onward, ordered by seq. A journal with no
- * run-started has **no tail at all** (durable types only); the anchor is
+ * only when the journal has one — every non-latest-only event from the latest
+ * `dispatcher.run-started` onward, plus the maximum-sequence fact of each
+ * latest-only type across the whole journal, ordered by seq. A journal with no
+ * run-started has **no tail at all** (durable and latest-only facts only); the anchor is
  * never defaulted to 0, which would make a `seq >= anchor` clause select the
  * whole journal and defeat the bound. */
 export function projectRepositoryStateEvents(

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

@@ -105,6 +105,8 @@ export interface ArtifactMeta {
  * 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 {
+  /** Latest merge, completion or abort fact sequence. */
+  readinessChangeSeq?: number
   slug: string
   terminal?: 'done' | 'aborted'
   /** Ascending-seq `{seq, ts}` pairs for every `observation.recorded` in the
@@ -368,7 +370,9 @@ export interface BuildStore {
   ): 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`.
+   * the journal has one — the tail from the latest `dispatcher.run-started`,
+   * excluding latest-only types; plus exactly the maximum-sequence fact for
+   * each REPOSITORY_LATEST_EVENT_TYPES type across the whole journal.
    * Reducing this subset with the state readers yields exactly what a full
    * replay yields (`projectRepositoryStateEvents` is the normative oracle).
    * Unknown repo rejects like `getRepoEvents`. */

package/skills/guide/SKILL.md

@@ -234,6 +234,19 @@ Every other known table is closed to unknown keys. The removed `[dashboardFrames
 `[dispatcher]`, `[harvest]`, and `[outer]` tables have no aliases or migration
 shims; they fail as ordinary unknown top-level keys.
 
+Ticket-source ready scans run immediately when no completed measurement exists,
+then every
+`ticketScanIntervalSeconds` (default 60 seconds, a positive integer). Actual
+tick spacing is the floor when the configured interval is shorter. A
+same-repository `pr.merged`, `build.completed`, or `build.aborted` fact forces
+another scan on the next tick; changed ready criteria also force a scan.
+Housekeeping keeps its ordinary tick cadence. Between scans, queue depth and
+standing diagnostics repeat the last completed measurement, including across
+process restarts. Tickets groomed directly in the tracker are picked up within
+one scan interval plus one tick when capacity permits. Observation while intake
+is off shares the cadence; an observation measurement cannot suppress a fresh
+admission scan when intake is enabled.
+
 ### Root scalars
 
 Root scalars must appear before the first TOML table; TOML otherwise nests them
@@ -242,6 +255,7 @@ under the preceding table.
 | Field | Default | Allowed / constraints | Effect |
 |---|---|---|---|
 | `baseBranch` | `"main"` | nonempty string | The branch builds branch from and target with their PR; what `reconcile` merges into the build branch. |
+| `ticketScanIntervalSeconds` | `60` | positive integer seconds | Hot-reloaded ready scan cadence; tick spacing is the floor, and same-repository merge/completion/abort forces an early scan. |
 | `capacity` | `1` | positive integer | Maximum concurrent builds for this repository. |
 | `forge` | `"github"` | nonblank string | Selects shipped `github` or `local-git`, or a plugin-registered Forge adapter. `github` authenticates with `GITHUB_TOKEN`, then `GH_TOKEN`, then the gh CLI's stored login. |
 | `plugins` | `[]` | array of unique nonblank module specifiers | Trusted Bun plugin modules loaded before dispatch, `ab ticket`, and scoped phase wiring. |
@@ -899,7 +913,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
@@ -1650,6 +1664,23 @@ matching event after that cursor is delivered exactly once, in per-stream
 sequence order — including events that landed while no watch was running. A
 cursor from a different repository or store is rejected.
 
+
+Dispatcher liveness is also visible through `ab repository status --json`:
+`dispatcher.holder` identifies the unexpired repository lease owner, independently
+of `latestRun`. Heartbeat age measures attributable renewals; tick age measures
+durable progress. Missing historical evidence is null. The liveness query uses
+bounded repository facts first, with a full-history fallback when a later
+invocation hides the holder start or the latest stop. Other state reads retain
+their bounded semantics.
+
+Repository-following `ab watch` additionally emits a read-only `dispatcher.lost`
+observation when an observed lease expires without a matching stop. JSON carries
+`observation` instead of `event`, with run, observedAt, leaseExpiresAt and available
+identity, plus the usual repo/build/state/cursor fields. It invents no durable
+sequence or actor. Retain the cursor to avoid repeat reports across invocations.
+No lease alone is not evidence of death. SIGINT, SIGHUP and SIGTERM drain dispatch,
+record the first signal in the stop fact, and release its lease before exit.
+
 The watch ends with exit 0 when `--timeout` elapses (30 minutes by default;
 `0` unbounded), after `--count <n>` records, or when named builds have all
 gone terminal; with no slugs named, an empty set of active builds does not end
@@ -1878,16 +1909,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/operate/SKILL.md

@@ -1,17 +1,175 @@
 ---
 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.
+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.
 
-## How you run
+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) and repository attention are watched. Named watches need `--repository` to also receive repository attention. `--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.
+
+Ticket-source degradation records mean dispatch intake cannot evaluate the source;
+existing builds may still advance. Inspect `ab repository status --json` for the
+active cause, operation, message, and expected reset. Reset times are advisory;
+recovery means reads actually succeeded. Allow the existing cooldown and retry
+behavior, investigate persistent ready-scan failures or a condition still active
+after its reset estimate, and keep watching through recovery. Empty builds do
+not establish idle intake; repeatedly restarting dispatch does not clear it.
+
+Repository records have null build and state. Handle them with repository
+status rather than build commands, keep their cursor, and re-arm. A legacy
+cursor without a repository position baselines that stream at attachment and
+cannot recover its earlier interval: reconcile current repository status.
+`ab wait --for attention` remains build-only and does not replace a repository
+attention watch.
+
+
+Check dispatcher liveness with `ab repository status --json` before starting another
+`ab dispatch`, and after a watch timeout or `dispatcher.lost` observation. Do not
+use process lists to decide whether a dispatcher owns this repository. The
+`dispatcher` projection distinguishes `held` (an unexpired lease), `lost`
+(expired ownership without a recorded stop), `stopped`, and `absent`. Its holder
+identity resolves a yield message to run, pid, host, start time, and heartbeat
+age. Historical identity and a new holder's heartbeat may be unknown until its
+first attributable renewal. Source degradation or an old tick alone does not
+establish loss: a healthy lease can accompany a slow tick.
+
+An unscoped watch, or a named watch with `--repository`, reports loss as a
+read-only observation: `{repo, build:null, state:null, observation:{type:
+"dispatcher.lost", run, observedAt, leaseExpiresAt, ...identity}, cursor}`.
+It has no durable event envelope. Keep its cursor just as for event records;
+resuming it suppresses repeated loss reports for that run. Inspect repository
+status before deciding how to recover; watch never restarts a dispatcher.
+
+### 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 --json --since <cursor>` (or named slugs with `--repository`) (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, and `ab repository status --json` for source health, initially and after
+   every timeout or legacy-cursor attachment. 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; for a repository record inspect repository status and act
+   on its condition without assuming a build slug. 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 +184,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 +201,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 +239,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 +258,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 +271,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.