@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/run/board/run-board-render-legend.ts

@@ -0,0 +1,82 @@
+import { styleText } from 'node:util'
+import type { FiledKind } from '#scripts/run/event/run-event-filed'
+import { run_board_kind } from './run-board-kind'
+import { run_board_labels, type Words } from './run-board-labels'
+import type { BoardRow } from './run-board-layout'
+import type { BoardNote } from './run-board-notes'
+import { run_board_phase } from './run-board-phase'
+import { run_board_render_notes } from './run-board-render-notes'
+import type { ItemState } from './run-board-status'
+
+// The legend at the foot of `run:board`: the symbols named once, so a row carries only what differs
+// between rows. Drawn apart from the rows, which tell it the icons they lead with.
+
+const { FILED_KIND_ICONS, KIND_WORDS, PHASE_ICONS, PHASE_WORDS, STATE_ICONS, WAITS_ICON, WORDS } =
+	run_board_labels
+const GAP = '  '
+
+// Every phase a run passes through, in the track's own order and whatever is on screen: a row's phase
+// moves between redraws, so fixed lines keep each icon where the eye last found it — six to a line, so
+// the twelve fit a narrow pane.
+const PHASES_PER_LINE = 6
+const PHASE_ENTRIES = run_board_phase.PHASES.map(
+	(phase) => `${PHASE_ICONS[phase]} ${WORDS[PHASE_WORDS[phase]]}`,
+)
+const PHASE_LEGEND = Array.from(
+	{ length: Math.ceil(PHASE_ENTRIES.length / PHASES_PER_LINE) },
+	(_, line) => PHASE_ENTRIES.slice(line * PHASES_PER_LINE, (line + 1) * PHASES_PER_LINE).join(GAP),
+)
+
+// The row states the legend can name, in its order, each with its word.
+const STATE_LEGEND: ReadonlyArray<readonly [ItemState, keyof Words]> = [
+	['merged', 'merged'],
+	['parked', 'parked'],
+	['done', 'done'],
+	['running', 'in_progress'],
+	['stopped', 'stopped'],
+	['waiting', 'waiting'],
+	['human', 'decision'],
+]
+
+// The states some row on screen leads with (`drawn`) — a running row leads with its phase, so 🔄 is
+// named only while a row draws it.
+function state_legend(drawn: ReadonlySet<string>): Array<string> {
+	return STATE_LEGEND.filter(([state]) => drawn.has(STATE_ICONS[state])).map(
+		([state, word]) => `${STATE_ICONS[state]} ${WORDS[word]}`,
+	)
+}
+
+// The release kinds the rows draw (joshuafolkken/kit#3577), in the release notes' order.
+function kinds_of(rows: ReadonlyArray<BoardRow>): Array<FiledKind> {
+	const drawn = new Set(rows.map((row) => row.kind))
+
+	return run_board_kind.KIND_ORDER.filter((kind) => drawn.has(kind))
+}
+
+function waits_legend(rows: ReadonlyArray<BoardRow>): Array<string> {
+	return rows.some((row) => row.waits.length > 0) ? [`${WAITS_ICON} ${WORDS.waits}`] : []
+}
+
+// The phases on their lines and what the screen draws on one more, drawn only when it names something.
+// The header's gauges and marks read by their place, so the legend leaves them.
+// `drawn` is the icons the rows lead with.
+function legend_of(
+	rows: ReadonlyArray<BoardRow>,
+	drawn: ReadonlySet<string>,
+	notes: ReadonlyArray<BoardNote>,
+): Array<string> {
+	const kinds = kinds_of(rows)
+	const kind_icons = kinds.map((kind) => FILED_KIND_ICONS[kind])
+	const notes_named = run_board_render_notes.notes_legend(notes, new Set([...drawn, ...kind_icons]))
+	const kind_named = kinds.map((kind) => `${FILED_KIND_ICONS[kind]} ${WORDS[KIND_WORDS[kind]]}`)
+	const shown = [...state_legend(drawn), ...kind_named, ...waits_legend(rows), ...notes_named]
+	const lines = shown.length === 0 ? PHASE_LEGEND : [...PHASE_LEGEND, shown.join(GAP)]
+
+	return lines.map((line) => styleText('dim', line))
+}
+
+const run_board_render_legend = {
+	legend_of,
+}
+
+export { run_board_render_legend }

