@defrex/autobuild 0.10.0 → 0.11.0

package/packages/core/src/cli/dashboard/render.ts

@@ -722,6 +722,21 @@ interface DetailGeometry extends DetailBodyLayout {
   limit: number
 }
 
+function standbyLine(model: DashboardModel, color: boolean, width: number): string[] {
+  return model.standby === undefined
+    ? []
+    : [
+        truncate(
+          paint(
+            `  Dispatcher on standby: repository held by ${displayText(model.standby)}`,
+            'yellow',
+            color,
+          ),
+          width,
+        ),
+      ]
+}
+
 function upgradeNoticeLine(
   model: DashboardModel,
   color: boolean,
@@ -749,7 +764,8 @@ function detailGeometry(
   const build = model.builds.find((candidate) => candidate.slug === view.slug)
   if (build === undefined) return undefined
   const layout = detailBody(build, view, { color: false, width, height, now: 0 })
-  const topLength = 2 + (model.availableUpgrade === undefined ? 0 : 1)
+  const topLength =
+    2 + (model.standby === undefined ? 0 : 1) + (model.availableUpgrade === undefined ? 0 : 1)
   const controls =
     model.resumeInput !== undefined || model.abortConfirmation !== undefined
       ? dashboardControls(model, false, width, controlsCapacity(height, topLength))
@@ -808,6 +824,7 @@ function renderDetail(model: DashboardModel, opts: RenderOpts): string[] {
       `  status ${paint(build.status.toUpperCase(), STATUS_COLOR[build.status], color)}${paused}`,
       width,
     ),
+    ...standbyLine(model, color, width),
     ...(notice === undefined ? [] : [notice]),
   ]
   const { body } = detailBody(build, view, opts)
@@ -862,11 +879,12 @@ export function transcriptScrollLimit(
   terminalWidth: number,
   height: number,
   hasUpgradeNotice = false,
+  hasStandby = false,
 ): number {
   const contentLines = transcriptContent(presentation, dashboardContentWidth(terminalWidth)).length
-  // Transcript chrome is two header rows, the optional upgrade row, two
+  // Transcript chrome is two header rows, optional standby/upgrade rows, two
   // separators, and controls. Keep this in lockstep with renderTranscript.
-  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0))
+  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0) - (hasStandby ? 1 : 0))
   return Math.max(0, contentLines - capacity)
 }
 
@@ -877,8 +895,15 @@ export function moveTranscriptScroll(
   current: number,
   delta: number,
   hasUpgradeNotice = false,
+  hasStandby = false,
 ): number {
-  const limit = transcriptScrollLimit(presentation, terminalWidth, height, hasUpgradeNotice)
+  const limit = transcriptScrollLimit(
+    presentation,
+    terminalWidth,
+    height,
+    hasUpgradeNotice,
+    hasStandby,
+  )
   // Clamp current first because a resize, or state from an older controller,
   // may leave it beyond the freshly wrapped viewport's end.
   return Math.max(0, Math.min(limit, Math.min(current, limit) + delta))
@@ -909,6 +934,7 @@ function renderTranscript(model: DashboardModel, opts: RenderOpts): string[] {
   const top = [
     truncate(`${paint('Transcript', 'bold', color)}  ${displayText(view.slug)}`, width),
     truncate(`  session ${displayText(view.sessionId)}`, width),
+    ...standbyLine(model, color, width),
     ...(notice === undefined ? [] : [notice]),
   ]
   const content = transcriptContent(view.transcript, width).map((line) => truncate(line, width))
@@ -948,11 +974,12 @@ export function sessionScrollLimit(
   terminalWidth: number,
   height: number,
   hasUpgradeNotice = false,
+  hasStandby = false,
 ): number {
   const contentLines = sessionContentLines(view, dashboardContentWidth(terminalWidth)).length
-  // Session chrome is two header rows, the optional upgrade row, two
+  // Session chrome is two header rows, optional standby/upgrade rows, two
   // separators, and controls — the transcript's exact arithmetic.
-  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0))
+  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0) - (hasStandby ? 1 : 0))
   return Math.max(0, contentLines - capacity)
 }
 
