@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/lane/{openai-review-broker.ts → lane-session-broker.ts}

@@ -3,15 +3,27 @@ import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from '
 import path from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_argv } from '#scripts/agent/agent-argv'
-import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { agent_role_profile, type AgentProvider } from '#scripts/agent/agent-role-profile'
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { error_text } from '#scripts/lib/error-message'
 import { json_value } from '#scripts/lib/json-value'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review } from '#scripts/run/ship/run-ship-review'
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
 import { z } from 'zod'
+import { lane_child_invocation, type ShipStop } from './lane-child-invocation'
+import { lane_child_marker } from './lane-child-marker'
 import type { LaneInfo } from './lane-registry'
+import { lane_relaunch } from './lane-relaunch'
+
+// The sessions a lane child's detached `josh ship` cannot start itself, started for it by a process
+// that can: the round-1 and round-2 reviewer, and the fresh child a stopped ship hands back to. An
+// OpenAI lane's own supervisor serves it, because a nested Codex cannot write outside its sandbox; a
+// Claude lane is served by the `run:wake` supervisor (`claude-lane-broker.ts`), because Claude Code removes its
+// token from what its Bash tool starts, so a token-only credential never reaches the ship the child
+// launched (joshuafolkken/kit#3817). **The request names an action, never a command**: the server
+// rebuilds the argv from the registered lane, so a child can ask for nothing but these two sessions.
 
 const REQUEST_PREFIX = '.josh-review-request-'
 const RESPONSE_PREFIX = '.josh-review-response-'
@@ -25,8 +37,22 @@ const HEARTBEAT_LIMIT_MS = 3000
 const MINUTE_MS = 60_000
 const REQUEST_LIMIT_MINUTES = 30
 const REQUEST_LIMIT_MS = REQUEST_LIMIT_MINUTES * MINUTE_MS
+const ANTHROPIC_PROVIDER: AgentProvider = 'anthropic'
+const stop_schema = z
+	.object({
+		stage: z.enum(run_ship_stage.STAGE),
+		title: z.string(),
+		flags: z.array(z.string()).readonly(),
+		is_review: z.boolean(),
+		conflicts: z.array(z.string()).readonly().default([]),
+	})
+	.strict()
+const action_schema = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('review'), round: z.enum(['1', '2']) }).strict(),
+	z.object({ kind: z.literal('relaunch'), stop: stop_schema }).strict(),
+])
 const request_schema = z
-	.object({ session: z.uuid(), nonce: z.uuid(), round: z.enum(['1', '2']) })
+	.object({ session: z.uuid(), nonce: z.uuid(), action: action_schema })
 	.strict()
 const response_schema = z
 	.object({
@@ -36,9 +62,10 @@ const response_schema = z
 		heartbeat_at: z.number().int().positive(),
 	})
 	.strict()
-type ReviewRequest = z.infer<typeof request_schema>
-type ReviewResponse = z.infer<typeof response_schema>
-type ReviewRound = ReviewRequest['round']
+type BrokerRequest = z.infer<typeof request_schema>
+type BrokerResponse = z.infer<typeof response_schema>
+type ReviewRound = Extract<z.infer<typeof action_schema>, { kind: 'review' }>['round']
+type BrokerAction = { kind: 'review'; round: ReviewRound } | { kind: 'relaunch'; stop: ShipStop }
 
 function review_paths(directory: string): { brief: string; findings: string; log: string } {
 	return {
@@ -67,6 +94,16 @@ function read_record<T>(target: string, schema: z.ZodType<T>): T | undefined {
 	}
 }
 
+// The reviewer runs on the lane's own provider, so a Claude lane's server never starts a Codex reviewer
+// and an OpenAI lane's never starts a Claude one.
+function provider_of(lane: LaneInfo): AgentProvider {
+	return lane.profile?.provider ?? ANTHROPIC_PROVIDER
+}
+
+// **The reviewer carries the lane's mark explicitly**: the supervisor serving a Claude lane is no lane child,
+// so a reviewer inheriting its environment would descend from the carry record's owner unmarked and be
+// read as the `backlogrun` parent by every hook.
+
 async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
 	const target = review_paths(lane.directory)
 	const prompt_of =
@@ -76,7 +113,7 @@ async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolea
 		agent_role_profile.REVIEWER,
 		lane.directory,
 	)
