@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/rules/worktree-guard.ts

@@ -17,12 +17,22 @@ import { shell_segments } from './shell-segments'
 // that stash findable and poppable by `pnpm josh stash:pop`, which is the whole of `operating-rules.md`'s
 // safety argument; the forms it warns against are the *positional/bare* ones. So `git stash push -m`
 // (with or without `-u`) and the read-only `git stash list` / `show` pass, and everything else — bare
-// `git stash`, a message-less push, `pop` / `apply` / `drop` / `save` / `clear` — is refused.
+// `git stash`, a message-less push, `pop` / `apply` / `drop` / `save` / `clear` — is refused. Those
+// flows now push with `pnpm josh stash:push` (joshuafolkken/kit#4131), invisible here; the raw message
+// form still passes for a procedure written before it.
 //
 // **The refusal names the way on for a handed-over stash.** joshuafolkken/kit#3630's plan restored a
 // stash with `git stash apply`, and the lane parked on how to apply it instead of popping by message;
 // the reason now says the substitution is the run's own to make (joshuafolkken/kit#3648).
 //
+// **The refusal names the way back for a single file.** A lane that refused `git checkout -- <file>`
+// reverted its own edit by hand with `Edit` and left a line behind, so a green record landed on the
+// wrong tree (joshuafolkken/kit#4988). The named restore writes HEAD's bytes over that one file, carries
+// no body inline (`file-edits.md`), and no row refuses it. It reverses the file's unstaged diff, so a
+// staged change (the user's) stays, `<path>` is read from the shell's directory like any pathspec,
+// nothing is emptied before git runs (a `git show HEAD:<path> > <path>` redirect is), and an untracked
+// path has no diff to reverse.
+//
 // **It fires on every occurrence**, for the reason `git-force.ts` does: discarding the working tree is
 // destructive each time it is issued.
 
@@ -117,28 +127,43 @@ function is_unauthorized_segment(segment: string): boolean {
 }
 
 function is_unauthorized_worktree_change(command: string): boolean {
-	return shell_segments.segments_of(command).some((segment) => is_unauthorized_segment(segment))
+	return shell_segments.commands_of(command).some((segment) => is_unauthorized_segment(segment))
 }
 
-// The instruction in the shape a refusal can carry: what the command touches, the authorized route,
-// and — for a stash — the message form that is allowed. `pnpm josh git` and `pnpm josh stash:pop` are
-// invisible to this trigger, so a run that uses them is never refused.
+// The instruction in the shape a refusal can carry: the authorized route — for one file, the restore,
+// limited to this run's own edit (another's uncommitted change is never discarded); for a stash, the
+// message form that is allowed. The refused command is the caller's own, so it is not listed back.
+// The `headline:` opening is what `time-transcript-line.ts` names the guard by. `pnpm josh git` and
+// `pnpm josh stash:pop` are invisible to this trigger, so a run that uses them is never refused.
+const SINGLE_FILE_RESTORE = 'git diff -- <path> | git apply -R'
 const WORKTREE_MUTATION_REASON =
-	'⛔ unauthorized working-tree change: `git checkout --`, `git restore`, `git clean -f`, ' +
-	'`git stash`. A documented flow stashes with `git stash push -u -m "<message>"`; a handed-over ' +
+	"⛔ unauthorized working-tree change: undo only this run's edit: " +
+	`\`${SINGLE_FILE_RESTORE}\`. A documented flow stashes with ` +
+	'`pnpm josh stash:push "<message>"`; a handed-over ' +
 	'stash is `pnpm josh stash:pop "<message>"`; record the substitution on the Issue (Tier A) unless ' +
 	'the plan says why the owner keeps the stash: then stop and confirm. It fires on every occurrence ' +
 	'(`operating-rules.md`).'
