@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lane/lane-round-two-stats.ts

@@ -0,0 +1,49 @@
+import { lane_ledger, type LedgerEntry, type RoundTwoEntry } from './lane-ledger'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// Why round 2 ran or was skipped: the ledger's `round-two` entries of one period reduced to one row per
+// verdict and reason code, printed by `josh lane:stats` so the next change — to the procedure, or to
+// what counts as an inert fix — is chosen from counts rather than impressions (joshuafolkken/kit#4064).
+
+const COLUMNS = ['round 2', 'code', 'decisions'] as const
+const KEY_SEPARATOR = ' '
+// A period with no decision: the table still prints, so a reader sees zero rather than no table.
+const NONE_ROW = ['none', 'none', '0']
+
+function is_round_two(entry: LedgerEntry): entry is RoundTwoEntry {
+	return entry.kind === lane_ledger.KIND.ROUND_TWO
+}
+
+function counts_of(decisions: ReadonlyArray<RoundTwoEntry>): Map<string, number> {
+	const counts = new Map<string, number>()
+
+	for (const decision of decisions) {
+		const key = `${decision.verdict}${KEY_SEPARATOR}${decision.code}`
+
+		counts.set(key, (counts.get(key) ?? 0) + 1)
+	}
+
+	return counts
+}
+
+// The most frequent pair first, so the reason worth acting on leads.
+function rows_of(counts: ReadonlyMap<string, number>): Array<string> {
+	return [...counts]
+		.toSorted(([, left], [, right]) => right - left)
+		.map(([key, count]) => lane_stats.to_row([...key.split(KEY_SEPARATOR), String(count)]))
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const rows = rows_of(counts_of(lane_stats.in_window(entries, window).filter(is_round_two)))
+
+	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_round_two_stats = { table }
+
+export { lane_round_two_stats }

package/scripts/lane/lane-sampler.ts

@@ -1,5 +1,7 @@
-import { lane_ledger } from './lane-ledger'
+import { lane_ledger_write } from './lane-ledger-write'
 import { lane_load } from './lane-load'
+import type { LaneSpan } from './lane-net-time'
+import { lane_sleep } from './lane-sleep'
 
 // The machine-load sampler: one `load` entry appended to the lane ledger, once or on a timer.
 //
@@ -14,13 +16,18 @@ const SAMPLE_INTERVAL_MS = 60_000
 // Where the ledger is and what "now" is, overridable so a test reads a fixed ledger at a fixed instant.
 interface MeasureContext {
 	ledger_path?: string
+	// The run's event stream `lane:stats` reads parks from and a sleep is recorded on; absent, the
+	// repository's own.
+	events_path?: string
+	// The lane transcript directories `lane:stats` reads tool calls from; absent, this repository's lanes'.
+	transcript_directories?: ReadonlyArray<string>
 	now_ms?: number
 }
 
 async function take(context: MeasureContext = {}): Promise<void> {
 	const at = new Date(context.now_ms ?? Date.now()).toISOString()
 
-	await lane_ledger.record(await lane_load.sample(at), context.ledger_path)
+	await lane_ledger_write.record(await lane_load.sample(at), context.ledger_path)
 }
 
 // A timer tick has no caller to raise into, and a sample that could not be read must never end the run
@@ -33,10 +40,26 @@ async function take_quietly(context: MeasureContext): Promise<void> {
 	}
 }
 
