jackherd 0.0.1 → 1.0.0

package/src/watch/command.ts

@@ -0,0 +1,919 @@
+/**
+ * `jh watch`: waits until the coordinator has something to do and prints it: a lane that stopped, a lane's
+ * pull request that was merged or whose checks settled, a deploy run of a lane's merge or a manual one (only with
+ * `watch.deploy` in the config), new feedback on a lane's open pull request (unless `watch.feedback` is false), a deploy preview for a
+ * lane's new head commit (only with `watch.previews`), a new or changed entry of a configured source or its failure (only
+ * with `watch.sources`), a gh outage, a lane's or the coordinator's own context fill rising to warn or alert, or the
+ * heartbeat. A blocked lane adds one duty line, a merge one per lane, a lane at alert one, and every report ends with one status line
+ * per lane and one for the coordinator, in the words of `responseLanguage`. When the installed kit changes version
+ * it prints `=== kit updated <old> → <new>` and ends. The coordinator is the agent in the
+ * watcher's own herdr pane unless `--coordinator` names it, else `orchestrator-<repository>`. A new start replaces a running watcher of the same
+ * repository; one in another repository keeps running.
+ *
+ * Without `--stream` it exits after one report, whose last line says so and points to the stream: that run is the
+ * fallback where no Monitor tool exists, a background task armed again after every wake-up.
+ * With `--stream` it prints each report in one write and keeps watching, the heartbeat as a single line: run it
+ * under Claude Code's Monitor tool, which turns every line into a message. Without lane names it watches every
+ * worktree whose name a herdr agent carries or the board's lanes table lists, and prints `lane added: <name>` /
+ * `lane removed: <name>` as that set changes. With every GitHub read it fetches `origin/<baseBranch>` once the
+ * remote moved past it, so the plans view, which watches `FETCH_HEAD`, shows a merged lane row at once. Inside herdr
+ * it brings back missing plans views of the board's lanes like `jh plans --ensure`: at its start, for every
+ * added lane and for every lane whose agent appeared.
+ *
+ * `watch source <name> --dry-run` runs one source once instead and prints what it would report (`source-dry-run-command.ts`).
+ *
+ *   jh watch [--stream] [--heartbeat <minutes>] [--board <board.md>] [--coordinator <name>] [<lane> ...]
+ *   jh watch source <name|draft.json|-> --dry-run
+ */
+import { readFileSync } from 'node:fs'
+import { basename, dirname, join, relative } from 'node:path'
+import { readResolvedConfig } from '../config/read-config'
+import type { JackherdConfig } from '../config/schema'
+import { defaultCoordinatorName } from '../context/coordinator-name'
+import { coordinatorSettings } from '../context/options'
+import { contextReport } from '../context/report'
+import { agentLog } from '../context/session-log'
+import { type LaneProgress, parseSprintLanes } from '../plan-format'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { boardFor, foundLanesOf } from '../plans/board-pick'
+import { ensurePlanPanes } from '../plans/ensure-panes'
+import { errorText } from '../plans/error-text'
+import { mainCheckout, worktreeNames, worktreeRoot } from '../plans/git'
+import { discoverLanes, isUnchanged, laneSetChange, laneSetLines } from '../plans/lane-discovery'
+import { clockLocaleOf, type PlansSettings, plansSettingsOf, worktreeOf } from '../plans/settings'
+import { boardTexts } from '../plans/texts'
+import { herdrLaneStatusSource } from '../terminal/herdr'
+import { startedKit } from '../version/started-kit'
+import {
+  type CoordinatorRead,
+  contextReadingOf,
+  coordinatorNameOf,
+  coordinatorReadOf,
+  coordinatorTargetOf,
+  explainedRead,
+  readingOf,
+} from './coordinator-fill'
+import {
+  type FeedbackItem,
+  type FeedbackRead,
+  type FeedbackTarget,
+  feedbackEvents,
+  feedbackReadOf,
+  feedbackSince,
+  feedbackTargets,
+  recordFeedback,
+} from './feedback'
+import { type FeedbackItemsRead, readCommentItems, readFeedbackItems, readOwnLogin } from './feedback-read'
+import { answered, deployTargetOf, type GithubRead, readGithub, targetText } from './github-read'
+import { agentScreen, listAgents } from './herdr'
+import { endedByKitUpdate } from './kit-update'
+import { type LaneReadings, laneFillEvents, recordLaneLevels } from './lane-fill'
+import { laneMessage, rememberedStatusLines, statusBlock } from './lane-message'
+import { boardCheckoutRows, watchedLaneProgress } from './lane-progress'
+import {
+  armLine,
+  blockedDutyLines,
+  coordinatorStatusLine,
+  feedbackEventLines,
+  ghUnavailableStatusLine,
+  type LaneReport,
+  laneFillDutyLines,
+  laneReportLine,
+  mergeDutyLines,
+  otherPullRequestsLine,
+  sourceEventLines,
+  sourceFailingStatusLine,
+  watchEventLine,
+} from './lane-report'
+import { laneReportPath, readLaneReport, reportMtime } from './lane-report-file'
+import { branchOf, fetchBaseWhenMoved } from './lane-sources'
+import {
+  advanceBaseline,
+  armBaseline,
+  baselineWithNewAgents,
+  departedLanes,
+  firedLanes,
+  type HerdrAgent,
+  LANE_GONE,
+  type LaneSnapshot,
+  NO_AGENT,
+  toSnapshot,
+} from './lane-watch'
+import { monitorToolAvailable } from './monitor-tool'
+import { parseWatchOptions, type WatchOptions } from './options'
+import {
+  ENSURE_TRIGGER,
+  type EnsureTrigger,
+  insideHerdr,
+  keepPlanViews,
+  lanesWithNewAgent,
+  type PlanViews,
+} from './plan-views'
+import { readDeploymentCandidates } from './preview-read'
+import {
+  commentCandidates,
+  feedbackFilterOf,
+  feedbackReadCovers,
+  type PreviewRead,
+  previewEvents,
+  previewReadOf,
+  recordPreviews,
+  unreportedTargets,
+} from './previews'
+import { latestPullRequestOf, type WatchedPullRequest } from './pull-requests'
+import { withSingleReportNotice } from './single-report'
+import { readOrchestrateSkill, skillLineFor } from './skill-change'
+import { sourceDryRun } from './source-dry-run-command'
+import { runSource, SOURCE_LIMITS } from './source-run'
+import {
+  isSourceDue,
+  recordSources,
+  type SourceRun,
+  type SourceSettings,
+  type SourceState,
+  sourceEvents,
+} from './sources'
+import { streamHeartbeatLine } from './stream-output'
+import { WATCH_TEXTS, type WatchTexts } from './texts'
+import {
+  coordinatorWatchEvent,
+  deployEvents,
+  emptyWatchState,
+  ghOutageEvent,
+  isHeartbeatDue,
+  mergeCommitsOf,
+  type Observation,
+  ownMergeCommitsOf,
+  parseWatchState,
+  pullRequestEvents,
+  recordCoordinatorLevel,
+  recordWatchState,
+  WATCH_EVENT,
+  type WatchEvent,
+  type WatchState,
+  withReportBaselines,
+} from './watch-events'
+import {
+  ensureWatcherDirectory,
+  releaseLock,
+  stopNoticeOf,
+  takeOverLock,
+  WATCHER_FILES,
+  writePrivate,
+} from './watcher-lock'
+import type { DeployConfig } from './workflow-runs'
+
+type Files = { state: string; lock: string }
+
+/** The logins whose feedback does not count, or false when the project turned feedback off. */
+type FeedbackConfig = JackherdConfig['watch']['feedback']
+
+/** Where deploy previews are read from; undefined when the project reads none. */
+type PreviewsConfig = JackherdConfig['watch']['previews']
+
+/** One feedback read: what counts as feedback, and every item it read, which the previews take their comments from. */
+type FeedbackPoll = { read: FeedbackRead; items: FeedbackItem[] }
+
+/** What one run of the watcher is set up with: the main checkout, the sprint, the command line and the config. */
+type Watch = {
+  root: string
+  sprintFile: string
+  /** Why this board was chosen over others; null when there was no choice or `--board` named it. */
+  boardNotice: string | null
+  options: WatchOptions
+  files: Files
+  settings: PlansSettings
+  deploy: DeployConfig | undefined
+  feedback: FeedbackConfig
+  previews: PreviewsConfig
+  sources: SourceSettings[]
+  texts: WatchTexts
+  /** Runs inside herdr with the herdr adapter, so missing plans views 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 }
+
+/**
+ * What the loop knows between polls. `state` is the record as of the last GitHub read that did not
+ * return; while a report is being written, a stop saves that and not the newer read, so the events
+ * of an interrupted report are reported again instead of being taken as done.
+ */
+type Watching = {
+  /** The lanes watched now: the named ones, or those found at the last herdr poll. */
+  lanes: string[]
+  /** The lane names of the board's lanes table as last read; a failed read keeps them. */
+  sprintLanes: string[]
+  /** Lanes that left the set with their agent since the last poll; they fire as gone once. */
+  departed: string[]
+  /** When the last report or heartbeat was printed, the start before the first. */
+  quietSince: number
+  state: WatchState
+  baseline: LaneSnapshot
+  current: LaneSnapshot
+  /** The last `herdr agent list` answer, kept for finding the coordinator by its pane. */
+  agents: HerdrAgent[]
+  github: GithubRead | null
+  laneBranches: Record<string, string>
+  githubReadAt: number
+  coordinator: Coordinator
+  herdrDown: boolean
+  reporting: boolean
+  /** A fetch of the base branch is under way; the next one waits for it. */
+  fetchingBase: boolean
+  /** The account `gh` runs as, read once it answers; feedback is read only once it is known. */
+  ownLogin: string | null
+  /** The last feedback read that answered; its targets and items are recorded with every state. */
+  feedbackRead: FeedbackRead | null
+  /** The last preview read that answered; recorded with every state like the feedback read. */
+  previewRead: PreviewRead | null
+  /** The runs of the sources due at the last GitHub poll; recorded with every state like the feedback read. */
+  sourceRuns: SourceRun[]
+  /** Source name → when it was last started in this process; a source without an entry runs at the next GitHub poll. */
+  sourceRanAt: Record<string, number>
+  /** The lanes' fills of the last read; a lane without an entry or with null has no value. */
+  laneReadings: LaneReadings
+  planViews: PlanViews
+}
+
+const POLL_MS = 5_000
+const GITHUB_POLL_MS = 60_000
+const MINUTE_MS = 60_000
+const USAGE_EXIT = 2
+
+const clock = (watch: Watch, epochMs: number): string =>
+  new Date(epochMs).toLocaleTimeString(clockLocaleOf(watch.settings))
+
+const agentNamesOf = (agents: readonly HerdrAgent[]): string[] => agents.flatMap((agent) => agent.name ?? [])
+
+const observationOf = (watching: Watching): Observation => ({
+  lanes: watching.current,
+  laneBranches: watching.laneBranches,
+  github: answered(watching.github),
+})
+
+/** Stamped with the time of the last GitHub read, not of the poll: a run created after it is still unseen. */
+const recordedOf = (watch: Watch, watching: Watching): WatchState => {
+  const recorded = recordCoordinatorLevel(
+    recordWatchState(watching.state, observationOf(watching), watching.githubReadAt),
+    readingOf(watching.coordinator.read),
+  )
+  const read = watching.feedbackRead
+  const withFeedback = read ? { ...recorded, feedback: recordFeedback(recorded.feedback, read) } : recorded
+  const previews = watching.previewRead
+  const withPreviews = previews
+    ? { ...withFeedback, previews: recordPreviews(withFeedback.previews, previews) }
+    : withFeedback
+  const withLevels = {
+    ...withPreviews,
+    laneLevels: recordLaneLevels(withPreviews.laneLevels, watching.laneReadings, watching.lanes),
+    sources: recordSources(withPreviews.sources, watching.sourceRuns, sourceNamesOf(watch), watching.githubReadAt),
+  }
+  return withReportBaselines(withLevels, watching.lanes, (lane) => reportMtime(reportPathOf(watch, lane)))
+}
+
+const sourceNamesOf = (watch: Watch): string[] => watch.sources.map(({ name }) => name)
+
+/** The events of one GitHub read against the state it is compared with. */
+const githubEventsOf = (state: WatchState, github: GithubRead, laneBranches: Record<string, string>): WatchEvent[] => {
+  if (!github.ok) {
+    const outage = ghOutageEvent(state, github.error)
+    return outage ? [outage] : []
+  }
+  const branches = { ...state.laneBranches, ...laneBranches }
+  const merges = mergeCommitsOf(github.pullRequests, branches)
+  const ownMerges = ownMergeCommitsOf(state, github.pullRequests, branches)
+  return [
+    ...pullRequestEvents(state, github.pullRequests, branches),
+    ...deployEvents(state, github.runs, merges, ownMerges),
+  ]
+}
+
+const screenOf = (lane: string): string => {
+  try {
+    return agentScreen(lane)
+  } catch (error) {
+    return `screen not readable: ${errorText(error)}`
+  }
+}
+
+const reportPathOf = (watch: Watch, lane: string): string | null =>
+  laneReportPath(worktreeOf(watch.root, watch.settings, lane), lane)
+
+/** The lines under a stopped lane's header and its report time to remember (`laneMessage`). */
+const stopMessageOf = (watch: Watch, lane: string, status: string, state: WatchState) =>
+  laneMessage({
+    status,
+    screen: screenOf(lane),
+    report: readLaneReport(reportPathOf(watch, lane)),
+    reportedMtime: state.reportMtimes[lane] ?? null,
+  })
+
+/** `--coordinator` if given, else the agent in the watcher's own pane, else `orchestrator-<repository>`. */
+const coordinatorNameFor = (watch: Watch, agents: readonly HerdrAgent[]): string =>
+  watch.options.coordinator ??
+  coordinatorNameOf(agents, process.env.HERDR_PANE_ID) ??
+  defaultCoordinatorName(basename(watch.root))
+
+/** One read of the fills: the coordinator's, and each watched lane's (null without a value). */
+type FillRead = { coordinator: CoordinatorRead; lanes: LaneReadings }
+
+/**
+ * The coordinator's fill with its own thresholds, as `jh context <name> --coordinator` computes it, or why there
+ * is none, and each lane's fill with the lanes' thresholds, as the plans view shows it: from one herdr listing. When
+ * herdr cannot be asked, the lanes have no reading, so their stored levels stay.
+ */
+const fillReadFor = (watch: Watch, name: string, agents: readonly HerdrAgent[], lanes: readonly string[]): FillRead => {
+  const target = coordinatorTargetOf(agents, name, process.env.HERDR_PANE_ID)
+  try {
+    const listed = herdrLaneStatusSource.listAgents(
+      target.kind === 'unnamedPane' ? { pane: target.pane, name } : undefined,
+    )
+    const own = contextReport(listed, name, agentLog, coordinatorSettings(watch.settings.context))
+    const laneReading = (lane: string) =>
+      contextReadingOf(contextReport(listed, lane, agentLog, watch.settings.context))
+    return {
+      coordinator: explainedRead(coordinatorReadOf(own), target, name, watch.texts),
+      lanes: Object.fromEntries(lanes.map((lane) => [lane, laneReading(lane)])),
+    }
+  } catch (error) {
+    return { coordinator: { reason: errorText(error) }, lanes: {} }
+  }
+}
+
+/** The saved state, or an empty one; a damaged file throws. */
+const readState = async (files: Files): Promise<WatchState> => {
+  const file = Bun.file(files.state)
+  return (await file.exists()) ? parseWatchState(await file.text()) : emptyWatchState()
+}
+
+const laneBranchesOf = (watch: Watch, lanes: readonly string[]): Record<string, string> =>
+  Object.fromEntries(
+    lanes.flatMap((lane) => {
+      const branch = branchOf(worktreeOf(watch.root, watch.settings, lane))
+      return branch ? [[lane, branch]] : []
+    }),
+  )
+
+const eventLinesOf = async (
+  watch: Watch,
+  events: readonly WatchEvent[],
+  github: GithubRead | null,
+): Promise<string[]> => {
+  const runs = answered(github)?.runs ?? []
+  const lines: string[] = []
+  for (const event of events) {
+    if (event.kind === WATCH_EVENT.feedback) {
+      lines.push(...feedbackEventLines(event))
+      continue
+    }
+    if (event.kind === WATCH_EVENT.source) {
+      lines.push(...sourceEventLines(event))
+      continue
+    }
+    const headSha = event.kind === WATCH_EVENT.deploy ? runs.find((run) => run.id === event.runId)?.headSha : undefined
+    const target =
+      event.kind === WATCH_EVENT.deploy && headSha && watch.deploy
+        ? await deployTargetOf(watch.root, watch.deploy, event.runId, headSha)
+        : null
+    lines.push(watchEventLine(event, target ? targetText(target) : null))
+  }
+  return lines
+}
+
+/** The progress of each watched lane, and the rows only the checkout's board file has, for the coordinator line. */
+const boardReadOf = async (
+  watch: Watch,
+  lanes: readonly string[],
+): Promise<{ progress: Record<string, LaneProgress>; checkoutRows: number }> => {
+  const text = await Bun.file(watch.sprintFile).text()
+  const sprintLanes = parseSprintLanes(text, watch.settings.planLanguage)
+  const watched = sprintLanes.filter((lane) => lanes.includes(lane.name))
+  const entries = await Promise.all(
+    watched.map(
+      async (lane) =>
+        [lane.name, await watchedLaneProgress(watch.root, watch.settings, watch.sprintFile, lane)] as const,
+    ),
+  )
+  const checkoutRows = boardCheckoutRows(watch.root, watch.settings, watch.sprintFile, text)
+  return { progress: Object.fromEntries(entries), checkoutRows }
+}
+
+/** What the status line of one lane is made of, from the loop's state. */
+const laneReportOf = (
+  lane: string,
+  watching: Watching,
+  state: WatchState,
+  pullRequests: readonly WatchedPullRequest[],
+  progress: LaneProgress | null,
+): LaneReport => {
+  const branch = watching.laneBranches[lane] ?? null
+  const pullRequest = branch ? latestPullRequestOf(pullRequests, branch) : null
+  const feedback = pullRequest ? (state.feedback.pullRequests[String(pullRequest.number)]?.count ?? 0) : 0
+  return {
+    lane,
+    status: watching.current[lane]?.status ?? NO_AGENT,
+    branch,
+    pullRequest: pullRequest ? { number: pullRequest.number, checks: pullRequest.checks, feedback } : null,
+    progress,
+    context: watching.laneReadings[lane]?.level ?? null,
+  }
+}
+
+/** `boardReadOf`, or when the board cannot be read, nothing of it and a note that says why. */
+const boardReadOrNote = async (
+  watch: Watch,
+  lanes: readonly string[],
+): Promise<{ progress: Record<string, LaneProgress>; checkoutRows: number; notes: string[] }> => {
+  try {
+    return { ...(await boardReadOf(watch, lanes)), notes: [] }
+  } catch (error) {
+    return {
+      progress: {},
+      checkoutRows: 0,
+      notes: [boardTexts(watch.settings.board.term).notReadable(errorText(error))],
+    }
+  }
+}
+
+/**
+ * The lane lines of the status block, the coordinator's line, the line of the own pull requests without a lane that
+ * follows it (`others`), and the lines after the block (notes, a gh outage).
+ */
+const statusLinesOf = async (
+  watch: Watch,
+  watching: Watching,
+  state: WatchState,
+): Promise<{ laneLines: string[]; coordinator: string; others: string[]; rest: string[] }> => {
+  const github = answered(watching.github)
+  const pullRequests = github?.pullRequests ?? []
+  const others = otherPullRequestsLine(pullRequests, github?.own ?? [], watch.texts)
+  const { progress, checkoutRows, notes } = await boardReadOrNote(watch, watching.lanes)
+  const laneLines = watching.lanes.map((lane) =>
+    laneReportLine(laneReportOf(lane, watching, state, pullRequests, progress[lane] ?? null), watch.texts),
+  )
+  const outage = state.ghDownSince === null ? [] : [ghUnavailableStatusLine(clock(watch, state.ghDownSince))]
+  const board = { term: watch.settings.board.term, checkoutRows }
+  const coordinator = coordinatorStatusLine(watching.coordinator.name, watching.coordinator.read, watch.texts, board)
+  return {
+    laneLines,
+    coordinator,
+    others: others === null ? [] : [others],
+    rest: [...notes, ...outage, ...failingSourceLines(watch, state.sources)],
+  }
+}
+
+const failingSourceLines = (watch: Watch, sources: SourceState): string[] =>
+  Object.entries(sources).flatMap(([name, { failingSince }]) =>
+    failingSince === null ? [] : [sourceFailingStatusLine(name, clock(watch, failingSince))],
+  )
+
+/** The section of each stopped lane (its header and message) and the report times it leaves behind. */
+const stoppedLaneSections = (
+  watch: Watch,
+  watching: Watching,
+  stopped: readonly string[],
+  next: WatchState,
+): { lines: string[]; reportMtimes: Record<string, number | null> } => {
+  const sections = stopped.map((lane) => {
+    const status = watching.current[lane]?.status
+    if (!status) return { lane, lines: [`=== ${lane}: ${terminalSafe(LANE_GONE)}`], mtime: undefined }
+    const message = stopMessageOf(watch, lane, status, next)
+    return { lane, lines: [`=== ${lane}: ${terminalSafe(status)}`, ...message.lines], mtime: message.reportedMtime }
+  })
+  const shown = sections.flatMap(({ lane, mtime }) => (mtime === undefined ? [] : [[lane, mtime] as const]))
+  return {
+    lines: sections.flatMap(({ lines }) => lines),
+    reportMtimes: { ...next.reportMtimes, ...Object.fromEntries(shown) },
+  }
+}
+
+/**
+ * Every line of one return, gathered before any is printed, so the output is never cut halfway by a slow lookup, and
+ * the state with what it showed: the report times of the stopped lanes and the status lines. A state without status
+ * lines prints the whole status block.
+ */
+const reportOf = async (
+  watch: Watch,
+  watching: Watching,
+  stopped: string[],
+  events: WatchEvent[],
+  next: WatchState,
+): Promise<{ lines: string[]; next: WatchState }> => {
+  const stops = stoppedLaneSections(watch, watching, stopped, next)
+  const eventLines = await eventLinesOf(watch, events, watching.github)
+  const dutyLines = [
+    ...blockedDutyLines(stopped, watching.current, watch.texts),
+    ...mergeDutyLines(events, watching.lanes, watch.texts),
+    ...laneFillDutyLines(events, watch.texts),
+  ]
+  const status = await statusLinesOf(watch, watching, next)
+  const block = statusBlock(status.laneLines, status.coordinator, next.statusLines, status.others)
+  return {
+    lines: [...stops.lines, ...eventLines, ...dutyLines, ...block, ...status.rest],
+    next: {
+      ...next,
+      reportMtimes: stops.reportMtimes,
+      statusLines: rememberedStatusLines(status.laneLines, status.others),
+    },
+  }
+}
+
+const recordGithub = (
+  watching: Watching,
+  github: GithubRead,
+  laneBranches: Record<string, string>,
+  now: number,
+): WatchEvent[] => {
+  watching.github = github
+  watching.laneBranches = laneBranches
+  watching.githubReadAt = now
+  return githubEventsOf(watching.state, watching.github, watching.laneBranches)
+}
+
+const recordCoordinator = (watching: Watching, coordinator: Coordinator): WatchEvent[] => {
+  watching.coordinator = coordinator
+  const event = coordinatorWatchEvent(watching.state, readingOf(coordinator.read))
+  return event ? [event] : []
+}
+
+const recordLaneFills = (watching: Watching, readings: LaneReadings): WatchEvent[] => {
+  watching.laneReadings = readings
+  return laneFillEvents(watching.state.laneLevels, readings)
+}
+
+/** The account `gh` runs as, read once and kept; null while `gh` cannot tell. */
+const ensureOwnLogin = async (watch: Watch, watching: Watching): Promise<string | null> => {
+  watching.ownLogin ??= await readOwnLogin(watch.root)
+  return watching.ownLogin
+}
+
+/**
+ * The feedback on the lanes' open pull requests that counts under the project's config, read over REST. Null when it
+ * is off, there is no target, the login is unknown or the read failed: the last read then stays, so the next one
+ * reaches back over the gap (`feedbackSince`) and no pull request loses its record.
+ */
+const readFeedback = async (
+  watch: Watch,
+  watching: Watching,
+  targets: FeedbackTarget[],
+  now: number,
+): Promise<FeedbackPoll | null> => {
+  if (watch.feedback === false || targets.length === 0) return null
+  const own = await ensureOwnLogin(watch, watching)
+  if (own === null) return null
+  const items = await readFeedbackItems(watch.root, targets, feedbackSince(watching.state.feedback, now))
+  if (!items.ok) return null
+  const filter = feedbackFilterOf(own, watch.feedback.ignore, watch.previews)
+  return { read: feedbackReadOf(now, targets, items.items, filter), items: items.items }
+}
+
+const recordFeedbackRead = (watching: Watching, read: FeedbackRead | null): WatchEvent[] => {
+  if (!read) return []
+  watching.feedbackRead = read
+  return feedbackEvents(watching.state.feedback, read)
+}
+
+/**
+ * The comments a preview author may have written: none without authors, else the feedback read's when it reached back
+ * as far as the last preview read (`feedbackReadCovers`), else a read of their own since then.
+ */
+const previewComments = async (
+  watch: Watch,
+  state: WatchState,
+  feedbackItems: FeedbackItem[] | null,
+  now: number,
+): Promise<FeedbackItemsRead> => {
+  if (!watch.previews || watch.previews.authors.length === 0) return { ok: true, items: [] }
+  if (feedbackItems && feedbackReadCovers(state.feedback.since, state.previews.since))
+    return { ok: true, items: feedbackItems }
+  return readCommentItems(watch.root, feedbackSince(state.previews, now))
+}
+
+/**
+ * The deploy previews of `targets`, the lanes' open pull requests as GitHub's list just named them, under the project's
+ * config: the configured authors' comments and, with `deployments`, the deployments of each head that has no preview
+ * reported yet. Null when previews are off, there is no target or a read failed: the state then stays as it was.
+ */
+const readPreviews = async (
+  watch: Watch,
+  watching: Watching,
+  targets: FeedbackTarget[],
+  feedbackItems: FeedbackItem[] | null,
+  now: number,
+): Promise<PreviewRead | null> => {
+  const previews = watch.previews
+  if (!previews || targets.length === 0) return null
+  const unreported = previews.deployments ? unreportedTargets(watching.state.previews, targets) : []
+  const [comments, deployments] = await Promise.all([
+    previewComments(watch, watching.state, feedbackItems, now),
+    readDeploymentCandidates(watch.root, unreported, watch.deploy?.environments ?? []),
+  ])
+  if (!comments.ok || !deployments.ok) return null
+  const candidates = [...commentCandidates(comments.items, previews), ...deployments.candidates]
+  return previewReadOf(now, targets, candidates)
+}
+
+const recordPreviewRead = (watching: Watching, read: PreviewRead | null): WatchEvent[] => {
+  if (!read) return []
+  watching.previewRead = read
+  return previewEvents(watching.state.previews, read)
+}
+
+/**
+ * Runs the sources whose interval has passed, all at once, each without a shell and within `SOURCE_LIMITS`; a failed
+ * run is a result, never a throw, so no source stops the watcher.
+ */
+const runDueSources = (watch: Watch, watching: Watching, now: number): Promise<SourceRun[]> => {
+  const due = watch.sources.filter((source) => isSourceDue(watching.sourceRanAt[source.name], source.every, now))
+  for (const source of due) watching.sourceRanAt[source.name] = now
+  return Promise.all(due.map((source) => runSource(source, watch.root, SOURCE_LIMITS)))
+}
+
+const recordSourceRuns = (watch: Watch, watching: Watching, runs: SourceRun[]): WatchEvent[] => {
+  watching.sourceRuns = runs
+  return sourceEvents(watching.state.sources, runs, watch.sources)
+}
+
+/** Starts a fetch of the base branch in the background when none runs; the loop does not wait for it. */
+const syncBase = (watch: Watch, watching: Watching) => {
+  if (watching.fetchingBase) return
+  watching.fetchingBase = true
+  void fetchBaseWhenMoved(watch.root, watch.settings.baseBranch).finally(() => {
+    watching.fetchingBase = false
+  })
+}
+
+/**
+ * Reads the coordinator's fill, GitHub, the feedback, the previews and the due sources, and stores them only once every read is complete: a SIGTERM
+ * while a read is pending saves the state as it was, so no event is taken as reported.
+ */
+const pollGithubAndCoordinator = async (watch: Watch, watching: Watching, now: number): Promise<WatchEvent[]> => {
+  syncBase(watch, watching)
+  const name = coordinatorNameFor(watch, watching.agents)
+  const fills = fillReadFor(watch, name, watching.agents, watching.lanes)
+  const laneBranches = laneBranchesOf(watch, watching.lanes)
+  const searched = Object.values({ ...watching.state.laneBranches, ...laneBranches })
+  const [github, sourceRuns] = await Promise.all([
+    readGithub(watch.root, watch.deploy, watch.settings.baseBranch, searched),
+    runDueSources(watch, watching, now),
+  ])
+  const pullRequests = answered(github)?.pullRequests ?? null
+  const branches = { ...watching.state.laneBranches, ...laneBranches }
+  const targets = feedbackTargets(pullRequests, branches, watching.state.feedback)
+  const feedback = await readFeedback(watch, watching, targets, now)
+  const previews = pullRequests ? await readPreviews(watch, watching, targets, feedback?.items ?? null, now) : null
+  return [
+    ...recordGithub(watching, github, laneBranches, now),
+    ...recordFeedbackRead(watching, feedback?.read ?? null),
+    ...recordPreviewRead(watching, previews),
+    ...recordSourceRuns(watch, watching, sourceRuns),
+    ...recordCoordinator(watching, { name, read: fills.coordinator }),
+    ...recordLaneFills(watching, fills.lanes),
+  ]
+}
+
+/** The sprint's lane names; the previous ones when the sprint cannot be read, so no lane drops out over it. */
+const sprintLaneNames = (watch: Watch, previous: string[]): string[] => {
+  try {
+    return parseSprintLanes(readFileSync(watch.sprintFile, 'utf8'), watch.settings.planLanguage).map(
+      (lane) => lane.name,
+    )
+  } catch {
+    return previous
+  }
+}
+
+const lanesFor = (watch: Watch, agents: readonly HerdrAgent[], sprintLanes: readonly string[]): string[] =>
+  watch.options.lanes ??
+  discoverLanes({
+    worktrees: worktreeNames(join(watch.root, watch.settings.worktreeDirectory)),
+    agentNames: agentNamesOf(agents),
+    sprintLanes,
+  })
+
+/** Brings back missing plans views beside the coordinator and the board's lanes when `trigger` calls for it; only inside herdr. */
+const keepViews = (watch: Watch, watching: Watching, trigger: EnsureTrigger) => {
+  if (!watch.herdr) return
+  watching.planViews = keepPlanViews(trigger, watching.planViews, {
+    ensure: () => ensurePlanPanes(watch.root, watch.settings, watch.sprintFile),
+    log: console.log,
+  })
+}
+
+/** Takes up lanes that were found or dropped since the last poll and returns the lanes it added; named lanes never change. */
+const followLaneSet = (watch: Watch, watching: Watching): string[] => {
+  if (watch.options.lanes !== null) return []
+  watching.sprintLanes = sprintLaneNames(watch, watching.sprintLanes)
+  const lanes = lanesFor(watch, watching.agents, watching.sprintLanes)
+  const change = laneSetChange(watching.lanes, lanes)
+  if (isUnchanged(change)) return []
+  watching.departed = [...watching.departed, ...departedLanes(change.removed, watching.baseline, watching.current)]
+  watching.lanes = lanes
+  watching.current = toSnapshot(watching.agents, lanes)
+  console.log(laneSetLines(change).join('\n'))
+  return change.added
+}
+
+/** Reads herdr's agents into the loop; false when herdr did not answer, said once per outage. */
+const readAgents = (watching: Watching): boolean => {
+  try {
+    watching.agents = listAgents()
+    watching.current = toSnapshot(watching.agents, watching.lanes)
+    watching.herdrDown = false
+    return true
+  } catch (error) {
+    if (!watching.herdrDown) console.log(`herdr poll failed, still watching: ${errorText(error)}`)
+    watching.herdrDown = true
+    return false
+  }
+}
+
+/** One herdr poll: the agents, the lane set, and once per poll the plans views of added lanes and of new agents. */
+const pollLanes = (watch: Watch, watching: Watching) => {
+  const previous = watching.current
+  if (!readAgents(watching)) return
+  const added = followLaneSet(watch, watching)
+  const withNewAgent = lanesWithNewAgent(previous, watching.current, watching.lanes)
+  keepViews(watch, watching, { kind: ENSURE_TRIGGER.poll, added, withNewAgent })
+  watching.baseline = baselineWithNewAgents(watching.baseline, watching.current)
+}
+
+/** Prints one report in a single write, so a stream delivers it as one message, then records its state; a single report ends with the notice that the call is over. */
+const report = async (
+  watch: Watch,
+  watching: Watching,
+  stopped: string[],
+  events: WatchEvent[],
+  next: WatchState,
+): Promise<WatchState> => {
+  watching.reporting = true
+  const { lines, next: shown } = await reportOf(watch, watching, stopped, events, next)
+  console.log(
+    (watch.options.stream ? lines : withSingleReportNotice(lines, monitorToolAvailable(process.env))).join('\n'),
+  )
+  writePrivate(watch.files.state, JSON.stringify(shown))
+  watching.reporting = false
+  return shown
+}
+
+/**
+ * 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.
+ * The state is also saved after every GitHub read, so a watcher killed without SIGTERM (a monitor
+ * that expires) loses no first sighting of a pull request.
+ */
+const pollOnce = async (watch: Watch, watching: Watching): Promise<boolean> => {
+  const { stream, heartbeatMinutes } = watch.options
+  const now = Date.now()
+  const due = now - watching.githubReadAt >= GITHUB_POLL_MS
+  const polledEvents = due ? await pollGithubAndCoordinator(watch, watching, now) : []
+  const stopped = [...firedLanes(watching.baseline, watching.current, watching.lanes), ...watching.departed]
+  watching.departed = []
+  const heartbeat = isHeartbeatDue(watching.quietSince, now, heartbeatMinutes * MINUTE_MS)
+  let next = recordedOf(watch, watching)
+  const reported = stopped.length > 0 || polledEvents.length > 0
+  if (reported) {
+    next = await report(watch, watching, stopped, polledEvents, next)
+    watching.baseline = { ...watching.current }
+  } else if (heartbeat && !stream) {
+    next = await report(watch, watching, [], [{ kind: WATCH_EVENT.heartbeat }], { ...next, statusLines: null })
+  } else {
+    if (heartbeat) console.log(streamHeartbeatLine(clock(watch, now), watching.lanes, watching.current))
+    if (due) writePrivate(watch.files.state, JSON.stringify(next))
+    watching.baseline = advanceBaseline(watching.baseline, watching.current)
+  }
+  watching.state = next
+  const spoke = reported || heartbeat
+  if (spoke) watching.quietSince = Date.now()
+  return stream || !spoke
+}
+
+/** The loop's state at the start: the found lanes armed from what they show now and from the saved state. */
+const initialWatching = (
+  watch: Watch,
+  start: { lanes: string[]; sprintLanes: string[]; state: WatchState; armed: LaneSnapshot; agents: HerdrAgent[] },
+): Watching => ({
+  lanes: start.lanes,
+  sprintLanes: start.sprintLanes,
+  departed: [],
+  quietSince: Date.now(),
+  state: start.state,
+  baseline: armBaseline(start.armed, start.state.seenSeqs),
+  current: start.armed,
+  agents: start.agents,
+  github: null,
+  laneBranches: {},
+  githubReadAt: 0,
+  coordinator: { name: watch.options.coordinator, read: null },
+  herdrDown: false,
+  reporting: false,
+  fetchingBase: false,
+  ownLogin: null,
+  feedbackRead: null,
+  previewRead: null,
+  sourceRuns: [],
+  sourceRanAt: {},
+  laneReadings: {},
+  planViews: { failureReported: false },
+})
+
+/** Saves the state a stop leaves behind: the one from before an unfinished report or an unread GitHub answer, else the latest. */
+const saveState = (watch: Watch, watching: Watching) => {
+  const unread = watching.reporting || watching.github === null
+  writePrivate(watch.files.state, JSON.stringify(unread ? watching.state : recordedOf(watch, watching)))
+}
+
+const watchLanes = async (watch: Watch) => {
+  const takeOver = await takeOverLock(watch.files.lock)
+  const state = await readState(watch.files)
+  const agents = listAgents()
+  const sprintLanes = watch.options.lanes ? [] : sprintLaneNames(watch, [])
+  const lanes = lanesFor(watch, agents, sprintLanes)
+  const armed = toSnapshot(agents, lanes)
+  console.log(armLine(lanes, armed, takeOver, relative(watch.root, watch.sprintFile)))
+  if (watch.boardNotice) console.log(watch.boardNotice)
+
+  const watching = initialWatching(watch, { lanes, sprintLanes, state, armed, agents })
+  keepViews(watch, watching, { kind: ENSURE_TRIGGER.start })
+  process.on('SIGTERM', () => {
+    saveState(watch, watching)
+    console.log(stopNoticeOf(watch.files.lock))
+    process.exit(0)
+  })
+
+  const kit = await startedKit()
+  const skillSnapshot = kit ? readOrchestrateSkill(kit.packageRoot) : null
+  const skillLine = () => skillLineFor(kit, skillSnapshot, dirname(watch.files.state))
+  while (await pollOnce(watch, watching)) {
+    await Bun.sleep(POLL_MS)
+    pollLanes(watch, watching)
+    if (endedByKitUpdate(kit, { saveState: () => saveState(watch, watching), log: console.log, skillLine })) return
+  }
+}
+
+const filesOf = (root: string): Files => {
+  const directory = ensureWatcherDirectory(root)
+  return { state: join(directory, WATCHER_FILES.state), lock: join(directory, WATCHER_FILES.lock) }
+}
+
+/** The watch as the command line and the config set it up; throws when the config or the sprint is missing. */
+const watchOf = (options: WatchOptions): Watch => {
+  const root = mainCheckout(process.cwd())
+  const { config, notes } = readResolvedConfig([worktreeRoot(process.cwd()), root])
+  for (const note of notes) console.log(note)
+  const settings = plansSettingsOf(config)
+  const picked = boardFor(options.boardPath, [root, worktreeRoot(process.cwd())], settings, () =>
+    foundLanesOf(root, settings, () => agentNamesOf(listAgents())),
+  )
+  return {
+    root,
+    sprintFile: picked.file,
+    boardNotice: picked.notice,
+    options,
+    files: filesOf(root),
+    settings,
+    deploy: config.watch.deploy,
+    feedback: config.watch.feedback,
+    previews: config.watch.previews,
+    sources: config.watch.sources,
+    texts: WATCH_TEXTS[settings.responseLanguage],
+    herdr: insideHerdr(settings.adapter, process.env),
+  }
+}
+
+export const run = async (args: string[]): Promise<number> => {
+  let options: WatchOptions
+  try {
+    options = parseWatchOptions(args)
+  } catch (error) {
+    // The usage text is the program's own and spans lines; errorText would strip its line breaks.
+    console.error(error instanceof Error ? error.message : String(error))
+    return USAGE_EXIT
+  }
+  if (options.sourceDryRun !== null) {
+    try {
+      return await sourceDryRun(options.sourceDryRun)
+    } catch (error) {
+      console.error(errorText(error))
+      return 1
+    }
+  }
+  let watch: Watch
+  try {
+    watch = watchOf(options)
+  } catch (error) {
+    console.error(errorText(error))
+    return 1
+  }
+  try {
+    await watchLanes(watch)
+    return 0
+  } catch (error) {
+    console.log(`watcher stopped: ${errorText(error)}`)
+    return 1
+  } finally {
+    releaseLock(watch.files.lock)
+  }
+}