-	if (built.kind === 'rejected' || built.profile.provider !== 'openai') return false
+	if (built.kind === 'rejected' || built.profile.provider !== provider_of(lane)) return false
 
 	const result = await detached_launch.launch_attached(
 		{
@@ -84,6 +121,7 @@ async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolea
 			cwd: lane.directory,
 			log_path: target.log,
 			profile: built.profile,
+			env: lane_child_marker.env_for(lane.issue),
 		},
 		console.error,
 	)
@@ -91,18 +129,35 @@ async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolea
 	return result.kind === 'completed' && result.exit_code === 0
 }
 
-function write_response(target: string, body: z.infer<typeof response_schema>): void {
+// An OpenAI lane's successor is its supervisor's to start, never a relaunch's.
+function relaunch(lane: LaneInfo, stop: ShipStop): boolean {
+	if (lane_relaunch.is_openai_lane(lane)) return false
+
+	const invocation = lane_child_invocation.ship_stop_invocation(lane.issue, stop)
+	const phase = agent_role_profile.IMPLEMENTATION_PHASE
+	const result = lane_relaunch.relaunch(lane, invocation, phase, console.error)
+
+	return result.kind === 'launched'
+}
+
+async function perform(lane: LaneInfo, action: BrokerAction): Promise<boolean> {
+	if (action.kind === 'relaunch') return relaunch(lane, action.stop)
+
+	return await launch_review(lane, action.round)
+}
+
+function write_response(target: string, body: BrokerResponse): void {
 	const temporary = `${target}.${String(process.pid)}.tmp`
 
 	writeFileSync(temporary, JSON.stringify(body))
 	renameSync(temporary, target)
 }
 
-async function launched(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
+async function launched(lane: LaneInfo, action: BrokerAction): Promise<boolean> {
 	try {
-		return await launch_review(lane, round)
+		return await perform(lane, action)
 	} catch (error) {
-		error_text.trace_swallowed('openai_review_broker.launched', error)
+		error_text.trace_swallowed('lane_session_broker.launched', error)
 
 		return false
 	}
@@ -111,10 +166,10 @@ async function launched(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
 async function process_request(
 	lane: LaneInfo,
 	response: string,
-	received: ReviewRequest,
-	state: { current: ReviewResponse },
+	received: BrokerRequest,
+	state: { current: BrokerResponse },
 ): Promise<void> {
-	const is_success = await launched(lane, received.round)
+	const is_success = await launched(lane, received.action)
 
 	state.current = {
 		session: received.session,
@@ -129,7 +184,7 @@ async function serve(
 	lane: LaneInfo,
 	session: string,
 	response: string,
-	state: { is_running: boolean; current: ReviewResponse },
+	state: { is_running: boolean; current: BrokerResponse },
 ): Promise<void> {
 	let last_nonce = ''
 	const target = request_path(lane.directory, lane.issue)
@@ -148,7 +203,7 @@ async function serve(
 	}
 }
 
-function prepare(lane: LaneInfo): { response: string; current: ReviewResponse } {
+function prepare(lane: LaneInfo): { response: string; current: BrokerResponse } {
 	const response = response_path(lane.directory, lane.issue)
 	if (response === undefined) throw new Error('review broker has no trusted response location')
 
@@ -156,7 +211,7 @@ function prepare(lane: LaneInfo): { response: string; current: ReviewResponse }
 
 	mkdirSync(path.dirname(response), { recursive: true })
 	mkdirSync(path.dirname(request_path(lane.directory, lane.issue)), { recursive: true })
-	const current: ReviewResponse = {
+	const current: BrokerResponse = {
 		session,
 		nonce: '',
 		is_success: false,
@@ -168,7 +223,7 @@ function prepare(lane: LaneInfo): { response: string; current: ReviewResponse }
 	return { response, current }
 }
 
-function start_heartbeat(state: { current: ReviewResponse }, response: string): NodeJS.Timeout {
+function start_heartbeat(state: { current: BrokerResponse }, response: string): NodeJS.Timeout {
 	const heartbeat = setInterval(() => {
 		state.current = { ...state.current, heartbeat_at: Date.now() }
 		write_response(response, state.current)
@@ -179,15 +234,17 @@ function start_heartbeat(state: { current: ReviewResponse }, response: string):
 	return heartbeat
 }
 
+// **The heartbeat outlives the request being served.** A ship waiting on a reviewer reads a stale
+// heartbeat as a dead server, so stopping it first would fail a review the server is still running.
 async function stop_server(
 	state: { is_running: boolean },
 	heartbeat: NodeJS.Timeout,
 	serving: Promise<void>,
 	response: string,
 ): Promise<void> {
-	clearInterval(heartbeat)
 	state.is_running = false
 	await serving
+	clearInterval(heartbeat)
 	unlinkSync(response)
 }
 
@@ -205,9 +262,9 @@ async function with_server<T>(lane: LaneInfo, run: () => Promise<T>): Promise<T>
 }
 
 function is_live_response(
-	response: ReviewResponse | undefined,
+	response: BrokerResponse | undefined,
 	session: string,
-): response is ReviewResponse {
+): response is BrokerResponse {
 	const now = Date.now()
 
 	return (
@@ -218,7 +275,7 @@ function is_live_response(
 }
 
 function response_verdict(
-	response: ReviewResponse | undefined,
+	response: BrokerResponse | undefined,
 	session: string,
 	nonce: string,
 ): 'wait' | 'success' | 'failure' {
@@ -242,21 +299,42 @@ async function wait_response(target: string, session: string, nonce: string): Pr
 	return false
 }
 
-async function request(directory: string, issue: string, round: ReviewRound): Promise<boolean> {
-	const target = response_path(directory, issue)
-	if (target === undefined) return false
+function live_response(target: string): BrokerResponse | undefined {
 	const response = read_record(target, response_schema)
 
-	if (response === undefined || !is_live_response(response, response.session)) return false
+	return is_live_response(response, response?.session ?? '') ? response : undefined
+}
+
+// Whether a server answers for this lane now — what a Claude lane's ship asks before it hands a session
+// over rather than starting the session itself.
+function is_serving(directory: string, issue: string): boolean {
+	const target = response_path(directory, issue)
+
+	return target !== undefined && live_response(target) !== undefined
+}
+
+async function request(directory: string, issue: string, action: BrokerAction): Promise<boolean> {
+	const target = response_path(directory, issue)
+	const response = target === undefined ? undefined : live_response(target)
+
+	if (target === undefined || response === undefined) return false
 
 	const nonce = randomUUID()
-	const body: ReviewRequest = { session: response.session, nonce, round }
+	const body = { session: response.session, nonce, action }
 
 	stamp_file.replace_stamp(request_path(directory, issue), body)
 
 	return await wait_response(target, response.session, nonce)
 }
 
-const openai_review_broker = { request, request_path, response_path, review_paths, with_server }
+const lane_session_broker = {
+	is_serving,
+	request,
+	request_path,
+	response_path,
+	review_paths,
+	with_server,
+}
 
-export { openai_review_broker }
+export type { BrokerAction, ReviewRound }
+export { lane_session_broker }

package/scripts/lane/lane-spent.ts

@@ -0,0 +1,195 @@
+import { backlog_drive_restore } from '#scripts/backlog/backlog-drive-restore'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_command } from '#scripts/git/git-command'
+import { issue_state } from '#scripts/issue/issue-state'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import {
+	PROCESS_ALIVE,
+	PROCESS_NONE,
+	PROCESS_UNKNOWN,
+	type ProcessTrace,
+} from '#scripts/run/run-liveness'
+import { lane_await } from './lane-await'
+import { lane_registry, type LaneInfo } from './lane-registry'
+
+// Whether a lane is in use, and whether it is spent — the one reading `lane:prune` discards a lane
+// on and `josh backlogrun` keeps a watching run on.
+//
+// **In use means a child is working in it, or nobody could tell.** A lane a past run left behind has
+// no process, and counting it as open kept a watching run from being replaced for as long as the lane
+// sat there. An unanswered probe is in use: both callers act on "nobody is here", and the lane a
+// wrong answer costs is one with a child mid-change.
+//
+// **Spent is all five: no child, the issue closed, not in flight, a clean tree, no commit off every
+// remote.** `lane:close` forces the removal, so each condition names something a close cannot give
+// back — and a condition that could not be read keeps the lane, with the reason said.
+//
+// **A lane the running `backlogrun` still has in flight is its `run:merge`'s.** A child that merged
+// while no driver watched leaves a lane that reads spent on every other count; closed here, the run
+// would have no `merge` event, no ledger line and no merged count for it (`run-tidy-lanes.ts`).
+
+const STATE_FIELD = 'state'
+const CLOSED_STATE = 'CLOSED'
+
+interface SpentProbes {
+	process_trace: (issue: string) => ProcessTrace
+	issue_state: (issue: string) => Promise<string | undefined>
+	// The issues the running `backlogrun` launched and has not settled.
+	in_flight: () => Promise<ReadonlySet<string>>
+	is_tree_dirty: (directory: string) => Promise<boolean>
+	unpushed_commits: (branch: string) => Promise<number | undefined>
+}
+
+interface KeptLane {
+	issue: string
+	reason: string
+}
+
+// The lanes that are in use, apart: a probe that did not answer is not a child seen working.
+interface LaneUse {
+	working: Array<string>
+	unread: Array<string>
+}
+
+// One probe answer per lane: a second sample can disagree with the first, and a lane bucketed on
+// two answers can land in neither list.
+type TracedLane = readonly [issue: string, trace: ProcessTrace]
+
+interface SpentSort {
+	spent: Array<LaneInfo>
+	kept: Array<KeptLane>
+}
+
+type Check = (lane: LaneInfo, probes: SpentProbes) => Promise<string | undefined>
+
+async function read_issue_state(issue: string): Promise<string | undefined> {
+	const json = await git_gh_issue_read.issue_view_json(issue, STATE_FIELD)
+
+	return json === undefined ? undefined : issue_state.parse_issue_state(json)?.state
+}
+
+async function read_unpushed_commits(branch: string): Promise<number | undefined> {
+	try {
+		return await git_command.commit_count_unpushed(branch)
+	} catch {
+		return undefined
+	}
+}
+
+async function read_in_flight(): Promise<ReadonlySet<string>> {
+	return backlog_drive_restore.active_issues(await run_event_stream_emit.current_events())
+}
+
+const LIVE_PROBES: SpentProbes = {
+	process_trace: lane_await.process_trace_default,
+	issue_state: read_issue_state,
+	in_flight: read_in_flight,
+	is_tree_dirty: run_hold.is_tree_dirty,
+	unpushed_commits: read_unpushed_commits,
+}
+
+// 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 {
+	return lane.is_stranded ? PROCESS_NONE : probes.process_trace(lane.issue)
+}
+
+async function child_reason(lane: LaneInfo, probes: SpentProbes): Promise<string | undefined> {
+	const trace = probes.process_trace(lane.issue)
+
+	if (trace === PROCESS_NONE) return undefined
+
+	return trace === PROCESS_ALIVE
+		? 'a child is still working in it'
+		: 'whether a child is working in it could not be read'
+}
+
+async function issue_reason(lane: LaneInfo, probes: SpentProbes): Promise<string | undefined> {
+	const state = await probes.issue_state(lane.issue)
+
+	if (state === CLOSED_STATE) return undefined
+
+	return state === undefined ? 'its issue could not be read' : 'its issue is still open'
+}
+
+async function run_reason(lane: LaneInfo, probes: SpentProbes): Promise<string | undefined> {
+	const in_flight = await probes.in_flight()
+
+	return in_flight.has(lane.issue)
+		? 'the running backlogrun has not collected it yet (`pnpm josh run:merge` does)'
+		: undefined
+}
+
+// `is_tree_dirty` answers dirty for a status it could not read, which is the side that keeps the lane.
+async function tree_reason(lane: LaneInfo, probes: SpentProbes): Promise<string | undefined> {
+	return (await probes.is_tree_dirty(lane.directory)) ? 'it has uncommitted changes' : undefined
+}
+
+async function commit_reason(lane: LaneInfo, probes: SpentProbes): Promise<string | undefined> {
+	const count = await probes.unpushed_commits(lane.branch)
+
+	if (count === 0) return undefined
+
+	return count === undefined
+		? 'its commits could not be counted'
+		: `it has ${String(count)} commit(s) that are on no remote`
+}
+
+// In the order a person acts on them: a running child outranks everything, and an open issue is why
+// the lane exists at all.
+const CHECKS: ReadonlyArray<Check> = [
+	child_reason,
+	issue_reason,
+	run_reason,
+	tree_reason,
+	commit_reason,
+]
+
+// Why the lane is kept, or `undefined` for a spent one.
+async function kept_reason(
+	lane: LaneInfo,
+	probes: SpentProbes = LIVE_PROBES,
+): Promise<string | undefined> {
+	const reasons = await Promise.all(CHECKS.map(async (check) => await check(lane, probes)))
+
+	return reasons.find((reason) => reason !== undefined)
+}
+
+// Every live lane as spent or kept. A stranded lane is neither: `lane:prune` closes it already.
+async function sort_lanes(
+	lanes: ReadonlyArray<LaneInfo>,
+	probes: SpentProbes = LIVE_PROBES,
+): Promise<SpentSort> {
+	const live = lanes.filter((lane) => !lane.is_stranded)
+	const reasons = await Promise.all(live.map(async (lane) => await kept_reason(lane, probes)))
+	const sorted: SpentSort = { spent: [], kept: [] }
+
+	for (const [index, lane] of live.entries()) {
+		const reason = reasons[index]
+
+		if (reason === undefined) sorted.spent.push(lane)
+		else sorted.kept.push({ issue: lane.issue, reason })
+	}
+
+	return sorted
+}
+
+function issues_traced(traced: ReadonlyArray<TracedLane>, trace: ProcessTrace): Array<string> {
+	return traced.filter(([, answer]) => answer === trace).map(([issue]) => issue)
+}
+
+/** The lanes in use — what a run being replaced must not be stopped over. */
+async function lanes_in_use(probes: SpentProbes = LIVE_PROBES): Promise<LaneUse> {
+	const lanes = await lane_registry.list_lanes()
+	const traced = lanes.map((lane): TracedLane => [lane.issue, trace_of(lane, probes)])
+
+	return {
+		working: issues_traced(traced, PROCESS_ALIVE),
+		unread: issues_traced(traced, PROCESS_UNKNOWN),
+	}
+}
+
+const lane_spent = { kept_reason, lanes_in_use, sort_lanes }
+
+export type { KeptLane, LaneUse, SpentProbes, SpentSort }
+export { lane_spent }

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

@@ -112,11 +112,15 @@ function stage_row(stage: string, measured: Measured): string {
 	])
 }
 
+function measured_of(entries: ReadonlyArray<LedgerEntry>): Measured {
+	const stages = entries.filter(is_stage)
+
+	return { implement: implement_durations(entries.filter(is_dispatch), stages), stages }
+}
+
 // The period's table: `entries` is the whole ledger, filtered here to `window`.
 function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
-	const period = lane_stats.in_window(entries, window)
-	const stages = period.filter(is_stage)
-	const measured = { implement: implement_durations(period.filter(is_dispatch), stages), stages }
+	const measured = measured_of(lane_stats.in_window(entries, window))
 
 	return [
 		lane_stats.to_row(COLUMNS),
@@ -125,10 +129,30 @@ function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string
 	].join('\n')
 }
 
+// Each stage's median over every entry given, a stage nothing recorded left out rather than read as
+// `0` — how long a stage usually takes, which `run:board` measures a running child's phase against.
+function medians(entries: ReadonlyArray<LedgerEntry>): ReadonlyMap<string, number> {
+	const measured = measured_of(entries)
+
+	return new Map(
+		STAGES.flatMap((stage) => {
+			const median = lane_stats.median(durations_of(stage, measured))
+
+			return median === undefined ? [] : [[stage, median] as const]
+		}),
+	)
+}
+
 const lane_stage_stats = {
 	IMPLEMENT,
 	NOT_MEASURED,
 	STAGES,
+	cell,
+	is_dispatch,
+	is_number,
+	is_stage,
+	medians,
+	started_ms,
 	table,
 }
 

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

@@ -0,0 +1,96 @@
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { lane_ledger, type LedgerEntry, type StopEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// How long a lane stood stopped: the ledger's `stop` entries of one period reduced to one row per stop
+// reason — median, maximum, how many stops were resumed and how many never were — printed by
+// `josh lane:stats` under the per-stage table, so the stop reason worth removing next is a number.
+//
+// **The wait is derived, not recorded**: from a stop to the start of the same issue's next ship stage,
+// the way `implement` is. A stop that no ship stage followed — the lane parked, or left stopped — is
+// counted under `not resumed` and kept out of the median and the maximum, whose time has no end.
+//
+// **A re-dispatch of the issue ends the search**: the new child's ship is a fresh lane's work, not the
+// resumption of a stop that may be days old.
+
+const COLUMNS = ['stop', 'median (min)', 'max (min)', 'runs', 'not resumed'] as const
+const { STAGE } = run_ship_stage
+const { is_dispatch, is_number, is_stage } = lane_stage_stats
+const REASONS = [
+	STAGE.PREFLIGHT,
+	STAGE.REVIEW,
+	STAGE.SYNC,
+	run_ship_stage.CONFLICT,
+	STAGE.GATE,
+	STAGE.COMMIT,
+	STAGE.ROUND_TWO,
+	STAGE.FOLLOWUP,
+	STAGE.REPORT,
+] as const
+
+interface StopWait {
+	reason: string
+	wait_ms: number | undefined
+}
+
+function is_stop(entry: LedgerEntry): entry is StopEntry {
+	return entry.kind === lane_ledger.KIND.STOP
+}
+
+function redispatch_ms(stop: StopEntry, entries: ReadonlyArray<LedgerEntry>): number {
+	const from_ms = Date.parse(stop.at)
+	const later = entries
+		.filter((entry) => is_dispatch(entry))
+		.filter((entry) => entry.issue === stop.issue)
+		.map((entry) => Date.parse(entry.at))
+		.filter((at) => at > from_ms)
+
+	return later.length === 0 ? Infinity : Math.min(...later)
+}
+
+function wait_ms(stop: StopEntry, entries: ReadonlyArray<LedgerEntry>): number | undefined {
+	const from_ms = Date.parse(stop.at)
+	const until_ms = redispatch_ms(stop, entries)
+	const starts = entries
+		.filter((entry) => is_stage(entry))
+		.filter((stage) => stage.issue === stop.issue)
+		.map((stage) => lane_stage_stats.started_ms(stage))
+		.filter((start) => start >= from_ms && start < until_ms)
+
+	return starts.length === 0 ? undefined : Math.min(...starts) - from_ms
+}
+
+function waits_of(entries: ReadonlyArray<LedgerEntry>): Array<StopWait> {
+	return entries
+		.filter(is_stop)
+		.map((stop) => ({ reason: stop.reason, wait_ms: wait_ms(stop, entries) }))
+}
+
+function reason_row(reason: string, waits: ReadonlyArray<StopWait>): string {
+	const of_reason = waits.filter((wait) => wait.reason === reason)
+	const resumed = of_reason.map((wait) => wait.wait_ms).filter((value) => is_number(value))
+
+	return lane_stats.to_row([
+		reason,
+		lane_stage_stats.cell(lane_stats.median(resumed)),
+		lane_stage_stats.cell(lane_stats.peak(resumed)),
+		String(resumed.length),
+		String(of_reason.length - resumed.length),
+	])
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const waits = waits_of(lane_stats.in_window(entries, window))
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...REASONS.map((reason) => reason_row(reason, waits)),
+	].join('\n')
+}
+
+const lane_stop_stats = { REASONS, table }
+
+export { lane_stop_stats }

package/scripts/lane/openai-lane-supervisor.ts

@@ -9,10 +9,10 @@ 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 type { LaneInfo } from './lane-registry'
+import { lane_session_broker } from './lane-session-broker'
 import { openai_lane_ship } from './openai-lane-ship'
 import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
 import { openai_lane_supervisor_owner, type SupervisorOwner } from './openai-lane-supervisor-owner'
-import { openai_review_broker } from './openai-review-broker'
 
 const { claim, read_state, release, update } = openai_lane_supervisor_owner
 const CHILD_POLL_MS = 250
@@ -178,7 +178,7 @@ async function supervise(lane: LaneInfo, profile: AgentProfile, nonce: string):
 	try {
 		if (!(await openai_lane_supervisor_decision.is_approved(lane.directory, nonce))) return 0
 
-		return await openai_review_broker.with_server(
+		return await lane_session_broker.with_server(
 			lane,
 			async () => await run_claimed(lane, profile, owner),
 		)

package/scripts/lane/process-tools.ts

@@ -0,0 +1,31 @@
+import path from 'node:path'
+
+// One definition of "the process tools a lane reads are not installed".
+//
+// **`ps` and `pgrep` are a prerequisite, not an optional probe.** The owner check walks the caller's
+// ancestry with `ps`, and lane liveness and reaping match children with `pgrep`. A machine without
+// them (a slim Debian image ships no `procps`) used to read every probe as "nothing there": the
+// ancestry stopped at the caller, `run:step` answered `unknown`, and the parent stopped before its
+// first lane with no word of why. A missing tool is refused by name instead.
+
+// What Node reports when the executable to spawn does not exist.
+const NOT_FOUND_CODE = 'ENOENT'
+const PACKAGE_HINT =
+	'install the package that provides it (procps on Debian/Ubuntu: `apt-get install procps`)'
+
+function is_not_found(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === NOT_FOUND_CODE
+}
+
+function missing_notice(command: string): string {
+	return `\`${path.basename(command)}\` is not installed — kit's lane commands read processes with ps and pgrep; ${PACKAGE_HINT}`
+}
+
+/** Throw a named refusal when `error` says `command` could not be spawned because it does not exist. */
+function throw_if_missing(command: string, error: unknown): void {
+	if (is_not_found(error)) throw new Error(missing_notice(command), { cause: error })
+}
+
+const process_tools = { missing_notice, throw_if_missing }
+
+export { process_tools }