@joshuafolkken/kit 1.1373.0 → 1.1383.0

package/scripts/init/security-policy.ts

@@ -0,0 +1,79 @@
+import path from 'node:path'
+import { repo_origin } from '#scripts/discovery/repo-origin'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { file_reader } from '#scripts/lib/read-file'
+
+// A consumer's `SECURITY.md` is its own policy, not kit's: the advisory and release links have to
+// name the repository the file lands in, and kit's account of its own published package is not a
+// fact about that repository. So the consumer copy is written from a template of its own, with the
+// repository filled in, and kit's root `SECURITY.md` stays kit's.
+const SECURITY_MD = 'SECURITY.md'
+const SECURITY_TEMPLATE = 'templates/SECURITY.md'
+const REPOSITORY_PLACEHOLDER = '{{REPOSITORY}}'
+const KIT_ADVISORY_URL = 'https://github.com/joshuafolkken/kit/security/advisories/new'
+const UNRESOLVED_REASON = '`origin` is not a GitHub repository `owner/repo` can be read from'
+const LINK_DELIMITER = /[\s()<>[\]]+/u
+
+// Read from the local `origin` rather than asked of GitHub: the basic profile decides whether to
+// write the file from the same remote, and a policy file must not depend on `gh` being signed in.
+function repository_at(root: string): string | undefined {
+	const url = git_spawn_sync.origin_url(root)
+	const identity = url === undefined ? undefined : repo_origin.parse_origin_url(url)
+
+	return identity === undefined ? undefined : `${identity.owner}/${identity.repo}`
+}
+
+function apply_repository(content: string, repository: string): string {
+	return content.replaceAll(REPOSITORY_PLACEHOLDER, () => repository)
+}
+
+// Throws rather than writing the placeholder through: both copy paths ask `did_skip_unresolved`
+// first, so reaching here without a repository is a caller that skipped the question.
+function apply_repository_for_destination(destination_path: string, content: string): string {
+	if (path.basename(destination_path) !== SECURITY_MD) return content
+	const repository = repository_at(path.dirname(destination_path))
+
+	if (repository === undefined) {
+		throw new Error(`${SECURITY_MD} needs a GitHub origin to name the repository it reports to`)
+	}
+
+	return apply_repository(content, repository)
+}
+
+// A full project synced before the template existed holds kit's own policy under this name, and the
+// skip leaves that file on disk — still sending its readers to kit's advisory form. The form is
+// matched as a whole link target, not as a substring: a longer address that merely starts with it
+// is another address.
+function does_report_to_kit(root: string): boolean {
+	const existing = file_reader.read_if_readable(path.join(root, SECURITY_MD)) ?? ''
+
+	return new Set(existing.split(LINK_DELIMITER)).has(KIT_ADVISORY_URL)
+}
+
+function unresolved_warning(root: string): string {
+	if (!does_report_to_kit(root)) return `  ⚠ skipped   ${SECURITY_MD} (${UNRESOLVED_REASON})`
+
+	return `  ⚠ stale     ${SECURITY_MD} still reports vulnerabilities to joshuafolkken/kit — replace it with your own policy or delete it (${UNRESOLVED_REASON})`
+}
+
+// Without a GitHub `origin` there is no repository for the advisory link to name, so the file is
+// left unwritten — the next `josh sync` after the remote is added writes it.
+function did_skip_unresolved(filename: string, root: string): boolean {
+	if (filename !== SECURITY_MD || repository_at(root) !== undefined) return false
+
+	console.warn(unresolved_warning(root))
+
+	return true
+}
+
+const security_policy = {
+	SECURITY_MD,
+	SECURITY_TEMPLATE,
+	REPOSITORY_PLACEHOLDER,
+	KIT_ADVISORY_URL,
+	repository_at,
+	apply_repository_for_destination,
+	did_skip_unresolved,
+}
+
+export { security_policy }

package/scripts/josh/josh-commands-ai.ts

@@ -214,7 +214,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		// credentials, the same reason `run:wake` carries these flags.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:
-			'Report whether the run is stranded — budget handed off, owner gone, and no supervisor watching',
+			'Report whether the run is stranded — owner gone, no successor holding the budget, and no supervisor watching',
 		category: 'AI tools',
 		reference: ['', 'automation', ['processes', 'notifications']],
 	},

package/scripts/josh/josh-commands-maintenance.ts