+// The opening before joshuafolkken/kit#4988, so `rule-value.ts` still credits a refusal it delivered.
+const FORMER_OPENING = '⛔ unauthorized working-tree change: `git checkout --`, `git restore`'
 
 const ROW = {
 	id: 'worktree-mutation',
 	is_trigger: bash_triggers.on_bash_command(is_unauthorized_worktree_change),
 	reason: WORKTREE_MUTATION_REASON,
+	former_reasons: [FORMER_OPENING],
 	decide: (): boolean => true,
+	about: {
+		title: 'Unauthorized work-tree mutation',
+		topic: '`operating-rules.md`',
+		fires:
+			'`git checkout -- <path>` / `git restore <path>` / forced `git clean -f` / an unauthorized `git stash` (bare, push without a message, positional pop). Every occurrence',
+		quiet: `\`git stash push -m\`, \`git stash list\`, \`pnpm josh git\`, \`pnpm josh stash:push\`, \`pnpm josh stash:pop\`, \`${SINGLE_FILE_RESTORE}\``,
+	},
 }
 
 const worktree_guard = {
 	ROW,
+	SINGLE_FILE_RESTORE,
 	WORKTREE_MUTATION_REASON,
 	is_unauthorized_worktree_change,
 	touches_worktree,

package/scripts/run/board/run-board-app-name.ts

@@ -0,0 +1,23 @@
+import path from 'node:path'
+
+// The name an app is drawn under on `run:board`'s 💻 processes section, computed from its command.
+// `run-board-process-groups.ts` remembers each command's answer, so a redraw names only the processes
+// new since the last one (joshuafolkken/kit#4263).
+
+const APP_SUFFIX = '.app'
+const COMMAND_SEPARATOR = ' '
+
+// An app's name: the outermost `.app` bundle its executable sits in, else its command's own name.
+function app_of(command: string): string {
+	const bundle = command.split(path.sep).find((part) => part.endsWith(APP_SUFFIX))
+
+	if (bundle !== undefined) return bundle.slice(0, -APP_SUFFIX.length)
+
+	const executable = command.startsWith(path.sep) ? command : command.split(COMMAND_SEPARATOR)[0]
+
+	return path.basename(executable ?? command)
+}
+
+const run_board_app_name = { app_of }
+
+export { run_board_app_name }

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

@@ -1,24 +1,25 @@
-#!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
-import { fileURLToPath } from 'node:url'
 import { styleText } from 'node:util'
-import { core_budget } from '#scripts/gate/core-budget'
-import { machine_capacity } from '#scripts/gate/machine-capacity'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { run_progress } from '#scripts/run/progress/run-progress'
 import { run_progress_read } from '#scripts/run/progress/run-progress-read'
 import terminalLink from 'terminal-link'
 import { run_board_closed } from './run-board-closed'
 import { run_board_every } from './run-board-every'
+import { run_board_fold } from './run-board-fold'
+import { run_board_gather } from './run-board-gather'
+import { run_board_gather_live } from './run-board-gather-live'
+import { run_board_gather_thread } from './run-board-gather-thread'
+import { run_board_keys, type KeyReading } from './run-board-keys'
 import { run_board_labels } from './run-board-labels'
-import { run_board_plan } from './run-board-plan'
-import { run_board_read } from './run-board-read'
+import { run_board_plan_shared } from './run-board-plan-shared'
 import { run_board_screen, type Screen } from './run-board-screen'
+import { run_board_snapshot } from './run-board-snapshot'
 import { run_board_spin } from './run-board-spin'
 import type { BoardPorts } from './run-board-state'
 import { run_board_thanks_read } from './run-board-thanks-read'
 import { run_board_tick } from './run-board-tick'
-import { run_board_usage_read } from './run-board-usage-read'
 
 // `josh run:board` — a full-screen board of the running `backlogrun`, redrawn once a second, its
 // spinners turned between redraws, for a person to keep open beside the run. What one redraw reads,
@@ -26,7 +27,6 @@ import { run_board_usage_read } from './run-board-usage-read'
 // terminal around it. A run that ended stays on screen until the next one starts; with no run in this
 // checkout it reads nothing from GitHub and waits.
 
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ONCE_FLAG = '--once'
@@ -48,13 +48,10 @@ function on_exit(leave: () => void): void {
 	process.once('SIGTERM', () => process.exit(SIGTERM_EXIT_CODE))
 }
 
-const LIVE_PORTS: BoardPorts = {
-	read_plan: async (scope) => await run_board_plan.read_plan(scope),
-	read_local: run_board_read.read_local,
-	read_machine: machine_capacity.read_sample,
-	read_waits: () => core_budget.budget_waits(),
-	read_usage: run_board_usage_read.usage_reader(),
+const LIVE_PORTS: Omit<BoardPorts, 'gather'> = {
+	read_plan: async (scope) => await run_board_plan_shared.read(scope),
 	read_closed: async (issues) => await run_board_closed.read_all(issues),
+	snapshot: run_board_snapshot.file_store(),
 	read_thanks: async () => await run_board_thanks_read.read_thanks(),
 	now: () => Date.now(),
 	write: (frame) => process.stdout.write(frame),
@@ -64,6 +61,20 @@ const LIVE_PORTS: BoardPorts = {
 	// Read on every redraw, so a resized pane is fitted on the next one.
 	size: () => ({ rows: process.stdout.rows, columns: process.stdout.columns }),
 	form: 'screen',
+	keys: {
+		is_tty: process.stdin.isTTY,
+		raw: (is_raw) => {
+			process.stdin.setRawMode(is_raw)
+		},
+		listen: (on_data) => {
+			process.stdin.setEncoding('utf8').on('data', on_data).resume()
+		},
+		// Stops reading, so stdin no longer holds the process open.
+		close: () => {
+			process.stdin.pause()
+		},
+		interrupt: () => process.exit(SIGINT_EXIT_CODE),
+	},
 	mark: async () => {
 		run_progress_read.mark(await run_progress_read.stamp_target(), Date.now())
 	},
@@ -76,14 +87,27 @@ const LIVE_PORTS: BoardPorts = {
 	},
 }
 
+// A live board reads on its worker thread, so no read stops its spinner; a single frame has no spinner
+// to stop, and reads where it draws.
+function live_ports(is_live: boolean): BoardPorts {
+	const gather = is_live
+		? run_board_gather_thread.worker_gatherer()
+		: run_board_gather.frame_gatherer(run_board_gather_live.ports_of(false))
+
+	return { ...LIVE_PORTS, gather }
+}
+
 // Every frame starts from the top of the alternate screen, erasing what the last one left below it, and
 // ends on the line that says closing the screen leaves the run going — only a screen a person can
 // close says it, and it is the first line to give way to a short pane. Nothing follows the last line,
 // so a frame that fills the pane never scrolls the header off the top.
+// The keys are named under it where a person can type them.
 function framed(ports: BoardPorts, screen: Screen): BoardPorts {
+	const keys = ports.folded === undefined ? [] : [run_board_fold.KEYS_LINE]
+
 	return {
 		...ports,
-		footer: ['', styleText('dim', WORDS.keeps_running)],
+		footer: ['', ...[WORDS.keeps_running, ...keys].map((line) => styleText('dim', line))],
 		write: (frame) => {
 			ports.write(`${screen.frame}${frame.replace(TRAILING_NEWLINE, '')}`)
 		},
@@ -91,13 +115,15 @@ function framed(ports: BoardPorts, screen: Screen): BoardPorts {
 }
 
 // Leaves the alternate screen once, whichever path gets there first: a second leave would restore the
-// cursor saved on entering and draw over whatever was printed after the first.
-function leaver(ports: BoardPorts, screen: Screen): () => void {
+// cursor saved on entering and draw over whatever was printed after the first. The terminal leaves raw
+// mode with it.
+function leaver(ports: BoardPorts, screen: Screen, keys: KeyReading): () => void {
 	let has_left = false
 
 	return () => {
 		if (has_left) return
 		has_left = true
+		keys.stop?.()
 		ports.write(screen.leave)
 	}
 }
@@ -121,13 +147,14 @@ async function redraw_forever(ports: BoardPorts, screen: Screen): Promise<void>
 // lands on the normal screen rather than vanishing with the alternate one.
 async function watch(ports: BoardPorts): Promise<void> {
 	const screen = run_board_screen.screen_of('live')
-	const leave = leaver(ports, screen)
+	const keys = run_board_keys.read_keys(ports.keys)
+	const leave = leaver(ports, screen, keys)
 
 	ports.write(screen.enter)
 	ports.on_exit(leave)
 
 	try {
-		await redraw_forever(ports, screen)
+		await redraw_forever({ ...ports, folded: keys.folded }, screen)
 	} finally {
 		leave()
 	}
@@ -162,25 +189,35 @@ async function push_every(minutes: string | undefined, ports: BoardPorts): Promi
 		return SUCCESS_EXIT_CODE
 	}
 
-	await run_board_every.push_until_ended(ports, interval * run_progress.MS_PER_MINUTE)
+	await run_board_every.push_until_ended(ports, interval * MS_PER_MINUTE)
 
 	return SUCCESS_EXIT_CODE
 }
 
-async function draw(flag: string, ports: BoardPorts): Promise<void> {
+// The ports a test hands in, else the live ones.
+function ports_for(ports: BoardPorts | undefined, is_live: boolean): BoardPorts {
+	return ports ?? live_ports(is_live)
+}
+
+async function draw(flag: string, ports: BoardPorts | undefined): Promise<void> {
 	if (flag === CHAT_FLAG) {
-		await answer(ports)
+		await answer(ports_for(ports, false))
 
 		return
 	}
 
-	const mode = run_board_screen.mode_of({ is_tty: ports.is_tty, is_once: flag === ONCE_FLAG })
+	const { is_tty } = ports ?? LIVE_PORTS
+	const mode = run_board_screen.mode_of({ is_tty, is_once: flag === ONCE_FLAG })
+
+	if (mode === 'live') {
+		await watch(ports_for(ports, true))
+
+		return
+	}
 
 	// One plain frame stays on the terminal after the command, so it draws the still icons rather than a
 	// spinner frame frozen mid-turn.
-	const once_ports = { ...ports, is_tty: false, size: undefined }
-
-	await (mode === 'live' ? watch(ports) : tick(FRESH_STATE, once_ports))
+	await tick(FRESH_STATE, { ...ports_for(ports, false), is_tty: false, size: undefined })
 }
 
 function is_every(flag: string, rest: ReadonlyArray<string>): boolean {
@@ -191,10 +228,10 @@ function is_refused(flag: string, rest: ReadonlyArray<string>): boolean {
 	return rest.length > 0 || !FLAGS.has(flag)
 }
 
-async function run(argv: ReadonlyArray<string>, ports: BoardPorts = LIVE_PORTS): Promise<number> {
+async function run(argv: ReadonlyArray<string>, ports?: BoardPorts): Promise<number> {
 	const [flag = '', ...rest] = argv
 
-	if (is_every(flag, rest)) return await push_every(rest[0], ports)
+	if (is_every(flag, rest)) return await push_every(rest[0], ports_for(ports, false))
 	if (is_refused(flag, rest)) return refuse()
 
 	await draw(flag, ports)
@@ -204,8 +241,4 @@ async function run(argv: ReadonlyArray<string>, ports: BoardPorts = LIVE_PORTS):
 
 const run_board_cli = { DISABLED_NOTICE, USAGE, run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
-}
-
 export { run_board_cli }

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

@@ -0,0 +1,94 @@
+import { lane_state } from '#scripts/lane/lane-state'
+import { run_board_kind } from './run-board-kind'
+import type { BoardRow, RowRead } from './run-board-layout'
+import type { ItemStatus } from './run-board-status'
+
+// The lanes on `run:board` that are not this run's (joshuafolkken/kit#4200, #4260, #4269): an earlier
+// run's lane that still holds a place under the limit, drawn after the run's own lanes with what its
+// record and the stream say it is doing — its phase, its time, its usage and its newest activity, as a
+// row of this run's is — and a lane with no lane state record, drawn unknown. Neither is ever counted
+// as this run's.
+
+// The earlier run's lanes still holding a place, what each is doing, and the open lanes with no record.
+interface EarlierLanes {
+	lanes: ReadonlyArray<string>
+	statuses?: ReadonlyMap<number, ItemStatus> | undefined
+	unknown?: ReadonlyArray<string> | undefined
+}
+
+const NO_EARLIER: EarlierLanes = { lanes: [] }
+
+// What an unknown lane's row says after its title: it has no record, and keeps its place.
+const UNKNOWN_TAIL = lane_state.NO_STATE_HINT
+
+// The mark an earlier run's running lane leads with in place of its phase (joshuafolkken/kit#4269),
+// two columns wide as every row icon is (`run-board-labels.ts`, kept out of it by its size).
+const EARLIER_ICON = '🧳'
+
+// A child working now — this run's, or an earlier run's lane holding a place.
+function is_live(row: BoardRow): boolean {
+	return row.state === 'running'
+}
+
+function base_row(
+	number: number,
+	read: RowRead,
+): Pick<BoardRow, 'number' | 'title' | 'kind' | 'priority'> {
+	const labels = read.labels.get(number)
+
+	return {
+		number,
+		title: read.titles.get(number),
+		kind: run_board_kind.kind_of(labels),
+		priority: run_board_kind.priority_of(labels),
+	}
+}
+
+// The row is drawn as its status says, marked as an earlier run's (`is_earlier`).
+function earlier_row(number: number, status: ItemStatus | undefined, read: RowRead): BoardRow {
+	return {
+		...base_row(number, read),
+		state: status?.state ?? 'running',
+		status,
+		waits: [],
+		is_earlier: true,
+	}
+}
+
+function unknown_row(number: number, read: RowRead): BoardRow {
+	return {
+		...base_row(number, read),
+		state: 'unknown',
+		status: undefined,
+		waits: [],
+		reason: { tail: UNKNOWN_TAIL },
+	}
+}
+
+function apart_of(
+	lanes: ReadonlyArray<string>,
+	statuses: ReadonlyMap<number, ItemStatus>,
+): Array<number> {
+	return lanes.map(Number).filter((number) => !statuses.has(number))
+}
+
+// An earlier run's lane holding a place, then a lane with no record, unless this run has touched its
+// issue since.
+function rows_of(
+	earlier: EarlierLanes,
+	statuses: ReadonlyMap<number, ItemStatus>,
+	read: RowRead,
+): Array<BoardRow> {
+	const lanes = apart_of(earlier.lanes, statuses)
+	const unknown = apart_of(earlier.unknown ?? [], statuses)
+
+	return [
+		...lanes.map((number) => earlier_row(number, earlier.statuses?.get(number), read)),
+		...unknown.map((number) => unknown_row(number, read)),
+	]
+}
+
+const run_board_earlier = { EARLIER_ICON, NO_EARLIER, UNKNOWN_TAIL, is_live, rows_of }
+
+export { run_board_earlier }
+export type { EarlierLanes }

package/scripts/run/board/run-board-ending-reason.ts

@@ -0,0 +1,71 @@
+import { lane_withdraw } from '#scripts/lane/lane-withdraw'
+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_stalled } from '#scripts/run/park/run-stalled'
+
+// Why a child's park or withdraw ended it, in the ending event's own words — the reason its board row
+// draws and its park note carries.
+
+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
+// `#<N> withdrawn by <who>: <reason>` — every withdrawer `lane-withdraw.ts` names.
+const WITHDRAW_PREFIX = new RegExp(
+	String.raw`^#\d+ withdrawn by (?:${lane_withdraw.WITHDRAWER_NAMES.join('|')}):\s*`,
+	'u',
+)
+
+// `#<N> parked (needs-decision)` reads as the reason `needs-decision`; a bare park has none.
+function park_reason(event: RunEvent): string {
+	const rest = event.text.replace(PARK_PREFIX, '')
+
+	return PARENTHESES.exec(rest)?.groups?.['inner'] ?? rest
+}
+
+// A withdraw's reason after its prefix; a text in any other shape carries none.
+function withdraw_reason(event: RunEvent): string {
+	const rest = event.text.replace(WITHDRAW_PREFIX, '')
+
+	return rest === event.text ? '' : rest.trim()
+}
+
+// A `run:stalled` park reads as its cause and the action that resumes it (`run-stalled.ts`); any other
+// park as its reason.
+function park_row_reason(event: RunEvent): string {
+	const reason = park_reason(event)
+	const cause = run_stalled.cause_of(reason)
+	const issue = run_event_scope.issue_named(event)
+
+	return cause === undefined || issue === undefined ? reason : run_stalled.row_text(issue, cause)
+}
+
+// The reason an ending event gives, `undefined` for an event that is neither a park nor a withdraw or
+// that gives none.
+function reason_of(event: RunEvent): string | undefined {
+	if (event.kind === KIND.PARK) return park_row_reason(event) || undefined
+
+	return event.kind === KIND.WITHDRAW ? withdraw_reason(event) || undefined : undefined
+}
+
+interface EndingRecord {
+	reason?: string
+	elapsed_ms?: number
+}
+
+// What an ending event records for its row: the reason it gives and the lane time its writer recorded
+// (joshuafolkken/kit#4481), each only where the event carries it.
+function recorded_of(event: RunEvent): EndingRecord {
+	const reason = reason_of(event)
+	const { elapsed_ms } = event
+
+	return {
+		...(reason !== undefined && { reason }),
+		...(elapsed_ms !== undefined && { elapsed_ms }),
+	}
+}
+
+const run_board_ending_reason = { park_reason, reason_of, recorded_of }
+
+export { run_board_ending_reason }

package/scripts/run/board/run-board-estimate-schedule.ts

@@ -0,0 +1,103 @@
+import { run_board_labels } from './run-board-labels'
+import type { BoardRow } from './run-board-layout'
+
+// Where each waiting child lands on the lanes (joshuafolkken/kit#4319): onto the lane that frees
+// first, but never before what it waits on ends — a 🔗 blocker, the 📂 child holding its path, the
+// running lanes a 🧍 `run:solo` child waits out, the 🙅 solo child ahead of it, the 📋 issue a named run
+// starts it after — nor before a `run:solo` child ends: a running one, or a 🧍 one placed ahead, which
+// itself starts once every lane placed before it has freed. A child waiting on an issue the board does
+// not carry waits past this run, so it is left out.
+
+const { WAIT_ICONS } = run_board_labels
+const AFTER_ICONS: ReadonlySet<string> = new Set([
+	WAIT_ICONS.path,
+	WAIT_ICONS.solo,
+	WAIT_ICONS.solo_ahead,
+	WAIT_ICONS.named,
+])
+
+interface Lanes {
+	// When each lane frees, from now.
+	free: Array<number>
+	// When each child on the board ends, from now.
+	ends: Map<number, number>
+	// No waiting child starts before this — the end of a `run:solo` child running or placed.
+	floor: number
+	per_child: number
+}
+
+interface Pending {
+	number: number
+	after: ReadonlyArray<number>
+	// A 🧍 `run:solo` child: it starts once every lane is free and lets none start beside it.
+	is_solo: boolean
+}
+
+// The issues a row's reason says it starts after, none for a wait no child's end lifts.
+function named_of(reason: BoardRow['reason']): ReadonlyArray<string> {
+	if (reason?.icon === undefined || !AFTER_ICONS.has(reason.icon)) return []
+
+	return reason.issues ?? []
+}
+
+// The issues a waiting row starts after: its standing blockers, and those its reason names.
+function pending_of(row: BoardRow): Pending {
+	const after = new Set([...row.waits, ...named_of(row.reason)])
+
+	const is_solo = row.reason?.icon === WAIT_ICONS.solo
+
+	return { number: row.number, after: [...after].map(Number), is_solo }
+}
+
+function is_ready(pending: Pending, lanes: Lanes): boolean {
+	return pending.after.every((issue) => lanes.ends.has(issue))
+}
+
+// The lane freeing latest by the time the child can start, so a child waiting on an end leaves the
+// lane free sooner to a child ready before it; the lane free first where none has freed by then.
+function lane_for(free: ReadonlyArray<number>, ready: number): number {
+	const fits = free.filter((at) => at <= ready)
+
+	return free.indexOf(fits.length > 0 ? Math.max(...fits) : Math.min(...free))
+}
+
+function place(pending: Pending, lanes: Lanes): void {
+	const waited = pending.after.map((issue) => lanes.ends.get(issue) ?? 0)
+	const busy = pending.is_solo ? lanes.free : []
+	const ready = Math.max(lanes.floor, ...waited, ...busy)
+	const lane = lane_for(lanes.free, ready)
+	const end = Math.max(lanes.free[lane] ?? 0, ready) + lanes.per_child
+
+	lanes.free[lane] = end
+	lanes.ends.set(pending.number, end)
+	if (pending.is_solo) lanes.floor = end
+}
+
+// One pass over the children not yet placed, placing each whose waits have ended; the rest are left.
+function pass(pending: ReadonlyArray<Pending>, lanes: Lanes): Array<Pending> {
+	const ready = pending.filter((entry) => is_ready(entry, lanes))
+
+	for (const entry of ready) place(entry, lanes)
+
+	return pending.filter((entry) => !lanes.ends.has(entry.number))
+}
+
+// The time the last lane ends, the waiting rows placed pass after pass until a pass places none.
+function end_of(waiting: ReadonlyArray<BoardRow>, lanes: Lanes): number {
+	let left = waiting.map((row) => pending_of(row))
+	let placed = Infinity
+
+	while (left.length > 0 && placed > 0) {
+		const next = pass(left, lanes)
+
+		placed = left.length - next.length
+		left = next
+	}
+
+	return Math.max(...lanes.free)
+}
+
+const run_board_estimate_schedule = { end_of }
+
+export { run_board_estimate_schedule }
+export type { Lanes }

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

@@ -0,0 +1,98 @@
+import { run_board_estimate_schedule, type Lanes } from './run-board-estimate-schedule'
+import { run_board_labels } from './run-board-labels'
+import { run_board_layout, type BoardLayout, type BoardRow } from './run-board-layout'
+import { run_board_phase, type Phase } from './run-board-phase'
+import type { ItemStatus } from './run-board-status'
+import type { UsualTimes } from './run-board-usual'
+
+// How long the run has left, from how long each phase usually takes (`run-board-usual.ts`,
+// joshuafolkken/kit#4044). A running child has left what remains of its phase and every phase it has
+// not reached; a waiting child the plan's waves hold takes one child's usual time, stacked onto the
+// lane that frees first once what it waits on has ended (`run-board-estimate-schedule.ts`). A parked
+// child, and one the plan has not reached — a start date or a blocker ahead of it — wait on something
+// no usual time measures, so they are left out. Without a usual time nothing is estimated.
+
+const { HEADER_ICONS, WORDS, minute_span_of } = run_board_labels
+const LEGEND = `${HEADER_ICONS.estimate} ${WORDS.estimate}`
+const ESTIMATE_MARK = '~'
+// A failed ship sends its child back to implement, so it has that phase and every later one left.
+const FAILED_PHASE: Phase = 'failed'
+const RESUMED_PHASE: Phase = 'implement'
+// The phases a child passes in order, a failed ship aside.
+const PATH: ReadonlyArray<Phase> = run_board_phase.PHASES.filter((phase) => phase !== FAILED_PHASE)
+const MIN_LANES = 1
+
+interface EstimateRead {
+	now_ms: number
+	ended_ms: number | undefined
+	layout: BoardLayout | undefined
+	usual?: UsualTimes | undefined
+	lane_limit?: number | undefined
+}
+
+function usual_sum(phases: ReadonlyArray<Phase>, usual: UsualTimes): number {
+	return phases.reduce((sum, phase) => sum + (usual.get(phase) ?? 0), 0)
+}
+
+// The phase a child stands at, as the path counts it.
+function phase_of(status: ItemStatus | undefined): Phase {
+	const phase = status?.track?.at(-1) ?? run_board_phase.LAUNCHED_PHASE
+
+	return phase === FAILED_PHASE ? RESUMED_PHASE : phase
+}
+
+// What a running child has left: its phase's usual time less what it has spent there, then every
+// phase after it.
+function running_left(row: BoardRow, read: EstimateRead, usual: UsualTimes): number {
+	const phase = phase_of(row.status)
+	const spent = read.now_ms - (row.status?.phase_ms ?? read.now_ms)
+	const current = Math.max(0, (usual.get(phase) ?? 0) - spent)
+
+	return current + usual_sum(PATH.slice(PATH.indexOf(phase) + 1), usual)
+}
+
+// The queued rows a lane will take, a decision a person owes left out.
+function waiting_rows(layout: BoardLayout): Array<BoardRow> {
+	const queued: BoardLayout = { ...run_board_layout.EMPTY_LAYOUT, queued: layout.queued }
+
+	return run_board_layout.rows_of(queued).filter((row) => row.state === 'waiting')
+}
+
+// The lanes as the running children leave them: each running child's end, the free lanes at zero, and
+// a running `run:solo` child's end as the floor no waiting child starts before.
+function lanes_of(running: ReadonlyArray<BoardRow>, read: EstimateRead, usual: UsualTimes): Lanes {
+	const ends = new Map(running.map((row) => [row.number, running_left(row, read, usual)]))
+	const count = Math.max(read.lane_limit ?? running.length, running.length, MIN_LANES)
+	const free = [...ends.values(), ...Array.from({ length: count - ends.size }, () => 0)]
+	const solo = running.filter((row) => row.is_solo === true).map((row) => ends.get(row.number) ?? 0)
+
+	return { free, ends, floor: Math.max(0, ...solo), per_child: usual_sum(PATH, usual) }
+}
+
+// How long the run has left, `undefined` where nothing is left to run or no usual time is known.
+function left_ms(read: EstimateRead): number | undefined {
+	const { layout, usual } = read
+
+	if (layout === undefined || usual === undefined || usual.size === 0) return undefined
+
+	const running = layout.active.filter((row) => row.state === 'running')
+	const waiting = waiting_rows(layout)
+
+	if (running.length + waiting.length === 0) return undefined
+
+	return run_board_estimate_schedule.end_of(waiting, lanes_of(running, read, usual))
+}
+
+// `🎯 ~25′`, `undefined` for an ended run or one with nothing to estimate.
+function part_of(read: EstimateRead): string | undefined {
+	const left = read.ended_ms === undefined ? left_ms(read) : undefined
+
+	return left === undefined
+		? undefined
+		: `${HEADER_ICONS.estimate} ${ESTIMATE_MARK}${minute_span_of(left)}`
+}
+
+const run_board_estimate = { LEGEND, left_ms, part_of }
+
+export { run_board_estimate }
+export type { EstimateRead }