package/scripts/run/board/run-board-render-notes.ts

@@ -0,0 +1,77 @@
+import { run_board_kind } from './run-board-kind'
+import { run_board_labels, type Words } from './run-board-labels'
+import type { BoardNote } from './run-board-notes'
+
+// The findings section at the foot of `run:board` and the part of the legend that names its symbols.
+// A finding is read to the minute, and the legend names only the kinds the section draws — the rows'
+// legend's rule — so a section of filed Issues alone is not explained with 💬 and 💤.
+
+const { FILED_KIND_ICONS, KIND_WORDS, NOTES_ICON, NOTE_ICONS, STATE_ICONS, WORDS, minute_of } =
+	run_board_labels
+const NOTE_LIMIT = 6
+const GAP = '  '
+const INDENT = '  '
+const NUMBER_PLACEHOLDER = '{n}'
+
+type Link = (reference: string) => string
+
+// The icons the legend can name, in its order, each with its word — a filed kind's the rows' own
+// (joshuafolkken/kit#3577), so one icon is never named with two words.
+const NOTE_LEGEND: ReadonlyArray<readonly [string, keyof Words]> = [
+	...run_board_kind.KIND_ORDER.map((kind) => [FILED_KIND_ICONS[kind], KIND_WORDS[kind]] as const),
+	[NOTE_ICONS.filed, 'filed'],
+	[NOTE_ICONS.park, 'parked'],
+	[NOTE_ICONS.note, 'note'],
+]
+
+function note_icon(note: BoardNote): string {
+	if (note.is_decision) return STATE_ICONS.human
+
+	return note.filed_kind === undefined ? NOTE_ICONS[note.kind] : FILED_KIND_ICONS[note.filed_kind]
+}
+
+function found_of(note: BoardNote, link: Link): string {
+	if (note.found_during === undefined) return ''
+
+	return WORDS.found_during.split(NUMBER_PLACEHOLDER).join(link(note.found_during))
+}
+
+// Where the legend names the symbols a note leads with its icon alone; where no legend is drawn it
+// keeps the kind's word.
+function note_text(note: BoardNote, has_legend: boolean, link: Link): string {
+	const kind = has_legend ? undefined : WORDS[note.kind]
+	const issue = note.issue === undefined ? undefined : link(note.issue)
+	const lead = [note_icon(note), minute_of(note.at_ms), issue, kind]
+		.filter((part) => part !== undefined)
+		.join(' ')
+
+	return `${INDENT}${lead}${GAP}${note.text}${found_of(note, link)}`
+}
+
+// The newest few, so the section never pushes the plan off the screen; the frame counts the rest
+// together with any it cuts to fit. Their numbers go through the board's `header.link`, so they open
+// their GitHub issue as the plan's rows do.
+function note_lines(
+	notes: ReadonlyArray<BoardNote>,
+	has_legend: boolean,
+	link: Link,
+): Array<string> {
+	return notes.slice(0, NOTE_LIMIT).map((note) => note_text(note, has_legend, link))
+}
+
+// 📌 while the section is on screen, then each kind a drawn line leads with —
+// one the rows' legend already names (`named`) is not named twice.
+function notes_legend(notes: ReadonlyArray<BoardNote>, named: ReadonlySet<string>): Array<string> {
+	if (notes.length === 0) return []
+
+	const drawn = new Set(notes.slice(0, NOTE_LIMIT).map((note) => note_icon(note)))
+	const kinds = NOTE_LEGEND.filter(([icon]) => drawn.has(icon) && !named.has(icon)).map(
+		([icon, word]) => `${icon} ${WORDS[word]}`,
+	)
+
+	return [`${NOTES_ICON} ${WORDS.notes}`, ...kinds]
+}
+
+const run_board_render_notes = { NOTE_LIMIT, note_lines, notes_legend }
+
+export { run_board_render_notes }

package/scripts/run/board/run-board-render-slot.ts

