@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lane/lane-session-reread.ts

@@ -0,0 +1,51 @@
+import { fileURLToPath } from 'node:url'
+import { json_value } from '#scripts/lib/json-value'
+import { execa } from 'execa'
+import { z } from 'zod'
+import { lane_registry } from './lane-registry'
+import { lane_session_action, type BrokerAnswer } from './lane-session-action'
+
+// **A request the supervisor's loaded code refuses is read again by the code on disk**
+// (joshuafolkken/kit#4732): the `run:wake` supervisor reloads only at a pass boundary, so a schema main
+// widened after it started refused the request a stopped ship sent, and the lane it should have
+// relaunched was parked instead. A fresh process of this file's sibling entry reads the request with
+// the schema main has now and performs the action; it prints the answer only when it read the request,
+// so a disk as old as the supervisor leaves the refusal to the broker.
+
+const ENTRY = fileURLToPath(new URL('lane-session-reread-main.ts', import.meta.url))
+const answer_schema = z.discriminatedUnion('is_success', [
+	z.object({ is_success: z.literal(true) }).strict(),
+	z.object({ is_success: z.literal(false), reason: z.string() }).strict(),
+])
+
+// The fresh process's side: the answer to a request read with the schema on disk, or `undefined` where
+// the request is unreadable or no open lane carries the issue.
+async function answer_text(issue: string, text: string): Promise<BrokerAnswer | undefined> {
+	const request = json_value.parse_with(text, lane_session_action.request_schema)
+	if (request === undefined) return undefined
+
+	const lane = await lane_registry.find_open_lane(issue)
+	if (lane === undefined) return undefined
+
+	return await lane_session_action.answer(lane, request.action)
+}
+
+function last_line(text: string): string {
+	return text.trimEnd().split('\n').at(-1) ?? ''
+}
+
+// The supervisor's side: the fresh process's answer, or `undefined` where it read nothing.
+async function reread(issue: string, received: unknown): Promise<BrokerAnswer | undefined> {
+	const result = await execa(
+		process.execPath,
+		[...process.execArgv, ENTRY, issue, JSON.stringify(received)],
+		{ reject: false, stderr: 'inherit' },
+	)
+	if (result.exitCode !== 0) return undefined
+
+	return json_value.parse_with(last_line(result.stdout), answer_schema)
+}
+
+const lane_session_reread = { answer_text, reread }
+
+export { lane_session_reread }

package/scripts/lane/lane-ship-lap-stats.ts