@@ -963,8 +990,9 @@ export function moveSessionScroll(
   current: number,
   delta: number,
   hasUpgradeNotice = false,
+  hasStandby = false,
 ): number {
-  const limit = sessionScrollLimit(view, terminalWidth, height, hasUpgradeNotice)
+  const limit = sessionScrollLimit(view, terminalWidth, height, hasUpgradeNotice, hasStandby)
   // Clamp current first: a resize, a feed apply, or state from an older
   // controller may leave it beyond the freshly wrapped viewport's end.
   return Math.max(0, Math.min(limit, Math.min(current, limit) + delta))
@@ -983,6 +1011,7 @@ function renderSessionView(model: DashboardModel, opts: RenderOpts): string[] {
       }`,
       width,
     ),
+    ...standbyLine(model, color, width),
     ...(notice === undefined ? [] : [notice]),
   ]
   const content = sessionContentLines(view, width).map((line) => truncate(line, width))
@@ -1417,6 +1446,7 @@ function renderDashboardContent(model: DashboardModel, opts: RenderOpts): string
   const top = [
     summary,
     toggles,
+    ...standbyLine(model, color, width),
     ...(upgradeNotice === undefined ? [] : [upgradeNotice]),
     ...warnings,
   ]

package/packages/core/src/cli/dispatch-frontend.ts

@@ -1,3 +1,4 @@
+import { StandbyIdentityResolver } from './dispatcher-liveness'
 import { configSchema, type Config } from '../config/schema'
 import { humanActor } from '../events/envelope'
 import type { RepositoryEvent } from '../events/repository'
@@ -114,6 +115,7 @@ export interface DispatchFrontendOptions {
 /** Terminal controller with a deliberately narrow wiring surface: terminal,
  * BuildStore, immutable repository identity, clock, and child supervision. */
 export class DispatchFrontend {
+  private readonly standbyResolver: StandbyIdentityResolver
   private readonly runId = crypto.randomUUID()
   private readonly clock: Clock
   private readonly region: LiveRegion
@@ -153,6 +155,7 @@ export class DispatchFrontend {
   private operatorStopRequested = false
 
   constructor(private readonly opts: DispatchFrontendOptions) {
+    this.standbyResolver = new StandbyIdentityResolver(opts.store, opts.repo)
     this.clock = opts.clock ?? systemClock
     this.keyboard = createKeyboardProtocol(
       (chunk) => opts.terminal.write(chunk),
@@ -191,6 +194,7 @@ export class DispatchFrontend {
                 this.opts.store.getRepoEvents(this.opts.repo, 0),
               )
             : await this.opts.store.getRepoEvents(this.opts.repo, 0)
+        this.standbyResolver.ingest(seed)
         this.repositorySeq = seed.at(-1)?.seq ?? 0
         this.dispatchStatus = reduceDispatchStatus(seed, this.runId)
         this.repositoryEvents.push(...seed.filter(isDashboardRepositoryEvent))
@@ -199,6 +203,7 @@ export class DispatchFrontend {
       }
       const delta = await this.opts.store.getRepoEvents(this.opts.repo, this.repositorySeq)
       if (delta.length === 0) return
+      this.standbyResolver.ingest(delta)
       this.repositorySeq = delta.at(-1)!.seq
       this.dispatchStatus = reduceDispatchStatus(delta, this.runId, this.dispatchStatus)
       this.repositoryEvents.push(...delta.filter(isDashboardRepositoryEvent))
@@ -367,10 +372,14 @@ export class DispatchFrontend {
       ...status.roleWarnings,
       ...(status.warningNotice !== undefined ? [status.warningNotice] : []),
     ]
+    const standby = this.opts.once
+      ? undefined
+      : await this.standbyResolver.refresh(this.runId, status.yieldedHolder, this.clock())
     const projected = buildDashboardFromProjected(
       snapshot.builds,
       {
         repo: this.opts.repo,
+        ...(standby !== undefined ? { standby } : {}),
         queued: status.queued ?? 0,
         activeCount: [...snapshot.states.values()].filter(
           (state) => state.status !== 'done' && state.status !== 'aborted',
@@ -409,6 +418,7 @@ export class DispatchFrontend {
         this.opts.terminal.columns,
         paintableRows(this.opts.terminal.rows),
         upgrade,
+        this.model?.standby !== undefined,
       )
       const current = view.follow ? limit : view.scroll
       const scroll = moveSessionScroll(
@@ -418,6 +428,7 @@ export class DispatchFrontend {
         current,
         delta,
         upgrade,
+        this.model?.standby !== undefined,
       )
       let follow = view.follow
       if (delta < 0 && follow && scroll < limit) follow = false
@@ -437,6 +448,7 @@ export class DispatchFrontend {
           this.view.scroll,
           delta,
           this.model?.availableUpgrade !== undefined,
+          this.model?.standby !== undefined,
         ),
       }
     } else if (this.view?.kind === 'detail' && this.model !== undefined) {
@@ -598,6 +610,7 @@ export class DispatchFrontend {
             terminal.columns,
             paintableRows(terminal.rows),
             this.model?.availableUpgrade !== undefined,
+            this.model?.standby !== undefined,
           )
           this.view = {
             ...next,
@@ -977,7 +990,9 @@ export class DispatchFrontend {
   private requestOperatorStop(): void {
     this.operatorStopRequested = true
     this.restorePresentationForStop()
-    void this.child?.stop()
+    void this.child?.stop(
+      typeof this.opts.signal?.reason === 'string' ? this.opts.signal.reason : undefined,
+    )
   }
 
   /** Stop terminal ownership synchronously before awaiting a kernel that may

package/packages/core/src/cli/dispatch-process.ts

@@ -25,7 +25,7 @@ export interface DispatchChildResult {
 
 export interface DispatchChildHandle {
   completed: Promise<DispatchChildResult>
-  stop(): Promise<void>
+  stop(signal?: string): Promise<void>
 }
 
 export interface DispatchSubprocess {
@@ -57,16 +57,20 @@ export interface DispatchKernelSignalBoundary {
  * one-shot handlers would expose the child to the default disposition on a
  * repeated Ctrl-C while it is still crossing an unsafe claim boundary. */
 export function installDispatchKernelSignalHandlers(
-  onStop: () => void,
+  onStop: (signal: DispatchKernelSignal) => void,
   boundary: DispatchKernelSignalBoundary = process,
 ): DispatchProcessHook {
-  for (const signal of DISPATCH_KERNEL_SIGNALS) boundary.on(signal, onStop)
+  const listeners = DISPATCH_KERNEL_SIGNALS.map((signal) => ({
+    signal,
+    listener: () => onStop(signal),
+  }))
+  for (const { signal, listener } of listeners) boundary.on(signal, listener)
   let closed = false
   return {
     close(): void {
       if (closed) return
       closed = true
-      for (const signal of DISPATCH_KERNEL_SIGNALS) boundary.removeListener(signal, onStop)
+      for (const { signal, listener } of listeners) boundary.removeListener(signal, listener)
     },
   }
 }
@@ -156,13 +160,14 @@ export function superviseDispatchChild(deps: DispatchChildSupervisorDeps): Dispa
   env[DISPATCH_CHILD_OPTIONS_ENV] = JSON.stringify(deps.options)
   const child = (deps.spawn ?? defaultSpawn)({ entrypoint, cwd: deps.cwd ?? deps.repo, env })
 
+  let requestedSignal: string | undefined
   let stopping = false
   let forced = false
   let stopPromise: Promise<void> | undefined
   // This is the sole supervisor writer of a missing stop fact. `stop()` only
   // chooses/awaits process termination, avoiding check-then-append races.
   const completed = child.exited.then(async (exitCode): Promise<DispatchChildResult> => {
-    const processSignal = child.signalCode === null ? undefined : String(child.signalCode)
+    const processSignal = child.signalCode === null ? requestedSignal : String(child.signalCode)
     const events = await deps.store.getRepoEvents(deps.repo)
     const recorded = events.findLast(
       (event) => event.type === 'dispatcher.run-stopped' && event.payload.run === deps.run,
@@ -179,7 +184,7 @@ export function superviseDispatchChild(deps: DispatchChildSupervisorDeps): Dispa
 
     const outcome: DispatchChildOutcome = forced
       ? 'forced'
-      : stopping && exitCode === 0 && processSignal === undefined
+      : stopping && exitCode === 0 && child.signalCode === null
         ? 'normal'
         : 'abnormal'
     const error =
@@ -209,11 +214,24 @@ export function superviseDispatchChild(deps: DispatchChildSupervisorDeps): Dispa
 
   return {
     completed,
-    stop(): Promise<void> {
+    stop(signal?: string): Promise<void> {
       if (stopPromise !== undefined) return stopPromise
       stopPromise = (async () => {
         if (child.exitCode !== null) return
         stopping = true
+        requestedSignal = signal
+        if (signal !== undefined) {
+          try {
+            await deps.store.appendRepo(deps.repo, {
+              actor: DISPATCHER,
+              type: 'dispatcher.stop-requested',
+              payload: { run: deps.run, signal },
+            })
+          } catch {
+            // Signal delivery must survive a transient Store failure. The
+            // kernel can still record its own abort reason after draining.
+          }
+        }
         child.kill('SIGINT')
         const timeout = deps.stopTimeoutMs ?? DEFAULT_STOP_TIMEOUT_MS
         const stopped = await Promise.race([

package/packages/core/src/cli/dispatch.ts

@@ -1,3 +1,5 @@
+import { readDispatcherLiveness, StandbyIdentityResolver } from './dispatcher-liveness'
+import { formatDispatcherIdentity } from '../kernel/dispatcher-liveness'
 /**
  * `ab dispatch` — the operator's entry into the outer loop (SPEC §3.3, §12).
  * Runs OUTSIDE build sessions like init/upgrade/ticket (§16.3): it takes a
@@ -691,6 +693,9 @@ class DispatchLoop {
    * discarded on Escape. All read semantics live in the shared feed module. */
   private sessionFeed: SessionStreamFeed | undefined
   private warningLine: string | undefined
+  /** Invocation-local ownership; independent of every notice slot. */
+  private standby: string | undefined
+  private standbyResolver: StandbyIdentityResolver | undefined
   /** Process-local, persistent release notice. It never shares the replaceable
    * warning slot and is re-applied to every store projection. */
   private availableUpgrade: string | undefined
@@ -1190,6 +1195,7 @@ class DispatchLoop {
       selection: _oldSelection,
       warningLines: _oldWarningLines,
       availableUpgrade: _oldAvailableUpgrade,
+      standby: _oldStandby,
       resumeInput: _oldResumeInput,
       abortConfirmation: _oldAbortConfirmation,
       view: _oldView,
@@ -1204,6 +1210,7 @@ class DispatchLoop {
     ]
     let effective: DashboardModel = {
       ...base,
+      ...(this.standby !== undefined ? { standby: this.standby } : {}),
       ...(this.availableUpgrade !== undefined ? { availableUpgrade: this.availableUpgrade } : {}),
       ...(warningLines.length > 0 ? { warningLines } : {}),
       ...(this.selection !== undefined ? { selection: this.selection } : {}),
@@ -1258,7 +1265,13 @@ class DispatchLoop {
     const limit =
       terminal === undefined
         ? 0
-        : sessionScrollLimit(view, terminal.columns, paintableRows(terminal.rows), upgrade)
+        : sessionScrollLimit(
+            view,
+            terminal.columns,
+            paintableRows(terminal.rows),
+            upgrade,
+            this.standby !== undefined,
+          )
     const current = view.follow ? limit : view.scroll
     const scroll =
       terminal === undefined
@@ -1270,6 +1283,7 @@ class DispatchLoop {
             current,
             delta,
             upgrade,
+            this.standby !== undefined,
           )
     let follow = view.follow
     if (delta < 0 && follow && scroll < limit) follow = false
@@ -1291,6 +1305,7 @@ class DispatchLoop {
       terminal.columns,
       paintableRows(terminal.rows),
       this.availableUpgrade !== undefined,
+      this.standby !== undefined,
     )
     return { ...view, scroll: view.follow ? limit : Math.min(view.scroll, limit) }
   }
@@ -1350,6 +1365,7 @@ class DispatchLoop {
                 this.view.scroll,
                 delta,
                 this.availableUpgrade !== undefined,
+                this.standby !== undefined,
               ),
       }
       this.syncModelControls()
@@ -3389,6 +3405,18 @@ class DispatchLoop {
     const claimed = await this.wiring.store
       .claimRepoLease(this.repoIdentity, holder, REPO_LEASE_TTL_MS)
       .catch(() => false)
+    if (this.dashboard && !this.opts.once) {
+      this.standbyResolver ??= new StandbyIdentityResolver(this.wiring.store, this.repoIdentity)
+      this.standby = claimed
+        ? undefined
+        : await this.standbyResolver.refresh(
+            this.runId,
+            this.yieldedTo ?? 'another invocation',
+            this.wiring.clock(),
+          )
+      this.syncModelControls()
+      this.paint()
+    }
     if (!claimed) {
       if (this.repoLeaseHolder !== undefined) {
         // We held the lease and the store says it is gone: a peer took over.
@@ -3474,10 +3502,17 @@ class DispatchLoop {
     const holder = this.runId
     if (!(await this.ensureRepoLease(holder))) {
       await this.recordTickYielded()
-      const peer = (await this.wiring.store.getRepo(this.repoIdentity).catch(() => null))?.lease
-        ?.holder
-      const message = `tick yielded: repository held by ${peer ?? 'another invocation'}`
-      this.warn(message)
+      if ((!this.dashboard && this.opts.kernelRunId === undefined) || this.opts.once) {
+        const peer = (await this.wiring.store.getRepo(this.repoIdentity).catch(() => null))?.lease
+          ?.holder
+        const liveness = await readDispatcherLiveness(
+          this.wiring.store,
+          this.repoIdentity,
+          this.wiring.clock(),
+        ).catch(() => null)
+        const message = `tick yielded: repository held by ${liveness?.dispatcher.holder ? formatDispatcherIdentity(liveness.dispatcher.holder) : (peer ?? 'another invocation')}`
+        this.warn(message)
+      }
       if (this.opts.once === true) return
       // Watch mode stays alive and retries the claim at every tick.
     }
@@ -3498,7 +3533,17 @@ class DispatchLoop {
         // lease and any provisioning state are released for the next
         // invocation.
         if (this.pastDeadline()) return
-        const initial = await this.dispatcherTick(true)
+        const initial = await this.dispatcherTick(true).catch(async (error: unknown) => {
+          await this.appendStatus({
+            actor: DISPATCHER,
+            type: 'dispatcher.tick-failed',
+            payload: {
+              run: this.runId,
+              error: error instanceof Error ? error.message : String(error),
+            },
+          })
+          throw error
+        })
         const initialPrinted = this.printReport(initial, false)
         await this.drainInFlight()
         const settledReports = await this.publishSettlementReports()
@@ -3963,6 +4008,7 @@ export async function abDispatch(opts: DispatchOpts): Promise<void> {
         payload: {
           run: runId,
           pid: process.pid,
+          host: hostname(),
           effectiveConfig: { kind: artifact.kind, rev: artifact.revision },
           roleWarnings: roleKeyWarnings(config),
         },
@@ -3973,6 +4019,17 @@ export async function abDispatch(opts: DispatchOpts): Promise<void> {
   const loop = new DispatchLoop(liveConfig, wiring, resolvedOpts, view)
   try {
     await loop.run()
+    const stopRequest = (
+      resolvedOpts.kernelRunId && resolvedOpts.signal?.aborted
+        ? await wiring.store.getRepoEvents(state.repo)
+        : []
+    ).find((event) => event.type === 'dispatcher.stop-requested' && event.payload.run === runId)
+    const stoppedSignal =
+      stopRequest?.type === 'dispatcher.stop-requested'
+        ? stopRequest.payload.signal
+        : typeof resolvedOpts.signal?.reason === 'string'
+          ? resolvedOpts.signal.reason
+          : undefined
     await view.appendRepo(state.repo, {
       actor: DISPATCHER,
       type: 'dispatcher.run-stopped',
@@ -3980,6 +4037,7 @@ export async function abDispatch(opts: DispatchOpts): Promise<void> {
         run: runId,
         outcome: 'normal',
         exitCode: 0,
+        ...(stoppedSignal === undefined ? {} : { signal: stoppedSignal }),
         ...(loop.supersededByPeer ? { reason: 'superseded' as const } : {}),
       },
     })

package/packages/core/src/cli/dispatcher-liveness.ts

@@ -0,0 +1,91 @@
+import type { RepositoryEvent } from '../events/repository'
+import type { BuildStore, RepositoryRecord } from '../store/types'
+import { formatDispatcherIdentity, projectDispatcherLiveness } from '../kernel/dispatcher-liveness'
+
+/** Bounded first; a later yielding invocation can hide the owner's identity or
+ * an earlier stop. Only this correlation query falls back to full history. */
+export async function readDispatcherLiveness(
+  store: BuildStore,
+  repo: string,
+  now = new Date(),
+  subset?: RepositoryEvent[],
+) {
+  const record = await store.getRepo(repo)
+  let events = record === null ? [] : (subset ?? (await store.getRepoStateEvents(repo)))
+  const bounded = projectDispatcherLiveness(record, events, now)
+  if (
+    record &&
+    ((record.lease &&
+      !events.some(
+        (e) => e.type === 'dispatcher.run-started' && e.payload.run === record.lease!.holder,
+      )) ||
+      (bounded.state !== 'held' &&
+        events.some((e) => e.type === 'dispatcher.run-started') &&
+        !events.some((e) => e.type === 'dispatcher.run-stopped')))
+  ) {
+    events = await store.getRepoEvents(repo)
+  }
+  return { record, events, dispatcher: projectDispatcherLiveness(record, events, now) }
+}
+
+/** Invocation-local identity cache. Only start facts survive refreshes; ages
+ * always come from the current lease record and clock. Failed correlations are
+ * negatively cached so a standby cannot repeatedly replay a large journal. */
+export class StandbyIdentityResolver {
+  private readonly starts = new Map<string, RepositoryEvent>()
+  private readonly attempted = new Set<string>()
+  private readonly pending = new Map<string, Promise<void>>()
+
+  constructor(
+    private readonly store: BuildStore,
+    private readonly repo: string,
+  ) {}
+
+  ingest(events: readonly RepositoryEvent[]): void {
+    for (const event of events) {
+      if (event.type === 'dispatcher.run-started') this.starts.set(event.payload.run, event)
+    }
+  }
+
+  private async correlate(holder: string): Promise<void> {
+    const pending = this.pending.get(holder)
+    if (pending !== undefined) return pending
+    if (this.starts.has(holder) || this.attempted.has(holder)) return
+    this.attempted.add(holder)
+    const lookup = (async () => {
+      try {
+        this.ingest(await this.store.getRepoStateEvents(this.repo))
+        if (!this.starts.has(holder)) this.ingest(await this.store.getRepoEvents(this.repo, 0))
+      } catch {
+        // Identity is best effort; the sampled holder id remains sufficient.
+      }
+    })()
+    this.pending.set(holder, lookup)
+    try {
+      await lookup
+    } finally {
+      this.pending.delete(holder)
+    }
+  }
+
+  async refresh(
+    run: string,
+    yieldedHolder: string | undefined,
+    now: Date,
+  ): Promise<string | undefined> {
+    let record: RepositoryRecord | null
+    try {
+      record = await this.store.getRepo(this.repo)
+    } catch {
+      return yieldedHolder
+    }
+    const holder = record?.lease?.holder
+    if (holder === run) return undefined
+    if (holder === undefined) return yieldedHolder
+    await this.correlate(holder)
+    if (!this.starts.has(holder)) return holder
+    const projection = projectDispatcherLiveness(record, [...this.starts.values()], now)
+    const identity = projection.holder ?? projection.expiredHolder
+    return identity?.run === holder ? formatDispatcherIdentity(identity) : holder
+  }
+}

package/packages/core/src/cli/help.ts

@@ -282,7 +282,7 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       '  ab watch [<slug>...] [--repository] [--event <glob>]... [--since <cursor>] [--timeout <duration>] [--interval <duration>] [--count <n>] [--json] [--store <ref>]',
       '',
       'Follow the event logs of one, several, or all active builds in this repository —',
-      'optionally the repository journal — and emit one record per matching event as it',
+      'the repository journal by default with no slugs — and emit one record per matching event as it',
       'lands. With no slug, every nonterminal build (queued, running, paused, blocked) is',
       'watched, and a build created while the watch runs joins it without a restart.',
       'Naming one or more slugs watches exactly those builds; an unknown slug is an error',
@@ -291,16 +291,18 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       '',
       'Options:',
       '  --repository       Also follow the repository journal (dispatcher and harvest',
-      '                     events). Without it, repository events are never emitted.',
+      '                     events) for named watches. No-slug watches include it by default.',
       '  --event <glob>     Repeatable glob over event type names: * matches any run of',
       '                     characters, ? one character (escalation.*, pr.merged, *). Every',
       '                     glob must match at least one type in the build catalog — or,',
-      '                     with --repository, the repository catalog — or the command fails',
+      '                     with no slugs or --repository, the repository catalog — or the command fails',
       '                     before any store read. Any --event replaces the default filter.',
       '  --since <cursor>   Resume from a cursor emitted by an earlier record; every matching',
       '                     event after that cursor is delivered exactly once, including',
       '                     events that landed while no watch was running. A cursor from a',
-      '                     different repository or store is rejected.',
+      '                     different repository or store is rejected. A legacy cursor without',
+      '                     a repository position baselines that stream now; reconcile earlier',
+      '                     source conditions with ab repository status.',
       '  --timeout <dur>    End the watch after this duration (30, 45s, 5m, 1h). Default',
       '                     30 minutes; 0 means unbounded.',
       '  --interval <dur>   Poll cadence. Default: 5s for an http(s) store, 1s for a local store.',
@@ -313,7 +315,8 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       'infrastructure.failed, runner.setup-failed, dispatch.failed, publication.lost,',
       'finalize.completed, pr.conflicted, pr.merged, pr.closed, build.completed,',
       'build.aborted. For the repository journal: harvest.escalated, harvest.failed,',
-      'dispatcher.tick-failed, dispatcher.config-rejected, dispatcher.harvest-runner-failed.',
+      'dispatcher.tick-failed, dispatcher.config-rejected, dispatcher.harvest-runner-failed,',
+      'dispatcher.ticket-source-degraded, dispatcher.ticket-source-recovered.',
       '',
       'Record shape (--json): build (slug, or null for a repository event), repo (repository',
       'id, present only for repository events), event (the complete durable envelope: build,',

package/packages/core/src/cli/init.ts

@@ -161,11 +161,12 @@ export async function ensureLocalStateIgnored(targetRepo: string): Promise<boole
  * pattern-matching a description. Membership here is reserved for skills that
  * drive NO phase — `spec` is the conversation that writes a spec before a build
  * exists, `tickets` is how "move ticket X to ready" becomes an action, and
- * `guide` is read-only reference material about the system. For these, model
+ * `guide` is read-only reference material about the system, and `operate` is the
+ * orchestrator role's manual (a role any agent takes on, not a pipeline phase). For these, model
  * invocation is precisely the point. Keep this set small; widening it needs the
  * §16.3 criterion, not convenience.
  */
-export const MODEL_INVOCABLE_SKILLS = new Set(['spec', 'tickets', 'guide'])
+export const MODEL_INVOCABLE_SKILLS = new Set(['spec', 'tickets', 'guide', 'operate'])
 
 /**
  * Rewrite a canonical skill's YAML frontmatter for installation (§16.3):