@joshuafolkken/kit 1.1387.0 → 1.1435.0

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 }

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

@@ -0,0 +1,234 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
+import { run_board_labels } from './run-board-labels'
+import type { LaneEvent } from './run-board-lane-event'
+import { run_board_operation, type Operation } from './run-board-operation'
+import type { SessionOperations } from './run-board-operation-read'
+import type { RunActivity } from './run-board-status'
+
+// The header's third line: what the run is doing now, as its kind, when it happened and its words.
+// Always one line while the stream holds an event — the newer of a running child's newest operation and
+// its newest event, or the newest operation of the session a stage is the work of, else the stage the
+// run is at, else how many children run, else how long it has watched, each of the last three with why;
+// an ended run keeps the newest thing it did. **An operation changes with every call a session makes**,
+// where a stage or a count stands for minutes. Every time is an event's or a call's own, so the line
+// never guesses one; the header ages it and draws it in its time column (joshuafolkken/kit#3767).
+
+const { KIND_BLANK, NOW_ICONS, PHASE_ICONS, STAGE_ICONS, STATE_ICONS, WORDS } = run_board_labels
+const { STAGE } = run_event_setup
+const REASON_SEPARATOR = ' — '
+const OPERATION_SEPARATOR = ' · '
+const WORD_SEPARATOR = ' '
+// The stages a session is at work on, and whose log says what it does. Every other stage is the
+// driver's or the supervisor's own step, which writes no log of calls.
+const STAGE_SESSIONS: Readonly<Partial<Record<string, 'owner' | 'judgment'>>> = {
+	[STAGE.PLANNING]: 'owner',
+	[STAGE.SESSION]: 'judgment',
+}
+
+interface NowRead {
+	now_ms: number
+	// Set once the run has ended: the newest event's age stops there.
+	ended_ms: number | undefined
+	activity: RunActivity
+	// The newest operation of each session of the run, `undefined` where none was read.
+	operations?: SessionOperations | undefined
+	// The issues of the children running now: a lane left by an earlier run is not this run's work.
+	children?: ReadonlySet<number> | undefined
+	running: number
+	// What the plan has left for the run, `undefined` until the plan is read.
+	waiting: number | undefined
+	// How many of those wait on a person.
+	people: number
+}
+
+interface NowLine {
+	// The kind's icon, drawn under the `⚡`.
+	icon: string
+	// The icon's word in the legend, `undefined` where the line's own words or the phase legend name it.
+	legend?: string | undefined
+	// How long ago what the line says happened — up to an ended run's end — `undefined` where no event
+	// gave it a time.
+	age_ms: number | undefined
+	text: string
+}
+
+// A line before it is aged: when what it says happened.
+type TimedLine = Omit<NowLine, 'age_ms'> & { since_ms: number | undefined }
+
+// What stands behind the pool once nothing runs: nothing, only what a person has to decide, or issues
+// the run cannot take yet.
+function pool_reason(waiting: number, people: number): string {
+	if (waiting === 0) return WORDS.pool_empty
+
+	return waiting === people
+		? `${String(waiting)} ${WORDS.on_person}`
+		: `${String(waiting)} ${WORDS.waiting}`
+}
+
+function running_of(running: number): string {
+	return `${String(running)} ${WORDS.in_progress}`
+}
+
+// Why the run is where it is: the children it runs, else what its plan has left. Nothing before the
+// plan is read.
+function reason_of(read: NowRead): string | undefined {
+	if (read.running > 0) return running_of(read.running)
+
+	return read.waiting === undefined ? undefined : pool_reason(read.waiting, read.people)
+}
+
+function with_reason(line: string, read: NowRead): string {
+	const reason = reason_of(read)
+
+	return reason === undefined ? line : `${line}${REASON_SEPARATOR}${reason}`
+}
+
+// The newest thing an ended run did.
+function latest_line(read: NowRead): TimedLine | undefined {
+	const { latest } = read.activity
+
+	if (latest === undefined) return undefined
+
+	return { icon: NOW_ICONS.ended, legend: WORDS.ended, since_ms: latest.at_ms, text: latest.text }
+}
+
+// A run with nothing running and at no stage is watching its pool, since the newest thing it did — a
+// stage it has left included, so a judgment session's minutes are not counted as watching.
+function watch_line(read: NowRead): TimedLine | undefined {
+	const { idle_ms } = read.activity
+
+	if (idle_ms === undefined) return undefined
+
+	return { icon: NOW_ICONS.watching, since_ms: idle_ms, text: with_reason(WORDS.watching, read) }
+}
+
+// `words`, then what the session did — words that end on a command or a path.
+function operated(words: string, operation: Operation): string {
+	return `${words}${OPERATION_SEPARATOR}${run_board_operation.words_of(operation)}`
+}
+
+function session_operation(read: NowRead, setup: string): Operation | undefined {
+	const session = STAGE_SESSIONS[setup]
+
+	return session === undefined ? undefined : read.operations?.[session]
+}
+
+// The newest operation of the session a stage is the work of. One older than the stage is an earlier
+// session's, or what the parent did before it — the watcher's log runs on across runs.
+function stage_operation(read: NowRead, setup: string): Operation | undefined {
+	const operation = session_operation(read, setup)
+
+	if (operation === undefined) return undefined
+
+	return operation.at_ms < (read.activity.setup_ms ?? 0) ? undefined : operation
+}
+
+// A stage's icon, keyed by its words before the issue a lane's stage names; a stage the board does not
+// know keeps the icon's columns blank, so its words start where every other line's do.
+function stage_icon(setup: string): string {
+	const known = Object.keys(STAGE_ICONS).find(
+		(words) => setup === words || setup.startsWith(`${words}${WORD_SEPARATOR}`),
+	)
+
+	return (known === undefined ? undefined : STAGE_ICONS[known]) ?? KIND_BLANK
+}
+
+// The stage, then what its session last did and when; the stage, since when the run has stood there
+// and why where no session is at work on it, or none could be read.
+function stage_line(read: NowRead, setup: string): TimedLine {
+	const operation = stage_operation(read, setup)
+	const icon = stage_icon(setup)
+
+	return operation === undefined
+		? { icon, since_ms: read.activity.setup_ms, text: with_reason(setup, read) }
+		: { icon, since_ms: operation.at_ms, text: operated(setup, operation) }
+}
+
+// A running child's words, named by its issue.
+function child_said(issue: number, words: string): string {
+	return `${issue_cite.plain(issue)}${OPERATION_SEPARATOR}${words}`
+}
+
+// What the running children's newest activity is read from: each session's newest operation and each
+// child's newest event, kept to the children named.
+interface ChildSources {
+	operations?: SessionOperations | undefined
+	lane_events?: ReadonlyMap<number, LaneEvent> | undefined
+	children?: ReadonlySet<number> | undefined
+}
+
+// The running children's newest operations, each named by its issue.
+function operation_lines(read: ChildSources): Array<TimedLine> {
+	const lanes = read.operations?.lanes.filter((lane) => read.children?.has(lane.issue)) ?? []
+
+	return lanes.map(({ issue, operation }) => ({
+		icon: NOW_ICONS.operation,
+		legend: WORDS.operation,
+		since_ms: operation.at_ms,
+		text: child_said(issue, run_board_operation.words_of(operation)),
+	}))
+}
+
+// The running children's newest events, each in its row's phase icon and its own words.
+function event_lines(read: ChildSources): Array<TimedLine> {
+	const events = [...(read.lane_events ?? [])]
+
+	return events
+		.filter(([issue]) => read.children?.has(issue))
+		.map(([issue, event]) => ({
+			icon: PHASE_ICONS[event.phase],
+			since_ms: event.at_ms,
+			text: child_said(issue, event.words),
+		}))
+}
+
+function newest_first(left: TimedLine, right: TimedLine): number {
+	return (right.since_ms ?? 0) - (left.since_ms ?? 0)
+}
+
+// The newest of the children's operations and events — an operation where the two are as new.
+// `undefined` where neither could be read. A row reads its own child's the same way
+// (joshuafolkken/kit#3769), so the header and the row never disagree on what is newest.
+function newest_of(sources: ChildSources): TimedLine | undefined {
+	return [...operation_lines(sources), ...event_lines(sources)].toSorted(newest_first).at(0)
+}
+
+// The running children's newest, or `undefined`, and the line counts the children instead.
+function child_line(read: NowRead): TimedLine | undefined {
+	const { operations, children, activity } = read
+
+	return newest_of({ operations, children, lane_events: activity.lane_events })
+}
+
+function quiet_line(read: NowRead): TimedLine | undefined {
+	if (read.running === 0) return watch_line(read)
+
+	return { icon: STATE_ICONS.running, since_ms: undefined, text: running_of(read.running) }
+}
+
+function timed_line(read: NowRead): TimedLine | undefined {
+	const { is_stopped, setup } = read.activity
+
+	if (is_stopped) return latest_line(read)
+	if (setup !== undefined) return stage_line(read, setup)
+
+	return child_line(read) ?? quiet_line(read)
+}
+
+// The line aged to now, or to an ended run's end: an age counting on after it would read as a hang.
+function line_of(read: NowRead): NowLine | undefined {
+	const line = timed_line(read)
+
+	if (line === undefined) return undefined
+
+	const { since_ms, ...rest } = line
+	const until_ms = read.ended_ms ?? read.now_ms
+
+	return { ...rest, age_ms: since_ms === undefined ? undefined : until_ms - since_ms }
+}
+
+const run_board_now = { line_of, newest_of }
+
+export { run_board_now }
+export type { ChildSources, NowLine, NowRead, TimedLine }