-/** Sample now and then every minute; the returned function stops it. */
+// A sleep that could not be recorded is a gap in the measurement, the same as an unread sample.
+async function record_quietly(span: LaneSpan, context: MeasureContext): Promise<void> {
+	try {
+		await lane_sleep.record(span, context.events_path)
+	} catch {
+		// Best-effort: an unrecorded sleep counts as lane time, never as a failure of the run.
+	}
+}
+
+/** Sample now and then every minute, recording a tick the host slept through; the returned function stops it. */
 function start(context: MeasureContext = {}): () => void {
+	let last_ms = Date.now()
+
 	void take_quietly(context)
 	const timer = setInterval(() => {
+		const now_ms = Date.now()
+		const slept = lane_sleep.gap_of(last_ms, now_ms, SAMPLE_INTERVAL_MS)
+
+		last_ms = now_ms
+		if (slept !== undefined) void record_quietly(slept, context)
 		void take_quietly(context)
 	}, SAMPLE_INTERVAL_MS).unref()
 

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

@@ -1,10 +1,16 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
 import { agent_argv } from '#scripts/agent/agent-argv'
 import { agent_role_profile, type AgentProvider } from '#scripts/agent/agent-role-profile'
+import { api_auth } from '#scripts/agent/api-auth'
+import { distributed_paths } from '#scripts/init/distributed-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { error_text } from '#scripts/lib/error-message'
+import { review_attest, type ReviewSlot } from '#scripts/review/review-attest'
 import { detached_launch, type AttachedLaunchResult } 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 { run_ship_stop_cause } from '#scripts/run/ship/run-ship-stop-cause'
 import { run_ship_stop_context } from '#scripts/run/ship/run-ship-stop-context'
 import { z } from 'zod'
 import { lane_child_invocation, type ShipStop } from './lane-child-invocation'
@@ -14,13 +20,14 @@ import type { LaneInfo } from './lane-registry'
 import { lane_relaunch } from './lane-relaunch'
 
 // The actions a lane's session broker performs for the ship that asked (`lane-session-broker.ts`):
-// starting the round-1 or round-2 reviewer, or relaunching the lane's child after a stopped ship.
+// starting the round-1 reviewers or the round-2 reviewer, or relaunching the lane's child after a stopped ship.
 // **A failure names its reason**: a bare `false` left every relaunch a stale supervisor refused
 // unexplained in the ship log (joshuafolkken/kit#3974).
 
 const BRIEF_PREFIX = 'josh-ship-review-brief-'
 const FINDINGS_PREFIX = 'josh-ship-review-findings-'
 const LOG_PREFIX = 'josh-ship-review-log-'
+const SUBMIT_SCRIPT = 'scripts/review/review-submit-cli.ts'
 const ANTHROPIC_PROVIDER: AgentProvider = 'anthropic'
 const stop_schema = z
 	.object({
@@ -28,16 +35,45 @@ const stop_schema = z
 		title: z.string(),
 		flags: z.array(z.string()).readonly(),
 		is_review: z.boolean(),
+		unpinned_ok: z.array(z.string()).readonly().exactOptional(),
 		conflicts: z.array(z.string()).readonly().default([]),
+		cause: z.enum(run_ship_stop_cause.CAUSE).exactOptional(),
+		is_review_stale: z.boolean().exactOptional(),
 		context: run_ship_stop_context.stop_context_schema.exactOptional(),
 	})
 	.strict()
+// `slots` is omitted for `/code-review` alone, so a supervisor still on the code before it reads the
+// request as before; it names the reviews a ship runs side by side (joshuafolkken/kit#4672).
+const slots_schema = z.array(z.enum(review_attest.REVIEW_SLOTS)).readonly()
 const action_schema = z.discriminatedUnion('kind', [
-	z.object({ kind: z.literal('review'), round: z.enum(['1', '2']) }).strict(),
+	z
+		.object({
+			kind: z.literal('review'),
+			round: z.enum(['1', '2']),
+			slots: slots_schema.exactOptional(),
+		})
+		.strict(),
 	z.object({ kind: z.literal('relaunch'), stop: stop_schema }).strict(),
 ])
+const request_schema = z
+	.object({ session: z.uuid(), nonce: z.uuid(), action: action_schema })
+	.strict()
 type ReviewRound = Extract<z.infer<typeof action_schema>, { kind: 'review' }>['round']
-type BrokerAction = { kind: 'review'; round: ReviewRound } | { kind: 'relaunch'; stop: ShipStop }
+
+interface ReviewAction {
+	kind: 'review'
+	round: ReviewRound
+	slots?: ReadonlyArray<ReviewSlot>
+}
+
+type BrokerAction = ReviewAction | { kind: 'relaunch'; stop: ShipStop }
+
+interface ReviewPaths {
+	brief: string
+	findings: string
+	log: string
+}
+
 type BrokerAnswer = { is_success: true } | { is_success: false; reason: string }
 
 const SUCCESS: BrokerAnswer = { is_success: true }
@@ -46,11 +82,18 @@ function failure(reason: string): BrokerAnswer {
 	return { is_success: false, reason }
 }
 
-function review_paths(directory: string): { brief: string; findings: string; log: string } {
+// **Each review slot has its own files**: `/code-review` and the interaction review run side by side
+// (joshuafolkken/kit#4672), so neither overwrites the other's brief, findings or log.
+function review_paths(
+	directory: string,
+	slot: ReviewSlot = review_attest.REVIEW_SLOT.CODE,
+): ReviewPaths {
+	const prefix = slot === review_attest.REVIEW_SLOT.CODE ? '' : 'interaction-'
+
 	return {
-		brief: stamp_file.stamp_path(BRIEF_PREFIX, directory, '.md'),
-		findings: stamp_file.stamp_path(FINDINGS_PREFIX, directory, '.txt'),
-		log: stamp_file.stamp_path(LOG_PREFIX, directory, '.log'),
+		brief: stamp_file.stamp_path(`${BRIEF_PREFIX}${prefix}`, directory, '.md'),
+		findings: stamp_file.stamp_path(`${FINDINGS_PREFIX}${prefix}`, directory, '.txt'),
+		log: stamp_file.stamp_path(`${LOG_PREFIX}${prefix}`, directory, '.log'),
 	}
 }
 
@@ -65,33 +108,62 @@ function provider_of(lane: LaneInfo): AgentProvider {
 // read as the `backlogrun` parent by every hook. **Its prompt ends with the review invocation**, so the
 // lane's liveness read and the park's reap find it as they find the child (joshuafolkken/kit#3878).
 
-function review_prompt(lane: LaneInfo, round: ReviewRound): string {
-	const target = review_paths(lane.directory)
-	const prompt_of =
-		round === '1' ? run_ship_review.reviewer_prompt : run_ship_review.verification_prompt
+function action_slots(action: ReviewAction): ReadonlyArray<ReviewSlot> {
+	return action.slots ?? [review_attest.REVIEW_SLOT.CODE]
+}
+
+// **A lane branched before `review:submit` is handed its findings path** (joshuafolkken/kit#4799): the
+// reviewer runs the lane's own josh, and a supervisor reloaded onto main serves lanes that predate it.
+function has_submit(directory: string): boolean {
+	return [SUBMIT_SCRIPT, `${distributed_paths.KIT_PACKAGE_PATH_PREFIX}${SUBMIT_SCRIPT}`].some(
+		(script) => existsSync(path.join(directory, script)),
+	)
+}
+
+function review_prompt(lane: LaneInfo, action: ReviewAction, slot: ReviewSlot): string {
+	const { brief, findings } = review_paths(lane.directory, slot)
+	const round_prompt =
+		action.round === '1' ? run_ship_review.reviewer_prompt : run_ship_review.verification_prompt
+	const prompt_of = run_ship_review.slot_prompt(round_prompt, slot, action_slots(action))
 	const tail = lane_child_invocation.review_invocation(lane.issue)
+	const findings_path = has_submit(lane.directory) ? undefined : findings
+
+	return `${prompt_of(brief, slot, lane.issue, findings_path)} This is ${tail}`
+}
+
+// **A reviewer that could not authenticate names it** with `api_auth.AUTH_FAILURE_NOTE`, read off its
+// log's exit record, so the ship stop is not booked as a review finding (joshuafolkken/kit#4216).
+function exited_answer(exit_code: number | null, log_path: string): BrokerAnswer {
+	const exited = `the reviewer exited with code ${String(exit_code)}`
+
+	if (!api_auth.is_auth_failed_transcript(stamp_file.read_stamp_text(log_path))) {
+		return failure(exited)
+	}
 
-	return `${prompt_of(target.brief, target.findings, lane.issue)} This is ${tail}`
+	return failure(`${api_auth.AUTH_FAILURE_NOTE}: ${exited}`)
 }
 
-function reviewer_answer(result: AttachedLaunchResult): BrokerAnswer {
+function reviewer_answer(result: AttachedLaunchResult, log_path: string): BrokerAnswer {
 	if (result.kind === 'failed') return failure(`the reviewer could not start: ${result.note}`)
 
-	return result.exit_code === 0
-		? SUCCESS
-		: failure(`the reviewer exited with code ${String(result.exit_code)}`)
+	return result.exit_code === 0 ? SUCCESS : exited_answer(result.exit_code, log_path)
 }
 
-async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<BrokerAnswer> {
-	const target = review_paths(lane.directory)
-	const built = agent_argv.review_in(review_prompt(lane, round), Number(round), lane.directory)
+async function launch_review(
+	lane: LaneInfo,
+	action: ReviewAction,
+	slot: ReviewSlot,
+): Promise<BrokerAnswer> {
+	const target = review_paths(lane.directory, slot)
+	const prompt = review_prompt(lane, action, slot)
+	const built = agent_argv.review_in(prompt, Number(action.round), lane.directory)
 	if (built.kind === 'rejected') return failure(`the reviewer profile was rejected: ${built.note}`)
 
 	if (built.profile.provider !== provider_of(lane)) {
 		return failure(`the reviewer resolved to ${built.profile.provider}, not the lane's provider`)
 	}
 
-	console.error(agent_role_profile.describe_review(Number(round), built.profile))
+	console.error(agent_role_profile.describe_review(Number(action.round), built.profile))
 	const result = await detached_launch.launch_attached(
 		{
 			argv: built.argv,
@@ -103,7 +175,17 @@ async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<Broker
 		console.error,
 	)
 
-	return reviewer_answer(result)
+	return reviewer_answer(result, target.log)
+}
+
+// **The slots' reviewers run side by side**, and the answer is the first failure among them — each
+// slot's findings file then says which review finished (`run-ship-reviewer.ts`).
+async function launch_reviews(lane: LaneInfo, action: ReviewAction): Promise<BrokerAnswer> {
+	const answers = await Promise.all(
+		action_slots(action).map(async (slot) => await launch_review(lane, action, slot)),
+	)
+
+	return answers.find((reply) => !reply.is_success) ?? SUCCESS
 }
 
 // An OpenAI lane's successor is its supervisor's to start, never a relaunch's.
@@ -128,7 +210,7 @@ async function perform(lane: LaneInfo, action: BrokerAction): Promise<BrokerAnsw
 
 	if (action.kind === 'relaunch') return relaunch(lane, action.stop)
 
-	return await launch_review(lane, action.round)
+	return await launch_reviews(lane, action)
 }
 
 // What the server answers: a thrown action is a failure naming its error, never a dead server.
@@ -140,7 +222,14 @@ async function answer(lane: LaneInfo, action: BrokerAction): Promise<BrokerAnswe
 	}
 }
 
-const lane_session_action = { SUCCESS, action_schema, answer, failure, review_paths }
+const lane_session_action = {
+	SUCCESS,
+	action_schema,
+	answer,
+	failure,
+	request_schema,
+	review_paths,
+}
 
 export type { BrokerAction, BrokerAnswer, ReviewRound }
 export { lane_session_action }

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

@@ -1,14 +1,19 @@
 import { randomUUID } from 'node:crypto'
-import { mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, rmSync, unlinkSync } from 'node:fs'
 import path from 'node:path'
-import { setTimeout as sleep } from 'node:timers/promises'
 import { git_common_directory } from '#scripts/git/git-common-directory'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { atomic_write } from '#scripts/lib/atomic-write'
 import { json_value } from '#scripts/lib/json-value'
+import { poll } from '#scripts/lib/poll'
+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 { z } from 'zod'
 import { lane_broker_server, type BrokerServer } from './lane-broker-server'
 import type { LaneInfo } from './lane-registry'
 import { lane_session_action, type BrokerAction, type BrokerAnswer } from './lane-session-action'
+import { lane_session_reread } from './lane-session-reread'
 
 // 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
@@ -28,11 +33,30 @@ const POLL_MS = 100
 const LEGACY_HEARTBEAT_MS = 500
 const LEGACY_HEARTBEAT_LIMIT_MS = 3000
 const MINUTE_MS = 60_000
-const REQUEST_LIMIT_MINUTES = 30
-const REQUEST_LIMIT_MS = REQUEST_LIMIT_MINUTES * MINUTE_MS
-const request_schema = z
-	.object({ session: z.uuid(), nonce: z.uuid(), action: lane_session_action.action_schema })
-	.strict()
+// **A relaunch is answered once the session has started, a review once it has finished**: waiting out a
+// review's limit on a relaunch left the stopped lane idle for half an hour (joshuafolkken/kit#4344).
+const REQUEST_LIMIT_MINUTES: Readonly<Record<BrokerAction['kind'], number>> = {
+	review: 30,
+	relaunch: 2,
+}
+const { request_schema } = lane_session_action
+// **A request this broker cannot read is still answered**: the supervisor reloads on new code only at
+// its next pass boundary (`run-wake-code.ts`), so until then a lane's ship can run a newer main than
+// the broker's, and a field the ship added made the request unreadable and
+// the ship waited out the whole limit on a server that had dropped it (joshuafolkken/kit#4230).
+// **The reason names the fields the schema refused**: a guess at the supervisor's age hid a field the
+// broker's schema had never learned even on one main (joshuafolkken/kit#4489).
+const envelope_schema = z.looseObject({ session: z.uuid(), nonce: z.uuid() })
+const UNREADABLE_REASON = 'the broker could not read the request'
+// **A refused request is read as a version difference, never dropped silently** (joshuafolkken/kit#4714):
+// the refusal marks the supervisor's code as suspect, so its next pass re-hashes the code even where the
+// commit did not move or the hash at its start could not be read, and reloads when it differs. Only the
+// `run:wake` supervisor takes the mark: an OpenAI lane's own supervisor never re-checks its code.
+// **Before it is refused, the code on disk reads it** (`lane-session-reread.ts`), so a schema main widened
+// since the supervisor started is answered now rather than after the reload (joshuafolkken/kit#4732).
+const VERSION_NOTE =
+	"the broker's code differs from the ship's; a run:wake supervisor re-checks its code at its next pass"
+const refusal = { is_pending: false }
 const response_schema = z
 	.object({
 		session: z.uuid(),
@@ -44,7 +68,7 @@ const response_schema = z
 // **A failure's reason sits beside the response, never in it**: a ship branched before the reason parses
 // the response strictly, so a new field would read as no server (joshuafolkken/kit#3974).
 const reason_schema = z.object({ nonce: z.string(), reason: z.string() }).strict()
-type BrokerRequest = z.infer<typeof request_schema>
+type BrokerEnvelope = z.infer<typeof envelope_schema>
 type BrokerResponse = z.infer<typeof response_schema>
 
 const { failure } = lane_session_action
@@ -73,19 +97,72 @@ function read_record<T>(target: string, schema: z.ZodType<T>): T | undefined {
 }
 
 function write_record(target: string, body: BrokerResponse | z.infer<typeof reason_schema>): void {
-	const temporary = `${target}.${String(process.pid)}.tmp`
+	atomic_write.replace_file(target, JSON.stringify(body))
+}
+
+function refused_field(issue: z.core.$ZodIssue): ReadonlyArray<string> {
+	const at = issue.path.map(String)
+
+	if (issue.code !== 'unrecognized_keys') return [`${at.join('.')}: ${issue.message}`]
+
+	return issue.keys.map((key) => `unrecognized key: ${[...at, key].join('.')}`)
+}
+
+function unreadable(error: z.ZodError): BrokerAnswer {
+	const fields = error.issues.flatMap((issue) => refused_field(issue))
+
+	return failure(`${UNREADABLE_REASON} — ${VERSION_NOTE} — ${fields.join('; ')}`)
+}
+
+// The answer of a broker on code older than the request, which the ship can still fall back from.
+function is_unreadable(answer: BrokerAnswer): boolean {
+	return !answer.is_success && answer.reason.includes(UNREADABLE_REASON)
+}
+
+async function answer_request(lane: LaneInfo, received: BrokerEnvelope): Promise<BrokerAnswer> {
+	const parsed = request_schema.safeParse(received)
+	if (parsed.success) return await lane_session_action.answer(lane, parsed.data.action)
+
+	refusal.is_pending = true
 
-	writeFileSync(temporary, JSON.stringify(body))
-	renameSync(temporary, target)
+	return (await lane_session_reread.reread(lane.issue, received)) ?? unreadable(parsed.error)
+}
+
+// Whether a request was refused since the supervisor last asked, clearing the mark — the supervisor
+// re-checks its code on it (`run-wake-code.ts`).
+function take_refusal(): boolean {
+	const { is_pending } = refusal
+
+	refusal.is_pending = false
+
+	return is_pending
+}
+
+// The requests this process's servers are answering now — what the supervisor's reload waits out
+// (`run-wake-cli.ts`), since closing a server mid-review fails that review.
+const answering = { count: 0 }
+
+function is_answering(): boolean {
+	return answering.count > 0
+}
+
+async function answer_counted(lane: LaneInfo, received: BrokerEnvelope): Promise<BrokerAnswer> {
+	answering.count += 1
+
+	try {
+		return await answer_request(lane, received)
+	} finally {
+		answering.count -= 1
+	}
 }
 
 async function process_request(
 	lane: LaneInfo,
 	response: string,
-	received: BrokerRequest,
+	received: BrokerEnvelope,
 	state: { current: BrokerResponse },
 ): Promise<void> {
-	const answer = await lane_session_action.answer(lane, received.action)
+	const answer = await answer_counted(lane, received)
 	const { session, nonce } = received
 
 	if (!answer.is_success) write_record(reason_path(response), { nonce, reason: answer.reason })
@@ -99,21 +176,23 @@ async function serve(
 	response: string,
 	state: { is_running: boolean; current: BrokerResponse },
 ): Promise<void> {
-	let last_nonce = ''
+	const served = { nonce: '' }
 	const target = request_path(lane.directory, lane.issue)
 
-	while (state.is_running) {
-		const received = read_record(target, request_schema)
+	// Requests are served one at a time, in arrival order: a pass ends only once its request is answered.
+	async function serve_pass(): Promise<true | undefined> {
+		if (!state.is_running) return true
+		const received = read_record(target, envelope_schema)
 
-		if (received?.session === session && received.nonce !== last_nonce) {
-			last_nonce = received.nonce
-			// eslint-disable-next-line no-await-in-loop -- requests are served one at a time, in arrival order
+		if (received?.session === session && received.nonce !== served.nonce) {
+			served.nonce = received.nonce
 			await process_request(lane, response, received, state)
 		}
 
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await sleep(POLL_MS)
+		return undefined
 	}
+
+	await poll.wait_for(serve_pass, { interval_ms: POLL_MS })
 }
 
 // The server record is written before the response, so a ship that finds the response finds it too.
@@ -233,18 +312,20 @@ async function wait_response(
 	target: string,
 	session: string,
 	nonce: string,
+	kind: BrokerAction['kind'],
 ): Promise<BrokerAnswer> {
-	const deadline = Date.now() + REQUEST_LIMIT_MS
+	const limit_minutes = REQUEST_LIMIT_MINUTES[kind]
+	const deadline = Date.now() + limit_minutes * MINUTE_MS
 
-	while (Date.now() < deadline) {
-		const verdict = response_verdict(target, session, nonce)
-		if (verdict !== undefined) return verdict
+	function verdict_by_deadline(): BrokerAnswer | undefined {
+		if (Date.now() >= deadline) {
+			return failure(`the broker gave no answer within ${String(limit_minutes)} minutes`)
+		}
 
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await sleep(POLL_MS)
+		return response_verdict(target, session, nonce)
 	}
 
-	return failure(`the broker gave no answer within ${String(REQUEST_LIMIT_MINUTES)} minutes`)
+	return await poll.wait_for(verdict_by_deadline, { interval_ms: POLL_MS })
 }
 
 function live_response(target: string): BrokerResponse | undefined {
@@ -255,12 +336,18 @@ function live_response(target: string): BrokerResponse | undefined {
 		: undefined
 }
 
+// The session of the server answering for this lane now, or `undefined` while none does. A new session
+// means the server that held the lane before has ended.
+function serving_session(directory: string, issue: string): string | undefined {
+	const target = response_path(directory, issue)
+
+	return target === undefined ? undefined : live_response(target)?.session
+}
+
 // 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
+	return serving_session(directory, issue) !== undefined
 }
 
 // **A request nobody waits for any more is taken back**: a server busy with an earlier request reads the
@@ -270,11 +357,17 @@ function withdraw(pending: string, nonce: string): void {
 	if (read_record(pending, request_schema)?.nonce === nonce) stamp_file.remove_stamp(pending)
 }
 
-async function request(
-	directory: string,
-	issue: string,
-	action: BrokerAction,
-): Promise<BrokerAnswer> {
+// A failure is put on the run's stream as well as the ship's output, so a broker that cannot serve the
+// lane is seen from `run:board` rather than only from the ship log (joshuafolkken/kit#4230).
+async function record_failure(issue: string, answer: BrokerAnswer): Promise<void> {
+	if (answer.is_success) return
+
+	const text = `${issue_cite.plain(issue)} lane broker: ${answer.reason}`
+
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.NOTE, text)
+}
+
+async function send(directory: string, issue: string, action: BrokerAction): Promise<BrokerAnswer> {
 	const target = response_path(directory, issue)
 	const response = target === undefined ? undefined : live_response(target)
 
@@ -285,19 +378,35 @@ async function request(
 	const pending = request_path(directory, issue)
 
 	stamp_file.replace_stamp(pending, body)
-	const answer = await wait_response(target, response.session, nonce)
+	const answer = await wait_response(target, response.session, nonce, action.kind)
 
 	withdraw(pending, nonce)
 
 	return answer
 }
 
+async function request(
+	directory: string,
+	issue: string,
+	action: BrokerAction,
+): Promise<BrokerAnswer> {
+	const answer = await send(directory, issue, action)
+
+	await record_failure(issue, answer)
+
+	return answer
+}
+
 const lane_session_broker = {
+	is_answering,
 	is_serving,
+	is_unreadable,
 	request,
 	request_path,
 	response_path,
 	review_paths: lane_session_action.review_paths,
+	serving_session,
+	take_refusal,
 	with_server,
 }
 

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { lane_session_reread } from './lane-session-reread'
+
+// The fresh process a lane broker starts for a request its own code refused (`lane-session-reread.ts`):
+// `<issue> <request JSON>` in, the answer's JSON out, exit 1 where it read nothing.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+	const [issue = '', text = ''] = process.argv.slice(ARGV_OFFSET)
+	const answer = await lane_session_reread.answer_text(issue, text)
+
+	if (answer === undefined) process.exitCode = 1
+	else process.stdout.write(`${JSON.stringify(answer)}\n`)
+}