jackherd 0.0.1 → 1.0.1

package/src/watch/kit-update.ts

@@ -0,0 +1,18 @@
+import { kitUpdatedLine, pendingKitUpdate } from '../version/installed-version'
+import type { StartedKit } from '../version/started-kit'
+
+type Effects = { saveState: () => void; log: (line: string) => void; skillLine: () => string }
+
+/**
+ * Ends the watcher when the kit on disk is another version than the one it started with: saves the state
+ * as any stop does, then prints the line that wakes the coordinator and the line about the orchestrate
+ * skill. True when the watcher should end.
+ */
+export const endedByKitUpdate = (kit: StartedKit | null, { saveState, log, skillLine }: Effects): boolean => {
+  const update = pendingKitUpdate(kit)
+  if (!update) return false
+  saveState()
+  log(kitUpdatedLine(update))
+  log(skillLine())
+  return true
+}

package/src/watch/lane-fill.ts

@@ -0,0 +1,36 @@
+import type { ContextLevel, ContextReading } from '../context'
+import { isContextLevel, levelStep } from './coordinator-fill'
+import { isRecord } from './json-guards'
+
+export const LANE_FILL_EVENT = 'lane'
+
+/** Lane → the context level last read for its agent; a lane without an entry counts as `ok`. */
+export type LaneLevels = Record<string, ContextLevel>
+
+/** Lane → its agent's fill as one read found it, null when there was no value (no agent, no log, no answer). */
+export type LaneReadings = Record<string, ContextReading | null>
+
+export type LaneFillEvent = { kind: typeof LANE_FILL_EVENT; lane: string; level: ContextLevel; share: number }
+
+/**
+ * One event per lane whose level rose above the stored one, as for the coordinator (`levelStep`). A lane seen
+ * for the first time counts as `ok`: the fill is a condition, so one already above a threshold reports once.
+ */
+export const laneFillEvents = (previous: LaneLevels, readings: LaneReadings): LaneFillEvent[] =>
+  Object.entries(readings).flatMap(([lane, reading]) =>
+    reading && levelStep(previous[lane], reading.level).fire
+      ? [{ kind: LANE_FILL_EVENT, lane, level: reading.level, share: reading.share }]
+      : [],
+  )
+
+/** The levels after a read: each watched lane at its current level, its stored one without a value; others dropped. */
+export const recordLaneLevels = (previous: LaneLevels, readings: LaneReadings, lanes: readonly string[]): LaneLevels =>
+  Object.fromEntries(
+    lanes.flatMap((lane) => {
+      const level = levelStep(previous[lane], readings[lane]?.level ?? null).level
+      return level === null ? [] : [[lane, level]]
+    }),
+  )
+
+export const isLaneLevels = (value: unknown): value is LaneLevels =>
+  isRecord(value) && Object.values(value).every(isContextLevel)

package/src/watch/lane-message.ts

