@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/lane/lane-withdraw-closed.ts

@@ -0,0 +1,124 @@
+import { git_command } from '#scripts/git/git-command'
+import { session_cite } from '#scripts/issue/session-cite'
+import { error_text } from '#scripts/lib/error-message'
+import { run_board_closed, type ClosedIssue } from '#scripts/run/board/run-board-closed'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_withdraw, type Withdrawer } from './lane-withdraw'
+
+// Every open lane whose issue was closed on GitHub as not planned is withdrawn through `lane:withdraw`'s
+// own path (joshuafolkken/kit#4915): its child is stopped, its work stashed and the lane closed, so the
+// lane leaves the count and no cut resumes it. Nothing else ends such a lane: the child keeps working on
+// an issue no one wants, and the lane limit counts it while the board draws no lane for it.
+//
+// **Only a not-planned close is swept.** A merged issue's lane is ended by the merge path, where a
+// detached ship may still be running its tail; an issue closed as completed by hand is left to
+// `lane:prune` and `run:merge`, which books it withdrawn when no merged pull request closed it
+// (joshuafolkken/kit#4916). An issue that could not be read is
+// asked again on the next pass, and a lane whose withdrawal is already on the event stream is not
+// withdrawn twice.
+//
+// **A branch with commits on no remote is kept**: the close deletes the branch and the stash keeps only
+// uncommitted work, so a person decides with `lane:withdraw` by hand. `run:merge` withdraws through the
+// same guard (`withdraw_lane`).
+
+const SWEEP_REASON = 'its issue was closed as not planned while the lane was still open'
+
+function is_not_planned(read: ClosedIssue | undefined): boolean {
+	return read !== undefined && read.is_not_planned && !read.is_merged
+}
+
+/** The open lanes whose issue is closed as not planned. */
+async function closed_lanes(): Promise<Array<LaneInfo>> {
+	const listed = await lane_registry.list_lanes()
+	const lanes = listed.filter((lane) => !lane.is_stranded)
+	const { closed } = await run_board_closed.read_all(lanes.map((lane) => Number(lane.issue)))
+
+	return lanes.filter((lane) => is_not_planned(closed.get(Number(lane.issue))))
+}
+
+// An unreadable count keeps the branch, as unpushed commits would.
+async function has_unpushed(branch: string): Promise<boolean> {
+	try {
+		return (await git_command.commit_count_unpushed(branch)) > 0
+	} catch (error) {
+		error_text.trace_swallowed('lane_withdraw_closed.has_unpushed', error)
+
+		return true
+	}
+}
+
+function kept_note(issue: string, by: Withdrawer): string {
+	const settled = by === 'yield' ? 'gave its lane back' : 'is closed without a merge'
+
+	return `${session_cite.issue(issue)} ${settled}, but its branch has commits on no remote, so its lane is kept — run \`pnpm josh lane:withdraw ${issue}\` by hand.`
+}
+
+interface UnattendedWithdrawal {
+	note: string
+	// The withdrawal could not read the issue, so nothing was stopped or closed.
+	is_retry: boolean
+}
+
+/** Withdraw a closed issue's open lane with no person present, keeping a branch with unpushed commits. */
+async function withdraw_lane(
+	lane: LaneInfo,
+	reason: string,
+	by: Withdrawer,
+): Promise<UnattendedWithdrawal> {
+	if (await has_unpushed(lane.branch)) return { note: kept_note(lane.issue, by), is_retry: false }
+	const outcome = await lane_withdraw.withdraw(lane.issue, reason, by)
+
+	return {
+		note: lane_withdraw.describe(outcome, lane.issue),
+		is_retry: outcome.kind === 'unreadable',
+	}
+}
+
+async function sweep_lane(
+	lane: LaneInfo,
+	events: ReadonlyArray<RunEvent>,
+): Promise<string | undefined> {
+	if (run_event_scope.is_withdrawn(events, lane.issue)) return undefined
+	const { note } = await withdraw_lane(lane, SWEEP_REASON, 'supervisor')
+
+	return note
+}
+
+// One lane's failure does not stop the sweep: the rest are still withdrawn, and this one is asked again.
+async function try_sweep_lane(
+	lane: LaneInfo,
+	events: ReadonlyArray<RunEvent>,
+): Promise<string | undefined> {
+	try {
+		return await sweep_lane(lane, events)
+	} catch (error) {
+		error_text.trace_swallowed('lane_withdraw_closed.sweep_lane', error)
+
+		return `${session_cite.issue(lane.issue)} could not be withdrawn (${error_text.message_of(error)}); the next pass tries again.`
+	}
+}
+
+/** Withdraw every open lane whose issue is closed as not planned — the supervisor's pass; one note each. */
+async function withdraw_closed(): Promise<Array<string>> {
+	const lanes = await closed_lanes()
+	const events = await run_event_stream_emit.current_events()
+	const notes: Array<string> = []
+
+	// Sequential, as `lane_close.close_each` is: two worktree removals at once contend for git's
+	// registration directory.
+	for (const lane of lanes) {
+		// eslint-disable-next-line no-await-in-loop -- worktree writes contend for the same registration directory
+		const note = await try_sweep_lane(lane, events)
+
+		if (note !== undefined) notes.push(note)
+	}
+
+	return notes
+}
+
+const lane_withdraw_closed = { SWEEP_REASON, withdraw_closed, withdraw_lane }
+
+export { lane_withdraw_closed }