package/scripts/run/board/run-board-operation-read.ts

@@ -0,0 +1,75 @@
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { run_board_operation, type Operation } from './run-board-operation'
+
+// The disk half of the third line's operation: the end of each session's log, read every time the
+// board re-reads its run. **A fixed, small read**: a dispatch log grows to tens of megabytes and the
+// watcher's log across runs, while the board re-reads every five seconds. The newest call is nearly
+// always inside it; where one line is longer than the read, there is no operation and the line says
+// what it said before. Nothing here may fail — a log that is missing or unreadable is no operation.
+
+const TAIL_BYTES = 65_536
+
+// A session's log and the checkout its paths are drawn from.
+interface OperationSource {
+	log: string | undefined
+	root: string | undefined
+}
+
+interface LaneSource extends OperationSource {
+	issue: string
+}
+
+interface OperationSources {
+	lanes: ReadonlyArray<LaneSource>
+	// The parent session's transcript.
+	owner: OperationSource
+	// The watcher's log, which a judgment session appends to.
+	judgment: OperationSource
+}
+
+interface LaneOperation {
+	issue: number
+	operation: Operation
+}
+
+// The newest operation of every session the run may have at work; which of them is at work now is the
+// reader's to say.
+interface SessionOperations {
+	lanes: ReadonlyArray<LaneOperation>
+	owner: Operation | undefined
+	judgment: Operation | undefined
+}
+
+type ReadTail = (file_path: string, max_bytes: number) => string
+
+function operation_of(source: OperationSource, read_tail: ReadTail): Operation | undefined {
+	if (source.log === undefined) return undefined
+
+	try {
+		return run_board_operation.latest_of(read_tail(source.log, TAIL_BYTES), source.root)
+	} catch {
+		return undefined
+	}
+}
+
+function lane_operation(source: LaneSource, read_tail: ReadTail): Array<LaneOperation> {
+	const operation = operation_of(source, read_tail)
+
+	return operation === undefined ? [] : [{ issue: Number(source.issue), operation }]
+}
+
+function read(
+	sources: OperationSources,
+	read_tail: ReadTail = time_density_hook.read_tail,
+): SessionOperations {
+	return {
+		lanes: sources.lanes.flatMap((lane) => lane_operation(lane, read_tail)),
+		owner: operation_of(sources.owner, read_tail),
+		judgment: operation_of(sources.judgment, read_tail),
+	}
+}
+
+const run_board_operation_read = { TAIL_BYTES, read }
+
+export { run_board_operation_read }
+export type { LaneOperation, OperationSources, SessionOperations }

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