@@ -0,0 +1,50 @@
+import { run_board_fit } from './run-board-fit'
+import type { BoardRow } from './run-board-layout'
+import type { ItemState } from './run-board-status'
+import type { LaneUsages } from './run-board-usage'
+import { run_board_usage_text } from './run-board-usage-text'
+
+// The column between a row's time and its track, one width on every row it is drawn on, so every
+// track starts in one column: a running row's CPU and memory, a finished row's finish time, and
+// blanks on any other row.
+
+const { finish_of, text_of } = run_board_usage_text
+const FINISHED: ReadonlySet<ItemState> = new Set(['merged', 'done'])
+const BLANK = ' '
+
+// What one frame's column is drawn from: each lane's usage, and the running rows the frame draws —
+// counted once a frame, the count a lane's share of the machine is divided by.
+interface UsageSlot {
+	usages: LaneUsages
+	running: number
+}
+
+function usage_slot(rows: ReadonlyArray<BoardRow>, usages: LaneUsages): UsageSlot {
+	return { usages, running: rows.filter((row) => row.state === 'running').length }
+}
+
+function slot_of(row: BoardRow, slot: UsageSlot, now_ms: number): string | undefined {
+	if (row.state === 'running') return text_of(slot.usages.get(row.number), slot.running)
+	if (FINISHED.has(row.state)) return finish_of(row.status?.ended_ms, now_ms)
+
+	return undefined
+}
+
+// The widest any row of the frame draws, as the terminal counts it — an emoji takes two columns.
+function column_width(rows: ReadonlyArray<BoardRow>, slot: UsageSlot, now_ms: number): number {
+	const widths = rows.map((row) => run_board_fit.width_of(slot_of(row, slot, now_ms) ?? ''))
+
+	return Math.max(0, ...widths)
+}
+
+// A row's column padded with blanks to the frame's width.
+function cell_of(text: string | undefined, width: number): string {
+	const drawn = text ?? ''
+
+	return `${drawn}${BLANK.repeat(Math.max(0, width - run_board_fit.width_of(drawn)))}`
+}
+
+const run_board_render_slot = { cell_of, column_width, slot_of, usage_slot }
+
+export { run_board_render_slot }
+export type { UsageSlot }

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

