jackherd 1.18.2 → 1.19.0

package/src/watch/clear-moment.ts

@@ -0,0 +1,228 @@
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { firstTableWithHeader, sectionLines } from '../plan-format/markdown'
+import { isRecord } from '../shared/is-record'
+import { AGENT_STATUS, isRestingAgent } from '../terminal/types'
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { coordinatorTargetOf } from './coordinator-fill'
+import { type HerdrAgent, NO_AGENT } from './lane-watch'
+import { questionCount, questionSections } from './report-questions'
+
+export const COORDINATOR_CLEAR_EVENT = 'coordinator clear'
+
+/** The word of a merge in the report; `watch-events.ts` imports this module, so its constant cannot be read here. */
+const MERGED_EVENT = 'merged'
+
+export type CoordinatorClearEvent = { kind: typeof COORDINATOR_CLEAR_EVENT; tokens: number }
+
+/** The fills at which the coordinator clears: `plans.context.coordinator`. */
+type ClearThresholds = { clearTokens: number; clearAfterMergeTokens: number }
+
+type ClearLane = {
+  name: string
+  status: string
+  /** The questions of its report not yet shown to the coordinator (`unshownQuestionCount`). */
+  questions: number
+}
+
+/** Everything a moment to clear depends on; `tokens` is null without a value, `coordinatorStatus` when it is not listed. */
+export type ClearInput = {
+  tokens: number | null
+  thresholds: ClearThresholds
+  coordinatorStatus: string | null
+  /** The coordinator has something to read: a report goes out in this poll or just went out. */
+  reportPending: boolean
+  lanes: readonly ClearLane[]
+  /** The ids of the approval requests a lane still waits on. */
+  openApprovals: readonly string[]
+  /** The open pull requests the user approved with self-merge. */
+  selfMergePullRequests: readonly number[]
+  /** When the last merge not yet taken as a moment to clear was seen; null without one. */
+  mergedAt: number | null
+  /** The change time of the board; null when it cannot be read. */
+  boardWrittenAt: number | null
+}
+
+type ClearVerdict = { clear: true } | { clear: false; reason: string }
+
+/** What one poll saw besides the fill: the lanes it reports as stopped, its events and when the last report went out. */
+type PollNews = {
+  stopped: readonly string[]
+  events: readonly { kind: string }[]
+  quietSince: number
+  now: number
+  /** How long a report just printed counts as unread: the coordinator's status may still say it rests. */
+  settleMs: number
+}
+
+/** What the watcher remembers: the fill above `clearTokens` was reported, and the merge still to be taken as a moment. */
+export type ClearState = { fillReported: boolean; mergedAt: number | null }
+
+export const emptyClearState = (): ClearState => ({ fillReported: false, mergedAt: null })
+
+export const isClearState = (value: unknown): value is ClearState =>
+  isRecord(value) &&
+  typeof value.fillReported === 'boolean' &&
+  (value.mergedAt === null || typeof value.mergedAt === 'number')
+
+/** A merge is a moment once the fill reached its threshold and the board was written after it. */
+const isMergeMoment = ({ tokens, thresholds, mergedAt, boardWrittenAt }: ClearInput): boolean =>
+  tokens !== null &&
+  tokens >= thresholds.clearAfterMergeTokens &&
+  mergedAt !== null &&
+  boardWrittenAt !== null &&
+  boardWrittenAt > mergedAt
+
+const coordinatorRefusal = ({ coordinatorStatus, reportPending }: ClearInput): string | null => {
+  if (coordinatorStatus === null) return 'coordinator not listed'
+  if (coordinatorStatus === AGENT_STATUS.blocked) return 'dialog open'
+  if (!isRestingAgent(coordinatorStatus)) return `coordinator ${coordinatorStatus}`
+  return reportPending ? 'report pending' : null
+}
+
+const laneRefusal = ({ name, status, questions }: ClearLane): string | null => {
+  if (status === AGENT_STATUS.blocked) return `lane ${name} blocked`
+  return questions > 0 ? `lane ${name} has ${questions} unshown questions` : null
+}
+
+/** Why what is open forbids clearing now; null when nothing is. */
+const openWorkRefusal = (input: ClearInput): string | null => {
+  const lane = input.lanes.map(laneRefusal).find((refusal) => refusal !== null)
+  if (lane) return lane
+  const [approval] = input.openApprovals
+  if (approval !== undefined) return `approval ${approval} open`
+  const [pullRequest] = input.selfMergePullRequests
+  return pullRequest === undefined ? null : `self-merge #${pullRequest} open`
+}
+
+/**
+ * Whether the coordinator may clear its context now: its fill reached `clearTokens`, or `clearAfterMergeTokens` after
+ * a merge with the board written afterwards, and nothing lives only in its chat: no dialog, nothing unread, no blocked
+ * lane, no question not yet shown, no approval a lane waits on, no open pull request with self-merge.
+ */
+export const clearMoment = (input: ClearInput): ClearVerdict => {
+  if (input.tokens === null) return { clear: false, reason: 'no value' }
+  if (input.tokens < input.thresholds.clearTokens && !isMergeMoment(input))
+    return { clear: false, reason: 'below threshold' }
+  const reason = coordinatorRefusal(input) ?? openWorkRefusal(input)
+  return reason === null ? { clear: true } : { clear: false, reason }
+}
+
+/**
+ * One poll's step: the event when the moment is quiet and not yet reported, once per rise above `clearTokens` and once
+ * per merge, and the state to keep. A fill below a threshold forgets what it counted for, so a clear does not fire
+ * again and a later rise does. No value keeps the state.
+ */
+export const clearStep = (
+  state: ClearState,
+  input: ClearInput,
+): { event: CoordinatorClearEvent | null; state: ClearState } => {
+  const { tokens, thresholds, mergedAt } = input
+  if (tokens === null) return { event: null, state: { ...state, mergedAt } }
+  const isDue = isMergeMoment(input) || !state.fillReported
+  const fires = isDue && clearMoment(input).clear
+  const isBelowMergeThreshold = tokens < thresholds.clearAfterMergeTokens
+  return {
+    event: fires ? { kind: COORDINATOR_CLEAR_EVENT, tokens } : null,
+    state: {
+      fillReported: tokens >= thresholds.clearTokens && (state.fillReported || fires),
+      mergedAt: fires || isBelowMergeThreshold ? null : mergedAt,
+    },
+  }
+}
+
+/** Whether the coordinator still has something to read: a report goes out in this poll, or went out just now. */
+export const isReportPending = ({ stopped, events, quietSince, now, settleMs }: PollNews): boolean =>
+  stopped.length > 0 || events.length > 0 || now - quietSince < settleMs
+
+/** The merge to keep for the next step: this poll's when it saw one, else the one still remembered. */
+export const mergedAtAfter = (
+  events: readonly { kind: string }[],
+  remembered: number | null,
+  now: number,
+): number | null => (events.some(({ kind }) => kind === MERGED_EVENT) ? now : remembered)
+
+/** The status of the coordinator as `coordinatorTargetOf` finds it; null when it is not listed or no name is known. */
+export const coordinatorStatusOf = (
+  agents: readonly HerdrAgent[],
+  name: string | null,
+  pane: string | undefined,
+): string | null => {
+  if (name === null) return null
+  const target = coordinatorTargetOf(agents, name, pane)
+  if (target.kind === 'absent') return null
+  const agent = agents.find((candidate) =>
+    target.kind === 'named' ? candidate.name === name : candidate.pane_id === target.pane,
+  )
+  return agent?.agent_status ?? null
+}
+
+/** The questions in a report's questions sections, as `questionsFingerprint` keeps them. */
+export const questionCountOf = (fingerprint: string): number => {
+  const lines = fingerprint.split('\n')
+  return questionCount(lines, questionSections(lines))
+}
+
+/**
+ * The questions of a lane's report the coordinator has not been shown: all of them while the fingerprint differs from
+ * the one remembered when its report was last shown, none once they match. A report seen for the first time is the
+ * baseline and holds nothing, as in `askingLanes`. A question shown or taken as the baseline stays open in the lane's
+ * report, and `jh resume --coordinator` names it after a clear.
+ */
+export const unshownQuestionCount = (current: string, shown: string | undefined): number =>
+  shown === undefined || current === shown ? 0 : questionCountOf(current)
+
+/**
+ * The lanes as `clearMoment` reads them. A lane without an agent holds nothing with its report: it will not fire again,
+ * so the hold would last until its report changes, and `jh resume --coordinator` names its questions.
+ */
+export const clearLanesOf = (
+  lanes: readonly string[],
+  current: Readonly<Record<string, { status: string } | undefined>>,
+  questions: Readonly<Record<string, string>> | null,
+  shown: Readonly<Record<string, string>>,
+): ClearLane[] =>
+  lanes.map((name) => {
+    const status = current[name]?.status ?? NO_AGENT
+    const count = status === NO_AGENT ? 0 : unshownQuestionCount(questions?.[name] ?? '', shown[name])
+    return { name, status, questions: count }
+  })
+
+/** The time at the start of an entry of a history cell: `11:39: ` or `~11:39: `. */
+const ENTRY_TIME = /(?:^|\s)~?(\d{1,2}:\d{2}):(?=\s)/g
+const PULL_REQUEST_NUMBER = /#(\d+)/g
+/** An approval in the board's words or the question's, never one a word before it denies. */
+const SELF_MERGE =
+  /(?<!\b(?:kein|keine|keinen|nicht|ohne|no|not|without)\s)\b(?:self[- ]?merge|selbst[- ]?merge|merge it yourself)/i
+
+/** The entries of a history cell, each with its time; text before the first time belongs to none. */
+const entriesOf = (cell: string): { time: string; text: string }[] => {
+  const matches = [...cell.matchAll(ENTRY_TIME)]
+  return matches.map((match, position) => ({
+    time: (match[1] ?? '').padStart(5, '0'),
+    text: cell.slice(match.index + match[0].length, matches[position + 1]?.index),
+  }))
+}
+
+const numbersIn = (text: string): number[] => [...text.matchAll(PULL_REQUEST_NUMBER)].map((match) => Number(match[1]))
+
+/**
+ * The open pull requests the board's history says the user approved with self-merge within the last `minutes`. The
+ * entry is free text, so this reads it by its words and its time; a miss only means the merge guard asks again, and a
+ * wrong hit holds a clear up until the approval lapses.
+ */
+export const selfMergePullRequests = (
+  board: string,
+  language: PlanLanguage,
+  open: readonly number[],
+  now: number,
+  minutes: number,
+): number[] => {
+  const { rows } = firstTableWithHeader(sectionLines(board, PLAN_VOCABULARY[language].sections.history))
+  const approved = rows.flatMap(([date, ...cells]) =>
+    entriesOf(cells.join(' '))
+      .filter(({ text }) => SELF_MERGE.test(text))
+      .filter(({ time }) => now - new Date(`${date}T${time}:00`).getTime() <= minutes * MS_PER_MINUTE)
+      .flatMap(({ text }) => numbersIn(text)),
+  )
+  return open.filter((number) => approved.includes(number))
+}

