@joshuafolkken/kit 1.1455.0 → 1.1514.0

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

@@ -2,6 +2,7 @@
 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 { telegram_notify } from '#scripts/notify/telegram-notify'
 import { run_progress } from '#scripts/run/progress/run-progress'
@@ -51,6 +52,7 @@ 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(),
 	read_closed: async (issues) => await run_board_closed.read_all(issues),
 	read_thanks: async () => await run_board_thanks_read.read_thanks(),

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

@@ -18,10 +18,13 @@ interface ClosedIssue {
 	closed_ms: number | undefined
 	// Closed by a merged pull request, rather than closed by hand.
 	is_merged: boolean
+	// Closed as not planned — withdrawn rather than finished (joshuafolkken/kit#3958).
+	is_not_planned: boolean
 }
 
-const CLOSED_FIELDS = 'title,state,closedAt,labels'
+const CLOSED_FIELDS = 'title,state,stateReason,closedAt,labels'
 const CLOSED_STATE = 'CLOSED'
+const NOT_PLANNED_REASON = 'not_planned'
 const STILL_OPEN = 'open' as const
 
 // What one issue answered: closed, still open, or `undefined` when it could not be read.
@@ -41,6 +44,7 @@ const READ_CONCURRENCY = 4
 const closed_schema = z.looseObject({
 	title: z.string(),
 	state: z.string(),
+	stateReason: z.string().nullish(),
 	closedAt: z.string().nullish(),
 	labels: z.array(issue_label_schema).default([]),
 })
@@ -69,7 +73,9 @@ async function read_closed(issue: number): Promise<ClosedRead> {
 
 	const labels = view.labels.map((label) => label.name)
 
-	return { title: view.title, labels, closed_ms: closed_ms_of(view), is_merged }
+	const is_not_planned = view.stateReason === NOT_PLANNED_REASON
+
+	return { title: view.title, labels, closed_ms: closed_ms_of(view), is_merged, is_not_planned }
 }
 
 async function read_all(

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

@@ -2,6 +2,7 @@ import { run_progress } from '#scripts/run/progress/run-progress'
 import { run_progress_cli } from '#scripts/run/progress/run-progress-cli'
 import type { ClosedAnswer } from './run-board-closed'
 import { run_board_fetch, type Fetch } from './run-board-fetch'
+import { run_board_idle } from './run-board-idle'
 import { run_board_layout, type BoardPlan } from './run-board-layout'
 import type { LocalRead } from './run-board-read'
 import { run_board_state, type BoardPorts, type BoardState, type Pace } from './run-board-state'
@@ -72,8 +73,23 @@ function fold_plan(state: BoardState): BoardState {
 	}
 }
 