@@ -0,0 +1,99 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { AGENT_STATUS } from './lane-watch'
+
+/** A lane's report file as the watcher found it: its path, when it was last written, its text. */
+export type LaneReportFile = { path: string; mtimeMs: number; text: string }
+
+/**
+ * What the watcher knows when a lane stops: `reportedMtime` is the change time of the report file it showed last
+ * for this lane, null when it never showed one.
+ */
+export type LaneStop = { status: string; screen: string; report: LaneReportFile | null; reportedMtime: number | null }
+
+/** The lines printed under `=== <lane>: <status>` and the report change time to remember for the lane. */
+export type LaneMessage = { lines: string[]; reportedMtime: number | null }
+
+const SCREEN_LINES = 30
+const SCREEN_LINE_LENGTH = 220
+/** How far up from the bottom the input box's rule may sit; a rule higher up belongs to the lane's text. */
+const INPUT_BOX_DEPTH = 15
+/** A line of box-drawing rule only, as Claude Code draws around its input box. */
+const INPUT_BOX_RULE = /^[─▔]{20,}$/
+const REPORT_LINES = 15
+const REPORT_CHARACTERS = 1500
+
+/** The last `SCREEN_LINES` lines, each made safe and cut. */
+const lastScreenLines = (lines: readonly string[]): string =>
+  lines
+    .slice(-SCREEN_LINES)
+    .map((line) => terminalSafe(line).slice(0, SCREEN_LINE_LENGTH))
+    .join('\n')
+
+/**
+ * The screen without the input box and what follows it (the status bar, the mode line, the agent list): everything
+ * from the first rule line in the bottom `INPUT_BOX_DEPTH` lines on. Without such a line the screen stays whole. The
+ * last `SCREEN_LINES` lines above are kept, each made safe and cut.
+ */
+export const cutScreen = (screen: string): string => {
+  const lines = screen.split('\n')
+  const ruleIndex = lines.findIndex(
+    (line, index) => index >= lines.length - INPUT_BOX_DEPTH && INPUT_BOX_RULE.test(line.trim()),
+  )
+  return lastScreenLines(ruleIndex === -1 ? lines : lines.slice(0, ruleIndex))
+}
+
+/** The head of a report file: its first lines, made safe, within a character budget. */
+export const reportExcerpt = (text: string): string =>
+  text.split('\n').slice(0, REPORT_LINES).map(terminalSafe).join('\n').slice(0, REPORT_CHARACTERS)
+
+/** What `reportExcerpt` leaves out, in lines or else characters; null when the excerpt is the whole report. */
+const reportRest = (text: string): string | null => {
+  const lines = text.split('\n')
+  if (lines.length > REPORT_LINES) return `+${lines.length - REPORT_LINES} lines`
+  const shown = lines.map(terminalSafe).join('\n').length
+  return shown > REPORT_CHARACTERS ? `+${shown - REPORT_CHARACTERS} characters` : null
+}
+
+const isNewReport = (report: LaneReportFile | null, reportedMtime: number | null): report is LaneReportFile =>
+  report !== null && (reportedMtime === null || report.mtimeMs > reportedMtime)
+
+/**
+ * What a stopped lane shows the coordinator: a blocked lane its whole screen, since the dialog is the news; else a
+ * report the lane wrote since the last one shown (its path and head), else the screen without the input box.
+ */
+export const laneMessage = ({ status, screen, report, reportedMtime }: LaneStop): LaneMessage => {
+  if (status === AGENT_STATUS.blocked) return { lines: [lastScreenLines(screen.split('\n'))], reportedMtime }
+  if (isNewReport(report, reportedMtime)) {
+    const path = terminalSafe(report.path)
+    const rest = reportRest(report.text)
+    const more = rest === null ? [] : [`… ${rest}, read ${path}`]
+    return { lines: [`report ${path}`, reportExcerpt(report.text), ...more], reportedMtime: report.mtimeMs }
+  }
+  return { lines: [cutScreen(screen)], reportedMtime }
+}
+
+/** The lines a report remembers for the next comparison: the lane lines, then the lines after the coordinator's. */
+export const rememberedStatusLines = (laneLines: readonly string[], otherLines: readonly string[]): string[] => [
+  ...laneLines,
+  ...otherLines,
+]
+
+/**
+ * The status block of a report: whole when a lane line or a line after the coordinator's (`otherLines`) differs from
+ * `previous` (`rememberedStatusLines` of the last report) or nothing was reported before (null, which a heartbeat
+ * report passes to show it whole), else one line that says so, with the coordinator's line, which changes with every
+ * read.
+ */
+export const statusBlock = (
+  laneLines: readonly string[],
+  coordinatorLine: string,
+  previous: readonly string[] | null,
+  otherLines: readonly string[],
+): string[] => {
+  const compared = rememberedStatusLines(laneLines, otherLines)
+  const unchanged =
+    previous !== null && previous.length === compared.length && previous.every((line, i) => line === compared[i])
+  return unchanged
+    ? [`status: unchanged · ${coordinatorLine}`]
+    : ['status:', ...laneLines, coordinatorLine, ...otherLines]
+}

package/src/watch/lane-progress.ts

