@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -0,0 +1,198 @@
+import { machine_capacity, type MachineSample } from '#scripts/gate/machine-capacity'
+import { run_board_labels, type Paint } from './run-board-labels'
+
+// The machine line of `run:board`: whether a quiet run is stuck or only slow on a machine that has
+// run out of room.
+//
+// **The reading is the gate's own** (`machine-capacity.ts`), so the board shows what the core budget
+// admits against. 🔥 is the busy share of the CPU between two samples; 🧠 the kernel's memory pressure,
+// never a GB figure that would disagree with Activity Monitor's "memory used"; 💾 how fast pages are
+// swapped, never how much swap is held — macOS grows its swap files, so a usage share reads near 100%
+// and the amount itself does no harm. A figure that needs two samples is not drawn on the first, and a
+// figure that could not be read is not drawn at all.
+//
+// **Each gauge is green, yellow or red**, the three Activity Monitor draws. 🧠 takes its color from
+// the kernel's pressure verdict, as Activity Monitor does, and from its thresholds only where no
+// verdict was read; 💾 takes no color until it swaps. The three are `GAUGE_SHADES`, so no terminal
+// palette draws them blue or orange.
+
+const { GAUGE_SHADES, HEADER_ICONS, bar_of, painted } = run_board_labels
+const PERCENT = 100
+const MS_PER_SECOND = 1000
+const PERCENT_WIDTH = '100%'.length
+const RATE_WIDTH = '3.1M/s'.length
+// Below this a rate keeps one decimal, so `0.4M/s` is not drawn as `0M/s`.
+const RATE_DECIMAL_BELOW = 10
+// The header's gap between its parts, the gauges' as well.
+const GAP = '  '
+
+// Where each gauge is full and where it turns yellow and red. **Provisional, not yet measured**: to
+// be tuned against a heavy run's readings.
+const CPU_YELLOW = 70
+const CPU_RED = 90
+const MEMORY_YELLOW = 70
+const MEMORY_RED = 85
+const SWAP_FULL_MB_PER_S = 20
+const SWAP_RED_MB_PER_S = 10
+
+type Alert = 'normal' | 'yellow' | 'red'
+
+// `kern.memorystatus_vm_pressure_level`'s verdicts.
+const PRESSURE_NORMAL = 1
+const PRESSURE_WARNING = 2
+const PRESSURE_CRITICAL = 4
+const PRESSURE_ALERTS: ReadonlyMap<number, Alert> = new Map([
+	[PRESSURE_NORMAL, 'normal'],
+	[PRESSURE_WARNING, 'yellow'],
+	[PRESSURE_CRITICAL, 'red'],
+])
+
+// One sample and the moment it was taken, so a rate is over the time that really passed.
+interface MachineMark {
+	sample: MachineSample
+	at_ms: number
+}
+
+interface MachineGauges {
+	cpu_percent: number | undefined
+	memory_percent: number | undefined
+	swap_mb_per_s: number | undefined
+	memory_pressure: number | undefined
+}
+
+interface GaugeSpec {
+	icon: string
+	// The done part's color below the yellow threshold; `undefined` leaves it the terminal's own.
+	normal: Paint | undefined
+	full: number
+	yellow: number
+	red: number
+	format: (value: number) => string
+}
+
+function percent_text(value: number): string {
+	return `${String(Math.round(value))}%`.padStart(PERCENT_WIDTH)
+}
+
+function rate_text(value: number): string {
+	const figure = value < RATE_DECIMAL_BELOW ? value.toFixed(1) : String(Math.round(value))
+
+	return `${figure}M/s`.padStart(RATE_WIDTH)
+}
+
+const SPECS = {
+	cpu: {
+		icon: HEADER_ICONS.cpu,
+		normal: GAUGE_SHADES.normal,
+		full: PERCENT,
+		yellow: CPU_YELLOW,
+		red: CPU_RED,
+		format: percent_text,
+	},
+	memory: {
+		icon: HEADER_ICONS.memory,
+		normal: GAUGE_SHADES.normal,
+		full: PERCENT,
+		yellow: MEMORY_YELLOW,
+		red: MEMORY_RED,
+		format: percent_text,
+	},
+	swap: {
+		icon: HEADER_ICONS.swap,
+		normal: undefined,
+		full: SWAP_FULL_MB_PER_S,
+		yellow: 1,
+		red: SWAP_RED_MB_PER_S,
+		format: rate_text,
+	},
+} as const satisfies Readonly<Record<string, GaugeSpec>>
+
+function cpu_percent(before: MachineMark | undefined, after: MachineMark): number | undefined {
+	if (before === undefined) return undefined
+
+	const share = machine_capacity.busy_share_between(before.sample.cpu, after.sample.cpu)
+
+	return share === undefined ? undefined : share * PERCENT
+}
+
+function memory_percent(sample: MachineSample): number | undefined {
+	const { available_mb } = sample.memory
+
+	return available_mb === undefined
+		? undefined
+		: PERCENT - (available_mb / sample.total_mb) * PERCENT
+}
+
+function swap_rate(before: MachineMark | undefined, after: MachineMark): number | undefined {
+	if (before === undefined) return undefined
+
+	const swapped = machine_capacity.swapped_between(
+		before.sample.memory.swapped_mb,
+		after.sample.memory.swapped_mb,
+	)
+	const seconds = (after.at_ms - before.at_ms) / MS_PER_SECOND
+
+	return swapped === undefined || seconds <= 0 ? undefined : swapped / seconds
+}
+
+function gauges_of(before: MachineMark | undefined, after: MachineMark): MachineGauges {
+	return {
+		cpu_percent: cpu_percent(before, after),
+		memory_percent: memory_percent(after.sample),
+		swap_mb_per_s: swap_rate(before, after),
+		memory_pressure: after.sample.memory.pressure_level,
+	}
+}
+
+function threshold_alert(value: number, spec: Pick<GaugeSpec, 'red' | 'yellow'>): Alert {
+	if (value >= spec.red) return 'red'
+
+	return value >= spec.yellow ? 'yellow' : 'normal'
+}
+
+// A pressure verdict the kernel gave decides the color; an unread or unknown one falls to the thresholds.
+function alert_of(spec: GaugeSpec, value: number, pressure: number | undefined): Alert {
+	const verdict = pressure === undefined ? undefined : PRESSURE_ALERTS.get(pressure)
+
+	return verdict ?? threshold_alert(value, spec)
+}
+
+// Icon, figure, then bar: the figure is what a person reads, and its fixed
+// width keeps every bar starting in one column. The bar stops full past `spec.full`; the figure still
+// says how far past, and takes the warning colors only, so a quiet machine's figures stay the terminal's
+// own.
+function gauge(spec: GaugeSpec, value: number | undefined, pressure?: number): string | undefined {
+	if (value === undefined) return undefined
+
+	const alert = alert_of(spec, value, pressure)
+	const warning = alert === 'normal' ? undefined : GAUGE_SHADES[alert]
+	const bar = bar_of(value, spec.full, undefined, warning ?? spec.normal)
+
+	return `${spec.icon} ${painted(warning, spec.format(value))} ${bar}`
+}
+
+// `undefined` when not one gauge could be read, so the header draws no line at all.
+function line_of(gauges: MachineGauges | undefined): string | undefined {
+	if (gauges === undefined) return undefined
+
+	const parts = [
+		gauge(SPECS.cpu, gauges.cpu_percent),
+		gauge(SPECS.memory, gauges.memory_percent, gauges.memory_pressure),
+		gauge(SPECS.swap, gauges.swap_mb_per_s),
+	].filter((part) => part !== undefined)
+
+	return parts.length === 0 ? undefined : parts.join(GAP)
+}
+
+const run_board_machine = {
+	CPU_YELLOW,
+	GAP,
+	MEMORY_YELLOW,
+	gauges_of,
+	line_of,
+	percent_text,
+	threshold_alert,
+}
+
+export { run_board_machine }
+export type { Alert, MachineGauges, MachineMark }

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

