@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -0,0 +1,219 @@
+import { stripVTControlCharacters } from 'node:util'
+import string_width from 'string-width'
+import { run_board_labels } from './run-board-labels'
+
+// A live `run:board` frame kept within the terminal. A frame taller than the pane scrolls the
+// alternate screen as it is written, and the header — the lines that say whether the run moves and
+// how far it is — is what scrolls off. So the parts below it give way instead, least wanted first:
+// the footer, the legend, the finished rows, the notes, the rows not yet started, the parked rows
+// and, last, the running rows — what a person keeps the board open to see. Each stage stops once the
+// frame fits, a cut row is counted on its section's `more N` line, and the order a row is drawn in
+// never changes. A line wider than the pane wraps, so every line is counted by the rows it takes on
+// screen, not as one.
+
+const { WORDS } = run_board_labels
+const INDENT = '  '
+
+interface TerminalSize {
+	rows: number
+	columns: number
+}
+
+// The stage an issue row gives way in, the earlier first.
+type YieldStage = 'finished' | 'pending' | 'parked' | 'running'
+
+// When a row's stage gives it way: the oldest first, a row with no time before every timed one.
+interface RowYield {
+	stage: YieldStage
+	at_ms: number | undefined
+}
+
+// One line of the plan, an issue row with when it gives way; a rule, a blank or an epic's own line none.
+interface PlanLine {
+	text: string
+	row: RowYield | undefined
+}
+
+// A plan section drops its heading once none of its rows is left.
+interface PlanSection {
+	head: ReadonlyArray<string>
+	lines: ReadonlyArray<PlanLine>
+}
+
+// The newest notes shown, and how many older ones are already past the section's limit.
+interface NotesPart {
+	head: ReadonlyArray<string>
+	lines: ReadonlyArray<string>
+	hidden: number
+}
+
+// A frame in its parts, top to bottom: the header above stays.
+interface FrameParts {
+	above: ReadonlyArray<string>
+	plan: ReadonlyArray<PlanSection>
+	notes: NotesPart
+	legend: ReadonlyArray<string>
+	footer: ReadonlyArray<string>
+}
+
+// One thing that gives way: a part as a whole, one note (the oldest shown), or one issue row.
+type Yielder = 'footer' | 'legend' | 'note' | PlanLine
+
+interface Cut {
+	footer: boolean
+	legend: boolean
+	notes: number
+	rows: ReadonlySet<PlanLine>
+}
+
+const NO_CUT: Cut = { footer: false, legend: false, notes: 0, rows: new Set() }
+
+// The columns a line takes on screen: its color escapes take none, an emoji two.
+function width_of(line: string): number {
+	return string_width(stripVTControlCharacters(line))
+}
+
+function height_of(line: string, columns: number): number {
+	return Math.max(1, Math.ceil(width_of(line) / Math.max(1, columns)))
+}
+
+function heights(lines: ReadonlyArray<string>, columns: number): number {
+	return lines.reduce((sum, line) => sum + height_of(line, columns), 0)
+}
+
+function more_lines(hidden: number): Array<string> {
+	return hidden > 0 ? [`${INDENT}${WORDS.more} ${String(hidden)}`] : []
+}
+
+// A section that ends on an epic whose children were all cut ends on its last row instead.
+function section_lines(section: PlanSection, cut: ReadonlySet<PlanLine>): Array<string> {
+	const kept = section.lines.filter((line) => !cut.has(line))
+	const last = kept.findLastIndex((line) => line.row !== undefined)
+
+	if (last === -1) return []
+
+	return [...section.head, ...kept.slice(0, last + 1).map((line) => line.text)]
+}
+
+// The plan's cut rows are counted on one line at its end, under a blank when no section is left.
+function plan_lines(plan: ReadonlyArray<PlanSection>, cut: ReadonlySet<PlanLine>): Array<string> {
+	const drawn = plan.flatMap((section) => section_lines(section, cut))
+	const lead = drawn.length === 0 && cut.size > 0 ? [''] : []
+
+	return [...lead, ...drawn, ...more_lines(cut.size)]
+}
+
+// The notes give way from the oldest shown; with none left the section goes, heading and all.
+function notes_lines(notes: NotesPart, cut: number): Array<string> {
+	const kept = notes.lines.slice(0, notes.lines.length - cut)
+
+	if (kept.length === 0) return []
+
+	return [...notes.head, ...kept, ...more_lines(notes.hidden + cut)]
+}
+
+function compose(parts: FrameParts, cut: Cut): Array<string> {
+	return [
+		...parts.above,
+		...plan_lines(parts.plan, cut.rows),
+		...notes_lines(parts.notes, cut.notes),
+		...(cut.legend ? [] : parts.legend),
+		...(cut.footer ? [] : parts.footer),
+	]
+}
+
+interface Indexed {
+	line: PlanLine
+	index: number
+}
+
+function at_of(entry: Indexed): number {
+	return entry.line.row?.at_ms ?? -Infinity
+}
+
+// The oldest first; rows with the same time — the rows not yet started have none — from the plan's end.
+function oldest_first(left: Indexed, right: Indexed): number {
+	const [left_at, right_at] = [at_of(left), at_of(right)]
+
+	if (left_at === right_at) return right.index - left.index
+
+	return left_at < right_at ? -1 : 1
+}
+
+function yielding(rows: ReadonlyArray<Indexed>, stage: YieldStage): Array<PlanLine> {
+	return rows
+		.filter((entry) => entry.line.row?.stage === stage)
+		.toSorted(oldest_first)
+		.map((entry) => entry.line)
+}
+
+// Everything that gives way, in the order it does.
+function order_of(parts: FrameParts): Array<Yielder> {
+	const rows = parts.plan
+		.flatMap((section) => section.lines)
+		.map((line, index) => ({ line, index }))
+		.filter((entry) => entry.line.row !== undefined)
+	const notes = parts.notes.lines.map((): Yielder => 'note')
+
+	return [
+		'footer',
+		'legend',
+		...yielding(rows, 'finished'),
+		...notes,
+		...yielding(rows, 'pending'),
+		...yielding(rows, 'parked'),
+		...yielding(rows, 'running'),
+	]
+}
+
+function is_line(item: Yielder): item is PlanLine {
+	return typeof item !== 'string'
+}
+
+// What the first `count` of the order cuts.
+function cut_of(order: ReadonlyArray<Yielder>, count: number): Cut {
+	const gone = order.slice(0, count)
+
+	return {
+		footer: gone.includes('footer'),
+		legend: gone.includes('legend'),
+		notes: gone.filter((item) => item === 'note').length,
+		rows: new Set(gone.filter((item) => is_line(item))),
+	}
+}
+
+// The leading lines that fit, for a pane too short even for the header: the top is what is kept.
+function clamped(lines: ReadonlyArray<string>, size: TerminalSize): Array<string> {
+	let used = 0
+
+	return lines.filter((line) => {
+		used += height_of(line, size.columns)
+
+		return used <= size.rows
+	})
+}
+
+// A frame drawn whole, where no terminal bounds it.
+function whole(parts: FrameParts): Array<string> {
+	return compose(parts, NO_CUT)
+}
+
+// The frames each longer cut of the order leaves, the uncut whole first.
+function frames_of(parts: FrameParts): Array<Array<string>> {
+	const order = order_of(parts)
+	const counts = Array.from({ length: order.length + 1 }, (_, count) => count)
+
+	return counts.map((count) => compose(parts, cut_of(order, count)))
+}
+
+function fit(parts: FrameParts, size: TerminalSize): Array<string> {
+	const frames = frames_of(parts)
+	const fitting = frames.find((frame) => heights(frame, size.columns) <= size.rows)
+
+	return clamped(fitting ?? frames.at(-1) ?? [], size)
+}
+
+const run_board_fit = { fit, height_of, whole, width_of }
+
+export { run_board_fit }
+export type { FrameParts, NotesPart, PlanLine, PlanSection, RowYield, TerminalSize, YieldStage }

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

