@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/lane/lane-breakdown-laps.ts

@@ -0,0 +1,107 @@
+import { lane_breakdown, type Breakdown, type Segment, type Stage } from './lane-breakdown'
+import { lane_breakdown_implement } from './lane-breakdown-implement'
+import { lane_ledger, type LedgerEntry } from './lane-ledger'
+import type { ToolCall } from './lane-transcript-calls'
+
+// What each ship stage of a lane's breakdown spent its time on (joshuafolkken/kit#5294): the laps the
+// ship wrote for its inner steps (`run-ship-lap.ts`), the lane's core-budget waits and the checks of
+// the lane's gates, each under the stage it ended in, and the time between two ship stages split by
+// the Bash the lane child ran there, by the implementation's kinds (`lane-breakdown-implement.ts`).
+// A lap and a wait or a check inside it overlap — the gate's wait for cores and its checks, run side
+// by side, are part of its `josh gate` lap — so a stage's laps can add up to more.
+
+const { KIND } = lane_ledger
+const CORE_WAIT_STEP = 'core-budget wait'
+
+// Each stage's laps, longest first, keyed by the stage's name in the breakdown.
+type Laps = ReadonlyMap<string, ReadonlyArray<Stage>>
+
+interface Placed {
+	at_ms: number
+	part: Stage
+}
+
+function lap_of(entry: LedgerEntry, issue: number): ReadonlyArray<Placed> {
+	if (entry.kind !== KIND.SHIP_LAP || entry.issue !== issue) return []
+
+	return [{ at_ms: Date.parse(entry.at), part: { name: entry.step, ms: entry.elapsed_ms } }]
+}
+
+function wait_of(entry: LedgerEntry, issue: number): ReadonlyArray<Placed> {
+	if (entry.kind !== KIND.CORE_WAIT || entry.issue !== issue) return []
+
+	return [{ at_ms: Date.parse(entry.at), part: { name: CORE_WAIT_STEP, ms: entry.waited_ms } }]
+}
+
+// Each check the lane's gate ran, placed where the gate ended (joshuafolkken/kit#5319). A row with no
+// `issue` — outside a lane, or written before the gate recorded it — is no lane's; a reused check
+// started nothing, so its zero is no time spent.
+function checks_of(entry: LedgerEntry, issue: number): ReadonlyArray<Placed> {
+	if (entry.kind !== KIND.GATE || entry.issue !== issue) return []
+	const at_ms = Date.parse(entry.at)
+
+	return (entry.checks ?? [])
+		.filter((check) => check.is_reused !== true)
+		.map((check) => ({ at_ms, part: { name: check.label, ms: check.elapsed_ms } }))
+}
+
+// The ship stage a lap, a wait or a check ended in — never the time between stages, which the ship runs nothing in.
+function stage_at(segments: ReadonlyArray<Segment>, at_ms: number): string | undefined {
+	const segment = segments.find((span) => at_ms > span.from_ms && at_ms <= span.to_ms)
+
+	return segment?.stage === lane_breakdown.BETWEEN_STAGE ? undefined : segment?.stage
+}
+
+function grouped(
+	placed: ReadonlyArray<Placed>,
+	segments: ReadonlyArray<Segment>,
+): Map<string, Array<Stage>> {
+	const groups = new Map<string, Array<Stage>>()
+
+	for (const { at_ms, part } of placed) {
+		const stage = stage_at(segments, at_ms)
+
+		if (stage !== undefined) groups.set(stage, [...(groups.get(stage) ?? []), part])
+	}
+
+	return groups
+}
+
+function between_of(
+	calls: ReadonlyArray<ToolCall>,
+	segments: ReadonlyArray<Segment>,
+): Array<Stage> {
+	const between = segments.filter((segment) => segment.stage === lane_breakdown.BETWEEN_STAGE)
+
+	return lane_breakdown_implement.bash_kinds(calls, between)
+}
+
+/** `issue`'s ship stages split by their laps, and the time between them by the lane child's Bash. */
+function of(
+	entries: ReadonlyArray<LedgerEntry>,
+	issue: number,
+	breakdown: Breakdown,
+	calls: ReadonlyArray<ToolCall>,
+): Laps {
+	const placed = entries.flatMap((entry) => [
+		...lap_of(entry, issue),
+		...wait_of(entry, issue),
+		...checks_of(entry, issue),
+	])
+	const laps = new Map(
+		[...grouped(placed, breakdown.ship)].map(([stage, parts]) => [
+			stage,
+			lane_breakdown.ranked(parts),
+		]),
+	)
+	const between = between_of(calls, breakdown.ship)
+
+	if (between.length > 0) laps.set(lane_breakdown.BETWEEN_STAGE, between)
+
+	return laps
+}
+
+const lane_breakdown_laps = { CORE_WAIT_STEP, of }
+
+export { lane_breakdown_laps }
+export type { Laps }