@@ -0,0 +1,407 @@
+import {
+	run_board_fit,
+	type FrameParts,
+	type NotesPart,
+	type PlanLine,
+	type PlanSection,
+	type RowYield,
+	type TerminalSize,
+	type YieldStage,
+} from './run-board-fit'
+import { run_board_header, type BoardHeader } from './run-board-header'
+import { run_board_labels } from './run-board-labels'
+import {
+	run_board_layout,
+	type BoardLayout,
+	type BoardRow,
+	type WaveEntry,
+} from './run-board-layout'
+import type { BoardNote } from './run-board-notes'
+import type { Phase } from './run-board-phase'
+import { run_board_render_legend } from './run-board-render-legend'
+import { run_board_render_notes } from './run-board-render-notes'
+import { run_board_render_slot, type UsageSlot } from './run-board-render-slot'
+import type { ItemState } from './run-board-status'
+import { run_board_track } from './run-board-track'
+
+// The whole `run:board` screen as lines — pure, so what a person sees is tested apart from the
+// terminal. The header says where the run is; the sections below it follow the plan's order; the
+// findings at the bottom are what the run would otherwise have said in no chat anyone reads. A section
+// is a rule rather than a heading, and the legend at the foot names the symbols, so a row carries only
+// what differs between rows. Every word is English whatever the session language: one set of words
+// reads the same on every board.
+
+const { FILED_KIND_ICONS, KIND_BLANK, NOTES_ICON, PHASE_ICONS, STATE_ICONS, WAITS_ICON, WORDS } =
+	run_board_labels
+const { clock_of, elapsed_of } = run_board_labels
+const { NOTE_LIMIT } = run_board_render_notes
+const { cell_of, column_width, slot_of, usage_slot } = run_board_render_slot
+// The columns a terminal row gives its title: a longer one is cut to an ellipsis.
+const TITLE_LIMIT = 48
+const ELLIPSIS = '…'
+const GAP = '  '
+const INDENT = '  '
+const BRANCH = '     ├ '
+const LAST_BRANCH = '     └ '
+const RULE = '─'
+const RULE_LEAD = `${RULE}${RULE}`
+const RULE_WIDTH = 50
+
+// The live terminal a frame is kept within, and the footer the frame ends on and gives way first;
+// neither for a frame that is not redrawn in place.
+interface FrameBounds {
+	size?: TerminalSize | undefined
+	footer?: ReadonlyArray<string> | undefined
+}
+
+interface BoardView extends FrameBounds {
+	header: BoardHeader
+	notes: ReadonlyArray<BoardNote>
+	// The session a stopped run resumes from.
+	resume?: string | undefined
+}
+
+// What every row of one frame is drawn with: the header, how wide the time column is, so a three-digit
+// `125:30` and a `00:42` end in the same column, and each lane's usage where its column is drawn, with
+// the column's width.
+interface RowFrame {
+	header: BoardHeader
+	time_width: number
+	usage: UsageSlot | undefined
+	slot_width: number
+}
+
+// A title cut to the title column, so every time after it starts in one column.
+function title_of(title = ''): string {
+	return title.length > TITLE_LIMIT ? `${title.slice(0, TITLE_LIMIT - 1)}${ELLIPSIS}` : title
+}
+
+// A row drawn before the plan is read has no title yet, and says so.
+function row_title(row: BoardRow, header: BoardHeader): string | undefined {
+	if (row.title !== undefined || run_board_header.is_plan_read(header)) return row.title
+
+	return ELLIPSIS
+}
+
+// A running row runs until now; a settled one until its recorded end. A child settled from the open
+// listing has none, so it draws no time rather than one that keeps counting.
+function end_of(row: BoardRow, now_ms: number): number | undefined {
+	return row.state === 'running' ? now_ms : row.status?.ended_ms
+}
+
+// How long a row has run: a running one until now, a settled one its whole span.
+function elapsed_ms(row: BoardRow, now_ms: number): number | undefined {
+	const started = row.status?.started_ms
+	const ended = end_of(row, now_ms)
+
+	if (started === undefined || ended === undefined) return undefined
+
+	return ended - started
+}
+
+function time_of(row: BoardRow, now_ms: number): string | undefined {
+	const elapsed = elapsed_ms(row, now_ms)
+
+	return elapsed === undefined ? undefined : elapsed_of(elapsed)
+}
+
+// The phases a row's track draws — every one the child passed while running, kept once it settles.
+function drawn_phases(row: BoardRow): ReadonlyArray<Phase> {
+	return row.status?.track ?? []
+}
+
+// A row's phases as its track, drawn last: it grows with every round, so the
+// columns before it stay where they are whatever its length. A settled row's ends on its state icon.
+function track_text(row: BoardRow): string | undefined {
+	const phases = drawn_phases(row)
+
+	return phases.length === 0 ? undefined : run_board_track.track_of(phases, row.state)
+}
+
+function waits_of(row: BoardRow, header: BoardHeader): string | undefined {
+	if (row.waits.length === 0) return undefined
+
+	return `${WAITS_ICON} ${row.waits.map((reference) => header.link(reference)).join(', ')}`
+}
+
+// The title is padded to the title column where a time or the usage column follows it, so the times
+// form one column; a row with no time draws blanks in its place before the usage column.
+function timed_parts(
+	row: BoardRow,
+	frame: RowFrame,
+	is_slotted: boolean,
+): Array<string | undefined> {
+	const time = time_of(row, frame.header.now_ms)
+
+	const title = title_of(row_title(row, frame.header))
+
+	if (time === undefined && !is_slotted) return [title]
+
+	return [title.padEnd(TITLE_LIMIT), (time ?? '').padStart(frame.time_width)]
+}
+
+// A running row leads with the icon of the phase it is in now — the rightmost
+// icon of its track — and with 🔄 while its track draws none yet.
+function state_icon(row: BoardRow): string {
+	const current = row.state === 'running' ? drawn_phases(row).at(-1) : undefined
+
+	return current === undefined ? STATE_ICONS[row.state] : PHASE_ICONS[current]
+}
+
+// A running row turns the spinner in the first column of its indent where the header has one, so its
+// title starts in the same column as every other row's.
+function indent_of(prefix: string, row: BoardRow, header: BoardHeader): string {
+	if (row.state !== 'running' || header.spinner === undefined) return prefix
+
+	return `${header.spinner}${prefix.slice(1)}`
+}
+
+// A row's usage column where the frame draws one, padded to one width on every row so every track
+// starts in one column. A plan row the run has not touched has no time, usage or track to align, so it
+// draws none and what it waits on stays beside its title.
+function cell_text(row: BoardRow, frame: RowFrame): string | undefined {
+	const { usage, slot_width } = frame
+
+	if (usage === undefined || slot_width === 0 || row.status === undefined) return undefined
+
+	return cell_of(slot_of(row, usage, frame.header.now_ms), slot_width)
+}
+
+function joined(parts: ReadonlyArray<string | undefined>): string {
+	return parts.filter((part) => part !== undefined && part !== '').join(GAP)
+}
+
+// The release kind's icon between the number and the title, one space either side; a row with no title
+// ends at its icon, so what follows keeps its usual gap.
+function lead_of(row: BoardRow, header: BoardHeader, title: string): string {
+	const kind = row.kind === undefined ? KIND_BLANK : FILED_KIND_ICONS[row.kind]
+	const lead = `${state_icon(row)} ${header.link(String(row.number))} ${kind}`
+
+	return title === '' ? lead : `${lead} ${title}`
+}
+
+// A row up to its usage column — the columns that stay where they are whatever the track's length.
+function head_text(row: BoardRow, frame: RowFrame): string {
+	const cell = cell_text(row, frame)
+	const [title = '', ...time] = timed_parts(row, frame, cell !== undefined)
+
+	return joined([lead_of(row, frame.header, title), ...time, cell])
+}
+
+// Every row carries its state's icon, a waiting one ⏳ too; a row with nothing
+// after its padded columns ends where its text does.
+function row_text(row: BoardRow, frame: RowFrame): string {
+	return joined([head_text(row, frame), track_text(row), waits_of(row, frame.header)]).trimEnd()
+}
+
+// The stage each state's row gives way in when the pane is short.
+const YIELD_STAGES: Readonly<Record<ItemState, YieldStage>> = {
+	merged: 'finished',
+	done: 'finished',
+	waiting: 'pending',
+	human: 'pending',
+	parked: 'parked',
+	stopped: 'parked',
+	running: 'running',
+}
+
+// A running row is as old as its start; a settled one as its end, or its start where it has none.
+function aged_ms(row: BoardRow): number | undefined {
+	const started = row.status?.started_ms
+
+	return row.state === 'running' ? started : (row.status?.ended_ms ?? started)
+}
+
+function yield_of(row: BoardRow): RowYield {
+	return { stage: YIELD_STAGES[row.state], at_ms: aged_ms(row) }
+}
+
+// A plan line that draws one issue row, and one that draws none — a blank, a rule, an epic's own line.
+function row_line(prefix: string, row: BoardRow, frame: RowFrame): PlanLine {
+	const text = `${indent_of(prefix, row, frame.header)}${row_text(row, frame)}`
+
+	return { text, row: yield_of(row) }
+}
+
+function bare(text: string): PlanLine {
+	return { text, row: undefined }
+}
+
+function epic_lines(entry: Extract<WaveEntry, { kind: 'epic' }>, frame: RowFrame): Array<PlanLine> {
+	const last = entry.rows.length - 1
+	const children = entry.rows.map((row, index) =>
+		row_line(index === last ? LAST_BRANCH : BRANCH, row, frame),
+	)
+	const title = title_of(entry.title)
+	const number = frame.header.link(String(entry.epic))
+	const epic = title === '' ? number : `${number}${GAP}${title}`
+
+	return [bare(`${INDENT}📁 ${epic}`), ...children]
+}
+
+function entry_lines(entry: WaveEntry, frame: RowFrame): Array<PlanLine> {
+	if (entry.kind === 'row') return [row_line(INDENT, entry.row, frame)]
+
+	return epic_lines(entry, frame)
+}
+
+function rule_of(label: string): string {
+	return `${RULE_LEAD} ${label} `.padEnd(RULE_WIDTH, RULE)
+}
+
+function heading_lines(heading: string | undefined): Array<string> {
+	return heading === undefined ? [''] : ['', rule_of(heading)]
+}
+
+function plan_section(
+	heading: string | undefined,
+	lines: ReadonlyArray<PlanLine>,
+): Array<PlanSection> {
+	if (lines.length === 0) return []
+
+	return [{ head: heading_lines(heading), lines }]
+}
+
+function rows_section(
+	heading: string | undefined,
+	rows: ReadonlyArray<BoardRow>,
+	frame: RowFrame,
+): Array<PlanSection> {
+	return plan_section(
+		heading,
+		rows.map((row) => row_line(INDENT, row, frame)),
+	)
+}
+
+// The time column's width: the widest time any active row draws in this frame.
+function time_width(header: BoardHeader): number {
+	const times = (header.layout?.active ?? []).map((row) => time_of(row, header.now_ms) ?? '')
+
+	return Math.max(0, ...times.map((time) => time.length))
+}
+
+// Whether every row's usage column still fits one terminal line — measured as the deepest, an epic's
+// child — where a frame is kept within a terminal. The track after it is left out: it grows without
+// bound, so one long history would otherwise take the usage column off every row.
+function is_usage_fitting(
+	rows: ReadonlyArray<BoardRow>,
+	frame: RowFrame,
+	size: TerminalSize | undefined,
+): boolean {
+	if (size === undefined) return true
+
+	return rows.every(
+		(row) => run_board_fit.height_of(`${BRANCH}${head_text(row, frame)}`, size.columns) === 1,
+	)
+}
+
+// The usage column is drawn on every row or on none: a pane too narrow for it on any row draws it on
+// none — a finish time with it.
+function frame_of(
+	header: BoardHeader,
+	layout: BoardLayout,
+	size: TerminalSize | undefined,
+): RowFrame {
+	const rows = run_board_layout.rows_of(layout)
+	const usage = header.usages === undefined ? undefined : usage_slot(rows, header.usages)
+	const frame = {
+		header,
+		time_width: time_width(header),
+		usage,
+		slot_width: usage === undefined ? 0 : column_width(rows, usage, header.now_ms),
+	}
+
+	return is_usage_fitting(rows, frame, size) ? frame : { ...frame, usage: undefined }
+}
+
+function plan_sections(header: BoardHeader, size: TerminalSize | undefined): Array<PlanSection> {
+	const { layout } = header
+
+	if (layout === undefined) return []
+
+	const frame = frame_of(header, layout, size)
+	const waves = layout.waves.flatMap((wave, index) =>
+		plan_section(
+			String(index + 1),
+			wave.flatMap((entry) => entry_lines(entry, frame)),
+		),
+	)
+
+	return [
+		...rows_section(undefined, layout.active, frame),
+		...waves,
+		...rows_section(STATE_ICONS.human, layout.people, frame),
+		...rows_section(WAITS_ICON, layout.unreached, frame),
+	]
+}
+
+// The findings under a rule, led by 📌 where a legend names it and by its word where none does, and how
+// many more there are, so the section never pushes the plan off the screen.
+function notes_part(notes: ReadonlyArray<BoardNote>, header: BoardHeader): NotesPart {
+	const has_legend = header.layout !== undefined
+	const lines = run_board_render_notes.note_lines(notes, has_legend, header.link)
+	const label = has_legend ? NOTES_ICON : WORDS.notes
+
+	return { head: heading_lines(label), lines, hidden: notes.length - lines.length }
+}
+
+// The command that resumes a stopped run's session, under the header where the person looks first.
+function resume_lines(resume: string | undefined): Array<string> {
+	if (resume === undefined) return []
+
+	return ['', `${STATE_ICONS.human} ${WORDS.resume}${GAP}claude --resume ${resume}`]
+}
+
+// No legend is drawn before a plan is read: there are no rows whose symbols it would name.
+function legend_lines(header: BoardHeader, notes: ReadonlyArray<BoardNote>): Array<string> {
+	const { layout } = header
+
+	if (layout === undefined) return []
+
+	const rows = run_board_layout.rows_of(layout)
+	const drawn = new Set(rows.map((row) => state_icon(row)))
+
+	return ['', ...run_board_render_legend.legend_of(rows, drawn, notes)]
+}
+
+// A live frame is kept within its terminal; any other is drawn whole.
+function bounded(parts: FrameParts, bounds: FrameBounds): Array<string> {
+	const { size } = bounds
+
+	return size === undefined ? run_board_fit.whole(parts) : run_board_fit.fit(parts, size)
+}
+
+function render(view: BoardView): Array<string> {
+	const { header, notes } = view
+	const above = [
+		...run_board_header.header_lines(header),
+		...resume_lines(view.resume),
+		...run_board_header.idle_lines(header),
+	]
+	const parts = {
+		above,
+		plan: plan_sections(header, view.size),
+		notes: notes_part(notes, header),
+		legend: legend_lines(header, notes),
+		footer: view.footer ?? [],
+	}
+
+	return bounded(parts, view)
+}
+
+function render_no_run(now_ms: number, bounds: FrameBounds = {}): Array<string> {
+	const above = [`■ backlogrun${GAP}${WORDS.no_run}${GAP}${clock_of(now_ms)}`]
+	const notes = { head: [], lines: [], hidden: 0 }
+
+	return bounded({ above, plan: [], notes, legend: [], footer: bounds.footer ?? [] }, bounds)
+}
+
+const run_board_render = {
+	NOTE_LIMIT,
+	TITLE_LIMIT,
+	render,
+	render_no_run,
+}
+
+export { run_board_render }
+export type { BoardView, FrameBounds }

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