@@ -0,0 +1,162 @@
+import { run_progress } from '#scripts/run/progress/run-progress'
+import { run_progress_cli } from '#scripts/run/progress/run-progress-cli'
+import type { ClosedAnswer } from './run-board-closed'
+import { run_board_fetch, type Fetch } from './run-board-fetch'
+import { run_board_layout, type BoardPlan } from './run-board-layout'
+import type { LocalRead } from './run-board-read'
+import { run_board_state, type BoardPorts, type BoardState, type Pace } from './run-board-state'
+import { run_board_status, type ItemStatus } from './run-board-status'
+
+// The GitHub reads a `run:board` redraw draws over: the plan, and the run's children that left the
+// open listing. Each is taken no more often than `run:progress` re-reads after a decline. **A live
+// board never waits on them**: each read is launched and folded in on the redraw after it lands, so
+// the clock keeps moving while GitHub answers; one plain frame waits for them. A failed plan read
+// keeps the previous plan on screen and says when it failed. A run that ended keeps its plan as it
+// last read.
+
+const PLAN_RETRY_MS = run_progress_cli.DECLINE_RETRY_SECONDS * run_progress.MS_PER_SECOND
+// A rejected closed read answers nothing closed and not whole, so it is asked again.
+const UNANSWERED: ClosedAnswer = { closed: new Map(), is_whole: false }
+const { is_due } = run_board_state
+
+// What a step of the GitHub reads works against.
+interface Gather {
+	ports: BoardPorts
+	local: LocalRead
+	now_ms: number
+	pace: Pace
+}
+
+// A title the board once knew stays known, so an issue that left the open listing keeps its name.
+function with_titles(plan: BoardPlan, previous: BoardPlan | undefined): BoardPlan {
+	const titles = new Map([...(previous?.context.titles ?? []), ...plan.context.titles])
+
+	return { ...plan, context: { ...plan.context, titles } }
+}
+
+// An ended run's plan is read until it lands once, then held; a read in flight is not launched again.
+function is_plan_due(state: BoardState, gather: Gather): boolean {
+	if (state.plan_fetch !== undefined) return false
+	if (gather.local.ended_ms !== undefined && state.fetched_ms !== undefined) return false
+
+	return is_due(state.attempted_ms, PLAN_RETRY_MS, gather.now_ms)
+}
+
+function launch_plan(state: BoardState, gather: Gather): BoardState {
+	if (!is_plan_due(state, gather)) return state
+
+	async function read(): Promise<BoardPlan | undefined> {
+		return await gather.ports.read_plan(gather.local.scope)
+	}
+
+	const plan_fetch = run_board_fetch.launch(read, undefined)
+
+	return { ...state, plan_fetch, attempted_ms: gather.now_ms }
+}
+
+// A landed read is folded in as of the moment it was asked; one still in flight leaves the state as is.
+function fold_plan(state: BoardState): BoardState {
+	const answer = state.plan_fetch?.answer()
+
+	if (answer === undefined) return state
+
+	const settled = { ...state, plan_fetch: undefined }
+
+	if (answer.value === undefined) return { ...settled, failed_ms: state.attempted_ms }
+
+	return {
+		...settled,
+		plan: with_titles(answer.value, state.plan),
+		fetched_ms: state.attempted_ms,
+		failed_ms: undefined,
+	}
+}
+
+function statuses_for(plan: BoardPlan, local: LocalRead): ReadonlyMap<number, ItemStatus> {
+	return run_board_status.statuses_of(local.events, local.lanes, run_board_layout.numbers_of(plan))
+}
+
+// The children the run touched that the open listing no longer holds and the board has not read yet.
+// A listing cut short proves nothing missing, so it asks about none.
+function unread_closed(state: BoardState, local: LocalRead): Array<number> {
+	const open = state.plan?.context.open_numbers
+
+	if (open === undefined || state.plan === undefined) return []
+
+	const touched = [...statuses_for(state.plan, local).keys()]
+
+	return touched.filter((issue) => !open.has(issue) && !state.closed.has(issue))
+}
+
+// An ended run asks until one ask after it ended has answered whole, then holds what it has, as its
+// plan is held: the board is left open between runs, so a child that never answers closed would
+// otherwise be asked about every retry interval while no run is going.
+function has_asked_since_end(state: BoardState, local: LocalRead): boolean {
+	const { closed_answered_ms } = state
+	if (closed_answered_ms === undefined || local.ended_ms === undefined) return false
+
+	return closed_answered_ms >= local.ended_ms
+}
+
+function is_closed_due(state: BoardState, gather: Gather): boolean {
+	if (state.closed_fetch !== undefined || has_asked_since_end(state, gather.local)) return false
+
+	return is_due(state.closed_attempted_ms, PLAN_RETRY_MS, gather.now_ms)
+}
+
+// A closed child is read once and its answer kept; one that has not answered closed is asked again no
+// sooner than the plan is, and an ended run's not again once an ask after the end has answered whole.
+function launch_closed(state: BoardState, gather: Gather): BoardState {
+	const unread = unread_closed(state, gather.local)
+
+	if (unread.length === 0 || !is_closed_due(state, gather)) return state
+
+	async function read(): Promise<ClosedAnswer> {
+		return await gather.ports.read_closed(unread)
+	}
+
+	const closed_fetch = run_board_fetch.launch(read, UNANSWERED)
+
+	return { ...state, closed_fetch, closed_attempted_ms: gather.now_ms }
+}
+
+// A whole answer counts as of the moment it was asked.
+function fold_closed(state: BoardState): BoardState {
+	const answer = state.closed_fetch?.answer()
+
+	if (answer === undefined) return state
+
+	const { closed, is_whole } = answer.value
+	const closed_answered_ms = is_whole ? state.closed_attempted_ms : state.closed_answered_ms
+
+	return {
+		...state,
+		closed: new Map([...state.closed, ...closed]),
+		closed_fetch: undefined,
+		closed_answered_ms,
+	}
+}
+
+// At the `settled` pace, waits for a read in flight to land.
+async function settle(pending: Fetch<unknown> | undefined, pace: Pace): Promise<void> {
+	if (pending !== undefined && pace === 'settled') await pending.landed
+}
+
+// Folds what landed and launches what is due — the plan first, since the closed children are read off
+// the plan's listing.
+async function gather_github(state: BoardState, gather: Gather): Promise<BoardState> {
+	const planned = launch_plan(fold_plan(state), gather)
+
+	await settle(planned.plan_fetch, gather.pace)
+
+	const closing = launch_closed(fold_closed(fold_plan(planned)), gather)
+
+	await settle(closing.closed_fetch, gather.pace)
+
+	return fold_closed(closing)
+}
+
+const run_board_github = { PLAN_RETRY_MS, gather_github, statuses_for }
+
+export { run_board_github }
+export type { Gather }

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