package/scripts/lane/lane-breakdown-pinned.ts

@@ -0,0 +1,76 @@
+import { lane_breakdown, type Breakdown } from './lane-breakdown'
+import { lane_ledger, type LedgerEntry, type TestPinnedEntry } from './lane-ledger'
+
+// What a lane's ship pre-detach spent on `josh test:pinned` (joshuafolkken/kit#5078): the lane's
+// `test-pinned` rows written inside that stage, as hunks the cache answered and the probed hunks'
+// test files and wall time, the longest first.
+
+type PinnedProbe = TestPinnedEntry['probes'][number]
+
+// The longest probes named; the rest are counted in the head alone.
+const MAX_SHOWN = 5
+
+// `run:review`'s check and the pre-detach's probe past its stop (joshuafolkken/kit#5327) alike.
+const DISCARDED_LABEL = 'background test:pinned probes discarded'
+
+function is_lane_row(entry: LedgerEntry, issue: number): entry is TestPinnedEntry {
+	return entry.kind === lane_ledger.KIND.TEST_PINNED && entry.issue === issue
+}
+
+function is_discarded(entry: TestPinnedEntry): boolean {
+	return entry.discarded === true
+}
+
+function is_in_pre_detach(entry: TestPinnedEntry, breakdown: Breakdown): boolean {
+	const at_ms = Date.parse(entry.at)
+
+	return breakdown.pre_detach.some((span) => at_ms >= span.from_ms && at_ms <= span.to_ms)
+}
+
+// `issue`'s `test-pinned` rows written inside its ship pre-detach stage.
+function rows_of(
+	entries: ReadonlyArray<LedgerEntry>,
+	issue: number,
+	breakdown: Breakdown,
+): Array<TestPinnedEntry> {
+	return entries
+		.filter((entry) => is_lane_row(entry, issue))
+		.filter((entry) => !is_discarded(entry) && is_in_pre_detach(entry, breakdown))
+}
+
+// `issue`'s background probes stopped before their answer (joshuafolkken/kit#5262, #5327), as a
+// count and their wall time; `''` when none was.
+function discarded_text(entries: ReadonlyArray<LedgerEntry>, issue: number): string {
+	const rows = entries
+		.filter((entry) => is_lane_row(entry, issue))
+		.filter((entry) => is_discarded(entry))
+	if (rows.length === 0) return ''
+	const elapsed_ms = rows.reduce((sum, row) => sum + row.elapsed_ms, 0)
+
+	return `${DISCARDED_LABEL} ${String(rows.length)}, ${lane_breakdown.minutes_text(elapsed_ms)}`
+}
+
+function probe_text(probe: PinnedProbe): string {
+	const tests = probe.tests === undefined ? '' : ` ${String(probe.tests)} test files`
+
+	return `${probe.file}${tests} ${lane_breakdown.minutes_text(probe.elapsed_ms)}`
+}
+
+// The detail the pre-detach line carries, or `''` when no probe ran inside it.
+function detail_text(rows: ReadonlyArray<TestPinnedEntry>): string {
+	if (rows.length === 0) return ''
+	const probes = rows
+		.flatMap((row) => row.probes)
+		.toSorted((left, right) => right.elapsed_ms - left.elapsed_ms)
+	const held = rows.reduce((sum, row) => sum + row.held, 0)
+	const rewired = rows.reduce((sum, row) => sum + (row.rewired ?? 0), 0)
+	const total = held + rewired + probes.length
+	const head = `test:pinned ${String(total)} hunks, ${String(held)} cached, ${String(probes.length)} probed`
+	const counts = rewired === 0 ? [head] : [head, `${String(rewired)} rewired`]
+
+	return ` (${[...counts, ...probes.slice(0, MAX_SHOWN).map((probe) => probe_text(probe))].join(', ')})`
+}
+
+const lane_breakdown_pinned = { detail_text, discarded_text, rows_of }
+
+export { lane_breakdown_pinned }