@@ -0,0 +1,74 @@
+import { lane_check_stats } from './lane-check-stats'
+import { lane_ledger, type LedgerEntry, type ShipLapEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// What the ship stages spent their time on (joshuafolkken/kit#5294): one period's `ship-lap` entries
+// reduced to one row per stage and inner step — median, maximum and runs — printed by `josh lane:stats`
+// under the stage table. The rows follow the stages' running order, a stage's steps longest first.
+//
+// **A row's first cell names both, `<stage>: <step>`**: `lane:value cell` finds a row by its first
+// cell alone, and a stage records several steps while a step (`scoped pair`) runs in several stages.
+
+const COLUMNS = ['ship step', 'median (min)', 'max (min)', 'runs'] as const
+const STAGE_ORDER: ReadonlyArray<string> = lane_stage_stats.STAGES
+
+interface Group {
+	stage: string
+	step: string
+	elapsed: ReadonlyArray<number>
+}
+
+function is_ship_lap(entry: LedgerEntry): entry is ShipLapEntry {
+	return entry.kind === lane_ledger.KIND.SHIP_LAP
+}
+
+function groups_of(laps: ReadonlyArray<ShipLapEntry>): Array<Group> {
+	const keys = [...new Map(laps.map((lap) => [`${lap.stage}\n${lap.step}`, lap])).values()]
+
+	return keys.map(({ stage, step }) => ({
+		stage,
+		step,
+		elapsed: laps
+			.filter((lap) => lap.stage === stage && lap.step === step)
+			.map((lap) => lap.elapsed_ms),
+	}))
+}
+
+// A stage `STAGES` does not name sorts after every stage it does.
+function stage_rank(stage: string): number {
+	const index = STAGE_ORDER.indexOf(stage)
+
+	return index === -1 ? STAGE_ORDER.length : index
+}
+
+function compare(left: Group, right: Group): number {
+	const by_stage = stage_rank(left.stage) - stage_rank(right.stage)
+
+	if (by_stage !== 0) return by_stage
+
+	return (lane_stats.median(right.elapsed) ?? 0) - (lane_stats.median(left.elapsed) ?? 0)
+}
+
+function row_of(group: Group): string {
+	return lane_stats.to_row([
+		`${group.stage}: ${group.step}`,
+		lane_stage_stats.cell(lane_stats.median(group.elapsed)),
+		lane_stage_stats.cell(lane_stats.peak(group.elapsed)),
+		String(group.elapsed.length),
+	])
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const laps = lane_stats.in_window(entries, window).filter(is_ship_lap)
+	const rows = groups_of(laps)
+		.toSorted(compare)
+		.map((group) => row_of(group))
+
+	return [...lane_check_stats.header(COLUMNS), ...rows].join('\n')
+}
+
+const lane_ship_lap_stats = { table }
+
+export { lane_ship_lap_stats }

package/scripts/lane/lane-sleep.ts

@@ -0,0 +1,58 @@
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+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 type { LaneSpan } from './lane-net-time'
+
+// The host's sleep (joshuafolkken/kit#5032): a closed lid stops every lane, yet no park, outage or
+// usage-limit event says so, and its minutes read as work. The load sampler's timer does not fire while
+// the host sleeps, so a tick later than a few intervals is the sign: the wall clock past the tick that
+// was due is recorded as one `sleep` event, and every lane's net time takes it out (`lane-net-time.ts`).
+// A tick merely slowed by load runs well inside the threshold, so a busy host is not read as asleep.
+
+const { EVENT_KIND } = run_event_stream
+
+const GAP_INTERVALS = 3
+
+/** The sleep between two ticks `interval_ms` apart, or `undefined` when the later one was on time. */
+function gap_of(last_ms: number, now_ms: number, interval_ms: number): LaneSpan | undefined {
+	if (now_ms - last_ms <= interval_ms * GAP_INTERVALS) return undefined
+
+	return { from_ms: last_ms + interval_ms, to_ms: now_ms }
+}
+
+function event_of(span: LaneSpan): Omit<RunEvent, 'pos'> {
+	const elapsed_ms = span.to_ms - span.from_ms
+	const minutes = (elapsed_ms / MS_PER_MINUTE).toFixed(1)
+
+	// Stamped at the wake, when it is appended: a stream reader takes its newest line for the newest time.
+	return {
+		at: new Date(span.to_ms).toISOString(),
+		kind: EVENT_KIND.SLEEP,
+		text: `host slept ${minutes} min`,
+		elapsed_ms,
+	}
+}
+
+/** Append `span` as a `sleep` event to `events_path`, or to this checkout's run stream when absent. */
+async function record(span: LaneSpan, events_path?: string): Promise<void> {
+	const target = events_path ?? (await run_event_stream_emit.stream_target())
+
+	if (target === undefined) return
+
+	run_event_stream.append_event(target, event_of(span))
+}
+
+// Every sleep on `events`, oldest first.
+function spans(events: ReadonlyArray<RunEvent>): Array<LaneSpan> {
+	return events
+		.filter((event) => event.kind === EVENT_KIND.SLEEP)
+		.map((event) => {
+			const to_ms = Date.parse(event.at)
+
+			return { from_ms: to_ms - (event.elapsed_ms ?? 0), to_ms }
+		})
+}
+
+const lane_sleep = { gap_of, record, spans }
+
+export { lane_sleep }

package/scripts/lane/lane-snapshot-trace.ts

@@ -0,0 +1,84 @@
+import {
+	PROCESS_ALIVE,
+	PROCESS_NONE,
+	PROCESS_UNKNOWN,
+	type ProcessTrace,
+} from '#scripts/run/run-liveness'
+import { lane_child_invocation } from './lane-child-invocation'
+import { lane_handoff } from './lane-handoff'
+import { lane_process_table, type ProcessTable, type TableRead } from './lane-process-table'
+import type { TreeProbes } from './lane-reap'
+
+// `lane_await.process_trace_default` answered for many lanes from one process snapshot
+// (joshuafolkken/kit#4245). That probe starts a synchronous `pgrep` per lane and reads the ship record's
+// start time through another `ps`, so a reader asking about every lane each few seconds — `run:board`,
+// the backlogrun drive — blocked its event loop for as long as the lanes took between them.
+//
+// **The answers are the probe's own.** A command line matching the lane's pattern, or a detached ship
+// still running for it, is `alive`; a snapshot that matched neither is `none`; a snapshot that could not
+// be read is `unknown`, as an unanswered `pgrep` is. The ship record is read only for a lane no process
+// matched, which is the only lane its answer can change.
+
+type TraceRead = (issue: string) => ProcessTrace
+
+function is_matched(probes: TreeProbes, issue: string): boolean {
+	return probes.matching(lane_child_invocation.process_pattern(issue)).length > 0
+}
+
+/** Each of `issues` traced from `rows`, the snapshot `undefined` where it could not be read. */
+async function traces_of(
+	issues: ReadonlyArray<string>,
+	rows: ProcessTable | undefined,
+): Promise<TraceRead> {
+	if (rows === undefined) return () => PROCESS_UNKNOWN
+
+	const probes = lane_process_table.probes_of(rows)
+	const unmatched = issues.filter((issue) => !is_matched(probes, issue))
+	const is_shipping =
+		unmatched.length === 0
+			? (): boolean => false
+			: await lane_handoff.ship_reader(lane_process_table.start_reader(rows))
+	const idle = new Set(unmatched.filter((issue) => !is_shipping(issue)))
+
+	return (issue) => (idle.has(issue) ? PROCESS_NONE : PROCESS_ALIVE)
+}
+
+function never_merge_waiting(): boolean {
+	return false
+}
+
+/**
+ * Whether each of `issues` has a detached ship waiting on its merge (`lane_handoff.merge_wait_reader`),
+ * read from `rows`. The record is read only where the snapshot shows that lane's ship supervisor, so a
+ * count with no ship running starts no process (joshuafolkken/kit#4466).
+ */
+async function merge_waits_of(
+	issues: ReadonlyArray<string>,
+	rows: ProcessTable | undefined,
+): Promise<(issue: string) => boolean> {
+	if (rows === undefined) return never_merge_waiting
+
+	const probes = lane_process_table.probes_of(rows)
+	const shipping = issues.filter(
+		(issue) => probes.matching(lane_child_invocation.ship_pattern(issue)).length > 0,
+	)
+
+	if (shipping.length === 0) return never_merge_waiting
+
+	return await lane_handoff.merge_wait_reader(lane_process_table.start_reader(rows))
+}
+
+/** How many of `issues` have a detached ship in this checkout waiting on its merge, from a fresh snapshot. */
+async function count_merge_waiting(
+	issues: ReadonlyArray<string>,
+	table: TableRead = lane_process_table.read_table,
+): Promise<number> {
+	const is_waiting = await merge_waits_of(issues, await table())
+
+	return issues.filter((issue) => is_waiting(issue)).length
+}
+
+const lane_snapshot_trace = { count_merge_waiting, merge_waits_of, traces_of }
+
+export { lane_snapshot_trace }
+export type { TraceRead }

package/scripts/lane/lane-spans.ts

@@ -0,0 +1,51 @@
+// The spans an issue's starts open and its ends close, shared by `josh lane:stats`' gaps
+// (`lane-gap-stats.ts`) and `run:board`'s in-lane time (`run-board-lane-time.ts`)
+// (joshuafolkken/kit#4463).
+
+// One instant an issue's wait can end at. `issue` is absent on a stage whose writer held none.
+interface IssueAt {
+	issue: number | undefined
+	at_ms: number
+}
+
+interface IssuePair {
+	starts: ReadonlyArray<IssueAt>
+	bounds: ReadonlyArray<IssueAt>
+	ends: ReadonlyArray<IssueAt>
+}
+
+interface Span {
+	from_ms: number
+	end_ms: number | undefined
+}
+
+// The issue's next start of any kind closes the window: an end after it belongs to that later start,
+// so a start never ended stays not ended rather than borrowing a later run's end.
+function next_start_ms(
+	starts: ReadonlyArray<IssueAt>,
+	issue: number | undefined,
+	from_ms: number,
+): number {
+	const later = starts.filter((other) => other.issue === issue && other.at_ms > from_ms)
+
+	return Math.min(...later.map((other) => other.at_ms))
+}
+
+// Each start until the first end of its own issue, before that issue's next start in `bounds`.
+function issue_spans(pair: IssuePair): Array<Span> {
+	return pair.starts.map((start) => {
+		const until_ms = next_start_ms(pair.bounds, start.issue, start.at_ms)
+
+		return {
+			from_ms: start.at_ms,
+			end_ms: pair.ends.find(
+				(end) => end.issue === start.issue && end.at_ms >= start.at_ms && end.at_ms < until_ms,
+			)?.at_ms,
+		}
+	})
+}
+
+const lane_spans = { issue_spans }
+
+export { lane_spans }
+export type { IssueAt, IssuePair, Span }

package/scripts/lane/lane-spent.ts

@@ -89,8 +89,11 @@ const LIVE_PROBES: SpentProbes = {
 	unpushed_commits: read_unpushed_commits,
 }
 
+// The one probe the in-use readings take, so a reader holding a process snapshot passes its own.
+type TraceProbes = Pick<SpentProbes, 'process_trace'>
+
 // A stranded lane has no work tree for a child to be in, so it is never in use.
-function trace_of(lane: LaneInfo, probes: SpentProbes): ProcessTrace {
+function trace_of(lane: LaneInfo, probes: TraceProbes): ProcessTrace {
 	return lane.is_stranded ? PROCESS_NONE : probes.process_trace(lane.issue)
 }
 
@@ -178,7 +181,7 @@ function issues_traced(traced: ReadonlyArray<TracedLane>, trace: ProcessTrace):
 	return traced.filter(([, answer]) => answer === trace).map(([issue]) => issue)
 }
 
-function traced_of(lanes: ReadonlyArray<LaneInfo>, probes: SpentProbes): Array<TracedLane> {
+function traced_of(lanes: ReadonlyArray<LaneInfo>, probes: TraceProbes): Array<TracedLane> {
 	return lanes.map((lane): TracedLane => [lane.issue, trace_of(lane, probes)])
 }
 
@@ -195,12 +198,12 @@ async function lanes_in_use(probes: SpentProbes = LIVE_PROBES): Promise<LaneUse>
 /** The lanes no child is working in, read as such — never one whose probe did not answer. */
 function idle_lanes(
 	lanes: ReadonlyArray<LaneInfo>,
-	probes: SpentProbes = LIVE_PROBES,
+	probes: TraceProbes = LIVE_PROBES,
 ): Array<string> {
 	return issues_traced(traced_of(lanes, probes), PROCESS_NONE)
 }
 
-const lane_spent = { idle_lanes, kept_reason, lanes_in_use, sort_lanes }
+const lane_spent = { idle_lanes, kept_reason, lanes_in_use, read_unpushed_commits, sort_lanes }
 
 export type { KeptLane, LaneUse, SpentProbes, SpentSort }
 export { lane_spent }

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

@@ -0,0 +1,28 @@
+import { split_resolution } from '#scripts/split/split-resolution'
+import type { LedgerEntry } from './lane-ledger'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// Whether the split notice works: the lanes the notice reached in one period, and how many of them
+// filed a split child, printed by `josh lane:stats` so the notice's effect is read off the ledger
+// rather than searched for in lane transcripts (joshuafolkken/kit#4695). A split child counts
+// whenever it was filed, since a lane may carve the rest out before the notice reaches it.
+
+const COLUMNS = ['noticed lanes', 'split'] as const
+
+// The period's table: `entries` is the whole ledger; the notices are filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const in_period = split_resolution.notices(lane_stats.in_window(entries, window))
+	const noticed = new Set(in_period.map((entry) => entry.issue))
+	const split = split_resolution.split_issues(entries)
+	const split_count = [...noticed].filter((issue) => split.has(issue)).length
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		lane_stats.to_row([String(noticed.size), String(split_count)]),
+	].join('\n')
+}
+
+const lane_split_stats = { table }
+
+export { lane_split_stats }

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