@@ -0,0 +1,275 @@
+import { styleText } from 'node:util'
+import { backlog_budget } from '#scripts/backlog/backlog-budget'
+import { backlog_idle, type IdleWindow } from '#scripts/backlog/backlog-idle'
+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 type { RunActivity } from './run-board-status'
+import type { LaneUsages } from './run-board-usage'
+
+// The top of `run:board`: whether the run is moving, how long it has run, how long it has left, how
+// fresh its last event is, and how far through the plan it is — and, while it waits on an empty
+// backlog, until when it waits and what ends the wait. Every time comes from a record (the carry's
+// start, the stream's events, the `idle` window); 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. Beside the time, the machine the run is on, so a slow run reads apart from a stuck
+// one. **Always two lines**: the run's state with its progress, then the time with the machine. 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, clock_of, elapsed_of, left_of, minute_of } =
+	run_board_labels
+const UNKNOWN = '-'
+const { GAP } = run_board_machine
+// A running run whose newest event is older than this is drawn as stale, so a hang stands out; past
+// twice that it is drawn as alarming.
+const STALE_MINUTES = 15
+const STALE_MS = STALE_MINUTES * backlog_budget.MS_PER_MINUTE
+const ALARM_FACTOR = 2
+const ALARM_MS = STALE_MS * ALARM_FACTOR
+const INDENT = '  '
+const RUN_NAME = 'backlogrun'
+
+// Who reads the frame: a person on a screen, or a chat a session answers a progress question in, which
+// draws what the screen does but for the machine, its memory alone — a CPU or swap figure read once
+// means nothing.
+type BoardForm = 'screen' | 'chat'
+
+interface BoardHeader {
+	now_ms: number
+	started_ms: number
+	// Set once the run has ended: the title then says when, and how long it took.
+	ended_ms: number | undefined
+	activity: RunActivity
+	layout: BoardLayout | undefined
+	// The total the board first saw, so arrivals since then read as `(+N)`.
+	baseline_total: number | undefined
+	plan_fetched_ms: number | undefined
+	plan_failed_ms: number | undefined
+	// Whether a plan read is in flight.
+	is_plan_loading: boolean
+	// The machine's gauges, `undefined` before the first sample.
+	machine: MachineGauges | undefined
+	// Each running lane's CPU and memory, `undefined` where none could be read.
+	usages?: LaneUsages | 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
+	form: BoardForm
+	// An issue reference as the board draws it — `3450` or `owner/repo#12` — made a link where the
+	// terminal opens one.
+	link: (reference: string) => string
+}
+
+interface BoardCounts {
+	total: number
+	settled: number
+	parked: number
+	running: number
+	remaining: number
+}
+
+type RunMark = 'running' | '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' },
+	idle: { glyph: '⏸', color: 'yellow' },
+	human: { glyph: '✋', color: 'magenta' },
+	stopped: { glyph: '■', color: 'gray' },
+}
+
+function count_state(rows: ReadonlyArray<BoardRow>, state: BoardRow['state']): number {
+	return rows.filter((row) => row.state === state).length
+}
+
+function counts_of(layout: BoardLayout): BoardCounts {
+	const total = run_board_layout.rows_of(layout).length
+	const parked = count_state(layout.active, 'parked')
+	const settled = count_state(layout.active, 'merged') + parked + count_state(layout.active, 'done')
+	const running = count_state(layout.active, 'running')
+
+	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 {
+	return layout?.waves.length === 0 && layout.people.length > 0 ? 'human' : 'idle'
+}
+
+// The run's state, each state overriding the ones below it.
+function mark_of(header: BoardHeader, running: number): RunMark {
+	if (header.activity.is_stopped) return 'stopped'
+	if (running > 0) return 'running'
+
+	return header.activity.idle === undefined ? quiet_mark(header.layout) : 'idle'
+}
+
+// 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 {
+	const { glyph, color } = RUN_MARKS[mark]
+	const shown = mark === 'running' ? (spinner ?? glyph) : glyph
+
+	return styleText(color, `${shown} ${RUN_NAME}`)
+}
+
+function aged(part: string, age_ms: number): string {
+	if (age_ms > ALARM_MS) return styleText('red', part)
+
+	return age_ms > STALE_MS ? styleText('yellow', part) : part
+}
+
+// How long ago the stream last moved; only a running run can be stale, so only it is colored. An ended
+// run has no heartbeat to keep: one counting on would read as a hang.
+function heartbeat_part(header: BoardHeader, mark: RunMark): string | undefined {
+	const last = header.activity.last_event_ms
+
+	if (last === undefined || header.ended_ms !== undefined) return undefined
+
+	const age = header.now_ms - last
+	const part = `💓 ${elapsed_of(age)}`
+
+	return mark === 'running' ? aged(part, age) : part
+}
+
+// A plan fetch is said only when it failed — the board otherwise keeps quiet about a routine read.
+function plan_warning(header: BoardHeader): string | undefined {
+	const failed = header.plan_failed_ms
+
+	if (failed === undefined) return undefined
+
+	return styleText('yellow', `⚠ ${WORDS.plan} ${minute_of(failed)}`)
+}
+
+// A plan read in flight turns the spinner after ⏳ and says nothing more; a
+// frame that is not a terminal's has no spinner, and draws nothing for it.
+function loading_part(header: BoardHeader): string | undefined {
+	const { is_plan_loading, spinner } = header
+
+	return is_plan_loading && spinner !== undefined ? `${HEADER_ICONS.loading} ${spinner}` : undefined
+}
+
+// A running run's age and time left before the cut-off, or an ended run's frozen duration and the
+// minute it ended — an ended run has no cut-off left.
+function time_parts(header: BoardHeader): Array<string> {
+	const { now_ms, started_ms, ended_ms } = header
+
+	if (ended_ms !== undefined) {
+		return [
+			`⏱ ${elapsed_of(ended_ms - started_ms)}`,
+			`${HEADER_ICONS.ended} ${minute_of(ended_ms)}`,
+		]
+	}
+
+	const cutoff = started_ms + backlog_budget.WHOLE_RUN_BUDGET_MS
+
+	return [`⏱ ${elapsed_of(now_ms - started_ms)}`, `⌛ ${left_of(cutoff - now_ms)}`]
+}
+
+function layout_of(header: BoardHeader): BoardLayout {
+	return header.layout ?? run_board_layout.EMPTY_LAYOUT
+}
+
+// Whether the plan has been read: until it has, the board draws the run's own children alone, and the
+// counts only the plan knows — the total and what waits — are unknown.
+function is_plan_read(header: BoardHeader): boolean {
+	return header.plan_fetched_ms !== undefined
+}
+
+// Arrivals since the board first looked, as `(+N)`.
+function plus_of(counts: BoardCounts, header: BoardHeader): string {
+	const added = counts.total - (header.baseline_total ?? counts.total)
+
+	return added > 0 ? ` (+${String(added)})` : ''
+}
+
+// Icon, figure, then bar, as the machine gauges: the settled count is right-aligned to the total's
+// width, so the bar starts in one column as the count grows. Arrivals since the board first looked
+// follow the bar, where they cannot move it.
+function tally_part(counts: BoardCounts, is_read: boolean): string {
+	const { settled } = counts
+	const total = is_read ? String(counts.total) : UNKNOWN
+	const tally = `${String(settled)}/${total}`.padStart(`${total}/${total}`.length)
+	const bar = is_read ? bar_of(settled, counts.total) : bar_of(0, 0)
+
+	return `${STATE_ICONS.merged} ${tally} ${bar}`
+}
+
+function progress_parts(counts: BoardCounts, header: BoardHeader): Array<string> {
+	const is_read = is_plan_read(header)
+
+	return [
+		`${tally_part(counts, is_read)}${is_read ? plus_of(counts, header) : ''}`,
+		`${STATE_ICONS.running} ${String(counts.running)}`,
+		`${STATE_ICONS.waiting} ${is_read ? String(counts.remaining) : UNKNOWN}`,
+		`${STATE_ICONS.parked} ${String(counts.parked)}`,
+	]
+}
+
+// The run's mark and its progress, then how fresh its stream is and what its plan read is doing.
+function state_line(counts: BoardCounts, header: BoardHeader): string {
+	const mark = mark_of(header, counts.running)
+	const parts = [
+		run_part(mark, header.spinner),
+		...progress_parts(counts, header),
+		heartbeat_part(header, mark),
+		loading_part(header),
+		plan_warning(header),
+	]
+
+	return parts.filter((part) => part !== undefined).join(GAP)
+}
+
+function idle_line(idle: IdleWindow, now_ms: number): string {
+	const ending = idle.bound === 'idle' ? WORDS.idle_end_idle : WORDS.idle_end_run
+	const left = `${elapsed_of(idle.until_ms - now_ms)} ${WORDS.idle_left}`
+	const until = `${WORDS.idle_until} ${clock_of(idle.until_ms)} (${left}) → ${ending}`
+	const next_check = `${WORDS.next_check} ${clock_of(backlog_idle.next_check_ms(idle))}`
+
+	return `${INDENT}${RUN_MARKS.idle.glyph} ${until} · ${next_check}`
+}
+
+// The wait, under the header's blank line, drawn only while it is what the run is doing: no child
+// running and the run not ended. The children running are the run's own, read
+// locally, so a board still waiting on GitHub never draws a running run as waiting.
+function idle_lines(header: BoardHeader): Array<string> {
+	const { idle, is_stopped } = header.activity
+
+	if (is_stopped || idle === undefined || counts_of(layout_of(header)).running > 0) return []
+
+	return ['', idle_line(idle, header.now_ms)]
+}
+
+// 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
+
+	if (machine === undefined || header.form === 'screen') return machine
+
+	return { ...machine, cpu_percent: undefined, swap_mb_per_s: undefined }
+}
+
+// The machine before a gauge could be read: each gauge's icon, its figure unknown, apart as the gauges.
+const MACHINE_UNKNOWN = [HEADER_ICONS.cpu, HEADER_ICONS.memory, HEADER_ICONS.swap]
+	.map((icon) => `${icon} ${UNKNOWN}`)
+	.join(GAP)
+
+// The time, then the machine the run is on.
+function clock_line(header: BoardHeader): string {
+	const machine = run_board_machine.line_of(machine_of(header)) ?? MACHINE_UNKNOWN
+
+	return [...time_parts(header), machine].join(GAP)
+}
+
+// The run's state with its progress, then the time with the machine, in every state the board can be in.
+function header_lines(header: BoardHeader): Array<string> {
+	return [state_line(counts_of(layout_of(header)), header), clock_line(header)]
+}
+
+const run_board_header = { counts_of, header_lines, idle_lines, is_plan_read }
+
+export { run_board_header }
+export type { BoardCounts, BoardForm, BoardHeader }

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