package/scripts/lane/lane-breakdown-text.ts

@@ -0,0 +1,145 @@
+import { lane_breakdown, type Breakdown, type Stage } from './lane-breakdown'
+import { lane_breakdown_implement, type ImplementDetail } from './lane-breakdown-implement'
+import { lane_breakdown_laps, type Laps } from './lane-breakdown-laps'
+import { lane_breakdown_pinned } from './lane-breakdown-pinned'
+import { lane_ci_path_stats } from './lane-ci-path-stats'
+import type { LedgerEntry } from './lane-ledger'
+
+// A lane's breakdown in words (joshuafolkken/kit#4995): the stages longest first, the implementation's
+// tool-call kinds beside it, and the waits taken out last. `josh lane:breakdown` prints it, the overrun
+// investigation comments it on the lane's Issue and leads its prompt with it (`lane-overrun.ts`).
+
+const HEADING = 'Net time by stage, longest first'
+const EXCLUDED = 'waits taken out (park, outage, usage limit, yield, host sleep)'
+const SLEPT = 'of which host sleep'
+const YIELDED = 'of which yield wait'
+
+interface Report {
+	breakdown: Breakdown
+	detail: ImplementDetail
+	// The ship pre-detach line's `test:pinned` detail, `''` when none (joshuafolkken/kit#5078).
+	pinned?: string
+	// The discarded `run:review` background probes' line, `''` when none (joshuafolkken/kit#5262).
+	discarded?: string
+	// The followup's CI wait's last check to settle, `''` when none was recorded (joshuafolkken/kit#5295).
+	critical?: string
+	// Each ship stage's laps, and the Bash between ship stages, longest first (joshuafolkken/kit#5294).
+	laps?: Laps
+}
+
+// A stage's line and the laps printed under it.
+interface Entry {
+	text: string
+	laps: ReadonlyArray<string>
+}
+
+function part_text(part: Stage): string {
+	return `${part.name} ${lane_breakdown.minutes_text(part.ms)}`
+}
+
+// A kind's minutes, and the backgrounded subagent calls it counted at no time.
+function kind_text(kind: Stage, untimed: ImplementDetail['untimed']): string {
+	const count = untimed.get(kind.name) ?? 0
+
+	return count > 0 ? `${part_text(kind)} + ${String(count)} backgrounded, untimed` : part_text(kind)
+}
+
+function detail_text(detail: ImplementDetail): string {
+	const kinds = detail.kinds.map((kind) => kind_text(kind, detail.untimed))
+	const count = String(detail.background)
+	const background =
+		detail.background > 0 ? [`${count} backgrounded calls, their waits in editing & thinking`] : []
+
+	return ` (${[...kinds, ...background].join(', ')})`
+}
+
+// Why a ship stage ran or was skipped, as its event line said (joshuafolkken/kit#5296).
+function reason_text(reason: string | undefined): string {
+	return reason === undefined ? '' : ` (${reason})`
+}
+
+// The detail a stage's line carries after its minutes, `''` for a stage with none.
+function suffix_of(name: string, report: Report): string {
+	const suffixes: Record<string, string | undefined> = {
+		[lane_breakdown.IMPLEMENT_STAGE]: detail_text(report.detail),
+		[lane_breakdown.PRE_DETACH_STAGE]: report.pinned,
+		[lane_breakdown.FOLLOWUP_STAGE]: report.critical,
+	}
+
+	return suffixes[name] ?? reason_text(report.breakdown.reasons?.get(name))
+}
+
+function stage_entry(stage: Stage, report: Report): Entry {
+	const laps = report.laps?.get(stage.name) ?? []
+
+	return {
+		text: `${part_text(stage)}${suffix_of(stage.name, report)}`,
+		laps: laps.map((lap) => part_text(lap)),
+	}
+}
+
+function entries_of(report: Report): Array<Entry> {
+	const { breakdown } = report
+	const yielded = `${YIELDED} ${lane_breakdown.minutes_text(breakdown.yield_ms)}`
+	const slept = `${SLEPT} ${lane_breakdown.minutes_text(breakdown.slept_ms)}`
+	const excluded = `${EXCLUDED} ${lane_breakdown.minutes_text(breakdown.excluded_ms)}, ${yielded}, ${slept}`
+
+	const discarded =
+		report.discarded === undefined || report.discarded === '' ? [] : [report.discarded]
+
+	const tail = [...discarded, excluded].map((text) => ({ text, laps: [] }))
+
+	return [...breakdown.stages.map((stage) => stage_entry(stage, report)), ...tail]
+}
+
+function bullets_of(entry: Entry): Array<string> {
+	return [`- ${entry.text}`, ...entry.laps.map((lap) => `  - ${lap}`)]
+}
+
+function inline_of(entry: Entry): string {
+	return entry.laps.length > 0 ? `${entry.text} [${entry.laps.join(', ')}]` : entry.text
+}
+
+// `issue`'s breakdown with its implementation's tool calls read off its transcripts, and its ship
+// pre-detach's `test:pinned` rows read off `entries`.
+function report_of(
+	issue: number,
+	breakdown: Breakdown,
+	entries: ReadonlyArray<LedgerEntry>,
+): Report {
+	const calls = lane_breakdown_implement.read(issue, breakdown)
+	const rows = lane_breakdown_pinned.rows_of(entries, issue, breakdown)
+
+	return {
+		breakdown,
+		detail: lane_breakdown_implement.of(calls, breakdown),
+		laps: lane_breakdown_laps.of(entries, issue, breakdown, calls),
+		pinned: lane_breakdown_pinned.detail_text(rows),
+		discarded: lane_breakdown_pinned.discarded_text(entries, issue),
+		critical: lane_ci_path_stats.last_check_text(entries, issue),
+	}
+}
+
+// The Issue comment and the printout: a heading, then one bullet per stage.
+function comment(issue: number, minutes: number, report: Report): string {
+	const lead = `${HEADING}, ${String(minutes)} min of net time`
+	const source = `(\`pnpm josh lane:breakdown ${String(issue)}\`):`
+
+	return [
+		`${lead} ${source}`,
+		'',
+		...entries_of(report).flatMap((entry) => bullets_of(entry)),
+	].join('\n')
+}
+
+// One line, the form the investigation's prompt leads with.
+function line(report: Report): string {
+	return `${HEADING}: ${entries_of(report)
+		.map((entry) => inline_of(entry))
+		.join('; ')}.`
+}
+
+const lane_breakdown_text = { comment, line, report_of }
+
+export { lane_breakdown_text }
+export type { Report }