@@ -0,0 +1,44 @@
+import { dirname } from 'node:path'
+import type { LaneProgress, SprintLane } from '../plan-format'
+import { boardRowsOf } from '../plans/board-rows'
+import { baseReaderOf, gitStatusOf } from '../plans/git'
+import { laneWorkOf, readPlans, textAtBase } from '../plans/lane-plans'
+import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from '../plans/settings'
+import { workedLaneProgress } from '../plans/worked-phases'
+
+/**
+ * The progress the watcher reports for a lane, from the same reading as the plans view: the base ref's plans, the
+ * phases the lane works on from its worktree (also without a board row), so both name the same open phase.
+ */
+export const watchedLaneProgress = async (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  lane: SprintLane,
+): Promise<LaneProgress> => {
+  const baseRef = baseRefOf(settings)
+  const worktree = worktreeOf(root, settings, lane.name)
+  const sources = {
+    root,
+    settings,
+    base: baseReaderOf(root, baseRef),
+    sprintDirectory: dirname(boardRepoPathOf(root, settings, boardFile)),
+  }
+  const work = laneWorkOf(worktree, await gitStatusOf(worktree, baseRef))
+  const { plans } = await readPlans(lane, sources, work, [])
+  return workedLaneProgress(lane, plans)
+}
+
+/**
+ * The rows the checkout's board file (`checkoutText`) has beyond the board at the base ref, counted as the plans view
+ * adds them; 0 when the base ref lacks the board, which is then read from the checkout as a whole.
+ */
+export const boardCheckoutRows = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  checkoutText: string,
+): number => {
+  const atBase = textAtBase(baseReaderOf(root, baseRefOf(settings)), boardRepoPathOf(root, settings, boardFile))
+  return atBase === null ? 0 : boardRowsOf(atBase, checkoutText, settings.planLanguage).rowsFromCheckout
+}

package/src/watch/lane-report-file.ts