@@ -0,0 +1,17 @@
+import type { NamedPlan } from '#scripts/backlog/backlog-plan'
+import { run_invocation } from '#scripts/run/run-invocation'
+
+// Which plan a run covers, read off the invocation its carry record kept, so the board draws only what
+// the run was asked to do. The invocation is parsed through the grammar the run itself uses, into the
+// shape `backlog:plan` renders a named prefix from, so the board and the plan agree on it.
+// An invocation that does not parse names nothing, which is the bare `backlogrun`'s plan.
+function scope_of(invocation: string): NamedPlan {
+	return {
+		issues: run_invocation.issue_numbers(invocation) ?? [],
+		only: run_invocation.has_only(invocation),
+	}
+}
+
+const run_board_scope = { scope_of }
+
+export { run_board_scope }

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

@@ -0,0 +1,43 @@
+// How `josh run:board` puts its frames on the terminal. A board kept open
+// draws on the alternate screen, as `top` and `less` do: clearing the normal screen pushes every
+// redraw into the scrollback, so the board would grow like a log. Leaving restores the screen and the
+// cursor the person had. One frame — `--once`, or a pipe — draws no screen control; a terminal still
+// gets its colors.
+
+type ScreenMode = 'live' | 'plain'
+
+// The control bytes written on entering, before each frame, and on leaving.
+interface Screen {
+	enter: string
+	frame: string
+	leave: string
+}
+
+const ESC = '\u{1B}['
+const ALTERNATE_SCREEN_ON = `${ESC}?1049h`
+const ALTERNATE_SCREEN_OFF = `${ESC}?1049l`
+const CURSOR_HIDE = `${ESC}?25l`
+const CURSOR_SHOW = `${ESC}?25h`
+const CURSOR_HOME = `${ESC}H`
+const ERASE_BELOW = `${ESC}J`
+
+const LIVE: Screen = {
+	enter: `${ALTERNATE_SCREEN_ON}${CURSOR_HIDE}`,
+	frame: `${CURSOR_HOME}${ERASE_BELOW}`,
+	leave: `${CURSOR_SHOW}${ALTERNATE_SCREEN_OFF}`,
+}
+
+const PLAIN: Screen = { enter: '', frame: '', leave: '' }
+
+function mode_of(options: { is_tty: boolean; is_once: boolean }): ScreenMode {
+	return options.is_tty && !options.is_once ? 'live' : 'plain'
+}
+
+function screen_of(mode: ScreenMode): Screen {
+	return mode === 'live' ? LIVE : PLAIN
+}
+
+const run_board_screen = { mode_of, screen_of }
+
+export { run_board_screen }
+export type { Screen, ScreenMode }