@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lane/lane-withdraw.ts

@@ -10,25 +10,31 @@ import { lane_close, type CloseKind } from './lane-close'
 import { lane_preserve, type KeptWork } from './lane-preserve'
 import { lane_reap } from './lane-reap'
 import { lane_registry, type LaneInfo } from './lane-registry'
-
-// `josh lane:withdraw <N> --reason <text>` — a person takes a running lane child's issue out of the run
-// for good: the child is stopped, its work stashed, the Issue closed as not planned and the lane closed.
+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** —
+// a withdrawal ends this run's attempt, not the work — so a later run offers it again; this run does
+// not (`backlog-drive-restore.ts` → `offer_exclude`, and the drive's own exclusion).
 //
 // **The `withdraw` event is written first, before anything is stopped.** Killing the child alone would
 // let `lane:await` book it stopped and `run:merge` classify it from GitHub — an open issue resumed as an
-// `outage` or parked `needs-decision`. `run:merge` reads the event stream before GitHub, so a child whose
-// newest launch-or-withdraw event is a withdraw is booked `withdrawn` whatever the Issue's state reads
-// at that moment, and the race between the kill and the close cannot book it as anything else.
+// `outage` or parked `run:stalled`. `run:merge` reads the event stream before GitHub, so a child whose
+// newest launch-or-withdraw event is a withdraw is booked `withdrawn` whatever the Issue's state reads.
 //
-// **The issue is read again once the child is stopped.** It may merge between the first read and the
-// reap; the reap stopped it, so the second read is final, and an issue it already closed keeps
-// GitHub's close — `run:merge` books a merged close as merged whatever the event stream says.
+// 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.
 //
-// A tree that could not be stashed is left in place with the Issue open: 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'
@@ -36,99 +42,158 @@ 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 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
-	// The issue had closed on its own — merged — before the withdrawal reached it, so it was left as is.
-	had_closed: boolean
 	lane: CloseKind
+	// What else the close ended from the checkout; `undefined` where it could not be read.
+	residents: ReadonlyArray<number> | undefined
 }
 
-type IssueSettled = Pick<Withdrawn, 'had_closed' | 'is_closed'>
-
 type Refused =
 	{ kind: typeof CLOSED_KIND } | { kind: typeof NO_LANE_KIND } | { kind: typeof UNREADABLE_KIND }
 type WithdrawOutcome = Withdrawn | Unsaved | Refused
 
