@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lane/lane-core-wait-stats.ts

@@ -0,0 +1,66 @@
+import { lane_ledger, type CoreWaitEntry, type LedgerEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// How long each lane's commands waited for the core budget: the ledger's `core-wait` entries of one
+// period reduced to one row per lane, printed by `josh lane:stats` so a lane's time splits into work
+// and waiting (joshuafolkken/kit#4382). A lane is named by its issue number, a wait outside a lane — the
+// main checkout's — by its own row.
+
+const COLUMNS = ['lane', 'total (min)', 'median (min)', 'waits'] as const
+const OUTSIDE_A_LANE = 'outside a lane'
+const { NOT_MEASURED } = lane_stage_stats
+// A period with no wait: the table still prints, so a reader sees zero waits rather than no table.
+const NONE_ROW = ['none', NOT_MEASURED, NOT_MEASURED, '0']
+
+function is_core_wait(entry: LedgerEntry): entry is CoreWaitEntry {
+	return entry.kind === lane_ledger.KIND.CORE_WAIT
+}
+
+function lane_of(wait: CoreWaitEntry): string {
+	return wait.issue === undefined ? OUTSIDE_A_LANE : String(wait.issue)
+}
+
+function total(values: ReadonlyArray<number>): number {
+	return values.reduce((sum, value) => sum + value, 0)
+}
+
+function waits_of(waits: ReadonlyArray<CoreWaitEntry>, lane: string): Array<number> {
+	return waits.filter((wait) => lane_of(wait) === lane).map((wait) => wait.waited_ms)
+}
+
+function lane_row(lane: string, waits: ReadonlyArray<CoreWaitEntry>): string {
+	const waited = waits_of(waits, lane)
+
+	return lane_stats.to_row([
+		lane,
+		lane_stage_stats.cell(total(waited)),
+		lane_stage_stats.cell(lane_stats.median(waited)),
+		String(waited.length),
+	])
+}
+
+// The lanes the period saw, the longest total first, so the lane the budget held back most leads.
+function lanes_of(waits: ReadonlyArray<CoreWaitEntry>): Array<string> {
+	const lanes = [...new Set(waits.map((wait) => lane_of(wait)))]
+
+	return lanes.toSorted(
+		(left, right) => total(waits_of(waits, right)) - total(waits_of(waits, left)),
+	)
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const waits = lane_stats.in_window(entries, window).filter((entry) => is_core_wait(entry))
+	const rows = lanes_of(waits).map((lane) => lane_row(lane, waits))
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...(rows.length === 0 ? [lane_stats.to_row(NONE_ROW)] : rows),
+	].join('\n')
+}
+
+const lane_core_wait_stats = { table }
+
+export { lane_core_wait_stats }

package/scripts/lane/lane-dispatch-log.ts

@@ -1,11 +1,11 @@
-import { stamp_file } from '#scripts/josh/stamp-file'
+import { durable_state } from '#scripts/josh/durable-state'
 import type { LaneInfo } from './lane-registry'
 
-const LOG_PREFIX = 'josh-lane-dispatch-'
+const LOG_PREFIX = durable_state.PREFIX.LANE_DISPATCH
 const LOG_SUFFIX = '.log'
 
 function default_log_path(lane: LaneInfo): string {
-	return stamp_file.stamp_path(`${LOG_PREFIX}${lane.issue}-`, lane.directory, LOG_SUFFIX)
+	return durable_state.path(`${LOG_PREFIX}${lane.issue}-`, lane.directory, LOG_SUFFIX)
 }
 
 const lane_dispatch_log = { default_log_path }

package/scripts/lane/lane-dispatch.ts

@@ -10,15 +10,17 @@ import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 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_park } from '#scripts/run/park/run-park'
 import { run_ending } from '#scripts/run/run-ending'
 import { run_label } from '#scripts/run/run-label'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
 import { lane_dispatch_log } from './lane-dispatch-log'