package/scripts/lane/lane-withdraw.ts

@@ -12,6 +12,7 @@ import { lane_reap } from './lane-reap'
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_residents } from './lane-residents'
 import { lane_state } from './lane-state'
+import { lane_yield } from './lane-yield'
 
 // `josh lane:withdraw <N> --reason <text>` — a person takes a running lane child's issue out of the
 // current run: the child is stopped, its work stashed and the lane closed. **The Issue stays open** —
@@ -25,9 +26,15 @@ import { lane_state } from './lane-state'
 //
 // A tree that could not be stashed is left in place: closing the lane would delete the work, and the
 // person decides what to keep.
+//
+// **An issue closed on GitHub while its lane stayed open is withdrawn the same way**
+// (joshuafolkken/kit#4915): its child would otherwise keep working, be resumed by the next cut and
+// hold a lane. `lane-withdraw-closed.ts` sweeps those lanes each supervisor pass, and the event, the
+// stash note and the issue comment name the supervisor rather than a person. `run:merge` withdraws a
+// returned child whose issue closed without a merge the same way, named as itself
+// (`run-merge-withdrawn.ts`, joshuafolkken/kit#4916).
 
 const WITHDRAW_OCCASION = 'lane withdraw'
-const WITHDRAW_CAUSE = 'a person withdrew it with `lane:withdraw`'
 const CLOSED_STATE = 'CLOSED'
 const CLOSED_KIND = 'closed'
 const NO_LANE_KIND = 'no-lane'
@@ -35,13 +42,63 @@ const UNREADABLE_KIND = 'unreadable'
 
 type Unsaved = Extract<KeptWork, { kind: 'unsaved' }>
 