@@ -80,6 +80,9 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Update all dependencies to latest',
 		category: 'Maintenance',
 		reference: ['', 'developer', ['files', 'network']],
+		// `JOSH_PLAYWRIGHT_BROWSERS` widens the browsers a Playwright bump installs, and a project
+		// keeps that setting in its `.env`.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

package/scripts/josh/josh-commands-project.ts

@@ -88,7 +88,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 	},
 	adopt: {
 		script: 'scripts/adopt/adopt.ts',
-		description: 'Upgrade every installed @joshuafolkken toolkit here and open the pull request',
+		description: 'Upgrade the @joshuafolkken toolkits and other dependencies here, open the PR',
 		category: 'Project',
 		reference: ['[--dry-run]', 'developer', ['files', 'git', 'network', 'processes']],
 	},

package/scripts/josh/josh-commands-versioning.ts

@@ -20,7 +20,8 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 	// before chaining here, exactly as it already does for `latest:update`.
 	ranges: {
 		script: 'scripts/version/publishable-range-check.ts',
-		description: 'Check that every published dependency range still resolves for a consumer',
+		description:
+			'Check that every published dependency range still resolves for a consumer and no peer range falls below an installed toolkit',
 		category: 'Versioning',
 		reference: ['', 'developer', ['network']],
 	},

package/scripts/lane/lane-cli.ts

@@ -62,9 +62,7 @@ async function guard_cut_session(): Promise<string | undefined> {
 
 	const read = run_carry.read_carry(run_carry.carry_path(directory))
 
-	if ((read.kind !== 'carried' && read.kind !== 'expired') || read.carry.is_handed_off !== true) {
-		return undefined
-	}
+	if (read.kind !== 'carried' || read.carry.is_handed_off !== true) return undefined
 
 	return run_carry.count_refused_message(read.carry)
 }

package/scripts/propagate/propagate-run.ts

@@ -13,6 +13,7 @@ import type { PropagateTarget } from './propagate-targets'
 const STEP_PRECHECK = 'working tree check'
 const STEP_UPGRADE = 'josh vu'
 const STEP_SYNC = 'josh sync'
+const STEP_LATEST = 'josh latest'
 const STEP_LINT_RELATED = 'related lint check'
 const STEP_TEST_RELATED = 'related test check'
 const STEP_VERIFY = 'verification gate'
@@ -32,6 +33,18 @@ const STEP_ORDER: ReadonlyArray<string> = [
 	STEP_PR,
 	STEP_RETURN,
 ]
+// The same sequence with the consumer's other dependencies, its audit and its pnpm pin brought up
+// to date after the sync. Only `josh adopt` runs it: `josh latest` moves every dependency to the
+// registry's newest, which is what adoption is for and exactly what propagation's exact-version wait
+// exists to prevent — and an unrelated dependency's breakage would stop a release reaching a
+// consumer. Derived from `STEP_ORDER` rather than listed, so the two cannot drift apart; behind the
+// sync, because the sync can add devDependencies to `package.json` without installing them, and a
+// pull request opened over that fails CI's frozen install — the step installs before it updates
+// (`propagate_steps`), so the lockfile is re-resolved even when `josh latest` rolls its update back.
+// The related checks and the gate that follow then verify the tree as it will be committed.
+const ADOPT_STEP_ORDER: ReadonlyArray<string> = STEP_ORDER.flatMap((step) =>
+	step === STEP_SYNC ? [step, STEP_LATEST] : step,
+)
 const PROPAGATED_REASON = 'opened a pull request'
 
 type RunOutcome = 'propagated' | 'failed' | 'skipped'