-import { lane_ledger } from './lane-ledger'
+import { lane_ledger_write } from './lane-ledger-write'
 import { lane_output } from './lane-output'
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_resume, type ResumePlan } from './lane-resume'
+import { lane_state } from './lane-state'
 import { openai_lane_supervisor } from './openai-lane-supervisor'
 
 // `josh lane:dispatch <issue-number>` — start a lane's child as an operating-system process of its own.
@@ -244,10 +246,15 @@ async function dispatched_start(
 		: dispatched_of(request, pid, notes)
 }
 
+// **A dispatch takes back any park the issue's earlier child recorded**: the issue is offered
+// again only once `needs-decision` is off, so a record still on disk is one a person cleared by hand on
+// GitHub, and left in place it would silence `lane-park` on this child's own stop
+// (joshuafolkken/kit#4132).
 async function started(request: StartRequest): Promise<DispatchOutcome> {
 	const notes: Array<string> = []
 	const existing = existing_dispatch(request)
 	if (existing !== undefined) return existing
+	run_park.clear(request.lane.issue, request.lane.directory)
 	const nonce =
 		request.profile.provider === 'openai' ? openai_lane_supervisor.new_nonce() : undefined
 	const result = detached_launch.launch(
@@ -327,13 +334,27 @@ async function mark_in_progress(issue: string): Promise<LabelWrite> {
 // removal warns and never throws, so it cannot turn a launch failure into a thrown error.
 //
 // The lane ledger takes the same instant: `lane:stats` times a lane's implementation from it, and the
-// stream is capped, so a period's earlier dispatches would be gone from there.
-async function record_started(issue: string): Promise<void> {
+// stream is capped, so a period's earlier dispatches would be gone from there. The lane's state record
+// takes the stream's launch instant as its own, so `run:board`, which reads the lane's events from
+// the record's launch on, keeps the launch event that opens them (joshuafolkken/kit#4269).
+async function record_started(issue: string, start: DispatchStart): Promise<void> {
+	const now = new Date()
+
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.CHILD_LAUNCH,
 		`${issue_cite.plain(issue)} dispatched`,
+		now,
+	)
+	await lane_ledger_write.record_dispatch(Number(issue))
+	await lane_state.record_change(
+		{
+			issue,
+			state: 'running',
+			command: start === RESTART_START ? 'lane:restart' : 'lane:dispatch',
+			is_launch: true,
+		},
+		{ now },
 	)
-	await lane_ledger.record_dispatch(Number(issue))
 }
 
 // How a dispatch begins. A `resumable` one claims the marker itself and resumes an `outage` session; a
@@ -359,7 +380,7 @@ async function finish_dispatch(
 
 	const is_failed = outcome.kind === 'failed'
 
-	await (is_failed ? run_label.unmark(issue) : record_started(issue))
+	await (is_failed ? run_label.unmark(issue) : record_started(issue, start))
 
 	return outcome
 }

package/scripts/lane/lane-gap-stats.ts

@@ -0,0 +1,157 @@
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { lane_ledger, type LedgerEntry, type MergeEntry } from './lane-ledger'
+import { lane_net_time } from './lane-net-time'
+import { lane_spans, type Span } from './lane-spans'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+import { lane_stop_stats } from './lane-stop-stats'
+
+// How long a lane slot waited on the lane machinery rather than on work, printed by `josh lane:stats`
+// (joshuafolkken/kit#4395). Three hand-offs, each timed from the moment the slot's next step could run:
+//
+// - `cut → resume`: a child's session cut until the relaunched session resumed the lane.
+// - `outage → relaunch`: a child that ended with no result, collected as an `outage`, until its next
+//   `child-launch` (joshuafolkken/kit#4410).
+// - `park → offer`: a park until the driver's next offer answered — a `held`, `released` or `dispatch`
+//   entry. A pool that stays full writes no line after its one `released`, and a driver handed back
+//   writes none, so a gap over the offer interval is a full pool or no driver, never the hand-over
+//   (joshuafolkken/kit#4410). The ship's cap park and the driver's collection of it are each timed.
+// - `yield → redispatch`: a yield (`lane:plan` gave the seat back) until its issue's next `dispatch`, the
+//   wait `josh lane:net` takes out (`lane-net-time.ts`, joshuafolkken/kit#5216).
+// - `followup → merge`: the ship's last `followup` stage before the merge until the parent wrote the
+//   `merge` line, the step that releases the slot. A merge with no `followup` stage has no start.
+//
+// A start nothing ended is counted under `not ended`, kept out of the seconds.
+
+const COLUMNS = ['gap', 'count', 'median (s)', 'max (s)', 'not ended'] as const
+const RELAUNCH = 'cut → resume'
+const OUTAGE = 'outage → relaunch'
+const PARK = 'park → offer'
+const YIELD = 'yield → redispatch'
+const MERGE = 'followup → merge'
+const FOLLOWUP_STAGE = 'followup'
+const IMPLEMENTATION_CUT = `cut (${agent_role_profile.IMPLEMENTATION_PHASE})`
+const { NOT_MEASURED, is_dispatch, is_merge, is_number, is_stage } = lane_stage_stats
+const { EVENT_KIND } = run_event_stream
+// The offer answers that are not a dispatch: a free lane held, or the pool found full.
+const OFFER_ANSWERS: ReadonlySet<string> = new Set([
+	lane_ledger.KIND.HELD,
+	lane_ledger.KIND.RELEASED,
+])
+
+// Only an implementation cut appends a `resume` when it is adopted; a pre-gate resume appends nothing,
+// so its cut would read as never ended (`run-cut-resume.ts` → `emit_resume_event`).
+function implementation_cuts(events: ReadonlyArray<RunEvent>): Array<RunEvent> {
+	return events.filter((event) => event.text.endsWith(IMPLEMENTATION_CUT))
+}
+
+function relaunch_spans(events: ReadonlyArray<RunEvent>): Array<Span> {
+	return lane_spans.issue_spans({
+		starts: lane_stop_stats.events_of(implementation_cuts(events), EVENT_KIND.CUT),
+		bounds: lane_stop_stats.events_of(events, EVENT_KIND.CUT),
+		ends: lane_stop_stats.events_of(events, EVENT_KIND.RESUME),
+	})
+}
+
+// A child that ended with no result is collected as an `outage`, re-dispatchable; its next launch is
+// the relaunch.
+function outage_spans(events: ReadonlyArray<RunEvent>): Array<Span> {
+	const outages = lane_stop_stats.events_of(events, EVENT_KIND.OUTAGE)
+
+	return lane_spans.issue_spans({
+		starts: outages,
+		bounds: outages,
+		ends: lane_stop_stats.events_of(events, EVENT_KIND.CHILD_LAUNCH),
+	})
+}
+
+function offer_times(entries: ReadonlyArray<LedgerEntry>): Array<number> {
+	return entries
+		.filter((entry) => is_dispatch(entry) || OFFER_ANSWERS.has(entry.kind))
+		.map((entry) => Date.parse(entry.at))
+		.toSorted((left, right) => left - right)
+}
+
+function park_spans(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+): Array<Span> {
+	const offers = offer_times(entries)
+
+	return lane_stop_stats
+		.events_of(events, EVENT_KIND.PARK)
+		.map((park) => ({ from_ms: park.at_ms, end_ms: offers.find((at) => at > park.at_ms) }))
+}
+
+function is_followup_of(entry: LedgerEntry, merge: MergeEntry): boolean {
+	return (
+		is_stage(entry) &&
+		entry.stage === FOLLOWUP_STAGE &&
+		entry.issue === merge.issue &&
+		entry.at <= merge.at
+	)
+}
+
+function merge_span(entries: ReadonlyArray<LedgerEntry>, merge: MergeEntry): Span | undefined {
+	const followup = entries.findLast((entry) => is_followup_of(entry, merge))
+
+	return followup === undefined
+		? undefined
+		: { from_ms: Date.parse(followup.at), end_ms: Date.parse(merge.at) }
+}
+
+function merge_spans(entries: ReadonlyArray<LedgerEntry>): Array<Span> {
+	return entries
+		.filter((entry) => is_merge(entry))
+		.map((merge) => merge_span(entries, merge))
+		.filter((span) => span !== undefined)
+}
+
+function seconds(milliseconds: number | undefined): string {
+	return milliseconds === undefined
+		? NOT_MEASURED
+		: String(Math.round(milliseconds / MS_PER_SECOND))
+}
+
+function is_in(span: Span, window: StatsWindow): boolean {
+	return span.from_ms >= window.since_ms && span.from_ms <= window.until_ms
+}
+
+function gap_row(name: string, spans: ReadonlyArray<Span>, window: StatsWindow): string {
+	const started = spans.filter((span) => is_in(span, window))
+	const ended = started
+		.map((span) => (span.end_ms === undefined ? undefined : span.end_ms - span.from_ms))
+		.filter((value) => is_number(value))
+
+	return lane_stats.to_row([
+		name,
+		String(started.length),
+		seconds(lane_stats.median(ended)),
+		seconds(lane_stats.peak(ended)),
+		String(started.length - ended.length),
+	])
+}
+
+// The period's table: `entries` is the whole ledger and `events` the whole run-event stream, both
+// reduced here to the spans that started in `window`.
+function table(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+	events: ReadonlyArray<RunEvent> = [],
+): string {
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		gap_row(RELAUNCH, relaunch_spans(events), window),
+		gap_row(OUTAGE, outage_spans(events), window),
+		gap_row(PARK, park_spans(entries, events), window),
+		gap_row(YIELD, lane_net_time.yield_spans(entries, events), window),
+		gap_row(MERGE, merge_spans(entries), window),
+	].join('\n')
+}
+
+const lane_gap_stats = { table }
+
+export { lane_gap_stats }

package/scripts/lane/lane-guard-policy.ts

@@ -26,7 +26,7 @@ import { lane_child_marker, type MarkerSource } from './lane-child-marker'
 // The three ways a guard may behave in a lane child. Outside a lane child every
 // guard is `refuse`, which is why that is also the fail-safe default below.
 type LaneGuardMode = 'refuse' | 'notice' | 'off'
-type LaneGuardId = 'investigation' | 'batching' | 'rule' | 'duplicate-read'
+type LaneGuardId = 'investigation' | 'batching' | 'search-batching' | 'rule' | 'duplicate-read'
 
 // The mode outside a lane child, and the fail-safe for a guard nobody enumerated: a denial, the same
 // direction `delegation-policy.ts` takes, because a silenced rule is the one mistake that ships unseen.
@@ -55,6 +55,12 @@ const LANE_GUARD_POLICY: ReadonlyArray<LaneGuardEntry> = [
 		because:
 			'a refusal ends a child turn and every advisory notice was measured not to move the call density, so the guard is off and the density stays readable through `josh time:density`',
 	},
+	{
+		id: 'search-batching',
+		mode_in_lane_child: 'refuse',
+		because:
+			'the largest share of single-call pairs in lane children is a search chain (`grep` / `sed` issued one per turn, about 10,600 pairs in 14 days), and a refusal re-fires only every third single-call search turn, so one refused round trip (about $0.036) is repaid once it folds two later searches into one turn',
+	},
 	{
 		id: 'duplicate-read',
 		mode_in_lane_child: 'notice',

package/scripts/lane/lane-handoff.ts

@@ -1,7 +1,11 @@
 import { git_common_directory } from '#scripts/git/git-common-directory'
+import { run_carry } from '#scripts/run/carry/run-carry'
 import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
 import { lane_child_marker, type MarkerSource } from './lane-child-marker'
 
+type StartRead = (pid: number) => string | undefined
+
 // Whether a lane has handed its post-implementation region to the detached ship.
 //
 // **A child that ran `pnpm josh ship --detach` waits on nobody when it ends.** The supervisor drives the
@@ -24,6 +28,62 @@ function is_ship_running(issue: string, directory: string): boolean {
 	)
 }
 
+// A detached ship for `issue` launched at or after `since_ms` ended in success — it merged, so no cut
+// hand-off follows it. The record outlives its run until the next `ship --detach` replaces it, so a
+// success launched earlier belongs to a past dispatch of the issue and never counts.
+function is_ship_succeeded(issue: string, directory: string, since_ms: number): boolean {
+	const repository = git_common_directory.repository(directory)
+	const reading =
+		repository === undefined ? undefined : run_ship_detach.read_result(repository, issue)
+
+	return reading?.result === 'success' && (reading.launched_at ?? since_ms - 1) >= since_ms
+}
+
+async function read_repository(): Promise<string | undefined> {
+	try {
+		return await run_carry.repository_directory()
+	} catch {
+		return undefined
+	}
+}
+
+// `is_ship_running` for this checkout, for a reader that must not block its event loop
+// (joshuafolkken/kit#4245): the repository is read asynchronously once and every recorded start time
+// through `read`, so no answer starts a synchronous process.
+async function ship_reader(read: StartRead): Promise<(issue: string) => boolean> {
+	const repository = await read_repository()
+
+	return (issue) =>
+		repository !== undefined &&
+		run_ship_detach.read_result(repository, issue, read)?.result === 'running'
+}
+
+// The live ship for `issue` is inside `josh followup`: it waits on CI, CodeRabbit and the merge alone
+// (joshuafolkken/kit#4466). The mark is down while the followup stage merges and gates again, after a
+// stop, and once a successor supervisor opens the record (`run_ship_stage.read_merge_waiting`).
+function is_merge_waiting(repository: string, issue: string, read: StartRead): boolean {
+	if (run_ship_detach.read_result(repository, issue, read)?.result !== 'running') return false
+
+	return run_ship_stage.read_merge_waiting(run_ship_stage.record_path(repository, issue))
+}
+
+// `is_merge_waiting` for this checkout, read the way `ship_reader` reads.
+async function merge_wait_reader(read: StartRead): Promise<(issue: string) => boolean> {
+	const repository = await read_repository()
+
+	return (issue) => repository !== undefined && is_merge_waiting(repository, issue, read)
+}
+
+// The live ship for `issue` in the repository `directory` belongs to waits for a lane place before it
+// relaunches its child (`run-ship-place.ts`); a dead supervisor's mark reads as no wait.
+function is_place_waiting(issue: string, directory: string): boolean {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository === undefined || !is_ship_running(issue, directory)) return false
+
+	return run_ship_stage.read_place_waiting(run_ship_stage.record_path(repository, issue))
+}
+
 // When the detached ship for `issue` that is still live was launched, or `undefined` where none is.
 function ship_running_since(issue: string, directory: string): number | undefined {
 	const repository = git_common_directory.repository(directory)
@@ -40,6 +100,14 @@ function is_handed_off(directory: string, source: MarkerSource = process.env): b
 	return is_ship_running(issue, directory)
 }
 
-const lane_handoff = { is_handed_off, is_ship_running, ship_running_since }
+const lane_handoff = {
+	is_handed_off,
+	is_place_waiting,
+	is_ship_running,
+	is_ship_succeeded,
+	merge_wait_reader,
+	ship_reader,
+	ship_running_since,
+}
 
 export { lane_handoff }

package/scripts/lane/lane-held-stats.ts

@@ -0,0 +1,129 @@
+import { lane_ledger, type HeldEntry, type LedgerEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// How long a free lane stayed empty, and why: the ledger's `held` entries of one period reduced to one
+// row per reason, printed by `josh lane:stats` so the idle capacity a backlog stall episode reported
+// is split by cause — an offer that started nothing apart from a driver waiting on its session
+// (joshuafolkken/kit#3995).
+//
+// **A hold lasts until the next `held`, `released` or `dispatch` entry**: the driver writes one on every
+// offered pass that started nothing, so consecutive entries tile the wait and the last one ends at the
+// dispatch — or at the release a full pool or a finished run writes.
+// A hold nothing followed is counted under `not ended`, kept out of the minutes, whose time has no end;
+// one past `MAX_HOLD_MS` is a driver nobody restarted, read as ended at the cap.
+
+const COLUMNS = [
+	'held by',
+	'total (min)',
+	'median (min)',
+	'max (min)',
+	'holds',
+	'not ended',
+] as const
+const MS_PER_HOUR = 3_600_000
+const MAX_HOLD_MS = MS_PER_HOUR
+const { NOT_MEASURED } = lane_stage_stats
+// A period with no hold: the table still prints, so a reader sees zero holds rather than no table.
+const NONE_ROW = ['none', NOT_MEASURED, NOT_MEASURED, NOT_MEASURED, '0', '0']
+const { is_dispatch, is_number } = lane_stage_stats
+
+interface Hold {
+	reason: string
+	wait_ms: number | undefined
+}
+
+function is_held(entry: LedgerEntry): entry is HeldEntry {
+	return entry.kind === lane_ledger.KIND.HELD
+}
+
+function is_hold_end(entry: LedgerEntry): boolean {
+	return is_held(entry) || is_dispatch(entry) || entry.kind === lane_ledger.KIND.RELEASED
+}
+
+// Every instant a hold can end at, parsed and sorted once: holds come once a minute, so re-reading the
+// whole ledger per hold made a week's `lane:stats` take seconds.
+function end_times(entries: ReadonlyArray<LedgerEntry>): Array<number> {
+	return entries
+		.filter((entry) => is_hold_end(entry))
+		.map((entry) => Date.parse(entry.at))
+		.filter((at) => Number.isFinite(at))
+		.toSorted((left, right) => left - right)
+}
+
+function wait_ms(held: HeldEntry, ends: ReadonlyArray<number>): number | undefined {
+	const from_ms = Date.parse(held.at)
+	const end_ms = ends.find((at) => at > from_ms)
+
+	return end_ms === undefined ? undefined : Math.min(end_ms - from_ms, MAX_HOLD_MS)
+}
+
+function holds_of(entries: ReadonlyArray<LedgerEntry>): Array<Hold> {
+	const ends = end_times(entries)
+
+	return entries
+		.filter(is_held)
+		.map((held) => ({ reason: held.reason, wait_ms: wait_ms(held, ends) }))
+}
+
+function total(values: ReadonlyArray<number>): number {
+	return values.reduce((sum, value) => sum + value, 0)
+}
+
+function ended_of(holds: ReadonlyArray<Hold>, reason: string): Array<number> {
+	return holds
+		.filter((hold) => hold.reason === reason)
+		.map((hold) => hold.wait_ms)
+		.filter((value) => is_number(value))
+}
+
+function reason_row(reason: string, holds: ReadonlyArray<Hold>): string {
+	const ended = ended_of(holds, reason)
+	const count = holds.filter((hold) => hold.reason === reason).length
+
+	return lane_stats.to_row([
+		reason,
+		lane_stage_stats.cell(ended.length === 0 ? undefined : total(ended)),
+		lane_stage_stats.cell(lane_stats.median(ended)),
+		lane_stage_stats.cell(lane_stats.peak(ended)),
+		String(count),
+		String(count - ended.length),
+	])
+}
+
+// The reasons the period saw, the longest total first, so the cause worth removing next leads.
+function reasons_of(holds: ReadonlyArray<Hold>): Array<string> {
+	const reasons = [...new Set(holds.map((hold) => hold.reason))]
+
+	return reasons.toSorted(
+		(left, right) => total(ended_of(holds, right)) - total(ended_of(holds, left)),
+	)
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const holds = holds_of(lane_stats.in_window(entries, window))
+	const rows = reasons_of(holds).map((reason) => reason_row(reason, holds))
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...(rows.length === 0 ? [lane_stats.to_row(NONE_ROW)] : rows),
+	].join('\n')
+}
+
+function is_open_at(held: HeldEntry, now_ms: number): boolean {
+	return now_ms - Date.parse(held.at) < MAX_HOLD_MS
+}
+
+// The reason of the hold still open at the ledger's end, or `undefined` where the last one has ended —
+// or is past `MAX_HOLD_MS`, a driver killed while held that wrote no hand-back.
+function open_reason(entries: ReadonlyArray<LedgerEntry>, now_ms: number): string | undefined {
+	const last = entries.findLast((entry) => is_hold_end(entry))
+
+	return last !== undefined && is_held(last) && is_open_at(last, now_ms) ? last.reason : undefined
+}
+
+const lane_held_stats = { open_reason, table }
+
+export { lane_held_stats }