package/scripts/lane/lane-breakdown.ts

@@ -0,0 +1,239 @@
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { lane_ledger, type LedgerEntry } from './lane-ledger'
+import { lane_net_time, type LaneSpan } from './lane-net-time'
+import { lane_stop_stats } from './lane-stop-stats'
+
+// A lane's net time by stage (joshuafolkken/kit#4995), read off the run events it already leaves: from
+// its dispatch to its `plan`, the implementation from the `plan` (or `lane-phase implement`) to the first
+// ship stage, each ship stage from its start to its end, and the time between ship stages — a stopped
+// stage's fix included. The waits `lane:net` takes out are taken out of the stage they fell in and
+// counted apart, so the stages add up to the net time. A cut and its resume open no stage: the
+// implementation stays one stage across them.
+
+const { EVENT_KIND } = run_event_stream
+const { PHASE } = run_ship_stage
+
+const PLAN_STAGE = 'start to plan'
+const IMPLEMENT_STAGE = 'implement'
+const BETWEEN_STAGE = 'between ship stages'
+const SHIP_LEAD = 'ship '
+const IMPLEMENT_SUFFIX = ' implement'
+const PRE_DETACH_STAGE = `${SHIP_LEAD}${lane_ledger.PRE_DETACH_STAGE}`
+const FOLLOWUP_STAGE = `${SHIP_LEAD}${run_ship_stage.STAGE.FOLLOWUP}`
+
+// One stage's net milliseconds.
+interface Stage {
+	name: string
+	ms: number
+}
+
+interface Breakdown {
+	// Longest first, the waits taken out.
+	stages: ReadonlyArray<Stage>
+	// The waits taken out, together.
+	excluded_ms: number
+	// The host's sleeps among them (joshuafolkken/kit#5032).
+	slept_ms: number
+	// The yields' waits for a redispatch among them (joshuafolkken/kit#5216).
+	yield_ms: number
+	// The waits taken out, each — the implementation's split leaves them out of its remainder too.
+	waits: ReadonlyArray<LaneSpan>
+	// The implementation's spans, waits left in — the window its tool calls are read in.
+	implement: ReadonlyArray<LaneSpan>
+	// The ship pre-detach stage's spans — the window its `test:pinned` rows are read in
+	// (joshuafolkken/kit#5078).
+	pre_detach: ReadonlyArray<LaneSpan>
+	// Each ship stage's spans and the spans between them, waits left in — the windows its laps and the
+	// fixes between stages are read in (joshuafolkken/kit#5294).
+	ship: ReadonlyArray<Segment>
+	// Why each ship stage last ran or was skipped, where its event line said (joshuafolkken/kit#5296).
+	reasons?: ReadonlyMap<string, string>
+}
+
+interface Segment extends LaneSpan {
+	stage: string
+}
+
+function is_ship(segment: Segment): boolean {
+	return segment.stage.startsWith(SHIP_LEAD) || segment.stage === BETWEEN_STAGE
+}
+
+interface Marker {
+	at_ms: number
+	stage: string
+}
+
+function ship_stage_of(text: string): string {
+	const { stage, phase } = run_ship_stage.words_of(text)
+
+	return phase === PHASE.START ? `${SHIP_LEAD}${stage}` : BETWEEN_STAGE
+}
+
+// The stage an event opens, `undefined` for one that opens none.
+function stage_of(event: RunEvent): string | undefined {
+	if (event.kind === EVENT_KIND.SHIP_STAGE) return ship_stage_of(event.text)
+	const is_implement =
+		event.kind === EVENT_KIND.PLAN ||
+		(event.kind === EVENT_KIND.LANE_PHASE && event.text.endsWith(IMPLEMENT_SUFFIX))
+
+	return is_implement ? IMPLEMENT_STAGE : undefined
+}
+
+function is_inside(at_ms: number, span: LaneSpan): boolean {
+	return at_ms >= span.from_ms && at_ms < span.to_ms
+}
+
+function is_lane_event(event: RunEvent, issue: number, span: LaneSpan): boolean {
+	return lane_stop_stats.issue_of(event) === issue && is_inside(Date.parse(event.at), span)
+}
+
+function marker_of(event: RunEvent, issue: number, span: LaneSpan): ReadonlyArray<Marker> {
+	const stage = stage_of(event)
+	const at_ms = Date.parse(event.at)
+
+	return stage !== undefined && is_lane_event(event, issue, span) ? [{ at_ms, stage }] : []
+}
+
+function reason_of(event: RunEvent, issue: number, span: LaneSpan): Array<[string, string]> {
+	if (event.kind !== EVENT_KIND.SHIP_STAGE || !is_lane_event(event, issue, span)) return []
+
+	const reason = run_ship_stage.reason_of(event.text)
+	const stage = `${SHIP_LEAD}${run_ship_stage.words_of(event.text).stage}`
+
+	return reason === undefined ? [] : [[stage, reason]]
+}
+
+// The newest reason each ship stage's event line gave, by the stage's name.
+function reasons_of(
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+	span: LaneSpan,
+): Map<string, string> {
+	const ordered = events.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+
+	return new Map(ordered.flatMap((event) => reason_of(event, issue, span)))
+}
+
+function segments_of(
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+	span: LaneSpan,
+): Array<Segment> {
+	const opened = events
+		.flatMap((event) => marker_of(event, issue, span))
+		.toSorted((left, right) => left.at_ms - right.at_ms)
+	// A marker of the stage already open opens nothing: the `plan` and `lane-phase implement` of one
+	// start, or of a resumed session, leave the implementation one span.
+	const markers = [{ at_ms: span.from_ms, stage: PLAN_STAGE }, ...opened].filter(
+		(marker, index, all) => marker.stage !== all[index - 1]?.stage,
+	)
+
+	return markers.map((marker, index) => ({
+		stage: marker.stage,
+		from_ms: marker.at_ms,
+		to_ms: markers[index + 1]?.at_ms ?? span.to_ms,
+	}))
+}
+
+function clipped(segment: LaneSpan, parts: ReadonlyArray<LaneSpan>): Array<LaneSpan> {
+	return parts
+		.map((part) => ({
+			from_ms: Math.max(segment.from_ms, part.from_ms),
+			to_ms: Math.min(segment.to_ms, part.to_ms),
+		}))
+		.filter((part) => part.to_ms > part.from_ms)
+		.toSorted((left, right) => left.from_ms - right.from_ms)
+}
+
+// The milliseconds of `segment` that any of `parts` covers, each covered millisecond once — parallel
+// tool calls, or a call across a wait, overlap.
+function covered_ms(segment: LaneSpan, parts: ReadonlyArray<LaneSpan>): number {
+	let reached_ms = segment.from_ms
+	let total_ms = 0
+
+	for (const part of clipped(segment, parts)) {
+		total_ms += Math.max(0, part.to_ms - Math.max(part.from_ms, reached_ms))
+		reached_ms = Math.max(reached_ms, part.to_ms)
+	}
+
+	return total_ms
+}
+
+// Each name's milliseconds summed, longest first — the stages here and the tool-call kinds of the
+// implementation (`lane-breakdown-implement.ts`) alike.
+function ranked(parts: ReadonlyArray<Stage>): Array<Stage> {
+	const totals = new Map<string, number>()
+
+	for (const part of parts) totals.set(part.name, (totals.get(part.name) ?? 0) + part.ms)
+
+	return [...totals]
+		.map(([name, ms]) => ({ name, ms }))
+		.toSorted((left, right) => right.ms - left.ms)
+}
+
+function spans_ms(spans: ReadonlyArray<LaneSpan>): number {
+	return spans.reduce((sum, span) => sum + span.to_ms - span.from_ms, 0)
+}
+
+/**
+ * `issue`'s lane by stage, or `undefined` when the ledger holds no dispatch and merge of it — the same
+ * span and waits `lane_net_time.net_ms` reads, so the stages add up to it.
+ */
+function of(
+	entries: ReadonlyArray<LedgerEntry>,
+	events: ReadonlyArray<RunEvent>,
+	issue: number,
+): Breakdown | undefined {
+	const span = lane_net_time.span_of(entries, issue)
+
+	if (span === undefined) return undefined
+
+	const waits = lane_net_time.waits(entries, events, issue, span)
+	const segments = segments_of(events, issue, span)
+	const parts = segments.map((segment) => ({
+		name: segment.stage,
+		ms: segment.to_ms - segment.from_ms - covered_ms(segment, waits),
+	}))
+
+	return {
+		stages: ranked(parts),
+		excluded_ms: spans_ms(waits),
+		slept_ms: spans_ms(lane_net_time.slept(events, span)),
+		yield_ms: spans_ms(lane_net_time.yielded(entries, events, issue, span)),
+		waits,
+		implement: segments.filter((segment) => segment.stage === IMPLEMENT_STAGE),
+		pre_detach: segments.filter((segment) => segment.stage === PRE_DETACH_STAGE),
+		ship: segments.filter((segment) => is_ship(segment)),
+		reasons: reasons_of(events, issue, span),
+	}
+}
+
+function minutes_text(ms: number): string {
+	return `${(ms / MS_PER_MINUTE).toFixed(1)} min`
+}
+
+// The longest stage in whole minutes, the words the overrun's start note carries.
+function longest_of(breakdown: Breakdown): { name: string; minutes: number } | undefined {
+	const [longest] = breakdown.stages
+
+	return longest === undefined
+		? undefined
+		: { name: longest.name, minutes: Math.round(longest.ms / MS_PER_MINUTE) }
+}
+
+const lane_breakdown = {
+	BETWEEN_STAGE,
+	FOLLOWUP_STAGE,
+	IMPLEMENT_STAGE,
+	PRE_DETACH_STAGE,
+	covered_ms,
+	longest_of,
+	minutes_text,
+	of,
+	ranked,
+}
+
+export { lane_breakdown }
+export type { Breakdown, Segment, Stage }

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