@@ -0,0 +1,53 @@
+import { closeSync, lstatSync, openSync, readSync } from 'node:fs'
+import { join } from 'node:path'
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
+import type { LaneReportFile } from './lane-message'
+
+/** A lane name that stays a single file name: no separator, no `..`. */
+const SAFE_LANE_NAME = /^(?!\.\.?$)[A-Za-z0-9._-]+$/
+/** The head of a report the watcher reads; it prints far less, and a huge file must not stall it. */
+const READ_LIMIT_BYTES = 8192
+
+/**
+ * Where a lane writes its report, inside its worktree: `.claude/handover/<lane>-report.md`. Null for a lane name
+ * that could leave that directory: names come from board rows and herdr agents.
+ */
+export const laneReportPath = (worktree: string, lane: string): string | null =>
+  SAFE_LANE_NAME.test(lane) ? join(worktree, claudePath(HANDOVER_DIRECTORY), `${lane}-report.md`) : null
+
+/** The change time of a regular file at `path`, not followed through a symlink; null for anything else. */
+const regularFileMtime = (path: string): number | null => {
+  try {
+    const stats = lstatSync(path)
+    return stats.isFile() ? stats.mtimeMs : null
+  } catch {
+    return null
+  }
+}
+
+const readHead = (path: string): string => {
+  const descriptor = openSync(path, 'r')
+  try {
+    const buffer = Buffer.alloc(READ_LIMIT_BYTES)
+    return buffer.subarray(0, readSync(descriptor, buffer, 0, READ_LIMIT_BYTES, 0)).toString('utf8')
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
+/** The change time of the report file; null when there is none or it is no regular file. */
+export const reportMtime = (path: string | null): number | null => (path === null ? null : regularFileMtime(path))
+
+/**
+ * The report file with its change time and the first `READ_LIMIT_BYTES` of its text; null when it is missing,
+ * unreadable, or no regular file (a symlink, a directory, a FIFO).
+ */
+export const readLaneReport = (path: string | null): LaneReportFile | null => {
+  const mtimeMs = reportMtime(path)
+  if (path === null || mtimeMs === null) return null
+  try {
+    return { path, mtimeMs, text: readHead(path) }
+  } catch {
+    return null
+  }
+}

package/src/watch/lane-report.ts

@@ -0,0 +1,270 @@
+import { CONTEXT_LEVEL, type ContextLevel, contextLabel } from '../context'
+import { currentPhase, isTickedUnmerged, type LaneProgress } from '../plan-format'
+import { terminalSafe } from '../plan-format/terminal-text'
+import type { ChecksState } from '../plans/pull-requests'
+import type { CoordinatorRead } from './coordinator-fill'
+import { type FeedbackEvent, firstLine } from './feedback'
+import type { LaneFillEvent } from './lane-fill'
+import { AGENT_STATUS, type LaneSnapshot, NO_AGENT } from './lane-watch'
+import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
+import { SOURCE_FIELD } from './source-fields'
+import { type FieldChange, lineText, type SourceEvent } from './sources'
+import type { WatchTexts } from './texts'
+import {
+  type DeployEvent,
+  isPullRequestEvent,
+  type PullRequestEvent,
+  WATCH_EVENT,
+  type WatchEvent,
+} from './watch-events'
+import type { TakeOver } from './watcher-lock'
+
+export type LaneReport = {
+  lane: string
+  status: string
+  branch: string | null
+  /** `feedback` counts the feedback reported since the pull request's last push. */
+  pullRequest: { number: number; checks: ChecksState; feedback: number } | null
+  progress: LaneProgress | null
+  /** The context level last read for the lane's agent; null without a value. */
+  context: ContextLevel | null
+}
+
+/** The board as the coordinator line reminds of it: its term and the rows only the checkout's board file has. */
+export type BoardReminder = { term: string; checkoutRows: number }
+
+const UNKNOWN = 'unknown'
+const REPORT_TEXT_LENGTH = 160
+const FIELD_VALUE_LENGTH = 60
+const EMPTY_VALUE = '(empty)'
+const CHANGE_ARROW = '→'
+const VALUE_ARROW = '->'
+const FEEDBACK_ENTRY_LIMIT = 10
+const REPORT_INDENT = '  '
+const SHORT_SHA_LENGTH = 7
+const NO_REMINDER: BoardReminder = { term: '', checkoutRows: 0 }
+const OTHER_PULL_REQUEST_LIMIT = 5
+
+const pullRequestSegment = (pullRequest: LaneReport['pullRequest'], texts: WatchTexts): string => {
+  if (!pullRequest) return texts.noPullRequest
+  const feedback = pullRequest.feedback ? ` · ${pullRequest.feedback} ${WATCH_EVENT.feedback}` : ''
+  return `PR #${pullRequest.number} ${pullRequest.checks}${feedback}`
+}
+
+const phaseSegment = (progress: LaneProgress | null, texts: WatchTexts): string => {
+  if (!progress) return texts.noPlan
+  if (!progress.current) return progress.total > 0 ? texts.planFinished : texts.noPlan
+  const phase = currentPhase(progress)
+  if (!phase) return texts.noPlan
+  const title = phase.title ? ` ${terminalSafe(phase.title)}` : ''
+  if (isTickedUnmerged(phase)) return `${texts.phase} ${terminalSafe(phase.id)}${title} ${texts.tickedUnmerged}`
+  const startsAfter = progress.steps[progress.current.stepIndex]?.step.startsAfter
+  const after = startsAfter ? ` (${texts.startsAfter}: ${terminalSafe(startsAfter)})` : ''
+  return `${texts.openPhase} ${terminalSafe(phase.id)}${title}${after}`
+}
+
+/** `context warn` or `context alert`; nothing at `ok` or without a value, so the line stays the same while the share moves. */
+const contextSegment = (level: ContextLevel | null): string[] =>
+  level === null || level === CONTEXT_LEVEL.ok ? [] : [`context ${level}`]
+
+/**
+ * One line per lane, in the words of `texts`: `<lane> <status> [· context warn|alert] · <branch>|kein Branch ·
+ * PR #<n> <checks>|kein PR · offene Phase …|Phase … abgehakt, nicht gemergt|Plan fertig|kein Plan` in German.
+ */
+export const laneReportLine = (report: LaneReport, texts: WatchTexts): string =>
+  [
+    `${terminalSafe(report.lane)} ${terminalSafe(report.status)}`,
+    ...contextSegment(report.context),
+    report.branch ? terminalSafe(report.branch) : texts.noBranch,
+    pullRequestSegment(report.pullRequest, texts),
+    phaseSegment(report.progress, texts),
+  ].join(' · ')
+
+/** The lane, or `branch <name>` for an own pull request without a lane, its name cut like other third-party text. */
+const pullRequestOwner = (event: PullRequestEvent): string =>
+  event.lane === null ? `branch ${terminalSafe(event.branch).slice(0, REPORT_TEXT_LENGTH)}` : terminalSafe(event.lane)
+
+/** The lane, `#<number>` for an own pull request without a lane, or `manual`. */
+const deployOwner = (event: DeployEvent): string => {
+  if (event.lane !== null) return terminalSafe(event.lane)
+  return event.pullRequest === undefined ? 'manual' : `#${event.pullRequest}`
+}
+
+/**
+ * `other PRs: #<n> passed · #<m> none`, in the words of `texts`: the open pull requests among `own` (the user's own without a
+ * lane), newest first, at most `OTHER_PULL_REQUEST_LIMIT` and `+<k>` for the rest; null when there is none.
+ */
+export const otherPullRequestsLine = (
+  pullRequests: readonly WatchedPullRequest[],
+  own: readonly number[],
+  texts: WatchTexts,
+): string | null => {
+  const open = pullRequests
+    .filter(({ number, state }) => state === PULL_REQUEST_STATE.open && own.includes(number))
+    .sort((left, right) => right.number - left.number)
+  if (open.length === 0) return null
+  const shown = open.slice(0, OTHER_PULL_REQUEST_LIMIT).map(({ number, checks }) => `#${number} ${checks}`)
+  const more = open.length - OTHER_PULL_REQUEST_LIMIT
+  return `${texts.otherPullRequests}: ${[...shown, ...(more > 0 ? [`+${more}`] : [])].join(' · ')}`
+}
+
+/**
+ * The header line of one event: `=== merged #<number> (lane)`, `=== checks failed #<number> (lane|branch <name>)`,
+ * `=== 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>`.
+ * `target` is the deploy environment read from the run, null when none was found.
+ */
+export const watchEventLine = (event: WatchEvent, target: string | null): string => {
+  if (event.kind === WATCH_EVENT.deploy) {
+    const by = deployOwner(event)
+    const outcome = terminalSafe(event.conclusion ?? UNKNOWN)
+    const where = terminalSafe(target ?? UNKNOWN)
+    return `=== deploy ${outcome} run ${event.runId} (${terminalSafe(event.trigger)}, ${by}) target ${where}`
+  }
+  if (event.kind === WATCH_EVENT.ghUnavailable) return `=== ${event.kind}: ${terminalSafe(event.reason)}`
+  if (event.kind === WATCH_EVENT.preview)
+    return `=== ${event.kind} #${event.number} (${terminalSafe(event.lane)}) ${terminalSafe(event.url)} · ${terminalSafe(event.headCommit.slice(0, SHORT_SHA_LENGTH))}`
+  if (event.kind === WATCH_EVENT.laneFill)
+    return `=== ${event.kind} ${terminalSafe(event.lane)} ${event.level} ${contextLabel(event.share)}`
+  if (event.kind === WATCH_EVENT.coordinator) return `=== ${event.kind} ${event.level} ${contextLabel(event.share)}`
+  if (isPullRequestEvent(event)) return `=== ${event.kind} #${event.number} (${pullRequestOwner(event)})`
+  if ('number' in event) return `=== ${event.kind} #${event.number} (${terminalSafe(event.lane)})`
+  return `=== ${event.kind}`
+}
+
+/**
+ * The lines of a feedback event: `=== feedback #<number> (lane) <author> <label> · <k> new`, then one line per entry,
+ * `<path>:<line> <first line>` or `<first line>`, cut to a length and to `FEEDBACK_ENTRY_LIMIT` entries.
+ */
+export const feedbackEventLines = (event: FeedbackEvent): string[] => {
+  const header = `=== ${event.kind} #${event.number} (${terminalSafe(event.lane)}) ${terminalSafe(event.author)} ${terminalSafe(event.label)} · ${event.entries.length} new`
+  const entries = event.entries.slice(0, FEEDBACK_ENTRY_LIMIT).map(({ place, text }) => {
+    const line = terminalSafe(place === null ? text : `${place} ${text}`).slice(0, REPORT_TEXT_LENGTH)
+    return `${REPORT_INDENT}${line}`
+  })
+  const more = event.entries.length - FEEDBACK_ENTRY_LIMIT
+  return [header, ...entries, ...(more > 0 ? [`${REPORT_INDENT}… ${more} more`] : [])]
+}
+
+/**
+ * A field value on one line (`lineText`), cut to 60, `(empty)` when empty; an arrow inside it becomes `->`, so a value
+ * cannot pass for a further change.
+ */
+const fieldValueText = (value: string): string => {
+  const text = lineText(value).replaceAll(CHANGE_ARROW, VALUE_ARROW).slice(0, FIELD_VALUE_LENGTH)
+  return text === '' ? EMPTY_VALUE : text
+}
+
+/** `status In progress → Ready, assignee (empty) → Kim`. */
+const fieldChangesText = (changes: readonly FieldChange[]): string =>
+  changes
+    .map(
+      ({ field, from, to }) => `${terminalSafe(field)} ${fieldValueText(from)} ${CHANGE_ARROW} ${fieldValueText(to)}`,
+    )
+    .join(', ')
+
+/** A field change shows the body only when the body is one of the changed fields. */
+const showsBody = (changes: readonly FieldChange[] | undefined): boolean =>
+  changes === undefined || changes.some(({ field }) => field === SOURCE_FIELD.body)
+
+/**
+ * The lines of a source event: `=== source <name> [(lane)] <id> <title> · new|updated`, with `reportOn`
+ * `· updated: <field> <old> → <new>, …` (no body line unless the body changed), then the first line of the body
+ * with text that is no Markdown heading (`firstLine`), cut to a length, and the checked URL, each only when there is one; a failure is
+ * `=== source <name> [(lane)] failed: <reason>`, the entries past the report limit `=== source <name> [(lane)] +<n> more`. Everything but the reason comes from the external service.
+ */
+export const sourceEventLines = (event: SourceEvent): string[] => {
+  const lane = event.lane === null ? '' : ` (${terminalSafe(event.lane)})`
+  const head = `=== ${event.kind} ${terminalSafe(event.name)}${lane}`
+  if ('failure' in event) return [`${head} failed: ${event.failure}`]
+  if ('more' in event) return [`${head} +${event.more} more`]
+  const id = terminalSafe(event.id).slice(0, REPORT_TEXT_LENGTH)
+  const title = terminalSafe(event.title).slice(0, REPORT_TEXT_LENGTH)
+  const body = showsBody(event.changes) ? terminalSafe(firstLine(event.body)).slice(0, REPORT_TEXT_LENGTH) : ''
+  const changes = event.changes ? `: ${fieldChangesText(event.changes)}` : ''
+  return [
+    `${head} ${id}${title ? ` ${title}` : ''} · ${event.change}${changes}`,
+    ...(body ? [`${REPORT_INDENT}${body}`] : []),
+    ...(event.url ? [`${REPORT_INDENT}${terminalSafe(event.url)}`] : []),
+  ]
+}
+
+/** The status line while a source fails; `since` is the start of the streak as a clock time. */
+export const sourceFailingStatusLine = (name: string, since: string): string =>
+  `${WATCH_EVENT.source} ${terminalSafe(name)} failing since ${since}`
+
+const coordinatorValue = (name: string | null, read: CoordinatorRead | null, texts: WatchTexts): string => {
+  if (name === null) return `coordinator ${texts.noName}`
+  if (read === null) return `coordinator ${terminalSafe(name)} ${texts.noValue}`
+  const value =
+    'reading' in read
+      ? `${contextLabel(read.reading.share)} ${read.reading.level}${read.note ? ` (${terminalSafe(read.note)})` : ''}`
+      : `${texts.noValue} (${terminalSafe(read.reason)})`
+  return `coordinator ${terminalSafe(name)} ${value}`
+}
+
+/**
+ * `coordinator <name> 62 % warn`, `coordinator <name> kein Wert (<reason>)` or `coordinator kein Name` in German;
+ * while the board has rows only in the checkout, `· board: 2 rows only in the checkout` follows.
+ */
+export const coordinatorStatusLine = (
+  name: string | null,
+  read: CoordinatorRead | null,
+  texts: WatchTexts,
+  board: BoardReminder = NO_REMINDER,
+): string => {
+  const line = coordinatorValue(name, read, texts)
+  return board.checkoutRows > 0 ? `${line} · ${texts.checkoutRows(terminalSafe(board.term), board.checkoutRows)}` : line
+}
+
+/** The status line while `gh` is unavailable; `since` is the start of the outage as a clock time. */
+export const ghUnavailableStatusLine = (since: string): string => `${WATCH_EVENT.ghUnavailable} since ${since}`
+
+type MergeEvent = PullRequestEvent & { kind: typeof WATCH_EVENT.merged }
+
+const isMerge = (event: WatchEvent): event is MergeEvent => event.kind === WATCH_EVENT.merged
+
+const mergeDuty = (merged: MergeEvent, lane: string, texts: WatchTexts): string => {
+  const duty = lane === merged.lane ? texts.mergedLaneDuty : texts.otherLaneDuty
+  return `${texts.afterMerge(merged.number)}: ${terminalSafe(lane)} ${duty}`
+}
+
+/**
+ * What a merge asks of every watched lane (`orchestrate` § 6), one line per lane and merge: the
+ * merged lane goes on or closes, every other lane rebases and goes on or waits with a reason. The
+ * watcher only names the duty; the coordinator decides and prompts the lanes.
+ */
+export const mergeDutyLines = (events: readonly WatchEvent[], lanes: readonly string[], texts: WatchTexts): string[] =>
+  events.filter(isMerge).flatMap((merged) => lanes.map((lane) => mergeDuty(merged, lane, texts)))
+
+const isLaneAlert = (event: WatchEvent): event is LaneFillEvent =>
+  event.kind === WATCH_EVENT.laneFill && event.level === CONTEXT_LEVEL.alert
+
+/** What a lane whose context reached `alert` asks of the coordinator (`orchestrate` § 8): one line per such lane. */
+export const laneFillDutyLines = (events: readonly WatchEvent[], texts: WatchTexts): string[] =>
+  events
+    .filter(isLaneAlert)
+    .map(({ lane }) => `${terminalSafe(lane)} context ${CONTEXT_LEVEL.alert}: ${texts.laneAlertDuty}`)
+
+/**
+ * What a blocked lane asks of the coordinator (`orchestrate` § 4), one line per stopped lane that
+ * sits in `blocked`: vet the question, answer it in the lane or ask the user, never hand the pane
+ * over. Lanes that stopped as `done` or `idle`, or left the listing, get none.
+ */
+export const blockedDutyLines = (stopped: readonly string[], current: LaneSnapshot, texts: WatchTexts): string[] =>
+  stopped
+    .filter((lane) => current[lane]?.status === AGENT_STATUS.blocked)
+    .map((lane) => `${terminalSafe(lane)} ${AGENT_STATUS.blocked}: ${texts.blockedDuty}`)
+
+const takeOverNote = ({ replaced, stillRunning }: TakeOver): string => {
+  if (stillRunning !== null) return ` (watcher ${stillRunning} did not stop)`
+  return replaced === null ? '' : ` (replaced watcher ${replaced})`
+}
+
+/** The first line of a run: `armed: <lane>=<state> … board <path>`, with a note when an older watcher was replaced or did not stop. */
+export const armLine = (lanes: readonly string[], armed: LaneSnapshot, takeOver: TakeOver, board: string): string => {
+  const states =
+    lanes.map((lane) => `${terminalSafe(lane)}=${terminalSafe(armed[lane]?.status ?? NO_AGENT)}`).join(' ') ||
+    'no lanes'
+  return `armed: ${states}${takeOverNote(takeOver)} board ${terminalSafe(board)}`
+}

package/src/watch/lane-search.ts

@@ -0,0 +1,41 @@
+import type { WatchedPullRequest } from './pull-requests'
+
+/**
+ * Branches in one search. GitHub documents a limit of 256 characters for a search and counts qualifiers
+ * differently from what was measured (16 branches, 506 characters, accepted). The cut is by count, not by length:
+ * ten names of 55 characters make a longer text than was ever measured.
+ */
+export const BRANCHES_PER_SEARCH = 10
+
+/** Characters of a branch name that `head:` takes literally; anything else is left out of the search. */
+const SEARCHABLE_BRANCH = /^[A-Za-z0-9._/-]+$/
+
+/**
+ * The branches worth a search: no base branch (every merged lane ends there), no duplicates, no name the search
+ * syntax could misread (quotes, colons, brackets; `head:` with such a name was never seen to match). Such a lane
+ * keeps its merge detection from the light list and only goes without a check status.
+ */
+export const searchableBranches = (branches: readonly string[], baseBranch: string): string[] =>
+  [...new Set(branches)].filter((branch) => branch !== baseBranch && SEARCHABLE_BRANCH.test(branch)).sort()
+
+/** The branches cut into batches of at most `BRANCHES_PER_SEARCH`. */
+export const branchBatches = (branches: readonly string[]): string[][] =>
+  Array.from({ length: Math.ceil(branches.length / BRANCHES_PER_SEARCH) }, (_, index) =>
+    branches.slice(index * BRANCHES_PER_SEARCH, (index + 1) * BRANCHES_PER_SEARCH),
+  )
+
+/** `head:a head:b`: GitHub combines several `head:` qualifiers with or. */
+export const searchTextOf = (branches: readonly string[]): string =>
+  branches.map((branch) => `head:${branch}`).join(' ')
+
+/**
+ * The pull requests whose branch is one of `branches`, exactly. `head:` matches a prefix and ignores case, so
+ * `head:fix/order-opening` also finds `fix/order-opening-hours`; a pull request of a foreign branch must not pass.
+ */
+export const onBranches = (
+  pullRequests: readonly WatchedPullRequest[],
+  branches: readonly string[],
+): WatchedPullRequest[] => {
+  const wanted = new Set(branches)
+  return pullRequests.filter((pullRequest) => wanted.has(pullRequest.branch))
+}

package/src/watch/lane-sources.ts

@@ -0,0 +1,46 @@
+import { existsSync } from 'node:fs'
+import { fetchBase } from '../plans/fetch'
+import { BASE_REMOTE } from '../plans/settings'
+import { baseFetchNeeded, remoteTipOf } from './base-tip'
+
+const GIT_ASYNC_TIMEOUT_MS = 30_000
+
+/** Runs git without blocking, killed after the timeout; its stdout, or null when it failed. Never rejects. */
+const gitAsync = async (cwd: string, args: string[]): Promise<string | null> => {
+  try {
+    const child = Bun.spawn(['git', '-C', cwd, ...args], {
+      stdout: 'pipe',
+      stderr: 'ignore',
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    })
+    const timer = setTimeout(() => child.kill(), GIT_ASYNC_TIMEOUT_MS)
+    const [stdout, exitCode] = await Promise.all([new Response(child.stdout).text(), child.exited])
+    clearTimeout(timer)
+    return exitCode === 0 ? stdout : null
+  } catch {
+    return null
+  }
+}
+
+const git = (cwd: string, args: string[]): string | null => {
+  const result = Bun.spawnSync(['git', '-C', cwd, ...args], { stdout: 'pipe', stderr: 'pipe' })
+  return result.exitCode === 0 ? result.stdout.toString().trim() : null
+}
+
+/** The branch checked out in a worktree, or null for a missing worktree or a detached head. */
+export const branchOf = (worktree: string): string | null =>
+  existsSync(worktree) ? git(worktree, ['branch', '--show-current']) || null : null
+
+/**
+ * Fetches the base branch when the remote moved past `origin/<branch>`, so every reader of that ref
+ * (the plans view watches `FETCH_HEAD`) sees a merge as soon as the watcher does. Asks the remote
+ * first, so an unchanged base costs no fetch; a failure leaves the ref as it is.
+ */
+export const fetchBaseWhenMoved = async (root: string, branch: string): Promise<void> => {
+  const [remote, local] = await Promise.all([
+    gitAsync(root, ['ls-remote', BASE_REMOTE, `refs/heads/${branch}`]),
+    gitAsync(root, ['rev-parse', '--verify', '--quiet', `${BASE_REMOTE}/${branch}^{commit}`]),
+  ])
+  if (!baseFetchNeeded(remote === null ? null : remoteTipOf(remote, branch), local?.trim() || null)) return
+  await fetchBase(root, BASE_REMOTE, branch)
+}