@@ -0,0 +1,150 @@
+import path from 'node:path'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// The newest thing a session did, read off the end of its log — a lane child's dispatch log, the
+// parent's transcript or the watcher's log, all one JSON object a line with the tool calls of an
+// `assistant` line under `message.content`. **Only what a machine decided is kept**: the tool's name
+// and what it was pointed at. The call's `description` is the session's own prose, in the session's
+// language, and the board is written in English.
+
+interface Operation {
+	// The tool's name: `Bash`, `Edit`, `Read`, …
+	kind: string
+	// The head of the command, or the file's path; `undefined` for a tool pointed at neither.
+	target: string | undefined
+	at_ms: number
+}
+
+// A command is cut here, so a long argument — or a value passed in one — is not drawn.
+const TARGET_LIMIT = 40
+const CUT_MARK = '…'
+const TOOL_USE = 'tool_use'
+// A line that holds no call is never parsed: one can be tens of thousands of characters long.
+const TOOL_USE_MARK = `"${TOOL_USE}"`
+const NEWLINE = '\n'
+// One variable set ahead of the command, with what parts it from the command: it carries a value,
+// never what the command does. The value is read as the shell reads one word — a quoted stretch with
+// its escapes and line breaks, a command run for its output, an escaped character, a plain one.
+const QUOTED = /"(?:[^"\\]|\\.)*"|'[^']*'/su
+const SUBSTITUTED = /\$\((?:[^()]|\([^()]*\))*\)|`[^`]*`/su
+const PLAIN = /\\.|[^\s"'`;&|()\\]/su
+const VALUE = `(?:${QUOTED.source}|${SUBSTITUTED.source}|${PLAIN.source})*`
+const ASSIGNMENT = new RegExp(String.raw`^\w+=${VALUE}(?:\s*(?:&&|;)\s*|\s+|$)`, 'su')
+// A variable still at the head once every readable one is gone: its value could not be read as one.
+const UNREAD_ASSIGNMENT = /^\w+=/u
+const SPACES = /\s+/gu
+// The printable ASCII a target begins with: what follows may be the session's own language.
+const ASCII_HEAD = /^[ -~]*/u
+
+// A call names its tool; every other block of a line — its text, its thinking — is not one.
+const CALL_SCHEMA = z.looseObject({
+	type: z.literal(TOOL_USE),
+	name: z.string(),
+	input: z.unknown(),
+})
+
+function is_dated(text: string): boolean {
+	return !Number.isNaN(Date.parse(text))
+}
+
+const MESSAGE_SCHEMA = z.looseObject({ content: z.array(z.unknown()) })
+const LINE_SCHEMA = z.looseObject({
+	timestamp: z.string().refine(is_dated),
+	message: MESSAGE_SCHEMA,
+})
+// An input that is no object reads as one pointed at nothing.
+const INPUT_SCHEMA = z
+	.looseObject({ command: z.string().optional(), file_path: z.string().optional() })
+	.catch({})
+
+type Call = z.infer<typeof CALL_SCHEMA>
+type Input = z.infer<typeof INPUT_SCHEMA>
+
+function ascii_head(text: string): string {
+	return (ASCII_HEAD.exec(text)?.[0] ?? '').trim()
+}
+
+function cut(text: string): string {
+	return text.length > TARGET_LIMIT ? `${text.slice(0, TARGET_LIMIT)}${CUT_MARK}` : text
+}
+
+// The command without every variable set ahead of it, one at a time.
+function without_assignments(command: string): string {
+	const rest = command.replace(ASSIGNMENT, '')
+
+	return rest === command ? command : without_assignments(rest)
+}
+
+// The first line of what the command runs, cut to the limit. A command whose variable cannot be read
+// to its end is drawn as nothing: a part of the value would stand where the command should.
+function command_target(command: string): string {
+	const [first = ''] = without_assignments(command.trim()).split(NEWLINE)
+	if (UNREAD_ASSIGNMENT.test(first)) return ''
+
+	return cut(ascii_head(first.replaceAll(SPACES, ' ')))
+}
+
+// The path from `root` down; a file outside it is drawn by its name alone, never by where it is.
+function path_target(file_path: string, root: string | undefined): string {
+	const relative = root === undefined ? undefined : path.relative(root, file_path)
+	const is_inside = relative !== undefined && !relative.startsWith('..') && relative !== ''
+
+	return ascii_head(is_inside ? relative : path.basename(file_path))
+}
+
+function shown(target: string): string | undefined {
+	return target === '' ? undefined : target
+}
+
+function target_of(input: Input, root: string | undefined): string | undefined {
+	if (input.command !== undefined) return shown(command_target(input.command))
+
+	return input.file_path === undefined ? undefined : shown(path_target(input.file_path, root))
+}
+
+function is_call(block: unknown): block is Call {
+	return CALL_SCHEMA.safeParse(block).success
+}
+
+function last_call(content: ReadonlyArray<unknown>): Call | undefined {
+	return content.findLast((block) => is_call(block))
+}
+
+// The last call a line holds, `undefined` for a line that is cut, is not JSON, or holds none.
+function line_operation(line: string, root: string | undefined): Operation | undefined {
+	const parsed = json_value.parse_with(line, LINE_SCHEMA)
+	const call = last_call(parsed?.message.content ?? [])
+
+	if (parsed === undefined || call === undefined) return undefined
+
+	return {
+		kind: call.name,
+		target: target_of(INPUT_SCHEMA.parse(call.input), root),
+		at_ms: Date.parse(parsed.timestamp),
+	}
+}
+
+// The newest operation in `tail` — the end of a log, whose first line is usually cut mid-way and so
+// reads as no call. `root` is the checkout the session works in, which its paths are drawn from.
+function latest_of(tail: string, root?: string): Operation | undefined {
+	const lines = tail.split(NEWLINE).filter((line) => line.includes(TOOL_USE_MARK))
+
+	for (const line of lines.toReversed()) {
+		const operation = line_operation(line, root)
+
+		if (operation !== undefined) return operation
+	}
+
+	return undefined
+}
+
+// The operation as the board writes it: `Bash pnpm josh test:related`, or the tool alone.
+function words_of(operation: Operation): string {
+	return operation.target === undefined ? operation.kind : `${operation.kind} ${operation.target}`
+}
+
+const run_board_operation = { TARGET_LIMIT, latest_of, words_of }
+
+export { run_board_operation }
+export type { Operation }

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