@@ -0,0 +1,35 @@
+import {
+	BREAKING_CHANGE_LABEL,
+	BUG_LABEL,
+	BUGFIX_LABEL,
+	ENHANCEMENT_LABEL,
+	has_label_name,
+} from '#scripts/issue/issue-labels'
+import type { FiledKind } from '#scripts/run/event/run-event-filed'
+
+// The release category a row is drawn with (joshuafolkken/kit#3577): the categories
+// `.github/release.yml` sorts a change into, in its order, each with every label that places an issue
+// there. An issue with labels from several takes the first, as the release notes do; one with none is
+// an Other Change and draws no kind.
+
+const SEMVER_MAJOR_LABEL = 'Semver-Major'
+const SEMVER_MINOR_LABEL = 'Semver-Minor'
+
+const RELEASE_KINDS: ReadonlyArray<readonly [FiledKind, ReadonlyArray<string>]> = [
+	['breaking-change', [BREAKING_CHANGE_LABEL, SEMVER_MAJOR_LABEL]],
+	['enhancement', [ENHANCEMENT_LABEL, SEMVER_MINOR_LABEL]],
+	['bug', [BUGFIX_LABEL, BUG_LABEL]],
+]
+
+// The kinds in the release notes' order — the order a legend names them in.
+const KIND_ORDER: ReadonlyArray<FiledKind> = RELEASE_KINDS.map(([kind]) => kind)
+
+function kind_of(labels: ReadonlyArray<string> | undefined): FiledKind | undefined {
+	if (labels === undefined) return undefined
+
+	return RELEASE_KINDS.find(([, names]) => names.some((name) => has_label_name(labels, name)))?.[0]
+}
+
+const run_board_kind = { KIND_ORDER, kind_of }
+
+export { run_board_kind }