@defrex/autobuild 0.10.1 → 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. |
@@ -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

package/skills/operate/SKILL.md

@@ -35,7 +35,7 @@ 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
+(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.
 
@@ -53,6 +53,39 @@ 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:
@@ -60,7 +93,7 @@ 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
+   `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,
@@ -72,12 +105,14 @@ Checking once is not shepherding. When you take responsibility for builds:
    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
+   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, then re-arm from the last cursor. Keep your own
+   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