@@ -130,10 +143,11 @@ function run_target(
 	target: PropagateTarget,
 	run_step: RunStep,
 	success_reason: string = PROPAGATED_REASON,
+	order: ReadonlyArray<string> = STEP_ORDER,
 ): TargetResult {
 	const steps: Array<StepResult> = []
 
-	for (const step of STEP_ORDER) {
+	for (const step of order) {
 		const result = run_step(target, step)
 
 		steps.push(result)
@@ -192,11 +206,13 @@ const propagate_run = {
 	STEP_ISSUE,
 	STEP_UPGRADE,
 	STEP_SYNC,
+	STEP_LATEST,
 	STEP_LINT_RELATED,
 	STEP_TEST_RELATED,
 	STEP_VERIFY,
 	STEP_PR,
 	STEP_ORDER,
+	ADOPT_STEP_ORDER,
 	skip_reason,
 	run_target,
 	run_targets,

package/scripts/propagate/propagate-steps.ts

@@ -27,10 +27,17 @@ const SUCCESS_EXIT_CODE = 0
 // pass — so the chain is not repeated here. It resolves in the consumer's directory, which by this
 // point has already been upgraded to the version being propagated, so the command is present.
 const VERIFY_SCRIPT = `pnpm josh ${GATE_COMMAND}`
+// `josh latest` behind an install of its own. The sync can add devDependencies to `package.json`
+// without installing them, and `josh latest` does not always re-resolve the lockfile: when the age
+// gate would downgrade a dependency it restores the files it found and exits zero. Installing first
+// makes the tree it finds a consistent one, so the lockfile matches `package.json` on either path.
+// `--no-frozen-lockfile` because the install exists to write the lockfile, which pnpm refuses under CI.
+const LATEST_SCRIPT = 'pnpm install --no-frozen-lockfile && pnpm josh latest'
 
 // The commands the release-independent spawning steps run inside the target's own directory. The
 // upgrade and the sync are not here: both are per toolkit, so they are built from the plan instead.
 const STEP_COMMANDS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	[propagate_run.STEP_LATEST]: ['sh', '-c', LATEST_SCRIPT],
 	[propagate_run.STEP_LINT_RELATED]: ['pnpm', 'josh', 'lint:related'],
 	[propagate_run.STEP_TEST_RELATED]: ['pnpm', 'josh', 'test:related'],
 	[propagate_run.STEP_VERIFY]: ['sh', '-c', VERIFY_SCRIPT],
@@ -353,7 +360,8 @@ interface Release {
 // `josh propagate` always passes exactly one release; `josh adopt` passes every toolkit installed in
 // the repository it runs in. Only the upgrade and the sync repeat per
 // release — the pre-check, the verification gate, the issue, the pull request and the return to the
-// default branch happen once, which is why the step order itself is unchanged.
+// default branch happen once, which is why the step order does not depend on the plan — `josh adopt`
+// runs `propagate_run.ADOPT_STEP_ORDER`, the same order with `josh latest` added.
 interface ReleasePlan {
 	releases: ReadonlyArray<Release>
 	origin: string

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

@@ -1,33 +1,36 @@
 import { styleText } from 'node:util'
 import { backlog_budget } from '#scripts/backlog/backlog-budget'
-import { backlog_idle, type IdleWindow } from '#scripts/backlog/backlog-idle'
+import { run_board_fit } from './run-board-fit'
 import { run_board_labels } from './run-board-labels'
 import { run_board_layout, type BoardLayout, type BoardRow } from './run-board-layout'
 import { run_board_machine, type MachineGauges } from './run-board-machine'
+import { run_board_render_slot } from './run-board-render-slot'
 import type { RunActivity } from './run-board-status'
 import type { LaneUsages } from './run-board-usage'
 
-// The top of `run:board`: whether the run is moving, how long it has run, how long it has left, how
-// fresh its last event is, and how far through the plan it is — and, while it waits on an empty
-// backlog, until when it waits and what ends the wait. Every time comes from a record (the carry's
-// start, the stream's events, the `idle` window); nothing here guesses one. Lines of symbols rather
-// than sentences: the `⏱` that moves every second is the proof the board is live, so no `updated`
-// line is drawn. Beside the time, the machine the run is on, so a slow run reads apart from a stuck
-// one. **Always two lines**: the run's state with its progress, then the time with the machine. A
-// value not read yet is drawn `-`, never `0`, so a header still loading reads as unknown rather than
-// as an empty run.
-
-const { HEADER_ICONS, STATE_ICONS, WORDS, bar_of, clock_of, elapsed_of, left_of, minute_of } =
-	run_board_labels
+// The top of `run:board`: whether the run is moving, how long it has run, how fresh its last event is,
+// and how far through the plan it is. Every time comes from a record (the carry's start, the stream's
+// events); nothing here guesses one. Lines of symbols rather than sentences: the `⏰` that moves every
+// second is the proof the board is live, so no `updated` line is drawn. **Always two lines, in three
+// columns**: the run's mark and name over its repository's, the run's age over the `💓`, then the
+// progress over the machine the run is on — so the first line reads as how far the run is and the
+// second as what it runs on, a slow run apart from a stuck one. Both are written the same while the
+// run works and while it waits, so a wait is read off the mark and the `💓` rather than off a line
+// that changes shape. A value not read yet is drawn `-`, never `0`, so a header still loading reads
+// as unknown rather than as an empty run.
+
+const { HEADER_ICONS, STATE_ICONS, WORDS, bar_of, minute_of, span_of } = run_board_labels
+const { cell_of } = run_board_render_slot
 const UNKNOWN = '-'
-const { GAP } = run_board_machine
+const BLANK = ' '
+const REPO_SEPARATOR = '/'
+const { GAP, PERCENT_WIDTH } = run_board_machine
 // A running run whose newest event is older than this is drawn as stale, so a hang stands out; past
 // twice that it is drawn as alarming.
 const STALE_MINUTES = 15
 const STALE_MS = STALE_MINUTES * backlog_budget.MS_PER_MINUTE
 const ALARM_FACTOR = 2
 const ALARM_MS = STALE_MS * ALARM_FACTOR
-const INDENT = '  '
 const RUN_NAME = 'backlogrun'
 
 // Who reads the frame: a person on a screen, or a chat a session answers a progress question in, which
@@ -56,6 +59,8 @@ interface BoardHeader {
 	// terminal and they draw their still icons.
 	spinner: string | undefined
 	form: BoardForm
+	// The repository the plan was read for, as `owner/repo`; `undefined` before a plan is read.
+	repo: string | undefined
 	// An issue reference as the board draws it — `3450` or `owner/repo#12` — made a link where the
 	// terminal opens one.
 	link: (reference: string) => string
@@ -103,9 +108,8 @@ function quiet_mark(layout: BoardLayout | undefined): RunMark {
 // The run's state, each state overriding the ones below it.
 function mark_of(header: BoardHeader, running: number): RunMark {
 	if (header.activity.is_stopped) return 'stopped'
-	if (running > 0) return 'running'
 
-	return header.activity.idle === undefined ? quiet_mark(header.layout) : 'idle'
+	return running > 0 ? 'running' : quiet_mark(header.layout)
 }
 
 // A running run turns the spinner in place of ▶, both one column wide; every other mark stands still.
@@ -116,25 +120,61 @@ function run_part(mark: RunMark, spinner: string | undefined): string {
 	return styleText(color, `${shown} ${RUN_NAME}`)
 }
 
+// The repository's own name — `kit` of `owner/kit` — under the run's, past the mark's columns, so a
+// board open beside another repository's is told apart. Blank before a plan names one.
+function repo_part(header: BoardHeader, mark: RunMark): string {
+	const name = header.repo?.split(REPO_SEPARATOR).at(-1) ?? ''
+	const indent = run_board_fit.width_of(RUN_MARKS[mark].glyph) + BLANK.length
+
+	return `${BLANK.repeat(indent)}${name}`
+}
+
 function aged(part: string, age_ms: number): string {
 	if (age_ms > ALARM_MS) return styleText('red', part)
 
 	return age_ms > STALE_MS ? styleText('yellow', part) : part
 }
 
-// How long ago the stream last moved; only a running run can be stale, so only it is colored. An ended
-// run has no heartbeat to keep: one counting on would read as a hang.
-function heartbeat_part(header: BoardHeader, mark: RunMark): string | undefined {
+// How long ago the stream last moved. An ended run has no heartbeat to keep: one counting on would
+// read as a hang.
+function age_of(header: BoardHeader): number | undefined {
 	const last = header.activity.last_event_ms
 
 	if (last === undefined || header.ended_ms !== undefined) return undefined
 
-	const age = header.now_ms - last
-	const part = `💓 ${elapsed_of(age)}`
+	return header.now_ms - last
+}
+
+// The minute an ended run ended, standing where its heartbeat did. Blank while the run has none to draw.
+function ended_part(header: BoardHeader): string {
+	const { ended_ms } = header
+
+	return ended_ms === undefined ? '' : `${HEADER_ICONS.ended} ${minute_of(ended_ms)}`
+}
+
+// The `💓` under the run's age, in the `⏰`'s own format with its digits right-aligned to `width` —
+// only a running run can be stale, so only it is colored. Only an ended run draws anything else there:
+// the minute it ended.
+function beat_part(header: BoardHeader, mark: RunMark, width: number): string {
+	const age = age_of(header)
+
+	if (age === undefined) return ended_part(header)
+
+	const part = `${HEADER_ICONS.heartbeat} ${span_of(age).padStart(width)}`
 
 	return mark === 'running' ? aged(part, age) : part
 }
 
+// A run's age over the `💓`, or over the minute an ended run ended: the shorter of the two lengths is
+// right-aligned to the longer, so the digits stand in one column when only one has passed ten hours.
+function time_parts(header: BoardHeader, mark: RunMark): Array<string> {
+	const elapsed = span_of((header.ended_ms ?? header.now_ms) - header.started_ms)
+	const age = age_of(header)
+	const width = Math.max(elapsed.length, age === undefined ? 0 : span_of(age).length)
+
+	return [`${HEADER_ICONS.elapsed} ${elapsed.padStart(width)}`, beat_part(header, mark, width)]
+}
+
 // A plan fetch is said only when it failed — the board otherwise keeps quiet about a routine read.
 function plan_warning(header: BoardHeader): string | undefined {
 	const failed = header.plan_failed_ms
@@ -152,23 +192,6 @@ function loading_part(header: BoardHeader): string | undefined {
 	return is_plan_loading && spinner !== undefined ? `${HEADER_ICONS.loading} ${spinner}` : undefined
 }
 
-// A running run's age and time left before the cut-off, or an ended run's frozen duration and the
-// minute it ended — an ended run has no cut-off left.
-function time_parts(header: BoardHeader): Array<string> {
-	const { now_ms, started_ms, ended_ms } = header
-
-	if (ended_ms !== undefined) {
-		return [
-			`⏱ ${elapsed_of(ended_ms - started_ms)}`,
-			`${HEADER_ICONS.ended} ${minute_of(ended_ms)}`,
-		]
-	}
-
-	const cutoff = started_ms + backlog_budget.WHOLE_RUN_BUDGET_MS
-
-	return [`⏱ ${elapsed_of(now_ms - started_ms)}`, `⌛ ${left_of(cutoff - now_ms)}`]
-}
-
 function layout_of(header: BoardHeader): BoardLayout {
 	return header.layout ?? run_board_layout.EMPTY_LAYOUT
 }
@@ -186,14 +209,25 @@ function plus_of(counts: BoardCounts, header: BoardHeader): string {
 	return added > 0 ? ` (+${String(added)})` : ''
 }
 
-// Icon, figure, then bar, as the machine gauges: the settled count is right-aligned to the total's
-// width, so the bar starts in one column as the count grows. Arrivals since the board first looked
-// follow the bar, where they cannot move it.
-function tally_part(counts: BoardCounts, is_read: boolean): string {
+// The plan's total as the tally draws it, unknown until the plan is read.
+function total_of(counts: BoardCounts, header: BoardHeader): string {
+	return is_plan_read(header) ? String(counts.total) : UNKNOWN
+}
+
+// The width the tally and the machine's first figure are both right-aligned to — the wider of a full
+// tally and a full percent — so the progress bar and the gauge under it start in one column, and
+// neither moves as a count or a percent gains a digit.
+function figure_width(total: string): number {
+	return Math.max(PERCENT_WIDTH, `${total}/${total}`.length)
+}
+
+// Icon, figure, then bar, as the machine gauges. Arrivals since the board first looked follow the
+// bar, where they cannot move it.
+function tally_part(counts: BoardCounts, header: BoardHeader): string {
 	const { settled } = counts
-	const total = is_read ? String(counts.total) : UNKNOWN
-	const tally = `${String(settled)}/${total}`.padStart(`${total}/${total}`.length)
-	const bar = is_read ? bar_of(settled, counts.total) : bar_of(0, 0)
+	const total = total_of(counts, header)
+	const tally = `${String(settled)}/${total}`.padStart(figure_width(total))
+	const bar = is_plan_read(header) ? bar_of(settled, counts.total) : bar_of(0, 0)
 
 	return `${STATE_ICONS.merged} ${tally} ${bar}`
 }
@@ -202,47 +236,20 @@ function progress_parts(counts: BoardCounts, header: BoardHeader): Array<string>
 	const is_read = is_plan_read(header)
 
 	return [
-		`${tally_part(counts, is_read)}${is_read ? plus_of(counts, header) : ''}`,
+		`${tally_part(counts, header)}${is_read ? plus_of(counts, header) : ''}`,
 		`${STATE_ICONS.running} ${String(counts.running)}`,
 		`${STATE_ICONS.waiting} ${is_read ? String(counts.remaining) : UNKNOWN}`,
 		`${STATE_ICONS.parked} ${String(counts.parked)}`,
 	]
 }
 
-// The run's mark and its progress, then how fresh its stream is and what its plan read is doing.
-function state_line(counts: BoardCounts, header: BoardHeader): string {
-	const mark = mark_of(header, counts.running)
-	const parts = [
-		run_part(mark, header.spinner),
-		...progress_parts(counts, header),
-		heartbeat_part(header, mark),
-		loading_part(header),
-		plan_warning(header),
-	]
+// The run's progress, then what its plan read is doing.
+function progress_part(counts: BoardCounts, header: BoardHeader): string {
+	const parts = [...progress_parts(counts, header), loading_part(header), plan_warning(header)]
 
 	return parts.filter((part) => part !== undefined).join(GAP)
 }
 
-function idle_line(idle: IdleWindow, now_ms: number): string {
-	const ending = idle.bound === 'idle' ? WORDS.idle_end_idle : WORDS.idle_end_run
-	const left = `${elapsed_of(idle.until_ms - now_ms)} ${WORDS.idle_left}`
-	const until = `${WORDS.idle_until} ${clock_of(idle.until_ms)} (${left}) → ${ending}`
-	const next_check = `${WORDS.next_check} ${clock_of(backlog_idle.next_check_ms(idle))}`
-
-	return `${INDENT}${RUN_MARKS.idle.glyph} ${until} · ${next_check}`
-}
-
-// The wait, under the header's blank line, drawn only while it is what the run is doing: no child
-// running and the run not ended. The children running are the run's own, read
-// locally, so a board still waiting on GitHub never draws a running run as waiting.
-function idle_lines(header: BoardHeader): Array<string> {
-	const { idle, is_stopped } = header.activity
-
-	if (is_stopped || idle === undefined || counts_of(layout_of(header)).running > 0) return []
-
-	return ['', idle_line(idle, header.now_ms)]
-}
-
 // The gauges the machine line draws: every one on a screen, the memory alone in a chat.
 function machine_of(header: BoardHeader): MachineGauges | undefined {
 	const { machine } = header
@@ -257,19 +264,35 @@ const MACHINE_UNKNOWN = [HEADER_ICONS.cpu, HEADER_ICONS.memory, HEADER_ICONS.swa
 	.map((icon) => `${icon} ${UNKNOWN}`)
 	.join(GAP)
 
-// The time, then the machine the run is on.
-function clock_line(header: BoardHeader): string {
-	const machine = run_board_machine.line_of(machine_of(header)) ?? MACHINE_UNKNOWN
+// The machine the run is on, its first figure as wide as the tally over it.
+function machine_part(counts: BoardCounts, header: BoardHeader): string {
+	const width = figure_width(total_of(counts, header))
 
-	return [...time_parts(header), machine].join(GAP)
+	return run_board_machine.line_of(machine_of(header), width) ?? MACHINE_UNKNOWN
 }
 
-// The run's state with its progress, then the time with the machine, in every state the board can be in.
+// Both lines' cells of one column, the narrower padded to the wider as the terminal counts them.
+function column_of(cells: ReadonlyArray<string>): Array<string> {
+	const width = Math.max(...cells.map((cell) => run_board_fit.width_of(cell)))
+
+	return cells.map((cell) => cell_of(cell, width))
+}
+
+// The run's name, age and progress, then its repository, heartbeat and machine under them, in every
+// state the board can be in.
 function header_lines(header: BoardHeader): Array<string> {
-	return [state_line(counts_of(layout_of(header)), header), clock_line(header)]
+	const counts = counts_of(layout_of(header))
+	const mark = mark_of(header, counts.running)
+	const columns = [
+		column_of([run_part(mark, header.spinner), repo_part(header, mark)]),
+		column_of(time_parts(header, mark)),
+		[progress_part(counts, header), machine_part(counts, header)],
+	]
+
+	return [0, 1].map((line) => columns.map((column) => column[line]).join(GAP))
 }
 
-const run_board_header = { counts_of, header_lines, idle_lines, is_plan_read }
+const run_board_header = { counts_of, header_lines, is_plan_read }
 
 export { run_board_header }
 export type { BoardCounts, BoardForm, BoardHeader }

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

@@ -6,16 +6,16 @@ import type { BoardNote } from './run-board-notes'
 import type { Phase } from './run-board-phase'
 import type { ItemState } from './run-board-status'
 
-// The words and the clock `run:board` draws with. A moment on the board is a local `HH:MM:SS` clock;
-// how long something has run is a short `MM:SS`, so a person reads the board against the clock on
-// their own screen.
+// The words and the clock `run:board` draws with. A moment on the board is a local clock, `HH:MM`
+// where a person reads it to the minute; how long a row or the heartbeat has run is a short `MM:SS`,
+// and how long the run has run or its wait has left is `H:MM:SS` — two separators are a length and one
+// is a time of day, so the header's time column never reads a length as a moment.
 
 const CLOCK_WIDTH = 2
 const CLOCK_PAD = '0'
 const MS_PER_SECOND = 1000
 const SECONDS_PER_MINUTE = 60
 const MINUTES_PER_HOUR = 60
-const MS_PER_MINUTE = MS_PER_SECOND * SECONDS_PER_MINUTE
 // Every gauge is this wide — the plan, the machine and a row's phase.
 const BAR_WIDTH = 10
 // A centered square done and a thin line left: the shapes alone tell the two apart where no color is
@@ -58,11 +58,6 @@ const WORDS = {
 	followup: 'followup',
 	report: 'report',
 	failed: 'failed',
-	idle_until: 'wait ends',
-	idle_left: 'left',
-	idle_end_idle: 'ends and reports if nothing new',
-	idle_end_run: 'ends at the whole-run cut-off and reports',
-	next_check: 'next check',
 	notes: 'findings and decisions',
 	more: 'more',
 	filed: 'filed',
@@ -168,13 +163,16 @@ const KIND_WORDS: Readonly<Record<FiledKind, keyof Words>> = {
 }
 
 // The header's gauges and marks. ⚡ rather than 🔥: a fire beside a gauge drawn green reads as an
-// alarm.
+// alarm. ⏰ rather than ⏱, a text symbol some terminals draw one column wide: under it the 💓's digits
+// would stand a column off.
 const HEADER_ICONS = {
 	cpu: '⚡',
 	memory: '🧠',
 	swap: '💾',
 	ended: '🔚',
 	loading: '⏳',
+	elapsed: '⏰',
+	heartbeat: '💓',
 } as const
 
 // **The machine gauges' three colors, decided here alone**: Activity Monitor's green, yellow and red
@@ -207,8 +205,8 @@ function minute_of(ms: number): string {
 	return [date.getHours(), date.getMinutes()].map((value) => two_digits(value)).join(':')
 }
 
-// How long something has run, as `MM:SS` whose minutes never carry into hours (`61:05`), so the header
-// and every row read one short column; a negative span reads as zero.
+// How long a row's child has run, as `MM:SS` whose minutes never carry into hours (`61:05`), so every
+// row reads one short column; a negative span reads as zero.
 function elapsed_of(ms: number): string {
 	const seconds = Math.floor(Math.max(0, ms) / MS_PER_SECOND)
 	const minutes = Math.floor(seconds / SECONDS_PER_MINUTE)
@@ -216,12 +214,15 @@ function elapsed_of(ms: number): string {
 	return `${two_digits(minutes)}:${two_digits(seconds % SECONDS_PER_MINUTE)}`
 }
 
-// How long is left, as `7h38m`; a deadline already passed reads as zero.
-function left_of(ms: number): string {
-	const minutes = Math.floor(Math.max(0, ms) / MS_PER_MINUTE)
+// How long the run has run or its stream has been silent, as `H:MM:SS` with the hours not padded; a negative
+// span reads as zero. Always three fields, so a run under an hour (`0:03:25`) never reads as a time.
+function span_of(ms: number): string {
+	const seconds = Math.floor(Math.max(0, ms) / MS_PER_SECOND)
+	const minutes = Math.floor(seconds / SECONDS_PER_MINUTE)
 	const hours = Math.floor(minutes / MINUTES_PER_HOUR)
+	const tail = [minutes % MINUTES_PER_HOUR, seconds % SECONDS_PER_MINUTE]
 
-	return `${String(hours)}h${two_digits(minutes % MINUTES_PER_HOUR)}m`
+	return [String(hours), ...tail.map((value) => two_digits(value))].join(':')
 }
 
 function is_shade(color: Paint): color is Shade {
@@ -289,9 +290,9 @@ const run_board_labels = {
 	bar_of,
 	clock_of,
 	elapsed_of,
-	left_of,
 	minute_of,
 	painted,
+	span_of,
 	spinner_of,
 }