@joshuafolkken/kit 1.1383.0 → 1.1435.0

package/scripts/run/board/run-board-header.ts

@@ -1,26 +1,34 @@
 import { styleText } from 'node:util'
 import { backlog_budget } from '#scripts/backlog/backlog-budget'
 import { run_board_fit } from './run-board-fit'
+import { run_board_fresh } from './run-board-fresh'
 import { run_board_labels } from './run-board-labels'
 import { run_board_layout, type BoardLayout, type BoardRow } from './run-board-layout'
 import { run_board_machine, type MachineGauges } from './run-board-machine'
+import { run_board_now, type NowLine } from './run-board-now'
+import type { SessionOperations } from './run-board-operation-read'
 import { run_board_render_slot } from './run-board-render-slot'
 import type { RunActivity } from './run-board-status'
 import type { LaneUsages } from './run-board-usage'
+import type { UsualTimes } from './run-board-usual'
 
 // The top of `run:board`: whether the run is moving, how long it has run, how fresh its last event is,
 // and how far through the plan it is. Every time comes from a record (the carry's start, the stream's
-// events); nothing here guesses one. Lines of symbols rather than sentences: the `⏰` that moves every
-// second is the proof the board is live, so no `updated` line is drawn. **Always two lines, in three
-// columns**: the run's mark and name over its repository's, the run's age over the `💓`, then the
-// progress over the machine the run is on — so the first line reads as how far the run is and the
-// second as what it runs on, a slow run apart from a stuck one. Both are written the same while the
-// run works and while it waits, so a wait is read off the mark and the `💓` rather than off a line
-// that changes shape. A value not read yet is drawn `-`, never `0`, so a header still loading reads
-// as unknown rather than as an empty run.
+// events); nothing here guesses one. Two lines of symbols rather than sentences: the `⏰` that moves
+// every second is the proof the board is live, so no `updated` line is drawn. **Always three lines,
+// the first two in three columns**: the run's mark and name over its repository's, the run's age over
+// the `💓`, then the progress over the machine the run is on — so the first line reads as how far the
+// run is and the second as what it runs on, a slow run apart from a stuck one. The third says what the
+// run is doing now (`run-board-now.ts`): the spinner, its time and its kind's icon under the second and
+// third columns' icons and digits, so the mark itself never turns. All three are written the
+// same while the run works and while it waits, so a wait is read off the mark, the `💓` and the third
+// line's words rather than off a line that changes shape. A value not read yet is drawn `-`, never
+// `0`, so a header still loading reads as unknown rather than as an empty run.
 
 const { HEADER_ICONS, STATE_ICONS, WORDS, bar_of, minute_of, span_of } = run_board_labels
 const { cell_of } = run_board_render_slot
+const { padded } = run_board_fresh
+const aged_fresh = run_board_fresh.aged
 const UNKNOWN = '-'
 const BLANK = ' '
 const REPO_SEPARATOR = '/'
