@joshuafolkken/kit 1.1383.0 → 1.1435.0

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

@@ -3,10 +3,14 @@ import {
 	IN_PROGRESS_LABEL,
 	NEEDS_DECISION_LABEL,
 } from '#scripts/issue/issue-labels'
+import type { PrChecks } from '#scripts/run/event/run-event-checks'
 import { run_event_scope } from '#scripts/run/event/run-event-scope'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_board_checks } from './run-board-checks'
 import type { ClosedIssue } from './run-board-closed'
+import { run_board_lane_event, type LaneEvent } from './run-board-lane-event'
 import { run_board_phase, type Phase } from './run-board-phase'
+import { run_board_setup, type SetupRead } from './run-board-setup'
 
 // What each issue of a run is doing now, read from the run's own event stream and its open lanes.
 // Local reads only — no `gh` call — so `run:board` can redraw it every few seconds; the plan these
@@ -24,11 +28,29 @@ interface ItemStatus {
 	lane?: string | undefined
 	// Every phase the child passed while running, in order (`run-board-phase.ts`) — kept once it settles.
 	track?: ReadonlyArray<Phase> | undefined
+	// When a running child entered the phase its track ends on — the event that moved it there.
+	phase_ms?: number | undefined
 }
 
-// The run as a whole, read off the same stream.
-interface RunActivity {
+interface LatestEvent {
+	text: string
+	at_ms: number
+}
+
+// The run as a whole, read off the same stream. The setup half is `run-board-setup.ts`'s, absent
+// where a stream carries no stage.
+interface RunActivity extends Partial<SetupRead> {
 	last_event_ms: number | undefined
+	// The newest thing the run did — its newest position, or its newest event where it has none yet —
+	// in the event's own words, and when.
+	latest?: LatestEvent | undefined
+	// When the run last did anything of its own — its newest position or stage, whichever is newer. A
+	// stage that has ended still counts: what follows it is counted from its end, not from before it.
+	idle_ms?: number | undefined
+	// Each child's newest `lane-phase` or `ship-stage`, by issue (`run-board-lane-event.ts`).
+	lane_events?: ReadonlyMap<number, LaneEvent> | undefined
+	// Each child's newest `pr-checks`, by issue (`run-board-checks.ts`).
+	pr_checks?: ReadonlyMap<number, PrChecks> | undefined
 	// The run's last position is a `stop` that names no child — the run itself ended.
 	is_stopped: boolean
 }
@@ -42,13 +64,30 @@ const ENDING_STATES: Readonly<Partial<Record<string, ItemState>>> = {
 }
 // A cut or a resume says the child is still running, on whatever phase it had reached.
 const CONTINUING_KINDS: ReadonlySet<string> = new Set([KIND.CUT, KIND.RESUME])
+// A person's restart starts the child over in a fresh session, so its track starts over too.
+const LAUNCH_KINDS: ReadonlySet<string> = new Set([KIND.CHILD_LAUNCH, KIND.RESTART])
 
 function moment(event: RunEvent): number {
 	return Date.parse(event.at)
 }
 
 function launched(event: RunEvent): ItemStatus {
-	return { state: 'running', started_ms: moment(event), track: [run_board_phase.LAUNCHED_PHASE] }
+	const at_ms = moment(event)
+
+	return {
+		state: 'running',
+		started_ms: at_ms,
+		track: [run_board_phase.LAUNCHED_PHASE],
+		phase_ms: at_ms,
+	}
+}
+
+// The status with its track moved on by `event`. The phase's start moves only where the phase the
+// track ends on changes, so a second session's first edit does not restart the time of its phase.
+function moved(previous: ItemStatus, track: ReadonlyArray<Phase>, event: RunEvent): ItemStatus {
+	const is_same = previous.phase_ms !== undefined && track.at(-1) === previous.track?.at(-1)
+
+	return { ...previous, track, phase_ms: is_same ? previous.phase_ms : moment(event) }
 }
 
 // The status a child settles into: its start and the track it had reached, so a settled row still
@@ -64,7 +103,9 @@ function ended(previous: ItemStatus | undefined, state: ItemState, event: RunEve
 }
 
 function continued(previous: ItemStatus | undefined): ItemStatus {
-	return { state: 'running', started_ms: previous?.started_ms, track: previous?.track }
+	const { started_ms, track, phase_ms } = previous ?? {}
+
+	return { state: 'running', started_ms, track, phase_ms }
 }
 
 // A stage line carrying its attempt redraws the track of any child launched on this stream — a settled
@@ -73,11 +114,12 @@ function continued(previous: ItemStatus | undefined): ItemStatus {
 function replayed(
 	previous: ItemStatus | undefined,
 	attempt: ReadonlyArray<Phase>,
+	event: RunEvent,
 ): ItemStatus | undefined {
 	if (previous === undefined) return previous
 	if (previous.track === undefined && previous.state !== 'running') return previous
 
-	return { ...previous, track: run_board_phase.replayed(previous.track ?? [], attempt) }
+	return moved(previous, run_board_phase.replayed(previous.track ?? [], attempt), event)
 }
 
 // A phase moves only a running child, so a three-word `report` stage after its merge — or a `plan`
@@ -87,18 +129,18 @@ function phased(previous: ItemStatus | undefined, event: RunEvent): ItemStatus |
 
 	if (phase === undefined || previous?.state !== 'running') return previous
 
-	return { ...previous, track: run_board_phase.history_after(previous.track ?? [], phase) }
+	return moved(previous, run_board_phase.history_after(previous.track ?? [], phase), event)
 }
 
 function advanced(previous: ItemStatus | undefined, event: RunEvent): ItemStatus | undefined {
 	const attempt = run_board_phase.attempt_of(event)
 
-	return attempt === undefined ? phased(previous, event) : replayed(previous, attempt)
+	return attempt === undefined ? phased(previous, event) : replayed(previous, attempt, event)
 }
 
 // One event folded into the status of the child it names; an event the board does not track keeps it.
 function next_status(previous: ItemStatus | undefined, event: RunEvent): ItemStatus | undefined {
-	if (event.kind === KIND.CHILD_LAUNCH) return launched(event)
+	if (LAUNCH_KINDS.has(event.kind)) return launched(event)
 
 	const ending = ENDING_STATES[event.kind]
 
@@ -125,16 +167,17 @@ function fold_events(events: ReadonlyArray<RunEvent>): Map<number, ItemStatus> {
 function is_running_lane(
 	issue: number,
 	status: ItemStatus | undefined,
+	events: ReadonlyArray<RunEvent>,
 	in_run: ReadonlySet<number>,
 ): boolean {
-	if (status === undefined) return in_run.has(issue)
+	if (status !== undefined) return status.state === 'running'
 
-	return status.state === 'running'
+	return in_run.has(issue) && !run_board_setup.is_lane_pending(events, issue)
 }
 
 // Every child the run has touched, with the lane each running child holds. A lane the stream never saw
 // launched — a run restored after the stream rolled — still reads as running while its issue is in the
-// run's plan (`in_run`).
+// run's plan (`in_run`); one the run is still setting up for stays waiting until its launch.
 function statuses_of(
 	events: ReadonlyArray<RunEvent>,
 	lanes: ReadonlyArray<string>,
@@ -146,7 +189,7 @@ function statuses_of(
 		const issue = Number(lane)
 		const status = statuses.get(issue)
 
-		if (is_running_lane(issue, status, in_run)) {
+		if (is_running_lane(issue, status, events, in_run)) {
 			statuses.set(issue, { state: 'running', ...status, lane: `lane ${lane}` })
 		}
 	}
@@ -244,6 +287,21 @@ function is_run_stop(event: RunEvent | undefined): boolean {
 	return event?.kind === KIND.STOP && run_event_scope.issue_named(event) === undefined
 }
 
+function latest_of(event: RunEvent | undefined): LatestEvent | undefined {
+	return event === undefined ? undefined : { text: event.text, at_ms: moment(event) }
+}
+
+function is_own(event: RunEvent): boolean {
+	return event.kind === KIND.SETUP || !run_event_stream.TRACE_KINDS.has(event.kind)
+}
+
+// A stream of traces alone has done nothing of its own yet, so its newest event stands in.
+function idle_of(events: ReadonlyArray<RunEvent>): number | undefined {
+	const own = events.findLast((event) => is_own(event)) ?? events.at(-1)
+
+	return own === undefined ? undefined : moment(own)
+}
+
 // `is_ended` is a run `run:carry --end` closed: its record says it stopped, whatever its last event
 // was.
 function activity_of(events: ReadonlyArray<RunEvent>, is_ended = false): RunActivity {
@@ -251,7 +309,12 @@ function activity_of(events: ReadonlyArray<RunEvent>, is_ended = false): RunActi
 	const position = events.findLast((event) => !run_event_stream.TRACE_KINDS.has(event.kind))
 
 	return {
+		...run_board_setup.read(events),
 		last_event_ms: last === undefined ? undefined : moment(last),
+		latest: latest_of(position ?? last),
+		idle_ms: idle_of(events),
+		lane_events: run_board_lane_event.newest_of(events),
+		pr_checks: run_board_checks.newest_of(events),
 		is_stopped: is_ended || is_run_stop(position),
 	}
 }
@@ -259,4 +322,4 @@ function activity_of(events: ReadonlyArray<RunEvent>, is_ended = false): RunActi
 const run_board_status = { activity_of, settle_closed, statuses_of }
 
 export { run_board_status }
-export type { ItemState, ItemStatus, OpenRead, RunActivity }
+export type { ItemState, ItemStatus, LatestEvent, OpenRead, RunActivity }

package/scripts/run/board/run-board-thanks-csv.ts

@@ -0,0 +1,71 @@
+import { parse } from 'csv-parse/sync'
+import { run_board_render_title } from './run-board-render-title'
+
+// The reviewers who helped kit, read off the published roster's CSV. The roster is a spreadsheet anyone
+// with edit access changes, so nothing in it is trusted as drawn: a sheet whose header is not `name,url`
+// is not the roster, a row without a name or with a link that is not `https://` is dropped, and a name
+// loses every control character — an escape in a cell would otherwise be written to the terminal as one.
+
+const HEADER = ['name', 'url'] as const
+// Enough for any person's or project's name, short enough that one cell cannot fill the line; a
+// longer one is cut to an ellipsis, as a row's title is.
+const NAME_LIMIT = 40
+const CONTROL = /\p{Cc}/gu
+const SAFE_URL = /^https:\/\/[^\s\p{Cc}]+$/u
+
+interface Thanker {
+	name: string
+	// The page the name opens; `undefined` draws the name unlinked.
+	url: string | undefined
+}
+
+type Thanks = ReadonlyArray<Thanker>
+
+function name_of(cell: string): string {
+	return run_board_render_title.title_of(cell.replaceAll(CONTROL, '').trim(), NAME_LIMIT)
+}
+
+// An empty cell is a name without a link; any other value has to be a whole `https://` URL.
+function url_of(cell: string): string | undefined | false {
+	const url = cell.trim()
+
+	if (url === '') return undefined
+
+	return SAFE_URL.test(url) && URL.canParse(url) ? url : false
+}
+
+function thanker_of(row: ReadonlyArray<string>): Array<Thanker> {
+	const [name_cell = '', url_cell = ''] = row
+	const name = name_of(name_cell)
+	const url = url_of(url_cell)
+
+	if (name === '' || url === false) return []
+
+	return [{ name, url }]
+}
+
+function is_roster(header: ReadonlyArray<string> | undefined): boolean {
+	return header?.length === HEADER.length && HEADER.every((cell, index) => header[index] === cell)
+}
+
+function rows_of(csv: string): Array<Array<string>> | undefined {
+	try {
+		return parse(csv, { relax_column_count: true, skip_empty_lines: true, bom: true })
+	} catch {
+		return undefined
+	}
+}
+
+// `undefined` for a text that is not the roster, so a failed read is told apart from an empty roster.
+function thanks_of(csv: string): Thanks | undefined {
+	const [header, ...rows] = rows_of(csv) ?? []
+
+	if (!is_roster(header)) return undefined
+
+	return rows.flatMap((row) => thanker_of(row))
+}
+
+const run_board_thanks_csv = { NAME_LIMIT, thanks_of }
+
+export { run_board_thanks_csv }
+export type { Thanker, Thanks }

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

@@ -0,0 +1,112 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { timed_fetch } from '#scripts/lib/timed-fetch'
+import { run_progress } from '#scripts/run/progress/run-progress'
+import { z } from 'zod'
+import { run_board_thanks_csv, type Thanks } from './run-board-thanks-csv'
+
+// The roster `run:board` thanks its reviewers from: a Google spreadsheet published as CSV, changed
+// apart from any build or release, so it is read at run time. Its answer is kept in the project's
+// record beside the board's other state and reused for five minutes — Google's own cache holds it as
+// long — so neither a redraw nor a fresh `--once` asks again inside that window. A read that fails
+// keeps the last answer, and with none draws no line; nothing about the failure reaches the screen.
+
+const ROSTER_URL =
+	'https://docs.google.com/spreadsheets/d/e/2PACX-1vR8Ia38Wiw6Kfyk9Or594J8ZRS8okynV30CpOtq5B6_GyJG7A1-t8Au64jTYvmzgIOlbafcKKgrNFVJ/pub?gid=0&single=true&output=csv'
+const RECORD_PREFIX = 'josh-run-board-thanks-'
+const TTL_MINUTES = 5
+const TTL_MS = TTL_MINUTES * run_progress.MS_PER_MINUTE
+
+const thanker_schema = z.object({ name: z.string(), url: z.string().optional() })
+const record_schema = z.object({ checked_ms: z.number(), thanks: z.array(thanker_schema) })
+
+interface ThanksRecord {
+	checked_ms: number
+	thanks: Thanks
+}
+
+// What the read works through, injected in tests.
+interface ThanksDependencies {
+	fetch_text: () => Promise<string>
+	record_path: string
+	now: () => number
+}
+
+function read_record(record_path: string): ThanksRecord | undefined {
+	const raw = stamp_file.read_stamp_text(record_path)
+	const parsed = raw === undefined ? undefined : json_value.parse_with(raw, record_schema)
+
+	if (parsed === undefined) return undefined
+
+	return {
+		checked_ms: parsed.checked_ms,
+		thanks: parsed.thanks.map(({ name, url }) => ({ name, url })),
+	}
+}
+
+// A record that cannot be written leaves the next read to ask again — never a reason to fail the board.
+function write_record(record_path: string, record: ThanksRecord): void {
+	try {
+		stamp_file.replace_stamp(record_path, record)
+	} catch {
+		// The board draws what it read either way.
+	}
+}
+
+async function fetch_roster(read: () => Promise<string>): Promise<Thanks | undefined> {
+	try {
+		return run_board_thanks_csv.thanks_of(await read())
+	} catch {
+		return undefined
+	}
+}
+
+// The recorded roster while it is younger than the record's life; `undefined` once it is stale. A
+// record dated after now — the clock stepped back — is stale too, or it would hold until the clock
+// caught up with it.
+function fresh_thanks(record: ThanksRecord | undefined, now_ms: number): Thanks | undefined {
+	if (record === undefined) return undefined
+
+	const age_ms = now_ms - record.checked_ms
+
+	return age_ms >= 0 && age_ms < TTL_MS ? record.thanks : undefined
+}
+
+// A response that is not a success is a failed read, so its body is never taken for the roster.
+async function fetch_text(): Promise<string> {
+	const response = await timed_fetch(ROSTER_URL)
+
+	if (!response.ok) throw new Error(`roster read answered ${String(response.status)}`)
+
+	return await response.text()
+}
+
+const LIVE_DEPS: ThanksDependencies = {
+	fetch_text,
+	record_path: stamp_file.stamp_path(RECORD_PREFIX, PROJECT_ROOT),
+	now: () => Date.now(),
+}
+
+async function read_with(deps: ThanksDependencies): Promise<Thanks> {
+	const now_ms = deps.now()
+	const record = read_record(deps.record_path)
+	const fresh = fresh_thanks(record, now_ms)
+
+	if (fresh !== undefined) return fresh
+
+	const thanks = (await fetch_roster(deps.fetch_text)) ?? record?.thanks ?? []
+
+	write_record(deps.record_path, { checked_ms: now_ms, thanks })
+
+	return thanks
+}
+
+async function read_thanks(deps: ThanksDependencies = LIVE_DEPS): Promise<Thanks> {
+	return await read_with(deps)
+}
+
+const run_board_thanks_read = { TTL_MS, read_thanks }
+
+export { run_board_thanks_read }
+export type { ThanksDependencies }

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

@@ -0,0 +1,53 @@
+import { run_board_fetch, type Fetch } from './run-board-fetch'
+import { run_board_state, type BoardPorts, type BoardState, type Pace } from './run-board-state'
+import type { Thanks } from './run-board-thanks-csv'
+import { run_board_thanks_read } from './run-board-thanks-read'
+
+// The reviewers' roster a `run:board` redraw draws above its legend. Like the GitHub reads
+// (`run-board-github.ts`), **a live board never waits on it**: the read is launched and folded in on
+// the redraw after it lands; one plain frame waits for it. It is launched again no sooner than the
+// roster's own record goes stale. A board with no `read_thanks` port — the chat frame — reads none and
+// draws none.
+
+const { TTL_MS } = run_board_thanks_read
+const { is_due } = run_board_state
+
+type ThanksState = Pick<BoardState, 'thanks' | 'thanks_fetch' | 'thanks_attempted_ms'>
+
+function launch_thanks(state: BoardState, ports: BoardPorts, now_ms: number): BoardState {
+	const { read_thanks } = ports
+
+	if (read_thanks === undefined || state.thanks_fetch !== undefined) return state
+	if (!is_due(state.thanks_attempted_ms, TTL_MS, now_ms)) return state
+
+	const thanks_fetch: Fetch<Thanks> = run_board_fetch.launch(read_thanks, state.thanks)
+
+	return { ...state, thanks_fetch, thanks_attempted_ms: now_ms }
+}
+
+function fold_thanks(state: BoardState): BoardState {
+	const answer = state.thanks_fetch?.answer()
+
+	if (answer === undefined) return state
+
+	return { ...state, thanks: answer.value, thanks_fetch: undefined }
+}
+
+// Folds what landed and launches what is due; at the `settled` pace, waits for it to land.
+async function gather_thanks(
+	state: BoardState,
+	ports: BoardPorts,
+	now_ms: number,
+	pace: Pace,
+): Promise<BoardState> {
+	const launched = launch_thanks(fold_thanks(state), ports, now_ms)
+
+	if (pace === 'settled' && launched.thanks_fetch !== undefined) await launched.thanks_fetch.landed
+
+	return fold_thanks(launched)
+}
+
+const run_board_thanks = { gather_thanks }
+
+export { run_board_thanks }
+export type { ThanksState }

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

@@ -8,10 +8,12 @@ import { run_board_link } from './run-board-link'
 import { run_board_machine } from './run-board-machine'
 import { run_board_notes, type Titles } from './run-board-notes'
 import type { LocalRead } from './run-board-read'
+import { run_board_reason } from './run-board-reason'
 import { run_board_render, type FrameBounds } from './run-board-render'
 import { run_board_spin, type Spun } from './run-board-spin'
 import { run_board_state, type BoardPorts, type BoardState, type Pace } from './run-board-state'
-import { run_board_status } from './run-board-status'
+import { run_board_status, type RunActivity } from './run-board-status'
+import { run_board_thanks } from './run-board-thanks'
 import { run_board_usage } from './run-board-usage'
 
 // One `run:board` redraw. **Three speeds**: the frame is redrawn once a second, on the second, so
@@ -30,6 +32,7 @@ const LOCAL_READ_SECONDS = 5
 const LOCAL_READ_MS = LOCAL_READ_SECONDS * run_progress.MS_PER_SECOND
 const { FRESH_STATE, is_due } = run_board_state
 const { PLAN_RETRY_MS, gather_github, statuses_for } = run_board_github
+const { gather_thanks } = run_board_thanks
 
 async function reread(state: BoardState, ports: BoardPorts, now_ms: number): Promise<BoardState> {
 	if (!is_due(state.read_ms, LOCAL_READ_MS, now_ms)) return state
@@ -88,17 +91,17 @@ function titles_of(state: BoardState): Titles {
 	return with_closed(state.plan, state.closed).context.titles
 }
 
-// The statuses scoped to the run's plan, a running child the plan's listing no longer holds settled.
-// Before the plan is read, the run's own children alone.
-function layout_for(state: BoardState, local: LocalRead): BoardLayout {
-	const { plan, closed } = state
-
-	if (plan === undefined) {
-		return run_board_layout.local_layout_of(
-			run_board_status.statuses_of(local.events, local.lanes, new Set()),
-		)
-	}
+// A run `run:carry --end` closed and one nobody drives any more are both drawn as stopped.
+function activity_here(local: LocalRead): RunActivity {
+	return run_board_status.activity_of(
+		local.events,
+		local.ended_ms !== undefined || local.is_stranded,
+	)
+}
 
+// The plan laid under its statuses, each waiting row saying why it waits.
+function planned_layout(state: BoardState, plan: BoardPlan, local: LocalRead): BoardLayout {
+	const { closed } = state
 	const read = {
 		open_numbers: plan.context.open_numbers,
 		read_ms: state.fetched_ms,
@@ -106,8 +109,25 @@ function layout_for(state: BoardState, local: LocalRead): BoardLayout {
 		labels: plan.labels,
 	}
 	const statuses = run_board_status.settle_closed(statuses_for(plan, local), read)
+	const reason_of = run_board_reason.reader({
+		plan,
+		statuses,
+		events: local.events,
+		free_lanes: local.free_lanes,
+		is_stopped: activity_here(local).is_stopped,
+	})
+
+	return run_board_layout.layout_of(with_closed(plan, closed), statuses, reason_of)
+}
+
+// The statuses scoped to the run's plan, a running child the plan's listing no longer holds settled.
+// Before the plan is read, the run's own children alone.
+function layout_for(state: BoardState, local: LocalRead): BoardLayout {
+	if (state.plan !== undefined) return planned_layout(state, state.plan, local)
 
-	return run_board_layout.layout_of(with_closed(plan, closed), statuses)
+	return run_board_layout.local_layout_of(
+		run_board_status.statuses_of(local.events, local.lanes, new Set()),
+	)
 }
 
 // What one redraw draws with.
@@ -116,6 +136,22 @@ interface Redraw {
 	now_ms: number
 }
 
+// What the header reads off the local read.
+type LocalHeader = Pick<
+	BoardHeader,
+	'started_ms' | 'ended_ms' | 'activity' | 'operations' | 'usual'
+>
+
+function local_header(local: LocalRead): LocalHeader {
+	return {
+		started_ms: local.started_ms,
+		ended_ms: local.ended_ms,
+		activity: activity_here(local),
+		operations: local.operations,
+		usual: local.usual,
+	}
+}
+
 function header_of(
 	state: BoardState,
 	local: LocalRead,
@@ -124,9 +160,7 @@ function header_of(
 ): BoardHeader {
 	return {
 		now_ms: redraw.now_ms,
-		started_ms: local.started_ms,
-		ended_ms: local.ended_ms,
-		activity: run_board_status.activity_of(local.events, local.ended_ms !== undefined),
+		...local_header(local),
 		layout,
 		baseline_total: state.baseline_total,
 		plan_fetched_ms: state.fetched_ms,
@@ -153,6 +187,8 @@ function frame_of(state: BoardState, local: LocalRead, layout: BoardLayout, redr
 		header: header_of(state, local, layout, redraw),
 		notes: run_board_notes.notes_of(local.events, titles_of(state)),
 		resume: local.resume,
+		thanks: state.thanks,
+		link: redraw.ports.link,
 		...bounds,
 	})
 
@@ -195,8 +231,9 @@ async function tick(
 	}
 
 	const gathered = await gather_github(state_for(read, local), { ports, local, now_ms, pace })
+	const thanked = await gather_thanks(gathered, ports, now_ms, pace)
 
-	return draw_run(await resample(gathered, ports, now_ms), local, { ports, now_ms })
+	return draw_run(await resample(thanked, ports, now_ms), local, { ports, now_ms })
 }
 
 const run_board_tick = {

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

@@ -0,0 +1,44 @@
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
+import { lane_stage_stats } from '#scripts/lane/lane-stage-stats'
+import { run_board_phase, type Phase } from './run-board-phase'
+
+// How long each phase usually takes: the lane ledger's median of the stage the phase is
+// (`lane-stage-stats.ts`), so a running child that has stood at its phase far longer stands out
+// (joshuafolkken/kit#3769). A phase is a `josh ship` stage under the names `run-board-phase.ts` gives
+// them, and `implement` is the ledger's derived one. A phase no stage records — `investigate`, `plan`,
+// `failed` — has no usual time, and is never drawn as long.
+
+type UsualTimes = ReadonlyMap<Phase, number>
+
+const IMPLEMENT_PHASE: Phase = 'implement'
+
+// Each phase's ledger stage, from the stage-to-phase names a row's phase is drawn with. The ledger's
+// `implement` runs from the dispatch, so it also holds the investigation and the plan the row draws
+// before its `implement` phase: the usual time is the longer, which can only draw a phase as long
+// later, never sooner.
+const PHASE_STAGES: ReadonlyArray<readonly [string, Phase | undefined]> = [
+	[lane_stage_stats.IMPLEMENT, IMPLEMENT_PHASE],
+	...Object.entries(run_board_phase.SHIP_PHASES),
+]
+
+function usual_of(entries: ReadonlyArray<LedgerEntry>): UsualTimes {
+	const medians = lane_stage_stats.medians(entries)
+
+	return new Map(
+		PHASE_STAGES.flatMap(([stage, phase]) => {
+			const median = medians.get(stage)
+
+			return phase === undefined || median === undefined ? [] : [[phase, median] as const]
+		}),
+	)
+}
+
+// The repository's whole ledger, read where the board reads its stream; an absent one has no usual time.
+function read(repository: string): UsualTimes {
+	return usual_of(lane_ledger.read_entries(lane_ledger.target_of(repository)))
+}
+
+const run_board_usual = { read, usual_of }
+
+export { run_board_usual }
+export type { UsualTimes }

package/scripts/run/carry/run-carry-added.ts

@@ -51,7 +51,7 @@ function add_issues(
 ): RunCarry {
 	const next: RunCarry = { ...carry, added: next_added(carry, additions) }
 
-	stamp_file.write_stamp(target, next)
+	stamp_file.replace_stamp(target, next)
 
 	return next
 }

package/scripts/run/carry/run-carry-args.ts

@@ -1,5 +1,6 @@
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_headless } from '#scripts/run/run-headless'
 import { run_invocation } from '#scripts/run/run-invocation'
 import { run_carry, type CarryChange, type CarryClaimRequest, type CarryOwner } from './run-carry'
 
@@ -178,6 +179,13 @@ function group_count(values: ParsedValues): number {
 	return groups.filter(Boolean).length
 }
 
+// The mark rides the environment the run launched its session with; the record keeps it beside the
+// owner, so `josh backlogrun --stop` knows that owner for the run's own. An attached owner is left as
+// it is, so its record is the one it always was.
+function marked(owner: CarryOwner): CarryOwner {
+	return run_headless.is_headless_parent(process.env) ? { ...owner, is_headless: true } : owner
+}
+
 // **`--owner` is what makes liveness answerable at all.** The process that runs this command is a
 // short-lived `tsx`, so its own pid says nothing about whether the run is still going; the caller
 // names the process that is — its own session — and a `backlogrun` passes `--owner "$PPID"`. Absent,
@@ -192,7 +200,7 @@ function to_owner(value: OptionValue): CarryOwner | undefined {
 
 	const pid = Number(text)
 
-	return pid < MIN_PID ? undefined : run_carry.owner_of(pid)
+	return pid < MIN_PID ? undefined : marked(run_carry.owner_of(pid))
 }
 
 // A non-empty `--summary`, or nothing. An empty string is nothing here, so it reads as absent and the

package/scripts/run/carry/run-carry-change.ts

@@ -83,7 +83,7 @@ function apply_change(
 		retrospective: effective.retrospective === true || carry.retrospective,
 	}
 
-	stamp_file.write_stamp(target, next)
+	stamp_file.replace_stamp(target, next)
 
 	return next
 }