-function statuses_for(plan: BoardPlan, local: LocalRead): ReadonlyMap<number, ItemStatus> {
-	return run_board_status.statuses_of(local.events, local.lanes, run_board_layout.numbers_of(plan))
+// joshuafolkken/kit#3969: the planned issues whose open lane may be this run's though the stream never
+// saw it launched. An earlier run's lane is not, so its issue waits until this run launches it.
+function lanes_in_run(plan: BoardPlan, local: LocalRead): ReadonlySet<number> {
+	const earlier = new Set(local.earlier_lanes?.map(Number))
+
+	return new Set([...run_board_layout.numbers_of(plan)].filter((issue) => !earlier.has(issue)))
+}
+
+function statuses_for(
+	state: BoardState,
+	plan: BoardPlan,
+	local: LocalRead,
+): ReadonlyMap<number, ItemStatus> {
+	const in_run = lanes_in_run(plan, local)
+	const stopped = run_board_idle.stopped_of(state.idle_since, state.read_ms)
+
+	return run_board_status.statuses_of(local.events, local.lanes, in_run, stopped)
 }
 
 // The children the run touched that the open listing no longer holds and the board has not read yet.
@@ -83,7 +99,7 @@ function unread_closed(state: BoardState, local: LocalRead): Array<number> {
 
 	if (open === undefined || state.plan === undefined) return []
 
-	const touched = [...statuses_for(state.plan, local).keys()]
+	const touched = [...statuses_for(state, state.plan, local).keys()]
 
 	return touched.filter((issue) => !open.has(issue) && !state.closed.has(issue))
 }

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

@@ -1,5 +1,6 @@
 import { styleText } from 'node:util'
 import { backlog_budget } from '#scripts/backlog/backlog-budget'
+import type { BudgetWait } from '#scripts/gate/core-wait'
 import { run_board_fit } from './run-board-fit'
 import { run_board_fresh } from './run-board-fresh'
 import { run_board_labels } from './run-board-labels'
@@ -65,6 +66,8 @@ interface BoardHeader {
 	machine: MachineGauges | undefined
 	// Each running lane's CPU and memory, `undefined` where none could be read.
 	usages?: LaneUsages | undefined
+	// The claims waiting in the machine-wide core budget (`run-board-render-waits.ts`).
+	budget_waits?: ReadonlyArray<BudgetWait> | undefined
 	// How long each phase usually takes; a running row's phase time is colored against it.
 	usual?: UsualTimes | undefined
 	// The spinner's frame a running run and a running row turn, `undefined` where the output is not a
@@ -107,7 +110,7 @@ function count_state(rows: ReadonlyArray<BoardRow>, state: BoardRow['state']): n
 function counts_of(layout: BoardLayout): BoardCounts {
 	const total = run_board_layout.rows_of(layout).length
 	const parked = count_state(layout.active, 'parked')
-	const settled = count_state(layout.active, 'merged') + parked + count_state(layout.active, 'done')
+	const settled = layout.active.filter((row) => run_board_layout.is_settled(row.state)).length
 	const running = count_state(layout.active, 'running')
 
 	return { total, settled, parked, running, remaining: total - settled - running }

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

@@ -0,0 +1,31 @@
+import { lane_await } from '#scripts/lane/lane-await'
+
+// A lane is drawn stopped only once it has read idle for `lane_await.RECONFIRM_MS`: a boundary cut drops
+// the child's process for a moment before its resume takes over, and one bare probe cannot tell that
+// handoff from a child that died — `lane:await` re-confirms a disappearance over the same window. A live
+// board carries when each lane was first read idle across its reads; a single frame has no earlier read,
+// so it reads the lanes again after the window (`run-board-tick.ts`).
+
+/** When each lane the last read found idle was first read so. */
+type IdleSince = ReadonlyMap<string, number>
+
+const NO_IDLE: IdleSince = new Map()
+
+// The lanes read idle now, each keeping the moment it was first read so; a lane read working drops out.
+function since_of(before: IdleSince, idle: ReadonlyArray<string>, now_ms: number): IdleSince {
+	return new Map(idle.map((lane) => [lane, before.get(lane) ?? now_ms]))
+}
+
+// The lanes idle for the whole window as of the read at `read_ms`; none before any read.
+function stopped_of(since: IdleSince, read_ms: number | undefined): Array<string> {
+	if (read_ms === undefined) return []
+
+	const lasted = [...since].filter(([, at]) => read_ms - at >= lane_await.RECONFIRM_MS)
+
+	return lasted.map(([lane]) => lane)
+}
+
+const run_board_idle = { NO_IDLE, since_of, stopped_of }
+
+export type { IdleSince }
+export { run_board_idle }

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

@@ -43,6 +43,7 @@ const WORDS = {
 	merged: 'merged',
 	parked: 'parked',
 	done: 'done',
+	withdrawn: 'withdrawn',
 	in_progress: 'running',
 	stopped: 'stopped',
 	waiting: 'waiting',
@@ -104,6 +105,7 @@ const STATE_ICONS: Readonly<Record<ItemState, string>> = {
 	waiting: '⏳',
 	human: '🙋',
 	stopped: '🛑',
+	withdrawn: '🚫',
 }
 
 // The blocking edge, chosen on the same rule: ⛓ is a text symbol.

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

@@ -82,7 +82,7 @@ interface Drawn extends Overlay {
 	reason_of: ReasonOf | undefined
 }
 
-const SETTLED_STATES: ReadonlySet<ItemState> = new Set(['merged', 'parked', 'done'])
+const SETTLED_STATES: ReadonlySet<ItemState> = new Set(['merged', 'parked', 'done', 'withdrawn'])
 
 function is_settled(state: ItemState): boolean {
 	return SETTLED_STATES.has(state)

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

@@ -1,7 +1,8 @@
 import type { NamedPlan } from '#scripts/backlog/backlog-plan'
+import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
-import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_spent } from '#scripts/lane/lane-spent'
 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'
@@ -33,21 +34,22 @@ interface LocalRead {
 	is_stranded: boolean
 	// The newest operation of each session of the run, read off the end of its log.
 	operations?: SessionOperations | undefined
-	// How many more lanes the limit allows beside the live ones; `undefined` where the limit could not
-	// be read, so nothing is said about it.
+	// The open lanes no child is working in at this read (`lane-spent.ts`); one is drawn stopped once it
+	// has stayed so (`run-board-idle.ts`).
+	idle_lanes?: ReadonlyArray<string> | undefined
+	// The open lanes that last took a child before the run started — an earlier run's, until this run
+	// dispatches into one again.
+	earlier_lanes?: ReadonlyArray<string> | undefined
+	// How many more lanes the limit allows beside the live ones, as `lane:limit` counts them;
+	// `undefined` where the limit could not be read, so nothing is said about it.
 	free_lanes?: number | undefined
+	// The issues whose lanes hold a place under the limit (`backlog-occupied.ts`), named beside a row
+	// that waits for a free lane.
+	occupied_lanes?: ReadonlyArray<string> | undefined
 	// How long each phase usually takes, from the repository's lane ledger.
 	usual?: UsualTimes | undefined
 }
 
-async function free_lanes_of(lanes: ReadonlyArray<LaneInfo>): Promise<number | undefined> {
-	const choice = await lane_capacity.lane_limit()
-
-	if (choice.kind !== 'limit') return undefined
-
-	return lane_capacity.free_lanes(choice.limit, lane_registry.live_count(lanes))
-}
-
 const NO_SPAN: SpanHere = { span: undefined, resume: undefined, transcript: undefined }
 
 interface SpanHere {
@@ -85,6 +87,13 @@ function sources_of(
 	}
 }
 
+// joshuafolkken/kit#3969: a lane whose last dispatch is unknown is not called earlier.
+function earlier_lanes(lanes: ReadonlyArray<LaneInfo>, started_ms: number): Array<string> {
+	return lanes
+		.filter((lane) => lane.dispatched_ms !== undefined && lane.dispatched_ms < started_ms)
+		.map((lane) => lane.issue)
+}
+
 // `undefined` when no run has started here.
 async function read_local(): Promise<LocalRead | undefined> {
 	const repository = await run_carry.repository_directory()
@@ -94,6 +103,7 @@ async function read_local(): Promise<LocalRead | undefined> {
 
 	const events = run_event_stream.read_events(run_event_stream.target_of(repository))
 	const lanes = await lane_registry.list_lanes()
+	const occupied = await backlog_ready.occupied_lanes(lanes)
 
 	return {
 		started_ms: span.started_ms,
@@ -104,7 +114,10 @@ async function read_local(): Promise<LocalRead | undefined> {
 		resume,
 		is_stranded: run_stranded_detect.is_stranded_at(repository),
 		operations: run_board_operation_read.read(sources_of(repository, lanes, transcript)),
-		free_lanes: await free_lanes_of(lanes),
+		idle_lanes: lane_spent.idle_lanes(lanes),
+		earlier_lanes: earlier_lanes(lanes, span.started_ms),
+		free_lanes: await backlog_ready.free_lanes_beside(lanes),
+		occupied_lanes: occupied.map((lane) => lane.issue),
 		usual: run_board_usual.read(repository),
 	}
 }

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

@@ -5,6 +5,7 @@ import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import type { RunEvent } from '#scripts/run/event/run-event-stream'
 import { run_board_layout, type Overlay, type ReasonOf, type RowReason } from './run-board-layout'
 import { run_board_setup } from './run-board-setup'
+import type { ItemStatus } from './run-board-status'
 
 // Why each waiting row waits — pure, so the words are tested apart from the screen. A row whose lane is
 // being opened says the stage that lane is at; any other says what `backlog:next` would answer for it,
@@ -35,6 +36,9 @@ interface ReasonRead extends Overlay {
 	events: ReadonlyArray<RunEvent>
 	// How many more lanes the limit allows; `undefined` where it could not be read.
 	free_lanes: number | undefined
+	// The issues whose lanes fill the limit, named after `no free lane` so a lane an earlier run left
+	// behind shows on the row it holds back.
+	occupied_lanes?: ReadonlyArray<string> | undefined
 	// A stopped run opens no lane, so a stage its stream ends on is not one any lane is at.
 	is_stopped: boolean
 }
@@ -63,10 +67,13 @@ function is_untriaged_candidate(child: EpicChild, read: ReasonRead): boolean {
 	return !epic_triage.is_triaged(child) && !run_board_layout.is_blocked(child, read)
 }
 
+// A child whose lane stands with no one in it still holds the paths it declared, as its open lane does.
+function holds_paths(status: ItemStatus): boolean {
+	return status.state === 'running' || status.lane !== undefined
+}
+
 function running_of(read: ReasonRead): Array<number> {
-	return [...read.statuses]
-		.filter(([, status]) => status.state === 'running')
-		.map(([issue]) => issue)
+	return [...read.statuses].filter(([, status]) => holds_paths(status)).map(([issue]) => issue)
 }
 
 function pool_of(read: ReasonRead): Pool {
@@ -88,6 +95,12 @@ function overlap_of(child: EpicChild, read: ReasonRead, pool: Pool): string | un
 		: `${WORDS.overlaps} ${String(clash.holder)} (${clash.path})`
 }
 
+function no_lane_of(occupied: ReadonlyArray<string> = []): string {
+	if (occupied.length === 0) return WORDS.no_lane
+
+	return `${WORDS.no_lane} — ${occupied.join(' ')}`
+}
+
 // A candidate nothing blocks, in the order `backlog:next` answers: the pool held for a judgment, then
 // a path a running issue declares, then a pool with no lane left.
 function offer_wait(child: EpicChild, read: ReasonRead, pool: Pool): string | undefined {
@@ -97,7 +110,7 @@ function offer_wait(child: EpicChild, read: ReasonRead, pool: Pool): string | un
 
 	if (overlap !== undefined) return overlap
 
-	return read.free_lanes === NO_FREE_LANES ? WORDS.no_lane : undefined
+	return read.free_lanes === NO_FREE_LANES ? no_lane_of(read.occupied_lanes) : undefined
 }
 
 function wait_of(child: EpicChild, read: ReasonRead, pool: Pool): RowReason | undefined {

package/scripts/run/board/run-board-render-legend.ts

@@ -32,6 +32,7 @@ const STATE_LEGEND: ReadonlyArray<readonly [ItemState, keyof Words]> = [
 	['merged', 'merged'],
 	['parked', 'parked'],
 	['done', 'done'],
+	['withdrawn', 'withdrawn'],
 	['running', 'in_progress'],
 	['stopped', 'stopped'],
 	['waiting', 'waiting'],

package/scripts/run/board/run-board-render-slot.ts

@@ -9,7 +9,7 @@ import { run_board_usage_text } from './run-board-usage-text'
 // blanks on any other row.
 
 const { finish_of, text_of } = run_board_usage_text
-const FINISHED: ReadonlySet<ItemState> = new Set(['merged', 'done'])
+const FINISHED: ReadonlySet<ItemState> = new Set(['merged', 'done', 'withdrawn'])
 const BLANK = ' '
 
 // What one frame's column is drawn from: each lane's usage, and the running rows the frame draws —

package/scripts/run/board/run-board-render-waits.ts

@@ -0,0 +1,41 @@
+import { core_wait, type BudgetWait } from '#scripts/gate/core-wait'
+
+// The claims waiting in the machine-wide core budget, under the header (joshuafolkken/kit#3943): a lane
+// held back by memory pressure otherwise reads the same as one that is stuck. Each line names the
+// command, the lane it runs in — the main checkout where none, and another repository's checkout by
+// name, unlinked — how long it has waited, and why.
+
+const MS_PER_SECOND = 1000
+// 🚧 rather than ⏳, which a waiting row already draws, or 🚦, the gate stage's; an emoji a terminal
+// draws two columns wide.
+const BUDGET_ICON = '🚧'
+const GAP = '  '
+const MAIN_CHECKOUT = 'main'
+
+function place_text(wait: BudgetWait, link: (reference: string) => string): string {
+	if (wait.elsewhere !== undefined) return wait.elsewhere
+
+	return wait.lane === undefined ? MAIN_CHECKOUT : link(wait.lane)
+}
+
+function wait_text(wait: BudgetWait, link: (reference: string) => string): string {
+	const lane = place_text(wait, link)
+	const seconds = `${String(Math.round(wait.waited_ms / MS_PER_SECOND))}s`
+	const parts = [wait.command ?? 'a step', lane, seconds, core_wait.REASON_TEXT[wait.reason]]
+
+	return `${BUDGET_ICON} ${parts.join(GAP)}`
+}
+
+// Nothing is drawn while no claim waits.
+function wait_lines(
+	waits: ReadonlyArray<BudgetWait> | undefined,
+	link: (reference: string) => string,
+): Array<string> {
+	if (waits === undefined || waits.length === 0) return []
+
+	return ['', ...waits.map((wait) => wait_text(wait, link))]
+}
+
+const run_board_render_waits = { BUDGET_ICON, wait_lines }
+
+export { run_board_render_waits }

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

@@ -24,6 +24,7 @@ import { run_board_render_slot, type UsageSlot } from './run-board-render-slot'
 import { run_board_render_tail } from './run-board-render-tail'
 import { run_board_render_thanks } from './run-board-render-thanks'
 import { run_board_render_title } from './run-board-render-title'
+import { run_board_render_waits } from './run-board-render-waits'
 import { run_board_row_yield } from './run-board-row-yield'
 import type { Thanks } from './run-board-thanks-csv'
 
@@ -388,7 +389,11 @@ function bounded(parts: FrameParts, bounds: FrameBounds): Array<string> {
 
 function render(view: BoardView): Array<string> {
 	const { header, notes } = view
-	const above = [...run_board_header.header_lines(header), ...resume_lines(view.resume)]
+	const above = [
+		...run_board_header.header_lines(header),
+		...run_board_render_waits.wait_lines(header.budget_waits, header.link),
+		...resume_lines(view.resume),
+	]
 	const parts = {
 		above,
 		plan: plan_sections(header, view.size),

package/scripts/run/board/run-board-row-yield.ts

@@ -9,6 +9,7 @@ import type { ItemState } from './run-board-status'
 const YIELD_STAGES: Readonly<Record<ItemState, YieldStage>> = {
 	merged: 'finished',
 	done: 'finished',
+	withdrawn: 'finished',
 	waiting: 'pending',
 	human: 'pending',
 	parked: 'parked',

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

@@ -1,9 +1,11 @@
 import type { NamedPlan } from '#scripts/backlog/backlog-plan'
+import type { BudgetWait } from '#scripts/gate/core-wait'
 import type { MachineSample } from '#scripts/gate/machine-capacity'
 import type { ClosedAnswer, ClosedIssue } from './run-board-closed'
 import type { Fetch } from './run-board-fetch'
 import type { TerminalSize } from './run-board-fit'
 import type { BoardForm } from './run-board-header'
+import { run_board_idle, type IdleSince } from './run-board-idle'
 import type { BoardPlan } from './run-board-layout'
 import type { Link } from './run-board-link'
 import type { MachineGauges, MachineMark } from './run-board-machine'
@@ -20,6 +22,8 @@ interface BoardPorts {
 	// `undefined` when no run has started here.
 	read_local: () => Promise<LocalRead | undefined>
 	read_machine: () => Promise<MachineSample>
+	// The claims waiting in the core budget, read on the machine's second; none where it is not given.
+	read_waits?: (() => Array<BudgetWait>) | undefined
 	// Every process and its lane, the last reading's lanes reused (`run-board-usage-read.ts`).
 	read_usage: (before: UsageMark | undefined) => Promise<UsageMark | undefined>
 	// The issues that answered as closed, and whether every issue answered (`run-board-closed.ts`).
@@ -56,6 +60,8 @@ interface BoardState {
 	// The last local read, drawn until the next is due; `undefined` when no run had started.
 	local: LocalRead | undefined
 	read_ms: number | undefined
+	// When each lane the reads found idle was first read so (`run-board-idle.ts`).
+	idle_since: IdleSince
 	// The start of the run the plan state was built for, so a run that begins draws nothing of the last.
 	run_started_ms: number | undefined
 	plan: BoardPlan | undefined
@@ -82,6 +88,7 @@ interface BoardState {
 	// them.
 	usage: UsageMark | undefined
 	usages: LaneUsages | undefined
+	budget_waits: ReadonlyArray<BudgetWait>
 	// The reviewers drawn above the legend, the read of them in flight, and when it was last launched.
 	thanks: Thanks
 	thanks_fetch: Fetch<Thanks> | undefined
@@ -91,6 +98,7 @@ interface BoardState {
 const FRESH_STATE: BoardState = {
 	local: undefined,
 	read_ms: undefined,
+	idle_since: run_board_idle.NO_IDLE,
 	run_started_ms: undefined,
 	plan: undefined,
 	plan_fetch: undefined,
@@ -108,6 +116,7 @@ const FRESH_STATE: BoardState = {
 	spots: [],
 	usage: undefined,
 	usages: undefined,
+	budget_waits: [],
 	thanks: [],
 	thanks_fetch: undefined,
 	thanks_attempted_ms: undefined,