@@ -37,6 +37,7 @@ const { STAGE } = run_ship_stage
 const LAUNCHED_PHASE: Phase = 'investigate'
 const WORD_SEPARATOR = ' '
 const STAGE_INDEX = 1
+const PHASE_INDEX = 2
 
 // `josh ship`'s stages, each its own phase; the preflight is the ship's own start.
 const SHIP_PHASES: Readonly<Partial<Record<string, Phase>>> = {
@@ -64,6 +65,11 @@ function stage_word_of(event: RunEvent): string {
 	return event.text.split(WORD_SEPARATOR)[STAGE_INDEX] ?? ''
 }
 
+// The word after the stage — whether it started, succeeded, failed or was passed over.
+function phase_word_of(event: RunEvent): string {
+	return event.text.split(WORD_SEPARATOR)[PHASE_INDEX] ?? ''
+}
+
 // A stage marks its phase when it starts; its `done`, and one a resumed ship passed over, mark none.
 function ship_phase_of(event: RunEvent): Phase | undefined {
 	if (!run_event_stream.is_stage_start(event)) return undefined
@@ -79,6 +85,16 @@ function phase_of(event: RunEvent): Phase | undefined {
 	return KIND_PHASES[event.kind]
 }
 
+// The phase a `lane-phase` or `ship-stage` event's stage belongs to, started or not, so a line written
+// from it draws the icon its row's track does — a stage that failed is the ship's failure.
+function stage_phase_of(event: RunEvent): Phase | undefined {
+	if (event.kind === KIND.LANE_PHASE) return LANE_PHASES[stage_word_of(event)]
+
+	if (phase_word_of(event) === run_ship_stage.PHASE.FAILED) return 'failed'
+
+	return SHIP_PHASES[stage_word_of(event)]
+}
+
 // A failed ship keeps only its own start: everything after the newest `ship` folds into `failed`.
 function failed_after(track: ReadonlyArray<Phase>): Array<Phase> {
 	const ship = track.lastIndexOf('ship')
@@ -130,7 +146,16 @@ function replayed(track: ReadonlyArray<Phase>, attempt: ReadonlyArray<Phase>): A
 	return [...track.slice(0, start), ...(is_covered ? attempt : new Set([...current, ...attempt]))]
 }
 
-const run_board_phase = { LAUNCHED_PHASE, PHASES, attempt_of, history_after, phase_of, replayed }
+const run_board_phase = {
+	LAUNCHED_PHASE,
+	PHASES,
+	SHIP_PHASES,
+	attempt_of,
+	history_after,
+	phase_of,
+	replayed,
+	stage_phase_of,
+}
 
 export { run_board_phase }
 export type { Phase }