-function close_comment(reason: string): string {
-	return [
-		'Withdrawn by a person with `pnpm josh lane:withdraw`.',
-		'Its lane child was stopped and the lane closed.',
-		`- 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 }
-
-	return undefined
-}
-
-async function close_open_issue(issue: string, reason: string): Promise<IssueSettled> {
-	const refusal = await refusal_of(issue)
+	if (read.kind !== 'state') return undefined
 
-	// An unread issue may have merged during the reap, so it is left open for a person to close.
-	if (refusal !== undefined) {
-		const is_closed = refusal.kind === CLOSED_KIND
-
-		return { is_closed, had_closed: is_closed }
-	}
-
-	const is_closed = await git_gh_issue_write.issue_close_not_planned(issue, close_comment(reason))
-
-	return { is_closed, had_closed: false }
+	return read.state.state.toUpperCase() === CLOSED_STATE
 }
 
-async function close_issue(
+async function note_issue(
 	issue: string,
-	reason: string,
+	withdrawal: Withdrawal,
 	stash: string | undefined,
-): Promise<IssueSettled> {
-	const settled = await close_open_issue(issue, reason)
+): Promise<boolean> {
+	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 settled
+	return is_noted
 }
 
-async function stop_and_close(lane: LaneInfo, reason: string): Promise<WithdrawOutcome> {
-	await record_withdraw(lane.issue, reason)
-	const reaped = lane_reap.reap_child(lane.issue).length
+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 settled = await close_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)
 
-	return { kind: 'withdrawn', reaped, stash: saved.stash, ...settled, lane: closed.kind }
+	// After the close, so the record names the withdrawal rather than the close it ran. An `incomplete`
+	// close is not `ended`: the supervisor closes the lane again until its last process is gone.
+	if (closed.kind !== 'incomplete') {
+		await lane_state.record_change({ issue: lane.issue, state: 'ended', command: 'lane:withdraw' })
+	}
+
+	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, close the Issue as not planned and close the lane. */
-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 {
@@ -137,28 +202,36 @@ function stash_sentence(stash: string | undefined): string {
 	return `Its uncommitted work was stashed — recover with \`pnpm josh stash:pop "${stash}"\`.`
 }
 
+// What the lane's close left or ended, as a suffix.
+function lane_suffix(outcome: Withdrawn, cited: string): string {
+	const removed = outcome.lane === 'incomplete' ? ' The lane could not be fully removed.' : ''
+	const residents = lane_residents.residents_sentence(outcome.residents, cited)
+
+	return residents === undefined ? removed : `${removed} ${residents}`
+}
+
 function withdrawn_text(outcome: Withdrawn, issue: string): string {
 	const cited = session_cite.issue(issue)
 	const stopped = outcome.reaped === 0 ? 'Its child had already ended.' : 'Stopped its child.'
 	const head = `Withdrew ${cited}. ${stopped} ${stash_sentence(outcome.stash)}`
-	const lane = outcome.lane === 'incomplete' ? ' The lane could not be fully removed.' : ''
+	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
 
-	if (outcome.had_closed) return `${head} The Issue had already closed and was left as is.${lane}`
-
-	if (outcome.is_closed) return `${head} The Issue is closed as not planned.${lane}`
-
-	return `${head} The Issue could not be closed — close ${cited} by hand; \`run:merge\` books it withdrawn either way.${lane}`
+	return `${head} ${issue_sentence}${noted}${lane}`
 }
 
 function unsaved_text(outcome: Unsaved, issue: string): string {
-	return `The child for ${session_cite.issue(issue)} was stopped, but its uncommitted work could not be stashed (${outcome.reason}), so the Issue is left open and the lane at ${outcome.directory}; \`run:merge\` books it withdrawn.`
+	return `The child for ${session_cite.issue(issue)} was stopped, but its uncommitted work could not be stashed (${outcome.reason}), so the lane is left at ${outcome.directory}; \`run:merge\` books it withdrawn.`
 }
 
 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) {
@@ -176,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/lane/process-directories.ts

@@ -0,0 +1,70 @@
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { lane_paths } from './lane-paths'
+
+// Each process's working directory, read with `lsof` — the one place its output is parsed.
+//
+// **A process belongs to a lane by its working directory first, its ancestry only after.** A process
+// detached from a lane (`josh ship --detach`, a diagnostic started under `script`) is re-parented to
+// pid 1, so no parent chain reaches it, while its working directory still sits under `.kit-lanes/<N>`.
+// `run:board` draws such a process as a lane's or a leftover, and `lane:close` ends it
+// (joshuafolkken/kit#4304); the board falls back to the ancestry where the directory names no lane
+// (`run-board-usage-lanes.ts`).
+// **macOS alone**, as the board reads it: elsewhere nothing is listed.
+
+const LSOF_COMMAND = 'lsof'
+// `-a` joins the conditions: the `cwd` descriptor only, in `-F` fields. The board appends `-p <pids>`.
+const CWD_ARGUMENTS = ['-a', '-d', 'cwd', '-Fn']
+// `lsof -F`'s field lines: `p<pid>` opens a process, `n<path>` names its directory.
+const LSOF_PROCESS = /^(?=p)/mu
+const LSOF_NAME = 'n'
+const LISTING_PLATFORMS: ReadonlySet<NodeJS.Platform> = new Set(['darwin'])
+
+function lsof_block(block: string): [number, string] | undefined {
+	const [process_line = '', ...rest] = block.trim().split('\n')
+	const name = rest.find((line) => line.startsWith(LSOF_NAME))
+
+	return name === undefined ? undefined : [Number(process_line.slice(1)), name.slice(1)]
+}
+
+/** Each process's working directory from `lsof -F`'s output. */
+function parse(output: string): Map<number, string> {
+	const blocks = output.split(LSOF_PROCESS).map((block) => lsof_block(block))
+
+	return new Map(blocks.filter((block) => block !== undefined))
+}
+
+/**
+ * Every process's working directory, `undefined` where `lsof` could not be run or timed out — never
+ * read as "nothing there". `lsof` exits non-zero when one process cannot be read and still lists the
+ * rest, so its output is read whatever the exit status.
+ */
+function list_all(platform: NodeJS.Platform = process.platform): Map<number, string> | undefined {
+	if (!LISTING_PLATFORMS.has(platform)) return new Map()
+
+	const result = spawnSync(LSOF_COMMAND, CWD_ARGUMENTS, {
+		encoding: 'utf8',
+		timeout: PROBE_TIMEOUT_MS,
+		stdio: ['ignore', 'pipe', 'ignore'],
+	})
+
+	return result.error === undefined ? parse(result.stdout) : undefined
+}
+
+/**
+ * The lane of `root` a directory sits under — itself or a directory above it, the outermost first.
+ * The one lane-membership reading: the board draws a leftover by it, and the close ends by it
+ * (joshuafolkken/kit#4300).
+ */
+function lane_of(directory: string, root: string): string | undefined {
+	const parts = directory.split(path.sep)
+	const ancestors = parts.map((_, index) => parts.slice(0, index + 1).join(path.sep)).slice(1)
+	const environment = { [lane_paths.LANE_ROOT_KEY]: root }
+
+	return ancestors.map((ancestor) => lane_paths.lane_issue_of(ancestor, environment)).find(Boolean)
+}
+
+const process_directories = { CWD_ARGUMENTS, lane_of, list_all, parse }
+
+export { process_directories }