package/src/watch/command.ts

@@ -68,6 +68,16 @@ import {
 } from './appointments'
 import { type ApprovalRequestFile, approvalEvents, readApprovalRequests, recordApprovals } from './approvals'
 import { askingLanes, questionsFingerprint, recordReportQuestions } from './asking-lanes'
+import {
+  type ClearInput,
+  type ClearState,
+  clearLanesOf,
+  clearStep,
+  coordinatorStatusOf,
+  isReportPending,
+  mergedAtAfter,
+  selfMergePullRequests,
+} from './clear-moment'
 import {
   baselinesOf,
   type LiveValues,
@@ -184,7 +194,7 @@ import {
   previewReadOf,
   unreportedTargets,
 } from './previews'
-import { latestPullRequestOf, type WatchedPullRequest } from './pull-requests'
+import { latestPullRequestOf, PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { recordedReadsOf } from './recorded-reads'
 import {
   annotateEach,
@@ -280,12 +290,14 @@ type Watch = {
   skillCopies: SkillCopy[]
   /** The tools of `guard.approvals.standing`: an approval of one of them points to the stage approval reference. */
   stageTools: readonly string[]
+  /** `guard.selfMerge.approvalMinutes`: how long an entry in the board's history holds a clear up. */
+  selfMergeMinutes: number
   /** Runs inside herdr with the herdr adapter, so missing herd panes can be brought back. */
   herdr: boolean
 }
 
-/** The coordinator's agent name (null when none is found) and its last read (null before the first one). */
-type Coordinator = { name: string | null; read: CoordinatorRead | null }
+/** The coordinator's agent name (null when none is found), its last read (null before the first one) and the tokens of that read (null without a value). */
+type Coordinator = { name: string | null; read: CoordinatorRead | null; tokens: number | null }
 
 /**
  * What the loop knows between polls. `state` is the record as of the last GitHub read that did not
@@ -310,6 +322,8 @@ type Watching = {
   laneBranches: Record<string, string>
   githubReadAt: number
   coordinator: Coordinator
+  /** What `coordinator clear` already reported and the merge still to be taken as a moment; persisted like the fingerprints. */
+  coordinatorClear: ClearState
   herdrDown: boolean
   reporting: boolean
   /** The fetch of the base branch under way, null when none runs; the next one waits for it, a report after a merge too. */
@@ -408,6 +422,7 @@ const recordedOf = (watch: Watch, watching: Watching): WatchState => {
     laneLevels: recordLaneLevels(withReads.laneLevels, watching.laneReadings, watching.lanes),
     laneModels: recordLaneModels(withReads.laneModels, watching.laneModelReadings, watching.lanes),
     laneParallels: recordLaneParallels(withReads.laneParallels, watching.laneParallelReadings, watching.lanes),
+    coordinatorClear: watching.coordinatorClear,
     taskParallels: watching.taskParallels,
     parallelAutoEnded: watching.parallelAutoEnded,
     noTaskSignals: watching.noTaskSignals,
@@ -490,7 +505,12 @@ const coordinatorNameFor = (watch: Watch, agents: readonly HerdrAgent[]): string
  * One read of the fills: the coordinator's, and each watched lane's (null without a value), with `models`, lane → the
  * model of its agent's last answer (null without one), read from the same report.
  */
-type FillRead = { coordinator: CoordinatorRead; lanes: LaneReadings; models: Record<string, string | null> }
+type FillRead = {
+  coordinator: CoordinatorRead
+  coordinatorTokens: number | null
+  lanes: LaneReadings
+  models: Record<string, string | null>
+}
 
 /**
  * The coordinator's fill with its own thresholds, as `jh context <name> --coordinator` computes it, or why there
@@ -507,11 +527,12 @@ const fillReadFor = (watch: Watch, name: string, agents: readonly HerdrAgent[],
     const reports = lanes.map((lane) => [lane, contextReport(listed, lane, agentLog, watch.settings.context)] as const)
     return {
       coordinator: explainedRead(coordinatorReadOf(own), target, name, watch.texts),
+      coordinatorTokens: own?.tokens ?? null,
       lanes: Object.fromEntries(reports.map(([lane, report]) => [lane, contextReadingOf(report)])),
       models: Object.fromEntries(reports.map(([lane, report]) => [lane, report?.model ?? null])),
     }
   } catch (error) {
-    return { coordinator: { reason: errorText(error) }, lanes: {}, models: {} }
+    return { coordinator: { reason: errorText(error) }, coordinatorTokens: null, lanes: {}, models: {} }
   }
 }
 
@@ -1050,7 +1071,7 @@ const pollGithubAndCoordinator = async (watch: Watch, watching: Watching, now: n
     ...recordFeedbackRead(watching, feedback?.read ?? null),
     ...recordPreviewRead(watching, previews),
     ...recordSourceRuns(watching, sourceRuns),
-    ...recordCoordinator(watching, { name, read: fills.coordinator }),
+    ...recordCoordinator(watching, { name, read: fills.coordinator, tokens: fills.coordinatorTokens }),
     ...recordLaneFills(watching, fills.lanes),
     ...recordLaneModelReads(watching, laneModelReadingsOf(watch, watching, fills.models, modelProgress)),
     ...recordLaneParallelReads(watching, laneParallelReadingsOf(watch, watching)),
@@ -1395,6 +1416,66 @@ const takeStoppedLanes = (watch: Watch, watching: Watching): string[] => {
   return [...fired, ...askingLanes(working, watching.reportQuestions, watching.state.reportQuestions)]
 }
 
+/** The open pull requests the board's history approves with self-merge; none below the thresholds, where it decides nothing, or when the board cannot be read. */
+const selfMergesOf = (watch: Watch, watching: Watching, now: number): number[] => {
+  const { tokens } = watching.coordinator
+  if (tokens === null || tokens < watch.settings.context.coordinator.clearAfterMergeTokens) return []
+  const board = readBoardText(watch)
+  if (board === null) return []
+  const open = Object.entries(watching.state.pullRequests).flatMap(([number, { state }]) =>
+    state === PULL_REQUEST_STATE.open ? [Number(number)] : [],
+  )
+  return selfMergePullRequests(board, watch.settings.planLanguage, open, now, watch.selfMergeMinutes)
+}
+
+const clearInputOf = (
+  watch: Watch,
+  watching: Watching,
+  reportPending: boolean,
+  mergedAt: number | null,
+  now: number,
+): ClearInput => {
+  const openRequests = approvalEvents([], watching.approvalRequests ?? [], now)
+  return {
+    tokens: watching.coordinator.tokens,
+    thresholds: watch.settings.context.coordinator,
+    coordinatorStatus: coordinatorStatusOf(watching.agents, watching.coordinator.name, process.env.HERDR_PANE_ID),
+    reportPending,
+    lanes: clearLanesOf(watching.lanes, watching.current, watching.reportQuestions, watching.state.reportQuestions),
+    openApprovals: openRequests.map(({ id }) => id),
+    selfMergePullRequests: selfMergesOf(watch, watching, now),
+    mergedAt,
+    boardWrittenAt: reportMtime(watch.sprintFile),
+  }
+}
+
+/**
+ * This poll's `coordinator clear`, when the moment is quiet: a report that goes out now or went out within the last
+ * GitHub poll still has to be read, so it holds the moment up. Records the state in `watching`.
+ */
+const recordCoordinatorClear = (
+  watch: Watch,
+  watching: Watching,
+  stopped: readonly string[],
+  events: readonly WatchEvent[],
+  now: number,
+): WatchEvent[] => {
+  const mergedAt = mergedAtAfter(events, watching.coordinatorClear.mergedAt, now)
+  const reportPending = isReportPending({
+    stopped,
+    events,
+    quietSince: watching.quietSince,
+    now,
+    settleMs: GITHUB_POLL_MS,
+  })
+  const { event, state } = clearStep(
+    watching.coordinatorClear,
+    clearInputOf(watch, watching, reportPending, mergedAt, now),
+  )
+  watching.coordinatorClear = state
+  return event ? [event] : []
+}
+
 /**
  * One poll: reports what is due and tells whether to keep watching. Without `--stream` the first
  * report ends the watch; in a stream every reported lane counts as seen and the heartbeat is one line.
@@ -1412,12 +1493,13 @@ const pollOnce = async (watch: Watch, watching: Watching): Promise<boolean> => {
   // read at every poll like the approvals; the events and the record use the same read and time, so an appointment
   // that falls due between the two is neither recorded unreported nor reported twice
   watching.appointments = readAppointments(watch, now)
-  const polledEvents = [
+  const newsEvents = [
     ...githubEvents,
     ...approvalEvents(watching.state.approvals, watching.approvalRequests, now),
     ...appointmentEvents(watching.state.appointments, watching.appointments?.table ?? null, now),
   ]
   const stopped = takeStoppedLanes(watch, watching)
+  const polledEvents = [...newsEvents, ...recordCoordinatorClear(watch, watching, stopped, newsEvents, now)]
   const heartbeat = isHeartbeatDue(watching.quietSince, now, heartbeatMinutes * MINUTE_MS)
   let next = recordedOf(watch, watching)
   const reported = stopped.length > 0 || polledEvents.length > 0
@@ -1460,7 +1542,8 @@ const initialWatching = (
   github: null,
   laneBranches: {},
   githubReadAt: 0,
-  coordinator: { name: watch.options.coordinator, read: null },
+  coordinator: { name: watch.options.coordinator, read: null, tokens: null },
+  coordinatorClear: start.state.coordinatorClear,
   herdrDown: false,
   reporting: false,
   baseFetch: null,
@@ -1616,6 +1699,7 @@ const watchOf = (options: WatchOptions): Watch => {
     texts: watchTexts(settings.responseLanguage),
     skillCopies: skillCopiesFor(root, homedir(), config.skillPrefix, DEFAULT_SKILL_PREFIX),
     stageTools: stageToolsOf(config.guard.approvals.standing),
+    selfMergeMinutes: config.guard.selfMerge.approvalMinutes,
     herdr: insideHerdr(settings.adapter, process.env),
   }
 }

package/src/watch/lane-report.ts

@@ -166,6 +166,9 @@ export const otherPullRequestsLine = (
   return `${texts.otherPullRequests}: ${[...named, ...(more > 0 ? [`+${more}`] : [])].join(' · ')}`
 }
 
+/** `250k`. */
+const thousandsLabel = (tokens: number): string => `${Math.round(tokens / 1000)}k`
+
 /** The header line of an event about one lane's agent (fill, model, parallel phases, task signal, standing still); null for any other. */
 const laneEventLine = (event: WatchEvent): string | null => {
   if (event.kind === WATCH_EVENT.laneFill)
@@ -184,7 +187,7 @@ const laneEventLine = (event: WatchEvent): string | null => {
  * The header line of one event: `=== merged #<number> (lane)`, `=== checks failed #<number> (lane|branch <name>): <checks> (<k> tests: <names>)`,
  * the checks and tests only when the event carries them,
  * `=== deploy success run 9 (push, lane|#<number>) target stage`, `=== heartbeat`, `=== gh unavailable: <reason>`,
- * `=== coordinator warn 62 %`, `=== lane <name> alert 47 %`, `=== preview #<number> (lane) <url> · <sha7>`.
+ * `=== coordinator warn 62 %`, `=== coordinator clear 250k`, `=== lane <name> alert 47 %`, `=== preview #<number> (lane) <url> · <sha7>`.
  * `target` is the deploy environment read from the run, null when none was found.
  */
 export const watchEventLine = (event: WatchEvent, target: string | null): string => {
@@ -204,6 +207,7 @@ export const watchEventLine = (event: WatchEvent, target: string | null): string
   if (event.kind === WATCH_EVENT.approval)
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${event.id} ${terminalSafe(event.tool)} · ${terminalSafe(event.summary)}`
   if (event.kind === WATCH_EVENT.coordinator) return `=== ${event.kind} ${event.level} ${contextLabel(event.share)}`
+  if (event.kind === WATCH_EVENT.coordinatorClear) return `=== ${event.kind} ${thousandsLabel(event.tokens)}`
   if (isPullRequestEvent(event))
     return `=== ${event.kind} #${event.number} (${pullRequestOwner(event)})${failedChecksSuffix(event)}`
   if ('number' in event) return `=== ${event.kind} #${event.number} (${pullRequestOwner(event)})`

package/src/watch/reference-paths.ts

@@ -13,6 +13,7 @@ export const REFERENCE = {
   events: 'references/events.md',
   laneSession: 'references/lane-session.md',
   coordinatorHandover: 'references/coordinator-handover.md',
+  coordinatorClear: 'references/coordinator-clear.md',
   closeLane: 'references/close-lane.md',
   laneHandover: 'references/lane-handover.md',
   startLane: 'references/start-lane.md',
@@ -38,6 +39,7 @@ const SKILL_ENTRY = 'SKILL.md'
  * lines do not grow. A lane's fill and an approval depend on more than the kind: see `eventReference`.
  */
 const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
+  [WATCH_EVENT.coordinatorClear]: REFERENCE.coordinatorClear,
   [WATCH_EVENT.feedback]: REFERENCE.events,
   [WATCH_EVENT.preview]: REFERENCE.events,
   [WATCH_EVENT.source]: REFERENCE.events,
@@ -54,8 +56,11 @@ const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
   [WATCH_EVENT.laneModel]: REFERENCE.laneSession,
 }
 
-const isCoordinatorHandoverLevel = (level: unknown): boolean =>
-  level === CONTEXT_LEVEL.warn || level === CONTEXT_LEVEL.alert
+/** The reference of the coordinator's rising context: clearing at `warn`, its hand-over at `alert`, none at `ok`. */
+const coordinatorFillReference = (level: unknown): Reference | null => {
+  if (level === CONTEXT_LEVEL.alert) return REFERENCE.coordinatorHandover
+  return level === CONTEXT_LEVEL.warn ? REFERENCE.coordinatorClear : null
+}
 
 /** The reference of a lane whose context rose: its hand-over at `alert`, the events at `warn`. */
 const laneFillReference = (level: unknown): Reference =>
@@ -69,8 +74,7 @@ export const eventReference = (
   event: { kind: string; level?: unknown; tool?: string },
   isStageTool: (tool: string) => boolean = () => false,
 ): Reference | null => {
-  if (event.kind === WATCH_EVENT.coordinator)
-    return isCoordinatorHandoverLevel(event.level) ? REFERENCE.coordinatorHandover : null
+  if (event.kind === WATCH_EVENT.coordinator) return coordinatorFillReference(event.level)
   if (event.kind === WATCH_EVENT.laneFill) return laneFillReference(event.level)
   if (event.kind === WATCH_EVENT.approval)
     return event.tool !== undefined && isStageTool(event.tool) ? REFERENCE.stageApproval : null

package/src/watch/watch-events.ts

@@ -8,6 +8,13 @@ import {
   isAppointmentState,
 } from './appointments'
 import { APPROVAL_EVENT, type ApprovalEvent } from './approvals'
+import {
+  type ClearState,
+  COORDINATOR_CLEAR_EVENT,
+  type CoordinatorClearEvent,
+  emptyClearState,
+  isClearState,
+} from './clear-moment'
 import { type CoordinatorLevel, type CoordinatorReading, isContextLevel, levelStep } from './coordinator-fill'
 import { emptyFailureState, type FailureState, failedTestsOf, isFailureState } from './failures'
 import { emptyFeedbackState, FEEDBACK_EVENT, type FeedbackEvent, type FeedbackState, isFeedbackState } from './feedback'
@@ -53,6 +60,7 @@ export const WATCH_EVENT = {
   heartbeat: 'heartbeat',
   ghUnavailable: 'gh unavailable',
   coordinator: 'coordinator',
+  coordinatorClear: COORDINATOR_CLEAR_EVENT,
   feedback: FEEDBACK_EVENT,
   preview: PREVIEW_EVENT,
   laneFill: LANE_FILL_EVENT,
@@ -103,6 +111,8 @@ export type WatchState = {
   laneBranches: Record<string, string>
   /** The coordinator's level when it was last read with a value; null before the first one (counts as `ok`). */
   coordinatorLevel: CoordinatorLevel | null
+  /** What `coordinator clear` already reported and the merge still to be taken as a moment to clear; see `clear-moment.ts`. */
+  coordinatorClear: ClearState
   /** The feedback seen on the lanes' open pull requests; kept apart from `pullRequests`, it is read over REST. */
   feedback: FeedbackState
   /** The failed tests read from the logs of the lanes' red pull requests, once per head commit; see `failures.ts`. */
@@ -186,6 +196,7 @@ export type WatchEvent =
   | DeployEvent
   | SignalEvent
   | CoordinatorEvent
+  | CoordinatorClearEvent
   | FeedbackEvent
   | PreviewEvent
   | LaneFillEvent
@@ -224,6 +235,7 @@ export const emptyWatchState = (): WatchState => ({
   savedAt: null,
   laneBranches: {},
   coordinatorLevel: null,
+  coordinatorClear: emptyClearState(),
   feedback: emptyFeedbackState(),
   failures: emptyFailureState(),
   previews: emptyPreviewState(),
@@ -279,6 +291,7 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   isSeq(value.savedAt) &&
   everyValue(value.laneBranches, (entry) => typeof entry === 'string') &&
   (value.coordinatorLevel === null || isContextLevel(value.coordinatorLevel)) &&
+  isClearState(value.coordinatorClear) &&
   isFeedbackState(value.feedback) &&
   isFailureState(value.failures) &&
   isPreviewState(value.previews) &&