@@ -1,5 +1,12 @@
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
-import { lane_ledger, type DispatchEntry, type LedgerEntry, type StageEntry } from './lane-ledger'
+import {
+	lane_ledger,
+	type DispatchEntry,
+	type LedgerEntry,
+	type MergeEntry,
+	type StageEntry,
+} from './lane-ledger'
 import { lane_stats, type StatsWindow } from './lane-stats'
 
 // Where a lane's time goes: the ledger's `stage` and `dispatch` entries of one period reduced to one
@@ -14,9 +21,10 @@ import { lane_stats, type StatsWindow } from './lane-stats'
 // dispatched, and a ship resumed after a fix cannot record the implementation twice.
 //
 // **`ci-wait` is `followup`'s own lap, inside the `followup` stage** — a row of its own so the wait for
-// CI reads beside `review`, the round-one review it would overlap.
+// CI reads beside `review`, the round-one review it would overlap. `coderabbit-wait` and
+// `coderabbit-rate-limit` follow it: how much of `followup`'s waiting CodeRabbit was still running or
+// rate-limited, a row recorded only by a run that saw it.
 
-const MS_PER_MINUTE = 60_000
 const DECIMALS = 1
 const NOT_MEASURED = 'not measured'
 const IMPLEMENT = 'implement'
