@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/backlog/backlog-ready.ts

@@ -1,14 +1,22 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import type { JoshResult } from '#scripts/josh/josh-run'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { lane_process_table, type TableRead } from '#scripts/lane/lane-process-table'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_snapshot_trace } from '#scripts/lane/lane-snapshot-trace'
 import { lane_spent } from '#scripts/lane/lane-spent'
+import { lane_state } from '#scripts/lane/lane-state'
 import type { RunCarry } from '#scripts/run/carry/run-carry'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_headless } from '#scripts/run/run-headless'
 import { run_invocation } from '#scripts/run/run-invocation'
-import { backlog_occupied, type OccupiedRead } from './backlog-occupied'
+import { backlog_drive_restore } from './backlog-drive-restore'
+import { backlog_next_shared } from './backlog-next-shared'
+import { backlog_occupied } from './backlog-occupied'
+import { backlog_offer_exclude } from './backlog-offer-exclude'
 import { backlog_stalled } from './backlog-stalled'
 
 // The ready line reports runnable work to the driving backlogrun parent on a watcher wake.
@@ -21,10 +29,27 @@ interface ReadyReading {
 	free_lanes: number
 }
 
-// How many open lanes hold a place under the limit, and how many hold a port seat.
+// How many open lanes hold a place under the limit, how many hold a port seat, and the ones with no
+// lane state record.
 interface LaneUse {
 	occupied: number
 	seated: number
+	unknown: ReadonlyArray<string>
+}
+
+// The lanes that hold a place under the limit, read once for every count drawn from them.
+interface LaneRoom {
+	occupied: ReadonlyArray<LaneInfo>
+	// The open lanes no child is working in, read from the same snapshot.
+	idle: ReadonlyArray<string>
+	// The open lanes with no lane state record, counted as holding a place until one is written.
+	unknown: ReadonlyArray<string>
+	use: LaneUse
+}
+
+interface LaneCount {
+	limit: number
+	free: number
 }
 
 interface ReadyPorts {
@@ -32,45 +57,69 @@ interface ReadyPorts {
 	ready_issues: () => Promise<ReadonlyArray<string>>
 }
 
-// What decides which open lanes hold a place, read from this checkout's live run.
-async function occupied_read(): Promise<OccupiedRead> {
-	const carry = await run_headless.current_carry()
-
-	return {
-		invocation: carry?.invocation,
-		events: carry === undefined ? [] : await run_event_stream_emit.scoped_current_events(),
-		idle: lane_spent.idle_lanes,
-	}
+// The lanes that hold a place under the limit (`backlog-occupied.ts`), the idle ones and the unknown
+// ones. Paused is each lane's state record's answer; every lane's idle reading is drawn from one
+// asynchronous process snapshot, so the count never blocks its caller's event loop
+// (joshuafolkken/kit#4241, #4245); `run:board` passes the snapshot its redraw already read (#4246).
+async function occupancy_of(
+	open: ReadonlyArray<LaneInfo>,
+	table: TableRead,
+): Promise<Omit<LaneRoom, 'use'>> {
+	const rows = await table()
+	const issues = open.map((lane) => lane.issue)
+	const trace = { process_trace: await lane_snapshot_trace.traces_of(issues, rows) }
+	const records = await lane_state.read_states(issues)
+	const is_merge_waiting = await lane_snapshot_trace.merge_waits_of(issues, rows)
+	const occupied = backlog_occupied.occupied_lanes(
+		open,
+		(live) => lane_spent.idle_lanes(live, trace),
+		records,
+		is_merge_waiting,
+	)
+	const unknown = backlog_occupied.unknown_lanes(open, records)
+
+	return { occupied, idle: lane_spent.idle_lanes(open, trace), unknown }
 }
 
-// The lanes that hold a place under the limit (`backlog-occupied.ts`).
-async function occupied_lanes(lanes?: ReadonlyArray<LaneInfo>): Promise<Array<LaneInfo>> {
+// The open lanes as the free count reads them: those that hold a place under the limit, and every
+// open one, since an uncounted lane still holds its port seat.
+async function lane_room(
+	lanes?: ReadonlyArray<LaneInfo>,
+	table: TableRead = lane_process_table.read_table,
+): Promise<LaneRoom> {
 	const open = lanes ?? (await lane_registry.list_lanes())
+	const occupancy = await occupancy_of(open, table)
+	const seated = open.filter((lane) => !lane.is_stranded).length
 
-	return backlog_occupied.occupied_lanes(open, await occupied_read())
+	const use = { occupied: occupancy.occupied.length, seated, unknown: occupancy.unknown }
+
+	return { ...occupancy, use }
 }
 
-// The open lanes as the free count reads them: those that hold a place under the limit, and every
-// open one, since an uncounted lane still holds its port seat.
 async function lane_use(lanes?: ReadonlyArray<LaneInfo>): Promise<LaneUse> {
-	const open = lanes ?? (await lane_registry.list_lanes())
-	const occupied = await occupied_lanes(open)
+	const room = await lane_room(lanes)
 
-	return { occupied: occupied.length, seated: open.filter((lane) => !lane.is_stranded).length }
+	return room.use
 }
 
 function free_of(limit: number, use: LaneUse): number {
 	return lane_capacity.free_lanes(limit, use.occupied, use.seated)
 }
 
-// Free lanes beside `lanes`, `undefined` where the limit could not be read: the count `lane:limit`
-// prints, and the one `run:board` draws, so the two never answer apart.
-async function free_lanes_beside(lanes: ReadonlyArray<LaneInfo>): Promise<number | undefined> {
+// The limit and the free lanes in `room`, `undefined` where the limit could not be read: the count
+// `lane:limit` prints, and the one `run:board` draws, so the two never answer apart.
+async function count_in(room: LaneRoom): Promise<LaneCount | undefined> {
 	const limit = await lane_capacity.lane_limit()
 
 	if (limit.kind !== 'limit') return undefined
 
-	return free_of(limit.limit, await lane_use(lanes))
+	return { limit: limit.limit, free: free_of(limit.limit, room.use) }
+}
+
+async function free_lanes_beside(lanes: ReadonlyArray<LaneInfo>): Promise<number | undefined> {
+	const count = await count_in(await lane_room(lanes))
+
+	return count?.free
 }
 
 async function free_under(limit: number): Promise<number> {
@@ -94,12 +143,24 @@ async function free_lane_count(): Promise<number> {
 // **The drive's count throws on an unreadable limit**. The drive launches no
 // more than this count, so the safe-direction zero above would leave it launching nothing and reporting
 // nothing for good; a bad setting is the hard error `lane_capacity` says it is, ending the drive loudly.
-async function drive_free_lane_count(): Promise<number> {
+async function drive_limit(): Promise<number> {
 	const limit = await lane_capacity.lane_limit()
 
 	if (limit.kind !== 'limit') throw new Error(limit.problem)
 
-	return await free_under(limit.limit)
+	return limit.limit
+}
+
+async function drive_free_lane_count(): Promise<number> {
+	return await free_under(await drive_limit())
+}
+
+// The drive's room under the limit alone, for resuming a kept lane, which already holds its port seat.
+async function drive_limit_room(): Promise<number> {
+	const limit = await drive_limit()
+	const use = await lane_use()
+
+	return lane_capacity.limit_room(limit, use.occupied)
 }
 
 // **A `--only` run has no pool to drain**. `backlog:next` lists the opted-in
@@ -110,13 +171,32 @@ function drains_pool(carry: RunCarry | undefined): boolean {
 	return carry === undefined || !run_invocation.has_only(carry.invocation)
 }
 
+// The offer's own exclusion, read off this run's stream: a merged child `backlog:next` still reads OPEN,
+// or one in flight, is no ready work (joshuafolkken/kit#4349). Scoped to this invocation, as the drive's
+// list is: the stream is the repository's log, so an earlier run's merge or unsettled launch would
+// otherwise hide a reopened issue for good.
+async function stream_exclude(carry: RunCarry | undefined): Promise<ReadonlyArray<string>> {
+	const target = await run_event_stream_emit.stream_target()
+
+	if (target === undefined || carry === undefined) return []
+
+	const scope = run_event_scope.scope_of({ kind: 'carried', carry })
+	const events = run_event_scope.scoped_events(run_event_stream.read_events(target), scope) ?? []
+
+	return backlog_drive_restore.offer_exclude(events)
+}
+
 // The `backlog:next` read, or `undefined` for a `--only` run, which answers none before paying for the
 // network read. A bounded read keeps stderr piped: the arrival probe reads once
 // a minute, and a forwarded refusal would fill the watcher's output.
 async function read_backlog_next(timeout_ms?: number): Promise<JoshResult | undefined> {
-	if (!drains_pool(await run_headless.current_carry())) return undefined
+	const carry = await run_headless.current_carry()
+
+	if (!drains_pool(carry)) return undefined
+
+	const argv = ['backlog:next', ...backlog_offer_exclude.exclude_argv(await stream_exclude(carry))]
 
-	return await josh_command.josh_run(['backlog:next'], timeout_ms === undefined, timeout_ms)
+	return await backlog_next_shared.read(argv, timeout_ms === undefined, timeout_ms)
 }
 
 // The runnable issues for this checkout, read the way a loop reads them: `backlog:next`'s numeric lines.
@@ -208,9 +288,11 @@ const backlog_ready = {
 	print_offer_hint,
 	free_lane_count,
 	free_lanes_beside,
+	count_in,
+	lane_room,
 	lane_use,
-	occupied_lanes,
 	drive_free_lane_count,
+	drive_limit_room,
 	drains_pool,
 	print_ready_line,
 	read_ready,
@@ -219,4 +301,4 @@ const backlog_ready = {
 }
 
 export { backlog_ready }
-export type { LaneUse, ReadyPorts, ReadyReading }
+export type { LaneCount, LaneRoom, LaneUse, ReadyPorts, ReadyReading }

package/scripts/backlog/backlog-stalled-detect.ts

@@ -1,12 +1,14 @@
-import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { backlog_ready, type ReadyPorts } from './backlog-ready'
 import { backlog_stalled, type StallReading, type StallVerdict } from './backlog-stalled'
 
 // The I/O half of the stall detector: it gathers the three counts the pure
-// judge in `backlog-stalled.ts` weighs, then — on a stall — leaves the marker and sends the one
-// notification. `stop-guard.ts` wires it into the Stop hook, so it runs at each loop boundary; the CLI
+// judge in `backlog-stalled.ts` weighs, then — on a stall — leaves the marker `run:step` reads as
+// `backlog:next`. It sends no Telegram (joshuafolkken/kit#4015): a stall resolves itself at the next
+// dispatch, so the person it reached had nothing to do; the idle notification `backlog:drive` sends
+// when nothing is left to dispatch is the one that wants a hand. `stop-guard.ts` wires it into the Stop hook, so it runs at each loop boundary; the CLI
 // exposes the same call for a person to run by hand.
 //
 // **Cheap first.** The costly read is `backlog:next`, a subprocess that hits the network. The two local
@@ -14,26 +16,39 @@ import { backlog_stalled, type StallReading, type StallVerdict } from './backlog
 // is one `git worktree list`. Neither the lane count nor the backlog read is made unless the cheaper
 // condition ahead of it already holds, so an ordinary stop — a run not idle, or with no free lane —
 // costs a single file read and nothing more.
+//
+// **A stall is aged from when work and a lane first met** (joshuafolkken/kit#4349). Each probe records,
+// on the lane ledger, whether offerable work and a free lane coexist — only when that changes — and the
+// wait runs from the observation that opened the current episode. The dispatch age stays the cheap
+// gate: the wait can never exceed it.
 
 const NO_FREE = 0
 const NO_READY = 0
 const NO_AGE = 0
 
-// The recovery line names the command that resolves the stall — the same one `run:step` points a stalled
-// run at — so the person the notification reaches has the fix in hand.
-const STALL_RECOVERY = 'Dispatch the ready work with `pnpm josh backlog:next`.'
-
-// The seams a test replaces: the stream target and its events, the clock, the two counts, and the two
-// side effects. The defaults are the real readers; a test hands fakes so the gather and report logic run
-// without a git tree, a network or a wall clock.
+// The seams a test replaces: the stream target and its events, the clock, the two counts, the ledger,
+// and the marker. The defaults are the real readers; a test hands fakes so the gather and report logic
+// run without a git tree, a network or a wall clock.
 interface DetectPorts {
 	resolve_target: () => Promise<string | undefined>
 	read_events: (target: string) => ReadonlyArray<RunEvent>
 	now_ms: () => number
 	free_lane_count: () => Promise<number>
 	ready_count: () => Promise<number>
+	read_ledger: () => Promise<ReadonlyArray<LedgerEntry>>
+	mark_offerable: (is_offerable: boolean) => Promise<void>
 	emit_stall: (text: string) => Promise<boolean>
-	notify_stalled: (body: string) => Promise<boolean>
+}
+
+interface Counts {
+	ready_count: number
+	free_lanes: number
+}
+
+// The dispatch reference the episode is bounded by, and the probe's own time.
+interface Clock {
+	reference_ms: number
+	now_ms: number
 }
 
 // The free-lane and runnable-issue reads are `backlog-ready.ts`'s — the watcher's ready line reads the
@@ -55,8 +70,15 @@ async function real_emit_stall(text: string): Promise<boolean> {
 	return await run_event_stream_emit.emit_once_since(STALL, text, CHILD_LAUNCH)
 }
 
-async function real_notify_stalled(body: string): Promise<boolean> {
-	return await telegram_notify.stalled({ body, recovery: STALL_RECOVERY })
+// A test run has no ledger (`lane_ledger.target`), so it reads as empty there.
+async function read_real_ledger(): Promise<ReadonlyArray<LedgerEntry>> {
+	const path = await lane_ledger.target()
+
+	return path === undefined ? [] : lane_ledger.read_entries(path)
+}
+
+async function real_mark_offerable(is_offerable: boolean): Promise<void> {
+	await lane_ledger.record_offerable(is_offerable)
 }
 
 function ports_over(ready: ReadyPorts): DetectPorts {
@@ -66,26 +88,64 @@ function ports_over(ready: ReadyPorts): DetectPorts {
 		now_ms: () => Date.now(),
 		free_lane_count: ready.free_lane_count,
 		ready_count: ready_count_of(ready),
+		read_ledger: read_real_ledger,
+		mark_offerable: real_mark_offerable,
 		emit_stall: real_emit_stall,
-		notify_stalled: real_notify_stalled,
 	}
 }
 
 const DEFAULT_PORTS: DetectPorts = ports_over(backlog_ready.DEFAULT_PORTS)
 
-function ok_reading(dispatch_age_ms: number): StallReading {
-	return { ready_count: NO_READY, free_lanes: NO_FREE, dispatch_age_ms }
+function ok_reading(): StallReading {
+	return { ready_count: NO_READY, free_lanes: NO_FREE, waiting_ms: NO_AGE }
 }
 
-// The idle-and-past-threshold branch, where the costly reads finally happen: count the free lanes, and
-// only if one is free read the backlog. A full pool short-circuits before the network call — a stall
-// needs a lane to go into.
-async function probe_reading(ports: DetectPorts, dispatch_age_ms: number): Promise<StallReading> {
+// Count the free lanes, and only if one is free read the backlog. A full pool short-circuits before the
+// network call — a stall needs a lane to go into.
+async function read_counts(ports: DetectPorts): Promise<Counts> {
 	const free_lanes = await ports.free_lane_count()
 
-	if (free_lanes <= NO_FREE) return { ready_count: NO_READY, free_lanes, dispatch_age_ms }
+	if (free_lanes <= NO_FREE) return { ready_count: NO_READY, free_lanes }
+
+	return { ready_count: await ports.ready_count(), free_lanes }
+}
+
+function has_both(counts: Counts): boolean {
+	return counts.ready_count > NO_READY && counts.free_lanes > NO_FREE
+}
+
+// How long both have held: from the observation that opened the episode, or zero where this probe opens
+// or closes one — and records that change.
+async function waiting_ms(
+	ports: DetectPorts,
+	entries: ReadonlyArray<LedgerEntry>,
+	clock: Clock,
+	is_offerable: boolean,
+): Promise<number> {
+	const opened_ms = backlog_stalled.open_offerable_ms(entries, clock.reference_ms)
+
+	if (is_offerable === (opened_ms !== undefined)) return clock.now_ms - (opened_ms ?? clock.now_ms)
 
-	return { ready_count: await ports.ready_count(), free_lanes, dispatch_age_ms }
+	await ports.mark_offerable(is_offerable)
+
+	return NO_AGE
+}
+
+// The idle-and-past-threshold branch, where the costly reads finally happen.
+async function probe_reading(ports: DetectPorts, clock: Clock): Promise<StallReading> {
+	const counts = await read_counts(ports)
+	const entries = await ports.read_ledger()
+	const waited = await waiting_ms(ports, entries, clock, has_both(counts))
+
+	return { ...counts, waiting_ms: waited, hold: backlog_stalled.open_hold(entries) }
+}
+
+// The dispatch reference and the probe's time, or `undefined` when the stream has nothing to age against.
+function clock_of(ports: DetectPorts, target: string): Clock | undefined {
+	const now_ms = ports.now_ms()
+	const age = backlog_stalled.dispatch_age_ms(ports.read_events(target), now_ms)
+
+	return age === undefined ? undefined : { reference_ms: now_ms - age, now_ms }
 }
 
 // The reading that decides the verdict, assembled cheap-condition-first. `undefined` is the unreadable
@@ -96,25 +156,38 @@ async function gather(ports: DetectPorts, threshold_ms: number): Promise<StallRe
 
 	if (target === undefined) return undefined
 
-	const age = backlog_stalled.dispatch_age_ms(ports.read_events(target), ports.now_ms())
+	const clock = clock_of(ports, target)
 
-	if (age === undefined) return ok_reading(NO_AGE)
-	if (age <= threshold_ms) return ok_reading(age)
+	if (clock === undefined || clock.now_ms - clock.reference_ms <= threshold_ms) return ok_reading()
 
-	return await probe_reading(ports, age)
+	return await probe_reading(ports, clock)
 }
 
-// The marker and the notification, both once per stall episode. `emit_stall` refuses a second until a
-// dispatch has intervened, and its `false` is what holds the notification back too — so a stall
-// polled every stop reaches the person once, not once a turn.
-async function report(ports: DetectPorts, reading: StallReading): Promise<void> {
-	const text = backlog_stalled.describe(reading)
+// The watcher's once-a-minute arrival probe records the same observation from the reading it already
+// made, so an episode opens within a probe interval of work meeting a lane — not at the first stop past
+// the dispatch-age gate, which would hide up to one threshold of the wait. Best-effort, like the check.
+async function observe_offerable(
+	is_offerable: boolean,
+	ports: DetectPorts = DEFAULT_PORTS,
+): Promise<void> {
+	try {
+		const target = await ports.resolve_target()
+		const clock = target === undefined ? undefined : clock_of(ports, target)
 
-	if (await ports.emit_stall(text)) await ports.notify_stalled(text)
+		if (clock !== undefined) await waiting_ms(ports, await ports.read_ledger(), clock, is_offerable)
+	} catch {
+		// A failed observation is dropped: the next probe records it, and the watcher's loop must not break.
+	}
+}
+
+// The marker, once per stall episode: `emit_stall` refuses a second until a dispatch has intervened, so a
+// stall polled every stop lands on the stream once, not once a turn.
+async function report(ports: DetectPorts, reading: StallReading): Promise<void> {
+	await ports.emit_stall(backlog_stalled.describe(reading))
 }
 
-// Read the three conditions, print nothing, and on a stall leave the marker and notify. The verdict is
-// returned for the CLI to print; the side effects are the report's.
+// Read the three conditions, print nothing, and on a stall leave the marker. The verdict is returned for
+// the CLI to print; the side effect is the report's.
 async function detect_and_report(
 	ports: DetectPorts = DEFAULT_PORTS,
 	threshold_ms: number = backlog_stalled.STALL_THRESHOLD_MS,
@@ -127,7 +200,7 @@ async function detect_and_report(
 	return verdict
 }
 
-// Best-effort for the Stop hook: the detector is a report, so a failure to gather or notify is dropped
+// Best-effort for the Stop hook: the detector is a report, so a failure to gather or mark is dropped
 // rather than raised into the stop decision it rides alongside.
 async function run_stall_check(ready: ReadyPorts = backlog_ready.DEFAULT_PORTS): Promise<void> {
 	try {
@@ -137,7 +210,7 @@ async function run_stall_check(ready: ReadyPorts = backlog_ready.DEFAULT_PORTS):
 	}
 }
 
-const backlog_stalled_detect = { detect_and_report, run_stall_check }
+const backlog_stalled_detect = { detect_and_report, observe_offerable, run_stall_check }
 
 export { backlog_stalled_detect }
 export type { DetectPorts }

package/scripts/backlog/backlog-stalled.ts

@@ -1,11 +1,13 @@
 import { epic_triage } from '#scripts/epic/epic-triage'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
 // When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks.
 // This is the mechanical judge of that state: three facts read, never
 // weighed — is there runnable work, is there a free lane, and has nothing been dispatched for a while.
-// The verdict is a report, not a stop: a false positive costs one notification, never a halted run.
+// The verdict is a report, not a stop: a false positive costs one stream marker, never a halted run.
 //
 // **Pure by design.** The clock and the counts are handed in, so the four acceptance cases — work with
 // a free lane, work with no free lane, no work, and an unreadable record — and the elapsed-time
@@ -13,7 +15,6 @@ import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-st
 // counts is `backlog-stalled-detect.ts`; this file only decides.
 
 const STALL_THRESHOLD_MINUTES = 10
-const MS_PER_MINUTE = 60_000
 const STALL_THRESHOLD_MS = STALL_THRESHOLD_MINUTES * MS_PER_MINUTE
 const NONE = 0
 
@@ -28,11 +29,14 @@ const OK: StallVerdict = 'ok'
 const UNREADABLE: StallVerdict = 'unreadable'
 
 // The three facts, read and never judged: how many issues could start now, how many lanes are free, and
-// how long since the last dispatch. Assembled by the detect layer; consumed only here.
+// how long both have held together since the last dispatch — never the idle time before work arrived or
+// a long child ran (joshuafolkken/kit#4349). `hold` is the driver's open hold reason (`memory`, …), so a
+// deliberate hold reads apart from a slow dispatch. Assembled by the detect layer; consumed only here.
 interface StallReading {
 	ready_count: number
 	free_lanes: number
-	dispatch_age_ms: number
+	waiting_ms: number
+	hold?: string | undefined
 }
 
 // All three together, and only together. Separated from `assess` so the short-circuit gate in the
@@ -40,9 +44,7 @@ interface StallReading {
 // same condition rather than a second copy of it.
 function is_stalled(reading: StallReading, threshold_ms: number): boolean {
 	return (
-		reading.ready_count > NONE &&
-		reading.free_lanes > NONE &&
-		reading.dispatch_age_ms > threshold_ms
+		reading.ready_count > NONE && reading.free_lanes > NONE && reading.waiting_ms > threshold_ms
 	)
 }
 
@@ -68,23 +70,55 @@ function dispatch_reference_iso(events: ReadonlyArray<RunEvent>): string | undef
 	return last_launch?.at ?? events[0]?.at
 }
 
-// Milliseconds since that reference, or `undefined` when there is no reference or the stamp is
-// unparseable — the caller reads either as "nothing to age against" and returns no stall.
-function dispatch_age_ms(events: ReadonlyArray<RunEvent>, now_ms: number): number | undefined {
+// That reference as epoch milliseconds, or `undefined` when there is none or the stamp is unparseable.
+function dispatch_reference_ms(events: ReadonlyArray<RunEvent>): number | undefined {
 	const iso = dispatch_reference_iso(events)
+	const at = iso === undefined ? NaN : Date.parse(iso)
+
+	return Number.isNaN(at) ? undefined : at
+}
 
-	if (iso === undefined) return undefined
+// Milliseconds since that reference, or `undefined` when there is no reference — the caller reads it as
+// "nothing to age against" and returns no stall. A stall cannot be older than this, so it gates the
+// costly reads.
+function dispatch_age_ms(events: ReadonlyArray<RunEvent>, now_ms: number): number | undefined {
+	const at = dispatch_reference_ms(events)
+
+	return at === undefined ? undefined : now_ms - at
+}
+
+// When the current coexistence of offerable work and a free lane was first observed: the newest
+// observation since the reference, if it saw both. `undefined` when it did not or none was made — an
+// observation before the last dispatch belongs to an episode that dispatch ended.
+function open_offerable_ms(
+	entries: ReadonlyArray<LedgerEntry>,
+	reference_ms: number,
+): number | undefined {
+	const newest = entries.findLast(
+		(entry) => entry.kind === lane_ledger.KIND.OFFERABLE && Date.parse(entry.at) >= reference_ms,
+	)
+
+	if (newest?.kind !== lane_ledger.KIND.OFFERABLE || !newest.is_offerable) return undefined
+
+	return Date.parse(newest.at)
+}
 
-	const at = Date.parse(iso)
+// The driver's open hold reason: the newest of its hold, release and dispatch records, when a hold.
+function open_hold(entries: ReadonlyArray<LedgerEntry>): string | undefined {
+	const { HELD, RELEASED, DISPATCH } = lane_ledger.KIND
+	const hold_kinds: ReadonlySet<string> = new Set([HELD, RELEASED, DISPATCH])
+	const newest = entries.findLast((entry) => hold_kinds.has(entry.kind))
 
-	return Number.isNaN(at) ? undefined : now_ms - at
+	return newest?.kind === lane_ledger.KIND.HELD ? newest.reason : undefined
 }
 
-// The one line a person reads in the notification and on the stream: what is waiting and how long.
+// The one line a person reads in the notification and on the stream: what is waiting, how long, and the
+// driver's hold reason when it holds deliberately.
 function describe(reading: StallReading): string {
-	const minutes = Math.floor(reading.dispatch_age_ms / MS_PER_MINUTE)
+	const minutes = Math.floor(reading.waiting_ms / MS_PER_MINUTE)
+	const held = reading.hold === undefined ? '' : ` (held: ${reading.hold})`
 
-	return `${String(reading.ready_count)} ready, ${String(reading.free_lanes)} free lane(s), ${String(minutes)}m since the last dispatch`
+	return `${String(reading.ready_count)} ready, ${String(reading.free_lanes)} free lane(s), ${String(minutes)}m waiting with both${held}`
 }
 
 // The runnable issue numbers `backlog:next` printed: one token per line, a bare number per runnable
@@ -118,6 +152,8 @@ const backlog_stalled = {
 	describe,
 	dispatch_age_ms,
 	needs_triage,
+	open_hold,
+	open_offerable_ms,
 	ready_tokens,
 }