@@ -1,10 +1,16 @@
 import { MS_PER_SECOND } from '#scripts/lib/timeouts'
-import { lane_ledger, type GateCheckRecord, type GateEntry, type LedgerEntry } from './lane-ledger'
+import {
+	lane_ledger,
+	type GateCheckRecord,
+	type GateEntry,
+	type LedgerEntry,
+	type PushMissEntry,
+} from './lane-ledger'
 import { lane_stage_stats } from './lane-stage-stats'
 import { lane_stats, type StatsWindow } from './lane-stats'
 
 // Which check a gate waited on: one period's per-check rows reduced to one row per check — median,
-// maximum, runs, reuses, no-ops and whole-suite fallbacks — printed last by `josh lane:stats`.
+// maximum, runs, reuses, no-ops and whole-suite fallbacks — printed by `josh lane:stats`.
 //
 // The whole gate is the first row, since its reuse started no check (joshuafolkken/kit#4397); the
 // checks follow in the order they first appear.
@@ -15,7 +21,8 @@ import { lane_stats, type StatsWindow } from './lane-stats'
 // would stand for a run that tested nothing.
 //
 // **The fallbacks are broken down by why** in a second table, one row per reason kind, so a slow unit
-// leg can be read as the full suite it ran and the reason it had to.
+// leg can be read as the full suite it ran and the reason it had to. A pre-push hook that ran a suite
+// over a record it could not reuse joins it, prefixed `pre-push <scope>:`.
 
 const DECIMALS = 1
 const WHOLE_GATE_LABEL = 'gate (whole)'