@@ -25,6 +33,7 @@ const { STAGE } = run_ship_stage
 const STAGES = [
 	IMPLEMENT,
 	STAGE.PREFLIGHT,
+	lane_ledger.PRE_DETACH_STAGE,
 	STAGE.REVIEW,
 	STAGE.SYNC,
 	STAGE.GATE,
@@ -32,6 +41,9 @@ const STAGES = [
 	STAGE.ROUND_TWO,
 	STAGE.FOLLOWUP,
 	lane_ledger.CI_WAIT_STAGE,
+	lane_ledger.CODERABBIT_WAIT_STAGE,
+	lane_ledger.CODERABBIT_RATE_LIMIT_STAGE,
+	lane_ledger.CODERABBIT_RETRIGGER_STAGE,
 	STAGE.REPORT,
 ] as const
 
@@ -48,6 +60,10 @@ function is_dispatch(entry: LedgerEntry): entry is DispatchEntry {
 	return entry.kind === lane_ledger.KIND.DISPATCH
 }
 
+function is_merge(entry: LedgerEntry): entry is MergeEntry {
+	return entry.kind === lane_ledger.KIND.MERGE
+}
+
 function is_number(value: number | undefined): value is number {
 	return value !== undefined
 }
@@ -149,6 +165,7 @@ const lane_stage_stats = {
 	STAGES,
 	cell,
 	is_dispatch,
+	is_merge,
 	is_number,
 	is_stage,
 	medians,