+// Who withdrew the lane: a person with `lane:withdraw`, the supervisor's sweep of closed issues,
+// `run:merge` collecting a child whose issue closed without a merge (joshuafolkken/kit#4916), or the
+// child's own `lane:plan` giving its lane back (`lane-yield.ts`, joshuafolkken/kit#4926).
+type Withdrawer = 'person' | 'supervisor' | 'merge' | 'yield'
+
+const OPEN_TAIL =
+	'Its lane child was stopped and the lane closed. The Issue stays open: this run does not resume it, and the next run offers it again.'
+// What `describe` says of an open issue's place in the run once its lane is withdrawn.
+const STAYS_OPEN = 'The Issue stays open: this run does not offer it again, the next run does.'
+
+// How each withdrawer is named on the event stream, in the stash note and on the issue.
+const WITHDRAWER_TEXT = {
+	person: {
+		name: 'a person',
+		cause: 'a person withdrew it with `lane:withdraw`',
+		closed_head:
+			'Its lane was withdrawn with `pnpm josh lane:withdraw` after the Issue was closed.',
+		open_head: 'Withdrawn from the current run by a person with `pnpm josh lane:withdraw`.',
+		open_tail: OPEN_TAIL,
+		stays: STAYS_OPEN,
+	},
+	supervisor: {
+		name: 'the run:wake supervisor',
+		cause: 'the `run:wake` supervisor withdrew it after its issue was closed',
+		closed_head: 'Its lane was withdrawn by the `run:wake` supervisor after the Issue was closed.',
+		open_head: 'Withdrawn from the current run by the `run:wake` supervisor.',
+		open_tail: OPEN_TAIL,
+		stays: STAYS_OPEN,
+	},
+	merge: {
+		name: 'the run:merge driver',
+		cause: '`run:merge` withdrew it after its issue was closed without a merge',
+		closed_head:
+			'Its lane was withdrawn by `pnpm josh run:merge` after the Issue was closed without a merge.',
+		open_head: 'Withdrawn from the current run by `pnpm josh run:merge`.',
+		open_tail: OPEN_TAIL,
+		stays: STAYS_OPEN,
+	},
+	yield: lane_yield.YIELD_TEXT,
+} as const satisfies Record<Withdrawer, Record<string, string>>
+
+interface Withdrawal {
+	reason: string
+	by: Withdrawer
+	is_closed: boolean
+}
+
 interface Withdrawn {
 	kind: 'withdrawn'
+	by: Withdrawer
 	// How many of the child's processes the withdrawal stopped — 0 for a child that had already ended.
 	reaped: number
 	stash: string | undefined
-	// Whether the comment saying the issue stays open reached it.
+	// Whether the comment saying so reached the issue.
 	is_noted: boolean
+	// The issue was already closed — withdrawn or finished on GitHub while its lane stayed open.
+	is_closed: boolean
 	lane: CloseKind
 	// What else the close ended from the checkout; `undefined` where it could not be read.
 	residents: ReadonlyArray<number> | undefined
@@ -51,51 +108,54 @@ type Refused =
 	{ kind: typeof CLOSED_KIND } | { kind: typeof NO_LANE_KIND } | { kind: typeof UNREADABLE_KIND }
 type WithdrawOutcome = Withdrawn | Unsaved | Refused
 
-function withdraw_comment(reason: string): string {
-	return [
-		'Withdrawn from the current run by a person with `pnpm josh lane:withdraw`.',
-		'Its lane child was stopped and the lane closed. The Issue stays open: this run does not resume it, and the next run offers it again.',
-		`- Why: ${reason}`,
-	].join('\n')
+function withdraw_comment({ reason, by, is_closed }: Withdrawal): string {
+	const head = is_closed ? WITHDRAWER_TEXT[by].closed_head : WITHDRAWER_TEXT[by].open_head
+	const tail = is_closed
+		? 'Its lane child was stopped and the lane closed, so it no longer holds a lane and is not resumed.'
+		: WITHDRAWER_TEXT[by].open_tail
+
+	return [head, tail, `- Why: ${reason}`].join('\n')
 }
 
-async function record_withdraw(issue: string, reason: string): Promise<void> {
+async function record_withdraw(issue: string, { reason, by }: Withdrawal): Promise<void> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.WITHDRAW,
-		`${issue_cite.plain(issue)} withdrawn by a person: ${reason}`,
+		`${issue_cite.plain(issue)} withdrawn by ${WITHDRAWER_TEXT[by].name}: ${reason}`,
 	)
 }
 
-// A closed issue has nothing to withdraw, and an unread one might be: neither writes anything.
-async function refusal_of(issue: string): Promise<Refused | undefined> {
+// Whether the issue is closed, or `undefined` when it could not be read — an unread issue writes nothing.
+async function read_is_closed(issue: string): Promise<boolean | undefined> {
 	const read = await issue_state_cli.read_issue(issue)
 
-	if (read.kind !== 'state') return { kind: UNREADABLE_KIND }
-	if (read.state.state.toUpperCase() === CLOSED_STATE) return { kind: CLOSED_KIND }
+	if (read.kind !== 'state') return undefined
 
-	return undefined
+	return read.state.state.toUpperCase() === CLOSED_STATE
 }
 
 async function note_issue(
 	issue: string,
-	reason: string,
+	withdrawal: Withdrawal,
 	stash: string | undefined,
 ): Promise<boolean> {
-	const is_noted = await git_gh_issue_write.issue_try_comment(issue, withdraw_comment(reason))
+	const is_noted = await git_gh_issue_write.issue_try_comment(issue, withdraw_comment(withdrawal))
+
+	if (stash !== undefined) {
+		await lane_preserve.announce(issue, stash, WITHDRAWER_TEXT[withdrawal.by].cause)
+	}
 
-	if (stash !== undefined) await lane_preserve.announce(issue, stash, WITHDRAW_CAUSE)
 	await run_label.unmark(issue)
 
 	return is_noted
 }
 
-async function stop_and_close(lane: LaneInfo, reason: string): Promise<WithdrawOutcome> {
-	await record_withdraw(lane.issue, reason)
+async function stop_and_close(lane: LaneInfo, withdrawal: Withdrawal): Promise<WithdrawOutcome> {
+	await record_withdraw(lane.issue, withdrawal)
 	const reaped = lane_reap.reap_child(lane).length
 	const saved = await lane_preserve.keep_work(lane.issue, lane.directory, WITHDRAW_OCCASION)
 
 	if (saved.kind === 'unsaved') return saved
-	const is_noted = await note_issue(lane.issue, reason, saved.stash)
+	const is_noted = await note_issue(lane.issue, withdrawal, saved.stash)
 	const closed = await lane_close.close_lane(lane.issue)
 
 	// After the close, so the record names the withdrawal rather than the close it ran. An `incomplete`
@@ -106,25 +166,34 @@ async function stop_and_close(lane: LaneInfo, reason: string): Promise<WithdrawO
 
 	return {
 		kind: 'withdrawn',
+		by: withdrawal.by,
 		reaped,
 		stash: saved.stash,
 		is_noted,
+		is_closed: withdrawal.is_closed,
 		lane: closed.kind,
 		residents: closed.residents,
 	}
 }
 
-/** Stop `#<N>`'s lane child, stash its work and close the lane, leaving the Issue open. */
-async function withdraw(issue: string, reason: string): Promise<WithdrawOutcome> {
+/**
+ * Stop `#<N>`'s lane child, stash its work and close the lane, leaving the Issue as it is. A closed
+ * issue is refused only when no lane is left for it (joshuafolkken/kit#4915).
+ */
+async function withdraw(
+	issue: string,
+	reason: string,
+	by: Withdrawer = 'person',
+): Promise<WithdrawOutcome> {
 	issue_number_shape.require_issue_number(issue)
-	const refusal = await refusal_of(issue)
+	const is_closed = await read_is_closed(issue)
 
-	if (refusal !== undefined) return refusal
+	if (is_closed === undefined) return { kind: UNREADABLE_KIND }
 	const lane = await lane_registry.find_open_lane(issue)
 
-	if (lane === undefined) return { kind: NO_LANE_KIND }
+	if (lane === undefined) return { kind: is_closed ? CLOSED_KIND : NO_LANE_KIND }
 
-	return await stop_and_close(lane, reason)
+	return await stop_and_close(lane, { reason, by, is_closed })
 }
 
 function stash_sentence(stash: string | undefined): string {
@@ -147,8 +216,11 @@ function withdrawn_text(outcome: Withdrawn, issue: string): string {
 	const head = `Withdrew ${cited}. ${stopped} ${stash_sentence(outcome.stash)}`
 	const lane = lane_suffix(outcome, cited)
 	const noted = outcome.is_noted ? '' : ' The comment saying so could not be posted.'
+	const issue_sentence = outcome.is_closed
+		? 'The Issue was already closed, so its lane no longer holds a place.'
+		: WITHDRAWER_TEXT[outcome.by].stays
 
-	return `${head} The Issue stays open: this run does not offer it again, the next run does.${noted}${lane}`
+	return `${head} ${issue_sentence}${noted}${lane}`
 }
 
 function unsaved_text(outcome: Unsaved, issue: string): string {
@@ -159,7 +231,7 @@ function refused_text(outcome: Refused, issue: string): string {
 	const cited = session_cite.issue(issue)
 
 	if (outcome.kind === CLOSED_KIND) {
-		return `${cited} is already closed, so there is nothing to withdraw.`
+		return `${cited} is already closed and no lane is open for it, so there is nothing to withdraw.`
 	}
 
 	if (outcome.kind === NO_LANE_KIND) {
@@ -177,7 +249,12 @@ function describe(outcome: WithdrawOutcome, issue: string): string {
 		: refused_text(outcome, issue)
 }
 
-const lane_withdraw = { describe, withdraw }
+// How every withdrawer is named in the `withdraw` event — the board reads the reason after it.
+const WITHDRAWER_NAMES: ReadonlyArray<string> = Object.values(WITHDRAWER_TEXT).map(
+	(text) => text.name,
+)
+
+const lane_withdraw = { WITHDRAWER_NAMES, describe, withdraw }
 
-export type { WithdrawOutcome }
+export type { Withdrawer, WithdrawOutcome }
 export { lane_withdraw }

package/scripts/lane/lane-yield.ts

@@ -0,0 +1,85 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+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'
+
+// A lane child that gives its lane back (joshuafolkken/kit#4926): `lane:plan` found a running lane that
+// planned one of its files first, so instead of polling for the holder to end while its seat stays taken,
+// it notes its yield on the stream and ends. `run:merge` books it `yielded` — neither a merge, a failure
+// nor an outage — and closes the lane through `lane:withdraw`'s path, named as this withdrawer.
+//
+// **The yield is a `note`, not a `withdraw`**: a `withdraw` event says the lane is already closed, and
+// the readers of the stream (`backlog-drive-restore.ts`, the `run:wake` sweep, `run:tidy`) act on that.
+// The yielding child cannot close its own lane, so its issue stays in flight until `run:merge` does.
+//
+// **Unlike a person's withdrawal, a yield does not take the issue out of the run.** Its plan outlives the
+// lane (`lane-plan.ts` → `release`), so `backlog:next` holds it back on that plan while the holder runs
+// and offers it again once the holder's lane ends; `backlog-drive-restore.ts` reads `is_yield` to leave
+// the closing withdrawal out of the withdrawn and the settled issues.
+
+// The reason `run:merge` closes a yielded lane with.
+const YIELD_REASON = 'it gave its lane back to an earlier lane holding one of its planned files'
+
+const YIELD_MARK = ' yielded its lane: '
+
+const YIELD_TEXT = {
+	name: 'its own lane:plan',
+	cause: '`lane:plan` gave its lane back to an earlier lane holding one of its planned files',
+	closed_head: 'Its lane was given back by `pnpm josh lane:plan` after the Issue was closed.',
+	open_head:
+		'Gave its lane back: `pnpm josh lane:plan` found an earlier lane holding one of its planned files.',
+	open_tail:
+		'The lane closed before any implementation edit. The Issue stays in the run: it is offered again once the holding lane ends, keeping its place in line.',
+	stays: 'The Issue stays in the run: it is offered again once the holding lane ends.',
+} as const
+
+// Where in the lane the yield fell, one word on the note, kept for a later count of how many the entry
+// probe caught before the investigation (joshuafolkken/kit#5211): `entry` from `run:entry`, `summary` from the
+// `lane:plan` a child runs once its work summary is set.
+type YieldAt = 'entry' | 'summary'
+
+const YIELD_AT_MARK = ' · at: '
+
+async function record_yield(issue: number, reason: string, at: YieldAt): Promise<void> {
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.NOTE,
+		`${issue_cite.plain(String(issue))}${YIELD_MARK}${reason}${YIELD_AT_MARK}${at}`,
+	)
+}
+
+function is_yield_note(event: RunEvent): boolean {
+	return event.kind === run_event_stream.EVENT_KIND.NOTE && event.text.includes(YIELD_MARK)
+}
+
+// Whether `event` is the withdrawal `run:merge` closed a yielded lane with, rather than one that takes
+// the issue out of the run.
+function is_yield(event: RunEvent): boolean {
+	return (
+		event.kind === run_event_stream.EVENT_KIND.WITHDRAW &&
+		event.text.includes(` withdrawn by ${YIELD_TEXT.name}:`)
+	)
+}
+
+// An event that decides whether the issue's newest launch yielded: the launch, the yield, or a
+// withdrawal that is not the yield's own close.
+function is_deciding(event: RunEvent, issue: string): boolean {
+	if (run_event_scope.issue_named(event) !== issue) return false
+	if (event.kind === run_event_stream.EVENT_KIND.CHILD_LAUNCH) return true
+
+	return (
+		is_yield_note(event) ||
+		(event.kind === run_event_stream.EVENT_KIND.WITHDRAW && !is_yield(event))
+	)
+}
+
+// Whether the issue's newest launch gave its lane back, and no one withdrew it since.
+function is_yielded(events: ReadonlyArray<RunEvent>, issue: string): boolean {
+	const newest = events.findLast((event) => is_deciding(event, issue))
+
+	return newest !== undefined && is_yield_note(newest)
+}
+
+const lane_yield = { YIELD_REASON, YIELD_TEXT, is_yield, is_yielded, record_yield }
+
+export { lane_yield }
+export type { YieldAt }

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

@@ -1,4 +1,4 @@
-import { setTimeout as sleep } from 'node:timers/promises'
+import { poll } from '#scripts/lib/poll'
 import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
 import { run_ship_probe } from '#scripts/run/ship/run-ship-probe'
 
@@ -12,19 +12,20 @@ async function current(issue: string): Promise<ShipReading | undefined> {
 	return repository === undefined ? undefined : run_ship_detach.read_result(repository, issue)
 }
 
+// The ship's ending once it leaves `running`, and `abnormal` once its result is gone.
+async function settled(issue: string): Promise<Exclude<ShipEnding, 'none'> | undefined> {
+	const read = await current(issue)
+	if (read === undefined) return 'abnormal'
+
+	return read.result === 'running' ? undefined : read.result
+}
+
 async function wait_for_ship(issue: string, prior_launch: string | undefined): Promise<ShipEnding> {
-	let read = await current(issue)
+	const read = await current(issue)
 	if (read === undefined || read.launch_id === prior_launch) return 'none'
+	if (read.result !== 'running') return read.result
 
-	while (read.result === 'running') {
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await sleep(POLL_MS)
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		read = await current(issue)
-		if (read === undefined) return 'abnormal'
-	}
-
-	return read.result
+	return await poll.wait_for(async () => await settled(issue), { interval_ms: POLL_MS })
 }
 
 const openai_lane_ship = { current, wait_for_ship }

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

@@ -1,5 +1,6 @@
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
+import { poll } from '#scripts/lib/poll'
 import { z } from 'zod'
 
 const DECISION_PREFIX = 'josh-openai-lane-supervisor-decision-'
@@ -40,15 +41,12 @@ function cancel(lane_directory: string, nonce: string): boolean {
 }
 
 async function is_approved(lane_directory: string, nonce: string): Promise<boolean> {
-	for (let attempt = 0; attempt < APPROVAL_POLL_LIMIT; attempt += 1) {
-		const decision = read(lane_directory, nonce)?.decision
-		if (decision !== undefined) return decision === 'approved'
+	const decision = await poll.poll_for(() => read(lane_directory, nonce)?.decision, {
+		attempts: APPROVAL_POLL_LIMIT,
+		interval_ms: APPROVAL_POLL_MS,
+	})
 
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await new Promise((resolve) => setTimeout(resolve, APPROVAL_POLL_MS))
-	}
-
-	return false
+	return decision === 'approved'
 }
 
 function remove(lane_directory: string, nonce: string): void {

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

@@ -4,6 +4,7 @@ import { process_identity } from '#scripts/josh/process-identity'
 import { process_owner_schema } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
+import { poll } from '#scripts/lib/poll'
 import { z } from 'zod'
 import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
 
@@ -66,14 +67,10 @@ function active(lane_directory: string): SupervisorOwner | undefined {
 }
 
 async function wait_for_active(lane_directory: string): Promise<SupervisorOwner | undefined> {
-	for (let attempt = 0; attempt < CLAIM_POLL_LIMIT; attempt += 1) {
-		const owner = active(lane_directory)
-		if (owner !== undefined) return owner
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await new Promise((resolve) => setTimeout(resolve, CLAIM_POLL_MS))
-	}
-
-	return undefined
+	return await poll.poll_for(() => active(lane_directory), {
+		attempts: CLAIM_POLL_LIMIT,
+		interval_ms: CLAIM_POLL_MS,
+	})
 }
 
 // The hard link snapshots the exact owner inode. Several contenders may snapshot one stale owner,

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

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { agent_argv } from '#scripts/agent/agent-argv'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 import { process_identity } from '#scripts/josh/process-identity'
+import { poll } from '#scripts/lib/poll'
 import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
 import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 import { lane_child_invocation } from './lane-child-invocation'
@@ -142,10 +143,10 @@ async function wait_for_inherited_child(
 	child_pid: number,
 	child_process_start: string | undefined,
 ): Promise<void> {
-	while (process_identity.is_same_process(child_pid, child_process_start) !== false) {
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await new Promise((resolve) => setTimeout(resolve, CHILD_POLL_MS))
-	}
+	await poll.wait_for(
+		() => process_identity.is_same_process(child_pid, child_process_start) === false || undefined,
+		{ interval_ms: CHILD_POLL_MS },
+	)
 }
 
 async function recovered_resume(lane: LaneInfo, nonce: string): Promise<boolean | undefined> {

package/scripts/lib/poll.ts

@@ -1,4 +1,4 @@
-// One bounded polling loop and one sleep, in one place.
+// One polling loop — bounded by attempts, or ended only by its read — and one sleep, in one place.
 //
 // **Three modules had already written the same three-line `sleep`** — `gh/git-pr-checks.ts`,
 // `eval/eval-run.ts` and `propagate/propagate-publish.ts` — and the release command's tag watch
@@ -24,9 +24,6 @@ interface PollOptions {
 	sleeper?: (duration_ms: number) => Promise<void>
 }
 
-// **True as soon as `is_done` answers true, false when the attempts run out.** The first attempt runs
-// before any wait, so a condition already met costs nothing — which is the common case for a tag that
-// was created while the command was doing something else.
 // **The wait goes between attempts, never after the last one**, so the budget a caller computes from
 // `attempts × interval_ms` is the budget it actually spends. The pre-existing merge-gate loop in
 // `git-pr-checks.ts` guards its sleep the same way; extracted here so the loop keeps one branch.
@@ -39,21 +36,53 @@ async function wait_between(
 	if (attempt < attempts - 1) await wait(interval_ms)
 }
 
-async function poll_until(is_done: () => Promise<boolean>, options: PollOptions): Promise<boolean> {
+type WaitOptions = Omit<PollOptions, 'attempts'>
+
+// **The first value `read` answers, `undefined` when the attempts run out.** `undefined` is "not yet",
+// so a read that reaches a verdict — success or failure — answers it and the loop ends there.
+async function poll_for<T>(
+	read: () => Promise<T | undefined> | T | undefined,
+	options: PollOptions,
+): Promise<T | undefined> {
 	const wait = options.sleeper ?? sleep
 
 	for (let attempt = 0; attempt < options.attempts; attempt += 1) {
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		if (await is_done()) return true
+		const value = await read()
+		if (value !== undefined) return value
 
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await wait_between(wait, options.interval_ms, attempt, options.attempts)
 	}
 
-	return false
+	return undefined
+}
+
+// **True as soon as `is_done` answers true, false when the attempts run out.** The first attempt runs
+// before any wait, so a condition already met costs nothing — which is the common case for a tag that
+// was created while the command was doing something else.
+async function poll_until(
+	is_done: () => Promise<boolean> | boolean,
+	options: PollOptions,
+): Promise<boolean> {
+	const is_reached = await poll_for(async () => ((await is_done()) ? true : undefined), options)
+
+	return is_reached === true
+}
+
+// **A wait that ends only when `read` answers** — a child process exiting, a ship leaving `running`.
+// Its bound, if any, is the read's own: a wall-clock deadline the read answers with its failure.
+async function wait_for<T>(
+	read: () => Promise<T | undefined> | T | undefined,
+	options: WaitOptions,
+): Promise<T> {
+	const value = await poll_for(read, { ...options, attempts: Infinity })
+	if (value === undefined) throw new Error('an unbounded poll ran out of attempts')
+
+	return value
 }
 
-const poll = { poll_until, sleep }
+const poll = { poll_for, poll_until, sleep, wait_for }
 
 export { poll }
-export type { PollOptions }
+export type { PollOptions, WaitOptions }

package/scripts/lib/settled-together.ts

@@ -0,0 +1,10 @@
+// Both steps run to their end before either's failure is thrown, so neither is left half-done behind
+// the other's failure. The first step's failure is thrown when both failed.
+async function settled_together(first: Promise<void>, second: Promise<void>): Promise<void> {
+	const [result, other] = await Promise.allSettled([first, second])
+
+	if (result.status === 'rejected') throw result.reason
+	if (other.status === 'rejected') throw other.reason
+}
+
+export { settled_together }