@@ -69,8 +76,21 @@ function whole_gate(gate: GateEntry): GateCheckRecord {
 	}
 }
 
-function fallback_table(checks: ReadonlyArray<GateCheckRecord>): string {
-	const reasons = checks.map((check) => check.fallback).filter((reason) => reason !== undefined)
+function is_push_miss(entry: LedgerEntry): entry is PushMissEntry {
+	return entry.kind === lane_ledger.KIND.PUSH_MISS
+}
+
+// A pre-push hook's miss, told apart from the gate's own fallbacks by its scope (joshuafolkken/kit#5234).
+function push_reason(miss: PushMissEntry): string {
+	return `pre-push ${miss.scope}: ${miss.reason}`
+}
+
+function fallback_table(
+	checks: ReadonlyArray<GateCheckRecord>,
+	misses: ReadonlyArray<PushMissEntry>,
+): string {
+	const fallbacks = checks.map((check) => check.fallback).filter((reason) => reason !== undefined)
+	const reasons = [...fallbacks, ...misses.map((miss) => push_reason(miss))]
 	const kinds = [...new Set(reasons)]
 	const rows = kinds.map((kind) =>
 		lane_stats.to_row([kind, String(reasons.filter((reason) => reason === kind).length)]),
@@ -81,17 +101,18 @@ function fallback_table(checks: ReadonlyArray<GateCheckRecord>): string {
 
 // The period's tables: `entries` is the whole ledger, filtered here to `window`.
 function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
-	const gates = lane_stats.in_window(entries, window).filter(is_gate)
+	const windowed = lane_stats.in_window(entries, window)
+	const gates = windowed.filter(is_gate)
 	const checks = gates.flatMap((gate) => gate.checks ?? [])
 	const rows = [...gates.map((gate) => whole_gate(gate)), ...checks]
 	const labels = [...new Set(rows.map((row) => row.label))]
 
 	return [
 		[...header(COLUMNS), ...labels.map((label) => check_row(label, rows))].join('\n'),
-		fallback_table(checks),
+		fallback_table(checks, windowed.filter(is_push_miss)),
 	].join('\n\n')
 }
 
-const lane_check_stats = { WHOLE_GATE_LABEL, table }
+const lane_check_stats = { WHOLE_GATE_LABEL, cell, header, table }
 
 export { lane_check_stats }

package/scripts/lane/lane-child-invocation.ts

@@ -95,8 +95,8 @@ function outage_resume_invocation(issue: string): string {
 // tail and the changed files (`run-ship-stop-context.ts`), so the session starts at the fix rather than
 // at `josh ship --log` and `git diff` (joshuafolkken/kit#3923).
 //
-// The context gets what the rest of the prompt leaves of the one argv element's cap, so the whole
-// prompt still launches (joshuafolkken/kit#3964).
+// The context gets what the rest of the prompt leaves of `MAX_VALUE_LENGTH`, so the whole prompt
+// stays within it and launches (joshuafolkken/kit#3964).
 function known_stop_lines(
 	issue: string,
 	stop: ShipStop,
@@ -127,6 +127,12 @@ function ship_stop_invocation(issue: string, stop?: ShipStop): string {
 	return [opening, ...middle, closing].join(LINE_BREAK)
 }
 
+// The same stop for the session that launched the ship and still waits on it (`run-ship-waiter.ts`):
+// the next command and the context alone, since that session has the run in front of it already.
+function ship_stop_note(issue: string, stop: ShipStop): string {
+	return known_stop_lines(issue, stop, []).join(LINE_BREAK)
+}
+
 const lane_child_invocation = {
 	child_invocation,
 	outage_resume_invocation,
@@ -135,6 +141,7 @@ const lane_child_invocation = {
 	review_invocation,
 	ship_pattern,
 	ship_stop_invocation,
+	ship_stop_note,
 }
 
 export type { ShipStop }

package/scripts/lane/lane-child-mark-keys.ts

@@ -0,0 +1,12 @@
+// The environment keys a launcher marks a lane child with, in a module of their own so the unit
+// suite's vitest config reads them without widening its import graph (`whole-suite-files.ts`).
+// `lane-child-marker.ts` documents each mark; a mark added there is added here, and the unit suite
+// then blanks it with no list of its own (joshuafolkken/kit#5029).
+
+const KEY = 'JOSH_LANE_CHILD'
+const OVERRUN_KEY = 'JOSH_LANE_OVERRUN'
+const MARK_KEYS: ReadonlyArray<string> = [KEY, OVERRUN_KEY]
+
+const lane_child_mark_keys = { KEY, MARK_KEYS, OVERRUN_KEY }
+
+export { lane_child_mark_keys }