@@ -0,0 +1,103 @@
+import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import { run_event_filed, type FiledKind } from '#scripts/run/event/run-event-filed'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+
+// The board's findings section: what a run filed, what it parked and the
+// one-line observations it left, read off the event stream alone. A run started from the command line
+// says these in no chat a person reads, so the board is where they surface. Nothing is inferred from a
+// conversation log — an event that is not on the stream is not on the board.
+
+type NoteKind = 'filed' | 'park' | 'note'
+
+interface BoardNote {
+	kind: NoteKind
+	at_ms: number
+	// The issue the line is about: the filed Issue, the parked child, or the one a note names.
+	issue: string | undefined
+	text: string
+	// Whose work turned up a filed Issue: the lane child, else the Issue the branch names.
+	found_during?: string | undefined
+	// A filed Issue's classification, which its line leads with.
+	filed_kind?: FiledKind | undefined
+	// A park waiting on a person's decision, drawn apart from an ordinary park.
+	is_decision: boolean
+}
+
+const KIND = run_event_stream.EVENT_KIND
+// `#<N> parked`, `#<N> parked (<reason>)` and `#<N> waiting on #<M>` lose their leading number, so a
+// waiting park does not name its issue twice.
+const PARK_PREFIX = /^#\d+ (?:parked\s*)?/u
+const PARENTHESES = /^\((?<inner>.*)\)$/u
+
+function filed_note(event: RunEvent): BoardNote | undefined {
+	const filed = run_event_filed.parse(event.text)
+
+	if (filed === undefined) return undefined
+
+	return {
+		kind: 'filed',
+		at_ms: Date.parse(event.at),
+		issue: filed.reference.replace(/^#/u, ''),
+		text: filed.title,
+		found_during: filed.found_during,
+		filed_kind: filed.kind,
+		is_decision: false,
+	}
+}
+
+// The board's titles by issue number: the plan's listing with its closed children's.
+type Titles = ReadonlyMap<number, string>
+
+// `#<N> parked (needs-decision)` reads as the reason `needs-decision`; a bare park has none.
+function reason_of(event: RunEvent): string {
+	const rest = event.text.replace(PARK_PREFIX, '')
+
+	return PARENTHESES.exec(rest)?.groups?.['inner'] ?? rest
+}
+
+// The parked issue's title with its reason after it; before the plan is read there is no title, and
+// the reason alone is drawn.
+function park_text(title: string | undefined, reason: string): string {
+	if (title === undefined) return reason
+
+	return reason === '' ? title : `${title} (${reason})`
+}
+
+function park_note(event: RunEvent, titles: Titles): BoardNote {
+	const reason = reason_of(event)
+	const issue = run_event_scope.issue_named(event)
+	const title = issue === undefined ? undefined : titles.get(Number(issue))
+	const is_decision = reason.includes(NEEDS_DECISION_LABEL)
+
+	return {
+		kind: 'park',
+		at_ms: Date.parse(event.at),
+		issue,
+		text: park_text(title, reason),
+		is_decision,
+	}
+}
+
+function plain_note(event: RunEvent): BoardNote {
+	const issue = run_event_scope.issue_named(event)
+
+	return { kind: 'note', at_ms: Date.parse(event.at), issue, text: event.text, is_decision: false }
+}
+
+function note_of(event: RunEvent, titles: Titles): BoardNote | undefined {
+	if (event.kind === KIND.FILED) return filed_note(event)
+	if (event.kind === KIND.PARK) return park_note(event, titles)
+
+	return event.kind === KIND.NOTE ? plain_note(event) : undefined
+}
+
+// Newest first: the line a person glancing at the board needs is the latest one.
+function notes_of(events: ReadonlyArray<RunEvent>, titles: Titles): ReadonlyArray<BoardNote> {
+	return events.flatMap((event) => note_of(event, titles) ?? []).toReversed()
+}
+
+const run_board_notes = { notes_of }
+
+export { run_board_notes }
+export type { BoardNote, Titles }

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

@@ -0,0 +1,136 @@
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+
+// How far a running lane child has got, read from the events that name its issue. **Each phase comes
+// from a record a step already writes**: the launch, the `plan` event `run-event-plan.ts` writes, the
+// `lane-phase` the PreToolUse hook writes at the first implementation edit of each session, the ship
+// supervisor's launch, `josh ship`'s own stage trace and its stop. Nothing is guessed from the clock,
+// so a child that never reaches a record stays on the phase before it rather than being drawn further
+// on.
+//
+// **A child's phases are a history, not a high-water mark**: a ship that stops sends the child back to
+// implement, so a furthest phase that never went back would hold a row on 👀 while it codes again.
+// Each phase is written after the last, and a failed ship's own stages fold into the `ship`, `failed`
+// pair, so the retries read as the count of 🔨 and of 🚢💥. A stage line that lists its attempt
+// redraws that attempt whole (`replayed`).
+
+const PHASES = [
+	'investigate',
+	'plan',
+	'implement',
+	'ship',
+	'review',
+	'gate',
+	'sync',
+	'commit',
+	'round_two',
+	'followup',
+	'report',
+	'failed',
+] as const
+
+type Phase = (typeof PHASES)[number]
+
+const KIND = run_event_stream.EVENT_KIND
+const { STAGE } = run_ship_stage
+// A launched child is investigating until a later record says otherwise — no event marks the start.
+const LAUNCHED_PHASE: Phase = 'investigate'
+const WORD_SEPARATOR = ' '
+const STAGE_INDEX = 1
+
+// `josh ship`'s stages, each its own phase; the preflight is the ship's own start.
+const SHIP_PHASES: Readonly<Partial<Record<string, Phase>>> = {
+	[STAGE.PREFLIGHT]: 'ship',
+	[STAGE.REVIEW]: 'review',
+	[STAGE.GATE]: 'gate',
+	[STAGE.SYNC]: 'sync',
+	[STAGE.COMMIT]: 'commit',
+	[STAGE.ROUND_TWO]: 'round_two',
+	[STAGE.FOLLOWUP]: 'followup',
+	[STAGE.REPORT]: 'report',
+}
+
+const LANE_PHASES: Readonly<Partial<Record<string, Phase>>> = { implement: 'implement' }
+
+// The kinds that mark one phase whatever their text says.
+const KIND_PHASES: Readonly<Partial<Record<string, Phase>>> = {
+	[KIND.PLAN]: 'plan',
+	[KIND.SHIP_LAUNCH]: 'ship',
+	[KIND.SHIP_STOP]: 'failed',
+}
+
+// The word after the issue — `#<N> <stage> <phase>` carries the stage second.
+function stage_word_of(event: RunEvent): string {
+	return event.text.split(WORD_SEPARATOR)[STAGE_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
+
+	return SHIP_PHASES[stage_word_of(event)]
+}
+
+// The phase one event marks, or `undefined` for an event that marks none.
+function phase_of(event: RunEvent): Phase | undefined {
+	if (event.kind === KIND.LANE_PHASE) return LANE_PHASES[stage_word_of(event)]
+	if (event.kind === KIND.SHIP_STAGE) return ship_phase_of(event)
+
+	return KIND_PHASES[event.kind]
+}
+
+// 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')
+
+	return [...track.slice(0, ship + 1), 'failed']
+}
+
+// The history after one more phase: the same phase twice in a row — a `ship-launch` and its preflight,
+// a second session's first edit — is written once.
+function history_after(track: ReadonlyArray<Phase>, next: Phase): Array<Phase> {
+	if (next === 'failed') return failed_after(track)
+
+	return track.at(-1) === next ? [...track] : [...track, next]
+}
+
+const ATTEMPT_PHASES: ReadonlySet<Phase | undefined> = new Set(Object.values(SHIP_PHASES))
+
+// The phases a `ship-stage` line says its attempt has started (`run-ship-stage.ts` → `event_text`), in
+// the order they ran and led by the ship's own start, which a resumed ship's passed-over preflight does
+// not list. `undefined` for a line that carries none — an older three-word line is read one phase at a
+// time.
+function attempt_of(event: RunEvent): ReadonlyArray<Phase> | undefined {
+	const started = event.kind === KIND.SHIP_STAGE ? run_ship_stage.started_of(event.text) : undefined
+
+	if (started === undefined) return undefined
+
+	return [...new Set<Phase>(['ship', ...started.flatMap((stage) => SHIP_PHASES[stage] ?? [])])]
+}
+
+// Where the current ship attempt starts on a track: the first `ship` of the stages that end it, else the
+// end — a failed or re-implemented attempt before it is history, never redrawn. A supervisor restarted
+// with no stop between adds a second `ship` inside the same attempt, which the line redraws whole.
+function attempt_start(track: ReadonlyArray<Phase>): number {
+	const tail = track.findLastIndex((phase) => !ATTEMPT_PHASES.has(phase)) + 1
+	const ship = track.indexOf('ship', tail)
+
+	return ship === -1 ? track.length : ship
+}
+
+// **The newest line restores what the bound dropped**: on a stream full of
+// positions only each issue's newest stage line survives, so the current attempt is redrawn from it, in
+// the order the line lists. A line that misses a phase the track holds — a restarted supervisor's, which
+// lists none of the stages it passed over — is added after them rather than replacing them.
+function replayed(track: ReadonlyArray<Phase>, attempt: ReadonlyArray<Phase>): Array<Phase> {
+	const start = attempt_start(track)
+	const current = track.slice(start)
+	const is_covered = current.every((phase) => attempt.includes(phase))
+
+	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 }
+
+export { run_board_phase }
+export type { Phase }

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

@@ -0,0 +1,129 @@
+import { auto_ok_cli, type OptedInRead } from '#scripts/auto-ok/auto-ok-cli'
+import type { OptedIn } from '#scripts/backlog/backlog-next'
+import type { NamedPlan } from '#scripts/backlog/backlog-plan'
+import { backlog_plan_read, type OpenListing, type Plan } from '#scripts/backlog/backlog-plan-read'
+import { backlog_waves } from '#scripts/backlog/backlog-waves'
+import type { EpicChild } from '#scripts/epic/epic-graph'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
+import type { BoardPlan } from './run-board-layout'
+
+// The plan `run:board` lays the run over, scoped to what the run was asked to do.
+// **`--only`** draws the named issues alone — a named epic expanded into its children; **a named prefix
+// without it** draws the named issues first and the opted-in waves after them; **nothing named** draws the
+// opted-in waves. The named issues are classified through the very function `backlog:next`
+// places the pool with, fed as an opted-in set of their own, so an epic is expanded the way the run
+// expands it and no second placement exists to disagree with it.
+
+// The reads the plan is drawn from, a seam so each scope is tested without GitHub.
+interface PlanPorts {
+	fetch_open: () => Promise<OpenListing | undefined>
+	fetch_opted_in: () => Promise<OptedInRead>
+	classify: (opted_in: OptedIn, exclude: ReadonlyArray<number>) => Promise<Plan | undefined>
+}
+
+const LIVE_PORTS: PlanPorts = {
+	fetch_open: backlog_plan_read.fetch_open,
+	fetch_opted_in: auto_ok_cli.fetch_opted_in,
+	classify: backlog_plan_read.classify,
+}
+
+// One classified plan, against the listing it was read with.
+interface PlanRead {
+	listing: OpenListing
+	ports: PlanPorts
+}
+
+// A row the listing read without its labels is left out, so it reads as unknown rather than unlabelled.
+function labels_of(rows: ReadonlyArray<OpenIssueData>): ReadonlyMap<number, ReadonlyArray<string>> {
+	const labelled = rows.flatMap((row) =>
+		row.labels === undefined ? [] : [[row.number, row.labels.map((label) => label.name)] as const],
+	)
+
+	return new Map(labelled)
+}
+
+async function board_of(
+	opted_in: OptedIn,
+	exclude: ReadonlyArray<number>,
+	read: PlanRead,
+): Promise<BoardPlan | undefined> {
+	const plan = await read.ports.classify(opted_in, exclude)
+
+	if (plan === undefined) return undefined
+
+	return {
+		waves: backlog_waves.build(plan.result, plan.repo, plan.scope),
+		tracked: plan.tracked,
+		context: backlog_plan_read.context_of(plan, read.listing),
+		labels: labels_of(read.listing.rows),
+	}
+}
+
+async function pool_board(
+	exclude: ReadonlyArray<number>,
+	read: PlanRead,
+): Promise<BoardPlan | undefined> {
+	const opted_in = await read.ports.fetch_opted_in()
+
+	return opted_in.kind === 'read' ? await board_of(opted_in, exclude, read) : undefined
+}
+
+// The named issues as the open listing holds them — a closed one is the stream's to show, not the plan's.
+async function named_board(named: NamedPlan, read: PlanRead): Promise<BoardPlan | undefined> {
+	const issues = read.listing.rows.filter((row) => named.issues.includes(row.number))
+
+	return await board_of({ kind: 'read', issues, cutoff: 'none' }, [], read)
+}
+
+function children_of(plan: BoardPlan): Array<EpicChild> {
+	return [...plan.waves.waves.flat(), ...plan.waves.unreached]
+}
+
+function not_held(children: ReadonlyArray<EpicChild>, held: ReadonlySet<number>): Array<EpicChild> {
+	return children.filter((child) => !held.has(child.number))
+}
+
+// The named waves lead and the pool's follow, a child the named plan already holds left out of the pool
+// so a named epic's children are not drawn twice.
+function joined(lead: BoardPlan, pool: BoardPlan): BoardPlan {
+	const held = new Set(children_of(lead).map((child) => child.number))
+
+	return {
+		waves: {
+			waves: [...lead.waves.waves, ...pool.waves.waves.map((wave) => not_held(wave, held))],
+			unreached: [...lead.waves.unreached, ...not_held(pool.waves.unreached, held)],
+		},
+		tracked: new Map([...pool.tracked, ...lead.tracked]),
+		context: pool.context,
+		labels: pool.labels,
+	}
+}
+
+async function scoped_board(named: NamedPlan, read: PlanRead): Promise<BoardPlan | undefined> {
+	const lead = await named_board(named, read)
+
+	if (lead === undefined || named.only) return lead
+
+	const pool = await pool_board(named.issues, read)
+
+	return pool === undefined ? undefined : joined(lead, pool)
+}
+
+// `undefined` is a failed read, which the board answers by keeping the plan it already has.
+async function read_plan(
+	named: NamedPlan,
+	ports: PlanPorts = LIVE_PORTS,
+): Promise<BoardPlan | undefined> {
+	const listing = await ports.fetch_open()
+
+	if (listing === undefined) return undefined
+
+	const read = { listing, ports }
+
+	return named.issues.length === 0 ? await pool_board([], read) : await scoped_board(named, read)
+}
+
+const run_board_plan = { read_plan }
+
+export { run_board_plan }
+export type { PlanPorts }

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

@@ -0,0 +1,62 @@
+import type { NamedPlan } from '#scripts/backlog/backlog-plan'
+import { lane_registry } from '#scripts/lane/lane-registry'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import { run_carry_ended } from '#scripts/run/carry/run-carry-ended'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_board_scope } from './run-board-scope'
+import { run_board_span, type BoardSpan } from './run-board-span'
+
+// What `run:board` reads locally each tick: the run's span and scope, its events and its open lanes.
+// The run is the running one, or the one that last ended until the next run begins.
+interface LocalRead {
+	started_ms: number
+	// Set only once the run has ended; the board then draws its end-of-run screen.
+	ended_ms: number | undefined
+	// What the run was asked to do, from its invocation.
+	scope: NamedPlan
+	events: ReadonlyArray<RunEvent>
+	lanes: ReadonlyArray<string>
+	// The session a stopped run is resumed from; `undefined` otherwise.
+	resume: string | undefined
+}
+
+interface SpanHere {
+	span: BoardSpan | undefined
+	resume: string | undefined
+}
+
+function span_here(repository: string): SpanHere {
+	const read = run_carry.read_carry(run_carry.carry_path(repository))
+	const ended = run_carry_ended.read_ended(run_carry_ended.ended_path(repository))
+
+	return {
+		span: run_board_span.span_of(read, ended),
+		resume: run_board_span.resume_of(read, ended),
+	}
+}
+
+// `undefined` when no run has started here.
+async function read_local(): Promise<LocalRead | undefined> {
+	const repository = await run_carry.repository_directory()
+	const { span, resume } =
+		repository === undefined ? { span: undefined, resume: undefined } : span_here(repository)
+
+	if (repository === undefined || span === undefined) return undefined
+
+	const events = run_event_stream.read_events(run_event_stream.target_of(repository))
+	const lanes = await lane_registry.list_lanes()
+
+	return {
+		started_ms: span.started_ms,
+		ended_ms: span.ended_ms,
+		scope: run_board_scope.scope_of(span.invocation),
+		events: run_board_span.events_of(events, span),
+		lanes: lanes.map((lane) => lane.issue),
+		resume,
+	}
+}
+
+const run_board_read = { read_local }
+
+export { run_board_read }
+export type { LocalRead }