@@ -44,6 +52,8 @@ interface BoardHeader {
 	// Set once the run has ended: the title then says when, and how long it took.
 	ended_ms: number | undefined
 	activity: RunActivity
+	// The newest operation of each session of the run, `undefined` where none was read.
+	operations?: SessionOperations | undefined
 	layout: BoardLayout | undefined
 	// The total the board first saw, so arrivals since then read as `(+N)`.
 	baseline_total: number | undefined
@@ -55,6 +65,8 @@ interface BoardHeader {
 	machine: MachineGauges | undefined
 	// Each running lane's CPU and memory, `undefined` where none could be read.
 	usages?: LaneUsages | undefined
+	// How long each phase usually takes; a running row's phase time is colored against it.
+	usual?: UsualTimes | undefined
 	// The spinner's frame a running run and a running row turn, `undefined` where the output is not a
 	// terminal and they draw their still icons.
 	spinner: string | undefined
@@ -74,13 +86,15 @@ interface BoardCounts {
 	remaining: number
 }
 
-type RunMark = 'running' | 'idle' | 'human' | 'stopped'
+// `setup` is a run with no child running that is itself at work on a stage (`run-board-setup.ts`).
+type RunMark = 'running' | 'setup' | 'idle' | 'human' | 'stopped'
 
 type TextColor = Parameters<typeof styleText>[0]
 
 // The run's state as a colored glyph before its name.
 const RUN_MARKS: Readonly<Record<RunMark, { glyph: string; color: TextColor }>> = {
 	running: { glyph: '▶', color: 'green' },
+	setup: { glyph: '▶', color: 'green' },
 	idle: { glyph: '⏸', color: 'yellow' },
 	human: { glyph: '✋', color: 'magenta' },
 	stopped: { glyph: '■', color: 'gray' },
@@ -99,9 +113,16 @@ function counts_of(layout: BoardLayout): BoardCounts {
 	return { total, settled, parked, running, remaining: total - settled - running }
 }
 
-// Nothing running: the run is waiting on a person when all the plan has left is what
-// `needs-decision` holds, and otherwise idle.
-function quiet_mark(layout: BoardLayout | undefined): RunMark {
+// The marks of a run that is working: they turn the spinner, and only they can go stale.
+const WORKING_MARKS: ReadonlySet<RunMark> = new Set<RunMark>(['running', 'setup'])
+
+// Nothing running: the run is at work on a stage of its own; else it is waiting on a person when all
+// the plan has left is what `needs-decision` holds, or idle.
+function quiet_mark(header: BoardHeader): RunMark {
+	const { layout } = header
+
+	if (header.activity.setup !== undefined) return 'setup'
+
 	return layout?.waves.length === 0 && layout.people.length > 0 ? 'human' : 'idle'
 }
 
@@ -109,15 +130,14 @@ function quiet_mark(layout: BoardLayout | undefined): RunMark {
 function mark_of(header: BoardHeader, running: number): RunMark {
 	if (header.activity.is_stopped) return 'stopped'
 
-	return running > 0 ? 'running' : quiet_mark(header.layout)
+	return running > 0 ? 'running' : quiet_mark(header)
 }
 
-// A running run turns the spinner in place of ▶, both one column wide; every other mark stands still.
-function run_part(mark: RunMark, spinner: string | undefined): string {
+// The mark stands still in every state: the spinner turns on the third line.
+function run_part(mark: RunMark): string {
 	const { glyph, color } = RUN_MARKS[mark]
-	const shown = mark === 'running' ? (spinner ?? glyph) : glyph
 
-	return styleText(color, `${shown} ${RUN_NAME}`)
+	return styleText(color, `${glyph} ${RUN_NAME}`)
 }
 
 // The repository's own name — `kit` of `owner/kit` — under the run's, past the mark's columns, so a
@@ -129,6 +149,8 @@ function repo_part(header: BoardHeader, mark: RunMark): string {
 	return `${BLANK.repeat(indent)}${name}`
 }
 
+// A part aged as the `💓` is: yellow once stale, red once alarming — a row's newest activity too
+// (`run-board-render-tail.ts`).
 function aged(part: string, age_ms: number): string {
 	if (age_ms > ALARM_MS) return styleText('red', part)
 
@@ -153,26 +175,76 @@ function ended_part(header: BoardHeader): string {
 }
 
 // The `💓` under the run's age, in the `⏰`'s own format with its digits right-aligned to `width` —
-// only a running run can be stale, so only it is colored. Only an ended run draws anything else there:
-// the minute it ended.
+// only a working run can be stale, so only it is colored. Only an ended run draws anything else there:
+// the minute it ended. Its digits are emphasized for a few seconds after a new event resets them
+// (`run-board-fresh.ts`).
 function beat_part(header: BoardHeader, mark: RunMark, width: number): string {
 	const age = age_of(header)
 
 	if (age === undefined) return ended_part(header)
 
-	const part = `${HEADER_ICONS.heartbeat} ${span_of(age).padStart(width)}`
+	const span = span_of(age)
+	const part = `${HEADER_ICONS.heartbeat} ${padded(span, width, aged_fresh(span, age, header))}`
 
-	return mark === 'running' ? aged(part, age) : part
+	return WORKING_MARKS.has(mark) ? aged(part, age) : part
 }
 
-// A run's age over the `💓`, or over the minute an ended run ended: the shorter of the two lengths is
-// right-aligned to the longer, so the digits stand in one column when only one has passed ten hours.
-function time_parts(header: BoardHeader, mark: RunMark): Array<string> {
-	const elapsed = span_of((header.ended_ms ?? header.now_ms) - header.started_ms)
+// How long ago what the third line says happened, blank where no event gave it a time.
+function now_age(now: NowLine | undefined): string {
+	const age = now?.age_ms
+
+	return age === undefined ? '' : span_of(age)
+}
+
+// How long ago what the third line says happened, counted to now: an ended run's age stops at its end,
+// so its last words would otherwise stay fresh on every frame after it.
+function fresh_age(now: NowLine | undefined, header: BoardHeader): number | undefined {
+	const age = now?.age_ms
+
+	return age === undefined ? undefined : age + header.now_ms - (header.ended_ms ?? header.now_ms)
+}
+
+// The `💓`'s digits, blank where it draws none.
+function beat_span(header: BoardHeader): string {
 	const age = age_of(header)
-	const width = Math.max(elapsed.length, age === undefined ? 0 : span_of(age).length)
 
-	return [`${HEADER_ICONS.elapsed} ${elapsed.padStart(width)}`, beat_part(header, mark, width)]
+	return age === undefined ? '' : span_of(age)
+}
+
+// The third line's time: the spinner in the `⏰`'s and `💓`'s column — turning only while the run
+// works, so a watch or an end stands blank — then its age, digits under theirs, emphasized while what
+// the line says is fresh.
+function now_time(
+	header: BoardHeader,
+	mark: RunMark,
+	now: NowLine | undefined,
+	width: number,
+): string {
+	const spinner = WORKING_MARKS.has(mark) ? header.spinner : undefined
+	const icon = cell_of(spinner, run_board_fit.width_of(HEADER_ICONS.heartbeat))
+	const age = now_age(now)
+
+	return `${icon} ${padded(age, width, aged_fresh(age, fresh_age(now, header), header))}`
+}
+
+// What the third line says, emphasized while it is fresh.
+function now_text(now: NowLine, header: BoardHeader): string {
+	return `${now.icon} ${aged_fresh(now.text, fresh_age(now, header), header)}`
+}
+
+// A run's age over the `💓` — or over the minute an ended run ended — over the third line's age: the
+// shorter lengths are right-aligned to the longest, so the digits stand in one column when only one has
+// passed ten hours.
+function time_parts(header: BoardHeader, mark: RunMark, now: NowLine | undefined): Array<string> {
+	const elapsed = span_of((header.ended_ms ?? header.now_ms) - header.started_ms)
+	const age = now_age(now)
+	const width = Math.max(...[elapsed, beat_span(header), age].map((span) => span.length))
+
+	return [
+		`${HEADER_ICONS.elapsed} ${elapsed.padStart(width)}`,
+		beat_part(header, mark, width),
+		now_time(header, mark, now, width),
+	]
 }
 
 // A plan fetch is said only when it failed — the board otherwise keeps quiet about a routine read.
@@ -250,6 +322,27 @@ function progress_part(counts: BoardCounts, header: BoardHeader): string {
 	return parts.filter((part) => part !== undefined).join(GAP)
 }
 
+// The children drawn as running: only their operations are the run's newest.
+function running_issues(layout: BoardLayout): ReadonlySet<number> {
+	const running = layout.active.filter((row) => row.state === 'running')
+
+	return new Set(running.map((row) => row.number))
+}
+
+// What the run is doing now (`run-board-now.ts`).
+function now_line(counts: BoardCounts, header: BoardHeader): NowLine | undefined {
+	return run_board_now.line_of({
+		now_ms: header.now_ms,
+		ended_ms: header.ended_ms,
+		activity: header.activity,
+		operations: header.operations,
+		children: running_issues(layout_of(header)),
+		running: counts.running,
+		waiting: is_plan_read(header) ? counts.remaining : undefined,
+		people: layout_of(header).people.length,
+	})
+}
+
 // The gauges the machine line draws: every one on a screen, the memory alone in a chat.
 function machine_of(header: BoardHeader): MachineGauges | undefined {
 	const { machine } = header
@@ -271,28 +364,37 @@ function machine_part(counts: BoardCounts, header: BoardHeader): string {
 	return run_board_machine.line_of(machine_of(header), width) ?? MACHINE_UNKNOWN
 }
 
-// Both lines' cells of one column, the narrower padded to the wider as the terminal counts them.
+// The lines' cells of one column, the narrower padded to the wider as the terminal counts them.
 function column_of(cells: ReadonlyArray<string>): Array<string> {
 	const width = Math.max(...cells.map((cell) => run_board_fit.width_of(cell)))
 
 	return cells.map((cell) => cell_of(cell, width))
 }
 
-// The run's name, age and progress, then its repository, heartbeat and machine under them, in every
-// state the board can be in.
+// The run's name, age and progress, then its repository, heartbeat and machine under them, then what
+// it is doing now — its time under theirs, its kind's icon under the `⚡`, the name's column left blank
+// and no label — in every state the board can be in. A stream with no event yet leaves it blank.
 function header_lines(header: BoardHeader): Array<string> {
 	const counts = counts_of(layout_of(header))
 	const mark = mark_of(header, counts.running)
-	const columns = [
-		column_of([run_part(mark, header.spinner), repo_part(header, mark)]),
-		column_of(time_parts(header, mark)),
-		[progress_part(counts, header), machine_part(counts, header)],
-	]
+	const now = now_line(counts, header)
+	const names = column_of([run_part(mark), repo_part(header, mark), ''])
+	const times = column_of(time_parts(header, mark, now))
+	const lasts = [progress_part(counts, header), machine_part(counts, header)]
+	const third =
+		now === undefined ? '' : [names.at(-1), times.at(-1), now_text(now, header)].join(GAP)
+
+	return [...lasts.map((last, line) => [names[line], times[line], last].join(GAP)), third]
+}
+
+// The third line's kind as the legend names it, `undefined` where the line's own words name it.
+function now_legend(header: BoardHeader): string | undefined {
+	const now = now_line(counts_of(layout_of(header)), header)
 
-	return [0, 1].map((line) => columns.map((column) => column[line]).join(GAP))
+	return now?.legend === undefined ? undefined : `${now.icon} ${now.legend}`
 }
 
-const run_board_header = { counts_of, header_lines, is_plan_read }
+const run_board_header = { aged, counts_of, header_lines, is_plan_read, now_legend }
 
 export { run_board_header }
 export type { BoardCounts, BoardForm, BoardHeader }

package/scripts/run/board/run-board-labels.ts

@@ -1,6 +1,7 @@
 import { WriteStream } from 'node:tty'
 import { styleText } from 'node:util'
 import type { FiledKind } from '#scripts/run/event/run-event-filed'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import cli_spinners from 'cli-spinners'
 import type { BoardNote } from './run-board-notes'
 import type { Phase } from './run-board-phase'
@@ -67,6 +68,12 @@ const WORDS = {
 	park: 'park',
 	note: 'note',
 	found_during: ' (found during {n})',
+	// What the run is doing now, where no stage of its own says it.
+	watching: 'watching',
+	pool_empty: 'pool empty',
+	on_person: 'waiting on a person',
+	operation: 'operation',
+	ended: 'ended',
 	// The session a stopped run waits in, and what closing the board leaves.
 	resume: 'stopped — resume with',
 	keeps_running: 'Closing this screen leaves the run going · reopen with `pnpm josh backlogrun`',
@@ -175,6 +182,24 @@ const HEADER_ICONS = {
 	heartbeat: '💓',
 } as const
 
+// The kind of what the header's third line says, under the `⚡` (joshuafolkken/kit#3767): a call a
+// session made, the run watching its pool, the run ended, or each of the run's own stages, keyed by the
+// stage's words before any issue. A child's event draws its row's phase icon instead. The run ended
+// draws the header's own end mark — 🏁 is already a done row's state icon.
+const NOW_ICONS = { operation: '🔧', watching: '🔭', ended: HEADER_ICONS.ended } as const
+const { STAGE, LANE_STAGE } = run_event_setup
+const STAGE_ICONS: Readonly<Partial<Record<string, string>>> = {
+	[STAGE.STARTING]: '🚀',
+	[STAGE.PLANNING]: '📝',
+	[STAGE.HANDING_OFF]: '🤝',
+	[STAGE.JUDGING]: '🤔',
+	[STAGE.SESSION]: '💭',
+	[STAGE.NO_CHILD]: '🚫',
+	[LANE_STAGE.OPENING]: '🚪',
+	[LANE_STAGE.INSTALLING]: '📥',
+	[LANE_STAGE.DISPATCHING]: '📤',
+}
+
 // **The machine gauges' three colors, decided here alone**: Activity Monitor's green, yellow and red
 // in the system's dark-mode values. A palette's `green` draws blue and its `red` orange in a VSCode
 // terminal, so the normal gauge would read as the cyan plan bar and the busy one as yellow.
@@ -214,17 +239,32 @@ function elapsed_of(ms: number): string {
 	return `${two_digits(minutes)}:${two_digits(seconds % SECONDS_PER_MINUTE)}`
 }
 
-// How long the run has run or its stream has been silent, as `H:MM:SS` with the hours not padded; a negative
-// span reads as zero. Always three fields, so a run under an hour (`0:03:25`) never reads as a time.
-function span_of(ms: number): string {
+// A length as its hours, and its minutes and seconds within the hour; a negative span reads as zero.
+function span_fields(ms: number): [hours: number, minutes: number, seconds: number] {
 	const seconds = Math.floor(Math.max(0, ms) / MS_PER_SECOND)
 	const minutes = Math.floor(seconds / SECONDS_PER_MINUTE)
 	const hours = Math.floor(minutes / MINUTES_PER_HOUR)
-	const tail = [minutes % MINUTES_PER_HOUR, seconds % SECONDS_PER_MINUTE]
+
+	return [hours, minutes % MINUTES_PER_HOUR, seconds % SECONDS_PER_MINUTE]
+}
+
+// How long the run has run or its stream has been silent, as `H:MM:SS` with the hours not padded; a negative
+// span reads as zero. Always three fields, so a run under an hour (`0:03:25`) never reads as a time.
+function span_of(ms: number): string {
+	const [hours, ...tail] = span_fields(ms)
 
 	return [String(hours), ...tail.map((value) => two_digits(value))].join(':')
 }
 
+// How long the run has stood at its stage, as `M:SS` with the minutes not padded, and as `span_of`'s
+// `H:MM:SS` from an hour on. It stands beside the stage's words, never in the header's time column, so
+// its one separator is not read there as a time of day.
+function stage_span_of(ms: number): string {
+	const [hours, minutes, seconds] = span_fields(ms)
+
+	return hours === 0 ? `${String(minutes)}:${two_digits(seconds)}` : span_of(ms)
+}
+
 function is_shade(color: Paint): color is Shade {
 	return typeof color === 'object' && 'rgb' in color
 }
@@ -281,9 +321,11 @@ const run_board_labels = {
 	KIND_WORDS,
 	NOTES_ICON,
 	NOTE_ICONS,
+	NOW_ICONS,
 	PHASE_ICONS,
 	PHASE_WORDS,
 	SPINNER_INTERVAL_MS,
+	STAGE_ICONS,
 	STATE_ICONS,
 	WAITS_ICON,
 	WORDS,
@@ -294,6 +336,7 @@ const run_board_labels = {
 	painted,
 	span_of,
 	spinner_of,
+	stage_span_of,
 }
 
 export { run_board_labels }

package/scripts/run/board/run-board-lane-event.ts

@@ -0,0 +1,66 @@
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { run_board_phase, type Phase } from './run-board-phase'
+
+// Each running child's newest event of its own — the `lane-phase` the hook writes or a `ship-stage` its
+// ship writes — in words, with the phase whose icon its row's track draws. A child inside a long
+// `josh ship` makes no call of its own while the ship writes on, so the header's third line reads the
+// newer of this and the child's newest operation (joshuafolkken/kit#3767).
+
+interface LaneEvent {
+	phase: Phase
+	// The event's words after its issue: `implement`, `ship gate`, `ship gate failed`.
+	words: string
+	at_ms: number
+}
+
+const KIND = run_event_stream.EVENT_KIND
+const LANE_KINDS: ReadonlySet<string> = new Set([KIND.LANE_PHASE, KIND.SHIP_STAGE])
+const WORD_SEPARATOR = ' '
+const SHIP = 'ship'
+
+// A ship's stage reads as `ship <stage>` once started and names how it ended after that; a lane's phase
+// reads as its own word.
+function words_of(event: RunEvent): string {
+	const [, stage = '', phase] = event.text.split(WORD_SEPARATOR)
+
+	if (event.kind === KIND.LANE_PHASE) return stage
+
+	const words = [SHIP, stage]
+
+	return (phase === run_ship_stage.PHASE.START ? words : [...words, phase]).join(WORD_SEPARATOR)
+}
+
+function lane_event_of(event: RunEvent): LaneEvent | undefined {
+	const phase = LANE_KINDS.has(event.kind) ? run_board_phase.stage_phase_of(event) : undefined
+
+	return phase === undefined
+		? undefined
+		: { phase, words: words_of(event), at_ms: Date.parse(event.at) }
+}
+
+// The stream's bound keeps each issue's newest stage start apart from the rest, so the order of the
+// lines is not their age.
+function is_newer(lane: LaneEvent, held: LaneEvent | undefined): boolean {
+	return held === undefined || lane.at_ms >= held.at_ms
+}
+
+// The newest lane event of every issue the stream names one for.
+function newest_of(events: ReadonlyArray<RunEvent>): ReadonlyMap<number, LaneEvent> {
+	const newest = new Map<number, LaneEvent>()
+
+	for (const event of events) {
+		const lane = lane_event_of(event)
+		const issue = Number(run_event_scope.issue_named(event))
+
+		if (lane !== undefined && is_newer(lane, newest.get(issue))) newest.set(issue, lane)
+	}
+
+	return newest
+}
+
+const run_board_lane_event = { newest_of }
+
+export { run_board_lane_event }
+export type { LaneEvent }

package/scripts/run/board/run-board-layout.ts

@@ -1,3 +1,4 @@
+import type { Declared } from '#scripts/backlog/backlog-overlap'
 import { backlog_plan, type PlanContext } from '#scripts/backlog/backlog-plan'
 import type { WavePlan } from '#scripts/backlog/backlog-waves'
 import type { EpicChild } from '#scripts/epic/epic-graph'
@@ -25,8 +26,22 @@ interface BoardPlan {
 	// Each issue's label names as the open listing read them, so a running row is drawn as its labels
 	// say it stopped.
 	labels: ReadonlyMap<number, ReadonlyArray<string>>
+	// The paths each issue's body declares (`Plan.scope.declared`), which a waiting row is checked
+	// against a running one by; a plan read without them checks none.
+	declared?: Declared | undefined
 }
 
+// Why a waiting row waits, or the stage its lane's launch is at, in the board's own words.
+interface RowReason {
+	text: string
+	// When the row entered a stage, where the reason is one — how long it has stood there is counted
+	// from it.
+	since_ms?: number | undefined
+}
+
+// What a waiting child's row says after its blockers; `undefined` says nothing.
+type ReasonOf = (child: EpicChild) => RowReason | undefined
+
 interface BoardRow {
 	number: number
 	title: string | undefined
@@ -36,6 +51,8 @@ interface BoardRow {
 	status: ItemStatus | undefined
 	// The standing blockers this row still waits on, as the plan names them.
 	waits: ReadonlyArray<string>
+	// Why the row waits beyond its blockers (`run-board-reason.ts`); a row the run has touched has none.
+	reason?: RowReason | undefined
 }
 
 type WaveEntry =
@@ -60,6 +77,11 @@ interface Overlay {
 	statuses: ReadonlyMap<number, ItemStatus>
 }
 
+// The overlay a layout is drawn from: the plan under the statuses, and what each waiting row says.
+interface Drawn extends Overlay {
+	reason_of: ReasonOf | undefined
+}
+
 const SETTLED_STATES: ReadonlySet<ItemState> = new Set(['merged', 'parked', 'done'])
 
 function is_settled(state: ItemState): boolean {
@@ -80,13 +102,20 @@ function reference_of(edge: IssueReference, repo: string): string {
 	return edge.repo === repo ? String(edge.number) : issue_cite.plain(edge.number, edge.repo)
 }
 
-function plan_row(child: EpicChild, state: ItemState, overlay: Overlay): BoardRow {
+// Whether a blocker the plan names still stands for `child` — the wait its row draws as 🔗.
+function is_blocked(child: EpicChild, overlay: Overlay): boolean {
+	return child.blocked_by.some((edge) => is_waiting_on(edge, overlay))
+}
+
+function plan_row(child: EpicChild, state: ItemState, overlay: Drawn): BoardRow {
 	const { context } = overlay.plan
 	const waits = child.blocked_by
 		.filter((edge) => is_waiting_on(edge, overlay))
 		.map((edge) => reference_of(edge, context.repo))
+	const reason = state === 'waiting' ? overlay.reason_of?.(child) : undefined
 
 	return {
+		...(reason !== undefined && { reason }),
 		number: child.number,
 		title: context.titles.get(child.number),
 		kind: run_board_kind.kind_of(child.labels),
@@ -119,7 +148,7 @@ function active_rows(statuses: ReadonlyMap<number, ItemStatus>, read: RowRead):
 function place_in_epic(
 	entries: Array<WaveEntry>,
 	epic: number,
-	overlay: Overlay,
+	overlay: Drawn,
 	row: BoardRow,
 ): void {
 	const group = entries.find((entry) => entry.kind === 'epic' && entry.epic === epic)
@@ -144,7 +173,7 @@ function wave_state(child: EpicChild): ItemState {
 
 // One wave, its rows in the plan's order, an epic's children gathered under the epic where the first
 // of them falls.
-function wave_entries(wave: ReadonlyArray<EpicChild>, overlay: Overlay): Array<WaveEntry> {
+function wave_entries(wave: ReadonlyArray<EpicChild>, overlay: Drawn): Array<WaveEntry> {
 	const entries: Array<WaveEntry> = []
 
 	for (const child of wave) {
@@ -158,7 +187,7 @@ function wave_entries(wave: ReadonlyArray<EpicChild>, overlay: Overlay): Array<W
 	return entries
 }
 
-function unreached_rows(overlay: Overlay, is_people: boolean): Array<BoardRow> {
+function unreached_rows(overlay: Drawn, is_people: boolean): Array<BoardRow> {
 	const state: ItemState = is_people ? 'human' : 'waiting'
 
 	return overlay.plan.waves.unreached
@@ -166,8 +195,25 @@ function unreached_rows(overlay: Overlay, is_people: boolean): Array<BoardRow> {
 		.map((child) => plan_row(child, state, overlay))
 }
 
-function layout_of(plan: BoardPlan, statuses: ReadonlyMap<number, ItemStatus>): BoardLayout {
-	const overlay = { plan, statuses }
+// Every issue the plan holds, wave or unreached.
+function children_of(plan: BoardPlan): Array<EpicChild> {
+	return [...plan.waves.waves.flat(), ...plan.waves.unreached]
+}
+
+// The children whose rows wait on the run rather than on a person: the run has not touched them, and
+// no decision is asked of anyone.
+function waiting_children(overlay: Overlay): Array<EpicChild> {
+	return children_of(overlay.plan).filter(
+		(child) => is_untouched(child, overlay) && !is_human(child),
+	)
+}
+
+function layout_of(
+	plan: BoardPlan,
+	statuses: ReadonlyMap<number, ItemStatus>,
+	reason_of?: ReasonOf,
+): BoardLayout {
+	const overlay = { plan, statuses, reason_of }
 	const waves = plan.waves.waves.map((wave) =>
 		wave_entries(
 			wave.filter((child) => is_untouched(child, overlay)),
@@ -195,9 +241,9 @@ function local_layout_of(statuses: ReadonlyMap<number, ItemStatus>): BoardLayout
 	}
 }
 
-// Every issue the plan holds, wave or unreached — the run's scope a lane is checked against.
+// The run's scope a lane is checked against.
 function numbers_of(plan: BoardPlan): ReadonlySet<number> {
-	return new Set([...plan.waves.waves.flat(), ...plan.waves.unreached].map((child) => child.number))
+	return new Set(children_of(plan).map((child) => child.number))
 }
 
 // Every row the layout draws, an epic's children among them — what the header counts and the legend reads.
@@ -211,12 +257,14 @@ function rows_of(layout: BoardLayout): Array<BoardRow> {
 
 const run_board_layout = {
 	EMPTY_LAYOUT,
+	is_blocked,
 	is_settled,
 	layout_of,
 	local_layout_of,
 	numbers_of,
 	rows_of,
+	waiting_children,
 }
 
 export { run_board_layout }
-export type { BoardLayout, BoardPlan, BoardRow, WaveEntry }
+export type { BoardLayout, BoardPlan, BoardRow, Overlay, ReasonOf, RowReason, WaveEntry }